tier

<p align="center"> <h1 align="center">Tier</h1> <p align="center"><strong>Adaptive tool routing for AI agents of any size.</strong></p> <p align="center"> <a href="https://zenodo.org/records/19228710"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19228710.svg" alt="DOI"></a> <a href="https://pypi.org/project/yantrikos-sdk/"><img src="https://img.shields.io/pypi/v/yantrikos-sdk" alt="PyPI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a> </p> </p> --- ```bash pip install yantrikos-sdk ``` Full setup in [Quick Start](#quick-start); the OpenClaw integration is a code plugin on [ClawHub](https://clawhub.ai) — see [Production](#openclaw-plugin). ### 30-second example ```python from yantrikos import BaseTool, ToolResult, Tier, register @register class FileReadTool(BaseTool): name = "file_read" descriptions = { Tier.S: "Read file", # 1.5B model Tier.M: "Read a file from disk", Tier.L: "Read file with encoding control", Tier.XL: "Read file with line numbers, offset, encoding", # GPT-4o } parameters = { Tier.S: {"path": str}, Tier.M: {"path": str}, Tier.L: {"path": str}, Tier.XL: {"path": str, "offset": int, "limit": int}, } def execute(self, input: dict, tier: Tier) -> ToolResult: return ToolResult.ok(open(input["path"]).read()) ``` One tool definition, a different face per model tier. Full walkthrough in [Quick Start](#quick-start). ## The Problem Every AI agent framework presents **all tools identically** regardless of model size: | Model | Tools shown | Accuracy | Tokens wasted | |-------|------------|----------|---------------| | 1.5B | All 80 | **50%** | 3,400 | | 35B | All 80 | **88%** | 3,400 | A 1.5B model on a Raspberry Pi receives the same tool descriptions as a 35B model on a GPU server. The small model drowns in options. **The model isn't bad at using tools — it's bad at finding them.** ## The Insight Tool selection decomposes into two stages: ``` P(correct tool) = P(correct family) × P(correct tool | correct family) ``` The results were surprising: | Model | P(right family) | P(right tool \| family) | |-------|----------------|----------------------| | 1.5B | 56% | **89%** | | 9B | 82% | **98%** | | 20B | 84% | **95%** | | 35B | 90% | **98%** | **Even a 1.5B model picks the right tool 89% of the time — when it's looking in the right neighborhood.** The bottleneck isn't selection, it's navigation. ## The Solution **Adapt the interface, not the model.** Different model sizes get different tool presentations: ### Same 80 tools, three different presentations: | | **Tiny** (< 4B) | **Large** (14-35B) | **XL** (35B+) | |---|---|---|---| | **Strategy** | Hybrid | Reorder + hint | Full | | **What model sees** | 8 detailed + 72 name-only | All 80, relevance-sorted | All 80, full descriptions | | **file_read** | `"Read file"` `path: str` | `"Read file with encoding control"` `path, encoding, lines` | `"Read file with line numbers, offset, encoding"` `path, encoding, lines, offset, limit` | | **Accuracy** | **60%** (+10pp) | **88%** (+8pp) | **88%** (baseline) | | **Tokens** | 97% fewer | same | same | ## Results Benchmarked across **1,000+ native tool calling** inference calls (Ollama `/api/chat`), 4 models, 80 tools, 50 prompts: | Strategy | 1.5B | 9B | 20B | 35B | Tokens | |----------|------|----|-----|-----|--------| | **Baseline** (80 tools, full desc) | 50% | 80% | 80% | 88% | 2,100-5,300 | | **Hybrid** (8 detailed + 72 names) | **60%** | — | 76% | — | ~1,800 | | **Reorder + hint** | 54% | — | **88%** | — | same | | **Family oracle** (upper bound) | **70%** | **86%** | **84%** | **88%** | 400-900 | Key findings: - **Hybrid** works best for tiny models: +10pp accuracy, 97% fewer tokens - **Reorder + hint** works best for large models: +8pp, makes 20B match 35B - **No single strategy dominates** — optimal presentation is scale-dependent - **Token savings of 83-92%** with filtering strategies - **Native tool calling matters** — text injection produces different (misleading) results Full results and analysis in the [whitepaper](https://zenodo.org/records/19228710). ## Quick Start ### Install the SDK ```bash pip install yantrikos-sdk ``` ### Define a tier-aware tool ```python from yantrikos import BaseTool, ToolResult, Tier, register @register class FileReadTool(BaseTool): name = "file_read" category = "filesystem" descriptions = { Tier.S: "Read file", Tier.M: "Read a file from disk", Tier.L: "Read file with encoding control", Tier.XL: "Read file with line numbers, offset, and encoding", } parameters = { Tier.S: {"path": str}, Tier.M: {"path": str, "encoding": str}, Tier.L: {"path": str, "encoding": str, "line_numbers": bool}, Tier.XL: {"path": str, "encoding": str, "line_numbers": bool, "offset": int, "limit": int}, } def execute(self, input: dict, tier: Tier) -> ToolResult: path = input["path"] content = open(path).read() if tier == Tier.S: return ToolResult.ok(content[:1000]) else: return ToolResult.ok(content) ``` ### Route tools by model tier ```python from yantrikos import TierRouter # Auto-detects tier from model name router = TierRouter(model_name="qwen2.5:1.5b") # -> Tier.S, hybrid strategy native_tools = router.route("Read the file config.yaml") # Returns Ollama/OpenAI native tool definitions, adapted for 1.5B router_large = TierRouter(model_name="gpt-4o") # -> Tier.XL, full strategy native_tools = router_large.route("Read the file config.yaml") # Returns full tool definitions with all parameters ``` ### Auto-detect model tier ```python from yantrikos import detect_tier detect_tier("qwen3.5:0.6b") # -> Tier.S detect_tier("qwen3.5:9b") # -> Tier.M detect_tier("gpt-oss:20b") # -> Tier.L detect_tier("claude-opus-4-6") # -> Tier.XL ``` ## How It Works ### 1. Tier Detection The SDK parses model names to determine capability: | Tier | Parameters | Strategy | Max Tools | Format | |------|-----------|----------|-----------|--------| | **S** (Tiny) | < 4B | Hybrid | 8 detailed + rest name-only | Short descriptions, minimal params | | **M** (Medium) | 4-14B | Hybrid | 8 detailed + rest name-only | Condensed descriptions | | **L** (Large) | 14-35B | Reorder | All tools, relevance-sorted | Full descriptions, category hint | | **XL** (X-Large) | 35B+ | Full | All tools | Full descriptions, all params | ### 2. Tool Registration Every tool declares behavior per tier — descriptions get shorter, parameters get fewer: ```python descriptions = { Tier.S: "Search web", # 10 chars — tiny model focus Tier.M: "Search the web", # 14 chars Tier.L: "Search web for info", # 19 chars Tier.XL: "Search web with filters and date range", # 39 chars } parameters = { Tier.S: {"query": str}, # 1 param Tier.M: {"query": str, "limit": int}, # 2 params Tier.L: {"query": str, "limit": int}, # 2 params Tier.XL: {"query": str, "limit": int, "date": str}, # 3 params } ``` ### 3. Native Tool Export Tools export as OpenAI/Ollama native format — ready for `/api/chat`: ```python from yantrikos import to_native_tool, Tier native = to_native_tool(my_tool, Tier.S) # { # "type": "function", # "function": { # "name": "web_search", # "description": "Search web", # "parameters": { # "type": "object", # "properties": {"query": {"type": "string"}}, # "required": ["query"] # } # } # } ``` ### 4. Routing Strategies The `TierRouter` selects the best strategy per tier: **Hybrid (Tiny/Medium):** Top-K semantically relevant tools get full descriptions. The rest appear as name-only entries. The model focuses on the best candidates but can still pick from the full set. **Reorder (Large):** All tools are presented, but sorted by semantic relevance to the query. Most likely tools appear first. Combined with a system prompt category hint for +8pp accuracy. **Full (XL):** All tools with full descriptions. Large models don't need adaptation. ## The Specification ### Tool Requirements Every tool built with the SDK must declare: 1. **`name`** — unique tool identifier 2. **`category`** — semantic family (filesystem, web, code, data, etc.) 3. **`descriptions`** — one per tier, shortest for S, longest for XL 4. **`parameters`** — one set per tier, fewest for S, most for XL 5. **`execute(input, tier)`** — tier-aware execution ### Design Guidelines 1. **Descriptions should be discriminative, not exhaustive.** For Tier.S, use the 2-3 words that distinguish this tool from all others. 2. **First parameter is always the most important one.** It's the only one a tiny model sees. 3. **Categories should be semantically distinct.** Don't put CSV tools in both "filesystem" and "data." 4. **Test at Tier.S.** If a 1.5B model can't pick your tool from its short description, rewrite it. ### Validation The SDK validates tools at registration: ```python @register # Raises ToolValidationError if: class MyTool(BaseTool): # - name is empty # - any tier is missing a description # - Tier.S has more params than Tier.XL # - descriptions or parameters dict is empty ``` ## Production ### YantrikOS The tier architecture originates from [YantrikOS](https://github.com/yantrikos/yantrik-os), an AI-native desktop OS (under active development) with **116+ tools** across 48 categories, designed for models from 0.8B to 35B+. The `ModelCapabilityProfile` adapts six dimensions: tool count, call format, slot extraction, family routing, context budget, and confidence thresholds. YantrikOS addresses the family detection bottleneck through `discover_tools` — a meta-tool that lets models navigate the tool space iteratively with self-correction. ### OpenClaw Plugin The Tier plugin is available on [ClawHub](https://clawhub.ai) as a code plugin. It integrates the SDK with OpenClaw's gateway, automatically adapting tool presentation based on the configured model. ## Benchmark Reproduction ```bash git clone https://github.com/yantrikos/tier cd tier pip install yantrikos-sdk yantrikdb sentence-transformers python benchmarks/harness_v3.py ``` Raw results (1,000+ data points): [`benchmarks/results_v3_full.jsonl`](benchmarks/results_v3_full.jsonl) ## Citation ```bibtex @misc{sarkar2026tier, author = {Sarkar, Pranab}, title = {Tier-Based Adaptive Tool Routing for Capability-Heterogeneous AI Agents}, year = {2026}, publisher = {Zenodo}, doi = {10.5281/zenodo.19228710}, url = {https://zenodo.org/records/19228710} } ``` ## Related projects Other agent infrastructure by the same author: - [contextcache](https://github.com/spranab/contextcache) — the other half of the tool-cost problem: cache the KV states of tool schemas so they aren't re-prefilled on every request. - [yantrikdb](https://github.com/yantrikos/yantrikdb) — cognitive memory engine for agents: temporal decay, contradiction detection, consolidation. - [yantrikdb-mcp](https://github.com/yantrikos/yantrikdb-mcp) — that memory as an MCP server for Claude Code, Cursor and Windsurf. - [yantrik-memory](https://github.com/yantrikos/yantrik-memory) — framework-agnostic Python memory layer with traits and bond evolution. - [truenas-mcp](https://github.com/spranab/truenas-mcp) — 278 actions behind one hierarchical MCP tool; the same "don't show the model everything" idea. ## License MIT