iron-cage 0.2.0

Iron SDK - Python SDK for AI agent protection with LLM proxy and safety controls

Iron Cage

Python SDK for Iron Cage AI agent protection. Provides LlmRouter and Runtime for protecting AI agents with budget tracking, safety controls, and LLM API proxying.

Installation

uv pip install iron-cage

[!IMPORTANT] Requirements: Python 3.9+ (python --version)

Quick Start

from iron_cage import LlmRouter
from openai import OpenAI

# Use with Iron Cage server
with LlmRouter(api_key="ic_xxx", server_url="https://api.iron-cage.io") as router:
    client = OpenAI(base_url=router.base_url, api_key=router.api_key)
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

# Or with direct provider key (for testing)
with LlmRouter(provider_key="sk-xxx", budget=10.0) as router:
    client = OpenAI(base_url=router.base_url, api_key=router.api_key)
    # ... use client

Architecture

Iron Cage uses a two-crate architecture:

Crate	Language	Purpose
iron_runtime	Pure Rust	Core implementation - LlmRouter, AgentRuntime, policies
iron_sdk (folder)	Rust + Python	PyO3 bindings exposing iron_runtime to Python

Package Hierarchy:

What you install:  uv pip install iron-cage
What you import:   from iron_cage import LlmRouter, Runtime
Internal:          iron_runtime (Rust crate, linked at compile time)

Key Features

• LLM Proxy: Local HTTP proxy that intercepts OpenAI/Anthropic API requests
• Budget Control: Set and track spending limits in USD
• Auto-detection: Automatically detects provider from API key format
• Context Manager: Clean resource management with with statement
• Type Stubs: Full IDE support with .pyi files

API Reference

LlmRouter

LlmRouter(
    api_key: str = None,           # Iron Cage API token
    server_url: str = None,        # Iron Cage server URL
    cache_ttl_seconds: int = 300,  # API key cache TTL
    budget: float = None,          # Budget limit in USD
    provider_key: str = None,      # Direct provider API key
)

Properties:

• base_url - URL for OpenAI client (e.g., "http://127.0.0.1:52431/v1")
• api_key - API key to use with client
• port - Port the proxy is listening on
• provider - Detected provider ("openai" or "anthropic")
• is_running - Whether proxy is running
• budget - Current budget limit in USD
• budget_status - Tuple of (spent, limit) in USD

Methods:

• total_spent() - Get total spent in USD
• set_budget(amount_usd) - Set budget limit
• stop() - Stop the proxy server

Runtime

Runtime(
    budget: float,           # Budget limit in USD
    verbose: bool = False,   # Enable verbose logging
)

Properties:

• budget - Budget limit
• verbose - Verbose setting

Methods:

• start_agent(script_path) - Start an agent
• stop_agent(agent_id) - Stop an agent
• get_metrics(agent_id) - Get agent metrics as JSON

Optional Dependencies

# LangChain integration
uv pip install iron-cage[langchain]

# CrewAI integration
uv pip install iron-cage[crewai]

# All integrations
uv pip install iron-cage[all]

# Examples dependencies
uv pip install iron-cage[examples]

Examples

See examples/ directory for runnable examples:

• examples/langchain/ - LangChain integration examples
• examples/crewai/ - CrewAI integration examples
• examples/raw_api/ - Direct API usage examples
• examples/patterns/ - Protection pattern examples

Run examples:

python examples/lead_gen_agent.py

Development

# Build the Python package
cd module/iron_sdk
maturin develop

# Run tests
pytest tests/

Documentation

• Specification: See spec.md for complete technical requirements
• Examples: See examples/ directory

License

Apache-2.0 - See license file for details