@agentionai/agents 0.4.2 → 0.6.1

package/dist/graph/planning/PlanningTools.d.ts

@@ -0,0 +1,45 @@
+import { Tool } from "../../tools/Tool";
+import { PlanStore } from "./PlanStore";
+/**
+ * Create a tool for agents to create an execution plan.
+ *
+ * @param planStore - The PlanStore to create plans in
+ * @returns A Tool that creates plans
+ *
+ * @example
+ * ```typescript
+ * const store = new PlanStore();
+ * const createTool = createPlanTool(store);
+ * agent.addTools([createTool]);
+ * ```
+ */
+export declare function createPlanTool(planStore: PlanStore): Tool<string>;
+/**
+ * Create a tool for agents to view the current plan status.
+ *
+ * @param planStore - The PlanStore to view plans from
+ * @returns A Tool that displays plan information
+ */
+export declare function createViewPlanTool(planStore: PlanStore): Tool<string>;
+/**
+ * Create a tool for agents to update step status.
+ *
+ * @param planStore - The PlanStore to update steps in
+ * @returns A Tool that updates step status
+ */
+export declare function createUpdateStepTool(planStore: PlanStore): Tool<string>;
+/**
+ * Create a tool for agents to get the next step to work on.
+ *
+ * @param planStore - The PlanStore to get steps from
+ * @returns A Tool that retrieves the next pending step
+ */
+export declare function createGetNextStepTool(planStore: PlanStore): Tool<string>;
+/**
+ * Create a tool for agents to add a step to the current plan.
+ *
+ * @param planStore - The PlanStore to add steps to
+ * @returns A Tool that adds new steps
+ */
+export declare function createAddStepTool(planStore: PlanStore): Tool<string>;
+//# sourceMappingURL=PlanningTools.d.ts.map

