flatagents 0.4.1__py3-none-any.whl

flatagents/monitoring.py

@@ -0,0 +1,373 @@
+"""
+Monitoring and observability utilities for FlatAgents.
+
+Provides standardized logging configuration and OpenTelemetry-based metrics.
+"""
+
+import logging
+import os
+import sys
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Optional
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Logging Configuration
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Global logger registry
+_loggers: Dict[str, logging.Logger] = {}
+_logging_configured = False
+
+
+def setup_logging(
+    level: Optional[str] = None,
+    format: Optional[str] = None,
+    force: bool = False
+) -> None:
+    """
+    Configure SDK-wide logging with sensible defaults.
+    
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+               Defaults to FLATAGENTS_LOG_LEVEL env var or INFO.
+        format: Log format style. Options:
+                - 'standard': Human-readable with timestamps
+                - 'json': Structured JSON logging
+                - 'simple': Just level and message
+                - Custom format string
+                Defaults to FLATAGENTS_LOG_FORMAT env var or 'standard'.
+        force: If True, reconfigure even if already configured.
+    
+    Example:
+        >>> from flatagents import setup_logging
+        >>> setup_logging(level='DEBUG')
+        >>> # Or via environment:
+        >>> # export FLATAGENTS_LOG_LEVEL=DEBUG
+        >>> # export FLATAGENTS_LOG_FORMAT=json
+    """
+    global _logging_configured
+    
+    if _logging_configured and not force:
+        return
+    
+    # Determine log level
+    if level is None:
+        level = os.getenv('FLATAGENTS_LOG_LEVEL', 'INFO').upper()
+    
+    log_level = getattr(logging, level.upper(), logging.INFO)
+    
+    # Determine format
+    if format is None:
+        format = os.getenv('FLATAGENTS_LOG_FORMAT', 'standard')
+    
+    if format == 'json':
+        # Structured JSON logging - note: message content should be escaped by caller for true JSON safety
+        log_format = '{"time":"%(asctime)s","name":"%(name)s","level":"%(levelname)s","message":%(message)s}'
+    elif format == 'simple':
+        log_format = '%(levelname)s - %(message)s'
+    elif format == 'standard':
+        log_format = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    else:
+        # Custom format string
+        log_format = format
+    
+    # Configure root logger for the SDK
+    logging.basicConfig(
+        level=log_level,
+        format=log_format,
+        datefmt='%Y-%m-%d %H:%M:%S',
+        stream=sys.stdout,
+        force=force
+    )
+    
+    _logging_configured = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a properly configured logger for a module.
+    
+    Args:
+        name: Logger name (typically __name__ from the calling module)
+    
+    Returns:
+        Configured logger instance
+    
+    Example:
+        >>> from flatagents import get_logger
+        >>> logger = get_logger(__name__)
+        >>> logger.info("Agent started")
+    """
+    if name not in _loggers:
+        # Ensure logging is configured
+        if not _logging_configured:
+            setup_logging()
+        
+        logger = logging.getLogger(name)
+        _loggers[name] = logger
+    
+    return _loggers[name]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Metrics with OpenTelemetry
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Lazy imports for OpenTelemetry (optional dependency)
+_otel_available = False
+_meter = None
+_metrics_enabled = False
+_cached_histograms: Dict[str, Any] = {}  # Cache for histogram instruments
+
+try:
+    from opentelemetry import metrics
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+    from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+    from opentelemetry.sdk.resources import Resource, SERVICE_NAME
+    _otel_available = True
+except ImportError:
+    _otel_available = False
+
+
+def _init_metrics() -> None:
+    """Initialize OpenTelemetry metrics if enabled and available."""
+    global _meter, _metrics_enabled
+    
+    # Check if metrics should be enabled
+    enabled = os.getenv('FLATAGENTS_METRICS_ENABLED', 'false').lower() in ('true', '1', 'yes')
+    
+    if not enabled:
+        _metrics_enabled = False
+        return
+    
+    if not _otel_available:
+        logger = get_logger(__name__)
+        logger.warning(
+            "Metrics enabled but OpenTelemetry not available. "
+            "Install with: pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp"
+        )
+        _metrics_enabled = False
+        return
+    
+    try:
+        # Get service name from environment or use default
+        service_name = os.getenv('OTEL_SERVICE_NAME', 'flatagents')
+        
+        # Create resource with service name
+        resource = Resource(attributes={
+            SERVICE_NAME: service_name
+        })
+        
+        # Check which exporter to use
+        exporter_type = os.getenv('OTEL_METRICS_EXPORTER', 'otlp').lower()
+        
+        if exporter_type == 'console':
+            # Use console exporter for testing/debugging
+            try:
+                from opentelemetry.sdk.metrics.export import ConsoleMetricExporter
+                exporter = ConsoleMetricExporter()
+            except ImportError:
+                logger = get_logger(__name__)
+                logger.warning("Console exporter not available, falling back to OTLP")
+                exporter = OTLPMetricExporter(
+                    endpoint=os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT'),
+                )
+        else:
+            # Configure OTLP exporter (supports Datadog, Honeycomb, etc.)
+            exporter = OTLPMetricExporter(
+                endpoint=os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT'),
+                # Headers can be set via OTEL_EXPORTER_OTLP_HEADERS env var
+            )
+        
+        # Create meter provider with periodic export
+        reader = PeriodicExportingMetricReader(
+            exporter=exporter,
+            export_interval_millis=int(os.getenv('OTEL_METRIC_EXPORT_INTERVAL', '5000' if exporter_type == 'console' else '60000'))
+        )
+        
+        provider = MeterProvider(
+            resource=resource,
+            metric_readers=[reader]
+        )
+        
+        metrics.set_meter_provider(provider)
+        _meter = metrics.get_meter(__name__)
+        _metrics_enabled = True
+        
+        logger = get_logger(__name__)
+        logger.info(f"OpenTelemetry metrics enabled for service: {service_name}")
+        
+    except Exception as e:
+        logger = get_logger(__name__)
+        logger.warning(f"Failed to initialize OpenTelemetry metrics: {e}")
+        _metrics_enabled = False
+
+
+def get_meter():
+    """
+    Get the OpenTelemetry meter for creating custom metrics.
+    
+    Returns:
+        OpenTelemetry Meter instance or None if metrics disabled
+    
+    Example:
+        >>> from flatagents import get_meter
+        >>> meter = get_meter()
+        >>> if meter:
+        ...     counter = meter.create_counter("my_custom_metric")
+        ...     counter.add(1, {"attribute": "value"})
+    """
+    global _meter
+    
+    if _meter is None and not _metrics_enabled:
+        _init_metrics()
+    
+    return _meter
+
+
+class AgentMonitor:
+    """
+    Context manager for tracking agent execution metrics.
+    
+    Automatically tracks:
+    - Execution duration
+    - Success/failure status
+    - Custom metrics via the metrics dict
+    
+    Example:
+        >>> from flatagents import AgentMonitor
+        >>> with AgentMonitor("my-agent") as monitor:
+        ...     # Do agent work
+        ...     monitor.metrics["tokens"] = 1500
+        ...     monitor.metrics["cost"] = 0.03
+        >>> # Metrics automatically emitted on exit
+    """
+    
+    def __init__(self, agent_id: str, extra_attributes: Optional[Dict[str, Any]] = None):
+        """
+        Initialize the monitor.
+        
+        Args:
+            agent_id: Identifier for this agent/operation
+            extra_attributes: Additional attributes to attach to all metrics
+        """
+        self.agent_id = agent_id
+        self.start_time = None
+        self.metrics: Dict[str, Any] = {}
+        self.extra_attributes = extra_attributes or {}
+        self.logger = get_logger(f"flatagents.monitor.{agent_id}")
+        
+        # Get or create metric instruments
+        self._meter = get_meter()
+        if self._meter:
+            self._duration_histogram = self._meter.create_histogram(
+                "flatagents.agent.duration",
+                unit="ms",
+                description="Agent execution duration"
+            )
+            self._token_counter = self._meter.create_counter(
+                "flatagents.agent.tokens",
+                description="Tokens used by agent"
+            )
+            self._cost_counter = self._meter.create_counter(
+                "flatagents.agent.cost",
+                description="Estimated cost of agent execution"
+            )
+            self._status_counter = self._meter.create_counter(
+                "flatagents.agent.executions",
+                description="Agent execution count by status"
+            )
+    
+    def __enter__(self):
+        """Start monitoring."""
+        self.start_time = time.time()
+        self.logger.debug(f"Agent {self.agent_id} started")
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Stop monitoring and emit metrics."""
+        duration_ms = (time.time() - self.start_time) * 1000
+        status = "success" if exc_type is None else "error"
+        
+        # Build attributes
+        attributes = {
+            "agent_id": self.agent_id,
+            "status": status,
+            **self.extra_attributes
+        }
+        
+        if exc_type is not None:
+            attributes["error_type"] = exc_type.__name__
+        
+        # Log completion
+        self.logger.info(
+            f"Agent {self.agent_id} completed in {duration_ms:.2f}ms - {status}"
+        )
+        
+        # Emit metrics if enabled
+        if self._meter:
+            self._duration_histogram.record(duration_ms, attributes)
+            self._status_counter.add(1, attributes)
+            
+            if "tokens" in self.metrics:
+                self._token_counter.add(self.metrics["tokens"], attributes)
+            
+            if "cost" in self.metrics:
+                self._cost_counter.add(self.metrics["cost"], attributes)
+        
+        # Don't suppress exceptions
+        return False
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Convenience context manager for temporary metrics
+# ─────────────────────────────────────────────────────────────────────────────
+
+@contextmanager
+def track_operation(operation_name: str, **attributes):
+    """
+    Track duration of an operation.
+    
+    Args:
+        operation_name: Name of the operation
+        **attributes: Additional attributes to attach
+    
+    Example:
+        >>> from flatagents.monitoring import track_operation
+        >>> with track_operation("llm_call", model="gpt-4"):
+        ...     response = await llm.call(messages)
+    """
+    meter = get_meter()
+    start_time = time.time()
+    
+    try:
+        yield
+        status = "success"
+    except Exception as e:
+        status = "error"
+        attributes["error_type"] = type(e).__name__
+        raise
+    finally:
+        duration_ms = (time.time() - start_time) * 1000
+        
+        if meter:
+            # Cache histogram to avoid recreating on each call
+            cache_key = f"flatagents.{operation_name}.duration"
+            if cache_key not in _cached_histograms:
+                _cached_histograms[cache_key] = meter.create_histogram(
+                    cache_key,
+                    unit="ms",
+                    description=f"Duration of {operation_name}"
+                )
+            _cached_histograms[cache_key].record(duration_ms, {**attributes, "status": status})
+
+
+__all__ = [
+    "setup_logging",
+    "get_logger",
+    "get_meter",
+    "AgentMonitor",
+    "track_operation",
+]

