@netbirdio/explain 0.1.0

package/dist/server/handler.js

@@ -0,0 +1,117 @@
+import { AnthropicProvider } from "./providers/anthropic";
+import { OpenAIProvider } from "./providers/openai";
+function getHeader(req, name) {
+    if (typeof req.headers === "object" && req.headers !== null) {
+        if ("get" in req.headers && typeof req.headers.get === "function") {
+            return req.headers.get(name);
+        }
+        const headers = req.headers;
+        const value = headers[name] ?? headers[name.toLowerCase()];
+        if (Array.isArray(value))
+            return value[0] ?? null;
+        return value ?? null;
+    }
+    return null;
+}
+function sendJson(res, statusCode, data) {
+    if (typeof res.status === "function" && typeof res.json === "function") {
+        const chained = res.status(statusCode);
+        if (chained && typeof chained.json === "function") {
+            chained.json(data);
+            return;
+        }
+    }
+    if (typeof res.writeHead === "function" && typeof res.end === "function") {
+        res.writeHead(statusCode, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(data));
+        return;
+    }
+    if (typeof res.end === "function") {
+        if (res.statusCode !== undefined)
+            res.statusCode = statusCode;
+        res.end(JSON.stringify(data));
+    }
+}
+async function parseBody(req) {
+    if (req.body !== undefined && req.body !== null) {
+        return req.body;
+    }
+    if (typeof req.on === "function") {
+        const onFn = req.on.bind(req);
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            onFn("data", (chunk) => chunks.push(String(chunk)));
+            onFn("end", () => {
+                try {
+                    resolve(JSON.parse(chunks.join("")));
+                }
+                catch {
+                    reject(new Error("Invalid JSON body"));
+                }
+            });
+            onFn("error", reject);
+        });
+    }
+    throw new Error("Unable to parse request body");
+}
+function createProvider(config) {
+    switch (config.provider) {
+        case "anthropic":
+            return new AnthropicProvider({ apiKey: config.apiKey, model: config.model });
+        case "openai":
+            return new OpenAIProvider({ apiKey: config.apiKey, model: config.model });
+        default:
+            throw new Error(`Unknown provider: ${config.provider}`);
+    }
+}
+export function createAssistant(config) {
+    const provider = createProvider(config);
+    async function chat(req) {
+        if (!req.messages || !Array.isArray(req.messages) || req.messages.length === 0) {
+            throw new Error("messages array is required and must not be empty");
+        }
+        const reply = await provider.chat(req.messages, config.systemPrompt);
+        return { reply };
+    }
+    function handler(opts) {
+        return async (req, res) => {
+            try {
+                if (opts?.apiKey) {
+                    const authHeader = getHeader(req, "Authorization") || getHeader(req, "authorization");
+                    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+                    if (token !== opts.apiKey) {
+                        sendJson(res, 401, { error: "Unauthorized" });
+                        return;
+                    }
+                }
+                let body;
+                try {
+                    body = await parseBody(req);
+                }
+                catch {
+                    sendJson(res, 400, { error: "Invalid request body" });
+                    return;
+                }
+                const { messages } = body;
+                if (!messages || !Array.isArray(messages) || messages.length === 0) {
+                    sendJson(res, 400, { error: "messages array is required and must not be empty" });
+                    return;
+                }
+                try {
+                    const result = await chat({ messages });
+                    sendJson(res, 200, result);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : "LLM request failed";
+                    sendJson(res, 502, { error: message });
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "Internal server error";
+                sendJson(res, 500, { error: message });
+            }
+        };
+    }
+    return { chat, handler };
+}
+//# sourceMappingURL=handler.js.map

package/dist/server/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/server/handler.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -0,0 +1,6 @@
+export { createAssistant } from "./handler";
+export type { AssistantConfig } from "./handler";
+export { AnthropicProvider } from "./providers/anthropic";
+export { OpenAIProvider } from "./providers/openai";
+export type { LLMProvider, ProviderConfig } from "./providers/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,4 @@
+export { createAssistant } from "./handler";
+export { AnthropicProvider } from "./providers/anthropic";
+export { OpenAIProvider } from "./providers/openai";
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/server/providers/anthropic.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../../types";
+import type { LLMProvider, ProviderConfig } from "./types";
+export declare class AnthropicProvider implements LLMProvider {
+    private apiKey;
+    private model;
+    constructor(config: ProviderConfig);
+    chat(messages: Message[], systemPrompt?: string): Promise<string>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/server/providers/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/server/providers/anthropic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,cAAc;IAK5B,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAwCxE"}

package/dist/server/providers/anthropic.js

@@ -0,0 +1,40 @@
+export class AnthropicProvider {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.model = config.model || "claude-sonnet-4-20250514";
+    }
+    async chat(messages, systemPrompt) {
+        const anthropicMessages = messages.map((m) => ({
+            role: m.role === "context" || m.role === "system" ? "user" : m.role,
+            content: m.role === "context" ? `[Context]: ${m.content}` : m.content,
+        }));
+        const body = {
+            model: this.model,
+            max_tokens: 4096,
+            messages: anthropicMessages,
+        };
+        if (systemPrompt) {
+            body.system = systemPrompt;
+        }
+        const response = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Anthropic API error ${response.status}: ${text}`);
+        }
+        const data = await response.json();
+        const textBlock = data.content?.find((block) => block.type === "text");
+        if (!textBlock) {
+            throw new Error("No text content in Anthropic response");
+        }
+        return textBlock.text;
+    }
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/server/providers/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/server/providers/anthropic.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,iBAAiB;IAI5B,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,0BAA0B,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAmB,EAAE,YAAqB;QACnD,MAAM,iBAAiB,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;YAC9E,OAAO,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;SACtE,CAAC,CAAC,CAAC;QAEJ,MAAM,IAAI,GAA4B;YACpC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,iBAAiB;SAC5B,CAAC;QAEF,IAAI,YAAY,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;QAC7B,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,uCAAuC,EAAE;YACpE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;gBACxB,mBAAmB,EAAE,YAAY;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;QACrE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAClC,CAAC,KAAuB,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CACnD,CAAC;QACF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,SAAS,CAAC,IAAI,CAAC;IACxB,CAAC;CACF"}

package/dist/server/providers/openai.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../../types";
+import type { LLMProvider, ProviderConfig } from "./types";
+export declare class OpenAIProvider implements LLMProvider {
+    private apiKey;
+    private model;
+    constructor(config: ProviderConfig);
+    chat(messages: Message[], systemPrompt?: string): Promise<string>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/server/providers/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/server/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,cAAc;IAK5B,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CA0CxE"}

package/dist/server/providers/openai.js

@@ -0,0 +1,46 @@
+export class OpenAIProvider {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.model = config.model || "gpt-4o";
+    }
+    async chat(messages, systemPrompt) {
+        const openaiMessages = [];
+        if (systemPrompt) {
+            openaiMessages.push({ role: "system", content: systemPrompt });
+        }
+        for (const m of messages) {
+            if (m.role === "context") {
+                openaiMessages.push({ role: "user", content: `[Context]: ${m.content}` });
+            }
+            else if (m.role === "system") {
+                openaiMessages.push({ role: "user", content: m.content });
+            }
+            else {
+                openaiMessages.push({ role: m.role, content: m.content });
+            }
+        }
+        const response = await fetch("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.model,
+                messages: openaiMessages,
+                max_tokens: 4096,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`OpenAI API error ${response.status}: ${text}`);
+        }
+        const data = await response.json();
+        const choice = data.choices?.[0];
+        if (!choice?.message?.content) {
+            throw new Error("No content in OpenAI response");
+        }
+        return choice.message.content;
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/server/providers/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../../src/server/providers/openai.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,cAAc;IAIzB,YAAY,MAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAmB,EAAE,YAAqB;QACnD,MAAM,cAAc,GAA6C,EAAE,CAAC;QAEpE,IAAI,YAAY,EAAE,CAAC;YACjB,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACzB,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC5E,CAAC;iBAAM,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC/B,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;iBAAM,CAAC;gBACN,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,4CAA4C,EAAE;YACzE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,cAAc;gBACxB,UAAU,EAAE,IAAI;aACjB,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,oBAAoB,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IAChC,CAAC;CACF"}

package/dist/server/providers/types.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../../types";
+export interface LLMProvider {
+    chat(messages: Message[], systemPrompt?: string): Promise<string>;
+}
+export type ProviderConfig = {
+    apiKey: string;
+    model?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/providers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/server/providers/types.js

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

package/dist/server/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/providers/types.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export type Message = {
+    id?: string;
+    role: "user" | "assistant" | "context" | "system";
+    content: string;
+};
+export type ExplainContext = {
+    modalName?: string;
+    pageName?: string;
+    docsUrls?: string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC"}

package/dist/types.js

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

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@netbirdio/explain",
+  "version": "0.1.0",
+  "description": "Full-stack AI assistant library with React frontend components and Node.js backend handler",
+  "license": "BSD-3-Clause",
+  "main": "./dist/client/index.js",
+  "types": "./dist/client/index.d.ts",
+  "exports": {
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "client": ["./dist/client/index.d.ts"],
+      "server": ["./dist/server/index.d.ts"]
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "lucide-react": ">=0.300.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/netbirdio/explain.git"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/client/AIAssistantProvider.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from "react";
+import type { ExplainContext } from "../types";
+import AIChatBot from "./AIChatBot";
+import AIFloatingButton from "./AIFloatingButton";
+import * as S from "./styles";
+
+type AIAssistantContextType = {
+  openChat: (selectedText?: string) => void;
+  closeChat: () => void;
+  isChatOpen: boolean;
+  explainMode: boolean;
+  enterExplainMode: () => void;
+  exitExplainMode: () => void;
+  setExplainContext: (ctx: ExplainContext) => void;
+  clearExplainContext: () => void;
+};
+
+const AIAssistantContext = createContext<AIAssistantContextType>({
+  openChat: () => {},
+  closeChat: () => {},
+  isChatOpen: false,
+  explainMode: false,
+  enterExplainMode: () => {},
+  exitExplainMode: () => {},
+  setExplainContext: () => {},
+  clearExplainContext: () => {},
+});
+
+export const useAIAssistant = () => useContext(AIAssistantContext);
+
+type AIAssistantProviderProps = {
+  endpoint: string;
+  apiKey?: string;
+  children: React.ReactNode;
+};
+
+/**
+ * Find the closest ancestor (or self) with a data-nb-explain attribute.
+ * Returns null if nothing is explainable.
+ */
+function findExplainable(el: HTMLElement): HTMLElement | null {
+  return el.closest("[data-nb-explain]") as HTMLElement | null;
+}
+
+/**
+ * Extract a short label from an explainable element by looking for
+ * a label, heading, or first bit of text content.
+ */
+function extractLabel(el: HTMLElement): string {
+  const label = el.querySelector("label") as HTMLElement | null;
+  if (label?.innerText?.trim()) return label.innerText.trim();
+
+  const heading = el.querySelector("h1, h2, h3, h4") as HTMLElement | null;
+  if (heading?.innerText?.trim()) return heading.innerText.trim();
+
+  const text = el.innerText?.trim();
+  if (text && text.length <= 80) return text;
+  if (text) return text.slice(0, 80) + "...";
+
+  return "this element";
+}
+
+/**
+ * Look for data-nb-explain-docs on the element or its ancestors.
+ * Returns an array of documentation URLs, or an empty array.
+ */
+function findExplainDocs(el: HTMLElement): string[] {
+  const withDocs = el.closest("[data-nb-explain-docs]") as HTMLElement | null;
+  if (!withDocs) return [];
+
+  const raw = withDocs.getAttribute("data-nb-explain-docs") || "";
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+  } catch {
+    // If not valid JSON, treat as a single URL
+    if (raw.trim()) return [raw.trim()];
+  }
+  return [];
+}
+
+function buildQuery(
+  label: string,
+  ctx: ExplainContext | null,
+  elementDocs: string[],
+): string {
+  let userMessage = `Explain "${label}"`;
+  if (ctx) {
+    if (ctx.modalName) userMessage += ` on ${ctx.modalName} modal`;
+    if (ctx.pageName) userMessage += ` in ${ctx.pageName}`;
+  }
+
+  // Merge docs from context and element attribute
+  const allDocs = [
+    ...(ctx?.docsUrls || []),
+    ...elementDocs,
+  ];
+  // Deduplicate
+  const uniqueDocs = [...new Set(allDocs)];
+
+  const parts = [userMessage];
+  if (uniqueDocs.length > 0) {
+    parts.push(`Docs: ${uniqueDocs.join(", ")}`);
+  }
+  return parts.join("\n");
+}
+
+export default function AIAssistantProvider({
+  endpoint,
+  apiKey,
+  children,
+}: AIAssistantProviderProps) {
+  const [isChatOpen, setIsChatOpen] = useState(false);
+  const [initialQuery, setInitialQuery] = useState("");
+  const [explainMode, setExplainMode] = useState(false);
+  const [hoveredEl, setHoveredEl] = useState<HTMLElement | null>(null);
+  const [explainCtx, setExplainCtx] = useState<ExplainContext | null>(null);
+
+  const openChat = useCallback((selectedText?: string) => {
+    setInitialQuery(selectedText || "");
+    setIsChatOpen(true);
+    setExplainMode(false);
+    setHoveredEl(null);
+  }, []);
+
+  const closeChat = useCallback(() => {
+    setIsChatOpen(false);
+    setInitialQuery("");
+  }, []);
+
+  const enterExplainMode = useCallback(() => {
+    setExplainMode(true);
+  }, []);
+
+  const exitExplainMode = useCallback(() => {
+    setExplainMode(false);
+    setHoveredEl(null);
+  }, []);
+
+  const setExplainContext = useCallback((ctx: ExplainContext) => {
+    setExplainCtx(ctx);
+  }, []);
+
+  const clearExplainContext = useCallback(() => {
+    setExplainCtx(null);
+  }, []);
+
+  // Explain mode: highlight explainable elements on hover, open chat on click
+  useEffect(() => {
+    if (!explainMode) return;
+
+    const handleMouseOver = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (
+        target.closest("[data-nb-explain-ignore]") ||
+        target.closest("[data-nb-explain-banner]")
+      )
+        return;
+      const explainable = findExplainable(target);
+      setHoveredEl(explainable);
+    };
+
+    const handleMouseOut = () => {
+      setHoveredEl(null);
+    };
+
+    const handleClick = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (
+        target.closest("[data-nb-explain-ignore]") ||
+        target.closest("[data-nb-explain-banner]")
+      )
+        return;
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      const explainable = findExplainable(target);
+      if (!explainable) return;
+
+      const attrValue = explainable.getAttribute("data-nb-explain") || "";
+      const label =
+        attrValue && attrValue !== "true"
+          ? attrValue
+          : extractLabel(explainable);
+
+      const elementDocs = findExplainDocs(explainable);
+      const query = buildQuery(label, explainCtx, elementDocs);
+      openChat(query);
+    };
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        exitExplainMode();
+      }
+    };
+
+    document.addEventListener("mouseover", handleMouseOver, true);
+    document.addEventListener("mouseout", handleMouseOut, true);
+    document.addEventListener("click", handleClick, true);
+    document.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      document.removeEventListener("mouseover", handleMouseOver, true);
+      document.removeEventListener("mouseout", handleMouseOut, true);
+      document.removeEventListener("click", handleClick, true);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [explainMode, explainCtx, openChat, exitExplainMode]);
+
+  // Apply/remove highlight on hovered explainable element via CSS class
+  useEffect(() => {
+    if (!hoveredEl) return;
+    hoveredEl.setAttribute("data-nb-explain-highlight", "");
+    return () => {
+      hoveredEl.removeAttribute("data-nb-explain-highlight");
+    };
+  }, [hoveredEl]);
+
+  // Force-remove all highlights when leaving explain mode
+  useEffect(() => {
+    if (!explainMode) {
+      document.querySelectorAll("[data-nb-explain-highlight]").forEach((el) => {
+        el.removeAttribute("data-nb-explain-highlight");
+      });
+    }
+  }, [explainMode]);
+
+  return (
+    <AIAssistantContext.Provider
+      value={{
+        openChat,
+        closeChat,
+        isChatOpen,
+        explainMode,
+        enterExplainMode,
+        exitExplainMode,
+        setExplainContext,
+        clearExplainContext,
+      }}
+    >
+      {/* Inject CSS custom properties, animations, and highlight styles */}
+      <style>{S.CSS_VARS + S.ANIMATIONS + S.HIGHLIGHT_STYLES}</style>
+
+      {children}
+
+      {/* Explain mode banner */}
+      {explainMode && (
+        <div data-nb-explain-banner style={S.banner}>
+          <span>Click on a highlighted element to explain it</span>
+          <button
+            onClick={() => exitExplainMode()}
+            style={S.bannerCancel}
+          >
+            Cancel
+          </button>
+        </div>
+      )}
+
+      <AIFloatingButton
+        isOpen={isChatOpen}
+        onClick={() => {
+          if (isChatOpen) {
+            closeChat();
+          } else {
+            openChat();
+          }
+        }}
+      />
+
+      <AIChatBot
+        open={isChatOpen}
+        onClose={closeChat}
+        initialQuery={initialQuery}
+        endpoint={endpoint}
+        apiKey={apiKey}
+      />
+    </AIAssistantContext.Provider>
+  );
+}