docs(api): one documented way to turn reasoning off, on every chat model

src/content/docs-es/examples.md

@@ -78,7 +78,7 @@ Instalación: `npm install openai`
 
 ### salida estructurada en deepseek-v4-flash
 
-`deepseek-v4-flash` rechaza `response_format` `json_schema` con un `400`, y `json_object` solo garantiza JSON válido, no su forma. Para obtener una salida que siga un esquema, define una única herramienta de tipo función cuyo `parameters` sea tu JSON Schema (raíz `"type": "object"`, `"strict": true`) y fuérzala con `tool_choice`. El modelo devuelve argumentos que siguen el esquema en `choices[0].message.tool_calls[0].function.arguments`, como una cadena JSON. `strict` pide que se ajusten exactamente; se aplica donde el modelo admite decodificación estricta, así que valida los argumentos si tu código depende de ellos.
+En `api.nan.builders`, `deepseek-v4-flash` rechaza `response_format` `json_schema` con un `400` (en `api.helmcode.com` se acepta), y `json_object` solo garantiza JSON válido, no su forma. Para obtener una salida que siga un esquema, define una única herramienta de tipo función cuyo `parameters` sea tu JSON Schema (raíz `"type": "object"`, `"strict": true`) y fuérzala con `tool_choice`. El modelo devuelve argumentos que siguen el esquema en `choices[0].message.tool_calls[0].function.arguments`, como una cadena JSON. `strict` pide que se ajusten exactamente; se aplica donde el modelo admite decodificación estricta, así que valida los argumentos si tu código depende de ellos.
 
 ```bash
 curl https://api.nan.builders/v1/chat/completions \

src/content/docs-es/models.mdx

@@ -33,7 +33,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (function calling)',
-    'Modo razonamiento (traza de razonamiento)',
+    'Control del razonamiento (<code>reasoning_effort</code>: de <code>minimal</code> a <code>max</code>; siempre razona, <code>none</code> se aplica como <code>minimal</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
     'Audio (entrada de audio)',
     'Vídeo (entrada de vídeo)',
@@ -50,7 +50,7 @@ OpenAI y la misma `base URL`.
   tag="305B MoE"
   leftLabel="generación de texto, chat y visión"
   rightLabel="capacidades"
-  description="Modelo MoE de 305B parámetros, servido en su variante Vision-Exp: acepta imágenes de entrada. Contexto de 1M tokens. Tool calling y razonamiento. Cuota de 3B tokens al mes por miembro. Salida estructurada: response_format json_object es compatible (el prompt debe contener la palabra JSON; si no, se rechaza con un 400), json_schema no y se rechaza con un 400. json_object solo garantiza JSON sintácticamente válido, no su forma: describe el esquema en el prompt. Para salida restringida a un esquema, usa qwen3.6 o gemma4, donde json_schema con strict restringe campos, tipos y claves obligatorias; o, en este modelo, fuerza una única herramienta de tipo función cuyo parameters sea tu esquema (ver Ejemplos). Un max_tokens por debajo de 16384 se sube a 16384 para que quepa el razonamiento, así que un prompt a menos de 16384 tokens de la ventana de 1.048.576 se rechaza con un 400 aunque pidas un max_tokens pequeño (normalmente Context length exceeded, a veces un Invalid request genérico)."
+  description={'Modelo MoE de 305B parámetros, servido en su variante Vision-Exp: acepta imágenes de entrada. Contexto de 1M tokens. Tool calling y razonamiento. Cuota de 3B tokens al mes por miembro. La salida estructurada depende del host: en api.helmcode.com se aceptan response_format json_schema y json_object; en api.nan.builders, json_object es compatible (el prompt debe contener la palabra JSON; si no, se rechaza con un 400) y json_schema se rechaza con un 400. json_object solo garantiza JSON sintácticamente válido, no su forma: describe el esquema en el prompt. Para salida restringida a un esquema en api.nan.builders, usa qwen3.6 o gemma4, donde json_schema con strict restringe campos, tipos y claves obligatorias; o, en este modelo, fuerza una única herramienta de tipo función cuyo parameters sea tu esquema (ver Ejemplos). Con el razonamiento activado, un max_tokens por debajo de 16384 se sube a 16384 para que quepa el razonamiento, así que un prompt a menos de 16384 tokens de la ventana de 1.048.576 se rechaza con un 400 aunque pidas un max_tokens pequeño (normalmente Context length exceeded, a veces un Invalid request genérico). Con el razonamiento apagado (reasoning_effort "none" o cualquiera de sus alias) tu max_tokens se usa tal cual.'}
   specs={[
     { label: 'Tipo', value: 'MoE (305B total)' },
     { label: 'Cuantización', value: 'FP8' },
@@ -61,9 +61,9 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling',
-    'Modo razonamiento',
+    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> lo apaga · de <code>minimal</code> a <code>max</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
-    'Modo JSON (<code>json_object</code>, el prompt debe mencionar JSON) · <code>json_schema</code> no soportado (400)',
+    'Modo JSON (<code>json_object</code>; en api.nan.builders el prompt debe mencionar JSON) · <code>json_schema</code>: 400 en api.nan.builders, aceptado en api.helmcode.com',
     'Contexto de 1M tokens',
     'Generación en streaming (SSE)',
   ]}
@@ -87,7 +87,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (function calling)',
-    'Modo razonamiento',
+    'Control del razonamiento (<code>reasoning_effort</code>: de <code>minimal</code> a <code>max</code>; siempre razona, <code>none</code> se aplica como <code>minimal</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
     'Contexto de 1M tokens',
     'Generación en streaming (SSE)',
@@ -112,7 +112,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (formato XML)',
-    'Modo razonamiento (activado por defecto)',
+    'Razonamiento activado por defecto (<code>reasoning_effort</code>: <code>none</code> lo apaga · de <code>minimal</code> a <code>max</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
     'Contexto de 1M tokens',
     'Generación en streaming (SSE)',
@@ -134,7 +134,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (function calling)',
-    'Modo razonamiento (se recomienda <code>max_tokens &ge; 300</code>)',
+    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> lo apaga · de <code>low</code> a <code>max</code>; se recomienda <code>max_tokens &ge; 300</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Visión (entrada de imagen)',
     'Audio (entrada de audio)',
     'Contexto de 1M tokens',
@@ -158,7 +158,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (formato XML)',
-    'Modo razonamiento',
+    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> o <code>minimal</code> lo apagan · de <code>low</code> a <code>max</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Multimodal (visión / imágenes)',
     'Generación en streaming (SSE)',
   ]}
@@ -182,7 +182,7 @@ OpenAI y la misma `base URL`.
   ]}
   items={[
     'Tool calling (formato XML)',
-    'Modo razonamiento',
+    'Control del razonamiento (<code>reasoning_effort</code>: <code>none</code> o <code>minimal</code> lo apagan · de <code>low</code> a <code>max</code>) · <a href="#controlar-el-razonamiento">detalles</a>',
     'Multimodal (visión / imágenes)',
     'Generación en streaming (SSE)',
   ]}
@@ -331,36 +331,130 @@ OpenAI y la misma `base URL`.
 
 ## Controlar el razonamiento.
 
-Todos los modelos de chat de arriba razonan antes de responder, y el
-razonamiento llega separado de la respuesta, en `message.reasoning_content`.
-Cuánto puede pensar cada modelo se elige por petición con el parámetro
-`reasoning_effort`, y cada modelo lo aplica distinto: la tabla es el contrato.
-Un valor que un modelo no puede aplicar nunca es un error.
+Todos los modelos de chat de arriba razonan antes de responder. El
+razonamiento llega separado de la respuesta: en `message.reasoning_content` en
+Chat Completions y como un elemento de salida `reasoning` en Responses. Lo
+controla un único parámetro, igual en todos los modelos:
 
-| Modelo | valores de `reasoning_effort` | Qué hace |
+| API | Parámetro |
+| --- | --- |
+| Chat Completions (`/v1/chat/completions`) | `reasoning_effort` |
+| Responses (`/v1/responses`) | `reasoning: {"effort": ...}` |
+
+Los valores, de sin razonamiento al más profundo: `none`, `minimal`, `low`,
+`medium`, `high`, `xhigh`, `max`.
+
+**Para apagar el razonamiento, envía `none`.** No hace falta nada más.
+Funciona en todos los modelos salvo GLM, que no puede dejar de razonar (ver la
+tabla).
+
+El código escrito para otro proveedor sigue funcionando: también aceptamos
+`thinking: {"type": "disabled"}`, `reasoning: {"enabled": false}`,
+`enable_thinking: false` y `chat_template_kwargs: {"enable_thinking": false}`,
+en el primer nivel del cuerpo o dentro de `extra_body`. Cada uno significa
+exactamente `none`. Si una petición lleva un valor y además uno de estos, gana
+el valor.
+
+| Modelo | Para apagar (`none`) | El resto de valores |
 | --- | --- | --- |
-| `glm5.3` · `glm5.3-flash` | `low`, `medium`, `high`, `max` | Control total. Valores más altos dejan que el modelo razone más antes de responder; `max` es el más profundo. |
-| `qwen3.6` | `none`, `minimal`, `low`, `medium`, `high`, `max` | `none` y `minimal` se saltan por completo la fase de razonamiento. Los otros cuatro la acotan: low 2.048, medium 8.192, high 16.384, max 32.768 tokens. |
-| `gemma4` | `none`, `minimal`, `low`, `medium`, `high`, `max` | Igual que `qwen3.6`: apagado, o un presupuesto de razonamiento entre 2.048 y 32.768 tokens. |
-| `deepseek-v4-flash` | cualquier valor (sin efecto) | El modelo decide por petición cuánto razona; el parámetro nunca cambia eso. |
-| `qwen3.8-flash` · `mimo-v2.6-flash` | aceptado, profundidad no ajustable | El parámetro se acepta y nunca se rechaza, pero estos modelos gestionan su propia profundidad de razonamiento. |
+| `deepseek-v4-flash` | Apagado. Sin tokens de razonamiento. | De `minimal` a `max` orientan cuánto razona. Son indicaciones que el modelo sigue, no topes estrictos. |
+| `qwen3.8-flash` | Apagado. Sin tokens de razonamiento. | El razonamiento está activado por defecto; de `minimal` a `max` orientan su profundidad (indicaciones, no topes). |
+| `mimo-v2.6-flash` | Apagado. Sin tokens de razonamiento. | `low`, `medium`, `high`, `max`. `minimal` se aplica como `low` y `xhigh` como `max`. |
+| `qwen3.6` · `gemma4` | Apagado. `minimal` también lo apaga. | En Chat Completions acotan la fase de razonamiento: `low` 2.048, `medium` 8.192, `high` 16.384, `xhigh` y `max` 32.768 tokens. En Responses solo hay encendido y apagado: cualquier valor que no sea `none` o `minimal` razona con el presupuesto por defecto de 16.384 tokens. |
+| `glm5.3` · `glm5.3-flash` | No es posible: GLM siempre razona. `none` se aplica como `minimal`, su razonamiento más corto (unos pocos tokens). | De `minimal` a `max`; los valores más altos razonan más antes de responder. |
 
-Sin parámetro, cada modelo usa su propio valor por defecto (razonamiento
-activo en `qwen3.6` y `gemma4`, con presupuesto de 16.384 tokens). Más
-razonamiento cuesta latencia y cuenta dentro de `max_tokens`; nunca cuesta
-configuración adicional.
+Sin parámetro, todos los modelos razonan (`qwen3.6` y `gemma4` con un
+presupuesto de 16.384 tokens). El razonamiento cuesta latencia y sus tokens
+cuentan dentro de `max_tokens`. Usa solo los valores de esta página.
+Cualquier otro valor se envía tal cual y queda fuera de este contrato: según el modelo,
+se rechaza con un `400` o se ignora.
 
 ```bash
 curl https://api.nan.builders/v1/chat/completions \
   -H "Authorization: Bearer $NAN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "glm5.3-flash",
