Skip to content

Solver Agent specification (Stage 3)

Status: Deferred — design only. Not implemented. Stage 3 scope in roadmap. Current MVP: Router (conditional edge) → RAG | Tools | (direct) → Report.

This page defines the Solver Agent — the async CAE job orchestrator planned for Stage 3. Specified as a skill-based agent contract so implementation can swap orchestration backends without changing engineering semantics.

Scope

In scope:

  • Submit, monitor, and parse async external CAE / solver jobs
  • Generate input decks from validated CAEState fields
  • Return structured results with logged assumptions and job metadata
  • Surface uncertainty and request human review on safety-critical outputs

Out of scope:

  • Autonomous design decisions (geometry changes, load case selection without human approval)
  • Blocking the LangGraph request thread during long FEA runs
  • Numeric material properties from RAG (see Data-First)

Context and inputs

Input Source Notes
CAEState LangGraph shared state Single source of truth
Material IDs, σ_y, E Tools / structured API Never from RAG chunks
Geometry / load summary User query + validated state fields Pydantic-validated
Input deck path File storage (S3 / PVC) Written before queue submit
Prior tool results state.tool_results Beam hand-calc vs FEA cross-check

Process (chain of thought)

sequenceDiagram
    participant LG as LangGraph
    participant SA as SolverAgent
    participant FS as FileStorage
    participant Q as TaskQueue
    participant Docker as SolverContainer

    LG->>SA: invoke with validated CAEState
    SA->>SA: Self-check inputs (units, BCs, material source)
    SA->>FS: Write input deck
    SA->>Q: submit_job(job_id)
    SA->>LG: Job started — return job_id to user

    Note over Q,Docker: Async — graph does not block

    Q->>Docker: Run solver
    Docker->>FS: Write results
    Q->>SA: job complete webhook / poll
    SA->>FS: Parse max stress, displacement
    SA->>SA: Quality Bar self-check
    SA->>LG: Structured result + human_review flag

Steps:

  1. Validate all numeric inputs (Pydantic + unit check)
  2. Confirm material data came from Tools, not RAG
  3. Generate solver input deck
  4. Submit to queue (Celery/Redis or k8s Job)
  5. Return job_id immediately — engineer monitors progress
  6. On completion: parse results, run Quality Bar checklist
  7. Flag human_review_required for safety-critical outputs

Output format

Structured report fields (extends existing report node):

{
  "job_id": "cae-job-123",
  "status": "completed",
  "max_stress_mpa": 142.3,
  "max_displacement_mm": 0.87,
  "input_assumptions": ["simply supported", "6061-T6 from material tool"],
  "citations": [],
  "human_review_required": true,
  "quality_bar_passed": true
}

Free-text summary for the engineer references job_id and input assumptions — not unsourced claims.

Quality Bar (self-check checklist)

Before returning results to the report node, the Solver Agent verifies:

Check Rule
Units consistent Stress in MPa, length in mm (or logged conversion)
Boundary conditions logged BCs appear in input_assumptions
Material provenance Material ID traced to structured tool, not RAG
Safety factor present If load case is structural, FoS computed or flagged missing
Human approval flag human_review_required=true for safety-critical classes
Job traceability job_id, input deck path, solver version in state

Failed checks → append to state.errors, do not present as final answer.

Anti-patterns

Anti-pattern Why it fails
Block LangGraph until FEA completes Timeouts, no UX for 30-min runs
Read yield strength from RAG chunk Hallucination risk on tabular data
Skip human review on structural results Black-box liability
Hard-code one commercial solver Vendor lock-in; use containerized backends
Present solver output without input assumptions Not auditable — engineer cannot verify

Planned infrastructure

Component Options
Execution Docker images per solver backend
Queue Celery + Redis or k8s Job + webhook
Storage Shared PVC / object store for decks and results
Graph resume Poll or webhook to continue LangGraph after job completion

Do not name specific commercial CAE products in marketing until working prototypes exist. See positioning.

Skill-based agent pattern

This specification follows the same structure used by skill-based agent frameworks (e.g. Hermes, OpenClaw-style skill specs): explicit scope, inputs, process, output schema, quality bar, and anti-patterns — without coupling the product to any single agent runtime.