synth-ai 0.22.2.dev688__tar.gz → 0.22.2.dev690__tar.gz

{synth_ai-0.22.2.dev688/synth_ai.egg-info → synth_ai-0.22.2.dev690}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev688
+Version: 0.22.2.dev690
 Summary: Python SDK, CLI and MCP servers for Synth Index search and Swarms
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT

{synth_ai-0.22.2.dev688 → synth_ai-0.22.2.dev690}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.22.2.dev688"
+version = "0.22.2.dev690"
 description = "Python SDK, CLI and MCP servers for Synth Index search and Swarms"
 keywords = ["synth", "index", "search", "citations", "research", "swarms", "mcp", "sdk"]
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]

{synth_ai-0.22.2.dev688 → synth_ai-0.22.2.dev690}/synth_ai/core/http/async_transport.py

@@ -38,12 +38,13 @@ class AsyncHttpTransport:
     """One native async transport for JSON, bytes, and SSE operations."""
 
     base_url: str
-    headers: Mapping[str, str]
+    headers: Mapping[str, str] = field(repr=False)
     timeout_seconds: float = 30.0
     retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
     error_handler: ErrorHandler = raise_http_error
     exception_handler: ExceptionHandler = raise_transport_exception
     decode_error_handler: DecodeErrorHandler = raise_json_decode_error
+    follow_redirects: bool = True
     client: httpx.AsyncClient = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
@@ -52,7 +53,7 @@ class AsyncHttpTransport:
             headers=dict(self.headers),
             timeout=self.timeout_seconds,
             limits=httpx.Limits(max_keepalive_connections=0),
-            follow_redirects=True,
+            follow_redirects=self.follow_redirects,
         )
 
     async def close(self) -> None:

synth_ai-0.22.2.dev690/synth_ai/core/http/retry.py

