Add diffusion language model API example

README.md

@@ -20,6 +20,9 @@ results + artifacts (trackio dashboards, jobs, models) over resumable SSE.
 The Space root serves the interactive API documentation. Endpoints live
 under `/v1` — start at `POST /v1/responses`.
 
+The docs include verified public-endpoint examples, starting with short
+research/model-selection tasks and extending to longer artifact-producing runs.
+
 Source: https://github.com/huggingface/ml-intern (see `docs/API.md`).
 
 Optional Space secrets:

api-docs/example-results/diffusion-language-models.json

@@ -0,0 +1,79 @@
+{
+  "request": {
+    "slug": "diffusion-language-models",
+    "title": "Research a cutting-edge concept",
+    "model": "moonshotai/Kimi-K2.6:novita",
+    "input": "Research diffusion language models for text generation. In 5 concise bullets, explain what changed recently, why it matters, and cite 2 relevant Hugging Face paper pages or model pages if available. Keep under 300 words.",
+    "background": true,
+    "max_cost_usd": 3.0,
+    "metadata": {
+      "example_slug": "diffusion-language-models"
+    }
+  },
+  "response": {
+    "id": "resp_bf64687c764f4d509a134188390a2236",
+    "object": "response",
+    "created_at": 1781313817,
+    "completed_at": 1781313849,
+    "status": "completed",
+    "model": "moonshotai/Kimi-K2.6:novita",
+    "background": true,
+    "previous_response_id": null,
+    "session_id": "7f8b617e-640d-4aa8-a8df-1402037b7c71",
+    "max_cost_usd": 3.0,
+    "instructions": null,
+    "output": [
+      {
+        "type": "custom_tool_call",
+        "id": "functions.hf_papers:0",
+        "name": "hf_papers",
+        "input": "{\"operation\": \"search\", \"query\": \"diffusion language models text generation\", \"date_from\": \"2024-01-01\", \"limit\": 15}",
+        "output": "# Papers matching 'diffusion language models text generation'\nShowing 15 paper(s)\n\n## 1. Energy-Based Diffusion Language Models for Text Generation\n**arxiv_id:** 2410.21357 | **upvotes:** 3\nhttps://huggingface.co/papers/2410.21357\n**Keywords:** discrete diffusion models, parallel generation, Energy-based Diffusion Language Model, energy-based model, residual form\n**GitHub:** https://github.com/MinkaiXu/Energy-Diffusion-LLM (69 stars)\n**Summary:** Energy-based Diffusion Language Model improves diffusion-based generation by using an energy-based model with parameter optimization from autoregressive models and achieves faster sampling speeds with comparable performance to autoregressive models.\n\n## 2. Dependency-Guided Parallel Decoding in Discrete Diffusion Language Models\n**arxiv_id:** 2604.02560 | **upvotes:** 0\nhttps://huggingface.co/papers/2604.02560\n**Keywords:** discrete diffusion language models, parallel decoding, distributional mismatch, joint conditional, per-token marginals\n**Summary:** Discrete diffusion language models accelerate text generation by parallel token unmasking, but this introduces distributional mismatch; a dependency predictor called DEMASK addresses this by identifying bounded cumulative dependency positions for simultaneous unmasking under sub-additivity assumptio...\n\n## 3. DPad: Efficient Diffusion Language Models with Suffix Dropout\n**arxiv_id:** 2508.14148 | **upvotes:** 0\nhttps://huggingface.co/papers/2508.14148\n**Keywords:** diffusion-based large language models, denoising process, attention, sliding window, distance-decay dropout\n**GitHub:** https://github.com/Crys-Chen/DPad (62 stars)\n**Summary:** Diffusion Scratchpad (DPad) enhances the efficiency of diffusion-based large language models by restricting attention to nearby tokens, achieving significant speedup without compromising accuracy.\n\n## 4. Unveiling the Potential of Diffusion Large Language Model in\n  Controllable Generation\n**arxiv_id:** 2507.04504 | **upvotes:** 1\nhttps://huggingface.co/papers/2507.04504\n**Keywords:** diffusion models, autoregressive large language models, dLLMs, bidirectional attention mechanism, controllable generation\n**Summary:** A novel framework, S<sup>3</sup>, enhances diffusion language models for controllable text generation by improving context modeling, reducing hallucinations, and accelerating inference.\n\n## 5. FS-DFM: Fast and Accurate Long Text Generation with Few-Step Diffusion\n  Language Models\n**arxiv_id:** 2509.20624 | **upvotes:** 1\nhttps://huggingface.co/papers/2509.20624\n**Summary:** Autoregressive language models (ARMs) deliver strong likelihoods, but are\ninherently serial: they generate one token per forward pass, which limits\nthroughput and inflates latency for long sequences. Diffusion Language Models\n(DLMs) parallelize across positions and thus appear promising for language...\n\n## 6. Text Generation with Diffusion Language Models: A Pre-training Approach\n  with Continuous Paragraph Denoise\n**arxiv_id:** 2212.11685 | **upvotes:** 2\nhttps://huggingface.co/papers/2212.11685\n**Keywords:** diffusion language model, encoder, diffusion-based decoder, continuous paragraph denoise objective, semantic coherence\n**Summary:** GENIE, a diffusion-based language model with an encoder and diffusion decoder, achieves state-of-the-art performance in text generation by using a continuous paragraph denoise objective.\n\n## 7. A Survey on Parallel Text Generation: From Parallel Decoding to\n  Diffusion Language Models\n**arxiv_id:** 2508.08712 | **upvotes:** 0\nhttps://huggingface.co/papers/2508.08712\n**Keywords:** Large Language Models, autoregressive, parallel text generation, token-by-token, inference efficiency\n**GitHub:** https://github.com/zhanglingzhe0820/Awesome-Parallel-Text-Generation (43 stars)\n**Summary:** A survey of parallel text generation methods categorizes and analyzes AR-based and Non-AR-based techniques, assessing their trade-offs and potential for improving inference efficiency in LLMs.\n\n## 8. CtrlDiff: Boosting Large Diffusion Language Models with Dynamic Block\n  Prediction and Controllabl\u2026 [truncated 4109 chars]",
+        "status": "completed"
+      },
+      {
+        "type": "custom_tool_call",
+        "id": "functions.web_search:1",
+        "name": "web_search",
+        "input": "{\"query\": \"site:huggingface.co diffusion language model text generation\"}",
+        "output": "{\n  \"query\": \"site:huggingface.co diffusion language model text generation\",\n  \"results\": [\n    \"Search results for 'site:huggingface.co diffusion language model text generation'. Include a Sources section in the final answer.\\n- [Towards Speed-of-Light Text Generation with Nemotron-Labs Diffusion ...](https://huggingface.co/blog/nvidia/nemotron-labs-diffusion)\\n- [Diffusion Language Models: The New Paradigm - Hugging Face](https://huggingface.co/blog/ProCreations/diffusion-language-model)\\n- [Text diffusion - a stereoplegic Collection - Hugging Face](https://huggingface.co/collections/stereoplegic/text-diffusion)\\n- [google/diffusiongemma-26B-A4B-it \\u00b7 Hugging Face](https://huggingface.co/google/diffusiongemma-26B-A4B-it)\\n- [Paper page - Diffusion-LM Improves Controllable Text Generation](https://huggingface.co/papers/2205.14217)\\n- [Paper page - Text Generation with Diffusion Language Models: A Pre ...](https://huggingface.co/papers/2212.11685)\\n- [Energy-Based Diffusion Language Models for Text Generation](https://huggingface.co/papers/2410.21357)\\n- [SSD-LM: Semi-autoregressive Simplex-based Diffusion Language Model for ...](https://huggingface.co/papers/2210.17432)\",\n    {\n      \"tool_use_id\": \"functions.web_search:1\",\n      \"content\": [\n        {\n          \"title\": \"Towards Speed-of-Light Text Generation with Nemotron-Labs Diffusion ...\",\n          \"url\": \"https://huggingface.co/blog/nvidia/nemotron-labs-diffusion\"\n        },\n        {\n          \"title\": \"Diffusion Language Models: The New Paradigm - Hugging Face\",\n          \"url\": \"https://huggingface.co/blog/ProCreations/diffusion-language-model\"\n        },\n        {\n          \"title\": \"Text diffusion - a stereoplegic Collection - Hugging Face\",\n          \"url\": \"https://huggingface.co/collections/stereoplegic/text-diffusion\"\n        },\n        {\n          \"title\": \"google/diffusiongemma-26B-A4B-it \\u00b7 Hugging Face\",\n          \"url\": \"https://huggingface.co/google/diffusiongemma-26B-A4B-it\"\n        },\n        {\n          \"title\": \"Paper page - Diffusion-LM Improves Controllable Text Generation\",\n          \"url\": \"https://huggingface.co/papers/2205.14217\"\n        },\n        {\n          \"title\": \"Paper page - Text Generation with Diffusion Language Models: A Pre ...\",\n          \"url\": \"https://huggingface.co/papers/2212.11685\"\n        },\n        {\n          \"title\": \"Energy-Based Diffusion Language Models for Text Generation\",\n          \"url\": \"https://huggingface.co/papers/2410.21357\"\n        },\n        {\n          \"title\": \"SSD-LM: Semi-autoregressive Simplex-based Diffusion Language Model for ...\",\n          \"url\": \"https://huggingface.co/papers/2210.17432\"\n        }\n      ]\n    }\n  ],\n  \"durationSeconds\": 0.7180289310053922\n}",
+        "status": "completed"
+      },
+      {
+        "type": "message",
+        "id": "msg_2",
+        "role": "assistant",
+        "status": "completed",
+        "content": [
+          {
+            "type": "output_text",
+            "text": "**Diffusion language models (DLMs) have shifted from research curiosity to viable AR alternatives.** Google's **DiffusionGemma-26B** now matches autoregressive quality at scale, demonstrating that discrete diffusion can compete on standard benchmarks.\n\n**Few-step decoding has become practical.** Methods like **T3D** (trajectory self-distillation) and **IDLM** (inverse distillation) collapsed sampling from hundreds of steps to 4\u20138 while preserving quality. This removes the main adoption barrier\u2014DLMs are no longer prohibitively slow at inference.\n\n**Hybrid \"plan-and-fill\" architectures are now dominant.** Models like **CtrlDiff** and **FS-DFM** use autoregressive skeleton planning followed by parallel diffusion-based token filling. This semi-autoregressive approach captures AR coherence benefits with DLM parallelization speedups.\n\n**Controllability is emerging as the killer feature.** Bidirectional attention in DLMs enables fine-grained control over length, style, and structure mid-generation\u2014something causal AR models cannot easily do. Recent frameworks like **S\u00b3** exploit this for structured outputs and prompt adherence.\n\n**Reasoning capabilities are being unlocked.** Papers such as **d\u00b2** and the energy-based diffusion LLM show that with policy-gradient training and energy-based formulations, DLMs can match or exceed AR models on math and logical reasoning tasks, challenging the assumption that autoregression is necessary for complex reasoning.\n\n**Relevant Hugging Face pages:**\n- Model: [google/diffusiongemma-26B-A4B-it](https://huggingface.co/google/diffusiongemma-26B-A4B-it)\n- Paper: [T3D: Few-Step Diffusion Language Models via Trajectory Self-Distillation](https://huggingface.co/papers/2602.12262)"
+          }
+        ]
+      }
+    ],
+    "error": null,
+    "incomplete_details": null,
+    "usage": {
+      "session_id": "7f8b617e-640d-4aa8-a8df-1402037b7c71",
+      "total_usd": 0.0,
+      "inference_usd": 0.0,
+      "hf_jobs_estimated_usd": 0.0,
+      "sandbox_estimated_usd": 0.0,
+      "llm_calls": 3,
+      "hf_jobs_count": 0,
+      "sandbox_count": 0,
+      "prompt_tokens": 48470,
+      "completion_tokens": 1131,
+      "cache_read_tokens": 0,
+      "cache_creation_tokens": 0,
+      "total_tokens": 49601,
+      "hf_jobs_billable_seconds_estimate": 0,
+      "sandbox_billable_seconds_estimate": 0
+    },
+    "artifacts": [],
+    "metadata": {
+      "example_slug": "diffusion-language-models"
+    }
+  }
+}

