Architecture overview

CAE Copilot is an engineering analysis operating layer — data-first knowledge, traceable agents, human-orchestrated workflows. Why: portfolio/problem-statement.md.

The system is an agent graph, not a single LLM call. All nodes read and write a shared CAEState — the single source of truth for debugging and tracing.

Maturity stages

Stage	Focus	Status
1 — Data Foundation	Rocky PDF corpus, manifest metadata	Done (MVP)
2 — Trusted Agent Layer	RAG + tools + HITL	Done (v1–v3)
3 — Solver Orchestration	Async CAE jobs	Deferred

Details: roadmap · status.

Core loop (Stage 2 — shipped)

User query → Intent → Router → [RAG | Tools | (direct)] → Report

The router is a conditional edge (route_after_intent()), not a separate graph node. Each request takes one branch:

Intent	Path
knowledge, setup, scripting	RAG (retrieval only) → Report (LLM synthesis)
calculation	Tools (pure Python) → Report
unknown	Report directly (no RAG, no tools)

Stage 3 adds a Solver node — design only: solver-agent-skill.md.

flowchart TD
    Q[User query] --> I[Intent node]
    I -->|knowledge setup scripting| R[RAG node]
    I -->|calculation| T[Tools node]
    I -->|unknown| P[Report node]
    R --> P
    T --> P

Deployment (current)

flowchart LR
    User([Engineer]) --> UI[cae-copilot.dmitryivanov.dev]
    UI --> API[api.cae-copilot.dmitryivanov.dev]
    API --> Graph[LangGraph]
    Graph --> Qdrant[(Qdrant)]
    Graph --> LLM[LLM provider]

Streamlit and FastAPI are separate deployables. The UI calls the API over HTTP only (SSE streaming via POST /ask/stream). LLM provider is model-agnostic via CAEC_LLM_* settings.

Documentation map

Page	Content
Roadmap	3-stage maturity model + v1–v4 changelog
Data-First	RAG vs Tools boundary
Requirements	MVP scope, must-haves, anti-goals
Principles	Design rules (state, citations, pure tools)
Stack	Technology choices by stage
Data flow	RAG path (implemented)
Runtime view	Tool-calling and retry loop (implemented)
Solver agent skill	Stage 3 agent spec (deferred)

Quick reference

Layer	Technology
UI	Streamlit
API	FastAPI
Orchestrator	LangGraph
Knowledge	Qdrant + sentence-transformers
Tools	Pure Python functions (Pydantic-validated)
LLM	OpenRouter / Anthropic / OpenAI / compatible local endpoints

UI capabilities (Stage 2)

The Streamlit UI consumes the API over HTTP only — no graph imports:

Feature	API / code
SSE streaming	POST /ask/stream — pipeline stages + token stream
Citation cards + confidence	citation_cards, metadata.confidence in response
Follow-up chips	follow_up_questions in response
Feedback thumbs	POST /feedback
Starter prompts	GET /suggest-questions
Script copy/download	Scripting intent + report draft blocks
Regenerate answer	UI resubmit with same query
Rate limiting	CAEC_RATE_LIMIT_PER_MINUTE + nginx ingress
Demo kill switch	CAEC_DEMO_ENABLED