warnerco-schematica

name	warnerco-schematica
description	Develop and extend the WARNERCO Robotics Schematica system - an agentic RAG application with FastAPI, FastMCP, LangGraph orchestration, and 3-tier memory (JSON/Chroma/Azure AI Search). Use when working on the schematica backend, adding schematics, modifying the LangGraph flow, updating dashboards, or deploying to Azure.

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

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:

{
  "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