### Copy Example Configuration File

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

Copy the example configuration file to start customizing your settings.

```bash
cp config.researchclaw.example.yaml config.arc.yaml
```

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

### Setup Development Environment

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/CONTRIBUTING.md

Install the project with development dependencies using pip. Ensure you are in a Python virtual environment.

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

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

### Install Axolotl

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/axolotl.md

Install Axolotl using pip or by cloning the repository and installing from source. Cloning from source is recommended for development.

```bash
pip install axolotl
```

```bash
git clone https://github.com/axolotl-ai-cloud/axolotl.git
cd axolotl && pip install -e .
```

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

### Install PEFT

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/peft.md

Install the PEFT library using pip. This is the first step before using any PEFT functionalities.

```bash
pip install peft
```

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

### Install MetaClaw

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Install MetaClaw using pip or by cloning from source.

```bash
pip install metaclaw
# Or clone from source:
git clone https://github.com/aiming-lab/MetaClaw.git
cd metaclaw && pip install -e .
```

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

### Install a Custom Skill

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Use this command to install a custom skill from a local path. This installation persists across projects.

```bash
researchclaw skills install /path/to/my-skill/
```

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

### Manual Installation of AutoResearchClaw

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

Steps for manually cloning the repository, setting up a virtual environment, and installing the project.

```bash
# 1. Clone the repo
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate       # macOS / Linux
# .venv\Scripts\activate        # Windows (prefer WSL2)

# 3. Install
pip install -e .

# 4. Verify
researchclaw --help
```

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

### Quick Start: Run Pipeline

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

Activate your virtual environment, set your API key, and run the pipeline with a configuration file. This is the most basic way to start the research process.

```bash
source .venv/bin/activate
export OPENAI_API_KEY="sk-xxxx"       # or ANTHROPIC_API_KEY

researchclaw run --config config.arc.yaml --auto-approve
```

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

### Install LLaMA Factory

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/llamafactory.md

Install the LLaMA Factory library using pip or by cloning the repository and installing it in editable mode.

```bash
pip install llamafactory
```

```bash
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory && pip install -e .
```

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

### Install and Run AutoResearchClaw

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Clone the repository, set up a virtual environment, install dependencies, configure the tool, and run a research topic.

```bash
# 1. Clone & install
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Setup (interactive — installs OpenCode beast mode, checks Docker/LaTeX)
researchclaw setup

# 3. Configure
researchclaw init          # Interactive: choose LLM provider, creates config.arc.yaml
# Or manually: cp config.researchclaw.example.yaml config.arc.yaml

# 4. Run
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve
```

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

### Install TRL

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/trl.md

Install the TRL library using pip.

```bash
pip install trl
```

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

### Clone Repository and Install AutoResearchClaw

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Clone the AutoResearchClaw repository, set up a virtual environment, and install the project using pip.

```bash
# Clone the repository
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw

# Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
# .venv\Scripts\activate     # Windows

# Install
pip install -e .
```

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

### Start MetaClaw Proxy Server

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Start the MetaClaw proxy server for full skill matching and session tracking. This is optional.

```bash
metaclaw start --mode skills_only --port 30000
# Or use the provided script:
bash scripts/metaclaw_start.sh
```

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

### Co-Pilot Workflow Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Illustrates the interactive workflow of the Co-Pilot mode, showing user interventions and AI responses during critical research stages.

```bash
You: researchclaw run --topic "Quantum noise as neural network regularization" --mode co-pilot

Pipeline runs Stages 1-7 automatically...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Stage 08: HYPOTHESIS_GEN                            │
  │  Post-stage review                                          │
  │                                                             │
  │  Hypotheses mentioned: 3                                    │
  │  Novelty score: 0.72 (moderate)                             │
  │                                                             │
  │  [a] Approve  [r] Reject  [e] Edit  [c] Collaborate         │
  │  [i] Inject guidance  [v] View output  [q] Abort            │
  └─────────────────────────────────────────────────────────────┘

You: c  (start collaborative chat)
You: Hypothesis 3 is interesting but needs Dropout/Label Smoothing as baselines
AI:  Updated — added Dropout, Label Smoothing, MixUp, CutMix as baselines...
You: approve

Pipeline continues with your refined hypothesis...
```

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

### Install COBRApy

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/external/agents/Biology-Agent/skills/gsmm-builder/references/cobra_reference.md

