@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/spec/v0.2.5-RC/ossa-0.2.5-RC.yaml

@@ -0,0 +1,581 @@
+ossaVersion: '0.2.5-RC'
+
+# OSSA (Open Standard for Smart & Scalable Agents) - Version 0.2.5-RC
+# The OpenAPI for AI Agents
+#
+# RELEASE CANDIDATE - APIs and schemas may change before final release
+#
+# This specification defines a standard format for AI agent definition,
+# deployment, and orchestration across heterogeneous environments.
+#
+# v0.2.5-RC NEW FEATURES:
+# - Transport metadata for capabilities (streaming, protocol binding)
+# - State/memory block for agent state management
+# - Enhanced security with scopes and compliance tags
+# - Capability versioning and deprecation support
+# - Google ADK extension for Agent Development Kit integration
+
+spec:
+  title: OSSA 0.2.5-RC Specification
+  description: Open Standard for Smart & Scalable Agents - Release Candidate
+  version: '0.2.5-RC'
+  status: development
+  license: Apache-2.0
+  maintainer: OSSA Working Group
+  website: https://openstandardagents.org
+  repository: https://github.com/ossa-standard/specification
+
+# ==============================================================================
+# NEW IN v0.2.5: Transport Metadata
+# ==============================================================================
+# Transport configuration for protocol-specific settings
+# Supports ADK, A2A, MCP, and other protocols with streaming
+
+transport:
+  description: |
+    Transport metadata defines how capabilities communicate over different protocols.
+    This is essential for:
+    - Google ADK bidirectional streaming
+    - A2A protocol agent-to-agent communication
+    - MCP tool server integration
+    - gRPC streaming services
+
+  schema:
+    protocol:
+      type: enum
+      values: [http, grpc, a2a, mcp, websocket, custom]
+      description: Transport protocol for the capability
+
+    streaming:
+      type: enum
+      values: [none, request, response, bidirectional]
+      default: none
+      description: |
+        Streaming mode:
+        - none: Standard request/response
+        - request: Client streams to server
+        - response: Server streams to client (SSE, streaming LLM)
+        - bidirectional: Full duplex (WebSocket, gRPC bidirectional)
+
+    binding:
+      type: string
+      description: |
+        Path or endpoint binding specific to the protocol:
+        - HTTP: "/api/v1/chat"
+        - gRPC: "myservice.MyMethod"
+        - MCP: Tool name
+        - A2A: Action path
+
+    content_type:
+      type: string
+      examples:
+        - application/json
+        - application/x-ndjson  # For streaming
+        - text/event-stream    # For SSE
+
+  examples:
+    # HTTP streaming response (common for LLM)
+    - protocol: http
+      streaming: response
+      binding: /api/v1/chat/stream
+      content_type: text/event-stream
+
+    # gRPC bidirectional (for real-time agents)
+    - protocol: grpc
+      streaming: bidirectional
+      binding: AgentService.StreamChat
+
+    # A2A protocol
+    - protocol: a2a
+      streaming: none
+      binding: /tasks/send
+
+    # MCP tool
+    - protocol: mcp
+      streaming: none
+      binding: query_database
+
+# ==============================================================================
+# NEW IN v0.2.5: State/Memory Block
+# ==============================================================================
+# Agent state management configuration
+# Essential for OpenAI SDK, Microsoft Autogen Framework, and long-running agents
+
+state:
+  description: |
+    State configuration defines how an agent manages memory and context.
+    Critical for:
+    - Session continuity (OpenAI Agents SDK)
+    - Long-running workflows (MS Autogen Framework)
+    - RAG systems with context retention
+    - Multi-turn conversations
+
+  schema:
+    mode:
+      type: enum
+      values: [stateless, session, long_running]
+      default: stateless
+      description: |
+        State management mode:
+        - stateless: No state between requests
+        - session: State retained for session duration
+        - long_running: Persistent state across sessions
+
+    storage:
+      type: object
+      properties:
+        type:
+          type: enum
+          values: [memory, vector-db, kv, rdbms, custom]
+          default: memory
+          description: |
+            Storage backend:
+            - memory: In-process (lost on restart)
+            - vector-db: Vector database (Pinecone, Weaviate, etc.)
+            - kv: Key-value store (Redis, DynamoDB)
+            - rdbms: Relational database
+            - custom: Custom implementation
+
+        retention:
+          type: string
+          examples: [24h, 7d, 30d, 1y, forever]
+          description: How long to retain state
+
+        config:
+          type: object
+          description: Storage-specific configuration
+
+    context_window:
+      type: object
+      properties:
+        max_messages:
+          type: integer
+          description: Maximum messages to retain in context
+        max_tokens:
+          type: integer
+          description: Maximum tokens to retain
+        strategy:
+          type: enum
+          values: [sliding_window, summarization, importance_weighted]
+          default: sliding_window
+          description: How to manage context when limits exceeded
+
+  examples:
+    # Stateless API agent
+    - mode: stateless
+
+    # Session-based chat agent
+    - mode: session
+      storage:
+        type: memory
+        retention: 24h
+      context_window:
+        max_messages: 50
+        strategy: sliding_window
+
+    # Long-running workflow agent
+    - mode: long_running
+      storage:
+        type: vector-db
+        retention: 1y
+        config:
+          provider: pinecone
+          index: agent-memory
+      context_window:
+        max_tokens: 128000
+        strategy: summarization
+
+# ==============================================================================
+# NEW IN v0.2.5: Enhanced Security with Scopes
+# ==============================================================================
+# Fine-grained permission scopes and compliance tags
+
+security_scopes:
+  description: |
+    Security scopes provide fine-grained access control for capabilities.
+    Similar to OAuth2 scopes but for agent capabilities.
+
+  schema:
+    scopes:
+      type: array
+      items: string
+      description: |
+        Required permission scopes for the capability:
+        - read:data - Read access to data
+        - write:data - Write access to data
+        - admin:system - Administrative operations
+        - execute:code - Code execution permissions
+
+    compliance_tags:
+      type: array
+      items: string
+      description: |
+        Compliance framework tags:
+        - pii - Handles personally identifiable information
+        - hipaa - HIPAA compliance required
+        - gdpr - GDPR compliance required
+        - fedramp - FedRAMP requirements
+        - soc2 - SOC2 Type II controls
+
+  examples:
+    # Database query capability with scopes
+    - name: query_database
+      scopes:
+        - read:data
+        - execute:query
+      compliance_tags:
+        - pii
+        - gdpr
+
+    # Admin capability with elevated permissions
+    - name: manage_users
+      scopes:
+        - admin:users
+        - write:data
+      compliance_tags:
+        - pii
+        - soc2
+        - hipaa
+
+# ==============================================================================
+# NEW IN v0.2.5: Capability Versioning
+# ==============================================================================
+# Version capabilities independently for backward compatibility
+
+capability_versioning:
+  description: |
+    Capabilities can be versioned independently of the agent.
+    Supports deprecation with migration paths.
+
+  schema:
+    version:
+      type: string
+      pattern: '^[0-9]+\.[0-9]+$'
+      description: |
+        Capability version in major.minor format.
+        - Major: Breaking changes
+        - Minor: New features, backward compatible
+
+    deprecated:
+      type: boolean
+      default: false
+      description: Whether capability is deprecated
+
+    deprecation_message:
+      type: string
+      description: |
+        Migration guidance for deprecated capabilities.
+        Should include:
+        - When it will be removed
+        - What to use instead
+        - Migration steps
+
+  examples:
+    # Current capability
+    - name: search_documents
+      version: '2.1'
+      deprecated: false
+
+    # Deprecated capability with migration path
+    - name: search_legacy
+      version: '1.0'
+      deprecated: true
+      deprecation_message: |
+        Deprecated in v0.2.4. Will be removed in v0.3.0.
+        Use 'search_documents' capability instead.
+        Migration: Change capability name and update input schema
+        to use 'query' instead of 'search_term'.
+
+# ==============================================================================
+# NEW IN v0.2.5: Google ADK Extension
+# ==============================================================================
+# Integration with Google's Agent Development Kit
+
+google_adk_extension:
+  description: |
+    Google Agent Development Kit (ADK) integration.
+    Supports LLM agents, workflow agents, and multi-agent orchestration.
+
+  schema:
+    enabled:
+      type: boolean
+      default: false
+
+    agent_type:
+      type: enum
+      values: [llm_agent, sequential_agent, parallel_agent, loop_agent, custom]
+      default: llm_agent
+      description: |
+        ADK agent architecture:
+        - llm_agent: Single LLM-powered agent
+        - sequential_agent: Pipeline of agents
+        - parallel_agent: Concurrent agent execution
+        - loop_agent: Iterative agent with conditions
+
+    model:
+      type: string
+      examples: [gemini-2.0-flash-exp, gemini-1.5-pro]
+
+    session:
+      type: object
+      properties:
+        service:
+          type: enum
+          values: [in_memory, database, vertex_ai]
+        state_schema:
+          type: object
+          description: Session state schema definition
+
+    memory:
+      type: object
+      properties:
+        enabled: boolean
+        service:
+          type: enum
+          values: [in_memory, vertex_ai_rag]
+
+  examples:
+    # Simple LLM agent
+    - enabled: true
+      agent_type: llm_agent
+      model: gemini-2.0-flash-exp
+      session:
+        service: in_memory
+
+    # Multi-agent orchestration
+    - enabled: true
+      agent_type: sequential_agent
+      sub_agents:
+        - research-agent
+        - writing-agent
+        - review-agent
+
+# ==============================================================================
+# Complete Agent Manifest Example (v0.2.5)
+# ==============================================================================
+
+example_manifest:
+  apiVersion: ossa/v0.2.5
+  kind: Agent
+  metadata:
+    name: research-assistant
+    version: 1.0.0
+    description: AI research assistant with memory and streaming support
+    labels:
+      domain: research
+      tier: production
+    annotations:
+      openstandardagents.org/stability: development
+
+  spec:
+    role: |
+      You are a research assistant that helps users find and analyze information.
+      You maintain context across conversations and can search multiple sources.
+
+    llm:
+      provider: google
+      model: gemini-2.0-flash-exp
+      temperature: 0.7
+      maxTokens: 8192
+
+    # NEW: State/memory configuration
+    state:
+      mode: session
+      storage:
+        type: vector-db
+        retention: 30d
+        config:
+          provider: pinecone
+          index: research-memory
+      context_window:
+        max_messages: 100
+        max_tokens: 32000
+        strategy: summarization
+
+    tools:
+      - type: http
+        name: search-api
+        endpoint: https://api.example.com/search
+        # NEW: Transport metadata
+        transport:
+          protocol: http
+          streaming: response
+          binding: /v1/search/stream
+          content_type: text/event-stream
+        auth:
+          type: bearer
+          credentials: secret:search-api-key
+          # NEW: Security scopes
+          scopes:
+            - read:search
+            - read:documents
+        # NEW: Compliance tags
+        compliance_tags:
+          - gdpr
+        capabilities:
+          - name: web_search
+            description: Search the web for information
+            # NEW: Capability versioning
+            version: '2.0'
+            deprecated: false
+            input_schema:
+              type: object
+              properties:
+                query:
+                  type: string
+            output_schema:
+              type: array
+              items:
+                type: object
+            # NEW: Per-capability transport
+            transport:
+              protocol: http
+              streaming: response
+            # NEW: Per-capability scopes
+            scopes:
+              - read:search
+
+          - name: legacy_search
+            description: Old search endpoint
+            version: '1.0'
+            # NEW: Deprecation
+            deprecated: true
+            deprecation_message: |
+              Use 'web_search' instead. Will be removed in v2.0.0.
+
+    autonomy:
+      level: autonomous
+      approval_required: false
+      allowed_actions:
+        - search
+        - summarize
+        - analyze
+
+    constraints:
+      cost:
+        maxTokensPerDay: 1000000
+        maxCostPerDay: 50
+        currency: USD
+      performance:
+        maxLatencySeconds: 30
+        maxConcurrentRequests: 10
+
+    observability:
+      tracing:
+        enabled: true
+        exporter: otlp
+      metrics:
+        enabled: true
+        exporter: prometheus
+      logging:
+        level: info
+        format: json
+
+  extensions:
+    # NEW: Google ADK extension
+    google_adk:
+      enabled: true
+      agent_type: llm_agent
+      model: gemini-2.0-flash-exp
+      session:
+        service: in_memory
+        state_schema:
+          search_history: array
+          current_topic: string
+      memory:
+        enabled: true
+        service: vertex_ai_rag
+      callbacks:
+        before_model_callback: validate_input
+        after_model_callback: log_response
+
+    openai_agents:
+      enabled: true
+      model: gpt-4o
+      memory:
+        enabled: true
+        type: session
+        max_messages: 100
+
+    mcp:
+      enabled: true
+      server_type: sse
+      config:
+        max_message_size: 1048576
+
+# ==============================================================================
+# Migration Notes
+# ==============================================================================
+
+migration:
+  from_v0.2.3:
+    breaking_changes: none
+    new_optional_fields:
+      - spec.state
+      - spec.tools[].transport
+      - spec.tools[].capabilities[].version
+      - spec.tools[].capabilities[].deprecated
+      - spec.tools[].capabilities[].deprecation_message
+      - spec.tools[].capabilities[].scopes
+      - spec.tools[].capabilities[].compliance_tags
+      - spec.tools[].auth.scopes
+      - spec.tools[].compliance_tags
+      - extensions.google_adk
+    recommended_actions:
+      - Add state configuration for stateful agents
+      - Add transport metadata for streaming capabilities
+      - Add compliance tags for regulated environments
+      - Version capabilities for better API lifecycle management
+
+# ==============================================================================
+# Best Practices (v0.2.5)
+# ==============================================================================
+
+best_practices:
+  # State management
+  - Use stateless mode for simple request/response agents
+  - Use session mode for chat and conversational agents
+  - Use long_running mode for workflow agents with persistent state
+  - Configure appropriate retention periods to manage storage costs
+
+  # Transport
+  - Use streaming: response for LLM text generation
+  - Use streaming: bidirectional for real-time collaborative agents
+  - Specify content_type for HTTP transports to ensure compatibility
+
+  # Security
+  - Apply least-privilege scopes to each capability
+  - Tag all capabilities that handle PII with appropriate compliance tags
+  - Use compliance_tags consistently across related capabilities
+
+  # Versioning
+  - Version capabilities when making API changes
+  - Use deprecation_message to provide clear migration paths
+  - Allow deprecation period of at least one minor version
+
+  # Google ADK
+  - Use appropriate agent_type based on workflow complexity
+  - Enable memory service for agents requiring long-term context
+  - Configure session state schema for type safety
+
+# ==============================================================================
+# Development Notes
+# ==============================================================================
+
+development_notes:
+  status: DEVELOPMENT VERSION - APIs may change
+  stability: unstable
+  feedback: https://github.com/blueflyio/openstandardagents/issues
+  planned_ga: v0.3.0
+
+  known_limitations:
+    - Transport metadata validation is experimental
+    - State storage backends limited to documented types
+    - Capability versioning pattern may be refined
+    - Google ADK extension is based on ADK preview release
+
+  upcoming_features:
+    - Agent composition patterns
+    - Distributed state management
+    - Cross-agent memory sharing
+    - Enhanced A2A protocol support

