tinyfish 0.2.5__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfish
-Version: 0.2.5
+Version: 0.2.6
 Summary: Official Python SDK for the TinyFish API
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
@@ -75,6 +75,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 +91,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 +115,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
@@ -179,6 +195,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 +208,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 |
@@ -296,6 +314,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.2.6}/README.md

@@ -65,6 +65,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 +81,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 +105,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
@@ -169,6 +185,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 +198,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 |
@@ -286,6 +304,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.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.2.5"
+version = "0.2.6"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,6 +10,11 @@ dependencies = [
     "tenacity>=8.0.0",
 ]
 
+[tool.uv]
+constraint-dependencies = [
+  "pygments>=2.20.0",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -20,8 +25,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.2.6}/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.2.6}/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.2.6}/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.2.6}/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

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

@@ -27,12 +27,32 @@ def _build_run_body(
     url: str,
     browser_profile: BrowserProfile | None,
     proxy_config: ProxyConfig | None,
+    output_schema: dict[str, Any] | None,
+    use_profile: bool | None = None,
+    profile_id: str | None = None,
+    use_vault: bool | None = None,
+    credential_item_ids: list[str] | None = None,
 ) -> dict[str, Any]:
     body: dict[str, Any] = {"goal": goal, "url": url}
     if browser_profile is not None:
         body["browser_profile"] = browser_profile
     if proxy_config is not None:
         body["proxy_config"] = proxy_config.model_dump(exclude_none=True)
+    if output_schema is not None:
+        body["output_schema"] = output_schema
+    if use_profile is not None:
+        body["use_profile"] = use_profile
+    if profile_id is not None:
+        profile_id = profile_id.strip()
+        if not profile_id:
+            raise ValueError("profile_id must be a non-empty string")
+        if use_profile is not True:
+            raise ValueError("profile_id requires use_profile=True")
+        body["profile_id"] = profile_id
+    if use_vault is not None:
+        body["use_vault"] = use_vault
+    if credential_item_ids is not None:
+        body["credential_item_ids"] = credential_item_ids
     return body
 
 
@@ -106,6 +126,11 @@ class AgentResource(BaseSyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
     ) -> AgentRunResponse:
         """Run a browser automation and wait for it to finish.
 
@@ -117,6 +142,11 @@ class AgentResource(BaseSyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
 
         Returns:
             AgentRunResponse with status, result, and timing info.
@@ -126,7 +156,17 @@ class AgentResource(BaseSyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
         return self._post("/v1/automation/run", json=body, cast_to=AgentRunResponse)
 
     def queue(
@@ -136,6 +176,11 @@ class AgentResource(BaseSyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
     ) -> AgentRunAsyncResponse:
         """Queue a browser automation and return immediately.
 
