matimo-examples 0.1.0-alpha.11

package/postgres/postgres-langchain.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * POSTGRES 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 Postgres tools to use
+ * 3. Generates appropriate SQL based on context
+ * 4. Executes queries autonomously
+ * 5. Processes results and responds naturally
+ *
+ * CRITICAL: Database credentials are NEVER exposed to the LLM
+ * - LLM only sees tool descriptions and results
+ * - Matimo handles all credential loading from environment variables
+ * - Tool execution is secure and isolated
+ *
+ * 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 SQL queries)
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Make sure Postgres is running (see POSTGRES_EXAMPLE_SETUP.md)
+ * 2. Create .env file with database credentials:
+ *    MATIMO_POSTGRES_HOST=localhost
+ *    MATIMO_POSTGRES_PORT=5432
+ *    MATIMO_POSTGRES_USER=matimo
+ *    MATIMO_POSTGRES_PASSWORD=development
+ *    MATIMO_POSTGRES_DB=matimo
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   pnpm postgres:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. Explore database tables and schema
+ * 2. Execute SELECT queries to analyze data
+ * 3. Respond naturally in conversation style
+ * 4. Multi-step reasoning without exposing credentials
+ *
+ * Example:
+ *   User: "What tables exist in matimo?"
+ *   AI Agent: "Let me query the database to see what tables are available..."
+ *   [Agent calls postgres-execute-sql tool with SELECT query]
+ *   AI Agent: "The matimo database contains these tables: ..."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from 'matimo';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+
+/**
+ * Run AI Agent with Postgres tools
+ * The agent receives natural language requests and decides which Postgres tools to use
+ */
+async function runPostgresAIAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     Postgres AI Agent - LangChain + OpenAI             ║');
+  console.info('║     True autonomous agent with LLM reasoning           ║');
+  console.info('║     Database credentials: NEVER exposed to LLM         ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const pgConnected =
+    process.env.MATIMO_POSTGRES_HOST &&
+    process.env.MATIMO_POSTGRES_USER &&
+    process.env.MATIMO_POSTGRES_PASSWORD &&
+    process.env.MATIMO_POSTGRES_DB;
+
+  if (!pgConnected) {
+    console.error('❌ Error: Postgres connection not configured in .env');
+    console.info('   Required environment variables:');
+    console.info('     MATIMO_POSTGRES_HOST');
+    console.info('     MATIMO_POSTGRES_USER');
+    console.info('     MATIMO_POSTGRES_PASSWORD');
+    console.info('     MATIMO_POSTGRES_DB');
+    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(
+    `📍 Postgres: ${process.env.MATIMO_POSTGRES_DB}@${process.env.MATIMO_POSTGRES_HOST}`
+  );
+  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 Postgres tools and convert to LangChain format
+    console.info('💬 Loading Postgres tools...');
+    const matimoTools = matimo.listTools();
+    const postgresTools = matimoTools.filter((t) => t.name.startsWith('postgres'));
+    console.info(`✅ Loaded ${postgresTools.length} Postgres tool(s)\n`);
+
+    // ✅ Convert Matimo tools to LangChain format using the built-in integration
+    const langchainTools = await convertToolsToLangChain(
+      postgresTools as ToolDefinition[],
+      matimo,
+      {
+        // Pass database credentials so LLM tool calls can execute securely
+        // The LLM will NEVER see these values - only Matimo tool execution will use them
+      }
+    );
+
+    // 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 (sequential - each task uses results from previous)
+    const userRequests = [
+      {
+        title: 'Step 1: Discover tables',
+        request:
+          'Get a list of all tables in the matimo database. Query the information_schema to show me all tables and their row counts.',
+      },
+      {
+        title: 'Step 2: Analyze data volume',
+        request:
+          'Now that you know which tables exist, tell me the total number of records across all tables and which tables have the most data.',
+      },
+      {
+        title: 'Step 3: Show schema for main table',
+        request:
+          'For the table with the most records, show me the column structure (column names and data types) so I understand what data is stored there.',
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks (Sequential Workflow)');
+    console.info('═'.repeat(60));
+
+    // Run each task through the agent sequentially
+    // Each task builds on previous results instead of making assumptions
+    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 SQL queries');
+    console.info('  ✅ LLM generates SQL based on context');
+    console.info('  ✅ Database credentials NEVER exposed to LLM');
+    console.info('  ✅ Matimo handles secure credential injection');
+    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
+runPostgresAIAgent().catch(console.error);

package/postgres/postgres-with-approval.ts

@@ -0,0 +1,344 @@
+/**
+ * Postgres Tool Example with Real Database and Approval Flow
+ *
+ * This example demonstrates:
+ * 1. Connecting to a real Postgres database
+ * 2. Executing non-destructive queries (SELECT) - no approval needed
+ * 3. Executing destructive queries - approval required and handled
+ * 4. Setting up a single generic approval callback
+ *
+ * Approval Flow (Generic for ALL tools):
+ * - Tool declares requires_approval in YAML OR contains destructive keywords
+ * - Check MATIMO_AUTO_APPROVE=true (approve all)
+ * - Check MATIMO_APPROVED_PATTERNS="pattern*" (pre-approved patterns)
+ * - Call single approval callback for user/policy approval
+ * - No per-tool, per-provider custom logic needed
+ *
+ * Setup Instructions:
+ * 1. Make sure you have a Postgres instance running locally or accessible
+ * 2. Set the connection string via environment variable:
+ *    export MATIMO_POSTGRES_URL="postgresql://user:password@localhost:5432/dbname"
+ *    OR set individual components:
+ *    export MATIMO_POSTGRES_HOST="localhost"
+ *    export MATIMO_POSTGRES_PORT="5432"
+ *    export MATIMO_POSTGRES_USER="user"
+ *    export MATIMO_POSTGRES_PASSWORD="password"
+ *    export MATIMO_POSTGRES_DB="dbname"
+ *
+ * 3. Run the example:
+ *    pnpm postgres:approval
+ */
+
+import 'dotenv/config';
+import { MatimoInstance, getGlobalApprovalHandler, type ApprovalRequest } from '@matimo/core';
+import * as readline from 'readline';
+
+// Interactive approval callback - prompts user when MATIMO_AUTO_APPROVE is not set
+function createApprovalCallback() {
+  return async (request: ApprovalRequest): Promise<boolean> => {
+    const isInteractive = process.stdin.isTTY;
+
+    console.info('\n' + '='.repeat(70));
+    console.info('🔒 APPROVAL REQUIRED FOR DESTRUCTIVE OPERATION');
+    console.info('='.repeat(70));
+    console.info(`\n📋 Tool: ${request.toolName}`);
+    console.info(`📝 Description: ${request.description || '(no description provided)'}`);
+
+    // Show SQL content if available
+    if (request.params && typeof request.params.sql === 'string') {
+      console.info(`\n📄 SQL to execute:`);
+      console.info('   ' + request.params.sql.split('\n').join('\n   '));
+    }
+
+    if (!isInteractive) {
+      console.info('\n❌ REJECTED - Non-interactive environment (no terminal)');
+      console.info('\n💡 To enable auto-approval in CI/scripts:');
+      console.info('   export MATIMO_AUTO_APPROVE=true');
+      console.info('\n💡 Or approve specific patterns:');
+      console.info('   export MATIMO_APPROVED_PATTERNS="postgres-execute-sql"');
+      console.info('\n' + '='.repeat(70) + '\n');
+      return false;
+    }
+
+    // Interactive mode: prompt user
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+      console.info('\n❓ User Action Required');
+      const question = '   Type "yes" to approve or "no" to reject: ';
+
+      rl.question(question, (answer) => {
+        const approved = answer.toLowerCase() === 'yes' || answer.toLowerCase() === 'y';
+
+        if (approved) {
+          console.info('   ✅ Operation APPROVED by user');
+        } else {
+          console.info('   ❌ Operation REJECTED by user');
+        }
+        console.info('='.repeat(70) + '\n');
+
+        rl.close();
+        resolve(approved);
+      });
+    });
+  };
+}
+
+async function main() {
+  // Check if database connection is available
+  if (
+    !process.env.MATIMO_POSTGRES_URL &&
+    (!process.env.MATIMO_POSTGRES_HOST ||
+      !process.env.MATIMO_POSTGRES_USER ||
+      !process.env.MATIMO_POSTGRES_PASSWORD ||
+      !process.env.MATIMO_POSTGRES_DB)
+  ) {
+    console.error('❌ Database connection not configured.');
+    console.error('Please set one of:');
+    console.error('  - MATIMO_POSTGRES_URL="postgresql://user:password@host:port/db"');
+    console.error(
+      '  - MATIMO_POSTGRES_HOST, MATIMO_POSTGRES_PORT, MATIMO_POSTGRES_USER, MATIMO_POSTGRES_PASSWORD, MATIMO_POSTGRES_DB'
+    );
+    process.exit(1);
+  }
+
+  // Initialize Matimo with postgres tools
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  console.info('\n' + '='.repeat(70));
+  console.info('🚀 Postgres Tool Example with Approval Flow');
+  console.info('='.repeat(70));
+
+  // Configure centralized approval handler
+  const approvalHandler = getGlobalApprovalHandler();
+  approvalHandler.setApprovalCallback(createApprovalCallback());
+
+  // Show current approval mode
+  const autoApproveEnabled = process.env.MATIMO_AUTO_APPROVE === 'true';
+  const approvedPatterns = process.env.MATIMO_APPROVED_PATTERNS;
+
+  console.info('\n🔐 APPROVAL CONFIGURATION:');
+  if (autoApproveEnabled) {
+    console.info('   ✅ MATIMO_AUTO_APPROVE=true');
+    console.info('   → All destructive operations will be AUTO-APPROVED');
+  } else if (approvedPatterns) {
+    console.info(`   ✅ MATIMO_APPROVED_PATTERNS="${approvedPatterns}"`);
+    console.info('   → Matching operations will be auto-approved');
+  } else {
+    console.info('   ⚠️  INTERACTIVE MODE ENABLED');
+    console.info('   → You will be prompted to approve destructive operations');
+    console.info('   → Type "yes" or "no" when prompted');
+  }
+
+  try {
+    // 1. List available tools
+    const tools = matimo.listTools();
+    const postgresTools = tools.filter((t) => t.name.startsWith('postgres'));
+    console.info(`\n📋 Available Postgres tools: ${postgresTools.map((t) => t.name).join(', ')}`);
+
+    // Sequential discovery workflow
+
+    // STEP 1: Discover tables (SELECT - no approval needed)
+    console.info('\n\n1️⃣  DISCOVER TABLES (Step 1/3 - No approval needed)');
+    console.info('-'.repeat(70));
+
+    let discoveredTables: string[] = [];
+    try {
+      console.info('Executing: SELECT table_name FROM information_schema.tables...');
+      console.info('(This is a SELECT - no approval will be requested)\n');
+      const tablesResult = await matimo.execute('postgres-execute-sql', {
+        sql: `
+          SELECT table_name 
+          FROM information_schema.tables 
+          WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+          ORDER BY table_name;
+        `,
+      });
+      if (
+        tablesResult &&
+        typeof tablesResult === 'object' &&
+        'success' in tablesResult &&
+        (tablesResult as any).success === false
+      ) {
+        throw new Error((tablesResult as any).error || 'Query failed');
+      }
+      console.info('✅ Query executed successfully (no approval required for SELECT)');
+      if (tablesResult && typeof tablesResult === 'object' && 'rows' in tablesResult) {
+        const rows = (tablesResult as any).rows;
+        if (rows && rows.length > 0) {
+          console.info('Tables found:');
+          rows.forEach((row: any) => {
+            console.info(`   - ${row.table_name}`);
+            discoveredTables.push(row.table_name);
+          });
+        } else {
+          console.info('(No tables found in public schema)');
+        }
+      } else {
+        console.info('(No tables found in public schema)');
+      }
+    } catch (err: any) {
+      console.error('❌ Error:', err.message);
+    }
+
+    // STEP 2: Get row counts (SELECT - no approval needed)
+    console.info('\n\n2️⃣  COUNT RECORDS (Step 2/3 - No approval needed)');
+    console.info('-'.repeat(60));
+    console.info('SQL: SELECT tablename, n_live_tup FROM pg_stat_user_tables\n');
+
+    try {
+      const countsResult = await matimo.execute('postgres-execute-sql', {
+        sql: `
+          SELECT 
+            table_name,
+            (SELECT count(*) FROM information_schema.columns 
+             WHERE information_schema.columns.table_name = t.table_name) as columns
+          FROM information_schema.tables t
+          WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+          ORDER BY table_name;
+        `,
+      });
+      if (
+        countsResult &&
+        typeof countsResult === 'object' &&
+        'success' in countsResult &&
+        (countsResult as any).success === false
+      ) {
+        throw new Error((countsResult as any).error || 'Query failed');
+      }
+      console.info('✅ Query executed successfully (no approval needed for SELECT)');
+      if (countsResult && typeof countsResult === 'object' && 'rows' in countsResult) {
+        const rows = (countsResult as any).rows;
+        if (rows && rows.length > 0) {
+          console.info('Tables found:');
+          rows.forEach((row: any) => {
+            console.info(`   - ${row.table_name} (${row.columns} columns)`);
+          });
+        } else {
+          console.info('(No tables found in public schema)');
+        }
+      } else {
+        console.info('(No tables found in public schema)');
+      }
+    } catch (err: any) {
+      console.error('❌ Error:', err.message);
+    }
+
+    // STEP 3: Try a destructive operation that requires approval
+    console.info('\n\n3️⃣  DESTRUCTIVE OPERATION (Step 3/3 - Requires approval)');
+    console.info('-'.repeat(70));
+    console.info('Attempting DELETE operation - this WILL trigger approval...\n');
+
+    if (discoveredTables.length > 0) {
+      const tableName = discoveredTables[0];
+      const deleteSql = `DELETE FROM ${tableName} WHERE 1=0;`;
+      console.info(`📄 SQL Query: ${deleteSql}`);
+      console.info('⚠️  NOTE: This is a DESTRUCTIVE operation (DELETE keyword detected)');
+      console.info('⚠️  NOTE: WHERE 1=0 matches no rows, so it is SAFE\n');
+
+      if (autoApproveEnabled) {
+        console.info('ℹ️  MATIMO_AUTO_APPROVE=true → Will auto-approve this operation\n');
+      } else if (approvedPatterns) {
+        console.info(`ℹ️  MATIMO_APPROVED_PATTERNS set → Checking pattern matching...\n`);
+      } else {
+        console.info('ℹ️  INTERACTIVE MODE → You will be prompted to approve/reject\n');
+      }
+
+      try {
+        // Safe DELETE that matches no rows (WHERE 1=0)
+        const deleteResult = await matimo.execute('postgres-execute-sql', {
+          sql: deleteSql,
+        });
+
+        // Check if operation was rejected by user approval
+        if (
+          deleteResult &&
+          typeof deleteResult === 'object' &&
+          'approved' in deleteResult &&
+          (deleteResult as any).approved === false
+        ) {
+          console.info('\n⚠️  DELETE was REJECTED by user approval');
+          console.info(`   Reason: ${(deleteResult as any).reason}`);
+          console.info('   The operation was cancelled due to approval denial\n');
+        } else {
+          console.info('\n✅ DELETE APPROVED AND EXECUTED');
+          console.info('   Operation was approved (or auto-approved)');
+          console.info('   (0 rows deleted - safe WHERE clause)\n');
+        }
+      } catch (err: any) {
+        const errorMsg = err?.message || String(err);
+
+        if (
+          errorMsg.includes('Operation rejected') ||
+          errorMsg.includes('not approved') ||
+          errorMsg.includes('User or policy rejected')
+        ) {
+          console.info('\n⚠️  DELETE was REJECTED by user');
+          console.info(`   Reason: ${errorMsg}`);
+          console.info('   You chose to reject this destructive operation\n');
+        } else if (errorMsg.includes('approval') && errorMsg.includes('required')) {
+          console.info('\n⚠️  DELETE REQUIRES APPROVAL');
+          console.info(`   Error: ${errorMsg}`);
+          console.info('   Set MATIMO_AUTO_APPROVE=true to auto-approve, or run interactively\n');
+        } else {
+          console.error(`\n❌ Unexpected error: ${errorMsg}\n`);
+        }
+      }
+    } else {
+      console.info('\n⚠️  No tables found to demonstrate destructive operation');
+      console.info('   (Would require approval when attempting DELETE/UPDATE/CREATE/DROP/ALTER)\n');
+    }
+
+    // STEP 4: Show approval configuration and summary
+    console.info('\n\n4️⃣  APPROVAL SYSTEM SUMMARY');
+    console.info('='.repeat(70));
+
+    console.info('\n📋 Current Settings:');
+    if (autoApproveEnabled) {
+      console.info('   ✅ MATIMO_AUTO_APPROVE=true → All destructive ops AUTO-APPROVED');
+    } else if (approvedPatterns) {
+      console.info(`   ✅ MATIMO_APPROVED_PATTERNS="${approvedPatterns}"`);
+      console.info('   → Matching patterns AUTO-APPROVED, others require user input');
+    } else {
+      console.info('   ⚠️  Interactive Mode (RECOMMENDED FOR HUMANS)');
+      console.info('   → All destructive operations require your "yes/no" input');
+    }
+
+    console.info('\n💡 How to Use:');
+    console.info('   1. Interactive (default):     pnpm postgres:approval');
+    console.info(
+      '   2. Auto-approve in CI:         MATIMO_AUTO_APPROVE=true pnpm postgres:approval'
+    );
+    console.info(
+      '   3. Pre-approved patterns:      MATIMO_APPROVED_PATTERNS="postgres*" pnpm postgres:approval'
+    );
+
+    console.info('\n🔐 Supported Approval Modes:');
+    console.info('   • MATIMO_AUTO_APPROVE=true     → Approve all destructive operations');
+    console.info(
+      '   • MATIMO_APPROVED_PATTERNS     → Approve only matching tool names (glob pattern)'
+    );
+    console.info('   • Interactive (no env vars)    → Prompt user for each operation');
+
+    console.info('\n✨ Workflow Complete! You tested:');
+    console.info('   1. ✅ SELECT (non-destructive) → No approval needed');
+    console.info('   2. ✅ SELECT (non-destructive) → No approval needed');
+    console.info('   3. 🔒 DELETE (destructive)    → Approval required/tested');
+
+    console.info('\n' + '='.repeat(70) + '\n');
+  } catch (err: any) {
+    console.error('\n❌ Error:', err.message);
+    if (err.code === 'ECONNREFUSED') {
+      console.error('\nDatabase connection refused. Make sure your Postgres instance is running.');
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});