@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/for-audiences/Architects.md

@@ -0,0 +1,224 @@
+---
+title: "Architects"
+---
+
+# For Architects & Platform Engineers
+
+Design and govern multi-agent systems using OSSA's standard architecture patterns.
+
+## Architecture Overview
+
+### OSSA's Role in Agent Architecture
+
+OSSA provides:
+- **Standard Contract**: Framework-agnostic agent definition
+- **Portability**: Move agents across infrastructures
+- **Governance**: Standard format enables policy enforcement
+- **Observability**: Consistent monitoring across agents
+
+## Design Patterns
+
+### Pattern 1: Single Agent
+
+Simple, standalone agent:
+
+```yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+metadata:
+  name: standalone-agent
+spec:
+  role: Agent description
+  llm: { ... }
+  tools: [ ... ]
+```
+
+### Pattern 2: Agent Orchestration
+
+Orchestrator coordinates multiple agents:
+
+```yaml
+# Orchestrator Agent
+spec:
+  role: Coordinate workflow
+  tools:
+    - type: http
+      name: invoke_worker_agent
+      endpoint: http://worker-agent:8080/api
+```
+
+See: [Integration Patterns](../Examples/Integration-Patterns)
+
+### Pattern 3: Agent Mesh
+
+Agents communicate directly:
+
+- Peer-to-peer communication
+- Event-driven patterns
+- Service mesh integration
+
+## Multi-Agent Systems
+
+### Architecture Decisions
+
+1. **Orchestration vs. Choreography**
+   - Orchestration: Central coordinator
+   - Choreography: Distributed coordination
+
+2. **Communication Patterns**
+   - HTTP/gRPC for synchronous
+   - Message queues for asynchronous
+   - MCP for tool sharing
+
+3. **State Management**
+   - Stateless agents (recommended)
+   - Shared state via external store
+   - Event sourcing patterns
+
+## Governance & Compliance
+
+### Policy Enforcement
+
+OSSA enables:
+
+- **Cost Controls**: Declarative cost limits
+- **Security Policies**: Standard security configuration
+- **Compliance**: Automated compliance checking
+- **Audit Logging**: Standard observability
+
+### Example: Compliance Agent
+
+```yaml
+spec:
+  role: Compliance checking agent
+  constraints:
+    cost:
+      maxCostPerDay: 50.00
+  observability:
+    logging:
+      level: info
+      format: json
+```
+
+## Infrastructure Planning
+
+### Deployment Options
+
+1. **Kubernetes**
+   - Native K8s resources
+   - Service mesh integration
+   - Auto-scaling
+
+2. **Serverless**
+   - AWS Lambda
+   - Google Cloud Functions
+   - Azure Functions
+
+3. **Container Orchestration**
+   - Docker Compose
+   - Nomad
+   - Custom orchestration
+
+### Resource Planning
+
+```yaml
+constraints:
+  resources:
+    cpu: "500m"
+    memory: "1Gi"
+  performance:
+    maxConcurrentRequests: 10
+```
+
+## Observability Strategy
+
+### Distributed Tracing
+
+```yaml
+observability:
+  tracing:
+    enabled: true
+    exporter: otlp
+    endpoint: http://jaeger:4318
+```
+
+### Metrics Collection
+
+```yaml
+observability:
+  metrics:
+    enabled: true
+    exporter: prometheus
+    endpoint: http://prometheus:9090/metrics
+```
+
+### Logging Strategy
+
+```yaml
+observability:
+  logging:
+    level: info
+    format: json
+```
+
+## Cost Management
+
+### Cost Constraints
+
+```yaml
+constraints:
+  cost:
+    maxTokensPerDay: 100000
+    maxCostPerDay: 10.00
+    currency: USD
+```
+
+### Cost Optimization Strategies
+
+1. **Model Selection**: Use appropriate model for task
+2. **Token Limits**: Set maxTokens per request
+3. **Caching**: Cache responses where possible
+4. **Batching**: Batch requests when possible
+
+## Security Architecture
+
+### Authentication
+
+```yaml
+tools:
+  - type: http
+    auth:
+      type: bearer
+      credentials: API_KEY_SECRET
+```
+
+### Network Security
+
+- Service mesh integration
+- mTLS between agents
+- Network policies
+- API gateways
+
+## Scalability Patterns
+
+### Horizontal Scaling
+
+- Stateless agents
+- Load balancing
+- Auto-scaling based on metrics
+
+### Vertical Scaling
+
+```yaml
+constraints:
+  resources:
+    cpu: "2"
+    memory: "4Gi"
+```
+
+## Related Resources
+
+- [Technical Documentation](../Technical/Specification-Deep-Dive)
+- [Integration Patterns](../Examples/Integration-Patterns)
+- [Enterprise Guide](../For-Audiences/Enterprises)
+

package/website/content/docs/for-audiences/Developers.md

@@ -0,0 +1,220 @@
+---
+title: "Developers"
+---
+
+# For Developers
+
+Build OSSA-compliant agents using your preferred framework and deploy anywhere.
+
+## Quick Start
+
+### 1. Install OSSA CLI
+
+```bash
+npm install -g @bluefly/open-standards-scalable-agents
+```
+
+### 2. Generate Your First Agent
+
+```bash
+ossa generate chat --name "My Agent" --output agent.ossa.yaml
+```
+
+### 3. Validate
+
+```bash
+ossa validate agent.ossa.yaml
+```
+
+### 4. Deploy
+
+Use your preferred deployment method - OSSA doesn't care!
+
+## Development Workflow
+
+### Build with Your Framework
+
+OSSA is framework-agnostic. Build agents with:
+
+- **LangChain** - Python-based agent framework
+- **Anthropic SDK** - TypeScript/Python SDK
+- **Custom Code** - Your own implementation
+- **Any Framework** - OSSA works with all
+
+### Validate with OSSA
+
+Once built, validate against OSSA:
+
+```bash
+ossa validate my-agent.ossa.yaml
+```
+
+### Deploy Anywhere
+
+Deploy to:
+- Kubernetes
+- Docker
+- Serverless (AWS Lambda, Google Cloud Functions)
+- On-premise
+- Your infrastructure
+
+## Migration from Existing Frameworks
+
+### LangChain → OSSA
+
+See: [Migration Guide: LangChain](../Examples/Migration-Guides/from-langchain-to-ossa)
+
+### Anthropic SDK → OSSA
+
+Coming soon: Anthropic SDK migration guide
+
+### Custom Framework → OSSA
+
+1. Map your agent structure to OSSA format
+2. Define tools/capabilities
+3. Configure LLM settings
+4. Add observability
+5. Validate
+
+## API Reference
+
+### CLI Commands
+
+```bash
+# Validate agent
+ossa validate <path> [--schema <version>] [--verbose]
+
+# Generate agent
+ossa generate <type> [--name <name>] [--output <file>]
+
+# Migrate agent
+ossa migrate <source> [--target-version <version>]
+```
+
+### Programmatic API
+
+```typescript
+import { ValidationService } from '@bluefly/open-standards-scalable-agents/validation';
+import { GenerationService } from '@bluefly/open-standards-scalable-agents/generation';
+
+// Validate
+const validationService = new ValidationService();
+const result = await validationService.validate(manifest, '0.2.2');
+
+// Generate
+const generationService = new GenerationService();
+const manifest = await generationService.generate(template);
+```
+
+## Best Practices
+
+### 1. Use Descriptive Names
+
+```yaml
+metadata:
+  name: customer-support-agent  # Good
+  # name: agent1  # Bad
+```
+
+### 2. Add Comprehensive Descriptions
+
+```yaml
+metadata:
+  description: |
+    Customer support agent that handles:
+    - Product inquiries
+    - Order status
+    - Returns and refunds
+```
+
+### 3. Configure Constraints
+
+```yaml
+constraints:
+  cost:
+    maxTokensPerDay: 100000
+    maxCostPerDay: 10.00
+  performance:
+    maxLatencySeconds: 5.0
+```
+
+### 4. Enable Observability
+
+```yaml
+observability:
+  tracing:
+    enabled: true
+  metrics:
+    enabled: true
+  logging:
+    level: info
+```
+
+## Common Patterns
+
+### Pattern 1: Simple Chat Agent
+
+```yaml
+spec:
+  role: You are a helpful assistant
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+  tools: []
+```
+
+### Pattern 2: Agent with Tools
+
+```yaml
+spec:
+  role: You are a research assistant
+  llm:
+    provider: openai
+    model: gpt-4
+  tools:
+    - type: http
+      name: web_search
+      endpoint: https://api.search.com/search
+```
+
+### Pattern 3: Multi-Agent Orchestration
+
+See: [Integration Patterns](../Examples/Integration-Patterns)
+
+## Testing
+
+### Validate Before Deployment
+
+```bash
+ossa validate agent.ossa.yaml --verbose
+```
+
+### Test with Examples
+
+```bash
+# Validate all examples
+npm run validate:examples
+```
+
+## Troubleshooting
+
+### Validation Errors
+
+```bash
+# Get detailed error messages
+ossa validate agent.ossa.yaml --verbose
+```
+
+### Common Issues
+
+1. **Missing required fields**: Check schema reference
+2. **Invalid tool types**: Use supported types (http, function, mcp, etc.)
+3. **LLM provider not supported**: Check provider enum values
+
+## Resources
+
+- [Getting Started](../Getting-Started/Hello-World)
+- [API Reference](../Technical/CLI-Reference)
+- [Migration Guides](../Examples/Migration-Guides)
+- [Examples](../Examples/Getting-Started-Examples)
+

