modular-agent-examples 0.0.1

package/ingestion-pipeline.ts

@@ -0,0 +1,353 @@
+/**
+ * Ingestion Pipeline Example
+ *
+ * Demonstrates how to use the chunkers and ingestion pipeline
+ * to process documents and store them in a vector database.
+ *
+ * Prerequisites:
+ * - Set OPENAI_API_KEY environment variable for full pipeline example
+ * - Run with: npm run example -- examples/ingestion-pipeline.ts
+ */
+import "dotenv/config";
+import {
+  TextChunker,
+  RecursiveChunker,
+  TokenChunker,
+  IngestionPipeline,
+} from "../lib";
+import { OpenAIEmbeddings } from "../lib/embeddings/OpenAIEmbeddings";
+import { LanceDBVectorStore } from "../lib/vectorstore/LanceDBVectorStore";
+
+async function main() {
+  console.log("=== Text Chunker Examples ===\n");
+
+  // Sample document
+  const sampleDoc = `# Introduction
+
+This is a sample document that demonstrates the text chunking capabilities.
+The chunker will split this document into smaller pieces for vector storage.
+
+## Features
+
+The chunking system supports multiple strategies:
+
+1. TextChunker - Simple character-based splitting with overlap
+2. RecursiveChunker - Smart splitting on semantic boundaries
+3. TokenChunker - Token-aware splitting for LLM compatibility
+
+## Usage
+
+To use a chunker, simply create an instance with your desired configuration
+and call the chunk method with your text.
+
+### Example Code
+
+Here's how you might use the RecursiveChunker:
+
+\`\`\`typescript
+const chunker = new RecursiveChunker({
+  chunkSize: 500,
+  chunkOverlap: 50,
+});
+
+const chunks = await chunker.chunk(document);
+\`\`\`
+
+## Conclusion
+
+Text chunking is an essential step in building RAG applications.
+Choose the right chunker based on your use case and document types.`;
+
+  // Example 1: TextChunker
+  console.log("1. TextChunker (character-based)");
+  console.log("-".repeat(40));
+
+  const textChunker = new TextChunker({
+    chunkSize: 200,
+    chunkOverlap: 20,
+  });
+
+  const textChunks = await textChunker.chunk(sampleDoc, {
+    sourceId: "sample-doc",
+    sourcePath: "/docs/sample.md",
+  });
+
+  console.log(`Created ${textChunks.length} chunks`);
+  console.log(`First chunk (${textChunks[0].metadata.char_count} chars):`);
+  console.log(textChunks[0].content.substring(0, 100) + "...\n");
+
+  // Example 2: RecursiveChunker
+  console.log("2. RecursiveChunker (semantic boundaries)");
+  console.log("-".repeat(40));
+
+  const recursiveChunker = new RecursiveChunker({
+    chunkSize: 300,
+    chunkOverlap: 30,
+    separators: ["\n\n", "\n", ". ", " "],
+  });
+
+  const recursiveChunks = await recursiveChunker.chunk(sampleDoc, {
+    sourceId: "sample-doc",
+    metadata: { type: "documentation" },
+  });
+
+  console.log(`Created ${recursiveChunks.length} chunks`);
+  for (let i = 0; i < Math.min(3, recursiveChunks.length); i++) {
+    const chunk = recursiveChunks[i];
+    console.log(
+      `  Chunk ${i}: ${chunk.metadata.char_count} chars, section: ${chunk.metadata.section ?? "N/A"}`
+    );
+  }
+  console.log();
+
+  // Example 3: TokenChunker
+  console.log("3. TokenChunker (token-aware)");
+  console.log("-".repeat(40));
+
+  const tokenChunker = new TokenChunker({
+    chunkSize: 100, // 100 tokens
+    chunkOverlap: 10,
+  });
+
+  const tokenChunks = await tokenChunker.chunk(sampleDoc, {
+    sourceId: "sample-doc",
+  });
+
+  console.log(`Created ${tokenChunks.length} chunks`);
+  for (let i = 0; i < Math.min(3, tokenChunks.length); i++) {
+    const chunk = tokenChunks[i];
+    console.log(
+      `  Chunk ${i}: ~${chunk.metadata.token_count} tokens, ${chunk.metadata.char_count} chars`
+    );
+  }
+  console.log();
+
+  // Example 4: Chunk with custom processor
+  console.log("4. Chunker with custom processor (filtering)");
+  console.log("-".repeat(40));
+
+  const filteringChunker = new TextChunker({
+    chunkSize: 150,
+    chunkProcessor: (chunk) => {
+      // Filter out very short chunks
+      if (chunk.content.trim().length < 50) {
+        console.log(
+          `  Filtered out short chunk: "${chunk.content
+            .trim()
+            .substring(0, 30)}..."`
+        );
+        return null;
+      }
+      // Add custom metadata
+      return {
+        ...chunk,
+        metadata: {
+          ...chunk.metadata,
+          processedAt: new Date().toISOString(),
+        },
+      };
+    },
+  });
+
+  const filteredChunks = await filteringChunker.chunk(sampleDoc);
+  console.log(`Created ${filteredChunks.length} chunks after filtering\n`);
+
+  // Example 5: Chunk linking
+  console.log("5. Chunk linking (previous/next)");
+  console.log("-".repeat(40));
+
+  const linkingChunker = new TextChunker({ chunkSize: 15 });
+  const linkedChunks = await linkingChunker.chunk(
+    "First part. Second part. Third part. Fourth part.",
+    {
+      sourceId: "linked-doc",
+    }
+  );
+
+  for (const chunk of linkedChunks) {
+    console.log(`  ${chunk.id}:`);
+    console.log(`    prev: ${chunk.metadata.prev_id ?? "null"}`);
+    console.log(`    next: ${chunk.metadata.next_id ?? "null"}`);
+  }
+  console.log();
+
+  // Example 6: Full ingestion pipeline (requires API keys)
+  console.log("6. Full Ingestion Pipeline");
+  console.log("-".repeat(40));
+
+  if (!process.env.OPENAI_API_KEY) {
+    console.log("Skipping ingestion pipeline (OPENAI_API_KEY not set)");
+    console.log("Set OPENAI_API_KEY to run the full pipeline example.\n");
+  } else {
+    try {
+      // Create components
+      const embeddings = new OpenAIEmbeddings({
+        model: "text-embedding-3-small",
+      });
+
+      const store = await LanceDBVectorStore.create({
+        name: "ingestion-demo",
+        uri: "./data/ingestion-demo",
+        tableName: "documents",
+        embeddings,
+        metadataFields: [
+          { name: "author", type: "string" as const, nullable: true },
+        ],
+      });
+
+      const pipeline = new IngestionPipeline(
+        new RecursiveChunker({ chunkSize: 500, chunkOverlap: 50 }),
+        embeddings,
+        store
+      );
+
+      // Ingest the sample document — table is created here on first insert
+      const result = await pipeline.ingest(sampleDoc, {
+        sourceId: "sample-doc",
+        sourcePath: "/docs/sample.md",
+        metadata: {
+          author: "demo",
+          createdAt: new Date().toISOString(),
+        },
+        batchSize: 10,
+        onProgress: ({ phase, processed, total }) => {
+          console.log(`  ${phase}: ${processed}/${total}`);
+        },
+      });
+
+      console.log("\nIngestion complete:");
+      console.log(`  Chunks processed: ${result.chunksProcessed}`);
+      console.log(`  Chunks stored: ${result.chunksStored}`);
+      console.log(`  Duration: ${result.duration}ms`);
+      console.log(`  Errors: ${result.errors.length}`);
+      for (const e of result.errors) {
+        console.error("  Error:", e.error);
+      }
+
+      // Schema is now available after first insert
+      const tableSchema = await store.getTable()!.schema();
+      console.log(
+        "Table schema fields:",
+        tableSchema.fields.map((f) => `${f.name}:${f.type}`).join(", ")
+      );
+
+      // Inspect a raw stored row
+      const rawRows = await store.getTable()!.query().limit(1).toArray();
+      console.log(
+        "Raw row sample:",
+        JSON.stringify(rawRows[0], (_, v) =>
+          v instanceof Float32Array ? "<vector>" : v
+        )
+      );
+
+      // Test search
+      console.log("\nTesting search...");
+      const searchResults = await store.search("chunking strategies", {
+        limit: 3,
+      });
+
+      console.log(`Found ${searchResults.length} results:`);
+      for (const result of searchResults) {
+        console.log(`  - Score: ${result.score.toFixed(3)}`);
+        console.log(
+          `    Content: ${result.document.content.substring(0, 80)}...`
+        );
+        // User metadata (author) is a top-level column; chunk metadata is in chunk_metadata struct
+        console.log(`    author: ${result.document.metadata?.author}`);
+      }
+
+      // Search with metadata filter on user-defined columns
+      console.log("\nTesting search with metadata filter...");
+      const filtered = await store.search("chunking", {
+        limit: 3,
+        filter: { author: "demo" },
+      });
+      console.log(`Found ${filtered.length} results filtered by author='demo'`);
+    } catch (error) {
+      console.error("Pipeline error:", error);
+    }
+  }
+
+  // Example 7: Batch ingestion
+  console.log("\n7. Batch Document Ingestion");
+  console.log("-".repeat(40));
+
+  if (!process.env.OPENAI_API_KEY) {
+    console.log("Skipping batch ingestion (OPENAI_API_KEY not set)\n");
+  } else {
+    try {
+      const embeddings = new OpenAIEmbeddings({
+        model: "text-embedding-3-small",
+      });
+
+      const store = await LanceDBVectorStore.create({
+        name: "batch-demo",
+        uri: "./data/batch-demo",
+        tableName: "documents",
+        embeddings,
+        metadataFields: [
+          { name: "category", type: "string" as const, nullable: true },
+        ],
+      });
+
+      const pipeline = new IngestionPipeline(
+        new RecursiveChunker({ chunkSize: 300 }),
+        embeddings,
+        store
+      );
+
+      // Simulate multiple documents
+      const documents = [
+        {
+          text: "Document 1: Introduction to machine learning concepts and algorithms.",
+          options: { sourceId: "doc-1", metadata: { category: "ml" } },
+        },
+        {
+          text: "Document 2: Deep learning fundamentals including neural networks and backpropagation.",
+          options: { sourceId: "doc-2", metadata: { category: "dl" } },
+        },
+        {
+          text: "Document 3: Natural language processing techniques for text analysis.",
+          options: { sourceId: "doc-3", metadata: { category: "nlp" } },
+        },
+      ];
+
+      const result = await pipeline.ingestMany(documents, {
+        batchSize: 5,
+        onProgress: ({ phase, processed, total }) => {
+          console.log(`  ${phase}: ${processed}/${total}`);
+        },
+      });
+
+      console.log("\nBatch ingestion complete:");
+      console.log(`  Total chunks: ${result.chunksStored}`);
+      console.log(`  Duration: ${result.duration}ms`);
+
+      const batchTableSchema = await store.getTable()!.schema();
+      console.log(
+        "Table schema fields:",
+        batchTableSchema.fields.map((f) => `${f.name}:${f.type}`).join(", ")
+      );
+
+      // The 'category' user metadata is a top-level column — filterable directly
+      console.log("\nTesting search with category filter...");
+      const mlResults = await store.search("neural networks", {
+        limit: 3,
+        filter: { category: "dl" },
+      });
+      console.log(
+        `Found ${mlResults.length} results filtered by category='dl'`
+      );
+      for (const r of mlResults) {
+        console.log(`  - category: ${r.document.metadata?.category}`);
+        console.log(`    ${r.document.content.substring(0, 60)}...`);
+      }
+    } catch (error) {
+      console.error("Batch ingestion error:", error);
+    }
+  }
+
+  console.log("\n=== Examples Complete ===");
+}
+
+main().catch(console.error);

package/mcp-airbnb-example.ts

@@ -0,0 +1,69 @@
+import "dotenv/config";
+
+/**
+ * MCP Airbnb Example
+ *
+ * Demonstrates using the Airbnb MCP server to search listings and retrieve
+ * property details via an AI agent.
+ *
+ * The @openbnb/mcp-server-airbnb server exposes two tools:
+ *   - airbnb_search      — search listings by location, dates, guests, price
+ *   - airbnb_listing_details — get full details for a specific listing ID
+ *
+ * No API key required. Respects Airbnb's robots.txt by default.
+ *
+ * Prerequisites:
+ *   npm install @modelcontextprotocol/sdk @anthropic-ai/sdk
+ *
+ * Usage:
+ *   ANTHROPIC_API_KEY=sk-ant-... ts-node examples/mcp-airbnb-example.ts
+ */
+
+import { MCPClient } from "../lib/mcp";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error("ANTHROPIC_API_KEY environment variable is required");
+  }
+
+  // Spawn the Airbnb MCP server as a local process via npx
+  const mcp = MCPClient.fromStdio({
+    command: "npx",
+    args: ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
+  });
+
+  console.log("Connecting to Airbnb MCP server...");
+  await mcp.connect();
+
+  const tools = mcp.getTools();
+  console.log(
+    `Discovered ${tools.length} tools: ${tools.map((t) => t.name).join(", ")}\n`
+  );
+
+  const agent = new ClaudeAgent({
+    id: "airbnb-agent",
+    name: "Airbnb Agent",
+    description:
+      "You are a helpful travel assistant. Use the available tools to search Airbnb listings and provide detailed recommendations based on the user's needs.",
+    apiKey,
+    model: "claude-sonnet-4-6",
+    maxTokens: 10000,
+    tools,
+  });
+
+  const result = await agent.execute(
+    "Find me a nice place to stay Near Weymouth for 2 adults " +
+      "checking in on 2026-03-15 and checking out on 2026-03-20. " +
+      "Give me the top 3 options with prices and a brief description of each."
+  );
+
+  console.log("Agent response:\n");
+  console.log(result);
+
+  await mcp.disconnect();
+  console.log("\nDisconnected from Airbnb MCP server.");
+}
+
+main().catch(console.error);

