Metadata-Version: 2.4
Name: ava-protocol
Version: 0.1.0
Summary: AVA - AI Visibility Anonymizer Protocol
Project-URL: Homepage, https://github.com/ava-protocol/ava-protocol
Project-URL: Documentation, https://ava-protocol.readthedocs.io
Project-URL: Repository, https://github.com/ava-protocol/ava-protocol
Project-URL: Bug Tracker, https://github.com/ava-protocol/ava-protocol/issues
Author-email: Gerald Enrique Nelson Mc Kenzie <lordxmen2k@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,anonymization,data-protection,gdpr,hipaa,llm,pii,presidio,privacy,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: boto3>=1.28.0; extra == 'all'
Requires-Dist: presidio-analyzer>=2.2.0; extra == 'all'
Requires-Dist: presidio-anonymizer>=2.2.0; extra == 'all'
Requires-Dist: spacy>=3.7.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.28.0; extra == 'aws'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: presidio-analyzer>=2.2.0; extra == 'local'
Requires-Dist: presidio-anonymizer>=2.2.0; extra == 'local'
Requires-Dist: spacy>=3.7.0; extra == 'local'
Description-Content-Type: text/markdown

# AVA Protocol 🛡️

**AI Visibility Anonymizer Protocol** — A protocol-first approach to privacy-preserving AI interactions.

## Authors

