ateve 0.2.0__tar.gz → 0.2.2__tar.gz

{ateve-0.2.0 → ateve-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ateve
-Version: 0.2.0
+Version: 0.2.2
 Summary: Official Python SDK for the Ateve Search API
 Project-URL: Homepage, https://ateve.ai
 Project-URL: Documentation, https://ateve.ai/docs
@@ -81,20 +81,32 @@ decisions remain caller-owned.
 
 ## Search contract limits
 
-Use `max_results` (1–100, default 10); `limit` and `offset` have been removed.
-`ContentOptions.snippet` is optional and defaults to `True`. To retrieve full
-text, pass `content=ContentOptions(text=TextOptions())`, or configure
+Use `max_results` to set the maximum number of results (1–100, default 10).
+`limit` and `offset` have been removed. Both synchronous and asynchronous
+clients accept `content` and `max_results`, or a `SearchRequest` instance.
+
+Snippets are always returned and cannot be disabled. To request full text, pass
+`content=ContentOptions(text=TextOptions())`. To customize the output, use
 `TextOptions(max_characters=8000, format=ContentFormat.MARKDOWN)`.
-`format` accepts `"text"` (default) or `"markdown"`. Omitting `text` does not
-request full text. `max_characters` remains a strict positive signed 32-bit
-integer; its server default is 5000 per result, applied after format conversion.
-`summary` and `highlights` have been removed from `ContentOptions`; `favicon`
-remains optional. Both synchronous and asynchronous clients accept `content`
-and `max_results`, or a `SearchRequest` instance.
-
-Both formats return content in `SearchResult.text`. It defaults to `None` when
-absent or when extraction fails; `model_fields_set` distinguishes those cases.
-Snippets may coexist with text; set `ContentOptions(snippet=False)` to omit
-them. Obsolete answer, usage, news/video, query tuning and raw content/summary/
-highlights response fields and models have been removed. Unknown response
-fields continue to be retained by Pydantic for forward compatibility.
+`format` accepts `ContentFormat.TEXT` (default) or `ContentFormat.MARKDOWN`.
+Full text is requested only when `text` is supplied. `max_characters` must be a
+strict positive signed 32-bit integer. The server default is 5,000 characters
+per result, applied after format conversion. Both formats return content in
+`SearchResult.text`, which is `None` when absent or when extraction fails.
+`model_fields_set` distinguishes those cases. Full text is returned alongside
+snippets.
+
+Highlights are optional and disabled by default. Set
+`content=ContentOptions(highlights=True)` to return concise, query-relevant
+excerpts in addition to snippets. `SearchResult.highlights` is a `list[str]`, or
+`None` when the field is absent. Highlights can coexist with snippets and full text.
+
+For token-efficient workflows, your agent can prioritize highlights when building
+model context and supplement them with snippets when additional context is needed.
+When the API returns both fields, token savings depend on which content your
+agent passes to the model.
+
+`summary` and the snippet toggle have been removed from `ContentOptions`.
+`favicon` remains optional under `content`. Obsolete answer, usage, news/video,
+query tuning, and raw content/summary response fields and models have been removed.
+Unknown response fields continue to be retained by Pydantic for forward compatibility.

{ateve-0.2.0 → ateve-0.2.2}/README.md

@@ -55,20 +55,32 @@ decisions remain caller-owned.
 
 ## Search contract limits
 
-Use `max_results` (1–100, default 10); `limit` and `offset` have been removed.
-`ContentOptions.snippet` is optional and defaults to `True`. To retrieve full
-text, pass `content=ContentOptions(text=TextOptions())`, or configure
+Use `max_results` to set the maximum number of results (1–100, default 10).
+`limit` and `offset` have been removed. Both synchronous and asynchronous
+clients accept `content` and `max_results`, or a `SearchRequest` instance.
+
+Snippets are always returned and cannot be disabled. To request full text, pass
+`content=ContentOptions(text=TextOptions())`. To customize the output, use
 `TextOptions(max_characters=8000, format=ContentFormat.MARKDOWN)`.
-`format` accepts `"text"` (default) or `"markdown"`. Omitting `text` does not
-request full text. `max_characters` remains a strict positive signed 32-bit
-integer; its server default is 5000 per result, applied after format conversion.
-`summary` and `highlights` have been removed from `ContentOptions`; `favicon`
-remains optional. Both synchronous and asynchronous clients accept `content`
-and `max_results`, or a `SearchRequest` instance.
-
-Both formats return content in `SearchResult.text`. It defaults to `None` when
-absent or when extraction fails; `model_fields_set` distinguishes those cases.
-Snippets may coexist with text; set `ContentOptions(snippet=False)` to omit
-them. Obsolete answer, usage, news/video, query tuning and raw content/summary/
-highlights response fields and models have been removed. Unknown response
-fields continue to be retained by Pydantic for forward compatibility.
+`format` accepts `ContentFormat.TEXT` (default) or `ContentFormat.MARKDOWN`.
+Full text is requested only when `text` is supplied. `max_characters` must be a
+strict positive signed 32-bit integer. The server default is 5,000 characters
+per result, applied after format conversion. Both formats return content in
+`SearchResult.text`, which is `None` when absent or when extraction fails.
+`model_fields_set` distinguishes those cases. Full text is returned alongside
+snippets.
+
+Highlights are optional and disabled by default. Set
+`content=ContentOptions(highlights=True)` to return concise, query-relevant
+excerpts in addition to snippets. `SearchResult.highlights` is a `list[str]`, or
+`None` when the field is absent. Highlights can coexist with snippets and full text.
+
+For token-efficient workflows, your agent can prioritize highlights when building
+model context and supplement them with snippets when additional context is needed.
+When the API returns both fields, token savings depend on which content your
+agent passes to the model.
+
+`summary` and the snippet toggle have been removed from `ContentOptions`.
+`favicon` remains optional under `content`. Obsolete answer, usage, news/video,
+query tuning, and raw content/summary response fields and models have been removed.
+Unknown response fields continue to be retained by Pydantic for forward compatibility.

{ateve-0.2.0 → ateve-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ateve"
-version = "0.2.0"
+version = "0.2.2"
 description = "Official Python SDK for the Ateve Search API"
 readme = "README.md"
 requires-python = ">=3.11"

ateve-0.2.2/src/ateve/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{ateve-0.2.0 → ateve-0.2.2}/src/ateve/models.py

@@ -87,7 +87,7 @@ class TextOptions(RequestModel):
 
 
 class ContentOptions(RequestModel):
-    snippet: Optional[bool] = Field(default=True)
+    highlights: Optional[bool] = Field(default=False)
     text: Optional[TextOptions] = None
     favicon: Optional[bool] = None
 
@@ -144,6 +144,7 @@ class SearchResult(ResponseModel):
     published_at: Optional[datetime] = None
     score: Optional[float] = None
     snippet: Optional[str] = None
+    highlights: Optional[List[str]] = None
     text: Optional[str] = None
     favicon: Optional[str] = None
     images: List[ImageItem] = Field(default_factory=list)

{ateve-0.2.0 → ateve-0.2.2}/tests/test_client.py

@@ -57,7 +57,8 @@ def test_sync_golden_contract_and_wire_names() -> None:
         date_range="2026-01-01..2026-06-30",
         locale=LocaleSettings(mkt="US", language="en"),
         content=ContentOptions(
-            snippet=False, text=TextOptions(format=ContentFormat.MARKDOWN, max_characters=5000)
+            highlights=True,
+            text=TextOptions(format=ContentFormat.MARKDOWN, max_characters=5000)
         ),
         safe_search=False,
     )
@@ -66,7 +67,8 @@ def test_sync_golden_contract_and_wire_names() -> None:
     assert payload["date_range"] == "2026-01-01..2026-06-30"
     assert payload["safe_search"] is False
     assert payload["max_results"] == 20
-    assert payload["content"]["snippet"] is False
+    assert "snippet" not in payload["content"]
+    assert payload["content"]["highlights"] is True
     assert not {"limit", "offset", "contents"}.intersection(payload)
     assert payload["content"]["text"]["max_characters"] == 5000
     assert "images" not in payload["content"]
@@ -77,6 +79,7 @@ def test_sync_golden_contract_and_wire_names() -> None:
     assert captured[0].headers["User-Agent"] == f"ateve-python/{__version__}"
     assert response.id == "req_01J9ZK3V6XQ8"
     assert response.results[0].published_at is not None
+    assert response.results[0].highlights == GOLDEN_RESPONSE["results"][0]["highlights"]
     assert response.query.original == "climate policy analysis"
     assert response.total_estimated_matches == 128000
 
@@ -341,7 +344,10 @@ def test_sync_and_async_send_new_defaults_and_nested_text_options() -> None:
             httpx.AsyncClient(transport=httpx.MockTransport(handler)) as transport,
             AsyncAteve("sk_test", http_client=transport) as client,
         ):
