lighton-sdk 1.0.0__py3-none-any.whl

lighton/__init__.py

@@ -0,0 +1,48 @@
+from importlib.metadata import version
+
+from lighton._client import LightOn
+from lighton.apikey import ApiKey, ApiKeyScope
+from lighton.batch import BatchIngest, BatchIngestJob, BatchProgress, FailedIngest
+from lighton.content_type import Attribute, ContentType, Facet
+from lighton.enums import (
+    ExecMode,
+    FileStatus,
+    JobStatus,
+    RelevanceScoring,
+    Role,
+    SearchMode,
+)
+from lighton.file import File, wait_all
+from lighton.job import ExtractJob, ParseJob
+from lighton.tag import Tag
+from lighton.types import LightOnConfiguration
+from lighton.workspace import Workspace
+
+__version__ = version(
+    "lighton-sdk"
+)  # single source of truth: pyproject.toml (via installed metadata)
+__all__ = [
+    "ApiKey",
+    "ApiKeyScope",
+    "Attribute",
+    "BatchIngest",
+    "BatchIngestJob",
+    "BatchProgress",
+    "ContentType",
+    "ExecMode",
+    "ExtractJob",
+    "Facet",
+    "FailedIngest",
+    "File",
+    "FileStatus",
+    "JobStatus",
+    "LightOn",
+    "LightOnConfiguration",
+    "ParseJob",
+    "RelevanceScoring",
+    "Role",
+    "SearchMode",
+    "Tag",
+    "Workspace",
+    "wait_all",
+]

lighton/_active_record.py

@@ -0,0 +1,117 @@
+"""Shared active-record plumbing for the resource models.
+
+Read-side lifecycle (list/get/refresh/delete) and the client-binding internals
+(`_bind`/`_api`/`_absorb`) are identical across Workspace/ApiKey/File, so they live
+here. What genuinely diverges stays on the subclass: the field schema, `create()`
+(JSON vs multipart body), and `save()` (per-resource PATCH payload).
+
+Subclasses set two ClassVars: `_base` (URL path) and `_resource` (name used in error
+messages). `_absorb` overwrites only fields present in the response, so one-time or
+local-only fields (ApiKey.key, File.path) survive a later refresh().
+"""
+
+from __future__ import annotations
+
+# The list() classmethod shadows builtin list in annotations (class scope).
+from builtins import list as _list
+from typing import TYPE_CHECKING, ClassVar, Self
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+if TYPE_CHECKING:
+    from lighton._client import LightOn
+
+
+class _ActiveRecord(BaseModel):
+    # Responses carry extra fields the curated schema doesn't model; ignore them.
+    model_config = ConfigDict(extra="ignore")
+
+    _base: ClassVar[str]  # e.g. "/api/v3/workspaces"
+    _resource: ClassVar[str]  # e.g. "workspace", used in error messages
+
+    id: int | str | None = Field(
+        None, description="Server-assigned id; None until created/retrieved."
+    )
+
+    _client: LightOn | None = PrivateAttr(default=None)
+
+    # --- class-level (no instance yet) -------------------------------------
+    @classmethod
+    def list(cls, client: LightOn, **params: object) -> _list[Self]:
+        """List every resource, following pagination to the end.
+
+        Args:
+            client: The client used to make the request and bind to each result.
+            **params: Optional query filters (e.g. workspace_id) sent on the first page.
+
+        Returns:
+            All matching resources, each bound to `client`.
+        """
+        query: dict[str, object] | None = params or None
+        items: _list[Self] = []
+        path: str | None = cls._base
+        while path:  # follow pagination, no silent truncation
+            page = client._request("GET", path, params=query)
+            items.extend(cls._bind(client, row) for row in page["results"])
+            path = page.get("next")
+            query = None  # `next` already carries the query string
+        return items
+
+    @classmethod
+    def get(cls, client: LightOn, id: int | str) -> Self:
+        """Fetch a single resource by id.
+
+        Args:
+            client: The client used to make the request and bind to the result.
+            id: The resource id to retrieve.
+
+        Returns:
+            The resource, bound to `client`.
+        """
+        return cls._bind(client, client._request("GET", f"{cls._base}/{id}"))
+
+    # --- instance lifecycle ------------------------------------------------
+    def refresh(self) -> Self:
+        """Re-fetch this resource from the API (GET).
+
+        Returns:
+            `self`, updated with the latest field values.
+        """
+        return self._absorb(self._api("GET", f"{self._base}/{self.id}"))
+
+    def delete(self) -> None:
+        """Delete this resource and clear its local id."""
+        self._api("DELETE", f"{self._base}/{self.id}")
+        self.id = None
+
+    # --- internals ---------------------------------------------------------
+    def _bound_client(self) -> LightOn:
+        """Return the bound client, or raise if this instance isn't persisted yet.
+
+        Returns:
+            The client bound by create()/get()/list().
+
+        Raises:
+            ValueError: If the instance has no id or no bound client.
+        """
+        if self.id is None or self._client is None:
+            raise ValueError(f"{self._resource} must be created or retrieved first")
+        return self._client
+
+    def _api(self, method: str, path: str, **kwargs: object):
+        return self._bound_client()._request(method, path, **kwargs)
+
+    @classmethod
+    def _bind(cls, client: LightOn, data: dict) -> Self:
+        obj = cls.model_validate(data)
+        obj._client = client
+        return obj
+
+    def _absorb(self, data: dict | None) -> Self:
+        """Copy returned fields onto self, keeping _client and any local-only fields."""
+        if data:
+            fresh = self.model_validate(data)
+            for field in type(self).model_fields:
+                if field in data:  # only overwrite what the response returned
+                    setattr(self, field, getattr(fresh, field))
+        return self

lighton/_client.py

@@ -0,0 +1,138 @@
+"""Synchronous LightOn API client.
+
+The 4 primary verbs (ask, search, parse, extract) are mixed in from lighton/verbs/;
+this module holds only the transport core (auth, _request, lifecycle). CRUD-style
+groups (files, ingestion, keys) hang off the active-record resources instead.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from lighton import exceptions as exc
+from lighton.types import LightOnConfiguration
+from lighton.verbs import AskMixin, ExtractMixin, ParseMixin, SearchMixin
+
+
+class _RateGate:
+    """Thread-safe minimum-interval pacer to hold a per-minute request ceiling.
+
+    ponytail: even spacing, not a burst-allowing token bucket, simplest thing that
+    keeps concurrent threads under a per-minute cap. Swap for a token bucket if you
+    need to allow short bursts. Clock/sleep are injectable so tests need no wall time.
+    """
+
+    def __init__(
+        self,
+        per_minute: int,
+        *,
+        sleep: Callable[[float], None] = time.sleep,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._interval = 60.0 / per_minute
+        self._sleep = sleep
+        self._monotonic = monotonic
+        self._lock = threading.Lock()
+        self._next = 0.0
+
+    def acquire(self) -> None:
+        """Block just long enough that requests stay spaced by the interval."""
+        with self._lock:
+            now = self._monotonic()
+            wait = self._next - now
+            self._next = max(now, self._next) + self._interval
+        if wait > 0:
+            self._sleep(wait)
+
+
+class LightOn(AskMixin, SearchMixin, ParseMixin, ExtractMixin):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        config: LightOnConfiguration | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("LIGHTON_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "api_key is required (pass api_key= or set LIGHTON_API_KEY)"
+            )
+        config = config or LightOnConfiguration()
+        # httpx.HTTPTransport(retries=) retries connection errors only (exp. backoff).
+        # HTTP 429 cooldown/retry is handled separately in _request; 5xx isn't retried.
+        transport = config.transport or httpx.HTTPTransport(retries=config.retries)
+        self._http = httpx.Client(
+            base_url=config.base_url.rstrip("/"),
+            timeout=config.timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+            transport=transport,
+        )
+        self._gate = (
+            _RateGate(config.max_requests_per_minute)
+            if config.max_requests_per_minute
+            else None
+        )
+        self._rate_limit_retries = config.rate_limit_retries
+
+    # --- lifecycle ---------------------------------------------------------
+    def __enter__(self) -> "LightOn":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # --- transport ---------------------------------------------------------
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Send a request, raise on error, return parsed JSON (or None for empty 2xx).
+
+        Paces requests under the configured per-minute cap and, on HTTP 429, waits
+        the Retry-After cooldown (or exponential backoff) and retries up to
+        `rate_limit_retries` times. All callers route through here, so both the cap
+        and the cooldown apply to every endpoint uniformly.
+        """
+        for attempt in range(self._rate_limit_retries + 1):
+            if self._gate is not None:
+                self._gate.acquire()
+            try:
+                response = self._http.request(method, path, **kwargs)
+            except httpx.TransportError as e:
+                raise exc.LightOnConnectionError(str(e)) from e
+            if response.is_success:
+                if not response.content:
+                    return None
+                try:
+                    return response.json()
+                except ValueError as e:
+                    raise exc.MalformedResponseError(
+                        f"expected JSON but got: {response.text[:200]!r}"
+                    ) from e
+            error = exc.from_response(response)
+            if (
+                isinstance(error, exc.RateLimitError)
+                and attempt < self._rate_limit_retries
+            ):
+                time.sleep(_cooldown(error.retry_after, attempt))
+                continue
+            raise error
+        raise AssertionError("unreachable")  # loop either returns or raises
+
+
+def _cooldown(retry_after: float | None, attempt: int) -> float:
+    """Seconds to wait before a 429 retry: honor Retry-After, else backoff+jitter.
+
+    ponytail: exponential backoff capped at 60s with small jitter; good enough for a
+    rate-limit cooldown. Uses `random` for jitter, fine at SDK runtime.
+    """
+    if retry_after is not None:
+        return retry_after
+    return min(60.0, 2.0**attempt) + random.uniform(0.0, 0.5)

