@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/website/content/docs/ecosystem/overview.md

@@ -1,366 +0,0 @@
----
-title: Ecosystem Overview
-description: Comprehensive overview of the Open Standard Agents ecosystem, integrations, and interoperability model
----
-
-# Ecosystem Overview
-
-The Open Standard Agents (OSSA) ecosystem encompasses a wide range of frameworks, runtimes, tools, and integrations that enable vendor-neutral AI agent orchestration. This document provides a comprehensive overview of how OSSA enables interoperability across the agent landscape.
-
-## Architecture Model
-
-OSSA follows a layered architecture that separates concerns and enables flexibility:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Application Layer                         │
-│   (Your Agents - CrewAI, LangChain, kAgent, Custom, etc.)   │
-└─────────────────────────────────────────────────────────────┘
-                            ↕
-┌─────────────────────────────────────────────────────────────┐
-│                   OSSA Specification Layer                   │
-│        (Standard Manifest, Schema Validation, Tools)         │
-└─────────────────────────────────────────────────────────────┘
-                            ↕
-┌─────────────────────────────────────────────────────────────┐
-│                    Framework Layer                           │
-│  (LangChain, CrewAI, Anthropic MCP, OpenAI, Langflow, etc.) │
-└─────────────────────────────────────────────────────────────┘
-                            ↕
-┌─────────────────────────────────────────────────────────────┐
-│                     Runtime Layer                            │
-│   (Docker, Kubernetes, Lambda, Cloud Functions, etc.)       │
-└─────────────────────────────────────────────────────────────┘
-                            ↕
-┌─────────────────────────────────────────────────────────────┐
-│                  Infrastructure Layer                        │
-│      (Cloud Providers, On-Premise, Edge, Hybrid)            │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Core Principles
-
-### 1. Framework Agnostic
-
-OSSA is designed to work with any AI agent framework. Whether you're using:
-
-- **LangChain** for chain-based workflows
-- **CrewAI** for multi-agent coordination
-- **kAgent** for native OSSA implementation
-- **Anthropic MCP** for Claude integration
-- **OpenAI Assistants** for GPT-based agents
-- **Custom frameworks** built in-house
-
-All frameworks can produce and consume OSSA manifests, enabling seamless interoperability.
-
-### 2. Runtime Portable
-
-Deploy the same agent definition across:
-
-- **Containers**: Docker, Podman
-- **Orchestrators**: Kubernetes, Docker Swarm
-- **Serverless**: AWS Lambda, Google Cloud Functions, Azure Functions
-- **Edge**: Cloudflare Workers, AWS Lambda@Edge
-- **On-Premise**: Bare metal servers, private clouds
-
-The OSSA manifest travels with your agent, ensuring consistent behavior across environments.
-
-### 3. Tool Extensible
-
-OSSA supports multiple tool integration patterns:
-
-- **MCP Servers**: Model Context Protocol for standardized tool interfaces
-- **REST APIs**: OpenAPI/Swagger-based HTTP services
-- **GraphQL**: Query-based data fetching
-- **gRPC**: High-performance binary protocols
-- **WebSockets**: Real-time bidirectional communication
-- **Native Functions**: Language-specific tool implementations
-
-### 4. Security First
-
-Built-in security features include:
-
-- **Capability-based permissions**: Fine-grained access control
-- **Secret management**: Secure credential handling
-- **Audit trails**: Complete operation logging
-- **Sandboxing**: Isolated execution environments
-- **Compliance**: SOC 2, HIPAA, GDPR-ready
-
-## Integration Patterns
-
-### Pattern 1: Direct Framework Integration
-
-Frameworks implement OSSA manifest import/export:
-
-```typescript
-// LangChain example
-import { OSSAAgent } from '@ossa/langchain';
-
-const agent = OSSAAgent.fromManifest('agent-manifest.json');
-await agent.execute({ input: 'Hello world' });
-```
-
-### Pattern 2: Runtime Adapter
-
-Runtimes provide OSSA-to-native translation:
-
-```yaml
-# Kubernetes deployment
-apiVersion: ossa.io/v1
-kind: Agent
-metadata:
-  name: my-agent
-spec:
-  manifestRef:
-    name: agent-manifest
-    namespace: default
-```
-
-### Pattern 3: Middleware Translation
-
-Middleware layers bridge OSSA and proprietary formats:
-
-```bash
-# Convert OpenAI Assistant to OSSA
-ossa convert \
-  --from openai-assistant \
-  --to ossa \
-  --input assistant.json \
-  --output manifest.json
-```
-
-## Ecosystem Components
-
-### Core Specification
-
-- **Schema**: JSON Schema defining manifest structure
-- **Validator**: Command-line tool for manifest validation
-- **TypeScript Types**: Type definitions for TypeScript/JavaScript
-- **Python Types**: Type definitions for Python (Pydantic models)
-
-### Framework Adapters
-
-- **@ossa/langchain**: LangChain integration
-- **@ossa/crewai**: CrewAI integration
-- **@ossa/mcp**: Anthropic MCP integration
-- **@ossa/openai**: OpenAI Assistants integration
-- **@ossa/langflow**: Langflow visual builder integration
-
-### Runtime Support
-
-- **Docker Images**: Pre-built containers for OSSA agents
-- **Kubernetes Operators**: Custom resource definitions for K8s
-- **Serverless Templates**: CloudFormation, Terraform modules
-- **Edge Workers**: Cloudflare Workers, Lambda@Edge templates
-
-### Development Tools
-
-- **OSSA CLI**: Command-line interface for validation, conversion, deployment
-- **VSCode Extension**: IntelliSense, validation, snippets
-- **Playground**: Interactive web-based agent testing
-- **Schema Explorer**: Visual schema documentation
-
-### Monitoring & Observability
-
-- **OpenTelemetry**: Distributed tracing integration
-- **Prometheus**: Metrics collection and alerting
-- **Structured Logging**: JSON-formatted logs with correlation IDs
-- **Health Checks**: Readiness and liveness probes
-
-## Data Flow
-
-### Agent Lifecycle with OSSA
-
-```mermaid
-graph TD
-    A[Define Agent] --> B[Write OSSA Manifest]
-    B --> C[Validate Schema]
-    C --> D{Valid?}
-    D -->|No| E[Fix Errors]
-    E --> B
-    D -->|Yes| F[Package Agent]
-    F --> G[Deploy to Runtime]
-    G --> H[Runtime Loads Manifest]
-    H --> I[Initialize Framework]
-    I --> J[Register Tools]
-    J --> K[Agent Ready]
-    K --> L[Execute Tasks]
-    L --> M[Log/Monitor]
-    M --> N{Continue?}
-    N -->|Yes| L
-    N -->|No| O[Cleanup]
-```
-
-## Interoperability Model
-
-### Multi-Framework Orchestration
-
-OSSA enables coordinating agents across different frameworks:
-
-```json
-{
-  "name": "hybrid-system",
-  "type": "orchestrator",
-  "agents": [
-    {
-      "id": "researcher",
-      "framework": "langchain",
-      "manifestRef": "./langchain-researcher.json"
-    },
-    {
-      "id": "writer",
-      "framework": "crewai",
-      "manifestRef": "./crewai-writer.json"
-    },
-    {
-      "id": "reviewer",
-      "framework": "openai",
-      "manifestRef": "./openai-reviewer.json"
-    }
-  ],
-  "workflow": {
-    "steps": [
-      { "agent": "researcher", "output": "research_data" },
-      { "agent": "writer", "input": "research_data", "output": "draft" },
-      { "agent": "reviewer", "input": "draft", "output": "final" }
-    ]
-  }
-}
-```
-
-### Cross-Runtime Deployment
-
-Deploy agents to different runtimes based on requirements:
-
-- **CPU-Intensive**: Kubernetes with GPU nodes
-- **Event-Driven**: AWS Lambda with SQS triggers
-- **Low-Latency**: Cloudflare Workers at the edge
-- **Stateful**: EC2 instances with persistent storage
-
-## Community Ecosystem
-
-### Open Source Projects
-
-- **kAgent**: Native OSSA framework (reference implementation)
-- **OSSA Validator**: Schema validation and linting
-- **OSSA Playground**: Web-based testing environment
-- **OSSA CLI**: Command-line tools
-
-### Commercial Integrations
-
-- **LangSmith**: LangChain deployment platform
-- **Crew Studio**: CrewAI management console
-- **Claude for Enterprise**: Anthropic's enterprise offering
-- **OpenAI Teams**: Team collaboration features
-
-### Community Resources
-
-- **Discord**: Real-time chat and support
-- **GitLab**: Source code, issues, discussions
-- **Documentation**: Comprehensive guides and references
-- **Examples**: Real-world implementation patterns
-
-## Getting Started
-
-### For Framework Developers
-
-Integrate OSSA into your framework:
-
-1. **Implement Manifest Parser**: Read OSSA JSON/YAML
-2. **Map to Native Types**: Convert OSSA concepts to your framework
-3. **Validate Schema**: Ensure manifest compliance
-4. **Export Manifest**: Generate OSSA from native definitions
-5. **Document Integration**: Provide migration guides
-
-### For Runtime Developers
-
-Add OSSA support to your runtime:
-
-1. **Parse Manifest**: Extract deployment requirements
-2. **Provision Resources**: Create necessary infrastructure
-3. **Initialize Framework**: Setup agent execution environment
-4. **Monitor Lifecycle**: Track agent health and performance
-5. **Handle Cleanup**: Properly tear down resources
-
-### For Tool Developers
-
-Create OSSA-compatible tools:
-
-1. **Define Schema**: Describe tool inputs/outputs
-2. **Implement Interface**: Follow OSSA tool protocol
-3. **Add Documentation**: Provide usage examples
-4. **Register Tool**: Make discoverable in ecosystem
-5. **Maintain Compatibility**: Keep up with spec updates
-
-## Best Practices
-
-### Manifest Design
-
-- **Keep it simple**: Start with minimal required fields
-- **Document thoroughly**: Use descriptions for all properties
-- **Version explicitly**: Always specify OSSA spec version
-- **Validate early**: Run validation before deployment
-- **Test thoroughly**: Verify behavior across target runtimes
-
-### Integration Strategy
-
-- **Start small**: Integrate one agent type first
-- **Iterate quickly**: Get feedback from real usage
-- **Document everything**: Provide clear migration paths
-- **Support community**: Help users adopt your integration
-- **Stay updated**: Track OSSA specification changes
-
-### Security Considerations
-
-- **Never embed secrets**: Use secret references only
-- **Validate inputs**: Sanitize all user-provided data
-- **Limit permissions**: Grant minimum necessary capabilities
-- **Audit access**: Log all sensitive operations
-- **Update dependencies**: Keep frameworks and tools current
-
-## Roadmap
-
-### Current Focus (2024)
-
-- **Framework Parity**: Complete integrations for major frameworks
-- **Runtime Support**: Expand deployment options
-- **Tool Ecosystem**: Grow available OSSA-compatible tools
-- **Documentation**: Comprehensive guides and examples
-
-### Near Term (2025)
-
-- **Advanced Orchestration**: Multi-agent coordination patterns
-- **Observability**: Enhanced monitoring and debugging
-- **Performance**: Optimize manifest parsing and validation
-- **Security**: Enhanced secret management and access control
-
-### Long Term (2026+)
-
-- **Federation**: Cross-organization agent collaboration
-- **Marketplace**: Centralized agent and tool registry
-- **Certification**: Compliance and compatibility testing
-- **Governance**: Community-driven specification evolution
-
-## Contributing
-
-The OSSA ecosystem thrives on community contributions:
-
-- **Report Issues**: Help identify bugs and gaps
-- **Submit PRs**: Contribute code and documentation
-- **Share Examples**: Demonstrate real-world usage
-- **Provide Feedback**: Guide specification evolution
-- **Build Integrations**: Extend ecosystem reach
-
-Visit [github.com/blueflyio/openstandardagents](https://github.com/blueflyio/openstandardagents) to get involved.
-
-## Resources
-
-- **Specification**: Full OSSA specification reference
-- **Examples**: Real-world implementation examples
-- **API Reference**: Detailed API documentation
-- **Community**: Discord, forums, and social media
-- **Blog**: Updates, tutorials, and case studies
-
----
-
-**Next Steps**: Explore [Framework Support](/docs/ecosystem/framework-support) for detailed integration guides.

package/website/content/docs/examples/AIFlow-Framework-Integration-with-OSSA.md

@@ -1,107 +0,0 @@
----
-title: "AIFlow Framework Integration with OSSA"
----
-
-# AIFlow Framework Integration with OSSA
-
-## Overview
-
-AIFlow is a Python-based social agent framework that enables personality-driven, emotionally intelligent AI agents for autonomous social media content generation. This integration demonstrates how AIFlow agents are wrapped in OSSA 1.0 manifests for Kubernetes orchestration and deployment through agent-buildkit.
-
-For complete integration analysis, see: [agent-buildkit AIFlow Integration Guide](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
-
-## Core Components
-
-### OSSA Manifest
-
-**Location**: [agent-buildkit/examples/aiflow-integration/social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
-
-The manifest defines the agent's identity, runtime configuration, capabilities, and deployment requirements. It conforms to OSSA 1.0 specification.
-
-**Key Manifest Sections**:
-
-- **Agent Identity**: `social-agent-aiflow`, version 1.0.0, role: chat
-- **Runtime**: Docker image `aiflow/agent:1.0.0`, Python 3.12+, resource requirements
-- **Capabilities**: `generate_post`, `generate_response` with defined schemas
-- **Dependencies**: Required integration with `agent-brain` for cognitive functions
-- **Environment**: Required secrets for Anthropic API, Twitter API, Telegram Bot, PostgreSQL
-
-### OpenAPI Specification
-
-**Location**: [agent-buildkit/openapi/aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
-
-The OpenAPI 3.1 specification defines the REST API interface for the AIFlow agent, including:
-- FastAPI bridge endpoints for AIFlow Sia runtime
-- Request/response schemas for all capabilities
-- Kubernetes metadata extensions (x-k-agent) for orchestration
-- Health check endpoints and observability metrics
-
-### OSSA Schema
-
-**Location**: [OSSA/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
-
-JSON Schema definition for OSSA 1.0 manifest validation. All agent manifests must conform to this schema.
-
-## Validation
-
-### OSSA Manifest Validation
-
-Validate the manifest against OSSA 1.0 schema:
-
-```yaml
-ossa validate examples/aiflow-integration/social-agent-aiflow.ossa.yaml
-```
-
-This checks:
-- Schema compliance against OSSA 1.0 specification
-- Required fields and type correctness
-- Capability schema definitions
-- Dependency declarations
-- Environment variable definitions
-
-### OpenAPI Specification Validation
-
-Validate OpenAPI spec with strict mode and K-Agent metadata checks:
-
-```yaml
-buildkit openapi validate --spec openapi/aiflow-agent.openapi.yml --strict
-```
-
-This validates:
-- OpenAPI 3.1 syntax and semantics
-- x-k-agent extension metadata for Kubernetes
-- Endpoint schemas match OSSA capability definitions
-- Health check endpoint compliance
-
-## Deployment
-
-Deploy via agent-buildkit orchestration:
-
-```yaml
-buildkit orchestrate deploy --manifest examples/aiflow-integration/social-agent-aiflow.ossa.yaml
-```
-
-This generates Kubernetes manifests and deploys the agent with:
-- Rolling deployment strategy
-- Horizontal Pod Autoscaling (HPA)
-- Health checks and readiness probes
-- Service account and RBAC configuration
-- ConfigMap for character definitions
-- Persistent volume for memory database
-
-## Integration Architecture
-
-1. **OSSA Manifest** → Defines agent structure and requirements
-2. **OpenAPI Spec** → REST API contract with K8s metadata
-3. **FastAPI Bridge** → Wraps AIFlow Sia runtime in REST API
-4. **BuildKit Deployment** → Generates and applies K8s manifests
-5. **Runtime Orchestration** → Kubernetes manages agent lifecycle
-
-## Resources
-
-- **AIFlow Repository**: https://github.com/AIFlow-agent/AIFlow-Agent
-- **OSSA Project**: [openapi-ai-agents-standard](https://github.com/blueflyio/openstandardagents)
-- **Integration Guide**: [agent-buildkit Wiki](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
-- **OSSA Specification Schema**: [OSSA 1.0 Schema](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
-- **Example Manifest**: [social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
-- **OpenAPI Spec**: [aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)

package/website/content/docs/examples/Migration-Guides.md

@@ -1,214 +0,0 @@
----
-title: "Migration Guides"
----
-
-# Migration Guides
-
-Migrate agents from existing frameworks to OSSA format.
-
-## Available Migration Guides
-
-### LangChain → OSSA
-
-**Location**: [examples/migration-guides/from-langchain-to-ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/main/examples/migration-guides/from-langchain-to-ossa.yaml)
-
-**Covers**:
-- Simple LangChain agents
-- Agents with custom tools
-- Multi-agent systems
-- ReAct agents
-
-**Key Differences**:
-- LangChain: Code-based (Python)
-- OSSA: Declarative (YAML/JSON)
-- LangChain: Framework-specific
-- OSSA: Framework-agnostic
-
-### Anthropic SDK → OSSA
-
-**Status**: Coming soon
-
-**Will Cover**:
-- Anthropic SDK agent structure
-- Tool definitions
-- Message handling
-- Migration patterns
-
-### MCP-Only Agents → OSSA
-
-**Status**: Coming soon
-
-**Will Cover**:
-- MCP server integration
-- Tool exposure
-- Protocol bridging
-
-### Custom Framework → OSSA
-
-**General Approach**:
-
-1. **Map Agent Structure**
-   - Identify agent components
-   - Map to OSSA format
-   - Define capabilities
-
-2. **Define Tools**
-   - List available tools
-   - Map to OSSA tool types
-   - Configure endpoints
-
-3. **Configure LLM**
-   - Identify LLM provider
-   - Map model settings
-   - Set parameters
-
-4. **Add Observability**
-   - Configure tracing
-   - Set up metrics
-   - Enable logging
-
-5. **Validate**
-   - Use OSSA CLI
-   - Fix validation errors
-   - Test functionality
-
-## Migration Checklist
-
-### Pre-Migration
-
-- [ ] Inventory existing agents
-- [ ] Identify framework dependencies
-- [ ] Document current capabilities
-- [ ] Plan migration order
-
-### Migration
-
-- [ ] Convert agent structure
-- [ ] Map tools/capabilities
-- [ ] Configure LLM settings
-- [ ] Add observability
-- [ ] Set constraints
-
-### Post-Migration
-
-- [ ] Validate with OSSA CLI
-- [ ] Test functionality
-- [ ] Compare behavior
-- [ ] Update documentation
-- [ ] Deploy and monitor
-
-## Migration Tools
-
-### OSSA CLI
-
-```bash
-# Migrate agent between versions
-ossa migrate agent.yaml --target-version 0.2.2
-```
-
-### Manual Migration
-
-1. Use migration guide examples
-2. Follow step-by-step instructions
-3. Validate at each step
-4. Test thoroughly
-
-## Common Migration Patterns
-
-### Pattern 1: Simple Agent
-
-**Before** (Framework-specific):
-```python
-# Framework code
-agent = create_agent(llm, tools)
-```
-
-**After** (OSSA):
-```yaml
-apiVersion: ossa/v0.2.2
-kind: Agent
-spec:
-  role: Agent description
-  llm: { ... }
-  tools: [ ... ]
-```
-
-### Pattern 2: Agent with Tools
-
-**Before**:
-```python
-tools = [Tool1(), Tool2()]
-agent = create_agent(llm, tools)
-```
-
-**After**:
-```yaml
-spec:
-  tools:
-    - type: function
-      name: tool1
-    - type: http
-      name: tool2
-      endpoint: https://api.example.com
-```
-
-### Pattern 3: Multi-Agent System
-
-**Before**:
-```python
-orchestrator = create_orchestrator()
-worker1 = create_worker()
-worker2 = create_worker()
-```
-
-**After**:
-```yaml
-# orchestrator.ossa.yaml
-spec:
-  tools:
-    - type: http
-      name: invoke_worker
-      endpoint: http://worker:8080/api
-
-# worker.ossa.yaml
-spec:
-  role: Worker agent
-  # ...
-```
-
-## Validation
-
-### Validate Migrated Agent
-
-```bash
-ossa validate migrated-agent.ossa.yaml --verbose
-```
-
-### Compare Behavior
-
-1. Run original agent with test inputs
-2. Run OSSA agent with same inputs
-3. Compare outputs
-4. Verify functionality
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Missing Fields**: Check schema reference
-2. **Invalid Tool Types**: Use supported types
-3. **LLM Provider**: Verify provider support
-4. **Tool Configuration**: Check endpoint/auth config
-
-### Getting Help
-
-- [GitLab Issues](https://github.com/blueflyio/openstandardagents/issues)
-- [Documentation](../Technical/Specification-Deep-Dive)
-- [Examples](../Getting-Started-Examples)
-
-## Related
-
-- [Getting Started](../Getting-Started/Hello-World)
-- [Schema Reference](../Technical/Schema-Reference)
-- [Integration Patterns](Integration-Patterns)
-