@@ -147,6 +192,11 @@ class AgentResource(BaseSyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
 
         Returns:
             AgentRunAsyncResponse with the run_id to poll later.
@@ -156,7 +206,17 @@ class AgentResource(BaseSyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
         return self._post("/v1/automation/run-async", json=body, cast_to=AgentRunAsyncResponse)
 
     def stream(
@@ -166,6 +226,11 @@ class AgentResource(BaseSyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
         on_started: Callable[[StartedEvent], None] | None = None,
         on_streaming_url: Callable[[StreamingUrlEvent], None] | None = None,
         on_progress: Callable[[ProgressEvent], None] | None = None,
@@ -202,6 +267,11 @@ class AgentResource(BaseSyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
             on_started: Called when the run starts (receives StartedEvent).
             on_streaming_url: Called with the live browser stream URL (receives StreamingUrlEvent).
             on_progress: Called on each automation step (receives ProgressEvent).
@@ -216,7 +286,17 @@ class AgentResource(BaseSyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
 
         def _generate() -> Iterator[AgentRunWithStreamingResponse]:
             lines = self._post_stream("/v1/automation/run-sse", json=body)
@@ -261,6 +341,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
     ) -> AgentRunResponse:
         """Run a browser automation and wait for it to finish.
 
@@ -272,6 +357,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
 
         Returns:
             AgentRunResponse with status, result, and timing info.
@@ -281,7 +371,17 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
         return await self._post("/v1/automation/run", json=body, cast_to=AgentRunResponse)
 
     async def queue(
@@ -291,6 +391,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
     ) -> AgentRunAsyncResponse:
         """Queue a browser automation and return immediately.
 
@@ -302,6 +407,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
 
         Returns:
             AgentRunAsyncResponse with the run_id to poll later.
@@ -311,7 +421,17 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
         return await self._post("/v1/automation/run-async", json=body, cast_to=AgentRunAsyncResponse)
 
     def stream(
@@ -321,6 +441,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
         url: str,
         browser_profile: BrowserProfile | None = None,
         proxy_config: ProxyConfig | None = None,
+        output_schema: dict[str, Any] | None = None,
+        use_profile: bool | None = None,
+        profile_id: str | None = None,
+        use_vault: bool | None = None,
+        credential_item_ids: list[str] | None = None,
         on_started: Callable[[StartedEvent], None] | None = None,
         on_streaming_url: Callable[[StreamingUrlEvent], None] | None = None,
         on_progress: Callable[[ProgressEvent], None] | None = None,
@@ -357,6 +482,11 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             url: The URL to open the browser on.
             browser_profile: "lite" (default) or "stealth" (anti-detection).
             proxy_config: Optional proxy settings (enabled, country_code).
+            output_schema: Optional JSON Schema object describing the expected final result.
+            use_profile: Whether to start from a saved Browser Context Profile.
+            profile_id: Specific Browser Context Profile ID. Requires use_profile=True.
+            use_vault: Whether to use stored vault credentials for authentication.
+            credential_item_ids: Specific vault item IDs to use. When omitted, all matching credentials are available.
             on_started: Called when the run starts (receives StartedEvent).
             on_streaming_url: Called with the live browser stream URL (receives StreamingUrlEvent).
             on_progress: Called on each automation step (receives ProgressEvent).
@@ -371,7 +501,17 @@ class AsyncAgentResource(BaseAsyncAPIResource):
             RateLimitError: Too many requests.
             InternalServerError: Something went wrong on the server.
         """
-        body = _build_run_body(goal, url, browser_profile, proxy_config)
+        body = _build_run_body(
+            goal,
+            url,
+            browser_profile,
+            proxy_config,
+            output_schema,
+            use_profile,
+            profile_id,
+            use_vault,
+            credential_item_ids,
+        )
 
         async def _generate() -> AsyncIterator[AgentRunWithStreamingResponse]:
             lines = self._post_stream("/v1/automation/run-sse", json=body)

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

@@ -8,6 +8,7 @@ from .browser import AsyncBrowserResource, BrowserResource
 from .fetch import AsyncFetchResource, FetchResource
 from .runs import AsyncRunsResource, RunsResource
 from .search import AsyncSearchResource, SearchResource
+from .vault import AsyncVaultResource, VaultResource
 
 __all__ = ["TinyFish", "AsyncTinyFish"]
 
@@ -28,6 +29,7 @@ class TinyFish(BaseSyncAPIClient):
     fetch: FetchResource
     runs: RunsResource
     search: SearchResource
+    vault: VaultResource
 
     def __init__(
         self,
@@ -52,6 +54,7 @@ class TinyFish(BaseSyncAPIClient):
         self.fetch = FetchResource(self)
         self.runs = RunsResource(self)
         self.search = SearchResource(self)
+        self.vault = VaultResource(self)
 
 
 class AsyncTinyFish(BaseAsyncAPIClient):
@@ -65,6 +68,7 @@ class AsyncTinyFish(BaseAsyncAPIClient):
     fetch: AsyncFetchResource
     runs: AsyncRunsResource
     search: AsyncSearchResource
+    vault: AsyncVaultResource
 
     def __init__(
         self,
@@ -89,3 +93,4 @@ class AsyncTinyFish(BaseAsyncAPIClient):
         self.fetch = AsyncFetchResource(self)
         self.runs = AsyncRunsResource(self)
         self.search = AsyncSearchResource(self)
+        self.vault = AsyncVaultResource(self)