anysearch-py 0.1.0__tar.gz

anysearch_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WH-2099
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anysearch_py-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: anysearch-py
+Version: 0.1.0
+Summary: Typed Python client for AnySearch.
+Author: WH-2099
+Author-email: WH-2099 <wh2099@pm.me>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: pydantic>=2.12
+Requires-Dist: urllib3-future>=2.12.910
+Requires-Python: >=3.14
+Project-URL: source, https://github.com/WH-2099/anysearch-py
+Project-URL: homepage, https://github.com/WH-2099/anysearch-py
+Project-URL: issues, https://github.com/WH-2099/anysearch-py/issues
+Description-Content-Type: text/markdown
+
+# anysearch-py
+
+Typed Python clients for AnySearch.
+
+The package has two first-class clients.
+
+`Client` calls the REST Web API.
+
+`MCPClient` calls the MCP `tools/call` API used by `anysearch-skill/`.
+
+Both clients share the same Pydantic models, enums, validation, and serialization logic.
+
+## Install
+
+```bash
+uv add anysearch-py
+```
+
+## REST Search
+
+```python
+from anysearch_py import Client, SearchTag
+
+with Client(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    response = client.search(
+        "Go 1.26 release notes",
+        tag=SearchTag.CODE_DOC,
+        params={"library": "golang"},
+    )
+
+print(response.data.results[0].url)
+```
+
+## Async REST Search
+
+```python
+from anysearch_py import AsyncClient
+
+async with AsyncClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    response = await client.search("what is quantum computing")
+```
+
+## MCP Tools
+
+```python
+from anysearch_py import Domain, MCPClient
+
+with MCPClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    markdown = client.get_sub_domains(domains=[Domain.FINANCE, Domain.HEALTH])
+
+print(markdown)
+```
+
+## MCP Search
+
+```python
+from anysearch_py import Domain, MCPClient
+
+with MCPClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    markdown = client.search(
+        "AAPL",
+        domain=Domain.FINANCE,
+        sub_domain="finance.quote",
+        sub_domain_params="type=stock,symbol=AAPL,cn_code=",
+        max_results=5,
+    )
+
+print(markdown)
+```
+
+## Live Tests
+
+Live tests read `ANYSEARCH_API_KEY` from `.env` or `anysearch-skill/.env`.
+
+If neither file exists, those tests skip automatically.
+
+Package code never reads `.env`.

anysearch_py-0.1.0/README.md

@@ -0,0 +1,77 @@
+# anysearch-py
+
+Typed Python clients for AnySearch.
+
+The package has two first-class clients.
+
+`Client` calls the REST Web API.
+
+`MCPClient` calls the MCP `tools/call` API used by `anysearch-skill/`.
+
+Both clients share the same Pydantic models, enums, validation, and serialization logic.
+
+## Install
+
+```bash
+uv add anysearch-py
+```
+
+## REST Search
+
+```python
+from anysearch_py import Client, SearchTag
+
+with Client(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    response = client.search(
+        "Go 1.26 release notes",
+        tag=SearchTag.CODE_DOC,
+        params={"library": "golang"},
+    )
+
+print(response.data.results[0].url)
+```
+
+## Async REST Search
+
+```python
+from anysearch_py import AsyncClient
+
+async with AsyncClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    response = await client.search("what is quantum computing")
+```
+
+## MCP Tools
+
+```python
+from anysearch_py import Domain, MCPClient
+
+with MCPClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    markdown = client.get_sub_domains(domains=[Domain.FINANCE, Domain.HEALTH])
+
+print(markdown)
+```
+
+## MCP Search
+
+```python
+from anysearch_py import Domain, MCPClient
+
+with MCPClient(api_key="YOUR_ANYSEARCH_API_KEY") as client:
+    markdown = client.search(
+        "AAPL",
+        domain=Domain.FINANCE,
+        sub_domain="finance.quote",
+        sub_domain_params="type=stock,symbol=AAPL,cn_code=",
+        max_results=5,
+    )
+
+print(markdown)
+```
+
+## Live Tests
+
+Live tests read `ANYSEARCH_API_KEY` from `.env` or `anysearch-skill/.env`.
+
+If neither file exists, those tests skip automatically.
+
+Package code never reads `.env`.

