open-genie-server 1.0.0__tar.gz

open_genie_server-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tadayuki OKADA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

open_genie_server-1.0.0/MANIFEST.in

@@ -0,0 +1,20 @@
+# What an sdist gets beyond the package itself. The wheel is unaffected —
+# it ships src/genie_server/ and nothing else.
+#
+# README.md links into docs/ and examples/, and the launcher is how the device
+# starts the server, so a source tarball without them is not the source.
+include LICENSE
+include README.md
+include README.ja.md
+include SECURITY.md
+include SECURITY.ja.md
+include requirements.txt
+include genie-server.py
+recursive-include docs *.md
+recursive-include examples *.md *.json *.py *.sh *.txt
+recursive-include tests *.py *.md *.json
+
+# Never ship someone else's board, or bytecode.
+exclude tests/integration/test_config.json
+global-exclude *.pyc
+global-exclude __pycache__

open_genie_server-1.0.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: open-genie-server
+Version: 1.0.0
+Summary: OpenAI-compatible REST API server for Qualcomm Genie (libGenie.so) on the Hexagon NPU
+Author: Tadayuki OKADA
+Project-URL: Homepage, https://github.com/TadayukiOkada/open-genie-server
+Project-URL: Documentation, https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md
+Project-URL: Changelog, https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/CHANGELOG.md
+Keywords: qualcomm,genie,qairt,hexagon,npu,openai,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Android
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: tokenizers
+Provides-Extra: logprobs
+Requires-Dist: numpy; extra == "logprobs"
+Provides-Extra: vlm
+Requires-Dist: numpy; extra == "vlm"
+Requires-Dist: pillow; extra == "vlm"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Requires-Dist: requests; extra == "test"
+Requires-Dist: jsonschema; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Dynamic: license-file
+
+# open-genie-server
+
+*English | [日本語](https://github.com/TadayukiOkada/open-genie-server/blob/master/README.ja.md)*
+
+A single-process FastAPI server that exposes the Qualcomm Genie C API (`libGenie.so`) as an OpenAI-compatible REST API. It lets you drive LLMs running on a [Hexagon NPU](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#glossary) — Qualcomm's name for the accelerator this server talks to through the QNN HTP backend — from ordinary OpenAI-compatible HTTP clients — `lm_eval`, `curl`, the OpenAI SDK, [Open WebUI](https://github.com/open-webui/open-webui), and so on. The implementation lives in the `genie_server` package (`src/genie_server/`); `genie-server.py` is the launcher.
+
+> [!IMPORTANT]
+> This repository contains only the open-genie-server source itself. To run it you also need the **QAIRT SDK** from Qualcomm (a toolchain distributed under Qualcomm's proprietary license, containing `libGenie.so`) and a model compiled for a Hexagon NPU (a model directory containing `genie_config.json`). Neither the SDK nor any models are included in this repository — obtain them separately from [Qualcomm AI Hub](https://aihub.qualcomm.com/) or similar.
+
+See [MANUAL.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md) for configuration and behaviour, [API.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/API.md) for the endpoint reference, and [Platform Notes](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/PLATFORM_NOTES.md) for what every measured number here assumes about the device it was measured on.
+
+## What this is for
+
+**A bench instrument for the Genie C API and for quantized model bundles — not a production inference server.** Everything else follows from that, in this order:
+
+1. **Reach as much of the Genie C API as the API allows.** Not just chat: SDK-side profiling counters, performance policies, prompt scoring through the custom-sampler hook, LoRA, prefix-cache snapshots, and the composable `GenieNode`/`GeniePipeline` path behind VLM slots are all reachable over HTTP, because the point is to exercise them.
+2. **Make standard benchmarks easy to point at a device.** `lm_eval` works against an unmodified install, generation and loglikelihood tasks alike, and [examples/bfcl](https://github.com/TadayukiOkada/open-genie-server/tree/master/examples/bfcl) drives the Berkeley Function Calling Leaderboard the same way. A benchmark that needs the server patched is a benchmark you will not run.
+3. **Do not hide the SDK's or the model's problems by default.** A defect you cannot see is one you will ship. So the stock-library slot wedge is neither detected nor papered over; grammar's leaked terminal token is reported rather than stripped; a response names the model actually loaded instead of echoing the string the client sent; and the prefix cache fills only on an explicit warmup, so it cannot quietly improve a TTFT measurement. Workarounds exist, but they are switches you turn on knowing what they conceal — `TOOL_CALL_RECOVERY`, which reassembles a tool call whose marker the model mangled, is off until you ask for it.
+4. **Stay compatible with the OpenAI API, and with what other inference servers do — where that does not conflict with 3.** Where the two disagree, this server reports what happened. The `model` field above is the worked example: OpenAI and vLLM echo the request, and this server does not, because a benchmark that ran against a hot-swapped model should say so.
+
+**Backward compatibility is not one of these.** Nothing gets broken for the sake of it, and a change to an existing response shape or default is called out under Breaking in the [CHANGELOG](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/CHANGELOG.md). But this server is a view onto the Genie C API, and when that API moves, this follows — keeping an old shape alive to spare an existing caller would make the instrument lie about what the SDK now does. The same goes for our own defaults: a measurement showing that one of them hides something is reason enough to change it. If you need a surface that holds still, pin a version.
+
+**What it is not.** There is no authentication, no rate limiting and no multi-process scaling, `POST /v1/models/switch` will open any path the process can read, and one text slot serializes its requests behind a single `GenieDialog` handle. Run it on a bench network you control ([SECURITY.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/SECURITY.md) says what that means, and what is worth reporting). If you need a production serving stack on Hexagon, this is the wrong starting point — but it will tell you, in detail, what your bundle and your SDK actually do.
+
+## Features
+
+- `/v1/completions` / `/v1/chat/completions` — OpenAI-compatible text/chat completion (streaming supported; also registered without the `/v1` prefix)
+- **Function calling (`tools`)** — Hermes-format tool calling for Qwen3-class models: `<tool_call>` output is parsed into OpenAI `message.tool_calls` / `finish_reason: "tool_calls"`, held back correctly during streaming
+- Works out of the box with `lm_eval` (`local-completions` / `local-chat-completions`; token-id prompts are decoded server-side)
+- **Logprobs** via the SDK's custom-sampler hook: per-token `logprobs`/`top_logprobs` for generated tokens (a few ms/token overhead, zero when unused), and **prompt scoring** (`echo`+`logprobs` teacher forcing) that makes lm_eval loglikelihood tasks (hellaswag, arc, mmlu, ...) work — gated behind `POST /v1/server/prompt_logprobs` since it runs at decode speed
+- Open WebUI-friendly: parts-array `content` flattening, `GET /health`, CORS, streaming `usage` chunks (`stream_options.include_usage`)
+- Prefix KV cache for system prompts (namespaced per model/LoRA)
+- LoRA adapter hot-swapping via `GenieDialog_applyLora` etc. — apply, strength, release and read-back, verified on hardware
+- Model hot-swapping via `/v1/models/switch` (by default the old model is freed before the new one loads, which is the order that switches reliably; a failed load then leaves the slot empty. `"unload_first": false` keeps the old model as a fallback by holding both at once — see the caveat below before using it)
+- `Genie_PerformancePolicy_t` switching (e.g. pin to `burst` for benchmarking)
+- Non-blocking status monitoring, including context occupancy (KV cache usage)
+- **SDK-side profiling** — `GENIE_PROFILE` exposes Genie's own TTFT / prefill / decode KPIs on `GET /v1/server/profile`, without touching the OpenAI response shapes
+- **Multi text-slot support** — `TEXT_SLOTS` lets you assign an independent `GenieDialog` handle (its own lock, optionally its own model) to each Hexagon NSP core you can use (cdsp0/cdsp1; see the [Glossary](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#glossary) if HTP/NSP/cDSP/NPU are unfamiliar). Requests to different slots do overlap, but the measured gain on our bench was **~1.3×, not 2×** (see [Multi Text Slots](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#multi-text-slots)). **How many cores you may use is licensed per SKU, not implied by the part number** — see [Platform Notes](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/PLATFORM_NOTES.md)
+- **Grammar-constrained decoding** — constrain output with JSON Schema/regex/EBNF (XGrammar backend, fixed per model/slot)
+- **VLM (multimodal) support** — image-input models such as Qwen3-VL that use the `GenieNode`/`GeniePipeline` composable pipeline API can be added via `VLM_SLOTS`, entirely in parallel with `TEXT_SLOTS` (see [examples/vlm](https://github.com/TadayukiOkada/open-genie-server/tree/master/examples/vlm))
+- Offline test suite (`tests/`, pytest + a fake SDK) — the whole HTTP/engine/template stack runs without an NPU
+
+## Requirements
+
+- Python 3.10+ (uses `int | None`-style type syntax)
+- The QAIRT SDK (`libGenie.so` and its dependencies) and a model that runs on the Hexagon NPU (see the note above)
+
+```bash
+pip install .[logprobs,vlm]     # everything
+pip install .                   # server only: fastapi, uvicorn, tokenizers
+```
+
+The distribution is named `open-genie-server`; the package you import is
+`genie_server`. `pip install -r requirements.txt` still works and is the same
+as the first line above.
+
+| | in | why |
+|---|---|---|
+| `fastapi`, `uvicorn` | core | the server |
+| `tokenizers` | core | accurate token counts. Without it, counts come from `text.split()`, so a 55-token Japanese paragraph counts as 1 — and that feeds the context check and the default `max_tokens`, not just the reported usage. See [Token counting](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#token-counting) |
+| `numpy` | `[logprobs]`, `[vlm]` | **logprobs and prompt scoring**, and VLM. Without it those requests are rejected with HTTP 400 |
+| `pillow` | `[vlm]` | image input |
+| `pytest`, `httpx`, `requests`, `jsonschema` | `[test]` | the offline suite |
+
+Installing the package also gives you a `genie-server` command; the
+repository-root `genie-server.py` launcher does the same thing and needs no
+install. On Android three of these publish no wheel — see
+[Running on Android](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#running-on-android).
+
+> [!WARNING]
+> **Check which QAIRT version you are pointing at before deploying.** Which SDK
+> defects you inherit depends on that version, and **every 2.49.x we have tested
+> carries three of them in one place: what `GenieDialog_reset()` fails to put
+> back.** A server resets between requests to keep them independent, so that is
+> the path under every request you serve.
+>
+> You would see one oversized request wedging a slot for good; a long request
+> failing on an empty context because the one before it was shorter; or, on a
+> bundle built for speculative decoding, every answer after the first reset
+> coming back fluent and wrong. **All three report success.**
+>
+> **[QAIRT Version Issues](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/QAIRT_VERSIONS.md)** has the per-version
+> matrix, [a check you can run against your own SDK](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/QAIRT_VERSIONS.md#checking-your-own-sdk),
+> and how to choose a library. A version not listed there is one we have not
+> tested, not one we know to be clean.
+
+## Quick start
+
+> [!NOTE]
+> The examples in this section reach the device at `192.168.1.2:8080`. That
+> address is not special to this server — it is the default the SA8255P's LV GVM
+> comes up with, and it is what our own bench uses, so it appears throughout the
+> docs and in `tests/integration/test_config.sample.json`. Replace it with your
+> device's address (or `localhost` if you are running the server and the client
+> on the same machine).
+
+1. Place an `env_config.json` in the server's startup (current) directory.
+
+   ```json
+   {
+     "QAIRT_SDK_ROOT": "/path/to/qairt-dir",
+     "HEXAGON_VERSION": "v73",
+     "MODELS_BASE_DIR": "/path/to/models",
+     "PREFIX_CACHE_DIR": "/path/to/prefix_cache",
+     "TEXT_SLOTS": [{"model_root": "model-dir"}]
+   }
+   ```
+
+   `model_root` points at the directory containing `genie_config.json`. That is the only key a slot needs; `name` and `device_id` default.
+
+   A relative `model_root` resolves under `MODELS_BASE_DIR`, so the example above loads `/path/to/models/model-dir`. Absolute paths also work — see [Where model paths resolve](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#where-model-paths-resolve).
+
+   On a SoC with multiple NSP cores, add an entry per core to keep a model resident on each (see [MANUAL.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#multi-text-slots) for details, including the ordering rule — a second slot does not always fit):
+
+   ```json
+   {
+     "QAIRT_SDK_ROOT": "/path/to/qairt-dir",
+     "HEXAGON_VERSION": "v73",
+     "MODELS_BASE_DIR": "/path/to/models",
+     "PREFIX_CACHE_DIR": "/path/to/prefix_cache",
+     "TEXT_SLOTS": [
+       {"name": "tool_call", "device_id": 0, "model_root": "model-fast"},
+       {"name": "chat", "device_id": 1, "model_root": "model-general"}
+     ]
+   }
+   ```
+
+2. Start the server.
+
+   ```bash
+   python3 genie-server.py            # flags: --config/--host/--port
+   # or, if the package is installed
+   genie-server                       # same flags
+   # or under uvicorn directly
+   uvicorn genie_server.asgi:app --host 0.0.0.0 --port 8080 --workers 1
+   ```
+
+3. Sanity-check it:
+
+   ```bash
+   curl http://192.168.1.2:8080/v1/models
+
+   curl http://192.168.1.2:8080/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{"model":"genie-local","messages":[{"role":"user","content":"Hello"}]}'
+   ```
+
+See [examples/grammar](https://github.com/TadayukiOkada/open-genie-server/tree/master/examples/grammar) for a grammar-constrained decoding config example, [examples/vlm](https://github.com/TadayukiOkada/open-genie-server/tree/master/examples/vlm) for VLM (image input) setup and testing steps, and [examples/lm_eval](https://github.com/TadayukiOkada/open-genie-server/tree/master/examples/lm_eval) for running `lm_eval` against a board (including how to compare the result with the unquantized model).
+
+## Using it with lm_eval
+
+```bash
+lm_eval --model local-chat-completions \
+  --model_args model=genie-local,base_url=http://192.168.1.2:8080/v1,\
+tokenizer_backend=huggingface,tokenizer=<hf_model>,max_tokens=512,num_concurrent=1 \
+  --tasks mmlu_generative --apply_chat_template --batch_size 1
+```
+
+See [API.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/API.md) for the endpoint reference and [MANUAL.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md) for configuration.
+
+## Directory layout
+
+```
+genie-server.py       — launcher (CLI flags: --config/--host/--port)
+src/genie_server/     — the server implementation, one module per concern
+pyproject.toml        — packaging: dependencies, extras, the genie-server command
+requirements.txt      — kept as a pointer to pyproject.toml's dependencies
+SECURITY.md           — what is deliberately absent, and what to report (.ja.md)
+LICENSE
+
+tests/                — offline test suite (pytest; fake SDK, no NPU needed)
+tests/integration/    — host-side runner against a live device (MD/JSON reports)
+
+docs/MANUAL.md        — configuration, behaviour, and the why behind it (.ja.md)
+docs/API.md           — every endpoint, grouped by purpose (.ja.md)
+docs/PLATFORM_NOTES.md— what the measured numbers assume about a device (.ja.md)
+docs/QAIRT_VERSIONS.md— the SDK defects, per QAIRT version (.ja.md)
+docs/CHANGELOG.md     — release notes
+
+examples/config/      — env_config.json samples (single-slot / dual-NSP / VLM)
+examples/grammar/     — grammar-constrained decoding
+examples/vlm/         — VLM (multimodal) setup and testing steps
+examples/lm_eval/     — lm_eval, and comparing against the unquantized model
+examples/bfcl/        — the Berkeley Function Calling Leaderboard
+```
+
+The module-by-module breakdown of `src/genie_server/` is in
+[MANUAL.md § Architecture Overview](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#architecture-overview) rather than repeated
+here.
+
+Run the offline tests with:
+
+```bash
+pip install -e .[logprobs,vlm,test]
+python3 -m pytest tests/
+```
+
+The `[test]` dependencies are not optional for a green run: without `requests`
+and `jsonschema` eight grammar tests fail with `ModuleNotFoundError`, and
+without `numpy` eight logprobs tests do. The same suite runs on every push and
+pull request against Python 3.10 and 3.12
+(`.github/workflows/offline-tests.yml`).
+
+To exercise a real device end-to-end from the host PC (with a Markdown/JSON report and server-death detection), see [tests/integration/](https://github.com/TadayukiOkada/open-genie-server/tree/master/tests/integration).
+
+## Known limitations
+
+- **This server does not guard against the stock-library reset defects** described at the top of this page — it neither detects nor recovers from them. Avoiding them is a deployment choice: see [QAIRT Version Issues](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/QAIRT_VERSIONS.md).
+- **A bundle built for speculative decoding (`"dialog": {"type": "ssd-q1"}`) needs a patched library**, and cannot use LoRA without one. See [D5](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/QAIRT_VERSIONS.md#d5--reset-corrupts-a-speculative-decoding-dialog) for why, and for the one-line change to the bundle that avoids it.
+- One text slot = one `GenieDialog` handle; requests to a slot are serialized by that slot's own lock (with `TEXT_SLOTS` unset there's only a single slot, so every request is serialized, same as before).
+- `n > 1` (multiple completions per request) is not supported; it is rejected with a `400`.
+- The Llama2/Mistral template folds the system prompt into `[INST]`, so it's not eligible for prefix KV caching.
+- `POST /v1/models/switch` frees the old model before loading the new one by default, so a failed load leaves that slot with no model until a later switch succeeds; every endpoint that touches it returns `503` in the meantime.
+- `"unload_first": false` avoids that by holding both models on the slot's HTP device while the new one loads — but **on the SA8255P board that overlap is not dependable**. Over 36 measured swaps the outcome did not follow from which models were involved: one pair succeeded 6/6 in one run and failed 8/8 in another, and a run of six flipped from failing to succeeding halfway through. What decides it is device state the host cannot observe. Use it only where the device has memory to spare and the swaps your deployment actually performs have been tested there, repeatedly and from a cold start.
+- VLM slots are single-turn only (no conversation history), and don't support LoRA, prefix KV cache, grammar constraints, or hot-swapping. See [MANUAL.md](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#vlm-multimodal-support) for details.
+
+See [MANUAL.md's Limitations section](https://github.com/TadayukiOkada/open-genie-server/blob/master/docs/MANUAL.md#limitations) for the rest of the known limitations.
+
+## Acknowledgements
+
+Built with [Claude Code](https://claude.com/claude-code). The first commit here
+is dated 2026-08-19, and in the eleven days since, this went from a single
+2,700-line script to a packaged server with 311 offline tests, a hardware
+integration suite, and manuals in two languages.
+
+The code was never the slow part. What took the time was reading the QAIRT
+SDK's reference sources closely enough to tell an SDK defect from a bug of our
+own, reproducing each one on the board until it was certain which it was, and
+then writing down what had been measured rather than what had been assumed —
+several of the findings in these documents reverse an earlier conclusion that
+looked obvious at the time. Doing that at this pace, as one engineer, would not
+have been possible without it.
+
+## License
+
+[MIT](https://github.com/TadayukiOkada/open-genie-server/blob/master/LICENSE)
+
+This repository's license applies only to the open-genie-server source code itself. The Qualcomm QAIRT SDK, `libGenie.so`, and any Hexagon NPU models are not covered — they remain subject to Qualcomm's and each model's own distributor's license terms.
+
+**MIT was a choice, not a default.** A bench instrument is the kind of project
+people expect to find under a copyleft licence, so it is worth saying why this
+one is not. Two reasons, both specific to what this is. It loads a proprietary
+`libGenie.so` through ctypes at run time, and copyleft would put a
+combined-work question in front of anyone shipping a board image that carries
+both — a normal way to ship on this hardware, and not a question worth handing
+to someone's legal team before they can measure a model. And the useful thing
+to do with this code is take it apart: lift `logprobs.py` into your own
+evaluation harness, fork it for the one endpoint your board needs. A licence
+that taxes that is working against the point.

open_genie_server-1.0.0/README.ja.md

@@ -0,0 +1,244 @@
+# open-genie-server
+
+*[English](./README.md) | 日本語*
+
+Qualcomm Genie C API (`libGenie.so`) を OpenAI互換のREST APIとして公開する、単一プロセスのFastAPIサーバです。[Hexagon NPU](./docs/MANUAL.ja.md#用語集)(本サーバが QNN HTP バックエンド経由で使うアクセラレータの、Qualcomm での呼び名)上で動くLLMを、`lm_eval`・`curl`・OpenAI SDK・[Open WebUI](https://github.com/open-webui/open-webui)等、一般的なOpenAI互換HTTPクライアントから叩けるようにします。実装本体は `genie_server` パッケージ(`src/genie_server/`)にあり、`genie-server.py` はランチャーです。
+
+> [!IMPORTANT]
+> このリポジトリは open-genie-server 自体のソースのみを含みます。動作させるには別途、Qualcomm から **QAIRT SDK**(`libGenie.so` を含む、Qualcomm の proprietary licenseで配布されるツールチェーン)と、Hexagon NPU向けにコンパイル済みのモデル一式(`genie_config.json` を含むモデルディレクトリ)を用意する必要があります。SDK・モデルはこのリポジトリには含まれておらず、[Qualcomm AI Hub](https://aihub.qualcomm.com/) 等から別途取得してください。
+
+設定と挙動は [MANUAL.ja.md](./docs/MANUAL.ja.md)、エンドポイントのリファレンスは [API.ja.md](./docs/API.ja.md)、そして**本ドキュメントの実測値がデバイスについて何を前提にしているか**は [プラットフォーム別の注意点](./docs/PLATFORM_NOTES.ja.md) を参照してください。
+
+## このプロジェクトの目的
+
+**Genie C API と量子化済みモデルバンドルを検証するための計測器であって、本番用の推論サーバではありません。** 他のすべてはここから、この優先順位で導かれます:
+
+1. **Genie C API を、APIが許す限り広く使えるようにする。** チャットだけではありません。SDK側のプロファイリングカウンタ、パフォーマンスポリシー、カスタムサンプラーフック経由のプロンプトスコアリング、LoRA、prefixキャッシュのスナップショット、VLMスロットの背後にある `GenieNode`/`GeniePipeline` — これらすべてにHTTPから手が届きます。**触れるようにすること自体が目的**だからです。
+2. **標準的なベンチマークを、そのままデバイスに向けられるようにする。** `lm_eval` は無改造で通ります(生成タスクもloglikelihoodタスクも)。[examples/bfcl](./examples/bfcl) は Berkeley Function Calling Leaderboard を同じやり方で回します。**サーバに手を入れないと動かないベンチマークは、結局回さない**ものです。
+3. **SDKやモデルの問題を、既定では隠さない。** 見えない欠陥は、そのまま出荷される欠陥です。よって素のライブラリによるスロット恒久故障は検知も回避もしません。grammar が漏らす終端トークンは、取り除かずに報告します。応答が名乗るのは、クライアントが送ってきた文字列ではなく**実際にロードされているモデル**です。prefixキャッシュは明示的なウォームアップでしか埋まらないので、TTFTの計測を黙って改善してしまうことがありません。回避策はありますが、**何を隠すかを承知のうえで自分で入れるスイッチ**として用意してあります — マーカーが化けたツール呼び出しを組み立て直す `TOOL_CALL_RECOVERY` は、**自分で ON にするまで効きません**。
+4. **OpenAI API および他の主要な推論サーバの挙動との互換性を保つ — 3と衝突しない範囲で。** 両者が食い違うときは、実際に起きたことを報告する側を採ります。上に挙げた `model` フィールドがその実例です。OpenAI も vLLM もリクエストをそのまま返しますが、本サーバは返しません。**ホットスワップされたモデルで走ったベンチマークは、そう名乗るべき**だからです。
+
+**後方互換性はこの中に入りません。** 意味もなく壊すことはしませんし、既存の応答形式や既定値を変える変更は [CHANGELOG](./docs/CHANGELOG.md) の Breaking に明記します。ただし本サーバは **Genie C API を覗くための窓**であり、**その API が動けば、こちらも動きます** — 既存の呼び出し側を守るためだけに古い形を残すことは、SDK が今どうなっているかについて**計測器に嘘をつかせる**ことになります。**自分たちの既定値についても同じ**です。ある既定値が何かを隠していると実測で分かれば、それだけで変更の理由になります。**動かない表面が必要なら、バージョンを固定してください。**
+
+**目指していないもの。** 認証もレート制限もマルチプロセスのスケーリングもありません。`POST /v1/models/switch` はプロセスが読めるあらゆるパスを開きます。1つのテキストスロットは、単一の `GenieDialog` ハンドルの後ろでリクエストを直列化します。**自分で管理しているベンチ用ネットワークで動かしてください**([SECURITY.ja.md](./SECURITY.ja.md) に、それが何を意味するかと、報告してほしいことを書いてあります)。Hexagon上に本番のサービング基盤が要るなら、ここは出発点として間違っています — ただし、**あなたのバンドルとSDKが実際に何をしているかは、詳細に教えてくれます**。
+
+## 特徴
+
+- `/v1/completions`・`/v1/chat/completions` — OpenAI互換のテキスト/チャット補完(ストリーミング対応。`/v1` なしのパスにも登録)
+- **Function calling(`tools`)対応** — Qwen3系モデル向けのHermes形式ツール呼び出し。出力の `<tool_call>` をOpenAIの `message.tool_calls` / `finish_reason: "tool_calls"` に変換し、ストリーミング中は正しくホールドバック
+- `lm_eval`(`local-completions` / `local-chat-completions`)にそのまま対応。トークンID形式のプロンプトもサーバ側でデコード
+- **Logprobs対応**(SDKのカスタムサンプラーフック経由): 生成トークンの`logprobs`/`top_logprobs`(トークンあたり数msのオーバーヘッド、未使用時はゼロ)に加え、**プロンプトスコアリング**(`echo`+`logprobs`のteacher forcing)でlm_evalのloglikelihoodタスク(hellaswag, arc, mmlu等)も実行可能 — デコード速度で走るため`POST /v1/server/prompt_logprobs`によるゲート付き
+- Open WebUIフレンドリー — parts配列形式 `content` のフラット化、`GET /health`、CORS、ストリーミング `usage` チャンク(`stream_options.include_usage`)
+- システムプロンプトのprefix KVキャッシュ(モデル/LoRAごとにnamespace化)
+- `GenieDialog_applyLora` 等によるLoRAアダプタのホットスワップ — 適用・強度・解放・読み戻しとも**実機で確認済み**
+- `/v1/models/switch` によるモデルのホットスワップ(既定では旧モデルを解放してから新モデルをロードします。この順序が確実に切り替わりますが、ロードに失敗するとスロットは空になります。`"unload_first": false` は新旧を同時に載せることで旧モデルをフォールバックとして残せます — 使う前に下記の注意を参照)
+- `Genie_PerformancePolicy_t` の切り替え(ベンチマーク時に `burst` 固定など)
+- Context occupancy(KVキャッシュ占有量)を含む非ブロッキングなステータス監視
+- **SDK側プロファイリング** — `GENIE_PROFILE` で Genie 自身が計測した TTFT/プレフィル/デコードのKPIを `GET /v1/server/profile` から取得([プロファイリング](./docs/MANUAL.ja.md#プロファイリングsdk側のkpi)参照)。OpenAIのレスポンス形状は一切変更しない
+- **マルチテキストスロット対応** — `TEXT_SLOTS` 設定で、**使える**Hexagon NSPコア(cdsp0/cdsp1。HTP/NSP/cDSP/NPU の関係は[用語集](./docs/MANUAL.ja.md#用語集)参照)それぞれに独立した `GenieDialog` ハンドル(別ロック・別モデル可)を割り当て。別スロット宛のリクエストは実際に重なって進みますが、当方のベンチでの実測向上は **2倍ではなく約1.3倍**でした([マルチテキストスロット](./docs/MANUAL.ja.md#マルチテキストスロット)参照)。**何本使えるかは品番ではなくSKUのライセンスで決まります** — [プラットフォーム別の注意点](./docs/PLATFORM_NOTES.ja.md)参照
+- **Grammar制約デコーディング** — JSON Schema/正規表現/EBNFで出力を制約(XGrammarバックエンド、モデル/スロット単位の固定設定)
+- **VLM(マルチモーダル)対応** — Qwen3-VL等、`GenieNode`/`GeniePipeline` composable pipeline APIを使う画像入力モデルを、`VLM_SLOTS`設定で `TEXT_SLOTS` と完全に並列に追加可能([examples/vlm](./examples/vlm/README.ja.md)参照)
+- オフラインテストスイート(`tests/`、pytest + fake SDK)— HTTP/エンジン/テンプレートの全スタックがNPUなしで動作確認可能
+
+## 必要要件
+
+- Python 3.10+(`int | None` 等の型構文を使用)
+- QAIRT SDK(`libGenie.so` とその依存ライブラリ)、Hexagon NPU上で動作するモデル一式(上記の注意参照)
+
+```bash
+pip install .[logprobs,vlm]     # 全部入り
+pip install .                   # サーバ本体のみ: fastapi, uvicorn, tokenizers
+```
+
+配布名は `open-genie-server`、import するパッケージ名は `genie_server` です。
+`pip install -r requirements.txt` も従来どおり使えます(上の1行目と同じ内容)。
+
+| | 区分 | 用途 |
+|---|---|---|
+| `fastapi`, `uvicorn` | 本体 | サーバ |
+| `tokenizers` | 本体 | 正確なトークン数カウント。無いと `text.split()` で数えるため**実際55トークンの日本語の段落が「1」になり**、usage だけでなくコンテキストチェックと既定 `max_tokens` にも効きます。[トークン数のカウント](./docs/MANUAL.ja.md#トークン数のカウント)を参照 |
+| `numpy` | `[logprobs]`, `[vlm]` | **logprobsとプロンプトスコアリング**、およびVLM。無いとこれらのリクエストは HTTP 400 で拒否されます |
+| `pillow` | `[vlm]` | 画像入力 |
+| `pytest`, `httpx`, `requests`, `jsonschema` | `[test]` | オフラインテストスイート |
+
+インストールすると `genie-server` コマンドが使えるようになります。リポジトリ直下の
+`genie-server.py` ランチャーも同じもので、こちらはインストール不要です。
+Android ではこのうち3つに wheel がありません —
+[Androidで動かす](./docs/MANUAL.ja.md#androidで動かす)を参照してください。
+
+> [!WARNING]
+> **デプロイ前に、どのQAIRTバージョンを指しているか確認してください。**
+> どのSDK欠陥を抱えることになるかはそのバージョンで決まります。そして
+> **当方が検証した 2.49.x はいずれも、3つの欠陥を同じ一箇所に抱えています —
+> `GenieDialog_reset()` が元に戻しそこねるもの**です。サーバはリクエストを独立させるために
+> 毎回リセットするので、そこは**あなたが処理するすべてのリクエストの下を通る経路**です。
+>
+> 現れ方は、**過大なリクエスト1回でスロットが恒久的に壊れる**、
+> **直前が短かったせいで長いリクエストが空のコンテキストで失敗する**、
+> **投機デコード向けのバンドルで、最初のリセット以降の応答が流暢なまま間違って返る** —
+> のいずれかです。**3つとも「成功」を報告します。**
+>
+> バージョン別の一覧、[手元のSDKで試せる確認手順](./docs/QAIRT_VERSIONS.ja.md#手元の-sdk-を確認する)、
+> ライブラリの選び方は **[QAIRT バージョン別の問題点](./docs/QAIRT_VERSIONS.ja.md)** に
+> まとめてあります。**そこに載っていないバージョンは
+> 「問題が無いと分かっている」のではなく「未検証」**です。
+
+## クイックスタート
+
+> [!NOTE]
+> この節の例は `192.168.1.2:8080` でデバイスに接続しています。これは本サーバ固有の
+> 値ではなく、**SA8255P の LV GVM が既定で起動してくるアドレス**です。当方の検証環境も
+> これを使っているため、ドキュメント全体と
+> `tests/integration/test_config.sample.json` に同じ値が出てきます。
+> ご自身のデバイスのアドレスに置き換えてください(サーバとクライアントが同じマシン上
+> なら `localhost` で構いません)。
+
+1. `env_config.json` をサーバ起動ディレクトリ(カレントディレクトリ)に用意します。
+
+   ```json
+   {
+     "QAIRT_SDK_ROOT": "/path/to/qairt-dir",
+     "HEXAGON_VERSION": "v73",
+     "MODELS_BASE_DIR": "/path/to/models",
+     "PREFIX_CACHE_DIR": "/path/to/prefix_cache",
+     "TEXT_SLOTS": [{"model_root": "model-dir"}]
+   }
+   ```
+
+   `model_root` は `genie_config.json` を含むディレクトリを指します。スロットに必須なのはこのキーだけで、`name` と `device_id` は既定値が使われます。
+
+   相対パスの `model_root` は `MODELS_BASE_DIR` 配下として解決されるので、上の例は `/path/to/models/model-dir` をロードします。絶対パスも使えます — [モデルパスの解決ルール](./docs/MANUAL.ja.md#モデルパスの解決ルール)を参照。
+
+   複数NSPコアを積んだSoCでは、コアごとにエントリを足すとそれぞれにモデルを常駐させられます(詳細と、2本目が必ず載るとは限らないという順序の制約は [MANUAL.ja.md](./docs/MANUAL.ja.md#マルチテキストスロット)):
+
+   ```json
+   {
+     "QAIRT_SDK_ROOT": "/path/to/qairt-dir",
+     "HEXAGON_VERSION": "v73",
+     "MODELS_BASE_DIR": "/path/to/models",
+     "PREFIX_CACHE_DIR": "/path/to/prefix_cache",
+     "TEXT_SLOTS": [
+       {"name": "tool_call", "device_id": 0, "model_root": "model-fast"},
+       {"name": "chat", "device_id": 1, "model_root": "model-general"}
+     ]
+   }
+   ```
+
+2. サーバを起動します。
+
+   ```bash
+   python3 genie-server.py            # フラグ: --config/--host/--port
+   # または、パッケージをインストール済みなら
+   genie-server                       # フラグは同じ
+   # または uvicorn を直接
+   uvicorn genie_server.asgi:app --host 0.0.0.0 --port 8080 --workers 1
+   ```
+
+3. 動作確認:
+
+   ```bash
+   curl http://192.168.1.2:8080/v1/models
+
+   curl http://192.168.1.2:8080/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{"model":"genie-local","messages":[{"role":"user","content":"こんにちは"}]}'
+   ```
+
+Grammar制約デコーディングの設定例は [examples/grammar](./examples/grammar/README.ja.md)、VLM(画像入力)の設定・テスト手順は [examples/vlm](./examples/vlm/README.ja.md)、`lm_eval` の実行手順(量子化前モデルとの比較方法を含む)は [examples/lm_eval](./examples/lm_eval/README.ja.md) を参照してください。
+
+## lm_eval での利用
+
+```bash
+lm_eval --model local-chat-completions \
+  --model_args model=genie-local,base_url=http://192.168.1.2:8080/v1,\
+tokenizer_backend=huggingface,tokenizer=<hf_model>,max_tokens=512,num_concurrent=1 \
+  --tasks mmlu_generative --apply_chat_template --batch_size 1
+```
+
+設定と挙動の詳細は [MANUAL.ja.md](./docs/MANUAL.ja.md)、エンドポイントのリファレンスは [API.ja.md](./docs/API.ja.md) を参照してください。
+
+## ディレクトリ構成
+
+```
+genie-server.py       — ランチャー(CLIフラグ: --config/--host/--port)
+src/genie_server/     — サーバ実装本体。関心ごとに1モジュール
+pyproject.toml        — パッケージング設定: 依存・extras・genie-server コマンド
+requirements.txt      — pyproject.toml の依存を指すだけのファイル(互換用)
+SECURITY.md           — 意図的に持っていないもの/報告してほしいもの(日本語版あり)
+LICENSE
+
+tests/                — オフラインテストスイート(pytest。fake SDKでNPU不要)
+tests/integration/    — 実機に対するホスト側テストランナー(MD/JSONレポート出力)
+
+docs/MANUAL.ja.md     — 設定・挙動と、その理由(英語版は MANUAL.md)
+docs/API.ja.md        — 全エンドポイントを用途別にまとめたもの(英語版は API.md)
+docs/PLATFORM_NOTES.ja.md — 実測値がデバイスについて前提にしていること(英語版あり)
+docs/QAIRT_VERSIONS.ja.md — QAIRT バージョン別のSDK欠陥(英語版あり)
+docs/CHANGELOG.md     — リリースノート
+
+examples/config/      — env_config.json サンプル(シングルスロット/デュアルNSP/VLM)
+examples/grammar/     — Grammar制約デコーディング
+examples/vlm/         — VLM(マルチモーダル)の設定・テスト手順
+examples/lm_eval/     — lm_eval の実行と、量子化前モデルとの比較
+examples/bfcl/        — Berkeley Function Calling Leaderboard
+```
+
+`src/genie_server/` のモジュールごとの内訳は、ここで繰り返さず
+[MANUAL.ja.md § アーキテクチャ概要](./docs/MANUAL.ja.md#アーキテクチャ概要) にまとめてあります。
+
+オフラインテストの実行:
+
+```bash
+pip install -e .[logprobs,vlm,test]
+python3 -m pytest tests/
+```
+
+`[test]` の依存は「任意」ではありません。`requests` と `jsonschema` が無いと
+grammar のテストが8件 `ModuleNotFoundError` で落ち、`numpy` が無いと
+logprobs のテストが8件落ちます。同じスイートは push と
+pull request のたびに Python 3.10 / 3.12 で実行されます
+(`.github/workflows/offline-tests.yml`)。
+
+ホストPCから実機をエンドツーエンドで検査する統合テスト(Markdown/JSONレポート、サーバ停止検出付き)は [tests/integration/](./tests/integration/README.ja.md) を参照してください。
+
+## 既知の制約
+
+- **本サーバは、このページ冒頭で説明した素のライブラリでのリセット系欠陥を防ぎません** — 検知も復旧もしません。回避はデプロイ側の選択です — [QAIRT バージョン別の問題点](./docs/QAIRT_VERSIONS.ja.md)を参照。
+- **投機デコード向けにビルドされたバンドル(`"dialog": {"type": "ssd-q1"}`)にはパッチ版ライブラリが要り、それ無しでは LoRA も使えません。** 理由と、バンドル側の1行の書き換えで回避する方法は [D5](./docs/QAIRT_VERSIONS.ja.md#d5--リセットが投機デコードのダイアログを壊す) を参照。
+- 1テキストスロット = 1 `GenieDialog` ハンドルで、スロット内のリクエストはそのスロット自身のロックで直列化されます(`TEXT_SLOTS` 未設定時は単一スロットのみで、従来通り全リクエストが直列化されます)。
+- `n > 1`(1リクエストでの複数補完同時生成)は非対応で、`400` で拒否されます。
+- Llama2/Mistralテンプレートはシステムプロンプトを `[INST]` に埋め込むため、prefix KVキャッシュの対象外。
+- `POST /v1/models/switch` は既定で旧モデルを解放してから新モデルをロードするため、ロードに失敗するとそのスロットは次のswitchが成功するまでモデル未ロードのままになります。その間、そのスロットに触れる全エンドポイントは `503` を返します。
+- `"unload_first": false` にすると新旧を同時にHTPデバイスへ載せてこれを避けられますが、**SA8255Pボードではこの同時常駐は当てになりません**。36回のスワップを実測した結果、成否は**どのモデルの組み合わせかでは決まりませんでした** — 同じ組み合わせがあるときは6回中6回成功し、別のときは8回中8回失敗し、6回の連続実行の途中で失敗から成功に転じたこともあります。決めているのはホストからは観測できないデバイス側の状態です。**デバイスのメモリに十分な余裕があり、かつ実運用で行うスワップをコールドスタートからの反復も含めてテスト済みの場合にだけ**使ってください。
+- VLMスロットはシングルターンのみ(会話履歴の保持なし)、LoRA・Prefix KVキャッシュ・grammar制約・ホットスワップ非対応。詳細は [MANUAL.ja.md](./docs/MANUAL.ja.md#vlmマルチモーダル対応) を参照。
+
+他の詳細な制約事項は [MANUAL.ja.md の制約事項セクション](./docs/MANUAL.ja.md#制約事項) を参照してください。
+
+## 謝辞
+
+本プロジェクトは [Claude Code](https://claude.com/claude-code) を使って開発しました。
+最初のコミットは 2026-08-19 で、そこからの11日間で、2,700行の単一スクリプトから、
+オフラインテスト311件・実機統合テスト・英日2言語のマニュアルを備えたパッケージに
+なりました。
+
+**時間がかかったのはコードではありません。** QAIRT SDK のリファレンス実装を
+「SDK の欠陥」と「こちらのバグ」を切り分けられる程度まで読み込むこと、その一つひとつを
+実機で再現させてどちらなのかを確定させること、そして**推測ではなく実測を書き残す**こと —
+本ドキュメントの記述にも、当時は自明に見えた結論を後から覆したものがいくつもあります。
+これを**一人でこの速度でやることは、Claude Code なしでは不可能でした。**
+
+## License
+
+[MIT](./LICENSE)
+
+本リポジトリのライセンスはopen-genie-server自体のソースコードにのみ適用されます。Qualcomm QAIRT SDK・`libGenie.so`・Hexagon NPU向けモデルは対象外で、それぞれQualcommおよび各モデルの配布元のライセンス条件に従います。
+
+**MIT は既定値ではなく選択です。** この種の計測器はコピーレフトで公開されていることが
+多いので、そうしなかった理由を書いておきます。理由は2つあり、どちらもこのプロジェクト
+固有のものです。ひとつは、本サーバが proprietary な `libGenie.so` を ctypes で
+**実行時にロードする**こと。コピーレフトにすると、**このサーバと SDK を同梱した
+ボードイメージを配布する**人に結合著作物の解釈問題を負わせることになります。これは
+このハードウェアでは普通の配布形態であり、モデルを1つ測る前に法務レビューを挟ませるだけの
+価値はありません。もうひとつは、**このコードの正しい使い方が「分解すること」**だという点です。
+`logprobs.py` を自分の評価ハーネスに持っていく、自分のボードに必要なエンドポイント1つの
+ために fork する — そこに課税するライセンスは、このプロジェクトの目的に逆行します。