README.md

---
license: apache-2.0
base_model: Qwen/Qwen3.5-4B
base_model_relation: finetune
library_name: transformers
pipeline_tag: image-text-to-text
tags:
  - liveledger
  - epistemic-ledger
  - agent
  - tool-use
  - function-calling
  - deep-research
  - qwen3_5
language:
  - en
---

# LiveLedger-4B

**LiveLedger-4B** is the *ledger-update* module of **LiveLedger**, an epistemic agent framework for
answering multi-constraint questions with iterative web search and structured evidence tracking.

LiveLedger decomposes a question into atomic constraints and maintains an **Epistemic Ledger** — a
`(candidate × constraint)` table whose cells record whether a candidate satisfies a constraint and
the evidence for that verdict. Keeping this bookkeeping in an explicit structure, rather than in the
agent's context window, is what lets the agent stay coherent over long search trajectories.

Running the ledger update with the frontier search model is expensive: it is called after *every*
search step. LiveLedger-4B is a small, distilled specialist that takes over exactly that step. It is
supervised-fine-tuned on ledger-update trajectories produced by **gpt-oss-120b**, so a large model
drives search while this 4B model does the per-step evidence bookkeeping.

> This is **not** a general-purpose chat or search model. It is trained for one job: read search
> results and emit an `update_ledger` tool call. Used outside that harness, its behaviour is
> undefined.

## Model details

| | |
|---|---|
| Base model | [`Qwen/Qwen3.5-4B`](https://huggingface.co/Qwen/Qwen3.5-4B) |
| Parameters | 4.54 B (incl. the inherited vision tower) |
| Architecture | `Qwen3_5ForConditionalGeneration` |
| Precision | bfloat16 |
| Context length | 262,144 |
| Role in LiveLedger | ledger-update step (`update_ledger` tool call) |
| Teacher | gpt-oss-120b |

The base checkpoint is multimodal and the vision tower is carried over **unmodified** — only the
language-model weights were fine-tuned. LiveLedger is a text-only pipeline; the vision weights are
kept solely so the checkpoint stays loadable as a stock `Qwen3.5-4B`.

## Training

Full-parameter SFT (no LoRA) with DeepSpeed ZeRO-3 + optimizer offload.

| Hyperparameter | Value |
|---|---|
| Objective | supervised fine-tuning on assistant turns |
| Learning rate | 3e-5, cosine schedule, warmup ratio 0.05 |
| Weight decay | 0.1 |
| Gradient clipping | 1.0 |
| Batch | 1 per device × 8 grad-accum × 16 GPUs = **128** effective |
| Max sequence length | 8,192 (longer examples dropped) |
| Precision | bf16 |
| Seed | 42 |

**Data.** Tool-calling trajectories distilled from gpt-oss-120b LiveLedger rollouts on HDS-QA and
MultiConIR-books: 2,885 `update_ledger` examples and 1,393 constraint-extraction examples. After
dropping examples over 8,192 tokens the corpus is ~3.7K, split 90/10 into train/validation.

**Released checkpoint.** The run was scheduled for 10 epochs (260 steps) but validation loss bottoms
out early and rises steadily afterwards, so the released weights are **step 52 (epoch 2)**:

| Step | Epoch | Validation loss | Token accuracy |
|---|---|---|---|
| 26 | 1 | 0.9179 | 0.7405 |
| **52** | **2** | **0.9188** | **0.7417** |
| 78 | 3 | 0.9620 | 0.7370 |
| 104 | 4 | 1.0645 | 0.7291 |
| 130 | 5 | 1.2241 | 0.7194 |
| 156 | 6 | 1.4123 | 0.7115 |

Step 26 has a marginally lower loss, but step 52 has higher token accuracy and is the checkpoint used
for every reported LiveLedger result.

## Usage

### vLLM (how it is actually served)

The ledger model runs as its own endpoint alongside the search model. Tool-call and reasoning parsers
are required — the agent reads the structured `update_ledger` call, not free text.

```bash
vllm serve dayoon/LiveLedger-4B \
  --port 8100 \
  --tensor-parallel-size 1 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --reasoning-parser qwen3 \
  --max-num-seqs 16
```

### Transformers

```python
import torch
from transformers import AutoTokenizer, Qwen3_5ForConditionalGeneration

model_id = "dayoon/LiveLedger-4B"
tok = AutoTokenizer.from_pretrained(model_id)
model = Qwen3_5ForConditionalGeneration.from_pretrained(
    model_id, dtype=torch.bfloat16, device_map="auto"
)

tools = [{
    "type": "function",
    "function": {
        "name": "update_ledger",
        "description": (
            "Record evidence in the ledger based on search results.\n\n"
            "Each entry records evidence for ONE constraint of ONE candidate.\n"
            "Only include entries where new evidence was found."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "entries": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "candidate":    {"type": "string"},
                            "constraint":   {"type": "string"},
                            "obj":          {"type": "boolean"},
                            "obj_evidence": {"type": "string"},
                        },
                        "required": ["candidate", "constraint", "obj", "obj_evidence"],
                    },
                }
            },
            "required": ["entries"],
        },
    },
}]

messages = [
    {"role": "system", "content": "You are a careful and thorough ledger update assistant."},
    {"role": "user", "content": (
        "Constraints:\nC1: Directed by Christopher Nolan\nC2: Released in 2010\n\n"
        "Current ledger: {}\n\n"
        "Search results: 'Inception is a 2010 science fiction film written and "
        "directed by Christopher Nolan.'\n\nUpdate the ledger."
    )},
]

text = tok.apply_chat_template(messages, tools=tools, tokenize=False, add_generation_prompt=True)
inputs = tok(text, return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=512, do_sample=False)
print(tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=False))
```

The model reasons about the search results, then emits an `update_ledger` call whose `entries` set
`obj: true/false` per `(candidate, constraint)` pair with a supporting `obj_evidence` quote.

## Intended use and limitations

**Intended use.** The ledger-update step of a LiveLedger-style agent: given constraints, the current
ledger, a search query and its retrieval results, decide which `(candidate, constraint)` cells the
new evidence settles.

**Limitations.**

- **Narrow specialist.** Fine-tuned on a single tool-calling format. It is not a chat assistant and
  will not behave like the `Qwen3.5-4B` it came from on general tasks.
- **Trained in English** on English web content.
- **Evidence is extracted, not verified.** The model reports what retrieved text asserts. Wrong,
  stale or adversarial sources propagate into the ledger as confident verdicts.
- **Distillation ceiling.** Behaviour is bounded by the gpt-oss-120b trajectories it learned from,
  including their errors.
- **Small training corpus** (~3.7K examples) drawn from two source datasets; out-of-domain
  constraint types are less reliable.
- **Vision inputs are untested.** The vision tower is inherited, never fine-tuned, and never
  exercised in LiveLedger.

## License

Apache 2.0, inherited from [`Qwen/Qwen3.5-4B`](https://huggingface.co/Qwen/Qwen3.5-4B). The bundled
`LICENSE` file is the base model's.