Skip to content

api-reference.md

Latest commit

 

History

History
93 lines (72 loc) · 4.06 KB

api-reference.md

File metadata and controls

93 lines (72 loc) · 4.06 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 release and Apple verification status

Use current status for the source baseline, releases, open PRs and model/device verification. Use the preview guide for exact published CLI/C ABI assets. API availability, native packaging checks and real-model hardware validation are separate; this API index does not establish full-catalog or Metal acceptance. Historical checkpoints are indexed in engineering records.

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