@bluefly/openstandardagents 0.2.5-RC → 0.2.7

package/dist/spec/v0.2.7/core/agentgraph.md

@@ -0,0 +1,324 @@
+# AgentGraph Resource Specification
+
+**Version:** v0.2.7  
+**Status:** Draft  
+**Type:** Core Resource
+
+## Overview
+
+AgentGraph is a resource type for defining multi-agent compositions as directed graphs. It enables orchestration of multiple agents with explicit data flow and conditional routing.
+
+## Motivation
+
+Single agents are limited in capability. Complex tasks require:
+- Multiple specialized agents working together
+- Data flow between agents
+- Conditional routing based on outputs
+- Error handling across agent boundaries
+
+AgentGraph provides a declarative way to compose agents into workflows.
+
+## Resource Structure
+
+```yaml
+apiVersion: ossa.ai/v0.2.7
+kind: AgentGraph
+metadata:
+  name: string
+  version: string
+  description: string
+spec:
+  agents: Agent[]
+  edges: Edge[]
+  entrypoint: string
+  errorHandling: ErrorHandling
+```
+
+## Fields
+
+### metadata
+
+Standard OSSA metadata block.
+
+**Required fields:**
+- `name`: Unique identifier for the graph
+- `version`: Semantic version
+
+### spec.agents
+
+Array of agent definitions within the graph.
+
+**Fields:**
+- `id` (required): Unique identifier within graph
+- `agentRef` (required): Reference to Agent resource
+- `config` (optional): Agent-specific configuration overrides
+
+**Example:**
+```yaml
+agents:
+  - id: analyzer
+    agentRef: sentiment-analyzer
+    config:
+      threshold: 0.8
+  - id: responder
+    agentRef: response-generator
+```
+
+### spec.edges
+
+Array defining data flow between agents.
+
+**Fields:**
+- `from` (required): Source agent ID
+- `to` (required): Target agent ID
+- `condition` (optional): Boolean expression for conditional routing
+- `transform` (optional): Data transformation expression
+
+**Example:**
+```yaml
+edges:
+  - from: analyzer
+    to: responder
+  - from: analyzer
+    to: escalation
+    condition: output.sentiment < 0.3
+```
+
+### spec.entrypoint
+
+ID of the starting agent. Graph execution begins here.
+
+### spec.errorHandling
+
+Error handling strategy for the graph.
+
+**Fields:**
+- `strategy`: `fail-fast` | `continue` | `retry`
+- `maxRetries`: Maximum retry attempts (for retry strategy)
+- `fallbackAgent`: Agent ID to invoke on error
+
+## Execution Model
+
+### Sequential Execution
+
+Agents execute in topological order based on edges.
+
+```yaml
+edges:
+  - from: A
+    to: B
+  - from: B
+    to: C
+```
+
+Execution: A → B → C
+
+### Parallel Execution
+
+Agents with no dependencies execute in parallel.
+
+```yaml
+edges:
+  - from: A
+    to: B
+  - from: A
+    to: C
+  - from: B
+    to: D
+  - from: C
+    to: D
+```
+
+Execution: A → (B || C) → D
+
+### Conditional Routing
+
+Edges with conditions enable branching.
+
+```yaml
+edges:
+  - from: classifier
+    to: pathA
+    condition: output.category == 'A'
+  - from: classifier
+    to: pathB
+    condition: output.category == 'B'
+```
+
+### Data Flow
+
+Output from source agent becomes input to target agent.
+
+**Transformation:**
+```yaml
+edges:
+  - from: extractor
+    to: formatter
+    transform: |
+      {
+        "data": output.extracted,
+        "format": "json"
+      }
+```
+
+## Error Handling
+
+### Fail-Fast (default)
+
+Stop execution on first error.
+
+```yaml
+errorHandling:
+  strategy: fail-fast
+```
+
+### Continue
+
+Continue execution, skip failed agents.
+
+```yaml
+errorHandling:
+  strategy: continue
+```
+
+### Retry
+
+Retry failed agents up to maxRetries.
+
+```yaml
+errorHandling:
+  strategy: retry
+  maxRetries: 3
+```
+
+### Fallback
+
+Invoke fallback agent on error.
+
+```yaml
+errorHandling:
+  strategy: fail-fast
+  fallbackAgent: error-handler
+```
+
+## Examples
+
+### Sequential Pipeline
+
+```yaml
+apiVersion: ossa.ai/v0.2.7
+kind: AgentGraph
+metadata:
+  name: content-pipeline
+  version: 1.0.0
+spec:
+  agents:
+    - id: researcher
+      agentRef: research-agent
+    - id: writer
+      agentRef: writing-agent
+    - id: editor
+      agentRef: editing-agent
+  edges:
+    - from: researcher
+      to: writer
+    - from: writer
+      to: editor
+  entrypoint: researcher
+```
+
+### Parallel Processing
+
+```yaml
+apiVersion: ossa.ai/v0.2.7
+kind: AgentGraph
+metadata:
+  name: parallel-analysis
+  version: 1.0.0
+spec:
+  agents:
+    - id: splitter
+      agentRef: data-splitter
+    - id: analyzer1
+      agentRef: sentiment-analyzer
+    - id: analyzer2
+      agentRef: entity-extractor
+    - id: merger
+      agentRef: result-merger
+  edges:
+    - from: splitter
+      to: analyzer1
+    - from: splitter
+      to: analyzer2
+    - from: analyzer1
+      to: merger
+    - from: analyzer2
+      to: merger
+  entrypoint: splitter
+```
+
+### Conditional Routing
+
+```yaml
+apiVersion: ossa.ai/v0.2.7
+kind: AgentGraph
+metadata:
+  name: support-router
+  version: 1.0.0
+spec:
+  agents:
+    - id: classifier
+      agentRef: intent-classifier
+    - id: technical
+      agentRef: technical-support
+    - id: billing
+      agentRef: billing-support
+    - id: general
+      agentRef: general-support
+  edges:
+    - from: classifier
+      to: technical
+      condition: output.intent == 'technical'
+    - from: classifier
+      to: billing
+      condition: output.intent == 'billing'
+    - from: classifier
+      to: general
+      condition: output.intent == 'general'
+  entrypoint: classifier
+  errorHandling:
+    strategy: fail-fast
+    fallbackAgent: general
+```
+
+## Validation Rules
+
+1. **Acyclic**: Graph MUST NOT contain cycles
+2. **Connected**: All agents MUST be reachable from entrypoint
+3. **Valid References**: All `agentRef` MUST reference existing Agent resources
+4. **Unique IDs**: Agent IDs MUST be unique within graph
+5. **Valid Edges**: Edge `from`/`to` MUST reference agent IDs in graph
+
+## Runtime Requirements
+
+Implementations MUST:
+- Validate graph structure before execution
+- Execute agents in topological order
+- Handle parallel execution where possible
+- Evaluate conditions before edge traversal
+- Apply transformations to data flow
+- Implement specified error handling strategy
+
+## Future Considerations
+
+- **Loops**: Support for iterative agent execution
+- **Subgraphs**: Nested AgentGraph resources
+- **Dynamic Routing**: Runtime edge creation
+- **State Management**: Shared state across agents
+- **Observability**: Built-in tracing and metrics
+
+## Related Resources
+
+- [Agent Resource](./agent-definition.md)
+- [Multi-Agent Composition](../examples/multi-agent/)
+- [Error Handling](./error-handling.md)

package/dist/spec/v0.2.7/resources/agentgraph.yaml

@@ -0,0 +1,135 @@
+apiVersion: ossa.ai/v0.2.7
+kind: ResourceDefinition
+metadata:
+  name: AgentGraph
+  version: 1.0.0
+  description: Multi-agent composition and orchestration resource
+
+spec:
+  # AgentGraph defines a directed graph of agents with data flow
+  schema:
+    apiVersion:
+      type: string
+      pattern: ^ossa\.ai/v\d+\.\d+\.\d+$
+      required: true
+    
+    kind:
+      type: string
+      enum: [AgentGraph]
+      required: true
+    
+    metadata:
+      type: object
+      required: true
+      properties:
+        name:
+          type: string
+          description: Unique identifier for the agent graph
+        version:
+          type: string
+          pattern: ^\d+\.\d+\.\d+$
+        description:
+          type: string
+    
+    spec:
+      type: object
+      required: true
+      properties:
+        agents:
+          type: array
+          description: List of agents in the graph
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Unique ID within graph
+              agentRef:
+                type: string
+                description: Reference to Agent resource
+              config:
+                type: object
+                description: Agent-specific configuration
+        
+        edges:
+          type: array
+          description: Data flow between agents
+          items:
+            type: object
+            properties:
+              from:
+                type: string
+                description: Source agent ID
+              to:
+                type: string
+                description: Target agent ID
+              condition:
+                type: string
+                description: Optional condition for edge traversal
+              transform:
+                type: string
+                description: Optional data transformation
+        
+        entrypoint:
+          type: string
+          description: Starting agent ID
+        
+        errorHandling:
+          type: object
+          properties:
+            strategy:
+              type: string
+              enum: [fail-fast, continue, retry]
+            maxRetries:
+              type: integer
+            fallbackAgent:
+              type: string
+
+examples:
+  - name: Sequential Pipeline
+    description: Simple sequential agent pipeline
+    yaml: |
+      apiVersion: ossa.ai/v0.2.7
+      kind: AgentGraph
+      metadata:
+        name: content-pipeline
+        version: 1.0.0
+      spec:
+        agents:
+          - id: researcher
+            agentRef: research-agent
+          - id: writer
+            agentRef: writing-agent
+          - id: editor
+            agentRef: editing-agent
+        edges:
+          - from: researcher
+            to: writer
+          - from: writer
+            to: editor
+        entrypoint: researcher
+  
+  - name: Conditional Routing
+    description: Route based on agent output
+    yaml: |
+      apiVersion: ossa.ai/v0.2.7
+      kind: AgentGraph
+      metadata:
+        name: support-router
+        version: 1.0.0
+      spec:
+        agents:
+          - id: classifier
+            agentRef: intent-classifier
+          - id: technical
+            agentRef: technical-support
+          - id: billing
+            agentRef: billing-support
+        edges:
+          - from: classifier
+            to: technical
+            condition: output.intent == 'technical'
+          - from: classifier
+            to: billing
+            condition: output.intent == 'billing'
+        entrypoint: classifier

