modular-agent-examples 0.0.1

package/vector-store-filtering.ts

@@ -0,0 +1,303 @@
+import "dotenv/config";
+import { rmSync } from "fs";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { LanceDBVectorStore } from "../lib/vectorstore/LanceDBVectorStore";
+import { OpenAIEmbeddings } from "../lib/embeddings/OpenAIEmbeddings";
+
+/**
+ * Example demonstrating multi-tenancy and filtering in vector stores.
+ *
+ * Shows how to:
+ * 1. Store documents with tenant/project metadata
+ * 2. Create tenant-specific retrieval tools
+ * 3. Ensure agents only access documents for their tenant
+ *
+ * NOTE: LanceDB uses DataFusion for SQL filtering, which normalizes unquoted
+ * identifiers to lowercase. Use snake_case for metadata field names to avoid
+ * case-sensitivity issues.
+ */
+
+// Sample multi-tenant data
+const DOCUMENTS = [
+  // Tenant: Acme Corp
+  {
+    id: "acme-1",
+    content:
+      "Acme Corp uses a monthly billing cycle. Invoices are sent on the 1st of each month.",
+    metadata: { tenant_id: "acme", project_id: "proj-123", category: "billing" },
+  },
+  {
+    id: "acme-2",
+    content: "Acme Corp's support hours are Monday-Friday, 9am-5pm EST.",
+    metadata: { tenant_id: "acme", project_id: "proj-123", category: "support" },
+  },
+  {
+    id: "acme-3",
+    content: "Acme Corp has a 30-day refund policy for all services.",
+    metadata: { tenant_id: "acme", project_id: "proj-456", category: "policy" },
+  },
+
+  // Tenant: TechStart Inc
+  {
+    id: "techstart-1",
+    content:
+      "TechStart Inc uses annual billing. Payment is due within 15 days of invoice.",
+    metadata: {
+      tenant_id: "techstart",
+      project_id: "proj-789",
+      category: "billing",
+    },
+  },
+  {
+    id: "techstart-2",
+    content:
+      "TechStart Inc offers 24/7 premium support for enterprise customers.",
+    metadata: {
+      tenant_id: "techstart",
+      project_id: "proj-789",
+      category: "support",
+    },
+  },
+  {
+    id: "techstart-3",
+    content: "TechStart Inc has a 60-day money-back guarantee.",
+    metadata: {
+      tenant_id: "techstart",
+      project_id: "proj-789",
+      category: "policy",
+    },
+  },
+
+  // Tenant: Global Services
+  {
+    id: "global-1",
+    content:
+      "Global Services bills quarterly. Invoices are sent 15 days before the period ends.",
+    metadata: {
+      tenant_id: "global",
+      project_id: "proj-101",
+      category: "billing",
+    },
+  },
+  {
+    id: "global-2",
+    content:
+      "Global Services provides support in 12 languages, available 24/7.",
+    metadata: {
+      tenant_id: "global",
+      project_id: "proj-202",
+      category: "support",
+    },
+  },
+];
+
+async function vectorStoreFilteringExample() {
+  console.log("Multi-Tenancy Vector Store Example\n");
+  console.log("===================================\n");
+
+  // Check for required API keys
+  if (!process.env.OPENAI_API_KEY || !process.env.ANTHROPIC_API_KEY) {
+    console.error("Error: OPENAI_API_KEY and ANTHROPIC_API_KEY are required");
+    process.exit(1);
+  }
+
+  try {
+    // Step 1: Create embeddings and vector store (clean slate for demo)
+    console.log("1. Creating vector store...");
+    rmSync("./examples/data/vectors-filtered", { recursive: true, force: true });
+    const embeddings = new OpenAIEmbeddings({
+      model: "text-embedding-3-small",
+    });
+
+    const store = await LanceDBVectorStore.create({
+      name: "multi_tenant_kb",
+      uri: "./examples/data/vectors-filtered",
+      tableName: "tenant_docs",
+      embeddings,
+      metadataFields: [
+        { name: "tenant_id", type: "string" as const },
+        { name: "project_id", type: "string" as const },
+        { name: "category", type: "string" as const },
+        { name: "added_by", type: "string" as const },
+      ],
+    });
+    console.log("   Store created\n");
+
+    // Step 2: Add documents with tenant metadata
+    console.log("2. Adding documents for multiple tenants...");
+    await store.addDocuments(DOCUMENTS);
+    console.log(`   Added ${DOCUMENTS.length} documents\n`);
+
+    // Step 3: Test filtering directly
+    console.log("3. Testing direct search with filters...\n");
+
+    console.log("   Searching for billing info (no filter):");
+    const allBilling = await store.search("billing cycle", {
+      limit: 3,
+      filter: { category: "billing" },
+    });
+    for (const result of allBilling) {
+      console.log(
+        `   - [${result.score.toFixed(3)}] ${
+          result.document.metadata?.tenant_id
+        }: ${result.document.content}`
+      );
+    }
+    console.log();
+
+    console.log("   Searching for billing info (Acme only):");
+    const acmeBilling = await store.search("billing cycle", {
+      limit: 3,
+      filter: { tenant_id: "acme", category: "billing" },
+    });
+    for (const result of acmeBilling) {
+      console.log(
+        `   - [${result.score.toFixed(3)}] ${
+          result.document.metadata?.tenant_id
+        }: ${result.document.content}`
+      );
+    }
+    console.log();
+
+    // Step 4: Create tenant-specific agents
+    console.log("4. Creating tenant-specific agents...\n");
+
+    // Acme Corp agent - can only access Acme documents
+    const acmeSearchTool = store.toRetrievalTool(
+      "Search the Acme Corp knowledge base for billing, support, and policy information",
+      {
+        defaultLimit: 3,
+        defaultFilter: { tenant_id: "acme" }, // Always filter to Acme
+        allowFilterOverride: false, // Agent cannot override this filter
+      }
+    );
+
+    const acmeAgent = new ClaudeAgent({
+      id: "acme-agent",
+      name: "Acme Support Agent",
+      description:
+        "You are a customer support agent for Acme Corp. Use the search tool to find accurate information.",
+      apiKey: process.env.ANTHROPIC_API_KEY as string,
+      tools: [acmeSearchTool],
+      model: "claude-sonnet-4-20250514",
+    });
+
+    // TechStart agent - can only access TechStart documents
+    const techstartSearchTool = store.toRetrievalTool(
+      "Search the TechStart Inc knowledge base for billing, support, and policy information",
+      {
+        defaultLimit: 3,
+        defaultFilter: { tenant_id: "techstart" },
+        allowFilterOverride: false,
+      }
+    );
+
+    const techstartAgent = new ClaudeAgent({
+      id: "techstart-agent",
+      name: "TechStart Support Agent",
+      description:
+        "You are a customer support agent for TechStart Inc. Use the search tool to find accurate information.",
+      apiKey: process.env.ANTHROPIC_API_KEY as string,
+      tools: [techstartSearchTool],
+      model: "claude-sonnet-4-20250514",
+    });
+
+    // Step 5: Test tenant isolation
+    console.log("5. Testing tenant isolation...\n");
+
+    const question = "What is the billing cycle?";
+
+    console.log(`   Question: "${question}"\n`);
+
+    console.log("   Acme Agent Response:");
+    const acmeResponse = await acmeAgent.execute(question);
+    console.log(`   ${acmeResponse}\n`);
+
+    console.log("   TechStart Agent Response:");
+    const techstartResponse = await techstartAgent.execute(question);
+    console.log(`   ${techstartResponse}\n`);
+
+    // Step 6: Demonstrate project-level filtering with override
+    console.log("6. Creating agent with filter override capability...\n");
+
+    const flexibleSearchTool = store.toRetrievalTool(
+      "Search the knowledge base. You can filter by tenant_id, project_id, or category.",
+      {
+        defaultLimit: 3,
+        defaultFilter: { tenant_id: "acme" }, // Default to Acme
+        allowFilterOverride: true, // But allow overriding
+      }
+    );
+
+    const flexibleAgent = new ClaudeAgent({
+      id: "flexible-agent",
+      name: "Flexible Search Agent",
+      description: `You are a knowledge base assistant. Use the search tool with appropriate filters.
+      When asked about a specific project, use the project_id filter.
+      When asked about a category, use the category filter.`,
+      apiKey: process.env.ANTHROPIC_API_KEY as string,
+      tools: [flexibleSearchTool],
+      model: "claude-sonnet-4-20250514",
+    });
+
+    console.log(
+      '   Question: "What is the support policy for project proj-789?"\n'
+    );
+    const projectResponse = await flexibleAgent.execute(
+      "What is the support policy for project proj-789?"
+    );
+    console.log(`   Response: ${projectResponse}\n`);
+
+    // Step 7: Demonstrate adding documents with default metadata
+    console.log("7. Adding new document with automatic tenant tagging...\n");
+
+    const acmeAddTool = store.toAddDocumentsTool(
+      "Add new documents to the Acme Corp knowledge base",
+      {
+        defaultMetadata: {
+          tenant_id: "acme",
+          project_id: "proj-123",
+          added_by: "system",
+        },
+      }
+    );
+
+    const addAgent = new ClaudeAgent({
+      id: "add-agent",
+      name: "Document Manager",
+      description: "You help add new documents to the knowledge base.",
+      apiKey: process.env.ANTHROPIC_API_KEY as string,
+      tools: [acmeAddTool],
+      model: "claude-sonnet-4-20250514",
+    });
+
+    console.log("   Adding: 'Acme Corp offers a new premium support tier.'\n");
+    await addAgent.execute(
+      "Add a document with id 'acme-4' and content: 'Acme Corp offers a new premium support tier with 24/7 assistance.'"
+    );
+
+    // Verify it was added with correct metadata
+    const newDoc = await store.getById("acme-4");
+    console.log("   Document added with metadata:");
+    console.log(`   ${JSON.stringify(newDoc?.metadata, null, 2)}\n`);
+
+    console.log("✅ Multi-tenancy example completed successfully!\n");
+    console.log("Key takeaways:");
+    console.log("- Use defaultFilter to enforce tenant isolation");
+    console.log("- Set allowFilterOverride: false for strict security");
+    console.log("- Use defaultMetadata to auto-tag documents");
+    console.log(
+      "- Combine filters (tenant + project + category) for fine-grained control"
+    );
+    console.log(
+      "- Use snake_case for metadata field names (LanceDB normalizes SQL identifiers to lowercase)"
+    );
+
+    process.exit(0);
+  } catch (error) {
+    console.error("Error:", error);
+    process.exit(1);
+  }
+}
+
+vectorStoreFilteringExample();

