lockstock-integrations 2.0.0rc9
LockStock compliance runtime integrations for AI Agent SDKs - thin SaaS client with idempotency
Requires Python: >=3.10
Keywords: ai-agents, audit, authentication, compliance, lockstock

# LockStock Integrations

Universal compliance runtime for AI Agent SDKs. LockStock provides cryptographic identity, capability authorization, and audit trails for agents running on any framework.

## What's New in 2.0.0

- **Thin SaaS Client**: No local crypto, no Guard daemon required
- **Built-in Idempotency**: Safe retries on network failures without double-advancing the chain
- **Automatic Retry**: Exponential backoff for transient errors (502, 503, 504, timeouts)
- **Sequence Tracking**: Detects stale clients and provides resync diagnostics

## Supported Frameworks

| Integration | Framework | Status |
|-------------|-----------|--------|
| `lockstock_fastapi` | FastAPI (Thin Middleware) | **Stable** |
| `lockstock_claude` | Claude Agent SDK | Alpha |
| `lockstock_openai` | OpenAI Agents SDK | Alpha |
| `lockstock_langgraph` | LangGraph | Alpha |
| `lockstock_a2a` | A2A Protocol | Alpha |
| `lockstock_adk` | Google ADK | Planned |
| `lockstock_crewai` | CrewAI | Planned |

## Installation

```bash
# FastAPI thin middleware (recommended for SaaS)
pip install lockstock-integrations[fastapi]

# Install with specific framework support
pip install lockstock-integrations[claude]
pip install lockstock-integrations[openai]
pip install lockstock-integrations[langgraph]

# Install with all frameworks
pip install lockstock-integrations[all]
```

## Quick Start

### FastAPI Inference Servers (Recommended)

The thin middleware stamps every request and response via the `/v1/stamp` API with zero local crypto. Supports SSE streaming for LLM responses. Fail-closed by default (no stamp = no action).

```python
from fastapi import FastAPI
from lockstock_fastapi import LockStockThinMiddleware

app = FastAPI()

app.add_middleware(
    LockStockThinMiddleware,
    agent_id="agent_xxx_name",
    api_key="lsk_admin_...",
    path_tasks={
        "/v1/chat/completions": "chatcompletion",
        "/v1/models": "network",
        "/health": None,  # Excluded from stamping
    },
    # Defaults (no configuration needed):
    # - response_tasks auto-inferred: chatcompletion -> chatcompletionRESPONSE
    # - block_on_rejection=True: fail-closed, 503 if stamp fails
)
```

Install with:
```bash
pip install lockstock-integrations[fastapi]
```

### Claude Agent SDK

```python
from lockstock_claude import LockStockHook

# Create hook with your agent credentials
hook = LockStockHook(
    agent_id="agent_abc123",
    api_key="lsk_admin_...",
    endpoint="https://lockstock-api-i9kp.onrender.com"
)

# Use as pre-tool-execution hook
# The hook will verify capabilities before each tool call
```

### OpenAI Agents SDK

```python
from lockstock_openai import LockStockGuardrail

guardrail = LockStockGuardrail(agent_id="agent_abc123")

# Add to your agent's guardrails
agent = Agent(
    name="my-agent",
    guardrails=[guardrail]
)
```

### LangGraph

```python
from lockstock_langgraph import lockstock_middleware

# Wrap your graph with LockStock middleware
app = lockstock_middleware(
    graph=your_graph,
    agent_id="agent_abc123"
)
```

## Direct API Usage

For custom integrations, use the core client directly:

```python
from lockstock_core import LockStockClient

async with LockStockClient(
    agent_id="agent_xxx",
    api_key="lsk_admin_...",
) as client:
    # Stamp a capability (with automatic retry and idempotency)
    result = await client.stamp("chatcompletion")

    if result.authorized:
        print(f"Authorized! Sequence: {result.sequence}")
    else:
        print(f"Denied: {result.reason}")
```

### Idempotency Guarantees

Every `stamp()` call automatically:
1. Generates a unique idempotency key (UUID)
2. Retries on transient failures (timeouts, 502/503/504)
3. Returns cached response on retry if server already processed
4. Never double-advances the chain on network failures

```python
# Safe to retry - same logical request
result = await client.stamp("deploy")  # Network timeout
result = await client.stamp("deploy")  # Returns cached response, chain at same position
```

## Architecture

### Thin Middleware (SaaS)
```
┌─────────────────────────────────────────────────────────────────┐
│                     YOUR FASTAPI SERVER                         │
│              (LLM inference, chat completions, etc.)            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│               LOCKSTOCK THIN MIDDLEWARE                         │
│                                                                  │
│  • Pure ASGI (no buffering - supports SSE streaming)           │
│  • Calls /v1/stamp API (server does all crypto)                │
│  • Injects X-LockStock-* headers into response                 │
│  • Auto response stamping (fire-and-forget, non-blocking)      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     LOCKSTOCK CORE API                          │
│                                                                  │
│  • /v1/stamp - Request stamping (thin clients)                 │
│  • /verify - Full verification (fat clients)                   │
│  • /bootstrap - Agent identity initialization                   │
│  • Hash chain - Cryptographic audit trail                       │
└─────────────────────────────────────────────────────────────────┘
```

### Agent SDK Integrations
```
┌─────────────────────────────────────────────────────────────────┐
│                     YOUR AGENT RUNTIME                          │
│  (Claude Agent SDK / OpenAI / LangGraph / CrewAI / ADK)        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   LOCKSTOCK INTEGRATION                         │
│                                                                  │
│  • Pre-tool-execution hooks                                     │
│  • Capability verification                                       │
│  • Audit trail logging                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     LOCKSTOCK CORE API                          │
│                                                                  │
│  • /verify - Capability authorization                           │
│  • /bootstrap - Agent identity initialization                   │
│  • Hash chain - Cryptographic audit trail                       │
└─────────────────────────────────────────────────────────────────┘
```

## License

MIT License - See LICENSE file for details.