File size: 13,239 Bytes
7beef3d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | ---
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.80
- 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](https://github.com/Microck/spunto) 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:
```sh
python3.11 python/install-router.py prepare --target "$HOME/.local/share/spunto" --from-hub Microck/Spunto-Router-23M
```
See the [source README](https://github.com/Microck/spunto#install-and-enable) 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](https://huggingface.co/docs/hub/models-download-stats); 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.
```python
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`](https://huggingface.co/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](https://github.com/Microck/spunto/tree/main/docs) 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](LICENSE) and [NOTICE](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:
- [cross-encoder/ms-marco-MiniLM-L6-v2](https://huggingface.co/cross-encoder/ms-marco-MiniLM-L6-v2), including its MS MARCO training and evaluation references.
- [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2), including its sentence-embedding training references.
- [Qwen/Qwen3-Reranker-0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B), the distillation teacher. Teacher weights are not included here.
```bibtex
@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}
}
```
|