package/website/content/docs/for-audiences/Enterprises.md

@@ -0,0 +1,256 @@
+---
+title: "Enterprises"
+---
+
+# For Enterprises
+
+Adopt OSSA for vendor independence, compliance, and enterprise-scale agent management.
+
+## Enterprise Benefits
+
+### Vendor Independence
+
+✅ **No Framework Lock-in**: Build with any framework, deploy anywhere  
+✅ **Portable Agents**: Move agents between teams, clouds, organizations  
+✅ **Standard Contracts**: Consistent agent definitions across teams  
+✅ **Multi-Cloud Ready**: Deploy to AWS, GCP, Azure, on-premise  
+
+### Compliance & Governance
+
+✅ **Standard Format**: Enables automated compliance checking  
+✅ **Audit Logging**: Standard observability across all agents  
+✅ **Cost Controls**: Declarative cost limits prevent overspending  
+✅ **Security Policies**: Standard security configuration  
+
+### Scalability
+
+✅ **Enterprise Patterns**: Multi-agent orchestration, service mesh  
+✅ **Observability**: Distributed tracing, metrics, logging  
+✅ **Resource Management**: Declarative resource constraints  
+✅ **Performance Controls**: Latency and throughput limits  
+
+## Enterprise Adoption Guide
+
+### Phase 1: Evaluation
+
+1. **Understand OSSA**
+   - Review specification
+   - Study examples
+   - Evaluate fit
+
+2. **Pilot Project**
+   - Select one team/project
+   - Migrate existing agent
+   - Measure results
+
+3. **Assess Impact**
+   - Portability gains
+   - Cost savings
+   - Compliance improvements
+
+### Phase 2: Rollout
+
+1. **Training**
+   - Developer training
+   - Architecture guidelines
+   - Best practices
+
+2. **Tooling**
+   - CI/CD integration
+   - Validation pipelines
+   - Deployment automation
+
+3. **Governance**
+   - Policy enforcement
+   - Cost management
+   - Security controls
+
+### Phase 3: Scale
+
+1. **Organization-Wide**
+   - All teams adopt OSSA
+   - Central registry
+   - Shared patterns
+
+2. **Optimization**
+   - Cost optimization
+   - Performance tuning
+   - Pattern refinement
+
+## Compliance & Security
+
+### Compliance Features
+
+OSSA enables:
+
+- **FedRAMP**: Compliance scanning agents
+- **SOC 2**: Audit logging and controls
+- **GDPR**: Data residency and encryption
+- **HIPAA**: Healthcare compliance patterns
+
+### Example: Compliance Agent
+
+```yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+
+metadata:
+  name: compliance-scanner
+  labels:
+    compliance: fedramp
+    classification: internal
+
+spec:
+  role: Scan infrastructure for compliance
+  constraints:
+    cost:
+      maxCostPerDay: 50.00
+  observability:
+    logging:
+      level: info
+      format: json
+    audit: true
+```
+
+## Cost Management
+
+### Cost Controls
+
+```yaml
+constraints:
+  cost:
+    maxTokensPerDay: 1000000
+    maxCostPerDay: 100.00
+    currency: USD
+```
+
+### Cost Optimization
+
+1. **Model Selection**: Use appropriate models for tasks
+2. **Token Limits**: Set realistic maxTokens
+3. **Caching**: Cache responses
+4. **Monitoring**: Track costs per agent
+
+## Security Architecture
+
+### Authentication & Authorization
+
+```yaml
+tools:
+  - type: http
+    auth:
+      type: mtls
+      credentials: CLIENT_CERT_SECRET
+```
+
+### Network Security
+
+- Service mesh integration
+- mTLS between agents
+- Network policies
+- API gateways
+
+### Secrets Management
+
+- Use secret references (not values)
+- Integrate with secret managers
+- Rotate credentials regularly
+
+## Governance
+
+### Agent Lifecycle
+
+1. **Development**: Validate with OSSA CLI
+2. **Testing**: Automated validation in CI/CD
+3. **Deployment**: Standardized deployment process
+4. **Monitoring**: Observability and cost tracking
+5. **Retirement**: Deprecation and cleanup
+
+### Policy Enforcement
+
+- **Cost Limits**: Enforce via constraints
+- **Security**: Standard security config
+- **Compliance**: Automated compliance checking
+- **Quality**: Validation requirements
+
+## Multi-Tenant Support
+
+### Tenant Isolation
+
+- Separate agent namespaces
+- Resource quotas per tenant
+- Cost tracking per tenant
+- Access controls
+
+### Example: Multi-Tenant Agent
+
+```yaml
+metadata:
+  name: tenant-{tenant-id}-agent
+  labels:
+    tenant: {tenant-id}
+spec:
+  constraints:
+    cost:
+      maxCostPerDay: 10.00  # Per tenant
+```
+
+## Enterprise Patterns
+
+### Pattern 1: Centralized Orchestration
+
+- Central orchestrator agent
+- Worker agents per team
+- Shared infrastructure
+- Centralized monitoring
+
+### Pattern 2: Federated Agents
+
+- Team-owned agents
+- Shared registry
+- Cross-team communication
+- Distributed governance
+
+### Pattern 3: Hybrid Approach
+
+- Mix of centralized and federated
+- Core services centralized
+- Team services federated
+- Shared patterns and tools
+
+## Migration Strategy
+
+### From Framework-Specific Agents
+
+1. **Inventory**: List all existing agents
+2. **Prioritize**: Start with high-value agents
+3. **Migrate**: Convert to OSSA format
+4. **Validate**: Ensure correctness
+5. **Deploy**: Standard deployment process
+
+### Migration Tools
+
+- OSSA CLI migration command
+- Custom migration scripts
+- Framework-specific guides
+
+## Support & Resources
+
+### Enterprise Support
+
+- [GitLab Issues](https://github.com/blueflyio/openstandardagents/issues)
+- [Documentation](../Technical/Specification-Deep-Dive)
+- [Examples](../Examples/Enterprise-Examples)
+
+### Training
+
+- Architecture workshops
+- Developer training
+- Best practices sessions
+
+## Related Resources
+
+- [Architecture Guide](../For-Audiences/Architects)
+- [Technical Documentation](../Technical/Specification-Deep-Dive)
+- [Enterprise Examples](../Examples/Enterprise-Examples)
+