brooder 0.1.0__tar.gz

brooder-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**To reproduce**
+Steps / minimal agent script + the exact `brooder` command.
+
+**Expected behavior**
+What you expected instead.
+
+**Environment**
+- brooder version (`brooder --version`):
+- Python version:
+- OS:
+
+**Diff / output**
+Paste the relevant `brooder` output (use `-v` for debug logs).

brooder-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an idea for Brooder
+title: "[feat] "
+labels: enhancement
+---
+
+**Problem**
+What are you trying to do that Brooder doesn't support today?
+
+**Proposed solution**
+What you'd like to see (a command, a config option, an integration…).
+
+**Alternatives**
+Anything you've tried or considered.

brooder-0.1.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  # Keep the GitHub Actions used by ci.yml / release.yml / the composite action current.
+  # Grouped into a single PR so Dependabot doesn't open one PR per action.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]
+  # Keep Python dependencies current (grouped to avoid PR noise).
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: deps
+    groups:
+      python-deps:
+        patterns: ["*"]

brooder-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What & why
+
+Briefly describe the change and the motivation.
+
+## Checklist
+
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `mypy` passes (strict)
+- [ ] `pytest` passes; new/changed behavior has a test
+- [ ] Updated `CHANGELOG.md` under **Unreleased** if user-facing
+- [ ] Docs/README updated if needed

brooder-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy (strict)
+        run: mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: Unit tests
+        run: pytest --cov=brooder --cov-report=term-missing
+      - name: Smoke test the CLI (record then re-run the stable agent)
+        run: |
+          brooder record examples/stable_agent.py
+          brooder run --model gpt-5-new examples/stable_agent.py
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - name: Build docs
+        run: mkdocs build
+
+  licenses:
+    # Keep the Apache-2.0 core free of strong copyleft (GPL/AGPL/SSPL). LGPL is allowed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install runtime deps only
+        run: python -m pip install .
+      - name: Check dependency licenses
+        run: |
+          python -m pip install pip-licenses
+          echo "Dependency licenses:"
+          pip-licenses --format=markdown
+          copyleft=$(pip-licenses --format=csv \
+            | grep -Eiv 'lgpl|lesser general public' \
+            | grep -Ei 'gpl|affero|sspl|server side public' || true)
+          if [ -n "$copyleft" ]; then
+            echo "::error::strong copyleft dependency detected (Apache-2.0 core must stay clean):"
+            echo "$copyleft"
+            exit 1
+          fi
+          echo "OK: no strong copyleft in dependencies."

brooder-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+# Publish to PyPI on a version tag, via PyPI Trusted Publishing (OIDC) — no API tokens.
+#
+# Requires a PyPI Trusted Publisher configured for this repo with:
+#   workflow = release.yml   environment = pypi
+# (Set it at https://pypi.org/manage/project/brooder/settings/publishing/ once the project exists,
+#  or as a pending publisher before the first release.)
+#
+# Release flow:
+#   1. bump `version` in pyproject.toml
+#   2. git tag -a vX.Y.Z -m "brooder X.Y.Z" && git push origin vX.Y.Z
+#   3. (major tag for the Action) git tag -f vX && git push -f origin vX
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*" # semantic version tags only (the moving `v1` Action tag must not trigger a publish)
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Validate metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi # must match the PyPI Trusted Publisher's environment
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

brooder-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# ── Brooder local artifacts ────────────────────────────────────────────────
+# Baselines under .brooder/baselines/ ARE committed (they're your golden records).
+# Everything else Brooder writes locally is not.
+.brooder/runs/
+.brooder/results/
+.brooder/cache/
+
+# ── Python ──────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ── Virtual environments ────────────────────────────────────────────────────
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# ── Environment / secrets ───────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# ── Testing / typing / linting caches ───────────────────────────────────────
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+.tox/
+.nox/
+.cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# ── Build backends / packaging ──────────────────────────────────────────────
+pip-wheel-metadata/
+.pdm-python
+.pdm-build/
+
+# ── Docs (MkDocs output) ────────────────────────────────────────────────────
+site/
+
+# ── Node / TypeScript SDK (future) ──────────────────────────────────────────
+node_modules/
+npm-debug.log*
+yarn-error.log*
+*.tsbuildinfo
+
+# ── OS ──────────────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ── Editors / IDEs ──────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.claude/

brooder-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# See https://pre-commit.com. Install with:  pre-commit install
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies:
+          - pydantic>=2.5
+          - types-PyYAML
+          - rich
+          - typer

