Streamline model card: remove duplication, improve flow, make more concise

README.md

@@ -15,108 +15,48 @@ metrics:
 
 # Chayan: Multi-Model LLM Router
 
-**Chayan** is a high-performance LLM router that intelligently selects between 4 models (gpt-4o-mini, gemini-2.5-flash-lite, gemini-2.5-flash, and gpt-4o) to optimize the accuracy-cost tradeoff.
+**Chayan** is a high-performance LLM router that intelligently routes between 4 models (gpt-4o-mini, gemini-2.5-flash-lite, gemini-2.5-flash, and gpt-4o) to optimize the accuracy-cost tradeoff.
 
-## Performance
+## 🏆 RouterArena Performance
 
-🏆 **SOTA on RouterArena: #1 Optimal Accuracy Score, #2 Optimal Selection**
-
-Official RouterArena Full Dataset Results (8,400 queries):
-- **88.7% Optimal Accuracy Score** - 🥇 #1 SOTA! (Best routing decision quality)
-- **43.0% Optimal Selection Score** - 🥈 #2 Silver! (Second-best model selection)
-- **64.9% Overall Accuracy** - #7 overall, #5 among open-source routers
-- **Arena Score: 63.8** - #7 overall, #5 among open-source routers
+**Official Leaderboard Results** (8,400 queries):
+- 🥇 **#1 Optimal Accuracy Score: 88.7%** - SOTA! (Best routing decision quality)
+- 🥈 **#2 Optimal Selection Score: 43.0%** - Silver! (Second-best model selection)
+- **#7 Overall** (#5 open-source): 64.9% accuracy, 63.8 arena score
 - **$0.60 per 1K queries** - Cost-efficient routing
 
-**Key Metrics Explained:**
-- **Optimal Accuracy Score**: When Chayan routes to a model, that model gives the correct answer 88.7% of the time (highest on leaderboard!)
-- **Optimal Selection Score**: Chayan selects the best available model 43% of the time (second-best on leaderboard)
-
-Sub_10 Benchmark (809 queries):
-- **69.05% accuracy**
-- **$0.333 per 1K queries** (estimated cost)
-- **+7.62pp improvement** over baseline 2-model router
-- Achieves **99% of theoretical perfect oracle performance**
-
-## Model Architecture
-
-Chayan uses an adaptive K-NN classifier built on:
-- **Base model**: BERT-base-uncased embeddings
-- **Classification approach**: Prototype-based memory with FAISS indexing
-- **Key innovation**: Calibrated confidence scores to correct for training data imbalance
-
-### Supported Models
-
-| Model | Use Case | Cost/1M tokens |
-|-------|----------|----------------|
-| openai/gpt-4o-mini | Simple queries | $0.15 |
-| google/gemini-2.5-flash-lite | Medium complexity | $0.075 |
-| google/gemini-2.5-flash | Higher complexity | $0.30 |
-| openai/gpt-4o | Complex queries | $2.50 |
-
-## Training Methodology
-
-### Dataset
-- **Source**: RouterArena sub_10 split (809 queries)
-- **Oracle labels**: Generated using 4-model cascade strategy (select cheapest successful model)
-- **Features**: Query length, word count, math indicators, sentence count, multiple choice markers
-
-### Training Process
-1. **Multi-class classification**: Trained to predict one of 4 models
-2. **Memory-based learning**: K-NN classifier with prototype storage
-3. **Calibration optimization**: Grid search over 625 configurations to find optimal confidence score adjustments
-
-### The Calibration Breakthrough
-
-The uncalibrated router achieved only 61.76% accuracy due to heavy bias toward gpt-4o-mini (83% routing). By applying calibrated confidence scores, we corrected for training data imbalance and achieved 69.05% accuracy.
+![RouterArena Leaderboard](routerarena_leaderboard.png)
 
-**Optimal Calibration Factors:**
-```python
-calibration = {
-    "openai/gpt-4o-mini": 0.9,
-    "google/gemini-2.5-flash-lite": 1.5,
-    "google/gemini-2.5-flash": 1.8,
-    "openai/gpt-4o": 1.5
-}
-```
+**What do these metrics mean?**
+- **Optimal Accuracy**: When Chayan routes to a model, that model gives the correct answer 88.7% of the time
+- **Optimal Selection**: Chayan selects the best available model 43% of the time
 