anysearch_py-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = 'anysearch-py'
+version = '0.1.0'
+description = 'Typed Python client for AnySearch.'
+readme = 'README.md'
+license = 'MIT'
+license-files = ['LICENSE']
+authors = [
+    { name = 'WH-2099', email = 'wh2099@pm.me' }
+]
+requires-python = '>=3.14'
+dependencies = [
+    'pydantic>=2.12',
+    'urllib3-future>=2.12.910',
+]
+
+
+[project.urls]
+source = 'https://github.com/WH-2099/anysearch-py'
+homepage = 'https://github.com/WH-2099/anysearch-py'
+issues = 'https://github.com/WH-2099/anysearch-py/issues'
+
+[dependency-groups]
+dev = [
+    'pytest',
+    'pytest-cov',
+    'pytest-mock',
+    'ruff',
+    'prek',
+    'ty',
+]
+
+[build-system]
+requires = ['uv_build~=0.11']
+build-backend = 'uv_build'
+
+[tool.uv]
+default-groups = ['dev']
+
+[tool.ruff]
+fix = true
+preview = true
+required-version = '>=0.15'
+extend-exclude = ['anysearch-skill']
+
+[tool.ruff.lint]
+select = ['ALL']
+ignore = [
+    'COM812',  # Conflicts with `ruff format`.
+    'ERA001',  # False positives are common.
+    'TC',      # Runtime use of typing constructs is common now.
+    'CPY',     # Covered by the standalone LICENSE file.
+    'PLR0913', # Explicit is better than implicit.
+    'PLR0917', # Complex is better than complicated.
+    'PLR6301', # Violates the usual practice.
+    'D',       # Too verbose.
+    'FBT',     # Too strict.
+    'TID252',  # Too absolute.
+    'ANN401',  # We hope to enforce this, but typing is still evolving.
+]
+
+[tool.ruff.lint.pydoclint]
+ignore-one-line-docstrings = true
+
+[tool.ruff.lint.per-file-ignores]
+'tests/**/*.py' = [
+    'S101',    # Assert statements used for pytest.
+    'PLR2004', # Magic value used in test cases.
+    'PLC2701', # Allow import private members from graphon module.
+    'PLC1901', # be more precise about assertion in tests.
+
+    # permit calls of private methods until we separate
+    # public interface tests from implementation tests.
+    'SLF001', # allow calls of private class methods in tests
+]
+
+[tool.ty.environment]
+python-platform = 'linux'
+
+[tool.pytest]
+minversion = '9.0'
+testpaths = ['tests']

anysearch_py-0.1.0/src/anysearch_py/__init__.py

@@ -0,0 +1,72 @@
+"""Typed Python clients for AnySearch."""
+
+from .client import AsyncClient, AsyncMCPClient, Client, MCPClient
+from .exceptions import (
+    AnySearchError,
+    APIError,
+    HTTPStatusError,
+    JSONRPCError,
+    ResponseDecodeError,
+    ResponseValidationError,
+    TransportError,
+)
+from .models import (
+    APIEnvelope,
+    BatchSearchArguments,
+    Domain,
+    ExtractArguments,
+    GetSubDomainsArguments,
+    MCPArguments,
+    MCPContentBlock,
+    MCPToolCall,
+    MCPToolResponse,
+    MCPToolResult,
+    OutputFormat,
+    SearchArgumentInput,
+    SearchArguments,
+    SearchData,
+    SearchMetadata,
+    SearchRequest,
+    SearchResponse,
+    SearchResult,
+    SearchTag,
+    SubDomainParams,
+    ToolName,
+    Zone,
+)
+
+__all__ = [
+    "APIEnvelope",
+    "APIError",
+    "AnySearchError",
+    "AsyncClient",
+    "AsyncMCPClient",
+    "BatchSearchArguments",
+    "Client",
+    "Domain",
+    "ExtractArguments",
+    "GetSubDomainsArguments",
+    "HTTPStatusError",
+    "JSONRPCError",
+    "MCPArguments",
+    "MCPClient",
+    "MCPContentBlock",
+    "MCPToolCall",
+    "MCPToolResponse",
+    "MCPToolResult",
+    "OutputFormat",
+    "ResponseDecodeError",
+    "ResponseValidationError",
+    "SearchArgumentInput",
+    "SearchArguments",
+    "SearchData",
+    "SearchMetadata",
+    "SearchRequest",
+    "SearchResponse",
+    "SearchResult",
+    "SearchTag",
+    "SubDomainParams",
+    "ToolName",
+    "TransportError",
+    "Zone",
+]

anysearch_py-0.1.0/src/anysearch_py/client.py

