tinyfish 0.2.3__tar.gz → 0.2.5__tar.gz

tinyfish-0.2.5/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.5
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.10.9
+    hooks:
+      - id: uv-lock
+        name: uv-lock
+        files: ^sdk/sdk-python/(uv\.lock|pyproject\.toml)$

tinyfish-0.2.5/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

tinyfish-0.2.5/CLAUDE.md

@@ -0,0 +1,60 @@
+# TinyFish Python SDK (`tinyfish`)
+
+Official Python SDK for TinyFish. Provides sync (`TinyFish`) and async (`AsyncTinyFish`) clients for running
+automations, streaming events, and managing runs.
+
+For full method reference and examples: see `README.md`.
+
+---
+
+## Package Manager
+
+`uv` — not pip, not poetry.
+
+## Key Entry Points
+
+```
+src/tinyfish/__init__.py    → exports TinyFish, AsyncTinyFish, and all public types
+src/tinyfish/client.py      → TinyFish client class (sync)
+src/tinyfish/agent/         → agent.run(), agent.queue(), agent.stream()
+src/tinyfish/runs/          → runs.get(), runs.list()
+src/tinyfish/_utils/        → HTTP client base (sync + async), retry, error handling
+```
+
+## Quick Usage
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish(api_key="your-api-key")  # or set TINYFISH_API_KEY env var
+response = client.agent.run(goal="...", url="https://...")
+print(response.result)
+```
+
+## Tests
+
+```bash
+cd sdk/sdk-python && uv run pytest
+```
+
+## Pre-commit Hooks
+
+```bash
+cd sdk/sdk-python && pre-commit install
+```
+
+Hooks: `ruff format`, `ruff check`, `uv-lock` sync. Run before first commit and after any dep change.
+
+## Lint / Format
+
+```bash
+cd sdk/sdk-python && uv run ruff check . && uv run ruff format .
+```
+
+## Package name
+
+`tinyfish` (PyPI). The npm org uses a hyphen: `@tiny-fish/` (not `@tinyfish/`).
+
+## Further Reading
+
+See `README.md` for full usage examples, authentication patterns, and SDK changelog.

{tinyfish-0.2.3 → tinyfish-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfish
-Version: 0.2.3
+Version: 0.2.5
 Summary: Official Python SDK for the TinyFish API
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0

{tinyfish-0.2.3 → tinyfish-0.2.5}/RELEASE.md

@@ -33,13 +33,13 @@ Commit and merge to main.
 ### Step 2: Create a GitHub Release
 
 1. Go to the `ux-labs` repo on GitHub → **Releases** → **Draft a new release**
-2. Set the tag to match the version exactly, prefixed with `v`:
-   - Version `0.2.0` → tag `v0.2.0`
+2. Set the tag to match the version exactly, prefixed with `sdk-py/v`:
+   - Version `0.2.0` → tag `sdk-py/v0.2.0`
 3. Set the target to `main`
 4. Write release notes summarizing what changed
 5. Click **Publish release**
 
-The workflow validates that the tag matches the version in `pyproject.toml` — if they don't match, the build fails before anything is published.
+The CD workflow (`CD_sdk_python.yml`) only triggers on tags prefixed with `sdk-py/v`. It validates that the version portion of the tag matches `pyproject.toml` — if they don't match, the build fails before anything is published.
 
 ### Step 3: Monitor the workflow
 
@@ -56,13 +56,13 @@ After the workflow completes, verify the release:
 
 ```bash
 pip install tinyfish==0.2.0