package/mcp-http-example.ts

@@ -0,0 +1,70 @@
+import "dotenv/config";
+/**
+ * MCP HTTP Example
+ *
+ * Demonstrates connecting to a remote MCP server via Streamable HTTP transport.
+ * Shows both static API key auth (via headers) and the OAuth provider pattern.
+ *
+ * Prerequisites:
+ *   npm install @modelcontextprotocol/sdk @anthropic-ai/sdk
+ *
+ * Usage:
+ *   MCP_SERVER_URL=http://localhost:3000/mcp \
+ *   MCP_API_KEY=my-key \
+ *   ANTHROPIC_API_KEY=sk-ant-... \
+ *     ts-node examples/mcp-http-example.ts
+ */
+
+import { MCPClient } from "../lib/mcp";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const mcpServerUrl =
+    process.env.MCP_SERVER_URL ?? "http://localhost:3000/mcp";
+  const mcpApiKey = process.env.MCP_API_KEY;
+
+  if (!apiKey) {
+    throw new Error("ANTHROPIC_API_KEY environment variable is required");
+  }
+
+  // Connect to a remote MCP server with a static API key in the Authorization header.
+  //
+  // For OAuth-based servers, use the authProvider option instead:
+  //
+  //   import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+  //   const mcp = MCPClient.fromUrl(mcpServerUrl, { authProvider: myOAuthProvider });
+  //
+  const mcp = MCPClient.fromUrl(mcpServerUrl, {
+    ...(mcpApiKey ? { headers: { Authorization: `Bearer ${mcpApiKey}` } } : {}),
+  });
+
+  console.log(`Connecting to MCP server at ${mcpServerUrl}...`);
+  await mcp.connect();
+
+  const tools = mcp.getTools();
+  console.log(
+    `Discovered ${tools.length} MCP tools: ${tools
+      .map((t) => t.name)
+      .join(", ")}\n`
+  );
+
+  const agent = new ClaudeAgent({
+    id: "mcp-http-agent",
+    name: "Remote MCP Agent",
+    description: "An agent that uses tools from a remote MCP server.",
+    apiKey,
+    model: "claude-haiku-4-5-20251001",
+    tools,
+  });
+
+  const result = await agent.execute(
+    "What tools do you have available? Briefly describe each one."
+  );
+  console.log("Agent response:\n", result);
+
+  await mcp.disconnect();
+  console.log("\nDisconnected from MCP server.");
+}
+
+main().catch(console.error);

