lmgrep 0.1.17 → 0.2.0

package/dist/infrastructure/ai/AiSdkEmbedder.js

@@ -0,0 +1,79 @@
+import { createProviderRegistry, embed, embedMany, } from "ai";
+import { Vector } from "../../domain/corpus/Vector.js";
+import { ModelReference, ProviderRegistry } from "./ProviderRegistry.js";
+/**
+ * Embeddings via the Vercel AI SDK.
+ *
+ * Documents and queries take different prefixes because asymmetric models
+ * (nomic, e5, bge) are trained to expect them; omitting them degrades recall
+ * without any visible error, so the distinction is enforced by having two
+ * methods rather than one with a flag.
+ */
+export class AiSdkEmbedder {
+    config;
+    providers;
+    model;
+    dimensionsChecked = false;
+    constructor(config, providers = new ProviderRegistry()) {
+        this.config = config;
+        this.providers = providers;
+    }
+    async embedDocuments(texts) {
+        const model = await this.getModel();
+        const prefix = this.config.documentPrefix ?? "";
+        const out = [];
+        // Sub-batch to the configured size: providers reject oversized requests,
+        // and a local server will happily OOM on one.
+        for (let i = 0; i < texts.length; i += this.config.batchSize) {
+            const batch = texts.slice(i, i + this.config.batchSize);
+            const values = prefix ? batch.map((t) => prefix + t) : batch;
+            const { embeddings } = await embedMany({ model, values });
+            if (embeddings.length > 0)
+                this.verifyDimensions(embeddings[0]);
+            for (const e of embeddings)
+                out.push(Vector.from(e));
+        }
+        return out;
+    }
+    async embedQuery(query) {
+        const model = await this.getModel();
+        const prefix = this.config.queryPrefix ?? "";
+        const { embedding } = await embed({ model, value: prefix + query });
+        this.verifyDimensions(embedding);
+        return Vector.from(embedding);
+    }
+    /**
+     * Check the configured width once, on the first embedding seen. A mismatch
+     * means the model is not the one the config describes, and every vector
+     * after this would be silently unusable against the index.
+     */
+    verifyDimensions(vector) {
+        if (this.dimensionsChecked)
+            return;
+        this.dimensionsChecked = true;
+        if (this.config.dimensions != null &&
+            vector.length !== this.config.dimensions) {
+            throw new Error(`Embedding dimension mismatch: expected ${this.config.dimensions}, ` +
+                `got ${vector.length}. Check your model and config.dimensions.`);
+        }
+    }
+    async getModel() {
+        if (this.model)
+            return this.model;
+        const reference = ModelReference.parse(this.config.model, "Model");
+        const instance = await this.providers.instantiate({
+            reference,
+            packageName: this.config.provider,
+            baseURL: this.config.baseURL,
+            // Historically the embedding path only falls back to the factory
+            // when there is no default export; see ProviderRequest.
+            preferFactoryWhenBaseUrlSet: false,
+        });
+        const registry = createProviderRegistry({
+            [reference.provider]: instance,
+        });
+        this.model = registry.embeddingModel(reference.full);
+        return this.model;
+    }
+}
+//# sourceMappingURL=AiSdkEmbedder.js.map

