tinyfish 0.2.2__py3-none-any.whl

tinyfish/__init__.py

@@ -0,0 +1,104 @@
+"""
+TinyFish SDK - State-of-the-Art web agents in an API
+"""
+
+from importlib.metadata import version
+
+# Clients
+# Exceptions
+from ._utils.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    SDKError,
+    SSEParseError,
+    UnprocessableEntityError,
+)
+
+# Agent resource
+from .agent import AgentStream, AsyncAgentStream
+
+# Agent types
+from .agent.types import (
+    AgentRunAsyncResponse,
+    AgentRunResponse,
+    AgentRunWithStreamingResponse,
+    BrowserProfile,
+    CompleteEvent,
+    EventType,
+    HeartbeatEvent,
+    ProgressEvent,
+    ProxyConfig,
+    ProxyCountryCode,
+    StartedEvent,
+    StreamingUrlEvent,
+)
+from .client import AsyncTinyFish, TinyFish
+
+# Runs types
+from .runs.types import (
+    ErrorCategory,
+    PaginationInfo,
+    Run,
+    RunError,
+    RunListResponse,
+    RunStatus,
+    SortDirection,
+)
+
+__version__ = version("tinyfish")
+
+__all__ = [
+    # Clients
+    "TinyFish",
+    "AsyncTinyFish",
+    # Exceptions
+    "SDKError",
+    "SSEParseError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RequestTimeoutError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    # Agent resource
+    "AgentStream",
+    "AsyncAgentStream",
+    # Agent types
+    "EventType",
+    "BrowserProfile",
+    "ProxyCountryCode",
+    "ProxyConfig",
+    "AgentRunResponse",
+    "AgentRunAsyncResponse",
+    "StartedEvent",
+    "StreamingUrlEvent",
+    "ProgressEvent",
+    "HeartbeatEvent",
+    "CompleteEvent",
+    "AgentRunWithStreamingResponse",
+    # Runs types
+    "ErrorCategory",
+    "SortDirection",
+    "RunError",
+    "Run",
+    "RunStatus",
+    "RunListResponse",
+    "PaginationInfo",
+]

tinyfish/_utils/__init__.py

@@ -0,0 +1,26 @@
+"""Reusable SDK foundation.
+
+Provides base classes for building HTTP API SDKs:
+- Clients: HTTP client with auth, retries, error handling
+- Resources: Containers for grouping related API methods
+- Exceptions: Complete error hierarchy
+"""
+
+from .client import BaseAsyncAPIClient as BaseAsyncAPIClient
+from .client import BaseSyncAPIClient as BaseSyncAPIClient
+from .exceptions import APIConnectionError as APIConnectionError
+from .exceptions import APIError as APIError
+from .exceptions import APIStatusError as APIStatusError
+from .exceptions import APITimeoutError as APITimeoutError
+from .exceptions import AuthenticationError as AuthenticationError
+from .exceptions import BadRequestError as BadRequestError
+from .exceptions import ConflictError as ConflictError
+from .exceptions import InternalServerError as InternalServerError
+from .exceptions import NotFoundError as NotFoundError
+from .exceptions import PermissionDeniedError as PermissionDeniedError
+from .exceptions import RateLimitError as RateLimitError
+from .exceptions import RequestTimeoutError as RequestTimeoutError
+from .exceptions import SDKError as SDKError
+from .exceptions import UnprocessableEntityError as UnprocessableEntityError
+from .resource import BaseAsyncAPIResource as BaseAsyncAPIResource
+from .resource import BaseSyncAPIResource as BaseSyncAPIResource

tinyfish/_utils/client/__init__.py

@@ -0,0 +1,4 @@
+"""HTTP clients with auth, retries, and error handling."""
+
+from .async_ import BaseAsyncAPIClient as BaseAsyncAPIClient
+from .sync import BaseSyncAPIClient as BaseSyncAPIClient

tinyfish/_utils/client/_base.py

