### Install Kaggle CLI and Setup Credentials

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Install the Kaggle CLI and configure API credentials for downloading competition data.

```bash
pip install kaggle
mkdir -p ~/.kaggle
mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json   # from kaggle.com → Account → API
chmod 600 ~/.kaggle/kaggle.json
```

--------------------------------

### Example of a Bad Proposal (Incomplete)

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/references/analyst-proposal-guide.md

This proposal is considered bad because it is incomplete and lacks actionable details for GPU agents. It uses vague language like 'try using X' without providing necessary context such as repo URL, installation instructions, or specific functions to call.

```markdown
[PROPOSAL] exp_042: use MolBERT embeddings
Try using MolBERT to get better molecular representations.
Expected to improve MAE.
```

--------------------------------

### Create and Install into Biomlbench Venv

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Set up the biomlbench Python virtual environment from scratch using its pyproject.toml and install all dependencies.

```bash
# Create a new venv from the biomlbench pyproject.toml
cd /path/to/biomlbench
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[all]"

# Install PyTorch with CUDA 12.4 (adjust index URL for your CUDA version)
pip install torch==2.5.1 torchvision --index-url https://download.pytorch.org/whl/cu124

# Install additional packages used by agents
pip install fair-esm gpytorch segmentation-models-pytorch torchio torch-geometric
```

--------------------------------

### Post Setup Note to Workspace

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/SKILL.md

Posts a setup note to the workspace's knowledge files. Ensure the `setup_note` variable is correctly populated.

```python
requests.put(
    f"{API}/workspaces/{TEAM_WS_ID}/files/knowledge/setup_{REPO_NAME}.md",
    headers=HEADERS, json={"content": setup_note}
)
```

--------------------------------

### GPU Dispatch Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-autoresearch/LAUNCH.md

Defines a list of GPU agent names and outlines a simple sequential dispatch strategy, alternating GPUs and waiting between dispatches. This is intended for cold start scenarios.

```python
gpu_agents = [f"{PREFIX}_gpu{i}" for i in range(1, 7)]

# Simple sequential model: alternate GPUs, wait between dispatches.
# On cold start, dispatch GPU #1 as soon as the first queue is seeded (don't wait
```

--------------------------------

### Estimate Setup Complexity

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/references/analyst-proposal-guide.md

Rate the setup difficulty using predefined categories (Easy, Medium, Hard, Unknown) to help GPU agents budget their time.

```text
| Rating | Meaning |
|--------|---------|
| **Easy** | Pure PyPI install (`pip install X`). No checkpoint. No env conflicts. |
| **Medium** | GitHub clone + pip install from source. One checkpoint from HuggingFace. |
| **Hard** | Requires specific CUDA version, conflicting deps, or multi-step install. |
| **Unknown** | Not verified — GPU agent must assess. |
```

--------------------------------

### Example Proposal: Pretrained Molecular Encoder Integration

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/references/analyst-proposal-guide.md

A complete example proposal demonstrating how to integrate a pretrained molecular encoder, including repo, weights, interface sketch, and setup details.

```python
import sys
sys.path.insert(0, f"{FOCUS_ROOT}/.cache/repos/REPO_NAME")
from repo_module import Encoder

encoder = Encoder.from_pretrained("ORG/MODEL_NAME")
encoder.eval()
with torch.no_grad():
    embeddings = encoder.encode(smiles_list)  # np.ndarray (N, 768)
```

```python
# Load pretrained embeddings (pre-cached by setup step)
emb_train = np.load(f"{FOCUS_ROOT}/.cache/embeddings/REPO_NAME_train.npy")
emb_val   = np.load(f"{FOCUS_ROOT}/.cache/embeddings/REPO_NAME_val.npy")
X_train = np.hstack([X_train_morgan, emb_train])
X_val   = np.hstack([X_val_morgan,   emb_val])
```

--------------------------------

### Start Local ClawInstitute Server

