@bluefly/openstandardagents 0.4.3 → 0.4.4

package/templates/validators/pattern-requirements.ossa.yaml

@@ -0,0 +1,182 @@
+apiVersion: ossa/v0.4.4
+kind: Validator
+metadata:
+  name: pattern-requirements-validator
+  version: 1.0.0
+  description: Validates architecture patterns meet required constraints
+  agentType: validator
+  agentKind: semantic
+  tags:
+    - patterns
+    - architecture
+    - requirements
+
+spec:
+  validates:
+    targetTypes:
+      - all
+    phases:
+      - semantic
+
+  rules:
+    # Graph pattern requires workflow definition
+    - id: graph-requires-workflow
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: graph
+      and:
+        path: spec.workflow
+        exists: false
+      then:
+        enforcement: error
+        message: "Graph pattern requires spec.workflow with nodes and edges"
+        rationale: "Graph patterns represent DAG workflows and need explicit node/edge definitions"
+        fixes:
+          - action: add
+            path: spec.workflow
+            value:
+              nodes: []
+              edges: []
+            impact: "+0.30 compatibility"
+            effort: high
+        documentation: "https://openstandardagents.org/docs/patterns/graph"
+
+    # Pipeline pattern should have stages
+    - id: pipeline-should-have-stages
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: pipeline
+      and:
+        path: spec.stages
+        exists: false
+      then:
+        enforcement: warning
+        message: "Pipeline pattern should define spec.stages array"
+        rationale: "Pipelines consist of sequential stages (A → B → C)"
+        fixes:
+          - action: add
+            path: spec.stages
+            value: []
+            impact: "+0.20 clarity"
+            effort: medium
+
+    # Swarm pattern requires at least 2 agents
+    - id: swarm-minimum-agents
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: swarm
+      and:
+        path: spec.agents
+        exists: true
+      # Note: Can't check array length in JSON Schema validation
+      # This rule documents the requirement for runtime validation
+      then:
+        enforcement: info
+        message: "Swarm pattern requires at least 2 agents in spec.agents array"
+        rationale: "Single agent should use pattern: 'single', not swarm"
+        documentation: "https://openstandardagents.org/docs/patterns/swarm"
+
+    # Hierarchical pattern requires manager/worker structure
+    - id: hierarchical-requires-structure
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: hierarchical
+      and:
+        path: spec.hierarchy
+        exists: false
+      then:
+        enforcement: warning
+        message: "Hierarchical pattern should define spec.hierarchy structure"
+        rationale: "Hierarchical patterns organize agents in manager/worker layers"
+        fixes:
+          - action: add
+            path: spec.hierarchy
+            value:
+              levels: 2
+              manager: null
+              workers: []
+            impact: "+0.20 clarity"
+            effort: medium
+
+    # Single pattern with streaming should declare capability
+    - id: single-streaming-capability
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: single
+      and:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: streaming
+      and:
+        path: metadata.agentArchitecture.capabilities
+        contains: streaming
+        exists: false
+      then:
+        enforcement: warning
+        message: "Streaming executionModel should include 'streaming' in capabilities"
+        fixes:
+          - action: add
+            path: metadata.agentArchitecture.capabilities
+            value: streaming
+            impact: "+0.10 consistency"
+            effort: low
+
+    # Event-driven execution requires event handlers
+    - id: event-driven-requires-handlers
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: event-driven
+      and:
+        path: spec.eventHandlers
+        exists: false
+      then:
+        enforcement: warning
+        message: "Event-driven executionModel should define spec.eventHandlers"
+        rationale: "Event-driven agents respond to events and need handler definitions"
+        fixes:
+          - action: add
+            path: spec.eventHandlers
+            value: []
+            impact: "+0.15 completeness"
+            effort: medium
+
+    # Batch execution should have batch config
+    - id: batch-requires-config
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: batch
+      and:
+        path: spec.batch
+        exists: false
+      then:
+        enforcement: info
+        message: "Batch executionModel could specify spec.batch configuration (size, interval, etc.)"
+        rationale: "Batch processing often needs size limits and scheduling parameters"
+
+    # Real-time execution with single-instance scalability
+    - id: realtime-scalability-warning
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: realtime
+      and:
+        path: metadata.agentArchitecture.runtime.scalability
+        equals: single-instance
+      then:
+        enforcement: warning
+        message: "Real-time executionModel with single-instance scalability may bottleneck. Consider horizontal scaling."
+        rationale: "Real-time workloads often need horizontal scaling for high availability"
+        fixes:
+          - action: change
+            path: metadata.agentArchitecture.runtime.scalability
+            value: horizontal
+            impact: "+0.15 performance"
+            effort: medium
+
+  coordination:
+    composable: true
+    operators:
+      - ">>"
+      - "<||>"
+
+  dependencies:
+    - capability-compatibility-validator
+    - coordination-consistency-validator

