tinyfish 0.2.2__py3-none-any.whl

tinyfish/agent/types.py

@@ -0,0 +1,182 @@
+"""Agent automation request/response types."""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tinyfish.runs.types import RunError, RunStatus
+
+# ============================================================================
+# Shared Types
+# ============================================================================
+
+
+class BrowserProfile(StrEnum):
+    """Browser profile for execution."""
+
+    LITE = "lite"
+    STEALTH = "stealth"
+
+
+class ProxyCountryCode(StrEnum):
+    """ISO 3166-1 alpha-2 country code for proxy location."""
+
+    US = "US"
+    GB = "GB"
+    CA = "CA"
+    DE = "DE"
+    FR = "FR"
+    JP = "JP"
+    AU = "AU"
+
+
+class ProxyConfig(BaseModel):
+    """Proxy configuration for browser automation."""
+
+    enabled: bool
+    """Enable proxy for this automation run."""
+    country_code: ProxyCountryCode | None = None
+    """ISO 3166-1 alpha-2 country code for proxy location."""
+
+
+class EventType(StrEnum):
+    """SSE event type discriminator."""
+
+    STARTED = "STARTED"
+    STREAMING_URL = "STREAMING_URL"
+    PROGRESS = "PROGRESS"
+    HEARTBEAT = "HEARTBEAT"
+    COMPLETE = "COMPLETE"
+
+
+# ============================================================================
+# Response Types - Synchronous Run
+# ============================================================================
+
+
+class AgentRunResponse(BaseModel):
+    """
+    Response from synchronous automation execution.
+
+    Check status to determine success/failure:
+    - On success: result is populated, error is None
+    - On failure: result is None, error contains message
+
+    Example:
+        ```python
+        response = client.agent.run(
+            goal="Find the price of iPhone 15",
+            url="https://www.apple.com"
+        )
+        if response.status == "COMPLETED":
+            print(response.result)
+        else:
+            print(f"Failed: {response.error.message}")
+        ```
+    """
+
+    status: RunStatus = Field(..., description="Final status of the automation run")
+    run_id: str | None = Field(None, description="Unique identifier for the automation run")
+    result: dict[str, object] | None = Field(
+        None, description="Structured JSON result extracted from the automation. None if the run failed."
+    )
+    error: RunError | None = Field(None, description="Error details. None if the run succeeded.")
+    num_of_steps: int = Field(..., description="Number of steps taken during the automation")
+    started_at: datetime | None = Field(None, description="Timestamp when the run started")
+    finished_at: datetime | None = Field(None, description="Timestamp when the run finished")
+
+
+# ============================================================================
+# Response Types - Async Run
+# ============================================================================
+
+
+class AgentRunAsyncResponse(BaseModel):
+    """
+    Response from asynchronous automation execution.
+
+    Returns run_id immediately without waiting for completion.
+    Use client.runs.retrieve(run_id) to check status later.
+
+    Example:
+        ```python
+        response = client.agent.queue(
+            goal="Extract product details",
+            url="https://example.com"
+        )
+        print(f"Run started: {response.run_id}")
+
+        # Check status later
+        run = client.runs.get(response.run_id)
+        print(f"Status: {run.status}")
+        ```
+    """
+
+    run_id: str | None = Field(None, description="Unique identifier for the created automation run")
+    error: RunError | None = Field(None, description="Error details. None if successful.")
+
+
+# ============================================================================
+# Response Types - Streaming Events
+# ============================================================================
+
+
+class StartedEvent(BaseModel):
+    """SSE event indicating the automation run has started."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: EventType = Field(..., description="Event type")
+    run_id: str = Field(..., alias="runId", description="Unique identifier for the automation run")
+    timestamp: datetime = Field(..., description="Timestamp of the event")
+
+
+class StreamingUrlEvent(BaseModel):
+    """SSE event providing the live browser streaming URL."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: EventType = Field(..., description="Event type")
+    run_id: str = Field(..., alias="runId", description="Unique identifier for the automation run")
+    streaming_url: str = Field(..., alias="streamingUrl", description="WebSocket URL for live browser streaming")
+    timestamp: datetime = Field(..., description="Timestamp of the event")
+
+
+class ProgressEvent(BaseModel):
+    """SSE event indicating automation progress/activity."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: EventType = Field(..., description="Event type")
+    run_id: str = Field(..., alias="runId", description="Unique identifier for the automation run")
+    purpose: str = Field(..., description="Description of current automation step/activity")
+    timestamp: datetime = Field(..., description="Timestamp of the event")
+
+
+class HeartbeatEvent(BaseModel):
+    """SSE event for connection keepalive."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: EventType = Field(..., description="Event type")
+    timestamp: datetime = Field(..., description="Timestamp of the event")
+
+
+class CompleteEvent(BaseModel):
+    """SSE event indicating the automation run has completed."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: EventType = Field(..., description="Event type")
+    run_id: str = Field(..., alias="runId", description="Unique identifier for the automation run")
+    status: RunStatus = Field(..., description="Final status of the automation")
+    timestamp: datetime = Field(..., description="Timestamp of the event")
+    result_json: dict[str, object] | None = Field(
+        None, alias="resultJson", description="Structured JSON result extracted from the automation"
+    )
+    error: RunError | None = Field(None, description="Error details if the run failed. None if succeeded.")
+
+
+AgentRunWithStreamingResponse = StartedEvent | StreamingUrlEvent | ProgressEvent | HeartbeatEvent | CompleteEvent
+"""Union type for all possible SSE streaming events."""

tinyfish/client.py

@@ -0,0 +1,76 @@
+"""TinyFish SDK client."""
+
+from tinyfish._utils.client import BaseAsyncAPIClient, BaseSyncAPIClient
+from tinyfish._utils.client._base import _DEFAULT_TIMEOUT
+
+from .agent import AgentResource, AsyncAgentResource
+from .runs import AsyncRunsResource, RunsResource
+
+__all__ = ["TinyFish", "AsyncTinyFish"]
+
+API_BASE_URL = "https://agent.tinyfish.ai"
+
+
+class TinyFish(BaseSyncAPIClient):
+    """Synchronous TinyFish client for browser automation."""
+
+    # Explicit class-level annotations so that IDEs and static type checkers
+    # (mypy, Pylance/pyright) know the types of these attributes when the package
+    # is installed from PyPI. Without these declarations, tools that inspect the
+    # installed wheel rather than the live source may not infer the types from the
+    # __init__ assignments below — which means no autocomplete for users who just
+    # did `pip install tinyfish`.
+    agent: AgentResource
+    runs: RunsResource
+
+    def __init__(
+        self,
+        *,
+        # api_key is optional here: if omitted, _BaseClient will read it from
+        # the TINYFISH_API_KEY environment variable and raise a clear ValueError
+        # if neither is set.
+        api_key: str | None = None,
+        base_url: str = API_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.agent = AgentResource(self)
+        self.runs = RunsResource(self)
+
+
+class AsyncTinyFish(BaseAsyncAPIClient):
+    """Asynchronous TinyFish client for browser automation."""
+
+    # Same reasoning as TinyFish above: explicit annotations ensure that type
+    # checkers recognise these as AsyncAgentResource / AsyncRunsResource (not
+    # the sync variants) when resolving types from an installed package.
+    agent: AsyncAgentResource
+    runs: AsyncRunsResource
+
+    def __init__(
+        self,
+        *,
+        # api_key is optional here: if omitted, _BaseClient will read it from
+        # the TINYFISH_API_KEY environment variable and raise a clear ValueError
+        # if neither is set.
+        api_key: str | None = None,
+        base_url: str = API_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.agent = AsyncAgentResource(self)
+        self.runs = AsyncRunsResource(self)

tinyfish/py.typed

@@ -0,0 +1,11 @@
+# PEP 561 marker file.
+#
+# This empty file tells type checkers (mypy, Pylance/pyright) that this package
+# ships its own type information and should NOT be treated as untyped.
+#
+# Without this file, tools like Pylance will ignore the package's annotations even
+# though they exist in the source — meaning users get zero autocomplete or type
+# errors when they install the SDK. Every typed dependency we rely on (httpx,
+# pydantic, tenacity) includes this file for the same reason.
+#
+# Reference: https://peps.python.org/pep-0561/

tinyfish/runs/__init__.py

@@ -0,0 +1,147 @@
+"""Runs resource for retrieving and listing automation runs."""
+
+from __future__ import annotations
+
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+
+from .types import RunListResponse, RunRetrieveResponse, RunStatus, SortDirection
+
+
+class RunsResource(BaseSyncAPIResource):
+    """Retrieve and list automation runs."""
+
+    def get(self, run_id: str) -> RunRetrieveResponse:
+        """Retrieve a single run by its ID.
+
+        Args:
+            run_id: The run ID returned by `agent.queue()` or any run response.
+
+        Returns:
+            RunRetrieveResponse with the full run details including status and result.
+
+        Raises:
+            ValueError: run_id is empty or whitespace.
+            NotFoundError: No run exists with that ID.
+            AuthenticationError: Invalid API key.
+        """
+        if not run_id or not run_id.strip():
+            raise ValueError("run_id must be a non-empty string")
+        return self._get(f"/v1/runs/{run_id}", cast_to=RunRetrieveResponse)
+
+    def list(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+        status: RunStatus | None = None,
+        goal: str | None = None,
+        created_after: str | None = None,
+        created_before: str | None = None,
+        sort_direction: SortDirection | None = None,
+    ) -> RunListResponse:
+        """List automation runs, with optional filtering and pagination.
+
+        Args:
+            cursor: Pagination cursor from a previous response's next_cursor field.
+            limit: Maximum number of runs to return.
+            status: Filter by run status — one of "PENDING", "RUNNING",
+                    "COMPLETED", "FAILED", or "CANCELLED".
+            goal: Filter by goal text.
+            created_after: Filter runs created after this ISO timestamp.
+            created_before: Filter runs created before this ISO timestamp.
+            sort_direction: Sort order — "asc" or "desc".
+
+        Returns:
+            RunListResponse with a list of runs and pagination info.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+        """
+        params = {}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        if status is not None:
+            params["status"] = status
+        if goal is not None:
+            params["goal"] = goal
+        if created_after is not None:
+            params["created_after"] = created_after
+        if created_before is not None:
+            params["created_before"] = created_before
+        if sort_direction is not None:
+            params["sort_direction"] = sort_direction
+        return self._get("/v1/runs", params=params, cast_to=RunListResponse)
+
+
+class AsyncRunsResource(BaseAsyncAPIResource):
+    """Async retrieve and list automation runs."""
+
+    async def get(self, run_id: str) -> RunRetrieveResponse:
+        """Retrieve a single run by its ID.
+
+        Async version of `RunsResource.get()`.
+
+        Args:
+            run_id: The run ID returned by `agent.queue()` or any run response.
+
+        Returns:
+            RunRetrieveResponse with the full run details including status and result.
+
+        Raises:
+            ValueError: run_id is empty or whitespace.
+            NotFoundError: No run exists with that ID.
+            AuthenticationError: Invalid API key.
+        """
+        if not run_id or not run_id.strip():
+            raise ValueError("run_id must be a non-empty string")
+        return await self._get(f"/v1/runs/{run_id}", cast_to=RunRetrieveResponse)
+
+    async def list(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+        status: RunStatus | None = None,
+        goal: str | None = None,
+        created_after: str | None = None,
+        created_before: str | None = None,
+        sort_direction: SortDirection | None = None,
+    ) -> RunListResponse:
+        """List automation runs, with optional filtering and pagination.
+
+        Async version of `RunsResource.list()`.
+
+        Args:
+            cursor: Pagination cursor from a previous response's next_cursor field.
+            limit: Maximum number of runs to return.
+            status: Filter by run status — one of "PENDING", "RUNNING",
+                    "COMPLETED", "FAILED", or "CANCELLED".
+            goal: Filter by goal text.
+            created_after: Filter runs created after this ISO timestamp.
+            created_before: Filter runs created before this ISO timestamp.
+            sort_direction: Sort order — "asc" or "desc".
+
+        Returns:
+            RunListResponse with a list of runs and pagination info.
+
+        Raises:
+            AuthenticationError: Invalid API key.
+        """
+        params = {}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        if status is not None:
+            params["status"] = status
+        if goal is not None:
+            params["goal"] = goal
+        if created_after is not None:
+            params["created_after"] = created_after
+        if created_before is not None:
+            params["created_before"] = created_before
+        if sort_direction is not None:
+            params["sort_direction"] = sort_direction
+        return await self._get("/v1/runs", params=params, cast_to=RunListResponse)

tinyfish/runs/types.py

@@ -0,0 +1,107 @@
+"""Runs management request/response types."""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+# ============================================================================
+# Shared Types
+# ============================================================================
+
+
+class RunStatus(StrEnum):
+    """Status of an automation run.
+
+    Use these constants instead of raw strings when filtering or branching on
+    run status — your IDE will autocomplete the options and typos become
+    type errors.
+    """
+
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+
+class SortDirection(StrEnum):
+    """Sort order for list queries."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+class BrowserConfig(BaseModel):
+    """Browser configuration used for a run."""
+
+    proxy_enabled: bool | None = Field(None, description="Whether proxy was enabled")
+    proxy_country_code: str | None = Field(None, description="Country code for proxy")
+
+
+class ErrorCategory(StrEnum):
+    """Error category indicating the source of failure.
+
+    SYSTEM_FAILURE: TinyFish infrastructure issue — safe to retry.
+    AGENT_FAILURE: Problem with the run itself — fix the input.
+    UNKNOWN: Unclassified — treat as retryable.
+    """
+
+    SYSTEM_FAILURE = "SYSTEM_FAILURE"
+    AGENT_FAILURE = "AGENT_FAILURE"
+    UNKNOWN = "UNKNOWN"
+
+
+class RunError(BaseModel):
+    """Error details for failed runs."""
+
+    message: str = Field(..., description="Error message describing why the run failed")
+    category: ErrorCategory = Field(..., description="Error category indicating the source of failure")
+    retry_after: int | None = Field(None, description="Suggested retry delay in seconds")
+    help_url: str | None = Field(None, description="URL to troubleshooting docs")
+    help_message: str | None = Field(None, description="Human-readable guidance")
+
+
+# ============================================================================
+# Run Object (used in both retrieve and list)
+# ============================================================================
+
+
+class Run(BaseModel):
+    """A single automation run with full details."""
+
+    run_id: str = Field(..., description="Unique identifier for the run")
+    status: RunStatus = Field(..., description="Current status of the run")
+    goal: str = Field(..., description="Natural language goal for this automation run")
+    created_at: datetime = Field(..., description="Timestamp when run was created")
+    started_at: datetime | None = Field(None, description="Timestamp when run started executing")
+    finished_at: datetime | None = Field(None, description="Timestamp when run finished executing")
+    result: dict[str, object] | None = Field(
+        None, description="Extracted data from the automation run. None if not completed or failed."
+    )
+    error: RunError | None = Field(None, description="Error details. None if the run succeeded or is still running.")
+    streaming_url: str | None = Field(None, description="URL to watch live browser session (available while running)")
+    browser_config: BrowserConfig | None = Field(None, description="Browser configuration used for the run")
+
+
+# ============================================================================
+# Response Types
+# ============================================================================
+
+RunRetrieveResponse = Run
+"""Response from retrieving a single run."""
+
+
+class PaginationInfo(BaseModel):
+    """Pagination metadata for list responses."""
+
+    total: int = Field(..., description="Total number of runs matching the current filters")
+    has_more: bool = Field(..., description="Whether there are more results after this page")
+    next_cursor: str | None = Field(None, description="Cursor for fetching next page. None if no more results.")
+
+
+class RunListResponse(BaseModel):
+    """Paginated list of automation runs."""
+
+    data: list[Run] = Field(..., description="Array of runs")
+    pagination: PaginationInfo = Field(..., description="Pagination information")

