synth-ai 0.2.9.dev7__py3-none-any.whl → 0.2.9.dev8__py3-none-any.whl

examples/warming_up_to_rl/task_app/synth_envs_hosted/storage/volume.py

@@ -8,7 +8,7 @@ import tarfile
 import tempfile
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any
 
 
 class VolumeStorage:
@@ -57,8 +57,8 @@ class VolumeStorage:
 
     def create_archive(
         self,
-        state_dict: Dict[str, Any],
-        meta: Dict[str, Any],
+        state_dict: dict[str, Any],
+        meta: dict[str, Any],
     ) -> bytes:
         """Create a tar.gz archive with state and metadata."""
         with tempfile.TemporaryDirectory() as tmpdir:
@@ -88,7 +88,7 @@ class VolumeStorage:
 
             return compressed
 
-    def extract_archive(self, archive_bytes: bytes) -> tuple[Dict[str, Any], Dict[str, Any]]:
+    def extract_archive(self, archive_bytes: bytes) -> tuple[dict[str, Any], dict[str, Any]]:
         """Extract state and metadata from a tar.gz archive."""
         # Decompress
         tar_bytes = gzip.decompress(archive_bytes)
@@ -106,10 +106,10 @@ class VolumeStorage:
                 tar.extractall(tmppath)
 
             # Read state and meta
-            with open(tmppath / "state.json", "r") as f:
+            with open(tmppath / "state.json") as f:
                 state = json.load(f)
 
-            with open(tmppath / "meta.json", "r") as f:
+            with open(tmppath / "meta.json") as f:
                 meta = json.load(f)
 
             return state, meta
@@ -122,9 +122,9 @@ class VolumeStorage:
         self,
         rl_run_id: str,
         kind: str,
-        state_dict: Dict[str, Any],
-        config: Optional[Dict[str, Any]] = None,
-        parent_snapshot_id: Optional[str] = None,
+        state_dict: dict[str, Any],
+        config: dict[str, Any] | None = None,
+        parent_snapshot_id: str | None = None,
     ) -> tuple[str, str, int]:
         """Save a snapshot and return (snapshot_id, path, size)."""
         # Build metadata
@@ -166,7 +166,7 @@ class VolumeStorage:
         rl_run_id: str,
         kind: str,
         snapshot_id: str,
-    ) -> tuple[Dict[str, Any], Dict[str, Any]]:
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
         """Load a snapshot and return (state_dict, meta)."""
         path = self.get_snapshot_path(rl_run_id, kind, snapshot_id)
 
@@ -182,7 +182,7 @@ class VolumeStorage:
     def append_to_index(
         self,
         rl_run_id: str,
-        meta: Dict[str, Any],
+        meta: dict[str, Any],
     ) -> None:
         """Append metadata to the run's index file."""
         index_path = self.get_index_path(rl_run_id)
@@ -191,7 +191,7 @@ class VolumeStorage:
         with open(index_path, "a") as f:
             f.write(json.dumps(meta) + "\n")
 
-    def read_index(self, rl_run_id: str) -> list[Dict[str, Any]]:
+    def read_index(self, rl_run_id: str) -> list[dict[str, Any]]:
         """Read all entries from a run's index file."""
         index_path = self.get_index_path(rl_run_id)
 
@@ -199,7 +199,7 @@ class VolumeStorage:
             return []
 
         entries = []
-        with open(index_path, "r") as f:
+        with open(index_path) as f:
             for line in f:
                 if line.strip():
                     entries.append(json.loads(line))

examples/warming_up_to_rl/task_app/synth_envs_hosted/test_agents.py

@@ -16,6 +16,7 @@ This script will:
 
 import asyncio
 import os
+
 import httpx
 
 BASE_URL = os.environ.get("SYNTH_ENVS_HOSTED_URL", "http://localhost:8000")

examples/warming_up_to_rl/task_app/synth_envs_hosted/test_service.py

@@ -8,6 +8,7 @@ Run this after starting the service with:
 
 import asyncio
 import json
+
 import httpx
 
 

examples/warming_up_to_rl/task_app/synth_envs_hosted/utils.py

@@ -1,7 +1,8 @@
 """Utility functions for the task service."""
 
