@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/pre-release/index.md

@@ -0,0 +1,175 @@
+# Pre-Release Specifications
+
+> **Warning**: These specifications are in development and may change before stable release. Do not use in production.
+
+## Development Versions
+
+OSSA follows semantic versioning. Development specs are marked with `-dev` suffix to indicate they are not yet stable.
+
+### v0.2.4-dev - Transport & Security
+
+**Status**: Development
+**Target Release**: February 2025
+**Milestone**: [v0.2.4 - Transport & Security](https://github.com/blueflyio/openstandardagents/milestones/12)
+
+#### New Features
+
+1. **Transport Metadata for Capabilities**
+   - Protocol support: `http`, `grpc`, `a2a`, `mcp`, `websocket`, `custom`
+   - Streaming modes: `none`, `request`, `response`, `bidirectional`
+   - Binding paths for endpoints
+
+2. **State/Memory Specification**
+   - Mode: `stateless`, `session`, `long_running`
+   - Storage types: `memory`, `vector-db`, `kv`, `rdbms`, `custom`
+   - Retention configuration
+
+3. **Security Scopes and Compliance Tags**
+   - OAuth2-style scopes per capability
+   - Compliance tags: `pii`, `hipaa`, `gdpr`, `fedramp`, `soc2`
+
+4. **Capability Versioning**
+   - Version field (major.minor)
+   - Deprecation flags and messages
+
+5. **Google ADK Extension**
+   - A2A protocol support
+   - Agent hierarchies
+   - MCP integration
+   - Streaming modalities
+
+#### Framework Alignment
+
+- Google Agent Development Kit (ADK)
+- OpenAI Agents SDK
+- Microsoft Agent Framework
+
+---
+
+### v0.2.5-RC-dev - Multi-Agent Composition
+
+**Status**: Development
+**Target Release**: March 2025
+**Milestone**: [v0.2.5-RC - Multi-Agent Composition](https://github.com/blueflyio/openstandardagents/milestones/13)
+
+#### New Features
+
+1. **AgentGraph Resource Type**
+   ```yaml
+   apiVersion: ossa/v0.2.5-RC
+   kind: AgentGraph  # New!
+   metadata:
+     name: customer-support-cluster
+   spec:
+     agents:
+       - ref: triage-agent
+         role: entry
+       - ref: resolver-agent
+         role: worker
+     edges:
+       - from: triage-agent
+         to: resolver-agent
+         condition: standard-issue
+     process: sequential
+   ```
+
+2. **Process Patterns**
+   - `sequential`: Agents execute one after another
+   - `parallel`: Agents execute simultaneously
+   - `hierarchical`: Manager delegates to workers
+   - `conditional`: Branching based on conditions
+   - `loop`: Iterative execution
+
+3. **Edge Routing**
+   - From/to agent references
+   - Condition expressions
+   - Priority ordering
+
+4. **Shared State**
+   - Schema definition
+   - Persistence options
+   - Checkpointing and recovery
+
+#### Framework Alignment
+
+- CrewAI (crews, manager agents)
+- MetaGPT (SOPs, role pipelines)
+- Microsoft AF (workflows)
+- Google ADK (agent graphs)
+- LangGraph (state machines)
+
+---
+
+## Using Development Specs
+
+### Installation
+
+Development specs are available in the repository:
+
+```bash
+# Clone the repository
+git clone https://github.com/blueflyio/openstandardagents.git
+cd openstandardagents
+
+# View development specs
+ls spec/v0.2.5-RC/
+ls spec/v0.2.5-RC/
+```
+
+### Validation
+
+```bash
+# Install CLI (if not already installed)
+npm install -g @bluefly/openstandardagents
+
+# Validate against development schema
+ossa validate your-agent.yaml --version 0.2.4-dev
+```
+
+### Examples
+
+Development examples are in the spec directories:
+
+- `spec/v0.2.5-RC/examples/customer-support-graph.ossa.yaml` - Sequential process
+- `spec/v0.2.5-RC/examples/research-team.ossa.yaml` - Hierarchical process
+- `spec/v0.2.5-RC/examples/parallel-processors.ossa.yaml` - Parallel process
+
+---
+
+## Providing Feedback
+
+We welcome feedback on development specifications:
+
+1. **GitHub Issues**: [Create an issue](https://github.com/blueflyio/openstandardagents/issues/new)
+2. **Discussions**: Comment on milestone issues
+3. **Pull Requests**: Submit improvements
+
+### v0.2.4 Issues
+- [#220 - Transport metadata](https://github.com/blueflyio/openstandardagents/issues/220)
+- [#221 - State/memory block](https://github.com/blueflyio/openstandardagents/issues/221)
+- [#222 - Security scopes](https://github.com/blueflyio/openstandardagents/issues/222)
+- [#223 - Capability versioning](https://github.com/blueflyio/openstandardagents/issues/223)
+- [#224 - Google ADK extension](https://github.com/blueflyio/openstandardagents/issues/224)
+- [#225 - MS AF adapter](https://github.com/blueflyio/openstandardagents/issues/225)
+
+### v0.2.5-RC Issues
+- [#211-212 - AgentGraph resource](https://github.com/blueflyio/openstandardagents/issues/211)
+- [#213 - Process patterns](https://github.com/blueflyio/openstandardagents/issues/213)
+- [#214 - Edge routing](https://github.com/blueflyio/openstandardagents/issues/214)
+- [#215 - Shared state](https://github.com/blueflyio/openstandardagents/issues/215)
+- [#216-218 - Adapter examples](https://github.com/blueflyio/openstandardagents/issues/216)
+- [#219 - Validation rules](https://github.com/blueflyio/openstandardagents/issues/219)
+
+---
+
+## Roadmap
+
+| Version | Focus | Status | Target |
+|---------|-------|--------|--------|
+| v0.2.3 | Documentation & Examples | **Stable** | Released |
+| v0.2.4 | Transport & Security | Development | Feb 2025 |
+| v0.2.5-RC | Multi-Agent Composition | Development | Mar 2025 |
+| v0.3.0 | Gamma Release | Planned | Apr 2025 |
+| v1.0.0 | Genesis Release | Planned | TBD |
+
+See [milestones](https://github.com/blueflyio/openstandardagents/milestones) for full details.

package/website/content/docs/quick-reference.md

@@ -0,0 +1,17 @@
+---
+title: "Quick Reference"
+---
+
+# Quick Reference
+
+- Root: `x-ossa-metadata`, `x-ossa`, `x-agent`
+- Operation: `x-ossa-capability`, `x-ossa-autonomy`, `x-ossa-constraints`, `x-ossa-tools`, `x-ossa-llm`
+- Parameters: `x-ossa-agent-id`, `x-ossa-version`
+- Schemas: `x-ossa-capability-schema`
+
+**Validation**:
+```bash
+ossa validate examples/openapi-extensions/worker-agent-api.openapi.yml --openapi --verbose
+```
+
+**Links**: [OpenAPI-Extensions](./OpenAPI-Extensions) · [Examples](./Examples)

package/website/content/docs/readme.md

@@ -0,0 +1,35 @@
+---
+title: "README"
+---
+
+# OSSA Documentation
+
+## Core Documentation
+
+- **[Getting Started](Getting-Started)** - Quick start guide for OSSA
+- **[OpenAPI Extensions](OpenAPI-Extensions)** - How OSSA extends OpenAPI/Swagger for AI agents
+- **[Migration Guide](migration/)** - Upgrading from v0.1.x to v1.0
+- **[Specification](Specification/)** - OSSA 1.0 JSON Schema
+- **[Examples](Examples/)** - Reference implementations
+
+## Additional Resources
+
+For comprehensive documentation, guides, and architecture details, visit:
+
+**[GitHub Repository](https://github.com/blueflyio/openstandardagents)**
+
+The repository contains:
+- Architecture guides
+- Deployment strategies
+- Integration tutorials
+- Best practices
+- Community guidelines
+- Contributing guidelines
+
+## Quick Links
+
+- **Specification**: [spec/ossa-1.0.schema.json](Specification/ossa-1.0.schema.json)
+- **npm Package**: [@bluefly/openstandardagents](https://www.npmjs.com/package/@bluefly/openstandardagents)
+- **GitHub Repository**: [blueflyio/openstandardagents](https://github.com/blueflyio/openstandardagents)
+- **Issues**: [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
+

package/website/content/docs/schema-reference/agent-spec.md

@@ -0,0 +1,406 @@
+---
+title: "Agent Spec"
+description: "Agent specification object defining behavior and capabilities"
+weight: 2
+---
+
+# Agent Spec Object
+
+The `spec` object defines the agent's behavior, capabilities, configuration, and operational parameters.
+
+## Field Reference
+
+| Field Name | Type | Required | Description |
+|------------|------|----------|-------------|
+| `taxonomy` | [Taxonomy](./taxonomy.md) | No | Agent classification by domain, subdomain, and capability |
+| `role` | string | **Yes** | Agent role/system prompt describing behavior and capabilities. Minimum 1 character |
+| `llm` | [LLMConfig](./llm-config.md) | No | Language model provider and configuration parameters |
+| `tools` | array[[Tool](./tools.md)] | No | Available tools and capabilities for the agent |
+| `autonomy` | [Autonomy](./autonomy.md) | No | Autonomy level and action control settings |
+| `constraints` | [Constraints](./constraints.md) | No | Cost, performance, and resource constraints |
+| `observability` | [Observability](./observability.md) | No | Tracing, metrics, and logging configuration |
+
+## Basic Example
+
+```yaml
+spec:
+  role: |
+    You are a helpful customer support agent.
+    Answer customer questions professionally and accurately.
+```
+
+## Complete Example
+
+```yaml
+spec:
+  taxonomy:
+    domain: customer-service
+    subdomain: technical-support
+    capability: troubleshooting
+
+  role: |
+    You are a technical support specialist for SaaS products.
+
+    Your responsibilities:
+    - Diagnose technical issues from customer descriptions
+    - Provide step-by-step troubleshooting guidance
+    - Escalate complex issues to engineering when needed
+    - Document solutions in the knowledge base
+
+    Communication style:
+    - Professional and empathetic
+    - Clear and concise technical explanations
+    - Patient with non-technical users
+    - Proactive in suggesting preventive measures
+
+  llm:
+    provider: anthropic
+    model: claude-3-5-sonnet-20241022
+    temperature: 0.3
+    maxTokens: 4096
+
+  tools:
+    - type: mcp
+      server: crm
+      capabilities:
+        - search_tickets
+        - create_ticket
+        - update_ticket
+    - type: mcp
+      server: knowledge-base
+      capabilities:
+        - search_articles
+        - create_article
+    - type: http
+      endpoint: https://api.example.com/diagnostics
+      auth:
+        type: bearer
+        credentials: SECRET_REF_DIAGNOSTICS_API
+      capabilities:
+        - run_health_check
+        - get_system_status
+
+  autonomy:
+    level: supervised
+    approval_required: false
+    allowed_actions:
+      - search_knowledge_base
+      - create_ticket
+      - update_ticket
+      - run_diagnostics
+    blocked_actions:
+      - delete_data
+      - access_production_db
+      - modify_user_accounts
+
+  constraints:
+    cost:
+      maxTokensPerDay: 1000000
+      maxCostPerDay: 50.0
+      currency: USD
+    performance:
+      maxLatencySeconds: 10
+      maxConcurrentRequests: 100
+      timeoutSeconds: 60
+    resources:
+      cpu: "1"
+      memory: 2Gi
+
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+      endpoint: https://traces.example.com
+    metrics:
+      enabled: true
+      exporter: prometheus
+    logging:
+      level: info
+      format: json
+```
+
+## Role Field Guidelines
+
+The `role` field is the most important part of the agent specification. It defines the agent's behavior through a system prompt.
+
+### Best Practices
+
+**Be specific about responsibilities:**
+```yaml
+role: |
+  You are a code reviewer specializing in Python security.
+
+  Review code for:
+  - SQL injection vulnerabilities
+  - XSS attack vectors
+  - Authentication/authorization issues
+  - Secrets in code
+  - Dependency vulnerabilities
+```
+
+**Define communication style:**
+```yaml
+role: |
+  You are a documentation writer.
+
+  Writing style:
+  - Clear and concise
+  - Active voice
+  - Examples for every feature
+  - Beginner-friendly explanations
+  - Professional tone
+```
+
+**Set boundaries:**
+```yaml
+role: |
+  You are a data analyst assistant.
+
+  You CAN:
+  - Query databases for analysis
+  - Generate visualizations
+  - Explain statistical concepts
+  - Recommend analytical approaches
+
+  You CANNOT:
+  - Modify production data
+  - Grant database access
+  - Make business decisions
+  - Share sensitive customer data
+```
+
+**Include domain knowledge:**
+```yaml
+role: |
+  You are a Kubernetes troubleshooting expert.
+
+  Expertise areas:
+  - Pod scheduling and resource constraints
+  - Network policies and service mesh
+  - Volume and storage issues
+  - RBAC and security contexts
+  - Custom resource definitions
+
+  Always ask for kubectl output before making recommendations.
+```
+
+### Anti-Patterns
+
+**Too vague:**
+```yaml
+# ❌ Bad
+role: "You are a helpful assistant."
+
+# ✅ Good
+role: |
+  You are a customer onboarding specialist who helps new users
+  set up their accounts, configure integrations, and learn core features.
+```
+
+**Too rigid:**
+```yaml
+# ❌ Bad - too prescriptive
+role: |
+  Step 1: Always greet the user
+  Step 2: Ask for their problem
+  Step 3: Provide exactly 3 solutions
+  Step 4: Say goodbye
+
+# ✅ Good - provides guidance with flexibility
+role: |
+  You are a friendly problem solver. Greet users warmly, understand
+  their needs, and provide practical solutions. Adapt your approach
+  based on user expertise level.
+```
+
+**Conflicting instructions:**
+```yaml
+# ❌ Bad
+role: |
+  Be extremely concise. Always provide detailed explanations.
+  Never use technical jargon. Use industry-standard terminology.
+
+# ✅ Good
+role: |
+  Provide clear explanations appropriate for the user's expertise.
+  Start with simple terms, then introduce technical terminology with definitions.
+```
+
+## Taxonomy
+
+The optional `taxonomy` field classifies the agent by domain, subdomain, and capability. This enables:
+
+- **Discovery** - Find agents by functional area
+- **Organization** - Group related agents
+- **Routing** - Direct requests to specialized agents
+- **Analytics** - Track agent usage by category
+
+See [Taxonomy Reference](./taxonomy.md) for details.
+
+```yaml
+spec:
+  taxonomy:
+    domain: infrastructure
+    subdomain: kubernetes
+    capability: troubleshooting
+```
+
+## LLM Configuration
+
+The optional `llm` field configures the language model provider and parameters. If omitted, the deployment platform chooses defaults.
+
+See [LLM Configuration Reference](./llm-config.md) for details.
+
+```yaml
+spec:
+  llm:
+    provider: openai
+    model: gpt-4o
+    temperature: 0.7
+    maxTokens: 2048
+```
+
+## Tools
+
+The optional `tools` array defines capabilities available to the agent. Tools can be:
+
+- **MCP servers** - Model Context Protocol integrations
+- **Kubernetes resources** - Direct K8s API access
+- **HTTP APIs** - REST/GraphQL endpoints
+- **gRPC services** - gRPC endpoints
+- **Custom functions** - Platform-specific functions
+
+See [Tools Reference](./tools.md) for details.
+
+```yaml
+spec:
+  tools:
+    - type: mcp
+      server: filesystem
+      capabilities:
+        - read_file
+        - write_file
+    - type: http
+      endpoint: https://api.github.com
+      auth:
+        type: bearer
+        credentials: SECRET_REF_GITHUB_TOKEN
+```
+
+## Autonomy
+
+The optional `autonomy` field controls decision-making level and action permissions.
+
+See [Autonomy Reference](./autonomy.md) for details.
+
+```yaml
+spec:
+  autonomy:
+    level: autonomous
+    approval_required: false
+    allowed_actions:
+      - read_data
+      - analyze
+      - generate_report
+    blocked_actions:
+      - delete_data
+      - modify_schema
+```
+
+## Constraints
+
+The optional `constraints` field sets limits on cost, performance, and resources.
+
+See [Constraints Reference](./constraints.md) for details.
+
+```yaml
+spec:
+  constraints:
+    cost:
+      maxTokensPerDay: 1000000
+      maxCostPerDay: 25.0
+      currency: USD
+    performance:
+      maxLatencySeconds: 5
+      timeoutSeconds: 30
+```
+
+## Observability
+
+The optional `observability` field configures tracing, metrics, and logging.
+
+See [Observability Reference](./observability.md) for details.
+
+```yaml
+spec:
+  observability:
+    tracing:
+      enabled: true
+      exporter: jaeger
+    metrics:
+      enabled: true
+      exporter: prometheus
+    logging:
+      level: debug
+      format: json
+```
+
+## Minimal Example
+
+The only required field in `spec` is `role`:
+
+```yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+metadata:
+  name: simple-agent
+spec:
+  role: You are a helpful assistant that answers questions concisely.
+```
+
+## Multi-line Role Example
+
+Use YAML block scalars for complex role definitions:
+
+```yaml
+spec:
+  role: |
+    You are an expert DevOps engineer specializing in CI/CD pipelines.
+
+    Core competencies:
+    - GitHub Actions workflow optimization
+    - Docker multi-stage build strategies
+    - Kubernetes deployment manifests
+    - Terraform infrastructure as code
+    - Secret management and security scanning
+
+    When analyzing pipelines:
+    1. Identify security vulnerabilities
+    2. Suggest performance optimizations
+    3. Recommend best practices
+    4. Provide working code examples
+
+    Always explain the reasoning behind your recommendations.
+```
+
+## Related Objects
+
+- [Taxonomy](./taxonomy.md) - Agent classification
+- [LLM Configuration](./llm-config.md) - Language model settings
+- [Tools](./tools.md) - Available capabilities
+- [Autonomy](./autonomy.md) - Decision-making controls
+- [Constraints](./constraints.md) - Operational limits
+- [Observability](./observability.md) - Monitoring configuration
+- [OSSA Manifest](./ossa-manifest.md) - Root object
+
+## Validation
+
+The `spec` object is validated against the JSON Schema:
+```
+https://openstandardagents.org/schemas/v0.2.x/agent.json#/definitions/AgentSpec
+```
+
+Required fields:
+- `role` must be a non-empty string
+
+All other fields are optional and validated according to their respective schemas.