Skip to content

About

SKaiNET cartridge blueprints

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SKaiNET cartridge blueprints

License: MIT Maven Central REUSE status

Open-source blueprints for SKaiNET cartridges, and the reference materializer that turns a blueprint into a cartridge.

A cartridge is a self-contained package that runs one model on one target: native runtime, model artifacts, capability descriptor, signed manifest. A blueprint is everything needed to build one — API and runtime source, a descriptor template and a machine-readable recipe — without the model weights and without compiled binaries. Turning a blueprint into a cartridge is materialization:

flowchart LR
    blueprint["blueprint<br/>recipe + source"]
    profile["your profile<br/>target, measurements,<br/>license acceptance"]
    subgraph materialize ["./gradlew materializeCartridge — on your machine"]
        direction LR
        fetch["fetch<br/>weights, pinned by<br/>revision + SHA-256"]
        convert["convert<br/>Kotlin"]
        quantize["quantize<br/>Kotlin"]
        export["export<br/>StableHLO"]
        compile["compile<br/>IREE tools"]
        pack["pack + sign<br/>descriptor + manifest"]
    end
    cartridge["cartridge<br/>graphs + params<br/>+ native runtime"]
    blueprint --> fetch
    profile -- "license gate: terms are YOURS to accept,<br/>never accepted for you" --> fetch
    fetch --> convert --> quantize --> export --> compile --> pack --> cartridge
Loading

Normative text: Blueprints (cartridge spec v0.4, SKEEP-007). This repository never contains weights, .vmfb, .irpa or native libraries.

What is here

