Initial clean commit for Hugging Face Space

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+env/
+venv/
+ENV/
+env.bak/
+echo test1.png >> .gitignore
+git add .gitignore

Dockerfile

@@ -0,0 +1,43 @@
+# Multi-stage build for optimized image size
+FROM python:3.11-slim as base
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Install system dependencies
+# Tesseract is optional but included for OCR support
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tesseract-ocr \
+    tesseract-ocr-eng \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create non-root user for security
+RUN useradd -m -u 1000 appuser && \
+    chown -R appuser:appuser /app
+
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
+
+# Run application
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

agents/hashing_agent.py

@@ -0,0 +1,78 @@
+"""
+Hashing Agent
+Generates cryptographic hashes for content verification.
+"""
+
+from typing import Dict, Any
+import hashlib
+from datetime import datetime, timezone
+
+from core.agent_base import Agent
+from core.errors import HashingError
+from config.settings import settings
+
+
+class HashingAgent(Agent):
+    """
+    Generates SHA-256 hash for files or text content.
+    """
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate cryptographic hash.
+        
+        Expected input_data:
+            {
+                "content": bytes,
+                ...other fields...
+            }
+        
+        Returns:
+            {
+                "content_hash": str,
+                "hash_algorithm": str,
+                "hash_timestamp": str,
+                ...passes through input_data...
+            }
+        """
+        content = input_data.get("content")
+        
+        if not content:
+            raise HashingError("Missing 'content' field")
+        
+        if not isinstance(content, bytes):
+            raise HashingError("Content must be bytes")
+        
+        # Generate hash
+        algorithm = settings.HASH_ALGORITHM
+        hash_value = self._compute_hash(content, algorithm)
+        
+        # Add hash info to input data
+        result = input_data.copy()
+        result.update({
+            "content_hash": hash_value,
+            "hash_algorithm": algorithm,
+            "hash_timestamp": datetime.now(timezone.utc).isoformat(),
+        })
+        
+        return result
+    
+    def _compute_hash(self, content: bytes, algorithm: str) -> str:
+        """
+        Compute hash using specified algorithm.
+        
+        Args:
+            content: Content bytes to hash
+            algorithm: Hash algorithm name (e.g., 'sha256')
+        
+        Returns:
+            Hexadecimal hash string
+        """
+        try:
+            hasher = hashlib.new(algorithm)
+            hasher.update(content)
+            return hasher.hexdigest()
+        except ValueError as e:
+            raise HashingError(f"Unsupported hash algorithm: {algorithm}") from e
+        except Exception as e:
+            raise HashingError(f"Hash computation failed: {str(e)}") from e

agents/input_validator.py

@@ -0,0 +1,108 @@
+"""
+Input Validation Agent
+Validates and normalizes input data (file or text) into a standard format.
+"""
+
+from typing import Dict, Any, Optional
+import mimetypes
+from pathlib import Path
+
+from core.agent_base import Agent
+from core.errors import ValidationError
+from config.settings import settings
+
+
+class InputValidatorAgent(Agent):
+    """
+    Validates input type, size, format and normalizes to internal format.
+    """
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate and normalize input.
+        
+        Expected input_data:
+            {
+                "type": "file" | "text",
+                "content": bytes | str,
+                "filename": str (optional, for files),
+            }
+        
+        Returns:
+            {
+                "content": bytes,
+                "content_type": str,
+                "size": int,
+                "filename": str | None,
+                "validation_status": "valid"
+            }
+        """
+        input_type = input_data.get("type")
+        content = input_data.get("content")
+        
+        if not input_type or not content:
+            raise ValidationError("Missing required fields: 'type' and 'content'")
+        
+        if input_type == "file":
+            return self._validate_file(content, input_data.get("filename"))
+        elif input_type == "text":
+            return self._validate_text(content)
+        else:
+            raise ValidationError(f"Invalid input type: {input_type}")
+    
+    def _validate_file(self, content: bytes, filename: Optional[str]) -> Dict[str, Any]:
+        """Validate file input."""
+        if not isinstance(content, bytes):
+            raise ValidationError("File content must be bytes")
+        
+        if len(content) == 0:
+            raise ValidationError("File is empty")
+        
+        size = len(content)
+        max_size = settings.get_max_file_size_bytes()
+        
+        if size > max_size:
+            raise ValidationError(
+                f"File size {size} bytes exceeds maximum {max_size} bytes"
+            )
+        
+        # Detect content type
+        content_type = "application/octet-stream"
+        if filename:
+            guessed_type, _ = mimetypes.guess_type(filename)
+            if guessed_type:
+                content_type = guessed_type
+        
+        return {
+            "content": content,
+            "content_type": content_type,
+            "size": size,
+            "filename": filename,
+            "validation_status": "valid"
+        }
+    
+    def _validate_text(self, content: str) -> Dict[str, Any]:
+        """Validate text input."""
+        if not isinstance(content, str):
+            raise ValidationError("Text content must be string")
+        
+        if not content.strip():
+            raise ValidationError("Text is empty")
+        
+        # Convert to bytes for consistent handling
+        content_bytes = content.encode('utf-8')
+        size = len(content_bytes)
+        
+        max_size = settings.get_max_file_size_bytes()
+        if size > max_size:
+            raise ValidationError(
+                f"Text size {size} bytes exceeds maximum {max_size} bytes"
+            )
+        
+        return {
+            "content": content_bytes,
+            "content_type": "text/plain",
+            "size": size,
+            "filename": None,
+            "validation_status": "valid"
+        }

agents/metadata_agent.py

@@ -0,0 +1,73 @@
+"""
+Metadata Agent
+Generates structured metadata for proof objects.
+"""
+
+from typing import Dict, Any
+from datetime import datetime, timezone
+
+from core.agent_base import Agent
+from core.errors import MetadataError
+
+
+class MetadataAgent(Agent):
+    """
+    Creates comprehensive metadata for proof generation.
+    """
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Generate metadata object.
+        
+        Expected input_data:
+            {
+                "content_type": str,
+                "size": int,
+                "filename": str | None,
+                "content_hash": str,
+                "hash_algorithm": str,
+                "hash_timestamp": str,
+                "validation_status": str,
+                ...
+            }
+        
+        Returns:
+            {
+                "metadata": {
+                    "content_type": str,
+                    "content_size": int,
+                    "filename": str | None,
+                    "hash_reference": str,
+                    "created_at": str,
+                    "validation_status": str,
+                },
+                ...passes through input_data...
+            }
+        """
+        try:
+            metadata = {
+                "content_type": input_data.get("content_type"),
+                "content_size": input_data.get("size"),
+                "filename": input_data.get("filename"),
+                "hash_reference": input_data.get("content_hash"),
+                "hash_algorithm": input_data.get("hash_algorithm"),
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "validation_status": input_data.get("validation_status"),
+            }
+            
+            # Validate required fields
+            required = ["content_type", "content_size", "hash_reference"]
+            missing = [k for k in required if metadata.get(k) is None]
+            
+            if missing:
+                raise MetadataError(f"Missing required fields: {', '.join(missing)}")
+            
+            result = input_data.copy()
+            result["metadata"] = metadata
+            
+            return result
+            
+        except Exception as e:
+            if isinstance(e, MetadataError):
+                raise
+            raise MetadataError(f"Metadata generation failed: {str(e)}") from e

agents/proof_builder.py

@@ -0,0 +1,78 @@
+"""
+Proof Builder Agent
+Assembles final proof object from validated components.
+"""
+
+from typing import Dict, Any
+import uuid
+
+from core.agent_base import Agent
+from core.errors import ProofSystemError
+from models.proof import Proof
+
+
+class ProofBuilderAgent(Agent):
+    """
+    Combines hash, metadata, and validation results into a Proof object.
+    """
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build final proof object.
+        
+        Expected input_data:
+            {
+                "content_hash": str,
+                "hash_algorithm": str,
+                "metadata": dict,
+                "validation_status": str,
+                "extracted_text": str | None,
+                "ocr_engine": str | None,
+                "ocr_status": str | None,
+                ...
+            }
+        
+        Returns:
+            {
+                "proof": Proof,
+                "proof_id": str
+            }
+        """
+        try:
+            # Generate unique proof ID
+            proof_id = self._generate_proof_id()
+            
+            # Extract required fields
+            metadata = input_data.get("metadata", {})
+            
+            # Build proof object (including OCR fields)
+            proof = Proof(
+                proof_id=proof_id,
+                content_hash=input_data.get("content_hash"),
+                hash_algorithm=input_data.get("hash_algorithm"),
+                content_type=metadata.get("content_type"),
+                content_size=metadata.get("content_size"),
+                timestamp=metadata.get("created_at"),
+                validation_status=input_data.get("validation_status"),
+                metadata=metadata,
+                extracted_text=input_data.get("extracted_text"),
+                ocr_engine=input_data.get("ocr_engine"),
+                ocr_status=input_data.get("ocr_status")
+            )
+            
+            return {
+                "proof": proof,
+                "proof_id": proof_id
+            }
+            
+        except Exception as e:
+            raise ProofSystemError(f"Proof building failed: {str(e)}") from e
+    
+    def _generate_proof_id(self) -> str:
+        """
+        Generate unique proof identifier.
+        
+        Returns:
+            UUID string
+        """
+        return str(uuid.uuid4())

