# KOAN Demos

Eight demo apps showcasing KOAN features — four basic demos, one CLI policy lifecycle demo, and three domain-specific graph-augmented assistants.

## Prerequisites

```bash
# Install demo dependencies
uv sync --extra demos --extra llm --extra memory --extra graph-falkordb

# Set your API key
echo "OPENAI_API_KEY=sk-..." > .env

# For demos 2, 4, 5, 6, 7, 8: start FalkorDB
docker compose -f docker/docker-compose.graph.yml --profile falkordb up -d
```

## Demos

| Demo | Port | Features | Graph DB |
|------|------|----------|----------|
| **Demo 1** — Simple Chat | 8001 | ReactAgent, tools, SQLite threads, SSE streaming | None |
| **Demo 2** — Graph Chat | 8002 | GraphAugmentedAgent, feedback, context graph | FalkorDB |
| **Demo 3** — Multi-Agent | 8003 | Orchestrator, RuleRouter, 3 agents, SQLite threads | None |
| **Demo 4** — Full Stack | 8004 | Multi-agent + graph, evaluation, calibration, feedback | FalkorDB |
| **Demo 5** — Self-Organizing | CLI | Full policy lifecycle: emergence → gating → retirement | FalkorDB |
| **Demo 6** — Legal Assistant | 8006 | Case lookup, documents, motions, hearings | FalkorDB |
| **Demo 7** — Medical Triage | 8007 | Patient vitals, labs, medications, allergy screening | FalkorDB |
| **Demo 8** — Investment Advisor | 8008 | Portfolios, risk assessment, trade execution, market data | FalkorDB |

## Running

```bash
# Run any single demo
uv run python demos/demo1_simple_chat.py
uv run python demos/demo2_graph_chat.py
uv run python demos/demo3_multi_agent.py
uv run python demos/demo4_full_stack.py
uv run python demos/demo5_self_organizing.py  # CLI — runs automatically
uv run python demos/demo6_legal.py
uv run python demos/demo7_medical.py
uv run python demos/demo8_finance.py

# Then open http://localhost:800X in your browser (except demo 5)
```

## Test Questions

See [TEST_QUESTIONS.md](TEST_QUESTIONS.md) for copy-paste test scripts that exercise all features for each demo.

## UI Features

Web UI demos (1-4, 6-8) share the same chat interface:

- **Thread sidebar** — Create and switch between conversations
- **SSE streaming** — Tokens appear in real-time as the agent reasons
- **Tool call chips** — Amber during execution, green when complete
- **Info panel** — Shows iterations, tool calls, graph context, and evaluation status
- **Feedback buttons** — Thumbs up/down on each response (graph demos write to FalkorDB)

## What Each Demo Shows

### Demo 1: Simple Chat (port 8001)
Basic agent loop with tools (weather, calculator, time). Messages persist in SQLite. Good for understanding the core agent → tool → response cycle.

### Demo 2: Graph-Augmented Chat (port 8002)
A billing support agent that reads from the decision graph before answering. Past decisions, entity history, and policies appear in the agent's context. Feedback buttons write satisfaction signals to FalkorDB.

### Demo 3: Multi-Agent Router (port 8003)
An orchestrator routes input to one of three specialized agents (weather, math, general) based on keyword matching. The info panel shows which agent handled each request.

### Demo 4: Full Stack KOAN (port 8004)
Everything together: multi-agent routing (billing + support), graph-augmented reasoning, confidence calibration from feedback history, and automatic evaluation that flags low-confidence decisions. The `/api/calibration` endpoint shows live calibration stats.

### Demo 5: Self-Organizing Graph (CLI)
Automated walkthrough of the full policy lifecycle in 9 steps: cold start → accumulation → policy emergence → tool gating → negative feedback → retirement → recovery. No manual input needed — verifies that policies emerge from patterns, restrict tools, and self-correct.

### Demo 6: Legal Assistant (port 8006)
A law firm assistant with case lookup, document search, motion drafting, and hearing schedules. Uses FalkorDB graph (`koan_demo6`) with decision type `"legal"`. Repeat queries drive policy emergence; gated tools block unauthorized actions.

### Demo 7: Medical Triage (port 8007)
A clinical triage assistant with patient demographics, vitals review (with critical flags), lab ordering, medication checks, and allergy screening. Uses graph (`koan_demo7`) with decision type `"triage"`. Includes cross-reference for penicillin and sulfa drug families.

### Demo 8: Investment Advisor (port 8008)
A portfolio advisor with risk assessment, trade execution (with cash validation), and market data. Uses graph (`koan_demo8`) with decision type `"investment"`. Flags concentration risks (>30%), large gains (>50%), and evaluates risk tolerance before trades.
