matimo-examples 0.1.0-alpha.7

package/slack/slack-langchain.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * SLACK TOOLS - LANGCHAIN AI AGENT EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: True AI Agent with OpenAI + LangChain
+ * ─────────────────────────────────────────────────────────────────────────
+ * This is a REAL AI agent that:
+ * 1. Takes natural language user requests
+ * 2. Uses OpenAI LLM (GPT-4o-mini) to decide which Slack tools to use
+ * 3. Generates appropriate parameters based on context
+ * 4. Executes tools autonomously
+ * 5. Processes results and responds naturally
+ *
+ * Use this pattern when:
+ * ✅ Building true autonomous AI agents
+ * ✅ LLM should decide which tools to use
+ * ✅ Complex workflows with LLM reasoning
+ * ✅ Multi-step agentic processes
+ * ✅ User gives high-level instructions (not low-level API calls)
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxx
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * 2. Install dependencies:
+ *    npm install
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export SLACK_BOT_TOKEN=xoxb-xxxx
+ *   export OPENAI_API_KEY=sk-xxxx
+ *   npm run slack:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. List Slack channels
+ * 2. Send messages to channels
+ * 3. Search message history
+ * 4. Retrieve channel information
+ * 5. Respond naturally in conversation style
+ *
+ * Example conversation:
+ *   User: "Send a test message to #general"
+ *   AI Agent: "I'll send a test message to the general channel..."
+ *   [AI Agent calls slack-send-message tool]
+ *   AI Agent: "Done! Message sent successfully."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from 'matimo';
+
+/**
+ * Run AI Agent with Slack tools
+ * The agent receives natural language requests and decides which Slack tools to use
+ */
+async function runSlackAIAgent() {
+  // Parse CLI arguments
+  const args = process.argv.slice(2);
+  let channelId = process.env.TEST_CHANNEL || 'C0000000000';
+
+  for (const arg of args) {
+    if (arg.startsWith('--channel:')) {
+      channelId = arg.split(':')[1];
+    } else if (arg.startsWith('--channel=')) {
+      channelId = arg.split('=')[1];
+    }
+  }
+
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Slack AI Agent - LangChain + OpenAI               ║');
+  console.info('║     True autonomous agent with LLM reasoning          ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const botToken = process.env.SLACK_BOT_TOKEN;
+  if (!botToken) {
+    console.error('❌ Error: SLACK_BOT_TOKEN not set in .env');
+    console.info('   Set it: export SLACK_BOT_TOKEN="xoxb-..."');
+    console.info('   Get one from: https://api.slack.com/apps');
+    process.exit(1);
+  }
+
+  const openaiKey = process.env.OPENAI_API_KEY;
+  if (!openaiKey) {
+    console.error('❌ Error: OPENAI_API_KEY not set in .env');
+    console.info('   Set it: export OPENAI_API_KEY="sk-..."');
+    process.exit(1);
+  }
+
+  console.info(`📍 Target Channel: ${channelId}`);
+  console.info(`🤖 Using OpenAI (GPT-4o-mini) as the AI agent\n`);
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get Slack tools and convert to LangChain format
+    console.info('💬 Loading Slack tools...');
+    const matimoTools = matimo.listTools();
+    const slackTools = matimoTools.filter((t) => t.name.startsWith('slack'));
+    console.info(`✅ Loaded ${slackTools.length} Slack tools\n`);
+
+    // Find an available channel before creating agent
+    console.info('📋 Finding an available channel...');
+    const listChannelsResult = await matimo.execute('slack-list-channels', {
+      types: 'public_channel,private_channel',
+      limit: 10,
+    });
+
+    const listData = (listChannelsResult as any).data || listChannelsResult;
+    let activeChannel = channelId;
+
+    if (listData.ok === true && listData.channels && listData.channels.length > 0) {
+      const defaultChannelExists = listData.channels.some((ch: any) => ch.id === channelId);
+      if (!defaultChannelExists) {
+        activeChannel = listData.channels[0].id;
+        console.info(
+          `   Using first available channel: #${listData.channels[0].name} (${activeChannel})\n`
+        );
+      } else {
+        console.info(
+          `   Using specified channel: #${listData.channels.find((ch: any) => ch.id === channelId)?.name} (${channelId})\n`
+        );
+      }
+    } else {
+      console.info(`   ⚠️  Could not list channels, using default: ${channelId}\n`);
+    }
+
+    // Convert to LangChain tools (select key ones for agent)
+    const keySlackTools = slackTools.filter((t) =>
+      [
+        'slack-send-message',
+        'slack-list-channels',
+        'slack_get_channel_history',
+        'slack_search_messages',
+        'slack_get_user_info',
+      ].includes(t.name)
+    );
+
+    // ✅ Convert Matimo tools to LangChain format using the new integration
+    const langchainTools = await convertToolsToLangChain(
+      keySlackTools as ToolDefinition[],
+      matimo,
+      {
+        SLACK_BOT_TOKEN: botToken,
+      }
+    );
+
+    // Initialize OpenAI LLM
+    console.info('🤖 Initializing OpenAI (GPT-4o-mini) LLM...');
+    const model = new ChatOpenAI({
+      modelName: 'gpt-4o-mini',
+      temperature: 0.7,
+    });
+
+    // Create agent
+    console.info('🔧 Creating agent...\n');
+    const agent = await createAgent({
+      model,
+      tools: langchainTools as any[], // Type casting for LangChain tools
+    });
+
+    // Define agent tasks (natural language requests)
+    const userRequests = [
+      {
+        title: 'Example 1: List channels',
+        request: 'What Slack channels are available in this workspace?',
+      },
+      {
+        title: 'Example 2: Send a message',
+        request: `Send a test message to channel ${activeChannel} saying "Hello from AI Agent! This message was sent autonomously."`,
+      },
+      {
+        title: 'Example 3: Get channel history',
+        request: `What are the recent messages in channel ${activeChannel}?`,
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks');
+    console.info('═'.repeat(60));
+
+    // Run each task through the agent
+    for (const task of userRequests) {
+      console.info(`\n${task.title}`);
+      console.info('─'.repeat(60));
+      console.info(`👤 User: "${task.request}"\n`);
+
+      try {
+        const response = await agent.invoke({
+          messages: [
+            {
+              role: 'user',
+              content: task.request,
+            },
+          ],
+        });
+
+        // Get the last message from the agent
+        const lastMessage = response.messages[response.messages.length - 1];
+        if (lastMessage) {
+          if (typeof lastMessage.content === 'string') {
+            console.info(`🤖 Agent: ${lastMessage.content}\n`);
+          } else {
+            console.info(`🤖 Agent:`, lastMessage.content, '\n');
+          }
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.info(`⚠️  Agent error: ${errorMsg}\n`);
+      }
+    }
+
+    console.info('═'.repeat(60));
+    console.info('✨ AI Agent Examples Complete!\n');
+    console.info('Key Features:');
+    console.info('  ✅ Real LLM (OpenAI) decides which tools to use');
+    console.info('  ✅ Natural language requests, not API calls');
+    console.info('  ✅ LLM generates tool parameters based on context');
+    console.info('  ✅ Agentic reasoning and decision-making\n');
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('Stack:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the AI agent
+runSlackAIAgent().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist"
+  },
+  "include": ["agents/**/*.ts", "gmail/**/*.ts", "slack/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/web/web-decorator.ts

@@ -0,0 +1,52 @@
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+/**
+ * Example: Web tool using @tool decorator pattern
+ * Demonstrates class-based HTTP requests with automatic decoration
+ */
+class WebClient {
+  @tool('web')
+  async fetchUrl(url: string, timeout?: number): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+
+  @tool('web')
+  async postData(url: string, body: string, headers?: Record<string, string>): Promise<unknown> {
+    // Decorator automatically intercepts and executes via Matimo
+    return undefined;
+  }
+}
+
+async function decoratorExample() {
+  // Set up decorator support with autoDiscover
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+  setGlobalMatimoInstance(matimo);
+
+  console.info('=== Web Tool - Decorator Pattern ===\n');
+
+  const client = new WebClient();
+
+  try {
+    // Example 1: Fetch through decorated method
+    console.info('1. Fetching content via decorator\n');
+    const result1 = await client.fetchUrl('https://api.github.com/repos/tallclub/matimo');
+    console.info('Status:', (result1 as any).statusCode);
+    console.info('Size:', (result1 as any).contentLength);
+    console.info('---\n');
+
+    // Example 2: POST through decorated method
+    console.info('2. Posting data via decorator\n');
+    const result2 = await client.postData(
+      'https://httpbin.org/post',
+      JSON.stringify({ test: 'data' }),
+      { 'Content-Type': 'application/json' }
+    );
+    console.info('Status:', (result2 as any).statusCode);
+    console.info('---\n');
+  } catch (error: any) {
+    console.error('Error:', error.message);
+  }
+}
+
+decoratorExample();

package/web/web-factory.ts

@@ -0,0 +1,70 @@
+import { MatimoInstance } from '@matimo/core';
+
+/**
+ * Example: Web tool using factory pattern
+ * Demonstrates making HTTP requests and fetching web content
+ */
+async function webExample() {
+  // Initialize Matimo with autoDiscover to find all tools (core + providers)
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  console.info('=== Web Tool - Factory Pattern ===\n');
+
+  try {
+    // Example 1: Fetch GitHub API
+    console.info('1. Fetching GitHub API (public endpoint)\n');
+    const github = await matimo.execute('web', {
+      url: 'https://api.github.com/repos/tallclub/matimo',
+    });
+
+    console.info('Status Code:', (github as any).statusCode);
+    console.info('Content size:', (github as any).size);
+    // Content is already parsed as an object
+    const githubData =
+      typeof (github as any).content === 'string'
+        ? JSON.parse((github as any).content)
+        : (github as any).content;
+    console.info('Repository:', githubData.full_name);
+    console.info('Description:', githubData.description);
+    console.info('---\n');
+
+    // Example 2: Fetch HTML content
+    console.info('2. Fetching HTML content\n');
+    const html = await matimo.execute('web', {
+      url: 'https://www.example.com',
+      timeout: 15000,
+    });
+
+    console.info('Status Code:', (html as any).statusCode);
+    console.info('Content type:', (html as any).contentType);
+    console.info('Content size:', (html as any).size);
+    const htmlContent =
+      typeof (html as any).content === 'string'
+        ? (html as any).content
+        : JSON.stringify((html as any).content);
+    console.info('Content preview:');
+    console.info(htmlContent.substring(0, 200));
+    console.info('---\n');
+
+    // Example 3: POST request
+    console.info('3. POST request (echo service)\n');
+    const post = await matimo.execute('web', {
+      url: 'https://httpbin.org/post',
+      method: 'POST',
+      body: JSON.stringify({ message: 'Hello from Matimo' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    console.info('Status Code:', (post as any).statusCode);
+    const postContent =
+      typeof (post as any).content === 'string'
+        ? (post as any).content
+        : JSON.stringify((post as any).content);
+    console.info('Response:', postContent.substring(0, 200));
+    console.info('---\n');
+  } catch (error: any) {
+    console.error('Error fetching web content:', error.message);
+  }
+}
+
+webExample();

package/web/web-langchain.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * WEB TOOL - LANGCHAIN AI AGENT EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: True AI Agent with OpenAI + LangChain
+ * ─────────────────────────────────────────────────────────────────────────
+ * This is a REAL AI agent that:
+ * 1. Takes natural language user requests
+ * 2. Uses OpenAI LLM (GPT-4o-mini) to decide when to make HTTP requests
+ * 3. Generates appropriate URLs and methods based on context
+ * 4. Executes tools autonomously
+ * 5. Processes results and responds naturally
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * 2. Install dependencies:
+ *    npm install
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export OPENAI_API_KEY=sk-xxxx
+ *   npm run web:langchain
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain, type ToolDefinition } from '@matimo/core';
+
+/**
+ * Run AI Agent with Web tool
+ * The agent receives natural language requests and decides when to make HTTP requests
+ */
+async function runWebAIAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║      Web Tool AI Agent - LangChain + OpenAI            ║');
+  console.info('║      True autonomous agent with LLM reasoning          ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const openaiKey = process.env.OPENAI_API_KEY;
+  if (!openaiKey) {
+    console.error('❌ Error: OPENAI_API_KEY not set in .env');
+    console.info('   Set it: export OPENAI_API_KEY="sk-..."');
+    process.exit(1);
+  }
+
+  console.info('🤖 Using OpenAI (GPT-4o-mini) as the AI agent\n');
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get web tool
+    console.info('💬 Loading web tool...');
+    const matimoTools = matimo.listTools();
+    const webTool = matimoTools.filter((t) => t.name === 'web');
+    console.info(`✅ Loaded ${webTool.length} web tool(s)\n`);
+
+    if (webTool.length === 0) {
+      console.error('❌ Web tool not found');
+      process.exit(1);
+    }
+
+    // Convert to LangChain tools using the built-in converter
+    const webTools = webTool as ToolDefinition[];
+    const langchainTools = await convertToolsToLangChain(webTools, matimo);
+
+    // Initialize OpenAI LLM
+    console.info('🤖 Initializing OpenAI (GPT-4o-mini) LLM...');
+    const model = new ChatOpenAI({
+      modelName: 'gpt-4o-mini',
+      temperature: 0.7,
+    });
+
+    // Create agent
+    console.info('🔧 Creating agent...\n');
+    const agent = await createAgent({
+      model,
+      tools: langchainTools as any,
+    });
+
+    // Define agent tasks (natural language requests)
+    const userRequests = [
+      {
+        title: 'Example 1: Fetch GitHub repository info',
+        request: 'Get information about the tallclub/matimo repository from GitHub API',
+      },
+      {
+        title: 'Example 2: Check API status',
+        request: 'Make a request to the GitHub API and tell me what HTTP status code we get',
+      },
+      {
+        title: 'Example 3: Fetch public data',
+        request: 'Get JSON data from a public REST API endpoint and summarize the response',
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks');
+    console.info('═'.repeat(60) + '\n');
+
+    // Run each task through the agent
+    for (const task of userRequests) {
+      console.info(`${task.title}`);
+      console.info('─'.repeat(60));
+      console.info(`👤 User: "${task.request}"\n`);
+
+      try {
+        const response = await agent.invoke({
+          messages: [
+            {
+              role: 'user',
+              content: task.request,
+            },
+          ],
+        });
+
+        // Get the last message from the agent
+        const lastMessage = response.messages[response.messages.length - 1];
+        if (lastMessage) {
+          const content =
+            typeof lastMessage.content === 'string'
+              ? lastMessage.content
+              : String(lastMessage.content);
+
+          if (content && content.trim()) {
+            console.info(`🤖 Agent: ${content}\n`);
+          } else {
+            console.info('🤖 Agent: (Request completed successfully)\n');
+          }
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.info(`⚠️  Agent error: ${errorMsg}\n`);
+      }
+    }
+
+    console.info('═'.repeat(60));
+    console.info('\n✨ AI Agent Examples Complete!\n');
+    console.info('Key Features:');
+    console.info('  ✅ Real LLM (OpenAI) decides which tools to use');
+    console.info('  ✅ Natural language requests, not API calls');
+    console.info('  ✅ LLM generates URLs and HTTP methods based on context');
+    console.info('  ✅ Agentic reasoning and decision-making\n');
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('Stack:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the AI agent
+runWebAIAgent().catch(console.error);