snipget-client 0.1.0__py3-none-any.whl

snipget/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python client for the Snipget API.
+
+Snipget is a hosted utility API for AI agents and developers: data
+normalization, parsing, validation, and classification. This package is a
+thin HTTP wrapper around it — the per-endpoint contract lives in the
+OpenAPI spec at https://api.snipget.ai/openapi.json.
+
+    from snipget import Client
+
+    client = Client(api_key="...")  # or set SNIPGET_API_KEY
+    resp = client.call("/healthcare/npi/validate", {"npi": "1234567893"})
+    print(resp.result, resp.confidence, resp.meta.request_id)
+"""
+
+from snipget._client import AsyncClient, Client
+from snipget._exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    MaintenanceError,
+    QuotaExceededError,
+    RateLimitError,
+    SnipgetError,
+)
+from snipget._response import ResponseMeta, SnipgetResponse
+from snipget._version import __version__
+
+__all__ = [
+    "APIError",
+    "AsyncClient",
+    "AuthenticationError",
+    "Client",
+    "InvalidRequestError",
+    "MaintenanceError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ResponseMeta",
+    "SnipgetError",
+    "SnipgetResponse",
+    "__version__",
+]

snipget/_client.py

@@ -0,0 +1,373 @@
+"""Sync and async HTTP clients for the Snipget API.
+
+This module is deliberately a *thin* transport wrapper: it injects auth
+headers, retries transient failures, and converts the JSON response
+envelope into :class:`SnipgetResponse` / typed exceptions. It contains
+zero business logic by design — the hosted API is the product, and the
+OpenAPI spec at https://api.snipget.ai/openapi.json is the per-endpoint
+contract.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from snipget._exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    MaintenanceError,
+    QuotaExceededError,
+    RateLimitError,
+    SnipgetError,
+)
+from snipget._response import SnipgetResponse
+from snipget._version import __version__
+
+__all__ = ["AsyncClient", "Client"]
+
+DEFAULT_BASE_URL = "https://api.snipget.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+_ENV_API_KEY = "SNIPGET_API_KEY"
+_USER_AGENT = f"snipget-python/{__version__}"
+
+# Retry tuning. Exponential backoff: 0.5s, 1s, 2s, ... capped at 8s, plus
+# up to 25% jitter so synchronized callers don't stampede on recovery.
+_BACKOFF_BASE = 0.5
+_BACKOFF_CAP = 8.0
+# Never sleep longer than this even if the server's Retry-After asks for
+# more (e.g. the 300s maintenance window) — a blocking 5-minute sleep
+# inside a utility call would be hostile to callers.
+_RETRY_AFTER_CAP = 60.0
+
+# Test seam: tests monkeypatch these to assert on sleep behavior without
+# slowing the suite down.
+_sleep = time.sleep
+_async_sleep = asyncio.sleep
+
+AuthHeaderStyle = Literal["authorization", "x-api-key"]
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    key = api_key if api_key is not None else os.environ.get(_ENV_API_KEY)
+    if not key:
+        raise AuthenticationError(
+            "No API key provided. Pass api_key=... to the client or set the "
+            f"{_ENV_API_KEY} environment variable. Get a key at https://snipget.ai."
+        )
+    return key
+
+
+def _build_headers(api_key: str, auth_header: AuthHeaderStyle) -> dict[str, str]:
+    headers = {"User-Agent": _USER_AGENT}
+    if auth_header == "authorization":
+        headers["Authorization"] = f"Bearer {api_key}"
+    elif auth_header == "x-api-key":
+        headers["X-API-Key"] = api_key
+    else:
+        raise ValueError(f"auth_header must be 'authorization' or 'x-api-key', got {auth_header!r}")
+    return headers
+
+
+def _resolve_method(method: str | None, payload: dict[str, Any] | None) -> str:
+    """Default to POST when a payload is given, GET otherwise.
+
+    All 128 utility endpoints are POST; the handful of GET endpoints
+    (/, /health, /pricing/tiers, ...) take no payload, so the default does
+    the right thing for every path in the spec. ``method`` overrides.
+    """
+    if method is not None:
+        return method.upper()
+    return "POST" if payload is not None else "GET"
+
+
+def _normalize_path(path: str) -> str:
+    return path if path.startswith("/") else f"/{path}"
+
+
+def _retry_after_seconds(response: httpx.Response, body: dict[str, Any] | None) -> float | None:
+    """Pull the retry hint from ``retry_after_seconds`` (envelope, exact
+    float) or the ``Retry-After`` header (integer seconds, rounded up by
+    the server)."""
+    if isinstance(body, dict):
+        value = body.get("retry_after_seconds")
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return float(value)
+    header = response.headers.get("Retry-After")
+    if header is not None:
+        try:
+            return float(header)
+        except ValueError:
+            return None
+    return None
+
+
+def _parse_success(response: httpx.Response) -> SnipgetResponse:
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise APIError(
+            "Expected a JSON envelope but the response body was not valid JSON.",
+            http_status=response.status_code,
+        ) from exc
+    if not isinstance(data, dict):
+        raise APIError(
+            "Expected a JSON envelope object but got a different JSON type.",
+            http_status=response.status_code,
+        )
+    return SnipgetResponse.from_dict(data)
+
+
+def _error_from_response(response: httpx.Response) -> SnipgetError:
+    """Map a non-2xx response onto the typed exception taxonomy."""
+    status = response.status_code
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if not isinstance(body, dict):
+        return APIError(
+            f"HTTP {status} with a non-JSON body.",
+            http_status=status,
+        )
+
+    error_code = body.get("error_code")
+    message = body.get("message") or f"HTTP {status}"
+    meta = body.get("meta") if isinstance(body.get("meta"), dict) else {}
+    common: dict[str, Any] = {
+        "error_code": error_code,
+        "request_id": meta.get("request_id"),
+        "http_status": status,
+        "body": body,
+    }
+
+    if status == 429:
+        if error_code == "QUOTA_EXCEEDED":
+            return QuotaExceededError(
+                message,
+                credit_remaining_usd=meta.get("credit_remaining_usd"),
+                **common,
+            )
+        # RATE_LIMITED (and any future throttle variant on 429).
+        return RateLimitError(
+            message,
+            retry_after=_retry_after_seconds(response, body),
+            **common,
+        )
+    if status == 503 and error_code == "MAINTENANCE_MODE":
+        return MaintenanceError(
+            message,
+            retry_after=_retry_after_seconds(response, body),
+            **common,
+        )
+    if status in (401, 403):
+        return AuthenticationError(message, **common)
+    if status in (400, 422):
+        return InvalidRequestError(message, **common)
+    return APIError(message, **common)
+
+
+def _is_retryable(error: SnipgetError) -> bool:
+    """Whether a retry can possibly succeed.
+
+    Snipget utility calls are pure and idempotent (same input, same
+    output, no server-side state mutation), so retrying POSTs is safe.
+
+    - QUOTA_EXCEEDED never retries: it doesn't lift until the monthly
+      reset, a tier upgrade, or an allowance top-up.
+    - RATE_LIMITED retries: it's a per-second throttle.
+    - 5xx retries (includes MAINTENANCE_MODE, with short backoff).
+    - All other 4xx never retry: resending the same bad request can't help.
+    """
+    if isinstance(error, QuotaExceededError):
+        return False
+    if isinstance(error, RateLimitError):
+        return True
+    return error.http_status is not None and error.http_status >= 500
+
+
+def _retry_delay(error: SnipgetError | None, attempt: int) -> float:
+    """Seconds to sleep before retry number ``attempt`` (0-based).
+
+    RATE_LIMITED honors the server's Retry-After (capped). Everything
+    else — network errors, 5xx, maintenance — uses exponential backoff
+    with jitter; we deliberately do NOT honor maintenance's 300s hint
+    here (see MaintenanceError's docstring).
+    """
+    if isinstance(error, RateLimitError) and error.retry_after is not None:
+        return min(error.retry_after, _RETRY_AFTER_CAP)
+    base = min(_BACKOFF_BASE * (2**attempt), _BACKOFF_CAP)
+    return base + random.uniform(0.0, base / 4)
+
+
+class Client:
+    """Synchronous Snipget API client.
+
+    Args:
+        api_key: Your Snipget API key. Falls back to the
+            ``SNIPGET_API_KEY`` environment variable when omitted.
+        base_url: API origin; override for testing or self-hosted stacks.
+        timeout: Per-request timeout in seconds.
+        max_retries: How many times to retry retryable failures (network
+            errors, RATE_LIMITED, 5xx) on top of the initial attempt.
+        auth_header: ``"authorization"`` sends ``Authorization: Bearer <key>``
+            (preferred); ``"x-api-key"`` sends ``X-API-Key: <key>``.
+        transport: Optional httpx transport (proxies, mocking, ...).
+
+    Usage:
+        >>> from snipget import Client
+        >>> client = Client()  # reads SNIPGET_API_KEY
+        >>> resp = client.call("/healthcare/npi/validate", {"npi": "1234567893"})
+        >>> resp.result["is_valid"]
+        True
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        auth_header: AuthHeaderStyle = "authorization",
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.api_key = _resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=_build_headers(self.api_key, auth_header),
+            transport=transport,
+        )
+
+    def call(
+        self,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        method: str | None = None,
+    ) -> SnipgetResponse:
+        """Call any Snipget endpoint and return the parsed envelope.
+
+        Args:
+            path: Endpoint path, e.g. ``"/healthcare/npi/validate"``.
+            payload: JSON body. When given, the request defaults to POST.
+            method: Explicit HTTP method override.
+
+        Raises:
+            SnipgetError subclasses mapped from the error envelope.
+        """
+        resolved_method = _resolve_method(method, payload)
+        request_path = _normalize_path(path)
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(resolved_method, request_path, json=payload)
+            except httpx.TransportError as exc:
+                if attempt >= self.max_retries:
+                    raise APIError(f"Network error calling {request_path}: {exc}") from exc
+                _sleep(_retry_delay(None, attempt))
+                continue
+            if response.is_success:
+                return _parse_success(response)
+            error = _error_from_response(response)
+            if attempt >= self.max_retries or not _is_retryable(error):
+                raise error
+            _sleep(_retry_delay(error, attempt))
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Asynchronous Snipget API client. Same surface as :class:`Client`.
+
+    Usage:
+        >>> from snipget import AsyncClient
+        >>> async with AsyncClient() as client:
+        ...     resp = await client.call("/healthcare/npi/validate", {"npi": "1234567893"})
+        ...     resp.result["is_valid"]
+        True
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        auth_header: AuthHeaderStyle = "authorization",
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.api_key = _resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=_build_headers(self.api_key, auth_header),
+            transport=transport,
+        )
+
+    async def call(
+        self,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        method: str | None = None,
+    ) -> SnipgetResponse:
+        """Async variant of :meth:`Client.call`."""
+        resolved_method = _resolve_method(method, payload)
+        request_path = _normalize_path(path)
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._http.request(resolved_method, request_path, json=payload)
+            except httpx.TransportError as exc:
+                if attempt >= self.max_retries:
+                    raise APIError(f"Network error calling {request_path}: {exc}") from exc
+                await _async_sleep(_retry_delay(None, attempt))
+                continue
+            if response.is_success:
+                return _parse_success(response)
+            error = _error_from_response(response)
+            if attempt >= self.max_retries or not _is_retryable(error):
+                raise error
+            await _async_sleep(_retry_delay(error, attempt))
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

snipget/_exceptions.py

@@ -0,0 +1,145 @@
+"""Typed exception taxonomy for the Snipget client.
+
+Every exception maps one-to-one onto the API's error envelope:
+
+    {"status": "error", "error_code": "...", "message": "...", "meta": {...}}
+
+The full parsed envelope is always available on ``exc.body`` so callers can
+reach envelope fields the typed attributes don't surface (e.g. the ``details``
+list on 422 validation errors, or ``limit_type`` on quota errors).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "MaintenanceError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "SnipgetError",
+]
+
+
+class SnipgetError(Exception):
+    """Base class for every error raised by the Snipget client.
+
+    Attributes:
+        message: Human-readable message from the API (or the client).
+        error_code: Machine-readable code from the error envelope,
+            e.g. ``"INVALID_API_KEY"``. ``None`` when no envelope was
+            available (network failure, non-JSON body).
+        request_id: The ``meta.request_id`` from the envelope; quote it
+            when contacting support.
+        http_status: HTTP status code of the response, or ``None`` for
+            errors raised before a response existed.
+        body: The full parsed error envelope dict, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: str | None = None,
+        request_id: str | None = None,
+        http_status: int | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.request_id = request_id
+        self.http_status = http_status
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.error_code is not None:
+            parts.append(f"[error_code={self.error_code}]")
+        if self.http_status is not None:
+            parts.append(f"[http_status={self.http_status}]")
+        if self.request_id is not None:
+            parts.append(f"[request_id={self.request_id}]")
+        return " ".join(parts)
+
+
+class AuthenticationError(SnipgetError):
+    """401/403 — missing, invalid, or restricted API key.
+
+    Covers ``MISSING_API_KEY``, ``INVALID_API_KEY``, and ``IP_NOT_ALLOWED``.
+    Also raised client-side when no API key can be resolved at all.
+    """
+
+
+class InvalidRequestError(SnipgetError):
+    """400/422 — the request was rejected before any work was done.
+
+    ``INVALID_INPUT`` (400) or ``INVALID_REQUEST`` (422). For 422s the
+    Pydantic field errors are in ``exc.body["details"]``.
+    """
+
+
+class RateLimitError(SnipgetError):
+    """429 ``RATE_LIMITED`` — per-second throughput throttle.
+
+    Retryable within seconds; the client retries these automatically,
+    honoring ``retry_after``. Distinct from :class:`QuotaExceededError`,
+    which does not lift until the next month / an upgrade / a top-up.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, from the envelope's
+            ``retry_after_seconds`` (preferred) or the ``Retry-After``
+            header. ``None`` if the server sent neither.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(SnipgetError):
+    """429 ``QUOTA_EXCEEDED`` — monthly quota or prepaid allowance exhausted.
+
+    NOT retryable: it does not lift until the next UTC calendar month, a
+    tier upgrade, or an allowance purchase. The client never retries it.
+    ``exc.body["limit_type"]`` says which recovery applies
+    (``monthly_quota`` / ``included_exhausted`` / ``overage_balance_exhausted``).
+
+    Attributes:
+        credit_remaining_usd: Live prepaid-allowance balance from
+            ``meta.credit_remaining_usd``, when the server included it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        credit_remaining_usd: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.credit_remaining_usd = credit_remaining_usd
+
+
+class MaintenanceError(SnipgetError):
+    """503 ``MAINTENANCE_MODE`` — the API is in a maintenance window.
+
+    Attributes:
+        retry_after: Seconds until the server suggests retrying
+            (typically 300). The client's automatic retries use its own
+            short backoff instead of sleeping this long; if you see this
+            exception, wait ``retry_after`` seconds and call again.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class APIError(SnipgetError):
+    """Any other failure: unexpected status codes, 5xx errors, non-JSON
+    bodies, and network errors that survived the retry budget
+    (``http_status`` is ``None`` for those)."""

