rabbit-brain 0.6.0__py3-none-win_amd64.whl

rabbit_brain/__init__.py

@@ -0,0 +1,33 @@
+"""Rabbit Brain: the record of the experiments your coding agents run, kept as plain files in your repo.
+
+Experiments with variants and criteria, runs with receipts, and the datasets and checkpoints they used, recorded as YAML
+in `.rb/` beside the code. Agents propose and record; rb checks sources and computes findings; you decide. CLI: `rb`.
+Documentation: `rb docs` (AGENTS.md).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+__version__ = "0.6.0"
+if os.environ.get("RB_TEST_VERSION"):      # the tests pin the version, as RB_TEST_NOW pins the clock, so what they expect outlives a release
+    __version__ = os.environ["RB_TEST_VERSION"]
+
+from .errors import RBError, RBWarning  # noqa: E402
+
+_LAZY = {
+    "open": ".sdk", "init": ".sdk", "clone": ".sdk", "State": ".sdk", "Experiment": ".sdk", "Criterion": ".sdk", "Run": ".sdk",
+    "Spec": ".sdk", "DryRun": ".sdk",
+}
+
+__all__ = ["__version__", "RBError", "RBWarning", *_LAZY]
+
+
+def __getattr__(name: str) -> Any:
+    """Loaded on first use, so `import rabbit_brain` (and every `rb` command) does not pay for what it does not touch."""
+    if name in _LAZY:
+        import importlib
+        value = getattr(importlib.import_module(_LAZY[name], __name__), name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'rabbit_brain' has no attribute {name!r}")

rabbit_brain/_rb.py

@@ -0,0 +1,180 @@
+"""Calling rb from its Python package. The SDK and the terminal UI hold no rules of their own: every read and every
+write is asked of rb, through `rb bridge` (one JSON request, one JSON answer), so the Python surface and the command
+line can never disagree about what the record says.
+
+Which rb: RB_BIN when set, else the `rb` installed with this package (the scripts directory of this Python).
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import sysconfig
+import warnings
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from . import __version__
+from .errors import EXIT_ENVIRONMENT, RBError, RBWarning
+
+UNSET: Any = object()
+# pinned: unpinned, pip installs the newest final release, which can be another version than this one
+REINSTALL = f'pip install --force-reinstall "rabbit-brain=={__version__}"'
+
+
+def _quiet() -> dict:
+    """Windows: a Python with no console window (an editor's, a notebook's) starts rb without one too, so no window
+    flashes up for each question. In a terminal rb shares the terminal, as everywhere else."""
+    if sys.platform != "win32":
+        return {}
+    try:
+        import ctypes
+        if ctypes.windll.kernel32.GetConsoleWindow():
+            return {}
+    except Exception:  # noqa: BLE001 - no way to ask: start rb without a window, which is right in either case
+        pass
+    return {"creationflags": subprocess.CREATE_NO_WINDOW}
+
+
+QUIET = _quiet()
+
+
+def binary() -> Optional[str]:
+    """The rb binary this package calls, or None when there is none to find."""
+    given = os.environ.get("RB_BIN")
+    if given:
+        return given
+    exe = "rb" + (sysconfig.get_config_var("EXE") or "")
+    places = []
+    try:
+        places.append(sysconfig.get_path("scripts"))
+        places.append(sysconfig.get_path("scripts", scheme=sysconfig.get_preferred_scheme("user")))
+    except Exception:  # noqa: BLE001 - an unusual Python layout only means fewer places to look
+        pass
+    places.append(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "bin"))   # pip install --target
+    for d in places:
+        if d and os.path.isfile(os.path.join(d, exe)):
+            return os.path.join(d, exe)
+    return None
+
+
+def found() -> str:
+    """The rb this package calls. When there is none, that is said once, with what to do."""
+    rb = binary()
+    if rb is None:
+        raise RBError("E_INTERNAL", message="This Python package found no rb beside it: the SDK and the screen ask rb for everything.",
+                      fix=f"Install them together: {REINSTALL}. Or set RB_BIN to the rb binary.",
+                      exit_code=EXIT_ENVIRONMENT)
+    return rb
+
+
+def _jsonable(v: Any) -> Any:
+    """What json does not take as it is: a path, a numpy or torch scalar, a set."""
+    if isinstance(v, os.PathLike):
+        return os.fspath(v)
+    if hasattr(v, "item") and callable(v.item):
+        try:
+            return v.item()
+        except Exception:  # noqa: BLE001 - an array is not a scalar: said below
+            pass
+    if isinstance(v, (set, frozenset)):
+        return sorted(v)
+    raise RBError("E_OBJECT_INVALID", message=f"rb records text, numbers, true and false, lists and mappings (got {type(v).__name__}).")
+
+
+def command() -> list:
+    """The command line that runs rb, for what the screen runs as the user would type it."""
+    return [found()]
+
+
+def environment() -> dict:
+    """The environment rb runs in: this one, plus what only this process knows about the Python doing the work."""
+    env = dict(os.environ)
+    if sys.executable:
+        env["RB_PYTHON"] = sys.executable          # a run's receipt fingerprints the Python that made it
+    torch = sys.modules.get("torch")
+    cuda = getattr(getattr(torch, "version", None), "cuda", None) if torch is not None else None
+    if cuda:
+        env["RB_CUDA"] = str(cuda)                 # CUDA exists only on an imported torch: said by the process that has it
+    else:
+        env.pop("RB_CUDA", None)
+    return env
+
+
+def _answer(line: str) -> dict:
+    rb = found()
+    try:
+        r = subprocess.run([rb, "bridge"], input=(line + "\n").encode("utf-8"), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                           env=environment(), **QUIET)
+    except OSError as exc:
+        raise RBError("E_INTERNAL", message=f"rb could not be started ({rb}): {exc}", exit_code=EXIT_ENVIRONMENT)
+    out = r.stdout.decode("utf-8", "replace").strip()
+    try:
+        answer = json.loads(out.splitlines()[-1]) if out else None
+    except ValueError:
+        answer = None
+    if not isinstance(answer, dict) or "ok" not in answer:
+        tail = (r.stderr.decode("utf-8", "replace").strip().splitlines() or [out[:200] or f"exit {r.returncode}"])[-1]
+        raise RBError("E_INTERNAL", message=f"rb did not answer ({rb}): {tail}", exit_code=EXIT_ENVIRONMENT,
+                      fix=f"This Python package and the rb it found may be different versions: {REINSTALL}.")
+    return answer
+
+
+@dataclass
+class DryRun:
+    """A write asked with dry_run=True: rb made every check the write makes and wrote nothing. `value` is what the write
+    would give back; `would_write` what it would write, as `rb <command> --dry-run --json` gives it in data.would_write:
+    each record file with its content (`files`), each file it would remove (`removed`), each line it would add to the
+    log (`log`). Ids and times are drawn again when the write is made."""
+    value: Any
+    would_write: dict
+
+
+def call(op: str, args: Optional[dict] = None, *, root: Any = None, via: str = "sdk", agent: Optional[str] = None,
+         words: Any = UNSET, dry_run: bool = False, here: Any = None, place: Optional[str] = None, at: Optional[str] = None) -> Any:
+    """Ask rb for one thing. Returns its value, or with `dry_run` a DryRun; raises RBError with what rb said when it
+    refuses. `here` is the checkout the caller works in (a linked worktree nested in the record's), as op open gave it.
+    `place` and `at` ask what a screen reads of another place or a past version, by the id and commit op places lists:
+    read there, never written."""
+    req: dict = {"op": op, "root": os.fspath(root) if root is not None else None, "via": via, "agent": agent, "args": args or {}}
+    if here is not None:
+        req["here"] = os.fspath(here)
+    if place is not None:
+        req["place"] = place
+    if at is not None:
+        req["at"] = at
+    if words is not UNSET:
+        req["words"] = words
+    if dry_run:
+        req["dry_run"] = True
+    answer = _answer(json.dumps(req, default=_jsonable))
+    if answer["ok"]:
+        _said(answer.get("warnings"))
+        if dry_run:
+            return DryRun(answer.get("value"), answer.get("would_write") or {})
+        return answer.get("value")
+    e = dict(answer.get("error") or {})
+    raise RBError(e.pop("code", "E_INTERNAL"), message=e.pop("message", None), fix=e.pop("fix", None),
+                  exit_code=e.pop("exit_code", 2), problems=list(e.pop("problems", []) or []), extra=e)
+
+
+def _said(texts: Any) -> None:
+    """What rb says after a write it made (`data.warnings` on the command line), as an RBWarning at the line of code
+    that asked for the write: the first one outside this package."""
+    if not texts:
+        return
+    here = os.path.dirname(os.path.abspath(__file__))
+    frame, level = sys._getframe(1), 2
+    while frame is not None and os.path.dirname(os.path.abspath(frame.f_code.co_filename)) == here:
+        frame, level = frame.f_back, level + 1
+    for text in texts:
+        warnings.warn(str(text), RBWarning, stacklevel=level)
+
+
+def check_version(answered: Any) -> None:
+    """An opening answer says which rb gave it. A different version beside this package means a broken install."""
+    theirs = answered.get("rb") if isinstance(answered, dict) else None
+    if theirs is not None and theirs != __version__:
+        raise RBError("E_INTERNAL", message=f"rb {theirs} answered, and this Python package is rabbit-brain {__version__} ({binary()}).",
+                      fix=f"Reinstall so the two match: {REINSTALL}.", exit_code=EXIT_ENVIRONMENT)

