EVOSEAL: Evolutionary Self-Improving AI Agent

Latest Version: 0.3.2 (July 27, 2025)

Research status: EVOSEAL is an active research project exploring autonomous, scheduled self-modification. It is not yet production-validated, and benchmark results are not yet published (see TODO.md for the current roadmap and known gaps). Capabilities below describe the implemented Phase 3 system; treat maturity claims as research-stage rather than battle-tested.

🎉 Phase 3 - Bidirectional Continuous Evolution:

✅ Bidirectional co-evolution loop between EVOSEAL and its local coding models
✅ Real-time monitoring dashboard with WebSocket updates
✅ systemd service integration
✅ Model validation, versioning, and rollback capabilities
✅ Ollama integration with local coder/reviewer models (auto-discovered)
✅ Continuous improvement loop with automated cycles

Two co-evolution paths, pick by hardware:

Prompt-level co-evolution (CPU-friendly, default): a coder model writes code, a reviewer model critiques it, and the reviewer's feedback evolves the coder's system prompt — regression-gated, with rollback. Runs on CPU with two local Ollama models; no GPU required. See docs/architecture/local_coevolution.md.

Weight-level fine-tuning (GPU-only): the original LoRA/QLoRA path that fine-tunes a coding model from evolution data. This needs a CUDA GPU and is not runnable on a CPU-only host. Historically this targeted Mistral AI's Devstral; the code lives under evoseal/fine_tuning/.

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.

Features

🚀 Phase 3: Bidirectional Continuous Evolution

🧬 Bidirectional Evolution: EVOSEAL ↔ local models mutual improvement loop
🤖 Coder + Reviewer roles: DeepSeek-Coder writes, Qwen2.5-Coder reviews (auto-discovered from Ollama)
✍️ Prompt-level self-improvement: reviewer feedback evolves the coder's system prompt (CPU-friendly, no GPU)
🌐 Real-time Dashboard: Live monitoring at http://localhost:9613
🔄 Continuous Operation: Automated evolution cycles
🎯 Fine-tuning Infrastructure (GPU-only): LoRA/QLoRA with comprehensive validation
📊 Prompt & Model Versioning: Automatic version tracking and rollback
🛡️ Safety Controls: Model validation with alignment testing
🔧 systemd Integration: systemd service management with hardened security settings

🛠️ Script Organization & CLI

🗂 Modular Scripts: Organized into functional directories under scripts/lib/
📜 Unified CLI: Single entry point through scripts/evoseal
🚀 Service Management: Easy deployment with systemd service and timers
📊 Logging: Centralized logging with rotation and verbosity controls

🏗️ Core Architecture

🧬 Evolutionary algorithm for code improvement
🤖 Integration with multiple AI models (OpenAI, Anthropic, Ollama)
📊 Performance tracking and metrics
🔄 Continuous self-improvement
📝 Comprehensive documentation
🧪 Test coverage and CI/CD ready
🔒 Secure and privacy-focused
🏢 Modular architecture with clear separation of concerns
🛡️ Rollback safety protection - Prevents accidental codebase deletion

Getting Started

Prerequisites

Python 3.10+
Git
systemd (for service management)
[Optional] CUDA-compatible GPU for accelerated training

Installation

Clone the repository:

