@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/spec/v0.2.3/README.md

@@ -0,0 +1,154 @@
+# OSSA v0.2.3 Specification
+
+## Overview
+
+OSSA (Open Standard for Scalable AI Agents) v0.2.3 is a patch release focusing on documentation improvements and examples standardization. This version maintains full backward compatibility with v0.2.2.
+
+## What is OSSA?
+
+OSSA is to AI agents what OpenAPI is to REST APIs:
+- **Declarative**: Define agents using YAML/JSON manifests
+- **Framework-Agnostic**: Works with any AI framework (LangChain, CrewAI, OpenAI, Anthropic, etc.)
+- **Kubernetes-Style**: Familiar apiVersion/kind/metadata/spec structure
+- **Portable**: Export manifests from one platform, import to another
+
+## Schema Files
+
+- **ossa-0.2.3.schema.json**: JSON Schema validation for OSSA v0.2.3 manifests
+- **ossa-0.2.3.yaml**: YAML version of the schema
+
+## API Version
+
+```yaml
+apiVersion: ossa/v0.2.4
+```
+
+The schema accepts:
+- `ossa/v0.2.4` (recommended)
+- `ossa/v0.2.2` (backward compatible)
+- `ossa/v1` (forward compatible)
+
+## Key Features
+
+### Kubernetes-Style Manifest
+
+```yaml
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: my-agent
+  namespace: default
+  labels:
+    app: my-app
+    version: v1.0.0
+spec:
+  type: worker
+  runtime:
+    type: langchain
+    version: "0.3.0"
+  capabilities:
+    - query
+    - reasoning
+  config:
+    model: gpt-4
+    temperature: 0.7
+```
+
+### Framework Extensions
+
+OSSA supports framework-specific extensions:
+- **kAgent**: Kubernetes-native agents with CRDs
+- **Drupal**: CMS integration via ai_agents module
+- **OpenAI**: Assistants API format
+- **LangChain**: Tool/chain integration
+- **CrewAI**: Multi-agent orchestration
+
+## Changes from v0.2.2
+
+### Documentation & Examples (v0.2.3)
+- ✅ Enhanced inline documentation for all examples
+- ✅ Comprehensive migration guides (6 frameworks)
+- ✅ Improved README and getting-started guides
+- ✅ Added production-ready examples
+- ✅ GitLab wiki integration
+- ⚠️ **Schema unchanged** (backward compatible)
+
+This is a **documentation release** - no breaking changes to the schema.
+
+## Migration from v0.2.2
+
+**No migration required!** v0.2.3 is fully backward compatible with v0.2.2.
+
+Simply update your `apiVersion` field:
+
+```yaml
+# Before (v0.2.2)
+apiVersion: ossa/v0.2.2
+
+# After (v0.2.3)
+apiVersion: ossa/v0.2.4
+```
+
+Both versions are accepted by the same schema. See [migrations/v0.2.2-to-v0.2.3.md](migrations/v0.2.2-to-v0.2.3.md) for details.
+
+## Examples
+
+Located in `/examples/`:
+
+### Getting Started
+- `examples/getting-started/hello-world-complete.ossa.yaml`
+- `examples/getting-started/hello-world-minimal.ossa.yaml`
+
+### kAgent (Kubernetes)
+- `examples/kagent/k8s-troubleshooter.ossa.yaml`
+- `examples/kagent/compliance-validator.ossa.yaml`
+- `examples/kagent/security-scanner.ossa.yaml`
+- `examples/kagent/cost-optimizer.ossa.yaml`
+
+### Drupal Integration
+- `examples/drupal/gitlab-ml-recommender.ossa.yaml`
+
+### Integration Patterns
+- `examples/integration-patterns/agent-to-agent-orchestration.ossa.yaml`
+- `examples/integration-patterns/hybrid-reasoning.ossa.yaml`
+
+### Production
+- `examples/production/enterprise-agent.ossa.yaml`
+
+## Validation
+
+Validate your manifests using the OSSA CLI:
+
+```bash
+# Install
+npm install -g @bluefly/openstandardagents
+
+# Validate
+ossa validate my-agent.ossa.yaml
+
+# Generate new agent
+ossa generate my-new-agent --type worker
+```
+
+## Resources
+
+- **Main Docs**: https://github.com/blueflyio/openstandardagents
+- **Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
+- **Migration Guides**: https://github.com/blueflyio/openstandardagents/tree/main/spec
+- **OpenAPI Extensions**: https://github.com/blueflyio/openstandardagents/tree/main/docs
+
+## Compatibility Matrix
+
+| OSSA Version | kAgent | Drupal | OpenAI | LangChain | CrewAI | MCP |
+|--------------|--------|--------|--------|-----------|--------|-----|
+| v0.2.3       | ✅ v1α1 | ✅ v11  | ✅ v2   | ✅ v0.3    | ✅ v0.11| ✅  |
+| v0.2.2       | ✅ v1α1 | ✅ v11  | ✅ v2   | ✅ v0.3    | ✅ v0.11| ✅  |
+| v1.0 (legacy)| ⚠️ Partial | ❌ No | ❌ No | ⚠️ Partial | ❌ No  | ❌  |
+
+## License
+
+Apache 2.0
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

package/spec/v0.2.3/migrations/v0.2.2-to-v0.2.3.md

@@ -0,0 +1,343 @@
+# Migration Guide: OSSA v0.2.2 → v0.2.3
+
+**Migration Difficulty**: 🟢 **Trivial** (No breaking changes)
+**Estimated Time**: < 5 minutes
+**Downtime Required**: None
+
+## Overview
+
+OSSA v0.2.3 is a **documentation-only patch release** with **zero schema changes**. Existing v0.2.2 manifests work without modification. This guide covers optional updates to adopt v0.2.3 conventions.
+
+## TL;DR (Quick Migration)
+
+**No changes required!** Your v0.2.2 manifests work as-is.
+
+**Optional**: Update `apiVersion` field:
+
+```diff
+- apiVersion: ossa/v0.2.2
++ apiVersion: ossa/v0.2.4
+```
+
+That's it!
+
+---
+
+## What Changed?
+
+### Schema: ✅ Identical
+- **v0.2.2 schema hash**: `da22d4d47d4e9cc732c33290f971c670647d3318`
+- **v0.2.3 schema hash**: Same structure, updated version metadata only
+
+### Validation: ✅ Backward Compatible
+Both `ossa/v0.2.2` and `ossa/v0.2.4` accepted by the same validator.
+
+### What Actually Changed?
+- 📚 Enhanced documentation (README, wikis, examples)
+- 📖 6 new migration guides (LangChain, CrewAI, OpenAI, etc.)
+- 🏷️ Improved inline example annotations
+- 🔧 npm publishing preparation
+
+---
+
+## Migration Steps
+
+### Step 1: Update CLI (Optional)
+
+If using the OSSA CLI:
+
+```bash
+# Update globally
+npm update -g @bluefly/openstandardagents
+
+# Verify version
+ossa --version
+# Expected: 0.2.3
+```
+
+### Step 2: Update Manifests (Optional)
+
+**Option A: Bulk Update (Recommended)**
+
+```bash
+# Find and replace in all OSSA manifests
+find . -name "*.ossa.yaml" -exec sed -i '' 's/apiVersion: ossa\/v0.2.2/apiVersion: ossa\/v0.2.3/g' {} +
+
+# Verify changes
+git diff
+```
+
+**Option B: Keep v0.2.2 (Also Fine)**
+
+```yaml
+# This still works! No need to update.
+apiVersion: ossa/v0.2.2
+kind: Agent
+# ... rest of manifest
+```
+
+**Option C: Manual Update**
+
+```yaml
+# Before
+apiVersion: ossa/v0.2.2
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  type: worker
+  # ... rest unchanged
+
+# After (optional)
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  type: worker
+  # ... rest unchanged
+```
+
+### Step 3: Validate (Recommended)
+
+```bash
+# Validate all manifests
+ossa validate my-agent.ossa.yaml
+
+# Output should be identical for both v0.2.2 and v0.2.3
+```
+
+### Step 4: Update Documentation References
+
+If you have internal docs referencing OSSA:
+
+```diff
+- Documentation: https://github.com/blueflyio/openstandardagents/tree/v0.2.2
++ Documentation: https://github.com/blueflyio/openstandardagents/tree/v0.2.3
+
+- Schema: spec/v0.2.2/ossa-0.2.2.schema.json
++ Schema: spec/v0.2.3/ossa-0.2.3.schema.json
+```
+
+---
+
+## Compatibility Matrix
+
+| Format | v0.2.2 Validator | v0.2.3 Validator | Notes |
+|--------|------------------|------------------|-------|
+| `apiVersion: ossa/v0.2.2` | ✅ Valid | ✅ Valid | Backward compatible |
+| `apiVersion: ossa/v0.2.4` | ✅ Valid | ✅ Valid | Forward compatible |
+| `apiVersion: ossa/v1` | ✅ Valid | ✅ Valid | Alias for v0.2.x |
+
+**Conclusion**: Use whichever version you prefer - they're identical!
+
+---
+
+## Testing Your Migration
+
+### 1. Validation Test
+
+```bash
+# Test with v0.2.2 manifest
+ossa validate examples/kagent/k8s-troubleshooter.ossa.yaml
+
+# Update to v0.2.3
+sed -i '' 's/v0.2.2/v0.2.3/' examples/kagent/k8s-troubleshooter.ossa.yaml
+
+# Validate again (should produce identical results)
+ossa validate examples/kagent/k8s-troubleshooter.ossa.yaml
+```
+
+### 2. Schema Validation Test
+
+```javascript
+const Ajv = require('ajv');
+const ajv = new Ajv();
+
+// Both schemas validate identically
+const schema022 = require('./spec/v0.2.2/ossa-0.2.2.schema.json');
+const schema023 = require('./spec/v0.2.3/ossa-0.2.3.schema.json');
+
+const manifest = {
+  apiVersion: 'ossa/v0.2.4',
+  kind: 'Agent',
+  metadata: { name: 'test' },
+  spec: { type: 'worker' }
+};
+
+console.log(ajv.validate(schema022, manifest)); // true
+console.log(ajv.validate(schema023, manifest)); // true
+```
+
+### 3. Runtime Test
+
+```bash
+# Generate agent with v0.2.3
+ossa generate test-agent --type worker
+
+# Should produce:
+# apiVersion: ossa/v0.2.4
+# kind: Agent
+# ...
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Unsupported API version"
+
+**Solution**: Update OSSA CLI to v0.2.3+
+
+```bash
+npm update -g @bluefly/openstandardagents
+```
+
+### Issue: "Schema validation failed"
+
+**Diagnosis**: Likely a manifest syntax error, not a version issue.
+
+**Solution**:
+```bash
+# Check JSON/YAML syntax
+ossa validate --verbose my-agent.ossa.yaml
+
+# Common issues:
+# - Missing required fields (metadata, spec)
+# - Invalid YAML indentation
+# - Typos in field names
+```
+
+### Issue: "Cannot find schema v0.2.3"
+
+**Solution**: Clear cache and reinstall
+
+```bash
+rm -rf ~/.ossa/cache
+npm install -g @bluefly/openstandardagents@latest
+```
+
+---
+
+## Rollback Plan
+
+If you encounter issues (unlikely), rollback is instant:
+
+```bash
+# Revert manifest changes
+git checkout -- *.ossa.yaml
+
+# Downgrade CLI (if needed)
+npm install -g @bluefly/openstandardagents@0.2.2
+```
+
+**Note**: Since there are no schema changes, rollback is safe and instant.
+
+---
+
+## Framework-Specific Notes
+
+### kAgent (Kubernetes)
+```yaml
+# Both work identically with kagent CRDs
+apiVersion: ossa/v0.2.2  # ✅
+apiVersion: ossa/v0.2.4  # ✅
+```
+
+### Drupal (ai_agents module)
+```php
+// Both versions supported by ai_agents module
+$agent = new OssaAgent('my-agent', 'v0.2.2');  // ✅
+$agent = new OssaAgent('my-agent', 'v0.2.3');  // ✅
+```
+
+### LangChain
+```python
+# Both versions work with LangChain provider
+from ossa.langchain import OSSAAgent
+
+agent = OSSAAgent.from_manifest('agent-v0.2.2.yaml')  # ✅
+agent = OSSAAgent.from_manifest('agent-v0.2.3.yaml')  # ✅
+```
+
+### OpenAI Agents SDK
+```typescript
+// Both versions supported by OpenAI bridge
+import { OSSABridge } from '@ossa/openai';
+
+const agent = await OSSABridge.load('agent.ossa.yaml');
+// Works regardless of v0.2.2 or v0.2.3
+```
+
+---
+
+## New Features to Explore (v0.2.3)
+
+While the schema is unchanged, v0.2.3 includes new resources:
+
+### 1. Enhanced Migration Guides
+- **Location**: `examples/migration-guides/`
+- **Covers**: LangChain, CrewAI, OpenAI, Anthropic MCP, Langflow, Drupal ECA
+- **Benefit**: Faster framework integration
+
+### 2. Annotated Examples
+- **Location**: `examples/kagent/*.ossa.yaml`
+- **Includes**: Inline comments explaining best practices
+- **Benefit**: Learn OSSA patterns by example
+
+### 3. GitHub Repository
+- **URL**: https://github.com/blueflyio/openstandardagents
+- **Content**: Comprehensive guides, tutorials, API references
+- **Benefit**: Centralized, searchable documentation
+
+### 4. Production Templates
+- **Location**: `examples/production/`
+- **Includes**: Enterprise-ready agent configurations
+- **Benefit**: Deploy faster with battle-tested patterns
+
+---
+
+## FAQ
+
+### Q: Do I *have* to migrate?
+**A**: No! v0.2.2 manifests work indefinitely.
+
+### Q: Will v0.2.4 break compatibility?
+**A**: Patch versions (0.2.x) never break compatibility. Only minor (0.x.0) or major (x.0.0) versions may introduce changes.
+
+### Q: Should I update `apiVersion` in existing manifests?
+**A**: Optional. Update if you want to reflect the latest spec version, but v0.2.2 works equally well.
+
+### Q: Are there any deprecated features?
+**A**: No. Everything in v0.2.2 is still fully supported.
+
+### Q: Can I mix v0.2.2 and v0.2.3 manifests?
+**A**: Yes! They validate and execute identically.
+
+---
+
+## Support
+
+If you encounter issues during migration:
+
+1. **Check Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
+2. **Read Documentation**: https://github.com/blueflyio/openstandardagents
+3. **File Issue**: https://github.com/blueflyio/openstandardagents/issues
+
+---
+
+## Summary
+
+✅ **No breaking changes**
+✅ **No migration effort required**
+✅ **Backward compatible**
+✅ **Forward compatible**
+✅ **Safe to adopt immediately**
+
+**Recommendation**: Update at your convenience. Both versions work identically.
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-12
+**Applies To**: OSSA v0.2.3