OpenAlpha_Evolve：贡献以改进此项目

OpenAlpha_Evolve 是一个开源 Python 框架，灵感来源于 DeepMind 的 AlphaEvolve 等自主编码智能体（autonomous coding agents）的前沿研究。它是对核心思想的再生：一个智能系统，通过 LiteLLM 利用大语言模型（Large Language Models，简称 LLMs），在进化原则的指导下，迭代地编写、测试和改进代码。

我们的使命是为研究人员、开发者和爱好者提供一个易于访问、理解且可扩展的平台，以探索人工智能、代码生成和自动化问题解决之间迷人的交叉领域。

目录

• ✨ 愿景：AI 驱动的算法创新
• 🧠 工作原理：进化循环
• 🚀 关键特性
• 📂 项目结构
• 🏁 入门指南
• 💡 定义您自己的算法任务！
• 🔮 展望：未来进化
• 🤝 加入进化：贡献
• 📜 许可证
• 🙏 致敬

---

✨ 愿景：AI 驱动的算法创新

想象一个能够：

• 理解复杂的问题描述。
• 生成初始算法解决方案。
• 严格测试其自身代码。
• 从失败和成功中学习。
• 随时间进化出越来越复杂和高效的算法。

OpenAlpha_Evolve 是迈向这一愿景的一步。这不仅仅是关于生成代码；而是关于创建一个能够自主发现和优化解决方案的系统。

---

🧠 工作原理：进化循环

OpenAlpha_Evolve 采用模块化、基于智能体（agent-based）的架构来编排进化过程：

1. 任务定义（Task Definition）：您，即用户，定义算法“任务”——要解决的问题，包括输入和预期输出的示例。
2. 提示词工程（Prompt Engineering）（PromptDesignerAgent）：此智能体为 LLM 制作智能提示词。它设计：
   • 初始提示词（Initial Prompts）：用于生成第一组候选解决方案。
   • 变异提示词（Mutation Prompts）：用于引入现有解决方案的变体和改进，通常要求以“差异（diff）”格式提出更改。
   • 错误修复提示词（Bug-Fix Prompts）：引导 LLM 纠正先前尝试中的错误，通常也期望返回“差异”。
3. 代码生成（Code Generation）（CodeGeneratorAgent）：由 LLM 驱动（当前配置为 Gemini），此智能体接收提示词并生成 Python 代码。如果请求并收到“差异”，它会尝试将更改应用到父代码中。
4. 评估（Evaluation）（EvaluatorAgent）：生成的代码接受测试！
   • 语法检查（Syntax Check）：代码是否为有效的 Python？
   • 执行（Execution）：代码在临时隔离环境中运行，针对任务中定义的输入/输出示例进行测试。
   • 适应度评分（Fitness Scoring）：程序根据正确性（通过多少测试用例）、效率（运行时间）和其他潜在指标进行评分。
5. 数据库（Database）（DatabaseAgent）：所有程序（代码、适应度评分、生成记录、谱系）都被存储，创建进化历史记录（目前为内存中）。
6. 选择（Selection）（SelectionControllerAgent）：“适者生存”原则的体现。此智能体选择：
   • 父代（Parents）：来自当前世代有前途的程序，用于产生子代。
   • 幸存者（Survivors）：来自当前种群和新子代中最好的程序，以进入下一代。
7. 迭代（Iteration）：此循环重复定义的代数，每一代都旨在产生比上一代更好的解决方案。
8. 编排（Orchestration）（TaskManagerAgent）：操作的大师，协调所有其他智能体并管理整体进化循环。

---

🚀 关键特性

• LLM 驱动的代码生成：利用最先进的 LLMs，通过 LiteLLM，支持多个提供商（OpenAI, Anthropic, Google 等）。
• 进化算法核心：通过选择、LLM 驱动的变异/错误修复（使用 diff）和生存来实现迭代改进。
• 模块化智能体架构：轻松扩展或替换各个组件（例如，使用不同的 LLM、数据库或评估策略）。
• 自动化程序评估：语法检查和针对用户提供的示例的功能测试。代码执行使用 Docker 容器进行沙箱化，以提高安全性和依赖管理，并配备可配置的超时机制。
• 配置管理：通过 config/settings.py 和 .env 轻松调整参数，如种群大小、代数、LLM 模型、API 设置和 Docker 配置。
• 详细日志：全面的日志提供对进化过程每一步的洞察。
• 基于差异的变异：系统设计为使用差异进行变异和错误修复，允许 LLM 进行更有针对性的代码修改。
• 开源与可扩展：使用 Python 构建，专为实验和社区贡献而设计。

---

📂 项目结构