api-docs/index.html

@@ -183,6 +183,23 @@ td:first-child code { white-space: nowrap; }
 }
 .callout b { color: var(--ink); }
 
+/* examples */
+.examples { display: grid; gap: 14px; margin-top: 14px; }
+.example {
+  background: #fff; border: 1px solid var(--line); border-radius: 8px;
+  padding: 14px 16px;
+}
+.example h3 { margin: 0 0 6px; }
+.example .meta {
+  display: flex; flex-wrap: wrap; gap: 6px; margin: 8px 0 10px;
+}
+.example .meta code {
+  border: 1px solid var(--line-soft); background: var(--bg-deep);
+  font-size: 11.5px; padding: 2px 7px; border-radius: 5px;
+}
+.example p { font-size: 13.5px; }
+.example pre { white-space: pre-wrap; word-break: break-word; }
+
 /* ── terminal (animated example) ───────────────────── */
 .term { background: var(--terminal); border: 1px solid var(--terminal-edge); border-radius: 10px; overflow: hidden; margin: 18px 0 6px; }
 .term-bar { display: flex; align-items: center; gap: 6px; padding: 10px 14px; border-bottom: 1px solid var(--terminal-edge); }
@@ -218,6 +235,7 @@ td:first-child code { white-space: nowrap; }
     <h5>Getting started</h5>
     <a href="#overview">Overview</a>
     <a href="#authentication">Authentication</a>
