documentlanguagemodel Public

Watch 0 Fork 0 Star 0
markdown · 4781 bytes Raw Blame History

Frontmatter reference

The YAML block between the two --- lines at the top of every .dlm document. Validated with Pydantic in dlm.doc.schema (extra="forbid", frozen=True) — unknown keys or wrong types fail fast with a file:line:col error.

Minimum required frontmatter

---
dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
base_model: smollm2-135m
---

dlm_id is a 26-character Crockford base32 ULID. dlm init generates it; don't edit it by hand.

base_model is either a registry key or hf:org/name:

Registry key HuggingFace id
smollm2-135m HuggingFaceTB/SmolLM2-135M-Instruct
smollm2-360m HuggingFaceTB/SmolLM2-360M-Instruct
smollm2-1.7b HuggingFaceTB/SmolLM2-1.7B-Instruct
qwen2.5-0.5b Qwen/Qwen2.5-0.5B-Instruct
qwen2.5-1.5b Qwen/Qwen2.5-1.5B-Instruct
qwen2.5-3b Qwen/Qwen2.5-3B-Instruct
qwen2.5-coder-1.5b Qwen/Qwen2.5-Coder-1.5B-Instruct
llama-3.2-1b meta-llama/Llama-3.2-1B-Instruct (gated)
llama-3.2-3b meta-llama/Llama-3.2-3B-Instruct (gated)
phi-3.5-mini microsoft/Phi-3.5-mini-instruct

Off-registry bases use hf: prefix, e.g. base_model: hf:mistralai/Mistral-7B-Instruct-v0.3. dlm init runs a compatibility probe; failures abort with a clear diagnostic.

Full frontmatter

---
dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
dlm_version: 1                    # bumped by `dlm migrate`; default: 1
base_model: qwen2.5-1.5b
system_prompt: |
  You are a concise assistant.
training:
  adapter: lora                   # or qlora (CUDA only)
  lora_r: 8                       # 1..256
  lora_alpha: 16
  lora_dropout: 0.05              # 0.0..0.5
  target_modules: auto            # or a list[str]
  sequence_len: 2048              # 64..32768
  micro_batch_size: auto          # or a positive int
  grad_accum: auto                # or a positive int
  learning_rate: 2e-4
  num_epochs: 3
  optimizer: adamw_torch          # or adamw_bnb_8bit / paged_adamw_8bit
  lr_scheduler: cosine            # or linear / constant
  warmup_ratio: 0.1               # 0.0..0.5
  seed: 42
export:
  default_quant: Q4_K_M           # or Q5_K_M / Q6_K / Q8_0
  default_temperature: 0.2        # optional; overrides dialect default
  default_top_p: null             # optional; null keeps dialect default
---

Field-by-field

Top-level

Field Type Default Notes
dlm_id 26-char ULID required Assigned by dlm init. Never regenerated.
dlm_version int ≥ 1 1 Bumped by dlm migrate when the schema evolves.
base_model non-empty str required Registry key or hf:org/name.
system_prompt str or null null Emitted as SYSTEM "…" in the Modelfile on export.
training object defaults See below.
export object defaults See below.

training

Field Type Default Notes
adapter lora or qlora lora QLoRA requires CUDA + bitsandbytes.
lora_r int 1..256 8 LoRA rank.
lora_alpha int ≥ 1 16 LoRA alpha (scaling).
lora_dropout float 0..0.5 0.05
target_modules auto or list auto auto uses the per-architecture registry from Sprint 06. Explicit lists override.
sequence_len int 64..32768 2048 Max token length per example. Also emitted as Ollama PARAMETER num_ctx.
micro_batch_size auto or int ≥ 1 auto Doctor picks based on VRAM.
grad_accum auto or int ≥ 1 auto Doctor picks to reach effective batch = 8.
learning_rate float > 0 2e-4
num_epochs int ≥ 1 3
optimizer enum adamw_torch adamw_bnb_8bit / paged_adamw_8bit for CUDA + bnb.
lr_scheduler enum cosine
warmup_ratio float 0..0.5 0.1
seed int 42 Determinism seed. Changing it invalidates the determinism golden.

export

Field Type Default Notes
default_quant Q4_K_M/Q5_K_M/Q6_K/Q8_0 Q4_K_M Used when dlm export --quant isn't passed.
default_temperature float 0..2 or null null Per-document sampling override. Emitted as Modelfile PARAMETER temperature.
default_top_p float 0..1 or null null Per-document sampling override.

Migrations

When a new version bumps dlm_version (e.g., adding a field), dlm migrate runs the registered migrators in order and rewrites the frontmatter in place. See Sprint 12b for the migration framework.

The parser refuses to load a document whose dlm_version exceeds the running CLI's CURRENT_SCHEMA_VERSION:

error: tutor.dlm:2:14 — dlm_version 2 is newer than this CLI supports (1).
       Upgrade dlm to continue.
