文書Documentation

Rust engine

cargo add kotoshu — the engine itself as a crate: Dictionary load, correct, ranked suggest, the C ABI batch format, and the models registry behind the resources feature.

The kotoshu crate is the engine every other surface wraps — pure Rust, no runtime dependencies by default.

Install

cargo add kotoshu

Quick start

use std::path::Path;

fn main() {
let dict = kotoshu::dict::Dictionary::load(
Path::new("en_US.aff"),
Path::new("en_US.dic"),
)
.expect("load dictionary");

println!("correct(\"hello\") = {}", dict.correct("hello"));
println!("correct(\"helo\")  = {}", dict.correct("helo"));

for s in dict.suggest("hlelo", 3) {
println!(
"suggest: {} dist={} conf={:.2} source={:?}",
s.word, s.distance, s.confidence, s.source
);
}
}

correct("hello") = true
correct("helo")  = false
suggest: hello dist=1 conf=1.00 source=EditDistance
suggest: halo dist=1 conf=0.50 source=Phonetic
suggest: heel dist=1 conf=0.50 source=Phonetic

Dictionary::load takes paths; load_from_sources takes the .aff/.dic text directly — byte-symmetric, and the form the wasm binding uses. A Suggestion carries word, distance, confidence, and a SuggestionSource enum (EditDistance, Phonetic, keyboard, n-gram) — the same row the conformance vectors freeze.

Features

Feature	Adds
`(default)`	dictionaries, affixes, ranked suggestions — zero dependencies
`rerank`	context-aware reranking math — cosine similarity over host-supplied vectors; always compiled, this is the module
`onnx`	the `OrtProvider` over ONNX Runtime — dynamic loading only, never bundled
`resources`	the models registry (`kotoshu.resources/v1`): tier resolution, SHA-256 verification, primary→mirror downloads, local cache
`ruby` / `wasm` / `python`	FFI shims — the gem native extension, `@kotoshu/wasm`, and the `kotoshu_native` wheel

The batch format — KOSH

For hosts embedding the engine, the C ABI speaks a single batch wire format defined in ffi::shared: every buffer starts with the 4-byte magic KOSH, a version, and a kind tag, followed by length-prefixed records. One serialization serves every binding — measured 3–5× faster than object-by-object FFI — and it is the format the 2630 conformance vectors speak, so all language surfaces agree by construction.

Verified 2026-09-05 — the quick start executed against kotoshu 0.1.0 on stable Rust. Registry: kotoshu on crates.io · kotoshu-rs repo