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

synth_ai/data/enums.py

@@ -0,0 +1,141 @@
+"""Centralized enums for Synth AI SDK.
+
+This module defines all enum types used across the SDK. Enums are pure data
+with no dependencies on other modules.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class JobType(str, Enum):
+    """Types of training/optimization jobs."""
+
+    PROMPT_LEARNING = "prompt_learning"
+    SFT = "sft"
+    RL = "rl"
+    GSPO = "gspo"
+    EVAL = "eval"
+    RESEARCH_AGENT = "research_agent"
+
+
+class JobStatus(str, Enum):
+    """Status of a job."""
+
+    PENDING = "pending"
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class PromptLearningMethod(str, Enum):
+    """Prompt optimization algorithms."""
+
+    GEPA = "gepa"
+    MIPRO = "mipro"
+
+
+class RLMethod(str, Enum):
+    """Reinforcement learning training algorithms."""
+
+    PPO = "ppo"
+    GRPO = "grpo"
+    REINFORCE = "reinforce"
+
+
+class SFTMethod(str, Enum):
+    """Supervised fine-tuning approaches."""
+
+    FULL = "full"
+    LORA = "lora"
+    QLORA = "qlora"
+
+
+class ResearchAgentAlgorithm(str, Enum):
+    """Research agent algorithms."""
+
+    SCAFFOLD_TUNING = "scaffold_tuning"
+    EVALUATION = "evaluation"
+    TRACE_ANALYSIS = "trace_analysis"
+
+
+class ContainerBackend(str, Enum):
+    """Container backends for research agent."""
+
+    DAYTONA = "daytona"
+    MODAL = "modal"
+    DOCKER = "docker"
+
+
+class InferenceMode(str, Enum):
+    """Inference modes for policy evaluation."""
+
+    SYNTH_HOSTED = "synth_hosted"
+
+
+class ProviderName(str, Enum):
+    """LLM provider names."""
+
+    OPENAI = "openai"
+    GROQ = "groq"
+    GOOGLE = "google"
+    ANTHROPIC = "anthropic"
+
+
+class RewardSource(str, Enum):
+    """Source of reward signal for training."""
+
+    TASK_APP = "task_app"
+    JUDGE = "judge"
+    FUSED = "fused"
+
+
+class AdaptiveCurriculumLevel(str, Enum):
+    """Preset levels for adaptive pooling curriculum."""
+
+    NONE = "NONE"
+    LOW = "LOW"
+    MODERATE = "MODERATE"
+    HIGH = "HIGH"
+
+
+class AdaptiveBatchLevel(str, Enum):
+    """Preset levels for adaptive batch curriculum (GEPA only)."""
+
+    NONE = "NONE"
+    LOW = "LOW"
+    MODERATE = "MODERATE"
+    HIGH = "HIGH"
+
+
+class SynthModelName(str, Enum):
+    """Synth-hosted model names for routing through Synth backend."""
+
+    SYNTH_SMALL = "synth-small"
+    SYNTH_MEDIUM = "synth-medium"
+
+
+# Legacy: list of model names for CLI validation
+SYNTH_MODEL_NAMES: list[str] = [m.value for m in SynthModelName]
+
+
+__all__ = [
+    "JobType",
+    "JobStatus",
+    "PromptLearningMethod",
+    "RLMethod",
+    "SFTMethod",
+    "ResearchAgentAlgorithm",
+    "ContainerBackend",
+    "InferenceMode",
+    "ProviderName",
+    "RewardSource",
+    "AdaptiveCurriculumLevel",
+    "AdaptiveBatchLevel",
+    "SynthModelName",
+    "SYNTH_MODEL_NAMES",
+]
+

synth_ai/data/rewards.py

@@ -0,0 +1,152 @@
+"""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.
+"""
+
+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.
+    """
+
+    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.
+    """
+
+    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_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/specs.py

@@ -0,0 +1,36 @@
+"""System specification data types.
+
+This module re-exports spec dataclasses from their original location
+to provide a cleaner import path: `from synth_ai.data.specs import Spec`
+
+Based on Sean Grove's "spec as code" pattern from AI Engineer World's Fair.
+Specs are the source of truth that encode intent, policies, and rules.
+"""
+
+from __future__ import annotations
+
+from synth_ai.sdk.specs.dataclasses import (
+    Constraints,
+    Example,
+    GlossaryItem,
+    Interfaces,
+    Metadata,
+    Principle,
+    Rule,
+    Spec,
+    TestCase,
+)
+
+__all__ = [
+    "Spec",
+    "Metadata",
+    "Principle",
+    "Rule",
+    "Constraints",
+    "Example",
+    "TestCase",
+    "Interfaces",
+    "GlossaryItem",
+]
+
+

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,46 @@
+"""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 judge/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")
+