ava-protocol 0.1.0__py3-none-any.whl

ava/__init__.py

@@ -0,0 +1,23 @@
+"""AVA Protocol - AI Visibility Anonymizer"""
+
+__version__ = "0.1.0"
+__author__ = "AVA Team"
+__license__ = "MIT"
+
+from ava.client import Client, GatewayClient, create_client
+from ava.config import Config
+from ava.session import Session
+
+try:
+    from ava.engines.presidio import PresidioEngine
+except ImportError:
+    PresidioEngine = None
+
+__all__ = [
+    "Client",
+    "GatewayClient", 
+    "Config",
+    "Session",
+    "create_client",
+    "PresidioEngine",
+]

ava/client.py

@@ -0,0 +1,157 @@
+"""AVA Client - Main entry point for protocol operations"""
+from __future__ import annotations
+import os
+from typing import Optional, Dict, Any, Union
+from contextlib import contextmanager
+
+from ava.config import Config
+from ava.session import Session
+from ava.protocol.token_vault import MemoryVault, TokenVault
+from ava.protocol.manifest import AVAManifest
+
+
+class Client:
+    """Embedded AVA client with local detection engine."""
+
+    def __init__(
+        self,
+        engine: str = "presidio",
+        policy: str = "general_moderate",
+        vault: Optional[TokenVault] = None,
+        retention: int = 3600,
+        config: Optional[Dict[str, Any]] = None
+    ):
+        self.engine_name = engine
+        self.policy = policy
+        self.retention = retention
+        self.vault = vault or MemoryVault(ttl_seconds=retention)
+        self._engine = None
+        self.config = config or {}
+
+        self._load_engine()
+
+    def _load_engine(self):
+        """Lazy-load detection engine."""
+        if self._engine is not None:
+            return
+
+        if self.engine_name == "presidio":
+            try:
+                from ava.engines.presidio import PresidioEngine
+                self._engine = PresidioEngine()
+            except ImportError as e:
+                raise ImportError(
+                    "Presidio engine not available. "
+                    "Install with: pip install ava-protocol[local]"
+                ) from e
+        elif self.engine_name == "mock":
+            from ava.engines.base import MockEngine
+            self._engine = MockEngine()
+        else:
+            raise ValueError(f"Unknown engine: {self.engine_name}")
+
+    @contextmanager
+    def session(self, reversibility: bool = True):
+        """Create an AVA session for sanitize/restore operations."""
+        session = Session(
+            engine=self._engine,
+            vault=self.vault,
+            policy=self.policy,
+            reversibility=reversibility
+        )
+        try:
+            yield session
+        finally:
+            session.close()
+
+    def sanitize(self, text: str) -> str:
+        """One-shot sanitize (no session context)."""
+        with self.session() as s:
+            return s.sanitize(text)
+
+    def close(self):
+        """Cleanup resources."""
+        if self.vault:
+            self.vault.close()
+
+
+class GatewayClient:
+    """Client for remote AVA Gateway."""
+
+    def __init__(
+        self,
+        url: str,
+        api_key: Optional[str] = None,
+        policy: str = "general_moderate",
+        timeout: float = 30.0
+    ):
+        self.url = url.rstrip("/")
+        self.api_key = api_key or os.getenv("AVA_API_KEY")
+        self.policy = policy
+        self.timeout = timeout
+        self._session: Optional[Any] = None
+
+    def _get_client(self):
+        """Lazy init HTTP client."""
+        if self._session is None:
+            import httpx
+            headers = {"X-AVA-Policy": self.policy}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            self._session = httpx.Client(
+                base_url=self.url,
+                headers=headers,
+                timeout=self.timeout
+            )
+        return self._session
+
+    @contextmanager
+    def session(self, reversibility: bool = True):
+        """Gateway-backed session."""
+        from ava.gateways.http import GatewaySession
+        s = GatewaySession(
+            client=self._get_client(),
+            policy=self.policy,
+            reversibility=reversibility
+        )
+        try:
+            yield s
+        finally:
+            s.close()
+
+    def health(self) -> Dict[str, Any]:
+        """Check gateway health and capabilities."""
+        client = self._get_client()
+        resp = client.get("/v1/health")
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self):
+        """Close HTTP session."""
+        if self._session:
+            self._session.close()
+
+
+def create_client(config: Union[Config, Dict[str, Any], str, None] = None) -> Union[Client, GatewayClient]:
+    """Factory function to create appropriate client from config."""
+    if isinstance(config, str):
+        config = Config.from_yaml(config)
+    elif isinstance(config, dict):
+        config = Config.from_dict(config)
+    elif config is None:
+        config = Config.from_env()
+
+    if config.mode == "embedded":
+        return Client(
+            engine=config.engine,
+            policy=config.policy,
+            retention=config.retention
+        )
+    elif config.mode == "gateway":
+        return GatewayClient(
+            url=config.url,
+            api_key=config.api_key,
+            policy=config.policy
+        )
+    else:
+        raise ValueError(f"Unknown mode: {config.mode}")