@@ -0,0 +1,302 @@
+"""Classified retry policy shared by sync and async transports.
+
+# See: testing/specifications/sdk/core_research_migration.md
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from synth_ai.core.errors import (
+    ContractMismatchError,
+    RetryDirective,
+    RuntimeUnavailableError,
+    SynthError,
+    SynthErrorCategory,
+    SynthErrorCode,
+    SynthFailure,
+)
+from synth_ai.core.http.request import HttpMethod, HttpRequest, OperationMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    attempts_max: int = 3
+    delay_seconds_initial: float = 0.5
+    delay_seconds_max: float = 5.0
+    retry_statuses: frozenset[int] = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.attempts_max, bool)
+            or not isinstance(self.attempts_max, int)
+            or not 1 <= self.attempts_max <= 100
+        ):
+            raise ValueError("attempts_max must be an integer from 1 through 100")
+        for delay in (self.delay_seconds_initial, self.delay_seconds_max):
+            if (
+                isinstance(delay, bool)
+                or not isinstance(delay, (int, float))
+                or not math.isfinite(delay)
+            ):
+                raise ValueError("retry delays must be finite numbers")
+        if self.delay_seconds_initial < 0 or self.delay_seconds_max < 0:
+            raise ValueError("retry delays must be non-negative")
+        if self.delay_seconds_initial > self.delay_seconds_max:
+            raise ValueError("delay_seconds_initial cannot exceed delay_seconds_max")
+
+    def permits(
+        self,
+        operation: OperationMetadata,
+        *,
+        idempotency_key: str | None,
+    ) -> bool:
+        """Retry only metadata-declared idempotent operations.
+
+        Unsafe methods additionally require an idempotency key.
+        """
+        if not operation.idempotent:
+            return False
+        if operation.method is HttpMethod.GET:
+            return True
+        return bool(idempotency_key)
+
+    def delay_seconds(
+        self,
+        attempt_index: int,
+        *,
+        retry_after_seconds: float | None,
+    ) -> float:
+        """Deterministic exponential backoff capped by policy and Retry-After."""
+        if attempt_index < 0:
+            raise ValueError("attempt_index must be non-negative")
+        exponential = min(
+            self.delay_seconds_max,
+            self.delay_seconds_initial * (2**attempt_index),
+        )
+        if retry_after_seconds is None:
+            return exponential
+        if not math.isfinite(retry_after_seconds) or retry_after_seconds < 0:
+            raise ValueError("retry_after_seconds must be non-negative")
+        return min(self.delay_seconds_max, max(exponential, retry_after_seconds))
+
+
+def idempotency_key_from_request(request: HttpRequest) -> str | None:
+    """Extract an idempotency key from headers or JSON body fields."""
+    values = [value for name, value in request.headers.items() if name.lower() == "idempotency-key"]
+    if isinstance(request.body, dict):
+        values.extend(
+            request.body[name]
+            for name in ("idempotency_key", "idempotency_key_run_create")
+            if name in request.body
+        )
+    identities = set()
+    for value in values:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("idempotency identity must be a non-empty string")
+        identities.add(value)
+    if len(identities) > 1:
+        raise ValueError("request contains conflicting idempotency identities")
+    return next(iter(identities), None)
+
+
+def should_retry_failure(
+    policy: RetryPolicy,
+    request: HttpRequest,
+    error: BaseException,
+) -> bool:
+    """Decide whether one failed execute attempt may be retried."""
+    if isinstance(error, (ContractMismatchError, RuntimeUnavailableError)):
+        return False
+    if not policy.permits(
+        request.operation,
+        idempotency_key=idempotency_key_from_request(request),
+    ):
+        return False
+    if isinstance(error, SynthError):
+        if error.failure is not None:
+            # The first-class directive is authoritative, including an explicit false.
+            return error.failure.retry.retryable
+        if error.retryable:
+            return True
+        status = None
+        if error.failure is not None:
+            status = error.failure.status
+        if status is None and hasattr(error, "status"):
+            status = error.status
+        return isinstance(status, int) and status in policy.retry_statuses
+    return False
+
+
+def retry_after_from_error(error: BaseException) -> float | None:
+    if isinstance(error, SynthError):
+        return error.retry_after_seconds
+    return None
+
+
+# Backend ``core/data/db/backpressure_classification.py::DB_BACKPRESSURE_REASON_CODE``,
+# emitted as ``error_code`` by ``core/data/db/admission.py::db_backpressure_payload``.
+DB_BACKPRESSURE_ERROR_CODE = "db_backpressure"
+DB_BACKPRESSURE_RETRY_EXHAUSTED_CODE = "db_backpressure_retry_exhausted"
+_REPLAY_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+@dataclass(frozen=True, slots=True)
+class DbBackpressureRefusal:
+    """One typed DB backpressure refusal decoded from a backend error body."""
+
+    status: int
+    error_code: str
+    component: str | None
+    work_class: str | None
+    retry_after_seconds: float | None
+    operator_action: str | None
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class DbBackpressureRetryPolicy:
+    """Bounds for replaying a request the backend shed before starting DB work.
+
+    Attempts and total sleep are both bounded; the server's ``retry_after`` is
+    honored up to ``retry_after_cap_seconds`` and only ever lengthened by jitter.
+    """
+
+    attempts_max: int = 5
+    total_wait_seconds_max: float = 120.0
+    retry_after_cap_seconds: float = 30.0
+    delay_seconds_initial: float = 1.0
+    jitter_ratio: float = 0.25
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.attempts_max, bool)
+            or not isinstance(self.attempts_max, int)
+            or not 1 <= self.attempts_max <= 20
+        ):
+            raise ValueError("attempts_max must be an integer from 1 through 20")
+        for name in (
+            "total_wait_seconds_max",
+            "retry_after_cap_seconds",
+            "delay_seconds_initial",
+            "jitter_ratio",
+        ):
+            value = getattr(self, name)
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(value)
+                or value < 0
+            ):
+                raise ValueError(f"{name} must be a finite non-negative number")
+        if self.jitter_ratio > 1:
+            raise ValueError("jitter_ratio cannot exceed 1")
+
+    def next_delay_seconds(
+        self,
+        *,
+        attempts_made: int,
+        waited_seconds: float,
+        refusal: DbBackpressureRefusal,
+        rng: random.Random,
+    ) -> float | None:
+        """Return the sleep before the next attempt, or None when bounds are spent."""
+        if attempts_made >= self.attempts_max:
+            return None
+        if refusal.retry_after_seconds is not None:
+            base = min(self.retry_after_cap_seconds, refusal.retry_after_seconds)
+        else:
+            base = min(
+                self.retry_after_cap_seconds,
+                self.delay_seconds_initial * (2 ** (attempts_made - 1)),
+            )
+        delay = base * (1.0 + rng.uniform(0.0, self.jitter_ratio))
+        if waited_seconds + delay > self.total_wait_seconds_max:
+            return None
+        return delay
+
+
+def request_permits_replay(method: str, headers: Mapping[str, str]) -> bool:
+    """A request may be replayed only when safe by method or carrying an idempotency key."""
+    if method.upper() in _REPLAY_SAFE_METHODS:
+        return True
+    return any(
+        name.lower() == "idempotency-key" and bool(str(value).strip())
+        for name, value in headers.items()
+    )
+
+
+class DbBackpressureRetryExhaustedError(SynthError):
+    """The backend kept shedding DB work past the retry bounds.
+
+    Carries the last refusal's ``component``, ``work_class`` and ``retry_after``.
+    Not retryable again: callers already spent the bounded budget.
+    """
+
+    def __init__(
+        self,
+        *,
+        method: str,
+        path: str,
+        operation_id: str | None,
+        refusal: DbBackpressureRefusal,
+        attempts: int,
+        waited_seconds: float,
+    ) -> None:
+        self.method = method
+        self.path = path
+        self.refusal = refusal
+        self.attempts = attempts
+        self.waited_seconds = waited_seconds
+        detail = (
+            f"{method} {path}: backend refused DB work ({refusal.error_code}) on "
+            f"{attempts} attempts over {waited_seconds:.1f}s; last component="
+            f"{refusal.component} work_class={refusal.work_class} "
+            f"retry_after={refusal.retry_after_seconds} status={refusal.status} "
+            f"operator_action={refusal.operator_action}"
+        )
+        super().__init__(
+            detail,
+            failure=SynthFailure(
+                code=SynthErrorCode(DB_BACKPRESSURE_RETRY_EXHAUSTED_CODE),
+                category=SynthErrorCategory.TRANSIENT_SERVICE,
+                operation=operation_id,
+                request_id=None,
+                correlation_id=None,
+                retry=RetryDirective(
+                    retryable=False,
+                    retry_after_seconds=refusal.retry_after_seconds,
+                ),
+                status=refusal.status,
+                detail=detail,
+                reason=refusal.component,
+            ),
+        )
+
+    @property
+    def component(self) -> str | None:
+        return self.refusal.component
+
+    @property
+    def work_class(self) -> str | None:
+        return self.refusal.work_class
+
+    @property
+    def retry_after_seconds(self) -> float | None:
+        return self.refusal.retry_after_seconds
+
+
+__all__ = [
+    "DB_BACKPRESSURE_ERROR_CODE",
+    "DbBackpressureRefusal",
+    "DbBackpressureRetryExhaustedError",
+    "DbBackpressureRetryPolicy",
+    "request_permits_replay",
+    "RetryPolicy",
+    "idempotency_key_from_request",
+    "retry_after_from_error",
+    "should_retry_failure",
+]

{synth_ai-0.22.2.dev688 → synth_ai-0.22.2.dev690}/synth_ai/core/http/transport.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import math
+import random
 import time
 from collections.abc import Callable, Iterator, Mapping
 from dataclasses import dataclass, field
@@ -37,7 +38,12 @@ from synth_ai.core.errors import (
 )
 from synth_ai.core.http.request import HttpRequest
 from synth_ai.core.http.retry import (
+    DB_BACKPRESSURE_ERROR_CODE,
+    DbBackpressureRefusal,
+    DbBackpressureRetryExhaustedError,
+    DbBackpressureRetryPolicy,
     RetryPolicy,
+    request_permits_replay,
     retry_after_from_error,
     should_retry_failure,
 )
@@ -118,7 +124,7 @@ def _declares_runtime_unavailable(decoded: JsonValue | None) -> bool:
         return False
     nested = decoded.get("detail")
     return any(
-        source.get(key) in RUNTIME_UNAVAILABLE_CODES
+        isinstance(source.get(key), str) and source.get(key) in RUNTIME_UNAVAILABLE_CODES
         for source in (nested, decoded)
         if isinstance(source, dict)
         for key in ("error_code", "code", "error")
@@ -206,6 +212,37 @@ SEARCH_ID_HEADER = "x-synth-search-id"
 SEARCH_RESOURCE_KIND = "index_search"
 
 
+def db_backpressure_refusal(response: httpx.Response) -> DbBackpressureRefusal | None:
+    """Decode the backend's typed DB backpressure refusal, or None for any other error."""
+    if response.status_code not in {429, 503}:
+        return None
+    try:
+        decoded = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(decoded, dict):
+        return None
+    detail = decoded.get("detail")
+    body = detail if isinstance(detail, dict) else decoded
+    if DB_BACKPRESSURE_ERROR_CODE not in (body.get("error_code"), body.get("failure_class")):
+        return None
+
+    def text(key: str) -> str | None:
+        value = body.get(key)
+        return value if isinstance(value, str) and value.strip() else None
+
+    retry_after = _retry_after_seconds(response, sources=(cast(JsonObject, body),))
+    return DbBackpressureRefusal(
+        status=response.status_code,
+        error_code=DB_BACKPRESSURE_ERROR_CODE,
+        component=text("component"),
+        work_class=text("work_class"),
+        retry_after_seconds=retry_after,
+        operator_action=text("operator_action"),
+        message=text("message") or "database work rejected before starting",
+    )
+
+
 def _created_search(
     response: httpx.Response, sources: tuple[JsonObject, ...]
 ) -> ResourceRef | None:
