robert-ai 0.1.0__py3-none-any.whl

robert/__init__.py

@@ -0,0 +1,13 @@
+"""robert: the AI simulation scientist.
+
+A thin method layer over the stochadex engine. It owns the method files and the
+gates of the discovery-and-warrant loop, and delegates every simulation action to
+the stochadex binary. The same tool registry drives the CLI and the MCP server, so
+a chat-driven project and a hand-driven one leave the same trail in the repo.
+
+The version below is the single source: the package metadata, the plugin manifest
+and the skills version every project records all read it. The stochadex version
+robert supports lives in `stochadex.json`.
+"""
+
+__version__ = "0.1.0"

robert/adapters.py

@@ -0,0 +1,97 @@
+"""Render per-agent adapters from the one source of method content in skills/.
+
+Method content has one source. These thin adapters only change its packaging: a
+Claude Code plugin, Cursor rules plus MCP config, and an AGENTS.md for anything
+else. Correctness never lives here; it lives in the MCP tools every adapter calls.
+`tests/test_adapters.py` fails when a committed adapter drifts from its source.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from . import __version__
+from .scaffold import MCP_SERVER
+from .tools import TOOLS
+
+REPO = Path(__file__).resolve().parents[1]
+AUTHOR = {"name": "umbralcalc", "email": "umbralcalc@gmail.com",
+          "url": "https://github.com/umbralcalc/robert"}
+DESCRIPTION = ("The AI simulation scientist: drives stochadex projects through the "
+               "discovery-and-warrant loop, with every gate enforced by the robert MCP server.")
+HEADER = "<!-- Generated by `robert adapters` from skills/. Do not edit by hand. -->\n"
+
+
+def skills(repo: Path = REPO) -> list[tuple[dict[str, str], str]]:
+    out = []
+    for path in sorted((repo / "skills").glob("*/SKILL.md")):
+        _, front, body = path.read_text().split("---", 2)
+        # Skill frontmatter is `key: value` lines, not strict YAML (descriptions
+        # may contain `{type: ...}`), so split each line at its first colon.
+        meta = dict(line.split(":", 1) for line in front.strip().splitlines())
+        out.append(({k.strip(): v.strip() for k, v in meta.items()}, body.strip() + "\n"))
+    return out
+
+
+def _nest_headings(body: str) -> str:
+    """Push a skill's headings two levels down, leaving code blocks alone."""
+    lines, fenced = [], False
+    for line in body.splitlines(keepends=True):
+        if line.startswith("```"):
+            fenced = not fenced
+        elif not fenced and re.match(r"#+ ", line):
+            line = "##" + line
+        lines.append(line)
+    return "".join(lines)
+
+
+def outputs(repo: Path = REPO) -> dict[str, str]:
+    """Every adapter file, keyed by path relative to the repo."""
+    files: dict[str, str] = {}
+    files[".claude-plugin/plugin.json"] = json.dumps({
+        "name": "robert",
+        "description": DESCRIPTION,
+        "version": __version__,
+        "author": AUTHOR,
+        "repository": AUTHOR["url"],
+        "license": "MIT",
+        "keywords": ["simulation", "stochadex", "scientific-method", "agent-skill"],
+        "skills": "./skills/",
+        "mcpServers": {"robert": MCP_SERVER},
+    }, indent=2) + "\n"
+    files[".claude-plugin/marketplace.json"] = json.dumps({
+        "name": "robert",
+        "owner": AUTHOR,
+        "metadata": {"description": DESCRIPTION, "version": __version__},
+        "plugins": [{"name": "robert", "source": ".", "description": DESCRIPTION,
+                     "category": "modeling",
+                     "keywords": ["simulation", "stochadex", "scientific-method"]}],
+    }, indent=2) + "\n"
+    files["adapters/cursor/mcp.json"] = json.dumps(
+        {"mcpServers": {"robert": MCP_SERVER}}, indent=2) + "\n"
+
+    agents = [HEADER, "# robert: the simulation scientist\n\n",
+              "Connect the `robert` MCP server (`robert mcp`, stdio) and follow the "
+              "skills below. The tools enforce the gates; these notes explain them.\n\n",
+              "## Tools\n\n"]
+    agents += [f"- `{t.name}`: {t.description}\n" for t in TOOLS]
+    for front, body in skills(repo):
+        files[f"adapters/cursor/rules/{front['name']}.mdc"] = (
+            f"---\ndescription: {json.dumps(front['description'], ensure_ascii=False)}\n"
+            "alwaysApply: false\n---\n"
+            + HEADER + body)
+        agents += [f"\n## Skill: {front['name']}\n\n", _nest_headings(body)]
+    files["adapters/agents/AGENTS.md"] = "".join(agents)
+    return files
+
+
+def render(repo: Path = REPO) -> list[str]:
+    written = []
+    for rel, text in outputs(repo).items():
+        p = repo / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text)
+        written.append(rel)
+    return written

