fluxloop 0.1.0__py3-none-any.whl

fluxloop/schemas/trace.py

@@ -0,0 +1,197 @@
+"""
+Trace and Observation models based on Langfuse data model.
+
+References:
+- https://langfuse.com/docs/observability/data-model
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class TraceStatus(str, Enum):
+    """Status of a trace execution."""
+    
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class ObservationType(str, Enum):
+    """Type of observation in the trace hierarchy."""
+    
+    SPAN = "span"  # Generic span
+    EVENT = "event"  # Single event
+    GENERATION = "generation"  # LLM generation
+    TOOL = "tool"  # Tool/function call
+    AGENT = "agent"  # Agent execution
+    CHAIN = "chain"  # Chain of operations
+    EVALUATION = "evaluation"  # Evaluation result
+
+
+class ObservationLevel(str, Enum):
+    """Log level for observations."""
+    
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class ScoreDataType(str, Enum):
+    """Data type of score values."""
+    
+    NUMERIC = "numeric"
+    BOOLEAN = "boolean"
+    CATEGORICAL = "categorical"
+
+
+class Score(BaseModel):
+    """Score/evaluation result for a trace or observation."""
+    
+    id: UUID = Field(default_factory=uuid4)
+    trace_id: UUID
+    observation_id: Optional[UUID] = None
+    name: str  # e.g., "accuracy", "relevance", "latency"
+    value: Union[float, bool, str]
+    data_type: ScoreDataType
+    comment: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    @field_validator("value")
+    def validate_value_type(cls, v, info):
+        """Ensure value matches the declared data type."""
+        data_type = info.data.get("data_type")
+        if data_type == ScoreDataType.NUMERIC and not isinstance(v, (int, float)):
+            raise ValueError("Numeric score must be int or float")
+        elif data_type == ScoreDataType.BOOLEAN and not isinstance(v, bool):
+            raise ValueError("Boolean score must be bool")
+        elif data_type == ScoreDataType.CATEGORICAL and not isinstance(v, str):
+            raise ValueError("Categorical score must be str")
+        return v
+
+
+class Observation(BaseModel):
+    """Single observation within a trace."""
+    
+    id: UUID = Field(default_factory=uuid4)
+    trace_id: UUID
+    parent_observation_id: Optional[UUID] = None
+    type: ObservationType
+    name: str
+    
+    # Timing
+    start_time: datetime = Field(default_factory=datetime.utcnow)
+    end_time: Optional[datetime] = None
+    
+    # Content
+    input: Optional[Any] = None
+    output: Optional[Any] = None
+    error: Optional[str] = None
+    
+    # Metadata
+    level: ObservationLevel = ObservationLevel.INFO
+    status_message: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    
+    # LLM specific (for GENERATION type)
+    model: Optional[str] = None
+    llm_parameters: Optional[Dict[str, Any]] = None
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    
+    # Scores attached to this observation
+    scores: List[Score] = Field(default_factory=list)
+    
+    def duration_ms(self) -> Optional[float]:
+        """Calculate duration in milliseconds."""
+        if self.start_time and self.end_time:
+            delta = self.end_time - self.start_time
+            return delta.total_seconds() * 1000
+        return None
+
+
+class Trace(BaseModel):
+    """Root trace representing a complete execution flow."""
+    
+    id: UUID = Field(default_factory=uuid4)
+    session_id: Optional[UUID] = None
+    name: str
+    
+    # Timing
+    start_time: datetime = Field(default_factory=datetime.utcnow)
+    end_time: Optional[datetime] = None
+    
+    # Status
+    status: TraceStatus = TraceStatus.PENDING
+    error: Optional[str] = None
+    
+    # Context
+    user_id: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    tags: List[str] = Field(default_factory=list)
+    
+    # Experiment specific
+    experiment_id: Optional[str] = None
+    iteration: Optional[int] = None
+    persona: Optional[str] = None
+    variation_seed: Optional[str] = None
+    
+    # Input/Output
+    input: Optional[Any] = None
+    output: Optional[Any] = None
+    
+    # Hierarchical data
+    observations: List[Observation] = Field(default_factory=list)
+    scores: List[Score] = Field(default_factory=list)
+    
+    # Metrics
+    total_cost: Optional[float] = None
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    
+    def duration_ms(self) -> Optional[float]:
+        """Calculate total duration in milliseconds."""
+        if self.start_time and self.end_time:
+            delta = self.end_time - self.start_time
+            return delta.total_seconds() * 1000
+        return None
+    
+    def get_observation_tree(self) -> Dict[UUID, List[Observation]]:
+        """Build parent-child relationship tree of observations."""
+        tree: Dict[UUID, List[Observation]] = {None: []}
+        
+        for obs in self.observations:
+            parent_id = obs.parent_observation_id
+            if parent_id not in tree:
+                tree[parent_id] = []
+            tree[parent_id].append(obs)
+        
+        return tree
+    
+    def calculate_metrics(self) -> Dict[str, Any]:
+        """Calculate aggregate metrics for the trace."""
+        metrics = {
+            "duration_ms": self.duration_ms(),
+            "observation_count": len(self.observations),
+            "score_count": len(self.scores),
+            "error_count": sum(1 for o in self.observations if o.error),
+            "total_tokens": self.total_tokens or 0,
+        }
+        
+        # Calculate success rate from scores
+        success_scores = [s for s in self.scores if s.name == "success" and s.data_type == ScoreDataType.BOOLEAN]
+        if success_scores:
+            success_rate = sum(1 for s in success_scores if s.value) / len(success_scores)
+            metrics["success_rate"] = success_rate
+        
+        return metrics

fluxloop/serialization.py

@@ -0,0 +1,116 @@
+"""Utilities for serializing trace and observation data."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict
+from uuid import UUID
+
+from .models import ObservationData, TraceData
+
+
+def _convert_uuid(value: UUID | None) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _convert_datetime(value: datetime | None) -> str | None:
+    if value is None:
+        return None
+    # Use ISO 8601 format with UTC indicator when possible
+    iso = value.isoformat()
+    if value.tzinfo is None:
+        return iso + "Z"
+    return iso
+
+
+def _make_json_safe(value: Any) -> Any:
+    """Recursively convert values so they can be JSON-serialized."""
+
+    if isinstance(value, datetime):
+        return _convert_datetime(value)
+
+    if isinstance(value, UUID):
+        return str(value)
+
+    if isinstance(value, Enum):
+        return value.value
+
+    if isinstance(value, dict):
+        return {str(key): _make_json_safe(val) for key, val in value.items()}
+
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [
+            _make_json_safe(item)
+            for item in value
+        ]
+
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+
+    return repr(value)
+
+
+def serialize_trace(trace: TraceData) -> Dict[str, Any]:
+    """Convert TraceData into a JSON-serializable dictionary."""
+
+    data = trace.model_dump(exclude_none=True)
+
+    if trace.id:
+        data["id"] = _convert_uuid(trace.id)
+    if trace.session_id:
+        data["session_id"] = _convert_uuid(trace.session_id)
+
+    if trace.start_time:
+        data["start_time"] = _convert_datetime(trace.start_time)
+    if trace.end_time:
+        data["end_time"] = _convert_datetime(trace.end_time)
+
+    if "metadata" in data:
+        data["metadata"] = _make_json_safe(data["metadata"])
+
+    if "input" in data:
+        data["input"] = _make_json_safe(data["input"])
+
+    if "output" in data:
+        data["output"] = _make_json_safe(data["output"])
+
+    return data
+
+
+def serialize_observation(observation: ObservationData) -> Dict[str, Any]:
+    """Convert ObservationData into a JSON-serializable dictionary."""
+
+    data = observation.model_dump(exclude_none=True)
+
+    if observation.id:
+        data["id"] = _convert_uuid(observation.id)
+    if observation.trace_id:
+        data["trace_id"] = _convert_uuid(observation.trace_id)
+    if observation.parent_observation_id:
+        data["parent_observation_id"] = _convert_uuid(observation.parent_observation_id)
+
+    if observation.start_time:
+        data["start_time"] = _convert_datetime(observation.start_time)
+    if observation.end_time:
+        data["end_time"] = _convert_datetime(observation.end_time)
+
+    if "metadata" in data:
+        data["metadata"] = _make_json_safe(data["metadata"])
+
+    if "input" in data:
+        data["input"] = _make_json_safe(data["input"])
+
+    if "output" in data:
+        data["output"] = _make_json_safe(data["output"])
+
+    if "llm_parameters" in data:
+        data["llm_parameters"] = _make_json_safe(data["llm_parameters"])
+
+    return data
+

