modelfusion 0.35.2 → 0.37.0

package/core/FunctionEvent.d.ts

@@ -1,5 +1,6 @@
-import { ExecuteToolFinishedEvent, ExecuteToolStartedEvent } from "../tool/ExecuteToolEvent.js";
 import { ModelCallFinishedEvent, ModelCallStartedEvent } from "../model-function/ModelCallEvent.js";
+import { RetrieveFinishedEvent, RetrieveStartedEvent } from "../retriever/RetrieveEvent.js";
+import { ExecuteToolFinishedEvent, ExecuteToolStartedEvent } from "../tool/ExecuteToolEvent.js";
 export interface BaseFunctionEvent {
     /**
      * Unique identifier for the function call.
@@ -72,4 +73,4 @@ export interface BaseFunctionFinishedEvent extends BaseFunctionEvent {
      */
     result: BaseFunctionFinishedEventResult;
 }
-export type FunctionEvent = ModelCallStartedEvent | ExecuteToolStartedEvent | ModelCallFinishedEvent | ExecuteToolFinishedEvent;
+export type FunctionEvent = ModelCallStartedEvent | ExecuteToolStartedEvent | RetrieveStartedEvent | ModelCallFinishedEvent | ExecuteToolFinishedEvent | RetrieveFinishedEvent;

package/core/getFunctionCallLogger.cjs

