@gtrabanco/pi-nan-provider 0.5.1 → 0.5.2

package/AGENTS.md

@@ -89,9 +89,21 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
 - Capability values that diverge from models.dev are recorded as build-time
   `MANUAL_OVERRIDES` (mandatory provenance note) in `scripts/manual-overrides.ts`,
   applied by `scripts/generate-models.ts` — never hand-edited into
-  `scripts/models.generated.ts` and never invented. e.g. qwen3.8-flash
-  contextWindow 1,000,000 (maintainer-confirmed 2026-09-05; models.dev and NaN
-  docs still listed 262,144 that day).
+  `scripts/models.generated.ts` and never invented. e.g. deepseek-v4-flash
+  image input (Vision-Exp variant; models.dev lists text only). Re-verify
+  overrides when the sources update: the qwen3.8-flash contextWindow 1,000,000
+  override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the
+  updated NaN docs still say 262K "the model's native window" and models.dev
+  agrees at 262,144.
+- NaN's official chat model list (https://nan.builders/openapi.json `model`
+  param description + https://nan.builders/docs/models, checked 2026-09-07):
+  community `deepseek-v4-flash`, `mimo-v2.5`, `qwen3.8-flash`, `glm5.3-flash`,
+  `qwen3.6`, `gemma4` (all text+image vision) + premium-tier `glm5.3`
+  (~753B MoE, text-only input, 1M context, 400M tokens/rolling 4h window).
+  `glm5.2` was removed by the provider (2026-09-05); models.dev may still list
+  it — the generator excludes it via `PROVIDER_REMOVED_MODEL_IDS`. Non-chat
+  endpoints: qwen3-embedding, rerank, kokoro (TTS), whisper (STT),
+  flux-2-klein (images) — MCP-bridge territory, not chat catalog models.
 - Relative imports inside this package use `.ts` extensions (pi's official
   extension examples do the same; pi transpiles extension sources).
 - pi intentionally has NO built-in MCP client (docs/usage.md). MCP integration

package/README.es.md

@@ -105,7 +105,7 @@ Variables de entorno:
 
 ## Modelos
 
-Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-04 — límites *servidos* por NaN, no máximos teóricos):
+Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-07 y corregido contra [los docs de NaN](https://nan.builders/docs/models) y [openapi.json](https://nan.builders/openapi.json) — límites *servidos* por NaN, no máximos teóricos):
 
 | Modelo | Contexto | Máx. salida | Entrada | Razonamiento |
 |---|---|---|---|---|
@@ -113,19 +113,18 @@ Catálogo base (de models.dev, proveedor `nan`, obtenido 2026-09-04 — límites
 | `gemma4` | 262,144 | 32,768 | texto, imagen | sí |
 | `deepseek-v4-flash` | 1,000,000 | 384,000 | texto, imagen | sí |
 | `mimo-v2.5` | 1,048,576 | 131,072 | texto, imagen | sí |
-| `glm5.2` | 500,000 | 131,072 | texto | sí |
 | `glm5.3-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
-| `qwen3.8-flash` | 1,000,000 | 131,072 | texto, imagen | sí |
+| `qwen3.8-flash` | 262,144 | 131,072 | texto, imagen | sí |
 
 Notas (grabadas por entrada en `scripts/models.generated.ts`):
 
-- La ventana de contexto de `qwen3.8-flash` está confirmada por el mantenedor en 1M (2026-09-05); models.dev y los docs de NaN aún listaban 262,144 en esa fecha. Este tipo de divergencias se registran como `MANUAL_OVERRIDES` en tiempo de build (con procedencia) en `scripts/manual-overrides.ts` — añade una ahí en vez de editar el fichero generado.
-
-- `deepseek-v4-flash` incluye entrada de imagen porque NaN sirve la variante Vision-Exp ([docs de NaN](https://nan.builders/docs/models)); models.dev la lista como solo texto.
+- `qwen3.8-flash` sirve 262K tokens, «la ventana nativa del modelo» ([docs de NaN](https://nan.builders/docs/models), 2026-09-07). Un override previo de 1M (confirmado por el mantenedor el 2026-09-05) se retiró cuando los docs actualizados siguieron diciendo 262K; models.dev coincide en 262,144. Este tipo de divergencias se registran como `MANUAL_OVERRIDES` en tiempo de build (con procedencia) en `scripts/manual-overrides.ts` — añade una ahí en vez de editar el fichero generado.
+- `deepseek-v4-flash` incluye entrada de imagen porque NaN sirve la variante Vision-Exp ([docs de NaN](https://nan.builders/docs/models), confirmado por los content-parts de visión en [openapi.json](https://nan.builders/openapi.json)); models.dev la lista como solo texto.
+- `glm5.2` fue eliminado por NaN (2026-09-05). models.dev aún lo listaba el 2026-09-07, así que el generador lo excluye vía `PROVIDER_REMOVED_MODEL_IDS` con la razón registrada — una regeneración no debe resucitar modelos retirados por el proveedor.
 - `mimo-v2.5` es omnimodal (texto/imagen/audio) en NaN, pero el tipo de modelo de pi solo representa entrada texto/imagen, así que el audio se omite en `input`.
 - NaN factura por cuota de membresía, que models.dev reporta como coste cero por token — el coste mostrado por pi será $0.
 - Compat (`supportsDeveloperRole: false`, `supportsReasoningEffort: true`, `supportsUsageInStreaming: true`, `maxTokensField: "max_tokens"`) coincide con la config LiteLLM probada en batalla que este paquete reemplaza; el ejemplo de los docs de NaN (`supportsDeveloperRole: true`) no está probado.
-- **Tier/cuota**: qué modelos puedes llamar lo decide tu membresía de NaN. Con clave, el fetch en vivo refleja exactamente eso (ver *Cómo funciona* — detección de tier). El GLM 5.3 de tier premium no está en el proveedor `nan` de models.dev; solo está `glm5.3-flash`.
+- **Tier/cuota**: qué modelos puedes llamar lo decide tu membresía de NaN. Con clave, el fetch en vivo refleja exactamente eso (ver *Cómo funciona* — detección de tier). El `glm5.3` de tier premium no está en el proveedor `nan` de models.dev y ninguna fuente documenta su límite de salida, así que no entra en el catálogo estático (marcado como no emitible en los metadatos); las claves premium lo reciben en vivo vía el refresh de `/models`, con límites conservadores (128K contexto / 4K salida). Solo está `glm5.3-flash` en el catálogo estático.
 
 ### Relación con `~/.pi/agent/models.json`
 

package/README.md

@@ -105,7 +105,7 @@ Environment variables:
 
 ## Models
 
-Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-04 — NaN's *served* limits, not raw model maxima):
+Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-07 and corrected against [NaN's docs](https://nan.builders/docs/models) and [openapi.json](https://nan.builders/openapi.json) — NaN's *served* limits, not raw model maxima):
 
 | Model | Context | Max output | Input | Reasoning |
 |---|---|---|---|---|
@@ -113,18 +113,18 @@ Baseline catalog (from models.dev, provider `nan`, fetched 2026-09-04 — NaN's
 | `gemma4` | 262,144 | 32,768 | text, image | yes |
 | `deepseek-v4-flash` | 1,000,000 | 384,000 | text, image | yes |
 | `mimo-v2.5` | 1,048,576 | 131,072 | text, image | yes |
-| `glm5.2` | 500,000 | 131,072 | text | yes |
 | `glm5.3-flash` | 1,000,000 | 131,072 | text, image | yes |
-| `qwen3.8-flash` | 1,000,000 | 131,072 | text, image | yes |
+| `qwen3.8-flash` | 262,144 | 131,072 | text, image | yes |
 
 Notes (recorded per entry in `scripts/models.generated.ts`):
 
-- `qwen3.8-flash` context window is maintainer-confirmed at 1M (2026-09-05); models.dev and NaN's docs still listed 262,144 at that date. Divergences like this are recorded as build-time `MANUAL_OVERRIDES` (with provenance) in `scripts/manual-overrides.ts` — apply one instead of editing the generated file.
-- `deepseek-v4-flash` includes image input because NaN serves the Vision-Exp variant ([NaN docs](https://nan.builders/docs/models)); models.dev lists text only.
+- `qwen3.8-flash` serves 262K tokens, "the model's native window" ([NaN docs](https://nan.builders/docs/models), 2026-09-07). An earlier 1M override (maintainer-confirmed 2026-09-05) was withdrawn once the updated docs still said 262K; models.dev agrees at 262,144. Divergences like this are recorded as build-time `MANUAL_OVERRIDES` (with provenance) in `scripts/manual-overrides.ts` — apply one instead of editing the generated file.
+- `deepseek-v4-flash` includes image input because NaN serves the Vision-Exp variant ([NaN docs](https://nan.builders/docs/models), confirmed by the vision content-parts in [openapi.json](https://nan.builders/openapi.json)); models.dev lists text only.
+- `glm5.2` was removed by NaN (2026-09-05). models.dev still listed it on 2026-09-07, so the generator excludes it via `PROVIDER_REMOVED_MODEL_IDS` with a recorded reason — a regeneration must not resurrect provider-removed models.
 - `mimo-v2.5` is omnimodal (text/image/audio) on NaN, but pi's model type only represents text/image input, so audio is dropped from `input`.
 - NaN bills via membership quota, which models.dev reports as zero per-token cost — pi's cost display will read $0.
 - Compat (`supportsDeveloperRole: false`, `supportsReasoningEffort: true`, `supportsUsageInStreaming: true`, `maxTokensField: "max_tokens"`) matches the battle-tested LiteLLM config this package replaces; NaN's docs example (`supportsDeveloperRole: true`) is not battle-tested.
-- **Tier/quota**: which models you can call is decided by your NaN membership. With a key, the live fetch reflects exactly that (see *How it works* — tier detection). The premium-tier GLM 5.3 is not in the models.dev `nan` provider at all; only `glm5.3-flash` is.
+- **Tier/quota**: which models you can call is decided by your NaN membership. With a key, the live fetch reflects exactly that (see *How it works* — tier detection). The premium-tier `glm5.3` is absent from the models.dev `nan` provider and no source documents its max output tokens, so it is not in the static catalog (flagged as unemittable in the catalog metadata); premium keys still get it live via the `/models` refresh with conservative placeholder limits (128K context / 4K output). Only `glm5.3-flash` is in the static catalog.
 
 ### Relationship to `~/.pi/agent/models.json`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",

package/scripts/generate-models.ts

@@ -37,9 +37,35 @@ const PI_SUPPORTED_INPUT = new Set(["text", "image"]);
  * Manual corrections over models.dev live in scripts/manual-overrides.ts
  * (shared with test/generated-catalog.test.ts, which pins that every
  * override lands on the generated entry with its provenance note).
- * Capabilities diverging from models.dev are recorded there, never here.
+ * Capability divergences from models.dev are recorded there, never here.
+ * MANUAL_NOTES adds provenance-only notes to otherwise-untouched entries.
  */
-const MANUAL_NOTES: Record<string, string> = {};
+const MANUAL_NOTES: Record<string, string> = {
+	"qwen3.8-flash":
+		"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07).",
+};
+
+/**
+ * Models the provider has removed but that models.dev may still list.
+ * Excluded at generation time with the recorded reason — a regeneration must
+ * never resurrect an entry the gateway no longer serves (this happened with
+ * glm5.2: hand-removed 2026-09-05, models.dev re-listed it by 2026-09-07).
+ */
+const PROVIDER_REMOVED_MODEL_IDS: Record<string, string> = {
+	"glm5.2":
+		"removed by NaN (2026-09-05); absent from the official chat model list in https://nan.builders/openapi.json and https://nan.builders/docs/models (checked 2026-09-07) while models.dev provider nan still listed it — excluded so regeneration does not resurrect it",
+};
+
+/**
+ * Models the provider documents and serves but that cannot be emitted yet:
+ * absent from models.dev, or missing a limit no source documents. Flagged in
+ * the catalog metadata instead of invented (no-fabrication rule); keys with
+ * access still receive them live via the /models refresh with conservative
+ * placeholder limits (UNKNOWN_MODEL_LIMITS).
+ */
+const KNOWN_UNEMITTABLE_MODEL_NOTES: readonly string[] = [
+	"glm5.3: served by NaN on the GLM 5.3 premium tier (https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-07) but absent from models.dev, and no source documents its max output tokens — no entry is generated (no-fabrication rule); premium keys still get it live via the /models refresh with conservative placeholder limits",
+];
 
 /**
  * LiteLLM compat confirmed against the live api.nan.builders gateway by the
@@ -113,6 +139,10 @@ function normalizeInput(modalitiesInput: string[] | undefined, modelId: string):
 }
 
 function convertModel(modelId: string, m: ModelsDevModel): GeneratedModel | { skip: string } {
+	const removedReason = PROVIDER_REMOVED_MODEL_IDS[modelId];
+	if (removedReason) {
+		return { skip: `provider-removed: "${modelId}" excluded from the catalog (${removedReason})` };
+	}
 	const contextWindow = m.limit?.context;
 	const maxTokens = m.limit?.output;
 	if (typeof contextWindow !== "number" || contextWindow <= 0) {
@@ -195,6 +225,7 @@ async function main(): Promise<void> {
 	const fetchedAt = new Date().toISOString();
 	const allNotes = [
 		...skipped,
+		...KNOWN_UNEMITTABLE_MODEL_NOTES,
 		...new Set(entries.flatMap((entry) => entry.notes ?? [])),
 	];
 

package/scripts/manual-overrides.ts

@@ -38,10 +38,6 @@ export interface ManualModelOverride {
 export const MANUAL_OVERRIDES: Record<string, ManualModelOverride> = {
 	"deepseek-v4-flash": {
 		input: ["text", "image"],
-		note: "input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
-	},
-	"qwen3.8-flash": {
-		contextWindow: 1_000_000,
-		note: "contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update.",
+		note: "input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only.",
 	},
 };

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-05T11:34:28.187Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-07T12:31:36.901Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -36,7 +36,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		},
 		"notes": [
 			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-			"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only."
+			"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only."
 		],
 		"extras": {
 			"id": "deepseek-v4-flash",
@@ -133,62 +133,6 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			}
 		}
 	},
-	{
-		"id": "glm5.2",
-		"name": "GLM-5.2",
-		"reasoning": true,
-		"input": [
-			"text"
-		],
-		"cost": {
-			"input": 0,
-			"output": 0,
-			"cacheRead": 0,
-			"cacheWrite": 0
-		},
-		"contextWindow": 500000,
-		"maxTokens": 131072,
-		"compat": {
-			"supportsDeveloperRole": false,
-			"supportsReasoningEffort": true,
-			"supportsUsageInStreaming": true,
-			"maxTokensField": "max_tokens"
-		},
-		"notes": [
-			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested."
-		],
-		"extras": {
-			"id": "glm5.2",
-			"name": "GLM-5.2",
-			"description": "Open flagship GLM for long-horizon coding agents, served at 500K context on the NaN premium tier",
-			"family": "glm",
-			"attachment": false,
-			"reasoning": true,
-			"reasoning_options": [],
-			"tool_call": true,
-			"structured_output": true,
-			"temperature": true,
-			"release_date": "2026-06-13",
-			"last_updated": "2026-06-13",
-			"modalities": {
-				"input": [
-					"text"
-				],
-				"output": [
-					"text"
-				]
-			},
-			"open_weights": true,
-			"limit": {
-				"context": 500000,
-				"output": 131072
-			},
-			"cost": {
-				"input": 0,
-				"output": 0
-			}
-		}
-	},
 	{
 		"id": "glm5.3-flash",
 		"name": "GLM-5.3-Flash",
@@ -382,7 +326,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 			"cacheRead": 0,
 			"cacheWrite": 0
 		},
-		"contextWindow": 1000000,
+		"contextWindow": 262144,
 		"maxTokens": 131072,
 		"compat": {
 			"supportsDeveloperRole": false,
@@ -392,7 +336,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 		},
 		"notes": [
 			"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-			"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
+			"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 		],
 		"extras": {
 			"id": "qwen3.8-flash",
@@ -431,12 +375,14 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-05T11:34:28.187Z",
-	modelCount: 7,
-	models: ["deepseek-v4-flash","gemma4","glm5.2","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
+	fetchedAt: "2026-09-07T12:31:36.901Z",
+	modelCount: 6,
+	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [
+	"provider-removed: \"glm5.2\" excluded from the catalog (removed by NaN (2026-09-05); absent from the official chat model list in https://nan.builders/openapi.json and https://nan.builders/docs/models (checked 2026-09-07) while models.dev provider nan still listed it — excluded so regeneration does not resurrect it)",
+	"glm5.3: served by NaN on the GLM 5.3 premium tier (https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-07) but absent from models.dev, and no source documents its max output tokens — no entry is generated (no-fabrication rule); premium keys still get it live via the /models refresh with conservative placeholder limits",
 	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, supportsUsageInStreaming true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested.",
-	"input includes image: NaN serves the Vision-Exp variant (confirmed at https://nan.builders/docs/models, 'takes images as input'); models.dev provider nan lists text only.",
-	"contextWindow 1,000,000: maintainer-confirmed against api.nan.builders (2026-09-05); both models.dev and https://nan.builders/docs/models still listed 262,144 ('262K token context, the model's native window') as of 2026-09-05 — re-verify against the gateway/docs when they update."
+	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models, checked 2026-09-07; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models); models.dev provider nan lists text only.",
+	"contextWindow 262,144: the earlier 1,000,000 override (maintainer-confirmed 2026-09-05) was withdrawn 2026-09-07 — the updated https://nan.builders/docs/models still states '262K token context, the model's native window' and models.dev agrees at 262,144; NaN docs are treated as the most reliable source (maintainer instruction, 2026-09-07)."
 ],
 } as const;