# APCE Safety

**Attention Provenance & Conservation Engine**

Runtime verification for transformer models using conservation laws. Mathematical guarantees for AI safety.

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.9+-green.svg)](https://python.org)
[![PyPI](https://img.shields.io/badge/PyPI-v0.1.0-orange.svg)](https://pypi.org/project/apce-safety/)

## The Insight

Every row of the attention matrix sums to exactly 1. Not approximately — exactly. It's a conservation law, enforced at every layer, every head, every token, since Vaswani 2017.

We hash it. Every layer. Merkle chain. Cryptographic proof of the entire computational path.

**Result: Velado's Contradiction Theorem**

```
D(ε) × I(ε) ≥ κ
```

Attackers face a geometric impossibility. They can hide, or they can cause harm. Not both.

## Key Metrics

| Metric | Value |
|--------|-------|
| Detection Rate | 100% |
| Overhead | 2.7% at 7B |
| FlashAttention | ✓ Compatible |
| Attacks Tested | 10,000+ |

## Installation

```bash
# Core package
pip install apce-safety

# With Anthropic Claude support
pip install apce-safety[anthropic]

# With OpenAI GPT support  
pip install apce-safety[openai]

# With local Llama/Transformers support
pip install apce-safety[llama]

# Full installation
pip install apce-safety[full]
```

## Quick Start

### Wrap Claude with Verification

```python
from apce.wrappers import ClaudeWrapper

wrapper = ClaudeWrapper(api_key="sk-ant-...")

response = wrapper.chat([
    {"role": "user", "content": "Explain conservation laws in physics"}
])

print(response.content)
print(f"Verified: {response.verified}")
print(f"Provenance: {response.provenance.merkle_root}")
```

### Wrap GPT with Audit Trails

```python
from apce.wrappers import GPTWrapper

wrapper = GPTWrapper(api_key="sk-...")

response = wrapper.chat([
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is machine learning?"}
])

# Export provenance for compliance
audit_record = response.provenance.to_json()
```

### Full Verification with Local Models

```python
from apce.wrappers import LlamaWrapper
from apce import VerificationMode

wrapper = LlamaWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    mode=VerificationMode.THOROUGH,
    device="cuda"
)

response = wrapper.chat([
    {"role": "user", "content": "Hello!"}
])

# Full 8-signal manifold analysis (only available with local models)
print(f"Conservation deviation: {response.analysis.conservation_deviation.value}")
print(f"Entropy fingerprint: {response.analysis.entropy_fingerprint.value}")
print(f"Signals violated: {response.analysis.violation_count}")
```

### Direct Attention Verification

```python
import numpy as np
from apce import APCEVerifier, VerificationMode

# Your attention weights from model
attention = np.random.softmax(np.random.randn(1, 8, 512, 512), axis=-1)

verifier = APCEVerifier(mode=VerificationMode.BALANCED)
result = verifier.verify_attention(attention)

print(f"Valid: {result.is_valid}")
for signal in result.signals:
    print(f"  {signal.name}: {signal.value:.6f} (violated: {signal.violated})")
```

### EU AI Act Watermarking

```python
from apce.compliance import Watermarker

wm = Watermarker(model_id="gpt-4", organization="Acme Corp")

# Watermark AI output (invisible to users)
marked_text = wm.watermark_text(
    "This is AI-generated content...",
    provenance_hash="abc123..."
)

# Later verification
is_valid, metadata = wm.verify_text(marked_text)
if is_valid:
    print(f"Generated by {metadata.model_id} at {metadata.timestamp}")
```

## Verification Modes

| Mode | Sampling | Overhead | Detection |
|------|----------|----------|-----------|
| TURBO | 5% | 0.5% | 88% |
| BALANCED | 10% | 0.8% | 92% |
| THOROUGH | 25% | 1.2% | 96% |
| ESCALATION | Adaptive | 0.8-2.7% | **100%** |

## 8-Signal Manifold Analysis

APCE monitors 8 orthogonal signals:

1. **Conservation Deviation** - Σⱼ Aᵢⱼ deviation from 1.0
2. **Entropy Fingerprint** - Information content of attention
3. **Sparsity Index** - Attention concentration pattern
4. **Top-K Checksum** - Dominant attention weight verification
5. **Geometric Curvature** - Manifold shape anomaly detection
6. **Layer Hash Chain** - BLAKE3 cryptographic provenance
7. **Numerical Stability** - NaN/Inf/subnormal detection
8. **Temporal Consistency** - Cross-layer pattern coherence

## Compliance Coverage

### EU AI Act

| Article | Requirement | APCE Coverage |
|---------|-------------|---------------|
| Art. 9 | Risk Management | ✓ Conservation law enforcement |
| Art. 10 | Data Governance | ✓ Cryptographic provenance |
| Art. 11 | Technical Documentation | ✓ Merkle proof export |
| Art. 12 | Record-Keeping | ✓ BLAKE3 hash chains |
| Art. 13 | Transparency | ✓ Watermarking module |
| Art. 15 | Accuracy & Robustness | ✓ 100% adversarial detection |

### NIST IR 8596

85-90% coverage of Cybersecurity Framework for AI requirements.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Your Application                         │
├─────────────────────────────────────────────────────────────┤
│  ClaudeWrapper  │  GPTWrapper  │  LlamaWrapper  │  Custom   │
├─────────────────────────────────────────────────────────────┤
│                      APCEVerifier                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Conservation │  │   Manifold   │  │  Provenance  │       │
│  │   Checking   │  │   Analysis   │  │   Chaining   │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
├─────────────────────────────────────────────────────────────┤
│                 Compliance (Watermark, Audit)                │
└─────────────────────────────────────────────────────────────┘
```

## Security Model

**Velado's Contradiction Theorem** proves that for any perturbation ε:

```
D(ε) × I(ε) ≥ κ
```

Where:
- D(ε) = detection probability
- I(ε) = impact/damage of perturbation
- κ = security constant > 0

The "get away with it" quadrant (low detection + high impact) is **mathematically empty**.

## Patent Coverage

18 patent applications filed covering:
- Conservation law verification
- FlashAttention compatibility (FlashAPCE)
- Contradiction Theorem proofs
- Byzantine fault tolerance

## Academic Validation

- 5 peer-reviewed publications on Zenodo
- CCS 2026 submission in review
- 10,000+ adversarial samples tested

## License

Apache 2.0

## Author

**Rafael Velado**  
Principal, Atomic Trust  
raf@atomic-trust.com  
https://atomic-trust.com

---

*"Every row sums to one. We just started paying attention to it."*
