@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/rag-agent/index.ts

@@ -0,0 +1,272 @@
+/**
+ * RAG Agent Reference Implementation
+ * Demonstrates a Retrieval-Augmented Generation agent using @ossa/runtime
+ */
+
+import { createRuntime, OssaAgent } from '@ossa/runtime';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Vector store interface (simplified)
+ */
+interface VectorStore {
+  search(query: string, limit: number): Promise<Array<{
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+  }>>;
+  index(documents: Array<{ id: string; content: string; metadata?: Record<string, unknown> }>): Promise<void>;
+}
+
+/**
+ * Mock vector store implementation
+ */
+class MockVectorStore implements VectorStore {
+  private documents: Array<{
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+  }> = [];
+
+  async search(query: string, limit: number = 5) {
+    // Simple mock: return documents that contain query terms
+    const queryLower = query.toLowerCase();
+    return this.documents
+      .filter(doc => doc.content.toLowerCase().includes(queryLower))
+      .slice(0, limit)
+      .map(doc => ({
+        ...doc,
+        score: 0.9, // Mock score
+      }));
+  }
+
+  async index(documents: Array<{ id: string; content: string; metadata?: Record<string, unknown> }>) {
+    this.documents.push(...documents);
+  }
+}
+
+/**
+ * RAG Agent implementation
+ */
+export async function createRagAgent(): Promise<OssaAgent> {
+  const runtime = createRuntime();
+
+  // Load agent manifest
+  const manifestPath = join(__dirname, 'manifest.yaml');
+  const agent = await runtime.loadAgent(manifestPath);
+
+  // Initialize vector store
+  const vectorStore = new MockVectorStore();
+
+  // Seed with sample documents
+  await vectorStore.index([
+    {
+      id: 'doc1',
+      content: 'OSSA (Open Standard for Scalable AI Agents) is a specification standard for AI agents, similar to OpenAPI for REST APIs.',
+      metadata: { category: 'documentation' }
+    },
+    {
+      id: 'doc2',
+      content: 'The OSSA runtime SDK provides reference implementations for executing OSSA-compliant agents.',
+      metadata: { category: 'documentation' }
+    },
+    {
+      id: 'doc3',
+      content: 'RAG (Retrieval-Augmented Generation) combines information retrieval with language generation.',
+      metadata: { category: 'concepts' }
+    },
+    {
+      id: 'doc4',
+      content: 'Vector databases enable semantic search by storing and querying high-dimensional embeddings.',
+      metadata: { category: 'technology' }
+    }
+  ]);
+
+  // Register search capability
+  agent.registerCapability(
+    {
+      name: 'search',
+      description: 'Search documents using semantic search',
+      input_schema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Search query' },
+          limit: { type: 'number', description: 'Maximum results', default: 5 }
+        },
+        required: ['query']
+      },
+      output_schema: {
+        type: 'object',
+        properties: {
+          results: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                content: { type: 'string' },
+                score: { type: 'number' },
+                metadata: { type: 'object' }
+              }
+            }
+          }
+        }
+      },
+      timeout_seconds: 5
+    },
+    async (input: { query: string; limit?: number }) => {
+      const results = await vectorStore.search(input.query, input.limit || 5);
+      return { results };
+    }
+  );
+
+  // Register answer capability
+  agent.registerCapability(
+    {
+      name: 'answer',
+      description: 'Answer questions using RAG pattern',
+      input_schema: {
+        type: 'object',
+        properties: {
+          question: { type: 'string', description: 'Question to answer' },
+          context_limit: { type: 'number', description: 'Max context documents', default: 3 }
+        },
+        required: ['question']
+      },
+      output_schema: {
+        type: 'object',
+        properties: {
+          answer: { type: 'string' },
+          sources: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                content: { type: 'string' },
+                score: { type: 'number' }
+              }
+            }
+          }
+        }
+      },
+      timeout_seconds: 10
+    },
+    async (input: { question: string; context_limit?: number }) => {
+      // Search for relevant documents
+      const searchResults = await vectorStore.search(input.question, input.context_limit || 3);
+
+      // Build context from search results
+      const context = searchResults
+        .map(r => r.content)
+        .join('\n\n');
+
+      // Generate answer (mock implementation)
+      const answer = `Based on the documents: ${context}\n\nAnswer: ${input.question}`;
+
+      return {
+        answer,
+        sources: searchResults.map(r => ({
+          id: r.id,
+          content: r.content,
+          score: r.score
+        }))
+      };
+    }
+  );
+
+  // Register index capability
+  agent.registerCapability(
+    {
+      name: 'index',
+      description: 'Index new documents into the vector store',
+      input_schema: {
+        type: 'object',
+        properties: {
+          documents: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                content: { type: 'string' },
+                metadata: { type: 'object' }
+              },
+              required: ['id', 'content']
+            }
+          }
+        },
+        required: ['documents']
+      },
+      output_schema: {
+        type: 'object',
+        properties: {
+          indexed: { type: 'number' }
+        }
+      },
+      timeout_seconds: 30
+    },
+    async (input: { documents: Array<{ id: string; content: string; metadata?: Record<string, unknown> }> }) => {
+      await vectorStore.index(input.documents);
+      return { indexed: input.documents.length };
+    }
+  );
+
+  return agent;
+}
+
+/**
+ * Example usage
+ */
+async function main() {
+  console.log('🤖 RAG Agent Example\n');
+
+  // Create and initialize agent
+  const agent = await createRagAgent();
+  console.log('✅ Agent loaded:', agent.getMetadata().name);
+
+  // Test search capability
+  console.log('\n📚 Testing search capability...');
+  const searchResult = await agent.execute('search', { query: 'OSSA', limit: 2 });
+  if (searchResult.success) {
+    console.log('Search results:', JSON.stringify(searchResult.data, null, 2));
+  }
+
+  // Test answer capability
+  console.log('\n💬 Testing answer capability...');
+  const answerResult = await agent.execute('answer', {
+    question: 'What is OSSA?',
+    context_limit: 2
+  });
+  if (answerResult.success) {
+    console.log('Answer:', JSON.stringify(answerResult.data, null, 2));
+  }
+
+  // Test index capability
+  console.log('\n📥 Testing index capability...');
+  const indexResult = await agent.execute('index', {
+    documents: [
+      {
+        id: 'doc5',
+        content: 'The @ossa/runtime package provides TypeScript implementations for OSSA agents.',
+        metadata: { category: 'sdk' }
+      }
+    ]
+  });
+  if (indexResult.success) {
+    console.log('Indexed documents:', indexResult.data);
+  }
+
+  console.log('\n✨ All capabilities tested successfully!');
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}

