superopt 0.1.1

Agentic Environment Optimization for Autonomous AI Agents

🚀 SuperOpt

Agentic Environment Optimization for Autonomous AI Agents

SuperOpt is a unified framework for optimizing agent environments (prompts, tools, retrieval, memory) without modifying model parameters. It treats the entire agent environment as a structured optimization target, enabling autonomous agents to self-correct and stabilize over time.

---

✨ Key Features

🚀 Environment-Level Optimization	🎯 Automatic Failure Diagnosis	🛡️ Stability Guarantees
Optimize prompts, tools, retrieval, and memory as a unified system	Intelligent routing of failures to appropriate optimizers	Hierarchy of mutability prevents oscillation and ensures convergence

📊 Trace-Based Learning	⚡ No Model Retraining	🔧 Framework Agnostic
Uses execution traces as supervision signals	All improvements happen at the environment level	Works with DSPy, CrewAI, AutoGen, and custom agents

🏗️ Architecture Overview

SuperOpt formalizes optimization as iterative descent over Natural Language Gradients derived from execution traces. A meta-diagnostic controller attributes failures to specific environment layers and routes corrective updates to specialized optimization engines.

Core Components

🎯 SuperController	📝 SuperPrompt	🔧 SuperReflexion	🔍 SuperRAG	🧠 SuperMem
Diagnostic meta-controller for failure routing	Evolutionary instruction optimization (GEPA-based)	Self-healing tool schema repair	Adaptive retrieval optimization	Typed memory with decay and conflict resolution

Research Paper

The research paper describing SuperOpt has been uploaded and will be available soon after launch.

Key Features

• Environment-Level Optimization: Optimize prompts, tools, retrieval, and memory as a unified system
• Failure Attribution: Automatic diagnosis and routing of failures to appropriate optimizers
• Stability Guarantees: Hierarchy of mutability prevents oscillation and ensures convergence
• Trace-Based Learning: Uses execution traces as supervision signals
• No Model Retraining: All improvements happen at the environment level

📦 Installation

Quick Install

pip install superopt

From Source

git clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e .

Optional Dependencies

Feature	Install Command	Description
🧪 Development	pip install -e ".[dev]"	Testing, linting, formatting tools
🤖 Aider Integration	pip install -e ".[aider]"	Coding agent optimization
🔍 LanceDB RAG	pip install -e ".[lancedb]"	Vector database for retrieval
📦 Everything	pip install -e ".[all]"	All optional dependencies

⚡ Quick Start

🚀 Try It Now

Copy and run this complete example:

# Complete SuperOpt Example - Copy this entire file to test SuperOpt
from superopt import SuperOpt, AgenticEnvironment
from superopt.core.environment import PromptConfig, ToolSchema
from superopt.core.trace import ExecutionTrace, ToolCall

# 1. Define your agent's environment
environment = AgenticEnvironment(
    prompts=PromptConfig(
        system_prompt="You are a helpful coding assistant."
    ),
    tools={
        "edit_file": ToolSchema(
            name="edit_file",
            description="Edit a file at a specific line",
            arguments={"file": "str", "line": "int"},
        ),
    },
)

# 2. Initialize the optimizer
optimizer = SuperOpt(environment=environment)

# 3. Simulate agent execution with a failure
trace = ExecutionTrace(
    task_description="Edit line 0 in test.py",
    success=False,
)
trace.tool_errors.append(ToolCall(
    tool_name="edit_file",
    arguments={"file": "test.py", "line": 0},
    error_message="Line numbers must be 1-indexed",
))

# 4. Let SuperOpt learn and optimize
print("Before optimization:")
print(optimizer.environment.tools['edit_file'].description)
print()

optimizer.step(trace)

# 5. Check the improved environment
print("After optimization:")
print(optimizer.environment.tools['edit_file'].description)

To test this example:

1. Save the code above as test_superopt.py
2. Run python test_superopt.py
3. You should see the tool description get updated with the 1-indexing constraint

🏃‍♂️ Run the Official Example

python examples/basic_example.py

Expected Output:

SuperOpt Basic Example
==================================================

1. Initial Environment:
   Tool schema description: Edit a file by applying changes...

2. Executing task with tool error...
   Error: Line numbers must be 1-indexed, not 0-indexed

3. Optimizing environment...

4. Updated Environment:
   Tool schema description length: 126 chars
   ✓ Schema was updated with clarifications

5. Statistics:
   Controller diagnoses: {'PROMPT': 0, 'TOOL': 1, 'RETRIEVAL': 0, 'MEMORY': 0, 'NONE': 0}
   Optimization steps: 1

🔄 How SuperOpt Works

SuperOpt operates in an outer optimization loop surrounding the agent execution loop:

┌─────────────────────────────────────────────────────────────┐
│                    🚀 SuperOpt Optimization Loop             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                  🤖 Agent Execution Loop                 ││
│  │   Task → Agent → Tool Calls → Results → Output          ││
│  └─────────────────────────────────────────────────────────┘│
│                           │                                  │
│                    📊 Execution Trace                        │
│                           ↓                                  │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              🎯 SuperController (Diagnosis)              ││
│  │   Classify failure: PROMPT | TOOL | RETRIEVAL | MEMORY  ││
│  └─────────────────────────────────────────────────────────┘│
│                           │                                  │
│         ┌─────────────────┼─────────────────┐               │
│         ↓                 ↓                 ↓               │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐           │
│   │📝 Super- │     │🔧 Super-   │     │🔍 Super- │           │
│   │   Prompt │     │ Reflexion │     │   RAG   │           │
│   │(Prompts) │     │  (Tools)  │     │(Retrieval)│          │
│   └──────────┘     └──────────┘     └──────────┘           │
│         │                 │                 │               │
│         └─────────────────┼─────────────────┘               │
│                           ↓                                  │
│              🌟 Natural Language Gradient (∇_NL)            │
│                           ↓                                  │
│                  ✨ Updated Environment Φ                   │
└─────────────────────────────────────────────────────────────┘