flatagents/persistence.py

@@ -0,0 +1,200 @@
+import json
+import fcntl
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, List
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from datetime import datetime, timezone
+import aiofiles
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class MachineSnapshot:
+    """Wire format for machine checkpoints."""
+    execution_id: str
+    machine_name: str
+    spec_version: str
+    current_state: str
+    context: Dict[str, Any]
+    step: int
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    event: Optional[str] = None  # The event that triggered this checkpoint (machine_start, etc)
+    output: Optional[Dict[str, Any]] = None  # Output if captured at state_exit/machine_end
+    total_api_calls: Optional[int] = None  # Cumulative API calls
+    total_cost: Optional[float] = None  # Cumulative cost
+    # Lineage (v0.4.0)
+    parent_execution_id: Optional[str] = None  # ID of launcher machine if this was launched
+    # Outbox pattern (v0.4.0)
+    pending_launches: Optional[List[Dict[str, Any]]] = None  # LaunchIntent dicts awaiting completion
+
+class PersistenceBackend(ABC):
+    """Abstract storage backend for checkpoints."""
+    
+    @abstractmethod
+    async def save(self, key: str, value: bytes) -> None:
+        pass
+    
+    @abstractmethod
+    async def load(self, key: str) -> Optional[bytes]:
+        pass
+    
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        pass
+
+class LocalFileBackend(PersistenceBackend):
+    """File-based persistence backend."""
+    
+    def __init__(self, base_dir: str = ".checkpoints"):
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+    
+    async def save(self, key: str, value: bytes) -> None:
+        path = self.base_dir / key
+        path.parent.mkdir(parents=True, exist_ok=True)
+        async with aiofiles.open(path, 'wb') as f:
+            await f.write(value)
+    
+    async def load(self, key: str) -> Optional[bytes]:
+        path = self.base_dir / key
+        if not path.exists():
+            return None
+        async with aiofiles.open(path, 'rb') as f:
+            return await f.read()
+            
+    async def delete(self, key: str) -> None:
+        path = self.base_dir / key
+        if path.exists():
+            path.unlink()
+
+class MemoryBackend(PersistenceBackend):
+    """In-memory backend for ephemeral executions."""
+    
+    def __init__(self):
+        self._store: Dict[str, bytes] = {}
+        
+    async def save(self, key: str, value: bytes) -> None:
+        self._store[key] = value
+        
+    async def load(self, key: str) -> Optional[bytes]:
+        return self._store.get(key)
+        
+    async def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+class CheckpointManager:
+    """Manages saving and loading machine snapshots."""
+    
+    def __init__(self, backend: PersistenceBackend, execution_id: str):
+        self.backend = backend
+        self.execution_id = execution_id
+        
+    def _snapshot_key(self, event: str, step: int) -> str:
+        """Generate key for specific snapshot."""
+        return f"{self.execution_id}/step_{step:06d}_{event}.json"
+        
+    def _latest_pointer_key(self) -> str:
+        """Key that points to the latest snapshot."""
+        return f"{self.execution_id}/latest"
+
+    def _safe_serialize_value(self, value: Any, path: str, non_serializable: List[str]) -> Any:
+        """Recursively serialize a value, converting non-JSON types to strings."""
+        if isinstance(value, dict):
+            result = {}
+            for k, v in value.items():
+                try:
+                    json.dumps({k: v})
+                    result[k] = v
+                except (TypeError, OverflowError):
+                    result[k] = self._safe_serialize_value(v, f"{path}.{k}", non_serializable)
+            return result
+        elif isinstance(value, list):
+            result = []
+            for i, item in enumerate(value):
+                try:
+                    json.dumps(item)
+                    result.append(item)
+                except (TypeError, OverflowError):
+                    result.append(self._safe_serialize_value(item, f"{path}[{i}]", non_serializable))
+            return result
+        else:
+            try:
+                json.dumps(value)
+                return value
+            except (TypeError, OverflowError):
+                original_type = type(value).__name__
+                non_serializable.append(f"{path} ({original_type})")
+                return str(value)
+
+    def _safe_serialize(self, data: Dict[str, Any]) -> str:
+        """Safely serialize data to JSON, handling non-serializable objects."""
+        try:
+            return json.dumps(data)
+        except (TypeError, OverflowError):
+            # Identify and warn about specific non-serializable fields
+            safe_data = {}
+            non_serializable_fields: List[str] = []
+
+            for k, v in data.items():
+                if isinstance(v, dict):
+                    # Recursively check nested dicts
+                    try:
+                        json.dumps(v)
+                        safe_data[k] = v
+                    except (TypeError, OverflowError):
+                        safe_data[k] = self._safe_serialize_value(v, k, non_serializable_fields)
+                elif isinstance(v, list):
+                    # Recursively check lists
+                    try:
+                        json.dumps(v)
+                        safe_data[k] = v
+                    except (TypeError, OverflowError):
+                        safe_data[k] = self._safe_serialize_value(v, k, non_serializable_fields)
+                else:
+                    try:
+                        json.dumps({k: v})
+                        safe_data[k] = v
+                    except (TypeError, OverflowError):
+                        original_type = type(v).__name__
+                        safe_data[k] = str(v)
+                        non_serializable_fields.append(f"{k} ({original_type})")
+
+            if non_serializable_fields:
+                logger.warning(
+                    f"Context fields not JSON serializable, converted to strings: "
+                    f"{', '.join(non_serializable_fields)}. "
+                    f"These values will lose type information on restore."
+                )
+
+            return json.dumps(safe_data)
+
+    async def save_checkpoint(self, snapshot: MachineSnapshot) -> None:
+        """Save a snapshot and update latest pointer."""
+        data = asdict(snapshot)
+        json_bytes = self._safe_serialize(data).encode('utf-8')
+        
+        # Save the immutable snapshot
+        key = self._snapshot_key(snapshot.event or "unknown", snapshot.step)
+        await self.backend.save(key, json_bytes)
+        
+        # Update pointer to this key
+        await self.backend.save(self._latest_pointer_key(), key.encode('utf-8'))
+        
+    async def load_latest(self) -> Optional[MachineSnapshot]:
+        """Load the latest snapshot."""
+        # Get pointer
+        ptr_bytes = await self.backend.load(self._latest_pointer_key())
+        if not ptr_bytes:
+            return None
+            
+        # Get snapshot
+        key = ptr_bytes.decode('utf-8')
+        data_bytes = await self.backend.load(key)
+        if not data_bytes:
+            return None
+            
+        data = json.loads(data_bytes.decode('utf-8'))
+        return MachineSnapshot(**data)

