@bluefly/openstandardagents 0.2.4 → 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/anthropic/claude-assistant.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "claude-assistant",

package/examples/autogen/multi-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "autogen-assistant",

package/examples/bridges/Dockerfile.production

@@ -79,7 +79,7 @@ LABEL org.opencontainers.image.title="AIFlow Social Agent" \
       org.opencontainers.image.description="Personality-driven social AI agent with BuildKit registration" \
       org.opencontainers.image.version="1.0.0" \
       org.opencontainers.image.vendor="OSSA Community" \
-      org.opencontainers.image.source="https://gitlab.bluefly.io/llm/openapi-ai-agents-standard" \
+      org.opencontainers.image.source="https://github.com/blueflyio/openstandardagents" \
       ossa.compliant="true" \
       ossa.version="1.0" \
       agent.framework="aiflow" \

package/examples/crewai/research-team.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "research-agent",

package/examples/cursor/code-review-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "code-review-agent",

package/examples/enterprise/agent.yml

@@ -449,4 +449,4 @@ bridge:
       api_version: "11.x"
     gitlab:
       enabled: true
-      ci_component: app-4001.cloud.bluefly.io/llm/golden@v0.1.0
+      ci_component: gitlab.com/blueflyio/agent-platform/gitlab_components/golden@v0.1.0

package/examples/getting-started/hello-world-complete.ossa.yaml

@@ -32,7 +32,7 @@
 #
 # ============================================================================
 
-apiVersion: ossa/v0.2.x
+apiVersion: ossa/v0.2
 kind: Agent
 
 metadata:
@@ -260,7 +260,7 @@ spec:
 # - OSSA Specification: spec/v0.2.x/ossa-0.2.x.schema.json
 # - Schema Reference: docs/schemas/
 # - API Reference: openapi/
-# - GitLab Wiki: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/wikis
+# - GitHub Repository: https://github.com/blueflyio/openstandardagents
 #
 # ============================================================================
 

package/examples/integration-patterns/agent-to-agent-orchestration.ossa.yaml

@@ -36,7 +36,7 @@
 # ----------------------------------------------------------------------------
 # Coordinates the workflow, delegates tasks to worker agents, and aggregates results
 
-apiVersion: ossa/v0.2.2
+apiVersion: ossa/v0.2
 kind: Agent
 
 metadata:
@@ -154,7 +154,7 @@ spec:
 # Specialized agent for research tasks
 
 ---
-apiVersion: ossa/v0.2.2
+apiVersion: ossa/v0.2
 kind: Agent
 
 metadata:
@@ -221,7 +221,7 @@ spec:
 # Specialized agent for data analysis
 
 ---
-apiVersion: ossa/v0.2.2
+apiVersion: ossa/v0.2
 kind: Agent
 
 metadata:
@@ -282,7 +282,7 @@ spec:
 # Specialized agent for content creation
 
 ---
-apiVersion: ossa/v0.2.2
+apiVersion: ossa/v0.2
 kind: Agent
 
 metadata:

package/examples/langchain/chain-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "langchain-agent",

package/examples/langflow/workflow-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "workflow-orchestrator",

package/examples/langgraph/state-machine-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "state-machine-agent",

package/examples/llamaindex/rag-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.3",
+  "apiVersion": "ossa/v0.2",
   "kind": "Agent",
   "metadata": {
     "name": "rag-query-agent",

package/examples/openai/basic-agent.ossa.yaml

@@ -0,0 +1,61 @@
+apiVersion: ossa/v0.2.4
+kind: Agent
+
+metadata:
+  name: basic-openai-agent
+  version: 1.0.0
+  description: A basic OpenAI agent demonstrating simple tool usage
+
+spec:
+  role: |
+    You are a helpful assistant that can search the web and perform calculations.
+    Always provide clear and concise answers.
+
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+    temperature: 0.7
+
+extensions:
+  openai_agents:
+    model: gpt-4o-mini
+    instructions: |
+      You are a helpful assistant with access to web search and calculator tools.
+      Use the search tool to find current information.
+      Use the calculator for mathematical operations.
+      Always explain your reasoning.
+    
+    tools_mapping:
+      - ossa_capability: web_search
+        openai_tool_name: search
+        description: Search the web for current information
+        parameters:
+          type: object
+          properties:
+            query:
+              type: string
+              description: The search query
+          required:
+            - query
+      
+      - ossa_capability: calculator
+        openai_tool_name: calculate
+        description: Perform mathematical calculations
+        parameters:
+          type: object
+          properties:
+            expression:
+              type: string
+              description: Mathematical expression to evaluate (e.g., "2 + 2", "sqrt(16)")
+          required:
+            - expression
+    
+    guardrails:
+      enabled: true
+      max_tool_calls: 5
+      timeout_seconds: 60
+    
+    memory:
+      enabled: true
+      type: session
+      max_messages: 20