@bluefly/openstandardagents 0.4.0 → 0.4.1

package/examples/export/langchain/production-agent-with-tools/agent.ossa.yaml

@@ -0,0 +1,216 @@
+apiVersion: ossa/v0.4.1
+kind: Agent
+metadata:
+  name: production-agent-with-tools
+  version: 1.0.0
+  description: |
+    Production-ready agent with 6 tools showcasing v0.4.1 features:
+    - Async API calls
+    - Pydantic models for type validation
+    - MCP tool integration
+    - Production-quality error handling
+  labels:
+    platform: langchain
+    export: langchain
+    use-case: production-showcase
+    tier: production
+    version: v0.4.1
+
+spec:
+  role: |
+    You are a production assistant with multiple capabilities:
+    1. Search and analyze data
+    2. Make HTTP API calls
+    3. Execute MCP tools
+    4. Process text and generate reports
+    5. Send notifications
+
+  llm:
+    provider: openai
+    model: gpt-4o
+    temperature: 0.7
+    maxTokens: 2000
+
+  capabilities:
+    - search
+    - api_calls
+    - text_processing
+    - notifications
+    - mcp_tools
+
+  tools:
+    # API Tool - Async HTTP requests with Pydantic validation
+    - type: api
+      name: search_api
+      description: Search external knowledge base via REST API
+      endpoint: https://api.example.com/search
+      method: POST
+      parameters:
+        type: object
+        properties:
+          query:
+            type: string
+            description: Search query string
+          max_results:
+            type: integer
+            description: Maximum number of results
+            default: 10
+          filters:
+            type: object
+            description: Optional search filters
+        required:
+          - query
+
+    # Function Tool - Complex schema with Pydantic model
+    - type: function
+      name: analyze_text
+      description: Analyze text content and extract insights
+      parameters:
+        type: object
+        properties:
+          text:
+            type: string
+            description: Text content to analyze
+          analysis_types:
+            type: array
+            items:
+              type: string
+            description: Types of analysis (sentiment, entities, keywords)
+          language:
+            type: string
+            description: Language code (en, es, fr, etc.)
+            default: en
+          include_summary:
+            type: boolean
+            description: Include generated summary
+            default: true
+        required:
+          - text
+          - analysis_types
+
+    # Function Tool - Data processing with nested schema
+    - type: function
+      name: generate_report
+      description: Generate formatted report from data
+      parameters:
+        type: object
+        properties:
+          title:
+            type: string
+            description: Report title
+          sections:
+            type: array
+            items:
+              type: object
+            description: Report sections with content
+          format:
+            type: string
+            description: Output format
+            enum: [markdown, html, pdf]
+            default: markdown
+          include_charts:
+            type: boolean
+            description: Include data visualizations
+            default: false
+        required:
+          - title
+          - sections
+
+    # API Tool - Webhook notification
+    - type: api
+      name: send_notification
+      description: Send notification via webhook
+      endpoint: https://hooks.example.com/notify
+      method: POST
+      parameters:
+        type: object
+        properties:
+          message:
+            type: string
+            description: Notification message
+          priority:
+            type: string
+            enum: [low, medium, high, urgent]
+            description: Notification priority
+          channels:
+            type: array
+            items:
+              type: string
+            description: Notification channels (email, slack, sms)
+        required:
+          - message
+          - priority
+
+    # MCP Tool - Model Context Protocol integration
+    - type: mcp
+      name: mcp_database_query
+      description: Query database via MCP server
+      server: mcp-postgres-server
+      config:
+        server: mcp-postgres-server
+        timeout: 30
+      parameters:
+        type: object
+        properties:
+          query:
+            type: string
+            description: SQL query to execute
+          database:
+            type: string
+            description: Database name
+          read_only:
+            type: boolean
+            description: Execute in read-only mode
+            default: true
+        required:
+          - query
+          - database
+
+    # Function Tool - Simple tool without complex schema
+    - type: function
+      name: format_timestamp
+      description: Format timestamp to human-readable string
+      parameters:
+        type: object
+        properties:
+          timestamp:
+            type: integer
+            description: Unix timestamp
+          format:
+            type: string
+            description: Output format string
+            default: "%Y-%m-%d %H:%M:%S"
+          timezone:
+            type: string
+            description: Timezone (e.g., UTC, America/New_York)
+            default: UTC
+        required:
+          - timestamp
+
+  autonomy:
+    level: supervised
+    approval_required: false
+
+  memory:
+    enabled: true
+    type: conversation_buffer
+    window_size: 20
+
+  observability:
+    logging:
+      level: info
+      format: json
+    metrics:
+      enabled: true
+    tracing:
+      enabled: true
+      provider: opentelemetry
+
+extensions:
+  langchain:
+    agent_type: react
+    export_config:
+      format: python
+      include_dependencies: true
+      include_api_server: true
+      api_port: 8000

