kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/chat/_views/chat_request.py

@@ -0,0 +1,153 @@
+"""OpenAI-compatible chat request model.
+
+``messages`` / ``tools`` are kept as loose dicts on purpose: OpenAI's multimodal
+``content`` parts vary by client and we parse them leniently in
+``_operations/parse_messages``. Unknown top-level fields are tolerated
+(``extra="allow"``). ``model`` selects which registered chat model answers
+(see core/model).
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ChatRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={
+            "examples": [
+                {
+                    "model": "qwen3-omni",
+                    "messages": [
+                        {"role": "system", "content": "You are a helpful assistant."},
+                        {
+                            "role": "user",
+                            "content": [
+                                {"type": "text", "text": "What is in this image?"},
+                                {
+                                    "type": "image_url",
+                                    "image_url": {"url": "https://example.com/cat.png"},
+                                },
+                            ],
+                        },
+                    ],
+                }
+            ]
+        },
+    )
+
+    messages: list[dict[str, Any]] = Field(
+        ...,
+        min_length=1,
+        description=(
+            "OpenAI-style conversation turns. Each item is "
+            "`{role, content}` where `role` is `system` / `user` / "
+            "`assistant` / `tool`. `content` is either a plain string or a "
+            "list of typed parts for multimodal input: `{type: 'text', text}`, "
+            "`{type: 'image_url', image_url: {url}}`, "
+            "`{type: 'audio_url', audio_url: {url}}`, "
+            "`{type: 'video_url', video_url: {url}}`, or inline base64 via "
+            "`{type: 'input_audio', input_audio: {data, format}}`. A media `url` "
+            "accepts an http(s) URL or a `data:` URL; `input_audio.data` is bare "
+            "base64. Which modalities are accepted depends on the resolved model "
+            "(see GET /v1/models)."
+        ),
+    )
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Registered chat model name, alias, or repo id. When omitted, the "
+            "family default chat model answers. See GET /v1/models for the "
+            "servable list and each model's accepted input modalities."
+        ),
+        examples=["qwen3-omni"],
+    )
+    tools: list[dict[str, Any]] | None = Field(
+        default=None,
+        description=(
+            "OpenAI function-tool definitions: "
+            "`{type: 'function', function: {name, description, parameters}}` "
+            "where `parameters` is a JSON Schema object. Tool calls are parsed "
+            "from the model output and returned as `message.tool_calls`."
+        ),
+    )
+    tool_choice: Any | None = Field(
+        default=None,
+        description=(
+            "How the model may call tools: `'auto'` (default when tools are "
+            "given — model decides), `'none'` (never call a tool), "
+            "`'required'`/`'any'` (must call at least one tool), or a specific "
+            "tool `{type: 'function', function: {name}}`."
+        ),
+    )
+    parallel_tool_calls: bool = Field(
+        default=True,
+        description=(
+            "OpenAI-compatible. When false, at most one tool call is returned "
+            "even if the model emits several."
+        ),
+    )
+
+    max_completion_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Upper bound on generated tokens. Replaces the deprecated "
+            "`max_tokens`, which is rejected."
+        ),
+    )
+    temperature: float | None = Field(
+        default=None,
+        description="Sampling temperature. Higher is more random; 0 is greedy.",
+    )
+    top_p: float | None = Field(
+        default=None,
+        description="Nucleus sampling cutoff in (0, 1].",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Seed for reproducible sampling when set.",
+    )
+
+    # Extensions (not in the OpenAI spec):
+    fps: float | None = Field(
+        default=None,
+        description=(
+            "kiapi extension (non-OpenAI). Frame sampling rate for video "
+            "inputs, in frames per second."
+        ),
+    )
+    use_audio_in_video: bool | None = Field(
+        default=None,
+        description=(
+            "kiapi extension (non-OpenAI). Demux a video's audio track and feed "
+            "it as audio alongside the frames. Overrides the server default."
+        ),
+    )
+    chat_template_kwargs: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "kiapi extension (non-OpenAI). Extra kwargs forwarded verbatim to "
+            "the tokenizer's `apply_chat_template`, e.g. "
+            "`{'enable_thinking': false}` to turn off Qwen3.6's reasoning. "
+            "Mirrors the vLLM/SGLang "
+            "`extra_body={'chat_template_kwargs': {...}}` convention."
+        ),
+    )
+
+    stream: bool = Field(
+        default=False,
+        description=(
+            "When true, stream the answer as OpenAI-style "
+            "`text/event-stream` `chat.completion.chunk` events ending with "
+            "`data: [DONE]`. When false, wait for and return the full "
+            "`chat.completion` object."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def reject_deprecated_max_tokens(self):  # type: ignore
+        if self.model_extra and "max_tokens" in self.model_extra:
+            raise ValueError("max_tokens is deprecated; use max_completion_tokens")
+        return self

kiapi/capabilities/depthpro/README.ja.md

@@ -0,0 +1,131 @@
+# depthpro
+
+[English](README.md) | **日本語**
+
+[mflux Depth Pro](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/depth_pro/README.md) で、単一画像から深度マップを推定し、下記を生成します。
+
+- グレースケール PNG の深度マップ
+- 任意で、生の深度配列と min/max を含む圧縮 NPZ
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/depthpro/estimate` | 深度推定 | Files API の画像から深度マップを推定。 |
+| `GET /v1/image/depthpro/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/depthpro/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/depthpro/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/depthpro/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/depthpro/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Depth Pro の MLX 実装を利用。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [apple/DepthPro](https://huggingface.co/apple/DepthPro) | Apple Depth Pro License | 不要 | 1.8 GB | `base`（デフォルト）。単一画像から相対深度を推定。既定は `quantize: 8`。初回利用時にモデルをダウンロードすることがある。 |
+
+## Notes
+
+- **レスポンス形式**:
+  `include_depth_data: true`（デフォルト）では PNG と NPZ の 2 成果物を作るため、
+  sync でも Job JSON を返す。`include_depth_data: false` では PNG のみになり、
+  sync はデフォルトで生の PNG バイト列を返す。Job JSON が必要な場合は
+  `Accept: application/json` を付ける。
+- **quantize override**:
+  `quantize` は `3` / `4` / `5` / `6` / `8` / `null`。通常は常駐モデルを使うが、
+  リクエストで既定値と異なる `quantize` を指定した場合は、一回限りの一時モデルとして
+  ロード・実行・解放する。
+- **入力サイズ上限**:
+  既定では入力画像は `4096 * 4096` pixels まで。Depth Pro は内部でリサイズするが、
+  大きすぎる入力でキューを長時間占有しないように制限している。
+- **進捗**:
+  Depth Pro は単一 forward pass で細かいステップ通知を持たないため、実行中は時間ベースの
+  synthetic progress を流す。
+
+## Quickstart
+
+### estimate — 深度推定
+
+先にソース画像をアップロードする:
+
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+
+深度 PNG と生データ NPZ の両方を作る:
+
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "sync",
+  image: {type: "file_id", file_id: $img},
+  quantize: 8,
+  include_depth_data: true
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" | jq .
+```
+
+表示用の深度 PNG だけが欲しい場合:
+
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "sync",
+  image: {type: "file_id", file_id: $img},
+  include_depth_data: false
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o depth.png
+```
+
+### async
+
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "async",
+  image: {type: "file_id", file_id: $img},
+  include_depth_data: true
+}')
+
+JOB=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+
+完了後、Job の `artifacts` または `result.depth_image_file_id` /
+`result.depth_data_file_id` を使って成果物を取得できます。
+
+```bash
+FID=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.depth_image_file_id)
+curl -sS http://localhost:${PORT:-8000}/v1/files/$FID/download -o depth.png
+```

kiapi/capabilities/depthpro/README.md

@@ -0,0 +1,124 @@
+# depthpro
+
+**English** | [日本語](README.ja.md)
+
+[mflux Depth Pro](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/depth_pro/README.md) estimates a depth map from a single image and produces the following:
+
+- Depth map in grayscale PNG
+- optionally compressed NPZ with raw depth array and min/max
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/depthpro/estimate` | Depth estimation | Estimate depth map from Files API images. |
+| `GET /v1/image/depthpro/models` | Model list | Returns a list of available models. |
+| `GET /v1/image/depthpro/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/depthpro/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/depthpro/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/depthpro/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Uses Depth Pro's MLX implementation. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [apple/DepthPro](https://huggingface.co/apple/DepthPro) | Apple Depth Pro License | Not required | 1.8 GB | `base` (default). Estimating relative depth from a single image. Default is `quantize: 8`. A model may be downloaded the first time you use it. |
+
+## Notes
+
+- **Response format**:
+  `include_depth_data: true` (default) creates two artifacts, PNG and NPZ.
+  sync also returns Job JSON. `include_depth_data: false` means only PNG,
+  sync returns raw PNG bytes by default. If you need Job JSON
+  Add `Accept: application/json`.
+- **quantize override**:
+  `quantize` is `3` / `4` / `5` / `6` / `8` / `null`. Usually a resident model is used, but
+  If you specify `quantize` in the request that is different from the default value, it will be used as a one-time temporary model.
+  Load, execute, release.
+- **Input size limit**:
+  By default, the input image is up to `4096 * 4096` pixels. Depth Pro resizes internally, but
+  Limits inputs that are too large to occupy the queue for too long.
+- **Progress**:
+  Depth Pro has a single forward pass and no detailed step notification, so it uses time-based
+  Stream synthetic progress.
+
+## Quickstart
+
+### estimate — Depth estimation
+
+Upload the source image first:
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+Create both depth PNG and raw data NPZ:
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "sync",
+  image: {type: "file_id", file_id: $img},
+  quantize: 8,
+  include_depth_data: true
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" | jq .
+```
+If you just want the depth PNG for display:
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "sync",
+  image: {type: "file_id", file_id: $img},
+  include_depth_data: false
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o depth.png
+```
+
+### async
+
+```bash
+PARAMS=$(jq -n \
+--arg img "$IMG" \
+'{
+  model: "base",
+  mode: "async",
+  image: {type: "file_id", file_id: $img},
+  include_depth_data: true
+}')
+
+JOB=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/depthpro/estimate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+After completion, the Job's `artifacts` or `result.depth_image_file_id` /
+You can retrieve artifacts using `result.depth_data_file_id`.
+```bash
+FID=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.depth_image_file_id)
+curl -sS http://localhost:${PORT:-8000}/v1/files/$FID/download -o depth.png
+```

kiapi/capabilities/depthpro/__init__.py

@@ -0,0 +1,23 @@
+"""depthpro family — Depth Pro image → depth map estimation via mflux.
+
+Endpoint: ``POST /v1/image/depthpro/estimate``. Depth Pro consumes one input
+image from the Files API and stores a displayable grayscale depth PNG, plus an
+optional compressed NPZ with the raw depth array.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_estimate import validate_estimate
+from ._operations.handle_estimate import handle_estimate
+from ._settings import settings_manager
+from ._views.estimate_request import EstimateRequest
+
+__all__ = [
+    "EstimateRequest",  # ._views
+    "ValidationError",  # kiapi.capabilities
+    "handle_estimate",  # ._operations
+    "register",  # ._helpers
+    "settings_manager",  # ._settings
+    "validate_estimate",  # ._helpers
+]

