nvisionx 0.1.0__py3-none-any.whl

nvisionx/__init__.py

@@ -0,0 +1,51 @@
+from nvisionx import types
+from nvisionx._base_client import DEFAULT_BASE_URL
+from nvisionx._client import AsyncNx, Nx
+from nvisionx._errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    JobTimeoutError,
+    NotFoundError,
+    NxError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    StreamError,
+    UnprocessableEntityError,
+)
+from nvisionx._pagination import AsyncPage, AsyncPaginator, SyncPage
+from nvisionx._streaming import AsyncChatStream, ChatStream
+from nvisionx._version import __version__
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncChatStream",
+    "AsyncNx",
+    "AsyncPage",
+    "AsyncPaginator",
+    "AuthenticationError",
+    "BadRequestError",
+    "ChatStream",
+    "ConflictError",
+    "InternalServerError",
+    "JobTimeoutError",
+    "NotFoundError",
+    "Nx",
+    "NxError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "StreamError",
+    "SyncPage",
+    "UnprocessableEntityError",
+    "__version__",
+    "types",
+]

nvisionx/_base.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError, ValidatorFunctionWrapHandler, WrapValidator
+
+
+class NxModel(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+def _accept_unknown(value: Any, handler: ValidatorFunctionWrapHandler) -> Any:
+    try:
+        return handler(value)
+    except ValidationError:
+        if isinstance(value, (str, int)) and not isinstance(value, bool):
+            return value
+        raise
+
+
+Open = WrapValidator(_accept_unknown)

nvisionx/_base_client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+import random
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import IO, Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel
+
+from nvisionx._errors import NxError, parse_retry_after
+from nvisionx._version import __version__
+
+DEFAULT_BASE_URL = "https://platform.us.nvisionx.ai"
+DEFAULT_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
+DEFAULT_MAX_RETRIES = 2
+AGENT_TIMEOUT = httpx.Timeout(300.0, connect=10.0)
+UPLOAD_TIMEOUT = httpx.Timeout(60.0, connect=10.0, write=None)
+
+RETRYABLE_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0
+MAX_RETRY_AFTER = 60.0
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    method: str
+    path: str
+    params: Mapping[str, Any] | None = None
+    json: Any = None
+    data: Mapping[str, Any] | None = None
+    files: list[Any] | None = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    idempotency_key: str | None = None
+    timeout: httpx.Timeout | None = None
+
+
+def path(template: str, **params: str) -> str:
+    return template.format(**{k: quote(v, safe="") for k, v in params.items()})
+
+
+def drop_none(values: Mapping[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+class BaseClient:
+    api_key: str
+    base_url: httpx.URL
+    timeout: httpx.Timeout
+    max_retries: int
+    _owns_http: bool
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | httpx.URL | None,
+        timeout: float | httpx.Timeout | None,
+        max_retries: int,
+        default_headers: Mapping[str, str] | None,
+    ) -> None:
+        api_key = api_key or os.environ.get("NX_API_KEY")
+        if not api_key:
+            raise NxError("No API key: pass api_key= or set NX_API_KEY.")
+        self.api_key = api_key
+        self.base_url = httpx.URL(str(base_url or os.environ.get("NX_BASE_URL") or DEFAULT_BASE_URL).rstrip("/") + "/")
+        if timeout is None:
+            self.timeout = DEFAULT_TIMEOUT
+        elif isinstance(timeout, httpx.Timeout):
+            self.timeout = timeout
+        else:
+            self.timeout = httpx.Timeout(timeout)
+        self.max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+
+    def _bind_resources(self) -> None:
+        raise NotImplementedError
+
+    @property
+    def default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"nvisionx-python/{__version__}",
+            **self._default_headers,
+        }
+
+    def _prepare(self, options: RequestOptions) -> RequestOptions:
+        if options.method == "GET" or options.idempotency_key:
+            return options
+        return replace(options, idempotency_key=f"nx-py-{uuid.uuid4()}")
+
+    def _build_request(self, http: httpx.Client | httpx.AsyncClient, options: RequestOptions) -> httpx.Request:
+        headers = {**self.default_headers, **options.headers}
+        if options.idempotency_key:
+            headers["Idempotency-Key"] = options.idempotency_key
+        return http.build_request(
+            options.method,
+            self.base_url.join(options.path.lstrip("/")),
+            params=drop_none(options.params) if options.params else None,
+            json=options.json,
+            data=options.data,
+            files=options.files,
+            headers=headers,
+            timeout=options.timeout if options.timeout and self.timeout is DEFAULT_TIMEOUT else self.timeout,
+        )
+
+    def _should_retry(self, response: httpx.Response) -> bool:
+        return response.status_code in RETRYABLE_STATUSES
+
+    def _retry_delay(self, attempt: int, response: httpx.Response | None) -> float:
+        if response is not None:
+            retry_after = parse_retry_after(response)
+            if retry_after is not None and retry_after <= MAX_RETRY_AFTER:
+                return retry_after
+        delay = min(INITIAL_RETRY_DELAY * 2.0**attempt, MAX_RETRY_DELAY)
+        return delay * (1 - 0.25 * random.random())
+
+    @staticmethod
+    def _rewindable(options: RequestOptions) -> bool:
+        if not options.files:
+            return True
+        for _, (_, content, _) in options.files:
+            if not isinstance(content, bytes) and not (hasattr(content, "seek") and _seekable(content)):
+                return False
+        return True
+
+    @staticmethod
+    def _rewind(options: RequestOptions) -> None:
+        for _, (_, content, _) in options.files or []:
+            if not isinstance(content, bytes):
+                content.seek(0)
+
+
+def _seekable(content: IO[bytes]) -> bool:
+    try:
+        return bool(content.seekable())
+    except (AttributeError, OSError, ValueError):
+        return False
+
+
+def parse(cast_to: type[ModelT], response: httpx.Response) -> ModelT:
+    return cast_to.model_validate(response.json())

nvisionx/_client.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+
+from nvisionx._base_client import (
+    DEFAULT_MAX_RETRIES,
+    BaseClient,
+    ModelT,
+    RequestOptions,
+    parse,
+)
+from nvisionx._errors import APIConnectionError, APITimeoutError, error_from_response
+from nvisionx.resources.agents import Agents, AsyncAgents
+from nvisionx.resources.billing import AsyncBilling, Billing
+from nvisionx.resources.budgets import AsyncBudgets, Budgets
+from nvisionx.resources.chat import AsyncChat, Chat
+from nvisionx.resources.documents import AsyncDocuments, Documents
+from nvisionx.resources.jobs import AsyncJobs, Jobs
+from nvisionx.resources.mcp import AsyncMcp, Mcp
+from nvisionx.resources.search import AsyncSearch, Search
+from nvisionx.resources.sources import AsyncSources, Sources
+
+SelfT = TypeVar("SelfT", bound=BaseClient)
+
+
+def _with_options(
+    client: SelfT,
+    api_key: str | None,
+    base_url: str | httpx.URL | None,
+    timeout: float | httpx.Timeout | None,
+    max_retries: int | None,
+    default_headers: Mapping[str, str] | None,
+) -> SelfT:
+    clone = copy.copy(client)
+    if api_key is not None:
+        clone.api_key = api_key
+    if base_url is not None:
+        clone.base_url = httpx.URL(str(base_url).rstrip("/") + "/")
+    if timeout is not None:
+        clone.timeout = timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout)
+    if max_retries is not None:
+        clone.max_retries = max_retries
+    if default_headers is not None:
+        clone._default_headers = {**client._default_headers, **default_headers}
+    clone._owns_http = False
+    clone._bind_resources()
+    return clone
+
+
+class Nx(BaseClient):
+    documents: Documents
+    jobs: Jobs
+    search: Search
+    sources: Sources
+    mcp: Mcp
+    agents: Agents
+    chat: Chat
+    billing: Billing
+    budgets: Budgets
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client or httpx.Client(follow_redirects=True)
+        self._owns_http = http_client is None
+        self._bind_resources()
+
+    def _bind_resources(self) -> None:
+        self.documents = Documents(self)
+        self.jobs = Jobs(self)
+        self.search = Search(self)
+        self.sources = Sources(self)
+        self.mcp = Mcp(self)
+        self.agents = Agents(self)
+        self.chat = Chat(self)
+        self.billing = Billing(self)
+        self.budgets = Budgets(self)
+
+    def with_options(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> Nx:
+        return _with_options(self, api_key, base_url, timeout, max_retries, default_headers)
+
+    def send(self, options: RequestOptions, *, stream: bool = False) -> httpx.Response:
+        options = self._prepare(options)
+        rewindable = self._rewindable(options)
+        attempt = 0
+        while True:
+            request = self._build_request(self._http, options)
+            retry = attempt < self.max_retries and rewindable
+            response: httpx.Response | None = None
+            try:
+                response = self._http.send(request, stream=stream)
+            except httpx.TimeoutException as exc:
+                if not retry:
+                    raise APITimeoutError(request=request) from exc
+            except httpx.TransportError as exc:
+                if not retry:
+                    raise APIConnectionError(str(exc) or "Connection error.", request=request) from exc
+            if response is not None:
+                if response.is_success:
+                    return response
+                if not (retry and self._should_retry(response)):
+                    if stream:
+                        response.read()
+                        response.close()
+                    raise error_from_response(response)
+                response.close()
+
+            time.sleep(self._retry_delay(attempt, response))
+            self._rewind(options)
+            attempt += 1
+
+    def request(self, options: RequestOptions, cast_to: type[ModelT]) -> ModelT:
+        return parse(cast_to, self.send(options))
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Nx:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class AsyncNx(BaseClient):
+    documents: AsyncDocuments
+    jobs: AsyncJobs
+    search: AsyncSearch
+    sources: AsyncSources
+    mcp: AsyncMcp
+    agents: AsyncAgents
+    chat: AsyncChat
+    billing: AsyncBilling
+    budgets: AsyncBudgets
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._http = http_client or httpx.AsyncClient(follow_redirects=True)
+        self._owns_http = http_client is None
+        self._bind_resources()
+
+    def _bind_resources(self) -> None:
+        self.documents = AsyncDocuments(self)
+        self.jobs = AsyncJobs(self)
+        self.search = AsyncSearch(self)
+        self.sources = AsyncSources(self)
+        self.mcp = AsyncMcp(self)
+        self.agents = AsyncAgents(self)
+        self.chat = AsyncChat(self)
+        self.billing = AsyncBilling(self)
+        self.budgets = AsyncBudgets(self)
+
+    def with_options(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | httpx.URL | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> AsyncNx:
+        return _with_options(self, api_key, base_url, timeout, max_retries, default_headers)
+
+    async def send(self, options: RequestOptions, *, stream: bool = False) -> httpx.Response:
+        options = self._prepare(options)
+        rewindable = self._rewindable(options)
+        attempt = 0
+        while True:
+            request = self._build_request(self._http, options)
+            retry = attempt < self.max_retries and rewindable
+            response: httpx.Response | None = None
+            try:
+                response = await self._http.send(request, stream=stream)
+            except httpx.TimeoutException as exc:
+                if not retry:
+                    raise APITimeoutError(request=request) from exc
+            except httpx.TransportError as exc:
+                if not retry:
+                    raise APIConnectionError(str(exc) or "Connection error.", request=request) from exc
+            if response is not None:
+                if response.is_success:
+                    return response
+                if not (retry and self._should_retry(response)):
+                    if stream:
+                        await response.aread()
+                        await response.aclose()
+                    raise error_from_response(response)
+                await response.aclose()
+
+            await asyncio.sleep(self._retry_delay(attempt, response))
+            self._rewind(options)
+            attempt += 1
+
+    async def request(self, options: RequestOptions, cast_to: type[ModelT]) -> ModelT:
+        return parse(cast_to, await self.send(options))
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncNx:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()

nvisionx/_errors.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+from pydantic import ValidationError
+
+if TYPE_CHECKING:
+    from nvisionx._models import ErrorDetail
+
+
+class NxError(Exception):
+    pass
+
+
+class APIConnectionError(NxError):
+    def __init__(self, message: str = "Connection error.", *, request: httpx.Request) -> None:
+        super().__init__(message)
+        self.request = request
+
+
+class APITimeoutError(APIConnectionError):
+    def __init__(self, *, request: httpx.Request) -> None:
+        super().__init__("Request timed out.", request=request)
+
+
+class JobTimeoutError(NxError):
+    def __init__(self, job_id: str, timeout: float) -> None:
+        super().__init__(f"Job {job_id} did not finish within {timeout:g}s.")
+        self.job_id = job_id
+        self.timeout = timeout
+
+
+class StreamError(NxError):
+    pass
+
+
+class APIStatusError(NxError):
+    status_code: int
+
+    def __init__(self, message: str, *, response: httpx.Response, detail: ErrorDetail | None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response = response
+        self.status_code = response.status_code
+        self.detail = detail
+
+    @property
+    def type(self) -> str | None:
+        return self.detail.type if self.detail else None
+
+    def __str__(self) -> str:
+        kind = f" {self.type}" if self.type else ""
+        return f"{self.status_code}{kind}: {self.message}"
+
+
+class BadRequestError(APIStatusError):
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    pass
+
+
+class PaymentRequiredError(APIStatusError):
+    pass
+
+
+class PermissionDeniedError(APIStatusError):
+    @property
+    def required_scope(self) -> str | None:
+        return self.detail.required_scope if self.detail else None
+
+
+class NotFoundError(APIStatusError):
+    pass
+
+
+class ConflictError(APIStatusError):
+    pass
+
+
+class UnprocessableEntityError(APIStatusError):
+    pass
+
+
+class RateLimitError(APIStatusError):
+    @property
+    def retry_after(self) -> float | None:
+        return parse_retry_after(self.response)
+
+
+class InternalServerError(APIStatusError):
+    pass
+
+
+_BY_STATUS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: BadRequestError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def parse_retry_after(response: httpx.Response) -> float | None:
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    try:
+        return max(float(value), 0.0)
+    except ValueError:
+        return None
+
+
+def error_from_response(response: httpx.Response) -> APIStatusError:
+    from nvisionx._models import Error
+
+    detail: ErrorDetail | None = None
+    message = response.reason_phrase or f"HTTP {response.status_code}"
+    try:
+        detail = Error.model_validate(response.json()).error
+        message = detail.message
+    except (ValueError, ValidationError):
+        text = response.text.strip()
+        if text:
+            message = text[:500]
+
+    cls = _BY_STATUS.get(response.status_code)
+    if cls is None:
+        cls = InternalServerError if response.status_code >= 500 else APIStatusError
+    return cls(message, response=response, detail=detail)

nvisionx/_files.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import mimetypes
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from typing import IO, Union, cast
+
+FileContent = Union[bytes, IO[bytes]]
+FileInput = Union[
+    str,
+    "os.PathLike[str]",
+    FileContent,
+    tuple[str, FileContent],
+    tuple[str, FileContent, str],
+]
+FilesInput = Union[FileInput, Sequence[FileInput]]
+
+HTTPXFile = tuple[str, tuple[str, FileContent, str]]
+
+
+def _content_type(name: str) -> str:
+    return mimetypes.guess_type(name)[0] or "application/octet-stream"
+
+
+def _one(file: FileInput, opened: list[IO[bytes]]) -> tuple[str, FileContent, str]:
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        handle = path.open("rb")
+        opened.append(handle)
+        return path.name, handle, _content_type(path.name)
+    if isinstance(file, tuple):
+        if len(file) == 2:
+            name, content = file
+            return name, content, _content_type(name)
+        return file
+    if isinstance(file, bytes):
+        return "upload", file, "application/octet-stream"
+    name = Path(str(getattr(file, "name", "upload"))).name
+    return name, file, _content_type(name)
+
+
+def to_httpx_files(files: FilesInput, opened: list[IO[bytes]]) -> list[HTTPXFile]:
+    items: Sequence[FileInput]
+    if isinstance(files, (str, bytes, os.PathLike, tuple)) or hasattr(files, "read"):
+        items = [cast(FileInput, files)]
+    else:
+        items = files
+    return [("file", _one(item, opened)) for item in items]