./
├── code_generator/      # Agent responsible for generating code using LLMs.
├── database_agent/      # Agent for managing the storage and retrieval of programs and their metadata.
├── evaluator_agent/     # Agent that evaluates the generated code for syntax, execution, and fitness.
├── prompt_designer/     # Agent that crafts prompts for the LLM for initial generation, mutation, and bug fixing.
├── selection_controller/  # Agent that implements the selection strategy for parent and survivor programs.
├── task_manager/        # Agent that orchestrates the overall evolutionary loop and coordinates other agents.
├── config/                  # Holds configuration files, primarily `settings.py` for system parameters and API keys.
├── core/                    # Defines core data structures and interfaces, like `Program` and `TaskDefinition`.
├── tests/                   # Includes unit and integration tests to ensure code quality and correctness.
├── main.py                  # The main entry point to run the OpenAlpha_Evolve system and start an evolutionary run.
├── requirements.txt         # Lists all Python package dependencies required to run the project.
├── .env.example             # An example file showing the environment variables needed, such as API keys. Copy this to `.env` and fill in your values.
├── .gitignore               # Specifies intentionally untracked files that Git should ignore (e.g., `.env`, `__pycache__/`).
├── LICENSE.md               # Contains the full text of the MIT License under which the project is distributed.
└── README.md                # This file! Provides an overview of the project, setup instructions, and documentation.

---

🏁 入门指南

1. 前置条件：

   • Python 3.10+
   • pip (包管理工具)
   • git (版本控制工具)
   • Docker：用于沙箱代码评估。请确保已安装并运行 Docker Desktop（Windows/Mac）或 Docker Engine（Linux）。访问 docker.com 获取安装说明。

2. 克隆仓库：

   git clone https://github.com/shyamsaktawat/OpenAlpha_Evolve.git
   cd OpenAlpha_Evolve
   

3. 设置虚拟环境（推荐）：

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

4. 安装依赖项：

   pip install -r requirements.txt
   

5. 设置环境变量（对 API 密钥至关重要）：

   • 此步骤对于应用程序正确使用您的 API 密钥至关重要。.env 文件存储您的敏感凭据和配置，覆盖 config/settings.py 中的默认占位符。
   • 通过复制示例创建您的个人环境文件：

     cp .env_example .env
     

   LLM 配置

   Google Cloud 认证（例如，通过应用程序默认凭证 (ADC) 或由 GOOGLE_APPLICATION_CREDENTIALS 指向的服务账号密钥）是使用 Google 大语言模型 (LLM) 的一种支持方法。

   要为 Google Cloud 设置环境变量，您可以使用以下任一方法。这些应添加到您的 .env 文件中：

   # For Google Cloud (Vertex AI / AI Studio)
   # Option 1: Using Application Default Credentials (ADC)
   # Ensure you have authenticated via gcloud CLI:
   # gcloud auth application-default login
   # Or set the GOOGLE_APPLICATION_CREDENTIALS environment variable:
   # GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
   
   # Option 2: Directly using an API Key for specific Google services (e.g., Gemini API)
   # GEMINI_API_KEY="your_gemini_api_key"
   

   本项目使用 LiteLLM 来接口连接各种 LLM 提供商。对于 Google Cloud 以外的提供商（例如 OpenAI, Anthropic, Cohere），请参阅 LiteLLM 文档 以了解所需的具体环境变量。常见示例包括：

   # OPENAI_API_KEY="your_openai_api_key"
   # ANTHROPIC_API_KEY="your_anthropic_api_key"
   # COHERE_API_KEY="your_cohere_api_key"
   

   将您选择的 LLM 提供商所需的必要 API 密钥变量添加到您的 .env 文件中。

6. 运行 OpenAlpha_Evolve！ 使用以下命令运行示例任务（Dijkstra 算法）：

   python -m main examples/shortest_path.yaml
   

   在终端中查看日志以观察进化过程的展开！日志文件也默认保存到 alpha_evolve.log。

7. 启动 Gradio Web 界面 通过 Web 用户界面 (Web UI) 与系统交互。要启动 Gradio 应用：

   python app.py
   

   Gradio 将显示一个本地 URL（例如 http://127.0.0.1:7860）以及如果启用了公共分享链接。在浏览器中打开它以定义自定义任务并交互式地运行进化过程。

---

💡 定义您自己的算法挑战！

想用新问题挑战 OpenAlpha_Evolve 吗？这很简单！您可以通过两种方式定义您的任务：

1. 使用 YAML 文件（推荐）

在 examples 目录中创建一个具有以下结构的 YAML 文件：

task_id: "your_task_id"
task_description: |
  Your detailed problem description here.
  Be specific about function names, expected behavior, and constraints.
function_name: "your_function_name"
allowed_imports: ["module1", "module2"]

tests:
  - description: "Test group description" # Describes a group of related tests
    name: "Test group name" # A name for this test group
    test_cases: # This should be a list of individual test cases
      - input: [arg1, arg2]  # First test case
        output: expected_output # Expected result for this input
        # Each test case uses either 'output' for direct comparison
        # or 'validation_func' for more complex validation.
      - input: [arg_for_validation_func_1, arg_for_validation_func_2] # Second test case
        validation_func: |
          def validate(output_from_function):
              # Custom validation logic for this specific test case's output
              # For example, check if output is within a certain range,
              # or if it has specific properties.
              return isinstance(output_from_function, bool) and output_from_function is True

参见 examples/shortest_path.yaml 中的示例

2. 使用 Python 代码（旧版）