package/dist/graph/planning/PlanningTools.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlanTool = createPlanTool;
+exports.createViewPlanTool = createViewPlanTool;
+exports.createUpdateStepTool = createUpdateStepTool;
+exports.createGetNextStepTool = createGetNextStepTool;
+exports.createAddStepTool = createAddStepTool;
+const Tool_1 = require("../../tools/Tool");
+/**
+ * Create a tool for agents to create an execution plan.
+ *
+ * @param planStore - The PlanStore to create plans in
+ * @returns A Tool that creates plans
+ *
+ * @example
+ * ```typescript
+ * const store = new PlanStore();
+ * const createTool = createPlanTool(store);
+ * agent.addTools([createTool]);
+ * ```
+ */
+function createPlanTool(planStore) {
+    return new Tool_1.Tool({
+        name: "create_plan",
+        description: "Create an execution plan with a goal and ordered steps. Each step should be a clear, actionable task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                goal: {
+                    type: "string",
+                    description: "The overall goal to achieve",
+                },
+                steps: {
+                    type: "array",
+                    description: "Ordered list of step descriptions",
+                },
+            },
+            required: ["goal", "steps"],
+        },
+        execute: async (input) => {
+            const plan = planStore.createPlan(input.goal, input.steps);
+            return JSON.stringify({
+                success: true,
+                planId: plan.id,
+                stepCount: plan.steps.length,
+                summary: planStore.getSummary(),
+            });
+        },
+    });
+}
+/**
+ * Create a tool for agents to view the current plan status.
+ *
+ * @param planStore - The PlanStore to view plans from
+ * @returns A Tool that displays plan information
+ */
+function createViewPlanTool(planStore) {
+    return new Tool_1.Tool({
+        name: "view_plan",
+        description: "View the current plan status and steps.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        execute: async () => {
+            const plan = planStore.getActivePlan();
+            if (!plan) {
+                return JSON.stringify({ error: "No active plan" });
+            }
+            return JSON.stringify({
+                plan,
+                summary: planStore.getSummary(),
+            });
+        },
+    });
+}
+/**
+ * Create a tool for agents to update step status.
+ *
+ * @param planStore - The PlanStore to update steps in
+ * @returns A Tool that updates step status
+ */
+function createUpdateStepTool(planStore) {
+    return new Tool_1.Tool({
+        name: "update_step",
+        description: "Update the status of a plan step. Mark as completed when done, failed if there was an error.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                stepId: {
+                    type: "string",
+                    description: "The step ID to update (e.g., step_1)",
+                },
+                status: {
+                    type: "string",
+                    enum: ["in_progress", "completed", "failed", "skipped"],
+                    description: "New status for the step",
+                },
+                output: {
+                    type: "string",
+                    description: "Optional output or result from this step",
+                },
+                error: {
+                    type: "string",
+                    description: "Optional error message if the step failed",
+                },
+            },
+            required: ["stepId", "status"],
+        },
+        execute: async (input) => {
+            planStore.updateStep(input.stepId, input.status, input.output, input.error);
+            return JSON.stringify({
+                success: true,
+                summary: planStore.getSummary(),
+            });
+        },
+    });
+}
+/**
+ * Create a tool for agents to get the next step to work on.
+ *
+ * @param planStore - The PlanStore to get steps from
+ * @returns A Tool that retrieves the next pending step
+ */
+function createGetNextStepTool(planStore) {
+    return new Tool_1.Tool({
+        name: "get_next_step",
+        description: "Get the next pending step from the plan to work on.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        execute: async () => {
+            const step = planStore.getNextStep();
+            if (!step) {
+                return JSON.stringify({
+                    message: "No more pending steps",
+                    summary: planStore.getSummary(),
+                });
+            }
+            return JSON.stringify({ nextStep: step });
+        },
+    });
+}
+/**
+ * Create a tool for agents to add a step to the current plan.
+ *
+ * @param planStore - The PlanStore to add steps to
+ * @returns A Tool that adds new steps
+ */
+function createAddStepTool(planStore) {
+    return new Tool_1.Tool({
+        name: "add_step",
+        description: "Add a new step to the current plan.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                description: {
+                    type: "string",
+                    description: "Description of the new step",
+                },
+            },
+            required: ["description"],
+        },
+        execute: async (input) => {
+            const step = planStore.addStep(input.description);
+            if (!step) {
+                return JSON.stringify({ error: "No active plan to add step to" });
+            }
+            return JSON.stringify({
+                success: true,
+                step,
+                summary: planStore.getSummary(),
+            });
+        },
+    });
+}
+//# sourceMappingURL=PlanningTools.js.map

package/dist/graph/planning/index.d.ts

@@ -0,0 +1,5 @@
+export { Plan, PlanStep, PlanStepStatus, PlanStatus } from "./types";
+export { PlanStore } from "./PlanStore";
+export { createPlanTool, createViewPlanTool, createUpdateStepTool, createGetNextStepTool, createAddStepTool, } from "./PlanningTools";
+export { PlanExecutor, PlanExecutorOptions } from "./PlanExecutor";
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/planning/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanExecutor = exports.createAddStepTool = exports.createGetNextStepTool = exports.createUpdateStepTool = exports.createViewPlanTool = exports.createPlanTool = exports.PlanStore = void 0;
+var PlanStore_1 = require("./PlanStore");
+Object.defineProperty(exports, "PlanStore", { enumerable: true, get: function () { return PlanStore_1.PlanStore; } });
+var PlanningTools_1 = require("./PlanningTools");
+Object.defineProperty(exports, "createPlanTool", { enumerable: true, get: function () { return PlanningTools_1.createPlanTool; } });
+Object.defineProperty(exports, "createViewPlanTool", { enumerable: true, get: function () { return PlanningTools_1.createViewPlanTool; } });
+Object.defineProperty(exports, "createUpdateStepTool", { enumerable: true, get: function () { return PlanningTools_1.createUpdateStepTool; } });
+Object.defineProperty(exports, "createGetNextStepTool", { enumerable: true, get: function () { return PlanningTools_1.createGetNextStepTool; } });
+Object.defineProperty(exports, "createAddStepTool", { enumerable: true, get: function () { return PlanningTools_1.createAddStepTool; } });
+var PlanExecutor_1 = require("./PlanExecutor");
+Object.defineProperty(exports, "PlanExecutor", { enumerable: true, get: function () { return PlanExecutor_1.PlanExecutor; } });
+//# sourceMappingURL=index.js.map