- Gerald Enrique Nelson Mc Kenzie (https://github.com/lordxmen2k)

## Date

- 3/13/2026


[![PyPI version](https://badge.fury.io/py/ava-protocol.svg)](https://badge.fury.io/py/ava-protocol)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

```
┌─────────────────────────────────────────────────────────┐
│                      AVA LAYER                          │
│         (AI Visibility Anonymizer Protocol)             │
├─────────────────────────────────────────────────────────┤
│  INGEST → DETECT → CLASSIFY → TRANSFORM → AUDIT → AI   │
│    ↑                                              ↓     │
│  Original Data                            Clean Response│
│    ↑                                              ↓     │
│  RESTORE ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←    │
└─────────────────────────────────────────────────────────┘
```

## 🎯 What is AVA?

AVA is an **open protocol** and **Python library** for anonymizing sensitive data before sending it to AI/LLM services, with complete audit trails and reversible tokenization.

### Core Principles

| Principle | Description |
|-----------|-------------|
| **Visibility** | Complete audit trail of what was sanitized and why |
| **Reversibility** | Secure token vault for restoring original data in responses |
| **Interoperability** | Works with any AI provider (OpenAI, Anthropic, local models) |
| **Configurability** | Policy-driven sensitivity levels per use case |
| **Engine Agnostic** | Pluggable detection engines (Presidio, AWS Macie, etc.) |

## 🚀 Quick Start

### Installation

```bash
# Core library only (gateway mode)
pip install ava-protocol

# With local detection engine (Presidio)
pip install ava-protocol[local]

# With all optional dependencies
pip install ava-protocol[all]
```

### Basic Usage

```python
import ava
import openai

# Initialize client (local Presidio engine)
client = ava.Client(
    engine="presidio",
    policy="healthcare_strict",
    retention=3600  # Token expiry in seconds
)

# Sanitize → AI → Restore
with client.session(reversibility=True) as session:
    # 1. Sanitize PII before sending to AI
    clean_prompt = session.sanitize(
        "Patient John Doe (john.doe@email.com) needs prescription refill"
    )
    # Result: "Patient AVA_PERS_7a3f9k2m (AVA_EMAI_x8n4p5qv) needs prescription refill"

    # 2. Send to AI (AI never sees original PII)
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": clean_prompt}]
    )
    ai_output = response.choices[0].message.content

    # 3. Restore original values in AI response
    original_response = session.restore(ai_output)
    # Result: "John Doe should contact john.doe@email.com..."
```

### Gateway Mode (Enterprise)

```python
import ava

# Connect to centralized AVA Gateway
client = ava.GatewayClient(
    url="https://ava.internal.company.com",
    api_key="your-api-key",
    policy="finance_strict"
)

with client.session() as session:
    clean = session.sanitize("Invoice to Acme Corp...")
    # ... AI call ...
    original = session.restore(ai_response)
```

## 📋 Supported Entity Types

| Category | Entities | Example |
|----------|----------|---------|
| Identity | `PERSON_NAME`, `USERNAME` | "John Doe" → `AVA_PERS_7a3f9k2m` |
| Contact | `EMAIL_ADDRESS`, `PHONE_NUMBER` | "john@email.com" → `AVA_EMAI_x8n4p5qv` |
| Financial | `CREDIT_CARD`, `BANK_ACCOUNT`, `SSN` | "123-45-6789" → `AVA_SSN_3x8k9n4p` |
| Location | `LOCATION`, `IP_ADDRESS` | "192.168.1.1" → `AVA_IPAD_q2m7n5vx` |
| Medical | `MEDICAL_LICENSE`, `DIAGNOSIS` | Condition-specific detection |

## 🔧 Configuration

### Environment Variables

```bash
export AVA_MODE=embedded              # or "gateway"
export AVA_ENGINE=presidio
export AVA_POLICY=healthcare_strict
export AVA_RETENTION=3600
export AVA_GATEWAY_URL=https://ava.internal.company.com
export AVA_API_KEY=your-api-key
```

### YAML Config

```yaml
# ava-config.yaml
mode: embedded
engine: presidio
policy: finance_strict
retention: 7200

# Or gateway mode:
mode: gateway
url: https://ava-gateway.company.com
api_key: ${AVA_API_KEY}
```

```python
import ava

config = ava.Config.from_yaml("ava-config.yaml")
client = ava.create_client(config)
```

## 🏗️ Architecture

### Protocol-First Design

```
┌─────────────────────────────────────┐
│         AVA PROTOCOL SPEC          │  ← The standard (IETF-bound)
├─────────────────────────────────────┤
│    AVA Python Library (this repo)   │  ← Reference implementation
│    ┌─────────────────────────┐      │
│    │  Presidio | AWS Macie   │      │  ← Pluggable engines
│    │  | Azure PII | Custom   │      │
│    └─────────────────────────┘      │
└─────────────────────────────────────┘
```

### Manifest Format

Every transformation produces an **AVA Manifest** — a complete audit record:

```json
{
  "ava_version": "1.0",
  "manifest_id": "ava-a1b2c3d4-001",
  "timestamp": "2025-03-13T15:05:59Z",
  "policy": {
    "domain": "healthcare",
    "strictness": "strict",
    "reversibility": true
  },
  "entities": [
    {
      "type": "PERSON_NAME",
      "value_hash": "sha256:7f83b...",
      "position": [8, 16],
      "confidence": 0.98,
      "action": "pseudonymize",
      "token": "AVA_PERS_7a3f9k2m"
    }
  ]
}
```

## 🔌 Pluggable Engines

Swap detection engines without changing your code:

| Engine | Installation | Best For |
|--------|--------------|----------|
| **Presidio** (default) | `pip install ava-protocol[local]` | Self-hosted, free, customizable |
| **AWS Macie** | `pip install ava-protocol[aws]` | Enterprise, cloud-native |
| **Mock** (built-in) | No install | Testing, CI/CD |
| **Custom** | Extend `DetectionEngine` | Domain-specific needs |

## 📦 Project Structure

```
ava-protocol/
├── src/ava/
│   ├── __init__.py           # Main exports
│   ├── client.py             # Client & GatewayClient
│   ├── session.py            # Transaction context
│   ├── config.py             # Configuration management
│   ├── protocol/             # Core protocol types
│   │   ├── manifest.py       # AVA Manifest
│   │   ├── entities.py       # DetectedEntity
│   │   └── token_vault.py    # Vault implementations
│   ├── engines/              # Detection engines
│   │   ├── base.py           # Abstract interface
│   │   └── presidio.py       # Presidio adapter
│   └── gateways/             # Remote gateway clients
│       └── http.py           # REST client
├── tests/                    # Test suite
├── pyproject.toml           # Package config
├── README.md                # This file
└── PUBLISH.md               # PyPI release guide
```

## 🧪 Development

```bash
# Clone repo
git clone https://github.com/ava-protocol/ava-protocol.git
cd ava-protocol

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[all,dev]"

# Download Presidio models (if using local)
python -m spacy download en_core_web_lg

# Run tests
pytest

# Lint
black src/ava tests/
ruff check src/ava tests/
```

## 🛡️ Security Considerations

- **Zero-Retention Mode**: Tokens auto-expire (default: 1 hour)
- **Vault Isolation**: Session-scoped token storage
- **Audit Trail**: Every transformation logged in manifest
- **Hash-Only Storage**: Original values never in manifests (only tokens)

## 📄 License

MIT License — see [LICENSE](LICENSE)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 🔗 Links

- **Documentation**: https://ava-protocol.readthedocs.io
- **PyPI**: https://pypi.org/project/ava-protocol/
- **Repository**: https://github.com/ava-protocol/ava-protocol
- **Issues**: https://github.com/ava-protocol/ava-protocol/issues

---

**AVA**: Making AI interactions private by default, visible by design.
