Metadata-Version: 2.4
Name: deepbuilder
Version: 0.1.0
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/deepbuilderai/deepbuilder
Project-URL: Repository, https://github.com/deepbuilderai/deepbuilder
Project-URL: Documentation, https://github.com/deepbuilderai/deepbuilder/tree/main/docs
Project-URL: Issues, https://github.com/deepbuilderai/deepbuilder/issues
Classifier: Development Status :: 5 - Production/Stable
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=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.8
Requires-Dist: backports-zstd>=1.3
Requires-Dist: tornado>=6.4
Requires-Dist: markdown-it-py<5,>=3
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.8; 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">
  <a href="https://github.com/deepbuilderai/deepbuilder/actions/workflows/deepbuilder-contract-ci.yml"><img src="https://github.com/deepbuilderai/deepbuilder/actions/workflows/deepbuilder-contract-ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://pypi.org/project/deepbuilder/"><img src="https://img.shields.io/pypi/v/deepbuilder?label=PyPI&amp;color=0f766e&amp;cacheSeconds=300" alt="PyPI"></a>
  <a href="https://github.com/deepbuilderai/deepbuilder/issues"><img src="https://img.shields.io/badge/feedback-open-334155" alt="Feedback"></a>
  <img src="https://img.shields.io/badge/Python-3.11--3.13-3776AB" alt="Python 3.11–3.13">
</p>

<p align="justify">
DeepBuilder 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>

## Quick start

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

### Install

Create an isolated Conda environment, then install DeepBuilder from PyPI:

```bash
conda create -n deepbuilder python=3.12 -y
conda activate deepbuilder
python -m pip install deepbuilder
deepbuilder --help
```

<details>
<summary><strong>Other installation methods</strong></summary>

**pipx**

```bash
pipx install deepbuilder
```

**uv**

```bash
uv tool install deepbuilder
```

**Python virtual environment**

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install deepbuilder
```

</details>

### Configure and start

```bash
deepbuilder config init
deepbuilder config path     # edit the generated private model registry
deepbuilder tui
```

<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 workers=2 cpu=16 gpu=cpu duration=1h
```

**2 · Start after preflight passes**

```text
run
```

<p align="justify">
DeepBuilder 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 results, model usage, and resources.</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>/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>

Choose a saved chat session with:

```bash
deepbuilder tui --resume
```

See the [runtime guide](https://deepbuilder.ai/guides/runtime/) for workspace and execution details.

## 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.

<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">DeepBuilder 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. DeepBuilder 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/deepbuilder/models.json</code> (mode
<code>600</code>); API keys are excluded from task manifests, sessions, and reports. See the
<a href="https://github.com/deepbuilderai/deepbuilder/blob/main/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 "deepbuilder[full]"
```

<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 https://github.com/deepbuilderai/deepbuilder.git
cd deepbuilder
uv sync --python 3.12 --group dev
uv run deepbuilder config init
uv run deepbuilder tui
```

<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">
DeepBuilder 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, exceeding the strongest reported baseline by <strong>5.78 percentage points</strong>.
</p>
