# Tenuo Python Examples

This directory contains working examples demonstrating how to use the Tenuo Python SDK.

## Prerequisites

```bash
# Using uv (recommended)
uv pip install tenuo

# Or standard pip
pip install tenuo
```

## Quick Start

**OpenAI** - Semantic constraints that block attacks:
```python
from openai import OpenAI
from tenuo.openai import GuardBuilder
from tenuo.constraints import Subpath, UrlSafe

client = (GuardBuilder(OpenAI())
    .allow("read_file", path=Subpath("/data"))  # Blocks path traversal
    .allow("fetch", url=UrlSafe())              # Blocks SSRF attacks
    .build())
```

**Google ADK** - Same semantic protection:
```python
from tenuo.google_adk import GuardBuilder
from tenuo.constraints import Subpath

guard = (GuardBuilder()
    .allow("read_file", path=Subpath("/data"))
    .build())

agent = Agent(tools=[...], before_tool_callback=guard.before_tool)
```

**A2A (Multi-Agent)** - Warrant-based delegation:
```python
from tenuo.a2a import A2AServerBuilder

server = (A2AServerBuilder()
    .name("Worker")
    .url("https://worker.example.com")
    .key(my_key)
    .accept_warrants_from(orchestrator_key)
    .build())
```

> **Simple Allowlist?** Use `protect(client, tools=[...])` for basic protection without constraints.

---

## Featured Demo: Research Agent with Guardrails

**The best way to see Tenuo in action — works in dry-run mode OR with real OpenAI!**

```bash
# Install core dependencies
uv pip install "tenuo[mcp]"

# Run demo (dry-run mode - no API keys needed!)
python research_agent_demo.py

# Optional: For real LLM integration
uv pip install langchain-openai
export OPENAI_API_KEY="sk-..."

# Optional: For real web search
uv pip install tavily-python
export TAVILY_API_KEY="tvly-..."  # Free tier: https://tavily.com

# Run with real LLM
python research_agent_demo.py
```

