lockstock-integrations 2.0.0rc8

LockStock compliance runtime integrations for AI Agent SDKs - thin SaaS client with idempotency

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

# 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).

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:

pip install lockstock-integrations[fastapi]

Claude Agent SDK

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

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

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:

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

# 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.