Metadata-Version: 2.4
Name: scienceflow
Version: 0.2.0b4
Summary: An end-to-end autoresearch agent framework for long-horizon ML research, scientific discovery, and beyond
License-Expression: MIT
Project-URL: Homepage, https://github.com/science-learner/ScienceFlow
Project-URL: Repository, https://github.com/science-learner/ScienceFlow
Project-URL: Documentation, https://github.com/science-learner/ScienceFlow/tree/preview/docs
Project-URL: Issues, https://github.com/science-learner/ScienceFlow/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: omegaconf>=2.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: psutil>=5.9
Requires-Dist: aiofiles>=23.0
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.1
Requires-Dist: dataclasses-json>=0.6.0
Requires-Dist: openai>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: tenacity>=9.0
Requires-Dist: lazy-loader>=0.4
Requires-Dist: inquirycraft[openai,tui]==0.9.0
Requires-Dist: backports-zstd>=1.3
Requires-Dist: tornado>=6.4
Requires-Dist: reportlab<5,>=4.2
Provides-Extra: ml
Requires-Dist: numpy>=1.26; extra == "ml"
Requires-Dist: pandas>=2.2; extra == "ml"
Requires-Dist: scipy>=1.12; extra == "ml"
Requires-Dist: scikit-learn>=1.3; extra == "ml"
Requires-Dist: openpyxl>=3.1; extra == "ml"
Requires-Dist: matplotlib>=3.8; extra == "ml"
Requires-Dist: seaborn>=0.13; extra == "ml"
Requires-Dist: catboost>=1.2; extra == "ml"
Requires-Dist: xgboost>=2.0; extra == "ml"
Requires-Dist: lightgbm>=4.0; extra == "ml"
Provides-Extra: gpu
Requires-Dist: numpy>=1.26; extra == "gpu"
Requires-Dist: tabpfn>=7.0; extra == "gpu"
Requires-Dist: torch>=2.11; extra == "gpu"
Requires-Dist: torchvision>=0.20; extra == "gpu"
Requires-Dist: pillow>=10.0; extra == "gpu"
Requires-Dist: torchaudio<2.12,>=2.11.0; extra == "gpu"
Requires-Dist: sentencepiece>=0.2; extra == "gpu"
Requires-Dist: timm>=1.0.3; extra == "gpu"
Requires-Dist: segmentation-models-pytorch>=0.3.4; extra == "gpu"
Requires-Dist: ultralytics>=8.0; extra == "gpu"
Requires-Dist: transformers>=4.40; extra == "gpu"
Requires-Dist: protobuf>=4.25; extra == "gpu"
Requires-Dist: tiktoken>=0.7; extra == "gpu"
Requires-Dist: librosa>=0.10; extra == "gpu"
Requires-Dist: muq; extra == "gpu"
Requires-Dist: opencv-python-headless>=4.8; extra == "gpu"
Requires-Dist: torchmetrics>=1.0; extra == "gpu"
Requires-Dist: termcolor>=2.0; extra == "gpu"
Provides-Extra: mlebench
Requires-Dist: mlebench; extra == "mlebench"
Requires-Dist: pydicom>=2.4; extra == "mlebench"
Provides-Extra: detection-2d
Requires-Dist: dicomsdl>=0.107; extra == "detection-2d"
Requires-Dist: ensemble-boxes>=1.0; extra == "detection-2d"
Provides-Extra: inquirycraft-mcp
Requires-Dist: inquirycraft[mcp]==0.9.0; extra == "inquirycraft-mcp"
Provides-Extra: scientific-design
Requires-Dist: cloudpickle>=3.0; extra == "scientific-design"
Requires-Dist: sci-modeling-bench==0.10.0; extra == "scientific-design"
Provides-Extra: full
Requires-Dist: numpy>=1.26; extra == "full"
Requires-Dist: pandas>=2.2; extra == "full"
Requires-Dist: scipy>=1.12; extra == "full"
Requires-Dist: scikit-learn>=1.3; extra == "full"
Requires-Dist: openpyxl>=3.1; extra == "full"
Requires-Dist: matplotlib>=3.8; extra == "full"
Requires-Dist: seaborn>=0.13; extra == "full"
Requires-Dist: tabpfn>=7.0; extra == "full"
Requires-Dist: catboost>=1.2; extra == "full"
Requires-Dist: xgboost>=2.0; extra == "full"
Requires-Dist: lightgbm>=4.0; extra == "full"
Requires-Dist: torch>=2.11; extra == "full"
Requires-Dist: torchvision>=0.20; extra == "full"
Requires-Dist: pillow>=10.0; extra == "full"
Requires-Dist: torchaudio<2.12,>=2.11.0; extra == "full"
Requires-Dist: sentencepiece>=0.2; extra == "full"
Requires-Dist: timm>=1.0.3; extra == "full"
Requires-Dist: segmentation-models-pytorch>=0.3.4; extra == "full"
Requires-Dist: ultralytics>=8.0; extra == "full"
Requires-Dist: transformers>=4.40; extra == "full"
Requires-Dist: protobuf>=4.25; extra == "full"
Requires-Dist: tiktoken>=0.7; extra == "full"
Requires-Dist: librosa>=0.10; extra == "full"
Requires-Dist: muq; extra == "full"
Requires-Dist: opencv-python-headless>=4.8; extra == "full"
Requires-Dist: torchmetrics>=1.0; extra == "full"
Requires-Dist: termcolor>=2.0; extra == "full"
Requires-Dist: mlebench; extra == "full"
Requires-Dist: pydicom>=2.4; extra == "full"
Requires-Dist: dicomsdl>=0.107; extra == "full"
Requires-Dist: ensemble-boxes>=1.0; extra == "full"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/brand/scienceflow-banner.svg" alt="ScienceFlow" width="800">
</p>

