matimo 0.1.0-alpha.1 → 0.1.0-alpha.3

package/docs/user-guide/SDK_PATTERNS.md

@@ -1,316 +0,0 @@
-# SDK Usage Patterns
-
-Learn the two main ways to use Matimo SDK in v0.1.0-alpha.1.
-
-## Pattern 1: Factory Pattern (Recommended for Simple Use Cases)
-
-The factory pattern is the simplest and most ergonomic way to use Matimo.
-
-### Basic Setup
-
-```typescript
-import { matimo } from 'matimo';
-
-// Initialize once
-const m = await matimo.init('./tools');
-```
-
-### Execute a Tool
-
-```typescript
-const result = await m.execute('calculator', {
-  operation: 'add',
-  a: 5,
-  b: 3
-});
-
-console.log(result); // { result: 8 }
-```
-
-### Discover Tools
-
-```typescript
-// List all tools
-const allTools = m.listTools();
-console.log(`Loaded ${allTools.length} tools`);
-
-// Get specific tool
-const tool = m.getTool('calculator');
-console.log(`Tool: ${tool.name} - ${tool.description}`);
-
-// Filter by tags
-const mathTools = m.getToolsByTag('math');
-mathTools.forEach(t => console.log(`- ${t.name}`));
-
-// Search tools
-const results = m.searchTools('email');
-results.forEach(t => console.log(`Found: ${t.name}`));
-```
-
-### Handle Errors
-
-```typescript
-try {
-  const result = await m.execute('calculator', {
-    operation: 'divide',
-    a: 10,
-    b: 0  // ⚠️ Will fail
-  });
-} catch (error) {
-  if (error.code === 'TOOL_NOT_FOUND') {
-    console.error('Tool not available:', error.message);
-  } else if (error.code === 'INVALID_PARAMETERS') {
-    console.error('Bad parameters:', error.details);
-  } else if (error.code === 'EXECUTION_FAILED') {
-    console.error('Tool error:', error.details);
-  }
-}
-```
-
-### Complete Example
-
-```typescript
-import { matimo } from 'matimo';
-
-async function main() {
-  try {
-    // 1. Initialize
-    const m = await matimo.init('./tools');
-
-    // 2. List available tools
-    const tools = m.listTools();
-    console.log(`📦 Loaded ${tools.length} tools`);
-
-    // 3. Execute tool
-    const result = await m.execute('gmail-send-email', {
-      to: 'recipient@example.com',
-      subject: 'Hello',
-      body: 'Message from Matimo'
-    });
-
-    console.log('✅ Email sent:', result);
-  } catch (error) {
-    console.error('❌ Error:', error.message);
-  }
-}
-
-main();
-```
-
----
-
-## Pattern 2: Decorator Pattern (Recommended for Class-Based Code)
-
-The decorator pattern is ideal for class-based agents and applications.
-
-### Basic Setup
-
-```typescript
-import { tool, matimo } from 'matimo';
-
-// Initialize Matimo
-const matimoInstance = await matimo.init('./tools');
-
-// Create agent class
-class EmailAgent {
-  constructor(private matimoInstance: any) {}
-
-  @tool('gmail-send-email')
-  async sendEmail(to: string, subject: string, body: string) {
-    // Decorator handles execution
-    // Method body is optional - decorator does the work
-  }
-
-  @tool('gmail-list-messages')
-  async listEmails(maxResults?: number) {
-    // Executed by decorator
-    // Return type inferred from tool definition
-  }
-}
-
-// Use it
-const agent = new EmailAgent(matimoInstance);
-
-// Call decorated methods
-await agent.sendEmail(
-  'john@example.com',
-  'Hello John',
-  'This is a test email'
-);
-
-const emails = await agent.listEmails(10);
-console.log(`Found ${emails.length} emails`);
-```
-
-### Advanced: Custom Agent with Multiple Tools
-
-```typescript
-import { tool, matimo } from 'matimo';
-
-class AIAssistant {
-  constructor(private matimo: any) {}
-
-  @tool('calculator')
-  async calculate(operation: string, a: number, b: number) {
-    // Decorator auto-executes the calculator tool
-    // Argument order matches tool parameters
-  }
-
-  @tool('gmail-send-email')
-  async sendEmail(to: string, subject: string, body: string) {
-    // Send emails as part of workflow
-  }
-
-  @tool('gmail-list-messages')
-  async checkEmails(maxResults?: number) {
-    // List emails
-  }
-
-  // Custom methods that use tools
-  async runWorkflow(userEmail: string) {
-    // Orchestrate tool calls
-    const emails = await this.checkEmails(5);
-    console.log(`Checking ${emails.length} latest emails`);
-
-    if (emails.length > 0) {
-      await this.sendEmail(
-        userEmail,
-        'Daily Summary',
-        `You have ${emails.length} unread emails`
-      );
-    }
-  }
-}
-
-// Usage
-const matimo = await matimo.init('./tools');
-const assistant = new AIAssistant(matimo);
-
-await assistant.runWorkflow('user@example.com');
-```
-
----
-
-## Comparison: Factory vs Decorator
-
-| Feature | Factory | Decorator |
-|---------|---------|-----------|
-| **Simplicity** | Simple | Requires classes |
-| **Best For** | Scripts, backends | Agents, complex apps |
-| **Syntax** | `m.execute()` | `@tool()` |
-| **Type Safety** | Good | Excellent |
-| **Framework Fit** | Any | Class-based |
-| **Async/Await** | Required | Required |
-| **Error Handling** | Try/catch | Try/catch |
-
----
-
-## Using Matimo with AI Frameworks
-
-For intelligent tool orchestration with LangChain, CrewAI, Claude SDK, or other AI frameworks where the LLM automatically decides which tool to use, see:
-
-- **[LangChain Integration Guide](../framework-integrations/LANGCHAIN.md)** — Complete patterns with LangChain
-  - Official API pattern (recommended)
-  - Decorator pattern with LangChain
-  - Factory pattern with LangChain
-  - Working examples with GPT-4
-
----
-
-## Patterns in Different Contexts
-
-### Backend API
-
-```typescript
-// Express.js route handler
-import { matimo } from 'matimo';
-
-const m = await matimo.init('./tools');
-
-app.post('/api/send-email', async (req, res) => {
-  try {
-    const result = await m.execute('gmail-send-email', {
-      to: req.body.to,
-      subject: req.body.subject,
-      body: req.body.body
-    });
-    res.json({ success: true, result });
-  } catch (error) {
-    res.status(400).json({ error: error.message });
-  }
-});
-```
-
-### LangChain Agent
-
-```typescript
-// See LANGCHAIN.md for full integration
-const m = await matimo.init('./tools');
-
-const langchainTools = m.listTools().map(tool => ({
-  name: tool.name,
-  description: tool.description,
-  run: async (input) => {
-    const result = await m.execute(tool.name, JSON.parse(input));
-    return JSON.stringify(result);
-  }
-}));
-```
-
-### CLI Tool
-
-```typescript
-// Command-line interface
-import { matimo } from 'matimo';
-
-const m = await matimo.init('./tools');
-
-const toolName = process.argv[2];
-const params = JSON.parse(process.argv[3] || '{}');
-
-const result = await m.execute(toolName, params);
-console.log(JSON.stringify(result, null, 2));
-```
-
----
-
-## Error Handling Best Practices
-
-```typescript
-import { MatimoError } from 'matimo';
-
-try {
-  const result = await m.execute('calculator', params);
-} catch (error) {
-  if (error instanceof MatimoError) {
-    // Handle Matimo-specific errors
-    switch (error.code) {
-      case 'TOOL_NOT_FOUND':
-        console.error(`Tool not available: ${error.message}`);
-        break;
-      case 'INVALID_PARAMETERS':
-        console.error(`Bad parameters: ${JSON.stringify(error.details)}`);
-        break;
-      case 'EXECUTION_FAILED':
-        console.error(`Execution failed: ${error.details}`);
-        break;
-      default:
-        console.error(`Unknown error: ${error.message}`);
-    }
-  } else {
-    // Handle other errors
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
----
-
-## Next Steps
-
-- **[Tool Discovery Guide](./TOOL_DISCOVERY.md)** — More on finding tools
-- **[LangChain Integration](../framework-integrations/LANGCHAIN.md)** — Using with LangChain
-- **[Decorator Pattern Guide](../tool-development/DECORATOR_GUIDE.md)** — Deep dive on decorators
-- **[API Reference](../api-reference/SDK.md)** — Complete API docs
-
-See [examples/](../../examples/) for working code.

package/docs/user-guide/TOOL_DISCOVERY.md

@@ -1,209 +0,0 @@
-# Tool Discovery & Filtering
-
-Find and filter tools by name, description, and tags.
-
-## List All Tools
-
-```typescript
-import { matimo } from 'matimo';
-
-const m = await matimo.init('./tools');
-
-// List all loaded tools
-const allTools = m.listTools();
-console.log(`Loaded ${allTools.length} tools`);
-
-allTools.forEach(tool => {
-  console.log(`• ${tool.name} - ${tool.description}`);
-});
-```
-
-**Output:**
-```
-Loaded 8 tools
-• calculator - Perform basic math operations
-• gmail-send-email - Send an email via Gmail API
-• gmail-list-messages - List emails from Gmail
-• github-create-issue - Create a GitHub issue
-... (more tools)
-```
-
----
-
-## Get Specific Tool
-
-```typescript
-const tool = m.getTool('calculator');
-
-console.log(`Name: ${tool.name}`);
-console.log(`Description: ${tool.description}`);
-console.log(`Version: ${tool.version}`);
-```
-
----
-
-## Filter by Tags
-
-```typescript
-// Get tools with specific tags
-const mathTools = m.getToolsByTag('math');
-console.log(`Math tools: ${mathTools.map(t => t.name).join(', ')}`);
-
-const emailTools = m.getToolsByTag('email');
-console.log(`Email tools: ${emailTools.map(t => t.name).join(', ')}`);
-```
-
----
-
-## Search Tools
-
-```typescript
-// Search by name or description
-const results = m.searchTools('email');
-
-results.forEach(tool => {
-  console.log(`Found: ${tool.name}`);
-  console.log(`  Description: ${tool.description}`);
-  console.log(`  Tags: ${tool.tags?.join(', ') || 'none'}`);
-});
-```
-
-**Output:**
-```
-Found: gmail-send-email
-  Description: Send an email via Gmail API
-  Tags: email, gmail, http
-
-Found: gmail-list-messages
-  Description: List emails from Gmail
-  Tags: email, gmail, http
-```
-
----
-
-## Filter Criteria
-
-### By Type
-
-```typescript
-// Filter by execution type
-const httpTools = m.listTools().filter(t => t.execution?.type === 'http');
-console.log(`HTTP tools: ${httpTools.length}`);
-
-const cmdTools = m.listTools().filter(t => t.execution?.type === 'command');
-console.log(`Command tools: ${cmdTools.length}`);
-```
-
-### By Authentication
-
-```typescript
-// Tools requiring OAuth2
-const oauth2Tools = m.listTools().filter(t => t.authentication?.type === 'oauth2');
-console.log(`OAuth2 tools: ${oauth2Tools.map(t => t.name).join(', ')}`);
-```
-
-### By Provider
-
-```typescript
-// Gmail tools
-const gmailTools = m.listTools().filter(t => t.name.startsWith('gmail-'));
-console.log(`Gmail tools: ${gmailTools.map(t => t.name).join(', ')}`);
-
-// GitHub tools
-const githubTools = m.listTools().filter(t => t.name.startsWith('github-'));
-console.log(`GitHub tools: ${githubTools.map(t => t.name).join(', ')}`);
-```
-
----
-
-## Tool Metadata
-
-Each tool has:
-
-```typescript
-const tool = m.getTool('calculator');
-
-// Basic info
-tool.name                    // 'calculator'
-tool.description             // 'Perform basic math operations'
-tool.version                 // '1.0.0'
-
-// Parameters
-tool.parameters              // { operation: {...}, a: {...}, b: {...} }
-Object.keys(tool.parameters) // ['operation', 'a', 'b']
-
-// Execution config
-tool.execution.type          // 'command' | 'http'
-tool.execution.command       // shell command (if type === 'command')
-tool.execution.url           // API endpoint (if type === 'http')
-
-// Authentication
-tool.authentication?.type    // 'oauth2' | 'api_key' | etc.
-tool.authentication?.provider // 'google' | 'github' | 'slack'
-
-// Output
-tool.output_schema           // { type: 'object', properties: {...} }
-
-// Metadata
-tool.tags                    // ['math', 'calculator']
-tool.author                  // 'Matimo'
-tool.license                 // 'MIT'
-```
-
----
-
-## Common Use Cases
-
-### Find All Email Tools
-
-```typescript
-const emailTools = m.listTools()
-  .filter(t => t.tags?.includes('email'));
-
-emailTools.forEach(tool => {
-  console.log(`- ${tool.name}: ${tool.description}`);
-});
-```
-
-### Find Tools Without Authentication
-
-```typescript
-const publicTools = m.listTools()
-  .filter(t => !t.authentication);
-
-console.log(`Public tools (no auth required):`);
-publicTools.forEach(t => console.log(`  - ${t.name}`));
-```
-
-### Find Tools Requiring OAuth2
-
-```typescript
-const oauth2Tools = m.listTools()
-  .filter(t => t.authentication?.type === 'oauth2');
-
-console.log(`Tools requiring OAuth2:`);
-oauth2Tools.forEach(t => {
-  console.log(`  - ${t.name} (${t.authentication?.provider})`);
-});
-```
-
-### List All Providers
-
-```typescript
-const providers = new Set(
-  m.listTools()
-    .filter(t => t.authentication?.provider)
-    .map(t => t.authentication?.provider)
-);
-
-console.log(`Available providers: ${Array.from(providers).join(', ')}`);
-```
-
----
-
-## Next Steps
-
-- **Execute Tools**: [Your First Tool](../getting-started/YOUR_FIRST_TOOL.md)
-- **Learn Patterns**: [SDK Usage Patterns](./SDK_PATTERNS.md)
-- **Setup OAuth2**: [Authentication Guide](./AUTHENTICATION.md)
-