kiapi/capabilities/depthpro/_constants/description.py

@@ -0,0 +1,39 @@
+DESCRIPTION = """Monocular depth estimation from a single image (Apple Depth Pro via mflux).
+
+This is **image-to-depth**, not prompt-driven image generation: you give one
+image and get back a metric depth map.
+
+## Upstream docs
+- [mflux](https://github.com/filipstrand/mflux) — the MLX engine kiapi runs
+- [apple/DepthPro](https://huggingface.co/apple/DepthPro) — model weights
+- [apple/ml-depth-pro](https://github.com/apple/ml-depth-pro) — original Depth Pro code and paper
+
+## What you get back
+- A grayscale depth **PNG** where brighter pixels are nearer and darker pixels
+  are farther — ready to display or overlay.
+- Optionally (default on, `include_depth_data=true`) a compressed **NPZ**
+  containing the raw float depth array plus `min_depth` / `max_depth` in meters,
+  for downstream numeric use (point clouds, masking, measurement).
+
+The depth array is loadable with NumPy: `np.load(path)["depth"]`, with scalar
+`min_depth` / `max_depth` also stored in the same archive.
+
+## Models
+- **base** (default) — `apple/DepthPro`. The only variant today.
+
+## Quantization
+`quantize` selects the model's bit-width (one of 3, 4, 5, 6, 8; server default
+8). The warmed, resident model uses the server default; requesting a *different*
+`quantize` builds a one-off transient model for that call, which loads weights
+fresh and is therefore slower and not reused. Keep `quantize` unset (or equal to
+the default) for the fast resident path.
+
+## TIPS
+- For a quick visual, leave `include_depth_data=false` and call `sync` — you get
+  the PNG bytes straight back (`curl -o depth.png`).
+- For measurement or 3D work, keep `include_depth_data=true` and read the NPZ.
+- Large uploads are bounded by an input pixel cap; downscale very large images
+  before sending. Depth Pro resizes internally, so modest inputs are fine.
+- First use downloads Apple's Depth Pro weights; run `kiapi activate` ahead of
+  time to avoid a cold-start download on the first request.
+"""

