Rework capabilities pages with LFM3 and LFM2/LFM2.5 tabs

docs.json

@@ -113,7 +113,7 @@
                   "lfm/key-concepts/tool-use",
                   "lfm/key-concepts/vision-capabilities",
                   "lfm/key-concepts/audio-capabilities",
-                  "lfm/key-concepts/omni-capabilities",
+                  "lfm/key-concepts/speech-generation",
                   "lfm/key-concepts/speculative-decoding"
                 ]
               },
@@ -334,6 +334,10 @@
     ]
   },
   "redirects": [
+    {
+      "source": "/lfm/key-concepts/omni-capabilities",
+      "destination": "/lfm/key-concepts/audio-capabilities"
+    },
     {
       "source": "/lfm/key-concepts/tool-search",
       "destination": "/lfm/key-concepts/tool-use"

guides/migration-guide.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Migration Guide"
 description: "Move from Qwen, Llama, or Gemma to LFMs while avoiding the common migration pitfalls."
 ---
 
-import { ToolCallTokenExample } from "/snippets/key-concepts/tool-call-token-example.mdx";
+import { LFM25ToolCallExample } from "/snippets/key-concepts/lfm25-tool-call-example.mdx";
 
 This guide is for teams already running Qwen, Llama, or Gemma who want to evaluate Liquid Foundation Models (LFMs) as replacements. LFMs load and serve through the same frameworks you already use, so most migrations are a model ID and configuration change. The details that usually matter are:
 - deployment runtime choice (see [Deployment runtimes](#deployment-runtimes)),
 - chat templates (see [Chat Template](#chat-template)),
 - sampling configuration (see [Sampling Configuration](#sampling-configuration)),
@@ -16,7 +16,7 @@
 
 ## Model mapping
 
 Start with LFM3 for general text, vision, audio, or omni workloads. Compare models within your deployment's memory, latency, and quality constraints. Smaller and specialized older models remain useful when they fit those constraints better.
 
 | If you run | Evaluate | Notes |
 | --- | --- | --- |
@@ -25,16 +25,16 @@
 | Whisper plus separate TTS | [LFM3-Audio-2B](/lfm/models/lfm3-audio-2b) | ASR, TTS, and speech-to-speech in one model. |
 | Separate vision and speech models | [LFM3-Omni-2B](/lfm/models/lfm3-omni-2b) | Text, image, video, and audio input with text or speech output. |
 | Small text models, `<1B` | [LFM2.5-230M](/lfm/models/lfm25-230m) or [LFM2.5-350M](/lfm/models/lfm25-350m) | Classification, extraction, routing, and tight memory budgets. |
 | Larger text models, `4B-13B` | [LFM2.5-8B-A1B](/lfm/models/lfm25-8b-a1b) | MoE alternative for reasoning and agentic workloads; 1.5B active parameters. |
 | Larger text models, `14B+` | [LFM2.5-24B-A2B](/lfm/models/lfm25-24b-a2b) | Larger reasoning MoE alternative; evaluate quality, latency, and memory on your task. |
 
 For image-to-JSON extraction, also evaluate the specialized [LFM2.5-VL-Extract models](/lfm/models/liquid-nanos).
 
 See the [Complete Model Library](/lfm/models/complete-library) for the full catalog.
 
 ## Deployment runtimes
 
 Across runtimes, avoid carrying over hand-written Qwen, Llama, or Gemma prompt templates. Use the model-provided chat template and a runtime build that supports your checkpoint. For tool use, LFM3 uses `qwen3_coder` parsing in vLLM and SGLang; LFM2 and LFM2.5 use `lfm2`. Follow the selected model's quickstart for the full launch configuration.
 
 For GPU inference, see [Transformers](/deployment/gpu-inference/transformers), [vLLM](/deployment/gpu-inference/vllm), [SGLang](/deployment/gpu-inference/sglang), or [zml/llmd](/deployment/gpu-inference/zml-llmd).
 
@@ -42,27 +42,27 @@
 
 ## Chat Template
 
 LFMs use a ChatML-style format, with generation-specific tokens and reasoning behavior. LFM3 templates normally open a thinking-model assistant turn with `<think>`; use the tokenizer or processor to format the prompt.
 
 Roles are `system`, `user`, `assistant`, and `tool`. Image and video markers differ by model generation; let the processor insert them.
 
 Migration notes:
 
 - **From Qwen:** ChatML is familiar, but token details differ. Use `apply_chat_template`; do not reuse literal Qwen strings.
 - **From Llama:** replace `<|begin_of_text|>` and `<|start_header_id|>` prompt builders.
 - **From Gemma:** replace `<start_of_turn>` builders. LFMs support a real `system` role.
 
 See [Chat Template](/lfm/key-concepts/chat-template) and Hugging Face's [`apply_chat_template` guide](https://huggingface.co/docs/transformers/main/en/chat_templating#using-applychattemplate) for the full formatting workflow.
 
 ## Sampling Configuration
 
 Generation parameters are model-specific. Tune on your task instead of carrying over defaults from Qwen, Llama, or Gemma.
 
 See the [Prompting Guide](/lfm/key-concepts/text-generation-and-prompting) for recommended sampling configurations by model.
 
 ## Tool Use
 
 LFM3 emits XML tool calls, using a superset of the `qwen3_coder` format:
 
 ```text
 <tool_call>
@@ -74,17 +74,17 @@
 </tool_call>
 ```
 
 LFM2 and LFM2.5 use the earlier tool-call format, typically a Pythonic call list:
 
-<ToolCallTokenExample></ToolCallTokenExample>
+<LFM25ToolCallExample></LFM25ToolCallExample>
 
 Serving runtimes can parse these native formats into OpenAI-compatible `tool_calls`. A client that reads raw generated text must handle the format for its selected model.
 
 What to do:
 
 1. Pass tools through [`tokenizer.apply_chat_template(messages, tools=[...])`](https://huggingface.co/docs/transformers/main/en/chat_templating#using-applychattemplate) or the serving runtime's supported tool mechanism.
 2. Prefer the serving runtime's structured `tool_calls`. If you parse raw text, handle LFM3 XML or the older `<|tool_call_start|>` / `<|tool_call_end|>` format as appropriate.
 3. On vLLM or SGLang, use `qwen3_coder` for LFM3 and `lfm2` for LFM2/LFM2.5, with the other flags from the model's quickstart.
 4. Return results as `tool` role messages, with JSON content if useful.
 5. If you fine-tune for tool calling, format the data with the selected model's own chat template and native tool-call format.
 

lfm/key-concepts/chat-template.mdx

@@ -1,27 +1,40 @@
 ---
 title: "Chat Template"
-description: "The chat template defines how conversations are structured using special tokens and roles. LFM3 uses a ChatML-like chat template to structure conversations as follows:"
+description: "Learn how chat templates structure conversations with roles and special tokens for text, image, and audio messages."
 ---
 
-import { ChatMLExample } from "/snippets/key-concepts/chatml-example.mdx";
+import { LFM3ChatPrompt } from "/snippets/key-concepts/lfm3-chat-prompt.mdx";
+import { LFM25ChatPrompt } from "/snippets/key-concepts/lfm25-chat-prompt.mdx";
 
-```
-<|startoftext|><|im_start|>system
-You are a helpful assistant trained by Liquid AI.<|im_end|>
-<|im_start|>user
-Explain how a heat pump works.<|im_end|>
-<|im_start|>assistant
-<think>
-```
+A chat template turns a conversation into the text the model reads. The examples below show how the template formats messages and generation prompts.
+
+## Message structure
+
+Compare the generation prompts for the same system message and user request:
+
+<Tabs>
+<Tab title="LFM3">
+
+<LFM3ChatPrompt></LFM3ChatPrompt>
+
+</Tab>
+<Tab title="LFM2/LFM2.5">
+
+<LFM25ChatPrompt></LFM25ChatPrompt>
+
+</Tab>
+</Tabs>
 
 Conversations are formatted using special tokens:
 
-* **`<|startoftext|>`** — Start of the conversation.
-* **`<|im_start|>`** — Start of the message. Always followed by the role name (`system`, `user`, `assistant`, or `tool`) and a line break.
-* **`<|im_end|>`** — End of the message.
-* **`<think>`** / **`</think>`** — Start and end of the model's reasoning, at the beginning of an assistant turn.
+| Special token | Meaning |
+|---|---|
+| `<\|startoftext\|>` | Start of the conversation. |
+| `<\|im_start\|>` | Start of the message. Always followed by the role name (`system`, `user`, `assistant`, or `tool`) and a line break. |
+| `<\|im_end\|>` | End of the message. |
+| `<think>` / `</think>` | Start and end of the model's reasoning, at the beginning of an assistant turn. See [Thinking](/lfm/key-concepts/thinking). |
 
-LFM3 supports four conversation roles:
+LFM models support four conversation roles:
 
 * **`system`** — (Optional) Defines who the assistant is and how it should respond.
 * **`user`** — Messages from the user containing questions and instructions.
@@ -30,22 +43,21 @@
 
 The complete chat template definition can be found in the `chat_template.jinja` file in each model's Hugging Face repository.
 
-<Note>
-Using LFM2 or LFM2.5? See [LFM2 and LFM2.5](#lfm2-and-lfm2-5) for their chat template.
-</Note>
-
 ## Text Models
 
 We recommend storing your conversation as a list of dictionaries as follows:
 
 ```python
 messages = [
     {"role": "system", "content": "You are a helpful assistant trained by Liquid AI."},
-    {"role": "user", "content": "Explain how a heat pump works."}
+    {"role": "user", "content": "What is C. elegans?"}
 ]
 ```
 
-You can then apply LFM3's chat template using the [`.apply_chat_template()`](https://huggingface.co/docs/transformers/main/en/chat_templating#using-applychattemplate) method from Transformers:
+You can then apply the model's chat template using the [`.apply_chat_template()`](https://huggingface.co/docs/transformers/main/en/chat_templating#using-applychattemplate) method from Transformers:
+
+<Tabs>
+<Tab title="LFM3">
 
 ```python
 from transformers import AutoTokenizer
@@ -61,29 +73,69 @@
 print(prompt)
 ```
 
-Output:
+**Output**
 
+<LFM3ChatPrompt></LFM3ChatPrompt>
+
+</Tab>
+<Tab title="LFM2/LFM2.5">
+
+```python
+from transformers import AutoTokenizer
+
+tokenizer = AutoTokenizer.from_pretrained("LiquidAI/LFM2.5-1.2B-Instruct")
+
+# Apply chat template
+prompt = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True
+)
+print(prompt)
 ```
-<|startoftext|><|im_start|>system
-You are a helpful assistant trained by Liquid AI.<|im_end|>
-<|im_start|>user
-Explain how a heat pump works.<|im_end|>
-<|im_start|>assistant
-<think>
-```
+
+**Output**
+
+<LFM25ChatPrompt></LFM25ChatPrompt>
+
+</Tab>
+</Tabs>
 
 ### Reasoning
 
+<Tabs>
+<Tab title="LFM3">
+
 Thinking models reason before they answer, so the template opens every assistant turn with `<think>`. Two arguments to `apply_chat_template()` control this:
 
 * **`enable_thinking`** (default `True`) — On models that can switch thinking off, `enable_thinking=False` fills in an empty `<think></think>` block instead, so the model starts on the answer straight away. Models that always think don't support `False`.
 * **`preserve_thinking`** (default `False`) — The template removes the reasoning from assistant turns before the latest user message. Set `preserve_thinking=True` to keep it in the prompt.
 
+</Tab>
+<Tab title="LFM2/LFM2.5">
+
+LFM2.5 thinking models always think, and their templates have no `enable_thinking` argument. Depending on the model, the template opens the assistant turn with `<think>` or the model writes it itself. Either way, the reply contains a closing `</think>` before the answer.
+
+For LFM2.5-8B-A1B and LFM2.5-24B-A2B, reasoning before the latest user message is removed by default, while reasoning from later assistant turns stays. LFM2.5-1.2B-Thinking instead retains only the last assistant message's reasoning by default. Set `preserve_thinking=True` to retain reasoning from all assistant messages; LFM2.5-1.2B-Thinking also accepts the older name `keep_past_thinking`.
+
+</Tab>
+</Tabs>
+
 See [Thinking](/lfm/key-concepts/thinking) for how to use thinking, separate the reasoning from the answer, and check which models can switch thinking off.
 
 ## Vision Models
 
-LFM3-VL models follow the same chat template with additional support for images and videos. Each image is rendered as `<|vision_start|><|image|><|vision_end|>` and each video as `<|vision_start|><|video|><|vision_end|>`. The processor's `.apply_chat_template()` method inserts these tokens automatically, so do not include them in your message content.
+Vision models follow the same chat template with additional support for images. When creating conversations for vision models, use a structured format with `content` as a list containing image and text entries. You can then apply the chat template using the processor's `.apply_chat_template()` method.
+
+<Tabs>
+<Tab title="LFM3">
+
+| Special token | Meaning |
+|---|---|
+| `<\|vision_start\|><\|image\|><\|vision_end\|>` | Each image is rendered as these tokens. |
+| `<\|vision_start\|><\|video\|><\|vision_end\|>` | Each video is rendered as these tokens. |
+
+The processor's `.apply_chat_template()` method inserts these tokens automatically, so do not include them in your message content.
 
 ```python
 from transformers import AutoProcessor
@@ -110,9 +162,9 @@
 print(prompt)
 ```
 
-Output:
+**Output**
 
-```
+```text
 <|startoftext|><|im_start|>system
 You are a helpful assistant trained by Liquid AI.<|im_end|>
 <|im_start|>user
@@ -121,112 +173,128 @@
 <think>
 ```
 
-## Audio and Omni Models
+</Tab>
+<Tab title="LFM2/LFM2.5">
+
+| Special token | Meaning |
+|---|---|
+| `<image>` | When formatted, images are represented with this sentinel token, which is automatically replaced with image tokens by the processor. |
 
-LFM3-Omni follows the same chat template. Every input audio clip, image, and video sits inside a `<|vision_start|>` / `<|vision_end|>` span, which `apply_chat_template()` inserts for you. Audio clips render as `<|vision_start|><|audio|><|vision_end|>`.
+```python
+from transformers import AutoProcessor
+
+processor = AutoProcessor.from_pretrained("LiquidAI/LFM2.5-VL-1.6B")
+
+messages = [
+    {"role": "system", "content": "You are a helpful assistant trained by Liquid AI."},
+    {
+        "role": "user",
+        "content": [
+            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
+            {"type": "text", "text": "What species is in this picture?"},
+        ],
+    },
+]
 
+# Apply chat template
+prompt = processor.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True
+)
+print(prompt)
 ```
+
+**Output**
+
+```text
 <|startoftext|><|im_start|>system
-Perform ASR in English.<|im_end|>
+You are a helpful assistant trained by Liquid AI.<|im_end|>
 <|im_start|>user
-<|vision_start|><|audio|><|vision_end|><|im_end|>
+<image>What species is in this picture?<|im_end|>
 <|im_start|>assistant
 ```
 
-In the answer, `<|audio_start|>` opens speech and `<|mixed_start|>` opens interleaved text and speech. LFM3-Omni-2B is a non-reasoning model: its template opens every assistant turn with an empty `<think></think>` block. See [LFM3-Audio-2B](/lfm/models/lfm3-audio-2b) and [LFM3-Omni-2B](/lfm/models/lfm3-omni-2b) for the recommended system prompts.
-
-## LFM2 and LFM2.5
+</Tab>
+</Tabs>
 
-LFM2 and LFM2.5 use a ChatML-like chat template. Unlike LFM3, most of their templates don't open the assistant turn with `<think>` (see [LFM2.5 Thinking Models](#lfm2-5-thinking-models)):
+## Audio and Omni Models
 
-<ChatMLExample />
+Audio and omni models follow the same chat template. The processor's `.apply_chat_template()` method inserts the audio tokens for you.
 
-### LFM2 Text Models
+| Special token | Meaning |
+|---|---|
+| `<\|audio\|>` | An input audio clip. Depending on the model, it sits inside a `<\|vision_start\|>` / `<\|vision_end\|>` span, like images and video. |
+| `<\|audio_start\|>` | Opens speech in the answer. |
+| `<\|mixed_start\|>` | Opens interleaved text and speech in the answer. |
+| `<think></think>` | Empty block that the template of a non-reasoning model opens every assistant turn with. |
 
-We recommend storing your conversation as a list of dictionaries as follows:
+For example, an audio model and an omni model can format the same audio transcription request:
 
 ```python
 messages = [
-    {"role": "system", "content": "You are a helpful assistant."},
-    {"role": "user", "content": "What is machine learning?"}
+    {"role": "system", "content": "Perform ASR in English."},
+    {"role": "user", "content": [{"type": "audio", "audio": "speech.wav"}]},
 ]
 ```
 
-You can then apply LFM2's chat template using the [`.apply_chat_template()`](https://huggingface.co/docs/transformers/main/en/chat_templating#using-applychattemplate) method from Transformers:
+<Tabs>
+<Tab title="LFM3-Audio">
 
 ```python
-from transformers import AutoTokenizer
+from transformers import AutoProcessor
 
-tokenizer = AutoTokenizer.from_pretrained("LiquidAI/LFM2.5-1.2B-Instruct")
+processor = AutoProcessor.from_pretrained("LiquidAI/LFM3-Audio-2B", trust_remote_code=True)
 
 # Apply chat template
-prompt = tokenizer.apply_chat_template(
+prompt = processor.apply_chat_template(
     messages,
     tokenize=False,
-    add_generation_prompt=True
+    add_generation_prompt=True,
 )
 print(prompt)
 ```
 
-Output:
+**Output**
 
-```
+```text
 <|startoftext|><|im_start|>system
-You are a helpful assistant.<|im_end|>
+Perform ASR in English.<|im_end|>
 <|im_start|>user
-What is machine learning?<|im_end|>
+<|audio|><|im_end|>
 <|im_start|>assistant
 ```
 
-### LFM2.5 Thinking Models
-
-LFM2.5 thinking models always think, and their templates have no `enable_thinking` argument. Depending on the model, the template opens the assistant turn with `<think>` or the model writes it itself. Either way, the reply contains a closing `</think>` before the answer.
-
-For LFM2.5-8B-A1B and LFM2.5-24B-A2B, reasoning before the latest user message is removed by default, while reasoning from later assistant turns stays. LFM2.5-1.2B-Thinking instead retains only the last assistant message's reasoning by default. Set `preserve_thinking=True` to retain reasoning from all assistant messages; LFM2.5-1.2B-Thinking also accepts the older name `keep_past_thinking`. See [Thinking](/lfm/key-concepts/thinking#multi-turn-conversations) for guidance on agent conversations.
-
-### LFM2 Vision Models
-
-LFM2-VL models follow the same chat template with additional support for images. When formatted, images are represented with a sentinel token (`<image>`), which is automatically replaced with image tokens by the processor.
-
-When creating conversations for vision models, use a structured format with `content` as a list containing image and text entries:
-
-```python
-image = load_image("path/to/image.jpg")  # or use PIL Image
-
-messages = [
-    {
-        "role": "user",
-        "content": [
-            {"type": "image", "image": image},  # PIL Image or loaded image
-            {"type": "text", "text": "What is in this image?"},
-        ],
-    },
-]
-```
-
-You can then apply the chat template using the processor's `.apply_chat_template()` method:
+</Tab>
+<Tab title="LFM3-Omni">
 
 ```python
 from transformers import AutoProcessor
-from transformers.image_utils import load_image
 
-processor = AutoProcessor.from_pretrained("LiquidAI/LFM2.5-VL-1.6B")
+processor = AutoProcessor.from_pretrained("LiquidAI/LFM3-Omni-2B", trust_remote_code=True)
 
 # Apply chat template
 prompt = processor.apply_chat_template(
-    conversation,
+    messages,
     tokenize=False,
-    add_generation_prompt=True
+    add_generation_prompt=True,
 )
 print(prompt)
 ```
 
-Output:
+**Output**
 
-```
+```text
 <|startoftext|><|im_start|>system
-You are a helpful multimodal assistant by Liquid AI.<|im_end|>
+Perform ASR in English.<|im_end|>
 <|im_start|>user
-<image>What is in this image?<|im_end|>
+<|vision_start|><|audio|><|vision_end|><|im_end|>
 <|im_start|>assistant
+<think></think>
 ```
+
+</Tab>
+</Tabs>
+
+See [Speech Generation](/lfm/key-concepts/speech-generation#choose-the-output-modality) for choosing the output modality, and [Audio Capabilities](/lfm/key-concepts/audio-capabilities) for recommended system prompts.
+