kiapi 0.1.0__tar.gz → 0.2.0__tar.gz

{kiapi-0.1.0 → kiapi-0.2.0}/.gitignore

@@ -5,6 +5,7 @@ build/
 dist/
 wheels/
 *.egg-info
+.mypy_cache/
 
 # Virtual environments
 .venv

{kiapi-0.1.0 → kiapi-0.2.0}/ARCHITECTURE.ja.md

@@ -22,6 +22,10 @@ kiapi/
     workdir/           # 実行中の一時作業ディレクトリ管理
     net/               # ネットワークガード（ユーザー指定 URL の SSRF 検証）
     logging/           # ロギング設定
+    relay/             # relay 抽象、plugin registry、process 内 dispatcher
+
+  relay/
+    gcp/               # Firebase RTDB 通知 + GCS payload transport
 
   capabilities/        # ファミリーごとに 1 パッケージ（dir == family）
     chat/              # OpenAI 互換 chat completions（マルチモーダル / tool / stream）
@@ -186,6 +190,50 @@ SearXNG / Crawl4AI は Docker container そのものとしてではなく、kiap
 resident subprocess の payload として扱う。起動コマンドが `docker run --rm` なので、
 kiapi 停止や eviction で subprocess を止めれば container も掃除される。
 
+## Remote Job Relay
+
+relay は `KIAPI_RELAY_DEFAULT` または `kiapi run --relay ...` で有効化する optional
+background subsystem である。`core/relay` は安定した `Relay` / `RelayDelivery` protocol
+と plugin registry を定義する。`relay/gcp` は GCP transport、`relay/local` は local
+verification 用の filesystem-backed transport を実装する。
+
+```text
+requester
+  → GCS request.json
+  → RTDB request notification
+      ┊
+GCP relay SSE listener
+  → RTDB queued
+  → local relay queue
+  → RTDB running
+  → process 内 FastAPI app へ ASGI dispatch
+  → GCS response.body（binary のみ）
+  → GCS response.json（create-only generation precondition）
+  → atomic RTDB terminal response + request deletion
+```
+
+listener は delivery processing と独立して動作するため、現在の request を実行中でも次の
+request を local queue に積める。relay runner は delivery を直列に消費する。GPU job の
+直列化は API worker が引き続き管理し、relay progress は内部 job state ではなく bridge
+の進捗を表す。
+
+RTDB には Google OAuth credential を使う REST streaming API でアクセスする。terminal
+delivery は root-level multi-location `PATCH` を使い、response 公開と request 削除を
+atomic に行う。GCS は body、metadata の順で公開する。`response.json` が commit marker
+であり、`if_generation_match=0` を使用する。
+
+queued delivery の消費時に `response.json` が存在する場合、content type と size を復旧し、
+terminal RTDB notification を再送して API dispatch を skip する。これにより、完了済み
+処理を意図的に繰り返さず at-least-once notification handling を実現する。同じ node ID の
+kiapi process が複数あれば実行は重複し得るが、GCS commit marker を作成できるのは 1
+process だけである。
+
+LocalRelay は GCP の layout を local root directory 配下に写す。
+`{root}/{prefix}/nodes/{node_id}/requests/*.json` を poll し、
+`sessions/{session_id}/request.json` から request を読み、`response.body` を
+`response.json` より先に書き、terminal status を書いたタイミングで request notification
+を削除する。
+
 ---
 
 > [!NOTE] 以降は、上記の各ステップを実現する仕組み。

{kiapi-0.1.0 → kiapi-0.2.0}/ARCHITECTURE.md

@@ -22,6 +22,10 @@ kiapi/
     workdir/           # temporary working directory management
     net/               # network guard for user-provided URLs
     logging/           # logging setup
+    relay/             # relay abstraction, plugin registry, and local dispatcher
+
+  relay/
+    gcp/               # Firebase RTDB notifications + GCS payload transport
 
   capabilities/        # one package per family (dir == family)
     chat/              # OpenAI-compatible chat completions (multimodal / tool / stream)
@@ -144,6 +148,51 @@ Web search/fetch also runs through the worker. `memory.acquire` starts the
 resident SearXNG or Crawl4AI Docker subprocess on first use, waits for its
 healthcheck, and passes the local backend URL to the capability handler.
 
