Metadata-Version: 2.4
Name: agentforge-langfuse
Version: 0.2.4
Summary: Langfuse trace dashboard 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,langfuse,llm,observability
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: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Description-Content-Type: text/markdown

# agentforge-langfuse

Langfuse trace dashboard hook for the AgentForge framework.

Implements the `StepHook` + `FinishHook` contracts and
registers as `agentforge.hooks:langfuse`.

## Installation

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

The `[langfuse]` extra pulls in the `langfuse>=2.0` SDK.
Without it, the production factory raises `ModuleError` with
pip remediation.

## Usage

```python
from agentforge import Agent
from agentforge_langfuse import LangfuseHook

hook = LangfuseHook.from_config(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="https://cloud.langfuse.com",
    trace_name_prefix="agentforge.pr-reviewer",
)

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

## Trace shape

- One **trace** per run, opened on the first step (keyed by
  `run_id`).
- One **span** per step (`name = "step:<kind>"`).
- A **nested span** per `tool_call` (`name = "tool:<name>"`).
- Two **scores** on finish: `cost_usd` and `duration_ms`.
- The trace is `flush()`-ed at finish so it lands in the
  dashboard without waiting for the SDK's batch interval.

## License

Apache-2.0.
