Metadata-Version: 2.4
Name: superopt
Version: 0.1.0
Summary: Agentic Environment Optimization for Autonomous AI Agents
Project-URL: Homepage, https://github.com/SuperagenticAI/superopt
Project-URL: Documentation, https://github.com/SuperagenticAI/superopt#readme
Project-URL: Repository, https://github.com/SuperagenticAI/superopt
Project-URL: Issues, https://github.com/SuperagenticAI/superopt/issues
Project-URL: Changelog, https://github.com/SuperagenticAI/superopt/blob/main/CHANGELOG.md
Author-email: Shashi Jagtap <shashi@super-agentic.ai>, Shashi Jagtap <shashikant.jagtap@icloud.com>
Maintainer-email: Shashi Jagtap <team@super-agentic.ai>, Shashi Jagtap <shashikant.jagtap@icloud.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,autonomous,llm,natural-language-gradients,optimization,prompts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0.0
Provides-Extra: aider
Requires-Dist: backoff>=2.2.0; extra == 'aider'
Requires-Dist: beautifulsoup4>=4.14.0; extra == 'aider'
Requires-Dist: configargparse>=1.7.0; extra == 'aider'
Requires-Dist: diff-match-patch>=20241021; extra == 'aider'
Requires-Dist: diskcache>=5.6.0; extra == 'aider'
Requires-Dist: gitpython>=3.1.0; extra == 'aider'
Requires-Dist: grep-ast>=0.9.0; extra == 'aider'
Requires-Dist: importlib-metadata<8.0.0; extra == 'aider'
Requires-Dist: importlib-resources>=6.5.0; extra == 'aider'
Requires-Dist: json5>=0.12.0; extra == 'aider'
Requires-Dist: jsonschema>=4.0.0; extra == 'aider'
Requires-Dist: litellm>=1.80.0; extra == 'aider'
Requires-Dist: mixpanel>=5.0.0; extra == 'aider'
Requires-Dist: networkx<3.5; extra == 'aider'
Requires-Dist: oslex>=0.1.0; extra == 'aider'
Requires-Dist: packaging>=25.0; extra == 'aider'
Requires-Dist: pathspec>=0.12.0; extra == 'aider'
Requires-Dist: pexpect>=4.9.0; extra == 'aider'
Requires-Dist: pillow>=12.0.0; extra == 'aider'
Requires-Dist: posthog>=7.0.0; extra == 'aider'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'aider'
Requires-Dist: psutil>=7.1.0; extra == 'aider'
Requires-Dist: pydub>=0.25.0; extra == 'aider'
Requires-Dist: pypandoc>=1.16.0; extra == 'aider'
Requires-Dist: pyperclip>=1.11.0; extra == 'aider'
Requires-Dist: pyyaml>=6.0.0; extra == 'aider'
Requires-Dist: rich>=14.0.0; extra == 'aider'
Requires-Dist: scipy<1.16; extra == 'aider'
Requires-Dist: shtab>=1.8.0; extra == 'aider'
Requires-Dist: socksio>=1.0.0; extra == 'aider'
Requires-Dist: watchfiles>=1.1.0; extra == 'aider'
Provides-Extra: all
Requires-Dist: backoff>=2.2.0; extra == 'all'
Requires-Dist: beautifulsoup4>=4.14.0; extra == 'all'
Requires-Dist: black>=23.0.0; extra == 'all'
Requires-Dist: configargparse>=1.7.0; extra == 'all'
Requires-Dist: diff-match-patch>=20241021; extra == 'all'
Requires-Dist: diskcache>=5.6.0; extra == 'all'
Requires-Dist: gitpython>=3.1.0; extra == 'all'
Requires-Dist: grep-ast>=0.9.0; extra == 'all'
Requires-Dist: importlib-metadata<8.0.0; extra == 'all'
Requires-Dist: importlib-resources>=6.5.0; extra == 'all'
Requires-Dist: json5>=0.12.0; extra == 'all'
Requires-Dist: jsonschema>=4.0.0; extra == 'all'
Requires-Dist: lancedb>=0.26.0; extra == 'all'
Requires-Dist: litellm>=1.80.0; extra == 'all'
Requires-Dist: mixpanel>=5.0.0; extra == 'all'
Requires-Dist: mypy>=1.0.0; extra == 'all'
Requires-Dist: networkx<3.5; extra == 'all'
Requires-Dist: oslex>=0.1.0; extra == 'all'
Requires-Dist: packaging>=25.0; extra == 'all'
Requires-Dist: pathspec>=0.12.0; extra == 'all'
Requires-Dist: pexpect>=4.9.0; extra == 'all'
Requires-Dist: pillow>=12.0.0; extra == 'all'
Requires-Dist: posthog>=7.0.0; extra == 'all'
Requires-Dist: pre-commit>=3.0.0; extra == 'all'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'all'
Requires-Dist: psutil>=7.1.0; extra == 'all'
Requires-Dist: pydub>=0.25.0; extra == 'all'
Requires-Dist: pypandoc>=1.16.0; extra == 'all'
Requires-Dist: pyperclip>=1.11.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: pyyaml>=6.0.0; extra == 'all'
Requires-Dist: rich>=14.0.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: scipy<1.16; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Requires-Dist: shtab>=1.8.0; extra == 'all'
Requires-Dist: socksio>=1.0.0; extra == 'all'
Requires-Dist: watchfiles>=1.1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: lancedb
Requires-Dist: lancedb>=0.26.0; extra == 'lancedb'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'lancedb'
Description-Content-Type: text/markdown

