tenseleyflow/documentlanguagemodel / 4dba4c8

-> `.dlm` is a trainable local AI document format: typed sections, directives,

-> replay-backed retraining, and export.

-- a selected multimodal or audio-language document

-history so retrains do not silently forget, and exports local runtimes such as

-Ollama, `llama-server`, `vllm`, and `mlx-serve`.

-

-**Status:** pre-v1.0, but far beyond the original MVP framing. The core

-author/train/prompt/export/pack/share loop is real, and newer runtime-target

-work is landing incrementally. Current export targets are `ollama`,

-## What A `.dlm` Actually Is

-

-A `.dlm` is not just “a text file with a special extension.”

-

-It is a trainable project surface with:

-

-- **frontmatter** for base-model choice, training config, export defaults,

-  sources, cache policy, and multi-adapter gate settings

-- **typed body sections** such as prose, `::instruction::`,

-  `::preference::`, `::image::`, and `::audio::`

-- **adapter routing** via fences like `::instruction#knowledge::`

-- **directive-driven ingestion** from files and directories through

-  `training.sources`

-- **repo-local subtree control** through `.dlm/training.yaml` and `.dlm/ignore`

-- a stable **`dlm_id`** that binds the document to a local store under

-  `~/.dlm/store/<dlm_id>/`

-

-That combination is what makes DLM more like a local AI authoring format than a

-single prompt file.

-

-## Why DLM

-

-Most “personal AI” tooling still pushes you toward one of two bad choices:

-

-- upload your data to someone else’s cloud

-- run an oversized model with weak authoring and retraining ergonomics

-

-DLM sits in the gap:

-

-- **The document is the interface.** You author the thing you care about instead

-  of wiring together a hidden dataset pipeline.

-- **Training is real.** LoRA / QLoRA / DoRA on pretrained bases, not a toy

-  from-scratch transformer.

-- **Retraining is additive.** Previous document versions flow into a replay

-  corpus so the model does not forget last week’s state by default.

-- **Everything stays local.** Training, inference, store state, exports, and

-  packs all live on your machine unless you explicitly push them somewhere.

-- **Determinism is a contract.** Locks, pinned versions, and golden checks are

-  first-class design constraints, not “best effort.”

-

-## Core Capabilities

-

-- **Author structured training data in one place.** Mix prose, SFT examples,

-  preferences, image sections, and audio sections in one document.

-- **Ingest whole trees, not just one file.** `training.sources` can walk a

-  repo, and subtree-local `.dlm/training.yaml` / `.dlm/ignore` let the corpus

-  carry its own curation rules.

-- **Train on modern base families.** Text, reasoning-tuned, sparse-MoE,

-  vision-language, and audio-language registry rows ship today, plus `hf:org/name`

-  escape hatches.

-- **Compose multiple adapters in one document.** Named adapters, weighted export

-  mixes, and learned adapter gates let one `.dlm` separate knowledge, tone, or

-  persona lanes.

-- **Mine preference pairs from a live adapter.** `dlm preference mine` can use

-  `sway`, HF reward models, or external CLI judges to write auto-mined

-  `::preference::` sections back into the document.

-- **Stay in a local iteration loop.** `dlm prompt`, `dlm repl`,

-  `dlm train --watch`, `dlm metrics`, and `dlm doctor` are all part of the

-  normal workflow now.

-- **Export beyond the original Ollama-only story.** DLM still does explicit

-  Ollama exports with pinned templates, and now also emits `llama-server`,

-  `vllm`, and `mlx-serve` launch artifacts for local runtime targets.

-- **Close the eval loop.** `dlm harvest` can pull failing `sway`-style probe

-  reports back into the document as new training examples.

-- **Pack and share reproducibly.** `.dlm.pack`, verification, push/pull, and

-  local serve flows are all built around the same store contracts.

-

-## Supported Platforms

-| Tier | Training | Inference / export |

-|---|---|---|

-| NVIDIA CUDA (SM ≥ 8.0) | bf16 + QLoRA 4-bit + FlashAttention | Ollama, GGUF export, `llama-server`, `vllm` |

-| NVIDIA CUDA (SM < 8.0) | fp16 LoRA | Ollama, GGUF export, `llama-server`, `vllm` |

-| Apple Silicon (MPS) | fp16 or fp32 LoRA depending on doctor plan | Ollama, selected MLX inference paths, GGUF export, `vllm` (conservative Metal defaults), `mlx-serve` |