package/docs/brand-guide/01-brand-overview.md

@@ -0,0 +1,37 @@
+# OSSA Brand Overview
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Mission
+
+**Make AI agents interoperable across all platforms and frameworks.**
+
+OSSA (Open Standard for Scalable AI Agents) provides a vendor-neutral specification standard that enables AI agents to communicate and collaborate seamlessly.
+
+## Vision
+
+**Become the OpenAPI for AI agents** - the universally adopted standard for defining, deploying, and connecting autonomous AI systems.
+
+## Core Values
+
+### 1. Open & Vendor-Neutral
+Community-driven, no vendor lock-in, Apache 2.0 license
+
+### 2. Interoperable  
+Common language across frameworks, runtime-independent
+
+### 3. Trustworthy
+Compliance-ready, security built-in, enterprise-grade
+
+### 4. Simple & Practical
+Clear specification, production-ready implementations
+
+## Key Messages
+
+**Primary:** "The OpenAPI for AI Agents"
+
+**For Enterprises:** Deploy anywhere, switch frameworks anytime, maintain compliance always
+
+**For Developers:** Write once, deploy anywhere - portable and future-proof
+
+**For Framework Builders:** Build on an open standard

package/docs/brand-guide/02-logo-usage.md

@@ -0,0 +1,43 @@
+# OSSA Logo Usage Guidelines
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Primary Logo
+
+Dynamic gradient-based mark representing interconnected AI agents.
+
+**Location:** `/website/public/brand/ossa-logo.svg`
+
+**Colors:** Gradient from Cyan Blue (#1CB9ED) → Deep Purple (#4A3ECD) → Light Purple (#9060EA)
+
+## Logo Variations
+
+- **Full Color:** White/light backgrounds
+- **Monochrome White:** Dark backgrounds (#FFFFFF)
+- **Monochrome Dark:** Light backgrounds, print (#2D1B69)
+- **Grayscale:** Print only (#374151)
+
+## Minimum Sizes
+
+- **Digital:** 120px width min (180px recommended)
+- **Print:** 1 inch min (1.5 inches recommended)
+- **Icon:** 16px, 32px, 64px, 128px
+
+## Clear Space
+
+Maintain clear space = **0.5× logo height** on all sides
+
+## Incorrect Usage
+
+❌ Don't change colors
+❌ Don't distort/stretch
+❌ Don't add effects
+❌ Don't modify
+❌ Don't use low-quality
+
+## Background Guidelines
+
+✅ White, light gray, light blue, dark purple, black
+❌ Bright colors, busy patterns, low-contrast
+
+**Rule:** 4.5:1 minimum contrast ratio

package/docs/brand-guide/03-color-palette.md

@@ -0,0 +1,70 @@
+# OSSA Color Palette
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Primary Brand Colors
+
+### Deep Purple (Primary)
+**Base:** `#4A3ECD`
+**Usage:** Primary actions, branding, emphasis
+**Scale:** 50-950 (see full guide)
+
+### Cyan Blue (Secondary)  
+**Base:** `#1CB9ED`
+**Usage:** Secondary actions, accents, gradients
+**Scale:** 50-950
+
+### Light Purple (Accent)
+**Base:** `#9060EA`  
+**Usage:** Decorative accents, gradient endpoints
+**Scale:** 50-950
+
+### Dark Purple (Depth)
+**Base:** `#2D1B69`
+**Usage:** Dark backgrounds, dark mode, contrast
+**Scale:** 50-950
+
+## Semantic Colors
+
+- **Success:** `#10B981` (Green)
+- **Warning:** `#F59E0B` (Amber)
+- **Error:** `#EF4444` (Red)
+- **Info:** `#06B6D4` (Cyan)
+
+## Neutrals (Grays)
+
+**Scale:** `#F9FAFB` (50) to `#111827` (900)
+
+**Common Uses:**
+- Primary text: Gray-700 (#374151) or Gray-900
+- Secondary text: Gray-600 (#4B5563)
+- Borders: Gray-200 (#E5E7EB) or Gray-300
+- Backgrounds: White, Gray-50, Gray-100
+
+## Gradients
+
+### Brand Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 40%, #4A3ECD 70%, #9060EA 100%);
+```
+
+### Hero Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 35%, #4A3ECD 65%, #9060EA 100%);
+```
+
+## Accessibility
+
+All combinations meet WCAG AA minimum (AAA preferred):
+- Normal text: 4.5:1 minimum (7:1 target)
+- Large text: 3:1 minimum (4.5:1 target)
+- UI components: 3:1 minimum
+
+**White text on:**
+- Primary-500+: ✅ AAA (7.5:1)
+- Secondary-600+: ✅ AA (4.7:1)
+- Dark Purple-700+: ✅ AAA (10:1+)
+
+**Black text on:**
+- Gray-50 to Gray-300: ✅ AAA (8:1+)
+- Primary-50 to Primary-400: ✅ AAA (7:1+)

package/docs/brand-guide/04-typography.md

@@ -0,0 +1,82 @@
+# OSSA Typography Guidelines
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Font Families
+
+### Primary: Inter (Sans-serif)
+**Usage:** UI, headings, body text, marketing
+**Weights:** 400 (Regular), 500 (Medium), 600 (Semi-Bold), 700 (Bold), 800 (Extra-Bold)
+**Why:** Exceptional legibility, optimized for screens, 200+ languages
+
+### Monospace: JetBrains Mono
+**Usage:** Code blocks, inline code, technical content
+**Weights:** 400 (Regular), 500 (Medium), 600 (Semi-Bold)
+**Why:** Developer-focused, excellent ligatures, clear character distinction
+
+## Type Scale
+
+| Element | Size | Line Height | Weight | Color |
+|---------|------|-------------|--------|-------|
+| **Display** | 72px (4.5rem) | 1.1 | 800 | Gray-900 or Gradient |
+| **H1** | 56px (3.5rem) | 1.2 | 700 | Gray-900 or Primary-500 |
+| **H2** | 40px (2.5rem) | 1.3 | 700 | Gray-900 |
+| **H3** | 32px (2rem) | 1.4 | 600 | Gray-900 |
+| **H4** | 24px (1.5rem) | 1.5 | 600 | Gray-800 |
+| **H5** | 20px (1.25rem) | 1.5 | 600 | Gray-800 |
+| **H6** | 18px (1.125rem) | 1.5 | 600 | Gray-700 |
+| **Body** | 16px (1rem) | 1.6 | 400 | Gray-700 |
+| **Body Large** | 18px (1.125rem) | 1.6 | 400 | Gray-700 |
+| **Small** | 14px (0.875rem) | 1.5 | 400 | Gray-600 |
+| **Extra Small** | 12px (0.75rem) | 1.5 | 400 | Gray-500 |
+
+## Letter Spacing
+
+- **Display:** -0.02em (tighter for large sizes)
+- **H1:** -0.01em (slightly tighter)
+- **H2-H6, Body:** 0 (normal)
+- **All Caps:** 0.05em (improve readability)
+
+## Code Typography
+
+### Inline Code
+- Font: JetBrains Mono, 0.875em
+- Color: Primary-700 (#322598)
+- Background: Primary-50 (#F5F4FD)
+- Padding: 0.2em 0.4em
+- Border Radius: 4px
+
+### Code Blocks
+- Font: JetBrains Mono, 14px (0.875rem)
+- Color: #D4D4D4 (light gray on dark)
+- Background: #1E1E1E (dark gray)
+- Line Height: 1.6
+- Padding: 16px
+- Border Radius: 8px
+
+## Responsive Typography
+
+**Mobile (< 768px):**
+- Display: 40px
+- H1: 36px
+- H2: 28px
+
+**Tablet (768-1279px):**
+- Display: 56px
+- H1: 48px
+- H2: 32px
+
+**Desktop (1280px+):**
+- Use full scale (above)
+
+## Accessibility
+
+✅ Line height: 1.5 minimum for body (we use 1.6)
+✅ Contrast: All text meets WCAG AA minimum (AAA preferred)
+✅ Font size: Never below 12px (prefer 14px minimum)
+✅ Zoom: Support up to 200% without loss of functionality
+
+**Text Contrast:**
+- Primary text: Gray-700 on white (10.5:1 AAA)
+- Secondary text: Gray-600 on white (7.4:1 AAA)
+- Links: Primary-500 on white (6.1:1 AA)