synth-ai 0.2.14__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/data/rewards.py

@@ -0,0 +1,249 @@
+"""Reward data structures.
+
+This module defines pure data types for representing rewards in training
+and evaluation contexts. These are actual data records, not API abstractions.
+
+Synth AI uses two primary reward scopes:
+
+- **Event Rewards**: Fine-grained rewards attached to individual events within a session
+  (e.g., each tool call, each LLM response). Use `EventRewardRecord` to annotate specific
+  events with reward values.
+
+- **Outcome Rewards**: Episode-level rewards that summarize the overall success of a
+  complete session. Use `OutcomeRewardRecord` for aggregate metrics.
+
+Example usage:
+
+```python
+from synth_ai.data.rewards import EventRewardRecord, OutcomeRewardRecord
+
+# Annotate a specific event with a reward
+event_reward = EventRewardRecord(
+    event_id="evt_123",
+    session_id="sess_abc",
+    reward_value=0.8,
+    reward_type="evaluator",
+    annotation={"reason": "Correct tool selection"}
+)
+
+# Record episode-level outcome
+outcome = OutcomeRewardRecord(
+    session_id="sess_abc",
+    total_reward=0.85,
+    achievements_count=3,
+    total_steps=10,
+    metadata={"task": "code_generation"}
+)
+```
+
+See Also:
+- Event rewards SDK guide: /sdk/tracing/rewards/event-rewards
+- Outcome rewards SDK guide: /sdk/tracing/rewards/outcome-rewards
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass
+class RewardRecord:
+    """A single reward observation.
+
+    Represents a reward signal at a specific point in a trajectory,
+    with metadata about its source and scope.
+
+    Attributes:
+        value: The numeric reward value (typically in range [0, 1] or unbounded).
+        reward_type: Category of reward - "shaped" (dense), "sparse" (terminal only),
+            "achievement" (milestone), "penalty" (negative signal), "evaluator"
+            (from LLM verifier), or "human" (manual annotation).
+        scope: Granularity level - "step" (per action), "event" (per significant event),
+            or "outcome" (episode-level).
+        source: Origin of the reward - "environment" (task env), "runner" (framework),
+            "evaluator" (verifier), or "human" (annotator).
+        key: Optional identifier like achievement name or rubric criterion ID.
+        turn: Turn number within the session where reward was earned.
+        timestamp: When the reward was recorded.
+        metadata: Additional context (e.g., rubric scores, evaluation details).
+    """
+
+    value: float
+    reward_type: Literal["shaped", "sparse", "achievement", "penalty", "evaluator", "human"] = "shaped"
+    scope: Literal["step", "event", "outcome"] = "step"
+    source: Literal["environment", "runner", "evaluator", "human"] | None = None
+    key: str | None = None  # e.g., achievement name
+    turn: int | None = None
+    timestamp: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class OutcomeRewardRecord:
+    """Episode-level reward summary.
+
+    Aggregates reward information for a complete episode/session,
+    including total reward, achievements, and step counts. This is the
+    primary data structure for outcome rewards used in training.
+
+    Attributes:
+        session_id: Unique identifier linking to the SessionTrace.
+        total_reward: Aggregate reward for the entire episode (typically 0.0-1.0).
+        achievements_count: Number of achievements/milestones reached.
+        total_steps: Total number of steps in the episode.
+        metadata: Task-specific metadata (e.g., {"task": "code_gen", "difficulty": "hard"}).
+        annotation: Human or evaluator annotations explaining the score.
+        created_at: When this record was created.
+
+    Example:
+        ```python
+        outcome = OutcomeRewardRecord(
+            session_id="sess_abc123",
+            total_reward=0.75,
+            achievements_count=2,
+            total_steps=8,
+            metadata={"task": "customer_support"},
+            annotation={"evaluator": "Resolved issue but could improve tone"}
+        )
+        ```
+    """
+
+    session_id: str
+    total_reward: float
+    achievements_count: int = 0
+    total_steps: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    annotation: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None
+
+
+@dataclass
+class EventRewardRecord:
+    """Event-level reward annotation.
+
+    Links a reward to a specific event in a trace, with optional
+    annotations and source information. Event rewards provide fine-grained
+    feedback on individual actions or decisions within a session.
+
+    Attributes:
+        event_id: Unique identifier of the event being rewarded.
+        session_id: Session containing this event.
+        reward_value: Reward for this specific event (typically 0.0-1.0).
+        reward_type: Category of reward (e.g., "tool_success", "reasoning", "progress").
+        key: Rubric criterion or achievement key this reward relates to.
+        turn_number: Turn/step within the session where event occurred.
+        source: Origin of the reward ("environment", "evaluator", "human").
+        annotation: Explanation or details about why this reward was given.
+        created_at: When this record was created.
+
+    Example:
+        ```python
+        event_reward = EventRewardRecord(
+            event_id="evt_tool_call_5",
+            session_id="sess_abc123",
+            reward_value=1.0,
+            reward_type="tool_success",
+            turn_number=3,
+            source="environment",
+            annotation={"tool": "search", "result": "found_answer"}
+        )
+        ```
+    """
+
+    event_id: str
+    session_id: str
+    reward_value: float
+    reward_type: str | None = None
+    key: str | None = None
+    turn_number: int | None = None
+    source: str | None = None
+    annotation: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None
+
+
+@dataclass
+class RewardAggregates:
+    """Aggregated statistics for a set of rewards."""
+
+    mean: float
+    median: float = 0.0
+    std: float = 0.0
+    n: int = 0
+    min_value: float | None = None
+    max_value: float | None = None
+
+
+@dataclass
+class CalibrationExample:
+    """A calibration example for few-shot verifier evaluation.
+    
+    Contains a full execution trace with its ground truth rewards.
+    Used to teach the verifier evaluation patterns through labeled examples.
+    """
+    
+    session_trace: dict[str, Any]  # V3 SessionTrace format (validated separately)
+    event_rewards: list[float]  # List of rewards per event (0.0-1.0), one per event in trace
+    outcome_reward: float  # Overall outcome reward (0.0-1.0)
+    metadata: dict[str, Any] = field(default_factory=dict)  # Optional metadata
+    
+    def __post_init__(self) -> None:
+        """Validate reward values."""
+        # Validate event_rewards are in range
+        for idx, reward in enumerate(self.event_rewards):
+            if not isinstance(reward, (int, float)) or reward < 0.0 or reward > 1.0:
+                raise ValueError(
+                    f"event_rewards[{idx}] must be float 0.0-1.0, got {reward} (type: {type(reward).__name__})"
+                )
+        
+        # Validate outcome_reward is in range
+        if not isinstance(self.outcome_reward, (int, float)) or self.outcome_reward < 0.0 or self.outcome_reward > 1.0:
+            raise ValueError(
+                f"outcome_reward must be float 0.0-1.0, got {self.outcome_reward} (type: {type(self.outcome_reward).__name__})"
+            )
+        
+        # Convert to float for consistency
+        self.event_rewards = [float(r) for r in self.event_rewards]
+        self.outcome_reward = float(self.outcome_reward)
+
+
+@dataclass
+class GoldExample:
+    """A gold-standard example for contrastive verifier evaluation.
+    
+    Contains a correctly scored trace example that the verifier's judgment
+    will be compared against. Used to evaluate verifier consistency.
+    """
+    
+    summary: str  # Summary of the trace being evaluated
+    gold_score: float  # Gold-standard score (0.0-1.0)
+    gold_reasoning: str  # Gold-standard reasoning/explanation
+    session_trace: dict[str, Any] | None = None  # Optional full trace (for richer evaluation)
+    metadata: dict[str, Any] = field(default_factory=dict)  # Optional metadata
+    
+    def __post_init__(self) -> None:
+        """Validate score and fields."""
+        if not self.summary or not isinstance(self.summary, str) or not self.summary.strip():
+            raise ValueError("summary must be a non-empty string")
+        
+        if not isinstance(self.gold_score, (int, float)) or self.gold_score < 0.0 or self.gold_score > 1.0:
+            raise ValueError(
+                f"gold_score must be float 0.0-1.0, got {self.gold_score} (type: {type(self.gold_score).__name__})"
+            )
+        
+        if not self.gold_reasoning or not isinstance(self.gold_reasoning, str) or not self.gold_reasoning.strip():
+            raise ValueError("gold_reasoning must be a non-empty string")
+        
+        # Convert to float for consistency
+        self.gold_score = float(self.gold_score)
+
+
+__all__ = [
+    "RewardRecord",
+    "OutcomeRewardRecord",
+    "EventRewardRecord",
+    "RewardAggregates",
+    "CalibrationExample",
+    "GoldExample",
+]

synth_ai/data/traces.py

@@ -0,0 +1,35 @@
+"""Trace data types - re-exported from tracing_v3.
+
+The tracing_v3 format is stable and well-tested. This module provides
+a cleaner import path: `from synth_ai.data.traces import SessionTrace`
+
+DO NOT modify tracing_v3 internals. This module only re-exports types.
+"""
+
+from __future__ import annotations
+
+from synth_ai.core.tracing_v3.abstractions import (
+    BaseEvent,
+    EnvironmentEvent,
+    LMCAISEvent,
+    RuntimeEvent,
+    SessionEventMarkovBlanketMessage,
+    SessionMessageContent,
+    SessionTimeStep,
+    SessionTrace,
+    TimeRecord,
+)
+
+__all__ = [
+    "SessionTrace",
+    "SessionTimeStep",
+    "BaseEvent",
+    "RuntimeEvent",
+    "EnvironmentEvent",
+    "LMCAISEvent",
+    "SessionEventMarkovBlanketMessage",
+    "SessionMessageContent",
+    "TimeRecord",
+]
+
+

synth_ai/products/__init__.py

@@ -0,0 +1,6 @@
+"""Synth AI Products - Graph optimization and more."""
+
+from .graph_evolve import GraphOptimizationConfig, GraphOptimizationClient
+
+__all__ = ["GraphOptimizationConfig", "GraphOptimizationClient"]
+

synth_ai/products/graph_evolve/__init__.py

@@ -0,0 +1,45 @@
+"""GraphEvolve - Optimize LLM workflow graphs.
+
+This product provides tools for optimizing LLM-based workflow graphs
+using evolutionary algorithms. It can optimize both:
+
+- **Policy graphs**: Graphs that solve tasks (e.g., multi-hop QA, reasoning)
+- **Verifier graphs**: Graphs that verify/score existing results
+
+Algorithms:
+- `graph_evolve`: Evolutionary optimization for graph structure
+
+Usage:
+    # From command line:
+    synth graph-optimization run --config config.toml
+
+    # Or programmatically:
+    from synth_ai.products.graph_evolve import GraphOptimizationClient, GraphOptimizationConfig
+
+    config = GraphOptimizationConfig.from_toml("config.toml")
+    async with GraphOptimizationClient(base_url, api_key) as client:
+        job_id = await client.start_job(config)
+        async for event in client.stream_events(job_id):
+            print(event)
+"""
+
+from .config import GraphOptimizationConfig
+from .client import GraphOptimizationClient
+from .converters import (
+    convert_openai_sft,
+    preview_conversion,
+    ConversionResult,
+    ConversionWarning,
+    ConversionError,
+)
+
+__all__ = [
+    "GraphOptimizationConfig",
+    "GraphOptimizationClient",
+    # Converters
+    "convert_openai_sft",
+    "preview_conversion",
+    "ConversionResult",
+    "ConversionWarning",
+    "ConversionError",
+]

synth_ai/products/graph_evolve/client.py

@@ -0,0 +1,226 @@
+"""Client for GraphEvolve Optimization jobs.
+
+This module provides a client for interacting with the graph
+optimization job API on the backend.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Dict, Optional
+
+import httpx
+
+from .config import GraphOptimizationConfig
+
+
+class GraphOptimizationClient:
+    """Client for Graph Optimization Job API.
+    
+    This client interacts with the backend to run graph optimization jobs.
+    The client is agnostic to graph internals - it just manages jobs.
+    
+    Example:
+        async with GraphOptimizationClient("http://localhost:8000", api_key) as client:
+            config = GraphOptimizationConfig.from_toml("config.toml")
+            job_id = await client.start_job(config)
+            
+            async for event in client.stream_events(job_id):
+                print(event["type"], event.get("data", {}))
+            
+            result = await client.get_result(job_id)
+            print(f"Best score: {result['best_score']}")
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        api_key: Optional[str] = None,
+        timeout: float = 300.0,
+    ):
+        """Initialize the client.
+        
+        Args:
+            base_url: Backend API URL
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client: Optional[httpx.AsyncClient] = None
+    
+    async def __aenter__(self) -> "GraphOptimizationClient":
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=self.timeout,
+        )
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+    
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Use 'async with GraphOptimizationClient(...) as client:'"
+            )
+        return self._client
+    
+    def _get_api_prefix(self, algorithm: str) -> str:
+        """Get the API prefix for an algorithm.
+
+        Args:
+            algorithm: Algorithm name (e.g., "graph_evolve")
+
+        Returns:
+            API prefix (e.g., "/graph-evolve")
+        """
+        # Map algorithm names to API prefixes
+        prefixes = {
+            "graph_evolve": "/graph-evolve",
+            "graph_gepa": "/graph-evolve",  # Backwards compat: map old name to new endpoint
+            # Future algorithms can be added here
+        }
+        return prefixes.get(algorithm, f"/{algorithm.replace('_', '-')}")
+    
+    async def start_job(
+        self,
+        config: GraphOptimizationConfig,
+    ) -> str:
+        """Start a graph optimization job.
+        
+        Args:
+            config: Job configuration (includes algorithm selection)
+            
+        Returns:
+            Job ID (e.g., "graph_evolve_abc123")
+            
+        Raises:
+            httpx.HTTPStatusError: If request fails
+        """
+        client = self._ensure_client()
+        prefix = self._get_api_prefix(config.algorithm)
+        response = await client.post(
+            f"{prefix}/jobs",
+            json=config.to_request_dict(),
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["job_id"]
+    
+    async def get_status(self, job_id: str) -> Dict[str, Any]:
+        """Get job status.
+
+        Args:
+            job_id: Job ID
+
+        Returns:
+            Status dictionary with status, progress, current_generation, etc.
+        """
+        client = self._ensure_client()
+        response = await client.get(f"/graph-evolve/jobs/{job_id}/status")
+        response.raise_for_status()
+        return response.json()
+
+    async def get_result(self, job_id: str) -> Dict[str, Any]:
+        """Get job result.
+
+        Args:
+            job_id: Job ID
+
+        Returns:
+            Result dictionary with best_yaml, best_score, etc.
+        """
+        client = self._ensure_client()
+        response = await client.get(f"/graph-evolve/jobs/{job_id}/result")
+        response.raise_for_status()
+        return response.json()
+
+    async def cancel_job(self, job_id: str) -> Dict[str, Any]:
+        """Cancel a running job.
+
+        Args:
+            job_id: Job ID
+
+        Returns:
+            Cancellation confirmation
+        """
+        client = self._ensure_client()
+        response = await client.delete(f"/graph-evolve/jobs/{job_id}")
+        response.raise_for_status()
+        return response.json()
+
+    async def stream_events(
+        self,
+        job_id: str,
+        timeout: float = 600.0,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Stream events from a running job via SSE.
+
+        Args:
+            job_id: Job ID
+            timeout: Stream timeout in seconds
+
+        Yields:
+            Event dictionaries with type, data, etc.
+        """
+        client = self._ensure_client()
+
+        async with client.stream(
+            "GET",
+            f"/graph-evolve/jobs/{job_id}/events",
+            timeout=timeout,
+        ) as response:
+            response.raise_for_status()
+            
+            async for line in response.aiter_lines():
+                line = line.strip()
+                if not line:
+                    continue
+                if line.startswith("data: "):
+                    data_str = line[6:]
+                    if data_str == "[DONE]":
+                        break
+                    try:
+                        yield json.loads(data_str)
+                    except json.JSONDecodeError:
+                        continue
+    
+    async def wait_for_completion(
+        self,
+        job_id: str,
+        poll_interval: float = 2.0,
+        max_wait: float = 3600.0,
+    ) -> Dict[str, Any]:
+        """Wait for job completion by polling status.
+        
+        Args:
+            job_id: Job ID
+            poll_interval: Seconds between status checks
+            max_wait: Maximum wait time in seconds
+            
+        Returns:
+            Final job result
+            
+        Raises:
+            TimeoutError: If max_wait exceeded
+        """
+        import asyncio
+        import time
+        
+        start = time.time()
+        while time.time() - start < max_wait:
+            status = await self.get_status(job_id)
+            if status.get("status") in ("completed", "failed", "cancelled"):
+                return await self.get_result(job_id)
+            await asyncio.sleep(poll_interval)
+        
+        raise TimeoutError(f"Job {job_id} did not complete within {max_wait}s")
+