@agentionai/agents 0.6.1 → 0.8.0

package/dist/mcp/index.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * MCP (Model Context Protocol) support for agention-lib.
+ *
+ * Connects to any MCP server — local stdio processes or remote HTTP endpoints —
+ * and exposes their tools as agention-lib {@link Tool} instances compatible with
+ * all agent types (ClaudeAgent, OpenAiAgent, MistralAgent, GeminiAgent).
+ *
+ * @requires @modelcontextprotocol/sdk - Optional peer dependency, install when needed:
+ * ```
+ * npm install @modelcontextprotocol/sdk
+ * ```
+ *
+ * @example Stdio (local process)
+ * ```typescript
+ * import { MCPClient, ClaudeAgent } from "@agentionai/agents";
+ *
+ * const mcp = MCPClient.fromStdio({
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+ * });
+ *
+ * await mcp.connect();
+ *
+ * const agent = new ClaudeAgent({
+ *   id: "file-agent",
+ *   name: "File Agent",
+ *   description: "An agent that can work with files",
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   tools: mcp.getTools(),
+ * });
+ *
+ * const result = await agent.execute("List the files in /tmp");
+ * await mcp.disconnect();
+ * ```
+ *
+ * @example HTTP with static API key
+ * ```typescript
+ * import { MCPClient } from "@agentionai/agents";
+ *
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
+ *   headers: { Authorization: "Bearer my-api-key" },
+ * });
+ *
+ * await mcp.connect();
+ * agent.addTools(mcp.getTools());
+ * await mcp.disconnect();
+ * ```
+ *
+ * @example HTTP with OAuth
+ * ```typescript
+ * import { MCPClient } from "@agentionai/agents";
+ * import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+ *
+ * // Implement OAuthClientProvider from the MCP SDK
+ * const myOAuthProvider: OAuthClientProvider = { ... };
+ *
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
+ *   authProvider: myOAuthProvider,
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPClient = void 0;
+var MCPClient_1 = require("./MCPClient");
+Object.defineProperty(exports, "MCPClient", { enumerable: true, get: function () { return MCPClient_1.MCPClient; } });
+//# sourceMappingURL=index.js.map

package/dist/mcp/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Configuration for connecting to an MCP server via stdio (local process).
+ */
+export interface MCPStdioConfig {
+    /** The command to spawn (e.g. "node", "python", "npx") */
+    command: string;
+    /** Arguments to pass to the command */
+    args?: string[];
+    /** Environment variables for the spawned process */
+    env?: Record<string, string>;
+}
+/**
+ * Configuration for connecting to an MCP server via HTTP (remote URL).
+ */
+export interface MCPHttpConfig {
+    /** Full URL to the MCP endpoint */
+    url: string;
+    /** Optional HTTP headers for static auth tokens or API keys */
+    headers?: Record<string, string>;
+    /**
+     * Optional OAuth provider for dynamic authorization.
+     * Implement the `OAuthClientProvider` interface from `@modelcontextprotocol/sdk`
+     * and pass it here for OAuth 2.0 + PKCE flows.
+     *
+     * @example
+     * ```typescript
+     * import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+     *
+     * const mcp = MCPClient.fromUrl("https://my-server.com/mcp", {
+     *   authProvider: myOAuthProvider,
+     * });
+     * ```
+     */
+    authProvider?: unknown;
+}
+/**
+ * Options shared by all MCPClient connection types.
+ */
+export interface MCPClientOptions {
+    /**
+     * Name to identify this MCP client (sent during SDK handshake).
+     * @default "agention-mcp-client"
+     */
+    clientName?: string;
+    /**
+     * Version string for the MCP client.
+     * @default "1.0.0"
+     */
+    clientVersion?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/types.js

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

package/dist/vectorstore/LanceDBVectorStore.d.ts

@@ -18,7 +18,7 @@ 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 of the metadata field. Use snake_case (e.g. `tenant_id`) to avoid SQL filter issues. */
     name: string;
     /** Data type for the field */
     type: MetadataFieldType;
@@ -42,73 +42,84 @@ export interface LanceDBVectorStoreConfig {
     /** 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).
+     * User-defined metadata field definitions.
+     *
+     * When provided, these fields are stored as typed Arrow columns and are
+     * filterable via SQL predicates in `search()`. The table is created on
+     * first insert using an explicit Arrow schema built from these definitions.
+     *
+     * **Important:** Use `snake_case` for field names (e.g. `tenant_id`, not
+     * `tenantId`). LanceDB uses DataFusion for SQL filtering, which normalizes
+     * unquoted identifiers to lowercase. Mixed-case names like `tenantId` will
+     * fail to match the column `tenantId` because the filter resolves to
+     * `tenantid`.
+     *
+     * Chunk metadata fields (index, hash, prev_id, etc.) are handled
+     * automatically via a `chunk_metadata` struct column — they do not need
+     * to be listed here.
+     *
+     * When omitted, the store connects to a **pre-existing** table (created
+     * independently, e.g. via the LanceDB CLI or another tool). In that case
+     * the schema is not managed by this class and all non-system columns are
+     * returned as metadata on read.
      */
     metadataFields?: MetadataFieldDefinition[];
 }
 /**
  * LanceDB implementation of the VectorStore interface.
  *
- * @example Basic usage with JSON metadata (legacy)
- * ```typescript
- * import { LanceDBVectorStore, OpenAIEmbeddings } from "@agentionai/agents";
+ * Supports two modes of operation:
  *
