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

{synth_ai-0.18.2.dev615/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.dev615
+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.dev615 → 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.dev615 → synth_ai-0.18.2.dev617}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.18.2.dev615"
+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.dev615 → 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.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/optimizers/client.py

@@ -53,6 +53,7 @@ class CheckpointsAPI:
         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",
@@ -76,6 +77,7 @@ class CheckpointsAPI:
         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='')}",
@@ -92,6 +94,7 @@ class CheckpointsAPI:
         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",
@@ -115,6 +118,7 @@ class ModelsAPI:
     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",
@@ -131,6 +135,7 @@ class RunsAPI:
         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",
@@ -140,6 +145,8 @@ class RunsAPI:
 
 
 class AsyncCheckpointsAPI:
+    """Asynchronous saved-checkpoint discovery and lineage reads."""
+
     def __init__(self, transport: AsyncHttpTransport) -> None:
         self._transport = transport
 
@@ -160,6 +167,7 @@ class AsyncCheckpointsAPI:
         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",
@@ -183,6 +191,7 @@ class AsyncCheckpointsAPI:
         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='')}",
@@ -199,6 +208,7 @@ class AsyncCheckpointsAPI:
         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",
@@ -214,10 +224,13 @@ class AsyncCheckpointsAPI:
 
 
 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",
@@ -228,10 +241,13 @@ class AsyncModelsAPI:
 
 
 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",
@@ -261,6 +277,7 @@ class OptimizersClient:
         self.runs = RunsAPI(self._transport)
 
     def close(self) -> None:
+        """Close the hosted optimizer HTTP transport."""
         self._transport.close()
 
 
@@ -285,6 +302,7 @@ class AsyncOptimizersClient:
         self.runs = AsyncRunsAPI(self._transport)
 
     async def close(self) -> None:
+        """Close the asynchronous hosted optimizer HTTP transport."""
         await self._transport.close()
 
 

