Metadata-Version: 2.4
Name: camelai-tealtiger
Version: 0.1.0
Summary: Deterministic governance hook for CAMEL-AI multi-agent systems — policy enforcement, PII detection, cost tracking, kill switch, and structured audit evidence. No LLM in the governance path.
Project-URL: Homepage, https://tealtiger.ai
Project-URL: Documentation, https://docs.tealtiger.ai/integrations/camel-ai
Project-URL: Repository, https://github.com/agentguard-ai/tealtiger
Project-URL: Issues, https://github.com/agentguard-ai/tealtiger/issues
Project-URL: Changelog, https://github.com/agentguard-ai/tealtiger/blob/main/packages/camelai-tealtiger/CHANGELOG.md
Author-email: TealTiger Team <reachout@tealtiger.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,audit,camel-ai,cost-tracking,deterministic,governance,guardrails,kill-switch,llm,multi-agent,pii,policy,security,tealtiger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: camel-ai>=0.2.0
Requires-Dist: tealtiger>=1.3.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# camelai-tealtiger

Deterministic governance hook for [CAMEL-AI](https://github.com/camel-ai/camel) multi-agent systems — policy enforcement, PII detection, cost tracking, kill switch, and structured audit evidence.

**No LLM in the governance path.** All policy evaluation is deterministic, adding <2ms latency.

[![PyPI](https://img.shields.io/pypi/v/camelai-tealtiger)](https://pypi.org/project/camelai-tealtiger/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/camelai-tealtiger)](https://pypi.org/project/camelai-tealtiger/)

## Installation

```bash
pip install camelai-tealtiger
```

## Quick Start

### Zero-Config Mode (Observe)

Add governance to any CAMEL-AI multi-agent system with zero configuration. In this mode, TealTiger observes all traffic, tracks cost estimates, detects PII, and allows everything through — producing structured audit entries for observability.

```python
from camelai_tealtiger import TealTigerAgentHook

hook = TealTigerAgentHook()

# Before each agent step
decision = hook.pre_step(
    agent_id="assistant-001",
    step_content="Summarize this document about AI safety...",
    tool_name="web_search",
    tool_args={"query": "AI safety papers"},
    agent_role="researcher",
)
# decision["action"] == "ALLOW"
# decision["pii_detected"] == []
# decision["cost_tracked"] == 0.000025
# decision["teec"]["namespace"] == "teec.camelai"

# After each agent step
hook.post_step(
    agent_id="assistant-001",
    step_result="Here is the summary of 3 papers...",
    token_usage={"prompt_tokens": 200, "completion_tokens": 150},
)

# Access cost summary
print(hook.summary)  # Per-agent cost, step counts, PII findings
```

### Policy Mode (Enforce)

When you provide a `TealEngine` instance, the hook evaluates configured policies and blocks steps that violate governance rules.

```python
from tealtiger import TealEngine
from camelai_tealtiger import TealTigerAgentHook, GovernanceDenyError

engine = TealEngine(policies=[
    {"type": "cost_limit", "max_per_session": 5.00},
    {"type": "pii_block", "categories": ["ssn", "credit_card"]},
])

hook = TealTigerAgentHook(
    engine=engine,
    mode="ENFORCE",
    task_prompt="Research AI safety",
    society_id="research-team-001",
)

try:
    decision = hook.pre_step(
        agent_id="agent-1",
        step_content="Process this request",
        agent_role="researcher",
    )
except GovernanceDenyError as e:
    print(f"Blocked: {e.decision['reason']}")
```

## Features

| Feature | Zero-Config | Policy Mode |
|---------|:-----------:|:-----------:|
| PII detection (email, SSN, credit card, phone, IP) | ✅ | ✅ |
| Cost tracking per agent/session/task | ✅ | ✅ |
| Structured audit entries | ✅ | ✅ |
| Correlation IDs (UUID v4) | ✅ | ✅ |
| TEEC namespace (teec.camelai) | ✅ | ✅ |
| Kill switch (freeze/unfreeze) | ✅ | ✅ |
| Behavioral baseline | ✅ | ✅ |
| Policy enforcement (DENY/ALLOW) | — | ✅ |
| Fail-closed on engine error | — | ✅ |
| Role validation (allowlist) | ✅ | ✅ |
| Risk scoring | ✅ | ✅ |

## Hook API

### `pre_step(agent_id, step_content, tool_name=None, tool_args=None, agent_role=None, role_type=None)`

Evaluate governance before an agent step. Returns a decision dict. Raises `GovernanceDenyError` in ENFORCE mode when blocked.

### `post_step(agent_id, step_result, token_usage=None, agent_role=None, role_type=None)`

Track cost and audit after an agent step completes. Accepts optional `token_usage` dict for accurate cost tracking.

### `freeze(agent_id)` / `unfreeze(agent_id)`

Kill switch — blocks all subsequent `pre_step` calls for the specified agent. `unfreeze` restores normal operation.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `audit_trail` | `List[AuditEntry]` | Full audit trail of governance decisions |
| `summary` | `Dict[str, AgentSummary]` | Cost/step counts per agent |
| `cumulative_cost` | `float` | Total tracked cost for the session |
| `session_id` | `str` | Session identifier |

### `get_baseline()`

Returns a behavioral baseline summary per agent, including average cost per step, common tools, PII frequency, and typical risk scores.

## Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `engine` | `TealEngine \| None` | `None` | TealEngine for policy evaluation |
| `mode` | `str` | `"OBSERVE"` | Mode: `OBSERVE`, `MONITOR`, or `ENFORCE` |
| `cost_per_1k_tokens` | `float` | `0.002` | Estimated cost per 1000 tokens |
| `session_id` | `str \| None` | Auto-generated | Session identifier |
| `society_id` | `str \| None` | `None` | Multi-agent society/group identifier |
| `task_prompt` | `str \| None` | `None` | Task prompt (hashed for TEEC) |
| `role_allowlist` | `List[str] \| None` | `None` | Allowed agent roles |

## Governance Modes

- **OBSERVE** — Zero-config default. Allow all, track cost, detect PII, produce audit entries.
- **MONITOR** — Policy mode with logging only. Evaluate policies but allow all requests through.
- **ENFORCE** — Production mode. Block steps that violate policies. Fail-closed on engine errors.

## TEEC Namespace (teec.camelai)

Every audit entry includes TEEC (Typed Evidence & Evidence Contract) fields:

```python
{
    "teec": {
        "namespace": "teec.camelai",
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
        "step_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "task_prompt": "a3f2b8c1...",  # SHA-256 hash
        "agent_role": "researcher",
        "role_type": "assistant",
        "society_id": "debate-team-001"
    }
}
```

## Kill Switch

Emergency agent termination without restarting the system:

```python
hook = TealTigerAgentHook(mode="ENFORCE")

# Agent misbehaving? Freeze it immediately
hook.freeze("rogue-agent-001")

# All subsequent steps for this agent are blocked
# Other agents continue normally

# Restore when ready
hook.unfreeze("rogue-agent-001")
```

## Role Validation

Restrict which roles can operate in your multi-agent system:

```python
hook = TealTigerAgentHook(
    mode="ENFORCE",
    role_allowlist=["assistant", "critic", "researcher"],
)

# Allowed
hook.pre_step(agent_id="a1", step_content="...", agent_role="assistant")

# Blocked — raises GovernanceDenyError
hook.pre_step(agent_id="a2", step_content="...", agent_role="admin")
```

## Audit Entry Structure

Every evaluation produces a structured audit entry:

```python
{
    "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp_ms": 1709234567890.0,
    "action": "ALLOW",
    "mode": "OBSERVE",
    "phase": "pre_step",
    "agent_id": "assistant-001",
    "reason": "Allowed: zero-config observe mode",
    "reason_codes": ["OBSERVE_PASSTHROUGH"],
    "risk_score": 0,
    "pii_detected": [],
    "cost_tracked": 0.000025,
    "cumulative_cost": 0.000075,
    "evaluation_time_ms": 0.38,
    "teec": {
        "namespace": "teec.camelai",
        "session_id": "...",
        "step_id": "..."
    },
    "metadata": {
        "step_count": 3,
        "tool_name": "web_search",
        "tool_args": {"query": "..."},
        "input_length": 45,
        "estimated_tokens": 11
    }
}
```

## PII Detection

Built-in pattern detection for:
- Email addresses
- US phone numbers
- Social Security Numbers (SSN)
- Credit card numbers
- IP addresses

PII findings are reported in audit entries with redacted values. In OBSERVE/MONITOR modes, steps proceed normally with PII flagged in the audit trail.

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

# Linting
ruff check src/ tests/
```

## License

Apache-2.0 — see [LICENSE](LICENSE).
