@bluefly/openstandardagents 0.3.2 → 0.3.3

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

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