ava/config.py

@@ -0,0 +1,51 @@
+"""AVA Configuration management"""
+from __future__ import annotations
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class Config:
+    """AVA client configuration."""
+    mode: str = "embedded"  # embedded or gateway
+    engine: str = "presidio"
+    policy: str = "general_moderate"
+    retention: int = 3600
+    # Gateway mode
+    url: Optional[str] = None
+    api_key: Optional[str] = None
+    # Extensions
+    extensions: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls, prefix: str = "AVA_") -> Config:
+        """Load config from environment variables."""
+        mode = os.getenv(f"{prefix}MODE", "embedded").lower()
+
+        config = cls(
+            mode=mode,
+            engine=os.getenv(f"{prefix}ENGINE", "presidio"),
+            policy=os.getenv(f"{prefix}POLICY", "general_moderate"),
+            retention=int(os.getenv(f"{prefix}RETENTION", "3600")),
+        )
+
+        if mode == "gateway":
+            config.url = os.getenv(f"{prefix}GATEWAY_URL")
+            config.api_key = os.getenv(f"{prefix}API_KEY")
+            if not config.url:
+                raise ValueError(f"{prefix}GATEWAY_URL required for gateway mode")
+
+        return config
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Config:
+        """Load config from dictionary."""
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    @classmethod
+    def from_yaml(cls, path: str) -> Config:
+        """Load config from YAML file."""
+        import yaml
+        with open(path) as f:
+            return cls.from_dict(yaml.safe_load(f))

ava/engines/__init__.py

@@ -0,0 +1,9 @@
+"""AVA Detection Engines"""
+from ava.engines.base import DetectionEngine, MockEngine
+
+try:
+    from ava.engines.presidio import PresidioEngine
+except ImportError:
+    PresidioEngine = None
+
+__all__ = ["DetectionEngine", "MockEngine", "PresidioEngine"]

ava/engines/base.py

@@ -0,0 +1,42 @@
+"""Base detection engine interface"""
+from abc import ABC, abstractmethod
+from typing import List, Optional
+import re
+
+from ava.protocol.entities import DetectedEntity
+
+
+class DetectionEngine(ABC):
+    """Abstract base for PII detection engines."""
+
+    @abstractmethod
+    def detect(self, text: str, policy: Optional[str] = None) -> List[DetectedEntity]:
+        """Detect entities in text."""
+        pass
+
+
+class MockEngine(DetectionEngine):
+    """Mock engine for testing - uses regex patterns."""
+
+    PATTERNS = {
+        "EMAIL_ADDRESS": r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
+        "PHONE_NUMBER": r"\b\+?1?[-.]?\(?[0-9]{3}\)?[-.]?[0-9]{3}[-.]?[0-9]{4}\b",
+        "SSN": r"\d{3}-\d{2}-\d{4}",
+        "CREDIT_CARD": r"\b\d{4}[-]?\d{4}[-]?\d{4}[-]?\d{4}\b",
+    }
+
+    def detect(self, text: str, policy: Optional[str] = None) -> List[DetectedEntity]:
+        entities = []
+
+        for entity_type, pattern in self.PATTERNS.items():
+            for match in re.finditer(pattern, text):
+                entities.append(DetectedEntity(
+                    type=entity_type,
+                    value=match.group(),
+                    position=(match.start(), match.end()),
+                    confidence=0.95
+                ))
+
+        # Sort by position
+        entities.sort(key=lambda e: e.position[0])
+        return entities

