kainguru-sdk 0.1.4.dev0__py3-none-any.whl

kainguru/__init__.py

@@ -0,0 +1,48 @@
+"""Kainguru Python SDK — run models and fine-tune them on the Kainguru ML platform."""
+
+from __future__ import annotations
+
+from ._config import KainguruConfig
+from ._errors import (
+    KainguruAPIError,
+    KainguruAuthError,
+    KainguruConfigError,
+    KainguruConnectionError,
+    KainguruError,
+    KainguruNotFoundError,
+    KainguruRateLimitError,
+    KainguruTimeoutError,
+)
+from .async_client import AsyncKainguruClient
+from .client import KainguruClient
+from .models import (
+    ApplicationDto,
+    ExecutionResultDto,
+    ModelExecResponseDto,
+    ModelFineTunedDetailDto,
+    ModelStatus,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "KainguruClient",
+    "AsyncKainguruClient",
+    "KainguruConfig",
+    # Errors
+    "KainguruError",
+    "KainguruConfigError",
+    "KainguruAPIError",
+    "KainguruAuthError",
+    "KainguruNotFoundError",
+    "KainguruRateLimitError",
+    "KainguruTimeoutError",
+    "KainguruConnectionError",
+    # Models
+    "ModelStatus",
+    "ModelExecResponseDto",
+    "ModelFineTunedDetailDto",
+    "ApplicationDto",
+    "ExecutionResultDto",
+]

kainguru/_config.py

@@ -0,0 +1,63 @@
+"""Client configuration resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._errors import KainguruConfigError
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BASE_DELAY = 1.0
+
+
+@dataclass(frozen=True)
+class KainguruConfig:
+    api_key: str
+    base_url: str
+    timeout: float
+    max_retries: int
+    retry_base_delay: float
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+    ) -> KainguruConfig:
+        """Resolve configuration, failing fast when the caller omits a required field.
+
+        Both ``api_key`` and ``base_url`` are required and must be passed
+        explicitly. (A per-request ``api_key=`` kwarg may still override per call.)
+        """
+        if not api_key or not api_key.strip():
+            raise KainguruConfigError(
+                "Kainguru API key is required. Pass api_key=... to the client."
+            )
+        if not base_url or not base_url.strip():
+            raise KainguruConfigError(
+                "Kainguru base URL is required. Pass base_url=... (the full host "
+                "including the /api context path)."
+            )
+        if timeout <= 0:
+            raise KainguruConfigError("timeout must be > 0")
+        if max_retries < 0:
+            raise KainguruConfigError("max_retries must be >= 0")
+
+        return cls(
+            api_key=api_key.strip(),
+            # httpx resolves request paths against base_url using RFC 3986, so the
+            # base URL MUST end with "/" or the "/api" context path is dropped.
+            base_url=_ensure_trailing_slash(base_url.strip()),
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+        )
+
+
+def _ensure_trailing_slash(url: str) -> str:
+    return url if url.endswith("/") else url + "/"

kainguru/_errors.py

@@ -0,0 +1,81 @@
+"""Exception hierarchy for the Kainguru SDK.
+
+Every error extends :class:`KainguruError`. HTTP-derived errors expose the status
+code, raw body, optional API code, and the underlying ``httpx.Response`` when
+available. Specific subclasses for common statuses let callers narrow their
+``except`` clauses.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class KainguruError(Exception):
+    """Base class for all SDK errors."""
+
+
+class KainguruConfigError(KainguruError):
+    """Missing or invalid configuration (e.g. no API key, bad base URL)."""
+
+
+class KainguruAPIError(KainguruError):
+    """Non-2xx HTTP response, or a 2xx body with ``success == False``."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: str = "",
+        api_code: int | None = None,
+        response: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.api_code = api_code
+        self.response = response
+
+
+class KainguruAuthError(KainguruAPIError):
+    """401 / 403 — authentication or authorization failure."""
+
+
+class KainguruNotFoundError(KainguruAPIError):
+    """404 — resource not found."""
+
+
+class KainguruRateLimitError(KainguruAPIError):
+    """429 — rate limited. ``retry_after`` (seconds) is set when the header is present."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: str = "",
+        api_code: int | None = None,
+        response: Any | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            body=body,
+            api_code=api_code,
+            response=response,
+        )
+        self.retry_after = retry_after
+
+
+class KainguruTimeoutError(KainguruError):
+    """``await_completion`` exceeded its timeout. Carries the last DTO observed."""
+
+    def __init__(self, message: str, *, last_dto: Any | None = None) -> None:
+        super().__init__(message)
+        self.last_dto = last_dto
+
+
+class KainguruConnectionError(KainguruError):
+    """Network / transport failure. The underlying error is chained via ``from``."""

