Turn simulation artefacts into deterministic, provenance-preserving evidence that AI systems can inspect, query, compare, and cite.
Quickstart · Architecture · Platform stack · CLI · REST/OpenAPI · Security · Commercial licensing
Raw simulation files are not AI context. CaeReflex converts CAE work into governed, machine-readable evidence—without running solvers, mutating source cases, or forcing heavy numerical arrays into model context windows.
CaeReflex connects computer-aided engineering workflows to physics-aware AI systems. It inspects solver cases, meshes, fields, spatial relationships, dimensional evidence, literature metadata, revision history, and human review; then exposes the result through versioned contracts, Python, CLI, and a bounded REST/OpenAPI service.
| INSPECT | STRUCTURE | REASON | GOVERN |
|---|---|---|---|
| Native, read-only evidence extraction from supported CAE formats | ReflexCase, lazy arrays, spatial graphs, provenance, and diagnostics | Deterministic dimensional and physics-consistency checks | Immutable revisions, temporal comparisons, run histories, and append-only review |
| Leadership view | Platform view | Engineering view |
|---|---|---|
| A horizontal infrastructure layer between simulation software and physics-aware AI. | A bounded evidence service that can sit inside model, agent, digital-engineering, and R&D platforms. | Native readers, typed contracts, lazy heavy-data access, spatial queries, rule packs, and governed lifecycle from one toolchain. |
Simulation intelligence is usually trapped inside folders, solver conventions, binary-heavy datasets, scripts, and expert memory. An AI system may receive a screenshot, copied log, or verbal summary, but not the structured evidence required to distinguish:
- what was actually present in the engineering files;
- what was decoded exactly, inferred, user-supplied, conflicted, or unavailable;
- which coordinate frame, field association, unit, time step, and source path applies;
- what changed between two engineering revisions;
- which checks passed, failed, were blocked, or could not be evaluated;
- what a human reviewer accepted, rejected, conditioned, or superseded; and
- which conclusions remain outside the recorded evidence.
CaeReflex is not another model. It is the evidence substrate models need before they can operate responsibly on CAE.
| Physics-aware AI | Simulation intelligence | Digital engineering | Governed R&D automation |
|---|---|---|---|
| Foundation models, engineering copilots, tool-using agents, and scientific reasoning systems | Search, review, comparison, and knowledge layers over simulation estates | Digital twins, design-space exploration, optimisation workflows, and model-based engineering | Internal platforms that require provenance, bounded execution, immutable evidence, and human control |
flowchart LR
subgraph Sources["Engineering sources"]
OF["OpenFOAM cases"]
GM["Gmsh geometry and meshes"]
VT["VTK datasets and collections"]
LR["Optional literature query"]
end
subgraph Acquisition["Evidence acquisition"]
DM["Discovery manifest"]
IP["Bounded inspection plan"]
NR["Isolated native readers"]
DF["Deterministic fallbacks"]
end
subgraph Core["Evidence core"]
RC["ReflexCase"]
PR["Provenance and diagnostics"]
AR["ArrayRef and content-addressed artefacts"]
end
subgraph Intelligence["Physics-aware structure"]
SG["Spatial graph"]
SQ["Bounded spatial queries"]
RU["Deterministic physics-rule reports"]
end
subgraph Governance["Governed lifecycle"]
PJ["Projects"]
RV["Immutable revisions"]
CP["Temporal comparisons"]
HR["Append-only human review"]
end
subgraph Interfaces["Integration surfaces"]
CLI["CLI"]
PY["Python"]
API["Bounded REST/OpenAPI"]
end
Sources --> DM --> IP
IP --> NR
IP --> DF
NR --> RC
DF --> RC
RC --> PR
RC --> AR
RC --> SG --> SQ
RC --> RU
RC --> PJ --> RV --> CP --> HR
Core --> Interfaces
Intelligence --> Interfaces
Governance --> Interfaces
| Layer | Capability | Primary output |
|---|---|---|
| Discovery | Bounded workspace cataloguing, format detection, adapter probing, and incremental manifest diffs | CaseManifest |
| Inspection | Read-only Gmsh, OpenFOAM, and VTK inspection with explicit parser attempts and fallbacks | ReflexCase |
| Native evidence | Isolated backends for supported geometry, mesh, topology, field, and time metadata | InspectionExecutionResult |
| Heavy data | Content-addressed artefacts and lazy bounded numerical access | ArrayRef |
| Units | Seven-component dimensional evidence, parsing, conversion, and compatibility checks | quantity evidence and dimensional checks |
| Spatial evidence | Backend-neutral entities, coordinate frames, relations, bounds, and array links | persisted spatial graph |
| Spatial queries | Bounded entity, relation, neighbourhood, bounds, frame, and array-link queries | deterministic query result |
| Physics checks | Versioned deterministic rules with evidence pointers, limitations, remediation, and six-valued outcomes | RuleEvaluationReport |
| Literature | Explicitly requested DOI metadata and available abstracts | literature evidence and BibTeX |
| Lifecycle | Projects, immutable revisions, restricted runs, and append-only events | lifecycle records |
| Temporal review | Deterministic revision comparison using exact JSON-pointer paths | TemporalComparison |
| Human control | Append-only decisions with supersession and digest chaining | HumanReviewRecord |
| Services | Synchronous evidence endpoints and bounded local asynchronous jobs | REST/OpenAPI responses |
| Characteristic | Why it matters |
|---|---|
| Deterministic | Stable ordering, versioned contracts, explicit states, canonical digests, and fail-closed behaviour make outputs testable and comparable. |
| Evidence-preserving | Every material claim can retain provenance, source paths, evidence state, diagnostics, and missing-evidence records. |
| Heavy-data aware | Large coordinates, connectivity, and field arrays remain outside prompt payloads behind verified, bounded handles. |
| Backend-neutral | Native formats map into common evidence and spatial contracts without asserting false cross-format equivalence. |
| Governed | Immutable snapshots, restricted state transitions, temporal diffs, and append-only review preserve operational history. |
| Bounded | Filesystem scope, scanning, worker time, output size, arrays, queries, request bodies, queues, and lists have explicit limits. |
| Extensible | Adapter entry points, rule packs, service contracts, and independent protocol versions provide controlled expansion surfaces. |
| Local-first | Ordinary inspection stays local; external literature calls are explicit and raw simulation files are not transmitted. |
CaeReflex is an inspection, evidence, provenance, and workflow-control system for simulation artefacts.
It is not a solver, mesher, CAD repair tool, visualisation engine, optimisation engine, simulation validator, certification system, convergence proof, mesh-adequacy assessor, or autonomous engineering decision-maker.
Safety boundary: a
consistentrule result means that the recorded evidence satisfied that rule. It does not establish numerical accuracy, physical validity, convergence, mesh independence, experimental validation, regulatory compliance, certification, or design safety.
git clone https://github.com/KNOWDYN/CaeReflex.git
cd CaeReflex
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[server]"Optional native-reader dependencies:
pip install -e ".[mesh]" # NumPy + meshio
pip install -e ".[vtk]" # PyVista + VTK
pip install -e ".[gmsh]" # Gmsh Python API
pip install -e ".[all,dev]"caereflex version
caereflex doctor
caereflex adapters list
caereflex execution backendscaereflex inspect examples/openfoam_cavity_minimal \
--profile deep \
--out caereflex.json \
--manifest-out manifest.json \
--agent-context agent_context.json \
--report case_report.mdThis produces a full ReflexCase, discovery manifest, compact AI-ready context, and human-readable report. With deep or forensic, supported cases also pass through an isolated native backend and may create spatial evidence and lazy array references.
caereflex physics evaluate-openfoam \
--case caereflex.json \
--out physics_report.jsonThe initial OpenFOAM CFD pack checks velocity, pressure, and viscosity dimensions; mesh face accounting; boundary-patch coverage; and field association. Missing evidence never becomes a pass.
caereflex lifecycle project-create "Pump study"
# Copy the returned project_id.
caereflex lifecycle revision-create PROJECT_ID \
--case caereflex.json \
--label baselineRepeat the inspection after a design or setup change, create a second revision, then compare:
caereflex lifecycle compare \
PROJECT_ID \
BASELINE_REVISION_ID \
CANDIDATE_REVISION_ID \
--max-changes 200caereflex serve \
--host 127.0.0.1 \
--port 8765 \
--workspace .curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/openapi.yamlThe service is localhost-first. Binding to a non-localhost address requires an API key.
| Profile | Purpose |
|---|---|
catalog |
Bounded discovery and inventory creation |
standard |
Core adapter inspection and normalized ReflexCase output |
deep |
Standard inspection plus isolated native execution where supported |
forensic |
Native execution path for the highest-evidence inspection workflow currently supported by the selected backend |
Inspection remains read-only at every profile. Adapter and backend support determines what can be decoded; unsupported grammar becomes explicit diagnostics or fallback evidence rather than an invented result.
CaeReflex can inspect case structure, dictionaries, polyMesh data, time directories, and supported ASCII fields. The native backend decodes bounded forms of:
- points and bounds;
- faces, owner, neighbour, and boundary records;
- cell, internal-face, and boundary-face counts;
- boundary-patch ranges;
- uniform and non-uniform scalar, vector, and common tensor internal fields;
- field classes, associations, and seven-component dimension vectors; and
- field availability across time directories.
It does not execute OpenFOAM, load solver libraries, expand code streams, or modify a case. Binary, directive-bearing, and unsupported inputs fall back with diagnostics.
Supported evidence paths include:
- declaration-only
.geoinspection; - dependency-free bounded ASCII reading for MSH 2.x and 4.x;
- optional
meshioreading; - nodes, elements, entities, physical groups, bounds, and field records;
- optional explicit Gmsh API inspection for selected CAD formats; and
- fingerprint-only handling for STEP, IGES, and BREP by default.
The .geo path does not invoke Gmsh or execute scripts. Includes, loops, functions, system calls, extrusions, and boolean operations remain unresolved unless supported by a separately controlled path. The optional API path does not request mesh generation.
Supported extensions include legacy VTK, XML datasets, parallel metadata, and collection formats:
.vtk, .vtu, .vtp, .vti, .vtr, .vts, .pvtu, .pvtp, .pvti, .pvtr, .pvts, .pvd, .vtm, and .vtmb.
Evidence may include:
- points, bounds, structured extents, and rectilinear coordinates;
- connectivity, offsets, and cell types;
- point, cell, and field data through lazy array references;
- collection references and time values; and
- ordered PyVista/VTK,
meshio, core ASCII/XML, and fingerprint fallbacks.
Collection and parallel references are inventoried; external references are not automatically fetched or traversed.
Additional adapters can be registered through the Python entry-point group:
caereflex.adapters
Each plugin declares formats, geometry/topology/field support, units behaviour, optional dependencies, fallback modes, network requirements, and source-execution requirements.
CaeReflex keeps compact evidence in JSON and heavy numerical payloads behind verified handles.
| Record | Role |
|---|---|
ReflexCase |
Normalized case identity, evidence, diagnostics, provenance, summaries, and references |
CaseManifest |
Bounded inventory of selected workspace paths and format hints |
InspectionPlan |
Explicit selected paths, profile, backend candidates, and budgets |
InspectionExecutionResult |
Backend identity, attempts, diagnostics, artefacts, arrays, status, and source-mutation evidence |
ArrayRef |
Lazy handle carrying shape, type, checksum, association, backend, time, frame, and permitted operations |
SpatialGraphSnapshot |
Compact entities, frames, relations, bounds, and array links |
RuleEvaluationReport |
Versioned rule outcomes, exact evidence pointers, missing evidence, remediation, and digests |
RevisionRecord |
Immutable canonical ReflexCase snapshot with SHA-256 digest |
TemporalComparison |
Deterministic structural changes between verified revisions |
HumanReviewRecord |
Append-only decision and statement linked to recorded evidence |
Current protocol versions
| Contract | Version |
|---|---|
| Package | 2.0.0b6 |
| ReflexCase schema | 1.0 |
| Backend-neutral inspection contract | 2.0-alpha.3 |
| Gate 5 backend-result envelope | caereflex.gate5.backend-result/1.0 |
| Spatial graph | 1.0 |
| Spatial mapping | caereflex.spatial-mapping/1.0 |
| Spatial query | caereflex.spatial-query/1.0 |
| Gate 6 spatial acceptance | caereflex.gate6.spatial/1.0 |
| Physics-rule protocol | caereflex.physics-rule/1.0 |
| OpenFOAM CFD rule pack | caereflex.openfoam-cfd/1.0.0 |
| Project/revision/run lifecycle | caereflex.lifecycle/1.0 |
| Temporal comparison | caereflex.temporal-comparison/1.0 |
| Human review | caereflex.human-review/1.0 |
| Asynchronous jobs | caereflex.async-job/1.0 |
Large coordinates, connectivity, field values, memberships, and topology arrays are stored in the local content-addressed artefact store rather than embedded in ReflexCase JSON.
ArrayRef exposes metadata and permitted operations. The CLI provides bounded access:
caereflex arrays list
caereflex arrays describe ARRAY_ID
caereflex arrays sample ARRAY_ID --count 100
caereflex arrays slice ARRAY_ID --start 0 --stop 100
caereflex arrays reduce ARRAY_ID --operation meanReturned element counts are bounded, slices are checked, and reductions stream over the artefact rather than materialising an unrestricted array in JSON.
Native OpenFOAM, Gmsh, and VTK evidence can be mapped into a backend-neutral spatial graph. The graph separates geometry, mesh, grouping, and dataset identities and records coordinate-frame evidence without assuming global axes, metres, zero origins, handedness, or cross-format equivalence.
Heavy coordinates and connectivity stay behind ArrayRef links.
caereflex spatial version
caereflex spatial graphs --case-id CASE_ID
caereflex spatial show GRAPH_ID
caereflex spatial frames GRAPH_ID
caereflex spatial entities GRAPH_ID --kinds mesh_cell,mesh_face
caereflex spatial relations GRAPH_ID --entity-id ENTITY_ID
caereflex spatial neighbours GRAPH_ID ENTITY_ID --depth 2
caereflex spatial bounds GRAPH_ID \
--frame-id FRAME_ID \
--minimum "0,0,0" \
--maximum "1,1,1"
caereflex spatial arrays GRAPH_ID
caereflex spatial validate GRAPH_IDSpatial queries are read-only and bounded. They use recorded relations and same-frame bounds; they do not invent adjacency, compose unresolved transforms, infer units, or assert cross-format equivalence.
Every rule declares identity, version, applicability, required evidence, assumptions, limitations, severity, evidence pointers, remediation, and deterministic result semantics.
The six possible outcomes are:
consistent, inconsistent, unknown, not_applicable, not_evaluated, and blocked.
caereflex physics version
caereflex physics evaluate-openfoam --case caereflex.jsonRule reports include input and report digests. Malformed required evidence and internal rule exceptions fail closed as blocked.
flowchart LR
P["Project"] --> R1["Revision 1"]
P --> R2["Revision 2"]
R1 --> C["Deterministic comparison"]
R2 --> C
P --> RUN["Run and append-only events"]
C --> H1["Human review"]
H1 --> H2["Superseding review"]
Key properties:
- project-local revision sequences and parent links;
- canonical JSON snapshots verified by SHA-256;
- restricted run transitions and append-only events;
- terminal runs cannot be reopened;
- volatile timestamps are ignored by default during comparison;
- changes use exact JSON-pointer paths;
- detailed comparisons are bounded and explicitly marked when truncated;
- review rows cannot be updated or deleted; and
- optional signature metadata is preserved but not independently authenticated.
caereflex lifecycle version
caereflex lifecycle project-list
caereflex lifecycle project-show PROJECT_ID
caereflex lifecycle revision-list PROJECT_ID
caereflex lifecycle revision-show REVISION_ID --include-case
caereflex lifecycle run-list PROJECT_ID
caereflex lifecycle run-show RUN_ID
caereflex lifecycle review-list PROJECT_ID| Command group | Operations |
|---|---|
| Core | version, doctor, scan, inspect, serve |
| Adapters | adapters list, adapters info, adapters probe |
| Units | units parse, units convert, units check |
| Execution | execution backends, execution run |
| Arrays | arrays list, arrays describe, arrays sample, arrays slice, arrays reduce |
| Spatial | spatial version, graphs, show, frames, entities, relations, neighbours, bounds, arrays, validate |
| Physics | physics version, physics evaluate-openfoam |
| Lifecycle | lifecycle version, project, revision, run, comparison, and review commands |
| Jobs | jobs list, jobs show |
| Literature | crossref search, crossref attach |
| Export | export agent-context, export markdown, export bibtex |
| Schema | schema show, schema validate |
| Diagnostics | diagnostics list, diagnostics explain |
| Cache | cache clean |
| Examples | examples list, examples run |
Use caereflex COMMAND --help or caereflex GROUP COMMAND --help for complete options and limits.
from pathlib import Path
from caereflex.contracts import InspectionProfile
from caereflex.services import export_case, inspect_path, save_case
source = Path("examples/openfoam_cavity_minimal")
case = inspect_path(
source,
adapter="auto",
profile=InspectionProfile.deep,
)
save_case(case, "caereflex.json")
export_case(case, "agent-context", "agent_context.json")
export_case(case, "markdown", "case_report.md")Lifecycle and comparison example:
from caereflex.lifecycle import LifecycleStore, compare_revisions
from caereflex.services import load_case
store = LifecycleStore(".caereflex")
project = store.create_project("Pump study")
baseline_case = load_case("baseline.caereflex.json")
candidate_case = load_case("candidate.caereflex.json")
baseline = store.create_revision(project.project_id, baseline_case.model_dump(mode="json"))
candidate = store.create_revision(project.project_id, candidate_case.model_dump(mode="json"))
comparison = compare_revisions(
store,
project.project_id,
baseline.revision_id,
candidate.revision_id,
)Install the server extra and start a workspace-bound service:
pip install -e ".[server]"
caereflex serve \
--host 127.0.0.1 \
--port 8765 \
--workspace /trusted/engineering/workspaceFor a non-localhost bind:
caereflex serve \
--host 0.0.0.0 \
--port 8765 \
--workspace /trusted/engineering/workspace \
--api-key "$CAEREFLEX_API_KEY"The server exposes its generated schema at /openapi.yaml.
| Group | Endpoints |
|---|---|
| Service | GET /health, GET /version, GET /lifecycle/version, GET /openapi.yaml |
| Cases | POST /cases/import, GET /cases, GET /cases/{case_id}, summary, agent-context, literature, and inspection-flags endpoints |
| Literature | case-scoped CrossRef search and attach |
| Export | case-scoped JSON, Markdown, and BibTeX export |
| Projects | create, list, retrieve, and archive |
| Revisions | create/list by project and retrieve by revision |
| Runs | list by project and retrieve with append-only events |
| Comparisons | create and retrieve |
| Reviews | create and filtered list |
| Jobs | submit inspection/comparison, list, and retrieve |
Defaults and hard limits include:
- request body: 1 MiB default; configurable between 1 KiB and 10 MiB;
- list responses: at most 100 records through REST;
- CrossRef result limit: at most 50;
- comparison details: at most 500 changes;
- asynchronous workers: 1–8;
- queued jobs: 0–128;
- options: at most 32 keys;
- metadata: bounded key count and serialized size; and
- every REST filesystem path must remain inside the configured workspace.
The asynchronous executor is local and in-process, not a distributed queue. Pending or running lifecycle jobs left by a stopped service are failed closed during recovery rather than silently resumed.
Literature lookup is opt-in. Ordinary discovery, inspection, spatial queries, rules, lifecycle operations, and exports do not make hidden literature-service calls.
caereflex crossref search caereflex.json \
--query "lid driven cavity CFD" \
--limit 5 \
--out literature.json
caereflex crossref attach caereflex.json \
--query "lid driven cavity CFD" \
--limit 5 \
--out caereflex.with_literature.json
caereflex export bibtex caereflex.with_literature.json \
--out references.bibOnly generated or user-supplied query strings and API parameters are sent. Raw simulation files are not transmitted. Returned records are metadata and available abstracts, not proof that a full paper was read or that a simulation is valid.
CaeReflex is designed around a narrow, inspectable boundary:
- localhost-first service deployment;
- mandatory API key for non-localhost binding;
- workspace-contained REST paths;
- bounded scanning, execution time, result size, request size, arrays, and queries;
- sanitised deep-execution environment by default;
- network and child-process guards in the Python worker;
- before-and-after source snapshots;
- content-addressed artefacts with integrity verification;
- explicit parser attempts and fallbacks;
- no solver, mesher, shell, visualisation-pipeline, or source-mutation endpoints; and
- no hidden external literature calls.
The worker is not a complete operating-system sandbox. Native libraries can bypass Python-level controls. Untrusted, proprietary, regulated, or safety-critical inputs may require a container, virtual machine, restricted operating-system account, or institutionally managed worker.
See SECURITY.md for the full security boundary and responsible-disclosure process.
CaeReflex can serve as:
- a workstation tool for inspecting individual simulation cases;
- an evidence-preparation stage for physics-aware AI systems;
- a local or internal REST service for engineering tools;
- a provenance layer for simulation-data pipelines;
- a deterministic pre-check layer before human review;
- a revision and review ledger for model-development workflows; or
- an adapter framework for additional engineering formats.
Production, multi-user, cloud, regulated, or safety-critical deployment requires additional identity, authorization, HTTPS termination, isolation, logging, observability, secrets management, and operational controls. CaeReflex does not provide OAuth, RBAC, tenant isolation, or a hosted platform boundary.
| Path | Contents |
|---|---|
caereflex/ |
Package source |
caereflex/adapters/ |
Core format adapters |
caereflex/execution/ |
Isolated execution runtime and backends |
caereflex/spatial/ |
Spatial contracts, mapping, persistence, queries, and acceptance checks |
caereflex/physics/ |
Physics-rule protocol and rule packs |
caereflex/lifecycle/ |
Projects, revisions, runs, comparisons, reviews, and async jobs |
openapi/ |
Generated JSON and YAML API contracts |
examples/ |
Small offline example cases and mock literature data |
tests/ |
Core, optional-backend, gate, compatibility, and malformed-input tests |
docs/ |
Gate specifications and compact reference documents |
wiki/docs/ |
User guides, learning projects, architecture, developer, security, and release documentation |
- Installation
- Quickstart
- Safe execution and arrays
- Native OpenFOAM inspection
- Native Gmsh inspection
- Native VTK inspection
- Spatial queries
- Architecture overview
- REST API architecture
- CLI reference
- OpenAPI reference
- Licensing reference
The repository maintains separate checks for:
- deterministic core behaviour across Python 3.10, 3.11, and 3.12;
- optional Gmsh and VTK dependencies;
- native-reader compatibility;
- malformed-input and fault-injection behaviour;
- spatial acceptance;
- physics-rule determinism; and
- lifecycle, immutable review, asynchronous jobs, and bounded REST services.
The checked-in OpenAPI documents, package metadata, citation metadata, changelog, and release documentation are validated against the package version.
CaeReflex is source-available, not OSI-approved open-source software.
Academic research, teaching, coursework, non-commercial reproducibility, and non-commercial evaluation are permitted subject to the CaeReflex Research Source Licence. Commercial use—including internal commercial R&D, paid services, production systems, commercial agent workflows, APIs, hosted services, and incorporation into products—requires a separate paid commercial licence.
Commercial licensing and permissions: ipcontrol@knowdyn.co.uk
CaeReflex output must remain evidence, not authority. Qualified engineers remain responsible for verification, validation, convergence assessment, mesh studies, experiments, regulatory interpretation, design decisions, and professional sign-off.
Report security issues privately using the contact in SECURITY.md.