synth-ai 0.18.2.dev614__tar.gz → 0.18.2.dev617__tar.gz

{synth_ai-0.18.2.dev614/synth_ai.egg-info → synth_ai-0.18.2.dev617}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.18.2.dev614
+Version: 0.18.2.dev617
 Summary: Python SDK and CLI for Synth Managed Research and Research Factory
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -145,9 +145,7 @@ from synth_ai import SynthClient
 from synth_ai.sdk.research.public import EffortSpec, FactorySpec, ProjectId
 
 with SynthClient() as client:
-    factory = client.research.factories.create(
-        FactorySpec(name="Prompt optimizer")
-    )
+    factory = client.research.factories.create(FactorySpec(name="Prompt optimizer"))
     effort = client.research.factories.efforts.create(
         EffortSpec(
             factory_id=factory.factory_id,

{synth_ai-0.18.2.dev614 → synth_ai-0.18.2.dev617}/README.md

@@ -118,9 +118,7 @@ from synth_ai import SynthClient
 from synth_ai.sdk.research.public import EffortSpec, FactorySpec, ProjectId
 
 with SynthClient() as client:
-    factory = client.research.factories.create(
-        FactorySpec(name="Prompt optimizer")
-    )
+    factory = client.research.factories.create(FactorySpec(name="Prompt optimizer"))
     effort = client.research.factories.efforts.create(
         EffortSpec(
             factory_id=factory.factory_id,

{synth_ai-0.18.2.dev614 → synth_ai-0.18.2.dev617}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.18.2.dev614"
+version = "0.18.2.dev617"
 description = "Python SDK and CLI for Synth Managed Research and Research Factory"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"

{synth_ai-0.18.2.dev614 → synth_ai-0.18.2.dev617}/synth_ai/__init__.py

@@ -39,6 +39,7 @@ except _PackageNotFoundError:
 __all__ = [
     "AsyncResearchInternReactiveSession",
     "AsyncSynthClient",
+    "AsyncOptimizersClient",
     "DataBindingCreateRequest",
     "DatasetRevisionCreateRequest",
     "DatasetRevisionFinalizeRequest",
@@ -99,9 +100,30 @@ __all__ = [
     "ResearchVisualPromotionRequest",
     "ResearchVisualVersions",
     "SynthClient",
+    "OptimizersClient",
+    "OptimizerRunOutputs",
+    "SavedLoraCheckpoint",
+    "SavedLoraCheckpointPage",
+    "SavedLoraLineage",
+    "SavedLoraRunPage",
+    "HostedTrainingModelCatalog",
 ]
 
 _EXPORTS: dict[str, tuple[str, str]] = {
+    "AsyncOptimizersClient": ("synth_ai.sdk.optimizers", "AsyncOptimizersClient"),
+    "HostedTrainingModelCatalog": (
+        "synth_ai.sdk.optimizers",
+        "HostedTrainingModelCatalog",
+    ),
+    "OptimizersClient": ("synth_ai.sdk.optimizers", "OptimizersClient"),
+    "OptimizerRunOutputs": ("synth_ai.sdk.optimizers", "OptimizerRunOutputs"),
+    "SavedLoraCheckpoint": ("synth_ai.sdk.optimizers", "SavedLoraCheckpoint"),
+    "SavedLoraCheckpointPage": (
+        "synth_ai.sdk.optimizers",
+        "SavedLoraCheckpointPage",
+    ),
+    "SavedLoraLineage": ("synth_ai.sdk.optimizers", "SavedLoraLineage"),
+    "SavedLoraRunPage": ("synth_ai.sdk.optimizers", "SavedLoraRunPage"),
     "AsyncResearchInternReactiveSession": (
         "synth_ai.sdk.research.research_intern",
         "AsyncResearchInternReactiveSession",

{synth_ai-0.18.2.dev614 → synth_ai-0.18.2.dev617}/synth_ai/client.py

@@ -9,6 +9,7 @@ from synth_ai.core.auth.credentials import resolve_api_credential
 from synth_ai.core.utils.urls import BACKEND_URL_BASE, normalize_backend_base
 
 if TYPE_CHECKING:
+    from synth_ai.sdk.optimizers import AsyncOptimizersClient, OptimizersClient
     from synth_ai.sdk.research import AsyncResearchClient
     from synth_ai.sdk.research.facade import ResearchClient
 
@@ -22,10 +23,10 @@ def _resolve_base_url(base_url: str | None) -> str:
 
 
 class SynthClient:
-    """Sync client for Managed Research.
+    """Sync client for Managed Research and hosted optimizers.
 
     Use ``research`` for hosted projects, swarms, and Factory lifecycles. That
-    is the whole client: there is no container, tunnel, or pool namespace.
+    Use ``optimizers`` for hosted training model discovery and saved LoRAs.
     """
 
     def __init__(
@@ -41,6 +42,7 @@ class SynthClient:
         self.timeout_seconds = timeout_seconds
         self.allow_legacy_intern_sessions = allow_legacy_intern_sessions
         self._research_client: ResearchClient | None = None
+        self._optimizers_client: OptimizersClient | None = None
 
     @property
     def research(self) -> ResearchClient:
@@ -61,6 +63,22 @@ class SynthClient:
         if self._research_client is not None:
             self._research_client.close()
             self._research_client = None
+        if self._optimizers_client is not None:
+            self._optimizers_client.close()
+            self._optimizers_client = None
+
+    @property
+    def optimizers(self) -> OptimizersClient:
+        """Hosted training models and searchable saved-LoRA lineage."""
+        if self._optimizers_client is None:
+            from synth_ai.sdk.optimizers import OptimizersClient
+
+            self._optimizers_client = OptimizersClient(
+                api_key=self.api_key,
+                base_url=self.base_url,
+                timeout_seconds=self.timeout_seconds,
+            )
+        return self._optimizers_client
 
     def __enter__(self) -> SynthClient:
         return self
@@ -70,7 +88,7 @@ class SynthClient:
 
 
 class AsyncSynthClient:
-    """Async client for Managed Research."""
+    """Async client for Managed Research and hosted optimizers."""
 
     def __init__(
         self,
@@ -85,6 +103,7 @@ class AsyncSynthClient:
         self.timeout_seconds = timeout_seconds
         self.allow_legacy_intern_sessions = allow_legacy_intern_sessions
         self._async_research_client: AsyncResearchClient | None = None
+        self._async_optimizers_client: AsyncOptimizersClient | None = None
 
     @property
     def research(self) -> AsyncResearchClient:
@@ -115,6 +134,22 @@ class AsyncSynthClient:
         if self._async_research_client is not None:
             await self._async_research_client.close()
             self._async_research_client = None
+        if self._async_optimizers_client is not None:
+            await self._async_optimizers_client.close()
+            self._async_optimizers_client = None
+
+    @property
+    def optimizers(self) -> AsyncOptimizersClient:
+        """Native asynchronous hosted optimizer namespace."""
+        if self._async_optimizers_client is None:
+            from synth_ai.sdk.optimizers import AsyncOptimizersClient
+
+            self._async_optimizers_client = AsyncOptimizersClient(
+                api_key=self.api_key,
+                base_url=self.base_url,
+                timeout_seconds=self.timeout_seconds,
+            )
+        return self._async_optimizers_client
 
     async def __aenter__(self) -> AsyncSynthClient:
         return self

{synth_ai-0.18.2.dev614 → synth_ai-0.18.2.dev617}/synth_ai/mcp/research/tools/research_intern.py

@@ -1153,6 +1153,11 @@ def build_research_intern_tools(
                         "type": "integer",
                         "minimum": 0,
                         "maximum": 60,
+                        "description": (
+                            "Bounded wait for the explicit Factory-ready "
+                            "condition before binding; omit to refuse "
+                            "immediately with a typed readiness report."
+                        ),
                     },
                 },
                 required=["objective", "idempotency_key"],

synth_ai-0.18.2.dev617/synth_ai/sdk/optimizers/__init__.py

@@ -0,0 +1,30 @@
+"""Public hosted optimizer SDK namespace."""
+
+from synth_ai.sdk.optimizers.client import AsyncOptimizersClient, OptimizersClient
+from synth_ai.sdk.optimizers.contracts import (
+    HostedTrainingModel,
+    HostedTrainingModelCatalog,
+    OptimizerRunArtifact,
+    OptimizerRunIdentity,
+    OptimizerRunOutputs,
+    SavedLoraCheckpoint,
+    SavedLoraCheckpointPage,
+    SavedLoraLineage,
+    SavedLoraRunPage,
+    SavedLoraStorage,
+)
+
+__all__ = [
+    "AsyncOptimizersClient",
+    "HostedTrainingModel",
+    "HostedTrainingModelCatalog",
+    "OptimizerRunIdentity",
+    "OptimizerRunArtifact",
+    "OptimizerRunOutputs",
+    "OptimizersClient",
+    "SavedLoraCheckpoint",
+    "SavedLoraCheckpointPage",
+    "SavedLoraLineage",
+    "SavedLoraRunPage",
+    "SavedLoraStorage",
+]

synth_ai-0.18.2.dev617/synth_ai/sdk/optimizers/client.py

@@ -0,0 +1,309 @@
+"""Public sync and async clients for hosted optimizers."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from urllib.parse import quote
+
+from synth_ai.core.auth.credentials import resolve_api_credential
+from synth_ai.core.contracts.json_value import JsonObject, JsonValue
+from synth_ai.core.http.async_transport import AsyncHttpTransport
+from synth_ai.core.http.transport import HttpTransport
+from synth_ai.core.utils.urls import BACKEND_URL_BASE, normalize_backend_base
+from synth_ai.sdk.optimizers.contracts import (
+    HostedTrainingModelCatalog,
+    OptimizerRunOutputs,
+    SavedLoraCheckpoint,
+    SavedLoraCheckpointPage,
+    SavedLoraRunPage,
+)
+
+
+def _object(payload: JsonValue) -> JsonObject:
+    if not isinstance(payload, dict):
+        raise ValueError("optimizer API response must be an object")
+    return payload
+
+
+def _params(**values: Any) -> dict[str, JsonValue]:
+    return {key: value for key, value in values.items() if value is not None and value != ""}
+
+
+class CheckpointsAPI:
+    """List automatically persisted checkpoints and traverse their lineage."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    def list(
+        self,
+        *,
+        query: str | None = None,
+        scope: str = "all",
+        optimizer_algorithm: str | None = None,
+        run_id: str | None = None,
+        attempt_id: str | None = None,
+        source_checkpoint_id: str | None = None,
+        provider: str | None = None,
+        checkpoint_kind: str | None = None,
+        base_model: str | None = None,
+        status: str | None = "ready",
+        tags: Sequence[str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> SavedLoraCheckpointPage:
+        """Search saved checkpoints with filters and a page size clamped to 1–100."""
+        payload = self._transport.request_json(
+            "GET",
+            "/api/v1/optimizers/checkpoints",
+            params=_params(
+                q=query,
+                scope=scope,
+                optimizer_algorithm=optimizer_algorithm,
+                run_id=run_id,
+                attempt_id=attempt_id,
+                source_checkpoint_id=source_checkpoint_id,
+                provider=provider,
+                checkpoint_kind=checkpoint_kind,
+                base_model=base_model,
+                status=status,
+                tags=tags,
+                limit=max(1, min(100, limit)),
+                offset=max(0, offset),
+            ),
+            operation_id="optimizers.checkpoints.list",
+        )
+        return SavedLoraCheckpointPage.model_validate(_object(payload))
+
+    def get(self, checkpoint_id: str) -> SavedLoraCheckpoint:
+        """Retrieve one saved checkpoint by its URL-escaped identifier."""
+        payload = self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/checkpoints/{quote(checkpoint_id, safe='')}",
+            operation_id="optimizers.checkpoints.get",
+        )
+        return SavedLoraCheckpoint.model_validate(_object(payload))
+
+    def list_for_run(
+        self,
+        run_id: str,
+        *,
+        checkpoint_kind: str | None = None,
+        status: str | None = "ready",
+        limit: int = 100,
+        offset: int = 0,
+    ) -> SavedLoraRunPage:
+        """List saved checkpoints for one run with bounded pagination."""
+        payload = self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/runs/{quote(run_id, safe='')}/saved-checkpoints",
+            params=_params(
+                checkpoint_kind=checkpoint_kind,
+                status=status,
+                limit=max(1, min(100, limit)),
+                offset=max(0, offset),
+            ),
+            operation_id="optimizers.checkpoints.list_for_run",
+        )
+        return SavedLoraRunPage.model_validate(_object(payload))
+
+
+class ModelsAPI:
+    """Discover models and algorithm support available for hosted training."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    def list(
+        self, *, algorithm: str | None = None, provider: str | None = None
+    ) -> HostedTrainingModelCatalog:
+        """Discover hosted training models filtered by algorithm and provider."""
+        payload = self._transport.request_json(
+            "GET",
+            "/api/v1/optimizers/models/training",
+            params=_params(algorithm=algorithm, provider=provider),
+            operation_id="optimizers.models.list",
+        )
+        return HostedTrainingModelCatalog.model_validate(_object(payload))
+
+
+class RunsAPI:
+    """Inspect automatically persisted outputs for hosted optimizer runs."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    def outputs(self, run_id: str) -> OptimizerRunOutputs:
+        """Retrieve the backend-owned output inventory for one optimizer run."""
+        payload = self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/runs/{quote(run_id, safe='')}/outputs",
+            operation_id="optimizers.runs.outputs",
+        )
+        return OptimizerRunOutputs.model_validate(_object(payload))
+
+
+class AsyncCheckpointsAPI:
+    """Asynchronous saved-checkpoint discovery and lineage reads."""
+
+    def __init__(self, transport: AsyncHttpTransport) -> None:
+        self._transport = transport
+
+    async def list(
+        self,
+        *,
+        query: str | None = None,
+        scope: str = "all",
+        optimizer_algorithm: str | None = None,
+        run_id: str | None = None,
+        attempt_id: str | None = None,
+        source_checkpoint_id: str | None = None,
+        provider: str | None = None,
+        checkpoint_kind: str | None = None,
+        base_model: str | None = None,
+        status: str | None = "ready",
+        tags: Sequence[str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> SavedLoraCheckpointPage:
+        """Search saved checkpoints with filters and a page size clamped to 1–100."""
+        payload = await self._transport.request_json(
+            "GET",
+            "/api/v1/optimizers/checkpoints",
+            params=_params(
+                q=query,
+                scope=scope,
+                optimizer_algorithm=optimizer_algorithm,
+                run_id=run_id,
+                attempt_id=attempt_id,
+                source_checkpoint_id=source_checkpoint_id,
+                provider=provider,
+                checkpoint_kind=checkpoint_kind,
+                base_model=base_model,
+                status=status,
+                tags=tags,
+                limit=max(1, min(100, limit)),
+                offset=max(0, offset),
+            ),
+            operation_id="optimizers.checkpoints.list",
+        )
+        return SavedLoraCheckpointPage.model_validate(_object(payload))
+
+    async def get(self, checkpoint_id: str) -> SavedLoraCheckpoint:
+        """Retrieve one saved checkpoint by its URL-escaped identifier."""
+        payload = await self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/checkpoints/{quote(checkpoint_id, safe='')}",
+            operation_id="optimizers.checkpoints.get",
+        )
+        return SavedLoraCheckpoint.model_validate(_object(payload))
+
+    async def list_for_run(
+        self,
+        run_id: str,
+        *,
+        checkpoint_kind: str | None = None,
+        status: str | None = "ready",
+        limit: int = 100,
+        offset: int = 0,
+    ) -> SavedLoraRunPage:
+        """List saved checkpoints for one run with bounded pagination."""
+        payload = await self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/runs/{quote(run_id, safe='')}/saved-checkpoints",
+            params=_params(
+                checkpoint_kind=checkpoint_kind,
+                status=status,
+                limit=max(1, min(100, limit)),
+                offset=max(0, offset),
+            ),
+            operation_id="optimizers.checkpoints.list_for_run",
+        )
+        return SavedLoraRunPage.model_validate(_object(payload))
+
+
+class AsyncModelsAPI:
+    """Asynchronous hosted training model discovery."""
+
+    def __init__(self, transport: AsyncHttpTransport) -> None:
+        self._transport = transport
+
+    async def list(self, **filters: Any) -> HostedTrainingModelCatalog:
+        """Read the training model catalog using backend-supported query filters."""
+        payload = await self._transport.request_json(
+            "GET",
+            "/api/v1/optimizers/models/training",
+            params=_params(**filters),
+            operation_id="optimizers.models.list",
+        )
+        return HostedTrainingModelCatalog.model_validate(_object(payload))
+
+
+class AsyncRunsAPI:
+    """Asynchronous reads of persisted hosted optimizer outputs."""
+
+    def __init__(self, transport: AsyncHttpTransport) -> None:
+        self._transport = transport
+
+    async def outputs(self, run_id: str) -> OptimizerRunOutputs:
+        """Retrieve the backend-owned output inventory for one optimizer run."""
+        payload = await self._transport.request_json(
+            "GET",
+            f"/api/v1/optimizers/runs/{quote(run_id, safe='')}/outputs",
+            operation_id="optimizers.runs.outputs",
+        )
+        return OptimizerRunOutputs.model_validate(_object(payload))
+
+
+class OptimizersClient:
+    """Hosted optimizer namespace mounted at ``SynthClient.optimizers``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        credential = resolve_api_credential(api_key)
+        self._transport = HttpTransport(
+            base_url=normalize_backend_base(base_url or BACKEND_URL_BASE),
+            headers=credential.authorization_headers(),
+            timeout_seconds=timeout_seconds,
+        )
+        self.checkpoints = CheckpointsAPI(self._transport)
+        self.models = ModelsAPI(self._transport)
+        self.runs = RunsAPI(self._transport)
+
+    def close(self) -> None:
+        """Close the hosted optimizer HTTP transport."""
+        self._transport.close()
+
+
+class AsyncOptimizersClient:
+    """Native asynchronous hosted optimizer namespace."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        credential = resolve_api_credential(api_key)
+        self._transport = AsyncHttpTransport(
+            base_url=normalize_backend_base(base_url or BACKEND_URL_BASE),
+            headers=credential.authorization_headers(),
+            timeout_seconds=timeout_seconds,
+        )
+        self.checkpoints = AsyncCheckpointsAPI(self._transport)
+        self.models = AsyncModelsAPI(self._transport)
+        self.runs = AsyncRunsAPI(self._transport)
+
+    async def close(self) -> None:
+        """Close the asynchronous hosted optimizer HTTP transport."""
+        await self._transport.close()
+
+
+__all__ = ["AsyncOptimizersClient", "OptimizersClient"]

synth_ai-0.18.2.dev617/synth_ai/sdk/optimizers/contracts.py

@@ -0,0 +1,142 @@
+"""Typed public contracts for hosted optimizer model discovery and lineage."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OptimizerContract(BaseModel):
+    """Forward-compatible base for optimizer API payloads."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class SavedLoraStorage(OptimizerContract):
+    backend: str
+    bucket: str
+    key: str
+    version: str | None = None
+    etag: str | None = None
+    sha256: str | None = None
+    size_bytes: int | None = None
+    content_type: str
+
+
+class SavedLoraLineage(OptimizerContract):
+    optimizer_algorithm: str | None = None
+    run_id: str | None = None
+    attempt_id: str | None = None
+    source_checkpoint_id: str | None = None
+    provider_checkpoint_reference: str | None = None
+
+
+class SavedLoraCheckpoint(OptimizerContract):
+    schema_version: str = "saved_lora_checkpoint.v1"
+    checkpoint_id: str
+    org_id: str
+    owner_user_id: str | None = None
+    visibility: str
+    name: str
+    description: str = ""
+    provider: str
+    checkpoint_kind: str
+    provider_checkpoint_reference: str | None = None
+    optimizer_algorithm: str | None = None
+    run_id: str | None = None
+    attempt_id: str | None = None
+    source_checkpoint_id: str | None = None
+    base_model: str
+    lora_rank: int | None = None
+    step: int | None = None
+    status: str
+    storage: SavedLoraStorage
+    lineage: SavedLoraLineage = Field(default_factory=SavedLoraLineage)
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str | None = None
+    updated_at: str | None = None
+    archived_at: str | None = None
+
+
+class SavedLoraCheckpointPage(OptimizerContract):
+    items: list[SavedLoraCheckpoint]
+    total: int
+    limit: int
+    offset: int
+
+
+class OptimizerRunIdentity(OptimizerContract):
+    run_id: str
+    attempt_id: str | None = None
+    optimizer_algorithm: str
+    status: str
+
+
+class OptimizerRunArtifact(OptimizerContract):
+    artifact_id: str
+    run_id: str
+    artifact_name: str
+    content_type: str | None = None
+    size_bytes: int
+    sha256: str | None = None
+    storage_backend: str
+    uri: str
+    download_path: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class OptimizerRunOutputs(OptimizerContract):
+    """All automatically persisted outputs for one optimizer run."""
+
+    schema_version: str = "optimizer.run_outputs.v1"
+    run: OptimizerRunIdentity
+    result: dict[str, Any] | None = None
+    artifacts: list[OptimizerRunArtifact]
+    model_checkpoints: list[SavedLoraCheckpoint]
+    counts: dict[str, int]
+
+
+class SavedLoraRunPage(OptimizerContract):
+    schema_version: str = "saved_lora_checkpoint.run_page.v1"
+    run: OptimizerRunIdentity
+    items: list[SavedLoraCheckpoint]
+    counts: dict[str, int]
+    total: int
+    limit: int
+    offset: int
+
+
+class HostedTrainingModel(OptimizerContract):
+    model_id: str
+    label: str
+    provider: str
+    provider_revision: str
+    architecture: str
+    max_context_length: int
+    rank: dict[str, int]
+    algorithms: dict[str, dict[str, Any]]
+
+
+class HostedTrainingModelCatalog(OptimizerContract):
+    catalog_revision: str
+    live_preflight_required: bool
+    models: list[HostedTrainingModel]
+    total: int
+
+
+__all__ = [
+    "HostedTrainingModel",
+    "HostedTrainingModelCatalog",
+    "OptimizerRunIdentity",
+    "OptimizerRunArtifact",
+    "OptimizerRunOutputs",
+    "SavedLoraCheckpoint",
+    "SavedLoraCheckpointPage",
+    "SavedLoraLineage",
+    "SavedLoraRunPage",
+    "SavedLoraStorage",
+]