package/templates/validators/transport-compatibility.ossa.yaml

@@ -0,0 +1,185 @@
+apiVersion: ossa/v0.4.4
+kind: Validator
+metadata:
+  name: transport-compatibility-validator
+  version: 1.0.0
+  description: Validates transport protocol configuration and compatibility
+  agentType: validator
+  agentKind: platform
+  tags:
+    - transport
+    - networking
+    - protocols
+
+spec:
+  validates:
+    targetTypes:
+      - all
+    phases:
+      - platform
+
+  rules:
+    # KAGENT prefers gRPC transport
+    - id: kagent-grpc-preferred
+      when:
+        path: metadata.agentType
+        equals: kagent
+      and:
+        path: spec.transport.protocol
+        exists: false
+      then:
+        enforcement: info
+        message: "KAGENT agents typically use gRPC transport for Kubernetes-native communication"
+        rationale: "gRPC provides efficient binary protocol with bidirectional streaming, well-suited for K8s"
+        fixes:
+          - action: add
+            path: spec.transport
+            value:
+              protocol: grpc
+              host: "0.0.0.0"
+              port: 50051
+            impact: "+0.10 performance"
+            effort: low
+        documentation: "https://openstandardagents.org/docs/agent-types/kagent"
+
+    # Claude/OpenAI typically use HTTP/REST
+    - id: llm-agents-http-transport
+      when:
+        path: metadata.agentType
+        equals: claude
+      or:
+        path: metadata.agentType
+        equals: openai
+      and:
+        path: spec.transport
+        exists: false
+      then:
+        enforcement: info
+        message: "LLM agents (Claude, OpenAI) typically use HTTP/REST transport"
+        rationale: "Provider APIs use HTTP REST, no need for custom transport unless coordinating with other agents"
+
+    # Streaming capability requires appropriate transport
+    - id: streaming-transport-requirements
+      when:
+        path: metadata.agentArchitecture.capabilities
+        contains: streaming
+      and:
+        path: spec.transport.protocol
+        equals: http
+      and:
+        path: spec.transport.streaming
+        exists: false
+      then:
+        enforcement: warning
+        message: "Streaming capability with HTTP transport should configure spec.transport.streaming (SSE or WebSocket)"
+        rationale: "HTTP streaming requires Server-Sent Events (SSE) or WebSocket protocol"
+        fixes:
+          - action: add
+            path: spec.transport.streaming
+            value:
+              type: sse
+            impact: "+0.10 completeness"
+            effort: low
+
+    # gRPC transport should specify protobuf definitions
+    - id: grpc-requires-protobuf
+      when:
+        path: spec.transport.protocol
+        equals: grpc
+      and:
+        path: spec.transport.protobuf
+        exists: false
+      then:
+        enforcement: warning
+        message: "gRPC transport should reference protobuf definitions (spec.transport.protobuf)"
+        fixes:
+          - action: add
+            path: spec.transport.protobuf
+            value:
+              package: agent.v1
+              service: AgentService
+            impact: "+0.10 completeness"
+            effort: medium
+
+    # Authentication should be configured for production
+    - id: production-requires-auth
+      when:
+        path: metadata.labels.environment
+        equals: production
+      and:
+        path: spec.transport.authentication
+        exists: false
+      then:
+        enforcement: error
+        message: "Production agents must configure transport authentication"
+        rationale: "Unauthenticated transports in production are a security risk"
+        fixes:
+          - action: add
+            path: spec.transport.authentication
+            value:
+              type: bearer
+              tokenRotation: enabled
+            impact: "+0.40 security"
+            effort: medium
+        documentation: "https://openstandardagents.org/docs/security/authentication"
+
+    # TLS should be enabled for production
+    - id: production-requires-tls
+      when:
+        path: metadata.labels.environment
+        equals: production
+      and:
+        path: spec.transport.tls
+        equals: false
+      then:
+        enforcement: error
+        message: "Production agents must enable TLS/SSL encryption"
+        rationale: "Unencrypted transport in production exposes sensitive data"
+        fixes:
+          - action: change
+            path: spec.transport.tls
+            value: true
+            impact: "+0.35 security"
+            effort: low
+
+    # Port conflicts: Check common ports
+    - id: avoid-privileged-ports
+      when:
+        path: spec.transport.port
+        # Can't do numeric comparison in JSON Schema
+        # This is a reminder for runtime validation
+      then:
+        enforcement: info
+        message: "Avoid privileged ports (< 1024) unless necessary. Common agent ports: 8080 (HTTP), 50051 (gRPC)"
+        rationale: "Privileged ports require root access, complicating deployment"
+        documentation: "https://openstandardagents.org/docs/deployment/ports"
+
+    # Swarm agents need agent-to-agent transport
+    - id: swarm-requires-a2a-transport
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: swarm
+      and:
+        path: spec.transport.a2a
+        exists: false
+      then:
+        enforcement: warning
+        message: "Swarm pattern should configure agent-to-agent transport (spec.transport.a2a)"
+        rationale: "Swarm agents communicate directly and need A2A transport config"
+        fixes:
+          - action: add
+            path: spec.transport.a2a
+            value:
+              protocol: grpc
+              discovery: dns
+            impact: "+0.20 coordination"
+            effort: medium
+
+  coordination:
+    composable: true
+    operators:
+      - ">>"
+      - "<||>"
+
+  dependencies:
+    - capability-compatibility-validator

