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

synth_ai/sdk/api/train/configs/rl.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from pydantic import model_validator
+
+from ..utils import load_toml
+from .shared import AlgorithmConfig, ComputeConfig, ExtraModel, LoraConfig, PolicyConfig
+
+
+class RLServicesConfig(ExtraModel):
+    task_url: str
+    judge_url: str | None = None
+
+
+class ModelConfig(ExtraModel):
+    source: str | None = None
+    base: str | None = None
+    trainer_mode: str
+    label: str
+
+    @model_validator(mode="after")
+    def _ensure_exactly_one_source_or_base(self) -> ModelConfig:
+        if bool(self.source) == bool(self.base):
+            raise ValueError("Config must set exactly one of [model].source or [model].base")
+        return self
+
+
+class RolloutConfig(ExtraModel):
+    env_name: str
+    policy_name: str
+    env_config: dict[str, Any] | None = None
+    policy_config: dict[str, Any] | None = None
+    max_turns: int
+    episodes_per_batch: int
+    max_concurrent_rollouts: int
+    batches_per_step: int | None = None
+    ops: list[str] | None = None
+
+
+class WeightSyncConfig(ExtraModel):
+    enable: bool | None = None
+    targets: list[str] | None = None
+    mode: str | None = None
+    direct: bool | None = None
+    verify_every_k: int | None = None
+
+
+class RewardsConfig(ExtraModel):
+    """Rewards configuration for RL training."""
+    step_rewards_enabled: bool | None = None
+    step_rewards_mode: str | None = None
+    step_rewards_indicator_lambda: float | None = None
+    step_rewards_beta: float | None = None
+    step_rewards_strategy: str | None = None
+    event_rewards_kind: str | None = None
+
+
+class RLTrainingConfig(ExtraModel):
+    num_epochs: int
+    iterations_per_epoch: int
+    gradient_accumulation_steps: int | None = None
+    max_accumulated_minibatch: int | None = None
+    max_turns: int
+    batch_size: int
+    group_size: int
+    learning_rate: float
+    log_interval: int | None = None
+    weight_sync_interval: int | None = None
+    # DEPRECATED: flat reward fields (use rewards.* instead)
+    step_rewards_enabled: bool | None = None
+    step_rewards_mode: str | None = None
+    step_rewards_indicator_lambda: float | None = None
+    step_rewards_beta: float | None = None
+    step_rewards_strategy: str | None = None
+    event_rewards_kind: str | None = None
+    # NEW: nested configs
+    weight_sync: WeightSyncConfig | None = None
+    lora: LoraConfig | None = None
+    rewards: RewardsConfig | None = None
+
+
+class EvaluationConfig(ExtraModel):
+    instances: int
+    every_n_iters: int
+    seeds: list[int]
+
+
+class JudgeOptionsConfig(ExtraModel):
+    event: bool | None = None
+    outcome: bool | None = None
+    provider: str | None = None
+    model: str | None = None
+    rubric_id: str | None = None
+    rubric_overrides: dict[str, Any] | None = None
+    tracks: list[str] | None = None
+    weights: dict[str, float] | None = None
+    max_concurrency: int | None = None
+
+
+class RubricConfig(ExtraModel):
+    """Rubric configuration for reward blending."""
+    enabled: bool = False
+    reward_blend: dict[str, float] | None = None  # env, event, outcome weights
+
+
+class JudgeConfig(ExtraModel):
+    type: str | None = None
+    timeout_s: int | None = None
+    enabled: bool | None = None  # Master switch for judge/rubric
+    reward_blend: dict[str, float] | None = None  # NEW: nested reward blending (replaces rubric.weights)
+    rubric: RubricConfig | None = None  # DEPRECATED: use flat fields instead
+    options: JudgeOptionsConfig | None = None
+
+
+class SmokeConfig(ExtraModel):
+    """Configuration for local smoke testing (CLI only, ignored by trainer)."""
+    # Test parameters
+    task_url: str | None = None
+    env_name: str | None = None
+    policy_name: str | None = None
+    max_steps: int | None = None
+    policy: str | None = None  # mock, gpt-5-nano, openai, groq
+    model: str | None = None
+    mock_backend: str | None = None  # synthetic or openai
+    mock_port: int | None = None
+    return_trace: bool | None = None
+    use_mock: bool | None = None
+    
+    # Task app auto-start configuration
+    task_app_name: str | None = None  # Task app to serve (e.g., "grpo-crafter")
+    task_app_port: int | None = None  # Port for task app (default: 8765)
+    task_app_env_file: str | None = None  # Path to .env file for task app
+    task_app_force: bool | None = None  # Use --force flag when serving
+    
+    # sqld auto-start configuration
+    sqld_auto_start: bool | None = None  # Auto-start sqld server
+    sqld_db_path: str | None = None  # Database path (default: ./traces/local.db)
+    sqld_hrana_port: int | None = None  # Hrana WebSocket port (default: 8080)
+    sqld_http_port: int | None = None  # HTTP API port (default: 8081)
+
+
+class RLConfig(ExtraModel):
+    algorithm: AlgorithmConfig
+    services: RLServicesConfig
+    compute: ComputeConfig | None = None
+    topology: dict[str, Any] | None = None  # DEPRECATED: use compute.topology instead
+    vllm: dict[str, Any] | None = None
+    reference: dict[str, Any] | None = None  # DEPRECATED: use compute.topology.reference_placement instead
+    model: ModelConfig | None = None  # DEPRECATED: use policy instead
+    policy: PolicyConfig | None = None  # NEW: unified policy (preferred)
+    lora: dict[str, Any] | None = None  # DEPRECATED: use training.lora instead
+    rollout: RolloutConfig | None = None
+    evaluation: EvaluationConfig | None = None
+    training: RLTrainingConfig | None = None
+    rubric: dict[str, Any] | None = None  # DEPRECATED: use judge.reward_blend and judge.enabled instead
+    judge: JudgeConfig | None = None
+    tags: dict[str, Any] | None = None
+    smoke: SmokeConfig | None = None  # CLI-only: local smoke testing config (ignored by trainer)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="python", exclude_none=True)
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> RLConfig:
+        """Load RL config from dict/TOML mapping."""
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_path(cls, path: Path) -> RLConfig:
+        content = load_toml(path)
+        return cls.from_mapping(content)
+
+
+__all__ = [
+    "EvaluationConfig",
+    "JudgeConfig",
+    "JudgeOptionsConfig",
+    "ModelConfig",
+    "RLConfig",
+    "RLServicesConfig",
+    "RLTrainingConfig",
+    "RolloutConfig",
+    "SmokeConfig",
+    "WeightSyncConfig",
+]

