Files
lolympus-agent/README.md
T
2026-05-14 14:58:29 -07:00

99 lines
3.0 KiB
Markdown

# lolympus-agent
## Overview
lolympus-agent is an LLM-based onboarding agent for the lolympus gaming community.
It receives onboarding events, checks the user's current state, and replies with a
short helpful message through the community's backend messaging pipeline.
## Purpose
I created this service to automate repetitive onboarding guidance while keeping
the response quality close to a human community staff member. The agent can answer
common questions, validate onboarding progress, and route more complex cases
through LLM-powered reasoning and tool calls.
## Functionalities
**1. Onboarding responses:** <br />
&nbsp; &nbsp; * Handles new member, nickname, photo, progress, timeout, and completion events <br />
&nbsp; &nbsp; * Generates concise responses for user messages <br />
&nbsp; &nbsp; * Falls back to deterministic templates when an LLM response is not needed <br />
**2. Nickname and progress checks:** <br />
&nbsp; &nbsp; * Validates community nickname format <br />
&nbsp; &nbsp; * Checks onboarding session progress from Redis/Garnet <br />
&nbsp; &nbsp; * Looks up room context when MongoDB is configured <br />
**3. Tool-aware LLM runtime:** <br />
&nbsp; &nbsp; * Supports planner, responder, critic, and tool-loop execution modes <br />
&nbsp; &nbsp; * Routes requests across local, proxy, or OpenRouter-compatible LLM providers <br />
&nbsp; &nbsp; * Uses circuit breaking, health checks, and response validation <br />
**4. Evaluation pipeline:** <br />
&nbsp; &nbsp; * Captures golden and shadow evaluation cases <br />
&nbsp; &nbsp; * Runs rule, LLM, process, attribution, and PRM-style judges <br />
&nbsp; &nbsp; * Supports review queues, calibration, drift checks, promotion, and tournaments <br />
**5. Background worker:** <br />
&nbsp; &nbsp; * Processes shadow evaluation jobs asynchronously <br />
&nbsp; &nbsp; * Archives evaluation results and publishes alerts <br />
&nbsp; &nbsp; * Keeps real-time responses separate from slower analysis work <br />
## Used technologies
&nbsp; &nbsp; * TypeScript <br />
&nbsp; &nbsp; * Node.js <br />
&nbsp; &nbsp; * NATS <br />
&nbsp; &nbsp; * Redis / Garnet <br />
&nbsp; &nbsp; * MongoDB / Mongoose <br />
&nbsp; &nbsp; * OpenTelemetry <br />
&nbsp; &nbsp; * Pino <br />
&nbsp; &nbsp; * Zod <br />
&nbsp; &nbsp; * Vitest <br />
&nbsp; &nbsp; * ESLint <br />
&nbsp; &nbsp; * Prettier <br />
## How to run
1. Install dependencies:
```bash
npm install
```
2. Create a local environment file:
```bash
cp env-vars/env.example env-vars/dev.env
```
3. Fill in the required NATS, Redis/Garnet, MongoDB, and LLM provider values in
`env-vars/dev.env`.
4. Run checks:
```bash
npm run typecheck
npm test
```
5. Start the agent:
```bash
npm run start:dev
```
## Useful commands
```bash
npm run build
npm run lint
npm run eval
npm run eval:report
npm run eval:review
```
The service is designed to run as two processes in production: the real-time
agent (`src/main.ts`) and the background worker (`src/workers/background.ts`).