ava/engines/presidio.py

@@ -0,0 +1,113 @@
+"""Presidio-based detection engine"""
+from typing import List, Optional, Dict
+
+from ava.engines.base import DetectionEngine
+from ava.protocol.entities import DetectedEntity
+
+
+class PresidioEngine(DetectionEngine):
+    """Microsoft Presidio-based entity detection."""
+
+    # Map Presidio entities to AVA types
+    ENTITY_MAP: Dict[str, str] = {
+        "PERSON": "PERSON_NAME",
+        "EMAIL_ADDRESS": "EMAIL_ADDRESS",
+        "PHONE_NUMBER": "PHONE_NUMBER",
+        "CREDIT_CARD": "CREDIT_CARD_NUMBER",
+        "US_SSN": "SSN",
+        "US_BANK_NUMBER": "BANK_ACCOUNT",
+        "IBAN": "IBAN",
+        "US_PASSPORT": "PASSPORT",
+        "US_DRIVER_LICENSE": "DRIVER_LICENSE",
+        "IP_ADDRESS": "IP_ADDRESS",
+        "LOCATION": "LOCATION",
+        "DATE_TIME": "DATE_TIME",
+        "NRP": "NATIONALITY",
+        "MEDICAL_LICENSE": "MEDICAL_LICENSE",
+        "URL": "URL",
+    }
+
+    def __init__(self, languages: Optional[List[str]] = None):
+        try:
+            from presidio_analyzer import AnalyzerEngine
+            from presidio_anonymizer import AnonymizerEngine
+        except ImportError as e:
+            raise ImportError(
+                "Presidio not installed. "
+                "Install with: pip install presidio-analyzer presidio-anonymizer"
+            ) from e
+
+        self.languages = languages or ["en"]
+        self._analyzer = AnalyzerEngine()
+        self._anonymizer = AnonymizerEngine()
+
+        # Policy strictness mapping
+        self._score_thresholds = {
+            "permissive": 0.3,
+            "moderate": 0.5,
+            "strict": 0.7,
+            "paranoid": 0.3,  # Low threshold = more detections
+        }
+
+    def detect(self, text: str, policy: Optional[str] = None) -> List[DetectedEntity]:
+        """Detect entities using Presidio analyzer."""
+        from presidio_analyzer import RecognizerResult
+
+        # Determine threshold from policy
+        strictness = "moderate"
+        if policy:
+            for s in ["permissive", "moderate", "strict", "paranoid"]:
+                if s in policy.lower():
+                    strictness = s
+                    break
+
+        threshold = self._score_thresholds.get(strictness, 0.5)
+
+        # Analyze
+        results: List[RecognizerResult] = self._analyzer.analyze(
+            text=text,
+            language=self.languages[0],
+            score_threshold=threshold
+        )
+
+        # Convert to AVA entities
+        entities = []
+        for result in results:
+            entity_type = self.ENTITY_MAP.get(
+                result.entity_type, 
+                result.entity_type
+            )
+
+            entities.append(DetectedEntity(
+                type=entity_type,
+                value=text[result.start:result.end],
+                position=(result.start, result.end),
+                confidence=result.score
+            ))
+
+        # Sort by position
+        entities.sort(key=lambda e: e.position[0])
+        return entities
+
+    def anonymize(self, text: str, entities: List[DetectedEntity]) -> str:
+        """Direct anonymization (utility method)."""
+        from presidio_anonymizer.entities import OperatorConfig
+
+        presidio_results = [
+            {
+                "entity_type": e.type,
+                "start": e.position[0],
+                "end": e.position[1],
+                "score": e.confidence
+            }
+            for e in entities
+        ]
+
+        result = self._anonymizer.anonymize(
+            text=text,
+            analyzer_results=presidio_results,
+            operators={
+                "DEFAULT": OperatorConfig("replace", {"new_value": "<REDACTED>"})
+            }
+        )
+        return result.text

ava/gateways/__init__.py

@@ -0,0 +1,4 @@
+"""AVA Gateway clients"""
+from ava.gateways.http import GatewaySession
+
+__all__ = ["GatewaySession"]

