scienceflow 0.2.0b5

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.

Quick start

Requirements: Python 3.11+ and access to a supported model API.

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

pipx install scienceflow==0.2.0b5 is an equivalent isolated installation. Inside an activated virtual environment, use python -m pip install scienceflow==0.2.0b5. On Debian and Ubuntu, avoid bypassing PEP 668 with --break-system-packages.

Chat normally in the TUI, or enter /long-research to configure and launch a managed task. Closing the TUI detaches from research without terminating its workers.

Minimal TUI example

The built-in circle-packing example needs no dataset. After starting the TUI, complete these prompts in order:

1 · Prepare the task

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

2 · Accept the model defaults

default

3 · Start after preflight passes

run

ScienceFlow runs preflight checks, starts two CPU workers, evaluates candidate solutions, and retains the best valid artifact under the workspace. Follow it with /tasks or /status 1.

Resume the latest chat session with:

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

How it works

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.

Agent messages, reasoning, tool calls, evaluator results, resource samples, costs, and stage lineage are retained as structured events for inspection and future training workflows.

Task contract

A registered task.yaml is the source of truth for measurement and valid artifacts. ScienceFlow does not invent a missing evaluator or silently replace required task data.

Models, resources, and task environments

Model settings stay local in ~/.config/scienceflow/models.json (mode 600); API keys are excluded from task manifests, sessions, and reports. See the redacted example.

The base package provides the control plane and TUI. Install task-specific ML/GPU dependencies only when needed:

python -m pip install "scienceflow[full]"==0.2.0b5

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

Develop from source

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"

Use uv sync --extra full --group dev only when tests require the full ML/GPU environment.

Research

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 70.22 ± 1.18% Any-Medal over three runs.

Citation

If ScienceFlow supports your research, please cite:

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