@bluefly/openstandardagents 0.4.0 → 0.4.2

package/examples/production/document-analyzer-openai.yml

@@ -1,7 +1,7 @@
 # OSSA Agent with OpenAI Bridge Configuration Example
 # Document Analyzer Agent - Proof of Concept
 
-apiVersion: ossa/v0.3.5
+apiVersion: ossa/v0.4.1
 kind: Agent
 metadata:
   name: document-analyzer

package/examples/production-ready/01-customer-support-bot/.env.example

@@ -0,0 +1,32 @@
+# OpenAI Configuration
+OPENAI_API_KEY=sk-...
+
+# Redis Configuration
+REDIS_URL=redis://localhost:6379
+
+# Server Configuration
+PORT=8080
+NODE_ENV=development
+
+# Logging
+LOG_LEVEL=info
+
+# Metrics
+METRICS_ENABLED=true
+METRICS_PORT=9090
+
+# Observability
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+TRACING_ENABLED=true
+
+# Rate Limiting
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW_MS=60000
+
+# Security
+ENABLE_PII_REDACTION=true
+ENABLE_INPUT_VALIDATION=true
+
+# Feature Flags
+ENABLE_TICKET_CREATION=true
+ENABLE_EMAIL_SENDING=true

package/examples/production-ready/01-customer-support-bot/Dockerfile

@@ -0,0 +1,30 @@
+FROM node:18-alpine AS base
+
+# Install Python for LangChain
+RUN apk add --no-cache python3 py3-pip
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY requirements.txt ./
+
+# Install dependencies
+RUN npm ci --only=production
+RUN pip3 install --no-cache-dir -r requirements.txt
+
+# Copy application
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Expose port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node healthcheck.js || exit 1
+
+# Run application
+CMD ["node", "dist/index.js"]

package/examples/production-ready/01-customer-support-bot/README.md