package/mcp-stdio-example.ts

@@ -0,0 +1,63 @@
+import "dotenv/config";
+
+/**
+ * MCP Stdio Example
+ *
+ * Demonstrates connecting to a local MCP server process via stdio and using its
+ * tools with a ClaudeAgent.
+ *
+ * This example uses the @modelcontextprotocol/server-filesystem MCP server, which
+ * exposes filesystem operations (read_file, write_file, list_directory, etc.) as tools.
+ *
+ * Prerequisites:
+ *   npm install @modelcontextprotocol/sdk @anthropic-ai/sdk
+ *
+ * Usage:
+ *   ANTHROPIC_API_KEY=sk-ant-... ts-node examples/mcp-stdio-example.ts
+ */
+
+import { MCPClient } from "../lib/mcp";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error("ANTHROPIC_API_KEY environment variable is required");
+  }
+
+  // Connect to the filesystem MCP server via stdio (spawned as a child process)
+  const mcp = MCPClient.fromStdio({
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+  });
+
+  console.log("Connecting to MCP filesystem server...");
+  await mcp.connect();
+
+  const tools = mcp.getTools();
+  console.log(
+    `Discovered ${tools.length} MCP tools: ${tools
+      .map((t) => t.name)
+      .join(", ")}\n`
+  );
+
+  const agent = new ClaudeAgent({
+    id: "mcp-file-agent",
+    name: "File Agent",
+    description:
+      "An agent that can explore and read files using MCP filesystem tools.",
+    apiKey,
+    model: "claude-haiku-4-5-20251001",
+    tools,
+  });
+
+  const result = await agent.execute(
+    "List the contents of /tmp and describe what you find."
+  );
+  console.log("Agent response:\n", result);
+
+  await mcp.disconnect();
+  console.log("\nDisconnected from MCP server.");
+}
+
+main().catch(console.error);