synth_ai/sdk/api/train/configs/sft.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from pydantic import Field
+
+from ..utils import load_toml
+from .shared import AlgorithmConfig, ComputeConfig, ExtraModel, LoraConfig, PolicyConfig
+
+
+class JobConfig(ExtraModel):
+    model: str
+    data: str | None = None
+    data_path: str | None = None
+    poll_seconds: int | None = None
+
+
+class SFTDataConfig(ExtraModel):
+    topology: dict[str, Any] | None = None
+    validation_path: str | None = None
+
+
+class TrainingValidationConfig(ExtraModel):
+    enabled: bool | None = None
+    evaluation_strategy: str | None = None
+    eval_steps: int | None = None
+    save_best_model_at_end: bool | None = None
+    metric_for_best_model: str | None = None
+    greater_is_better: bool | None = None
+
+
+class TrainingConfig(ExtraModel):
+    mode: str | None = None
+    use_qlora: bool | None = None
+    validation: TrainingValidationConfig | None = None
+    lora: LoraConfig | None = None  # NEW: nested LoRA config
+
+
+class HyperparametersParallelism(ExtraModel):
+    use_deepspeed: bool | None = None
+    deepspeed_stage: int | None = None
+    fsdp: bool | None = None
+    bf16: bool | None = None
+    fp16: bool | None = None
+    activation_checkpointing: bool | None = None
+    tensor_parallel_size: int | None = None
+    pipeline_parallel_size: int | None = None
+
+
+class HyperparametersConfig(ExtraModel):
+    n_epochs: int = 1
+    batch_size: int | None = None
+    global_batch: int | None = None
+    per_device_batch: int | None = None
+    gradient_accumulation_steps: int | None = None
+    sequence_length: int | None = None
+    learning_rate: float | None = None
+    warmup_ratio: float | None = None
+    train_kind: str | None = None
+    weight_decay: float | None = None
+    parallelism: HyperparametersParallelism | None = None
+
+
+class SFTConfig(ExtraModel):
+    algorithm: AlgorithmConfig | None = None
+    job: JobConfig
+    policy: PolicyConfig | None = None  # NEW: unified policy section
+    compute: ComputeConfig | None = None
+    data: SFTDataConfig | None = None
+    training: TrainingConfig | None = None
+    hyperparameters: HyperparametersConfig = Field(default_factory=HyperparametersConfig)
+    lora: dict[str, Any] | None = None  # DEPRECATED: use training.lora instead
+    tags: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="python", exclude_none=True)
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> SFTConfig:
+        """Load SFT config from dict/TOML mapping."""
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_path(cls, path: Path) -> SFTConfig:
+        content = load_toml(path)
+        return cls.from_mapping(content)
+
+
+__all__ = [
+    "HyperparametersConfig",
+    "HyperparametersParallelism",
+    "JobConfig",
+    "SFTConfig",
+    "SFTDataConfig",
+    "TrainingConfig",
+    "TrainingValidationConfig",
+]