# 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.

## 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:

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

## 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

### Basic Installation

```bash
pip install superopt
```

### Install from Source

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

### Optional Dependencies

```bash
# Development tools (pytest, black, ruff, mypy)
pip install -e ".[dev]"

# Aider integration (for coding agent optimization)
pip install -e ".[aider]"

# LanceDB for RAG optimization
pip install -e ".[lancedb]"

# All optional dependencies
pip install -e ".[all]"
```

## Quick Start

### Basic Usage

```python
from superopt import SuperOpt, AgenticEnvironment, ExecutionTrace
from superopt.core.environment import PromptConfig, ToolSchema
from superopt.core.trace import ToolCall, FailureType

# 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. After your agent fails, create a trace
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",
))
trace.failure_type = FailureType.TOOL

# 4. Optimize - SuperOpt will fix the tool schema
optimizer.step(trace)

# 5. The environment is now updated
print(optimizer.environment.tools['edit_file'].description)
# Output: "Edit a file at a specific line. Note: Line numbers must be 1-indexed, not 0-indexed."
```

### Run the Example

```bash
python examples/basic_example.py
```

## Architecture

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  ││
│  └─────────────────────────────────────────────────────────┘│
│                           │                                  │
│         ┌─────────────────┼─────────────────┐               │
│         ↓                 ↓                 ↓               │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐           │
│   │SuperPrompt│     │SuperReflexion│  │ SuperRAG │           │
│   │(Prompts) │     │  (Tools)  │     │(Retrieval)│           │
│   └──────────┘     └──────────┘     └──────────┘           │
│         │                 │                 │               │
│         └─────────────────┼─────────────────┘               │
│                           ↓                                  │
│              Natural Language Gradient           │
│                           ↓                                  │
│                  Updated Environment Φ                       │
└─────────────────────────────────────────────────────────────┘
```

**Optimization Steps:**

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

## Components

### SuperController

Diagnostic meta-controller that classifies failures into:
- **PROMPT**: Instruction violations, format errors
- **TOOL**: Schema violations, invalid arguments
- **RETRIEVAL**: Missing symbols, empty results
- **MEMORY**: Repeated mistakes, contradictions

### SuperPrompt

Evolutionary prompt optimizer using:
- Reflective mutation guided by execution traces
- Pareto-based selection across multiple objectives
- Population-based search

### SuperReflexion

Tool schema repair that:
- Analyzes tool failures
- Generates schema clarifications
- Appends constraints to tool descriptions

### SuperRAG

Retrieval optimizer that adapts:
- `top_k` retrieval count
- Chunk size and overlap
- Reranking thresholds
- Semantic vs structural modes

### SuperMem

Typed memory system with:
- Type hierarchy (TOOL_RULE > RAG_HEURISTIC > STRATEGY)
- Exponential decay
- Conflict resolution
- Confidence tracking

## Integration with Agents

SuperOpt provides adapters for popular agent frameworks:

### Using with Aider

```python
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

