llm-agent-runtime 0.1.6 → 0.1.16

package/dist/intents/define.d.ts

@@ -0,0 +1,35 @@
+import type { IntentBinding, IntentDefinition, IntentRegistry } from "../types.js";
+import { type WithGeneralIntentOptions } from "./general.js";
+/**
+ * One object for both routing (`name` / `examples` / …) and execution (`prompt` / `tools`).
+ * Use with {@link defineIntents} or {@link withGeneralIntents}.
+ */
+export type UnifiedIntent<TContext = unknown> = IntentDefinition & IntentBinding<TContext>;
+/**
+ * Split unified intent objects into the two lists `createAgentRuntime` expects.
+ *
+ * @example
+ * ```ts
+ * const { intents, intentRegistry } = defineIntents([
+ *   {
+ *     name: "qa",
+ *     examples: ["what is", "how do I"],
+ *     description: "answer from docs",
+ *     prompt: () => "Answer from knowledge.",
+ *     tools: () => [],
+ *   },
+ * ]);
+ * ```
+ */
+export declare function defineIntents<TContext = unknown>(items: UnifiedIntent<TContext>[]): {
+    intents: IntentDefinition[];
+    intentRegistry: IntentRegistry<TContext>;
+};
+/**
+ * Same as {@link defineIntents}, then prepends the optional general catch-all intent.
+ */
+export declare function withGeneralIntents<TContext = unknown>(items: UnifiedIntent<TContext>[], options?: WithGeneralIntentOptions<TContext>): {
+    intents: IntentDefinition[];
+    intentRegistry: IntentRegistry<TContext>;
+};
+//# sourceMappingURL=define.d.ts.map

package/dist/intents/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/intents/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,GAAG,OAAO,IAAI,gBAAgB,GAC9D,aAAa,CAAC,QAAQ,CAAC,CAAC;AAE1B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAG,OAAO,EAC9C,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,GAC/B;IACD,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;CAC1C,CAgCA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EACnD,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,EAChC,OAAO,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC3C;IACD,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;CAC1C,CAGA"}

package/dist/intents/define.js