ava/gateways/http.py

@@ -0,0 +1,46 @@
+"""HTTP client for AVA Gateway"""
+from typing import Optional, Dict, Any
+
+
+class GatewaySession:
+    """Session backed by remote AVA Gateway."""
+
+    def __init__(self, client, policy: str, reversibility: bool = True):
+        self.client = client
+        self.policy = policy
+        self.reversibility = reversibility
+        self._manifest_id: Optional[str] = None
+        self._closed = False
+
+    def sanitize(self, text: str, context: Optional[str] = None) -> str:
+        """Sanitize via gateway API."""
+        if self._closed:
+            raise RuntimeError("Session is closed")
+
+        resp = self.client.post("/v1/sanitize", json={
+            "text": text,
+            "context": context,
+            "reversibility_required": self.reversibility
+        })
+        resp.raise_for_status()
+
+        data = resp.json()
+        self._manifest_id = data.get("manifest", {}).get("manifest_id")
+        return data["sanitized_text"]
+
+    def restore(self, text: str, manifest_id: Optional[str] = None) -> str:
+        """Restore via gateway API."""
+        if self._closed:
+            raise RuntimeError("Session is closed")
+
+        resp = self.client.post("/v1/restore", json={
+            "ai_response": text,
+            "manifest_id": manifest_id or self._manifest_id
+        })
+        resp.raise_for_status()
+
+        return resp.json()["restored_text"]
+
+    def close(self):
+        """Close session - no-op for stateless HTTP."""
+        self._closed = True

ava/protocol/__init__.py

@@ -0,0 +1,12 @@
+"""AVA Protocol - Core data structures and schemas"""
+from ava.protocol.manifest import AVAManifest, EntityRecord
+from ava.protocol.entities import DetectedEntity
+from ava.protocol.token_vault import TokenVault, MemoryVault
+
+__all__ = [
+    "AVAManifest",
+    "EntityRecord", 
+    "DetectedEntity",
+    "TokenVault",
+    "MemoryVault",
+]

ava/protocol/entities.py

@@ -0,0 +1,18 @@
+"""Entity definitions for detected PII"""
+from dataclasses import dataclass
+from typing import Tuple
+import hashlib
+
+
+@dataclass
+class DetectedEntity:
+    """A detected sensitive entity in text."""
+    type: str                    # e.g., "PERSON_NAME", "EMAIL_ADDRESS"
+    value: str                   # Original text
+    position: Tuple[int, int]    # (start, end) character positions
+    confidence: float            # 0.0-1.0 detection confidence
+
+    def hash(self) -> str:
+        """Hash the value for audit trails without storing original."""
+        h = hashlib.sha256(self.value.encode()).hexdigest()[:16]
+        return f"sha256:{h}"

ava/protocol/manifest.py