```python
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)
```

## Running Evaluations

### Evaluate on Sample Tasks

```bash
# Run baseline (no optimization)
python scripts/evaluate_baseline.py \
    --tasks data/tasks/sample_tasks.json \
    --output results/baseline.json

# Run with GEPA (prompt-only optimization)
python scripts/evaluate_gepa.py \
    --tasks data/tasks/sample_tasks.json \
    --output results/gepa.json

# Run with SuperOpt (full optimization)
python scripts/evaluate_superopt.py \
    --tasks data/tasks/sample_tasks.json \
    --output results/superopt.json

# Compare all methods
python scripts/compare_all.py \
    --tasks data/tasks/sample_tasks.json \
    --output results/comparison.json
```

### Analyze Results

```bash
python scripts/analyze_results.py --results-dir results/
```

## Project Structure

```
superopt/
├── superopt/                 # Main package
│   ├── core/                 # Core abstractions
│   │   ├── environment.py    # AgenticEnvironment, PromptConfig, ToolSchema
│   │   ├── trace.py          # ExecutionTrace, ToolCall
│   │   └── nlg.py            # NaturalLanguageGradient
│   ├── adapters/             # Agent framework integrations
│   │   ├── base.py           # AgentAdapter base class
│   │   ├── aider_adapter.py  # Aider integration
│   │   └── letta_adapter.py  # Letta integration
│   ├── comparison/           # Comparison with baselines
│   ├── rag/                  # RAG optimization (LanceDB)
│   ├── optimizer.py          # Main SuperOpt class
│   ├── supercontroller.py    # Failure diagnosis
│   ├── superprompt.py        # Prompt optimization
│   ├── superreflexion.py     # Tool schema repair
│   ├── superrag.py           # Retrieval optimization
│   └── supermem.py           # Memory optimization
├── examples/                 # Usage examples
├── scripts/                  # Evaluation scripts
├── data/                     # Task datasets
├── tests/                    # Unit tests
└── pyproject.toml            # Package configuration
```

## Evaluation

SuperOpt evaluates improvements along multiple dimensions:

- **Reliability**: Reduction in repeated failures
- **Stability**: Persistence of improvements over time
- **Efficiency**: Token usage, retry counts
- **Generalization**: Transfer across tasks
- **Interpretability**: Human-readable updates

## Paper

This implementation accompanies the paper:

> **SuperOpt: Agentic Environment Optimization for Autonomous AI Agents**
> Shashi Jagtap, Superagentic AI
> arXiv:XXXX.XXXXX (2025)

## Related Work

SuperOpt builds on and extends:
- **GEPA** [Agrawal et al., 2025]: Evolutionary prompt optimization
- **ACE** [Zhang et al., 2025]: Agentic context engineering
- **Meta-ACE** [Romero, 2025]: Meta-reasoning extensions
- **DSPy** [Khattab et al., 2023]: Prompt programming framework
- **TextGrad** [Yuksekgonul et al., 2024]: Textual differentiation

## Contributing

Contributions welcome! Please:

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

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

# Run tests
pytest

# Format code
black .
ruff check .

# Type checking
mypy superopt/
```

## License

Apache License 2.0 - see [LICENSE](LICENSE) file for details.

## Citation

If you use SuperOpt in your research, please cite:

```bibtex
@misc{jagtap2025superopt,
  title={SuperOpt: Agentic Environment Optimization for Autonomous AI Agents},
  author={Jagtap, Shashi},
  year={2025},
  howpublished={\url{https://github.com/SuperagenticAI/superopt}},
  note={Superagentic AI}
}
```

## Support

- **Issues**: [GitHub Issues](https://github.com/SuperagenticAI/superopt/issues)
- **Discussions**: [GitHub Discussions](https://github.com/SuperagenticAI/superopt/discussions)
- **Email**: shashi@super-agentic.ai