package/.wiki-config.json

@@ -1,24 +0,0 @@
-{
-  "PROJECT_NAME": "@bluefly/openstandardagents",
-  "PROJECT_DESCRIPTION": "OSSA - Open Standard for Scalable AI Agents. A specification standard for AI agents (like OpenAPI for REST APIs). NOT a framework.",
-  "VERSION": "0.3.0",
-  "STATUS": "Active",
-  "LICENSE": "Apache-2.0",
-  "KEY_FEATURES": "- OSSA v0.3.0 specification\n- Type-safe TypeScript validation\n- OpenAPI 3.1 specifications\n- Reference implementations\n- Agent-to-Agent messaging\n- Web-native protocols",
-  "REPO_URL": "https://gitlab.com/blueflyio/openstandardagents",
-  "GITLAB_ISSUES_URL": "https://gitlab.com/blueflyio/openstandardagents/-/issues",
-  "DOCS_URL": "https://gitlab.com/blueflyio/openstandardagents/-/wikis/home",
-  "TEAM_CONTACT": "${GIT_AUTHOR_EMAIL:-oss@bluefly.io}",
-  "PREREQUISITES": "- Node.js 20+\n- TypeScript 5.9+",
-  "INSTALL_COMMAND": "npm install",
-  "START_COMMAND": "npm run dev",
-  "VERIFY_COMMAND": "npm run test",
-  "BACKEND_STACK": "- TypeScript 5.9+\n- Zod - Schema validation\n- AJV - JSON Schema validation",
-  "FRONTEND_STACK": "N/A",
-  "INFRASTRUCTURE_STACK": "- Docker\n- GitLab CI/CD",
-  "API_BASE_URL": "N/A",
-  "OPENAPI_URL": "https://gitlab.com/blueflyio/openstandardagents/-/tree/main/openapi",
-  "UNIT_TEST_COMMAND": "npm run test:unit",
-  "LINT_COMMAND": "npm run lint",
-  "FORMAT_COMMAND": "npm run format"
-}

package/DEMO.md

