@ai-for-dev/providers 0.1.0 → 0.3.0

package/README.md

@@ -31,12 +31,26 @@ Vous pouvez aussi fournir la clé par variable d'environnement : `ILAAS_API_KEY`
 
 `extensions/index.ts` contient, pour chaque serveur, une table des modèles connus : taille du contexte, sortie maximale, lecture d'images et gestion du raisonnement. Ces valeurs ont été mesurées sur les serveurs. Le raisonnement peut être :
 
-- activable (`toggle`) : Pi propose `off` et `high`, et passe par `chat_template_kwargs.enable_thinking` ;
+- réglable par niveau : Pi propose `off`, `low`, `medium` et `high`, et envoie `enable_thinking` et `reasoning_effort` dans `chat_template_kwargs`. La table donne la valeur à envoyer pour chaque niveau, car chaque modèle a son vocabulaire (`xhigh` pour Qwen 3.8, `max` pour DeepSeek V4.1) ;
+- activable (`toggle`) : le modèle ne sait que réfléchir ou non. Pi propose `off` et `high`, et passe par `chat_template_kwargs.enable_thinking` ;
 - permanent (`always`) : Pi ne propose que `high` ;
 - absent (`none`) : Pi n'envoie aucun paramètre de raisonnement.
 
+Seuls `qwen-3.8-27b` et `ARES/DeepSeek-V4.1-Flash` lisent un niveau d'effort dans leur modèle de chat. Ceux de Qwen 3.6 et de Gemma 4 ne connaissent que `enable_thinking`.
+
 Un modèle marqué `hidden: true` n'apparaît pas, même si le serveur le liste. Un modèle qui n'est pas dans la table reste utilisable. Il prend la taille de contexte donnée par le serveur (128 000 tokens à défaut), 32 768 tokens de sortie, sans images ni raisonnement.
 
+## Exporter un `models.json`
+
+Certains outils lisent un `models.json` mais ne chargent pas d'extension. C'est le cas de trysquare, qui lance pi sans extension et relaie la clé lui-même. Pour eux, le paquet écrit ses deux fournisseurs au format de `~/.pi/agent/models.json` :
+
+```bash
+npm ci
+npm run export-models -- chemin/vers/models.json   # sans chemin, le fichier sort sur stdout
+```
+
+L'export lit seulement la table de `extensions/index.ts`, sans appeler les serveurs : une même version du paquet écrit toujours le même fichier. Les modèles marqués `hidden` sont exclus, et un modèle sans `contextWindow` dans la table fait échouer l'export. Les clés restent des références (`$ILAAS_API_KEY`, `$IA4DEV_API_KEY`) que pi lit dans l'environnement. `IA4DEV_ILAAS_BASE_URL` et `IA4DEV_GRICAD_BASE_URL` changent l'URL écrite, comme pour l'extension.
+
 ## Limites
 
 - Un fournisseur déjà défini sous le même nom dans `~/.pi/agent/models.json` prend le dessus sur celui du paquet.

package/extensions/index.ts

@@ -13,11 +13,19 @@ type ChatModel = Model<"openai-completions">;
 
 /**
  * How a model handles reasoning, measured against the real servers:
- * - "toggle": off by default, switched on with chat_template_kwargs.enable_thinking (vLLM).
+ * - "toggle": chat_template_kwargs.enable_thinking switches reasoning on and off, nothing finer.
  * - "always": always reasons and ignores every switch.
  * - "none": no reasoning; any reasoning parameter makes the server fail.
+ * - Efforts: the chat template also reads a reasoning_effort, given here as the value
+ *   to send for each of Pi's low, medium and high levels.
  */
