cayu.tools.web

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

HttpxWebFetchTransport

from cayu.tools import HttpxWebFetchTransport

Streaming HTTPX transport that connects to an already admitted IP address.

init (method)

HttpxWebFetchTransport.__init__(*, transport: httpx.AsyncBaseTransport | None=None) -> None

fetch (method)

async HttpxWebFetchTransport.fetch(request: WebFetchHttpRequest) -> WebFetchHttpResponse

Release source · Runtime guarantees · Capability guides

SystemWebFetchResolver

from cayu.tools import SystemWebFetchResolver

Resolve destinations with the local operating system resolver.

resolve (method)

async SystemWebFetchResolver.resolve(hostname: str, port: int) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

WebFetchAdapter

from cayu.tools import WebFetchAdapter

High-level execution adapter for the stable web_fetch tool contract.

Decorators: @runtime_checkable.

Bases: Protocol.

fetch (method)

async WebFetchAdapter.fetch(ctx: ToolContext, request: WebFetchAdapterRequest) -> ToolResult

Release source · Runtime guarantees · Capability guides

WebFetchAdapterRequest

from cayu.tools import WebFetchAdapterRequest

Canonical bounded request passed to a selected web-fetch adapter.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
requested_url	str	required
max_response_bytes	int	required
max_content_bytes	int	required
timeout_seconds	float	required
max_redirects	int	required

Release source · Runtime guarantees · Capability guides

WebFetchHttpRequest

from cayu.tools import WebFetchHttpRequest

One admitted, DNS-pinned HTTPS request made by WebFetchTool.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
url	str	required
pinned_url	str	required
host_header	str	required
server_hostname	str	required
max_response_bytes	int	required
timeout_seconds	float	required

Release source · Runtime guarantees · Capability guides

WebFetchHttpResponse

from cayu.tools import WebFetchHttpResponse

Bounded response returned by a web-fetch HTTP transport.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
status_code	int	required
headers	Mapping[str, str]	required
body	bytes	required

Release source · Runtime guarantees · Capability guides

WebFetchHttpTransport

from cayu.tools import WebFetchHttpTransport

Fetches one admitted HTTPS hop without following redirects.

Decorators: @runtime_checkable.

Bases: Protocol.

fetch (method)

async WebFetchHttpTransport.fetch(request: WebFetchHttpRequest) -> WebFetchHttpResponse

Release source · Runtime guarantees · Capability guides

WebFetchResolver

from cayu.tools import WebFetchResolver

Resolves every destination immediately before its request hop.

Decorators: @runtime_checkable.

Bases: Protocol.

resolve (method)

async WebFetchResolver.resolve(hostname: str, port: int) -> Sequence[str]

Release source · Runtime guarantees · Capability guides

WebFetchTool

from cayu.tools import WebFetchTool

Fetch bounded text from public HTTPS pages in the trusted Cayu process.

Bases: Tool.

init (method)

WebFetchTool.__init__(*, adapter: WebFetchAdapter | None=None, resolver: WebFetchResolver | None=None, transport: WebFetchHttpTransport | None=None, max_response_bytes: int=DEFAULT_WEB_FETCH_MAX_RESPONSE_BYTES, max_content_bytes: int=DEFAULT_WEB_FETCH_MAX_CONTENT_BYTES, timeout_seconds: float=DEFAULT_WEB_FETCH_TIMEOUT_SECONDS, max_redirects: int=DEFAULT_WEB_FETCH_MAX_REDIRECTS, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None, spec: ToolSpec | None=None) -> None

name (property)

WebFetchTool.name() -> str

execution_profile_identity (property)

WebFetchTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

WebFetchTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

WebFetchTool.description() -> str

schema (property)

WebFetchTool.schema() -> dict[str, Any]

run (method)

async WebFetchTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

Release source · Runtime guarantees · Capability guides

WebSearchAdapter

from cayu.tools import WebSearchAdapter

High-level execution adapter for the stable web_search contract.

Decorators: @runtime_checkable.

Bases: Protocol.

search (method)

async WebSearchAdapter.search(ctx: ToolContext, request: WebSearchAdapterRequest) -> ToolResult

Release source · Runtime guarantees · Capability guides

WebSearchAdapterRequest

from cayu.tools import WebSearchAdapterRequest

Canonical bounded request passed to a selected web-search adapter.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
query	str	required
max_results	int	required
max_snippet_bytes	int	required
max_total_snippet_bytes	int	required
timeout_seconds	float	required
restrictions	WebSearchRestrictions	field(default_factory=WebSearchRestrictions)

Release source · Runtime guarantees · Capability guides

WebSearchRestrictions

from cayu.tools import WebSearchRestrictions

Application-owned restrictions for provider-backed web search.

These settings never enter the model-facing tool schema. Adapters must either enforce every non-empty field or return unsupported_semantics; silently broadening a restricted search is not permitted.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
include_domains	tuple[str, ...]	()
exclude_domains	tuple[str, ...]	()
published_on_or_after	date | None	None
country	str | None	None
locale	str | None	None
content_types	tuple[str, ...]	()

Release source · Runtime guarantees · Capability guides

WebSearchTool

from cayu.tools import WebSearchTool

Search through one explicitly selected hosted-provider adapter.

Bases: Tool.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
spec	class attribute	_web_search_tool_spec(default_results=DEFAULT_WEB_SEARCH_RESULTS, max_results=DEFAULT_WEB_SEARCH_MAX_RESULTS)

init (method)

WebSearchTool.__init__(*, adapter: WebSearchAdapter, default_results: int=DEFAULT_WEB_SEARCH_RESULTS, max_results: int=DEFAULT_WEB_SEARCH_MAX_RESULTS, max_snippet_bytes: int=DEFAULT_WEB_SEARCH_MAX_SNIPPET_BYTES, max_total_snippet_bytes: int=DEFAULT_WEB_SEARCH_MAX_TOTAL_SNIPPET_BYTES, timeout_seconds: float=DEFAULT_WEB_SEARCH_TIMEOUT_SECONDS, restrictions: WebSearchRestrictions | None=None, execution_profile_identity: ExecutionProfileBehaviorIdentity | None=None, spec: ToolSpec | None=None) -> None

name (property)

WebSearchTool.name() -> str

execution_profile_identity (property)

WebSearchTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

WebSearchTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

WebSearchTool.description() -> str

schema (property)

WebSearchTool.schema() -> dict[str, Any]

run (method)

async WebSearchTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

Release source · Runtime guarantees · Capability guides