tinyfish 0.3.0__tar.gz → 0.4.0__tar.gz

tinyfish-0.4.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.4.0](https://github.com/tinyfish-io/ux-labs/compare/sdk-py/v0.3.0...sdk-py/v0.4.0) (2026-07-23)
+
+
+### Features
+
+* **search:** add pub_year_min/pub_year_max publication-year filter ([#3691](https://github.com/tinyfish-io/ux-labs/issues/3691)) ([8728754](https://github.com/tinyfish-io/ux-labs/commit/8728754206fe4b7cf3a4ee8226c74bb364532869))
+* **search:** expose include_domains/exclude_domains in SDKs, CLI, MCP prose (ML-2084) ([#3692](https://github.com/tinyfish-io/ux-labs/issues/3692)) ([6c2079f](https://github.com/tinyfish-io/ux-labs/commit/6c2079f52872f9c9472cde8ec95d70280f25defa))
+
+## [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.3.0/README.md → tinyfish-0.4.0/PKG-INFO

@@ -1,3 +1,13 @@
+Metadata-Version: 2.4
+Name: tinyfish
+Version: 0.4.0
+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
+Description-Content-Type: text/markdown
+
 # TinyFish Python SDK
 
 The official Python SDK for [TinyFish](https://agent.tinyfish.ai)
@@ -309,6 +319,7 @@ Optional parameters:
 - `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"`
+- `pub_year_min` / `pub_year_max` — publication-year range, inclusive (`0` to `9999`). Only supported for `domain_type="research_paper"`
 
 ```python
 # geo-targeted
@@ -323,6 +334,11 @@ response = client.search.query("FIFA", after_date="2026-06-01", before_date="202
 # domain type
 response = client.search.query("FIFA", domain_type="news")
 response = client.search.query("machine learning", domain_type="research_paper")
+
+# publication-year range (research_paper only)
+response = client.search.query(
+    "transformer architecture", domain_type="research_paper", pub_year_min=2019, pub_year_max=2022
+)
 ```
 
 Filter validation rules:
@@ -332,6 +348,8 @@ Filter validation rules:
 - `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"`
+- `pub_year_min` and `pub_year_max` must be integers from `0` to `9999`
+- if both are present, `pub_year_min` must be less than or equal to `pub_year_max`
 
 ---
 

tinyfish-0.3.0/PKG-INFO → tinyfish-0.4.0/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.4
-Name: tinyfish
-Version: 0.3.0
-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
-Description-Content-Type: text/markdown
-
 # TinyFish Python SDK
 
 The official Python SDK for [TinyFish](https://agent.tinyfish.ai)
@@ -319,6 +309,7 @@ Optional parameters:
 - `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"`
+- `pub_year_min` / `pub_year_max` — publication-year range, inclusive (`0` to `9999`). Only supported for `domain_type="research_paper"`
 
 ```python
 # geo-targeted
@@ -333,6 +324,11 @@ response = client.search.query("FIFA", after_date="2026-06-01", before_date="202
 # domain type
 response = client.search.query("FIFA", domain_type="news")
 response = client.search.query("machine learning", domain_type="research_paper")
+
+# publication-year range (research_paper only)
+response = client.search.query(
+    "transformer architecture", domain_type="research_paper", pub_year_min=2019, pub_year_max=2022
+)
 ```
 
 Filter validation rules:
@@ -342,6 +338,8 @@ Filter validation rules:
 - `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"`
+- `pub_year_min` and `pub_year_max` must be integers from `0` to `9999`
+- if both are present, `pub_year_min` must be less than or equal to `pub_year_max`
 
 ---
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"

{tinyfish-0.3.0 → tinyfish-0.4.0}/src/tinyfish/search/__init__.py

@@ -26,16 +26,27 @@ def _validate_iso_date(field_name: str, value: str) -> str:
     return value
 
 
+def _validate_pub_year(field_name: str, value: int) -> None:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{field_name} must be an integer")
+    if not 0 <= value <= 9999:
+        raise ValueError(f"{field_name} must be between 0 and 9999")
+
+
 def _build_search_params(
     *,
     query: str,
     purpose: str | None = None,
     location: str | None = None,
     language: str | None = None,
+    include_domains: str | None = None,
+    exclude_domains: str | None = None,
     after_date: str | None = None,
     before_date: str | None = None,
     recency_minutes: int | None = None,
     domain_type: str | None = None,
+    pub_year_min: int | None = None,
+    pub_year_max: int | None = None,
     page: int | None = None,
 ) -> dict[str, str]:
     if not query or not query.strip():
@@ -67,6 +78,12 @@ def _build_search_params(
         raise ValueError("recency_minutes cannot be combined with after_date or before_date")
     if after_date is not None and before_date is not None and after_date > before_date:
         raise ValueError("after_date must be on or before before_date")
+    if pub_year_min is not None:
+        _validate_pub_year("pub_year_min", pub_year_min)
+    if pub_year_max is not None:
+        _validate_pub_year("pub_year_max", pub_year_max)
+    if pub_year_min is not None and pub_year_max is not None and pub_year_min > pub_year_max:
+        raise ValueError("pub_year_min must be less than or equal to pub_year_max")
 
     params: dict[str, str] = {"query": query}
     if purpose is not None:
@@ -75,6 +92,10 @@ def _build_search_params(
         params["location"] = location
     if language is not None:
         params["language"] = language
+    if include_domains is not None:
+        params["include_domains"] = include_domains
+    if exclude_domains is not None:
+        params["exclude_domains"] = exclude_domains
     if after_date is not None:
         params["after_date"] = after_date
     if before_date is not None:
@@ -83,6 +104,11 @@ def _build_search_params(
         params["recency_minutes"] = str(recency_minutes)
     if domain_type is not None:
         params["domain_type"] = domain_type
+    # browser-search requires a 4-character year string, so zero-pad (e.g. 500 -> "0500").
+    if pub_year_min is not None:
+        params["pub_year_min"] = f"{pub_year_min:04d}"
+    if pub_year_max is not None:
+        params["pub_year_max"] = f"{pub_year_max:04d}"
     if page is not None:
         params["page"] = str(page)
     return params
@@ -98,10 +124,14 @@ class SearchResource(BaseSyncAPIResource):
         purpose: str | None = None,
         location: str | None = None,
         language: str | None = None,
+        include_domains: str | None = None,
+        exclude_domains: str | None = None,
         after_date: str | None = None,
         before_date: str | None = None,
         recency_minutes: int | None = None,
         domain_type: str | None = None,
+        pub_year_min: int | None = None,
+        pub_year_max: int | None = None,
         page: int | None = None,
     ) -> SearchQueryResponse:
         """Execute a web search query.
@@ -115,10 +145,18 @@ class SearchResource(BaseSyncAPIResource):
                 characters.
             location: Optional location to scope results (e.g. "United States").
             language: Optional language code (e.g. "en").
+            include_domains: Optional comma-separated list of domains to restrict
+                results to (e.g. "github.com,arxiv.org").
+            exclude_domains: Optional comma-separated list of domains to exclude
+                from results (e.g. "pinterest.com,quora.com").
             after_date: Optional date cutoff in YYYY-MM-DD format.
             before_date: Optional date cutoff in YYYY-MM-DD format.
             recency_minutes: Optional rolling freshness window in minutes (1 to 5256000).
             domain_type: Optional search type — "web" (default), "news", or "research_paper".
+            pub_year_min: Optional minimum publication year, inclusive (0 to 9999). Only
+                supported for domain_type="research_paper".
+            pub_year_max: Optional maximum publication year, inclusive (0 to 9999). Only
+                supported for domain_type="research_paper".
             page: Result page for pagination.
 
         Returns:
@@ -135,10 +173,14 @@ class SearchResource(BaseSyncAPIResource):
             purpose=purpose,
             location=location,
             language=language,
+            include_domains=include_domains,
+            exclude_domains=exclude_domains,
             after_date=after_date,
             before_date=before_date,
             recency_minutes=recency_minutes,
             domain_type=domain_type,
+            pub_year_min=pub_year_min,
+            pub_year_max=pub_year_max,
             page=page,
         )
         return self._get("/v1/search", params=params, cast_to=SearchQueryResponse)
@@ -154,10 +196,14 @@ class AsyncSearchResource(BaseAsyncAPIResource):
         purpose: str | None = None,
         location: str | None = None,
         language: str | None = None,
+        include_domains: str | None = None,
+        exclude_domains: str | None = None,
         after_date: str | None = None,
         before_date: str | None = None,
         recency_minutes: int | None = None,
         domain_type: str | None = None,
+        pub_year_min: int | None = None,
+        pub_year_max: int | None = None,
         page: int | None = None,
     ) -> SearchQueryResponse:
         """Execute a web search query.
@@ -173,10 +219,18 @@ class AsyncSearchResource(BaseAsyncAPIResource):
                 characters.
             location: Optional location to scope results (e.g. "United States").
             language: Optional language code (e.g. "en").
+            include_domains: Optional comma-separated list of domains to restrict
+                results to (e.g. "github.com,arxiv.org").
+            exclude_domains: Optional comma-separated list of domains to exclude
+                from results (e.g. "pinterest.com,quora.com").
             after_date: Optional date cutoff in YYYY-MM-DD format.
             before_date: Optional date cutoff in YYYY-MM-DD format.
             recency_minutes: Optional rolling freshness window in minutes (1 to 5256000).
             domain_type: Optional search type — "web" (default), "news", or "research_paper".
+            pub_year_min: Optional minimum publication year, inclusive (0 to 9999). Only
+                supported for domain_type="research_paper".
+            pub_year_max: Optional maximum publication year, inclusive (0 to 9999). Only
+                supported for domain_type="research_paper".
             page: Result page for pagination.
 
         Returns:
@@ -193,10 +247,14 @@ class AsyncSearchResource(BaseAsyncAPIResource):
             purpose=purpose,
             location=location,
             language=language,
+            include_domains=include_domains,
+            exclude_domains=exclude_domains,
             after_date=after_date,
             before_date=before_date,
             recency_minutes=recency_minutes,
             domain_type=domain_type,
+            pub_year_min=pub_year_min,
+            pub_year_max=pub_year_max,
             page=page,
         )
         return await self._get("/v1/search", params=params, cast_to=SearchQueryResponse)

{tinyfish-0.3.0 → tinyfish-0.4.0}/tests/test_search.py

@@ -88,6 +88,8 @@ def test_query_parses_result_fields(client: TinyFish, respx_mock: MockRouter):
         ),
         ({"location": "United States"}, "location", "United States"),
         ({"language": "en"}, "language", "en"),
+        ({"include_domains": "github.com,arxiv.org"}, "include_domains", "github.com,arxiv.org"),
+        ({"exclude_domains": "pinterest.com"}, "exclude_domains", "pinterest.com"),
         ({"after_date": "2026-06-01"}, "after_date", "2026-06-01"),
         ({"before_date": "2026-06-18"}, "before_date", "2026-06-18"),
         ({"recency_minutes": 60}, "recency_minutes", "60"),
@@ -195,6 +197,17 @@ def test_query_rejects_non_integer_page(bad_page: Any, client: TinyFish):
             {"after_date": "2026-06-18", "before_date": "2026-06-01"},
             "after_date must be on or before before_date",
         ),
+        ({"pub_year_min": True}, "pub_year_min must be an integer"),
+        ({"pub_year_min": 1.5}, "pub_year_min must be an integer"),
+        ({"pub_year_min": -1}, "pub_year_min must be between 0 and 9999"),
+        ({"pub_year_max": True}, "pub_year_max must be an integer"),
+        ({"pub_year_max": 1.5}, "pub_year_max must be an integer"),
+        ({"pub_year_max": -1}, "pub_year_max must be between 0 and 9999"),
+        ({"pub_year_max": 10_000}, "pub_year_max must be between 0 and 9999"),
+        (
+            {"pub_year_min": 2022, "pub_year_max": 2019},
+            "pub_year_min must be less than or equal to pub_year_max",
+        ),
     ],
 )
 def test_query_rejects_invalid_search_filters(
@@ -238,6 +251,48 @@ def test_query_rejects_invalid_domain_type(client: TinyFish):
         client.search.query("test", domain_type="video")
 
 
+@pytest.mark.parametrize(
+    ("pub_year_min", "pub_year_max", "expected_min", "expected_max"),
+    [
+        (2019, 2022, "2019", "2022"),
+        (500, 999, "0500", "0999"),
+        (0, 0, "0000", "0000"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_forwards_pub_year_zero_padded(
+    pub_year_min: int,
+    pub_year_max: int,
+    expected_min: str,
+    expected_max: str,
+    client: TinyFish,
+    respx_mock: MockRouter,
+):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test", domain_type="research_paper", pub_year_min=pub_year_min, pub_year_max=pub_year_max)
+    params = route.calls[0].request.url.params
+    assert params["pub_year_min"] == expected_min
+    assert params["pub_year_max"] == expected_max
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_forwards_pub_year_min_only(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test", domain_type="research_paper", pub_year_min=2019)
+    params = route.calls[0].request.url.params
+    assert params["pub_year_min"] == "2019"
+    assert "pub_year_max" not in params
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_forwards_pub_year_max_only(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test", domain_type="research_paper", pub_year_max=2022)
+    params = route.calls[0].request.url.params
+    assert "pub_year_min" not in params
+    assert params["pub_year_max"] == "2022"
+
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # search.query() — async (mirrors sync tests above)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -275,6 +330,8 @@ async def test_async_query_parses_result_fields(async_client: AsyncTinyFish, res
         ),
         ({"location": "United States"}, "location", "United States"),
         ({"language": "en"}, "language", "en"),
+        ({"include_domains": "github.com,arxiv.org"}, "include_domains", "github.com,arxiv.org"),
+        ({"exclude_domains": "pinterest.com"}, "exclude_domains", "pinterest.com"),
         ({"after_date": "2026-06-01"}, "after_date", "2026-06-01"),
         ({"before_date": "2026-06-18"}, "before_date", "2026-06-18"),
         ({"recency_minutes": 60}, "recency_minutes", "60"),
@@ -371,6 +428,17 @@ async def test_async_query_rejects_non_integer_page(
             {"after_date": "2026-06-18", "before_date": "2026-06-01"},
             "after_date must be on or before before_date",
         ),
+        ({"pub_year_min": True}, "pub_year_min must be an integer"),
+        ({"pub_year_min": 1.5}, "pub_year_min must be an integer"),
+        ({"pub_year_min": -1}, "pub_year_min must be between 0 and 9999"),
+        ({"pub_year_max": True}, "pub_year_max must be an integer"),
+        ({"pub_year_max": 1.5}, "pub_year_max must be an integer"),
+        ({"pub_year_max": -1}, "pub_year_max must be between 0 and 9999"),
+        ({"pub_year_max": 10_000}, "pub_year_max must be between 0 and 9999"),
+        (
+            {"pub_year_min": 2022, "pub_year_max": 2019},
+            "pub_year_min must be less than or equal to pub_year_max",
+        ),
     ],
 )
 async def test_async_query_rejects_invalid_search_filters(
@@ -407,6 +475,54 @@ async def test_async_query_rejects_invalid_domain_type(async_client: AsyncTinyFi
         await _do_query(async_client, "test", domain_type="video")
 
 
+@pytest.mark.parametrize(
+    ("pub_year_min", "pub_year_max", "expected_min", "expected_max"),
+    [
+        (2019, 2022, "2019", "2022"),
+        (500, 999, "0500", "0999"),
+        (0, 0, "0000", "0000"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_forwards_pub_year_zero_padded(
+    pub_year_min: int,
+    pub_year_max: int,
+    expected_min: str,
+    expected_max: str,
+    async_client: AsyncTinyFish,
+    respx_mock: MockRouter,
+):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(
+        async_client,
+        "test",
+        domain_type="research_paper",
+        pub_year_min=pub_year_min,
+        pub_year_max=pub_year_max,
+    )
+    params = route.calls[0].request.url.params
+    assert params["pub_year_min"] == expected_min
+    assert params["pub_year_max"] == expected_max
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_forwards_pub_year_min_only(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(async_client, "test", domain_type="research_paper", pub_year_min=2019)
+    params = route.calls[0].request.url.params
+    assert params["pub_year_min"] == "2019"
+    assert "pub_year_max" not in params
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_forwards_pub_year_max_only(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(async_client, "test", domain_type="research_paper", pub_year_max=2022)
+    params = route.calls[0].request.url.params
+    assert "pub_year_min" not in params
+    assert params["pub_year_max"] == "2022"
+
+
 @pytest.mark.respx(base_url=BASE_URL)
 async def test_async_query_401(async_client: AsyncTinyFish, respx_mock: MockRouter):
     respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(401, json={"error": {"message": "unauthorized"}}))

tinyfish-0.3.0/CHANGELOG.md

@@ -1,9 +0,0 @@
-# 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))