@@ -0,0 +1,82 @@
+"""AVA Manifest - Audit and transformation tracking"""
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+
+@dataclass
+class EntityRecord:
+    """Recorded entity in manifest."""
+    type: str
+    value_hash: str
+    position: List[int]
+    confidence: float
+    action: str
+    token: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": self.type,
+            "value_hash": self.value_hash,
+            "position": self.position,
+            "confidence": self.confidence,
+            "action": self.action,
+            "token": self.token
+        }
+
+
+@dataclass  
+class AVAManifest:
+    """AVA transformation manifest for audit and reversibility."""
+
+    # Required fields
+    manifest_id: str
+    timestamp: str
+    policy_domain: str = "general"
+    policy_strictness: str = "moderate"
+    reversibility: bool = True
+
+    # Runtime state
+    entities: List[EntityRecord] = field(default_factory=list)
+    input_transform: str = "pseudonymize"
+    output_transform: str = "restore"
+
+    def add_entity(
+        self,
+        entity_type: str,
+        value_hash: str,
+        position: List[int],
+        confidence: float,
+        action: str,
+        token: str
+    ):
+        """Add an entity record to this manifest."""
+        self.entities.append(EntityRecord(
+            type=entity_type,
+            value_hash=value_hash,
+            position=position,
+            confidence=confidence,
+            action=action,
+            token=token
+        ))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize manifest to dictionary."""
+        return {
+            "ava_version": "1.0",
+            "manifest_id": self.manifest_id,
+            "timestamp": self.timestamp,
+            "policy": {
+                "domain": self.policy_domain,
+                "strictness": self.policy_strictness,
+                "reversibility": self.reversibility
+            },
+            "entities": [e.to_dict() for e in self.entities],
+            "transformations": {
+                "input_transform": self.input_transform,
+                "output_transform": self.output_transform
+            }
+        }
+
+    def get_tokens(self) -> List[str]:
+        """Return all tokens in this manifest."""
+        return [e.token for e in self.entities]

ava/protocol/token_vault.py

@@ -0,0 +1,167 @@
+"""Token vault implementations for secure storage of original values"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Tuple
+import secrets
+import threading
+from datetime import datetime, timedelta, timezone
+
+
+class TokenVault(ABC):
+    """Abstract base for token storage backends."""
+
+    TOKEN_PREFIX = "AVA"
+
+    @abstractmethod
+    def store(self, original: str, entity_type: str, session_id: str) -> str:
+        """Store original value, return token."""
+        pass
+
+    @abstractmethod
+    def retrieve(self, token: str, session_id: str) -> Optional[str]:
+        """Retrieve original value by token."""
+        pass
+
+    @abstractmethod
+    def expire_session(self, session_id: str):
+        """Remove all tokens for a session."""
+        pass
+
+    @abstractmethod
+    def close(self):
+        """Cleanup resources."""
+        pass
+
+    def _generate_token(self, entity_type: str, suffix: str) -> str:
+        """Generate standard AVA token format: AVA_TYPE_suffix"""
+        short_type = entity_type.split("_")[0][:4].upper()
+        return f"{self.TOKEN_PREFIX}_{short_type}_{suffix}"
+
+    def _now(self) -> datetime:
+        """Get current UTC time (timezone-aware)."""
+        return datetime.now(timezone.utc)
+
+
+class MemoryVault(TokenVault):
+    """In-memory token vault with TTL support."""
+
+    def __init__(self, ttl_seconds: int = 3600):
+        self.ttl_seconds = ttl_seconds
+        self._store: Dict[str, Tuple[str, datetime]] = {}
+        self._session_tokens: Dict[str, set] = {}
+        self._lock = threading.RLock()
+        self._closed = False
+
+    def store(self, original: str, entity_type: str, session_id: str) -> str:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Vault is closed")
+
+            suffix = secrets.token_urlsafe(6)[:8]
+            token = self._generate_token(entity_type, suffix)
+
+            # Ensure uniqueness
+            while token in self._store:
+                suffix = secrets.token_urlsafe(6)[:8]
+                token = self._generate_token(entity_type, suffix)
+
+            expiry = self._now() + timedelta(seconds=self.ttl_seconds)
+            self._store[token] = (original, expiry)
+
+            if session_id not in self._session_tokens:
+                self._session_tokens[session_id] = set()
+            self._session_tokens[session_id].add(token)
+
+            return token
+
+    def retrieve(self, token: str, session_id: str) -> Optional[str]:
+        with self._lock:
+            if self._closed:
+                return None
+
+            entry = self._store.get(token)
+            if not entry:
+                return None
+
+            original, expiry = entry
+            if self._now() > expiry:
+                self._store.pop(token, None)
+                return None
+
+            return original
+
+    def expire_session(self, session_id: str):
+        with self._lock:
+            tokens = self._session_tokens.pop(session_id, set())
+            for token in tokens:
+                self._store.pop(token, None)
+
+    def close(self):
+        with self._lock:
+            self._store.clear()
+            self._session_tokens.clear()
+            self._closed = True
+
+
+class SqliteVault(TokenVault):
+    """SQLite-backed token vault for persistence."""
+
+    def __init__(self, db_path: str = ":memory:", ttl_seconds: int = 3600):
+        import sqlite3
+        self.db_path = db_path
+        self.ttl_seconds = ttl_seconds
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._init_db()
+
+    def _init_db(self):
+        self._conn.execute(
+            "CREATE TABLE IF NOT EXISTS tokens ("
+            "token TEXT PRIMARY KEY, original TEXT NOT NULL, "
+            "session_id TEXT NOT NULL, entity_type TEXT NOT NULL, "
+            "created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, expires_at TIMESTAMP)"
+        )
+        self._conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_session ON tokens(session_id)"
+        )
+        self._conn.commit()
+
+    def store(self, original: str, entity_type: str, session_id: str) -> str:
+        import sqlite3
+        suffix = secrets.token_urlsafe(6)[:8]
+        token = self._generate_token(entity_type, suffix)
+
+        expires = self._now() + timedelta(seconds=self.ttl_seconds)
+
+        try:
+            with self._conn:
+                self._conn.execute(
+                    "INSERT INTO tokens (token, original, session_id, entity_type, expires_at) VALUES (?, ?, ?, ?, ?)",
+                    (token, original, session_id, entity_type, expires.isoformat())
+                )
+            return token
+        except sqlite3.IntegrityError:
+            # Collision, retry
+            return self.store(original, entity_type, session_id)
+
+    def retrieve(self, token: str, session_id: str) -> Optional[str]:
+        cursor = self._conn.execute(
+            "SELECT original, expires_at FROM tokens WHERE token = ?",
+            (token,)
+        )
+        row = cursor.fetchone()
+        if not row:
+            return None
+
+        original, expires_at = row
+        if datetime.fromisoformat(expires_at) < self._now():
+            self._conn.execute("DELETE FROM tokens WHERE token = ?", (token,))
+            return None
+
+        return original
+
+    def expire_session(self, session_id: str):
+        with self._conn:
+            self._conn.execute("DELETE FROM tokens WHERE session_id = ?", (session_id,))
+
+    def close(self):
+        self._conn.close()