@@ -0,0 +1,383 @@
+"""HTTP clients for AnySearch."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from itertools import count
+from typing import Any, Self
+
+import urllib3
+from urllib3.util import Retry, Timeout
+
+from .exceptions import (
+    HTTPStatusError,
+    ResponseDecodeError,
+    TransportError,
+)
+from .models import (
+    APIErrorDetails,
+    BatchSearchArguments,
+    Domain,
+    ExtractArguments,
+    GetSubDomainsArguments,
+    JsonObject,
+    JsonValue,
+    MCPArguments,
+    MCPToolCall,
+    MCPToolResponse,
+    MCPToolResult,
+    OutputFormat,
+    SearchArgumentInput,
+    SearchArguments,
+    SearchRequest,
+    SearchResponse,
+    SearchTag,
+    ToolName,
+    Zone,
+)
+
+API_BASE_URL = "https://api.anysearch.com"
+REST_SEARCH_PATH = "/v1/search"
+MCP_PATH = "/mcp"
+USER_AGENT = "anysearch-py/0.1.0"
+
+DEFAULT_TIMEOUT = Timeout(connect=10.0, read=30.0)
+DEFAULT_RETRIES = Retry(
+    total=2,
+    connect=2,
+    read=2,
+    status=2,
+    backoff_factor=0.25,
+    allowed_methods=frozenset({"GET", "POST"}),
+    status_forcelist=frozenset({500, 502, 503, 504}),
+    raise_on_status=False,
+)
+HTTP_OK_MIN = 200
+HTTP_REDIRECT_MIN = 300
+
+
+@dataclass(kw_only=True)
+class _HTTPClient:
+    api_key: str | None = None
+    base_url: str = API_BASE_URL
+    user_agent: str = USER_AGENT
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+
+    def _raise_for_http_status(self, response: Any, payload: Any) -> None:
+        status = int(getattr(response, "status", 0))
+        if HTTP_OK_MIN <= status < HTTP_REDIRECT_MIN:
+            return
+
+        details = APIErrorDetails.from_payload(
+            payload,
+            fallback_message=f"HTTP {status} response from AnySearch",
+        )
+        headers = getattr(response, "headers", None)
+        raise HTTPStatusError(
+            details.message,
+            status=status,
+            code=details.code,
+            request_id=details.request_id,
+            data=details.data,
+            headers={str(key): str(value) for key, value in headers.items()}
+            if hasattr(headers, "items")
+            else {},
+        )
+
+
+class _SyncHTTPClient(_HTTPClient):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = API_BASE_URL,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        retries: Retry | bool | int = DEFAULT_RETRIES,
+        user_agent: str = USER_AGENT,
+        http: Any | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, user_agent=user_agent)
+        self.http = http or urllib3.PoolManager(timeout=timeout, retries=retries)
+        self.owns_http = http is None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        del exc_info
+        self.close()
+
+    def close(self) -> None:
+        if self.owns_http and hasattr(self.http, "clear"):
+            self.http.clear()
+
+    def post_json(self, path: str, payload: JsonObject) -> Any:
+        try:
+            response = self.http.request(
+                "POST",
+                self._url(path),
+                headers=self._headers(),
+                json=payload,
+            )
+        except urllib3.exceptions.HTTPError as exc:
+            msg = "AnySearch HTTP request failed"
+            raise TransportError(msg, cause=exc) from exc
+
+        try:
+            decoded = response.json()
+        except ValueError as exc:
+            raw = getattr(response, "data", None)
+            msg = "response body is not valid JSON"
+            raise ResponseDecodeError(msg, raw=raw) from exc
+        self._raise_for_http_status(response, decoded)
+        return decoded
+
+
+class _AsyncHTTPClient(_HTTPClient):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = API_BASE_URL,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        retries: Retry | bool | int = DEFAULT_RETRIES,
+        user_agent: str = USER_AGENT,
+        http: Any | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, user_agent=user_agent)
+        self.http = http or urllib3.AsyncPoolManager(timeout=timeout, retries=retries)
+        self.owns_http = http is None
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        del exc_info
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if not self.owns_http or not hasattr(self.http, "clear"):
+            return
+        result = self.http.clear()
+        if hasattr(result, "__await__"):
+            await result
+
+    async def post_json(self, path: str, payload: JsonObject) -> Any:
+        try:
+            response = await self.http.request(
+                "POST",
+                self._url(path),
+                headers=self._headers(),
+                json=payload,
+            )
+        except urllib3.exceptions.HTTPError as exc:
+            msg = "AnySearch HTTP request failed"
+            raise TransportError(msg, cause=exc) from exc
+
+        try:
+            decoded = await response.json()
+        except ValueError as exc:
+            msg = "response body is not valid JSON"
+            raise ResponseDecodeError(msg) from exc
+        self._raise_for_http_status(response, decoded)
+        return decoded
+
+
+class Client(_SyncHTTPClient):
+    """Synchronous AnySearch REST API client."""
+
+    def search(
+        self,
+        request: SearchRequest | str,
+        *,
+        max_results: int = 10,
+        tag: SearchTag | str | None = None,
+        zone: Zone | str | None = None,
+        language: str | None = None,
+        params: Mapping[str, JsonValue] | None = None,
+        output_format: OutputFormat | str = OutputFormat.JSON,
+    ) -> SearchResponse:
+        search_request = SearchRequest.from_input(
+            request,
+            max_results=max_results,
+            tag=tag,
+            zone=zone,
+            language=language,
+            params=params,
+            output_format=output_format,
+        )
+        payload = self.post_json(REST_SEARCH_PATH, search_request.to_payload())
+        return SearchResponse.from_payload(payload)
+
+
+class MCPClient(_SyncHTTPClient):
+    """Synchronous AnySearch MCP tools/call client."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.ids = count(1)
+
+    def call_tool(
+        self,
+        tool: ToolName | str | MCPArguments | MCPToolCall,
+        arguments: Mapping[str, JsonValue] | None = None,
+    ) -> MCPToolResult:
+        tool_call = (
+            tool
+            if isinstance(tool, MCPToolCall)
+            else tool.to_tool_call()
+            if isinstance(tool, MCPArguments)
+            else MCPToolCall.from_arguments(tool, arguments)
+        )
+        payload = self.post_json(
+            MCP_PATH, tool_call.to_request(next(self.ids)).to_payload()
+        )
+        return MCPToolResponse.from_payload(payload)
+
+    def search(
+        self, arguments: SearchArguments | str | Mapping[str, Any], **kwargs: Any
+    ) -> str:
+        args = SearchArguments.from_input(arguments, **kwargs)
+        return self.call_tool(args).text
+
+    def batch_search(
+        self,
+        queries: Sequence[SearchArgumentInput] | BatchSearchArguments,
+        *,
+        domain: Domain | str | None = None,
+        sub_domain: str | None = None,
+        sub_domain_params: Mapping[str, JsonValue] | str | None = None,
+    ) -> str:
+        args = (
+            queries
+            if isinstance(queries, BatchSearchArguments)
+            else BatchSearchArguments.from_queries(
+                queries,
+                domain=domain,
+                sub_domain=sub_domain,
+                sub_domain_params=sub_domain_params,
+            )
+        )
+        return self.call_tool(args).text
+
+    def get_sub_domains(
+        self,
+        *,
+        domain: Domain | str | None = None,
+        domains: Sequence[Domain | str] | None = None,
+    ) -> str:
+        args = GetSubDomainsArguments.from_selector(domain=domain, domains=domains)
+        return self.call_tool(args).text
+
+    def extract(self, url: str) -> str:
+        return self.call_tool(ExtractArguments.from_url(url)).text
+
+
+class AsyncClient(_AsyncHTTPClient):
+    """Asynchronous AnySearch REST API client."""
+
+    async def search(
+        self,
+        request: SearchRequest | str,
+        *,
+        max_results: int = 10,
+        tag: SearchTag | str | None = None,
+        zone: Zone | str | None = None,
+        language: str | None = None,
+        params: Mapping[str, JsonValue] | None = None,
+        output_format: OutputFormat | str = OutputFormat.JSON,
+    ) -> SearchResponse:
+        search_request = SearchRequest.from_input(
+            request,
+            max_results=max_results,
+            tag=tag,
+            zone=zone,
+            language=language,
+            params=params,
+            output_format=output_format,
+        )
+        payload = await self.post_json(REST_SEARCH_PATH, search_request.to_payload())
+        return SearchResponse.from_payload(payload)
+
+
+class AsyncMCPClient(_AsyncHTTPClient):
+    """Asynchronous AnySearch MCP tools/call client."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.ids = count(1)
+
+    async def call_tool(
+        self,
+        tool: ToolName | str | MCPArguments | MCPToolCall,
+        arguments: Mapping[str, JsonValue] | None = None,
+    ) -> MCPToolResult:
+        tool_call = (
+            tool
+            if isinstance(tool, MCPToolCall)
+            else tool.to_tool_call()
+            if isinstance(tool, MCPArguments)
+            else MCPToolCall.from_arguments(tool, arguments)
+        )
+        payload = await self.post_json(
+            MCP_PATH,
+            tool_call.to_request(next(self.ids)).to_payload(),
+        )
+        return MCPToolResponse.from_payload(payload)
+
+    async def search(
+        self,
+        arguments: SearchArguments | str | Mapping[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        args = SearchArguments.from_input(arguments, **kwargs)
+        result = await self.call_tool(args)
+        return result.text
+
+    async def batch_search(
+        self,
+        queries: Sequence[SearchArgumentInput] | BatchSearchArguments,
+        *,
+        domain: Domain | str | None = None,
+        sub_domain: str | None = None,
+        sub_domain_params: Mapping[str, JsonValue] | str | None = None,
+    ) -> str:
+        args = (
+            queries
+            if isinstance(queries, BatchSearchArguments)
+            else BatchSearchArguments.from_queries(
+                queries,
+                domain=domain,
+                sub_domain=sub_domain,
+                sub_domain_params=sub_domain_params,
+            )
+        )
+        result = await self.call_tool(args)
+        return result.text
+
+    async def get_sub_domains(
+        self,
+        *,
+        domain: Domain | str | None = None,
+        domains: Sequence[Domain | str] | None = None,
+    ) -> str:
+        args = GetSubDomainsArguments.from_selector(domain=domain, domains=domains)
+        result = await self.call_tool(args)
+        return result.text
+
+    async def extract(self, url: str) -> str:
+        result = await self.call_tool(ExtractArguments.from_url(url))
+        return result.text

anysearch_py-0.1.0/src/anysearch_py/exceptions.py

@@ -0,0 +1,62 @@
+"""Exception hierarchy for AnySearch clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AnySearchError(Exception):
+    """Base class for all package-specific errors."""
+
+
+class TransportError(AnySearchError):
+    """Raised when the HTTP client cannot complete a request."""
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class ResponseDecodeError(AnySearchError):
+    """Raised when a response cannot be decoded as JSON."""
+
+    def __init__(self, message: str, *, raw: Any = None) -> None:
+        super().__init__(message)
+        self.raw = raw
+
+
+class ResponseValidationError(AnySearchError):
+    """Raised when a decoded response does not match the expected schema."""
+
+    def __init__(self, message: str, *, payload: Any = None) -> None:
+        super().__init__(message)
+        self.payload = payload
+
+
+class APIError(AnySearchError):
+    """Raised when AnySearch returns an application-level error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: int | str | None = None,
+        request_id: str | None = None,
+        data: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.data = data
+        self.headers = headers or {}
+
+
+class HTTPStatusError(APIError):
+    """Raised for non-2xx HTTP responses."""
+
+
+class JSONRPCError(APIError):
+    """Raised for JSON-RPC error objects or MCP tool failures."""

anysearch_py-0.1.0/src/anysearch_py/models.py

@@ -0,0 +1,580 @@
+"""Pydantic models shared by the AnySearch REST and MCP clients."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from enum import StrEnum
+from typing import Annotated, Any, ClassVar, Literal, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    RootModel,
+    StringConstraints,
+    TypeAdapter,
+    ValidationError,
+    computed_field,
+    model_validator,
+)
+
+from .exceptions import APIError, JSONRPCError, ResponseValidationError
+
+type JsonScalar = str | int | float | bool | None
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+type JsonObject = dict[str, JsonValue]
+type SearchArgumentInput = SearchArguments | str | Mapping[str, Any]
+
+NonEmptyString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+LanguageCode = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True,
+        min_length=2,
+        max_length=16,
+        pattern=r"^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?$",
+    ),
+]
+SubDomainName = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True,
+        min_length=3,
+        pattern=r"^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$",
+    ),
+]
+
+_JSON_VALUE = TypeAdapter(JsonValue)
+
+
+class StrictRequestModel(BaseModel):
+    """Base class for outbound payloads."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        validate_default=True,
+    )
+
+    def to_payload(self) -> JsonObject:
+        dumped = self.model_dump(mode="json", by_alias=True, exclude_none=True)
+        if not isinstance(dumped, dict):
+            msg = "model dump did not produce a JSON object"
+            raise TypeError(msg)
+        return dumped
+
+
+class ResponseModel(BaseModel):
+    """Base class for inbound payloads."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        frozen=True,
+        populate_by_name=True,
+        validate_default=True,
+    )
+
+
+class Domain(StrEnum):
+    ACADEMIC = "academic"
+    AGRICULTURE = "agriculture"
+    BUSINESS = "business"
+    CODE = "code"
+    ENERGY = "energy"
+    ENVIRONMENT = "environment"
+    FILM = "film"
+    FINANCE = "finance"
+    GAMING = "gaming"
+    GENERAL = "general"
+    HEALTH = "health"
+    IP = "ip"
+    LEGAL = "legal"
+    RESOURCE = "resource"
+    SECURITY = "security"
+    SOCIAL_MEDIA = "social_media"
+    TRAVEL = "travel"
+
+
+class SearchTag(StrEnum):
+    ACADEMIC_BIOMEDICAL = "academic.biomedical"
+    ACADEMIC_CITATION = "academic.citation"
+    ACADEMIC_DATASET = "academic.dataset"
+    ACADEMIC_PREPRINT = "academic.preprint"
+    ACADEMIC_SEARCH = "academic.search"
+    AGRICULTURE_FAO = "agriculture.fao"
+    BUSINESS_COMPANY = "business.company"
+    BUSINESS_JOBS = "business.jobs"
+    BUSINESS_PEOPLE = "business.people"
+    BUSINESS_TRADE = "business.trade"
+    CODE_DOC = "code.doc"
+    CODE_SNIPPET = "code.snippet"
+    ENERGY_ELECTRICITY = "energy.electricity"
+    ENERGY_PRODUCTION = "energy.production"
+    ENVIRONMENT_AQI = "environment.aqi"
+    FILM_TORRENT = "film.torrent"
+    FINANCE_CALENDAR = "finance.calendar"
+    FINANCE_FUNDAMENTAL = "finance.fundamental"
+    FINANCE_MACRO = "finance.macro"
+    FINANCE_NEWS = "finance.news"
+    FINANCE_QUOTE = "finance.quote"
+    FINANCE_SCREEN = "finance.screen"
+    GAMING_ESPORTS = "gaming.esports"
+    GAMING_STORE = "gaming.store"
+    GENERAL_GENERAL = "general.general"
+    HEALTH_DRUG = "health.drug"
+    HEALTH_STATS = "health.stats"
+    HEALTH_TRIAL = "health.trial"
+    IP_GLOBAL = "ip.global"
+    LEGAL_CASE = "legal.case"
+    LEGAL_LEGISLATION = "legal.legislation"
+    LEGAL_STATUTE = "legal.statute"
+    RESOURCE_IMAGE = "resource.image"
+    SECURITY_INTEL = "security.intel"
+    SECURITY_NOISE = "security.noise"
+    SECURITY_SCAN = "security.scan"
+    SECURITY_VULN = "security.vuln"
+    SOCIAL_MEDIA_SOCIAL_MEDIA = "social_media.social_media"
+    TRAVEL_FLIGHT = "travel.flight"
+    TRAVEL_FLIGHT_STATUS = "travel.flight_status"
+
+
+class Zone(StrEnum):
+    CHINA = "cn"
+    INTERNATIONAL = "intl"
+
+
+class OutputFormat(StrEnum):
+    JSON = "json"
+    MARKDOWN = "markdown"
+
+
+class ToolName(StrEnum):
+    SEARCH = "search"
+    BATCH_SEARCH = "batch_search"
+    GET_SUB_DOMAINS = "get_sub_domains"
+    EXTRACT = "extract"
+
+
+class SearchRequest(StrictRequestModel):
+    """REST /v1/search request."""
+
+    query: NonEmptyString
+    max_results: int = Field(default=10, ge=1, le=20)
+    tag: SearchTag | None = None
+    zone: Zone | None = None
+    language: LanguageCode | None = None
+    params: JsonObject | None = None
+    format: OutputFormat = OutputFormat.JSON
+
+    @classmethod
+    def from_input(
+        cls,
+        request: Self | str,
+        *,
+        max_results: int = 10,
+        tag: SearchTag | str | None = None,
+        zone: Zone | str | None = None,
+        language: str | None = None,
+        params: Mapping[str, JsonValue] | None = None,
+        output_format: OutputFormat | str = OutputFormat.JSON,
+    ) -> Self:
+        if not isinstance(request, str):
+            return request
+        return cls.model_validate(
+            {
+                "query": request,
+                "max_results": max_results,
+                "tag": tag,
+                "zone": zone,
+                "language": language,
+                "params": dict(params) if params is not None else None,
+                "format": output_format,
+            },
+        )
+
+
+class SearchResult(ResponseModel):
+    """One REST search result."""
+
+    title: str
+    url: HttpUrl
+    snippet: str
+    content: str | None = None
+
+
+class SearchMetadata(ResponseModel):
+    """REST search metadata."""
+
+    total_results: int = Field(ge=0)
+    search_time_ms: int = Field(ge=0)
+
+
+class SearchData(ResponseModel):
+    """REST search data envelope."""
+
+    results: tuple[SearchResult, ...]
+    metadata: SearchMetadata
+
+
+class APIErrorDetails(ResponseModel):
+    """Normalized application error details."""
+
+    message: str
+    code: int | str | None = None
+    request_id: str | None = None
+    data: JsonValue | None = None
+
+    @classmethod
+    def from_payload(cls, payload: Any, *, fallback_message: str) -> Self:
+        if not isinstance(payload, dict):
+            return cls(
+                message=fallback_message,
+                data=cls.coerce_json(payload),
+            )
+
+        code = payload.get("code")
+        if not isinstance(code, int | str):
+            code = payload.get("symbol")
+        if not isinstance(code, int | str):
+            code = None
+
+        message = payload.get("message")
+        if not isinstance(message, str) or not message.strip():
+            message = payload.get("error")
+        if not isinstance(message, str) or not message.strip():
+            message = fallback_message
+
+        request_id = payload.get("request_id")
+        if not isinstance(request_id, str):
+            request_id = None
+
+        return cls(
+            message=message,
+            code=code,
+            request_id=request_id,
+            data=cls.coerce_json(payload.get("data")),
+        )
+
+    @staticmethod
+    def coerce_json(value: Any) -> JsonValue:
+        try:
+            return _JSON_VALUE.validate_python(value)
+        except ValidationError:
+            return str(value)
+
+
+class APIEnvelope[DataT](ResponseModel):
+    """Standard REST response envelope."""
+
+    code: int
+    message: str
+    request_id: str | None = None
+    data: DataT | None = None
+
+    @computed_field
+    @property
+    def ok(self) -> bool:
+        return self.code == 0
+
+    def raise_if_error(self) -> None:
+        if self.ok:
+            return
+
+        raise APIError(
+            self.message or "AnySearch request failed",
+            code=self.code,
+            request_id=self.request_id,
+            data=APIErrorDetails.coerce_json(self.data),
+        )
+
+
+class SearchResponse(APIEnvelope[SearchData]):
+    """Successful REST search response."""
+
+    data: SearchData
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> Self:
+        try:
+            APIEnvelope[Any].model_validate(payload).raise_if_error()
+        except ValidationError as exc:
+            msg = "search response does not match the AnySearch envelope schema"
+            raise ResponseValidationError(msg, payload=payload) from exc
+
+        try:
+            return cls.model_validate(payload)
+        except ValidationError as exc:
+            msg = "successful search response does not match the documented schema"
+            raise ResponseValidationError(msg, payload=payload) from exc
+
+
+class SubDomainParams(RootModel[JsonObject]):
+    """MCP sub-domain parameters."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_params(cls, value: Any) -> Any:
+        if not isinstance(value, str):
+            return value
+
+        stripped = value.strip()
+        if not stripped:
+            return None
+
+        try:
+            return json.loads(stripped)
+        except json.JSONDecodeError:
+            parsed = {}
+            for item in stripped.split(","):
+                key, separator, raw_value = item.partition("=")
+                if separator and key.strip():
+                    parsed[key.strip()] = raw_value.strip()
+            return parsed or value
+
+
+class MCPArguments(StrictRequestModel):
+    """Base class for MCP tool arguments."""
+
+    tool_name: ClassVar[ToolName]
+
+    def to_tool_call(self) -> MCPToolCall:
+        return MCPToolCall(name=self.tool_name, arguments=self.to_payload())
+
+
+class SearchArguments(MCPArguments):
+    """MCP search tool arguments."""
+
+    tool_name = ToolName.SEARCH
+
+    query: NonEmptyString
+    domain: Domain | None = None
+    sub_domain: SubDomainName | None = None
+    sub_domain_params: SubDomainParams | None = None
+    max_results: int | None = Field(default=None, ge=1, le=10)
+
+    @classmethod
+    def from_input(
+        cls, arguments: Self | str | Mapping[str, Any], **kwargs: Any
+    ) -> SearchArguments:
+        if isinstance(arguments, SearchArguments):
+            if kwargs:
+                msg = "keyword arguments cannot be combined with SearchArguments"
+                raise ValueError(msg)
+            return arguments
+        if isinstance(arguments, str):
+            return cls.model_validate({"query": arguments, **kwargs})
+        return cls.model_validate({**dict(arguments), **kwargs})
+
+    @model_validator(mode="after")
+    def validate_vertical_shape(self) -> Self:
+        if self.domain is None:
+            if self.sub_domain is not None or self.sub_domain_params is not None:
+                msg = "sub_domain and sub_domain_params require domain"
+                raise ValueError(msg)
+            return self
+        if self.sub_domain is None:
+            msg = "sub_domain is required when domain is provided"
+            raise ValueError(msg)
+        return self
+
+
+class BatchSearchArguments(MCPArguments):
+    """MCP batch_search tool arguments."""
+
+    tool_name = ToolName.BATCH_SEARCH
+
+    queries: tuple[SearchArguments, ...] = Field(min_length=1, max_length=5)
+
+    @classmethod
+    def from_queries(
+        cls,
+        queries: Sequence[SearchArgumentInput],
+        *,
+        domain: Domain | str | None = None,
+        sub_domain: str | None = None,
+        sub_domain_params: SubDomainParams
+        | Mapping[str, JsonValue]
+        | str
+        | None = None,
+    ) -> Self:
+        shared_params = (
+            SubDomainParams.model_validate(sub_domain_params)
+            if sub_domain_params is not None
+            else None
+        )
+        items: list[SearchArguments] = []
+        for query in queries:
+            values: dict[str, Any]
+            if isinstance(query, SearchArguments):
+                values = query.to_payload()
+            elif isinstance(query, str):
+                values = {"query": query}
+            else:
+                values = dict(query)
+
+            if domain is not None and values.get("domain") is None:
+                values["domain"] = str(domain)
+            if sub_domain is not None and values.get("sub_domain") is None:
+                values["sub_domain"] = sub_domain
+            if shared_params is not None and values.get("sub_domain_params") is None:
+                values["sub_domain_params"] = shared_params.root
+            items.append(SearchArguments.model_validate(values))
+        return cls(queries=tuple(items))
+
+
+class GetSubDomainsArguments(MCPArguments):
+    """MCP get_sub_domains tool arguments."""
+
+    tool_name = ToolName.GET_SUB_DOMAINS
+
+    domain: Domain | None = None
+    domains: tuple[Domain, ...] | None = Field(default=None, min_length=1, max_length=5)
+
+    @classmethod
+    def from_selector(
+        cls,
+        *,
+        domain: Domain | str | None = None,
+        domains: Sequence[Domain | str] | None = None,
+    ) -> Self:
+        return cls.model_validate(
+            {
+                "domain": domain,
+                "domains": tuple(domains) if domains is not None else None,
+            },
+        )
+
+    @model_validator(mode="after")
+    def validate_domain_selector(self) -> Self:
+        has_domain = self.domain is not None
+        has_domains = self.domains is not None
+        if has_domain == has_domains:
+            msg = "provide exactly one of domain or domains"
+            raise ValueError(msg)
+        return self
+
+
+class ExtractArguments(MCPArguments):
+    """MCP extract tool arguments."""
+
+    tool_name = ToolName.EXTRACT
+
+    url: HttpUrl
+
+    @classmethod
+    def from_url(cls, url: str) -> Self:
+        return cls.model_validate({"url": url})
+
+
+class MCPContentBlock(ResponseModel):
+    """One MCP content block."""
+
+    type: str
+    text: str | None = None
+
+
+class MCPToolResult(ResponseModel):
+    """MCP tools/call result."""
+
+    content: tuple[MCPContentBlock, ...] = ()
+    is_error: bool = Field(default=False, alias="isError")
+
+    @computed_field
+    @property
+    def text(self) -> str:
+        return "\n".join(
+            block.text for block in self.content if block.type == "text" and block.text
+        )
+
+    def raise_if_error(self) -> None:
+        if not self.is_error:
+            return
+
+        raise JSONRPCError(self.text or "MCP tool returned an error")
+
+
+class JSONRPCErrorObject(ResponseModel):
+    code: int
+    message: str
+    data: JsonValue | None = None
+
+    def raise_error(self) -> None:
+        raise JSONRPCError(self.message, code=self.code, data=self.data)
+
+
+class JSONRPCResponse[DataT](ResponseModel):
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: int | str | None = None
+    result: DataT | None = None
+    error: JSONRPCErrorObject | None = None
+
+    @model_validator(mode="after")
+    def validate_result_or_error(self) -> Self:
+        if (self.result is None) == (self.error is None):
+            msg = "JSON-RPC response must contain exactly one of result or error"
+            raise ValueError(msg)
+        return self
+
+    def unwrap(self) -> DataT:
+        if self.error is not None:
+            self.error.raise_error()
+        if self.result is None:
+            msg = "MCP response is missing result"
+            raise ResponseValidationError(msg, payload=self.model_dump(mode="json"))
+        return self.result
+
+
+class MCPToolResponse(JSONRPCResponse[MCPToolResult]):
+    """Successful MCP tools/call response."""
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> MCPToolResult:
+        try:
+            result = cls.model_validate(payload).unwrap()
+        except ValidationError as exc:
+            msg = "MCP response does not match JSON-RPC tools/call schema"
+            raise ResponseValidationError(msg, payload=payload) from exc
+        result.raise_if_error()
+        return result
+
+
+class JSONRPCToolCallParams(StrictRequestModel):
+    name: ToolName
+    arguments: JsonObject
+
+
+class JSONRPCToolCallRequest(StrictRequestModel):
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: int
+    method: Literal["tools/call"] = "tools/call"
+    params: JSONRPCToolCallParams
+
+
+class MCPToolCall(StrictRequestModel):
+    """MCP tool call before JSON-RPC wrapping."""
+
+    name: ToolName
+    arguments: JsonObject = Field(default_factory=dict)
+
+    @classmethod
+    def from_arguments(
+        cls,
+        name: ToolName | str,
+        arguments: MCPArguments | Mapping[str, JsonValue] | None = None,
+    ) -> MCPToolCall:
+        if isinstance(arguments, MCPArguments):
+            return arguments.to_tool_call()
+        return cls.model_validate({"name": name, "arguments": dict(arguments or {})})
+
+    def to_request(self, request_id: int) -> JSONRPCToolCallRequest:
+        return JSONRPCToolCallRequest(
+            id=request_id,
+            params=JSONRPCToolCallParams(
+                name=self.name,
+                arguments=self.arguments,
+            ),
+        )