|
Download README.md from Microck/Spunto-Router-23M: direct link, hf CLI and curl.
- Browser
- Download file 13.2 kB
-
https://huggingface.co/Microck/Spunto-Router-23M/resolve/main/README.md
- Command line
-
hf download hf://Microck/Spunto-Router-23M/README.md
-
curl -L -o README.md https://huggingface.co/Microck/Spunto-Router-23M/resolve/main/README.md
13.2 kB
| 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} | |
| } | |
| ``` | |