kiapi 0.2.0__tar.gz → 0.5.0__tar.gz

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

@@ -14,6 +14,12 @@ wheels/
 # ace-step writes a progress-estimate cache under the project root
 /.cache/
 
+# Local environment variables
+.env
+
+# Local settings
+test_settings.yaml
+
 # Local service logs
 *.log
 
@@ -23,3 +29,6 @@ wheels/
 
 # Test assets downloaded via mise
 tests/assets/
+
+# Node modules (pnpm-managed dev tooling, e.g. firebase-tools)
+node_modules/

kiapi-0.5.0/.mise/tasks/package/current

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+#MISE description="Print the current package name"
+
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+basename "$(dirname "$(dirname "$(dirname "$script_dir")")")"

kiapi-0.5.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

kiapi-0.5.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-07-11
+
+### Fixed
+
+- `kiapi service install` now also pins `XDG_CACHE_HOME` in the launchd property list so the background service uses the same cache directory and single-instance lock as the interactive CLI.
+
+## [0.4.0] - 2026-07-11
+
+### Added
+
+- Added `kiapi service show` to print the installed launchd property list.
+
+### Fixed
+
+- `kiapi service install` now pins the current `XDG_CONFIG_HOME` and `XDG_DATA_HOME` values in the launchd property list so the background service resolves the same user settings and data directories as the interactive CLI.
+- The hot-reload worker subprocess (`kiapi run --debug`) now loads the user settings file in the ASGI factory, so relays configured only in user settings (for example the GCP relay's `database_url`/`bucket`) start correctly. Previously `kiapi run --relay gcp --debug` failed at startup with "required field is not set" because the reload subprocess never ran `load_user_settings()`.
+
+## [0.3.0] - 2026-07-02
+
+### Added
+
+- `GET /health` now reports the status of the relay started with the server in a `relay` field (`name`, `running`, `failed`), or `null` when no relay is configured.
+- Added a `request` method to the `Relay` protocol and implemented it on `LocalRelay` and `GCPRelay`, promoting the relay request client from the verification scripts into the relay packages. Responses are returned as `RelayResponse`, with binary bodies materialized to a temporary file the caller owns.
+- The server now resolves a persistent relay `node_id` from its user data directory and injects it into the relay, and acquires a single-instance lock (via `kiarina-utils-app`, scoped to the user cache directory) at startup so a second `kiapi` cannot share the same node identity. Added a `request_poll_interval_s` setting for GCP request polling.
+
+### Changed
+
+- The relay `node_id` is now generated automatically and persisted per data directory instead of being configured. The manual `node_id`/`source_node_id` relay settings were removed; clients discover a target node through liveness heartbeats and address responses with their own generated `node_id`.
+- Simplified the `Relay` protocol to a single `watch` method and moved listener tasks and the HTTP client into the `watch` lifecycle, removing the explicit `close` method.
+- Reworked the relay verification scripts to issue requests through `Relay.request` via the relay registry factories, removing the duplicated transport client in `scripts/relay/_client.py`.
+- Converted the repository into a uv workspace and moved the `kiapi` package to `packages/kiapi/` with a `src/` layout. Packaging and lint/test paths are now per-package.
+- Extracted the relay subsystem into a separate `kiapi-relay` package. `kiapi.core.relay` is now `kiapi_relay`, and `kiapi.relay.{local,gcp}` are now `kiapi_relay.{local,gcp}`. The `relay-gcp` extra now pulls `kiapi-relay[gcp]`.
+- User-directory resolution and single-instance locking are delegated to the shared `kiarina-utils-app` package and used directly (`kiarina.utils.app`) rather than through a `core.app` re-export layer, removing the private `AppSettings`/user-directory copy and the direct `platformdirs` dependency. `kiapi.core.app` now provides only the `AppContext` schema. The app identity is set by calling `kiarina.utils.app.configure("kiapi", "kiarina")` at the CLI entry (`kiapi ...`) and the ASGI factory used by hot reload. The directory getters return `pathlib.Path`. The user `settings.yaml` section for these settings moves from `kiapi.core.app` to `kiarina.utils.app`, and the override environment variables move from `KIAPI_` to `KIARINA_UTILS_APP_`.
+
+## [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
+
+- Initial release.
+- Added release automation with mise tasks for version bumps, changelog updates, changelog extraction, package builds, and PyPI publishing.
+- Added a tag-driven GitHub Actions release workflow that builds distributions, creates GitHub Releases from `CHANGELOG.md`, and publishes to PyPI.
+- Added pull request and main-branch CI for tests, formatting/linting, documentation generation, and package builds.
+- Added contribution and security policy documentation for public OSS use.
+- Added PyPI classifiers and keywords to improve package metadata.
+- Made PyPI publishing failures fail the release workflow instead of being ignored.
+
+### Changed
+
+- Updated GitHub Actions CI and release jobs from `macos-14` to `macos-15`.
+
+### Fixed
+
+- Declared `uv` in `mise.toml` so GitHub Actions installs it before running `uv sync`.
+- Moved PyPI publishing to a Linux runner while keeping macOS release checks and builds.

kiapi-0.5.0/Makefile

@@ -0,0 +1,19 @@
+.PHONY: format lint test build clean check
+.DEFAULT_GOAL := check
+
+# Package-scoped tasks. mise resolves the package from this directory through
+# package:current, so the package name does not need to be passed explicitly.
+format:
+	mise run format
+lint:
+	mise run lint
+test:
+	mise run test
+build:
+	mise run build
+clean:
+	mise run clean
+check:
+	mise run format
+	mise run lint
+	mise run test

kiapi-0.5.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: kiapi
+Version: 0.5.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
+Project-URL: Documentation, https://kiarina.github.io/kiapi/
+Project-URL: Changelog, https://github.com/kiarina/kiapi/blob/main/packages/kiapi/CHANGELOG.md
+Author-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,api,apple-silicon,fastapi,local-inference,mlx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.12
+Requires-Dist: click
+Requires-Dist: fastapi<0.137
+Requires-Dist: httpx
+Requires-Dist: kiapi-relay
+Requires-Dist: kiarina-utils-app>=2.3.0
+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
+Requires-Dist: mlx-vlm==0.6.3
+Requires-Dist: numpy<2.5
+Requires-Dist: pillow
+Requires-Dist: psutil
+Requires-Dist: pydantic-settings-manager>=3.8.0
+Requires-Dist: pydantic>=2
+Requires-Dist: python-multipart
+Requires-Dist: pyyaml
+Requires-Dist: questionary
+Requires-Dist: soundfile>=0.13.1
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: torchvision
+Requires-Dist: uvicorn[standard]
+Provides-Extra: relay-gcp
+Requires-Dist: kiapi-relay[gcp]; extra == 'relay-gcp'
+Description-Content-Type: text/markdown
+
+# kiapi
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+![Python](https://img.shields.io/badge/Python-3.12-blue.svg)
+![Platform](https://img.shields.io/badge/Platform-Apple%20Silicon-lightgrey.svg)
+[![API Docs](https://img.shields.io/badge/API%20Docs-GitHub%20Pages-green.svg)](https://kiarina.github.io/kiapi/)
+
+**English** | [日本語](README.ja.md)
+
+## Summary
+
+kiapi is a local API server that uses Apple Silicon and MLX to provide generative AI capabilities for LLM agents.
+
+## API
+
+| Domain | Family | Endpoint | Description |
+|---|---|---|---|
+| chat |  | `POST /v1/chat` | [Chat API details](./kiapi/capabilities/chat/README.md) |
+| embedding |  | `POST /v1/embedding` | [Embedding API details](./kiapi/capabilities/embedding/README.md) |
+| image | zimage | `POST /v1/image/zimage` | [Z-Image API details](./kiapi/capabilities/zimage/README.md) |
+|  | flux2 | `POST /v1/image/flux2` | [FLUX.2 API details](./kiapi/capabilities/flux2/README.md) |
+|  | qwen | `POST /v1/image/qwen` | [Qwen Image API details](./kiapi/capabilities/qwen/README.md) |
+|  | ideogram4 | `POST /v1/image/ideogram4` | [Ideogram 4 API details](./kiapi/capabilities/ideogram4/README.md) |
+|  | ernie | `POST /v1/image/ernie` | [ERNIE-Image API details](./kiapi/capabilities/ernie/README.md) |
+|  | seedvr2 | `POST /v1/image/seedvr2` | [SeedVR2 API details](./kiapi/capabilities/seedvr2/README.md) |
+|  | depthpro | `POST /v1/image/depthpro` | [Depth Pro API details](./kiapi/capabilities/depthpro/README.md) |
+| audio | acestep | `POST /v1/audio/acestep` | [ACE-Step API details](./kiapi/capabilities/acestep/README.md) |
+|  | audiogen | `POST /v1/audio/audiogen` | [AudioGen API details](./kiapi/capabilities/audiogen/README.md) |
+| video | ltx2 | `POST /v1/video/ltx2` | [LTX-2 API details](./kiapi/capabilities/ltx2/README.md) |
+| web |  | `POST /v1/web` | [Web API details](./kiapi/capabilities/web/README.md) |
+| core | files | `POST /v1/files` | Upload input files, LoRA adapters, and other files, then issue a `file_id`. |
+|  |  | `GET /v1/files` | Return a list of stored files. |
+|  |  | `GET /v1/files/{file_id}` | Return file metadata. |
+|  |  | `GET /v1/files/{file_id}/download` | Download the file body. |
+|  |  | `DELETE /v1/files/{file_id}` | Delete a stored file. |
+|  | jobs | `GET /v1/jobs` | Return a list of generation jobs. |
+|  |  | `GET /v1/jobs/{job_id}` | Return job status, progress, result, and artifact `file_id`s. |
+|  |  | `DELETE /v1/jobs/{job_id}` | Remove a job from the job store. Running jobs are not interrupted. |
+|  | openapi | `GET /openapi.json` | Return the common API and each capability documentation URL. |
+|  |  | `GET /v1/{domain}/{family}/openapi.json` | Return detailed input/output specs, usage, tips, and examples for each family. |
+|  | health | `GET /health` | Return server status, warmup status, queue length, and memory usage. |
+
+See: [kiapi API Docs](https://kiarina.github.io/kiapi/)
+
+## Requirements
+
+- macOS / Apple Silicon
+- Python `>=3.12,<3.13`
+- `uv` (optional, recommended for isolated CLI installs and faster venv/package setup in `kiapi activate`)
+- `mise` (used for development)
+- Docker (when using the Web capability)
+- Enough disk capacity for model weights and Docker images
+
+kiapi is developed mainly for personal use on a **Mac Studio M4 Max 128GB**.
+Some or all features may work on other Apple Silicon environments, but they are
+not the primary verification target.
+
+The memory budget can be specified with `KIAPI_MEMORY_LIMIT_GB`. If omitted,
+kiapi automatically uses 80% of installed memory as the effective budget on
+startup. If a model's required memory does not fit in that budget, requests
+return 503 as an insufficient memory budget error.
+
+`kiapi activate --all` uses a little under 600GB of disk capacity, including
+model weights and Docker images. At first, it is recommended to use `kiapi activate`
+to set up only the capabilities you need.
+
+## 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_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+
+# Uses Application Default Credentials by default.
+kiapi run --relay gcp
+```
+
+Each node generates its own `node_id` on first start, persists it in the user
+data directory, and publishes a liveness heartbeat under `liveness`.
+A requester picks the most recently seen node and writes
+`sessions/{session_id}/request.json` in GCS, then writes a notification
+to `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 session-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/src/kiapi_relay/impl/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_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.
+
+## Local Storage
+
+kiapi mainly writes to these local paths at runtime.
+
+| Purpose | Setting | Default | Notes |
+|---|---|---|---|
+| Files API uploads, generated artifacts, and URL/data URL inputs | `KIAPI_FILES_ROOT` | `/tmp/kiapi/files` | Storage referenced by `file_id`. The default may disappear after OS reboot or tmp cleanup. Use `~/.kiapi/files` or external storage for long-term retention. |
+| Temporary working directories during request processing | `KIAPI_TMP_ROOT` | `/tmp/kiapi/work` | Used for chat/embedding input expansion, generation intermediates, LoRA training work, and similar tasks. |
+| Web backend subprocess logs | `KIAPI_WEB_BACKEND_LOG_DIR` | `/tmp/kiapi/logs/web` | stdout/stderr for SearXNG / Crawl4AI Docker subprocesses. |
+| ACE-Step dedicated venv / project / checkpoints | `KIAPI_ACESTEP_PYTHON_PATH`, `KIAPI_ACESTEP_PROJECT_ROOT`, `KIAPI_ACESTEP_CHECKPOINT_DIR` | `acestep/` under the user data dir | When `python_path`, `project_root`, and `checkpoint_dir` are omitted, kiapi places the ACE-Step venv and checkpoints under a persistent ACE-Step directory. |
+
+Other model weights and library caches are managed by Hugging Face, mflux,
+Docker, or each library/tool. kiapi generally does not move them into its own
+storage location.
+
+## Security
+
+By default, `kiapi run` starts on `127.0.0.1:8000`.
+When `--host 0.0.0.0` is specified, the server may be reachable from other
+machines, so use it only on trusted networks.

kiapi-0.5.0/README.ja.md

@@ -0,0 +1,144 @@
+# kiapi
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+![Python](https://img.shields.io/badge/Python-3.12-blue.svg)
+![Platform](https://img.shields.io/badge/Platform-Apple%20Silicon-lightgrey.svg)
+[![API Docs](https://img.shields.io/badge/API%20Docs-GitHub%20Pages-green.svg)](https://kiarina.github.io/kiapi/)
+
+[English](README.md) | **日本語**
+
+## Summary
+
+kiapi は、Apple Silicon と MLX を活用し、LLM エージェントに生成 AI 機能を提供するローカル API サーバーです。
+
+## API
+
+| Domain | Family | Endpoint | Description |
+|---|---|---|---|
+| chat |  | `POST /v1/chat` | [Chat API の詳細はこちら](./kiapi/capabilities/chat/README.ja.md) |
+| embedding |  | `POST /v1/embedding` | [Embedding API の詳細はこちら](./kiapi/capabilities/embedding/README.ja.md) |
+| image | zimage | `POST /v1/image/zimage` | [Z-Image API の詳細はこちら](./kiapi/capabilities/zimage/README.ja.md) |
+|  | flux2 | `POST /v1/image/flux2` | [FLUX.2 API の詳細はこちら](./kiapi/capabilities/flux2/README.ja.md) |
+|  | qwen | `POST /v1/image/qwen` | [Qwen Image API の詳細はこちら](./kiapi/capabilities/qwen/README.ja.md) |
+|  | ideogram4 | `POST /v1/image/ideogram4` | [Ideogram 4 API の詳細はこちら](./kiapi/capabilities/ideogram4/README.ja.md) |
+|  | ernie | `POST /v1/image/ernie` | [ERNIE-Image API の詳細はこちら](./kiapi/capabilities/ernie/README.ja.md) |
+|  | seedvr2 | `POST /v1/image/seedvr2` | [SeedVR2 API の詳細はこちら](./kiapi/capabilities/seedvr2/README.ja.md) |
+|  | depthpro | `POST /v1/image/depthpro` | [Depth Pro API の詳細はこちら](./kiapi/capabilities/depthpro/README.ja.md) |
+| audio | acestep | `POST /v1/audio/acestep` | [ACE-Step API の詳細はこちら](./kiapi/capabilities/acestep/README.ja.md) |
+|  | audiogen | `POST /v1/audio/audiogen` | [AudioGen API の詳細はこちら](./kiapi/capabilities/audiogen/README.ja.md) |
+| video | ltx2 | `POST /v1/video/ltx2` | [LTX-2 API の詳細はこちら](./kiapi/capabilities/ltx2/README.ja.md) |
+| web |  | `POST /v1/web` | [Web API の詳細はこちら](./kiapi/capabilities/web/README.ja.md) |
+| core | files | `POST /v1/files` | 入力ファイルや LoRA adapter などをアップロードし、`file_id` を発行する。 |
+|  |  | `GET /v1/files` | 保存済みファイルの一覧を返す。 |
+|  |  | `GET /v1/files/{file_id}` | ファイルメタデータを返す。 |
+|  |  | `GET /v1/files/{file_id}/download` | ファイル本体をダウンロードする。 |
+|  |  | `DELETE /v1/files/{file_id}` | 保存済みファイルを削除する。 |
+|  | jobs | `GET /v1/jobs` | 生成ジョブの一覧を返す。 |
+|  |  | `GET /v1/jobs/{job_id}` | ジョブの状態、進捗、結果、成果物 `file_id` を返す。 |
+|  |  | `DELETE /v1/jobs/{job_id}` | ジョブストアからジョブを削除する。実行中ジョブは中断されない。 |
+|  | openapi | `GET /openapi.json` | 共通 API と各 capability のドキュメント URL を返す。 |
+|  |  | `GET /v1/{domain}/{family}/openapi.json` | 各 family の詳細な入出力仕様、使い方、TIPS、例を返す。 |
+|  | health | `GET /health` | サーバー状態、warmup、キュー長、メモリ使用状況を返す。 |
+
+See: [kiapi API Docs](https://kiarina.github.io/kiapi/)
+
+## Requirements
+
+- macOS / Apple Silicon
+- Python `>=3.12,<3.13`
+- `uv`（任意。CLI tool として隔離インストールしたい場合や、`kiapi activate` が行う venv 作成・package install を高速化したい場合に推奨）
+- `mise`（開発で使用）
+- Docker（Web capability を使う場合）
+- モデル重みや Docker image を保存するための十分なディスク容量
+
+kiapi は主に **Mac Studio M4 Max 128GB** での個人利用を想定して開発しています。
+他の Apple Silicon 環境でも一部または全部の機能が動作する可能性はありますが、
+主な検証対象ではありません。
+
+メモリ予算は `KIAPI_MEMORY_LIMIT_GB` で明示指定できます。未指定の場合は、
+起動時に搭載メモリの 80% を自動で実効予算にします。モデルの必要メモリが
+この予算に収まらない場合、リクエストはメモリ予算不足として 503 を返します。
+
+`kiapi activate --all` は、モデル重みや Docker image を含めて
+600GB 弱のディスク容量を使用します。最初は必要な capability だけを
+`kiapi activate` で選択してセットアップすることをおすすめします。
+
+## 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_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+
+# 既定では Application Default Credentials を使用
+kiapi run --relay gcp
+```
+
+各 node は初回起動時に自分の `node_id` を生成して user data directory に永続化し、
+`liveness` 以下へ liveness heartbeat を publish します。requester は最も新しく
+観測された node を選び、GCS の `sessions/{session_id}/request.json` を書き込んだ
+後、RTDB の `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 日後に削除する session 限定 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/src/kiapi_relay/impl/gcp/README.ja.md) を参照してください。
+
+GCP を使わずに relay を検証したい場合は `local` を使えます。同じ process 内 dispatch
+経路を使い、通知と payload をローカルディレクトリ配下に保存します。
+
+```sh
+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 に保存します。
+
+## Local Storage
+
+kiapi が実行中にローカルへ書き込む主な場所は次の通りです。
+
+| 用途 | 設定 | 既定値 | 備考 |
+|---|---|---|---|
+| Files API のアップロード・生成成果物・URL/data URL 入力 | `KIAPI_FILES_ROOT` | `/tmp/kiapi/files` | `file_id` で参照される保存先。既定では OS の再起動や tmp cleanup で消える可能性があります。長期保存したい場合は `~/.kiapi/files` や外部ディスクに変更してください。 |
+| リクエスト処理中の一時作業ディレクトリ | `KIAPI_TMP_ROOT` | `/tmp/kiapi/work` | chat/embedding の入力展開、生成前の中間ファイル、LoRA 学習作業など。 |
+| Web backend subprocess log | `KIAPI_WEB_BACKEND_LOG_DIR` | `/tmp/kiapi/logs/web` | SearXNG / Crawl4AI Docker subprocess の stdout/stderr。 |
+| ACE-Step 専用 venv / project / checkpoints | `KIAPI_ACESTEP_PYTHON_PATH`, `KIAPI_ACESTEP_PROJECT_ROOT`, `KIAPI_ACESTEP_CHECKPOINT_DIR` | user data dir 配下の `acestep/` | `python_path`, `project_root`, `checkpoint_dir` が未指定の場合、ACE-Step 用の永続ディレクトリに venv と checkpoint を配置します。 |
+
+上記を除くモデル重みやライブラリキャッシュは Hugging Face、mflux、Docker など
+各ライブラリ・ツールの管理下に置き、kiapi は原則として独自の保存先へ移しません。
+
+## Security
+
+既定では `kiapi run` は `127.0.0.1:8000` で起動します。
+`--host 0.0.0.0` を指定すると他のマシンから到達できる可能性があるため、
+信頼できるネットワーク内でのみ使用してください。

kiapi-0.5.0/README.md

@@ -0,0 +1,150 @@
+# kiapi
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+![Python](https://img.shields.io/badge/Python-3.12-blue.svg)
+![Platform](https://img.shields.io/badge/Platform-Apple%20Silicon-lightgrey.svg)
+[![API Docs](https://img.shields.io/badge/API%20Docs-GitHub%20Pages-green.svg)](https://kiarina.github.io/kiapi/)
+
+**English** | [日本語](README.ja.md)
+
+## Summary
+
+kiapi is a local API server that uses Apple Silicon and MLX to provide generative AI capabilities for LLM agents.
+
+## API
+
+| Domain | Family | Endpoint | Description |
+|---|---|---|---|
+| chat |  | `POST /v1/chat` | [Chat API details](./kiapi/capabilities/chat/README.md) |
+| embedding |  | `POST /v1/embedding` | [Embedding API details](./kiapi/capabilities/embedding/README.md) |
+| image | zimage | `POST /v1/image/zimage` | [Z-Image API details](./kiapi/capabilities/zimage/README.md) |
+|  | flux2 | `POST /v1/image/flux2` | [FLUX.2 API details](./kiapi/capabilities/flux2/README.md) |
+|  | qwen | `POST /v1/image/qwen` | [Qwen Image API details](./kiapi/capabilities/qwen/README.md) |
+|  | ideogram4 | `POST /v1/image/ideogram4` | [Ideogram 4 API details](./kiapi/capabilities/ideogram4/README.md) |
+|  | ernie | `POST /v1/image/ernie` | [ERNIE-Image API details](./kiapi/capabilities/ernie/README.md) |
+|  | seedvr2 | `POST /v1/image/seedvr2` | [SeedVR2 API details](./kiapi/capabilities/seedvr2/README.md) |
+|  | depthpro | `POST /v1/image/depthpro` | [Depth Pro API details](./kiapi/capabilities/depthpro/README.md) |
+| audio | acestep | `POST /v1/audio/acestep` | [ACE-Step API details](./kiapi/capabilities/acestep/README.md) |
+|  | audiogen | `POST /v1/audio/audiogen` | [AudioGen API details](./kiapi/capabilities/audiogen/README.md) |
+| video | ltx2 | `POST /v1/video/ltx2` | [LTX-2 API details](./kiapi/capabilities/ltx2/README.md) |
+| web |  | `POST /v1/web` | [Web API details](./kiapi/capabilities/web/README.md) |
+| core | files | `POST /v1/files` | Upload input files, LoRA adapters, and other files, then issue a `file_id`. |
+|  |  | `GET /v1/files` | Return a list of stored files. |
+|  |  | `GET /v1/files/{file_id}` | Return file metadata. |
+|  |  | `GET /v1/files/{file_id}/download` | Download the file body. |
+|  |  | `DELETE /v1/files/{file_id}` | Delete a stored file. |
+|  | jobs | `GET /v1/jobs` | Return a list of generation jobs. |
+|  |  | `GET /v1/jobs/{job_id}` | Return job status, progress, result, and artifact `file_id`s. |
+|  |  | `DELETE /v1/jobs/{job_id}` | Remove a job from the job store. Running jobs are not interrupted. |
+|  | openapi | `GET /openapi.json` | Return the common API and each capability documentation URL. |
+|  |  | `GET /v1/{domain}/{family}/openapi.json` | Return detailed input/output specs, usage, tips, and examples for each family. |
+|  | health | `GET /health` | Return server status, warmup status, queue length, and memory usage. |
+
+See: [kiapi API Docs](https://kiarina.github.io/kiapi/)
+
+## Requirements
+
+- macOS / Apple Silicon
+- Python `>=3.12,<3.13`
+- `uv` (optional, recommended for isolated CLI installs and faster venv/package setup in `kiapi activate`)
+- `mise` (used for development)
+- Docker (when using the Web capability)
+- Enough disk capacity for model weights and Docker images
+
+kiapi is developed mainly for personal use on a **Mac Studio M4 Max 128GB**.
+Some or all features may work on other Apple Silicon environments, but they are
+not the primary verification target.
+
+The memory budget can be specified with `KIAPI_MEMORY_LIMIT_GB`. If omitted,
+kiapi automatically uses 80% of installed memory as the effective budget on
+startup. If a model's required memory does not fit in that budget, requests
+return 503 as an insufficient memory budget error.
+
+`kiapi activate --all` uses a little under 600GB of disk capacity, including
+model weights and Docker images. At first, it is recommended to use `kiapi activate`
+to set up only the capabilities you need.
+
+## 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_DATABASE_URL="https://PROJECT.firebaseio.com"
+export KIAPI_RELAY_GCP_BUCKET="PRIVATE_RELAY_BUCKET"
+
+# Uses Application Default Credentials by default.
+kiapi run --relay gcp
+```
+
+Each node generates its own `node_id` on first start, persists it in the user
+data directory, and publishes a liveness heartbeat under `liveness`.
+A requester picks the most recently seen node and writes
+`sessions/{session_id}/request.json` in GCS, then writes a notification
+to `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 session-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/src/kiapi_relay/impl/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_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.
+
+## Local Storage
+
+kiapi mainly writes to these local paths at runtime.
+
+| Purpose | Setting | Default | Notes |
+|---|---|---|---|
+| Files API uploads, generated artifacts, and URL/data URL inputs | `KIAPI_FILES_ROOT` | `/tmp/kiapi/files` | Storage referenced by `file_id`. The default may disappear after OS reboot or tmp cleanup. Use `~/.kiapi/files` or external storage for long-term retention. |
+| Temporary working directories during request processing | `KIAPI_TMP_ROOT` | `/tmp/kiapi/work` | Used for chat/embedding input expansion, generation intermediates, LoRA training work, and similar tasks. |
+| Web backend subprocess logs | `KIAPI_WEB_BACKEND_LOG_DIR` | `/tmp/kiapi/logs/web` | stdout/stderr for SearXNG / Crawl4AI Docker subprocesses. |
+| ACE-Step dedicated venv / project / checkpoints | `KIAPI_ACESTEP_PYTHON_PATH`, `KIAPI_ACESTEP_PROJECT_ROOT`, `KIAPI_ACESTEP_CHECKPOINT_DIR` | `acestep/` under the user data dir | When `python_path`, `project_root`, and `checkpoint_dir` are omitted, kiapi places the ACE-Step venv and checkpoints under a persistent ACE-Step directory. |
+
+Other model weights and library caches are managed by Hugging Face, mflux,
+Docker, or each library/tool. kiapi generally does not move them into its own
+storage location.
+
+## Security
+
+By default, `kiapi run` starts on `127.0.0.1:8000`.
+When `--host 0.0.0.0` is specified, the server may be reachable from other
+machines, so use it only on trusted networks.