Source: https://github.com/mims-harvard/autoscientists/blob/main/README.md

Starts the local ClawInstitute server, which agents use for coordination. This command downloads the clawinstitute package from npm on the first run.

```bash
npx clawinstitute start
```

--------------------------------

### Clone and Install biomlbench CLI

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Steps to clone the biomlbench repository and install its command-line interface. This is a prerequisite for preparing the data cache.

```bash
# 1. Clone biomlbench and install it
git clone https://github.com/science-machine/biomlbench.git
cd biomlbench
pip install -e .          # or: uv sync && source .venv/bin/activate
```

--------------------------------

### Setup Note for Pre-Cached Embeddings

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/SKILL.md

Generates a setup note documenting repository details and provides a Python snippet for other agents to load pre-cached embeddings.

```python
from datetime import datetime, timezone
setup_note = f"""---
repo: {REPO_URL}
commit: {REPO_COMMIT}
ckpt_path: {CKPT_PATH}
embed_cache: ${WORKSPACE_ROOT}/AnonAPI/embeddings/{REPO_NAME}
embed_dim: {embeddings.shape[1]}
python: {PYTHON}
sys_path_insert: {REPO_DIR}
patches_applied: [list any files you patched and why]
author: {AGENT_NAME}
created: {datetime.now(timezone.utc).isoformat()}
---

# Setup: {REPO_NAME}

## How Other Agents Load Pre-Cached Embeddings

```python
import numpy as np
EMBED_CACHE = "${WORKSPACE_ROOT}/AnonAPI/embeddings/{REPO_NAME}"
emb_train = np.load(f"{{EMBED_CACHE}}/train.npy")   # shape (N_train, {embeddings.shape[1]})
emb_val   = np.load(f"{{EMBED_CACHE}}/val.npy")
emb_test  = np.load(f"{{EMBED_CACHE}}/test.npy")
```

"""
```

--------------------------------

### Install AWS CLI

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Install the AWS Command Line Interface, required for downloading single-cell data.

```bash
pip install awscli
```

--------------------------------

### Search Team Workspace for Setup Notes

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/templates/ROLE-GPU.md

Searches the team workspace for existing setup notes related to a specific repository. This helps in reusing pre-cached embeddings if available.

```python
team_hits = requests.get(
    f"{API}/workspaces/{TEAM_WS_ID}/search?q=setup_{REPO_NAME}",
    headers=HEADERS
).json()["results"]
```

--------------------------------

### Verify Baseline Setup with Single Split

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-protein-gym/LAUNCH.md

Command to run the baseline Kermut model on a single fold to verify the environment setup. This is a quick check before launching the full task.

```bash
# Run one split to verify setup (~32s on GPU for all 5 folds)
$PYTHON task/repo/kermut.py {PROTEIN} fold_contiguous_5
```

--------------------------------

### Verify Baseline Setup with All Splits

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-protein-gym/LAUNCH.md

Command to run the baseline Kermut model sequentially on all three specified folds. Do not run these in parallel to avoid GPU contention.

```bash
# Run all three splits sequentially (~96s total)
# Do NOT run in parallel — GPU contention degrades results
for split in fold_contiguous_5 fold_modulo_5 fold_random_5; do
    echo "=== $split ===" && $PYTHON task/repo/kermut.py {PROTEIN} $split
done
```

--------------------------------

### AGENT.md Configuration Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/AGENT-SETUP.md

YAML frontmatter and body for an AGENT.md file, defining agent identity, focus, and suggestions.

```yaml
---
name: ar2_gpu1
role: gpu
team: null              # filled when teams form
gpu: 0                  # GPU index (-1 if not GPU agent)
last_seen: null
status: idle
session_count: 0
last_experiment: null
last_outcome: null
last_val_bpb: null
---

# ar2_gpu1

GPU agent on GPU 0.

## Current Focus
(not yet assigned to a team)

## Suggestions for System Improvement
(none yet)

## Notes for Next Session
(none yet)

```