robert/checks.py

@@ -0,0 +1,133 @@
+"""Deterministic checks shared by the gates.
+
+A gate collects named checks. A failed gate is not an error: the result says which
+check failed and what the method suggests next, and the user decides whether to
+accept that, override it (logged as an intervention) or bench the project.
+"""
+
+from __future__ import annotations
+
+import filecmp
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .engine import Engine
+from .project import MethodError, Project
+
+
+@dataclass
+class Gate:
+    step: str
+    checks: list[dict[str, Any]] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def check(self, name: str, passed: bool, detail: str = "") -> bool:
+        self.checks.append({"check": name, "passed": bool(passed),
+                            **({"detail": detail} if detail else {})})
+        return bool(passed)
+
+    def all(self, name: str, problems: list[str]) -> bool:
+        return self.check(name, not problems, "; ".join(problems))
+
+    def note(self, text: str) -> None:
+        """Something for the user's judgment that does not block the gate."""
+        self.notes.append(text)
+
+    @property
+    def passed(self) -> bool:
+        return all(c["passed"] for c in self.checks)
+
+    def result(self, next_if_passed: str, next_if_failed: str) -> dict[str, Any]:
+        failed = [c for c in self.checks if not c["passed"]]
+        out: dict[str, Any] = {"passed": self.passed}
+        # Compressed by default: show what failed and what needs a judgment.
+        out["failed"] = failed
+        out["passed_checks"] = [c["check"] for c in self.checks if c["passed"]]
+        if self.notes:
+            out["for_your_judgment"] = self.notes
+        out["next"] = next_if_passed if self.passed else next_if_failed
+        return out
+
+
+def run_script(project: Project, script: str, config: str | None = None,
+               sets: list[str] | None = None, extra_env: dict[str, str] | None = None
+               ) -> dict[str, Any]:
+    """Run an analysis script and read the JSON object on its last line of stdout.
+
+    Scripts are functions of committed inputs: they get the project root, the
+    config and overrides under test, and the outputs that config writes.
+    """
+    path = project.path(script)
+    if not path.is_file():
+        raise MethodError(f"script `{script}` does not exist")
+    env = dict(os.environ)
+    env["ROBERT_ROOT"] = str(project.root)
+    if config:
+        env["ROBERT_CONFIG"] = config
+        env["ROBERT_SETS"] = json.dumps(sets or [])
+        outs = Engine(project.root).file_outputs(config, sets)
+        env["ROBERT_OUTPUTS"] = json.dumps({o["name"]: o["path"] for o in outs})
+    env.update(extra_env or {})
+    python = os.environ.get("ROBERT_PYTHON", sys.executable)
+    proc = subprocess.run([python, str(path)], cwd=project.root, env=env,
+                          capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise MethodError(f"script `{script}` failed:\n{proc.stderr.strip()[-2000:]}")
+    lines = [ln for ln in proc.stdout.splitlines() if ln.strip()]
+    if not lines:
+        raise MethodError(f"script `{script}` printed nothing; it must print one JSON object")
+    try:
+        return json.loads(lines[-1])
+    except json.JSONDecodeError as e:
+        raise MethodError(f"script `{script}`: last line is not JSON: {lines[-1]!r}") from e
+
+
+def _canonical_json_log(path: Path) -> list[tuple[float, str, str]]:
+    rows = []
+    for line in path.read_text().splitlines():
+        if line.strip():
+            r = json.loads(line)
+            rows.append((r.get("time"), r.get("partition_name"), line))
+    return sorted(rows)
+
+
+def harness_twice(project: Project, config: str, sets: list[str] | None = None
+                  ) -> tuple[bool, str]:
+    """Run the config twice with its file outputs redirected, and compare bytes.
+
+    Catches statefulness residues and unseeded randomness from outside the engine.
+    """
+    engine = Engine(project.root)
+    outs = engine.file_outputs(config, sets)
+    work = project.path(".robert/harness")
+    shutil.rmtree(work, ignore_errors=True)
+    stdouts = []
+    for arm in ("a", "b"):
+        redirect = [f"outputs[name={o['name']}].function.path=.robert/harness/{arm}/{Path(o['path']).name}"
+                    for o in outs]
+        project.path(f".robert/harness/{arm}").mkdir(parents=True, exist_ok=True)
+        r = engine._call(["--config", config, *engine._sets((sets or []) + redirect)])
+        if not r.ok:
+            return False, f"run {arm} failed: {r.summary()['error']}"
+        stdouts.append(r.stdout)
+    for o in outs:
+        name = Path(o["path"]).name
+        a, b = work / "a" / name, work / "b" / name
+        if o["sink"] == "json_log":
+            # Partitions write concurrently, so rows within one step may arrive in
+            # either order; what must match is the set of rows at each time.
+            same = _canonical_json_log(a) == _canonical_json_log(b)
+        else:
+            same = filecmp.cmp(a, b, shallow=False)
+        if not same:
+            return False, f"output `{o['name']}` differs between two identical runs"
+    if not outs and stdouts[0] != stdouts[1]:
+        return False, "stdout differs between two identical runs"
+    shutil.rmtree(work, ignore_errors=True)
+    return True, f"{len(outs) or 'stdout'} output(s) byte-identical across two runs"

robert/cli.py

@@ -0,0 +1,108 @@
+"""`robert`: the CLI face of the tool registry.
+
+Arguments are generated from each tool's JSON Schema: strings and numbers are
+flags, string lists repeat (`--conditions a --conditions b`), booleans are
+`--x/--no-x`, and objects take JSON. Exit codes: 0 gate passed, 1 gate failed,
+2 the request could not be carried out.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import yaml
+
+from . import __version__
+from .project import MethodError
+from .tools import TOOLS
+
+
+def _add_arg(p: argparse.ArgumentParser, name: str, schema: dict[str, Any],
+             required: bool) -> None:
+    flag = "--" + name.replace("_", "-")
+    t = schema.get("type")
+    kw: dict[str, Any] = {"dest": name, "help": schema.get("description")}
+    if t == "boolean":
+        p.add_argument(flag, action=argparse.BooleanOptionalAction, default=None, **kw)
+        return
+    if t == "array" and schema.get("items", {}).get("type") == "string":
+        kw.update(action="append")
+    elif t in ("array", "object"):
+        kw.update(type=json.loads, metavar="JSON")
+    elif t == "number":
+        kw.update(type=float)
+    if "enum" in schema:
+        kw["choices"] = schema["enum"]
+    p.add_argument(flag, required=required, **kw)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="robert", description="The AI simulation scientist's method CLI.")
+    parser.add_argument("--version", action="version", version=f"robert {__version__}")
+    parser.add_argument("--json", action="store_true", help="print JSON instead of YAML")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for tool in TOOLS:
+        p = sub.add_parser(tool.name, help=tool.description.split(". ")[0],
+                           description=tool.description)
+        schema = tool.input_schema
+        for name, prop in schema["properties"].items():
+            _add_arg(p, name, prop, name in tool.required)
+    mcp = sub.add_parser("mcp", help="Serve every tool over MCP (stdio by default)")
+    mcp.add_argument("--http", action="store_true",
+                     help="serve streamable HTTP at /mcp instead of stdio")
+    mcp.add_argument("--host", default="127.0.0.1",
+                     help="bind address; anything but loopback requires ROBERT_MCP_TOKEN")
+    mcp.add_argument("--port", type=int, default=8765)
+    setup = sub.add_parser("setup", help="Install the locked stochadex and register agents")
+    setup.add_argument("--stochadex", metavar="VERSION",
+                       help="stochadex version to install; default: the lock's")
+    setup.add_argument("--accelerated", action="store_true",
+                       help="the BLAS + DuckDB build instead of the portable one")
+    setup.add_argument("--agents", nargs="+", metavar="AGENT",
+                       help="agents to register (claude, cursor); default: all found")
+    setup.add_argument("--no-agents", action="store_true", help="install stochadex only")
+    sub.add_parser("adapters", help="Render agent adapters from the skills source")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    ns = parser.parse_args(argv)
+    try:
+        if ns.command == "mcp":
+            from .mcp_server import serve, serve_http
+            if ns.http:
+                serve_http(ns.host, ns.port)
+            else:
+                serve()
+            return 0
+        if ns.command == "adapters":
+            from .adapters import render
+            for path in render():
+                print(path)
+            return 0
+        if ns.command == "setup":
+            from .setup import setup
+            result = setup(ns.stochadex, ns.accelerated, ns.agents, ns.no_agents)
+        else:
+            tool = next(t for t in TOOLS if t.name == ns.command)
+            args = {k: v for k, v in vars(ns).items()
+                    if k not in ("command", "json") and v is not None}
+            result = tool.call(args)
+    except MethodError as e:
+        print(f"robert {ns.command}: {e}", file=sys.stderr)
+        return 2
+    if ns.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(yaml.safe_dump(result, sort_keys=False, allow_unicode=True, width=100), end="")
+    gate = result.get("gate")
+    return 1 if (gate and not gate["passed"]) or result.get("ok") is False else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

robert/contracts.py

@@ -0,0 +1,108 @@
+"""Contracts for the method files.
+
+Each method file has one job and a validator that says, in plain words, what is
+missing. Nothing here describes the model itself: structure and wiring live only in
+model/sim.yaml, which stochadex validates. These files hold what stochadex does not
+encode: the claim, the user's domain terms, and the role, hypothesis and evidence
+behind each partition.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Query modes, in order of the warrant they need (Pearl's ladder, plus deployment).
+MODES = ["explain", "forecast", "decide", "automate", "design", "counterfactual"]
+INTERVENTION_MODES = {"decide", "automate", "design", "counterfactual"}
+
+ROLES = ["structural", "nuisance", "surrogate"]
+STATUSES = ["untested", "passed", "failed", "benched"]
+TEST_KINDS = ["backtest", "process", "swap", "generalisation", "outcome"]
+LINEAGE_STEPS = ["conjecture", "discover", "compress", "swap"]
+ACTORS = ["user", "standin"]
+DECISIONS = ["accept", "override", "redirect", "bench"]
+
+# iteration types that make a partition "learned" rather than mechanistic.
+LEARNED_TYPES = {"onnx_inference"}
+
+
+def _missing(d: dict[str, Any], keys: list[str], where: str) -> list[str]:
+    out = []
+    for k in keys:
+        v = d.get(k)
+        if v is None or (isinstance(v, (str, list, dict)) and not v):
+            out.append(f"{where}: `{k}` is not named")
+    return out
+
+
+def check_domain(d: dict[str, Any]) -> list[str]:
+    problems = _missing(d, ["description", "user_knows"], "domain.yaml")
+    if d.get("level") not in ("novice", "practitioner", "expert"):
+        problems.append("domain.yaml: `level` must be novice, practitioner or expert")
+    return problems
+
+
+def check_claim(c: dict[str, Any]) -> list[str]:
+    problems = _missing(
+        c, ["question", "claim", "intended_use", "conditions", "observables"], "claim.yaml"
+    )
+    if c.get("intended_use") and c["intended_use"] not in MODES:
+        problems.append(f"claim.yaml: `intended_use` must be one of {', '.join(MODES)}")
+    tol = c.get("compress_tolerance")
+    if tol is not None and not (isinstance(tol, (int, float)) and tol >= 0):
+        problems.append("claim.yaml: `compress_tolerance` must be a non-negative number")
+    return problems
+
+
+def check_partitions(sidecar: dict[str, Any], sim_names: list[str]) -> list[str]:
+    """One entry per partition in sim.yaml, and no others."""
+    entries = sidecar.get("partitions", {}) or {}
+    problems = []
+    for name in sim_names:
+        if name not in entries:
+            problems.append(f"partitions.yaml: `{name}` is in sim.yaml but has no entry")
+            continue
+        e = entries[name] or {}
+        if e.get("role") not in ROLES:
+            problems.append(f"partitions.yaml: `{name}` needs a role ({', '.join(ROLES)})")
+        if not e.get("hypothesis"):
+            problems.append(f"partitions.yaml: `{name}` needs a one-line hypothesis")
+        if e.get("status", "untested") not in STATUSES:
+            problems.append(f"partitions.yaml: `{name}` status must be one of {STATUSES}")
+    for name in entries:
+        if name not in sim_names:
+            problems.append(f"partitions.yaml: `{name}` is not a partition in sim.yaml")
+    return problems
+
+
+def check_test_spec(t: dict[str, Any]) -> list[str]:
+    where = f"tests.yaml check `{t.get('id', '?')}`"
+    problems = _missing(t, ["id", "partitions", "kind", "script"], where)
+    if t.get("kind") and t["kind"] not in TEST_KINDS:
+        problems.append(f"{where}: kind must be one of {', '.join(TEST_KINDS)}")
+    if t.get("kind") == "backtest":
+        te, ts = t.get("train_end"), t.get("test_start")
+        if te is None or ts is None:
+            problems.append(f"{where}: a backtest names train_end and test_start")
+        elif not ts > te:
+            problems.append(f"{where}: test_start must come after train_end (leakage)")
+    return problems
+
+
+def check_intervention(e: dict[str, Any]) -> list[str]:
+    problems = _missing(e, ["step", "actor", "agent_proposal", "decision", "reason"],
+                        "intervention")
+    if e.get("actor") and e["actor"] not in ACTORS:
+        problems.append(f"intervention: actor must be one of {', '.join(ACTORS)}")
+    if e.get("decision") and e["decision"] not in DECISIONS:
+        problems.append(f"intervention: decision must be one of {', '.join(DECISIONS)}")
+    return problems
+
+
+def sim_partitions(sim: dict[str, Any]) -> list[dict[str, Any]]:
+    return list(((sim or {}).get("main") or {}).get("partitions") or [])
+
+
+def is_learned(partition: dict[str, Any]) -> bool:
+    it = partition.get("iteration") or {}
+    return isinstance(it, dict) and it.get("type") in LEARNED_TYPES