Quick start

pip install aevyra-witness

from aevyra_witness.runtime import span, trace

@span("classify")
def classify(ticket: str) -> str:
    return "billing/refund"

@span("search_kb", optimize=True, prompt_id="kb_search_v2")
def search_kb(topic: str) -> list[str]:
    return ["refund_policy.md", "billing_faq.md"]

@span("answer", optimize=True, prompt_id="answer_v1")
def answer(question: str, docs: list[str]) -> str:
    return "You can request a refund within 30 days by contacting support."

def my_agent(question: str) -> str:
    topic = classify(question)
    docs  = search_kb(topic)
    return answer(question, docs)

# Run under a tracer to capture the execution
with trace() as tracer:
    output = my_agent("I was charged twice — how do I get a refund?")

captured: AgentTrace = tracer.finish()
print(captured.to_trace_text())

from aevyra_witness.adapters import from_openclaw_jsonl, from_otel_spans
from pathlib import Path

# OpenClaw JSONL
trace = from_openclaw_jsonl(Path("run.jsonl").read_text().splitlines())

# OpenTelemetry (Python SDK, OTLP JSON, or any gen_ai.* framework)
trace = from_otel_spans(otel_exporter.get_finished_spans())

from mcp import ClientSession
from aevyra_witness.interceptors import wrap_mcp_session

async with ClientSession(read, write) as session:
    await session.initialize()
    mcp = wrap_mcp_session(session, server_name="stripe")

    charge   = await mcp.call_tool("get_charge", {"id": "ch_123"})
    customer = await mcp.call_tool("get_customer", {"id": "cus_abc"})

    trace = mcp.to_trace()

from aevyra_witness import AgentTrace

# Human-readable rendering
print(trace.to_trace_text())

# Count spans by kind
for node in trace.nodes:
    print(f"{node.id}  {node.kind:<10}  {node.name}")

# Serialise — pass to Origin, save to disk, ship over HTTP
import json
Path("trace.json").write_text(trace.to_json(indent=2))

# Deserialise
trace2 = AgentTrace.from_dict(json.loads(Path("trace.json").read_text()))

@span("plan", optimize=True, prompt_id="planner_v1")
def plan(context: str) -> str: ...

trace.nodes[0].optimize = True
trace.nodes[0].prompt_id = "planner_v1"