@agentionai/agents 0.3.0-beta

package/dist/tools/Tool.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = exports.ToolResultEvent = exports.ToolEvent = void 0;
+const events_1 = __importDefault(require("events"));
+const VizReporter_1 = require("../viz/VizReporter");
+const VizConfig_1 = require("../viz/VizConfig");
+class ToolEvent {
+    constructor(target, input, id, agentId, agentName) {
+        this.target = target;
+        this.input = input;
+        this.id = id;
+        this.agentId = agentId;
+        this.agentName = agentName;
+        this.defaultPrevented = false;
+    }
+    preventDefault() {
+        this.defaultPrevented = true;
+    }
+    get isDefaultPrevented() {
+        return this.defaultPrevented;
+    }
+}
+exports.ToolEvent = ToolEvent;
+ToolEvent.EXECUTE = "execute";
+class ToolResultEvent extends ToolEvent {
+    constructor(target, input, id, result, agentId, agentName) {
+        super(target, input, id, agentId, agentName);
+        this.target = target;
+        this.input = input;
+        this.id = id;
+        this.result = result;
+        this.agentId = agentId;
+        this.agentName = agentName;
+        this.eventName = "ToolResult";
+    }
+}
+exports.ToolResultEvent = ToolResultEvent;
+ToolResultEvent.RESULT = "toolResult";
+/**
+ * Tools are used to retrieve additional information for LLMs, so they can provide better results. Examples could be
+ * Retrieving weather information, stock prices or specific price information.
+ *
+ * @param T Generic. Format of the tool result
+
+ */
+class Tool extends events_1.default {
+    /**
+     * Agents can act as assistants to other agents. This static method creates a tool
+     * @param agent The agent that will act as an assistant
+     * @param description Th
+     * @returns Tool
+     */
+    static fromAgent(agent, description) {
+        return new Tool({
+            name: agent.getName().replace(/ /g, "_"),
+            description: description ? description : agent.getDescription(),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instructions: {
+                        type: "string",
+                        description: "Detailed instructions for the agent.",
+                    },
+                },
+                required: ["instructions"],
+            },
+            execute: async (input) => {
+                try {
+                    return (await agent.execute(input.instructions));
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        error: "Failed to execute instructions: " + error.message,
+                    });
+                }
+            },
+        });
+    }
+    constructor(config) {
+        super();
+        this.executeFn = config.execute;
+        this.context = config.context || null;
+        this.name = config.name;
+        this.description = config.description;
+        this.schema = config.inputSchema;
+    }
+    async execute(agentId, agentName, input, id, agentModel, agentVendor) {
+        const event = new ToolEvent(this, input, id, agentId, agentName);
+        this.emit(ToolEvent.EXECUTE, event);
+        if (event.isDefaultPrevented) {
+            throw new Error("Tool execution prevented, do not try this tool again with this input");
+        }
+        // Visualization reporting
+        let vizEventId;
+        if (VizConfig_1.vizConfig.isEnabled()) {
+            const vizSource = {
+                agentId,
+                agentName,
+                model: agentModel || "unknown",
+                vendor: agentVendor || "anthropic",
+            };
+            vizEventId = VizReporter_1.vizReporter.toolStart(this.name, id, input, vizSource);
+        }
+        try {
+            const result = await this.executeFn(input, this.context);
+            const resultEvent = new ToolResultEvent(this, input, id, result, agentId, agentName);
+            this.emit(ToolResultEvent.RESULT, resultEvent);
+            if (resultEvent.isDefaultPrevented) {
+                throw new Error("Tool result prevented, do not try this tool again with this input");
+            }
+            // Report tool completion to viz
+            if (vizEventId) {
+                VizReporter_1.vizReporter.toolComplete(vizEventId, this.name, id, true, result);
+            }
+            return result;
+        }
+        catch (error) {
+            // Report tool error to viz
+            if (vizEventId) {
+                VizReporter_1.vizReporter.toolError(vizEventId, this.name, id, error?.message || "Unknown error");
+            }
+            throw error;
+        }
+    }
+    getPrompt(_vendor) {
+        return {
+            name: this.name,
+            description: this.description,
+            input_schema: this.schema,
+        };
+    }
+}
+exports.Tool = Tool;
+//# sourceMappingURL=Tool.js.map

