modular-agent-examples 0.0.1

package/ollama.ts

@@ -0,0 +1,148 @@
+/**
+ * Ollama Agent Example
+ *
+ * Demonstrates using OllamaAgent with locally-hosted Ollama models.
+ * Requires: ollama running on localhost:11434 and the `ollama` npm package.
+ *
+ * Install ollama npm package:
+ *   npm install ollama
+ *
+ * Pull a model with tool support (in terminal):
+ *   ollama pull llama3.2
+ *   ollama pull qwen2.5   # better tool-use support
+ *
+ * Run this example:
+ *   npx tsx examples/ollama.ts
+ */
+
+import { OllamaAgent } from "../lib/agents/ollama/OllamaAgent";
+import { Tool } from "../lib/tools/Tool";
+
+// =============================================================================
+// Tools
+// =============================================================================
+
+interface WeatherInput {
+  location: string;
+}
+
+const getWeatherTool = new Tool({
+  name: "get_weather",
+  description: "Get the current weather for a location",
+  inputSchema: {
+    type: "object",
+    properties: {
+      location: {
+        type: "string",
+        description: "City name or location (e.g. 'Amsterdam', 'New York')",
+      },
+    },
+    required: ["location"],
+  },
+  execute: async (input: WeatherInput) => {
+    // Simulated weather data — replace with a real API call
+    const conditions = ["sunny", "cloudy", "rainy", "windy", "snowy"];
+    const condition = conditions[Math.floor(Math.random() * conditions.length)];
+    const temp = Math.round(5 + Math.random() * 25);
+    return {
+      location: input.location,
+      temperature: temp,
+      unit: "celsius",
+      condition,
+      humidity: Math.round(40 + Math.random() * 40),
+    };
+  },
+});
+
+interface CalculatorInput {
+  expression: string;
+}
+
+const calculatorTool = new Tool({
+  name: "calculate",
+  description: "Evaluate a mathematical expression",
+  inputSchema: {
+    type: "object",
+    properties: {
+      expression: {
+        type: "string",
+        description:
+          "Math expression to evaluate, e.g. '2 + 2' or '10 * 5 / 2'",
+      },
+    },
+    required: ["expression"],
+  },
+  execute: async (input: CalculatorInput) => {
+    // Safe evaluation of simple math expressions
+    const sanitized = input.expression.replace(/[^0-9+\-*/().\s]/g, "");
+    try {
+      const result = Function(`"use strict"; return (${sanitized})`)();
+      return { expression: input.expression, result };
+    } catch {
+      return { expression: input.expression, error: "Invalid expression" };
+    }
+  },
+});
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  console.log("=== Ollama Agent Example ===\n");
+
+  // Basic chat (no tools)
+  console.log("--- Basic Chat ---");
+  const chatAgent = new OllamaAgent({
+    id: "ollama-chat",
+    name: "Ollama Chat",
+    description: "A helpful assistant",
+    model: "gemma4:e4b",
+    think: false,
+    apiKey: "", // Ollama doesn't require an API key
+  });
+
+  const chatResponse = await chatAgent.execute(
+    "What is the capital of France? Answer in one sentence."
+  );
+  console.log("Response:", chatResponse);
+  console.log("Tokens:", chatAgent.lastTokenUsage);
+
+  console.log("\n--- Tool-Use Agent ---");
+
+  // Agent with tools — use a model with strong tool support
+  const toolAgent = new OllamaAgent({
+    id: "ollama-tool-agent",
+    name: "Ollama Tool Agent",
+    think: false,
+
+    description: "An agent that can check weather and do math",
+    model: "gemma4:e4b", // qwen2.5 has good tool-call support
+    tools: [getWeatherTool, calculatorTool],
+    apiKey: "",
+  });
+
+  const toolResponse = await toolAgent.execute(
+    "What's the weather in Amsterdam? Also, what is 42 * 7?"
+  );
+  console.log("Response:", toolResponse);
+  console.log("Tokens:", toolAgent.lastTokenUsage);
+
+  // Custom host example
+  console.log("\n--- Custom Host ---");
+  const remoteAgent = new OllamaAgent({
+    id: "ollama-remote",
+    name: "Remote Ollama",
+    thinking: false,
+
+    description: "Agent connecting to a non-default Ollama server",
+    model: "gemma4:e4b",
+    host: "http://localhost:11434", // default, but can point to any Ollama instance
+    apiKey: "",
+  });
+
+  const remoteResponse = await remoteAgent.execute("Say hello in Dutch.");
+  console.log("Response:", remoteResponse);
+}
+
+main().catch(console.error);

