kainguru-sdk 0.1.4.dev0__tar.gz

kainguru_sdk-0.1.4.dev0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenv
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db

kainguru_sdk-0.1.4.dev0/MAINTAINERS.md

@@ -0,0 +1,72 @@
+# Maintaining kainguru-sdk
+
+Internal notes for building, testing, and publishing the Python SDK.
+
+## Layout
+
+```
+kainguru-sdk-python/
+  pyproject.toml          # PEP 621 metadata, hatchling build backend
+  Makefile                # generate / lint / typecheck / test / build
+  src/kainguru/
+    __init__.py           # public exports
+    _config.py            # KainguruConfig: api key + base URL resolution
+    _environment.py       # Environment enum + base-URL map
+    _transport.py         # httpx wrappers, auth, retry, error mapping, unwrap
+    _errors.py            # exception hierarchy
+    _polling.py           # sync + async await_completion engines
+    models.py             # GENERATED (datamodel-code-generator), pydantic v2
+    client.py             # KainguruClient (sync)
+    async_client.py       # AsyncKainguruClient
+    resources/            # ExecutionsResource / FineTuningResource (+ async)
+    py.typed              # PEP 561 marker
+  tests/
+    resources/openapi.json  # pinned spec snapshot
+```
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+make install            # pip install -e ".[dev]"
+```
+
+## Local workflow
+
+```bash
+make generate           # regenerate src/kainguru/models.py from the pinned spec
+make lint               # ruff check
+make typecheck          # mypy (strict)
+make test               # pytest (sync + async via pytest-asyncio)
+make build              # wheel + sdist into dist/
+```
+
+## Model-drift check (CI)
+
+`src/kainguru/models.py` is committed. CI runs `make generate` and
+`git diff --exit-code src/kainguru/models.py` to detect drift against
+`tests/resources/openapi.json`. Update the pinned spec and regenerate when the
+backend contract changes.
+
+> Note: `datamodel-code-generator` emits PEP 604 (`X | None`) syntax, so the
+> package floor is **Python 3.10** (`requires-python = ">=3.10"`).
+
+## httpx base URL gotcha
+
+httpx resolves request paths against `base_url` per RFC 3986, so the base URL
+**must end with `/`** or the `/api` context path is dropped. `KainguruConfig`
+normalizes this; request paths are written without a leading slash
+(`"v1/executions"`).
+
+## Publishing
+
+- PyPI name: `kainguru-sdk`; import name: `kainguru`.
+- Automated via GitHub Actions on tag push; see
+  `.github/workflows/kainguru-sdk-python-publish.yml` and the step-by-step guide in
+  `.claude/plans/kainguru-pypi-publish-steps.md`.
+
+```bash
+# Manual publish (fallback)
+make build
+python -m twine upload dist/*
+```

kainguru_sdk-0.1.4.dev0/Makefile

@@ -0,0 +1,28 @@
+.PHONY: install generate lint typecheck test build all
+
+install:
+	python -m pip install -e ".[dev]"
+
+# Regenerate pydantic models from the pinned OpenAPI spec.
+generate:
+	datamodel-codegen \
+		--input tests/resources/openapi.json \
+		--input-file-type openapi \
+		--output src/kainguru/models.py \
+		--output-model-type pydantic_v2.BaseModel \
+		--target-python-version 3.10 \
+		--disable-timestamp
+
+lint:
+	ruff check src tests
+
+typecheck:
+	mypy
+
+test:
+	pytest
+
+build:
+	python -m build
+
+all: generate lint typecheck test build

kainguru_sdk-0.1.4.dev0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: kainguru-sdk
+Version: 0.1.4.dev0
+Summary: Python SDK for the Kainguru ML platform — run models and fine-tune them.
+Project-URL: Homepage, https://kainguru.com
+Project-URL: Repository, https://github.com/kainguru/kainguru
+Author: Kainguru
+License: MIT
+Keywords: fine-tuning,kainguru,machine-learning,ml,sdk
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kainguru-sdk
+
+Python SDK for the [Kainguru](https://kainguru.com) ML platform — run models and
+fine-tune them from any Python application.
+
+- Python 3.10+
+- **Sync and async** clients with an identical surface (`KainguruClient`, `AsyncKainguruClient`)
+- Typed pydantic v2 models
+- Built-in polling with configurable timeout and backoff
+- Automatic retry on 429 / 5xx with exponential backoff (honors `Retry-After`)
+
+Covers `/v1/executions` and `/v1/fine-tuning`.
+
+---
+
+## Installation
+
+```bash
+pip install kainguru-sdk
+```
+
+Import name is `kainguru`:
+
+```python
+from kainguru import KainguruClient
+```
+
+---
+
+## Authentication
+
+You must pass **both** an API key and the base URL explicitly. The API key is issued
+from the Kainguru Dashboard (it begins with `kg_`); the base URL is the full host
+including the `/api` context path:
+
+```python
+from kainguru import KainguruClient
+
+client = KainguruClient(
+    api_key="kg_your_api_key",
+    base_url="https://your-host/api",
+)
+```
+
+Both fields are required. If either is missing or blank, the constructor raises
+`KainguruConfigError` (fail fast). There are no defaults, environment presets, or
+environment-variable fallbacks.
+
+`KainguruClient` is a context manager — use `with` to close the HTTP pool automatically.
+
+---
+
+## Quick start (sync)
+
+```python
+from kainguru import KainguruClient
+
+with KainguruClient(
+    api_key="kg_your_api_key",
+    base_url="https://your-host/api",
+) as client:
+    submitted = client.executions.execute(
+        "my-mlflow-id",
+        {"prompt": "hello world"},
+        output_format="json",
+    )
+
+    done = client.executions.await_completion(submitted.id)
+
+    print(done.status)              # ModelStatus.COMPLETED / FAILED
+    print(done.execution.output)    # model output
+```
+
+`ml_flow_id` (first positional arg) is the model's **MLflow id** — the identifier the
+Dashboard shows for the model.
+
+## Quick start (async)
+
+```python
+import asyncio
+from kainguru import AsyncKainguruClient
+
+
+async def main():
+    async with AsyncKainguruClient(
+        api_key="kg_your_api_key", base_url="https://your-host/api"
+    ) as client:
+        submitted = await client.executions.execute(
+            "my-mlflow-id", {"prompt": "hello world"}, output_format="json"
+        )
+        done = await client.executions.await_completion(submitted.id)
+        print(done.status)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Executions API
+
+```python
+exec = client.executions
+
+# Run a model (returns immediately, typically PENDING)
+pending = exec.execute(ml_flow_id, input, output_format=None, exec_id=None)
+
+# Poll the current status once
+current = exec.get(id)
+
+# Block until COMPLETED or FAILED (default: 2 s interval, 5 min timeout)
+done = exec.await_completion(id)
+
+# Block with custom poll options
+done = exec.await_completion(id, poll_interval=1.0, timeout=60.0)
+```
+
+**Terminal statuses:** `COMPLETED`, `FAILED`. `REGISTERED` is treated as non-terminal.
+A `FAILED` job *returns* from `await_completion` — inspect `dto.status`; it is not raised.
+
+---
+
+## Fine-Tuning API
+
+```python
+ft = client.fine_tuning
+
+# Start fine-tuning
+pending = ft.execute(model_id, "my-fine-tuned-variant", input)
+
+# Get status / poll until done
+current = ft.get_status(id)
+done = ft.await_completion(id)
+```
+
+(The async client exposes the same methods with `await`.)
+
+---
+
+## Polling options
+
+```python
+client.executions.await_completion(
+    id,
+    poll_interval=2.0,   # base interval between polls in s (default 2.0)
+    timeout=300.0,       # total wall-clock timeout in s (default 300.0)
+    backoff=1.5,         # multiply interval each attempt (default 1.0 = fixed)
+    max_interval=30.0,   # cap on interval after backoff (default 30.0)
+)
+```
+
+On timeout, `await_completion` raises `KainguruTimeoutError`, which carries the last DTO
+seen via `err.last_dto`.
+
+---
+
+## Configuration
+
+```python
+client = KainguruClient(
+    api_key="kg_...",                    # required, explicit key
+    base_url="https://your-host/api",    # required, full host incl. /api context path
+    timeout=30.0,                        # per-request timeout in s
+    max_retries=3,                       # retries on 429 / 5xx / network
+)
+```
+
+Both `api_key` and `base_url` are required and must be passed explicitly — there are no
+defaults or environment-variable fallbacks. The base URL must be the full host including
+the dashboard's `/api` context path.
+
+Every method also accepts a per-request `api_key=` to override the client key for one call.
+
+---
+
+## Error handling
+
+All errors extend `KainguruError`.
+
+| Error | When |
+|---|---|
+| `KainguruConfigError` | Missing/invalid configuration (e.g. no API key) |
+| `KainguruAPIError` | Non-2xx HTTP response, or `success=false` in the body. Has `status_code`, `body`, `api_code` |
+| `KainguruAuthError` | 401 / 403 (subclass of `KainguruAPIError`) |
+| `KainguruNotFoundError` | 404 (subclass of `KainguruAPIError`) |
+| `KainguruRateLimitError` | 429 (subclass of `KainguruAPIError`); exposes `retry_after` |
+| `KainguruTimeoutError` | `await_completion` exceeded `timeout`; carries `last_dto` |
+| `KainguruConnectionError` | Network / transport failure; chained via `from` |
+
+```python
+from kainguru import (
+    KainguruAPIError,
+    KainguruNotFoundError,
+    KainguruTimeoutError,
+)
+
+try:
+    result = client.executions.await_completion(id)
+    if result.status.value == "FAILED":
+        ...  # FAILED is returned, not raised — inspect the result
+except KainguruNotFoundError as e:
+    print("not found:", e.status_code)
+except KainguruAPIError as e:
+    print(f"HTTP {e.status_code}: {e.body}")
+except KainguruTimeoutError as e:
+    print("timed out; last:", e.last_dto)
+```
+
+The SDK automatically retries `429` and `5xx` responses up to 3 times with exponential
+backoff (base 1 s, doubling per attempt); `Retry-After` headers are respected.
+
+---
+
+## Limitations (v0.1.0)
+
+- Cancel endpoints are not exposed yet (they require JWT/Keycloak auth, not an API key).
+- `input` parameters are untyped (`dict[str, Any]`).
+- `output_format` is a free `str`; allowed values are not yet enumerated by the backend.
+
+---
+
+> Building or publishing the SDK yourself? See **[MAINTAINERS.md](MAINTAINERS.md)**.

kainguru_sdk-0.1.4.dev0/README.md

@@ -0,0 +1,222 @@
+# kainguru-sdk
+
+Python SDK for the [Kainguru](https://kainguru.com) ML platform — run models and
+fine-tune them from any Python application.
+
+- Python 3.10+
+- **Sync and async** clients with an identical surface (`KainguruClient`, `AsyncKainguruClient`)
+- Typed pydantic v2 models
+- Built-in polling with configurable timeout and backoff
+- Automatic retry on 429 / 5xx with exponential backoff (honors `Retry-After`)
+
+Covers `/v1/executions` and `/v1/fine-tuning`.
+
+---
+
+## Installation
+
+```bash
+pip install kainguru-sdk
+```
+
+Import name is `kainguru`:
+
+```python
+from kainguru import KainguruClient
+```
+
+---
+
+## Authentication
+
+You must pass **both** an API key and the base URL explicitly. The API key is issued
+from the Kainguru Dashboard (it begins with `kg_`); the base URL is the full host
+including the `/api` context path:
+
+```python
+from kainguru import KainguruClient
+
+client = KainguruClient(
+    api_key="kg_your_api_key",
+    base_url="https://your-host/api",
+)
+```
+
+Both fields are required. If either is missing or blank, the constructor raises
+`KainguruConfigError` (fail fast). There are no defaults, environment presets, or
+environment-variable fallbacks.
+
+`KainguruClient` is a context manager — use `with` to close the HTTP pool automatically.
+
+---
+
+## Quick start (sync)
+
+```python
+from kainguru import KainguruClient
+
+with KainguruClient(
+    api_key="kg_your_api_key",
+    base_url="https://your-host/api",
+) as client:
+    submitted = client.executions.execute(
+        "my-mlflow-id",
+        {"prompt": "hello world"},
+        output_format="json",
+    )
+
+    done = client.executions.await_completion(submitted.id)
+
+    print(done.status)              # ModelStatus.COMPLETED / FAILED
+    print(done.execution.output)    # model output
+```
+
+`ml_flow_id` (first positional arg) is the model's **MLflow id** — the identifier the
+Dashboard shows for the model.
+
+## Quick start (async)
+
+```python
+import asyncio
+from kainguru import AsyncKainguruClient
+
+
+async def main():
+    async with AsyncKainguruClient(
+        api_key="kg_your_api_key", base_url="https://your-host/api"
+    ) as client:
+        submitted = await client.executions.execute(
+            "my-mlflow-id", {"prompt": "hello world"}, output_format="json"
+        )
+        done = await client.executions.await_completion(submitted.id)
+        print(done.status)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Executions API
+
+```python
+exec = client.executions
+
+# Run a model (returns immediately, typically PENDING)
+pending = exec.execute(ml_flow_id, input, output_format=None, exec_id=None)
+
+# Poll the current status once
+current = exec.get(id)
+
+# Block until COMPLETED or FAILED (default: 2 s interval, 5 min timeout)
+done = exec.await_completion(id)
+
+# Block with custom poll options
+done = exec.await_completion(id, poll_interval=1.0, timeout=60.0)
+```
+
+**Terminal statuses:** `COMPLETED`, `FAILED`. `REGISTERED` is treated as non-terminal.
+A `FAILED` job *returns* from `await_completion` — inspect `dto.status`; it is not raised.
+
+---
+
+## Fine-Tuning API
+
+```python
+ft = client.fine_tuning
+
+# Start fine-tuning
+pending = ft.execute(model_id, "my-fine-tuned-variant", input)
+
+# Get status / poll until done
+current = ft.get_status(id)
+done = ft.await_completion(id)
+```
+
+(The async client exposes the same methods with `await`.)
+
+---
+
+## Polling options
+
+```python
+client.executions.await_completion(
+    id,
+    poll_interval=2.0,   # base interval between polls in s (default 2.0)
+    timeout=300.0,       # total wall-clock timeout in s (default 300.0)
+    backoff=1.5,         # multiply interval each attempt (default 1.0 = fixed)
+    max_interval=30.0,   # cap on interval after backoff (default 30.0)
+)
+```
+
+On timeout, `await_completion` raises `KainguruTimeoutError`, which carries the last DTO
+seen via `err.last_dto`.
+
+---
+
+## Configuration
+
+```python
+client = KainguruClient(
+    api_key="kg_...",                    # required, explicit key
+    base_url="https://your-host/api",    # required, full host incl. /api context path
+    timeout=30.0,                        # per-request timeout in s
+    max_retries=3,                       # retries on 429 / 5xx / network
+)
+```
+
+Both `api_key` and `base_url` are required and must be passed explicitly — there are no
+defaults or environment-variable fallbacks. The base URL must be the full host including
+the dashboard's `/api` context path.
+
+Every method also accepts a per-request `api_key=` to override the client key for one call.
+
+---
+
+## Error handling
+
+All errors extend `KainguruError`.
+
+| Error | When |
+|---|---|
+| `KainguruConfigError` | Missing/invalid configuration (e.g. no API key) |
+| `KainguruAPIError` | Non-2xx HTTP response, or `success=false` in the body. Has `status_code`, `body`, `api_code` |
+| `KainguruAuthError` | 401 / 403 (subclass of `KainguruAPIError`) |
+| `KainguruNotFoundError` | 404 (subclass of `KainguruAPIError`) |
+| `KainguruRateLimitError` | 429 (subclass of `KainguruAPIError`); exposes `retry_after` |
+| `KainguruTimeoutError` | `await_completion` exceeded `timeout`; carries `last_dto` |
+| `KainguruConnectionError` | Network / transport failure; chained via `from` |
+
+```python
+from kainguru import (
+    KainguruAPIError,
+    KainguruNotFoundError,
+    KainguruTimeoutError,
+)
+
+try:
+    result = client.executions.await_completion(id)
+    if result.status.value == "FAILED":
+        ...  # FAILED is returned, not raised — inspect the result
+except KainguruNotFoundError as e:
+    print("not found:", e.status_code)
+except KainguruAPIError as e:
+    print(f"HTTP {e.status_code}: {e.body}")
+except KainguruTimeoutError as e:
+    print("timed out; last:", e.last_dto)
+```
+
+The SDK automatically retries `429` and `5xx` responses up to 3 times with exponential
+backoff (base 1 s, doubling per attempt); `Retry-After` headers are respected.
+
+---
+
+## Limitations (v0.1.0)
+
+- Cancel endpoints are not exposed yet (they require JWT/Keycloak auth, not an API key).
+- `input` parameters are untyped (`dict[str, Any]`).
+- `output_format` is a free `str`; allowed values are not yet enumerated by the backend.
+
+---
+
+> Building or publishing the SDK yourself? See **[MAINTAINERS.md](MAINTAINERS.md)**.

kainguru_sdk-0.1.4.dev0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kainguru-sdk"
+version = "0.1.4.dev0"
+description = "Python SDK for the Kainguru ML platform — run models and fine-tune them."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Kainguru" }]
+keywords = ["kainguru", "ml", "machine-learning", "sdk", "fine-tuning"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.5",
+]
+
+[project.urls]
+Homepage = "https://kainguru.com"
+Repository = "https://github.com/kainguru/kainguru"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "build>=1.2",
+    "datamodel-code-generator>=0.25",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kainguru"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/kainguru"]
+# models.py is generated by datamodel-code-generator; its output (e.g. constr(...)
+# constraint types) isn't static-type clean, so it's excluded from mypy checking.
+[[tool.mypy.overrides]]
+module = "kainguru.models"
+ignore_errors = true

kainguru_sdk-0.1.4.dev0/src/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",
+]