Metadata-Version: 2.4
Name: tracerazor-crewai
Version: 1.0.0
Summary: TraceRazor callback adapter for CrewAI - automatic token efficiency auditing
Author: Zulfaqar Hafez
License-Expression: MIT
Project-URL: Homepage, https://github.com/ZulfaqarHafez/tracerazor
Project-URL: Repository, https://github.com/ZulfaqarHafez/tracerazor
Keywords: ai,agents,crewai,token-efficiency,tracing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: tracerazor>=1.0.1
Provides-Extra: crewai
Requires-Dist: crewai>=0.28; extra == "crewai"

# tracerazor-crewai

CrewAI callback adapter for [TraceRazor](../../README.md).

Automatically captures every task execution and tool call from your CrewAI crew with zero manual instrumentation.

**v0.2.0 — New Metrics:**
- ✨ **Semantic Continuity (CSD)** — Detects when your crew's agents drift topic mid-workflow
- ✨ **Adherence Scoring (IAR)** — After optimizing, validates that fixes actually improved metrics

## Install

```bash
pip install tracerazor-crewai
pip install tracerazor-crewai[crewai]  # includes crewai
```

Requires the `tracerazor` binary:

```bash
cargo build --release
export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
```

## Usage

```python
from tracerazor_crewai import TraceRazorCallback
from crewai import Agent, Task, Crew

callback = TraceRazorCallback(
    agent_name="support-crew",
    threshold=70,
)

crew = Crew(
    agents=[...],
    tasks=[...],
    callbacks=[callback],
)

crew.kickoff()

# After the crew finishes:
report = callback.analyse()
print(report.markdown())

# CI/CD gate — raises AssertionError if TAS < threshold:
callback.assert_passes()
```

## API

### `TraceRazorCallback(agent_name, framework, threshold, task_value_score, tracerazor_bin)`

| param | default | description |
|---|---|---|
| `agent_name` | `"crewai-crew"` | shown in all reports |
| `framework` | `"crewai"` | framework label |
| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
| `task_value_score` | `1.0` | answer quality (0–1) |
| `tracerazor_bin` | auto | path to binary; falls back to `TRACERAZOR_BIN` env var |

### `callback.analyse() → TraceRazorReport`

Finalise and submit the trace. Returns the report.

### `callback.assert_passes()`

Raise `AssertionError` if TAS < threshold.

### `callback.set_task_value_score(score: float)`

Update quality score before calling `analyse()`.

## Captured events

| CrewAI event | TraceRazor step type |
|---|---|
| `on_task_start` / `on_task_end` | `reasoning` |
| `on_agent_action` | `reasoning` or `tool_call` |
| `on_tool_use_start` / `on_tool_use_end` | `tool_call` (success) |
| `on_tool_error` | `tool_call` (failure → TCA misfire) |

## Multi-Agent Crews

For complex workflows with multiple crews, use a separate callback for each:

```python
from tracerazor_crewai import TraceRazorCallback

# Crew 1: Triage & classification
triage_crew = Crew(agents=[triage_agent], tasks=[triage_task], 
                   callbacks=[TraceRazorCallback(agent_name="triage-crew")])
triage_result = triage_crew.kickoff()

# Crew 2: Resolution execution
resolution_crew = Crew(agents=[resolution_agent], tasks=[resolution_task],
                       callbacks=[TraceRazorCallback(agent_name="resolution-crew")])
resolution_result = resolution_crew.kickoff()

# Each crew is audited independently
```

See [Multi-Agent Guide](../tracerazor/examples/MULTI_AGENT_GUIDE.md) for complete example with per-agent optimization.