Install COBRApy using pip or conda. Use `pip install cobra[all]` to include optional solvers.

```bash
pip install cobra
```

```bash
pip install cobra[all]       # includes optional solvers
```

```bash
conda install -c conda-forge cobra
```

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

### AutoResearchClaw Configuration Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

Example configuration for AutoResearchClaw, covering project settings, research topic, LLM provider, and experiment parameters.

```yaml
# === Project ===
project:
  name: "my-test"
  mode: "full-auto"

# === Research Topic — describe your idea in English ===
research:
  topic: "Your research idea in 1-2 sentences"
  domains:
    - "machine-learning"     # Options: nlp, cv, rl, graph-learning, etc.

# === LLM — use the strongest model you have access to! ===
#
# Option 1: OpenAI (GPT-5.4 recommended)
llm:
  provider: "openai-compatible"
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-5.4"              # Best available
  fallback_models:
    - "gpt-5.1"
    - "gpt-4.1"

# Option 2: Anthropic Claude (Claude Opus 4.6 recommended)
# llm:
#   provider: "openai-compatible"
#   base_url: "https://api.anthropic.com/v1"
#   api_key_env: "ANTHROPIC_API_KEY"
#   primary_model: "claude-opus-4-6"
#   fallback_models:
#     - "claude-sonnet-4-6"

# === Experiment ===
experiment:
  mode: "sandbox"                # sandbox = local execution (recommended)
  time_budget_sec: 600           # Max seconds per experiment run
  max_iterations: 10
  metric_key: "primary_metric"
  metric_direction: "minimize"   # or "maximize"
```

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

### Tokenization and Data Preparation

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/transformers_training.md

Load a tokenizer and define a function to tokenize text examples. Use dataset.map() to apply the tokenization function in batches.

```python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

def tokenize_function(examples):
    return tokenizer(
        examples["text"],
        padding="max_length",
        truncation=True,
        max_length=512,
    )

tokenized_ds = dataset.map(tokenize_function, batched=True)

```

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

### Install AIDE ML

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/baseline/README.md

Clones the AIDE ML repository and sets up a conda environment with necessary Python packages. Includes a note on patching the backend to read OPENAI_BASE_URL from the environment.

```bash
git clone https://github.com/WecoAI/aideml.git \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/aideml

# Create conda env on /playpen2 (large dependency tree)
conda create -p /playpen2/shiqiu/arc_bench/baselines/aide_ml/conda_env python=3.11 -y
PIP_CACHE_DIR=/playpen2/shiqiu/arc_bench/baselines/aide_ml/pip_cache \
  /playpen2/shiqiu/arc_bench/baselines/aide_ml/conda_env/bin/pip install -e \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/aideml

# Patch the AIDE backend to read OPENAI_BASE_URL from env (one-line)
# in baseline/external/aideml/aide/backend/backend_openai.py:
#   OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
```

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

### Install and Run ResearchClaw CLI

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/RESEARCHCLAW_AGENTS.md

Installs the ResearchClaw package and provides a basic command to run the pipeline with a specified topic and auto-approval.

```bash
pip install -e .

cp config.researchclaw.example.yaml config.yaml
# Set llm.base_url, llm.api_key, experiment.mode

researchclaw run --topic "Your topic" --auto-approve
```

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

### Start HITL Mode CLI

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Initiates the AutoResearchClaw pipeline with the Human-in-the-Loop Co-Pilot mode enabled.

```bash
# Start with HITL mode
researchclaw run --topic "..." --mode co-pilot
```

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

### Method-to-Claim Map Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/external/agents/stat_research_agent/skills/statistical-method-design/SKILL.md

Illustrates how to map a proposed statistical method to specific claims, including expected evidence and theoretical targets. Use this structure to justify the method's relevance and expected performance.

```yaml
method_to_claim_map:
  proposed_method:
    claims: [C1, C2]
    expected_evidence: "lower risk under stress condition"
    theory_target: "consistency under assumptions A1-A3"
```

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

### Claude Code Interaction Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Demonstrates a typical interaction with Claude Code, where it reads project context and runs the pipeline to return results.

```text
You: Research the impact of attention mechanisms on speech recognition
Claude: [Reads project context, runs the pipeline, returns results]
```

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

### Install AI Scientist v2

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/baseline/README.md

Clones the AI Scientist v2 repository and sets up a Python virtual environment, installing dependencies from its requirements file.