snipget/_response.py

@@ -0,0 +1,101 @@
+"""Typed views over the Snipget success envelope.
+
+Every Snipget endpoint returns the same JSON envelope:
+
+    {
+      "status": "ok",
+      "confidence": 0.92,
+      "result": {...},
+      "meta": {"version": "...", "elapsed_ms": 3, "cost_units": 1,
+               "request_id": "req_...", ...}
+    }
+
+These classes only *carry* that envelope; they never reshape or interpret
+``result``. The per-endpoint result schemas live in the OpenAPI spec at
+https://api.snipget.ai/openapi.json.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["ResponseMeta", "SnipgetResponse"]
+
+
+def _opt_int(value: Any) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _opt_float(value: Any) -> float | None:
+    if isinstance(value, bool):
+        return None
+    return float(value) if isinstance(value, (int, float)) else None
+
+
+@dataclass(frozen=True)
+class ResponseMeta:
+    """Typed view of the envelope's ``meta`` object.
+
+    Fields the server didn't send are ``None``. The untouched meta dict is
+    available as ``raw`` (so additive server-side fields are never lost).
+    """
+
+    version: str | None = None
+    elapsed_ms: int | None = None
+    cost_units: int | None = None
+    request_id: str | None = None
+    trace: list[str] | None = None
+    rate_limit_remaining: int | None = None
+    rate_limit_reset: int | None = None  # unix timestamp
+    quota_remaining: int | None = None
+    quota_reset: int | None = None  # unix timestamp (start of next UTC month)
+    credit_remaining_usd: float | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ResponseMeta:
+        return cls(
+            version=data.get("version"),
+            elapsed_ms=_opt_int(data.get("elapsed_ms")),
+            cost_units=_opt_int(data.get("cost_units")),
+            request_id=data.get("request_id"),
+            trace=data.get("trace"),
+            rate_limit_remaining=_opt_int(data.get("rate_limit_remaining")),
+            rate_limit_reset=_opt_int(data.get("rate_limit_reset")),
+            quota_remaining=_opt_int(data.get("quota_remaining")),
+            quota_reset=_opt_int(data.get("quota_reset")),
+            credit_remaining_usd=_opt_float(data.get("credit_remaining_usd")),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class SnipgetResponse:
+    """One parsed success envelope.
+
+    Attributes:
+        status: Always ``"ok"`` for a success envelope.
+        confidence: 0.0-1.0 confidence score for the result.
+        result: The endpoint-specific payload, exactly as the API sent it.
+        meta: Typed metadata (cost_units, request_id, rate-limit and
+            quota headroom, ...).
+        raw: The full unmodified envelope dict.
+    """
+
+    status: str
+    confidence: float
+    result: Any
+    meta: ResponseMeta
+    raw: dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SnipgetResponse:
+        meta = data.get("meta")
+        return cls(
+            status=data.get("status", "ok"),
+            confidence=float(data.get("confidence", 0.0)),
+            result=data.get("result"),
+            meta=ResponseMeta.from_dict(meta if isinstance(meta, dict) else {}),
+            raw=data,
+        )

snipget/_version.py

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

snipget_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: snipget-client
+Version: 0.1.0
+Summary: Official Python client for the Snipget API: data normalization, parsing, validation, and classification utilities for AI agents.
+Project-URL: Homepage, https://snipget.ai
+Project-URL: Documentation, https://api.snipget.ai/docs
+Project-URL: Repository, https://github.com/snipget/snipget-python
+Author-email: "Snipget Inc." <hello@snipget.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,ai-agents,api,data-normalization,data-validation,healthcare,llm,mcp,npi,parsing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# snipget-client
+
+The official Python client for [Snipget](https://snipget.ai), the hosted utility API for AI agents: data normalization, parsing, validation, and classification over plain HTTPS.
+
+## What is Snipget
+
+Snipget is a hosted, pay-per-call utility API built for AI agents and the developers who build them. It serves 130+ programmatic endpoints for data normalization, parsing, validation, and classification, with particular depth in healthcare data: NPI validation and lookup, DEA numbers, provider taxonomy, credentials, and certifications. Every endpoint is deterministic (no LLM calls inside the API), returns a confidence score, and ships in single-record and batch variants.
+
+Snipget is agent-native by design. Agents can discover and call it through the [OpenAPI spec](https://api.snipget.ai/openapi.json) or the MCP server, and every response uses one consistent JSON envelope so a single integration covers the whole catalog. This package is a thin HTTP wrapper around that hosted API; all the actual logic runs server-side, and the [interactive docs](https://api.snipget.ai/docs) are the per-endpoint contract.
+
+## Install
+
+```bash
+pip install snipget-client
+```
+
+Requires Python 3.10+. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+You need an API key from [snipget.ai](https://snipget.ai). One generic `call()` method reaches every endpoint; pass the path and the JSON payload from the [API docs](https://api.snipget.ai/docs).
+
+```python
+from snipget import Client
+
+client = Client(api_key="YOUR_API_KEY")  # or set SNIPGET_API_KEY
+
+resp = client.call("/healthcare/npi/validate", {"npi": "1234567893"})
+
+print(resp.result)
+# {'npi': 1234567893, 'is_valid': True, 'checksum_valid': True, 'input_was_clean': True}
+print(resp.confidence)        # 1.0
+print(resp.meta.cost_units)   # 1
+print(resp.meta.request_id)   # 'req_...'
+
+# Batch variants exist for every utility:
+resp = client.call(
+    "/healthcare/npi/validate/batch",
+    {"items": ["1234567893", "1234567890"]},
+)
+print(resp.result["summary"])  # {'total': 2, 'valid': 1, 'invalid': 1}
+```
+
+Async, same surface:
+
+```python
+import asyncio
+from snipget import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:  # reads SNIPGET_API_KEY
+        resp = await client.call(
+            "/common/phone/validate",
+            {"value": "(415) 555-0132", "country_hint": "US"},
+        )
+        print(resp.result)
+
+asyncio.run(main())
+```
+
+`call()` defaults to `POST` when a payload is given and `GET` otherwise, which matches every endpoint in the spec; pass `method=` to override.
+
+## Authentication
+
+Get an API key at [snipget.ai](https://snipget.ai). The client resolves the key in this order:
+
+1. `Client(api_key="...")`
+2. The `SNIPGET_API_KEY` environment variable
+
+By default the key is sent as `Authorization: Bearer <key>`. The API also accepts an `X-API-Key` header; opt in with `Client(auth_header="x-api-key")`.
+
+## Error handling
+
+Every API error is raised as a typed exception. All of them subclass `SnipgetError` and carry `error_code`, `message`, `request_id`, `http_status`, and the full parsed envelope as `body`.
+
+```python
+import snipget
+
+client = snipget.Client()
+
+try:
+    resp = client.call("/healthcare/npi/validate", {"npi": "1234567893"})
+except snipget.AuthenticationError as e:
+    print("Check your API key:", e.error_code)            # 401/403
+except snipget.InvalidRequestError as e:
+    print("Bad request:", e.body.get("details"))           # 400/422
+except snipget.RateLimitError as e:
+    print("Throttled; retry in", e.retry_after, "seconds")  # 429 RATE_LIMITED
+except snipget.QuotaExceededError as e:
+    print("Out of monthly capacity:", e.body.get("limit_type"))
+    print("Allowance left (USD):", e.credit_remaining_usd)  # 429 QUOTA_EXCEEDED
+except snipget.MaintenanceError as e:
+    print("Maintenance window; retry in", e.retry_after)    # 503 MAINTENANCE_MODE
+except snipget.APIError as e:
+    print("Server error; quote this id to support:", e.request_id)
+```
+
+The two 429s mean different things: `RateLimitError` is a per-second throughput throttle and clears in seconds; `QuotaExceededError` means the monthly included calls or prepaid overage allowance are exhausted and will not clear until the monthly reset, a tier upgrade, or an allowance top-up. The client retries the first automatically and never retries the second.
+
+## Retries and timeouts
+
+```python
+client = Client(
+    api_key="...",
+    timeout=30.0,      # per-request timeout in seconds
+    max_retries=2,     # retries on top of the initial attempt
+)
+```
+
+The client automatically retries network errors, `RATE_LIMITED` 429s (honoring the server's `Retry-After`), and 5xx responses, using exponential backoff with jitter. Snipget utility calls are pure and idempotent, so retrying a POST is safe. It never retries `QUOTA_EXCEEDED` or any other 4xx. Maintenance 503s are retried on the short backoff only; if the window outlasts the retry budget you get a `MaintenanceError` with `retry_after` (typically 300 seconds) so you can schedule your own retry.
+
+## The response envelope
+
+Every Snipget endpoint, success or error, returns one envelope shape. `call()` returns a `SnipgetResponse`:
+
+| Attribute | Type | Meaning |
+| --- | --- | --- |
+| `result` | endpoint-specific | The payload, exactly as the API returned it |
+| `confidence` | `float` | 0.0-1.0 confidence score (1.0 = deterministic match; batch responses always report 1.0 at the top level, with per-item confidences inside `result.items`) |
+| `status` | `str` | `"ok"` on success |
+| `meta.cost_units` | `int` | Billable units consumed by this call |
+| `meta.request_id` | `str` | Server request id; quote it to support |
+| `meta.elapsed_ms` | `int` | Server-side processing time |
+| `meta.version` | `str` | API version |
+| `meta.rate_limit_remaining` / `meta.rate_limit_reset` | `int` | Throughput headroom and bucket reset (unix time) |
+| `meta.quota_remaining` / `meta.quota_reset` | `int` | Monthly included-call headroom and reset (unix time) |
+| `meta.credit_remaining_usd` | `float` | Live prepaid-allowance balance, populated once a call starts burning allowance |
+| `meta.trace` | `list[str]` | Reasoning trace, when the request set `include_trace: true` |
+| `raw` | `dict` | The full unmodified envelope |
+
+Meta fields the server didn't send are `None`; unknown future fields stay available via `meta.raw`.
+
+## Links
+
+- Website: [https://snipget.ai](https://snipget.ai)
+- Interactive API docs: [https://api.snipget.ai/docs](https://api.snipget.ai/docs)
+- OpenAPI spec: [https://api.snipget.ai/openapi.json](https://api.snipget.ai/openapi.json)
+- npm sibling: a JavaScript/TypeScript client (`snipget` on npm) is planned but not yet published
+
+## License
+
+MIT. Copyright 2026 Snipget Inc.

snipget_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+snipget/__init__.py,sha256=r-9_yIdBmBg6zV-D3-AiC7vxf_zRCnSC-q0-K0IP8Ro,1153
+snipget/_client.py,sha256=-gzfdPmyTvDuF3jSOOWGDE3ppd45A1Fed9KUIKoooTQ,13074
+snipget/_exceptions.py,sha256=yJwZvuS47AO2geH1IGv-oxAQOgBjDvmWdS3xnO10Ato,5058
+snipget/_response.py,sha256=yFKaxfCgQ6QyaCeJ1C68YsQJvOsXyVFf3fyWqMfg8mM,3400
+snipget/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+snipget/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snipget_client-0.1.0.dist-info/METADATA,sha256=AZ-mnn4s5ChIEk1CME80LNXjbgW1dvPPKD5j47h_IwU,8048
+snipget_client-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+snipget_client-0.1.0.dist-info/licenses/LICENSE,sha256=2PzLutoeZb-V1r-HyjZBns49deP9cvKzmdgpj3ZA0cU,1065
+snipget_client-0.1.0.dist-info/RECORD,,

snipget_client-0.1.0.dist-info/WHEEL

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

snipget_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Snipget Inc.
+
+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.