synth_ai/sdk/api/train/configs/shared.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+
+class ExtraModel(BaseModel):
+    """Base model that tolerates unknown keys so configs keep forward compatibility."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class AlgorithmConfig(ExtraModel):
+    type: str
+    method: str
+    variety: str
+
+
+class TopologyConfig(ExtraModel):
+    """Compute topology configuration - how GPUs are distributed across processes."""
+    type: str | None = None  # e.g., "single_node_split"
+    gpus_for_vllm: int | None = None
+    gpus_for_training: int | None = None
+    gpus_for_ref: int | None = None
+    tensor_parallel: int | None = None
+    reference_placement: str | None = None  # NEW: e.g., "none", "shared", "dedicated"
+
+
+class LoraConfig(ExtraModel):
+    """LoRA (Low-Rank Adaptation) training configuration."""
+    r: int | None = None  # Rank
+    alpha: int | None = None
+    dropout: float | None = None
+    target_modules: list[str] | None = None
+
+
+class ComputeConfig(ExtraModel):
+    gpu_type: str
+    gpu_count: int
+    nodes: int | None = None
+    topology: TopologyConfig | None = None  # NEW: nested topology
+
+
+class PolicyConfig(ExtraModel):
+    """Unified policy configuration for both SFT and RL.
+    
+    This is the SINGLE SOURCE OF TRUTH for:
+    - What model to use (model_name or source)
+    - How to sample from it (temperature, max_tokens, etc.)
+    - How to train it (trainer_mode, label)
+    """
+    
+    # Model specification (exactly one required)
+    model_name: str | None = None  # e.g., "Qwen/Qwen3-4B"
+    source: str | None = None       # e.g., "ft:abc123" for checkpoints
+    
+    # Sampling parameters (with sensible defaults)
+    max_tokens: int = 512
+    temperature: float = 0.7
+    top_p: float = 0.95
+    top_k: int | None = None
+    repetition_penalty: float = 1.0
+    stop_sequences: list[str] | None = None
+    
+    # Training-specific
+    trainer_mode: str  # "lora", "full", "qlora"
+    label: str         # Model identifier/name
+    
+    # Optional - for distributed inference
+    inference_url: str | None = None
+    
+    @model_validator(mode="after")
+    def _ensure_exactly_one_source(self) -> PolicyConfig:
+        """Ensure exactly one of model_name or source is set."""
+        if not (bool(self.model_name) ^ bool(self.source)):
+            raise ValueError(
+                "Must set exactly one: [policy].model_name OR [policy].source"
+            )
+        return self
+
+
+__all__ = ["ExtraModel", "AlgorithmConfig", "ComputeConfig", "PolicyConfig", "TopologyConfig", "LoraConfig"]

synth_ai/sdk/api/train/context_learning.py

@@ -0,0 +1,312 @@
+"""First-class SDK API for Context Learning (Context Engineering).
+
+Context Learning is an infra training job type that optimizes environment
+setup scripts (pre-flight / post-flight bash) for terminal/coding agents.
+
+CLI usage:
+    uvx synth-ai train --type context_learning --config my_context.toml
+
+SDK usage:
+    from synth_ai.sdk.api.train.context_learning import ContextLearningJob
+
+    job = ContextLearningJob.from_config("context.toml")
+    job.submit()
+    final = job.stream_until_complete()
+    best = job.download_best_script()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence
+
+from synth_ai.core.telemetry import log_info
+
+from synth_ai.sdk.streaming import (
+    ContextLearningHandler,
+    JobStreamer,
+    StreamConfig,
+    StreamEndpoints,
+    StreamType,
+)
+
+from .utils import ensure_api_base, http_get, http_post, load_toml, TrainError
+
+
+@dataclass
+class ContextLearningSubmitResult:
+    job_id: str
+    status: str
+    created_at: Optional[str] = None
+
+
+@dataclass
+class BestScriptResult:
+    job_id: str
+    best_score: float
+    preflight_script: str
+    generation: int
+    variation_id: str
+    metadata: Dict[str, Any]
+
+
+@dataclass
+class ContextLearningJobConfig:
+    config_path: Path
+    backend_url: str
+    api_key: str
+    task_app_api_key: Optional[str] = None
+    overrides: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        if not self.config_path.exists():
+            raise FileNotFoundError(f"Config file not found: {self.config_path}")
+        if not self.backend_url:
+            raise ValueError("backend_url is required")
+        if not self.api_key:
+            raise ValueError("api_key is required")
+        if not self.task_app_api_key:
+            self.task_app_api_key = os.environ.get("ENVIRONMENT_API_KEY")
+
+
+class ContextLearningJob:
+    """High-level SDK class for running Context Learning jobs."""
+
+    def __init__(self, config: ContextLearningJobConfig, job_id: Optional[str] = None) -> None:
+        self.config = config
+        self._job_id = job_id
+        self._payload: Optional[Dict[str, Any]] = None
+
+    @property
+    def job_id(self) -> Optional[str]:
+        return self._job_id
+
+    @classmethod
+    def from_config(
+        cls,
+        config_path: str | Path,
+        *,
+        backend_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        task_app_api_key: Optional[str] = None,
+        overrides: Optional[Dict[str, Any]] = None,
+    ) -> ContextLearningJob:
+        from synth_ai.core.env import get_backend_from_env
+
+        config_path_obj = Path(config_path)
+
+        if not backend_url:
+            backend_url = os.environ.get("BACKEND_BASE_URL", "").strip()
+            if not backend_url:
+                base, _ = get_backend_from_env()
+                backend_url = f"{base}/api" if not base.endswith("/api") else base
+
+        if not api_key:
+            api_key = os.environ.get("SYNTH_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "api_key is required (provide explicitly or set SYNTH_API_KEY env var)"
+                )
+
+        cfg = ContextLearningJobConfig(
+            config_path=config_path_obj,
+            backend_url=backend_url,
+            api_key=api_key,
+            task_app_api_key=task_app_api_key,
+            overrides=overrides or {},
+        )
+        return cls(cfg)
+
+    @classmethod
+    def from_job_id(
+        cls,
+        job_id: str,
+        *,
+        backend_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+    ) -> ContextLearningJob:
+        from synth_ai.core.env import get_backend_from_env
+
+        if not backend_url:
+            backend_url = os.environ.get("BACKEND_BASE_URL", "").strip()
+            if not backend_url:
+                base, _ = get_backend_from_env()
+                backend_url = f"{base}/api" if not base.endswith("/api") else base
+
+        if not api_key:
+            api_key = os.environ.get("SYNTH_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "api_key is required (provide explicitly or set SYNTH_API_KEY env var)"
+                )
+
+        cfg = ContextLearningJobConfig(
+            config_path=Path("/dev/null"),
+            backend_url=backend_url,
+            api_key=api_key,
+        )
+        return cls(cfg, job_id=job_id)
+
+    def _build_payload(self) -> Dict[str, Any]:
+        if self._payload is not None:
+            return self._payload
+
+        cfg = load_toml(self.config.config_path)
+        section = cfg.get("context_learning")
+        if not isinstance(section, dict):
+            raise TrainError("Missing required [context_learning] section.")
+
+        task_app_url = section.get("task_app_url") or section.get("task_url")
+        if not task_app_url:
+            raise TrainError("[context_learning].task_app_url is required")
+
+        evaluation_seeds = section.get("evaluation_seeds") or []
+        if not isinstance(evaluation_seeds, list):
+            raise TrainError("[context_learning].evaluation_seeds must be a list")
+
+        env_section = section.get("environment") if isinstance(section.get("environment"), dict) else {}
+        preflight_script = env_section.get("preflight_script")
+        postflight_script = env_section.get("postflight_script")
+
+        # Support script paths
+        preflight_path = env_section.get("baseline_preflight_script_path")
+        if preflight_path and not preflight_script:
+            p = Path(str(preflight_path))
+            preflight_script = p.read_text(encoding="utf-8")
+
+        postflight_path = env_section.get("baseline_postflight_script_path")
+        if postflight_path and not postflight_script:
+            p = Path(str(postflight_path))
+            postflight_script = p.read_text(encoding="utf-8")
+
+        algo_section = section.get("algorithm") if isinstance(section.get("algorithm"), dict) else {}
+
+        algorithm_config: Dict[str, Any] = {}
+        for key in (
+            "initial_population_size",
+            "num_generations",
+            "mutation_llm_model",
+            "policy_config",
+        ):
+            if key in algo_section and algo_section[key] is not None:
+                algorithm_config[key] = algo_section[key]
+
+        metadata = section.get("metadata") if isinstance(section.get("metadata"), dict) else {}
+
+        payload: Dict[str, Any] = {
+            "task_app_url": task_app_url,
+            "task_app_api_key": self.config.task_app_api_key,
+            "evaluation_seeds": evaluation_seeds,
+            "environment": {
+                "preflight_script": preflight_script,
+                "postflight_script": postflight_script,
+            },
+            "algorithm_config": algorithm_config,
+            "metadata": metadata,
+            "auto_start": True,
+        }
+
+        # Merge overrides (CLI and caller)
+        for k, v in (self.config.overrides or {}).items():
+            if v is not None:
+                payload[k] = v
+
+        self._payload = payload
+        return payload
+
+    def submit(self) -> ContextLearningSubmitResult:
+        if self._job_id:
+            raise RuntimeError(f"Job already submitted: {self._job_id}")
+
+        payload = self._build_payload()
+        url = f"{self.config.backend_url.rstrip('/')}/context-learning/jobs"
+        headers = {
+            "Authorization": f"Bearer {self.config.api_key}",
+            "Content-Type": "application/json",
+        }
+        log_info("ContextLearningJob.submit invoked", ctx={"url": url})
+        resp = http_post(url, headers=headers, json_body=payload)
+        if resp.status_code not in (200, 201):
+            raise RuntimeError(
+                f"Context learning submission failed: {resp.status_code} {resp.text[:500]}"
+            )
+        js = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
+        job_id = js.get("job_id")
+        if not job_id:
+            raise RuntimeError("Response missing job_id")
+        self._job_id = job_id
+        return ContextLearningSubmitResult(
+            job_id=job_id,
+            status=js.get("status", "pending"),
+            created_at=js.get("created_at"),
+        )
+
+    def stream_until_complete(
+        self,
+        *,
+        handlers: Optional[Sequence[Any]] = None,
+        on_event: Optional[Callable[[Dict[str, Any]], None]] = None,
+    ) -> Dict[str, Any]:
+        if not self._job_id:
+            raise RuntimeError("Job not yet submitted. Call submit() first.")
+
+        config = StreamConfig(
+            enabled_streams={StreamType.STATUS, StreamType.EVENTS, StreamType.METRICS},
+            max_events_per_poll=500,
+            deduplicate=True,
+        )
+
+        if handlers is None:
+            handlers = [ContextLearningHandler()]
+
+        streamer = JobStreamer(
+            base_url=self.config.backend_url,
+            api_key=self.config.api_key,
+            job_id=self._job_id,
+            endpoints=StreamEndpoints.context_learning(self._job_id),
+            config=config,
+            handlers=list(handlers),
+        )
+
+        final_status = asyncio.run(streamer.stream_until_terminal())
+
+        if on_event and isinstance(final_status, dict):
+            try:
+                on_event(final_status)
+            except Exception:
+                pass
+
+        return final_status
+
+    def download_best_script(self) -> BestScriptResult:
+        if not self._job_id:
+            raise RuntimeError("Job not yet submitted. Call submit() first.")
+
+        url = f"{self.config.backend_url.rstrip('/')}/context-learning/jobs/{self._job_id}/best-script"
+        headers = {"Authorization": f"Bearer {self.config.api_key}"}
+        resp = http_get(url, headers=headers)
+        if resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to fetch best script: {resp.status_code} {resp.text[:500]}"
+            )
+        js = resp.json()
+        return BestScriptResult(
+            job_id=js.get("job_id", self._job_id),
+            best_score=float(js.get("best_score") or 0.0),
+            preflight_script=str(js.get("preflight_script") or ""),
+            generation=int(js.get("generation") or 0),
+            variation_id=str(js.get("variation_id") or ""),
+            metadata=js.get("metadata") or {},
+        )
+
+
+__all__ = [
+    "ContextLearningJob",
+    "ContextLearningJobConfig",
+    "ContextLearningSubmitResult",
+    "BestScriptResult",
+]
+