modelfusion 0.32.0 → 0.33.0

package/README.md

@@ -365,7 +365,7 @@ const reconstructedText = await tokenizer.detokenize(tokens);
 
 Providers: [OpenAI](https://modelfusion.dev/integration/model-provider/openai), [Cohere](https://modelfusion.dev/integration/model-provider/cohere), [Llama.cpp](https://modelfusion.dev/integration/model-provider/llamacpp)
 
-### [Upserting and Retrieving Text Chunks from Vector Indices](https://modelfusion.dev/guide/text-chunks)
+### [Upserting and Retrieving Objects from Vector Indices](https://modelfusion.dev/guide/vector-index)
 
 ```ts
 const texts = [
@@ -374,21 +374,22 @@ const texts = [
   // ...
 ];
 
-const vectorIndex = new MemoryVectorIndex<TextChunk>();
+const vectorIndex = new MemoryVectorIndex<string>();
 const embeddingModel = new OpenAITextEmbeddingModel({
   model: "text-embedding-ada-002",
 });
 
 // update an index - usually done as part of an ingestion process:
-await upsertTextChunks({
+await upsertIntoVectorIndex({
   vectorIndex,
   embeddingModel,
-  chunks: texts.map((text) => ({ text })),
+  objects: texts,
+  getValueToEmbed: (text) => text,
 });
 
 // retrieve text chunks from the vector index - usually done at query time:
-const { chunks } = await retrieveTextChunks(
-  new SimilarTextChunksFromVectorIndexRetriever({
+const retrievedTexts = await retrieve(
+  new VectorIndexRetriever({
     vectorIndex,
     embeddingModel,
     maxResults: 3,

package/index.cjs

@@ -21,6 +21,7 @@ __exportStar(require("./model-function/index.cjs"), exports);
 __exportStar(require("./model-provider/index.cjs"), exports);
 __exportStar(require("./observability/index.cjs"), exports);
 __exportStar(require("./prompt/index.cjs"), exports);
+__exportStar(require("./retriever/index.cjs"), exports);
 __exportStar(require("./text-chunk/index.cjs"), exports);
 __exportStar(require("./tool/index.cjs"), exports);
 __exportStar(require("./util/index.cjs"), exports);

package/index.d.ts

@@ -5,6 +5,7 @@ export * from "./model-function/index.js";
 export * from "./model-provider/index.js";
 export * from "./observability/index.js";
 export * from "./prompt/index.js";
+export * from "./retriever/index.js";
 export * from "./text-chunk/index.js";
 export * from "./tool/index.js";
 export * from "./util/index.js";

package/index.js

@@ -5,6 +5,7 @@ export * from "./model-function/index.js";
 export * from "./model-provider/index.js";
 export * from "./observability/index.js";
 export * from "./prompt/index.js";
+export * from "./retriever/index.js";
 export * from "./text-chunk/index.js";
 export * from "./tool/index.js";
 export * from "./util/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modelfusion",
   "description": "Build multimodal applications, chatbots, and agents with JavaScript and TypeScript.",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "author": "Lars Grammel",
   "license": "MIT",
   "keywords": [

package/retriever/Retriever.d.ts

@@ -0,0 +1,7 @@
+import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
+export interface RetrieverSettings {
+}
+export interface Retriever<OBJECT, QUERY, SETTINGS extends RetrieverSettings> {
+    retrieve(query: QUERY, options?: ModelFunctionOptions<RetrieverSettings>): Promise<OBJECT[]>;
+    withSettings(additionalSettings: Partial<SETTINGS>): this;
+}

package/retriever/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Retriever.cjs"), exports);
+__exportStar(require("./retrieve.cjs"), exports);

package/retriever/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Retriever.js";
+export * from "./retrieve.js";

package/retriever/index.js

@@ -0,0 +1,2 @@
+export * from "./Retriever.js";
+export * from "./retrieve.js";

package/retriever/retrieve.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieve = void 0;
+async function retrieve(retriever, query, options) {
+    // TODO add error handling, events, duration tracking, etc.
+    // TODO metadata handling
+    return retriever.retrieve(query, options);
+}
+exports.retrieve = retrieve;

package/retriever/retrieve.d.ts

@@ -0,0 +1,3 @@
+import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
+import { Retriever, RetrieverSettings } from "./Retriever.js";
+export declare function retrieve<OBJECT, QUERY, SETTINGS extends RetrieverSettings>(retriever: Retriever<OBJECT, QUERY, SETTINGS>, query: QUERY, options?: ModelFunctionOptions<SETTINGS>): Promise<OBJECT[]>;

package/retriever/retrieve.js

@@ -0,0 +1,5 @@
+export async function retrieve(retriever, query, options) {
+    // TODO add error handling, events, duration tracking, etc.
+    // TODO metadata handling
+    return retriever.retrieve(query, options);
+}

package/text-chunk/index.cjs

@@ -14,12 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./SimilarTextChunksFromVectorIndexRetriever.cjs"), exports);
 __exportStar(require("./TextChunk.cjs"), exports);
-__exportStar(require("./retrieve-text-chunks/TextChunkRetriever.cjs"), exports);
-__exportStar(require("./retrieve-text-chunks/retrieveTextChunks.cjs"), exports);
 __exportStar(require("./split/SplitFunction.cjs"), exports);
 __exportStar(require("./split/splitOnSeparator.cjs"), exports);
 __exportStar(require("./split/splitRecursively.cjs"), exports);
 __exportStar(require("./split/splitTextChunks.cjs"), exports);
-__exportStar(require("./upsertTextChunks.cjs"), exports);

package/text-chunk/index.d.ts

@@ -1,9 +1,5 @@
-export * from "./SimilarTextChunksFromVectorIndexRetriever.js";
 export * from "./TextChunk.js";
-export * from "./retrieve-text-chunks/TextChunkRetriever.js";
-export * from "./retrieve-text-chunks/retrieveTextChunks.js";
 export * from "./split/SplitFunction.js";
 export * from "./split/splitOnSeparator.js";
 export * from "./split/splitRecursively.js";
 export * from "./split/splitTextChunks.js";
-export * from "./upsertTextChunks.js";

package/text-chunk/index.js

@@ -1,9 +1,5 @@
-export * from "./SimilarTextChunksFromVectorIndexRetriever.js";
 export * from "./TextChunk.js";
-export * from "./retrieve-text-chunks/TextChunkRetriever.js";
-export * from "./retrieve-text-chunks/retrieveTextChunks.js";
 export * from "./split/SplitFunction.js";
 export * from "./split/splitOnSeparator.js";
 export * from "./split/splitRecursively.js";
 export * from "./split/splitTextChunks.js";
-export * from "./upsertTextChunks.js";

package/{text-chunk/SimilarTextChunksFromVectorIndexRetriever.cjs → vector-index/VectorIndexRetriever.cjs}

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimilarTextChunksFromVectorIndexRetriever = void 0;
+exports.VectorIndexRetriever = void 0;
 const embedText_js_1 = require("../model-function/embed-text/embedText.cjs");
-class SimilarTextChunksFromVectorIndexRetriever {
+class VectorIndexRetriever {
     constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }) {
         Object.defineProperty(this, "vectorIndex", {
             enumerable: true,
@@ -29,9 +29,9 @@ class SimilarTextChunksFromVectorIndexRetriever {
             similarityThreshold,
         };
     }
-    async retrieveTextChunks(query, options) {
+    async retrieve(query, options) {
         if (options?.settings != null) {
-            return this.withSettings(options.settings).retrieveTextChunks(query, {
+            return this.withSettings(options.settings).retrieve(query, {
                 functionId: options.functionId,
                 observers: options.observers,
                 run: options.run,
@@ -49,10 +49,10 @@ class SimilarTextChunksFromVectorIndexRetriever {
         return queryResult.map((item) => item.data);
     }
     withSettings(additionalSettings) {
-        return new SimilarTextChunksFromVectorIndexRetriever(Object.assign({}, this.settings, additionalSettings, {
+        return new VectorIndexRetriever(Object.assign({}, this.settings, additionalSettings, {
             vectorIndex: this.vectorIndex,
             embeddingModel: this.embeddingModel,
         }));
     }
 }
-exports.SimilarTextChunksFromVectorIndexRetriever = SimilarTextChunksFromVectorIndexRetriever;
+exports.VectorIndexRetriever = VectorIndexRetriever;

package/vector-index/VectorIndexRetriever.d.ts

@@ -0,0 +1,19 @@
+import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
+import { TextEmbeddingModel, TextEmbeddingModelSettings } from "../model-function/embed-text/TextEmbeddingModel.js";
+import { Retriever, RetrieverSettings } from "../retriever/Retriever.js";
+import { VectorIndex } from "./VectorIndex.js";
+export interface VectorIndexRetrieverSettings {
+    maxResults?: number;
+    similarityThreshold?: number;
+}
+export declare class VectorIndexRetriever<OBJECT, INDEX> implements Retriever<OBJECT, string, VectorIndexRetrieverSettings> {
+    private readonly vectorIndex;
+    private readonly embeddingModel;
+    private readonly settings;
+    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }: {
+        vectorIndex: VectorIndex<OBJECT, INDEX>;
+        embeddingModel: TextEmbeddingModel<unknown, TextEmbeddingModelSettings>;
+    } & VectorIndexRetrieverSettings);
+    retrieve(query: string, options?: ModelFunctionOptions<RetrieverSettings>): Promise<OBJECT[]>;
+    withSettings(additionalSettings: Partial<VectorIndexRetrieverSettings>): this;
+}

package/{text-chunk/SimilarTextChunksFromVectorIndexRetriever.js → vector-index/VectorIndexRetriever.js}

@@ -1,5 +1,5 @@
 import { embedText } from "../model-function/embed-text/embedText.js";
-export class SimilarTextChunksFromVectorIndexRetriever {
+export class VectorIndexRetriever {
     constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }) {
         Object.defineProperty(this, "vectorIndex", {
             enumerable: true,
@@ -26,9 +26,9 @@ export class SimilarTextChunksFromVectorIndexRetriever {
             similarityThreshold,
         };
     }
-    async retrieveTextChunks(query, options) {
+    async retrieve(query, options) {
         if (options?.settings != null) {
-            return this.withSettings(options.settings).retrieveTextChunks(query, {
+            return this.withSettings(options.settings).retrieve(query, {
                 functionId: options.functionId,
                 observers: options.observers,
                 run: options.run,
@@ -46,7 +46,7 @@ export class SimilarTextChunksFromVectorIndexRetriever {
         return queryResult.map((item) => item.data);
     }
     withSettings(additionalSettings) {
-        return new SimilarTextChunksFromVectorIndexRetriever(Object.assign({}, this.settings, additionalSettings, {
+        return new VectorIndexRetriever(Object.assign({}, this.settings, additionalSettings, {
             vectorIndex: this.vectorIndex,
             embeddingModel: this.embeddingModel,
         }));

package/vector-index/index.cjs

@@ -15,5 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./VectorIndex.cjs"), exports);
+__exportStar(require("./VectorIndexRetriever.cjs"), exports);
 __exportStar(require("./memory/MemoryVectorIndex.cjs"), exports);
 __exportStar(require("./pinecone/PineconeVectorIndex.cjs"), exports);
+__exportStar(require("./upsertIntoVectorIndex.cjs"), exports);

package/vector-index/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./VectorIndex.js";
+export * from "./VectorIndexRetriever.js";
 export * from "./memory/MemoryVectorIndex.js";
 export * from "./pinecone/PineconeVectorIndex.js";
+export * from "./upsertIntoVectorIndex.js";

package/vector-index/index.js

@@ -1,3 +1,5 @@
 export * from "./VectorIndex.js";
+export * from "./VectorIndexRetriever.js";
 export * from "./memory/MemoryVectorIndex.js";
 export * from "./pinecone/PineconeVectorIndex.js";
+export * from "./upsertIntoVectorIndex.js";

package/vector-index/upsertIntoVectorIndex.cjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertIntoVectorIndex = void 0;
+const nanoid_1 = require("nanoid");
+const embedText_js_1 = require("../model-function/embed-text/embedText.cjs");
+async function upsertIntoVectorIndex({ vectorIndex, embeddingModel, generateId = nanoid_1.nanoid, objects, getValueToEmbed, getId, }, options) {
+    // many embedding models support bulk embedding, so we first embed all texts:
+    const embeddings = await (0, embedText_js_1.embedTexts)(embeddingModel, objects.map(getValueToEmbed), options);
+    await vectorIndex.upsertMany(objects.map((object, i) => ({
+        id: getId?.(object, i) ?? generateId(),
+        vector: embeddings[i],
+        data: object,
+    })));
+}
+exports.upsertIntoVectorIndex = upsertIntoVectorIndex;

package/vector-index/upsertIntoVectorIndex.d.ts

@@ -0,0 +1,11 @@
+import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
+import { TextEmbeddingModel, TextEmbeddingModelSettings } from "../model-function/embed-text/TextEmbeddingModel.js";
+import { VectorIndex } from "./VectorIndex.js";
+export declare function upsertIntoVectorIndex<OBJECT, SETTINGS extends TextEmbeddingModelSettings>({ vectorIndex, embeddingModel, generateId, objects, getValueToEmbed, getId, }: {
+    vectorIndex: VectorIndex<OBJECT, unknown>;
+    embeddingModel: TextEmbeddingModel<unknown, SETTINGS>;
+    generateId?: () => string;
+    objects: OBJECT[];
+    getValueToEmbed: (object: OBJECT, index: number) => string;
+    getId?: (object: OBJECT, index: number) => string | undefined;
+}, options?: ModelFunctionOptions<SETTINGS>): Promise<void>;

package/vector-index/upsertIntoVectorIndex.js

@@ -0,0 +1,11 @@
+import { nanoid as createId } from "nanoid";
+import { embedTexts } from "../model-function/embed-text/embedText.js";
+export async function upsertIntoVectorIndex({ vectorIndex, embeddingModel, generateId = createId, objects, getValueToEmbed, getId, }, options) {
+    // many embedding models support bulk embedding, so we first embed all texts:
+    const embeddings = await embedTexts(embeddingModel, objects.map(getValueToEmbed), options);
+    await vectorIndex.upsertMany(objects.map((object, i) => ({
+        id: getId?.(object, i) ?? generateId(),
+        vector: embeddings[i],
+        data: object,
+    })));
+}

package/text-chunk/SimilarTextChunksFromVectorIndexRetriever.d.ts

@@ -1,20 +0,0 @@
-import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
-import { TextEmbeddingModel, TextEmbeddingModelSettings } from "../model-function/embed-text/TextEmbeddingModel.js";
-import { TextChunk } from "./TextChunk.js";
-import { TextChunkRetriever, TextChunkRetrieverSettings } from "./retrieve-text-chunks/TextChunkRetriever.js";
-import { VectorIndex } from "../vector-index/VectorIndex.js";
-export interface SimilarTextChunksFromVectorIndexRetrieverSettings {
-    maxResults?: number;
-    similarityThreshold?: number;
-}
-export declare class SimilarTextChunksFromVectorIndexRetriever<CHUNK extends TextChunk, INDEX, SETTINGS extends TextEmbeddingModelSettings> implements TextChunkRetriever<CHUNK, string, SimilarTextChunksFromVectorIndexRetrieverSettings> {
-    private readonly vectorIndex;
-    private readonly embeddingModel;
-    private readonly settings;
-    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }: {
-        vectorIndex: VectorIndex<CHUNK, INDEX>;
-        embeddingModel: TextEmbeddingModel<unknown, SETTINGS>;
-    } & SimilarTextChunksFromVectorIndexRetrieverSettings);
-    retrieveTextChunks(query: string, options?: ModelFunctionOptions<TextChunkRetrieverSettings>): Promise<CHUNK[]>;
-    withSettings(additionalSettings: Partial<SimilarTextChunksFromVectorIndexRetrieverSettings>): this;
-}

package/text-chunk/retrieve-text-chunks/TextChunkRetriever.d.ts

@@ -1,8 +0,0 @@
-import { ModelFunctionOptions } from "../../model-function/ModelFunctionOptions.js";
-import { TextChunk } from "../TextChunk.js";
-export interface TextChunkRetrieverSettings {
-}
-export interface TextChunkRetriever<CHUNK extends TextChunk, QUERY, SETTINGS extends TextChunkRetrieverSettings> {
-    retrieveTextChunks(query: QUERY, options?: ModelFunctionOptions<TextChunkRetrieverSettings>): Promise<CHUNK[]>;
-    withSettings(additionalSettings: Partial<SETTINGS>): this;
-}

package/text-chunk/retrieve-text-chunks/retrieveTextChunks.cjs

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.retrieveTextChunks = void 0;
-async function retrieveTextChunks(retriever, query, options) {
-    // TODO add error handling, events, duration tracking, etc.
-    return {
-        chunks: await retriever.retrieveTextChunks(query, options),
-    };
-}
-exports.retrieveTextChunks = retrieveTextChunks;

package/text-chunk/retrieve-text-chunks/retrieveTextChunks.d.ts

@@ -1,6 +0,0 @@
-import { ModelFunctionOptions } from "../../model-function/ModelFunctionOptions.js";
-import { TextChunk } from "../TextChunk.js";
-import { TextChunkRetriever, TextChunkRetrieverSettings } from "./TextChunkRetriever.js";
-export declare function retrieveTextChunks<CHUNK extends TextChunk, QUERY, SETTINGS extends TextChunkRetrieverSettings>(retriever: TextChunkRetriever<CHUNK, QUERY, SETTINGS>, query: QUERY, options?: ModelFunctionOptions<SETTINGS>): Promise<{
-    chunks: CHUNK[];
-}>;

package/text-chunk/retrieve-text-chunks/retrieveTextChunks.js

@@ -1,6 +0,0 @@
-export async function retrieveTextChunks(retriever, query, options) {
-    // TODO add error handling, events, duration tracking, etc.
-    return {
-        chunks: await retriever.retrieveTextChunks(query, options),
-    };
-}

package/text-chunk/upsertTextChunks.cjs

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.upsertTextChunks = void 0;
-const nanoid_1 = require("nanoid");
-const embedText_js_1 = require("../model-function/embed-text/embedText.cjs");
-async function upsertTextChunks({ vectorIndex, embeddingModel, generateId = nanoid_1.nanoid, chunks, ids, }, options) {
-    // many embedding models support bulk embedding, so we first embed all texts:
-    const embeddings = await (0, embedText_js_1.embedTexts)(embeddingModel, chunks.map((chunk) => chunk.text), options);
-    await vectorIndex.upsertMany(chunks.map((chunk, i) => ({
-        id: ids?.[i] ?? generateId(),
-        vector: embeddings[i],
-        data: chunk,
-    })));
-}
-exports.upsertTextChunks = upsertTextChunks;

package/text-chunk/upsertTextChunks.d.ts

@@ -1,11 +0,0 @@
-import { ModelFunctionOptions } from "../model-function/ModelFunctionOptions.js";
-import { TextEmbeddingModel, TextEmbeddingModelSettings } from "../model-function/embed-text/TextEmbeddingModel.js";
-import { TextChunk } from "./TextChunk.js";
-import { VectorIndex } from "../vector-index/VectorIndex.js";
-export declare function upsertTextChunks<CHUNK extends TextChunk, SETTINGS extends TextEmbeddingModelSettings>({ vectorIndex, embeddingModel, generateId, chunks, ids, }: {
-    vectorIndex: VectorIndex<CHUNK, unknown>;
-    embeddingModel: TextEmbeddingModel<unknown, SETTINGS>;
-    generateId?: () => string;
-    chunks: CHUNK[];
-    ids?: Array<string | undefined>;
-}, options?: ModelFunctionOptions<SETTINGS>): Promise<void>;

package/text-chunk/upsertTextChunks.js

@@ -1,11 +0,0 @@
-import { nanoid as createId } from "nanoid";
-import { embedTexts } from "../model-function/embed-text/embedText.js";
-export async function upsertTextChunks({ vectorIndex, embeddingModel, generateId = createId, chunks, ids, }, options) {
-    // many embedding models support bulk embedding, so we first embed all texts:
-    const embeddings = await embedTexts(embeddingModel, chunks.map((chunk) => chunk.text), options);
-    await vectorIndex.upsertMany(chunks.map((chunk, i) => ({
-        id: ids?.[i] ?? generateId(),
-        vector: embeddings[i],
-        data: chunk,
-    })));
-}