Create README.md

README.md

@@ -0,0 +1,201 @@
+---
+language:
+  - en
+license: apache-2.0
+library_name: transformers
+tags:
+  - cross-encoder
+  - reranker
+  - thread-matching
+  - conversational-ai
+  - lora
+  - peft
+  - onnx
+pipeline_tag: text-classification
+datasets:
+  - Algokruti/thread-reranker-data
+base_model: nreimers/MiniLM-L6-H384-uncased
+model-index:
+  - name: thread-reranker
+    results:
+      - task:
+          type: text-classification
+          name: Thread Relevance Ranking
+        dataset:
+          name: thread-reranker-data
+          type: Algokruti/thread-reranker-data
+          split: test
+        metrics:
+          - name: Hit Rate @ 1 (Overall)
+            type: accuracy
+            value: 0.9049
+          - name: Hit Rate @ 1 (Easy)
+            type: accuracy
+            value: 1.0000
+          - name: Hit Rate @ 1 (Medium)
+            type: accuracy
+            value: 0.8211
+          - name: Hit Rate @ 1 (Hard)
+            type: accuracy
+            value: 0.8413
+---
+
+# Thread Reranker
+
+A cross-encoder reranker that scores how relevant a conversation thread is to a new user message. Designed for unified conversation architectures where a single chat stream replaces explicit thread management — the model determines which internal thread a message belongs to so the right context can be retrieved automatically.
+
+## How It Works
+
+In a unified conversation system, users interact through a single continuous chat. Behind the scenes, the system maintains multiple internal threads (topics the user has discussed before). When a new message arrives, candidate threads are retrieved using fast heuristics (entity matching, recency, flow continuity), and this reranker scores each candidate to pick the best match.
+
+The model takes two inputs simultaneously: the text pair (user message + thread summary) processed through the encoder, and structured retrieval features computed by the upstream pipeline. It fuses both signals to produce a relevance score.
+
+### Architecture
+
+```
+User Message + Thread Summary ──► MiniLM-L6 (frozen + LoRA r=8) ──► CLS token ──┐
+                                                                                  ├──► MLP Head ──► Score
+Step 3 Structured Features ──────► Feature Projection (Linear→ReLU→Linear) ──────┘
+```
+
+**Base model:** nreimers/MiniLM-L6-H384-uncased (22M parameters, encoder-only)
+
+**LoRA configuration:** Rank 8, alpha 16, applied to query and value projections, dropout 0.1
+
+**Structured features (5 inputs):**
+- `entity_overlap` — count of thread entities found in the user message
+- `keyword_matches` — keyword overlap between message and thread content
+- `flow_continuity` — 1.0 if this thread was the most recently active, 0.0 otherwise
+- `recency_score` — exponential decay score based on hours since thread was last active
+- `hours_since_active` — raw hours since thread was last active
+
+## Intended Use
+
+This model is one component in a 7-step unified conversation pipeline:
+
+1. **User sends message** — single chat stream, no thread selector
+2. **Entity & signal extraction** — lightweight NER and pattern matching (no ML)
+3. **Layered context retrieval** — database queries using entity match, recency, flow continuity
+4. **Reranker (this model)** — scores candidate threads from Step 3
+5. **Confidence threshold** — auto-select if confident, ask user if ambiguous
+6. **LLM responds** — with the correct thread context injected
+7. **Update thread store** — extract new entities and facts, write back to database
+
+The model only fires when the deterministic heuristics in Step 3 produce multiple plausible candidates. Clear-cut cases (unique entity match + high recency) are resolved without the model.
+
+## Performance
+
+Evaluated on synthetic test data with three difficulty tiers:
+
+| Difficulty | Hit Rate @ 1 | Description |
+|---|---|---|
+| **Easy** | 100.0% | Message contains explicit entity references ("fix the React bug") |
+| **Medium** | 82.1% | Indirect references ("that bug we were debugging") |
+| **Hard** | 84.1% | No entity signal, relies on recency and flow ("let's keep going") |
+| **Overall** | 90.5% | Weighted across all tiers |
+
+**Note:** In the hybrid pipeline, easy cases are handled by deterministic heuristics without calling the model. The model's effective contribution is on medium and hard cases, where the combined system achieves 95%+ accuracy when including heuristic pre-filtering.
+
+## Training
+
+**Dataset:** Algokruti/thread-reranker-data — 50,543 synthetic examples (12,500 positive, 38,043 negative) generated from 500 simulated user profiles across 12 topic types in 5 domains.
+
+**Training strategy:** Curriculum learning — epochs 1-2 trained on easy examples only, epochs 3-5 on all difficulty tiers. Binary cross-entropy loss with cosine learning rate schedule and warmup.
+
+**Hyperparameters:**
+- Batch size: 64
+- Learning rate: 2e-4
+- Epochs: 5 (2 curriculum + 3 full)
+- Max sequence length: 256
+- LoRA rank: 8, alpha: 16
+- Optimizer: AdamW with weight decay 0.01
+- Gradient clipping: max norm 1.0
+
+**Training domains covered:**
+- Web Development (React Dashboard, Authentication, CSS Grid)
+- Backend Development (Python API, Docker Deployment)
+- Personal (Meal Planning, Job Search, Fitness)
+- Data Science (ML Training, Data Pipeline)
+- Mobile Development (iOS/Swift, Android/Kotlin)
+
+## Limitations
+
+- **Trained on synthetic data only.** Performance on real user conversations may differ, particularly for domains and linguistic patterns not represented in the training set.
+- **Limited domain coverage.** 12 topics across 5 domains, heavily skewed toward software development. Non-technical topics (travel, health, education, finance, creative writing) are underrepresented.
+- **English only.** Not tested on multilingual conversations.
+- **Cold start.** With no conversation history, the model has nothing to rank. The system falls back to treating each message as a new thread.
+- **Ambiguity resolution.** On genuinely ambiguous messages with no entity, recency, or flow signal, the model may select incorrectly. The confidence threshold mechanism is designed to catch these cases and ask the user instead.
+
+## How to Use
+
+### PyTorch Inference
+
+```python
+import torch
+from transformers import AutoTokenizer, AutoModel
+from peft import PeftModel
+
+# Load model and tokenizer
+tokenizer = AutoTokenizer.from_pretrained("nreimers/MiniLM-L6-H384-uncased")
+
+# Load the full ThreadReranker (see training notebook for class definition)
+model = ThreadReranker()
+model.load_state_dict(torch.load("model.pt", map_location="cpu"))
+model.eval()
+
+# Score a message against a candidate thread
+message = "can you fix that chart rendering issue"
+thread_text = "Building a metrics dashboard with Chart.js | the bar chart overflows on mobile | React, Chart.js"
+
+encoding = tokenizer(message, thread_text, max_length=256,
+                     padding="max_length", truncation=True, return_tensors="pt")
+
+features = torch.tensor([[1.0, 1.0, 1.0, 0.92, 2.0]])  # Step 3 features
+
+with torch.no_grad():
+    score = torch.sigmoid(model(encoding["input_ids"], encoding["attention_mask"], features))
+
+print(f"Relevance score: {score.item():.4f}")
+```
+
+### ONNX Inference (On-Device)
+
+```python
+import onnxruntime as ort
+import numpy as np
+
+session = ort.InferenceSession("thread_reranker.onnx")
+
+# Prepare inputs (tokenized text + structured features)
+result = session.run(None, {
+    "input_ids": input_ids_np,
+    "attention_mask": attention_mask_np,
+    "structured_features": features_np,
+})
+
+score = 1 / (1 + np.exp(-result[0]))  # sigmoid
+```
+
+## Files
+
+| File | Description |
+|---|---|
+| `model.pt` | PyTorch model weights (base + LoRA merged + classification head) |
+| `thread_reranker.onnx` | ONNX export for on-device inference |
+| `config.json` | Model configuration and feature definitions |
+| `training_history.json` | Per-epoch training and validation metrics |
+| `tokenizer.json` | Tokenizer files |
+
+## Citation
+
+If you use this model, please reference the training dataset:
+
+```
+@misc{thread-reranker-2026,
+  title={Thread Reranker: Cross-Encoder for Unified Conversation Thread Matching},
+  author={Algokruti},
+  year={2026},
+  publisher={Hugging Face},
+  url={https://huggingface.co/Algokruti/thread-reranker}
+}
+```