Spunto-Router-23M / README.md
Microck's picture
Release Spunto-Router-23M
7beef3d verified
|
Raw History Blame
13.2 kB
metadata
license: apache-2.0
library_name: onnx
pipeline_tag: text-classification
base_model:
  - cross-encoder/ms-marco-MiniLM-L6-v2
  - sentence-transformers/all-MiniLM-L6-v2
language:
  - en
  - es
  - pt
tags:
  - onnx
  - reranker
  - routing
  - agents
  - skills
  - cross-encoder
  - minilm
model-index:
  - name: Spunto-Router-23M
    results:
      - task:
          type: text-classification
          name: Agent skill routing
        dataset:
          type: private-authored-routing
          name: Private authored fresh routing set
          split: fresh
        metrics:
          - type: precision
            name: Top-1 precision, lower label bound
            value: 0.8
          - type: coverage
            name: Fire-based coverage, lower label bound, not recall
            value: 0.692
          - type: false-fire-count
            name: False fires on known-no-skill requests
            value: 2

Spunto-Router-23M

Spunto-Router-23M scores conversation and skill-description pairs to select useful SKILL.md-style instructions for agents. The model is agent-agnostic. This repository contains the CPU FP32 ONNX bundles for an eight-candidate bi-encoder retrieval stage and a fine-tuned MiniLM cross-encoder decider. The OMP extension and installer inject selected skill bodies into the agent's context. The router can abstain, and it does not replace explicit policy or native permissions.

Naming

Spunto is Italian for "a cue". Spunto-Router-23M follows the Brand-Router-Size convention of Arch-Router-1.5B and Supra-Router-51M. The size refers to the MiniLM-L6 decider, about 22.7 million parameters, not the combined decider and stock retrieval model. This project is unrelated to pipizhao/SkillRouter-*.

Integrations

OMP (oh-my-pi) is the first shipped integration. Other integrations are welcome, but no other agent integration is included. The OMP extension handles live catalog discovery, policy, and skill-body injection.

Model details

Property Value
Developer Microck
Decider Fine-tuned cross-encoder/ms-marco-MiniLM-L6-v2 encoder, 128-dimensional projection, 32-dimensional GRU decision head
Retriever Unchanged pretrained sentence-transformers/all-MiniLM-L6-v2, 384-dimensional normalized embeddings
Retrieval candidates 8, with deterministic ID tie-breaking
Runtime ONNX Runtime CPU, FP32, ONNX opset 17
Decider input Request and optional structured action paired with one skill description
Decider output Raw relevance logit, followed by frozen abstention/selection thresholds
Retained input Up to 96 recent intent tokens, up to 96 action tokens, description head, 320 payload tokens plus 3 special tokens
License Apache-2.0

The decider is not an unmodified Hugging Face sequence-classification graph. Its encoder returns pooled features, and aggregator-step.onnx produces the final logit. Use both graphs or the supplied worker. It is not directly loadable with AutoModelForSequenceClassification or a generic Transformers pipeline.

Intended use

Use the router to suggest or load trusted local specialist instructions for an OMP coding agent. The live catalog supplies skill IDs, descriptions, and bodies. The model does not have a fixed skill-label vocabulary.

Do not use the router to authorize tool calls, enforce a security policy, or certify an instruction as safe. It can miss useful skills, fire on irrelevant ones, and misread negated or quoted tasks. Evaluate on your own catalog before enabling automatic injection.

Use with OMP

Install the source repository's requirements, then run this command from its root:

python3.11 python/install-router.py prepare --target "$HOME/.local/share/spunto" --from-hub Microck/Spunto-Router-23M

See the source README for the environment setup, enable/disable commands, configuration, and rollback. OMP 18.18.0, Python 3.11, Bun 1.4.4, and Linux aarch64 are the supplied install target. Add --revision with a full Hub commit SHA to pin a release.

The installer downloads top-level config.json through hf_hub_download before any bundle file. It pins the resolved commit and verifies every listed SHA-256 and byte count. The normal config request follows Hugging Face's server-side download-counting mechanism; the installer does not send a separate analytics event. Routing itself runs offline.

Score short pairs with ONNX Runtime

Download the repository files and run the following from the model folder. Install onnxruntime==1.23.2, tokenizers==0.22.1, and numpy==2.2.6 in a Python 3.11 environment first.

This example deliberately uses short requests without actions, so each pair fits in one full window. It runs both decision graphs and returns raw logits, not calibrated probabilities. For long requests or structured actions, use python/pair-windows.py and the worker from the source repository to preserve the exact truncation and position rules.

from pathlib import Path
import numpy as np
import onnxruntime as ort
from tokenizers import Tokenizer

bundle = Path("decision-bundle")
tokenizer = Tokenizer.from_file(str(bundle / "tokenizer.json"))
tokenizer.no_padding()
tokenizer.no_truncation()
pairs = [
    ("Inspect the settings form for keyboard access.",
     "Review keyboard navigation and accessible form labels."),
    ("Inspect the settings form for keyboard access.",
     "Create and publish a container image."),
]
encoded = tokenizer.encode_batch(pairs)
width = max(len(item.ids) for item in encoded)
arrays = {
    "input_ids": np.zeros((len(pairs), width), dtype=np.int64),
    "attention_mask": np.zeros((len(pairs), width), dtype=np.int64),
    "token_type_ids": np.zeros((len(pairs), width), dtype=np.int64),
}
for row, item in enumerate(encoded):
    arrays["input_ids"][row, :len(item.ids)] = item.ids
    arrays["attention_mask"][row, :len(item.ids)] = item.attention_mask
    arrays["token_type_ids"][row, :len(item.ids)] = item.type_ids