lighton/apikey.py

@@ -0,0 +1,94 @@
+"""API key schema + management (active-record, see `_ActiveRecord`).
+
+The plaintext secret (`key`) is returned only by create(), once. list()/get()/
+save()/refresh() never resend it, create() is your only chance to read it.
+"""
+
+from __future__ import annotations
+
+# The list() classmethod shadows builtin list in annotations (class scope).
+from builtins import list as _list
+from datetime import datetime
+from typing import TYPE_CHECKING, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from lighton._active_record import _ActiveRecord
+from lighton.enums import Role
+
+if TYPE_CHECKING:
+    from lighton._client import LightOn
+
+_BASE = "/api/v3/keys"
+
+
+class ApiKeyScope(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    workspace_id: int = Field(description="Workspace this scope grants access to.")
+    role: Role = Field(description="Access role granted on the workspace.")
+
+
+class ApiKey(_ActiveRecord):
+    _base: ClassVar[str] = _BASE
+    _resource: ClassVar[str] = "api key"
+
+    id: str | None = Field(
+        None, description="Server-assigned id; None until created/retrieved."
+    )
+    name: str = Field(description="API key display name.")
+    expires_at: datetime | None = Field(
+        None, description="Expiry timestamp; None for no expiry."
+    )
+    scopes: _list[ApiKeyScope] = Field(
+        default_factory=list,
+        description="Per-workspace access scopes; empty for an unscoped key.",
+    )
+    # Read-only, populated from responses.
+    prefix: str | None = Field(
+        None, description="Non-secret key prefix for identification (read-only)."
+    )
+    created_at: datetime | None = Field(
+        None, description="Creation timestamp (read-only)."
+    )
+    key: SecretStr | None = Field(
+        None,
+        description="Plaintext secret, returned ONLY by create(), once. Use .get_secret_value().",
+    )
+
+    # --- instance lifecycle ------------------------------------------------
+    def create(self, client: LightOn) -> ApiKey:
+        """Create this API key and bind the client for later lifecycle calls.
+
+        Args:
+            client: The client to create the key with and bind to `self`.
+
+        Returns:
+            `self`, updated with the id and the one-time plaintext `key`.
+        """
+        payload = {
+            "name": self.name,
+            "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+            # Providing scopes marks the key workspace-scoped; omit when empty.
+            "scopes": [s.model_dump() for s in self.scopes] or None,
+        }
+        data = client._request("POST", _BASE, json=payload)
+        self._client = client
+        return self._absorb(data)
+
+    def save(self) -> ApiKey:
+        """Persist local edits to name/scopes (PATCH).
+
+        Returns:
+            `self`, refreshed with the server's response (never re-includes `key`).
+        """
+        data = self._api(
+            "PATCH",
+            f"{_BASE}/{self.id}",
+            # `or None`: empty scopes means unscoped, matching create(), not [].
+            json={
+                "name": self.name,
+                "scopes": [s.model_dump() for s in self.scopes] or None,
+            },
+        )
+        return self._absorb(data)