@@ -1,212 +0,0 @@
-# OSSA v0.4.1 - The Killer Demo
-
-## Turn Any AI Agent into a Production NPM Package in 60 Seconds
-
-**Problem**: You built an AI agent. How do you deploy it? Share it? Version it? Install it like real software?
-
-**Solution**: OSSA CLI
-
----
-
-## The Demo
-
-### 1. Install OSSA CLI (when published)
-```bash
-npm install -g @bluefly/openstandardagents
-```
-
-### 2. Create Your Agent (3 commands)
-```bash
-# Quick start with wizard
-ossa quickstart
-
-# OR create from scratch
-ossa wizard
-
-# OR import from another platform
-ossa import cursor-agent.json --from cursor
-```
-
-### 3. Export to Production Package (1 command)
-```bash
-ossa export my-agent.ossa.yaml --platform npm --output ./my-agent-package
-```
-
-**Output**: A production-ready NPM package with:
-- ✅ `package.json` with proper metadata
-- ✅ `index.js` entry point
-- ✅ `index.d.ts` TypeScript types
-- ✅ `README.md` with usage docs
-- ✅ `.npmignore` for clean publishing
-- ✅ Original OSSA manifest included
-
-### 4. Publish & Use
-```bash
-cd my-agent-package
-npm publish
-
-# Now anyone can install it:
-npm install my-agent
-```
-
----
-
-## What Problem Does This Solve?
-
-**Before OSSA:**
-- No standard format for agent definitions
-- Platform lock-in - rewrite for each platform
-- Manual packaging and deployment setup
-- No dependency management or versioning
-- Copy-paste agent configs between tools
-
-**With OSSA:**
-- One manifest works across 12+ platforms
-- Export to: NPM, Docker, Kubernetes, MCP, Cursor, Claude Desktop, Langchain, CrewAI, AutoGen, AG2, Langflow, OpenAI
-- Production CLI with validation, dry-run, JSON output
-- Type-safe manifests with Zod + TypeScript
-- OpenAPI-style approach for agents
-
----
-
-## Real Example
-
-```yaml
-# my-agent.ossa.yaml
-apiVersion: ossa/v0.3.6
-kind: Agent
-metadata:
-  name: code-reviewer
-  version: 1.0.0
-  description: AI code reviewer agent
-spec:
-  role: "You review code for quality, security, and best practices"
-  llm:
-    provider: openai
-    model: gpt-4
-  capabilities:
-    - id: review-code
-      type: tool
-      name: review_code
-      description: Review code and provide feedback
-```
-
-**One command later:**
-```bash
-ossa export my-agent.ossa.yaml --platform npm
-
-# Outputs:
-# ✓ NPM package exported to: code-reviewer-npm/
-#   Files: package.json, index.js, index.d.ts, README.md
-```
-
-**Now it's installable software:**
-```bash
-npm install @myorg/code-reviewer
-```
-
----
-
-## Platform Support Matrix
-
-| Platform | Export | Import | Status |
-|----------|--------|--------|--------|
-| NPM | ✅ | ✅ | Production |
-| Docker | ✅ | ❌ | Beta |
-| Kubernetes | ✅ | ❌ | Beta |
-| MCP | ✅ | ✅ | Production |
-| Cursor | ✅ | ✅ | Production |
-| Claude Desktop | ✅ | ❌ | Production |
-| Langchain | ✅ | ✅ | Beta |
-| CrewAI | ✅ | ✅ | Beta |
-| AutoGen | ✅ | ✅ | Beta |
-| AG2 | ✅ | ❌ | Beta |
-| Langflow | ✅ | ✅ | Beta |
-| OpenAI | ✅ | ✅ | Production |
-
----
-
-## The "Wow" Factor
-
-**Traditional approach** (Cursor agent to production):
-1. Write agent in Cursor format
-2. Manually create package.json
-3. Write entry point code
-4. Create TypeScript types
-5. Write README
-6. Configure for each platform
-7. Test deployments
-8. Maintain separate configs
-
-**Time**: Hours to days
-
-**OSSA approach**:
-```bash
-ossa import cursor-agent.json --from cursor
-ossa export agent.ossa.yaml --platform npm
-```
-
-**Time**: 60 seconds
-
----
-
-## Production Features
-
-All commands support:
-- `--dry-run` - Preview without changes
-- `--verbose` - Detailed output
-- `--quiet` - Minimal output for scripts
-- `--json` - Machine-readable output
-- `--no-color` - CI-friendly
-- Proper exit codes for scripts
-
-Example:
-```bash
-# Safe preview
-ossa export agent.yaml --platform npm --dry-run
-
-# Automated pipeline
-ossa export agent.yaml --platform npm --quiet --json > result.json
-```
-
----
-
-## Why OSSA is The Standard
-
-1. **OpenAPI-inspired**: We learned from the API revolution
-2. **Platform-agnostic**: Write once, deploy everywhere
-3. **Type-safe**: Zod + TypeScript for reliability
-4. **Production-ready**: Built for real deployments
-5. **Open Standard**: Community-driven, not vendor lock-in
-
----
-
-## Get Started Now
-
-```bash
-# Install
-npm install -g @bluefly/openstandardagents
-
-# Quick start
-ossa quickstart
-
-# Create agent
-ossa wizard
-
-# Export to any platform
-ossa export agent.yaml --platform npm
-```
-
-**Documentation**: https://openstandardagents.org
-**GitHub**: https://github.com/blueflyio/openstandardagents
-**Spec**: https://openstandardagents.org/spec
-
----
-
-## Why OSSA Exists
-
-OpenAPI standardized REST API definitions. OSSA does the same for AI agents.
-
-One manifest format. Works everywhere. Production-ready tooling.
-
-**OSSA v0.4.1** - Ready for production use.