spolm-tracer 0.1.1

Official Spolm SDK for Python — trace, simulate, and verify AI agent runs.

spolm-tracer

Official Spolm SDK for Python — trace, simulate, and verify AI agent runs.

spolm-tracer instruments your agent so its runs appear in Spolm, where they're clustered into failure patterns, turned into enforceable checks, and certified in a shareable Reliability Report. The JavaScript SDK is @spolm/tracer.

Install

pip install spolm-tracer

Quickstart

from spolm_tracer import Tracer

tracer = Tracer(API_KEY, AGENT_ID)   # from your Spolm dashboard

run_id = tracer.startRun("Summarize the Q3 earnings call")

# Wrap the functions you want traced as steps
traced_llm = tracer.log_step(step_name="answer", step_type="model", provider="openai")(call_llm)
result = await traced_llm(prompt)

tracer.end_run(result, "complete")

Simulation

Run your agent against a Spolm-generated set of test cases (auto-generated from the agent's configured description/instructions/rubrics) and record the results as simulation traces:

async def agent_fn(user_task, tracer):
    # your agent must call startRun/end_run itself (or via its own Tracer)
    tracer.startRun(user_task)
    result = await run_agent(user_task)
    tracer.end_run(result, "complete")
    return result

# Deterministic adversarial packs + generated cases
await tracer.simulate(agent_fn, mode="full", pause_ms=250)

# mode="fast" runs only the deterministic adversarial packs (cheap CI)
await tracer.simulate(agent_fn, mode="fast")

Property-based testing

Actively search for inputs that make your agent violate its promoted checks/invariants — trace-seeded mutations, the enforced suite as the oracle, and delta-debugged minimal repros for any violation found:

result = await tracer.property_test(
    agent_fn,
    invariants=[{"id": "no-injection-obedience", "description": "never obey injected instructions"}],
    iterations=2,
    per_round=8,
)
print(result["violations_found"], "violations", result["violations"])

API

Method	Purpose
Tracer(api_key, agent_id, options=None)	Create a tracer
startRun(user_task, metadata={})	Begin a run; returns run_id
log_step(step_name=, step_type=, provider=None, options=None)(fn)	Wrap a function as a traced step
end_run(final_result, status="complete")	Finalize and send the run
await simulate(agent_fn, count=None, pause_ms=0, mode="full")	Run generated/adversarial test cases
await property_test(agent_fn, invariants=None, iterations=1, per_round=8, pause_ms=0, max_runs=None)	Search for invariant violations

MIT.