📋 Optimization Workflow

Step	Action	Description
1️⃣	Execute	Run agent task under current environment
2️⃣	Capture	Record structured execution trace
3️⃣	Diagnose	SuperController classifies the failure mode
4️⃣	Route	Send trace to the appropriate optimizer
5️⃣	Generate	Create Natural Language Gradient update
6️⃣	Validate	Check update against stability constraints
7️⃣	Apply	Update environment and persist
8️⃣	Repeat	Continue until convergence

🧩 Core Components

🎯 SuperController

Diagnostic Meta-Controller

The intelligent orchestrator that analyzes execution traces and routes optimization tasks to the appropriate component:

• PROMPT: Handles instruction violations, format errors, and unclear prompts
• TOOL: Detects schema violations, invalid arguments, and tool misuse
• RETRIEVAL: Identifies missing symbols, empty results, and retrieval failures
• MEMORY: Catches repeated mistakes, contradictions, and memory issues

📝 SuperPrompt

Evolutionary Prompt Optimizer

Advances prompt engineering through systematic optimization:

• Reflective mutation guided by execution traces and failure patterns
• Pareto-based selection across multiple objectives (accuracy, efficiency, clarity)
• Population-based search using GEPA methodology for prompt evolution
• Automatic prompt refinement based on real-world performance data

🔧 SuperReflexion

Self-Healing Tool Schemas

Automatically repairs and enhances tool definitions when agents encounter issues:

• Analyzes tool failures and error patterns in real-time
• Generates schema clarifications and constraint additions automatically
• Appends important constraints to tool descriptions to prevent future errors
• Learns from agent mistakes to improve tool reliability

🔍 SuperRAG

Adaptive Retrieval Optimization

Dynamically optimizes retrieval-augmented generation systems:

• Optimizes top_k retrieval count based on query complexity and context
• Adapts chunk size and overlap for better semantic understanding
• Tunes reranking thresholds to improve result relevance
• Automatically switches between semantic vs structural retrieval modes

🧠 SuperMem

Intelligent Memory System

Advanced memory management with hierarchical organization:

• Type hierarchy: TOOL_RULE > RAG_HEURISTIC > STRATEGY for organized knowledge
• Exponential decay: Relevance-based forgetting to maintain current knowledge
• Conflict resolution: Automatic detection and resolution of contradictory information
• Confidence tracking: Validation and uncertainty quantification for memory entries

Integration with Agents

SuperOpt provides adapters for popular agent frameworks:

Using with Aider

from superopt.adapters import AiderAdapter
from superopt import SuperOpt

# Create adapter for your Aider instance
adapter = AiderAdapter(
    model="gpt-4",
    coder_class="EditBlockCoder",
)

# Extract the current environment
environment = adapter.extract_environment()

# Initialize optimizer
optimizer = SuperOpt(environment=environment)

# Run optimization episode
results = optimizer.optimize_episode(
    task_description="Fix the failing tests in auth.py",
    agent_executor=adapter.execute,
    max_iterations=10,
)

# Apply optimized environment back to agent
adapter.apply_environment(optimizer.environment)

Custom Agent Integration

from superopt.adapters.base import AgentAdapter
from superopt import AgenticEnvironment, ExecutionTrace

class MyAgentAdapter(AgentAdapter):
    def extract_environment(self) -> AgenticEnvironment:
        """Extract current environment from your agent."""
        return AgenticEnvironment(
            prompts=self.agent.get_prompts(),
            tools=self.agent.get_tools(),
        )

    def apply_environment(self, env: AgenticEnvironment) -> None:
        """Apply optimized environment back to agent."""
        self.agent.set_prompts(env.prompts)
        self.agent.set_tools(env.tools)

    def execute(self, task: str) -> ExecutionTrace:
        """Execute task and return trace."""
        result = self.agent.run(task)
        return self._create_trace(result)

📊 Evaluation & Benchmarks

🏃‍♂️ Run Evaluations

# Quick evaluation on sample tasks
python scripts/evaluate_baseline.py --tasks data/tasks/sample_tasks.json
python scripts/evaluate_superopt.py --tasks data/tasks/sample_tasks.json
python scripts/compare_all.py --tasks data/tasks/sample_tasks.json

# Analyze results
python scripts/analyze_results.py --results-dir results/

📈 Evaluation Metrics

SuperOpt evaluates improvements across multiple dimensions:

🔒 Reliability	🛡️ Stability	⚡ Efficiency	🌍 Generalization	👁️ Interpretability
Reduction in repeated failures	Persistence of improvements over time	Token usage, retry counts	Transfer across tasks	Human-readable updates

🔬 Related Research

SuperOpt builds upon groundbreaking work in agent optimization:

🎯 GEPA	🧠 ACE	🎓 Meta-ACE	🔧 DSPy	📝 TextGrad
Evolutionary prompt optimization	Agentic context engineering	Meta-reasoning extensions	Prompt programming framework	Textual differentiation

Agrawal et al. (2025) • Zhang et al. (2025) • Romero (2025) • Khattab et al. (2023) • Yuksekgonul et al. (2024)

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

🛠️ Development Setup

git clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e ".[dev]"

# Run tests and quality checks
pytest
black .
ruff check .

---

📄 License

Apache License 2.0 - see LICENSE file for details.

🤝 Support & Community

📧 Email	🐛 Issues	💬 Discussions	🌟 Contribute
[e-mail]	GitHub Issues	GitHub Discussions	Contributing Guide

---

Brought to you 🔥 by Superagentic AI