@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/adapters/mistral-README.md

@@ -0,0 +1,367 @@
+# Mistral AI Adapter for OSSA
+
+Production-ready runtime adapter for executing OSSA agents using Mistral AI's API.
+
+## Features
+
+- ✅ **Full Mistral API Support**: All models including Mistral Large, Medium, Small, and Mixtral variants
+- ✅ **Function Calling**: Native support for Mistral's function calling capabilities
+- ✅ **Streaming**: Real-time streaming responses with tool execution
+- ✅ **Safety Controls**: Built-in safe mode and safe prompt options
+- ✅ **Multi-turn Conversations**: Automatic conversation history management
+- ✅ **Production Ready**: Comprehensive error handling, timeouts, and type safety
+
+## Supported Models
+
+| Model | ID | Context | Use Case |
+|-------|-----|---------|----------|
+| Mistral Large 2 | `mistral-large-latest` | 128K | Most capable, best for complex tasks |
+| Mistral Small | `mistral-small-latest` | 32K | Fast and cost-effective |
+| Mixtral 8x7B | `mixtral-8x7b-instruct-v0.1` | 32K | Open-source, efficient for most tasks |
+| Mixtral 8x22B | `mixtral-8x22b-instruct-v0.1` | 64K | Largest open model |
+
+## Installation
+
+```bash
+npm install @bluefly/openstandardagents
+```
+
+## Configuration
+
+Set your Mistral API key:
+
+```bash
+export MISTRAL_API_KEY=your-api-key-here
+```
+
+Or provide it in the manifest:
+
+```yaml
+extensions:
+  mistral:
+    api_key: ${MISTRAL_API_KEY}
+```
+
+## Quick Start
+
+### Basic Chat
+
+```typescript
+import { MistralAdapter } from '@bluefly/openstandardagents/dist/services/runtime/mistral.adapter.js';
+
+const manifest = {
+  apiVersion: 'ossa/v0.3.0',
+  kind: 'Agent',
+  metadata: {
+    name: 'my-agent',
+    version: '1.0.0'
+  },
+  spec: {
+    role: 'You are a helpful assistant.',
+    llm: {
+      provider: 'mistral',
+      model: 'mistral-large-latest'
+    }
+  }
+};
+
+const adapter = new MistralAdapter({ manifest });
+adapter.initialize();
+
+const response = await adapter.chat('Hello!');
+console.log(response);
+```
+
+### With Function Calling
+
+```typescript
+const manifest = {
+  apiVersion: 'ossa/v0.3.0',
+  kind: 'Agent',
+  metadata: {
+    name: 'weather-agent'
+  },
+  spec: {
+    role: 'You are a weather assistant.'
+  },
+  extensions: {
+    mistral: {
+      model: 'mistral-large-latest',
+      tools: [
+        {
+          type: 'function',
+          function: {
+            name: 'get_weather',
+            description: 'Get current weather',
+            parameters: {
+              type: 'object',
+              properties: {
+                location: {
+                  type: 'string',
+                  description: 'City name'
+                }
+              },
+              required: ['location']
+            }
+          }
+        }
+      ]
+    }
+  }
+};
+
+const adapter = new MistralAdapter({ manifest });
+adapter.initialize();
+
+// Register tool handler
+adapter.registerToolHandler('get_weather', async (args) => {
+  const weather = await fetchWeather(args.location);
+  return JSON.stringify(weather);
+});
+
+const response = await adapter.chat("What's the weather in Paris?", {
+  verbose: true
+});
+```
+
+### Streaming
+
+```typescript
+const adapter = new MistralAdapter({ manifest });
+adapter.initialize();
+
+for await (const chunk of adapter.chatStream('Write a haiku')) {
+  process.stdout.write(chunk);
+}
+```
+
+## Configuration Options
+
+### Manifest Extensions
+
+```yaml
+extensions:
+  mistral:
+    # Model selection
+    model: mistral-large-latest
+
+    # API credentials
+    api_key: ${MISTRAL_API_KEY}
+
+    # Generation parameters
+    temperature: 0.7        # 0.0 to 1.0
+    max_tokens: 4096        # Max output tokens
+    top_p: 0.95            # Nucleus sampling
+    random_seed: 42        # For reproducibility
+
+    # Safety controls
+    safe_mode: false       # Enable content filtering
+    safe_prompt: false     # Prepend safety instructions
+
+    # System prompt
+    system: "Custom system prompt"
+
+    # Function calling tools
+    tools:
+      - type: function
+        function:
+          name: tool_name
+          description: Tool description
+          parameters:
+            type: object
+            properties: {}
+```
+
+### Runtime Options
+
+```typescript
+interface MistralRunOptions {
+  verbose?: boolean;      // Log tool calls and turns
+  maxTurns?: number;      // Max conversation turns (default: 10)
+  stream?: boolean;       // Enable streaming
+}
+
+await adapter.chat('Message', {
+  verbose: true,
+  maxTurns: 5
+});
+```
+
+## Advanced Features
+
+### Multi-turn Conversations
+
+```typescript
+adapter.initialize();
+
+const response1 = await adapter.chat('What is JavaScript?');
+const response2 = await adapter.chat('Can you show an example?');
+// Context is automatically maintained
+
+// View history
+const history = adapter.getConversationHistory();
+
+// Clear history
+adapter.clearHistory();
+```
+
+### Error Handling
+
+```typescript
+try {
+  const response = await adapter.chat('Message');
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.error('Request timed out');
+  } else if (error.message.includes('API error')) {
+    console.error('Mistral API error');
+  }
+}
+```
+
+### Safe Mode
+
+```typescript
+const manifest = {
+  // ...
+  extensions: {
+    mistral: {
+      safe_mode: true,      // Enable content moderation
+      safe_prompt: true     // Add safety instructions
+    }
+  }
+};
+```
+
+### Reproducible Outputs
+
+```typescript
+const manifest = {
+  // ...
+  extensions: {
+    mistral: {
+      random_seed: 42,      // Same seed = same output
+      temperature: 0.0      // Deterministic sampling
+    }
+  }
+};
+```
+
+## API Reference
+
+### `MistralAdapter`
+
+#### Constructor
+
+```typescript
+new MistralAdapter(config: MistralAdapterConfig)
+```
+
+```typescript
+interface MistralAdapterConfig {
+  manifest: OssaAgent;
+  apiKey?: string;        // Optional, falls back to env
+  baseUrl?: string;       // Default: https://api.mistral.ai/v1
+  timeout?: number;       // Default: 60000ms
+}
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize()` | Initialize conversation with system prompt |
+| `chat(message, options?)` | Send message, get response (non-streaming) |
+| `chatStream(message, options?)` | Send message, get streaming response |
+| `registerToolHandler(name, handler)` | Register function tool handler |
+| `getAgentInfo()` | Get agent metadata |
+| `getConversationHistory()` | Get all messages |
+| `clearHistory()` | Reset conversation |
+| `getTools()` | Get registered tools |
+
+## Examples
+
+See comprehensive examples in:
+- `/examples/mistral-adapter-example.ts` - All features demonstrated
+- `/examples/adapters/mistral-agent.yaml` - YAML manifest example
+
+Run examples:
+
+```bash
+npm install
+npm run build
+node dist/examples/mistral-adapter-example.js
+```
+
+## Performance
+
+- **Non-streaming**: ~2-5s for typical responses
+- **Streaming**: First token in ~500ms
+- **Tool calling**: Adds ~1s per tool execution
+
+## Best Practices
+
+1. **Model Selection**
+   - Use `mistral-large-latest` for complex reasoning
+   - Use `mistral-small-latest` for simple tasks (faster, cheaper)
+   - Use `mixtral-8x7b` for open-source requirements
+
+2. **Temperature**
+   - 0.0-0.3: Factual, deterministic responses
+   - 0.5-0.7: Balanced creativity and consistency
+   - 0.8-1.0: Creative, diverse outputs
+
+3. **Function Calling**
+   - Always provide detailed descriptions
+   - Use strict JSON schemas
+   - Handle tool errors gracefully
+
+4. **Streaming**
+   - Use for long responses
+   - Better user experience
+   - Lower perceived latency
+
+5. **Error Handling**
+   - Set appropriate timeouts
+   - Retry failed requests
+   - Log errors for debugging
+
+## Troubleshooting
+
+### "Mistral API key is required"
+
+Set the environment variable:
+```bash
+export MISTRAL_API_KEY=your-key
+```
+
+Or provide in config:
+```typescript
+new MistralAdapter({ manifest, apiKey: 'your-key' })
+```
+
+### Request Timeout
+
+Increase timeout:
+```typescript
+new MistralAdapter({ manifest, timeout: 120000 }) // 2 minutes
+```
+
+### Content Filtered
+
+Enable safe mode explicitly or adjust prompts:
+```yaml
+extensions:
+  mistral:
+    safe_mode: false
+```
+
+## License
+
+Apache-2.0
+
+## Support
+
+- [OSSA Documentation](https://gitlab.com/blueflyio/openstandardagents/-/wikis/home)
+- [Mistral AI Documentation](https://docs.mistral.ai/)
+- [Report Issues](https://gitlab.com/blueflyio/openstandardagents/-/issues)

package/examples/adapters/mistral-agent.yaml

@@ -0,0 +1,147 @@
+apiVersion: ossa/v0.3.0
+kind: Agent
+metadata:
+  name: mistral-code-assistant
+  version: 1.0.0
+  description: Code review and analysis assistant using Mistral Large
+  labels:
+    provider: mistral
+    purpose: code-review
+    language: multi
+
+spec:
+  role: |
+    You are an expert code reviewer and software architect.
+    You provide detailed, constructive feedback on code quality, performance, and best practices.
+    You can analyze code in multiple programming languages and suggest improvements.
+
+  llm:
+    provider: mistral
+    model: mistral-large-latest
+    temperature: 0.3
+    maxTokens: 4096
+
+  tools:
+    - type: function
+      name: analyze_complexity
+      capabilities:
+        - code-analysis
+        - complexity-metrics
+      config:
+        max_depth: 10
+        metrics:
+          - cyclomatic
+          - cognitive
+          - halstead
+
+    - type: function
+      name: check_security
+      capabilities:
+        - security-scan
+        - vulnerability-detection
+
+extensions:
+  mistral:
+    # Mistral-specific configuration
+    model: mistral-large-latest
+    api_key: ${MISTRAL_API_KEY}
+    temperature: 0.3
+    max_tokens: 4096
+    top_p: 0.95
+    random_seed: 42
+    safe_mode: false
+
+    # Define tools in Mistral format
+    tools:
+      - type: function
+        function:
+          name: analyze_complexity
+          description: Analyze code complexity and generate metrics
+          parameters:
+            type: object
+            properties:
+              code:
+                type: string
+                description: The code to analyze
+              language:
+                type: string
+                description: Programming language (e.g., javascript, python, java)
+                enum: [javascript, python, java, go, rust, typescript]
+              metrics:
+                type: array
+                items:
+                  type: string
+                description: Metrics to calculate
+            required:
+              - code
+              - language
+
+      - type: function
+        function:
+          name: check_security
+          description: Scan code for security vulnerabilities and best practice violations
+          parameters:
+            type: object
+            properties:
+              code:
+                type: string
+                description: The code to scan
+              language:
+                type: string
+                description: Programming language
+              severity_threshold:
+                type: string
+                enum: [low, medium, high, critical]
+                description: Minimum severity level to report
+            required:
+              - code
+              - language
+
+      - type: function
+        function:
+          name: suggest_refactoring
+          description: Suggest code refactoring opportunities
+          parameters:
+            type: object
+            properties:
+              code:
+                type: string
+                description: The code to analyze
+              language:
+                type: string
+                description: Programming language
+              focus:
+                type: array
+                items:
+                  type: string
+                description: Areas to focus on
+                enum:
+                  - performance
+                  - readability
+                  - maintainability
+                  - testability
+            required:
+              - code
+              - language
+
+  # Observability
+  observability:
+    enabled: true
+    metrics:
+      - token_usage
+      - latency
+      - tool_calls
+    traces:
+      provider: opentelemetry
+      endpoint: http://localhost:4318/v1/traces
+
+  # Rate limiting
+  ratelimit:
+    requests_per_minute: 60
+    tokens_per_minute: 100000
+
+  # Caching
+  cache:
+    enabled: true
+    ttl: 3600
+    strategy: semantic

package/examples/adapters/symfony-messenger-task.yaml

@@ -0,0 +1,135 @@
+# Example: OSSA Task executed via Symfony Messenger
+# Demonstrates async task execution with queue-based processing
+apiVersion: ossa/v0.3.0
+kind: Task
+metadata:
+  name: send-email-symfony
+  version: 1.0.0
+  description: Send email using Symfony Mailer via Messenger
+  labels:
+    runtime: symfony
+    transport: messenger
+    domain: communication
+
+spec:
+  execution:
+    type: deterministic
+    runtime: symfony
+    entrypoint: "App\\TaskHandler\\SendEmailHandler::execute"
+    timeout_seconds: 30
+
+  capabilities:
+    - send_email
+    - render_template
+    - validate_email
+
+  input:
+    type: object
+    properties:
+      to:
+        type: string
+        format: email
+        description: Recipient email address
+      subject:
+        type: string
+        description: Email subject line
+      template:
+        type: string
+        description: Twig template name
+      variables:
+        type: object
+        description: Template variables
+        additionalProperties: true
+      attachments:
+        type: array
+        items:
+          type: object
+          properties:
+            filename:
+              type: string
+            content_type:
+              type: string
+            path:
+              type: string
+      priority:
+        type: string
+        enum: [low, normal, high]
+        default: normal
+    required:
+      - to
+      - subject
+      - template
+
+  output:
+    type: object
+    properties:
+      message_id:
+        type: string
+        description: Email message ID
+      sent_at:
+        type: string
+        format: date-time
+      status:
+        type: string
+        enum: [sent, queued, failed]
+      delivery_info:
+        type: object
+        properties:
+          transport:
+            type: string
+          queue_position:
+            type: integer
+
+  error_handling:
+    on_error: retry
+    retry:
+      max_attempts: 3
+      initial_delay_ms: 1000
+      backoff_strategy: exponential
+      retryable_errors:
+        - SMTP_TEMPORARY_ERROR
+        - CONNECTION_TIMEOUT
+        - RATE_LIMITED
+
+  observability:
+    logging:
+      level: info
+    metrics:
+      enabled: true
+      custom_labels:
+        email_type: "${{ input.template }}"
+        priority: "${{ input.priority }}"
+
+# Symfony-specific runtime bindings
+runtime:
+  type: symfony
+  bindings:
+    send_email:
+      service: "@Symfony\\Component\\Mailer\\MailerInterface"
+      method: "send"
+    render_template:
+      service: "@Twig\\Environment"
+      method: "render"
+    validate_email:
+      service: "@Symfony\\Component\\Validator\\Validator\\ValidatorInterface"
+      method: "validate"
+
+  # Messenger configuration
+  messenger:
+    transport: ossa_tasks
+    routing_key: email.send
+    priority: "${{ input.priority }}"
+    delay_ms: 0
+
+    # Message headers
+    headers:
+      X-OSSA-Task-Type: send-email
+      X-OSSA-Version: v0.3.0
+      X-Priority: "${{ input.priority }}"
+
+    # Retry configuration (overrides default)
+    retry:
+      max_retries: 3
+      delay: 1000
+      multiplier: 2
+      max_delay: 60000