@@ -17,14 +17,15 @@ function getFunctionCallLogger(logging) {
 exports.getFunctionCallLogger = getFunctionCallLogger;
 const basicTextObserver = {
     onFunctionEvent(event) {
+        const text = `[${event.timestamp.toISOString()}] ${event.callId}${event.functionId != null ? ` (${event.functionId})` : ""} - ${event.functionType} ${event.eventType}`;
         // log based on event type:
         switch (event.eventType) {
             case "started": {
-                console.log(`[${event.timestamp.toISOString()}] ${event.callId} - ${event.functionType} ${event.eventType}`);
+                console.log(text);
                 break;
             }
             case "finished": {
-                console.log(`[${event.timestamp.toISOString()}] ${event.callId} - ${event.functionType} ${event.eventType} in ${event.durationInMs}ms`);
+                console.log(`${text} in ${event.durationInMs}ms`);
                 break;
             }
         }

package/core/getFunctionCallLogger.js

@@ -13,14 +13,15 @@ export function getFunctionCallLogger(logging) {
 }
 const basicTextObserver = {
     onFunctionEvent(event) {
+        const text = `[${event.timestamp.toISOString()}] ${event.callId}${event.functionId != null ? ` (${event.functionId})` : ""} - ${event.functionType} ${event.eventType}`;
         // log based on event type:
         switch (event.eventType) {
             case "started": {
-                console.log(`[${event.timestamp.toISOString()}] ${event.callId} - ${event.functionType} ${event.eventType}`);
+                console.log(text);
                 break;
             }
             case "finished": {
-                console.log(`[${event.timestamp.toISOString()}] ${event.callId} - ${event.functionType} ${event.eventType} in ${event.durationInMs}ms`);
+                console.log(`${text} in ${event.durationInMs}ms`);
                 break;
             }
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modelfusion",
   "description": "Build multimodal applications, chatbots, and agents with JavaScript and TypeScript.",
-  "version": "0.35.2",
+  "version": "0.37.0",
   "author": "Lars Grammel",
   "license": "MIT",
   "keywords": [
@@ -73,7 +73,7 @@
     "husky": "^8.0.3",
     "lint-staged": "14.0.1",
     "prettier": "3.0.3",
-    "rimraf": "5.0.1",
+    "rimraf": "5.0.5",
     "typescript": "5.2.2",
     "vitest": "^0.34.5"
   },

package/retriever/RetrieveEvent.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/retriever/RetrieveEvent.d.ts

@@ -0,0 +1,10 @@
+import { BaseFunctionFinishedEvent, BaseFunctionStartedEvent } from "../core/FunctionEvent.js";
+export interface RetrieveStartedEvent extends BaseFunctionStartedEvent {
+    functionType: "retrieve";
+    query: unknown;
+}
+export interface RetrieveFinishedEvent extends BaseFunctionFinishedEvent {
+    functionType: "retrieve";
+    query: unknown;
+    results: unknown;
+}

package/retriever/RetrieveEvent.js

@@ -0,0 +1 @@
+export {};

package/retriever/retrieve.cjs

@@ -1,9 +1,77 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retrieve = void 0;
+const nanoid_1 = require("nanoid");
+const FunctionEventSource_js_1 = require("../core/FunctionEventSource.cjs");
+const GlobalFunctionLogging_js_1 = require("../core/GlobalFunctionLogging.cjs");
+const GlobalFunctionObservers_js_1 = require("../core/GlobalFunctionObservers.cjs");
+const AbortError_js_1 = require("../core/api/AbortError.cjs");
+const getFunctionCallLogger_js_1 = require("../core/getFunctionCallLogger.cjs");
+const DurationMeasurement_js_1 = require("../util/DurationMeasurement.cjs");
+const runSafe_js_1 = require("../util/runSafe.cjs");
 async function retrieve(retriever, query, options) {
-    // TODO add error handling, events, duration tracking, etc.
-    // TODO metadata handling
-    return retriever.retrieve(query, options);
+    const run = options?.run;
+    const eventSource = new FunctionEventSource_js_1.FunctionEventSource({
+        observers: [
+            ...(0, getFunctionCallLogger_js_1.getFunctionCallLogger)(options?.logging ?? (0, GlobalFunctionLogging_js_1.getGlobalFunctionLogging)()),
+            ...(0, GlobalFunctionObservers_js_1.getGlobalFunctionObservers)(),
+            ...(run?.functionObserver != null ? [run.functionObserver] : []),
+            ...(options?.observers ?? []),
+        ],
+        errorHandler: run?.errorHandler,
+    });
+    const durationMeasurement = (0, DurationMeasurement_js_1.startDurationMeasurement)();
+    const startMetadata = {
+        functionType: "retrieve",
+        callId: `call-${(0, nanoid_1.nanoid)()}`,
+        runId: run?.runId,
+        sessionId: run?.sessionId,
+        userId: run?.userId,
+        functionId: options?.functionId,
+        query,
+        timestamp: durationMeasurement.startDate,
+        startTimestamp: durationMeasurement.startDate,
+    };
+    eventSource.notify({
+        eventType: "started",
+        ...startMetadata,
+    });
+    const result = await (0, runSafe_js_1.runSafe)(() => retriever.retrieve(query, options));
+    const finishMetadata = {
+        eventType: "finished",
+        ...startMetadata,
+        finishTimestamp: new Date(),
+        durationInMs: durationMeasurement.durationInMs,
+    };
+    if (!result.ok) {
+        if (result.isAborted) {
+            eventSource.notify({
+                ...finishMetadata,
+                eventType: "finished",
+                result: {
+                    status: "abort",
+                },
+            });
+            throw new AbortError_js_1.AbortError();
+        }
+        eventSource.notify({
+            ...finishMetadata,
+            eventType: "finished",
+            result: {
+                status: "error",
+                error: result.error,
+            },
+        });
+        throw result.error;
+    }
+    eventSource.notify({
+        ...finishMetadata,
+        eventType: "finished",
+        result: {
+            status: "success",
+            output: result.output,
+        },
+    });
+    return result.output;
 }
 exports.retrieve = retrieve;

package/retriever/retrieve.js

@@ -1,5 +1,73 @@
+import { nanoid as createId } from "nanoid";
+import { FunctionEventSource } from "../core/FunctionEventSource.js";
+import { getGlobalFunctionLogging } from "../core/GlobalFunctionLogging.js";
+import { getGlobalFunctionObservers } from "../core/GlobalFunctionObservers.js";
+import { AbortError } from "../core/api/AbortError.js";
+import { getFunctionCallLogger } from "../core/getFunctionCallLogger.js";
+import { startDurationMeasurement } from "../util/DurationMeasurement.js";
+import { runSafe } from "../util/runSafe.js";
 export async function retrieve(retriever, query, options) {
-    // TODO add error handling, events, duration tracking, etc.
-    // TODO metadata handling
-    return retriever.retrieve(query, options);
+    const run = options?.run;
+    const eventSource = new FunctionEventSource({
+        observers: [
+            ...getFunctionCallLogger(options?.logging ?? getGlobalFunctionLogging()),
+            ...getGlobalFunctionObservers(),
+            ...(run?.functionObserver != null ? [run.functionObserver] : []),
+            ...(options?.observers ?? []),
+        ],
+        errorHandler: run?.errorHandler,
+    });
+    const durationMeasurement = startDurationMeasurement();
+    const startMetadata = {
+        functionType: "retrieve",
+        callId: `call-${createId()}`,
+        runId: run?.runId,
+        sessionId: run?.sessionId,
+        userId: run?.userId,
+        functionId: options?.functionId,
+        query,
+        timestamp: durationMeasurement.startDate,
+        startTimestamp: durationMeasurement.startDate,
+    };
+    eventSource.notify({
+        eventType: "started",
+        ...startMetadata,
+    });
+    const result = await runSafe(() => retriever.retrieve(query, options));
+    const finishMetadata = {
+        eventType: "finished",
+        ...startMetadata,
+        finishTimestamp: new Date(),
+        durationInMs: durationMeasurement.durationInMs,
+    };
+    if (!result.ok) {
+        if (result.isAborted) {
+            eventSource.notify({
+                ...finishMetadata,
+                eventType: "finished",
+                result: {
+                    status: "abort",
+                },
+            });
+            throw new AbortError();
+        }
+        eventSource.notify({
+            ...finishMetadata,
+            eventType: "finished",
+            result: {
+                status: "error",
+                error: result.error,
+            },
+        });
+        throw result.error;
+    }
+    eventSource.notify({
+        ...finishMetadata,
+        eventType: "finished",
+        result: {
+            status: "success",
+            output: result.output,
+        },
+    });
+    return result.output;
 }

package/vector-index/VectorIndex.d.ts

@@ -1,5 +1,5 @@
 import { Vector } from "../core/Vector.js";
-export interface VectorIndex<DATA, INDEX> {
+export interface VectorIndex<DATA, INDEX, FILTER> {
     upsertMany(data: Array<{
         id: string;
         vector: Vector;
@@ -9,6 +9,7 @@ export interface VectorIndex<DATA, INDEX> {
         queryVector: Vector;
         maxResults: number;
         similarityThreshold?: number;
+        filter?: FILTER;
     }): Promise<Array<{
         id: string;
         data: DATA;

package/vector-index/VectorIndexRetriever.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VectorIndexRetriever = void 0;
 const embedText_js_1 = require("../model-function/embed-text/embedText.cjs");
 class VectorIndexRetriever {
-    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }) {
+    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, filter, }) {
         Object.defineProperty(this, "vectorIndex", {
             enumerable: true,
             configurable: true,
@@ -27,6 +27,7 @@ class VectorIndexRetriever {
         this.settings = {
             maxResults,
             similarityThreshold,
+            filter,
         };
     }
     async retrieve(query, options) {
@@ -37,6 +38,11 @@ class VectorIndexRetriever {
                 run: options.run,
             });
         }
+        let filter = this.settings?.filter;
+        if (typeof query === "object") {
+            filter = query.filter ?? filter; // use filter from query if available
+            query = query.text;
+        }
         const embedding = await (0, embedText_js_1.embedText)(this.embeddingModel, query, {
             functionId: options?.functionId,
             run: options?.run,
@@ -45,6 +51,7 @@ class VectorIndexRetriever {
             queryVector: embedding,
             maxResults: this.settings.maxResults ?? 1,
             similarityThreshold: this.settings.similarityThreshold,
+            filter,
         });
         return queryResult.map((item) => item.data);
     }

package/vector-index/VectorIndexRetriever.d.ts

@@ -2,18 +2,24 @@ 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 {
+export interface VectorIndexRetrieverSettings<FILTER> {
     maxResults?: number;
     similarityThreshold?: number;
+    filter?: FILTER;
 }
-export declare class VectorIndexRetriever<OBJECT, INDEX> implements Retriever<OBJECT, string, VectorIndexRetrieverSettings> {
+type VectorIndexRetrieverQuery<FILTER> = string | {
+    text: string;
+    filter?: FILTER;
+};
+export declare class VectorIndexRetriever<OBJECT, INDEX, FILTER> implements Retriever<OBJECT, VectorIndexRetrieverQuery<FILTER>, VectorIndexRetrieverSettings<FILTER>> {
     private readonly vectorIndex;
     private readonly embeddingModel;
     private readonly settings;
-    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }: {
-        vectorIndex: VectorIndex<OBJECT, INDEX>;
+    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, filter, }: {
+        vectorIndex: VectorIndex<OBJECT, INDEX, FILTER>;
         embeddingModel: TextEmbeddingModel<unknown, TextEmbeddingModelSettings>;
-    } & VectorIndexRetrieverSettings);
-    retrieve(query: string, options?: ModelFunctionOptions<RetrieverSettings>): Promise<OBJECT[]>;
-    withSettings(additionalSettings: Partial<VectorIndexRetrieverSettings>): this;
+    } & VectorIndexRetrieverSettings<FILTER>);
+    retrieve(query: VectorIndexRetrieverQuery<FILTER>, options?: ModelFunctionOptions<RetrieverSettings>): Promise<OBJECT[]>;
+    withSettings(additionalSettings: Partial<VectorIndexRetrieverSettings<FILTER>>): this;
 }
+export {};

package/vector-index/VectorIndexRetriever.js

@@ -1,6 +1,6 @@
 import { embedText } from "../model-function/embed-text/embedText.js";
 export class VectorIndexRetriever {
-    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, }) {
+    constructor({ vectorIndex, embeddingModel, maxResults, similarityThreshold, filter, }) {
         Object.defineProperty(this, "vectorIndex", {
             enumerable: true,
             configurable: true,
@@ -24,6 +24,7 @@ export class VectorIndexRetriever {
         this.settings = {
             maxResults,
             similarityThreshold,
+            filter,
         };
     }
     async retrieve(query, options) {
@@ -34,6 +35,11 @@ export class VectorIndexRetriever {
                 run: options.run,
             });
         }
+        let filter = this.settings?.filter;
+        if (typeof query === "object") {
+            filter = query.filter ?? filter; // use filter from query if available
+            query = query.text;
+        }
         const embedding = await embedText(this.embeddingModel, query, {
             functionId: options?.functionId,
             run: options?.run,
@@ -42,6 +48,7 @@ export class VectorIndexRetriever {
             queryVector: embedding,
             maxResults: this.settings.maxResults ?? 1,
             similarityThreshold: this.settings.similarityThreshold,
+            filter,
         });
         return queryResult.map((item) => item.data);
     }

package/vector-index/memory/MemoryVectorIndex.cjs

@@ -40,8 +40,9 @@ class MemoryVectorIndex {
             this.entries.set(entry.id, entry);
         }
     }
-    async queryByVector({ queryVector, similarityThreshold, maxResults, }) {
+    async queryByVector({ queryVector, similarityThreshold, maxResults, filter, }) {
         const results = [...this.entries.values()]
+            .filter((value) => filter?.(value.data) ?? true)
             .map((entry) => ({
             id: entry.id,
             similarity: (0, cosineSimilarity_js_1.cosineSimilarity)(entry.vector, queryVector),

package/vector-index/memory/MemoryVectorIndex.d.ts

@@ -6,7 +6,7 @@ import { VectorIndex } from "../VectorIndex.js";
  * a small number of entries and don't want to set up a real database, e.g. for conversational memory
  * that does not need to be persisted.
  */
-export declare class MemoryVectorIndex<DATA> implements VectorIndex<DATA, MemoryVectorIndex<DATA>> {
+export declare class MemoryVectorIndex<DATA> implements VectorIndex<DATA, MemoryVectorIndex<DATA>, (value: DATA) => boolean> {
     static deserialize<DATA>({ serializedData, schema, }: {
         serializedData: string;
         schema?: z.ZodSchema<DATA>;
@@ -17,10 +17,11 @@ export declare class MemoryVectorIndex<DATA> implements VectorIndex<DATA, Memory
         vector: Vector;
         data: DATA;
     }>): Promise<void>;
-    queryByVector({ queryVector, similarityThreshold, maxResults, }: {
+    queryByVector({ queryVector, similarityThreshold, maxResults, filter, }: {
         queryVector: Vector;
         maxResults: number;
         similarityThreshold?: number;
+        filter?: (value: DATA) => boolean;
     }): Promise<Array<{
         id: string;
         data: DATA;

package/vector-index/memory/MemoryVectorIndex.js

@@ -34,8 +34,9 @@ export class MemoryVectorIndex {
             this.entries.set(entry.id, entry);
         }
     }
-    async queryByVector({ queryVector, similarityThreshold, maxResults, }) {
+    async queryByVector({ queryVector, similarityThreshold, maxResults, filter, }) {
         const results = [...this.entries.values()]
+            .filter((value) => filter?.(value.data) ?? true)
             .map((entry) => ({
             id: entry.id,
             similarity: cosineSimilarity(entry.vector, queryVector),

package/vector-index/pinecone/PineconeVectorIndex.d.ts

@@ -2,7 +2,7 @@ import { VectorOperationsApi } from "@pinecone-database/pinecone/dist/pinecone-g
 import { z } from "zod";
 import { Vector } from "../../core/Vector.js";
 import { VectorIndex } from "../VectorIndex.js";
-export declare class PineconeVectorIndex<DATA extends object | undefined> implements VectorIndex<DATA, PineconeVectorIndex<DATA>> {
+export declare class PineconeVectorIndex<DATA extends object | undefined> implements VectorIndex<DATA, PineconeVectorIndex<DATA>, null> {
     readonly index: VectorOperationsApi;
     readonly namespace?: string;
     readonly schema: z.ZodSchema<DATA>;

package/vector-index/upsertIntoVectorIndex.d.ts

@@ -2,7 +2,7 @@ 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>;
+    vectorIndex: VectorIndex<OBJECT, unknown, unknown>;
     embeddingModel: TextEmbeddingModel<unknown, SETTINGS>;
     generateId?: () => string;
     objects: OBJECT[];