package/vector-store.ts

@@ -0,0 +1,210 @@
+import "dotenv/config";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { LanceDBVectorStore } from "../lib/vectorstore/LanceDBVectorStore";
+import { OpenAIEmbeddings } from "../lib/embeddings/OpenAIEmbeddings";
+import { RecursiveChunker, IngestionPipeline, OpenAiAgent } from "../lib";
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+import { createInterface } from "node:readline/promises";
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+/**
+ * Recursively load all markdown files from a directory
+ */
+function loadMarkdownFiles(
+  dir: string,
+  baseDir?: string
+): Array<{ path: string; content: string }> {
+  const base = baseDir || dir;
+  const files: Array<{ path: string; content: string }> = [];
+
+  const items = readdirSync(dir);
+
+  for (const item of items) {
+    const fullPath = join(dir, item);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      // Recursively load from subdirectories
+      files.push(...loadMarkdownFiles(fullPath, base));
+    } else if (item.endsWith(".md")) {
+      // Load markdown file
+      const content = readFileSync(fullPath, "utf-8");
+      const relativePath = fullPath.replace(base + "/", "");
+      files.push({ path: relativePath, content });
+    }
+  }
+
+  return files;
+}
+
+async function vectorStoreExample() {
+  console.log("Vector Store Example with RAG Agent\n");
+  console.log("====================================\n");
+
+  // Check for required API keys
+  if (!process.env.OPENAI_API_KEY) {
+    console.error("Error: OPENAI_API_KEY is required for embeddings");
+    process.exit(1);
+  }
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.error("Error: ANTHROPIC_API_KEY is required for the agent");
+    process.exit(1);
+  }
+
+  try {
+    // Step 1: Create embeddings provider
+    console.log("1. Creating OpenAI embeddings provider...");
+    const embeddings = new OpenAIEmbeddings({
+      model: "text-embedding-3-small",
+    });
+    console.log(
+      `   Model: ${embeddings.model}, Dimensions: ${embeddings.dimensions}\n`
+    );
+
+    // Step 2: Create vector store
+    console.log("2. Creating LanceDB vector store...");
+    const store = await LanceDBVectorStore.create({
+      name: "knowledge_base",
+      uri: "./examples/data/vectors",
+      tableName: "agention_docs",
+      embeddings,
+      metadataFields: [
+        { name: "source", type: "string" as const },
+        { name: "type", type: "string" as const },
+      ],
+    });
+    console.log("   Store created successfully\n");
+
+    // Step 3: Create chunker
+    console.log("3. Creating RecursiveChunker for semantic splitting...");
+    const chunker = new RecursiveChunker({
+      chunkSize: 1000,
+      chunkOverlap: 100,
+      separators: ["\n\n", "\n", ". ", " "],
+    });
+    console.log("   Chunker created\n");
+
+    // Step 4: Create ingestion pipeline
+    console.log("4. Creating ingestion pipeline...");
+    const pipeline = new IngestionPipeline(chunker, embeddings, store);
+    console.log("   Pipeline ready\n");
+
+    // Step 5: Load and ingest documentation files
+    console.log("5. Loading documentation files from docs/guide/...");
+    const docsPath = join(__dirname, "../docs/guide");
+    const markdownFiles = loadMarkdownFiles(docsPath);
+    console.log(`   Found ${markdownFiles.length} markdown files\n`);
+
+    // Step 6: Ingest documents using pipeline
+    console.log("6. Ingesting documents (this may take a moment)...");
+
+    const documents = markdownFiles.map((file) => ({
+      text: file.content,
+      options: {
+        sourceId: file.path,
+        sourcePath: file.path,
+        metadata: {
+          source: file.path,
+          type: "documentation",
+        },
+      },
+    }));
+
+    const result = await pipeline.ingestMany(documents, {
+      batchSize: 10,
+      skipDuplicates: true, // Skip chunks that already exist (by content hash)
+      onProgress: ({ phase, processed, total }) => {
+        console.log(`   ${phase}: ${processed}/${total}`);
+      },
+    });
+
+    console.log("\n   Ingestion complete:");
+    console.log(`   - Chunks processed: ${result.chunksProcessed}`);
+    console.log(`   - Chunks skipped (duplicates): ${result.chunksSkipped}`);
+    console.log(`   - Chunks stored: ${result.chunksStored}`);
+    console.log(`   - Duration: ${result.duration}ms`);
+    console.log(`   - Errors: ${result.errors.length}\n`);
+
+    // Step 7: Test direct search
+    console.log('7. Testing direct search for "pipeline"...');
+    const searchResults = await store.search(
+      "How do I chain agents together?",
+      {
+        limit: 3,
+      }
+    );
+    console.log("   Top results:");
+    for (const result of searchResults) {
+      console.log(
+        `   - [${result.score.toFixed(3)}] ${result.document.metadata?.source}`
+      );
+      console.log(`     ${result.document.content.substring(0, 100)}...\n`);
+    }
+
+    // Step 8: Create retrieval and navigation tools
+    console.log("8. Creating tools for the agent...");
+    const searchTool = store.toRetrievalTool(
+      "Search the Agention documentation for information about agents, tools, pipelines, vector stores, and other features",
+      { defaultLimit: 3 }
+    );
+    const getChunkTool = store.toGetChunkByIdTool(
+      "Retrieve a specific chunk by ID. Use this to get more context by reading previous or next chunks. Check the metadata.prev_id and metadata.next_id fields from search results."
+    );
+    console.log(`   Search tool: ${searchTool.name}`);
+    console.log(`   Get chunk tool: ${getChunkTool.name}\n`);
+
+    // Step 9: Create agent with the tools
+    console.log("9. Creating Claude agent with search and navigation tools...");
+    const agent = new OpenAiAgent({
+      id: "rag-agent",
+      name: "Documentation Assistant",
+      description:
+        "You are a helpful assistant that answers questions about Agention. Always use the search tool to find relevant documentation before answering. If you need more context, use the get_chunk tool with previousChunkId or nextChunkId to read surrounding chunks. Base your answers on the search results and cite the source files.",
+      apiKey: process.env.OPENAI_API_KEY as string,
+      tools: [searchTool, getChunkTool],
+      model: "gpt-4.1-nano",
+    });
+    console.log("   Agent created\n");
+
+    // Step 10: Interactive Q&A
+    console.log("10. Interactive Q&A (type 'exit' to quit)\n");
+    console.log("   Try asking:\n");
+    console.log("   - What are the different types of executors?");
+    console.log("   - How do I create a pipeline?");
+    console.log("   - What embedding models are supported?");
+    console.log("   - How do vector stores work?\n");
+
+    while (true) {
+      const question = await rl.question("You: ");
+
+      if (question.toLowerCase() === "exit") {
+        console.log("\nGoodbye!");
+        break;
+      }
+
+      if (!question.trim()) {
+        continue;
+      }
+
+      console.log("\nAssistant: Searching documentation...\n");
+
+      const response = await agent.execute(question);
+      console.log(`Assistant: ${response}\n`);
+    }
+
+    rl.close();
+    process.exit(0);
+  } catch (error) {
+    console.error("Error:", error);
+    rl.close();
+    process.exit(1);
+  }
+}
+
+vectorStoreExample();