package/dist/vectorstore/Embeddings.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Embeddings interface for generating vector representations of text.
+ *
+ * This module provides an abstract interface for embedding providers,
+ * allowing vector stores to work with any embedding service.
+ */
+/**
+ * Configuration for embedding operations.
+ */
+export interface EmbeddingOptions {
+    /** Model identifier (provider-specific) */
+    model?: string;
+    /** Number of dimensions for the embedding (if configurable) */
+    dimensions?: number;
+}
+/**
+ * Abstract interface for embedding providers.
+ *
+ * Implementations generate vector representations of text that can be
+ * used for semantic similarity search in vector stores.
+ *
+ * @example
+ * ```typescript
+ * class OpenAIEmbeddings extends Embeddings {
+ *   async embed(texts: string[]): Promise<number[][]> {
+ *     const response = await openai.embeddings.create({
+ *       model: this.model,
+ *       input: texts,
+ *     });
+ *     return response.data.map(d => d.embedding);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Embeddings {
+    /** Name identifier for this embeddings provider */
+    abstract readonly name: string;
+    /** The model being used for embeddings */
+    abstract readonly model: string;
+    /** Number of dimensions in the output vectors */
+    abstract readonly dimensions: number;
+    /**
+     * Generate embeddings for multiple texts.
+     *
+     * @param texts - Array of text strings to embed
+     * @returns Array of embedding vectors (one per input text)
+     */
+    abstract embed(texts: string[]): Promise<number[][]>;
+    /**
+     * Generate embedding for a single text.
+     * Default implementation calls embed() with a single-item array.
+     *
+     * @param text - Text string to embed
+     * @returns Embedding vector
+     */
+    embedOne(text: string): Promise<number[]>;
+    /**
+     * Generate embedding for a search query.
+     * Some providers use different models/settings for queries vs documents.
+     * Default implementation calls embedOne().
+     *
+     * @param query - Query text to embed
+     * @returns Embedding vector optimized for query
+     */
+    embedQuery(query: string): Promise<number[]>;
+}
+//# sourceMappingURL=Embeddings.d.ts.map

package/dist/vectorstore/Embeddings.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Embeddings interface for generating vector representations of text.
+ *
+ * This module provides an abstract interface for embedding providers,
+ * allowing vector stores to work with any embedding service.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Embeddings = void 0;
+/**
+ * Abstract interface for embedding providers.
+ *
+ * Implementations generate vector representations of text that can be
+ * used for semantic similarity search in vector stores.
+ *
+ * @example
+ * ```typescript
+ * class OpenAIEmbeddings extends Embeddings {
+ *   async embed(texts: string[]): Promise<number[][]> {
+ *     const response = await openai.embeddings.create({
+ *       model: this.model,
+ *       input: texts,
+ *     });
+ *     return response.data.map(d => d.embedding);
+ *   }
+ * }
+ * ```
+ */
+class Embeddings {
+    /**
+     * Generate embedding for a single text.
+     * Default implementation calls embed() with a single-item array.
+     *
+     * @param text - Text string to embed
+     * @returns Embedding vector
+     */
+    async embedOne(text) {
+        const results = await this.embed([text]);
+        return results[0];
+    }
+    /**
+     * Generate embedding for a search query.
+     * Some providers use different models/settings for queries vs documents.
+     * Default implementation calls embedOne().
+     *
+     * @param query - Query text to embed
+     * @returns Embedding vector optimized for query
+     */
+    async embedQuery(query) {
+        return this.embedOne(query);
+    }
+}
+exports.Embeddings = Embeddings;
+//# sourceMappingURL=Embeddings.js.map

package/dist/vectorstore/LanceDBVectorStore.d.ts

