Update README.md

README.md

@@ -1,85 +1,344 @@
 ---
 library_name: vllm
-pipeline_tag: text-generation
+inference: false
+extra_gated_description: >-
+  To learn more about how we process your personal data, please read our <a
+  href="https://poolside.ai/legal/privacy">Privacy Policy</a>.
 tags:
-  - laguna
-  - vllm
-  - fp8
-  - moe
+- laguna-m.1
+- vllm
+- fp8
+- moe
+license: apache-2.0
+pipeline_tag: text-generation
 ---
 
 <p align="center">
   <img alt="poolside-banner" src="https://poolside.ai/assets/laguna/laguna-m1-banner.svg" width="800px">
 </p>
 
-# Laguna-M.1 (FP8 + FP8 KV-cache)
-
-Poolside Laguna-M, FP8-quantized weights (block scheme, 128×128) with FP8 KV-cache scales.
-Packaged as a self-contained HuggingFace repo so partners can `hf download` once and
-serve via the bundled vLLM overlay image without additional build steps.
-
-## Contents
-
-| Path                                          | Size   | What it is                                                 |
-|-----------------------------------------------|--------|------------------------------------------------------------|
-| `config.json`, `*.safetensors`, `tokenizer.*` | 214 GB | Laguna-M FP8 weights + FP8 KV-cache scales + tokenizer     |
-| `image/laguna-vllm-v0.19.0-overlay.tar.gz`    | 8.9 GB | vLLM v0.19.0 Docker image with Laguna support overlaid     |
-
-## Hardware
-
-Built and tested on **NVIDIA H200 (141 GB HBM3e)**. Recommended serving config: **4× H200, TP=4**.
-Other GPU generations (H100, B200) may work but are untested.
-
-## Quickstart
-
-```bash
-# 1. Download.
-hf download poolside/Laguna-M.1 --local-dir laguna-m
-
-# 2. Load the vLLM image.
-gunzip -c laguna-m/image/laguna-vllm-v0.19.0-overlay.tar.gz | docker load
-# -> laguna-vllm:v0.19.0-overlay
-
-# 3. Serve on 4× H200.
-docker run --gpus '"device=0,1,2,3"' --network host \
-  -v "$PWD/laguna-m":/model \
-  laguna-vllm:v0.19.0-overlay \
-  /model \
-  --tensor-parallel-size 4 \
-  --trust-remote-code \
-  --dtype bfloat16 \
-  --kv-cache-dtype fp8 \
-  --max-model-len 4096 \
-  --gpu-memory-utilization 0.85 \
-  --served-model-name laguna \
-  --reasoning-parser poolside_v1 \
-  --tool-call-parser poolside_v1 \
-  --enable-auto-tool-choice \
-  --port 8000
+<p align="center">
+  <a href="https://platform.poolside.ai"><strong>Get an API key</strong></a> ·
+  <a href="https://poolside.ai/blog/laguna-a-deeper-dive"><strong>Release blog post</strong></a> ·
+  <a href="https://poolside.ai/assets/laguna/laguna-m1-xs2-technical-report.pdf"><strong>Technical report</strong></a>
+</p>
+
+<br>
+
+# Laguna M.1
+
+Laguna M.1 is a 225B total parameter Mixture-of-Experts model with 23B activated parameters per token designed for agentic coding and long-horizon work. This release provides open weights under the Apache 2.0 license, with upstream support in vLLM, Transformers and TRT-LLM.
+
+> [!NOTE]
+> For more details on how we trained this model, including our Model Factory approach, post-training recipe, async off-policy agent RL, and evaluations, check out our [release blog post](https://poolside.ai/blog/laguna-a-deeper-dive) and [technical report](https://poolside.ai/assets/laguna/laguna-m1-xs2-technical-report.pdf).
+
+## Highlights
+
+* **Large sparse MoE for agentic coding**: Laguna M.1 is a 70-layer MoE transformer with 225.8B total parameters and 23.4B activated parameters per token
+* **High-capacity expert routing**: After 3 dense SwiGLU layers, Laguna M.1 uses 67 sparse MoE layers with 256 experts, top-k=16 routing and auxiliary-loss-free load balancing
+* **Global attention architecture**: Laguna M.1 uses global attention across all layers with 64 Q-heads, 8 KV-heads and softplus attention output gating
+* **Native reasoning support**: Interleaved thinking between tool calls with support for enabling and disabling thinking per-request
+* **Strong agentic benchmark performance**: Laguna M.1 is competitive with state-of-the-art open-weight and frontier models on SWE-bench Verified, SWE-bench Multilingual, SWE-Bench Pro, and Terminal-Bench 2.0
+* **Apache 2.0 license**: Use and modify freely for commercial and non-commercial purposes
+
+---
+
+## Model overview
+
+- Training: pre-training, post-training and reinforcement learning stages
+- Number of parameters: 225B total with 23B activated per token
+- Optimizer: Muon
+- Layers: 70 layers with global attention
+- Experts: 256 experts with 1 shared expert; top-k=16 routing
+- Dense layers: first 3 layers are dense SwiGLU; remaining 67 layers are sparse MoE
+- Attention: 64 Q-heads, 8 KV-heads, head dimension 128, with softplus attention output gating
+- Positional encoding: RoPE with YaRN
+- Modality: text-to-text
+- Context window: 262,144 tokens
+- Reasoning support: interleaved thinking with preserved thinking
+
+## Benchmark results
+
+<p align="center">
+  <img alt="benchmarks" src="https://poolside.ai/assets/laguna/laguna-m1-chart.svg" width="800px">
+</p>
+
+| Model                     | Size (total params.) | SWE-bench Verified | SWE-bench Multilingual | SWE-bench Pro (Public Dataset) | Terminal-Bench 2.0 |
+|---------------------------|----------------------|--------------------|------------------------|--------------------------------|--------------------|
+| **Laguna M.1**            | 225B                 | 74.6%              | 63.1%                  | 49.2%                          | 45.8%              |
+| Devstral 2                | 123B dense           | 72.2%              | 61.3%                  | -                              | 32.6%              |
+| GLM-4.7                   | 355B-A32B            | 73.8%              | 66.7%                  | -                              | 41.0%              |
+| DeepSeek-V4 Flash         | 284B-A13B            | 79.0%              | 73.3%                  | 52.6%                          | 56.9%              |
+| Qwen3.5-397B-A17B         | 397B-A17B            | 76.2%              | 69.3%                  | 50.9%                          | 52.5%              |
+| Claude Sonnet 4.6         | -                    | 79.6%              | -                      | -                              | 59.1%              |
+
+*We used the highest publicly-referenced scores for all comparison models across each benchmark. In almost all cases these were official scores published in release blog posts or equivalent, with Claude Sonnet 4.6 shown as a frontier proprietary reference of comparable model size. “-” indicates a score not reported by the model provider.*
+
+<details>
+<summary>Expand for benchmarking methodology</summary>
+
+All benchmarking for Laguna M.1 was completed using our [pool agent harness](https://github.com/poolsideai/pool), with a maximum of 500 steps and sandboxed execution. The same sampling parameters were used for all Laguna M.1 benchmarking: temperature=1.0 and top_k=20, with thinking mode enabled and a context length of 256K tokens. All tasks were run in their own sandbox using 8 GB RAM/2 CPUs, with the exception of Terminal-Bench 2.0, which used 48 GB RAM/32 CPUs.
+
+Some base task images and verifiers were patched to fix infrastructure reliability issues inherent in task setup, such as rate limits on third-party dependencies in external registries used by the verifier. All four agentic benchmarks were run with patched images. We also ran a reward-hack judge post-hoc on Laguna M.1 evaluation runs and did not find significant reward hacking after joint judge review and manual review.
+
+- SWE-bench Verified: mean pass@1 averaged over 4 runs
+- SWE-bench Multilingual: mean pass@1 averaged over 4 runs
+- SWE-Bench Pro: mean pass@1 averaged over 4 runs
+- Terminal-Bench 2.0: mean pass@1 averaged over 4 runs; 48 GB RAM/32 CPUs
+
+</details>
+
+## Usage
+
+Laguna M.1 is available through the Poolside API and as open weights under the Apache 2.0 license.
+
+The fastest way to get started is with our API, directly or using OpenRouter.
+
+> [!NOTE]
+> We are providing free access for a limited time to Laguna M.1 and Laguna XS.2 on our API. You can create an API key on our [Platform](https://platform.poolside.ai).
+
+### pool
+
+**pool** is a lightweight terminal-based coding agent and a dual [Agent Client Protocol](https://agentclientprotocol.com/get-started) client-server.
+
+Download and install for macOS and Linux:
+
+```shell
+curl -fsSL https://downloads.poolside.ai/pool/install.sh | bash
+```
+
+Launch and *Log in with Poolside* to get a free API key.
+
+```shell
+pool
+```
+
+Use in any [ACP client](https://agentclientprotocol.com/get-started/clients). Configure Zed and JetBrains automatically:
+
+```shell
+pool acp setup --editor zed|jetbrains
+```
+
+#### Feedback and issues
+
+Submit feedback with `/feedback` and read the [full documentation on GitHub](https://github.com/poolsideai/pool).
+
+### Local deployment
+
+Laguna M.1 is supported in vLLM and Transformers, and TRT-LLM thanks to the support of the team at NVIDIA.
+
+#### vLLM
+
+Serve Laguna M.1 locally with vLLM and query it from any OpenAI-compatible client (see [Controlling reasoning](#controlling-reasoning) for tool calls, streaming, and reasoning extraction):
+
+> [!NOTE]
+> Laguna M.1 support is available in upstream vLLM.
+
+```shell
+pip install vllm
+
+vllm serve \
+    --model poolside/Laguna-M.1 \
+    --tool-call-parser poolside_v1 \
+    --reasoning-parser poolside_v1 \
+    --enable-auto-tool-choice \
+    --served-model-name laguna \
+    --default-chat-template-kwargs '{"enable_thinking": true}'
+```
+
+See the [vLLM recipes page](https://recipes.vllm.ai/poolside/Laguna-XS.2) for our Laguna XS.2 model with which the implementation is shared for additional deployment guidance.
+
+#### Transformers
+
+Laguna M.1 is supported in Transformers.
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_id = "poolside/Laguna-M.1"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    dtype=torch.bfloat16,
+    device_map="auto",
+)
+
+messages = [
+    {"role": "user", "content": "Write a Python retry wrapper with exponential backoff."},
+]
+
+# Reasoning is on by default; pass enable_thinking=False to skip the <think> block.
+inputs = tokenizer.apply_chat_template(
+    messages,
+    add_generation_prompt=True,
+    return_tensors="pt",
+    enable_thinking=True,
+).to(model.device)
+
+outputs = model.generate(
+    inputs,
+    max_new_tokens=1024,
+    do_sample=True,
+    temperature=1,
+    top_k=20,
+)
+
+response = tokenizer.decode(outputs[0][inputs.shape[-1]:], skip_special_tokens=True)
+print(response)
+```
+
+#### TRT-LLM
+
+Laguna M.1 is supported in TRT-LLM thanks to the support of the team at NVIDIA.
+
+```python
+from tensorrt_llm import LLM, SamplingParams
+
+llm = LLM(
+    model="poolside/Laguna-M.1",
+    trust_remote_code=True,
+    tensor_parallel_size=4,
+)
+
+sampling = SamplingParams(max_tokens=1024, temperature=1, top_k=20)
+out = llm.generate(["Write a Python retry wrapper with exponential backoff."], sampling)
+print(out[0].outputs[0].text)
+```
+
+Or serve with an OpenAI-compatible endpoint:
+
+```shell
+trtllm-serve poolside/Laguna-M.1 --port 8000 --trust-remote-code
 ```
 