package/vectorstore/store/dbService.ts

@@ -0,0 +1,80 @@
+import "dotenv/config";
+import * as lancedb from "@lancedb/lancedb";
+import * as arrow from "apache-arrow";
+
+import { Utf8 } from "apache-arrow";
+import { embedding } from "@lancedb/lancedb";
+import "@lancedb/lancedb/embedding/openai";
+// import { EmbeddingFunction, getRegistry } from "@lancedb/lancedb/embedding";
+
+const setup = async () => {
+  const db = await lancedb.connect("./");
+
+  // const _tbl =
+  // await db.createTable(
+  //   "myTable",
+  //   { mode: "overwrite" }
+  // );
+  let tbl: lancedb.Table;
+  // console.log(process.env.OPENAI_API_KEY);
+  // const apiKey = process.env.OPENAI_API_KEY;
+  // await db.dropTable("words");
+  const tableNames = await db.tableNames();
+
+  if (tableNames.includes("words")) {
+    tbl = await db.openTable("words");
+  } else {
+    const func = embedding.getRegistry().get("openai")?.create({
+      model: "text-embedding-ada-002",
+      // apiKey,
+    });
+
+    // const func = embedding.getRegistry()!.get("openai")!.create({
+    //   model: "text-embedding-ada-002",
+    //   apiKey: process.env.OPENAI_API_KEY,
+    // });
+    const wordsSchema = embedding.LanceSchema({
+      text: func!.sourceField(new Utf8()),
+      vector: func!.vectorField(),
+      id: new arrow.Int32(),
+    });
+    tbl = await db.createEmptyTable("words", wordsSchema, {
+      mode: "overwrite",
+    });
+
+    await tbl.add([
+      { text: "hello world", id: 1 },
+      { text: "goodbye world", id: 2 },
+    ]);
+  }
+
+  console.log(tableNames);
+  await tbl.add([
+    {
+      text: "The world says hello and goodbye to the person who is coming and going",
+      id: 3,
+    },
+    {
+      text: `LanceDB registers the Sentence Transformers embeddings function in the registry as sentence-transformers. You can pass any supported model name to the create. By default it uses "sentence-transformers/paraphrase-MiniLM-L6-v2".`,
+      id: 4,
+    },
+  ]);
+
+  // const data = [
+  //   { vector: [1.3, 1.4], item: "fizz", price: 100.0 },
+  //   { vector: [9.5, 56.2], item: "buzz", price: 200.0 },
+  // ];
+
+  const query = "Sentence Transformers";
+  const actual = await tbl.search(query).where("id > 2").limit(2).toArray();
+
+  // await tbl.delete("id = 4");
+  // const res = await tbl.search([100, 100]).limit(2).toArray();
+  actual.forEach(({ text, id }) => console.log(text, id));
+  console.log((await tbl.query().where("id = 4").limit(10).toArray()).length);
+
+  // console.log(actual.text);
+  // await tbl.add(data);
+};
+
+setup();