您仍然可以使用 TaskDefinition 类以编程方式定义任务：

from core.task_definition import TaskDefinition

task = TaskDefinition(
    id="your_task_id",
    description="Your detailed problem description",
    function_name_to_evolve="your_function_name",
    input_output_examples=[
        {"input": [arg1, arg2], "output": expected_output},
        # More examples...
    ],
    allowed_imports=["module1", "module2"]
)

任务定义的最佳实践

制定有效的任务定义是成功引导 OpenAlpha_Evolve 的关键。请考虑以下建议：

• 清晰且无歧义：撰写任务描述时，仿佛向另一位开发者解释问题一样。尽量避免行话，或者清晰地解释它们。
• 提供多样且全面的示例：测试用例是智能体 (Agent) 验证其生成代码的主要方式。
  • 包含典型用例
  • 覆盖边界情况（空输入、边界值等）
  • 包含测试不同逻辑路径的示例
  • 对于复杂检查使用验证函数
• 从简单开始，然后增加复杂度：首先将复杂问题分解为更简单的版本。
• 指定约束和边界情况：在描述中提及具体的约束和边界情况。
• 定义预期的函数签名 (Function Signature)：清楚地说明预期的函数名称和参数。
• 迭代与优化：根据智能体 (Agent) 的表现审查并优化你的任务定义。

---

🔮 展望：未来演进

---

🤝 加入演进：贡献指南

这是一个开放的协作邀请！无论你是 AI 研究人员、Python 开发者，还是仅仅是一个爱好者，都欢迎你的贡献。

• 报告 Bug (缺陷)：发现问题了吗？请在 GitHub 上创建一个 Issue (问题)！
• 建议功能：有让 OpenAlpha_Evolve 变得更好的想法吗？打开一个 Issue (问题) 来讨论它！
• 提交拉取请求 (Pull Requests)：
  • Fork (分叉) 仓库。
  • 为你的功能或修复创建新分支（git checkout -b feature/your-feature-name）。
  • 编写清晰、文档完善的代码。
  • 如果适用，为你的更改添加测试。
  • 确保你的更改不会破坏现有功能。
  • 提交一个带有清晰更改描述的拉取请求 (Pull Request)！

让我们一起进化这个智能体 (Agent)！

---

📜 许可证

本项目采用 MIT 许可证 授权。详细信息请参阅 LICENSE.md 文件。

---

🙏 致谢

OpenAlpha_Evolve 自豪地受到 Google DeepMind 团队在 AlphaEvolve 以及其他基于大语言模型 (LLM) 的代码生成和自动发现相关研究的开创性工作的启发。本项目旨在使核心概念更容易被广泛实验和学习。我们站在巨人的肩膀上。

---

免责声明：这是一个实验性项目。生成的代码可能并不总是最优、正确或安全的。请务必彻底审查和测试代码，特别是在将其用于生产环境之前。

OpenAlpha_Evolve 快速上手指南

OpenAlpha_Evolve 是一个基于大语言模型（LLM）的开源 Python 框架，灵感源自 DeepMind 的 AlphaEvolve 研究。它通过进化算法自动编写、测试并改进代码，旨在探索 AI 在代码生成与自动化问题解决领域的潜力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows / macOS / Linux
• Python：版本 3.10 或更高
• 工具链：git (用于克隆仓库), pip (包管理)
• Docker：必需。用于隔离运行生成的代码以确保安全及依赖管理。请确保 Docker Desktop (Windows/Mac) 或 Docker Engine (Linux) 已安装并正在运行。

💡 提示：国内开发者建议在 pip install 时配置国内镜像源以提升下载速度。

安装步骤

1. 克隆项目

   git clone https://github.com/shyamsaktawat/OpenAlpha_Evolve.git
   cd OpenAlpha_Evolve
   

2. 创建虚拟环境 (推荐)

   python -m venv venv
   source venv/bin/activate  # Windows 用户请使用：venv\Scripts\activate
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 配置环境变量 项目需要 API Key 才能调用 LLM。

   cp .env_example .env
   

   编辑 .env 文件，填入您选择的 LLM 提供商密钥（如 Google Gemini, OpenAI 等）。例如：

   GEMINI_API_KEY="your_gemini_api_key"
   # 或其他支持 LiteLLM 的提供商密钥
   

基本使用

运行示例任务

项目内置了一个最短路径算法（Dijkstra）的示例任务，可直接运行观察进化过程：

python -m main examples/shortest_path.yaml

运行后，终端将显示日志，同时默认日志会保存至 alpha_evolve.log。

启动 Web 界面

您可以通过 Gradio 网页界面交互式地定义任务并监控进化过程：

python app.py

浏览器打开显示的本地链接（如 http://127.0.0.1:7860）即可开始操作。

自定义算法挑战

您可以修改 examples 目录下的 YAML 文件来定义自己的问题。主要结构包括：

• task_description: 详细的问题描述。
• function_name: 目标函数名。
• tests: 包含输入 (input) 和预期输出 (output) 或验证函数 (validation_func) 的测试用例列表。