This demo shows Tenuo's key capabilities:
- **Delegation chains**: Control Plane -> Orchestrator -> Worker
- **Attenuation**: Each hop narrows capabilities (can't exceed parent)
- **Cryptographic audit**: Signed proof of every action
- **Multi-agent separation**: Different workers get different capabilities
- **Prompt injection defense**: Warrant blocks unauthorized actions
- **Multi-mission isolation**: Same worker, different mission warrants
- **Real LLM integration**: OpenAI GPT with warrant-protected tools (or dry-run)
- **High-level templates**: `FileReader`, `WebSearcher`, `DatabaseReader` for easy adoption

---

## Available Examples

### Basics
- **[basic_usage.py](basic_usage.py)**: The "Hello World" of Tenuo. Shows how to create a keypair, issue a warrant, and authorize a tool call. Demonstrates POLA (Principle of Least Authority) with explicit capabilities.
- **[trust_cliff_demo.py](trust_cliff_demo.py)**: Demonstrates the "Trust Cliff" - once you add ANY constraint, unknown arguments are rejected. Shows `_allow_unknown`, `Wildcard()`, and non-inheritance during attenuation.
- **[clearance_demo.py](clearance_demo.py)**: Shows how to assign clearance levels to warrants and configure clearance requirements per tool (gateway policy). Demonstrates clearance hierarchy enforcement and defense in depth.
- **[issuer_execution_pattern.py](issuer_execution_pattern.py)**: **RECOMMENDED PATTERN** - Shows the production best practice: ISSUER warrants for planners, EXECUTION warrants for workers. Demonstrates clearance levels and separation of concerns. **Start here for production deployments.**
- **[decorator_example.py](decorator_example.py)**: Demonstrates the `@guard` decorator pattern for protecting functions with minimal boilerplate.
- **[context_pattern.py](context_pattern.py)**: Shows how to use `warrant_scope` for thread-safe/async-safe warrant passing (essential for web frameworks like FastAPI).

### Multi-Agent Delegation
- **[orchestrator_worker.py](orchestrator_worker.py)**: **Core delegation pattern** - Shows how orchestrators attenuate warrants for workers. Demonstrates Tenuo's key value: authority that shrinks as it flows through the system. Essential for understanding multi-agent workflows.

### MCP Integration
- **[research_agent_demo.py](research_agent_demo.py)**: **RUNNABLE DEMO** - Pure Python MCP demo with delegation chains, attenuation, and cryptographic audit. Uses mock or real Tavily search. **Best first demo!**
- **[mcp_research_server.py](mcp_research_server.py)**: The MCP server used by `research_agent_demo.py`. Demonstrates `web_search`, `write_file`, `read_file` tools.

### LangChain Integration
- **[langchain/](langchain/)**: Complete LangChain and LangGraph integration examples
  - **[simple.py](langchain/simple.py)**: Minimal example of protecting LangChain tools. **Start here for LangChain integration.**
  - **[integration.py](langchain/integration.py)**: Advanced integration with callbacks and context propagation
  - **[protect_tools.py](langchain/protect_tools.py)**: Securing third-party tools from `langchain_community`
  - **[mcp_integration.py](langchain/mcp_integration.py)**: LangChain + MCP + Tenuo complete integration
  - **[langgraph_protected.py](langchain/langgraph_protected.py)**: State-aware agents with checkpointing (serialization, key binding, TenuoToolNode)
  - **[langgraph_mcp_integration.py](langchain/langgraph_mcp_integration.py)**: LangGraph + MCP integration

### OpenAI Integration
- **[openai/](openai/)**: Complete OpenAI integration examples
  - **[guardrails.py](openai/guardrails.py)**: Tier 1 runtime guardrails (no warrants)
  - **[warrant.py](openai/warrant.py)**: Tier 2 cryptographic authorization with PoP
  - **[async_patterns.py](openai/async_patterns.py)**: Async/streaming patterns with TOCTOU protection
  - **[agents_sdk.py](openai/agents_sdk.py)**: OpenAI Agents SDK integration

### AutoGen Integration
- **[autogen_demo_unprotected.py](autogen_demo_unprotected.py)**: AgentChat workflow with no protections (baseline/attack illustration).
- **[autogen_demo_protected_tools.py](autogen_demo_protected_tools.py)**: Guarded tools with UrlSafe allowlist + Subpath.
- **[autogen_demo_protected_attenuation.py](autogen_demo_protected_attenuation.py)**: Per-agent attenuation + escalation blocking.
- **[autogen_demo_guardbuilder_tier1.py](autogen_demo_guardbuilder_tier1.py)**: GuardBuilder (constraints-only) with on_denial raise/log/skip.
- **[autogen_demo_guardbuilder_tier2.py](autogen_demo_guardbuilder_tier2.py)**: GuardBuilder with warrant + PoP (Tier 2).

### Google ADK Integration
- **[google_adk_incident_response/](google_adk_incident_response/)**: **Multi-Agent Security Demo** - Detector, Analyst, and Responder agents with warrant-based authorization. Shows Tier 2 protection with monotonic attenuation.
- **[google_adk_a2a_incident/](google_adk_a2a_incident/)**: **Distributed A2A Demo** - Same incident response scenario but with real A2A HTTP calls between separate agent processes. Shows warrant delegation over the network.

### A2A (Agent-to-Agent) Integration
- **[a2a_demo.py](a2a_demo.py)**: **Research Pipeline Demo** - Multi-agent delegation with warrant-based authorization. Shows User -> Orchestrator -> Worker flow with constraint attenuation and attack scenarios.

**Security Constraints:**
- `Subpath("/data")` - Blocks path traversal attacks (normalizes `../` before checking containment)
- `UrlSafe()` - Blocks SSRF attacks (private IPs, metadata endpoints, IP encoding bypasses)

### MCP (Model Context Protocol)
- **[mcp_integration.py](mcp_integration.py)**: Demonstrates how to integrate Tenuo with MCP servers, extracting constraints from MCP tool calls.

### Web Frameworks
- **[fastapi_integration.py](fastapi_integration.py)**: Complete FastAPI application with Tenuo authorization. Shows:
    - Middleware for warrant extraction and context setting
    - Multiple protected endpoints
    - Error handling and proper HTTP responses
    - SigningKey loading from secrets
    - Request-scoped warrant validation

### Error Handling
- **[error_handling_guide.py](error_handling_guide.py)**: Comprehensive error handling patterns. Covers:
    - Common error scenarios (expired warrants, PoP failures, constraint violations)
    - Error classification and severity levels
    - Recovery strategies (when to retry vs abort)
    - Production-ready error handling patterns

### Infrastructure
- **[kubernetes_integration.py](kubernetes_integration.py)**: A complete simulation of a Kubernetes deployment. Shows how to:
    - Load identity keys from volume mounts
    - Read warrants from headers
    - Use the context pattern in a mock service

## Running Examples

All examples are standalone scripts. You can run them directly:

```bash
# Basic examples (no dependencies beyond tenuo)
python basic_usage.py
python clearance_demo.py  # Clearance level enforcement
python decorator_example.py
python context_pattern.py

# Multi-agent delegation (core pattern)
python orchestrator_worker.py

# Featured MCP demo (requires: uv pip install "tenuo[mcp,langchain]" langchain-openai langgraph)
# Also requires: OPENAI_API_KEY (TAVILY_API_KEY optional for real search)
python research_agent_demo.py

# LangChain examples (requires: uv pip install langchain langchain-openai langchain-community)
python langchain/simple.py
python langchain/integration.py
python langchain/protect_tools.py
python langchain/mcp_integration.py  # LangChain + MCP + Tenuo

# LangGraph example (requires: uv pip install langgraph)
python langchain/langgraph_protected.py
python langchain/langgraph_mcp_integration.py

# OpenAI examples (requires: uv pip install openai)
python openai/guardrails.py     # Tier 1: runtime guardrails
python openai/warrant.py        # Tier 2: cryptographic authorization
python openai/async_patterns.py # Async/streaming patterns
python openai/agents_sdk.py     # Agents SDK integration

# Google ADK examples (requires: uv pip install tenuo[adk])
python google_adk_incident_response/demo.py  # Multi-agent incident response

# A2A examples (requires: uv pip install tenuo[a2a])
python a2a_demo.py              # Research pipeline with delegation

# MCP example (uses local config file, no external server needed)
python mcp_integration.py

# Web framework example (requires: uv pip install fastapi uvicorn)
python fastapi_integration.py
# Or run with: uvicorn fastapi_integration:app --reload

# Error handling guide
python error_handling_guide.py

# Kubernetes example (simulation, no actual K8s needed)
python kubernetes_integration.py
```

## Key Concepts Demonstrated

1. **Zero-Intrusion**: Tools don't import Tenuo security code. Security is applied via decorators or wrappers, keeping business logic clean.
2. **Context Propagation**: Warrants are passed via `ContextVar`, making them thread-safe and async-safe. Perfect for web frameworks like FastAPI.
3. **Fail-Closed**: Missing warrants block execution. If no warrant is in context, authorization fails by default.
4. **PoP Automation**: Proof-of-Possession signatures are generated automatically by the SDK when using `@guard` or `guard()`.
5. **Closed-World Constraints (Trust Cliff)**: Once you add ANY constraint, unknown arguments are rejected. Use `_allow_unknown=True` to opt out, or `Wildcard()` to explicitly allow fields. See [trust_cliff_demo.py](trust_cliff_demo.py).

## Learning Path

**New to Tenuo?** Start here:
1. `research_agent_demo.py` - **Best first demo!** Real OpenAI + web search with guardrails
2. `basic_usage.py` - Core concepts (warrants, constraints, attenuation, POLA)
3. `clearance_demo.py` - Clearance level enforcement
4. `decorator_example.py` - Simplest protection pattern
5. `context_pattern.py` - Context-based patterns (for web frameworks)
6. `orchestrator_worker.py` - **Multi-agent delegation (core value proposition)**

**Integrating with LangChain?**
1. `research_agent_demo.py` - **Start here!** Complete runnable demo
2. `langchain/simple.py` - Basic LangChain protection
3. `langchain/protect_tools.py` - Protecting third-party tools
4. `langchain/integration.py` - Advanced callback patterns

**Integrating with OpenAI?**
1. `openai/guardrails.py` - **Start here!** Tier 1 runtime protection
2. `openai/warrant.py` - Tier 2 cryptographic authorization
3. `openai/agents_sdk.py` - Agents SDK guardrails

**Production Patterns:**
- `orchestrator_worker.py` - **Multi-agent delegation (understand this first!)**
- `langchain/langgraph_protected.py` - **State-aware agents with checkpointing (LangGraph)**
- `fastapi_integration.py` - Complete web application with authorization
- `error_handling_guide.py` - Production error handling strategies
- `kubernetes_integration.py` - Real-world deployment patterns
- `mcp_integration.py` - MCP server integration

**Note:** Queue integration patterns (RabbitMQ, SQS, etc.) will be available in v0.2 with framework-specific packages to reduce boilerplate.
