🔧 Installation Guide

Welcome to SuperOptiX! This guide will help you install the Full Stack Agentic AI Optimization Framework on your system.

🚀 Quick Start

New to SuperOptiX? Start with our Quick Start Guide after installation!

Stable Release Available!

SuperOptiX is now available as a stable release:

pip install superoptix

📋 Prerequisites

Required

Python 3.11+ (required)
Git (required for DSPy installation)
Package Manager (pip, conda, or uv)

Verify Requirements

# Check Python version
python --version  # Should be 3.11 or higher

# Check Git
git --version  # Should show git version

Install Git (if needed)

macOSLinuxWindows

xcode-select --install

# Ubuntu/Debian
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

Download from git-scm.com

Python Version Requirement

SuperOptiX requires Python 3.11 or higher. Check your version with:

python --version

🎯 Installation Methods

Framework-Free Core

SuperOptiX core is now framework-independent! 🎉

Install only what you need. Choose from 6 AI frameworks, or use core without any.

Choose your preferred installation method:

Core Only (Includes DSPy)With DSPy FrameworkWith Specific FrameworkAll DSPy-Compatible FrameworksWith MCP OptimizationWith EverythingUsing UVUsing Conda

pip install superoptix

Includes: CLI tools, SuperSpec DSL, YAML processing, template engine, DSPy

Use for: GEPA optimization, DSPy pipelines, evaluation

pip install superoptix[frameworks-dspy]

Includes: SuperOptiX core + DSPy + GEPA

Use for: GEPA optimization, DSPy pipelines, evaluation

# OpenAI Agents SDK
pip install superoptix[frameworks-openai]

# Google ADK
pip install superoptix[frameworks-google]

# Microsoft Agent Framework
pip install superoptix[frameworks-microsoft]

# DeepAgents
pip install superoptix[frameworks-deepagents]

# CrewAI (conflicts with DSPy)
pip install superoptix[frameworks-crewai]

Choose ONE or COMBINE (except DSPy + CrewAI)

pip install superoptix[frameworks]

Includes: DSPy, OpenAI SDK, Google ADK, Microsoft, DeepAgents

