@bluefly/openstandardagents 0.3.1 → 0.3.3

package/spec/v0.2.3/README.md

@@ -1,154 +0,0 @@
-# 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

@@ -1,343 +0,0 @@
-# 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