-python -c "from tinyfish import Tinyfish; print('ok')"
+python -c "from tinyfish import TinyFish; print('ok')"
 ```
 
 ## Troubleshooting
 
 **Tag does not match pyproject.toml version**
-The build job validates that the git tag (e.g., `v0.2.0`) matches the version in `pyproject.toml` (e.g., `0.2.0`). Fix by updating `pyproject.toml` to match the tag before publishing, then delete and recreate the release.
+The build job validates that the git tag (e.g., `sdk-py/v0.2.0`) matches the version in `pyproject.toml` (e.g., `0.2.0`). Fix by updating `pyproject.toml` to match the tag before publishing, then delete and recreate the release.
 
 **403 / authentication error**
 Verify that `PYPI_API_TOKEN` has been added to the `ux-labs` repo secrets in `github-control`. The token must exist as a GitHub Actions secret before the workflow can publish.

tinyfish-0.2.5/docs/internal/api-integration-header.md

@@ -0,0 +1,58 @@
+# API Integration Tagging (`TF_API_INTEGRATION`)
+
+Internal-only mechanism for identifying which integration platform is making API requests through our SDK.
+
+## How it works
+
+The SDK reads the `TF_API_INTEGRATION` environment variable when building request bodies. When set, the SDK injects `api_integration` into every request body sent to the automation endpoints.
+
+```text
+TF_API_INTEGRATION=n8n  -->  { "goal": "...", "url": "...", "api_integration": "n8n" }
+```
+
+This reuses the existing `api_integration` body field that the server already parses, stores in the DB, and emits to PostHog — no backend changes needed.
+
+This is intentionally **not** exposed as a constructor parameter or public API. It does not appear in editor autocomplete, type definitions, or documentation. Only we control which integrations set this value.
+
+## Environment variable
+
+| Variable              | Example values         | Required |
+| --------------------- | ---------------------- | -------- |
+| `TF_API_INTEGRATION`  | `n8n`, `dify`, `zapier` | No       |
+
+When unset or empty, `api_integration` is omitted from the body. Existing behavior is unchanged.
+
+## Where it's read
+
+`src/tinyfish/_utils/client/_base.py` — `_inject_integration()`, called from `_request()` in both sync and async clients:
+
+```python
+integration = os.environ.get("TF_API_INTEGRATION", "").strip()
+if integration:
+    json["api_integration"] = integration
+```
+
+This runs on every API request automatically — no per-resource setup needed.
+
+## Server-side flow
+
+1. Server validates `api_integration` via Zod schema (`frontend/app/v1/schemas.ts`)
+2. `buildRunOptions()` extracts it from the request body
+3. Stored in `runs.api_integration` DB column
+4. Emitted on `run_completed` PostHog event as `api_integration` property
+
+## Setting up a new integration
+
+To tag requests from a new integration partner:
+
+1. Set `TF_API_INTEGRATION=<name>` in the environment where the SDK runs (e.g., the n8n node, Dify plugin, Zapier action)
+2. No SDK code changes needed — the env var is picked up automatically
+3. The value will appear in PostHog under `run_completed.api_integration`
+
+## Tests
+
+`tests/test_client.py`:
+
+- `test_integration_in_body_via_env` — `api_integration` is in the request body when env var is set
+- `test_no_integration_in_body_by_default` — `api_integration` is absent when env var is not set
+- `test_async_integration_in_body_via_env` — async client variant

{tinyfish-0.2.3 → tinyfish-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.2.3"
+version = "0.2.5"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,6 +33,10 @@ asyncio_default_fixture_loop_scope = "session"
 [tool.ruff]
 src = ["src"]
 line-length = 120
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+docstring-code-line-length = 20
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "PYI", "TID"]

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/__init__.py

@@ -26,8 +26,6 @@ from ._utils.exceptions import (
 
 # Agent resource
 from .agent import AgentStream, AsyncAgentStream
-
-# Agent types
 from .agent.types import (
     AgentRunAsyncResponse,
     AgentRunResponse,
@@ -42,7 +40,16 @@ from .agent.types import (
     StartedEvent,
     StreamingUrlEvent,
 )
+
+# Browser types
+from .browser.types import BrowserSession, BrowserSessionCreateParams
 from .client import AsyncTinyFish, TinyFish
+from .fetch.types import (
+    FetchError,
+    FetchFormat,
+    FetchResponse,
+    FetchResult,
+)
 
 # Runs types
 from .runs.types import (
@@ -55,6 +62,9 @@ from .runs.types import (
     SortDirection,
 )
 
+# Search types
+from .search.types import SearchQueryResponse, SearchResult
+
 __version__ = version("tinyfish")
 
 __all__ = [
@@ -80,6 +90,9 @@ __all__ = [
     # Agent resource
     "AgentStream",
     "AsyncAgentStream",
+    # Browser types
+    "BrowserSession",
+    "BrowserSessionCreateParams",
     # Agent types
     "EventType",
     "BrowserProfile",
@@ -93,6 +106,14 @@ __all__ = [
     "HeartbeatEvent",
     "CompleteEvent",
     "AgentRunWithStreamingResponse",
+    # Fetch types
+    "FetchFormat",
+    "FetchResult",
+    "FetchError",
+    "FetchResponse",
+    # Search types
+    "SearchResult",
+    "SearchQueryResponse",
     # Runs types
     "ErrorCategory",
     "SortDirection",

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/_utils/client/_base.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 from importlib.metadata import version as _pkg_version
-from typing import TypeVar
+from typing import Any, TypeVar
 
 import httpx
 from pydantic import BaseModel
@@ -79,8 +79,19 @@ class _BaseClient:
             "Accept": "application/json",
             "X-API-Key": self._api_key,
             "User-Agent": f"tinyfish-python/{_pkg_version('tinyfish')}",
+            "X-TF-Request-Origin": "tinyfish-python",
         }
 
+    @staticmethod
+    def _inject_integration(json: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Inject api_integration from TF_API_INTEGRATION env var into JSON body."""
+        if json is None:
+            return None
+        integration = os.environ.get("TF_API_INTEGRATION", "").strip()
+        if integration:
+            json["api_integration"] = integration
+        return json
+
     def _make_status_error(self, response: httpx.Response) -> APIStatusError:
         """
         Translate an error HTTP response into the appropriate SDK exception.

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/_utils/client/async_.py

@@ -72,6 +72,7 @@ class BaseAsyncAPIClient(_BaseClient):
             APIConnectionError: Network/connection error
             APIStatusError: HTTP error status (4xx, 5xx)
         """
+        json = self._inject_integration(json)
         max_attempts = self._max_retries + 1
 
         # Retryable: 408, 429, 5xx, and network errors (TimeoutException ⊂ RequestError).
@@ -142,6 +143,7 @@ class BaseAsyncAPIClient(_BaseClient):
         matching the retry behaviour of ``_request()``. Once a 200 response
         is received and streaming begins, no further retries are attempted.
         """
+        json = self._inject_integration(json)
         max_attempts = self._max_retries + 1
 
         @retry(

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/_utils/client/sync.py

@@ -72,6 +72,7 @@ class BaseSyncAPIClient(_BaseClient):
             APIConnectionError: Network/connection error
             APIStatusError: HTTP error status (4xx, 5xx)
         """
+        json = self._inject_integration(json)
         max_attempts = self._max_retries + 1
 
         # Retryable: 408, 429, 5xx, and network errors (TimeoutException ⊂ RequestError).
@@ -142,6 +143,7 @@ class BaseSyncAPIClient(_BaseClient):
         matching the retry behaviour of ``_request()``. Once a 200 response
         is received and streaming begins, no further retries are attempted.
         """
+        json = self._inject_integration(json)
         max_attempts = self._max_retries + 1
 
         @retry(

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/agent/__init__.py

@@ -41,8 +41,15 @@ class AgentStream:
 
     Use as::
 
-        with client.agent.stream(goal=..., url=...) as stream:
-            for event in stream:
+        with (
+            client.agent.stream(
+                goal=...,
+                url=...,
+            ) as stream
+        ):
+            for (
+                event
+            ) in stream:
                 ...
     """
 
@@ -64,8 +71,15 @@ class AsyncAgentStream:
 
     Use as::
 
-        async with client.agent.stream(goal=..., url=...) as stream:
-            async for event in stream:
+        async with (
+            client.agent.stream(
+                goal=...,
+                url=...,
+            ) as stream
+        ):
+            async for (
+                event
+            ) in stream:
                 ...
     """
 
@@ -166,10 +180,22 @@ class AgentResource(BaseSyncAPIResource):
         Use the on_* callbacks for a reactive style, or iterate over
         the stream for a sequential style::
 
-            with client.agent.stream(goal=..., url=...) as stream:
-                for event in stream:
-                    if isinstance(event, ProgressEvent):
-                        print(event.purpose)
+            with (
+                client.agent.stream(
+                    goal=...,
+                    url=...,
+                ) as stream
+            ):
+                for (
+                    event
+                ) in stream:
+                    if isinstance(
+                        event,
+                        ProgressEvent,
+                    ):
+                        print(
+                            event.purpose
+                        )
 
         Args:
             goal: Natural language description of what to do on the page.
@@ -309,10 +335,22 @@ class AsyncAgentResource(BaseAsyncAPIResource):
         Use the on_* callbacks for a reactive style, or iterate over
         the stream for a sequential style::
 
-            async with client.agent.stream(goal=..., url=...) as stream:
-                async for event in stream:
-                    if isinstance(event, ProgressEvent):
-                        print(event.purpose)
+            async with (
+                client.agent.stream(
+                    goal=...,
+                    url=...,
+                ) as stream
+            ):
+                async for (
+                    event
+                ) in stream:
+                    if isinstance(
+                        event,
+                        ProgressEvent,
+                    ):
+                        print(
+                            event.purpose
+                        )
 
         Args:
             goal: Natural language description of what to do on the page.

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/agent/types.py

@@ -67,12 +67,19 @@ class AgentRunResponse(BaseModel):
         ```python
         response = client.agent.run(
             goal="Find the price of iPhone 15",
-            url="https://www.apple.com"
+            url="https://www.apple.com",
         )
