graphile-llm 0.11.5 → 0.12.0

package/__tests__/graphile-llm.test.js

@@ -39,6 +39,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const ollama_1 = __importDefault(require("@agentic-kit/ollama"));
 const graphile_connection_filter_1 = require("graphile-connection-filter");
 const pgvector_1 = require("graphile-search/adapters/pgvector");
+const tsvector_1 = require("graphile-search/adapters/tsvector");
+const tsvector_codec_1 = require("graphile-search/codecs/tsvector-codec");
 const vector_codec_1 = require("graphile-search/codecs/vector-codec");
 const plugin_1 = require("graphile-search/plugin");
 const graphile_test_1 = require("graphile-test");
@@ -235,10 +237,10 @@ describe('graphile-llm schema enrichment', () => {
     });
     // ─── Mutation text companion fields ──────────────────────────────────────
     describe('Mutation text companion fields', () => {
-        it('adds embeddingText field to CreateArticleInput', async () => {
+        it('adds embeddingText field to ArticleInput (create input)', async () => {
             const result = await query(`
         query {
-          __type(name: "CreateArticleInput") {
+          __type(name: "ArticleInput") {
             inputFields {
               name
               type { name }
@@ -250,9 +252,7 @@ describe('graphile-llm schema enrichment', () => {
             const inputType = result.data?.__type;
             expect(inputType).toBeDefined();
             const fieldNames = inputType.inputFields.map((f) => f.name);
-            // Original embedding field
             expect(fieldNames).toContain('embedding');
-            // Companion text field from LlmTextMutationPlugin
             expect(fieldNames).toContain('embeddingText');
             const textField = inputType.inputFields.find((f) => f.name === 'embeddingText');
             expect(textField).toBeDefined();
@@ -461,12 +461,16 @@ function makeTestSmartTagsPlugin(tagsByTable) {
     return {
         name: 'TestSmartTagsPlugin',
         version: '1.0.0',
+        before: ['LlmRagPlugin'],
         schema: {
             hooks: {
-                init: {
-                    before: ['UnifiedSearchPlugin', 'LlmRagPlugin'],
-                    callback(_, build) {
-                        for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                build: {
+                    before: ['LlmRagPlugin'],
+                    callback(build) {
+                        const pgRegistry = build.input?.pgRegistry ?? build.pgRegistry;
+                        if (!pgRegistry)
+                            return build;
+                        for (const codec of Object.values(pgRegistry.pgCodecs || {})) {
                             const c = codec;
                             if (!c.attributes || !c.name)
                                 continue;
@@ -479,7 +483,7 @@ function makeTestSmartTagsPlugin(tagsByTable) {
                                 c.extensions.tags = {};
                             Object.assign(c.extensions.tags, tags);
                         }
-                        return _;
+                        return build;
                     }
                 }
             }
@@ -518,47 +522,39 @@ describe('RAG plugin schema enrichment', () => {
                 usage: { input: 10, output: 15, reasoning: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 25 }
             };
         };
+        // Provide mock embedder/chat directly instead of using createLlmModulePlugin
+        // to avoid build.extend naming conflicts when overriding
+        const mockLlmPlugin = {
+            name: 'TestMockLlmPlugin',
+            version: '1.0.0',
+            schema: {
+                hooks: {
+                    build(build) {
+                        return build.extend(build, {
+                            llmEmbedder: mockEmbedder,
+                            llmChatCompleter: mockChatCompleter,
+                            llmEmbeddingModel: 'test-mock-model',
+                            llmChatModel: 'test-mock-chat'
+                        }, 'TestMockLlmPlugin providing mock embedder and chat completer');
+                    }
+                }
+            }
+        };
         const testPreset = {
             extends: [(0, graphile_connection_filter_1.ConnectionFilterPreset)()],
             plugins: [
                 vector_codec_1.VectorCodecPlugin,
                 unifiedPlugin,
                 smartTagsPlugin,
-                (0, llm_module_plugin_1.createLlmModulePlugin)({
-                    defaultEmbedder: {
-                        provider: 'ollama',
-                        model: 'nomic-embed-text',
-                        baseUrl: 'http://localhost:11434'
-                    }
-                }),
+                mockLlmPlugin,
                 (0, text_search_plugin_1.createLlmTextSearchPlugin)(),
                 (0, text_mutation_plugin_1.createLlmTextMutationPlugin)(),
                 (0, rag_plugin_1.createLlmRagPlugin)()
             ]
         };
-        // Override the embedder and chat completer on the build context
-        // by wrapping the LlmModulePlugin's build hook
-        const overridePlugin = {
-            name: 'TestOverridePlugin',
-            version: '1.0.0',
-            after: ['LlmModulePlugin'],
-            schema: {
-                hooks: {
-                    build(build) {
-                        return build.extend(build, {
-                            llmEmbedder: mockEmbedder,
-                            llmChatCompleter: mockChatCompleter
-                        }, 'TestOverridePlugin overriding embedder and chat completer');
-                    }
-                }
-            }
-        };
         const connections = await (0, graphile_test_1.getConnections)({
             schemas: ['llm_test'],
-            preset: {
-                ...testPreset,
-                plugins: [...testPreset.plugins, overridePlugin]
-            },
+            preset: testPreset,
             useRoot: true,
             authRole: 'postgres'
         }, [graphile_test_1.seed.sqlfile([(0, path_1.join)(__dirname, './setup.sql')])]);
@@ -735,3 +731,288 @@ describe('GraphileLlmPreset toggles', () => {
         expect(pluginNames).not.toContain('LlmRagPlugin');
     });
 });
+// =============================================================================
+// Suite 7: Real Ollama + unifiedSearch + pgvector RRF integration
+//
+// End-to-end: embeds article text with real Ollama nomic-embed-text (768 dims),
+// seeds the DB, then runs hybrid text+vector queries verifying RRF fusion,
+// semantic relevance, and the embedTextInWhere pipeline.
+//
+// Requires: PostgreSQL with pgvector + Ollama with nomic-embed-text.
+// =============================================================================
+const INTEGRATION_ARTICLES = [
+    { id: 1, title: 'Introduction to Machine Learning', body: 'Machine learning is a subset of artificial intelligence that focuses on algorithms and statistical models.' },
+    { id: 2, title: 'Cooking Italian Pasta', body: 'The best Italian pasta is made with fresh ingredients like San Marzano tomatoes and homemade egg noodles.' },
+    { id: 3, title: 'Deep Learning with Neural Networks', body: 'Deep learning uses neural networks with multiple layers to learn hierarchical representations of data.' },
+    { id: 4, title: 'Gardening Tips for Spring', body: 'Start your spring garden by preparing soil, choosing the right seeds, and ensuring proper sunlight and watering.' },
+    { id: 5, title: 'Natural Language Processing', body: 'NLP combines computational linguistics with machine learning to enable computers to understand human language.' },
+];
+const INTEGRATION_SETUP_SQL = `
+  CREATE EXTENSION IF NOT EXISTS vector;
+  CREATE SCHEMA IF NOT EXISTS llm_integration;
+
+  CREATE TABLE llm_integration.articles (
+    id serial PRIMARY KEY,
+    title text NOT NULL,
+    body text NOT NULL,
+    tsv tsvector GENERATED ALWAYS AS (
+      setweight(to_tsvector('english', title), 'A') ||
+      setweight(to_tsvector('english', body), 'B')
+    ) STORED,
+    embedding vector(768) NOT NULL
+  );
+
+  CREATE INDEX idx_int_articles_tsv ON llm_integration.articles USING gin(tsv);
+  CREATE INDEX idx_int_articles_embedding ON llm_integration.articles
+    USING hnsw(embedding vector_cosine_ops);
+`;
+describe('Real Ollama + unifiedSearch + pgvector RRF integration', () => {
+    let db;
+    let teardown;
+    let query;
+    let embedder;
+    // Pre-computed query vectors (embedded once in beforeAll)
+    let mlQueryVector;
+    let cookingQueryVector;
+    beforeAll(async () => {
+        // Build a real Ollama embedder
+        const built = (0, embedder_1.buildEmbedder)({
+            provider: 'ollama',
+            model: 'nomic-embed-text',
+            baseUrl: 'http://localhost:11434',
+        });
+        if (!built)
+            throw new Error('Failed to build Ollama embedder');
+        embedder = built;
+        await ensureNomicModel();
+        // Embed all article bodies in parallel
+        const embeddings = await Promise.all(INTEGRATION_ARTICLES.map((a) => embedder(`${a.title}. ${a.body}`)));
+        // Build seed SQL with real 768-dim embeddings
+        const values = INTEGRATION_ARTICLES.map((a, i) => {
+            const vecStr = `'[${embeddings[i].embedding.join(',')}]'`;
+            const titleEsc = a.title.replace(/'/g, "''");
+            const bodyEsc = a.body.replace(/'/g, "''");
+            return `(${a.id}, '${titleEsc}', '${bodyEsc}', ${vecStr})`;
+        }).join(',\n  ');
+        const seedSql = `
+      INSERT INTO llm_integration.articles (id, title, body, embedding)
+      VALUES ${values};
+      SELECT setval('llm_integration.articles_id_seq', ${INTEGRATION_ARTICLES.length});
+    `;
+        // Pre-compute search query vectors
+        const [mlResult, cookResult] = await Promise.all([
+            embedder('machine learning artificial intelligence algorithms'),
+            embedder('Italian cooking pasta recipes tomatoes'),
+        ]);
+        mlQueryVector = mlResult.embedding;
+        cookingQueryVector = cookResult.embedding;
+        // Set up PostGraphile with tsvector + pgvector adapters + LLM plugin
+        const unifiedPlugin = (0, plugin_1.createUnifiedSearchPlugin)({
+            adapters: [
+                (0, tsvector_1.createTsvectorAdapter)(),
+                (0, pgvector_1.createPgvectorAdapter)(),
+            ],
+            enableSearchScore: true,
+            enableUnifiedSearch: true,
+            rrfK: 60,
+        });
+        const testPreset = {
+            extends: [(0, graphile_connection_filter_1.ConnectionFilterPreset)()],
+            plugins: [
+                tsvector_codec_1.TsvectorCodecPlugin,
+                vector_codec_1.VectorCodecPlugin,
+                unifiedPlugin,
+                (0, llm_module_plugin_1.createLlmModulePlugin)({
+                    defaultEmbedder: {
+                        provider: 'ollama',
+                        model: 'nomic-embed-text',
+                        baseUrl: 'http://localhost:11434',
+                    },
+                }),
+                (0, text_search_plugin_1.createLlmTextSearchPlugin)(),
+            ],
+        };
+        const connections = await (0, graphile_test_1.getConnections)({
+            schemas: ['llm_integration'],
+            preset: testPreset,
+            useRoot: true,
+            authRole: 'postgres',
+        }, [
+            graphile_test_1.seed.fn(async (ctx) => {
+                await ctx.pg.query(INTEGRATION_SETUP_SQL);
+                await ctx.pg.query(seedSql);
+            }),
+        ]);
+        db = connections.db;
+        teardown = connections.teardown;
+        query = connections.query;
+        await db.client.query('BEGIN');
+    }, 120_000);
+    afterAll(async () => {
+        if (db) {
+            try {
+                await db.client.query('ROLLBACK');
+            }
+            catch { }
+        }
+        if (teardown)
+            await teardown();
+    });
+    beforeEach(async () => { await db.beforeEach(); });
+    afterEach(async () => { await db.afterEach(); });
+    // ─── embedTextInWhere with real Ollama ──────────────────────────────────
+    it('embedTextInWhere transforms unifiedSearch with real 768-dim Ollama vector', async () => {
+        const realEmbedder = async (text) => {
+            const result = await embedder(text);
+            return result.embedding;
+        };
+        const where = { unifiedSearch: 'machine learning algorithms' };
+        await (0, text_search_plugin_1.embedTextInWhere)(where, realEmbedder, true);
+        expect(where.unifiedSearch).toHaveProperty('__text', 'machine learning algorithms');
+        expect(where.unifiedSearch).toHaveProperty('__vector');
+        expect(Array.isArray(where.unifiedSearch.__vector)).toBe(true);
+        expect(where.unifiedSearch.__vector.length).toBe(768);
+        for (const v of where.unifiedSearch.__vector) {
+            expect(typeof v).toBe('number');
+            expect(Number.isFinite(v)).toBe(true);
+        }
+    }, 30_000);
+    // ─── unifiedSearch text-only (no vector injection) ─────────────────────
+    it('unifiedSearch text-only uses tsvector without pgvector', async () => {
+        const result = await query(`
+      query {
+        allArticles(where: { unifiedSearch: "machine learning" }) {
+          nodes { rowId title tsvRank embeddingVectorDistance searchScore }
+        }
+      }
+    `);
+        expect(result.errors).toBeUndefined();
+        const nodes = result.data?.allArticles?.nodes ?? [];
+        expect(nodes.length).toBeGreaterThan(0);
+        // tsvector should be active
+        const hasTsv = nodes.some((n) => n.tsvRank !== null);
+        expect(hasTsv).toBe(true);
+        // pgvector should NOT participate (no vector injection in graphile-test)
+        for (const node of nodes) {
+            expect(node.embeddingVectorDistance).toBeNull();
+        }
+    });
+    // ─── unifiedSearch + real pgvector: hybrid RRF ─────────────────────────
+    it('unifiedSearch + real vector embedding fuses tsvector + pgvector via RRF', async () => {
+        const vecStr = `[${mlQueryVector.join(',')}]`;
+        const result = await query(`
+      query($vec: [Float!]!) {
+        allArticles(where: {
+          unifiedSearch: "machine learning"
+          vectorEmbedding: { vector: $vec, metric: COSINE }
+        }) {
+          nodes { rowId title tsvRank embeddingVectorDistance searchScore }
+        }
+      }
+    `, { vec: mlQueryVector });
+        expect(result.errors).toBeUndefined();
+        const nodes = result.data?.allArticles?.nodes ?? [];
+        expect(nodes.length).toBeGreaterThan(0);
+        // Both adapters should be active
+        const hasTsv = nodes.some((n) => n.tsvRank !== null);
+        const hasVector = nodes.some((n) => n.embeddingVectorDistance !== null);
+        expect(hasTsv).toBe(true);
+        expect(hasVector).toBe(true);
+        // searchScore must be normalized [0,1]
+        for (const node of nodes) {
+            expect(node.searchScore).toBeGreaterThanOrEqual(0);
+            expect(node.searchScore).toBeLessThanOrEqual(1);
+        }
+    });
+    // ─── Semantic relevance with real embeddings ───────────────────────────
+    it('ML query ranks ML articles higher than cooking/gardening with real embeddings', async () => {
+        const result = await query(`
+      query($vec: [Float!]!) {
+        allArticles(where: {
+          unifiedSearch: "machine learning"
+          vectorEmbedding: { vector: $vec, metric: COSINE }
+        }) {
+          nodes { rowId title searchScore }
+        }
+      }
+    `, { vec: mlQueryVector });
+        expect(result.errors).toBeUndefined();
+        const nodes = result.data?.allArticles?.nodes ?? [];
+        // ML-related articles (1, 3, 5) should score higher than non-ML (2, 4)
+        const mlArticles = nodes.filter((n) => [1, 3, 5].includes(n.rowId));
+        const nonMlArticles = nodes.filter((n) => [2, 4].includes(n.rowId));
+        if (mlArticles.length > 0 && nonMlArticles.length > 0) {
+            const bestMlScore = Math.max(...mlArticles.map((n) => n.searchScore));
+            const bestNonMlScore = Math.max(...nonMlArticles.map((n) => n.searchScore));
+            expect(bestMlScore).toBeGreaterThan(bestNonMlScore);
+        }
+    });
+    it('cooking query ranks cooking article higher than ML articles with real embeddings', async () => {
+        const result = await query(`
+      query($vec: [Float!]!) {
+        allArticles(where: {
+          unifiedSearch: "Italian pasta cooking"
+          vectorEmbedding: { vector: $vec, metric: COSINE }
+        }) {
+          nodes { rowId title searchScore }
+        }
+      }
+    `, { vec: cookingQueryVector });
+        expect(result.errors).toBeUndefined();
+        const nodes = result.data?.allArticles?.nodes ?? [];
+        // Cooking article (id=2) should rank highest
+        const cookingArticle = nodes.find((n) => n.rowId === 2);
+        const otherArticles = nodes.filter((n) => n.rowId !== 2);
+        if (cookingArticle && otherArticles.length > 0) {
+            const bestOtherScore = Math.max(...otherArticles.map((n) => n.searchScore));
+            expect(cookingArticle.searchScore).toBeGreaterThan(bestOtherScore);
+        }
+    });
+    // ─── Vector-only search with real embeddings ───────────────────────────
+    it('VectorNearbyInput with real embedding returns semantically relevant results', async () => {
+        const result = await query(`
+      query($vec: [Float!]!) {
+        allArticles(where: {
+          vectorEmbedding: { vector: $vec, metric: COSINE }
+        }) {
+          nodes { rowId title embeddingVectorDistance }
+        }
+      }
+    `, { vec: mlQueryVector });
+        expect(result.errors).toBeUndefined();
+        const nodes = result.data?.allArticles?.nodes ?? [];
+        expect(nodes.length).toBe(5);
+        // Nearest to ML query should be ML articles
+        const sorted = [...nodes].sort((a, b) => a.embeddingVectorDistance - b.embeddingVectorDistance);
+        // Top result should be an ML-related article (1, 3, or 5)
+        expect([1, 3, 5]).toContain(sorted[0].rowId);
+    });
+    // ─── RRF boost: text+vector scores higher than text-only ───────────────
+    it('hybrid text+vector search scores higher than text-only for relevant docs', async () => {
+        const textOnly = await query(`
+      query {
+        allArticles(where: { unifiedSearch: "machine learning" }) {
+          nodes { rowId searchScore }
+        }
+      }
+    `);
+        const hybrid = await query(`
+      query($vec: [Float!]!) {
+        allArticles(where: {
+          unifiedSearch: "machine learning"
+          vectorEmbedding: { vector: $vec, metric: COSINE }
+        }) {
+          nodes { rowId searchScore }
+        }
+      }
+    `, { vec: mlQueryVector });
+        expect(textOnly.errors).toBeUndefined();
+        expect(hybrid.errors).toBeUndefined();
+        const doc1TextOnly = textOnly.data?.allArticles?.nodes?.find((n) => n.rowId === 1);
+        const doc1Hybrid = hybrid.data?.allArticles?.nodes?.find((n) => n.rowId === 1);
+        // Doc 1 (ML article) should score at least as high with hybrid
+        if (doc1TextOnly && doc1Hybrid) {
+            expect(doc1Hybrid.searchScore).toBeGreaterThanOrEqual(doc1TextOnly.searchScore);
+        }
+    });
+});

package/__tests__/unified-search-embedding.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Unit tests for LlmTextSearchPlugin's embedTextInWhere function.
+ *
+ * Tests the transformation logic:
+ *   - unifiedSearch: "text" → unifiedSearch: { __text: "text", __vector: [...] }
+ *   - VectorNearbyInput.text → VectorNearbyInput.vector (existing behavior)
+ *
+ * Pure unit tests — no database or Ollama required.
+ */
+export {};

package/__tests__/unified-search-embedding.test.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Unit tests for LlmTextSearchPlugin's embedTextInWhere function.
+ *
+ * Tests the transformation logic:
+ *   - unifiedSearch: "text" → unifiedSearch: { __text: "text", __vector: [...] }
+ *   - VectorNearbyInput.text → VectorNearbyInput.vector (existing behavior)
+ *
+ * Pure unit tests — no database or Ollama required.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const text_search_plugin_1 = require("../../src/plugins/text-search-plugin");
+describe('unifiedSearch embedding integration', () => {
+    const mockVector = [0.1, 0.2, 0.3, 0.4, 0.5];
+    const mockEmbedder = jest.fn(async (_text) => mockVector);
+    const nullEmbedder = jest.fn(async (_text) => null);
+    beforeEach(() => {
+        mockEmbedder.mockClear();
+        nullEmbedder.mockClear();
+    });
+    describe('unifiedSearch text → { __text, __vector } transformation', () => {
+        it('transforms unifiedSearch string to object with __text and __vector', async () => {
+            const where = { unifiedSearch: 'HIPAA compliance' };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toEqual({
+                __text: 'HIPAA compliance',
+                __vector: mockVector,
+            });
+            expect(mockEmbedder).toHaveBeenCalledWith('HIPAA compliance');
+        });
+        it('leaves unifiedSearch as plain string when embedder returns null (graceful degradation)', async () => {
+            const where = { unifiedSearch: 'database normalization' };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true);
+            // Should remain as string — text adapters handle it
+            expect(where.unifiedSearch).toBe('database normalization');
+            expect(nullEmbedder).toHaveBeenCalledWith('database normalization');
+        });
+        it('throws when embedder returns null and no text adapters available', async () => {
+            const where = { unifiedSearch: 'vector only query' };
+            await expect((0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, false)).rejects.toThrow('embedding failed');
+        });
+        it('does not embed empty unifiedSearch strings', async () => {
+            const where = { unifiedSearch: '   ' };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toBe('   ');
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+        it('does not embed null unifiedSearch', async () => {
+            const where = { unifiedSearch: null };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toBeNull();
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+    });
+    describe('VectorNearbyInput text → vector (existing behavior)', () => {
+        it('transforms VectorNearbyInput text to vector', async () => {
+            const where = { vectorEmbedding: { text: 'semantic query' } };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.vectorEmbedding).toEqual({ vector: mockVector });
+            expect(mockEmbedder).toHaveBeenCalledWith('semantic query');
+        });
+        it('removes text field when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'failed query' } };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true);
+            expect(where.vectorEmbedding).toEqual({});
+            expect(nullEmbedder).toHaveBeenCalledWith('failed query');
+        });
+        it('does not modify VectorNearbyInput with existing vector', async () => {
+            const existingVector = [1, 2, 3];
+            const where = { vectorEmbedding: { vector: existingVector, text: 'ignored' } };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            // text + vector present → not modified (vector takes precedence)
+            expect(where.vectorEmbedding.vector).toBe(existingVector);
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+    });
+    describe('combined unifiedSearch + VectorNearbyInput', () => {
+        it('embeds both unifiedSearch and VectorNearbyInput.text in parallel', async () => {
+            const where = {
+                unifiedSearch: 'hybrid search query',
+                vectorEmbedding: { text: 'vector part' },
+            };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toEqual({
+                __text: 'hybrid search query',
+                __vector: mockVector,
+            });
+            expect(where.vectorEmbedding).toEqual({ vector: mockVector });
+            expect(mockEmbedder).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('nested filter structures (AND, OR)', () => {
+        it('handles unifiedSearch inside nested AND/OR filters', async () => {
+            const where = {
+                AND: [
+                    { unifiedSearch: 'first query' },
+                    { unifiedSearch: 'second query' },
+                ],
+            };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true);
+            expect(where.AND[0].unifiedSearch).toEqual({
+                __text: 'first query',
+                __vector: mockVector,
+            });
+            expect(where.AND[1].unifiedSearch).toEqual({
+                __text: 'second query',
+                __vector: mockVector,
+            });
+        });
+    });
+    describe('onQuotaExceeded option', () => {
+        it('degrade mode (default): leaves unifiedSearch as string when embedder returns null', async () => {
+            const where = { unifiedSearch: 'some query' };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true, 'degrade');
+            expect(where.unifiedSearch).toBe('some query');
+        });
+        it('throw mode: throws on unifiedSearch when embedder returns null even with text adapters', async () => {
+            const where = { unifiedSearch: 'some query' };
+            await expect((0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true, 'throw')).rejects.toThrow('onQuotaExceeded is set to \'throw\'');
+        });
+        it('throw mode: throws on VectorNearbyInput.text when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'semantic query' } };
+            await expect((0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true, 'throw')).rejects.toThrow('VectorNearbyInput: embedding failed');
+        });
+        it('degrade mode: silently removes VectorNearbyInput.text when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'failed query' } };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, nullEmbedder, true, 'degrade');
+            expect(where.vectorEmbedding).toEqual({});
+        });
+        it('throw mode: still works normally when embedder succeeds', async () => {
+            const where = { unifiedSearch: 'good query' };
+            await (0, text_search_plugin_1.embedTextInWhere)(where, mockEmbedder, true, 'throw');
+            expect(where.unifiedSearch).toEqual({
+                __text: 'good query',
+                __vector: mockVector,
+            });
+        });
+        it('no text adapters: throws regardless of onQuotaExceeded setting', async () => {
+            const where1 = { unifiedSearch: 'query1' };
+            await expect((0, text_search_plugin_1.embedTextInWhere)(where1, nullEmbedder, false, 'degrade')).rejects.toThrow('No text search adapters available');
+            const where2 = { unifiedSearch: 'query2' };
+            await expect((0, text_search_plugin_1.embedTextInWhere)(where2, nullEmbedder, false, 'throw')).rejects.toThrow('No text search adapters available');
+        });
+    });
+    describe('apply function object shape handling', () => {
+        it('plugin.ts apply function handles { __text, __vector } correctly', () => {
+            // Simulate what the apply function does with the transformed value
+            const val = { __text: 'HIPAA compliance', __vector: [0.1, 0.2, 0.3] };
+            let text;
+            let vector = null;
+            if (typeof val === 'object' && val.__text) {
+                text = val.__text;
+                vector = val.__vector ?? null;
+            }
+            else {
+                text = typeof val === 'string' ? val : String(val);
+            }
+            expect(text).toBe('HIPAA compliance');
+            expect(vector).toEqual([0.1, 0.2, 0.3]);
+        });
+        it('plugin.ts apply function handles plain string correctly', () => {
+            const val = 'plain text search';
+            let text;
+            let vector = null;
+            if (typeof val === 'object' && val.__text) {
+                text = val.__text;
+                vector = val.__vector ?? null;
+            }
+            else {
+                text = typeof val === 'string' ? val : String(val);
+            }
+            expect(text).toBe('plain text search');
+            expect(vector).toBeNull();
+        });
+    });
+});

package/embedder.d.ts

@@ -4,12 +4,32 @@
  * Provides a provider-based architecture for converting text into vector
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
- * The embedder is resolved at request time from:
- *   1. The `llm_module` api_modules configuration (per-database)
- *   2. The preset's `defaultEmbedder` option (fallback for dev/testing)
- *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ * Per-request model/baseUrl overrides are read from AsyncLocalStorage
+ * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * the database's `llm_module` config via `ctx.useLlm()`. This means
+ * the same embedder function — and its metering wrapper — handle every
+ * request, regardless of which tenant's model config applies.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type { EmbedderConfig, EmbedderFunction, LlmModuleData } from './types';
+/**
+ * Per-request LLM config overrides from the database's llm_module.
+ * Only string parameters — the embedder client itself stays the same.
+ */
+export interface LlmConfigOverrides {
+    embeddingModel?: string;
+    embeddingBaseUrl?: string;
+    chatModel?: string;
+    chatBaseUrl?: string;
+}
+/**
+ * AsyncLocalStorage for per-request LLM config overrides.
+ *
+ * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * read by the embedder at call time. The metering wrapper sits between
+ * them and is completely unaware — it just wraps the same function.
+ */
+export declare const llmConfigStore: AsyncLocalStorage<LlmConfigOverrides>;
 /**
  * Build an embedder function from a config object.
  *