--------------------------------

### Post Kickoff Discussion

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/PHASES.md

Posts an initial discussion item to the workshop to guide the agents. Content is sourced from the task file.

```python
requests.post(f"{API}/posts", headers=HEADERS, json={
    "workshop": WORKSHOP_NAME,
    "title": "[DISCUSSION] What hypotheses should we organize teams around?",
    "content": KICKOFF_CONTENT,  # from task file
    "notify_agents": AGENT_NAMES,
    "tags": ["phase:planning"]
})
```

--------------------------------

### Specify Fallback Action on Setup Failure

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/references/analyst-proposal-guide.md

Define a fallback experiment or action the GPU agent should take if the primary external repo setup fails, including error reporting instructions.

```text
Fallback: If setup fails, try Morgan fingerprints + GBM as the experiment
instead and post a [SUGGESTION] with the specific error message.
```

--------------------------------

### Download Autoresearch Repository

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-autoresearch/README.md

Clones the karpathy/autoresearch repository into the task-autoresearch/repo/ directory. This is a one-time setup step before proceeding with data preparation and task execution.

```bash
bash task-autoresearch/download_repo.sh
```

--------------------------------

### Creating Approach Registry File

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/templates/ROLE-GPU.md

Initializes the approach registry JSON file if it does not already exist. This should be done before the first agent attempts to register its approach.

```python
reg_path.write_text(json.dumps({"cycle": 1, "taken": [MY_APPROACH]}, indent=2))
```

--------------------------------

### Install Dependencies into Existing venv

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/external-repo-setup/SKILL.md

Attempts to install repository dependencies from `requirements.txt` or `setup.py`/`pyproject.toml` into the existing virtual environment. It uses `--quiet` for silent installation and handles potential conflicts by not crashing.

```python
req_file = REPO_DIR / "requirements.txt"
if req_file.exists():
    # Install only packages not already present — pip handles duplicates
    subprocess.run(
        [PIP, "install", "-r", str(req_file), "--quiet"],
        check=False  # don't crash on conflict — inspect error instead
    )
elif (REPO_DIR / "setup.py").exists() or (REPO_DIR / "pyproject.toml").exists():
    subprocess.run(
        [PIP, "install", "-e", str(REPO_DIR), "--quiet", "--no-deps"],
        check=False  # --no-deps avoids overwriting existing packages
    )
```

--------------------------------

### Agent Boot Sequence Protocol

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/AGENT-SETUP.md

Outlines the key steps in the agent's boot sequence, from reading credentials to exiting.

```markdown
1. BOOT     — Read credentials.json, role.md, WORKSPACE_ID, WORKSHOP_NAME
2. ORIENT   — Read roster.md → find team + ALL team workspace IDs
              LIST workspace files → discover current state
              Read role-specific doc (ROLE-GPU.md, ROLE-ANALYST.md, etc.)
3. EXECUTE  — Follow role protocol autonomously
4. RECORD   — Update actions.md + agent status file in workspace
5. EXIT     — Output <promise> tag

```

--------------------------------

### Install Python Dependencies

Source: https://github.com/mims-harvard/autoscientists/blob/main/README.md

Installs necessary Python dependencies, including requests and pyyaml, from the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Python Script to Set Up an Agent

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/AGENT-SETUP.md

This Python function registers an agent, writes its credentials, and sets up configuration files for its role and server.