```bash
git clone https://github.com/SakanaAI/AI-Scientist-v2.git \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/AI-Scientist-v2

python -m venv /playpen2/shiqiu/arc_bench/ais_v2_venv
/playpen2/shiqiu/arc_bench/ais_v2_venv/bin/pip install -r \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/AI-Scientist-v2/requirements.txt
```

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

### Causal LM Training Setup

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/transformers_training.md

Configure the Trainer for Causal Language Modeling (GPT-style). Use DataCollatorForLanguageModeling with mlm=False.

```python
from transformers import AutoModelForCausalLM, DataCollatorForLanguageModeling

model = AutoModelForCausalLM.from_pretrained("gpt2")
data_collator = DataCollatorForLanguageModeling(
    tokenizer=tokenizer,
    mlm=False,  # causal LM, not masked LM
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized_ds,
    data_collator=data_collator,
)

```

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

### SFTTrainer for Supervised Fine-Tuning

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/trl.md

Example of using SFTTrainer for supervised fine-tuning. Requires a model, tokenizer, and dataset. SFTConfig inherits from TrainingArguments and allows customization of training parameters and dataset formatting.

```python
from trl import SFTTrainer, SFTConfig
from transformers import AutoModelForCausalLM, AutoTokenizer
from datasets import load_dataset

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-3B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-3B")
dataset = load_dataset("json", data_files="train.jsonl", split="train")

# SFTConfig inherits from TrainingArguments
training_args = SFTConfig(
    output_dir="./output",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-5,
    max_seq_length=1024,
    logging_steps=10,
    save_strategy="epoch",
    bf16=True,
    gradient_checkpointing=True,
    # Dataset formatting
    dataset_text_field="text",           # column name for text
    packing=True,                         # pack short samples for efficiency
)

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    args=training_args,
)
trainer.train()
trainer.save_model("./final_model")
```

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

### Example Stage Entry in Prompt Bank

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

Illustrates a typical stage entry within a custom prompt bank module, showing the structure for 'system' and 'user' prompts with placeholder substitution.

```python
STAGES["hypothesis_gen"] = {
    "system": (
        "You formulate testable HEP-phenomenology hypotheses that address "
        "gaps NOT covered by existing experimental results. Every "
        "hypothesis must be:\n"
        "1. NOVEL: Not replicating a published recast or an existing "
        "collaboration exclusion.\n"
        "..."
    ),
    "user": (
        "Generate at least 2 falsifiable HEP-ph hypotheses from the "
        "synthesis below.\n"
        "For each hypothesis provide:\n"
        "- **Hypothesis statement**: A clear claim in physics language, "
        "  naming the BSM model / operator and the observable.\n"
        "..."
        "{domain_context}"
        "Synthesis:\n{synthesis}"
    ),
}
```

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

### HITL Configuration Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Defines Human-in-the-Loop settings in the AutoResearchClaw configuration file, including mode, cost budget, notifications, and stage-specific policies.

```yaml
# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # Pause when cost exceeds budget (0 = no limit)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24h default wait
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # Per-stage custom policies (optional, for 'custom' mode)
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }
```

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

### Install AgentLaboratory

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/baseline/README.md

Clones the AgentLaboratory repository and sets up a conda environment, installing dependencies from its requirements file. Mentions a patch for ARC-Bench environment variable support.

```bash
git clone https://github.com/SamuelSchmidgall/AgentLaboratory.git \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/AgentLaboratory

conda create -p /playpen2/shiqiu/arc_bench/baselines/agent_lab/conda_env python=3.11 -y
/playpen2/shiqiu/arc_bench/baselines/agent_lab/conda_env/bin/pip install -r \
    /path/to/AutoResearchClaw/experiments/arc_bench/baseline/external/AgentLaboratory/requirements.txt

# Apply ARC-Bench env-var patch (AGENTLAB_RESEARCH_DIR support)
# See `experiments/framework_comparison/patches/AgentLab_research_dir_env.diff`
# in the repo history if you need the original patch context.
```

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

### DPOTrainer for Direct Preference Optimization

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/trl.md

Example of using DPOTrainer for direct preference optimization. Requires a DPOConfig and a dataset with 'prompt', 'chosen', and 'rejected' columns, or 'chosen' and 'rejected' as full conversations. The ref_model can be None for implicit reference via PEFT.

```python
from trl import DPOTrainer, DPOConfig

training_args = DPOConfig(
    output_dir="./dpo_output",
    num_train_epochs=1,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=8,
    learning_rate=5e-7,
    beta=0.1,                  # KL penalty coefficient
    max_length=1024,
    max_prompt_length=512,
    bf16=True,
    gradient_checkpointing=True,
    loss_type="sigmoid",       # "sigmoid" (default), "hinge", "ipo"
)

# Dataset must have columns: "prompt", "chosen", "rejected"
# OR "chosen" and "rejected" as full conversations
trainer = DPOTrainer(
    model=model,
    ref_model=None,            # None = use implicit reference (PEFT)
    train_dataset=dpo_dataset,
    tokenizer=tokenizer,
    args=training_args,
)
trainer.train()
```

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

### PPOTrainer for Proximal Policy Optimization (RLHF)

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/trl.md

Example of using PPOTrainer for Proximal Policy Optimization in RLHF. Requires a PPOConfig, a model with a value head, tokenizer, and dataset. The training loop involves generating responses, calculating rewards, and stepping the trainer.

```python
from trl import PPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead

config = PPOConfig(
    model_name="Qwen/Qwen2.5-3B",
    learning_rate=1.41e-5,
    batch_size=16,
    mini_batch_size=4,
    ppo_epochs=4,
    gradient_accumulation_steps=1,
)

model = AutoModelForCausalLMWithValueHead.from_pretrained("Qwen/Qwen2.5-3B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-3B")

trainer = PPOTrainer(
    config=config,
    model=model,
    tokenizer=tokenizer,
    dataset=dataset,
)

# Training loop
for batch in trainer.dataloader:
    query_tensors = batch["input_ids"]
    response_tensors = trainer.generate(query_tensors, max_new_tokens=128)
    rewards = [reward_model(q, r) for q, r in zip(query_tensors, response_tensors)]
    stats = trainer.step(query_tensors, response_tensors, rewards)
```

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

### Build and Run ResearchClaw in Docker Mode

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

This sequence of commands is for advanced users with an NVIDIA GPU and Docker installed. It covers building the experiment image, configuring the project for Docker mode, and running the experiment.

```bash
# 1. Build the experiment image
docker build -t researchclaw/experiment:latest researchclaw/docker/

# 2. Update config.arc.yaml:
#   experiment:
#     mode: "docker"
#     docker:
#       gpu_enabled: true
#       memory_limit_mb: 8192
#       network_policy: "setup_only"  # recommended default

# 3. Run
researchclaw run --config config.arc.yaml --auto-approve
```

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

### LLaMA Factory Training Configuration (YAML)

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/llamafactory.md

Example YAML configuration for fine-tuning a model using LLaMA Factory, covering model, method, dataset, training, evaluation, logging, and quantization parameters.

```yaml
### Model
model_name_or_path: Qwen/Qwen2.5-3B
trust_remote_code: true

### Method (LoRA)
stage: sft                    # sft, pt (pretrain), rm, ppo, dpo, kto, orpo
do_train: true
finetuning_type: lora         # lora, freeze, full
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target: all              # "all" for all linear, or comma-separated names

### Dataset
dataset: alpaca_en            # registered dataset name or custom path
template: qwen                # chat template: qwen, llama3, mistral, chatglm, etc.
cutoff_len: 1024
preprocessing_num_workers: 8

### Training
output_dir: ./output
num_train_epochs: 3.0
per_device_train_batch_size: 4
gradient_accumulation_steps: 4
learning_rate: 2.0e-5
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
gradient_checkpointing: true

### Evaluation
val_size: 0.05
per_device_eval_batch_size: 8
eval_strategy: steps
eval_steps: 500

### Logging
logging_steps: 10
save_steps: 500
save_total_limit: 3
report_to: none

### Quantization (QLoRA)
quantization_bit: 4           # 4 or 8
quantization_method: bitsandbytes  # bitsandbytes, gptq, awq

```

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

### One-time Environment Setup for Autoclaw and AI-Scientist-v2

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/RUN_GUIDE.md

Sets up separate Conda and Python virtual environments for autoclaw and AI-Scientist-v2, including installing dependencies and applying necessary patches.