-        if response.status == "COMPLETED":
-            print(response.result)
+        if (
+            response.status
+            == "COMPLETED"
+        ):
+            print(
+                response.result
+            )
         else:
-            print(f"Failed: {response.error.message}")
+            print(
+                f"Failed: {response.error.message}"
+            )
         ```
     """
 
@@ -103,13 +110,19 @@ class AgentRunAsyncResponse(BaseModel):
         ```python
         response = client.agent.queue(
             goal="Extract product details",
-            url="https://example.com"
+            url="https://example.com",
+        )
+        print(
+            f"Run started: {response.run_id}"
         )
-        print(f"Run started: {response.run_id}")
 
         # Check status later
-        run = client.runs.get(response.run_id)
-        print(f"Status: {run.status}")
+        run = client.runs.get(
+            response.run_id
+        )
+        print(
+            f"Status: {run.status}"
+        )
         ```
     """
 
@@ -173,7 +186,7 @@ class CompleteEvent(BaseModel):
     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"
+        None, alias="result", description="Structured JSON result extracted from the automation"
     )
     error: RunError | None = Field(None, description="Error details if the run failed. None if succeeded.")
 

tinyfish-0.2.5/src/tinyfish/browser/__init__.py

@@ -0,0 +1,86 @@
+"""Browser resource for creating remote browser sessions."""
+
+from __future__ import annotations
+
+from tinyfish._utils.client import BaseAsyncAPIClient, BaseSyncAPIClient
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+
+from .types import BrowserSession, BrowserSessionCreateParams
+
+
+class BrowserSessionsResource(BaseSyncAPIResource):
+    """Create remote browser sessions (sync)."""
+
+    def create(
+        self,
+        *,
+        url: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> BrowserSession:
+        """Create a new remote browser session.
+
+        Args:
+            url: Target URL for the browser session. If omitted, browser starts at about:blank.
+            timeout_seconds: Inactivity timeout in seconds. If omitted or exceeds plan max,
+                the plan max is used.
+
+        Returns:
+            BrowserSession with session_id, cdp_url, and base_url.
+
+        Raises:
+            BadRequestError: Invalid parameters.
+            AuthenticationError: Invalid API key.
+        """
+        params = BrowserSessionCreateParams(url=url, timeout_seconds=timeout_seconds)
+        body = params.model_dump(exclude_none=True)
+        return self._post("/v1/browser", json=body, cast_to=BrowserSession)
+
+
+class AsyncBrowserSessionsResource(BaseAsyncAPIResource):
+    """Create remote browser sessions (async)."""
+
+    async def create(
+        self,
+        *,
+        url: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> BrowserSession:
+        """Create a new remote browser session.
+
+        Async version of `BrowserSessionsResource.create()`.
+
+        Args:
+            url: Target URL for the browser session. If omitted, browser starts at about:blank.
+            timeout_seconds: Inactivity timeout in seconds. If omitted or exceeds plan max,
+                the plan max is used.
+
+        Returns:
+            BrowserSession with session_id, cdp_url, and base_url.
+
+        Raises:
+            BadRequestError: Invalid parameters.
+            AuthenticationError: Invalid API key.
+        """
+        params = BrowserSessionCreateParams(url=url, timeout_seconds=timeout_seconds)
+        body = params.model_dump(exclude_none=True)
+        return await self._post("/v1/browser", json=body, cast_to=BrowserSession)
+
+
+class BrowserResource(BaseSyncAPIResource):
+    """Browser API namespace (sync)."""
+
+    sessions: BrowserSessionsResource
+
+    def __init__(self, client: BaseSyncAPIClient) -> None:
+        super().__init__(client)
+        self.sessions = BrowserSessionsResource(client)
+
+
+class AsyncBrowserResource(BaseAsyncAPIResource):
+    """Browser API namespace (async)."""
+
+    sessions: AsyncBrowserSessionsResource
+
+    def __init__(self, client: BaseAsyncAPIClient) -> None:
+        super().__init__(client)
+        self.sessions = AsyncBrowserSessionsResource(client)

tinyfish-0.2.5/src/tinyfish/browser/types.py

@@ -0,0 +1,24 @@
+"""Browser API request/response types."""
+
+from pydantic import BaseModel, Field
+
+
+class BrowserSessionCreateParams(BaseModel):
+    """Parameters for `browser.sessions.create()`."""
+
+    url: str | None = Field(
+        None,
+        description="Target URL for the browser session. If omitted, browser starts at about:blank.",
+    )
+    timeout_seconds: int | None = Field(
+        None,
+        description="Inactivity timeout in seconds. If omitted or exceeds plan max, the plan max is used.",
+    )
+
+
+class BrowserSession(BaseModel):
+    """Response from creating a browser session."""
+
+    session_id: str = Field(..., description="Unique session identifier")
+    cdp_url: str = Field(..., description="CDP WebSocket URL for direct browser connection")
+    base_url: str = Field(..., description="HTTPS base URL for the browser session")

{tinyfish-0.2.3 → tinyfish-0.2.5}/src/tinyfish/client.py

@@ -4,7 +4,10 @@ from tinyfish._utils.client import BaseAsyncAPIClient, BaseSyncAPIClient
 from tinyfish._utils.client._base import _DEFAULT_TIMEOUT
 
 from .agent import AgentResource, AsyncAgentResource
+from .browser import AsyncBrowserResource, BrowserResource
+from .fetch import AsyncFetchResource, FetchResource
 from .runs import AsyncRunsResource, RunsResource
+from .search import AsyncSearchResource, SearchResource
 
 __all__ = ["TinyFish", "AsyncTinyFish"]
 
@@ -21,7 +24,10 @@ class TinyFish(BaseSyncAPIClient):
     # __init__ assignments below — which means no autocomplete for users who just
     # did `pip install tinyfish`.
     agent: AgentResource
+    browser: BrowserResource
+    fetch: FetchResource
     runs: RunsResource
+    search: SearchResource
 
     def __init__(
         self,
@@ -42,7 +48,10 @@ class TinyFish(BaseSyncAPIClient):
         )
 
         self.agent = AgentResource(self)
+        self.browser = BrowserResource(self)
+        self.fetch = FetchResource(self)
         self.runs = RunsResource(self)
+        self.search = SearchResource(self)
 
 
 class AsyncTinyFish(BaseAsyncAPIClient):
@@ -52,7 +61,10 @@ class AsyncTinyFish(BaseAsyncAPIClient):
     # checkers recognise these as AsyncAgentResource / AsyncRunsResource (not
     # the sync variants) when resolving types from an installed package.
     agent: AsyncAgentResource
+    browser: AsyncBrowserResource
+    fetch: AsyncFetchResource
     runs: AsyncRunsResource
+    search: AsyncSearchResource
 
     def __init__(
         self,
@@ -73,4 +85,7 @@ class AsyncTinyFish(BaseAsyncAPIClient):
         )
 
         self.agent = AsyncAgentResource(self)
+        self.browser = AsyncBrowserResource(self)
+        self.fetch = AsyncFetchResource(self)
         self.runs = AsyncRunsResource(self)
+        self.search = AsyncSearchResource(self)