SCOPE-Router

SCOPE-Router: Cost-Aware Open-Set VLM Routing for Execution-Oriented Tasks.

Paper | Hugging Face | VLM-ExecRouterBench

SCOPE-Router is a cost-aware, open-set router for vision-language models. It routes each query to a candidate VLM by matching the query embedding against reusable model profiles built from a small calibration set, allowing new candidate models to be added by profiling them without retraining the router.

The repository contains the SCOPE-Router implementation, feature extraction and calibration utilities, evaluation scripts, and the VLM-ExecRouterBench data generation/evaluation pipeline.

Overview

Installation

git clone https://github.com/yutao1024/SCOPE-Router.git
cd SCOPE-Router

conda create -n scope-router python=3.10 -y
conda activate scope-router

pip install --upgrade pip
pip install -e .

Dataset Format

The router-side pipeline expects a prepared dataset directory with files such as:

BENCHMARKS/*.tsv
SPLITS/*.jsonl
data/matrices/Y.npz
data/matrices/C.npy
data/matrices/sample_ids.pkl
data/matrices/model_names.pkl
data/registry/meta.parquet
config/models.yaml
config/pricing.yaml

Precomputed text and vision embeddings are stored under:

EMBEDDINGS/text/<encoder>.parquet
EMBEDDINGS/vision/<encoder>.parquet

Feature Extraction

The default paper setting uses BAAI/bge-m3 for text and facebook/dinov2-large for images:

python routers/features/extract_cli.py \
  --dataset_dir /path/to/dataset \
  --text_encoder BAAI/bge-m3 \
  --vision_encoder facebook/dinov2-large \
  --batch_size 64

Train SCOPE-Router

The convenience script selects a 1024-sample hybrid calibration set, builds a query-aware profile, and trains SCOPE-Router with CRM + RCCR:

bash scripts/train_scope_router.sh /path/to/dataset

Runtime Gateway Integration

SCOPE-Router can be used as a live model selector inside an existing agent gateway.

Start the service:

python integrations/scope_router_service.py \
  --router /path/to/scope_router.pkl \
  --host 127.0.0.1 \
  --port 8760 \
  --text-encoder BAAI/bge-m3 \
  --vision-encoder facebook/dinov2-large

For cc-switch, this repository includes a ready-to-adapt fork under cc-switch/. It adds a proxy-level scope_router hook before static model mapping. For Claude Code Router, claude-code-router/ adds a gateway-level resolveScopeRouterRouteDecision hook before provider resolution. See integrations/README.md for the request contract and config snippets.

VLM-ExecRouterBench

VLM-ExecRouterBench/ contains the execution-oriented benchmark generation and evaluation utilities used by the project. See VLM-ExecRouterBench/README.md and the documents under VLM-ExecRouterBench/docs/ for the benchmark-side workflow.

Repository Layout

Path	Purpose
routers/scope_router/	Main frozen-feature SCOPE-Router implementation.
routers/scope_router_online/	Optional online variant with trainable query encoders.
routers/features/	Text and vision embedding extraction utilities.
routers/utils/	Shared evaluation, ranking, target-construction, and training helpers.
tools/select_calibration_set.py	Random, diagnostic, diversity, and hybrid calibration selection.
tools/build_calibration_profile.py	Calibration profile construction.
scripts/train_scope_router.sh	End-to-end SCOPE-Router training script.
integrations/scope_router_service.py	Runtime HTTP routing service for agent gateways such as cc-switch and Claude Code Router.
cc-switch/	Ready-to-adapt cc-switch fork with proxy-level SCOPE-Router support.
claude-code-router/	Ready-to-adapt Claude Code Router fork with gateway-level SCOPE-Router support.
VLM-ExecRouterBench/	Execution-oriented benchmark construction and SFT/evaluation utilities.

Citation

@misc{yu2026scoperoutercostawareopensetvlm,
      title={SCOPE-Router: Cost-Aware Open-Set VLM Routing for Execution-Oriented Tasks}, 
      author={Tao Yu and Yifei Qu and Zhiqing Cui and Pengfei Zhou and Zhongtian Luo and Yujia Yang and Shenghua Chai and Haopeng Jin and Zhenghao Zhang and Xinming Wang and Hongzhu Yi and Wangbo Zhao and Zhenglin Wan and Yan Huang and Yeshani and Jinwen Luo and Yang You},
      year={2026},
      eprint={2608.12127},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2608.12127}, 
}