-    "reasoning_effort": "low",
+    "model": "deepseek-v4-flash",
+    "reasoning_effort": "none",
     "messages": [{"role": "user", "content": "Write a one-line summary of the CAP theorem."}]
   }'
 ```
 
+En Helmcode, usa `https://api.helmcode.com/v1` como base URL; todo lo demás es idéntico.
+
+Con el SDK de OpenAI, en Chat Completions y en Responses:
+
+```python
+# pip install openai
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ["NAN_API_KEY"],
+    base_url="https://api.nan.builders/v1",  # Helmcode: https://api.helmcode.com/v1
+)
+
+chat = client.chat.completions.create(
+    model="deepseek-v4-flash",
+    reasoning_effort="none",
+    messages=[{"role": "user", "content": "Write a one-line summary of the CAP theorem."}],
+)
+print(chat.choices[0].message.content)
+
+resp = client.responses.create(
+    model="deepseek-v4-flash",
+    reasoning={"effort": "none"},
+    input="Write a one-line summary of the CAP theorem.",
+)
+print(resp.output_text)
+```
+
+Si tu versión del SDK de Python todavía no conoce el parámetro (lanza `TypeError: ... unexpected keyword argument`), envíalo dentro de `extra_body`; llega a la API exactamente igual:
+
+```python
+chat = client.chat.completions.create(
+    model="deepseek-v4-flash",
+    extra_body={"reasoning_effort": "none"},
+    messages=[{"role": "user", "content": "Write a one-line summary of the CAP theorem."}],
+)
+```
+
+En Node, con los mismos nombres que la API HTTP:
+
+```javascript
+// npm install openai
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  apiKey: process.env.NAN_API_KEY,
+  baseURL: 'https://api.nan.builders/v1', // Helmcode: https://api.helmcode.com/v1
+});
+
+const chat = await client.chat.completions.create({
+  model: 'deepseek-v4-flash',
+  reasoning_effort: 'none',
+  messages: [{ role: 'user', content: 'Write a one-line summary of the CAP theorem.' }],
+});
+console.log(chat.choices[0].message.content);
+
+const resp = await client.responses.create({
+  model: 'deepseek-v4-flash',
+  reasoning: { effort: 'none' },
+  input: 'Write a one-line summary of the CAP theorem.',
+});
+console.log(resp.output_text);
+```
+
+TypeScript: si tu versión del SDK tipa el parámetro como una unión a la que le falta un valor que envías (por ejemplo `max`), añade `// @ts-expect-error` en la línea de encima, o haz un cast del objeto de parámetros. La API acepta todos los valores de la tabla.
+
+```typescript
+const chat = await client.chat.completions.create({
+  model: 'deepseek-v4-flash',
+  reasoning_effort: 'max' as any, // older SDK types do not list 'max'
+  messages: [{ role: 'user', content: 'Write a one-line summary of the CAP theorem.' }],
+});
+```
+
 ## Límite de stream solo-razonamiento.
 
 Los prompts que exigen mucho razonamiento pueden dejar al modelo pensando