@@ -0,0 +1,52 @@
+import { withGeneralIntent } from "./general.js";
+/**
+ * Split unified intent objects into the two lists `createAgentRuntime` expects.
+ *
+ * @example
+ * ```ts
+ * const { intents, intentRegistry } = defineIntents([
+ *   {
+ *     name: "qa",
+ *     examples: ["what is", "how do I"],
+ *     description: "answer from docs",
+ *     prompt: () => "Answer from knowledge.",
+ *     tools: () => [],
+ *   },
+ * ]);
+ * ```
+ */
+export function defineIntents(items) {
+    const intents = [];
+    const intentRegistry = {};
+    for (const item of items) {
+        const { prompt, tools, name, examples, sticky, description, regex } = item;
+        if (!name?.trim()) {
+            throw new Error("defineIntents: each intent needs a non-empty name");
+        }
+        if (!Array.isArray(examples)) {
+            throw new Error(`defineIntents: intent "${name}" needs an examples array`);
+        }
+        if (typeof prompt !== "function" || typeof tools !== "function") {
+            throw new Error(`defineIntents: intent "${name}" needs prompt() and tools() functions`);
+        }
+        if (intentRegistry[name]) {
+            throw new Error(`defineIntents: duplicate intent name "${name}"`);
+        }
+        intents.push({
+            name,
+            examples,
+            ...(sticky !== undefined ? { sticky } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(regex !== undefined ? { regex } : {}),
+        });
+        intentRegistry[name] = { prompt, tools };
+    }
+    return { intents, intentRegistry };
+}
+/**
+ * Same as {@link defineIntents}, then prepends the optional general catch-all intent.
+ */
+export function withGeneralIntents(items, options) {
+    const split = defineIntents(items);
+    return withGeneralIntent(split.intents, split.intentRegistry, options);
+}

package/dist/intents/general.d.ts

@@ -0,0 +1,37 @@
+import type { IntentBinding, IntentDefinition, IntentRegistry, PromptContext } from "../types.js";
+/** Default catch-all intent name (Xel uses `greetings` the same way). */
+export declare const GENERAL_INTENT_NAME = "general";
+/**
+ * Optional catch-all intent (first in catalog, used as fallback).
+ * Not required — apps that already define `greetings` / `general` can skip this.
+ */
+export declare function createGeneralIntent(overrides?: Partial<IntentDefinition>): IntentDefinition;
+/**
+ * Default prompt + empty tools for the general intent.
+ * Pass your own `prompt` / `tools` when you want a richer menu.
+ */
+export declare function createGeneralIntentBinding<TContext = unknown>(options?: {
+    prompt?: (ctx: PromptContext<TContext>) => string;
+    tools?: IntentBinding<TContext>["tools"];
+}): IntentBinding<TContext>;
+export type WithGeneralIntentOptions<TContext = unknown> = {
+    /** Override the general intent definition (e.g. `name: "greetings"` to match Xel). */
+    intent?: Partial<IntentDefinition>;
+    /** Prompt / tools for the general registry entry. */
+    binding?: {
+        prompt?: (ctx: PromptContext<TContext>) => string;
+        tools?: IntentBinding<TContext>["tools"];
+    };
+};
+/**
+ * Prepend a general intent if missing, and merge its registry binding.
+ * Does nothing when an intent with the same name already exists.
+ *
+ * This is a **catch-all routing intent**, not shared style rules.
+ * For rules that apply to every intent, use `sharedPrompt` on `createAgentRuntime`.
+ */
+export declare function withGeneralIntent<TContext = unknown>(intents: IntentDefinition[], registry: IntentRegistry<TContext>, options?: WithGeneralIntentOptions<TContext>): {
+    intents: IntentDefinition[];
+    intentRegistry: IntentRegistry<TContext>;
+};
+//# sourceMappingURL=general.d.ts.map

package/dist/intents/general.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"general.d.ts","sourceRoot":"","sources":["../../src/intents/general.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAErB,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAkB7C;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,gBAAgB,CAUlB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE;IACvE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC;IAClD,KAAK,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;CAC1C,GAAG,aAAa,CAAC,QAAQ,CAAC,CAgB1B;AAED,MAAM,MAAM,wBAAwB,CAAC,QAAQ,GAAG,OAAO,IAAI;IACzD,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,qDAAqD;IACrD,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC;QAClD,KAAK,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;KAC1C,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAClD,OAAO,EAAE,gBAAgB,EAAE,EAC3B,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAClC,OAAO,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC3C;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,cAAc,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;CAAE,CAa3E"}

package/dist/intents/general.js

@@ -0,0 +1,67 @@
+/** Default catch-all intent name (Xel uses `greetings` the same way). */
+export const GENERAL_INTENT_NAME = "general";
+const DEFAULT_GENERAL_EXAMPLES = [
+    "hello",
+    "hi",
+    "hey",
+    "how are you",
+    "good morning",
+    "good afternoon",
+    "good evening",
+    "thanks",
+    "thank you",
+    "what can you do",
+    "help",
+    "menu",
+    "show me the menu",
+];
+/**
+ * Optional catch-all intent (first in catalog, used as fallback).
+ * Not required — apps that already define `greetings` / `general` can skip this.
+ */
+export function createGeneralIntent(overrides) {
+    return {
+        name: overrides?.name ?? GENERAL_INTENT_NAME,
+        examples: overrides?.examples ?? DEFAULT_GENERAL_EXAMPLES,
+        description: overrides?.description ??
+            "general chat, greetings, small talk, help, menu, or unclear requests",
+        sticky: overrides?.sticky,
+        regex: overrides?.regex,
+    };
+}
+/**
+ * Default prompt + empty tools for the general intent.
+ * Pass your own `prompt` / `tools` when you want a richer menu.
+ */
+export function createGeneralIntentBinding(options) {
+    return {
+        prompt: options?.prompt ??
+            ((ctx) => {
+                const data = ctx.context;
+                const name = typeof data?.contactName === "string" ? data.contactName : "there";
+                return (`You are a friendly general assistant. Greet ${name} warmly when appropriate. ` +
+                    `Answer simple questions, explain what you can help with, and guide the user to the right flow. ` +
+                    `Keep replies concise.`);
+            }),
+        tools: options?.tools ?? (() => []),
+    };
+}
+/**
+ * Prepend a general intent if missing, and merge its registry binding.
+ * Does nothing when an intent with the same name already exists.
+ *
+ * This is a **catch-all routing intent**, not shared style rules.
+ * For rules that apply to every intent, use `sharedPrompt` on `createAgentRuntime`.
+ */
+export function withGeneralIntent(intents, registry, options) {
+    const general = createGeneralIntent(options?.intent);
+    const already = intents.some((i) => i.name === general.name);
+    const nextIntents = already ? intents : [general, ...intents];
+    const nextRegistry = already
+        ? registry
+        : {
+            [general.name]: createGeneralIntentBinding(options?.binding),
+            ...registry,
+        };
+    return { intents: nextIntents, intentRegistry: nextRegistry };
+}

package/dist/llm.d.ts

@@ -1,13 +1,13 @@
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import type { Embeddings } from "@langchain/core/embeddings";
-import type { LlmConfig, LlmProvider } from "./types.js";
+import type { EmbeddingsProvider, LlmConfig, LlmProvider } from "./types.js";
 export type CreatedModels = {
     chat: BaseChatModel;
     intentRouter: BaseChatModel;
     embeddings: Embeddings;
     config: {
         provider: LlmProvider;
-        embeddingsProvider: LlmProvider;
+        embeddingsProvider: EmbeddingsProvider;
         model: string;
         intentRouterModel: string;
         embeddingsModel: string;

package/dist/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoBzD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,EAAE,aAAa,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE;QACN,QAAQ,EAAE,WAAW,CAAC;QACtB,kBAAkB,EAAE,WAAW,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CA8E1D"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAI7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAuC7E,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,EAAE,aAAa,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE;QACN,QAAQ,EAAE,WAAW,CAAC;QACtB,kBAAkB,EAAE,kBAAkB,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CA8F1D"}

package/dist/llm.js

@@ -1,21 +1,40 @@
 import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
 import { ChatOllama, OllamaEmbeddings } from "@langchain/ollama";
-const normalizeProvider = (value) => {
+import { XenovaEmbeddings } from "./embeddings/xenova.js";
+const normalizeChatProvider = (value) => {
     const normalized = value?.trim().toLowerCase();
     if (normalized === "openai" ||
         normalized === "gpt" ||
         normalized === "chatgpt") {
         return "openai";
     }
-    if (normalized === "openrouter" ||
-        normalized === "or") {
+    if (normalized === "openrouter" || normalized === "or") {
         return "openrouter";
     }
     return "ollama";
 };
+const normalizeEmbeddingsProvider = (value, chatProvider) => {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "openai" || normalized === "gpt")
+        return "openai";
+    if (normalized === "ollama")
+        return "ollama";
+    if (normalized === "xenova" ||
+        normalized === "transformers" ||
+        normalized === "local") {
+        return "xenova";
+    }
+    if (normalized === "openrouter")
+        return "xenova";
+    // Unset on LlmConfig: same rule as env — non-ollama chat → xenova.
+    if (!value) {
+        return chatProvider === "ollama" ? "ollama" : "xenova";
+    }
+    return chatProvider === "ollama" ? "ollama" : "xenova";
+};
 export function createModels(llm) {
-    const provider = normalizeProvider(llm.provider);
-    const embeddingsProvider = normalizeProvider(llm.embeddingsProvider ?? llm.provider);
+    const provider = normalizeChatProvider(llm.provider);
+    const embeddingsProvider = normalizeEmbeddingsProvider(llm.embeddingsProvider, provider);
     const temperature = llm.temperature ?? 0;
     const createChat = (modelName) => {
         if (provider === "openai") {
@@ -36,6 +55,8 @@ export function createModels(llm) {
                 model: modelName,
                 temperature,
                 apiKey: llm.apiKey,
+                timeout: 60_000,
+                maxRetries: 2,
                 configuration: {
                     baseURL: llm.baseUrl ?? "https://openrouter.ai/api/v1",
                 },
@@ -47,26 +68,35 @@ export function createModels(llm) {
             baseUrl: llm.baseUrl,
         });
     };
+    const embeddingsModelName = llm.embeddingsModel ??
+        (embeddingsProvider === "openai"
+            ? "text-embedding-3-small"
+            : embeddingsProvider === "xenova"
+                ? "Xenova/all-MiniLM-L6-v2"
+                : "mxbai-embed-large:latest");
     const createEmbeddings = () => {
         if (embeddingsProvider === "openai") {
-            if (!llm.apiKey) {
-                throw new Error("llm.apiKey is required when embeddingsProvider is openai.");
+            const embeddingsApiKey = llm.embeddingsApiKey ?? llm.apiKey;
+            if (!embeddingsApiKey) {
+                throw new Error("llm.embeddingsApiKey (or llm.apiKey) is required when embeddingsProvider is openai.");
             }
             return new OpenAIEmbeddings({
-                model: llm.embeddingsModel ?? "text-embedding-3-small",
-                apiKey: llm.apiKey,
+                model: embeddingsModelName,
+                apiKey: embeddingsApiKey,
             });
         }
+        if (embeddingsProvider === "xenova") {
+            return new XenovaEmbeddings({ model: embeddingsModelName });
+        }
+        const ollamaBaseUrl = llm.embeddingsBaseUrl ??
+            (provider === "ollama" ? llm.baseUrl : undefined) ??
+            "http://localhost:11434";
         return new OllamaEmbeddings({
-            model: llm.embeddingsModel ?? "mxbai-embed-large:latest",
-            baseUrl: llm.baseUrl,
+            model: embeddingsModelName,
+            baseUrl: ollamaBaseUrl,
         });
     };
     const intentRouterModelName = llm.intentRouterModel ?? llm.model;
-    const embeddingsModelName = llm.embeddingsModel ??
-        (embeddingsProvider === "openai"
-            ? "text-embedding-3-small"
-            : "mxbai-embed-large:latest");
     return {
         chat: createChat(llm.model),
         intentRouter: createChat(intentRouterModelName),

package/dist/rag/index.d.ts

@@ -0,0 +1,67 @@
+import type { Embeddings } from "@langchain/core/embeddings";
+import { loadRagDocuments, loadRagDocument, type LoadedRagDocument } from "./loaders.js";
+import { ragSourcesFromEnv, resolveRagSources, resolveRagSource, isHttpUrl, type ResolvedRagSource, type RagSourceKind } from "./sources.js";
+export type { LoadedRagDocument, ResolvedRagSource, RagSourceKind };
+export { loadRagDocuments, loadRagDocument, ragSourcesFromEnv, resolveRagSources, resolveRagSource, isHttpUrl, };
+export type RagChunk = {
+    id: string;
+    source: string;
+    text: string;
+    embedding: number[];
+};
+export type SimpleRagStore = {
+    chunks: RagChunk[];
+    retrieve: (query: string, topK?: number) => Promise<string>;
+};
+/**
+ * Build an in-memory RAG store from loaded documents + any Embeddings backend
+ * (xenova / ollama / openai).
+ */
+export declare function createSimpleRagStore(options: {
+    documents: LoadedRagDocument[];
+    embeddings: Embeddings;
+    chunkSize?: number;
+    overlap?: number;
+}): Promise<SimpleRagStore>;
+/**
+ * Resolve + load + index RAG sources (local paths and/or http(s) PDF/DOCX URLs).
+ */
+export declare function createSimpleRagFromSources(options: {
+    sources: string[];
+    embeddings: Embeddings;
+    chunkSize?: number;
+    overlap?: number;
+}): Promise<{
+    resolved: ResolvedRagSource[];
+    documents: LoadedRagDocument[];
+    store: SimpleRagStore;
+}>;
+/** Same as createSimpleRagFromSources, reading RAG_SOURCES / RAG_PDF_* / RAG_DOC_URLS. */
+export declare function createSimpleRagFromEnv(options: {
+    embeddings: Embeddings;
+    env?: NodeJS.ProcessEnv;
+    chunkSize?: number;
+    overlap?: number;
+}): Promise<{
+    resolved: ResolvedRagSource[];
+    documents: LoadedRagDocument[];
+    store: SimpleRagStore;
+}>;
+export type GetRagStoreOptions = {
+    /** Defaults to embeddings from `llmConfigFromEnv()` / `createModels()`. */
+    embeddings?: Embeddings;
+    env?: NodeJS.ProcessEnv;
+    chunkSize?: number;
+    overlap?: number;
+    /** Log `[rag] indexed N document(s)` (default true). */
+    log?: boolean;
+};
+/**
+ * Lazy singleton RAG store from `RAG_SOURCES` (path and/or URL).
+ * Apps do not need their own `rag/store.ts` — call this, then `store.retrieve(message)`.
+ */
+export declare function getRagStore(options?: GetRagStoreOptions): Promise<SimpleRagStore>;
+export declare function getRagDocumentCount(): number;
+/** Clear the singleton (tests / re-index). Next `getRagStore()` rebuilds. */
+export declare function resetRagStore(): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAC;AACpE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,GACV,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D,CAAC;AAgCF;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,cAAc,CAAC,CAkC1B;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC;IACV,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB,CAAC,CAUD;AAED,0FAA0F;AAC1F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;cArBW,iBAAiB,EAAE;eAClB,iBAAiB,EAAE;WACvB,cAAc;GAgCtB;AAKD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,2BA+B3D;AAED,wBAAgB,mBAAmB,WAElC;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,SAG5B"}

package/dist/rag/index.js

@@ -0,0 +1,138 @@
+import { llmConfigFromEnv } from "../env-llm.js";
+import { createModels } from "../llm.js";
+import { loadRagDocuments, loadRagDocument, } from "./loaders.js";
+import { ragSourcesFromEnv, resolveRagSources, resolveRagSource, isHttpUrl, } from "./sources.js";
+export { loadRagDocuments, loadRagDocument, ragSourcesFromEnv, resolveRagSources, resolveRagSource, isHttpUrl, };
+function chunkText(text, chunkSize = 800, overlap = 120) {
+    const cleaned = text.replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return [];
+    if (cleaned.length <= chunkSize)
+        return [cleaned];
+    const chunks = [];
+    let start = 0;
+    while (start < cleaned.length) {
+        const end = Math.min(start + chunkSize, cleaned.length);
+        chunks.push(cleaned.slice(start, end));
+        if (end >= cleaned.length)
+            break;
+        start = Math.max(0, end - overlap);
+    }
+    return chunks;
+}
+function cosine(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    if (!magA || !magB)
+        return 0;
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+/**
+ * Build an in-memory RAG store from loaded documents + any Embeddings backend
+ * (xenova / ollama / openai).
+ */
+export async function createSimpleRagStore(options) {
+    const chunks = [];
+    let i = 0;
+    for (const doc of options.documents) {
+        const parts = chunkText(doc.text, options.chunkSize ?? 800, options.overlap ?? 120);
+        for (const part of parts) {
+            const embedding = await options.embeddings.embedQuery(part);
+            chunks.push({
+                id: `${i++}`,
+                source: doc.source,
+                text: part,
+                embedding,
+            });
+        }
+    }
+    return {
+        chunks,
+        retrieve: async (query, topK = 4) => {
+            if (!chunks.length)
+                return "";
+            const q = await options.embeddings.embedQuery(query);
+            return chunks
+                .map((c) => ({ c, score: cosine(q, c.embedding) }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, topK)
+                .map(({ c }) => `[${c.source}]\n${c.text}`)
+                .join("\n---\n");
+        },
+    };
+}
+/**
+ * Resolve + load + index RAG sources (local paths and/or http(s) PDF/DOCX URLs).
+ */
+export async function createSimpleRagFromSources(options) {
+    const resolved = await resolveRagSources(options.sources);
+    const documents = await loadRagDocuments(resolved);
+    const store = await createSimpleRagStore({
+        documents,
+        embeddings: options.embeddings,
+        chunkSize: options.chunkSize,
+        overlap: options.overlap,
+    });
+    return { resolved, documents, store };
+}
+/** Same as createSimpleRagFromSources, reading RAG_SOURCES / RAG_PDF_* / RAG_DOC_URLS. */
+export async function createSimpleRagFromEnv(options) {
+    const sources = ragSourcesFromEnv(options.env ?? process.env);
+    if (!sources.length) {
+        throw new Error("No RAG sources configured. Set RAG_SOURCES=/path/a.pdf,https://example.com/b.docx");
+    }
+    return createSimpleRagFromSources({
+        sources,
+        embeddings: options.embeddings,
+        chunkSize: options.chunkSize,
+        overlap: options.overlap,
+    });
+}
+let storePromise = null;
+let documentCount = 0;
+/**
+ * Lazy singleton RAG store from `RAG_SOURCES` (path and/or URL).
+ * Apps do not need their own `rag/store.ts` — call this, then `store.retrieve(message)`.
+ */
+export function getRagStore(options = {}) {
+    if (!storePromise) {
+        storePromise = (async () => {
+            const embeddings = options.embeddings ?? createModels(llmConfigFromEnv()).embeddings;
+            const { store, documents } = await createSimpleRagFromEnv({
+                embeddings,
+                env: options.env,
+                chunkSize: options.chunkSize,
+                overlap: options.overlap,
+            });
+            if (!documents.length) {
+                throw new Error("RAG sources were configured but none could be loaded. Check file paths and PDF/DOCX parsers.");
+            }
+            documentCount = documents.length;
+            if (options.log !== false) {
+                console.log(`[rag] indexed ${documents.length} document(s) from RAG_SOURCES`);
+            }
+            return store;
+        })().catch((err) => {
+            // Allow the next getRagStore() call to retry after a failed index.
+            storePromise = null;
+            documentCount = 0;
+            throw err;
+        });
+    }
+    return storePromise;
+}
+export function getRagDocumentCount() {
+    return documentCount;
+}
+/** Clear the singleton (tests / re-index). Next `getRagStore()` rebuilds. */
+export function resetRagStore() {
+    storePromise = null;
+    documentCount = 0;
+}

package/dist/rag/loaders.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedRagSource } from "./sources.js";
+export type LoadedRagDocument = {
+    source: string;
+    text: string;
+};
+/**
+ * Extract plain text from a resolved PDF / DOCX / TXT source.
+ */
+export declare function loadRagDocument(resolved: ResolvedRagSource): Promise<LoadedRagDocument>;
+export declare function loadRagDocuments(resolved: ResolvedRagSource[]): Promise<LoadedRagDocument[]>;
+//# sourceMappingURL=loaders.d.ts.map

package/dist/rag/loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.d.ts","sourceRoot":"","sources":["../../src/rag/loaders.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAiDF;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAsB5B;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiB9B"}

package/dist/rag/loaders.js

@@ -0,0 +1,80 @@
+import { createRequire } from "node:module";
+import fs from "node:fs/promises";
+const require = createRequire(import.meta.url);
+function loadPdfParse() {
+    try {
+        // Prefer CJS require — ESM `import("pdf-parse")` is flaky with pdf.js (bad XRef).
+        const mod = require("pdf-parse");
+        if (typeof mod === "function")
+            return mod;
+        if (typeof mod?.default === "function")
+            return mod.default;
+        throw new Error("pdf-parse export missing");
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === "pdf-parse export missing") {
+            throw err;
+        }
+        throw new Error("PDF RAG requires pdf-parse. Install with: pnpm add pdf-parse");
+    }
+}
+async function loadPdf(localPath) {
+    const pdfParse = loadPdfParse();
+    const data = await fs.readFile(localPath);
+    const parsed = await pdfParse(data);
+    return parsed.text ?? "";
+}
+async function loadDocx(localPath) {
+    let mammoth;
+    try {
+        mammoth = await import("mammoth");
+    }
+    catch {
+        throw new Error('DOCX RAG requires mammoth. Install with: pnpm add mammoth');
+    }
+    const result = await mammoth.extractRawText({ path: localPath });
+    return result.value ?? "";
+}
+async function loadText(localPath) {
+    return fs.readFile(localPath, "utf8");
+}
+/**
+ * Extract plain text from a resolved PDF / DOCX / TXT source.
+ */
+export async function loadRagDocument(resolved) {
+    let text;
+    switch (resolved.kind) {
+        case "pdf":
+            text = await loadPdf(resolved.localPath);
+            break;
+        case "docx":
+            text = await loadDocx(resolved.localPath);
+            break;
+        case "txt":
+            text = await loadText(resolved.localPath);
+            break;
+        default:
+            throw new Error(`Unsupported RAG file type for ${resolved.source} (use .pdf, .docx, .txt, .md)`);
+    }
+    return {
+        source: resolved.source,
+        text: text.replace(/\u0000/g, "").trim(),
+    };
+}
+export async function loadRagDocuments(resolved) {
+    const docs = [];
+    for (const item of resolved) {
+        try {
+            const doc = await loadRagDocument(item);
+            if (doc.text)
+                docs.push(doc);
+            else {
+                console.warn(`[rag] skipped empty document: ${item.source}`);
+            }
+        }
+        catch (err) {
+            console.warn(`[rag] skipped unreadable source: ${item.source}`, err instanceof Error ? err.message : err);
+        }
+    }
+    return docs;
+}

package/dist/rag/sources.d.ts

@@ -0,0 +1,29 @@
+export type RagSourceKind = "pdf" | "docx" | "txt" | "unknown";
+export type ResolvedRagSource = {
+    /** Original path or URL from config. */
+    source: string;
+    /** Local file path after download (URL) or as given (path). */
+    localPath: string;
+    kind: RagSourceKind;
+    /** True when we downloaded a remote file into a temp location. */
+    isTemp: boolean;
+};
+export declare function isHttpUrl(value: string): boolean;
+/**
+ * Collect RAG sources from env.
+ *
+ * Preferred:
+ *   RAG_SOURCES=/path/a.pdf,https://cdn.example.com/b.docx
+ *
+ * Also accepted:
+ *   RAG_PDF_PATH=/one.pdf
+ *   RAG_PDF_PATHS=/a.pdf,/b.pdf
+ *   RAG_DOC_URLS=https://.../a.pdf,https://.../b.docx
+ */
+export declare function ragSourcesFromEnv(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Resolve a single source (local path or http(s) URL) to a local file.
+ */
+export declare function resolveRagSource(source: string): Promise<ResolvedRagSource>;
+export declare function resolveRagSources(sources: string[]): Promise<ResolvedRagSource[]>;
+//# sourceMappingURL=sources.d.ts.map

package/dist/rag/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/rag/sources.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,aAAa,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAUF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAiBV;AAwBD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,CAAC,CA6B5B;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAM9B"}