[jeffdupont]

Why

Nothing in CI notices when a public function's signature changes: a new required parameter, a removed parameter or a changed return type all pass today. That's a breaking change for callers, and after 1.0 it has to be deliberate.

What

• A committed API report for every public module, at packages/<package>/api-report/<module>.txt. That's every package root (10 reports, including opencode-agents), plus each module of launchdarkly_ai_server.experimental. The umbrella launchdarkly_ai_python re-exports the core package, so the core report covers it.
• Each report lists every name in __all__ with its full signature, one line per name. A class's constructor and public members are indented below it. Tags show async, classmethod, property and decorators. A re-export from another distribution is recorded as name = target [re-export].
• scripts/api_report.py generates the reports with griffe (griffelib, now an explicit dev dependency; it was already in the lockfile through openai-agents).
• tests/test_api_report.py fails while any report is out of date, so make test and CI catch a signature change whose report wasn't regenerated. It also checks the generator against a fixture package: functions, async, dataclasses, properties, classmethods, private members, external re-exports, a missing __all__, and an undefined name in __all__.
• make api-report writes the reports; make api-report-check checks them.
• .github/CODEOWNERS gives packages/*/api-report/ to @launchdarkly/team-ai-agents, so a public API change needs their approval of the report diff.
• AGENTS.md documents the workflow.

Tested

• uv run pytest: 2556 passed, 14 skipped. ruff check and ruff format --check are clean.
• A signature change fails the check. Adding a required strict: bool to inspect_config turns make api-report-check red, with the exact one-line diff and "run make api-report and commit the result". Reverting it turns it green again.

Not in this PR

These come in follow-up PRs:

• detecting breaking changes against the base branch and the last release, declared with ! in the PR title
• the usage-ID table as a data file
• the README experimental-features block
• the dir() ⊆ __all__ sweep for every module

🤖 Generated with Claude Code

---

Note

Overview
Introduces committed API reports as the public contract for every package module (and experimental submodules): each __all__ name and signature lives at packages/<package>/api-report/<module>.txt, generated by scripts/api_report.py (griffe) via make api-report, with make api-report-check and tests/test_api_report.py failing when reports are stale.

Adds griffelib as a dev dependency, CODEOWNERS review on packages/*/api-report/ for @launchdarkly/team-ai-agents, and AGENTS.md workflow docs. Initial report snapshots are committed for all handler packages plus launchdarkly_ai_server (including experimental skills/evaluations); the umbrella launchdarkly_ai_python package is skipped because it re-exports the core module.

^{Reviewed by Cursor Bugbot for commit cd40590. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0d155e6. Configure here.}