Path Content Status
blueprint-gradle-plugin/ Gradle plugin sk.ainet.cartridge.blueprint — the materializer core working, see below
blueprints/nlu-functiongemma-270m-iree/ Function-calling NLU, FunctionGemma 270M — Kotlin Multiplatform API (runtime binding: Android), recipe, step-by-step guide (weights: Gemma Terms of Use, acceptance required) recipe verified step by step; end-to-end materialization needs your license acceptance
blueprints/asr-moonshine-v2-streaming-iree/ Streaming speech-to-text, Moonshine v2 tiny en + de — Kotlin Multiplatform API (runtime binding: Android), recipe, step-by-step guide (weights: MIT) German flavor materialized end to end, signed, verified on a device against the previous build
blueprints/nlu-qwen-iree/ Function-calling NLU, Qwen instruct models, one flavor per checkpoint (today: Qwen3-0.6B) — Kotlin Multiplatform API (runtime binding: Android), recipe, step-by-step guide (weights: Apache-2.0) recipe runs on the host; compiled graphs match llama.cpp token for token on host IREE; not yet run on a device
blueprints/detection-yolov8-iree/ Single-shot object detection, YOLOv8n (COCO, 80 classes) — Kotlin Multiplatform API implementing the yolo/v1 task profile, the YOLOv8 graph in the SKaiNET DSL, recipe (weights: AGPL-3.0, restricted) materialized end to end, signed; verified on a device (Pixel 8a, Vulkan, 320/640); consumer library on Maven Central
blueprints/classification-moonshine-v2-head-iree/ A classification head on a frozen Moonshine v2 encoder (spoken intents and the like), trained by the recipe on your label set and recordings, calibrated to accept, defer or refuse — the head in the SKaiNET DSL, trained with the training DSL, recipe with train / calibrate steps (encoder: MIT; your data's license applies) materialized end to end on the host from the German example; compiled module matches the eager head; not yet run on a device
blueprints/generator-lfm25-350m-skainet/ LFM2.5-350M eager CPU generation through existing llm/v1 and shared POSIX/JVM runtime Source recipe; each rebuilt artifact closure requires fresh CPU measurement and final materialization validation; unsigned evaluation only
blueprints/generator-lfm25-350m-iree/ Complete cached LFM2.5-350M StableHLO/IREE Vulkan generation at context64, with the same shared profile/runtime Source pipeline and provisional staging; complete GPU target qualification pending, materialization fails closed
blueprints/generator-lfm25-350m-torq/ Text generation, LFM2.5-350M, one decode step per call on the Synaptics Torq NPU (Q8_0 projections and Q4_0 head as block-quant matmuls, bf16, one dispatch) — Kotlin Multiplatform API for the host side of the step (JVM, Linux), recipe (weights: LFM Open License v1.0, acceptance required) step compiled and run on an SL2610 (533 ms per step, top-1 equal to FP32); end-to-end materialization needs your license acceptance
profiles/yolo-v1/ The yolo/v1 task-profile contract (copy of the spec's normative types until they are published) working, on Maven Central
docs/ Model-specific guides: download, convert, quantize, compile planned

Two modules are published to Maven Central — code only: packs are materialized locally from the blueprint, weights never ship:

implementation("sk.ainet.cartridge.profiles:yolo-v1:0.2.2")      // the yolo/v1 contract alone
implementation("sk.ainet.cartridge:detection-yolov8-iree:0.2.2") // the blueprint's consumer library

The materializer

plugins { id("sk.ainet.cartridge.blueprint") }

blueprint {
    // What the model-specific build tasks produced, under the names blueprint.json uses.
    product("graphs-vmfb", compileGraphs.flatMap { it.outputDir })
    product("runtime-so", buildRuntime.flatMap { it.library })
}
./gradlew blueprintValidate                                   # blueprint.json (+ profile) against the spec schemas
./gradlew blueprintFetch       -Pprofile=profiles/mine.json   # license gate, then download + verify every digest
./gradlew materializeCartridge -Pprofile=profiles/mine.json   # descriptor, effective license, pack_dir, manifest, signature

What it does today, each covered by tests:

  • validates blueprint.json and the profile against the spec's JSON Schemas (bundled at a recorded spec commit);
  • stops before any download when a source is acceptance-required and the profile records no acceptance — it never accepts a license for you;
  • fetches hf://, https:// and file: sources (or a profile's mirror) with SKaiNET's own skainet-data-source: SHA-256 verified while streaming and before anything enters the cache, one shared cache per machine (~/.cache/skainet/data), ./gradlew --offline served from that cache, and HF_TOKEN / HUGGING_FACE_HUB_TOKEN attached to hub requests only — not forwarded along the hub's CDN redirect (pinned by a test). Plain http:// is refused;
  • resolves the descriptor from the template — performance/quality must come from the profile's measurements, never from a blueprint's reference numbers;
  • computes the effective license from what each artifact is derived_from;
  • writes the pack_dir (descriptor.json, manifest.json, artifacts/<role>/…) with provenance.blueprint and provenance.materialization;
  • signs with Ed25519 exactly as the spec's sign_manifest.py does — a manifest produced here verifies with the spec's verify_manifest.py.

The steps in between — convert, quantize, export, compile, build-runtime, measure — are model- and backend-specific. They are ordinary Gradle tasks in each blueprint module; the plugin sees their results as named products.

Reusable step tasks the plugin offers to blueprint modules: HostGatherTask (move a decoder's token-embedding lookup to the host; a text rewrite of the exported StableHLO, byte-identical to the rewrite it replaces), IreeCompileTask and IreeConvertParametersTask (IREE tools, StableHLO → IREE, in the pinned container image), blueprint.sourceFile(source, path) (a fetched, verified file as a task input) and blueprint.target (the profile's target and its params).

The signing key is read from the environment variable the profile's signing.key_ref names, or from -PsigningKeyFile=<pem> (unencrypted PKCS#8, openssl genpkey -algorithm ed25519). It is never in a profile.

Build

./gradlew build        # builds the plugin, runs unit tests and TestKit functional tests

JDK 21 or newer. BLUEPRINT_NETWORK_TESTS=1 ./gradlew build additionally runs real hf:// downloads of two small, MIT-licensed, pinned files (off by default, so the build works offline).

License

Code and recipes: MIT, see LICENSE. Model weights are not part of this repository and keep their publishers' licenses — each blueprint states them per source, with a link.

About

SKaiNET cartridge blueprints

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages