Metadata-Version: 2.4
Name: agentforge-statsd
Version: 0.2.4
Summary: StatsD metrics emitter hook for AgentForge
Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py
Project-URL: Changelog, https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Scaffoldic/agentforge-py/issues
Author: The AgentForge Authors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,metrics,observability,statsd
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: agentforge-core~=0.2.4
Provides-Extra: statsd
Requires-Dist: statsd>=4.0; extra == 'statsd'
Description-Content-Type: text/markdown

# agentforge-statsd

StatsD metrics emitter for the AgentForge framework.

Implements the `StepHook` + `FinishHook` contracts on the
existing `agentforge.hooks` entry-point so installing the
package makes `name: statsd` available in
`modules.observability` config blocks.

## Installation

```bash
pip install agentforge-statsd[statsd]
```

The `[statsd]` extra pulls in the `statsd>=4.0` Python client.
Without the extra, the package is importable but the
production factory raises `ModuleError` with pip remediation.

## Usage

```python
from agentforge import Agent
from agentforge_statsd import StatsdHook

hook = StatsdHook.from_config(
    host="statsd.internal",
    port=8125,
    prefix="agentforge.pr-reviewer",
)

agent = Agent(
    model="bedrock:...",
    on_step=hook,
    on_finish=hook,
)
```

## Metrics emitted

| Metric | Type | When |
|---|---|---|
| `<prefix>.step.<kind>` | counter +1 | every step |
| `<prefix>.step.duration_ms` | timing | every step with `duration_ms > 0` |
| `<prefix>.tool.<name>` | counter +1 | every step with `tool_call` |
| `<prefix>.run.finish.<reason>` | counter +1 | on run finish |
| `<prefix>.run.duration_ms` | timing | on run finish |
| `<prefix>.run.cost_usd` | gauge | on run finish |
| `<prefix>.run.tokens_in` | gauge | on run finish |
| `<prefix>.run.tokens_out` | gauge | on run finish |

## License

Apache-2.0.