+    <a href="#examples">Examples</a>
     <a href="#conventions">Conventions</a>
     <h5>Endpoints</h5>
     <a href="#create"><span class="m post">POST</span>/responses</a>
@@ -300,6 +318,33 @@ td:first-child code { white-space: nowrap; }
   lifetime only.</p>
 </section>
 
+<!-- ════════ EXAMPLES ════════ -->
+<section id="examples">
+  <h2>Examples <a class="anchor" href="#examples">#</a></h2>
+  <p>Verified against the public Space endpoint. Each example uses
+  <code>background: true</code>, then polls <code>GET /v1/responses/{id}</code> until terminal status.</p>
+
+  <div class="examples">
+    <article class="example">
+      <h3>Research a cutting-edge concept</h3>
+      <div class="meta">
+        <code>completed</code><code>43 s</code><code>hf_papers</code><code>resp_bf64687c764f4d509a134188390a2236</code>
+      </div>
+      <p><b>Task:</b> Research diffusion language models for text generation; explain recent changes and cite Hugging Face paper/model pages.</p>
+      <div class="codebox"><span class="lang">request</span><button class="copy" type="button">copy</button>
+<pre>{
+  "model": "moonshotai/Kimi-K2.6:novita",
+  "input": "Research diffusion language models for text generation. In 5 concise bullets, explain what changed recently, why it matters, and cite 2 relevant Hugging Face paper pages or model pages if available. Keep under 300 words.",
+  "background": true,
+  "max_cost_usd": 3.0
+}</pre></div>
+      <p><b>Result:</b> The agent found recent DLM work, identified few-step decoding and hybrid plan-and-fill architectures as key shifts, and cited
+      <a href="https://huggingface.co/google/diffusiongemma-26B-A4B-it" target="_blank" rel="noopener">google/diffusiongemma-26B-A4B-it</a> plus
+      <a href="https://huggingface.co/papers/2602.12262" target="_blank" rel="noopener">T3D on HF Papers</a>.</p>
+    </article>
+  </div>
+</section>
+
 <!-- ════════ CONVENTIONS ════════ -->
 <section id="conventions">
   <h2>Conventions <a class="anchor" href="#conventions">#</a></h2>