fluxloop/storage.py

@@ -0,0 +1,53 @@
+"""Offline storage helper for FluxLoop traces and observations."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Iterable, Tuple
+from uuid import UUID
+
+from .config import get_config
+from .models import ObservationData, TraceData
+from .serialization import serialize_observation, serialize_trace
+
+
+class OfflineStore:
+    """Persist traces and observations to local JSON artifacts."""
+
+    def __init__(self) -> None:
+        self.config = get_config()
+        self.base_dir = Path(self.config.offline_store_dir)
+        self.traces_file = self.base_dir / "traces.jsonl"
+        self.observations_file = self.base_dir / "observations.jsonl"
+
+        if self.config.offline_store_enabled:
+            self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def record_traces(self, traces: Iterable[TraceData]) -> None:
+        if not self.config.offline_store_enabled:
+            return
+
+        if not self.traces_file.exists():
+            self.traces_file.write_text("")
+
+        with self.traces_file.open("a") as fp:
+            for trace in traces:
+                fp.write(json.dumps(serialize_trace(trace)) + os.linesep)
+
+    def record_observations(
+        self, items: Iterable[Tuple[UUID, ObservationData]]
+    ) -> None:
+        if not self.config.offline_store_enabled:
+            return
+
+        if not self.observations_file.exists():
+            self.observations_file.write_text("")
+
+        with self.observations_file.open("a") as fp:
+            for trace_id, observation in items:
+                payload = serialize_observation(observation)
+                payload["trace_id"] = str(trace_id)
+                fp.write(json.dumps(payload) + os.linesep)
+

fluxloop-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: fluxloop
+Version: 0.1.0
+Summary: FluxLoop SDK for agent instrumentation and tracing
+Author-email: FluxLoop Team <team@fluxloop.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/fluxloop/fluxloop
+Project-URL: Documentation, https://docs.fluxloop.dev
+Project-URL: Repository, https://github.com/fluxloop/fluxloop
+Project-URL: Issues, https://github.com/fluxloop/fluxloop/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.0.20; extra == "langgraph"
+
+# FluxLoop SDK
+
+FluxLoop SDK for agent instrumentation and tracing.
+
+## Installation
+
+```bash
+pip install fluxloop
+```
+
+## Quick Start
+
+```python
+from fluxloop import trace, FluxLoopClient
+
+# Initialize the client
+client = FluxLoopClient()
+
+# Use the trace decorator
+@trace()
+def my_agent_function(prompt: str):
+    # Your agent logic here
+    return result
+```
+
+## Features
+
+- 🔍 **Automatic Tracing**: Instrument your agent code with simple decorators
+- 📊 **Rich Context**: Capture inputs, outputs, and metadata
+- 🔄 **Async Support**: Works with both sync and async functions
+- 🎯 **Framework Integration**: Built-in support for LangChain and LangGraph
+
+## Documentation
+
+For detailed documentation, visit [https://docs.fluxloop.dev](https://docs.fluxloop.dev)
+
+## License
+
+Apache License 2.0 - see LICENSE file for details
+

fluxloop-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+fluxloop/__init__.py,sha256=TomDcCLgeFB1LG3NpspyFVQ3bd5HNr4CPA2etl5XXKs,1248
+fluxloop/buffer.py,sha256=pbviGFU0P_HlBYOlZccVuaj7OcQ5-M0L8d7r_vF1hQg,5940
+fluxloop/client.py,sha256=4WCi1de8MJW-5La-ZalVYEaN7-gUFHlr6mByi1bBoc0,5487
+fluxloop/config.py,sha256=A7hekvUFpQCeAcOEqj7d4fW8dvPihfaQ51ZbamiOyGw,5723
+fluxloop/context.py,sha256=09VTTSnn72E0wRf55PX5j355ngKE2GXaqCYpgBVgxMM,6458
+fluxloop/decorators.py,sha256=nfKIQpLwfMhr7A1TjtL-vppPWroPs98LsFB_1-ADfFM,15519
+fluxloop/models.py,sha256=5AQ2jqArRGwQB91GOBVrBRb1h5gJBghl5G81EClOUp8,2399
+fluxloop/recording.py,sha256=lnhJI0fWJfgMGMjw6TA8wU66PbelfYyD2UzMJ02W-uI,6609
+fluxloop/serialization.py,sha256=SkY4bSUHxBrCkrPns-jWC1PkVSX8qh-oBprQTbmc5Z8,3239
+fluxloop/storage.py,sha256=siwlbGdUpFAzdI6MMnODtkuxJyftQG9D4Phs2s5quMs,1732
+fluxloop/schemas/__init__.py,sha256=przYFHTxNK7juJbqWZ2YVuCdBiMk3PB1H7T4xg3l62g,911
+fluxloop/schemas/config.py,sha256=ib7GZVfWgUh9flwix9oKEOijyG0lWZjNBxC9lLbKZDw,11120
+fluxloop/schemas/trace.py,sha256=tkeYQon9pCTZLp1Ad3e-KM86xLaofIqxjHJ7l-mX0Bk,6270
+fluxloop-0.1.0.dist-info/METADATA,sha256=zeO_FZNKSlYYKAo-QDHZq2UJcbVqwWzGGfQ8ZSHWItM,2320
+fluxloop-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fluxloop-0.1.0.dist-info/top_level.txt,sha256=-whiUKvhn6Y7-TLfqrY7fZ1Cudjk8PnrKe7h7m8cuL4,9
+fluxloop-0.1.0.dist-info/RECORD,,

fluxloop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fluxloop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fluxloop