-| CPU | inference-first; training refused above small bases unless forced | GGUF export, Ollama, `llama-server` |

-| AMD ROCm | experimental | ROCm-oriented llama.cpp flows |

-See [docs/hardware](./docs/hardware/memory-estimates.md) and

-[docs/hardware/vl-memory.md](./docs/hardware/vl-memory.md) for the real support

-matrix and current caveats.

-## Install

-### From the Homebrew tap

-brew tap tenseleyFlow/tap

-brew install dlm

-# Optional, only if you want `--target ollama` registration/smoke:

-brew install ollama

-```

-`brew install dlm` pulls in the Python environment and the vendored

-`llama.cpp` source tree DLM uses for GGUF conversion. CUDA users unlock QLoRA

-after install:

-```sh

-$(brew --prefix dlm)/libexec/venv/bin/pip install 'dlm[cuda]'

-uv sync

-# Build GGUF tooling:

-# If you want the llama.cpp HTTP target too:

-

-# If you want the Apple Silicon MLX HTTP target:

-uv sync --extra mlx

-

-# If you want the vLLM HTTP target:

-# install a compatible vllm runtime separately; DLM writes launch artifacts

-# but does not bundle the server runtime itself.

-

-uv run dlm --help

-We deliberately do not publish to PyPI yet. See

-[CONTRIBUTING.md](./CONTRIBUTING.md) for the release flow.

-

-uv run dlm init tutor.dlm --base smollm2-135m

-$EDITOR tutor.dlm

-uv run dlm train tutor.dlm

-uv run dlm prompt tutor.dlm "What is a Python decorator?"

-uv run dlm export tutor.dlm --target ollama --name my-tutor

-A minimal `.dlm` still works:

-```dlm

-dlm_version: 1

-# Your document title

-Write prose here.

-That path is still important. It is just no longer the whole story.

-

-## Authoring Beyond The Toy Example

-A more representative `.dlm` can mix directives, named adapters, and export

-defaults in one place:

-

-```dlm

-dlm_version: 1

-  sources_policy: strict

-      exclude: ["tests/**", "**/__pycache__/**"]

-Two important upgrades over the older README story:

-

-- `training.sources` can turn a repo or notes tree into synthetic training

-  sections.

-- `training.adapters` + `training.gate` let one document route prompts across

-  multiple adapters instead of pretending one flat adapter is the only mode.

-

-If you need deeper subtree-specific curation, drop `.dlm/training.yaml` and

-`.dlm/ignore` into nested directories and let the corpus carry its own rules.

-

-### 1. Hand-authored document

-uv run dlm init tutor.dlm --base smollm2-135m

-uv run dlm train tutor.dlm

-uv run dlm prompt tutor.dlm "Explain decorators"

-### 2. Train across a codebase

-uv run dlm train ./my-repo --base qwen3-1.7b --include '**/*.py' --name corpus

-That auto-scaffolds a `.dlm` under `./my-repo/.dlm/` and lets the repo become

-its own training surface.

-### 3. Multi-adapter composition

-uv run dlm prompt mydoc.dlm "Explain the runbook" --adapter knowledge

-uv run dlm export mydoc.dlm --adapter-mix knowledge:1.0,tone:0.5

-### 4. Local iteration loop

-uv run dlm train mydoc.dlm --watch

-uv run dlm repl mydoc.dlm

-uv run dlm metrics mydoc.dlm

-### 5. Export and ship

-uv run dlm export mydoc.dlm --target ollama --name mydoc

-uv run dlm export mydoc.dlm --target llama-server

-uv run dlm export mydoc.dlm --target vllm

-uv run dlm export mydoc.dlm --target mlx-serve

-uv run dlm pack mydoc.dlm --include-exports

-uv run dlm verify mydoc.dlm.pack

-On Apple Silicon, `--target vllm` now emits conservative `vllm-metal`

-defaults in the launch script: it pins the server to the MLX KV path

-(`VLLM_METAL_USE_PAGED_ATTENTION=0`, `VLLM_METAL_MEMORY_FRACTION=auto`)

-and caps `--max-model-len` to the document's `training.sequence_len`

-instead of blindly asking `vllm` for the base model's full context.

-

-### 6. Mine preference pairs and retrain

-uv run dlm preference mine mydoc.dlm --samples 4 --max-pairs 8

