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}
}
```