Cactus Hybrid is a small on-device model that embeds a confidence probe inside its checkpoint, enabling it to route low-confidence queries to a larger model while returning structured confidence scores.

Stars

180

7-day growth

No data

Forks

3

Open issues

1

License

MIT

Last updated

2026-07-23

Why it is worth attention

It provides a practical hybrid inference system where a small model can match a much larger one (Gemini 3.1 Flash-Lite) by routing only 15–55% of queries, and it achieves strong confidence calibration (AUROC 0.814 mean) even on unseen modalities like audio.

Who it is for

  • Developers building edge or on-device AI applications
  • ML engineers optimizing cost and latency in production
  • Researchers studying confidence estimation and model routing
  • Users seeking private, local inference with automatic fallback

Use cases

  • On-device question answering with automatic handoff to cloud API when uncertain
  • Cost-sensitive inference pipelines that minimize large model calls
  • Private local AI assistant that only escalates when necessary
  • Multi-modal tasks (text, vision, audio) requiring calibrated confidence

Strengths

  • Built-in structured confidence scores (0–1) without parsing answer text
  • Achieves 0.814 mean AUROC across text, vision, and audio benchmarks, including zero-shot audio
  • Small model (Gemma 4 E2B) matches Gemini 3.1 Flash-Lite with only 15–55% handoff
  • Open-source (MIT) with ready-to-use integrations (Python, MLX, Transformers, llama.cpp)

Considerations

  • Quantization degrades handoff rates, requiring benchmarking for different quantization methods
  • Transformers integration requires a specific version range (5.5.4–5.6) and explicit device placement
  • llama.cpp support requires manually applying a patch to the engine

README quick start

Cactus Hybrid

A small, on-device model is fast and private, but sometimes wrong. At Cactus we post-train models to know when they are wrong: we ship probes inside the checkpoint that score every answer with a confidence between 0 and 1, returned as structured data (never parsed out of the answer text). Answer on-device when confidence is high; you can re-route to a bigger model when it's low:

if confidence ", answer)[-1]
answer = re.sub(r"^(thought|final)\b\s*", "", answer).strip()
print(answer)
print("confidence:", model.last_confidence)

Transformers

# pip install "transformers>=5.5.4,<5.6" torch   (5.14+ segfaults on this checkpoint)
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "Cactus-Compute/gemma-4-e2b-it-hybrid"
device = "cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu"

tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(model_id, trust_remote_code=True, dtype="auto").to(device)

messages = [{"role": "user", "content": "What is the capital of France?"}]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(device)
out = model.generate(**inputs, return_confidence=True, max_new_tokens=512)

print(tokenizer.decode(out.sequences[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))
print("confidence:", out.confidence)

Load the model with an explicit .to(device), not device_map="auto": the probe scores generations outside the module forward() path, so weights that accelerate offloads (left on the meta device) crash the confidence read.

llama.cpp

llama.cpp is C++, so the probe is a patch you compile into the engine (see patches/llama.cpp/). Build the patched server once:

git clone https://github.com/cactus-compute/cactus-hybrid && cd cactus-hybrid
./patches/llama.cpp/install.sh && rehash

Then serve and query it like any llama-server — the response carries a top-level confidence field:

llama-server -hf Cactus-Compute/gemma-4-e2b-it-hybrid-GGUF:Q4_K_M --jinja
curl -s http://localhost:8080/v1/chat/completions \
  -d '{"messages":[{"role":"user","content":"What is the capital of France?"}],"max_tokens":512}' \
  |

Description

On-device models that know when they're wrong: every answer carries a confidence score for cloud handoff.

Related repositories

Similar projects matched by category, topics, and programming language.

jamesob
Featured
jamesob GitHub avatar

local-llm

A comprehensive guide for building and configuring a high-end local machine to run state-of-the-art LLMs, with detailed hardware choices, BIOS tuning, and Docker-based model serving.

AI & Machine LearningLarge Language Models
1,520
programmersd21
Featured
programmersd21 GitHub avatar

flow

A terminal dashboard that shows your internet throughput in real time, with a deliberately minimal interface designed to be understood within one second.

Developer ToolsCLI & Terminal
66
xai-org
Featured
xai-org GitHub avatar

grok-build

Grok Build is SpaceXAI's terminal-based AI coding agent that runs as a full-screen TUI, understands codebases, edits files, executes commands, searches the web, and manages tasks interactively or headlessly.

AI & Machine LearningAI Agents
20,399