<p align="center">
  <a href="https://github.com/science-learner/ScienceFlow/actions/workflows/scienceflow-contract-ci.yml"><img src="https://github.com/science-learner/ScienceFlow/actions/workflows/scienceflow-contract-ci.yml/badge.svg?branch=preview" alt="CI"></a>
  <a href="https://pypi.org/project/scienceflow/"><img src="https://img.shields.io/pypi/v/scienceflow?label=PyPI&amp;color=0f766e" alt="PyPI"></a>
  <a href="https://arxiv.org/abs/2608.14354"><img src="https://img.shields.io/badge/arXiv-2608.14354-B31B1B.svg" alt="arXiv paper"></a>
  <a href="https://github.com/science-learner/ScienceFlow/issues"><img src="https://img.shields.io/badge/feedback-open-334155" alt="Feedback"></a>
  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB" alt="Python 3.11+">
</p>

<p align="justify">
ScienceFlow turns an executable task with a measurable objective into persistent,
evaluator-guided research. It coordinates parallel workers, promotes valid results into
recoverable stages, preserves the best artifacts, and exposes the full process through a
TUI and Web monitor.
</p>

> [!IMPORTANT]
> **Testing preview.** Interfaces and workspace metadata may change before the stable release.

## Quick start

<p align="justify"><strong>Requirements:</strong> Python 3.11+ and access to a supported model API.</p>

```bash
uv tool install scienceflow==0.2.0b4
scienceflow config init
scienceflow config path     # edit the generated private model registry
scienceflow tui --workspace "$PWD/sf_workspace"
```

<p align="justify">
<code>pipx install scienceflow==0.2.0b4</code> is an equivalent isolated installation.
Inside an activated virtual environment, use
<code>python -m pip install scienceflow==0.2.0b4</code>. On Debian and Ubuntu, avoid
bypassing PEP 668 with <code>--break-system-packages</code>.
</p>

<p align="justify">
Chat normally in the TUI, or enter <code>/long-research</code> to configure and launch a
managed task. Closing the TUI detaches from research without terminating its workers.
</p>

### Minimal TUI example

<p align="justify">
The built-in <code>circle-packing</code> example needs no dataset. After starting the TUI,
complete these prompts in order:
</p>

**1 · Prepare the task**

```text
/long-research circle-packing data=none workers=2 cpu=16 gpu=cpu duration=1h
```

**2 · Accept the model defaults**

```text
default
```

**3 · Start after preflight passes**

```text
run
```

<p align="justify">
ScienceFlow runs preflight checks, starts two CPU workers, evaluates candidate solutions,
and retains the best valid artifact under the workspace. Follow it with
<code>/tasks</code> or <code>/status 1</code>.
</p>

<table width="100%">
  <thead>
    <tr>
      <th width="500" align="center">Command</th>
      <th width="500" align="center">Purpose</th>
    </tr>
  </thead>
  <tbody>
    <tr><td align="left"><code>/long-research DESCRIPTION</code></td><td align="left">Prepare and launch a research task.</td></tr>
    <tr><td align="left"><code>/tasks</code>, <code>/status N</code></td><td align="left">List tasks or inspect one task.</td></tr>
    <tr><td align="left"><code>/stop N</code>, <code>/resume N</code>, <code>/attach N</code></td><td align="left">Control or follow a task.</td></tr>
    <tr><td align="left"><code>/research-usage N</code>, <code>/resources</code></td><td align="left">Inspect model, cost, and resource usage.</td></tr>
    <tr><td align="left"><code>/models</code></td><td align="left">Select the fixed chat model.</td></tr>
    <tr><td align="left"><code>/web</code>, <code>/web stop</code></td><td align="left">Start or stop the workspace Web monitor.</td></tr>
  </tbody>
