Skip to content

Architecture roadmap

Enterprise maturity model for CAE Copilot adoption. Canonical status matrix: status.md.

Two layers:

  • Stages 1–3 — business and engineering maturity (this page, top sections)
  • v1–v4 — implementation changelog (appendix below)

Enterprise maturity model

Stage Business goal Engineer goal Stack (target) Status
1 — Data Foundation Governed Rocky manual corpus Find manual section with page citation PyMuPDF → Qdrant; manifest metadata (cae_product, doc_type) Done (v26r1 MVP)
2 — Trusted Agent Layer Documentation copilot + DEM helpers Cited answers, script drafts, engineer orchestrates LangGraph, RAG, tools, eval Done
3 — Live CAE integration Optional vendor API / job control Run/monitor Rocky from copilot (license required) COM/API, k8s Jobs — future adapter work Deferred 
flowchart LR
    S1[Stage1_DataFoundation] --> S2[Stage2_TrustedAgent]
    S2 --> S3[Stage3_SolverOrchestration]

Stage 1 — Data Foundation

Problem addressed: AI deployed on top of unstructured chaos (duplicate PDFs, outdated standards, broken tables).

Business outcome: A governed knowledge layer before any agent goes live. Supports AI-First Redesign (TO-BE workflow) instead of automating bad AS-IS click paths.

Engineer outcome: Retrieve the current requirement with a citation — not a plausible paragraph from the wrong document version.

Stack (target):

Component Role
Unstructured.io PDF/GOST parsing, table extraction
Qdrant Narrative chunks (post-normalization)
Hybrid search Vector + metadata filters (doc_type, material, version)
Metadata contracts Source doc ID, effective date, doc_type

Fast-track adoption: Start in a sandbox with a simplified security model and a bounded document set — prove value before full enterprise InfoSec cycle.

Implemented today: Rocky v26r1 PDF ingest via scripts/ingest.py + manifest, parent-child chunking, Qdrant vector store, metadata filters. Not yet: Unstructured.io pipeline, structured material catalog API, BM25 + vector fusion.

See Data-First.

Stage 2 — Trusted Agent Layer

Problem addressed: Black-box AI — answers without sources, arithmetic in the LLM.

Business outcome: Traceable assistance suitable for engineering compliance workflows. Human-in-the-Loop: engineer remains orchestrator; AI prepares drafts and runs validated calculations.

Engineer outcome: Question → cited retrieval OR deterministic tool result → structured report. Engineer reviews before the answer enters a design record.

Stack (shipped — v1–v3):

Component Role
LangGraph Intent routing, conditional edges, retry loops
Qdrant + sentence-transformers RAG with parent-child chunks
Pure Python tools Deterministic engineering calculations
Pydantic Tool argument validation + retry (max 3)
FastAPI + Streamlit API/UI split over HTTP
Eval suite Golden Q&A, citation hit rate

Model-agnostic: CAEC_LLM_PROVIDER supports OpenRouter, OpenAI, Anthropic; local models (Qwen, YandexGPT-class) via compatible API base URL — reduces vendor lock-in and supports on-prem deployment.

See data flow, runtime view, principles.

Stage 3 — Solver Orchestration

Status: Deferred — design only. Not part of current product positioning.

Problem addressed: Extending the workflow to long-running CAE jobs without blocking the agent or creating a new black box.

Business outcome: Orchestrated solver runs with audit trail — not "AI runs FEA autonomously."

Engineer outcome: Submit job → monitor job_id → review parsed results with logged assumptions. Human approves before results enter the report.

Stack (planned):

Component Role
Docker Isolated solver containers
Celery + Redis or k8s Jobs Async task queue
File storage Input decks and result files
Solver Agent Skill-spec orchestrator — see solver-agent-skill.md

Long-running jobs must not block the LangGraph request thread:

sequenceDiagram
    actor U as Engineer
    participant LG as LangGraph
    participant FS as File storage
    participant Queue as Task queue
    participant Docker as Solver container

    U->>LG: Run static analysis on this beam model
    LG->>LG: Validate inputs via Tools
    LG->>FS: Store input deck
    LG->>Queue: submit_job(job_id)
    LG->>U: Job started. ID: 123

    Note over Queue,Docker: Async execution

    Queue->>Docker: Run solver
    Docker->>FS: Write results
    Queue->>LG: job_id 123 done
    LG->>FS: Parse max stress, displacement
    LG->>U: Report with human_review flag

Do not use specific commercial product names in portfolio or marketing copy until working prototypes exist.

Target architecture (Stage 3 vision)

Status: Planned — not current deployment.

graph TD
    User((Engineer)) --> UI[Streamlit UI]
    UI --> API[FastAPI]
    API --> State[(CAEState)]
    State --> Router{Router}

    Router --> RAG[RAG node]
    Router --> Tools[Tools node]
    Router --> Solver[Solver node]

    RAG <--> Qdrant[(Qdrant)]
    Tools --> PyTools[Python tools]
    Solver --> DockerSolver[Docker solvers]

    RAG --> Report[Report node]
    Tools --> Report
    Solver --> Report
    Report --> API

Current MVP implements Router → RAG (knowledge/setup/scripting) | Tools (calculation) | Report (unknown) → Report. Router is a conditional edge, not a graph node.

Implementation history (v1–v4)

Technical changelog mapped to maturity stages.

v1 — Agent skeleton (done) → Stage 2

  • CAEState TypedDict as single source of truth
  • Intent node (keyword + optional LLM)
  • Router (conditional edge) → RAG (knowledge/setup/scripting) | Tools (calculation) | Report (unknown)
  • FastAPI POST /ask, GET /health, GET /tools
  • Unit tests without API key or Qdrant

v2 — Knowledge base (done) → Stage 1 + 2

  • Qdrant vector store with in-memory fallback
  • Parent-child chunking and metadata (doc_type, material)
  • scripts/ingest.py CLI
  • Citations in report output
  • Local compose: make dev-stack + make ingest

v3 — Engineering tools (done) → Stage 2

  • Three DEM helper tools (particle count, unit convert, timestep heuristic)
  • LLM tool-calling with validation retry (max 3 attempts)
  • Regex fallback for offline / CI
  • Streamlit UI via HTTP client (no graph imports in UI)

v4 — External tool integration (deferred) → Stage 3

Same scope as Stage 3 above. Full spec: solver-agent-skill.md.

Post-MVP backlog

Item Priority Stage Notes
Unstructured.io ingestion pipeline High 1 PDF/GOST table extraction
Structured material catalog API High 1 Data-First numeric lookup
First prod deploy + DNS/TLS — 2 Done — deployment
Expand eval to 15–20 golden cases High 2 14 cases today; pdm run eval
LangSmith / datasets faithfulness eval Medium 2 [eval] extras planned; run_eval.py is rule-based only
Solver Agent prototype Medium 3 Deferred
LangSmith tracing in CI smoke Medium 2 CAEC_ENABLE_TRACING
Telegram / multi-channel UI Low 2 API-first design supports later