Metadata-Version: 2.4
Name: air-blackbox-sdk
Version: 0.1.1
Summary: Python SDK for AIR Blackbox Gateway — record, replay, and govern every AI decision
Author-email: Jason Shotwell <jason.j.shotwell@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/airblackbox/gateway
Project-URL: Repository, https://github.com/airblackbox/python-sdk
Project-URL: Issues, https://github.com/airblackbox/python-sdk/issues
Project-URL: Documentation, https://github.com/airblackbox/python-sdk#readme
Keywords: ai,llm,audit,governance,openai,langchain,crewai,compliance,accountability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: langchain
Requires-Dist: langchain-openai>=0.1.0; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1.0; extra == "crewai"
Requires-Dist: langchain-openai>=0.1.0; extra == "crewai"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: langchain-openai>=0.1.0; extra == "all"
Requires-Dist: crewai>=0.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# AIR SDK for Python

[![CI](https://github.com/airblackbox/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/airblackbox/python-sdk/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue?logo=python&logoColor=white)](https://python.org)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

**Record every AI decision your agents make. One line of code.**

AIR SDK connects your Python AI applications to the [AIR Blackbox Gateway](https://github.com/airblackbox/gateway) — giving you tamper-evident audit trails, compliance reporting, and deterministic replay without changing how you write code.

## Install

```bash
pip install air-blackbox-sdk
```

With framework extras:
```bash
pip install air-blackbox-sdk[openai]      # OpenAI integration
pip install air-blackbox-sdk[langchain]   # LangChain integration
pip install air-blackbox-sdk[crewai]      # CrewAI integration
pip install air-blackbox-sdk[all]         # Everything
```

## Quickstart

### OpenAI (3 lines)

```python
from openai import OpenAI
import air

client = air.air_wrap(OpenAI())

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is a flight recorder?"}],
)
print(response.choices[0].message.content)
# Every call recorded with tamper-evident audit trail
```

### LangChain (2 lines)

```python
from air.integrations.langchain import air_langchain_llm

llm = air_langchain_llm("gpt-4o-mini")
response = llm.invoke("Explain tamper-evident logging.")
print(response.content)
# Works with chains, agents, and tools
```

### CrewAI (swap one import)

```python
from crewai import Agent, Task, Crew
from air.integrations.crewai import air_crewai_llm

llm = air_crewai_llm("gpt-4o-mini")
agent = Agent(role="Researcher", goal="Find facts", llm=llm)
task = Task(description="Research AI safety", agent=agent,
            expected_output="A brief report.")
crew = Crew(agents=[agent], tasks=[task])
crew.kickoff()
# Every agent LLM call recorded in AIR
```

### Direct Client

```python
from air import AIRClient

with AIRClient() as client:
    # Chat through the gateway
    result = client.chat(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-4o-mini",
    )
    print(result["_air"]["run_id"])  # Your audit trail ID

    # Check compliance status
    audit = client.audit(gateway_key="your-key")

    # Export signed evidence for regulators
    evidence = client.export_evidence(gateway_key="your-key")
```

## Configuration

| Environment Variable | Default | Description |
|---|---|---|
| `AIR_GATEWAY_URL` | `http://localhost:8080` | AIR gateway URL |
| `OPENAI_API_KEY` | *(none)* | Your LLM provider API key |
| `AIR_TIMEOUT` | `120` | Request timeout in seconds |

## What You Get

When your code runs through AIR, every LLM call automatically gets:

- **Tamper-evident audit trail** — HMAC-SHA256 chain, modify one record and the chain breaks
- **Vault-backed content** — prompts and completions in your S3/MinIO, not third-party clouds
- **Compliance reporting** — 22 controls across SOC 2 and ISO 27001, auto-evaluated
- **Signed evidence export** — hand your auditor a single JSON document
- **Deterministic replay** — reproduce any AI decision from the audit record

## Part of the AIR Ecosystem

This SDK is the developer entry point to the [AIR Blackbox Gateway](https://github.com/airblackbox/gateway) infrastructure:

| Component | What It Does |
|---|---|
| **python-sdk** (this repo) | Python integrations for OpenAI, LangChain, CrewAI |
| [gateway](https://github.com/airblackbox/gateway) | Core proxy + vault + audit chain + compliance |
| [air-platform](https://github.com/airblackbox/air-platform) | Docker Compose orchestration |
| [agent-episode-store](https://github.com/airblackbox/agent-episode-store) | Episode-level audit grouping |
| [agent-policy-engine](https://github.com/airblackbox/agent-policy-engine) | Risk-tiered autonomy + runtime policy |

## License

Apache-2.0