+## Remote Job Relay
+
+The relay is an optional background subsystem enabled by
+`KIAPI_RELAY_DEFAULT` or `kiapi run --relay ...`. `core/relay` defines the
+stable `Relay` / `RelayDelivery` protocols and plugin registry. `relay/gcp`
+implements the GCP transport, and `relay/local` implements a filesystem-backed
+transport for local verification.
+
+```text
+requester
+  → GCS request.json
+  → RTDB request notification
+      ┊
+GCP relay SSE listener
+  → RTDB queued
+  → local relay queue
+  → RTDB running
+  → ASGI dispatch to the in-process FastAPI app
+  → GCS response.body (binary only)
+  → GCS response.json (create-only generation precondition)
+  → atomic RTDB terminal response + request deletion
+```
+
+The listener runs independently from delivery processing, so it can queue new
+requests while the current request is running. The relay runner consumes
+deliveries serially. The API worker still controls GPU job serialization;
+relay progress represents bridge progress rather than internal job state.
+
+RTDB uses its REST streaming API with Google OAuth credentials. Terminal
+delivery uses a root-level multi-location `PATCH`, making response publication
+and request deletion atomic. GCS publishes body first and metadata last.
+`response.json` is the commit marker and uses `if_generation_match=0`.
+
+If `response.json` already exists when a queued delivery is consumed, the relay
+recovers its content type and size, republishes the terminal RTDB notification,
+and skips API dispatch. This provides at-least-once notification handling
+without intentionally repeating completed work. Duplicate kiapi processes can
+still execute concurrently, but only one can create the GCS commit marker.
+
+LocalRelay mirrors the GCP layout below a local root directory. It polls
+`{root}/{prefix}/nodes/{node_id}/requests/*.json`, reads requests from
+`sessions/{session_id}/request.json`, writes `response.body` before
+`response.json`, and removes the request notification when the terminal status
+is written.
+
 ## Models
 
 All servable models are registered as `ModelSpec` entries in one global model