options = ort.SessionOptions()
options.intra_op_num_threads = 2
options.inter_op_num_threads = 1
encoder = ort.InferenceSession(str(bundle / "encoder.onnx"), options,
                               providers=["CPUExecutionProvider"])
head = ort.InferenceSession(str(bundle / "aggregator-step.onnx"), options,
                            providers=["CPUExecutionProvider"])
pooled = encoder.run(["pooled"], arrays)[0]
logits = head.run(["logit"], {
    "pooled": pooled,
    "positions": np.array([[0, 1, 0, 1]] * len(pairs), dtype=np.float32),
    "hidden": np.zeros((len(pairs), 32), dtype=np.float32),
})[0]
print(logits[:, 0].tolist())

The snippet opens local graph files directly. The installer and production worker additionally verify the full manifests and their hashes before loading them.

Training

The training pipeline used synthetic contexts authored by LLMs and blind A/B LLM-reviewer labels. It excluded unresolved judgments from hard supervision and kept source groups together across partitions. The admitted training partition contained 1,744 contexts and 209,810 reviewed pairs, comprising 6,670 positive and 203,140 negative pairs. These counts describe admitted supervision, not the number of unique optimizer examples after teacher candidate construction.

The decider combined mean binary cross-entropy on reviewed hard labels with distillation from Qwen/Qwen3-Reranker-0.6B. Teacher candidate construction used training data only. Validation chose the deployment thresholds. The retriever uses unchanged pretrained weights; it was not fine-tuned for this release.

Training setting Value
Epoch limit 3
Optimizer-step limit 10,000
Batch size 16
Learning rate 0.00002
Seed 42
Distillation weight 1.0
Teacher temperature 2.0

The training source and contracts are available. Training contexts, review judgments, skill bodies, and the evaluation cases are not distributed. Exact training-data reproduction is therefore unavailable.

Evaluation

These results use private, authored agent-routing cases, not MS MARCO or MTEB. Each fired route contributes its highest-scoring eligible automatic choice to precision.

Split Fires Known-correct top-1 Precision bounds Coverage bounds False fires on known-no-skill
Development validation 20 19 0.950 / 0.950 0.800 / 0.800 0
Development unseen family 9 7 0.778 / 0.889 0.727 / 0.750 0
Development temporal 18 13 0.722 / 0.778 0.810 / 0.857 0
Fresh, 41 requests 20 16 0.800 lower 0.692 / 0.692 2
Previous router, same fresh set 20 6 0.300 lower 0.308 / 0.308 12

Fresh precision upper bounds are not reported here. Development precision bounds reflect unknown top-1 labels. The lower bound counts only known-correct choices; the upper bound also treats unknown choices as correct. These are label-completeness bounds, not confidence intervals. Coverage counts any fire on a known-needed request, including a wrong fire, and is not correct-skill recall. The fresh set contains 26 known-needed and 15 known-no-skill requests.

Historical warm CPU routing measured p50 251 ms and p95 344 ms on the fresh set, with a 462 ms maximum. Model startup took about 1.63 seconds. Those measurements used Linux aarch64 and exclude cold catalog preparation. The development collection measured p95 314 ms. Different hardware, catalogs, and context lengths can change latency.

The router did not meet the original 0.95 precision goal on the held-out development splits or fresh set. It also missed a later fresh-set requirement of at least 0.75 coverage and zero false fires. The release should be treated as experimental despite improving on the previous router. Retrieval misses and active-request-scope confusion remain important failure modes; a stronger teacher on the same shortlist did not reach the held-out precision goal either.

Limitations and biases

  • The eight-candidate shortlist limits which skills the decider can recover. Some observed needed skills ranked well below eight.
  • Bounded tail/head token retention can lose decisive context. Quoted or cancelled earlier work can still affect a choice.
  • The base models are English-oriented. The synthetic training included English, Spanish, Portuguese, and mixed-language examples, but no broad multilingual benchmark was run.
  • LLM-authored examples and LLM labels may share correlated biases. Agreement does not establish human correctness.
  • The evaluation set is small, private, and catalog-specific. Its numerical results cannot be independently reproduced from these files alone.
  • Public release metadata omits execution identities. Graph and tokenizer bytes are unchanged, while runtime pins and file manifests describe the public package.
  • The shipped embedding table is empty. The worker prepares the live catalog at startup under a 10-second budget, separate from the 750 ms route budget. Large catalogs can exceed startup limits.
  • Skill bodies are not included. You are responsible for the instructions and licenses of the skills you install.

Files

config.json is the router's top-level format and file-hash inventory, not a Transformers architecture config. decision-bundle/ contains the fine-tuned encoder, recurrent head, tokenizer, model config, recipe, validation, evaluation, and public export-parity probes. shortlist-bundle/ contains the unchanged pretrained retriever export, tokenizer, config, reports, and empty live-catalog cache. Each bundle has its own closed, hash-verified manifest.

The parity probes are generic authored export checks, not training or evaluation cases. Pair-level validation reports describe export/calibration checks and must not be confused with the request-level routing table above.

Citation and attribution

The release uses Apache-2.0. See LICENSE and NOTICE. The decider modifies the MiniLM cross-encoder with task-specific fine-tuning and a learned projection/recurrent head. The retrieval model is an ONNX export of unchanged pretrained all-MiniLM-L6-v2.

Please cite and consult the upstream model cards:

@article{qwen3embedding,
  title={Qwen3 Embedding: Advancing Text Embedding and Reranking Through Foundation Models},
  author={Zhang, Yanzhao and Li, Mingxin and Long, Dingkun and Zhang, Xin and Lin, Huan and Yang, Baosong and Xie, Pengjun and Yang, An and Liu, Dayiheng and Lin, Junyang and Huang, Fei and Zhou, Jingren},
  journal={arXiv preprint arXiv:2506.05176},
  year={2025}
}