</table>

Resume the latest chat session with:

```bash
scienceflow tui --workspace "$PWD/sf_workspace" --resume
```

## How it works

<p align="center">
  <img src="docs/public/scienceflow/assets/scienceflow_system_architecture.png" alt="ScienceFlow system architecture" width="100%">
</p>

1. **Explore:** isolated workers advance executable workspaces under explicit CPU, GPU,
   model, and time budgets.
2. **Evaluate:** task evaluators convert artifacts into normalized evidence and final scores.
3. **Preserve:** Stage Gate admits valid results as immutable, recoverable stages while the
   best artifact remains available independently of submission state.
4. **Adapt:** ESTRA continues the current route or re-anchors work to a stronger archived
   stage at research boundaries.

<p align="justify">
Agent messages, reasoning, tool calls, evaluator results, resource samples, costs, and stage
lineage are retained as structured events for inspection and future training workflows.
</p>

## Task contract

<table width="100%">
  <thead>
    <tr>
      <th width="500" align="center">You provide</th>
      <th width="500" align="center">ScienceFlow manages</th>
    </tr>
  </thead>
  <tbody>
    <tr><td align="left">Objective, constraints, and metric direction</td><td align="left">Research lifecycle and parallel workers</td></tr>
    <tr><td align="left">Executable task code and required data</td><td align="left">Isolated workspaces and resource leases</td></tr>
    <tr><td align="left">Evaluator and valid artifact contract</td><td align="left">Evidence normalization and Stage admission</td></tr>
    <tr><td align="left">Baseline or starting implementation</td><td align="left">Exploration, recovery, selection, and finalization</td></tr>
  </tbody>
</table>

<p align="justify">
A registered <code>task.yaml</code> is the source of truth for measurement and valid
artifacts. ScienceFlow does not invent a missing evaluator or silently replace required
task data.
</p>

## Models, resources, and task environments

<p>
Model settings stay local in <code>~/.config/scienceflow/models.json</code> (mode
<code>600</code>); API keys are excluded from task manifests, sessions, and reports. See the
<a href="docs/examples/models.example.json">redacted example</a>.
</p>

<p align="justify">
The base package provides the control plane and TUI. Install task-specific ML/GPU
dependencies only when needed:
</p>

```bash
python -m pip install "scienceflow[full]"==0.2.0b4
```

<p align="justify">
CPU and GPU allocations form task boundaries; CPU capacity is divided across workers. Model
pricing is optional—without it, the UI reports <code>Cost —</code>. Do not resume a
workspace with a different task, dataset, evaluator, prompt, or artifact contract.
</p>

## Develop from source

```bash
git clone --branch preview https://github.com/science-learner/ScienceFlow.git
cd ScienceFlow
uv sync --python 3.12 --group dev
uv run scienceflow config init
uv run scienceflow tui --workspace "$PWD/sf_workspace"
```

<p align="justify">
Use <code>uv sync --extra full --group dev</code> only when tests require the full ML/GPU
environment.
</p>

## Research

<p align="justify">
ScienceFlow uses the same Stage Gate and evaluator contract across machine-learning
engineering, scientific modeling, and mathematical optimization. In the reported 24-hour,
75-task MLE-bench evaluation, it reaches <strong>70.22 ± 1.18% Any-Medal</strong> over three
runs.
</p>

<p align="center">
  <img src="docs/public/scienceflow/assets/mlebench_top10_any_medal.png" alt="Representative full MLE-bench Any-Medal leaderboard" width="100%">
</p>

## Citation

If ScienceFlow supports your research, please cite:

```bibtex
@misc{zhao2026scienceflow,
  title         = {{ScienceFlow}: A Long-Horizon Agent for {ML} Research, Scientific Discovery and Beyond},
  author        = {Mingming Zhao and Jiqian Dong and Kangping Xu and Zadid Hasan and Chengrui Fan and Shan Jiang and Shuai Mao and Yating Ling and Linyi Zou and Tailin Zhou and Yun Hin Chan and Wenkai Zhang and Zhanhong Zhou and Guowei Huang and Hongliang Li and Wenjing Cun and Zhitang Chen and Mingxuan Yuan and Yanhui Geng},
  year          = {2026},
  eprint        = {2608.14354},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  doi           = {10.48550/arXiv.2608.14354},
  url           = {https://arxiv.org/abs/2608.14354}
}
```
