Metadata-Version: 2.4
Name: spolm-tracer
Version: 0.1.0
Summary: Official Spolm SDK for Python — trace, simulate, and verify AI agent runs.
Author: Spolm
License: MIT
Project-URL: Homepage, https://spolm.com
Project-URL: Repository, https://github.com/Tanrocode/spolm
Keywords: ai,agents,llm,tracing,observability,verification,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25

# 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`](https://www.npmjs.com/package/@spolm/tracer).

## Install

```bash
pip install spolm-tracer
```

## Quickstart

```python
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:

```python
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:

```python
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.
