Arch: Add Protocol 4 (Autonomous Resource Integration) - connectors.py, AGENTS.md, .env.template

.env.template

@@ -0,0 +1,15 @@
+# Environment Configuration Template
+# Copy to .env and fill in values
+
+# Hugging Face API Token (optional, for private models)
+# Get from: https://huggingface.co/settings/tokens
+HF_TOKEN=
+
+# Hugging Face Space ID (for deployment)
+HF_SPACE_ID=ANXLOG/LOGOS-SPCW-Matroska
+
+# LOGOS Debug Mode (set to 1 for verbose logging)
+LOGOS_DEBUG=0
+
+# Number of parallel workers for DSP operations
+NUM_WORKERS=16

logos/connectors.py

@@ -0,0 +1,272 @@
+"""
+connectors.py - External API/Service Adapters
+Protocol 4: Autonomous Resource Integration
+
+This module isolates all external dependencies so the core engine remains pure.
+Each connector wraps an external API/library with a standardized interface.
+"""
+
+import os
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+
+
+# ==========================================
+# CONFIGURATION
+# ==========================================
+
+@dataclass
+class ConnectorConfig:
+    """Configuration for external connectors."""
+    hf_token: Optional[str] = None
+    hf_space_id: Optional[str] = None
+    
+    @classmethod
+    def from_env(cls) -> 'ConnectorConfig':
+        """Load configuration from environment variables."""
+        return cls(
+            hf_token=os.environ.get('HF_TOKEN'),
+            hf_space_id=os.environ.get('HF_SPACE_ID')
+        )
+
+
+# ==========================================
+# HUGGING FACE CONNECTOR
+# ==========================================
+
+class HuggingFaceConnector:
+    """
+    Adapter for Hugging Face Hub and Inference API.
+    Wraps huggingface_hub for model loading and inference.
+    """
+    
+    def __init__(self, config: ConnectorConfig = None):
+        self.config = config or ConnectorConfig.from_env()
+        self._client = None
+    
+    def _ensure_client(self):
+        """Lazy initialization of HF client."""
+        if self._client is None:
+            try:
+                from huggingface_hub import InferenceClient
+                self._client = InferenceClient(token=self.config.hf_token)
+            except ImportError:
+                raise ImportError("huggingface_hub not installed. Run: pip install huggingface_hub")
+        return self._client
+    
+    def image_to_text(self, image_path: str, model: str = "Salesforce/blip-image-captioning-base") -> str:
+        """
+        Generate text description from image using HF Inference API.
+        
+        Args:
+            image_path: Path to image file
+            model: HF model ID for image captioning
+            
+        Returns:
+            Generated text description
+        """
+        client = self._ensure_client()
+        with open(image_path, 'rb') as f:
+            result = client.image_to_text(f.read(), model=model)
+        return result
+    
+    def text_generation(self, prompt: str, model: str = "gpt2", max_length: int = 100) -> str:
+        """
+        Generate text from prompt using HF Inference API.
+        
+        Args:
+            prompt: Input text prompt
+            model: HF model ID for text generation
+            max_length: Maximum output length
+            
+        Returns:
+            Generated text
+        """
+        client = self._ensure_client()
+        result = client.text_generation(prompt, model=model, max_new_tokens=max_length)
+        return result
+
+
+# ==========================================
+# OCR CONNECTOR
+# ==========================================
+
+class OCRConnector:
+    """
+    Adapter for EasyOCR.
+    Provides text extraction from images.
+    """
+    
+    def __init__(self, languages: List[str] = None, gpu: bool = False):
+        self.languages = languages or ['en']
+        self.gpu = gpu
+        self._reader = None
+    
+    def _ensure_reader(self):
+        """Lazy initialization of EasyOCR reader."""
+        if self._reader is None:
+            try:
+                import easyocr
+                self._reader = easyocr.Reader(self.languages, gpu=self.gpu)
+            except ImportError:
+                raise ImportError("easyocr not installed. Run: pip install easyocr")
+        return self._reader
+    
+    def extract_text(self, image_path: str) -> Dict[str, Any]:
+        """
+        Extract text from image.
+        
+        Args:
+            image_path: Path to image file
+            
+        Returns:
+            Dict with text_blocks and full_text
+        """
+        reader = self._ensure_reader()
+        results = reader.readtext(image_path)
+        
+        text_blocks = [
+            {"text": text, "confidence": conf, "bbox": bbox}
+            for bbox, text, conf in results
+        ]
+        full_text = " ".join([r[1] for r in results])
+        
+        return {
+            "text_blocks": text_blocks,
+            "full_text": full_text,
+            "word_count": len(full_text.split())
+        }
+
+
+# ==========================================
+# VISION CONNECTOR (Future: Multi-modal)
+# ==========================================
+
+class VisionConnector:
+    """
+    Adapter for computer vision operations.
+    Wraps OpenCV and scikit-image.
+    """
+    
+    @staticmethod
+    def calculate_ssim(image1_path: str, image2_path: str) -> float:
+        """
+        Calculate Structural Similarity Index between two images.
+        Uses scikit-image for accurate SSIM calculation.
+        
+        Args:
+            image1_path: Path to first image
+            image2_path: Path to second image
+            
+        Returns:
+            SSIM score (0-1, higher is better)
+        """
+        try:
+            import cv2
+            from skimage.metrics import structural_similarity as ssim
+            
+            img1 = cv2.imread(image1_path)
+            img2 = cv2.imread(image2_path)
+            
+            # Resize if needed
+            if img1.shape != img2.shape:
+                img2 = cv2.resize(img2, (img1.shape[1], img1.shape[0]))
+            
+            # Convert to grayscale for SSIM
+            gray1 = cv2.cvtColor(img1, cv2.COLOR_BGR2GRAY)
+            gray2 = cv2.cvtColor(img2, cv2.COLOR_BGR2GRAY)
+            
+            return ssim(gray1, gray2)
+            
+        except ImportError as e:
+            raise ImportError(f"Required library not installed: {e}")
+    
+    @staticmethod
+    def analyze_entropy(image_path: str) -> Dict[str, float]:
+        """
+        Analyze image entropy (information density).
+        
+        Args:
+            image_path: Path to image file
+            
+        Returns:
+            Dict with entropy metrics
+        """
+        try:
+            import cv2
+            import numpy as np
+            from skimage.measure import shannon_entropy
+            
+            img = cv2.imread(image_path)
+            gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+            
+            # Calculate entropy
+            entropy = shannon_entropy(gray)
+            
+            # Calculate histogram entropy
+            hist = cv2.calcHist([gray], [0], None, [256], [0, 256])
+            hist = hist.flatten() / hist.sum()
+            hist_entropy = -np.sum(hist[hist > 0] * np.log2(hist[hist > 0]))
+            
+            return {
+                "shannon_entropy": entropy,
+                "histogram_entropy": hist_entropy,
+                "mean_intensity": float(np.mean(gray)),
+                "std_intensity": float(np.std(gray))
+            }
+            
+        except ImportError as e:
+            raise ImportError(f"Required library not installed: {e}")
+
+
+# ==========================================
+# FACTORY
+# ==========================================
+
+def get_connector(connector_type: str, **kwargs) -> Any:
+    """
+    Factory function for connectors.
+    
+    Args:
+        connector_type: One of 'hf', 'ocr', 'vision'
+        **kwargs: Connector-specific arguments
+        
+    Returns:
+        Initialized connector instance
+    """
+    connectors = {
+        'hf': HuggingFaceConnector,
+        'ocr': OCRConnector,
+        'vision': VisionConnector
+    }
+    
+    if connector_type not in connectors:
+        raise ValueError(f"Unknown connector type: {connector_type}. Available: {list(connectors.keys())}")
+    
+    return connectors[connector_type](**kwargs)
+
+
+# ==========================================
+# REGISTRY (For Protocol 4 Discovery)
+# ==========================================
+
+AVAILABLE_CONNECTORS = {
+    'hf': {
+        'name': 'Hugging Face',
+        'capabilities': ['image_to_text', 'text_generation'],
+        'requires': ['huggingface_hub'],
+        'env_vars': ['HF_TOKEN']
+    },
+    'ocr': {
+        'name': 'EasyOCR',
+        'capabilities': ['extract_text'],
+        'requires': ['easyocr'],
+        'env_vars': []
+    },
+    'vision': {
+        'name': 'Vision (OpenCV/scikit-image)',
+        'capabilities': ['calculate_ssim', 'analyze_entropy'],
+        'requires': ['opencv-python-headless', 'scikit-image'],
+        'env_vars': []
+    }
+}