@ai-for-dev/providers 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI-for-dev team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @ai-for-dev/providers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Providers [Pi](https://pi.dev) pour la formation AI4Dev. Le paquet ajoute deux fournisseurs de modèles :
+
+| Commande | Serveur |
+|---|---|
+| `/login ia4dev-ilaas` | https://devllm.ilaas.fr/v1 |
+| `/login ia4dev-gricad` | https://ia4dev-owui.univ-grenoble-alpes.fr/api |
+
+## Installation
+
+```bash
+pi install npm:@ai-for-dev/providers
+```
+
+## Utilisation
+
+1. Lancez `pi`.
+2. Tapez `/login ia4dev-ilaas` (ou `/login ia4dev-gricad`) et collez votre clé API.
+3. Choisissez un modèle avec `/model`.
+
+La liste des modèles est lue sur le serveur (`GET /models`) avec votre clé. Elle se met à jour au démarrage, à l'ouverture de `/model` et après `/login`.
+
+Vous pouvez aussi fournir la clé par variable d'environnement : `ILAAS_API_KEY` ou `IA4DEV_API_KEY`.
+
+## Changer d'URL
+
+`IA4DEV_ILAAS_BASE_URL` et `IA4DEV_GRICAD_BASE_URL` remplacent l'URL par défaut.
+
+## Réglages des modèles
+
+`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 :
+
+- 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.
+
+## Limites
+
+- Un fournisseur déjà défini sous le même nom dans `~/.pi/agent/models.json` prend le dessus sur celui du paquet.
+- La liste des modèles est mise en cache. Après un changement d'URL, elle se met à jour au prochain rafraîchissement (`/model` ou `/login`).
+
+## Développement
+
+```bash
+npm ci
+npm run typecheck
+npm test
+```
+
+Les tests tournent hors ligne : un faux `pi` et un `fetch` simulé remplacent Pi et les serveurs.
+
+## Publication
+
+La publication reprend le fonctionnement de `@ai-for-dev/combo` :
+
+1. Lancer le workflow `release-please` à la main. Il ouvre une pull request avec le `CHANGELOG.md` et la nouvelle version, calculés à partir des titres de commits (conventional commits).
+2. Fusionner cette pull request, puis relancer `release-please`. Ce second passage crée le tag et la release GitHub.
+3. La release déclenche `publish`, qui vérifie le code et envoie le paquet sur npm en mode « staged ».
+4. Approuver la version depuis une machine qui peut répondre à la double authentification : `npm stage list`, puis `npm stage approve <id>`.
+
+Le dépôt a besoin du secret `RELEASE_PLEASE` (un token GitHub qui peut écrire le contenu et les pull requests), et npm doit déclarer ce dépôt et `publish.yml` comme éditeur de confiance (trusted publisher) pour `@ai-for-dev/providers`.

package/extensions/index.ts

@@ -0,0 +1,189 @@
+// The compat entry point: Pi maps the package root to it as well, and it is the one
+// that exports openAICompletionsApi when the tests run under plain Node.
+import {
+	createProvider,
+	envApiKeyAuth,
+	type Model,
+	openAICompletionsApi,
+	type RefreshModelsContext,
+} from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type ChatModel = Model<"openai-completions">;
+
+/**
+ * How a model handles reasoning, measured against the real servers:
+ * - "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" | Efforts;
+
+interface Efforts {
+	low: string;
+	medium: string;
+	high: string;
+}
+
+interface ModelTuning {
+	contextWindow?: number;
+	maxTokens?: number;
+	vision?: boolean;
+	thinking?: Thinking;
+	// Listed by the server but unusable for the course.
+	hidden?: boolean;
+}
+
+interface Endpoint {
+	id: string;
+	name: string;
+	baseUrl: string;
+	envVar: string;
+	models: Record<string, ModelTuning>;
+}
+
+const ENDPOINTS: Endpoint[] = [
+	{
+		id: "ia4dev-ilaas",
+		name: "ILAAS",
+		baseUrl: "https://devllm.ilaas.fr/v1",
+		envVar: "ILAAS_API_KEY",
+		models: {
+			"scaleway/glm-5.2": { contextWindow: 256_000, maxTokens: 16_384, vision: false, thinking: "always" },
+			"scaleway/glm-5.3": { contextWindow: 256_000, maxTokens: 16_384, vision: false, thinking: "always" },
+			"scaleway/deepseek-v4.1-flash": { contextWindow: 256_000, maxTokens: 32_768, vision: true, thinking: "always" },
+			"scaleway/deepseek-v4-flash-0731": { contextWindow: 256_000, maxTokens: 32_768, vision: false, thinking: "always" },
+			"qwen-3.6-35b-instruct": { contextWindow: 262_144, vision: true, thinking: "toggle" },
+			"gemma-4-31b": { contextWindow: 131_072, vision: true, thinking: "toggle" },
+			"llama-3.1-8b": { hidden: true },
+			"gpt-oss-120b": { hidden: true },
+			"mistral-small-4-119b": { contextWindow: 128_000, vision: true, thinking: "none" },
+			"mistral-medium-latest": { contextWindow: 128_000, vision: true, thinking: "none" },
+		},
+	},
+	{
+		id: "ia4dev-gricad",
+		name: "IA4Dev",
+		baseUrl: "https://ia4dev-owui.univ-grenoble-alpes.fr/api",
+		envVar: "IA4DEV_API_KEY",
+		models: {
+			// The chat template accepts low, medium and xhigh (its default).
+			"qwen-3.8-27b": { 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": { vision: true, thinking: { low: "low", medium: "high", high: "max" } },
+			"gemma-4-31b": { vision: true, thinking: "toggle" },
+		},
+	},
+];
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 32_768;
+const FETCH_TIMEOUT_MS = 10_000;
+
+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;
+	// LiteLLM tags embedding and reranking models with a mode; they cannot chat.
+	mode?: string;
+	// vLLM reports max_model_len, LiteLLM max_input_tokens and max_output_tokens.
+	max_model_len?: number;
+	max_input_tokens?: number;
+	max_output_tokens?: number;
+}
+
+function toModel(endpoint: Endpoint, remote: RemoteModel): ChatModel {
+	const tuning = endpoint.models[remote.id] ?? {};
+	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;
+	return {
+		id: remote.id,
+		name: remote.id,
+		api: "openai-completions",
+		provider: endpoint.id,
+		baseUrl: endpoint.baseUrl,
+		input: tuning.vision ? ["text", "image"] : ["text"],
+		reasoning: reasoning.reasoning,
+		thinkingLevelMap: reasoning.thinkingLevelMap,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow,
+		maxTokens: Math.min(maxTokens, contextWindow),
+		compat: {
+			// These gateways reject the newer OpenAI-only fields.
+			supportsDeveloperRole: false,
+			supportsStore: false,
+			// 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,
+			...reasoning.compat,
+		},
+	};
+}
+
+async function fetchModels(endpoint: Endpoint, context: RefreshModelsContext): Promise<ChatModel[]> {
+	const key = context.credential?.type === "api_key" ? context.credential.key : process.env[endpoint.envVar];
+	if (!context.allowNetwork || !key) return [];
+
+	const response = await fetch(`${endpoint.baseUrl}/models`, {
+		headers: { Authorization: `Bearer ${key}` },
+		signal: AbortSignal.any([context.signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)]),
+	});
+	if (!response.ok) {
+		throw new Error(`${endpoint.name}: GET /models a répondu ${response.status}`);
+	}
+	const body = (await response.json()) as { data?: RemoteModel[] };
+	return (body.data ?? [])
+		.filter((m) => typeof m.id === "string" && (m.mode === undefined || m.mode === "chat"))
+		.filter((m) => !endpoint.models[m.id]?.hidden)
+		.map((m) => toModel(endpoint, m));
+}
+
+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 };
+		pi.registerProvider(
+			createProvider<"openai-completions">({
+				id: endpoint.id,
+				name: endpoint.name,
+				baseUrl: endpoint.baseUrl,
+				auth: { apiKey: envApiKeyAuth(`${endpoint.name} API key`, [endpoint.envVar]) },
+				models: [],
+				fetchModels: (context) => fetchModels(endpoint, context),
+				api: openAICompletionsApi(),
+			}),
+		);
+	}
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@ai-for-dev/providers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Pi providers for the AI4Dev course models (ILAAS and IA4Dev)",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "provider",
+    "llm"
+  ],
+  "license": "MIT",
+  "author": "AI-for-dev team",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AI-for-dev/providers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AI-for-dev/providers/issues"
+  },
+  "type": "module",
+  "files": [
+    "extensions",
+    "LICENSE",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.0"
+  }
+}