robert

The AI scientific research developer powered by simulations.

robert is the method layer of an AI simulation scientist. It packages what a simulation scientist does as tools that any coding agent can call, and it leaves the simulation itself to stochadex. The agent does the implementation, and the experienced user supplies judgment where the work is new. Every point where the user had to step in is logged.

It is built to test one claim: how far can simulation science be automated? The design doc has the full argument.

The loop

flowchart LR
  pose --> conjecture --> confront --> test
  test -- fails --> discover --> confront
  test -- holds --> compress --> test
  compress --> warrant --> query --> revise --> pose

The supporting commands are run, graph, plot, status, explain, intervene and doctor. Every command is also an MCP tool with the same arguments, so a project driven through chat leaves the same trail as one driven by hand.

Install

curl -fsSL https://raw.githubusercontent.com/umbralcalc/robert/main/install.sh | sh

The installer puts the robert-ai package in an isolated tool environment, using uv if you have it, then pipx, and otherwise it installs uv first. It then runs robert setup, which:

• downloads the stochadex release robert locks into ~/.robert/stochadex/<version>/ and checks it against the SHA-256 recorded in robert/stochadex.json;
• installs the Claude Code plugin (both skills and the MCP server) when claude is on PATH, and adds the MCP server to ~/.cursor/mcp.json when Cursor is installed.

Run robert doctor at any time to check the toolchain. Re-running robert setup repairs or upgrades the install, and robert setup --accelerated swaps in the BLAS + DuckDB build of stochadex. Set ROBERT_VERSION=0.2.0 to install a specific release, or ROBERT_NO_AGENTS=1 to skip agent registration.

Until the first PyPI release is out, install from GitHub instead:

curl -fsSL https://raw.githubusercontent.com/umbralcalc/robert/main/install.sh | ROBERT_SOURCE=git+https://github.com/umbralcalc/robert sh

How robert depends on stochadex

robert never bundles stochadex. It locks one release and declares the range it supports, in robert/stochadex.json:

robert needs stochadex v0.24 or later: it renders the partition graph with stochadex graph, and checks its skills against stochadex catalogue, the JSON list of everything a build can run.

Connect an agent

robert setup already registers Claude Code and Cursor. To do it by hand:

Every project that robert init creates also contains its own .mcp.json, .cursor/mcp.json, AGENTS.md and .devcontainer/, so any agent opened in it finds the tools.

The skills in skills/ are the single source of method content. After you edit one, run robert adapters to regenerate the Cursor rules, AGENTS.md and the plugin manifest. CI fails if they drift.

In the cloud

Releases

Versions follow SemVer, pre-1.0, so a minor bump may break the CLI, the tool schemas or the file contracts. CHANGELOG.md has the policy. robert/__init__.py holds the only version number; the package, the plugin manifests and every project's recorded skills version all read it.

To release, run the Prepare release PR workflow with the new version. It turns the [Unreleased] changelog section into the release and bumps the version. Review and merge that PR. tag-release.yml then tags the merge commit, and release.yml tests and publishes:

• the robert-ai package to PyPI, through a trusted publisher;
• the GitHub Release, with the changelog section as its notes;
• the image to GHCR, for amd64 and arm64;
• the Dev Container Feature.

Worked example

examples/logistic-growth/walkthrough.sh /tmp/logistic-demo

This runs the whole loop against real stochadex runs:

1. Unconstrained growth fails its backtest and its density-dependence process check.
2. The user's redirect is logged.
3. discover adds a carrying capacity, which beats its parent on held-out years.
4. compress removes a seasonal nuisance without moving the claim.
5. A forecast is warranted and queried.
6. A decide query is refused, because no model-part swap was tested on the action path.

Design principles

• One hard boundary. Determinism is enforced at the stochadex run. The agent is free in everything it writes above it, and restriction comes from checks, not templates.
• Build on stochadex, not beside it. model/sim.yaml is a pure stochadex config. Validation, I/O manifests, provenance and the partition graph all come from the stochadex CLI. robert adds only the claim, the per-partition roles and hypotheses, the lineage, the tests, the ledger and the gates.
• The agent never produces a number. Every figure traces back to a config, a seed and a provenance sidecar.
• Mechanism first. Learned (ONNX) components must earn their place through discover, after mechanistic variants have failed and the user has approved.
• Gates live in the MCP server, never in agent hooks, so every agent is held to the same standard.

Repository layout

Testing

pip install -e '.[dev]'

robert setup --no-agents

pytest

The loop and recipe tests skip when no supported stochadex is installed.