sr-harness 1.0.0__tar.gz

sr_harness-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026-present, YuMeow.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sr_harness-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: sr-harness
+Version: 1.0.0
+Summary: SRHarness: a harness for agentic symbolic regression
+Author-email: YuMeow <yuzh19@tsinghua.org.cn>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: sympy>=1.12
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: docstring-parser>=0.16
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: h5py>=3.16.0
+Requires-Dist: datasets>=4.8.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: nn
+Requires-Dist: torch>=2.0.0; extra == "nn"
+Requires-Dist: torch-geometric>=2.4.0; extra == "nn"
+Provides-Extra: tools
+Requires-Dist: pysr>=1.5.10; extra == "tools"
+Requires-Dist: pysindy>=2.1.0; extra == "tools"
+Requires-Dist: pypdf>=5.0.0; extra == "tools"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ipynbname>=2025.8.0.0; extra == "dev"
+Requires-Dist: yumeow_plot>=0.1.2; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.27; extra == "dev"
+Requires-Dist: mkdocs-static-i18n>=1.3; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: all
+Requires-Dist: sr-harness[dev,nn,tools]; extra == "all"
+Dynamic: license-file
+
+# SRHarness: A Harness for Agentic Symbolic Regression
+
+[English](README.md) | [简体中文](README.zh.md)
+
+[![GitHub](https://img.shields.io/github/stars/yuzhTHU/SRHarness?style=flat&logo=github&label=GitHub)](https://github.com/yuzhTHU/SRHarness)
+[![PyPI](https://img.shields.io/pypi/v/sr-harness?logo=pypi&logoColor=white)](https://pypi.org/project/sr-harness/)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-4e968b?logo=materialformkdocs&logoColor=white)](https://yuzhthu.github.io/SRHarness/)
+[![Live WebUI](https://img.shields.io/badge/WebUI-live-4e968b?logo=googlechrome&logoColor=white)](http://sim1.fiblab.tech:30000/)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.35501-b31b1b?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2609.35501)
+[![Documentation build](https://github.com/yuzhTHU/SRHarness/actions/workflows/docs.yml/badge.svg?branch=dev)](https://github.com/yuzhTHU/SRHarness/actions/workflows/docs.yml)
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.12-3776AB?logo=python&logoColor=white)](https://pypi.org/project/sr-harness/)
+[![License](https://img.shields.io/github/license/yuzhTHU/SRHarness)](LICENSE)
+
+SRHarness is a domain-specific runtime for **agentic symbolic regression**. It lets language-model agents prepare scientific data, invoke composable analysis and fitting tools, retain evaluated hypotheses, and refine interpretable formulas over long search trajectories. Its interactive workbench also supports persistent conversations, editable task configuration, and task-specific formula evaluation through custom Evaluators.
+
+
+## Highlights
+
+- **Composable scientific actions:** analysis, fitting, evaluation, code execution, and formula submission use a shared tool interface.
+- **Persistent scientific state:** candidates, metrics, complexity, diagnostics, provenance, and Pareto rankings survive beyond one model response.
+- **Managed search trajectories:** the `R-C-L-K` lifecycle coordinates restarts, branches, refinement depth, and local sampling.
+- **Interactive research workflow:** the WebUI connects data preparation, task configuration, Evaluator construction, symbolic search, human guidance, and persistent workspaces.
+- **Extensible symbolic modeling:** SRHarness Engine supports ordinary expressions as well as indexed graph and hypergraph formulas.
+
+## Results
+
+The [paper](https://arxiv.org/abs/2609.35501) evaluates SRHarness on LLM-SRBench under matched language-model backbones. LSR-Transform measures symbolic recovery on transformed scientific equations, while LSR-Transform-Anon removes scientific descriptions and variable semantics to test whether the search process remains effective without domain-specific textual cues. The table reports symbolic accuracy (SA):
+
+| Method / backbone | LSR-Transform | LSR-Transform-Anon |
+|---|---:|---:|
+| SRHarness + DeepSeek-v4-flash-0731 | **93.69%** | **72.97%** |
+| SR-Scientist + DeepSeek-v4-flash-0731 | 62.16% | 39.64% |
+| Codex + DeepSeek-v4-flash-0731 | — | 20.72% |
+
+With the same DeepSeek-v4-flash-0731 backbone, SRHarness substantially improves symbolic recovery over SR-Scientist on both settings. Its accuracy remains comparatively high after descriptions and variable semantics are removed, and it also outperforms Codex on the anonymized benchmark. These results indicate that the structured runtime—scientific actions, persistent hypothesis state, and trajectory management—contributes materially beyond the choice of language model alone. See the paper for the complete evaluation protocol, numerical-generalization results, complexity and resource analyses, and ablation studies.
+
+## Installation
+
+SRHarness requires Python 3.12 or newer.
+
+```bash
+pip install sr-harness
+```
+
+See the [installation guide](https://yuzhthu.github.io/SRHarness/install/) for provider configuration, source installation, development environments, and optional integrations.
+
+## Quick Start
+
+### Discover a known equation: `sr-harness synthetic`
+
+Set `OPENROUTER_API_KEY`, then use `synthetic` to generate data from a known equation and test whether SRAgent can recover it:
+
+```bash
+sr-harness synthetic \
+  --equation 'y = 1 + x1 ** 2 + 2 * x1 * x2' \
+  --n-samples 200 \
+  --x-low -2 \
+  --x-high 2 \
+  --seed 42 \
+  --llm-provider openrouter \
+  --llm-model deepseek/deepseek-v4-flash-0731 \
+  --save-path ./logs/quick-start \
+  -R 1 -C 1 -L 10 -K 1
+```
+
+If you use another provider, configure its API key and change `--llm-provider` and `--llm-model` accordingly.
+
+### Interactive workbench: `sr-harness run`
+
+Use `run` for the complete interactive research workflow. It starts the WebUI for data preparation, task and evaluator configuration, symbolic-regression search, and human guidance:
+
+```bash
+sr-harness run \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --workspace-dir ./workspaces \
+  --save-path ./logs/webui
+```
+
+Then open <http://127.0.0.1:8000/>. The workspace registry and conversation workspaces are stored under `./workspaces`, while session snapshots and run records are stored under `./logs/webui`. A hosted instance is also available at <http://sim1.fiblab.tech:30000/>.
+
+## Documentation
+
+- [Overview](https://yuzhthu.github.io/SRHarness/)
+- [Quick Start](https://yuzhthu.github.io/SRHarness/quick-start/)
+- [Installation and provider configuration](https://yuzhthu.github.io/SRHarness/install/)
+- [Commands and runtime options](https://yuzhthu.github.io/SRHarness/sr-harness/)
+- [SRHarness Agent Workflow](https://yuzhthu.github.io/SRHarness/agent/)
+- [Tools and tool-call Parsers](https://yuzhthu.github.io/SRHarness/core-abstractions/)
+- [Structured data and `context.data`](https://yuzhthu.github.io/SRHarness/context-data/)
+- [Formula evaluation and custom Evaluators](https://yuzhthu.github.io/SRHarness/evaluator/)
+- [SRHarness WebUI](https://yuzhthu.github.io/SRHarness/web-ui/)
+- [SRHarness Engine](https://yuzhthu.github.io/SRHarness/engine/)
+- [API reference](https://yuzhthu.github.io/SRHarness/reference/)
+
+## Citation
+
+```bibtex
+@article{yu2026srharness,
+  title   = {SRHarness: A Harness for Agentic Symbolic Regression},
+  author  = {Yu, Zihan and Zhou, Shixuan and Huang, Hao and Ding, Jingtao and Li, Yong},
+  journal = {arXiv preprint arXiv:2609.35501},
+  year    = {2026}
+}
+```
+
+## License
+
+SRHarness is released under the [MIT License](LICENSE).

sr_harness-1.0.0/README.md

@@ -0,0 +1,109 @@
+# SRHarness: A Harness for Agentic Symbolic Regression
+
+[English](README.md) | [简体中文](README.zh.md)
+
+[![GitHub](https://img.shields.io/github/stars/yuzhTHU/SRHarness?style=flat&logo=github&label=GitHub)](https://github.com/yuzhTHU/SRHarness)
+[![PyPI](https://img.shields.io/pypi/v/sr-harness?logo=pypi&logoColor=white)](https://pypi.org/project/sr-harness/)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-4e968b?logo=materialformkdocs&logoColor=white)](https://yuzhthu.github.io/SRHarness/)
+[![Live WebUI](https://img.shields.io/badge/WebUI-live-4e968b?logo=googlechrome&logoColor=white)](http://sim1.fiblab.tech:30000/)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.35501-b31b1b?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2609.35501)
+[![Documentation build](https://github.com/yuzhTHU/SRHarness/actions/workflows/docs.yml/badge.svg?branch=dev)](https://github.com/yuzhTHU/SRHarness/actions/workflows/docs.yml)
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.12-3776AB?logo=python&logoColor=white)](https://pypi.org/project/sr-harness/)
+[![License](https://img.shields.io/github/license/yuzhTHU/SRHarness)](LICENSE)
+
+SRHarness is a domain-specific runtime for **agentic symbolic regression**. It lets language-model agents prepare scientific data, invoke composable analysis and fitting tools, retain evaluated hypotheses, and refine interpretable formulas over long search trajectories. Its interactive workbench also supports persistent conversations, editable task configuration, and task-specific formula evaluation through custom Evaluators.
+
+
+## Highlights
+
+- **Composable scientific actions:** analysis, fitting, evaluation, code execution, and formula submission use a shared tool interface.
+- **Persistent scientific state:** candidates, metrics, complexity, diagnostics, provenance, and Pareto rankings survive beyond one model response.
+- **Managed search trajectories:** the `R-C-L-K` lifecycle coordinates restarts, branches, refinement depth, and local sampling.
+- **Interactive research workflow:** the WebUI connects data preparation, task configuration, Evaluator construction, symbolic search, human guidance, and persistent workspaces.
+- **Extensible symbolic modeling:** SRHarness Engine supports ordinary expressions as well as indexed graph and hypergraph formulas.
+
+## Results
+
+The [paper](https://arxiv.org/abs/2609.35501) evaluates SRHarness on LLM-SRBench under matched language-model backbones. LSR-Transform measures symbolic recovery on transformed scientific equations, while LSR-Transform-Anon removes scientific descriptions and variable semantics to test whether the search process remains effective without domain-specific textual cues. The table reports symbolic accuracy (SA):
+
+| Method / backbone | LSR-Transform | LSR-Transform-Anon |
+|---|---:|---:|
+| SRHarness + DeepSeek-v4-flash-0731 | **93.69%** | **72.97%** |
+| SR-Scientist + DeepSeek-v4-flash-0731 | 62.16% | 39.64% |
+| Codex + DeepSeek-v4-flash-0731 | — | 20.72% |
+
+With the same DeepSeek-v4-flash-0731 backbone, SRHarness substantially improves symbolic recovery over SR-Scientist on both settings. Its accuracy remains comparatively high after descriptions and variable semantics are removed, and it also outperforms Codex on the anonymized benchmark. These results indicate that the structured runtime—scientific actions, persistent hypothesis state, and trajectory management—contributes materially beyond the choice of language model alone. See the paper for the complete evaluation protocol, numerical-generalization results, complexity and resource analyses, and ablation studies.
+
+## Installation
+
+SRHarness requires Python 3.12 or newer.
+
+```bash
+pip install sr-harness
+```
+
+See the [installation guide](https://yuzhthu.github.io/SRHarness/install/) for provider configuration, source installation, development environments, and optional integrations.
+
+## Quick Start
+
+### Discover a known equation: `sr-harness synthetic`
+
+Set `OPENROUTER_API_KEY`, then use `synthetic` to generate data from a known equation and test whether SRAgent can recover it:
+
+```bash
+sr-harness synthetic \
+  --equation 'y = 1 + x1 ** 2 + 2 * x1 * x2' \
+  --n-samples 200 \
+  --x-low -2 \
+  --x-high 2 \
+  --seed 42 \
+  --llm-provider openrouter \
+  --llm-model deepseek/deepseek-v4-flash-0731 \
+  --save-path ./logs/quick-start \
+  -R 1 -C 1 -L 10 -K 1
+```
+
+If you use another provider, configure its API key and change `--llm-provider` and `--llm-model` accordingly.
+
+### Interactive workbench: `sr-harness run`
+
+Use `run` for the complete interactive research workflow. It starts the WebUI for data preparation, task and evaluator configuration, symbolic-regression search, and human guidance:
+
+```bash
+sr-harness run \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --workspace-dir ./workspaces \
+  --save-path ./logs/webui
+```
+
+Then open <http://127.0.0.1:8000/>. The workspace registry and conversation workspaces are stored under `./workspaces`, while session snapshots and run records are stored under `./logs/webui`. A hosted instance is also available at <http://sim1.fiblab.tech:30000/>.
+
+## Documentation
+
+- [Overview](https://yuzhthu.github.io/SRHarness/)
+- [Quick Start](https://yuzhthu.github.io/SRHarness/quick-start/)
+- [Installation and provider configuration](https://yuzhthu.github.io/SRHarness/install/)
+- [Commands and runtime options](https://yuzhthu.github.io/SRHarness/sr-harness/)
+- [SRHarness Agent Workflow](https://yuzhthu.github.io/SRHarness/agent/)
+- [Tools and tool-call Parsers](https://yuzhthu.github.io/SRHarness/core-abstractions/)
+- [Structured data and `context.data`](https://yuzhthu.github.io/SRHarness/context-data/)
+- [Formula evaluation and custom Evaluators](https://yuzhthu.github.io/SRHarness/evaluator/)
+- [SRHarness WebUI](https://yuzhthu.github.io/SRHarness/web-ui/)
+- [SRHarness Engine](https://yuzhthu.github.io/SRHarness/engine/)
+- [API reference](https://yuzhthu.github.io/SRHarness/reference/)
+
+## Citation
+
+```bibtex
+@article{yu2026srharness,
+  title   = {SRHarness: A Harness for Agentic Symbolic Regression},
+  author  = {Yu, Zihan and Zhou, Shixuan and Huang, Hao and Ding, Jingtao and Li, Yong},
+  journal = {arXiv preprint arXiv:2609.35501},
+  year    = {2026}
+}
+```
+
+## License
+
+SRHarness is released under the [MIT License](LICENSE).

sr_harness-1.0.0/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sr-harness"
+version = "1.0.0"
+description = "SRHarness: a harness for agentic symbolic regression"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+license = "MIT"
+authors = [
+    {name = "YuMeow", email = "yuzh19@tsinghua.org.cn"}
+]
+dependencies = [
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "scikit-learn>=1.3.0",
+    "sympy>=1.12",
+    "pandas>=2.0.0",
+    "openpyxl>=3.1.0",
+    "joblib>=1.3.0",
+    "docstring-parser>=0.16",
+    "pyyaml>=6.0",
+    "rich>=13.0.0",
+    "matplotlib>=3.7.0",
+    "openai>=1.0.0",
+    "google-genai>=1.0.0",
+    "requests>=2.28.0",
+    "python-dotenv>=1.0.0",
+    "h5py>=3.16.0",
+    "datasets>=4.8.0",
+    "textual>=1.0.0",
+    "prompt_toolkit>=3.0.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.scripts]
+sr-harness = "sr_harness.cli:entrypoint"
+
+[project.optional-dependencies]
+nn = [
+    "torch>=2.0.0",
+    "torch-geometric>=2.4.0",
+]
+tools = [
+    "pysr>=1.5.10",
+    "pysindy>=2.1.0",
+    "pypdf>=5.0.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "ipynbname>=2025.8.0.0",
+    "yumeow_plot>=0.1.2",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+    "mkdocs-static-i18n>=1.3",
+    "ruff>=0.8",
+]
+all = [
+    "sr-harness[nn,tools,dev]",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sr_harness*", "sr_harness_engine*"]
+
+[tool.setuptools.package-data]
+sr_harness = [
+    "*.md",
+    "*.yaml",
+    "**/*.md",
+    "**/*.yaml",
+    "web/static/*.html",
+    "web/static/*.svg",
+]
+sr_harness_engine = ["README.zh.md"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+markers = [
+    "slow: marks tests as slow (integration tests)",
+    "paid: marks tests as paid API calls (requires credits)",
+]
+addopts = "--quiet -m 'not slow and not paid'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]

sr_harness-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sr_harness-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/sr_harness/_vendor/llmsr_bench/__init__.py

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

sr_harness-1.0.0/src/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)