matimo-examples 0.1.0-alpha.7

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "matimo-examples",
+  "version": "0.1.0-alpha.7",
+  "description": "Matimo SDK examples - Factory Pattern, Decorator Pattern, and LangChain integration with Slack and Gmail",
+  "type": "module",
+  "dependencies": {
+    "@langchain/core": "^1.1.18",
+    "@langchain/openai": "^1.2.4",
+    "langchain": "^1.2.16",
+    "dotenv": "^17.2.3",
+    "zod": "^4.3.6",
+    "matimo": "0.1.0-alpha.7",
+    "@matimo/gmail": "0.1.0-alpha.7",
+    "@matimo/postgres": "0.1.0-alpha.7",
+    "@matimo/slack": "0.1.0-alpha.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "better-sqlite3": "^12.6.2",
+    "typescript": "^5.9.3",
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "agent:decorator": "tsx agents/decorator-pattern-agent.ts",
+    "agent:factory": "tsx agents/factory-pattern-agent.ts",
+    "agent:langchain": "tsx agents/langchain-agent.ts",
+    "gmail:factory": "tsx gmail/gmail-factory.ts",
+    "gmail:decorator": "tsx gmail/gmail-decorator.ts",
+    "gmail:langchain": "tsx gmail/gmail-langchain.ts",
+    "slack:factory": "tsx slack/slack-factory.ts",
+    "slack:decorator": "tsx slack/slack-decorator.ts",
+    "slack:langchain": "tsx slack/slack-langchain.ts",
+    "postgres:factory": "tsx postgres/postgres-factory.ts",
+    "postgres:decorator": "tsx postgres/postgres-decorator.ts",
+    "postgres:langchain": "tsx postgres/postgres-langchain.ts",
+    "postgres:approval": "tsx postgres/postgres-with-approval.ts",
+    "execute:factory": "tsx execute/execute-factory.ts",
+    "execute:decorator": "tsx execute/execute-decorator.ts",
+    "execute:langchain": "tsx execute/execute-langchain.ts",
+    "read:factory": "tsx read/read-factory.ts",
+    "read:decorator": "tsx read/read-decorator.ts",
+    "read:langchain": "tsx read/read-langchain.ts",
+    "edit:factory": "tsx edit/edit-factory.ts",
+    "edit:decorator": "tsx edit/edit-decorator.ts",
+    "edit:langchain": "tsx edit/edit-langchain.ts",
+    "search:factory": "tsx search/search-factory.ts",
+    "search:decorator": "tsx search/search-decorator.ts",
+    "search:langchain": "tsx search/search-langchain.ts",
+    "web:factory": "tsx web/web-factory.ts",
+    "web:decorator": "tsx web/web-decorator.ts",
+    "web:langchain": "tsx web/web-langchain.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}

package/postgres/README.md

@@ -0,0 +1,188 @@
+# Postgres Tool Examples
+
+These examples demonstrate how to use the Matimo Postgres execute-sql tool with different patterns and approval flows.
+
+## ⚡ Quick Setup
+
+
+
+## Prerequisites
+
+Before running any examples, you need a Postgres database instance. You can either: 
+
+### Option 1: Docker (Recommended - One Command)
+
+```bash
+docker run --name postgres-matimo -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres
+```
+
+### Option 2: Local Installation
+
+**macOS with Homebrew:**
+```bash
+brew install postgresql
+brew services start postgresql
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install postgresql
+sudo systemctl start postgresql
+```
+
+### Configure Connection String
+
+The examples use these environment variables from `.env`:
+
+```bash
+MATIMO_POSTGRES_HOST=localhost
+MATIMO_POSTGRES_PORT=5432
+MATIMO_POSTGRES_USER=your_user_name
+MATIMO_POSTGRES_PASSWORD=your_db_password
+MATIMO_POSTGRES_DB=your_db_name
+```
+
+Or use a full connection string:
+
+```bash
+MATIMO_POSTGRES_URL="your connection string"
+```
+
+---
+
+## Running the Examples
+
+### 1. Factory Pattern (Simple Usage)
+
+```bash
+pnpm tsx examples/tools/postgres/postgres-factory.ts
+or
+pnpm postgres:factory
+```
+
+Basic example showing how to initialize Matimo and execute a tool.
+
+### 2. Decorator Pattern (Class-Based)
+
+```bash
+pnpm tsx examples/tools/postgres/postgres-decorator.ts
+or
+pnpm postgres:decorator
+```
+
+Example using the `@tool` decorator for a class-based approach.
+
+### 3. LangChain Integration
+
+```bash
+pnpm tsx examples/tools/postgres/postgres-langchain.ts
+or
+pnpm postgres:langchain
+```
+
+Example converting Postgres tools to LangChain-compatible schemas.
+
+### 4. Real Database with Approval Flow (Interactive)
+
+```bash
+pnpm tsx examples/tools/postgres/postgres-with-approval.ts
+or
+pnpm postgres:approval
+```
+
+**Most comprehensive example** that demonstrates:
+- ✅ Non-destructive queries (SELECT) - no approval needed
+- ✅ Destructive queries (INSERT, UPDATE, DELETE) - interactive approval
+- ✅ Interactive approval callback that asks for user confirmation
+- ✅ Auto-approval mode for CI/automated environments
+- ✅ Error handling and proper feedback
+
+This example **requires a real Postgres connection** and will:
+1. Ask for permission before executing destructive SQL operations
+2. Show actual query results
+3. Demonstrate approval rejection workflow
+
+**Example session:**
+```
+🚀 Postgres Tool Example with Approval Flow
+==================================================
+
+1️⃣  Non-destructive query (SELECT - no approval needed)
+--------------------------------------------------
+✅ Query executed successfully
+Result: { command: 'SELECT', rowCount: 1, rows: [{...}] }
+
+2️⃣  Destructive query (INSERT - requires approval)
+--------------------------------------------------
+⚠️  Approval Required for WRITE operation:
+SQL: INSERT INTO test_table ...
+Do you approve? (yes/no): yes
+Result: ✅ APPROVED
+✅ INSERT approved and executed successfully
+```
+
+## Approval Modes
+
+### Interactive Mode (Default)
+
+In interactive mode, the tool will prompt you before executing destructive SQL:
+
+```bash
+pnpm tsx examples/tools/postgres/postgres-with-approval.ts
+```
+
+### CI/Automated Mode
+
+For automated environments or CI pipelines, enable auto-approval:
+
+```bash
+export MATIMO_SQL_AUTO_APPROVE=true
+pnpm tsx examples/tools/postgres/postgres-with-approval.ts
+```
+
+### Permanent Approval Patterns
+
+Define SQL patterns that are permanently approved:
+
+```bash
+export MATIMO_SQL_APPROVED_PATTERNS="DELETE FROM logs|DROP TABLE test_.*|TRUNCATE.*"
+pnpm tsx examples/tools/postgres/postgres-with-approval.ts
+```
+
+## Destructive SQL Detection
+
+The Postgres tool automatically detects and requires approval for these operations:
+- `CREATE` - Create tables, indexes, etc.
+- `DROP` - Drop tables, indexes, etc.
+- `ALTER` - Alter tables, columns, etc.
+- `TRUNCATE` - Truncate tables
+- `DELETE` - Delete rows
+- `UPDATE` - Update rows
+
+**SELECT, INSERT (without parameter templating), and other read-only operations are not flagged as destructive.**
+
+## Troubleshooting
+
+### "Connection refused" Error
+
+Make sure Postgres is running:
+
+```bash
+# Check if running
+psql -U postgres -c "SELECT version();"
+
+# Or start Docker container
+docker run --name postgres-matimo -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres
+```
+
+### "Permission denied" for CREATE TABLE
+
+Use a superuser or ensure the user has CREATE permissions:
+
+```sql
+ALTER USER username CREATEDB;
+```
+
+### Questions?
+
+Check the [Matimo documentation](https://github.com/tallclub/matimo/docs) or [GitHub issues](https://github.com/tallclub/matimo/issues).

package/postgres/postgres-decorator.ts

@@ -0,0 +1,198 @@
+import 'dotenv/config';
+import { MatimoInstance, setGlobalMatimoInstance, tool } from 'matimo';
+
+async function main() {
+  console.info('🚀 Postgres Decorator Pattern Example');
+  console.info('='.repeat(60));
+
+  try {
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+    setGlobalMatimoInstance(matimo);
+
+    console.info('\n📦 Initializing Matimo with decorators...');
+
+    // Class-based database client using Matimo
+    class PostgresAgent {
+      private matimo: MatimoInstance;
+
+      constructor(matimo: MatimoInstance) {
+        this.matimo = matimo;
+      }
+
+      // Sequential step 1: Discover tables
+      async discoverTables(): Promise<string[]> {
+        console.info('\n1️⃣  DISCOVER TABLES (Step 1/3)');
+        console.info('-'.repeat(60));
+        console.info('SQL: Getting all tables from information_schema...\n');
+
+        const result = await this.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;
+          `,
+        });
+
+        this.handleResult(result as any);
+
+        if (result && (result as any).rows && (result as any).rows.length > 0) {
+          return (result as any).rows.map((row: any) => row.table_name);
+        }
+        return [];
+      }
+
+      // Sequential step 2: Get row counts
+      async getTableRowCounts(): Promise<void> {
+        console.info('\n2️⃣  COUNT RECORDS (Step 2/3)');
+        console.info('-'.repeat(60));
+        console.info('SQL: Getting record counts for tables...\n');
+
+        // Try pg_stat_user_tables first, fall back to manual counts
+        try {
+          const result = await this.matimo.execute('postgres-execute-sql', {
+            sql: `
+              SELECT 
+                tablename, 
+                n_live_tup as row_count
+              FROM pg_stat_user_tables
+              WHERE schemaname = 'public'
+              ORDER BY n_live_tup DESC;
+            `,
+          });
+
+          this.handleResult(result);
+        } catch (err: any) {
+          // Fall back to information_schema method
+          console.info('⚠️  Using information_schema for row counts (pg_stat not available)');
+          const result = await this.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;
+            `,
+          });
+
+          this.handleResult(result);
+        }
+      }
+
+      // Sequential step 3: Analyze first table structure
+      async analyzeTableStructure(tableName: string): Promise<void> {
+        console.info(`\n3️⃣  ANALYZE TABLE STRUCTURE (Step 3/3)`);
+        console.info('-'.repeat(60));
+        console.info(`SQL: Getting column structure for table "${tableName}"...\n`);
+
+        const result = await this.matimo.execute('postgres-execute-sql', {
+          sql: `
+            SELECT 
+              column_name, 
+              data_type,
+              is_nullable,
+              column_default
+            FROM information_schema.columns 
+            WHERE table_name = $1
+            ORDER BY ordinal_position;
+          `,
+          params: [tableName],
+        });
+
+        this.handleResult(result);
+      }
+
+      // Bonus: Show database health
+      async showDatabaseHealth(): Promise<void> {
+        console.info('\n📊 DATABASE HEALTH');
+        console.info('-'.repeat(60));
+        console.info('SQL: Getting database and connection info...\n');
+
+        const result = await this.matimo.execute('postgres-execute-sql', {
+          sql: `
+            SELECT 
+              current_database() as database_name,
+              version() as postgres_version,
+              now() as current_time,
+              (SELECT count(*) FROM pg_stat_activity) as active_connections;
+          `,
+        });
+
+        this.handleResult(result);
+      }
+
+      private handleResult(result: any) {
+        if (
+          result &&
+          typeof result === 'object' &&
+          'success' in result &&
+          (result as any).success === false
+        ) {
+          throw new Error((result as any).error || 'Query failed');
+        }
+        if (result && typeof result === 'object' && 'rows' in result) {
+          const rows = (result as any).rows;
+          if (rows && Array.isArray(rows)) {
+            console.info(`✅ Found ${rows.length} row(s):`);
+            rows.forEach((row: any, idx: number) => {
+              console.info(`   [${idx + 1}] ${JSON.stringify(row)}`);
+            });
+          } else {
+            console.info('✅ Query executed successfully');
+          }
+        } else {
+          console.info('✅ Query executed successfully');
+        }
+      }
+    }
+
+    const agent = new PostgresAgent(matimo);
+
+    console.info('✅ Agent initialized\n');
+
+    // Execute sequential workflow
+    const tables = await agent.discoverTables();
+
+    await agent.getTableRowCounts();
+
+    // Analyze first discovered table if any exist
+    if (tables.length > 0) {
+      await agent.analyzeTableStructure(tables[0]);
+    } else {
+      console.info('\n3️⃣  ANALYZE TABLE STRUCTURE (Step 3/3)');
+      console.info('-'.repeat(60));
+      console.info('⚠️  No tables found to analyze\n');
+    }
+
+    // Show additional database health info
+    await agent.showDatabaseHealth();
+
+    console.info('\n\n✨ Sequential discovery complete!');
+    console.info('='.repeat(60));
+    console.info('Pattern: 1) Get tables 2) Count rows 3) Analyze discovered table\n');
+  } catch (err: any) {
+    console.error('\n❌ Error:');
+    const message = err.message || String(err);
+    console.error('Message:', message);
+
+    if (message.includes('ECONNREFUSED')) {
+      console.error('\n💡 Connection refused - Postgres not running?');
+    } else if (message.includes('does not exist')) {
+      console.error('\n💡 Database or user does not exist');
+    }
+
+    console.error('\nCurrent .env Postgres settings:');
+    console.error(`  MATIMO_POSTGRES_HOST=${process.env.MATIMO_POSTGRES_HOST || '(not set)'}`);
+    console.error(`  MATIMO_POSTGRES_USER=${process.env.MATIMO_POSTGRES_USER || '(not set)'}`);
+    console.error(`  MATIMO_POSTGRES_DB=${process.env.MATIMO_POSTGRES_DB || '(not set)'}`);
+
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/postgres/postgres-factory.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { MatimoInstance } from 'matimo';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  console.info('🚀 Postgres Factory Pattern Example');
+  console.info('='.repeat(60));
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('\n📦 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get postgres tools
+    const tools = matimo.listTools();
+    const postgresTools = tools.filter((t) => t.name.startsWith('postgres'));
+    console.info(`✅ Found ${postgresTools.length} Postgres tool(s)`);
+
+    // STEP 1: Discover available tables
+    console.info('\n\n1️⃣  DISCOVER TABLES (Step 1/3)');
+    console.info('-'.repeat(60));
+    console.info('SQL: Getting all tables from information_schema...\n');
+
+    const tablesResult = 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 column_count
+        FROM information_schema.tables t
+        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');
+    }
+
+    let tableNames: string[] = [];
+    console.info('✅ Tables found:');
+    if (tablesResult && typeof tablesResult === 'object' && 'rows' in tablesResult) {
+      const rows = (tablesResult as any).rows;
+      if (rows && rows.length > 0) {
+        rows.forEach((row: any) => {
+          tableNames.push(row.table_name);
+          console.info(`   - ${row.table_name} (${row.column_count} columns)`);
+        });
+      } else {
+        console.info('   (No tables in public schema)');
+      }
+    } else {
+      console.info('   (No tables in public schema)');
+    }
+
+    // STEP 2: Get row counts for each table
+    console.info('\n\n2️⃣  COUNT RECORDS (Step 2/3)');
+    console.info('-'.repeat(60));
+
+    if (tableNames.length > 0) {
+      console.info(`SQL: Getting record counts for ${tableNames.length} table(s)...\n`);
+
+      const countsResult = await matimo.execute('postgres-execute-sql', {
+        sql: `
+          SELECT 
+            schemaname, 
+            tablename, 
+            n_live_tup as row_count
+          FROM pg_stat_user_tables
+          WHERE schemaname = 'public'
+          ORDER BY n_live_tup DESC;
+        `,
+        params: [],
+      });
+
+      if (
+        countsResult &&
+        typeof countsResult === 'object' &&
+        'success' in countsResult &&
+        (countsResult as any).success === false
+      ) {
+        console.info('⚠️  Could not get row counts');
+      } else {
+        console.info('✅ Record counts by table:');
+        if (countsResult && typeof countsResult === 'object' && 'rows' in countsResult) {
+          const rows = (countsResult as any).rows;
+          if (rows && rows.length > 0) {
+            rows.forEach((row: any) => {
+              console.info(`   - ${row.tablename}: ${row.row_count} rows`);
+            });
+          }
+        }
+      }
+    }
+
+    // STEP 3: Analyze the first discovered table
+    console.info('\n\n3️⃣  ANALYZE TABLE STRUCTURE (Step 3/3)');
+    console.info('-'.repeat(60));
+
+    if (tableNames.length > 0) {
+      const firstTable = tableNames[0];
+      console.info(`SQL: Getting column structure for table "${firstTable}"...\n`);
+
+      const columnsResult = await matimo.execute('postgres-execute-sql', {
+        sql: `
+          SELECT 
+            column_name, 
+            data_type,
+            is_nullable,
+            column_default
+          FROM information_schema.columns 
+          WHERE table_name = $1
+          ORDER BY ordinal_position;
+        `,
+        params: [firstTable],
+      });
+
+      if (
+        columnsResult &&
+        typeof columnsResult === 'object' &&
+        'success' in columnsResult &&
+        (columnsResult as any).success === false
+      ) {
+        console.info('⚠️  Could not get column structure');
+      } else {
+        console.info(`✅ Columns in "${firstTable}" table:`);
+        if (columnsResult && typeof columnsResult === 'object' && 'rows' in columnsResult) {
+          const rows = (columnsResult as any).rows;
+          if (rows && rows.length > 0) {
+            rows.forEach((row: any) => {
+              const nullable = row.is_nullable === 'YES' ? 'nullable' : 'NOT NULL';
+              const defaultVal = row.column_default ? ` = ${row.column_default}` : '';
+              console.info(`   - ${row.column_name} (${row.data_type}) ${nullable}${defaultVal}`);
+            });
+          }
+        }
+      }
+    }
+
+    console.info('\n\n✨ Sequential discovery complete!');
+    console.info('='.repeat(60));
+    console.info('Pattern: 1) Get tables 2) Count rows 3) Analyze discovered table\n');
+  } catch (err: any) {
+    console.error('\n❌ Error:');
+
+    // Try to extract helpful information
+    const message = err.message || String(err);
+    console.error('Message:', message);
+
+    // Provide specific hints based on error type
+    if (message.includes('ECONNREFUSED') || message.includes('Connection refused')) {
+      console.error('\n💡 Connection refused - Postgres not running?');
+      console.error('   Check docker-compose or your Postgres instance');
+    } else if (message.includes('does not exist')) {
+      console.error('\n💡 Database or user does not exist');
+      console.error('   Verify MATIMO_POSTGRES_* env vars in .env');
+    }
+
+    console.error('\nCurrent .env Postgres settings:');
+    console.error(`  MATIMO_POSTGRES_HOST=${process.env.MATIMO_POSTGRES_HOST || '(not set)'}`);
+    console.error(`  MATIMO_POSTGRES_PORT=${process.env.MATIMO_POSTGRES_PORT || '(not set)'}`);
+    console.error(`  MATIMO_POSTGRES_USER=${process.env.MATIMO_POSTGRES_USER || '(not set)'}`);
+    console.error(`  MATIMO_POSTGRES_DB=${process.env.MATIMO_POSTGRES_DB || '(not set)'}`);
+
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});