package/openai-compatible.ts

@@ -0,0 +1,141 @@
+/**
+ * OpenAI-Compatible Agent Example
+ *
+ * Demonstrates how to build a custom agent for any server that exposes an
+ * OpenAI-compatible `/v1/chat/completions` API — vLLM, LM Studio, Together AI,
+ * Groq, or your own fine-tuned model server.
+ *
+ * This example shows:
+ *   1. Using LlamaCppAgent (the built-in OpenAI-compatible agent for llama.cpp)
+ *   2. Extending OpenAICompatibleAgent to create your own custom agent
+ *
+ * Prerequisites for the llama.cpp demo:
+ *   npm install openai
+ *   llama-server -m ./models/your-model.gguf   # defaults to http://localhost:8080
+ *
+ * Run this example:
+ *   npx tsx examples/openai-compatible.ts
+ */
+
+import { LlamaCppAgent } from "../lib/agents/llamacpp/LlamaCppAgent";
+import {
+  OpenAICompatibleAgent,
+  OpenAICompatibleConfig,
+} from "../lib/agents/openai-compatible/OpenAICompatibleAgent";
+import { Tool } from "../lib/tools/Tool";
+import { History } from "../lib/history/History";
+
+// =============================================================================
+// Part 1: LlamaCppAgent — built-in, zero boilerplate
+// =============================================================================
+
+async function llamaCppDemo() {
+  console.log("=== LlamaCppAgent (built-in) ===\n");
+
+  const agent = new LlamaCppAgent({
+    id: "llama-1",
+    name: "Local Assistant",
+    description: "You are a helpful assistant running locally via llama.cpp.",
+    baseURL: "http://localhost:8080/v1", // default — can omit
+    model: "default",
+  });
+
+  const response = await agent.execute(
+    "What is the capital of France? Answer in one sentence."
+  );
+  console.log("Response:", response);
+  console.log("Tokens:", agent.lastTokenUsage);
+
+  // Discover which models the server has loaded
+  const models = await agent.listModels();
+  console.log(
+    "Available models:",
+    models.map((m) => m.id)
+  );
+}
+
+// =============================================================================
+// Part 2: Custom OpenAICompatibleAgent subclass
+//
+// Use this pattern to add your own config, vendor-specific request params, or
+// a display name for a server that isn't llama.cpp (e.g. vLLM, LM Studio).
+// =============================================================================
+
+type VLLMConfig = Omit<OpenAICompatibleConfig, "baseURL" | "vendor"> & {
+  /** URL of the vLLM server (default: http://localhost:8000/v1) */
+  baseURL?: string;
+};
+
+class VLLMAgent extends OpenAICompatibleAgent {
+  constructor(config: VLLMConfig, history?: History) {
+    super(
+      {
+        ...config,
+        vendor: "llamacpp", // reuse the "llamacpp" vendor slot for OpenAI-compatible servers
+        baseURL: config.baseURL ?? "http://localhost:8000/v1",
+        model: config.model ?? "default",
+      },
+      history
+    );
+  }
+
+  protected getVendorName(): string {
+    return "vLLM";
+  }
+}
+
+async function vllmDemo() {
+  console.log("\n=== VLLMAgent (custom subclass) ===\n");
+
+  const weatherTool = new Tool({
+    name: "get_weather",
+    description: "Get the current weather for a location",
+    inputSchema: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "City name (e.g. 'Amsterdam')",
+        },
+      },
+      required: ["location"],
+    },
+    execute: async (input: { location: string }) => ({
+      location: input.location,
+      temperature: Math.round(10 + Math.random() * 20),
+      unit: "celsius",
+      condition: ["sunny", "cloudy", "rainy"][Math.floor(Math.random() * 3)],
+    }),
+  });
+
+  const agent = new VLLMAgent({
+    id: "vllm-1",
+    name: "vLLM Assistant",
+    description: "You are a helpful assistant. Use tools when helpful.",
+    baseURL: "http://localhost:8000/v1",
+    tools: [weatherTool],
+  });
+
+  const response = await agent.execute(
+    "What's the weather like in Amsterdam today?"
+  );
+  console.log("Response:", response);
+  console.log("Tokens:", agent.lastTokenUsage);
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  // Run whichever demo matches your running server.
+  // Comment out the one you don't need.
+  await llamaCppDemo().catch((err) =>
+    console.warn("llama.cpp demo skipped:", err.message)
+  );
+  await vllmDemo().catch((err) =>
+    console.warn("vLLM demo skipped:", err.message)
+  );
+}
+
+main().catch(console.error);

