camelai-tealtiger
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. All policy evaluation is deterministic, adding <2ms latency.
Installation
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.
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.
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:
{
"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:
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:
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:
{
"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
# 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.
Metadata
Release files for camelai-tealtiger 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| camelai_tealtiger-0.1.0.tar.gz | 22.2 kB | Without provenance | Details for camelai_tealtiger-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| camelai_tealtiger-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for camelai_tealtiger-0.1.0-py3-none-any.whl |
Total release size: 38.1 kB
Release files / camelai_tealtiger-0.1.0.tar.gz
| Download URL | camelai_tealtiger-0.1.0.tar.gz |
|---|---|
| Size | 22.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
588f19f10b75953c8ad2a81d4beeca5312f203098bc9d07d193923af2d11b69a
|
|
BLAKE2b-256 checksum How to use checksums |
d9c19baa1b05645e541dc1d332bc0bf735cc549281a9b16d7b7574f91293b150
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / camelai_tealtiger-0.1.0-py3-none-any.whl
| Download URL | camelai_tealtiger-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5803528ec83a8f1ddce07f90cf69cc8be60cebb296ee70149d6306222bea9196
|
|
BLAKE2b-256 checksum How to use checksums |
52cce973fb207681e97071d60064d57ceccf870535a2ca8e6de9d4e48566dc57
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for camelai-tealtiger 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.