```bash
# autoclaw (root repo)
conda create -n autoclaw python=3.11 -y
conda activate autoclaw
pip install -e .        # installs `researchclaw` CLI
pip install -r requirements.txt

# AI-Scientist-v2 baseline — separate venv to keep deps isolated
cd /playpen2/shiqiu/arc_bench
python3.11 -m venv ais_v2_venv
source ais_v2_venv/bin/activate
pip install -r <path-to-repo>/experiments/framework_comparison/external/AI-Scientist-v2/requirements.txt
# Apply the /v1/responses patch so gpt-5.x codex works through the proxy
cd <path-to-repo>/experiments/framework_comparison/external/AI-Scientist-v2
git apply <path-to-repo>/experiments/framework_comparison/patches/ai_scientist_v2_responses_api.patch
```

```bash
git clone https://github.com/SakanaAI/AI-Scientist-v2.git \
  experiments/framework_comparison/external/AI-Scientist-v2
```

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

### AutoResearchClaw Project Configuration

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Defines the project's name and operational mode. Use 'docs-first' for initial setup, 'semi-auto' for guided research, or 'full-auto' for autonomous operation.

```yaml
project:
  name: "my-research"
  mode: "docs-first"
```

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

### Minimum Viable New Domain Setup

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

This reference lists the essential files and configurations needed to set up a new domain integration. It includes the domain-specific YAML profile, adapter Python files, prompt adapter registration, keyword rules, and testing procedures.

```text
1. researchclaw/domains/profiles/<id>.yaml         — write the YAML
2. researchclaw/domains/adapters/<id>.py           — copy biology.py, edit
3. researchclaw/domains/adapters/__init__.py       — import + __all__
   researchclaw/domains/prompt_adapter.py          — add to _build_adapter_registry
4. researchclaw/domains/detector.py:_KEYWORD_RULES — append your tuple
5. pytest tests/test_prompt_bank_parity.py         — must pass (no-op
                                                      unless you added a bank)
6. python -m researchclaw run --profile <id> ...   — smoke test
```

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

### Initialize and Use Trainer

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/transformers_training.md

Instantiate the Trainer with the model, arguments, datasets, and optional components like tokenizer, metrics, and data collator. Then, call train(), evaluate(), and save_model().

```python
from transformers import Trainer, AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "bert-base-uncased", num_labels=2
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=train_ds,
    eval_dataset=eval_ds,
    tokenizer=tokenizer,
    compute_metrics=compute_metrics,     # optional metric function
    data_collator=data_collator,         # optional custom collator
)

# Train
train_result = trainer.train()

# Evaluate
metrics = trainer.evaluate()

# Save
trainer.save_model("./best_model")

```

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

### Implement MyDomainPromptAdapter

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

Inherit from PromptAdapter and implement methods to return PromptBlocks for different research stages. Empty fields fall back to defaults.

```python
# researchclaw/domains/adapters/my_domain.py
"""My-domain prompt adapter."""
from __future__ import annotations
from typing import Any
from researchclaw.domains.prompt_adapter import PromptAdapter, PromptBlocks


class MyDomainPromptAdapter(PromptAdapter):
    """Adapter for <description of domain>. """

    # ── Stage 11 (code generation) ──────────────────────────────────────
    def get_code_generation_blocks(self, context: dict[str, Any]) -> PromptBlocks:
        # Return PromptBlocks() (all empty) if you have a full prompt bank
        # in researchclaw/prompts/<id>.py — the bank already covers this
        # stage natively. (HEPPhPromptAdapter at hep_ph.py:24-25 does this.)
        #
        # If you don't have a bank, the GenericPromptAdapter pattern is to
        # populate the four common blocks from DomainProfile fields:
        domain = self.domain
        return PromptBlocks(
            compute_budget=domain.compute_budget_guidance or "",
            dataset_guidance=domain.dataset_guidance or "",
            hp_reporting=domain.hp_reporting_guidance or "",
            code_generation_hints=domain.code_generation_hints or "",
            output_format_guidance=(
                'Output results to results.json:\n'
                '{\"conditions\": {\"method\": {\"metric\": value}}, '
                '\"metadata\": {\"domain\": \"my_domain\"}}'
            ),
        )

    # ── Stage 10 (experiment design) ────────────────────────────────────
    def get_experiment_design_blocks(self, context: dict[str, Any]) -> PromptBlocks:
        domain = self.domain
        design_context = (
            f"This is a **{domain.display_name}** experiment.\n\n"
            "Key principles:\n"
            "1. <first principle>\n"
            "2. <use canonical metric M>\n"
            "3. <compare against established baselines B1, B2>\n"
        )
        return PromptBlocks(
            experiment_design_context=design_context,
            statistical_test_guidance=(
                "Use <test family> for significance; apply <correction> "
                "for multiple comparisons."
            ),
        )

    # ── Stage 13 (result analysis) ──────────────────────────────────────
    def get_result_analysis_blocks(self, context: dict[str, Any]) -> PromptBlocks:
        return PromptBlocks(
            result_analysis_hints=(
                "My-domain result analysis:\n"
                "- Report <metric A>, <metric B>, runtime\n"
                "- Distinguish primary vs secondary findings\n"
            ),
        )

    # ── Stage 22 (export / publish) ─────────────────────────────────────
    def get_export_publish_blocks(self, context: dict[str, Any]) -> PromptBlocks:
        # Used when domain has its own LaTeX template and final-pass
        # formatting rules. HEP example: hep_ph.py:33-44.
        guidance = (
            "This is a <my_domain> manuscript; the export pass must "
            "preserve <domain conventions>. Do NOT insert "
            "<inappropriate template artifacts>."
        )
        return PromptBlocks(
            export_publish_guidance=guidance,
            preferred_template="my_template",   # registered in
                                                #   templates/conference.py
        )

    # ── Blueprint hint (called from blueprint stage) ────────────────────
    # Inherits the default from PromptAdapter.get_blueprint_context (lines
    # 87-105), which auto-renders typical_file_structure + core_libraries
    # + code_generation_hints from the YAML. Override only if you need
    # something dynamic.

```

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