{kiapi-0.1.0 → kiapi-0.2.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-26
+
+### Added
+
+- Added an optional plugin-based remote job relay with Firebase Realtime Database notifications, GCS request/response payloads, in-process ASGI dispatch, committed-response recovery, and atomic terminal delivery.
+- Added a filesystem-backed LocalRelay for local relay verification without GCP services.
+- Added relay verification scripts for LocalRelay, GCPRelay, and end-to-end LocalRelay capability checks.
+
+### Changed
+
+- Moved GCP relay dependencies into the optional `relay-gcp` extra.
+- Updated the minimum `pydantic-settings-manager` dependency to 3.7.0.
+
+### Fixed
+
+- Added the OAuth scopes required by the Firebase Realtime Database REST API to GCP relay credentials.
+- Added relay support for multipart file uploads such as `POST /v1/files`.
+
 ## [0.1.0] - 2026-06-23
 
 ### Added

{kiapi-0.1.0 → kiapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiapi
-Version: 0.1.0
+Version: 0.2.0
 Summary: Unified local inference API server for LLM agents on Apple Silicon (MLX): chat, embedding, image, music, sound-effect, and video — one process, one global memory budget, one single-flight queue, unified jobs and files.
 Project-URL: Homepage, https://github.com/kiarina/kiapi
 Project-URL: Repository, https://github.com/kiarina/kiapi
@@ -25,6 +25,7 @@ Requires-Python: <3.13,>=3.12
 Requires-Dist: click
 Requires-Dist: fastapi<0.137
 Requires-Dist: httpx
+Requires-Dist: kiarina-utils-common>=2.2.0
 Requires-Dist: mflux>=0.18.0
 Requires-Dist: mlx-audiocraft>=0.1.0
 Requires-Dist: mlx-embeddings>=0.1.0
@@ -33,7 +34,7 @@ Requires-Dist: numpy<2.5
 Requires-Dist: pillow
 Requires-Dist: platformdirs
 Requires-Dist: psutil
-Requires-Dist: pydantic-settings-manager>=3.6.0
+Requires-Dist: pydantic-settings-manager>=3.7.0
 Requires-Dist: pydantic>=2
 Requires-Dist: python-multipart
 Requires-Dist: pyyaml
@@ -43,6 +44,9 @@ Requires-Dist: torch
 Requires-Dist: torchaudio
 Requires-Dist: torchvision
 Requires-Dist: uvicorn[standard]
+Provides-Extra: relay-gcp
+Requires-Dist: google-cloud-storage>=3.7.0; extra == 'relay-gcp'
+Requires-Dist: kiarina-lib-google>=2.2.1; extra == 'relay-gcp'
 Description-Content-Type: text/markdown
 
 # kiapi
@@ -243,6 +247,71 @@ kiapi service stop
 kiapi service uninstall
 ```
 
+## Remote Job Relay
+
+The optional GCP relay lets a kiapi node inside a closed network receive API
+work without exposing an inbound socket. Firebase Realtime Database carries
+small notifications, while Cloud Storage carries request and response bodies.
+Install kiapi with the `relay-gcp` extra to enable it:
+
+```sh
+python3.12 -m pip install --upgrade "kiapi[relay-gcp]"
+uv tool install --python 3.12 "kiapi[relay-gcp]"
+```
+
+```sh
+export KIAPI_RELAY_GCP_NODE_ID="studio-1"
+export KIAPI_RELAY_GCP_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+export KIAPI_RELAY_GCP_PREFIX="private/kiapi"
+
+# Uses Application Default Credentials by default.
+kiapi run --relay gcp
+```
+
+The requester writes
+`{prefix}/sessions/{session_id}/request.json` in GCS, then writes a notification
+to `{prefix}/nodes/{node_id}/requests/{session_id}` in RTDB. The relay reports
+`queued`, `running`, and the terminal result below the requester node's
+`responses` path.
+
+- Requests are dispatched directly to the in-process FastAPI app and handled
+  one at a time by the relay.
+- JSON responses use `response.json`. Binary responses write `response.body`
+  before `response.json`.
+- `response.json` uses a GCS create-only generation precondition. A completed
+  response found after restart is reported without executing the API again.
+- The terminal RTDB response and request deletion use one atomic multi-location
+  update.
+- Startup installs a prefix-scoped lifecycle rule that deletes session objects
+  after one day. Set `KIAPI_RELAY_GCP_MANAGE_BUCKET_LIFECYCLE=false` when
+  infrastructure manages this rule.
+
+Use a dedicated bucket and narrowly scoped RTDB/GCS permissions. Google
+credentials are configured through
+[`kiarina-lib-google`](https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google).
+
+See [GCP Relay setup](kiapi/relay/gcp/README.md) for resource creation, IAM,
+authentication, configuration, and verification steps.
+
+For local relay verification without GCP, use `local`. It uses the same
+in-process dispatch path but stores notifications and payloads under a local
+directory:
+
+```sh
+export KIAPI_RELAY_LOCAL_NODE_ID="studio-1"
+export KIAPI_RELAY_LOCAL_ROOT="/tmp/kiapi/relay"
+export KIAPI_RELAY_LOCAL_PREFIX="private/kiapi"
+
+kiapi run --relay local
+```
+
+The requester writes `{root}/{prefix}/sessions/{session_id}/request.json`, then
+writes `{root}/{prefix}/nodes/{node_id}/requests/{session_id}.json` with
+`{"session_id":"...","source_node_id":"..."}`. The relay writes bridge status
+to `{root}/{prefix}/nodes/{source_node_id}/responses/{session_id}.json` and
+stores the committed response in the session directory.
+
 ## Architecture
 
 > [!NOTE]

{kiapi-0.1.0 → kiapi-0.2.0}/README.ja.md

@@ -197,6 +197,68 @@ kiapi service stop
 kiapi service uninstall
 ```
 
+## Remote Job Relay
+
+オプションの GCP relay を使うと、閉鎖ネットワーク内の kiapi node に inbound socket を
+公開せず API 処理を依頼できます。小さな通知は Firebase Realtime Database、request /
+response body は Cloud Storage で受け渡します。
+有効にするには、`relay-gcp` extra 付きで kiapi をインストールしてください。
+
+```sh
+python3.12 -m pip install --upgrade "kiapi[relay-gcp]"
+uv tool install --python 3.12 "kiapi[relay-gcp]"
+```
+
+```sh
+export KIAPI_RELAY_GCP_NODE_ID="studio-1"
+export KIAPI_RELAY_GCP_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+export KIAPI_RELAY_GCP_PREFIX="private/kiapi"
+
+# 既定では Application Default Credentials を使用
+kiapi run --relay gcp
+```
+
+requester は GCS の
+`{prefix}/sessions/{session_id}/request.json` を書き込んだ後、RTDB の
+`{prefix}/nodes/{node_id}/requests/{session_id}` へ通知を書き込みます。relay は
+requester node の `responses` path へ `queued`、`running`、terminal result を通知します。
+
+- request は process 内の FastAPI app へ直接 dispatch され、relay が 1 件ずつ処理します。
+- JSON response は `response.json`、binary response は `response.body` の後に
+  `response.json` を書き込みます。
+- `response.json` は GCS の create-only generation precondition で排他します。再起動後に
+  完了済み response が見つかった場合、API を再実行せず結果を再通知します。
+- terminal RTDB response の通知と request 削除は 1 回の atomic multi-location update
+  で行います。
+- 起動時に session object を 1 日後に削除する prefix 限定 lifecycle rule を設定します。
+  infrastructure 側で管理する場合は
+  `KIAPI_RELAY_GCP_MANAGE_BUCKET_LIFECYCLE=false` を指定してください。
+
+専用 bucket と必要最小限の RTDB / GCS 権限を使用してください。Google credential は
+[`kiarina-lib-google`](https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google)
+で設定します。
+
+resource 作成、IAM、認証、設定、検証手順は
+[GCP Relay setup](kiapi/relay/gcp/README.ja.md) を参照してください。
+
+GCP を使わずに relay を検証したい場合は `local` を使えます。同じ process 内 dispatch
+経路を使い、通知と payload をローカルディレクトリ配下に保存します。
+
+```sh
+export KIAPI_RELAY_LOCAL_NODE_ID="studio-1"
+export KIAPI_RELAY_LOCAL_ROOT="/tmp/kiapi/relay"
+export KIAPI_RELAY_LOCAL_PREFIX="private/kiapi"
+
+kiapi run --relay local
+```
+
+requester は `{root}/{prefix}/sessions/{session_id}/request.json` を書き込んだ後、
+`{root}/{prefix}/nodes/{node_id}/requests/{session_id}.json` に
+`{"session_id":"...","source_node_id":"..."}` を書き込みます。relay は bridge status を
+`{root}/{prefix}/nodes/{source_node_id}/responses/{session_id}.json` に書き込み、
+committed response を session directory に保存します。
+
 ## Architecture
 
 > [!NOTE]

{kiapi-0.1.0 → kiapi-0.2.0}/README.md

@@ -196,6 +196,71 @@ kiapi service stop
 kiapi service uninstall
 ```
 
+## Remote Job Relay
+
+The optional GCP relay lets a kiapi node inside a closed network receive API
+work without exposing an inbound socket. Firebase Realtime Database carries
+small notifications, while Cloud Storage carries request and response bodies.
+Install kiapi with the `relay-gcp` extra to enable it:
+
+```sh
+python3.12 -m pip install --upgrade "kiapi[relay-gcp]"
+uv tool install --python 3.12 "kiapi[relay-gcp]"
+```
+
+```sh
+export KIAPI_RELAY_GCP_NODE_ID="studio-1"
+export KIAPI_RELAY_GCP_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+export KIAPI_RELAY_GCP_PREFIX="private/kiapi"
+
+# Uses Application Default Credentials by default.
+kiapi run --relay gcp
+```
+
+The requester writes
+`{prefix}/sessions/{session_id}/request.json` in GCS, then writes a notification
+to `{prefix}/nodes/{node_id}/requests/{session_id}` in RTDB. The relay reports
+`queued`, `running`, and the terminal result below the requester node's
+`responses` path.
+
+- Requests are dispatched directly to the in-process FastAPI app and handled
+  one at a time by the relay.
+- JSON responses use `response.json`. Binary responses write `response.body`
+  before `response.json`.
+- `response.json` uses a GCS create-only generation precondition. A completed
+  response found after restart is reported without executing the API again.
+- The terminal RTDB response and request deletion use one atomic multi-location
+  update.
+- Startup installs a prefix-scoped lifecycle rule that deletes session objects
+  after one day. Set `KIAPI_RELAY_GCP_MANAGE_BUCKET_LIFECYCLE=false` when
+  infrastructure manages this rule.
+
+Use a dedicated bucket and narrowly scoped RTDB/GCS permissions. Google
+credentials are configured through
+[`kiarina-lib-google`](https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google).
+
+See [GCP Relay setup](kiapi/relay/gcp/README.md) for resource creation, IAM,
+authentication, configuration, and verification steps.
+
+For local relay verification without GCP, use `local`. It uses the same
+in-process dispatch path but stores notifications and payloads under a local
+directory:
+
+```sh
+export KIAPI_RELAY_LOCAL_NODE_ID="studio-1"
+export KIAPI_RELAY_LOCAL_ROOT="/tmp/kiapi/relay"
+export KIAPI_RELAY_LOCAL_PREFIX="private/kiapi"
+
+kiapi run --relay local
+```
+
+The requester writes `{root}/{prefix}/sessions/{session_id}/request.json`, then
+writes `{root}/{prefix}/nodes/{node_id}/requests/{session_id}.json` with
+`{"session_id":"...","source_node_id":"..."}`. The relay writes bridge status
+to `{root}/{prefix}/nodes/{source_node_id}/responses/{session_id}.json` and
+stores the committed response in the session directory.
+
 ## Architecture
 
 > [!NOTE]

{kiapi-0.1.0 → kiapi-0.2.0}/kiapi/api/app.py

@@ -11,6 +11,8 @@ from kiapi.core.app import AppContext
 from kiapi.core.capability import capability_spec_registry
 from kiapi.core.logging import setup_logger
 from kiapi.core.model import model_registry
+from kiapi.core.relay import RelayRunner, relay_registry
+from kiapi.core.relay import settings_manager as relay_settings_manager
 from kiapi.core.worker import create_worker
 
 from .audio.acestep.router import router as acestep_router
@@ -65,11 +67,20 @@ async def lifespan(app: FastAPI):  # type: ignore
     app.state.worker = worker
 
     worker.start()
-
     asyncio.create_task(worker.warmup())  # noqa: RUF006
 
+    relay_runner: RelayRunner | None = None
+
+    if relay_settings_manager.get_settings().default is not None:
+        relay_runner = RelayRunner(relay_registry.resolve(), app)
+        relay_runner.start()
+        app.state.relay_runner = relay_runner
+
     yield
 
+    if relay_runner is not None:
+        await relay_runner.stop()
+
     await worker.stop()
 
 

{kiapi-0.1.0 → kiapi-0.2.0}/kiapi/cli/config/template/cli.py

@@ -10,6 +10,10 @@ _SETTINGS_IMPORT_PATHS = [
     "kiapi.core.memory",
     "kiapi.core.worker",
     "kiapi.core.net",
+    "kiapi.core.relay",
+    "kiapi.relay.gcp",
+    "kiapi.relay.local",
+    "kiarina.lib.google",
     "kiapi.capabilities.chat",
     "kiapi.capabilities.embedding",
     "kiapi.capabilities.depthpro",

{kiapi-0.1.0 → kiapi-0.2.0}/kiapi/cli/run/cli.py

@@ -7,13 +7,20 @@ from kiapi.api import settings_manager as api_settings_manager
 from kiapi.cli import register_all_capabilities
 from kiapi.core.logging import get_log_level
 from kiapi.core.logging import settings_manager as logging_settings_manager
+from kiapi.core.relay import settings_manager as relay_settings_manager
 
 
 @click.command()
 @click.option("--host", type=str, help="Bind socket to this host")
 @click.option("--port", type=int, help="Bind socket to this port")
+@click.option("--relay", type=str, help="Start a relay, for example: gcp")
 @click.option("--debug", is_flag=True, help="Enable debug logging and hot reload")
-def run(host: str | None, port: int | None, debug: bool) -> None:
+def run(
+    host: str | None,
+    port: int | None,
+    relay: str | None,
+    debug: bool,
+) -> None:
     """Run the kiapi API server."""
     api_cli_args: dict[str, str | int] = {}
 
@@ -25,6 +32,9 @@ def run(host: str | None, port: int | None, debug: bool) -> None:
     if api_cli_args:
         api_settings_manager.cli_args = api_cli_args
 
+    if relay is not None:
+        relay_settings_manager.cli_args = {"default": relay}
+
     settings = api_settings_manager.get_settings()
 
     if debug:
@@ -33,6 +43,9 @@ def run(host: str | None, port: int | None, debug: bool) -> None:
         # in-process cli_args, so propagate the log level via the environment.
         os.environ["KIAPI_LOG_LEVEL"] = "DEBUG"
 
+        if relay is not None:
+            os.environ["KIAPI_RELAY_DEFAULT"] = relay
+
         # Hot reload requires an import string (the worker subprocess
         # re-imports the app), so use the ASGI factory that registers
         # capabilities on import.

{kiapi-0.1.0 → kiapi-0.2.0}/kiapi/core/config/_helpers/load_user_settings.py

@@ -31,7 +31,7 @@ def load_user_settings(path: Path | None = None) -> None:
     user_configs = _normalize_user_configs(data, settings_path)
 
     try:
-        load_user_configs(user_configs)
+        load_user_configs(user_configs, missing_module_policy="warn")
     except (ImportError, AttributeError, TypeError, ValueError) as exc:
         raise UserConfigError(f"Failed to load {settings_path}: {exc}") from exc
 

kiapi-0.2.0/kiapi/core/relay/__init__.py

@@ -0,0 +1,34 @@
+from ._instances.relay_registry import relay_registry
+from ._schemas.relay_file_body import RelayFileBody
+from ._schemas.relay_json_body import RelayJsonBody
+from ._schemas.relay_multipart_body import RelayMultipartBody
+from ._schemas.relay_multipart_file import RelayMultipartFile
+from ._services.relay_runner import RelayRunner
+from ._settings import RelaySettings, settings_manager
+from ._types.relay import Relay
+from ._types.relay_delivery import RelayDelivery
+from ._types.relay_method import RelayMethod
+from ._types.relay_name import RelayName
+from ._types.relay_specifier import RelaySpecifier
+from ._views.relay_error import RelayError
+from ._views.relay_request import RelayRequest
+from ._views.relay_response import RelayResponse
+
+__all__ = [
+    "Relay",
+    "RelayDelivery",
+    "RelayError",
+    "RelayFileBody",
+    "RelayJsonBody",
+    "RelayMethod",
+    "RelayMultipartBody",
+    "RelayMultipartFile",
+    "RelayName",
+    "RelayRequest",
+    "RelayResponse",
+    "RelayRunner",
+    "RelaySettings",
+    "RelaySpecifier",
+    "relay_registry",
+    "settings_manager",
+]

kiapi-0.2.0/kiapi/core/relay/_instances/relay_registry.py

@@ -0,0 +1,12 @@
+from kiarina.utils.component_registry import ComponentRegistry
+
+from .._settings import settings_manager
+from .._types.relay import Relay
+
+relay_registry = ComponentRegistry[Relay](
+    expected_type=Relay,  # type: ignore[type-abstract]
+    component_label="Relay",
+    get_default=lambda: settings_manager.get_settings().default,
+    get_presets=lambda: settings_manager.get_settings().presets,
+    get_customs=lambda: settings_manager.get_settings().customs,
+)

kiapi-0.2.0/kiapi/core/relay/_schemas/relay_file_body.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class RelayFileBody(BaseModel):
+    type: Literal["file"] = "file"
+    path: Path
+    content_type: str
+    size: int

kiapi-0.2.0/kiapi/core/relay/_schemas/relay_json_body.py

@@ -0,0 +1,8 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class RelayJsonBody(BaseModel):
+    type: Literal["json"] = "json"
+    value: Any

kiapi-0.2.0/kiapi/core/relay/_schemas/relay_multipart_body.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, Field
+
+from .relay_multipart_file import RelayMultipartFile
+
+
+class RelayMultipartBody(BaseModel):
+    fields: dict[str, str] = Field(default_factory=dict)
+    files: list[RelayMultipartFile]

kiapi-0.2.0/kiapi/core/relay/_schemas/relay_multipart_file.py

@@ -0,0 +1,19 @@
+import base64
+import binascii
+
+from pydantic import BaseModel, Field
+
+
+class RelayMultipartFile(BaseModel):
+    field: str = "file"
+    filename: str
+    content_type: str | None = None
+    content_base64: str = Field(
+        description="Base64-encoded file bytes for a multipart/form-data part.",
+    )
+
+    def content(self) -> bytes:
+        try:
+            return base64.b64decode(self.content_base64, validate=True)
+        except binascii.Error as exc:
+            raise ValueError("content_base64 must be valid base64") from exc