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