kainguru/_polling.py

@@ -0,0 +1,98 @@
+"""Polling engines for ``await_completion`` — sync and async."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from ._errors import KainguruTimeoutError
+
+T = TypeVar("T")
+
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_TIMEOUT = 300.0
+DEFAULT_BACKOFF = 1.0
+DEFAULT_MAX_INTERVAL = 30.0
+
+
+def _validate(poll_interval: float, timeout: float, backoff: float, max_interval: float) -> None:
+    if poll_interval <= 0:
+        raise ValueError("poll_interval must be > 0")
+    if timeout <= 0:
+        raise ValueError("timeout must be > 0")
+    if backoff < 1.0:
+        raise ValueError("backoff must be >= 1.0")
+    if max_interval <= 0:
+        raise ValueError("max_interval must be > 0")
+
+
+def await_completion(
+    get_fn: Callable[[], T],
+    *,
+    is_terminal: Callable[[T], bool],
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+    timeout: float = DEFAULT_TIMEOUT,
+    backoff: float = DEFAULT_BACKOFF,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    _clock: Callable[[], float] = time.monotonic,
+    _sleep: Callable[[float], None] = time.sleep,
+) -> T:
+    """Poll ``get_fn`` until ``is_terminal`` is true, then return that value.
+
+    Raises :class:`KainguruTimeoutError` (carrying the last DTO) on timeout. A
+    ``FAILED`` status is terminal and therefore *returns* — inspect the result.
+    """
+    _validate(poll_interval, timeout, backoff, max_interval)
+    start = _clock()
+    deadline = start + timeout
+    interval = poll_interval
+    last: T | None = None
+
+    while True:
+        last = get_fn()
+        if is_terminal(last):
+            return last
+        now = _clock()
+        if now >= deadline:
+            raise KainguruTimeoutError(
+                f"Polling timed out after {timeout}s", last_dto=last
+            )
+        sleep_for = min(interval, max_interval, deadline - now)
+        if sleep_for > 0:
+            _sleep(sleep_for)
+        interval = min(interval * backoff, max_interval)
+
+
+async def await_completion_async(
+    get_fn: Callable[[], Awaitable[T]],
+    *,
+    is_terminal: Callable[[T], bool],
+    poll_interval: float = DEFAULT_POLL_INTERVAL,
+    timeout: float = DEFAULT_TIMEOUT,
+    backoff: float = DEFAULT_BACKOFF,
+    max_interval: float = DEFAULT_MAX_INTERVAL,
+    _clock: Callable[[], float] = time.monotonic,
+    _sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> T:
+    """Async mirror of :func:`await_completion` using non-blocking sleeps."""
+    _validate(poll_interval, timeout, backoff, max_interval)
+    start = _clock()
+    deadline = start + timeout
+    interval = poll_interval
+    last: T | None = None
+
+    while True:
+        last = await get_fn()
+        if is_terminal(last):
+            return last
+        now = _clock()
+        if now >= deadline:
+            raise KainguruTimeoutError(
+                f"Polling timed out after {timeout}s", last_dto=last
+            )
+        sleep_for = min(interval, max_interval, deadline - now)
+        if sleep_for > 0:
+            await _sleep(sleep_for)
+        interval = min(interval * backoff, max_interval)

kainguru/_transport.py

@@ -0,0 +1,206 @@
+"""HTTP transport: auth header injection, retry, error mapping, envelope unwrap.
+
+Two thin wrappers — :class:`Transport` (sync) and :class:`AsyncTransport`
+(async) — share the retry/error helpers below so the two clients behave
+identically.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from ._config import KainguruConfig
+from ._errors import (
+    KainguruAPIError,
+    KainguruAuthError,
+    KainguruConnectionError,
+    KainguruNotFoundError,
+    KainguruRateLimitError,
+)
+
+API_KEY_HEADER = "X-API-Key"
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+def _headers(config: KainguruConfig, api_key: str | None) -> dict[str, str]:
+    headers = {"Accept": "application/json"}
+    key = api_key or config.api_key
+    if key:
+        headers[API_KEY_HEADER] = key
+    return headers
+
+
+def _is_retriable_status(status_code: int) -> bool:
+    return status_code == 429 or 500 <= status_code <= 599
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(int(raw.strip())))
+    except (ValueError, TypeError):
+        return None
+
+
+def _retry_delay(attempt: int, response: httpx.Response | None, base_delay: float) -> float:
+    if response is not None:
+        retry_after = _retry_after_seconds(response)
+        if retry_after is not None:
+            return retry_after
+    exp = base_delay * (2**attempt)
+    jitter = random.uniform(0, max(0.001, exp / 2))
+    return float(exp + jitter)
+
+
+def _map_http_error(response: httpx.Response) -> KainguruAPIError:
+    status = response.status_code
+    body = response.text
+    message = f"Kainguru API error: HTTP {status}"
+    if status in (401, 403):
+        return KainguruAuthError(message, status_code=status, body=body, response=response)
+    if status == 404:
+        return KainguruNotFoundError(message, status_code=status, body=body, response=response)
+    if status == 429:
+        return KainguruRateLimitError(
+            message,
+            status_code=status,
+            body=body,
+            response=response,
+            retry_after=_retry_after_seconds(response),
+        )
+    return KainguruAPIError(message, status_code=status, body=body, response=response)
+
+
+def unwrap(response: httpx.Response, model_cls: type[ModelT]) -> ModelT:
+    """Unwrap a ``CommonApiResponse`` envelope into ``model_cls``.
+
+    Raises :class:`KainguruAPIError` on non-2xx, a malformed body, or
+    ``success == False``.
+    """
+    if not response.is_success:
+        raise _map_http_error(response)
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise KainguruAPIError(
+            "Malformed JSON in Kainguru API response",
+            status_code=response.status_code,
+            body=response.text,
+            response=response,
+        ) from exc
+    if not isinstance(body, dict) or "success" not in body:
+        raise KainguruAPIError(
+            "Unexpected response body (missing CommonApiResponse envelope)",
+            status_code=response.status_code,
+            body=response.text,
+            response=response,
+        )
+    if not body.get("success"):
+        raise KainguruAPIError(
+            f"Kainguru API returned success=false (code={body.get('code')})",
+            status_code=response.status_code,
+            body=response.text,
+            api_code=body.get("code"),
+            response=response,
+        )
+    try:
+        return model_cls.model_validate(body.get("data"))
+    except ValidationError as exc:
+        raise KainguruAPIError(
+            f"Failed to parse Kainguru API response into {model_cls.__name__}",
+            status_code=response.status_code,
+            body=response.text,
+            response=response,
+        ) from exc
+
+
+class Transport:
+    """Synchronous transport wrapping an ``httpx.Client``."""
+
+    def __init__(self, client: httpx.Client, config: KainguruConfig) -> None:
+        self._client = client
+        self._config = config
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        api_key: str | None = None,
+    ) -> httpx.Response:
+        headers = _headers(self._config, api_key)
+        last_exc: Exception | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, url, params=params, json=json, headers=headers
+                )
+            except httpx.RequestError as exc:
+                last_exc = exc
+                if attempt >= self._config.max_retries:
+                    raise KainguruConnectionError(
+                        f"Network error while calling the Kainguru API: {exc}"
+                    ) from exc
+                time.sleep(_retry_delay(attempt, None, self._config.retry_base_delay))
+                continue
+            if _is_retriable_status(response.status_code) and attempt < self._config.max_retries:
+                time.sleep(_retry_delay(attempt, response, self._config.retry_base_delay))
+                continue
+            return response
+        # Unreachable, but keeps type checkers happy.
+        raise KainguruConnectionError("Retry loop exhausted") from last_exc
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    """Asynchronous transport wrapping an ``httpx.AsyncClient``."""
+
+    def __init__(self, client: httpx.AsyncClient, config: KainguruConfig) -> None:
+        self._client = client
+        self._config = config
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        api_key: str | None = None,
+    ) -> httpx.Response:
+        headers = _headers(self._config, api_key)
+        last_exc: Exception | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, url, params=params, json=json, headers=headers
+                )
+            except httpx.RequestError as exc:
+                last_exc = exc
+                if attempt >= self._config.max_retries:
+                    raise KainguruConnectionError(
+                        f"Network error while calling the Kainguru API: {exc}"
+                    ) from exc
+                await asyncio.sleep(_retry_delay(attempt, None, self._config.retry_base_delay))
+                continue
+            if _is_retriable_status(response.status_code) and attempt < self._config.max_retries:
+                await asyncio.sleep(_retry_delay(attempt, response, self._config.retry_base_delay))
+                continue
+            return response
+        raise KainguruConnectionError("Retry loop exhausted") from last_exc
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