package/dist/graph/planning/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Status of a plan step.
+ */
+export type PlanStepStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped";
+/**
+ * A single step in a plan.
+ */
+export interface PlanStep {
+    /** Unique identifier for this step (e.g., "step_1") */
+    id: string;
+    /** Human-readable description of what this step does */
+    description: string;
+    /** Current status of this step */
+    status: PlanStepStatus;
+    /** Output or result from this step (set after completion) */
+    output?: string;
+    /** Error message if the step failed */
+    error?: string;
+}
+/**
+ * Overall status of a plan.
+ */
+export type PlanStatus = "created" | "executing" | "completed" | "failed";
+/**
+ * A complete execution plan with a goal and ordered steps.
+ */
+export interface Plan {
+    /** Unique identifier for this plan */
+    id: string;
+    /** The overall goal this plan aims to achieve */
+    goal: string;
+    /** Ordered list of steps to execute */
+    steps: PlanStep[];
+    /** Overall status of the plan */
+    status: PlanStatus;
+    /** Timestamp when the plan was created */
+    createdAt: number;
+    /** Timestamp when the plan was last updated */
+    updatedAt: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graph/planning/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/history/History.js

@@ -62,6 +62,9 @@ class History extends events_1.default {
             ...entry,
             __metadata,
         });
+        if (this.options.maxLength && this._entries.length > this.options.maxLength) {
+            this._entries = this._entries.slice(this._entries.length - this.options.maxLength);
+        }
         this.emit("entry", entry);
     }
     /**

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./graph/AgentGraph";
 export * from "./tools/Tool";
 export * from "./viz";
 export * from "./vectorstore";
+export * from "./embeddings";
 export * from "./chunkers";
 export * from "./ingestion";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -49,6 +49,8 @@ __exportStar(require("./tools/Tool"), exports);
 __exportStar(require("./viz"), exports);
 // Vector Store
 __exportStar(require("./vectorstore"), exports);
+// Embeddings (also re-exported from vectorstore for backward compatibility)
+__exportStar(require("./embeddings"), exports);
 // Chunkers
 __exportStar(require("./chunkers"), exports);
 // Ingestion

package/dist/ingestion/IngestionPipeline.d.ts

@@ -1,6 +1,6 @@
 import { Chunk, ChunkOptions } from "../chunkers/types";
 import { Chunker } from "../chunkers/Chunker";
-import { Embeddings } from "../vectorstore/Embeddings";
+import { Embeddings } from "../embeddings/Embeddings";
 import { VectorStore } from "../vectorstore/VectorStore";
 import { IngestionOptions, IngestionResult, DocumentInput } from "./types";
 /**

package/dist/vectorstore/LanceDBVectorStore.d.ts

@@ -9,7 +9,22 @@
  */
 import type { Connection, Table, ConnectionOptions } from "@lancedb/lancedb";
 import { VectorStore, Document, EmbeddedDocument, SearchResult, AddDocumentsOptions, SearchOptions, DeleteOptions } from "./VectorStore";
-import { Embeddings } from "./Embeddings";
+import { Embeddings } from "../embeddings/Embeddings";
+/**
+ * Supported types for metadata fields.
+ */
+export type MetadataFieldType = "string" | "number" | "boolean";
+/**
+ * Definition for a metadata field that will be stored as a separate column.
+ */
+export interface MetadataFieldDefinition {
+    /** Name of the metadata field */
+    name: string;
+    /** Data type for the field */
+    type: MetadataFieldType;
+    /** Whether the field can be null (default: true) */
+    nullable?: boolean;
+}
 /**
  * Configuration for LanceDBVectorStore.
  */