-            await client.search("q", max_results=100, content=ContentOptions(snippet=False))
+            response = await client.search(
+                "q", max_results=100, content=ContentOptions(highlights=True)
+            )
+            assert response.results[0].highlights == GOLDEN_RESPONSE["results"][0]["highlights"]
             await client.search(
                 SearchRequest(query="q", content=ContentOptions(text=TextOptions()))
             )
@@ -352,12 +358,12 @@ def test_sync_and_async_send_new_defaults_and_nested_text_options() -> None:
         {
             "query": "q",
             "max_results": 10,
-            "content": {"snippet": True, "text": {"format": "text"}},
+            "content": {"highlights": False, "text": {"format": "text"}},
         },
-        {"query": "q", "max_results": 100, "content": {"snippet": False}},
+        {"query": "q", "max_results": 100, "content": {"highlights": True}},
         {
             "query": "q",
             "max_results": 10,
-            "content": {"snippet": True, "text": {"format": "text"}},
+            "content": {"highlights": False, "text": {"format": "text"}},
         },
     ]

{ateve-0.2.0 → ateve-0.2.2}/tests/test_models.py

@@ -25,6 +25,8 @@ def test_request_models_preserve_validation_and_frozen_configuration() -> None:
         request.query = "changed"
     with pytest.raises(ValidationError):
         TextOptions(max_characters=True)