package/examples/export/langchain-export-example.ts

@@ -0,0 +1,246 @@
+/**
+ * LangChain Export Example
+ *
+ * Demonstrates complete LangChain export with:
+ * - Python agent code
+ * - FastAPI REST API
+ * - OpenAPI 3.1 specification
+ * - Docker containerization
+ * - Multiple memory backends
+ */
+
+import { LangChainExporter } from '../../src/services/export/langchain/index.js';
+import type { OssaAgent } from '../../src/types/index.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Example: Customer Support Bot
+ */
+const supportBotManifest: OssaAgent = {
+  apiVersion: 'ossa/v0.3.6',
+  kind: 'Agent',
+  metadata: {
+    name: 'support-bot',
+    version: '1.0.0',
+    description:
+      'Customer support agent with ticket creation and knowledge base search',
+    author: 'OSSA Team',
+    license: 'MIT',
+  },
+  spec: {
+    role: `You are a helpful customer support agent. Your responsibilities:
+
+1. Answer customer questions using the knowledge base
+2. Create support tickets for complex issues
+3. Escalate urgent matters to human agents
+4. Maintain a friendly, professional tone
+
+Always be helpful, clear, and empathetic.`,
+    llm: {
+      provider: 'openai',
+      model: 'gpt-4',
+      temperature: 0.7,
+      maxTokens: 2000,
+    },
+    tools: [
+      {
+        name: 'search_docs',
+        type: 'function',
+        description:
+          'Search the knowledge base for relevant documentation and FAQs',
+        input_schema: {
+          type: 'object',
+          properties: {
+            query: {
+              type: 'string',
+              description: 'Search query',
+            },
+            limit: {
+              type: 'integer',
+              description: 'Maximum number of results',
+              default: 5,
+            },
+          },
+          required: ['query'],
+        },
+      },
+      {
+        name: 'create_ticket',
+        type: 'function',
+        description:
+          'Create a support ticket for complex issues that require human attention',
+        input_schema: {
+          type: 'object',
+          properties: {
+            title: {
+              type: 'string',
+              description: 'Ticket title',
+            },
+            description: {
+              type: 'string',
+              description: 'Detailed description of the issue',
+            },
+            priority: {
+              type: 'string',
+              enum: ['low', 'medium', 'high', 'urgent'],
+              description: 'Ticket priority',
+              default: 'medium',
+            },
+          },
+          required: ['title', 'description'],
+        },
+      },
+      {
+        name: 'get_order_status',
+        type: 'api',
+        description: 'Get the current status of a customer order',
+        config: {
+          endpoint: 'https://api.example.com/orders/{order_id}',
+          method: 'GET',
+        },
+      },
+    ],
+  },
+};
+
+/**
+ * Export with all features enabled
+ */
+async function exportSupportBot() {
+  console.log('🚀 Exporting LangChain Support Bot...\n');
+
+  const exporter = new LangChainExporter();
+
+  const result = await exporter.export(supportBotManifest, {
+    pythonVersion: '3.11',
+    includeApi: true,
+    includeOpenApi: true,
+    includeDocker: true,
+    includeTests: true,
+    memoryBackend: 'redis',
+    apiPort: 8000,
+  });
+
+  if (!result.success) {
+    console.error('❌ Export failed:', result.error);
+    process.exit(1);
+  }
+
+  // Write files to output directory
+  const outputDir = path.join(process.cwd(), 'examples/export/output/support-bot');
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log('📝 Writing files:\n');
+
+  for (const file of result.files) {
+    const filePath = path.join(outputDir, file.path);
+    const fileDir = path.dirname(filePath);
+
+    if (!fs.existsSync(fileDir)) {
+      fs.mkdirSync(fileDir, { recursive: true });
+    }
+
+    fs.writeFileSync(filePath, file.content, 'utf-8');
+    console.log(`  ✅ ${file.path} (${file.type}, ${file.content.length} bytes)`);
+  }
+
+  console.log('\n✨ Export completed successfully!\n');
+  console.log('📊 Export Statistics:');
+  console.log(`  - Python Version: ${result.metadata?.pythonVersion}`);
+  console.log(`  - LangChain Version: ${result.metadata?.langchainVersion}`);
+  console.log(`  - Tools: ${result.metadata?.toolsCount}`);
+  console.log(`  - Memory: ${result.metadata?.memoryType}`);
+  console.log(`  - API: ${result.metadata?.hasApi ? 'Yes' : 'No'}`);
+  console.log(`  - OpenAPI: ${result.metadata?.hasOpenApi ? 'Yes' : 'No'}`);
+  console.log(`  - Duration: ${result.metadata?.duration}ms`);
+  console.log(`  - Files: ${result.files.length}`);
+
+  console.log('\n🚀 Next Steps:');
+  console.log(`  cd ${outputDir}`);
+  console.log(`  # Copy .env.example to .env and add your API keys`);
+  console.log(`  cp .env.example .env`);
+  console.log(`  # Run with Docker:`);
+  console.log(`  docker-compose up`);
+  console.log(`  # OR run locally:`);
+  console.log(`  pip install -r requirements.txt`);
+  console.log(`  uvicorn server:app --reload`);
+  console.log(`  # API docs at: http://localhost:8000/docs`);
+}
+
+/**
+ * Export with buffer memory (simple)
+ */
+async function exportSimpleAgent() {
+  console.log('\n📦 Exporting Simple Agent with Buffer Memory...\n');
+
+  const simpleManifest: OssaAgent = {
+    apiVersion: 'ossa/v0.3.6',
+    kind: 'Agent',
+    metadata: {
+      name: 'simple-agent',
+      version: '1.0.0',
+      description: 'Simple conversational agent',
+    },
+    spec: {
+      role: 'You are a helpful AI assistant.',
+      llm: {
+        provider: 'anthropic',
+        model: 'claude-3-sonnet-20240229',
+        temperature: 0.7,
+      },
+    },
+  };
+
+  const exporter = new LangChainExporter();
+
+  const result = await exporter.export(simpleManifest, {
+    memoryBackend: 'buffer',
+    includeApi: true,
+    includeDocker: true,
+  });
+
+  if (result.success) {
+    const outputDir = path.join(
+      process.cwd(),
+      'examples/export/output/simple-agent'
+    );
+
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    for (const file of result.files) {
+      const filePath = path.join(outputDir, file.path);
+      const fileDir = path.dirname(filePath);
+
+      if (!fs.existsSync(fileDir)) {
+        fs.mkdirSync(fileDir, { recursive: true });
+      }
+
+      fs.writeFileSync(filePath, file.content, 'utf-8');
+    }
+
+    console.log(`✅ Simple agent exported to: ${outputDir}`);
+    console.log(`   Files: ${result.files.length}`);
+  }
+}
+
+// Run examples
+async function main() {
+  try {
+    await exportSupportBot();
+    await exportSimpleAgent();
+  } catch (error) {
+    console.error('Error:', error);
+    process.exit(1);
+  }
+}
+
+// Execute if run directly
+if (import.meta.url.endsWith(process.argv[1])) {
+  main();
+}

package/examples/export/langserve-export-example.ts

@@ -0,0 +1,246 @@
+/**
+ * LangServe Export Example
+ *
+ * Demonstrates how to export an OSSA agent to a production-ready
+ * LangServe deployment with Docker, Kubernetes, and cloud platform configs.
+ */
+
+import { LangChainExporter } from '../../src/services/export/langchain/index.js';
+import type { OssaAgent } from '../../src/types/index.js';
+
+// Example OSSA manifest
+const manifest: OssaAgent = {
+  apiVersion: 'ossa.ai/v0.4.1',
+  kind: 'Agent',
+  metadata: {
+    name: 'customer-support-agent',
+    description: 'AI-powered customer support agent with LangServe deployment',
+    version: '1.0.0',
+    labels: {
+      'app.kubernetes.io/name': 'customer-support-agent',
+      'app.kubernetes.io/component': 'ai-agent',
+    },
+  },
+  spec: {
+    role: 'You are a helpful customer support agent. Assist users with their questions about products, orders, and services.',
+    llm: {
+      provider: 'openai',
+      model: 'gpt-4',
+      temperature: 0.7,
+      maxTokens: 2000,
+    },
+    tools: [
+      {
+        name: 'search_knowledge_base',
+        description: 'Search the knowledge base for information',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: {
+              type: 'string',
+              description: 'Search query',
+            },
+          },
+          required: ['query'],
+        },
+      },
+      {
+        name: 'create_ticket',
+        description: 'Create a support ticket',
+        parameters: {
+          type: 'object',
+          properties: {
+            title: {
+              type: 'string',
+              description: 'Ticket title',
+            },
+            description: {
+              type: 'string',
+              description: 'Ticket description',
+            },
+            priority: {
+              type: 'string',
+              enum: ['low', 'medium', 'high', 'urgent'],
+              description: 'Ticket priority',
+            },
+          },
+          required: ['title', 'description', 'priority'],
+        },
+      },
+    ],
+    memory: {
+      type: 'conversation-buffer',
+    },
+  },
+};
+
+async function exportToLangServe() {
+  const exporter = new LangChainExporter();
+
+  console.log('Exporting OSSA agent to LangServe deployment...\n');
+
+  // Export with LangServe support
+  const result = await exporter.export(manifest, {
+    pythonVersion: '3.11',
+    includeApi: true,
+    includeOpenApi: true,
+    includeDocker: true,
+    includeTests: true,
+    memoryBackend: 'buffer',
+    apiPort: 8000,
+
+    // Enable LangServe deployment
+    includeLangServe: true,
+
+    // LangServe configuration
+    langserve: {
+      enableFeedback: true,
+      enablePublicTraceLink: true,
+      enablePlayground: true,
+      routePath: '/agent',
+      port: 8000,
+      includeDeployment: true,
+      deploymentPlatforms: ['docker', 'kubernetes', 'railway', 'render', 'fly'],
+    },
+
+    // Observability
+    callbacks: {
+      langsmith: true,
+      langfuse: false,
+      opentelemetry: false,
+    },
+
+    // Error handling
+    errorHandling: {
+      retry: {
+        enabled: true,
+        maxRetries: 3,
+        backoffMultiplier: 2,
+      },
+      circuitBreaker: {
+        enabled: true,
+        failureThreshold: 5,
+        timeout: 60000,
+      },
+      fallback: {
+        useCachedResponses: true,
+      },
+    },
+  });
+
+  if (result.success) {
+    console.log('✓ Export successful!\n');
+    console.log(`Generated ${result.files.length} files:\n`);
+
+    // Group files by type
+    const filesByType = result.files.reduce(
+      (acc, file) => {
+        const type = file.type || 'other';
+        if (!acc[type]) acc[type] = [];
+        acc[type].push(file.path);
+        return acc;
+      },
+      {} as Record<string, string[]>
+    );
+
+    // Display files
+    for (const [type, files] of Object.entries(filesByType)) {
+      console.log(`${type.toUpperCase()}:`);
+      files.forEach((file) => console.log(`  - ${file}`));
+      console.log();
+    }
+
+    console.log('Metadata:');
+    console.log(`  Python Version: ${result.metadata?.pythonVersion}`);
+    console.log(`  LangChain Version: ${result.metadata?.langchainVersion}`);
+    console.log(`  Tools: ${result.metadata?.toolsCount}`);
+    console.log(`  Memory Backend: ${result.metadata?.memoryType}`);
+    console.log(`  Duration: ${result.metadata?.duration}ms`);
+    console.log();
+
+    // Display LangServe endpoints
+    console.log('LangServe Endpoints:');
+    console.log('  POST /agent/invoke - Synchronous invocation');
+    console.log('  POST /agent/batch - Batch processing');
+    console.log('  POST /agent/stream - Streaming responses (SSE)');
+    console.log('  POST /agent/stream_log - Detailed streaming');
+    console.log('  GET /agent/playground - Interactive playground UI');
+    console.log('  GET /docs - OpenAPI documentation');
+    console.log('  GET /health - Health check');
+    console.log();
+
+    // Display deployment options
+    console.log('Deployment Options:');
+    console.log('  1. Docker:');
+    console.log('     docker build -f Dockerfile.langserve -t customer-support-agent .');
+    console.log('     docker-compose -f docker-compose.langserve.yaml up');
+    console.log();
+    console.log('  2. Kubernetes:');
+    console.log('     kubectl apply -f k8s/');
+    console.log();
+    console.log('  3. Railway:');
+    console.log('     railway up');
+    console.log();
+    console.log('  4. Render:');
+    console.log('     Connect Git repo and deploy via render.yaml');
+    console.log();
+    console.log('  5. Fly.io:');
+    console.log('     fly launch && fly deploy');
+    console.log();
+
+    // Display file content preview for key files
+    console.log('Key Files Preview:\n');
+
+    const langserveApp = result.files.find((f) => f.path === 'langserve_app.py');
+    if (langserveApp) {
+      console.log('--- langserve_app.py (first 30 lines) ---');
+      console.log(langserveApp.content.split('\n').slice(0, 30).join('\n'));
+      console.log('...\n');
+    }
+
+    const deploymentReadme = result.files.find((f) => f.path === 'DEPLOYMENT.md');
+    if (deploymentReadme) {
+      console.log('--- DEPLOYMENT.md (first 40 lines) ---');
+      console.log(deploymentReadme.content.split('\n').slice(0, 40).join('\n'));
+      console.log('...\n');
+    }
+
+    // Usage examples
+    console.log('Usage Examples:\n');
+    console.log('Python Client:');
+    console.log('```python');
+    console.log('from langserve import RemoteRunnable');
+    console.log('');
+    console.log('agent = RemoteRunnable("http://localhost:8000/agent")');
+    console.log('result = agent.invoke("How do I track my order?")');
+    console.log('print(result)');
+    console.log('```\n');
+
+    console.log('JavaScript/TypeScript Client:');
+    console.log('```typescript');
+    console.log('import { RemoteRunnable } from "@langchain/core/runnables/remote";');
+    console.log('');
+    console.log('const agent = new RemoteRunnable({');
+    console.log('  url: "http://localhost:8000/agent"');
+    console.log('});');
+    console.log('const result = await agent.invoke("How do I return a product?");');
+    console.log('```\n');
+
+    console.log('cURL:');
+    console.log('```bash');
+    console.log('curl -X POST "http://localhost:8000/agent/invoke" \\');
+    console.log('  -H "Content-Type: application/json" \\');
+    console.log('  -d \'{"input": "What are your business hours?"}\'');
+    console.log('```\n');
+  } else {
+    console.error('✗ Export failed:');
+    console.error(result.error);
+    process.exit(1);
+  }
+}
+
+// Run example
+exportToLangServe().catch((error) => {
+  console.error('Error:', error);
+  process.exit(1);
+});