Instructions to use badtheorylabs/BTL-3-Compact with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use badtheorylabs/BTL-3-Compact with llama-cpp-python:

# !pip install llama-cpp-python

from llama_cpp import Llama

llm = Llama.from_pretrained(
	repo_id="badtheorylabs/BTL-3-Compact",
	filename="model/BTL-3-Compact-AVQ2.gguf",
)

llm.create_chat_completion(
	messages = [
		{
			"role": "user",
			"content": "What is the capital of France?"
		}
	]
)

Notebooks
Google Colab
Kaggle
Local Apps Settings

llama.cpp

How to use badtheorylabs/BTL-3-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-3-Compact
# Run inference directly in the terminal:
llama cli -hf badtheorylabs/BTL-3-Compact

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf badtheorylabs/BTL-3-Compact
# Run inference directly in the terminal:
llama cli -hf badtheorylabs/BTL-3-Compact

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-3-Compact
# Run inference directly in the terminal:
./llama-cli -hf badtheorylabs/BTL-3-Compact

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-3-Compact
# Run inference directly in the terminal:
./build/bin/llama-cli -hf badtheorylabs/BTL-3-Compact

Use Docker

docker model run hf.co/badtheorylabs/BTL-3-Compact

LM Studio
Jan

vLLM

How to use badtheorylabs/BTL-3-Compact with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "badtheorylabs/BTL-3-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-3-Compact",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/badtheorylabs/BTL-3-Compact

Ollama
How to use badtheorylabs/BTL-3-Compact with Ollama:
```
ollama run hf.co/badtheorylabs/BTL-3-Compact
```

Unsloth Studio

How to use badtheorylabs/BTL-3-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-3-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-3-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-3-Compact to start chatting

How to use badtheorylabs/BTL-3-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-3-Compact

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-3-Compact"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Hermes Agent new

How to use badtheorylabs/BTL-3-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-3-Compact

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-3-Compact

Run Hermes

hermes

Atomic Chat new

OpenClaw new

How to use badtheorylabs/BTL-3-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-3-Compact

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-3-Compact" \
  --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-3-Compact with Docker Model Runner:
```
docker model run hf.co/badtheorylabs/BTL-3-Compact
```

Lemonade

How to use badtheorylabs/BTL-3-Compact with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull badtheorylabs/BTL-3-Compact

Run and chat with the model

lemonade run user.BTL-3-Compact-{{QUANT_TAG}}

List all available models

lemonade list

BTL-3 Compact

The complete 27B agent model in one 8.39 GB file

Under 2.5 effective bits per parameter · 98.4% held-out tool-contract retention

Full BTL-3 · Runtime source · Bad Theory Labs · Discord

Canonical behavior refresh — July 24, 2026: the file at the existing model/BTL-3-Compact-AVQ2.gguf path now embeds the rank-8 step-160 Thinking Escape behavior adapter. The packed decoder and rank-32 output correction are unchanged. The new model SHA-256 is 0a4d9ddee49e5aa93586a792bd4d452ea837229d49d22e54212dde87a5c9888a. Thinking remains disabled by default; thinking-enabled coding still fails its release gate and should be treated as experimental.

Introducing BTL-3 Compact

BTL-3 is a 27B open-weight agent model built for agentic coding, structural tool use, repository work, failure recovery, and long multi-turn execution. BTL-3 Compact packages the complete text model into one 8.39 GB native GGUF—smaller than an 8B model stored in FP16 and under 2.5 effective artifact bits per parameter.

On the step-160 candidate's held-out teacher-correct tool gate, BTL-3 Compact retained 62 of 63 behaviors, yielding 98.4% conditional retention.

Overview

BTL-3 Compact is the portable native edition of BTL-3. It packages the complete text model—including the compressed decoder, vocabulary matrices, output correction, and behavior repair—into a single 8,392,369,600-byte GGUF.

The runtime consumes the packed representation directly. It does not download, load, or reconstruct the original BF16 checkpoint.

Highlights

Complete Qwen3.6-27B-derived text model in 8.39 GB decimal / 7.82 GiB.
Full 64-layer mixed AVQ2/UniSVQ representation with targeted precision islands and compact behavioral corrections.
98.4% conditional retention (62/63) on the step-160 candidate's held-out teacher-correct tool gate.
Exact native CUDA and Metal execution with no persistent dense reconstruction.
OpenAI-compatible local server plus LM Studio and Ollama CLI integrations.
Verified macOS arm64 package and a clearly separated DGX Spark CUDA preview.

Model specification

Item	Specification
Model lineage	Qwen3.6-27B → BTL-3 RL-0013
Scope	Text-only coding, reasoning, and tool use
Layers	64
Model file	`model/BTL-3-Compact-AVQ2.gguf`
Deployed model bytes	8,392,369,600
Deployed model size	8.39 GB / 7.82 GiB
Architectural context	262,144 tokens
Packed tensors	2,416
Runtime	BTL packed llama.cpp
License	Apache-2.0 model, MIT runtime