git clone https://github.com/SHA888/EVOSEAL.git
cd EVOSEAL

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
pip install -e .
```

CLI Usage

The main entry point for EVOSEAL is the scripts/evoseal script. Make it executable and run it with the --help flag to see available commands:

# Make the script executable
chmod +x scripts/evoseal

# Show help
./scripts/evoseal --help

# Run tests
./scripts/evoseal test

# Start evolution cycle
./scripts/evoseal evolve

# Manage versions
./scripts/evoseal version --help

Service Management

To run EVOSEAL as a systemd service:

Install the service (run as your user):

./scripts/evoseal deploy install-service

Enable and start the service:

systemctl --user enable evoseal.service
systemctl --user start evoseal.service

View logs:
```
journalctl --user -u evoseal -f
```
Install the update timer (runs daily at 4 AM):
```
./scripts/evoseal deploy install-timer
```

Environment Variables

Key environment variables can be set in .env or passed to the service:

# Core settings
EVOSEAL_ROOT=/path/to/evoseal
EVOSEAL_VENV=/path/to/venv
EVOSEAL_LOGS=/path/to/logs

# Provider configuration
# Models are auto-discovered from what is installed in Ollama (matched by family).
# Override per role only if you want a specific tag:
OLLAMA_API_BASE=http://localhost:11434
EVOSEAL_CODER_MODEL=deepseek-coder-v2:16b-lite-instruct-q8_0
EVOSEAL_REVIEWER_MODEL=qwen2.5-coder:7b-instruct-q6_K

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

Project Structure

Main Directories

EVOSEAL/
├── scripts/                 # Scripts and utilities
│   ├── lib/                 # Library of modular scripts
│   │   ├── cli/             # Command-line interface tools
│   │   ├── deploy/          # Deployment and service management
│   │   ├── evolution/       # Evolution cycle management
│   │   ├── release/         # Release automation
│   │   ├── test/            # Test runners and utilities
│   │   ├── utils/           # Shared utilities and helpers
│   │   └── version/         # Version management
│   └── evoseal              # Main CLI entry point
│
├── 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
│
├── evolution/              # 📊 Phase 1: Evolution Data Collection
│   ├── data_collector.py   # Async evolution data collection
│   ├── pattern_analyzer.py # Pattern extraction from evolution results
│   ├── training_builder.py # Training data generation
│   └── models.py           # Evolution data models
│
├── prompt_evolution/       # ✍️ Phase 2 (CPU): prompt-level self-improvement
│   ├── coevolution_manager.py # generate→review→evolve→revalidate→accept/rollback
│   ├── prompt_evolver.py      # distill reviewer critique into a prompt edit (guardrailed)
│   ├── prompt_store.py        # versioned system prompts with rollback
│   └── models.py              # task/critique/prompt-version records
│
├── fine_tuning/            # 🎯 Phase 2 (GPU-only): weight fine-tuning
│   ├── model_fine_tuner.py     # ModelFineTuner: LoRA/QLoRA fine-tuning (model-agnostic)
│   ├── training_manager.py     # Training pipeline coordination
│   ├── model_validator.py      # Comprehensive model validation
│   ├── version_manager.py      # Model version tracking & rollback
│   └── bidirectional_manager.py # EVOSEAL ↔ model weight-training orchestration
│
├── services/               # 🚀 Phase 3: Continuous Evolution
│   ├── continuous_evolution_service.py # Main continuous service
│   └── monitoring_dashboard.py         # Real-time web dashboard
│
├── providers/              # AI/ML model providers
│   ├── __init__.py
│   ├── local_models.py     # Ollama model discovery + per-role resolution
│   ├── ollama_provider.py  # Ollama integration (coder/reviewer)
│   ├── provider_manager.py # Provider selection & fallback
│   └── seal_providers.py   # Legacy provider interfaces
│
├── integration/            # Integration modules
│   ├── dgm/                # Darwin Godel Machine
│   ├── openevolve/         # OpenEvolve framework
│   └── seal/               # SEAL interface
│
├── agents/                 # Agent implementations
├── models/                 # Data models and schemas
├── storage/                # Data persistence
├── config.py               # Configuration management
└── utils/                  # Utility functions

scripts/                    # 🔧 Deployment & Management
├── run_phase3_continuous_evolution.py  # Phase 3 orchestrator
├── test_phase2_components.py           # Phase 2 testing
└── provider_cli.py                     # Provider management

tests/                      # Test suite
├── integration/            # Integration tests
├── unit/                   # Unit tests
└── regression/             # Regression tests

.config/systemd/user/       # 🔧 Production Service
└── evoseal.service         # systemd service configuration

🚀 Phase 3: Bidirectional Continuous Evolution

Architecture Overview

EVOSEAL Phase 3 implements a bidirectional evolution system where EVOSEAL and its local coding models continuously improve each other. There are two co-evolution paths; the CPU-friendly prompt-level path is the default (see docs/architecture/local_coevolution.md), and the GPU-only weight fine-tuning path below is optional:

Phase 1: Evolution Data Collection
- Async collection of evolution results from EVOSEAL's self-improvement cycles
- Pattern analysis to extract successful improvement strategies
- Training data generation in multiple formats (Alpaca, Chat, JSONL)
Phase 2: Self-improvement Infrastructure
- Prompt-level (CPU): reviewer feedback evolves the coder's system prompt, regression-gated with rollback (evoseal/prompt_evolution/) — no GPU needed.
- Weight-level (GPU-only): LoRA/QLoRA fine-tuning from evolution patterns (evoseal/fine_tuning/) — requires a CUDA GPU; not runnable on a CPU-only host.
- Comprehensive model validation with 5-category testing
- Version management with automatic rollback capabilities
Phase 3: Continuous Improvement Loop
- Automated evolution cycles and orchestration
- Real-time monitoring dashboard with WebSocket updates
- systemd service integration for long-running operation
- Bidirectional feedback loop: EVOSEAL ↔ local coder/reviewer models

🌐 Real-time Monitoring Dashboard

Access the live monitoring dashboard at http://localhost:9613:

Service Status: Real-time system health, uptime, and operational state
Evolution Metrics: Cycle counts, training progress, model improvements
Training Status: Data readiness, sample counts, model versions
Performance Analytics: Success rates, cycles per hour, efficiency metrics
Live Activity Log: Real-time system events and notifications
WebSocket Updates: Live data streaming without page refresh

🔧 systemd Integration

EVOSEAL Phase 3 runs as a production systemd service:

# Service management
systemctl --user status evoseal.service    # Check status
systemctl --user restart evoseal.service   # Restart service
systemctl --user stop evoseal.service      # Stop service
systemctl --user start evoseal.service     # Start service

# Real-time logs
journalctl --user -fu evoseal.service       # Follow logs

# Service configuration
~/.config/systemd/user/evoseal.service      # Service file

🎯 Model Integration

Ollama local models (auto-discovered): EVOSEAL queries Ollama for installed models and matches one per role by family — so a re-quantized or renamed tag keeps working. Defaults on a typical CPU box:

Coder (writes code): DeepSeek-Coder-V2-Lite — deepseek-coder-v2:16b-lite-instruct-q8_0
Reviewer (critiques code): Qwen2.5-Coder — qwen2.5-coder:7b-instruct-q6_K
Override per role with EVOSEAL_CODER_MODEL / EVOSEAL_REVIEWER_MODEL.
Requirements: runs CPU-only (no GPU). Pull the models with ollama pull <tag>.

Optional GPU fine-tuning (weight-level path) historically used Mistral AI's Devstral and requires a CUDA GPU (e.g. a single RTX 4090 or a 32GB Mac); it is not exercised on CPU-only hosts.

📊 Continuous Operation

Evolution Cycles: Every 1 hour (configurable)
Training Checks: Every 30 minutes (configurable)
Automatic Fine-tuning: Triggered when sufficient evolution data collected
Model Validation: Comprehensive safety and quality checks
Version Management: Automatic rollback on validation failure
Health Monitoring: Continuous system health checks

For detailed installation and usage instructions, see the Documentation.

Command Line Interface (CLI)

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.

Installation

The CLI is installed automatically with the main package. You can access it using the evoseal command:

evoseal --help

Basic Commands

Initialize a New Project

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

Configuration Management

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

Component Management

Manage SEAL, OpenEvolve, and DGM components:

# SEAL model operations
evoseal seal --help

# OpenEvolve processes
evoseal openevolve --help

# DGM workflows
evoseal dgm --help

Pipeline Control

Control and monitor the evolution pipeline with comprehensive commands:

# Initialize a pipeline for a repository
evoseal pipeline init https://github.com/user/repo.git

# Start the evolution pipeline
evoseal pipeline start

# Monitor pipeline status
evoseal pipeline status

# Pause/resume pipeline execution
evoseal pipeline pause
evoseal pipeline resume

# Stop the pipeline
evoseal pipeline stop

# View pipeline configuration
evoseal pipeline config --show

# Set configuration parameters
evoseal pipeline config --set "logging.level=DEBUG"

# View pipeline logs
evoseal pipeline logs --lines 100

# Debug pipeline state
evoseal pipeline debug --inspect

Process Control

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

Cost Estimation

Estimate token consumption and costs for evolution runs:

# Estimate costs for 100 iterations with default settings
evoseal estimate-cost --iterations 100

# Estimate with custom DGM token rate
evoseal estimate-cost --iterations 50 --dgm-tokens-per-call 5000

# Estimate with custom cost per 1k tokens (e.g., Anthropic Claude)
evoseal estimate-cost --iterations 200 --cost-per-1k-tokens 0.003

Cost Expectations Table (default settings, per iteration):

Model Provider	Cost per 1k tokens	Tokens/Iteration*	Cost/Iteration
OpenAI GPT-4	$0.015	~4,100	~$0.062
Anthropic Claude	$0.008	~4,100	~$0.033
Ollama/Local	$0.000	~4,100	$0.000

*Tokens per iteration = DGM tokens (4,000) + SEAL tokens (100)

Example Budget Calculations:

100 iterations with GPT-4: ~6,200 tokens, ~$0.062
1,000 iterations with Claude: ~41,000 tokens, ~$0.328
10,000 iterations with Ollama: 0 cost (local model)

For detailed cost tracking and budget enforcement, see the cost and budget specification.

Exporting Results

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/

Example Workflow

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

Continuous Operation

EVOSEAL can run continuously as a background service, ideal for long-term evolution and self-improvement tasks:

# Run continuously in foreground (for monitoring)
./scripts/run_continuous.sh

# Install and run as a system service
./scripts/install_service.sh
sudo systemctl start evoseal.service

For detailed instructions on continuous operation, see Continuous Operation Guide.

Advanced Usage

Custom Configuration Files

By default, EVOSEAL looks for configuration in .evoseal/config.yaml. You can specify a custom config file:

evoseal --config path/to/config.yaml [COMMAND]

Non-Interactive Mode

For scripting and automation, use the --no-input flag to disable interactive prompts:

echo "y" | evoseal config set seal.model gpt-4 --no-input

Debug Mode

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.

Documentation

For detailed documentation, please visit https://sha888.github.io/EVOSEAL/.

Key Components

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
User Guide
API Reference
Architecture Overview
Development Guide

Contributing

We welcome contributions from the community! Please read our Contributing Guidelines to get started.

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Contact

Project Link: https://github.com/SHA888/EVOSEAL

Acknowledgements

Dependencies & Requirements

For basic setup, see Getting Started → Installation above. All dependencies are declared in pyproject.toml.

Setting Up the Environment

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install (recommended for most users):
```
pip install -e .
```
For development (includes linting, type-checking, test tooling):
```
pip install -e ".[dev,test]"
```

For production with pinned versions:

pip install -r requirements/pinned_requirements.txt

Virtual Environment Recommendation

Important: EVOSEAL uses .venv as the standard virtual environment directory name. This is:

✅ Recommended: .venv (hidden directory, widely adopted convention)
❌ Avoid: venv (visible directory, less conventional)

The .gitignore file is configured to ignore both, but please use .venv for consistency with the project documentation.

Configuration

EVOSEAL uses a flexible configuration system that supports multiple environments (development, testing, production). For detailed configuration instructions, see CONFIGURATION.md.

Technical Architecture

High-Level Architecture

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]

System Implementation

The EVOSEAL system integrates three sophisticated components with well-defined interfaces:

DGM Implementation Details

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:
- Initializing evolution runs with initialize_run()
- Selecting candidates for improvement through choose_selfimproves()
- Managing the archive of successful improvements via update_archive()
- Filtering out non-compiled or empty solutions using filter_compiled()
coding_agent.py: Implements the AgenticSystem class that:
- Interfaces with Git repositories for version control
- Manages code edits and improvement processes
- Runs regression tests to verify improvements
- Handles communication with SEAL models
llm_withtools.py: Provides sophisticated SEAL integration:
- Supports both Claude and OpenAI models
- Implements tool-calling capabilities for code manipulation
- Handles message history conversion between different SEAL formats
- Manages backoff and retry mechanisms for API stability

OpenEvolve Implementation Details

OpenEvolve provides a robust framework for program evolution with several key components:

controller.py: The central orchestration module containing the OpenEvolve class that:
- Manages the entire evolution process from initialization to completion
- Coordinates between the prompt sampler, SEAL ensemble, evaluator, and program database
- Implements checkpoint saving and loading mechanisms
- Tracks the best program across evolution steps
evaluator.py: Handles program evaluation through:
- Integration with external evaluation scripts
- Collection and normalization of performance metrics
- Support for SEAL-based evaluation when needed
database.py: Sophisticated program version management system for:
- Storing and retrieving program variants
- Tracking program lineage and relationships
- Implementing selection strategies (MAP-Elites process)
- Maintaining diversity in the solution space

SEAL Implementation Details

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:
- Training procedures for meta-learning capabilities
- Evaluation frameworks for measuring adaptation quality
- Example tasks and benchmarks
knowledge-incorporation/: Focuses on techniques for adding factual knowledge to SEALs:
- Methods for identifying and incorporating new information
- Verification mechanisms for knowledge consistency
- Evaluation metrics for knowledge retention

Core Processes

Evolve Task Solution

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:

Variant Generation: Using SEAL's self-adapting capabilities to generate diverse code solutions
Evaluation: Assessing each variant based on multiple metrics including correctness, efficiency, and readability
Selection: Applying OpenEvolve's MAP-Elites process to maintain both quality and diversity
Refinement: Iterative improvement of promising solutions

Improve Self

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:

Pipeline Variation: Using DGM to generate modifications to the agent's own codebase
Validation Testing: Rigorously testing each variant for correctness and performance improvements
Selection: Choosing the best variant based on comprehensive metrics
Integration: Incorporating the improvements into the main architecture
Version Control: Maintaining a history of improvements through Git-based version control

Component Integration

The three core technologies of EVOSEAL are tightly integrated through well-defined interfaces and data flows:

SEAL Integration

Code Generation Interface: SEAL's self-adapting capabilities are exposed through a structured API that allows OpenEvolve to request code variants
Knowledge Incorporation Pipeline: New knowledge is continuously fed into SEAL models during the evolution process
Few-shot Learning Activation: Task-specific examples are used to prime SEAL for generating contextually relevant code
Model Selection: Different SEAL model configurations are selected based on task complexity and domain

OpenEvolve Integration

Evolutionary Engine: Serves as the central orchestration system for the entire EVOSEAL framework
Database Interface: Provides a unified storage and retrieval system for program variants across all components
Evaluation System: Standardizes metrics collection and normalization for consistent comparison across variants
Checkpoint Management: Enables seamless persistence and recovery of evolutionary progress

DGM Integration

Meta-Evolution Layer: Applied at the highest level to evolve EVOSEAL's own components
Git-based Version Control: Provides a robust mechanism for tracking changes to the agent's architecture
Archive Management: Maintains a history of successful architecture variants with performance metrics
Selection Mechanism: Implements sophisticated strategies for choosing which parts of the architecture to improve

Technical Benefits

Self-Refinement

Self-Editing Capabilities: SEAL models can identify and correct their own errors, leading to progressively higher quality code
Knowledge Integration: New information is continuously incorporated into the system's knowledge base
Contextual Adaptation: Models automatically adjust their output style and approach based on task requirements
Error Reduction: Analysis of previous generation errors informs improvements in subsequent generations

Evolutionary Optimization

MAP-Elites Implementation: Maintains diversity while optimizing for multiple objectives simultaneously
Multi-metric Evaluation: Programs are evaluated across several dimensions including correctness, efficiency, and readability
Efficient Search: Intelligent exploration of the solution space through targeted mutations and crossovers
Elitism Preservation: The best solutions are always maintained across generations

Continuous Improvement

Iterative Architecture Refinement: DGM continuously improves the agent's core algorithms and workflows
Cross-pollination of Solutions: Successful strategies from one domain are applied to others
Automated Learning Rate Adjustment: Self-tuning of learning parameters based on progress metrics
Regression Prevention: Comprehensive testing prevents performance degradation

Implementation Roadmap

Current Development

Automated Pipeline Integration: Streamlining the connections between SEAL, OpenEvolve, and DGM components
Performance Benchmarking: Establishing baseline metrics across a variety of programming tasks
Documentation Expansion: Developing comprehensive API references and integration guides

Future Directions

Real-time Learning Mechanisms: Implement streaming learning capabilities to accelerate the self-improvement cycle
Extended Benchmark Support: Expand compatibility with standard programming benchmarks and diverse task domains
Enhanced Safety Protocols: Develop more sophisticated safeguards for managing self-modifying code risks
Distributed Evolution: Enable parallel evolution across multiple compute nodes for faster convergence
Human Feedback Integration: Create interfaces for incorporating human developer feedback into the evolution process

See CONFIGURATION.md for details on the required YAML structure.

Usage Examples

Basic Usage

# Run EVOSEAL on a programming task
python run_evoseal.py --task ./tasks/example_task.json --iterations 10 --output ./results

Running Individual Components

DGM Only

# 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

OpenEvolve Only

# Run OpenEvolve on a program
python -m openevolve.openevolve-run ./program.py ./evaluation.py \
                               --iterations 50 --output ./output

SEAL Experiments

# Run SEAL few-shot learning experiment
cd SEAL/few-shot
python run_experiment.py --config configs/default.yaml

Example Output

When EVOSEAL completes a run, it produces several output artifacts:

results/best_solution.py: The best solution found for the given task
results/evolution_metrics.json: Performance metrics across generations
results/architecture_improvements/: Record of self-improvements made to the system
results/checkpoints/: Saved states that can be used to resume interrupted runs

Design Considerations and Challenges

Research scope note: EVOSEAL is a research project exploring autonomous, scheduled self-modification — a direction that user-driven systems do not attempt. This section describes the target design and intended safeguards. Several configuration and metrics files referenced below (e.g., under configs/ and metrics/) describe planned mechanisms and may not yet exist in the repository. Treat this section as design intent, not a description of shipped, production-validated behavior.

EVOSEAL's architecture presents several important design considerations and challenges that are actively being worked on:

Complexity Management

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.

Evaluation Framework

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:
- Diverse test suites that cover multiple edge cases
- Randomized test generation to prevent overfitting
- Secondary validation using different evaluation methods
- Human review prompts at configurable checkpoints

Safety Mechanisms

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.

Computational Efficiency

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.

Convergence Behavior

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.

Scalability Considerations

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.

Implementation Insights

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.

Open Research Questions

Baseline Comparisons: Reproducible benchmarking against non-evolutionary baselines (e.g., single-shot generation) is planned but not yet published. Results will be recorded in benchmarks/comparison_results.md once available. No verified improvement figures are claimed at this time. See TODO.md (P0 — Benchmarks & Empirical Validation).
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.

Citation

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

License

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.

Name		Name	Last commit message	Last commit date
Latest commit History 480 Commits
.claude		.claude
.evoseal		.evoseal
.github		.github
SEAL @ 6d9c9f9		SEAL @ 6d9c9f9
assets		assets
benchmarks		benchmarks
config		config
dgm @ a565fd2		dgm @ a565fd2
docs		docs
evoseal		evoseal
examples		examples
metrics		metrics
openevolve @ 80945ed		openevolve @ 80945ed
releases		releases
reports/tests		reports/tests
scripts		scripts
systemd		systemd
templates		templates
tests		tests
.coveragerc		.coveragerc
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
.hadolint.yaml		.hadolint.yaml
.pre-commit-config.yaml		.pre-commit-config.yaml
.safety-policy.json		.safety-policy.json
.secrets.baseline		.secrets.baseline
AGENT.md		AGENT.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
EVOLUTION.md		EVOLUTION.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
Plans.md		Plans.md
README.md		README.md
SAFETY.md		SAFETY.md
TODO.md		TODO.md
docker-compose.evoseal.yml		docker-compose.evoseal.yml
docker-compose.yml		docker-compose.yml
harness.toml		harness.toml
mkdocs.yml		mkdocs.yml
mypy.ini		mypy.ini
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

EVOSEAL: Evolutionary Self-Improving AI Agent

Features

🚀 Phase 3: Bidirectional Continuous Evolution

🛠️ Script Organization & CLI

🏗️ Core Architecture

Getting Started

Prerequisites

Installation

CLI Usage

Service Management

Environment Variables

Project Structure

Main Directories

🚀 Phase 3: Bidirectional Continuous Evolution

Architecture Overview

🌐 Real-time Monitoring Dashboard

🔧 systemd Integration

🎯 Model Integration

📊 Continuous Operation

Command Line Interface (CLI)

Installation

Basic Commands

Initialize a New Project

Configuration Management

Component Management

Pipeline Control

Process Control

Cost Estimation

Exporting Results

Example Workflow

Continuous Operation

Advanced Usage

Custom Configuration Files

Non-Interactive Mode

Debug Mode

Documentation

Key Components

Contributing

Contact

Acknowledgements

Dependencies & Requirements

Setting Up the Environment

Virtual Environment Recommendation

Configuration

Technical Architecture

High-Level Architecture

System Implementation

DGM Implementation Details

OpenEvolve Implementation Details

SEAL Implementation Details

Core Processes

Evolve Task Solution

Improve Self

Component Integration

SEAL Integration

OpenEvolve Integration

DGM Integration

Technical Benefits

Self-Refinement

Evolutionary Optimization

Continuous Improvement

Implementation Roadmap

Current Development

Future Directions

Usage Examples

Basic Usage

Running Individual Components

DGM Only

OpenEvolve Only

SEAL Experiments

Example Output

Design Considerations and Challenges

Complexity Management

Evaluation Framework

Safety Mechanisms

Computational Efficiency

Packages