kainguru/async_client.py

@@ -0,0 +1,74 @@
+"""Asynchronous client facade."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_BASE_DELAY,
+    DEFAULT_TIMEOUT,
+    KainguruConfig,
+)
+from ._transport import AsyncTransport
+from .resources import AsyncExecutionsResource, AsyncFineTuningResource
+
+
+class AsyncKainguruClient:
+    """Entry point for the Kainguru SDK (async).
+
+    Example::
+
+        async with AsyncKainguruClient(
+            api_key="kg_...", base_url="https://your-host/api"
+        ) as client:
+            submitted = await client.executions.execute(
+                "my-mlflow-id", {"prompt": "hello world"}, "json"
+            )
+            done = await client.executions.await_completion(submitted.id)
+            print(done.status)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._config = KainguruConfig.resolve(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+        )
+        client = http_client or httpx.AsyncClient(
+            base_url=self._config.base_url, timeout=self._config.timeout
+        )
+        self._transport = AsyncTransport(client, self._config)
+        self.executions = AsyncExecutionsResource(self._transport)
+        self.fine_tuning = AsyncFineTuningResource(self._transport)
+
+    @property
+    def config(self) -> KainguruConfig:
+        return self._config
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncKainguruClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

kainguru/client.py

@@ -0,0 +1,74 @@
+"""Synchronous client facade."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_BASE_DELAY,
+    DEFAULT_TIMEOUT,
+    KainguruConfig,
+)
+from ._transport import Transport
+from .resources import ExecutionsResource, FineTuningResource
+
+
+class KainguruClient:
+    """Entry point for the Kainguru SDK (sync).
+
+    Example::
+
+        with KainguruClient(
+            api_key="kg_...", base_url="https://your-host/api"
+        ) as client:
+            submitted = client.executions.execute(
+                "my-mlflow-id", {"prompt": "hello world"}, "json"
+            )
+            done = client.executions.await_completion(submitted.id)
+            print(done.status)  # ModelStatus.COMPLETED / FAILED
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = KainguruConfig.resolve(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+        )
+        client = http_client or httpx.Client(
+            base_url=self._config.base_url, timeout=self._config.timeout
+        )
+        self._transport = Transport(client, self._config)
+        self.executions = ExecutionsResource(self._transport)
+        self.fine_tuning = FineTuningResource(self._transport)
+
+    @property
+    def config(self) -> KainguruConfig:
+        return self._config
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> KainguruClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()