scienceflow 0.2.0b3__tar.gz

scienceflow-0.2.0b3/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (C) 2026 Huawei Technologies Co., Ltd. All Rights Reserved.
+
+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.

scienceflow-0.2.0b3/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: scienceflow
+Version: 0.2.0b3
+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
+
+<h1 align="center">ScienceFlow</h1>
+
+<p align="center"><b>An End-to-End Autoresearch Agent Framework</b></p>
+
+<p align="center">
+  <a href="https://www.noahlab.com.hk/news/212"><b>Project News</b></a>
+  ·
+  <a href="https://arxiv.org/abs/2608.14354"><b>Paper (arXiv)</b></a>
+  ·
+  <a href="docs/public/README_CN.md"><b>Chinese</b></a>
+</p>
+
+> [!IMPORTANT]
+> **Testing preview.** This code line backs the public `preview` branch and is intended
+> for evaluation, integration testing, and demonstrations. It includes TUI chat,
+> multi-task long research, resume and recovery, resource coordination, and structured
+> telemetry. Interfaces, configuration schemas, UI details, and workspace metadata may
+> change before the stable release. Use the reviewed lock file and isolated workspaces,
+> and do not rely on this preview for unattended production workloads.
+
+ScienceFlow is an end-to-end autoresearch agent framework for productive, stable, and goal-aligned research over hours or days. It organizes research around recoverable executable workspaces, coupling persistent state, adaptive exploration, and evidence-aware execution control so agents can continue, redirect, or recover without losing validated progress.
+
+ScienceFlow documentation uses **iqcraft** as the short name for InquiryCraft. Package,
+import, and CLI examples continue to use the canonical `inquirycraft` name.
+
+Across machine learning, scientific modeling, and mathematical optimization, ScienceFlow sustains effective long-horizon research and reaches **70.22 ± 1.18% Any-Medal** on the full 75-task MLE-bench within a 24-hour budget, exceeding the strongest reported baseline by **4.92 percentage points**.
+
+<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>
+<p align="center"><sub><b>Figure 1a. Full MLE-bench Any-Medal leaderboard.</b> Mean ± SEM over three independent runs for ScienceFlow.</sub></p>
+
+## News
+
+- **[2026-09]** The testing preview is available on the `preview` branch for integration testing and feedback.
+- **[2026-08]** ScienceFlow is open source — the framework code, task packages, and documentation are available in this repository.
+- **[2026-08]** The ScienceFlow paper is available on [arXiv](https://arxiv.org/abs/2608.14354).
+
+## Core concepts
+
+1. **Recoverable executable state.** Each persistent LNR worker advances research in an isolated executable workspace. An archived state binds that workspace to compact memory, validation evidence, and resource records.
+2. **Stage Gate.** A task-specific result signal invokes `GateService`: the configured Evaluator produces normalized evidence, and the Gate policy decides admission. An accepted result materializes an immutable Stage with ledger facts and a recoverable workspace snapshot.
+3. **ESTRA.** At a research boundary, Executable-State Transition through Re-Anchoring makes a two-axis decision: a start point (the current workspace or an archived Stage) and an intent (`continue` or `redirect`). Selecting an archived start point restores its executable state before the next research segment.
+4. **Persistent memory.** Add records accepted Stage progress. Fold keeps recent, best-validated, and anchor-relevant evidence explicit while summarizing older records; Unfold/restore retrieves indexed evidence and state, and Assemble constructs the anchor-specific context for the next segment.
+5. **Evidence-aware execution control.** Research workers choose scientific routes, while the controller admits, leases, monitors, timeboxes, and stops physical jobs using resource availability, remaining budget, validated progress, and recoverability. Valid worker states are finalized under `merge/finals/final_*`.
+
+## System architecture
+
+<p align="center">
+  <img src="docs/public/scienceflow/assets/scienceflow_system_architecture.png" alt="ScienceFlow system architecture" width="100%">
+</p>
+<p align="center"><sub><b>Figure 2. ScienceFlow system architecture.</b> Research workers operate over recoverable executable states and adapt long-horizon trajectories through boundary-triggered ESTRA transitions, while evidence-aware execution control coordinates physical resource allocation and runtime execution.</sub></p>
+
+## Design boundaries
+
+- LNR is **no-skill by default**: `lnr_skill_tool_enabled: false` and `lnr_skill_auto_read: false`.
+- `.scienceflow/skills/data_processing/` is retained only for the dedicated data-prep agent and validation-split workflow.
+- `auto` is the default evaluator backend and resolves registered tasks to `task_package`; `artifact_command` remains available for generic command-based evaluation.
+- Parallel runs bind CPU/GPU resources at task level, then split CPU capacity across workers. GPU leases support controlled sharing by multiple workers.
+- Result signals may create Stages without a submission when the task contract permits it. Merge can only emit finals from candidates that carry the required artifact.
+
+## Repository layout
+
+```text
+ScienceFlow/
+├── scienceflow/                         # Framework package
+│   ├── agent/                           # InquiryCraft host ports, construction, and sessions
+│   ├── foundation/                      # Architecture rules, typed config, and contracts
+│   │   ├── architecture/                # Executable dependency and size policies
+│   │   ├── config/                      # LLM/runtime/schema config and packaged profiles
+│   │   └── contracts/                   # Stable cross-domain values
+│   ├── research/                        # Research-domain decisions and persistent state
+│   │   ├── control/                     # Admission, ESTRA, execution-value, and resources
+│   │   ├── quality/                     # Assessment, Evaluator, Gate, and finalization
+│   │   ├── solver/lnr/                  # Long-horizon solver, split into five responsibilities
+│   │   │   ├── lifecycle/               # Stage, workspace, records, and snapshots
+│   │   │   ├── orchestration/           # Coordinator and worker execution
+│   │   │   ├── resources/               # Resource feedback and physical runtime
+│   │   │   ├── support/                 # Context and prompt support
+│   │   │   └── transitions/             # ESTRA, resume, and recovery
+│   │   └── state/                       # Dataset, knowledge, and workspace state
+│   ├── runtime/                         # Physical execution and operational boundaries
+│   │   ├── core/                        # Kernel, process, stage, and shared runtime support
+│   │   ├── observability/               # Agent I/O, monitoring, correlation, and traces
+│   │   ├── safety/                      # Agent, shell, process, and resource safeguards
+│   │   └── parallel/                    # Task scheduling and subprocess execution
+│   ├── interfaces/                      # User-facing adapters
+│   │   ├── cli/                         # Command composition
+│   │   └── ui/                          # Read-only monitor and trace presentation
+│   └── cli.py                           # Stable `python -m scienceflow.cli` entry point
+├── tasks/                               # Task packages and evaluators
+├── scripts/                             # Five canonical manifests and two lifecycle launchers
+├── tools/                               # Architecture, contract, and parity developer tools
+├── .scienceflow/skills/data_processing/ # Data-preparation skills
+└── docs/                                # Public docs, architecture, plans, benchmarks, and evidence
+```
+
+The package root is intentionally limited to five ownership namespaces: `foundation`,
+`agent`, `research`, `runtime`, and `interfaces`. Foundation defines stable contracts and
+configuration; research owns policy and recoverable state; runtime owns physical effects,
+safety, and observation; agent and interfaces adapt external interaction. InquiryCraft
+remains behind typed ports in `scienceflow/agent`, so ScienceFlow policy does not leak into
+the generic agent runtime. The default fan-out limit at every depth is five immediate
+subdirectories and five direct business modules (`__init__.py` excluded). A small number of
+cohesive product surfaces have explicit path-specific ceilings; increases require review in
+`tests/test_leaf_package_structure_v5_2.py` rather than changing the global default.
+
+## Install and run
+
+**Requirements:** Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+InquiryCraft `0.9.0` is published on the public package index and pinned by the ScienceFlow
+lock file. Create the source environment directly from the reviewed dependency set:
+
+```bash
+cd ScienceFlow
+uv sync --python 3.12 --group dev
+source .venv/bin/activate
+```
+
+The Light runtime without test dependencies uses `uv sync`. The Full profile is
+`uv sync --extra full --group dev`.
+
+Create the private model registry once, edit it, and start the TUI:
+
+```bash
+scienceflow config init
+scienceflow config path
+scienceflow tui --workspace /path/to/workspace
+```
+
+The default registry is `~/.config/scienceflow/models.json` with mode `600`. Use
+`--model-config PATH` to test another registry. API keys stay in the registry and are not copied
+into manifests, sessions, or reports. See [model configuration](docs/public/LLM_CONFIGURATION.md).
+
+Activation is per shell. To expose this checkout without activation, ensure `~/.local/bin` is on
+`PATH` and create a user-level link:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sfn "$PWD/.venv/bin/scienceflow" ~/.local/bin/scienceflow
+scienceflow tui --workspace /path/to/workspace
+```
+
+ScienceFlow embeds InquiryCraft as its sole generic Agent Runtime; no second process is required.
+Useful entry points are:
+
+```bash
+scienceflow agent tools list
+scienceflow repl
+scienceflow parallel -m scripts/lnr.yaml -j 1
+scienceflow monitor --manifest scripts/lnr.yaml --refresh 5
+scienceflow web --workspace /path/to/workspace
+```
+
+After the preview package is published, install the exact pre-release version from PyPI.
+Pinning the version prevents a test environment from changing when a later preview is released.
+Container and Compose usage lives in [`deploy/README.md`](deploy/README.md).
+
+```bash
+pip install scienceflow==0.2.0b3
+pip install "scienceflow[full]"==0.2.0b3
+```
+
+## Configuration essentials
+
+| Setting | Purpose |
+|---|---|
+| `lnr.num_workers` | Number of persistent research workers inside one task. |
+| `task.cpu_list` / `task.gpu_list` | Task-level CPU and GPU resource boundaries; LNR further splits CPU across workers. |
+| `lnr.omp_threads_cap` | CPU thread cap for each worker slice. |
+| `lnr.wall_clock_budget_sec` | Total wall-clock budget for the LNR process. |
+| `lnr.estra_enabled` / `estra_trigger_stage_count` | Enables ESTRA and sets the trigger for boundary review and context folding. |
+| `lnr.resource_runtime_enabled` | Enables evidence-aware resource and execution control. |
+| `resume_budget_policy` | Budget accounting for resumed runs; `fresh` adds this round's `time_limit` on top of accumulated time. |
+| `evaluator.backend` | Selects `auto` (default), `task_package`, or `artifact_command`. |
+| `evaluator.stage_source_mode` | Selects the `shadow`, `adjudicate`, or `primary` Stage source mode. |
+| `evaluator.command.python_executable` | Points a task at an isolated Python environment. |
+| `profile_overrides.<profile>` | Overrides prompts, Evaluator, and resource behavior per task type. |
+| `tasks/**/task.yaml` | Declares the task-level artifact, metric, provider/profile, Evaluator, and Gate policy. |
+| `metric.authoritative: true` | Marks a metric as authoritative evidence eligible for high-trust selection. |
+
+## Documentation
+
+[Documentation index](docs/README.md) · [Architecture overview](docs/public/scienceflow/index.html) · [Recoverable states and LNR](docs/public/scienceflow/module-lnr.html) · [Evidence-aware execution control](docs/public/scienceflow/module-resource.html) · [Adding optimization tasks](docs/public/scienceflow/module-opt-solver-onboarding.html) · [Current plans](docs/plans/current/) · [SciModelingBench](tasks/sci_modeling_bench/README.md)
+
+## Paper task coverage
+
+The paper evaluates the same ScienceFlow workflow across three classes of executable research tasks:
+
+- **Machine learning engineering:** all 75 [MLE-bench](https://github.com/openai/mle-bench) tasks through the pipeline-construction interface.
+- **Scientific modeling and design:** 12 [SciModelingBench tasks on Hugging Face](https://huggingface.co/datasets/sci-modeling-bench/design-bench) through the candidate-optimization interface.
+- **Mathematical and engineering optimization:** [Circle Packing](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/circle_packing), [Ratio Minimization](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/alphaevolve_math_problems/minimizing_max_min_dist), [Uncertainty Inequality](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/alphaevolve_math_problems/uncertainty_ineq), and the easy, medium, and hard [SpOC4 KTTSP](https://www.esa.int/gsp/ACT/news/spoc-2026/) tracks through the candidate-optimization interface.
+
+All task families share the Stage Gate and Evaluator contract. Each `task.yaml` keeps provider/profile, artifact schema, evaluator backend, authoritative status, and Gate policy outside the generic solver. MLE-bench tasks may leave metric direction open for the runtime to resolve from task, stage, and evaluation evidence.
+
+## TUI and managed research
+
+`scienceflow tui` starts a new chat session by default; add `--resume` to restore the latest
+session for the same workspace. Ordinary text uses InquiryCraft's Agent Runtime. The main
+ScienceFlow commands are:
+
+| Command | Purpose |
+|---|---|
+| `/models` | Select the chat model and show the registry path. |
+| `/long-research DESCRIPTION` | Prepare a task, confirm resources and models, preflight, and launch it. |
+| `/tasks`, `/status N` | List tasks or inspect one persistent task number. |
+| `/stop N`, `/resume N`, `/attach N` | Control or attach to a research task. |
+| `/research-usage N`, `/resources` | Show model usage/cost or host and running-task resources. |
+| `/web`, `/web stop` | Start or stop the workspace Web monitor. |
+
+Closing the TUI detaches from supervised research; it does not stop workers. Chat cancellation
+also does not stop research—use `/stop`. Managed-run records live under
+`~/.local/state/scienceflow/managed_runs/`, while chat sessions live under
+`<workspace>/.scienceflow/sessions/`.
+
+`/resources` keeps each `starting` or `running` task on one line. Stopping tasks are hidden, but
+their reservations remain excluded from `Available` until the processes release them.
+
+The CLI exposes the same lifecycle when a full-screen terminal is not wanted:
+
+```bash
+scienceflow run circle-packing --tui --workspace /path/to/experiment
+scienceflow status --all
+scienceflow stop RUN_ID
+scienceflow resume RUN_ID --tui
+```
+
+Do not resume a workspace with a different task profile, dataset, prompt, or artifact contract.
+MLE-bench additionally requires the data root, `exp_id`, and `submission.csv` contract to agree.
+Model pricing is optional and lives only in `models.<alias>.pricing`; missing prices display
+`Cost —` rather than silently using a built-in estimate.
+
+The Web monitor shows task status, workers, metric history, Stage lineage, ESTRA/EEC, usage, and
+final reports. See [Web monitor behavior](docs/web-monitor.md) for local and SSH access.
+
+## Verification
+
+Run tests through the active development environment against the pinned, published
+InquiryCraft `0.9.0` package:
+
+```bash
+.venv/bin/pytest -q \
+  tests/test_inquirycraft_dependency_boundary.py \
+  tests/test_inquirycraft_cli_composition.py \
+  tests/test_long_research_interaction.py
+```
+
+The release workflow accepts only a version-matching tag, builds and checks the wheel and
+source distribution, installs the wheel in a clean runner, and reruns the public dependency
+contracts before publishing through PyPI Trusted Publishing. The full regression command is
+`uv run --locked pytest -q`. Optional ML, GPU, MLE-bench, and scientific-design tests require
+their corresponding extras.

scienceflow-0.2.0b3/README.md

@@ -0,0 +1,253 @@
+<h1 align="center">ScienceFlow</h1>
+
+<p align="center"><b>An End-to-End Autoresearch Agent Framework</b></p>
+
+<p align="center">
+  <a href="https://www.noahlab.com.hk/news/212"><b>Project News</b></a>
+  ·
+  <a href="https://arxiv.org/abs/2608.14354"><b>Paper (arXiv)</b></a>
+  ·
+  <a href="docs/public/README_CN.md"><b>Chinese</b></a>
+</p>
+
+> [!IMPORTANT]
+> **Testing preview.** This code line backs the public `preview` branch and is intended
+> for evaluation, integration testing, and demonstrations. It includes TUI chat,
+> multi-task long research, resume and recovery, resource coordination, and structured
+> telemetry. Interfaces, configuration schemas, UI details, and workspace metadata may
+> change before the stable release. Use the reviewed lock file and isolated workspaces,
+> and do not rely on this preview for unattended production workloads.
+
+ScienceFlow is an end-to-end autoresearch agent framework for productive, stable, and goal-aligned research over hours or days. It organizes research around recoverable executable workspaces, coupling persistent state, adaptive exploration, and evidence-aware execution control so agents can continue, redirect, or recover without losing validated progress.
+
+ScienceFlow documentation uses **iqcraft** as the short name for InquiryCraft. Package,
+import, and CLI examples continue to use the canonical `inquirycraft` name.
+
+Across machine learning, scientific modeling, and mathematical optimization, ScienceFlow sustains effective long-horizon research and reaches **70.22 ± 1.18% Any-Medal** on the full 75-task MLE-bench within a 24-hour budget, exceeding the strongest reported baseline by **4.92 percentage points**.
+
+<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>
+<p align="center"><sub><b>Figure 1a. Full MLE-bench Any-Medal leaderboard.</b> Mean ± SEM over three independent runs for ScienceFlow.</sub></p>
+
+## News
+
+- **[2026-09]** The testing preview is available on the `preview` branch for integration testing and feedback.
+- **[2026-08]** ScienceFlow is open source — the framework code, task packages, and documentation are available in this repository.
+- **[2026-08]** The ScienceFlow paper is available on [arXiv](https://arxiv.org/abs/2608.14354).
+
+## Core concepts
+
+1. **Recoverable executable state.** Each persistent LNR worker advances research in an isolated executable workspace. An archived state binds that workspace to compact memory, validation evidence, and resource records.
+2. **Stage Gate.** A task-specific result signal invokes `GateService`: the configured Evaluator produces normalized evidence, and the Gate policy decides admission. An accepted result materializes an immutable Stage with ledger facts and a recoverable workspace snapshot.
+3. **ESTRA.** At a research boundary, Executable-State Transition through Re-Anchoring makes a two-axis decision: a start point (the current workspace or an archived Stage) and an intent (`continue` or `redirect`). Selecting an archived start point restores its executable state before the next research segment.
+4. **Persistent memory.** Add records accepted Stage progress. Fold keeps recent, best-validated, and anchor-relevant evidence explicit while summarizing older records; Unfold/restore retrieves indexed evidence and state, and Assemble constructs the anchor-specific context for the next segment.
+5. **Evidence-aware execution control.** Research workers choose scientific routes, while the controller admits, leases, monitors, timeboxes, and stops physical jobs using resource availability, remaining budget, validated progress, and recoverability. Valid worker states are finalized under `merge/finals/final_*`.
+
+## System architecture
+
+<p align="center">
+  <img src="docs/public/scienceflow/assets/scienceflow_system_architecture.png" alt="ScienceFlow system architecture" width="100%">
+</p>
+<p align="center"><sub><b>Figure 2. ScienceFlow system architecture.</b> Research workers operate over recoverable executable states and adapt long-horizon trajectories through boundary-triggered ESTRA transitions, while evidence-aware execution control coordinates physical resource allocation and runtime execution.</sub></p>
+
+## Design boundaries
+
+- LNR is **no-skill by default**: `lnr_skill_tool_enabled: false` and `lnr_skill_auto_read: false`.
+- `.scienceflow/skills/data_processing/` is retained only for the dedicated data-prep agent and validation-split workflow.
+- `auto` is the default evaluator backend and resolves registered tasks to `task_package`; `artifact_command` remains available for generic command-based evaluation.
+- Parallel runs bind CPU/GPU resources at task level, then split CPU capacity across workers. GPU leases support controlled sharing by multiple workers.
+- Result signals may create Stages without a submission when the task contract permits it. Merge can only emit finals from candidates that carry the required artifact.
+
+## Repository layout
+
+```text
+ScienceFlow/
+├── scienceflow/                         # Framework package
+│   ├── agent/                           # InquiryCraft host ports, construction, and sessions
+│   ├── foundation/                      # Architecture rules, typed config, and contracts
+│   │   ├── architecture/                # Executable dependency and size policies
+│   │   ├── config/                      # LLM/runtime/schema config and packaged profiles
+│   │   └── contracts/                   # Stable cross-domain values
+│   ├── research/                        # Research-domain decisions and persistent state
+│   │   ├── control/                     # Admission, ESTRA, execution-value, and resources
+│   │   ├── quality/                     # Assessment, Evaluator, Gate, and finalization
+│   │   ├── solver/lnr/                  # Long-horizon solver, split into five responsibilities
+│   │   │   ├── lifecycle/               # Stage, workspace, records, and snapshots
+│   │   │   ├── orchestration/           # Coordinator and worker execution
+│   │   │   ├── resources/               # Resource feedback and physical runtime
+│   │   │   ├── support/                 # Context and prompt support
+│   │   │   └── transitions/             # ESTRA, resume, and recovery
+│   │   └── state/                       # Dataset, knowledge, and workspace state
+│   ├── runtime/                         # Physical execution and operational boundaries
+│   │   ├── core/                        # Kernel, process, stage, and shared runtime support
+│   │   ├── observability/               # Agent I/O, monitoring, correlation, and traces
+│   │   ├── safety/                      # Agent, shell, process, and resource safeguards
+│   │   └── parallel/                    # Task scheduling and subprocess execution
+│   ├── interfaces/                      # User-facing adapters
+│   │   ├── cli/                         # Command composition
+│   │   └── ui/                          # Read-only monitor and trace presentation
+│   └── cli.py                           # Stable `python -m scienceflow.cli` entry point
+├── tasks/                               # Task packages and evaluators
+├── scripts/                             # Five canonical manifests and two lifecycle launchers
+├── tools/                               # Architecture, contract, and parity developer tools
+├── .scienceflow/skills/data_processing/ # Data-preparation skills
+└── docs/                                # Public docs, architecture, plans, benchmarks, and evidence
+```
+
+The package root is intentionally limited to five ownership namespaces: `foundation`,
+`agent`, `research`, `runtime`, and `interfaces`. Foundation defines stable contracts and
+configuration; research owns policy and recoverable state; runtime owns physical effects,
+safety, and observation; agent and interfaces adapt external interaction. InquiryCraft
+remains behind typed ports in `scienceflow/agent`, so ScienceFlow policy does not leak into
+the generic agent runtime. The default fan-out limit at every depth is five immediate
+subdirectories and five direct business modules (`__init__.py` excluded). A small number of
+cohesive product surfaces have explicit path-specific ceilings; increases require review in
+`tests/test_leaf_package_structure_v5_2.py` rather than changing the global default.
+
+## Install and run
+
+**Requirements:** Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+InquiryCraft `0.9.0` is published on the public package index and pinned by the ScienceFlow
+lock file. Create the source environment directly from the reviewed dependency set:
+
+```bash
+cd ScienceFlow
+uv sync --python 3.12 --group dev
+source .venv/bin/activate
+```
+
+The Light runtime without test dependencies uses `uv sync`. The Full profile is
+`uv sync --extra full --group dev`.
+
+Create the private model registry once, edit it, and start the TUI:
+
+```bash
+scienceflow config init
+scienceflow config path
+scienceflow tui --workspace /path/to/workspace
+```
+
+The default registry is `~/.config/scienceflow/models.json` with mode `600`. Use
+`--model-config PATH` to test another registry. API keys stay in the registry and are not copied
+into manifests, sessions, or reports. See [model configuration](docs/public/LLM_CONFIGURATION.md).
+
+Activation is per shell. To expose this checkout without activation, ensure `~/.local/bin` is on
+`PATH` and create a user-level link:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sfn "$PWD/.venv/bin/scienceflow" ~/.local/bin/scienceflow
+scienceflow tui --workspace /path/to/workspace
+```
+
+ScienceFlow embeds InquiryCraft as its sole generic Agent Runtime; no second process is required.
+Useful entry points are:
+
+```bash
+scienceflow agent tools list
+scienceflow repl
+scienceflow parallel -m scripts/lnr.yaml -j 1
+scienceflow monitor --manifest scripts/lnr.yaml --refresh 5
+scienceflow web --workspace /path/to/workspace
+```
+
+After the preview package is published, install the exact pre-release version from PyPI.
+Pinning the version prevents a test environment from changing when a later preview is released.
+Container and Compose usage lives in [`deploy/README.md`](deploy/README.md).
+
+```bash
+pip install scienceflow==0.2.0b3
+pip install "scienceflow[full]"==0.2.0b3
+```
+
+## Configuration essentials
+
+| Setting | Purpose |
+|---|---|
+| `lnr.num_workers` | Number of persistent research workers inside one task. |
+| `task.cpu_list` / `task.gpu_list` | Task-level CPU and GPU resource boundaries; LNR further splits CPU across workers. |
+| `lnr.omp_threads_cap` | CPU thread cap for each worker slice. |
+| `lnr.wall_clock_budget_sec` | Total wall-clock budget for the LNR process. |
+| `lnr.estra_enabled` / `estra_trigger_stage_count` | Enables ESTRA and sets the trigger for boundary review and context folding. |
+| `lnr.resource_runtime_enabled` | Enables evidence-aware resource and execution control. |
+| `resume_budget_policy` | Budget accounting for resumed runs; `fresh` adds this round's `time_limit` on top of accumulated time. |
+| `evaluator.backend` | Selects `auto` (default), `task_package`, or `artifact_command`. |
+| `evaluator.stage_source_mode` | Selects the `shadow`, `adjudicate`, or `primary` Stage source mode. |
+| `evaluator.command.python_executable` | Points a task at an isolated Python environment. |
+| `profile_overrides.<profile>` | Overrides prompts, Evaluator, and resource behavior per task type. |
+| `tasks/**/task.yaml` | Declares the task-level artifact, metric, provider/profile, Evaluator, and Gate policy. |
+| `metric.authoritative: true` | Marks a metric as authoritative evidence eligible for high-trust selection. |
+
+## Documentation
+
+[Documentation index](docs/README.md) · [Architecture overview](docs/public/scienceflow/index.html) · [Recoverable states and LNR](docs/public/scienceflow/module-lnr.html) · [Evidence-aware execution control](docs/public/scienceflow/module-resource.html) · [Adding optimization tasks](docs/public/scienceflow/module-opt-solver-onboarding.html) · [Current plans](docs/plans/current/) · [SciModelingBench](tasks/sci_modeling_bench/README.md)
+
+## Paper task coverage
+
+The paper evaluates the same ScienceFlow workflow across three classes of executable research tasks:
+
+- **Machine learning engineering:** all 75 [MLE-bench](https://github.com/openai/mle-bench) tasks through the pipeline-construction interface.
+- **Scientific modeling and design:** 12 [SciModelingBench tasks on Hugging Face](https://huggingface.co/datasets/sci-modeling-bench/design-bench) through the candidate-optimization interface.
+- **Mathematical and engineering optimization:** [Circle Packing](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/circle_packing), [Ratio Minimization](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/alphaevolve_math_problems/minimizing_max_min_dist), [Uncertainty Inequality](https://github.com/algorithmicsuperintelligence/openevolve/tree/main/examples/alphaevolve_math_problems/uncertainty_ineq), and the easy, medium, and hard [SpOC4 KTTSP](https://www.esa.int/gsp/ACT/news/spoc-2026/) tracks through the candidate-optimization interface.
+
+All task families share the Stage Gate and Evaluator contract. Each `task.yaml` keeps provider/profile, artifact schema, evaluator backend, authoritative status, and Gate policy outside the generic solver. MLE-bench tasks may leave metric direction open for the runtime to resolve from task, stage, and evaluation evidence.
+
+## TUI and managed research
+
+`scienceflow tui` starts a new chat session by default; add `--resume` to restore the latest
+session for the same workspace. Ordinary text uses InquiryCraft's Agent Runtime. The main
+ScienceFlow commands are:
+
+| Command | Purpose |
+|---|---|
+| `/models` | Select the chat model and show the registry path. |
+| `/long-research DESCRIPTION` | Prepare a task, confirm resources and models, preflight, and launch it. |
+| `/tasks`, `/status N` | List tasks or inspect one persistent task number. |
+| `/stop N`, `/resume N`, `/attach N` | Control or attach to a research task. |
+| `/research-usage N`, `/resources` | Show model usage/cost or host and running-task resources. |
+| `/web`, `/web stop` | Start or stop the workspace Web monitor. |
+
+Closing the TUI detaches from supervised research; it does not stop workers. Chat cancellation
+also does not stop research—use `/stop`. Managed-run records live under
+`~/.local/state/scienceflow/managed_runs/`, while chat sessions live under
+`<workspace>/.scienceflow/sessions/`.
+
+`/resources` keeps each `starting` or `running` task on one line. Stopping tasks are hidden, but
+their reservations remain excluded from `Available` until the processes release them.
+
+The CLI exposes the same lifecycle when a full-screen terminal is not wanted:
+
+```bash
+scienceflow run circle-packing --tui --workspace /path/to/experiment
+scienceflow status --all
+scienceflow stop RUN_ID
+scienceflow resume RUN_ID --tui
+```
+
+Do not resume a workspace with a different task profile, dataset, prompt, or artifact contract.
+MLE-bench additionally requires the data root, `exp_id`, and `submission.csv` contract to agree.
+Model pricing is optional and lives only in `models.<alias>.pricing`; missing prices display
+`Cost —` rather than silently using a built-in estimate.
+
+The Web monitor shows task status, workers, metric history, Stage lineage, ESTRA/EEC, usage, and
+final reports. See [Web monitor behavior](docs/web-monitor.md) for local and SSH access.
+
+## Verification
+
+Run tests through the active development environment against the pinned, published
+InquiryCraft `0.9.0` package:
+
+```bash
+.venv/bin/pytest -q \
+  tests/test_inquirycraft_dependency_boundary.py \
+  tests/test_inquirycraft_cli_composition.py \
+  tests/test_long_research_interaction.py
+```
+
+The release workflow accepts only a version-matching tag, builds and checks the wheel and
+source distribution, installs the wheel in a clean runner, and reruns the public dependency
+contracts before publishing through PyPI Trusted Publishing. The full regression command is
+`uv run --locked pytest -q`. Optional ML, GPU, MLE-bench, and scientific-design tests require
+their corresponding extras.