agents/storage_agent.py

@@ -0,0 +1,148 @@
+"""
+Storage Agent
+Abstract storage interface with Supabase implementation stub.
+"""
+
+from typing import Dict, Any, Optional
+from abc import abstractmethod
+
+from core.agent_base import Agent
+from core.errors import StorageError, ProofNotFoundError
+from models.proof import Proof
+from config.settings import settings
+
+
+class StorageAgent(Agent):
+    """
+    Abstract storage interface for proof persistence.
+    """
+    
+    @abstractmethod
+    def save_proof(self, proof: Proof) -> Dict[str, Any]:
+        """
+        Save proof to storage.
+        
+        Args:
+            proof: Proof object to save
+            
+        Returns:
+            Storage response with proof_id and status
+        """
+        pass
+    
+    @abstractmethod
+    def get_proof(self, proof_id: str) -> Optional[Proof]:
+        """
+        Retrieve proof from storage.
+        
+        Args:
+            proof_id: Unique proof identifier
+            
+        Returns:
+            Proof object if found, None otherwise
+        """
+        pass
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute storage operation based on action.
+        
+        Expected input_data:
+            {
+                "action": "save" | "get",
+                "proof": Proof (for save),
+                "proof_id": str (for get)
+            }
+        """
+        action = input_data.get("action")
+        
+        if action == "save":
+            proof = input_data.get("proof")
+            if not proof:
+                raise StorageError("Missing 'proof' for save action")
+            return self.save_proof(proof)
+        
+        elif action == "get":
+            proof_id = input_data.get("proof_id")
+            if not proof_id:
+                raise StorageError("Missing 'proof_id' for get action")
+            proof = self.get_proof(proof_id)
+            if not proof:
+                raise ProofNotFoundError(f"Proof not found: {proof_id}")
+            return {"proof": proof}
+        
+        else:
+            raise StorageError(f"Invalid action: {action}")
+
+
+class SupabaseStorageAgent(StorageAgent):
+    """
+    Supabase-backed storage implementation.
+    Uses environment variables for credentials - never hardcoded.
+    """
+    
+    def __init__(self):
+        super().__init__()
+        self._client = None
+        self._init_client()
+    
+    def _init_client(self):
+        """
+        Initialize Supabase client using environment variables.
+        This is a stub - actual implementation would use supabase-py.
+        """
+        if not settings.validate():
+            raise StorageError(
+                "Supabase credentials not configured. "
+                "Set SUPABASE_URL and SUPABASE_KEY environment variables."
+            )
+        
+        # TODO: Initialize actual Supabase client when library is added
+        # from supabase import create_client
+        # self._client = create_client(settings.SUPABASE_URL, settings.SUPABASE_KEY)
+        
+        # For now, using in-memory storage for testing
+        self._memory_store = {}
+    
+    def save_proof(self, proof: Proof) -> Dict[str, Any]:
+        """
+        Save proof to Supabase table.
+        Currently using in-memory stub.
+        """
+        try:
+            proof_data = proof.to_dict()
+            
+            # TODO: Replace with actual Supabase insert
+            # response = self._client.table(settings.SUPABASE_TABLE).insert(proof_data).execute()
+            
+            # In-memory stub
+            self._memory_store[proof.proof_id] = proof_data
+            
+            return {
+                "success": True,
+                "proof_id": proof.proof_id,
+                "message": "Proof saved successfully"
+            }
+            
+        except Exception as e:
+            raise StorageError(f"Failed to save proof: {str(e)}") from e
+    
+    def get_proof(self, proof_id: str) -> Optional[Proof]:
+        """
+        Retrieve proof from Supabase table.
+        Currently using in-memory stub.
+        """
+        try:
+            # TODO: Replace with actual Supabase query
+            # response = self._client.table(settings.SUPABASE_TABLE).select("*").eq("proof_id", proof_id).execute()
+            
+            # In-memory stub
+            proof_data = self._memory_store.get(proof_id)
+            
+            if not proof_data:
+                return None
+            
+            return Proof.from_dict(proof_data)
+            
+        except Exception as e:
+            raise StorageError(f"Failed to retrieve proof: {str(e)}") from e

agents/text_extraction_agent.py

@@ -0,0 +1,214 @@
+"""
+Text Extraction Agent (OCR)
+Deterministic preprocessing agent for extracting text from images and PDFs.
+Uses Tesseract OCR - a deterministic, non-AI algorithm.
+"""
+
+from typing import Dict, Any, Optional
+import io
+import logging
+
+from core.agent_base import Agent
+from core.errors import (
+    OCRNotApplicableError,
+    OCRProcessingError,
+    OCRDependencyMissingError
+)
+from config.settings import settings
+
+# Lazy imports - only load if OCR is needed
+try:
+    import pytesseract
+    from PIL import Image
+    TESSERACT_AVAILABLE = True
+except ImportError:
+    TESSERACT_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class TextExtractionAgent(Agent):
+    """
+    Extracts text from images and PDFs using Tesseract OCR.
+    This is a deterministic preprocessing step, not AI.
+    """
+    
+    # Content types that support OCR
+    OCR_SUPPORTED_TYPES = {
+        "image/png",
+        "image/jpeg",
+        "image/jpg",
+        "image/tiff",
+        "image/bmp",
+        "image/gif",
+    }
+    
+    def __init__(self):
+        super().__init__()
+        self._check_dependencies()
+    
+    def _check_dependencies(self):
+        """Check if Tesseract is available."""
+        if not TESSERACT_AVAILABLE:
+            logger.warning(
+                "Tesseract dependencies not available. "
+                "Install with: pip install pytesseract pillow"
+            )
+            return
+        
+        try:
+            # Verify Tesseract binary is accessible
+            pytesseract.get_tesseract_version()
+            logger.info("Tesseract OCR is available and ready")
+        except Exception as e:
+            logger.warning(
+                f"Tesseract binary not found in PATH: {str(e)}. "
+                "OCR will be skipped for all inputs."
+            )
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract text from content if applicable.
+        
+        Expected input_data:
+            {
+                "content": bytes,
+                "content_type": str,
+                "size": int,
+                ...other fields from validation...
+            }
+        
+        Returns:
+            {
+                "extracted_text": str | None,
+                "ocr_engine": str | None,
+                "ocr_status": "success" | "skipped" | "failed",
+                "ocr_confidence": float | None,  # Future enhancement
+                ...passes through input_data...
+            }
+        """
+        # Skip if OCR is globally disabled
+        if not settings.OCR_ENABLED:
+            logger.debug("OCR is disabled in settings")
+            return self._skip_ocr(input_data, "disabled")
+        
+        # Check if dependencies are available
+        if not TESSERACT_AVAILABLE:
+            logger.debug("OCR dependencies not available")
+            return self._skip_ocr(input_data, "dependencies_missing")
+        
+        content_type = input_data.get("content_type", "")
+        content = input_data.get("content")
+        
+        # Check if content type supports OCR
+        if not self._is_ocr_applicable(content_type):
+            logger.debug(f"OCR not applicable for content type: {content_type}")
+            return self._skip_ocr(input_data, "not_applicable")
+        
+        # Attempt OCR extraction
+        try:
+            extracted_text = self._extract_text(content, content_type)
+            
+            result = input_data.copy()
+            result.update({
+                "extracted_text": extracted_text,
+                "ocr_engine": "tesseract",
+                "ocr_status": "success",
+                "ocr_confidence": None,  # Tesseract confidence available but not used in MVP
+            })
+            
+            logger.info(
+                f"OCR successful: extracted {len(extracted_text)} characters"
+            )
+            return result
+            
+        except Exception as e:
+            logger.error(f"OCR processing failed: {str(e)}")
+            return self._skip_ocr(input_data, "failed", error=str(e))
+    
+    def _is_ocr_applicable(self, content_type: str) -> bool:
+        """
+        Check if OCR is applicable for this content type.
+        
+        Args:
+            content_type: MIME type of the content
+            
+        Returns:
+            True if OCR should be attempted
+        """
+        return content_type.lower() in self.OCR_SUPPORTED_TYPES
+    
+    def _extract_text(self, content: bytes, content_type: str) -> str:
+        """
+        Extract text using Tesseract OCR.
+        
+        Args:
+            content: Image bytes
+            content_type: MIME type
+            
+        Returns:
+            Extracted text string
+            
+        Raises:
+            OCRProcessingError: If extraction fails
+        """
+        try:
+            # Convert bytes to PIL Image
+            image = Image.open(io.BytesIO(content))
+            
+            # Perform OCR with configured language
+            text = pytesseract.image_to_string(
+                image,
+                lang=settings.OCR_LANGUAGE,
+                config='--psm 3'  # Fully automatic page segmentation
+            )
+            
+            # Clean up extracted text
+            text = text.strip()
+            
+            if not text:
+                logger.warning("OCR completed but no text was extracted")
+            
+            return text
+            
+        except pytesseract.TesseractNotFoundError as e:
+            raise OCRDependencyMissingError(
+                "Tesseract binary not found. Please install Tesseract OCR."
+            ) from e
+        except Exception as e:
+            raise OCRProcessingError(
+                f"Text extraction failed: {str(e)}"
+            ) from e
+    
+    def _skip_ocr(
+        self,
+        input_data: Dict[str, Any],
+        reason: str,
+        error: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Return input data with OCR skipped.
+        
+        Args:
+            input_data: Original input data
+            reason: Reason for skipping
+            error: Optional error message
+            
+        Returns:
+            Input data with OCR status = skipped/failed
+        """
+        result = input_data.copy()
+        
+        ocr_status = "skipped" if reason != "failed" else "failed"
+        
+        result.update({
+            "extracted_text": None,
+            "ocr_engine": None,
+            "ocr_status": ocr_status,
+            "ocr_confidence": None,
+        })
+        
+        if error:
+            result["ocr_error"] = error
+        
+        return result

agents/verification_agent.py

@@ -0,0 +1,90 @@
+"""
+Verification Agent
+Verifies proof authenticity by recomputing and comparing hashes.
+"""
+
+from typing import Dict, Any
+import hashlib
+from datetime import datetime, timezone
+
+from core.agent_base import Agent
+from core.errors import VerificationError
+from models.proof import VerificationResult, Proof
+from agents.storage_agent import StorageAgent
+
+
+class VerificationAgent(Agent):
+    """
+    Verifies proof by fetching from storage and recomputing hash.
+    """
+    
+    def __init__(self, storage_agent: StorageAgent):
+        super().__init__()
+        self.storage_agent = storage_agent
+    
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Verify proof authenticity.
+        
+        Expected input_data:
+            {
+                "proof_id": str,
+                "content": bytes  # Original content to verify
+            }
+        
+        Returns:
+            {
+                "verification_result": VerificationResult
+            }
+        """
+        proof_id = input_data.get("proof_id")
+        content = input_data.get("content")
+        
+        if not proof_id:
+            raise VerificationError("Missing 'proof_id'")
+        
+        if not content:
+            raise VerificationError("Missing 'content' to verify")
+        
+        # Fetch original proof
+        proof = self.storage_agent.get_proof(proof_id)
+        
+        if not proof:
+            raise VerificationError(f"Proof not found: {proof_id}")
+        
+        # Recompute hash
+        computed_hash = self._compute_hash(content, proof.hash_algorithm)
+        
+        # Compare hashes
+        is_valid = computed_hash == proof.content_hash
+        
+        result = VerificationResult(
+            proof_id=proof_id,
+            is_valid=is_valid,
+            original_hash=proof.content_hash,
+            computed_hash=computed_hash,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            message="Hash match: proof is valid" if is_valid else "Hash mismatch: proof is invalid"
+        )
+        
+        return {
+            "verification_result": result
+        }
+    
+    def _compute_hash(self, content: bytes, algorithm: str) -> str:
+        """
+        Compute hash using specified algorithm.
+        
+        Args:
+            content: Content bytes to hash
+            algorithm: Hash algorithm name
+            
+        Returns:
+            Hexadecimal hash string
+        """
+        try:
+            hasher = hashlib.new(algorithm)
+            hasher.update(content)
+            return hasher.hexdigest()
+        except Exception as e:
+            raise VerificationError(f"Hash computation failed: {str(e)}") from e

app.py

@@ -0,0 +1,459 @@
+"""
+FastAPI Application - Thin HTTP translation layer
+Stateless server that delegates all business logic to the orchestrator.
+
+Design principles:
+- No business logic in this file
+- Orchestrator handles all operations
+- Clean error handling with typed exceptions
+- Graceful degradation for optional features (OCR, AI)
+"""
+
+from fastapi import FastAPI, File, UploadFile, HTTPException, Form
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from typing import Optional
+import logging
+from contextlib import asynccontextmanager
+import os
+
+# Load environment variables
+from dotenv import load_dotenv
+load_dotenv()
+
+from core.orchestrator import Orchestrator
+from core.errors import (
+    ProofSystemError,
+    ValidationError,
+    ProofNotFoundError,
+    OCRError
+)
+from config.settings import settings
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# APPLICATION LIFECYCLE
+# ============================================================================
+
+# Global orchestrator instance (initialized at startup)
+orchestrator: Optional[Orchestrator] = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan handler.
+    Initialize orchestrator at startup, cleanup at shutdown.
+    """
+    global orchestrator
+    
+    logger.info("Starting Proof-of-Existence API")
+    logger.info(f"OCR Enabled: {settings.OCR_ENABLED}")
+    logger.info(f"AI Enabled: {settings.AI_ENABLED}")
+    
+    # Initialize orchestrator
+    try:
+        orchestrator = Orchestrator()
+        logger.info("Orchestrator initialized successfully")
+    except Exception as e:
+        logger.error(f"Failed to initialize orchestrator: {str(e)}")
+        raise
+    
+    yield
+    
+    # Cleanup (if needed)
+    logger.info("Shutting down Proof-of-Existence API")
+
+
+# ============================================================================
+# FASTAPI APP INITIALIZATION
+# ============================================================================
+
+app = FastAPI(
+    title="Proof-of-Existence API",
+    description="Deterministic proof generation and verification with optional OCR and AI assistance",
+    version="0.4.0",
+    lifespan=lifespan
+)
+
+# CORS middleware (configure as needed)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure appropriately for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ============================================================================
+# REQUEST/RESPONSE MODELS
+# ============================================================================
+
+class TextProofRequest(BaseModel):
+    """Request model for creating proof from text content."""
+    content: str = Field(..., description="Text content to create proof for")
+    metadata: Optional[dict] = Field(None, description="Optional metadata")
+
+
+class VerifyProofRequest(BaseModel):
+    """Request model for verifying a proof."""
+    proof_id: str = Field(..., description="Unique proof identifier")
+    content: str = Field(..., description="Content to verify against proof")
+
+
+class AssistantRequest(BaseModel):
+    """Request model for AI assistant queries."""
+    question: str = Field(..., description="Question to ask the AI assistant")
+    proof_id: Optional[str] = Field(None, description="Optional proof ID for context")
+
+
+class ProofResponse(BaseModel):
+    """Standard proof creation response."""
+    success: bool
+    proof_id: Optional[str] = None
+    hash: Optional[str] = None
+    timestamp: Optional[str] = None
+    message: str
+    assistant: Optional[dict] = None
+
+
+class VerificationResponse(BaseModel):
+    """Standard verification response."""
+    success: bool
+    is_valid: Optional[bool] = None
+    message: str
+    assistant: Optional[dict] = None
+
+
+# ============================================================================
+# ERROR HANDLERS
+# ============================================================================
+
+@app.exception_handler(ValidationError)
+async def validation_error_handler(request, exc: ValidationError):
+    """Handle validation errors with 400 Bad Request."""
+    return JSONResponse(
+        status_code=400,
+        content={
+            "success": False,
+            "error": "validation_error",
+            "message": str(exc)
+        }
+    )
+
+
+@app.exception_handler(ProofNotFoundError)
+async def proof_not_found_handler(request, exc: ProofNotFoundError):
+    """Handle proof not found with 404."""
+    return JSONResponse(
+        status_code=404,
+        content={
+            "success": False,
+            "error": "proof_not_found",
+            "message": str(exc)
+        }
+    )
+
+
+@app.exception_handler(ProofSystemError)
+async def proof_system_error_handler(request, exc: ProofSystemError):
+    """Handle general proof system errors with 500."""
+    logger.error(f"Proof system error: {str(exc)}")
+    return JSONResponse(
+        status_code=500,
+        content={
+            "success": False,
+            "error": "system_error",
+            "message": str(exc)
+        }
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request, exc: Exception):
+    """Handle unexpected errors with 500."""
+    logger.error(f"Unexpected error: {str(exc)}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "success": False,
+            "error": "internal_error",
+            "message": "An unexpected error occurred"
+        }
+    )
+
+
+# ============================================================================
+# HEALTH CHECK
+# ============================================================================
+
+@app.get("/health")
+async def health_check():
+    """
+    Health check endpoint.
+    Returns system status and feature availability.
+    """
+    return {
+        "status": "healthy",
+        "version": "0.4.0",
+        "features": {
+            "ocr": settings.OCR_ENABLED,
+            "ai_assistant": settings.AI_ENABLED and orchestrator.ai_sidecar.enabled if orchestrator else False
+        }
+    }
+
+
+# ============================================================================
+# PROOF ENDPOINTS
+# ============================================================================
+
+@app.post("/proof/create/text", response_model=ProofResponse)
+async def create_proof_from_text(request: TextProofRequest):
+    """
+    Create a cryptographic proof from text content.
+    
+    This endpoint:
+    1. Validates text input
+    2. Generates SHA-256 hash
+    3. Creates proof with timestamp
+    4. Stores proof in database
+    5. Optionally provides AI explanation
+    
+    Returns:
+        Proof ID, hash, timestamp, and optional AI explanation
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    logger.info(f"Creating proof from text ({len(request.content)} chars)")
+    
+    result = orchestrator.create_proof({
+        "type": "text",
+        "content": request.content
+    })
+    
+    if not result["success"]:
+        raise HTTPException(
+            status_code=500,
+            detail=result.get("message", "Failed to create proof")
+        )
+    
+    proof = result["proof"]
+    
+    return ProofResponse(
+        success=True,
+        proof_id=proof.proof_id,
+        hash=proof.content_hash,
+        timestamp=proof.timestamp,
+        message="Proof created successfully",
+        assistant=result.get("assistant")
+    )
+
+
+@app.post("/proof/create/file")
+async def create_proof_from_file(
+    file: UploadFile = File(...),
+    metadata: Optional[str] = Form(None)
+):
+    """
+    Create a cryptographic proof from uploaded file.
+    
+    Supports:
+    - Text files
+    - Images (with optional OCR)
+    - PDFs
+    - Binary files
+    
+    Returns:
+        Proof ID, hash, timestamp, OCR results (if applicable), and optional AI explanation
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    logger.info(f"Creating proof from file: {file.filename} ({file.content_type})")
+    
+    # Read file content
+    content = await file.read()
+    
+    if len(content) == 0:
+        raise ValidationError("File is empty")
+    
+    result = orchestrator.create_proof({
+        "type": "file",
+        "content": content,
+        "filename": file.filename
+    })
+    
+    if not result["success"]:
+        raise HTTPException(
+            status_code=500,
+            detail=result.get("message", "Failed to create proof")
+        )
+    
+    proof = result["proof"]
+    
+    return {
+        "success": True,
+        "proof_id": proof.proof_id,
+        "hash": proof.content_hash,
+        "timestamp": proof.timestamp,
+        "content_type": proof.content_type,
+        "size": proof.content_size,
+        "ocr_status": proof.ocr_status,
+        "extracted_text": proof.extracted_text[:200] + "..." if proof.extracted_text and len(proof.extracted_text) > 200 else proof.extracted_text,
+        "message": "Proof created successfully",
+        "assistant": result.get("assistant")
+    }
+
+
+@app.get("/proof/{proof_id}")
+async def get_proof(proof_id: str):
+    """
+    Retrieve a stored proof by ID.
+    
+    Args:
+        proof_id: Unique proof identifier
+        
+    Returns:
+        Complete proof object with all metadata
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    logger.info(f"Retrieving proof: {proof_id}")
+    
+    result = orchestrator.get_proof(proof_id)
+    
+    if not result["success"]:
+        raise ProofNotFoundError(f"Proof not found: {proof_id}")
+    
+    proof = result["proof"]
+    
+    return {
+        "success": True,
+        "proof": proof.to_dict(),
+        "message": "Proof retrieved successfully"
+    }
+
+
+@app.post("/proof/verify", response_model=VerificationResponse)
+async def verify_proof(request: VerifyProofRequest):
+    """
+    Verify a proof against original content.
+    
+    This endpoint:
+    1. Retrieves original proof
+    2. Recomputes hash from provided content
+    3. Compares hashes
+    4. Returns verification result
+    5. Optionally provides AI explanation
+    
+    Returns:
+        Verification status (valid/invalid) with explanation
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    logger.info(f"Verifying proof: {request.proof_id}")
+    
+    # Convert content to bytes
+    content_bytes = request.content.encode('utf-8')
+    
+    result = orchestrator.verify_proof(request.proof_id, content_bytes)
+    
+    if not result["success"]:
+        raise HTTPException(
+            status_code=500,
+            detail=result.get("message", "Verification failed")
+        )
+    
+    verification_result = result["verification_result"]
+    
+    return VerificationResponse(
+        success=True,
+        is_valid=verification_result.is_valid,
+        message=verification_result.message,
+        assistant=result.get("assistant")
+    )
+
+
+# ============================================================================
+# AI ASSISTANT ENDPOINTS (OPTIONAL)
+# ============================================================================
+
+@app.post("/assistant/ask")
+async def ask_assistant(request: AssistantRequest):
+    """
+    Ask the AI assistant a question about proofs.
+    
+    This is an OPTIONAL feature that provides explanations and guidance.
+    The assistant is non-authoritative and never affects proof validity.
+    
+    Returns:
+        AI-generated explanation (clearly marked as non-authoritative)
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    if not settings.AI_ENABLED or not orchestrator.ai_sidecar.enabled:
+        return {
+            "success": False,
+            "message": "AI assistant is not enabled. Set AI_ENABLED=true and configure GEMINI_API_KEY."
+        }
+    
+    logger.info(f"AI assistant query: {request.question[:50]}...")
+    
+    result = orchestrator.ask_assistant(request.question, request.proof_id)
+    
+    return result
+
+
+# ============================================================================
+# DOCUMENTATION ENDPOINTS
+# ============================================================================
+
+@app.get("/")
+async def root():
+    """
+    API root with basic information and links.
+    """
+    return {
+        "name": "Proof-of-Existence API",
+        "version": "0.4.0",
+        "description": "Deterministic cryptographic proof generation and verification",
+        "docs": "/docs",
+        "health": "/health",
+        "endpoints": {
+            "create_text_proof": "POST /proof/create/text",
+            "create_file_proof": "POST /proof/create/file",
+            "get_proof": "GET /proof/{proof_id}",
+            "verify_proof": "POST /proof/verify",
+            "ask_assistant": "POST /assistant/ask (optional)"
+        }
+    }
+
+
+# ============================================================================
+# DEVELOPMENT SERVER
+# ============================================================================
+
+if __name__ == "__main__":
+    import uvicorn
+    
+    # Run development server
+    uvicorn.run(
+        "app:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,  # Enable auto-reload in development
+        log_level="info"
+    )

config/settings.py

@@ -0,0 +1,73 @@
+"""
+Configuration settings loaded from environment variables.
+Never hardcode credentials or secrets.
+"""
+
+import os
+from typing import Optional
+
+
+class Settings:
+    """
+    Application settings with sensible defaults.
+    Override via environment variables.
+    """
+    
+    # Storage settings
+    SUPABASE_URL: str = os.getenv("SUPABASE_URL", "")
+    SUPABASE_KEY: str = os.getenv("SUPABASE_KEY", "")
+    SUPABASE_TABLE: str = os.getenv("SUPABASE_TABLE", "proofs")
+    
+    # Hashing settings
+    HASH_ALGORITHM: str = os.getenv("HASH_ALGORITHM", "sha256")
+    
+    # Validation settings
+    MAX_FILE_SIZE_MB: int = int(os.getenv("MAX_FILE_SIZE_MB", "10"))
+    ALLOWED_CONTENT_TYPES: list = [
+        "text/plain",
+        "application/pdf",
+        "image/png",
+        "image/jpeg",
+        "application/json",
+    ]
+    
+    # OCR settings
+    OCR_ENABLED: bool = os.getenv("OCR_ENABLED", "true").lower() == "true"
+    OCR_LANGUAGE: str = os.getenv("OCR_LANGUAGE", "eng")  # Tesseract language code
+    
+    # AI Sidecar settings (non-authoritative)
+    AI_ENABLED: bool = os.getenv("AI_ENABLED", "false").lower() == "true"
+    GEMINI_API_KEY: str = os.getenv("GEMINI_API_KEY", "")
+    GEMINI_MODEL: str = os.getenv("GEMINI_MODEL", "gemini-1.5-flash")
+    GEMINI_TIMEOUT: int = int(os.getenv("GEMINI_TIMEOUT", "10"))  # seconds
+    
+    @classmethod
+    def validate(cls) -> bool:
+        """
+        Check if required settings are present.
+        Returns True if valid, False otherwise.
+        """
+        if not cls.SUPABASE_URL or not cls.SUPABASE_KEY:
+            return False
+        return True
+    
+    @classmethod
+    def validate_ai(cls) -> bool:
+        """
+        Check if AI sidecar is properly configured.
+        Returns True if AI can be enabled, False otherwise.
+        """
+        if not cls.AI_ENABLED:
+            return False
+        if not cls.GEMINI_API_KEY:
+            return False
+        return True
+    
+    @classmethod
+    def get_max_file_size_bytes(cls) -> int:
+        """Get max file size in bytes."""
+        return cls.MAX_FILE_SIZE_MB * 1024 * 1024
+
+
+# Global settings instance
+settings = Settings()

core/agent_base.py

@@ -0,0 +1,36 @@
+"""
+Base agent interface for all system agents.
+Ensures consistent behavior across all agent implementations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class Agent(ABC):
+    """
+    Base class for all agents in the system.
+    Each agent must implement the execute method with structured I/O.
+    """
+    
+    def __init__(self):
+        self.name = self.__class__.__name__
+    
+    @abstractmethod
+    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute the agent's core logic.
+        
+        Args:
+            input_data: Structured input dictionary
+            
+        Returns:
+            Structured output dictionary
+            
+        Raises:
+            ProofSystemError: On execution failure
+        """
+        pass
+    
+    def __repr__(self) -> str:
+        return f"<{self.name}>"

core/errors.py

@@ -0,0 +1,58 @@
+"""
+Custom exception types for the proof-of-existence system.
+All agents raise these typed errors for consistent error handling.
+"""
+
+class ProofSystemError(Exception):
+    """Base exception for all proof system errors."""
+    pass
+
+
+class ValidationError(ProofSystemError):
+    """Raised when input validation fails."""
+    pass
+
+
+class HashingError(ProofSystemError):
+    """Raised when hashing operation fails."""
+    pass
+
+
+class MetadataError(ProofSystemError):
+    """Raised when metadata generation fails."""
+    pass
+
+
+class StorageError(ProofSystemError):
+    """Raised when storage operations fail."""
+    pass
+
+
+class VerificationError(ProofSystemError):
+    """Raised when proof verification fails."""
+    pass
+
+
+class ProofNotFoundError(ProofSystemError):
+    """Raised when a proof cannot be found in storage."""
+    pass
+
+
+class OCRError(ProofSystemError):
+    """Base exception for OCR-related errors."""
+    pass
+
+
+class OCRNotApplicableError(OCRError):
+    """Raised when OCR is not applicable to the content type."""
+    pass
+
+
+class OCRProcessingError(OCRError):
+    """Raised when OCR processing fails."""
+    pass
+
+
+class OCRDependencyMissingError(OCRError):
+    """Raised when Tesseract OCR is not installed or not found."""
+    pass

core/orchestrator.py

@@ -0,0 +1,302 @@
+"""
+Orchestrator Module
+Central controller that coordinates agent execution in a fixed sequence.
+"""
+
+from typing import Dict, Any, Optional
+import logging
+
+from core.agent_base import Agent
+from core.errors import ProofSystemError
+from agents.input_validator import InputValidatorAgent
+from agents.text_extraction_agent import TextExtractionAgent
+from agents.hashing_agent import HashingAgent
+from agents.metadata_agent import MetadataAgent
+from agents.proof_builder import ProofBuilderAgent
+from agents.storage_agent import SupabaseStorageAgent
+from agents.verification_agent import VerificationAgent
+from models.proof import Proof, VerificationResult
+from sidecar.gemini_sidecar import GeminiSidecar
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class Orchestrator:
+    """
+    Central orchestrator that manages the proof generation pipeline.
+    Coordinates agent execution and handles failures gracefully.
+    """
+    
+    def __init__(self):
+        """Initialize all agents in the pipeline."""
+        self.input_validator = InputValidatorAgent()
+        self.text_extraction_agent = TextExtractionAgent()
+        self.hashing_agent = HashingAgent()
+        self.metadata_agent = MetadataAgent()
+        self.proof_builder = ProofBuilderAgent()
+        self.storage_agent = SupabaseStorageAgent()
+        self.verification_agent = VerificationAgent(self.storage_agent)
+        
+        # AI Sidecar (optional, non-authoritative)
+        self.ai_sidecar = GeminiSidecar()
+        
+        logger.info("Orchestrator initialized with all agents")
+    
+    def create_proof(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute the full proof creation pipeline.
+        
+        Args:
+            input_data: {
+                "type": "file" | "text",
+                "content": bytes | str,
+                "filename": str (optional)
+            }
+        
+        Returns:
+            {
+                "success": bool,
+                "proof_id": str,
+                "proof": Proof,
+                "message": str
+            }
+        """
+        try:
+            logger.info("Starting proof creation pipeline")
+            
+            # Step 1: Validate input
+            logger.info("Step 1/6: Validating input")
+            validated_data = self.input_validator.execute(input_data)
+            
+            # Step 2: Extract text (OCR if applicable)
+            logger.info("Step 2/6: Text extraction (OCR)")
+            ocr_data = self.text_extraction_agent.execute(validated_data)
+            
+            # Step 3: Generate hash (ALWAYS on raw content, never OCR output)
+            logger.info("Step 3/6: Generating hash from raw content")
+            hashed_data = self.hashing_agent.execute(ocr_data)
+            
+            # Step 4: Generate metadata (includes OCR results)
+            logger.info("Step 4/6: Generating metadata")
+            metadata_data = self.metadata_agent.execute(hashed_data)
+            
+            # Step 5: Build proof
+            logger.info("Step 5/6: Building proof object")
+            proof_data = self.proof_builder.execute(metadata_data)
+            
+            # Step 6: Save proof
+            logger.info("Step 6/6: Saving proof to storage")
+            storage_result = self.storage_agent.save_proof(proof_data["proof"])
+            
+            logger.info(f"Proof created successfully: {proof_data['proof_id']}")
+            
+            # OPTIONAL: AI Sidecar explains the proof (non-blocking)
+            # This does NOT affect the core response
+            result = {
+                "success": True,
+                "proof_id": proof_data["proof_id"],
+                "proof": proof_data["proof"],
+                "message": "Proof created and stored successfully"
+            }
+            
+            # Add AI explanation if available (optional, non-authoritative)
+            if self.ai_sidecar.enabled:
+                try:
+                    assistant_response = self.ai_sidecar.explain_proof(
+                        proof_data["proof"]
+                    )
+                    result["assistant"] = assistant_response.to_dict()
+                    logger.info("AI explanation added to response")
+                except Exception as e:
+                    logger.warning(f"AI explanation failed (non-critical): {str(e)}")
+                    # AI failure does not affect core response
+            
+            return result
+            
+        except ProofSystemError as e:
+            logger.error(f"Proof creation failed: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": e.__class__.__name__,
+                "message": "Proof creation failed"
+            }
+        except Exception as e:
+            logger.error(f"Unexpected error: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": "UnexpectedError",
+                "message": "An unexpected error occurred"
+            }
+    
+    def ask_assistant(
+        self,
+        question: str,
+        proof_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Ask the AI assistant a question about a proof.
+        This is a separate, optional endpoint - not part of core flow.
+        
+        Args:
+            question: User's question
+            proof_id: Optional proof ID for context
+        
+        Returns:
+            {
+                "success": bool,
+                "assistant": AssistantResponse dict,
+                "message": str
+            }
+        """
+        if not self.ai_sidecar.enabled:
+            return {
+                "success": False,
+                "message": "AI assistant is not enabled. Set AI_ENABLED=true and configure GEMINI_API_KEY."
+            }
+        
+        try:
+            logger.info(f"AI assistant query: {question[:50]}...")
+            
+            # Get proof if provided
+            proof = None
+            if proof_id:
+                proof = self.storage_agent.get_proof(proof_id)
+            
+            assistant_response = self.ai_sidecar.answer_question(
+                question,
+                proof
+            )
+            
+            return {
+                "success": True,
+                "assistant": assistant_response.to_dict(),
+                "message": "Question answered"
+            }
+            
+        except Exception as e:
+            logger.error(f"AI assistant query failed: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "message": "AI assistant query failed"
+            }
+    
+    def verify_proof(self, proof_id: str, content: bytes) -> Dict[str, Any]:
+        """
+        Verify an existing proof.
+        
+        Args:
+            proof_id: Unique proof identifier
+            content: Original content to verify
+        
+        Returns:
+            {
+                "success": bool,
+                "verification_result": VerificationResult,
+                "message": str
+            }
+        """
+        try:
+            logger.info(f"Starting proof verification: {proof_id}")
+            
+            result = self.verification_agent.execute({
+                "proof_id": proof_id,
+                "content": content
+            })
+            
+            verification_result = result["verification_result"]
+            
+            logger.info(f"Verification completed: {verification_result.message}")
+            
+            result = {
+                "success": True,
+                "verification_result": verification_result,
+                "message": verification_result.message
+            }
+            
+            # OPTIONAL: AI Sidecar explains verification (non-blocking)
+            if self.ai_sidecar.enabled:
+                try:
+                    # Get original proof for context
+                    proof = self.storage_agent.get_proof(proof_id)
+                    assistant_response = self.ai_sidecar.explain_verification(
+                        verification_result,
+                        proof
+                    )
+                    result["assistant"] = assistant_response.to_dict()
+                    logger.info("AI verification explanation added")
+                except Exception as e:
+                    logger.warning(f"AI explanation failed (non-critical): {str(e)}")
+                    # AI failure does not affect core response
+            
+            return result
+            
+        except ProofSystemError as e:
+            logger.error(f"Verification failed: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": e.__class__.__name__,
+                "message": "Verification failed"
+            }
+        except Exception as e:
+            logger.error(f"Unexpected error: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": "UnexpectedError",
+                "message": "An unexpected error occurred"
+            }
+    
+    def get_proof(self, proof_id: str) -> Dict[str, Any]:
+        """
+        Retrieve a proof from storage.
+        
+        Args:
+            proof_id: Unique proof identifier
+        
+        Returns:
+            {
+                "success": bool,
+                "proof": Proof | None,
+                "message": str
+            }
+        """
+        try:
+            logger.info(f"Retrieving proof: {proof_id}")
+            
+            proof = self.storage_agent.get_proof(proof_id)
+            
+            if not proof:
+                return {
+                    "success": False,
+                    "proof": None,
+                    "message": f"Proof not found: {proof_id}"
+                }
+            
+            return {
+                "success": True,
+                "proof": proof,
+                "message": "Proof retrieved successfully"
+            }
+            
+        except ProofSystemError as e:
+            logger.error(f"Proof retrieval failed: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": e.__class__.__name__,
+                "message": "Proof retrieval failed"
+            }
+        except Exception as e:
+            logger.error(f"Unexpected error: {str(e)}")
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": "UnexpectedError",
+                "message": "An unexpected error occurred"
+            }

deo.py

@@ -0,0 +1 @@
+print("run")

docker-compose.yml

@@ -0,0 +1,40 @@
+version: '3.8'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    environment:
+      # Core settings
+      - MAX_FILE_SIZE_MB=10
+      - HASH_ALGORITHM=sha256
+      
+      # OCR settings (optional)
+      - OCR_ENABLED=true
+      - OCR_LANGUAGE=eng
+      
+      # AI settings (optional - set your key)
+      - AI_ENABLED=${AI_ENABLED:-false}
+      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+      - GEMINI_MODEL=gemini-1.5-flash
+      
+      # Storage settings (configure when ready)
+      - SUPABASE_URL=${SUPABASE_URL:-}
+      - SUPABASE_KEY=${SUPABASE_KEY:-}
+      - SUPABASE_TABLE=proofs
+    
+    volumes:
+      # Mount .env file for local development
+      - ./.env:/app/.env:ro
+    
+    restart: unless-stopped
+    
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s

image_base64.txt

@@ -0,0 +1 @@
+��

main.py

@@ -0,0 +1,244 @@
+"""
+Main Entry Point
+Demonstrates orchestrator usage with example workflows.
+No business logic - just a thin interface layer.
+"""
+from dotenv import load_dotenv
+load_dotenv()
+
+from core.orchestrator import Orchestrator
+
+
+print(">>> MAIN FILE LOADED <<<")
+
+
+def example_text_proof():
+    """Example: Create proof from text content."""
+    print("\n=== Example 1: Text Proof Creation ===")
+    
+    orchestrator = Orchestrator()
+    
+    # Create proof from text
+    result = orchestrator.create_proof({
+        "type": "text",
+        "content": "This is a confidential document that needs timestamping."
+    })
+    
+    if result["success"]:
+        print(f"✓ Proof created: {result['proof_id']}")
+        print(f"  Hash: {result['proof'].content_hash}")
+        print(f"  Timestamp: {result['proof'].timestamp}")
+        
+        # AI explanation (if available)
+        if "assistant" in result:
+            print(f"\n  🤖 AI Explanation:")
+            print(f"  {result['assistant']['response']}")
+    else:
+        print(f"✗ Failed: {result['message']}")
+    
+    return result
+
+
+def example_file_proof():
+    """Example: Create proof from file content."""
+    print("\n=== Example 2: File Proof Creation ===")
+    
+    orchestrator = Orchestrator()
+    
+    # Simulate file content
+    file_content = b"Binary file content here"
+    
+    result = orchestrator.create_proof({
+        "type": "file",
+        "content": file_content,
+        "filename": "document.pdf"
+    })
+    
+    if result["success"]:
+        print(f"✓ Proof created: {result['proof_id']}")
+        print(f"  Hash: {result['proof'].content_hash}")
+        print(f"  File: {result['proof'].metadata['filename']}")
+        print(f"  OCR Status: {result['proof'].ocr_status}")
+        if result['proof'].extracted_text:
+            print(f"  Extracted Text: {result['proof'].extracted_text[:100]}...")
+    else:
+        print(f"✗ Failed: {result['message']}")
+    
+    return result
+
+
+def example_image_ocr():
+    """Example: Create proof from image with OCR."""
+    print("\n=== Example 5: Image Proof with OCR ===")
+    
+    orchestrator = Orchestrator()
+    
+    # Note: In real usage, this would be actual image bytes
+    # For demo, we'll just show the structure
+    print("Note: This example requires actual image bytes with text.")
+    print("Skipping OCR demo - install Tesseract and provide real image to test.")
+    
+    # Example structure:
+    # with open("invoice.png", "rb") as f:
+    #     image_bytes = f.read()
+    # 
+    # result = orchestrator.create_proof({
+    #     "type": "file",
+    #     "content": image_bytes,
+    #     "filename": "invoice.png"
+    # })
+    # 
+    # if result["success"]:
+    #     print(f"✓ Proof created with OCR")
+    #     print(f"  Extracted: {result['proof'].extracted_text}")
+    
+    print("✓ OCR integration ready for image inputs")
+
+
+def example_ai_assistant():
+    """Example: Ask AI assistant about proofs."""
+    print("\n=== Example 6: AI Assistant Q&A ===")
+    
+    orchestrator = Orchestrator()
+    
+    if not orchestrator.ai_sidecar.enabled:
+        print("⚠️  AI assistant is disabled")
+        print("   Enable with: AI_ENABLED=true GEMINI_API_KEY=your-key")
+        return
+    
+    # Create a proof first
+    create_result = orchestrator.create_proof({
+        "type": "text",
+        "content": "Important contract signed on December 24, 2024"
+    })
+    
+    if not create_result["success"]:
+        print("Failed to create proof for demo")
+        return
+    
+    proof_id = create_result["proof_id"]
+    
+    # Ask AI about the proof
+    questions = [
+        "What does this proof guarantee?",
+        "How can I verify this proof later?",
+        "What should I do with this proof ID?"
+    ]
+    
+    for question in questions:
+        print(f"\n  Q: {question}")
+        result = orchestrator.ask_assistant(question, proof_id)
+        
+        if result["success"]:
+            print(f"  🤖 A: {result['assistant']['response']}")
+        else:
+            print(f"  ✗ {result['message']}")
+
+
+def example_verification():
+    """Example: Verify an existing proof."""
+    print("\n=== Example 3: Proof Verification ===")
+    
+    orchestrator = Orchestrator()
+    
+    # First create a proof
+    original_content = "Verify this content"
+    create_result = orchestrator.create_proof({
+        "type": "text",
+        "content": original_content
+    })
+    
+    if not create_result["success"]:
+        print("Failed to create proof for verification")
+        return
+    
+    proof_id = create_result["proof_id"]
+    print(f"Created proof: {proof_id}")
+    
+    # Verify with correct content
+    verify_result = orchestrator.verify_proof(
+        proof_id,
+        original_content.encode('utf-8')
+    )
+    
+    if verify_result["success"]:
+        vr = verify_result["verification_result"]
+        status = "✓ VALID" if vr.is_valid else "✗ INVALID"
+        print(f"{status}: {vr.message}")
+        
+        # AI explanation (if available)
+        if "assistant" in verify_result:
+            print(f"\n  🤖 AI Explanation:")
+            print(f"  {verify_result['assistant']['response']}")
+    else:
+        print(f"✗ Verification failed: {verify_result['message']}")
+    
+    # Verify with tampered content
+    print("\nAttempting verification with tampered content:")
+    tampered_result = orchestrator.verify_proof(
+        proof_id,
+        b"Tampered content"
+    )
+    
+    if tampered_result["success"]:
+        vr = tampered_result["verification_result"]
+        status = "✓ VALID" if vr.is_valid else "✗ INVALID"
+        print(f"{status}: {vr.message}")
+
+
+def example_retrieval():
+    """Example: Retrieve a stored proof."""
+    print("\n=== Example 4: Proof Retrieval ===")
+    
+    orchestrator = Orchestrator()
+    
+    # Create a proof first
+    create_result = orchestrator.create_proof({
+        "type": "text",
+        "content": "Retrieve this later"
+    })
+    
+    if not create_result["success"]:
+        print("Failed to create proof")
+        return
+    
+    proof_id = create_result["proof_id"]
+    
+    # Retrieve it
+    get_result = orchestrator.get_proof(proof_id)
+    
+    if get_result["success"]:
+        proof = get_result["proof"]
+        print(f"✓ Retrieved proof: {proof.proof_id}")
+        print(f"  Hash: {proof.content_hash}")
+        print(f"  Size: {proof.content_size} bytes")
+        print(f"  Created: {proof.timestamp}")
+    else:
+        print(f"✗ Failed: {get_result['message']}")
+
+
+def main():
+    """Run all examples."""
+    print("=" * 60)
+    print("PROOF-OF-EXISTENCE SYSTEM - Priority-3 MVP")
+    print("Deterministic Core + OCR + AI Sidecar")
+    print("=" * 60)
+    
+    try:
+        example_text_proof()
+        example_file_proof()
+        example_verification()
+        example_retrieval()
+        example_image_ocr()
+        example_ai_assistant()
+        
+        print("\n" + "=" * 60)
+        print("All examples completed successfully!")
+        print("=" * 60)
+        
+    except Exception as e:
+        print(f"\n✗ Error running examples: {str(e)}")
+
+
+if __name__ == "__main__":
+    main()

models/proof.py

@@ -0,0 +1,61 @@
+"""
+Proof data model representing a cryptographic proof of existence.
+"""
+
+from dataclasses import dataclass, asdict
+from typing import Optional
+from datetime import datetime
+import json
+
+
+@dataclass
+class Proof:
+    """
+    Immutable proof object containing hash, metadata, and validation info.
+    """
+    proof_id: str
+    content_hash: str
+    hash_algorithm: str
+    content_type: str
+    content_size: int
+    timestamp: str
+    validation_status: str
+    metadata: dict
+    extracted_text: Optional[str] = None  # OCR output (if applicable)
+    ocr_engine: Optional[str] = None  # Fixed: "tesseract"
+    ocr_status: Optional[str] = None  # "success" | "skipped" | "failed"
+    
+    def to_dict(self) -> dict:
+        """Convert proof to dictionary."""
+        return asdict(self)
+    
+    def to_json(self) -> str:
+        """Serialize proof to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Proof':
+        """Create proof from dictionary."""
+        return cls(**data)
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> 'Proof':
+        """Deserialize proof from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+
+
+@dataclass
+class VerificationResult:
+    """
+    Result of proof verification operation.
+    """
+    proof_id: str
+    is_valid: bool
+    original_hash: str
+    computed_hash: str
+    timestamp: str
+    message: str
+    
+    def to_dict(self) -> dict:
+        """Convert result to dictionary."""
+        return asdict(self)

requirements.txt

@@ -0,0 +1,22 @@
+# Core dependencies
+python-multipart
+
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+python-dotenv==1.0.0
+pydantic==2.5.3
+
+# OCR dependencies (optional but recommended)
+pytesseract==0.3.10
+Pillow==10.2.0
+
+# AI dependencies (optional)
+google-generativeai==0.3.2
+
+# Storage dependencies (when Supabase is connected)
+# supabase==2.3.0
+
+# Development dependencies (uncomment for local dev)
+# pytest==7.4.3
+# pytest-asyncio==0.23.3
+# httpx==0.26.0

sidecar/gemini_sidecar.py

@@ -0,0 +1,412 @@
+"""
+Gemini AI Sidecar
+Non-authoritative assistant layer for proof explanation and guidance.
+
+CRITICAL: This module is an OBSERVER, not a decision-maker.
+- It explains proofs, never validates them
+- It guides users, never creates proofs
+- It fails gracefully, never blocks core operations
+"""
+
+from typing import Dict, Any, Optional
+import logging
+from dataclasses import dataclass
+
+from models.proof import Proof, VerificationResult
+from config.settings import settings
+
+# Lazy import - only load if AI is enabled
+try:
+    import google.generativeai as genai
+    GEMINI_AVAILABLE = True
+except ImportError:
+    GEMINI_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AssistantResponse:
+    """
+    Non-authoritative AI response wrapper.
+    Makes it explicit that this is guidance, not fact.
+    """
+    provider: str = "gemini"
+    role: str = "explanatory"
+    response: str = ""
+    confidence: str = "non-authoritative"
+    error: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "provider": self.provider,
+            "role": self.role,
+            "response": self.response,
+            "confidence": self.confidence
+        }
+        if self.error:
+            result["error"] = self.error
+        return result
+
+
+class GeminiSidecar:
+    """
+    AI Sidecar for providing explanations and guidance.
+    
+    This is NOT part of the deterministic core.
+    All methods return graceful fallbacks on failure.
+    """
+    
+    def __init__(self):
+        """Initialize Gemini client if available and configured."""
+        self.enabled = False
+        self.client = None
+        self._initialize()
+    
+    def _initialize(self):
+        """
+        Initialize Gemini client.
+        Fails gracefully if dependencies missing or API key invalid.
+        """
+        # Check if AI is enabled in config
+        if not settings.AI_ENABLED:
+            logger.info("AI Sidecar is disabled in configuration")
+            return
+        
+        # Check if dependencies available
+        if not GEMINI_AVAILABLE:
+            logger.warning(
+                "Gemini dependencies not available. "
+                "Install with: pip install google-generativeai"
+            )
+            return
+        
+        # Check if API key is configured
+        if not settings.validate_ai():
+            logger.warning(
+                "Gemini API key not configured. "
+                "Set GEMINI_API_KEY environment variable to enable AI features."
+            )
+            return
+        
+        try:
+            # Configure Gemini
+            genai.configure(api_key=settings.GEMINI_API_KEY)
+            self.client = genai.GenerativeModel(settings.GEMINI_MODEL)
+            self.enabled = True
+            logger.info(f"AI Sidecar initialized with model: {settings.GEMINI_MODEL}")
+        except Exception as e:
+            logger.error(f"Failed to initialize Gemini client: {str(e)}")
+            self.enabled = False
+    
+    def explain_proof(self, proof: Proof) -> AssistantResponse:
+        """
+        Explain what a proof means in plain language.
+        
+        Args:
+            proof: Proof object to explain
+            
+        Returns:
+            AssistantResponse with explanation or fallback
+        """
+        if not self.enabled:
+            return self._fallback_explain_proof(proof)
+        
+        try:
+            prompt = self._build_proof_explanation_prompt(proof)
+            response = self._call_gemini(prompt)
+            
+            return AssistantResponse(
+                response=response
+            )
+            
+        except Exception as e:
+            logger.error(f"AI explanation failed: {str(e)}")
+            return self._fallback_explain_proof(proof)
+    
+    def explain_verification(
+        self,
+        verification_result: VerificationResult,
+        proof: Optional[Proof] = None
+    ) -> AssistantResponse:
+        """
+        Explain what a verification result means.
+        
+        Args:
+            verification_result: Verification result to explain
+            proof: Optional original proof for context
+            
+        Returns:
+            AssistantResponse with explanation or fallback
+        """
+        if not self.enabled:
+            return self._fallback_explain_verification(verification_result)
+        
+        try:
+            prompt = self._build_verification_explanation_prompt(
+                verification_result,
+                proof
+            )
+            response = self._call_gemini(prompt)
+            
+            return AssistantResponse(
+                response=response
+            )
+            
+        except Exception as e:
+            logger.error(f"AI verification explanation failed: {str(e)}")
+            return self._fallback_explain_verification(verification_result)
+    
+    def summarize_content(self, extracted_text: str) -> AssistantResponse:
+        """
+        Summarize extracted text content.
+        
+        Args:
+            extracted_text: Text extracted from OCR or document
+            
+        Returns:
+            AssistantResponse with summary or fallback
+        """
+        if not self.enabled:
+            return self._fallback_summarize(extracted_text)
+        
+        if not extracted_text or not extracted_text.strip():
+            return AssistantResponse(
+                response="No text content available to summarize."
+            )
+        
+        try:
+            prompt = self._build_summarization_prompt(extracted_text)
+            response = self._call_gemini(prompt)
+            
+            return AssistantResponse(
+                response=response
+            )
+            
+        except Exception as e:
+            logger.error(f"AI summarization failed: {str(e)}")
+            return self._fallback_summarize(extracted_text)
+    
+    def answer_question(
+        self,
+        question: str,
+        proof: Optional[Proof] = None,
+        context: Optional[str] = None
+    ) -> AssistantResponse:
+        """
+        Answer user questions about proofs or content.
+        
+        Args:
+            question: User's question
+            proof: Optional proof for context
+            context: Optional additional context
+            
+        Returns:
+            AssistantResponse with answer or fallback
+        """
+        if not self.enabled:
+            return self._fallback_answer()
+        
+        try:
+            prompt = self._build_question_prompt(question, proof, context)
+            response = self._call_gemini(prompt)
+            
+            return AssistantResponse(
+                response=response
+            )
+            
+        except Exception as e:
+            logger.error(f"AI question answering failed: {str(e)}")
+            return self._fallback_answer()
+    
+    def _call_gemini(self, prompt: str) -> str:
+        """
+        Make API call to Gemini with timeout and error handling.
+        
+        Args:
+            prompt: Prompt to send to Gemini
+            
+        Returns:
+            Generated response text
+            
+        Raises:
+            Exception: If API call fails
+        """
+        if not self.client:
+            raise Exception("Gemini client not initialized")
+        
+        # Generate response with timeout
+        response = self.client.generate_content(
+            prompt,
+            generation_config={
+                "temperature": 0.7,
+                "max_output_tokens": 500,
+            }
+        )
+        
+        return response.text.strip()
+    
+    def _build_proof_explanation_prompt(self, proof: Proof) -> str:
+        """Build prompt for proof explanation."""
+        return f"""You are an assistant explaining a cryptographic proof of existence.
+
+Proof Details:
+- Proof ID: {proof.proof_id}
+- Content Type: {proof.content_type}
+- Content Size: {proof.content_size} bytes
+- Hash: {proof.content_hash[:16]}...
+- Timestamp: {proof.timestamp}
+- OCR Status: {proof.ocr_status or 'not applicable'}
+
+Explain in 2-3 sentences what this proof means and why it's useful.
+Focus on:
+1. What was proven (that content existed at a point in time)
+2. How it works (cryptographic hash)
+3. Why it's trustworthy (immutable)
+
+Keep it simple and non-technical."""
+    
+    def _build_verification_explanation_prompt(
+        self,
+        result: VerificationResult,
+        proof: Optional[Proof]
+    ) -> str:
+        """Build prompt for verification explanation."""
+        status = "VALID" if result.is_valid else "INVALID"
+        
+        prompt = f"""You are an assistant explaining a proof verification result.
+
+Verification Result:
+- Status: {status}
+- Original Hash: {result.original_hash[:16]}...
+- Computed Hash: {result.computed_hash[:16]}...
+- Match: {result.is_valid}
+
+Explain in 2-3 sentences what this verification result means.
+If valid: explain that the content hasn't changed.
+If invalid: explain that the content has been modified."""
+        
+        if proof and proof.extracted_text:
+            prompt += f"\n\nOriginal content was: {proof.content_type}"
+        
+        return prompt + "\n\nKeep it simple and actionable."
+    
+    def _build_summarization_prompt(self, text: str) -> str:
+        """Build prompt for content summarization."""
+        # Truncate if very long
+        max_chars = 2000
+        truncated = text[:max_chars]
+        if len(text) > max_chars:
+            truncated += "... (truncated)"
+        
+        return f"""Summarize the following text in 2-3 sentences:
+
+{truncated}
+
+Focus on:
+- Main topic or purpose
+- Key information
+- Document type (if identifiable)
+
+Keep it concise and factual."""
+    
+    def _build_question_prompt(
+        self,
+        question: str,
+        proof: Optional[Proof],
+        context: Optional[str]
+    ) -> str:
+        """Build prompt for question answering."""
+        prompt = f"""You are an assistant helping users understand cryptographic proofs.
+
+User Question: {question}
+"""
+        
+        if proof:
+            prompt += f"""
+Proof Context:
+- Type: {proof.content_type}
+- Size: {proof.content_size} bytes
+- Created: {proof.timestamp}
+- Hash: {proof.content_hash[:16]}...
+"""
+            if proof.extracted_text:
+                prompt += f"- Extracted Text: {proof.extracted_text[:200]}...\n"
+        
+        if context:
+            prompt += f"\nAdditional Context: {context}\n"
+        
+        prompt += """
+Provide a helpful answer in 2-3 sentences.
+Remember: You are explaining, not validating.
+Focus on helping the user understand proofs and their uses."""
+        
+        return prompt
+    
+    # Fallback methods - used when AI is unavailable
+    
+    def _fallback_explain_proof(self, proof: Proof) -> AssistantResponse:
+        """Fallback explanation when AI is unavailable."""
+        response = (
+            f"This is a cryptographic proof that {proof.content_type} content "
+            f"({proof.content_size} bytes) existed at {proof.timestamp}. "
+            f"The proof uses a SHA-256 hash to ensure the content cannot be altered "
+            f"without detection."
+        )
+        
+        return AssistantResponse(
+            response=response,
+            error="AI assistant unavailable, using fallback explanation"
+        )
+    
+    def _fallback_explain_verification(
+        self,
+        result: VerificationResult
+    ) -> AssistantResponse:
+        """Fallback verification explanation when AI is unavailable."""
+        if result.is_valid:
+            response = (
+                "Verification successful: The content matches the original proof. "
+                "The cryptographic hash is identical, confirming no modifications "
+                "have been made."
+            )
+        else:
+            response = (
+                "Verification failed: The content does not match the original proof. "
+                "The cryptographic hashes differ, indicating the content has been "
+                "modified since the proof was created."
+            )
+        
+        return AssistantResponse(
+            response=response,
+            error="AI assistant unavailable, using fallback explanation"
+        )
+    
+    def _fallback_summarize(self, text: str) -> AssistantResponse:
+        """Fallback summarization when AI is unavailable."""
+        word_count = len(text.split())
+        char_count = len(text)
+        
+        preview = text[:150] + "..." if len(text) > 150 else text
+        
+        response = (
+            f"Content preview ({word_count} words, {char_count} characters): "
+            f"{preview}"
+        )
+        
+        return AssistantResponse(
+            response=response,
+            error="AI assistant unavailable, showing content preview"
+        )
+    
+    def _fallback_answer(self) -> AssistantResponse:
+        """Fallback answer when AI is unavailable."""
+        return AssistantResponse(
+            response=(
+                "AI assistant is currently unavailable. "
+                "For questions about proofs, refer to the documentation or "
+                "contact support."
+            ),
+            error="AI assistant unavailable"
+        )