-type Thinking = "toggle" | "always" | "none";
+type Thinking = "toggle" | "always" | "none" | Efforts;
+
+interface Efforts {
+	low: string;
+	medium: string;
+	high: string;
+}
 
 interface ModelTuning {
 	contextWindow?: number;
@@ -28,7 +36,7 @@ interface ModelTuning {
 	hidden?: boolean;
 }
 
-interface Endpoint {
+export interface Endpoint {
 	id: string;
 	name: string;
 	baseUrl: string;
@@ -36,7 +44,7 @@ interface Endpoint {
 	models: Record<string, ModelTuning>;
 }
 
-const ENDPOINTS: Endpoint[] = [
+export const ENDPOINTS: Endpoint[] = [
 	{
 		id: "ia4dev-ilaas",
 		name: "ILAAS",
@@ -61,9 +69,11 @@ const ENDPOINTS: Endpoint[] = [
 		baseUrl: "https://ia4dev-owui.univ-grenoble-alpes.fr/api",
 		envVar: "IA4DEV_API_KEY",
 		models: {
-			"qwen-3.8-27b": { vision: true, thinking: "toggle" },
-			"ARES/DeepSeek-V4.1-Flash": { vision: true, thinking: "toggle" },
-			"gemma-4-31b": { vision: true, thinking: "toggle" },
+			// The chat template accepts low, medium and xhigh (its default).
+			"qwen-3.8-27b": { contextWindow: 262_144, vision: true, thinking: { low: "low", medium: "medium", high: "xhigh" } },
+			// The deployed chat template accepts low, high (its default) and max, but not medium.
+			"ARES/DeepSeek-V4.1-Flash": { contextWindow: 1_048_576, vision: true, thinking: { low: "low", medium: "high", high: "max" } },
+			"gemma-4-31b": { contextWindow: 159_488, vision: true, thinking: "toggle" },
 		},
 	},
 ];
@@ -72,11 +82,34 @@ const DEFAULT_CONTEXT_WINDOW = 128_000;
 const DEFAULT_MAX_TOKENS = 32_768;
 const FETCH_TIMEOUT_MS = 10_000;
 
-// Effort levels mean nothing to these servers: reasoning is either on or off.
-const THINKING_LEVELS: Record<Exclude<Thinking, "none">, ChatModel["thinkingLevelMap"]> = {
-	toggle: { minimal: null, low: null, medium: null },
-	always: { off: null, minimal: null, low: null, medium: null },
-};
+type Reasoning = Pick<ChatModel, "reasoning" | "thinkingLevelMap"> & { compat: ChatModel["compat"] };
+
+// Pi's levels without a counterpart on the server are mapped to null, which hides them.
+function reasoningFor(thinking: Thinking): Reasoning {
+	if (thinking === "none") return { reasoning: false, compat: {} };
+	if (thinking === "always") {
+		return { reasoning: true, thinkingLevelMap: { off: null, minimal: null, low: null, medium: null }, compat: {} };
+	}
+	if (thinking === "toggle") {
+		return {
+			reasoning: true,
+			thinkingLevelMap: { minimal: null, low: null, medium: null },
+			compat: { thinkingFormat: "qwen-chat-template" },
+		};
+	}
+	return {
+		reasoning: true,
+		thinkingLevelMap: { minimal: null, ...thinking },
+		compat: {
+			thinkingFormat: "chat-template",
+			chatTemplateKwargs: {
+				enable_thinking: { $var: "thinking.enabled" },
+				preserve_thinking: true,
+				reasoning_effort: { $var: "thinking.effort", omitWhenOff: true },
+			},
+		},
+	};
+}
 
 interface RemoteModel {
 	id: string;
@@ -88,9 +121,9 @@ interface RemoteModel {
 	max_output_tokens?: number;
 }
 
-function toModel(endpoint: Endpoint, remote: RemoteModel): ChatModel {
+export function toModel(endpoint: Endpoint, remote: RemoteModel): ChatModel {
 	const tuning = endpoint.models[remote.id] ?? {};
-	const thinking = tuning.thinking ?? "none";
+	const reasoning = reasoningFor(tuning.thinking ?? "none");
 	const contextWindow =
 		tuning.contextWindow ?? remote.max_model_len ?? remote.max_input_tokens ?? DEFAULT_CONTEXT_WINDOW;
 	const maxTokens = tuning.maxTokens ?? remote.max_output_tokens ?? DEFAULT_MAX_TOKENS;
@@ -101,8 +134,8 @@ function toModel(endpoint: Endpoint, remote: RemoteModel): ChatModel {
 		provider: endpoint.id,
 		baseUrl: endpoint.baseUrl,
 		input: tuning.vision ? ["text", "image"] : ["text"],
-		reasoning: thinking !== "none",
-		thinkingLevelMap: thinking === "none" ? undefined : THINKING_LEVELS[thinking],
+		reasoning: reasoning.reasoning,
+		thinkingLevelMap: reasoning.thinkingLevelMap,
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 		contextWindow,
 		maxTokens: Math.min(maxTokens, contextWindow),
@@ -110,9 +143,10 @@ function toModel(endpoint: Endpoint, remote: RemoteModel): ChatModel {
 			// These gateways reject the newer OpenAI-only fields.
 			supportsDeveloperRole: false,
 			supportsStore: false,
-			// reasoning_effort is ignored by vLLM chat templates and crashes the Mistral models.
+			// A top-level reasoning_effort is ignored by vLLM chat templates and crashes the
+			// Mistral models; models that read an effort get it through the chat template.
 			supportsReasoningEffort: false,
-			...(thinking === "toggle" ? { thinkingFormat: "qwen-chat-template" as const } : {}),
+			...reasoning.compat,
 		},
 	};
 }
@@ -135,11 +169,47 @@ async function fetchModels(endpoint: Endpoint, context: RefreshModelsContext): P
 		.map((m) => toModel(endpoint, m));
 }
 
+// <ID>_BASE_URL (ex: IA4DEV_ILAAS_BASE_URL) remplace l'URL par défaut, pour tester ou changer de serveur.
+function withBaseUrl(base: Endpoint): Endpoint {
+	const urlVar = `${base.id.toUpperCase().replaceAll("-", "_")}_BASE_URL`;
+	return { ...base, baseUrl: process.env[urlVar] ?? base.baseUrl };
+}
+
+/**
+ * The same providers as a pi models.json, for tools that read that file but load no
+ * extension, such as trysquare. Built from the table alone: no server is asked, so a
+ * given version of this package always writes the same file. The key stays a `$VAR`
+ * reference that pi resolves from the environment.
+ */
+export function modelsJson(endpoints: Endpoint[] = ENDPOINTS) {
+	const providers: Record<string, unknown> = {};
+	for (const base of endpoints) {
+		const endpoint = withBaseUrl(base);
+		const models = Object.entries(endpoint.models)
+			.filter(([, tuning]) => !tuning.hidden)
+			.map(([id, tuning]) => {
+				// Without a server to ask, the default would pass for a measured value.
+				if (tuning.contextWindow === undefined) {
+					throw new Error(`${endpoint.name}: ${id} has no contextWindow in the table`);
+				}
+				// The provider entry already says these three.
+				const { provider, api, baseUrl, ...model } = toModel(endpoint, { id });
+				return model;
+			});
+		providers[endpoint.id] = {
+			name: endpoint.name,
+			baseUrl: endpoint.baseUrl,
+			api: "openai-completions",
+			apiKey: `$${endpoint.envVar}`,
+			models,
+		};
+	}
+	return { providers };
+}
+
 export default function (pi: ExtensionAPI) {
 	for (const base of ENDPOINTS) {
-		// <ID>_BASE_URL (ex: IA4DEV_ILAAS_BASE_URL) remplace l'URL par défaut, pour tester ou changer de serveur.
-		const urlVar = `${base.id.toUpperCase().replaceAll("-", "_")}_BASE_URL`;
-		const endpoint = { ...base, baseUrl: process.env[urlVar] ?? base.baseUrl };
+		const endpoint = withBaseUrl(base);
 		pi.registerProvider(
 			createProvider<"openai-completions">({
 				id: endpoint.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-for-dev/providers",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Pi providers for the AI4Dev course models (ILAAS and IA4Dev)",
   "keywords": [
     "pi",
@@ -30,7 +30,8 @@
   },
   "scripts": {
     "test": "node --test 'test/*.test.ts'",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "export-models": "node scripts/export-models.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -44,6 +45,7 @@
     "@earendil-works/pi-ai": "^1.3.0",
     "@earendil-works/pi-coding-agent": "^1.3.0",
     "@types/node": "^24.13.3",
+    "typebox": "^1.4.1",
     "typescript": "^5.9.0"
   }
 }