ava-protocol 0.1.0

AVA - AI Visibility Anonymizer Protocol

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

┌─────────────────────────────────────────────────────────┐
│                      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

# 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

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 ([e-mail]) 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 [e-mail]..."

Gateway Mode (Enterprise)

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	"[e-mail]" → 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

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

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

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:

{
  "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

# 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

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