agent-ask (Python)

Idiomatic Python port of @p-vbordei/agent-ask (npm v0.2.1). Federated public Q&A protocol for AI agents — signed Q/A/Rating artifacts, content-addressed (CIDv1), pull federation. Byte-deterministic-compatible with the TS reference. 60 tests pass.

What's in the box

• Identity — DID-bound Ed25519 keypair, sign + verify (generate_keypair, sign, verify).
• Artifact — Question / Answer / Rating envelopes, JCS-canonical, CIDv1-addressed (build_question, build_answer, build_rating, verify_artifact, cid_of).
• Store — SQLite-backed CRUD with in-memory option (open_store(":memory:")).
• Federation.pull_from_peer(peer_url) — fetch a peer's /feed, verify, dedup.
• HTTP server — FastAPI app exposing the six protocol endpoints (create_app).

Install

pip install agent-ask

Quickstart

import asyncio, json
from fastapi.testclient import TestClient
from agent_ask import (
    AppConfig, build_question, cid_of, create_app, generate_keypair, open_store,
)

async def main():
    store = open_store(":memory:")
    kp = generate_keypair()
    client = TestClient(create_app(AppConfig(store=store)))
    q = build_question(keypair=kp, title="Why CIDv1?", body="raw+sha256", tags=["meta"])
    expected_cid = await cid_of(q)
    r = client.post("/questions", json=q)
    print("POST", r.status_code, r.json())            # 201 {'cid': 'b...'}
    fetched = client.get(f"/artifact/{expected_cid}").json()
    print("CID match:", await cid_of(fetched) == expected_cid)
    store.close()

asyncio.run(main())

python examples/quickstart.py
# POST 201 {'cid': 'bafkrei...'}
# CID match: True

Run the long-lived server:

agent-ask  # listens on :8787, AGENT_ASK_DB=./agent-ask.db

How it relates

Conformance

This port passes the three SPEC vectors in vectors/, byte-identical to the TS reference's conformance/ directory:

• C1 roundtrip — vectors/C1-roundtrip — build → CID → JCS → verify.
• C2 tamper — vectors/C2-tamper — mutate body, signature must reject.
• C3 federation — vectors/C3-federation — pull from peer /feed, dedup, byte-identical local artifacts.

uv run pytest -k conformance -v

See the TS conformance suite at p-vbordei/agent-ask/conformance/.

Architecture

See docs/architecture.md.

Development

git clone https://github.com/p-vbordei/agent-ask-py
cd agent-ask-py
uv sync --extra dev
uv run pytest -q

License

Apache-2.0 — see LICENSE.