EVOSEAL is an advanced AI agent designed to solve complex tasks through code evolution while continuously improving its own architecture. It integrates three key technologies:
SEAL (Self-Adapting Language Models): A framework for training language models via reinforcement learning to generate self-edits (finetuning data and update directives for themselves). SEAL focuses on knowledge incorporation and few-shot learning to adapt models to new tasks with minimal examples.
OpenEvolve: An evolutionary framework for program optimization that uses a MAP-Elites process to maintain diversity, comprehensive checkpointing, and a sophisticated database system to track program versions and their performance metrics.
DGM (Darwin Godel Machine): Implements a Darwinian approach to code improvement using SEAL models to progressively enhance code quality through multiple generations. DGM maintains an archive of successful improvements and uses sophisticated selection mechanisms to guide evolution.
Get started with EVOSEAL in minutes:
# Clone the repository git clone https://github.com/Continual-Intelligence/SEAL cd EVOSEAL # Set up virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Install in development mode pip install -e . # Run the basic example python -m evoseal.examples.basic.quickstart
Start a new project using our template:
# Copy the template to a new directory cp -r evoseal/examples/templates/basic my_project cd my_project # Install dependencies pip install -r requirements.txt
evoseal/
├── core/ # Core framework components
│ ├── __init__.py # Package initialization
│ ├── controller.py # Main orchestration logic
│ ├── evaluator.py # Fitness evaluation
│ ├── selection.py # Selection algorithms
│ └── version_database.py # Tracking program versions
│
├── integration/ # Integration modules
│ ├── dgm/ # Darwin Godel Machine
│ ├── openevolve/ # OpenEvolve framework
│ └── seal/ # SEAL interface
│
├── agents/ # Agent implementations
│ ├── __init__.py
│ ├── agentic_system.py
│ └── agentic_workflow_agent.py
│
├── providers/ # AI/ML model providers
│ ├── __init__.py
│ └── seal_providers.py
│
├── models/ # Data models and schemas
├── storage/ # Data persistence
└── utils/ # Utility functions
tests/ # Test suite
├── integration/ # Integration tests
├── unit/ # Unit tests
└── regression/ # Regression tests
For detailed installation and usage instructions, see the Documentation.
EVOSEAL provides a powerful command-line interface for managing all aspects of the system. The CLI is built using Typer and supports both interactive and non-interactive usage.
The CLI is installed automatically with the main package. You can access it using the evoseal command:
evoseal --help
Create a new EVOSEAL project with the standard directory structure:
evoseal init project my_project
Use --force to initialize in a non-empty directory:
evoseal init project my_project --force
View and modify configuration settings:
# List all configuration values evoseal config list # Get a specific configuration value evoseal config get seal.model # Set a configuration value evoseal config set seal.model gpt-4 # Unset a configuration value evoseal config unset seal.model
Manage SEAL, OpenEvolve, and DGM components:
# SEAL model operations evoseal seal --help # OpenEvolve processes evoseal openevolve --help # DGM workflows evoseal dgm --help
Start, stop, and monitor EVOSEAL processes:
# Start the API server evoseal start api # Start a worker process evoseal start worker # Stop all processes evoseal stop all # Check system status evoseal status
Export evolution results and code variants:
# Export results to a file evoseal export results results.json # Export a specific variant evoseal export variant variant_id output/
Here's a complete example workflow:
# Initialize a new project evoseal init project my_project cd my_project # Configure the project evoseal config set seal.model gpt-4 evoseal config set evolve.population_size 50 # Start the evolution process evoseal evolve start # Monitor progress evoseal status # Export results evoseal export results results.json
By default, EVOSEAL looks for configuration in .evoseal/config.yaml. You can specify a custom config file:
evoseal --config path/to/config.yaml [COMMAND]
For scripting and automation, use the --no-input flag to disable interactive prompts:
echo "y" | evoseal config set seal.model gpt-4 --no-input
Enable debug output with the --debug flag:
evoseal --debug [COMMAND]
For more detailed information, run evoseal --help or evoseal [COMMAND] --help for specific command documentation.
For detailed documentation, please visit https://sha888.github.io/EVOSEAL/.
Core: Contains the main evolutionary algorithms and orchestration logic
Integration: Modules for integrating with external systems (DGM, OpenEvolve, SEAL)
Agents: Implements different agent behaviors and workflows
Providers: Interfaces to various AI/ML model providers
Models: Data structures and schemas used throughout the system
Storage: Persistence layer for programs and metadata
Utils: Shared utility functions and helpers
We welcome contributions from the community! Please read our Contributing Guidelines to get started.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)Distributed under the MIT License. See LICENSE for more information.
Project Link: https://github.com/SHA888/EVOSEAL
EVOSEAL uses a structured requirements system to manage dependencies across different environments:
requirements.txt - Points to base requirements (references requirements/base.txt)requirements/base.txt - Core dependencies required for running EVOSEALrequirements/dev.txt - Development dependencies (includes base requirements)requirements/requirements.txt - Pinned production dependencies (generated by pip freeze)Create and activate a virtual environment:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
Install base requirements (recommended for most users):
pip install -r requirements.txt
For development, install development dependencies:
pip install -r requirements/dev.txt
For production, use pinned versions:
pip install -r requirements/requirements.txt
EVOSEAL uses a flexible configuration system that supports multiple environments (development, testing, production). For detailed configuration instructions, see CONFIGURATION.md.
EVOSEAL operates in an iterative loop, alternating between solving the provided task and enhancing its own capabilities. The process is illustrated in the following flowchart:
flowchart TD A[Start] --> B[User provides task and max_iterations] B --> C[Initialize EVOSEAL agent] C --> D[Set iteration=0] D --> E{iteration < max_iterations?} E -->|Yes| F[Evolve task solution] F --> G[Output best solution] G --> H[Improve self] H --> I[iteration = iteration + 1] I --> E E -->|No| J[End]
The EVOSEAL system integrates three sophisticated components with well-defined interfaces:
DGM is implemented through a collection of Python modules that work together to evolve code:
DGM_outer.py: Orchestrates the evolution process across generations, implementing functions for:
initialize_run()choose_selfimproves()update_archive()filter_compiled()coding_agent.py: Implements the AgenticSystem class that:
llm_withtools.py: Provides sophisticated SEAL integration:
OpenEvolve provides a robust framework for program evolution with several key components:
controller.py: The central orchestration module containing the OpenEvolve class that:
evaluator.py: Handles program evaluation through:
database.py: Sophisticated program version management system for:
SEAL provides the theoretical foundation and implementation for self-adapting language models:
few-shot/: Contains implementations for adapting models to new tasks with minimal examples:
knowledge-incorporation/: Focuses on techniques for adding factual knowledge to SEALs:
In this phase, EVOSEAL leverages SEAL to generate and refine code variants. These variants are then evaluated and the best one is selected using OpenEvolve's evolutionary mechanisms.
graph LR A[Start] --> B[Generate code variants with SEAL] B --> C[Evaluate variants with OpenEvolve] C --> D[Select best variant] D --> E[End]
The evolution process involves:
During this phase, DGM is utilized to generate and validate variants of the agent's own pipeline. The best variant is selected and used to update the agent's architecture, enabling continuous self-improvement.
graph LR A[Start] --> B[Generate pipeline variants with DGM] B --> C[Validate variants] C --> D[Select best variant] D --> E[Update agent's pipeline] E --> F[End]
The self-improvement process includes:
The three core technologies of EVOSEAL are tightly integrated through well-defined interfaces and data flows:
Clone the repository:
git clone https://github.com/yourusername/EVOSEAL.git cd EVOSEAL
Install core dependencies:
pip install -r requirements.txt
Install component-specific dependencies:
pip install -r SEAL/requirements.txt pip install -r openevolve/requirements.txt
Configure API keys:
Create a .env file in the project root with the following content:
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
EVOSEAL can be configured through YAML files that control each component's behavior:
configs/evoseal.yaml: Main configuration fileconfigs/dgm.yaml: DGM-specific settingsconfigs/openevolve.yaml: OpenEvolve parametersconfigs/seal.yaml: SEAL model configurationEVOSEAL provides a SystemConfig model for loading and validating configuration from YAML files. This model supports:
SystemConfig.from_yaml('path/to/config.yaml')config.get('dgm.max_iterations')dgm, openevolve, seal, integration)Example usage:
from evoseal.models.system_config import SystemConfig config = SystemConfig.from_yaml('configs/evoseal.yaml') config.validate() # Raises if required sections are missing max_iters = config.get('dgm.max_iterations', 100)
See CONFIGURATION.md for details on the required YAML structure.
# Run EVOSEAL on a programming task python run_evoseal.py --task ./tasks/example_task.json --iterations 10 --output ./results
# Run DGM for code improvement python -m dgm.DGM_outer --problem_statement "Fix the bug in function X" \ --git_dir ./repo --base_commit abc123 \ --selfimprove_size 5 --max_generation 3
# Run OpenEvolve on a program python -m openevolve.openevolve-run ./program.py ./evaluation.py \ --iterations 50 --output ./output
# Run SEAL few-shot learning experiment cd SEAL/few-shot python run_experiment.py --config configs/default.yaml
When EVOSEAL completes a run, it produces several output artifacts:
results/best_solution.py: The best solution found for the given taskresults/evolution_metrics.json: Performance metrics across generationsresults/architecture_improvements/: Record of self-improvements made to the systemresults/checkpoints/: Saved states that can be used to resume interrupted runsEVOSEAL's sophisticated architecture presents several important design considerations and challenges that are actively being addressed in the implementation:
Version Compatibility: Component versions are tracked using semantic versioning, with a compatibility matrix stored in configs/compatibility.yaml. During self-modification, the system verifies that changes maintain compatibility across component boundaries.
Interface Stability: Core APIs between components are treated as stable contracts with strict versioning. When DGM modifies integration code, regression tests verify that all interfaces remain compatible.
Modular Architecture: Each component is encapsulated with well-defined boundaries, allowing individual evolution without cascading changes across the system.
Multi-Metric Balancing: The system uses a weighted scoring approach defined in configs/evaluation_weights.yaml to balance correctness (highest weight), efficiency, and readability. Users can adjust these weights to suit specific needs.
Anti-Gaming Protections: Evaluation includes:
Regression Testing: Comprehensive test suites verify that new solutions and self-modifications maintain or improve functionality without introducing regressions.
Immutable Core: Certain components are designated as "immutable" in configs/safety.yaml, preventing self-modification of critical safety systems.
Safety Boundaries: Explicit constraints in configs/constraints.yaml define the permissible action space for self-improvements, preventing drift from original objectives.
Versioned Rollbacks: Every architecture change is tracked with Git, allowing immediate rollback to previous stable versions if instability is detected.
Performance Profiling: Detailed profiling in metrics/performance_log.json tracks the computational overhead of self-improvement relative to task solving (currently averaging 30% of total computation).
Resource Allocation: Configurable resource limits in configs/resources.yaml control API request rates, model selection based on task complexity, and parallel processing options.
Caching Mechanisms: Extensive caching of intermediate results reduces redundant computation and API calls, with cache invalidation strategies based on change magnitude.
Diminishing Returns Detection: The system tracks improvement magnitudes and automatically adjusts self-improvement frequency when returns diminish below a configurable threshold.
Time Horizon Evaluation: Long-term impact of architectural changes is assessed through simulation over multiple future tasks before permanent adoption.
Stability Metrics: Convergence stability is measured using statistical methods that identify oscillations and potential divergence patterns.
Task Complexity Scaling: Performance across a spectrum of task complexities is tracked in metrics/complexity_scaling.json, with adjustable strategies for handling increasingly complex tasks.
Domain Adaptation: The system includes transfer learning mechanisms that adapt to new domains by leveraging knowledge from previously solved tasks in related domains.
Architectural Flexibility: Self-improvements can introduce fundamentally new approaches when existing methods prove insufficient, guided by a library of architectural patterns.
API Design: RESTful interfaces between components with standardized JSON schemas allow independent evolution while maintaining compatibility.
Database Architecture: OpenEvolve's database includes indexing optimizations and pruning strategies to maintain performance with large numbers of program variants.
Monitoring and Telemetry: Comprehensive logging and visualization tools provide insights into system behavior across generations.
Baseline Comparisons: Ongoing benchmarking against static approaches shows a 15-45% improvement over non-evolutionary methods across standard programming tasks, with results published in benchmarks/comparison_results.md.
Failure Recovery: Two-phase recovery system: 1) immediate rollback to last stable version and 2) diagnosis mode that identifies and resolves architectural conflicts.
Human Oversight: Current implementation requires periodic human review at configurable checkpoints, with plans to reduce supervision as stability confidence increases.
Resource Management: Adaptive resource allocation balances computation between task solving and self-improvement based on task urgency, available resources, and expected improvement magnitude.
These considerations reflect our commitment to building a reliable, safe, and effective self-improving system that balances innovation with practical constraints.
If you use EVOSEAL in your research or projects, please cite:
@software{evoseal2025, title = {EVOSEAL: Evolutionary Self-Improving AI Agent}, author = {Sucandra, Kresna}, year = {2025}, month = {6}, publisher = {GitHub}, url = {https://github.com/SHA888/EVOSEAL} }
When using specific components of EVOSEAL, please also cite the respective original works:
@article{zhang2025darwin, title={Darwin Godel Machine: Open-Ended Evolution of Self-Improving Agents}, author={Zhang, Jenny and Hu, Shengran and Lu, Cong and Lange, Robert and Clune, Jeff}, journal={arXiv preprint arXiv:2505.22954}, year={2025} } @software{openevolve, title = {OpenEvolve: Open-source implementation of AlphaEvolve}, author = {Asankhaya Sharma}, year = {2025}, publisher = {GitHub}, url = {https://github.com/codelion/openevolve} } @misc{zweiger2025selfadaptinglanguagemodels, title={Self-Adapting Language Models}, author={Adam Zweiger and Jyothish Pari and Han Guo and Ekin Akyürek and Yoon Kim and Pulkit Agrawal}, year={2025}, eprint={2506.10943}, archivePrefix={arXiv}, primaryClass={cs.LG}, url={https://arxiv.org/abs/2506.10943} }
EVOSEAL is provided under the Apache License, Version 2.0.
This project incorporates components from multiple sources with different licenses:
See the LICENSE file for the complete text of the Apache License 2.0 and the NOTICE file for detailed attribution information.