kiapi/capabilities/depthpro/_helpers/register.py

@@ -0,0 +1,46 @@
+from kiapi.core.capability import CapabilitySpec, capability_spec_registry
+from kiapi.core.model import ModelSpec, model_registry
+from kiapi.core.setup import UrlFileResource
+
+from .._constants.description import DESCRIPTION
+from .._models import depthpro
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="depthpro",
+            domain="image",
+            title="kiapi DepthPro API",
+            summary="Estimate depth maps from input images.",
+            description=DESCRIPTION,
+            openapi_path="/v1/image/depthpro/openapi.json",
+            docs_path="/v1/image/depthpro/docs",
+            redoc_path="/v1/image/depthpro/redoc",
+            path_prefixes=("/v1/image/depthpro",),
+        )
+    )
+
+    depthpro_url = "https://ml-site.cdn-apple.com/models/depth-pro/depth_pro.pt"
+    model_registry.register(
+        ModelSpec(
+            name="base",
+            family="depthpro",
+            domain="image",
+            repo="apple/DepthPro",
+            module=depthpro,
+            weight_gb=2.7,
+            peak_headroom_gb=1.2,
+            framework="mlx",
+            priority=0,
+            aliases=("depthpro", "depth-pro", "DepthPro"),
+            default=True,
+            setup_resources=(
+                UrlFileResource(
+                    url=depthpro_url,
+                    path="~/.cache/mflux/depth_pro/depth_pro.pt",
+                    disk_gb=1.8,
+                ),
+            ),
+        )
+    )

kiapi/capabilities/depthpro/_helpers/validate_estimate.py

@@ -0,0 +1,32 @@
+from PIL import Image
+
+from kiapi.capabilities import ValidationError
+
+from .._settings import settings_manager
+from .._views.estimate_request import EstimateRequest
+
+
+def validate_estimate(
+    req: EstimateRequest,
+    *,
+    image_path: str | None = None,
+) -> None:
+    settings = settings_manager.get_settings()
+
+    if req.quantize is not None and req.quantize not in (3, 4, 5, 6, 8):
+        raise ValidationError("quantize must be one of 3, 4, 5, 6, 8")
+
+    if image_path is None:
+        return
+
+    try:
+        with Image.open(image_path) as img:
+            width, height = img.size
+    except Exception as exc:
+        raise ValidationError(f"input image could not be opened: {exc}")  # noqa: B904
+
+    pixels = width * height
+    if pixels > settings.max_input_pixels:
+        raise ValidationError(
+            f"input image has {pixels} pixels, exceeding the cap {settings.max_input_pixels}"
+        )