### Configure TrainingArguments

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/transformers_training.md

Set key parameters for training, including epochs, batch size, optimizer, learning rate, and precision. Use bf16=True on Ampere+ GPUs for better performance.

```python
from transformers import TrainingArguments

args = TrainingArguments(
    output_dir="./output",
    # Training
    num_train_epochs=3,
    per_device_train_batch_size=8,
    per_device_eval_batch_size=16,
    gradient_accumulation_steps=4,      # effective batch = 8 * 4 = 32
    gradient_checkpointing=True,         # saves memory at ~20% speed cost
    # Optimizer
    learning_rate=2e-5,
    weight_decay=0.01,
    warmup_ratio=0.1,                    # or warmup_steps=100
    lr_scheduler_type="cosine",          # "linear", "cosine", "constant"
    optim="adamw_torch",                 # "adamw_torch", "adamw_8bit", "paged_adamw_8bit"
    # Precision
    bf16=True,                           # bfloat16 (Ampere+ GPUs)
    # fp16=True,                         # float16 (older GPUs)
    # Logging
    logging_steps=10,
    logging_strategy="steps",
    report_to="none",                    # "wandb", "tensorboard", "none"
    # Saving
    save_strategy="epoch",
    save_total_limit=2,
    load_best_model_at_end=True,
    metric_for_best_model="eval_loss",
    # Evaluation
    eval_strategy="epoch",
    # Other
    dataloader_num_workers=4,
    remove_unused_columns=True,
    seed=42,
    max_grad_norm=1.0,
)

```

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

### Verify Installation with Pytest

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/website/getting-started.html

Run the test suite using pytest to verify that your installation of AutoResearchClaw is successful and all components are working correctly.

```bash
python -m pytest tests/ -v
```

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

### Registering a New Domain in Prompt Manager

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

Shows how to add a new domain to the list of supported domains in the prompt manager configuration.

```python
SUPPORTED_DOMAINS = ("ml", "hep_ph", "my_domain")
```

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

### Cost Budget Alert Example

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/HITL_GUIDE.md

Example of a cost budget alert message indicating the current spending and percentage of the budget reached.

```text
Cost budget alert: Cost: $42.50 / $50.00 [████████████████░░░░] 85%
```

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

### Install Python Dependencies

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/website/getting-started.html

Install the researchclaw package and its dependencies using pip. This command ensures all necessary libraries are available for the tool to function.

```bash
pip install -e .
```

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

### Run All Quantum Topics

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/config/quantum/README.md

Execute the benchmark for all topics within the quantum domain. This command is used for comprehensive evaluation.

```bash
python experiments/arc_bench/scripts/run_bench.py \
  --mode rc_full \
  --domain quantum \
  --runs 1
```

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

### Install and Run AutoResearchClaw (Autonomous Mode)

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Installs the AutoResearchClaw package and initiates a fully autonomous research paper generation process. This mode requires no human intervention after the initial command.

