warnerco-schematica

# WARNERCO Robotics Schematica Agentic robot schematics system with semantic memory and retrieval-augmented generation. ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ FastAPI + FastMCP │ ├─────────────────────────────────────────────────────────────┤ │ LangGraph Flow (9-node Hybrid RAG) │ │ parse_intent -> query_graph -> inject_scratchpad -> retrieve│ │ -> compress -> reason -> respond │ ├─────────────────────────────────────────────────────────────┤ │ Hybrid Memory Layer │ │ +-------------------+ +-------------------+ +-----------+│ │ | Vector Store | | Graph Store | | Scratchpad|│ │ | JSON->Chroma-> | | SQLite + NetworkX | | In-memory |│ │ | Azure AI Search | | (Knowledge Graph) | | (Session) |│ │ +-------------------+ +-------------------+ +-----------+│ └─────────────────────────────────────────────────────────────┘ ``` ## Project Structure ``` src/warnerco/backend/ ├── app/ │ ├── main.py # FastAPI application │ ├── config.py # Settings and environment │ ├── models.py # Pydantic schemas │ ├── routes.py # API endpoints │ ├── mcp_tools.py # FastMCP tool definitions │ ├── adapters/ # Memory backend implementations │ │ ├── json_store.py │ │ ├── chroma_store.py │ │ ├── azure_search_store.py │ │ ├── graph_store.py │ │ └── scratchpad_store.py │ └── langgraph/ │ └── flow.py # 9-node hybrid RAG orchestration ├── data/ │ ├── schematics/ # JSON source of truth │ └── chroma/ # Vector embeddings ├── static/dash/ # SPA dashboards └── .env # Configuration ``` ## Commands ```bash cd src/warnerco/backend # Local development uv sync uv run uvicorn app.main:app --reload --port 8000 # Index schematics into Chroma uv run python -c "from app.adapters.chroma_store import ChromaMemoryStore; import asyncio; asyncio.run(ChromaMemoryStore().index_all())" # MCP stdio server (for Claude Desktop) uv run warnerco-mcp ``` ## Memory Backend Selection Set `MEMORY_BACKEND` in `.env`: | Backend | Use Case | Config | |---------|----------|--------| | `json` | Fastest startup, keyword search | Default | | `chroma` | Local semantic search | Recommended for dev | | `azure_search` | Enterprise deployment | Requires Azure resources | ## MCP Tools | Tool | Description | |------|-------------| | `warn_list_robots` | List schematics with filters | | `warn_get_robot` | Get schematic by ID | | `warn_semantic_search` | Natural language search | | `warn_memory_stats` | Backend statistics | | `warn_add_relationship` | Create graph triplet (subject, predicate, object) | | `warn_graph_neighbors` | Get connected entities | | `warn_graph_path` | Find shortest path between entities | | `warn_graph_stats` | Graph node/edge statistics | | `warn_scratchpad_write` | Store session observation | | `warn_scratchpad_read` | Retrieve session entries | | `warn_scratchpad_clear` | Clear session entries | | `warn_scratchpad_stats` | Token budget statistics | ## LangGraph Flow 9-node hybrid retrieval-augmented generation: 1. **parse_intent** - Classify query (lookup/diagnostic/analytics/search) 2. **query_graph** - Enrich with knowledge graph relationships 3. **inject_scratchpad** - Add session working memory (CoALA working tier) 4. **recall_episodes** - Recall prior episodes (CoALA episodic tier; gated to ANALYTICS/DIAGNOSTIC) 5. **retrieve** - Fetch candidates from memory backend (CoALA semantic tier) 6. **compress_context** - Minimize token bloat 7. **reason** - LLM generates response (official `anthropic` SDK preferred, then Azure OpenAI, then OpenAI) 8. **respond** - Format for dashboards/MCP 9. **log_episode** - Write the interaction back to episodic memory (always) ## Adding Schematics Edit `data/schematics/schematics.json`: ```json { "id": "WRN-00026", "model": "WC-900", "name": "New Robot Name", "component": "component description", "version": "v1.0", "summary": "Technical summary...", "category": "sensors", "status": "active", "tags": ["tag1", "tag2"], "specifications": { "spec_key": "spec_value" }, "url": "https://schematics.warnerco.io/..." } ``` Then re-index: `uv run python -c "...index_all()"` ## Dashboards - **Schematics Browser** (`/dash/schematics/`) - Search, filter, view robot data - **Memory Learning** (`/dash/memory/`) - Educational RAG visualization ## Azure Deployment See `references/azure-deployment.md` for: - Container App setup - APIM configuration - AI Search indexing - OpenAI model deployment ## API Endpoints | Method | Path | Description | |--------|------|-------------| | GET | `/api/robots` | List schematics | | GET | `/api/robots/{id}` | Get by ID | | POST | `/api/search` | Semantic search | | GET | `/api/memory/stats` | Backend stats | | GET | `/docs` | OpenAPI docs |