Needle v2 Hinglish action router
A fine-tune of Cactus-Compute/needle3 plus the router code around
it: a customer-support record and a (Hinglish) customer transcript go in, resolved write calls come out (for example
cancel_order on order FD4124), or a request to ask the customer when a reference cannot be resolved. Runs on CPU.
Model description
Intended use
Files
| file | size | md5 | what |
|---|---|---|---|
tuned_full.cact |
63,437,076 B | 5361a65ba4703689e0ff1428a8f3dea4 |
the model: needle3 + the R_e15 LoRA merged, W4A8 (the live demo's router) |
n1/tuned_full.cact |
63,437,076 B | 92ddd0d787388b07db831a7da6114aba |
Needle N1, the earlier v1 router (5 agent types): the live worker's rollback (S2S_ROUTER=n1) |
adapter/adapter_R_e15.safetensors |
7,906,616 B | 4e89cbcc83769681fa1cc6664481a7dd |
the LoRA it was built from (needle build needle3.safetensors --lora adapter_R_e15.safetensors) |
examples/food_01.json |
one synthetic record |
This repo holds no code (weights, examples and this card only). The router code (router_v2, resolver_v2, tool
schemas for the 7 agent types, numconv, romanise and the N1 helpers) is the pip package
packages/needle_router in the GitHub monorepo.
Sweep checkpoints
Every adapter from the fine-tune sweep (training sets A / B / R x 3 / 6 / 10 epochs, plus R at 15 epochs), each with
the .cact built from it the same way as tuned_full.cact.
| path | what |
|---|---|
checkpoints/<A_e3, A_e6, A_e10, B_e3, B_e6, B_e10, R_e3, R_e6, R_e10, R_e15>/adapter.safetensors |
the LoRA (7,906,616 B each) |
checkpoints/<same>/full.cact |
needle3 + that LoRA merged, W4A8 (63,437,076 B each); R_e15/full.cact = root tuned_full.cact |
checkpoints/summaries/val_losses_*.json |
validation losses per sweep run (clean / Opus / R sets) |
checkpoints/summaries/engine_val_*.json |
engine-decoded validation results per .cact (incl. tuned_l8, not uploaded) |
checkpoints/summaries/selection.json |
one row per sweep run: val loss, engine-val counts on 120 rows, train time (R_e15 is the one shipped at the root) |
Use a specific checkpoint:
from huggingface_hub import hf_hub_download
w = hf_hub_download("shivamgupta/needle-hinglish-router-v2", "full.cact", subfolder="checkpoints/R_e6")
calls = needle_router.route(record["agent_type"], record, transcript, weights=w)
Agent types: food_delivery_support, ecommerce_support, cab_ride_support, subscription_account_support,
airport_ticket_counter, bank_card_support, telecom_prepaid_support.
Quickstart / How to run
The code lives in the GitHub monorepo
shivamgcodes/s2s-hinglish-agent.
pip install "git+https://github.com/shivamgcodes/s2s-hinglish-agent#subdirectory=packages/needle_router" huggingface_hub # pulls cactus-needle==3.0.6
import json, needle_router
from huggingface_hub import hf_hub_download
w = hf_hub_download("shivamgupta/needle-hinglish-router-v2", "tuned_full.cact")
record = json.load(open(hf_hub_download("shivamgupta/needle-hinglish-router-v2", "examples/food_01.json")))
transcript = "mujhe order cancel karna hai. order cancel karna hai. I want to cancel the order"
for c in needle_router.route(record["agent_type"], record, transcript, weights=w):
print(c["name"], c["resolved_id"], c["server_args"], c["ask"], c["ask_reasons"])
# cancel_order FD4124 {'order_id': 'FD4124'} False []
Checked 2026-10-07 on CPU in a fresh venv with only the package + huggingface_hub. The full example (raw model calls,
the transcript the model sees) is
research/inference/needle_router/example.py.
- The transcript can be raw ASR text in Devanagari, Roman Hinglish or English; the router converts spoken numbers to
digits and romanises Devanagari itself (
needle_router.prepare_transcriptshows the text the model sees). - Each call has
name,arguments(as the model emitted them),server_args(resolved values),refs,askandask_reasons. Do not execute a call withask: true; ask the customer instead. - Needle N1 (
n1/tuned_full.cact):needle_router.n1_router().route(agent_type, record, transcript, weights=...). - On first use
cactus-needledownloads its native library. It also sends anonymous usage counts; setNEEDLE_TELEMETRY=0to turn that off.
In the live demo the router runs in the GPU worker (deploy/worker/router/router_core.py)
on the ASR text of the customer's last 30 s whenever the speech model says a check-line; the image pins this repo at a
commit and downloads only tuned_full.cact + n1/tuned_full.cact. Training and eval code:
research/needle/.
Training data
Built from the V4/ calls of shivamgupta/hinglish-s2s-synthetic-calls: 30 s customer-audio windows ending at each agent check-line, transcribed with Trelis Whisper-Hinglish (clean and Opus-degraded). The window/row-building code is in the GitHub repo under research/needle/n2/.
Training procedure
Evaluation results
Limitations and risks
Links
- Live demo (passcode-protected): https://shivamgupta-hinglish-agent.hf.space
- Code (training, data generation, evaluation, the pip packages, GPU worker, Space, web client): https://github.com/shivamgcodes/s2s-hinglish-agent
- Companion speech model: https://huggingface.co/shivamgupta/personaplex-hinglish-v4-lora
Base model and license
- Base model: Cactus-Compute/needle3 (Apache-2.0), run with the
cactus-needlepackage 3.0.6. - This model and the code in this repo: Apache-2.0.
Citation
Model tree for shivamgupta/needle-hinglish-router-v2
Base model
Cactus-Compute/needle3