config.researchclaw.example.yaml

project:
  name: "my-research"
  mode: "full-auto"

research:
  topic: "Your research topic here"
  domains:
    - "machine-learning"
  daily_paper_count: 10
  quality_threshold: 4.0

runtime:
  timezone: "America/New_York"
  max_parallel_tasks: 3
  approval_timeout_hours: 12
  retry_limit: 2

notifications:
  channel: "console"
  target: ""
  on_stage_start: true
  on_stage_fail: true
  on_gate_required: true

knowledge_base:
  backend: "markdown"
  root: "docs/kb"

openclaw_bridge:
  use_cron: false
  use_message: false
  use_memory: false
  use_sessions_spawn: false
  use_web_fetch: false
  use_browser: false

llm:
  provider: "openai-compatible"
  base_url: "https://api.openai.com/v1"
  wire_api: "chat_completions"  # Set to "responses" for Responses-only gateways
  api_key_env: "OPENAI_API_KEY"
  api_key: ""
  primary_model: "gpt-4o"
  fallback_models:
    - "gpt-4.1"
    - "gpt-4o-mini"
  # --- MiniMax provider example (global OpenAI-compatible endpoint) ---
  # provider: "minimax-global"
  # base_url: "https://api.minimax.io/v1"
  # api_key_env: "MINIMAX_API_KEY"
  # primary_model: "MiniMax-M3"
  # fallback_models:
  #   - "MiniMax-M2.7"
  # Other endpoint presets:
  #   minimax: https://api.minimaxi.com/v1
  #   minimax-anthropic: https://api.minimax.io/anthropic
  #   minimax-anthropic-cn: https://api.minimaxi.com/anthropic
  # Anthropic-compatible presets require: pip install "researchclaw[anthropic]"
  # --- Atlas Cloud provider example ---
  # provider: "atlascloud"
  # api_key_env: "ATLASCLOUD_API_KEY"
  # primary_model: "deepseek-ai/deepseek-v4-pro"
  # fallback_models:
  #   - "deepseek-ai/deepseek-v4-flash"
  # --- Ollama (local) example ---
  # provider: "ollama"
  # base_url: "http://localhost:11434/v1"
  # api_key_env: ""
  # api_key: "ollama"
  # primary_model: "llama3.2"
  # fallback_models:
  #   - "mistral"

literature_search:
  # Stage 4 academic search backends. Defaults preserve the current
  # OpenAlex -> Semantic Scholar -> arXiv order.
  sources:
    - "openalex"
    - "semantic_scholar"
    - "arxiv"
  max_results_per_query: 40
  inter_query_delay_sec: 1.5
  openalex_email: "researchclaw@users.noreply.github.com"
  openalex_api_key_env: "OPENALEX_API_KEY"
  openalex_api_key: ""
  s2_api_key_env: "S2_API_KEY"
  s2_api_key: ""

security:
  hitl_required_stages: [5, 9, 20]
  allow_publish_without_approval: false
  redact_sensitive_logs: true

experiment:
  # ★ mode 决定实验结果的真实性
  #   "sandbox"   — 在本地沙盒中实际执行生成的 Python 代码，产出真实实验数据
  #   "docker"    — 在 Docker 容器中执行，支持 GPU 直通、依赖自动安装、内存隔离
  #   "simulated" — 不执行代码，使用公式生成假数据（仅用于框架开发调试，不应用于论文生成）
  mode: "sandbox"
  time_budget_sec: 300
  max_iterations: 10
  metric_key: "primary_metric"
  metric_direction: "minimize"
  sandbox:
    # Use ".venv/Scripts/python.exe" on Windows
    python_path: ".venv/bin/python3"
    gpu_required: false
    max_memory_mb: 4096
  # Docker sandbox settings (only used when mode: "docker")
  # Build image first: docker build -t researchclaw/experiment:latest researchclaw/docker/
  docker:
    image: "researchclaw/experiment:latest"
    gpu_enabled: true
    # gpu_device_ids: [0]        # empty = all GPUs
    memory_limit_mb: 8192
    network_policy: "setup_only"  # none | setup_only | pip_only | full
    # pip_pre_install: ["torchdiffeq", "einops"]
    auto_install_deps: true
    shm_size_mb: 2048
    keep_containers: false
  ssh_remote:
    host: ""                # SSH hostname or IP
    user: ""                # SSH username (default: current user)
    port: 22                # SSH port
    key_path: ""            # Path to private key (default: ~/.ssh/id_rsa)
    gpu_ids: []             # e.g. [0, 1] for CUDA_VISIBLE_DEVICES
    remote_workdir: "/tmp/researchclaw_experiments"
    remote_python: "python3"
    setup_commands: []      # e.g. ["source ~/venv/bin/activate", "pip install torch"]
    # Docker-over-SSH (most secure remote execution)
    use_docker: false       # Set true to run experiments inside Docker on remote host
    docker_image: "researchclaw/experiment:latest"
    docker_network_policy: "none"   # none | full
    docker_memory_limit_mb: 8192
    docker_shm_size_mb: 2048
  # OpenCode Beast Mode — external AI coding agent for complex experiments
  # Install: npm i -g opencode-ai@latest  (or use `researchclaw setup`)
  opencode:
    enabled: true                # Master switch (default: true)
    auto: true                   # Auto-trigger without confirmation (default: true)
    complexity_threshold: 0.2    # 0.0-1.0 — higher = only trigger on complex experiments
    model: ""                    # Override model (empty = use llm.primary_model)
    timeout_sec: 600             # Max seconds for OpenCode generation
    max_retries: 1               # Retry count on failure
    workspace_cleanup: true      # Remove temp workspace after collection

# ============================================================================
# SSH Remote Examples
# ============================================================================
#
# 1. Lab server (bare Python, basic sandboxing):
#   experiment:
#     mode: "ssh_remote"
#     ssh_remote:
#       host: "gpu-server.lab.edu"
#       user: "researcher"
#       key_path: "~/.ssh/id_rsa"
#       gpu_ids: [0]
#       remote_python: "python3"
#
# 2. Lab server (Docker — most secure):
#   experiment:
#     mode: "ssh_remote"
#     ssh_remote:
#       host: "gpu-server.lab.edu"
#       user: "researcher"
#       key_path: "~/.ssh/id_rsa"
#       gpu_ids: [0]
#       use_docker: true
#       docker_image: "researchclaw/experiment:latest"
#       docker_network_policy: "none"
#
# 3. Colab via SSH tunnel:
#   experiment:
#     mode: "ssh_remote"
#     ssh_remote:
#       host: "localhost"
#       port: 12345
#       user: "root"
#       remote_python: "python3"
#       setup_commands:
#         - "pip install torch torchvision -q"
#
# 4. Colab via Google Drive (most robust, no SSH needed):
#   experiment:
#     mode: "colab_drive"
#     colab_drive:
#       drive_root: "~/Library/CloudStorage/GoogleDrive-you@gmail.com/My Drive/researchclaw"
#       poll_interval_sec: 30
#       timeout_sec: 3600
#       setup_script: "pip install torch torchvision -q"
#   # Then in Colab: run the colab_worker.py that appears in your Drive

  colab_drive:
    drive_root: ""          # Local path to Google Drive mount
    poll_interval_sec: 30   # How often to check for results
    timeout_sec: 3600       # Max wait per experiment (1 hour)
    setup_script: ""        # Shell commands to run before each experiment

  # Scientific Visualization Agent (Code-to-Viz + Nano Banana)
  # Uses a Decision Agent to analyze paper content and determine:
  #   - Code figures (bar charts, line plots) → Matplotlib/TikZ
  #   - Image figures (architecture, flowcharts) → Gemini Nano Banana
  figure_agent:
    enabled: true
    min_figures: 3
    max_figures: 10
    max_iterations: 3
    render_timeout_sec: 30
    # Security: Docker sandbox for visualization code execution
    # use_docker: null  # null = auto-detect, true = force, false = disable
    docker_image: "researchclaw/experiment:latest"
    # Output format: "python" (Matplotlib/Seaborn) or "latex" (TikZ/PGFPlots)
    output_format: "python"
    # Nano Banana (Gemini native image generation)
    nano_banana_enabled: true
    # gemini_api_key: ""  # or set GEMINI_API_KEY env var
    gemini_model: "gemini-2.5-flash-image"
    strict_mode: false
    dpi: 300

# === Prompts ===
# Customize LLM prompts by pointing to your own YAML file.
# Copy prompts.default.yaml, edit the prompts you want, and set the path here.
prompts:
  custom_file: ""  # e.g. "my_prompts.yaml" (empty = use built-in defaults)

  # Per-stage additional guidance. Each key is a stage name (run
  # `researchclaw info` to see the full stage list); each value is either
  # an inline instruction or a path to a text/markdown file. The text is
  # appended to that stage's user prompt under "## Additional Stage
  # Guidance". Unknown stage names emit a warning and are dropped.
  #
  #   extra_prompts:
  #     code_generation: "Favour MadGraph5 + Pythia8 + Delphes toolchains."
  #     paper_outline: ./prompts/jhep_outline_rules.md
  extra_prompts: {}


# === MetaClaw Integration ===
# Enable the MetaClaw bridge to get skill injection, PRM quality gates,
# and continuous learning from research pipeline failures.
# Requires MetaClaw to be running: metaclaw start --mode skills_only
metaclaw_bridge:
  enabled: false
  proxy_url: "http://localhost:30000"    # MetaClaw proxy endpoint
  skills_dir: "~/.metaclaw/skills"       # MetaClaw skills directory
  fallback_url: ""                       # Direct LLM URL if proxy is down
  fallback_api_key: ""

  # PRM quality gate: LLM-as-judge scoring at gate stages
  prm:
    enabled: false
    api_base: ""                         # OpenAI-compatible API for PRM judge
    api_key_env: "PRM_API_KEY"
    api_key: ""
    model: "gpt-5.4"
    votes: 3                             # Majority vote count
    gate_stages: [5, 9, 15, 20]          # Stages to apply PRM gating

  # Lesson-to-skill: auto-convert pipeline failures into MetaClaw skills
  lesson_to_skill:
    enabled: true
    min_severity: "error"                # Only convert error-level lessons
    max_skills_per_run: 3