rabbit_brain/errors.py

@@ -0,0 +1,71 @@
+"""Error codes: one table feeds `errors[]` in the JSON envelope, `rb docs`, and the tests.
+
+Exit codes: 0 ok · 1 a check failed (rb status --fail-on, rb spec verify, rb fmt --check, rb doctor) · 2 rb could not do what was asked, and says why
+· 3 a fault in rb itself, or an install that cannot start it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+EXIT_OK = 0
+EXIT_CHECK_FAILED = 1
+EXIT_INVALID = 2
+EXIT_ENVIRONMENT = 3
+
+# code -> (meaning, what to do)
+ERRORS: dict[str, tuple[str, str]] = {
+    "E_FILE_NOT_FOUND": ("A file given on the command line does not exist, or could not be read.", "Check the path; it is relative to the current directory."),
+    "E_NOT_AVAILABLE": ("This command, or the hosted service it needs, is not available in this version of rabbit-brain.", "The message says what to use instead. `rb --help` lists every command in this version."),
+    "E_WRITE_FAILED": ("A file could not be written.", "The message names the file and says why; check that its directory is one you can write to."),
+    "E_NO_PROJECT": ("No record here: no .rb/ in this directory or any directory above it.", "Run `rb init \"<the work's theme>\"` in the project root (it creates .rb/), or cd into a project that has one. In a project already under way, `rb docs --start` says how to record the work done."),
+    "E_PROJECT_EXISTS": ("A project already exists here or in a directory above, or in another worktree of this repository.", "Use it: `rb status`. One .rb/ per line of work; start another in a different directory."),
+    "E_YAML": ("The file is not Rabbit Brain YAML.", "The message says where and what to write instead. Rabbit Brain YAML is plain YAML without anchors, tags, dates or yes/no; `rb fmt <file>` rewrites a file that reads in the canonical form."),
+    "E_OBJECT_NOT_FOUND": ("No record with that id in this project.", "`rb status --json` lists every record; `rb show <experiment>` lists its variants, settings, criteria and runs; a setting is addressed as <experiment>/<name>."),
+    "E_OBJECT_INVALID": ("The values given do not make a valid record.", "Do what the message says; `rb <command> --help` lists the arguments and `rb schema <kind>` prints a record's shape (experiment, criterion, run, ...)."),
+    "E_FROZEN": ("The experiment is frozen, and this would change what it locked: a setting, a variant, what it varies, or a criterion.", "Run the same command with --amend --why \"<reason>\"; the change, the reason, who made it and the hash before and after are kept."),
+    "E_USAGE": ("The command line could not be parsed: an unknown option, a missing argument, or a value that is not allowed.", "`rb <command> --help` lists the arguments. A negative number is written as it is (--at-most -0.001); text that starts with '-' goes after --."),
+    "E_ACTOR_INVALID": ("RB_ACTOR is not in the form human:<name> or agent:<name>.", "Set it to human:<name> or agent:<name> (letters, digits and _.@+-), or unset it: rb then detects the agent runtime, or names the human from git."),
+    "E_SOURCE_UNRESOLVED": ("The source was read and does not state the value, or could not be read.", "The setting stays provisional. Check the path, key, line, quote or commit, or set the value the source actually states: `rb spec set <exp> <name> <value> --source <file#key>`."),
+    "E_SOURCE_OUTSIDE": ("The source is outside the project, so nobody else can check it.", "Copy it into the repository, commit it, and point --source at the copy."),
+    "E_SOURCE_UNVERIFIABLE": ("This source cannot be checked by reading a file: a url, a note, or a file source without a line or a quote.", "Point at a config key (file#key), a file line, a quote in a saved copy of the page, or a run's JSON (run:PATH#/pointer) that states the value; or someone vouches for it: `rb decide <exp>/<name> accept --why \"...\"`."),
+    "E_STATE_EDITED": ("A record under .rb/ was changed outside rb (its content edited, its file moved or deleted, or written by hand), and rb will not write over it. Comments and formatting are not changes.", "`rb doctor` lists every such file. `rb doctor --restore` puts back what rb last wrote; if the change is right, `rb doctor --adopt --why \"...\"` takes it as it stands, recorded as yours."),
+    "E_STATE_CORRUPT": ("A file under .rb/ is not a valid record.", "It was probably edited by hand or left mid-merge. `rb doctor` lists every such file and says where it breaks; `rb doctor --restore` puts back what rb last wrote."),
+    "E_STATE_NEWER": ("Part of this .rb/ was written by a newer rb than this one.", "Upgrade: `pip install --upgrade rabbit-brain`. Until then rb will not guess at state it cannot read, so gates fail closed with this reason."),
+    "E_BUNDLE_INVALID": ("The bundle is not a valid rb export, or its files do not match its manifest.", "Get a fresh copy from where it was published; every file must hash to what manifest.json records. rb export --with-record writes one."),
+    "E_HUB_REFUSED": ("The hub refused the request.", "The message carries the hub's reason and fix; the record on this machine is unchanged."),
+    "E_HUB_UNREACHABLE": ("The hub could not be reached, or what answered at its address is not the hub.", "Check the address (--hub, or RB_HUB_URL) and the network; nothing local was affected."),
+    "E_ADOPT_AUTHORITY": ("The edit changes who wrote or decided something, or through what, which an adoption must never launder into the record.", "`rb doctor --restore` puts the file back. If the authorship or decision is really wrong, make the change through rb as yourself, where it is logged as yours."),
+    "E_STALE_REVIEW": ("The files changed between the review and the adoption, so what was reviewed is not what would be adopted.", "Look again: `rb doctor` lists every file changed outside rb as it is now."),
+    "E_INTERNAL": ("A fault in rb itself, or an install that cannot run a part of it.", "Report it with the link its fix line gives (report_url under --json)."),
+}
+
+
+class RBWarning(UserWarning):
+    """What rb says after a write that went through, for the writer to act on: the SDK's `data.warnings`. A run's input
+    whose copy here is not the bytes it names gets one, and so do numbers that differ from the run already recorded with
+    the same output files, and an agent's new text that holds LaTeX."""
+
+
+@dataclass
+class RBError(Exception):
+    code: str
+    message: str | None = None
+    fix: str | None = None
+    exit_code: int = EXIT_INVALID
+    problems: list[str] = field(default_factory=list)
+    extra: dict = field(default_factory=dict)          # structured detail for agents
+
+    def __post_init__(self) -> None:
+        meaning, default_fix = ERRORS.get(self.code, ("Unexpected failure.", ERRORS["E_INTERNAL"][1]))
+        if self.message is None:
+            self.message = meaning
+        if self.fix is None:
+            self.fix = default_fix
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict:
+        d = {"code": self.code, "message": self.message, "fix": self.fix}
+        if self.problems:
+            d["problems"] = list(self.problems)
+        d.update(self.extra)
+        return d

rabbit_brain/models.py

@@ -0,0 +1,33 @@
+"""The envelope every command prints with --json, and the registry `rb schema` prints from."""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorItem(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    code: str
+    message: str
+    fix: Optional[str] = None
+
+
+class Envelope(BaseModel):
+    """What every command prints with --json: exactly one object on stdout."""
+    model_config = ConfigDict(extra="forbid")
+    ok: bool
+    rb_version: str
+    command: str
+    data: dict = Field(default_factory=dict)
+    errors: list[ErrorItem] = Field(default_factory=list)
+    next: list[str] = Field(default_factory=list)
+    rb_delta: list[dict] = Field(default_factory=list)   # in an agent session: what changed in the research since it last looked
+
+
+def _schemas() -> dict[str, type[BaseModel]]:
+    from .record import OBJECT_SCHEMAS
+    return {**OBJECT_SCHEMAS, "envelope": Envelope}
+
+
+SCHEMAS: dict[str, type[BaseModel]] = _schemas()