Duplicate from katanemo/Arch-Router-1.5B

Co-authored-by: Shuguang Chen <nehcgs@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,97 @@
+# Katanemo Labs, Inc. COMMUNITY LICENSE AGREEMENT  
+**Version Release Date:** November 15th, 2025  
+
+This Katanemo Labs, Inc. COMMUNITY LICENSE AGREEMENT is based on the Llama 3.2 Community License, Copyright © Meta Platforms, Inc. The terms and conditions have been adapted to reflect the proprietary nature of Katanemo Labs' materials.
+
+---
+
+1.Definitions
+  a. "Agreement": The terms and conditions for use, reproduction, distribution, and modification of the Katanemo Materials set forth herein.
+  b. "Documentation": The specifications, manuals, and documentation accompanying Katanemo LLMs v1.
+  c. "Licensee" or "you: The individual or entity entering into this Agreement, including your employer if you are acting on their behalf.
+  d. "Katanemo": The foundational large language models and software provided by Katanemo Labs, Inc., available at https://huggingface.co/katanemolabs.
+  e. "Katanemo Materials": Collectively, Katanemo's proprietary models and Documentation. Some Materials are derived from the Qwen language models licensed under the Qwen RESEARCH LICENSE AGREEMENT.
+  f. "Katanemo Labs" or "we": Katanemo Labs Inc., a Delaware, USA Corporation.
+
+---
+
+2. 
+By clicking "I Accept" or using any part of the Katanemo Materials, you agree to be bound by this Agreement.
+
+---
+
+3. LICENSE RIGHTS AND REDISTRIBUTION
+  a. Grant of Rights  
+  Subject to the restrictions in Section 4, you are granted a non-exclusive, worldwide, non-transferable, and royalty-free license to:
+  - Use, reproduce, distribute, and modify the Katanemo Materials.
+  - Create derivative works based on the Katanemo Materials.
+  
+  b. Permitted Redistribution  
+  If you distribute the Katanemo Materials or any derivative work:
+  - You must include a copy of this License.
+  - You must prominently display the notice “Built with Katanemo” on a related website or documentation.
+  
+  c. Attribution Requirement  
+  You must include the following attribution notice in any distributed or public-facing use:
+  "Katanemo is licensed under the Katanemo Labs Community License.  
+  Copyright © Katanemo Labs, Inc. All Rights Reserved."
+
+  d. Compliance Requirement  
+  All use of the Katanemo Materials must comply with the Acceptable Use Policy, available at: https://katanemo.com/use-policy
+
+---
+
+4. COMMERCIAL USE AND DISTRIBUTION RESTRICTIONS
+
+You may use, reproduce, modify, distribute, and create derivative works from the Katanemo Materials for any purpose, including commercial use, EXCEPT in the following cases:
+
+You may NOT package, distribute, or make available the Katanemo Materials as part of:
+- A framework,
+- A proxy server,
+- Middleware,
+- A gateway infrastructure product,
+- Or any product substantially similar in function or purpose to the above,
+
+unless you obtain a separate commercial license from Katanemo Labs.
+
+**Exception for Katanemo-integrated products.**  
+You do not need a separate commercial license when you use the Arch-Router model (or other Katanemo models) **only through a Katanemo product that provides an integrated experience and is itself licensed under Apache 2.0** (for example, the Arch Gateway project at https://github.com/katanemo/archgw), as long as:
+
+1. The model is called only through that integrated product experience and is **not** exposed or offered as a separate framework, proxy, middleware, gateway infrastructure product, or similar service; and  
+2. For Arch Gateway (archgw), any LLM traffic using the Arch-Router model is proxied through Arch Gateway’s data plane.
+
+This exception applies only to use of the Katanemo Materials through such Katanemo-provided integrated products. It does **not** permit you to repackage or redistribute the Katanemo Materials as your own framework, proxy server, middleware, gateway infrastructure product, or any substantially similar product.
+
+---
+
+This license does not grant trademark rights or rights outside the scope described above.
+
+5. Disclaimer of Warranty  
+The Katanemo Materials are provided "AS IS" without warranties of any kind, either express or implied, including but not limited to warranties of title, non-infringement, or fitness for a particular purpose.
+
+---
+
+6. Limitation of Liability  
+Katanemo Labs is not liable for any indirect, special, or consequential damages arising out of the use of the Katanemo Materials, even if advised of the possibility of such damages.
+
+---
+
+7. Intellectual Property
+  a. Trademarks  
+  No trademark licenses are granted, except as required for attribution as described in Section 1.b. You may use the “Katanemo” mark according to Katanemo Labs' brand guidelines.
+
+  b. Ownership  
+  You own any derivative works or modifications you create, except for portions owned by Katanemo Labs.
+
+  c. Litigation  
+  If you file a lawsuit against Katanemo Labs regarding intellectual property, your license under this Agreement terminates.
+
+---
+
+8. Term and Termination  
+This Agreement continues until terminated. Katanemo Labs may terminate the Agreement if you breach any terms. Upon termination, you must cease using the Katanemo Materials.
+
+---
+
+10. Governing Law and Jurisdiction  
+This Agreement is governed by the laws of the State of Washington, USA. Any disputes will be resolved in the courts of California.

README.md

@@ -0,0 +1,172 @@
+---
+base_model:
+- Qwen/Qwen2.5-1.5B-Instruct
+language:
+- en
+library_name: transformers
+license: other
+license_name: katanemo-research
+license_link: https://huggingface.co/katanemo/Arch-Router-1.5B/blob/main/LICENSE
+pipeline_tag: text-generation
+tags:
+- routing
+- preference
+- arxiv:2506.16655
+- llm
+paper: https://arxiv.org/abs/2506.16655
+---
+
+# katanemo/Arch-Router-1.5B
+
+## Overview
+With the rapid proliferation of large language models (LLMs) -- each optimized for different strengths, style, or latency/cost profile -- routing has become an essential technique to operationalize the use of different models. However, existing LLM routing approaches are limited in two key ways: they evaluate performance using benchmarks that often fail to capture human preferences driven by subjective evaluation criteria, and they typically select from a limited pool of models. 
+
+We introduce a preference-aligned routing framework that guides model selection by matching queries to user-defined domains (e.g., travel) or action types (e.g., image editing) -- offering a practical mechanism to encode preferences in routing decisions. Specifically, we introduce Arch-Router, a compact 1.5B model that learns to map queries to domain-action preferences for model routing decisions. Experiments on conversational datasets demonstrate that our approach achieves state-of-the-art (SOTA) results in matching queries with human preferences, outperforming top proprietary models. 
+
+This model is described in the paper: https://arxiv.org/abs/2506.16655, and powers [Arch](https://github.com/katanemo/arch) the models-native proxy server for agents.
+
+### How It Works
+
+To support effective routing, Arch-Router introduces two key concepts:
+- **Domain** – the high-level thematic category or subject matter of a request (e.g., legal, healthcare, programming).
+- **Action** – the specific type of operation the user wants performed (e.g., summarization, code generation, booking appointment, translation).
+
+Both domain and action configs are associated with preferred models or model variants. At inference time, Arch-Router analyzes the incoming prompt to infer its domain and action using semantic similarity, task indicators, and contextual cues. It then applies the user-defined routing preferences to select the model best suited to handle the request.
+
+### Key Features
+
+- **Structured Preference Routing**: Aligns prompt request with model strengths using explicit domain–action mappings.
+- **Transparent and Controllable**: Makes routing decisions transparent and configurable, empowering users to customize system behavior.
+- **Flexible and Adaptive**: Supports evolving user needs, model updates, and new domains/actions without retraining the router.
+- **Production-Ready Performance**: Optimized for low-latency, high-throughput applications in multi-model environments.
+
+# Requirements
+The code of Arch-Router-1.5B has been in the Hugging Face `transformers` library and we advise you to install latest version:
+```bash
+pip install transformers>=4.37.0
+```
+
+# How to use
+We use the following example to illustrate how to use our model to perform routing tasks. Please note that, our model works best with our provided prompt format. 
+### Quickstart
+````python
+import json
+from typing import Any, Dict, List
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "katanemo/Arch-Router-1.5B"
+model = AutoModelForCausalLM.from_pretrained(
+    model_name, device_map="auto", torch_dtype="auto", trust_remote_code=True
+)
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+# Please use our provided prompt for best performance
+TASK_INSTRUCTION = """
+You are a helpful assistant designed to find the best suited route.
+You are provided with route description within <routes></routes> XML tags:
+<routes>
+
+{routes}
+
+</routes>
+
+<conversation>
+
+{conversation}
+
+</conversation>
+"""
+
+FORMAT_PROMPT = """
+Your task is to decide which route is best suit with user intent on the conversation in <conversation></conversation> XML tags.  Follow the instruction:
+1. If the latest intent from user is irrelevant or user intent is full filled, response with other route {"route": "other"}.
+2. You must analyze the route descriptions and find the best match route for user latest intent. 
+3. You only response the name of the route that best matches the user's request, use the exact name in the <routes></routes>.
+
+Based on your analysis, provide your response in the following JSON formats if you decide to match any route:
+{"route": "route_name"} 
+"""
+
+# Define route config
+route_config = [
+    {
+        "name": "code_generation",
+        "description": "Generating new code snippets, functions, or boilerplate based on user prompts or requirements",
+    },
+    {
+        "name": "bug_fixing",
+        "description": "Identifying and fixing errors or bugs in the provided code across different programming languages",
+    },
+    {
+        "name": "performance_optimization",
+        "description": "Suggesting improvements to make code more efficient, readable, or scalable",
+    },
+    {
+        "name": "api_help",
+        "description": "Assisting with understanding or integrating external APIs and libraries",
+    },
+    {
+        "name": "programming",
+        "description": "Answering general programming questions, theory, or best practices",
+    },
+]
+
+# Helper function to create the system prompt for our model
+def format_prompt(
+    route_config: List[Dict[str, Any]], conversation: List[Dict[str, Any]]
+):
+    return (
+        TASK_INSTRUCTION.format(
+            routes=json.dumps(route_config), conversation=json.dumps(conversation)
+        )
+        + FORMAT_PROMPT
+    )
+
+# Define conversations
+
+conversation = [
+    {
+        "role": "user",
+        "content": "fix this module 'torch.utils._pytree' has no attribute 'register_pytree_node'. did you mean: '_register_pytree_node'?",
+    }
+]
+
+route_prompt = format_prompt(route_config, conversation)
+
+messages = [
+    {"role": "user", "content": route_prompt},
+]
+
+input_ids = tokenizer.apply_chat_template(
+    messages, add_generation_prompt=True, return_tensors="pt"
+).to(model.device)
+
+# 2. Generate
+generated_ids = model.generate(
+    input_ids=input_ids,  # or just positional: model.generate(input_ids, …)
+    max_new_tokens=32768,
+)
+
+# 3. Strip the prompt from each sequence
+prompt_lengths = input_ids.shape[1]  # same length for every row here
+generated_only = [
+    output_ids[prompt_lengths:]  # slice off the prompt tokens
+    for output_ids in generated_ids
+]
+
+# 4. Decode if you want text
+response = tokenizer.batch_decode(generated_only, skip_special_tokens=True)[0]
+print(response)
+````
+
+Then you should be able to see the following output string in JSON format:
+````python
+{"route": "bug_fixing"}
+````
+
+To better understand how to create the route descriptions, please take a look at our [Katanemo API](https://docs.archgw.com/guides/llm_router.html).
+
+# License
+Katanemo Arch-Router model is distributed under the [Katanemo license](https://huggingface.co/katanemo/Arch-Router-1.5B/blob/main/LICENSE).
+
+GitHub: https://github.com/katanemo/arch

config.json

@@ -0,0 +1,28 @@
+{
+  "architectures": [
+    "Qwen2ForCausalLM"
+  ],
+  "attention_dropout": 0.0,
+  "bos_token_id": 151643,
+  "eos_token_id": 151645,
+  "hidden_act": "silu",
+  "hidden_size": 1536,
+  "initializer_range": 0.02,
+  "intermediate_size": 8960,
+  "max_position_embeddings": 32768,
+  "max_window_layers": 21,
+  "model_type": "qwen2",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 28,
+  "num_key_value_heads": 2,
+  "rms_norm_eps": 1e-06,
+  "rope_scaling": null,
+  "rope_theta": 1000000.0,
+  "sliding_window": 32768,
+  "tie_word_embeddings": true,
+  "torch_dtype": "float16",
+  "transformers_version": "4.51.3",
+  "use_cache": true,
+  "use_sliding_window": false,
+  "vocab_size": 151936
+}

generation_config.json

@@ -0,0 +1,14 @@
+{
+  "bos_token_id": 151643,
+  "do_sample": true,
+  "eos_token_id": [
+    151645,
+    151643
+  ],
+  "pad_token_id": 151643,
+  "repetition_penalty": 1.1,
+  "temperature": 0.7,
+  "top_k": 20,
+  "top_p": 0.8,
+  "transformers_version": "4.51.3"
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9395579ce8f703f1812ff56215b5fb8a421dd11040c357c0b371b55ea922e5c9
+size 3087466808

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9c5ae00e602b8860cbd784ba82a8aa14e8feecec692e7076590d014d7b7fdafa
+size 11421896

tokenizer_config.json

@@ -0,0 +1,209 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "bos_token": null,
+  "chat_template": "{%- if tools %}\n    {{- '<|im_start|>system\\n' }}\n    {%- if messages[0]['role'] == 'system' %}\n        {{- messages[0]['content'] }}\n    {%- else %}\n        {{- 'You are Qwen, created by Alibaba Cloud. You are a helpful assistant.' }}\n    {%- endif %}\n    {{- \"\\n\\n# Tools\\n\\nYou may call one or more functions to assist with the user query.\\n\\nYou are provided with function signatures within <tools></tools> XML tags:\\n<tools>\" }}\n    {%- for tool in tools %}\n        {{- \"\\n\" }}\n        {{- tool | tojson }}\n    {%- endfor %}\n    {{- \"\\n</tools>\\n\\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\\n<tool_call>\\n{\\\"name\\\": <function-name>, \\\"arguments\\\": <args-json-object>}\\n</tool_call><|im_end|>\\n\" }}\n{%- else %}\n    {%- if messages[0]['role'] == 'system' %}\n        {{- '<|im_start|>system\\n' + messages[0]['content'] + '<|im_end|>\\n' }}\n    {%- else %}\n        {{- '<|im_start|>system\\nYou are Qwen, created by Alibaba Cloud. You are a helpful assistant.<|im_end|>\\n' }}\n    {%- endif %}\n{%- endif %}\n{%- for message in messages %}\n    {%- if (message.role == \"user\") or (message.role == \"system\" and not loop.first) or (message.role == \"assistant\" and not message.tool_calls) %}\n        {{- '<|im_start|>' + message.role + '\\n' + message.content + '<|im_end|>' + '\\n' }}\n    {%- elif message.role == \"assistant\" %}\n        {{- '<|im_start|>' + message.role }}\n        {%- if message.content %}\n            {{- '\\n' + message.content }}\n        {%- endif %}\n        {%- for tool_call in message.tool_calls %}\n            {%- if tool_call.function is defined %}\n                {%- set tool_call = tool_call.function %}\n            {%- endif %}\n            {{- '\\n<tool_call>\\n{\"name\": \"' }}\n            {{- tool_call.name }}\n            {{- '\", \"arguments\": ' }}\n            {{- tool_call.arguments | tojson }}\n            {{- '}\\n</tool_call>' }}\n        {%- endfor %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"tool\" %}\n        {%- if (loop.index0 == 0) or (messages[loop.index0 - 1].role != \"tool\") %}\n            {{- '<|im_start|>user' }}\n        {%- endif %}\n        {{- '\\n<tool_response>\\n' }}\n        {{- message.content }}\n        {{- '\\n</tool_response>' }}\n        {%- if loop.last or (messages[loop.index0 + 1].role != \"tool\") %}\n            {{- '<|im_end|>\\n' }}\n        {%- endif %}\n    {%- endif %}\n{%- endfor %}\n{%- if add_generation_prompt %}\n    {{- '<|im_start|>assistant\\n' }}\n{%- endif %}\n",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "extra_special_tokens": {},
+  "model_max_length": 131072,
+  "pad_token": "<|endoftext|>",
+  "padding_side": "left",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}