package/dist/infrastructure/ai/AiSdkEmbedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AiSdkEmbedder.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/AiSdkEmbedder.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,sBAAsB,EAEtB,KAAK,EACL,SAAS,GACT,MAAM,IAAI,CAAC;AAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAEvD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IAKP;IACA;IALV,KAAK,CAA6B;IAClC,iBAAiB,GAAG,KAAK,CAAC;IAElC,YACkB,MAAoB,EACpB,YAA8B,IAAI,gBAAgB,EAAE;QADpD,WAAM,GAAN,MAAM,CAAc;QACpB,cAAS,GAAT,SAAS,CAA2C;IACnE,CAAC;IAEJ,KAAK,CAAC,cAAc,CAAC,KAAe;QACnC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;QAChD,MAAM,GAAG,GAAa,EAAE,CAAC;QAEzB,yEAAyE;QACzE,8CAA8C;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACxD,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7D,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;YAChE,KAAK,MAAM,CAAC,IAAI,UAAU;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,GAAG,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAa;QAC7B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;QAC7C,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACK,gBAAgB,CAAC,MAAgB;QACxC,IAAI,IAAI,CAAC,iBAAiB;YAAE,OAAO;QACnC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC9B,IACC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI;YAC9B,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,UAAU,EACvC,CAAC;YACF,MAAM,IAAI,KAAK,CACd,0CAA0C,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI;gBACnE,OAAO,MAAM,CAAC,MAAM,2CAA2C,CAChE,CAAC;QACH,CAAC;IACF,CAAC;IAEO,KAAK,CAAC,QAAQ;QACrB,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAElC,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;YACjD,SAAS;YACT,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YACjC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,iEAAiE;YACjE,wDAAwD;YACxD,2BAA2B,EAAE,KAAK;SAClC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,sBAAsB,CAAC;YACvC,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ;SACL,CAAC,CAAC;QAE5B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,cAAc,CACnC,SAAS,CAAC,IAA6B,CACrB,CAAC;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;CACD"}

package/dist/infrastructure/ai/EmbeddingPrefixes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Query and document prefixes required by asymmetric embedding models.
+ *
+ * These models are trained with the prefixes present, and omitting them
+ * degrades retrieval without producing any error — the vectors are still
+ * valid, just worse. Nobody discovers that from the tool; they discover it
+ * from the model card, if at all. Setting them at `init` time is the only
+ * point where the model is actually known.
+ *
+ * Deliberately short: it covers only families whose prefixes are documented
+ * and unambiguous. An unrecognized model gets none, which is the safe default.
+ */
+export declare class EmbeddingPrefixes {
+    private static readonly KNOWN;
+    /** Prefixes for a model id, or undefined when none are known to apply. */
+    static forModel(modelId: string): {
+        query: string;
+        document: string;
+        family: string;
+    } | undefined;
+}

package/dist/infrastructure/ai/EmbeddingPrefixes.js

@@ -0,0 +1,40 @@
+/**
+ * Query and document prefixes required by asymmetric embedding models.
+ *
+ * These models are trained with the prefixes present, and omitting them
+ * degrades retrieval without producing any error — the vectors are still
+ * valid, just worse. Nobody discovers that from the tool; they discover it
+ * from the model card, if at all. Setting them at `init` time is the only
+ * point where the model is actually known.
+ *
+ * Deliberately short: it covers only families whose prefixes are documented
+ * and unambiguous. An unrecognized model gets none, which is the safe default.
+ */
+export class EmbeddingPrefixes {
+    static KNOWN = [
+        {
+            match: /nomic-embed/i,
+            query: "search_query: ",
+            document: "search_document: ",
+            family: "nomic-embed",
+        },
+        {
+            match: /(^|[^a-z])e5[-_]|multilingual-e5/i,
+            query: "query: ",
+            document: "passage: ",
+            family: "e5",
+        },
+    ];
+    /** Prefixes for a model id, or undefined when none are known to apply. */
+    static forModel(modelId) {
+        const found = EmbeddingPrefixes.KNOWN.find((e) => e.match.test(modelId));
+        if (!found)
+            return undefined;
+        return {
+            query: found.query,
+            document: found.document,
+            family: found.family,
+        };
+    }
+}
+//# sourceMappingURL=EmbeddingPrefixes.js.map

package/dist/infrastructure/ai/EmbeddingPrefixes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingPrefixes.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/EmbeddingPrefixes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,iBAAiB;IACrB,MAAM,CAAU,KAAK,GAKxB;QACJ;YACC,KAAK,EAAE,cAAc;YACrB,KAAK,EAAE,gBAAgB;YACvB,QAAQ,EAAE,mBAAmB;YAC7B,MAAM,EAAE,aAAa;SACrB;QACD;YACC,KAAK,EAAE,mCAAmC;YAC1C,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,IAAI;SACZ;KACD,CAAC;IAEF,0EAA0E;IAC1E,MAAM,CAAC,QAAQ,CACd,OAAe;QAEf,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,OAAO;YACN,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;SACpB,CAAC;IACH,CAAC"}

