docs(sdk/py): refresh README for v0.10.0 daemon-mediated path#641
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Python SDK’s published README to steer adopters toward the canonical daemon-mediated signing workflow (per ADR-0022) and aligns examples/imports with the v0.10.0 surface.
Changes:
- Reworks the README Quick Start to: install → run
agent-receipts-daemon→ emit viaDaemonEmitter→ confirm viaagent-receipts verify, and moves in-process signing to an appendix. - Documents remote/HTTP delivery via
HttpEmitterandWalEmitter, including retain-and-replay WAL behavior and the sync vs fire-and-forget caveat. - Re-exports
ActionInputfrom the top-levelagent_receiptspackage and updates the “first run” contract test accordingly.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
sdk/py/README.md |
Refreshes Python SDK README to lead with daemon flow; adds remote collector delivery guidance; reorganizes in-process signing into an appendix; updates ecosystem links. |
sdk/py/src/agent_receipts/__init__.py |
Re-exports ActionInput from the top-level package via imports and __all__. |
sdk/py/tests/contracts/test_first_run.py |
Switches ActionInput import to the new top-level re-export. |
Refresh the PyPI README so Python adopters land on the canonical daemon-mediated signing path (ADR-0022) instead of the deprecated in-process flow: - Quick start now runs Install -> start daemon -> emit via DaemonEmitter -> confirm with `agent-receipts verify`, matching the site Quick Start. - In-process create/sign/verify moves to a tutorial-and-testing appendix carrying the ADR-0022 D2 "Not for production" note. - Document the v0.10.0 emitters package for the remote/HTTP path (HttpEmitter + WalEmitter retain-and-replay at-least-once delivery). - Re-export ActionInput from the top-level agent_receipts package and use the top-level import in the snippets and first-run contract test. - Point the Ecosystem table at the agent-receipts/ar monorepo, dropping the dead agent-receipts/sdk-py reference.
Restore the footgun warning: HttpEmitter in "fire-and-forget" mode returns before the POST lands, so WalEmitter clears the WAL entry prematurely and the at-least-once guarantee is lost. Use the default "sync" mode.
The "future milestone (M3)" note was stale — classify_tool_call, load_taxonomy_config, and resolve_action_type already ship and are exported from the top-level package. Replace it with an accurate description and a runnable snippet.
Address review feedback: "agent-receipts verify CLI" implied verify was the CLI name rather than a subcommand, and the in-process appendix link sat at the tail of a nested parenthetical. Reword to "the agent-receipts CLI (including the verify command)" and restructure the emitters intro with an em-dash so the link clause ends cleanly.
The daemon errors on non-linux/darwin GOOS (daemon.go: "Phase 1 supports linux and darwin only"), so "install it for your platform" could lead Windows users into a dead end. State the supported platforms explicitly.
The remote-collector example built the emitter and called replay() inside deliver(), implying a full WAL drain on every emission and contradicting the "call once at startup" guidance. Move construction + replay() to module scope so deliver() only emits.
ojongerius
force-pushed
the
claude/festive-davinci-492t8
branch
from
82e4dff to
5af420d
Compare
Comment on lines
+373
to
374
| | Component | Description | | ||
| |:---|:---| |
ojongerius
pushed a commit
that referenced
this pull request
May 26, 2026
main landed ADR-0023 (Canonical Go Module Path), colliding with this branch's ADR-0023 (Emit Failure Contract). Resolve by renumbering the emit failure contract to ADR-0024 across the ADR, all three SDKs, docs, changelogs, and the conformance vector. - docs/adr/README.md: list both ADR-0023 (go module path) and ADR-0024. - sdk/py/README.md: take main's restructured README (PR #641) and re-apply the surface-by-default emit wording to its new "Emit a receipt" section. - test_first_run.py: reconcile the auto-merged module docstring — the silent-drop test was renamed/flipped, and PY-P4 is decoupled from #599 per ADR-0024 §3. All three SDK suites pass after the merge. https://claude.ai/code/session_01KgF1mix4aL1nATwYGAeXSD
ojongerius
added a commit
that referenced
this pull request
May 28, 2026
main landed ADR-0023 (Canonical Go Module Path), colliding with this branch's ADR-0023 (Emit Failure Contract). Resolve by renumbering the emit failure contract to ADR-0024 across the ADR, all three SDKs, docs, changelogs, and the conformance vector. - docs/adr/README.md: list both ADR-0023 (go module path) and ADR-0024. - sdk/py/README.md: take main's restructured README (PR #641) and re-apply the surface-by-default emit wording to its new "Emit a receipt" section. - test_first_run.py: reconcile the auto-merged module docstring — the silent-drop test was renamed/flipped, and PY-P4 is decoupled from #599 per ADR-0024 §3. All three SDK suites pass after the merge.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refreshes the Python SDK README (the PyPI publish surface) so adopters land on the canonical daemon-mediated signing path per ADR-0022, matching the site Quick Start (#625) instead of being steered to the deprecated in-process flow.
Closes #630.
Changes
agent-receipts-daemon→ emit viaDaemonEmitter→ confirm withagent-receipts verify.HttpEmitter(sync vs fire-and-forget) andWalEmitter— including the v0.10.0 retain-and-replay at-least-once behaviour,FileWalvsMemoryWal, and the footgun that fire-and-forget breaks the WAL guarantee.agent-receipts verifyreferenced as the in-SDK confirmation path.ActionInputre-exported from the top-levelagent_receiptspackage; Quick Start snippet and the first-run contract test now use the top-level import.agent-receipts/armonorepo, dropping the deadagent-receipts/sdk-pyreference. (CI badge was already onagent-receipts/ar.)Acceptance (from #630)
agent-receipts verify)DaemonEmitterfor the local daemon pathHttpEmitter+WalEmitter(incl. WAL retain-replay)agent-receipts verifyActionInputfrom top-level and updates the Quick Start snippetagent-receipts/arTest plan
scripts/readme_snippets/check.py --lang py, 9 units clean)uv run pytest— 411 passed, 6 skippeduv run pyright src— 0 errors (strict)