sr-harness 1.0.0__py3-none-any.whl

sr_harness/README.md

@@ -0,0 +1,102 @@
+# SRHarness 框架说明
+
+> SRHarness 的长篇使用文档和 API Reference：[`docs/index.md`](../../docs/index.md)
+
+## SRAgent 整体架构
+
+SRAgent 是一个基于 LLM 的符号回归 Agent。其核心是一个 **"请求 LLM → 解析工具调用 → 调用工具 → 格式化消息"** 的循环，循环的 pipeline 由四个参数控制：
+
+```
+for R in 1..max_restart_loop:       # best-solution restart 次数
+  for C in 1..global_width:         # 独立对话分支数量
+    for L in 1..max_refinement_depth:  # 每个分支的迭代轮数
+      for K in 1..local_sample_size:   # 每轮 LLM 重复采样次数
+        ... (单次迭代)
+```
+
+- **R (Restart)**：外层重启循环。每轮重启会用历史最优结果构建新的初始 prompt，引导 LLM 在已有成果上继续搜索。
+- **C (Conversation branch)**：独立对话分支，每个分支从相同的初始 prompt 出发独立探索。
+- **L (Refinement step)**：单个分支内的对话迭代，每轮包含一次完整的 prompt 构建、LLM 请求、工具调用、buffer 更新。
+- **K (Local sample)**：单次 LLM 请求的重复采样次数，产生多个候选响应，产生最佳结果的响应会被追加到 buffer 中，其余结果中不涉及公式评估的工具调用结果也会被追加到 buffer 中以供后续参考。
+
+## SRAgent 核心组件
+
+`Agent` 抽象基类负责 API、Parser、共享工具上下文和工具执行机制。
+`DataPreparationAgent` 基于它维护独立、可持续的资料整理对话；`SRAgent` 基于它维护
+R-C-L-K 符号回归搜索，`SRAgentInteractive` 则在同一个搜索循环上增加人工控制和事件。
+这些 Agent 可以共享一个 `AgentContext`，但不会混用各自的对话 Buffer。
+
+`AgentContext`：内存中的权威研究上下文。它保存完整结构化数据、目标和自变量、变量
+描述、来源、工作区、当前训练/验证划分以及单调递增的数据版本。工具继续通过 Mapping
+接口读取上下文。数据准备 Agent 只在工作区生成或验证 `context.data/`；`InteractiveSession` 在受控边界加载新版本。运行中的交互式
+SRAgent 只在安全迭代边界刷新划分并把变量变化写入原有对话。
+
+SRAgent 在运行时组织以下核心组件：
+
+`tools: List[BaseTool]`：可用的工具实例列表。每个工具接收调用参数，返回一个 `ToolCallResult`。
+- 工具的详细开发指南见 [`tools/README.md`](tools/README.md)。
+- 工具的调用流程如下：
+  1. 初始化 SRAgent 时，工具被实例化并拿到运行时上下文（数据、目标变量等）。
+  2. LLM 产生工具调用（名称 + 参数）
+  3. Agent 根据名称在 `tools` 中查找对应工具实例
+  4. 调用 `tool(**params)`，返回 `ToolCallResult`（包含 `ok`、`result`、`result_str`、`meta_data`）
+
+`api: BaseAPI`：LLM API 实例，负责与 LLM 服务交互。
+- 调用方式如下：
+  ```python
+  llm_result = self.api(messages, n=local_sample_size)
+  ```
+- `messages` 是对话消息列表，格式为 `[{'role': 'system', 'content': ...}, {'role': 'user', 'content': ...}, ...]`。
+- `llm_result` 是一个 `APICallResult` 对象，可迭代获取 LLM 的响应：
+  ```python
+  for content, tool_calls, message in llm_result:
+      # content: LLM 响应中的文字内容
+      # tool_calls: 从响应中解析出的工具调用列表 (List[ToolCall])
+      #   - 文本解析模式 (text/json): 从 content 中解析
+      #   - OpenAI 模式: 从 message 的 tool_calls 字段直接提取
+      # message: 可直接追加到 messages 中以延续对话的消息字典
+  ```
+- 迭代完成后，`llm_result` 中保留用量统计：
+  ```python
+  llm_result.usage   # {'token': {...}, 'price': {...}}
+  ```
+
+## SRAgent 单次迭代流程
+
+每一轮 (L) 的执行步骤如下：
+
+1. **构建 Prompt**：根据当前 buffer（对话历史）构建 messages。
+2. **请求 LLM**：调用 `api(messages)`，得到 K 个候选响应。
+3. **执行工具**：解析每个响应中的 tool_calls，查找并调用对应工具，得到结果列表。
+4. **记录搜索节点**：将当前 Prompt、响应、工具结果、父节点关系和用量写入 `SearchRunState`。
+5. **收集候选公式**：验证 `is_candidate=True` 的结果，并按配置的排名指标更新候选集合。
+6. **更新 Buffer**：选择产生最优候选的分支，将其 message 和工具结果追加到 buffer；其它分支中不涉及公式评估的工具结果也会追加，避免丢失有用信息。
+7. **日志与终止检查**：打印当前最优结果、工具调用统计和 token/费用用量，并判断是否结束搜索。
+
+## 目录结构
+
+```
+src/sr_harness/
+├── agents/
+│   ├── agent.py                 # Agent 抽象基类与共享工具执行机制
+│   ├── data_preparation_agent.py # 持久化的数据准备 Agent
+│   ├── sr_agent.py              # SRAgent 主类，包含 run() 主循环和各个步骤方法
+│   └── sr_agent_interactive.py  # 交互式 SRAgent
+├── api/                         # BaseAPI 与各 Provider API
+│   ├── base_api.py
+│   └── *_api.py                 # OpenAI、DeepSeek、Gemini 等实现
+├── core/                        # APICallResult、ToolCall 和搜索状态等核心结构
+│   ├── api.py
+│   ├── context.py               # AgentContext 共享研究上下文
+│   ├── search.py
+│   └── tool.py
+├── interaction/                 # 终端与 Web 交互管理器
+├── runtime/                     # 模型路由与交互控制器
+├── parser/                      # 工具调用解析器
+│   ├── base_parser.py   # BaseParser 基类
+│   ├── *_parser.py   # 具体解析器实现 (TextParser, JSONParser, ...)
+├── tools/                       # BaseTool 与具体科学工具
+├── skills/                      # 运行时技能管理
+├── web/                         # Web 服务与会话适配
+└── utils/                       # 通用工具函数
+```