{synth_ai-0.18.2.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/research/contracts/__init__.py

@@ -322,6 +322,9 @@ from synth_ai.sdk.research.contracts.research_intern import (
     DataBindingResponse,
     DatasetRevisionCreateRequest,
     DatasetRevisionResponse,
+    InternAcceptanceFixtureReceipt,
+    InternAcceptanceFixtureRequest,
+    InternAcceptanceFixtureResource,
     InternAgentConfig,
     InternAsyncBlocker,
     InternAsyncCheckpoint,
@@ -517,8 +520,11 @@ from synth_ai.sdk.research.contracts.traces import (
     TraceStoreAccessReceipt,
     TraceStoreDescriptor,
     TraceStoreLifecycleReceipt,
+    TraceStorePreflightRequest,
+    TraceStorePreflightResponse,
     TraceStoreProvisioningStatus,
     TraceStoreProvisionResult,
+    TraceStoreRunEnvelopeIdentity,
 )
 from synth_ai.sdk.research.contracts.transcript import (
     SwarmTranscriptEvent,
@@ -794,6 +800,9 @@ __all__ = [
     "ImageUploadId",
     "InferenceProvider",
     "InternAgentConfig",
+    "InternAcceptanceFixtureReceipt",
+    "InternAcceptanceFixtureRequest",
+    "InternAcceptanceFixtureResource",
     "InternAsyncBlocker",
     "InternAsyncCheckpoint",
     "InternAsyncCommandKind",
@@ -1103,6 +1112,9 @@ __all__ = [
     "TranscriptReplayMode",
     "TranscriptView",
     "TranscriptVisibilityDecision",
+    "TraceStorePreflightRequest",
+    "TraceStorePreflightResponse",
+    "TraceStoreRunEnvelopeIdentity",
     "UsageFreshness",
     "UsageMoney",
     "UsageSource",

{synth_ai-0.18.2.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/research/contracts/research_intern.py

@@ -536,6 +536,17 @@ class InternSyncCommandReceipt(_StrictContract):
     state_generation: int = Field(ge=0)
     decision_code: str
     created_at: datetime
+    # Durable actuation receipt (schema smr.intern-command-actuation.v1),
+    # present once the command reached a final decision. Kept opaque
+    # (WS3 per-field decision: supported_opaque) because the backend mints it,
+    # types it as an open JSON object in its own contract, and stamps a
+    # result_digest over its canonical content; re-modeling it here would put
+    # a second schema authority under that digest. Absent on older backends.
+    actuation: dict[str, Any] | None = None
+    # True when this response replays an already-admitted command (idempotent
+    # retry); the stored receipt/actuation is immutable. Older backends omit
+    # the field, which means first application.
+    duplicate: bool = False
 
 
 class InternSyncEvent(_StrictContract):
@@ -926,6 +937,14 @@ class InternAsyncCommandReceipt(_StrictContract):
     state_generation: int = Field(ge=0)
     decision_code: str
     created_at: datetime
+    # Same durable actuation receipt as InternSyncCommandReceipt.actuation:
+    # backend-minted smr.intern-command-actuation.v1, kept opaque
+    # (supported_opaque) because the backend is the schema and digest
+    # authority for it. Absent on older backends.
+    actuation: dict[str, Any] | None = None
+    # True when this response replays an already-admitted command (idempotent
+    # retry). Older backends omit the field, which means first application.
+    duplicate: bool = False
 
 
 class InternAsyncEvent(_StrictContract):
@@ -954,6 +973,51 @@ class InternAsyncEventPage(_StrictContract):
     next_sequence: int = Field(ge=0)
 
 
+class InternAcceptanceFixtureRequest(_StrictContract):
+    """Bootstrap one disposable Factory/Project/Effort/Run acceptance fixture.
+
+    No tribal ids: the backend provisions the whole chain from the named task
+    template and binds the organization Intern to it. Idempotent within one
+    test attempt via ``idempotency_key``.
+    """
+
+    idempotency_key: str = Field(min_length=1, max_length=180)
+    task_template: str = Field(default="acceptance_default", min_length=1, max_length=128)
+    # A fixture Run is an inert, pre-terminalized row that satisfies binding
+    # validation without dispatching compute. Disable for chain-only fixtures.
+    include_run: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InternAcceptanceFixtureResource(_StrictContract):
+    resource_kind: str
+    resource_id: str | None = None
+    status: str
+    error_code: str | None = None
+
+
+class InternAcceptanceFixtureReceipt(_StrictContract):
+    """Durable, validator-readable evidence for one acceptance fixture."""
+
+    schema_version: Literal["smr.intern-acceptance-fixture.v1"]
+    fixture_id: str
+    org_id: str
+    research_intern_id: str
+    task_template: str
+    status: Literal["ready", "torn_down"]
+    binding: InternRuntimeBinding
+    resources: tuple[InternAcceptanceFixtureResource, ...] = ()
+    # Backend factory_binding_readiness report; opaque because the backend is
+    # the readiness authority and its report shape is advisory evidence.
+    factory_readiness: dict[str, Any] = Field(default_factory=dict)
+    replayed: bool = False
+    created_at: datetime
+    torn_down_at: datetime | None = None
+    # Evidence stays readable until this instant; teardown never destroys it
+    # before the validation window ends.
+    retention_expires_at: datetime | None = None
+
+
 class ResearchInternFactoryMembershipResponse(_StrictContract):
     research_intern_id: str
     org_id: str
@@ -1558,6 +1622,9 @@ __all__ = [
     "DatasetRevisionCreateRequest",
     "DatasetRevisionLifecycleRequest",
     "DatasetRevisionResponse",
+    "InternAcceptanceFixtureReceipt",
+    "InternAcceptanceFixtureRequest",
+    "InternAcceptanceFixtureResource",
     "InternAsyncBlocker",
     "InternAsyncCheckpoint",
     "InternAsyncCommandKind",

{synth_ai-0.18.2.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/research/contracts/run_launch.py

@@ -6,7 +6,7 @@ from collections.abc import AsyncIterable, AsyncIterator, Iterable, Iterator, Ma
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import StrEnum
-from typing import Self, TypeAlias
+from typing import Literal, Self, TypeAlias
 
 from synth_ai.sdk.research.contracts.actor_images import (
     ActorImageBinding,
@@ -238,6 +238,14 @@ class RunLaunchRequest(CommandRequest):
     dev_environment_id: str | None = None
     run_policy: SmrRunPolicy | WireMapping | None = None
     kickoff_contract: KickoffContract | WireMapping | None = None
+    # Sealed-run provenance: one resolved deployment receipt per participating
+    # repository, and the posture that governs them. The backend provenance
+    # authority validates and digest-stamps the pins ('live' refuses
+    # placeholder pins and unprovisioned trace stores with typed 422s), so the
+    # SDK passes them through opaquely and only checks shape and the mode
+    # vocabulary client-side.
+    deployment_pins: Sequence[WireMapping] | None = None
+    provenance_mode: Literal["live", "dry_run"] | str | None = None
     resource_bindings: RunResourceBindings | WireMapping | None = None
     evidence_obligations: EvidenceObligations | WireMapping | None = None
     ai_cache: WireMapping | None = None
@@ -271,6 +279,8 @@ class RunLaunchRequest(CommandRequest):
         )
         _validate_launch_text(self.idempotency_key, field_name="idempotency_key")
         _validate_positive_int(self.timebox_seconds, field_name="timebox_seconds")
+        if self.provenance_mode is not None and self.provenance_mode not in ("live", "dry_run"):
+            raise ValueError("provenance_mode must be 'live' or 'dry_run'")
         _validate_launch_sequences(self)
         _validate_launch_mappings(self)
         _validate_launch_combinations(self)
@@ -316,6 +326,8 @@ class RunLaunchRequest(CommandRequest):
             workflow=self.workflow,
             run_policy=self.run_policy,
             kickoff_contract=self.kickoff_contract,
+            deployment_pins=tuple(self.deployment_pins) if self.deployment_pins else None,
+            provenance_mode=self.provenance_mode,
             resource_bindings=self.resource_bindings,
             evidence_obligations=self._evidence_obligations_payload(),
             dev_environment_id=self.dev_environment_id,
@@ -1240,6 +1252,8 @@ def _validate_launch_sequences(request: RunLaunchRequest) -> None:
             raise ValueError(f"actor_model_overrides[{index}] must be an actor model assignment")
     for index, spec in enumerate(request.required_work_products or ()):
         _require_mapping(spec, label=f"required_work_products[{index}]")
+    for index, pin in enumerate(request.deployment_pins or ()):
+        _require_mapping(pin, label=f"deployment_pins[{index}]")
 
 
 def _validate_launch_mappings(request: RunLaunchRequest) -> None:

{synth_ai-0.18.2.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/research/contracts/traces.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from datetime import datetime
 from enum import StrEnum
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
@@ -351,6 +351,50 @@ class TraceStoreProvisionResult(_TraceContract):
     receipt: TraceStoreLifecycleReceipt
 
 
+# The preflight trio keeps the backend contract names verbatim (unlike the
+# older abridged names above) because the response and identity block are
+# schema-versioned envelopes that sealed runners embed and re-verify by name.
+
+
+class TraceStorePreflightRequest(_TraceContract):
+    """Pre-launch trace-store readiness gate for a sealed run."""
+
+    catalog_provider: TraceCatalogProvider = TraceCatalogProvider.NONE
+    provision_if_missing: bool = True
+
+
+class TraceStoreRunEnvelopeIdentity(_TraceContract):
+    """Trace-store identity carried inside a sealed-run envelope.
+
+    Sealed runners embed exactly this block (as ``trace_store``) in the run
+    envelope so trace-inventory collection after grading can never 404 on an
+    unprovisioned or ambiguous store.
+    """
+
+    schema_version: Literal["synth.trace-store-run-envelope-identity.v1"]
+    trace_store_id: str
+    org_id: str
+    factory_id: str
+    blob_bucket: str
+    blob_prefix: str
+    catalog_provider: TraceCatalogProvider
+    catalog_database_name: str | None = None
+    provisioning_status: TraceStoreProvisioningStatus
+    provisioning_version: int
+
+
+class TraceStorePreflightResponse(_TraceContract):
+    """Typed provision-and-health result gating sealed-run launch."""
+
+    schema_version: Literal["synth.trace-store-preflight.v1"]
+    healthy: bool
+    provisioned: Literal["existing", "created"]
+    descriptor: TraceStoreDescriptor
+    run_envelope_identity: TraceStoreRunEnvelopeIdentity
+    health_conditions: list[str] = Field(default_factory=list)
+    checked_at: datetime
+
+
 __all__ = [
     "TraceBundleDownload",
     "TraceBundleDownloadObject",
@@ -372,8 +416,11 @@ __all__ = [
     "TraceStoreAccessReceipt",
     "TraceStoreDescriptor",
     "TraceStoreLifecycleReceipt",
+    "TraceStorePreflightRequest",
+    "TraceStorePreflightResponse",
     "TraceStoreProvisionResult",
     "TraceStoreProvisioningStatus",
+    "TraceStoreRunEnvelopeIdentity",
     "validate_optional_sha256_digest",
     "validate_sha256_digest",
     "validate_sha256_digest_list",

{synth_ai-0.18.2.dev615 → synth_ai-0.18.2.dev617}/synth_ai/sdk/research/errors.py

@@ -317,6 +317,70 @@ class ResearchStructuredDenialError(ResearchApiError):
         self.detail = dict(detail) if detail else {}
 
 
+class ResearchNotFoundError(ResearchStructuredDenialError):
+    """Raised when the backend reports a typed ``*_not_found`` condition (HTTP 404).
+
+    The backend scopes every Research Intern lookup to the organization bound
+    to the caller's API key, so a 404 only proves the resource is absent *for
+    that organization* -- it never proves global absence. Release evidence must
+    be able to distinguish a genuine miss from a wrong-organization lookup, so
+    this error preserves the backend's typed condition instead of collapsing it
+    into an opaque denial:
+
+    - ``backend_error_code``: the exact backend condition, for example
+      ``intern_async_runtime_not_found``, ``intern_sync_session_not_found``,
+      or a retention condition such as
+      ``intern_async_runtime_retention_expired`` /
+      ``intern_acceptance_fixture_retention_expired`` (the resource existed;
+      its read-only retention window ended). (Named to avoid shadowing the
+      read-only ``SynthError.error_code`` transport-failure property.)
+    - ``resource``: the resource segment of the condition (``async_runtime``,
+      ``sync_session``, ``acceptance_fixture``, ...), or ``None`` when the
+      code has neither the ``intern_*_not_found`` nor the
+      ``intern_*_retention_expired`` shape.
+    - ``scope_identifier``: the lookup key the backend echoed back (the
+      organization id for org-singleton lookups such as the Async Intern, the
+      resource id otherwise), when the backend provided one.
+
+    Evidence that records ``backend_error_code`` + ``scope_identifier`` next to
+    the caller's organization binding can attribute the miss: a not-found under
+    the expected organization is a true absence for that organization, while a
+    mismatch between the expected resource's organization and the caller's
+    binding identifies a wrong-organization lookup.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_text: str | None = None,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            response_text=response_text,
+            detail=detail,
+        )
+        code = self.detail.get("error_code")
+        self.backend_error_code: str = code.strip() if isinstance(code, str) else ""
+        resource: str | None = None
+        if self.backend_error_code.startswith("intern_"):
+            for suffix in ("_not_found", "_retention_expired"):
+                if self.backend_error_code.endswith(suffix):
+                    resource = self.backend_error_code.removeprefix("intern_").removesuffix(suffix)
+                    break
+        self.resource: str | None = resource
+        scope: str | None = None
+        for key in ("runtime_id", "resource_id", "fixture_id", "async_runtime_id", "org_id"):
+            value = self.detail.get(key)
+            if isinstance(value, str) and value.strip():
+                scope = value.strip()
+                break
+        self.scope_identifier: str | None = scope
+
+
 class ResearchLimitExtensionError(ResearchApiError):
     """Base class for durable run-limit extension refusals."""
 
@@ -569,6 +633,7 @@ __all__ = [
     "ResearchLimitExtensionIdempotencyConflictError",
     "ResearchLimitRevisionConflictError",
     "ResearchManagedInferenceUnavailableError",
+    "ResearchNotFoundError",
     "ResearchOperationError",
     "ResearchProjectMonthlyBudgetExhaustedError",
     "ResearchStructuredDenialError",