Skip to content

api-reference.md

Latest commit

 

History

History
149 lines (123 loc) · 7.64 KB

api-reference.md

File metadata and controls

149 lines (123 loc) · 7.64 KB
Raw

API reference

English | 日本語

An index of Vokra's API surfaces and where each one's reference lives. Most of it is auto-generated from the source; this page is a thin pointer, not a hand-maintained copy (which would rot). What is generated versus written by hand is stated in §4.

1. Rust — docs.rs

The Rust crates are documented with rustdoc. Once a future release publishes the crates, each crate auto-links to its own page:

  • https://docs.rs/vokra-core — the IR, Backend trait, GGUF loader, engine
  • https://docs.rs/vokra-capi — the C ABI surface crate (IF-01)
  • https://docs.rs/vokra-models, .../vokra-ops, and the backend crates

The feature-gated GPU/NPU backends carry [package.metadata.docs.rs] so docs.rs builds their platform-specific API (Metal / CoreML on an Apple target, WebGPU on wasm32, CUDA / Vulkan / QNN via their features). Build a focused, memory-safe crate locally with:

cargo doc -p vokra-core --no-deps --open

Maintainers build workspace-wide rustdoc on VAST or CI, never on the 16 GB development Mac.

2. C ABI — include/vokra.h

The canonical C reference is the generated header include/vokra.h. It is produced by scripts/gen-c-abi.sh from the vokra-capi crate and its doc comments are the reference text; a CI drift check keeps it in sync with the Rust source. Every Unity, Godot, Swift, Kotlin, Python and JS binding sits on this one header (IF-01). Vokra is distributed as an ordinary Cargo crate / single library, so this header plus the library is the whole integration surface (NFR-DS-03).

3. Language bindings

Each binding documents its own idiomatic surface on top of the C ABI:

4. What is auto-generated, and what is not

  • Auto-generated: the Rust docs (rustdoc → docs.rs) and the C header (gen-c-abi.sh → include/vokra.h). These regenerate from source and are the source of truth.
  • Manual, but thin: this index and the binding tutorials. They point at the generated references and the working examples; they are not a second copy of the API.
  • Deferred (honest): HTML rendering of the C header (doxygen) and per-language HTML generators (C# / Python / Swift doc tools) are not wired — the header comments and the tutorials are the reference for now. The first docs.rs render is verified by the owner after a crates.io publish.

5. Current 0.3.0 release and Apple verification status

The current release line is workspace version 0.3.0.

2026-10-17 current campaign snapshot: baseline main 5f1dfc1e includes accepted model-free Candle CPU/API work. PR #259's normal CI is complete (72 successful checks / one intentional skip), but its additional observer patch still needs actual upstream library/API verification and remains Draft. The latest retained inventory is dated 2026-10-16: 194 repositories, 136 code/artifact-full / 58 non-full. This documentation refresh does not rerun that inventory, regenerate an API/header, or prove real-weight CPU or Apple parity. See the current status and remaining tasks for the seven open PRs and the non-Apple → VAST → final packet → Scaleway → result/cleanup sequence. Historical snapshots below retain their original scope.

2026-10-13 metadata snapshot: the exact GitHub main checkout is 7d38061c3dcb56f6a16bcf4b8085d966b3cdab09. The fresh metadata/card-only audit reports 194 repositories, 193 GGUF-bearing repositories and 198 GGUF files: CPU full=136, partial=43, no-runtime-binder=14, not-artifact=1; Metal full=136, blocked-by-cpu=57, not-artifact=1. These are catalog metadata counts, not a new API/header or Apple hardware verification. The separate 2026-10-13 VibeVoice VAST audit was static-only and private: it did not execute models or APIs, and it does not establish CPU/Metal/no-fallback parity or publication eligibility. See the documentation refresh record and VibeVoice static-closure audit.

2026-10-08 historical snapshot: this documentation review and the read-only metadata/card-only public audit use exact GitHub main checkout d100d93778191ccab77bd1c37fe3552e3d889758. The audit reports 194 repositories, 193 GGUF-bearing repositories and 198 GGUF files. CPU status is full=136, partial=43, no-runtime-binder=14, not-artifact=1; Metal status is full=136, blocked-by-cpu=57, not-artifact=1, recording 58 unresolved public rows in that historical snapshot. The authorized Scaleway Apple CPU/reference, Metal/reference and no-fallback batch passed only for its named scopes; four separately approved artifacts were then published through the gated workflow. VibeVoice Realtime-0.5B now has a strict structural vibevoice_streaming binder and CLI inspection route, so it is partial; its complete 605-tensor checkpoint has been converted and a narrow independent Microsoft-source reference probe is accepted, but full streaming, native CPU parity, and Apple CPU/Metal verification remain pending. UTMOS numeric parity remains unclaimed, and the v0.3.0 release tag and GitHub release are published. On 2026-10-04, a corrected VAST source-only audit authenticated fixed Kyutai source inputs and independently verified cleanup; it did not execute model weights or change the CPU, Apple-hardware, or publication verdicts. This is not a claim of complete public model-catalog support or v1.0 release readiness.

2026-09-09 audit-start historical snapshot: PR #79 was at 9efcd16eb63b857f48fc00d0b83d1113defd578b; its remote checks then reported 110 successful checks, 13 expected skips, and 0 failures. The audit-start public audit reported 194 repositories (193 GGUF repositories, 198 GGUF files). CPU coverage is full=131, partial=45, no-runtime-binder=17, not-artifact=1; Metal is full=131, blocked-by-cpu=62, not-artifact=1; source-level CPU-only coverage is 0. At that audit-start snapshot, there were 0 release tags and 0 GitHub Releases.

GigaAM v3 and Multilingual had complete conservative Metal code routes, but their Apple-hardware verdicts were not available. The remaining 63 public rows were not claimed complete. Scaleway had not started; CI/audit results did not substitute for Apple hardware evidence. UTMOS numeric parity was also not claimed because its legacy Lightning checkpoint is intentionally refused by the restricted weights_only=True loader.

Keeping this page current

Last verified: 2026-10-08 — against exact GitHub main checkout d100d93778191ccab77bd1c37fe3552e3d889758 and include/vokra.h. The pre-alpha Python generator and checked-in ctypes table cover all 57 generated C functions exactly; the header has 15 typedefs, four enums, two concrete structures, and nine opaque handles. The high-level Python package remains a smaller idiomatic surface rather than a wrapper class for every C handle.

  • Update responsibility: a PR that adds a published crate, a new binding, or changes the C ABI generation updates this index and its Japanese twin in the same PR.
  • Review cadence: quarterly Go/No-go review (NFR-MT-05).
  • Re-fetch the generated surfaces:
scripts/gen-c-abi.sh
# Maintainers run workspace rustdoc on VAST/CI, not on the development Mac:
cargo doc --no-deps --workspace