View source
1 # Frontmatter reference
2
3 The YAML block between the two `---` lines at the top of every `.dlm`
4 document. Validated with Pydantic in `dlm.doc.schema` (`extra="forbid"`,
5 `frozen=True`) — unknown keys or wrong types fail fast with a
6 `file:line:col` error.
7
8 ## Minimum required frontmatter
9
10 ```yaml
11 ---
12 dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
13 base_model: smollm2-135m
14 ---
15 ```
16
17 `dlm_id` is a 26-character Crockford base32 ULID. `dlm init` generates
18 it; don't edit it by hand.
19
20 `base_model` is either a registry key or `hf:org/name`:
21
22 | Registry key | HuggingFace id |
23 |---|---|
24 | `smollm2-135m` | HuggingFaceTB/SmolLM2-135M-Instruct |
25 | `smollm2-360m` | HuggingFaceTB/SmolLM2-360M-Instruct |
26 | `smollm2-1.7b` | HuggingFaceTB/SmolLM2-1.7B-Instruct |
27 | `qwen2.5-0.5b` | Qwen/Qwen2.5-0.5B-Instruct |
28 | `qwen2.5-1.5b` | Qwen/Qwen2.5-1.5B-Instruct |
29 | `qwen2.5-3b` | Qwen/Qwen2.5-3B-Instruct |
30 | `qwen2.5-coder-1.5b` | Qwen/Qwen2.5-Coder-1.5B-Instruct |
31 | `llama-3.2-1b` | meta-llama/Llama-3.2-1B-Instruct (gated) |
32 | `llama-3.2-3b` | meta-llama/Llama-3.2-3B-Instruct (gated) |
33 | `phi-3.5-mini` | microsoft/Phi-3.5-mini-instruct |
34
35 Off-registry bases use `hf:` prefix, e.g.
36 `base_model: hf:mistralai/Mistral-7B-Instruct-v0.3`. `dlm init` runs
37 a compatibility probe; failures abort with a clear diagnostic.
38
39 ## Full frontmatter
40
41 ```yaml
42 ---
43 dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
44 dlm_version: 1 # bumped by `dlm migrate`; default: 1
45 base_model: qwen2.5-1.5b
46 system_prompt: |
47 You are a concise assistant.
48 training:
49 adapter: lora # or qlora (CUDA only)
50 lora_r: 8 # 1..256
51 lora_alpha: 16
52 lora_dropout: 0.05 # 0.0..0.5
53 target_modules: auto # or a list[str]
54 sequence_len: 2048 # 64..32768
55 micro_batch_size: auto # or a positive int
56 grad_accum: auto # or a positive int
57 learning_rate: 2e-4
58 num_epochs: 3
59 optimizer: adamw_torch # or adamw_bnb_8bit / paged_adamw_8bit
60 lr_scheduler: cosine # or linear / constant
61 warmup_ratio: 0.1 # 0.0..0.5
62 seed: 42
63 export:
64 default_quant: Q4_K_M # or Q5_K_M / Q6_K / Q8_0
65 default_temperature: 0.2 # optional; overrides dialect default
66 default_top_p: null # optional; null keeps dialect default
67 ---
68 ```
69
70 ## Field-by-field
71
72 ### Top-level
73
74 | Field | Type | Default | Notes |
75 |---|---|---|---|
76 | `dlm_id` | 26-char ULID | required | Assigned by `dlm init`. Never regenerated. |
77 | `dlm_version` | int ≥ 1 | `1` | Bumped by `dlm migrate` when the schema evolves. |
78 | `base_model` | non-empty str | required | Registry key or `hf:org/name`. |
79 | `system_prompt` | str or null | null | Emitted as `SYSTEM "…"` in the Modelfile on export. |
80 | `training` | object | defaults | See below. |
81 | `export` | object | defaults | See below. |
82
83 ### `training`
84
85 | Field | Type | Default | Notes |
86 |---|---|---|---|
87 | `adapter` | `lora` or `qlora` | `lora` | QLoRA requires CUDA + bitsandbytes. |
88 | `lora_r` | int 1..256 | 8 | LoRA rank. |
89 | `lora_alpha` | int ≥ 1 | 16 | LoRA alpha (scaling). |
90 | `lora_dropout` | float 0..0.5 | 0.05 | |
91 | `target_modules` | `auto` or list | `auto` | `auto` uses the per-architecture registry from Sprint 06. Explicit lists override. |
92 | `sequence_len` | int 64..32768 | 2048 | Max token length per example. Also emitted as Ollama `PARAMETER num_ctx`. |
93 | `micro_batch_size` | `auto` or int ≥ 1 | `auto` | Doctor picks based on VRAM. |
94 | `grad_accum` | `auto` or int ≥ 1 | `auto` | Doctor picks to reach effective batch = 8. |
95 | `learning_rate` | float > 0 | 2e-4 | |
96 | `num_epochs` | int ≥ 1 | 3 | |
97 | `optimizer` | enum | `adamw_torch` | `adamw_bnb_8bit` / `paged_adamw_8bit` for CUDA + bnb. |
98 | `lr_scheduler` | enum | `cosine` | |
99 | `warmup_ratio` | float 0..0.5 | 0.1 | |
100 | `seed` | int | 42 | Determinism seed. Changing it invalidates the [determinism golden](../determinism.md). |
101
102 ### `export`
103
104 | Field | Type | Default | Notes |
105 |---|---|---|---|
106 | `default_quant` | `Q4_K_M`/`Q5_K_M`/`Q6_K`/`Q8_0` | `Q4_K_M` | Used when `dlm export --quant` isn't passed. |
107 | `default_temperature` | float 0..2 or null | null | Per-document sampling override. Emitted as Modelfile `PARAMETER temperature`. |
108 | `default_top_p` | float 0..1 or null | null | Per-document sampling override. |
109
110 ## Migrations
111
112 When a new version bumps `dlm_version` (e.g., adding a field),
113 `dlm migrate` runs the registered migrators in order and rewrites the
114 frontmatter in place. See Sprint 12b for the migration framework.
115
116 The parser refuses to load a document whose `dlm_version` exceeds the
117 running CLI's `CURRENT_SCHEMA_VERSION`:
118
119 ```
120 error: tutor.dlm:2:14 — dlm_version 2 is newer than this CLI supports (1).
121 Upgrade dlm to continue.
122 ```