@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/docs/issue-19-validation.md

@@ -0,0 +1,351 @@
+# Issue #19 Validation Checklist
+
+**Issue:** ossa run command - Run agents with OpenAI adapter  
+**Milestone:** v0.2.7 - Multi-Agent & Adapters  
+**Status:** Implementation Complete, Testing & Documentation Added
+
+## Acceptance Criteria Validation
+
+### ✅ 1. Create `ossa run` command functionality
+
+**Status:** COMPLETE
+
+**Implementation:**
+- File: `src/cli/commands/run.command.ts`
+- Command registered in: `src/cli/index.ts`
+- Entry point: `bin/ossa`
+
+**Features Implemented:**
+- ✅ Command accepts `<path>` argument for manifest file
+- ✅ Interactive REPL mode for conversations
+- ✅ Single message mode with `-m, --message` flag
+- ✅ Verbose output with `-v, --verbose` flag
+- ✅ Validation toggle with `--no-validate` flag
+- ✅ Max turns configuration with `--max-turns` flag
+- ✅ Runtime selection with `-r, --runtime` flag
+
+**Tests:**
+- Unit tests: `tests/unit/cli/commands/run.command.test.ts`
+- Integration tests: `tests/integration/cli/run.test.ts`
+
+**Documentation:**
+- CLI Reference: `website/content/docs/cli/run-command.md`
+- Getting Started: `website/content/docs/getting-started/running-agents.md`
+- README.md: Updated with run command examples
+
+---
+
+### ✅ 2. Integrate with OpenAI adapter for agent execution
+
+**Status:** COMPLETE
+
+**Implementation:**
+- File: `src/services/runtime/openai.adapter.ts`
+- OpenAI SDK version: 6.9.1
+
+**Features Implemented:**
+- ✅ OpenAI API integration using official SDK
+- ✅ Function calling support
+- ✅ Tool registration and execution
+- ✅ Conversation history management
+- ✅ Model selection from manifest or extensions
+- ✅ System prompt handling
+- ✅ Tool mapping from OSSA capabilities to OpenAI functions
+- ✅ Custom tool handler registration
+- ✅ Error handling for tool execution
+- ✅ Max turns limit to prevent infinite loops
+
+**Tests:**
+- Unit tests: `tests/unit/services/runtime/openai.adapter.test.ts`
+
+**Documentation:**
+- Adapter Guide: `website/content/docs/adapters/openai-adapter.md`
+- Examples: `examples/openai/basic-agent.ossa.yaml`, `examples/openai/multi-tool-agent.ossa.json`
+
+---
+
+### ✅ 3. Ensure proper command-line interface and argument handling
+
+**Status:** COMPLETE
+
+**CLI Options Implemented:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `<path>` | Argument | Required | Path to OSSA agent manifest |
+| `-r, --runtime` | Option | `openai` | Runtime adapter selection |
+| `-v, --verbose` | Flag | `false` | Verbose output |
+| `-m, --message` | Option | Interactive | Single message mode |
+| `--no-validate` | Flag | Validation on | Skip validation |
+| `--max-turns` | Option | `10` | Max tool call iterations |
+
+**Argument Validation:**
+- ✅ Path argument is required
+- ✅ Runtime must be 'openai' (others show error)
+- ✅ Max turns must be a valid number
+- ✅ Message can be any string
+
+**Tests:**
+- Integration tests cover all CLI options
+- Error handling tests for invalid arguments
+
+**Documentation:**
+- Complete CLI reference with all options documented
+- Examples for each option combination
+
+---
+
+### ✅ 4. Add appropriate error handling and validation
+
+**Status:** COMPLETE
+
+**Error Handling Implemented:**
+
+1. **Manifest Loading Errors:**
+   - ✅ File not found
+   - ✅ Invalid YAML/JSON syntax
+   - ✅ Manifest validation failures
+
+2. **API Key Validation:**
+   - ✅ Check for OPENAI_API_KEY environment variable
+   - ✅ Clear error message with instructions
+
+3. **Runtime Errors:**
+   - ✅ Unsupported runtime detection
+   - ✅ List of available runtimes
+
+4. **Tool Execution Errors:**
+   - ✅ Unknown tool handling
+   - ✅ Tool handler exceptions caught
+   - ✅ Error messages returned to agent
+
+5. **Conversation Errors:**
+   - ✅ API errors caught and displayed
+   - ✅ Max turns limit enforcement
+   - ✅ Graceful error recovery in REPL mode
+
+**Validation:**
+- ✅ Manifest validation before execution (optional)
+- ✅ Schema validation using AJV
+- ✅ Validation errors displayed with details
+- ✅ Verbose mode shows validation details
+
+**Tests:**
+- Error handling scenarios covered in unit tests
+- Integration tests for validation failures
+- API key missing tests
+- Invalid manifest tests
+
+**Documentation:**
+- Troubleshooting section in running-agents.md
+- Error handling section in run-command.md
+- Common errors and solutions documented
+
+---
+
+### ✅ 5. Include documentation for the new command
+
+**Status:** COMPLETE
+
+**Documentation Created:**
+
+1. **CLI Reference** (`website/content/docs/cli/run-command.md`)
+   - ✅ Complete command synopsis
+   - ✅ All arguments and options documented
+   - ✅ Interactive mode explanation
+   - ✅ Single message mode explanation
+   - ✅ Environment variables
+   - ✅ Exit codes
+   - ✅ Examples for all use cases
+   - ✅ Error handling guide
+   - ✅ Manifest configuration examples
+
+2. **Getting Started Guide** (`website/content/docs/getting-started/running-agents.md`)
+   - ✅ Quick start instructions
+   - ✅ Prerequisites
+   - ✅ Installation steps
+   - ✅ Basic usage examples
+   - ✅ Command options table
+   - ✅ Detailed option descriptions
+   - ✅ Interactive REPL mode guide
+   - ✅ Troubleshooting section
+   - ✅ Advanced usage examples
+
+3. **OpenAI Adapter Guide** (`website/content/docs/adapters/openai-adapter.md`)
+   - ✅ Overview and features
+   - ✅ Configuration options
+   - ✅ Model selection
+   - ✅ System prompt configuration
+   - ✅ Tool mapping guide
+   - ✅ Conversation management
+   - ✅ Tool execution
+   - ✅ Advanced features
+   - ✅ API integration details
+   - ✅ Examples (basic, customer support, code assistant, multi-tool)
+   - ✅ Troubleshooting
+   - ✅ Best practices
+
+4. **README.md Updates**
+   - ✅ Quick start with run command
+   - ✅ Running agents section
+   - ✅ CLI commands list updated
+
+5. **Example Agents**
+   - ✅ Basic agent: `examples/openai/basic-agent.ossa.yaml`
+   - ✅ Multi-tool agent: `examples/openai/multi-tool-agent.ossa.json`
+   - ✅ Existing swarm agent: `examples/openai/swarm-agent.ossa.json`
+
+---
+
+## Test Coverage Summary
+
+### Unit Tests
+
+1. **Run Command Tests** (`tests/unit/cli/commands/run.command.test.ts`)
+   - Validation scenarios
+   - Runtime selection
+   - API key validation
+   - Single message mode
+   - Error handling
+   - Agent info display
+
+2. **OpenAI Adapter Tests** (`tests/unit/services/runtime/openai.adapter.test.ts`)
+   - Constructor and initialization
+   - Model selection (extension, LLM config, default)
+   - System prompt selection
+   - Tool mapping (tools_mapping, spec.tools)
+   - Tool handler registration
+   - Tool execution (with handler, without handler, errors)
+   - Conversation management
+   - Chat options (verbose, maxTurns)
+   - LLM configuration (temperature, maxTokens)
+   - Agent info retrieval
+
+### Integration Tests
+
+1. **Run Command Integration Tests** (`tests/integration/cli/run.test.ts`)
+   - Validation with valid/invalid manifests
+   - Skip validation flag
+   - API key validation
+   - Runtime selection (default, unsupported)
+   - Single message mode (-m, --message)
+   - Verbose mode (-v, --verbose)
+   - Max turns option
+   - Error handling (missing file, invalid YAML/JSON)
+   - Agent info display
+   - Example manifests
+
+**Total Test Files Created:** 3  
+**Test Scenarios Covered:** 50+
+
+---
+
+## Documentation Summary
+
+### Files Created/Updated
+
+1. **Created:**
+   - `website/content/docs/cli/run-command.md` (comprehensive CLI reference)
+   - `website/content/docs/adapters/openai-adapter.md` (adapter guide)
+   - `examples/openai/basic-agent.ossa.yaml` (basic example)
+   - `examples/openai/multi-tool-agent.ossa.json` (advanced example)
+   - `docs/issue-19-validation.md` (this file)
+
+2. **Updated:**
+   - `website/content/docs/getting-started/running-agents.md` (enhanced guide)
+   - `README.md` (added run command examples)
+
+**Total Documentation Pages:** 6  
+**Total Word Count:** ~15,000+ words
+
+---
+
+## Implementation Quality Metrics
+
+### Code Quality
+- ✅ TypeScript with strict typing
+- ✅ ES modules
+- ✅ Dependency injection (Inversify)
+- ✅ Error handling throughout
+- ✅ Consistent code style
+- ✅ JSDoc comments (in adapter)
+
+### Testing
+- ✅ Unit tests for core functionality
+- ✅ Integration tests for CLI
+- ✅ Mocking for external dependencies
+- ✅ Error scenario coverage
+- ✅ Edge case handling
+
+### Documentation
+- ✅ Comprehensive CLI reference
+- ✅ Getting started guide
+- ✅ Adapter documentation
+- ✅ Examples with comments
+- ✅ Troubleshooting guides
+- ✅ Best practices
+
+### User Experience
+- ✅ Clear error messages
+- ✅ Helpful usage instructions
+- ✅ Interactive REPL mode
+- ✅ Verbose debugging option
+- ✅ Sensible defaults
+
+---
+
+## Verification Steps
+
+To verify the implementation:
+
+### 1. Run Unit Tests
+```bash
+npm run test:unit
+```
+
+### 2. Run Integration Tests
+```bash
+npm run test:integration
+```
+
+### 3. Test CLI Manually
+```bash
+# Build the project
+npm run build
+
+# Test validation
+ossa validate examples/openai/basic-agent.ossa.yaml
+
+# Test run command (requires API key)
+export OPENAI_API_KEY=sk-your-key
+ossa run examples/openai/basic-agent.ossa.yaml -m "Hello"
+```
+
+### 4. Verify Documentation
+- Browse to https://openstandardagents.org/docs/cli/run-command
+- Browse to https://openstandardagents.org/docs/adapters/openai-adapter
+- Browse to https://openstandardagents.org/docs/getting-started/running-agents
+
+---
+
+## Conclusion
+
+All acceptance criteria for Issue #19 have been **FULLY IMPLEMENTED** with:
+
+✅ Complete `ossa run` command functionality  
+✅ Full OpenAI adapter integration  
+✅ Comprehensive CLI argument handling  
+✅ Robust error handling and validation  
+✅ Extensive documentation and examples  
+
+**Additional deliverables:**
+- Comprehensive test suite (unit + integration)
+- Multiple example agents
+- Best practices guide
+- Troubleshooting documentation
+
+**Ready for:**
+- Code review
+- QA testing
+- Merge to main branch
+- Release in v0.2.7 milestone

package/examples/adk-integration/code-review-workflow.yml

@@ -0,0 +1,136 @@
+# Example: ADK Code Review Workflow with OSSA Agents
+# This demonstrates how OSSA agents work with ADK orchestration patterns
+
+apiVersion: '@ossa/v0.1.9'
+kind: Workflow
+metadata:
+  name: code-review-workflow
+  description: 'Multi-agent code review using ADK patterns'
+
+spec:
+  # ADK orchestration pattern
+  adk_pattern: sequential
+
+  # Agents involved in workflow
+  agents:
+    - name: code-analyzer
+      type: LlmAgent
+      ossa_type: worker
+      capabilities:
+        - code-analysis
+        - static-analysis
+      instruction: |
+        Analyze the provided code for:
+        - Code quality issues
+        - Potential bugs
+        - Performance concerns
+        - Security vulnerabilities
+        Store findings in {analysis_results}
+      output_key: analysis_results
+
+    - name: style-checker
+      type: LlmAgent
+      ossa_type: critic
+      capabilities:
+        - style-checking
+        - formatting
+      instruction: |
+        Check code style based on {analysis_results}:
+        - Naming conventions
+        - Code formatting
+        - Documentation completeness
+        Store style issues in {style_report}
+      output_key: style_report
+
+    - name: security-auditor
+      type: CustomAgent
+      custom_type: governor
+      ossa_type: governor
+      capabilities:
+        - security-scanning
+        - vulnerability-detection
+      policies:
+        - name: owasp-top-10
+          severity: high
+        - name: cwe-sans-25
+          severity: critical
+      instruction: |
+        Audit code for security issues using {analysis_results}
+        Apply OWASP and CWE policies
+        Store violations in {security_audit}
+      output_key: security_audit
+
+    - name: review-aggregator
+      type: WorkflowAgent
+      workflow_type: parallel
+      ossa_type: orchestrator
+      sub_agents:
+        - code-analyzer
+        - style-checker
+        - security-auditor
+      instruction: |
+        Aggregate all review results:
+        - {analysis_results}
+        - {style_report}  
+        - {security_audit}
+        Generate comprehensive review report
+      output_key: final_review
+
+  # Execution configuration
+  execution:
+    # Use ADK state management
+    state_management: adk_session
+
+    # Tool delegation
+    tool_delegation:
+      type: explicit
+      tools:
+        - name: git_operations
+          capabilities: [version-control]
+        - name: issue_tracker
+          capabilities: [issue-management]
+
+    # Conditional execution based on findings
+    conditions:
+      - agent: security-auditor
+        condition: "session.state.analysis_results.severity > 'medium'"
+      - agent: style-checker
+        condition: 'session.state.analysis_results.lines_of_code > 100'
+
+    # Loop configuration for iterative review
+    loop_options:
+      max_iterations: 3
+      break_condition: 'session.state.security_audit.violations.length == 0'
+
+  # ADK integration settings
+  adk_config:
+    # Model configuration
+    models:
+      default: gemini-2.0-flash
+      specialized:
+        security-auditor: gemini-2.0-pro
+
+    # Performance settings
+    performance:
+      parallel_execution: true
+      cache_session_state: true
+      state_persistence: redis
+
+    # Error handling
+    error_handling:
+      retry_count: 3
+      fallback_pattern: sequential
+# Example usage with ADK adapter:
+#
+# const adapter = new OSSAADKAdapter();
+# await adapter.loadAgent('.agents/code-analyzer');
+# await adapter.loadAgent('.agents/style-checker');
+# await adapter.loadAgent('.agents/security-auditor');
+# await adapter.loadAgent('.agents/review-aggregator');
+#
+# const result = await adapter.executeOrchestration(
+#   'sequential',
+#   ['code-analyzer', 'style-checker', 'security-auditor', 'review-aggregator'],
+#   { code: sourceCode },
+#   { conditions: [...], loop_options: {...} }
+# );