ateve 0.0.1__py3-none-any.whl

ateve/__init__.py

@@ -0,0 +1,64 @@
+"""Official Python SDK for the Ateve Search API."""
+
+from ._version import __version__
+from .client import AsyncAteve, Ateve
+from .errors import (
+    ApiConnectionError,
+    ApiError,
+    ApiResponseError,
+    AteveError,
+    AuthenticationError,
+    ConcurrencyLimitError,
+    InvalidRequestError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServerError,
+)
+from .models import (
+    AnswerBlock,
+    Citation,
+    ContentFormat,
+    ContentOptions,
+    ImageItem,
+    LocaleSettings,
+    QueryInfo,
+    SearchRequest,
+    SearchResponse,
+    SearchResult,
+    Topic,
+    Usage,
+    UsageBreakdown,
+    UserLocation,
+    VideoItem,
+)
+
+__all__ = [
+    "AnswerBlock",
+    "ApiConnectionError",
+    "ApiError",
+    "ApiResponseError",
+    "AsyncAteve",
+    "Ateve",
+    "AteveError",
+    "AuthenticationError",
+    "Citation",
+    "ConcurrencyLimitError",
+    "ContentFormat",
+    "ContentOptions",
+    "ImageItem",
+    "InvalidRequestError",
+    "LocaleSettings",
+    "PaymentRequiredError",
+    "QueryInfo",
+    "RateLimitError",
+    "SearchRequest",
+    "SearchResponse",
+    "SearchResult",
+    "ServerError",
+    "Topic",
+    "Usage",
+    "UsageBreakdown",
+    "UserLocation",
+    "VideoItem",
+    "__version__",
+]

ateve/_version.py

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

ateve/client.py

