SKaiNET-cartridge

The home of the cartridge concept in the SKaiNET universe — spec, schemas, runtime ABI, task profiles, and decision log, versioned together.

A cartridge is a self-contained, application-agnostic software package that runs one model on given hardware, with a minimal input→output API any application — in any language — can call. It is the deployment unit that bridges a SKaiNET model and a real application on real hardware: App → Adapter → Cartridge, where the cartridge is public and HW-native and the adapter is the app-specific (often closed) glue.

Start with the MANIFESTO (the short front door), then the spec.

Project status — normative draft. Spec v0.4, ABI v0.1. Every section carries a maturity tag (working / drafted / direction). Expect the drafted parts to change through ADRs.

The spec (v0.4)

Rendered documentation: https://skainet-developers.github.io/SKaiNET-cartridge/

The source is an Antora component (skainet-cartridge), readable directly as Asciidoc:

• index.adoc — the concept, contract, descriptor, integrity/licensing model, consumption modes, open questions
• abi.adoc — the C Runtime ABI (normative header: cartridge-abi/include/cartridge_abi.h)
• task-profiles.adoc — per-task consumer contracts (asr/v1, yolo/v1) and the typed facade
• blueprints.adoc — new in v0.4: the open, weight-free recipe a cartridge is built from, and materialization — how a blueprint plus a profile becomes a signed cartridge. Guides: tutorial, private materialization, explanation; design record: SKEEP-007
• threat-model.adoc — who verifies what, where
• roadmap.adoc — phases 2–5
• adr/ — decision log

Worked, runnable examples (JSON schemas, signed example manifests, verify_manifest.py / sign_manifest.py) live in docs/modules/ROOT/examples/:

cd docs/modules/ROOT/examples
python3 verify_manifest.py asr-whisper-tiny-npu.manifest.json \
    publisher-2026-09=demo-keys/publisher.pub

Code

• cartridge-abi/ — the ABI header (C, FFI-clean)
• cartridge-task-profiles/ — Kotlin Multiplatform module with the public task profiles: asr/v1 (Flow-based core + callback bridge) and yolo/v1 (single-shot), package sk.ainet.cartridge.profile

./gradlew build

Reference cartridges

The spec was extracted from, and is validated against, two working cartridges: a batch Whisper-tiny cartridge running natively on a vendor NPU (asr-whisper-tiny-npu) and a streaming Moonshine cartridge on ONNX Runtime with VAD inside (asr-moonshine-ort-cpu). Their descriptors and signed manifests are the worked examples; retrofitting both onto the Runtime ABI is roadmap Phase 3.

Building the docs locally

npx --yes antora@3.1 --stacktrace docs/antora-playbook.yml
open docs/build/site/index.html

Contributing

Spec changes go through an ADR in docs/modules/ROOT/pages/adr/ — see CONTRIBUTING.md. This project follows the SKaiNET Code of Conduct.

Citing

If you reference the cartridge concept, the spec, the runtime ABI, or the task profiles in a paper or an implementation, please cite this repository. Citation metadata lives in CITATION.cff (GitHub's Cite this repository button exports BibTeX and APA from it). Ready-to-paste BibTeX:

@misc{skainet_cartridge_spec,
  author       = {Harakal, Michal and {SKaiNET-developers contributors}},
  title        = {{SKaiNET} Cartridge Specification},
  year         = {2026},
  doi          = {10.5281/zenodo.23165734},
  note         = {Specification v0.4, Runtime ABI v0.1. MIT License},
  howpublished = {\url{https://github.com/SKaiNET-developers/SKaiNET-cartridge}}
}

When citing a specific normative statement, please include the spec version (the spec is a living draft; sections carry maturity tags) and, ideally, the commit hash or a tagged release.

License

MIT — see LICENSE.