@@ -0,0 +1,137 @@
+"""Shared base client internals."""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import version as _pkg_version
+from typing import TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from ..exceptions import (
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    UnprocessableEntityError,
+)
+
+ResponseT = TypeVar("ResponseT", bound=BaseModel)
+
+# 600 s = 10 min — matches the platform's own run timeout
+# (frontend/app/v1/lib/one-off-run.ts: RUN_TIMEOUT_MS = 60_000 * 10)
+_DEFAULT_TIMEOUT: float = 600.0
+_DEFAULT_MAX_RETRIES: int = 2
+_RETRY_MULTIPLIER: float = 0.5
+_RETRY_MAX_WAIT: float = 8.0
+
+
+class _BaseClient:
+    """Shared logic for sync and async clients. Not for direct use."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        Args:
+            api_key: API key for authentication. If None, falls back to the
+                     TINYFISH_API_KEY environment variable.
+            base_url: Base URL for all API requests
+            max_retries: Default max retry attempts (default: 2)
+        """
+        # If no key was passed explicitly, try the environment variable.
+        # This lets users do `export TINYFISH_API_KEY=xxx` and omit api_key
+        # entirely when constructing the client.
+        resolved_key = api_key or os.environ.get("TINYFISH_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= to the client or set the TINYFISH_API_KEY environment variable."
+            )
+
+        # Stored with leading underscores so they are not part of the public API
+        # and do not appear in autocomplete or when someone inspects the object
+        # casually (e.g. vars(client) in a debug session).
+        self._api_key = resolved_key
+        self._base_url = base_url
+        self._max_retries = max_retries
+
+    def __repr__(self) -> str:
+        # Mask the key so that logging `repr(client)` never writes a live secret
+        # to stdout, log files, or error tracking services. We keep the first 8
+        # characters so the user can still tell *which* key is in use when they
+        # have more than one (e.g. separate dev/prod keys).
+        masked = f"{self._api_key[:8]}****" if len(self._api_key) > 8 else "****"
+        return f"{self.__class__.__name__}(base_url={self._base_url!r}, api_key={masked!r})"
+
+    def _build_default_headers(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "X-API-Key": self._api_key,
+            "User-Agent": f"tinyfish-python/{_pkg_version('tinyfish')}",
+        }
+
+    def _make_status_error(self, response: httpx.Response) -> APIStatusError:
+        """
+        Translate an error HTTP response into the appropriate SDK exception.
+
+        Called by _request() in sync.py and async_.py immediately after a response
+        comes back with response.is_error == True. httpx does not raise on bad status
+        codes by itself — this method bridges that gap.
+
+        See docs/exceptions-and-errors-guide.md for the full error-handling architecture.
+        """
+        error_map: dict[int, type[APIStatusError]] = {
+            int(httpx.codes.BAD_REQUEST): BadRequestError,
+            int(httpx.codes.UNAUTHORIZED): AuthenticationError,
+            int(httpx.codes.FORBIDDEN): PermissionDeniedError,
+            int(httpx.codes.NOT_FOUND): NotFoundError,
+            int(httpx.codes.REQUEST_TIMEOUT): RequestTimeoutError,
+            int(httpx.codes.CONFLICT): ConflictError,
+            int(httpx.codes.UNPROCESSABLE_ENTITY): UnprocessableEntityError,
+            int(httpx.codes.TOO_MANY_REQUESTS): RateLimitError,
+        }
+
+        if response.is_server_error:
+            error_class = InternalServerError
+        else:
+            error_class = error_map.get(response.status_code, APIStatusError)
+
+        # Try to parse error message from JSON response
+        try:
+            error_data = response.json()
+            message = error_data.get("error", {}).get("message", response.text)
+        except Exception:
+            message = response.text or f"HTTP {response.status_code}"
+
+        if error_class is APIStatusError:
+            # Fallback: no concrete subclass matched, so pass the raw status code.
+            return error_class(message=message, response=response, status_code=response.status_code)
+        return error_class(message=message, response=response)
+
+    def _parse_response(
+        self,
+        response: httpx.Response,
+        cast_to: type[ResponseT],
+    ) -> ResponseT:
+        """
+        Parse HTTP response JSON into the given Pydantic model.
+
+        Args:
+            response: The HTTP response
+            cast_to: Pydantic model to validate and parse into
+
+        Raises:
+            pydantic.ValidationError: Response doesn't match the expected schema
+        """
+        return cast_to.model_validate(response.json())

tinyfish/_utils/client/async_.py

