Metadata-Version: 2.4
Name: swt3-ai
Version: 0.2.1
Summary: SWT3 AI Witness SDK — cryptographic attestation for AI inference
Project-URL: Homepage, https://tenova.io
Project-URL: Documentation, https://docs.tenova.io/swt3-ai
Project-URL: Repository, https://github.com/tenova/swt3-ai
Author-email: TeNova <engineering@tenovaai.com>
License: Apache-2.0
Keywords: ai,attestation,compliance,eu-ai-act,nist-ai-rmf,swt3,witness
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: anthropic>=0.20; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

Witness your AI, don't just run it. Cryptographic provenance for LLMs with zero data retention.

# swt3-ai

**SWT3 AI Witness SDK**:continuous, cryptographic attestation for AI systems. Prove your models are running approved weights, safety guardrails are active, inferences are traceable, and fairness thresholds are met. All without your prompts or responses ever leaving your infrastructure.

Built on the [SWT3 Protocol](https://tenova.io/swt3), the same cryptographic witnessing layer trusted for federal compliance (NIST 800-53, CMMC, FedRAMP).

## Three Lines of Code

```python
from swt3_ai import Witness
from openai import OpenAI

witness = Witness(
    endpoint="https://sovereign.tenova.io",
    api_key="axm_live_...",
    tenant_id="YOUR_ENCLAVE",
)
client = witness.wrap(OpenAI())

# That's it. Every inference is now witnessed.
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this contract..."}],
)
# response is untouched, use it exactly as before
print(response.choices[0].message.content)
```

No code changes. No performance impact. No data leakage.

## What Happens Per Inference

1. **Intercept**: The SDK wraps your AI client transparently
2. **Hash**: Prompts and responses are SHA-256 hashed locally
3. **Extract**: Model version, latency, token count, guardrail status captured as numeric factors
4. **Clear**: Raw text is purged from the wire payload (configurable clearing level)
5. **Anchor**: Factors are batched and flushed to the SWT3 Witness Ledger in the background
6. **Return**: Your original response returns untouched, zero added latency

The result: an immutable, cryptographic proof that your AI followed the rules, without the auditor ever needing to see the sensitive data.

## Supported Providers

| Provider | Client | Status |
|----------|--------|--------|
| OpenAI | `openai.OpenAI` | **Supported** |
| Anthropic | `anthropic.Anthropic` | **Supported** |
| AWS Bedrock | `bedrock-runtime` | Planned |
| Azure OpenAI | `openai.AzureOpenAI` | Planned |
| Ollama / vLLM | Local models | Planned |

### OpenAI

```python
from swt3_ai import Witness
from openai import OpenAI

witness = Witness(endpoint="...", api_key="axm_...", tenant_id="...")
client = witness.wrap(OpenAI())

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

### Anthropic

```python
from swt3_ai import Witness
from anthropic import Anthropic

witness = Witness(endpoint="...", api_key="axm_...", tenant_id="...")
client = witness.wrap(Anthropic())

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

## Clearing Levels

The Clearing Engine controls what leaves your infrastructure. Your code always gets the full response. Clearing only affects the wire payload sent to the witness ledger.

| Level | Name | What's on the wire | Use case |
|-------|------|-------------------|----------|
| 0 | Analytics | Hashes + factors + model ID + provider + guardrail names | Internal analytics, non-sensitive workloads |
| 1 | Standard | Hashes + factors + model ID + provider metadata | **Default.** Production SaaS, enterprise apps |
| 2 | Sensitive | Hashes + factors + model ID only | Healthcare, legal, PII-adjacent workloads |
| 3 | Classified | Numeric factors only. Model ID hashed. No metadata. | Defense, classified environments, air-gapped |

```python
# Level 2: Sensitive, no provider names, no guardrail names on the wire
witness = Witness(
    endpoint="...",
    api_key="axm_...",
    tenant_id="...",
    clearing_level=2,
)
```

At Level 1+, raw prompts and responses **never leave your infrastructure**. Only SHA-256 hashes and numeric factors travel on the wire. This satisfies both GDPR Article 17 (right to erasure) and EU AI Act Article 12 (record-keeping) simultaneously.

## What Gets Witnessed

Each inference produces anchors for these AI procedures:

| Procedure | Domain | What it proves |
|-----------|--------|---------------|
| AI-INF.1 | Inference | Prompt and response were captured (provenance) |
| AI-INF.2 | Inference | Latency within threshold (detects model swaps) |
| AI-MDL.1 | Model | Deployed model matches approved hash (integrity) |
| AI-MDL.2 | Model | Model version identifier recorded (tracking) |
| AI-GRD.1 | Guardrail | Required safety filters were active (enforcement) |
| AI-GRD.2 | Safety | No refusal or content filter triggered (content safety) |

Each procedure maps to both **NIST AI RMF** functions and **EU AI Act** articles. When a CISO looks at the ledger, they don't see "inference captured." They see "Article 12 Compliance: Verified."

## Resilience (Flight Recorder)

The SDK never blocks your inference call. Witnessing happens in a background thread.

If the witness endpoint is unreachable (network outage, air-gapped deployment), payloads move to a **dead-letter queue** instead of being dropped. When connectivity is restored, the backlog drains automatically with exponential backoff.

```python
witness = Witness(
    endpoint="...",
    api_key="axm_...",
    tenant_id="...",
    buffer_size=50,       # flush every 50 anchors
    flush_interval=10.0,  # or every 10 seconds
    max_retries=5,        # retry 5 times before dead-lettering
)

# Check dead-letter status
print(f"Pending: {witness.pending}")
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `endpoint` | *required* | Witness endpoint URL |
| `api_key` | *required* | API key (`axm_*` prefix) |
| `tenant_id` | *required* | Your enclave identifier |
| `clearing_level` | `1` | Clearing level (0-3) |
| `buffer_size` | `10` | Flush after N anchors |
| `flush_interval` | `5.0` | Flush after N seconds |
| `timeout` | `10.0` | HTTP timeout for flush |
| `max_retries` | `3` | Retry count before dead-letter |
| `latency_threshold_ms` | `30000` | AI-INF.2 latency threshold |
| `guardrails_required` | `0` | AI-GRD.1 required guardrail count |
| `guardrail_names` | `[]` | Names of active guardrails |
| `factor_handoff` | `None` | `"file"` to enable local factor export |
| `factor_handoff_path` | `None` | Directory for factor handoff files |

## Factor Handoff (Clearing Level 2+)

At Clearing Level 2 or 3, some or all verifiable data is stripped from the wire before it reaches the witness endpoint. The Factor Handoff ensures your factors are safely written to a local directory **before** clearing proceeds. If the write fails, the payload is not transmitted.

```python
witness = Witness(
    endpoint="https://sovereign.tenova.io",
    api_key="axm_live_...",
    tenant_id="YOUR_ENCLAVE",
    clearing_level=3,
    factor_handoff="file",
    factor_handoff_path="/secure/vault/factors/",
)
```

Each anchor gets its own JSON file (named by fingerprint) containing the full uncleared factors and metadata needed for independent re-verification. Files are written with 0600 permissions.

For the full protocol specification, see the [Factor Handoff Protocol](https://sovereign.tenova.io/docs/factor-handoff-protocol.html).

## Custom Pipelines

For non-standard LLM integrations, use the decorator or manual API:

```python
@witness.inference()
def my_custom_llm(prompt: str) -> str:
    # Your custom inference logic
    return result

# Or manual recording
from swt3_ai.types import InferenceRecord
from swt3_ai.fingerprint import sha256_truncated

record = InferenceRecord(
    model_id="my-model-v2",
    model_hash=sha256_truncated("my-model-v2"),
    prompt_hash=sha256_truncated(prompt),
    response_hash=sha256_truncated(response),
    latency_ms=elapsed_ms,
    provider="custom",
)
witness.record(record)
```

## Installation

```bash
pip install swt3-ai

# With provider extras
pip install swt3-ai[openai]
pip install swt3-ai[anthropic]
pip install swt3-ai[all]
```

## Regulatory Coverage

The SWT3 AI Witnessing Profile maps to:

- **EU AI Act**: Articles 9, 10, 12, 13, 14, 53, 72
- **NIST AI RMF**: GOVERN, MAP, MEASURE, MANAGE (10 subcategories)
- **ISO 42001**: Annex A AI management controls
- **NIST 800-53**: SI-7 (integrity), AU-2/AU-3 (audit), AC controls

## AI Witness-as-a-Service

SWT3 AI Witness is available as a managed service:

| Tier | Anchors/mo | Retention | AI Systems | Price |
|------|-----------|-----------|------------|-------|
| **Developer** | 10K | 30 days | 1 | Free |
| **Observer** | 500K | 90 days | 3 | $499/mo |
| **Sentinel** | 5M | 1 year | Unlimited | $9,500/mo |
| **Sovereign** | Unlimited | Custom | Unlimited + On-prem | $25,000/mo |

All paid tiers include the SDK, dashboard, regulatory reports, and verification CLI.

Contact: [sales@tenovaai.com](mailto:sales@tenovaai.com) | [Book a demo](https://calendly.com/tenova-axiom/30min)

## Documentation

- [SDK Developer Docs](https://sovereign.tenova.io/docs/) - Quickstart, providers, clearing levels, configuration
- [Factor Handoff Protocol](https://sovereign.tenova.io/docs/factor-handoff-protocol.html) - How factors are securely transferred to your custody
- [Clearing Protocol Terms](https://sovereign.tenova.io/terms/clearing-addendum) - Shared responsibility model and liability
- [CMMC Compliance Overlay](https://sovereign.tenova.io/guides/cmmc-overlay.html) - Control mappings for defense industrial base

---

*SWT3: Sovereign Witness Traceability. We don't run your models. We witness them.*

SWT3 and Sovereign Witness Traceability are trademarks of Tenable Nova LLC. Patent pending. Apache 2.0 licensed.