- * // 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,
- * });
+ * **Managed mode** (`metadataFields` provided): The store creates the LanceDB
+ * table on first insert using an explicit Arrow schema derived from
+ * `metadataFields`. User-defined fields are stored as typed top-level columns.
+ * Chunk metadata (from chunkers) is automatically packed into a `chunk_metadata`
+ * struct column.
  *
- * // Add documents (embeddings generated automatically)
- * await store.addDocuments([
- *   { id: "1", content: "LanceDB is a vector database" },
- *   { id: "2", content: "Vector search enables semantic queries" },
- * ]);
+ * **Pre-existing table mode** (`metadataFields` omitted): The store connects
+ * to a table that was created independently (e.g. via LanceDB CLI or another
+ * tool). No schema management is performed; all non-system columns are returned
+ * as metadata on read.
  *
- * // Search
- * const results = await store.search("What is LanceDB?", { limit: 5 });
+ * @example Managed mode — user-defined metadata fields
+ * ```typescript
+ * import { LanceDBVectorStore } from "@agentionai/agents";
+ * import { OpenAIEmbeddings } from "@agentionai/agents/embeddings";
  *
- * // Create a tool for agents
- * const searchTool = store.toRetrievalTool("Search the knowledge base");
- * ```
+ * const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
  *
- * @example With filterable metadata fields
- * ```typescript
  * const store = await LanceDBVectorStore.create({
  *   name: "knowledge_base",
  *   uri: "./my-database",
- *   tableName: "documents",
+ *   tableName: "chunks",
  *   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
+ *     { name: "author", type: "string", nullable: true },
+ *     { name: "category", type: "string", nullable: true },
  *   ],
  * });
  *
- * // Add documents with metadata
+ * // Chunk metadata (index, hash, prev_id, etc.) is stored automatically
+ * // in a chunk_metadata struct column — no need to declare it.
  * await store.addDocuments([
- *   {
- *     id: "1",
- *     content: "LanceDB is a vector database",
- *     metadata: { category: "database", source: "docs", year: 2024, verified: true },
- *   },
+ *   { id: "1", content: "LanceDB is a vector database", metadata: { category: "db" } },
  * ]);
  *
- * // Search with filters on metadata columns
+ * // Search with filters on user metadata columns
  * const results = await store.search("vector database", {
  *   limit: 5,
- *   filter: { category: "database", year: 2024 },
+ *   filter: { category: "db" },
+ * });
+ * ```
+ *
+ * @example Pre-existing table mode — connect to externally managed table
+ * ```typescript
+ * const store = await LanceDBVectorStore.create({
+ *   name: "my_store",
+ *   uri: "./my-database",
+ *   tableName: "existing_table", // table already exists with its own schema
+ *   embeddings,
+ *   // metadataFields omitted — schema is not managed by this class
  * });
  * ```
  */
