Language Bindings

Litsea is a Rust library, but it is also usable from other languages. The bindings live in this repository as workspace members, so they are versioned and released together with litsea itself.

Crates

Design principles

These apply to every binding.

Models are never embedded

A binding package ships code only. The caller supplies a model as raw bytes, a filesystem path, a file:// path, or an http(s):// URL. The bundled models range from 84 KB to 8 MB each, so embedding all four languages would push a wheel or npm package past 20 MB; keeping models external also means a model can be updated without republishing the binding.

See Pre-trained Models for where to get a model.

The model kind is detected, not declared

The CLI needs --pos to know whether it is loading a segmentation model or a two-stage POS model. Bindings do not: they read the model bytes once and dispatch on the detected kind, so has_pos is a property of the loaded model rather than something the caller has to get right.

Cancellation is explicit

Training can run for a long time, and litsea’s trainers stop early when their running flag is cleared. The CLI drives that flag from a Ctrl-C handler, but a library must not install one: signal handling is process-global and the host language usually owns it already. Bindings therefore expose a cancellation token that the caller triggers.

Shared logic lives in one crate

Everything that is not FFI-specific — language-name parsing, model loading and kind detection, token offsets, trainer orchestration, error categories — lives in litsea-binding-core. Each binding only maps that surface onto its host language’s types and exception model.