package/multimodal.ts

@@ -0,0 +1,144 @@
+import "dotenv/config";
+/**
+ * Multimodal example — sending images to Claude and OpenAI
+ *
+ * Run:  ANTHROPIC_API_KEY=... npx ts-node examples/multimodal.ts
+ *
+ * Images are always passed directly to execute() as a MessageContent array.
+ * Use imageUrl() for remote URLs and imageBase64() for local files.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { OpenAiAgent } from "../lib/agents/openai/OpenAiAgent";
+import { imageUrl, imageBase64 } from "../lib/history/History";
+const plantPath = path.join(__dirname, "data", "flower.jpg");
+
+// ---------------------------------------------------------------------------
+// 1. URL image via execute(MessageContent[])
+// ---------------------------------------------------------------------------
+
+async function exampleUrl() {
+  const agent = new ClaudeAgent({
+    id: "vision-url",
+    name: "VisionAgent",
+    description: "An agent that can analyse images",
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+    model: "claude-opus-4-6",
+    maxTokens: 512,
+  });
+
+  const response = await agent.execute([
+    imageUrl(
+      "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"
+    ),
+    { type: "text", text: "What do you see in this image? One sentence." },
+  ]);
+
+  console.log("[URL example]\n", response, "\n");
+}
+// ---------------------------------------------------------------------------
+// 3. Multiple images — compare two images in one turn
+// ---------------------------------------------------------------------------
+
+async function exampleMultiImage() {
+  const agent = new ClaudeAgent({
+    id: "vision-multi",
+    name: "VisionAgent",
+    description: "An agent that can analyse images",
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+    model: "claude-opus-4-6",
+    maxTokens: 512,
+  });
+
+  const response = await agent.execute([
+    { type: "text", text: "Compare these two images in one sentence:" },
+    imageUrl(
+      "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"
+    ),
+    imageUrl(
+      "https://upload.wikimedia.org/wikipedia/commons/thumb/1/14/Gatto_europeo4.jpg/320px-Gatto_europeo4.jpg"
+    ),
+  ]);
+
+  console.log("[Multi-image example]\n", response, "\n");
+}
+
+// ---------------------------------------------------------------------------
+// 4. Plant identification — local JPEG via base64
+//    Drop a photo at examples/data/plant.jpg to run this example.
+// ---------------------------------------------------------------------------
+
+async function examplePlantIdentification() {
+  if (!fs.existsSync(plantPath)) {
+    console.log(
+      "[Plant example] skipped — add a photo at examples/data/plant.jpg\n"
+    );
+    return;
+  }
+
+  const agent = new ClaudeAgent({
+    id: "vision-plant",
+    name: "PlantAgent",
+    description: "An agent that identifies plants from photos",
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+    model: "claude-opus-4-6",
+    maxTokens: 512,
+  });
+
+  const data = fs.readFileSync(plantPath).toString("base64");
+
+  const response = await agent.execute([
+    imageBase64(data, "image/jpeg"),
+    {
+      type: "text",
+      text: "What plant is this? Give the common name, scientific name, and one care tip.",
+    },
+  ]);
+
+  console.log("[Plant example]\n", response, "\n");
+}
+
+// ---------------------------------------------------------------------------
+// 5. OpenAI — same MessageContent[] interface works across providers
+// ---------------------------------------------------------------------------
+
+async function exampleOpenAi() {
+  if (!process.env.OPENAI_API_KEY) {
+    console.log("[OpenAI example] skipped — OPENAI_API_KEY not set\n");
+    return;
+  }
+
+  const agent = new OpenAiAgent({
+    id: "vision-openai",
+    name: "VisionAgent",
+    description: "An agent that can analyse images",
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-4o-mini",
+    maxTokens: 512,
+  });
+
+  const data = fs.readFileSync(plantPath).toString("base64");
+
+  const response = await agent.execute([
+    imageBase64(data, "image/jpeg"),
+    {
+      type: "text",
+      text: "What plant is this? Give the common name, scientific name, and one care tip.",
+    },
+  ]);
+
+  console.log("[OpenAI example]\n", response, "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+(async () => {
+  await exampleUrl();
+  // await exampleMultiImage();
+  await examplePlantIdentification();
+  await exampleOpenAi();
+})().catch(console.error);