```bash
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve
```

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

### MetaClaw Installation and Configuration

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

Install MetaClaw using pip and enable it in your AutoResearchClaw configuration file. The configuration includes options for enabling the bridge, setting proxy and skills directories, and defining fallback behavior.

```bash
pip install metaclaw
```

```yaml
# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # MetaClaw proxy (optional)
  skills_dir: "~/.metaclaw/skills"          # Where skills are stored
  fallback_url: "https://api.openai.com/v1" # Direct LLM fallback
  fallback_api_key: ""                      # API key for fallback URL
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # Convert warnings + errors
    max_skills_per_run: 3
```

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

### Verify AutoResearchClaw Installation

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Check if the researchclaw CLI is available and validate your configuration settings.

```bash
# Check the CLI is available
researchclaw --help

# Validate your configuration
researchclaw validate --config config.yaml
```

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

### Adding a New Quantum Topic Configuration

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/experiments/arc_bench/config/quantum/README.md

Steps to add a new quantum topic, including updating configuration files and scripts. Ensure consistency across manifest and judge scripts.

```bash
# 1. Add entry to topics.yaml
# 2. Write manifests/Q11.yaml
# 3. Write rubrics/Q11.json
# 4. Ensure scripts/prepare_run.py and scripts/judge.py map Q -> quantum
# 5. Run end-to-end with --runs 1 for initial testing
```

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

### Get All Substructure Matches

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/skills/builtin/domain/chemistry-rdkit/SKILL.md

Retrieve all occurrences of a SMARTS pattern within a molecule using `mol.GetSubstructMatches`.

```python
mol.GetSubstructMatches(pattern)
```

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

### Update and Install AutoResearchClaw

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/TESTER_GUIDE.md

Always pull the latest code before testing and re-install to ensure all changes are picked up.

```bash
cd AutoResearchClaw
git pull origin main
pip install -e .    # Re-install to pick up changes
```

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

### Loading Custom Domain Prompt Bank

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

Demonstrates the logic for loading a specific domain's prompt bank, with fallbacks to default or ML banks.

```python
def _load_bank(domain: str) -> tuple[...]:
    if domain == "hep_ph":
        from researchclaw.prompts import hep as _bank
    elif domain == "my_domain":
        from researchclaw.prompts import my_domain as _bank
    else:
        from researchclaw.prompts import ml as _bank
    ...
```

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

### Dataset Formats (JSON)

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/llamafactory.md

Examples of supported dataset formats for LLaMA Factory, including Alpaca and ShareGPT formats.

```json
// Alpaca format
{"instruction": "Translate to French", "input": "Hello", "output": "Bonjour"}

// ShareGPT format
{"conversations": [
  {"from": "human", "value": "Hello"},
  {"from": "gpt", "value": "Hi there!"}
]}

```

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

### Create a Custom Skill File

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/README.md

To load a custom skill by dropping a file into the project, create a SKILL.md file within the .claude/skills/<skill-name> directory. This file requires YAML frontmatter including name, description, trigger-keywords, and applicable-stages.

```bash
mkdir -p .claude/skills/my-custom-skill
# Then create a SKILL.md with YAML frontmatter (name, description, trigger-keywords, applicable-stages)
```

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

### PyTorch Training Loop Boilerplate

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/skills/builtin/tooling/pytorch-training/SKILL.md

Essential imports and setup for a standard PyTorch training loop, including reproducibility settings.

```python
import torch
import torch.nn as nn
from torch.utils.data import DataLoader

# Reproducibility
torch.manual_seed(seed)
torch.cuda.manual_seed_all(seed)
torch.backends.cudnn.deterministic = True

# Training loop
model.train()
for epoch in range(num_epochs):
    for batch in train_loader:
        optimizer.zero_grad(set_to_none=True)
        loss = criterion(model(batch['input']), batch['target'])
        loss.backward()
        torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
        optimizer.step()
    scheduler.step()
```

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

### Compile LaTeX Paper

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Use this command to compile the generated LaTeX paper into a PDF for submission. Ensure you have a LaTeX distribution installed.

```bash
pdflatex stage-22/paper.tex
```

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

### Integration with PEFT/LoRA

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/trl.md

Example of integrating PEFT/LoRA with TRL trainers. A LoraConfig can be passed directly to the trainer, which will automatically wrap the model with LoRA.

```python
from peft import LoraConfig

peft_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    task_type="CAUSAL_LM",
)

# Pass peft_config to any TRL trainer
trainer = SFTTrainer(
    model=model,
    peft_config=peft_config,   # automatically wraps model with LoRA
    ...,
)
```

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

### Implement run_project for SandboxProtocol Parity

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/DOMAIN_INTEGRATION_GUIDE.md

Implement the `run_project` method for agent-based sandboxes to ensure compatibility with the SandboxProtocol. This method dispatches to `run()` after locating the plan markdown.

```python
def run_project(self, project_dir, *, entry_point="main.py",
                timeout_sec=300, args=None, env_overrides=None):
    del entry_point, args, env_overrides  # SandboxProtocol parity only
    for cand in (project_dir / "REPAIR_PROMPT.md",
                 project_dir / _PROMPT_FILENAME,
                 self.workdir / _PROMPT_FILENAME):
        if cand.is_file():
            return self.run(cand.read_text(encoding="utf-8"),
                            timeout_sec=timeout_sec)
    return SandboxResult(returncode=-1, stdout="",
                         stderr="no plan found", elapsed_sec=0.0,
                         metrics={}, timed_out=False)
```

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

### Save, Load, and Merge LoRA Adapters

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/peft.md

Demonstrates how to save only the LoRA adapter weights, load them onto a base model, and merge the adapter into the base model for deployment.

```python
# Save adapter only (small file)
model.save_pretrained("./lora_adapter")

# Load adapter
from peft import PeftModel
base_model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-3B")
model = PeftModel.from_pretrained(base_model, "./lora_adapter")

# Merge adapter into base model (for deployment)
merged_model = model.merge_and_unload()
merged_model.save_pretrained("./merged_model")
```

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

### Configure and Apply QLoRA

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/peft.md

Set up 4-bit quantization using BitsAndBytesConfig and apply it to a model before applying LoRA. This is useful for reducing memory usage during fine-tuning.

```python
from transformers import BitsAndBytesConfig
import torch

# 4-bit quantization config
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",          # "nf4" or "fp4"
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,      # nested quantization
)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-3B",
    quantization_config=bnb_config,
    device_map="auto",
)

# Then apply LoRA on top
from peft import prepare_model_for_kbit_training
model = prepare_model_for_kbit_training(model)
model = get_peft_model(model, lora_config)
```

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

### Axolotl Training Configuration (YAML)

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/researchclaw/data/framework_docs/axolotl.md

A comprehensive YAML configuration for training LLMs with Axolotl, covering model loading, QLoRA settings, dataset configuration, training parameters, memory optimization, and logging.

```yaml
base_model: Qwen/Qwen2.5-3B
model_type: AutoModelForCausalLM
tokenizer_type: AutoTokenizer
trust_remote_code: true

# Load in 4-bit (QLoRA)
load_in_4bit: true
adapter: qlora                 # qlora, lora, or omit for full fine-tune
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target_linear: true       # target all linear layers

# Dataset
datasets:
  - path: my_data.jsonl
    type: alpaca               # alpaca, sharegpt, completion, etc.
    # OR custom format:
    # type:
    #   field_instruction: instruction
    #   field_input: input
    #   field_output: output
    #   format: "{instruction}\n{input}"

# Training
sequence_len: 2048
sample_packing: true           # pack short sequences together
pad_to_sequence_len: true

num_epochs: 3
micro_batch_size: 4
gradient_accumulation_steps: 4
learning_rate: 2e-5
lr_scheduler: cosine
warmup_ratio: 0.1
optimizer: paged_adamw_8bit

# Precision
bf16: auto                     # auto-detect GPU capability
tf32: true

# Memory optimization
gradient_checkpointing: true
flash_attention: true          # use flash attention 2

# Logging & saving
logging_steps: 10
save_strategy: steps
save_steps: 500
save_total_limit: 3
output_dir: ./output

# Evaluation
val_set_size: 0.05
eval_steps: 500

# Weights & Biases (optional)
wandb_project: my-project
wandb_run_id:

```

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

### Re-run Specific Stages

Source: https://github.com/aiming-lab/autoresearchclaw/blob/main/docs/integration-guide.md

Execute only the paper writing stages of the pipeline. Use the `--from-stage` flag to specify the starting point for the re-run.

```bash
# Re-run just the paper writing stages
researchclaw run -c config.yaml --from-stage PAPER_OUTLINE --auto-approve
```