ava/session.py

@@ -0,0 +1,128 @@
+"""AVA Session - Context manager for sanitize/restore operations"""
+from __future__ import annotations
+import uuid
+from datetime import datetime
+from typing import Optional, List, Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ava.engines.base import DetectionEngine
+    from ava.protocol.token_vault import TokenVault
+    from ava.protocol.manifest import AVAManifest
+
+
+class Session:
+    """Transaction context for AVA operations."""
+
+    def __init__(
+        self,
+        engine: DetectionEngine,
+        vault: TokenVault,
+        policy: str,
+        reversibility: bool = True
+    ):
+        self.engine = engine
+        self.vault = vault
+        self.policy = policy
+        self.reversibility = reversibility
+        self.session_id = str(uuid.uuid4())[:8]
+        self.manifests: List[AVAManifest] = []
+        self._closed = False
+
+    def sanitize(self, text: str, context: Optional[str] = None) -> str:
+        """Sanitize text, return cleaned version."""
+        if self._closed:
+            raise RuntimeError("Session is closed")
+
+        # Detect entities
+        entities = self.engine.detect(text, policy=self.policy)
+
+        # Build manifest
+        from ava.protocol.manifest import AVAManifest
+        manifest = AVAManifest(
+            manifest_id=f"ava-{self.session_id}-{len(self.manifests)}",
+            timestamp=datetime.utcnow().isoformat() + "Z",
+            policy_domain=self.policy.split("_")[0] if "_" in self.policy else "general",
+            policy_strictness=self.policy.split("_")[-1] if "_" in self.policy else "moderate",
+            reversibility=self.reversibility
+        )
+
+        # Transform
+        transformed_text = text
+        offset = 0
+
+        for entity in sorted(entities, key=lambda e: e.position[0]):
+            token = self.vault.store(
+                original=entity.value,
+                entity_type=entity.type,
+                session_id=self.session_id
+            )
+
+            manifest.add_entity(
+                entity_type=entity.type,
+                value_hash=entity.hash(),
+                position=[entity.position[0] + offset, entity.position[1] + offset],
+                confidence=entity.confidence,
+                action="pseudonymize",
+                token=token
+            )
+
+            # Replace in text
+            start, end = entity.position[0] + offset, entity.position[1] + offset
+            transformed_text = transformed_text[:start] + token + transformed_text[end:]
+            offset += len(token) - (end - start)
+
+        self.manifests.append(manifest)
+        return transformed_text
+
+    def restore(self, text: str, manifest_id: Optional[str] = None) -> str:
+        """Restore sanitized text to original values."""
+        if self._closed:
+            raise RuntimeError("Session is closed")
+
+        if not self.reversibility:
+            raise RuntimeError("Session created without reversibility")
+
+        result = text
+        # Find manifest
+        manifest = None
+        if manifest_id:
+            for m in self.manifests:
+                if m.manifest_id == manifest_id:
+                    manifest = m
+                    break
+        else:
+            manifest = self.manifests[-1] if self.manifests else None
+
+        if not manifest:
+            raise ValueError("No manifest found for restoration")
+
+        # Restore entities (reverse order to preserve positions)
+        for entity in reversed(manifest.entities):
+            original = self.vault.retrieve(entity.token, session_id=self.session_id)
+            if original:
+                result = result.replace(entity.token, original)
+
+        return result
+
+    def get_manifest(self, manifest_id: Optional[str] = None) -> Optional[AVAManifest]:
+        """Retrieve manifest by ID or latest."""
+        if manifest_id:
+            for m in self.manifests:
+                if m.manifest_id == manifest_id:
+                    return m
+            return None
+        return self.manifests[-1] if self.manifests else None
+
+    def close(self):
+        """Cleanup session resources."""
+        if self._closed:
+            return
+        self.vault.expire_session(self.session_id)
+        self._closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False