Usable context depends on device memory, KV cache, and runtime workspace. Start with 4K on a 16 GB Mac, 16K on a 12–16 GB GPU, or 32K on a 24 GB GPU, then increase the window after measuring headroom.

Measured retention

The candidate gate contains 63 turns across single, parallel, sequential, parallel-multiple, and abstention behavior. It is an internal contract-retention evaluation, not a public frontier benchmark.

Metric	Result
Teacher-correct cases	63/63
BTL-3 Compact	62/63
Conditional retention	98.4% (62/63)
Single-call retention	100% (23/23)
Parallel-call retention	100% (14/14)
Parallel-multiple retention	100% (2/2)
Sequential-call retention	87.5% (7/8)
Abstention retention	100% (16/16)

The complete candidate report is included in evidence/thinking-escape-v3-tool-gate.json.

Native performance

Device	Prompt processing	Generation	Runtime status
RTX PRO 6000 Blackwell 96 GB	84.70 tok/s	43.16 tok/s	Exact GGUF, full CUDA offload
Apple M2 16 GB	2.30 tok/s	2.48 tok/s	Exact GGUF, Metal compatibility smoke

The RTX result is the mean of three native runs with a 512-token prompt and 128 generated tokens. The M2 measurement is a compatibility smoke on the entry-level 16 GB system, not a performance projection for newer Apple hardware.

Runtime support

Target	Status	Package
macOS arm64 / Apple Metal	Verified	`runtimes/supported/BTL-3-Compact-macos-arm64`
Linux arm64 / NVIDIA CUDA / DGX Spark	Preview	`runtimes/preview/BTL-3-Compact-linux-arm64-cuda`
OpenAI-compatible HTTP	Verified	Native `btl3-server`
LM Studio	Supported through included generator	`integrations/btl3-native`
Ollama CLI	Supported through included bridge	`integrations/ollama`

Stock Ollama and the stock LM Studio GGUF engine do not decode AVQ2 directly. The included integrations start or connect to BTL's native runner while preserving the familiar client interface.

Quickstart

Current reasoning-policy note: BTL-3 Compact is released with thinking disabled by default. Use the supported non-thinking path for chat, coding, and tools. The experimental thinking override is currently discouraged because it can repeat procedural reasoning or fail to terminate. On the step-160 held-out smoke, 5/12 prompts reached </think> and a final answer; thinking-enabled coding reached 0/3. The default no-thinking path passed direct-answer stopping and executable Python validation on the exact GGUF.

Install the verified macOS package

python3 tools/install_consumer_bundle.py \
  --runtime runtimes/supported/BTL-3-Compact-macos-arm64 \
  --model model/BTL-3-Compact-AVQ2.gguf

Start the server directly

BTL3_MODEL="$PWD/model/BTL-3-Compact-AVQ2.gguf" \
BTL3_CTX_SIZE=4096 \
  runtimes/supported/BTL-3-Compact-macos-arm64/bin/btl3-server

Call the OpenAI-compatible API

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "BTL-3",
    "messages": [
      {
        "role": "user",
        "content": "Write a retrying fetch helper and include tests."
      }
    ],
    "chat_template_kwargs": {"enable_thinking": false},
    "stream": true
  }'

Representation

The release combines:

packed AVQ2 decoder tensors;
affine INT4 tensors and two measured INT4 demotions;
selected higher-precision islands;
packed embedding and output matrices;
a rank-32 output correction;
a compact behavior adapter.

All 2,416 tensor payloads were byte-verified during export. Native CUDA parity was checked against the reference representation, and the exact exported GGUF subsequently completed autoregressive generation on CUDA and Metal.

Artifact integrity

Artifact	Value
File	`model/BTL-3-Compact-AVQ2.gguf`
Bytes	`8,392,369,600`
SHA-256	`0a4d9ddee49e5aa93586a792bd4d452ea837229d49d22e54212dde87a5c9888a`

Verify the complete release directory:

shasum -a 256 -c SHA256SUMS

RELEASE_MANIFEST.json records the exact model identity and separates verified runtimes from preview packages.

Intended use

local coding and debugging;
private repository and terminal agents;
structured single, sequential, and parallel tool use;
offline or self-hosted OpenAI-compatible inference;
consumer and workstation deployments where the BF16 model is impractical.

Operational guidance

Run generated code and tool calls in a sandbox. Require explicit confirmation before destructive, privileged, financial, or otherwise high-impact actions.

License and citation

The model artifact is Apache-2.0. The included runtime is MIT-licensed; see the packaged licenses and third-party notices.

@software{btl3_compact_2026,
  title  = {BTL-3 Compact: A Native 8.39 GB Agentic Coding Model},
  author = {Bad Theory Labs},
  year   = {2026},
  url    = {https://huggingface.co/badtheorylabs/BTL-3-Compact}
}

For questions and release updates, visit Bad Theory Labs or join the community Discord.

Downloads last month: 1,231

GGUF

Model size

8B params

Architecture

qwen35

Hardware compatibility

We're not able to determine the quantization variants.

View all variants

Model tree for badtheorylabs/BTL-3-Compact

Base model

Qwen/Qwen3.6-27B

Quantized

(642)

this model