brooder-0.1.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-02
+
+First public release.
+
+### Added
+- Python SDK: `@brooder.record` decorator and `brooder.tool_call(...)` capture.
+- CLI: `init`, `record`, `run`, `diff`, `approve`, `ci`, `migrate`, plus `--version` / `-v`.
+- Structural behavioral diff engine (tool-call sequence, args, final output) + stability score.
+- **Model Migration Report** (`brooder migrate --from X --to Y`).
+- **Flakiness detection** (`brooder run --runs N`) — runs each case N times, verdict `FLAKY`.
+- **Pluggable output judge** (`judge: exact | llm`) so equivalent wording isn't flagged as a regression.
+- **Provider auto-capture** (`brooder.instrument(client)`) — records the model's tool calls
+  automatically for OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, and Google (Gemini/Vertex).
+- **First-class trajectory (phase 1)** — a `Run` captures an ordered `Step` trajectory
+  (TURN / TOOL / FINAL), exposed via `run.turns` and `run.step_count`. New `brooder.turn()` marks
+  a model turn; provider auto-capture emits turns and tool steps.
+- **Trajectory-aware diff (phase 2)** — the diff engine LCS-aligns the baseline and current
+  trajectories, so an added, dropped, or reordered step is reported at the exact position where the
+  path diverged (`trajectory[N]`) instead of cascading. Turn- and step-counts surface as
+  `trajectory.turns` / `trajectory.steps` signals, the report leads with a
+  *"path diverged at step N"* headline, and the summary table gains a Trajectory column (so the
+  Model Migration Report shows loop/turn regressions at a glance).
+- **Trajectory guardrails & observations (phase 3)** — `trajectory.max_steps` aborts a run that
+  exceeds the cap and records it as a `trajectory.runaway` regression, so infinite loops fail fast
+  instead of hanging. An agent that returns without a final answer is captured as a diffable
+  `trajectory.gave_up` terminal. Tool observations (results) can be diffed through the judge by
+  opting in with `trajectory.observations: true` — off by default because tool output is noisy.
+- **Adapter capture core (P4a)** — a `RunHandle` + external-id registry (`brooder.recorder.open_run`
+  / `get_run`) that lets framework adapters open a run driven by the framework's own events (a trace
+  or session), append steps as they arrive — possibly out of order and from other threads — and
+  finish it, all feeding the same `Step` trajectory. `@record` and provider auto-capture now run on
+  this one lifecycle. Adapter-owned runs *flag* a `max_steps` runaway instead of raising (they can't
+  abort the framework's loop). Foundation for the native framework adapters
+  (see [design/framework-adapters.md](design/framework-adapters.md)).
+- **OpenTelemetry GenAI ingestion (P4b)** — `brooder.integrations.otel.BrooderSpanProcessor`, a
+  duck-typed OTel `SpanProcessor` that turns the GenAI/agent spans your stack already emits into a
+  trajectory (inference → TURN, `execute_tool` → TOOL, the agent-root's input/output → case identity
+  and FINAL). One adapter covers **LangGraph / CrewAI / AutoGen** and slots into existing OTel
+  pipelines. Spans are buffered per trace and sorted by start time at finalize, so out-of-order /
+  cross-thread delivery is handled; incomplete traces drain on `force_flush` / `shutdown`. Tool
+  *names* are always captured; when content capture is off it degrades gracefully and warns once
+  (set a `brooder.case_id` span attribute for a stable case id). Importing the module does not
+  require `opentelemetry` to be installed.
+- **Claude Agent SDK capture (P4c)** — `brooder.claude_agent_hooks(agent=...)` returns a hooks
+  mapping for `ClaudeAgentOptions(hooks=...)` that records the agent's tool trajectory with no manual
+  `tool_call`. `UserPromptSubmit` opens a run (the prompt is the case identity), `PostToolUse` /
+  `PostToolUseFailure` become TOOL steps, and `Stop` finalizes. Each user turn in a session is one
+  case. Since the Python SDK's `Stop` hook carries no final text, capture the answer with the
+  optional `brooder.integrations.claude_agent.record_output(session_id, result)` (fed from the
+  `ResultMessage` stream); the trajectory — the core diff signal — is captured regardless.
+- **OpenAI Agents SDK capture (P4d)** — `brooder.integrations.openai_agents.install(agent=...)`
+  registers a trace processor (appended, so the SDK's default exporter keeps working; no OpenAI API
+  key needed to capture) that maps the SDK's spans into a trajectory: `generation`/`response` → TURN,
+  `function` → TOOL, `handoff` → a `handoff` TOOL step (`{from, to}`), `guardrail` → a `guardrail`
+  TOOL step (`{name, triggered}`). Spans are buffered per trace and sorted by `started_at` at
+  `on_trace_end` (handling parallel tool calls / concurrent agents); the initial input and final
+  answer are recovered from the response spans. Importing the module does not require `openai-agents`.
+- **LangChain / LangGraph capture (P4e)** — `brooder.integrations.langchain.callback_handler(agent=...)`
+  returns a `BaseCallbackHandler` for `config={"callbacks": [handler]}` that records the trajectory
+  with no manual `tool_call` and no OpenTelemetry wiring (covers LangGraph, which runs on LangChain's
+  callbacks). The root `on_chain_start` opens a run (its input is the case identity), model starts →
+  TURN steps, `on_tool_start`+`on_tool_end` → TOOL steps (paired by the tool's `run_id`, with
+  `on_tool_error` captured too), and the root `on_chain_end` finalizes. Nested calls are mapped to
+  their root run; capture is thread-safe (sync handlers can run on worker threads during async runs).
+  The capture logic imports without `langchain-core`; only building the handler needs it.
+- **Async auto-capture** — `@brooder.record` and `brooder.instrument(...)` now work on
+  `async def` agents and async clients (`AsyncOpenAI`, `AsyncAzureOpenAI`, `AsyncAnthropic`, and
+  Google's `generate_content_async`). The active-run context stays bound across the agent's `await`
+  points (and into child tasks), so tool calls are captured just like the sync path. (Async Bedrock
+  via aioboto3 is not covered yet.)
+- **Machine-readable output** — `brooder run` / `ci` / `diff` accept `--format table|json|markdown`
+  (with `--json` as a shortcut). JSON emits a stable, versioned summary (per-case verdict, stability,
+  changes, and aggregate counts) for CI to parse; Markdown renders a PR-comment-ready table + diff.
+  Exit codes are unchanged.
+- **OTLP metric emission** — set `metrics.otlp_endpoint` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) and each
+  run emits a snapshot of gauges (`brooder.cases.*`, `brooder.stability.mean`) over a single OTLP
+  exporter — one emitter reaching Datadog / Grafana / Honeycomb / CloudWatch. Duck-typed and
+  best-effort: it warns once and no-ops if the `otel` extra isn't installed, and never fails a run.
+- **GitHub Action** — a composite action (`action.yml`, usage in
+  [examples/github-action.yml](examples/github-action.yml)) that runs `brooder ci` on pull requests,
+  upserts a comment with the behavioral diff, and fails the check on regression.
+- Offline example agents (`stable_agent`, `regressing_agent`, `flaky_agent`, multi-step
+  `loop_agent`) — no API keys required.
+- Strict typing (`py.typed`), atomic storage writes, typed config, structured logging.
+- Tooling: ruff, mypy (strict), pre-commit, pytest + coverage, CI matrix (3.10–3.12).
+
+[Unreleased]: https://github.com/agentbrooder/brooder/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/agentbrooder/brooder/releases/tag/v0.1.0

brooder-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to Brooder
+
+Thanks for helping build the safety net for AI agents. This project is being built in public and
+early — issues, ideas, and PRs are all welcome.
+
+## Dev setup
+
+```bash
+git clone https://github.com/agentbrooder/brooder && cd brooder
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Try the demo
+
+```bash
+brooder migrate --from gpt-4o --to gpt-5-new examples/regressing_agent.py
+```
+
+## Where things live
+
+- `src/brooder/recorder.py` — the `@record` decorator + `tool_call` capture.
+- `src/brooder/diffing.py` — the behavioral diff engine (the core).
+- `src/brooder/cli.py` — the `brooder` commands.
+- `examples/` — runnable demo agents (offline, no API keys).
+
+## Good first issues
+
+- Add an OpenAI or Anthropic provider wrapper so tool calls are captured automatically.
+- Add a semantic (LLM-judge) diff mode behind `judge: llm` in config.
+- Add flakiness scoring (run each case N times, report variance).
+
+## Docs
+
+The API docs are generated from docstrings with MkDocs + mkdocstrings.
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve       # live preview at http://127.0.0.1:8000
+mkdocs build       # what CI runs
+```
+
+Public modules, classes, and functions use **Google-style docstrings** (Args/Returns/Raises),
+enforced by ruff's `D` rules. New public API without a docstring will fail lint.
+
+## Signing your commits (DCO)
+
+Contributions are accepted under the [Developer Certificate of Origin](DCO). Certify that you wrote
+(or have the right to submit) your change by signing off each commit:
+
+```bash
+git commit -s -m "your message"
+```
+
+This appends a `Signed-off-by: Your Name <you@example.com>` line. No paperwork, no account — just the
+sign-off. See [LICENSING.md](LICENSING.md) for the full licensing picture.
+
+## Guidelines
+
+- Keep the core engine model-agnostic and runnable offline (the example agents must never require keys).
+- Prefer small, reviewable PRs. Add a test in `tests/` for engine changes.
+- Public API gets a Google-style docstring (ruff `D` enforces it; docs generate from them).
+- Be kind. We're all figuring agents out together.

brooder-0.1.0/DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.