ava_protocol-0.1.0.dist-info/METADATA

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

ava_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+ava/__init__.py,sha256=3J2aKq9n8DShZk3CLSNLeYRQT2879Fj9d34RRjrx2Xk,463
+ava/client.py,sha256=N-FGi9mhtv0ymegi3PBirzcBof6imQzF6NfvZWD-VdI,4762
+ava/config.py,sha256=6ifUtgLhKfSSIUlj4B7oJV_D_m6KHAOK4OKZypv4N5I,1666
+ava/session.py,sha256=q2BSjCaOQk5TpELtkvvWvkRGdAGCnep3fp7SfrsYQNw,4337
+ava/engines/__init__.py,sha256=y2YUYLQAhtYMRTsxgNi3bqjjaMUBhY35mogQa7NGmR4,252
+ava/engines/base.py,sha256=fQnjo2nhtkfw40I6YnFkz7NBhIaNKvld5UYKSLbdbcI,1354
+ava/engines/presidio.py,sha256=Cnyaw8jRsDQm3jrBYjHv2-aqqC9OVHzxi7QLBnqfJVM,3663
+ava/gateways/__init__.py,sha256=Fq10R6Wdd3oUOip7tNdZHYmasmTuCqmTXf_eRs2WXn4,101
+ava/gateways/http.py,sha256=RhFuN6za3HLO9ad3TcgMgSGhBtRbzwgIcPntDnOgggI,1475
+ava/protocol/__init__.py,sha256=9yiAH-e0XI5Mc6mJKfgm8apKK4xbtOtZFXjciRpbI4A,338
+ava/protocol/entities.py,sha256=RYayqOaHDLlIPVtn2m1LS7i89HyxT9edPkOnb3yHBeU,645
+ava/protocol/manifest.py,sha256=UE-PKHHkSZMHczLt0fgA1bW05-X-AvqI21dAkS5zcuc,2318
+ava/protocol/token_vault.py,sha256=hlY5qA3zsX3e4P_cubVcHqdl6OtJ6fn5Fhd9L_aY4Zs,5517
+ava_protocol-0.1.0.dist-info/METADATA,sha256=G-IXI-LbDFg2xFS8-iFlnA498SUtdpvjqLA252Vh6sI,11374
+ava_protocol-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ava_protocol-0.1.0.dist-info/entry_points.txt,sha256=Ss7GoyQPKi4Zsbx0To102--qMW7iqY42ZLqZ9lOgWkI,37
+ava_protocol-0.1.0.dist-info/licenses/LICENSE,sha256=E3QcRMbgb3k2EAQZ_y5uONaUgdtMRE2gYQdUpUHlHxA,1074
+ava_protocol-0.1.0.dist-info/RECORD,,

ava_protocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ava_protocol-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ava = ava.cli:main

ava_protocol-0.1.0.dist-info/licenses/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.