@@ -0,0 +1,520 @@
+"""Synchronous and asynchronous Ateve Search API clients."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, Optional, Union
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+from pydantic import ValidationError
+
+from ._version import __version__
+from .errors import (
+    ApiConnectionError,
+    ApiResponseError,
+    AuthenticationError,
+    ConcurrencyLimitError,
+    InvalidRequestError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServerError,
+)
+from .models import (
+    ContentOptions,
+    LocaleSettings,
+    SearchRequest,
+    SearchResponse,
+    Topic,
+)
+
+DEFAULT_BASE_URL = "https://api.ateve.ai"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_CONNECT_TIMEOUT = 5.0
+DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+USER_AGENT = f"ateve-python/{__version__}"
+_BILLING_CODES = {"insufficient_credit", "credit_limit_exceeded", "payment_required"}
+
+
+class _BodyLimitExceeded(Exception):
+    pass
+
+
+def _require_api_key(api_key: Optional[str]) -> str:
+    value = api_key if api_key is not None else os.getenv("ATEVE_API_KEY")
+    if value is None or not value.strip():
+        raise ValueError("API key missing: pass api_key or set ATEVE_API_KEY")
+    value = value.strip()
+    if any(character in value for character in ("\r", "\n", "\0")):
+        raise ValueError("api_key must not contain CR, LF, or NUL characters")
+    return value
+
+
+def _normalize_base_url(base_url: Optional[str]) -> str:
+    value = base_url if base_url is not None else os.getenv("ATEVE_BASE_URL", DEFAULT_BASE_URL)
+    value = value.strip().rstrip("/")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme.lower() not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "base_url must be an absolute http(s) URL without user-info, query, or fragment"
+        )
+    return urlunsplit((parsed.scheme.lower(), parsed.netloc, parsed.path, "", ""))
+
+
+def _timeout(timeout: float, connect_timeout: float) -> httpx.Timeout:
+    if timeout <= 0 or connect_timeout <= 0:
+        raise ValueError("timeout and connect_timeout must be positive")
+    return httpx.Timeout(timeout, connect=connect_timeout)
+
+
+def _request_from_args(
+    query: Union[str, SearchRequest],
+    *,
+    limit: Optional[int],
+    offset: Optional[int],
+    date_range: Optional[str],
+    locale: Optional[LocaleSettings],
+    topic: Optional[Topic],
+    include_domains: Optional[list[str]],
+    exclude_domains: Optional[list[str]],
+    content: Optional[ContentOptions],
+    safe_search: Optional[bool],
+) -> SearchRequest:
+    options = (
+        limit,
+        offset,
+        date_range,
+        locale,
+        topic,
+        include_domains,
+        exclude_domains,
+        content,
+        safe_search,
+    )
+    if isinstance(query, SearchRequest):
+        if any(value is not None for value in options):
+            raise TypeError("options cannot be combined with a SearchRequest instance")
+        return query
+    return SearchRequest(
+        query=query,
+        limit=limit,
+        offset=offset,
+        date_range=date_range,
+        locale=locale,
+        topic=topic,
+        include_domains=include_domains,
+        exclude_domains=exclude_domains,
+        content=content,
+        safe_search=safe_search,
+    )
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return max(0, int(value.strip()))
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(value)
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        return max(0, int((when - datetime.now(timezone.utc)).total_seconds()))
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _read_json_object(body: bytes) -> Dict[str, Any]:
+    try:
+        value = json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def _map_api_error(response: httpx.Response, body: bytes) -> Exception:
+    payload = _read_json_object(body)
+    error = payload.get("error")
+    error = error if isinstance(error, dict) else {}
+    raw_request_id = payload.get("id") or response.headers.get("X-Request-Id")
+    status = response.status_code
+    raw_message = error.get("message")
+    message = raw_message if isinstance(raw_message, str) else f"HTTP {status}"
+    request_id = raw_request_id if isinstance(raw_request_id, str) else None
+    raw_code = error.get("code")
+    code = raw_code if isinstance(raw_code, str) else None
+    raw_param = error.get("param")
+    param = raw_param if isinstance(raw_param, str) else None
+    raw_type = error.get("type")
+    error_type = raw_type if isinstance(raw_type, str) else None
+    raw_doc_url = error.get("doc_url")
+    doc_url = raw_doc_url if isinstance(raw_doc_url, str) else None
+    if status == 401:
+        return AuthenticationError(
+            message,
+            status_code=status,
+            request_id=request_id,
+            code=code,
+            param=param,
+            error_type=error_type,
+            doc_url=doc_url,
+        )
+    if status == 402 or (status == 403 and code in _BILLING_CODES):
+        return PaymentRequiredError(
+            message,
+            status_code=status,
+            request_id=request_id,
+            code=code,
+            param=param,
+            error_type=error_type,
+            doc_url=doc_url,
+        )
+    if status == 429:
+        return RateLimitError(
+            message,
+            status_code=status,
+            request_id=request_id,
+            code=code,
+            param=param,
+            error_type=error_type,
+            doc_url=doc_url,
+            retry_after_seconds=_parse_retry_after(response.headers.get("Retry-After")),
+            limit_scope=response.headers.get("X-Ateve-Limit-Scope"),
+        )
+    if status >= 500:
+        return ServerError(
+            message,
+            status_code=status,
+            request_id=request_id,
+            code=code,
+            param=param,
+            error_type=error_type,
+            doc_url=doc_url,
+        )
+    return InvalidRequestError(
+        message,
+        status_code=status,
+        request_id=request_id,
+        code=code,
+        param=param,
+        error_type=error_type,
+        doc_url=doc_url,
+    )
+
+
+def _request_may_have_been_sent(error: httpx.HTTPError) -> bool:
+    return not isinstance(
+        error,
+        (
+            httpx.ConnectError,
+            httpx.ConnectTimeout,
+            httpx.PoolTimeout,
+            httpx.InvalidURL,
+            httpx.UnsupportedProtocol,
+        ),
+    )
+
+
+def _validate_limits(max_response_bytes: int, max_concurrent_requests: int) -> None:
+    if max_response_bytes < 0:
+        raise ValueError("max_response_bytes must be >= 0")
+    if max_concurrent_requests < 0:
+        raise ValueError("max_concurrent_requests must be >= 0")
+
+
+class _BaseAteve:
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: float,
+        connect_timeout: float,
+        max_response_bytes: int,
+        max_concurrent_requests: int,
+    ) -> None:
+        _validate_limits(max_response_bytes, max_concurrent_requests)
+        self._base_url = _normalize_base_url(base_url)
+        self._search_url = self._base_url + "/v1/search"
+        self._timeout = _timeout(timeout, connect_timeout)
+        self._max_response_bytes = max_response_bytes
+        self._max_concurrent_requests = max_concurrent_requests
+        self._headers = {
+            "Authorization": f"Bearer {_require_api_key(api_key)}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        self._closed = False
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("Ateve client is closed")
+
+    def _decode(self, response: httpx.Response, body: bytes) -> SearchResponse:
+        if not 200 <= response.status_code < 300:
+            raise _map_api_error(response, body)
+        try:
+            return SearchResponse.model_validate_json(body)
+        except ValidationError as exc:
+            raise ApiResponseError(
+                f"Response from {self._base_url} could not be decoded as SearchResponse",
+                status_code=response.status_code,
+                request_id=response.headers.get("X-Request-Id"),
+                base_url=self._base_url,
+            ) from exc
+
+
+class Ateve(_BaseAteve):
+    """Reusable synchronous client. Close it when the owning application stops."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
+        max_concurrent_requests: int = 0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+            max_response_bytes=max_response_bytes,
+            max_concurrent_requests=max_concurrent_requests,
+        )
+        self._owns_http_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=self._timeout, follow_redirects=False)
+        self._bulkhead = (
+            threading.BoundedSemaphore(max_concurrent_requests)
+            if max_concurrent_requests > 0
+            else None
+        )
+
+    def search(
+        self,
+        query: Union[str, SearchRequest],
+        *,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        date_range: Optional[str] = None,
+        locale: Optional[LocaleSettings] = None,
+        topic: Optional[Topic] = None,
+        include_domains: Optional[list[str]] = None,
+        exclude_domains: Optional[list[str]] = None,
+        content: Optional[ContentOptions] = None,
+        safe_search: Optional[bool] = None,
+    ) -> SearchResponse:
+        """Send exactly one search request; no retries or endpoint failover."""
+        self._ensure_open()
+        request = _request_from_args(
+            query,
+            limit=limit,
+            offset=offset,
+            date_range=date_range,
+            locale=locale,
+            topic=topic,
+            include_domains=include_domains,
+            exclude_domains=exclude_domains,
+            content=content,
+            safe_search=safe_search,
+        )
+        if self._bulkhead is not None and not self._bulkhead.acquire(blocking=False):
+            raise ConcurrencyLimitError(self._max_concurrent_requests)
+        try:
+            try:
+                with self._client.stream(
+                    "POST",
+                    self._search_url,
+                    headers=self._headers,
+                    json=request.model_dump(mode="json", exclude_none=True),
+                    timeout=self._timeout,
+                    follow_redirects=False,
+                ) as response:
+                    body = self._read_limited(response)
+            except _BodyLimitExceeded as exc:
+                raise ApiConnectionError(
+                    f"Response from {self._base_url} exceeded "
+                    f"max_response_bytes={self._max_response_bytes}",
+                    base_url=self._base_url,
+                    request_may_have_been_sent=True,
+                ) from exc
+            except httpx.HTTPError as exc:
+                raise ApiConnectionError(
+                    f"Request to {self._base_url} failed: {exc.__class__.__name__}",
+                    base_url=self._base_url,
+                    request_may_have_been_sent=_request_may_have_been_sent(exc),
+                ) from exc
+            return self._decode(response, body)
+        finally:
+            if self._bulkhead is not None:
+                self._bulkhead.release()
+
+    def _read_limited(self, response: httpx.Response) -> bytes:
+        declared = response.headers.get("Content-Length")
+        if (
+            self._max_response_bytes > 0
+            and declared is not None
+            and declared.isdigit()
+            and int(declared) > self._max_response_bytes
+        ):
+            raise _BodyLimitExceeded
+        body = bytearray()
+        for chunk in response.iter_bytes():
+            if (
+                self._max_response_bytes > 0
+                and len(chunk) > self._max_response_bytes - len(body)
+            ):
+                raise _BodyLimitExceeded
+            body.extend(chunk)
+        return bytes(body)
+
+    def close(self) -> None:
+        if not self._closed and self._owns_http_client:
+            self._client.close()
+        self._closed = True
+
+    def __enter__(self) -> Ateve:
+        self._ensure_open()
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self.close()
+
+
+class AsyncAteve(_BaseAteve):
+    """Reusable asynchronous client for high-concurrency applications."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
+        max_concurrent_requests: int = 0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+            max_response_bytes=max_response_bytes,
+            max_concurrent_requests=max_concurrent_requests,
+        )
+        self._owns_http_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=self._timeout, follow_redirects=False
+        )
+        self._in_flight = 0
+
+    async def search(
+        self,
+        query: Union[str, SearchRequest],
+        *,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        date_range: Optional[str] = None,
+        locale: Optional[LocaleSettings] = None,
+        topic: Optional[Topic] = None,
+        include_domains: Optional[list[str]] = None,
+        exclude_domains: Optional[list[str]] = None,
+        content: Optional[ContentOptions] = None,
+        safe_search: Optional[bool] = None,
+    ) -> SearchResponse:
+        """Send exactly one non-blocking search request."""
+        self._ensure_open()
+        request = _request_from_args(
+            query,
+            limit=limit,
+            offset=offset,
+            date_range=date_range,
+            locale=locale,
+            topic=topic,
+            include_domains=include_domains,
+            exclude_domains=exclude_domains,
+            content=content,
+            safe_search=safe_search,
+        )
+        if (
+            self._max_concurrent_requests > 0
+            and self._in_flight >= self._max_concurrent_requests
+        ):
+            raise ConcurrencyLimitError(self._max_concurrent_requests)
+        self._in_flight += 1
+        try:
+            try:
+                async with self._client.stream(
+                    "POST",
+                    self._search_url,
+                    headers=self._headers,
+                    json=request.model_dump(mode="json", exclude_none=True),
+                    timeout=self._timeout,
+                    follow_redirects=False,
+                ) as response:
+                    body = await self._read_limited(response)
+            except _BodyLimitExceeded as exc:
+                raise ApiConnectionError(
+                    f"Response from {self._base_url} exceeded "
+                    f"max_response_bytes={self._max_response_bytes}",
+                    base_url=self._base_url,
+                    request_may_have_been_sent=True,
+                ) from exc
+            except httpx.HTTPError as exc:
+                raise ApiConnectionError(
+                    f"Request to {self._base_url} failed: {exc.__class__.__name__}",
+                    base_url=self._base_url,
+                    request_may_have_been_sent=_request_may_have_been_sent(exc),
+                ) from exc
+            return self._decode(response, body)
+        finally:
+            self._in_flight -= 1
+
+    async def _read_limited(self, response: httpx.Response) -> bytes:
+        declared = response.headers.get("Content-Length")
+        if (
+            self._max_response_bytes > 0
+            and declared is not None
+            and declared.isdigit()
+            and int(declared) > self._max_response_bytes
+        ):
+            raise _BodyLimitExceeded
+        body = bytearray()
+        async for chunk in response.aiter_bytes():
+            if (
+                self._max_response_bytes > 0
+                and len(chunk) > self._max_response_bytes - len(body)
+            ):
+                raise _BodyLimitExceeded
+            body.extend(chunk)
+        return bytes(body)
+
+    async def aclose(self) -> None:
+        if not self._closed and self._owns_http_client:
+            await self._client.aclose()
+        self._closed = True
+
+    async def __aenter__(self) -> AsyncAteve:
+        self._ensure_open()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.aclose()

ateve/errors.py

@@ -0,0 +1,124 @@
+"""Typed errors raised by the Ateve Python SDK."""
+
+from typing import Optional
+
+
+class AteveError(Exception):
+    """Base class for all SDK errors."""
+
+
+class ApiError(AteveError):
+    """The API returned a non-success HTTP status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        request_id: Optional[str] = None,
+        code: Optional[str] = None,
+        param: Optional[str] = None,
+        error_type: Optional[str] = None,
+        doc_url: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.code = code
+        self.param = param
+        self.type = error_type
+        self.doc_url = doc_url
+
+    @property
+    def is_retryable(self) -> bool:
+        """Whether a caller-owned policy may consider the status retryable."""
+        return self.status_code == 429 or self.status_code >= 500
+
+
+class InvalidRequestError(ApiError):
+    """The request was rejected by validation or routing."""
+
+
+class AuthenticationError(ApiError):
+    """The API key was missing or invalid."""
+
+
+class PaymentRequiredError(ApiError):
+    """The account has insufficient credit or exceeded its credit limit."""
+
+
+class ServerError(ApiError):
+    """The API or its upstream search provider failed."""
+
+
+class RateLimitError(ApiError):
+    """A server-side rate limit was exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        request_id: Optional[str] = None,
+        code: Optional[str] = None,
+        param: Optional[str] = None,
+        error_type: Optional[str] = None,
+        doc_url: Optional[str] = None,
+        retry_after_seconds: Optional[int] = None,
+        limit_scope: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            request_id=request_id,
+            code=code,
+            param=param,
+            error_type=error_type,
+            doc_url=doc_url,
+        )
+        self.retry_after_seconds = retry_after_seconds
+        self.limit_scope = limit_scope
+
+
+class ApiConnectionError(AteveError):
+    """A DNS, connection, TLS, timeout, reset, or body-limit failure."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        base_url: str,
+        request_may_have_been_sent: bool,
+    ) -> None:
+        super().__init__(message)
+        self.base_url = base_url
+        self.request_may_have_been_sent = request_may_have_been_sent
+
+
+class ApiResponseError(AteveError):
+    """A success response could not be decoded as the documented schema."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        request_id: Optional[str],
+        base_url: str,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.base_url = base_url
+        self.request_may_have_been_sent = True
+
+
+class ConcurrencyLimitError(AteveError):
+    """Rejected locally before network I/O by the optional bulkhead."""
+
+    def __init__(self, max_concurrent_requests: int) -> None:
+        super().__init__(
+            "Concurrency limit reached "
+            f"(max_concurrent_requests={max_concurrent_requests}); request rejected"
+        )
+        self.max_concurrent_requests = max_concurrent_requests

ateve/models.py

@@ -0,0 +1,217 @@
+"""Pydantic request and response models for ``POST /v1/search``."""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+class Topic(str, Enum):
+    GENERAL = "general"
+    NEWS = "news"
+    PAPER = "paper"
+    DOCS = "docs"
+    CODE = "code"
+    FORUM = "forum"
+    WIKI = "wiki"
+    PEOPLE = "people"
+    COMPANY = "company"
+    PERSONAL_SITE = "personal_site"
+    FINANCIAL_REPORT = "financial_report"
+    GOVERNMENT = "government"
+    ECOMMERCE = "ecommerce"
+
+
+class ContentFormat(str, Enum):
+    TEXT = "text"
+    MARKDOWN = "markdown"
+
+
+class RequestModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+
+class UserLocation(RequestModel):
+    country: Optional[str] = Field(default=None, pattern=r"^[A-Z]{2}$")
+    region: Optional[str] = None
+    city: Optional[str] = None
+    timezone: Optional[str] = None
+
+    @field_validator("timezone")
+    @classmethod
+    def validate_timezone(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return value
+        try:
+            ZoneInfo(value)
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError("timezone must be a valid IANA Time Zone identifier") from exc
+        if value in {"PST", "EST", "CST", "MST"} or re.match(r"^UTC[+-]", value):
+            raise ValueError("timezone must be a region-based IANA identifier")
+        return value
+
+
+class LocaleSettings(RequestModel):
+    mkt: Optional[str] = Field(default=None, pattern=r"^[A-Z]{2}$")
+    language: Optional[str] = Field(default=None, pattern=r"^[a-z]{2}$")
+    user_location: Optional[UserLocation] = None
+
+
+class ContentOptions(RequestModel):
+    snippet: Optional[bool] = None
+    raw_content: Optional[bool] = None
+    format: Optional[ContentFormat] = None
+    summary: Optional[bool] = None
+    highlights: Optional[bool] = None
+    images: Optional[int] = Field(default=None, ge=0, le=10)
+    favicon: Optional[bool] = None
+
+
+_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def _parse_date(value: str) -> date:
+    if not _DATE.fullmatch(value):
+        raise ValueError("date_range contains an invalid date shape")
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(f"date_range contains an invalid calendar date: {value}") from exc
+
+
+def _validate_date_range(value: Optional[str]) -> Optional[str]:
+    if value is None or value == "" or value in {"day", "week", "month", "year"}:
+        return value
+    if ".." not in value:
+        _parse_date(value)
+        return value
+    if value.count("..") != 1:
+        raise ValueError("date_range must contain at most one '..' separator")
+    start_text, end_text = value.split("..")
+    if not start_text and not end_text:
+        raise ValueError("date_range cannot be '..'")
+    start = _parse_date(start_text) if start_text else None
+    end = _parse_date(end_text) if end_text else None
+    if start is not None and end is not None and end < start:
+        raise ValueError("date_range end date must be on or after the start date")
+    return value
+
+
+class SearchRequest(RequestModel):
+    query: str = Field(min_length=1, max_length=2000)
+    limit: Optional[int] = Field(default=None, ge=1, le=50)
+    offset: Optional[int] = Field(default=None, ge=0, le=1000)
+    date_range: Optional[str] = None
+    locale: Optional[LocaleSettings] = None
+    topic: Optional[Topic] = None
+    include_domains: Optional[List[str]] = Field(default=None, max_length=300)
+    exclude_domains: Optional[List[str]] = Field(default=None, max_length=300)
+    content: Optional[ContentOptions] = None
+    safe_search: Optional[bool] = None
+
+    @field_validator("query")
+    @classmethod
+    def query_must_not_be_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("query is required")
+        return value
+
+    @field_validator("date_range")
+    @classmethod
+    def date_range_must_be_valid(cls, value: Optional[str]) -> Optional[str]:
+        return _validate_date_range(value)
+
+    @model_validator(mode="after")
+    def copy_domain_lists(self) -> SearchRequest:
+        # Pydantic already copies normal inputs; this assertion keeps the
+        # validation path explicit and rejects null list entries consistently.
+        for name in ("include_domains", "exclude_domains"):
+            domains = getattr(self, name)
+            if domains is not None and any(domain is None for domain in domains):
+                raise ValueError(f"{name} must not contain null entries")
+        return self
+
+
+class ImageItem(ResponseModel):
+    url: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+    alt: Optional[str] = None
+
+
+class VideoItem(ResponseModel):
+    url: Optional[str] = None
+    thumbnail: Optional[str] = None
+    title: Optional[str] = None
+    duration_seconds: Optional[int] = None
+
+
+class Citation(ResponseModel):
+    url: Optional[str] = None
+    title: Optional[str] = None
+    start_index: Optional[int] = None
+    end_index: Optional[int] = None
+    quote: Optional[str] = None
+
+
+class AnswerBlock(ResponseModel):
+    content: Optional[str] = None
+    citations: Optional[List[Citation]] = None
+
+
+class QueryInfo(ResponseModel):
+    original: str
+    effective: Optional[str] = None
+    auto_tuned: Optional[Dict[str, Any]] = None
+
+
+class SearchResult(ResponseModel):
+    id: Optional[str] = None
+    title: Optional[str] = None
+    url: Optional[str] = None
+    display_url: Optional[str] = None
+    site_name: Optional[str] = None
+    language: Optional[str] = None
+    published_at: Optional[datetime] = None
+    score: Optional[float] = None
+    snippet: Optional[str] = None
+    raw_content: Optional[str] = None
+    summary: Optional[str] = None
+    highlights: Optional[List[str]] = None
+    favicon: Optional[str] = None
+    images: List[ImageItem] = Field(default_factory=list)
+    is_safe: Optional[bool] = None
+
+
+class UsageBreakdown(ResponseModel):
+    search: Optional[int] = None
+    rerank: Optional[int] = None
+    answer: Optional[int] = None
+
+
+class Usage(ResponseModel):
+    credits: Optional[int] = None
+    breakdown: Optional[UsageBreakdown] = None
+
+
+class SearchResponse(ResponseModel):
+    id: str
+    created: int
+    latency_ms: int
+    query: QueryInfo
+    answer: Optional[AnswerBlock] = None
+    results: List[SearchResult]
+    news: Optional[List[SearchResult]] = None
+    images: Optional[List[ImageItem]] = None
+    videos: Optional[List[VideoItem]] = None
+    total_estimated_matches: Optional[int] = None
+    usage: Optional[Usage] = None

ateve/py.typed

@@ -0,0 +1 @@
+

ateve-0.0.1.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: ateve
+Version: 0.0.1
+Summary: Official Python SDK for the Ateve Search API
+Project-URL: Homepage, https://ateve.ai
+Project-URL: Documentation, https://ateve.ai/docs
+Project-URL: Repository, https://github.com/ateve-inc/ateve-sdks
+Author-email: "Ateve Inc." <ops@ateve-inc.com>
+License: Apache-2.0
+Keywords: AI,RAG,ateve,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: tzdata>=2025.2; platform_system == 'Windows'
+Description-Content-Type: text/markdown
+
+# Ateve Python SDK
+
+Official typed client for `POST /v1/search`. Requires Python 3.11+.
+
+## Install
+
+```bash
+pip install ateve
+```
+
+## Synchronous
+
+```python
+from ateve import Ateve, ContentOptions, Topic
+
+with Ateve() as client:  # reads ATEVE_API_KEY
+    response = client.search(
+        query="quantum computing",
+        date_range="week",
+        topic=Topic.NEWS,
+        content=ContentOptions(summary=True, highlights=True),
+    )
+    print(response.results[0].title, response.usage.credits)
+```
+
+## Asynchronous
+
+```python
+from ateve import AsyncAteve
+
+async with AsyncAteve() as client:
+    response = await client.search("quantum computing", limit=10)
+```
+
+`Ateve` owns and closes its default `httpx.Client`; `AsyncAteve` does the same
+for its default `httpx.AsyncClient`. An injected `http_client` is borrowed and
+never closed by the SDK. Reuse one Ateve client for its connection pool instead
+of constructing one per request.
+
+Each `search` call sends exactly one HTTP request. The SDK never retries,
+backs off, or switches endpoints. This is intentional: a timeout/reset can
+happen after the billable search already ran. `ApiConnectionError` exposes
+`request_may_have_been_sent`; only DNS/connect/connect-timeout/pool-timeout
+failures are classified as definitely not sent.
+
+The built-in path defaults to a 60-second request timeout, 5-second connect
+timeout, a 32 MiB response cap, and no redirects. Use
+`max_concurrent_requests` for an optional fail-fast bulkhead.
+
+Typed errors include `AuthenticationError`, `PaymentRequiredError`,
+`RateLimitError`, `InvalidRequestError`, `ServerError`,
+`ApiConnectionError`, `ApiResponseError`, and `ConcurrencyLimitError`.
+`RateLimitError` preserves `retry_after_seconds` and `limit_scope`; retry
+decisions remain caller-owned.

ateve-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ateve/__init__.py,sha256=own73gS6yBOX3gb4SsmFBprj9BCeznsPEWLEC0-15_k,1224
+ateve/_version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+ateve/client.py,sha256=wr91nhWuWEL4stcZWYrec8mOyPKi3PVt426_B1Qc_SM,17744
+ateve/errors.py,sha256=dL19ZPnruG7YZAuGzuNxdfHAmkQ2GRAfOOaVgTThlJI,3431
+ateve/models.py,sha256=Ue1tTSyFowbTa3lqlfOW9-dzHeiuqx2HlCSSAhpXVAU,6866
+ateve/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ateve-0.0.1.dist-info/METADATA,sha256=E9FZmPegMhQ7j3eE8JTRN9YCiheaRCayoBS_fufLKfY,2815
+ateve-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ateve-0.0.1.dist-info/RECORD,,

ateve-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any