tinyfish-0.2.2.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: tinyfish
+Version: 0.2.2
+Summary: Official Python SDK for the TinyFish API
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=8.0.0

tinyfish-0.2.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+tinyfish/__init__.py,sha256=hKareLVKDKMAywdmW0IOAKz9a5ZR5d7M86s1_opO7GI,2036
+tinyfish/client.py,sha256=2IS60FJZbDnbbOQww4N0opBi8nMMggFGq2hbGQtoBdY,2599
+tinyfish/py.typed,sha256=yxjSy53_7xEIAsOyy7r2GFVkBYVEjtl2XyXKssTRdqc,532
+tinyfish/_utils/__init__.py,sha256=-uUXnfefCggFPEGiscX1eKN1oDzk82HANesVZYZ9thA,1336
+tinyfish/_utils/exceptions.py,sha256=DjNt7b9biQG6JSsElBdGQrMlpoC8qD7DV5gqklt0p1s,5105
+tinyfish/_utils/resource.py,sha256=N9R-Ku90nOXie3ysEnjb2FZYmjqx3q0Lzbt3IfcGEV8,670
+tinyfish/_utils/sse_parser.py,sha256=-zwym5Aq3axxcU8TJupsrDoC-7jhDmNAL1TiAaT_Jd8,1847
+tinyfish/_utils/client/__init__.py,sha256=3qqhgxPazeJp5KO2WZAPnTAc5l1nfFwmRPR90cIyZkM,178
+tinyfish/_utils/client/_base.py,sha256=i8P8eKU-qPTWnunjKo_bUI-sIGEnHKugUAOALfs10p8,5208
+tinyfish/_utils/client/async_.py,sha256=bYRDI-xRoYtolfz1Q95AAAG8I3szpVVQsIkermIV64A,6452
+tinyfish/_utils/client/sync.py,sha256=p2iXYpQJUsbV8yjy5XwFb4aCM6958Kpf2kCUzs2URAM,6269
+tinyfish/agent/__init__.py,sha256=_OmCgTNzp-e1rdl7UK25zjjbkk2_ICsFi0lljdkGeOI,14278
+tinyfish/agent/types.py,sha256=hwymhzRDn5JklSn0R76TaZE4jKI3PXIFv_G5ampl2RI,6361
+tinyfish/runs/__init__.py,sha256=YLUrveaCsff7xfWDj40fSsXpWnLSxcQU_g2Me54c2jA,5440
+tinyfish/runs/types.py,sha256=jMIjiQyE9lESHPbxm1hTgnh5fUZ0hVk1auuCta1Hx0g,4110
+tinyfish-0.2.2.dist-info/METADATA,sha256=vK3OgMO0sSCVlAyBhnfDc59Q5GUJu8Z3enzb8-wgEFQ,217
+tinyfish-0.2.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tinyfish-0.2.2.dist-info/RECORD,,

tinyfish-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any