pramana-sdk 0.0.1__tar.gz

pramana_sdk-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.pramana/
+.pytest_cache/
+web/node_modules/
+web/dist/
+# Secrets. The trailing slash this line used to have (`.env/`) matched only a
+# *directory* named .env, never the file — which is how .env ended up committed
+# in a1434d1 with a live Postgres password and S3 keys in it. Adding it here
+# does not remove it from history: those credentials must be rotated, and the
+# commit purged, separately.
+.env
+.env.*
+!.env.example

pramana_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: pramana-sdk
+Version: 0.0.1
+Requires-Python: >=3.12
+Requires-Dist: pramana-core
+Requires-Dist: pramana-proto
+Requires-Dist: pramana-store
+Requires-Dist: requests>=2.32
+Requires-Dist: zstandard>=0.22

pramana_sdk-0.0.1/examples/demo_walkthrough.py

@@ -0,0 +1,658 @@
+"""One-command demo dataset — run this before showing Pramana to anyone.
+
+Records four traces against a live pramana-ingest, mints evidence bundles for
+the clean ones, and prints exactly what to click through.
+
+The flagship trace is a **five-agent loan underwriting run**: a supervisor that
+fans work out to four specialists, each with its own tool calls, then
+synthesizes a decision. That shape was chosen because it is what real agentic
+systems actually look like — a hub with specialists, not two agents passing a
+baton — and because lending is *regulated*: a lender must be able to explain a
+declined application. "Here is provably what the system did, and why" is the
+thing Pramana sells, so the demo data should be a case where somebody genuinely
+needs it.
+
+Uses fake vendor clients shaped like the real OpenAI SDK (no OPENAI_API_KEY
+needed) so this runs anywhere, offline, in a few seconds.
+
+    PRAMANA_TENANT_ID=demo uv run --package pramana-sdk python sdk-python/examples/demo_walkthrough.py
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from pathlib import Path
+
+import requests
+from pramana import context, interceptor, messaging, runtime
+from pramana.context import TraceContext
+from pramana.sinks.http import HttpSink
+from pramana_proto.v1.event_pb2 import LLM_CALL, TOOL_EXEC
+from pramana_store.blob import LocalBlobStore, blob_store_factory_from_env
+from pramana_store.postgres import PostgresEventRepository
+
+TENANT_ID = os.environ.get("PRAMANA_TENANT_ID", "demo")
+INGEST_URL = os.environ.get("PRAMANA_INGEST_URL", "http://localhost:8081/v1/events:batch")
+API_URL = os.environ.get("PRAMANA_API_URL", "http://localhost:8082")
+CONNINFO = os.environ.get("PRAMANA_PG", "postgresql://postgres@127.0.0.1:55432/pramana")
+BLOB_DIR = Path(os.environ.get("PRAMANA_BLOB_DIR", ".pramana/blobs"))
+DEMO_KEYS_FILE = Path(".pramana/demo-keys.txt")
+
+
+def _engineer_key() -> str | None:
+    if not DEMO_KEYS_FILE.exists():
+        return None
+    for line in DEMO_KEYS_FILE.read_text().splitlines():
+        if line.startswith("engineer="):
+            return line.split("=", 1)[1].strip()
+    return None
+
+
+def _require_engineer_key() -> str:
+    """Ingest authenticates every write now (docs/plan.md §15), so this demo
+    cannot record without a key. Fail with the command that mints one rather
+    than letting every batch come back 401 from a background thread.
+    """
+    key = os.environ.get("PRAMANA_API_KEY") or _engineer_key()
+    if not key:
+        raise SystemExit(
+            f"No engineer API key found. Set PRAMANA_API_KEY, or create {DEMO_KEYS_FILE} by running:\n"
+            "  uv run --package pramana-api python deploy/seed_demo.py"
+        )
+    return key
+
+
+def approx_tokens(*texts: str) -> int:
+    return max(1, round(sum(len(t.split()) for t in texts) * 1.3))
+
+
+def latency_for(text: str, base: float = 0.1) -> float:
+    return base + min(len(text) * 0.001, 0.6)  # kept short: this runs before every demo
+
+
+# Call-site depth matters here, and it is the one subtle thing in this file.
+#
+# `capture_call_site` walks a fixed number of frames up to find "the line the
+# user called from". In a real integration that works out because
+# `pramana.instrument(client)` patches the vendor method directly, so there is
+# exactly one wrapper frame. These helpers stand in for that wrapper — which is
+# why `llm_call`/`tool_call` call `intercepted_call` *directly*: one frame, so
+# the captured call site is the line in the scenario function below. Two
+# different lines get two different call sites, and the same line called twice
+# gets one call site with ordinals 0 and 1.
+#
+# `_intercept` deliberately adds one more frame, for the opposite reason — see
+# `call_policy_decision`.
+def _intercept(fn, **kwargs):
+    return interceptor.intercepted_call(fn, **kwargs)
+
+
+def make_wire():
+    box: dict = {}
+
+    def send(envelope):
+        box["envelope"] = envelope
+        return "ack"
+
+    def receive():
+        return box["envelope"]
+
+    return send, receive
+
+
+def start_recording(tenant_id: str):
+    from pramana.buffer import EventBuffer
+    from pramana.collector import Collector
+    from pramana.spool import Spooler
+
+    store = LocalBlobStore(BLOB_DIR, tenant_id=tenant_id)
+    # Without a spooler, Collector.flush_once() re-raises on any transient
+    # failure (a slow/unreachable sink) instead of retrying — which kills
+    # the background thread silently and drops whatever was still queued.
+    # pramana.init() always configures one for exactly this reason; this
+    # hand-rolled setup needs to match it.
+    spooler = Spooler(BLOB_DIR.parent / "spool" / f"{tenant_id}.spool")
+    buffer = EventBuffer(spooler=spooler)
+    collector = Collector(
+        buffer,
+        HttpSink(INGEST_URL, tenant_id=tenant_id, api_key=_require_engineer_key()),
+        spooler=spooler,
+        blob_store=store,
+    )
+    runtime.configure(tenant_id=tenant_id, blob_store=store, buffer=buffer, collector=collector)
+    collector.start()
+    return collector
+
+
+def llm_call(model, messages, content, extra_attrs=None):
+    text = " ".join(m["content"] for m in messages)
+
+    def fn():
+        time.sleep(latency_for(content))
+        return {"choices": [{"message": {"content": content}}]}
+
+    attrs = {
+        "model": model,
+        "vendor": "openai",
+        "tokens_in": str(approx_tokens(text)),
+        "tokens_out": str(approx_tokens(content)),
+        **(extra_attrs or {}),
+    }
+    return interceptor.intercepted_call(
+        fn, raw_input={"model": model, "messages": messages}, kind=LLM_CALL, attrs=attrs
+    )
+
+
+def tool_call(name, args, result, latency: float = 0.05):
+    def fn():
+        time.sleep(latency)
+        return result
+
+    # `tool` in attrs, not just as a payload key: attrs is the documented
+    # extension point (docs/plan.md §3.1) and it is what the trace views can
+    # read without fetching every payload, so the timeline can say
+    # "bureau_pull" instead of "TOOL_EXEC".
+    return interceptor.intercepted_call(
+        fn, raw_input={name: args}, kind=TOOL_EXEC, attrs={"tool": name}
+    )
+
+
+def send_to(from_ctx, to_ctx, payload, to_agent, from_agent):
+    """One directed handoff: MSG_SEND on the sender, MSG_RECV on the receiver.
+
+    Returns the delivered payload. The vector clock rides along inside the
+    envelope, so `pramana_core.sequencer.total_order` can reconstruct causal
+    order across all five lanes from the clocks alone — never wall time.
+    """
+    send, receive = make_wire()
+    context.set_current(from_ctx)
+    messaging.send_message(send, payload, to_agent_id=to_agent)
+    context.set_current(to_ctx)
+    return messaging.receive_message(receive, from_agent_id=from_agent)
+
+
+# --------------------------------------------------------------------------
+# Trace 1 — five-agent loan underwriting
+# --------------------------------------------------------------------------
+
+APPLICATION = {
+    "application_id": "LN-2026-08841",
+    "applicant": "R. Okonkwo",
+    "requested_amount_usd": 28000,
+    "purpose": "used vehicle purchase",
+    "term_months": 60,
+    "stated_annual_income_usd": 74000,
+    "employment": "Full-time, 3y 2m at current employer",
+}
+
+POLICY_PROMPT = {
+    "role": "system",
+    "content": (
+        "You are the underwriting policy engine. Approve only if ALL hold: FICO >= 660, "
+        "debt-to-income after the new loan <= 43%, no sanctions or PEP match, and fraud risk "
+        "score < 60. If you decline, cite the specific failing criterion — an applicant is "
+        "legally entitled to the reason."
+    ),
+}
+
+
+def record_loan_underwriting() -> str:
+    """Supervisor + four specialists, each with real tool calls and a handoff.
+
+    This is the trace to open in the Simulation tab: five lanes, message arcs
+    crossing between them, and a retry that shares a call site with its first
+    attempt.
+    """
+    trace_id = f"run-{uuid.uuid4()}"
+    collector = start_recording(TENANT_ID)
+
+    orch = TraceContext(trace_id=trace_id, agent_id="orchestrator", mode="record")
+    kyc = TraceContext(trace_id=trace_id, agent_id="kyc-agent", mode="record")
+    credit = TraceContext(trace_id=trace_id, agent_id="credit-agent", mode="record")
+    fraud = TraceContext(trace_id=trace_id, agent_id="fraud-agent", mode="record")
+    policy = TraceContext(trace_id=trace_id, agent_id="policy-agent", mode="record")
+
+    # --- supervisor plans the run ---
+    context.set_current(orch)
+    llm_call(
+        "gpt-4o",
+        [
+            {"role": "system", "content": "You orchestrate loan underwriting. Delegate to specialists, then decide."},
+            {"role": "user", "content": f"Underwrite application {APPLICATION['application_id']}: {APPLICATION}"},
+        ],
+        "Plan: run KYC and credit in that order, then fraud screening, then hand all three findings to "
+        "the policy engine for the decision and adverse-action reasoning.",
+        extra_attrs={"cost_usd": "0.0042"},
+    )
+
+    # --- KYC specialist ---
+    task = send_to(orch, kyc, {"task": "Verify identity and screen sanctions/PEP", "application": APPLICATION}, "kyc-agent", "orchestrator")
+    identity = tool_call(
+        "identity_verify",
+        {"name": task["application"]["applicant"], "doc_type": "passport"},
+        {
+            "match": True,
+            "confidence": 0.97,
+            "document_valid": True,
+            "address_match": True,
+            "source": "govt-registry-api",
+        },
+    )
+    sanctions = tool_call(
+        "sanctions_screen",
+        {"name": task["application"]["applicant"], "lists": ["OFAC", "UN", "EU", "PEP"]},
+        {"ofac": "no_match", "un": "no_match", "eu": "no_match", "pep": "no_match", "screened_at": "2026-08-18T09:14:02Z"},
+        latency=0.09,
+    )
+    kyc_finding = (
+        "Identity verified at 0.97 confidence with a valid passport and matching address. "
+        "No hits on OFAC, UN, EU or PEP lists. KYC: PASS."
+    )
+    llm_call("gpt-4o-mini", [{"role": "user", "content": f"Summarize: {identity} {sanctions}"}], kyc_finding)
+    send_to(kyc, orch, {"finding": kyc_finding, "status": "pass"}, "orchestrator", "kyc-agent")
+
+    # --- credit specialist, with a bureau timeout and retry ---
+    task = send_to(orch, credit, {"task": "Pull bureau report and compute DTI", "application": APPLICATION}, "credit-agent", "orchestrator")
+    # A real retry loop: the bureau times out, then succeeds on the second
+    # attempt. Because both attempts happen at the *same source line*, they
+    # share one `call_site_id` and differ only by ordinal (0 then 1) — which is
+    # exactly the case that makes a global sequence number useless as a replay
+    # key, and why resolution is (call_site_id, ordinal) instead (docs/plan.md D3).
+    bureau_responses = [
+        {"error": "upstream_timeout", "retryable": True, "waited_ms": 5000},
+        {
+            "fico": 712,
+            "open_accounts": 6,
+            "total_monthly_debt_usd": 1840,
+            "delinquencies_24m": 0,
+            "oldest_account_years": 9.5,
+            "hard_inquiries_6m": 1,
+        },
+    ]
+    bureau: dict = {}
+    for attempt in bureau_responses:
+        bureau = tool_call(
+            "bureau_pull",
+            {"applicant": task["application"]["applicant"], "bureau": "experian"},
+            attempt,
+            latency=0.12,
+        )
+        if "error" not in bureau:
+            break
+    dti = tool_call(
+        "compute_dti",
+        {"monthly_income_usd": 6166, "existing_debt_usd": 1840, "new_loan_payment_usd": 512},
+        {"dti_before": 0.298, "dti_after": 0.381, "new_payment_usd": 512, "method": "monthly_obligations / gross_monthly_income"},
+    )
+    credit_finding = (
+        "FICO 712 (above the 660 floor). Six open accounts, no delinquencies in 24 months, "
+        "9.5-year credit history. DTI moves from 29.8% to 38.1% with the new $512 payment — "
+        "inside the 43% ceiling. Note: the first bureau pull timed out and was retried. Credit: PASS."
+    )
+    llm_call(
+        "gpt-4o",
+        [{"role": "user", "content": f"Assess: {bureau} {dti}"}],
+        credit_finding,
+        extra_attrs={"cost_usd": "0.0061"},
+    )
+    send_to(credit, orch, {"finding": credit_finding, "status": "pass", "fico": 712, "dti_after": 0.381}, "orchestrator", "credit-agent")
+
+    # --- fraud specialist ---
+    task = send_to(orch, fraud, {"task": "Screen for application fraud", "application": APPLICATION}, "fraud-agent", "orchestrator")
+    device = tool_call(
+        "device_fingerprint",
+        {"application_id": task["application"]["application_id"]},
+        {"device_reputation": "clean", "vpn": False, "emulator": False, "prior_applications_this_device": 1},
+    )
+    velocity = tool_call(
+        "velocity_check",
+        {"ssn_hash": "…9f2c", "window_days": 30},
+        {"applications_30d": 2, "distinct_lenders": 2, "threshold": 5, "flag": False},
+    )
+    fraud_finding = (
+        "Device reputation clean, no VPN or emulator, one prior application from this device. "
+        "Two applications across two lenders in 30 days, well under the threshold of five. "
+        "Composite fraud risk score 18/100. Fraud: PASS."
+    )
+    llm_call("gpt-4o-mini", [{"role": "user", "content": f"Score: {device} {velocity}"}], fraud_finding)
+    send_to(fraud, orch, {"finding": fraud_finding, "status": "pass", "risk_score": 18}, "orchestrator", "fraud-agent")
+
+    # --- policy engine decides ---
+    task = send_to(
+        orch,
+        policy,
+        {
+            "task": "Apply lending policy and produce the decision",
+            "kyc": kyc_finding,
+            "credit": credit_finding,
+            "fraud": fraud_finding,
+            "metrics": {"fico": 712, "dti_after": 0.381, "fraud_score": 18, "sanctions": "no_match"},
+        },
+        "policy-agent",
+        "orchestrator",
+    )
+    rules = tool_call(
+        "policy_lookup",
+        {"product": "auto_loan_used", "version": "2026.07"},
+        {
+            "min_fico": 660,
+            "max_dti": 0.43,
+            "max_fraud_score": 60,
+            "sanctions_must_be": "no_match",
+            "policy_version": "2026.07",
+        },
+    )
+    decision = call_policy_decision(
+        lambda: {
+            "choices": [
+                {
+                    "message": {
+                        "content": (
+                            "APPROVED. FICO 712 clears the 660 minimum. Post-loan DTI of 38.1% is within "
+                            "the 43% ceiling. Fraud score 18 is well below 60. No sanctions or PEP match. "
+                            "Approved at $28,000 over 60 months."
+                        )
+                    }
+                }
+            ]
+        },
+        metrics=task["metrics"],
+        rules=rules,
+    )
+    send_to(policy, orch, {"decision": decision["choices"][0]["message"]["content"], "outcome": "approved"}, "orchestrator", "policy-agent")
+
+    # --- supervisor records the final decision ---
+    context.set_current(orch)
+    llm_call(
+        "gpt-4o",
+        [{"role": "user", "content": f"Finalize: {decision['choices'][0]['message']['content']}"}],
+        "Application LN-2026-08841 approved for $28,000 over 60 months at 38.1% post-loan DTI. "
+        "All four specialist checks passed. Decision and supporting findings recorded for audit.",
+        extra_attrs={"cost_usd": "0.0038"},
+    )
+
+    collector.shutdown()
+    runtime.reset()
+    return trace_id
+
+
+def call_policy_decision(fn, metrics, rules):
+    """The policy engine's decision call — deliberately its own function.
+
+    Replay resolves by call site, so keeping this one call in one place is what
+    lets `record_policy_threshold_change` re-run *exactly this* decision under a
+    changed policy prompt and get a divergence pinned to it.
+    """
+    def timed():
+        # A real model call is not instantaneous, and this is the event the
+        # divergence demo points at — it should not be the one row with no bar.
+        time.sleep(0.22)
+        return fn()
+
+    return _intercept(
+        timed,
+        raw_input={
+            "model": "gpt-4o",
+            "messages": [POLICY_PROMPT, {"role": "user", "content": f"metrics={metrics} rules={rules}"}],
+        },
+        kind=LLM_CALL,
+        attrs={"model": "gpt-4o", "vendor": "openai", "tokens_in": "180", "tokens_out": "64", "cost_usd": "0.0031"},
+    )
+
+
+# --------------------------------------------------------------------------
+# Trace 2 — the divergence: tightening one policy threshold flips a decision
+# --------------------------------------------------------------------------
+
+TIGHTENED_POLICY_PROMPT = {
+    "role": "system",
+    "content": (
+        "You are the underwriting policy engine. Approve only if ALL hold: FICO >= 660, "
+        "debt-to-income after the new loan <= 36%, no sanctions or PEP match, and fraud risk "
+        "score < 60. If you decline, cite the specific failing criterion — an applicant is "
+        "legally entitled to the reason."
+    ),
+}
+
+
+def record_policy_threshold_change() -> str:
+    """Record an approval, then replay it after the DTI ceiling drops 43% -> 36%.
+
+    This is the demo that lands with a regulated buyer: one threshold changed in
+    one prompt, and an applicant who was approved is now declined. Pramana names
+    the exact call site where the behaviour changed and diffs the inputs, rather
+    than leaving someone to guess which of a hundred prompt edits did it.
+
+    Recorded under CONTINUE_AND_FLAG so the divergence is stored rather than
+    raised — the run completes and the flag is the artifact.
+    """
+    trace_id = f"run-{uuid.uuid4()}"
+    collector = start_recording(TENANT_ID)
+    context.set_current(TraceContext(trace_id=trace_id, agent_id="policy-agent", mode="record"))
+
+    metrics = {"fico": 712, "dti_after": 0.381, "fraud_score": 18, "sanctions": "no_match"}
+    rules = {"min_fico": 660, "max_dti": 0.43, "max_fraud_score": 60, "policy_version": "2026.07"}
+
+    call_policy_decision(
+        lambda: {
+            "choices": [
+                {
+                    "message": {
+                        "content": (
+                            "APPROVED. Post-loan DTI of 38.1% is within the 43% ceiling; FICO 712 clears "
+                            "660; fraud score 18 is below 60. Approved at $28,000 over 60 months."
+                        )
+                    }
+                }
+            ]
+        },
+        metrics=metrics,
+        rules=rules,
+    )
+
+    collector.shutdown()
+    runtime.reset()
+
+    # --- replay the same decision under the tightened policy ---
+    store = (
+        blob_store_factory_from_env()(TENANT_ID)
+        if os.environ.get("PRAMANA_BLOB_BACKEND") == "s3"
+        else LocalBlobStore(BLOB_DIR, tenant_id=TENANT_ID)
+    )
+    repo = PostgresEventRepository(CONNINFO, tenant_id=TENANT_ID)
+    runtime.configure(tenant_id=TENANT_ID, blob_store=store, repo=repo)
+    context.set_current(
+        TraceContext(trace_id=trace_id, agent_id="policy-agent", mode="replay", policy="CONTINUE_AND_FLAG")
+    )
+
+    def boom():
+        raise AssertionError("replay must never call the real model")
+
+    # Same call site, same ordinal — but the policy prompt and the DTI ceiling
+    # both changed, so the input hash no longer matches what was recorded.
+    global POLICY_PROMPT
+    original_prompt = POLICY_PROMPT
+    POLICY_PROMPT = TIGHTENED_POLICY_PROMPT
+    try:
+        call_policy_decision(
+            boom,
+            metrics=metrics,
+            rules={"min_fico": 660, "max_dti": 0.36, "max_fraud_score": 60, "policy_version": "2026.09-draft"},
+        )
+    finally:
+        POLICY_PROMPT = original_prompt
+        runtime.reset()
+
+    return trace_id
+
+
+# --------------------------------------------------------------------------
+# Trace 3 — single-agent support conversation (the Conversation tab)
+# --------------------------------------------------------------------------
+
+
+def record_support_conversation() -> str:
+    trace_id = f"run-{uuid.uuid4()}"
+    collector = start_recording(TENANT_ID)
+    context.set_current(TraceContext(trace_id=trace_id, agent_id="support-agent", mode="record"))
+
+    system_msg = {
+        "role": "system",
+        "content": (
+            "You are a customer support agent for Northwind Traders. Use the available tools to "
+            "look up order and policy information before answering. Be concise, friendly, and accurate."
+        ),
+    }
+    user_msg = {
+        "role": "user",
+        "content": (
+            "Hi, I'd like a refund for order #48213 — the espresso machine arrived with a cracked "
+            "carafe. Can you also remind me what your return window is?"
+        ),
+    }
+
+    lead_in = "Let me check your order details and our return policy for you."
+    llm_call("gpt-4o", [system_msg, user_msg], lead_in)
+
+    order = tool_call(
+        "lookup_order",
+        {"order_id": "48213"},
+        {
+            "order_id": "48213",
+            "customer": "J. Alvarez",
+            "items": [{"sku": "ESP-900", "name": "Northwind Pro Espresso Machine", "qty": 1, "price_usd": 249.00}],
+            "status": "delivered",
+            "delivered_at": "2026-08-10",
+            "carrier": "UPS",
+            "tracking": "1Z999AA10123456784",
+        },
+    )
+    policy = tool_call(
+        "lookup_policy",
+        {"topic": "returns"},
+        {
+            "topic": "returns",
+            "summary": (
+                "Items may be returned within 30 days of delivery for a full refund if unused, or "
+                "immediately for items that arrive damaged or defective, no restocking fee."
+            ),
+            "damaged_item_process": (
+                "Support can issue a prepaid return label and refund upon photo verification of the "
+                "damage; no need to wait for the item to be received back."
+            ),
+            "url": "https://support.northwindtraders.example/policies/returns",
+        },
+    )
+
+    final_answer = (
+        "I'm sorry about the cracked carafe — that's definitely covered. Since your espresso machine "
+        "(order #48213) arrived damaged, you don't need to wait out the normal 30-day return window; "
+        "I can issue a prepaid return label right away and process a full refund of $249.00 once we "
+        "get photo confirmation of the damage. Could you reply with 1-2 photos of the cracked carafe "
+        "so I can get that started?"
+    )
+    history = [
+        system_msg,
+        user_msg,
+        {"role": "assistant", "content": lead_in},
+        {"role": "tool", "content": str(order)},
+        {"role": "tool", "content": str(policy)},
+    ]
+    llm_call("gpt-4o", history, final_answer)
+
+    collector.shutdown()
+    runtime.reset()
+    return trace_id
+
+
+def create_evidence_bundle(trace_id: str, event_count: int, engineer_key: str) -> str | None:
+    resp = requests.post(
+        f"{API_URL}/v1/evidence",
+        headers={"Authorization": f"Bearer {engineer_key}"},
+        json={"trace_id": trace_id, "from_seq": 0, "to_seq": event_count - 1},
+        timeout=10,
+    )
+    if resp.status_code != 200:
+        print(f"  (evidence bundle failed for {trace_id}: {resp.status_code} {resp.text})")
+        return None
+    return resp.json()["bundle_id"]
+
+
+def _event_count(trace_id: str) -> int:
+    return len(PostgresEventRepository(CONNINFO, tenant_id=TENANT_ID).list_by_trace(trace_id))
+
+
+def main() -> None:
+    print("Recording demo traces against", INGEST_URL, "...")
+
+    loan_trace = record_loan_underwriting()
+    print(f"  loan underwriting:  {loan_trace}")
+    print("      5 agents (orchestrator + kyc/credit/fraud/policy), 8 tool calls, a bureau retry")
+
+    divergence_trace = record_policy_threshold_change()
+    print(f"  policy tightening:  {divergence_trace}")
+    print("      DTI ceiling 43% -> 36%; the same applicant flips approved -> declined")
+
+    support_trace = record_support_conversation()
+    print(f"  support conversation: {support_trace}  (single agent, 2 tool calls)")
+
+    time.sleep(1.5)  # let the collector's final flush land before we read counts back
+
+    engineer_key = _engineer_key()
+    bundles: dict[str, str | None] = {}
+    if engineer_key:
+        print("\nMinting evidence bundles...")
+        for t in (loan_trace, support_trace):
+            n = _event_count(t)
+            if n:
+                bundles[t] = create_evidence_bundle(t, n, engineer_key)
+    else:
+        print(f"\n(no {DEMO_KEYS_FILE} found — skipping evidence bundles; run deploy/seed_demo.py first)")
+
+    print("\n" + "=" * 76)
+    print("Demo ready. Open http://localhost:5173 and connect with:")
+    print(f"  API URL: {API_URL}")
+    if engineer_key:
+        print(f"  API key (engineer): {engineer_key}")
+    print()
+    print("Walk it in this order — each step shows something the next one builds on:")
+    print()
+    print(f"  1. {loan_trace}")
+    print("     Simulation tab. Five swimlanes, one per agent, with message arcs between them.")
+    print("     Scrub the timeline to watch the fan-out: orchestrator dispatches to KYC, then")
+    print("     credit, then fraud, then hands all three findings to the policy engine.")
+    print("     Ordering comes from vector clocks, not timestamps — so it stays correct even")
+    print("     though these agents ran concurrently.")
+    print()
+    print("     Then: Timeline tab -> find the two 'bureau_pull' calls. Same call site, ordinals")
+    print("     0 and 1: the first timed out, the second succeeded. Retries are why replay keys")
+    print("     on (call site, ordinal) instead of a sequence number.")
+    print()
+    print(f"  2. {divergence_trace}")
+    print("     Divergences tab. One threshold changed in one prompt — the DTI ceiling went from")
+    print("     43% to 36% — and this applicant went from approved to declined. Pramana names the")
+    print("     exact call site and diffs the inputs. This is the question 'which prompt edit")
+    print("     broke it?' answered in one screen instead of a week.")
+    print()
+    print(f"  3. {support_trace}")
+    print("     Conversation tab. The simple single-agent case, rendered as a readable chat with")
+    print("     tool calls folded inline.")
+    print()
+    if any(bundles.values()):
+        print(f"  4. Evidence tab on {loan_trace[:20]}...")
+        print("     Export a bundle, then paste the signer public key and hit Verify — it")
+        print("     recomputes the hash chain, Merkle root, and Ed25519 signature in your browser.")
+        print("     Then 'Download' and run `pramana-verify bundle.json --pubkey <hex>` offline.")
+        print("     That's the pitch for a regulated buyer: they can check the record without")
+        print("     trusting your servers. For a declined loan, that is the audit trail.")
+        print()
+    print("  5. Agent graph tab. Hub-and-spoke topology across every trace this tenant has")
+    print("     recorded — orchestrator at the centre, four specialists around it, line weight")
+    print("     by message volume.")
+    print("=" * 76)
+
+
+if __name__ == "__main__":
+    main()