-Smoke test once the server logs `Application startup complete`:
+## Controlling reasoning
 
-```bash
-curl -s http://127.0.0.1:8000/v1/completions \
-  -H 'Content-Type: application/json' \
-  -d '{"model":"laguna","prompt":"The capital of France is","max_tokens":8,"temperature":0}'
+Laguna M.1 has native reasoning support and is designed to work best with *preserved thinking*, where `reasoning` content from prior assistant messages is preserved in the message history. This model will generally reason before calling tools and between tool calls.
+
+<details>
+<summary>Expand for example</summary>
+
+```python
+import json
+from openai import OpenAI
+
+client = OpenAI(
+  base_url="https://inference.poolside.ai/v1",
+  api_key="...",
+)
+
+model = "poolside/laguna-m.1"
+
+tools = [{"type": "function", "function": {
+  "name": "shell",
+  "description": "Execute a bash command and return the output.",
+  "parameters": {"type": "object", "properties": {"cmd": {"type": "string"}}, "required": ["cmd"]},
+}}]
+
+messages = [
+  {"role": "system", "content": "You are a coding agent with access to a shell tool."},
+  {"role": "user", "content": "Run uname -a"},
+]
+
+# Thinking is enabled by default when the server sets --default-chat-template-kwargs {"enable_thinking": True}
+# When using the Poolside API (https://inference.poolside.ai/v1), this flag is set by default
+response = client.chat.completions.create(
+  model=model,
+  messages=messages,
+  tools=tools,
+  stream=True,
+)
+
+reasoning, content, tool_calls = "", "", []
+for chunk in response:
+  delta = chunk.choices[0].delta
+  if hasattr(delta, "reasoning_content") and delta.reasoning_content:
+    reasoning += delta.reasoning_content
+  if hasattr(delta, "content") and delta.content:
+    content += delta.content
+  if hasattr(delta, "tool_calls") and delta.tool_calls:
+    for tc in delta.tool_calls:
+      if tc.index >= len(tool_calls):
+        tool_calls.append({"id": tc.id, "function": {"name": "", "arguments": ""}})
+      if tc.function.name:
+        tool_calls[tc.index]["function"]["name"] = tc.function.name
+      if tc.function.arguments:
+        tool_calls[tc.index]["function"]["arguments"] += tc.function.arguments
+
+print(f"Reasoning: {reasoning}\nContent: {content}\nTool calls: {tool_calls}\n")
+
+# Return reasoning in the next request for best performance
+messages.append({
+  "role": "assistant",
+  "content": content,
+  "reasoning_content": reasoning,
+  "tool_calls": [{"id": tc["id"], "type": "function", "function": tc["function"]} for tc in tool_calls]
+})
+
+messages.append({
+  "role": "tool",
+  "tool_call_id": tool_calls[0]["id"],
+  "content": json.dumps({"stdout": "Darwin arm64", "exit_code": "0"})
+})
+
+response = client.chat.completions.create(
+  model=model,
+  messages=messages,
+  tools=tools,
+  stream=True,
+)
+
+reasoning, content = "", ""
+for chunk in response:
+  delta = chunk.choices[0].delta
+  if hasattr(delta, "reasoning_content") and delta.reasoning_content:
+    reasoning += delta.reasoning_content
+  if hasattr(delta, "content") and delta.content:
+    content += delta.content
+
+print(f"Reasoning: {reasoning}\nContent: {content}")
 ```
 
-## Eval (5-shot)
+</details>
+
+### Disabling reasoning
+
+You can disable thinking by setting `enable_thinking` to `False` in a request or by not providing `--default-chat-template-kwargs {"enable_thinking": True}` or equivalent when starting the server.
+
+<details>
+<summary>Expand for example</summary>
+
+```python
+from openai import OpenAI
+client = OpenAI()
+
+completion = client.chat.completions.create(
+  model="poolside/laguna-m.1",
+  messages=[
+    {"role": "user", "content": "Write a retry wrapper with exponential backoff."}
+  ],
+  extra_body={
+    "chat_template_kwargs": { "enable_thinking": False },
+  },
+  stream=True
+)
+
+for chunk in completion:
+    print(chunk.choices[0].delta)
+```
+
+</details>
+
+For agentic coding use cases, we recommend enabling thinking and preserving reasoning in message history as outlined in the [Controlling reasoning](#controlling-reasoning) section.
 
-- MMLU: 79.06% ± 0.33%  *(all 14k questions, TP=4 H200)*
-- GSM8K: 92% strict-match  *(n=50 smoke, TP=4 H200; full run to come)*
+## License
 
-## Architecture
+This model is licensed under the [Apache 2.0 License](https://huggingface.co/poolside/Laguna-M.1/blob/main/LICENSE.md).
 
-Laguna-M is a 70-layer MoE transformer:
+## Intended and Responsible Use 
 
-- hidden=4096, Q-heads=64, KV-heads=8, head_dim=128 (Q-projection is 2× hidden → 8192)
-- First 3 layers dense SwiGLU; remaining 67 are sparse MoE (256 experts, top-k=16, sigmoid router, shared expert)
-- Per-element attention output gating (softplus)
-- RoPE θ=500000, YaRN factor=32, original ctx 4096
-- Auxiliary-loss-free load balancing via `e_score_correction_bias`
+Laguna M.1 is designed for software engineering and agentic coding use cases, and you are responsible for confirming that it is appropriate for your intended application. Laguna M.1 is subject to the [Apache 2.0 License](https://huggingface.co/poolside/Laguna-M.1/blob/main/LICENSE.md), and should be used consistently with Poolside's [Acceptable Use Policy](https://poolside.ai/legal/acceptable-use-policy). We advise against circumventing Laguna M.1 safety guardrails without implementing substantially equivalent mitigations appropriate for your use case.
 
-Weights use compressed-tensors FP8 block format (128×128 blocks, dynamic activation quant).
-FP8 KV-cache scales are included under `model.layers.*.self_attn.{k,v}_scale`.
+Please report security vulnerabilities or safety concerns to [security@poolside.ai](mailto:security@poolside.ai).