matimo-examples 1.0.0

package/slack/slack-factory.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * SLACK TOOLS - FACTORY PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: SDK Factory Pattern
+ * ─────────────────────────────────────────────────────────────────────────
+ * Direct tool execution via MatimoInstance - the simplest way to use tools.
+ *
+ * Use this pattern when:
+ * ✅ Building simple scripts or CLI tools
+ * ✅ Direct API calls without abstraction
+ * ✅ Quick prototyping
+ * ✅ One-off tool execution
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file in project root:
+ *    SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx
+ *
+ * 2. Get a Slack bot token:
+ *    - Go to: https://api.slack.com/apps
+ *    - Create a new app or select existing
+ *    - OAuth & Permissions → Install app to workspace
+ *    - Copy "Bot User OAuth Token"
+ *    - Required scopes: chat:write, channels:read, conversations:history
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export SLACK_BOT_TOKEN=xoxb-xxxx
+ *   npm run slack:factory -- --channel:C123456
+ *
+ * AVAILABLE TOOLS:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. slack-send-message
+ *    Parameters: channel (required), text (required), [blocks]
+ *    Returns: Message timestamp and channel ID
+ *    Example: Send a message to #general channel
+ *
+ * 2. slack-list-channels
+ *    Parameters: [types], [limit], [cursor]
+ *    Returns: List of channels, DMs, and groups
+ *    Types: public_channel, private_channel, mpim, im
+ *
+ * 3. slack_create_channel
+ *    Parameters: name (required), [is_private]
+ *    Returns: Channel object with ID and name
+ *    Example: Create a new public or private channel
+ *
+ * 4. slack_join_channel
+ *    Parameters: channel (required)
+ *    Returns: { ok: true/false }
+ *    Example: Bot joins a public channel
+ *
+ * 5. slack_set_channel_topic
+ *    Parameters: channel (required), topic (required)
+ *    Returns: { ok: true/false, topic }
+ *    Example: Set channel description/topic
+ *
+ * 6. slack_get_channel_history
+ *    Parameters: channel (required), [limit], [oldest], [latest], [cursor]
+ *    Returns: Messages array with pagination
+ *    Example: Get recent messages from channel
+ *
+ * And more...
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { MatimoInstance } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Run factory pattern examples
+ */
+async function runFactoryPatternExamples() {
+  // Parse CLI arguments
+  const args = process.argv.slice(2);
+  let channelId = process.env.SLACK_CHANNEL_ID || '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 Tools - Factory Pattern                      ║');
+  console.info('║     (Direct execution - simplest approach)             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  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-xxxx"');
+    console.info('   Get one from: https://api.slack.com/apps');
+    process.exit(1);
+  }
+
+  console.info(`🤖 Bot Token: ${botToken.slice(0, 10)}...`);
+  console.info(`📍 Target Channel: ${channelId}\n`);
+
+  // Initialize Matimo with auto-discovery to find all @matimo/* packages
+  console.info('🚀 Initializing Matimo...');
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  const allTools = matimo.listTools();
+  console.info(`✅ Loaded ${allTools.length} tools\n`);
+
+  // Get Slack tools
+  const slackTools = allTools.filter((t) => t.name.startsWith('slack'));
+  console.info(`🔧 Found ${slackTools.length} Slack tools\n`);
+
+  // List available channels and use first one if default doesn't exist
+  console.info('📋 Finding an available channel...');
+  const listResult = await matimo.execute('slack-list-channels', {
+    limit: 10,
+    types: 'public_channel,private_channel',
+  });
+  const listData = (listResult as any).data || listResult;
+  let activeChannel = channelId;
+
+  if (listData.ok === true && listData.channels && listData.channels.length > 0) {
+    // Use first available channel if default is not found
+    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})`
+      );
+    } else {
+      console.info(
+        `   Using specified channel: #${listData.channels.find((ch: any) => ch.id === channelId)?.name} (${channelId})`
+      );
+    }
+  } else {
+    console.info(`   ⚠️  Could not list channels, using default: ${channelId}`);
+  }
+  console.info();
+
+  console.info('════════════════════════════════════════════════════════════\n');
+  console.info('Running Examples:');
+  console.info('════════════════════════════════════════════════════════════\n');
+
+  try {
+    // Example 1: Send a message
+    console.info('1️⃣  Sending message to channel...');
+    const sendResult = await matimo.execute('slack-send-message', {
+      channel: activeChannel,
+      text: `🤖 Factory Pattern test message at ${new Date().toISOString()}`,
+    });
+    // Slack API returns {ok: true/false, ...} or wrapped in data
+    const sendData = (sendResult as any).data || sendResult;
+    if (sendData.ok === true) {
+      console.info('   ✅ Message sent successfully');
+      console.info(`      Channel: ${sendData.channel}`);
+      console.info(`      Timestamp: ${sendData.ts}\n`);
+    } else {
+      console.info(`   ❌ Failed: ${sendData.error || 'Unknown error'}`);
+      console.info(`      Response: ${JSON.stringify(sendData)}\n`);
+    }
+
+    // Example 2: List channels
+    console.info('2️⃣  Listing channels...');
+    const listResult = await matimo.execute('slack-list-channels', {
+      limit: 5,
+      types: 'public_channel,private_channel',
+    });
+    const listData = (listResult as any).data || listResult;
+    if (listData.ok === true && listData.channels) {
+      const channels = listData.channels || [];
+      console.info(`   ✅ Found ${channels.length} channels`);
+      channels.slice(0, 3).forEach((ch: any) => {
+        console.info(`      • #${ch.name} (${ch.id})`);
+      });
+      console.info();
+    } else {
+      console.info(`   ❌ Failed: ${listData.error || 'Unknown error'}`);
+      console.info(`      Response: ${JSON.stringify(listData)}\n`);
+    }
+
+    // Example 3: Set channel topic
+    console.info('3️⃣  Setting channel topic...');
+    const topicResult = await matimo.execute('slack_set_channel_topic', {
+      channel: activeChannel,
+      topic: '🎯 Matimo Testing Channel - Factory Pattern Example',
+    });
+    const topicData = (topicResult as any).data || topicResult;
+    if (topicData.ok === true) {
+      console.info('   ✅ Topic set successfully\n');
+    } else {
+      console.info(`   ❌ Failed: ${topicData.error || 'Unknown error'}`);
+      console.info(`      Response: ${JSON.stringify(topicData)}\n`);
+    }
+
+    // Example 4: Get channel history
+    console.info('4️⃣  Retrieving channel history...');
+    const historyResult = await matimo.execute('slack_get_channel_history', {
+      channel: activeChannel,
+      limit: 5,
+    });
+    const historyData = (historyResult as any).data || historyResult;
+    if (historyData.ok === true && historyData.messages) {
+      console.info(`   ✅ Retrieved ${historyData.messages.length} recent messages\n`);
+    } else {
+      console.info(`   ❌ Failed: ${historyData.error || 'Unknown error'}`);
+      console.info(`      Response: ${JSON.stringify(historyData)}\n`);
+    }
+  } catch (error) {
+    console.error('❌ Error:', error);
+    process.exit(1);
+  }
+
+  console.info('════════════════════════════════════════════════════════════');
+  console.info('✨ Factory Pattern Example Complete!');
+  console.info('════════════════════════════════════════════════════════════\n');
+}
+
+runFactoryPatternExamples().catch(console.error);

package/slack/slack-langchain.ts

@@ -0,0 +1,240 @@
+#!/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 } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 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, 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,
+    });
+
+    // 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"]
+}