@mostajs/chatbot 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog — @mostajs/chatbot
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+## 0.2.0 — 2026-06-10
+- **Extraction en modules (façon @mostajs/orm)** : la couche LLM et la boucle/routeur quittent le chatbot.
+  - **`@mostajs/llm`** : dialectes (1 par IA) + registre + types function-calling (déplacés depuis `src/dialects/`).
+  - **`@mostajs/btool-use`** : boucle tool-use `runToolLoop` (extraite de `backends/ai.ts`).
+  - **`@mostajs/intent-router`** : routeur déterministe intents→outils (extrait de `backends/router.ts`).
+  - Le chatbot **compose** ces 3 modules ; backends `ai` (→ `runToolLoop`) et `router` (→ `intent-router`) recâblés.
+  - **Compat préservée** : `types.ts` réexporte sous les noms historiques (`ChatActor`/`ChatTool`/`ChatChunk`/`ChatIntent`),
+    `index.ts`/`server.ts` réexportent dialectes + `getLlmProvider`/`registerDialect`/`runToolLoop`/`matchIntent`… → **code app inchangé**.
+  - `src/dialects/` et `src/providers/` supprimés. Regroupement physique dans `mostajs/mosta-chat-stack/`.
+  - Vérifié : build vert ; app typecheck clean ; tool-use live DeepSeek **6/6** ; routeur cross-modules **5/5 (zéro IA)**.
+
+## 0.1.0 — 2026-06-10
+- **Backend `router` (routeur hybride)** : résout d'abord les **intents déterministes** fournis par
+  l'app (`ChatIntent` : slash-commande `/cmd` + motifs regex → outil + extraction d'arguments) en
+  appelant `tool.run(args, actor)` **DIRECTEMENT, sans aucun appel IA** (coût zéro, fiable, pas
+  d'hallucination) ; bascule sur l'IA uniquement en **repli** (`CHATBOT_ROUTER_FALLBACK=ai|scripted|none`,
+  défaut `ai`). Mêmes garde-fous d'écriture (autorisation + `needsConfirmation`). → « moins d'IA, plus
+  d'actions par outils maison » ; le chatbot **fonctionne même sans clé / hors-ligne**. Test `test-scripts/run-router-test.sh` **5/5**.
+- **Boucle tool-use (function-calling)** dans le backend `ai` : `complete()` → `tool_calls` →
+  `tool.run(args, actor)` → résultat renvoyé → reboucle → texte final (`MAX_TOOL_ROUNDS=6`). Débloque
+  le **niveau A** (exécution réelle d'outils). Écritures gardées : autorisation wildcard-aware
+  (`actorCanUse`) **et** confirmation humaine (les outils renvoient un aperçu `needsConfirmation` tant
+  que `confirm:true` n'est pas fourni). Streaming texte conservé en repli (pas d'outils / provider sans `complete`).
+- **Architecture dialectes** (calquée sur les *dialects* de `@mostajs/orm` : un dialecte par IA, DRY par
+  héritage). Interface `ILlmDialect` + registre `registerDialect`/`getDialect`/`getSupportedDialects`.
+  - Familles : **`OpenAiDialect`** (format OpenAI-compatible, `fetch`, zéro dép) et **`AnthropicDialect`**
+    (SDK, `tool_use`/`tool_result`, blocs bruts préservés pour le thinking adaptatif).
+  - Dialectes concrets (≈8 lignes, façon `CockroachDBDialect extends PostgresDialect`) : **`deepseek`**,
+    **`openai`**, **`mistral`**, **`groq`**, **`ollama`** (local, sans clé), **`anthropic`**.
+  - `providers/{deepseek,anthropic}` conservés en **alias rétrocompatibles** vers les dialectes.
+  - Métadonnées driver (clé/endpoint/modèle/dépendance + `available()`) façon `installHint` de l'ORM.
+- Test live (vrais appels DeepSeek) **6/6** : `order_status` réellement invoqué + valeur réelle restituée
+  (anti-hallucination) ; action d'écriture non exécutée sans autorisation, exécutée après confirmation.
+
+## 0.0.2 — 2026-06-08
+- **Règles de conduite du copilote** (gouvernance, à la DEVRULES) : champ `DomainProfile.rules?: string[]` + `CHATBOT_RULES` (`.env`, séparées par `|`), **injectés dans le prompt système** du backend `ai` sous un bloc « RÈGLES À RESPECTER IMPÉRATIVEMENT ». L'app peut alimenter `rules` depuis un **fichier** lu au runtime (ex. `COPILOT-RULES.md`). Helper `chatbotRules()`.
+
+## 0.0.1 — 2026-06-08
+- Scaffold (DEVRULES §5) après livrables #1-#3 (`docs/`). Assistant/copilote/agent **générique réutilisable**.
+- **Interrupteur maître** `CHATBOT_ENABLED` + rôles `CHATBOT_ROLES` + mode `CHATBOT_MODE=assistant|agent` (`.env`).
+- Registres pluggables (style dialectes) : **backends** (`scripted` défaut, `ai`), **providers LLM**, **outils** métier.
+- Providers LLM : **`anthropic`** (`@anthropic-ai/sdk`, `claude-opus-4-8`, adaptive thinking + streaming + option
+  web search) et **`deepseek`** (API compatible OpenAI, `fetch` SSE, sans dépendance).
+- **Multi-provider `CHATBOT_PROVIDERS=deepseek,anthropic,…`** avec **fallback** automatique.
+- API : `createChatbot({domain,tools})` → `enabled()/stream()/ask()` ; `registerBackend/LlmProvider/Tool`.
+- Client : widget React minimal `<Chatbot send=… />` (`./client`). Backend `scripted` minimal.
+- **Tout piloté par `.env`** (@mostajs/config, cascade MOSTA_ENV). Build `tsc` vert.

package/LICENSE

@@ -0,0 +1,21 @@
+@mostajs/i18n
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The complete text of the GNU Affero General Public License version 3 is
+available at the URL above and must accompany any distribution of this
+software.

package/README.md

@@ -0,0 +1,50 @@
+# @mostajs/chatbot
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+Assistant / copilote / agent conversationnel **générique et réutilisable** pour les apps `@mostajs/*`.
+**Activable/désactivable** et **entièrement piloté par `.env`**. Backends pluggables (`scripted` sans IA,
+`ai` avec LLM), **providers LLM pluggables avec fallback** (`anthropic`/`claude-opus-4-8`, `deepseek`),
+ancrage **tool-use** sur les données de l'app, **recherche web** optionnelle. Registres façon dialectes ORM.
+
+> Statut : **0.0.1 (scaffold)**. Livrables DEVRULES #1-#3 dans `docs/`. Voir `llms.txt` pour l'API complète.
+
+## Configuration (`.env` — tout par config)
+```
+CHATBOT_ENABLED=1                       # interrupteur maître (défaut 0)
+CHATBOT_ROLES=admin,employe             # vide = tous
+CHATBOT_MODE=assistant                  # assistant | agent
+CHATBOT_BACKEND=ai                      # scripted (défaut) | ai
+CHATBOT_PROVIDERS=deepseek,anthropic    # liste priorité + fallback
+CHATBOT_MODEL=                          # vide ⇒ défaut du provider
+ANTHROPIC_API_KEY=...                   # provider anthropic
+DEEPSEEK_API_KEY=...                    # provider deepseek (API compatible OpenAI)
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+CHATBOT_WEB_SEARCH=0                    # recherche web (anthropic)
+CHATBOT_EFFORT=high
+```
+
+## Usage (Next.js)
+```ts
+// serveur
+import { createChatbot, registerTool } from "@mostajs/chatbot";
+registerTool({ name:"orders_by_state", description:"Compter les commandes par état",
+  schema:{ type:"object", properties:{ state:{type:"string"} }, required:["state"] },
+  permission:"order.read", run: async ({state}, actor) => /* requête dépôt */ 0 });
+const bot = createChatbot({ domain:{ appName:"CRM TRADING",
+  description:"Société de négoce : commandes, fournisseurs, proformats.", locale:"fr" } });
+if (bot.enabled()) { const answer = await bot.ask([{role:"user",content:"aide"}], actor); }
+```
+```tsx
+// client (widget)
+import { Chatbot } from "@mostajs/chatbot/client";
+<Chatbot send={askServerAction} title="Assistant TRADING" />
+```
+
+## Ajouter un provider LLM (comme un dialecte)
+```ts
+import { registerLlmProvider } from "@mostajs/chatbot";
+registerLlmProvider({ key:"openai", async *stream(messages, tools, opts){ /* SSE */ } });
+```
+
+Peers : `@mostajs/config`, `@anthropic-ai/sdk` (optionnel), `react` (optionnel). DeepSeek : sans dépendance.

package/dist/backends/ai.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Backend `ai` — orchestre un dialecte LLM (@mostajs/llm). Construit le system prompt à partir du
+ * profil métier + des outils, puis :
+ *  - si des **outils** sont fournis ET que le dialecte sait faire `complete` → **boucle tool-use**
+ *    (déléguée à `@mostajs/btool-use` : `runToolLoop`) → exécution réelle des outils (gardée + confirmée) ;
+ *  - sinon → **streaming texte** (réponse ancrée, sans exécution d'outil).
+ * Multi-providers `.env` (CHATBOT_PROVIDERS) avec FALLBACK si le 1er chunk est une erreur.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IChatBackend } from "../types.js";
+export declare const aiBackend: IChatBackend;
+//# sourceMappingURL=ai.d.ts.map

package/dist/backends/ai.js

@@ -0,0 +1,71 @@
+import { getLlmProvider } from "@mostajs/llm";
+import { runToolLoop, actorCanUse } from "@mostajs/btool-use";
+import { registerBackend } from "../registry.js";
+import { chatbotProviders, chatbotModel, chatbotEffort, chatbotMaxTokens, chatbotWebSearch, chatbotRules } from "../config.js";
+/** Outils exposables à l'acteur (filtre RBAC ; l'autorisation fine reste faite par l'outil lui-même). */
+function visibleTools(ctx) {
+    return (ctx.tools ?? []).filter((t) => actorCanUse(ctx.actor, t.permission));
+}
+function systemPrompt(ctx) {
+    const tools = visibleTools(ctx);
+    const toolList = tools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+    // Règles impératives (gouvernance, à la DEVRULES) : profil métier (`domain.rules`) + ops (`CHATBOT_RULES`).
+    const rules = [...(ctx.domain.rules ?? []), ...chatbotRules()].map((r) => r.trim()).filter(Boolean);
+    const rulesBlock = rules.length ? `RÈGLES À RESPECTER IMPÉRATIVEMENT :\n${rules.join("\n")}` : "";
+    return [
+        `Tu es l'assistant de « ${ctx.domain.appName} ». ${ctx.domain.description}`,
+        ctx.domain.locale ? `Réponds en langue: ${ctx.domain.locale}.` : "",
+        rulesBlock,
+        toolList
+            ? `Tu disposes d'outils que tu peux APPELER directement pour obtenir des données réelles ou agir :\n${toolList}\n` +
+                `Appelle l'outil pertinent plutôt que d'inventer une donnée. Pour toute action d'ÉCRITURE, l'outil renvoie ` +
+                `d'abord un aperçu (champ « needsConfirmation ») SANS rien modifier : présente cet aperçu à l'utilisateur et ` +
+                `attends sa confirmation EXPLICITE avant de rappeler l'outil avec confirm=true.`
+            : "",
+        `N'invente jamais de données : si une information n'est pas disponible, dis-le.`,
+    ].filter(Boolean).join("\n\n");
+}
+export const aiBackend = {
+    key: "ai",
+    async *reply(ctx) {
+        const opts = {
+            model: chatbotModel() || undefined,
+            system: systemPrompt(ctx),
+            effort: chatbotEffort(),
+            maxTokens: chatbotMaxTokens(),
+            webSearch: chatbotWebSearch(),
+        };
+        const tools = visibleTools(ctx);
+        const hasTools = tools.length > 0;
+        const keys = chatbotProviders();
+        let lastErr = "aucun provider";
+        for (const key of keys) {
+            const provider = getLlmProvider(key);
+            if (!provider) {
+                lastErr = `provider « ${key} » inconnu`;
+                continue;
+            }
+            // Boucle tool-use (déléguée à @mostajs/btool-use) si outils + complete ; sinon streaming.
+            const it = (hasTools && typeof provider.complete === "function")
+                ? runToolLoop({ provider, messages: ctx.messages, tools, actor: ctx.actor, opts })[Symbol.asyncIterator]()
+                : provider.stream(ctx.messages, ctx.tools ?? [], opts)[Symbol.asyncIterator]();
+            const first = await it.next();
+            if (!first.done && first.value.type === "error") {
+                lastErr = first.value.text ?? "erreur";
+                continue;
+            }
+            if (!first.done)
+                yield first.value;
+            while (true) {
+                const n = await it.next();
+                if (n.done)
+                    break;
+                yield n.value;
+            }
+            return; // provider opérationnel : terminé
+        }
+        yield { type: "error", text: `Aucun provider LLM disponible (${keys.join(", ") || "—"}). Dernière erreur : ${lastErr}` };
+    },
+};
+registerBackend(aiBackend);
+//# sourceMappingURL=ai.js.map

package/dist/backends/router.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Backend `router` — **routeur hybride** : délègue à `@mostajs/intent-router` la résolution des
+ * **intents déterministes** (slash-commandes + motifs regex fournis par l'app) → exécution directe
+ * de l'outil **sans aucun appel IA** (coût zéro, fiable) ; ne bascule sur l'IA
+ * (`CHATBOT_ROUTER_FALLBACK=ai`, défaut) qu'en **repli** pour le langage libre. → « moins d'IA, plus
+ * d'actions par outils maison », et le chatbot **n'est pas dépendant de l'IA** (intents OK sans clé / hors-ligne).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IChatBackend } from "../types.js";
+export declare const routerBackend: IChatBackend;
+//# sourceMappingURL=router.d.ts.map

package/dist/backends/router.js

@@ -0,0 +1,39 @@
+import { matchIntent, runIntent } from "@mostajs/intent-router";
+import { registerBackend, getBackend } from "../registry.js";
+import { chatbotRouterFallback } from "../config.js";
+/** Dernier message utilisateur (le texte à router). */
+function lastUserText(ctx) {
+    for (let i = ctx.messages.length - 1; i >= 0; i--)
+        if (ctx.messages[i].role === "user")
+            return ctx.messages[i].content ?? "";
+    return "";
+}
+export const routerBackend = {
+    key: "router",
+    async *reply(ctx) {
+        const intents = ctx.intents ?? [];
+        const text = lastUserText(ctx);
+        // 1) Intent déterministe → exécution directe, ZÉRO appel IA.
+        const hit = intents.length ? matchIntent(text, intents) : null;
+        if (hit) {
+            yield* runIntent({ intent: hit.intent, args: hit.args, tools: ctx.tools ?? [], actor: ctx.actor });
+            return;
+        }
+        // 2) Repli configurable (langage libre).
+        const fb = chatbotRouterFallback();
+        if (fb === "none") {
+            const cmds = intents.filter((i) => i.command).map((i) => `/${i.command}`).join("  ");
+            yield { type: "text", text: cmds ? `Je n'ai pas compris. Commandes disponibles : ${cmds}` : "Je n'ai pas compris la demande." };
+            yield { type: "done" };
+            return;
+        }
+        const backend = getBackend(fb) ?? getBackend("ai") ?? getBackend("scripted");
+        if (!backend || backend.key === "router") {
+            yield { type: "error", text: `Repli « ${fb} » introuvable.` };
+            return;
+        }
+        yield* backend.reply(ctx);
+    },
+};
+registerBackend(routerBackend);
+//# sourceMappingURL=router.js.map

package/dist/backends/scripted.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Backend `scripted` — réponses à intentions/FAQ, sans IA, sans clé, sans coût (défaut).
+ * Minimal en 0.0.1 : aiguillage par mots-clés sur le profil métier ; à enrichir (intents) en 0.1.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IChatBackend } from "../types.js";
+export declare const scriptedBackend: IChatBackend;
+//# sourceMappingURL=scripted.d.ts.map

package/dist/backends/scripted.js

@@ -0,0 +1,25 @@
+import { registerBackend } from "../registry.js";
+export const scriptedBackend = {
+    key: "scripted",
+    async *reply(ctx) {
+        const last = [...ctx.messages].reverse().find((m) => m.role === "user")?.content?.toLowerCase() ?? "";
+        const tools = (ctx.tools ?? []).map((t) => `• ${t.name} — ${t.description}`).join("\n");
+        let text;
+        if (/aide|help|mode d'emploi|comment/.test(last)) {
+            text = `Assistant ${ctx.domain.appName}. ${ctx.domain.description}\n` +
+                (tools ? `Je peux mobiliser :\n${tools}` : "Posez votre question.") +
+                `\n\n(Backend « scripted » — activez l'IA via CHATBOT_BACKEND=ai pour des réponses en langage naturel.)`;
+        }
+        else if (!last) {
+            text = `Bonjour 👋 — assistant ${ctx.domain.appName}. Tapez « aide » pour commencer.`;
+        }
+        else {
+            text = `Je suis en mode « scripted » (sans IA) et ne sais pas répondre librement à « ${last} ». ` +
+                `Activez le backend IA (CHATBOT_BACKEND=ai) pour une réponse en langage naturel.`;
+        }
+        yield { type: "text", text };
+        yield { type: "done" };
+    },
+};
+registerBackend(scriptedBackend);
+//# sourceMappingURL=scripted.js.map

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+export declare function Chatbot({ send, title, greeting }: {
+    send: (text: string) => Promise<string>;
+    title?: string;
+    greeting?: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,34 @@
+/**
+ * @mostajs/chatbot/client — widget React minimal (bulle + panneau). L'app fournit `send(text)`
+ * (qui appelle son endpoint serveur → createChatbot). Styles : classes `cbot-*` côté hôte.
+ * (0.0.1 : non-streaming. Streaming SSE en 0.3.)
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+export function Chatbot({ send, title = "Assistant", greeting = "Bonjour 👋" }) {
+    const [open, setOpen] = useState(false);
+    const [msgs, setMsgs] = useState([{ role: "assistant", content: greeting }]);
+    const [val, setVal] = useState("");
+    const [busy, setBusy] = useState(false);
+    const submit = async (e) => {
+        e.preventDefault();
+        const t = val.trim();
+        if (!t || busy)
+            return;
+        setVal("");
+        setMsgs((m) => [...m, { role: "user", content: t }]);
+        setBusy(true);
+        try {
+            const r = await send(t);
+            setMsgs((m) => [...m, { role: "assistant", content: r }]);
+        }
+        catch {
+            setMsgs((m) => [...m, { role: "assistant", content: "Erreur de l'assistant." }]);
+        }
+        setBusy(false);
+    };
+    return (_jsxs("div", { className: "cbot", children: [open ? (_jsxs("div", { className: "cbot-panel", role: "dialog", children: [_jsxs("div", { className: "cbot-head", children: [_jsx("span", { children: title }), _jsx("button", { className: "cbot-x", onClick: () => setOpen(false), "aria-label": "Fermer", children: "\u00D7" })] }), _jsxs("div", { className: "cbot-msgs", children: [msgs.map((m, i) => _jsx("div", { className: `cbot-msg ${m.role}`, children: m.content }, i)), busy ? _jsx("div", { className: "cbot-msg assistant cbot-typing", children: "\u2026" }) : null] }), _jsxs("form", { className: "cbot-form", onSubmit: submit, children: [_jsx("input", { value: val, onChange: (e) => setVal(e.target.value), placeholder: "Votre question\u2026" }), _jsx("button", { className: "cbot-send", type: "submit", disabled: busy, children: "\u27A4" })] })] })) : null, _jsx("button", { className: "cbot-fab", onClick: () => setOpen((v) => !v), "aria-label": title, children: "\uD83E\uDD16" })] }));
+}
+//# sourceMappingURL=client.js.map

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import type { ChatbotMode } from "./types.js";
+/** Interrupteur MAÎTRE — désactivé par défaut (opt-in explicite). */
+export declare function chatbotEnabled(): boolean;
+/** Mode : `assistant` (Q&A/copilote) ou `agent` (boucle but→outils→action). */
+export declare function chatbotMode(): ChatbotMode;
+/** Backend de réponse : `scripted` (défaut, sans IA) ou `ai` (LLM). */
+export declare function chatbotBackend(): string;
+/**
+ * Providers LLM actifs (backend `ai`), en **ordre de priorité / fallback**.
+ * `CHATBOT_PROVIDERS=deepseek,anthropic,…` (liste) ; sinon `CHATBOT_PROVIDER` (single) ; défaut `anthropic`.
+ */
+export declare function chatbotProviders(): string[];
+/** Premier provider (compat). */
+export declare function chatbotProvider(): string;
+/** Modèle LLM (jamais en dur — §10). Vide ⇒ défaut spécifique au provider (anthropic→claude-opus-4-8, deepseek→deepseek-chat). */
+export declare function chatbotModel(): string;
+/** Recherche web (outils serveur `web_search`/`web_fetch`). */
+export declare function chatbotWebSearch(): boolean;
+export declare function chatbotEffort(): string;
+export declare function chatbotMaxTokens(): number;
+/** Rôles autorisés (vide = tous les utilisateurs authentifiés). */
+export declare function chatbotAllowedRoles(): string[];
+/** Règles impératives supplémentaires (ops) injectées dans le prompt système. `CHATBOT_RULES=r1|r2|…`. */
+export declare function chatbotRules(): string[];
+/**
+ * Backend de **repli** du routeur hybride quand aucun intent déterministe ne matche.
+ * `CHATBOT_ROUTER_FALLBACK=ai|scripted|none` (défaut `ai`). `none` ⇒ message d'aide, aucun appel IA.
+ */
+export declare function chatbotRouterFallback(): string;
+/** L'acteur a-t-il le droit d'utiliser l'assistant ? (maître + rôles) */
+export declare function chatbotAllowsRole(role: string): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,49 @@
+/**
+ * @mostajs/chatbot — configuration `.env` (@mostajs/config, cascade MOSTA_ENV).
+ * Interrupteur maître + mode + backend + provider + modèle + recherche web + quotas/rôles.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import { getEnv } from "@mostajs/config";
+/** Interrupteur MAÎTRE — désactivé par défaut (opt-in explicite). */
+export function chatbotEnabled() { return getEnv("CHATBOT_ENABLED", "0") === "1"; }
+/** Mode : `assistant` (Q&A/copilote) ou `agent` (boucle but→outils→action). */
+export function chatbotMode() { return getEnv("CHATBOT_MODE", "assistant") === "agent" ? "agent" : "assistant"; }
+/** Backend de réponse : `scripted` (défaut, sans IA) ou `ai` (LLM). */
+export function chatbotBackend() { return getEnv("CHATBOT_BACKEND", "scripted"); }
+/**
+ * Providers LLM actifs (backend `ai`), en **ordre de priorité / fallback**.
+ * `CHATBOT_PROVIDERS=deepseek,anthropic,…` (liste) ; sinon `CHATBOT_PROVIDER` (single) ; défaut `anthropic`.
+ */
+export function chatbotProviders() {
+    const raw = getEnv("CHATBOT_PROVIDERS", "") || getEnv("CHATBOT_PROVIDER", "anthropic");
+    return raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+/** Premier provider (compat). */
+export function chatbotProvider() { return chatbotProviders()[0] ?? "anthropic"; }
+/** Modèle LLM (jamais en dur — §10). Vide ⇒ défaut spécifique au provider (anthropic→claude-opus-4-8, deepseek→deepseek-chat). */
+export function chatbotModel() { return getEnv("CHATBOT_MODEL", ""); }
+/** Recherche web (outils serveur `web_search`/`web_fetch`). */
+export function chatbotWebSearch() { return getEnv("CHATBOT_WEB_SEARCH", "0") === "1"; }
+export function chatbotEffort() { return getEnv("CHATBOT_EFFORT", "high"); }
+export function chatbotMaxTokens() { return Number(getEnv("CHATBOT_MAX_TOKENS", "4096")) || 4096; }
+/** Rôles autorisés (vide = tous les utilisateurs authentifiés). */
+export function chatbotAllowedRoles() {
+    return getEnv("CHATBOT_ROLES", "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+/** Règles impératives supplémentaires (ops) injectées dans le prompt système. `CHATBOT_RULES=r1|r2|…`. */
+export function chatbotRules() {
+    return getEnv("CHATBOT_RULES", "").split("|").map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Backend de **repli** du routeur hybride quand aucun intent déterministe ne matche.
+ * `CHATBOT_ROUTER_FALLBACK=ai|scripted|none` (défaut `ai`). `none` ⇒ message d'aide, aucun appel IA.
+ */
+export function chatbotRouterFallback() { return getEnv("CHATBOT_ROUTER_FALLBACK", "ai"); }
+/** L'acteur a-t-il le droit d'utiliser l'assistant ? (maître + rôles) */
+export function chatbotAllowsRole(role) {
+    if (!chatbotEnabled())
+        return false;
+    const allowed = chatbotAllowedRoles();
+    return allowed.length === 0 || allowed.includes(role);
+}
+//# sourceMappingURL=config.js.map

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @mostajs/chatbot — point d'entrée serveur-safe. Assistant/copilote/agent générique, réutilisable
+ * par toute app `@mostajs/*` : l'app fournit son **profil métier** + ses **outils** (+ **intents**) ;
+ * le module route vers le backend configuré (`scripted` | `ai` | `router`). Activable/désactivable (`.env`).
+ *
+ * Architecture en couches (façon ORM) :
+ *   @mostajs/llm           — dialectes (1 par IA) + registre + types function-calling
+ *   @mostajs/btool-use     — boucle tool-use (runToolLoop), compose llm
+ *   @mostajs/intent-router — routeur déterministe intents→outils, compose llm
+ *   @mostajs/chatbot       — backends (scripted/ai/router) + createChatbot + widget ; compose les 3 ci-dessus
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import "@mostajs/llm";
+import "./backends/scripted.js";
+import "./backends/ai.js";
+import "./backends/router.js";
+import type { ChatChunk, ChatMessage, ChatActor, DomainProfile, ChatTool, ChatIntent } from "./types.js";
+export interface ChatbotOptions {
+    domain: DomainProfile;
+    tools?: ChatTool[];
+    intents?: ChatIntent[];
+}
+export declare function createChatbot(options: ChatbotOptions): {
+    enabled: () => boolean;
+    stream: (messages: ChatMessage[], actor: ChatActor) => AsyncIterable<ChatChunk>;
+    ask: (messages: ChatMessage[], actor: ChatActor) => Promise<string>;
+};
+export type { ChatbotOptions as Options };
+export type { AskContext, ChatChunk, ChatMessage, ChatActor, DomainProfile, ChatTool, ChatIntent, IChatBackend, ILlmProvider, ILlmDialect, ToolCall, LlmMessage, LlmTurn, ChatbotMode, LlmStreamOpts, } from "./types.js";
+export { registerBackend, getBackend, listBackends, registerTool, getTool, listTools } from "./registry.js";
+export { registerLlmProvider, getLlmProvider, listLlmProviders, registerDialect, getDialect, listDialects, getSupportedDialects, AbstractLlmDialect, OpenAiDialect, DeepSeekDialect, MistralDialect, GroqDialect, OllamaDialect, AnthropicDialect, } from "@mostajs/llm";
+export { runToolLoop } from "@mostajs/btool-use";
+export { matchIntent, runIntent } from "@mostajs/intent-router";
+export { chatbotEnabled, chatbotMode, chatbotBackend, chatbotProvider, chatbotProviders, chatbotModel, chatbotWebSearch, chatbotEffort, chatbotMaxTokens, chatbotAllowedRoles, chatbotAllowsRole, chatbotRouterFallback, } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * @mostajs/chatbot — point d'entrée serveur-safe. Assistant/copilote/agent générique, réutilisable
+ * par toute app `@mostajs/*` : l'app fournit son **profil métier** + ses **outils** (+ **intents**) ;
+ * le module route vers le backend configuré (`scripted` | `ai` | `router`). Activable/désactivable (`.env`).
+ *
+ * Architecture en couches (façon ORM) :
+ *   @mostajs/llm           — dialectes (1 par IA) + registre + types function-calling
+ *   @mostajs/btool-use     — boucle tool-use (runToolLoop), compose llm
+ *   @mostajs/intent-router — routeur déterministe intents→outils, compose llm
+ *   @mostajs/chatbot       — backends (scripted/ai/router) + createChatbot + widget ; compose les 3 ci-dessus
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import "@mostajs/llm"; // enregistre les dialectes LLM (deepseek, anthropic, openai, mistral, groq, ollama)
+import "./backends/scripted.js"; // backends built-in (effet de bord)
+import "./backends/ai.js";
+import "./backends/router.js";
+import { getBackend } from "./registry.js";
+import { chatbotEnabled, chatbotBackend, chatbotAllowsRole, chatbotMode } from "./config.js";
+export function createChatbot(options) {
+    async function* stream(messages, actor) {
+        if (!chatbotAllowsRole(actor.role)) {
+            yield { type: "error", text: "Assistant désactivé pour votre profil." };
+            return;
+        }
+        const backend = getBackend(chatbotBackend()) ?? getBackend("scripted");
+        const ctx = { messages, actor, domain: options.domain, tools: options.tools, intents: options.intents, mode: chatbotMode() };
+        yield* backend.reply(ctx);
+    }
+    async function ask(messages, actor) {
+        let out = "";
+        for await (const c of stream(messages, actor))
+            if (c.type === "text" && c.text)
+                out += c.text;
+        return out;
+    }
+    return { enabled: () => chatbotEnabled(), stream, ask };
+}
+export { registerBackend, getBackend, listBackends, registerTool, getTool, listTools } from "./registry.js";
+// Réexports de la couche LLM (compat : ces symboles vivaient dans @mostajs/chatbot avant l'extraction).
+export { registerLlmProvider, getLlmProvider, listLlmProviders, registerDialect, getDialect, listDialects, getSupportedDialects, AbstractLlmDialect, OpenAiDialect, DeepSeekDialect, MistralDialect, GroqDialect, OllamaDialect, AnthropicDialect, } from "@mostajs/llm";
+export { runToolLoop } from "@mostajs/btool-use";
+export { matchIntent, runIntent } from "@mostajs/intent-router";
+export { chatbotEnabled, chatbotMode, chatbotBackend, chatbotProvider, chatbotProviders, chatbotModel, chatbotWebSearch, chatbotEffort, chatbotMaxTokens, chatbotAllowedRoles, chatbotAllowsRole, chatbotRouterFallback, } from "./config.js";
+//# sourceMappingURL=index.js.map

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @mostajs/chatbot — registres de la couche conversation : **backends** de réponse + **outils** métier.
+ * Le registre des **dialectes/providers LLM** vit dans `@mostajs/llm` (réexporté par l'index pour compat).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { IChatBackend, ChatTool } from "./types.js";
+export declare function registerBackend(b: IChatBackend): void;
+export declare function getBackend(key: string): IChatBackend | null;
+export declare function listBackends(): IChatBackend[];
+/** Outils métier : l'app enregistre les siens (lecture seule par défaut). */
+export declare function registerTool(t: ChatTool): void;
+export declare function listTools(): ChatTool[];
+export declare function getTool(name: string): ChatTool | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,10 @@
+const BACKENDS = new Map();
+const TOOLS = new Map();
+export function registerBackend(b) { BACKENDS.set(b.key, b); }
+export function getBackend(key) { return BACKENDS.get(key) ?? null; }
+export function listBackends() { return Array.from(BACKENDS.values()); }
+/** Outils métier : l'app enregistre les siens (lecture seule par défaut). */
+export function registerTool(t) { TOOLS.set(t.name, t); }
+export function listTools() { return Array.from(TOOLS.values()); }
+export function getTool(name) { return TOOLS.get(name) ?? null; }
+//# sourceMappingURL=registry.js.map

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @mostajs/chatbot/server — backends/providers concrets (utile pour enregistrer des extensions
+ * ou composer côté serveur). Réexporte l'API publique.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export * from "./index.js";
+export { scriptedBackend } from "./backends/scripted.js";
+export { aiBackend } from "./backends/ai.js";
+export { routerBackend } from "./backends/router.js";
+export { AnthropicDialect, AnthropicDialect as anthropicProvider } from "@mostajs/llm";
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,12 @@
+/**
+ * @mostajs/chatbot/server — backends/providers concrets (utile pour enregistrer des extensions
+ * ou composer côté serveur). Réexporte l'API publique.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export * from "./index.js";
+export { scriptedBackend } from "./backends/scripted.js";
+export { aiBackend } from "./backends/ai.js";
+export { routerBackend } from "./backends/router.js";
+// Le dialecte Anthropic vit désormais dans @mostajs/llm (réexporté ici pour compat).
+export { AnthropicDialect, AnthropicDialect as anthropicProvider } from "@mostajs/llm";
+//# sourceMappingURL=server.js.map

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @mostajs/chatbot — types de la couche **conversation**. La couche **modèle** (dialectes, tool-use,
+ * function-calling) vit dans `@mostajs/llm` (composé) ; les intents déterministes dans
+ * `@mostajs/intent-router`. On réexporte ces types sous les **noms historiques** du chatbot (compat).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { LlmActor, LlmTool, LlmChunk } from "@mostajs/llm";
+import type { Intent } from "@mostajs/intent-router";
+export type ChatbotMode = "assistant" | "agent";
+export type ChatRole = "user" | "assistant" | "system";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+/** Acteur — alias de `LlmActor`. */
+export type ChatActor = LlmActor;
+/** Outil métier (tool-use) — alias de `LlmTool`. */
+export type ChatTool = LlmTool;
+/** Fragment streamé — alias de `LlmChunk`. */
+export type ChatChunk = LlmChunk;
+/** Intent déterministe (routeur hybride) — alias de `Intent` (@mostajs/intent-router). */
+export type ChatIntent = Intent;
+export type { LlmActor, LlmTool, LlmChunk, LlmMessage, LlmStreamOpts, LlmTurn, ToolCall, ILlmProvider, ILlmDialect } from "@mostajs/llm";
+/** Profil métier injecté par l'app hôte — rend le module réutilisable partout. */
+export interface DomainProfile {
+    appName: string;
+    description: string;
+    locale?: string;
+    /**
+     * Règles de conduite **impératives** du copilote (gouvernance, à la DEVRULES) — injectées dans le
+     * prompt système comme contraintes à respecter (ex. « demander confirmation avant toute action »,
+     * « ancrer chaque offre sur une source », « ne jamais exposer de secret »). Cumulées avec `CHATBOT_RULES`.
+     */
+    rules?: string[];
+}
+/** Contexte d'une requête à l'assistant. */
+export interface AskContext {
+    messages: ChatMessage[];
+    actor: ChatActor;
+    domain: DomainProfile;
+    tools?: ChatTool[];
+    /** Intents déterministes (routeur hybride) — fournis par l'app. */
+    intents?: ChatIntent[];
+    mode?: ChatbotMode;
+}
+/** Backend de réponse : `scripted` (règles/FAQ), `ai` (LLM + tool-use) ou `router` (hybride). */
+export interface IChatBackend {
+    key: string;
+    reply(ctx: AskContext): AsyncIterable<ChatChunk>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/llms.txt

@@ -0,0 +1,59 @@
+# @mostajs/chatbot — fiche LLM
+> Assistant / copilote / agent conversationnel GÉNÉRIQUE et réutilisable pour apps @mostajs/*. Activable/désactivable et **entièrement piloté par `.env`**. Backends pluggables (scripted | ai) ; providers LLM pluggables (anthropic/claude-opus-4-8, deepseek) avec **fallback** ; ancrage tool-use ; recherche web optionnelle. Registres façon dialectes ORM.
+
+- Version: 0.0.1 (scaffold) · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-chatbot · Livrables #1-#3: `docs/01..03` + `docs/scripts-recherche-chatbot-08062026.sh`
+
+## RÔLE
+L'app hôte fournit son **profil métier** (`DomainProfile`) + ses **outils** (`ChatTool`, lecture seule par
+défaut, RBAC) ; le module route vers le **backend** configuré et, en mode `ai`, vers un **provider LLM**
+(avec fallback). Aucune logique d'une app particulière dans le module (réutilisable partout : CRM, santé, …).
+
+## EXPORTS
+- `.` (serveur-safe) : `createChatbot({domain,tools})` → `{enabled(), stream(messages,actor), ask(messages,actor)}` ;
+  `registerBackend/getBackend/listBackends`, `registerLlmProvider/getLlmProvider/listLlmProviders`,
+  `registerTool/getTool/listTools` ; toute la config (`chatbot*`) ; types.
+- `./server` : built-ins concrets (`scriptedBackend`, `aiBackend`, `anthropicProvider`, `deepseekProvider`).
+- `./client` (React) : `<Chatbot send=… title? greeting? />` (widget bulle+panneau ; SSE en 0.3).
+
+## CONFIG (.env — @mostajs/config, cascade MOSTA_ENV) — TOUT par .env
+- `CHATBOT_ENABLED=0|1` (défaut 0, opt-in) · `CHATBOT_ROLES=admin,employe` (vide=tous) · `CHATBOT_MODE=assistant|agent`
+- `CHATBOT_BACKEND=scripted|ai` (défaut scripted)
+- `CHATBOT_PROVIDERS=deepseek,anthropic` (liste priorité+fallback ; `CHATBOT_PROVIDER` = single, compat)
+- `CHATBOT_MODEL=` (vide ⇒ défaut provider : anthropic→claude-opus-4-8, deepseek→deepseek-chat)
+- Anthropic : `ANTHROPIC_API_KEY` · `CHATBOT_WEB_SEARCH=0|1` · `CHATBOT_EFFORT=low|medium|high|xhigh|max`
+- DeepSeek : `DEEPSEEK_API_KEY` · `DEEPSEEK_BASE_URL=https://api.deepseek.com` (compatible OpenAI)
+- `CHATBOT_MAX_TOKENS` · `CHATBOT_QUOTA_PER_ROLE` (à venir)
+
+## PROVIDERS LLM (registre — ajouter = un fichier + register)
+- `anthropic` : `@anthropic-ai/sdk`, modèle `claude-opus-4-8`, `thinking:{type:"adaptive"}`, streaming, outils
+  serveur `web_search`/`web_fetch` si `CHATBOT_WEB_SEARCH=1`.
+- `deepseek` : endpoint `/chat/completions` (OpenAI-compatible), SSE en `fetch`, modèles `deepseek-chat` /
+  `deepseek-v4-flash` / `deepseek-v4-pro`. Sans dépendance.
+- Extension : `registerLlmProvider({ key:"openai", stream(messages,tools,opts){…} })`.
+
+## TYPES CLÉS
+DomainProfile { appName, description, locale? } · ChatTool { name, description, schema, permission?, run(input,actor) }
+ChatActor { id, role, permissions? } · ChatChunk { type:'text'|'tool'|'done'|'error', text?, tool? }
+IChatBackend { key, reply(ctx): AsyncIterable<ChatChunk> } · ILlmProvider { key, stream(msgs,tools,opts) }
+
+## PATTERN (app Next.js)
+```ts
+// serveur
+import { createChatbot, registerTool } from "@mostajs/chatbot";
+registerTool({ name:"orders_by_state", description:"Compter les commandes par état", schema:{...},
+  permission:"order.read", run: async ({state}) => crm.repositories.orders.find(o=>o.state===state).length });
+const bot = createChatbot({ domain:{ appName:"CRM TRADING", description:"Négoce: commandes/fournisseurs/proformats", locale:"fr" } });
+if (bot.enabled()) for await (const c of bot.stream(messages, actor)) { /* stream */ }
+```
+
+## DÉPEND DE (peers)
+- `@mostajs/config` (env). `@anthropic-ai/sdk` (optionnel — provider anthropic). `react` (optionnel — `./client`).
+- DeepSeek : aucune dépendance (fetch). Composition prévue : `@mostajs/repository` (outils/historique),
+  `@mostajs/auth`/`rbac` (accès+outils), `@mostajs/audit` (traçabilité), `@mostajs/i18n`, `@mostajs/net` (SSE).
+
+## PIÈGES
+- `CHATBOT_ENABLED=0` par défaut : rien ne s'affiche/ne coûte tant qu'on n'a pas opt-in.
+- `./client` est 'use client' : importer `createChatbot` (serveur) à part, passer un `send()` au widget.
+- Multi-provider : laisser `CHATBOT_MODEL` vide pour que chaque provider applique son défaut.
+- Backend `ai` envoie le contexte à un tiers (Anthropic/DeepSeek) : opt-in, pas de secret au prompt, audit, RGPD.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@mostajs/chatbot",
+  "version": "0.2.0",
+  "description": "Assistant / copilote / agent conversationnel générique et réutilisable pour apps @mostajs/* — backends pluggables (scripted | ai), providers LLM pluggables (anthropic/claude-opus-4-8 par défaut), ancrage tool-use, recherche web optionnelle. Activable/désactivable par .env.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "llms.txt",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@mostajs/config": "*",
+    "@mostajs/llm": "*",
+    "@mostajs/btool-use": "*",
+    "@mostajs/intent-router": "*",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/react": "^19.0.0"
+  },
+  "keywords": [
+    "chatbot",
+    "assistant",
+    "copilot",
+    "agent",
+    "llm",
+    "anthropic",
+    "claude",
+    "tool-use",
+    "mostajs"
+  ]
+}