Skip to content

📖 Reference

Quick reference documentation for SuperOptix APIs, CLI commands, and troubleshooting guides.

🔍 Quick Navigation

📚 API Reference

Complete Python SDK documentation: - Core Classes - Agent, Orchestra, Pipeline - Configuration - SuperSpec DSL objects - Memory Systems - Memory backends and interfaces - Tool Integration - Custom tool development - Inference Engines - Model provider integrations - Observability - Monitoring and debugging APIs

⌨️ CLI Reference

Command-line interface documentation: - super init - Initialize new projects - super agent - Agent management commands - super orchestra - Multi-agent orchestration - super model - Model management - super market - Marketplace operations - super observe - Observability commands

🔧 Troubleshooting

Common issues and solutions: - Installation Problems - Setup and dependency issues - Configuration Errors - SuperSpec DSL validation - Runtime Errors - Agent execution problems - Performance Issues - Optimization and scaling - Integration Problems - Third-party service issues

🚀 Quick Start Reference

Essential Commands

# Initialize new project
super init my-agent --tier genie

# Compile agent
super agent compile --spec agent.yaml

# Run evaluation
super agent evaluate --spec agent.yaml

# Optimize performance
super agent optimize --spec agent.yaml

# Deploy to production
super agent run --spec agent.yaml --env production

Core Configuration

# Minimal agent configuration
name: my-agent
tier: genie
description: "A helpful AI assistant"

capabilities:
  - conversation
  - reasoning

inference:
  provider: openai
  model: gpt-4

memory:
  episodic: true
  semantic: false

tools:
  - web_search
  - calculator

📋 Cheat Sheets

SuperSpec DSL Quick Reference

Basic Structure

# Agent metadata
name: string           # Required
tier: oracle|genie|sage # Required
description: string    # Optional
version: string        # Optional

# Core capabilities
capabilities:
  - conversation       # Basic chat
  - reasoning         # Logical thinking
  - knowledge_retrieval # Information access
  - task_execution    # Action taking
  - multimodal        # Text, image, audio

# Inference configuration
inference:
  provider: string     # openai, anthropic, local, etc.
  model: string        # Model identifier
  temperature: float   # 0.0 to 1.0
  max_tokens: int      # Response length limit
  streaming: bool      # Enable streaming

# Memory systems
memory:
  episodic: bool       # Conversation history
  semantic: bool       # Knowledge graph
  working: bool        # Short-term context
  backends:
    - type: string     # chroma, lancedb, etc.
      config: object   # Backend-specific config

# Tool integration
tools:
  - name: string       # Tool identifier
    config: object     # Tool configuration
    required: bool     # Whether tool is required

# Orchestration (multi-agent)
orchestra:
  coordination: string # workflow, broadcast, etc.
  agents:
    - name: string     # Agent identifier
      role: string     # Agent role
      dependencies: [] # Required agents

# Observability
observability:
  tracing: bool        # Enable tracing
  metrics: bool        # Collect metrics
  logging: bool        # Enable logging
  dashboard: bool      # Web dashboard

CLI Command Reference

Project Management

# Create new project
super init <name> [--tier <tier>] [--template <template>]

# Validate configuration
super agent validate --spec <file>

# Show project info
super agent info --spec <file>

Development Workflow

# Compile agent
super agent compile --spec <file> [--output <dir>]

# Run evaluation
super agent evaluate --spec <file> [--scenarios <dir>]

# Optimize performance
super agent optimize --spec <file> [--iterations <n>]

# Generate playbook
super agent playbook --spec <file> --output <file>

Model Management

# List available models
super model list [--provider <provider>]

# Download model
super model download <model> [--provider <provider>]

# Test model
super model test <model> [--prompt <text>]

Marketplace

# Search agents
super market search <query>

# Install agent
super market install <agent>

# Publish agent
super market publish --spec <file>

Error Codes Reference

Common Error Codes

  • SOX001 - Configuration validation error
  • SOX002 - Missing required dependency
  • SOX003 - Model not found
  • SOX004 - Authentication failure
  • SOX005 - Rate limit exceeded
  • SOX006 - Memory allocation error
  • SOX007 - Tool execution timeout
  • SOX008 - Network connectivity issue
  • SOX009 - File system permission error
  • SOX010 - Invalid tier specification

Quick Fixes

# Fix configuration
super agent validate --spec <file> --fix

# Reset environment
super init --reset

# Clear cache
super cache clear

# Update dependencies
super install --update

🔧 Configuration Examples

Single Agent

name: customer-service
tier: genie
description: "24/7 customer support assistant"

capabilities:
  - conversation
  - knowledge_retrieval
  - task_execution

inference:
  provider: openai
  model: gpt-4
  temperature: 0.7

memory:
  episodic: true
  semantic: true
  backends:
    - type: chroma
      config:
        persist_directory: "./memory"

tools:
  - name: search_knowledge_base
    config:
      database_url: "postgresql://..."
  - name: create_ticket
    config:
      api_key: "${TICKETING_API_KEY}"

Multi-Agent Orchestra

name: ecommerce-platform
description: "Complete e-commerce agent system"

agents:
  - name: product-recommender
    tier: genie
    capabilities: [reasoning, knowledge_retrieval]

  - name: inventory-manager
    tier: oracle
    capabilities: [task_execution]

  - name: order-processor
    tier: genie
    capabilities: [task_execution, reasoning]

  - name: customer-service
    tier: genie
    capabilities: [conversation, knowledge_retrieval]

orchestration:
  coordination: workflow
  patterns:
    - type: pipeline
      flow: [product-recommender, inventory-manager, order-processor]
    - type: broadcast
      agents: [customer-service]

🌟 Best Practices

Configuration Guidelines

  • Use meaningful names - Clear, descriptive agent names
  • Document everything - Include descriptions for all components
  • Version control - Track configuration changes
  • Environment variables - Use for sensitive data
  • Validation - Always validate before deployment

Performance Tips

  • Choose appropriate tier - Match complexity to requirements
  • Cache frequently used data - Reduce API calls
  • Use streaming - For better user experience
  • Monitor resource usage - Track CPU, memory, and costs
  • Implement fallbacks - Handle failures gracefully

Security Considerations

  • Protect API keys - Use environment variables
  • Validate inputs - Sanitize user data
  • Implement rate limiting - Prevent abuse
  • Audit access - Track agent usage
  • Update dependencies - Keep libraries current

This reference section provides everything you need for quick lookups and troubleshooting. 🚀