Instructions to use badtheorylabs/BTL-4-Compact with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- llama.cpp
How to use badtheorylabs/BTL-4-Compact with llama.cpp:
Install (macOS, Linux)
curl -LsSf https://llama.app/install.sh | sh # Start a local OpenAI-compatible server with a web UI: llama serve -hf badtheorylabs/BTL-4-Compact:IQ2_XXS # Run inference directly in the terminal: llama cli -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Install from WinGet (Windows)
winget install llama.cpp # Start a local OpenAI-compatible server with a web UI: llama serve -hf badtheorylabs/BTL-4-Compact:IQ2_XXS # Run inference directly in the terminal: llama cli -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Use pre-built binary
# Download pre-built binary from: # https://github.com/ggerganov/llama.cpp/releases # Start a local OpenAI-compatible server with a web UI: ./llama-server -hf badtheorylabs/BTL-4-Compact:IQ2_XXS # Run inference directly in the terminal: ./llama-cli -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Build from source code
git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp cmake -B build cmake --build build -j --target llama-server llama-cli # Start a local OpenAI-compatible server with a web UI: ./build/bin/llama-server -hf badtheorylabs/BTL-4-Compact:IQ2_XXS # Run inference directly in the terminal: ./build/bin/llama-cli -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Use Docker
docker model run hf.co/badtheorylabs/BTL-4-Compact:IQ2_XXS
- LM Studio
- Jan
- vLLM
How to use badtheorylabs/BTL-4-Compact with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "badtheorylabs/BTL-4-Compact" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "badtheorylabs/BTL-4-Compact", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker
docker model run hf.co/badtheorylabs/BTL-4-Compact:IQ2_XXS
- Ollama
How to use badtheorylabs/BTL-4-Compact with Ollama:
ollama run hf.co/badtheorylabs/BTL-4-Compact:IQ2_XXS
- Unsloth Studio
How to use badtheorylabs/BTL-4-Compact with Unsloth Studio:
Install Unsloth Studio (macOS, Linux, WSL)
curl -fsSL https://unsloth.ai/install.sh | sh # Run unsloth studio unsloth studio -H 0.0.0.0 -p 8888 # Then open http://localhost:8888 in your browser # Search for badtheorylabs/BTL-4-Compact to start chatting
Install Unsloth Studio (Windows)
irm https://unsloth.ai/install.ps1 | iex # Run unsloth studio unsloth studio -H 0.0.0.0 -p 8888 # Then open http://localhost:8888 in your browser # Search for badtheorylabs/BTL-4-Compact to start chatting
Using HuggingFace Spaces for Unsloth
# No setup required # Open https://huggingface.co/spaces/unsloth/studio in your browser # Search for badtheorylabs/BTL-4-Compact to start chatting
- Pi
How to use badtheorylabs/BTL-4-Compact with Pi:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Configure the model in Pi
# Install Pi: npm install -g @mariozechner/pi-coding-agent # Add to ~/.pi/agent/models.json: { "providers": { "llama-cpp": { "baseUrl": "http://localhost:8080/v1", "api": "openai-completions", "apiKey": "none", "models": [ { "id": "badtheorylabs/BTL-4-Compact:IQ2_XXS" } ] } } }Run Pi
# Start Pi in your project directory: pi
- OpenClaw new
How to use badtheorylabs/BTL-4-Compact with OpenClaw:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Configure OpenClaw
# Install OpenClaw: npm install -g openclaw@latest # Register the local server and set it as the default model: openclaw onboard --non-interactive --mode local \ --auth-choice custom-api-key \ --custom-base-url http://127.0.0.1:8080/v1 \ --custom-model-id "badtheorylabs/BTL-4-Compact:IQ2_XXS" \ --custom-provider-id llama-cpp \ --custom-compatibility openai \ --custom-text-input \ --accept-risk \ --skip-health
Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"
- Docker Model Runner
How to use badtheorylabs/BTL-4-Compact with Docker Model Runner:
docker model run hf.co/badtheorylabs/BTL-4-Compact:IQ2_XXS
- Lemonade
How to use badtheorylabs/BTL-4-Compact with Lemonade:
Pull the model
# Download Lemonade from https://lemonade-server.ai/ lemonade pull badtheorylabs/BTL-4-Compact:IQ2_XXS
Run and chat with the model
lemonade run user.BTL-4-Compact-IQ2_XXS
List all available models
lemonade list
- Hermes Agent
How to use badtheorylabs/BTL-4-Compact with Hermes Agent:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf badtheorylabs/BTL-4-Compact:IQ2_XXS
Configure Hermes
# Install Hermes: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup # Point Hermes at the local server: hermes config set model.provider custom hermes config set model.base_url http://127.0.0.1:8080/v1 hermes config set model.default badtheorylabs/BTL-4-Compact:IQ2_XXS
Run Hermes
hermes
- Atomic Chat
BTL-4 Compact
The whole 35B model in a single 9.96 GB file. 2.30 bits per weight, and it retains 94.1% of the full-precision model's measured behaviour.
BTL-4 is a mixture of experts with roughly 2.1B active parameters per token, so it costs a large model's memory and a small model's compute. Compact is the edition that runs on hardware you already own โ one file, one command, a running agent. No base download, no reconstruction.
Loads in llama.cpp, Ollama and LM Studio.
Full-precision weights: badtheorylabs/BTL-4
| build | size | bits/weight | behavioural retention |
|---|---|---|---|
BTL-4-IQ2_XXS.gguf |
9.96 GB | 2.30 | 94.1% |
Retention is measured, not estimated: 118 items on which the full-precision bf16 model is correct, replayed against this build. It reproduces 111 of them. Per category: 95.0% short-form factual, 100% grounded extraction, 87.2% false-premise rejection. The gate resolves to about ยฑ3.4 points, so treat differences smaller than that as noise.
Run it
llama-cli -m BTL-4-IQ2_XXS.gguf --jinja -c 8192 \
-p "Refactor this function to be pure."
llama-server -m BTL-4-IQ2_XXS.gguf --port 8080 \
--jinja \
--reasoning-format deepseek \
-c 32768 -fa on \
--cache-type-k q8_0 --cache-type-v q8_0 \
--temp 1.0 --top-p 0.95 --top-k 20
Requires a llama.cpp with qwen3_5_moe support (src/models/qwen35moe.cpp).
Flags that are not optional
--jinja. Without it llama.cpp ignores the template embedded in the GGUF
and falls back to a built-in one. BTL-4 emits tool calls as
<tool_call><function=name><parameter=arg>, not stock Qwen's JSON form, so
without this flag tool calls do not parse and multi-turn tool use fails.
--reasoning-format deepseek. Without it, reasoning is left in content
instead of being separated into reasoning_content. It then accumulates on
every turn, the template cannot strip it from older turns, and the model
repeats turns until it runs out of budget. If your agent loops on an otherwise
sane task, check this flag first.
Do not pass --chat-template. The GGUF ships the correct one. Overriding it
with a generic Qwen template produces the same repeat-forever failure.
Prefer --cache-type-k/v q8_0 over q4_0. At 2.30 bpw the weights are
already heavily compressed; a 4-bit KV cache on top of that degrades long-horizon
state tracking, which shows up as the model redoing work it already completed.
Only 10 of 40 layers keep a growing cache (~20 KB/token), so q8_0 is affordable
even at long context.
Architecture
| total parameters | 35.1B (34.7B excluding the vision tower) |
| active per token | ~2.1B |
| layers | 40 โ 30 linear-attention, 10 full-attention |
| experts | 256 per layer, 8 routed per token |
| context | 262,144 native |
| KV cache | ~20 KB/token |
Only 10 of 40 layers keep a growing KV cache, and those use 2 KV heads. The whole 262K window costs about 5.2 GB of cache, so long-context work fits on consumer hardware.
Notes on this build
The MTP layer is disabled. The source model declares
mtp_num_hidden_layers: 1 and the converter writes block_count = 41 while
emitting tensors for only 40 blocks, so a stock loader fails on
blk.40.attn_norm.weight. This build sets block_count = 40 and
nextn_predict_layers = 0. The multi-token-prediction head is a speculative
decoding accessory; the model runs without it.
The vision tower is not included. This is a text-only build.
Quantisation
The 120 expert tensors are IQ2_XXS (2.0625 bpw); everything else follows the
Q4_K_M mixture. An importance matrix was computed over 120 chunks of a 3 MB
corpus of source code, technical documentation and question prompts โ a
deliberate match for what this model is for, rather than generic web text.
The router (ffn_gate_inp) and every normalisation tensor stay at f32. Routing
decides which experts a token reaches, so error there changes which knowledge
gets used rather than degrading it smoothly, and at ~21M parameters it is free
to protect.
Where the 2.30 bpw goes: the experts are 93% of all parameters and contribute 1.92 bpw; the remaining 0.38 comes from the 4-bit and 6-bit non-expert matrices plus the f32 router and norms.
Two findings from simulation work on this model shaped the recipe. Range
selection dominates everything else at low bit widths โ replacing min/max
group ranging with a per-group MSE clip search moved retention from 77.1% to
95.8% at an identical byte budget. And protecting the output head, the usual
recommendation, is worth nothing: head and embedding at 4-bit retained 118 of
118. IQ2_XXS with an imatrix performs its own importance-weighted range
search, which is why it is the build shipped here.
Licence
Apache-2.0, inherited from the base model.
ยฉ 2026 Bad Theory Labs
- Downloads last month
- -
2-bit
Model tree for badtheorylabs/BTL-4-Compact
Base model
badtheorylabs/BTL-4