@@ -0,0 +1,295 @@
+# Customer Support Bot
+
+Production-ready customer support agent built with OSSA v0.3.6 and exported to LangChain.
+
+## Features
+
+- Multi-turn conversations with memory
+- Documentation search integration
+- Automated ticket creation
+- Email notifications
+- PII redaction and safety filters
+- OpenTelemetry observability
+- Redis-backed session persistence
+
+## Prerequisites
+
+- Docker and Docker Compose
+- Node.js 18+ (for local development)
+- Python 3.9+ (for LangChain)
+- OpenAI API key
+- Redis instance
+
+## Quick Start
+
+### Using Docker Compose (Recommended)
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=sk-...
+
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f customer-support-bot
+
+# Health check
+curl http://localhost:8080/v1/health
+```
+
+### Local Development
+
+```bash
+# Install dependencies
+npm install
+pip install -r requirements.txt
+
+# Set environment variables
+cp .env.example .env
+# Edit .env with your configuration
+
+# Build TypeScript
+npm run build
+
+# Start development server
+npm run dev
+```
+
+## Usage
+
+### Send a message
+
+```bash
+curl -X POST http://localhost:8080/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "How do I reset my password?",
+    "sessionId": "sess_123",
+    "userId": "user_456"
+  }'
+```
+
+### Get conversation history
+
+```bash
+curl http://localhost:8080/v1/session/sess_123/history
+```
+
+### Create a ticket
+
+```bash
+curl -X POST http://localhost:8080/v1/tickets \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Login issue",
+    "description": "Unable to access account after password reset",
+    "priority": "high",
+    "category": "technical"
+  }'
+```
+
+## OSSA Export
+
+This agent is defined in OSSA format and can be exported to multiple platforms:
+
+### Export to LangChain (Python)
+
+```bash
+ossa export agent.ossa.yaml --platform langchain --output customer_support.py
+```
+
+Generated file: `customer_support.py`
+
+```python
+from langchain.agents import create_react_agent
+from langchain_openai import ChatOpenAI
+from langchain.memory import ConversationBufferMemory
+from langchain.tools import Tool
+
+# Auto-generated from OSSA manifest
+class CustomerSupportAgent:
+    def __init__(self):
+        self.llm = ChatOpenAI(model="gpt-4o", temperature=0.7)
+        self.memory = ConversationBufferMemory(memory_key="chat_history")
+        self.tools = [
+            Tool(name="search_docs", func=self.search_docs, ...),
+            Tool(name="create_ticket", func=self.create_ticket, ...),
+            Tool(name="send_email", func=self.send_email, ...)
+        ]
+        self.agent = create_react_agent(self.llm, self.tools, ...)
+```
+
+### Export to LangChain (TypeScript)
+
+```bash
+ossa export agent.ossa.yaml --platform langchain-js --output customer-support.ts
+```
+
+### Export to npm package
+
+```bash
+ossa export agent.ossa.yaml --platform npm --output dist/
+```
+
+## Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────┐
+│   Express API       │
+│  (OpenAPI 3.1)      │
+└──────┬──────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│  OSSA Agent Runtime │
+│  - LangChain Agent  │
+│  - Memory Manager   │
+│  - Tool Executor    │
+└──────┬──────────────┘
+       │
+       ├───► Redis (Memory)
+       │
+       ├───► OpenAI (LLM)
+       │
+       └───► Tools (Docs, Tickets, Email)
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `OPENAI_API_KEY` | OpenAI API key | Yes |
+| `REDIS_URL` | Redis connection URL | Yes |
+| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No (default: info) |
+| `METRICS_ENABLED` | Enable Prometheus metrics | No (default: true) |
+| `NODE_ENV` | Environment (development, production) | No (default: development) |
+
+### Memory Configuration
+
+The agent uses conversation buffer memory with Redis persistence:
+
+```yaml
+memory:
+  type: conversation_buffer
+  window_size: 10          # Keep last 10 messages
+  persistence:
+    backend: redis
+    ttl: 86400            # 24 hours
+```
+
+### Safety Configuration
+
+Built-in safety features:
+
+- PII detection and redaction
+- Profanity filtering
+- Hallucination checking
+- Tone analysis
+
+## Monitoring
+
+### Metrics
+
+Access Prometheus metrics at `http://localhost:9090/metrics`:
+
+- `conversations_total` - Total conversations handled
+- `tickets_created` - Number of tickets created
+- `emails_sent` - Number of emails sent
+- `response_time` - Average response time
+
+### Logs
+
+Structured JSON logs are written to `./logs/`:
+
+```json
+{
+  "level": "info",
+  "timestamp": "2026-02-02T12:00:00Z",
+  "sessionId": "sess_123",
+  "action": "message_received",
+  "userId": "user_456"
+}
+```
+
+### Tracing
+
+OpenTelemetry traces are exported for distributed tracing.
+
+## Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Test OSSA manifest validation
+ossa validate agent.ossa.yaml
+```
+
+## Production Deployment
+
+### Kubernetes
+
+```bash
+# Apply Kubernetes manifests
+kubectl apply -f k8s/
+
+# Check deployment status
+kubectl get pods -l app=customer-support-bot
+
+# View logs
+kubectl logs -f deployment/customer-support-bot
+```
+
+### Scaling
+
+The agent is stateless (session data in Redis) and can be horizontally scaled:
+
+```bash
+docker-compose up -d --scale customer-support-bot=3
+```
+
+## Troubleshooting
+
+### Agent not responding
+
+Check Redis connection:
+```bash
+docker-compose logs redis
+redis-cli ping
+```
+
+### High latency
+
+Check OpenAI API status and rate limits:
+```bash
+curl -H "Authorization: Bearer $OPENAI_API_KEY" \
+  https://api.openai.com/v1/models
+```
+
+### Memory issues
+
+Clear Redis cache:
+```bash
+redis-cli FLUSHDB
+```
+
+## License
+
+Apache-2.0
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/org/repo/issues
+- Email: support@techcorp.com

package/examples/production-ready/01-customer-support-bot/agent.ossa.yaml

@@ -0,0 +1,172 @@
+apiVersion: ossa/v0.4.1
+kind: Agent
+metadata:
+  name: customer-support-bot
+  version: 1.0.0
+  description: |
+    Production customer support agent with memory, multi-channel support, and ticket creation.
+    Handles customer inquiries, searches documentation, creates tickets, and sends follow-up emails.
+  labels:
+    platform: langchain
+    export: langchain
+    use-case: customer-support
+    tier: production
+spec:
+  role: |
+    You are a professional customer support agent for TechCorp. Your responsibilities:
+
+    1. Answer customer questions accurately and professionally
+    2. Search documentation to provide accurate technical information
+    3. Create support tickets for issues requiring human intervention
+    4. Send follow-up emails to keep customers informed
+    5. Maintain conversation context to provide personalized support
+
+    Communication style:
+    - Professional, friendly, and empathetic
+    - Clear and concise explanations
+    - Proactive in offering solutions
+    - Transparent about limitations
+
+  llm:
+    provider: openai
+    model: gpt-4o
+    temperature: 0.7
+    maxTokens: 1500
+
+  capabilities:
+    - search_documentation
+    - create_ticket
+    - send_email
+    - conversation_memory
+
+  tools:
+    - type: function
+      name: search_docs
+      description: Search the knowledge base for relevant documentation
+      parameters:
+        type: object
+        properties:
+          query:
+            type: string
+            description: Search query for documentation
+          max_results:
+            type: integer
+            description: Maximum number of results to return
+            default: 5
+        required:
+          - query
+
+    - type: function
+      name: create_ticket
+      description: Create a support ticket for issues requiring human attention
+      parameters:
+        type: object
+        properties:
+          title:
+            type: string
+            description: Brief title of the issue
+          description:
+            type: string
+            description: Detailed description of the issue
+          priority:
+            type: string
+            enum: [low, medium, high, urgent]
+            description: Priority level of the ticket
+          category:
+            type: string
+            description: Category (billing, technical, account, etc.)
+        required:
+          - title
+          - description
+          - priority
+
+    - type: function
+      name: send_email
+      description: Send follow-up email to customer
+      parameters:
+        type: object
+        properties:
+          to:
+            type: string
+            description: Customer email address
+          subject:
+            type: string
+            description: Email subject line
+          body:
+            type: string
+            description: Email body content
+          template:
+            type: string
+            description: Email template to use
+            enum: [follow_up, resolution, escalation]
+        required:
+          - to
+          - subject
+          - body
+
+  autonomy:
+    level: supervised
+    approval_required: false
+    escalation_rules:
+      - condition: priority == 'urgent'
+        action: notify_human
+      - condition: ticket_count > 3
+        action: escalate
+
+  memory:
+    enabled: true
+    type: conversation_buffer
+    window_size: 10
+    persistence:
+      enabled: true
+      backend: redis
+      ttl: 86400
+
+  safety:
+    input_filters:
+      - type: pii_detection
+        action: redact
+      - type: profanity_filter
+        action: reject
+    output_validation:
+      - type: hallucination_check
+        threshold: 0.8
+      - type: tone_analysis
+        required_sentiment: [positive, neutral]
+
+  observability:
+    logging:
+      level: info
+      format: json
+      include_pii: false
+    metrics:
+      enabled: true
+      port: 9090
+      metrics:
+        - conversations_total
+        - tickets_created
+        - emails_sent
+        - response_time
+    tracing:
+      enabled: true
+      provider: opentelemetry
+
+extensions:
+  langchain:
+    agent_type: react
+    memory_type: conversation_buffer
+    chain_type: conversation
+    tools_mapping:
+      - ossa_capability: search_documentation
+        langchain_tool: search_docs
+        tool_class: CustomSearchTool
+      - ossa_capability: create_ticket
+        langchain_tool: create_ticket
+        tool_class: TicketingTool
+      - ossa_capability: send_email
+        langchain_tool: send_email
+        tool_class: EmailTool
+    export_config:
+      format: python
+      include_dependencies: true
+      output_file: customer_support_agent.py

package/examples/production-ready/01-customer-support-bot/docker-compose.yml

@@ -0,0 +1,55 @@
+version: '3.8'
+
+services:
+  customer-support-bot:
+    build: .
+    container_name: customer-support-bot
+    ports:
+      - "8080:8080"
+      - "9090:9090"  # Metrics
+    environment:
+      - NODE_ENV=production
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - REDIS_URL=redis://redis:6379
+      - LOG_LEVEL=info
+      - METRICS_ENABLED=true
+    depends_on:
+      - redis
+    restart: unless-stopped
+    networks:
+      - support-network
+    volumes:
+      - ./logs:/app/logs
+
+  redis:
+    image: redis:7-alpine
+    container_name: support-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    restart: unless-stopped
+    networks:
+      - support-network
+
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: support-prometheus
+    ports:
+      - "9091:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus-data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+    restart: unless-stopped
+    networks:
+      - support-network
+
+networks:
+  support-network:
+    driver: bridge
+
+volumes:
+  redis-data:
+  prometheus-data: