@bluefly/openstandardagents 0.3.3 → 0.3.5

package/examples/migrations/langchain/INTEGRATION-EXAMPLE.txt

@@ -0,0 +1,335 @@
+LangChain to OSSA Migration - Complete Integration Example
+============================================================
+
+This example demonstrates the complete workflow of migrating a LangChain
+agent to OSSA format, including validation and testing.
+
+SCENARIO
+--------
+You have a Python LangChain ReAct agent that handles customer inquiries
+with access to search, knowledge base, and ticket creation tools.
+
+STEP 1: ORIGINAL LANGCHAIN CODE
+--------------------------------
+File: customer-service-agent.py
+
+```python
+from langchain.agents import initialize_agent, AgentType, Tool
+from langchain.chat_models import ChatOpenAI
+from langchain.memory import ConversationBufferMemory
+from langchain.tools import tool
+
+llm = ChatOpenAI(
+    model_name="gpt-4-turbo",
+    temperature=0.5,
+    max_tokens=2000
+)
+
+@tool
+def search_knowledge_base(query: str) -> str:
+    """Search company knowledge base for information."""
+    # Implementation
+    return f"Knowledge base results for: {query}"
+
+@tool
+def create_support_ticket(description: str, priority: str) -> str:
+    """Create a support ticket. Priority: low, medium, high, urgent."""
+    # Implementation
+    return f"Ticket created: {description} (Priority: {priority})"
+
+@tool
+def check_order_status(order_id: str) -> str:
+    """Check the status of an order by order ID."""
+    # Implementation
+    return f"Order {order_id} status: Shipped"
+
+tools = [search_knowledge_base, create_support_ticket, check_order_status]
+memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
+
+agent = initialize_agent(
+    tools=tools,
+    llm=llm,
+    agent=AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION,
+    memory=memory,
+    verbose=True
+)
+```
+
+STEP 2: RUN MIGRATION
+---------------------
+Command:
+  ossa migrate langchain customer-service-agent.py -v --report migration-report.json
+
+Output:
+  Migrating LangChain agent from customer-service-agent.py...
+
+  Migration Summary:
+    Source: customer-service-agent.py
+    Format: python
+    Target: customer-service-agent.ossa.yaml
+    Confidence: 95%
+
+  Mappings:
+    ✓ LangChain react Agent → OSSA Agent (kind: Agent)
+    ✓ LLM: openai/gpt-4-turbo → spec.llm configuration
+    ✓ Tool: search_knowledge_base → spec.tools[] entry
+    ✓ Tool: create_support_ticket → spec.tools[] entry
+    ✓ Tool: check_order_status → spec.tools[] entry
+    ✓ Memory: ConversationBufferMemory → extensions.langchain.memory_type
+
+  Recommendations:
+    • Review tool implementations and add proper schemas
+    • Consider implementing tools as MCP servers for better reusability
+    • Validate generated manifest with: ossa validate customer-service-agent.ossa.yaml
+    • Test the agent in a development environment
+
+  Validating manifest...
+  ✓ Manifest is valid
+
+  ✓ Manifest saved to: customer-service-agent.ossa.yaml
+  ✓ Report saved to: migration-report.json
+
+  Next Steps:
+    1. Review the generated manifest: customer-service-agent.ossa.yaml
+    2. Implement tool functions/endpoints
+    3. Test the agent: ossa run customer-service-agent.ossa.yaml
+
+STEP 3: GENERATED OSSA MANIFEST
+--------------------------------
+File: customer-service-agent.ossa.yaml
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: customer-service-agent
+  version: 0.1.0
+  description: Migrated from LangChain react agent
+  labels:
+    ossa-version: v0.3.3
+    migration-source: langchain
+    department: customer-support
+  annotations:
+    ossa.io/migration: langchain-to-ossa
+    ossa.io/migrated-date: "2026-01-15"
+    ossa.io/source-file: customer-service-agent.py
+spec:
+  role: |
+    You are a helpful customer service agent. You can:
+    - Search the knowledge base for company information
+    - Create support tickets for complex issues
+    - Check order status for customers
+
+    Always be polite, professional, and empathetic.
+
+  llm:
+    provider: openai
+    model: gpt-4-turbo
+    temperature: 0.5
+    maxTokens: 2000
+
+  tools:
+    - type: function
+      name: search_knowledge_base
+      description: Search company knowledge base for information.
+
+    - type: function
+      name: create_support_ticket
+      description: Create a support ticket. Priority - low, medium, high, urgent.
+
+    - type: function
+      name: check_order_status
+      description: Check the status of an order by order ID.
+
+  autonomy:
+    level: autonomous
+    approval_required: false
+
+  constraints:
+    cost:
+      maxTokensPerDay: 100000
+      maxCostPerDay: 50.0
+    performance:
+      maxLatencySeconds: 30
+
+  extensions:
+    langchain:
+      memory_type: ConversationBufferMemory
+      memory_config:
+        memory_key: chat_history
+        return_messages: true
+```
+
+STEP 4: MIGRATION REPORT
+------------------------
+File: migration-report.json
+
+```json
+{
+  "sourceFile": "customer-service-agent.py",
+  "sourceFormat": "python",
+  "targetManifest": "customer-service-agent.ossa.yaml",
+  "components": {
+    "detected": [
+      {
+        "type": "agent",
+        "agentType": "react",
+        "name": "ReAct Agent"
+      },
+      {
+        "type": "llm",
+        "llmConfig": {
+          "provider": "openai",
+          "model": "gpt-4-turbo",
+          "temperature": 0.5,
+          "maxTokens": 2000
+        }
+      },
+      {
+        "type": "tool",
+        "tools": [
+          {
+            "name": "search_knowledge_base",
+            "description": "Search company knowledge base for information.",
+            "type": "function"
+          },
+          {
+            "name": "create_support_ticket",
+            "description": "Create a support ticket. Priority: low, medium, high, urgent.",
+            "type": "function"
+          },
+          {
+            "name": "check_order_status",
+            "description": "Check the status of an order by order ID.",
+            "type": "function"
+          }
+        ]
+      },
+      {
+        "type": "memory",
+        "memory": {
+          "type": "ConversationBufferMemory"
+        }
+      }
+    ],
+    "mapped": [
+      {
+        "source": "LangChain react Agent",
+        "target": "OSSA Agent (kind: Agent)",
+        "confidence": "high"
+      },
+      {
+        "source": "LLM: openai/gpt-4-turbo",
+        "target": "spec.llm configuration",
+        "confidence": "high"
+      },
+      {
+        "source": "Tool: search_knowledge_base",
+        "target": "spec.tools[] entry",
+        "confidence": "high"
+      },
+      {
+        "source": "Tool: create_support_ticket",
+        "target": "spec.tools[] entry",
+        "confidence": "high"
+      },
+      {
+        "source": "Tool: check_order_status",
+        "target": "spec.tools[] entry",
+        "confidence": "high"
+      },
+      {
+        "source": "Memory: ConversationBufferMemory",
+        "target": "extensions.langchain.memory_type",
+        "confidence": "medium"
+      }
+    ],
+    "unmapped": []
+  },
+  "warnings": [
+    "Memory configuration requires manual verification and implementation"
+  ],
+  "recommendations": [
+    "Review tool implementations and add proper schemas",
+    "Consider implementing tools as MCP servers for better reusability",
+    "Validate generated manifest with: ossa validate customer-service-agent.ossa.yaml",
+    "Test the agent in a development environment"
+  ],
+  "confidence": 95,
+  "timestamp": "2026-01-15T10:30:00.000Z"
+}
+```
+
+STEP 5: VALIDATE THE MANIFEST
+-----------------------------
+Command:
+  ossa validate customer-service-agent.ossa.yaml
+
+Output:
+  ✓ Manifest is valid (ossa/v0.3.3)
+
+  Agent Details:
+    Name: customer-service-agent
+    Version: 0.1.0
+    Kind: Agent
+    Tools: 3
+    LLM: openai/gpt-4-turbo
+
+STEP 6: ENHANCE THE MANIFEST (OPTIONAL)
+---------------------------------------
+Add OpenAPI-style tool schemas for better type safety:
+
+```yaml
+spec:
+  tools:
+    - type: function
+      name: search_knowledge_base
+      description: Search company knowledge base
+      input_schema:
+        type: object
+        properties:
+          query:
+            type: string
+            description: Search query
+        required: [query]
+      output_schema:
+        type: object
+        properties:
+          results:
+            type: array
+            items:
+              type: object
+              properties:
+                title: { type: string }
+                content: { type: string }
+                relevance_score: { type: number }
+```
+
+STEP 7: TEST THE AGENT
+-----------------------
+Command:
+  ossa run customer-service-agent.ossa.yaml
+
+This demonstrates the complete migration workflow from LangChain to OSSA,
+including validation, enhancement, and testing.
+
+KEY BENEFITS
+------------
+1. Standardized Format: OSSA manifests are portable across frameworks
+2. Better Validation: OpenAPI-style schemas for tools
+3. Enhanced Features: Cost tracking, constraints, observability
+4. Kubernetes-style: Familiar apiVersion/kind/metadata/spec structure
+5. MCP Integration: Ready for Model Context Protocol tooling
+
+TROUBLESHOOTING
+---------------
+If migration confidence is low (<50%):
+- Check that the source file is valid LangChain code
+- Ensure LLM configuration is present
+- Verify tool definitions are properly decorated/defined
+- Review the migration report for specific issues
+
+For manual adjustments:
+- Use --dry-run to preview before writing
+- Edit the generated manifest as needed
+- Re-validate after changes: ossa validate <manifest>

package/examples/migrations/langchain/USAGE.txt

@@ -0,0 +1,121 @@
+LangChain to OSSA Migration Tool Usage
+========================================
+
+The LangChain migration tool converts LangChain agents (Python/TypeScript)
+and configuration files to OSSA manifests.
+
+SUPPORTED FORMATS
+-----------------
+- Python LangChain (.py)
+- TypeScript LangChain (.ts, .js)
+- JSON configuration (.json)
+- YAML configuration (.yaml, .yml)
+
+BASIC USAGE
+-----------
+ossa migrate langchain <source-file> [options]
+
+OPTIONS
+-------
+-o, --output <path>      Output path for migrated manifest
+--report <path>          Save migration report to file
+--format <json|yaml>     Report format (default: json)
+--validate               Validate generated manifest (default: true)
+--dry-run                Preview migration without writing files
+-v, --verbose            Verbose output
+
+EXAMPLES
+--------
+
+1. Migrate Python ReAct agent:
+   ossa migrate langchain 01-python-react-agent-before.py
+
+2. Migrate with custom output:
+   ossa migrate langchain agent.py -o my-agent.ossa.yaml
+
+3. Generate migration report:
+   ossa migrate langchain agent.ts --report migration-report.json
+
+4. Dry run (preview only):
+   ossa migrate langchain config.yaml --dry-run
+
+5. Verbose output:
+   ossa migrate langchain agent.py -v
+
+MAPPING RULES
+-------------
+LangChain Component         → OSSA Equivalent
+-------------------           ----------------
+Agent (ReAct, Zero-Shot)    → kind: Agent with spec.role
+Chain (Sequential)          → kind: Workflow
+Chain (Other)               → kind: Task
+Tool                        → spec.tools[] (function/http/mcp)
+Memory                      → extensions.langchain.memory_type
+LLM Config                  → spec.llm
+
+AUTONOMY LEVELS
+---------------
+ReAct agents        → autonomous
+Other agents        → assisted
+
+TESTING
+-------
+Run the test script:
+  npm run tsx examples/migrations/langchain/test-migrations.ts
+
+Or test individual examples:
+  ossa migrate langchain 01-python-react-agent-before.py
+  ossa validate 01-python-react-agent-after.ossa.yaml
+
+MIGRATION REPORT
+----------------
+The migration report includes:
+- Source file and format
+- Detected components
+- Mapping details with confidence scores
+- Unmapped features
+- Warnings
+- Recommendations
+
+Report confidence scores:
+- High (>80%): All major components mapped successfully
+- Medium (50-80%): Most components mapped, some manual work needed
+- Low (<50%): Significant manual work required
+
+COMMON ISSUES
+-------------
+1. Missing LLM config: Add LLM configuration manually
+2. Custom prompts: Add to spec.role description
+3. Memory configuration: Requires implementation verification
+4. Tool implementations: Need proper schemas and endpoints
+
+NEXT STEPS
+----------
+After migration:
+1. Review generated manifest
+2. Implement tool functions/endpoints
+3. Add proper schemas for tools
+4. Test the agent: ossa run <manifest>
+5. Consider converting tools to MCP servers for reusability
+
+EXAMPLES IN THIS DIRECTORY
+---------------------------
+1. 01-python-react-agent-before.py
+   Python ReAct agent with search, calculator, and weather tools
+   Includes memory configuration
+
+2. 02-typescript-conversational-before.ts
+   TypeScript conversational agent with email, calendar, and knowledge base tools
+   Uses OpenAI functions and memory
+
+3. 03-sequential-chain-before.py
+   Python sequential chain for document processing
+   Includes extraction, analysis, and summarization steps
+
+4. 04-config-based-before.yaml
+   YAML configuration for customer support agent
+   Shows config-based agent definition
+
+Each example includes:
+- -before file: Original LangChain code/config
+- -after.ossa.yaml: Expected OSSA manifest output

package/examples/migrations/langchain/test-migrations.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env tsx
+/**
+ * Test script to validate LangChain migrations
+ * Run: npm run tsx examples/migrations/langchain/test-migrations.ts
+ */
+
+import { LangChainMigrationService } from '../../../src/services/migration/langchain-migration.service.js';
+import { ValidationService } from '../../../src/services/validation.service.js';
+import { container } from '../../../src/di-container.js';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import chalk from 'chalk';
+
+const examplesDir = path.dirname(new URL(import.meta.url).pathname);
+
+const examples = [
+  {
+    name: 'Python ReAct Agent',
+    source: '01-python-react-agent-before.py',
+    expected: '01-python-react-agent-after.ossa.yaml',
+  },
+  {
+    name: 'TypeScript Conversational Agent',
+    source: '02-typescript-conversational-before.ts',
+    expected: '02-typescript-conversational-after.ossa.yaml',
+  },
+  {
+    name: 'Python Sequential Chain',
+    source: '03-sequential-chain-before.py',
+    expected: '03-sequential-chain-after.ossa.yaml',
+  },
+  {
+    name: 'YAML Config-based Agent',
+    source: '04-config-based-before.yaml',
+    expected: '04-config-based-after.ossa.yaml',
+  },
+];
+
+async function testMigrations() {
+  console.log(chalk.blue('Testing LangChain Migrations\n'));
+
+  const migrationService = new LangChainMigrationService();
+  const validationService = container.get(ValidationService);
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const example of examples) {
+    console.log(chalk.cyan(`Testing: ${example.name}`));
+    const sourcePath = path.join(examplesDir, example.source);
+
+    try {
+      // Check if source file exists
+      await fs.access(sourcePath);
+
+      // Perform migration
+      const { manifest, report } = await migrationService.migrate(sourcePath);
+
+      console.log(chalk.gray(`  Source: ${example.source}`));
+      console.log(chalk.gray(`  Format: ${report.sourceFormat}`));
+      console.log(chalk.gray(`  Components detected: ${report.components.detected.length}`));
+      console.log(chalk.gray(`  Mappings: ${report.components.mapped.length}`));
+      console.log(chalk.gray(`  Confidence: ${report.confidence}%`));
+
+      // Validate generated manifest
+      const validationResult = await validationService.validate(manifest, 'current');
+
+      if (!validationResult.valid) {
+        console.log(chalk.red(`  ✗ Validation failed`));
+        validationResult.errors.forEach((error) => {
+          console.log(chalk.red(`    - ${error.instancePath}: ${error.message}`));
+        });
+        failed++;
+      } else {
+        console.log(chalk.green(`  ✓ Manifest is valid`));
+
+        // Check key properties
+        const checks = [
+          { name: 'apiVersion', value: manifest.apiVersion },
+          { name: 'kind', value: manifest.kind },
+          { name: 'metadata.name', value: manifest.metadata?.name },
+          { name: 'spec.role', value: manifest.spec?.role },
+        ];
+
+        let allChecksPass = true;
+        checks.forEach((check) => {
+          if (!check.value) {
+            console.log(chalk.yellow(`  ⚠ Missing ${check.name}`));
+            allChecksPass = false;
+          }
+        });
+
+        if (allChecksPass) {
+          console.log(chalk.green(`  ✓ All required fields present`));
+          passed++;
+        } else {
+          failed++;
+        }
+      }
+
+      // Display warnings
+      if (report.warnings.length > 0) {
+        console.log(chalk.yellow(`  Warnings: ${report.warnings.length}`));
+        if (report.warnings.length <= 3) {
+          report.warnings.forEach((w) => console.log(chalk.yellow(`    - ${w}`)));
+        }
+      }
+
+      console.log('');
+    } catch (error) {
+      console.log(chalk.red(`  ✗ Migration failed: ${error instanceof Error ? error.message : String(error)}`));
+      failed++;
+      console.log('');
+    }
+  }
+
+  // Summary
+  console.log(chalk.blue('Summary:'));
+  console.log(chalk.green(`  Passed: ${passed}`));
+  console.log(chalk.red(`  Failed: ${failed}`));
+  console.log(chalk.gray(`  Total: ${examples.length}`));
+
+  if (failed === 0) {
+    console.log(chalk.green('\n✓ All migrations successful!'));
+    process.exit(0);
+  } else {
+    console.log(chalk.red('\n✗ Some migrations failed'));
+    process.exit(1);
+  }
+}
+
+testMigrations().catch((error) => {
+  console.error(chalk.red('Test script error:'), error);
+  process.exit(1);
+});

package/examples/multi-agent/conditional-router.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: conditional-router

package/examples/multi-agent/parallel-execution.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: parallel-executor

package/examples/multi-agent/sequential-pipeline.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: sequential-pipeline

package/examples/observability/activity-stream-full.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: activity-tracked-agent

package/examples/openai/basic-agent.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3.5
 kind: Agent
 metadata:
   name: basic-openai-agent

package/examples/openai/multi-tool-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.3.3",
+  "apiVersion": "ossa/v0.3",
   "kind": "Agent",
   "metadata": {
     "name": "multi-tool-agent",

package/examples/openai/swarm-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.3.3",
+  "apiVersion": "ossa/v0.3",
   "kind": "Agent",
   "metadata": {
     "name": "swarm-agent",

package/examples/ossa-templates/01-code-assistant.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: code-assistant

package/examples/ossa-templates/02-security-scanner.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: security-scanner

package/examples/ossa-templates/03-ci-pipeline.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: ci-pipeline

package/examples/ossa-templates/04-code-reviewer.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: code-reviewer

package/examples/ossa-templates/05-doc-generator.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: doc-generator

package/examples/ossa-templates/06-compliance-validator.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Agent
 metadata:
   name: compliance-validator

package/examples/ossa-templates/07-workflow-orchestrator.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.3
+apiVersion: ossa/v0.3
 kind: Workflow
 metadata:
   name: workflow-orchestrator