@@ -26,11 +41,17 @@ export interface LanceDBVectorStoreConfig {
     dimensions?: number;
     /** Additional connection options */
     connectionOptions?: Partial<ConnectionOptions>;
+    /**
+     * Metadata field definitions for filterable columns.
+     * When specified, metadata fields are stored as separate columns enabling efficient filtering.
+     * If not specified, metadata is stored as a JSON string (legacy behavior).
+     */
+    metadataFields?: MetadataFieldDefinition[];
 }
 /**
  * LanceDB implementation of the VectorStore interface.
  *
- * @example
+ * @example Basic usage with JSON metadata (legacy)
  * ```typescript
  * import { LanceDBVectorStore, OpenAIEmbeddings } from "@agentionai/agents";
  *
@@ -58,6 +79,38 @@ export interface LanceDBVectorStoreConfig {
  * // Create a tool for agents
  * const searchTool = store.toRetrievalTool("Search the knowledge base");
  * ```
+ *
+ * @example With filterable metadata fields
+ * ```typescript
+ * const store = await LanceDBVectorStore.create({
+ *   name: "knowledge_base",
+ *   uri: "./my-database",
+ *   tableName: "documents",
+ *   embeddings,
+ *   metadataFields: [
+ *     { name: "category", type: "string" },
+ *     { name: "source", type: "string" },
+ *     { name: "year", type: "number" },
+ *     { name: "verified", type: "boolean" },
+ *     { name: "hash", type: "string" }, // Enables efficient deduplication
+ *   ],
+ * });
+ *
+ * // Add documents with metadata
+ * await store.addDocuments([
+ *   {
+ *     id: "1",
+ *     content: "LanceDB is a vector database",
+ *     metadata: { category: "database", source: "docs", year: 2024, verified: true },
+ *   },
+ * ]);
+ *
+ * // Search with filters on metadata columns
+ * const results = await store.search("vector database", {
+ *   limit: 5,
+ *   filter: { category: "database", year: 2024 },
+ * });
+ * ```
  */
 export declare class LanceDBVectorStore extends VectorStore {
     readonly name: string;
@@ -66,6 +119,7 @@ export declare class LanceDBVectorStore extends VectorStore {
     private embeddings?;
     private tableName;
     private dimensions;
+    private metadataFields?;
     private constructor();
     /**
      * Create a new LanceDBVectorStore instance.
@@ -110,6 +164,9 @@ export declare class LanceDBVectorStore extends VectorStore {
     /**
      * Get existing documents by their content hashes.
      * Used for deduplication during ingestion.
+     *
+     * Note: If using metadataFields, include a "hash" field of type "string"
+     * for efficient hash lookups. Otherwise, falls back to LIKE queries on JSON metadata.
      */
     getByHashes(hashes: string[], _options?: DeleteOptions): Promise<Map<string, string>>;
     /**
@@ -145,5 +202,13 @@ export declare class LanceDBVectorStore extends VectorStore {
      * Process raw LanceDB results into SearchResult format.
      */
     private processResults;
+    /**
+     * Extract metadata from a row based on metadataFields configuration.
+     */
+    private extractMetadata;
+    /**
+     * Get the configured metadata fields.
+     */
+    getMetadataFields(): MetadataFieldDefinition[] | undefined;
 }
 //# sourceMappingURL=LanceDBVectorStore.d.ts.map

package/dist/vectorstore/LanceDBVectorStore.js

@@ -47,7 +47,7 @@ const VectorStore_1 = require("./VectorStore");
 /**
  * LanceDB implementation of the VectorStore interface.
  *
- * @example
+ * @example Basic usage with JSON metadata (legacy)
  * ```typescript
  * import { LanceDBVectorStore, OpenAIEmbeddings } from "@agentionai/agents";
  *
@@ -75,6 +75,38 @@ const VectorStore_1 = require("./VectorStore");
  * // Create a tool for agents
  * const searchTool = store.toRetrievalTool("Search the knowledge base");
  * ```
+ *
+ * @example With filterable metadata fields
+ * ```typescript
+ * const store = await LanceDBVectorStore.create({
+ *   name: "knowledge_base",
+ *   uri: "./my-database",
+ *   tableName: "documents",
+ *   embeddings,
+ *   metadataFields: [
+ *     { name: "category", type: "string" },
+ *     { name: "source", type: "string" },
+ *     { name: "year", type: "number" },
+ *     { name: "verified", type: "boolean" },
+ *     { name: "hash", type: "string" }, // Enables efficient deduplication
+ *   ],
+ * });
+ *
+ * // Add documents with metadata
+ * await store.addDocuments([
+ *   {
+ *     id: "1",
+ *     content: "LanceDB is a vector database",
+ *     metadata: { category: "database", source: "docs", year: 2024, verified: true },
+ *   },
+ * ]);
+ *
+ * // Search with filters on metadata columns
+ * const results = await store.search("vector database", {
+ *   limit: 5,
+ *   filter: { category: "database", year: 2024 },
+ * });
+ * ```
  */
 class LanceDBVectorStore extends VectorStore_1.VectorStore {
     constructor(config, connection, table) {
@@ -86,6 +118,7 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
         this.tableName = config.tableName;
         this.dimensions =
             config.dimensions ?? config.embeddings?.dimensions ?? 1536;
+        this.metadataFields = config.metadataFields;
     }
     /**
      * Create a new LanceDBVectorStore instance.
@@ -122,12 +155,38 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
             catch {
                 throw new Error("apache-arrow is not installed. Install it with: npm install apache-arrow");
             }
-            const schema = new arrow.Schema([
+            // Build schema fields - use explicit type to allow different Field types
+            const schemaFields = [
                 new arrow.Field("id", new arrow.Utf8(), false),
                 new arrow.Field("text", new arrow.Utf8(), false),
                 new arrow.Field("vector", new arrow.FixedSizeList(dimensions, new arrow.Field("item", new arrow.Float32(), true)), false),
-                new arrow.Field("metadata", new arrow.Utf8(), true),
-            ]);
+            ];
+            // Add metadata fields - either as separate columns or as a JSON string
+            if (config.metadataFields && config.metadataFields.length > 0) {
+                for (const field of config.metadataFields) {
+                    const nullable = field.nullable !== false;
+                    let arrowType;
+                    switch (field.type) {
+                        case "string":
+                            arrowType = new arrow.Utf8();
+                            break;
+                        case "number":
+                            arrowType = new arrow.Float64();
+                            break;
+                        case "boolean":
+                            arrowType = new arrow.Bool();
+                            break;
+                        default:
+                            throw new Error(`Unsupported metadata field type: ${field.type}`);
+                    }
+                    schemaFields.push(new arrow.Field(field.name, arrowType, nullable));
+                }
+            }
+            else {
+                // Legacy: store metadata as JSON string
+                schemaFields.push(new arrow.Field("metadata", new arrow.Utf8(), true));
+            }
+            const schema = new arrow.Schema(schemaFields);
             table = await connection.createEmptyTable(config.tableName, schema);
         }
         return new LanceDBVectorStore(config, connection, table);
@@ -154,12 +213,25 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
      * Add documents with pre-computed embeddings.
      */
     async addEmbeddedDocuments(documents, _options) {
-        const records = documents.map((doc) => ({
-            id: doc.id,
-            text: doc.content,
-            vector: doc.embedding,
-            metadata: doc.metadata ? JSON.stringify(doc.metadata) : undefined,
-        }));
+        const records = documents.map((doc) => {
+            const record = {
+                id: doc.id,
+                text: doc.content,
+                vector: doc.embedding,
+            };
+            if (this.metadataFields && this.metadataFields.length > 0) {
+                // Store each metadata field as a separate column
+                for (const field of this.metadataFields) {
+                    const value = doc.metadata?.[field.name];
+                    record[field.name] = value !== undefined ? value : null;
+                }
+            }
+            else {
+                // Legacy: store metadata as JSON string
+                record.metadata = doc.metadata ? JSON.stringify(doc.metadata) : undefined;
+            }
+            return record;
+        });
         await this.table.add(records);
         return documents.map((d) => d.id);
     }
@@ -222,28 +294,41 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
         return {
             id: row.id,
             content: row.text,
-            metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+            metadata: this.extractMetadata(row),
         };
     }
     /**
      * Get existing documents by their content hashes.
      * Used for deduplication during ingestion.
+     *
+     * Note: If using metadataFields, include a "hash" field of type "string"
+     * for efficient hash lookups. Otherwise, falls back to LIKE queries on JSON metadata.
      */
     async getByHashes(hashes, _options) {
         const hashMap = new Map();
         if (hashes.length === 0) {
             return hashMap;
         }
-        // Query for documents with matching hashes
-        // Since hash is stored in the metadata JSON, we need to check each hash
+        // Check if hash is a defined metadata field for efficient queries
+        const hasHashField = this.metadataFields?.some((field) => field.name === "hash");
         for (const hash of hashes) {
-            // LanceDB doesn't support JSON path queries, so we search for the hash string
-            // in the metadata field. This works because the hash is a unique string.
-            const results = await this.table
-                .query()
-                .where(`metadata LIKE '%${hash}%'`)
-                .limit(1)
-                .toArray();
+            let results;
+            if (hasHashField) {
+                // Efficient direct column query
+                results = await this.table
+                    .query()
+                    .where(`hash = '${hash}'`)
+                    .limit(1)
+                    .toArray();
+            }
+            else {
+                // Legacy: search for hash string in JSON metadata
+                results = await this.table
+                    .query()
+                    .where(`metadata LIKE '%${hash}%'`)
+                    .limit(1)
+                    .toArray();
+            }
             if (results.length > 0) {
                 const record = results[0];
                 hashMap.set(hash, record.id);
@@ -319,9 +404,7 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
             if (scoreThreshold !== undefined && score < scoreThreshold) {
                 continue;
             }
-            const metadata = row.metadata
-                ? JSON.parse(row.metadata)
-                : undefined;
+            const metadata = this.extractMetadata(row);
             searchResults.push({
                 document: {
                     id: row.id,
@@ -333,6 +416,34 @@ class LanceDBVectorStore extends VectorStore_1.VectorStore {
         }
         return searchResults;
     }
+    /**
+     * Extract metadata from a row based on metadataFields configuration.
+     */
+    extractMetadata(row) {
+        if (this.metadataFields && this.metadataFields.length > 0) {
+            // Reconstruct metadata from separate columns
+            const metadata = {};
+            let hasValue = false;
+            for (const field of this.metadataFields) {
+                const value = row[field.name];
+                if (value !== null && value !== undefined) {
+                    metadata[field.name] = value;
+                    hasValue = true;
+                }
+            }
+            return hasValue ? metadata : undefined;
+        }
+        else {
+            // Legacy: parse metadata from JSON string
+            return row.metadata ? JSON.parse(row.metadata) : undefined;
+        }
+    }
+    /**
+     * Get the configured metadata fields.
+     */
+    getMetadataFields() {
+        return this.metadataFields;
+    }
 }
 exports.LanceDBVectorStore = LanceDBVectorStore;
 //# sourceMappingURL=LanceDBVectorStore.js.map