ava-protocol 0.1.0__tar.gz

ava_protocol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Lint with ruff
+      run: |
+        ruff check src/ava tests/
+
+    - name: Format check with black
+      run: |
+        black --check src/ava tests/
+
+    - name: Type check with mypy
+      run: |
+        mypy src/ava
+      continue-on-error: true
+
+    - name: Test with pytest
+      run: |
+        pytest tests/ -v --tb=short
+
+    - name: Build package
+      run: |
+        pip install build
+        python -m build
+
+  publish-test:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Build package
+      run: |
+        pip install build
+        python -m build
+
+    - name: Upload to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      continue-on-error: true

ava_protocol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # OIDC trusted publishing
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ava-protocol
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build tools
+      run: |
+        pip install build
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      # Uncomment for API token auth if not using OIDC:
+      # with:
+      #   password: ${{ secrets.PYPI_API_TOKEN }}

ava_protocol-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# MyPy
+.mypy_cache/
+.dmypy_cache/
+
+# Environment
+.env
+.env.local
+
+# macOS
+.DS_Store
+
+# Model files (large)
+*.bin
+*.pkl
+*.h5

ava_protocol-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## Authors
+
+- Gerald Enrique Nelson Mc Kenzie (https://github.com/lordxmen2k)
+
+## Date
+
+- 3/13/2026
+
+All notable changes to the AVA Protocol project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Core protocol layer with AVA Manifest format
+- Pluggable detection engine architecture
+- Microsoft Presidio engine adapter
+- Mock engine for testing
+- Memory-based and SQLite token vaults
+- HTTP gateway client for remote AVA services
+- Configuration management (env, YAML, dict)
+- Context manager session interface
+
+### Security
+- Zero-retention token vault with configurable TTL
+- Session-scoped token isolation
+- Hash-only audit trails (no original values in manifests)
+
+## [0.1.0] - 2025-03-13
+
+### Added
+- Initial release of AVA Protocol Python library
+- Basic client interface with embedded and gateway modes
+- PyPI package with optional dependencies: `[local]`, `[aws]`, `[all]`
+- Complete documentation: README, PUBLISH guide
+- CI/CD with GitHub Actions (test, build, publish)
+- MIT License
+
+---
+
+[Unreleased]: https://github.com/ava-protocol/ava-protocol/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ava-protocol/ava-protocol/releases/tag/v0.1.0

ava_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AVA Protocol Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ava_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+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.