package/opensearch-vector-store.ts

@@ -0,0 +1,342 @@
+/**
+ * OpenSearch Vector Store example
+ *
+ * Demonstrates how to use OpenSearchVectorStore for RAG (Retrieval-Augmented Generation)
+ * with a Claude agent.
+ *
+ * Prerequisites:
+ *   - A running OpenSearch instance (e.g. via Docker):
+ *
+ * docker run -p 9200:9200 -p 9600:9600 \
+ *  -e "discovery.type=single-node" \
+ *  -e 'OPENSEARCH_INITIAL_ADMIN_PASSWORD=MySearch@7742' \
+ *  opensearchproject/opensearch:latest
+ *
+ *
+ *   - Required env vars:
+ *       OPENAI_API_KEY       — for OpenAI embeddings
+ *       ANTHROPIC_API_KEY    — for the Claude agent
+ *       OPENSEARCH_NODE      — OpenSearch endpoint (default: https://localhost:9200)
+ *       OPENSEARCH_USERNAME  — username (default: admin)
+ *       OPENSEARCH_PASSWORD  — password (default: admin)
+ *
+ * Run with:
+ *   npm run example examples/opensearch-vector-store.ts
+ */
+
+import "dotenv/config";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { OpenSearchVectorStore } from "../lib/vectorstore/OpenSearchVectorStore";
+import { OpenAIEmbeddings } from "../lib/embeddings/OpenAIEmbeddings";
+
+const OPENSEARCH_NODE = process.env.OPENSEARCH_NODE ?? "https://localhost:9200";
+const OPENSEARCH_USERNAME = process.env.OPENSEARCH_USERNAME ?? "admin";
+const OPENSEARCH_PASSWORD = process.env.OPENSEARCH_PASSWORD ?? "admin";
+const INDEX_NAME = "agention_example";
+
+async function main() {
+  console.log("OpenSearch Vector Store Example\n");
+  console.log("================================\n");
+
+  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);
+  }
+
+  // 1. Embeddings
+  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`
+  );
+
+  // 2. Vector store
+  console.log(`2. Connecting to OpenSearch at ${OPENSEARCH_NODE}...`);
+  const store = await OpenSearchVectorStore.create({
+    name: "knowledge_base",
+    node: OPENSEARCH_NODE,
+    auth: { username: OPENSEARCH_USERNAME, password: OPENSEARCH_PASSWORD },
+    ssl: { rejectUnauthorized: false }, // allow self-signed certs in dev
+    indexName: INDEX_NAME,
+    embeddings,
+    spaceType: "cosinesimil",
+    metadataFields: [
+      { name: "category", type: "string" },
+      { name: "source", type: "string" },
+    ],
+  });
+  console.log(
+    `   Index: "${store.getIndexName()}", Dimensions: ${store.getDimensions()}\n`
+  );
+
+  // 3. Ingest some documents
+  console.log("3. Ingesting sample documents...");
+  const documents = [
+    {
+      id: "doc-1",
+      content:
+        "OpenSearch is a distributed, open-source search and analytics engine. " +
+        "It is a community-driven fork of Elasticsearch maintained by Amazon.",
+      metadata: { source: "docs", category: "overview" },
+    },
+    {
+      id: "doc-2",
+      content:
+        "The OpenSearch k-NN plugin enables approximate k-nearest-neighbour (ANN) search " +
+        "using the HNSW algorithm. It supports cosine similarity, L2, and inner product space types.",
+      metadata: { source: "docs", category: "knn" },
+    },
+    {
+      id: "doc-3",
+      content:
+        "Agention-lib provides an OpenSearchVectorStore that wraps the k-NN plugin " +
+        "and exposes a unified VectorStore interface for use in RAG pipelines.",
+      metadata: { source: "agention", category: "vectorstore" },
+    },
+    {
+      id: "doc-4",
+      content:
+        "Retrieval-Augmented Generation (RAG) is a pattern where an LLM is given relevant " +
+        "context retrieved from a vector store before generating a response.",
+      metadata: { source: "docs", category: "rag" },
+    },
+    {
+      id: "doc-5",
+      content:
+        "HNSW (Hierarchical Navigable Small World) is a graph-based ANN algorithm. " +
+        "The M parameter controls the number of bidirectional links per node, " +
+        "and ef_construction controls graph quality at index build time.",
+      metadata: { source: "docs", category: "knn" },
+    },
+  ];
+
+  const ids = await store.addDocuments(documents);
+  console.log(`   Indexed ${ids.length} documents\n`);
+
+  // 4. Index overview & data snapshot
+  console.log("4. Index overview & data snapshot");
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const rawClient = store.getClient() as any;
+
+  // Fetch the full index definition (settings + mappings)
+  const indexInfo = await rawClient.indices.get({ index: store.getIndexName() });
+  const indexDef = indexInfo.body[store.getIndexName()];
+  const knnSettings = indexDef?.settings?.index?.knn;
+  const embeddingMapping = indexDef?.mappings?.properties?.embedding;
+  const method = embeddingMapping?.method ?? {};
+
+  console.log(`   Engine:     ${method.engine ?? "—"}`);
+  console.log(`   Space type: ${method.space_type ?? "—"}`);
+  console.log(`   Dimensions: ${embeddingMapping?.dimension ?? "—"}`);
+  console.log(`   k-NN index: ${knnSettings ?? "—"}`);
+
+  // List mapped metadata fields and their distinct values via terms aggs
+  const metaProps = indexDef?.mappings?.properties?.metadata?.properties ?? {};
+  const metaFieldNames = Object.keys(metaProps);
+
+  if (metaFieldNames.length === 0) {
+    console.log("   Metadata fields: (none)");
+  } else {
+    const aggs: Record<string, unknown> = {};
+    for (const field of metaFieldNames) {
+      const fieldType = (metaProps[field] as { type?: string }).type;
+      // text fields from dynamic mapping need the .keyword sub-field for aggregations
+      const aggField = fieldType === "keyword" ? `metadata.${field}` : `metadata.${field}.keyword`;
+      aggs[field] = { terms: { field: aggField, size: 20 } };
+    }
+    const aggsResult = await rawClient.search({
+      index: store.getIndexName(),
+      body: { size: 0, aggs },
+    });
+    const aggsBody = aggsResult.body.aggregations ?? {};
+
+    console.log("   Metadata fields:");
+    for (const [field, v] of Object.entries(metaProps)) {
+      const fieldType = (v as { type?: string }).type ?? "?";
+      const buckets: Array<{ key: string; doc_count: number }> =
+        aggsBody[field]?.buckets ?? [];
+      const values = buckets.length > 0
+        ? buckets.map((b) => `${b.key} (${b.doc_count})`).join(", ")
+        : "(no values)";
+      console.log(`     ${field} [${fieldType}]: ${values}`);
+    }
+  }
+
+  // Data snapshot via match_all (no embedding needed)
+  const snapshot = await rawClient.search({
+    index: store.getIndexName(),
+    body: { size: 10, query: { match_all: {} }, _source: ["id", "content", "namespace", "metadata"] },
+  });
+  const hits = snapshot.body.hits?.hits ?? [];
+  console.log(`\n   Documents in index (${hits.length}):`);
+  for (const hit of hits) {
+    const src = hit._source;
+    const ns = src.namespace ? ` [ns:${src.namespace}]` : "";
+    const metaPairs = Object.entries(src.metadata ?? {})
+      .map(([k, val]) => `${k}=${val}`)
+      .join("  ");
+    console.log(`   ${src.id}${ns}  ${metaPairs}`);
+    console.log(`     "${src.content.substring(0, 80)}..."`);
+  }
+  console.log();
+
+  // 5. Direct search
+  console.log('5. Direct search: "how does vector search work in OpenSearch?"');
+  const searchResults = await store.search(
+    "how does vector search work in OpenSearch?",
+    { limit: 3 }
+  );
+  console.log("   Top results:");
+  for (const result of searchResults) {
+    console.log(
+      `   [${result.score.toFixed(3)}] (${
+        result.document.metadata?.category
+      }) ` +
+        result.document.content.substring(0, 80) +
+        "..."
+    );
+  }
+  console.log();
+
+  // 6. Metadata filter tests
+  console.log("6. Metadata filter tests");
+  console.log("   (All results show [score] (category|source) snippet)\n");
+
+  function printResults(results: Awaited<ReturnType<typeof store.search>>) {
+    if (results.length === 0) {
+      console.log("   (no results)");
+      return;
+    }
+    for (const r of results) {
+      const m = r.document.metadata ?? {};
+      console.log(
+        `   [${r.score.toFixed(3)}] (${m.category}|${m.source}) ${r.document.content.substring(0, 70)}...`
+      );
+    }
+  }
+
+  function assertCategories(
+    results: Awaited<ReturnType<typeof store.search>>,
+    expected: string,
+    label: string
+  ) {
+    const wrong = results.filter((r) => r.document.metadata?.category !== expected);
+    const status = wrong.length === 0 ? "PASS" : `FAIL (${wrong.length} wrong)`;
+    console.log(`   ${status}: ${label}`);
+  }
+
+  // 6a. Filter by category = "knn"
+  console.log('   6a. category = "knn" (expect only knn docs)');
+  const knnResults = await store.search("nearest neighbour algorithm", {
+    limit: 5,
+    filter: { category: "knn" },
+  });
+  printResults(knnResults);
+  assertCategories(knnResults, "knn", "all results have category=knn");
+  console.log();
+
+  // 6b. Filter by source = "agention"
+  console.log('   6b. source = "agention" (expect only agention docs)');
+  const agentionResults = await store.search("vector store RAG", {
+    limit: 5,
+    filter: { source: "agention" },
+  });
+  printResults(agentionResults);
+  const wrongSource = agentionResults.filter(
+    (r) => r.document.metadata?.source !== "agention"
+  );
+  console.log(
+    `   ${wrongSource.length === 0 ? "PASS" : "FAIL"}: all results have source=agention`
+  );
+  console.log();
+
+  // 6c. Filter by category = "overview" (only 1 doc exists)
+  console.log('   6c. category = "overview" (expect exactly 1 doc)');
+  const overviewResults = await store.search("OpenSearch", {
+    limit: 5,
+    filter: { category: "overview" },
+  });
+  printResults(overviewResults);
+  console.log(
+    `   ${overviewResults.length === 1 ? "PASS" : "FAIL"}: got ${overviewResults.length} result(s), expected 1`
+  );
+  console.log();
+
+  // 6d. Filter by non-existent category (expect 0 results)
+  console.log('   6d. category = "nonexistent" (expect 0 results)');
+  const emptyResults = await store.search("anything", {
+    limit: 5,
+    filter: { category: "nonexistent" },
+  });
+  printResults(emptyResults);
+  console.log(
+    `   ${emptyResults.length === 0 ? "PASS" : "FAIL"}: got ${emptyResults.length} result(s), expected 0`
+  );
+  console.log();
+
+  // 7. Namespace demo
+  console.log(
+    "7. Namespace demo — adding a document to namespace 'internal'..."
+  );
+  await store.addDocuments(
+    [
+      {
+        id: "internal-1",
+        content: "This is an internal document not shown in public searches.",
+        metadata: { source: "internal" },
+      },
+    ],
+    { namespace: "internal" }
+  );
+
+  const publicResults = await store.search("internal document", {
+    limit: 3,
+    namespace: "public", // won't match the 'internal' doc
+  });
+  console.log(
+    `   Search in namespace 'public' returned ${publicResults.length} results (expected 0 for the internal doc)\n`
+  );
+
+  // 8. Agent with retrieval tool
+  console.log("8. Creating Claude agent with OpenSearch retrieval tool...");
+  const searchTool = store.toRetrievalTool(
+    "Search the knowledge base for information about OpenSearch, vector search, RAG, and Agention.",
+    { defaultLimit: 3 }
+  );
+
+  const agent = new ClaudeAgent({
+    name: "RAG Assistant",
+    id: "rag_assistant",
+    model: "claude-haiku-4-5",
+    description:
+      "You are a helpful assistant. Always use the search tool to retrieve relevant context " +
+      "before answering questions. Base your answers on the search results.",
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    tools: [searchTool],
+  });
+  console.log("   Agent created\n");
+
+  // 9. Ask the agent a question
+  console.log(
+    '9. Asking the agent: "What is the HNSW algorithm and how is it configured?"\n'
+  );
+  const answer = await agent.execute(
+    "What is the HNSW algorithm and how is it configured?"
+  );
+  console.log(`Answer:\n${answer}\n`);
+
+  // 10. Clean up (delete all docs from the index)
+  console.log("10. Clearing the index...");
+  await store.clear();
+  console.log("   Done.\n");
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "modular-agent-examples",
+  "author": "Laurent Zuijdwijk",
+  "license": "ISC",
+  "version": "0.0.1",
+  "dependencies": {
+    "@lancedb/lancedb": "^0.18.1",
+    "@opensearch-project/opensearch": "^3.5.1",
+    "@types/ws": "^8.18.0",
+    "colors": "^1.4.0",
+    "dotenv": "^16.6.1",
+    "install": "^0.13.0",
+    "npm": "^11.2.0",
+    "ora": "^8.2.0",
+    "ora-classic": "^5.4.2",
+    "ws": "^8.18.1"
+  },
+  "overrides": {
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "tokenx": "^1.3.0"
+  }
+}