oooo        .o8
                                                     `888       "888
oooo d8b  .ooooo.  oooo    ooo ooo. .oo.    .ooooo.   888   .oooo888   .oooo.o
`888""8P d88' `88b  `88.  .8'  `888P"Y88b  d88' `88b  888  d88' `888  d88(  "8
 888     888ooo888   `88..8'    888   888  888   888  888  888   888  `"Y88b.
 888     888    .o    `888'     888   888  888   888  888  888   888  o.  )88b
d888b    `Y8bod8P'     .8'     o888o o888o `Y8bod8P' o888o `Y8bod88P" 8""888P'
                   .o..P'
                   `Y8P'

An agentic CFD workbench that lives in your terminal.

Describe a flow problem. It sets up the case, meshes it, solves it in OpenFOAM, and answers with evidence.

· · ·

Install · Quickstart · Docs · Benchmarks

Reynolds is a local-first agentic CFD workbench. You describe the flow in natural language and it drives the real pipeline — geometry, case setup, meshing, solving, verification, analysis — over typed contracts and a pinned OpenFOAM v2512 container. Project state stays local; OpenFOAM can run locally or on the approved hosted CPU executor.

The model never writes an OpenFOAM dictionary, runs a shell, or touches Docker. It proposes typed intent; deterministic services decide whether that intent is supported and execute it. Every number it reports carries an evidence reference to the artifact the number came from.

What it does

• Runs the whole loop. Geometry in, case spec, mesh, solve, verify, analyse, report — one conversation, no dictionary editing.
• 32 typed tools. A frozen catalog with strict schemas; no tool accepts a shell string, a path, or an arbitrary expression.
• Reviewed solver matrix. simpleFoam, pimpleFoam, interFoam, kinematicParcelFoam, DPMFoam — an installed executable is not scientific support.
• Meshing that respects the wall. y+-aware topology-safe prism layers, cell-count estimates before you spend compute, and Richardson/ASME grid convergence.
• Evidence-backed answers. Value, unit, run id, and the exact postProcessing file; approval gates bind to an exact proposal hash.
• Autonomy, not interrogation. It assumes standard engineering defaults and lists them instead of asking you eleven questions.
• 10 standalone CLI tools. y+, MPI decomposition, GCI, grid studies, diagnostics, case lint, container preflight, obstacle meshes.
• Deterministic studies. Bounded parameter sweeps and discrete optimization runs where only verification-passing candidates can win.

Install

npm install -g reynolds
reynolds

The first run walks through setup: it finds uv or offers to install it, syncs the locked Python dependencies, and prompts once for OPENAI_API_KEY (stored in a gitignored .env). Docker and the pinned OpenFOAM v2512 image are optional — you only need them for real meshing and solving. Supported host is WSL2 Ubuntu on x86-64 or ARM64. See installation.

Alternatively, the terminal can keep its conversation and project state locally while sending only typed OpenFOAM jobs to the approved CPU-only GCP executor. Configure the hosted connection once and then start normally:

reynolds setup --hosted
reynolds

The setup prompt stores the supplied installation token locally and verifies the public executor. Docker, WSL, OpenFOAM, and gcloud are not required on the client PC. Deployment/operator instructions are in infra/gcp. The first hosted TUI launch also downloads and caches the small reviewed OpenFOAM 10 reference-case subset used by prompt-only FoamBench-style requests; users do not install a tutorial corpus themselves.

Quickstart

export OPENAI_API_KEY=sk-...
reynolds

# then, at the prompt:
❯ /upload fixtures/geometries/duct.zip
❯ It's in metres, an internal fluid volume. Air at 10 m/s in, outlet at 0 Pa gauge,
  walls no-slip. I need the pressure drop.
❯ /approve

It inspects the geometry, computes Re, proposes a case with its assumptions listed, and waits for /approve. Then it proposes a mesh, meshes, solves, verifies, and answers with the number and the files it came from. The annotated session is in first run.

The Reynolds wordmark and status dashboard render once when the interactive session is ready. Background events restore only the one-line input prompt, so progress messages never clone the banner. /status or /by-the-way prints a fresh deterministic snapshot without interrupting an active mesh or solve. /help patch, /help pressure-gauge, and /help inlet translate OpenFOAM terms into plain language.

Every real user message is also written before response generation to a project-scoped Markdown ledger under workspaces/user-context/. Its current-facts section uses the latest explicit value, so a later "continue" turn cannot replace an earlier 10 m/s with an autonomy default. /context shows the exact bounded ledger review supplied to the coordinator.

Geometry inspection produces a deterministic image preview from the normalized surfaces and named boundary patches. Reynolds keeps that image with the immutable geometry revision so the shape can be reviewed alongside its measured bounds, topology findings, and patch names before meshing.

General generated geometry uses a closed typed constructive-CAD recipe: boxes, cylinders, spheres, 2D polygon extrusions, rigid transforms, unions, and differences. Semantic planar-face selectors name every inlet, outlet, opening, wall, symmetry face, or external body. Reynolds requires one valid positive-volume solid and complete, unambiguous face classification, then retains the same solid as STEP, creates a named-surface STL bundle for OpenFOAM, verifies the combined shell, and renders the review image. Branched cases may have multiple inlets or outlets in any orientation; the default case builder derives each inlet direction from its measured outward normal. Raw Python, kernel commands, and arbitrary executable CAD plugins are not part of this interface.

Meshing preserves each approved face's own refinement level; missing, duplicated, or unknown face bindings are rejected before OpenFOAM runs. If a supported snappy mesh fails a hard quality gate, Reynolds retains the exact report and prepares a bounded typed recovery revision. At the default auto level you review that diff and approve it; at full the terminal can approve and continue. Recovery never changes the case physics, raises the cell ceiling, weakens quality thresholds, or retries indefinitely. Concave-polyhedron advisories remain visible but are warnings when the documented hard gates—topology, legal positive-volume cells, one fluid region, non-orthogonality, and skewness—pass.

Autonomy

| Level | Behaviour | | --- | --- | | strict | Ask rather than assume — every materially-relevant unstated fact becomes a question. | | auto (default) | Assume standard defaults and list them; you approve every state mutation and compute spend. | | full | As auto, plus auto-approve its own typed proposals so a described problem runs to an answer. |

Set it with --autonomy LEVEL at launch or /auto LEVEL in the terminal, or just say "you decide" or "just run it" mid-conversation — those phrases are matched deterministically before the model sees the turn.

Autonomy governs inputs, never results: it never states a number without evidence and never reclassifies a failing check as a pass. Detail in autonomy.

How it works

Four hops, and the model only touches the first: coordinator → typed tool gateway → deterministic services → pinned OpenFOAM worker. The gateway validates proposed intent against the frozen tool catalog; the worker runs only allowlisted execution plans in the container.

| Path | Contents | | --- | --- | | apps/api | Composition: tool gateway, coordinator, pipeline, terminal surface | | apps/worker | Runs OpenFOAM jobs in the pinned container over loopback | | packages/ | Frozen contracts plus deterministic CFD capability packages | | bin/reynolds.js | Launcher: bootstrap, setup, doctor, web | | tools/ | Engineering CLI tools, deliberately not agent-callable | | validation/ | Validation suite, grid convergence, FoamBench drivers |

The enforced import map is in docs/architecture.md.

Benchmarks

Important: the FoamBench numbers below measure the model-free deterministic text-to-OpenFOAM synthesis backend. They do not exercise the Reynolds terminal, LLM coordinator, approvals, independent prompt-fidelity reviewer, or production v2512 workflow, and must not be presented as an end-user success rate. Genuine product-path evaluations use validation/foambench/user_path.py.

Measured FoamBench (CFDLLMBench) Basic success ratio is 0.973 over 110 cases; the paper's reference points for that split are GPT-4 ≈ 0.40–0.50 and MetaOpenFOAM ≈ 0.60–0.70.

The Advanced split is 0.250 over 16 cases and is explicitly unfinished — body-fitted graded meshing is the gap, not a parameter. Full provenance in BENCHMARK_MEASURED_RUN.md and benchmarks.

Development

make doctor        # validate the host toolchain
make bootstrap     # sync the locked Python env and npm deps
make tui           # start the terminal
make check         # full CI-equivalent local gate (no OpenAI key, no OpenFOAM)
make test          # both language suites

Capability ownership, the contract freeze, and the non-negotiable boundaries are in AGENTS.md; contributor workflow is in contributing.

Security

The model is confined to typed tools with strict schemas — a shell string, a filesystem path, a Docker command, and a raw OpenFOAM dictionary are unrepresentable in every registered input schema. All OpenFOAM execution happens inside the pinned v2512 container under an allowlisted execution plan, with even mpirun constrained at the entrypoint. Every approval binds to an exact proposal id and hash, so a retried or reconstructed call cannot spend compute twice.

License

Apache-2.0 — see LICENSE.