@@ -0,0 +1,149 @@
+/**
+ * LanceDB implementation of the VectorStore interface.
+ *
+ * LanceDB is an embedded vector database that runs locally or can connect
+ * to cloud storage. It provides fast vector search with automatic indexing.
+ *
+ * @requires @lancedb/lancedb - Install with: npm install @lancedb/lancedb
+ * @requires apache-arrow - Install with: npm install apache-arrow
+ */
+import type { Connection, Table, ConnectionOptions } from "@lancedb/lancedb";
+import { VectorStore, Document, EmbeddedDocument, SearchResult, AddDocumentsOptions, SearchOptions, DeleteOptions } from "./VectorStore";
+import { Embeddings } from "./Embeddings";
+/**
+ * Configuration for LanceDBVectorStore.
+ */
+export interface LanceDBVectorStoreConfig {
+    /** Name identifier for this store instance */
+    name: string;
+    /** URI for the LanceDB database (local path or cloud URI) */
+    uri: string;
+    /** Name of the table to use */
+    tableName: string;
+    /** Embeddings provider for automatic embedding generation */
+    embeddings?: Embeddings;
+    /** Vector dimensions (required if no embeddings provider, defaults to embeddings.dimensions) */
+    dimensions?: number;
+    /** Additional connection options */
+    connectionOptions?: Partial<ConnectionOptions>;
+}
+/**
+ * LanceDB implementation of the VectorStore interface.
+ *
+ * @example
+ * ```typescript
+ * import { LanceDBVectorStore, OpenAIEmbeddings } from "@agentionai/agents";
+ *
+ * // Create with OpenAI embeddings
+ * const embeddings = new OpenAIEmbeddings({
+ *   model: "text-embedding-3-small",
+ * });
+ *
+ * const store = await LanceDBVectorStore.create({
+ *   name: "knowledge_base",
+ *   uri: "./my-database",
+ *   tableName: "documents",
+ *   embeddings,
+ * });
+ *
+ * // Add documents (embeddings generated automatically)
+ * await store.addDocuments([
+ *   { id: "1", content: "LanceDB is a vector database" },
+ *   { id: "2", content: "Vector search enables semantic queries" },
+ * ]);
+ *
+ * // Search
+ * const results = await store.search("What is LanceDB?", { limit: 5 });
+ *
+ * // Create a tool for agents
+ * const searchTool = store.toRetrievalTool("Search the knowledge base");
+ * ```
+ */
+export declare class LanceDBVectorStore extends VectorStore {
+    readonly name: string;
+    private connection;
+    private table;
+    private embeddings?;
+    private tableName;
+    private dimensions;
+    private constructor();
+    /**
+     * Create a new LanceDBVectorStore instance.
+     *
+     * This is an async factory method since LanceDB connection is asynchronous.
+     *
+     * @param config - Configuration for the store
+     * @returns A configured LanceDBVectorStore instance
+     *
+     * @throws Error if @lancedb/lancedb is not installed
+     */
+    static create(config: LanceDBVectorStoreConfig): Promise<LanceDBVectorStore>;
+    /**
+     * Add documents to the vector store.
+     * If an embeddings provider is configured, embeddings are generated automatically.
+     */
+    addDocuments(documents: Document[], _options?: AddDocumentsOptions): Promise<string[]>;
+    /**
+     * Add documents with pre-computed embeddings.
+     */
+    addEmbeddedDocuments(documents: EmbeddedDocument[], _options?: AddDocumentsOptions): Promise<string[]>;
+    /**
+     * Search for documents similar to the query.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search using a pre-computed embedding vector.
+     */
+    searchByVector(embedding: number[], options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Delete documents by their IDs.
+     */
+    delete(ids: string[], _options?: DeleteOptions): Promise<number>;
+    /**
+     * Delete all documents.
+     */
+    clear(_options?: DeleteOptions): Promise<void>;
+    /**
+     * Get a document by its ID.
+     */
+    getById(id: string, _options?: DeleteOptions): Promise<Document | null>;
+    /**
+     * Get existing documents by their content hashes.
+     * Used for deduplication during ingestion.
+     */
+    getByHashes(hashes: string[], _options?: DeleteOptions): Promise<Map<string, string>>;
+    /**
+     * Get the underlying LanceDB connection.
+     */
+    getConnection(): Connection;
+    /**
+     * Get the underlying LanceDB table.
+     */
+    getTable(): Table;
+    /**
+     * Get the configured embeddings provider.
+     */
+    getEmbeddings(): Embeddings | undefined;
+    /**
+     * Get the vector dimensions.
+     */
+    getDimensions(): number;
+    /**
+     * Create an index on the vector column for faster searches.
+     * Recommended for tables with more than 10,000 rows.
+     */
+    createIndex(): Promise<void>;
+    /**
+     * Optimize the table for better performance.
+     */
+    optimize(): Promise<void>;
+    /**
+     * Build a SQL filter string from a filter object.
+     */
+    private buildFilterString;
+    /**
+     * Process raw LanceDB results into SearchResult format.
+     */
+    private processResults;
+}
+//# sourceMappingURL=LanceDBVectorStore.d.ts.map