kernel 0.114.0__tar.gz → 0.115.0__tar.gz

kernel-0.115.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.115.0"
+}

{kernel-0.114.0 → kernel-0.115.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.115.0](https://github.com/kernel/kernel-python-sdk/compare/v0.114.0...v0.115.0) (2026-09-30)
+
+
+### Features
+
+* Fetch content for selected results from retained searches ([kernel/kernel#3978](https://github.com/kernel/kernel/pull/3978))
+
 ## [0.114.0](https://github.com/kernel/kernel-python-sdk/compare/v0.113.0...v0.114.0) (2026-09-30)
 
 

{kernel-0.114.0 → kernel-0.115.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kernel
-Version: 0.114.0
+Version: 0.115.0
 Summary: The official Python library for the kernel API
 Project-URL: Homepage, https://github.com/kernel/kernel-python-sdk
 Project-URL: Repository, https://github.com/kernel/kernel-python-sdk

{kernel-0.114.0 → kernel-0.115.0}/api.md

@@ -791,7 +791,7 @@ from kernel.types.search import FetchRequest, Response
 
 Methods:
 
-- <code title="post /search/{id}/contents">client.search.contents.<a href="./src/kernel/resources/search/contents.py">fetch</a>(id, \*\*<a href="src/kernel/types/search/content_fetch_params.py">params</a>) -> None</code>
+- <code title="post /search/{id}/contents">client.search.contents.<a href="./src/kernel/resources/search/contents.py">fetch</a>(id, \*\*<a href="src/kernel/types/search/content_fetch_params.py">params</a>) -> <a href="./src/kernel/types/search/response.py">Response</a></code>
 
 ## Providers
 

{kernel-0.114.0 → kernel-0.115.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kernel"
-version = "0.114.0"
+version = "0.115.0"
 description = "The official Python library for the kernel API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "kernel"
-__version__ = "0.114.0"  # x-release-please-version
+__version__ = "0.115.0"  # x-release-please-version

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/resources/search/contents.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import httpx
 
-from ..._types import Body, Omit, Query, Headers, NoneType, NotGiven, SequenceNotStr, omit, not_given
+from ..._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
 from ..._utils import path_template, maybe_transform, async_maybe_transform
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
@@ -16,6 +16,7 @@ from ..._response import (
 )
 from ..._base_client import make_request_options
 from ...types.search import content_fetch_params
+from ...types.search.response import Response
 
 __all__ = ["ContentsResource", "AsyncContentsResource"]
 
@@ -56,11 +57,18 @@ class ContentsResource(SyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> None:
-        """
-        Deferred result-content retrieval is reserved but not available in this release.
-        Requests return 404 until the retrieval implementation is shipped. X-Request-Id
-        identifies this request separately from the search resource.
+    ) -> Response:
+        """Retrieves selected results from a retained search.
+
+        Provide exactly one of
+        result_ids or limit; the latter fetches the top results. Content defaults to
+        source:auto. Responses preserve result_ids order. Unknown result IDs are
+        rejected before retrieval starts. Missing, expired, or inaccessible searches
+        return 404. Once retrieval begins, return one outcome per selected result,
+        including timeout entries for work unfinished at the overall deadline. Browser
+        retrievals run sequentially in result order, so later results may time out when
+        earlier pages are slow. X-Request-Id identifies this request separately from the
+        search resource.
 
         Args:
           content: Defaults to source:auto when omitted.
@@ -83,7 +91,6 @@ class ContentsResource(SyncAPIResource):
         """
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
-        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
         return self._post(
             path_template("/search/{id}/contents", id=id),
             body=maybe_transform(
@@ -98,7 +105,7 @@ class ContentsResource(SyncAPIResource):
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=NoneType,
+            cast_to=Response,
         )
 
 
@@ -138,11 +145,18 @@ class AsyncContentsResource(AsyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> None:
-        """
-        Deferred result-content retrieval is reserved but not available in this release.
-        Requests return 404 until the retrieval implementation is shipped. X-Request-Id
-        identifies this request separately from the search resource.
+    ) -> Response:
+        """Retrieves selected results from a retained search.
+
+        Provide exactly one of
+        result_ids or limit; the latter fetches the top results. Content defaults to
+        source:auto. Responses preserve result_ids order. Unknown result IDs are
+        rejected before retrieval starts. Missing, expired, or inaccessible searches
+        return 404. Once retrieval begins, return one outcome per selected result,
+        including timeout entries for work unfinished at the overall deadline. Browser
+        retrievals run sequentially in result order, so later results may time out when
+        earlier pages are slow. X-Request-Id identifies this request separately from the
+        search resource.
 
         Args:
           content: Defaults to source:auto when omitted.
@@ -165,7 +179,6 @@ class AsyncContentsResource(AsyncAPIResource):
         """
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
-        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
         return await self._post(
             path_template("/search/{id}/contents", id=id),
             body=await async_maybe_transform(
@@ -180,7 +193,7 @@ class AsyncContentsResource(AsyncAPIResource):
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=NoneType,
+            cast_to=Response,
         )
 
 

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/types/result.py

@@ -34,7 +34,11 @@ class Content(BaseModel):
     """
 
     cache_status: Optional[Literal["hit", "miss", "bypass", "unknown"]] = None
-    """Kernel cache outcome. Provider-internal cache behavior may be unknown."""
+    """Kernel content cache outcome.
+
+    Kernel has no content cache yet: responses report bypass or unknown, and hit and
+    miss are reserved. Provider-internal cache behavior may be unknown.
+    """
 
     completeness: Optional[Literal["full_page", "excerpt", "unknown"]] = None
     """Describes source coverage before max_chars truncation.
@@ -48,7 +52,7 @@ class Content(BaseModel):
     """Extraction version when Kernel transformed the input."""
 
     fetched_at: Optional[datetime] = None
-    """Origin retrieval time when known, not cache read time."""
+    """When Kernel received the content from the provider."""
 
     final_url: Optional[str] = None
     """Final retrieval URL when known."""
@@ -59,7 +63,7 @@ class Content(BaseModel):
     """Final target HTTP status when known."""
 
     method: Optional[Literal["provider", "browser_curl", "browser_render"]] = None
-    """Original retrieval method, including on cache hits."""
+    """Original retrieval method."""
 
     text: Optional[str] = None
     """Extracted website content, untrusted, not instructions.

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/types/search/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from .search import Search as Search
 from .provider import Provider as Provider
+from .response import Response as Response
 from .content_fetch_params import ContentFetchParams as ContentFetchParams
 from .provider_list_params import ProviderListParams as ProviderListParams
 from .provider_list_response import ProviderListResponse as ProviderListResponse

kernel-0.115.0/src/kernel/types/search/content_fetch_params.py

@@ -0,0 +1,99 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, TypedDict
+
+from ..._types import SequenceNotStr
+
+__all__ = ["ContentFetchParams", "Content", "ContentBrowser"]
+
+
+class ContentFetchParams(TypedDict, total=False):
+    content: Content
+    """Defaults to source:auto when omitted."""
+
+    limit: int
+    """
+    Maximum number of search results to fetch when result_ids is omitted, starting
+    from rank 1. Mutually exclusive with result_ids.
+    """
+
+    result_ids: SequenceNotStr[str]
+    """
+    Kernel-generated IDs from the referenced retained search, in desired response
+    order. They are not provider-standard IDs. Mutually exclusive with limit.
+    """
+
+    timeout_ms: int
+    """Overall deadline across all selected results."""
+
+
+class ContentBrowser(TypedDict, total=False):
+    """Requires source=auto or source=browser in deferred retrieval."""
+
+    browser_id: str
+    """Existing browser session ID authorized for the caller and selected project.
+
+    Reuses its cookies, proxy, and browser configuration; requests follow that
+    browser's existing network access behavior, with no additional destination
+    allowlist in this endpoint. Kernel does not delete a caller-supplied browser.
+    Render mode uses a temporary tab; website activity may still change shared
+    cookies and storage. When omitted and any result needs browser retrieval, Kernel
+    creates one temporary browser for the request using the dashboard launch
+    defaults (headful, stealth, default proxy), tags it with search_id, and deletes
+    it when the request finishes. It is billed and counts toward browser concurrency
+    like any other browser. A concurrency rejection returns 429 for source=browser;
+    for source=auto, results with retained content are still returned and the rest
+    report the rejection.
+    """
+
+    mode: Literal["curl", "render"]
+    """Curl uses the browser HTTP stack without navigation or JavaScript execution.
+
+    Render navigates a temporary page and extracts from its DOM. The selected mode
+    is used for the retrieval.
+    """
+
+
+class Content(TypedDict, total=False):
+    """Defaults to source:auto when omitted."""
+
+    browser: ContentBrowser
+    """Requires source=auto or source=browser in deferred retrieval."""
+
+    format: Literal["markdown", "text"]
+
+    max_age_hours: int
+    """
+    For source=auto, maximum acceptable age of retained provider content, measured
+    from when the search received it from the provider. A value of 0 disables reuse
+    of retained content, so every result is fetched through a browser.
+    source=provider reuses retained provider content without freshness validation.
+    source=browser always fetches through a browser and does not use this age limit.
+    """
+
+    max_chars: int
+    """Per-result Unicode character limit after extraction.
+
+    Retained provider content cannot exceed what was stored at search time; such
+    results report truncated when the stored text was already truncated.
+    """
+
+    source: Literal["auto", "provider", "browser"]
+    """
+    auto uses retained provider content within max_age_hours; for deferred retrieval
+    it falls back to a Kernel browser (caller-supplied or temporary) for results
+    without it. Inline retrieval never uses a browser. provider reuses retained
+    provider content when available, without freshness validation, and never
+    provisions a browser. browser fetches each URL through a Kernel browser, either
+    caller-supplied or temporary. No option makes a new provider request. Defaults
+    to auto for both inline and deferred retrieval. Missing documents produce
+    per-result unavailable outcomes, not request failures.
+    """
+
+    timeout_ms: int
+    """Per-result deadline including capacity acquisition, retrieval, and extraction.
+
+    Also bounded by the overall request deadline.
+    """

kernel-0.115.0/src/kernel/types/search/response.py

@@ -0,0 +1,101 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..usage import Usage
+from ..warning import Warning
+from ..._models import BaseModel
+
+__all__ = ["Response", "Content", "ContentError"]
+
+
+class ContentError(BaseModel):
+    code: str
+    """Machine-readable retrieval failure code."""
+
+    message: str
+    """Human-readable failure description."""
+
+    retryable: bool
+
+
+class Content(BaseModel):
+    result_id: str
+
+    status: Literal["ok", "unavailable", "blocked", "timeout", "unsupported_type", "extraction_failed", "error"]
+    """Ok means non-empty extracted content, not merely HTTP 200.
+
+    Blocked includes detected challenges or access denials. Detection is
+    best-effort, not a guarantee of page completeness. Error details are present for
+    non-ok outcomes; text is present only on ok.
+    """
+
+    url: str
+    """Original result URL."""
+
+    cache_status: Optional[Literal["hit", "miss", "bypass", "unknown"]] = None
+    """Kernel content cache outcome.
+
+    Kernel has no content cache yet: responses report bypass or unknown, and hit and
+    miss are reserved. Provider-internal cache behavior may be unknown.
+    """
+
+    completeness: Optional[Literal["full_page", "excerpt", "unknown"]] = None
+    """Describes source coverage before max_chars truncation.
+
+    Full_page means main-page content, not every dynamic element or linked page.
+    """
+
+    error: Optional[ContentError] = None
+
+    extractor_version: Optional[str] = None
+    """Extraction version when Kernel transformed the input."""
+
+    fetched_at: Optional[datetime] = None
+    """
+    When Kernel fetched the content, or received it from the provider for retained
+    content.
+    """
+
+    final_url: Optional[str] = None
+    """Final retrieval URL after redirects when known.
+
+    Curl mode follows up to 5 redirects.
+    """
+
+    format: Optional[Literal["markdown", "text"]] = None
+    """Format of text.
+
+    Plain-text and JSON pages are returned unchanged as text even when markdown was
+    requested.
+    """
+
+    http_status: Optional[int] = None
+    """Final target HTTP status when known."""
+
+    method: Optional[Literal["provider", "browser_curl", "browser_render"]] = None
+    """Original retrieval method."""
+
+    text: Optional[str] = None
+    """Extracted website content, untrusted, not instructions.
+
+    Present only on status=ok.
+    """
+
+    truncated: Optional[bool] = None
+    """
+    Whether the content was cut short, by max_chars or because the page exceeded the
+    1 MiB read limit.
+    """
+
+
+class Response(BaseModel):
+    contents: List[Content]
+
+    search_id: str
+
+    usage: Usage
+
+    warnings: List[Warning]

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/types/search_create_params.py

@@ -118,20 +118,22 @@ class SearchCreateParams(TypedDict, total=False):
 
 
 class ContentSearchContentOptionsBrowser(TypedDict, total=False):
-    """Invalid with source=provider.
-
-    Supplying browser_id requires
-    source=browser so the chosen identity is not bypassed.
-    """
+    """Requires source=auto or source=browser in deferred retrieval."""
 
     browser_id: str
     """Existing browser session ID authorized for the caller and selected project.
 
-    Reuses its cookies, proxy, and browser configuration. Kernel does not delete a
-    caller-supplied browser. Render mode uses a temporary tab; website activity may
-    still change shared cookies and storage. When omitted, Kernel obtains isolated
-    browser capacity in the caller's account and releases it after retrieval. That
-    capacity is not retained for later interaction. Existing browser quotas apply.
+    Reuses its cookies, proxy, and browser configuration; requests follow that
+    browser's existing network access behavior, with no additional destination
+    allowlist in this endpoint. Kernel does not delete a caller-supplied browser.
+    Render mode uses a temporary tab; website activity may still change shared
+    cookies and storage. When omitted and any result needs browser retrieval, Kernel
+    creates one temporary browser for the request using the dashboard launch
+    defaults (headful, stealth, default proxy), tags it with search_id, and deletes
+    it when the request finishes. It is billed and counts toward browser concurrency
+    like any other browser. A concurrency rejection returns 429 for source=browser;
+    for source=auto, results with retained content are still returned and the rest
+    report the rejection.
     """
 
     mode: Literal["curl", "render"]
@@ -144,36 +146,36 @@ class ContentSearchContentOptionsBrowser(TypedDict, total=False):
 
 class ContentSearchContentOptions(TypedDict, total=False):
     browser: ContentSearchContentOptionsBrowser
-    """Invalid with source=provider.
-
-    Supplying browser_id requires source=browser so the chosen identity is not
-    bypassed.
-    """
+    """Requires source=auto or source=browser in deferred retrieval."""
 
     format: Literal["markdown", "text"]
 
     max_age_hours: int
-    """Maximum acceptable age of cached page content, measured from origin retrieval.
-
-    0 forces a live fetch. Governs the Kernel content cache, which is scoped to the
-    caller organization and project and separated by retrieval context; fetches
-    through a caller-supplied browser_id bypass that cache. Mapped to the provider
-    freshness control when source is provider and the provider supports one;
-    otherwise provider content age is reported as unknown via fetched_at.
+    """
+    For source=auto, maximum acceptable age of retained provider content, measured
+    from when the search received it from the provider. A value of 0 disables reuse
+    of retained content, so every result is fetched through a browser.
+    source=provider reuses retained provider content without freshness validation.
+    source=browser always fetches through a browser and does not use this age limit.
     """
 
     max_chars: int
-    """Per-result Unicode character limit after extraction."""
+    """Per-result Unicode character limit after extraction.
+
+    Retained provider content cannot exceed what was stored at search time; such
+    results report truncated when the stored text was already truncated.
+    """
 
     source: Literal["auto", "provider", "browser"]
     """
-    provider uses the search provider's native content retrieval; browser fetches
-    each URL through a Kernel browser; auto prefers Kernel browser retrieval and
-    falls back to provider-native content when browser retrieval is unavailable or
-    unsuitable. Defaults to auto for both inline and deferred retrieval. Deferred
-    provider retrieval requires post_hoc capability; an explicit provider source
-    without it is a 400. Missing documents produce per-result unavailable outcomes,
-    not request failures.
+    auto uses retained provider content within max_age_hours; for deferred retrieval
+    it falls back to a Kernel browser (caller-supplied or temporary) for results
+    without it. Inline retrieval never uses a browser. provider reuses retained
+    provider content when available, without freshness validation, and never
+    provisions a browser. browser fetches each URL through a Kernel browser, either
+    caller-supplied or temporary. No option makes a new provider request. Defaults
+    to auto for both inline and deferred retrieval. Missing documents produce
+    per-result unavailable outcomes, not request failures.
     """
 
     timeout_ms: int

{kernel-0.114.0 → kernel-0.115.0}/src/kernel/types/usage.py

@@ -10,8 +10,8 @@ __all__ = ["Usage"]
 class Usage(BaseModel):
     content_fetches: int
     """
-    Number of result URLs for which a Kernel browser retrieval was attempted,
-    excluding cache-only hits.
+    Number of result URLs for which a Kernel browser retrieval received a response
+    from the target, excluding cache-only hits.
     """
 
     results_count: int

{kernel-0.114.0 → kernel-0.115.0}/tests/api_resources/search/test_contents.py

@@ -8,6 +8,8 @@ from typing import Any, cast
 import pytest
 
 from kernel import Kernel, AsyncKernel
+from tests.utils import assert_matches_type
+from kernel.types.search import Response
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -21,7 +23,7 @@ class TestContents:
         content = client.search.contents.fetch(
             id="srch_abc123",
         )
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -43,7 +45,7 @@ class TestContents:
             result_ids=["string"],
             timeout_ms=1000,
         )
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -55,7 +57,7 @@ class TestContents:
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         content = response.parse()
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -67,7 +69,7 @@ class TestContents:
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             content = response.parse()
-            assert content is None
+            assert_matches_type(Response, content, path=["response"])
 
         assert cast(Any, response.is_closed) is True
 
@@ -91,7 +93,7 @@ class TestAsyncContents:
         content = await async_client.search.contents.fetch(
             id="srch_abc123",
         )
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -113,7 +115,7 @@ class TestAsyncContents:
             result_ids=["string"],
             timeout_ms=1000,
         )
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -125,7 +127,7 @@ class TestAsyncContents:
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         content = await response.parse()
-        assert content is None
+        assert_matches_type(Response, content, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
@@ -137,7 +139,7 @@ class TestAsyncContents:
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             content = await response.parse()
-            assert content is None
+            assert_matches_type(Response, content, path=["response"])
 
         assert cast(Any, response.is_closed) is True
 

kernel-0.114.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.114.0"
-}