chap-pydantic-ai
Bridge between Pydantic AI and the CHAP Coordinator. When a run pauses for tool approval, the bridge puts each proposed call in front of a person as a CHAP review, waits for their decision, made at a CHAP desk, and hands Pydantic AI the results that carry it out: the call as proposed, the call with the person's arguments, or nothing. Every step is a hash-linked entry on the workspace's audit log.
The proposed call, its tool name, arguments and tool_call_id, is the
artefact under review. An edit of the arguments is an RFC 6902 patch on the
log, so the chain records what changed and why.
Install
pip install chap-pydantic-ai
Depends on chap-coordinator>=0.3.5. Install the extra to run a live
agent; request_results needs Pydantic AI 1.41 or later to build the
results it returns:
pip install "chap-pydantic-ai[pydantic-ai]"
Quick start
A tool marked requires_approval=True ends the run with a
DeferredToolRequests output. request_results opens a review of each
pending call and waits for the person's decisions; the run resumes with
the DeferredToolResults it returns. This runs offline: TestModel
proposes the call, and a thread stands in for Alice at her desk.
import threading
import time
from pydantic_ai import Agent, DeferredToolRequests
from pydantic_ai.models.test import TestModel
from chap_coordinator import Coordinator
from chap_pydantic_ai import ChapApprovalBridge
agent = Agent(TestModel(), output_type=[str, DeferredToolRequests]) # or "openai:gpt-4o"
@agent.tool_plain(requires_approval=True)
def transfer(amount: int, to: str) -> str:
return f"sent {amount} to {to}"
coord = Coordinator(enable_chain=True)
bridge = ChapApprovalBridge(
coord,
workspace="wsp_payments",
agent="agent:assistant#v1",
reviewer="human:alice@example.org",
)
def alice_at_her_desk() -> None:
"""What a CHAP desk does for Alice: it shows her each call put to her,
and she decides it in her own name. Here she caps the amount."""
def call(method, **params):
return coord.dispatch({"jsonrpc": "2.0", "id": method, "method": method, "params": {
"workspace": "wsp_payments", "from": "human:alice@example.org", **params}})
while not (submitted := call("audit.read", filter={"method": "task.complete"})["result"]["entries"]):
time.sleep(0.1)
review = submitted[0]["envelope"]["params"]
print("Alice is shown:", review["output"])
call("decide.override", task_id=review["task_id"], rationale="over the desk limit",
diff=[{"op": "replace", "path": "/args/amount", "value": 50}])
threading.Thread(target=alice_at_her_desk).start()
result = agent.run_sync("pay the invoice")
results = bridge.request_results(result.output)
result = agent.run_sync("pay the invoice", message_history=result.all_messages(),
deferred_tool_results=results)
print(result.output)
What the person's decision does
CHAP decision Pydantic AI resolution
--------------------------------- ---------------------------------
decide.approve ToolApproved()
decide.override of the arguments ToolApproved(override_args=...)
anything else, or no decision ToolDenied(message=...)
Each call is reviewed on its own task, one that requires review, so only a person's decision completes it. The run carries out exactly what was decided, or nothing:
- an approval runs the call as proposed, and an override runs it with the person's arguments, which Pydantic AI checks against the tool as it checks the model's: arguments the tool cannot take run nothing, and the model is told why;
- a rejection denies the call, with the person's note as the message the model reads;
- an edit to anything but the arguments, such as the tool name, or one that takes the arguments away, is denied: the run cannot carry it out;
- a call sent back for another, a revision, is denied with the person's note, and its task is declined: the model's next call is reviewed on a task of its own.
Each result's metadata names the CHAP task, the reviewer and the
outcome (approve, override, revise, reject, abstain, another ending, or
no decision), and the tool reads it as ctx.tool_call_metadata. The
reviews all open before the first wait, so the person sees them together.
The review is addressed to every person in the workspace.
Waiting, timeouts and async code
The bridge reads each task every two seconds (poll_seconds) for as long
as the reviewer takes, or until timeout seconds have passed. A call
nobody decided in time is denied, with a message saying so, and its review
is withdrawn, so no decision lands later on a call that never ran; calls
decided in time run as decided. Interrupted, the bridge withdraws every
review still open before the interrupt propagates.
In async code, await request_results_async:
results = await bridge.request_results_async(result.output, timeout=600)
It never holds up the event loop, and cancelling the awaiting task, as
asyncio.wait_for does on its timeout, withdraws the reviews still open.
At a desk, over HTTP
A desk such as chap-coordinator serve, or a project from
create-chap-app --template support-desk, keeps the coordinator in its own
process. The bridge reaches it with chap_coordinator.client; with
python desk.py running in a support-desk project:
import json
from chap_coordinator.client import HttpCoordinator, Participant
from chap_pydantic_ai import ChapApprovalBridge
config = json.load(open("chap.config.json"))
agent_uri = config["agent"]["uri"]
http = HttpCoordinator(f"http://127.0.0.1:{config['port']}/chap")
bridge = ChapApprovalBridge(
Participant(http, config["workspace"], agent_uri),
workspace=config["workspace"],
agent=agent_uri,
reviewer=config["humans"][0]["uri"],
)
results = bridge.request_results(requests) # the reviews open in the desk
The bridge joins the agent first, takes the desk's workspace as it is, and
reads each task with the desk's GET /api/tasks/<id>. Under the
template's "require_signatures": "humans" the agent calls unsigned and
each person signs at the desk. Where every call is signed, give the
Participant the agent's key, Signer.load_or_create(agent_uri, "keys").
Where people sign, the bridge joins nobody in a person's name and records
no decision for them: the reviews open once a person has joined from the
desk, and each decision is theirs, signed with their own key.
Recording a decision made elsewhere
Where people decide in your own interface, record_results(requests, results) records the resolutions your code made, one CHAP decision per
call, in the reviewer's name:
Pydantic AI resolution CHAP envelope
--------------------------------- ---------------------------------
True / ToolApproved() decide.approve
ToolApproved(override_args=...) decide.override (a diff of the args)
False / ToolDenied(message=...) decide.reject
It writes the agent's task.create and task.complete, then the
decide.* call in the reviewer's name. The coordinator holds that call and
nothing more: no signature from the person, and no sign that they saw
anything but what your code says. So each recorded decision carries
via: "bridge-record", which the log keeps and chap-analytics reads, and
approved_artefact_digest, the digest of the call as proposed. Record the
same results the run resumes with, so what is recorded is what runs. Where
people sign, nothing is recorded: record_results raises
PersonRequired, and they decide at the desk through request_results.
The approver, rationale, tags and the refine-or-replace signal ride in
results.metadata[tool_call_id]:
results.metadata = {call.tool_call_id: {
"approver": "human:sam@example.org",
"rationale": "over the desk limit; capped to 50",
"tags": ["limit-exceeded"],
"intent_preserved": True, # the same decision, a smaller amount
}}
record_decision(call, resolution, **signal) records one. An edit of the
arguments is a refining override (intent_preserved=true) by default: the
person kept the decision and changed its inputs. An edit that is a
different decision in disguise says so with intent_preserved=False. The
approver is a person, a human: URI; the bridge's reviewer by default.
What you get in the audit chain
The quick start yields the following, every entry carrying prev_hash:
seq=0 workspace.create
seq=1 participant.join agent:assistant#v1
seq=2 participant.join human:alice@example.org
seq=3 task.create agent:assistant#v1 kind=transfer review_required=true
seq=4 task.complete agent:assistant#v1 the call; opens the review
seq=5 decide.override human:alice@example.org diff=[{op:replace, path:/args/amount, value:50}]
The chain verifies externally, or anchors to a SCITT transparency service
with the audit-scitt/1.0 profile.
Upgrading from 0.3.4
- Lead with the desk:
request_resultsopens the reviews and waits for the person's decisions, as the quick start shows.record_resultsis the recording mode above, refused where people sign. - A recorded decision opens its review on a task that requires one, with
task.createthentask.complete, and noreview.request; it carriesvia: "bridge-record"and the call's digest. The approver must be a person, ahuman:URI. - The bridge joins the agent when it is made. Where nobody signs, the reviewer joins when the first review opens; where people sign, the bridge joins no person.
- The bridge checks its parties when it is made, and raises
ValueErrorwhen the agent is not anagent:orservice:URI, when the reviewer is not a person (ahuman:URI), when aParticipantgiven as the coordinator calls as someone other than the agent, and when the workspace exists withoutcore/1.0andreview/1.0. - A refusal raises
chap_coordinator.client.ChapError, exported here asChapError;ChapBridgeErrornames the same class. Its message reads<method>: <message> (<code>).
Example
examples/01-approve-edit-deny.py drives one approval-gated tool through
a desk's decisions, an approval, two edits and a denial, using Pydantic
AI's TestModel (offline, no API key), then records a decision made in the
script's own interface, and prints the chain. tests/test_agent.py runs
request_results with a real agent, against an in-process desk and a desk
server where people sign.
Compatibility
chap-coordinator0.3.5 and laterpydantic-ai1.41 and later (optional; tested with pydantic-ai-slim 1.41.0 and pydantic-ai 2.54.0)- Python 3.10, 3.11, 3.12, 3.13
License
Apache 2.0. See LICENSE.
Metadata
Release files for chap-pydantic-ai 0.3.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chap_pydantic_ai-0.3.5.tar.gz | 23.4 kB | Without provenance | Details for chap_pydantic_ai-0.3.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chap_pydantic_ai-0.3.5-py3-none-any.whl | Python 3 | none | any | Details for chap_pydantic_ai-0.3.5-py3-none-any.whl |
Total release size: 38.3 kB
Release files / chap_pydantic_ai-0.3.5.tar.gz
| Download URL | chap_pydantic_ai-0.3.5.tar.gz |
|---|---|
| Size | 23.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb1f1702d65881a921b8c8b3594959bf87bf2140dcc5d36b46a42e6698752b27
|
|
BLAKE2b-256 checksum How to use checksums |
9d2ab02f461e129afed632bcd0ec37589a1127ee0052f356cbab5b08d2d0fb37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Release files / chap_pydantic_ai-0.3.5-py3-none-any.whl
| Download URL | chap_pydantic_ai-0.3.5-py3-none-any.whl |
|---|---|
| Size | 14.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ae5a46c388e1eb7aaa57cf802238601af563c93329d4220a4b138156bb309701
|
|
BLAKE2b-256 checksum How to use checksums |
e847842159dd0e8978e7ab576bc8875f2a77456f1e6502238d87b65f5ed10188
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Security for chap-pydantic-ai 0.3.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.