@bluefly/openstandardagents 0.2.4 → 0.2.7

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

@@ -0,0 +1,599 @@
+# Migration Guide: OSSA v0.2.3 -> v0.2.4-dev
+
+**Migration Difficulty**: Yellow - **Low** (All new features are additive)
+**Estimated Time**: 15-30 minutes (depending on feature adoption)
+**Downtime Required**: None
+**Status**: DEVELOPMENT VERSION - Features may change
+
+## Overview
+
+OSSA v0.2.4-dev introduces significant new features while maintaining full backward compatibility with v0.2.3. All existing manifests work without modification. This guide covers how to adopt the new features.
+
+## TL;DR (Quick Migration)
+
+**No changes required!** Your v0.2.3 manifests work as-is.
+
+**Optional**: Update `apiVersion` to access new features:
+
+```diff
+- apiVersion: ossa/v0.2.4
++ apiVersion: ossa/v0.2.4-dev
+```
+
+---
+
+## What Changed?
+
+### Schema Additions (Non-Breaking)
+
+| Feature | Location | Purpose |
+|---------|----------|---------|
+| Transport metadata | `spec.tools[].transport` | Protocol/streaming configuration |
+| State/memory | `spec.state` | Agent state management |
+| Security scopes | `spec.tools[].auth.scopes` | Fine-grained permissions |
+| Compliance tags | `spec.tools[].compliance_tags` | Regulatory tagging |
+| Capability versioning | `spec.tools[].capabilities[].version` | Independent capability versions |
+| Capability deprecation | `spec.tools[].capabilities[].deprecated` | Lifecycle management |
+| Google ADK extension | `extensions.google_adk` | Google ADK integration |
+
+### apiVersion Pattern
+Extended to support v0.2.4-dev:
+```regex
+^ossa/v(0\.2\.[2-4](-dev)?|1)(\.[0-9]+)?(-[a-zA-Z0-9]+)?$
+```
+
+---
+
+## Migration Steps
+
+### Step 1: Update CLI (Recommended)
+
+```bash
+# Install development version
+npm install -g @bluefly/openstandardagents@0.2.4-dev
+
+# Verify version
+ossa --version
+# Expected: 0.2.4-dev
+```
+
+### Step 2: Update apiVersion (Optional)
+
+**Option A: Keep v0.2.3 (Works fine)**
+```yaml
+apiVersion: ossa/v0.2.4
+# All existing features continue to work
+```
+
+**Option B: Upgrade to v0.2.4-dev (Access new features)**
+```yaml
+apiVersion: ossa/v0.2.4-dev
+# Enables new validation for transport, state, etc.
+```
+
+### Step 3: Adopt New Features (Optional)
+
+Select which new features benefit your use case:
+
+---
+
+## Feature Adoption Guide
+
+### 1. Transport Metadata
+
+**When to use**: Streaming LLMs, real-time agents, A2A protocol, gRPC services
+
+**Before (v0.2.3)**:
+```yaml
+tools:
+  - type: http
+    name: chat-api
+    endpoint: https://api.example.com/chat
+```
+
+**After (v0.2.4-dev)**:
+```yaml
+tools:
+  - type: http
+    name: chat-api
+    endpoint: https://api.example.com/chat
+    transport:
+      protocol: http
+      streaming: response          # Server sends streaming response
+      binding: /v1/chat/stream
+      content_type: text/event-stream
+```
+
+**Streaming mode reference**:
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `none` | Standard request/response | REST APIs |
+| `request` | Client streams to server | File uploads |
+| `response` | Server streams to client | LLM text generation |
+| `bidirectional` | Full duplex | Real-time chat |
+
+**Example: gRPC bidirectional streaming**:
+```yaml
+tools:
+  - type: grpc
+    name: agent-service
+    endpoint: grpc://agent.example.com:443
+    transport:
+      protocol: grpc
+      streaming: bidirectional
+      binding: AgentService.StreamChat
+```
+
+### 2. State/Memory Block
+
+**When to use**: Stateful agents, chat applications, long-running workflows
+
+**Before (v0.2.3)**: No standard state configuration
+
+**After (v0.2.4-dev)**:
+```yaml
+spec:
+  state:
+    mode: session                  # stateless | session | long_running
+    storage:
+      type: memory                 # memory | vector-db | kv | rdbms | custom
+      retention: 24h
+    context_window:
+      max_messages: 50
+      max_tokens: 16000
+      strategy: sliding_window     # sliding_window | summarization | importance_weighted
+```
+
+**Mode reference**:
+| Mode | Persistence | Use Case |
+|------|-------------|----------|
+| `stateless` | None | Simple request/response APIs |
+| `session` | Session duration | Chat, conversational agents |
+| `long_running` | Persistent | Workflows, research agents |
+
+**Storage type reference**:
+| Type | Characteristics | Use Case |
+|------|-----------------|----------|
+| `memory` | Fast, lost on restart | Development, testing |
+| `vector-db` | Semantic search | RAG, document retrieval |
+| `kv` | Key-value lookup | Session state, caching |
+| `rdbms` | Relational queries | Structured data, audit trails |
+
+**Example: Long-running research agent**:
+```yaml
+spec:
+  state:
+    mode: long_running
+    storage:
+      type: vector-db
+      retention: 1y
+      config:
+        provider: pinecone
+        index: research-memory
+        namespace: research-agent
+    context_window:
+      max_tokens: 128000
+      strategy: summarization
+```
+
+### 3. Security Scopes
+
+**When to use**: Fine-grained access control, OAuth2-style permissions
+
+**Before (v0.2.3)**:
+```yaml
+tools:
+  - type: http
+    auth:
+      type: bearer
+      credentials: secret:api-key
+```
+
+**After (v0.2.4-dev)**:
+```yaml
+tools:
+  - type: http
+    auth:
+      type: bearer
+      credentials: secret:api-key
+      scopes:                       # NEW: Permission scopes
+        - read:data
+        - write:data
+        - execute:query
+```
+
+**Common scopes**:
+| Scope | Description |
+|-------|-------------|
+| `read:data` | Read access to data |
+| `write:data` | Write access to data |
+| `admin:system` | System administration |
+| `admin:users` | User management |
+| `execute:code` | Code execution |
+| `execute:query` | Database queries |
+
+### 4. Compliance Tags
+
+**When to use**: Regulated environments (HIPAA, GDPR, FedRAMP, SOC2)
+
+**Before (v0.2.3)**: Compliance at policy level only
+
+**After (v0.2.4-dev)**:
+```yaml
+tools:
+  - type: http
+    compliance_tags:                # NEW: Tool-level compliance
+      - pii
+      - hipaa
+      - gdpr
+    capabilities:
+      - name: get_patient_data
+        compliance_tags:            # NEW: Capability-level compliance
+          - phi                     # Protected Health Information
+          - hipaa
+```
+
+**Common compliance tags**:
+| Tag | Framework | Description |
+|-----|-----------|-------------|
+| `pii` | General | Personally identifiable information |
+| `phi` | HIPAA | Protected health information |
+| `hipaa` | HIPAA | HIPAA compliance required |
+| `gdpr` | GDPR | GDPR compliance required |
+| `fedramp` | FedRAMP | Federal security requirements |
+| `soc2` | SOC2 | SOC2 Type II controls |
+
+### 5. Capability Versioning
+
+**When to use**: Managing capability lifecycle, deprecation announcements
+
+**Before (v0.2.3)**:
+```yaml
+capabilities:
+  - name: search_documents
+    description: Search for documents
+```
+
+**After (v0.2.4-dev)**:
+```yaml
+capabilities:
+  - name: search_documents
+    description: Search for documents
+    version: '2.1'                  # NEW: Capability version
+    deprecated: false
+
+  - name: search_legacy
+    description: Legacy search (deprecated)
+    version: '1.0'
+    deprecated: true                # NEW: Deprecation flag
+    deprecation_message: |          # NEW: Migration guidance
+      Deprecated in v0.2.4. Will be removed in v0.3.0.
+      Use 'search_documents' capability instead.
+      Migration steps:
+      1. Change capability name to 'search_documents'
+      2. Update input schema to use 'query' instead of 'search_term'
+```
+
+**Best practices**:
+- Use major.minor format (e.g., '2.1')
+- Increment major for breaking changes
+- Provide deprecation_message with migration steps
+- Allow at least one minor version for deprecation period
+
+### 6. Google ADK Extension
+
+**When to use**: Google Agent Development Kit integration
+
+**After (v0.2.4-dev)**:
+```yaml
+extensions:
+  google_adk:
+    enabled: true
+    agent_type: llm_agent          # llm_agent | sequential_agent | parallel_agent | loop_agent
+    model: gemini-2.0-flash-exp
+    instruction: "You are a helpful assistant."
+    session:
+      service: in_memory           # in_memory | database | vertex_ai
+      state_schema:
+        conversation_history: array
+        user_preferences: object
+    memory:
+      enabled: true
+      service: vertex_ai_rag
+    tools:
+      - name: web_search
+        type: function
+      - name: mcp_server
+        type: mcp_server
+        config:
+          server_name: filesystem
+    callbacks:
+      before_model_callback: validate_input
+      after_model_callback: log_response
+```
+
+**Agent types**:
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `llm_agent` | Single LLM agent | Simple assistants |
+| `sequential_agent` | Pipeline execution | Multi-step workflows |
+| `parallel_agent` | Concurrent execution | Fan-out tasks |
+| `loop_agent` | Iterative with conditions | Refinement loops |
+
+---
+
+## Complete Migration Example
+
+### Before (v0.2.3)
+```yaml
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: customer-support
+  version: 1.0.0
+spec:
+  role: Customer support agent
+  llm:
+    provider: openai
+    model: gpt-4
+  tools:
+    - type: http
+      name: crm-api
+      endpoint: https://crm.example.com/api
+      auth:
+        type: bearer
+        credentials: secret:crm-key
+      capabilities:
+        - customer_lookup
+        - ticket_create
+```
+
+### After (v0.2.4-dev)
+```yaml
+apiVersion: ossa/v0.2.4-dev
+kind: Agent
+metadata:
+  name: customer-support
+  version: 1.1.0                    # Bump version for new features
+spec:
+  role: Customer support agent
+  llm:
+    provider: openai
+    model: gpt-4
+
+  # NEW: State management for session continuity
+  state:
+    mode: session
+    storage:
+      type: memory
+      retention: 24h
+    context_window:
+      max_messages: 100
+      strategy: sliding_window
+
+  tools:
+    - type: http
+      name: crm-api
+      endpoint: https://crm.example.com/api
+      auth:
+        type: bearer
+        credentials: secret:crm-key
+        scopes:                     # NEW: Security scopes
+          - read:customers
+          - write:tickets
+      compliance_tags:              # NEW: Compliance tags
+        - pii
+        - gdpr
+      transport:                    # NEW: Transport metadata
+        protocol: http
+        streaming: none
+        binding: /v1
+      capabilities:
+        - name: customer_lookup
+          version: '1.0'           # NEW: Capability version
+          scopes:
+            - read:customers
+          compliance_tags:
+            - pii
+        - name: ticket_create
+          version: '1.0'
+          scopes:
+            - write:tickets
+```
+
+---
+
+## Validation
+
+### Validate Updated Manifests
+
+```bash
+# Validate single manifest
+ossa validate my-agent.ossa.yaml
+
+# Validate all manifests in directory
+ossa validate examples/
+```
+
+### Check for New Features
+
+```bash
+# Check if transport is properly configured
+ossa inspect my-agent.ossa.yaml --show transport
+
+# Check state configuration
+ossa inspect my-agent.ossa.yaml --show state
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Unknown property 'transport'"
+
+**Cause**: Using v0.2.4-dev features with v0.2.3 validator
+
+**Solution**: Update CLI to v0.2.4-dev
+```bash
+npm install -g @bluefly/openstandardagents@0.2.4-dev
+```
+
+### Issue: "Invalid streaming mode"
+
+**Cause**: Typo in streaming value
+
+**Solution**: Use valid enum values
+```yaml
+transport:
+  streaming: response  # Valid: none, request, response, bidirectional
+```
+
+### Issue: "State mode required when storage specified"
+
+**Cause**: Missing mode when storage is configured
+
+**Solution**: Always specify mode with state
+```yaml
+state:
+  mode: session        # Required when storage is specified
+  storage:
+    type: memory
+```
+
+### Issue: "Capability version format invalid"
+
+**Cause**: Using semver instead of major.minor
+
+**Solution**: Use two-part version
+```yaml
+capabilities:
+  - name: my_cap
+    version: '1.0'     # Correct: major.minor only
+    # version: '1.0.0' # Wrong: no patch version
+```
+
+---
+
+## Rollback Plan
+
+Since all changes are additive, rollback is simple:
+
+1. **Remove new properties** (transport, state, scopes, etc.)
+2. **Revert apiVersion** to v0.2.3
+3. **Validate** with v0.2.3 schema
+
+```bash
+# Downgrade CLI if needed
+npm install -g @bluefly/openstandardagents@0.2.3
+```
+
+---
+
+## Compatibility Matrix
+
+| Format | v0.2.3 Validator | v0.2.4-dev Validator | Notes |
+|--------|------------------|----------------------|-------|
+| `apiVersion: ossa/v0.2.4` | Valid | Valid | Backward compatible |
+| `apiVersion: ossa/v0.2.4-dev` | Invalid | Valid | Requires new validator |
+| New properties in v0.2.3 manifest | Invalid | Ignored | Will fail validation |
+
+---
+
+## Framework-Specific Notes
+
+### OpenAI Agents SDK
+```yaml
+# Use state for session management
+state:
+  mode: session
+  storage:
+    type: memory
+
+extensions:
+  openai_agents:
+    enabled: true
+    memory:
+      enabled: true
+      type: session
+```
+
+### Google ADK
+```yaml
+# Full ADK configuration
+extensions:
+  google_adk:
+    enabled: true
+    agent_type: llm_agent
+    model: gemini-2.0-flash-exp
+    session:
+      service: vertex_ai
+```
+
+### Microsoft Autogen Framework
+```yaml
+# Use long_running state for workflows
+state:
+  mode: long_running
+  storage:
+    type: rdbms
+    retention: 1y
+
+extensions:
+  autogen:
+    enabled: true
+    agent_type: assistant
+```
+
+### A2A Protocol
+```yaml
+# Use a2a transport
+tools:
+  - type: a2a
+    transport:
+      protocol: a2a
+      streaming: none
+      binding: /tasks/send
+```
+
+---
+
+## Checklist
+
+- [ ] Update OSSA CLI to v0.2.4-dev
+- [ ] Update apiVersion in manifests (optional)
+- [ ] Add state configuration for stateful agents
+- [ ] Add transport metadata for streaming capabilities
+- [ ] Add scopes for fine-grained access control
+- [ ] Add compliance_tags for regulated capabilities
+- [ ] Version capabilities for lifecycle management
+- [ ] Configure Google ADK extension if using ADK
+- [ ] Validate all updated manifests
+- [ ] Test in development environment
+
+---
+
+## 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
+- All new features are optional
+- Backward compatible with v0.2.3
+- Forward compatible for v0.2.4 stable
+
+**Recommendation**: Adopt features incrementally based on your needs. Start with state management for stateful agents and transport metadata for streaming capabilities.
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-18
+**Applies To**: OSSA v0.2.4-dev
+**Stability**: Development - APIs may change

package/spec/{v0.2.4-dev/ossa-0.2.4-dev.yaml → v0.2.4/ossa-0.2.4.yaml}

@@ -565,7 +565,7 @@ best_practices:
 development_notes:
   status: DEVELOPMENT VERSION - APIs may change
   stability: unstable
-  feedback: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/issues
+  feedback: https://github.com/blueflyio/openstandardagents/issues
   planned_ga: v0.3.0
 
   known_limitations: