fluxloop 0.1.0__py3-none-any.whl

fluxloop/__init__.py

@@ -0,0 +1,58 @@
+"""
+FluxLoop SDK - Agent instrumentation and tracing library.
+"""
+
+from .context import FluxLoopContext, get_current_context, instrument
+from .decorators import agent, prompt, tool
+from .schemas import (
+    ExperimentConfig,
+    PersonaConfig,
+    RunnerConfig,
+    VariationStrategy,
+    Trace,
+    Observation,
+    ObservationType,
+    ObservationLevel,
+    Score,
+    ScoreDataType,
+    TraceStatus,
+)
+from .client import FluxLoopClient
+from .config import configure, get_config, reset_config
+from .recording import disable_recording, enable_recording, record_call_args, set_recording_options
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Decorators
+    "agent",
+    "prompt",
+    "tool",
+    # Context
+    "instrument",
+    "get_current_context",
+    "FluxLoopContext",
+    # Client
+    "FluxLoopClient",
+    # Config
+    "configure",
+    "get_config",
+    "reset_config",
+    "enable_recording",
+    "disable_recording",
+    "set_recording_options",
+    "record_call_args",
+    # Schemas - configs
+    "ExperimentConfig",
+    "PersonaConfig",
+    "RunnerConfig",
+    "VariationStrategy",
+    # Schemas - tracing
+    "Trace",
+    "Observation",
+    "ObservationType",
+    "ObservationLevel",
+    "Score",
+    "ScoreDataType",
+    "TraceStatus",
+]

fluxloop/buffer.py