+    with pytest.raises(ValidationError, match="snippet"):
+        ContentOptions.model_validate({"snippet": False})
 
 
 def test_response_models_preserve_defaults_nulls_extra_fields_and_dates() -> None:
@@ -54,16 +56,31 @@ def test_request_lists_are_snapshots_and_wire_names_stay_snake_case() -> None:
 
 def test_request_defaults_and_nested_text_activation() -> None:
     assert SearchRequest(query="q").max_results == 10
-    assert ContentOptions().snippet is True
+    assert ContentOptions().highlights is False
     assert ContentOptions().text is None
     assert TextOptions().format == ContentFormat.TEXT
     request = SearchRequest(query="q", content=ContentOptions(text=TextOptions()))
     assert request.model_dump(mode="json", exclude_none=True) == {
         "query": "q",
         "max_results": 10,
-        "content": {"snippet": True, "text": {"format": "text"}},
+        "content": {"highlights": False, "text": {"format": "text"}},
     }
-    assert ContentOptions(snippet=False).model_dump(exclude_none=True) == {"snippet": False}
+    assert ContentOptions(highlights=True).highlights is True
+
+
+def test_highlights_are_typed_and_preserve_missing_and_empty_values() -> None:
+    missing = SearchResult()
+    assert missing.highlights is None
+    assert "highlights" not in missing.model_fields_set
+    result = SearchResult(snippet="excerpt", highlights=["Answer support", "Further evidence"])
+    assert result.snippet == "excerpt"
+    assert result.highlights == ["Answer support", "Further evidence"]
+    assert result.model_extra == {}
+    assert SearchResult(highlights=[]).highlights == []
+    with pytest.raises(ValidationError):
+        SearchResult.model_validate({"highlights": "excerpt"})
+    with pytest.raises(ValidationError):
+        SearchResult.model_validate({"highlights": [1]})
 
 
 @pytest.mark.parametrize("value", [0, -1, 101])
@@ -87,7 +104,6 @@ def test_removed_request_fields_and_invalid_text_options_are_rejected() -> None:
             SearchRequest.model_validate({"query": "q", name: value})
     for name, value in [
         ("summary", True),
-        ("highlights", True),
         ("raw_content", True),
         ("max_characters", 100),
         ("format", "text"),
@@ -99,7 +115,10 @@ def test_removed_request_fields_and_invalid_text_options_are_rejected() -> None:
             ContentOptions.model_validate({"text": value})
 
 
-@pytest.mark.parametrize("scenario", ["default", "text", "markdown", "no-snippet"])
+@pytest.mark.parametrize("scenario", [
+    "default", "text", "markdown", "no-snippet",
+    "highlights", "highlights-no-snippet", "highlights-markdown",
+])
 def test_captured_live_responses_preserve_missing_and_null_text(scenario: str) -> None:
     fixture = (
         Path(__file__).resolve().parents[2] / f"contract/fixtures/live-{scenario}-response.json"
@@ -112,8 +131,10 @@ def test_captured_live_responses_preserve_missing_and_null_text(scenario: str) -
     for result, raw in zip(response.results, wire["results"], strict=True):
         assert result.text == raw.get("text")
         assert result.snippet == raw.get("snippet")
+        assert result.highlights == raw.get("highlights")
         assert ("text" in result.model_fields_set) == ("text" in raw)
         assert ("snippet" in result.model_fields_set) == ("snippet" in raw)
+        assert ("highlights" in result.model_fields_set) == ("highlights" in raw)
         assert result.model_extra == {}
     if scenario in {"text", "markdown"}:
         assert response.results[0].text is not None and len(response.results[0].text) == 300

ateve-0.2.0/src/ateve/_version.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"