package/voyage-embeddings.ts

@@ -0,0 +1,99 @@
+/**
+ * VoyageAI Embeddings Example
+ *
+ * Demonstrates how to use VoyageAI embeddings with the vector store.
+ *
+ * Prerequisites:
+ * - Set VOYAGE_API_KEY environment variable
+ * - Run with: npm run example -- examples/voyage-embeddings.ts
+ */
+import "dotenv/config";
+import { VoyageAIEmbeddings } from "../lib/embeddings/VoyageAIEmbeddings";
+import { LanceDBVectorStore } from "../lib/vectorstore/LanceDBVectorStore";
+
+async function main() {
+  console.log("=== VoyageAI Embeddings Example ===\n");
+
+  // Check for required API key
+  if (!process.env.VOYAGE_API_KEY) {
+    console.error("Error: VOYAGE_API_KEY environment variable is not set");
+    console.log("\nPlease set your VoyageAI API key:");
+    console.log("  export VOYAGE_API_KEY=your-api-key-here");
+    process.exit(1);
+  }
+
+  // Create VoyageAI embeddings instance
+  console.log("Creating VoyageAI embeddings with voyage-4 model...");
+  const embeddings = new VoyageAIEmbeddings({
+    model: "voyage-4",
+    inputType: "document", // Use "document" for indexing, "query" for searching
+  });
+
+  console.log(`Model: ${embeddings.model}`);
+  console.log(`Dimensions: ${embeddings.dimensions}\n`);
+
+  // Example: Generate embeddings directly
+  console.log("Generating embeddings for sample texts...");
+  const texts = [
+    "VoyageAI provides state-of-the-art embedding models",
+    "Vector databases enable semantic search capabilities",
+    "The voyage-4 model offers excellent performance",
+  ];
+
+  const vectors = await embeddings.embed(texts);
+  console.log(`Generated ${vectors.length} embeddings`);
+  console.log(`First embedding dimensions: ${vectors[0].length}\n`);
+
+  // Example: Using with LanceDB Vector Store
+  console.log("Creating LanceDB vector store with VoyageAI embeddings...");
+  const store = await LanceDBVectorStore.create({
+    name: "voyage_demo",
+    uri: "./data/voyage-example",
+    tableName: "documents",
+    embeddings,
+    metadataFields: [
+      { name: "category", type: "string" as const },
+      { name: "source", type: "string" as const },
+    ],
+  });
+
+  // Add documents (embeddings generated automatically)
+  console.log("Adding documents to vector store...");
+  await store.addDocuments([
+    {
+      id: "doc1",
+      content: "VoyageAI specializes in embedding models for semantic search",
+      metadata: { category: "ai", source: "docs" },
+    },
+    {
+      id: "doc2",
+      content: "voyage-4 is their latest general-purpose embedding model",
+      metadata: { category: "models", source: "docs" },
+    },
+    {
+      id: "doc3",
+      content: "voyage-code-3 is optimized for code search and understanding",
+      metadata: { category: "models", source: "docs" },
+    },
+  ]);
+
+  console.log("Documents added successfully!\n");
+
+  // Perform semantic search
+  console.log("Performing semantic search...");
+  const query = "What is the latest VoyageAI model?";
+  const results = await store.search(query, { limit: 2 });
+
+  console.log(`\nQuery: "${query}"`);
+  console.log("Results:");
+  results.forEach((result, i) => {
+    console.log(
+      `${i + 1}. [Score: ${result.score.toFixed(4)}] ${result.content}`
+    );
+    console.log(`   Metadata:`, result.metadata);
+  });
+
+  console.log("\n=== Example Complete ===");
+}
+
+main().catch(console.error);