@@ -0,0 +1,186 @@
+"""
+Event buffering and batch sending logic.
+"""
+
+import atexit
+import json
+import threading
+import time
+from collections import deque
+from datetime import datetime
+from typing import Any, Deque, Dict, List, Optional, Tuple
+from uuid import UUID
+
+from .config import get_config
+from .models import ObservationData, TraceData
+from .storage import OfflineStore
+
+
+class EventBuffer:
+    """
+    Singleton buffer for collecting and batching events.
+    """
+    
+    _instance: Optional["EventBuffer"] = None
+    _lock = threading.Lock()
+    
+    def __init__(self):
+        """Initialize the buffer."""
+        if EventBuffer._instance is not None:
+            raise RuntimeError("Use EventBuffer.get_instance() instead")
+        
+        self.config = get_config()
+        self.traces: Deque[TraceData] = deque(maxlen=self.config.max_queue_size)
+        self.observations: Deque[Tuple[UUID, ObservationData]] = deque(
+            maxlen=self.config.max_queue_size
+        )
+        
+        # Threading
+        self.send_lock = threading.Lock()
+        self.last_flush = time.time()
+        
+        # Background thread for periodic flushing
+        self.stop_event = threading.Event()
+        self.flush_thread = threading.Thread(target=self._flush_periodically, daemon=True)
+        self.flush_thread.start()
+        
+        # Register cleanup on exit
+        atexit.register(self.shutdown)
+
+        # Offline store
+        self.offline_store = OfflineStore()
+    
+    @classmethod
+    def get_instance(cls) -> "EventBuffer":
+        """Get or create the singleton instance."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+    
+    def add_trace(self, trace: TraceData) -> None:
+        """
+        Add a trace to the buffer.
+        
+        Args:
+            trace: Trace data to add
+        """
+        if not self.config.enabled:
+            return
+        
+        with self.send_lock:
+            self.traces.append(trace)
+    
+    def add_observation(self, trace_id: UUID, observation: ObservationData) -> None:
+        """
+        Add an observation to the buffer.
+        
+        Args:
+            trace_id: ID of the parent trace
+            observation: Observation data to add
+        """
+        if not self.config.enabled:
+            return
+        
+        with self.send_lock:
+            self.observations.append((trace_id, observation))
+    
+    def flush_if_needed(self) -> None:
+        """Flush the buffer if batch size is reached."""
+        should_flush = False
+        
+        with self.send_lock:
+            total_items = len(self.traces) + len(self.observations)
+            should_flush = total_items >= self.config.batch_size
+        
+        if should_flush:
+            self.flush()
+    
+    def flush(self) -> None:
+        """Send all buffered events to the collector."""
+        if not self.config.enabled:
+            return
+        
+        # Collect items to send
+        traces_to_send: List[TraceData] = []
+        observations_to_send: List[Tuple[UUID, ObservationData]] = []
+        
+        with self.send_lock:
+            # Move items from buffer
+            while self.traces:
+                traces_to_send.append(self.traces.popleft())
+            
+            while self.observations:
+                observations_to_send.append(self.observations.popleft())
+            
+            self.last_flush = time.time()
+        
+        # Send if there's data
+        if traces_to_send or observations_to_send:
+            self._send_batch(traces_to_send, observations_to_send)
+    
+    def _send_batch(
+        self,
+        traces: List[TraceData],
+        observations: List[Tuple[UUID, ObservationData]]
+    ) -> None:
+        """
+        Send a batch of events to the collector.
+        
+        Args:
+            traces: List of traces to send
+            observations: List of (trace_id, observation) tuples
+        """
+        # Import here to avoid circular dependency
+        send_errors = False
+
+        if self.config.use_collector:
+            from .client import FluxLoopClient
+
+            client = FluxLoopClient()
+
+            for trace in traces:
+                try:
+                    client.send_trace(trace)
+                except Exception as e:
+                    send_errors = True
+                    if self.config.debug:
+                        print(f"Failed to send trace {trace.id}: {e}")
+
+            for trace_id, observation in observations:
+                try:
+                    client.send_observation(trace_id, observation)
+                except Exception as e:
+                    send_errors = True
+                    if self.config.debug:
+                        print(f"Failed to send observation {observation.id}: {e}")
+
+        if send_errors or not self.config.use_collector:
+            self.offline_store.record_traces(traces)
+            self.offline_store.record_observations(observations)
+    
+    def _flush_periodically(self) -> None:
+        """Background thread to flush periodically."""
+        while not self.stop_event.is_set():
+            time.sleep(self.config.flush_interval)
+            
+            # Check if enough time has passed since last flush
+            with self.send_lock:
+                time_since_flush = time.time() - self.last_flush
+                has_data = bool(self.traces or self.observations)
+            
+            if has_data and time_since_flush >= self.config.flush_interval:
+                self.flush()
+    
+    def shutdown(self) -> None:
+        """Shutdown the buffer and flush remaining events."""
+        # Stop the background thread
+        self.stop_event.set()
+        
+        # Final flush
+        self.flush()
+        
+        # Wait for thread to stop (with timeout)
+        if self.flush_thread.is_alive():
+            self.flush_thread.join(timeout=2.0)

fluxloop/client.py

@@ -0,0 +1,175 @@
+"""
+HTTP client for sending data to the collector.
+"""
+
+import json
+from typing import Any, Dict, Optional
+from uuid import UUID
+
+import httpx
+
+from .config import get_config
+from .models import ObservationData, TraceData
+
+
+class FluxLoopClient:
+    """
+    HTTP client for communicating with the FluxLoop collector.
+    """
+    
+    def __init__(self, collector_url: Optional[str] = None, api_key: Optional[str] = None):
+        """
+        Initialize the client.
+        
+        Args:
+            collector_url: Override collector URL
+            api_key: Override API key
+        """
+        self.config = get_config()
+        self.collector_url = collector_url or self.config.collector_url
+        self.api_key = api_key or self.config.api_key
+        self._client: Optional[httpx.Client] = None
+        if self.config.use_collector:
+            self._client = httpx.Client(
+                base_url=self.collector_url,
+                timeout=self.config.timeout,
+                headers=self._get_headers(),
+            )
+    
+    def _get_headers(self) -> Dict[str, str]:
+        """Get common headers for requests."""
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "fluxloop-sdk/0.1.0",
+        }
+        
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        
+        if self.config.service_name:
+            headers["X-Service-Name"] = self.config.service_name
+        
+        if self.config.environment:
+            headers["X-Environment"] = self.config.environment
+        
+        return headers
+    
+    def send_trace(self, trace: TraceData) -> Dict[str, Any]:
+        """
+        Send a trace to the collector.
+        
+        Args:
+            trace: Trace data to send
+            
+        Returns:
+            Response from the collector
+            
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        if not self.config.enabled:
+            return {"status": "disabled"}
+        
+        # Convert to JSON-serializable format
+        payload = self._serialize_trace(trace)
+        
+        if not self._client:
+            return {"status": "collector_disabled"}
+        
+        try:
+            response = self._client.post("/api/traces", json=payload)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            if self.config.debug:
+                print(f"Error sending trace: {e}")
+            raise
+    
+    def send_observation(
+        self, trace_id: UUID, observation: ObservationData
+    ) -> Dict[str, Any]:
+        """
+        Send an observation to the collector.
+        
+        Args:
+            trace_id: ID of the parent trace
+            observation: Observation data to send
+            
+        Returns:
+            Response from the collector
+            
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        if not self.config.enabled:
+            return {"status": "disabled"}
+        
+        # Convert to JSON-serializable format
+        payload = self._serialize_observation(observation)
+        payload["trace_id"] = str(trace_id)
+        
+        if not self._client:
+            return {"status": "collector_disabled"}
+        
+        try:
+            response = self._client.post(
+                f"/api/traces/{trace_id}/observations",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            if self.config.debug:
+                print(f"Error sending observation: {e}")
+            raise
+    
+    def _serialize_trace(self, trace: TraceData) -> Dict[str, Any]:
+        """Serialize trace for JSON transmission."""
+        data = trace.model_dump(exclude_none=True)
+        
+        # Convert UUIDs to strings
+        if "id" in data:
+            data["id"] = str(data["id"])
+        if "session_id" in data:
+            data["session_id"] = str(data["session_id"])
+        
+        # Convert datetime to ISO format
+        if "start_time" in data:
+            data["start_time"] = data["start_time"].isoformat()
+        if "end_time" in data and data["end_time"]:
+            data["end_time"] = data["end_time"].isoformat()
+        
+        return data
+    
+    def _serialize_observation(self, observation: ObservationData) -> Dict[str, Any]:
+        """Serialize observation for JSON transmission."""
+        data = observation.model_dump(exclude_none=True)
+        
+        # Convert UUIDs to strings
+        if "id" in data:
+            data["id"] = str(data["id"])
+        if "parent_observation_id" in data:
+            data["parent_observation_id"] = str(data["parent_observation_id"])
+        if "trace_id" in data:
+            data["trace_id"] = str(data["trace_id"])
+        
+        # Convert datetime to ISO format
+        if "start_time" in data:
+            data["start_time"] = data["start_time"].isoformat()
+        if "end_time" in data and data["end_time"]:
+            data["end_time"] = data["end_time"].isoformat()
+        
+        return data
+    
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client:
+            self._client.close()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

fluxloop/config.py

@@ -0,0 +1,191 @@
+"""
+SDK Configuration management.
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field, field_validator
+
+from .recording import disable_recording, enable_recording
+
+
+def _resolve_recording_path(path: Optional[str]) -> Path:
+    """Resolve the recording file path, creating parent directories."""
+
+    if path:
+        resolved = Path(path).expanduser().resolve()
+    else:
+        resolved = Path(
+            f"/tmp/fluxloop_args_{datetime.now().strftime('%Y%m%d_%H%M%S')}.jsonl"
+        ).resolve()
+
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    return resolved
+
+
+def _apply_recording_config(config: "SDKConfig") -> None:
+    """Enable or disable argument recording based on configuration."""
+
+    if config.record_args:
+        resolved_path = _resolve_recording_path(config.recording_file)
+        enable_recording(str(resolved_path))
+        config.recording_file = str(resolved_path)
+        if config.debug:
+            print(f"🎥 Argument recording enabled → {resolved_path}")
+    else:
+        disable_recording()
+        if config.debug:
+            print("🎥 Argument recording disabled")
+
+# Load environment variables
+load_dotenv()
+
+
+class SDKConfig(BaseModel):
+    """SDK configuration settings."""
+    
+    # Collector settings
+    collector_url: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_COLLECTOR_URL", "http://localhost:8000")
+    )
+    api_key: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_API_KEY")
+    )
+    
+    # Behavior settings
+    enabled: bool = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_ENABLED", "true").lower() == "true"
+    )
+    debug: bool = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_DEBUG", "false").lower() == "true"
+    )
+    use_collector: bool = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_USE_COLLECTOR", "true").lower() == "true"
+    )
+    offline_store_enabled: bool = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_OFFLINE_ENABLED", "true").lower() == "true"
+    )
+    offline_store_dir: str = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_OFFLINE_DIR", "./fluxloop_artifacts")
+    )
+
+    # Argument recording (disabled by default)
+    record_args: bool = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_RECORD_ARGS", "false").lower() == "true"
+    )
+    recording_file: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_RECORDING_FILE")
+    )
+    
+    # Performance settings
+    batch_size: int = Field(
+        default_factory=lambda: int(os.getenv("FLUXLOOP_BATCH_SIZE", "10"))
+    )
+    flush_interval: float = Field(
+        default_factory=lambda: float(os.getenv("FLUXLOOP_FLUSH_INTERVAL", "5.0"))
+    )
+    max_queue_size: int = Field(
+        default_factory=lambda: int(os.getenv("FLUXLOOP_MAX_QUEUE_SIZE", "1000"))
+    )
+    timeout: float = Field(
+        default_factory=lambda: float(os.getenv("FLUXLOOP_TIMEOUT", "10.0"))
+    )
+    
+    # Sampling
+    sample_rate: float = Field(
+        default_factory=lambda: float(os.getenv("FLUXLOOP_SAMPLE_RATE", "1.0"))
+    )
+    
+    # Metadata
+    service_name: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_SERVICE_NAME")
+    )
+    environment: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FLUXLOOP_ENVIRONMENT", "development")
+    )
+    
+    @field_validator("collector_url")
+    def validate_collector_url(cls, v):
+        """Ensure collector URL is valid."""
+        if v is None:
+            return None
+        try:
+            result = urlparse(v)
+            if not all([result.scheme, result.netloc]):
+                raise ValueError("Invalid URL format")
+        except Exception as e:
+            raise ValueError(f"Invalid collector URL: {e}")
+        return v.rstrip("/")  # Remove trailing slash
+    
+    @field_validator("sample_rate")
+    def validate_sample_rate(cls, v):
+        """Ensure sample rate is between 0 and 1."""
+        if not 0 <= v <= 1:
+            raise ValueError("sample_rate must be between 0 and 1")
+        return v
+    
+    @field_validator("batch_size")
+    def validate_batch_size(cls, v):
+        """Ensure batch size is reasonable."""
+        if v < 1:
+            raise ValueError("batch_size must be at least 1")
+        if v > 100:
+            raise ValueError("batch_size must not exceed 100")
+        return v
+
+
+# Global configuration instance
+_config = SDKConfig()
+_apply_recording_config(_config)
+
+
+def configure(**kwargs) -> SDKConfig:
+    """
+    Configure the SDK.
+    
+    Args:
+        **kwargs: Configuration parameters to override
+        
+    Returns:
+        Updated configuration
+        
+    Example:
+        >>> import fluxloop
+        >>> fluxloop.configure(
+        ...     collector_url="https://api.fluxloop.dev",
+        ...     api_key="your-api-key"
+        ... )
+    """
+    global _config
+    
+    # Update configuration with provided values
+    for key, value in kwargs.items():
+        if hasattr(_config, key):
+            setattr(_config, key, value)
+        else:
+            raise ValueError(f"Unknown configuration parameter: {key}")
+    
+    # Re-validate the configuration
+    _config = SDKConfig(**_config.model_dump())
+
+    _apply_recording_config(_config)
+
+    return _config
+
+
+def get_config() -> SDKConfig:
+    """Get current SDK configuration."""
+    return _config
+
+
+def reset_config() -> SDKConfig:
+    """Reset configuration to defaults."""
+    global _config
+    _config = SDKConfig()
+    _apply_recording_config(_config)
+    return _config