package/examples/rag-agent/manifest.yaml

@@ -0,0 +1,45 @@
+apiVersion: v0.3.0
+kind: Agent
+metadata:
+  name: rag-agent
+  version: 1.0.0
+  description: Retrieval-Augmented Generation agent for document search and question answering
+  labels:
+    type: rag
+    domain: knowledge-management
+    tier: production
+spec:
+  role: Document search and question answering using RAG pattern
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+    maxTokens: 2000
+  tools:
+    - type: mcp
+      name: vector-search
+      endpoint: http://localhost:6333
+      capabilities:
+        - search
+        - index
+        - delete
+    - type: mcp
+      name: embeddings
+      endpoint: http://localhost:11434
+      capabilities:
+        - embed
+  autonomy:
+    level: assisted
+    approval_required: false
+    allowed_actions:
+      - search_documents
+      - generate_embeddings
+      - answer_question
+  constraints:
+    cost:
+      maxTokensPerDay: 100000
+      maxTokensPerRequest: 2000
+    performance:
+      maxLatencySeconds: 5
+      maxConcurrentRequests: 10
+      timeoutSeconds: 30

package/examples/real-world/gitlab-cicd-optimizer.ossa.yaml

@@ -0,0 +1,163 @@
+apiVersion: ossa/v0.3.0
+kind: Agent
+metadata:
+  name: gitlab-cicd-optimizer
+  description: |
+    Real-world agent that optimizes GitLab CI/CD pipelines by:
+    - Analyzing pipeline performance
+    - Identifying slow jobs
+    - Suggesting parallelization opportunities
+    - Detecting unused cache keys
+    - Recommending resource optimizations
+  labels:
+    use-case: ci-cd-optimization
+    platform: gitlab
+    tier: production
+spec:
+  role: analyzer
+  capabilities:
+    - gitlab-api
+    - performance-analysis
+    - recommendation-engine
+  
+  # Trigger on pipeline completion
+  triggers:
+    - type: webhook
+      source: gitlab
+      events: [pipeline_success, pipeline_failed]
+      filter:
+        branches: [main, release/*]
+  
+  # Input: Pipeline data from GitLab webhook
+  inputs:
+    - name: pipeline_data
+      type: object
+      required: true
+      schema:
+        project_id: string
+        pipeline_id: integer
+        duration: integer
+        jobs: array
+  
+  # Analysis tasks
+  tasks:
+    - name: analyze-performance
+      description: Analyze pipeline performance metrics
+      steps:
+        - name: fetch-pipeline-details
+          action: http
+          method: GET
+          url: "https://gitlab.com/api/v4/projects/${inputs.pipeline_data.project_id}/pipelines/${inputs.pipeline_data.pipeline_id}"
+          headers:
+            PRIVATE-TOKEN: "${env.GITLAB_TOKEN}"
+        
+        - name: identify-slow-jobs
+          action: analyze
+          logic: |
+            # Find jobs taking >5 minutes
+            slow_jobs = []
+            for job in pipeline.jobs:
+              if job.duration > 300:
+                slow_jobs.append({
+                  'name': job.name,
+                  'duration': job.duration,
+                  'stage': job.stage
+                })
+            return slow_jobs
+        
+        - name: detect-parallelization
+          action: analyze
+          logic: |
+            # Find sequential jobs that could run in parallel
+            stages = group_by(pipeline.jobs, 'stage')
+            opportunities = []
+            for stage, jobs in stages.items():
+              if len(jobs) == 1 and jobs[0].duration > 180:
+                opportunities.append({
+                  'stage': stage,
+                  'suggestion': 'Split into parallel jobs'
+                })
+            return opportunities
+        
+        - name: check-cache-usage
+          action: analyze
+          logic: |
+            # Detect unused cache keys
+            cache_keys = set()
+            used_keys = set()
+            for job in pipeline.jobs:
+              if job.cache:
+                cache_keys.add(job.cache.key)
+              if job.cache_hit:
+                used_keys.add(job.cache.key)
+            unused = cache_keys - used_keys
+            return list(unused)
+    
+    - name: generate-recommendations
+      description: Create actionable recommendations
+      steps:
+        - name: create-report
+          action: template
+          template: |
+            ## 🚀 CI/CD Optimization Report
+            
+            **Pipeline**: #${inputs.pipeline_data.pipeline_id}
+            **Duration**: ${inputs.pipeline_data.duration}s
+            
+            ### ⚠️ Slow Jobs (>5min)
+            {% for job in analysis.slow_jobs %}
+            - **${job.name}** (${job.stage}): ${job.duration}s
+              - Consider: Caching dependencies, using smaller Docker images
+            {% endfor %}
+            
+            ### ⚡ Parallelization Opportunities
+            {% for opp in analysis.parallelization %}
+            - **${opp.stage}**: ${opp.suggestion}
+            {% endfor %}
+            
+            ### 🗑️ Unused Cache Keys
+            {% for key in analysis.unused_cache %}
+            - `${key}` - Consider removing to save storage
+            {% endfor %}
+            
+            ### 💡 Recommendations
+            1. Enable `interruptible: true` for non-critical jobs
+            2. Use `needs:` to create DAG pipelines
+            3. Consider using GitLab's merge trains
+            4. Review resource allocation for slow jobs
+        
+        - name: post-comment
+          action: http
+          method: POST
+          url: "https://gitlab.com/api/v4/projects/${inputs.pipeline_data.project_id}/merge_requests/${inputs.pipeline_data.merge_request_iid}/notes"
+          headers:
+            PRIVATE-TOKEN: "${env.GITLAB_TOKEN}"
+          body:
+            body: "${outputs.report}"
+  
+  # Outputs
+  outputs:
+    - name: report
+      type: markdown
+      description: Optimization report
+    - name: metrics
+      type: object
+      schema:
+        slow_jobs_count: integer
+        parallelization_opportunities: integer
+        unused_cache_keys: integer
+        total_duration: integer
+  
+  # Observability
+  observability:
+    tracing:
+      enabled: true
+      provider: opentelemetry
+      endpoint: "${env.OTEL_ENDPOINT}"
+    metrics:
+      - name: pipelines_analyzed
+        type: counter
+      - name: recommendations_generated
+        type: counter
+      - name: average_pipeline_duration
+        type: gauge

package/examples/real-world/rag-documentation-assistant.ossa.yaml

@@ -0,0 +1,235 @@
+apiVersion: ossa/v0.3.0
+kind: Agent
+metadata:
+  name: rag-documentation-assistant
+  description: |
+    Production RAG agent that answers questions about your codebase using:
+    - Vector embeddings of documentation
+    - Semantic search across code comments
+    - Context-aware responses with citations
+    - Automatic knowledge base updates on commits
+  labels:
+    use-case: documentation-qa
+    pattern: rag
+    tier: production
+spec:
+  role: assistant
+  capabilities:
+    - vector-search
+    - llm-generation
+    - document-processing
+  
+  # Knowledge sources (OSSA v0.3.0 extension)
+  extensions:
+    knowledge_sources:
+      - name: codebase-docs
+        type: vector_store
+        provider: qdrant
+        config:
+          collection: "documentation"
+          embedding_model: "text-embedding-3-small"
+          endpoint: "${env.QDRANT_URL}"
+      - name: api-specs
+        type: structured
+        provider: openapi
+        config:
+          specs:
+            - path: "./openapi.yaml"
+            - url: "https://api.example.com/openapi.json"
+  
+  # Trigger on Slack mention or API call
+  triggers:
+    - type: webhook
+      source: slack
+      events: [app_mention]
+    - type: api
+      endpoint: /ask
+      method: POST
+  
+  # Input: User question
+  inputs:
+    - name: question
+      type: string
+      required: true
+      description: "User's question about the codebase"
+    - name: context
+      type: object
+      required: false
+      schema:
+        user_id: string
+        channel_id: string
+        thread_ts: string
+  
+  # RAG pipeline tasks
+  tasks:
+    - name: retrieve-context
+      description: Find relevant documentation chunks
+      steps:
+        - name: embed-question
+          action: llm
+          provider: openai
+          model: text-embedding-3-small
+          input: "${inputs.question}"
+          output_var: question_embedding
+        
+        - name: vector-search
+          action: vector_search
+          source: codebase-docs
+          query: "${outputs.question_embedding}"
+          top_k: 5
+          min_score: 0.7
+          output_var: relevant_docs
+        
+        - name: rerank-results
+          action: rerank
+          model: cohere-rerank-v3
+          query: "${inputs.question}"
+          documents: "${outputs.relevant_docs}"
+          top_n: 3
+          output_var: top_docs
+    
+    - name: generate-answer
+      description: Generate contextual answer with citations
+      steps:
+        - name: build-prompt
+          action: template
+          template: |
+            You are a helpful documentation assistant. Answer the user's question using ONLY the provided context.
+            If the context doesn't contain the answer, say so clearly.
+            
+            Context:
+            {% for doc in context.top_docs %}
+            [Source: ${doc.metadata.file}:${doc.metadata.line}]
+            ${doc.content}
+            
+            {% endfor %}
+            
+            Question: ${inputs.question}
+            
+            Answer with citations in the format [1], [2], etc.
+          output_var: prompt
+        
+        - name: call-llm
+          action: llm
+          provider: openai
+          model: gpt-4-turbo
+          temperature: 0.3
+          max_tokens: 500
+          messages:
+            - role: system
+              content: "You are a precise documentation assistant."
+            - role: user
+              content: "${outputs.prompt}"
+          output_var: answer
+        
+        - name: format-response
+          action: template
+          template: |
+            ${outputs.answer}
+            
+            ---
+            **Sources:**
+            {% for doc in context.top_docs %}
+            [${loop.index}] `${doc.metadata.file}` (line ${doc.metadata.line})
+            {% endfor %}
+          output_var: formatted_answer
+    
+    - name: respond
+      description: Send answer back to user
+      steps:
+        - name: post-to-slack
+          action: http
+          method: POST
+          url: "https://slack.com/api/chat.postMessage"
+          headers:
+            Authorization: "Bearer ${env.SLACK_BOT_TOKEN}"
+          body:
+            channel: "${inputs.context.channel_id}"
+            thread_ts: "${inputs.context.thread_ts}"
+            text: "${outputs.formatted_answer}"
+          condition: "${inputs.context.channel_id != null}"
+        
+        - name: return-api-response
+          action: return
+          value:
+            answer: "${outputs.formatted_answer}"
+            sources: "${outputs.top_docs}"
+            confidence: "${outputs.top_docs[0].score}"
+  
+  # Background task: Update knowledge base on commits
+  background_tasks:
+    - name: update-knowledge-base
+      schedule: "*/30 * * * *"  # Every 30 minutes
+      steps:
+        - name: fetch-recent-commits
+          action: http
+          method: GET
+          url: "https://gitlab.com/api/v4/projects/${env.PROJECT_ID}/repository/commits"
+          headers:
+            PRIVATE-TOKEN: "${env.GITLAB_TOKEN}"
+          params:
+            since: "${now() - 30m}"
+        
+        - name: extract-changed-docs
+          action: filter
+          input: "${outputs.commits}"
+          condition: "file.path.endsWith('.md') or file.path.endsWith('.rst')"
+        
+        - name: process-and-embed
+          action: foreach
+          items: "${outputs.changed_docs}"
+          steps:
+            - name: fetch-content
+              action: http
+              method: GET
+              url: "https://gitlab.com/api/v4/projects/${env.PROJECT_ID}/repository/files/${item.path}/raw"
+            
+            - name: chunk-document
+              action: chunk
+              content: "${outputs.content}"
+              chunk_size: 500
+              overlap: 50
+            
+            - name: embed-chunks
+              action: llm
+              provider: openai
+              model: text-embedding-3-small
+              input: "${outputs.chunks}"
+            
+            - name: upsert-vectors
+              action: vector_store
+              operation: upsert
+              collection: codebase-docs
+              vectors: "${outputs.embeddings}"
+              metadata:
+                file: "${item.path}"
+                commit: "${item.commit_id}"
+                updated_at: "${now()}"
+  
+  # Outputs
+  outputs:
+    - name: answer
+      type: string
+      description: "Generated answer with citations"
+    - name: sources
+      type: array
+      description: "Source documents used"
+    - name: confidence
+      type: float
+      description: "Confidence score (0-1)"
+  
+  # Observability
+  observability:
+    tracing:
+      enabled: true
+      provider: opentelemetry
+    metrics:
+      - name: questions_answered
+        type: counter
+        labels: [user_id, confidence_bucket]
+      - name: retrieval_latency
+        type: histogram
+      - name: generation_latency
+        type: histogram
+      - name: knowledge_base_size
+        type: gauge