@bluefly/openstandardagents 0.2.9 → 0.3.0

package/bin/ossa-generate

@@ -11,26 +11,19 @@ if (!type || !name) {
 }
 
 const templates = {
-  agent: `apiVersion: ossa.ai/v0.2.6
+  agent: `apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: ${name}
-  version: 1.0.0
-spec:
+  version: "1.0.0"
   description: ${name} agent
-  capabilities:
-    - text-generation
-  interface:
-    input:
-      type: object
-      properties:
-        prompt:
-          type: string
-    output:
-      type: object
-      properties:
-        response:
-          type: string
+spec:
+  role: |
+    You are a helpful assistant.
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+  tools: []
 `,
   adapter: `import { Adapter } from '@ossa/core';
 

package/bin/quickstart

@@ -0,0 +1,514 @@
+#!/usr/bin/env bash
+
+# ╔═══════════════════════════════════════════════════════════════════════════════╗
+# ║                                                                               ║
+# ║                         OSSA QUICKSTART SCRIPT                                ║
+# ║                                                                               ║
+# ║   Create your first OSSA agent in minutes with this interactive wizard       ║
+# ║                                                                               ║
+# ╚═══════════════════════════════════════════════════════════════════════════════╝
+
+set -euo pipefail
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                               COLOR DEFINITIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ANSI color codes for beautiful terminal output
+readonly RED='\033[0;31m'
+readonly GREEN='\033[0;32m'
+readonly YELLOW='\033[1;33m'
+readonly BLUE='\033[0;34m'
+readonly MAGENTA='\033[0;35m'
+readonly CYAN='\033[0;36m'
+readonly WHITE='\033[1;37m'
+readonly GRAY='\033[0;90m'
+readonly BOLD='\033[1m'
+readonly DIM='\033[2m'
+readonly RESET='\033[0m'
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                            UTILITY FUNCTIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Print functions for consistent formatting
+print_header() {
+    echo -e "${CYAN}${BOLD}$1${RESET}"
+}
+
+print_success() {
+    echo -e "  ${GREEN}✓${RESET} $1"
+}
+
+print_error() {
+    echo -e "  ${RED}✗${RESET} $1"
+}
+
+print_info() {
+    echo -e "  ${BLUE}ℹ${RESET} $1"
+}
+
+print_warning() {
+    echo -e "  ${YELLOW}⚠${RESET} $1"
+}
+
+print_step() {
+    echo -e "\n${CYAN}${BOLD}$1${RESET}"
+}
+
+# Spinner animation for long-running tasks
+spinner() {
+    local pid=$1
+    local delay=0.1
+    local spinstr='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
+
+    while ps -p "$pid" > /dev/null 2>&1; do
+        local temp=${spinstr#?}
+        printf " ${CYAN}%c${RESET}  " "$spinstr"
+        spinstr=$temp${spinstr%"$temp"}
+        sleep $delay
+        printf "\b\b\b\b\b"
+    done
+    printf "    \b\b\b\b"
+}
+
+# Check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Get version of a command
+get_version() {
+    local cmd=$1
+    local version_flag=${2:---version}
+
+    if command_exists "$cmd"; then
+        $cmd $version_flag 2>&1 | head -n 1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n 1
+    else
+        echo ""
+    fi
+}
+
+# Compare versions (returns 0 if $1 >= $2)
+version_ge() {
+    [ "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]
+}
+
+# Prompt user for input with a default value
+prompt() {
+    local prompt_text=$1
+    local default_value=${2:-}
+    local user_input
+
+    if [ -n "$default_value" ]; then
+        echo -e -n "${WHITE}${prompt_text}${RESET} ${GRAY}(default: ${default_value})${RESET} ${CYAN}›${RESET} "
+    else
+        echo -e -n "${WHITE}${prompt_text}${RESET} ${CYAN}›${RESET} "
+    fi
+
+    read -r user_input
+
+    if [ -z "$user_input" ] && [ -n "$default_value" ]; then
+        echo "$default_value"
+    else
+        echo "$user_input"
+    fi
+}
+
+# Yes/No prompt
+prompt_yn() {
+    local prompt_text=$1
+    local default_value=${2:-y}
+    local user_input
+
+    if [ "$default_value" = "y" ]; then
+        echo -e -n "${WHITE}${prompt_text}${RESET} ${GRAY}(Y/n)${RESET} ${CYAN}›${RESET} "
+    else
+        echo -e -n "${WHITE}${prompt_text}${RESET} ${GRAY}(y/N)${RESET} ${CYAN}›${RESET} "
+    fi
+
+    read -r user_input
+    user_input=${user_input:-$default_value}
+
+    [[ "$user_input" =~ ^[Yy]$ ]]
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                               ASCII ART HEADER
+# ═══════════════════════════════════════════════════════════════════════════════
+
+show_header() {
+    clear
+    echo -e "${CYAN}"
+    cat << 'EOF'
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   ██████╗ ███████╗███████╗ █████╗                                 ║
+║  ██╔═══██╗██╔════╝██╔════╝██╔══██╗                                ║
+║  ██║   ██║███████╗███████╗███████║                                ║
+║  ██║   ██║╚════██║╚════██║██╔══██║                                ║
+║  ╚██████╔╝███████║███████║██║  ██║                                ║
+║   ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝                                ║
+║                                                                   ║
+║   Open Standard for Scalable AI Agents                            ║
+║   The OpenAPI of AI Agents - v0.3.0                               ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+EOF
+    echo -e "${RESET}"
+    echo ""
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                         PREREQUISITE CHECKS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+check_prerequisites() {
+    print_step "Checking prerequisites..."
+
+    local all_checks_passed=true
+
+    # Check Node.js
+    if command_exists node; then
+        local node_version
+        node_version=$(get_version node -v)
+        local node_major
+        node_major=$(echo "$node_version" | cut -d. -f1)
+
+        if [ "$node_major" -ge 18 ]; then
+            print_success "Node.js v${node_version} detected"
+        else
+            print_error "Node.js v${node_version} detected (v18+ required)"
+            all_checks_passed=false
+        fi
+    else
+        print_error "Node.js not found (v18+ required)"
+        print_info "Install from: https://nodejs.org/"
+        all_checks_passed=false
+    fi
+
+    # Check npm or pnpm
+    if command_exists npm; then
+        local npm_version
+        npm_version=$(get_version npm)
+        print_success "npm v${npm_version} detected"
+    elif command_exists pnpm; then
+        local pnpm_version
+        pnpm_version=$(get_version pnpm)
+        print_success "pnpm v${pnpm_version} detected"
+    else
+        print_error "npm or pnpm not found"
+        all_checks_passed=false
+    fi
+
+    # Check for API keys
+    local api_key_found=false
+
+    if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+        print_success "ANTHROPIC_API_KEY found"
+        api_key_found=true
+    fi
+
+    if [ -n "${OPENAI_API_KEY:-}" ]; then
+        print_success "OPENAI_API_KEY found"
+        api_key_found=true
+    fi
+
+    if [ -n "${GOOGLE_API_KEY:-}" ]; then
+        print_success "GOOGLE_API_KEY found"
+        api_key_found=true
+    fi
+
+    if [ "$api_key_found" = false ]; then
+        print_warning "No API keys found in environment"
+        print_info "Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY"
+        print_info "Example: export ANTHROPIC_API_KEY=sk-ant-..."
+        echo ""
+        if ! prompt_yn "Continue without API key?"; then
+            exit 1
+        fi
+    fi
+
+    # Check if ossa CLI is available
+    if command_exists ossa; then
+        print_success "ossa CLI available"
+    else
+        print_warning "ossa CLI not found globally"
+        print_info "The script will use local ossa commands"
+    fi
+
+    if [ "$all_checks_passed" = false ]; then
+        echo ""
+        print_error "Some prerequisites are missing. Please install them and try again."
+        exit 1
+    fi
+
+    echo ""
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                         AGENT CREATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+create_agent() {
+    print_step "Let's create your first agent!"
+    echo ""
+
+    # Get agent purpose from user
+    local agent_purpose
+    agent_purpose=$(prompt "What should your agent do?" "A helpful coding assistant")
+
+    # Generate agent name from purpose
+    local agent_name
+    agent_name=$(echo "$agent_purpose" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 ]//g' | sed 's/ \+/-/g' | cut -c1-50)
+    agent_name="${agent_name:-my-first-agent}"
+
+    # Prompt for filename
+    local filename
+    filename=$(prompt "Agent filename?" "${agent_name}.ossa.yaml")
+
+    # Determine LLM provider and model
+    local provider="anthropic"
+    local model="claude-sonnet-4-20250514"
+
+    if [ -n "${OPENAI_API_KEY:-}" ] && [ -z "${ANTHROPIC_API_KEY:-}" ]; then
+        provider="openai"
+        model="gpt-4o"
+    elif [ -n "${GOOGLE_API_KEY:-}" ] && [ -z "${ANTHROPIC_API_KEY:-}" ] && [ -z "${OPENAI_API_KEY:-}" ]; then
+        provider="google"
+        model="gemini-2.0-flash"
+    fi
+
+    echo ""
+    print_info "Creating ${filename}..."
+
+    # Create the OSSA manifest
+    cat > "$filename" << EOF
+# ╔═══════════════════════════════════════════════════════════════════════════════╗
+# ║                                                                               ║
+# ║   ██████╗ ███████╗███████╗ █████╗     ██╗   ██╗ ██████╗    ██████╗  ██████╗   ║
+# ║  ██╔═══██╗██╔════╝██╔════╝██╔══██╗    ██║   ██║██╔═████╗   ╚════██╗██╔═████╗  ║
+# ║  ██║   ██║███████╗███████╗███████║    ██║   ██║██║██╔██║    █████╔╝██║██╔██║  ║
+# ║  ██║   ██║╚════██║╚════██║██╔══██║    ╚██╗ ██╔╝████╔╝██║    ╚═══██╗████╔╝██║  ║
+# ║  ╚██████╔╝███████║███████║██║  ██║     ╚████╔╝ ╚██████╔╝██╗██████╔╝╚██████╔╝  ║
+# ║   ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝      ╚═══╝   ╚═════╝ ╚═╝╚═════╝  ╚═════╝   ║
+# ║                                                                               ║
+# ║               YOUR FIRST OSSA AGENT - CREATED BY QUICKSTART                   ║
+# ║                                                                               ║
+# ╚═══════════════════════════════════════════════════════════════════════════════╝
+#
+# This agent was generated by the OSSA quickstart script.
+# Learn more: https://openstandardagents.org/docs/getting-started/
+#
+# ═══════════════════════════════════════════════════════════════════════════════
+
+apiVersion: ossa/v0.3.0
+kind: Agent
+
+metadata:
+  name: ${agent_name}
+  version: 1.0.0
+  description: |
+    ${agent_purpose}
+  labels:
+    created-by: ossa-quickstart
+    difficulty: beginner
+
+spec:
+  # The role defines WHO the agent is and HOW it behaves
+  role: |
+    You are an AI agent designed to: ${agent_purpose}
+
+    Your capabilities:
+    - Understand natural language queries
+    - Provide clear, helpful responses
+    - Maintain context throughout conversations
+    - Admit when you don't know something
+
+    Communication style:
+    - Be concise but thorough
+    - Use examples when helpful
+    - Ask clarifying questions when needed
+    - Be friendly and professional
+
+  # LLM configuration - vendor-neutral and portable
+  llm:
+    provider: \${LLM_PROVIDER:-${provider}}
+    model: \${LLM_MODEL:-${model}}
+    temperature: 0.7
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# NEXT STEPS:
+#
+# 1. Validate:  ossa validate ${filename}
+# 2. Run:       ossa run ${filename} --interactive
+# 3. Learn:     Check out examples/ for more advanced features
+#
+# Add capabilities:
+#   - Tools:     See examples/getting-started/02-agent-with-tools.ossa.yaml
+#   - Safety:    See examples/getting-started/03-agent-with-safety.ossa.yaml
+#   - Messaging: See examples/getting-started/04-agent-with-messaging.ossa.yaml
+#   - Workflows: See examples/getting-started/05-workflow-composition.ossa.yaml
+#
+# Documentation: https://openstandardagents.org/docs/
+# ═══════════════════════════════════════════════════════════════════════════════
+EOF
+
+    print_success "Manifest created"
+    echo ""
+
+    echo "$filename"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                         VALIDATION
+# ═══════════════════════════════════════════════════════════════════════════════
+
+validate_agent() {
+    local filename=$1
+
+    print_step "Validating your agent..."
+    echo ""
+
+    # Try to find ossa command
+    local ossa_cmd=""
+
+    if command_exists ossa; then
+        ossa_cmd="ossa"
+    elif [ -x "$(dirname "$0")/ossa" ]; then
+        ossa_cmd="$(dirname "$0")/ossa"
+    else
+        print_warning "ossa CLI not found - skipping validation"
+        print_info "Install globally: npm install -g @bluefly/openstandardagents"
+        return 1
+    fi
+
+    # Run validation
+    if $ossa_cmd validate "$filename" 2>&1; then
+        echo ""
+        print_success "Schema validation passed"
+        print_success "LLM configuration valid"
+        print_success "All checks passed!"
+        return 0
+    else
+        echo ""
+        print_error "Validation failed"
+        return 1
+    fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                         TEST RUN
+# ═══════════════════════════════════════════════════════════════════════════════
+
+test_agent() {
+    local filename=$1
+
+    echo ""
+    if ! prompt_yn "Would you like to test your agent?"; then
+        return
+    fi
+
+    # Try to find ossa command
+    local ossa_cmd=""
+
+    if command_exists ossa; then
+        ossa_cmd="ossa"
+    elif [ -x "$(dirname "$0")/ossa" ]; then
+        ossa_cmd="$(dirname "$0")/ossa"
+    else
+        print_error "ossa CLI not found"
+        print_info "Install globally: npm install -g @bluefly/openstandardagents"
+        return 1
+    fi
+
+    # Check for API key
+    if [ -z "${ANTHROPIC_API_KEY:-}" ] && [ -z "${OPENAI_API_KEY:-}" ] && [ -z "${GOOGLE_API_KEY:-}" ]; then
+        print_error "No API key found in environment"
+        print_info "Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY"
+        return 1
+    fi
+
+    print_step "Running agent..."
+    echo ""
+    print_info "Agent will respond to: ${CYAN}Hello!${RESET}"
+    echo ""
+    echo -e "${GRAY}─────────────────────────────────────────────────────────────────${RESET}"
+
+    # Run the agent with a test input
+    echo "Hello!" | $ossa_cmd run "$filename" 2>&1 || true
+
+    echo -e "${GRAY}─────────────────────────────────────────────────────────────────${RESET}"
+    echo ""
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                         NEXT STEPS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+show_next_steps() {
+    local filename=$1
+
+    echo ""
+    echo -e "${GREEN}${BOLD}🎉 Congratulations!${RESET} ${WHITE}Your first OSSA agent is ready!${RESET}"
+    echo ""
+
+    print_header "Next steps:"
+    echo ""
+
+    echo -e "${BOLD}Run your agent:${RESET}"
+    echo -e "  ${CYAN}ossa run ${filename} --interactive${RESET}"
+    echo ""
+
+    echo -e "${BOLD}Add capabilities:${RESET}"
+    echo -e "  ${GRAY}Tools${RESET}      examples/getting-started/02-agent-with-tools.ossa.yaml"
+    echo -e "  ${GRAY}Safety${RESET}     examples/getting-started/03-agent-with-safety.ossa.yaml"
+    echo -e "  ${GRAY}Messaging${RESET}  examples/getting-started/04-agent-with-messaging.ossa.yaml"
+    echo -e "  ${GRAY}Workflows${RESET}  examples/getting-started/05-workflow-composition.ossa.yaml"
+    echo ""
+
+    echo -e "${BOLD}Export to frameworks:${RESET}"
+    echo -e "  ${CYAN}ossa export ${filename} --format langchain${RESET}"
+    echo -e "  ${CYAN}ossa export ${filename} --format crewai${RESET}"
+    echo -e "  ${CYAN}ossa export ${filename} --format autogen${RESET}"
+    echo ""
+
+    echo -e "${BOLD}Learn more:${RESET}"
+    echo -e "  ${BLUE}📚 Documentation:${RESET} https://openstandardagents.org/docs/"
+    echo -e "  ${BLUE}🔧 Tools Guide:${RESET}   https://openstandardagents.org/docs/tools/"
+    echo -e "  ${BLUE}🛡️  Safety Guide:${RESET}  https://openstandardagents.org/docs/safety/"
+    echo -e "  ${BLUE}💬 Community:${RESET}     https://github.com/blueflyio/openstandardagents/discussions"
+    echo ""
+
+    echo -e "${GRAY}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+    echo ""
+    echo -e "${DIM}Created with ❤️  by the OSSA community${RESET}"
+    echo ""
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+#                               MAIN
+# ═══════════════════════════════════════════════════════════════════════════════
+
+main() {
+    show_header
+    check_prerequisites
+
+    local filename
+    filename=$(create_agent)
+
+    # Validate the agent
+    if validate_agent "$filename"; then
+        # Test the agent if user wants
+        test_agent "$filename"
+    else
+        print_warning "Validation failed, but the manifest was created"
+        print_info "You can manually fix validation errors and try again"
+    fi
+
+    # Show next steps
+    show_next_steps "$filename"
+}
+
+# Run main function
+main "$@"

package/dist/adapters/anthropic/client.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Tool and Capability Mapping
+ * Convert between OSSA capabilities and Anthropic tools
+ */
+import type { Tool } from '@anthropic-ai/sdk/resources/messages';
+import type { AnthropicConfig } from './config.js';
+import type { OssaAgent } from '../../types/index.js';
+/**
+ * OSSA capability definition
+ */
+export interface OssaCapability {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    examples?: Array<{
+        name?: string;
+        input?: Record<string, unknown>;
+        output?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Tool handler function type
+ */
+export type ToolHandler = (args: Record<string, unknown>) => Promise<string | Record<string, unknown>>;
+/**
+ * Tool definition with handler
+ */
+export interface ToolDefinition {
+    tool: Tool;
+    handler?: ToolHandler;
+    capability?: OssaCapability;
+}
+/**
+ * Tool mapper for converting OSSA capabilities to Anthropic tools
+ */
+export declare class ToolMapper {
+    private tools;
+    /**
+     * Map OSSA capabilities to Anthropic tools
+     */
+    mapCapabilities(capabilities: OssaCapability[]): Tool[];
+    /**
+     * Map OSSA agent tools to Anthropic tools
+     */
+    mapAgentTools(agent: OssaAgent): Tool[];
+    /**
+     * Register a tool handler
+     */
+    registerToolHandler(name: string, handler: ToolHandler): boolean;
+    /**
+     * Get a tool by name
+     */
+    getTool(name: string): ToolDefinition | undefined;
+    /**
+     * Get all tools
+     */
+    getTools(): Tool[];
+    /**
+     * Execute a tool
+     */
+    executeTool(name: string, input: Record<string, unknown>): Promise<string>;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+    /**
+     * Convert OSSA capability to Anthropic tool
+     */
+    private convertCapabilityToTool;
+    /**
+     * Convert OSSA function tool to Anthropic tool
+     */
+    private convertFunctionToTool;
+    /**
+     * Normalize input schema to Anthropic format
+     */
+    private normalizeInputSchema;
+}
+/**
+ * Create tool mapper from OSSA agent
+ */
+export declare function createToolMapper(agent: OssaAgent): ToolMapper;
+/**
+ * Extract capabilities from OSSA agent
+ */
+export declare function extractCapabilities(agent: OssaAgent): OssaCapability[];
+/**
+ * Validate tool input against schema
+ */
+export declare function validateToolInput(input: Record<string, unknown>, schema: Record<string, unknown>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Create a simple tool definition
+ */
+export declare function createTool(name: string, description: string, properties: Record<string, {
+    type: string;
+    description?: string;
+}>, required?: string[]): Tool;
+/**
+ * Common tool templates
+ */
+export declare const COMMON_TOOLS: {
+    /**
+     * Web search tool
+     */
+    readonly webSearch: Tool;
+    /**
+     * Read file tool
+     */
+    readonly readFile: Tool;
+    /**
+     * Write file tool
+     */
+    readonly writeFile: Tool;
+    /**
+     * Execute code tool
+     */
+    readonly executeCode: Tool;
+    /**
+     * HTTP request tool
+     */
+    readonly httpRequest: Tool;
+};
+/**
+ * Anthropic Client Wrapper
+ * Provides compatibility layer for tests and legacy code
+ */
+export declare class AnthropicClient {
+    private config;
+    private stats;
+    constructor(config: AnthropicConfig);
+    getConfig(): AnthropicConfig;
+    getStats(): {
+        requestCount: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+    };
+    resetStats(): void;
+    updateConfig(config: Partial<AnthropicConfig>): void;
+}
+//# sourceMappingURL=client.d.ts.map