nestor-cloud 0.1.0__py3-none-any.whl

nestor/__about__.py

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

nestor/__init__.py

@@ -0,0 +1,140 @@
+"""Nestor Cloud Python SDK.
+
+    from nestor import Nestor
+
+    client = Nestor()  # NESTOR_TOKEN / NESTOR_ORGANIZATION / NESTOR_PROJECT or `nestor auth login`
+    endpoint = client.inference.endpoints.create(model="Qwen/Qwen2.5-0.5B-Instruct", wait=True)
+    print(client.inference.endpoints.chat(endpoint, "Hello").text)
+    run = client.run("build_model.py", wait=True)
+    training = client.training.run(".", command=["python", "train.py"], wait=True)
+    app = client.applications.create("my-product")
+
+``nestor.Client`` and ``nestor.TrainingRun`` are the Training v0.1 client,
+kept as a compatibility façade over the same transport; ``TrainingRunDocument``
+is the plain document type used by ``client.training``.
+"""
+
+from .__about__ import __version__
+from ._client import Nestor
+from .client import Client, TrainingRun  # Training v0.1 compatibility client
+from .data import DataItem
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    ConnectionError,
+    IntegrityError,
+    InternalError,
+    InvalidRequestError,
+    NestorError,
+    NotFoundError,
+    OperationFailedError,
+    PermissionDeniedError,
+    PreconditionFailedError,
+    ProtocolError,
+    QuotaExceededError,
+    ResourceExhaustedError,
+    ServiceUnavailableError,
+    StreamError,
+    TimeoutError,
+    WorkloadStateError,
+)
+from .pagination import Page
+from .runs import Run
+from .types import (
+    Application,
+    ApplicationActivityEvent,
+    ApplicationOverview,
+    ApplicationTrainingRun,
+    ApplicationWorkloadSummary,
+    AuditEvent,
+    ChatChunk,
+    ChatCompletion,
+    ChatStream,
+    DataFile,
+    Endpoint,
+    EndpointEvent,
+    EndpointMetrics,
+    EndpointRevision,
+    EndpointUsage,
+    InvocationKey,
+    InvocationLog,
+    Model,
+    Operation,
+    Organization,
+    Project,
+    Quota,
+    ReplicaStatus,
+    RunEvent,
+    RunFile,
+    RunLog,
+    Secret,
+    TrainingEvent,
+    TrainingFile,
+    TrainingLog,
+    TrainingRun as TrainingRunDocument,
+    TrainingSourceSnapshot,
+)
+
+__all__ = [
+    "APIError",
+    "Application",
+    "ApplicationActivityEvent",
+    "ApplicationOverview",
+    "ApplicationTrainingRun",
+    "ApplicationWorkloadSummary",
+    "AuditEvent",
+    "AuthenticationError",
+    "ChatChunk",
+    "ChatCompletion",
+    "ChatStream",
+    "Client",
+    "ConfigurationError",
+    "ConflictError",
+    "ConnectionError",
+    "DataFile",
+    "DataItem",
+    "Endpoint",
+    "EndpointEvent",
+    "EndpointMetrics",
+    "EndpointRevision",
+    "EndpointUsage",
+    "IntegrityError",
+    "InternalError",
+    "InvalidRequestError",
+    "InvocationKey",
+    "InvocationLog",
+    "Model",
+    "Nestor",
+    "NestorError",
+    "NotFoundError",
+    "Operation",
+    "OperationFailedError",
+    "Organization",
+    "Page",
+    "PermissionDeniedError",
+    "PreconditionFailedError",
+    "Project",
+    "ProtocolError",
+    "Quota",
+    "QuotaExceededError",
+    "ReplicaStatus",
+    "ResourceExhaustedError",
+    "Run",
+    "RunEvent",
+    "RunFile",
+    "RunLog",
+    "Secret",
+    "ServiceUnavailableError",
+    "StreamError",
+    "TimeoutError",
+    "TrainingEvent",
+    "TrainingFile",
+    "TrainingLog",
+    "TrainingRun",
+    "TrainingRunDocument",
+    "TrainingSourceSnapshot",
+    "WorkloadStateError",
+    "__version__",
+]

nestor/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m nestor`` runs the CLI."""
+
+from .cli import run
+
+run()

nestor/_client.py

@@ -0,0 +1,397 @@
+"""The ``Nestor`` client: one object, one credential, one project scope.
+
+    from nestor import Nestor
+    client = Nestor()                       # reads NESTOR_* or `nestor auth login`
+    op = client.inference.endpoints.create(model="Qwen/Qwen2.5-0.5B-Instruct")
+    endpoint = client.inference.endpoints.wait(op)
+
+The client is synchronous. Every method performs exactly the HTTP calls it
+documents; there is no background thread, cache or connection pool to reason
+about. An asynchronous client is not provided in this version.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import uuid
+from typing import TYPE_CHECKING, Any, BinaryIO, Callable, Iterator, Mapping, TypeVar
+from urllib.parse import quote, urlsplit
+
+from . import __about__
+from ._http import Response, Transport, UrllibTransport
+from .config import ENV_ALLOW_INSECURE_HTTP, Settings
+from .errors import (
+    ConfigurationError,
+    ConnectionError as NestorConnectionError,
+    ProtocolError,
+    StreamError,
+    error_from_response,
+)
+from .pagination import Page, extract_items
+
+if TYPE_CHECKING:
+    from .runs import Run
+
+T = TypeVar("T")
+
+RETRYABLE_STATUSES = (502, 503, 504)
+MUTATING_METHODS = ("POST", "PATCH", "PUT", "DELETE")
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+
+
+def check_id(value: Any, what: str = "id") -> str:
+    """Validate an opaque resource ID before it is placed in a URL path.
+
+    IDs are opaque strings; the SDK only refuses values that could change the
+    route (separators, empty strings, non-strings).
+    """
+    if not isinstance(value, str) or not _ID.match(value):
+        raise ValueError(f"{what} must be an opaque Nestor ID, got {value!r}")
+    return value
+
+
+def validate_api_url(url: str, *, allow_insecure_http: bool = False) -> str:
+    """Accept ``https://host[:port]`` or ``http://`` to a loopback host only."""
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise ConfigurationError(f"api_url must be an http(s) origin, got {url!r}")
+    if parts.username or parts.password or parts.query or parts.fragment:
+        raise ConfigurationError("api_url must not carry credentials, a query string or a fragment")
+    host = parts.hostname.lower()
+    loopback = host in LOOPBACK_HOSTS or host.endswith(".localhost")
+    if parts.scheme == "http" and not loopback and not allow_insecure_http:
+        raise ConfigurationError(
+            f"refusing to send a bearer token over plain HTTP to {host}",
+            hint=f"use https://, or set {ENV_ALLOW_INSECURE_HTTP}=1 / allow_insecure_http=True for a trusted private network",
+        )
+    return url.rstrip("/")
+
+
+class Nestor:
+    """Entry point for the Nestor API.
+
+    Args:
+        api_url: API origin, for example ``https://api.nestor.example``.
+            Plain ``http://`` is accepted only for loopback hosts.
+        token: Bearer token (a development token, a production access
+            token, or an invocation key for chat-only clients).
+        api_key: Project machine API key for unattended backends and CI
+            (console Access → Service accounts). Mutually exclusive with ``token``; also
+            read from ``NESTOR_API_KEY``, which takes precedence over
+            ``NESTOR_TOKEN`` and never falls back to it.
+        organization: Organization ID used for every project-scoped call.
+        project: Project ID used for every project-scoped call.
+        timeout: Socket timeout in seconds per request (connect and each read).
+        max_retries: Extra attempts for connection failures and 502/503/504.
+            Reads are always retried. Mutations are retried only when they
+            carry an ``Idempotency-Key`` (the same key on every attempt, so a
+            retry can never create a second resource); a request without a
+            key, such as a chat completion, is sent exactly once.
+        transport: Replacement HTTP transport (tests).
+        use_profile: Read the ``nestor auth login`` profile as a fallback.
+        allow_insecure_http: Permit ``http://`` to non-loopback hosts.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_url: str | None = None,
+        token: str | None = None,
+        organization: str | None = None,
+        project: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Transport | None = None,
+        use_profile: bool = True,
+        allow_insecure_http: bool | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        if token is not None and api_key is not None:
+            raise ConfigurationError("choose either token or api_key, not both")
+        self.settings = Settings.resolve(
+            api_url=api_url, token=token, organization=organization, project=project, use_profile=use_profile, api_key=api_key
+        )
+        if allow_insecure_http is None:
+            allow_insecure_http = os.environ.get(ENV_ALLOW_INSECURE_HTTP, "") in ("1", "true", "yes")
+        self.settings.api_url = validate_api_url(self.settings.api_url, allow_insecure_http=allow_insecure_http)
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.transport: Transport = transport or UrllibTransport(f"nestor-python/{__about__.__version__}")
+        self.sleep: Callable[[float], None] = time.sleep  # patched in tests
+        self._bind_namespaces()
+
+    def _bind_namespaces(self) -> None:
+        from .applications import Applications
+        from .data import Data
+        from .inference import Inference
+        from .management import Organizations, Projects
+        from .operations import Operations
+        from .quotas import Quotas
+        from .runs import Runs
+        from .secrets import Secrets
+        from .training import Training
+
+        self.organizations = Organizations(self)
+        self.projects = Projects(self)
+        self.operations = Operations(self)
+        self.inference = Inference(self)
+        self.training = Training(self)
+        self.runs = Runs(self)
+        self.applications = Applications(self)
+        self.secrets = Secrets(self)
+        self.quotas = Quotas(self)
+        self.data = Data(self)
+
+    def __repr__(self) -> str:
+        return f"Nestor(api_url={self.settings.api_url!r}, organization={self.settings.organization!r}, project={self.settings.project!r})"
+
+    def run(self, source: Any = ".", **arguments: Any) -> "Run":
+        """Run a finite program and return its Run: ``client.runs.run`` (see ``nestor.runs``)."""
+        return self.runs.run(source, **arguments)
+
+    # -- scope ----------------------------------------------------------------
+    @property
+    def api_url(self) -> str:
+        return self.settings.api_url
+
+    @property
+    def organization(self) -> str:
+        return self.settings.organization
+
+    @property
+    def project(self) -> str:
+        return self.settings.project
+
+    def with_scope(self, organization: str | None = None, project: str | None = None) -> "Nestor":
+        """A copy of this client bound to another organization and/or project."""
+        clone = Nestor.__new__(Nestor)
+        clone.__dict__.update(self.__dict__)
+        clone.settings = Settings(
+            api_url=self.settings.api_url,
+            token=self.settings.token,
+            organization=check_id(organization, "organization") if organization else self.settings.organization,
+            project=check_id(project, "project") if project else self.settings.project,
+            sources=dict(self.settings.sources),
+        )
+        clone._bind_namespaces()
+        return clone
+
+    def organization_path(self) -> str:
+        if not self.settings.organization:
+            raise ConfigurationError(
+                "no organization selected",
+                hint="pass organization=… or set NESTOR_ORGANIZATION (or run `nestor projects use`)",
+            )
+        return f"/v1/organizations/{check_id(self.settings.organization, 'organization')}"
+
+    def project_path(self) -> str:
+        organization = self.organization_path()
+        if not self.settings.project:
+            raise ConfigurationError(
+                "no project selected",
+                hint="pass project=… or set NESTOR_PROJECT (or run `nestor projects use`)",
+            )
+        return f"{organization}/projects/{check_id(self.settings.project, 'project')}"
+
+    # -- transport ------------------------------------------------------------
+    @staticmethod
+    def new_idempotency_key() -> str:
+        return uuid.uuid4().hex
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        body: "bytes | BinaryIO | None" = None,
+        content_type: str | None = None,
+        content_length: int | None = None,
+        params: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        auto_idempotency: bool = True,
+        etag: str | None = None,
+        token: str | None = None,
+        stream: bool = False,
+        expect: tuple[int, ...] = (200, 201, 202),
+        timeout: float | None = None,
+    ) -> Response:
+        """Send one request and return the response or raise a typed error.
+
+        Mutations always carry an ``Idempotency-Key``; one is generated when
+        the caller does not supply it, unless ``auto_idempotency`` is False
+        (chat completions, where the header is optional). A generated key is
+        fixed for the life of this call, so every retry replays the same
+        logical request. A non-streamed success must be JSON; anything else
+        raises ``ProtocolError`` rather than being returned as a result.
+        """
+        bearer = token or self.settings.token
+        if not bearer:
+            raise ConfigurationError(
+                "no credential configured",
+                hint="run `nestor auth login`, set NESTOR_TOKEN or NESTOR_API_KEY, or pass token=…/api_key=…",
+            )
+        headers = {"Authorization": f"Bearer {bearer}", "Accept": "application/json"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        elif auto_idempotency and method in MUTATING_METHODS:
+            headers["Idempotency-Key"] = self.new_idempotency_key()
+        if json_body is not None:
+            body = json.dumps(json_body, separators=(",", ":")).encode()
+            headers["Content-Type"] = "application/json"
+        elif body is not None:
+            headers["Content-Type"] = content_type or "application/octet-stream"
+            if not isinstance(body, (bytes, bytearray)):
+                # A streamed file body: its length is declared so nothing is
+                # buffered, and it is rewound before any retry.
+                if content_length is None:
+                    raise ValueError("content_length is required for a streamed body")
+                headers["Content-Length"] = str(content_length)
+        elif method in ("POST", "PATCH", "PUT"):
+            body = b"{}"
+            headers["Content-Type"] = "application/json"
+        if etag is not None:
+            headers["If-Match"] = _quote_etag(etag)
+        url = self.settings.api_url + path
+        if params:
+            query = "&".join(f"{k}={_encode(v)}" for k, v in params.items() if v not in (None, ""))
+            if query:
+                url += ("&" if "?" in url else "?") + query
+        # A request may be replayed only when the server can recognise it as
+        # the same request: reads, and mutations that carry a key.
+        replayable = method in ("GET", "HEAD") or "Idempotency-Key" in headers
+        attempt = 0
+        while True:
+            if body is not None and not isinstance(body, (bytes, bytearray)) and attempt > 0:
+                body.seek(0)
+            try:
+                response = self.transport.send(method, url, headers, body, timeout or self.timeout, stream=stream)
+            except NestorConnectionError:
+                if not replayable or attempt >= self.max_retries:
+                    raise
+                attempt += 1
+                self.sleep(min(0.5 * 2**attempt, 4.0))
+                continue
+            if response.status in RETRYABLE_STATUSES and replayable and attempt < self.max_retries:
+                response.close()
+                attempt += 1
+                self.sleep(min(0.5 * 2**attempt, 4.0))
+                continue
+            break
+        if response.status not in expect:
+            try:
+                payload = response.json()
+            except ProtocolError:
+                payload = None
+            raise error_from_response(
+                status=response.status, body=payload, method=method, path=path, request_id=response.request_id
+            )
+        return response
+
+    def get_json(self, path: str, **kwargs: Any) -> Any:
+        payload = self.request("GET", path, expect=(200,), **kwargs).json()
+        if not isinstance(payload, dict):
+            raise ProtocolError(f"expected a JSON object from GET {path}")
+        return payload
+
+    def paginate(
+        self,
+        path: str,
+        convert: Callable[[Mapping[str, Any]], T],
+        *,
+        key: str | None = None,
+        page_size: int | None = None,
+        page_token: str | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Page[T]:
+        """Fetch one page. The returned ``Page`` fetches the rest lazily.
+
+        Tokens are opaque and passed back verbatim. A server that returns the
+        token it was just given would loop forever, so that is refused.
+        """
+        query: dict[str, Any] = dict(params or {})
+        if page_size is not None:
+            if not 1 <= page_size <= 100:
+                raise ValueError("page_size must be between 1 and 100")
+            query["page_size"] = page_size
+        if page_token:
+            query["page_token"] = page_token
+        body = self.get_json(path, params=query)
+        items = [convert(item) for item in extract_items(body, key)]
+        next_token = str(body.get("next_page_token") or "")
+        if next_token and next_token == page_token:
+            raise ProtocolError(f"GET {path} returned the page token it was given; refusing to loop")
+
+        def fetch_next(tok: str) -> Page[T]:
+            return self.paginate(path, convert, key=key, page_size=page_size, page_token=tok, params=params)
+
+        return Page(items, next_token, fetch_next)
+
+    def iter_sse(self, response: Response) -> "SSEEvents":
+        """Parsed ``data:`` JSON objects from a server-sent event stream."""
+        return SSEEvents(response)
+
+
+class SSEEvents:
+    """Iterator over the JSON payloads of an event stream.
+
+    ``done`` becomes True when the server sent ``data: [DONE]``. A stream that
+    ends without it is incomplete, and an ``event: error`` event raises
+    ``StreamError`` carrying the API's error code.
+    """
+
+    def __init__(self, response: Response) -> None:
+        self.response = response
+        self.request_id = response.request_id
+        self.done = False
+        self.delivered = 0
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        event_name = ""
+        for line in self.response.iter_lines():
+            if not line:
+                event_name = ""
+                continue
+            if line.startswith("event:"):
+                event_name = line[6:].strip()
+                continue
+            if not line.startswith("data:"):
+                continue
+            data = line[5:].strip()
+            if data == "[DONE]":
+                self.done = True
+                self.response.close()
+                return
+            try:
+                payload = json.loads(data)
+            except ValueError:
+                raise StreamError("stream carried a malformed event", partial=self.delivered > 0, request_id=self.request_id) from None
+            if event_name == "error" or (isinstance(payload, dict) and "error" in payload and "choices" not in payload):
+                error = payload.get("error") if isinstance(payload, dict) else None
+                code = str((error or {}).get("code") or "UNAVAILABLE")
+                message = str((error or {}).get("message") or "stream failed")
+                failure = StreamError(f"stream failed: {code}: {message}", partial=self.delivered > 0, request_id=self.request_id)
+                failure.code = code
+                raise failure
+            self.delivered += 1
+            yield payload
+        if not self.done:
+            raise StreamError("stream ended before the server marked it complete", partial=self.delivered > 0, request_id=self.request_id)
+
+
+def _quote_etag(etag: str) -> str:
+    etag = etag.strip()
+    if etag.startswith('"') and etag.endswith('"'):
+        return etag
+    return f'"{etag}"'
+
+
+def _encode(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
+__all__ = ["Nestor", "SSEEvents", "check_id", "validate_api_url"]