-## Usage
+View full leaderboard: [RouterArena](https://routeworks.github.io/) | [PR #24](https://github.com/RouteWorks/RouterArena/pull/24)
 
-### Installation
+## Quick Start
 
 ```bash
 pip install adaptive-classifier
 ```
 
-### Basic Usage
-
 ```python
 from adaptive_classifier import AdaptiveClassifier
 
-# Load the router
+# Load router
 router = AdaptiveClassifier.load("adaptive-classifier/chayan")
 
-# Get routing decision with top-4 predictions
+# Get routing decision
 query = "What is the capital of France?"
 predictions = router.predict(query, k=4)
 
-# predictions is a list of (model_name, confidence) tuples
-# [(model1, score1), (model2, score2), (model3, score3), (model4, score4)]
-
-# Select top model
-selected_model = predictions[0][0]
-print(f"Route to: {selected_model}")
+# Route to top model
+selected_model = predictions[0][0]  # e.g., "openai/gpt-4o-mini"
 ```
 
-### Usage with Calibration (Recommended)
+### Recommended: Use with Calibration
 
 ```python
-from adaptive_classifier import AdaptiveClassifier
-
-# Load router
-router = AdaptiveClassifier.load("adaptive-classifier/chayan")
-
-# Define calibration factors
+# Apply calibration factors for best performance
 calibration = {
     "openai/gpt-4o-mini": 0.9,
     "google/gemini-2.5-flash-lite": 1.5,
@@ -124,124 +64,108 @@ calibration = {
     "openai/gpt-4o": 1.5
 }
 
-# Get predictions
-query = "Explain quantum entanglement in simple terms"
 predictions = router.predict(query, k=4)
-
-# Apply calibration
-calibrated_scores = {
-    model: score * calibration.get(model, 1.0)
-    for model, score in predictions
-}
-
-# Select model with highest calibrated score
+calibrated_scores = {model: score * calibration[model] for model, score in predictions}
 selected_model = max(calibrated_scores.items(), key=lambda x: x[1])[0]
-print(f"Route to: {selected_model}")
 ```
 
-### Feature Augmentation
-
-The router was trained with query features prepended as text tokens:
+## Architecture
 
-```python
-from adaptive_classifier.complexity_features import augment_query_with_features
+**Core Components:**
+- **Base Model**: BERT-base-uncased embeddings
+- **Classifier**: Adaptive K-NN with prototype memory (FAISS-backed)
+- **Innovation**: Calibrated confidence scores to correct training data imbalance
 
-query = "What is 2+2?"
-augmented = augment_query_with_features(query)
-# Returns: "[LEN:12][WORDS:3][MATH:1][SENT:1][MC:0] What is 2+2?"
+**Supported Models:**
 
-# Use augmented query for routing
-predictions = router.predict(augmented, k=4)
-```
+| Model | Use Case | Cost/1M tokens |
+|-------|----------|----------------|
+| openai/gpt-4o-mini | Simple queries | $0.15 |
+| google/gemini-2.5-flash-lite | Medium complexity | $0.075 |
+| google/gemini-2.5-flash | Higher complexity | $0.30 |
+| openai/gpt-4o | Complex queries | $2.50 |
 
-## Performance Comparison
+## How It Works
 
-| Router | Accuracy | Cost/1K | Notes |
-|--------|----------|---------|-------|
-| All gpt-4o-mini | 56.98% | $0.088 | Baseline |
-| 2-model router | 61.43% | $0.217 | Previous best |
-| **Chayan (uncalibrated)** | 61.76% | $0.269 | Biased toward mini |
-| **Chayan (calibrated)** | **69.05%** | **$0.333** | **Optimal** |
-| Perfect 2-model oracle | 69.84% | $0.784 | Theoretical max |
-| Perfect 4-model cascade | 76.51% | $0.553 | Theoretical max |
+### Training
+- **Dataset**: RouterArena sub_10 (809 queries)
+- **Oracle Labels**: 4-model cascade strategy (select cheapest successful model)
+- **Training Time**: 19.2 minutes
+- **Method**: K-NN classifier with 3000 prototypes, temperature 0.4
 
-## RouterArena Leaderboard
+### The Calibration Breakthrough
 
-🏆 **Official Results - #1 Optimal Accuracy, #2 Optimal Selection**
+The uncalibrated router achieved 61.76% accuracy but was biased toward gpt-4o-mini (83% routing). This happened because the training data had class imbalance:
+- 57% gpt-4o-mini examples
+- 27% gpt-4o examples
+- 12% gemini-flash-lite examples
+- 4% gemini-flash examples
 
-![RouterArena Leaderboard](routerarena_leaderboard.png)
+**Solution**: Apply post-training calibration factors to correct the bias without retraining.
 
-Chayan on the official [RouterArena leaderboard](https://routeworks.github.io/) (sorted by Optimal Accuracy):
+**Result**: +7.29pp improvement (61.76% → 69.05% on sub_10 benchmark)
 
-| Rank | Router | **Opt. Acc** | **Opt. Select** | Accuracy | Arena Score | Cost/1k | Type |
-|------|--------|--------------|-----------------|----------|-------------|---------|------|
-| **1** | **Chayan** | **88.7%** 🥇 | **43.0%** 🥈 | 64.9% | 63.8 | $0.60 | Open-Source |
-| 2 | RouterBench-MLP | 83.3% | 13.4% | 61.6% | 57.6 | $4.80 | Open-Source |
-| 3 | Azure | 82.0% | 22.5% | 68.1% | 66.7 | $0.50 | Closed-Source |
-| 4 | vLLM-SR | 79.3% | 4.8% | 67.3% | 64.3 | $1.70 | Open-Source |
-| 5 | RouterBench-KNN | 78.8% | 13.1% | 58.7% | 55.5 | $4.30 | Open-Source |
+## Performance Benchmarks
 
-**Overall Rankings:**
-- **Optimal Accuracy Score**: 🥇 #1 (88.7% - SOTA!)
-- **Optimal Selection Score**: 🥈 #2 (43.0% - Silver!)
-- **Overall Accuracy**: #7 overall, #5 among open-source
-- **Arena Score**: #7 overall, #5 among open-source
+**Sub_10 Benchmark (809 queries):**
 
-**🥇 SOTA Achievement - Optimal Accuracy Score**: Chayan achieves **88.7%**, the highest score among all routers. This measures routing decision quality - when Chayan routes to a model, that model gives the correct answer 88.7% of the time.
+| Router | Accuracy | Cost/1K |
+|--------|----------|---------|
+| All gpt-4o-mini (baseline) | 56.98% | $0.088 |
+| 2-model router | 61.43% | $0.217 |
+| Chayan (uncalibrated) | 61.76% | $0.269 |
+| **Chayan (calibrated)** | **69.05%** | **$0.333** |
+| Perfect 2-model oracle | 69.84% | $0.784 |
 
-**🥈 Silver Medal - Optimal Selection Score**: Chayan ranks **#2** with **43.0%**, meaning it selects the optimal model (best among all available models) 43% of the time, second only to Azure's 46.3%.
+**Key Insight**: Chayan achieves 99% of perfect oracle performance at 57% lower cost.
 
-View the full leaderboard and PR: [RouterArena PR #24](https://github.com/RouteWorks/RouterArena/pull/24)
+**Full Dataset (8,400 queries):**
+- **Optimal Accuracy**: 88.7% (🥇 #1)
+- **Optimal Selection**: 43.0% (🥈 #2)
+- **Overall Accuracy**: 64.9% (#7 overall, #5 open-source)
+- **Cost**: $0.60/1K queries
 
-## Technical Insights
+## Advanced Usage
 
-### Why Calibration Works
+### Feature Augmentation
 
-The router learned good semantic representations, but the decision boundaries were miscalibrated due to class imbalance in training data:
-- 57% gpt-4o-mini examples
-- 27% gpt-4o examples
-- 12% gemini-flash-lite examples
-- 4% gemini-flash examples
+Chayan was trained with query features prepended as tokens:
 
-K-NN classifiers are sensitive to class imbalance. By applying calibration factors post-training, we corrected the bias without retraining, unlocking a +7.29pp improvement.
+```python
+from adaptive_classifier.complexity_features import augment_query_with_features
 
-### Model Details
+query = "What is 2+2?"
+augmented = augment_query_with_features(query)
+# Returns: "[LEN:12][WORDS:3][MATH:1][SENT:1][MC:0] What is 2+2?"
 
-- **Training time**: 19.2 minutes
-- **Training examples**: 809 queries
-- **Memory size**: 3000 prototypes
-- **Temperature**: 0.4
-- **Distance metric**: Cosine similarity
-- **Embeddings**: Normalized BERT-base-uncased
+predictions = router.predict(augmented, k=4)
+```
 
 ## Limitations
 
-- Calibration factors were optimized on RouterArena sub_10 split and may not generalize perfectly to other domains
-- Router assumes the 4 specific models are available via API
-- Performance depends on query distribution matching RouterArena benchmark
+- Calibration factors optimized on RouterArena sub_10; may require adjustment for other domains
+- Requires the 4 specific models to be available via API
+- Performance depends on query distribution similar to RouterArena benchmark
 - Cost estimates assume ~500 tokens per query
 
 ## Citation
 
-If you use Chayan in your research or applications, please cite:
-
 ```bibtex
 @software{chayan_router_2025,
   title = {Chayan: Calibrated Multi-Model LLM Router},
   author = {Adaptive Classifier Team},
   year = {2025},
   url = {https://huggingface.co/adaptive-classifier/chayan},
-  note = {High-performance LLM router achieving 69.05\% accuracy on RouterArena}
+  note = {SOTA LLM router: 88.7\% optimal accuracy on RouterArena}
 }
 ```
 
-## License
-
-MIT License
-
 ## Links
 
-- **Model Repository**: https://huggingface.co/adaptive-classifier/chayan
 - **Library**: https://github.com/codelion/adaptive-classifier
 - **RouterArena**: https://routeworks.github.io/
 - **RouterArena Paper**: https://arxiv.org/abs/2510.00202
+
+## License
+
+MIT License