# contrastive-lm/clm architecture

> Architecture diagram of the GitHub repository contrastive-lm/clm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/contrastive-lm/clm
- Repository: https://github.com/contrastive-lm/clm

## Overview

CLM serves contrastive state–action scoring as typed decisions and candidate ranking. The primary workflow is a caller or playground sending a state and questions/candidates to the API; the server delegates scoring to the inference engine, which embeds text, applies projection heads, and returns distributions or rankings. Separate repository capabilities support adapting heads to downstream data and evaluating trajectory selection. The README documents broader pre-, mid-, and post-training, but the sampled source chiefly evidences fine-tuning and evaluation; the graph avoids guessing their full implementation.

Main entry points: [`src/clm/engine.py`](https://github.com/contrastive-lm/clm/blob/main/src/clm/engine.py) (Inference engine), [`train/finetune.py`](https://github.com/contrastive-lm/clm/blob/main/train/finetune.py) (Head fine-tuning), [`src/clm/server.py`](https://github.com/contrastive-lm/clm/blob/main/src/clm/server.py) (HTTP API), [`preprocessing/hf_embeddings.py`](https://github.com/contrastive-lm/clm/blob/main/preprocessing/hf_embeddings.py) (Embedding conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["API serving"]
  node_client["Python client<br/>[client.py]"]
  node_server["HTTP API<br/>[server.py]"]
  node_schema["Question schema<br/>[schema.py]"]
end

subgraph group_inference["Scoring engine"]
  node_engine["Inference engine<br/>[engine.py]"]
  node_embedder["Embedding client<br/>[embedder.py]"]
  node_heads["Projection heads<br/>[heads.py]"]
  node_cache[("Vector cache<br/>[cache.py]")]
end

subgraph group_adaptation["Model adaptation"]
  node_adapter["Data adapters<br/>[adapters.py]"]
  node_embed_utils["Training embeddings<br/>[embed_utils.py]"]
  node_finetune["Head fine-tuning<br/>[finetune.py]"]
  node_embedding_data["Embedding conversion<br/>[hf_embeddings.py]"]
  node_eval["Trajectory evaluation<br/>[bon_eval.py]"]
end

subgraph group_playground["Playground"]
  node_ui["Web playground<br/>[app.js]"]
end

node_caller(("Agent or caller"))
node_encoder["Embedding service"]
node_checkpoint[("Model checkpoints")]
node_playground_user(("Playground user"))
node_hf["Hugging Face data and models"]

node_caller -->|"calls"| node_client
node_client -->|"sends requests"| node_server
node_server -->|"dispatches scoring"| node_engine
node_server -->|"validates questions"| node_schema
node_engine -->|"requests embeddings"| node_embedder
node_embedder -->|"sends text"| node_encoder
node_engine -->|"scores with"| node_heads
node_engine -->|"reads and writes"| node_cache
node_engine -->|"loads weights"| node_checkpoint
node_playground_user -->|"uses"| node_ui
node_ui -->|"posts requests"| node_server
node_finetune -->|"loads examples"| node_adapter
node_finetune -->|"embeds training text"| node_embed_utils
node_embed_utils -->|"requests embeddings"| node_encoder
node_finetune -->|"uses embedding data"| node_embedding_data
node_embedding_data -.->|"downloads or uploads"| node_hf
node_finetune -->|"writes trained heads"| node_checkpoint
node_eval -->|"loads heads"| node_checkpoint
node_eval -->|"reads embedding data"| node_embedding_data

click node_client "https://github.com/contrastive-lm/clm/blob/main/src/clm/client.py"
click node_server "https://github.com/contrastive-lm/clm/blob/main/src/clm/server.py"
click node_schema "https://github.com/contrastive-lm/clm/blob/main/src/clm/schema.py"
click node_engine "https://github.com/contrastive-lm/clm/blob/main/src/clm/engine.py"
click node_embedder "https://github.com/contrastive-lm/clm/blob/main/src/clm/embedder.py"
click node_heads "https://github.com/contrastive-lm/clm/blob/main/src/clm/heads.py"
click node_cache "https://github.com/contrastive-lm/clm/blob/main/src/clm/cache.py"
click node_ui "https://github.com/contrastive-lm/clm/blob/main/src/clm/static/app.js"
click node_adapter "https://github.com/contrastive-lm/clm/blob/main/train/adapters.py"
click node_embed_utils "https://github.com/contrastive-lm/clm/blob/main/train/embed_utils.py"
click node_finetune "https://github.com/contrastive-lm/clm/blob/main/train/finetune.py"
click node_embedding_data "https://github.com/contrastive-lm/clm/blob/main/preprocessing/hf_embeddings.py"
click node_eval "https://github.com/contrastive-lm/clm/blob/main/evaluation/bon_eval.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_schema,node_playground_user toneBlue
class node_engine,node_embedder,node_heads,node_cache,node_checkpoint toneAmber
class node_adapter,node_embed_utils,node_finetune,node_embedding_data,node_eval toneMint
class node_ui toneRose
class node_caller,node_encoder,node_hf toneIndigo
```

## Components

### API serving

- [Python client](https://github.com/contrastive-lm/clm/blob/main/src/clm/client.py): `src/clm/client.py`
- [HTTP API](https://github.com/contrastive-lm/clm/blob/main/src/clm/server.py): `src/clm/server.py`
- [Question schema](https://github.com/contrastive-lm/clm/blob/main/src/clm/schema.py): `src/clm/schema.py`

### Scoring engine

- [Inference engine](https://github.com/contrastive-lm/clm/blob/main/src/clm/engine.py): `src/clm/engine.py`
- [Embedding client](https://github.com/contrastive-lm/clm/blob/main/src/clm/embedder.py): `src/clm/embedder.py`
- [Projection heads](https://github.com/contrastive-lm/clm/blob/main/src/clm/heads.py): `src/clm/heads.py`
- [Vector cache](https://github.com/contrastive-lm/clm/blob/main/src/clm/cache.py): `src/clm/cache.py`

### Model adaptation

- [Data adapters](https://github.com/contrastive-lm/clm/blob/main/train/adapters.py): `train/adapters.py`
- [Training embeddings](https://github.com/contrastive-lm/clm/blob/main/train/embed_utils.py): `train/embed_utils.py`
- [Head fine-tuning](https://github.com/contrastive-lm/clm/blob/main/train/finetune.py): `train/finetune.py`
- [Embedding conversion](https://github.com/contrastive-lm/clm/blob/main/preprocessing/hf_embeddings.py): `preprocessing/hf_embeddings.py`
- [Trajectory evaluation](https://github.com/contrastive-lm/clm/blob/main/evaluation/bon_eval.py): `evaluation/bon_eval.py`

### Playground

- [Web playground](https://github.com/contrastive-lm/clm/blob/main/src/clm/static/app.js): `src/clm/static/app.js`

### Other components

- **Agent or caller**
- **Embedding service**
- **Model checkpoints**
- **Playground user**
- **Hugging Face data and models**

## Connections

- Agent or caller → Python client: calls
- Python client → HTTP API: sends requests
- HTTP API → Inference engine: dispatches scoring
- HTTP API → Question schema: validates questions
- Inference engine → Embedding client: requests embeddings
- Embedding client → Embedding service: sends text
- Inference engine → Projection heads: scores with
- Inference engine → Vector cache: reads and writes
- Inference engine → Model checkpoints: loads weights
- Playground user → Web playground: uses
- Web playground → HTTP API: posts requests
- Head fine-tuning → Data adapters: loads examples
- Head fine-tuning → Training embeddings: embeds training text
- Training embeddings → Embedding service: requests embeddings
- Head fine-tuning → Embedding conversion: uses embedding data
- Embedding conversion → Hugging Face data and models: downloads or uploads
- Head fine-tuning → Model checkpoints: writes trained heads
- Trajectory evaluation → Model checkpoints: loads heads
- Trajectory evaluation → Embedding conversion: reads embedding data