empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/monitoring/multi_backend.py

@@ -1,271 +0,0 @@
-"""Multi-Backend Telemetry Support
-
-Enables simultaneous logging to multiple backends (JSONL + OTEL).
-
-**Features:**
-- Composite pattern for multiple backends
-- Parallel writes to all configured backends
-- Graceful handling of backend failures
-- Automatic backend selection based on configuration
-
-**Example:**
-```python
-from empathy_os.monitoring import TelemetryStore
-from empathy_os.monitoring.otel_backend import OTELBackend
-from empathy_os.monitoring.multi_backend import MultiBackend
-
-# Create composite backend
-backends = [
-    TelemetryStore(),           # JSONL (always enabled)
-    OTELBackend(),              # OTEL (if configured)
-]
-multi = MultiBackend(backends)
-
-# Logs to both backends
-multi.log_call(record)
-```
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-from typing import Protocol, runtime_checkable
-
-from empathy_os.models.telemetry import LLMCallRecord, TelemetryStore, WorkflowRunRecord
-
-
-@runtime_checkable
-class TelemetryBackend(Protocol):
-    """Protocol for telemetry storage backends.
-
-    All backends must implement log_call() and log_workflow().
-    """
-
-    def log_call(self, record: LLMCallRecord) -> None:
-        """Log an LLM call record."""
-        ...
-
-    def log_workflow(self, record: WorkflowRunRecord) -> None:
-        """Log a workflow run record."""
-        ...
-
-
-class MultiBackend:
-    """Composite backend for simultaneous logging to multiple backends.
-
-    Implements the TelemetryBackend protocol and forwards calls to all
-    configured backends. Handles failures gracefully - if one backend
-    fails, others continue to work.
-
-    **Auto-Configuration:**
-    - JSONL backend is always enabled (default)
-    - OTEL backend is enabled if EMPATHY_OTEL_ENDPOINT is set
-
-    Example:
-        >>> backend = MultiBackend.from_config()
-        >>> backend.log_call(call_record)  # Logs to JSONL + OTEL
-        >>> backend.log_workflow(workflow_record)
-    """
-
-    def __init__(self, backends: list[TelemetryBackend] | None = None):
-        """Initialize multi-backend.
-
-        Args:
-            backends: List of backend instances (default: auto-detect)
-        """
-        self.backends = backends or []
-        self._failed_backends: set[int] = set()
-
-    @classmethod
-    def from_config(cls, storage_dir: str = ".empathy") -> "MultiBackend":
-        """Create multi-backend from configuration.
-
-        Auto-detects available backends:
-        1. JSONL backend (always enabled)
-        2. OTEL backend (if EMPATHY_OTEL_ENDPOINT is set or collector detected)
-
-        Args:
-            storage_dir: Directory for JSONL storage (default: .empathy)
-
-        Returns:
-            MultiBackend instance with all available backends
-        """
-        backends: list[TelemetryBackend] = []
-
-        # Always add JSONL backend
-        try:
-            jsonl_backend = TelemetryStore(storage_dir)
-            backends.append(jsonl_backend)
-        except Exception as e:
-            print(f"⚠️  Failed to initialize JSONL backend: {e}")
-
-        # Add OTEL backend if configured
-        try:
-            from empathy_os.monitoring.otel_backend import OTELBackend
-
-            otel_backend = OTELBackend()
-            if otel_backend.is_available():
-                backends.append(otel_backend)
-        except ImportError:
-            # OTEL dependencies not installed
-            pass
-        except Exception as e:
-            print(f"⚠️  Failed to initialize OTEL backend: {e}")
-
-        return cls(backends)
-
-    def add_backend(self, backend: TelemetryBackend) -> None:
-        """Add a backend to the multi-backend.
-
-        Args:
-            backend: Backend instance to add
-        """
-        if isinstance(backend, TelemetryBackend):
-            self.backends.append(backend)
-        else:
-            raise TypeError(
-                f"Backend must implement TelemetryBackend protocol, got {type(backend)}"
-            )
-
-    def remove_backend(self, backend: TelemetryBackend) -> None:
-        """Remove a backend from the multi-backend.
-
-        Args:
-            backend: Backend instance to remove
-        """
-        if backend in self.backends:
-            self.backends.remove(backend)
-
-    def log_call(self, record: LLMCallRecord) -> None:
-        """Log an LLM call record to all backends.
-
-        Failures in individual backends are logged but don't affect other backends.
-
-        Args:
-            record: LLM call record to log
-        """
-        for i, backend in enumerate(self.backends):
-            if i in self._failed_backends:
-                # Skip backends that have failed before
-                continue
-
-            try:
-                backend.log_call(record)
-            except Exception as e:
-                backend_name = type(backend).__name__
-                print(f"⚠️  Failed to log call to {backend_name}: {e}")
-                # Mark backend as failed to reduce log spam
-                self._failed_backends.add(i)
-
-    def log_workflow(self, record: WorkflowRunRecord) -> None:
-        """Log a workflow run record to all backends.
-
-        Failures in individual backends are logged but don't affect other backends.
-
-        Args:
-            record: Workflow run record to log
-        """
-        for i, backend in enumerate(self.backends):
-            if i in self._failed_backends:
-                # Skip backends that have failed before
-                continue
-
-            try:
-                backend.log_workflow(record)
-            except Exception as e:
-                backend_name = type(backend).__name__
-                print(f"⚠️  Failed to log workflow to {backend_name}: {e}")
-                # Mark backend as failed to reduce log spam
-                self._failed_backends.add(i)
-
-    def get_active_backends(self) -> list[str]:
-        """Get list of active backend names.
-
-        Returns:
-            List of backend class names that are active (not failed)
-        """
-        return [
-            type(backend).__name__
-            for i, backend in enumerate(self.backends)
-            if i not in self._failed_backends
-        ]
-
-    def get_failed_backends(self) -> list[str]:
-        """Get list of failed backend names.
-
-        Returns:
-            List of backend class names that have failed
-        """
-        return [
-            type(self.backends[i]).__name__ for i in self._failed_backends if i < len(self.backends)
-        ]
-
-    def reset_failures(self) -> None:
-        """Reset failed backend tracking.
-
-        Allows retry of previously failed backends.
-        """
-        self._failed_backends.clear()
-
-    def flush(self) -> None:
-        """Flush all backends.
-
-        Calls flush() on backends that support it (e.g., OTEL backend).
-        """
-        for backend in self.backends:
-            if hasattr(backend, "flush"):
-                try:
-                    backend.flush()
-                except Exception as e:
-                    backend_name = type(backend).__name__
-                    print(f"⚠️  Failed to flush {backend_name}: {e}")
-
-    def __len__(self) -> int:
-        """Return number of active backends."""
-        return len(self.backends) - len(self._failed_backends)
-
-    def __repr__(self) -> str:
-        """String representation."""
-        active = self.get_active_backends()
-        failed = self.get_failed_backends()
-        status = f"active={active}"
-        if failed:
-            status += f", failed={failed}"
-        return f"MultiBackend({status})"
-
-
-# Singleton instance for global access
-_global_backend: MultiBackend | None = None
-
-
-def get_multi_backend(storage_dir: str = ".empathy") -> MultiBackend:
-    """Get or create the global multi-backend instance.
-
-    This is the recommended way to get a multi-backend instance.
-    It ensures a single instance is shared across the application.
-
-    Args:
-        storage_dir: Directory for JSONL storage (default: .empathy)
-
-    Returns:
-        Global MultiBackend instance
-
-    Example:
-        >>> backend = get_multi_backend()
-        >>> backend.log_call(record)
-    """
-    global _global_backend
-    if _global_backend is None:
-        _global_backend = MultiBackend.from_config(storage_dir)
-    return _global_backend
-
-
-def reset_multi_backend() -> None:
-    """Reset the global multi-backend instance.
-
-    Useful for testing or reconfiguration.
-    """
-    global _global_backend
-    if _global_backend is not None:
-        _global_backend.flush()
-    _global_backend = None

empathy_os/monitoring/otel_backend.py

@@ -1,362 +0,0 @@
-"""OpenTelemetry Backend for LLM Telemetry
-
-Exports telemetry data to OTEL-compatible collectors (SigNoz, Datadog, New Relic).
-
-**Features:**
-- Auto-detection of OTEL collector (localhost:4317)
-- Environment variable configuration (EMPATHY_OTEL_ENDPOINT)
-- Semantic conventions for LLM traces
-- Batch export with retry logic
-- Graceful fallback if collector unavailable
-
-**Setup:**
-```bash
-export EMPATHY_OTEL_ENDPOINT=http://localhost:4317
-pip install empathy-framework[otel]
-```
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-import os
-import socket
-
-from empathy_os.models.telemetry import LLMCallRecord, WorkflowRunRecord
-
-
-class OTELBackend:
-    """OpenTelemetry backend for exporting telemetry to OTEL collectors.
-
-    Implements the TelemetryBackend protocol for OTEL export.
-
-    **Auto-detection:**
-    - Checks for OTEL collector on localhost:4317
-    - Falls back to EMPATHY_OTEL_ENDPOINT environment variable
-
-    **Semantic Conventions:**
-    - LLM calls → OTEL spans with llm.* attributes
-    - Workflows → OTEL traces with workflow.* attributes
-
-    **Batch Export:**
-    - Buffers records and exports in batches
-    - Retries on transient failures
-    - Logs errors but doesn't crash
-
-    Example:
-        >>> backend = OTELBackend()
-        >>> if backend.is_available():
-        ...     backend.log_call(call_record)
-        ...     backend.log_workflow(workflow_record)
-    """
-
-    def __init__(
-        self,
-        endpoint: str | None = None,
-        batch_size: int = 10,
-        retry_count: int = 3,
-    ):
-        """Initialize OTEL backend.
-
-        Args:
-            endpoint: OTEL collector endpoint (default: auto-detect)
-            batch_size: Number of records to buffer before export
-            retry_count: Number of retries on transient failures
-        """
-        self.endpoint = endpoint or self._detect_endpoint()
-        self.batch_size = batch_size
-        self.retry_count = retry_count
-        self.call_buffer: list[LLMCallRecord] = []
-        self.workflow_buffer: list[WorkflowRunRecord] = []
-        self._available = self._check_availability()
-
-        # Try importing OTEL dependencies
-        self._otel_available = self._check_otel_installed()
-
-        if self._otel_available and self._available:
-            self._init_otel()
-
-    def _detect_endpoint(self) -> str:
-        """Detect OTEL collector endpoint.
-
-        Checks (in order):
-        1. EMPATHY_OTEL_ENDPOINT environment variable
-        2. localhost:4317 (default OTEL gRPC port)
-
-        Returns:
-            OTEL collector endpoint URL
-        """
-        # Check environment variable
-        endpoint = os.getenv("EMPATHY_OTEL_ENDPOINT")
-        if endpoint:
-            return endpoint
-
-        # Check localhost:4317
-        if self._is_port_open("localhost", 4317):
-            return "http://localhost:4317"
-
-        # Default (will fail availability check)
-        return "http://localhost:4317"
-
-    def _is_port_open(self, host: str, port: int, timeout: float = 1.0) -> bool:
-        """Check if a port is open on a host.
-
-        Args:
-            host: Hostname or IP address
-            port: Port number
-            timeout: Connection timeout in seconds
-
-        Returns:
-            True if port is open, False otherwise
-        """
-        try:
-            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-            sock.settimeout(timeout)
-            sock.connect((host, port))
-            sock.close()
-            return True
-        except (TimeoutError, OSError):
-            return False
-
-    def _check_availability(self) -> bool:
-        """Check if OTEL collector is available.
-
-        Returns:
-            True if collector is reachable, False otherwise
-        """
-        if not self.endpoint:
-            return False
-
-        # Parse endpoint to extract host and port
-        try:
-            # Remove http:// or https://
-            endpoint = self.endpoint.replace("http://", "").replace("https://", "")
-            if ":" in endpoint:
-                host, port_str = endpoint.split(":")
-                port = int(port_str.split("/")[0])  # Remove any path
-            else:
-                host = endpoint
-                port = 4317  # Default OTEL gRPC port
-
-            return self._is_port_open(host, port)
-        except (ValueError, IndexError):
-            return False
-
-    def _check_otel_installed(self) -> bool:
-        """Check if OTEL dependencies are installed.
-
-        Returns:
-            True if opentelemetry-api and opentelemetry-sdk are installed
-        """
-        import importlib.util
-
-        required_packages = [
-            "opentelemetry.trace",
-            "opentelemetry.exporter.otlp.proto.grpc.trace_exporter",
-            "opentelemetry.sdk.trace",
-            "opentelemetry.sdk.trace.export",
-        ]
-
-        return all(importlib.util.find_spec(pkg) is not None for pkg in required_packages)
-
-    def _init_otel(self) -> None:
-        """Initialize OTEL tracer and exporter."""
-        try:
-            from opentelemetry import trace
-            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
-            from opentelemetry.sdk.resources import Resource
-            from opentelemetry.sdk.trace import TracerProvider
-            from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-            # Create resource with service name
-            resource = Resource.create(
-                {
-                    "service.name": "empathy-framework",
-                    "service.version": "3.8.0-alpha",
-                }
-            )
-
-            # Create tracer provider
-            provider = TracerProvider(resource=resource)
-
-            # Create OTLP exporter
-            exporter = OTLPSpanExporter(endpoint=self.endpoint, insecure=True)
-
-            # Add batch processor
-            processor = BatchSpanProcessor(exporter)
-            provider.add_span_processor(processor)
-
-            # Set global tracer provider
-            trace.set_tracer_provider(provider)
-
-            # Get tracer
-            self.tracer = trace.get_tracer("empathy.llm.telemetry", "3.8.0-alpha")
-
-        except Exception as e:
-            print(f"⚠️  Failed to initialize OTEL: {e}")
-            self._available = False
-
-    def is_available(self) -> bool:
-        """Check if OTEL backend is available.
-
-        Returns:
-            True if OTEL collector is reachable and dependencies installed
-        """
-        return self._available and self._otel_available
-
-    def log_call(self, record: LLMCallRecord) -> None:
-        """Log an LLM call record to OTEL.
-
-        Creates an OTEL span with LLM semantic conventions.
-
-        Args:
-            record: LLM call record to log
-        """
-        if not self.is_available():
-            return
-
-        try:
-            # Create span with LLM semantic conventions
-            with self.tracer.start_as_current_span(
-                f"llm.{record.provider}.{record.model_id}"
-            ) as span:
-                # Set standard LLM attributes
-                span.set_attribute("llm.provider", record.provider)
-                span.set_attribute("llm.model", record.model_id)
-                span.set_attribute("llm.tier", record.tier)
-                span.set_attribute("llm.task_type", record.task_type)
-
-                # Set token usage
-                span.set_attribute("llm.usage.input_tokens", record.input_tokens)
-                span.set_attribute("llm.usage.output_tokens", record.output_tokens)
-                span.set_attribute(
-                    "llm.usage.total_tokens", record.input_tokens + record.output_tokens
-                )
-
-                # Set cost and latency
-                span.set_attribute("llm.cost.estimated", record.estimated_cost)
-                if record.actual_cost:
-                    span.set_attribute("llm.cost.actual", record.actual_cost)
-                span.set_attribute("llm.latency_ms", record.latency_ms)
-
-                # Set workflow context
-                if record.workflow_name:
-                    span.set_attribute("workflow.name", record.workflow_name)
-                if record.step_name:
-                    span.set_attribute("workflow.step", record.step_name)
-                if record.session_id:
-                    span.set_attribute("session.id", record.session_id)
-
-                # Set fallback info
-                if record.fallback_used:
-                    span.set_attribute("llm.fallback.used", True)
-                    if record.original_provider:
-                        span.set_attribute(
-                            "llm.fallback.original_provider", record.original_provider
-                        )
-                    if record.original_model:
-                        span.set_attribute("llm.fallback.original_model", record.original_model)
-
-                # Set error info
-                if not record.success:
-                    span.set_attribute("llm.error", True)
-                    if record.error_type:
-                        span.set_attribute("llm.error.type", record.error_type)
-                    if record.error_message:
-                        span.set_attribute("llm.error.message", record.error_message)
-
-        except Exception as e:
-            print(f"⚠️  Failed to export LLM call to OTEL: {e}")
-
-    def log_workflow(self, record: WorkflowRunRecord) -> None:
-        """Log a workflow run record to OTEL.
-
-        Creates an OTEL trace with workflow semantic conventions.
-
-        Args:
-            record: Workflow run record to log
-        """
-        if not self.is_available():
-            return
-
-        try:
-            # Create trace for workflow
-            with self.tracer.start_as_current_span(f"workflow.{record.workflow_name}") as span:
-                # Set workflow attributes
-                span.set_attribute("workflow.name", record.workflow_name)
-                span.set_attribute("workflow.run_id", record.run_id)
-                if record.session_id:
-                    span.set_attribute("session.id", record.session_id)
-
-                # Set token usage
-                span.set_attribute("workflow.usage.input_tokens", record.total_input_tokens)
-                span.set_attribute("workflow.usage.output_tokens", record.total_output_tokens)
-                span.set_attribute(
-                    "workflow.usage.total_tokens",
-                    record.total_input_tokens + record.total_output_tokens,
-                )
-
-                # Set cost and savings
-                span.set_attribute("workflow.cost.total", record.total_cost)
-                span.set_attribute("workflow.cost.baseline", record.baseline_cost)
-                span.set_attribute("workflow.cost.savings", record.savings)
-                span.set_attribute("workflow.cost.savings_percent", record.savings_percent)
-
-                # Set duration
-                span.set_attribute("workflow.duration_ms", record.total_duration_ms)
-
-                # Set providers and tiers used
-                span.set_attribute("workflow.providers_used", ",".join(record.providers_used))
-                span.set_attribute("workflow.tiers_used", ",".join(record.tiers_used))
-
-                # Set success status
-                span.set_attribute("workflow.success", record.success)
-                if not record.success and record.error:
-                    span.set_attribute("workflow.error", record.error)
-
-                # Create child spans for each stage
-                for stage in record.stages:
-                    with self.tracer.start_as_current_span(
-                        f"stage.{stage.stage_name}"
-                    ) as stage_span:
-                        stage_span.set_attribute("stage.name", stage.stage_name)
-                        stage_span.set_attribute("llm.tier", stage.tier)
-                        stage_span.set_attribute("llm.model", stage.model_id)
-                        stage_span.set_attribute("llm.usage.input_tokens", stage.input_tokens)
-                        stage_span.set_attribute("llm.usage.output_tokens", stage.output_tokens)
-                        stage_span.set_attribute("llm.cost", stage.cost)
-                        stage_span.set_attribute("llm.latency_ms", stage.latency_ms)
-                        stage_span.set_attribute("stage.success", stage.success)
-
-                        if stage.skipped:
-                            stage_span.set_attribute("stage.skipped", True)
-                            if stage.skip_reason:
-                                stage_span.set_attribute("stage.skip_reason", stage.skip_reason)
-
-                        if stage.error:
-                            stage_span.set_attribute("stage.error", stage.error)
-
-        except Exception as e:
-            print(f"⚠️  Failed to export workflow to OTEL: {e}")
-
-    def flush(self) -> None:
-        """Flush any buffered records to OTEL collector.
-
-        Called automatically on shutdown or can be called manually.
-        """
-        if not self.is_available():
-            return
-
-        try:
-            from opentelemetry import trace
-
-            # Get tracer provider and force flush
-            provider = trace.get_tracer_provider()
-            if hasattr(provider, "force_flush"):
-                provider.force_flush()
-        except Exception as e:
-            print(f"⚠️  Failed to flush OTEL data: {e}")
-
-    def __del__(self) -> None:
-        """Cleanup on deletion."""
-        self.flush()

empathy_os/optimization/__init__.py

@@ -1,19 +0,0 @@
-"""Context window optimization for XML-enhanced prompts.
-
-Provides compression and optimization to reduce token usage by 20-30%.
-
-Copyright 2026 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-from empathy_os.optimization.context_optimizer import (
-    CompressionLevel,
-    ContextOptimizer,
-    optimize_xml_prompt,
-)
-
-__all__ = [
-    "CompressionLevel",
-    "ContextOptimizer",
-    "optimize_xml_prompt",
-]