@gtrabanco/pi-nan-provider 0.10.2 → 0.10.3

package/AGENTS.md

@@ -198,9 +198,16 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
   entry) so the id is never emitted twice.
   Non-chat endpoints: qwen3-embedding, rerank, kokoro (TTS), whisper (STT),
   flux-2-klein and qwen-image-2.1 (images) — MCP-bridge territory, not chat
-  catalog models; `qwen-image-2.1` also sits on models.dev with
-  `limit.output: 0`, so generation excludes it via `NON_CHAT_MODEL_IDS`
-  instead of flagging it "needs manual verification" forever.
+  catalog models. The classification is now applied at RUNTIME too:
+  `NON_CHAT_MODEL_IDS` is exported from `src/fetch-models.ts` (single source
+  of truth: id → provenance reason), imported by `scripts/generate-models.ts`
+  (one definition, no duplicate), enforced by `mergeLiveWithGenerated` (those
+  ids land in the `nonChat` bucket and never enter the registry), and filtered
+  defensively by `baselineModels`. The generator excluded `qwen-image-2.1` via
+  this constant before (it also sits on models.dev with `limit.output: 0`,
+  excluded instead of being flagged "needs manual verification" forever); all
+  six ids are now under the same guard so they can never be emitted as chat
+  models or registered at runtime.
 - NaN can close an SSE stream **before** `finish_reason`. The catalog sets
   `supportsFinishReason: true` so pi-ai raises the retryable
   `Stream ended without finish_reason` (pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN`

package/README.es.md

@@ -41,6 +41,8 @@ El proveedor utiliza un **catálogo de modelos de dos capas** para garantizar la
 > [!IMPORTANT]
 > **Detección de Tier**: La lista en vivo es la autoridad. Si tu clave tiene acceso premium, esos modelos aparecerán automáticamente; de lo contrario, se filtran.
 
+Los ids no-chat que devuelve `/models` en vivo (embedding, rerank, TTS, STT, imagen) **no se registran** como modelos de chat — la clasificación es el único `NON_CHAT_MODEL_IDS` exportado desde `src/fetch-models.ts` (la misma fuente que usa el generador en build-time). La fusión salta sus marcadores y los coloca en un bucket observable `nonChat`; `baselineModels` también los filtra como capa defensiva. Esto evita que el selector de chat de pi ofrezca endpoints que no pueden servir chat (las peticiones devolverían 404).
+
 El registro es síncrono a propósito: el catálogo de fallback está disponible al instante, y el runtime de Models de pi dirige el refresco en vivo (refresco de red en el arranque interactivo y periódico, solo caché en el registro), persistiendo el overlay entre ejecuciones.
 
 ### 🧠 Seguridad al cambiar de modelo (guard de razonamiento cross-model)

package/README.md

@@ -41,6 +41,8 @@ The provider uses a **two-layer model catalog** to ensure reliability:
 > [!IMPORTANT]
 > **Tier Detection**: The live list is authoritative. If your key has premium access, those models will appear automatically; otherwise, they are filtered out.
 
+NaN's live `/models` also returns non-chat endpoint ids (embedding, rerank, TTS, STT, image). These are **not registered** as chat models — the classification is the single exported `NON_CHAT_MODEL_IDS` from `src/fetch-models.ts` (the same source used by the build-time generator). The merge skips their placeholders and places them in an observable `nonChat` bucket; `baselineModels` also filters them defensively. This prevents pi's chat picker from offering endpoints that cannot serve chat (requests would 404).
+
 The registration is synchronous on purpose: the generated fallback catalog is available immediately, and pi's Models runtime drives the live refresh (network refresh at interactive startup and periodically, cache-only at registration), persisting the overlay between runs.
 
 ### 🧠 Model-switch safety (cross-model reasoning guard)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.10.2",
+	"version": "0.10.3",
 	"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

@@ -25,7 +25,8 @@
  *   MANUAL_ONLY entry — or this script exits non-zero.
  * - Any other models.dev entry missing `limit.context`/`limit.output` is
  *   skipped and flagged "needs manual verification" — never guessed. Entries
- *   that are not chat models are excluded via NON_CHAT_MODEL_IDS instead.
+ *   that are not chat models are excluded via NON_CHAT_MODEL_IDS instead
+ *   (defined in `src/fetch-models.ts` and also enforced at runtime).
  * - models.dev modalities are intersected with pi's supported input set
  *   ("text" | "image"); e.g. mimo-v2.6-flash's audio input is not
  *   representable in pi's Model type and is dropped from `input` (noted on
@@ -33,6 +34,7 @@
  */
 
 import type { GeneratedModelEntry } from "../src/fetch-models.ts";
+import { NON_CHAT_MODEL_IDS } from "../src/fetch-models.ts";
 import type { ManualModelOverride } from "./manual-overrides.ts";
 import {
 	MANUAL_OVERRIDES,
@@ -97,17 +99,10 @@ const PROVIDER_REMOVED_MODEL_IDS: Record<string, string> = {
 		"removed by NaN (checked 2026-09-29): zero mentions in https://nan.builders/docs/models and in the model param description of https://nan.builders/openapi.json, and models.dev provider nan dropped it as well — superseded by mimo-v2.6-flash; excluded so regeneration does not resurrect it",
 };
 
-/**
- * models.dev entries that are not chat models. They can never join a chat
- * catalog (their output is an image, and models.dev reports limit.output 0),
- * so they are excluded with the docs as the reason instead of being flagged
- * "needs manual verification" forever — that flag would suggest limits worth
- * confirming for a model this package must not serve as chat.
- */
-const NON_CHAT_MODEL_IDS: Record<string, string> = {
-	"qwen-image-2.1":
-		"image-generation model (text→image; output modality image) documented in https://nan.builders/docs/models and https://nan.builders/openapi.json (checked 2026-09-29) — not a chat model, out of the static chat catalog (models.dev reports limit.output 0)",
-};
+// NON_CHAT_MODEL_IDS (six non-chat endpoint ids) is imported from its single
+// source of truth, `src/fetch-models.ts`, where the runtime live merge applies
+// the same classification. Here it feeds convertModel's exclusion and the
+// exclusion-note list in GENERATED_CATALOG_META.notes.
 
 /**
  * Premium/tier-gated models that models.dev documents but that are deliberately
@@ -346,6 +341,14 @@ async function main(): Promise<void> {
 	// so the manual data never disappears silently.
 	const entryById = new Map(entries.map((entry) => [entry.id, entry]));
 	for (const [modelId, detail] of Object.entries(MANUAL_ONLY_MODEL_IDS)) {
+		// Guard: a MANUAL_ONLY_MODEL_IDS entry must not be a non-chat id.
+		// (REQUIRED_MODEL_IDS can't land here: if a required id were non-chat,
+		// convertModel skips it and the existing missing-required fail already
+		// fires — but this guard is explicit for MANUAL_ONLY.)
+		const nonChatReason = NON_CHAT_MODEL_IDS[modelId];
+		if (nonChatReason) {
+			fail(`MANUAL_ONLY_MODEL_IDS id "${modelId}" is classified as non-chat (${nonChatReason}) — this is a contradictory repo configuration`);
+		}
 		const existing = entryById.get(modelId);
 		if (existing) {
 			const note = `manual-only: "${modelId}" skipped: models.dev provider "${SOURCE_PROVIDER_ID}" now lists it, so the manual-only entry is not emitted and the models.dev values are used (${detail})`;

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-10-01T10:18:48.654Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-01T10:56:14.717Z
 // 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.
@@ -455,7 +455,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-10-01T10:18:48.654Z",
+	fetchedAt: "2026-10-01T10:56:14.717Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [
@@ -463,6 +463,11 @@ export const GENERATED_CATALOG_META = {
 	"live-only: \"glm5.3\" kept out of the static catalog (premium-tier model (models.dev now documents it with 1M context / 131,072 max output; NaN docs https://nan.builders/docs/models + https://nan.builders/openapi.json, checked 2026-09-13) kept live-only so a non-premium key never sees a model it cannot call when the live /models fetch is unavailable; premium keys still get it via the /models refresh with conservative placeholder limits)",
 	"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)",
 	"provider-removed: \"mimo-v2.5\" excluded from the catalog (removed by NaN (checked 2026-09-29): zero mentions in https://nan.builders/docs/models and in the model param description of https://nan.builders/openapi.json, and models.dev provider nan dropped it as well — superseded by mimo-v2.6-flash; excluded so regeneration does not resurrect it)",
+	"non-chat: \"qwen3-embedding\" excluded from the chat catalog (embedding endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"rerank\" excluded from the chat catalog (rerank endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"kokoro\" excluded from the chat catalog (text-to-speech (TTS) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"whisper\" excluded from the chat catalog (speech-to-text (STT) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
+	"non-chat: \"flux-2-klein\" excluded from the chat catalog (image generation endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model)",
 	"compat matches the maintainer's working ~/.pi/agent/models.json LiteLLM config for api.nan.builders (2026-09-04): supportsDeveloperRole false, supportsReasoningEffort true, maxTokensField max_tokens. NaN's docs example sets only supportsDeveloperRole: true and is not battle-tested. supportsFinishReason true (2026-09-13, issue #2): the LiteLLM gateway intermittently closes SSE streams before emitting finish_reason; with true pi-ai raises 'Stream ended without finish_reason', which matches pi-ai's retryable-provider pattern ('ended without') and is retried automatically, whereas false silently synthesized stop/toolUse and stalled the turn mid-answer. supportsUsageInStreaming true (2026-09-16, issue #7): NaN's published schema is silent about stream_options, but the live gateway honors it — two identical streaming calls per model, differing only in stream_options: { include_usage: true }, returned 0 usage chunks without it and exactly 1 with it (prompt/completion/reasoning/cached token counts) on deepseek-v4-flash, glm5.3-flash, qwen3.6, mimo-v2.5 and gemma4, and a real pi session then recorded token counts where it recorded zeros. pi-ai only sends stream_options when this is not false, and the sanitizer forwards it when the model declares true, so chat models opt in by default and usage is reported (issue #4). A model that does not report streaming usage can still opt out per model with a models.json compat override (supportsUsageInStreaming: false); the sanitizer then strips stream_options and the payload stays strict.",
 	"input includes image: NaN serves the Vision-Exp variant ('takes images as input', https://nan.builders/docs/models; the image_url content-parts in https://nan.builders/openapi.json list deepseek-v4-flash among the vision models). models.dev provider nan also lists text+image now (DeepSeek V4.1 Flash entry, checked 2026-09-13; its 2026-09-07 snapshot listed text only), so this override is kept as a pin for the vision capability rather than as a divergence. reasoning_effort_values=[\"none\"] (issue #16, measured 2026-09-27 against live gateway, repro included in the issue): only \"none\" deterministically disables reasoning (0 reasoning tokens, answer produced). Every other value leaves 13-14K reasoning tokens and causes runaway reasoning (finish_reason:\"length\" with ZERO answer text). The catalog declares only [\"none\"] because the remaining values are useless noise. thinkingLevelMap { off: \"none\" } (issue #16, measured 2026-09-27): when pi maps reasoning:\"off\" to reasoningEffort:undefined, the thinkingLevelMap.off=\"none\" supplies the effort so the gateway receives reasoning_effort:\"none\" and does NOT enter runaway reasoning mode.",
 	"thinkingLevelMap { off: \"none\" } (issue #16): NaN docs state that with no reasoning_effort parameter gemma4 defaults to reasoning ON (16,384-token budget), while `none`/`minimal` skip reasoning entirely (https://nan.builders/docs/models#controlling-reasoning, checked 2026-10-01). pi maps reasoning:\"off\" to reasoningEffort:undefined, so without this map `thinking: off` sent no parameter and the model reasoned anyway; the map sends reasoning_effort:\"none\" and actually disables reasoning.",

package/src/fetch-models.ts

@@ -12,13 +12,15 @@
  *     only model `id`s — no capability fields. It is used as the authoritative
  *     list of what the endpoint returns for the API key.
  *
- * Merge: live IDs × generated capability data — all live IDs surface:
- * a live ID with generated data keeps its generated capabilities, and an
- * uncatalogued live ID (e.g. a new or undocumented model) gets conservative
- * placeholder limits (the same defaults used in custom-provider.md's
- * dynamic-discovery example) with no reasoning support — capabilities stay
- * "unknown", nothing is fabricated. On fetch failure, timeout, or an unusable
- * response, callers fall back to the generated catalog so startup is never blocked.
+ * Merge: live IDs × generated capability data — non-chat IDs (see
+ * `NON_CHAT_MODEL_IDS`) are excluded from the registered model set and
+ * reported in `MergedCatalog.nonChat`; all other live IDs surface: a live ID
+ * with generated data keeps its generated capabilities, and an uncatalogued
+ * live ID (e.g. a new or undocumented model) gets conservative placeholder
+ * limits (the same defaults used in custom-provider.md's dynamic-discovery
+ * example) with no reasoning support — capabilities stay "unknown", nothing is
+ * fabricated. On fetch failure, timeout, or an unusable response, callers fall
+ * back to the generated catalog so startup is never blocked.
  */
 
 import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
@@ -81,6 +83,32 @@ export const UNKNOWN_MODEL_LIMITS = { contextWindow: 128_000, maxTokens: 4_096 }
 /** Timeout for the live /models fetch; matches the pi-synthetic-provider precedent (~3s). */
 export const DEFAULT_MODELS_TIMEOUT_MS = 3_000;
 
+/**
+ * Live endpoint IDs classified as non-chat and excluded from the registered
+ * model set. Keys are model ids; values are provenance reasons citing the
+ * source that designated the endpoint as non-chat.
+ *
+ * Source: https://nan.builders/docs/models (checked 2026-10-01), plus
+ * qwen-image-2.1: https://models.dev API `limit.output: 0` (checked 2026-09-29).
+ * These are MCP-bridge territory (embedding / rerank / TTS / STT / image
+ * generation), not chat catalog models — see AGENTS.md classification notes
+ * and issue #15.
+ */
+export const NON_CHAT_MODEL_IDS: Readonly<Record<string, string>> = {
+	"qwen3-embedding":
+		"embedding endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	rerank:
+		"rerank endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	kokoro:
+		"text-to-speech (TTS) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	whisper:
+		"speech-to-text (STT) endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	"flux-2-klein":
+		"image generation endpoint (https://nan.builders/docs/models, checked 2026-10-01) — not a chat model",
+	"qwen-image-2.1":
+		"image-generation model (text→image; output modality image) documented in https://nan.builders/docs/models and https://nan.builders/openapi.json (checked 2026-09-29) — not a chat model, out of the static chat catalog (models.dev reports limit.output 0)",
+} as const;
+
 export interface CatalogSource {
 	/** Provider id as registered in pi, e.g. "nan". */
 	providerId: string;
@@ -108,7 +136,11 @@ export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Mode
 
 /** The generated fallback catalog as pi-ai Models for the given provider. */
 export function baselineModels(source: CatalogSource): Model<"openai-completions">[] {
-	return NAN_GENERATED_MODELS.map((entry) => toModel(entry, source));
+	// Defensive: the generated baseline never contains non-chat ids today,
+	// but the invariant must hold on every path (issue #15).
+	return NAN_GENERATED_MODELS.filter(
+		(entry) => !NON_CHAT_MODEL_IDS[entry.id],
+	).map((entry) => toModel(entry, source));
 }
 
 export interface LiveModelListOptions {
@@ -163,12 +195,18 @@ export interface MergedCatalog {
 	matched: string[];
 	/** Allowlisted live IDs kept with unknown capabilities (conservative limits). */
 	unknown: string[];
+	/**
+	 * Live model IDs classified as non-chat and excluded from the registered
+	 * model set, in live order. Populated from `NON_CHAT_MODEL_IDS` (issue #15).
+	 */
+	nonChat: string[];
 }
 
 /**
- * Merge live model IDs with the generated capability catalog. All live IDs
- * surface: live IDs with generated data keep their generated capabilities;
- * uncatalogued live IDs get conservative placeholder limits,
+ * Merge live model IDs with the generated capability catalog. Non-chat IDs
+ * (from `NON_CHAT_MODEL_IDS`) are excluded and reported in `nonChat`; all
+ * other live IDs surface: live IDs with generated data keep their generated
+ * capabilities; uncatalogued live IDs get conservative placeholder limits,
  * `reasoning: false`, and zero cost (documented defaults, not invented
  * capabilities).
  */
@@ -181,8 +219,15 @@ export function mergeLiveWithGenerated(
 	const models: Model<"openai-completions">[] = [];
 	const matched: string[] = [];
 	const unknown: string[] = [];
+	const nonChat: string[] = [];
 
 	for (const id of liveIds) {
+		// Issue #15: non-chat endpoint ids must never surface as chat models.
+		const nonChatReason = NON_CHAT_MODEL_IDS[id];
+		if (nonChatReason) {
+			nonChat.push(id);
+			continue;
+		}
 		const entry = byId.get(id);
 		if (entry) {
 			models.push(toModel(entry, source));
@@ -217,7 +262,7 @@ export function mergeLiveWithGenerated(
 		}
 	}
 
-	return { models, matched, unknown };
+	return { models, matched, unknown, nonChat };
 }
 
 export interface FetchModelsOptions {
@@ -240,13 +285,19 @@ export interface ResolvedCatalog {
 	liveIds: Set<string> | undefined;
 	/** Allowlisted live IDs kept with unknown capabilities (present only when liveIds is set). */
 	unknownIds: string[];
+	/**
+	 * Live model IDs classified as non-chat and excluded from the registered
+	 * model set (issue #15). Empty when the live fetch failed.
+	 */
+	nonChatIds: string[];
 }
 
 /**
  * Resolve the effective catalog: live `/models` IDs × generated capability
  * data. A successful live fetch is authoritative (tier-aware: it reflects
  * exactly what your NaN key can use); failure degrades to the generated
- * fallback so startup is never blocked.
+ * fallback so startup is never blocked. Non-chat IDs are excluded from
+ * models and reported in `nonChatIds` (issue #15).
  */
 export async function resolveCatalog(
 	source: CatalogSource,
@@ -260,11 +311,16 @@ export async function resolveCatalog(
 			timeoutMs: options.timeoutMs,
 			fetchImpl: options.fetchImpl,
 		});
-		if (!liveIds) return { models: baseline, liveIds: undefined, unknownIds: [] };
+		if (!liveIds) return { models: baseline, liveIds: undefined, unknownIds: [], nonChatIds: [] };
 		const merged = mergeLiveWithGenerated(liveIds, source);
-		return { models: merged.models, liveIds: new Set(liveIds), unknownIds: merged.unknown };
+		return {
+			models: merged.models,
+			liveIds: new Set(liveIds),
+			unknownIds: merged.unknown,
+			nonChatIds: merged.nonChat,
+		};
 	} catch {
-		return { models: baseline, liveIds: undefined, unknownIds: [] };
+		return { models: baseline, liveIds: undefined, unknownIds: [], nonChatIds: [] };
 	}
 }