sr_harness/__init__.py

@@ -0,0 +1,31 @@
+from .agents.agent import Agent
+from .agents.data_preparation_agent import DataPreparationAgent
+from .agents.evaluator_construction_agent import EvaluatorConstructionAgent
+from .agents.sr_agent import SRAgent
+from .agents.sr_agent_interactive import SRAgentInteractive
+from .core import AgentContext, ToolCall
+from .evaluator import DefaultEvaluator, GraphEvaluator, load_custom_evaluator
+from .runtime import InteractionManager, SRInteractionManager
+from . import api
+from . import tools
+from . import utils
+from . import parser
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "DataPreparationAgent",
+    "DefaultEvaluator",
+    "EvaluatorConstructionAgent",
+    "GraphEvaluator",
+    "InteractionManager",
+    "SRAgent",
+    "SRAgentInteractive",
+    "SRInteractionManager",
+    "ToolCall",
+    "api",
+    "load_custom_evaluator",
+    "parser",
+    "tools",
+    "utils",
+]

sr_harness/_vendor/README.zh.md

@@ -0,0 +1,13 @@
+本目录用于存放被 `sr_harness` 私有化的第三方源码。
+
+具体而言，sr_harness 需要利用第三方的代码和/或工具，尽管绝大多数工具可以通过 `pip install` 等方式安装，某些代码可能：
+1. 不存在合理的包结构、无法通过常规方式安装；
+2. 需要经过适当修改或包装以适应 SRHarness 的调用；
+我们将这类代码作为 `sr_harness` 的内部实现细节，安装到这一目录中。 
+
+这一目录中的依赖应使用 `sr_harness._vendor` 作为唯一导入入口，例如：
+```python
+import sr_harness._vendor.vendor_package
+```
+对于可以安装的第三方库，优先使用正常依赖声明和/或 `pip install`，不要将它放入这一目录。
+不要让同一份源码同时支持 `import vendor_package` 和 `import sr_harness._vendor.vendor_package` 两种入口，否则 Python 会把它们加载成两套模块对象，可能导致 `isinstance`、类身份比较、注册表和缓存失效。

sr_harness/_vendor/llmsr_bench/__init__.py

@@ -0,0 +1 @@
+from .core import SEDTask, SRResult, Problem

sr_harness/_vendor/llmsr_bench/algorithms/__init__.py

@@ -0,0 +1,32 @@
+"""
+符号回归算法集合
+"""
+
+import importlib
+from pathlib import Path
+
+# 算法目录
+ALGORITHMS_DIR = Path(__file__).parent
+
+def get_algorithm(name: str):
+    """获取指定算法的 run 函数"""
+    module = importlib.import_module(f".{name}", __name__)
+    return getattr(module, "run")
+
+
+def get_update_parser(name: str):
+    """获取指定算法的 update_parser 函数"""
+    module = importlib.import_module(f".{name}", __name__)
+    return getattr(module, "update_parser", None)
+
+
+def list_algorithms():
+    """列出所有可用的算法"""
+    algorithms = []
+    for p in ALGORITHMS_DIR.glob("*.py"):
+        if p.stem != "__init__":
+            algorithms.append(p.stem)
+    for p in ALGORITHMS_DIR.iterdir():
+        if p.is_dir() and (p / "__init__.py").exists() and not p.name.startswith("__"):
+            algorithms.append(p.name)
+    return sorted(algorithms)