Excludes: CrewAI (conflicts with DSPy's json-repair)

pip install superoptix[mcp]

Includes: MCP SDK for tool optimization

pip install superoptix[all]

Includes: All frameworks + MCP + vector DBs + observability

# Install UV first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SuperOptiX
uv pip install superoptix

# Create environment
conda create -n superoptix python=3.11 -y
conda activate superoptix

# Install SuperOptiX
pip install superoptix

🖥️ Platform-Specific Instructions

🍎 macOS🐧 Linux🪟 Windows

Using Homebrew (Recommended)

# Install Python 3.11+
brew install python@3.11

# Install UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SuperOptiX
uv pip install superoptix

Using Conda

# Install Miniconda
brew install --cask miniconda

# Create environment
conda create -n superoptix python=3.11 -y
conda activate superoptix
pip install superoptix

Ubuntu/Debian

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python 3.11+ and Git
sudo apt install python3.11 python3.11-venv python3-pip git -y

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SuperOptiX
uv pip install superoptix

CentOS/RHEL/Fedora

# Fedora
sudo dnf install python3.11 python3-pip git -y

# CentOS/RHEL
sudo yum install python3.11 python3-pip git -y

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SuperOptiX
uv pip install superoptix

Windows Users - Important!

On Windows, set PYTHONUTF8=1 to ensure proper UTF-8 encoding support:

set PYTHONUTF8=1

Or add it to your system environment variables for permanent setting.

Using PowerShell

# Install Git first
# Download from: https://git-scm.com/downloads

# Install UV (recommended)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install SuperOptiX
uv pip install superoptix

Using Conda

# Download and install Miniconda
# https://docs.conda.io/en/latest/miniconda.html

# Install Git
# Download from: https://git-scm.com/downloads

# Create environment
conda create -n superoptix python=3.11 -y
conda activate superoptix
pip install superoptix

🔧 Optional Dependencies

SuperOptiX is modular - install only what you need! Here are the available extras:

🌐 Framework Support

SuperOptiX now supports 6 major AI agent frameworks. Install the ones you need:

Framework	Install Command	Includes
DSPy ⭐	`pip install superoptix[frameworks-dspy]`	DSPy + GEPA
OpenAI SDK	`pip install superoptix[frameworks-openai]`	openai-agents, openai SDK
Google ADK	`pip install superoptix[frameworks-google]`	google-adk, google-generativeai
Microsoft	`pip install superoptix[frameworks-microsoft]`	agent-framework, azure-identity
DeepAgents	`pip install superoptix[frameworks-deepagents]`	deepagents
CrewAI ⚠️	`pip install superoptix[frameworks-crewai]`	crewai (conflicts with DSPy)

⭐ Recommended: DSPy for GEPA optimization
⚠️ Note: CrewAI and DSPy cannot be installed together

Framework-Specific Setup:

DSPy (Recommended)OpenAI SDKGoogle ADKMicrosoftDeepAgentsCrewAI

# Install
pip install superoptix[frameworks-dspy]

Includes: DSPy + GEPA

Use for: GEPA optimization, evaluation, orchestration

No API key required - Works with Ollama, OpenAI, Anthropic, etc.

# Install
pip install superoptix[frameworks-openai]

# For OpenAI API (optional, Ollama works too)
export OPENAI_API_KEY=your-key

# Install
pip install superoptix[frameworks-google]

# Set API key
export GOOGLE_API_KEY=your-google-api-key

# Install
pip install superoptix[frameworks-microsoft]

# For Azure OpenAI
export AZURE_OPENAI_ENDPOINT=your-endpoint
export AZURE_OPENAI_API_KEY=your-key

# Install
pip install superoptix[frameworks-deepagents]

Use for: LangGraph-based planning and complex workflows

# Install
pip install superoptix[frameworks-crewai]

⚠️ Cannot be installed with DSPy (json-repair conflict)

Use for: Multi-agent crew workflows without DSPy optimization

🔌 MCP Tool Optimization

Optimize MCP tool descriptions and system prompts with GEPA:

pip install superoptix[mcp]

Includes: MCP SDK

Use Cases: - Optimize MCP tool descriptions - Improve system prompts for tool usage - Multi-tool selection optimization - Local and remote MCP servers

Example:

from superoptix.optimizers import MCPAdapter
import gepa

adapter = MCPAdapter(
    tool_names=["read_file", "write_file"],
    task_model="ollama/llama3.2:1b",
    metric_fn=my_metric,
)

result = gepa.optimize(
    seed_candidate={"tool_description": "Read files"},
    adapter=adapter,
    trainset=dataset,
)

See MCP Optimization Tutorial for details.

📦 Other Optional Dependencies

🤖 Local Model Management🎨 UI & Visualization🧠 Vector Databases (RAG)🔍 Observability & Monitoring🌐 Web Frameworks📊 Data Processing🤖 AI Framework Integration

For running models locally on your machine

MLX (Apple Silicon)

pip install "superoptix[mlx]"

Includes: - mlx-lm==0.26.0 (Apple MLX framework for local inference)

HuggingFace

pip install "superoptix[huggingface]"

Includes: - transformers==4.53.2 (HuggingFace transformers library) - torch==2.7.1 (PyTorch for model inference) - fastapi==0.116.1 (Web framework for model serving) - huggingface-hub==0.33.4 (HuggingFace Hub integration) - uvicorn==0.35.0 (ASGI server for FastAPI)

For SuperOptiX Agent Studio and observability dashboards

# Install UI dependencies
pip install "superoptix[ui]"

Includes: - Streamlit (Agent Studio) - Plotly (Interactive charts) - Pandas (Data manipulation)

For Retrieval-Augmented Generation and memory systems

# Individual databases
pip install "superoptix[chromadb]"    # ChromaDB (recommended)
pip install "superoptix[lancedb]"     # LanceDB (fast local)
pip install "superoptix[faiss]"       # FAISS (high performance)
pip install "superoptix[weaviate]"    # Weaviate (semantic search)
pip install "superoptix[qdrant]"      # Qdrant (production)
pip install "superoptix[milvus]"      # Milvus (enterprise)

# All vector databases
pip install "superoptix[vectordb]"

For tracing, monitoring, and MLflow integration

# Install observability dependencies
pip install "superoptix[observability]"

Includes: - MLflow (Experiment tracking) - Pandas (Data analysis) - Plotly (Visualization)

For building web APIs and services

# Install web dependencies
pip install "superoptix[web]"

Includes: - FastAPI (Modern web framework) - Uvicorn (ASGI server) - Pydantic (Data validation)

For data analysis and machine learning

# Install data processing dependencies
pip install "superoptix[data]"

Includes: - Pandas (Data manipulation) - Scikit-learn (Machine learning) - Matplotlib (Plotting) - Seaborn (Statistical visualization)

For advanced AI orchestration and multi-agent systems

# Install core AI framework dependencies
pip install "superoptix[optimas]"

Includes: - DSPy (Prompt optimization framework) - OpenAI (LLM integration) - AutoGen (Multi-agent conversations) - Optimas AI (Advanced orchestration)

CrewAI Dependency Conflict

CrewAI has a known dependency conflict with DSPy due to incompatible json-repair version requirements:

DSPy 3.0.0 requires json-repair>=0.30.0
CrewAI 0.157.0 requires json-repair==0.25.2

To use CrewAI with SuperOptiX, install it manually:

# 1. Install SuperOptiX with DSPy support
pip install "superoptix[optimas]"

# 2. Install CrewAI without dependencies
pip install crewai==0.157.0 --no-deps

# 3. Ensure compatible json-repair version
pip install "json-repair>=0.30.0"

This approach bypasses the dependency conflict while maintaining compatibility.

🔍 Verification

After installation, verify SuperOptiX is working correctly:

# Check installation
python -c "import superoptix; print('SuperOptiX installed successfully!')"

# Check CLI
super --version

# Check available commands
super --help

🚀 Next Steps

Set up your LLM: Follow our LLM Setup Guide
Create your first agent: Try our Quick Start Guide
Explore the framework: Check out our Agent Patterns

🆘 Troubleshooting

Common Issues

Import Error: Make sure you're using Python 3.11+

python --version

Permission Error: Use virtual environments

# Create virtual environment
python -m venv superoptix-env
source superoptix-env/bin/activate  # Linux/macOS
# or
superoptix-env\Scripts\activate     # Windows

Package Not Found: Update pip

pip install --upgrade pip

CrewAI Installation Conflicts: If you encounter dependency conflicts when installing CrewAI with SuperOptiX:

# The issue: CrewAI requires json-repair==0.25.2, but DSPy needs json-repair>=0.30.0
# Solution: Install manually with --no-deps flag
pip install "superoptix[optimas]"  # Install DSPy support first
pip install crewai==0.157.0 --no-deps  # Install CrewAI without dependencies
pip install "json-repair>=0.30.0"  # Ensure compatible version

Still Having Issues?

📖 Check our Troubleshooting Guide
🐛 Report issues on GitHub