Getting Started¶

Kourai Khryseai works as a real-time conversation with ten AI specialists. You describe what you need, they ask clarifying questions, show their work as they build it, and iterate based on your feedback. Three paths to the same system:

• CLI — Fast, scriptable, terminal-based
• GUI — Rich desktop experience with agent portraits, TTS, and visual effects
• VN — Dating-sim inspired visual novel with affinity, romance, and character progression

All three are equally capable and connect to the same Docker-hosted agent backend. Pick whichever fits your workflow.

Prerequisites¶

Installation¶

1. Clone and install¶

git clone https://github.com/ajbarea/kourai_khryseai.git
cd kourai_khryseai

# Install all workspace packages
make setup
# (equivalent to: uv sync --all-packages)

2. Configure environment¶

cp .env.example .env

Edit .env and add your API key:

ANTHROPIC_API_KEY=sk-ant-your-key-here

KOURAI_PROVIDER=local

Starting the Agents¶

make up              # Build images + start full stack (waits for healthy services)
make status          # Show service state/health

Start everything:

docker compose up

All ten agents + Jaeger + Prometheus.

To start a single agent (plus its dependencies):

docker compose up mneme

For just Jaeger trace inspection:

docker compose up jaeger

Your First Request¶

Option 1: CLI¶

make cli

╔══════════════════════════════════════════╗
║     Kourai Khryseai — Golden Maidens     ║
╚══════════════════════════════════════════╝
Type your request. Commands: :q (quit), :status (agent info)

Connecting to Hephaestus at http://localhost:10000/...
Connected to Hephaestus — Orchestrator v0.1.0

❯ implement CSV export with tests

Hephaestus automatically routes your request to the right pipeline. You'll see real-time progress with agent emojis as each step completes.

See the CLI Reference for all commands.

Option 2: Pygame GUI¶

make gui

Opens a full-screen JRPG-styled interface with: - Full-color portraits of each agent with glow effects and crossfade transitions - Dialogue bubbles with real-time streaming responses - Personality-matched voices with neural speech synthesis - Golden particle effects and typewriter text animation - Settings overlay for voice customization and accessibility

See the GUI Reference for keyboard shortcuts, visual effects, and TTS configuration.

Option 3: Ren'Py Visual Novel¶

cd hosts/vn/renpy-8.5.2-sdk
./renpy.sh ../kourai_vn    # Linux/Mac
renpy.exe ..\kourai_vn     # Windows

Opens a Ren'Py visual novel with: - Warm forge aesthetic — gold, cream, charcoal - Affinity HUD — tracks your relationship tier with each agent - Gossip system — idle agents share personality-driven flavor text - Choice events — agents present choices that affect affinity - Full save/load — portrait thumbnails, conversation context, bridge reconnect

See the VN Reference for architecture, screens, and troubleshooting.

Viewing Traces & Metrics¶

Every request creates a distributed trace across all agents and generates performance metrics. Both Jaeger and Prometheus start automatically with make up.

• Jaeger — Trace inspection at localhost:16686. Select any agent from the service dropdown to see its spans, timings, and any errors.
• Prometheus — Metric inspection at localhost:9090. View RED metrics (Rate, Error, Duration) across all services.

Stopping the Agents¶

make down

Next Steps¶