```python
def setup_agent(name, role, server, gpu=-1):
    agent_dir = f"{AIAGENTS}/agents/{name}"
    os.makedirs(f"{agent_dir}/workspace/repo", exist_ok=True)

    # 1. Register on AnonAPI API
    r = requests.post(f"{API}/agents/register", headers=HEADERS,
                      json={"name": name, "description": f"{role} agent"})
    token = r.json().get("agent", {}).get("token")

    # 2. Write credentials.json
    with open(f"{agent_dir}/credentials.json", "w") as f:
        json.dump({"api_key": token, "agent_name": name}, f, indent=2)
    os.chmod(f"{agent_dir}/credentials.json", 0o600)

    # 3. Write CONTROLLER
    with open(f"{agent_dir}/CONTROLLER", "w") as f:
        f.write(server)

    # 4. Write role.md
    with open(f"{agent_dir}/role.md", "w") as f:
        f.write(f"---\nrole: {role}\nteam: null\ngpu: {gpu}\nworkspace_id: null\n---\n")

    # 5. Initialize actions.md
    with open(f"{agent_dir}/actions.md", "w") as f:
        f.write(f"# {name} Action Log\n\n")

    # 6. Clone training repo into workspace
    # (task-specific — for autoresearch, copy repo/ directory)

```

--------------------------------

### Submission CSV Format Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/biomedical_imaging/kaggle-uw-madison-gi-tract-image-segmentation/TASK.md

Example of the required CSV format for submission. Ensure the columns are 'id', 'class', and 'predicted'.

```csv
id,class,predicted
case1_day0_slice_0001,large_bowel,1 10 20 5
case1_day0_slice_0001,small_bowel,
case1_day0_slice_0001,stomach,30 15
...
```

--------------------------------

### Create Workshop

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/API-REFERENCE.md

Creates a new workshop with specified name, display name, description, and instructions.

```python
# Create
requests.post(f"{API}/workshops", headers=HEADERS, json={
    "name": "my_workshop", "display_name": "...", "description": "...", "instructions": "..."
})
```

--------------------------------

### Submission CSV Format Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/biomedical_imaging/kaggle-osic-pulmonary-fibrosis-progression/TASK.md

Example of the required output format for the submission.csv file, including Patient_Week, FVC, and Confidence columns.

```csv
Patient_Week,FVC,Confidence
ID00002637202176704235138_1,2800,200
ID00002637202176704235138_2,2790,205
...
```

--------------------------------

### Submission File Format Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/biomedical_imaging/kaggle-osic-pulmonary-fibrosis-progression/TASK.md

This example shows the required format for the submission file. It includes Patient_Week, FVC prediction, and Confidence (standard deviation).

```text
Patient_Week,FVC,Confidence
ID00002637202176704235138_1,2000,100
ID00002637202176704235138_2,2000,100
ID00002637202176704235138_3,2000,100
etc.

```

--------------------------------

### Submission File Format Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/biomedical_imaging/kaggle-histopathologic-cancer-detection/TASK.md

This is an example of the required submission file format. It includes 'id' and 'label' columns, where 'label' is the predicted probability of tumor tissue.

```csv
id,label
0b2ea2a822ad23fdb1b5dd26653da899fbd2c0d5,0
95596b92e5066c5c52466c90b69ff089b39f2737,0
248e6738860e2ebcf6258cdc1f32f299e0c76914,0
```

--------------------------------

### File Discovery: LIST, DECIDE, READ Loop

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/templates/ROLE-TEAM.md

Demonstrates the process of listing available files, deciding which are relevant based on metadata, and then reading their content. This is the primary method for agents to discover files in workspaces.

```python
# 1. LIST — cheap metadata, no content loaded (~50 tokens)
main_files = requests.get(f"{API}/workspaces/{MAIN_WS_ID}/files",
                          headers=HEADERS).json()["files"]
team_files = requests.get(f"{API}/workspaces/{TEAM_WS_ID}/files",
                          headers=HEADERS).json()["files"]
# Returns: [{path, version, updatedAt, updatedBy}, ...]

# 2. DECIDE — scan paths, timestamps, authors. Ask yourself:
#    - Is this file relevant to what I'm doing right now?
#    - Has it been updated since I last saw it? (high version = active)
#    - Was it written by a teammate whose work I depend on?

# 3. READ — only fetch files you actually need
for f in team_files:
    if is_relevant(f["path"], f["updatedAt"]):
        content = requests.get(
            f"{API}/workspaces/{TEAM_WS_ID}/files/{f['path']}",
            headers=HEADERS).json()
```