flatagents/utils.py

@@ -0,0 +1,46 @@
+"""Utility functions for flatagents."""
+
+import re
+
+
+def strip_markdown_json(content: str) -> str:
+    """
+    Extract JSON from potentially wrapped response content.
+
+    LLMs sometimes wrap JSON responses in markdown code blocks like:
+    ```json
+    {"key": "value"}
+    ```
+
+    Or include explanatory text before/after the JSON:
+    "Here is the result:
+    ```json
+    {"key": "value"}
+    ```"
+
+    This function extracts the JSON so json.loads() can parse it.
+
+    Args:
+        content: Raw string that may contain markdown-wrapped JSON
+
+    Returns:
+        Extracted JSON string
+    """
+    if not content:
+        return content
+
+    text = content.strip()
+
+    # First, try to find JSON in a markdown code fence (anywhere in content)
+    fence_pattern = r'```(?:json|JSON)?\s*\n?([\s\S]*?)\n?```'
+    match = re.search(fence_pattern, text)
+    if match:
+        return match.group(1).strip()
+
+    # If no fence, try to find a raw JSON object or array
+    json_pattern = r'(\{[\s\S]*\}|\[[\s\S]*\])'
+    match = re.search(json_pattern, text)
+    if match:
+        return match.group(1)
+
+    return text