Metadata-Version: 2.4
Name: agentbelt-sampler
Version: 0.1.1
Summary: Agent-aware span sampling: keeps errors, cost/latency outliers, retries, and novel calls; samples the rest. Part of the agentbelt suite.
Author: Saptarshi Bhattacharjee
License-Expression: MIT
Project-URL: Homepage, https://github.com/bsaptarshi/agentbelt
Keywords: llm,agents,sampling,observability,opentelemetry,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentbelt-core>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
Dynamic: license-file

# agentbelt-sampler

Agent-aware span sampling: always keep errors, cost/latency outliers,
retries, and novel calls; sample everything else at a low rate. Part of the
[agentbelt](https://github.com/bsaptarshi/agentbelt) suite.

```bash
pip install agentbelt-sampler
# or, for the real OpenTelemetry Sampler adapter:
pip install agentbelt-sampler[otel]
```

## Quickstart

```python
from agentbelt_sampler import Sampler, SamplingPolicy, Span

sampler = Sampler(SamplingPolicy(boring_sample_rate=0.05))

if sampler.should_keep(Span(tool="search", cost_usd=0.002, is_error=False)):
    export(span)
```

Run `python examples/volume_demo.py` for a concrete before/after number
(errors and outliers 100% retained, overall volume cut substantially on a
repetitive synthetic stream).

## What did this actually catch?

```python
print(sampler.impact_report())
# 100 span(s) seen, 11 kept (89.0% reduction)
```

The most direct of the three impact reports — seen vs. kept, mapped
straight to observability-backend cost reduction.

See the [suite README](https://github.com/bsaptarshi/agentbelt) for the
full concept and how this fits with `agentbelt-budget` and `agentbelt-loop`.

## License

MIT