@@ -388,7 +482,7 @@ Dos cosas que conviene saber:
   cualquier tool call lo desarma por el resto del turno: las respuestas que
   escriben sobre la marcha nunca se cortan, por largas que sean.
 - Si un turno se cierra así, el modelo seguía planificando cuando tocó el
-  techo. Bajá `reasoning_effort` donde el modelo lo soporte (tabla de
+  techo. Baja `reasoning_effort` donde el modelo lo soporte (tabla de
   arriba), o reestructurá el prompt para que empiece a escribir temprano.
 
 El límite existe para acotar un modo de fallo conocido de los modelos con

src/content/docs/examples.md

@@ -78,7 +78,7 @@ Install: `npm install openai`
 
 ### structured output on deepseek-v4-flash
 
-`deepseek-v4-flash` rejects `response_format` `json_schema` with a `400`, and `json_object` only guarantees valid JSON, not its shape. To get output that follows a schema, define one function tool whose `parameters` is your JSON Schema (root `"type": "object"`, `"strict": true`) and force it with `tool_choice`. The model returns arguments that follow the schema in `choices[0].message.tool_calls[0].function.arguments`, as a JSON string. `strict` asks for an exact match; it is enforced where the model supports strict decoding, so validate the arguments if your code depends on them.
+On `api.nan.builders`, `deepseek-v4-flash` rejects `response_format` `json_schema` with a `400` (on `api.helmcode.com` it is accepted), and `json_object` only guarantees valid JSON, not its shape. To get output that follows a schema, define one function tool whose `parameters` is your JSON Schema (root `"type": "object"`, `"strict": true`) and force it with `tool_choice`. The model returns arguments that follow the schema in `choices[0].message.tool_calls[0].function.arguments`, as a JSON string. `strict` asks for an exact match; it is enforced where the model supports strict decoding, so validate the arguments if your code depends on them.
 
 ```bash
 curl https://api.nan.builders/v1/chat/completions \