-uv run dlm preference list mydoc.dlm

-uv run dlm preference apply mydoc.dlm

-uv run dlm train mydoc.dlm --phase preference

-

-# A/B check against hand-authored pairs only:

-uv run dlm train mydoc.dlm --phase preference --no-mined

-

-# Use a different judge when bootstrap self-judging is not enough:

-uv run dlm preference mine mydoc.dlm --judge hf:YourOrg/reward-model --apply

-### 7. Scaffold multimodal or audio docs

-uv run dlm init diagrams.dlm --multimodal --base qwen2-vl-2b-instruct

-uv run dlm train diagrams.dlm

-uv run dlm prompt diagrams.dlm --image figures/system.png "What is happening here?"

-uv run dlm init calls.dlm --audio

-uv run dlm train calls.dlm

-uv run dlm prompt calls.dlm --audio clips/example.wav "Summarize the clip"

-### 8. Pull eval failures back into training

-uv run dlm harvest mydoc.dlm --sway-json sway-report.json --apply

-That is the probe-driven loop: evaluation finds a miss, DLM turns it into

-document-level training data, and the next train closes the gap.

-

-### 9. Inspect store state and reproducibility

-uv run dlm doctor

-uv run dlm show mydoc.dlm --json

-uv run dlm metrics mydoc.dlm --run-id 7 --json

-uv run dlm pack mydoc.dlm --include-exports

-uv run dlm verify mydoc.dlm.pack

-## Command Surface

-The CLI is broader than the original MVP now. A useful mental map:

-| Area | Commands | What they cover |

-| Author | `init`, `templates`, `show`, `migrate`, `cache` | Create docs, inspect them, migrate schema, manage cache state |

-| Train | `train`, `doctor`, `metrics`, `harvest` | Run training, inspect plans, observe runs, pull eval misses back in |

-| Align | `preference` | Mine, stage, apply, revert, and inspect auto-mined preference sections |

-| Infer | `prompt`, `repl` | Local interactive and one-shot inference |

-| Ship | `export`, `pack`, `unpack`, `verify`, `push`, `pull`, `serve` | Export to runtimes, bundle, verify, and move artifacts |

-- [Preference section reference](./docs/format/preference-section.md)

-- [Train from a folder](./docs/cookbook/train-from-folder.md)

-- [Multi-source training](./docs/cookbook/multi-source-training.md)

-- [Tokenized-section cache](./docs/cookbook/directive-cache.md)

-- [Learned adapter gate](./docs/cookbook/learned-adapter-gate.md)

-- [Self-improving loop / preference mining](./docs/cookbook/self-improving-loop.md)

-- [Reward-model integration](./docs/cookbook/reward-model-integration.md)

-- [Probe-driven training / sway harvest](./docs/cookbook/probe-driven-training.md)

-- [Multi-target export](./docs/cookbook/multi-target-export.md)

-- [Sharing adapters and packs](./docs/cookbook/sharing.md)

-- [CLI reference](./docs/cli/reference.md)

-1. **The document is the interface.**

-   But the document is structured: frontmatter, typed sections, directives, and

-   store contracts all matter.

-2. **Training is real.**

-   LoRA / QLoRA / DoRA on pretrained bases, not a toy transformer.

-3. **Retraining should not silently forget.**

-   Replay-backed accumulation is part of the product.

-4. **Local-first is load-bearing.**

-   Your training data, adapters, exports, and packs stay on your machine unless

-   you explicitly move them.

-5. **Determinism is a contract.**

-   If a change breaks the reproducibility story, that is a product regression.

-Python 3.11+ · PyTorch · HuggingFace `transformers` / `peft` / `trl` /

-`accelerate` / `datasets` · `watchfiles` · `prompt-toolkit` · `safetensors` ·

-vendored `llama.cpp` for GGUF export · Ollama (optional runtime target) ·

-Typer · Pydantic · `uv`

-See [CONTRIBUTING.md](./CONTRIBUTING.md). Testing conventions live in

-[docs-internal/README-testing.md](./docs-internal/README-testing.md).

-

-```sh

-uv run pre-commit install

-```

-MIT. Base-model licenses are separate and enforced where DLM needs them:

-`dlm init`, `dlm train`, `dlm export`, and `dlm pack` all keep the gated-base

-acceptance path explicit.

-name = "dlm"