Metadata-Version: 2.5
Name: strands-tealtiger
Version: 0.2.1
Summary: Deterministic governance plugin for Strands Agents — tool allowlists, PII/secret detection, prompt injection defense, cost budgets, and kill switches. No LLM in the governance path, no external server required.
Project-URL: Homepage, https://tealtiger.ai
Project-URL: Documentation, https://docs.tealtiger.ai/integrations/strands
Project-URL: Repository, https://github.com/agentguard-ai/tealtiger
Project-URL: Issues, https://github.com/agentguard-ai/tealtiger/issues
Author-email: TealTiger Team <reachout@tealtiger.ai>
License: Apache-2.0
Keywords: ai-agents,cost-tracking,deterministic,governance,guardrails,kill-switch,pii,plugin,security,strands,strands-agents,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: strands-agents>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# strands-tealtiger

Deterministic governance plugin for [Strands Agents](https://strandsagents.com) — tool allowlists, PII/secret detection, prompt injection defense, cost budgets, and kill switches.

**No LLM in the governance path. No external server. <2ms per evaluation.**

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

## Installation

```bash
pip install strands-tealtiger
```

📖 **Full documentation**: [docs.tealtiger.ai/integrations/strands](https://docs.tealtiger.ai/integrations/strands)

## Quick Start

```python
from strands import Agent
from strands_tools import calculator
from strands_tealtiger import TealTigerPlugin

agent = Agent(
    tools=[calculator],
    plugins=[TealTigerPlugin(
        mode="ENFORCE",
        allowed_tools=["calculator"],
        budget_limit=5.0,
    )]
)

agent("What is 42 * 17?")
```

## Usage

### Tool Allowlist + Blocklist

Control which tools the agent can call:

```python
from strands_tealtiger import TealTigerPlugin

governance = TealTigerPlugin(
    mode="ENFORCE",
    allowed_tools=["search", "read_*"],    # Glob patterns
    blocked_tools=["delete_*", "rm_*"],    # Always denied (overrides allowlist)
)
```

### PII Detection

Block tool calls containing sensitive data:

```python
governance = TealTigerPlugin(
    mode="ENFORCE",
    pii_categories=["ssn", "credit_card", "email", "phone"],
)
```

### Prompt Injection Defense

Detect adversarial inputs in tool arguments:

```python
governance = TealTigerPlugin(
    mode="ENFORCE",
    detect_injection=True,
    injection_threshold=0.8,  # Higher = fewer false positives
)
```

Detects: instruction override, DAN/jailbreak, developer mode, system prompt override, delimiter injection, XML tag injection, fake system messages.

### Cost Budget

Hard-stop when session cost exceeds the limit:

```python
governance = TealTigerPlugin(
    mode="ENFORCE",
    budget_limit=5.0,         # $5 max per session
    cost_per_call=0.003,      # Estimated cost per tool call
)
```

### Kill Switch

Freeze all tool calls immediately — no policy can override:

```python
governance = TealTigerPlugin(mode="ENFORCE")

# Later, when something goes wrong:
governance.freeze()    # All tool calls blocked instantly
governance.unfreeze()  # Resume normal governance
```

### Secret Detection

Block tool calls containing API keys, tokens, or credentials:

```python
governance = TealTigerPlugin(
    mode="ENFORCE",
    detect_secrets=True,  # Default: True
)
```

Catches: OpenAI keys (`sk-...`), GitHub tokens (`ghp_...`), AWS keys (`AKIA...`), Slack tokens, generic API keys, PEM private keys.

## Governance Modes

| Mode | Behavior | Use Case |
|------|----------|----------|
| `ENFORCE` | Block violations via `event.cancel_tool` | Production |
| `MONITOR` | Evaluate policies, log decisions, allow all through | Staging / shadow |
| `OBSERVE` | Skip evaluation, track cost only | Initial rollout |

```python
# Start with OBSERVE in staging
governance = TealTigerPlugin(mode="OBSERVE")

# Promote to MONITOR to see what would be blocked
governance = TealTigerPlugin(mode="MONITOR")

# Enforce in production
governance = TealTigerPlugin(mode="ENFORCE")
```

## Audit Trail

Every evaluation produces a structured `GovernanceDecision`:

```python
for decision in governance.decisions:
    print(
        f"[{decision.action}] {decision.tool_name} "
        f"— {decision.reason_codes} "
        f"(risk={decision.risk_score}, {decision.evaluation_time_ms:.2f}ms)"
    )
```

Fields:

| Field | Type | Description |
|-------|------|-------------|
| `decision_id` | `str` | UUID for correlation |
| `action` | `str` | `ALLOW` or `DENY` |
| `mode` | `str` | `ENFORCE`, `MONITOR`, or `OBSERVE` |
| `tool_name` | `str` | Tool that was evaluated |
| `reason` | `str` | Human-readable reason |
| `reason_codes` | `list[str]` | Machine-readable codes |
| `risk_score` | `int` | 0–100 |
| `cost_tracked` | `float` | Cost for this call |
| `cumulative_cost` | `float` | Session total |
| `evaluation_time_ms` | `float` | Governance latency |

## Multi-Agent (Swarm / Graph)

Works in multi-agent patterns — attach to individual agents:

```python
from strands import Agent
from strands.multiagent import Swarm
from strands_tealtiger import TealTigerPlugin

researcher = Agent(
    name="researcher",
    tools=[search],
    plugins=[TealTigerPlugin(
        mode="ENFORCE",
        allowed_tools=["search"],
        budget_limit=3.0,
    )]
)

writer = Agent(
    name="writer",
    tools=[write_file],
    plugins=[TealTigerPlugin(
        mode="ENFORCE",
        allowed_tools=["write_file"],
        pii_categories=["ssn", "credit_card"],
    )]
)

swarm = Swarm([researcher, writer])
```

## Complete Example

```python
import asyncio
from strands import Agent, tool
from strands_tealtiger import TealTigerPlugin

@tool
def search(query: str) -> str:
    """Search the web."""
    return f"Results for: {query}"

@tool
def send_email(to: str, body: str) -> str:
    """Send an email."""
    return f"Sent to {to}"

@tool
def delete_database(table: str) -> str:
    """Delete a database table."""
    return f"Deleted {table}"

# Configure governance
governance = TealTigerPlugin(
    mode="ENFORCE",
    allowed_tools=["search", "send_email"],
    blocked_tools=["delete_*"],
    pii_categories=["ssn", "credit_card", "email"],
    detect_secrets=True,
    detect_injection=True,
    budget_limit=5.0,
    cost_per_call=0.003,
    on_decision=lambda d: print(f"  [{d.action}] {d.tool_name}: {d.reason_codes}"),
)

agent = Agent(
    system_prompt="You are a helpful research assistant.",
    tools=[search, send_email, delete_database],
    plugins=[governance],
)

# This works (search is allowed)
agent("Search for AI governance frameworks")

# This is DENIED (delete_database is in blocklist)
agent("Delete the users table")

# Post-run analysis
print(f"\nTotal decisions: {len(governance.decisions)}")
print(f"Denied: {governance.deny_count}")
print(f"Session cost: ${governance.total_cost:.4f}")
```

## Comparison with Agent Control

| | Agent Control (Galileo) | TealTiger |
|---|---|---|
| Architecture | External server + Docker required | In-process, zero infrastructure |
| Latency | Network round-trip per evaluation | <2ms in-process |
| Dependencies | Galileo SaaS for AI evaluators | None — stdlib only |
| Determinism | LLM-as-judge (Luna-2) | Pure regex/pattern matching |
| Offline/air-gap | Requires server connectivity | Works fully offline |
| Lambda/serverless | Cold start penalty for server connection | Zero cold start overhead |
| Cost | Paid AI evaluations | Free, Apache 2.0 |

## API Reference

### `TealTigerPlugin`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mode` | `str` | `"ENFORCE"` | Governance mode |
| `allowed_tools` | `list[str] \| None` | `None` | Glob patterns for permitted tools |
| `blocked_tools` | `list[str] \| None` | `[]` | Explicit deny-list |
| `pii_categories` | `list[str] \| None` | `[]` | PII types to detect |
| `detect_secrets` | `bool` | `True` | Enable secret detection |
| `detect_injection` | `bool` | `True` | Enable injection detection |
| `injection_threshold` | `float` | `0.7` | Confidence threshold for injection |
| `budget_limit` | `float \| None` | `None` | Max session cost (USD) |
| `cost_per_call` | `float` | `0.002` | Estimated cost per tool call |
| `on_decision` | `callable \| None` | `None` | Callback for each decision |

### Methods

| Method | Description |
|--------|-------------|
| `freeze()` | Activate kill switch |
| `unfreeze()` | Deactivate kill switch |
| `reset()` | Clear session state |

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `decisions` | `list[GovernanceDecision]` | All decisions this session |
| `total_cost` | `float` | Cumulative cost |
| `deny_count` | `int` | Number of denials |
| `is_frozen` | `bool` | Kill switch status |

## License

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