package/website/{.lighthouserc.js → .lighthouserc.ts}

@@ -1,4 +1,6 @@
-module.exports = {
+import type { Config } from '@lhci/cli';
+
+const config: Config = {
   ci: {
     collect: {
       staticDistDir: './out',
@@ -18,3 +20,5 @@ module.exports = {
   },
 };
 
+export default config;
+

package/website/Dockerfile

@@ -1,17 +1,30 @@
 # OSSA Website - Next.js Dev Server (for quick deployment)
+# Build from project root to access examples directory
 FROM node:20-alpine
 
 WORKDIR /app
 
 # Copy package files
-COPY package*.json ./
-RUN npm install --legacy-peer-deps
+COPY website/package*.json ./website/
+RUN cd website && npm install --legacy-peer-deps
 
-# Copy source code
-COPY . .
+# Copy examples directory (needed for generate-examples script)
+COPY examples ./examples
+
+# Copy website source code
+COPY website ./website
+
+WORKDIR /app/website
+
+# Generate examples.json - this MUST succeed
+RUN npm run generate-examples
+
+# Verify examples.json was created and has content
+RUN test -f public/examples.json && echo "✅ examples.json created" || (echo "❌ examples.json NOT FOUND" && exit 1)
+RUN test -s public/examples.json && echo "✅ examples.json has content" || (echo "❌ examples.json is empty" && exit 1)
 
 # Expose port
 EXPOSE 3000
 
-# Start Next.js dev server (no build needed)
+# Start Next.js dev server
 CMD ["npm", "run", "dev"]

package/website/app/about/page.tsx

@@ -10,7 +10,7 @@ export default function AboutPage() {
   return (
     <>
       {/* Hero Section */}
-      <div className="bg-gradient-to-br from-primary via-accent to-secondary text-white py-20 px-4">
+      <div className="bg-gradient-to-br from-secondary via-primary to-accent text-white py-20 px-4">
         <div className="container mx-auto max-w-4xl text-center">
           <div className="inline-flex items-center justify-center w-20 h-20 bg-white/20 backdrop-blur-sm rounded-full mb-6">
             <svg className="w-10 h-10" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -28,7 +28,7 @@ export default function AboutPage() {
         <div className="max-w-4xl mx-auto">
           <section className="mb-16">
             <div className="flex items-center mb-6">
-              <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+              <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
                 <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                   <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4" />
                 </svg>
@@ -49,7 +49,7 @@ export default function AboutPage() {
 
         <section className="mb-16">
           <div className="flex items-center mb-6">
-            <div className="w-12 h-12 bg-gradient-to-br from-secondary to-primary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
               </svg>
@@ -95,7 +95,7 @@ export default function AboutPage() {
 
         <section className="mb-16">
           <div className="flex items-center mb-6">
-            <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
               </svg>
@@ -195,7 +195,7 @@ export default function AboutPage() {
 
         <section className="mb-16">
           <div className="flex items-center mb-6">
-            <div className="w-12 h-12 bg-gradient-to-br from-accent to-primary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0zm6 3a2 2 0 11-4 0 2 2 0 014 0zM7 10a2 2 0 11-4 0 2 2 0 014 0z" />
               </svg>
@@ -216,7 +216,7 @@ export default function AboutPage() {
         <section className="mb-16">
           <div className="bg-gradient-to-br from-primary/10 via-accent/10 to-secondary/10 rounded-2xl p-8 mb-8">
             <div className="flex items-center mb-6">
-              <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+              <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
                 <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                   <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 4.354a4 4 0 110 5.292M15 21H3v-1a6 6 0 0112 0v1zm0 0h6v-1a6 6 0 00-9-5.197M13 7a4 4 0 11-8 0 4 4 0 018 0z" />
                 </svg>
@@ -268,7 +268,7 @@ export default function AboutPage() {
         </section>
 
         <section className="mb-12">
-          <div className="bg-gradient-to-r from-primary to-secondary text-white rounded-2xl p-8">
+          <div className="bg-gradient-to-r from-secondary via-primary to-accent text-white rounded-2xl p-8">
             <div className="flex items-center mb-4">
               <svg className="w-8 h-8 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z" />