Contrastive-LM/CLM

Contrastive Language Models (CLMs) are a new class of System One model trained with a contrastive learning objective that connects states and actions.

Contrastive Language Models (CLM) – Quick Overview

What it is – CLM‑8B is a System‑One style model that makes fast, typed decisions by scoring how well a candidate action matches a textual state. It is built on a frozen large language model (Qwen‑3‑8B) plus a lightweight 20 M‑parameter projection head for states and another for actions. The two heads are trained with a contrastive (InfoNCE) loss on millions of question‑answer pairs, synthetic hard negatives, and agentic trajectories.

Why it matters – By separating state and action embeddings, CLM can cache action vectors and reuse them across many states. This makes inference cheap and up to 9× faster than comparable agents (e.g., Jev) while achieving similar or better success rates on computer‑use, gaming, and tool‑calling benchmarks. It also shines as a verifier on agentic coding benchmarks, setting new SOTA on Terminal‑Bench 2.1 (87.6 %) and DeepSWE (81.6 %).

Getting Started

# Install the client library
pip install contrastive-lm

Running the service

Start the encoder (Qwen‑3‑8B pooling model) with vllm:

vllm serve Qwen/Qwen3-8B --served-model-name qwen3-8b \
     --runner pooling --max-model-len 2048 --port 8090 &

Launch CLM:
```
clm-serve   # serves the API on http://127.0.0.1:8700
```
The first run downloads a 75 MB “head” checkpoint automatically.

Simple Python usage

from clm import CLMClient, Noul, Choice, Score
client = CLMClient()
resp = client.system_one(
    state="Customer: my invoice was charged twice and nobody answers the phone!",
    questions={
        "urgency": Noul(instructions="Is this urgent?"),
        "department": Choice(
            instructions="Which team should handle this?",
            criteria={"billing": "Charges, invoices, refunds",
                      "technical": "Bugs and outages"}),
        "frustration": Score(
            instructions="How frustrated is the customer?",
            criteria=["Calm", "Frustrated", "Very angry"]),
    },
)
print(resp.answers["urgency"].noul)          # probability the statement is true
print(resp.answers["department"].choice)   # selected option
print(resp.answers["frustration"].score)   # expected level (0‑2)

The same functionality is available via the built‑in playground UI at http://localhost:8700/ and through a plain HTTP API (POST /v1/systemone).

Core Features

Feature	Description
Typed decision API	Supports three question types – `Noul` (binary probability), `Choice` (categorical with softmax), and `Score` (ordered rating).
Fast ranking	`Engine.rank(state, candidates)` scores arbitrary candidate lists in‑process, useful for best‑of‑N selection, tool‑calling, or retrieval short‑listing.
Cache‑aware	Action embeddings are cached; repeated states reuse the same vector, cutting token‑count and latency.
Zero‑shot	No task‑specific prompt engineering needed – just supply the state text and the set of candidate actions.
Fine‑tuning	Lightweight projection‑head fine‑tuning on your own dataset (see `docs/FINETUNING.md`).
Extensible heads	Any checkpoint containing `state_head`, `action_head`, `logit_scale`, and config can be served via `--ckpt`.

Performance Highlights (as reported in the repo)

Latency: Up to 9× lower than Jev on tasks with many candidate actions (e.g., WikiRacing). |
Agentic verification: CLM‑8B reaches 87.6 % on Terminal‑Bench 2.1 and 81.6 % on DeepSWE, beating Jev while being 4–6× faster on an H100 GPU. |
Zero‑shot accuracy: Comparable success rates to Jev across computer‑use, gaming, and tool‑calling benchmarks. |

How It Works (high‑level)

State encoder and action encoder are frozen LLM backbones (Qwen‑3‑8B) with a small trainable projection head (≈20 M params). |
Contrastive training – a bidirectional InfoNCE loss pulls matching state–action pairs together and pushes all other pairs apart. |
Mid‑training adds synthetic hard negatives to sharpen fine‑grained discrimination. |
Post‑training on 1 M agentic trajectories aligns the model with real decision‑making sequences. |
Inference – embed the state, embed each candidate action, compute dot‑product similarity, apply temperature‑scaled softmax, and return the distribution.

Extending / Fine‑tuning

The repository includes a train/finetune.py script that freezes the encoder and updates only the projection heads. Example commands from the README:

# Reproduce DeepSWE verification result
python evaluation/bon_eval.py \
    --hf-dataset Contrastive-LM/deepswe-clm-embeddings-8k \
    --checkpoint heads/deepswe/best_head.pt \
    --tasks-file heads/deepswe/heldout_tasks.json -n 4 --window 12

# Fine‑tune on a custom typed‑decision dataset
python train/finetune.py --task choice \
    --data LocalLLaMA/typed-decisions --workflow all \
    --init-ckpt "$(clm-download)" --out-dir runs/typed

The docs/FINETUNING.md guide walks through data preparation, hyper‑parameters, and checkpoint management.

License & Availability

Code – Apache 2.0 license (see LICENSE). |
Model weights – Apache 2.0, hosted on Hugging Face: Contrastive-LM/CLM-v0.1-8B. |
Community – Blog, Discord, and Hugging Face hub links are provided in the top navigation bar.

Quick Reference – API Endpoints

POST /v1/systemone – typed decision request (state + questions). |
POST /v1/rank – raw ranking of candidate actions. |
GET / – optional web playground UI. |
GET /v1/models – list of available heads.

TL;DR: CLM‑8B is a contrastively trained, state‑action embedding model that delivers fast, typed decisions for agents. Install with a single pip command, run the lightweight server, and call it from Python, curl, or the built‑in UI. Fine‑tune the tiny projection heads on your own data to adapt it to new domains.