@@ -388,12 +425,19 @@ class HttpTransport:
     """One strict sync transport for JSON, bytes, and SSE operations."""
 
     base_url: str
-    headers: Mapping[str, str]
+    headers: Mapping[str, str] = field(repr=False)
     timeout_seconds: float = 30.0
     retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
     error_handler: ErrorHandler = raise_http_error
     exception_handler: ExceptionHandler = raise_transport_exception
     decode_error_handler: DecodeErrorHandler = raise_json_decode_error
+    follow_redirects: bool = True
+    db_backpressure_policy: DbBackpressureRetryPolicy = field(
+        default_factory=DbBackpressureRetryPolicy
+    )
+    sleep: Callable[[float], None] = time.sleep
+    monotonic: Callable[[], float] = time.monotonic
+    rng: random.Random = field(default_factory=random.Random, repr=False)
     client: httpx.Client = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
@@ -402,7 +446,7 @@ class HttpTransport:
             headers=dict(self.headers),
             timeout=self.timeout_seconds,
             limits=httpx.Limits(max_keepalive_connections=0),
-            follow_redirects=True,
+            follow_redirects=self.follow_redirects,
         )
 
     def close(self) -> None:
@@ -420,19 +464,44 @@ class HttpTransport:
         timeout_seconds: float | None = None,
         operation_id: str | None = None,
     ) -> JsonValue:
