tinyfish 0.2.5__tar.gz → 0.3.0__tar.gz

tinyfish-0.3.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.3.0](https://github.com/tinyfish-io/ux-labs/compare/sdk-py/v0.2.6...sdk-py/v0.3.0) (2026-07-22)
+
+
+### Features
+
+* **ci:** automate SDK/CLI releases via release-please ([#3632](https://github.com/tinyfish-io/ux-labs/issues/3632)) ([1b311ea](https://github.com/tinyfish-io/ux-labs/commit/1b311ea6d6277fad21b57baf0b7cfdc6619a3b93))
+* **sdk:** add domain_type to search.query() in TypeScript and Python SDKs ([#3432](https://github.com/tinyfish-io/ux-labs/issues/3432)) ([1c2954c](https://github.com/tinyfish-io/ux-labs/commit/1c2954cb192324cdca1ce206515de72df2cd231d))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfish
-Version: 0.2.5
+Version: 0.3.0
 Summary: Official Python SDK for the TinyFish API
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
@@ -53,8 +53,10 @@ Every method below is available on both `TinyFish` (sync) and `AsyncTinyFish` (a
 | [`agent.run()`](#agentrun--block-until-done) | Run an automation, wait for the result | `AgentRunResponse` | Yes |
 | [`agent.queue()`](#agentqueue--fire-and-forget) | Start an automation, return immediately | `AgentRunAsyncResponse` | No |
 | [`agent.stream()`](#agentstream--real-time-events) | Stream live SSE events as the agent works | `AgentStream` | No |
+| [`fetch.get_contents()`](#fetchget_contents--clean-content) | Fetch extracted page content without running a browser agent | `FetchResponse` | Yes |
 | [`runs.get()`](#runsget--retrieve-a-single-run) | Retrieve a single run by ID | `Run` | — |
 | [`runs.list()`](#runslist--list-and-filter-runs) | List runs with filtering, sorting, pagination | `RunListResponse` | — |
+| [`search.query()`](#searchquery--search-the-web) | Search the web for ranked results | `SearchQueryResponse` | Yes |
 
 ---
 
@@ -75,6 +77,14 @@ response = client.agent.run(
         enabled=True,
         country_code=ProxyCountryCode.US,            # optional — US, GB, CA, DE, FR, JP, AU
     ),
+    output_schema={                                  # require structured output
+        "type": "object",
+        "properties": {
+            "headline_count": {"type": "integer"},
+            "top_headline": {"type": "string"},
+        },
+        "required": ["headline_count", "top_headline"],
+    },
 )
 
 if response.status == RunStatus.COMPLETED:
@@ -83,6 +93,12 @@ else:
     print(f"Failed: {response.error.message}")
 ```
 
+`output_schema` must be a top-level object. The SDK sends the schema to the API as-is; invalid schemas are rejected by
+the API before execution.
+
+The same `output_schema=` keyword is available on `client.agent.queue()` and `client.agent.stream()`.
+Persisted runs return the requested contract back as `run.output_schema`.
+
 **Returns `AgentRunResponse`:**
 
 | Field | Type | Description |
@@ -101,6 +117,8 @@ else:
 
 Starts the automation in the background and returns a `run_id` immediately. Poll with `runs.get()` when you're ready for the result.
 
+`queue()` accepts the same structured-output parameters as `run()`, including `output_schema=...`.
+
 ```python
 import time
 from tinyfish import TinyFish, RunStatus
@@ -167,6 +185,41 @@ See the [Streaming Guide](docs/streaming-guide.md) for the full event lifecycle,
 
 ---
 
+### `fetch.get_contents()` — clean content
+
+Fetch extracted content from one or more URLs without a browser-agent run.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.fetch.get_contents(
+    [
+        "https://example.com",
+        "https://example.org",
+    ],
+    format="markdown",
+    links=True,
+    image_links=False,
+    per_url_timeout_ms=45_000,
+)
+
+print(response.results)
+print(response.errors)
+```
+
+`fetch.get_contents()` accepts 1 to 10 URLs. Set `per_url_timeout_ms` to apply an independent timeout budget to each URL in the batch; slow URLs return in `errors` with `timeout` while siblings can still complete.
+
+**Returns `FetchResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `results` | `list[FetchResult]` | Successfully fetched URLs |
+| `errors` | `list[FetchError]` | URLs that failed to fetch or extract |
+
+---
+
 ### `runs.get()` — retrieve a single run
 
 Fetch the full details of a run by its ID.
@@ -179,6 +232,7 @@ run = client.runs.get(
 print(run.status)   # PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
 print(run.result)
 print(run.goal)
+print(run.output_schema)         # requested structured-output contract, if one was provided
 print(run.streaming_url)          # live browser URL (while RUNNING)
 print(run.browser_config)         # proxy/browser settings that were used
 ```
@@ -191,6 +245,7 @@ print(run.browser_config)         # proxy/browser settings that were used
 | `status` | `RunStatus` | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED` |
 | `goal` | `str` | The goal that was given |
 | `result` | `dict \| None` | Extracted data (`None` if not completed) |
+| `output_schema` | `dict \| None` | JSON Schema contract originally requested for the run |
 | `error` | `RunError \| None` | Error details (`None` if succeeded) |
 | `streaming_url` | `str \| None` | Live browser URL (available while running) |
 | `browser_config` | `BrowserConfig \| None` | Proxy/browser settings used |
@@ -240,6 +295,56 @@ See the [Pagination Guide](docs/pagination-guide.md) for full pagination loop ex
 
 ---
 
+### `search.query()` — search the web
+
+Returns ranked web search results with titles, snippets, and URLs.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.search.query("FIFA")
+
+print(response.query)
+print(response.total_results)
+print(response.results[0].title if response.results else "No results")
+```
+
+Optional parameters:
+
+- `location` — country code for geo-targeted results (e.g. `"US"`, `"GB"`)
+- `language` — language code (e.g. `"en"`, `"fr"`)
+- `page` — page number, 0-indexed, max `10`
+- `recency_minutes` — freshness window in minutes (`1` to `5256000`)
+- `after_date` / `before_date` — calendar date range in `YYYY-MM-DD`
+- `domain_type` — result category: `"web"` (default), `"news"`, or `"research_paper"`
+
+```python
+# geo-targeted
+response = client.search.query("FIFA", location="US", language="en")
+
+# freshness window
+response = client.search.query("FIFA", recency_minutes=60)
+
+# calendar date range
+response = client.search.query("FIFA", after_date="2026-06-01", before_date="2026-06-18")
+
+# domain type
+response = client.search.query("FIFA", domain_type="news")
+response = client.search.query("machine learning", domain_type="research_paper")
+```
+
+Filter validation rules:
+
+- `recency_minutes` must be an integer from `1` to `5256000`
+- `after_date` and `before_date` must use `YYYY-MM-DD`
+- `recency_minutes` cannot be combined with `after_date` or `before_date`
+- if both dates are present, `after_date` must be less than or equal to `before_date`
+- `domain_type` must be one of `"web"`, `"news"`, or `"research_paper"`
+
+---
+
 ## Sync vs Async
 
 Use `AsyncTinyFish` when you're in an async context (FastAPI, aiohttp, etc.):
@@ -262,7 +367,7 @@ client = AsyncTinyFish()
 response = await client.agent.run(goal="...", url="...")
 ```
 
-All five methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `runs.get()`, `runs.list()`) work the same way — same parameters, just `await`-ed.
+All seven methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `fetch.get_contents()`, `runs.get()`, `runs.list()`, `search.query()`) work the same way — same parameters, just `await`-ed.
 
 ## Configuration
 
@@ -296,6 +401,20 @@ response = client.agent.run(
 )
 ```
 
+### Browser Context Profiles
+
+Use Browser Context Profiles when a run should start from saved logged-in state. Pass `use_profile=True` for your default profile, or add `profile_id` for a specific profile. Pair with `use_vault=True` when TinyFish should repair stale sessions with saved credentials.
+
+```python
+response = client.agent.run(
+    goal="Summarize the dashboard",
+    url="https://app.example.com/dashboard",
+    use_profile=True,
+    profile_id="prof_abc123def4567890",
+    use_vault=True,
+)
+```
+
 ### Proxy configuration
 
 Route requests through a proxy, optionally pinned to a country:

{tinyfish-0.2.5 → tinyfish-0.3.0}/README.md

@@ -43,8 +43,10 @@ Every method below is available on both `TinyFish` (sync) and `AsyncTinyFish` (a
 | [`agent.run()`](#agentrun--block-until-done) | Run an automation, wait for the result | `AgentRunResponse` | Yes |
 | [`agent.queue()`](#agentqueue--fire-and-forget) | Start an automation, return immediately | `AgentRunAsyncResponse` | No |
 | [`agent.stream()`](#agentstream--real-time-events) | Stream live SSE events as the agent works | `AgentStream` | No |
+| [`fetch.get_contents()`](#fetchget_contents--clean-content) | Fetch extracted page content without running a browser agent | `FetchResponse` | Yes |
 | [`runs.get()`](#runsget--retrieve-a-single-run) | Retrieve a single run by ID | `Run` | — |
 | [`runs.list()`](#runslist--list-and-filter-runs) | List runs with filtering, sorting, pagination | `RunListResponse` | — |
+| [`search.query()`](#searchquery--search-the-web) | Search the web for ranked results | `SearchQueryResponse` | Yes |
 
 ---
 
@@ -65,6 +67,14 @@ response = client.agent.run(
         enabled=True,
         country_code=ProxyCountryCode.US,            # optional — US, GB, CA, DE, FR, JP, AU
     ),
+    output_schema={                                  # require structured output
+        "type": "object",
+        "properties": {
+            "headline_count": {"type": "integer"},
+            "top_headline": {"type": "string"},
+        },
+        "required": ["headline_count", "top_headline"],
+    },
 )
 
 if response.status == RunStatus.COMPLETED:
@@ -73,6 +83,12 @@ else:
     print(f"Failed: {response.error.message}")
 ```
 
+`output_schema` must be a top-level object. The SDK sends the schema to the API as-is; invalid schemas are rejected by
+the API before execution.
+
+The same `output_schema=` keyword is available on `client.agent.queue()` and `client.agent.stream()`.
+Persisted runs return the requested contract back as `run.output_schema`.
+
 **Returns `AgentRunResponse`:**
 
 | Field | Type | Description |
@@ -91,6 +107,8 @@ else:
 
 Starts the automation in the background and returns a `run_id` immediately. Poll with `runs.get()` when you're ready for the result.
 
+`queue()` accepts the same structured-output parameters as `run()`, including `output_schema=...`.
+
 ```python
 import time
 from tinyfish import TinyFish, RunStatus
@@ -157,6 +175,41 @@ See the [Streaming Guide](docs/streaming-guide.md) for the full event lifecycle,
 
 ---
 
+### `fetch.get_contents()` — clean content
+
+Fetch extracted content from one or more URLs without a browser-agent run.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.fetch.get_contents(
+    [
+        "https://example.com",
+        "https://example.org",
+    ],
+    format="markdown",
+    links=True,
+    image_links=False,
+    per_url_timeout_ms=45_000,
+)
+
+print(response.results)
+print(response.errors)
+```
+
+`fetch.get_contents()` accepts 1 to 10 URLs. Set `per_url_timeout_ms` to apply an independent timeout budget to each URL in the batch; slow URLs return in `errors` with `timeout` while siblings can still complete.
+
+**Returns `FetchResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `results` | `list[FetchResult]` | Successfully fetched URLs |
+| `errors` | `list[FetchError]` | URLs that failed to fetch or extract |
+
+---
+
 ### `runs.get()` — retrieve a single run
 
 Fetch the full details of a run by its ID.
@@ -169,6 +222,7 @@ run = client.runs.get(
 print(run.status)   # PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
 print(run.result)
 print(run.goal)
+print(run.output_schema)         # requested structured-output contract, if one was provided
 print(run.streaming_url)          # live browser URL (while RUNNING)
 print(run.browser_config)         # proxy/browser settings that were used
 ```
@@ -181,6 +235,7 @@ print(run.browser_config)         # proxy/browser settings that were used
 | `status` | `RunStatus` | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED` |
 | `goal` | `str` | The goal that was given |
 | `result` | `dict \| None` | Extracted data (`None` if not completed) |
+| `output_schema` | `dict \| None` | JSON Schema contract originally requested for the run |
 | `error` | `RunError \| None` | Error details (`None` if succeeded) |
 | `streaming_url` | `str \| None` | Live browser URL (available while running) |
 | `browser_config` | `BrowserConfig \| None` | Proxy/browser settings used |
@@ -230,6 +285,56 @@ See the [Pagination Guide](docs/pagination-guide.md) for full pagination loop ex
 
 ---
 
+### `search.query()` — search the web
+
+Returns ranked web search results with titles, snippets, and URLs.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.search.query("FIFA")
+
+print(response.query)
+print(response.total_results)
+print(response.results[0].title if response.results else "No results")
+```
+
+Optional parameters:
+
+- `location` — country code for geo-targeted results (e.g. `"US"`, `"GB"`)
+- `language` — language code (e.g. `"en"`, `"fr"`)
+- `page` — page number, 0-indexed, max `10`
+- `recency_minutes` — freshness window in minutes (`1` to `5256000`)
+- `after_date` / `before_date` — calendar date range in `YYYY-MM-DD`
+- `domain_type` — result category: `"web"` (default), `"news"`, or `"research_paper"`
+
+```python
+# geo-targeted
+response = client.search.query("FIFA", location="US", language="en")
+
+# freshness window
+response = client.search.query("FIFA", recency_minutes=60)
+
+# calendar date range
+response = client.search.query("FIFA", after_date="2026-06-01", before_date="2026-06-18")
+
+# domain type
+response = client.search.query("FIFA", domain_type="news")
+response = client.search.query("machine learning", domain_type="research_paper")
+```
+
+Filter validation rules:
+
+- `recency_minutes` must be an integer from `1` to `5256000`
+- `after_date` and `before_date` must use `YYYY-MM-DD`
+- `recency_minutes` cannot be combined with `after_date` or `before_date`
+- if both dates are present, `after_date` must be less than or equal to `before_date`
+- `domain_type` must be one of `"web"`, `"news"`, or `"research_paper"`
+
+---
+
 ## Sync vs Async
 
 Use `AsyncTinyFish` when you're in an async context (FastAPI, aiohttp, etc.):
@@ -252,7 +357,7 @@ client = AsyncTinyFish()
 response = await client.agent.run(goal="...", url="...")
 ```
 
-All five methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `runs.get()`, `runs.list()`) work the same way — same parameters, just `await`-ed.
+All seven methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `fetch.get_contents()`, `runs.get()`, `runs.list()`, `search.query()`) work the same way — same parameters, just `await`-ed.
 
 ## Configuration
 
@@ -286,6 +391,20 @@ response = client.agent.run(
 )
 ```
 
+### Browser Context Profiles
+
+Use Browser Context Profiles when a run should start from saved logged-in state. Pass `use_profile=True` for your default profile, or add `profile_id` for a specific profile. Pair with `use_vault=True` when TinyFish should repair stale sessions with saved credentials.
+
+```python
+response = client.agent.run(
+    goal="Summarize the dashboard",
+    url="https://app.example.com/dashboard",
+    use_profile=True,
+    profile_id="prof_abc123def4567890",
+    use_vault=True,
+)
+```
+
 ### Proxy configuration
 
 Route requests through a proxy, optionally pinned to a country:

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

@@ -19,25 +19,22 @@ This is a one-time change. Once merged and applied, the workflow will have acces
 
 ## Release process
 
-### Step 1: Bump the version
+### Step 1: Merge SDK changes to main
 
-Edit `sdk/sdk-python/pyproject.toml` and update the `version` field:
+Use conventional commits (`feat:`, `fix:`, `feat!:`) for changes under `sdk/sdk-python/`.
+After merge, `release-please.yml` opens or updates a Python SDK release PR with:
 
-```toml
-[project]
-version = "0.2.0"  # bump this
-```
+- `sdk/sdk-python/pyproject.toml` version bump
+- `sdk/sdk-python/CHANGELOG.md` release notes
+- `.github/release-please/manifest.json` version tracking
+
+Review and merge that release PR when you're ready to publish.
 
-Commit and merge to main.
+### Step 2: Release Please creates the GitHub Release
 
-### Step 2: Create a GitHub Release
+Merging the release PR creates a GitHub Release tagged with the Python SDK component:
 
-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 `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**
+- Version `0.2.7` → tag `sdk-py/v0.2.7`
 
 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.
 
@@ -52,15 +49,18 @@ Monitor progress at: `github.com/tinyfish-io/ux-labs/actions`
 
 ### Step 4: Verify
 
-After the workflow completes, verify the release:
+After the workflow completes, verify the release (replace `0.2.7` with the released version):
 
 ```bash
-pip install tinyfish==0.2.0
+pip install tinyfish==0.2.7
 python -c "from tinyfish import TinyFish; print('ok')"
 ```
 
 ## Troubleshooting
 
+**Manual release escape hatch**
+Use `workflow_dispatch` on `CD_sdk_python.yml` at a `sdk-py/v*` tag if Release Please created the tag but the publish workflow did not run.
+
 **Tag does not match pyproject.toml version**
 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.
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.2.5"
+version = "0.3.0"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,6 +10,12 @@ dependencies = [
     "tenacity>=8.0.0",
 ]
 
+[tool.uv]
+exclude-newer = "7 days"
+constraint-dependencies = [
+  "pygments>=2.20.0",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -20,8 +26,8 @@ packages = ["src/tinyfish"]
 [dependency-groups]
 dev = [
     "ruff>=0.15.2",
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.25.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
     "respx>=0.22.0",
     "python-dotenv>=1.2.2",
 ]

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

@@ -65,6 +65,21 @@ from .runs.types import (
 # Search types
 from .search.types import SearchQueryResponse, SearchResult
 
+# Vault types
+from .vault.types import (
+    FieldMetadata,
+    SyncSummary,
+    VaultConnection,
+    VaultConnectResponse,
+    VaultDisconnectResponse,
+    VaultFieldType,
+    VaultItem,
+    VaultListConnectionsResponse,
+    VaultListItemsResponse,
+    VaultProvider,
+    VaultSyncItemsResponse,
+)
+
 __version__ = version("tinyfish")
 
 __all__ = [
@@ -122,4 +137,16 @@ __all__ = [
     "RunStatus",
     "RunListResponse",
     "PaginationInfo",
+    # Vault types
+    "VaultProvider",
+    "VaultFieldType",
+    "FieldMetadata",
+    "VaultItem",
+    "VaultConnection",
+    "SyncSummary",
+    "VaultConnectResponse",
+    "VaultListConnectionsResponse",
+    "VaultDisconnectResponse",
+    "VaultListItemsResponse",
+    "VaultSyncItemsResponse",
 ]

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

@@ -131,6 +131,16 @@ class BaseAsyncAPIClient(_BaseClient):
         response = await self._request("POST", path, json=json)
         return self._parse_response(response, cast_to)
 
+    async def _delete(
+        self,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+    ) -> ResponseT:
+        """Make DELETE request and parse the response into cast_to."""
+        response = await self._request("DELETE", path)
+        return self._parse_response(response, cast_to)
+
     async def _post_stream(
         self,
         path: str,

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

@@ -131,6 +131,16 @@ class BaseSyncAPIClient(_BaseClient):
         response = self._request("POST", path, json=json)
         return self._parse_response(response, cast_to)
 
+    def _delete(
+        self,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+    ) -> ResponseT:
+        """Make DELETE request and parse the response into cast_to."""
+        response = self._request("DELETE", path)
+        return self._parse_response(response, cast_to)
+
     def _post_stream(
         self,
         path: str,

{tinyfish-0.2.5 → tinyfish-0.3.0}/src/tinyfish/_utils/resource.py

@@ -10,6 +10,7 @@ class BaseSyncAPIResource:
         self._client = client
         self._get = client._get
         self._post = client._post
+        self._delete = client._delete
         self._post_stream = client._post_stream
 
 
@@ -20,4 +21,5 @@ class BaseAsyncAPIResource:
         self._client = client
         self._get = client._get
         self._post = client._post
+        self._delete = client._delete
         self._post_stream = client._post_stream