diff --git a/README.md b/README.md new file mode 100644 index 0000000..f176c75 --- /dev/null +++ b/README.md @@ -0,0 +1,98 @@ +# 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:**
+    * Handles new member, nickname, photo, progress, timeout, and completion events
+    * Generates concise responses for user messages
+    * Falls back to deterministic templates when an LLM response is not needed
+ +**2. Nickname and progress checks:**
+    * Validates community nickname format
+    * Checks onboarding session progress from Redis/Garnet
+    * Looks up room context when MongoDB is configured
+ +**3. Tool-aware LLM runtime:**
+    * Supports planner, responder, critic, and tool-loop execution modes
+    * Routes requests across local, proxy, or OpenRouter-compatible LLM providers
+    * Uses circuit breaking, health checks, and response validation
+ +**4. Evaluation pipeline:**
+    * Captures golden and shadow evaluation cases
+    * Runs rule, LLM, process, attribution, and PRM-style judges
+    * Supports review queues, calibration, drift checks, promotion, and tournaments
+ +**5. Background worker:**
+    * Processes shadow evaluation jobs asynchronously
+    * Archives evaluation results and publishes alerts
+    * Keeps real-time responses separate from slower analysis work
+ +## Used technologies + +    * TypeScript
+    * Node.js
+    * NATS
+    * Redis / Garnet
+    * MongoDB / Mongoose
+    * OpenTelemetry
+    * Pino
+    * Zod
+    * Vitest
+    * ESLint
+    * Prettier
+ +## 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`).