package/dist/infrastructure/ai/LmStudioProbe.d.ts

@@ -0,0 +1,18 @@
+import type { DetectedRuntime, RuntimeProbe } from "./ModelRuntime.js";
+/**
+ * Detects a local LM Studio server.
+ *
+ * LM Studio's native listing reports each model's type, so kinds come from the
+ * server rather than from guessing at names. Its OpenAI-compatible `/v1`
+ * surface is what the embedding calls actually use.
+ */
+export declare class LmStudioProbe implements RuntimeProbe {
+    private static readonly CATALOG_URL;
+    static readonly BASE_URL = "http://localhost:1234/v1";
+    /** LM Studio speaks OpenAI's protocol, not one of its own. */
+    static readonly PROVIDER_PACKAGE = "@ai-sdk/openai-compatible";
+    private static readonly TIMEOUT_MS;
+    detect(): Promise<DetectedRuntime | undefined>;
+    /** `vlm` is a vision-capable chat model, and answers text prompts fine. */
+    private static kindOf;
+}

package/dist/infrastructure/ai/LmStudioProbe.js

@@ -0,0 +1,49 @@
+/**
+ * Detects a local LM Studio server.
+ *
+ * LM Studio's native listing reports each model's type, so kinds come from the
+ * server rather than from guessing at names. Its OpenAI-compatible `/v1`
+ * surface is what the embedding calls actually use.
+ */
+export class LmStudioProbe {
+    static CATALOG_URL = "http://localhost:1234/api/v0/models";
+    static BASE_URL = "http://localhost:1234/v1";
+    /** LM Studio speaks OpenAI's protocol, not one of its own. */
+    static PROVIDER_PACKAGE = "@ai-sdk/openai-compatible";
+    static TIMEOUT_MS = 3000;
+    async detect() {
+        let payload;
+        try {
+            const res = await fetch(LmStudioProbe.CATALOG_URL, {
+                signal: AbortSignal.timeout(LmStudioProbe.TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return undefined;
+            payload = (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+        const models = (payload.data ?? []).map((m) => ({
+            id: m.id,
+            kind: LmStudioProbe.kindOf(m.type),
+            loaded: m.state === "loaded",
+        }));
+        return {
+            label: "LM Studio",
+            providerId: "lmstudio",
+            baseURL: LmStudioProbe.BASE_URL,
+            providerPackage: LmStudioProbe.PROVIDER_PACKAGE,
+            models,
+        };
+    }
+    /** `vlm` is a vision-capable chat model, and answers text prompts fine. */
+    static kindOf(type) {
+        if (type === "embeddings")
+            return "embedding";
+        if (type === "llm" || type === "vlm")
+            return "chat";
+        return "unknown";
+    }
+}
+//# sourceMappingURL=LmStudioProbe.js.map

package/dist/infrastructure/ai/LmStudioProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LmStudioProbe.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/LmStudioProbe.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IACjB,MAAM,CAAU,WAAW,GAAG,qCAAqC,CAAC;IAC5E,MAAM,CAAU,QAAQ,GAAG,0BAA0B,CAAC;IACtD,8DAA8D;IAC9D,MAAM,CAAU,gBAAgB,GAAG,2BAA2B,CAAC;IACvD,MAAM,CAAU,UAAU,GAAG,IAAI,CAAC;IAE1C,KAAK,CAAC,MAAM;QACX,IAAI,OAEH,CAAC;QACF,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,WAAW,EAAE;gBAClD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC;aACrD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YAC9B,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAE1B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,MAAM,GAAqB,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjE,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YAClC,MAAM,EAAE,CAAC,CAAC,KAAK,KAAK,QAAQ;SAC5B,CAAC,CAAC,CAAC;QAEJ,OAAO;YACN,KAAK,EAAE,WAAW;YAClB,UAAU,EAAE,UAAU;YACtB,OAAO,EAAE,aAAa,CAAC,QAAQ;YAC/B,eAAe,EAAE,aAAa,CAAC,gBAAgB;YAC/C,MAAM;SACN,CAAC;IACH,CAAC;IAED,2EAA2E;IACnE,MAAM,CAAC,MAAM,CAAC,IAAwB;QAC7C,IAAI,IAAI,KAAK,YAAY;YAAE,OAAO,WAAW,CAAC;QAC9C,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,MAAM,CAAC;QACpD,OAAO,SAAS,CAAC;IAClB,CAAC"}

package/dist/infrastructure/ai/LocalModelReloader.d.ts

@@ -0,0 +1,21 @@
+import type { LmgrepConfig } from "../../domain/config/LmgrepConfig.js";
+/**
+ * Unloads and reloads a model on a local inference server.
+ *
+ * A local server that has wedged or evicted the model is the common cause of a
+ * run of embedding failures, and it recovers on a reload — worth one automatic
+ * attempt before abandoning a long index run. Remote providers are never
+ * reloaded: the request would be meaningless and possibly billable.
+ */
+export declare class LocalModelReloader {
+    private readonly config;
+    private static readonly LOOPBACK_HOSTS;
+    private static readonly UNLOAD_SETTLE_MS;
+    private static readonly DEFAULT_BASE_URL;
+    private static readonly DEFAULT_CONTEXT_LENGTH;
+    constructor(config: LmgrepConfig);
+    /** Whether the configured endpoint is a loopback address. */
+    get isLocal(): boolean;
+    /** Best-effort reload; false when the server does not cooperate. */
+    reload(): Promise<boolean>;
+}

package/dist/infrastructure/ai/LocalModelReloader.js

@@ -0,0 +1,61 @@
+/**
+ * Unloads and reloads a model on a local inference server.
+ *
+ * A local server that has wedged or evicted the model is the common cause of a
+ * run of embedding failures, and it recovers on a reload — worth one automatic
+ * attempt before abandoning a long index run. Remote providers are never
+ * reloaded: the request would be meaningless and possibly billable.
+ */
+export class LocalModelReloader {
+    config;
+    static LOOPBACK_HOSTS = new Set([
+        "localhost",
+        "127.0.0.1",
+        "0.0.0.0",
+    ]);
+    static UNLOAD_SETTLE_MS = 2000;
+    static DEFAULT_BASE_URL = "http://localhost:1234";
+    static DEFAULT_CONTEXT_LENGTH = 8192;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Whether the configured endpoint is a loopback address. */
+    get isLocal() {
+        if (!this.config.baseURL)
+            return false;
+        try {
+            return LocalModelReloader.LOOPBACK_HOSTS.has(new URL(this.config.baseURL).hostname);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Best-effort reload; false when the server does not cooperate. */
+    async reload() {
+        const modelId = this.config.model.split(":").slice(1).join(":");
+        const baseURL = this.config.baseURL ?? LocalModelReloader.DEFAULT_BASE_URL;
+        const apiBase = baseURL.replace(/\/v1\/?$/, "");
+        try {
+            await fetch(`${apiBase}/api/v1/models/unload`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ instance_id: modelId }),
+            });
+            await new Promise((r) => setTimeout(r, LocalModelReloader.UNLOAD_SETTLE_MS));
+            const res = await fetch(`${apiBase}/api/v1/models/load`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    model: modelId,
+                    context_length: this.config.maxTokens ?? LocalModelReloader.DEFAULT_CONTEXT_LENGTH,
+                }),
+            });
+            await res.json();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=LocalModelReloader.js.map

package/dist/infrastructure/ai/LocalModelReloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalModelReloader.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/LocalModelReloader.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAkB;IAUD;IATrB,MAAM,CAAU,cAAc,GAAG,IAAI,GAAG,CAAC;QAChD,WAAW;QACX,WAAW;QACX,SAAS;KACT,CAAC,CAAC;IACK,MAAM,CAAU,gBAAgB,GAAG,IAAI,CAAC;IACxC,MAAM,CAAU,gBAAgB,GAAG,uBAAuB,CAAC;IAC3D,MAAM,CAAU,sBAAsB,GAAG,IAAI,CAAC;IAEtD,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,6DAA6D;IAC7D,IAAI,OAAO;QACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,CAAC;YACJ,OAAO,kBAAkB,CAAC,cAAc,CAAC,GAAG,CAC3C,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CACrC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,MAAM;QACX,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,kBAAkB,CAAC,gBAAgB,CAAC;QAC3E,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAEhD,IAAI,CAAC;YACJ,MAAM,KAAK,CAAC,GAAG,OAAO,uBAAuB,EAAE;gBAC9C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;aAC9C,CAAC,CAAC;YACH,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CACvB,UAAU,CAAC,CAAC,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAClD,CAAC;YACF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,qBAAqB,EAAE;gBACxD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACpB,KAAK,EAAE,OAAO;oBACd,cAAc,EACb,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC,sBAAsB;iBACnE,CAAC;aACF,CAAC,CAAC;YACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC"}

package/dist/infrastructure/ai/LocalRuntimeDetector.d.ts

@@ -0,0 +1,36 @@
+import type { CatalogedModel, DetectedRuntime, RuntimeProbe } from "./ModelRuntime.js";
+/**
+ * Finds whichever local inference server is running.
+ *
+ * Probes run concurrently and the first *useful* result wins — a server with
+ * models beats one that is merely listening, so a running-but-empty Ollama
+ * does not shadow a fully set up LM Studio.
+ */
+export declare class LocalRuntimeDetector {
+    private readonly probes;
+    constructor(probes?: readonly RuntimeProbe[]);
+    detectAll(): Promise<DetectedRuntime[]>;
+    /** The best runtime to configure against, if any is usable. */
+    detectBest(): Promise<DetectedRuntime | undefined>;
+    /**
+     * Models the runtime says are embedders, best candidate first.
+     *
+     * A loaded model sorts ahead of the rest. Runtimes list models in an order
+     * of their own — LM Studio appears to use recency — and picking by position
+     * means the choice silently changes depending on what was used last.
+     * Load state is an explicit signal instead of an incidental one.
+     */
+    static embeddingModels(runtime: DetectedRuntime): CatalogedModel[];
+    /** Stable sort putting loaded models first, order otherwise preserved. */
+    private static loadedFirst;
+    /**
+     * Models usable for `ask`. Only taken when the runtime typed them: guessing
+     * an embedder is a chat model produces a confusing failure at answer time.
+     */
+    static chatModels(runtime: DetectedRuntime): CatalogedModel[];
+    /**
+     * Fallback for runtimes that do not type their models: anything not
+     * recognizable as an embedder.
+     */
+    static untypedModels(runtime: DetectedRuntime): CatalogedModel[];
+}

package/dist/infrastructure/ai/LocalRuntimeDetector.js

@@ -0,0 +1,61 @@
+import { LmStudioProbe } from "./LmStudioProbe.js";
+import { OllamaProbe } from "./OllamaProbe.js";
+/**
+ * Finds whichever local inference server is running.
+ *
+ * Probes run concurrently and the first *useful* result wins — a server with
+ * models beats one that is merely listening, so a running-but-empty Ollama
+ * does not shadow a fully set up LM Studio.
+ */
+export class LocalRuntimeDetector {
+    probes;
+    constructor(probes = [
+        new LmStudioProbe(),
+        new OllamaProbe(),
+    ]) {
+        this.probes = probes;
+    }
+    async detectAll() {
+        const results = await Promise.all(this.probes.map((p) => p.detect().catch(() => undefined)));
+        return results.filter((r) => r !== undefined);
+    }
+    /** The best runtime to configure against, if any is usable. */
+    async detectBest() {
+        const found = await this.detectAll();
+        return (found.find((r) => LocalRuntimeDetector.embeddingModels(r).length > 0) ??
+            found[0]);
+    }
+    /**
+     * Models the runtime says are embedders, best candidate first.
+     *
+     * A loaded model sorts ahead of the rest. Runtimes list models in an order
+     * of their own — LM Studio appears to use recency — and picking by position
+     * means the choice silently changes depending on what was used last.
+     * Load state is an explicit signal instead of an incidental one.
+     */
+    static embeddingModels(runtime) {
+        return LocalRuntimeDetector.loadedFirst(runtime.models.filter((m) => m.kind === "embedding"));
+    }
+    /** Stable sort putting loaded models first, order otherwise preserved. */
+    static loadedFirst(models) {
+        return [
+            ...models.filter((m) => m.loaded),
+            ...models.filter((m) => !m.loaded),
+        ];
+    }
+    /**
+     * Models usable for `ask`. Only taken when the runtime typed them: guessing
+     * an embedder is a chat model produces a confusing failure at answer time.
+     */
+    static chatModels(runtime) {
+        return LocalRuntimeDetector.loadedFirst(runtime.models.filter((m) => m.kind === "chat"));
+    }
+    /**
+     * Fallback for runtimes that do not type their models: anything not
+     * recognizable as an embedder.
+     */
+    static untypedModels(runtime) {
+        return LocalRuntimeDetector.loadedFirst(runtime.models.filter((m) => m.kind === "unknown"));
+    }
+}
+//# sourceMappingURL=LocalRuntimeDetector.js.map

package/dist/infrastructure/ai/LocalRuntimeDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalRuntimeDetector.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/LocalRuntimeDetector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMnD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IAEd;IADlB,YACkB,SAAkC;QAClD,IAAI,aAAa,EAAE;QACnB,IAAI,WAAW,EAAE;KACjB;QAHgB,WAAM,GAAN,MAAM,CAGtB;IACC,CAAC;IAEJ,KAAK,CAAC,SAAS;QACd,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CACzD,CAAC;QACF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACrE,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,UAAU;QACf,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,OAAO,CACN,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YACrE,KAAK,CAAC,CAAC,CAAC,CACR,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,OAAwB;QAC9C,OAAO,oBAAoB,CAAC,WAAW,CACtC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CACpD,CAAC;IACH,CAAC;IAED,0EAA0E;IAClE,MAAM,CAAC,WAAW,CAAC,MAAwB;QAClD,OAAO;YACN,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;YACjC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;SAClC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,OAAwB;QACzC,OAAO,oBAAoB,CAAC,WAAW,CACtC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAC/C,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,OAAwB;QAC5C,OAAO,oBAAoB,CAAC,WAAW,CACtC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAClD,CAAC;IACH,CAAC;CACD"}

package/dist/infrastructure/ai/ModelRuntime.d.ts

@@ -0,0 +1,32 @@
+/** What a discovered model is good for. */
+export type ModelKind = "embedding" | "chat" | "unknown";
+export interface CatalogedModel {
+    id: string;
+    kind: ModelKind;
+    /**
+     * Currently loaded in the runtime.
+     *
+     * The strongest statement of intent available without asking: a model the
+     * user has deliberately loaded is the one they mean. Undefined when the
+     * runtime does not report load state.
+     */
+    loaded?: boolean;
+}
+/** A local inference server that was found listening. */
+export interface DetectedRuntime {
+    /** Human name, for what `init` prints. */
+    label: string;
+    /** Provider segment of the `provider:model` string. */
+    providerId: string;
+    baseURL: string;
+    /**
+     * AI SDK package to load. Undefined means the default
+     * `@ai-sdk/<providerId>` is correct.
+     */
+    providerPackage?: string;
+    models: CatalogedModel[];
+}
+/** Detects one kind of local inference server. */
+export interface RuntimeProbe {
+    detect(): Promise<DetectedRuntime | undefined>;
+}

package/dist/infrastructure/ai/ModelRuntime.js

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

package/dist/infrastructure/ai/ModelRuntime.js.map

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

package/dist/infrastructure/ai/OllamaProbe.d.ts

@@ -0,0 +1,21 @@
+import type { DetectedRuntime, RuntimeProbe } from "./ModelRuntime.js";
+/**
+ * Detects a local Ollama server.
+ *
+ * Ollama's tag listing does not say what a model is for, so kind is inferred
+ * from the name. That is a guess, and marked as one — `unknown` models are
+ * offered only when nothing better is found.
+ */
+export declare class OllamaProbe implements RuntimeProbe {
+    private static readonly TAGS_URL;
+    /** Models currently resident in memory. */
+    private static readonly RUNNING_URL;
+    static readonly BASE_URL = "http://localhost:11434/v1";
+    private static readonly TIMEOUT_MS;
+    /** Name fragments that reliably indicate an embedding model. */
+    private static readonly EMBEDDING_HINTS;
+    detect(): Promise<DetectedRuntime | undefined>;
+    /** Best-effort; an older Ollama without this endpoint just reports none. */
+    private loadedModelNames;
+    private static looksLikeEmbedding;
+}

package/dist/infrastructure/ai/OllamaProbe.js

@@ -0,0 +1,69 @@
+/**
+ * Detects a local Ollama server.
+ *
+ * Ollama's tag listing does not say what a model is for, so kind is inferred
+ * from the name. That is a guess, and marked as one — `unknown` models are
+ * offered only when nothing better is found.
+ */
+export class OllamaProbe {
+    static TAGS_URL = "http://localhost:11434/api/tags";
+    /** Models currently resident in memory. */
+    static RUNNING_URL = "http://localhost:11434/api/ps";
+    static BASE_URL = "http://localhost:11434/v1";
+    static TIMEOUT_MS = 3000;
+    /** Name fragments that reliably indicate an embedding model. */
+    static EMBEDDING_HINTS = [
+        "embed",
+        "nomic",
+        "bge",
+        "minilm",
+        "gte-",
+        "e5-",
+    ];
+    async detect() {
+        let payload;
+        try {
+            const res = await fetch(OllamaProbe.TAGS_URL, {
+                signal: AbortSignal.timeout(OllamaProbe.TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return undefined;
+            payload = (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+        const loaded = await this.loadedModelNames();
+        const models = (payload.models ?? []).map((m) => ({
+            id: m.name,
+            kind: OllamaProbe.looksLikeEmbedding(m.name) ? "embedding" : "unknown",
+            loaded: loaded.has(m.name),
+        }));
+        return {
+            label: "Ollama",
+            providerId: "ollama",
+            baseURL: OllamaProbe.BASE_URL,
+            models,
+        };
+    }
+    /** Best-effort; an older Ollama without this endpoint just reports none. */
+    async loadedModelNames() {
+        try {
+            const res = await fetch(OllamaProbe.RUNNING_URL, {
+                signal: AbortSignal.timeout(OllamaProbe.TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return new Set();
+            const payload = (await res.json());
+            return new Set((payload.models ?? []).map((m) => m.name));
+        }
+        catch {
+            return new Set();
+        }
+    }
+    static looksLikeEmbedding(name) {
+        const lower = name.toLowerCase();
+        return OllamaProbe.EMBEDDING_HINTS.some((hint) => lower.includes(hint));
+    }
+}
+//# sourceMappingURL=OllamaProbe.js.map

package/dist/infrastructure/ai/OllamaProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OllamaProbe.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/OllamaProbe.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACf,MAAM,CAAU,QAAQ,GAAG,iCAAiC,CAAC;IACrE,2CAA2C;IACnC,MAAM,CAAU,WAAW,GAAG,+BAA+B,CAAC;IACtE,MAAM,CAAU,QAAQ,GAAG,2BAA2B,CAAC;IAC/C,MAAM,CAAU,UAAU,GAAG,IAAI,CAAC;IAE1C,gEAAgE;IACxD,MAAM,CAAU,eAAe,GAAG;QACzC,OAAO;QACP,OAAO;QACP,KAAK;QACL,QAAQ;QACR,MAAM;QACN,KAAK;KACL,CAAC;IAEF,KAAK,CAAC,MAAM;QACX,IAAI,OAA6C,CAAC;QAClD,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE;gBAC7C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;aACnD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YAC9B,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAyC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAqB,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnE,EAAE,EAAE,CAAC,CAAC,IAAI;YACV,IAAI,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;YACtE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAC,CAAC;QAEJ,OAAO;YACN,KAAK,EAAE,QAAQ;YACf,UAAU,EAAE,QAAQ;YACpB,OAAO,EAAE,WAAW,CAAC,QAAQ;YAC7B,MAAM;SACN,CAAC;IACH,CAAC;IAED,4EAA4E;IACpE,KAAK,CAAC,gBAAgB;QAC7B,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE;gBAChD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC;aACnD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,IAAI,GAAG,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAEhC,CAAC;YACF,OAAO,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,GAAG,EAAE,CAAC;QAClB,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,kBAAkB,CAAC,IAAY;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,OAAO,WAAW,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,CAAC"}

package/dist/infrastructure/ai/ProviderFailure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Classifies provider errors that the research loop must handle differently
+ * from a genuine failure.
+ *
+ * A timeout and a context overflow both mean "the loop cannot continue, but
+ * what it gathered is still good" — they fall through to synthesis rather than
+ * degrading the whole run.
+ */
+export declare class ProviderFailure {
+    private static readonly OVERFLOW_PATTERN;
+    static isAbort(error: unknown): boolean;
+    /** A provider 400 whose body mentions the context window being exceeded. */
+    static isContextOverflow(error: unknown): boolean;
+    /** Opt-in diagnostics; provider errors carry detail worth seeing. */
+    static debug(where: string, error: unknown): void;
+}

package/dist/infrastructure/ai/ProviderFailure.js

@@ -0,0 +1,35 @@
+/**
+ * Classifies provider errors that the research loop must handle differently
+ * from a genuine failure.
+ *
+ * A timeout and a context overflow both mean "the loop cannot continue, but
+ * what it gathered is still good" — they fall through to synthesis rather than
+ * degrading the whole run.
+ */
+export class ProviderFailure {
+    static OVERFLOW_PATTERN = /context (size|length|window)|exceed|too (long|large)|max.*token/i;
+    static isAbort(error) {
+        return (error instanceof Error &&
+            (error.name === "AbortError" || error.name === "TimeoutError"));
+    }
+    /** A provider 400 whose body mentions the context window being exceeded. */
+    static isContextOverflow(error) {
+        const e = error;
+        if (e?.statusCode !== 400)
+            return false;
+        return ProviderFailure.OVERFLOW_PATTERN.test(`${e.responseBody ?? ""} ${e.message ?? ""}`);
+    }
+    /** Opt-in diagnostics; provider errors carry detail worth seeing. */
+    static debug(where, error) {
+        if (!process.env.LMGREP_DEBUG)
+            return;
+        const e = error;
+        console.error(`[lmgrep debug] ${where} error:`, {
+            name: e?.name,
+            message: e?.message,
+            statusCode: e?.statusCode,
+            responseBody: e?.responseBody,
+        });
+    }
+}
+//# sourceMappingURL=ProviderFailure.js.map

package/dist/infrastructure/ai/ProviderFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderFailure.js","sourceRoot":"","sources":["../../../src/infrastructure/ai/ProviderFailure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IACnB,MAAM,CAAU,gBAAgB,GACvC,kEAAkE,CAAC;IAEpE,MAAM,CAAC,OAAO,CAAC,KAAc;QAC5B,OAAO,CACN,KAAK,YAAY,KAAK;YACtB,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,CAC9D,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACtC,MAAM,CAAC,GAAG,KAIT,CAAC;QACF,IAAI,CAAC,EAAE,UAAU,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,eAAe,CAAC,gBAAgB,CAAC,IAAI,CAC3C,GAAG,CAAC,CAAC,YAAY,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAC5C,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,MAAM,CAAC,KAAK,CAAC,KAAa,EAAE,KAAc;QACzC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY;YAAE,OAAO;QACtC,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,OAAO,CAAC,KAAK,CAAC,kBAAkB,KAAK,SAAS,EAAE;YAC/C,IAAI,EAAE,CAAC,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,OAAO;YACnB,UAAU,EAAE,CAAC,EAAE,UAAU;YACzB,YAAY,EAAE,CAAC,EAAE,YAAY;SAC7B,CAAC,CAAC;IACJ,CAAC"}

package/dist/infrastructure/ai/ProviderModuleLoader.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Imports an AI SDK provider package.
+ *
+ * Providers are peer dependencies the user installs, so resolution has to
+ * reach beyond this package's own `node_modules`: an `npm i -g @ai-sdk/openai`
+ * is a normal setup and would otherwise fail to resolve.
+ */
+export declare class ProviderModuleLoader {
+    private readonly cache;
+    load(packageName: string): Promise<Record<string, unknown>>;
+    private resolve;
+    private globalModulePaths;
+}