+from typing import Any
+
 import numpy as np
-from typing import Any, Dict, List, Union
 
 
 def convert_numpy_to_python(obj: Any) -> Any:
@@ -22,13 +23,13 @@ def convert_numpy_to_python(obj: Any) -> Any:
         return obj.tolist()
     elif isinstance(obj, dict):
         return {key: convert_numpy_to_python(value) for key, value in obj.items()}
-    elif isinstance(obj, (list, tuple)):
+    elif isinstance(obj, list | tuple):
         return [convert_numpy_to_python(item) for item in obj]
     else:
         return obj
 
 
-def sanitize_observation(observation: Dict[str, Any]) -> Dict[str, Any]:
+def sanitize_observation(observation: dict[str, Any]) -> dict[str, Any]:
     """
     Sanitize observation data for JSON serialization.
 

synth/__init__.py

@@ -0,0 +1,14 @@
+_HELP_TEXT = """Synth-AI SDK
+
+Quickstart:
+    pip install synth-ai
+    import synth_ai
+    uvx synth-ai setup
+
+Docs → https://docs.usesynth.ai/sdk/get-started
+"""
+
+raise ImportError(
+    "No module named 'synth'. Did you mean 'synth_ai'?\n\n"
+    f"{_HELP_TEXT}"
+)

synth_ai/__init__.py

@@ -1,7 +1,3 @@
-"""
-Synth AI - Software for aiding the best and multiplying the will.
-"""
-
 # Environment exports - moved from synth-env
 from synth_ai.environments import *  # noqa
 import synth_ai.environments as environments  # expose module name for __all__
@@ -21,11 +17,35 @@ try:
 except Exception:
     AsyncOpenAI = OpenAI = None  # type: ignore
 
+# For LLMs
+try:
+    from .main import SynthAI
+except Exception:
+    SynthAI = None
+
 # Legacy tracing v1 is not required for v3 usage and can be unavailable in minimal envs.
 tracing = None  # type: ignore
 EventPartitionElement = RewardSignal = SystemTrace = TrainingQuestion = None  # type: ignore
 trace_event_async = trace_event_sync = upload = None  # type: ignore
 
+SDK_HELP = """
+Synth-AI SDK
+
+Quickstart:
+    pip install synth-ai
+    import synth_ai
+    uvx synth-ai setup
+
+Docs → https://docs.usesynth.ai/sdk/get-started
+""".strip()
+
+__doc__ = SDK_HELP
+
+
+def help() -> str:
+    """Return a concise quickstart for the Synth-AI SDK."""
+    return SDK_HELP
+
 __version__ = "0.2.6.dev4"
 __all__ = [
     "LM",
@@ -34,4 +54,6 @@ __all__ = [
     "Anthropic",
     "AsyncAnthropic",
     "environments",
+    "help",
+    "SynthAI"
 ]  # Explicitly define public API (v1 tracing omitted in minimal env)

synth_ai/api/models/supported.py

@@ -0,0 +1,376 @@
+"""Catalog of Synth-hosted base models and helpers (core vs experimental)."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+
+# ------------------------------------------------------------------------------
+# Model families
+# ------------------------------------------------------------------------------
+
+QWEN3_MODELS: list[str] = [
+    # Core Qwen3 base models
+    "Qwen/Qwen3-0.6B",
+    "Qwen/Qwen3-1.7B",
+    "Qwen/Qwen3-4B",
+    "Qwen/Qwen3-8B",
+    "Qwen/Qwen3-14B",
+    "Qwen/Qwen3-30B-A3B",
+    "Qwen/Qwen3-32B",
+    # Include 4B-2507 and Thinking variants used in RL
+    "Qwen/Qwen3-4B-Thinking-2507",
+    "Qwen/Qwen3-30B-A3B-Thinking-2507",
+    "Qwen/Qwen3-235B-A22B-Thinking-2507",
+]
+
+# Qwen3 Coder family (backend-supported); text-only, SFT/inference
+QWEN3_CODER_MODELS: list[str] = [
+    # Instruct variants used for coding tasks
+    "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+    "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+]
+
+# Training support sets
+RL_SUPPORTED_MODELS: frozenset[str] = frozenset(
+    {
+        "Qwen/Qwen3-1.7B",
+        "Qwen/Qwen3-4B",
+        "Qwen/Qwen3-4B-Thinking-2507",
+        "Qwen/Qwen3-8B",
+        "Qwen/Qwen3-14B",
+        "Qwen/Qwen3-30B-A3B",
+        "Qwen/Qwen3-30B-A3B-Thinking-2507",
+    }
+)
+
+# SFT allowlist includes core Qwen3 plus Coder family
+SFT_SUPPORTED_MODELS: frozenset[str] = frozenset([*QWEN3_MODELS, *QWEN3_CODER_MODELS])
+
+# ------------------------------------------------------------------------------
+# Lifecycle classification (core vs experimental)
+# ------------------------------------------------------------------------------
+
+# Which base models are considered "experimental" by default.
+_EXPERIMENTAL_DEFAULTS: frozenset[str] = frozenset(
+    {
+        # Larger (>= 64B) or bleeding-edge variants are experimental by default.
+        "Qwen/Qwen3-235B-A22B-Thinking-2507",
+        "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+        # Thinking variants can fluctuate more rapidly.
+        "Qwen/Qwen3-30B-A3B-Thinking-2507",
+        "Qwen/Qwen3-4B-Thinking-2507",
+    }
+)
+
+
+def _parse_experimental_env() -> frozenset[str]:
+    raw = os.getenv("SDK_EXPERIMENTAL_MODELS", "").strip()
+    if not raw:
+        return frozenset()
+    return frozenset(s.strip() for s in raw.split(",") if s.strip())
+
+
+# Final experimental set (defaults ∪ optional env override)
+EXPERIMENTAL_MODELS: frozenset[str] = frozenset(_EXPERIMENTAL_DEFAULTS | _parse_experimental_env())
+
+# Build catalog entries for both core and coder families under unified "Qwen3"
+_ALL_QWEN3_IDS: list[str] = [*QWEN3_MODELS, *QWEN3_CODER_MODELS]
+
+CORE_MODELS: frozenset[str] = frozenset(m for m in _ALL_QWEN3_IDS if m not in EXPERIMENTAL_MODELS)
+
+# ------------------------------------------------------------------------------
+# Experimental gating / warnings
+# ------------------------------------------------------------------------------
+
+
+class ExperimentalWarning(UserWarning):
+    """Warning for usage of experimental SDK models/APIs."""
+
+
+def _experimental_enabled() -> bool:
+    # Global toggle to permit experimental usage
+    return os.getenv("SDK_EXPERIMENTAL", "0") == "1"
+
+
+def _warn_if_experimental(model_id: str) -> None:
+    if model_id in EXPERIMENTAL_MODELS:
+        warnings.warn(
+            f"Model '{model_id}' is experimental and may change or be removed.",
+            category=ExperimentalWarning,
+            stacklevel=2,
+        )
+
+
+# ------------------------------------------------------------------------------
+# Model metadata + catalog
+# ------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SupportedModel:
+    """Metadata describing a supported base model."""
+
+    model_id: str
+    family: str
+    provider: str
+    modalities: tuple[str, ...] = ()
+    training_modes: tuple[str, ...] = ()
+    lifecycle: str = "core"  # "core" | "experimental"
+
+    def as_dict(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "model_id": self.model_id,
+            "family": self.family,
+            "provider": self.provider,
+            "lifecycle": self.lifecycle,
+        }
+        if self.modalities:
+            data["modalities"] = list(self.modalities)
+        if self.training_modes:
+            data["training_modes"] = list(self.training_modes)
+        return data
+
+
+SUPPORTED_MODELS: tuple[SupportedModel, ...] = tuple(
+    SupportedModel(
+        model_id=model,
+        family="Qwen3",
+        provider="Qwen",
+        modalities=("text",),
+        training_modes=tuple(
+            sorted(
+                {
+                    *(("sft",) if model in SFT_SUPPORTED_MODELS else ()),
+                    *(("rl",) if model in RL_SUPPORTED_MODELS else ()),
+                }
+            )
+        ),
+        lifecycle=("experimental" if model in EXPERIMENTAL_MODELS else "core"),
+    )
+    for model in _ALL_QWEN3_IDS
+)
+
+_BASE_LOOKUP = {model.model_id.lower(): model.model_id for model in SUPPORTED_MODELS}
+SUPPORTED_BASE_MODEL_IDS: frozenset[str] = frozenset(_BASE_LOOKUP.values())
+FINE_TUNED_PREFIXES: tuple[str, ...] = ("ft:", "fft:", "qft:", "rl:")
+_MODEL_BY_ID = {model.model_id: model for model in SUPPORTED_MODELS}
+
+# ------------------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------------------
+
+
+class UnsupportedModelError(ValueError):
+    """Raised when a model identifier is not supported by Synth."""
+
+
+def _extract_base_model(candidate: str, *, allow_finetuned_prefixes: bool) -> str | None:
+    cleaned = candidate.strip()
+    lowered = cleaned.lower()
+    base = _BASE_LOOKUP.get(lowered)
+    if base:
+        return base
+    if not allow_finetuned_prefixes or ":" not in cleaned:
+        return None
+
+    segments = cleaned.split(":")
+    for segment in segments[1:]:
+        candidate_base = segment.strip()
+        if not candidate_base:
+            continue
+        base = _BASE_LOOKUP.get(candidate_base.lower())
+        if base:
+            return base
+    return None
+
+
+def ensure_supported_model(
+    model_id: str,
+    *,
+    allow_finetuned_prefixes: bool = True,
+) -> str:
+    """Validate that *model_id* resolves to a supported base model (no lifecycle gate)."""
+    candidate = (model_id or "").strip()
+    if not candidate:
+        raise UnsupportedModelError("Model identifier is empty")
+
+    base = _extract_base_model(candidate, allow_finetuned_prefixes=allow_finetuned_prefixes)
+    if base:
+        return base
+
+    raise UnsupportedModelError(
+        f"Model '{candidate}' is not supported. Call supported_model_ids() for available base models."
+    )
+
+
+def ensure_allowed_model(
+    model_id: str,
+    *,
+    allow_finetuned_prefixes: bool = True,
+    allow_experimental: bool | None = None,
+) -> str:
+    """Validate support + lifecycle; gate experimental unless enabled."""
+    base = ensure_supported_model(model_id, allow_finetuned_prefixes=allow_finetuned_prefixes)
+    is_exp = base in EXPERIMENTAL_MODELS
+    allow_exp = allow_experimental if allow_experimental is not None else _experimental_enabled()
+    if is_exp and not allow_exp:
+        raise UnsupportedModelError(
+            f"Model '{base}' is experimental and disabled. "
+            "Set SDK_EXPERIMENTAL=1 or pass allow_experimental=True."
+        )
+    if is_exp:
+        _warn_if_experimental(base)
+    return base
+
+
+def normalize_model_identifier(
+    model_id: str,
+    *,
+    allow_finetuned_prefixes: bool = True,
+) -> str:
+    """Return a cleaned model identifier suitable for job payloads (no lifecycle gate)."""
+    canonical = ensure_supported_model(model_id, allow_finetuned_prefixes=allow_finetuned_prefixes)
+    cleaned = (model_id or "").strip()
+    if not cleaned:
+        return canonical
+    if cleaned.lower() in _BASE_LOOKUP:
+        return canonical
+    return cleaned
+
+
+def is_supported_model(model_id: str, *, allow_finetuned_prefixes: bool = True) -> bool:
+    """Return True if *model_id* resolves to a supported base model (ignores lifecycle)."""
+    try:
+        ensure_supported_model(model_id, allow_finetuned_prefixes=allow_finetuned_prefixes)
+    except UnsupportedModelError:
+        return False
+    return True
+
+
+def is_experimental_model(model_id: str) -> bool:
+    """Return True if *model_id* is marked experimental."""
+    try:
+        base = ensure_supported_model(model_id, allow_finetuned_prefixes=True)
+    except UnsupportedModelError:
+        return False
+    return base in EXPERIMENTAL_MODELS
+
+
+def is_core_model(model_id: str) -> bool:
+    """Return True if *model_id* is marked core."""
+    try:
+        base = ensure_supported_model(model_id, allow_finetuned_prefixes=True)
+    except UnsupportedModelError:
+        return False
+    return base in CORE_MODELS
+
+
+def iter_supported_models(
+    *,
+    families: Sequence[str] | None = None,
+    include: Sequence[str] | None = None,
+    exclude: Sequence[str] | None = None,
+) -> Iterator[SupportedModel]:
+    """Yield supported models, optionally filtered by family and lifecycle."""
+    include_set = {s.lower() for s in include} if include else None
+    exclude_set = {s.lower() for s in exclude} if exclude else None
+    fam_set = {f.lower() for f in families} if families else None
+
+    for m in SUPPORTED_MODELS:
+        if fam_set is not None and m.family.lower() not in fam_set:
+            continue
+        if include_set is not None and m.lifecycle.lower() not in include_set:
+            continue
+        if exclude_set is not None and m.lifecycle.lower() in exclude_set:
+            continue
+        yield m
+
+
+def list_supported_models(
+    *,
+    families: Sequence[str] | None = None,
+    include: Sequence[str] | None = None,
+    exclude: Sequence[str] | None = None,
+) -> list[SupportedModel]:
+    """Return supported models as a list for easier consumption."""
+    return list(iter_supported_models(families=families, include=include, exclude=exclude))
+
+
+def supported_model_ids(
+    *,
+    families: Sequence[str] | None = None,
+    include: Sequence[str] | None = None,
+    exclude: Sequence[str] | None = None,
+) -> list[str]:
+    """Return just the model identifiers for supported models."""
+    return [m.model_id for m in iter_supported_models(families=families, include=include, exclude=exclude)]
+
+
+def experimental_model_ids(*, families: Sequence[str] | None = None) -> list[str]:
+    """Return identifiers for experimental supported models."""
+    return supported_model_ids(families=families, include=("experimental",))
+
+
+def core_model_ids(*, families: Sequence[str] | None = None) -> list[str]:
+    """Return identifiers for core supported models."""
+    return supported_model_ids(families=families, include=("core",))
+
+
+def format_supported_models(
+    *,
+    families: Sequence[str] | None = None,
+    include: Sequence[str] | None = None,
+    exclude: Sequence[str] | None = None,
+) -> str:
+    """Produce a human readable table of supported models."""
+    rows: Iterable[SupportedModel] = iter_supported_models(families=families, include=include, exclude=exclude)
+    lines = ["model_id | family | provider | lifecycle | modalities | training_modes", "-" * 96]
+    for model in rows:
+        modalities = ",".join(model.modalities) or "-"
+        training = ",".join(model.training_modes) or "-"
+        lines.append(
+            f"{model.model_id} | {model.family} | {model.provider} | {model.lifecycle} | {modalities} | {training}"
+        )
+    return "\n".join(lines)
+
+
+def training_modes_for_model(model_id: str) -> tuple[str, ...]:
+    """Return the supported training modes (e.g., ('sft','rl')) for the given base model."""
+    canonical = ensure_supported_model(model_id, allow_finetuned_prefixes=True)
+    model = _MODEL_BY_ID.get(canonical)
+    if not model:
+        raise UnsupportedModelError(f"Model '{model_id}' is not registered as supported.")
+    return model.training_modes
+
+
+__all__ = [
+    "QWEN3_MODELS",
+    "QWEN3_CODER_MODELS",
+    "RL_SUPPORTED_MODELS",
+    "SFT_SUPPORTED_MODELS",
+    "EXPERIMENTAL_MODELS",
+    "CORE_MODELS",
+    "ExperimentalWarning",
+    "SupportedModel",
+    "SUPPORTED_MODELS",
+    "SUPPORTED_BASE_MODEL_IDS",
+    "FINE_TUNED_PREFIXES",
+    "UnsupportedModelError",
+    "ensure_supported_model",
+    "ensure_allowed_model",
+    "normalize_model_identifier",
+    "is_supported_model",
+    "is_experimental_model",
+    "is_core_model",
+    "iter_supported_models",
+    "list_supported_models",
+    "supported_model_ids",
+    "experimental_model_ids",
+    "core_model_ids",
+    "format_supported_models",
+    "training_modes_for_model",
+]
+