matimo 0.1.0-alpha.2 → 0.1.0-alpha.4

package/docs/framework-integrations/LANGCHAIN.md

@@ -1,286 +0,0 @@
-# LangChain Integration
-
-## Overview
-
-Matimo tools integrate seamlessly with LangChain for AI-powered agents. This guide shows how to use Matimo tools in LangChain applications.
-
-## v0.1.0-alpha.1 Status
-
-**✅ Implemented**: Direct SDK usage with LangChain tools interface
-**🔜 Future**: LangChain adapters and plugins
-
-## Installation
-
-```bash
-npm install matimo langchain @langchain/core
-# or
-pnpm add matimo langchain @langchain/core
-```
-
-## Basic Integration
-
-### 1. Load Matimo Tools
-
-```typescript
-import { matimo } from 'matimo';
-
-// Initialize Matimo with your tools
-const matimoInstance = await matimo.init('./tools');
-
-// Get available tools
-const allTools = matimoInstance.listTools();
-console.log('Available tools:', allTools.map(t => t.name));
-```
-
-### 2. Execute Tools Directly
-
-```typescript
-import { matimo } from 'matimo';
-
-const m = await matimo.init('./tools');
-
-// Execute a tool
-const result = await m.execute('gmail-send-email', {
-  to: 'user@example.com',
-  subject: 'Hello',
-  body: 'World'
-});
-
-console.log('Email sent:', result);
-```
-
-### 3. Using with LangChain Agents
-
-```typescript
-import { matimo } from 'matimo';
-import { ChatOpenAI } from '@langchain/openai';
-import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
-import { Tool } from '@langchain/core/tools';
-
-// Initialize Matimo
-const matimoInstance = await matimo.init('./tools');
-
-// Wrap Matimo tools for LangChain
-function createLangChainTool(matimoTool): Tool {
-  return new Tool({
-    name: matimoTool.name,
-    description: matimoTool.description,
-    func: async (input) => {
-      // Parse input and execute
-      const params = JSON.parse(input);
-      const result = await matimoInstance.execute(
-        matimoTool.name,
-        params
-      );
-      return JSON.stringify(result);
-    }
-  });
-}
-
-// Create LangChain tools from Matimo
-const langchainTools = matimoInstance
-  .listTools()
-  .map(tool => createLangChainTool(tool));
-
-// Create LangChain agent
-const model = new ChatOpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-  temperature: 0
-});
-
-const agent = await createOpenAIFunctionsAgent({
-  llm: model,
-  tools: langchainTools,
-  prompt: ChatPromptTemplate.fromMessages([
-    ['system', 'You are a helpful assistant with access to various tools.'],
-    ['human', '{input}'],
-    new MessagesPlaceholder('agent_scratchpad')
-  ])
-});
-
-const agentExecutor = new AgentExecutor({
-  agent,
-  tools: langchainTools,
-  verbose: true
-});
-
-// Run agent
-const result = await agentExecutor.invoke({
-  input: 'Send an email to john@example.com saying hello'
-});
-
-console.log('Agent response:', result.output);
-```
-
-## Decorator Pattern with LangChain
-
-For class-based agents using decorators:
-
-```typescript
-import { tool, matimo } from 'matimo';
-import { BaseLanguageModel } from '@langchain/core/language_models';
-
-class EmailAgent {
-  constructor(private matimoInstance: any) {}
-
-  @tool('gmail-send-email')
-  async sendEmail(to: string, subject: string, body: string) {
-    // Decorator handles execution
-    // Return type is inferred from tool definition
-  }
-
-  @tool('gmail-list-messages')
-  async listEmails(maxResults?: number) {
-    // Automatically calls Matimo executor
-  }
-}
-
-// Usage with LangChain
-const m = await matimo.init('./tools');
-const agent = new EmailAgent(m);
-
-// Call decorated methods
-await agent.sendEmail(
-  'recipient@example.com',
-  'Test Subject',
-  'Test Body'
-);
-```
-
-## Working Examples
-
-See [examples/langchain/](../../examples/langchain/) for complete examples:
-
-- `gmail-langchain.ts` - Gmail tool integration with LangChain
-- `gmail-decorator.ts` - Decorator pattern example
-- `gmail-factory.ts` - Factory pattern example
-
-Run them:
-
-```bash
-cd examples/langchain
-pnpm install
-pnpm gmail:langchain --email:your@email.com
-```
-
-## Tool Parameter Mapping
-
-Matimo parameters map directly to LangChain function calls:
-
-```yaml
-# Matimo tool definition
-parameters:
-  email:
-    type: string
-    required: true
-  subject:
-    type: string
-    required: true
-  body:
-    type: string
-    required: true
-```
-
-Becomes in LangChain:
-
-```json
-{
-  "name": "gmail-send-email",
-  "description": "Send an email",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "email": { "type": "string" },
-      "subject": { "type": "string" },
-      "body": { "type": "string" }
-    },
-    "required": ["email", "subject", "body"]
-  }
-}
-```
-
-## OAuth2 with LangChain
-
-Tools requiring OAuth2 authentication:
-
-```typescript
-// Set OAuth tokens as environment variables
-process.env.GMAIL_ACCESS_TOKEN = 'your-access-token';
-process.env.GITHUB_TOKEN = 'your-github-token';
-
-// Matimo automatically injects tokens into tools
-const result = await matimoInstance.execute('gmail-send-email', {
-  to: 'user@example.com',
-  subject: 'Hello',
-  body: 'Message'
-  // Token is automatically included from environment
-});
-```
-
-## Error Handling
-
-```typescript
-try {
-  const result = await agentExecutor.invoke({
-    input: 'Send an email'
-  });
-} catch (error) {
-  if (error.code === 'TOOL_NOT_FOUND') {
-    console.error('Tool not available:', error.message);
-  } else if (error.code === 'INVALID_PARAMETERS') {
-    console.error('Invalid parameters:', error.details);
-  } else if (error.code === 'EXECUTION_FAILED') {
-    console.error('Tool execution failed:', error.details);
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-
-## Future Releases
-
-🔜 **v0.2.0** will include:
-- Official LangChain adapter package
-- Automatic tool schema conversion
-- LangChain Tool subclass implementation
-- CrewAI integration examples
-- Vercel AI SDK integration
-
----
-
-## Troubleshooting
-
-### Tool Not Found Error
-
-```
-Error: Tool not found: gmail-send-email
-```
-
-**Solution**: Verify tools are loaded correctly
-
-```typescript
-const tools = matimoInstance.listTools();
-console.log('Available tools:', tools.map(t => t.name));
-```
-
-### OAuth Token Missing
-
-```
-Error: Missing OAuth token for provider: google
-```
-
-**Solution**: Set environment variable
-
-```bash
-export GMAIL_ACCESS_TOKEN=your_token_here
-```
-
-### Type Errors with LangChain Tools
-
-Ensure all Matimo tools are properly typed:
-
-```bash
-pnpm validate-tools  # Validates all YAML definitions
-```
-
-See [Troubleshooting Guide](../troubleshooting/FAQ.md) for more help.

package/docs/getting-started/QUICK_START.md

@@ -1,212 +0,0 @@
-# Quick Start — 5 Minutes
-
-Get Matimo up and running in 5 minutes.
-
-## 1. Installation (1 min)
-
-```bash
-npm install matimo
-# or with pnpm
-pnpm add matimo
-```
-
-## 2. Load Tools (2 min)
-
-Create a file `load-tools.ts`:
-
-```typescript
-import { ToolLoader } from 'matimo';
-
-const loader = new ToolLoader('./tools');
-const tools = await loader.loadToolsFromDirectory();
-
-console.log(`Loaded ${tools.length} tools`);
-```
-
-## 3. Execute a Tool (1 min)
-
-```typescript
-import { CommandExecutor } from 'matimo';
-
-const executor = new CommandExecutor();
-const result = await executor.execute(tools[0], {
-  param1: 'value1',
-  param2: 'value2'
-});
-
-console.log(result);
-```
-
-## 4. Use the SDK Factory (1 min)
-
-```typescript
-import { MatimoFactory } from 'matimo';
-
-// Create instance with factory pattern
-const matimo = MatimoFactory.create({
-  toolsPath: './tools'
-});
-
-// List all tools
-const allTools = matimo.getToolRegistry().listTools();
-
-// Execute a tool
-const result = await matimo.executeTool('calculator', {
-  operation: 'add',
-  a: 5,
-  b: 3
-});
-
-console.log(result); // { result: 8 }
-```
-
-## Next Steps
-
-- **[API Reference](../api-reference/SDK.md)** — Full SDK documentation
-- **[Tool Specification](../tool-development/TOOL_SPECIFICATION.md)** — Write your own tools
-- **[Decorator Guide](../tool-development/DECORATOR_GUIDE.md)** — Use TypeScript decorators
-- **[Development Guide](../CONTRIBUTING.md)** — Contributing to Matimo
-
-## Common Tasks
-
-### List All Loaded Tools
-
-```typescript
-const tools = matimo.getToolRegistry().listTools();
-tools.forEach(tool => {
-  console.log(`${tool.name} - ${tool.description}`);
-});
-```
-
-### Get Tool by Name
-
-```typescript
-const tool = matimo.getToolRegistry().getTool('calculator');
-if (tool) {
-  console.log(tool.parameters);
-}
-```
-
-### Execute with Error Handling
-
-```typescript
-try {
-  const result = await matimo.executeTool('github-create-issue', {
-    repo: 'owner/repo',
-    title: 'Bug Report'
-  });
-  console.log('Success:', result);
-} catch (error) {
-  if (error.code === 'VALIDATION_FAILED') {
-    console.error('Invalid parameters:', error.message);
-  } else if (error.code === 'EXECUTION_FAILED') {
-    console.error('Tool execution failed:', error.message);
-  } else {
-    console.error('Unknown error:', error);
-  }
-}
-```
-
-### Use with MCP Server
-
-```typescript
-// MCP Server - Coming in Phase 2
-// import { MCPServer } from 'matimo/mcp';
-
-const server = new MCPServer({
-  toolsPath: './tools',
-  port: 3000
-});
-
-await server.start();
-console.log('MCP Server running on port 3000');
-// Claude can now discover and call all tools via MCP
-```
-
-## Example Directory Structure
-
-```
-project/
-├── tools/
-│   ├── calculator/
-│   │   └── defination.yaml
-│   └── github/
-|       └── defination.yaml
-│       └── create-issue
-|            └── defination.yaml
-├── src/
-│   └── app.ts
-└── package.json
-```
-
-## Example Tool YAML
-
-Create `tools/calculator/tool.yaml`:
-
-```yaml
-name: calculator
-description: Perform basic math operations
-version: "1.0.0"
-
-parameters:
-  operation:
-    type: string
-    enum: [add, subtract, multiply, divide]
-    required: true
-  a:
-    type: number
-    required: true
-  b:
-    type: number
-    required: true
-
-execution:
-  type: command
-  command: node
-  args:
-    - -e
-    - "console.log(JSON.stringify({ result: eval(`${process.argv[1]} ${process.argv[2]} ${process.argv[3]}`) }))"
-    - "{operation === 'add' ? '+' : operation === 'subtract' ? '-' : operation === 'multiply' ? '*' : '/'}"
-    - "{a}"
-    - "{b}"
-
-output_schema:
-  type: object
-  properties:
-    result:
-      type: number
-```
-
-Load and execute:
-
-```typescript
-const result = await matimo.executeTool('calculator', {
-  operation: 'add',
-  a: 10,
-  b: 5
-});
-// result = { result: 15 }
-```
-
-## Troubleshooting
-
-**Tools not loading?**
-- Check that tool YAML files are in the correct path
-- Verify YAML syntax is valid
-- Run `pnpm lint` to check for errors
-
-**Execution failing?**
-- Check parameters match the tool's parameter schema
-- Verify required environment variables are set
-- Check error message for specific failure reason
-
-**Type errors?**
-- Ensure TypeScript strict mode is enabled
-- Check that tool definitions match expected types
-- Run `pnpm build` to catch compilation errors
-
-## Support
-
-- **Questions?** Open a [GitHub Discussion](https://github.com/tallclub/matimo/discussions)
-- **Found a bug?** [Open an issue](https://github.com/tallclub/matimo/issues)
-- **Want to contribute?** See [CONTRIBUTING.md](../CONTRIBUTING.md)

package/docs/getting-started/YOUR_FIRST_TOOL.md

@@ -1,217 +0,0 @@
-# Your First Tool — Step by Step
-
-Execute your first Matimo tool in 5 minutes.
-
-## Prerequisites
-
-- ✅ Matimo installed (see [Installation](./installation.md))
-- ✅ Node.js v18+ and pnpm installed
-- ✅ `cd` into a Matimo project with tools loaded
-
-## Step 1: Initialize Matimo
-
-Create `first-tool.ts`:
-
-```typescript
-import { matimo } from 'matimo';
-
-async function main() {
-  // Initialize Matimo with tools directory
-  const m = await matimo.init('./tools');
-  
-  console.log(`✅ Loaded ${m.listTools().length} tools`);
-}
-
-main().catch(console.error);
-```
-
-Run it:
-
-```bash
-npx tsx first-tool.ts
-```
-
-**Output:**
-```
-✅ Loaded 8 tools
-```
-
----
-
-## Step 2: List Available Tools
-
-Update `first-tool.ts`:
-
-```typescript
-import { matimo } from 'matimo';
-
-async function main() {
-  const m = await matimo.init('./tools');
-  
-  // List all tools
-  const tools = m.listTools();
-  
-  console.log('\n📦 Available Tools:\n');
-  tools.forEach(tool => {
-    console.log(`  • ${tool.name}`);
-    console.log(`    ${tool.description}\n`);
-  });
-}
-
-main().catch(console.error);
-```
-
-**Output:**
-```
-📦 Available Tools:
-
-  • calculator
-    Perform basic math operations
-
-  • gmail-send-email
-    Send an email via Gmail API
-    
-  ... (more tools)
-```
-
----
-
-## Step 3: Get Tool Details
-
-```typescript
-const tool = m.getTool('calculator');
-
-console.log(`Tool: ${tool.name}`);
-console.log(`Description: ${tool.description}`);
-console.log(`Parameters:`, tool.parameters);
-```
-
-**Output:**
-```
-Tool: calculator
-Description: Perform basic math operations
-Parameters: {
-  operation: { type: 'string', required: true, ... },
-  a: { type: 'number', required: true, ... },
-  b: { type: 'number', required: true, ... }
-}
-```
-
----
-
-## Step 4: Execute a Tool
-
-```typescript
-const result = await m.execute('calculator', {
-  operation: 'add',
-  a: 5,
-  b: 3
-});
-
-console.log('Result:', result);
-// Output: Result: { result: 8 }
-```
-
-### Execute Different Operations
-
-```typescript
-// Add
-const add = await m.execute('calculator', { operation: 'add', a: 10, b: 5 });
-console.log('10 + 5 =', add.result);  // 15
-
-// Subtract
-const sub = await m.execute('calculator', { operation: 'subtract', a: 10, b: 5 });
-console.log('10 - 5 =', sub.result);  // 5
-
-// Multiply
-const mul = await m.execute('calculator', { operation: 'multiply', a: 10, b: 5 });
-console.log('10 * 5 =', mul.result);  // 50
-
-// Divide
-const div = await m.execute('calculator', { operation: 'divide', a: 10, b: 5 });
-console.log('10 / 5 =', div.result);  // 2
-```
-
----
-
-## Step 5: Handle Errors
-
-```typescript
-try {
-  const result = await m.execute('calculator', {
-    operation: 'divide',
-    a: 10,
-    b: 0  // ⚠️ Invalid
-  });
-} catch (error) {
-  if (error.code === 'EXECUTION_FAILED') {
-    console.error('Tool execution failed:', error.message);
-  } else if (error.code === 'INVALID_PARAMETERS') {
-    console.error('Invalid parameters:', error.details);
-  } else {
-    console.error('Error:', error.message);
-  }
-}
-```
-
-See [Error Codes](../api-reference/ERRORS.md) for all possible errors.
-
----
-
-## Next Steps
-
-- **Learn SDK Patterns**: [Factory vs Decorator](../user-guide/SDK_PATTERNS.md)
-- **Find More Tools**: [Tool Discovery](../user-guide/TOOL_DISCOVERY.md)
-- **Use with LangChain**: [LangChain Integration](../framework-integrations/LANGCHAIN.md)
-- **Build Your Own Tools**: [YAML Tool Specification](../tool-development/YAML_TOOLS.md)
-
----
-
-## Complete Example
-
-```typescript
-import { matimo } from 'matimo';
-
-async function main() {
-  // 1. Initialize
-  const m = await matimo.init('./tools');
-  console.log(`✅ Loaded ${m.listTools().length} tools\n`);
-
-  // 2. List tools
-  const tools = m.listTools();
-  console.log('📦 Available tools:');
-  tools.forEach(t => console.log(`  - ${t.name}`));
-
-  // 3. Get tool
-  const calc = m.getTool('calculator');
-  console.log(`\n🔧 Tool: ${calc.name}`);
-
-  // 4. Execute
-  console.log('\n⚙️  Executing calculator...');
-  const result = await m.execute('calculator', {
-    operation: 'add',
-    a: 5,
-    b: 3
-  });
-  console.log('✅ Result:', result.result);
-}
-
-main().catch(console.error);
-```
-
-**Output:**
-```
-✅ Loaded 8 tools
-
-📦 Available tools:
-  - calculator
-  - gmail-send-email
-  - github-get-repo
-  ... (more tools)
-
-🔧 Tool: calculator
-
-⚙️ Executing calculator...
-✅ Result: 8
-```
-