test.py

@@ -0,0 +1,159 @@
+"""
+Simple test script for uploading images to the proof system.
+"""
+import requests
+import base64
+import json
+from pathlib import Path
+
+# API base URL
+BASE_URL = "http://127.0.0.1:8000"
+
+def test_text_proof():
+    """Test creating a proof from text."""
+    print("\n=== Testing Text Proof ===")
+    
+    response = requests.post(
+        f"{BASE_URL}/proof/create/text",
+        json={"content": "Hello, this is a test document!"}
+    )
+    
+    result = response.json()
+    print(f"Success: {result.get('success')}")
+    print(f"Proof ID: {result.get('proof_id')}")
+    print(f"Hash: {result.get('hash')}")
+    
+    if 'assistant' in result and result['assistant']:
+        print(f"\n🤖 AI: {result['assistant']['response']}")
+    
+    return result.get('proof_id')
+
+
+def test_image_proof(image_path):
+    """Test creating a proof from an image."""
+    print(f"\n=== Testing Image Proof: {image_path} ===")
+    
+    # Check if file exists
+    if not Path(image_path).exists():
+        print(f"❌ Error: File not found: {image_path}")
+        print(f"Current directory: {Path.cwd()}")
+        print(f"Available images: {list(Path('.').glob('*.png')) + list(Path('.').glob('*.jpg'))}")
+        return None
+    
+    # Use FastAPI's multipart/form-data upload (not base64)
+    with open(image_path, "rb") as f:
+        files = {"file": (Path(image_path).name, f, "image/png")}
+        
+        print(f"Uploading {Path(image_path).name}...")
+        
+        response = requests.post(
+            f"{BASE_URL}/proof/create/file",
+            files=files
+        )
+    
+    if response.status_code != 200:
+        print(f"❌ API Error {response.status_code}: {response.text}")
+        return None
+    
+    result = response.json()
+    
+    if not result.get('success'):
+        print(f"❌ Failed: {result.get('message')}")
+        if 'error' in result:
+            print(f"Error: {result['error']}")
+        return None
+    
+    print(f"✅ Success: {result.get('success')}")
+    print(f"Proof ID: {result.get('proof_id')}")
+    print(f"Hash: {result.get('hash')}")
+    print(f"OCR Status: {result.get('ocr_status')}")
+    
+    if result.get('extracted_text'):
+        text = result['extracted_text']
+        preview = text[:100] + "..." if len(text) > 100 else text
+        print(f"Extracted Text: {preview}")
+    else:
+        print("Extracted Text: (none - this is normal for photos)")
+    
+    if 'assistant' in result and result['assistant']:
+        print(f"\n🤖 AI: {result['assistant']['response']}")
+    
+    return result.get('proof_id'), Path(image_path).name
+
+
+def test_verify_proof(proof_id, original_content, filename=None):
+    """Test verifying a proof."""
+    print(f"\n=== Testing Verification: {proof_id} ===")
+    
+    # For file uploads, we need to re-upload the file
+    if filename:
+        print("⚠️  File verification requires the original file")
+        print(f"   API endpoint: POST /proof/verify")
+        print(f"   Body: {{'proof_id': '{proof_id}', 'content': 'original_content_as_string'}}")
+        return
+    
+    # For text content
+    if isinstance(original_content, bytes):
+        content_str = original_content.decode('utf-8')
+    else:
+        content_str = original_content
+    
+    response = requests.post(
+        f"{BASE_URL}/proof/verify",
+        json={
+            "proof_id": proof_id,
+            "content": content_str
+        }
+    )
+    
+    if response.status_code != 200:
+        print(f"❌ API Error {response.status_code}: {response.text}")
+        return
+    
+    result = response.json()
+    print(f"Valid: {result.get('is_valid')}")
+    print(f"Message: {result.get('message')}")
+    
+    if 'assistant' in result and result['assistant']:
+        print(f"\n🤖 AI: {result['assistant']['response']}")
+
+
+def main():
+    """Run all tests."""
+    print("=" * 60)
+    print("PROOF SYSTEM - API TESTS")
+    print("=" * 60)
+    
+    # Test 1: Text proof
+    text_proof_id = test_text_proof()
+    
+    # Test 2: Verify text proof
+    if text_proof_id:
+        test_verify_proof(text_proof_id, "Hello, this is a test document!")
+    
+    # Test 3: Image proof
+    image_files = ["test1.png", "test1.jpg", "test1.jpeg"]
+    image_path = None
+    
+    for img in image_files:
+        if Path(img).exists():
+            image_path = img
+            break
+    
+    if image_path:
+        result = test_image_proof(image_path)
+        
+        if result:
+            image_proof_id, filename = result
+            # Note: File verification needs special handling
+            print(f"\n💡 To verify the image proof, use proof ID: {image_proof_id}")
+    else:
+        print("\n⚠️  No test1 image found. Place test1.png in the backend folder.")
+    
+    print("\n" + "=" * 60)
+    print("Tests completed!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()