feat: Refactor LLM router and integrate health check endpoint

- Simplified LLM call logic in llm_router.py, removing tool adapter complexity and enhancing error handling. - Added health check endpoint to main.py for system status verification. - Cleaned up router.py by removing unused imports and commented-out code, streamlining the structure. - Updated docker-compose.yml to unify services under a single Lyra container, enhancing deployment simplicity. - Created Dockerfile for unified container setup, including both Relay and Cortex services. - Added QUICKSTART.md for improved onboarding and usage instructions. - Implemented start.sh script to manage service startup and health checks.
2026-05-29 18:20:56 -04:00
parent 376b8114ad
commit 5f53fb32a4
14 changed files with 802 additions and 1665 deletions
@@ -0,0 +1,124 @@
+# Lyra Quickstart
+
+## Architecture
+
+Lyra is now a **unified container** running:
+- **Relay** (Node.js on port 7078) - User-facing API with OpenAI-compatible endpoints
+- **Cortex** (Python on port 7081) - Brain with Intake summarization pipeline
+- **Intake** - Multi-level summarization (L1-L30) that sends to Nebula
+
+## Running Lyra
+
+### 1. Start the system
+```bash
+docker-compose up -d
+```
+
+### 2. Check logs
+```bash
+# All services
+docker-compose logs -f lyra
+
+# Just startup
+docker-compose logs lyra
+```
+
+### 3. Verify it's running
+```bash
+# Check Relay
+curl http://localhost:7078/_health
+
+# Check Cortex
+curl http://localhost:7081/_health
+
+# View UI
+open http://localhost:8081
+```
+
+## Making Changes
+
+### Restart after code changes
+```bash
+docker-compose restart lyra
+```
+
+### Rebuild after dependency changes
+```bash
+docker-compose up -d --build lyra
+```
+
+## Architecture Details
+
+```
+┌─────────────────────────────────────┐
+│   Unified Container (lyra)          │
+│                                      │
+│  ┌──────────────┐  ┌─────────────┐  │
+│  │ Relay :7078  │  │Cortex :7081 │  │
+│  │  (Node.js)   │─→│  (Python)   │  │
+│  └──────────────┘  └─────────────┘  │
+│                         │            │
+│                         ↓            │
+│                    ┌─────────┐       │
+│                    │ Intake  │       │
+│                    │Summarize│       │
+│                    └─────────┘       │
+│                         │            │
+└─────────────────────────┼────────────┘
+                          ↓
+                    ┌──────────┐
+                    │  Nebula  │  (external, to be built)
+                    │  (vector │
+                    │ storage) │
+                    └──────────┘
+```
+
+## Endpoints
+
+### Relay (Port 7078)
+- `POST /chat` - Lyra-native chat endpoint
+- `POST /v1/chat/completions` - OpenAI-compatible endpoint
+- `GET /sessions` - List sessions
+- `GET /_health` - Health check
+
+### Cortex (Port 7081)
+- `POST /reason` - Full reasoning pipeline
+- `POST /simple` - Simple chat mode
+- `POST /ingest` - Internal intake endpoint
+- `GET /_health` - Health check
+
+## Environment Variables
+
+Key variables in `.env`:
+```bash
+# LLM Configuration
+PRIMARY_LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-...
+
+# Nebula (when available)
+NEBULA_API=http://nebula:7090
+NEBULA_KEY=your-key
+
+# Intake Settings
+INTAKE_LLM=PRIMARY
+SUMMARY_MAX_TOKENS=200
+SUMMARY_TEMPERATURE=0.3
+```
+
+## Data Persistence
+
+Until Nebula is running, summaries are saved to:
+```
+.nebula_fallback/
+  └── {session_id}/
+      ├── L10_20260223_203045.json
+      ├── L20_20260223_204512.json
+      └── L30_20260223_210030.json
+```
+
+Sessions are saved to:
+```
+core/relay/sessions/
+  ├── {session_id}.json
+  └── {session_id}.meta.json
+```