@@ -0,0 +1,192 @@
+"""Base asynchronous API client."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Self, TypeVar
+
+import httpx
+from pydantic import BaseModel
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from ..exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    InternalServerError,
+    RateLimitError,
+    RequestTimeoutError,
+)
+from ._base import _DEFAULT_MAX_RETRIES, _DEFAULT_TIMEOUT, _RETRY_MAX_WAIT, _RETRY_MULTIPLIER, _BaseClient
+
+ResponseT = TypeVar("ResponseT", bound=BaseModel)
+
+
+class BaseAsyncAPIClient(_BaseClient):
+    """Base asynchronous API client — same interface as BaseSyncAPIClient with async/await."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        Args:
+            api_key: API key for authentication
+            base_url: Base URL for all API requests
+            timeout: Default timeout in seconds (default: 600.0)
+            max_retries: Default max retry attempts (default: 2)
+        """
+        super().__init__(api_key=api_key, base_url=base_url, max_retries=max_retries)
+
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            headers=self._build_default_headers(),
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """
+        Make async HTTP request with automatic retries.
+
+        Retryable errors: 408, 429, 5xx, and network errors.
+        Non-retryable errors (400, 401, 403, 404, …) propagate immediately.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: URL path (relative to base_url)
+            json: JSON request body (optional)
+            params: Query parameters (optional)
+
+        Raises:
+            APITimeoutError: Request timed out
+            APIConnectionError: Network/connection error
+            APIStatusError: HTTP error status (4xx, 5xx)
+        """
+        max_attempts = self._max_retries + 1
+
+        # Retryable: 408, 429, 5xx, and network errors (TimeoutException ⊂ RequestError).
+        # Non-retryable status errors (400, 401, 403, 404, …) propagate immediately.
+        # After retries exhausted: httpx errors are wrapped into SDK types by the outer try/except.
+        @retry(
+            stop=stop_after_attempt(max_attempts),
+            wait=wait_exponential(multiplier=_RETRY_MULTIPLIER, max=_RETRY_MAX_WAIT),
+            retry=retry_if_exception_type(
+                (
+                    RequestTimeoutError,
+                    RateLimitError,
+                    InternalServerError,
+                    httpx.RequestError,  # covers TimeoutException and connection errors
+                )
+            ),
+            reraise=True,
+        )
+        async def _execute() -> httpx.Response:
+            response = await self._client.request(
+                method=method,
+                url=path,
+                json=json,
+                params=params,
+            )
+            if response.is_error:
+                raise self._make_status_error(response)
+            return response
+
+        try:
+            return await _execute()
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e), request=e.request) from e
+        except httpx.RequestError as e:
+            raise APIConnectionError(str(e), request=e.request) from e
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+        params: dict[str, Any] | None = None,
+    ) -> ResponseT:
+        """Make GET request and parse the response into cast_to."""
+        response = await self._request("GET", path, params=params)
+        return self._parse_response(response, cast_to)
+
+    async def _post(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        cast_to: type[ResponseT],
+    ) -> ResponseT:
+        """Make POST request and parse the response into cast_to."""
+        response = await self._request("POST", path, json=json)
+        return self._parse_response(response, cast_to)
+
+    async def _post_stream(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> AsyncIterator[str]:
+        """POST request that streams raw response lines (for SSE). Does not parse JSON.
+
+        Retries the initial connection on 429/5xx with exponential backoff,
+        matching the retry behaviour of ``_request()``. Once a 200 response
+        is received and streaming begins, no further retries are attempted.
+        """
+        max_attempts = self._max_retries + 1
+
+        @retry(
+            stop=stop_after_attempt(max_attempts),
+            wait=wait_exponential(multiplier=_RETRY_MULTIPLIER, max=_RETRY_MAX_WAIT),
+            retry=retry_if_exception_type(
+                (
+                    RequestTimeoutError,
+                    RateLimitError,
+                    InternalServerError,
+                    httpx.RequestError,
+                )
+            ),
+            reraise=True,
+        )
+        async def _connect() -> httpx.Response:
+            response = await self._client.send(
+                self._client.build_request("POST", path, json=json),
+                stream=True,
+            )
+            if response.is_error:
+                await response.aread()
+                await response.aclose()
+                raise self._make_status_error(response)
+            return response
+
+        try:
+            response = await _connect()
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e), request=e.request) from e
+        except httpx.RequestError as e:
+            raise APIConnectionError(str(e), request=e.request) from e
+
+        try:
+            async for line in response.aiter_lines():
+                yield line
+        finally:
+            await response.aclose()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

tinyfish/_utils/client/sync.py

@@ -0,0 +1,191 @@
+"""Base synchronous API client."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Self, TypeVar
+
+import httpx
+from pydantic import BaseModel
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from ..exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    InternalServerError,
+    RateLimitError,
+    RequestTimeoutError,
+)
+from ._base import _DEFAULT_MAX_RETRIES, _DEFAULT_TIMEOUT, _RETRY_MAX_WAIT, _RETRY_MULTIPLIER, _BaseClient
+
+ResponseT = TypeVar("ResponseT", bound=BaseModel)
+
+
+class BaseSyncAPIClient(_BaseClient):
+    """Base synchronous API client with retries, error handling, and Pydantic response parsing."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        Args:
+            api_key: API key for authentication
+            base_url: Base URL for all API requests
+            timeout: Default timeout in seconds (default: 600.0)
+            max_retries: Default max retry attempts (default: 2)
+        """
+        super().__init__(api_key=api_key, base_url=base_url, max_retries=max_retries)
+
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers=self._build_default_headers(),
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """
+        Make HTTP request with automatic retries.
+
+        Retryable errors: 408, 429, 5xx, and network errors.
+        Non-retryable errors (400, 401, 403, 404, …) propagate immediately.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: URL path (relative to base_url)
+            json: JSON request body (optional)
+            params: Query parameters (optional)
+
+        Raises:
+            APITimeoutError: Request timed out
+            APIConnectionError: Network/connection error
+            APIStatusError: HTTP error status (4xx, 5xx)
+        """
+        max_attempts = self._max_retries + 1
+
+        # Retryable: 408, 429, 5xx, and network errors (TimeoutException ⊂ RequestError).
+        # Non-retryable status errors (400, 401, 403, 404, …) propagate immediately.
+        # After retries exhausted: httpx errors are wrapped into SDK types by the outer try/except.
+        @retry(
+            stop=stop_after_attempt(max_attempts),
+            wait=wait_exponential(multiplier=_RETRY_MULTIPLIER, max=_RETRY_MAX_WAIT),
+            retry=retry_if_exception_type(
+                (
+                    RequestTimeoutError,
+                    RateLimitError,
+                    InternalServerError,
+                    httpx.RequestError,  # covers TimeoutException and connection errors
+                )
+            ),
+            reraise=True,
+        )
+        def _execute() -> httpx.Response:
+            response = self._client.request(
+                method=method,
+                url=path,
+                json=json,
+                params=params,
+            )
+            if response.is_error:
+                raise self._make_status_error(response)
+            return response
+
+        try:
+            return _execute()
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e), request=e.request) from e
+        except httpx.RequestError as e:
+            raise APIConnectionError(str(e), request=e.request) from e
+
+    def _get(
+        self,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+        params: dict[str, Any] | None = None,
+    ) -> ResponseT:
+        """Make GET request and parse the response into cast_to."""
+        response = self._request("GET", path, params=params)
+        return self._parse_response(response, cast_to)
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        cast_to: type[ResponseT],
+    ) -> ResponseT:
+        """Make POST request and parse the response into cast_to."""
+        response = self._request("POST", path, json=json)
+        return self._parse_response(response, cast_to)
+
+    def _post_stream(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> Iterator[str]:
+        """POST request that streams raw response lines (for SSE). Does not parse JSON.
+
+        Retries the initial connection on 429/5xx with exponential backoff,
+        matching the retry behaviour of ``_request()``. Once a 200 response
+        is received and streaming begins, no further retries are attempted.
+        """
+        max_attempts = self._max_retries + 1
+
+        @retry(
+            stop=stop_after_attempt(max_attempts),
+            wait=wait_exponential(multiplier=_RETRY_MULTIPLIER, max=_RETRY_MAX_WAIT),
+            retry=retry_if_exception_type(
+                (
+                    RequestTimeoutError,
+                    RateLimitError,
+                    InternalServerError,
+                    httpx.RequestError,
+                )
+            ),
+            reraise=True,
+        )
+        def _connect() -> httpx.Response:
+            response = self._client.send(
+                self._client.build_request("POST", path, json=json),
+                stream=True,
+            )
+            if response.is_error:
+                response.read()
+                response.close()
+                raise self._make_status_error(response)
+            return response
+
+        try:
+            response = _connect()
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e), request=e.request) from e
+        except httpx.RequestError as e:
+            raise APIConnectionError(str(e), request=e.request) from e
+
+        try:
+            yield from response.iter_lines()
+        finally:
+            response.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()