@@ -124,14 +135,25 @@ export declare class LanceDBVectorStore extends VectorStore {
     /**
      * Create a new LanceDBVectorStore instance.
      *
-     * This is an async factory method since LanceDB connection is asynchronous.
+     * - If the table already exists it is opened immediately.
+     * - If `metadataFields` is provided and the table does not exist yet, it
+     *   will be created on the first insert with an explicit Arrow schema.
+     * - If `metadataFields` is **not** provided and the table does not exist,
+     *   an error is thrown — the store cannot manage an unknown schema.
      *
      * @param config - Configuration for the store
      * @returns A configured LanceDBVectorStore instance
      *
      * @throws Error if @lancedb/lancedb is not installed
+     * @throws Error if the table does not exist and no metadataFields are provided
      */
     static create(config: LanceDBVectorStoreConfig): Promise<LanceDBVectorStore>;
+    /**
+     * Create the table with an explicit Arrow schema derived from `metadataFields`
+     * plus a `chunk_metadata` struct column.
+     * Called on the first insert when operating in managed mode.
+     */
+    private createManagedTable;
     /**
      * Add documents to the vector store.
      * If an embeddings provider is configured, embeddings are generated automatically.
@@ -139,8 +161,29 @@ export declare class LanceDBVectorStore extends VectorStore {
     addDocuments(documents: Document[], _options?: AddDocumentsOptions): Promise<string[]>;
     /**
      * Add documents with pre-computed embeddings.
+     *
+     * In managed mode, chunk metadata fields are packed into a `chunk_metadata`
+     * struct and user-defined fields are projected to their declared columns.
+     * The table is created on the first call; subsequent calls append directly.
+     *
+     * In pre-existing table mode all metadata is spread flat as-is.
      */
     addEmbeddedDocuments(documents: EmbeddedDocument[], _options?: AddDocumentsOptions): Promise<string[]>;
+    /**
+     * Pack chunk metadata fields from flat metadata into a struct object.
+     * Returns a plain object for the `chunk_metadata` column, or null if
+     * no chunk metadata fields are present.
+     */
+    private packChunkMetadata;
+    /**
+     * Unpack a chunk_metadata struct value back to flat metadata keys.
+     */
+    private unpackChunkMetadata;
+    /**
+     * Project a record to only the columns declared in the schema
+     * (id, text, vector, chunk_metadata, plus all metadataFields).
+     */
+    private projectToSchema;
     /**
      * Search for documents similar to the query.
      */
@@ -165,8 +208,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.
+     * Requires that documents were stored with chunk metadata containing
+     * a `hash` field (automatically present when using chunkers from this library).
+     * Queries the `chunk_metadata.hash` struct sub-field.
      */
     getByHashes(hashes: string[], _options?: DeleteOptions): Promise<Map<string, string>>;
     /**
@@ -174,9 +218,9 @@ export declare class LanceDBVectorStore extends VectorStore {
      */
     getConnection(): Connection;
     /**
-     * Get the underlying LanceDB table.
+     * Get the underlying LanceDB table, or null if no data has been inserted yet.
      */
-    getTable(): Table;
+    getTable(): Table | null;
     /**
      * Get the configured embeddings provider.
      */
@@ -194,6 +238,10 @@ export declare class LanceDBVectorStore extends VectorStore {
      * Optimize the table for better performance.
      */
     optimize(): Promise<void>;
+    /**
+     * Get the configured metadata fields.
+     */
+    getMetadataFields(): MetadataFieldDefinition[] | undefined;
     /**
      * Build a SQL filter string from a filter object.
      */
@@ -203,12 +251,12 @@ export declare class LanceDBVectorStore extends VectorStore {
      */
     private processResults;
     /**
-     * Extract metadata from a row based on metadataFields configuration.
+     * Extract metadata from a row.
+     *
+     * In managed mode: returns user-defined fields plus unpacked chunk_metadata.
+     * In pre-existing table mode: returns all non-system columns, with
+     * chunk_metadata unpacked if present.
      */
     private extractMetadata;
-    /**
-     * Get the configured metadata fields.
-     */
-    getMetadataFields(): MetadataFieldDefinition[] | undefined;
 }
 //# sourceMappingURL=LanceDBVectorStore.d.ts.map