synth-ai 0.22.2.dev691__tar.gz → 0.22.2.dev692__tar.gz

{synth_ai-0.22.2.dev691/synth_ai.egg-info → synth_ai-0.22.2.dev692}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev691
+Version: 0.22.2.dev692
 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.dev691 → synth_ai-0.22.2.dev692}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.22.2.dev691"
+version = "0.22.2.dev692"
 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.dev692/synth_ai/core/contracts/rate_limits.py

@@ -0,0 +1,64 @@
+"""Per-response rate capacity; see testing/specifications/sdk/rate_limits.md.
+
+Only recognized, bounded numeric/ISO fields are retained. Response cookies,
+authorization, and unrelated headers never enter logs or exception metadata.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitSnapshot:
+    dimension: str
+    limit: int | None
+    remaining: int | None
+    reset_at: str | None
+    burst: int | None = None
+
+
+def parse_rate_limits(headers: Mapping[str, str]) -> tuple[RateLimitSnapshot, ...]:
+    normalized = {name.lower(): value for name, value in headers.items()}
+    result = []
+    for dimension in ("requests", "concurrency", "tokens", "spend-cents"):
+
+        def count(kind: str, dimension: str = dimension) -> int | None:
+            raw = normalized.get(f"x-ratelimit-{kind}-{dimension}", "")
+            return (
+                int(raw)
+                if raw.isascii() and raw.isdigit() and len(raw) <= 16 and int(raw) <= 2**53 - 1
+                else None
+            )
+
+        limit, remaining, burst = count("limit"), count("remaining"), count("burst")
+        reset = normalized.get(f"x-ratelimit-reset-{dimension}")
+        if reset is not None:
+            try:
+                if (
+                    len(reset) > 64
+                    or datetime.fromisoformat(reset.replace("Z", "+00:00")).tzinfo is None
+                ):
+                    reset = None
+            except ValueError:
+                reset = None
+        if limit is not None or remaining is not None or reset is not None or burst is not None:
+            result.append(RateLimitSnapshot(dimension, limit, remaining, reset, burst))
+    return tuple(result)
+
+
+@dataclass(slots=True)
+class ResponseMetadata:
+    """Caller-owned metadata for one request; safe for concurrent transports.
+
+    Pass a distinct instance per concurrent request. Metadata is replaced on
+    each response, so a later response without rate headers cannot reuse old
+    capacity. JSON/result wire contracts remain unchanged.
+    """
+
+    rate_limits: tuple[RateLimitSnapshot, ...] = ()
+
+    def capture(self, headers: Mapping[str, str]) -> None:
+        self.rate_limits = parse_rate_limits(headers)

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/core/errors.py

@@ -13,6 +13,8 @@ from dataclasses import dataclass
 from enum import StrEnum
 from typing import Any
 
+from synth_ai.core.contracts.rate_limits import RateLimitSnapshot
+
 HTTP_ERROR_BODY_CAPTURE_CHARS_MAX = 8192
 _DISPLAY_MESSAGE_CHARS_MAX = 4096
 _DISPLAY_BODY_CHARS_MAX = 4096
@@ -94,6 +96,7 @@ class SynthFailure:
     # Server-declared sub-cause of ``code`` (for example ``daily_spend_cap``
     # inside ``index_rate_limited``). Stable vocabulary owned by the backend.
     reason: str | None = None
+    rate_limits: tuple[RateLimitSnapshot, ...] = ()
 
 
 class SynthError(Exception):
@@ -138,6 +141,11 @@ class SynthError(Exception):
         """Server-declared sub-cause of the error code, when one was sent."""
         return self.failure.reason if self.failure is not None else None
 
+    @property
+    def rate_limits(self) -> tuple[RateLimitSnapshot, ...]:
+        """Recognized rate-capacity metadata from this failed response."""
+        return self.failure.rate_limits if self.failure is not None else ()
+
     @property
     def resource(self) -> ResourceRef | None:
         """Resource the failed operation already created or addressed, if named."""
@@ -187,6 +195,12 @@ class HTTPError(SynthError):
         if self.body_snippet:
             body = _safe_error_display(self.body_snippet, limit=_DISPLAY_BODY_CHARS_MAX)
             base += f" | body_excerpt={body}"
+        if self.rate_limits:
+            limits = "; ".join(
+                f"{item.dimension} remaining={item.remaining} limit={item.limit}"
+                for item in self.rate_limits
+            )
+            base += f" | rate_limits={limits}"
         return base
 
 

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/core/http/__init__.py

@@ -1,5 +1,6 @@
 """Shared sync and async HTTP operation substrate."""
 
+from synth_ai.core.contracts.rate_limits import RateLimitSnapshot, ResponseMetadata
 from synth_ai.core.http.async_transport import AsyncHttpTransport
 from synth_ai.core.http.request import HttpMethod, HttpRequest, OperationId, OperationMetadata
 from synth_ai.core.http.retry import RetryPolicy
@@ -14,6 +15,8 @@ __all__ = [
     "OperationId",
     "OperationMetadata",
     "RetryPolicy",
+    "RateLimitSnapshot",
+    "ResponseMetadata",
     "SseEvent",
     "iter_sse_events",
 ]

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/core/http/async_transport.py

@@ -14,6 +14,7 @@ from typing import Any, cast
 import httpx
 
 from synth_ai.core.contracts.json_value import JsonObject, JsonValue
+from synth_ai.core.contracts.rate_limits import ResponseMetadata
 from synth_ai.core.http.request import HttpRequest
 from synth_ai.core.http.retry import (
     RetryPolicy,
@@ -70,7 +71,10 @@ class AsyncHttpTransport:
         allow_not_found: bool = False,
         timeout_seconds: float | None = None,
         operation_id: str | None = None,
+        response_metadata: ResponseMetadata | None = None,
     ) -> JsonValue:
+        if response_metadata is not None:
+            response_metadata.rate_limits = ()
         try:
             response = await self.client.request(
                 method,
@@ -84,6 +88,8 @@ class AsyncHttpTransport:
             self.exception_handler(method, path, exc, operation_id)
         except httpx.TransportError as exc:
             self.exception_handler(method, path, exc, operation_id)
+        if response_metadata is not None:
+            response_metadata.capture(response.headers)
         if allow_not_found and response.status_code == 404:
             return None
         if response.is_error:

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/core/http/transport.py

@@ -16,6 +16,7 @@ from typing import Any, NoReturn, cast
 import httpx
 
 from synth_ai.core.contracts.json_value import JsonObject, JsonValue
+from synth_ai.core.contracts.rate_limits import ResponseMetadata, parse_rate_limits
 from synth_ai.core.errors import (
     HTTP_ERROR_BODY_CAPTURE_CHARS_MAX,
     RUNTIME_UNAVAILABLE_CODES,
@@ -203,6 +204,7 @@ def _failure_from_response(
         detail=message,
         resource=_created_search(response, sources),
         reason=reason,
+        rate_limits=parse_rate_limits(response.headers),
     )
 
 
@@ -463,7 +465,10 @@ class HttpTransport:
         allow_not_found: bool = False,
         timeout_seconds: float | None = None,
         operation_id: str | None = None,
+        response_metadata: ResponseMetadata | None = None,
     ) -> JsonValue:
+        if response_metadata is not None:
+            response_metadata.rate_limits = ()
         replay_safe = request_permits_replay(method, {**self.headers, **(headers or {})})
         attempts = 0
         waited_seconds = 0.0
@@ -502,6 +507,8 @@ class HttpTransport:
                 )
             self.sleep(delay)
             waited_seconds += delay
+        if response_metadata is not None:
+            response_metadata.capture(response.headers)
         if allow_not_found and response.status_code == 404:
             return None
         if response.is_error:

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/mcp/research/server.py

@@ -273,6 +273,7 @@ def _mcp_structured_core_error_payload(exc: SynthError) -> dict[str, Any]:
                 "correlation_id": failure.correlation_id,
                 "retryable": failure.retry.retryable,
                 "retry_after_seconds": failure.retry.retry_after_seconds,
+                "rate_limits": [asdict(item) for item in failure.rate_limits],
             }
         )
         if failure.status is not None:

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692}/synth_ai/sdk/index/client.py

@@ -16,6 +16,7 @@ from hashlib import sha256
 from typing import Any, Awaitable
 from uuid import UUID, uuid4
 
+from synth_ai.core.contracts.rate_limits import ResponseMetadata
 from synth_ai.core.errors import SynthError
 from synth_ai.core.http.async_transport import AsyncHttpTransport
 from synth_ai.core.http.transport import HttpTransport
@@ -318,6 +319,7 @@ class _Call:
     headers: dict[str, str] | None = None
     params: dict[str, Any] | None = None
     raw: bool = False
+    response_metadata: ResponseMetadata | None = None
     # Per-request transport timeout; None keeps the client's default.
     timeout_seconds: float | None = None
 
@@ -339,6 +341,8 @@ class _Call:
                 kwargs["json_body"] = self.json_body
             if self.headers is not None:
                 kwargs["headers"] = self.headers
+        if self.response_metadata is not None:
+            kwargs["response_metadata"] = self.response_metadata
         return method, template.format(**(self.path_parameters or {})), kwargs
 
 
@@ -683,6 +687,7 @@ class SearchesAPI(_Resource):
         *,
         idempotency_key: str | None = None,
         retry: IndexRetryPolicy = DEFAULT_INDEX_RETRY_POLICY,
+        response_metadata: ResponseMetadata | None = None,
     ) -> Any:
         """Create one durable Search and return its handle.
 