-        try:
-            response = self.client.request(
-                method,
-                path,
-                params=cast(Any, params),
-                json=json_body,
-                headers=headers,
-                timeout=self.timeout_seconds if timeout_seconds is None else timeout_seconds,
+        replay_safe = request_permits_replay(method, {**self.headers, **(headers or {})})
+        attempts = 0
+        waited_seconds = 0.0
+        while True:
+            try:
+                response = self.client.request(
+                    method,
+                    path,
+                    params=cast(Any, params),
+                    json=json_body,
+                    headers=headers,
+                    timeout=self.timeout_seconds if timeout_seconds is None else timeout_seconds,
+                )
+            except httpx.TimeoutException as exc:
+                self.exception_handler(method, path, exc, operation_id)
+            except httpx.TransportError as exc:
+                self.exception_handler(method, path, exc, operation_id)
+            attempts += 1
+            refusal = db_backpressure_refusal(response) if replay_safe else None
+            if refusal is None:
+                break
+            delay = self.db_backpressure_policy.next_delay_seconds(
+                attempts_made=attempts,
+                waited_seconds=waited_seconds,
+                refusal=refusal,
+                rng=self.rng,
             )
-        except httpx.TimeoutException as exc:
-            self.exception_handler(method, path, exc, operation_id)
-        except httpx.TransportError as exc:
-            self.exception_handler(method, path, exc, operation_id)
+            if delay is None:
+                raise DbBackpressureRetryExhaustedError(
+                    method=method,
+                    path=path,
+                    operation_id=operation_id,
+                    refusal=refusal,
+                    attempts=attempts,
+                    waited_seconds=waited_seconds,
+                )
+            self.sleep(delay)
+            waited_seconds += delay
         if allow_not_found and response.status_code == 404:
             return None
         if response.is_error:
@@ -598,6 +667,7 @@ class HttpTransport:
 
 
 __all__ = [
+    "db_backpressure_refusal",
     "ErrorHandler",
     "ExceptionHandler",
     "DecodeErrorHandler",

{synth_ai-0.22.2.dev688 → synth_ai-0.22.2.dev690}/synth_ai/mcp/research/tools/__init__.py

@@ -7,6 +7,7 @@ from synth_ai.mcp.research.tools.factories import build_factory_tools
 from synth_ai.mcp.research.tools.files import build_file_tools
 from synth_ai.mcp.research.tools.image_releases import build_image_release_tools
 from synth_ai.mcp.research.tools.intern_program import build_intern_program_tools
+from synth_ai.mcp.research.tools.local_files import SelectedFileReader
 from synth_ai.mcp.research.tools.models import build_model_tools
 from synth_ai.mcp.research.tools.outputs import build_output_tools
 from synth_ai.mcp.research.tools.progress import build_progress_tools
@@ -21,6 +22,7 @@ from synth_ai.mcp.research.tools.visuals import build_visual_tools
 from synth_ai.mcp.research.tools.workspace_inputs import build_workspace_input_tools
 
 __all__ = [
+    "SelectedFileReader",
     "build_dataset_tools",
     "build_environment_tools",
     "build_export_tools",

synth_ai-0.22.2.dev690/synth_ai/sdk/research/__init__.py

@@ -0,0 +1,69 @@
+"""Dependency-clean implementation of the public Synth Research SDK."""
+
+from synth_ai.sdk.research.client import AsyncClient, Client
+from synth_ai.sdk.research.contracts.resource_reads import (
+    DataPoolReadReference,
+    DatasetRevisionReadReference,
+    ProjectDataPoolDescriptor,
+    ProjectDataPoolInventory,
+)
+from synth_ai.sdk.research.facade import ResearchClient
+from synth_ai.sdk.research.hierarchy import AsyncHierarchyClient, HierarchyClient
+from synth_ai.sdk.research.hierarchy_models import (
+    EntityKey,
+    HierarchyCommand,
+    HierarchyOriginal,
+    HierarchyRead,
+    HierarchyScope,
+)
+from synth_ai.sdk.research.operations import RESEARCH_OPERATIONS, research_operation
+from synth_ai.sdk.research.owner_reads import (
+    AsyncOwnerReadClient,
+    OwnerReadAccess,
+    OwnerReadAccessExpired,
+    OwnerReadAccessExpiredError,
+    OwnerReadClient,
+    OwnerReadScope,
+)
+from synth_ai.sdk.research.planning_reads import (
+    AsyncPlanningReads,
+    PlanningGraphRead,
+    PlanningReadPosition,
+    PlanningReads,
+    PlanningTaskPage,
+    PlanningTaskRead,
+)
+
+AsyncResearchClient = AsyncClient
+
+__all__ = [
+    "AsyncHierarchyClient",
+    "HierarchyClient",
+    "HierarchyScope",
+    "HierarchyCommand",
+    "HierarchyRead",
+    "HierarchyOriginal",
+    "EntityKey",
+    "AsyncClient",
+    "AsyncResearchClient",
+    "AsyncOwnerReadClient",
+    "AsyncPlanningReads",
+    "Client",
+    "DataPoolReadReference",
+    "DatasetRevisionReadReference",
+    "ProjectDataPoolDescriptor",
+    "ProjectDataPoolInventory",
+    "OwnerReadAccess",
+    "OwnerReadAccessExpired",
+    "OwnerReadAccessExpiredError",
+    "OwnerReadClient",
+    "OwnerReadScope",
+    "PlanningGraphRead",
+    "PlanningReadPosition",
+    "PlanningReads",
+    "PlanningTaskPage",
+    "PlanningTaskRead",
+    "RESEARCH_OPERATIONS",
+    "ResearchClient",
+    "research_operation",
+]

{synth_ai-0.22.2.dev688 → synth_ai-0.22.2.dev690}/synth_ai/sdk/research/advanced_swarms.py

@@ -46,6 +46,16 @@ class _ResearchSession(Protocol):
 
     def run(self, project_id: str, run_id: str) -> _RunHandle: ...
 
+    def get_run_results(self, project_id: str, run_id: str) -> dict[str, Any]: ...
+
+    def get_run_logs(
+        self, project_id: str, run_id: str, *, limit: int | None = None, cursor: str | None = None
+    ) -> dict[str, Any]: ...
+
+    def get_run_execution(self, project_id: str, run_id: str, **kwargs: Any) -> Any: ...
+
+    def get_run_orchestrator(self, project_id: str, run_id: str) -> dict[str, Any]: ...
+
 
 def _session_project(project: ProjectSelector | str | None) -> str | None:
     if isinstance(project, ProjectSelector):
@@ -588,13 +598,16 @@ class ResearchRunsAPI:
         from synth_ai.sdk.pagination import page_from_wire
 
         payload = self.logs(project_id, run_id, limit=limit, cursor=cursor)
+        if isinstance(payload, dict) and "items" not in payload and "data" not in payload:
+            for field_name in ("entries", "logs", "records"):
+                if field_name in payload:
+                    payload = {
+                        "items": payload[field_name],
+                        "next_cursor": payload.get("next_cursor"),
+                        "has_more": payload.get("has_more", False),
+                    }
+                    break
         raw_items, next_cursor, has_more = page_from_wire(payload)
-        if isinstance(payload, dict) and isinstance(payload.get("entries"), list):
-            raw_items = payload["entries"]
-        elif isinstance(payload, dict) and isinstance(payload.get("logs"), list):
-            raw_items = payload["logs"]
-        elif isinstance(payload, dict) and isinstance(payload.get("records"), list):
-            raw_items = payload["records"]
         normalized = [cast(dict[str, Any], item) for item in raw_items if isinstance(item, dict)]
         return SyncPage(items=normalized, next_cursor=next_cursor, has_more=has_more)