chap-llama-index
Bridge between LlamaIndex Workflows and the CHAP Coordinator. When a workflow step pauses for human input, the bridge puts the proposed output in front of a person as a CHAP review, waits for their decision, made at a CHAP desk, and answers the workflow with what they decided. Every step is a hash-linked entry on the workspace's audit log.
The proposed output on the InputRequiredEvent, its proposed field or
else all of its fields, is the artefact under review; an event that
proposes nothing raises ValueError, since nobody can approve what they
were not shown. The HumanResponseEvent the bridge returns carries the
decision.
An edit is an RFC 6902 patch on the log, so the chain records what changed
and why.
Install
pip install chap-llama-index
Depends on chap-coordinator>=0.3.5. Install the extra to run a live
workflow; request_response needs it to build the event it returns:
pip install "chap-llama-index[llama-index]"
Quick start
A step returns an InputRequiredEvent and waits; a second step consumes
the HumanResponseEvent that answers it. The driver that streams the
workflow's events hands each pause to request_response, which opens a
review of the proposed output and waits for the person's decision. This
runs offline: a task on the event loop stands in for Alice at her desk.
import asyncio
from workflows import Context, Workflow, step
from workflows.events import HumanResponseEvent, InputRequiredEvent, StartEvent, StopEvent
from chap_coordinator import Coordinator
from chap_llama_index import ChapHitlBridge
coord = Coordinator(enable_chain=True)
bridge = ChapHitlBridge(
coord,
workspace="wsp_payments",
agent="agent:writer#v1",
reviewer="human:alice@example.org",
)
class PaymentReview(Workflow):
@step
async def propose(self, ctx: Context, ev: StartEvent) -> InputRequiredEvent:
return InputRequiredEvent(prefix="approve payment? ", proposed={"amount": 100, "to": "acct-9"})
@step
async def pay(self, ctx: Context, ev: HumanResponseEvent) -> StopEvent:
if ev.get("decision") in ("approve", "override"):
return StopEvent(result=f"paid {ev.get('response')}")
return StopEvent(result=f"not paid: {ev.get('response')}")
async def alice_at_her_desk() -> None:
"""What a CHAP desk does for Alice: it shows her the output 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"]):
await asyncio.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": "/amount", "value": 50}])
async def main() -> None:
desk = asyncio.create_task(alice_at_her_desk())
handler = PaymentReview(timeout=None).run()
async for event in handler.stream_events():
if isinstance(event, InputRequiredEvent):
handler.ctx.send_event(await bridge.request_response(event))
print(await handler)
await desk
asyncio.run(main())
What the response carries
The review is on a task that requires review, so only a person's decision
completes it. The HumanResponseEvent carries:
response: the output as decided, the person's version after an edit; or their note when nothing was approved;decision:approve,override,revise(sent back for another),reject,abstain, or another ending of the review;user_name,rationaleandtags: who decided, their note and tags;chap_task_id: the CHAP task;- every other field of the
InputRequiredEvent, so a step that waits withctx.wait_for_event(HumanResponseEvent, requirements={"request_id": rid})receives the response to its own request.
A workflow's own timeout, 45 seconds by default, counts the time the
person takes to decide: give it timeout=None, or one long enough.
A revision
When the person sends the output back for another, decision is
revise. Propose the next output on the same task by passing the
response's chap_task_id back, and it opens the next round of the same
review:
async for event in handler.stream_events():
if isinstance(event, InputRequiredEvent):
response = await bridge.request_response(event, task_id=event.get("chap_task_id"))
handler.ctx.send_event(response)
where the step that proposes again copies chap_task_id from the
revise response onto its new InputRequiredEvent.
Waiting, timeouts and cancellation
The bridge reads the task every two seconds (poll_seconds) for as long
as the reviewer takes, or until timeout seconds have passed, and never
holds up the event loop. After the timeout it withdraws the review, so no
decision lands later on output the workflow did not use, and raises
TimeoutError. Cancelling the awaiting task withdraws the review the same
way.
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:
import json
from chap_coordinator.client import HttpCoordinator, Participant
from chap_llama_index import ChapHitlBridge
config = json.load(open("chap.config.json"))
agent_uri = config["agent"]["uri"]
http = HttpCoordinator(f"http://127.0.0.1:{config['port']}/chap")
bridge = ChapHitlBridge(
Participant(http, config["workspace"], agent_uri),
workspace=config["workspace"],
agent=agent_uri,
reviewer=config["humans"][0]["uri"],
)
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 review opens 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_decision(input_event, response_event, decision=...) records the decision your code made, in the
reviewer's name:
decision CHAP envelope
-------- ---------------------------
approve decide.approve
override decide.override (proposed vs returned, as a diff)
reject decide.reject
Workflows events carry no approve, edit or reject signal, so decision
says which it was: the bridge never guesses it from the response text.
proposed, returned, rationale, tags, intent_preserved and
approver default to fields of the events (event.get(...)), and each can
be given per call. An override is a refining edit (intent_preserved=true)
by default; set it false for a substituting edit.
It writes the agent's task.create and task.complete, then the
decide.* call in the approver's name: a person's human: URI, the
response's user_name or else the bridge's reviewer. 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 proposed output.
Where people sign, nothing is recorded: record_decision raises
PersonRequired, and they decide at the desk through request_response.
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:writer#v1
seq=2 participant.join human:alice@example.org
seq=3 task.create agent:writer#v1 kind=workflow_output review_required=true
seq=4 task.complete agent:writer#v1 the output; opens the review
seq=5 decide.override human:alice@example.org diff=[{op:replace, path:/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_responseopens the review and waits for the person's decision, as the quick start shows.record_decisionis the recording mode above, refused where people sign. decisionon the response says how the review ended:revise,abstainand other endings no longer read asreject. The response carries the input event's fields.- 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 output'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-reject.py drives one paused workflow through a
desk's decisions, an approval, a refining edit, a substituting edit, a
rejection and a revision, against real llama-index-workflows, then
records a decision made in the script's own interface, and prints the
chain. tests/test_workflow.py runs request_response in real workflows,
against an in-process desk and a desk server where people sign.
Compatibility
chap-coordinator0.3.5 and laterllama-index-workflows1.x and 2.x (optional; tested with llama-index-workflows 1.0.0 and 2.26.1)- Python 3.10, 3.11, 3.12, 3.13
License
Apache 2.0. See LICENSE.
Metadata
Release files for chap-llama-index 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_llama_index-0.3.5.tar.gz | 18.4 kB | Without provenance | Details for chap_llama_index-0.3.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chap_llama_index-0.3.5-py3-none-any.whl | Python 3 | none | any | Details for chap_llama_index-0.3.5-py3-none-any.whl |
Total release size: 32.3 kB
Release files / chap_llama_index-0.3.5.tar.gz
| Download URL | chap_llama_index-0.3.5.tar.gz |
|---|---|
| Size | 18.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
415cbfea56621bf0025952b0e94def349f173411dc2007aa4703d6bb1f42c0af
|
|
BLAKE2b-256 checksum How to use checksums |
811ffa9274e82fdb02bec59cccb140410cc99d118d66f3d860e75c2f278c50fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Release files / chap_llama_index-0.3.5-py3-none-any.whl
| Download URL | chap_llama_index-0.3.5-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b645c4541a3133cc35e5ca917c97d34d1aa453ec4e38c31eb2282fd1b83ccfbc
|
|
BLAKE2b-256 checksum How to use checksums |
58b2d7e8a73aa6181336d538b82c4249a19eeae9fb97d52b436a4d542bf7b299
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Security for chap-llama-index 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.