@@ -698,6 +703,7 @@ class SearchesAPI(_Resource):
             Search.model_validate,
             json_body=_body(spec),
             headers=_key(idempotency_key),
+            response_metadata=response_metadata,
         )
         if self._asynchronous:
 
@@ -3000,6 +3006,7 @@ class _IndexRoot(_Resource):
         limits: SearchExecutionLimits | None = None,
         billing: SearchBillingConstraints | None = None,
         idempotency_key: str | None = None,
+        response_metadata: ResponseMetadata | None = None,
     ) -> Any:
         """Execute fast immediately or create-and-wait for one durable deep Search.
 
@@ -3010,7 +3017,9 @@ class _IndexRoot(_Resource):
         spec = _search_spec(spec, query, scope, filters, max_results, mode, limits, billing)
         if spec.mode == SearchMode.DEEP:
             key = _key(idempotency_key)["Idempotency-Key"]
-            handle = self.searches.create(spec, idempotency_key=key)
+            handle = self.searches.create(
+                spec, idempotency_key=key, response_metadata=response_metadata
+            )
             if self._asynchronous:
 
                 async def await_deep() -> SearchResult:
@@ -3030,6 +3039,7 @@ class _IndexRoot(_Resource):
                 lambda payload: _search_result(payload, spec),
                 json_body=spec.model_dump(mode="json"),
                 headers=_key(idempotency_key),
+                response_metadata=response_metadata,
             )
         )
 

{synth_ai-0.22.2.dev691 → synth_ai-0.22.2.dev692/synth_ai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev691
+Version: 0.22.2.dev692
 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.dev691 → synth_ai-0.22.2.dev692}/synth_ai.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ synth_ai/core/auth/credentials.py
 synth_ai/core/contracts/__init__.py
 synth_ai/core/contracts/json_value.py
 synth_ai/core/contracts/pagination.py
+synth_ai/core/contracts/rate_limits.py
 synth_ai/core/http/__init__.py
 synth_ai/core/http/async_transport.py
 synth_ai/core/http/request.py