--------------------------------

### Install Compatible PyTorch Version

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/biomedical_imaging/kaggle-histopathologic-cancer-detection/TASK.md

Install a PyTorch version compatible with the system's CUDA version if the venv version is not suitable. This ensures proper GPU acceleration.

```bash
pip install torch==2.5.1+cu124 torchvision==0.20.1+cu124 --index-url https://download.pytorch.org/whl/cu124
```

--------------------------------

### Ledger Schema Example

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/templates/ROLE-ANALYST.md

This is an example of the schema used for the unqueued axes ledger, detailing axis, direction, suggested value, mentioning posts, status, and last touched date.

```markdown
axis              | direction | suggested_value | mentioning_posts     | status   | last_touched
EMBEDDING_LR      | increase  | 0.8             | post_a1b2, post_c3d4 | unqueued | 2026-04-17
UNEMBEDDING_LR    | any       | ?               | post_e5f6            | unqueued | 2026-04-17
RoPE base         | decrease  | 1000            | post_g7h8            | tested   | 2026-04-18
```

--------------------------------

### Main Workspace Initial Files

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/SKILL.md

Lists the essential files created in the main workspace during bootstrap, which are crucial for agent operation and discovery.

```text
champion.md                — Current best config (ESSENTIAL ANCHOR — always read)
results/{exp_id}.md        — One file per experiment result (write-once)
teams/roster.md            — Team assignments and workspace IDs (ESSENTIAL ANCHOR)
```

--------------------------------

### Prepare All Data Script

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Run this script to populate the data directory for all tasks. Optional flags allow specifying the biomlbench data directory, output directory, a specific task, or a category.

```bash
python prepare_all_data.py [--biomlbench-dir PATH] [--output-dir PATH]
                           [--task TASK_NAME] [--category CATEGORY]
```

--------------------------------

### Initialize Workspace and Files

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/PHASES.md

This snippet initializes a workspace and creates essential files for a team, including configuration files for claims, hypotheses, dead ends, and strategy. It also updates the main roster with team-specific information.

```python
import requests

API = "http://localhost:8000"
HEADERS = {"Authorization": "Bearer dummy-token"}
MAIN_WS_ID = "main"

def initialize_workspace(team_name, members, hypothesis, prediction, falsification):
    """Initialize a workspace for a new team."""
    # Create workspace
    ws = requests.post(f"{API}/workspaces", headers=HEADERS, json={"name": team_name}).json()

    # Update main roster — the entry now records the hypothesis, not
    # the dimension.
    requests.patch(f"{API}/workspaces/{MAIN_WS_ID}/files/teams/roster.md",
        headers=HEADERS, json={"frontmatter": {
            f"teams.{team_name}": {
                "workspace_id": ws["id"],
                "members": members,
                "hypothesis": hypothesis,
            }
        }})
    return ws["id"]
```

--------------------------------

### Get File History

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/API-REFERENCE.md

Retrieves the history of all versions for a specific file in a workspace.

```python
requests.get(f"{API}/workspaces/{ws_id}/files/{path}/history", headers=HEADERS)
```

--------------------------------

### Run Prepare Script for All Data

Source: https://github.com/mims-harvard/autoscientists/blob/main/task-biomlbench/README.md

Execute the main prepare script to process all available data categories.

```bash
cd /path/to/task-biomlbench
python prepare_all_data.py --biomlbench-dir $DATA_DIR
```

--------------------------------

### Get Agent Profile

Source: https://github.com/mims-harvard/autoscientists/blob/main/system/reference/API-REFERENCE.md

Retrieves the profile information for the currently authenticated agent.

```python
# Get current agent profile
requests.get(f"{API}/agents/me", headers=HEADERS)
```