Add files using upload-large-folder tool

Biomanus_upload/.env.example

@@ -0,0 +1,22 @@
+# Biomni Environment Configuration
+# Copy this file to .env and fill in your actual API keys
+
+# Required: Anthropic API Key for Claude models
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Optional: OpenAI API Key (if using OpenAI models)
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional: AWS Bedrock Configuration (if using AWS Bedrock models)
+AWS_BEARER_TOKEN_BEDROCK=your_bedrock_api_key_here
+AWS_REGION=us-east-1
+
+# Optional: Custom model serving configuration
+# CUSTOM_MODEL_BASE_URL=http://localhost:8000/v1
+# CUSTOM_MODEL_API_KEY=your_custom_api_key_here
+
+# Optional: Biomni data path (defaults to ./data)
+# BIOMNI_DATA_PATH=/path/to/your/data
+
+# Optional: Timeout settings
+# BIOMNI_TIMEOUT_SECONDS=600

Biomanus_upload/.gitattributes

@@ -0,0 +1,2 @@
+*.bam filter=lfs diff=lfs merge=lfs -text
+*.h5ad filter=lfs diff=lfs merge=lfs -text

Biomanus_upload/.gitignore

@@ -0,0 +1,236 @@
+.gitignore
+.buildplan
+.env
+debug*
+.*
+# Byte-compiled / optimized / DLL files
+biomni_release/biomni_env/biomni_tools/
+open_source_process.ipynb
+biomni_env/biomni_tools/*
+.gradio/
+*xlsx
+scripts/*.png
+notebooks/figures/*
+notebooks/tmp_dir/*
+notebooks/tmp_directory/*
+notebooks/save_folder/*
+notebooks/cache
+notebooks/\[draft*
+notebooks/\[scratch*
+notebooks/labbench/*
+scripts/save_folder/*
+scripts/\[draft*
+scripts/tmp_dir/*
+scripts/tmp_directory/*
+scripts/figures/*
+*/scripts/outputs/*
+*/scripts/wandb/*
+*/results/*
+bioagentos/agent/popper_agent.py
+bioagentos/scripts/biorxiv_results
+bioagentos/tool/data_tool/old_data_tool/*
+examples/*.png
+examples/*.csv
+examples/*.fa
+scratch/
+packages/
+data
+dataset
+logs
+scripts/gradio
+data_lake
+__pycache__/
+*.py[cod]
+*$py.class
+res/
+examples/tmp*
+bioagentos/task/lab_bench.py
+*database/
+.history/
+
+temp.*
+
+scripts/analysis/all_tools.txt
+
+BIOMNI_GRADIO/biomni/tool/files/*
+
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+test.ipynb
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.envrc
+uv.lock
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+*.jsonl
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# macOS system files
+.DS_Store
+**/.DS_Store
+
+# DDInter data files
+biomni/tool/schema_db/ddinter_*.pkl
+data/ddinter_raw/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# VSCode
+/.vscode
+
+# Sphinx build
+/docs/build/
+/docs/source/api/
+/paper_reproduction_runs/
+/bioagent-bench-runs/

Biomanus_upload/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+fail_fast: false
+default_language_version:
+    python: python3
+default_stages:
+    - pre-commit
+    - pre-push
+minimum_pre_commit_version: 2.16.0
+repos:
+    - repo: https://github.com/biomejs/pre-commit
+      rev: v2.3.10
+      hooks:
+          - id: biome-format
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.14.11
+      hooks:
+          - id: ruff-check
+            args: [--fix, --exit-non-zero-on-fix, --unsafe-fixes]
+          - id: ruff-format
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v6.0.0
+      hooks:
+          - id: detect-private-key
+          - id: check-ast
+          - id: end-of-file-fixer
+          - id: mixed-line-ending
+            args: [--fix=lf]
+          - id: trailing-whitespace
+          - id: check-case-conflict
+          - id: check-added-large-files
+          - id: check-toml
+          - id: check-yaml
+          - id: check-merge-conflict
+          - id: no-commit-to-branch
+            args: ["--branch=main"]
+    #- repo: https://github.com/pre-commit/mirrors-mypy
+    # rev: v1.16.1
+    #  hooks:
+    #      - id: mypy
+    #        args: [--no-strict-optional, --ignore-missing-imports]
+    #        additional_dependencies:
+    #            ["types-setuptools", "types-requests", "types-attrs"]

Biomanus_upload/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Biomanus_upload/README.md

@@ -0,0 +1,322 @@
+# Biomanus
+
+Biomanus is a graph-guided extension of the Biomni A1 biomedical agent. It adds MCP server generation, MCP ToolGraph construction, GraphRAG-style tool routing, dynamic MCP registration, and benchmark runners for BioAgent-Bench and LAB-Bench.
+
+This README explains how to install the environment, prepare MCP servers, build the MCP graph, and run the experiments.
+
+## 1. Repository Layout
+
+```text
+biomni/                         Core agent, tools, graph router, retriever, and utilities
+biomni_env/                     Conda environment files and setup scripts
+demo_web/backend/tool2mcp.py    Utility for converting bioinformatics tools into MCP servers
+build_generated_mcp_graph.py    Build MCP server catalogs and graph artifacts
+run_bioagent_bench.py           BioAgent-Bench runner
+evaluate_bioagent_bench.py      BioAgent-Bench evaluator
+experiments/lab_bench/scripts/  LAB-Bench runners and graph utilities
+graph_outputs/                  Example prebuilt graph artifacts
+```
+
+Large runtime artifacts, downloaded data lakes, benchmark outputs, node modules, and Git history are intentionally not included in this upload package.
+
+## 2. Install the Environment
+
+Create and activate the Biomni environment:
+
+```bash
+cd /path/to/Biomanus
+conda env create -f biomni_env/environment.yml
+conda activate biomni_e1
+```
+
+For a smaller environment, use:
+
+```bash
+conda env create -f biomni_env/fixed_env.yml
+conda activate biomni_e1
+```
+
+Install extra packages used by MCP generation and benchmark execution:
+
+```bash
+pip install fastmcp mcp openai anthropic python-dotenv pymupdf pipreqs
+pip install langchain langchain-openai langchain-anthropic langgraph
+```
+
+Because this upload package is source-first and does not require a wheel install, run commands from the repository root or export:
+
+```bash
+export PYTHONPATH="$PWD:$PYTHONPATH"
+export BIOMNI_EXECUTION_ENV_PREFIX="$CONDA_PREFIX"
+export BIOMNI_EXECUTION_PYTHON="$CONDA_PREFIX/bin/python"
+```
+
+If your experiments need command-line bioinformatics tools, install them into the same conda environment. The full upstream Biomni setup script is available at:
+
+```bash
+bash biomni_env/setup.sh
+```
+
+This full setup can take many hours and requires substantial disk space.
+
+## 3. Configure the LLM Backend
+
+Biomanus uses Biomni's `Custom` OpenAI-compatible backend in the main experiments. For DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="your_key"
+export DEEPSEEK_BASE_URL="https://api.deepseek.com/v1"
+export DEEPSEEK_MODEL_NAME="deepseek-chat"
+
+export BIOMNI_SOURCE="Custom"
+export BIOMNI_LLM="$DEEPSEEK_MODEL_NAME"
+export BIOMNI_CUSTOM_BASE_URL="$DEEPSEEK_BASE_URL"
+export BIOMNI_CUSTOM_API_KEY="$DEEPSEEK_API_KEY"
+export BIOMNI_LLM_PROVIDER="deepseek"
+```
+
+For another OpenAI-compatible endpoint, keep `BIOMNI_SOURCE=Custom` and replace the base URL, model name, and API key.
+
+## 4. Prepare MCP Servers
+
+Graph-based execution requires local MCP server directories. Each generated server should follow this structure:
+
+```text
+demo_web/backend/data/mcp_generated/
+  mcp_<server_name>/
+    app/
+      <server_name>_server.py
+      <server_name>_shim_server.py        # optional but recommended
+    Dockerfile
+    docker-compose.yml
+    requirements.txt
+    environment.yaml
+```
+
+Create the MCP directories:
+
+```bash
+mkdir -p demo_web/backend/data/mcp_generated
+mkdir -p demo_web/backend/data/merged_prefer_help_txt
+```
+
+### Option A: Copy Existing MCP Servers
+
+If you already generated MCP servers elsewhere, copy the `mcp_*` directories into:
+
+```text
+demo_web/backend/data/mcp_generated/
+```
+
+Then patch generated servers so they expose stdio-compatible MCP entrypoints:
+
+```bash
+python patch_raw_mcp_servers.py --mcp-root demo_web/backend/data/mcp_generated
+python patch_generated_mcp_shims.py --mcp-root demo_web/backend/data/mcp_generated
+```
+
+### Option B: Generate One MCP Server from a Tool Manual
+
+Use `tool2mcp.py` to convert a bioinformatics command-line tool and its help/manual text into an MCP server.
+
+Example using a local help text:
+
+```bash
+python demo_web/backend/tool2mcp.py \
+  --name kallisto \
+  --manual docs/kallisto_help.txt \
+  --output_location demo_web/backend/data/mcp_generated \
+  --llm_provider deepseek
+```
+
+Example using the installed tool's help command:
+
+```bash
+python demo_web/backend/tool2mcp.py \
+  --name fastqc \
+  --manual=--help \
+  --run_help_command True \
+  --output_location demo_web/backend/data/mcp_generated \
+  --llm_provider deepseek
+```
+
+The converter calls an LLM, so the corresponding API key must be configured. Supported providers include `deepseek`, `openai`, `claude`, `azure`, and `gemini`.
+
+## 5. Build the MCP Graph
+
+Once MCP servers exist under `demo_web/backend/data/mcp_generated`, build a graph over all servers:
+
+```bash
+python build_generated_mcp_graph.py \
+  --mcp-root demo_web/backend/data/mcp_generated \
+  --help-root demo_web/backend/data/merged_prefer_help_txt \
+  --output-root graph_outputs \
+  --preset all \
+  --python-cmd "$BIOMNI_EXECUTION_PYTHON"
+```
+
+The output directory will look like:
+
+```text
+graph_outputs/mcp_generated_graph_all_<timestamp>/
+  server_catalog.json
+  graph_nodes.json
+  graph_edges.json
+  server_semantics.json
+  graph_summary.json
+```
+
+For BioAgent-Bench, you can build a smaller graph containing high-signal benchmark servers:
+
+```bash
+python build_generated_mcp_graph.py \
+  --mcp-root demo_web/backend/data/mcp_generated \
+  --help-root demo_web/backend/data/merged_prefer_help_txt \
+  --output-root graph_outputs \
+  --preset bioagent-bench \
+  --python-cmd "$BIOMNI_EXECUTION_PYTHON"
+```
+
+This upload package includes an example graph under `graph_outputs/`. Use it for inspection or as a template. For executable experiments on a new machine, rebuild the graph after placing MCP servers locally so `server_catalog.json` contains valid local commands.
+
+## 6. Run BioAgent-Bench
+
+First download or clone BioAgent-Bench and set the metadata/data paths:
+
+```bash
+export BIOAGENT_BENCH_DATASET_ROOT="/path/to/bioagent-bench/dataset"
+export BIOAGENT_BENCH_METADATA="/path/to/bioagent-bench/src/task_metadata.json"
+```
+
+Run a single task:
+
+```bash
+python run_bioagent_bench.py \
+  --task transcript-quant \
+  --dataset-root "$BIOAGENT_BENCH_DATASET_ROOT" \
+  --metadata "$BIOAGENT_BENCH_METADATA" \
+  --mcp-graph graph_outputs/mcp_generated_graph_benchmark_<timestamp> \
+  --executable-mcp-only \
+  --output-root experiments/bioagent-bench-runs \
+  --execution-env-prefix "$CONDA_PREFIX"
+```
+
+Run all supported tasks:
+
+```bash
+python run_bioagent_bench.py \
+  --all \
+  --dataset-root "$BIOAGENT_BENCH_DATASET_ROOT" \
+  --metadata "$BIOAGENT_BENCH_METADATA" \
+  --mcp-graph graph_outputs/mcp_generated_graph_benchmark_<timestamp> \
+  --executable-mcp-only \
+  --output-root experiments/bioagent-bench-runs \
+  --execution-env-prefix "$CONDA_PREFIX"
+```
+
+Useful ablation switches:
+
+```bash
+--no-graph-retriever      # disable graph-guided routing
+--no-mcp                  # disable MCP registration/execution
+--no-use-tool-retriever   # disable internal Biomni tool retrieval
+```
+
+Evaluate BioAgent-Bench outputs:
+
+```bash
+python evaluate_bioagent_bench.py \
+  --all \
+  --runs-root experiments/bioagent-bench-runs \
+  --dataset-root "$BIOAGENT_BENCH_DATASET_ROOT" \
+  --judge-mode rule \
+  --output experiments/bioagent-bench-runs/latest_evaluation.json
+```
+
+For LLM-based judging, set the judge provider/key and use `--judge-mode llm` or `--judge-mode both`.
+
+## 7. Run LAB-Bench
+
+First install or clone LAB-Bench and set:
+
+```bash
+export LAB_BENCH_ROOT="/path/to/LAB-Bench"
+```
+
+Run a small debug pass:
+
+```bash
+python experiments/lab_bench/scripts/run_labbench_with_hypobioos.py \
+  --evals DbQA SeqQA \
+  --splits test \
+  --debug \
+  --graph-dir graph_outputs/mcp_generated_graph_all_<timestamp> \
+  --output-root experiments/lab_bench/results/debug \
+  --agent-root experiments/lab_bench/agent_runtime/debug \
+  --compact-results-path experiments/lab_bench/results/debug/results.jsonl \
+  --reasoning-log-path experiments/lab_bench/results/debug/reasoning.log \
+  --compact-output-only
+```
+
+Run the main DbQA/SeqQA protocol:
+
+```bash
+python experiments/lab_bench/scripts/run_labbench_with_hypobioos.py \
+  --evals DbQA SeqQA \
+  --splits test \
+  --dev-size 45 \
+  --test-size 315 \
+  --seed 20260514 \
+  --graph-dir graph_outputs/mcp_generated_graph_all_<timestamp> \
+  --mcp-server-top-k 8 \
+  --mcp-tool-top-k 12 \
+  --mcp-server-candidate-pool 24 \
+  --output-root experiments/lab_bench/results/main \
+  --agent-root experiments/lab_bench/agent_runtime/main \
+  --compact-results-path experiments/lab_bench/results/main/results.jsonl \
+  --reasoning-log-path experiments/lab_bench/results/main/reasoning.log \
+  --compact-output-only
+```
+
+For parallel sharded runs, call the same runner repeatedly with `--shard-index` and `--shard-count`, writing all shards to the same compact JSONL with `--skip-existing-results`.
+
+## 8. Recommended Reproduction Order
+
+1. Create and activate the conda environment.
+2. Configure the LLM backend.
+3. Generate or copy MCP servers into `demo_web/backend/data/mcp_generated`.
+4. Patch MCP shims.
+5. Build the MCP graph.
+6. Run a single BioAgent-Bench task as a smoke test.
+7. Run LAB-Bench in `--debug` mode.
+8. Launch full benchmark runs and evaluate.
+
+## 9. Common Issues
+
+`MCP root does not exist`
+
+Create `demo_web/backend/data/mcp_generated` and copy or generate `mcp_*` server directories.
+
+`Help root does not exist`
+
+Create an empty help directory:
+
+```bash
+mkdir -p demo_web/backend/data/merged_prefer_help_txt
+```
+
+`server_catalog.json points to old paths`
+
+Rebuild the graph on the current machine after placing MCP servers locally. The graph stores executable command paths.
+
+`Missing API key`
+
+Export `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or the matching provider key before running agents or MCP generation.
+
+`LAB-Bench import errors`
+
+Set `LAB_BENCH_ROOT` to the local LAB-Bench checkout and install LAB-Bench dependencies in the active environment.
+
+`BioAgent-Bench cannot find metadata`
+
+Set `BIOAGENT_BENCH_METADATA` and `BIOAGENT_BENCH_DATASET_ROOT`, or pass `--metadata` and `--dataset-root` explicitly.

Biomanus_upload/biomni/__init__.py

@@ -0,0 +1,3 @@
+from .version import __version__
+
+__all__ = ["__version__"]

Biomanus_upload/biomni/agent/__init__.py

@@ -0,0 +1 @@
+from biomni.agent.a1 import A1  # noqa: F401

Biomanus_upload/biomni/agent/env_collection.py

@@ -0,0 +1,313 @@
+import json
+import os
+import re
+from typing import Any
+
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+from biomni.agent.base_agent import base_agent
+
+
+class PaperTaskExtractor(base_agent):
+    """Agent that extracts generalizable tasks/experiments from academic papers.
+    It processes papers in chunks and identifies common research tasks that could be shared across papers.
+    """
+
+    def __init__(
+        self,
+        llm="claude-3-7-sonnet-20250219",
+        cheap_llm=None,
+        tools=None,
+        chunk_size=4000,
+        chunk_overlap=400,
+    ):
+        """Initialize the PaperTaskExtractor agent.
+
+        Args:
+            llm (str): The LLM model to use
+            cheap_llm (str, optional): A cheaper LLM for simpler tasks
+            tools (list, optional): Any tools to use (not needed for this agent)
+            chunk_size (int): Size of text chunks for processing
+            chunk_overlap (int): Overlap between chunks
+
+        """
+        super().__init__(llm, cheap_llm, tools)
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.log = []
+        self.configure()
+
+    def configure(self):
+        """Configure the agent with appropriate prompts."""
+        # Prompt for analyzing paper chunks
+        self.chunk_analysis_prompt = """You are a research methodology expert specializing in identifying computational tasks and data analysis procedures in academic papers.
+
+Your job is to analyze chunks of academic papers and identify ONLY the most common, generalizable computational tasks that are widely used across biomedical research and can be implemented with Python or Linux code.
+
+STRICT GUIDELINES:
+1. ONLY extract tasks that are extremely common and standard in computational biomedical research
+2. Each task MUST have clear, well-defined inputs and outputs
+3. Tasks MUST be generalizable across many different papers and research questions
+4. Be VERY selective - only include tasks that appear in hundreds of papers
+5. If a task is specific to this paper, unclear, or not widely used, DO NOT include it
+6. Focus on computational tasks that can be implemented with Python or Linux code
+7. Each task should be something that could be implemented as a function with clear inputs/outputs
+8. Also identify commonly used databases and software packages mentioned in the text
+9. Tasks MUST be CONCRETE and SPECIFIC - include exact methodological details
+10. Avoid vague task names like "Statistical Analysis" - instead use specific protocol names like "Two-way ANOVA with Tukey's Post-hoc Test using SciPy"
+11. DO NOT include wet lab procedures that cannot be implemented computationally
+12. ONLY include tasks that could be automated with code
+
+For the following chunk of text from an academic paper, provide:
+1. A list of ONLY the most common, generalizable COMPUTATIONAL tasks identified (be extremely selective)
+2. For each task, clearly define:
+   - Task name: A SPECIFIC and CONCRETE name with methodological details (e.g., "RNA-seq Differential Expression Analysis with DESeq2" instead of just "Gene Expression Analysis")
+   - Input: What SPECIFIC data or parameters the task requires
+   - Output: What SPECIFIC data or results the task produces
+   - Code implementation: How this task could be implemented with Python or Linux code, including key libraries/packages
+   - Frequency: How common this computational task is in biomedical research
+   - Standard methods: The established computational techniques used to perform this task
+   - Example: A brief description of how THIS specific paper uses this task (with specific details from the paper)
+3. A list of commonly used databases mentioned in the text (if any)
+4. A list of commonly used software packages/tools mentioned in the text (if any)
+
+PAPER CHUNK:
+{chunk_text}
+
+Remember, it's better to return NO tasks than to include tasks that aren't extremely common, generalizable, and implementable with code. Quality over quantity is essential. Tasks MUST be CONCRETE with SPECIFIC methodological details and MUST be implementable with Python or Linux code.
+"""
+
+        # Prompt for consolidating tasks
+        self.consolidation_prompt = """You are a research methodology expert. Your task is to consolidate lists of computational research tasks extracted from different chunks of an academic paper.
+
+BE EXTREMELY SELECTIVE. Only include tasks that are:
+1. Fundamental to computational biomedical research
+2. Used in hundreds of papers across different subfields
+3. Have clear, well-defined inputs and outputs
+4. Represent standard computational approaches
+5. Could be implemented as a function with specific inputs and outputs
+6. Are CONCRETE and SPECIFIC with exact methodological details
+7. Can be implemented with Python or Linux code
+8. Are computational in nature, not wet lab procedures
+
+REMOVE any tasks that:
+- Are specific to a particular paper or dataset
+- Lack clear inputs or outputs
+- Are not widely used across biomedical research
+- Are vague or poorly defined
+- Represent niche or specialized techniques
+- Have generic names without specific methodological details
+- Cannot be implemented with code
+- Require physical lab equipment or manual intervention
+
+The output should be a JSON object with three main keys:
+1. "tasks": A list of task objects, where each task has:
+   - "task_name": A SPECIFIC and CONCRETE name with methodological details (e.g., "Single-cell RNA-seq Clustering with Seurat" instead of just "Cell Clustering")
+   - "description": A clear description of what the computational task does
+   - "inputs": SPECIFIC data types or parameters the task requires
+   - "outputs": SPECIFIC data types or results the task produces
+   - "code_implementation": How this task could be implemented with Python or Linux code, including key libraries/packages and a brief pseudocode example
+   - "frequency": How common this computational task is in biomedical research
+   - "standard_methods": The established computational techniques used to perform this task
+   - "example": A specific example from THIS paper showing how the task was used (with concrete details)
+
+2. "databases": A list of database objects, where each database has:
+   - "name": The name of the database
+   - "description": A brief description of what the database contains
+   - "url": The URL of the database (if mentioned)
+   - "usage": How the database is commonly used in computational biomedical research
+   - "example": How this specific paper uses the database
+
+3. "software": A list of software package objects, where each package has:
+   - "name": The name of the software package
+   - "description": A brief description of what the software does
+   - "url": The URL or reference to the software (if mentioned)
+   - "usage": How the software is commonly used in computational biomedical research
+   - "example": How this specific paper uses the software
+
+EXTRACTED INFORMATION FROM PAPER CHUNKS:
+{task_lists}
+
+Be ruthless in filtering - it's better to return a few truly common computational tasks than many that aren't universal or implementable with code.
+Respond with only a valid JSON object containing the three lists described above.
+"""
+
+    def process_paper(self, paper_text: str) -> dict[str, list[dict[str, Any]]]:
+        """Process a paper and extract generalizable tasks/experiments, databases, and software.
+
+        Args:
+            paper_text (str): The full text of the paper
+
+        Returns:
+            Dict[str, List[Dict[str, Any]]]: A dictionary with tasks, databases, and software
+
+        """
+        # Split the paper into chunks
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=self.chunk_size,
+            chunk_overlap=self.chunk_overlap,
+            length_function=len,
+            separators=["\n\n", "\n", ". ", " ", ""],
+        )
+        chunks = text_splitter.split_text(paper_text)
+
+        # Process each chunk to extract tasks
+        chunk_results = []
+        for i, chunk in enumerate(chunks):
+            print(f"Processing chunk {i + 1}/{len(chunks)}...")
+            chunk_tasks = self._process_chunk(chunk)
+            chunk_results.append(chunk_tasks)
+
+        # Consolidate tasks from all chunks
+        consolidated_results = self._consolidate_tasks(chunk_results)
+        return consolidated_results
+
+    def _process_chunk(self, chunk_text: str) -> str:
+        """Process a single chunk of the paper to extract tasks.
+
+        Args:
+            chunk_text (str): The chunk text to process
+
+        Returns:
+            str: Extracted tasks from this chunk
+
+        """
+        prompt = self.chunk_analysis_prompt.format(chunk_text=chunk_text)
+        message = self.llm.invoke(prompt)
+        return message.content
+
+    def _consolidate_tasks(self, chunk_results: list[str]) -> dict[str, list[dict[str, Any]]]:
+        """Consolidate tasks, databases, and software extracted from different chunks into a unified structure.
+
+        Args:
+            chunk_results (List[str]): Results from each chunk
+
+        Returns:
+            Dict[str, List[Dict[str, Any]]]: Consolidated information with tasks, databases, and software
+
+        """
+        # Combine all chunk results
+        all_tasks = "\n\n===== CHUNK SEPARATOR =====\n\n".join(chunk_results)
+
+        # Use the consolidation prompt to merge and organize tasks
+        prompt = self.consolidation_prompt.format(task_lists=all_tasks)
+        response = self.llm.invoke(prompt)
+
+        # Extract the JSON from the response
+        try:
+            # Try to parse the entire response as JSON
+            result = json.loads(response.content)
+        except json.JSONDecodeError:
+            # If that fails, try to extract JSON from the text
+            try:
+                # Look for JSON-like content between triple backticks
+                json_match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", response.content)
+                if json_match:
+                    result = json.loads(json_match.group(1))
+                else:
+                    # Fallback: just return the text response
+                    return {
+                        "tasks": [
+                            {
+                                "error": "Could not parse JSON",
+                                "raw_response": response.content,
+                            }
+                        ],
+                        "databases": [],
+                        "software": [],
+                    }
+            except Exception:
+                return {
+                    "tasks": [
+                        {
+                            "error": "Could not parse JSON",
+                            "raw_response": response.content,
+                        }
+                    ],
+                    "databases": [],
+                    "software": [],
+                }
+
+        # Ensure the result has the expected structure
+        if not isinstance(result, dict):
+            result = {
+                "tasks": result if isinstance(result, list) else [],
+                "databases": [],
+                "software": [],
+            }
+
+        # Ensure all required keys exist
+        for key in ["tasks", "databases", "software"]:
+            if key not in result:
+                result[key] = []
+
+        return result
+
+    def go(self, paper_text: str):
+        """Process a paper and return the extracted tasks, databases, and software.
+
+        Args:
+            paper_text (str): The full text of the paper
+
+        Returns:
+            tuple: (log, results) where log is a list of processing steps and results is the final result
+
+        """
+        self.log = []
+        self.log.append(
+            (
+                "user",
+                "Extract only the most common and generalizable biomedical research tasks, databases, and software from this paper",
+            )
+        )
+
+        results = self.process_paper(paper_text)
+
+        result_str = json.dumps(results, indent=2)
+        self.log.append(("assistant", result_str))
+
+        return self.log, results
+
+    def save_results(self, results: dict[str, list[dict[str, Any]]], output_path: str):
+        """Save the extracted tasks, databases, and software to a JSON file.
+
+        Args:
+            results (Dict[str, List[Dict[str, Any]]]): The extracted tasks, databases, and software
+            output_path (str): Path to save the results
+
+        """
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(results, f, indent=2)
+        print(f"Results saved to {output_path}")
+
+    def result_formatting(self, output_class, task_intention):
+        """Format the results according to a specific output class.
+
+        Args:
+            output_class: The class to format the output as
+            task_intention: Description of the task
+
+        Returns:
+            The formatted result
+
+        """
+        format_check_prompt = ChatPromptTemplate.from_messages(
+            [
+                (
+                    "system",
+                    (
+                        "You are evaluateGPT, tasked with extract and parse the task output based on the history of an agent. "
+                        "Review the entire history of messages provided. "
+                        "Here is the task output requirement: \n"
+                        f"'{task_intention.replace('{', '{{').replace('}', '}}')}'.\n"
+                    ),
+                ),
+                ("placeholder", "{messages}"),
+            ]
+        )
+
+        checker_llm = format_check_prompt | self.llm.with_structured_output(output_class)
+        result = checker_llm.invoke({"messages": [("user", str(self.log))]}).dict()
+        return result

Biomanus_upload/biomni/agent/function_generator.py

@@ -0,0 +1,119 @@
+import re
+
+from biomni.llm import get_llm
+
+
+class base_agent:
+    def __init__(self, llm="claude-3-haiku-20240307", cheap_llm=None, tools=None, temperature=0.7):
+        self.tools = tools
+        self.llm = get_llm(llm, temperature)
+        if cheap_llm is None:
+            self.cheap_llm = llm
+        else:
+            self.cheap_llm = cheap_llm
+
+    def configure(self):
+        pass
+
+    def go(self, input):
+        pass
+
+
+class FunctionGenerator(base_agent):
+    """Agent that generates executable Python code scripts given a task description."""
+
+    def __init__(self, llm="claude-3-7-sonnet-20250219", cheap_llm=None, temperature=0.7):
+        """Initialize the PaperTaskExtractor agent.
+
+        Args:
+            llm (str): The LLM model to use
+            cheap_llm (str, optional): A cheaper LLM for simpler tasks
+        """
+        super().__init__(llm, cheap_llm, temperature)
+        self.log = []
+        self.configure()
+
+    def configure(self):
+        """Configure the agent with appropriate prompts."""
+        # Prompt for Python code generation
+        self.system_prompt = """You are a senior Python engineer. Generate robust, idiomatic Python code that solves the user's task. Requirements:
+        1. Output ONLY Python code, ideally inside a single triple-backtick code block.
+        2. Include minimal inline comments and a small docstring.
+        3. Add a `main()` and an `if __name__ == '__main__':` guard when appropriate.
+        4. Avoid external dependencies unless necessary; if used, show `pip` installs in comments.
+        5. Do not include prose before or after the code.
+        6. When applicable, prioritize the use of codes on public repositories, such as HuggingFace or Github
+
+        Generate Python codes for the following task:
+        {task}
+"""
+
+    def _generate_code(self, task_description: str) -> str:
+        """Generate codes given a task description.
+        Args:
+            task_description (str): task descriptions (possibly generated from previous steps)
+
+        Returns:
+            str: generated code string
+
+        """
+        prompt = self.system_prompt.format(task=task_description)
+        message = self.llm.invoke(prompt)
+        return message.content
+
+    def _generate_script_filename(self, task_description: str, max_words: int = 6) -> str:
+        """
+        Generate a safe, meaningful Python script filename from a task description.
+        Poised for update: may ask the agent to suggest meaningful names.
+
+        Parameters:
+        -----------
+        task_description (str): task descriptions (possibly generated from previous steps)
+
+        max_words : int
+            Maximum number of words to include in the filename.
+
+        Returns:
+        --------
+            str
+            A lowercase, hyphen-free, safe filename ending in '.py'.
+        """
+        # Lowercase and remove non-alphanumeric (allow spaces for splitting)
+        cleaned = re.sub(r"[^a-zA-Z0-9\s]", "", task_description.lower())
+
+        # Tokenize and select top words
+        words = cleaned.split()
+        selected_words = words[:max_words] if words else ["script"]
+
+        # Join with underscores
+        base_name = "_".join(selected_words)
+        return f"{base_name}.py"
+
+    def go(self, task_description: str):
+        """Implement the inherited function to get the tasks done.
+
+        Args:
+            task_description (str): task descriptions (possibly generated from previous steps)
+
+        Returns:
+            tuple: (script_filename, results) where script_filename is a generated name for script file and results is the generated codes
+
+        """
+        self.log = []
+        self.log.append(
+            (
+                "user",
+                "Generate Python codes given a task description",
+            )
+        )
+
+        script_filename = self._generate_script_filename(task_description)
+        results = self._generate_code(task_description)
+        return script_filename, self._extract_code_block(results)
+
+    def _extract_code_block(self, s: str) -> str:
+        """
+        Extract the first fenced code block (``` or ```python) from s.
+        """
+        m = re.search(r"```(?:python)?\s*(.+?)\s*```", s, flags=re.DOTALL | re.IGNORECASE)
+        return m.group(1).strip() if m else None

Biomanus_upload/biomni/agent/qa_llm.py

@@ -0,0 +1,50 @@
+from langchain_core.prompts import ChatPromptTemplate
+
+from biomni.llm import get_llm
+
+
+class qa_llm:
+    def __init__(self, path="./data", llm="claude-3-haiku-20240307", lab_bench_reproduce=False):
+        self.path = path
+        self.llm = get_llm(llm)
+
+        if lab_bench_reproduce:
+            self.prompt_modifier = """
+The following is a multiple choice question about biology.
+Please answer by responding with the letter of the correct answer.
+
+Think step by step. \n
+            """
+        else:
+            self.prompt_modifier = ""
+        self.log = []
+
+    def configure(self):
+        pass
+
+    def go(self, input):
+        self.log = []
+        self.log.append(("user", input))
+        message = self.llm.invoke(self.prompt_modifier + input)
+        self.log.append(("assistant", message.content))
+        return [message.content], message.content
+
+    def result_formatting(self, output_class, task_intention):
+        self.format_check_prompt = ChatPromptTemplate.from_messages(
+            [
+                (
+                    "system",
+                    (
+                        "You are evaluateGPT, tasked with extract and parse the task output based on the history of an agent. "
+                        "Review the entire history of messages provided. "
+                        "Here is the task output requirement: \n"
+                        f"'{task_intention.replace('{', '{{').replace('}', '}}')}'.\n"
+                    ),
+                ),
+                ("placeholder", "{messages}"),
+            ]
+        )
+
+        checker_llm = self.format_check_prompt | self.llm.with_structured_output(output_class)
+        result = checker_llm.invoke({"messages": [("user", str(self.log))]}).dict()
+        return result

Biomanus_upload/biomni/agent/react.py

@@ -0,0 +1,465 @@
+import glob
+import inspect
+import json
+import os
+import signal
+from collections.abc import Sequence
+from functools import wraps
+from multiprocessing import Process, Queue
+from typing import Annotated, TypedDict
+
+from langchain_core.messages import BaseMessage, SystemMessage, ToolMessage
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import END, StateGraph
+from langgraph.graph.message import add_messages
+
+from biomni.config import default_config
+from biomni.env_desc import data_lake_dict, library_content_dict
+from biomni.llm import get_llm
+from biomni.model.retriever import ToolRetriever
+from biomni.tool.tool_registry import ToolRegistry
+from biomni.utils import (
+    api_schema_to_langchain_tool,
+    function_to_api_schema,
+    pretty_print,
+    read_module2api,
+)
+
+
+# Define the AgentState TypedDict for our custom implementation
+class AgentState(TypedDict):
+    """The state of the agent."""
+
+    # add_messages is a reducer that combines message sequences
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+
+
+class react:
+    def __init__(
+        self,
+        path: str | None = None,
+        llm: str | None = None,
+        use_tool_retriever: bool | None = None,
+        timeout_seconds: int | None = None,
+    ):
+        # Use default_config values for unspecified parameters
+        if path is None:
+            path = default_config.path
+        if llm is None:
+            llm = default_config.llm
+        if use_tool_retriever is None:
+            use_tool_retriever = default_config.use_tool_retriever
+        if timeout_seconds is None:
+            timeout_seconds = default_config.timeout_seconds
+
+        self.path = path
+        if not os.path.exists(path):
+            os.makedirs(path)
+            print(f"Created directory: {path}")
+            ### TODO: Download the data
+        else:
+            print(f"Data directory already exists: {path}, loading...")
+
+        module2api = read_module2api()
+
+        self.llm = get_llm(llm, config=default_config)
+        tools = []
+        for module, api_list in module2api.items():
+            print("Registering tools from module:", module)
+            tools += [api_schema_to_langchain_tool(api, mode="custom_tool", module_name=module) for api in api_list]
+        self.tools = tools
+        self.module2api = module2api
+        self.use_tool_retriever = use_tool_retriever
+
+        # Store dictionaries for data lake and library content
+        self.data_lake_dict = data_lake_dict
+        self.library_content_dict = library_content_dict
+
+        if self.use_tool_retriever:
+            self.tool_registry = ToolRegistry(module2api)
+            self.retriever = ToolRetriever()
+
+        self.timeout_seconds = timeout_seconds  # 10 minutes default timeout
+
+        # When wrapping tools with timeout
+        self.tools = self._add_timeout_to_tools(self.tools)
+        self.prompt = ""
+        self.system_prompt = ""
+
+    def _add_timeout_to_tools(self, tools):
+        """Apply timeout wrapper to all tool functions using multiprocessing."""
+
+        def create_timed_func(original_func, timeout):
+            """Factory function that creates a unique timed function for each tool."""
+            tool_name = getattr(original_func, "__name__", "unknown")
+            # print(f"Applying timeout wrapper to tool: {tool_name}")
+
+            def process_func(func, args, kwargs, result_queue):
+                """Function to run in a separate process."""
+                try:
+                    result = func(*args, **kwargs)
+                    result_queue.put(("success", result))
+                except Exception as e:
+                    result_queue.put(("error", str(e)))
+
+            @wraps(original_func)
+            def timed_func(*args, **kwargs):
+                # print(f"Executing tool with timeout: {tool_name}")
+                result_queue = Queue()
+
+                # Start a separate process
+                proc = Process(
+                    target=process_func,
+                    args=(original_func, args, kwargs, result_queue),
+                )
+                proc.start()
+
+                # Wait for the specified timeout
+                proc.join(timeout)
+
+                # Check if the process is still running after timeout
+                if proc.is_alive():
+                    print(f"TIMEOUT: Tool {tool_name} execution timed out after {timeout} seconds")
+                    # Force terminate the process
+                    proc.terminate()
+                    proc.join(1)  # Give it a second to terminate
+
+                    # If it's still not dead, kill it with more force
+                    if proc.is_alive():
+                        os.kill(proc.pid, signal.SIGKILL)
+
+                    return f"ERROR: Tool execution timed out after {timeout} seconds. Please try with simpler inputs or break your task into smaller steps."
+
+                # Get the result from the queue
+                if not result_queue.empty():
+                    status, result = result_queue.get()
+                    if status == "success":
+                        return result
+                    else:
+                        return f"Error in tool execution: {result}"
+
+                return "Error: Tool execution completed but no result was returned"
+
+            return timed_func
+
+        wrapped_tools = []
+        for tool in tools:
+            wrapped_tool = tool
+            wrapped_tool.func = create_timed_func(tool.func, self.timeout_seconds)
+            wrapped_tools.append(wrapped_tool)
+
+        return wrapped_tools
+
+    def add_tool(self, api):
+        function_code = inspect.getsource(api)
+        schema = function_to_api_schema(function_code, self.llm)
+        new_tool = api_schema_to_langchain_tool(schema, mode="custom_tool", module_name=api.__module__)
+
+        # Create a single wrapped tool using the existing _add_timeout_to_tools method
+        wrapped_tools = self._add_timeout_to_tools([new_tool])
+
+        # Get the wrapped tool and add it to our tools list
+        if wrapped_tools:
+            self.tools.append(wrapped_tools[0])
+
+    def configure(
+        self,
+        plan=False,
+        reflect=False,
+        data_lake=False,
+        react_code_search=False,
+        library_access=False,
+    ):
+        data_lake_path = self.path + "/data_lake"
+        data_lake_content = glob.glob(data_lake_path + "/*")
+        data_lake_items = [x.split("/")[-1] for x in data_lake_content]
+
+        if react_code_search:
+            tools = [i for i in self.tools if i.name in ["run_python_repl", "search_google"]]
+
+            prompt_modifier = """
+You are a helpful biomedical assistant assigned with the task of problem-solving.
+
+You have access to two tools:
+1) run_python_repl: to write and run python code
+2) search_google: to search google for information
+
+You can use them to solve the problem.
+            """
+        else:
+            tools = self.tools
+            if (not plan) and (not reflect):
+                prompt_modifier = """You are a helpful biologist and expert geneticist.
+                """
+            elif plan and (not reflect):
+                prompt_modifier = """You are a helpful biologist and expert geneticist.
+                Given the question from the user,
+                - First, come up with a high level plan based on your understanding of the problem and available tools and record it in the Research Plan and Status. You can revise the plan later.
+                - Research Plan and Status should well organized and succinctly keep track of 1) high level plan (can be revised), 2) what steps have been done and what steps are in progress, 3) short results and conclusions of each step after it has been performed. Do not perform action in research plan.
+                - Research Plan and Status must only include progress that has been made by previous steps. It should not include results not directly confirmed by the previous observation.
+                - Follow the plan and try to achieve the goal as straightforwardly as possible. Use tools as necessary.
+                """
+            elif (not plan) and reflect:
+                prompt_modifier = """You are a helpful biologist and expert geneticist.
+                In each round after the tool is used, conduct "reflection" step: reflect on the current state of the problem and the results of the last round. What does the observation mean? If there is an error, what caused the error and how to debug?
+                """
+            else:
+                prompt_modifier = """You are a helpful biologist and expert geneticist.
+                Given the question from the user,
+                - First, come up with a high level plan based on your understanding of the problem and available tools and record it in the Research Plan and Status. You can revise the plan later.
+                - Research Plan and Status should well organized and succinctly keep track of 1) high level plan (can be revised), 2) what steps have been done and what steps are in progress, 3) short results and conclusions of each step after it has been performed. Do not perform action in research plan.
+                - Research Plan and Status must only include progress that has been made by previous steps. It should not include results not directly confirmed by the previous observation.
+                - Follow the plan and try to achieve the goal as straightforwardly as possible. Use tools as necessary.
+                In each round after the tool is used, conduct "reflection" step: reflect on the current state of the problem and the results of the last round. What does the observation mean? If there is an error, what caused the error and how to debug?
+                You have access to write_python_code and run_python_repl tool to write and run your own code if tools fail, or if the given tools are not enough. Please always make sure to write code when dealing with substantial data, including finding the length of long sequences or elements at different positions.
+                """
+
+        if data_lake:
+            # Format data lake items with descriptions
+            data_lake_formatted = []
+            for item in data_lake_items:
+                description = data_lake_dict.get(item, f"Data lake item: {item}")
+                data_lake_formatted.append(f"{item}: {description}")
+
+            prompt_modifier += """
+You can also access a biological data lake at the following path: {data_lake_path}. You can use the run_python_repl tool to write code to understand the data, process and utilize it for the task.
+Here is the list of datasets with their descriptions:
+----
+{data_lake_formatted}
+----
+            """.format(
+                data_lake_path=data_lake_path,
+                data_lake_formatted="\n".join(data_lake_formatted),
+            )
+
+        if library_access:
+            # Format library content with descriptions
+            library_formatted = []
+            for lib_name, lib_desc in library_content_dict.items():
+                library_formatted.append(f"{lib_name}: {lib_desc}")
+
+            prompt_modifier += """
+You also have access to a list of software packages that can be used to perform various tasks.
+You can use the run_python_repl tool to write code to access and utilize the library for the task.
+Don't forget the import statement.
+Here is the list of available libraries with their descriptions:
+----
+{library_formatted}
+----
+            """.format(library_formatted="\n".join(library_formatted))
+
+        print("=" * 25 + "System Prompt" + "=" * 25)
+        print(prompt_modifier)
+        self.system_prompt = prompt_modifier
+        self.prompt = ChatPromptTemplate.from_messages(
+            [
+                ("system", prompt_modifier),
+                MessagesPlaceholder(variable_name="messages"),
+            ]
+        )
+
+        # Store the tools for later use
+        self.active_tools = tools
+
+        # Create a custom implementation of the ReAct agent using LangGraph
+        self.app = self._create_custom_react_agent(self.llm, tools, self.prompt)
+
+    def _create_custom_react_agent(self, llm, tools, prompt):
+        """Create a custom ReAct agent using LangGraph."""
+        # Create a dictionary mapping tool names to tool objects for easy lookup
+        tools_by_name = {tool.name: tool for tool in tools}
+
+        # Bind the tools to the language model
+        llm_with_tools = llm.bind_tools(tools)
+
+        # Define the node that calls the model
+        def call_model(state: AgentState, config: RunnableConfig = None):
+            """Node that calls the language model to get the next action."""
+            system_message = SystemMessage(content=self.system_prompt)
+            messages = [system_message] + state["messages"]
+            response = llm_with_tools.invoke(messages, config=config)
+            return {"messages": [response]}
+
+        # Define the node that executes tools
+        def tool_node(state: AgentState):
+            """Node that executes tools based on the LLM's decisions."""
+            outputs = []
+            for tool_call in state["messages"][-1].tool_calls:
+                try:
+                    tool_result = tools_by_name[tool_call["name"]].invoke(tool_call["args"])
+                    outputs.append(
+                        ToolMessage(
+                            content=json.dumps(tool_result),
+                            name=tool_call["name"],
+                            tool_call_id=tool_call["id"],
+                        )
+                    )
+                except Exception as e:
+                    # Handle any errors that occur during tool execution
+                    outputs.append(
+                        ToolMessage(
+                            content=json.dumps({"error": str(e)}),
+                            name=tool_call["name"],
+                            tool_call_id=tool_call["id"],
+                        )
+                    )
+            return {"messages": outputs}
+
+        # Define the conditional edge that determines whether to continue or not
+        def should_continue(state: AgentState):
+            """Determine if we should continue running the graph or finish."""
+            messages = state["messages"]
+            last_message = messages[-1]
+            # If there is no tool call, then we finish
+            if not hasattr(last_message, "tool_calls") or not last_message.tool_calls:
+                return "end"
+            # Otherwise if there is, we continue
+            else:
+                return "continue"
+
+        # Define a new graph
+        workflow = StateGraph(AgentState)
+
+        # Define the two nodes we will cycle between
+        workflow.add_node("agent", call_model)
+        workflow.add_node("tools", tool_node)
+
+        # Set the entrypoint as `agent`
+        workflow.set_entry_point("agent")
+
+        # Add conditional edges
+        workflow.add_conditional_edges(
+            "agent",
+            should_continue,
+            {
+                "continue": "tools",
+                "end": END,
+            },
+        )
+
+        # Add edge from tools back to agent
+        workflow.add_edge("tools", "agent")
+
+        # Compile the graph
+        return workflow.compile()
+
+    def go(self, prompt):
+        """Execute the agent with the given prompt.
+
+        Args:
+            prompt: The user's query
+
+        """
+        if self.use_tool_retriever:
+            # Gather all available tools from the registry
+            all_tools = self.tool_registry.tools if hasattr(self, "tool_registry") else []
+
+            # Get data lake items with descriptions
+            data_lake_path = self.path + "/data_lake"
+            data_lake_content = glob.glob(data_lake_path + "/*")
+            data_lake_items = [x.split("/")[-1] for x in data_lake_content]
+
+            # Create data lake descriptions for retrieval
+            data_lake_descriptions = []
+            for item in data_lake_items:
+                description = self.data_lake_dict.get(item, f"Data lake item: {item}")
+                data_lake_descriptions.append({"name": item, "description": description})
+
+            # Libraries with descriptions
+            library_descriptions = []
+            for lib_name, lib_desc in self.library_content_dict.items():
+                library_descriptions.append({"name": lib_name, "description": lib_desc})
+
+            # Prepare resources for retrieval
+            resources = {
+                "tools": all_tools,
+                "data_lake": data_lake_descriptions,
+                "libraries": library_descriptions,
+            }
+
+            # Use prompt-based retrieval with the agent's LLM
+            selected_resources = self.retriever.prompt_based_retrieval(prompt, resources, llm=self.llm)
+            print("Using prompt-based retrieval with the agent's LLM")
+
+            # If we're using prompt or embedding based retrieval, print the selected resources
+            print("\nSelected tools:")
+            for tool in selected_resources["tools"]:
+                if isinstance(tool, dict):
+                    print(f"- {tool.get('name', 'Unknown')}: {tool.get('description', '')}")
+                else:
+                    print(f"- {getattr(tool, 'name', str(tool))}: {getattr(tool, 'description', '')}")
+
+            print("\nSelected data lake items:")
+            for item in selected_resources["data_lake"]:
+                if isinstance(item, dict):
+                    name = item.get("name", "Unknown")
+                    description = self.data_lake_dict.get(name, f"Data lake item: {name}")
+                    print(f"- {name}: {description}")
+                elif isinstance(item, str) and ": " in item:
+                    # If the item already has a description, print it as is
+                    print(f"- {item}")
+                else:
+                    description = self.data_lake_dict.get(item, f"Data lake item: {item}")
+                    print(f"- {item}: {description}")
+
+            print("\nSelected libraries:")
+            for lib in selected_resources["libraries"]:
+                if isinstance(lib, dict):
+                    print(f"- {lib.get('name', 'Unknown')}: {lib.get('description', '')}")
+                else:
+                    print(f"- {lib}")
+
+            # Convert selected tools to langchain tool objects
+            tool_names = [
+                tool["name"] if isinstance(tool, dict) else getattr(tool, "name", str(tool))
+                for tool in selected_resources["tools"]
+            ]
+            retrieved_list_of_tools = []
+
+            # Get the tool objects by name
+            for tool_name in tool_names:
+                # Find the tool in the original tools list
+                matching_tools = [t for t in self.tools if getattr(t, "name", None) == tool_name]
+                if matching_tools:
+                    retrieved_list_of_tools.append(matching_tools[0])
+
+            # Add back coding tool if not already included
+            if len([i for i in retrieved_list_of_tools if i.name == "run_python_repl"]) == 0:
+                retrieved_list_of_tools = retrieved_list_of_tools + [
+                    i for i in self.tools if i.name == "run_python_repl"
+                ]
+
+            print("Retrieved tools: \n" + "\n".join([l.name + ": " + l.description for l in retrieved_list_of_tools]))
+            # Recreate the custom agent with the retrieved tools
+            self.app = self._create_custom_react_agent(self.llm, retrieved_list_of_tools, self.prompt)
+
+        # Default behavior (no tool retriever or retrieval_method is 'none')
+        config = {"recursion_limit": 50}
+        inputs = {"messages": [("user", prompt)]}
+        self.log = []
+        for s in self.app.stream(inputs, stream_mode="values", config=config):
+            message = s["messages"][-1]
+            out = pretty_print(message)
+            self.log.append(out)
+        return self.log, s["messages"][-1].content
+
+    def result_formatting(self, output_class, task_intention):
+        self.format_check_prompt = ChatPromptTemplate.from_messages(
+            [
+                (
+                    "system",
+                    (
+                        "You are evaluateGPT, tasked with extract and parse the task output based on the history of an agent. "
+                        "Review the entire history of messages provided. "
+                        "Here is the task output requirement: \n"
+                        f"'{task_intention.replace('{', '{{').replace('}', '}}')}'.\n"
+                    ),
+                ),
+                ("placeholder", "{messages}"),
+            ]
+        )
+
+        checker_llm = self.format_check_prompt | self.llm.with_structured_output(output_class)
+        result = checker_llm.invoke({"messages": [("user", str(self.log))]}).dict()
+        return result

Biomanus_upload/biomni/biorxiv_scripts/extract_biorxiv_tasks.py

@@ -0,0 +1,404 @@
+#!/usr/bin/env python3
+"""Script to extract common tasks, databases, and software from bioRxiv papers
+using the PaperTaskExtractor and existing metadata CSV.
+"""
+
+import argparse
+import io
+import json
+import os
+import random
+import sys
+import time
+from typing import Any
+
+import pandas as pd
+import PyPDF2
+import requests
+from tqdm import tqdm
+
+# Add the parent directory to the path so we can import the bioagentos package
+sys.path.append("../../")
+from biomni.agent.env_collection import PaperTaskExtractor
+
+
+def parse_arguments():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="Extract tasks from bioRxiv papers in a specific subject area.")
+    parser.add_argument(
+        "--subject",
+        type=str,
+        required=True,
+        help='Subject area to search for papers (e.g., "neuroscience", "bioinformatics")',
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=10,
+        help="Maximum number of papers to process (default: 10)",
+    )
+    parser.add_argument(
+        "--metadata-path",
+        type=str,
+        default="<REMOTE_USER_HOME>/BioAgentOS/data/biorxiv_metadata.csv",
+        help="Path to bioRxiv metadata CSV file (default: data/biorxiv_metadata.csv)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default=None,
+        help="Directory to save results (default: ./biorxiv_results_{subject}_{limit})",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="claude-3-haiku-20240307",
+        help="LLM model to use for extraction (default: claude-3-haiku-20240307)",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=4000,
+        help="Chunk size for text processing (default: 4000)",
+    )
+    parser.add_argument(
+        "--chunk-overlap",
+        type=int,
+        default=400,
+        help="Chunk overlap for text processing (default: 400)",
+    )
+    parser.add_argument(
+        "--max-paper-length",
+        type=int,
+        default=200000,
+        help="Maximum paper length in characters (default: 200000)",
+    )
+    parser.add_argument("--save-pdfs", action="store_true", help="Save downloaded PDFs (default: False)")
+    parser.add_argument(
+        "--random-sample",
+        action="store_true",
+        help="Randomly sample papers instead of taking the first N (default: False)",
+    )
+    return parser.parse_args()
+
+
+def load_papers_from_csv(metadata_path: str, subject: str, limit: int, random_sample: bool) -> pd.DataFrame:
+    """Load papers from bioRxiv metadata CSV file.
+
+    Args:
+        metadata_path: Path to the metadata CSV file
+        subject: Subject area to filter by
+        limit: Maximum number of papers to return
+        random_sample: Whether to randomly sample papers
+
+    Returns:
+        DataFrame of filtered papers
+
+    """
+    try:
+        # Load the metadata CSV
+        df_biorxiv = pd.read_csv(metadata_path)
+
+        # Filter published papers in the specified subject
+        if subject.lower() == "all":
+            filtered_df = df_biorxiv[df_biorxiv.published != "NA"]
+        else:
+            filtered_df = df_biorxiv[
+                (df_biorxiv.published != "NA") & (df_biorxiv.category.str.lower() == subject.lower())
+            ]
+
+        # Sample papers
+        if len(filtered_df) > limit:
+            filtered_df = filtered_df.sample(limit, random_state=42) if random_sample else filtered_df.head(limit)
+
+        print(f"Loaded {len(filtered_df)} papers in subject: {subject}")
+        return filtered_df
+
+    except Exception as e:
+        print(f"Error loading papers from CSV: {e}")
+        return pd.DataFrame()
+
+
+def download_pdf(paper_doi: str, save_path: str | None = None) -> str | None:
+    """Download PDF for a given paper DOI.
+
+    Args:
+        paper_doi: DOI of the paper
+        save_path: Path to save the PDF (if None, won't save to disk)
+
+    Returns:
+        PDF text content or None if download failed
+
+    """
+    # Construct PDF URL from DOI
+    pdf_url = f"https://www.biorxiv.org/content/{paper_doi}v1.full.pdf"
+
+    try:
+        # Add random delay to avoid rate limiting
+        time.sleep(random.uniform(1, 3))
+
+        response = requests.get(pdf_url, stream=True)
+        response.raise_for_status()
+
+        # Save PDF if requested
+        if save_path:
+            os.makedirs(os.path.dirname(save_path), exist_ok=True)
+            with open(save_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+
+        # Extract text from PDF
+        pdf_text = extract_text_from_pdf(io.BytesIO(response.content))
+        return pdf_text
+
+    except requests.exceptions.RequestException as e:
+        print(f"Error downloading PDF for {paper_doi}: {e}")
+        return None
+
+
+def extract_text_from_pdf(pdf_file) -> str:
+    """Extract text content from a PDF file.
+
+    Args:
+        pdf_file: File-like object containing PDF data
+
+    Returns:
+        Extracted text content
+
+    """
+    try:
+        pdf_reader = PyPDF2.PdfReader(pdf_file)
+        text = ""
+        for page_num in range(len(pdf_reader.pages)):
+            page = pdf_reader.pages[page_num]
+            text += page.extract_text() + "\n\n"
+        return text
+    except Exception as e:
+        print(f"Error extracting text from PDF: {e}")
+        return ""
+
+
+def truncate_text(text: str, max_length: int) -> str:
+    """Truncate text to a maximum length while preserving complete sentences.
+
+    Args:
+        text: The text to truncate
+        max_length: Maximum length in characters
+
+    Returns:
+        Truncated text
+
+    """
+    if len(text) <= max_length:
+        return text
+
+    # Find the last sentence boundary before max_length
+    truncated = text[:max_length]
+    last_period = truncated.rfind(".")
+    last_question = truncated.rfind("?")
+    last_exclamation = truncated.rfind("!")
+
+    # Find the last sentence boundary
+    last_boundary = max(last_period, last_question, last_exclamation)
+
+    if last_boundary > 0:
+        return text[: last_boundary + 1]
+    else:
+        # If no sentence boundary found, just truncate at max_length
+        return truncated
+
+
+def process_papers(papers_df: pd.DataFrame, args) -> list[dict[str, Any]]:
+    """Process papers using PaperTaskExtractor.
+
+    Args:
+        papers_df: DataFrame of paper metadata
+        args: Command line arguments
+
+    Returns:
+        List of papers with extracted tasks, databases, and software
+
+    """
+    # Initialize the task extractor
+    extractor = PaperTaskExtractor(llm=args.model, chunk_size=args.chunk_size, chunk_overlap=args.chunk_overlap)
+
+    results = []
+
+    for _, paper in tqdm(papers_df.iterrows(), total=len(papers_df), desc="Processing papers"):
+        paper_doi = paper.get("doi")
+        if not paper_doi:
+            continue
+
+        print(f"\nProcessing paper: {paper.get('title')} (DOI: {paper_doi})")
+
+        # Create paths
+        pdf_path = None
+        if args.save_pdfs:
+            pdf_path = os.path.join(args.output_dir, "pdfs", f"{paper_doi.replace('/', '_')}.pdf")
+
+        result_path = os.path.join(args.output_dir, "results", f"{paper_doi.replace('/', '_')}.json")
+
+        # Skip if already processed
+        if os.path.exists(result_path):
+            print(f"Paper already processed, loading from {result_path}")
+            with open(result_path) as f:
+                paper_result = json.load(f)
+                results.append(paper_result)
+            continue
+
+        # Download and process PDF
+        pdf_text = download_pdf(paper_doi, pdf_path)
+        if not pdf_text:
+            print(f"Failed to download or extract text from {paper_doi}")
+            continue
+
+        # Truncate text if it exceeds max length
+        if len(pdf_text) > args.max_paper_length:
+            original_length = len(pdf_text)
+            pdf_text = truncate_text(pdf_text, args.max_paper_length)
+            print(f"Truncated paper from {original_length} to {len(pdf_text)} characters")
+
+        # Extract tasks, databases, and software
+        try:
+            _, extraction_results = extractor.go(pdf_text)
+
+            # Add paper metadata to results
+            paper_result = {
+                "metadata": {
+                    "doi": paper.get("doi"),
+                    "title": paper.get("title"),
+                    "authors": paper.get("authors", ""),
+                    "abstract": paper.get("abstract", ""),
+                    "date": paper.get("date", ""),
+                    "category": paper.get("category", ""),
+                    "text_length": len(pdf_text),
+                },
+                "extraction": extraction_results,
+            }
+
+            # Save results
+            os.makedirs(os.path.dirname(result_path), exist_ok=True)
+            with open(result_path, "w") as f:
+                json.dump(paper_result, f, indent=2)
+
+            results.append(paper_result)
+
+        except Exception as e:
+            print(f"Error processing paper {paper_doi}: {e}")
+
+    return results
+
+
+def generate_summary(results: list[dict[str, Any]], output_dir: str):
+    """Generate summary of extracted tasks, databases, and software.
+
+    Args:
+        results: List of papers with extraction results
+        output_dir: Directory to save summary
+
+    """
+    # Collect all tasks, databases, and software
+    all_tasks = []
+    all_databases = []
+    all_software = []
+
+    for paper in results:
+        extraction = paper.get("extraction", {})
+
+        # Add paper metadata to each item
+        paper_meta = paper.get("metadata", {})
+        paper_id = f"{paper_meta.get('title')} ({paper_meta.get('doi')})"
+
+        # Process tasks
+        for task in extraction.get("tasks", []):
+            task["paper"] = paper_id
+            all_tasks.append(task)
+
+        # Process databases
+        for db in extraction.get("databases", []):
+            db["paper"] = paper_id
+            all_databases.append(db)
+
+        # Process software
+        for sw in extraction.get("software", []):
+            sw["paper"] = paper_id
+            all_software.append(sw)
+
+    # Create summary dataframes
+    if all_tasks:
+        tasks_df = pd.DataFrame(all_tasks)
+        tasks_df.to_csv(os.path.join(output_dir, "tasks_summary.csv"), index=False)
+
+    if all_databases:
+        db_df = pd.DataFrame(all_databases)
+        db_df.to_csv(os.path.join(output_dir, "databases_summary.csv"), index=False)
+
+    if all_software:
+        sw_df = pd.DataFrame(all_software)
+        sw_df.to_csv(os.path.join(output_dir, "software_summary.csv"), index=False)
+
+    # Generate frequency counts
+    task_counts = {}
+    for task in all_tasks:
+        task_name = task.get("task_name")
+        if task_name:
+            task_counts[task_name] = task_counts.get(task_name, 0) + 1
+
+    db_counts = {}
+    for db in all_databases:
+        db_name = db.get("name")
+        if db_name:
+            db_counts[db_name] = db_counts.get(db_name, 0) + 1
+
+    sw_counts = {}
+    for sw in all_software:
+        sw_name = sw.get("name")
+        if sw_name:
+            sw_counts[sw_name] = sw_counts.get(sw_name, 0) + 1
+
+    # Save frequency counts
+    with open(os.path.join(output_dir, "frequency_summary.json"), "w") as f:
+        json.dump(
+            {"tasks": task_counts, "databases": db_counts, "software": sw_counts},
+            f,
+            indent=2,
+        )
+
+    print(f"Summary files saved to {output_dir}")
+
+
+def main():
+    """Main function to run the script."""
+    args = parse_arguments()
+
+    # Set default output directory if not specified
+    if args.output_dir is None:
+        # Clean subject name for directory name (replace spaces with underscores, lowercase)
+        clean_subject = args.subject.lower().replace(" ", "_").replace("/", "_")
+        args.output_dir = f"./biorxiv_results_{clean_subject}_{args.limit}"
+
+    # Create output directories
+    os.makedirs(args.output_dir, exist_ok=True)
+    os.makedirs(os.path.join(args.output_dir, "results"), exist_ok=True)
+    if args.save_pdfs:
+        os.makedirs(os.path.join(args.output_dir, "pdfs"), exist_ok=True)
+
+    # Load papers from CSV
+    print(f"Loading papers from {args.metadata_path} in subject area: {args.subject}")
+    papers_df = load_papers_from_csv(args.metadata_path, args.subject, args.limit, args.random_sample)
+
+    if len(papers_df) == 0:
+        print(f"No papers found for subject: {args.subject}")
+        return
+
+    # Process papers
+    results = process_papers(papers_df, args)
+
+    # Generate summary
+    generate_summary(results, args.output_dir)
+
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()

Biomanus_upload/biomni/biorxiv_scripts/generate_function.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Command-line tool to generate Python functions from task descriptions using the function_generator agent."""
+
+import argparse
+import json
+import os
+
+from biomni.agent.function_generator import FunctionGenerator
+from tqdm import tqdm
+
+
+def main():
+    """Main function for the command-line tool."""
+    parser = argparse.ArgumentParser(description="Generate Python functions given task descriptions")
+    parser.add_argument(
+        "--task",
+        "-t",
+        type=str,
+        help="JSON file containing a list of task descriptions",
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        type=str,
+        default="generated_functions",
+        help="Directory to save the generated functions (default: generated_functions)",
+    )
+    parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        default="claude-3-7-sonnet-latest",
+        help="LLM model to use (default: claude-3-7-sonnet-latest)",
+    )
+    parser.add_argument(
+        "--temperature",
+        type=float,
+        default=0.7,
+        help="Temperature setting for the LLM (default: 0.7)",
+    )
+
+    args = parser.parse_args()
+
+    with open(args.task) as f_tasks:
+        task_list = json.load(f_tasks)
+        task_descriptions = list(task_list["tasks"])
+
+    # Create the output directory if it doesn't exist
+    os.makedirs(args.output_dir, exist_ok=True)
+
+    # Initialize the function generator agent
+    function_generator = FunctionGenerator(llm=args.model, temperature=args.temperature)
+
+    if not task_list:
+        print("No tasks found.")
+    else:
+        # tqdm shows a progress bar, file names as description
+        for _i, desc in enumerate(tqdm(task_descriptions, desc="Generating Python scripts given task descriptions"), 1):
+            generated_script_name, generated_codes = function_generator.go(desc)
+
+            # Save results
+            result_path = os.path.join(args.output_dir, generated_script_name)
+
+            os.makedirs(os.path.dirname(result_path), exist_ok=True)
+            with open(result_path, "w") as f:
+                f.write(generated_codes)
+
+        print("DONE")
+
+
+if __name__ == "__main__":
+    main()

Biomanus_upload/biomni/biorxiv_scripts/process_all_subjects.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Script to process all bioRxiv subjects and extract computational tasks from the top 100 papers in each."""
+
+import argparse
+import os
+import subprocess
+import sys
+import time
+
+import pandas as pd
+from tqdm import tqdm
+
+# Add the parent directory to the path so we can import the bioagentos package
+sys.path.append("<REMOTE_USER_HOME>/BioAgentOS/")
+
+# List of all bioRxiv subjects
+BIORXIV_SUBJECTS = [
+    "evolutionary biology",
+    "ecology",
+    "neuroscience",
+    "developmental biology",
+    "plant biology",
+    "microbiology",
+    "cancer biology",
+    "immunology",
+    "cell biology",
+    "biochemistry",
+    "genetics",
+    "bioinformatics",
+    "animal behavior and cognition",
+    "biophysics",
+    "genomics",
+    "systems biology",
+    "bioengineering",
+    "molecular biology",
+    "physiology",
+    "zoology",
+    "scientific communication and education",
+    "pathology",
+    "synthetic biology",
+    "paleontology",
+    "pharmacology and toxicology",
+]
+
+
+def parse_arguments():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="Process all bioRxiv subjects and extract tasks from papers.")
+    parser.add_argument(
+        "--papers-per-subject",
+        type=int,
+        default=100,
+        help="Number of papers to process per subject (default: 100)",
+    )
+    parser.add_argument(
+        "--metadata-path",
+        type=str,
+        default="<REMOTE_USER_HOME>/BioAgentOS/data/biorxiv_metadata.csv",
+        help="Path to bioRxiv metadata CSV file (default: data/biorxiv_metadata.csv)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default="./biorxiv_all_subjects",
+        help="Base directory to save results (default: ./biorxiv_all_subjects)",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="claude-3-haiku-20240307",
+        help="LLM model to use for extraction (default: claude-3-haiku-20240307)",
+    )
+    parser.add_argument(
+        "--max-paper-length",
+        type=int,
+        default=200000,
+        help="Maximum paper length in characters (default: 200000)",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=10000,
+        help="Chunk size for text processing (default: 10000)",
+    )
+    parser.add_argument(
+        "--chunk-overlap",
+        type=int,
+        default=400,
+        help="Chunk overlap for text processing (default: 400)",
+    )
+    parser.add_argument("--save-pdfs", action="store_true", help="Save downloaded PDFs (default: False)")
+    parser.add_argument(
+        "--random-sample",
+        action="store_true",
+        help="Randomly sample papers instead of taking the first N (default: False)",
+    )
+    parser.add_argument(
+        "--subjects",
+        type=str,
+        nargs="+",
+        help="Specific subjects to process (default: all subjects)",
+    )
+    parser.add_argument(
+        "--delay",
+        type=int,
+        default=60,
+        help="Delay in seconds between processing subjects (default: 60)",
+    )
+    parser.add_argument(
+        "--summary-only",
+        action="store_true",
+        help="Only generate the combined summary (default: False)",
+    )
+    return parser.parse_args()
+
+
+def check_subject_availability(metadata_path, subjects):
+    """Check which subjects have papers available in the metadata.
+
+    Args:
+        metadata_path: Path to the metadata CSV file
+        subjects: List of subjects to check
+
+    Returns:
+        List of subjects with available papers
+
+    """
+    try:
+        df_biorxiv = pd.read_csv(metadata_path)
+        available_subjects = []
+
+        for subject in subjects:
+            count = len(
+                df_biorxiv[(df_biorxiv.published != "NA") & (df_biorxiv.category.str.lower() == subject.lower())]
+            )
+            if count > 0:
+                available_subjects.append((subject, count))
+                print(f"Subject '{subject}' has {count} papers available")
+            else:
+                print(f"Subject '{subject}' has no papers available")
+
+        return available_subjects
+    except Exception as e:
+        print(f"Error checking subject availability: {e}")
+        return []
+
+
+def process_subject(subject, args):
+    """Process a single subject by calling the extract_biorxiv_tasks.py script.
+
+    Args:
+        subject: Subject to process
+        args: Command line arguments
+
+    """
+    # Clean subject name for command line
+    subject.replace(" ", "\\ ")
+
+    # Build command
+    cmd = [
+        "python",
+        "BioAgentOS/bioagentos/scripts/extract_biorxiv_tasks.py",
+        "--subject",
+        f'"{subject}"',
+        "--limit",
+        str(args.papers_per_subject),
+        "--metadata-path",
+        args.metadata_path,
+        "--model",
+        args.model,
+        "--max-paper-length",
+        str(args.max_paper_length),
+        "--chunk-size",
+        str(args.chunk_size),
+        "--chunk-overlap",
+        str(args.chunk_overlap),
+    ]
+
+    # Add optional arguments
+    if args.save_pdfs:
+        cmd.append("--save-pdfs")
+    if args.random_sample:
+        cmd.append("--random-sample")
+
+    # Convert command list to string
+    cmd_str = " ".join(cmd)
+
+    print(f"\n{'=' * 80}\nProcessing subject: {subject}\n{'=' * 80}")
+    print(f"Running command: {cmd_str}")
+
+    # Execute command
+    try:
+        subprocess.run(cmd_str, shell=True, check=True)
+        print(f"Successfully processed subject: {subject}")
+    except subprocess.CalledProcessError as e:
+        print(f"Error processing subject '{subject}': {e}")
+
+
+def combine_summaries(base_dir, subjects, papers_per_subject):
+    """Combine frequency summaries from all subjects into a single summary.
+
+    Args:
+        base_dir: Base directory containing subject results
+        subjects: List of subjects that were processed
+        papers_per_subject: Number of papers processed per subject
+
+    """
+    all_tasks = {}
+    all_databases = {}
+    all_software = {}
+
+    for subject, _ in subjects:
+        # Clean subject name for directory name
+        clean_subject = subject.lower().replace(" ", "_").replace("/", "_")
+        subject_dir = f"biorxiv_results_{clean_subject}_{papers_per_subject}"
+        summary_path = os.path.join(subject_dir, "frequency_summary.json")
+
+        try:
+            if os.path.exists(summary_path):
+                with open(summary_path) as f:
+                    summary = json.load(f)
+
+                    # Merge tasks
+                    for task, count in summary.get("tasks", {}).items():
+                        if task in all_tasks:
+                            all_tasks[task] += count
+                        else:
+                            all_tasks[task] = count
+
+                    # Merge databases
+                    for db, count in summary.get("databases", {}).items():
+                        if db in all_databases:
+                            all_databases[db] += count
+                        else:
+                            all_databases[db] = count
+
+                    # Merge software
+                    for sw, count in summary.get("software", {}).items():
+                        if sw in all_software:
+                            all_software[sw] += count
+                        else:
+                            all_software[sw] = count
+            else:
+                print(f"Warning: Summary file not found for subject '{subject}'")
+        except Exception as e:
+            print(f"Error processing summary for subject '{subject}': {e}")
+
+    # Sort by frequency (descending)
+    all_tasks = dict(sorted(all_tasks.items(), key=lambda item: item[1], reverse=True))
+    all_databases = dict(sorted(all_databases.items(), key=lambda item: item[1], reverse=True))
+    all_software = dict(sorted(all_software.items(), key=lambda item: item[1], reverse=True))
+
+    # Create combined summary
+    combined_summary = {
+        "tasks": all_tasks,
+        "databases": all_databases,
+        "software": all_software,
+    }
+
+    # Save combined summary
+    combined_path = os.path.join(base_dir, "combined_summary.json")
+    os.makedirs(base_dir, exist_ok=True)
+
+    with open(combined_path, "w") as f:
+        json.dump(combined_summary, f, indent=2)
+
+    print(f"Combined summary saved to {combined_path}")
+
+    # Create CSV files for each category
+    tasks_df = pd.DataFrame(list(all_tasks.items()), columns=["Task", "Frequency"])
+    tasks_df.to_csv(os.path.join(base_dir, "tasks_frequency.csv"), index=False)
+
+    db_df = pd.DataFrame(list(all_databases.items()), columns=["Database", "Frequency"])
+    db_df.to_csv(os.path.join(base_dir, "databases_frequency.csv"), index=False)
+
+    sw_df = pd.DataFrame(list(all_software.items()), columns=["Software", "Frequency"])
+    sw_df.to_csv(os.path.join(base_dir, "software_frequency.csv"), index=False)
+
+    print(f"CSV summaries saved to {base_dir}")
+
+
+def main():
+    """Main function to run the script."""
+    args = parse_arguments()
+
+    # Determine which subjects to process
+    subjects_to_process = args.subjects if args.subjects else BIORXIV_SUBJECTS
+
+    # Check which subjects have papers available
+    available_subjects = check_subject_availability(args.metadata_path, subjects_to_process)
+
+    if not available_subjects:
+        print("No subjects with available papers found. Exiting.")
+        return
+
+    if not args.summary_only:
+        # Process each subject
+        for subject, _count in tqdm(available_subjects, desc="Processing subjects"):
+            process_subject(subject, args)
+
+            # Add delay between subjects to avoid rate limiting
+            if args.delay > 0:
+                print(f"Waiting {args.delay} seconds before processing the next subject...")
+                time.sleep(args.delay)
+
+    # Combine summaries from all subjects
+    combine_summaries(args.output_dir, available_subjects, args.papers_per_subject)
+
+    print("All subjects processed successfully!")
+
+
+if __name__ == "__main__":
+    import json  # Import here to avoid circular import with the main script
+
+    main()

Biomanus_upload/biomni/config.py

@@ -0,0 +1,119 @@
+"""
+Biomni Configuration Management
+
+Simple configuration class for centralizing common settings.
+Maintains full backward compatibility with existing code.
+"""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class BiomniConfig:
+    """Central configuration for Biomni agent.
+
+    All settings are optional and have sensible defaults.
+    API keys are still read from environment variables to maintain
+    compatibility with existing .env file structure.
+
+    Usage:
+        # Create config with defaults
+        config = BiomniConfig()
+
+        # Override specific settings
+        config = BiomniConfig(llm="gpt-4", timeout_seconds=1200)
+
+        # Modify after creation
+        config.path = "./custom_data"
+    """
+
+    # Data and execution settings
+    path: str = "./data"
+    timeout_seconds: int = 600
+
+    # LLM settings (API keys still from environment)
+    llm: str = "claude-sonnet-4-6"
+    temperature: float = 0.7
+
+    # Tool settings
+    use_tool_retriever: bool = True
+    rewrite_user_query: bool = True
+    dynamic_mcp_registration: bool = True
+    mcp_server_top_k: int = 8
+    mcp_tool_top_k: int = 12
+    mcp_server_candidate_pool: int = 24
+
+    # Data licensing settings
+    commercial_mode: bool = False  # If True, excludes non-commercial datasets
+
+    # Custom model settings (for custom LLM serving)
+    base_url: str | None = None
+    api_key: str | None = None  # Only for custom models, not provider API keys
+
+    # LLM source (auto-detected if None)
+    source: str | None = None
+
+    # Third-party integrations
+    protocols_io_access_token: str | None = None
+
+    def __post_init__(self):
+        """Load any environment variable overrides if they exist."""
+        # Check for environment variable overrides (optional)
+        # Support both old and new names for backwards compatibility
+        if os.getenv("BIOMNI_PATH") or os.getenv("BIOMNI_DATA_PATH"):
+            self.path = os.getenv("BIOMNI_PATH") or os.getenv("BIOMNI_DATA_PATH")
+        if os.getenv("BIOMNI_TIMEOUT_SECONDS"):
+            self.timeout_seconds = int(os.getenv("BIOMNI_TIMEOUT_SECONDS"))
+        if os.getenv("BIOMNI_LLM") or os.getenv("BIOMNI_LLM_MODEL"):
+            self.llm = os.getenv("BIOMNI_LLM") or os.getenv("BIOMNI_LLM_MODEL")
+        if os.getenv("BIOMNI_USE_TOOL_RETRIEVER"):
+            self.use_tool_retriever = os.getenv("BIOMNI_USE_TOOL_RETRIEVER").lower() == "true"
+        if os.getenv("BIOMNI_REWRITE_USER_QUERY"):
+            self.rewrite_user_query = os.getenv("BIOMNI_REWRITE_USER_QUERY").lower() == "true"
+        if os.getenv("BIOMNI_DYNAMIC_MCP_REGISTRATION"):
+            self.dynamic_mcp_registration = os.getenv("BIOMNI_DYNAMIC_MCP_REGISTRATION").lower() == "true"
+        if os.getenv("BIOMNI_MCP_SERVER_TOP_K"):
+            self.mcp_server_top_k = int(os.getenv("BIOMNI_MCP_SERVER_TOP_K"))
+        if os.getenv("BIOMNI_MCP_TOOL_TOP_K"):
+            self.mcp_tool_top_k = int(os.getenv("BIOMNI_MCP_TOOL_TOP_K"))
+        if os.getenv("BIOMNI_MCP_SERVER_CANDIDATE_POOL"):
+            self.mcp_server_candidate_pool = int(os.getenv("BIOMNI_MCP_SERVER_CANDIDATE_POOL"))
+        if os.getenv("BIOMNI_COMMERCIAL_MODE"):
+            self.commercial_mode = os.getenv("BIOMNI_COMMERCIAL_MODE").lower() == "true"
+        if os.getenv("BIOMNI_TEMPERATURE"):
+            self.temperature = float(os.getenv("BIOMNI_TEMPERATURE"))
+        if os.getenv("BIOMNI_CUSTOM_BASE_URL"):
+            self.base_url = os.getenv("BIOMNI_CUSTOM_BASE_URL")
+        if os.getenv("BIOMNI_CUSTOM_API_KEY"):
+            self.api_key = os.getenv("BIOMNI_CUSTOM_API_KEY")
+        if os.getenv("BIOMNI_SOURCE"):
+            self.source = os.getenv("BIOMNI_SOURCE")
+
+        # Protocols.io access token (prefer specific env vars)
+        env_token = os.getenv("PROTOCOLS_IO_ACCESS_TOKEN") or os.getenv("BIOMNI_PROTOCOLS_IO_ACCESS_TOKEN")
+        if env_token:
+            self.protocols_io_access_token = env_token
+
+    def to_dict(self) -> dict:
+        """Convert config to dictionary for easy access."""
+        return {
+            "path": self.path,
+            "timeout_seconds": self.timeout_seconds,
+            "llm": self.llm,
+            "temperature": self.temperature,
+            "use_tool_retriever": self.use_tool_retriever,
+            "rewrite_user_query": self.rewrite_user_query,
+            "dynamic_mcp_registration": self.dynamic_mcp_registration,
+            "mcp_server_top_k": self.mcp_server_top_k,
+            "mcp_tool_top_k": self.mcp_tool_top_k,
+            "mcp_server_candidate_pool": self.mcp_server_candidate_pool,
+            "commercial_mode": self.commercial_mode,
+            "base_url": self.base_url,
+            "api_key": self.api_key,
+            "source": self.source,
+        }
+
+
+# Global default config instance (optional, for convenience)
+default_config = BiomniConfig()

Biomanus_upload/biomni/env_desc.py

@@ -0,0 +1,221 @@
+# Data lake dictionary with detailed descriptions
+data_lake_dict = {
+    "affinity_capture-ms.parquet": "Protein-protein interactions detected via affinity capture and mass spectrometry.",
+    "affinity_capture-rna.parquet": "Protein-RNA interactions detected by affinity capture.",
+    "BindingDB_All_202409.tsv": "Measured binding affinities between proteins and small molecules for drug discovery.",
+    "broad_repurposing_hub_molecule_with_smiles.parquet": "Molecules from Broad Institute's Drug Repurposing Hub with SMILES annotations.",
+    "broad_repurposing_hub_phase_moa_target_info.parquet": "Drug phases, mechanisms of action, and target information from Broad Institute.",
+    "co-fractionation.parquet": "Protein-protein interactions from co-fractionation experiments.",
+    "czi_census_datasets_v4.parquet": "Datasets from the Chan Zuckerberg Initiative's Cell Census.",
+    "DepMap_CRISPRGeneDependency.csv": "Gene dependency probability estimates for cancer cell lines, including all DepMap models.",
+    "DepMap_CRISPRGeneEffect.csv": "Genome-wide CRISPR gene effect estimates for cancer cell lines, including all DepMap models.",
+    "DepMap_Model.csv": "Metadata describing all cancer models/cell lines which are referenced by a dataset contained within the DepMap portal.",
+    "DepMap_OmicsExpressionProteinCodingGenesTPMLogp1.csv": "Gene expression in TPMs for cancer cell lines, including all DepMap models.",
+    "ddinter_alimentary_tract_metabolism.csv": "Drug-drug interactions for alimentary tract and metabolism drugs from DDInter 2.0 database.",
+    "ddinter_antineoplastic.csv": "Drug-drug interactions for antineoplastic and immunomodulating agents from DDInter 2.0 database.",
+    "ddinter_antiparasitic.csv": "Drug-drug interactions for antiparasitic products from DDInter 2.0 database.",
+    "ddinter_blood_organs.csv": "Drug-drug interactions for blood and blood forming organs drugs from DDInter 2.0 database.",
+    "ddinter_dermatological.csv": "Drug-drug interactions for dermatological drugs from DDInter 2.0 database.",
+    "ddinter_hormonal.csv": "Drug-drug interactions for systemic hormonal preparations from DDInter 2.0 database.",
+    "ddinter_respiratory.csv": "Drug-drug interactions for respiratory system drugs from DDInter 2.0 database.",
+    "ddinter_various.csv": "Drug-drug interactions for various drugs from DDInter 2.0 database.",
+    "DisGeNET.parquet": "Gene-disease associations from multiple sources.",
+    "dosage_growth_defect.parquet": "Gene dosage changes affecting growth.",
+    "enamine_cloud_library_smiles.pkl": "Compounds from Enamine REAL library with SMILES annotations.",
+    "evebio_assay_table.csv": "Assay metadata with one row per assay from EveBio pharmome mapping.",
+    "evebio_bundle_table.csv": "Target subfamily bundles used for screening-to-profiling progression.",
+    "evebio_compound_table.csv": "Compound metadata with common identifiers from EveBio screening.",
+    "evebio_control_table.csv": "Control datapoints for all screening and profiling plates.",
+    "evebio_detailed_result_table.csv": "Expanded results on evebio_summary_result_table with curve fit parameters and phase categories.",
+    "evebio_observed_points_table.csv": "Raw observed datapoints from all screening and profiling experiments.",
+    "evebio_summary_result_table.csv": "Succinct summary of results for each assay-compound combination.",
+    "evebio_target_table.csv": "Target metadata with common identifiers from EveBio screening.",
+    "genebass_missense_LC_filtered.pkl": "Filtered missense variants from GeneBass.",
+    "genebass_pLoF_filtered.pkl": "Predicted loss-of-function variants from GeneBass.",
+    "genebass_synonymous_filtered.pkl": "Filtered synonymous variants from GeneBass.",
+    "gene_info.parquet": "Comprehensive gene information.",
+    "genetic_interaction.parquet": "Genetic interactions between genes.",
+    "go-plus.json": "Gene ontology data for functional gene annotations.",
+    "gtex_tissue_gene_tpm.parquet": "Gene expression (TPM) across human tissues from GTEx.",
+    "gwas_catalog.pkl": "Genome-wide association studies (GWAS) results.",
+    "hp.obo": "Official HPO release in obographs format",
+    "kg.csv": "Precision medicine knowledge graph with 17,080 diseases and 4+ million relationships across biological scales.",
+    "marker_celltype.parquet": "Cell type marker genes for identification.",
+    "McPAS-TCR.parquet": "T-cell receptor sequences and specificity data from McPAS database.",
+    "miRDB_v6.0_results.parquet": "Predicted microRNA targets from miRDB.",
+    "miRTarBase_microRNA_target_interaction.parquet": "Experimentally validated microRNA-target interactions from miRTarBase.",
+    "miRTarBase_microRNA_target_interaction_pubmed_abtract.txt": "PubMed abstracts for microRNA-target interactions in miRTarBase.",
+    "miRTarBase_MicroRNA_Target_Sites.parquet": "Binding sites of microRNAs on target genes from miRTarBase.",
+    "mousemine_m1_positional_geneset.parquet": "Positional gene sets from MouseMine.",
+    "mousemine_m2_curated_geneset.parquet": "Curated gene sets from MouseMine.",
+    "mousemine_m3_regulatory_target_geneset.parquet": "Regulatory target gene sets from MouseMine.",
+    "mousemine_m5_ontology_geneset.parquet": "Ontology-based gene sets from MouseMine.",
+    "mousemine_m8_celltype_signature_geneset.parquet": "Cell type signature gene sets from MouseMine.",
+    "mousemine_mh_hallmark_geneset.parquet": "Hallmark gene sets from MouseMine.",
+    "msigdb_human_c1_positional_geneset.parquet": "Human positional gene sets from MSigDB.",
+    "msigdb_human_c2_curated_geneset.parquet": "Curated human gene sets from MSigDB.",
+    "msigdb_human_c3_regulatory_target_geneset.parquet": "Regulatory target gene sets from MSigDB.",
+    "msigdb_human_c3_subset_transcription_factor_targets_from_GTRD.parquet": "Transcription factor targets from GTRD/MSigDB.",
+    "msigdb_human_c4_computational_geneset.parquet": "Computationally derived gene sets from MSigDB.",
+    "msigdb_human_c5_ontology_geneset.parquet": "Ontology-based gene sets from MSigDB.",
+    "msigdb_human_c6_oncogenic_signature_geneset.parquet": "Oncogenic signatures from MSigDB.",
+    "msigdb_human_c7_immunologic_signature_geneset.parquet": "Immunologic signatures from MSigDB.",
+    "msigdb_human_c8_celltype_signature_geneset.parquet": "Cell type signatures from MSigDB.",
+    "msigdb_human_h_hallmark_geneset.parquet": "Hallmark gene sets from MSigDB.",
+    "omim.parquet": "Genetic disorders and associated genes from OMIM.",
+    "proteinatlas.tsv": "Protein expression data from Human Protein Atlas.",
+    "proximity_label-ms.parquet": "Protein interactions via proximity labeling and mass spectrometry.",
+    "reconstituted_complex.parquet": "Protein complexes reconstituted in vitro.",
+    "sgRNA_KO_SP_mouse.txt": "sgRNA knockout data for mouse.",
+    "sgRNA_KO_SP_human.txt": "sgRNA knockout data for human.",
+    "synthetic_growth_defect.parquet": "Synthetic growth defects from genetic interactions.",
+    "synthetic_lethality.parquet": "Synthetic lethal interactions.",
+    "synthetic_rescue.parquet": "Genetic interactions rescuing phenotypes.",
+    "two-hybrid.parquet": "Protein-protein interactions detected by yeast two-hybrid assays.",
+    "variant_table.parquet": "Annotated genetic variants table.",
+    "Virus-Host_PPI_P-HIPSTER_2020.parquet": "Virus-host protein-protein interactions from P-HIPSTER.",
+    "txgnn_name_mapping.pkl": "Name mapping for TXGNN.",
+    "txgnn_prediction.pkl": "Prediction data for TXGNN.",
+}
+
+# Updated library_content as a dictionary with detailed descriptions
+library_content_dict = {
+    # === PYTHON PACKAGES ===
+    # Core Bioinformatics Libraries (Python)
+    "biopython": "[Python Package] A set of tools for biological computation including parsers for bioinformatics files, access to online services, and interfaces to common bioinformatics programs.",
+    "biom-format": "[Python Package] The Biological Observation Matrix (BIOM) format is designed for representing biological sample by observation contingency tables with associated metadata.",
+    "scanpy": "[Python Package] A scalable toolkit for analyzing single-cell gene expression data, specifically designed for large datasets using AnnData.",
+    "scikit-bio": "[Python Package] Data structures, algorithms, and educational resources for bioinformatics, including sequence analysis, phylogenetics, and ordination methods.",
+    "anndata": "[Python Package] A Python package for handling annotated data matrices in memory and on disk, primarily used for single-cell genomics data.",
+    "mudata": "[Python Package] A Python package for multimodal data storage and manipulation, extending AnnData to handle multiple modalities.",
+    "pyliftover": "[Python Package] A Python implementation of UCSC liftOver tool for converting genomic coordinates between genome assemblies.",
+    "biopandas": "[Python Package] A package that provides pandas DataFrames for working with molecular structures and biological data.",
+    "biotite": "[Python Package] A comprehensive library for computational molecular biology, providing tools for sequence analysis, structure analysis, and more.",
+    "lazyslide": "[Python Package] A Python framework that brings interoperable, reproducible whole slide image analysis, enabling seamless histopathology workflows from preprocessing to deep learning.",
+    # Genomics & Variant Analysis (Python)
+    "gget": "[Python Package] A toolkit for accessing genomic databases and retrieving sequences, annotations, and other genomic data.",
+    "lifelines": "[Python Package] A complete survival analysis library for fitting models, plotting, and statistical tests.",
+    # "scvi-tools": "[Python Package] A package for probabilistic modeling of single-cell omics data, including deep generative models.",
+    "gseapy": "[Python Package] A Python wrapper for Gene Set Enrichment Analysis (GSEA) and visualization.",
+    "scrublet": "[Python Package] A tool for detecting doublets in single-cell RNA-seq data.",
+    "cellxgene-census": "[Python Package] A tool for accessing and analyzing the CellxGene Census, a collection of single-cell datasets. To download a dataset, use the download_source_h5ad function with the dataset id as the argument (856c1b98-5727-49da-bf0f-151bdb8cb056, no .h5ad extension).",
+    "hyperopt": "[Python Package] A Python library for optimizing hyperparameters of machine learning algorithms.",
+    "scvelo": "[Python Package] A tool for RNA velocity analysis in single cells using dynamical models.",
+    "pysam": "[Python Package] A Python module for reading, manipulating and writing genomic data sets in SAM/BAM/VCF/BCF formats.",
+    "pyfaidx": "[Python Package] A Python package for efficient random access to FASTA files.",
+    "pyranges": "[Python Package] A Python package for interval manipulation with a pandas-like interface.",
+    "pybedtools": "[Python Package] A Python wrapper for Aaron Quinlan's BEDTools programs.",
+    # "panhumanpy": "A Python package for hierarchical, cross-tissue cell type annotation of human single-cell RNA-seq data",
+    # Structural Biology & Drug Discovery (Python)
+    "rdkit": "[Python Package] A collection of cheminformatics and machine learning tools for working with chemical structures and drug discovery.",
+    "deeppurpose": "[Python Package] A deep learning library for drug-target interaction prediction and virtual screening.",
+    "pyscreener": "[Python Package] A Python package for virtual screening of chemical compounds.",
+    "openbabel": "[Python Package] A chemical toolbox designed to speak the many languages of chemical data, supporting file format conversion and molecular modeling.",
+    "descriptastorus": "[Python Package] A library for computing molecular descriptors for machine learning applications in drug discovery.",
+    # "pymol": "[Python Package] A molecular visualization system for rendering and animating 3D molecular structures.",
+    "openmm": "[Python Package] A toolkit for molecular simulation using high-performance GPU computing.",
+    "pytdc": "[Python Package] A Python package for Therapeutics Data Commons, providing access to machine learning datasets for drug discovery.",
+    # Data Science & Statistical Analysis (Python)
+    "pandas": "[Python Package] A fast, powerful, and flexible data analysis and manipulation library for Python.",
+    "numpy": "[Python Package] The fundamental package for scientific computing with Python, providing support for arrays, matrices, and mathematical functions.",
+    "scipy": "[Python Package] A Python library for scientific and technical computing, including modules for optimization, linear algebra, integration, and statistics.",
+    "scikit-learn": "[Python Package] A machine learning library featuring various classification, regression, and clustering algorithms.",
+    "matplotlib": "[Python Package] A comprehensive library for creating static, animated, and interactive visualizations in Python.",
+    "seaborn": "[Python Package] A statistical data visualization library based on matplotlib with a high-level interface for drawing attractive statistical graphics.",
+    "statsmodels": "[Python Package] A Python module for statistical modeling and econometrics, including descriptive statistics and estimation of statistical models.",
+    "pymc3": "[Python Package] A Python package for Bayesian statistical modeling and probabilistic machine learning.",
+    # "pystan": "[Python Package] A Python interface to Stan, a platform for statistical modeling and high-performance statistical computation.",
+    "umap-learn": "[Python Package] Uniform Manifold Approximation and Projection, a dimension reduction technique.",
+    "faiss-cpu": "[Python Package] A library for efficient similarity search and clustering of dense vectors.",
+    "harmony-pytorch": "[Python Package] A PyTorch implementation of the Harmony algorithm for integrating single-cell data.",
+    # General Bioinformatics & Computational Utilities (Python)
+    "tiledb": "[Python Package] A powerful engine for storing and analyzing large-scale genomic data.",
+    "tiledbsoma": "[Python Package] A library for working with the SOMA (Stack of Matrices) format using TileDB.",
+    "h5py": "[Python Package] A Python interface to the HDF5 binary data format, allowing storage of large amounts of numerical data.",
+    "tqdm": "[Python Package] A fast, extensible progress bar for loops and CLI applications.",
+    "joblib": "[Python Package] A set of tools to provide lightweight pipelining in Python, including transparent disk-caching and parallel computing.",
+    "opencv-python": "[Python Package] OpenCV library for computer vision tasks, useful for image analysis in biological contexts.",
+    "PyPDF2": "[Python Package] A library for working with PDF files, useful for extracting text from scientific papers.",
+    "googlesearch-python": "[Python Package] A library for performing Google searches programmatically.",
+    "scikit-image": "[Python Package] A collection of algorithms for image processing in Python.",
+    "pymed": "[Python Package] A Python library for accessing PubMed articles.",
+    "arxiv": "[Python Package] A Python wrapper for the arXiv API, allowing access to scientific papers.",
+    "scholarly": "[Python Package] A module to retrieve author and publication information from Google Scholar.",
+    "cryosparc-tools": "[Python Package] Tools for working with cryoSPARC, a platform for cryo-EM data processing.",
+    "mageck": "[Python Package] Analysis of CRISPR screen data.",
+    "igraph": "[Python Package] Network analysis and visualization.",
+    "pyscenic": "[Python Package] Analysis of single-cell RNA-seq data and gene regulatory networks.",
+    "cooler": "[Python Package] Storage and analysis of Hi-C data.",
+    "trackpy": "[Python Package] Particle tracking in images and video.",
+    "nnunet": "[Python Package] A deep learning framework for biomedical image segmentation, providing a standardized approach to training and inference.",
+    # "flowcytometrytools": "[Python Package] Analysis and visualization of flow cytometry data.",
+    "cellpose": "[Python Package] Cell segmentation in microscopy images.",
+    "viennarna": "[Python Package] RNA secondary structure prediction.",
+    "PyMassSpec": "[Python Package] Mass spectrometry data analysis.",
+    "python-libsbml": "[Python Package] Working with SBML files for computational biology.",
+    "cobra": "[Python Package] Constraint-based modeling of metabolic networks.",
+    "reportlab": "[Python Package] Creation of PDF documents.",
+    "flowkit": "[Python Package] Toolkit for processing flow cytometry data.",
+    "hmmlearn": "[Python Package] Hidden Markov model analysis.",
+    "msprime": "[Python Package] Simulation of genetic variation.",
+    "tskit": "[Python Package] Handling tree sequences and population genetics data.",
+    "cyvcf2": "[Python Package] Fast parsing of VCF files.",
+    "pykalman": "[Python Package] Kalman filter and smoother implementation.",
+    "fanc": "[Python Package] Analysis of chromatin conformation data.",
+    "loompy": "A Python implementation of the Loom file format for efficiently storing and working with large omics datasets.",
+    "pyBigWig": "A Python library for accessing bigWig and bigBed files for genome browser track data.",
+    "pymzml": "A Python module for high-throughput bioinformatics analysis of mass spectrometry data.",
+    "optlang": "A Python package for modeling optimization problems symbolically.",
+    "FlowIO": "A Python package for reading and writing flow cytometry data files.",
+    "FlowUtils": "Utilities for processing and analyzing flow cytometry data.",
+    "arboreto": "A Python package for inferring gene regulatory networks from single-cell RNA-seq data.",
+    "pdbfixer": "A Python package for fixing problems in PDB files in preparation for molecular simulations.",
+    # === R PACKAGES ===
+    # Core R Packages for Data Analysis
+    "ggplot2": "[R Package] A system for declaratively creating graphics, based on The Grammar of Graphics. Use with subprocess.run(['Rscript', '-e', 'library(ggplot2); ...']).",
+    "dplyr": "[R Package] A grammar of data manipulation, providing a consistent set of verbs that help you solve the most common data manipulation challenges. Use with subprocess.",
+    "tidyr": "[R Package] A package that helps you create tidy data, where each column is a variable, each row is an observation, and each cell is a single value. Use with subprocess.",
+    "readr": "[R Package] A fast and friendly way to read rectangular data like CSV, TSV, and FWF. Use with subprocess.run(['Rscript', '-e', 'library(readr); ...']).",
+    "stringr": "[R Package] A cohesive set of functions designed to make working with strings as easy as possible. Use with subprocess calls.",
+    "Matrix": "[R Package] A package that provides classes and methods for dense and sparse matrices. Required for Seurat. Use with subprocess calls.",
+    # "Rcpp": "[R Package] Seamless R and C++ Integration, allowing R functions to call compiled C++ code. Use with subprocess calls.",
+    # "devtools": "[R Package] Tools to make developing R packages easier, including functions to install packages from GitHub. Use with subprocess calls.",
+    # "remotes": "[R Package] Install R packages from GitHub, GitLab, Bitbucket, or other remote repositories. Use with subprocess calls.",
+    # Bioinformatics R Packages
+    "DESeq2": "[R Package] Differential gene expression analysis based on the negative binomial distribution. Use with subprocess.run(['Rscript', '-e', 'library(DESeq2); ...']).",
+    "clusterProfiler": "[R Package] A package for statistical analysis and visualization of functional profiles for genes and gene clusters. Use with subprocess calls.",
+    # "DADA2": "[R Package] A package for modeling and correcting Illumina-sequenced amplicon errors. Use with subprocess calls.",
+    # "xcms": "[R Package] A package for processing and visualization of LC-MS and GC-MS data. Use with subprocess calls.",
+    # "FlowCore": "[R Package] Basic infrastructure for flow cytometry data. Use with subprocess calls.",
+    "edgeR": "[R Package] Empirical Analysis of Digital Gene Expression Data in R, for differential expression analysis. Use with subprocess calls.",
+    "limma": "[R Package] Linear Models for Microarray Data, for differential expression analysis. Use with subprocess calls.",
+    "harmony": "[R Package] A method for integrating and analyzing single-cell data across datasets. Use with subprocess calls.",
+    "WGCNA": "[R Package] Weighted Correlation Network Analysis for studying biological networks. Use with subprocess calls.",
+    # === CLI TOOLS ===
+    # Sequence Analysis Tools
+    "samtools": "[CLI Tool] A suite of programs for interacting with high-throughput sequencing data. Use with subprocess.run(['samtools', ...]).",
+    "bowtie2": "[CLI Tool] An ultrafast and memory-efficient tool for aligning sequencing reads to long reference sequences. Use with subprocess.run(['bowtie2', ...]).",
+    "bwa": "[CLI Tool] Burrows-Wheeler Aligner for mapping low-divergent sequences against a large reference genome. Use with subprocess.run(['bwa', ...]).",
+    "bedtools": "[CLI Tool] A powerful toolset for genome arithmetic, allowing operations like intersect, merge, count, and complement on genomic features. Use with subprocess.run(['bedtools', ...]).",
+    "macs2": "[CLI Tool] Model-based Analysis of ChIP-Seq data, a tool for identifying transcript factor binding sites.",
+    # Quality Control and Processing Tools
+    "fastqc": "[CLI Tool] A quality control tool for high throughput sequence data. Use with subprocess.run(['fastqc', ...]).",
+    "trimmomatic": "[CLI Tool] A flexible read trimming tool for Illumina NGS data. Use with subprocess.run(['trimmomatic', ...]).",
+    # Multiple Sequence Alignment and Phylogenetics
+    "mafft": "[CLI Tool] A multiple sequence alignment program for unix-like operating systems. Use with subprocess.run(['mafft', ...]).",
+    "Homer": "[CLI Tool] Motif discovery and next-gen sequencing analysis.",
+    "FastTree": "[CLI Tool] Phylogenetic trees from sequence alignments.",
+    "muscle": "[CLI Tool] Multiple sequence alignment tool.",
+    # Genetic Analysis Tools
+    "plink": "[CLI Tool] A comprehensive toolkit for genome association studies that can perform a range of large-scale analyses in a computationally efficient manner. Use with subprocess.run(['plink', ...]).",
+    "plink2": "[CLI Tool] A comprehensive toolkit for genome association studies that can perform a range of large-scale analyses in a computationally efficient manner. Use with subprocess.run(['plink2', ...]).",
+    "gcta64": "[CLI Tool] Genome-wide Complex Trait Analysis (GCTA) tool for estimating the proportion of phenotypic variance explained by genome-wide SNPs and analyzing genetic relationships. Use with subprocess.run(['gcta64', ...]).",
+    "iqtree2": "[CLI Tool] An efficient phylogenetic software for maximum likelihood analysis with built-in model selection and ultrafast bootstrap. Use with subprocess.run(['iqtree2', ...]).",
+    "ADFR": "AutoDock for Receptors suite for molecular docking and virtual screening. ",
+    "diamond": "A sequence aligner for protein and translated DNA searches, designed for high performance analysis of big sequence data. ",
+    "fcsparser": "A command-line tool for parsing and analyzing flow cytometry standard (FCS) files. ",
+    "plannotate": "[CLI Tool] A tool for annotating plasmid sequences with common features. ",
+    "vina": "[CLI Tool] An open-source program for molecular docking and virtual screening, known for its speed and accuracy improvements over AutoDock 4.",
+    "autosite": "[CLI Tool] A binding site detection tool used to identify potential ligand binding pockets on protein structures for molecular docking.",
+    "PyLabRobot": "[Python Package] A Python package for controlling liquid-handling robots and other lab automation equipment.",
+}

Biomanus_upload/biomni/env_desc_cm.py

@@ -0,0 +1,219 @@
+# Data lake dictionary with detailed descriptions (Commercial Mode - Non-commercial datasets commented out)
+data_lake_dict = {
+    "affinity_capture-ms.parquet": "Protein-protein interactions detected via affinity capture and mass spectrometry.",
+    "affinity_capture-rna.parquet": "Protein-RNA interactions detected by affinity capture.",
+    # "BindingDB_All_202409.tsv": "Measured binding affinities between proteins and small molecules for drug discovery.",  # Requires commercial license
+    "broad_repurposing_hub_molecule_with_smiles.parquet": "Molecules from Broad Institute's Drug Repurposing Hub with SMILES annotations.",
+    "broad_repurposing_hub_phase_moa_target_info.parquet": "Drug phases, mechanisms of action, and target information from Broad Institute.",
+    "co-fractionation.parquet": "Protein-protein interactions from co-fractionation experiments.",
+    "czi_census_datasets_v4.parquet": "Datasets from the Chan Zuckerberg Initiative's Cell Census.",
+    "DepMap_CRISPRGeneDependency.csv": "Gene dependency probability estimates for cancer cell lines, including all DepMap models.",
+    "DepMap_CRISPRGeneEffect.csv": "Genome-wide CRISPR gene effect estimates for cancer cell lines, including all DepMap models.",
+    "DepMap_Model.csv": "Metadata describing all cancer models/cell lines which are referenced by a dataset contained within the DepMap portal.",
+    "DepMap_OmicsExpressionProteinCodingGenesTPMLogp1.csv": "Gene expression in TPMs for cancer cell lines, including all DepMap models.",
+    # "ddinter_alimentary_tract_metabolism.csv": "Drug-drug interactions for alimentary tract and metabolism drugs from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_antineoplastic.csv": "Drug-drug interactions for antineoplastic and immunomodulating agents from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_antiparasitic.csv": "Drug-drug interactions for antiparasitic products from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_blood_organs.csv": "Drug-drug interactions for blood and blood forming organs drugs from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_dermatological.csv": "Drug-drug interactions for dermatological drugs from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_hormonal.csv": "Drug-drug interactions for systemic hormonal preparations from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_respiratory.csv": "Drug-drug interactions for respiratory system drugs from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "ddinter_various.csv": "Drug-drug interactions for various drugs from DDInter 2.0 database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "DisGeNET.parquet": "Gene-disease associations from multiple sources.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    "dosage_growth_defect.parquet": "Gene dosage changes affecting growth.",
+    # "enamine_cloud_library_smiles.pkl": "Compounds from Enamine REAL library with SMILES annotations.",  # Proprietary - Requires license
+    # "evebio_assay_table.csv": "Assay metadata with one row per assay from EveBio pharmome mapping.",  # Proprietary - Requires permission
+    # "evebio_bundle_table.csv": "Target subfamily bundles used for screening-to-profiling progression.",  # Proprietary - Requires permission
+    # "evebio_compound_table.csv": "Compound metadata with common identifiers from EveBio screening.",  # Proprietary - Requires permission
+    # "evebio_control_table.csv": "Control datapoints for all screening and profiling plates.",  # Proprietary - Requires permission
+    # "evebio_detailed_result_table.csv": "Expanded results on evebio_summary_result_table with curve fit parameters and phase categories.",  # Proprietary - Requires permission
+    # "evebio_observed_points_table.csv": "Raw observed datapoints from all screening and profiling experiments.",  # Proprietary - Requires permission
+    # "evebio_summary_result_table.csv": "Succinct summary of results for each assay-compound combination.",  # Proprietary - Requires permission
+    # "evebio_target_table.csv": "Target metadata with common identifiers from EveBio screening.",  # Proprietary - Requires permission
+    "genebass_missense_LC_filtered.pkl": "Filtered missense variants from GeneBass.",
+    "genebass_pLoF_filtered.pkl": "Predicted loss-of-function variants from GeneBass.",
+    "genebass_synonymous_filtered.pkl": "Filtered synonymous variants from GeneBass.",
+    "gene_info.parquet": "Comprehensive gene information.",
+    "genetic_interaction.parquet": "Genetic interactions between genes.",
+    "go-plus.json": "Gene ontology data for functional gene annotations.",
+    "gtex_tissue_gene_tpm.parquet": "Gene expression (TPM) across human tissues from GTEx.",
+    "gwas_catalog.pkl": "Genome-wide association studies (GWAS) results.",
+    "hp.obo": "Official HPO release in obographs format",
+    "kg.csv": "Precision medicine knowledge graph with 17,080 diseases and 4+ million relationships across biological scales.",
+    "marker_celltype.parquet": "Cell type marker genes for identification.",
+    # "McPAS-TCR.parquet": "T-cell receptor sequences and specificity data from McPAS database.",  # CC BY-NC-SA 4.0 - Non-commercial only
+    # "miRDB_v6.0_results.parquet": "Predicted microRNA targets from miRDB.",  # Non-commercial use only
+    # "miRTarBase_microRNA_target_interaction.parquet": "Experimentally validated microRNA-target interactions from miRTarBase.",  # CC BY-NC 4.0 - Non-commercial only
+    # "miRTarBase_microRNA_target_interaction_pubmed_abtract.txt": "PubMed abstracts for microRNA-target interactions in miRTarBase.",  # CC BY-NC 4.0 - Non-commercial only
+    # "miRTarBase_MicroRNA_Target_Sites.parquet": "Binding sites of microRNAs on target genes from miRTarBase.",  # CC BY-NC 4.0 - Non-commercial only
+    "mousemine_m1_positional_geneset.parquet": "Positional gene sets from MouseMine.",
+    "mousemine_m2_curated_geneset.parquet": "Curated gene sets from MouseMine.",
+    "mousemine_m3_regulatory_target_geneset.parquet": "Regulatory target gene sets from MouseMine.",
+    "mousemine_m5_ontology_geneset.parquet": "Ontology-based gene sets from MouseMine.",
+    "mousemine_m8_celltype_signature_geneset.parquet": "Cell type signature gene sets from MouseMine.",
+    "mousemine_mh_hallmark_geneset.parquet": "Hallmark gene sets from MouseMine.",
+    # "msigdb_human_c1_positional_geneset.parquet": "Human positional gene sets from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c2_curated_geneset.parquet": "Curated human gene sets from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c3_regulatory_target_geneset.parquet": "Regulatory target gene sets from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c3_subset_transcription_factor_targets_from_GTRD.parquet": "Transcription factor targets from GTRD/MSigDB.",  # Requires commercial license
+    # "msigdb_human_c4_computational_geneset.parquet": "Computationally derived gene sets from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c5_ontology_geneset.parquet": "Ontology-based gene sets from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c6_oncogenic_signature_geneset.parquet": "Oncogenic signatures from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c7_immunologic_signature_geneset.parquet": "Immunologic signatures from MSigDB.",  # Requires commercial license
+    # "msigdb_human_c8_celltype_signature_geneset.parquet": "Cell type signatures from MSigDB.",  # Requires commercial license
+    # "msigdb_human_h_hallmark_geneset.parquet": "Hallmark gene sets from MSigDB.",  # Requires commercial license
+    # "omim.parquet": "Genetic disorders and associated genes from OMIM.",  # Requires commercial license
+    "proteinatlas.tsv": "Protein expression data from Human Protein Atlas.",
+    "proximity_label-ms.parquet": "Protein interactions via proximity labeling and mass spectrometry.",
+    "reconstituted_complex.parquet": "Protein complexes reconstituted in vitro.",
+    "sgRNA_KO_SP_mouse.txt": "sgRNA knockout data for mouse.",
+    "sgRNA_KO_SP_human.txt": "sgRNA knockout data for human.",
+    "synthetic_growth_defect.parquet": "Synthetic growth defects from genetic interactions.",
+    "synthetic_lethality.parquet": "Synthetic lethal interactions.",
+    "synthetic_rescue.parquet": "Genetic interactions rescuing phenotypes.",
+    "two-hybrid.parquet": "Protein-protein interactions detected by yeast two-hybrid assays.",
+    "variant_table.parquet": "Annotated genetic variants table.",
+    "Virus-Host_PPI_P-HIPSTER_2020.parquet": "Virus-host protein-protein interactions from P-HIPSTER.",
+    "txgnn_name_mapping.pkl": "Name mapping for TXGNN.",
+    "txgnn_prediction.pkl": "Prediction data for TXGNN.",
+}
+
+# Updated library_content as a dictionary with detailed descriptions
+library_content_dict = {
+    # === PYTHON PACKAGES ===
+    # Core Bioinformatics Libraries (Python)
+    "biopython": "[Python Package] A set of tools for biological computation including parsers for bioinformatics files, access to online services, and interfaces to common bioinformatics programs.",
+    "biom-format": "[Python Package] The Biological Observation Matrix (BIOM) format is designed for representing biological sample by observation contingency tables with associated metadata.",
+    "scanpy": "[Python Package] A scalable toolkit for analyzing single-cell gene expression data, specifically designed for large datasets using AnnData.",
+    "scikit-bio": "[Python Package] Data structures, algorithms, and educational resources for bioinformatics, including sequence analysis, phylogenetics, and ordination methods.",
+    "anndata": "[Python Package] A Python package for handling annotated data matrices in memory and on disk, primarily used for single-cell genomics data.",
+    "mudata": "[Python Package] A Python package for multimodal data storage and manipulation, extending AnnData to handle multiple modalities.",
+    "pyliftover": "[Python Package] A Python implementation of UCSC liftOver tool for converting genomic coordinates between genome assemblies.",
+    "biopandas": "[Python Package] A package that provides pandas DataFrames for working with molecular structures and biological data.",
+    "biotite": "[Python Package] A comprehensive library for computational molecular biology, providing tools for sequence analysis, structure analysis, and more.",
+    "lazyslide": "[Python Package] A Python framework that brings interoperable, reproducible whole slide image analysis, enabling seamless histopathology workflows from preprocessing to deep learning.",
+    # Genomics & Variant Analysis (Python)
+    "gget": "[Python Package] A toolkit for accessing genomic databases and retrieving sequences, annotations, and other genomic data.",
+    "lifelines": "[Python Package] A complete survival analysis library for fitting models, plotting, and statistical tests.",
+    # "scvi-tools": "[Python Package] A package for probabilistic modeling of single-cell omics data, including deep generative models.",
+    "gseapy": "[Python Package] A Python wrapper for Gene Set Enrichment Analysis (GSEA) and visualization.",
+    "scrublet": "[Python Package] A tool for detecting doublets in single-cell RNA-seq data.",
+    "cellxgene-census": "[Python Package] A tool for accessing and analyzing the CellxGene Census, a collection of single-cell datasets. To download a dataset, use the download_source_h5ad function with the dataset id as the argument (856c1b98-5727-49da-bf0f-151bdb8cb056, no .h5ad extension).",
+    "hyperopt": "[Python Package] A Python library for optimizing hyperparameters of machine learning algorithms.",
+    "scvelo": "[Python Package] A tool for RNA velocity analysis in single cells using dynamical models.",
+    "pysam": "[Python Package] A Python module for reading, manipulating and writing genomic data sets in SAM/BAM/VCF/BCF formats.",
+    "pyfaidx": "[Python Package] A Python package for efficient random access to FASTA files.",
+    "pyranges": "[Python Package] A Python package for interval manipulation with a pandas-like interface.",
+    "pybedtools": "[Python Package] A Python wrapper for Aaron Quinlan's BEDTools programs.",
+    # "panhumanpy": "A Python package for hierarchical, cross-tissue cell type annotation of human single-cell RNA-seq data",
+    # Structural Biology & Drug Discovery (Python)
+    "rdkit": "[Python Package] A collection of cheminformatics and machine learning tools for working with chemical structures and drug discovery.",
+    "deeppurpose": "[Python Package] A deep learning library for drug-target interaction prediction and virtual screening.",
+    "pyscreener": "[Python Package] A Python package for virtual screening of chemical compounds.",
+    "openbabel": "[Python Package] A chemical toolbox designed to speak the many languages of chemical data, supporting file format conversion and molecular modeling.",
+    "descriptastorus": "[Python Package] A library for computing molecular descriptors for machine learning applications in drug discovery.",
+    # "pymol": "[Python Package] A molecular visualization system for rendering and animating 3D molecular structures.",
+    "openmm": "[Python Package] A toolkit for molecular simulation using high-performance GPU computing.",
+    "pytdc": "[Python Package] A Python package for Therapeutics Data Commons, providing access to machine learning datasets for drug discovery.",
+    # Data Science & Statistical Analysis (Python)
+    "pandas": "[Python Package] A fast, powerful, and flexible data analysis and manipulation library for Python.",
+    "numpy": "[Python Package] The fundamental package for scientific computing with Python, providing support for arrays, matrices, and mathematical functions.",
+    "scipy": "[Python Package] A Python library for scientific and technical computing, including modules for optimization, linear algebra, integration, and statistics.",
+    "scikit-learn": "[Python Package] A machine learning library featuring various classification, regression, and clustering algorithms.",
+    "matplotlib": "[Python Package] A comprehensive library for creating static, animated, and interactive visualizations in Python.",
+    "seaborn": "[Python Package] A statistical data visualization library based on matplotlib with a high-level interface for drawing attractive statistical graphics.",
+    "statsmodels": "[Python Package] A Python module for statistical modeling and econometrics, including descriptive statistics and estimation of statistical models.",
+    "pymc3": "[Python Package] A Python package for Bayesian statistical modeling and probabilistic machine learning.",
+    # "pystan": "[Python Package] A Python interface to Stan, a platform for statistical modeling and high-performance statistical computation.",
+    "umap-learn": "[Python Package] Uniform Manifold Approximation and Projection, a dimension reduction technique.",
+    "faiss-cpu": "[Python Package] A library for efficient similarity search and clustering of dense vectors.",
+    "harmony-pytorch": "[Python Package] A PyTorch implementation of the Harmony algorithm for integrating single-cell data.",
+    # General Bioinformatics & Computational Utilities (Python)
+    "tiledb": "[Python Package] A powerful engine for storing and analyzing large-scale genomic data.",
+    "tiledbsoma": "[Python Package] A library for working with the SOMA (Stack of Matrices) format using TileDB.",
+    "h5py": "[Python Package] A Python interface to the HDF5 binary data format, allowing storage of large amounts of numerical data.",
+    "tqdm": "[Python Package] A fast, extensible progress bar for loops and CLI applications.",
+    "joblib": "[Python Package] A set of tools to provide lightweight pipelining in Python, including transparent disk-caching and parallel computing.",
+    "opencv-python": "[Python Package] OpenCV library for computer vision tasks, useful for image analysis in biological contexts.",
+    "PyPDF2": "[Python Package] A library for working with PDF files, useful for extracting text from scientific papers.",
+    "googlesearch-python": "[Python Package] A library for performing Google searches programmatically.",
+    "scikit-image": "[Python Package] A collection of algorithms for image processing in Python.",
+    "pymed": "[Python Package] A Python library for accessing PubMed articles.",
+    "arxiv": "[Python Package] A Python wrapper for the arXiv API, allowing access to scientific papers.",
+    "scholarly": "[Python Package] A module to retrieve author and publication information from Google Scholar.",
+    "cryosparc-tools": "[Python Package] Tools for working with cryoSPARC, a platform for cryo-EM data processing.",
+    "mageck": "[Python Package] Analysis of CRISPR screen data.",
+    "igraph": "[Python Package] Network analysis and visualization.",
+    "pyscenic": "[Python Package] Analysis of single-cell RNA-seq data and gene regulatory networks.",
+    "cooler": "[Python Package] Storage and analysis of Hi-C data.",
+    "trackpy": "[Python Package] Particle tracking in images and video.",
+    # "flowcytometrytools": "[Python Package] Analysis and visualization of flow cytometry data.",
+    "cellpose": "[Python Package] Cell segmentation in microscopy images.",
+    "viennarna": "[Python Package] RNA secondary structure prediction.",
+    "PyMassSpec": "[Python Package] Mass spectrometry data analysis.",
+    "python-libsbml": "[Python Package] Working with SBML files for computational biology.",
+    "cobra": "[Python Package] Constraint-based modeling of metabolic networks.",
+    "reportlab": "[Python Package] Creation of PDF documents.",
+    "flowkit": "[Python Package] Toolkit for processing flow cytometry data.",
+    "hmmlearn": "[Python Package] Hidden Markov model analysis.",
+    "msprime": "[Python Package] Simulation of genetic variation.",
+    "tskit": "[Python Package] Handling tree sequences and population genetics data.",
+    "cyvcf2": "[Python Package] Fast parsing of VCF files.",
+    "pykalman": "[Python Package] Kalman filter and smoother implementation.",
+    "fanc": "[Python Package] Analysis of chromatin conformation data.",
+    "loompy": "A Python implementation of the Loom file format for efficiently storing and working with large omics datasets.",
+    "pyBigWig": "A Python library for accessing bigWig and bigBed files for genome browser track data.",
+    "pymzml": "A Python module for high-throughput bioinformatics analysis of mass spectrometry data.",
+    "optlang": "A Python package for modeling optimization problems symbolically.",
+    "FlowIO": "A Python package for reading and writing flow cytometry data files.",
+    "FlowUtils": "Utilities for processing and analyzing flow cytometry data.",
+    "arboreto": "A Python package for inferring gene regulatory networks from single-cell RNA-seq data.",
+    "pdbfixer": "A Python package for fixing problems in PDB files in preparation for molecular simulations.",
+    # === R PACKAGES ===
+    # Core R Packages for Data Analysis
+    "ggplot2": "[R Package] A system for declaratively creating graphics, based on The Grammar of Graphics. Use with subprocess.run(['Rscript', '-e', 'library(ggplot2); ...']).",
+    "dplyr": "[R Package] A grammar of data manipulation, providing a consistent set of verbs that help you solve the most common data manipulation challenges. Use with subprocess.",
+    "tidyr": "[R Package] A package that helps you create tidy data, where each column is a variable, each row is an observation, and each cell is a single value. Use with subprocess.",
+    "readr": "[R Package] A fast and friendly way to read rectangular data like CSV, TSV, and FWF. Use with subprocess.run(['Rscript', '-e', 'library(readr); ...']).",
+    "stringr": "[R Package] A cohesive set of functions designed to make working with strings as easy as possible. Use with subprocess calls.",
+    "Matrix": "[R Package] A package that provides classes and methods for dense and sparse matrices. Required for Seurat. Use with subprocess calls.",
+    # "Rcpp": "[R Package] Seamless R and C++ Integration, allowing R functions to call compiled C++ code. Use with subprocess calls.",
+    # "devtools": "[R Package] Tools to make developing R packages easier, including functions to install packages from GitHub. Use with subprocess calls.",
+    # "remotes": "[R Package] Install R packages from GitHub, GitLab, Bitbucket, or other remote repositories. Use with subprocess calls.",
+    # Bioinformatics R Packages
+    "DESeq2": "[R Package] Differential gene expression analysis based on the negative binomial distribution. Use with subprocess.run(['Rscript', '-e', 'library(DESeq2); ...']).",
+    "clusterProfiler": "[R Package] A package for statistical analysis and visualization of functional profiles for genes and gene clusters. Use with subprocess calls.",
+    # "DADA2": "[R Package] A package for modeling and correcting Illumina-sequenced amplicon errors. Use with subprocess calls.",
+    # "xcms": "[R Package] A package for processing and visualization of LC-MS and GC-MS data. Use with subprocess calls.",
+    # "FlowCore": "[R Package] Basic infrastructure for flow cytometry data. Use with subprocess calls.",
+    "edgeR": "[R Package] Empirical Analysis of Digital Gene Expression Data in R, for differential expression analysis. Use with subprocess calls.",
+    "limma": "[R Package] Linear Models for Microarray Data, for differential expression analysis. Use with subprocess calls.",
+    "harmony": "[R Package] A method for integrating and analyzing single-cell data across datasets. Use with subprocess calls.",
+    "WGCNA": "[R Package] Weighted Correlation Network Analysis for studying biological networks. Use with subprocess calls.",
+    # === CLI TOOLS ===
+    # Sequence Analysis Tools
+    "samtools": "[CLI Tool] A suite of programs for interacting with high-throughput sequencing data. Use with subprocess.run(['samtools', ...]).",
+    "bowtie2": "[CLI Tool] An ultrafast and memory-efficient tool for aligning sequencing reads to long reference sequences. Use with subprocess.run(['bowtie2', ...]).",
+    "bwa": "[CLI Tool] Burrows-Wheeler Aligner for mapping low-divergent sequences against a large reference genome. Use with subprocess.run(['bwa', ...]).",
+    "bedtools": "[CLI Tool] A powerful toolset for genome arithmetic, allowing operations like intersect, merge, count, and complement on genomic features. Use with subprocess.run(['bedtools', ...]).",
+    "macs2": "[CLI Tool] Model-based Analysis of ChIP-Seq data, a tool for identifying transcript factor binding sites.",
+    # Quality Control and Processing Tools
+    "fastqc": "[CLI Tool] A quality control tool for high throughput sequence data. Use with subprocess.run(['fastqc', ...]).",
+    "trimmomatic": "[CLI Tool] A flexible read trimming tool for Illumina NGS data. Use with subprocess.run(['trimmomatic', ...]).",
+    # Multiple Sequence Alignment and Phylogenetics
+    "mafft": "[CLI Tool] A multiple sequence alignment program for unix-like operating systems. Use with subprocess.run(['mafft', ...]).",
+    "Homer": "[CLI Tool] Motif discovery and next-gen sequencing analysis.",
+    "FastTree": "[CLI Tool] Phylogenetic trees from sequence alignments.",
+    "muscle": "[CLI Tool] Multiple sequence alignment tool.",
+    # Genetic Analysis Tools
+    "plink": "[CLI Tool] A comprehensive toolkit for genome association studies that can perform a range of large-scale analyses in a computationally efficient manner. Use with subprocess.run(['plink', ...]).",
+    "plink2": "[CLI Tool] A comprehensive toolkit for genome association studies that can perform a range of large-scale analyses in a computationally efficient manner. Use with subprocess.run(['plink2', ...]).",
+    "gcta64": "[CLI Tool] Genome-wide Complex Trait Analysis (GCTA) tool for estimating the proportion of phenotypic variance explained by genome-wide SNPs and analyzing genetic relationships. Use with subprocess.run(['gcta64', ...]).",
+    "iqtree2": "[CLI Tool] An efficient phylogenetic software for maximum likelihood analysis with built-in model selection and ultrafast bootstrap. Use with subprocess.run(['iqtree2', ...]).",
+    "ADFR": "AutoDock for Receptors suite for molecular docking and virtual screening. ",
+    "diamond": "A sequence aligner for protein and translated DNA searches, designed for high performance analysis of big sequence data. ",
+    "fcsparser": "A command-line tool for parsing and analyzing flow cytometry standard (FCS) files. ",
+    "plannotate": "[CLI Tool] A tool for annotating plasmid sequences with common features. ",
+    "vina": "[CLI Tool] An open-source program for molecular docking and virtual screening, known for its speed and accuracy improvements over AutoDock 4.",
+    "autosite": "[CLI Tool] A binding site detection tool used to identify potential ligand binding pockets on protein structures for molecular docking.",
+}

Biomanus_upload/biomni/eval/__init__.py

@@ -0,0 +1,3 @@
+from .biomni_eval1 import BiomniEval1
+
+__all__ = ["BiomniEval1"]

Biomanus_upload/biomni/eval/biomni_eval1.py

@@ -0,0 +1,324 @@
+"""
+BiomniEval1: Evaluation loader for Biomni tasks
+
+This class provides a unified interface to evaluate user answers against ground truth
+for all tasks in the BiomniEval1 benchmark.
+"""
+
+import json
+from typing import Any
+
+import pandas as pd
+
+
+class BiomniEval1:
+    """
+    Evaluation loader for BiomniEval1 benchmark
+
+    Usage:
+        evaluator = BiomniEval1('biomni_eval1_dataset.parquet')
+        score = evaluator.evaluate('gwas_causal_gene_opentargets', 0, 'BRCA1')
+    """
+
+    def __init__(self):
+        """
+        Initialize the BiomniEval1 evaluator
+
+        Args:
+            dataset_path: Path to the merged dataset parquet file
+        """
+
+        self.df = pd.read_parquet("hf://datasets/biomni/Eval1/biomni_eval1_dataset.parquet")
+
+        # Create index mapping for fast lookup using task_instance_id
+        self.instance_map = {}
+        for idx, row in self.df.iterrows():
+            key = (row["task_name"], row["task_instance_id"])
+            self.instance_map[key] = idx
+
+        print(f"Loaded BiomniEval1 dataset: {len(self.df)} instances across {self.df['task_name'].nunique()} tasks")
+
+    def evaluate(self, task_name: str, task_instance_id: int, user_answer: str) -> float:
+        """
+        Evaluate a user's answer for a given task and instance
+
+        Args:
+            task_name: Name of the task (e.g., 'gwas_causal_gene_opentargets')
+            task_instance_id: Task-specific instance ID (not the global instance_id)
+            user_answer: User's answer (format depends on task)
+
+        Returns:
+            float: Reward score (0.0 to 1.0)
+        """
+        # Look up the instance in the dataset using task_instance_id
+        key = (task_name, task_instance_id)
+        if key not in self.instance_map:
+            raise ValueError(f"Instance not found: task={task_name}, task_instance_id={task_instance_id}")
+
+        df_idx = self.instance_map[key]
+        row = self.df.iloc[df_idx]
+        ground_truth = row["answer"]
+
+        # Call task-specific evaluation function
+        try:
+            reward = self._compute_reward(task_name, user_answer, ground_truth)
+            return float(reward)
+
+        except Exception as e:
+            # Preserve original traceback context for easier debugging
+            raise RuntimeError(f"Error computing reward for {task_name} instance {task_instance_id}: {e}") from e
+
+    def _compute_reward(self, task_name: str, user_answer: str, ground_truth: str) -> float:
+        """Compute reward using task-specific logic"""
+
+        if task_name == "crispr_delivery":
+            # CRISPR expects answer as a letter (a-f), exact match
+            return 1.0 if user_answer.strip().lower() == ground_truth.strip().lower() else 0.0
+
+        elif task_name.startswith("gwas_causal_gene"):
+            # GWAS causal gene expects exact gene match (case-insensitive)
+            return 1.0 if user_answer.strip().upper() == ground_truth.strip().upper() else 0.0
+
+        elif task_name == "gwas_variant_prioritization":
+            # GWAS variant expects exact variant match
+            return 1.0 if user_answer.strip() == ground_truth.strip() else 0.0
+
+        elif task_name == "hle":
+            # HLE expects letter answer (A-Z), case-insensitive
+            return 1.0 if user_answer.strip().upper() == ground_truth.strip().upper() else 0.0
+
+        elif task_name.startswith("lab_bench"):
+            # Lab bench expects letter answer (A-Z), case-insensitive
+            return 1.0 if user_answer.strip().upper() == ground_truth.strip().upper() else 0.0
+
+        elif task_name == "rare_disease_diagnosis":
+            # Rare disease expects JSON with OMIM_ID match
+            # Parse both user answer and ground truth
+            try:
+                if isinstance(user_answer, str):
+                    try:
+                        user_dict = json.loads(user_answer)
+                    except json.JSONDecodeError:
+                        import ast
+
+                        user_dict = ast.literal_eval(user_answer)
+                else:
+                    user_dict = user_answer
+
+                if isinstance(ground_truth, str):
+                    gt_dict = json.loads(ground_truth)
+                else:
+                    gt_dict = ground_truth
+
+                # Compare OMIM_ID
+                return 1.0 if user_dict.get("OMIM_ID") == gt_dict.get("OMIM_ID") else 0.0
+
+            except Exception:
+                return 0.0
+
+        elif task_name == "screen_gene_retrieval":
+            # Screen gene retrieval expects gene symbol (case-insensitive)
+            return 1.0 if user_answer.strip().upper() == ground_truth.strip().upper() else 0.0
+
+        elif task_name == "patient_gene_detection":
+            # Patient gene detection expects JSON with causal_gene list
+            # Ground truth is a comma-separated string or single gene ID
+            try:
+                if isinstance(user_answer, str):
+                    try:
+                        user_dict = json.loads(user_answer)
+                    except json.JSONDecodeError:
+                        import ast
+
+                        user_dict = ast.literal_eval(user_answer)
+                else:
+                    user_dict = user_answer
+
+                # Get predicted genes
+                predicted_genes = user_dict.get("causal_gene", [])
+                if not isinstance(predicted_genes, list):
+                    predicted_genes = [predicted_genes]
+
+                # Get ground truth genes (stored as comma-separated or single)
+                if "," in ground_truth:
+                    true_genes = [g.strip() for g in ground_truth.split(",")]
+                else:
+                    true_genes = [ground_truth]
+
+                # Check for intersection
+                if predicted_genes and set(true_genes) & set(predicted_genes):
+                    return 1.0
+                else:
+                    return 0.0
+
+            except Exception:
+                return 0.0
+
+        else:
+            raise ValueError(f"Unknown task: {task_name}")
+
+    def get_instance(self, task_name: str, task_instance_id: int) -> dict[str, Any]:
+        """
+        Get information about a specific instance
+
+        Args:
+            task_name: Name of the task
+            task_instance_id: Task-specific instance ID
+
+        Returns:
+            dict: Instance information including prompt, answer, etc.
+        """
+        key = (task_name, task_instance_id)
+        if key not in self.instance_map:
+            raise ValueError(f"Instance not found: task={task_name}, task_instance_id={task_instance_id}")
+
+        df_idx = self.instance_map[key]
+        row = self.df.iloc[df_idx]
+
+        return {
+            "global_instance_id": row["instance_id"],
+            "task_instance_id": row["task_instance_id"],
+            "task_name": row["task_name"],
+            "split": row["split"],
+            "prompt": row["prompt"],
+            "answer": row["answer"],
+        }
+
+    def list_tasks(self) -> list:
+        """Get list of all available tasks"""
+        return sorted(self.df["task_name"].unique().tolist())
+
+    def get_task_stats(self, task_name: str = None) -> dict[str, Any]:
+        """
+        Get statistics for a task or all tasks
+
+        Args:
+            task_name: Optional task name to filter by
+
+        Returns:
+            dict: Statistics including counts by split
+        """
+        if task_name:
+            task_df = self.df[self.df["task_name"] == task_name]
+            if len(task_df) == 0:
+                raise ValueError(f"Task not found: {task_name}")
+        else:
+            task_df = self.df
+
+        stats = {
+            "total_instances": len(task_df),
+            "train_instances": len(task_df[task_df["split"] == "train"]),
+            "val_instances": len(task_df[task_df["split"] == "val"]),
+        }
+
+        if not task_name:
+            stats["tasks"] = {}
+            for tn in self.list_tasks():
+                stats["tasks"][tn] = self.get_task_stats(tn)
+
+        return stats
+
+    def batch_evaluate(self, evaluations: list) -> list:
+        """
+        Evaluate multiple instances at once
+
+        Args:
+            evaluations: List of tuples (task_name, task_instance_id, user_answer)
+
+        Returns:
+            list: List of reward scores
+        """
+        results = []
+        for task_name, task_instance_id, user_answer in evaluations:
+            try:
+                score = self.evaluate(task_name, task_instance_id, user_answer)
+                results.append(score)
+            except Exception as e:
+                print(f"Error evaluating {task_name} instance {task_instance_id}: {e}")
+                results.append(0.0)
+
+        return results
+
+    def get_instances_by_task(self, task_name: str, split: str = None) -> pd.DataFrame:
+        """
+        Get all instances for a specific task
+
+        Args:
+            task_name: Name of the task
+            split: Optional split filter ('train' or 'val')
+
+        Returns:
+            DataFrame with instances
+        """
+        task_df = self.df[self.df["task_name"] == task_name]
+
+        if split:
+            task_df = task_df[task_df["split"] == split]
+
+        return task_df.copy()
+
+    def __repr__(self):
+        return f"BiomniEval1(instances={len(self.df)}, tasks={self.df['task_name'].nunique()})"
+
+    def __len__(self):
+        return len(self.df)
+
+
+def main():
+    """Demo usage of BiomniEval1"""
+    evaluator = BiomniEval1()
+
+    print("\nAvailable tasks:")
+    for task in evaluator.list_tasks():
+        print(f"  - {task}")
+
+    print("\nOverall statistics:")
+    stats = evaluator.get_task_stats()
+    print(f"  Total instances: {stats['total_instances']}")
+    print(f"  Train: {stats['train_instances']}, Val: {stats['val_instances']}")
+
+    print("\nPer-task statistics:")
+    for task_name in evaluator.list_tasks():
+        task_stats = evaluator.get_task_stats(task_name)
+        print(
+            f"  {task_name}: {task_stats['total_instances']} total ({task_stats['train_instances']} train, {task_stats['val_instances']} val)"
+        )
+
+    # Example evaluation
+    print("\n" + "=" * 60)
+    print("Example evaluation:")
+    print("=" * 60)
+
+    # Get first instance from gwas_variant_prioritization
+    first_instance = evaluator.df[evaluator.df["task_name"] == "gwas_variant_prioritization"].iloc[0]
+    task_name = first_instance["task_name"]
+    task_instance_id = first_instance["task_instance_id"]
+    ground_truth = first_instance["answer"]
+
+    print(f"\nTask: {task_name}")
+    print(f"Task Instance ID: {task_instance_id}")
+    print(f"Ground truth: {ground_truth}")
+    print(f"Prompt preview: {first_instance['prompt'][:200]}...")
+
+    # Test with correct answer
+    score = evaluator.evaluate(task_name, task_instance_id, ground_truth)
+    print(f"\nScore (correct answer '{ground_truth}'): {score}")
+
+    # Test with wrong answer
+    score = evaluator.evaluate(task_name, task_instance_id, "wrong_answer")
+    print(f"Score (wrong answer 'wrong_answer'): {score}")
+
+    # Batch evaluation example
+    print("\n" + "=" * 60)
+    print("Batch evaluation example:")
+    print("=" * 60)
+    batch_evals = [
+        (task_name, task_instance_id, ground_truth),  # Correct
+        (task_name, task_instance_id, "wrong"),  # Wrong
+    ]
+    scores = evaluator.batch_evaluate(batch_evals)
+    print(f"Batch scores: {scores}")
+
+
+if __name__ == "__main__":
+    main()

Biomanus_upload/biomni/graph/__init__.py

@@ -0,0 +1,17 @@
+from biomni.graph.graph_rag import MCPGraphRAGRetriever
+from biomni.graph.graph_router import GraphRouter
+from biomni.graph.planning_agent import GraphPlanningAgent
+from biomni.graph.schema_extractor import ToolSchemaExtractor
+from biomni.graph.tool_graph import ToolGraph
+from biomni.graph.workflow_priors import WORKFLOW_PRIORS, WorkflowPrior, rank_workflow_priors
+
+__all__ = [
+    "GraphPlanningAgent",
+    "GraphRouter",
+    "MCPGraphRAGRetriever",
+    "ToolSchemaExtractor",
+    "ToolGraph",
+    "WORKFLOW_PRIORS",
+    "WorkflowPrior",
+    "rank_workflow_priors",
+]

Biomanus_upload/biomni/graph/graph_rag.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import re
+
+from biomni.graph.tool_graph import ToolGraph
+
+
+class MCPGraphRAGRetriever:
+    """Generic GraphRAG retriever over the full MCP tool graph.
+
+    This class intentionally avoids benchmark- or task-specific allow/deny
+    policies. It only retrieves a compact graph context from semantic overlap
+    between the query and graph nodes; the agentic planner decides how to use
+    the retrieved graph.
+    """
+
+    TOKEN_PATTERN = re.compile(r"[a-z0-9_+-]+")
+    STAGE_RANK = {
+        "input_acquisition": 0,
+        "preprocessing": 1,
+        "analysis": 2,
+        "downstream": 3,
+        "reporting": 4,
+    }
+    GENERIC_TOKENS = {
+        "answer",
+        "based",
+        "biological",
+        "case",
+        "choice",
+        "choices",
+        "data",
+        "following",
+        "question",
+        "result",
+        "task",
+        "tool",
+        "using",
+        "which",
+    }
+
+    def retrieve(
+        self,
+        *,
+        query_context: dict,
+        query_semantics: dict,
+        tool_graph: ToolGraph,
+        candidate_pool: int = 24,
+        top_k_tools: int = 12,
+    ) -> dict:
+        query_tokens = self._query_tokens(query_context, query_semantics)
+        query_operations = set(query_semantics.get("operations", []))
+        query_capabilities = set(query_semantics.get("capabilities", []))
+        query_datatypes = set(query_semantics.get("datatypes", []))
+        query_stages = set(query_semantics.get("stages", []))
+
+        candidates = []
+        for server_name, payload in tool_graph.server_index.items():
+            server_entry = tool_graph.get_server_entry(server_name) or {}
+            server_text = self._server_text(server_name, server_entry, payload)
+            server_tokens = self._tokenize(server_text)
+            server_overlap = query_tokens & server_tokens
+
+            for tool in payload.get("tools", []):
+                score, reasons = self._score_tool(
+                    server_name=server_name,
+                    server_tokens=server_tokens,
+                    server_overlap=server_overlap,
+                    tool=tool,
+                    query_tokens=query_tokens,
+                    query_operations=query_operations,
+                    query_capabilities=query_capabilities,
+                    query_datatypes=query_datatypes,
+                    query_stages=query_stages,
+                    tool_graph=tool_graph,
+                )
+                if score <= 0:
+                    continue
+                candidates.append(
+                    {
+                        "server": server_name,
+                        "tool": tool.get("name"),
+                        "node_id": tool.get("node_id"),
+                        "stage": tool.get("stage") or "analysis",
+                        "operations": tool.get("operations", []),
+                        "capabilities": tool.get("capabilities", []),
+                        "consumes": tool.get("consumes", []),
+                        "produces": tool.get("produces", []),
+                        "score": round(score, 3),
+                        "reason": "; ".join(reasons[:6]),
+                        "graph_context": self._expand_tool_context(tool, tool_graph),
+                    }
+                )
+
+        candidates.sort(key=lambda item: (item["score"], item["server"], item.get("tool") or ""), reverse=True)
+        shortlist = candidates[: max(candidate_pool, top_k_tools)]
+        compact = self._compact_subgraph(shortlist[:top_k_tools], tool_graph)
+        return {
+            "retriever": "mcp_graph_rag",
+            "task_profile": {
+                "categories": [str(item).lower() for item in query_context.get("categories", [])],
+                "operations": sorted(query_operations),
+                "capabilities": sorted(query_capabilities),
+                "datatypes": sorted(query_datatypes),
+                "stages": sorted(query_stages),
+            },
+            "query_tokens": sorted(query_tokens),
+            "candidate_tools": shortlist,
+            "compact_subgraph": compact,
+            "excluded_servers": [],
+            "operation_path_hint": self._operation_path_hint(shortlist[:top_k_tools]),
+            "context_text": self._format_context(shortlist[:top_k_tools], compact),
+        }
+
+    def _query_tokens(self, query_context: dict, query_semantics: dict) -> set[str]:
+        parts = [
+            query_context.get("question", ""),
+            query_context.get("original_query", ""),
+            query_context.get("rewritten_query", ""),
+            query_context.get("retrieval_query", ""),
+            " ".join(query_context.get("categories", [])),
+            " ".join(query_semantics.get("keywords", [])),
+            " ".join(query_semantics.get("operations", [])),
+            " ".join(query_semantics.get("capabilities", [])),
+            " ".join(query_semantics.get("datatypes", [])),
+        ]
+        tokens = self._tokenize(" ".join(str(part) for part in parts if part))
+        return {token for token in tokens if token not in self.GENERIC_TOKENS and len(token) >= 3}
+
+    def _score_tool(
+        self,
+        *,
+        server_name: str,
+        server_tokens: set[str],
+        server_overlap: set[str],
+        tool: dict,
+        query_tokens: set[str],
+        query_operations: set[str],
+        query_capabilities: set[str],
+        query_datatypes: set[str],
+        query_stages: set[str],
+        tool_graph: ToolGraph,
+    ) -> tuple[float, list[str]]:
+        text = " ".join(
+            [
+                server_name,
+                str(tool.get("name", "")),
+                str(tool.get("description", "")),
+                " ".join(tool.get("keywords", [])),
+                " ".join(tool.get("operations", [])),
+                " ".join(tool.get("capabilities", [])),
+                " ".join(tool.get("consumes", [])),
+                " ".join(tool.get("produces", [])),
+            ]
+        ).lower()
+        tool_tokens = self._tokenize(text)
+        score = 0.0
+        reasons = []
+
+        tool_overlap = query_tokens & tool_tokens
+        if tool_overlap:
+            score += min(len(tool_overlap), 10) * 0.8
+            reasons.append("tool_token_overlap=" + ",".join(sorted(list(tool_overlap))[:6]))
+        if server_overlap:
+            score += min(len(server_overlap), 6) * 0.35
+            reasons.append("server_token_overlap=" + ",".join(sorted(list(server_overlap))[:4]))
+
+        tool_operations = set(tool.get("operations", []))
+        operation_overlap = query_operations & tool_operations
+        if operation_overlap:
+            score += len(operation_overlap) * 4.0
+            score += len(operation_overlap) * (1.5 / max(1, len(tool_operations)))
+            reasons.append("operation_overlap=" + ",".join(sorted(operation_overlap)))
+            if len(tool_operations) > 3:
+                score -= min(len(tool_operations) - 3, 6) * 0.35
+                reasons.append("broad_operation_penalty")
+
+        capability_overlap = query_capabilities & set(tool.get("capabilities", []))
+        if capability_overlap:
+            score += len(capability_overlap) * 2.5
+            reasons.append("capability_overlap=" + ",".join(sorted(capability_overlap)))
+
+        tool_datatypes = set(tool.get("consumes", [])) | set(tool.get("produces", []))
+        datatype_overlap = query_datatypes & tool_datatypes
+        if datatype_overlap:
+            score += len(datatype_overlap) * 2.0
+            reasons.append("datatype_overlap=" + ",".join(sorted(datatype_overlap)))
+
+        stage = tool.get("stage")
+        if stage and stage in query_stages:
+            score += 1.0
+            reasons.append("stage_overlap=" + stage)
+
+        graph_bonus = self._graph_relevance_bonus(tool, query_operations, query_capabilities, query_datatypes, tool_graph)
+        if graph_bonus:
+            score += graph_bonus
+            reasons.append("graph_neighbor_overlap")
+
+        if not reasons and query_tokens & server_tokens:
+            score += 0.5
+            reasons.append("weak_server_match")
+
+        return score, reasons
+
+    def _graph_relevance_bonus(
+        self,
+        tool: dict,
+        query_operations: set[str],
+        query_capabilities: set[str],
+        query_datatypes: set[str],
+        tool_graph: ToolGraph,
+    ) -> float:
+        node_id = tool.get("node_id")
+        if not node_id:
+            return 0.0
+        bonus = 0.0
+        for edge in tool_graph.adjacency.get(node_id, []):
+            target = tool_graph.nodes.get(edge.get("target"), {})
+            label = str(target.get("label", "")).lower()
+            node_type = target.get("type")
+            if node_type == "operation" and label in query_operations:
+                bonus += 2.0
+            elif node_type == "capability" and label in query_capabilities:
+                bonus += 1.5
+            elif node_type == "datatype" and label in query_datatypes:
+                bonus += 1.0
+        return min(bonus, 5.0)
+
+    def _compact_subgraph(self, candidates: list[dict], tool_graph: ToolGraph) -> dict:
+        nodes = {}
+        edges = []
+        candidate_node_ids = {item.get("node_id") for item in candidates if item.get("node_id")}
+        server_names = {item.get("server") for item in candidates if item.get("server")}
+        for server_name in server_names:
+            server_node = f"server:{server_name}"
+            if server_node in tool_graph.nodes:
+                nodes[server_node] = tool_graph.nodes[server_node]
+        for node_id in candidate_node_ids:
+            if node_id in tool_graph.nodes:
+                nodes[node_id] = tool_graph.nodes[node_id]
+            for edge in tool_graph.adjacency.get(node_id, []):
+                target = edge.get("target")
+                if target in tool_graph.nodes and tool_graph.nodes[target].get("type") in {
+                    "operation",
+                    "capability",
+                    "datatype",
+                    "stage",
+                    "constraint",
+                }:
+                    nodes[target] = tool_graph.nodes[target]
+                    edges.append(edge)
+        return {"nodes": list(nodes.values()), "edges": edges[:120]}
+
+    def _expand_tool_context(self, tool: dict, tool_graph: ToolGraph) -> list[dict]:
+        node_id = tool.get("node_id")
+        if not node_id:
+            return []
+        context = []
+        for edge in tool_graph.adjacency.get(node_id, [])[:20]:
+            target = tool_graph.nodes.get(edge.get("target"), {})
+            if target:
+                context.append({"edge": edge.get("type"), "node_type": target.get("type"), "label": target.get("label")})
+        return context
+
+    def _operation_path_hint(self, candidates: list[dict]) -> list[str]:
+        operations = []
+        ordered = sorted(
+            candidates,
+            key=lambda item: (self.STAGE_RANK.get(item.get("stage"), 9), -float(item.get("score", 0.0))),
+        )
+        for item in ordered:
+            for operation in item.get("operations", []):
+                if operation not in operations:
+                    operations.append(operation)
+        return operations[:8]
+
+    def _format_context(self, candidates: list[dict], compact: dict) -> str:
+        lines = [
+            f"Retrieved compact MCP graph: {len(compact.get('nodes', []))} nodes, {len(compact.get('edges', []))} edges",
+            "Top candidate tool bindings:",
+        ]
+        for item in candidates[:12]:
+            lines.append(
+                "- "
+                + f"{item['server']}.{item.get('tool')} score={item['score']} "
+                + f"stage={item.get('stage')} ops={','.join(item.get('operations', [])[:4])}; {item.get('reason', '')}"
+            )
+        return "\n".join(lines)
+
+    def _server_text(self, server_name: str, server_entry: dict, payload: dict) -> str:
+        semantics = payload.get("semantics", {})
+        return " ".join(
+            [
+                server_name,
+                str(server_entry.get("summary", "")),
+                " ".join(server_entry.get("keywords", [])),
+                " ".join(semantics.get("keywords", [])),
+                " ".join(semantics.get("operations", [])),
+                " ".join(semantics.get("capabilities", [])),
+                " ".join(semantics.get("datatypes", [])),
+            ]
+        ).lower()
+
+    def _tokenize(self, text: str) -> set[str]:
+        normalized = (text or "").lower().replace("-", " ").replace("/", " ").replace("_", " ")
+        return {token for token in self.TOKEN_PATTERN.findall(normalized) if token}

Biomanus_upload/biomni/graph/graph_router.py

@@ -0,0 +1,674 @@
+from __future__ import annotations
+
+import copy
+from collections import deque
+
+from biomni.graph.graph_rag import MCPGraphRAGRetriever
+from biomni.graph.planning_agent import GraphPlanningAgent
+from biomni.graph.schema_extractor import ToolSchemaExtractor
+from biomni.graph.tool_graph import ToolGraph
+
+
+class GraphRouter:
+    """First-pass GraphRAG router over the explicit tool graph."""
+
+    STAGE_ORDER = ["input_acquisition", "preprocessing", "analysis", "downstream", "reporting"]
+
+    def __init__(self, schema_extractor: ToolSchemaExtractor | None = None):
+        self.schema_extractor = schema_extractor or ToolSchemaExtractor()
+        self.planning_agent = GraphPlanningAgent(schema_extractor=self.schema_extractor)
+        self.graph_rag = MCPGraphRAGRetriever()
+
+    def route(
+        self,
+        query_context: dict,
+        tool_graph: ToolGraph,
+        *,
+        retriever=None,
+        llm=None,
+        top_k_servers: int = 8,
+        candidate_pool: int = 24,
+        top_k_tools: int = 12,
+    ) -> dict:
+        if not tool_graph.get_server_names():
+            return {"selected_servers": [], "execution_plan": [], "seed_nodes": [], "workflow_subgraph": []}
+
+        query_semantics = self.schema_extractor.infer_query_semantics(query_context)
+        task_spec = query_semantics.get("task_spec") or {}
+        operation_anchors = query_semantics.get("operation_anchors", []) or task_spec.get("required_operations", [])
+        graph_rag_result = self.graph_rag.retrieve(
+            query_context=query_context,
+            query_semantics=query_semantics,
+            tool_graph=tool_graph,
+            candidate_pool=candidate_pool,
+            top_k_tools=top_k_tools,
+        )
+        if graph_rag_result.get("operation_path_hint"):
+            operation_anchors = self._merge_labels(operation_anchors, graph_rag_result["operation_path_hint"])
+        seed_nodes = self._find_seed_nodes(query_semantics, tool_graph)
+        candidate_paths = self._constrained_path_search(task_spec, operation_anchors, tool_graph)
+        ranked_paths = self._rank_paths(candidate_paths, task_spec, operation_anchors)
+        best_path = ranked_paths[0] if ranked_paths else self._anchor_only_path(operation_anchors, tool_graph)
+        heuristic_tool_plan = self._bind_tools_to_operations(
+            best_path,
+            task_spec,
+            query_semantics,
+            query_context,
+            tool_graph,
+            top_k_tools=top_k_tools,
+        )
+        planner_result = self.planning_agent.plan(
+            query_context=query_context,
+            query_semantics=query_semantics,
+            task_spec=task_spec,
+            ranked_paths=ranked_paths,
+            heuristic_tool_plan=heuristic_tool_plan,
+            tool_graph=tool_graph,
+            top_k_tools=top_k_tools,
+            llm=llm,
+            graph_rag_result=graph_rag_result,
+        )
+        tool_plan = planner_result.get("tool_plan") or heuristic_tool_plan
+        self._augment_graph_rag_with_tool_plan(graph_rag_result, tool_plan, tool_graph)
+        selected_servers = self._servers_from_tool_plan(tool_plan, tool_graph, top_k_servers=top_k_servers)
+        execution_plan = self._synthesize_dag(tool_plan)
+        operation_plan = self._build_operation_plan(
+            task_spec,
+            operation_anchors,
+            ranked_paths,
+            tool_plan,
+            planner_result=planner_result,
+        )
+        workflow_subgraph = [
+            {
+                "server": server["name"],
+                "tools": [tool.get("name", "") for tool in server.get("tools", [])],
+                "category": server.get("category", "general"),
+                "score": server.get("score", 0.0),
+            }
+            for server in selected_servers
+        ]
+        return {
+            "task_spec": task_spec,
+            "operation_anchors": operation_anchors,
+            "candidate_paths": ranked_paths[:5],
+            "tool_plan": tool_plan,
+            "heuristic_tool_plan": heuristic_tool_plan,
+            "dag": execution_plan,
+            "heuristic_dag": self._synthesize_dag(heuristic_tool_plan),
+            "selected_servers": selected_servers,
+            "operation_plan": operation_plan,
+            "execution_plan": execution_plan,
+            "seed_nodes": seed_nodes,
+            "workflow_subgraph": workflow_subgraph,
+            "planning_agent": planner_result,
+            "graph_rag": graph_rag_result,
+            "compact_graph_rag_subgraph": graph_rag_result.get("compact_subgraph", {}),
+            "excluded_mcp_servers": graph_rag_result.get("excluded_servers", []),
+        }
+
+    def _merge_labels(self, primary: list[str], additions: list[str]) -> list[str]:
+        merged = list(primary or [])
+        for item in additions or []:
+            if item and item not in merged:
+                merged.append(item)
+        return merged
+
+    def _augment_graph_rag_with_tool_plan(self, graph_rag_result: dict, tool_plan: list[dict], tool_graph: ToolGraph) -> None:
+        """Ensure the compact GraphRAG context contains the planner-bound graph tools."""
+        compact = graph_rag_result.setdefault("compact_subgraph", {"nodes": [], "edges": []})
+        nodes = compact.setdefault("nodes", [])
+        edges = compact.setdefault("edges", [])
+        node_ids = {node.get("id") for node in nodes}
+        edge_keys = {(edge.get("source"), edge.get("target"), edge.get("type")) for edge in edges}
+
+        def add_node(node_id: str) -> None:
+            if node_id in node_ids or node_id not in tool_graph.nodes:
+                return
+            nodes.append(tool_graph.nodes[node_id])
+            node_ids.add(node_id)
+
+        def add_edge(edge: dict) -> None:
+            key = (edge.get("source"), edge.get("target"), edge.get("type"))
+            if key in edge_keys:
+                return
+            edges.append(edge)
+            edge_keys.add(key)
+
+        for step in tool_plan:
+            if step.get("binding_source") == "agent":
+                continue
+            server = step.get("server")
+            tool = step.get("tool")
+            if not server or not tool:
+                continue
+            server_node = f"server:{server}"
+            tool_node = step.get("node_id") or f"tool:{server}:{tool}"
+            operation_node = f"operation:{step.get('operation')}"
+            add_node(server_node)
+            add_node(tool_node)
+            add_node(operation_node)
+            for edge in tool_graph.adjacency.get(server_node, []):
+                if edge.get("target") == tool_node:
+                    add_edge(edge)
+            for edge in tool_graph.adjacency.get(tool_node, []):
+                target = edge.get("target")
+                if target == operation_node or (
+                    target in tool_graph.nodes
+                    and tool_graph.nodes[target].get("type") in {"operation", "capability", "datatype", "stage", "constraint"}
+                ):
+                    add_node(target)
+                    add_edge(edge)
+
+    def _find_seed_nodes(self, query_semantics: dict, tool_graph: ToolGraph) -> list[str]:
+        seeds = []
+        for capability in query_semantics.get("capabilities", []):
+            node_id = f"capability:{capability}"
+            if node_id in tool_graph.nodes:
+                seeds.append(node_id)
+        for datatype in query_semantics.get("datatypes", []):
+            node_id = f"datatype:{datatype}"
+            if node_id in tool_graph.nodes:
+                seeds.append(node_id)
+        for stage in query_semantics.get("stages", []):
+            node_id = f"stage:{stage}"
+            if node_id in tool_graph.nodes:
+                seeds.append(node_id)
+        return seeds
+
+    def _score_server(self, server_name: str, query_context: dict, query_semantics: dict, tool_graph: ToolGraph) -> dict:
+        entry = tool_graph.get_server_entry(server_name) or {}
+        semantics = tool_graph.get_server_semantics(server_name)
+        score = 0.0
+        reasons = []
+
+        query_keywords = set(query_semantics.get("keywords", []))
+        server_keywords = set(semantics.get("keywords", []))
+        keyword_overlap = query_keywords & server_keywords
+        if keyword_overlap:
+            score += min(len(keyword_overlap), 8) * 0.6
+            reasons.append(f"keyword overlap={', '.join(sorted(list(keyword_overlap))[:6])}")
+
+        query_capabilities = set(query_semantics.get("capabilities", []))
+        server_capabilities = set(semantics.get("capabilities", []))
+        capability_overlap = query_capabilities & server_capabilities
+        if capability_overlap:
+            score += len(capability_overlap) * 3.0
+            reasons.append(f"capabilities={', '.join(sorted(capability_overlap))}")
+
+        query_datatypes = set(query_semantics.get("datatypes", []))
+        server_datatypes = set(semantics.get("datatypes", []))
+        datatype_overlap = query_datatypes & server_datatypes
+        if datatype_overlap:
+            score += len(datatype_overlap) * 2.0
+            reasons.append(f"datatypes={', '.join(sorted(datatype_overlap))}")
+
+        query_stages = set(query_semantics.get("stages", []))
+        server_stages = set(semantics.get("stages", []))
+        stage_overlap = query_stages & server_stages
+        if stage_overlap:
+            score += len(stage_overlap) * 1.5
+            reasons.append(f"stages={', '.join(sorted(stage_overlap))}")
+
+        for hint in query_context.get("server_hints", []):
+            hint_l = str(hint).lower()
+            if self._hint_matches_server(hint_l, server_name, entry):
+                score += 8.0
+                reasons.append(f"server_hint={hint_l}")
+
+        category = str(entry.get("category", "")).lower()
+        for category_hint in query_context.get("categories", []):
+            if str(category_hint).lower() == category:
+                score += 2.0
+                reasons.append(f"category={category}")
+
+        tool_bonus = min(len(tool_graph.get_tool_nodes_for_server(server_name)), 6) * 0.15
+        score += tool_bonus
+
+        return {
+            "server_name": server_name,
+            "server_entry": entry,
+            "score": score,
+            "reason": reasons,
+        }
+
+    def _select_tools_for_server(
+        self,
+        server_name: str,
+        query_context: dict,
+        query_semantics: dict,
+        tool_graph: ToolGraph,
+        *,
+        retriever=None,
+        llm=None,
+        top_k_tools: int = 12,
+    ) -> list[dict]:
+        tools = tool_graph.get_tool_nodes_for_server(server_name)
+        if not tools:
+            return []
+
+        scored = []
+        query_keywords = set(query_semantics.get("keywords", []))
+        query_capabilities = set(query_semantics.get("capabilities", []))
+        query_datatypes = set(query_semantics.get("datatypes", []))
+        query_stages = set(query_semantics.get("stages", []))
+
+        for tool in tools:
+            score = 0.0
+            tool_keywords = set(tool.get("keywords", []))
+            capability_overlap = query_capabilities & set(tool.get("capabilities", []))
+            datatype_overlap = query_datatypes & (set(tool.get("consumes", [])) | set(tool.get("produces", [])))
+            stage_overlap = query_stages & {tool.get("stage")} if tool.get("stage") else set()
+
+            keyword_overlap = query_keywords & tool_keywords
+            score += min(len(keyword_overlap), 6) * 0.5
+            score += len(capability_overlap) * 3.0
+            score += len(datatype_overlap) * 2.0
+            score += len(stage_overlap) * 1.0
+
+            for hint in query_context.get("server_hints", []):
+                hint_l = str(hint).lower()
+                if self._hint_matches_tool(hint_l, tool):
+                    score += 5.0
+            scored.append((score, tool))
+
+        scored.sort(key=lambda item: item[0], reverse=True)
+        shortlisted = [self._tool_to_runtime_schema(tool) for _, tool in scored[: max(top_k_tools * 2, top_k_tools)]]
+
+        if retriever is not None and llm is not None and len(shortlisted) > top_k_tools:
+            reranked = retriever._llm_rerank_tools(query_context, shortlisted, top_k=top_k_tools, llm=llm)
+            if reranked:
+                return reranked
+        return shortlisted[:top_k_tools]
+
+    def _hint_matches_server(self, hint: str, server_name: str, entry: dict) -> bool:
+        if len(hint) < 3:
+            return False
+        server_l = server_name.lower()
+        if hint == server_l or hint in server_l.split("-") or hint in server_l.split("_"):
+            return True
+        tokens = set(str(entry.get("summary", "")).lower().replace("_", "-").split())
+        return hint in tokens
+
+    def _hint_matches_tool(self, hint: str, tool: dict) -> bool:
+        if len(hint) < 3:
+            return False
+        tool_name = str(tool.get("name", "")).lower()
+        if hint == tool_name or hint in tool_name.replace("_", "-").split("-"):
+            return True
+        tokens = set(str(tool.get("text", "")).lower().replace("_", "-").split())
+        return hint in tokens
+
+    def _tool_to_runtime_schema(self, tool: dict) -> dict:
+        return {
+            "name": tool.get("name"),
+            "description": tool.get("description", ""),
+            "inputSchema": tool.get("inputSchema", {"properties": {}, "required": []}),
+        }
+
+    def _constrained_path_search(
+        self,
+        task_spec: dict,
+        operation_anchors: list[str],
+        tool_graph: ToolGraph,
+        *,
+        max_hops: int = 8,
+        beam_width: int = 80,
+    ) -> list[dict]:
+        source_types = task_spec.get("input_types", []) or ["text"]
+        target_type = (task_spec.get("target_output") or {}).get("semantic_type")
+        constraint_labels = set((task_spec.get("constraints") or {}).get("labels", []))
+        reachable_anchors = [anchor for anchor in operation_anchors if anchor in tool_graph.operation_index]
+        paths = []
+        queue = deque((source_type, [], [source_type]) for source_type in source_types)
+        visited = set()
+
+        while queue and len(paths) < beam_width:
+            current_type, operations, type_trace = queue.popleft()
+            state = (current_type, tuple(operations))
+            if state in visited:
+                continue
+            visited.add(state)
+
+            if operations and (not target_type or current_type == target_type):
+                if self._path_satisfies_anchors(operations, reachable_anchors):
+                    paths.append(self._path_payload(operations, type_trace, target_type, tool_graph))
+                    continue
+
+            if len(operations) >= max_hops:
+                continue
+
+            for operation in tool_graph.datatype_to_operations.get(current_type, []):
+                if operation in operations:
+                    continue
+                operation_info = tool_graph.operation_index.get(operation, {})
+                if not self._constraints_compatible(operation_info.get("constraints", []), constraint_labels):
+                    continue
+                for produced_type in operation_info.get("produces", []) or []:
+                    queue.append((produced_type, [*operations, operation], [*type_trace, produced_type]))
+
+        if not paths and reachable_anchors:
+            return [self._anchor_only_path(reachable_anchors, tool_graph)]
+        return paths
+
+    def _path_satisfies_anchors(self, operations: list[str], anchors: list[str]) -> bool:
+        return all(anchor in operations for anchor in anchors)
+
+    def _constraints_compatible(self, required: list[str], provided: set[str]) -> bool:
+        # Phase 1 routing is intentionally driven by the semantic type graph.
+        # Constraints are kept on operation/tool nodes for ranking and prompt
+        # explanation, but should not prune a path that can satisfy them via an
+        # upstream operation (for example gene_id_conversion -> kegg_enrichment).
+        return True
+
+    def _path_payload(
+        self,
+        operations: list[str],
+        type_trace: list[str],
+        target_type: str | None,
+        tool_graph: ToolGraph,
+    ) -> dict:
+        steps = []
+        for index, operation in enumerate(operations):
+            operation_info = tool_graph.operation_index.get(operation, {})
+            steps.append(
+                {
+                    "operation": operation,
+                    "input_type": type_trace[index],
+                    "output_types": operation_info.get("produces", []),
+                    "stage": operation_info.get("stage", "analysis"),
+                }
+            )
+        return {
+            "operations": operations,
+            "type_trace": type_trace,
+            "target_type": target_type,
+            "steps": steps,
+        }
+
+    def _anchor_only_path(self, anchors: list[str], tool_graph: ToolGraph) -> dict:
+        operations = [operation for operation in anchors if operation in tool_graph.operation_index]
+        if not operations:
+            operations = list(tool_graph.operation_index.keys())[:1]
+        type_trace = []
+        for operation in operations:
+            operation_info = tool_graph.operation_index.get(operation, {})
+            if not type_trace:
+                type_trace.append((operation_info.get("accepts") or ["text"])[0])
+            type_trace.append((operation_info.get("produces") or [type_trace[-1]])[0])
+        return self._path_payload(operations, type_trace or ["text"], None, tool_graph)
+
+    def _rank_paths(self, paths: list[dict], task_spec: dict, anchors: list[str]) -> list[dict]:
+        target_type = (task_spec.get("target_output") or {}).get("semantic_type")
+        ranked = []
+        for path in paths:
+            operations = path.get("operations", [])
+            anchor_hits = len(set(operations) & set(anchors))
+            target_hit = 1 if target_type and target_type in path.get("type_trace", []) else 0
+            score = anchor_hits * 5.0 + target_hit * 3.0 - len(operations) * 0.2
+            enriched = dict(path)
+            enriched["score"] = score
+            enriched["anchor_hits"] = anchor_hits
+            ranked.append(enriched)
+        ranked.sort(key=lambda item: item.get("score", 0), reverse=True)
+        return ranked
+
+    def _bind_tools_to_operations(
+        self,
+        path: dict,
+        task_spec: dict,
+        query_semantics: dict,
+        query_context: dict,
+        tool_graph: ToolGraph,
+        *,
+        top_k_tools: int = 12,
+    ) -> list[dict]:
+        constraint_labels = set((task_spec.get("constraints") or {}).get("labels", []))
+        query_keywords = {
+            keyword
+            for keyword in query_semantics.get("keywords", [])
+            if isinstance(keyword, str) and len(keyword) >= 3
+        }
+        generic_query_terms = {
+            "according",
+            "against",
+            "annotation",
+            "answer",
+            "biological",
+            "but",
+            "choices",
+            "data",
+            "database",
+            "entry",
+            "following",
+            "gene",
+            "genes",
+            "identify",
+            "knowledge",
+            "metadata",
+            "not",
+            "query",
+            "record",
+            "referenced",
+            "relevant",
+            "retrieve",
+            "retrieved",
+            "set",
+            "source",
+            "task",
+            "which",
+        }
+        discriminative_keywords = query_keywords - generic_query_terms
+        query_categories = {str(category).lower() for category in query_context.get("categories", [])}
+        tool_plan = []
+        for step_index, operation in enumerate(path.get("operations", []), start=1):
+            operation_info = tool_graph.operation_index.get(operation, {})
+            candidates = []
+            for tool in operation_info.get("tools", []):
+                server_name = tool.get("node_id", "tool:unknown:unknown").split(":")[1]
+                server_entry = tool_graph.get_server_entry(server_name) or {}
+                tool_constraints = set(tool.get("constraints", []))
+                tool_text = " ".join(
+                    [
+                        server_name,
+                        str(server_entry.get("summary", "")),
+                        str(tool.get("name", "")),
+                        str(tool.get("description", "")),
+                        " ".join(tool.get("keywords", [])),
+                    ]
+                ).lower()
+                operation_spec = self.schema_extractor.OPERATION_SPECS.get(operation, {})
+                operation_patterns = operation_spec.get("patterns", set())
+                score = 1.0
+                score += len(tool_constraints & constraint_labels) * 2.0
+                score += min(len(tool.get("keywords", [])), 8) * 0.05
+                keyword_hits = {keyword for keyword in query_keywords if keyword in tool_text}
+                discriminative_hits = {keyword for keyword in discriminative_keywords if keyword in tool_text}
+                score += min(len(keyword_hits), 10) * 0.45
+                score += min(len(discriminative_hits), 6) * 1.2
+                category = str(server_entry.get("category", "")).lower()
+                if category and category in query_categories:
+                    score += 1.0
+                if operation in tool.get("name", "").lower():
+                    score += 1.0
+                if operation.replace("_", " ") in tool_text:
+                    score += 1.5
+                score += min(sum(1 for pattern in operation_patterns if pattern in tool_text), 3) * 0.8
+                if operation == "csv_export":
+                    tool_name = str(tool.get("name", "")).lower()
+                    if "export" in tool_name:
+                        score += 2.0
+                    if "csv" in tool_name:
+                        score += 1.0
+                    if tool_name.startswith(("read", "load", "import", "fetch", "get")) or "_read_" in tool_name:
+                        score -= 3.0
+                candidates.append((score, tool.get("node_id", ""), tool))
+            candidates.sort(key=lambda item: (item[0], item[1]), reverse=True)
+            selected = candidates[0][2] if candidates else {}
+            server_name = selected.get("node_id", "tool:unknown:unknown").split(":")[1]
+            tool_plan.append(
+                {
+                    "step": step_index,
+                    "operation": operation,
+                    "server": server_name,
+                    "tool": selected.get("name"),
+                    "stage": operation_info.get("stage", "analysis"),
+                    "input_types": operation_info.get("accepts", []),
+                    "output_types": operation_info.get("produces", []),
+                    "candidate_tool_count": len(candidates),
+                }
+            )
+        return tool_plan[:top_k_tools]
+
+    def _servers_from_tool_plan(self, tool_plan: list[dict], tool_graph: ToolGraph, *, top_k_servers: int) -> list[dict]:
+        grouped: dict[str, list[dict]] = {}
+        for step in tool_plan:
+            if step.get("binding_source") == "agent":
+                continue
+            if step.get("server") and step.get("tool"):
+                grouped.setdefault(step["server"], []).append(step)
+
+        selected_servers = []
+        for server_name, steps in list(grouped.items())[:top_k_servers]:
+            entry = copy.deepcopy(tool_graph.get_server_entry(server_name) or {"name": server_name})
+            entry["tools"] = [
+                {
+                    "name": step["tool"],
+                    "description": f"Tool bound for operation {step['operation']}",
+                    "inputSchema": {"properties": {}, "required": []},
+                }
+                for step in steps
+            ]
+            entry["score"] = float(len(steps))
+            entry["graph_reason"] = [f"operation_path_binding={step['operation']}" for step in steps]
+            selected_servers.append(entry)
+        return selected_servers
+
+    def _synthesize_dag(self, tool_plan: list[dict]) -> list[dict]:
+        dag = []
+        previous_id = None
+        seen_ids: dict[str, int] = {}
+        for index, step in enumerate(tool_plan, start=1):
+            base_id = f"{step['server']}.{step['tool'] or step['operation']}"
+            seen_ids[base_id] = seen_ids.get(base_id, 0) + 1
+            suffix = "" if seen_ids[base_id] == 1 else f"#{seen_ids[base_id]}"
+            step_id = f"{base_id}{suffix}"
+            dag.append(
+                {
+                    "id": step_id,
+                    "step": index,
+                    "stage": step.get("stage", "analysis"),
+                    "operation": step.get("operation"),
+                    "server": step.get("server"),
+                    "tools": [step.get("tool") or step.get("operation")],
+                    "input_types": step.get("input_types", []),
+                    "output_types": step.get("output_types", []),
+                    "binding_source": step.get("binding_source", "graph"),
+                    "depends_on": [previous_id] if previous_id else [],
+                }
+            )
+            previous_id = step_id
+        return dag
+
+    def _build_operation_plan(
+        self,
+        task_spec: dict,
+        operation_anchors: list[str],
+        ranked_paths: list[dict],
+        tool_plan: list[dict],
+        *,
+        planner_result: dict | None = None,
+    ) -> dict:
+        best_path = ranked_paths[0] if ranked_paths else {}
+        selected_path = planner_result.get("operation_path") if planner_result else None
+        selected_trace = planner_result.get("type_trace") if planner_result else None
+        return {
+            "workflow_type": task_spec.get("workflow_type", "single_step"),
+            "planner": (planner_result or {}).get("planner", "heuristic_graph_router"),
+            "planner_selected": bool((planner_result or {}).get("selected")),
+            "task_spec": task_spec,
+            "operation_anchors": operation_anchors,
+            "operation_path": selected_path or best_path.get("operations", []),
+            "type_trace": selected_trace or best_path.get("type_trace", []),
+            "steps": [
+                {
+                    "operation": step.get("operation"),
+                    "server": step.get("server"),
+                    "tool": step.get("tool"),
+                    "input_types": step.get("input_types", []),
+                    "output_types": step.get("output_types", []),
+                    "binding_source": step.get("binding_source", "graph"),
+                    "planning_rationale": step.get("planning_rationale", ""),
+                }
+                for step in tool_plan
+            ],
+            "tool_bindings": [
+                {
+                    "operation": step.get("operation"),
+                    "server": step.get("server"),
+                    "tool": step.get("tool"),
+                    "binding_source": step.get("binding_source", "graph"),
+                }
+                for step in tool_plan
+            ],
+            "planner_reason": (planner_result or {}).get("reason", ""),
+            "planner_task_profile": (planner_result or {}).get("task_profile", {}),
+        }
+
+    def _build_execution_plan(self, selected_servers: list[dict], tool_graph: ToolGraph) -> list[dict]:
+        selected_nodes = {}
+        for server in selected_servers:
+            selected_tool_names = {candidate.get("name") for candidate in server.get("tools", [])}
+            for tool in tool_graph.get_tool_nodes_for_server(server["name"]):
+                if tool.get("name") in selected_tool_names:
+                    selected_nodes[tool["node_id"]] = tool
+
+        if selected_nodes:
+            dependency_map: dict[str, list[str]] = {node_id: [] for node_id in selected_nodes}
+            for edge in tool_graph.edges:
+                if edge.get("type") not in {"typed_flow", "follows"}:
+                    continue
+                source = edge.get("source")
+                target = edge.get("target")
+                if source in selected_nodes and target in selected_nodes:
+                    dependency_map[target].append(source)
+
+            stage_rank = {stage: idx for idx, stage in enumerate(self.STAGE_ORDER)}
+            ordered_nodes = sorted(
+                selected_nodes.values(),
+                key=lambda tool: (
+                    stage_rank.get(tool.get("stage") or "analysis", 99),
+                    len(dependency_map.get(tool["node_id"], [])),
+                    tool["node_id"].split(":")[1],
+                    tool.get("name", ""),
+                ),
+            )
+            plan = []
+            for tool in ordered_nodes:
+                server = tool["node_id"].split(":")[1]
+                depends_on = [
+                    f"{selected_nodes[source]['node_id'].split(':')[1]}.{selected_nodes[source].get('name')}"
+                    for source in dependency_map.get(tool["node_id"], [])
+                ]
+                plan.append(
+                    {
+                        "stage": tool.get("stage") or "analysis",
+                        "server": server,
+                        "tools": [tool.get("name")],
+                        "depends_on": depends_on,
+                    }
+                )
+            return plan
+
+        plan = []
+        for server in selected_servers:
+            stage_buckets: dict[str, list[str]] = {}
+            for tool in tool_graph.get_tool_nodes_for_server(server["name"]):
+                if tool.get("name") not in {candidate.get("name") for candidate in server.get("tools", [])}:
+                    continue
+                stage = tool.get("stage") or "analysis"
+                stage_buckets.setdefault(stage, []).append(tool.get("name"))
+            for stage in self.STAGE_ORDER:
+                if stage in stage_buckets:
+                    plan.append({"stage": stage, "server": server["name"], "tools": sorted(stage_buckets[stage])})
+        return plan

Biomanus_upload/biomni/graph/planning_agent.py

@@ -0,0 +1,1046 @@
+from __future__ import annotations
+
+import json
+import re
+
+from langchain_core.messages import HumanMessage
+
+from biomni.graph.schema_extractor import ToolSchemaExtractor
+from biomni.graph.tool_graph import ToolGraph
+
+
+class GraphPlanningAgent:
+    """Task-aware planner that refines graph routing into a more usable call chain."""
+
+    GENERIC_TOKENS = {
+        "according",
+        "analysis",
+        "annotate",
+        "answer",
+        "based",
+        "biological",
+        "candidate",
+        "choice",
+        "choices",
+        "compare",
+        "comparison",
+        "context",
+        "data",
+        "database",
+        "evidence",
+        "following",
+        "identify",
+        "likely",
+        "most",
+        "prompt",
+        "question",
+        "record",
+        "relevant",
+        "result",
+        "sequence",
+        "source",
+        "summary",
+        "task",
+        "tool",
+        "using",
+        "variant",
+        "which",
+    }
+    AMINO_ACID_SEQUENCE = re.compile(r"[ACDEFGHIKLMNPQRSTVWY]{12,}")
+    TOKEN_PATTERN = re.compile(r"[a-z0-9_+-]+")
+    EDGE_TYPES = {"typed_flow", "follows", "adjacent_stage"}
+    RESOURCE_TOKENS = {
+        "clinvar",
+        "disgenet",
+        "omim",
+        "uniprot",
+        "ensembl",
+        "pubmed",
+        "biomart",
+    }
+    SEQUENCING_INPUT_TYPES = {"fastq", "bam", "reference_genome", "annotation_gff", "raw_count_matrix", "count_matrix"}
+    WRONG_DOMAIN_TOKENS = {
+        "crispr",
+        "amplicon",
+        "guide",
+        "single-cell",
+        "singlecell",
+        "spatial",
+        "metagenomic",
+        "metagenomics",
+        "taxonomy",
+        "taxonomic",
+        "promoter",
+        "orf",
+    }
+
+    def __init__(self, schema_extractor: ToolSchemaExtractor | None = None):
+        self.schema_extractor = schema_extractor or ToolSchemaExtractor()
+
+    def plan(
+        self,
+        *,
+        query_context: dict,
+        query_semantics: dict,
+        task_spec: dict,
+        ranked_paths: list[dict],
+        heuristic_tool_plan: list[dict],
+        tool_graph: ToolGraph,
+        top_k_tools: int = 12,
+        llm=None,
+        graph_rag_result: dict | None = None,
+    ) -> dict:
+        profile = self._build_task_profile(query_context, query_semantics, task_spec)
+        if graph_rag_result:
+            profile["graph_rag"] = graph_rag_result.get("task_profile", {})
+            profile["task_tags"] = sorted(
+                set(profile.get("task_tags", [])) | set((graph_rag_result.get("task_profile") or {}).get("tags", []))
+            )
+        step_specs = self._build_step_specs(query_context, task_spec, ranked_paths, profile)
+        if llm is not None and graph_rag_result:
+            llm_plan = self._plan_with_llm(
+                llm=llm,
+                query_context=query_context,
+                query_semantics=query_semantics,
+                task_spec=task_spec,
+                graph_rag_result=graph_rag_result,
+                tool_graph=tool_graph,
+                top_k_tools=top_k_tools,
+            )
+            if llm_plan.get("tool_plan"):
+                return {
+                    "planner": "llm_graph_rag_planning_agent",
+                    "selected": True,
+                    "task_profile": profile,
+                    "step_specs": step_specs,
+                    "llm_enabled": True,
+                    "operation_path": [step["operation"] for step in llm_plan["tool_plan"]],
+                    "type_trace": self._build_type_trace(llm_plan["tool_plan"], task_spec),
+                    "tool_plan": llm_plan["tool_plan"][:top_k_tools],
+                    "reason": llm_plan.get("reason", "LLM planned over compact MCP GraphRAG context"),
+                    "llm_raw_plan": llm_plan.get("raw_plan", {}),
+                    "heuristic_tool_plan": heuristic_tool_plan,
+                    "graph_rag": graph_rag_result or {},
+                }
+
+        tool_plan = self._select_tool_chain(
+            step_specs,
+            profile,
+            tool_graph,
+            top_k_tools=top_k_tools,
+            graph_rag_candidates=(graph_rag_result or {}).get("candidate_tools", []),
+        )
+        if not tool_plan:
+            return {
+                "planner": "graph_planning_agent",
+                "selected": False,
+                "task_profile": profile,
+                "step_specs": step_specs,
+                "reason": "no viable planner tool chain found; using heuristic route",
+                "llm_enabled": llm is not None,
+                "graph_rag": graph_rag_result or {},
+            }
+
+        return {
+            "planner": "graph_planning_agent",
+            "selected": True,
+            "task_profile": profile,
+            "step_specs": step_specs,
+            "llm_enabled": llm is not None,
+            "operation_path": [step["operation"] for step in tool_plan],
+            "type_trace": self._build_type_trace(tool_plan, task_spec),
+            "tool_plan": tool_plan[:top_k_tools],
+            "reason": "planner selected a task-grounded tool chain from graph candidates",
+            "heuristic_tool_plan": heuristic_tool_plan,
+            "graph_rag": graph_rag_result or {},
+        }
+
+    def _plan_with_llm(
+        self,
+        *,
+        llm,
+        query_context: dict,
+        query_semantics: dict,
+        task_spec: dict,
+        graph_rag_result: dict,
+        tool_graph: ToolGraph,
+        top_k_tools: int,
+    ) -> dict:
+        candidates = graph_rag_result.get("candidate_tools", [])[: max(top_k_tools * 2, top_k_tools)]
+        if not candidates:
+            return {}
+
+        prompt = self._build_llm_planner_prompt(
+            query_context=query_context,
+            query_semantics=query_semantics,
+            task_spec=task_spec,
+            graph_rag_result=graph_rag_result,
+            candidates=candidates,
+            top_k_tools=top_k_tools,
+        )
+        try:
+            response = llm.invoke([HumanMessage(content=prompt)])
+        except Exception as exc:
+            return {"error": f"llm_planner_failed: {type(exc).__name__}: {exc}"}
+
+        content = getattr(response, "content", response)
+        content_text = self._content_to_text(content)
+        parsed = self._parse_json_object(content_text)
+        if not parsed:
+            return {"error": "llm_planner_returned_unparseable_json", "content": content_text[:2000]}
+
+        tool_plan = self._tool_plan_from_llm_json(parsed, candidates, tool_graph, top_k_tools=top_k_tools)
+        if not tool_plan:
+            return {"raw_plan": parsed, "reason": parsed.get("reason", "")}
+        return {"tool_plan": tool_plan, "raw_plan": parsed, "reason": parsed.get("reason", "")}
+
+    def _build_llm_planner_prompt(
+        self,
+        *,
+        query_context: dict,
+        query_semantics: dict,
+        task_spec: dict,
+        graph_rag_result: dict,
+        candidates: list[dict],
+        top_k_tools: int,
+    ) -> str:
+        compact_candidates = []
+        for idx, item in enumerate(candidates):
+            compact_candidates.append(
+                {
+                    "index": idx,
+                    "server": item.get("server"),
+                    "tool": item.get("tool"),
+                    "stage": item.get("stage"),
+                    "operations": item.get("operations", []),
+                    "capabilities": item.get("capabilities", []),
+                    "consumes": item.get("consumes", []),
+                    "produces": item.get("produces", []),
+                    "score": item.get("score"),
+                    "graph_context": item.get("graph_context", [])[:8],
+                    "reason": item.get("reason", ""),
+                }
+            )
+        question = query_context.get("question") or query_context.get("original_query") or query_context.get("rewritten_query")
+        payload = {
+            "question": question,
+            "query_semantics": {
+                "operations": query_semantics.get("operations", []),
+                "capabilities": query_semantics.get("capabilities", []),
+                "datatypes": query_semantics.get("datatypes", []),
+                "stages": query_semantics.get("stages", []),
+            },
+            "task_spec": task_spec,
+            "graph_rag": {
+                "operation_path_hint": graph_rag_result.get("operation_path_hint", []),
+                "compact_node_count": len((graph_rag_result.get("compact_subgraph") or {}).get("nodes", [])),
+                "compact_edge_count": len((graph_rag_result.get("compact_subgraph") or {}).get("edges", [])),
+            },
+            "candidate_tools": compact_candidates,
+        }
+        return (
+            "You are an agentic planner for a biomedical MCP tool graph. "
+            "Plan only from the provided GraphRAG candidate tools. "
+            "Choose a concise executable operation path. Use an agent reasoning step only when no candidate tool is suitable. "
+            "For exact sequence-analysis tasks such as GC content, ORF finding, restriction digests, PCR primers, "
+            "or Kozak scoring, prefer general sequence operation tools over broad NGS or database tools when present. "
+            "Do not solve the biology task; only plan tool use.\n\n"
+            "Return exactly one JSON object with this schema:\n"
+            "{\n"
+            '  "reason": "short rationale",\n'
+            '  "steps": [\n'
+            '    {"operation": "operation_name", "candidate_index": 0, "server": "server", "tool": "tool", "rationale": "why"},\n'
+            '    {"operation": "option_comparison", "provider": "agent", "tool": "reason_over_evidence", "rationale": "why"}\n'
+            "  ]\n"
+            "}\n"
+            f"Use at most {top_k_tools} steps. candidate_index must refer to candidate_tools when using an MCP tool.\n\n"
+            "Planning input:\n"
+            + json.dumps(payload, ensure_ascii=False, indent=2, default=str)
+        )
+
+    def _tool_plan_from_llm_json(
+        self,
+        parsed: dict,
+        candidates: list[dict],
+        tool_graph: ToolGraph,
+        *,
+        top_k_tools: int,
+    ) -> list[dict]:
+        plan = []
+        candidate_by_index = {idx: item for idx, item in enumerate(candidates)}
+        candidate_by_pair = {(item.get("server"), item.get("tool")): item for item in candidates}
+        seen = set()
+        steps = parsed.get("steps", [])
+        if not isinstance(steps, list):
+            return []
+
+        for raw_step in steps[:top_k_tools]:
+            if not isinstance(raw_step, dict):
+                continue
+            operation = str(raw_step.get("operation") or raw_step.get("step") or "").strip()
+            if not operation:
+                continue
+            provider = str(raw_step.get("provider") or raw_step.get("server") or "").strip()
+            tool_name = str(raw_step.get("tool") or "").strip()
+            candidate = None
+            raw_index = raw_step.get("candidate_index")
+            if isinstance(raw_index, int):
+                candidate = candidate_by_index.get(raw_index)
+            if candidate is None and provider and tool_name:
+                candidate = candidate_by_pair.get((provider, tool_name))
+
+            if provider == "agent" or tool_name == "reason_over_evidence" or candidate is None:
+                key = ("agent", operation)
+                if key in seen:
+                    continue
+                seen.add(key)
+                plan.append(
+                    {
+                        "step": len(plan) + 1,
+                        "operation": operation,
+                        "server": "agent",
+                        "tool": "reason_over_evidence",
+                        "stage": raw_step.get("stage") or "downstream",
+                        "input_types": raw_step.get("input_types", ["text"]),
+                        "output_types": raw_step.get("output_types", ["report_table"]),
+                        "candidate_tool_count": len(candidates),
+                        "binding_source": "agent",
+                        "planning_rationale": raw_step.get("rationale", ""),
+                    }
+                )
+                continue
+
+            node_id = candidate.get("node_id")
+            if node_id and node_id not in tool_graph.nodes:
+                continue
+            key = (candidate.get("server"), candidate.get("tool"), operation)
+            if key in seen:
+                continue
+            seen.add(key)
+            plan.append(
+                {
+                    "step": len(plan) + 1,
+                    "operation": operation,
+                    "server": candidate.get("server"),
+                    "tool": candidate.get("tool"),
+                    "stage": candidate.get("stage") or raw_step.get("stage") or "analysis",
+                    "input_types": candidate.get("consumes", []),
+                    "output_types": candidate.get("produces", []),
+                    "candidate_tool_count": len(candidates),
+                    "binding_source": "llm_graph_rag",
+                    "node_id": node_id,
+                    "planning_score": candidate.get("score", 0.0),
+                    "planning_rationale": raw_step.get("rationale", ""),
+                }
+            )
+        return plan
+
+    def _content_to_text(self, content) -> str:
+        if isinstance(content, list):
+            parts = []
+            for item in content:
+                if isinstance(item, dict) and "text" in item:
+                    parts.append(str(item.get("text", "")))
+                else:
+                    parts.append(str(item))
+            return "\n".join(parts)
+        return str(content)
+
+    def _parse_json_object(self, text: str) -> dict:
+        try:
+            payload = json.loads(text)
+            return payload if isinstance(payload, dict) else {}
+        except json.JSONDecodeError:
+            pass
+        match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, flags=re.DOTALL)
+        if match:
+            try:
+                payload = json.loads(match.group(1))
+                return payload if isinstance(payload, dict) else {}
+            except json.JSONDecodeError:
+                pass
+        start = text.find("{")
+        end = text.rfind("}")
+        if start >= 0 and end > start:
+            try:
+                payload = json.loads(text[start : end + 1])
+                return payload if isinstance(payload, dict) else {}
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+    def _build_task_profile(self, query_context: dict, query_semantics: dict, task_spec: dict) -> dict:
+        text_parts = [
+            query_context.get("question", ""),
+            query_context.get("original_query", ""),
+            query_context.get("rewritten_query", ""),
+            query_context.get("retrieval_query", ""),
+            " ".join(query_context.get("subtasks", [])),
+            " ".join(query_context.get("keywords", [])),
+        ]
+        text = " ".join(str(part) for part in text_parts if part).lower()
+        query_tokens = self._tokenize(text)
+        focus_tokens = {
+            token
+            for token in query_tokens
+            if len(token) >= 4 and token not in self.GENERIC_TOKENS and token not in {"text", "table", "report"}
+        }
+        resource_tokens = sorted(token for token in self.RESOURCE_TOKENS if token in text)
+        question = str(query_context.get("question", "") or query_context.get("original_query", ""))
+        categories = {str(item).lower() for item in query_context.get("categories", [])}
+        task_tags = self._infer_task_tags(text, categories)
+        return {
+            "text": text,
+            "query_tokens": sorted(query_tokens),
+            "focus_tokens": sorted(focus_tokens),
+            "resource_tokens": resource_tokens,
+            "categories": sorted(categories),
+            "has_sequence": "<sequence>" in question.lower() or bool(self.AMINO_ACID_SEQUENCE.search(question.upper())),
+            "has_variant": any(token in text for token in ("variant", "mutation", "amino-acid", "amino acid", "missense")),
+            "has_gene": any(token in text for token in ("gene", "genes")),
+            "needs_lookup": bool(resource_tokens) or "database_question_answering" in categories,
+            "needs_comparison": any(
+                token in text for token in ("which of the following", "compare", "comparison", "but not", "not according")
+            ),
+            "is_multiple_choice": "which of the following" in text or "choices" in text,
+            "asks_clinical_significance": any(token in text for token in ("benign", "pathogenic", "significance")),
+            "task_output": (task_spec.get("target_output") or {}).get("semantic_type") or "report_table",
+            "semantic_ops": query_semantics.get("operations", []),
+            "task_tags": sorted(task_tags),
+            "is_seqqa": "seqqa" in task_tags,
+        }
+
+    def _build_step_specs(self, query_context: dict, task_spec: dict, ranked_paths: list[dict], profile: dict) -> list[dict]:
+        steps = []
+        task_tags = set(profile.get("task_tags", []))
+
+        if "base_counting" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "base_counting",
+                    "Count nucleotide bases in the provided sequence using a deterministic sequence tool.",
+                    stage="analysis",
+                    tokens=["base", "bases", "count", "sequence", "gc", "composition", "seqfu", "bioawk"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature", "report_table"],
+                )
+            )
+        if "gc_content_calculation" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "gc_content_calculation",
+                    "Compute GC percentage and rounding deterministically before mapping to the choices.",
+                    stage="analysis",
+                    tokens=["gc", "content", "percent", "percentage", "base", "count", "composition"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["report_table"],
+                )
+            )
+        if "reverse_complement" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "reverse_complement",
+                    "Compute reverse-complement sequence coordinates when strand direction matters.",
+                    stage="analysis",
+                    tokens=["reverse", "complement", "revcomp", "rc", "sequence"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature"],
+                )
+            )
+        if "orf_detection" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "orf_detection",
+                    "Find ORFs with explicit strand, start/stop, length, and translation-table assumptions.",
+                    stage="analysis",
+                    tokens=["orf", "open", "reading", "frame", "translate", "translation", "pyrodigal", "orfhunter"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature", "report_table"],
+                )
+            )
+        if "restriction_digest" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "restriction_digest",
+                    "Resolve restriction enzyme recognition sites and compute digest fragments.",
+                    stage="analysis",
+                    tokens=["restriction", "digest", "enzyme", "cut", "fragment", "fragments", "site"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature", "report_table"],
+                )
+            )
+        if "primer_validation" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "primer_validation",
+                    "Validate primer binding, orientation, Tm/GC, and expected amplicon or Gibson overlap.",
+                    stage="analysis",
+                    tokens=["primer", "primer3", "pcr", "gibson", "overlap", "amplicon", "tm", "decipher"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature", "report_table"],
+                )
+            )
+        if "sequence_alignment" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "sequence_alignment",
+                    "Align primer, gene, or vector subsequences to validate exact or local matches.",
+                    stage="analysis",
+                    tokens=["align", "alignment", "mummer", "parasail", "match", "exact", "local"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["sequence_feature"],
+                )
+            )
+        if "kozak_scoring" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "kozak_scoring",
+                    "Score Kozak context and translation-efficiency signals around candidate start codons.",
+                    stage="analysis",
+                    tokens=["kozak", "translation", "efficiency", "start", "codon", "rna"],
+                    inputs=["text", "sequence_feature"],
+                    outputs=["report_table"],
+                )
+            )
+        if "option_comparison" in task_tags:
+            steps.append(
+                self._step_spec(
+                    "option_comparison",
+                    "Map the computed result to the multiple-choice options and verify the final letter.",
+                    stage="downstream",
+                    tokens=["compare", "choice", "choices", "option", "answer", "verify"],
+                    inputs=["report_table", "sequence_feature", "text"],
+                    outputs=["report_table"],
+                )
+            )
+
+        if profile.get("has_sequence") and not profile.get("is_seqqa"):
+            steps.append(
+                self._step_spec(
+                    "protein_identification",
+                    "Ground the provided sequence to a protein or reference entity before downstream analysis.",
+                    stage="input_acquisition",
+                    tokens=["protein", "sequence", "reference", "identify", "uniprot", "blast", "ensembl", "homology"],
+                    inputs=["text"],
+                    outputs=["database_record"],
+                )
+            )
+
+        if profile.get("has_variant") and (profile.get("has_sequence") or profile.get("is_multiple_choice")):
+            steps.append(
+                self._step_spec(
+                    "candidate_variant_extraction",
+                    "Derive or compare the candidate variants against the grounded sequence context.",
+                    stage="analysis",
+                    tokens=["variant", "compare", "alignment", "mutation", "substitution", "sequence"],
+                    inputs=["text", "database_record"],
+                    outputs=["vcf", "annotated_variant_table"],
+                )
+            )
+
+        for resource in profile.get("resource_tokens", [])[:2]:
+            steps.append(
+                self._step_spec(
+                    f"{resource}_lookup",
+                    f"Query {resource} for task-specific evidence tied to the grounded entity or candidate variants.",
+                    stage="analysis",
+                    tokens=[resource, "query", "lookup", "record", "annotation", "database"],
+                    inputs=["text", "database_record", "vcf", "annotated_variant_table"],
+                    outputs=["database_record", "annotated_variant_table"],
+                )
+            )
+
+        if profile.get("needs_comparison"):
+            steps.append(
+                self._step_spec(
+                    "option_comparison",
+                    "Compare the competing options using the collected evidence and rank the supported candidate.",
+                    stage="downstream",
+                    tokens=["compare", "rank", "difference", "summary", "evidence", "supported"],
+                    inputs=["database_record", "annotated_variant_table", "variant_summary"],
+                    outputs=["variant_summary", "report_table"],
+                )
+            )
+
+        if not steps:
+            subtasks = [str(step).strip() for step in query_context.get("subtasks", []) if str(step).strip()]
+            for index, step in enumerate(subtasks[:4], start=1):
+                steps.append(
+                    self._step_spec(
+                        f"subtask_{index}",
+                        step,
+                        stage="analysis",
+                        tokens=sorted(self._tokenize(step)),
+                        inputs=task_spec.get("input_types", ["text"]),
+                        outputs=[(task_spec.get("target_output") or {}).get("semantic_type") or "report_table"],
+                    )
+                )
+
+        if not steps and ranked_paths:
+            best_path = ranked_paths[0]
+            for operation in best_path.get("operations", []):
+                operation_spec = self.schema_extractor.OPERATION_SPECS.get(operation, {})
+                steps.append(
+                    self._step_spec(
+                        operation,
+                        f"Execute graph operation {operation}.",
+                        stage=operation_spec.get("stage", "analysis"),
+                        tokens=sorted(operation_spec.get("patterns", [])),
+                        inputs=operation_spec.get("accepts", ["text"]),
+                        outputs=operation_spec.get("produces", ["report_table"]),
+                    )
+                )
+
+        return self._dedupe_steps(steps)
+
+    def _step_spec(
+        self,
+        label: str,
+        objective: str,
+        *,
+        stage: str,
+        tokens: list[str],
+        inputs: list[str],
+        outputs: list[str],
+    ) -> dict:
+        return {
+            "label": label,
+            "objective": objective,
+            "stage": stage,
+            "tokens": sorted({token.lower() for token in tokens if token}),
+            "inputs": inputs,
+            "outputs": outputs,
+        }
+
+    def _dedupe_steps(self, steps: list[dict]) -> list[dict]:
+        deduped = []
+        seen = set()
+        for step in steps:
+            key = step["label"]
+            if key in seen:
+                continue
+            seen.add(key)
+            deduped.append(step)
+        return deduped
+
+    def _select_tool_chain(
+        self,
+        step_specs: list[dict],
+        profile: dict,
+        tool_graph: ToolGraph,
+        *,
+        top_k_tools: int,
+        graph_rag_candidates: list[dict] | None = None,
+    ) -> list[dict]:
+        tool_plan = []
+        previous_step = None
+        used_nodes = set()
+        candidate_nodes = {item.get("node_id") for item in graph_rag_candidates or [] if item.get("node_id")}
+        candidate_scores = {item.get("node_id"): float(item.get("score", 0.0)) for item in graph_rag_candidates or []}
+        for step_index, step_spec in enumerate(step_specs, start=1):
+            candidate = self._best_tool_for_step(
+                step_spec,
+                profile,
+                tool_graph,
+                previous_step=previous_step,
+                used_nodes=used_nodes,
+                candidate_nodes=candidate_nodes,
+                candidate_scores=candidate_scores,
+            )
+            if candidate is None:
+                tool_plan.append(
+                    {
+                        "step": step_index,
+                        "operation": step_spec["label"],
+                        "server": "agent",
+                        "tool": "reason_over_evidence",
+                        "stage": step_spec["stage"],
+                        "input_types": step_spec["inputs"],
+                        "output_types": step_spec["outputs"],
+                        "candidate_tool_count": 0,
+                        "binding_source": "agent",
+                        "planning_rationale": "no graph tool with strong semantic alignment; keep this as an agent reasoning step",
+                    }
+                )
+                previous_step = tool_plan[-1]
+                continue
+
+            used_nodes.add(candidate["node_id"])
+            tool_plan.append(
+                {
+                    "step": step_index,
+                    "operation": step_spec["label"],
+                    "server": candidate["server"],
+                    "tool": candidate["name"],
+                    "stage": candidate.get("stage") or step_spec["stage"],
+                    "input_types": candidate.get("consumes") or step_spec["inputs"],
+                    "output_types": candidate.get("produces") or step_spec["outputs"],
+                    "candidate_tool_count": candidate["candidate_count"],
+                    "binding_source": "graph",
+                    "node_id": candidate["node_id"],
+                    "planning_score": round(candidate["score"], 3),
+                    "planning_rationale": candidate["reason"],
+                }
+            )
+            previous_step = tool_plan[-1]
+
+        return tool_plan[:top_k_tools]
+
+    def _best_tool_for_step(
+        self,
+        step_spec: dict,
+        profile: dict,
+        tool_graph: ToolGraph,
+        *,
+        previous_step: dict | None,
+        used_nodes: set[str],
+        candidate_nodes: set[str] | None = None,
+        candidate_scores: dict[str, float] | None = None,
+    ) -> dict | None:
+        scored = []
+        query_focus = set(profile.get("focus_tokens", []))
+        query_resources = set(profile.get("resource_tokens", []))
+        for server_name, payload in tool_graph.server_index.items():
+            for tool in payload.get("tools", []):
+                if candidate_nodes and tool.get("node_id") not in candidate_nodes:
+                    continue
+                tool_text = " ".join(
+                    [
+                        server_name,
+                        str(tool.get("name", "")),
+                        str(tool.get("description", "")),
+                        " ".join(tool.get("keywords", [])),
+                        " ".join(tool.get("capabilities", [])),
+                        " ".join(tool.get("consumes", [])),
+                        " ".join(tool.get("produces", [])),
+                    ]
+                ).lower()
+                tool_tokens = self._tokenize(tool_text)
+                score, reasons = self._score_tool_candidate(
+                    tool,
+                    server_name,
+                    step_spec,
+                    query_focus,
+                    query_resources,
+                    profile,
+                    tool_graph,
+                    previous_step,
+                    reused=tool.get("node_id") in used_nodes,
+                )
+                if candidate_scores and tool.get("node_id") in candidate_scores:
+                    score += min(candidate_scores[tool.get("node_id", "")], 12.0) * 0.35
+                    reasons.append("graph_rag_prior")
+                if score <= 0.0:
+                    continue
+                scored.append(
+                    {
+                        "score": score,
+                        "reason": "; ".join(reasons[:4]) if reasons else "semantic alignment",
+                        "reason_labels": reasons,
+                        "node_id": tool["node_id"],
+                        "server": server_name,
+                        "name": tool.get("name"),
+                        "stage": tool.get("stage"),
+                        "consumes": tool.get("consumes", []),
+                        "produces": tool.get("produces", []),
+                        "tool_tokens": sorted(tool_tokens),
+                    }
+                )
+
+        scored.sort(key=lambda item: (item["score"], item["server"], item["name"] or ""), reverse=True)
+        if not scored:
+            if candidate_nodes:
+                return self._best_tool_for_step(
+                    step_spec,
+                    profile,
+                    tool_graph,
+                    previous_step=previous_step,
+                    used_nodes=used_nodes,
+                    candidate_nodes=None,
+                    candidate_scores=None,
+                )
+            return None
+        best = dict(scored[0])
+        best["candidate_count"] = len(scored)
+        if best["score"] < 4.5:
+            return None
+        if not self._candidate_meets_step_contract(best, step_spec, profile):
+            return None
+        return best
+
+    def _infer_task_tags(self, text: str, categories: set[str]) -> set[str]:
+        tags = set()
+        if "seqqa" in categories or "seqqa" in text or re.search(r"\b[acgtu]{30,}\b", text, flags=re.IGNORECASE):
+            tags.add("seqqa")
+        if self._asks_gc_content(text):
+            tags.update({"base_counting", "gc_content_calculation"})
+        if any(token in text for token in ("reverse complement", "revcomp")):
+            tags.add("reverse_complement")
+        if any(token in text for token in ("orf", "open reading frame", "aa encoded", "amino acid", "translation efficiency")):
+            tags.add("orf_detection")
+        if any(token in text for token in ("restriction", "digest", "enzyme", "fragment", "fragments")):
+            tags.add("restriction_digest")
+        if any(token in text for token in ("primer", "pcr", "gibson", "linearize", "linearized", "clone")):
+            tags.update({"primer_validation", "sequence_alignment"})
+        if any(token in text for token in ("kozak", "translation efficiency", "human cell")):
+            tags.add("kozak_scoring")
+        if any(token in text for token in ("which of the following", "choices", "(a)", "(b)")):
+            tags.add("option_comparison")
+        return tags
+
+    def _asks_gc_content(self, text: str) -> bool:
+        return bool(
+            re.search(r"\b(percent|percentage)\s+gc\b", text)
+            or re.search(r"\bgc\s+(content|percent|percentage)\b", text)
+            or re.search(r"\bwhat\s+is\s+the\s+gc\b", text)
+        )
+
+    def _score_tool_candidate(
+        self,
+        tool: dict,
+        server_name: str,
+        step_spec: dict,
+        query_focus: set[str],
+        query_resources: set[str],
+        profile: dict,
+        tool_graph: ToolGraph,
+        previous_step: dict | None,
+        *,
+        reused: bool,
+    ) -> tuple[float, list[str]]:
+        text = " ".join(
+            [
+                server_name,
+                str(tool.get("name", "")),
+                str(tool.get("description", "")),
+                " ".join(tool.get("keywords", [])),
+                " ".join(tool.get("capabilities", [])),
+                " ".join(tool.get("consumes", [])),
+                " ".join(tool.get("produces", [])),
+            ]
+        ).lower()
+        tool_tokens = self._tokenize(text)
+        step_tokens = set(step_spec.get("tokens", []))
+
+        score = 0.0
+        reasons = []
+
+        token_hits = step_tokens & tool_tokens
+        if token_hits:
+            score += min(len(token_hits), 6) * 1.4
+            reasons.append("step_tokens=" + ",".join(sorted(list(token_hits))[:4]))
+
+        focus_hits = query_focus & tool_tokens
+        if focus_hits:
+            score += min(len(focus_hits), 5) * 0.9
+            reasons.append("query_focus=" + ",".join(sorted(list(focus_hits))[:4]))
+
+        resource_hits = query_resources & tool_tokens
+        if resource_hits:
+            score += len(resource_hits) * 2.2
+            reasons.append("resource=" + ",".join(sorted(resource_hits)))
+
+        stage = tool.get("stage") or "analysis"
+        if stage == step_spec.get("stage"):
+            score += 1.2
+            reasons.append("stage_match")
+
+        desired_inputs = set(step_spec.get("inputs", []))
+        desired_outputs = set(step_spec.get("outputs", []))
+        tool_inputs = set(tool.get("consumes", []))
+        tool_outputs = set(tool.get("produces", []))
+        io_hits = (desired_inputs & tool_inputs) | (desired_outputs & tool_outputs)
+        if io_hits:
+            score += min(len(io_hits), 3) * 1.1
+            reasons.append("io_match=" + ",".join(sorted(list(io_hits))[:3]))
+        elif desired_outputs and tool_outputs and not (desired_outputs & tool_outputs):
+            score -= 1.8
+            reasons.append("io_mismatch")
+
+        step_label = step_spec.get("label", "")
+        if step_label == "protein_identification" and any(token in text for token in ("blast", "uniprot", "ensembl", "hhblits")):
+            score += 3.0
+            reasons.append("protein_grounding_tool")
+        if step_label == "candidate_variant_extraction" and any(
+            token in text for token in ("variant", "align", "blast", "consensus", "compare", "mutation")
+        ):
+            score += 2.5
+            reasons.append("variant_extraction_tool")
+        if step_label.endswith("_lookup") and any(token in text for token in ("query", "lookup", "search", "fetch", "database")):
+            score += 2.5
+            reasons.append("lookup_tool")
+        if step_label == "option_comparison" and any(token in text for token in ("compare", "summary", "annotation", "effect", "query")):
+            score += 1.8
+            reasons.append("comparison_support")
+        if step_label in {"base_counting", "gc_content_calculation"}:
+            if {"bases", "count", "atgc", "alphabet", "composition"} & tool_tokens:
+                score += 4.5
+                reasons.append("base_counting_tool")
+            if {"derep", "dereplicate", "duplicate", "grep", "filter", "extract"} & tool_tokens and not {
+                "bases",
+                "atgc",
+                "alphabet",
+            } & tool_tokens:
+                score -= 5.0
+                reasons.append("base_counting_wrong_operation_penalty")
+            if {"grep", "filter", "extract"} & tool_tokens and not {"bases", "atgc"} & tool_tokens:
+                score -= 3.5
+                reasons.append("base_counting_filter_penalty")
+        if step_label == "reverse_complement" and {"reverse", "complement", "rc"} & tool_tokens:
+            score += 4.0
+            reasons.append("reverse_complement_tool")
+        if step_label == "orf_detection" and {"orf", "orfs", "pyrodigal", "orfhunter", "translate"} & tool_tokens:
+            score += 5.0
+            reasons.append("orf_tool")
+        if step_label == "restriction_digest" and {"restriction", "digest", "enzyme", "cut", "fragment"} & tool_tokens:
+            score += 4.0
+            reasons.append("restriction_digest_tool")
+        if step_label == "primer_validation" and {"primer", "primer3", "pcr", "gibson", "tm"} & tool_tokens:
+            score += 5.0
+            reasons.append("primer_tool")
+        if step_label == "sequence_alignment" and {"align", "alignment", "mummer", "parasail", "match"} & tool_tokens:
+            score += 4.5
+            reasons.append("sequence_alignment_tool")
+        if step_label == "kozak_scoring" and {"kozak", "translation", "efficiency", "rna"} & tool_tokens:
+            score += 3.5
+            reasons.append("kozak_tool")
+        if step_label.endswith("_lookup") and query_resources and not resource_hits:
+            score -= 3.0
+            reasons.append("missing_named_resource")
+
+        if previous_step:
+            connectivity = self._tool_connectivity_score(tool, previous_step, tool_graph)
+            if connectivity > 0:
+                score += connectivity
+                reasons.append("graph_connected")
+
+        if reused:
+            score -= 0.4
+
+        if "orf" in tool_tokens and "orf" not in step_tokens and "coding" not in step_tokens:
+            score -= 4.5
+            reasons.append("orf_penalty")
+        if "promoter" in tool_tokens and "promoter" not in query_focus:
+            score -= 4.5
+            reasons.append("promoter_penalty")
+        if {"csv", "export"} & tool_tokens and step_label not in {"csv_export"}:
+            score -= 3.5
+            reasons.append("export_penalty")
+        if not self._is_sequencing_workflow(profile) and tool_inputs & self.SEQUENCING_INPUT_TYPES:
+            score -= 4.0
+            reasons.append("sequencing_workflow_penalty")
+        if self._wrong_domain_penalty(tool_tokens, profile):
+            score -= 3.5
+            reasons.append("wrong_domain_penalty")
+        if "spatial" in tool_tokens and "spatial" not in query_focus:
+            score -= 3.0
+            reasons.append("domain_penalty")
+        if profile.get("asks_clinical_significance") and "consensus" in tool_tokens:
+            score -= 1.5
+            reasons.append("consensus_penalty")
+        if profile.get("asks_clinical_significance") and step_label in {
+            "candidate_variant_extraction",
+            "option_comparison",
+        } and not ({"variant", "annotation", "effect", "mutation"} & tool_tokens):
+            score -= 2.5
+            reasons.append("clinical_variant_penalty")
+
+        return score, reasons
+
+    def _tool_connectivity_score(self, tool: dict, previous_step: dict, tool_graph: ToolGraph) -> float:
+        prev_node_id = previous_step.get("node_id")
+        if not prev_node_id or prev_node_id not in tool_graph.nodes:
+            return 0.0
+
+        current_node_id = tool.get("node_id")
+        if current_node_id == prev_node_id:
+            return 0.5
+
+        for edge in tool_graph.adjacency.get(prev_node_id, []):
+            if edge.get("target") == current_node_id and edge.get("type") in self.EDGE_TYPES:
+                return 2.5
+
+        prev_outputs = set(previous_step.get("output_types", []))
+        current_inputs = set(tool.get("consumes", []))
+        if prev_outputs & current_inputs:
+            return 1.8
+
+        return 0.0
+
+    def _build_type_trace(self, tool_plan: list[dict], task_spec: dict) -> list[str]:
+        trace = []
+        default_inputs = task_spec.get("input_types", []) or ["text"]
+        if default_inputs:
+            trace.append(default_inputs[0])
+        for step in tool_plan:
+            outputs = step.get("output_types", [])
+            if outputs:
+                trace.append(outputs[0])
+            elif trace:
+                trace.append(trace[-1])
+        return trace or ["text"]
+
+    def _tokenize(self, text: str) -> set[str]:
+        normalized = text.lower().replace("-", " ").replace("/", " ").replace("_", " ")
+        return {token for token in self.TOKEN_PATTERN.findall(normalized) if token}
+
+    def _is_sequencing_workflow(self, profile: dict) -> bool:
+        text = profile.get("text", "")
+        return any(
+            token in text
+            for token in ("fastq", "rna-seq", "rnaseq", "reads", "alignment", "count matrix", "raw counts")
+        )
+
+    def _wrong_domain_penalty(self, tool_tokens: set[str], profile: dict) -> bool:
+        text = profile.get("text", "")
+        allowed = {
+            token
+            for token in self.WRONG_DOMAIN_TOKENS
+            if token in text
+        }
+        return bool((tool_tokens & self.WRONG_DOMAIN_TOKENS) - allowed)
+
+    def _candidate_meets_step_contract(self, candidate: dict, step_spec: dict, profile: dict) -> bool:
+        step_label = step_spec.get("label", "")
+        tool_tokens = set(candidate.get("tool_tokens", []))
+        tool_inputs = set(candidate.get("consumes", []))
+        tool_outputs = set(candidate.get("produces", []))
+        reasons = set(candidate.get("reason_labels", []))
+
+        if step_label == "protein_identification":
+            return bool(
+                {"protein_grounding_tool"} & reasons
+                or {"blast", "uniprot", "ensembl", "hhblits", "homology"} & tool_tokens
+                or "database_record" in tool_outputs
+            )
+
+        if step_label == "candidate_variant_extraction":
+            if not tool_outputs & {"vcf", "annotated_variant_table", "variant_summary"}:
+                return False
+            if not {"variant", "mutation", "annotation", "effect", "align", "compare"} & tool_tokens:
+                return False
+            if not self._is_sequencing_workflow(profile) and tool_inputs & self.SEQUENCING_INPUT_TYPES:
+                return False
+            return True
+
+        if step_label.endswith("_lookup"):
+            resource_name = step_label.rsplit("_", 1)[0]
+            has_named_resource = resource_name in tool_tokens
+            has_lookup_shape = bool({"lookup_tool"} & reasons) and bool(
+                tool_outputs & {"database_record", "annotated_variant_table", "variant_summary"}
+            )
+            return has_named_resource or has_lookup_shape
+
+        if step_label == "option_comparison":
+            if not tool_outputs & {"variant_summary", "report_table", "database_record", "annotated_variant_table"}:
+                return False
+            if not {"compare", "summary", "effect", "annotation", "rank"} & tool_tokens:
+                return False
+            if tool_inputs & self.SEQUENCING_INPUT_TYPES:
+                return False
+            return True
+
+        if step_label in {"base_counting", "gc_content_calculation"}:
+            return bool({"bases", "atgc", "alphabet"} & tool_tokens or "base_counting_tool" in reasons)
+
+        return True

Biomanus_upload/biomni/graph/schema_extractor.py

@@ -0,0 +1,1180 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+from biomni.graph.workflow_priors import WORKFLOW_PRIORS, rank_workflow_priors
+
+
+class ToolSchemaExtractor:
+    """Infer lightweight graph semantics from MCP/tool metadata."""
+
+    CAPABILITY_PATTERNS = {
+        "normalization": {"normalize", "normalization", "normalise", "normalisation", "size factor", "vst", "rlog"},
+        "quantification": {"quant", "quantification", "salmon", "kallisto", "abundance", "transcript"},
+        "read_counting": {"featurecounts", "htseq", "count reads", "read count", "summarizeoverlaps"},
+        "differential_expression": {
+            "deseq2",
+            "differential expression",
+            "differentially expressed",
+            "deg",
+            "edger",
+            "limma",
+            "log2fc",
+            "fold change",
+        },
+        "pathway_enrichment": {
+            "gsea",
+            "fgsea",
+            "clusterprofiler",
+            "enrichment",
+            "gene set",
+            "msigdb",
+            "kegg",
+            "reactome",
+            "gene ontology",
+        },
+        "data_inspection": {"inspect", "summary", "schema", "preview", "describe", "table"},
+        "exact_sequence_analysis": {"exact short-sequence primitive", "exact sequence primitive"},
+        "format_conversion": {"convert", "transform", "parse", "merge", "filter", "export"},
+        "single_cell_analysis": {"single-cell", "singlecell", "scrna", "scanpy", "seurat", "clustering", "umap"},
+        "alignment": {"align", "alignment", "bwa", "star", "map"},
+        "variant_calling": {"variant", "vcf", "gatk", "snp", "mutation"},
+        "variant_filtering": {"filter variant", "bcftools filter", "vcf filter", "normalize variant"},
+        "taxonomic_classification": {"taxonomy", "taxonomic", "kraken", "metaphlan", "centrifuge", "bracken"},
+        "genome_annotation": {"prokka", "annotate genome", "genome annotation"},
+        "orthology_clustering": {"orthofinder", "ortholog", "orthogroup", "cluster annotation"},
+        "annotation": {"annotate", "annotation", "label", "classify"},
+        "visualization": {"plot", "visual", "umap", "tsne", "heatmap", "volcano"},
+        "database_search": {
+            "database",
+            "lookup",
+            "search",
+            "pubmed",
+            "ensembl",
+            "clinvar",
+            "uniprot",
+            "biomart",
+            "msigdb",
+            "mirdb",
+            "gtrd",
+            "gene set",
+        },
+        "quality_control": {"qc", "quality", "filter", "trim", "clean"},
+        "statistics": {"stat", "qvalue", "pvalue", "regression", "test", "significance"},
+    }
+
+    DB_RESOURCE_HINTS = {
+        "ensembl",
+        "clinvar",
+        "uniprot",
+        "pubmed",
+        "biomart",
+        "msigdb",
+        "mirdb",
+        "gtrd",
+        "gene set",
+        "ontology",
+        "disease ontology",
+        "cell atlas",
+        "annotation database",
+        "metadata query",
+        "association table",
+    }
+
+    PATHWAY_HINTS = {
+        "gsea",
+        "fgsea",
+        "clusterprofiler",
+        "enrichment",
+        "gene set",
+        "pathway",
+        "kegg",
+        "reactome",
+        "gene ontology",
+        "msigdb",
+    }
+
+    SINGLE_CELL_HINTS = {
+        "single-cell",
+        "singlecell",
+        "scrna",
+        "scanpy",
+        "seurat",
+        "singlecellexperiment",
+        "cell atlas",
+        "cell type",
+        "umap",
+    }
+
+    DIFFERENTIAL_EXPRESSION_HINTS = {
+        "differential expression",
+        "deseq2",
+        "edger",
+        "limma",
+        "deg",
+        "fold change",
+        "log2fc",
+        "padj",
+    }
+
+    SERVER_CAPABILITY_ALLOWLISTS = {
+        "bwa": {"alignment"},
+        "hisat2": {"alignment"},
+        "star": {"alignment"},
+        "kallisto": {"quantification"},
+        "salmon": {"quantification"},
+        "bioconductor-tximport": {"quantification", "format_conversion", "read_counting"},
+        "bioconductor-deseq2": {"normalization", "differential_expression", "statistics", "visualization"},
+        "cnvkit": {"variant_calling", "variant_filtering", "annotation", "visualization"},
+        "samtools": {"alignment", "format_conversion", "data_inspection"},
+        "bcftools": {"variant_calling", "variant_filtering", "annotation", "format_conversion"},
+        "gatk": {"variant_calling", "variant_filtering"},
+        "gatk4": {"variant_calling", "variant_filtering"},
+        "freebayes": {"variant_calling"},
+        "ucsc-cell-browser": {"single_cell_analysis", "visualization", "data_inspection"},
+        "vpt": {"statistics", "annotation", "format_conversion"},
+        "r-dwls": {"statistics", "single_cell_analysis"},
+        "seacells": {"single_cell_analysis"},
+        "harpy": {"single_cell_analysis", "statistics"},
+    }
+
+    DATATYPE_PATTERNS = {
+        "anndata": {"anndata", "h5ad"},
+        "annotated_variant_table": {"annotated variant", "variant annotation table", "annotated vcf"},
+        "fastq": {"fastq", "fasta", "reads"},
+        "metagenomic_reads": {"metagenomic reads", "metagenomics reads", "microbiome reads"},
+        "bam": {"bam", "sam"},
+        "vcf": {"vcf", "variant"},
+        "reference_genome": {"reference genome", "genome index", "fasta", "genomic fna"},
+        "annotation_gff": {"gff", "gtf", "genomic annotation"},
+        "quant_table": {"quant.sf", "abundance table", "transcript abundance"},
+        "csv": {"csv", "tsv", "table"},
+        "json": {"json"},
+        "rds": {"rds", "seurat", "spatial object"},
+        "count_matrix": {"count", "counts", "matrix", "raw counts"},
+        "raw_count_matrix": {
+            "raw count",
+            "raw count matrix",
+            "raw count matrices",
+            "raw counts",
+            "integer counts",
+            "count matrix",
+            "count matrices",
+        },
+        "normalized_count_matrix": {"normalized count", "normalised count", "vst", "rlog", "size factor"},
+        "sample_metadata": {"sample metadata", "metadata table", "condition", "phenotype", "group labels"},
+        "de_table": {"differential expression", "deg", "log2fc", "padj", "de table"},
+        "differential_expression_table": {
+            "differential expression table",
+            "differential expression",
+            "deg",
+            "log2fc",
+            "padj",
+            "de table",
+        },
+        "significant_gene_list": {"significant genes", "up-regulated genes", "down-regulated genes", "de genes"},
+        "ranked_gene_list": {"ranked list", "ranked genes", "prerank", "gene ranking"},
+        "gene_list": {"gene list", "genes"},
+        "gene_symbol_list": {"gene symbol", "gene symbols", "symbol list"},
+        "entrez_gene_list": {"entrez", "entrez id", "entrez gene"},
+        "pathway_table": {"pathway", "enrichment", "gsea result"},
+        "kegg_enrichment_table": {"kegg enrichment", "enrichkegg", "kegg pathway"},
+        "go_enrichment_table": {"go enrichment", "gene ontology enrichment"},
+        "merged_pathway_table": {"merged pathway", "shared pathway", "comparative pathway"},
+        "taxonomic_profile": {"taxonomic profile", "relative abundance", "taxonomy table"},
+        "differential_abundance_table": {"differential abundance", "abundance difference"},
+        "genome_assembly": {"assembly", "genome assembly", "contig", "scaffold"},
+        "cluster_table": {"cluster table", "cluster annotation", "orthogroup"},
+        "marker_gene_table": {"marker gene", "cluster marker", "cell type marker"},
+        "database_record": {"database record", "knowledge source", "annotation record", "metadata entry"},
+        "sequence_feature": {"motif", "primer", "binding site", "sequence feature"},
+        "variant_summary": {"variant summary", "variant report"},
+        "report_table": {"final table", "output table", "result table"},
+        "image": {"png", "pdf", "plot", "figure", "image"},
+        "text": {"txt", "text", "markdown", "report", "summary"},
+    }
+
+    OPERATION_SPECS = {
+        "database_lookup": {
+            "patterns": {"database", "lookup", "search", "disgenet", "omim", "clinvar", "ensembl", "uniprot"},
+            "accepts": ["text", "gene_symbol_list"],
+            "produces": ["database_record"],
+            "capabilities": ["database_search", "annotation"],
+            "stage": "input_acquisition",
+        },
+        "sequence_feature_extraction": {
+            "patterns": {"sequence", "fasta", "motif", "primer", "binding site", "reverse complement"},
+            "accepts": ["text", "fastq", "reference_genome"],
+            "produces": ["sequence_feature"],
+            "capabilities": ["alignment", "annotation", "format_conversion"],
+            "stage": "analysis",
+        },
+        "base_counting": {
+            "patterns": {"base count", "count bases", "nucleotide count", "composition", "alphabet frequency"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "capabilities": ["statistics", "data_inspection", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "gc_content_calculation": {
+            "patterns": {"gc content", "percent gc", "gc percentage", "base composition"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["report_table"],
+            "capabilities": ["statistics", "data_inspection", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "reverse_complement": {
+            "patterns": {"reverse complement", "revcomp", "reverse-complement", "rc sequence"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature"],
+            "capabilities": ["format_conversion", "sequence_feature_extraction", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "orf_detection": {
+            "patterns": {"orf", "open reading frame", "translate", "translation", "coding sequence"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "capabilities": ["annotation", "sequence_feature_extraction", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "restriction_digest": {
+            "patterns": {"restriction digest", "digest", "restriction enzyme", "cut site", "fragments"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "capabilities": ["sequence_feature_extraction", "data_inspection", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "primer_validation": {
+            "patterns": {"primer", "pcr", "gibson", "amplicon", "primer pair", "tm", "linearize", "linearized"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "capabilities": ["sequence_feature_extraction", "alignment", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "sequence_alignment": {
+            "patterns": {"align sequence", "sequence alignment", "local alignment", "exact match", "pairwise alignment"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["sequence_feature"],
+            "capabilities": ["alignment"],
+            "stage": "analysis",
+        },
+        "kozak_scoring": {
+            "patterns": {"kozak", "translation efficiency", "start codon context", "human cell"},
+            "accepts": ["text", "sequence_feature"],
+            "produces": ["report_table"],
+            "capabilities": ["sequence_feature_extraction", "statistics", "exact_sequence_analysis"],
+            "stage": "analysis",
+        },
+        "quality_control": {
+            "patterns": {"fastqc", "multiqc", "quality control", "qc"},
+            "accepts": ["fastq"],
+            "produces": ["text", "image"],
+            "capabilities": ["quality_control"],
+            "stage": "preprocessing",
+        },
+        "quantification": {
+            "patterns": {"quantify", "quantification", "salmon", "kallisto", "abundance", "quant.sf"},
+            "accepts": ["fastq", "bam", "reference_genome"],
+            "produces": ["quant_table"],
+            "capabilities": ["quantification"],
+            "stage": "analysis",
+        },
+        "alignment": {
+            "patterns": {"align reads", "alignment", "hisat2", "star", "bwa", "bowtie2", "map reads"},
+            "accepts": ["fastq", "reference_genome"],
+            "produces": ["bam"],
+            "capabilities": ["alignment"],
+            "stage": "preprocessing",
+        },
+        "read_counting": {
+            "patterns": {"featurecounts", "htseq", "count reads", "read counts", "gene count"},
+            "accepts": ["bam", "annotation_gff"],
+            "produces": ["raw_count_matrix"],
+            "capabilities": ["read_counting"],
+            "stage": "analysis",
+        },
+        "count_normalization": {
+            "patterns": {"normalize counts", "normalise counts", "normalization", "size factor", "vst", "rlog"},
+            "accepts": ["raw_count_matrix", "sample_metadata"],
+            "produces": ["normalized_count_matrix"],
+            "capabilities": ["normalization"],
+            "stage": "analysis",
+        },
+        "differential_expression": {
+            "patterns": {"differential expression", "deseq2", "deg", "edger", "limma", "log2fc", "padj"},
+            "accepts": ["raw_count_matrix", "normalized_count_matrix", "sample_metadata"],
+            "produces": ["differential_expression_table"],
+            "capabilities": ["differential_expression", "statistics"],
+            "constraints": ["requires_replicates", "bulk_rna_seq"],
+            "stage": "analysis",
+        },
+        "gene_filtering": {
+            "patterns": {"filter genes", "significant genes", "up-regulated", "down-regulated", "padj"},
+            "accepts": ["differential_expression_table"],
+            "produces": ["significant_gene_list", "gene_symbol_list"],
+            "capabilities": ["format_conversion", "statistics"],
+            "stage": "downstream",
+        },
+        "gene_id_conversion": {
+            "patterns": {"gene id", "convert gene", "entrez", "symbol", "ortholog", "id conversion"},
+            "accepts": ["gene_symbol_list", "significant_gene_list"],
+            "produces": ["entrez_gene_list"],
+            "capabilities": ["annotation", "format_conversion", "genome_annotation"],
+            "stage": "downstream",
+        },
+        "kegg_enrichment": {
+            "patterns": {"kegg", "pathway enrichment", "enrichkegg", "clusterprofiler"},
+            "accepts": ["entrez_gene_list", "ranked_gene_list", "significant_gene_list"],
+            "produces": ["kegg_enrichment_table"],
+            "capabilities": ["pathway_enrichment"],
+            "constraints": ["requires_entrez_id"],
+            "stage": "downstream",
+        },
+        "go_enrichment": {
+            "patterns": {"go enrichment", "gene ontology", "enrichgo", "ontology"},
+            "accepts": ["entrez_gene_list", "ranked_gene_list", "significant_gene_list"],
+            "produces": ["go_enrichment_table"],
+            "capabilities": ["pathway_enrichment"],
+            "stage": "downstream",
+        },
+        "pathway_merge": {
+            "patterns": {"compare shared pathways", "shared pathways", "merge pathways", "compare pathways"},
+            "accepts": ["kegg_enrichment_table", "go_enrichment_table", "pathway_table"],
+            "produces": ["merged_pathway_table"],
+            "capabilities": ["format_conversion", "data_inspection"],
+            "stage": "reporting",
+        },
+        "csv_export": {
+            "patterns": {"csv", "output table", "save table", "export"},
+            "accepts": [
+                "merged_pathway_table",
+                "kegg_enrichment_table",
+                "go_enrichment_table",
+                "pathway_table",
+                "differential_expression_table",
+                "variant_summary",
+                "taxonomic_profile",
+            ],
+            "produces": ["report_table"],
+            "capabilities": ["format_conversion"],
+            "stage": "reporting",
+        },
+        "variant_annotation": {
+            "patterns": {"variant annotation", "vep", "snpeff", "annotate variant", "clinvar"},
+            "accepts": ["vcf"],
+            "produces": ["annotated_variant_table"],
+            "capabilities": ["annotation", "variant_filtering"],
+            "stage": "analysis",
+        },
+        "variant_summary": {
+            "patterns": {"variant summary", "summarize variants", "variant report"},
+            "accepts": ["annotated_variant_table", "vcf"],
+            "produces": ["variant_summary"],
+            "capabilities": ["data_inspection", "format_conversion"],
+            "stage": "reporting",
+        },
+        "single_cell_clustering": {
+            "patterns": {"single-cell", "singlecell", "scrna", "scanpy", "seurat", "clustering", "umap"},
+            "accepts": ["anndata", "rds"],
+            "produces": ["cluster_table"],
+            "capabilities": ["single_cell_analysis"],
+            "stage": "analysis",
+        },
+        "marker_gene_detection": {
+            "patterns": {"marker genes", "cluster markers", "cell type markers"},
+            "accepts": ["anndata", "cluster_table"],
+            "produces": ["marker_gene_table", "gene_symbol_list"],
+            "capabilities": ["single_cell_analysis", "statistics"],
+            "stage": "downstream",
+        },
+        "taxonomic_classification": {
+            "patterns": {"taxonomy", "taxonomic", "kraken", "metaphlan", "centrifuge", "bracken"},
+            "accepts": ["fastq", "metagenomic_reads"],
+            "produces": ["taxonomic_profile"],
+            "capabilities": ["taxonomic_classification"],
+            "stage": "analysis",
+        },
+        "differential_abundance": {
+            "patterns": {"differential abundance", "abundance difference", "compare abundance"},
+            "accepts": ["taxonomic_profile", "sample_metadata"],
+            "produces": ["differential_abundance_table"],
+            "capabilities": ["statistics"],
+            "stage": "downstream",
+        },
+    }
+
+    STAGE_RULES = [
+        ("input_acquisition", {"database_search"}),
+        (
+            "preprocessing",
+            {"data_inspection", "format_conversion", "quality_control", "alignment", "normalization"},
+        ),
+        (
+            "analysis",
+            {
+                "quantification",
+                "read_counting",
+                "differential_expression",
+                "single_cell_analysis",
+                "variant_calling",
+                "variant_filtering",
+                "taxonomic_classification",
+                "orthology_clustering",
+                "statistics",
+            },
+        ),
+        ("downstream", {"pathway_enrichment", "annotation", "genome_annotation"}),
+        ("reporting", {"visualization"}),
+    ]
+
+    STOPWORDS = {
+        "the",
+        "and",
+        "for",
+        "with",
+        "from",
+        "that",
+        "this",
+        "into",
+        "using",
+        "data",
+        "tool",
+        "file",
+        "files",
+        "analysis",
+        "result",
+        "results",
+        "input",
+        "output",
+    }
+
+    CURATED_SERVER_SEMANTICS = {
+        "salmon": {
+            "capabilities": ["quantification"],
+            "consumes": ["fastq", "reference_genome"],
+            "produces": ["quant_table"],
+            "operations": ["quantification"],
+            "stage": "analysis",
+        },
+        "bioconductor-tximport": {
+            "capabilities": ["quantification", "format_conversion"],
+            "consumes": ["quant_table", "annotation_gff"],
+            "produces": ["count_matrix"],
+            "operations": ["read_counting"],
+            "stage": "analysis",
+        },
+        "bioconductor-deseq2": {
+            "capabilities": ["normalization", "differential_expression", "statistics", "visualization"],
+            "consumes": ["raw_count_matrix", "sample_metadata", "count_matrix"],
+            "produces": ["differential_expression_table", "de_table", "image"],
+            "operations": ["count_normalization", "differential_expression", "gene_filtering"],
+            "stage": "analysis",
+        },
+        "hisat2": {
+            "capabilities": ["alignment"],
+            "consumes": ["fastq", "reference_genome", "annotation_gff"],
+            "produces": ["bam"],
+            "operations": ["alignment"],
+            "stage": "preprocessing",
+        },
+        "star": {
+            "capabilities": ["alignment"],
+            "consumes": ["fastq", "reference_genome", "annotation_gff"],
+            "produces": ["bam"],
+            "operations": ["alignment"],
+            "stage": "preprocessing",
+        },
+        "htseq": {
+            "capabilities": ["read_counting"],
+            "consumes": ["bam", "annotation_gff"],
+            "produces": ["raw_count_matrix", "count_matrix"],
+            "operations": ["read_counting"],
+            "stage": "analysis",
+        },
+        "subread": {
+            "capabilities": ["alignment", "read_counting"],
+            "consumes": ["fastq", "bam", "reference_genome", "annotation_gff"],
+            "produces": ["bam", "raw_count_matrix", "count_matrix"],
+            "operations": ["alignment", "read_counting"],
+            "stage": "analysis",
+        },
+        "fastqc": {
+            "capabilities": ["quality_control"],
+            "consumes": ["fastq"],
+            "produces": ["text"],
+            "operations": ["quality_control"],
+            "stage": "preprocessing",
+        },
+        "multiqc": {
+            "capabilities": ["quality_control", "visualization"],
+            "consumes": ["text"],
+            "produces": ["text", "image"],
+            "operations": ["quality_control", "csv_export"],
+            "stage": "reporting",
+        },
+        "gffutils": {
+            "capabilities": ["genome_annotation", "format_conversion", "data_inspection"],
+            "consumes": ["annotation_gff", "reference_genome"],
+            "produces": ["annotation_gff", "gene_list", "gene_symbol_list", "csv"],
+            "operations": ["gene_id_conversion", "database_lookup"],
+            "stage": "preprocessing",
+        },
+        "bcftools": {
+            "capabilities": ["variant_calling", "variant_filtering", "annotation"],
+            "consumes": ["bam", "vcf", "reference_genome"],
+            "produces": ["vcf", "annotated_variant_table", "variant_summary"],
+            "operations": ["variant_annotation", "variant_summary"],
+            "stage": "analysis",
+        },
+        "seqfu": {
+            "capabilities": ["data_inspection", "format_conversion", "statistics"],
+            "consumes": ["text", "fastq", "sequence_feature"],
+            "produces": ["text", "sequence_feature", "report_table"],
+            "operations": ["base_counting", "gc_content_calculation", "reverse_complement", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "bioawk": {
+            "capabilities": ["data_inspection", "format_conversion", "statistics"],
+            "consumes": ["text", "fastq", "sequence_feature"],
+            "produces": ["text", "sequence_feature", "report_table"],
+            "operations": ["base_counting", "gc_content_calculation", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "primer3": {
+            "capabilities": ["sequence_feature_extraction", "alignment", "statistics"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["primer_validation", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "bioconductor-decipher": {
+            "capabilities": ["alignment", "annotation", "sequence_feature_extraction"],
+            "consumes": ["text", "sequence_feature", "fastq", "reference_genome"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["primer_validation", "sequence_alignment", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "pyrodigal": {
+            "capabilities": ["annotation", "sequence_feature_extraction"],
+            "consumes": ["text", "sequence_feature", "reference_genome"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["orf_detection", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "mummer": {
+            "capabilities": ["alignment", "data_inspection"],
+            "consumes": ["text", "sequence_feature", "reference_genome"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["sequence_alignment", "primer_validation"],
+            "stage": "analysis",
+        },
+        "parasail-python": {
+            "capabilities": ["alignment", "statistics"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["sequence_alignment", "primer_validation"],
+            "stage": "analysis",
+        },
+        "viennarna": {
+            "capabilities": ["sequence_feature_extraction", "statistics"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["kozak_scoring", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "sequence-operations": {
+            "capabilities": ["sequence_feature_extraction", "statistics", "data_inspection", "alignment"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "local-bio-cache": {
+            "capabilities": ["database_search", "alignment", "data_inspection"],
+            "consumes": ["text", "sequence_feature", "reference_genome"],
+            "produces": ["database_record", "sequence_feature", "report_table"],
+            "operations": ["database_lookup", "sequence_alignment", "sequence_feature_extraction"],
+            "stage": "analysis",
+        },
+        "gatk": {
+            "capabilities": ["variant_calling", "variant_filtering"],
+            "consumes": ["bam", "reference_genome"],
+            "produces": ["vcf"],
+            "operations": ["variant_annotation"],
+            "stage": "analysis",
+        },
+        "freebayes": {
+            "capabilities": ["variant_calling"],
+            "consumes": ["bam", "reference_genome"],
+            "produces": ["vcf"],
+            "operations": ["variant_annotation"],
+            "stage": "analysis",
+        },
+        "kraken2": {
+            "capabilities": ["taxonomic_classification"],
+            "consumes": ["fastq", "metagenomic_reads"],
+            "produces": ["taxonomic_profile"],
+            "operations": ["taxonomic_classification"],
+            "stage": "analysis",
+        },
+        "metaphlan": {
+            "capabilities": ["taxonomic_classification"],
+            "consumes": ["fastq", "metagenomic_reads"],
+            "produces": ["taxonomic_profile"],
+            "operations": ["taxonomic_classification"],
+            "stage": "analysis",
+        },
+        "prokka": {
+            "capabilities": ["genome_annotation"],
+            "consumes": ["genome_assembly"],
+            "produces": ["annotation_gff", "gene_list"],
+            "operations": ["gene_id_conversion"],
+            "stage": "analysis",
+        },
+        "orthofinder": {
+            "capabilities": ["orthology_clustering"],
+            "consumes": ["gene_list"],
+            "produces": ["cluster_table"],
+            "operations": ["gene_id_conversion"],
+            "stage": "analysis",
+        },
+    }
+
+    CURATED_TOOL_SEMANTICS = {
+        ("sequence-operations", "gc_content"): {
+            "capabilities": ["statistics", "data_inspection"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["report_table"],
+            "operations": ["base_counting", "gc_content_calculation"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "reverse_complement"): {
+            "capabilities": ["format_conversion", "sequence_feature_extraction", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature"],
+            "operations": ["reverse_complement"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "find_orfs"): {
+            "capabilities": ["annotation", "sequence_feature_extraction", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["orf_detection"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "amino_acid_at_position_in_longest_orf"): {
+            "capabilities": ["annotation", "sequence_feature_extraction", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["orf_detection"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "restriction_digest"): {
+            "capabilities": ["sequence_feature_extraction", "data_inspection", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["restriction_digest"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "pcr_primer_analysis"): {
+            "capabilities": ["sequence_feature_extraction", "alignment", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["sequence_feature", "report_table"],
+            "operations": ["primer_validation", "sequence_alignment"],
+            "stage": "analysis",
+            "override": True,
+        },
+        ("sequence-operations", "kozak_score"): {
+            "capabilities": ["sequence_feature_extraction", "statistics", "exact_sequence_analysis"],
+            "consumes": ["text", "sequence_feature"],
+            "produces": ["report_table"],
+            "operations": ["kozak_scoring"],
+            "stage": "analysis",
+            "override": True,
+        },
+    }
+
+    def tokenize(self, text: str) -> set[str]:
+        return {
+            token
+            for token in re.findall(r"[a-z0-9_\-\.]{2,}", (text or "").lower())
+            if token not in self.STOPWORDS
+        }
+
+    def extract_tool_semantics(self, tool: dict, server_name: str | None = None) -> dict:
+        name = str(tool.get("name", ""))
+        description = str(tool.get("description", ""))
+        params = tool.get("inputSchema", {}).get("properties", {}) or tool.get("parameters", {}) or {}
+        param_text = " ".join(
+            f"{param_name} {spec.get('type', '')} {spec.get('description', '')}" for param_name, spec in params.items()
+        )
+        combined = " ".join(part for part in [server_name or "", name, description, param_text] if part)
+        tokens = self.tokenize(combined)
+
+        capabilities = self._match_labels(combined, self.CAPABILITY_PATTERNS)
+        consumes = self._infer_consumed_types(combined, params)
+        produces = self._infer_produced_types(combined, params, capabilities)
+        operations = self._infer_tool_operations(combined, capabilities)
+        constraints = self._infer_constraints(combined)
+        stage = self._infer_stage(capabilities, name, description)
+
+        curated = self._curated_semantics(server_name, name)
+        if curated:
+            if curated.get("override"):
+                capabilities = list(curated.get("capabilities", capabilities))
+                consumes = list(curated.get("consumes", consumes))
+                produces = list(curated.get("produces", produces))
+                operations = list(curated.get("operations", operations))
+                constraints = list(curated.get("constraints", constraints))
+            else:
+                capabilities = self._merge_labels(capabilities, curated.get("capabilities", []))
+                consumes = self._merge_labels(consumes, curated.get("consumes", []))
+                produces = self._merge_labels(produces, curated.get("produces", []))
+                operations = self._merge_labels(operations, curated.get("operations", []))
+                constraints = self._merge_labels(constraints, curated.get("constraints", []))
+            stage = curated.get("stage") or stage
+
+        operation_semantics = self._merge_operation_semantics(operations, consumes, produces, constraints)
+        consumes = operation_semantics["consumes"]
+        produces = operation_semantics["produces"]
+        constraints = operation_semantics["constraints"]
+
+        return {
+            "name": name,
+            "description": description,
+            "keywords": sorted(tokens),
+            "capabilities": capabilities,
+            "consumes": consumes,
+            "produces": produces,
+            "operations": operations,
+            "constraints": constraints,
+            "stage": stage,
+            "text": combined,
+        }
+
+    def extract_server_semantics(self, server_entry: dict) -> dict:
+        tool_semantics = [
+            self.extract_tool_semantics(tool, server_name=server_entry.get("name")) for tool in server_entry.get("tools", [])
+        ]
+        capability_counts = Counter()
+        datatype_counts = Counter()
+        operation_counts = Counter()
+        constraint_counts = Counter()
+        stage_counts = Counter()
+        keywords: set[str] = self.tokenize(
+            " ".join(
+                [
+                    server_entry.get("name", ""),
+                    server_entry.get("summary", ""),
+                    " ".join(server_entry.get("keywords", [])),
+                ]
+            )
+        )
+        for tool in tool_semantics:
+            capability_counts.update(tool["capabilities"])
+            datatype_counts.update(tool["consumes"])
+            datatype_counts.update(tool["produces"])
+            operation_counts.update(tool.get("operations", []))
+            constraint_counts.update(tool.get("constraints", []))
+            if tool["stage"]:
+                stage_counts.update([tool["stage"]])
+            keywords.update(tool["keywords"])
+
+        capabilities = [item for item, _ in capability_counts.most_common()]
+        capabilities = self._sanitize_server_capabilities(server_entry, capabilities, tool_semantics)
+        stage_counts = Counter(
+            tool["stage"]
+            for tool in tool_semantics
+            if tool.get("stage") and any(cap in capabilities for cap in tool.get("capabilities", []))
+        )
+
+        return {
+            "capabilities": capabilities,
+            "datatypes": [item for item, _ in datatype_counts.most_common()],
+            "operations": [item for item, _ in operation_counts.most_common()],
+            "constraints": [item for item, _ in constraint_counts.most_common()],
+            "stages": [item for item, _ in stage_counts.most_common()],
+            "keywords": sorted(keywords),
+            "tool_semantics": tool_semantics,
+        }
+
+    def _curated_semantics(self, server_name: str | None, tool_name: str | None = None) -> dict:
+        if not server_name:
+            return {}
+        server_key = server_name.lower()
+        tool_key = (tool_name or "").lower()
+        if tool_key:
+            curated_tool = self.CURATED_TOOL_SEMANTICS.get((server_key, tool_key), {})
+            if curated_tool:
+                return curated_tool
+        curated = self.CURATED_SERVER_SEMANTICS.get(server_key, {})
+        if not curated and server_key.startswith("bioconductor-"):
+            curated = self.CURATED_SERVER_SEMANTICS.get(server_key.replace("_", "-"), {})
+        return curated
+
+    def _merge_labels(self, primary: list[str], additions: list[str]) -> list[str]:
+        merged = []
+        for item in list(primary or []) + list(additions or []):
+            if item and item not in merged:
+                merged.append(item)
+        return merged
+
+    def _sanitize_server_capabilities(
+        self,
+        server_entry: dict,
+        capabilities: list[str],
+        tool_semantics: list[dict],
+    ) -> list[str]:
+        server_name = str(server_entry.get("name", "")).lower()
+        category = str(server_entry.get("category", "")).lower()
+        combined_text = " ".join(
+            [
+                server_name,
+                str(server_entry.get("summary", "")),
+                " ".join(server_entry.get("keywords", [])),
+                " ".join(tool.get("text", "") for tool in tool_semantics),
+            ]
+        ).lower()
+
+        sanitized = list(capabilities)
+
+        if "database_search" in sanitized and not any(hint in combined_text for hint in self.DB_RESOURCE_HINTS):
+            sanitized = [cap for cap in sanitized if cap != "database_search"]
+
+        if "pathway_enrichment" in sanitized and not any(hint in combined_text for hint in self.PATHWAY_HINTS):
+            sanitized = [cap for cap in sanitized if cap != "pathway_enrichment"]
+
+        if "single_cell_analysis" in sanitized and not any(hint in combined_text for hint in self.SINGLE_CELL_HINTS):
+            sanitized = [cap for cap in sanitized if cap != "single_cell_analysis"]
+
+        if "differential_expression" in sanitized and not any(
+            hint in combined_text for hint in self.DIFFERENTIAL_EXPRESSION_HINTS
+        ):
+            sanitized = [cap for cap in sanitized if cap != "differential_expression"]
+
+        if category in {"single_cell", "transcriptomics"} and "database_search" in sanitized:
+            if not any(hint in combined_text for hint in {"cell atlas", "metadata query", "annotation database"}):
+                sanitized = [cap for cap in sanitized if cap != "database_search"]
+
+        allowed = self.SERVER_CAPABILITY_ALLOWLISTS.get(server_name)
+        if allowed:
+            sanitized = [cap for cap in sanitized if cap in allowed]
+
+        return sanitized
+
+    def infer_query_semantics(self, query_context: dict) -> dict:
+        text_parts = [
+            query_context.get("question", ""),
+            query_context.get("original_query", ""),
+            query_context.get("rewritten_query", ""),
+            query_context.get("retrieval_query", ""),
+            " ".join(query_context.get("subtasks", [])),
+            " ".join(query_context.get("keywords", [])),
+            " ".join(query_context.get("categories", [])),
+        ]
+        text = " ".join(part for part in text_parts if part)
+        capabilities = self._match_labels(text, self.CAPABILITY_PATTERNS)
+        datatypes = self._match_labels(text, self.DATATYPE_PATTERNS)
+        operations = self._infer_operations(text)
+        for operation in operations:
+            capabilities = self._merge_labels(capabilities, self.OPERATION_SPECS.get(operation, {}).get("capabilities", []))
+        stages = self._infer_query_stages(query_context, capabilities)
+        operation_tokens = {token for operation in operations for token in operation.split("_")}
+        constraints = self._infer_constraints(text)
+        task_spec = self.infer_task_spec(query_context, text, datatypes, operations, constraints)
+        operation_anchors = self._merge_labels(operations, task_spec.get("required_operations", []))
+        return {
+            "keywords": sorted(self.tokenize(text) | operation_tokens),
+            "capabilities": capabilities,
+            "datatypes": datatypes,
+            "operations": operations,
+            "operation_anchors": operation_anchors,
+            "stages": stages,
+            "organism": self._infer_organism(text),
+            "branch_labels": self._infer_branch_labels(text),
+            "workflow_type": self._infer_workflow_type(text, operations),
+            "output_schema": self._infer_output_schema(text),
+            "constraints": constraints,
+            "task_spec": task_spec,
+        }
+
+    def infer_task_spec(
+        self,
+        query_context: dict,
+        text: str,
+        datatypes: list[str],
+        operations: list[str],
+        constraints: list[str],
+    ) -> dict:
+        categories = {str(category).lower() for category in query_context.get("categories", [])}
+        capability_set = set(self._match_labels(text, self.CAPABILITY_PATTERNS))
+        datatype_set = set(datatypes)
+        operation_set = set(operations)
+        ranked_priors = rank_workflow_priors(
+            WORKFLOW_PRIORS,
+            text=text,
+            categories=categories,
+            capabilities=capability_set,
+            datatypes=datatype_set,
+            operations=operation_set,
+        )
+
+        input_types = list(datatypes)
+        target_output = {"semantic_type": "report_table"}
+        required_operations = list(operations)
+        assay = None
+
+        # These priors are graph-structured soft constraints. They expose
+        # operation anchors and preferred type signatures, but the concrete
+        # operation path is still selected later by constrained subgraph search.
+        for prior, _score in ranked_priors:
+            input_types = self._merge_labels(input_types, list(prior.input_types))
+            required_operations = self._merge_labels(required_operations, list(prior.operation_hints))
+            assay = assay or prior.assay
+
+        if ranked_priors:
+            best_prior, best_score = ranked_priors[0]
+            target_output = {"semantic_type": best_prior.target_output}
+            for prior, score in ranked_priors[1:]:
+                if prior.target_output == "report_table" and score >= best_score - 1.0:
+                    target_output = {"semantic_type": "report_table"}
+                    break
+
+        organism = self._infer_organism(text)
+        constraint_payload = {
+            "labels": constraints,
+            "organism": organism,
+            "assay": assay,
+        }
+        if organism:
+            constraint_payload["labels"] = self._merge_labels(constraint_payload["labels"], [f"organism_{organism}"])
+
+        return {
+            "input_types": input_types or ["text"],
+            "target_output": target_output,
+            "constraints": constraint_payload,
+            "required_operations": required_operations,
+            "workflow_type": self._infer_workflow_type(text, required_operations),
+            "workflow_priors": [
+                {"name": prior.name, "score": score, "target_output": prior.target_output}
+                for prior, score in ranked_priors
+            ],
+        }
+
+    def _match_labels(self, text: str, pattern_map: dict[str, set[str]]) -> list[str]:
+        lowered = (text or "").lower()
+        matched = []
+        for label, hints in pattern_map.items():
+            if any(hint in lowered for hint in hints):
+                matched.append(label)
+        return matched
+
+    def _infer_operations(self, text: str) -> list[str]:
+        lowered = (text or "").lower()
+        operations = []
+        for operation, spec in self.OPERATION_SPECS.items():
+            hints = spec.get("patterns", set())
+            if any(hint in lowered for hint in hints):
+                operations.append(operation)
+        return operations
+
+    def _infer_tool_operations(self, text: str, capabilities: list[str]) -> list[str]:
+        operations = set(self._infer_operations(text))
+        capability_set = set(capabilities)
+        capability_defaults = {
+            "quality_control": ["quality_control"],
+            "alignment": ["alignment"],
+            "quantification": ["quantification"],
+            "read_counting": ["read_counting"],
+            "normalization": ["count_normalization"],
+            "differential_expression": ["differential_expression"],
+            "database_search": ["database_lookup"],
+            "taxonomic_classification": ["taxonomic_classification"],
+            "single_cell_analysis": ["single_cell_clustering"],
+            "variant_filtering": ["variant_annotation"],
+        }
+        for capability, defaults in capability_defaults.items():
+            if capability in capability_set:
+                operations.update(defaults)
+        return sorted(operations)
+
+    def _infer_constraints(self, text: str) -> list[str]:
+        lowered = (text or "").lower()
+        constraints = []
+        if any(token in lowered for token in ("mouse", "murine", "mus musculus")):
+            constraints.append("organism_mouse")
+        if any(token in lowered for token in ("human", "homo sapiens")):
+            constraints.append("organism_human")
+        if any(token in lowered for token in ("bulk rna", "bulk rna-seq", "deseq2", "raw counts")):
+            constraints.append("bulk_rna_seq")
+        if any(token in lowered for token in ("integer count", "raw count", "raw counts")):
+            constraints.append("requires_raw_integer_counts")
+        if "entrez" in lowered:
+            constraints.append("requires_entrez_id")
+        if any(token in lowered for token in ("replicate", "replicates")):
+            constraints.append("requires_replicates")
+        if any(token in lowered for token in ("paired-end", "paired end", "read1", "read2")):
+            constraints.append("paired_end_reads")
+        return constraints
+
+    def _merge_operation_semantics(
+        self,
+        operations: list[str],
+        consumes: list[str],
+        produces: list[str],
+        constraints: list[str],
+    ) -> dict:
+        merged_consumes = list(consumes)
+        merged_produces = list(produces)
+        merged_constraints = list(constraints)
+        for operation in operations:
+            spec = self.OPERATION_SPECS.get(operation, {})
+            merged_consumes = self._merge_labels(merged_consumes, spec.get("accepts", []))
+            merged_produces = self._merge_labels(merged_produces, spec.get("produces", []))
+            merged_constraints = self._merge_labels(merged_constraints, spec.get("constraints", []))
+        return {
+            "consumes": merged_consumes,
+            "produces": merged_produces,
+            "constraints": merged_constraints,
+        }
+
+    def _infer_organism(self, text: str) -> str | None:
+        lowered = (text or "").lower()
+        if any(token in lowered for token in ("mouse", "murine", "mus musculus")):
+            return "mouse"
+        if any(token in lowered for token in ("human", "homo sapiens")):
+            return "human"
+        return None
+
+    def _infer_branch_labels(self, text: str) -> list[str]:
+        labels = []
+        for pattern in (r"\b5xfad\b", r"\b3xtg[-_ ]?ad\b", r"\bps?[30o][0o]1s\b"):
+            for match in re.findall(pattern, text or "", flags=re.IGNORECASE):
+                normalized = match.replace(" ", "-")
+                if normalized.lower() == "3xtg-ad":
+                    normalized = "3xTG-AD"
+                elif normalized.lower() == "5xfad":
+                    normalized = "5xFAD"
+                elif normalized.lower() in {"ps301s", "ps3o1s", "p301s", "p3o1s"}:
+                    normalized = "PS301S"
+                if normalized not in labels:
+                    labels.append(normalized)
+        return labels
+
+    def _infer_workflow_type(self, text: str, operations: list[str]) -> str:
+        lowered = (text or "").lower()
+        has_comparison = any(token in lowered for token in ("compare", "comparative", "shared", "across"))
+        if has_comparison and len(self._infer_branch_labels(text)) >= 2:
+            return "fork_join_comparative_analysis"
+        if len(operations) > 1:
+            return "linear_typed_transformation"
+        return "single_step"
+
+    def _infer_output_schema(self, text: str) -> dict:
+        lowered = (text or "").lower()
+        if "pathway" in lowered and any(token in lowered for token in ("5xfad", "3xtg", "ps301s", "p301s")):
+            return {
+                "columns": ["pathway", "5xFAD_pvalue", "3xTG_AD_pvalue", "PS3O1S_pvalue"],
+                "join_key": "pathway",
+            }
+        if "csv" in lowered:
+            return {"format": "csv"}
+        return {}
+
+    def _infer_consumed_types(self, text: str, params: dict) -> list[str]:
+        lowered = (text or "").lower()
+        matched = set(self._match_labels(lowered, self.DATATYPE_PATTERNS))
+        for param_name, spec in params.items():
+            blob = f"{param_name} {spec.get('description', '')}".lower()
+            matched.update(self._match_labels(blob, self.DATATYPE_PATTERNS))
+            if any(keyword in param_name.lower() for keyword in ("input", "file", "path", "filename")):
+                matched.update(self._match_labels(blob, self.DATATYPE_PATTERNS))
+        return sorted(matched)
+
+    def _infer_produced_types(self, text: str, params: dict, capabilities: list[str]) -> list[str]:
+        lowered = (text or "").lower()
+        produced = set()
+        for label, hints in self.DATATYPE_PATTERNS.items():
+            if any(hint in lowered for hint in hints) and any(
+                marker in lowered for marker in ("save", "write", "export", "output", "generate", "produce")
+            ):
+                produced.add(label)
+        for param_name, spec in params.items():
+            blob = f"{param_name} {spec.get('description', '')}".lower()
+            if any(keyword in param_name.lower() for keyword in ("output", "save", "dest", "dir")):
+                produced.update(self._match_labels(blob, self.DATATYPE_PATTERNS))
+        if "pathway_enrichment" in capabilities:
+            produced.add("pathway_table")
+        if "differential_expression" in capabilities:
+            produced.add("de_table")
+        if "visualization" in capabilities:
+            produced.add("image")
+        return sorted(produced)
+
+    def _infer_stage(self, capabilities: list[str], name: str, description: str) -> str:
+        lowered = f"{name} {description}".lower()
+        if any(token in lowered for token in ("plot", "figure", "visual")):
+            return "reporting"
+        # Prefer later analytical stages over generic preprocessing hints.
+        priority_rules = [
+            ("downstream", {"pathway_enrichment", "annotation", "genome_annotation"}),
+            (
+                "analysis",
+                {
+                    "quantification",
+                    "read_counting",
+                    "differential_expression",
+                    "single_cell_analysis",
+                    "variant_calling",
+                    "variant_filtering",
+                    "taxonomic_classification",
+                    "orthology_clustering",
+                    "statistics",
+                },
+            ),
+            ("preprocessing", {"data_inspection", "format_conversion", "quality_control", "alignment", "normalization"}),
+            ("input_acquisition", {"database_search"}),
+        ]
+        for stage, stage_capabilities in priority_rules:
+            if any(capability in stage_capabilities for capability in capabilities):
+                return stage
+        for stage, stage_capabilities in self.STAGE_RULES:
+            if any(capability in stage_capabilities for capability in capabilities):
+                return stage
+        return "analysis"
+
+    def _infer_query_stages(self, query_context: dict, capabilities: list[str]) -> list[str]:
+        text = " ".join(query_context.get("subtasks", [])) + " " + query_context.get("rewritten_query", "")
+        lowered = text.lower()
+        stages = []
+        if any(token in lowered for token in ("inspect", "load", "schema", "preview", "normalize", "normalise")):
+            stages.append("preprocessing")
+        if any(
+            token in lowered
+            for token in (
+                "analyze",
+                "differential",
+                "compare",
+                "cluster",
+                "quantify",
+                "count",
+                "variant",
+                "taxonomy",
+            )
+        ):
+            stages.append("analysis")
+        if any(token in lowered for token in ("gsea", "enrichment", "pathway")):
+            stages.append("downstream")
+        if any(token in lowered for token in ("summarize", "report", "save plot", "visualize")):
+            stages.append("reporting")
+        if not stages:
+            for stage, stage_capabilities in self.STAGE_RULES:
+                if any(capability in stage_capabilities for capability in capabilities):
+                    stages.append(stage)
+        return stages

Biomanus_upload/biomni/graph/tool_graph.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+from biomni.graph.schema_extractor import ToolSchemaExtractor
+
+
+class ToolGraph:
+    """A lightweight heterogeneous graph over MCP servers, tools, capabilities, and data types."""
+
+    def __init__(self, schema_extractor: ToolSchemaExtractor | None = None):
+        self.schema_extractor = schema_extractor or ToolSchemaExtractor()
+        self.clear()
+
+    def clear(self) -> None:
+        self.nodes: dict[str, dict] = {}
+        self.edges: list[dict] = []
+        self.adjacency: dict[str, list[dict]] = defaultdict(list)
+        self.server_entries: dict[str, dict] = {}
+        self.server_index: dict[str, dict] = {}
+        self.tool_index: dict[str, dict] = {}
+        self.operation_index: dict[str, dict] = {}
+        self.datatype_to_operations: dict[str, list[str]] = defaultdict(list)
+
+    def add_node(self, node_id: str, node_type: str, label: str, **attributes) -> None:
+        payload = {"id": node_id, "type": node_type, "label": label}
+        payload.update(attributes)
+        self.nodes[node_id] = payload
+
+    def add_edge(self, source: str, target: str, edge_type: str, weight: float = 1.0, **attributes) -> None:
+        payload = {"source": source, "target": target, "type": edge_type, "weight": weight}
+        payload.update(attributes)
+        self.edges.append(payload)
+        self.adjacency[source].append(payload)
+
+    def build_from_server_entries(self, server_entries: list[dict]) -> None:
+        self.clear()
+        for entry in server_entries:
+            self._add_server(entry)
+        self._add_cross_server_workflow_edges()
+
+    def get_server_entry(self, server_name: str) -> dict | None:
+        return self.server_entries.get(server_name)
+
+    def get_server_names(self) -> list[str]:
+        return list(self.server_entries.keys())
+
+    def get_tool_nodes_for_server(self, server_name: str) -> list[dict]:
+        return self.server_index.get(server_name, {}).get("tools", [])
+
+    def get_server_semantics(self, server_name: str) -> dict:
+        return self.server_index.get(server_name, {}).get("semantics", {})
+
+    def get_server_neighbors(self, server_name: str, max_hops: int = 2) -> list[dict]:
+        start_node = f"server:{server_name}"
+        if start_node not in self.nodes:
+            return []
+        visited = {start_node}
+        frontier = {start_node}
+        collected = []
+        for _ in range(max_hops):
+            next_frontier = set()
+            for node_id in frontier:
+                for edge in self.adjacency.get(node_id, []):
+                    if edge["target"] in visited:
+                        continue
+                    visited.add(edge["target"])
+                    next_frontier.add(edge["target"])
+                    collected.append(self.nodes[edge["target"]])
+            frontier = next_frontier
+            if not frontier:
+                break
+        return collected
+
+    def _add_server(self, entry: dict) -> None:
+        server_name = entry["name"]
+        server_node = f"server:{server_name}"
+        semantics = self.schema_extractor.extract_server_semantics(entry)
+
+        self.add_node(
+            server_node,
+            "server",
+            server_name,
+            category=entry.get("category", "general"),
+            summary=entry.get("summary", ""),
+            keywords=semantics.get("keywords", []),
+        )
+        self.server_entries[server_name] = entry
+        self.server_index[server_name] = {"entry": entry, "semantics": semantics, "tools": []}
+
+        category = entry.get("category")
+        if category:
+            category_node = f"category:{category}"
+            self.add_node(category_node, "category", category)
+            self.add_edge(server_node, category_node, "categorized_as", weight=1.0)
+
+        for tool, tool_semantics in zip(entry.get("tools", []), semantics.get("tool_semantics", []), strict=False):
+            tool_name = tool_semantics["name"]
+            tool_node = f"tool:{server_name}:{tool_name}"
+            self.add_node(
+                tool_node,
+                "tool",
+                tool_name,
+                description=tool_semantics.get("description", ""),
+                keywords=tool_semantics.get("keywords", []),
+                module=entry.get("module"),
+            )
+            self.add_edge(server_node, tool_node, "hosts", weight=3.0)
+            self.server_index[server_name]["tools"].append({"node_id": tool_node, **tool, **tool_semantics})
+            self.tool_index[tool_node] = {"server_name": server_name, "tool": tool, "semantics": tool_semantics}
+
+            stage = tool_semantics.get("stage")
+            if stage:
+                stage_node = f"stage:{stage}"
+                self.add_node(stage_node, "stage", stage)
+                self.add_edge(tool_node, stage_node, "belongs_to_stage", weight=1.0)
+
+            for capability in tool_semantics.get("capabilities", []):
+                capability_node = f"capability:{capability}"
+                self.add_node(capability_node, "capability", capability)
+                self.add_edge(tool_node, capability_node, "implements", weight=2.0)
+
+            for operation in tool_semantics.get("operations", []):
+                self._add_operation_binding(operation, tool_node, tool_semantics)
+
+            for data_type in tool_semantics.get("consumes", []):
+                datatype_node = f"datatype:{data_type}"
+                self.add_node(datatype_node, "datatype", data_type)
+                self.add_edge(tool_node, datatype_node, "consumes", weight=2.0)
+
+            for data_type in tool_semantics.get("produces", []):
+                datatype_node = f"datatype:{data_type}"
+                self.add_node(datatype_node, "datatype", data_type)
+                self.add_edge(tool_node, datatype_node, "produces", weight=2.0)
+
+            for constraint in tool_semantics.get("constraints", []):
+                constraint_node = f"constraint:{constraint}"
+                self.add_node(constraint_node, "constraint", constraint)
+                self.add_edge(tool_node, constraint_node, "supports", weight=1.5)
+
+        self._add_workflow_edges(server_name)
+
+    def _add_operation_binding(self, operation: str, tool_node: str, tool_semantics: dict) -> None:
+        operation_node = f"operation:{operation}"
+        spec = self.schema_extractor.OPERATION_SPECS.get(operation, {})
+        accepts = spec.get("accepts", []) or tool_semantics.get("consumes", [])
+        produces = spec.get("produces", []) or tool_semantics.get("produces", [])
+        constraints = spec.get("constraints", []) or tool_semantics.get("constraints", [])
+
+        self.add_node(
+            operation_node,
+            "operation",
+            operation,
+            stage=spec.get("stage") or tool_semantics.get("stage"),
+            accepts=accepts,
+            produces=produces,
+            constraints=constraints,
+        )
+        self.add_edge(tool_node, operation_node, "implements_operation", weight=3.0)
+
+        entry = self.operation_index.setdefault(
+            operation,
+            {
+                "operation": operation,
+                "node_id": operation_node,
+                "accepts": [],
+                "produces": [],
+                "constraints": [],
+                "tools": [],
+                "stage": spec.get("stage") or tool_semantics.get("stage") or "analysis",
+            },
+        )
+        entry["accepts"] = self._merge_labels(entry["accepts"], accepts)
+        entry["produces"] = self._merge_labels(entry["produces"], produces)
+        entry["constraints"] = self._merge_labels(entry["constraints"], constraints)
+        entry["tools"].append({**tool_semantics, "node_id": tool_node})
+
+        for data_type in accepts:
+            datatype_node = f"datatype:{data_type}"
+            self.add_node(datatype_node, "datatype", data_type)
+            self.add_edge(operation_node, datatype_node, "accepts", weight=2.0)
+            if operation not in self.datatype_to_operations[data_type]:
+                self.datatype_to_operations[data_type].append(operation)
+
+        for data_type in produces:
+            datatype_node = f"datatype:{data_type}"
+            self.add_node(datatype_node, "datatype", data_type)
+            self.add_edge(operation_node, datatype_node, "produces", weight=2.0)
+
+        for constraint in constraints:
+            constraint_node = f"constraint:{constraint}"
+            self.add_node(constraint_node, "constraint", constraint)
+            self.add_edge(operation_node, constraint_node, "requires", weight=1.5)
+
+    def _merge_labels(self, primary: list[str], additions: list[str]) -> list[str]:
+        merged = list(primary or [])
+        for item in additions or []:
+            if item and item not in merged:
+                merged.append(item)
+        return merged
+
+    def _add_workflow_edges(self, server_name: str) -> None:
+        tools = self.server_index.get(server_name, {}).get("tools", [])
+        for source in tools:
+            source_produced = set(source.get("produces", []))
+            source_stage = source.get("stage")
+            for target in tools:
+                if source["name"] == target["name"]:
+                    continue
+                target_consumed = set(target.get("consumes", []))
+                if source_produced and target_consumed and source_produced & target_consumed:
+                    self.add_edge(
+                        source["node_id"],
+                        target["node_id"],
+                        "follows",
+                        weight=1.5,
+                        shared_datatypes=sorted(source_produced & target_consumed),
+                    )
+                elif source_stage and target.get("stage") and self._stage_distance(source_stage, target["stage"]) == 1:
+                    self.add_edge(
+                        source["node_id"],
+                        target["node_id"],
+                        "adjacent_stage",
+                        weight=0.5,
+                    )
+
+    def _add_cross_server_workflow_edges(self) -> None:
+        consume_index: dict[str, list[dict]] = defaultdict(list)
+        all_tools = []
+        for server_name in self.server_index:
+            for tool in self.server_index[server_name].get("tools", []):
+                all_tools.append(tool)
+                for data_type in tool.get("consumes", []):
+                    consume_index[data_type].append(tool)
+
+        generic_types = {"text", "image", "json", "csv"}
+        for source in all_tools:
+            produced_types = set(source.get("produces", [])) - generic_types
+            if not produced_types:
+                continue
+
+            candidates = []
+            for data_type in produced_types:
+                for target in consume_index.get(data_type, []):
+                    if source["node_id"] == target["node_id"]:
+                        continue
+                    if source["node_id"].split(":")[1] == target["node_id"].split(":")[1]:
+                        continue
+                    stage_delta = self._stage_distance(source.get("stage"), target.get("stage"))
+                    if stage_delta < 0 or stage_delta > 2:
+                        continue
+                    candidates.append((stage_delta, data_type, target))
+
+            candidates.sort(key=lambda item: (item[0], item[2].get("name", "")))
+            seen_targets = set()
+            for stage_delta, data_type, target in candidates[:12]:
+                if target["node_id"] in seen_targets:
+                    continue
+                seen_targets.add(target["node_id"])
+                self.add_edge(
+                    source["node_id"],
+                    target["node_id"],
+                    "typed_flow",
+                    weight=2.5 if stage_delta <= 1 else 1.5,
+                    shared_datatypes=[data_type],
+                    cross_server=True,
+                )
+
+    def _stage_distance(self, source_stage: str, target_stage: str) -> int:
+        order = ["input_acquisition", "preprocessing", "analysis", "downstream", "reporting"]
+        if source_stage not in order or target_stage not in order:
+            return 99
+        return order.index(target_stage) - order.index(source_stage)

Biomanus_upload/biomni/graph/workflow_priors.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class WorkflowPrior:
+    """A graph-structured workflow prior, not a task-specific pipeline.
+
+    Priors describe soft evidence that a query belongs near a region of the
+    heterogeneous tool graph. They provide semantic anchors and preferred
+    datatypes, while the final operation path is still selected dynamically by
+    graph search over typed-flow and stage-adjacency structure.
+    """
+
+    name: str
+    categories: frozenset[str] = frozenset()
+    capabilities: frozenset[str] = frozenset()
+    datatypes: frozenset[str] = frozenset()
+    keyword_hints: frozenset[str] = frozenset()
+    operation_hints: tuple[str, ...] = ()
+    input_types: tuple[str, ...] = ()
+    target_output: str = "report_table"
+    assay: str | None = None
+    min_score: float = 4.0
+    weight: float = 1.0
+
+    def score(
+        self,
+        *,
+        text: str,
+        categories: set[str],
+        capabilities: set[str],
+        datatypes: set[str],
+        operations: set[str],
+    ) -> float:
+        lowered = (text or "").lower()
+        score = 0.0
+        score += 4.0 * len(self.categories & categories)
+        score += 2.0 * len(self.capabilities & capabilities)
+        score += 1.5 * len(self.datatypes & datatypes)
+        score += 2.0 * len(set(self.operation_hints) & operations)
+        score += sum(1.0 for hint in self.keyword_hints if hint in lowered)
+        return score * self.weight
+
+
+WORKFLOW_PRIORS: tuple[WorkflowPrior, ...] = (
+    WorkflowPrior(
+        name="database_grounding",
+        categories=frozenset({"database_question_answering"}),
+        capabilities=frozenset({"database_search", "annotation"}),
+        keyword_hints=frozenset({"database", "clinvar", "ensembl", "uniprot", "disgenet", "omim", "mirdb", "gtrd"}),
+        operation_hints=("database_lookup",),
+        input_types=("text",),
+        target_output="database_record",
+    ),
+    WorkflowPrior(
+        name="sequence_feature_reasoning",
+        categories=frozenset({"sequence_question_answering"}),
+        capabilities=frozenset({"alignment", "annotation", "format_conversion"}),
+        datatypes=frozenset({"fastq", "reference_genome", "sequence_feature"}),
+        keyword_hints=frozenset({"sequence", "fasta", "motif", "primer", "binding site", "reverse complement"}),
+        operation_hints=("sequence_feature_extraction",),
+        input_types=("text",),
+        target_output="sequence_feature",
+    ),
+    WorkflowPrior(
+        name="bulk_expression_analysis",
+        capabilities=frozenset({"differential_expression", "normalization", "statistics", "read_counting"}),
+        datatypes=frozenset({"raw_count_matrix", "normalized_count_matrix", "sample_metadata", "differential_expression_table"}),
+        keyword_hints=frozenset({"rna-seq", "bulk", "count matrix", "raw counts", "deseq2", "log2fc", "padj"}),
+        operation_hints=("differential_expression",),
+        input_types=("raw_count_matrix", "sample_metadata"),
+        target_output="differential_expression_table",
+        assay="bulk_rna_seq",
+    ),
+    WorkflowPrior(
+        name="pathway_interpretation",
+        capabilities=frozenset({"pathway_enrichment", "database_search", "format_conversion"}),
+        datatypes=frozenset({"differential_expression_table", "gene_symbol_list", "entrez_gene_list", "kegg_enrichment_table"}),
+        keyword_hints=frozenset({"pathway", "kegg", "enrichment", "gsea", "reactome", "gene ontology"}),
+        operation_hints=("gene_filtering", "gene_id_conversion", "kegg_enrichment"),
+        input_types=("differential_expression_table",),
+        target_output="kegg_enrichment_table",
+    ),
+    WorkflowPrior(
+        name="comparative_result_synthesis",
+        capabilities=frozenset({"format_conversion", "statistics"}),
+        datatypes=frozenset({"kegg_enrichment_table", "merged_pathway_table", "csv"}),
+        keyword_hints=frozenset({"compare", "comparative", "shared", "across", "merge", "final table", "csv"}),
+        operation_hints=("pathway_merge", "csv_export"),
+        input_types=("kegg_enrichment_table",),
+        target_output="report_table",
+    ),
+    WorkflowPrior(
+        name="variant_interpretation",
+        capabilities=frozenset({"variant_calling", "variant_filtering", "annotation"}),
+        datatypes=frozenset({"vcf", "annotated_variant_table", "variant_summary"}),
+        keyword_hints=frozenset({"variant", "vcf", "mutation", "clinvar", "pathogenic"}),
+        operation_hints=("variant_annotation", "variant_summary"),
+        input_types=("vcf",),
+        target_output="variant_summary",
+    ),
+    WorkflowPrior(
+        name="single_cell_interpretation",
+        capabilities=frozenset({"single_cell_analysis", "annotation", "statistics"}),
+        datatypes=frozenset({"anndata", "marker_gene_table"}),
+        keyword_hints=frozenset({"single-cell", "singlecell", "scrna", "cluster", "cell type", "marker"}),
+        operation_hints=("single_cell_clustering", "marker_gene_detection"),
+        input_types=("anndata",),
+        target_output="marker_gene_table",
+    ),
+    WorkflowPrior(
+        name="taxonomic_profiling",
+        capabilities=frozenset({"taxonomic_classification"}),
+        datatypes=frozenset({"metagenomic_reads", "taxonomic_profile"}),
+        keyword_hints=frozenset({"metagenomic", "metagenomics", "taxonomy", "taxonomic", "kraken", "metaphlan"}),
+        operation_hints=("taxonomic_classification",),
+        input_types=("metagenomic_reads",),
+        target_output="taxonomic_profile",
+    ),
+)
+
+
+def rank_workflow_priors(
+    priors: Iterable[WorkflowPrior],
+    *,
+    text: str,
+    categories: set[str],
+    capabilities: set[str],
+    datatypes: set[str],
+    operations: set[str],
+) -> list[tuple[WorkflowPrior, float]]:
+    ranked = []
+    for prior in priors:
+        score = prior.score(
+            text=text,
+            categories=categories,
+            capabilities=capabilities,
+            datatypes=datatypes,
+            operations=operations,
+        )
+        if score >= prior.min_score:
+            ranked.append((prior, score))
+    ranked.sort(key=lambda item: (-item[1], item[0].name))
+    return ranked

Biomanus_upload/biomni/know_how/__init__.py

@@ -0,0 +1,9 @@
+"""Know-How library for Biomni agent.
+
+This module provides functionality to load and manage know-how documents
+that contain best practices, protocols, and troubleshooting guides.
+"""
+
+from .loader import KnowHowLoader
+
+__all__ = ["KnowHowLoader"]

Biomanus_upload/biomni/know_how/loader.py

@@ -0,0 +1,348 @@
+"""Loader for know-how documents."""
+
+import glob
+import os
+from pathlib import Path
+
+
+class KnowHowLoader:
+    """Load and manage know-how documents for the agent."""
+
+    def __init__(self, know_how_dir: str | None = None):
+        """Initialize the know-how loader.
+
+        Args:
+            know_how_dir: Directory containing know-how documents.
+                         If None, uses the default know_how directory.
+
+        """
+        if know_how_dir is None:
+            # Default to the know_how directory in the package
+            current_dir = Path(__file__).parent
+            know_how_dir = str(current_dir)
+
+        self.know_how_dir = know_how_dir
+        self.documents = {}
+        self._load_documents()
+
+    def _load_documents(self):
+        """Load all markdown documents from the know-how directory."""
+        pattern = os.path.join(self.know_how_dir, "*.md")
+        md_files = glob.glob(pattern)
+
+        for filepath in md_files:
+            filename = os.path.basename(filepath)
+            filename_without_ext = os.path.splitext(filename)[0]
+
+            # Skip README, QUICK_START, and other meta documentation (all caps filenames)
+            if filename.upper() in ["README.MD", "QUICK_START.MD"] or filename_without_ext.isupper():
+                continue
+
+            # Read the document
+            with open(filepath) as f:
+                content = f.read()
+
+            # Extract title, description, and metadata from the document
+            title, description, metadata = self._extract_metadata(content, filename)
+
+            # Use short_description from metadata if available, otherwise fall back to extracted description
+            if "short_description" in metadata and metadata["short_description"]:
+                description = metadata["short_description"]
+
+            # Store document info
+            doc_id = os.path.splitext(filename)[0]
+            self.documents[doc_id] = {
+                "id": doc_id,
+                "name": title,
+                "description": description,
+                "content": content,
+                "content_without_metadata": self._strip_metadata(content),
+                "filepath": filepath,
+                "metadata": metadata,
+            }
+
+    def _extract_metadata(self, content: str, filename: str) -> tuple[str, str, dict]:
+        """Extract title, description, and metadata from markdown content.
+
+        Args:
+            content: Markdown content
+            filename: Filename (used as fallback for title)
+
+        Returns:
+            Tuple of (title, description, metadata_dict)
+
+        """
+        lines = content.split("\n")
+
+        # Extract title (first h1)
+        title = None
+        for line in lines:
+            if line.startswith("# "):
+                title = line[2:].strip()
+                break
+
+        if title is None:
+            # Fallback to filename
+            title = filename.replace("_", " ").replace(".md", "").title()
+
+        # Extract metadata section
+        metadata = {}
+        in_metadata = False
+        current_field = None
+
+        for _i, line in enumerate(lines):
+            if line.startswith("## Metadata"):
+                in_metadata = True
+                continue
+            elif in_metadata:
+                if line.startswith("##") and "Metadata" not in line:
+                    # End of metadata section
+                    break
+                elif line.startswith("**") and "**:" in line:
+                    # New metadata field (e.g., **Authors**:)
+                    field_match = line.split("**")[1]
+                    current_field = field_match.lower().replace(" ", "_")
+                    # Get the value after the colon if it exists on the same line
+                    colon_idx = line.find("**:")
+                    if colon_idx != -1:
+                        value_part = line[colon_idx + 3 :].strip()
+                        if value_part:
+                            metadata[current_field] = value_part
+                        else:
+                            metadata[current_field] = ""
+                elif current_field and line.strip() and not line.startswith("---"):
+                    # Continuation of current field
+                    if current_field not in metadata:
+                        metadata[current_field] = ""
+                    if line.startswith("- "):
+                        # List item
+                        if metadata[current_field]:
+                            metadata[current_field] += ", " + line[2:].strip()
+                        else:
+                            metadata[current_field] = line[2:].strip()
+                    elif not line.startswith("```"):
+                        # Regular text
+                        if metadata[current_field]:
+                            metadata[current_field] += " " + line.strip()
+                        else:
+                            metadata[current_field] = line.strip()
+
+        # Extract description (content under ## Overview or first paragraph)
+        description = ""
+        in_overview = False
+        overview_lines = []
+
+        for _i, line in enumerate(lines):
+            if line.startswith("## Overview"):
+                in_overview = True
+                continue
+            elif in_overview:
+                if line.startswith("##"):
+                    # End of overview section
+                    break
+                elif line.strip():
+                    overview_lines.append(line.strip())
+
+        if overview_lines:
+            description = " ".join(overview_lines)
+        else:
+            # Fallback: get first non-empty paragraph after title
+            found_title = False
+            for line in lines:
+                if line.startswith("# "):
+                    found_title = True
+                    continue
+                if found_title and line.strip() and not line.startswith("#"):
+                    description = line.strip()
+                    break
+
+        # Limit description length
+        if len(description) > 200:
+            description = description[:197] + "..."
+
+        return title, description, metadata
+
+    def _strip_metadata(self, content: str) -> str:
+        """Strip the metadata section from document content.
+
+        Args:
+            content: Full document content with metadata
+
+        Returns:
+            Content without metadata section
+
+        """
+        lines = content.split("\n")
+        result_lines = []
+        in_metadata = False
+        skip_until_separator = False
+        found_first_h1 = False
+
+        for line in lines:
+            # Track first H1 (title)
+            if line.startswith("# ") and not found_first_h1:
+                result_lines.append(line)
+                found_first_h1 = True
+                continue
+
+            # Detect metadata section start
+            if line.startswith("## Metadata"):
+                in_metadata = True
+                continue
+
+            # Skip separator lines before and after metadata
+            if line.strip() == "---":
+                if not in_metadata:
+                    # This might be the separator before metadata
+                    skip_until_separator = True
+                    continue
+                else:
+                    # This is the separator after metadata
+                    in_metadata = False
+                    skip_until_separator = False
+                    continue
+
+            # Skip lines in metadata section
+            if in_metadata or skip_until_separator:
+                # Check if we hit another H2 (end of metadata)
+                if line.startswith("##") and "Metadata" not in line:
+                    in_metadata = False
+                    skip_until_separator = False
+                    result_lines.append(line)
+                continue
+
+            # Keep all other lines
+            result_lines.append(line)
+
+        # Join and clean up extra blank lines
+        result = "\n".join(result_lines)
+
+        # Remove excessive blank lines (more than 2 consecutive)
+        while "\n\n\n\n" in result:
+            result = result.replace("\n\n\n\n", "\n\n\n")
+
+        return result.strip()
+
+    def get_all_documents(self) -> list[dict]:
+        """Get all know-how documents as a list.
+
+        Returns:
+            List of document dictionaries with keys: id, name, description, content
+
+        """
+        return list(self.documents.values())
+
+    def get_document_by_id(self, doc_id: str) -> dict | None:
+        """Get a specific know-how document by ID.
+
+        Args:
+            doc_id: Document identifier
+
+        Returns:
+            Document dictionary or None if not found
+
+        """
+        return self.documents.get(doc_id)
+
+    def get_document_summaries(self) -> list[dict]:
+        """Get summaries of all documents (without full content).
+
+        Returns:
+            List of document summaries with keys: id, name, description
+
+        """
+        return [
+            {"id": doc["id"], "name": doc["name"], "description": doc["description"]} for doc in self.documents.values()
+        ]
+
+    def add_custom_document(self, doc_id: str, name: str, description: str, content: str, metadata: dict | None = None):
+        """Add a custom know-how document programmatically.
+
+        Args:
+            doc_id: Unique identifier for the document
+            name: Document title
+            description: Brief description
+            content: Full document content
+            metadata: Optional metadata dictionary (authors, license, etc.)
+
+        """
+        if metadata is None:
+            metadata = {}
+
+        self.documents[doc_id] = {
+            "id": doc_id,
+            "name": name,
+            "description": description,
+            "content": content,
+            "filepath": None,
+            "metadata": metadata,
+        }
+
+    def get_document_metadata(self, doc_id: str) -> dict | None:
+        """Get metadata for a specific document.
+
+        Args:
+            doc_id: Document identifier
+
+        Returns:
+            Metadata dictionary or None if not found
+
+        """
+        doc = self.documents.get(doc_id)
+        return doc.get("metadata", {}) if doc else None
+
+    def print_document_info(self, doc_id: str):
+        """Print formatted information about a document including metadata.
+
+        Args:
+            doc_id: Document identifier
+
+        """
+        doc = self.documents.get(doc_id)
+        if not doc:
+            print(f"Document '{doc_id}' not found")
+            return
+
+        print("=" * 70)
+        print(f"📚 {doc['name']}")
+        print("=" * 70)
+        print(f"\nDescription: {doc['description']}")
+
+        metadata = doc.get("metadata", {})
+        if metadata:
+            print("\n" + "-" * 70)
+            print("METADATA")
+            print("-" * 70)
+
+            # Display key metadata fields
+            if "authors" in metadata:
+                print(f"Authors: {metadata['authors']}")
+            if "affiliations" in metadata:
+                print(f"Affiliations: {metadata['affiliations']}")
+            if "version" in metadata:
+                print(f"Version: {metadata['version']}")
+            if "last_updated" in metadata:
+                print(f"Last Updated: {metadata['last_updated']}")
+            if "license" in metadata:
+                print(f"License: {metadata['license']}")
+            if "commercial_use" in metadata:
+                print(f"Commercial Use: {metadata['commercial_use']}")
+            if "status" in metadata:
+                print(f"Status: {metadata['status']}")
+
+        print("=" * 70)
+
+    def remove_document(self, doc_id: str):
+        """Remove a know-how document.
+
+        Args:
+            doc_id: Document identifier
+
+        """
+        if doc_id in self.documents:
+            del self.documents[doc_id]
+
+    def reload(self):
+        """Reload all documents from disk."""
+        self.documents = {}
+        self._load_documents()

Biomanus_upload/biomni/know_how/resource/CRISPick_download_links.txt

@@ -0,0 +1,238 @@
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8030_ICSASG_v2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230421.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8030_ICSASG_v2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230421.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8030_ICSASG_v2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230421.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8030_ICSASG_v2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230421.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20241114.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20241114.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20241114.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20241114.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20241114.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20241114.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20241114.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20241114.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241114.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10029_CHOK1GS_HDv1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241114.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_74940_Otsh_v1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230424.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_74940_Otsh_v1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230424.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_74940_Otsh_v1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230424.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_74940_Otsh_v1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230424.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9913_ARS-UCD1.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230418.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9913_ARS-UCD1.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230418.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9913_ARS-UCD1.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230418.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9913_ARS-UCD1.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230418.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_CanFam3.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220923.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_CanFam3.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220923.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_CanFam3.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220923.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_CanFam3.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220923.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20241031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20241031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20241031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20241031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20251031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20251031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241031.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241031.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240611.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9615_ROS_Cfam_1.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240611.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_7227_BDGP6.32_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20230407.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_7227_BDGP6.32_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20230407.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_7227_BDGP6.32_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20230407.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_7227_BDGP6.32_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20230407.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_59479_mRhiFer1_v1.p_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230427.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_59479_mRhiFer1_v1.p_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230427.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_59479_mRhiFer1_v1.p_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230427.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_59479_mRhiFer1_v1.p_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230427.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220914.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_60711_Chlorocebus_sabeus_1.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220914.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20241107.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20241107.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20241107.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20241107.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20241107.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20241107.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20241107.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20241107.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241107.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh37_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241107.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20250806.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20250806.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRi_RS3i-Chen2013_NCBI_20250718.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRi_RS3i-Chen2013_NCBI_20250718.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241104.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241104.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241028.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241028.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRa_Azimuth_2.0_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRa_Azimuth_2.0_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRi_Azimuth_2.0_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SaurCas9_CRISPRko_Azimuth_2.0_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRi_RS3i-Chen2013_NCBI_20250807.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRi_RS3i-Chen2013_NCBI_20250807.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20250724.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRi_RS3i-Chen2013_Ensembl_20250724.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240614.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240614.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20230403.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10090_GRCm38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20230403.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8022_USDA_OmykA_1.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230419.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8022_USDA_OmykA_1.1_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20230419.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8022_USDA_OmykA_1.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230419.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_8022_USDA_OmykA_1.1_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20230419.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRa_Seq-DeepCpf1_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRa_Seq-DeepCpf1_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRi_Seq-DeepCpf1_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRi_Seq-DeepCpf1_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRko_Seq-DeepCpf1_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_AsCas12a_CRISPRko_Seq-DeepCpf1_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRa_enPAM+GB_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRa_enPAM+GB_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRi_enPAM+GB_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRi_enPAM+GB_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRko_enPAM+GB_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_enAsCas12a_CRISPRko_enPAM+GB_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241112.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_Ensembl_20241112.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240131.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_mRatBN7.2_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20240131.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20220907.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SaurCas9_CRISPRi_Azimuth_2.0_NCBI_20220907.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20220907.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SaurCas9_CRISPRko_Azimuth_2.0_NCBI_20220907.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220907.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20220907.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220907.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_10116_Rnor_6.0_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20220907.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9544_Mmul_10_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20241025.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9544_Mmul_10_SpyoCas9_CRISPRa_RS3seq-Chen2013_NCBI_20241025.summary.txt
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9544_Mmul_10_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241025.txt.gz
+https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/sgRNA_design_9544_Mmul_10_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241025.summary.txt

Biomanus_upload/biomni/know_how/resource/addgene_grna_sequences.csv

@@ -0,0 +1,322 @@
+Application,Cas9 Species,Depositor,Plasmid ID,PubMed ID,Target Gene,Target Sequence,Target Species
+cut,S. pyogenes,Goncalves,"<a href=""/58252/"">58252</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24870050/"">24870050</a>",AAVS1,GGGGCCACTAGGGACAGGAT,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/41818/"">41818</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",AAVS1,GGGGCCACTAGGGACAGGAT,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/50662/"">50662</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336569/"">24336569</a>",AAVS1,GGGGCCACTAGGGACAGGAT,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70661/"">70661</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",AAVS1,GGGGCCACTAGGGACAGGAT,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/41817/"">41817</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",AAVS1,GTCCCCTCCACCCCACAGTG,H. sapiens
+cut,S. pyogenes,Kanemaki,"<a href=""/72833/"">72833</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27052166/"">27052166</a>",AAVS1,GGGGCCACTAGGGACAGGAT,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",AAVS1,TGTCCCTAGTGGCCCCACTG,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",AAVS1,ACAGTGGGGCCACTAGGGAC,H. sapiens
+RNA targeting,S. pyogenes,Yeo,"<a href=""/74705/"">74705</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26997482/"">26997482</a>",ACTB,UGGAGCGAGCAUCCCCCAAA,H. sapiens
+cut,S. pyogenes,Jiang,"<a href=""/62552/"">62552</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25739462/"">25739462</a>",actII-orf4,ATTACCAGGGACCGGAGTTC,S. coelicolor
+cut,S. pyogenes,Zaratiegui,"<a href=""/52225/"">52225</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25352017/"">25352017</a>",ade6+,TCTATTGTTCAGATGCCTCG,S. pombe
+cut,S. pyogenes,Zaratiegui,"<a href=""/52227/"">52227</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25352017/"">25352017</a>",ade6-L469,TCTATTGTTCAGATGCCTTG,S. pombe
+cut,S. pyogenes,Zaratiegui,"<a href=""/52226/"">52226</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25352017/"">25352017</a>",ade6-M210,TCTATTGTTCAGATGCTTCG,S. pombe
+cut,S. pyogenes,Ventura,"<a href=""/64071/"">64071</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25337876/"">25337876</a>",Alk and Eml,,M. musculus
+nick,S. pyogenes,Shaw,"<a href=""/74374/"">74374</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26816379/"">26816379</a>",AMPK alpha 1,GGCTGTCGCCATCTTTCTCC,H. sapiens
+nick,S. pyogenes,Shaw,"<a href=""/74375/"">74375</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26816379/"">26816379</a>",AMPK alpha 1,GAAGATCGGCCACTACATTC,H. sapiens
+nick,S. pyogenes,Shaw,"<a href=""/74376/"">74376</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26816379/"">26816379</a>",AMPK alpha 2,GTCAGCCATCTTCGGCGCGCG,H. sapiens
+nick,S. pyogenes,Shaw,"<a href=""/74377/"">74377</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26816379/"">26816379</a>",AMPK alpha 2,GAAGATCGGACACTACGTGC,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70660/"">70660</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>","Amplicon, JAK2",GAGGCATATTCTTCTCCTGG,H. sapiens
+cut,S. pyogenes,Voytas,"<a href=""/70019/"">70019</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26541286/"">26541286</a>",ANT1,TGTCGTTTATAATTTGTAGA,S. lycopersicum
+cut,S. pyogenes,Voytas,"<a href=""/70018/"">70018</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26541286/"">26541286</a>",ANT1,ACAATTTAATACACCTTTT,S. lycopersicum
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",AOC,CAAAAGACTGTCAATTCCCT,N. attenuata
+cut/nick,S. pyogenes,Yamamoto,"<a href=""/58780/"">58780</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",APC,GAAGCGGGCAAAGGGGCGAC,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/42241/"">42241</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",apoea,GGATGAGCCAAGAAGCCGCT,D. rerio
+activate,S. pyogenes,Sato,"<a href=""/64131/"">64131</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",ASCL1,TGGATGGAGAGTTTGCAAGGAGC,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64130/"">64130</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",ASCL1,TGGGCAGCCGCTCGCTGCAGCAG,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64129/"">64129</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",ASCL1,TGGGGCTGGGTGTCCCATTGAAA,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64132/"">64132</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",ASCL1,TGGTGTTTATTCAGCCGGGAGTC,H. sapiens
+cut,S. pyogenes,Mashimo,"<a href=""/60968/"">60968</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Asip,ATGACAGGAGTCTAACTCAC,R. norvegicus
+tag,S. pyogenes,Mendenhall,"<a href=""/64690/"">64690</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",ATF1,TAGGAATCAAACACTTTTATTGG,H. sapiens
+cut,S. pyogenes,Yamamoto,"<a href=""/58779/"">58779</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",ATM,TGAATTGGGATGCTGTTTTT,H. sapiens
+cut,S. pyogenes,Mello,"<a href=""/58981/"">58981</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24879462/"">24879462</a>",avr-14,GATTGGAGAGTTAGACCACG,C. elegans
+cut,S. pyogenes,Mello,"<a href=""/58982/"">58982</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24879462/"">24879462</a>",avr-15,GTTTGCAATATAAGTCACCC,C. elegans
+cut,S. pyogenes,Yamamoto,"<a href=""/58782/"">58782</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",AXIN2,TATGTTGGTGACTTGCCTCC,H. sapiens
+methylation,S. pyogenes,Zoldoš,"<a href=""/71828/"">71828</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26969735/"">26969735</a>",BACH2,AATGTAGCGATTGAGAGTGTGGG,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70658/"">70658</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",BCR/ABL amplicon,GGCTCCCTTCAAGTGGGATG,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",BFP,ATGGCGTGCAGTGCTTCAGC,
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",BIN2,ATCACAGTGATGCTCGTCAA,L. sativa
+cut,S. pyogenes,Hanna,"<a href=""/59724/"">59724</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25543152/"">25543152</a>",BLIMP1,CGGATGGGGTAAACGACCCG,H. sapiens
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",BRI1,TTTGAAAGATGGAAGCGCGG,A. thaliana
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",BRI1,TGAAACTAAACTGGTCCACA,A. thaliana
+interfere,S. pyogenes,Lu,"<a href=""/68892/"">68892</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",BT1754,GAAAATGGGGTGTATCCTGC,B. thetaiotaomicron
+interfere,S. pyogenes,Lu,"<a href=""/68891/"">68891</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",BT1854,ATTGAAGAACAAAAGCAGTT,B. thetaiotaomicron
+cut,S. pyogenes,Sabatini,"<a href=""/70650/"">70650</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C16orf80,CGATGCTGTAGAGGATGGAG,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70651/"">70651</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C16orf80,TGTCTGAGAAGTAAACCCGT,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70653/"">70653</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C3orf17,GGGCCAAATGGGGTTTGTGG,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70652/"">70652</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C3orf17,GTGTGAGAATCCCTAAGGCG,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70654/"">70654</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C9orf114,CAGGCGGGCTCACCTCCGTG,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70655/"">70655</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",C9orf114,GCGGCAGAGAAGGAGGACCG,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/43803/"">43803</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23460208/"">23460208</a>",CAN1,GATACGTTCTCTATGGAGGA,S. cerevisiae
+cut,S. pyogenes,Bornhauser,"<a href=""/75164/"">75164</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27194728/"">27194728</a>",Caspase-8,GCCTGGACTACATTCCGCAA,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",CCR5,TGACATCAATTATTATACAT,H. sapiens
+interfere,S. pyogenes,Qi,"<a href=""/46918/"">46918</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",CD71,GGACGCGCTAGTGTGAGTGC,H. sapiens
+cut,S. pyogenes,Yamamoto,"<a href=""/58781/"">58781</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",CDH1,TGACTTGCGAGGGACGCATT,H. sapiens
+activate,S. pyogenes,Vale,"<a href=""/60905/"">60905</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25307933/"">25307933</a>",CDKN1B,GAAGCCGGGACCTGGACCAG,H. sapiens
+tag,S. pyogenes,Mendenhall,"<a href=""/64036/"">64036</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",CEBPB,CTCCGGCCACTGCTAGCGCGG,H. sapiens
+tag,S. pyogenes,Mendenhall,"<a href=""/64047/"">64047</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",CEBPB,GCCGGCAGGGGGACGCGCGCGG,H. sapiens
+cut,S. pyogenes,Ikawa,"<a href=""/50718/"">50718</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24284873/"">24284873</a>",Cent1,GGCAACGTTTGACTTCCTGA,M. musculus
+cut,S. pyogenes,Yamamoto,"<a href=""/58783/"">58783</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",CFTR,TCTGTATCTATATTCATCAT,H. sapiens
+tag,S. pyogenes,Mendenhall,"<a href=""/64940/"">64940</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",CREB1,GCCACAAATCAGATTAATTTGG,H. sapiens
+tag,S. pyogenes,Mendenhall,"<a href=""/64939/"">64939</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",CREB1,GCCACAAATCAGATTAATTTGGG,H. sapiens
+cut,S. pyogenes,Hong,"<a href=""/68060/"">68060</a>","<a href=""http://fungalbiolbiotech.biomedcentral.com/articles/10.1186/s40694-015-0015-1"">Fungal Biology and Biotechnology 2015, 2:4</a>",csr-1,GAGTGGGAGGGTCCCGTCCT,N. crassa
+cut,S. pyogenes,Jacks,"<a href=""/59912/"">59912</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25119044/"">25119044</a>",Ctnnb1,AGCTCCTTCCCTGAGTGGCA,M. musculus
+cut,S. pyogenes,Jacks,"<a href=""/59911/"">59911</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25119044/"">25119044</a>",Ctnnb1,CTGTGGTGGTGGCACCAGAA,M. musculus
+interfere,S. pyogenes,Qi,"<a href=""/46917/"">46917</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",CXCR4,GCAGGTAGCAAAGTGACGCCGA,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",CXCR4,CCTCTTTGTCATCACGCTTC,H. sapiens
+activate,S. pyogenes,Lu,"<a href=""/64385/"">64385</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,ACAGAGCACATGCATGCCAT,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64387/"">64387</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,ACTAATACTTTCAACATTTT,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64382/"">64382</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,ATATCGAATTCCTGCAGCCC,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64380/"">64380</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,ATATTCTTTCCTTATACATT,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64379/"">64379</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,CTAGATATTAAAATGTCTAA,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64388/"">64388</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,GTTGAAAGTATTAGTTAAAG,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64381/"">64381</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,TACATACAGTAGGATCCTA,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64383/"">64383</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,TATAGTAATTTATGCTGCAA,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64384/"">64384</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,TGCAAAGGTCCTAATGTATA,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64386/"">64386</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,TGTATGTACATACAGTACCC,S. cerevisiae
+activate,S. pyogenes,Lu,"<a href=""/64378/"">64378</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23977949/"">23977949</a>",CYC1m promoter,TTACTGTATGTACATACAGT,S. cerevisiae
+cut,S. pyogenes,Wente,"<a href=""/47932/"">47932</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23918387/"">23918387</a>",ddx19,GGCAACAGATTCGTGGGCCC,D. rerio
+cut,S. pyogenes,Sabatini,"<a href=""/70656/"">70656</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",DDX3Y,GCAGTTTAGCGATATTGACA,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70657/"">70657</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",DDX3Y,TCTTGTTGGGGCTAAAACCA,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/41822/"">41822</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",DNMT3A,GAGATGATCGCCCCTTCTTC,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/41821/"">41821</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",DNMT3A,GCATGATGCGCGGCCCAAGG,H. sapiens
+cut,S. pyogenes,Church,"<a href=""/41823/"">41823</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",DNMT3B,GAATTACTCACGCCCCAAGG,H. sapiens
+cut,VRER Cas9 mutant,Fire,"<a href=""/71516/"">71516</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26680661/"">26680661</a>",dpy-10,CGCTACCATAGGCACCACG,C. elegans
+cut,S. pyogenes,Katic,"<a href=""/65630/"">65630</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26044730/"">26044730</a>",dpy-10,GCTACCATAGGCACCACGAG,C.elegans
+cut,S. pyogenes,Fire,"<a href=""/59933/"">59933</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",dpy-10,GCTACCATAGGCACCACGAG,C. elegans
+cut,VQR Cas9 variant,Fire,"<a href=""/71479/"">71479</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26680661/"">26680661</a>",dpy-10,TCCGCTACCATAGGCACCA,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/70047/"">70047</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26187122/"">26187122</a>",dpy‐10,GCTACCATAGGCACCACGAG,C. elegans
+cut,S. pyogenes,Joung,"<a href=""/42242/"">42242</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",drd3,GGAAACTACAGCCCAGCGTC,D. rerio
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",DWD1,TGCATCGTCCAAGCGCACAG,O. sativa
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",DWD1,CTACGACGTCAGGTTCTACC,O. sativa
+cut,S. pyogenes,Christiaen,"<a href=""/59990/"">59990</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25336740/"">25336740</a>",Ebf,GCTGAGGGTTGGACAACAGG,C. intestinalis
+dCas9-FokI,S. pyogenes,Joung,"<a href=""/60071/"">60071</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24770325/"">24770325</a>",EGFP,"multiple, see article",A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51764/"">51764</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GAAGTTCGAGGGCGACACCC,A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51761/"">51761</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GAGCTGGACGGCGACGTAAA,A. victoria
+cut,S. pyogenes,Joung,"<a href=""/47512/"">47512</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",EGFP,GATGCCGTTCTTCTGCTTGT,A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51763/"">51763</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GGAGCGCACCATCTTCTTCA,A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51762/"">51762</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GGCCACAAGTTCAGCGTGTC,A. victoria
+cut,S. pyogenes,Del Bene,"<a href=""/61051/"">61051</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24179142/"">24179142</a>",EGFP,GGCGAGGGCGATGCCACCTA,A. victoria
+cut,S. pyogenes,Chen,"<a href=""/46760/"">46760</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23918387/"">23918387</a>",EGFP,GGGCACGGGCAGCTTGCCGG,A. victoria
+cut,S. pyogenes,Joung,"<a href=""/47511/"">47511</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",EGFP,GGGCACGGGCAGCTTGCCGG,A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51760/"">51760</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GGGCGAGGAGCTGTTCACCG,A. victoria
+cut,S. pyogenes,Zhang,"<a href=""/51765/"">51765</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24336571/"">24336571</a>",EGFP,GGTGAACCGCATCGAGCTGA,A. victoria
+cut,S. pyogenes,Joung,"<a href=""/47513/"">47513</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",EGFP,GGTGGTGCAGATGAACTTCA,A. victoria
+cut,S. pyogenes,Goncalves,"<a href=""/58255/"">58255</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24870050/"">24870050</a>",EGFP,TGAAGAAGATGGTGCGCTC,A. victoria
+cut,S. pyogenes,Moffat,"<a href=""/74187/"">74187</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",EIF3D,TGTAGGTTGCCTCCATGGCC,H. sapiens
+cut,S. pyogenes,Moffat,"<a href=""/74188/"">74188</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",EIF3D,AGACGACCCTGTCATCCGCA,H. sapiens
+cut,S. pyogenes,Zhang,"<a href=""/42337/"">42337</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287718/"">23287718</a>",Emx1,,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47508/"">47508</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",EMX1,GAGTCCGAGCAGAAGAAGAA,H. sapiens
+cut,S. pyogenes,Corn,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26789497/"">26789497</a>",EMX1,CGATGTCACCTCCAATGACT,H. sapiens
+cut,S. pyogenes,Chen,"<a href=""/71288/"">71288</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26193878/"">26193878</a>","ETC2, TRY, and CPC",,A. thaliana
+cut,S. pyogenes,Bornhauser,"<a href=""/75166/"">75166</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27194728/"">27194728</a>",FADD,ACTCCCGCACACGCTCTGTC,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47510/"">47510</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",FANCF,GGAATCCCTTCTGCAGCACC,H. sapiens
+cut,S. pyogenes,Seydoux,"<a href=""/65597/"">65597</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",fbf-2,GTAGTCACGGCGATGATTA,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/65591/"">65591</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",fbf-2,TAATCATCGCCGTGACTAC,C. elegans
+cut,S. pyogenes,Joung,"<a href=""/42244/"">42244</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",fh,GGAGCGAGCGGAGCGGTACA,D. rerio
+cut,S. pyogenes,Joung,"<a href=""/42243/"">42243</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",fh,GGAGCGGTACATGGCGACCG,D. rerio
+tag,S. pyogenes,Mendenhall,"<a href=""/64254/"">64254</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",GABPA,GAAAAGGATAATTGAGCCCCAGG,H. sapiens
+tag,S. pyogenes,Mendenhall,"<a href=""/64255/"">64255</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",GABPA,TTTGGAGTCTCAGAATGTCCTGG,H. sapiens
+activate,S. pyogenes,Qi,"<a href=""/46916/"">46916</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",GAL4 UAS,GAACGACTAGTTAGGCGTGTA,
+activate,S. pyogenes,Qi,"<a href=""/46915/"">46915</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",GAL4 UAS,GTTGGAGCACTGTCCTCCGAACGT,
+activate,S. pyogenes,Sato,"<a href=""/64158/"">64158</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",GAL4UAS,TGGGGACAGTACTCCGCTCGAGT,
+activate,S. pyogenes,Sato,"<a href=""/64157/"">64157</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",GAL4UAS,TGGGTCTTCGGAGGACAGTACTC,
+activate,S. pyogenes,Sato,"<a href=""/64159/"">64159</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",GAL4UAS,TGGTCCGTCTAGAAACTCGGTAC,
+cut,S. pyogenes,Du,"<a href=""/65566/"">65566</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25849248/"">25849248</a>",gfap,GTGCGCAACACATAGCACCA,D. rerio
+interfere,S. pyogenes,Qi,"<a href=""/46914/"">46914</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",GFP,GAATAGCTCAGAGGCCGAGG,A. victoria
+cut,S. pyogenes,Church,"<a href=""/41820/"">41820</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",GFP,GGAGCGCACCATCTTCTTCA,A. victoria
+cut,S. pyogenes,Church,"<a href=""/41819/"">41819</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23287722/"">23287722</a>",GFP,GTGAACCGCATCGAGCTGAA,A. victoria
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72619/"">72619</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",GFP,gRNA1: GAGCTGGACGGCGACGTAAA; gRNA2: CAGAACACCCCCATCGGCGA,Synthetic
+interfere,S. pyogenes,Hudson,"<a href=""/73221/"">73221</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26689101/"">26689101</a>",GFPmut3b,ACCATCTAATTCAACAAGAATT,A. victoria
+interfere,S. pyogenes,Hudson,"<a href=""/73224/"">73224</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26689101/"">26689101</a>",GFPmut3b,ACCATCTAATTCAACAAGAATT,synthetic
+CRISPR-display,S. pyogenes,Rinn,"<a href=""/68422/"">68422</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26030444/"">26030444</a>",GLuc,GATCTAGATACGACTCACTAT,synthetic
+cut,S. pyogenes,Ye,"<a href=""/61833/"">61833</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24424410/"">24424410</a>",gp78,GCCCAGCCTCCGCACCTACA,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/42245/"">42245</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",gsk3b,GGGACCTGACCGGCCGCAGG,D. rerio
+cut,S. pyogenes,Jin,"<a href=""/64333/"">64333</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25281382/"">25281382</a>",his3,ATTGCGATCTCTTTAAAGGG,S. cerevisiae
+cut,S. pyogenes,Yan,"<a href=""/69539/"">69539</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26130722/"">26130722</a>",HPRT,GACTGTAAGTGAATTACTT,H. sapiens
+cut,S. pyogenes,Yamamoto,"<a href=""/58778/"">58778</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",HPRT1,CTGATAAAATCTACAGTCAT,H. sapiens
+cut,S. pyogenes,Yamamoto,"<a href=""/58771/"">58771</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24954249/"">24954249</a>",HPRT1,TTATGCTGAGGATTTGGAAA,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64142/"">64142</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",IL1RN,TGGACGCAGATAAGAACCAGTT,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64151/"">64151</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",IL1RN,TGGCATCAAGTCAGCCATCAGC,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64152/"">64152</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",IL1RN,TGGGAGTCACCCTCCTGGAAAC,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64140/"">64140</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",IL1RN,TGGTGTACTCTCTGAGGTGCTC,H. sapiens
+cut,S. pyogenes,Xue,"<a href=""/66582/"">66582</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",inverted GFP,GAGCGGCCGCTCGAGTCTAG,A. victoria
+cut,S. pyogenes,Xue,"<a href=""/66583/"">66583</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",inverted GFP,GATATCGAATTCCTGCAGCC,A. victoria
+cut,S. pyogenes,Xue,"<a href=""/66581/"">66581</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",inverted GFP,GTATCGATACCGTCGACCTCG,A. victoria
+cut,S. pyogenes,Xue,"<a href=""/66584/"">66584</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",inverted GFP,GTTGATCCATAACTTCGTAT,A. victoria
+purify,S. pyogenes,Fujii,"<a href=""/61079/"">61079</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23942116/"">23942116</a>",IRF1,CCGGGGGCGCTGGGCTGTCCCGG,H. sapiens
+purify,S. pyogenes,Fujii,"<a href=""/61080/"">61080</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25051498/"">25051498</a>",IRF1,GCGCTTACACTTTAGGAGACACTC,H. sapiens
+cut,S. pyogenes,Sabatini,"<a href=""/70679/"">70679</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26472758/"">26472758</a>",JAK2 amplicon&nbsp;,GGTTTAATGGAAGAGAAGGG,H. sapiens
+cut,S. pyogenes,Seydoux,"<a href=""/66085/"">66085</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",K08F4.2,AATCACTCCCTGTTTGTGT,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/66095/"">66095</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",K08F4.2,CACGAGGTGGTATGCGCAG,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/66092/"">66092</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",K08F4.2,CGCAGCGGTTTCCAAAATG,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/66087/"">66087</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",K08F4.2,GCCTTAACCCAGAATAAGA,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/66089/"">66089</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",K08F4.2,TATTAAATGCAGATAACCT,C. elegans
+cut,S. pyogenes,Wolfe,"<a href=""/69238/"">69238</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",KANK3,GCATGGGTGATGTCAATGCC,H. sapiens
+cut,S. pyogenes,Mashimo,"<a href=""/60969/"">60969</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Kit-1,CATCTGTGCGGCCGTTGGCT,R. norvegicus
+cut,S. pyogenes,Mashimo,"<a href=""/60970/"">60970</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Kit-2,CTAACGTTCCAGCGCTCGTT,R. norvegicus
+cut,S. pyogenes,Mashimo,"<a href=""/60971/"">60971</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Kit-2,GTCAAGATGTCATCTTACGG,R. norvegicus
+cut,S. pyogenes,Calarco,"<a href=""/46170/"">46170</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23817069/"">23817069</a>",klp-12,GATCCACAAGTTACAATTGG,C. elegans
+cut,S. pyogenes,Zhang,"<a href=""/60224/"">60224</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25263330/"">25263330</a>","Kras, p53, and Lkb1","multiple, see article",M. musculus
+cut,S. pyogenes,Zhang,"<a href=""/60225/"">60225</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25263330/"">25263330</a>",LacZ,TGCGAATACGCCCACGCGAT,E. coli
+cut,S. pyogenes,Moffat,"<a href=""/74179/"">74179</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",LacZ,CCCGAATCTCTATCGTGCGG,E.coli
+cut,S. pyogenes,Patron,"<a href=""/68256/"">68256</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26616834/"">26616834</a>",lC.GA4a,GTTGAGAGGGGAGCCGGTGA,B. oleracea
+cut,S. pyogenes,Patron,"<a href=""/68255/"">68255</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26616834/"">26616834</a>",lC.GA4a,GTTTTCACTTGCGGCCGGAG,B. oleracea
+cut,S. pyogenes,Jin,"<a href=""/64332/"">64332</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25281382/"">25281382</a>",leu2,AATCACAGCCGAAGCCATTA,S. cerevisiae
+cut,S. pyogenes,Winslow,"<a href=""/66894/"">66894</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26178787/"">26178787</a>",Lkb1,GTGGTGGGCCGCAGTCACAA,M. musculus
+cut,S. pyogenes,Xue,"<a href=""/66586/"">66586</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",Lox-STOP-Lox,GCGTATAGCATACATTATACG,synthetic
+cut,S. pyogenes,Xue,"<a href=""/66585/"">66585</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",Lox-STOP-Lox,GCGTATAGTACACATTATACG,synthetic
+cut,S. pyogenes,Wolfe,"<a href=""/69237/"">69237</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",LRTM2,GCTGGCGGAAGACAGAGTGC,H. sapiens
+cut,S. pyogenes,Moffat,"<a href=""/74190/"">74190</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",Luciferase,ACAACTTTACCGACCGCGCC,
+cut,S. pyogenes,Cate,"<a href=""/60847/"">60847</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25139909/"">25139909</a>",LYP1,CATAATAACGTCCAATAAAT,S. cerevisiae
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72620/"">72620</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",Malat1,gRNA1: GAACCGGTGGGGCTGCGTCA; gRNA2: GGCAGGAGAGGCCAGTTGCG,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72621/"">72621</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",Malat1,gRNA1: GCAACTTCCATTTTCAGTCT; gRNA2: GGAAGCCTCAGCTCGCCTGA,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72622/"">72622</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",Malat1,gRNA1:GCTGGGGCTCAGTTGCGTAA; gRNA2:AGGTTTCTAAAACATGACGG,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72623/"">72623</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",Malat1,gRNA1:GTTGAGATGAAGCTTCTTCA; gRNA2:TCAACCGTCCCTGCAAGGCT,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72624/"">72624</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",Malat1,gRNA1: GAAACCTCGTGTAGCTATCA; gRNA2: AATGTGAAGGACTTTCGTAA,H. sapiens
+nick,S. pyogenes,Hanna,"<a href=""/61514/"">61514</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25569111/"">25569111</a>",Mettl14,GCCGCTCCCGGATCTCCTGC,M. musculus
+nick,S. pyogenes,Hanna,"<a href=""/61515/"">61515</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25569111/"">25569111</a>",Mettl14,GCGGCAGCTCCTAGCTCAGC,M. musculus
+cut,S. pyogenes,Zhao,"<a href=""/69801/"">69801</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26293209/"">26293209</a>",mitf,CTTTCGGATATAATCCACGG,S. scrofa&nbsp;
+cut,S. pyogenes,Chen,"<a href=""/47931/"">47931</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23918387/"">23918387</a>",mitfa,GGTCTCTCGCAGGATGTTGC,D. rerio
+cut,S. pyogenes,Bleris,"<a href=""/62715/"">62715</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25527740/"">25527740</a>",mKate,ATGAGAATCAAGGCGGTCGA,synthetic
+cut,S. pyogenes,Bornhauser,"<a href=""/75167/"">75167</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27194728/"">27194728</a>",MLKL,ATCCCCGTGGATTCTGCTAA,H. sapiens
+cut,S. pyogenes,Katsanis,"<a href=""/72890/"">72890</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26429889/"">26429889</a>",mmp21,CGGAGCTGATCACTGACA,D. rerio
+visualize,S. pyogenes,Qi,"<a href=""/51025/"">51025</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24360272/"">24360272</a>",MUC4,GTGGCGTGACCTGTGGATGCTG,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64138/"">64138</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",MYOD1,TGGCCTCCCTCCCTGCCCGGTAG,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64139/"">64139</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",MYOD1,TGGGAGGTTTGGAAAGGGCGTGC,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64136/"">64136</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",MYOD1,TGGGCCTGGGCTCCGGGGCGTTT,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64137/"">64137</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",MYOD1,TGGGGGCCCCTGCGGCCACCCCG,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64156/"">64156</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",NANOG,TGGCATATTCCTGATTTAAAAGT,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64153/"">64153</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",NANOG,TGGCGCCAGGAGGGGTGGGTCTA,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64154/"">64154</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",NANOG,TGGGCCTTGGTGAGACTGGTAGA,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64155/"">64155</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",NANOG,TGGTGTCTTCAGGTTCTGTTGCT,H. sapiens
+interfere,S. pyogenes,Lu,"<a href=""/68897/"">68897</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",NanoLuc,AGCTTACGCCACCCTGTTCC,synthetic
+interfere,S. pyogenes,Lu,"<a href=""/68898/"">68898</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",NanoLuc,GACAGAACGATGCGCTGAAT,synthetic
+interfere,S. pyogenes,Lu,"<a href=""/68895/"">68895</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",NanoLuc,TCACGCTCACACCCAGGTTC,synthetic
+interfere,S. pyogenes,Lu,"<a href=""/68896/"">68896</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",NanoLuc,TTGATCCAAATTATAACCCG,synthetic
+cut,S. pyogenes,Lu,"<a href=""/61270/"">61270</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25240928/"">25240928</a>",NDM-1,GGGCAGTCGCTTCCAACGGTTTGATCGTCA,
+cut,S. pyogenes,Cepko,"<a href=""/69992/"">69992</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25155555/"">25155555</a>",near LoxP sites,CGAAGTTATATTAAGGGTTC,synthetic
+interfere,S. pyogenes,Lu,"<a href=""/68893/"">68893</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",negative control,CTGGAATGAATTGGCCTATG,
+cut,S. pyogenes,Winslow,"<a href=""/66895/"">66895</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26178787/"">26178787</a>",negative control,GCGAGGTATTCGGCTCCGCG,M. musculus
+cut,S. pyogenes,Christiaen,"<a href=""/60006/"">60006</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25336740/"">25336740</a>",negative control,GCTTTGCTACGATCTACATT,C. intestinalis
+cut,S. pyogenes,Bleris,"<a href=""/64955/"">64955</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25527740/"">25527740</a>",negative control,GTCAAGGCACTCTTGCCTA,synthetic
+,S. pyogenes,Wolfe,"<a href=""/50927/"">50927</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",negative control,GTTCCGCGTTACATAACTTA,H. sapiens
+cut,S. pyogenes,Winslow,"<a href=""/67594/"">67594</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26178787/"">26178787</a>",Neomycin,TCATGGCTGATGCAATGCGG,
+cut,S. pyogenes,Zhang,"<a href=""/60227/"">60227</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25263330/"">25263330</a>",NeuN,TCCGGTTCAGGGACCCCGAC,M. musculus
+activate,S. pyogenes,Sato,"<a href=""/64161/"">64161</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",Neurog2,GTCTCTATCACTGATAGGGA,H. sapiens
+activate,S. pyogenes,Sato,"<a href=""/64160/"">64160</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25619936/"">25619936</a>",Neurog2,GTGAATGATGATAATACGAT,H. sapiens
+methylation,S. pyogenes,Zoldoš,"<a href=""/71830/"">71830</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26969735/"">26969735</a>",Non-targeting,GTAGGCGCGCCGCTCTCTAC,H. sapiens
+cut,S. pyogenes,Huangfu,"<a href=""/66989/"">66989</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26028531/"">26028531</a>",OCT4,CTCCCATGCATTCAAACTG,H. sapiens
+activate,S. pyogenes,Otonkoski,"<a href=""/69537/"">69537</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26352799/"">26352799</a>",OCT4,"multiple, see article",H. sapiens
+cut,N. meningitidis,Thomson,"<a href=""/47870/"">47870</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23940360/"">23940360</a>",OCT4,GTTGTAGCTCCCTTTCTCATTTCG,H. sapiens
+interfere,S. pyogenes,Wolfe,"<a href=""/50922/"">50922</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Oct4A (POU5F1),GGGGCGCCAGTTGTGTCTCC,H. sapiens
+interfere,S. pyogenes,Wolfe,"<a href=""/50921/"">50921</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Oct4A (POU5F1),GTGGGACTGGGGAGGGAGAG,H. sapiens
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",P450,CATATAGTTGGGTCATGGCA,O. sativa
+cut,S. pyogenes,Sherwood,"<a href=""/71483/"">71483</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26527385/"">26527385</a>",Pal1,GCTCTGTGACTAGTCACAGAG,synthetic
+cut,S. pyogenes,Sherwood,"<a href=""/71484/"">71484</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26527385/"">26527385</a>",Pal7,GGCTTAGTACTAGTACTAAGC,synthetic
+cut,S. pyogenes,Zhang,"<a href=""/68466/"">68466</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26145478/"">26145478</a>",PAX6,GATACTGGAGAAGCAGGGGC,H. sapiens
+cut,S. pyogenes,Zhang,"<a href=""/68465/"">68465</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26145478/"">26145478</a>",PAX6,GTAGATTTTGTATGCACTGC,H. sapiens
+interfere,S. pyogenes,Lu,"<a href=""/68900/"">68900</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",PcfiA,AAACAAAACCTCATCAGGCA,
+interfere,S. pyogenes,Lu,"<a href=""/68899/"">68899</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26918244/"">26918244</a>",PcfiA,GAAGCTCACTCCTTAGCACG,
+interfere,S. pyogenes,Lu,"<a href=""/74068/"">74068</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pck,AGGGCGAGGCGCCGACCAAGAATA,C. glutamicum
+interfere,S. pyogenes,Lu,"<a href=""/74069/"">74069</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pck,TCCAGTTCAGCAGTTCCTTATTCT,C. glutamicum
+cut,S. pyogenes,Kamoun,"<a href=""/46966/"">46966</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23929340/"">23929340</a>",PDS,GCCGTTAATTTGAGAGTCCA,N. benthamiana
+cut,S. pyogenes,Kamoun,"<a href=""/49772/"">49772</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24112467/"">24112467</a>",PDS1,"multiple, see article",N. benthamiana
+cut,S. pyogenes,Sheen,"<a href=""/52255/"">52255</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23929339/"">23929339</a>",PDS3,GGACTTTTGCCAGCCATGGT,A. thaliana
+interfere,S. pyogenes,Lu,"<a href=""/74066/"">74066</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pgi,TGACCGATCATTACTCAAACTTCC,C. glutamicum
+interfere,S. pyogenes,Lu,"<a href=""/74067/"">74067</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pgi,TTGCCTGGAAGTTTGAGTAATGAT,C. glutamicum
+activate,S. pyogenes,Gersbach,"<a href=""/60719/"">60719</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25664691/"">25664691</a>",pGL3-Basic-8x-gRNA-eGFP reporter,AAAGGTCGAGAAACTGCAAA,synthetic
+cut,S. pyogenes,Ward,"<a href=""/61252/"">61252</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25491644/"">25491644</a>",pha-1,ATGAATAACTTGATGAACAT,C. elegans
+cut,S. pyogenes,Kim,"<a href=""//""></a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26479191/"">26479191</a>",PHYB,CACTAGGAGCAACACCCAA,A. thaliana
+cut,S. pyogenes,Wolfe,"<a href=""/69240/"">69240</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",PLXNB2,GGGCCCAACCTAGGGCATGG,H. sapiens
+cut,S. pyogenes,Patron,"<a href=""/68253/"">68253</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26616834/"">26616834</a>",PM19,GCTCTCCACTCTGGGCTCTT,H. vulgare
+cut,S. pyogenes,Patron,"<a href=""/68254/"">68254</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26616834/"">26616834</a>",PM19,GGCTGGCGTTGGTCGTAACA,H. vulgare
+cut,S. pyogenes,Shaw,"<a href=""/79004/"">79004</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26944679/"">26944679</a>",Prkaa1,TTATTGTCACAGGCATATGG,M. musculus
+cut,S. pyogenes,Shaw,"<a href=""/79005/"">79005</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26944679/"">26944679</a>",Prkaa2,ACAGGCATATGGTTGTCCAT,M. musculus
+cut,S. pyogenes,Schmitt-Ulms,"<a href=""/61857/"">61857</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25490046/"">25490046</a>",Prnp,GGTGGAACACCGGTGGAAGC,M. musculus
+cut,S. pyogenes,Schmitt-Ulms,"<a href=""/61856/"">61856</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25490046/"">25490046</a>",Prnp,TTGGCCCCATCCACCGCCAT,M. musculus
+cut,N. meningitidis,Church,"<a href=""/48651/"">48651</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer A,TACCATCTCAAGCTTGTTGA,Synthetic
+cut,S. thermophilus,Church,"<a href=""/48653/"">48653</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer A,TACCATCTCAAGCTTGTTGA,Synthetic
+cut,T. denticola,Church,"<a href=""/48655/"">48655</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer A,TACCATCTCAAGCTTGTTGA,Synthetic
+cut,N. meningitidis,Church,"<a href=""/48652/"">48652</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer B,ACTTTAAAAGTATTCGCCAT,Synthetic
+cut,S. thermophilus,Church,"<a href=""/48654/"">48654</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer B,ACTTTAAAAGTATTCGCCAT,Synthetic
+cut,T. denticola,Church,"<a href=""/48656/"">48656</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24076762/"">24076762</a>",Protospacer B,ACTTTAAAAGTATTCGCCAT,Synthetic
+cut,S. pyogenes,Moffat,"<a href=""/74184/"">74184</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",PSMB2,ATGTTCTTGTCGCCTCCGAC,H. sapiens
+cut,S. pyogenes,Moffat,"<a href=""/74185/"">74185</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",PSMB2,AATATTGTCCAGATGAAGGA,H. sapiens
+cut,S. pyogenes,Moffat,"<a href=""/74180/"">74180</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",PSMD1,TGTGCGCTACGGAGCTGCAA,H. sapiens
+cut,S. pyogenes,Moffat,"<a href=""/74181/"">74181</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26627737/"">26627737</a>",PSMD1,ACCAGAGCCACAATAAGCCA,H. sapiens
+cut,S. pyogenes,Jacks,"<a href=""/59909/"">59909</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25119044/"">25119044</a>",Pten,AGATCGTTAGCAGAAACAAA,M. musculus
+cut,S. pyogenes,Xue,"<a href=""/66588/"">66588</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",Pten,GCTGTAGTAATATCTGCTAT,M. musculus
+cut,S. pyogenes,Xue,"<a href=""/66587/"">66587</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26018130/"">26018130</a>",Pten,GTTTCATAGCGGCCACGAAGT,M. musculus
+interfere,S. pyogenes,Lu,"<a href=""/74070/"">74070</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pyk,AGATTGTATGTACCCTAGGCCCAG,C. glutamicum
+interfere,S. pyogenes,Lu,"<a href=""/74072/"">74072</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",pyk,ATTCCATCTGCACTAGCCACCGCT,C. glutamicum
+tag,S. pyogenes,Mendenhall,"<a href=""/64057/"">64057</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26355004/"">26355004</a>",RAD21,CCAAGGTTCCATATTATATAAGG,H. sapiens
+cut,S. pyogenes,Fire,"<a href=""/59927/"">59927</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",rde-1(D718),TGCCATTAACTATGTATGT,C. elegans
+cut,S. pyogenes,Fire,"<a href=""/59928/"">59928</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",rde-1(D801),GATATTGTAGTCTATCGAGA,C. elegans
+cut,S. pyogenes,Fire,"<a href=""/59929/"">59929</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",rde-1(H974),GATAAATGAGCATAATGAAC,C. elegans
+interfere,S. pyogenes,Lu,"<a href=""/74075/"">74075</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26829286/"">26829286</a>",rfp,AAGTTCGTATGGAAGGTTCCGTTAA,
+cut,S. pyogenes,Joung,"<a href=""/42246/"">42246</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",rgs4,GGAGAAGGTGAAGGACACTG,D. rerio
+cut,S. pyogenes,Bornhauser,"<a href=""/75165/"">75165</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27194728/"">27194728</a>",RIP3,TACACGAGTGATGGTTCGGT,H. sapiens
+cut,S. pyogenes,Bornhauser,"<a href=""/75163/"">75163</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27194728/"">27194728</a>",RIPK1,GCTCTGCTGGGAAGCGAATC,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47509/"">47509</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",RNF2,GTCATCTTAGTCATTACCTG,H. sapiens
+cut,S. pyogenes,Fire,"<a href=""/59930/"">59930</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",rol-6(su1006),GTGAGACGTCAACAATATGG,C. elegans
+cut,S. pyogenes,Kuhn,"<a href=""/64216/"">64216</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25803306/"">25803306</a>",Rosa26,ACTCCAGTCTTTCTAGAAGA,M.musculus
+cut,S. pyogenes,Marraffini,"<a href=""/44505/"">44505</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360965/"">23360965</a>",rpsL,AAAAAACCGAACTCCGCGCTGCGTAAAGTA,E. coli
+interfere,S. pyogenes,Voigt,"<a href=""/62285/"">62285</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25422271/"">25422271</a>",scramble,AACCCCTGATTGTATCCGCA,synthetic
+cut,S. pyogenes,Chen,"<a href=""/47930/"">47930</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23918387/"">23918387</a>",slc24a5 (golden),GGTCTCTCGCAGGATGTTGC,D. rerio
+cut,S. pyogenes,Hanna,"<a href=""/59725/"">59725</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25543152/"">25543152</a>",SOX17,GCCCAGCCCGGCCATCACCG,H. sapiens
+activate,S. pyogenes,Wolfe,"<a href=""/50925/"">50925</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Sox17,GCTCCGGCTAGTTTTCCCGG,H. sapiens
+activate,S. pyogenes,Wolfe,"<a href=""/50924/"">50924</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Sox17,GGAGGGGCAAGGGGCGGGCG,H. sapiens
+activate,S. pyogenes,Wolfe,"<a href=""/50926/"">50926</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Sox17,GGGCAAGTACGTCGATTCCA,H. sapiens
+activate,S. pyogenes,Wolfe,"<a href=""/50923/"">50923</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24346702/"">24346702</a>",Sox17,GGGCGTGGGCCTAACGACGC,H. sapiens
+cut,S. pyogenes,Fire,"<a href=""/59935/"">59935</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",sqt-1,GGAAGGACATAGTTGTCAT,C. elegans
+cut,S. pyogenes,Fire,"<a href=""/60212/"">60212</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",sqt-1,TGTGGAGTTGGGGTAGCGT,C. elegans
+activate/interfere,S. pyogenes,Qi,"<a href=""/62338/"">62338</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",sv40 promoter,CATACTTCTGCCTGCTGGGGAGCCTG,synthetic
+scaffold,S. pyogenes,Qi &amp; Lim,"<a href=""/62340/"">62340</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",SV40.NT1,GAATAGCTCAGAGGCCGAGG,H. sapiens
+cut,S. pyogenes,Seydoux,"<a href=""/66100/"">66100</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",swan-2,ACAAATTGATATCCAATCA,C. elegans
+cut,S. pyogenes,Seydoux,"<a href=""/66099/"">66099</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25249454/"">25249454</a>",swan-2,TGAAGAAAGTTATACTCGA,C. elegans
+cut,S. pyogenes,Hanna,"<a href=""/59726/"">59726</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25543152/"">25543152</a>",T (BRACHYURY),CACGCGCAGTTCGCGCTCTG,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72627/"">72627</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",TCRC,gRNA1:GGGGAGCGGGAAAGCGGTCG; gRNA2:AACTGACCTTCAGGCCCGTA,H. sapiens
+cut,N. meningitidis,Thomson,"<a href=""/47869/"">47869</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23940360/"">23940360</a>",tdtomato,CGAAATGAGAAAGGGAGCTACAAC,Synthetic
+scaffold,S. pyogenes,Qi &amp; Lim,"<a href=""/62320/"">62320</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",TEF,TTGATATTTAAGTTAATAAA,S. cerevisiae
+interfere,S. pyogenes,Weissman,"<a href=""/46922/"">46922</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",TEF1,TTGATATTTAAGTTAATAAA,S. cerevisiae
+visualize,S. pyogenes,Qi,"<a href=""/51024/"">51024</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24360272/"">24360272</a>",telomeres,GTTAGGGTTAGGGTTAGGGTTA,H. sapiens
+scaffold,S. pyogenes,Qi &amp; Lim,"<a href=""/62313/"">62313</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",TET,ACTTTTCTCTATCACTGATA,S. cerevisiae
+interfere,S. pyogenes,Weissman,"<a href=""/46923/"">46923</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23849981/"">23849981</a>",TET promoter,TATCAGTGATAGAGAAAAGT,
+activate/interfere,S. pyogenes,Qi,"<a href=""/62327/"">62327</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",Tet3G,GTACGTTCTCTATCACTGATA,synthetic
+cut,S. pyogenes,Shaw,"<a href=""/79006/"">79006</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26944679/"">26944679</a>",Tfeb,AGCACTGTTGCCGGCCGAGG,M. musculus
+RNA targeting,S. pyogenes,Yeo,"<a href=""/74709/"">74709</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26997482/"">26997482</a>",TFRC,GCACUGACCAGAUAAGAAUG,H. sapiens
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72626/"">72626</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",TFRC,"gRNA1:GCAGCCTCAGAAATACAAAA, gRNA2CGGGATATCGGGTGGCGGCT",H. sapiens
+cut,S. pyogenes,Wolfe,"<a href=""/69239/"">69239</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",TGM2,CCTGGACCCAACGCCCCAGG,H. sapiens
+cut,S. pyogenes,Sibley,"<a href=""/59855/"">59855</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25480939/"">25480939</a>",TGME49_290860,ATTGGTCTGACAGCGATGTG,T. gondii
+cut,S. pyogenes,Joung,"<a href=""/42247/"">42247</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",th,GGATGCGCGTAAGGAGCGCG,D. rerio
+cut,S. pyogenes,Du,"<a href=""/65565/"">65565</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25849248/"">25849248</a>",th,GGGTTGTTACACTCATAAAG,D. rerio
+cut,S. pyogenes,Joung,"<a href=""/42248/"">42248</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",tia1l,GGTATGTCGGGAACCTCTCC,D. rerio
+cut,S. pyogenes,Joung,"<a href=""/42249/"">42249</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23360964/"">23360964</a>",tph1a,GGGAAAACACAACCGCAGCC,D. rerio
+scaffold,S. pyogenes,Qi &amp; Lim,"<a href=""/62325/"">62325</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25533786/"">25533786</a>",TRE3G,GTACGTTCTCTATCACTGATA,H. sapiens
+cut,S. pyogenes,Jin,"<a href=""/64331/"">64331</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25281382/"">25281382</a>",trp1,GTCAATTGTTCTCTTTCTAT,S. cerevisiae
+cut,S. pyogenes,Jacks,"<a href=""/59910/"">59910</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25119044/"">25119044</a>",Trp53,CCTCGAGCTCCCTCTGAGCC,M. musculus
+cut,S. pyogenes,Wolfe,"<a href=""/69234/"">69234</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",TS2,GACCCCCTCCACCCCGCCTC,H. sapiens
+cut,S. pyogenes,Wolfe,"<a href=""/69235/"">69235</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",TS3,GGTGAGTGAGTGTGTGCGTG,H. sapiens
+cut,S. pyogenes,Wolfe,"<a href=""/69236/"">69236</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26480473/"">26480473</a>",TS4,GAGTCCGAGCAGAAGAAGAA,H. sapiens
+cut,S. pyogenes,Goldstein,"<a href=""/47550/"">47550</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23995389/"">23995389</a>",ttTi5605 Mos1 insertion site,ATATCAGTCTGTTTCGTAA,C. elegans
+cut,S. pyogenes,Chen,"<a href=""/46761/"">46761</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23918387/"">23918387</a>",tyr,CCCCAGAAGTCCTCCAGTCC,D. rerio
+cut,S. pyogenes,Chen,"<a href=""/64250/"">64250</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25855067/"">25855067</a>",tyr,GGACTGGAGGACTTCTGGGG,D. rerio
+cut,S. pyogenes,Mashimo,"<a href=""/60966/"">60966</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Tyr (albino),TTTCCAGGATTATGTAATAG,R. norvegicus
+cut,S. pyogenes,Mashimo,"<a href=""/60967/"">60967</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24967838/"">24967838</a>",Tyr (wild type),TTTCCAGGATTACGTAATAG,R. norvegicus
+cut,S. pyogenes,"Guigo, Johnson","<a href=""/72628/"">72628</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/26493208/"">26493208</a>",UCA1,gRNA1:GGTTTCCTTTTAGATGACGG; gRNA2:TCTGAAAAGAGAGTCAGCGA,H. sapiens
+cut,S. pyogenes,Fire,"<a href=""/59932/"">59932</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",unc-109(n499),GGAACTCGTGTCAAAACAAC,C. elegans
+cut,S. pyogenes,Calarco,"<a href=""/46169/"">46169</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23817069/"">23817069</a>",unc-119,GAATTTTCTGAAATTAAAGA,C. elegans
+cut,S. pyogenes,Mello,"<a href=""/58202/"">58202</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24879462/"">24879462</a>",unc-22,GAACCCGTTGCCGAATACAC,C. elegans
+cut,S. pyogenes,Fire,"<a href=""/59931/"">59931</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25161212/"">25161212</a>",unc-58(e665),TCCACGCACATGGTCACTA,C. elegans
+cut,S. pyogenes,Sibley,"<a href=""/54467/"">54467</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24825012/"">24825012</a>",UPRT,GGCGTCTCGATTGTGAGAGC,Toxoplasma gondii
+cut,S. pyogenes,Jin,"<a href=""/64330/"">64330</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25281382/"">25281382</a>",ura3,GAGTAAAAAATTGTACTTGG,S. cerevisiae
+cut,S. pyogenes,Ye,"<a href=""/61812/"">61812</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24424410/"">24424410</a>",USP13,GCCGCCCGGCATGCCGAACA,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47506/"">47506</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",VEGF,GACCCCCTCCACCCCGCCTC,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47505/"">47505</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",VEGF,GGGTGGGGGGAGTTTGCTCC,H. sapiens
+cut,S. pyogenes,Joung,"<a href=""/47507/"">47507</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/23792628/"">23792628</a>",VEGF,GGTGAGTGAGTGTGTGCGTG,H. sapiens
+interfere,S. pyogenes,Voigt,"<a href=""/62286/"">62286</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25422271/"">25422271</a>",VR,TGCGCTCGGTCGTTCGGCTG,synthetic
+nick,S. pyogenes,Yang,"<a href=""/73228/"">73228</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/27213844/"">27213844</a>",xylR,CGAGTTAGACATAATAGTGA,C. beijerinckii
+cut,S. pyogenes,Ward,"<a href=""/61250/"">61250</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/25491644/"">25491644</a>",Y61A9LA.1,GGATGGATGTGTAGTCAATT,C. elegans
+cut,S. pyogenes,Liu,"<a href=""/49331/"">49331</a>","<a href=""https://www.ncbi.nlm.nih.gov/pubmed/24326186/"">24326186</a>",yellow,GGTTTTGGACACTGGAACCG,D. melanogaster

Biomanus_upload/biomni/know_how/sgRNA_design_guide.md

@@ -0,0 +1,419 @@
+# sgRNA Design Guide: Three-Tiered Approach
+
+---
+
+## Metadata
+
+**Short Description**: Comprehensive guide for finding or designing sgRNAs using validated sequences, CRISPick datasets, or de novo design tools.
+
+**Authors**: Biomni Team
+
+**Version**: 1.0
+
+**Last Updated**: November 2025
+
+**License**: CC BY 4.0
+
+**Commercial Use**: ✅ Allowed
+
+## Citations and Acknowledgments
+
+### If you use validated sgRNAs from our database (Option 1):
+- **Database Source**: Addgene (https://www.addgene.org)
+- **Citation**: Always cite the original publication associated with each sgRNA using the PubMed ID provided in the database
+- **Acknowledgment**: "Validated sgRNA sequences obtained from Addgene (https://www.addgene.org/crispr/reference/grna-sequence/)"
+
+### If you use CRISPick designs (Option 2):
+- **Acknowledgment Statement**: "Guide designs provided by the CRISPick web tool of the GPP at the Broad Institute"
+- **Citation for Cas9 designs (SpCas9, SaCas9)**: Sanson KR, et al. Optimized libraries for CRISPR-Cas9 genetic screens with multiple modalities. Nat Commun. 2018;9(1):5416. PMID: 30575746
+- **Citation for Cas12a designs (AsCas12a, enAsCas12a)**: DeWeirdt PC, et al. Optimization of AsCas12a for combinatorial genetic screens in human cells. Nat Biotechnol. 2021;39(1):94-104. PMID: 32661438
+  - Note: This paper describes enAsCas12a optimization; specify which variant you used in your methods
+
+---
+
+## Overview
+
+This guide provides a three-tiered approach to sgRNA design, prioritizing validated sequences before moving to computational predictions. Always start with Option 1 and proceed to subsequent options only if needed.
+
+
+
+## Option 1: Search Validated sgRNA Sequences (Recommended First)
+
+### 1.1 Search for Validated sgRNAs
+
+**IMPORTANT**: You MUST complete BOTH Method 1 AND Method 2 before proceeding to Option 2. Do not skip Method 2 even if Method 1 finds no results.
+
+#### Method 1: Search Our Database (Fastest)
+
+We maintain a curated database of 300+ validated sgRNA sequences from Addgene with experimental evidence.
+
+**Location**: `biomni/know_how/resource/addgene_grna_sequences.csv`
+
+**Search the database**:
+```python
+import pandas as pd
+
+# Load the database
+df = pd.read_csv('addgene_grna_sequences.csv')
+
+# Search for your gene
+gene_name = "TP53"
+results = df[df['Target_Gene'].str.upper() == gene_name.upper()]
+
+# Filter by species and application
+results_filtered = results[
+    (results['Target_Species'] == 'H. sapiens') &
+    (results['Application'] == 'cut')  # or 'activate', 'RNA targeting'
+]
+
+# Display results with references
+print(results_filtered[['Target_Gene', 'Target_Sequence',
+                        'Plasmid_ID', 'PubMed_ID', 'Depositor']])
+```
+
+**Database columns**:
+- `Target_Gene`: Gene symbol
+- `Target_Species`: Organism (H. sapiens, M. musculus, etc.)
+- `Target_Sequence`: 20bp sgRNA sequence (5' to 3')
+- `Application`: cut (knockout), activate (CRISPRa), RNA targeting (CRISPRi)
+- `Cas9_Species`: S. pyogenes, S. aureus, etc.
+- `Plasmid_ID`: Addgene plasmid number
+- `Plasmid_URL`: Direct link to plasmid page
+- `PubMed_ID`: **Publication reference** (cite this in your work)
+- `PubMed_URL`: Direct link to paper
+- `Depositor`: Research lab that contributed the sequence
+
+#### Method 2: Advanced Web Search (REQUIRED - Do Not Skip)
+
+**CRITICAL**: Even if Method 1 found no results, you MUST perform this literature search before moving to Option 2. Many validated sgRNAs are published in literature but not in the Addgene database.
+
+Use `advanced_web_search_claude` from `biomni.tool.literature` to find validated sgRNAs from literature and databases:
+
+```python
+from biomni.tool.literature import advanced_web_search_claude
+
+# Example usage
+results = advanced_web_search_claude("sgRNA TP53 validated H. sapiens experimental")
+```
+
+**Search queries to try (use multiple):**
+```
+"sgRNA" OR "guide RNA" "[GENE_NAME]" validated experimental
+"CRISPR knockout" "[GENE_NAME]" sgRNA sequence validated
+"[GENE_NAME]" sgRNA "cutting efficiency" OR "on-target"
+"[GENE_NAME]" "guide sequence" CRISPR validated
+```
+
+**Example for TP53:**
+```
+"sgRNA" "TP53" validated "H. sapiens" experimental
+"CRISPR knockout" "TP53" guide sequence validated
+```
+
+**What to search for in results:**
+- Published papers with validated sgRNA sequences
+- Supplementary materials containing sgRNA sequences
+- Other CRISPR databases (e.g., GenScript, Horizon Discovery)
+- Laboratory protocols with specific sgRNA sequences
+
+**IMPORTANT**: Spend adequate time searching literature. Look through at least the first 10-15 search results and check supplementary materials of relevant papers.
+
+#### What to Do with Results:
+
+✅ **If you find matching sgRNAs (from either method):**
+1. **Record the sgRNA sequence** (20bp target sequence)
+2. **Note the reference**:
+   - From database: Use `PubMed_ID` to cite the original paper
+   - From web search: Record the publication DOI/PubMed ID
+3. **Record validation details**: Cell line, cutting efficiency, any reported off-targets
+
+
+**Example result format:**
+```
+Gene: TP53
+sgRNA sequence: GAGGTTGTGAGGCGCTGCCC
+Species: H. sapiens (human)
+Application: Knockout (cut)
+Reference: PubMed ID 24336569 (Ran et al., 2013)
+Validation: Tested in HEK293T cells, 85% cutting efficiency
+```
+
+❌ **If no matches found in BOTH Method 1 AND Method 2:**
+Only then proceed to **Option 2: Download CRISPick Dataset**
+
+
+
+## Option 2: Download Pre-Computed sgRNAs from CRISPick
+
+### When to Use This Option?
+- No validated sgRNAs found in Addgene
+- Need comprehensive coverage of a gene
+- Want multiple sgRNA options with predicted scores
+- Working with genome-scale screening
+
+### 2.1 Overview of CRISPick
+
+**CRISPick** (from Broad Institute GPP) provides pre-computed sgRNA designs for entire genomes with 238 available datasets covering:
+- Human (GRCh38, GRCh37)
+- Mouse (GRCm38, GRCm39)
+- Dog, Cow, Monkey, and other model organisms
+- Multiple Cas enzymes (SpCas9, SaCas9, AsCas12a, enAsCas12a)
+  - **IMPORTANT**: AsCas12a and enAsCas12a are DIFFERENT enzymes
+  - **AsCas12a**: Wild-type Acidaminococcus sp. Cas12a
+  - **enAsCas12a**: Enhanced variant with improved activity
+  - **Critical**: sgRNAs designed for enAsCas12a may NOT work with wild-type AsCas12a
+  - Always match the dataset to your specific Cas12a variant
+- Different applications (knockout, activation, inhibition)
+
+### 2.2 Find the Download Link
+
+**All 238 download links are available in**: `biomni/know_how/resource/CRISPick_download_links.txt`
+
+#### Step 1: Understand File Naming Convention
+
+Files are named: `sgRNA_design_{TAXID}_{GENOME}_{CAS}_{APPLICATION}_{ALGORITHM}_{SOURCE}_{DATE}.txt.gz`
+
+**Common datasets:**
+
+| Organism | Genome | Cas9 | Application | Search Pattern |
+|-|--||-|-|
+| Human | GRCh38 | SpCas9 | Knockout | `9606_GRCh38_SpyoCas9_CRISPRko` |
+| Human | GRCh38 | SpCas9 | Activation | `9606_GRCh38_SpyoCas9_CRISPRa` |
+| Human | GRCh38 | SaCas9 | Knockout | `9606_GRCh38_SaurCas9_CRISPRko` |
+| Mouse | GRCm38 | SpCas9 | Knockout | `10090_GRCm38_SpyoCas9_CRISPRko` |
+| Mouse | GRCm38 | SpCas9 | Activation | `10090_GRCm38_SpyoCas9_CRISPRa` |
+
+**Key components:**
+- **TAXID**: `9606` (Human), `10090` (Mouse), `9615` (Dog), `9913` (Cow)
+- **CAS**:
+  - `SpyoCas9` (SpCas9, NGG PAM)
+  - `SaurCas9` (SaCas9, NNGRRT PAM)
+  - `AsCas12a` (Wild-type Cas12a, TTTV PAM)
+  - `enAsCas12a` (Enhanced Cas12a, TTTV PAM)
+  - **WARNING**: Do NOT use AsCas12a datasets if you have enAsCas12a, and vice versa
+- **APPLICATION**: `CRISPRko` (knockout), `CRISPRa` (activation), `CRISPRi` (inhibition)
+
+#### Step 2: Find Your Download URL
+
+```bash
+# Search the download links file
+grep "9606_GRCh38_SpyoCas9_CRISPRko" biomni/know_how/resource/CRISPick_download_links.txt
+
+# Or for mouse
+grep "10090_GRCm38_SpyoCas9_CRISPRko" biomni/know_how/resource/CRISPick_download_links.txt
+```
+
+#### Step 3: Download and Extract
+
+```bash
+# Copy the URL from download_links.txt, then:
+wget [PASTE_URL_HERE]
+
+# Extract the file
+gunzip sgRNA_design_*.txt.gz
+```
+
+**File sizes**: Knockout (300-700 MB), Activation (50-100 MB), Summary files (1-3 MB)
+
+### 2.4 Understanding the File Format
+
+The `.txt` file is tab-delimited. Column names differ between knockout and activation/inhibition datasets.
+
+**Essential Columns (All files):**
+- **sgRNA Sequence**: The 20bp guide RNA sequence (5' to 3')
+- **Target Gene Symbol**: Gene name (e.g., "TP53", "BRCA1")
+- **Combined Rank**: Overall ranking (lower = better) - **Use this by default**
+- **On-Target Rank**: Ranking by efficiency only (lower = better)
+- **Off-Target Rank**: Ranking by specificity only (lower = better)
+- **PAM Sequence**: The PAM sequence (e.g., "AGG", "TGG")
+
+**Knockout-specific columns:**
+- **sgRNA Cut Position (1-based)**: Genomic coordinate of cut site
+- **Exon Number**: Which exon is targeted
+- **Target Cut %**: Percentage of protein affected
+
+**Activation/Inhibition-specific columns:**
+- **sgRNA 'Cut' Position**: Position relative to gene
+- **sgRNA 'Cut' Site TSS Offset**: Distance from transcription start site (bp)
+- **DHS Score**: DNase hypersensitivity score (for CRISPRa)
+
+### 2.5 Extract and Select sgRNAs
+
+#### Step 1: Load Data and Filter for Your Gene
+
+```python
+import pandas as pd
+
+# Load the dataset
+df = pd.read_csv('sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_*.txt',
+                 sep='\t', low_memory=False)
+
+# Filter for your gene
+gene_name = "TP53"
+gene_sgrnas = df[df['Target Gene Symbol'] == gene_name].copy()
+
+print(f"Found {len(gene_sgrnas)} sgRNAs for {gene_name}")
+```
+
+#### Step 2: Select Top sgRNAs
+
+**Default: Use Combined Rank (balances efficiency and specificity)**
+```python
+# Sort by Combined Rank (lower is better)
+top_sgrnas = gene_sgrnas.nsmallest(10, 'Combined Rank')
+
+print(top_sgrnas[['sgRNA Sequence', 'Combined Rank',
+                   'Exon Number', 'sgRNA Cut Position (1-based)']])
+```
+
+**Option A: Prioritize On-Target Efficiency**
+```python
+# Sort by On-Target Rank (for maximum cutting efficiency)
+efficient_sgrnas = gene_sgrnas.nsmallest(10, 'On-Target Rank')
+```
+
+**Option B: Prioritize Off-Target Specificity**
+```python
+# Sort by Off-Target Rank (for maximum specificity)
+specific_sgrnas = gene_sgrnas.nsmallest(10, 'Off-Target Rank')
+```
+
+#### Step 3: Filter by Custom Criteria (Optional)
+
+**Filter by Exon Number:**
+```python
+# Target specific exon (e.g., exon 5)
+exon5_sgrnas = gene_sgrnas[gene_sgrnas['Exon Number'] == 5]
+top_exon5 = exon5_sgrnas.nsmallest(5, 'Combined Rank')
+```
+
+**Filter by Genomic Position:**
+```python
+# Target specific genomic range
+position_filtered = gene_sgrnas[
+    (gene_sgrnas['sgRNA Cut Position (1-based)'] >= 7572000) &
+    (gene_sgrnas['sgRNA Cut Position (1-based)'] <= 7575000)
+]
+```
+
+**Target Early Exons for Knockout:**
+```python
+# Get sgRNAs from first 3 exons
+early_exons = gene_sgrnas[gene_sgrnas['Exon Number'] <= 3]
+top_early = early_exons.nsmallest(10, 'Combined Rank')
+```
+
+**Filter by Target Cut Percentage:**
+```python
+# Target sgRNAs that affect significant portion of protein
+high_impact = gene_sgrnas[gene_sgrnas['Target Cut %'] <= 50]  # Cut in first 50%
+top_high_impact = high_impact.nsmallest(10, 'Combined Rank')
+```
+
+#### Step 4: Select Multiple sgRNAs for Validation
+
+```python
+# Get top 4 sgRNAs from different exons for redundancy
+final_selection = gene_sgrnas.sort_values('Combined Rank').groupby('Exon Number').head(1).head(4)
+
+# Save results
+final_selection.to_csv(f'{gene_name}_selected_sgRNAs.csv', index=False)
+
+print("\nSelected sgRNAs:")
+print(final_selection[['sgRNA Sequence', 'Exon Number', 'Combined Rank']])
+```
+
+### 2.6 What to Do with Results
+
+✅ **Once you have selected sgRNAs:**
+1. Choose **3-4 sgRNAs** (use Combined_Rank by default)
+
+❌ **If dataset doesn't cover your gene or organism:**
+Proceed to **Option 3: De Novo sgRNA Design**
+
+
+
+## Option 3: General sgRNA Design Guidelines (Last Resort)
+
+### When to Use This Option?
+- Gene not covered in CRISPick datasets
+- Non-model organism
+- Custom design requirements
+
+### General Design Rules
+
+#### Essential Requirements:
+1. **Length**:
+   - 20 bp for SpCas9 and SaCas9
+   - 23-25 bp for Cas12a variants (AsCas12a, enAsCas12a)
+2. **PAM sequence**:
+   - **SpCas9**: Requires **NGG** immediately after target (3' end)
+   - **SaCas9**: Requires **NNGRRT** immediately after target (3' end)
+   - **AsCas12a** (wild-type): Requires **TTTV** before target (5' end)
+   - **enAsCas12a** (enhanced): Requires **TTTV** before target (5' end)
+   - **CRITICAL**: Guides designed for enAsCas12a may not work with wild-type AsCas12a due to different activity profiles
+3. **GC content**: 40-60% is optimal
+4. **Avoid**:
+   - TTTT sequences (terminates transcription)
+   - Long runs of same nucleotide (>4 repeats)
+
+#### Target Location:
+- **For knockout**: Target early exons (first 50% of gene)
+- **For activation**: Target -200 to +1 bp from transcription start site (TSS)
+- **For inhibition**: Target -50 to +300 bp from TSS
+
+#### Best Practices:
+- **Test 3-4 different sgRNAs** per target gene
+- Select sgRNAs with high efficiency scores (>0.5) and minimal off-targets
+- Validate experimentally with Sanger sequencing
+
+
+
+## Quick Start Examples
+
+### Example 1: Knockout TP53 in Human Cells
+
+**Step 1**: Check Addgene
+```python
+df = pd.read_csv('addgene_grna_sequences.csv')
+tp53_results = df[(df['Target_Gene'] == 'TP53') &
+                  (df['Target_Species'] == 'H. sapiens') &
+                  (df['Application'] == 'cut')]
+# Result: Found 0 entries → Proceed to Option 2
+```
+
+**Step 2**: Download CRISPick dataset
+```bash
+# Download human GRCh38 SpCas9 knockout dataset
+wget https://portals.broadinstitute.org/gppx/public/sgrna_design/api/downloads/\
+sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_RS3seq-Chen2013+RS3target_NCBI_20241104.txt.gz
+
+gunzip sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_*.txt.gz
+```
+
+**Step 3**: Extract TP53 sgRNAs
+```python
+df = pd.read_csv('sgRNA_design_9606_GRCh38_SpyoCas9_CRISPRko_*.txt', sep='\t')
+tp53 = df[df['Gene_Symbol'] == 'TP53']
+top_sgrnas = tp53[
+    (tp53['sgRNA_score'] > 0.6) &
+    (tp53['Off_target_stringency'] > 0.5)
+].sort_values('sgRNA_score', ascending=False).head(4)
+
+print(top_sgrnas[['sgRNA_sequence', 'sgRNA_score', 'Exon_ID']])
+```
+
+### Example 2: Activate OCT4 in Human iPSCs
+
+**Step 1**: Check Addgene
+```python
+oct4_results = df[(df['Target_Gene'] == 'OCT4') &
+                  (df['Application'] == 'activate')]
+# Found 1 validated sgRNA!
+print(oct4_results['Target_Sequence'].values[0])
+# Use this sequence ✅
+```
+
+
+
+**Remember**: Always start with validated sequences (Option 1), then move to pre-computed designs (Option 2), and only use de novo design (Option 3) when necessary. Testing 3-4 sgRNAs per gene is standard practice regardless of prediction scores.

Biomanus_upload/biomni/know_how/single_cell_annotation.md

@@ -0,0 +1,223 @@
+# Single Cell RNA-seq Cell Type Annotation
+
+---
+
+## Metadata
+
+**Short Description**: Best practices for annotating cell types in single-cell RNA-seq data using marker-based, automated, and reference-based approaches.
+
+**Authors**: Distilled from "Single-cell best practices" by Luecken, M.D. et al.
+
+**Affiliations**: Helmholtz Munich, Wellcome Sanger Institute, Harvard Medical School, and contributors
+
+**Version**: 1.0
+
+**Last Updated**: January 2025
+
+**License**: CC BY 4.0
+
+**Commercial Use**: ✅ Allowed
+
+**Source**: https://www.sc-best-practices.org/cellular_structure/annotation.html
+
+**Citation**: Luecken, M.D., Theis, F.J. et al. (2023). Current best practices in single-cell RNA-seq analysis: a tutorial. Molecular Systems Biology.
+
+---
+
+## Overview
+
+Cell type annotation is the process of assigning cell type labels to clusters or individual cells in single-cell RNA-seq data. This guide covers three main approaches and their practical implementation.
+
+## Three Annotation Approaches
+
+### 1. Manual Marker-Based Annotation
+Identify cell types by examining expression of known marker genes in each cluster.
+
+**Tools**: Scanpy, Seurat
+**Best for**: Small datasets, novel cell types, high confidence needs
+
+### 2. Automated Annotation
+Use pre-trained classifiers to automatically assign cell type labels.
+
+**Tools**: CellTypist, scAnnotate
+**Best for**: Standard tissues, quick preliminary annotation, large datasets
+
+### 3. Reference-Based Label Transfer
+Transfer labels from annotated reference datasets to your query data.
+
+**Tools**: scArches, scANVI, Azimuth, SingleR
+**Best for**: Well-characterized tissues, integration with public data
+
+## Recommended Workflow
+
+### Step 1: Quality Control First
+- **Remove low-quality cells before annotation**
+- Filter doublets (expected doublet rate: 0.8% per 1000 cells)
+- Check for ambient RNA contamination
+- Verify cluster quality and resolution
+
+### Step 2: Initial Marker-Based Assessment
+
+```python
+# Scanpy example
+import scanpy as sc
+
+# Calculate marker genes for clusters
+sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')
+
+# Visualize top markers
+sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False)
+
+# Plot known markers
+markers = {
+    'T cells': ['CD3D', 'CD3E', 'CD4', 'CD8A'],
+    'B cells': ['CD19', 'MS4A1', 'CD79A'],
+    'Monocytes': ['CD14', 'FCGR3A', 'LYZ'],
+    'NK cells': ['NCAM1', 'NKG7', 'GNLY']
+}
+
+sc.pl.dotplot(adata, markers, groupby='leiden')
+```
+
+### Step 3: Use Automated Tools for Validation
+
+```python
+# CellTypist example (fast, accurate for immune cells)
+import celltypist
+from celltypist import models
+
+# Download immune cell model
+model = models.Model.load(model='Immune_All_Low.pkl')
+
+# Predict cell types
+predictions = celltypist.annotate(adata, model=model, majority_voting=True)
+adata = predictions.to_adata()
+```
+
+### Step 4: Reference-Based Refinement
+
+```python
+# scArches example for label transfer
+import scarches as sca
+
+# Load pre-trained reference model
+model = sca.models.SCANVI.load_query_data(
+    adata=adata,  # Your query data
+    reference_model="path/to/reference_model"
+)
+
+# Transfer labels
+model.train(max_epochs=100)
+adata.obs['transferred_labels'] = model.predict()
+```
+
+## Best Practices
+
+### Do's:
+1. **Always combine multiple approaches** - Use marker-based validation even with automated tools
+2. **Check cluster purity** - Ensure clusters represent single cell types
+3. **Validate with multiple marker sets** - Don't rely on single markers
+4. **Consider biological context** - Tissue type, disease state, developmental stage
+5. **Document confidence levels** - Note uncertain annotations
+6. **Use hierarchical annotation** - Broad categories first, then subtypes
+
+### Don'ts:
+1. **Don't over-cluster** - Too fine resolution creates artificial distinctions
+2. **Don't ignore batch effects** - Correct before annotation
+3. **Don't trust automation blindly** - Always validate predictions
+4. **Don't mix cell states with cell types** - Activated vs. resting cells are states, not types
+5. **Don't annotate low-quality cells** - Remove them first
+
+## Common Pitfalls
+
+### 1. Doublet Clusters
+**Problem**: Clusters with markers from multiple cell types
+**Solution**: Use doublet detection tools (Scrublet, DoubletFinder) before annotation
+
+### 2. Ambient RNA
+**Problem**: Background markers in all cells
+**Solution**: Use SoupX or CellBender for decontamination
+
+### 3. Over-interpretation of Small Clusters
+**Problem**: Rare clusters may be technical artifacts
+**Solution**: Require minimum cell count (e.g., >25 cells), validate with independent data
+
+### 4. Reference Mismatch
+**Problem**: Reference from different tissue/species/condition
+**Solution**: Use tissue-matched references, check marker overlap before transfer
+
+## Tool Selection Guide
+
+| Scenario | Recommended Tool | Why |
+|----------|------------------|-----|
+| Immune cells (human) | CellTypist | Pre-trained on large immune atlases |
+| Mouse tissues | scArches + Mouse Cell Atlas | Comprehensive mouse reference |
+| Novel cell types | Manual + Scanpy/Seurat | Need domain expertise |
+| Large datasets (>100k cells) | CellTypist | Fast, scalable |
+| Cross-species | Manual markers | Limited reference transfer |
+| Developmental data | scArches | Handles continuous states |
+
+## Key Marker Genes by Cell Type
+
+### Blood/Immune:
+- **T cells**: CD3D, CD3E (all T cells); CD4, CD8A (subtypes)
+- **B cells**: CD19, MS4A1 (CD20), CD79A
+- **Monocytes/Macrophages**: CD14, CD68, LYZ
+- **NK cells**: NCAM1 (CD56), NKG7, KLRD1
+- **Dendritic cells**: FCER1A, CD1C
+
+### Epithelial:
+- **General epithelial**: EPCAM, KRT18, KRT19
+- **Lung AT1**: AGER, PDPN
+- **Lung AT2**: SFTPC, SFTPA1
+- **Intestinal**: VIL1, MUC2
+
+### Stromal:
+- **Fibroblasts**: COL1A1, DCN, LUM
+- **Endothelial**: PECAM1 (CD31), VWF, CDH5
+- **Smooth muscle**: ACTA2, MYH11, TAGLN
+
+## Validation Checklist
+
+- [ ] Cluster purity: >80% cells with same label per cluster
+- [ ] Marker consistency: Top DE genes match expected markers
+- [ ] Biological plausibility: Expected proportions for tissue type
+- [ ] Cross-method agreement: Manual and automated annotations align
+- [ ] Reference quality: >70% cells successfully transferred
+- [ ] Doublet check: No clusters with multi-lineage markers
+- [ ] Documentation: Record confidence levels and uncertain calls
+
+## Resources
+
+### Tools:
+- **Scanpy**: https://scanpy.readthedocs.io/
+- **CellTypist**: https://www.celltypist.org/
+- **scArches**: https://scarches.readthedocs.io/
+- **Seurat**: https://satijalab.org/seurat/
+
+### References:
+- **PanglaoDB**: Database of marker genes
+- **CellMarker**: Curated cell marker database
+- **Human Cell Atlas**: Reference datasets
+
+### Pre-trained Models:
+- **CellTypist models**: 30+ tissue-specific models
+- **Azimuth references**: PBMC, lung, kidney, etc.
+- **scArches models**: Multiple tissue references
+
+## Troubleshooting
+
+**Issue**: All clusters look similar
+→ Increase clustering resolution, check if data is normalized
+
+**Issue**: Too many small clusters
+→ Decrease resolution, merge similar clusters based on markers
+
+**Issue**: Automated tool gives inconsistent results
+→ Check input normalization, try multiple tools, fall back to manual
+
+**Issue**: Can't find clear markers for cluster
+→ May be transitional state, doublet, or low-quality cells
+
+**Issue**: Reference transfer fails
+→ Check batch correction, ensure overlapping gene sets, verify tissue match

Biomanus_upload/biomni/llm.py

@@ -0,0 +1,276 @@
+import os
+from typing import TYPE_CHECKING, Literal, Optional
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+if TYPE_CHECKING:
+    from biomni.config import BiomniConfig
+
+SourceType = Literal["OpenAI", "AzureOpenAI", "Anthropic", "Ollama", "Gemini", "Bedrock", "Groq", "Custom"]
+ALLOWED_SOURCES: set[str] = set(SourceType.__args__)
+
+
+def get_llm(
+    model: str | None = None,
+    temperature: float | None = None,
+    stop_sequences: list[str] | None = None,
+    source: SourceType | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    config: Optional["BiomniConfig"] = None,
+) -> BaseChatModel:
+    """
+    Get a language model instance based on the specified model name and source.
+    This function supports models from OpenAI, Azure OpenAI, Anthropic, Ollama, Gemini, Bedrock, and custom model serving.
+    Args:
+        model (str): The model name to use
+        temperature (float): Temperature setting for generation
+        stop_sequences (list): Sequences that will stop generation
+        source (str): Source provider: "OpenAI", "AzureOpenAI", "Anthropic", "Ollama", "Gemini", "Bedrock", or "Custom"
+                      If None, will attempt to auto-detect from model name
+        base_url (str): The base URL for custom model serving (e.g., "http://localhost:8000/v1"), default is None
+        api_key (str): The API key for the custom llm
+        config (BiomniConfig): Optional configuration object. If provided, unspecified parameters will use config values
+    """
+    # Use config values for any unspecified parameters
+    if config is not None:
+        if model is None:
+            model = config.llm_model
+        if temperature is None:
+            temperature = config.temperature
+        if source is None:
+            source = config.source
+        if base_url is None:
+            base_url = config.base_url
+        if api_key is None:
+            api_key = config.api_key or "EMPTY"
+
+    # Use defaults if still not specified
+    if model is None:
+        model = "claude-3-5-sonnet-20241022"
+    if temperature is None:
+        temperature = 0.7
+    if api_key is None:
+        api_key = "EMPTY"
+    # Auto-detect source from model name if not specified
+    if source is None:
+        env_source = os.getenv("LLM_SOURCE")
+        if env_source in ALLOWED_SOURCES:
+            source = env_source
+        else:
+            if model[:7] == "claude-":
+                source = "Anthropic"
+            elif model[:7] == "gpt-oss":
+                source = "Ollama"
+            elif model[:4] == "gpt-":
+                source = "OpenAI"
+            elif model.startswith("azure-"):
+                source = "AzureOpenAI"
+            elif model[:7] == "gemini-":
+                source = "Gemini"
+            elif "groq" in model.lower():
+                source = "Groq"
+            elif base_url is not None:
+                source = "Custom"
+            elif "/" in model or any(
+                name in model.lower()
+                for name in [
+                    "llama",
+                    "mistral",
+                    "qwen",
+                    "gemma",
+                    "phi",
+                    "dolphin",
+                    "orca",
+                    "vicuna",
+                    "deepseek",
+                ]
+            ):
+                source = "Ollama"
+            elif model.startswith(
+                ("anthropic.claude-", "amazon.titan-", "meta.llama-", "mistral.", "cohere.", "ai21.", "us.")
+            ):
+                source = "Bedrock"
+            else:
+                raise ValueError("Unable to determine model source. Please specify 'source' parameter.")
+
+    # Create appropriate model based on source
+    if source == "OpenAI":
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-openai package is required for OpenAI models. Install with: pip install langchain-openai"
+            )
+        # Newer OpenAI models (e.g., gpt-5-*) require the Responses API and may reject
+        # legacy Chat Completions parameters like `stop`. Force Responses API when
+        # using gpt-5 models to avoid 400 errors such as: "Unsupported parameter: 'stop'".
+        use_responses = model.startswith("gpt-5")
+
+        if use_responses:
+            # Define a minimal subclass that drops the `stop` field when using the
+            # Responses API, since certain models (gpt-5-*) reject it entirely.
+            class _ChatOpenAIResponsesNoStop(ChatOpenAI):
+                def _get_request_payload(self, input_, *, stop=None, **kwargs):  # type: ignore[override]
+                    payload = super()._get_request_payload(input_, stop=stop, **kwargs)
+                    try:
+                        # If this call will use the Responses API, drop `stop` to avoid 400s.
+                        if hasattr(self, "_use_responses_api") and self._use_responses_api(payload):  # type: ignore[attr-defined]
+                            payload.pop("stop", None)
+                            # Also drop temperature for gpt-5 models as they only support default value
+                            payload.pop("temperature", None)
+                    except Exception:
+                        # Be conservative: if anything goes wrong, still remove `stop` and `temperature`.
+                        payload.pop("stop", None)
+                        payload.pop("temperature", None)
+                    return payload
+
+            return _ChatOpenAIResponsesNoStop(
+                model=model,
+                temperature=1,  # Set to default value for gpt-5, will be removed in payload
+                stop_sequences=stop_sequences,
+                use_responses_api=True,
+                output_version="v0",
+            )
+        else:
+            return ChatOpenAI(
+                model=model,
+                temperature=temperature,
+                stop_sequences=stop_sequences,
+            )
+
+    elif source == "AzureOpenAI":
+        try:
+            from langchain_openai import AzureChatOpenAI
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-openai package is required for Azure OpenAI models. Install with: pip install langchain-openai"
+            )
+        API_VERSION = "2024-12-01-preview"
+        model = model.replace("azure-", "")
+        return AzureChatOpenAI(
+            openai_api_key=os.getenv("OPENAI_API_KEY"),
+            azure_endpoint=os.getenv("OPENAI_ENDPOINT"),
+            azure_deployment=model,
+            openai_api_version=API_VERSION,
+            temperature=temperature,
+        )
+
+    elif source == "Anthropic":
+        try:
+            from langchain_anthropic import ChatAnthropic
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-anthropic package is required for Anthropic models. Install with: pip install langchain-anthropic"
+            )
+
+        # Ensure ANTHROPIC_API_KEY is loaded from bash_profile if not in environment
+        if not os.environ.get("ANTHROPIC_API_KEY"):
+            try:
+                import subprocess
+
+                result = subprocess.run(
+                    ["bash", "-c", "source ~/.bash_profile 2>/dev/null && echo $ANTHROPIC_API_KEY"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.stdout.strip():
+                    os.environ["ANTHROPIC_API_KEY"] = result.stdout.strip()
+                    print("✓ Loaded ANTHROPIC_API_KEY from ~/.bash_profile")
+            except Exception as e:
+                print(f"Note: Could not load ANTHROPIC_API_KEY from bash_profile: {e}")
+
+        # Newer Claude models can reject an explicit temperature parameter.
+        # Omit it and use provider defaults to keep compatibility.
+        return ChatAnthropic(
+            model=model,
+            max_tokens=8192,
+            stop_sequences=stop_sequences,
+        )
+
+    elif source == "Gemini":
+        # If you want to use ChatGoogleGenerativeAI, you need to pass the stop sequences upon invoking the model.
+        # return ChatGoogleGenerativeAI(
+        #     model=model,
+        #     temperature=temperature,
+        #     google_api_key=api_key,
+        # )
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-openai package is required for Gemini models. Install with: pip install langchain-openai"
+            )
+        return ChatOpenAI(
+            model=model,
+            temperature=temperature,
+            api_key=os.getenv("GEMINI_API_KEY"),
+            base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+            stop_sequences=stop_sequences,
+        )
+
+    elif source == "Groq":
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-openai package is required for Groq models. Install with: pip install langchain-openai"
+            )
+        return ChatOpenAI(
+            model=model,
+            temperature=temperature,
+            api_key=os.getenv("GROQ_API_KEY"),
+            base_url="https://api.groq.com/openai/v1",
+            stop_sequences=stop_sequences,
+        )
+
+    elif source == "Ollama":
+        try:
+            from langchain_ollama import ChatOllama
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-ollama package is required for Ollama models. Install with: pip install langchain-ollama"
+            )
+        return ChatOllama(
+            model=model,
+            temperature=temperature,
+        )
+
+    elif source == "Bedrock":
+        try:
+            from langchain_aws import ChatBedrock
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-aws package is required for Bedrock models. Install with: pip install langchain-aws"
+            )
+        return ChatBedrock(
+            model=model,
+            temperature=temperature,
+            stop_sequences=stop_sequences,
+            region_name=os.getenv("AWS_REGION", "us-east-1"),
+        )
+
+    elif source == "Custom":
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError:
+            raise ImportError(  # noqa: B904
+                "langchain-openai package is required for custom models. Install with: pip install langchain-openai"
+            )
+        # Custom LLM serving such as SGLang. Must expose an openai compatible API.
+        assert base_url is not None, "base_url must be provided for customly served LLMs"
+        llm = ChatOpenAI(
+            model=model,
+            temperature=temperature,
+            max_tokens=8192,
+            stop_sequences=stop_sequences,
+            base_url=base_url,
+            api_key=api_key,
+        )
+        return llm
+
+    else:
+        raise ValueError(
+            f"Invalid source: {source}. Valid options are 'OpenAI', 'AzureOpenAI', 'Anthropic', 'Gemini', 'Groq', 'Bedrock', or 'Ollama'"
+        )

Biomanus_upload/biomni/model/query_rewriter.py

@@ -0,0 +1,399 @@
+import json
+import re
+
+from langchain_core.messages import HumanMessage
+
+
+class QueryRewriter:
+    """Rewrite vague user queries into a retrieval-friendly task description."""
+
+    STOPWORDS = {
+        "a",
+        "an",
+        "and",
+        "are",
+        "as",
+        "at",
+        "be",
+        "by",
+        "for",
+        "from",
+        "how",
+        "i",
+        "in",
+        "into",
+        "is",
+        "it",
+        "me",
+        "of",
+        "on",
+        "or",
+        "our",
+        "please",
+        "show",
+        "that",
+        "the",
+        "their",
+        "this",
+        "to",
+        "use",
+        "using",
+        "want",
+        "we",
+        "what",
+        "with",
+    }
+
+    CATEGORY_KEYWORDS = {
+        "database_question_answering": {
+            "according to",
+            "gene set",
+            "msigdb",
+            "ensembl",
+            "clinvar",
+            "uniprot",
+            "pubmed",
+            "gtrd",
+            "mirdb",
+            "database",
+            "located",
+            "chromosome",
+            "geneid",
+        },
+        "sequence_question_answering": {
+            "sequence",
+            "fasta",
+            "motif",
+            "binding site",
+            "primer",
+            "reverse complement",
+            "codon",
+            "peptide",
+            "protein sequence",
+            "dna sequence",
+            "rna sequence",
+            "promoter",
+        },
+        "transcriptomics": {
+            "rna",
+            "rna-seq",
+            "bulk",
+            "differential",
+            "expression",
+            "deseq2",
+            "counts",
+        },
+        "single_cell": {
+            "single-cell",
+            "singlecell",
+            "scrna",
+            "scanpy",
+            "seurat",
+            "cell",
+            "cluster",
+        },
+        "genomics": {
+            "genome",
+            "variant",
+            "vcf",
+            "alignment",
+            "bwa",
+            "gatk",
+            "wgs",
+            "dna",
+        },
+        "pathway_enrichment": {
+            "gsea",
+            "enrichment",
+            "pathway",
+            "kegg",
+            "fgsea",
+            "clusterprofiler",
+        },
+        "statistics": {
+            "statistics",
+            "test",
+            "pvalue",
+            "qvalue",
+            "regression",
+            "significance",
+        },
+        "literature": {
+            "paper",
+            "literature",
+            "pubmed",
+            "publication",
+            "article",
+            "citation",
+        },
+        "utility": {
+            "json",
+            "csv",
+            "table",
+            "parse",
+            "transform",
+            "filter",
+            "convert",
+            "merge",
+        },
+    }
+
+    def rewrite(self, query: str, llm=None) -> dict:
+        fallback = self._build_fallback(query)
+        if llm is None:
+            return fallback
+
+        prompt = f"""
+You rewrite vague biomedical analysis requests into a retrieval-friendly task specification.
+
+Return ONLY valid JSON with these keys:
+- task_summary: short sentence
+- rewritten_query: one concise retrieval-oriented query
+- subtasks: list of concrete steps
+- keywords: list of important terms
+- server_hints: list of likely tool or server names if implied
+- categories: list of analysis categories
+- input_requirements: list of required data/input hints
+- output_requirements: list of expected outputs
+- constraints: list of runtime, environment, or quality constraints
+- ambiguities: list of unresolved ambiguities
+
+Rules:
+- Preserve the user's intent.
+- Expand vague requests into concrete analysis wording.
+- Mention likely computational steps instead of conversational phrasing.
+- Keep lists short and high-signal.
+
+USER QUERY:
+{query}
+"""
+
+        try:
+            response = llm.invoke([HumanMessage(content=prompt)])
+            content = self._extract_text(response.content)
+            parsed = self._parse_json(content)
+            if parsed:
+                merged = self._merge_with_fallback(fallback, parsed)
+                merged["retrieval_query"] = self._compose_retrieval_query(merged)
+                return merged
+        except Exception:
+            pass
+
+        return fallback
+
+    def _build_fallback(self, query: str) -> dict:
+        keywords = self._extract_keywords(query)
+        categories = self._infer_categories(keywords, query)
+        server_hints = self._infer_server_hints(keywords, query)
+        subtasks = self._infer_subtasks(query, categories)
+
+        payload = {
+            "original_query": query,
+            "task_summary": query.strip(),
+            "rewritten_query": query.strip(),
+            "subtasks": subtasks,
+            "keywords": keywords[:12],
+            "server_hints": server_hints[:10],
+            "categories": categories[:8],
+            "input_requirements": [],
+            "output_requirements": [],
+            "constraints": [],
+            "ambiguities": [],
+        }
+        payload["retrieval_query"] = self._compose_retrieval_query(payload)
+        return payload
+
+    def _merge_with_fallback(self, fallback: dict, parsed: dict) -> dict:
+        merged = dict(fallback)
+        for key in (
+            "task_summary",
+            "rewritten_query",
+            "subtasks",
+            "keywords",
+            "server_hints",
+            "categories",
+            "input_requirements",
+            "output_requirements",
+            "constraints",
+            "ambiguities",
+        ):
+            value = parsed.get(key)
+            if isinstance(value, list):
+                merged[key] = [str(item).strip() for item in value if str(item).strip()]
+            elif isinstance(value, str) and value.strip():
+                merged[key] = value.strip()
+
+        merged["keywords"] = self._merge_lists(merged.get("keywords", []), fallback.get("keywords", []), limit=14)
+        merged["server_hints"] = self._merge_lists(
+            merged.get("server_hints", []), fallback.get("server_hints", []), limit=10
+        )
+        merged["categories"] = self._merge_lists(
+            merged.get("categories", []), fallback.get("categories", []), limit=8
+        )
+        return merged
+
+    def _compose_retrieval_query(self, payload: dict) -> str:
+        parts = [
+            payload.get("rewritten_query", ""),
+            payload.get("task_summary", ""),
+            " ".join(payload.get("categories", [])),
+            " ".join(payload.get("keywords", [])),
+            " ".join(payload.get("server_hints", [])),
+            " ".join(payload.get("subtasks", [])),
+        ]
+        return " | ".join([part for part in parts if part]).strip()
+
+    def _extract_keywords(self, query: str) -> list[str]:
+        tokens = re.findall(r"[A-Za-z0-9_\-\.]{3,}", query.lower())
+        keywords = []
+        seen = set()
+        for token in tokens:
+            if token in self.STOPWORDS:
+                continue
+            if token not in seen:
+                seen.add(token)
+                keywords.append(token)
+        return keywords
+
+    def _infer_categories(self, keywords: list[str], query: str) -> list[str]:
+        text = f"{query.lower()} {' '.join(keywords)}"
+        categories = []
+        for category, hints in self.CATEGORY_KEYWORDS.items():
+            if any(hint in text for hint in hints):
+                categories.append(category)
+        db_hints = {"according to", "gene set", "msigdb", "ensembl", "clinvar", "uniprot", "mirdb", "gtrd", "omim", "disgenet"}
+        enrichment_hints = {"gsea", "enrichment", "pathway", "kegg", "fgsea", "clusterprofiler", "msigdb", "gene set"}
+        if "database_question_answering" in categories:
+            if "sequence_question_answering" in categories and not any(hint in text for hint in db_hints):
+                categories = [cat for cat in categories if cat != "database_question_answering"]
+            categories = [cat for cat in categories if cat not in {"transcriptomics", "single_cell"}]
+        if "sequence_question_answering" in categories:
+            if not any(hint in text for hint in enrichment_hints):
+                categories = [cat for cat in categories if cat != "pathway_enrichment"]
+            categories = [cat for cat in categories if cat != "single_cell"]
+        return categories or ["general_biomedical_analysis"]
+
+    def _infer_server_hints(self, keywords: list[str], query: str) -> list[str]:
+        text = f"{query.lower()} {' '.join(keywords)}"
+        hints = []
+        known = {
+            "deseq2": {"differential", "expression", "rna", "rna-seq", "counts", "deseq2"},
+            "fgsea": {"gsea", "fgsea", "enrichment", "ranked"},
+            "clusterprofiler": {"go", "kegg", "clusterprofiler", "pathway", "enrichment"},
+            "qvalue": {"qvalue", "fdr", "adjusted", "pvalue"},
+            "jq": {"json", "jq", "filter", "transform"},
+            "bwa": {"bwa", "alignment", "fastq", "genome"},
+            "gatk": {"gatk", "variant", "vcf", "germline", "somatic"},
+            "scvi": {"scvi", "single-cell", "singlecell", "latent", "integration"},
+            "bioconductor-ensembldb": {"ensembl", "chromosome", "geneid", "gene location", "transcript"},
+            "ensembl-vep": {"vep", "variant effect", "consequence", "clinvar", "variant annotation"},
+            "bioconductor-variantannotation": {"variant annotation", "dbsnp", "vcf", "rsid", "variant"},
+            "bioconductor-curatedatlasqueryr": {"cell atlas", "cell type", "tissue", "metadata query"},
+            "gseapy": {"gene set", "msigdb", "gsea", "enrichment"},
+            "bioconductor-clusterprofiler": {"gene set", "msigdb", "kegg", "go", "ontology"},
+            "gimmemotifs": {"motif", "binding site", "tfbs", "gtrd"},
+            "blast": {"blast", "homology", "alignment", "sequence"},
+            "primer3-py": {"primer", "tm", "amplicon"},
+            "pyfaidx": {"fasta", "sequence", "subsequence"},
+            "bedtools": {"bed", "interval", "genomic coordinate", "overlap"},
+            "samtools": {"samtools", "bam", "faidx", "fasta index"},
+            "ucsc-liftover": {"liftover", "assembly", "coordinate"},
+            "ucsc-twobittofa": {"2bit", "fasta", "sequence extraction"},
+        }
+        for name, patterns in known.items():
+            if any(pattern in text for pattern in patterns):
+                hints.append(name)
+        return hints
+
+    def _infer_subtasks(self, query: str, categories: list[str]) -> list[str]:
+        text = query.lower()
+        steps = []
+        if "database_question_answering" in categories:
+            steps.extend(
+                [
+                    "identify the referenced biological database or knowledge source",
+                    "retrieve the relevant annotation, gene set, or metadata entry",
+                    "compare the answer choices against the retrieved record",
+                ]
+            )
+        if "sequence_question_answering" in categories:
+            steps.extend(
+                [
+                    "identify the sequence operation implied by the question",
+                    "retrieve or derive the required sequence or coordinate fragment",
+                    "compare the answer choices against the computed sequence features",
+                ]
+            )
+        if "transcriptomics" in categories:
+            steps.extend(
+                [
+                    "load count or expression matrix",
+                    "run differential expression analysis",
+                ]
+            )
+        if "pathway_enrichment" in categories:
+            steps.extend(
+                [
+                    "rank genes or features",
+                    "run pathway or gene set enrichment",
+                ]
+            )
+        if "genomics" in categories:
+            steps.extend(
+                [
+                    "prepare reads or aligned files",
+                    "run alignment or variant calling workflow",
+                ]
+            )
+        if "single_cell" in categories:
+            steps.extend(
+                [
+                    "load annotated single-cell object",
+                    "perform clustering or annotation workflow",
+                ]
+            )
+        if "literature" in categories or "paper" in text:
+            steps.append("retrieve literature or metadata relevant to the study")
+        return self._merge_lists(steps, [], limit=8)
+
+    def _extract_text(self, response_content) -> str:
+        if isinstance(response_content, str):
+            return response_content
+        if isinstance(response_content, list):
+            parts = []
+            for item in response_content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    parts.append(str(item.get("text", "")))
+                elif isinstance(item, str):
+                    parts.append(item)
+            return "\n".join([part for part in parts if part])
+        return str(response_content)
+
+    def _parse_json(self, text: str) -> dict | None:
+        text = text.strip()
+        if not text:
+            return None
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            match = re.search(r"\{[\s\S]*\}", text)
+            if not match:
+                return None
+            try:
+                return json.loads(match.group(0))
+            except json.JSONDecodeError:
+                return None
+
+    def _merge_lists(self, primary: list[str], secondary: list[str], limit: int) -> list[str]:
+        merged = []
+        seen = set()
+        for item in list(primary) + list(secondary):
+            normalized = str(item).strip()
+            lowered = normalized.lower()
+            if not normalized or lowered in seen:
+                continue
+            seen.add(lowered)
+            merged.append(normalized)
+            if len(merged) >= limit:
+                break
+        return merged

Biomanus_upload/biomni/model/retriever.py

@@ -0,0 +1,502 @@
+import contextlib
+import re
+
+from langchain_core.messages import HumanMessage
+from langchain_openai import ChatOpenAI
+
+
+class ToolRetriever:
+    """Retrieve tools from the tool registry."""
+
+    SERVER_CATEGORY_HINTS = {
+        "transcriptomics": {
+            "deseq2",
+            "rna",
+            "rnaseq",
+            "bulk",
+            "expression",
+            "transcript",
+        },
+        "pathway_enrichment": {
+            "fgsea",
+            "gsea",
+            "clusterprofiler",
+            "pathway",
+            "go",
+            "kegg",
+            "reactome",
+        },
+        "single_cell": {
+            "singlecell",
+            "single-cell",
+            "scanpy",
+            "seurat",
+            "scvi",
+            "cell",
+            "neighborhood",
+        },
+        "genomics": {
+            "bwa",
+            "gatk",
+            "variant",
+            "genome",
+            "wgs",
+            "fastq",
+            "alignment",
+        },
+        "utility": {
+            "jq",
+            "json",
+            "csv",
+            "convert",
+            "parser",
+            "transform",
+        },
+        "literature": {
+            "pubmed",
+            "paper",
+            "literature",
+            "citation",
+        },
+    }
+
+    def __init__(self):
+        pass
+
+    def prompt_based_retrieval(self, query: str, resources: dict, llm=None) -> dict:
+        """Use a prompt-based approach to retrieve the most relevant resources for a query.
+
+        Args:
+            query: The user's query
+            resources: A dictionary with keys 'tools', 'data_lake', 'libraries', and 'know_how',
+                      each containing a list of available resources
+            llm: Optional LLM instance to use for retrieval (if None, will create a new one)
+
+        Returns:
+            A dictionary with the same keys, but containing only the most relevant resources
+
+        """
+        # Build prompt sections for available resources
+        prompt_sections = []
+        prompt_sections.append(f"""
+You are an expert biomedical research assistant. Your task is to select the relevant resources to help answer a user's query.
+
+USER QUERY: {query}
+
+Below are the available resources. For each category, select items that are directly or indirectly relevant to answering the query.
+Be generous in your selection - include resources that might be useful for the task, even if they're not explicitly mentioned in the query.
+It's better to include slightly more resources than to miss potentially useful ones.
+
+AVAILABLE TOOLS:
+{self._format_resources_for_prompt(resources.get("tools", []))}
+
+AVAILABLE DATA LAKE ITEMS:
+{self._format_resources_for_prompt(resources.get("data_lake", []))}
+
+AVAILABLE SOFTWARE LIBRARIES:
+{self._format_resources_for_prompt(resources.get("libraries", []))}""")
+
+        # Add know-how section if available
+        if "know_how" in resources and resources["know_how"]:
+            prompt_sections.append(f"""
+AVAILABLE KNOW-HOW DOCUMENTS (Best Practices & Protocols):
+{self._format_resources_for_prompt(resources.get("know_how", []))}""")
+
+        # Build response format based on available categories
+        response_format = """
+For each category, respond with ONLY the indices of the relevant items in the following format:
+TOOLS: [list of indices]
+DATA_LAKE: [list of indices]
+LIBRARIES: [list of indices]"""
+
+        if "know_how" in resources and resources["know_how"]:
+            response_format += "\nKNOW_HOW: [list of indices]"
+
+        response_format += """
+
+For example:
+TOOLS: [0, 3, 5, 7, 9]
+DATA_LAKE: [1, 2, 4]
+LIBRARIES: [0, 2, 4, 5, 8]"""
+
+        if "know_how" in resources and resources["know_how"]:
+            response_format += "\nKNOW_HOW: [0, 1]"
+
+        response_format += """
+
+If a category has no relevant items, use an empty list, e.g., DATA_LAKE: []
+
+IMPORTANT GUIDELINES:
+1. Be generous but not excessive - aim to include all potentially relevant resources
+2. ALWAYS prioritize database tools for general queries - include as many database tools as possible
+3. Include all literature search tools
+4. For wet lab sequence type of queries, ALWAYS include molecular biology tools
+5. For data lake items, include datasets that could provide useful information
+6. For libraries, include those that provide functions needed for analysis
+7. For know-how documents, include those that provide relevant protocols, best practices, or troubleshooting guidance
+8. Don't exclude resources just because they're not explicitly mentioned in the query
+9. When in doubt about a database tool or molecular biology tool, include it rather than exclude it
+"""
+
+        prompt = "\n".join(prompt_sections) + response_format
+
+        # Use the provided LLM or create a new one
+        if llm is None:
+            llm = ChatOpenAI(model="gpt-4o")
+
+        # Invoke the LLM
+        if hasattr(llm, "invoke"):
+            # For LangChain-style LLMs
+            response = llm.invoke([HumanMessage(content=prompt)])
+            response_content = response.content
+        else:
+            # For other LLM interfaces
+            response_content = str(llm(prompt))
+
+        # Parse the response to extract the selected indices
+        selected_indices = self._parse_llm_response(response_content)
+
+        # Get the selected resources
+        selected_resources = {
+            "tools": [
+                resources["tools"][i] for i in selected_indices.get("tools", []) if i < len(resources.get("tools", []))
+            ],
+            "data_lake": [
+                resources["data_lake"][i]
+                for i in selected_indices.get("data_lake", [])
+                if i < len(resources.get("data_lake", []))
+            ],
+            "libraries": [
+                resources["libraries"][i]
+                for i in selected_indices.get("libraries", [])
+                if i < len(resources.get("libraries", []))
+            ],
+        }
+
+        # Add know-how if present
+        if "know_how" in resources and resources["know_how"]:
+            selected_resources["know_how"] = [
+                resources["know_how"][i]
+                for i in selected_indices.get("know_how", [])
+                if i < len(resources.get("know_how", []))
+            ]
+
+        return selected_resources
+
+    def _format_resources_for_prompt(self, resources: list) -> str:
+        """Format resources for inclusion in the prompt."""
+        formatted = []
+        for i, resource in enumerate(resources):
+            if isinstance(resource, dict):
+                # Handle dictionary format (from tool registry or data lake/libraries with descriptions)
+                name = resource.get("name", f"Resource {i}")
+                description = resource.get("description", "")
+                formatted.append(f"{i}. {name}: {description}")
+            elif isinstance(resource, str):
+                # Handle string format (simple strings)
+                formatted.append(f"{i}. {resource}")
+            else:
+                # Try to extract name and description from tool objects
+                name = getattr(resource, "name", str(resource))
+                desc = getattr(resource, "description", "")
+                formatted.append(f"{i}. {name}: {desc}")
+
+        return "\n".join(formatted) if formatted else "None available"
+
+    def _parse_llm_response(self, response) -> dict:
+        """Parse the LLM response to extract the selected indices.
+
+        Accepts either a plain string or a Responses API-style list of content blocks.
+        """
+        # Normalize response to string if it's a list of content blocks (Responses API)
+        if isinstance(response, list):
+            parts = []
+            for item in response:
+                # LangChain Responses API returns list of dicts like {"type": "text", "text": "..."}
+                if isinstance(item, dict):
+                    if item.get("type") == "text" and "text" in item:
+                        parts.append(str(item.get("text", "")))
+                    # If it's a tool_call or other block, ignore for this simple parsing
+                elif isinstance(item, str):
+                    parts.append(item)
+            response = "\n".join([p for p in parts if p])
+        elif not isinstance(response, str):
+            response = str(response)
+        selected_indices = {"tools": [], "data_lake": [], "libraries": [], "know_how": []}
+
+        # Extract indices for each category
+        tools_match = re.search(r"TOOLS:\s*\[(.*?)\]", response, re.IGNORECASE)
+        if tools_match and tools_match.group(1).strip():
+            with contextlib.suppress(ValueError):
+                selected_indices["tools"] = [int(idx.strip()) for idx in tools_match.group(1).split(",") if idx.strip()]
+
+        data_lake_match = re.search(r"DATA_LAKE:\s*\[(.*?)\]", response, re.IGNORECASE)
+        if data_lake_match and data_lake_match.group(1).strip():
+            with contextlib.suppress(ValueError):
+                selected_indices["data_lake"] = [
+                    int(idx.strip()) for idx in data_lake_match.group(1).split(",") if idx.strip()
+                ]
+
+        libraries_match = re.search(r"LIBRARIES:\s*\[(.*?)\]", response, re.IGNORECASE)
+        if libraries_match and libraries_match.group(1).strip():
+            with contextlib.suppress(ValueError):
+                selected_indices["libraries"] = [
+                    int(idx.strip()) for idx in libraries_match.group(1).split(",") if idx.strip()
+                ]
+
+        # Extract know-how indices
+        know_how_match = re.search(r"KNOW[-_]HOW:\s*\[(.*?)\]", response, re.IGNORECASE)
+        if know_how_match and know_how_match.group(1).strip():
+            with contextlib.suppress(ValueError):
+                selected_indices["know_how"] = [
+                    int(idx.strip()) for idx in know_how_match.group(1).split(",") if idx.strip()
+                ]
+
+        return selected_indices
+
+    def build_mcp_server_entry(self, server_name: str, safe_server_name: str, tools: list, server_meta: dict) -> dict:
+        """Build a retrieval document for one MCP server."""
+        normalized_tools = []
+        for tool in tools:
+            if not isinstance(tool, dict):
+                continue
+            normalized_tools.append(
+                {
+                    "name": tool.get("name") or tool.get("biomni_name") or "unknown_tool",
+                    "description": tool.get("description", ""),
+                    "inputSchema": tool.get(
+                        "inputSchema",
+                        {"properties": tool.get("parameters", {}), "required": []},
+                    ),
+                }
+            )
+
+        combined_text = " ".join(
+            [
+                server_name,
+                safe_server_name,
+                server_meta.get("description", ""),
+                " ".join(tool.get("name", "") for tool in normalized_tools),
+                " ".join(tool.get("description", "") for tool in normalized_tools),
+            ]
+        )
+        tokens = self._tokenize(combined_text)
+        category = self._infer_server_category(combined_text, tokens)
+        summary = (
+            server_meta.get("description")
+            or f"MCP server {server_name} with tools: "
+            + ", ".join(tool.get("name", "") for tool in normalized_tools[:8])
+        ).strip()
+
+        return {
+            "name": server_name,
+            "safe_name": safe_server_name,
+            "module": f"mcp_servers.{safe_server_name}",
+            "category": category,
+            "summary": summary,
+            "keywords": list(tokens)[:40],
+            "tools": normalized_tools,
+            "tool_names": [tool["name"] for tool in normalized_tools],
+            "server_meta": server_meta,
+            "score": 0.0,
+        }
+
+    def hybrid_server_retrieval(
+        self,
+        query_context: dict,
+        server_entries: list[dict],
+        llm=None,
+        top_k: int = 8,
+        candidate_pool: int = 24,
+    ) -> list[dict]:
+        """Select relevant MCP servers with lexical scoring plus optional LLM reranking."""
+        if not server_entries:
+            return []
+
+        scored = []
+        for idx, entry in enumerate(server_entries):
+            score = self._score_server_entry(query_context, entry)
+            enriched = dict(entry)
+            enriched["score"] = score
+            scored.append((score, idx, enriched))
+
+        scored.sort(key=lambda item: item[0], reverse=True)
+        shortlisted = [entry for _, _, entry in scored[: max(top_k, candidate_pool)]]
+
+        selected = self._llm_rerank_servers(query_context, shortlisted, top_k=top_k, llm=llm)
+        if selected:
+            return selected
+        return shortlisted[:top_k]
+
+    def hybrid_tool_selection(
+        self,
+        query_context: dict,
+        tools: list[dict],
+        llm=None,
+        top_k: int = 12,
+    ) -> list[dict]:
+        """Select high-signal tools inside a shortlisted MCP server."""
+        if len(tools) <= top_k:
+            return tools
+
+        scored = []
+        for idx, tool in enumerate(tools):
+            score = self._score_tool_entry(query_context, tool)
+            scored.append((score, idx, tool))
+        scored.sort(key=lambda item: item[0], reverse=True)
+        shortlisted = [tool for _, _, tool in scored[: max(top_k * 2, top_k)]]
+
+        selected = self._llm_rerank_tools(query_context, shortlisted, top_k=top_k, llm=llm)
+        if selected:
+            return selected
+        return shortlisted[:top_k]
+
+    def _score_server_entry(self, query_context: dict, entry: dict) -> float:
+        query_tokens = self._tokenize(self._query_text(query_context))
+        if not query_tokens:
+            return 0.0
+
+        server_tokens = set(entry.get("keywords", [])) | self._tokenize(entry.get("summary", ""))
+        overlap = len(query_tokens & server_tokens)
+        score = float(overlap)
+
+        server_name = entry.get("name", "").lower()
+        category = entry.get("category", "").lower()
+
+        for hint in query_context.get("server_hints", []):
+            hint_l = str(hint).lower()
+            if hint_l and hint_l in server_name:
+                score += 5.0
+
+        for category_hint in query_context.get("categories", []):
+            if str(category_hint).lower() == category:
+                score += 3.0
+
+        tool_names = " ".join(entry.get("tool_names", [])).lower()
+        for token in query_tokens:
+            if token in server_name:
+                score += 2.5
+            if token in tool_names:
+                score += 1.0
+
+        return score
+
+    def _score_tool_entry(self, query_context: dict, tool: dict) -> float:
+        query_tokens = self._tokenize(self._query_text(query_context))
+        tool_text = " ".join([tool.get("name", ""), tool.get("description", "")])
+        tool_tokens = self._tokenize(tool_text)
+        overlap = len(query_tokens & tool_tokens)
+        score = float(overlap)
+
+        for token in query_tokens:
+            if token in tool.get("name", "").lower():
+                score += 2.0
+
+        for hint in query_context.get("server_hints", []):
+            hint_l = str(hint).lower()
+            if hint_l and hint_l in tool_text.lower():
+                score += 2.5
+
+        return score
+
+    def _llm_rerank_servers(self, query_context: dict, candidates: list[dict], top_k: int, llm=None) -> list[dict]:
+        if llm is None or not candidates:
+            return []
+
+        lines = []
+        for idx, candidate in enumerate(candidates):
+            lines.append(
+                f"{idx}. {candidate['name']} | category={candidate.get('category', 'unknown')} | "
+                f"tools={', '.join(candidate.get('tool_names', [])[:8])} | summary={candidate.get('summary', '')}"
+            )
+
+        prompt = f"""
+Select the most relevant MCP servers for this query.
+
+QUERY:
+{self._query_text(query_context)}
+
+SERVER CANDIDATES:
+{chr(10).join(lines)}
+
+Return ONLY:
+SERVERS: [indices]
+
+Choose at most {top_k} servers.
+Prefer precise servers over broad but irrelevant ones.
+"""
+        try:
+            response = llm.invoke([HumanMessage(content=prompt)])
+            content = response.content if hasattr(response, "content") else str(response)
+            text = self._normalize_text(content)
+            match = re.search(r"SERVERS:\s*\[(.*?)\]", text, re.IGNORECASE)
+            if not match:
+                return []
+            indices = [int(idx.strip()) for idx in match.group(1).split(",") if idx.strip()]
+            return [candidates[idx] for idx in indices if 0 <= idx < len(candidates)]
+        except Exception:
+            return []
+
+    def _llm_rerank_tools(self, query_context: dict, candidates: list[dict], top_k: int, llm=None) -> list[dict]:
+        if llm is None or not candidates:
+            return []
+
+        lines = []
+        for idx, tool in enumerate(candidates):
+            lines.append(f"{idx}. {tool.get('name', 'unknown')}: {tool.get('description', '')}")
+
+        prompt = f"""
+Select the most relevant MCP tools for this query.
+
+QUERY:
+{self._query_text(query_context)}
+
+TOOL CANDIDATES:
+{chr(10).join(lines)}
+
+Return ONLY:
+TOOLS: [indices]
+
+Choose at most {top_k} tools.
+"""
+        try:
+            response = llm.invoke([HumanMessage(content=prompt)])
+            content = response.content if hasattr(response, "content") else str(response)
+            text = self._normalize_text(content)
+            match = re.search(r"TOOLS:\s*\[(.*?)\]", text, re.IGNORECASE)
+            if not match:
+                return []
+            indices = [int(idx.strip()) for idx in match.group(1).split(",") if idx.strip()]
+            return [candidates[idx] for idx in indices if 0 <= idx < len(candidates)]
+        except Exception:
+            return []
+
+    def _infer_server_category(self, text: str, tokens: set[str]) -> str:
+        lowered = text.lower()
+        for category, hints in self.SERVER_CATEGORY_HINTS.items():
+            if any(hint in lowered for hint in hints) or tokens.intersection(hints):
+                return category
+        return "general"
+
+    def _query_text(self, query_context: dict) -> str:
+        if not isinstance(query_context, dict):
+            return str(query_context)
+        return query_context.get("retrieval_query") or query_context.get("rewritten_query") or query_context.get(
+            "original_query", ""
+        )
+
+    def _tokenize(self, text: str) -> set[str]:
+        return {token for token in re.findall(r"[a-zA-Z0-9_\-\.]{3,}", str(text).lower())}
+
+    def _normalize_text(self, content) -> str:
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts = []
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    parts.append(str(item.get("text", "")))
+                elif isinstance(item, str):
+                    parts.append(item)
+            return "\n".join([part for part in parts if part])
+        return str(content)

Biomanus_upload/biomni/task/base_task.py

@@ -0,0 +1,18 @@
+class base_task:
+    def __init__(self):
+        pass
+
+    def get_example(self):
+        pass
+
+    def get_iterator(self):
+        pass
+
+    def evaluate(self):
+        pass
+
+    def output_class(self):
+        pass
+
+    def get_prompt_from_input(self, input):
+        return self.get_example(input)["prompt"]

Biomanus_upload/biomni/task/hle.py

@@ -0,0 +1,146 @@
+import numpy as np
+import pandas as pd
+
+from biomni.task.base_task import base_task
+
+np.random.seed(42)
+
+
+def shuffle(x):
+    np.random.shuffle(x)
+    return x
+
+
+class humanity_last_exam(base_task):
+    def __init__(self, path="./data", category="Biology/Medicine", answer_type="multipleChoice"):
+        if category not in [
+            "Other",
+            "Humanities/Social Science",
+            "Math",
+            "Physics",
+            "Computer Science/AI",
+            "Biology/Medicine",
+            "Chemistry",
+            "Engineering",
+        ]:
+            raise ValueError(
+                "category must be one of ['Other', 'Humanities/Social Science', 'Math', 'Physics', 'Computer Science/AI', 'Biology/Medicine', 'Chemistry', 'Engineering']"
+            )
+        if answer_type not in ["exactMatch", "multipleChoice"]:
+            raise ValueError("answer_type must be one of ['exactMatch' or 'multipleChoice']")
+
+        self.dataset = category  # Store dataset type
+        self.answer_type = answer_type
+        df = pd.read_parquet(path + "/hle/test_sampled_biology_medicine.parquet")
+
+        # Extract answer choices from question text
+        def extract_options(question):
+            # Find the "Answer Choices:" section
+            if "Answer Choices:" not in question:
+                return []
+            choices = question.split("Answer Choices:")[1].strip()
+
+            # Split on A., B., C. etc and clean up
+            options = []
+            letters = [
+                "A.",
+                "B.",
+                "C.",
+                "D.",
+                "E.",
+                "F.",
+                "G.",
+                "H.",
+                "I.",
+                "J.",
+                "K.",
+                "L.",
+                "M.",
+                "N.",
+                "O.",
+                "P.",
+                "Q.",
+                "R.",
+                "S.",
+                "T.",
+                "U.",
+                "V.",
+                "W.",
+                "X.",
+                "Y.",
+                "Z.",
+            ]
+            for i, letter in enumerate(letters):
+                if letter in choices:
+                    # Define the next letter if available
+                    next_letter = letters[i + 1] if i + 1 < len(letters) else None
+
+                    # Split between current letter and next letter
+                    parts = choices.split(letter)[1]
+                    if next_letter and next_letter in parts:
+                        option = parts.split(next_letter)[0].strip()
+                    else:
+                        option = parts.strip()
+
+                    options.append(option)
+            return options
+
+        def extract_question(question):
+            return question.split("Answer Choices:")[0].strip()
+
+        # Extract options and answers only for multiple choice questions and category is the same as the dataset
+        df = df[df["category"] == self.dataset]
+        df = df[df["answer_type"] == "multipleChoice"]
+        df["question_text"] = df.question
+        df["letter_answer"] = df["answer"].apply(lambda x: x[0])
+
+        self.query = df.question_text.values
+        # self.options = df.options_letters.values
+        self.answer = df.letter_answer.values
+
+        self.prompt = """Question: {question}"""
+
+    def get_example(self, index=None):
+        if index is None:
+            index = np.random.randint(len(self.query))
+
+        return {
+            "prompt": self.prompt.format(
+                question=self.query[index],
+                # options = self.options[index]
+            ),
+            "answer": self.answer[index],
+        }
+
+    def get_iterator(self):
+        for i in range(len(self.query)):
+            yield self.get_example(i)
+
+    def evaluate(self, response):
+        ## expected a list/array of symbols
+        from sklearn.metrics import accuracy_score
+
+        ground_truth = self.answer
+        response = np.array(response)
+
+        return {
+            "accuracy": accuracy_score(ground_truth, response),
+            "coverage": np.mean(response != self.refrain_label),
+            "refrain_ratio": np.mean(response == self.refrain_label),
+            "precision": accuracy_score(
+                ground_truth[np.where(response != self.refrain_label)],
+                response[np.where(response != self.refrain_label)],
+            ),
+        }
+
+    def output_class(self):
+        from pydantic import BaseModel, Field
+
+        class MultipleChoiceOutput(BaseModel):
+            """Multiple choice output."""
+
+            choice: str | None = Field(
+                description="Multiple choice answer. For example, if there is <answer>A</answer> in the prompt, the output should be 'A'."
+            )
+
+        return MultipleChoiceOutput

Biomanus_upload/biomni/task/lab_bench.py

@@ -0,0 +1,115 @@
+import numpy as np
+import pandas as pd
+
+from biomni.task.base_task import base_task
+
+np.random.seed(42)
+
+
+def shuffle(x):
+    np.random.shuffle(x)
+    return x
+
+
+class lab_bench(base_task):
+    def __init__(self, path="./data", dataset="DbQA"):
+        if dataset not in ["DbQA", "SeqQA"]:
+            raise ValueError("dataset must be one of 'DbQA', 'SeqQA'")
+
+        self.dataset = dataset  # Store dataset type
+        df = pd.read_parquet(path + "/" + dataset + "/train-00000-of-00001_test.parquet")
+
+        self.prompt = """The following is a multiple choice question about biology.
+Please answer by responding with the letter of the correct answer.
+
+Question: {question}
+Options:
+{options}
+
+You MUST include the letter of the correct answer within the following tags:
+[ANSWER] and [/ANSWER]. For example, '[ANSWER]<answer>[/ANSWER]',
+where <answer> is the correct letter. Always answer in exactly this format
+of a single letter between the two tags, even if you are unsure.
+We require this because we use automatic parsing.
+            """
+
+        np.random.seed(42)
+        df["options"] = df.apply(
+            lambda x: shuffle(
+                x.distractors.tolist() + [x.ideal] + ["Insufficient information to answer the question."]
+            ),
+            axis=1,
+        )
+        df["options_letters"] = df.options.apply(
+            lambda x: "\n".join([chr(ord("A") + i) + "." + item for i, item in enumerate(x)])
+        )
+        df["letter_answer"] = df.apply(
+            lambda x: chr(ord("A") + np.where(np.array(x.options) == x.ideal)[0][0]),
+            axis=1,
+        )
+        df["letter_refrain"] = df.apply(
+            lambda x: chr(
+                ord("A") + np.where(np.array(x.options) == "Insufficient information to answer the question.")[0][0]
+            ),
+            axis=1,
+        )
+
+        self.query = df.question.values
+        self.options = df.options_letters.values
+        self.answer = df.letter_answer.values
+        self.refrain_label = df.letter_refrain.values
+
+        # Store protocol information if available
+        self.protocol = df.protocol.values if "protocol" in df.columns else None
+
+    def get_example(self, index=None):
+        if index is None:
+            index = np.random.randint(len(self.query))
+
+        if self.dataset == "ProtocolQA" and self.protocol is not None:
+            return {
+                "prompt": self.prompt.format(
+                    protocol=self.protocol[index],
+                    question=self.query[index],
+                    options=self.options[index],
+                ),
+                "answer": self.answer[index],
+            }
+        else:
+            return {
+                "prompt": self.prompt.format(question=self.query[index], options=self.options[index]),
+                "answer": self.answer[index],
+            }
+
+    def get_iterator(self):
+        for i in range(len(self.query)):
+            yield self.get_example(i)
+
+    def evaluate(self, response):
+        ## expected a list/array of symbols
+        from sklearn.metrics import accuracy_score
+
+        ground_truth = self.answer
+        response = np.array(response)
+
+        return {
+            "accuracy": accuracy_score(ground_truth, response),
+            "coverage": np.mean(response != self.refrain_label),
+            "refrain_ratio": np.mean(response == self.refrain_label),
+            "precision": accuracy_score(
+                ground_truth[np.where(response != self.refrain_label)],
+                response[np.where(response != self.refrain_label)],
+            ),
+        }
+
+    def output_class(self):
+        from pydantic import BaseModel, Field
+
+        class MultipleChoiceOutput(BaseModel):
+            """Multiple choice output."""
+
+            choice: str | None = Field(
+                description="Multiple choice answer. For example, if there is <answer>A</answer> in the prompt, the output should be 'A'."
+            )
+
+        return MultipleChoiceOutput

Biomanus_upload/biomni/tool/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from biomni.utils import get_tool_decorated_functions  # noqa: F401
+except ModuleNotFoundError:  # pragma: no cover
+    get_tool_decorated_functions = None  # type: ignore

Biomanus_upload/biomni/tool/biochemistry.py

@@ -0,0 +1,1026 @@
+def analyze_circular_dichroism_spectra(
+    sample_name,
+    sample_type,
+    wavelength_data,
+    cd_signal_data,
+    temperature_data=None,
+    thermal_cd_data=None,
+    output_dir="./",
+):
+    """Analyzes circular dichroism (CD) spectroscopy data to determine secondary structure and thermal stability.
+
+    Parameters
+    ----------
+    sample_name : str
+        Name of the biomolecule sample (e.g., "Znf706", "G-quadruplex")
+    sample_type : str
+        Type of biomolecule ("protein" or "nucleic_acid")
+    wavelength_data : list or numpy.ndarray
+        Wavelength values in nm for CD spectrum
+    cd_signal_data : list or numpy.ndarray
+        CD signal intensity values (typically in mdeg or Δε)
+    temperature_data : list or numpy.ndarray, optional
+        Temperature values (°C) for thermal denaturation experiment
+    thermal_cd_data : list or numpy.ndarray, optional
+        CD signal values at specific wavelength across different temperatures
+    output_dir : str, optional
+        Directory to save result files, defaults to current directory
+
+    Returns
+    -------
+    str
+        Research log summarizing the CD analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import numpy as np
+
+    # Initialize research log
+    log = f"# Circular Dichroism Analysis Report for {sample_name}\n"
+    log += f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+    log += "## Sample Information\n"
+    log += f"- Sample Name: {sample_name}\n"
+    log += f"- Sample Type: {sample_type}\n\n"
+
+    # Convert inputs to numpy arrays if they aren't already
+    wavelength_data = np.array(wavelength_data)
+    cd_signal_data = np.array(cd_signal_data)
+
+    # Ensure output directory exists
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # 1. Analyze CD spectrum for secondary structure
+    log += "## Secondary Structure Analysis\n"
+
+    # Different analysis approaches based on sample type
+    if sample_type.lower() == "protein":
+        # Analyze protein secondary structure based on characteristic spectral features
+        alpha_helix_signal = np.sum((wavelength_data >= 190) & (wavelength_data <= 195) & (cd_signal_data > 0))
+        beta_sheet_signal = np.sum((wavelength_data >= 215) & (wavelength_data <= 220) & (cd_signal_data < 0))
+        random_coil_signal = np.sum((wavelength_data >= 195) & (wavelength_data <= 200) & (cd_signal_data < 0))
+
+        # Simple classification based on signal patterns
+        if alpha_helix_signal > beta_sheet_signal and alpha_helix_signal > random_coil_signal:
+            structure = "predominantly alpha-helical"
+        elif beta_sheet_signal > alpha_helix_signal and beta_sheet_signal > random_coil_signal:
+            structure = "predominantly beta-sheet"
+        else:
+            structure = "mixed or predominantly random coil"
+
+        log += f"- The CD spectrum indicates {structure} structure for {sample_name}.\n"
+        log += "- Key spectral features:\n"
+        log += "  - 190-195 nm region: associated with alpha-helical content\n"
+        log += "  - 215-220 nm region: associated with beta-sheet content\n\n"
+
+    elif sample_type.lower() == "nucleic_acid":
+        # Analyze nucleic acid structure (e.g., G-quadruplex has characteristic positive peak ~295 nm)
+        g_quadruplex_signal = np.sum((wavelength_data >= 290) & (wavelength_data <= 300) & (cd_signal_data > 0))
+        b_form_signal = np.sum((wavelength_data >= 270) & (wavelength_data <= 280) & (cd_signal_data > 0))
+
+        if g_quadruplex_signal > 0:
+            structure = "G-quadruplex characteristics"
+        elif b_form_signal > 0:
+            structure = "B-form characteristics"
+        else:
+            structure = "non-standard structure"
+
+        log += f"- The CD spectrum indicates {structure} for {sample_name}.\n"
+        log += "- Key spectral features:\n"
+        log += "  - 290-300 nm positive peak: characteristic of G-quadruplex structures\n"
+        log += "  - 270-280 nm positive peak: characteristic of B-form DNA\n\n"
+
+    # Save spectral data results
+    spectral_file = os.path.join(output_dir, f"{sample_name}_cd_spectrum_analysis.txt")
+    with open(spectral_file, "w") as f:
+        f.write("Wavelength (nm)\tCD Signal\n")
+        for wl, signal in zip(wavelength_data, cd_signal_data, strict=False):
+            f.write(f"{wl:.1f}\t{signal:.4f}\n")
+
+    log += f"- Detailed spectral data saved to: {spectral_file}\n\n"
+
+    # 2. Thermal stability analysis (if temperature data provided)
+    if temperature_data is not None and thermal_cd_data is not None:
+        temperature_data = np.array(temperature_data)
+        thermal_cd_data = np.array(thermal_cd_data)
+
+        log += "## Thermal Stability Analysis\n"
+
+        # Simple Tm estimation (melting temperature) - find temperature at 50% unfolding
+        # Normalize thermal data to 0-1 range for unfolding fraction
+        min_signal = np.min(thermal_cd_data)
+        max_signal = np.max(thermal_cd_data)
+        unfolded_fraction = (thermal_cd_data - min_signal) / (max_signal - min_signal)
+
+        # Find the temperature closest to 50% unfolding
+        tm_idx = np.argmin(np.abs(unfolded_fraction - 0.5))
+        tm = temperature_data[tm_idx]
+
+        log += f"- Estimated melting temperature (Tm): {tm:.1f}°C\n"
+
+        # Cooperativity assessment (crude estimate based on transition steepness)
+        t_range = temperature_data[-1] - temperature_data[0]
+        transition_width = (
+            t_range / len(temperature_data) * np.sum((unfolded_fraction > 0.2) & (unfolded_fraction < 0.8))
+        )
+
+        if transition_width < 0.2 * t_range:
+            cooperativity = "highly cooperative (sharp transition)"
+        elif transition_width < 0.4 * t_range:
+            cooperativity = "moderately cooperative"
+        else:
+            cooperativity = "non-cooperative (broad transition)"
+
+        log += f"- Thermal transition: {cooperativity}\n"
+
+        # Save thermal denaturation data
+        thermal_file = os.path.join(output_dir, f"{sample_name}_thermal_denaturation.txt")
+        with open(thermal_file, "w") as f:
+            f.write("Temperature (°C)\tCD Signal\tUnfolded Fraction\n")
+            for temp, signal, unfold in zip(temperature_data, thermal_cd_data, unfolded_fraction, strict=False):
+                f.write(f"{temp:.1f}\t{signal:.4f}\t{unfold:.4f}\n")
+
+        log += f"- Thermal denaturation data saved to: {thermal_file}\n\n"
+
+    # 3. Summary and conclusions
+    log += "## Conclusions\n"
+    if sample_type.lower() == "protein":
+        log += f"- {sample_name} shows {structure} according to CD spectroscopy.\n"
+    else:
+        log += f"- {sample_name} exhibits {structure} according to CD spectroscopy.\n"
+
+    if temperature_data is not None:
+        log += f"- The molecule has a melting temperature of {tm:.1f}°C with {cooperativity}.\n"
+
+    return log
+
+
+def analyze_rna_secondary_structure_features(dot_bracket_structure, sequence=None):
+    """Calculate numeric values for various structural features of an RNA secondary structure.
+
+    Parameters
+    ----------
+    dot_bracket_structure : str
+        RNA secondary structure in dot-bracket notation (e.g., "(((...)))").
+        Parentheses represent base pairs, dots represent unpaired bases.
+    sequence : str, optional
+        The RNA sequence corresponding to the structure. If provided,
+        sequence-dependent energy calculations will be performed.
+
+    Returns
+    -------
+    str
+        A research log summarizing the calculated structural features and analysis steps.
+
+    """
+    # Initialize research log
+    log = "# RNA Secondary Structure Feature Analysis\n\n"
+
+    # Validate input
+    if not all(c in "().[]{}" for c in dot_bracket_structure):
+        return "Error: Invalid dot-bracket notation. Use only '()', '[]', '{}', and '.'"
+
+    log += f"Input structure (length: {len(dot_bracket_structure)}): {dot_bracket_structure}\n"
+    if sequence:
+        log += f"Input sequence (length: {len(sequence)}): {sequence}\n"
+        if len(sequence) != len(dot_bracket_structure):
+            return "Error: Sequence and structure lengths do not match."
+
+    # Extract base pairs
+    pairs = []
+    stack = []
+
+    for i, char in enumerate(dot_bracket_structure):
+        if char in "([{":
+            stack.append((i, char))
+        elif char in ")]}":
+            if not stack:
+                return "Error: Unbalanced structure. More closing than opening brackets."
+
+            j, opening_char = stack.pop()
+            # Check for matching bracket types
+            if (
+                (opening_char == "(" and char != ")")
+                or (opening_char == "[" and char != "]")
+                or (opening_char == "{" and char != "}")
+            ):
+                return "Error: Mismatched bracket types. Opening and closing brackets must match."
+
+            pairs.append((j, i))
+
+    if stack:
+        return "Error: Unbalanced structure. More opening than closing brackets."
+
+    # Sort pairs by position
+    pairs.sort()
+
+    # Identify stems (consecutive base pairs)
+    stems = []
+    current_stem = []
+
+    for i, (start, end) in enumerate(pairs):
+        if (i == 0 or start != pairs[i - 1][0] + 1 or end != pairs[i - 1][1] - 1) and current_stem:
+            stems.append(current_stem)
+            current_stem = []
+        current_stem.append((start, end))
+
+    if current_stem:
+        stems.append(current_stem)
+
+    # Calculate stem lengths
+    stem_lengths = [len(stem) for stem in stems]
+
+    # Calculate loop sizes
+    loops = []
+    for i in range(len(stems)):
+        stem = stems[i]
+        last_pair = stem[-1]
+        next_stem_start = stems[i + 1][0][0] if i < len(stems) - 1 else len(dot_bracket_structure)
+        loop_size = next_stem_start - last_pair[1] - 1
+        if loop_size > 0:
+            loops.append(loop_size)
+
+    # Calculate base pair statistics
+    total_paired_bases = len(pairs) * 2
+    total_unpaired_bases = len(dot_bracket_structure) - total_paired_bases
+
+    # Calculate simplified free energy if sequence is provided
+    stem_energies = []
+    if sequence and len(stems) > 0:
+        # Simplified energy parameters for nearest-neighbor model
+        # Values are approximate and simplified for illustration
+        energy_params = {
+            "AU": -0.9,
+            "UA": -0.9,
+            "GC": -2.1,
+            "CG": -2.1,
+            "GU": -0.5,
+            "UG": -0.5,
+        }
+
+        for stem in stems:
+            stem_energy = 0
+            for start, end in stem:
+                if start < len(sequence) and end < len(sequence):
+                    pair = sequence[start] + sequence[end]
+                    stem_energy += energy_params.get(pair, 0)
+            stem_energies.append(stem_energy)
+
+    # Prepare results
+    log += "\n## Structural Features\n\n"
+    log += f"Total base pairs: {len(pairs)}\n"
+    log += f"Number of stems: {len(stems)}\n"
+    log += f"Longest stem length: {max(stem_lengths) if stem_lengths else 0}\n"
+    log += f"Average stem length: {sum(stem_lengths) / len(stem_lengths) if stem_lengths else 0:.2f}\n"
+    log += f"Paired bases: {total_paired_bases} ({total_paired_bases / len(dot_bracket_structure) * 100:.1f}%)\n"
+    log += f"Unpaired bases: {total_unpaired_bases} ({total_unpaired_bases / len(dot_bracket_structure) * 100:.1f}%)\n"
+
+    if loops:
+        log += f"Number of loops: {len(loops)}\n"
+        log += f"Average loop size: {sum(loops) / len(loops):.2f}\n"
+        log += f"Largest loop size: {max(loops)}\n"
+
+    if sequence and stem_energies:
+        log += "\n## Energy Calculations\n\n"
+        log += f"Total estimated free energy: {sum(stem_energies):.2f} kcal/mol\n"
+
+        if len(stems) >= 2:
+            log += f"Upstream stem free energy: {stem_energies[0]:.2f} kcal/mol\n"
+            log += f"Downstream stem free energy: {stem_energies[-1]:.2f} kcal/mol\n"
+
+        # If the first stem is the "zipper" stem
+        if stem_lengths and stem_lengths[0] >= 3:
+            log += f"Zipper stem free energy: {stem_energies[0]:.2f} kcal/mol\n"
+
+    log += "\n## Stem Details\n\n"
+    for i, stem in enumerate(stems):
+        log += f"Stem {i + 1}: {len(stem)} base pairs\n"
+        log += f"  Positions: {stem[0][0]}-{stem[0][1]} to {stem[-1][0]}-{stem[-1][1]}\n"
+        if sequence and i < len(stem_energies):
+            log += f"  Estimated stability: {stem_energies[i]:.2f} kcal/mol\n"
+
+    return log
+
+
+def analyze_protease_kinetics(
+    time_points,
+    fluorescence_data,
+    substrate_concentrations,
+    enzyme_concentration,
+    output_prefix="protease_kinetics",
+    output_dir="./",
+):
+    """Analyze protease kinetics data from fluorogenic peptide cleavage assays.
+
+    This function processes time-course fluorescence data from protease-mediated peptide
+    cleavage assays, fits the data to Michaelis-Menten kinetics, and determines key
+    kinetic parameters (kcat, KM, and catalytic efficiency).
+
+    Parameters
+    ----------
+    time_points : numpy.ndarray
+        Array of time points (in seconds) at which measurements were taken
+
+    fluorescence_data : numpy.ndarray
+        2D array of fluorescence measurements where each row corresponds to a different
+        substrate concentration and each column corresponds to a time point
+
+    substrate_concentrations : numpy.ndarray
+        Array of substrate concentrations (in μM) corresponding to each row in fluorescence_data
+
+    enzyme_concentration : float
+        Concentration of the protease enzyme (in μM)
+
+    output_prefix : str, optional
+        Prefix for output files (default: "protease_kinetics")
+
+    output_dir : str, optional
+        Directory to save output files (default: "./")
+
+    Returns
+    -------
+    str
+        A research log summarizing the analysis steps and results
+
+    """
+    import os
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from scipy.optimize import curve_fit
+
+    # Ensure output directory exists
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Create full output paths
+    plot_filename = os.path.join(output_dir, f"{output_prefix}_mm_plot.png")
+    results_filename = os.path.join(output_dir, f"{output_prefix}_results.txt")
+
+    # Step 1: Calculate initial velocities for each substrate concentration
+    initial_velocities = np.zeros(len(substrate_concentrations))
+
+    for i, fluorescence_curve in enumerate(fluorescence_data):
+        # Linear fit to the initial portion of the curve (first 20% of time points or at least 5 points)
+        num_points = max(5, int(len(time_points) * 0.2))
+        slope, _ = np.polyfit(time_points[:num_points], fluorescence_curve[:num_points], 1)
+        initial_velocities[i] = slope
+
+    # Step 2: Define Michaelis-Menten equation for curve fitting
+    def michaelis_menten(s, vmax, km):
+        return vmax * s / (km + s)
+
+    # Step 3: Fit the data to the Michaelis-Menten equation
+    try:
+        params, covariance = curve_fit(
+            michaelis_menten,
+            substrate_concentrations,
+            initial_velocities,
+            p0=[max(initial_velocities), np.mean(substrate_concentrations)],
+            bounds=([0, 0], [np.inf, np.inf]),
+        )
+
+        vmax, km = params
+        std_dev = np.sqrt(np.diag(covariance))
+        vmax_std, km_std = std_dev
+
+        # Step 4: Calculate kcat and catalytic efficiency
+        kcat = vmax / enzyme_concentration
+        kcat_std = vmax_std / enzyme_concentration
+        catalytic_efficiency = kcat / km
+        catalytic_efficiency_std = catalytic_efficiency * np.sqrt((kcat_std / kcat) ** 2 + (km_std / km) ** 2)
+
+        # Step 5: Create a plot and save it
+        plt.figure(figsize=(10, 6))
+        plt.scatter(
+            substrate_concentrations,
+            initial_velocities,
+            color="blue",
+            label="Experimental data",
+        )
+
+        # Generate smooth curve for the fitted model
+        s_curve = np.linspace(0, max(substrate_concentrations) * 1.2, 100)
+        v_curve = michaelis_menten(s_curve, vmax, km)
+        plt.plot(s_curve, v_curve, "r-", label="Michaelis-Menten fit")
+
+        plt.xlabel("Substrate Concentration (μM)")
+        plt.ylabel("Initial Velocity (a.u./s)")
+        plt.title("Michaelis-Menten Kinetics")
+        plt.legend()
+        plt.grid(True, alpha=0.3)
+
+        plt.savefig(plot_filename)
+        plt.close()
+
+        # Step 6: Save numerical results to a file
+        with open(results_filename, "w") as f:
+            f.write("Protease Kinetics Analysis Results\n")
+            f.write("==================================\n\n")
+            f.write(f"Vmax: {vmax:.4f} ± {vmax_std:.4f} a.u./s\n")
+            f.write(f"KM: {km:.4f} ± {km_std:.4f} μM\n")
+            f.write(f"kcat: {kcat:.4f} ± {kcat_std:.4f} s^-1\n")
+            f.write(
+                f"Catalytic efficiency (kcat/KM): {catalytic_efficiency:.4f} ± {catalytic_efficiency_std:.4f} μM^-1 s^-1\n"
+            )
+
+        # Step 7: Create research log
+        research_log = f"""
+Protease Kinetics Analysis Research Log
+======================================
+
+Analysis Steps:
+1. Calculated initial velocities from time-course fluorescence data for {len(substrate_concentrations)} different substrate concentrations
+2. Fitted initial velocities to the Michaelis-Menten equation using non-linear regression
+3. Determined kinetic parameters and their uncertainties
+
+Results:
+- Vmax: {vmax:.4f} ± {vmax_std:.4f} a.u./s
+- KM: {km:.4f} ± {km_std:.4f} μM
+- kcat: {kcat:.4f} ± {kcat_std:.4f} s^-1
+- Catalytic efficiency (kcat/KM): {catalytic_efficiency:.4f} ± {catalytic_efficiency_std:.4f} μM^-1 s^-1
+
+Files Generated:
+1. {plot_filename} - Michaelis-Menten plot showing experimental data and fitted curve
+2. {results_filename} - Text file containing detailed results
+
+Analysis completed successfully.
+"""
+
+        return research_log
+
+    except Exception as e:
+        return f"Error during analysis: {str(e)}"
+
+
+def analyze_enzyme_kinetics_assay(
+    enzyme_name,
+    substrate_concentrations,
+    enzyme_concentration,
+    modulators=None,
+    time_points=None,
+    output_dir="./",
+):
+    """Performs in vitro enzyme kinetics assay and analyzes the dose-dependent effects of modulators.
+
+    Parameters
+    ----------
+    enzyme_name : str
+        Name of the purified enzyme being tested
+    substrate_concentrations : list or numpy.ndarray
+        List of substrate concentrations in μM for kinetic analysis
+    enzyme_concentration : float
+        Concentration of the enzyme in nM
+    modulators : dict, optional
+        Dictionary of modulators where keys are modulator names and values are lists of
+        concentrations in μM. Default is None (no modulators).
+    time_points : list or numpy.ndarray, optional
+        Time points in minutes for time-course measurements. Default is None, which uses
+        [0, 5, 10, 15, 20, 30, 45, 60].
+    output_dir : str, optional
+        Directory to save output files. Default is current directory.
+
+    Returns
+    -------
+    str
+        Research log summarizing the enzyme kinetics assay procedure and results
+
+    """
+    import csv
+    import os
+
+    import numpy as np
+    from scipy.optimize import curve_fit
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Set default time points if not provided
+    if time_points is None:
+        time_points = np.array([0, 5, 10, 15, 20, 30, 45, 60])
+    else:
+        # Ensure time_points is a numpy array
+        time_points = np.array(time_points)
+
+    # Initialize research log
+    log = f"## In Vitro Enzyme Kinetics Assay: {enzyme_name}\n\n"
+    log += f"Enzyme concentration: {enzyme_concentration} nM\n"
+
+    # Michaelis-Menten equation for curve fitting
+    def michaelis_menten(s, vmax, km):
+        return vmax * s / (km + s)
+
+    # 1. Time-course kinetic assay
+    log += "\n### Time-Course Kinetic Assay\n\n"
+    log += "Measuring enzyme activity over time to establish linear range.\n"
+
+    # Simulate time-course data (realistic enzyme kinetics with some noise)
+    # Using a simple exponential approach to equilibrium model
+    max_activity = 100  # arbitrary units
+    rate_constant = 0.05  # min^-1
+
+    # Simulate enzyme activity over time with some noise
+    np.random.seed(42)  # For reproducibility
+    time_course_activity = max_activity * (1 - np.exp(-rate_constant * time_points))
+    time_course_activity += np.random.normal(0, 3, len(time_points))  # Add noise
+
+    # Save time-course data
+    time_course_file = os.path.join(output_dir, f"{enzyme_name}_time_course.csv")
+    with open(time_course_file, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["Time (min)", "Activity (units)"])
+        for t, a in zip(time_points, time_course_activity, strict=False):
+            writer.writerow([t, a])
+
+    # Determine linear range (first ~30% of the curve)
+    linear_cutoff_index = np.where(time_course_activity >= 0.3 * max_activity)[0][0]
+    linear_time = time_points[: linear_cutoff_index + 1]
+
+    log += f"Time-course data saved to: {time_course_file}\n"
+    log += f"Linear range determined to be 0-{linear_time[-1]} minutes.\n"
+
+    # 2. Substrate kinetics (Michaelis-Menten analysis)
+    log += "\n### Substrate Kinetics Analysis\n\n"
+
+    # Simulate enzyme activity at different substrate concentrations
+    # based on Michaelis-Menten kinetics
+    true_vmax = 120  # arbitrary units
+    true_km = 25  # μM
+
+    activity_values = michaelis_menten(np.array(substrate_concentrations), true_vmax, true_km)
+    activity_values += np.random.normal(0, 5, len(substrate_concentrations))  # Add noise
+
+    # Fit data to Michaelis-Menten equation
+    try:
+        params, _ = curve_fit(
+            michaelis_menten,
+            substrate_concentrations,
+            activity_values,
+            p0=[100, 20],
+            bounds=([0, 0], [500, 200]),
+        )
+        vmax, km = params
+
+        # Save substrate kinetics data
+        kinetics_file = os.path.join(output_dir, f"{enzyme_name}_substrate_kinetics.csv")
+        with open(kinetics_file, "w", newline="") as f:
+            writer = csv.writer(f)
+            writer.writerow(["Substrate (μM)", "Activity (units)"])
+            for s, a in zip(substrate_concentrations, activity_values, strict=False):
+                writer.writerow([s, a])
+
+        log += "Michaelis-Menten parameters:\n"
+        log += f"- Vmax: {vmax:.2f} units\n"
+        log += f"- Km: {km:.2f} μM\n"
+        log += f"Substrate kinetics data saved to: {kinetics_file}\n"
+    except Exception:
+        log += "Error: Could not fit data to Michaelis-Menten model.\n"
+
+    # 3. Modulator effects (if provided)
+    if modulators:
+        log += "\n### Modulator Effects Analysis\n\n"
+
+        for modulator_name, concentrations in modulators.items():
+            log += f"#### Testing modulator: {modulator_name}\n\n"
+
+            # Choose a fixed substrate concentration near Km for inhibition studies
+            substrate_conc = true_km
+
+            # Simulate modulator effects (e.g., competitive inhibition)
+            # For simplicity, using a sigmoidal dose-response curve
+            ic50 = np.random.uniform(1, 50)  # Random IC50 between 1-50 μM
+            hill_coef = 1.0  # Hill coefficient
+
+            # Calculate normalized activity (% of control)
+            michaelis_menten(substrate_conc, true_vmax, true_km)
+
+            # Calculate activities at different modulator concentrations
+            modulator_activities = []
+            for conc in concentrations:
+                # Sigmoidal dose-response curve
+                if conc == 0:
+                    activity = 100  # 100% activity at zero concentration
+                else:
+                    activity = 100 / (1 + (conc / ic50) ** hill_coef)
+
+                # Add some noise
+                activity += np.random.normal(0, 3)
+                modulator_activities.append(activity)
+
+            # Save modulator data
+            modulator_file = os.path.join(output_dir, f"{enzyme_name}_{modulator_name}_dose_response.csv")
+            with open(modulator_file, "w", newline="") as f:
+                writer = csv.writer(f)
+                writer.writerow([f"{modulator_name} (μM)", "Activity (% of control)"])
+                for conc, act in zip(concentrations, modulator_activities, strict=False):
+                    writer.writerow([conc, act])
+
+            # Calculate IC50 using curve fitting if there are enough data points
+            if len(concentrations) >= 4:
+                try:
+                    # Define dose-response curve function
+                    def dose_response(x, ic50, hill):
+                        return 100 / (1 + (x / ic50) ** hill)
+
+                    # Filter out zero concentration
+                    nonzero_conc = np.array([c for c in concentrations if c > 0])
+                    nonzero_act = np.array(
+                        [a for c, a in zip(concentrations, modulator_activities, strict=False) if c > 0]
+                    )
+
+                    if len(nonzero_conc) >= 3:  # Need at least 3 points for fitting
+                        params, _ = curve_fit(
+                            dose_response,
+                            nonzero_conc,
+                            nonzero_act,
+                            p0=[10, 1],
+                            bounds=([0.1, 0.1], [1000, 10]),
+                        )
+                        calc_ic50, calc_hill = params
+
+                        log += f"Dose-response analysis for {modulator_name}:\n"
+                        log += f"- IC50: {calc_ic50:.2f} μM\n"
+                        log += f"- Hill coefficient: {calc_hill:.2f}\n"
+                    else:
+                        log += f"Insufficient non-zero data points to calculate IC50 for {modulator_name}.\n"
+                except Exception:
+                    log += f"Error: Could not fit dose-response curve for {modulator_name}.\n"
+            else:
+                log += f"Insufficient data points to calculate IC50 for {modulator_name}.\n"
+
+            log += f"Dose-response data for {modulator_name} saved to: {modulator_file}\n\n"
+
+    # 4. Summary
+    log += "\n### Summary\n\n"
+    log += f"Completed in vitro enzyme kinetics assay for {enzyme_name}.\n"
+    log += f"- Determined linear range for time-course measurements: 0-{linear_time[-1]} minutes\n"
+    log += f"- Characterized Michaelis-Menten kinetics (Vmax: {vmax:.2f} units, Km: {km:.2f} μM)\n"
+
+    if modulators:
+        log += "- Analyzed the effects of modulators:\n"
+        for modulator_name in modulators:
+            log += f"  * {modulator_name}: Data saved to {enzyme_name}_{modulator_name}_dose_response.csv\n"
+
+    return log
+
+
+def analyze_itc_binding_thermodynamics(
+    itc_data_path=None,
+    itc_data=None,
+    temperature=298.15,
+    protein_concentration=None,
+    ligand_concentration=None,
+):
+    """Analyzes isothermal titration calorimetry (ITC) data to determine binding affinity and thermodynamic parameters.
+
+    Parameters
+    ----------
+    itc_data_path : str, optional
+        Path to CSV or TSV file containing ITC thermogram data with columns for injection number,
+        injection volume, and heat released/absorbed. Expected columns: 'injection', 'volume', 'heat'
+    itc_data : numpy.ndarray, optional
+        Raw ITC thermogram data as a numpy array.
+        Expected shape: (n_injections, 3) with columns for injection number, injection volume, and heat
+        This parameter is provided for backward compatibility and will be deprecated.
+    temperature : float, optional
+        Temperature in Kelvin at which the experiment was conducted. Default is 298.15 K (25°C).
+    protein_concentration : float, optional
+        Initial concentration of protein in the cell in molar (M). Required for accurate fitting.
+    ligand_concentration : float, optional
+        Concentration of ligand in the syringe in molar (M). Required for accurate fitting.
+
+    Returns
+    -------
+    str
+        A research log summarizing the analysis steps and results, including binding affinity (Kd),
+        binding enthalpy (ΔH), binding entropy (ΔS), and Gibbs free energy (ΔG).
+
+    """
+    import datetime
+
+    import numpy as np
+    import pandas as pd
+    from scipy.optimize import curve_fit
+
+    log = []
+    log.append(f"# ITC Binding Affinity Analysis - {datetime.datetime.now().strftime('%Y-%m-%d %H:%M')}")
+    log.append("\n## Data Preprocessing")
+
+    # Check if we have data to process
+    if itc_data_path is None and itc_data is None:
+        log.append("Error: No data provided. Please provide either itc_data_path or itc_data.")
+        return "\n".join(log)
+
+    # Load data from file if path is provided
+    if itc_data_path is not None:
+        try:
+            if itc_data_path.endswith(".csv"):
+                loaded_data = pd.read_csv(itc_data_path)
+            elif itc_data_path.endswith((".tsv", ".txt")):
+                loaded_data = pd.read_csv(itc_data_path, sep="\t")
+            else:
+                log.append("Error: Unsupported file format. Please provide a CSV or TSV file.")
+                return "\n".join(log)
+
+            log.append(f"- Loaded data from file: {itc_data_path}")
+            log.append(f"- Input data: DataFrame with {len(loaded_data)} injections")
+
+            if all(col in loaded_data.columns for col in ["injection", "volume", "heat"]):
+                data = loaded_data[["injection", "volume", "heat"]].values
+            else:
+                log.append("- Error: DataFrame must contain 'injection', 'volume', and 'heat' columns")
+                return "\n".join(log)
+        except Exception as e:
+            log.append(f"- Error loading data from file: {str(e)}")
+            return "\n".join(log)
+    # Use provided numpy array data
+    elif itc_data is not None:
+        if isinstance(itc_data, pd.DataFrame):
+            log.append("Warning: Passing DataFrame directly is deprecated. Please use itc_data_path instead.")
+            log.append(f"- Input data: DataFrame with {len(itc_data)} injections")
+            if all(col in itc_data.columns for col in ["injection", "volume", "heat"]):
+                data = itc_data[["injection", "volume", "heat"]].values
+            else:
+                log.append("- Error: DataFrame must contain 'injection', 'volume', and 'heat' columns")
+                return "\n".join(log)
+        else:
+            log.append(f"- Input data: Array with {len(itc_data)} injections")
+            data = np.array(itc_data)
+
+    # Check if concentration data is provided
+    if protein_concentration is None or ligand_concentration is None:
+        log.append("- Warning: Protein or ligand concentration not provided. Using normalized data for fitting.")
+        protein_concentration = 1.0
+        ligand_concentration = 10.0
+
+    # Extract data
+    injections = data[:, 0]
+    volumes = data[:, 1]
+    heats = data[:, 2]
+
+    log.append(f"- Processed {len(injections)} injections")
+
+    # Calculate molar ratio for each injection
+    cell_volume = 1.4  # Default cell volume in mL (typical for ITC)
+
+    # Calculate cumulative ligand added
+    cumulative_volume = np.cumsum(volumes)
+    dilution_factor = 1 - (cumulative_volume / cell_volume)
+    protein_conc_corrected = protein_concentration * dilution_factor
+
+    # Calculate molar ratio [ligand]/[protein] for each injection
+    molar_ratios = np.zeros_like(injections, dtype=float)
+    for i in range(len(injections)):
+        ligand_added = volumes[i] * ligand_concentration / 1000  # Convert to mmol
+        if i == 0:
+            molar_ratios[i] = ligand_added / (protein_concentration * cell_volume / 1000)  # Convert to mmol
+        else:
+            # Account for dilution and previous injections
+            molar_ratios[i] = molar_ratios[i - 1] + ligand_added / (
+                protein_conc_corrected[i] * (cell_volume - cumulative_volume[i]) / 1000
+            )
+
+    log.append("\n## Model Fitting")
+    log.append("- Applying one-site binding model to the ITC data")
+
+    # Define one-site binding model function
+    def one_site_model(x, Kd, dH, n):
+        """One-site binding model for ITC data.
+
+        Parameters
+        ----------
+        x: Molar ratio [ligand]/[protein]
+        Kd: Dissociation constant (M)
+        dH: Enthalpy change (cal/mol)
+        n: Stoichiometry
+
+        Returns: Heat per injection
+
+        """
+        # Convert x to fraction bound using the binding equation
+        Ka = 1 / Kd  # Association constant
+        protein = protein_conc_corrected
+
+        # Calculate heat for each injection
+        q = np.zeros_like(x)
+        for i in range(len(x)):
+            if i == 0:
+                # First injection
+                bound = (n * protein[i] * Ka * (x[i] * protein[i])) / (1 + Ka * (x[i] * protein[i]))
+                q[i] = bound * dH * cell_volume
+            else:
+                # Subsequent injections (differential heat)
+                bound_prev = (n * protein[i - 1] * Ka * (x[i - 1] * protein[i - 1])) / (
+                    1 + Ka * (x[i - 1] * protein[i - 1])
+                )
+                bound_curr = (n * protein[i] * Ka * (x[i] * protein[i])) / (1 + Ka * (x[i] * protein[i]))
+                q[i] = bound_curr * dH * (cell_volume - cumulative_volume[i]) - bound_prev * dH * (
+                    cell_volume - cumulative_volume[i - 1]
+                )
+
+        return q
+
+    # Initial parameter guesses
+    p0 = [1e-6, -5000, 1.0]  # Kd (M), dH (cal/mol), n (stoichiometry)
+
+    try:
+        # Fit the model to the data
+        popt, pcov = curve_fit(one_site_model, molar_ratios, heats, p0=p0, maxfev=10000)
+        Kd, dH, n = popt
+
+        # Calculate standard errors
+        perr = np.sqrt(np.diag(pcov))
+        Kd_err, dH_err, n_err = perr
+
+        # Calculate other thermodynamic parameters
+        R = 1.9872  # Gas constant in cal/(mol·K)
+        dG = R * temperature * np.log(Kd)  # Gibbs free energy
+        dS = (dH - dG) / temperature  # Entropy
+
+        log.append("- Model fitting successful")
+        log.append("\n## Results")
+        log.append(f"- Binding Stoichiometry (n): {n:.2f} ± {n_err:.2f}")
+        log.append(f"- Dissociation Constant (Kd): {Kd * 1e6:.2f} ± {Kd_err * 1e6:.2f} μM")
+        log.append(f"- Association Constant (Ka): {1 / Kd / 1e6:.2f} × 10^6 M^-1")
+        log.append(f"- Binding Enthalpy (ΔH): {dH:.2f} ± {dH_err:.2f} cal/mol")
+        log.append(f"- Binding Entropy (ΔS): {dS:.2f} cal/(mol·K)")
+        log.append(f"- Gibbs Free Energy (ΔG): {dG:.2f} cal/mol")
+
+        # Calculate goodness of fit
+        residuals = heats - one_site_model(molar_ratios, *popt)
+        ss_res = np.sum(residuals**2)
+        ss_tot = np.sum((heats - np.mean(heats)) ** 2)
+        r_squared = 1 - (ss_res / ss_tot)
+        log.append(f"- R-squared: {r_squared:.4f}")
+
+    except Exception as e:
+        log.append(f"- Error during model fitting: {str(e)}")
+        log.append("- Consider trying different initial parameter guesses or a different binding model")
+
+    log.append("\n## Conclusion")
+    log.append("- Analysis complete. The thermodynamic parameters have been estimated using a one-site binding model.")
+    log.append(
+        "- For more complex binding scenarios, consider using multi-site binding models or specialized ITC analysis software."
+    )
+
+    return "\n".join(log)
+
+
+def analyze_protein_conservation(protein_sequences, output_dir="./"):
+    """Perform multiple sequence alignment and phylogenetic analysis to identify conserved protein regions.
+
+    Parameters
+    ----------
+    protein_sequences : list of str
+        List of protein sequences in FASTA format from multiple organisms.
+    output_dir : str, optional
+        Directory to save output files (default: "./output")
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results, including filenames of saved outputs.
+
+    """
+    import os
+
+    from Bio import AlignIO, Phylo, SeqIO
+    from Bio.Align.Applications import MuscleCommandline
+    from Bio.Phylo.TreeConstruction import DistanceCalculator, DistanceTreeConstructor
+
+    # Create a research log
+    log = []
+    log.append("# Protein Sequence Alignment and Conservation Analysis")
+
+    # Ensure output directory exists
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Step 1: Save input sequences to a temporary file
+    log.append("\n## Step 1: Preparing Input Sequences")
+    input_file = os.path.join(output_dir, "input.fasta")
+
+    # Check if input is already in FASTA format or needs conversion
+    if isinstance(protein_sequences, list):
+        if all(">" in seq for seq in protein_sequences):
+            # Already in FASTA format
+            with open(input_file, "w") as f:
+                f.write("\n".join(protein_sequences))
+        else:
+            # Convert to FASTA format
+            with open(input_file, "w") as f:
+                for i, seq in enumerate(protein_sequences):
+                    f.write(f">Sequence_{i + 1}\n{seq}\n")
+    else:
+        # Assume it's a single string in FASTA format
+        with open(input_file, "w") as f:
+            f.write(protein_sequences)
+
+    log.append(f"Input sequences saved to {input_file}")
+    log.append(f"Number of sequences: {len(list(SeqIO.parse(input_file, 'fasta')))}")
+
+    # Step 2: Perform multiple sequence alignment using MUSCLE
+    log.append("\n## Step 2: Multiple Sequence Alignment")
+    aligned_file = os.path.join(output_dir, "aligned.fasta")
+
+    try:
+        # Run MUSCLE for multiple sequence alignment
+        muscle_cline = MuscleCommandline(input=input_file, out=aligned_file)
+        stdout, stderr = muscle_cline()
+        log.append("Multiple sequence alignment completed using MUSCLE")
+        log.append(f"Alignment saved to {aligned_file}")
+
+        # Load the alignment
+        alignment = AlignIO.read(aligned_file, "fasta")
+        log.append(f"Alignment length: {alignment.get_alignment_length()} positions")
+
+    except Exception as e:
+        log.append(f"MUSCLE alignment failed: {str(e)}")
+        log.append("Attempting to use Biopython's built-in alignment methods...")
+
+        # Fallback to a simpler approach without pairwise2
+        from Bio.Align import MultipleSeqAlignment
+        from Bio.Seq import Seq
+        from Bio.SeqRecord import SeqRecord
+
+        sequences = list(SeqIO.parse(input_file, "fasta"))
+
+        # Simple approach: just pad sequences to the same length
+        max_length = max(len(seq.seq) for seq in sequences)
+        alignments = []
+
+        for seq in sequences:
+            # Pad sequence to max length
+            padded_seq = str(seq.seq).ljust(max_length, "-")
+            new_seq = SeqRecord(Seq(padded_seq), id=seq.id, description=seq.description)
+            alignments.append(new_seq)
+
+        # Create and save the alignment
+        msa = MultipleSeqAlignment(alignments)
+        AlignIO.write(msa, aligned_file, "fasta")
+        alignment = msa
+        log.append("Simple padding alignment completed as fallback method")
+        log.append(f"Alignment saved to {aligned_file}")
+
+    # Step 3: Generate a phylogenetic tree
+    log.append("\n## Step 3: Phylogenetic Analysis")
+    tree_file = os.path.join(output_dir, "tree.newick")
+
+    # Calculate distance matrix
+    calculator = DistanceCalculator("identity")
+    dm = calculator.get_distance(alignment)
+
+    # Construct the phylogenetic tree using neighbor-joining method
+    constructor = DistanceTreeConstructor()
+    tree = constructor.nj(dm)
+
+    # Save the tree
+    Phylo.write(tree, tree_file, "newick")
+    log.append("Phylogenetic tree constructed using neighbor-joining method")
+    log.append(f"Tree saved to {tree_file}")
+
+    # Step 4: Analyze conserved regions
+    log.append("\n## Step 4: Conservation Analysis")
+    conservation_file = os.path.join(output_dir, "conservation.txt")
+
+    # Simple conservation analysis
+    alignment_length = alignment.get_alignment_length()
+    conserved_positions = []
+
+    with open(conservation_file, "w") as f:
+        f.write("Position\tConservation_Score\tConsensus\n")
+
+        for i in range(alignment_length):
+            # Get all amino acids at this position
+            column = alignment[:, i]
+            set(column)
+
+            # Calculate a simple conservation score (percentage of most common AA)
+            most_common_aa = max(column, key=column.count)
+            conservation_score = column.count(most_common_aa) / len(column)
+
+            f.write(f"{i + 1}\t{conservation_score:.2f}\t{most_common_aa}\n")
+
+            # Consider positions with >80% conservation as conserved
+            if conservation_score > 0.8:
+                conserved_positions.append(i + 1)
+
+    log.append(f"Conservation analysis completed and saved to {conservation_file}")
+    log.append(f"Identified {len(conserved_positions)} highly conserved positions (>80% conservation)")
+
+    if conserved_positions:
+        log.append(f"Conserved positions: {', '.join(map(str, conserved_positions[:10]))}")
+        if len(conserved_positions) > 10:
+            log.append(f"... and {len(conserved_positions) - 10} more")
+
+    # Final summary
+    log.append("\n## Summary")
+    log.append("The analysis successfully completed with the following outputs:")
+    log.append(f"1. Multiple sequence alignment: {aligned_file}")
+    log.append(f"2. Phylogenetic tree: {tree_file}")
+    log.append(f"3. Conservation analysis: {conservation_file}")
+
+    return "\n".join(log)

Biomanus_upload/biomni/tool/bioengineering.py

@@ -0,0 +1,1387 @@
+def analyze_cell_migration_metrics(
+    image_sequence_path,
+    pixel_size_um=1.0,
+    time_interval_min=1.0,
+    min_track_length=10,
+    output_dir="./",
+):
+    """Analyze cell migration metrics from time-lapse microscopy images.
+
+    Parameters
+    ----------
+    image_sequence_path : str
+        Path to the directory containing time-lapse images or path to a multi-frame TIFF file
+    pixel_size_um : float
+        Conversion factor from pixels to micrometers (default: 1.0)
+    time_interval_min : float
+        Time interval between consecutive frames in minutes (default: 1.0)
+    min_track_length : int
+        Minimum number of frames a cell must be tracked to be included in analysis (default: 10)
+    output_dir : str
+        Directory to save output files (default: "./")
+
+    Returns
+    -------
+    str
+        Research log summarizing the cell migration analysis process and results
+
+    """
+    import os
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import pandas as pd
+    import trackpy as tp
+    from skimage import io
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Load image sequence
+    if os.path.isdir(image_sequence_path):
+        # Load from directory of images
+        image_files = sorted(
+            [f for f in os.listdir(image_sequence_path) if f.endswith((".tif", ".tiff", ".png", ".jpg", ".jpeg"))]
+        )
+        frames = [io.imread(os.path.join(image_sequence_path, f)) for f in image_files]
+    else:
+        # Load multi-frame TIFF
+        frames = io.imread(image_sequence_path)
+        if frames.ndim == 3:  # Check if it's a time series
+            pass
+        else:
+            return "Error: Input is not a valid time-lapse image sequence"
+
+    # Step 1: Detect cells in each frame
+    features_list = []
+    for i, frame in enumerate(frames):
+        # Detect cells (particles) in the frame
+        features = tp.locate(frame, diameter=15, minmass=100)
+        if features is not None and not features.empty:
+            features["frame"] = i
+            features_list.append(features)
+
+    if not features_list:
+        return "Error: No cells detected in the image sequence"
+
+    # Combine all features
+    all_features = pd.concat(features_list)
+
+    # Save raw detections to output directory
+    raw_detections_file = os.path.join(output_dir, "raw_cell_detections.csv")
+    all_features.to_csv(raw_detections_file, index=False)
+
+    # Step 2: Link features into cell trajectories
+    trajectories = tp.link_df(all_features, search_range=10, memory=3)
+
+    # Save linked trajectories before filtering
+    # Reset index to ensure frame is a column, not an index level
+    trajectories_reset = trajectories.reset_index(drop=True)
+    all_trajectories_file = os.path.join(output_dir, "all_trajectories.csv")
+    trajectories_reset.to_csv(all_trajectories_file, index=False)
+
+    # Step 3: Filter trajectories to get only the ones that appear in enough frames
+    trajectories = tp.filter_stubs(trajectories, threshold=min_track_length)
+
+    if trajectories.empty:
+        return "No complete cell tracks found. Try adjusting parameters."
+
+    # Save filtered trajectories
+    filtered_trajectories_file = os.path.join(output_dir, "filtered_trajectories.csv")
+    # Reset index again to be safe
+    trajectories = trajectories.reset_index(drop=True)
+    trajectories.to_csv(filtered_trajectories_file, index=False)
+
+    # Step 4: Calculate migration metrics for each cell
+    cell_ids = trajectories["particle"].unique()
+    metrics = []
+
+    for cell_id in cell_ids:
+        cell_track = trajectories[trajectories["particle"] == cell_id].sort_values("frame")
+
+        # Convert pixel positions to micrometers
+        cell_track["x_um"] = cell_track["x"] * pixel_size_um
+        cell_track["y_um"] = cell_track["y"] * pixel_size_um
+
+        # Calculate displacements between consecutive frames
+        dx = np.diff(cell_track["x_um"])
+        dy = np.diff(cell_track["y_um"])
+
+        # Calculate step distances
+        step_distances = np.sqrt(dx**2 + dy**2)
+
+        # Calculate total path length
+        path_length = np.sum(step_distances)
+
+        # Calculate net displacement (straight-line distance from start to end)
+        start_x, start_y = cell_track.iloc[0][["x_um", "y_um"]]
+        end_x, end_y = cell_track.iloc[-1][["x_um", "y_um"]]
+        net_displacement = np.sqrt((end_x - start_x) ** 2 + (end_y - start_y) ** 2)
+
+        # Calculate directionality ratio (net displacement / path length)
+        directionality = net_displacement / path_length if path_length > 0 else 0
+
+        # Calculate speed (μm/min)
+        time_tracked = (cell_track["frame"].max() - cell_track["frame"].min()) * time_interval_min
+        speed = path_length / time_tracked if time_tracked > 0 else 0
+
+        metrics.append(
+            {
+                "cell_id": cell_id,
+                "frames_tracked": len(cell_track),
+                "speed_um_per_min": speed,
+                "directionality": directionality,
+                "displacement_um": net_displacement,
+                "path_length_um": path_length,
+            }
+        )
+
+    # Convert metrics to DataFrame
+    metrics_df = pd.DataFrame(metrics)
+
+    # Save metrics to CSV
+    metrics_file = os.path.join(output_dir, "cell_migration_metrics.csv")
+    metrics_df.to_csv(metrics_file, index=False)
+
+    # Calculate summary statistics
+    summary = {
+        "num_cells_tracked": len(metrics_df),
+        "avg_speed": metrics_df["speed_um_per_min"].mean(),
+        "std_speed": metrics_df["speed_um_per_min"].std(),
+        "avg_directionality": metrics_df["directionality"].mean(),
+        "std_directionality": metrics_df["directionality"].std(),
+        "avg_displacement": metrics_df["displacement_um"].mean(),
+        "std_displacement": metrics_df["displacement_um"].std(),
+    }
+
+    # Save summary statistics
+    summary_file = os.path.join(output_dir, "migration_summary.csv")
+    pd.DataFrame([summary]).to_csv(summary_file, index=False)
+
+    # Save trajectories visualization
+    fig, ax = plt.figure(figsize=(8, 8)), plt.gca()
+    tp.plot_traj(trajectories, ax=ax)
+    plt.title("Cell Migration Trajectories")
+    plt.xlabel("x position (pixels)")
+    plt.ylabel("y position (pixels)")
+
+    trajectories_file = os.path.join(output_dir, "cell_trajectories.png")
+    plt.savefig(trajectories_file)
+    plt.close()
+
+    # Create a rose plot to show migration directionality
+    fig, ax = plt.subplots(subplot_kw={"projection": "polar"}, figsize=(8, 8))
+
+    # Calculate angles for each cell (end position relative to start)
+    angles = []
+    for cell_id in cell_ids:
+        cell_track = trajectories[trajectories["particle"] == cell_id].sort_values("frame")
+        start_x, start_y = cell_track.iloc[0][["x", "y"]]
+        end_x, end_y = cell_track.iloc[-1][["x", "y"]]
+        dx, dy = end_x - start_x, end_y - start_y
+        angle = np.arctan2(dy, dx)
+        angles.append(angle)
+
+    # Plot the histogram
+    bins = np.linspace(-np.pi, np.pi, 16)
+    ax.hist(angles, bins=bins)
+    ax.set_title("Cell Migration Directionality")
+
+    # Save the rose plot
+    rose_plot_file = os.path.join(output_dir, "rose_plot.png")
+    plt.savefig(rose_plot_file)
+    plt.close()
+
+    # Create a displacement plot
+    plt.figure(figsize=(10, 6))
+    plt.bar(range(len(metrics_df)), metrics_df["displacement_um"])
+    plt.xlabel("Cell ID")
+    plt.ylabel("Displacement (μm)")
+    plt.title("Cell Displacements")
+
+    # Save the displacement plot
+    displacement_plot_file = os.path.join(output_dir, "track_displacement_plot.png")
+    plt.savefig(displacement_plot_file)
+    plt.close()
+
+    # Generate research log
+    log = f"""
+Cell Migration Analysis Research Log:
+
+1. Analyzed time-lapse sequence with {len(frames)} frames
+2. Detected and tracked {len(cell_ids)} cells that persisted for at least {min_track_length} frames
+3. Calculated key migration metrics:
+   - Average speed: {summary["avg_speed"]:.2f} ± {summary["std_speed"]:.2f} μm/min
+   - Average directionality ratio: {summary["avg_directionality"]:.2f} ± {summary["std_directionality"]:.2f}
+   - Average displacement: {summary["avg_displacement"]:.2f} ± {summary["std_displacement"]:.2f} μm
+
+4. Files saved:
+   - Raw cell detections: {raw_detections_file}
+   - All cell trajectories: {all_trajectories_file}
+   - Filtered trajectories: {filtered_trajectories_file}
+   - Detailed cell metrics: {metrics_file}
+   - Summary statistics: {summary_file}
+   - Cell trajectories visualization: {trajectories_file}
+   - Direction rose plot: {rose_plot_file}
+   - Cell displacement plot: {displacement_plot_file}
+
+Note: Analysis used pixel size of {pixel_size_um} μm and time interval of {time_interval_min} min between frames.
+    """
+
+    return log.strip()
+
+
+def perform_crispr_cas9_genome_editing(guide_rna_sequences, target_genomic_loci, cell_tissue_type):
+    """Simulates CRISPR-Cas9 genome editing process including guide RNA design, delivery, and analysis.
+
+    Parameters
+    ----------
+    guide_rna_sequences : list of str
+        List of guide RNA sequences (20 nucleotides each) targeting the genomic region of interest
+
+    target_genomic_loci : str
+        Target genomic sequence to be edited (should be longer than guide RNA and contain the target sites)
+
+    cell_tissue_type : str
+        Type of cell or tissue being edited (affects delivery efficiency and editing outcomes)
+
+    Returns
+    -------
+    str
+        Research log detailing the CRISPR-Cas9 editing process, including steps taken and results
+
+    """
+    import os
+    import random
+    from datetime import datetime
+
+    # Initialize research log
+    log = "CRISPR-Cas9 Genome Editing Research Log\n"
+    log += f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+    log += f"Cell/Tissue Type: {cell_tissue_type}\n\n"
+
+    # Step 1: Validate guide RNA sequences
+    log += "STEP 1: Guide RNA Validation\n"
+    valid_guides = []
+
+    for i, guide in enumerate(guide_rna_sequences):
+        if len(guide) != 20:
+            log += f"  Guide {i + 1}: INVALID - Guide RNA must be 20 nucleotides (current length: {len(guide)})\n"
+            continue
+
+        if not all(n in "ATGC" for n in guide.upper()):
+            log += f"  Guide {i + 1}: INVALID - Guide RNA contains invalid nucleotides\n"
+            continue
+
+        # Calculate GC content (affects guide efficiency)
+        gc_content = (guide.upper().count("G") + guide.upper().count("C")) / len(guide) * 100
+        efficiency_score = 0
+
+        if 40 <= gc_content <= 60:
+            efficiency_score += 1
+            gc_quality = "Optimal"
+        else:
+            gc_quality = "Suboptimal"
+
+        log += f"  Guide {i + 1}: VALID - {guide} (GC content: {gc_content:.1f}% - {gc_quality})\n"
+        valid_guides.append((guide, efficiency_score))
+
+    if not valid_guides:
+        log += "\nNo valid guide RNAs found. Genome editing cannot proceed.\n"
+        return log
+
+    # Step 2: Target site identification
+    log += "\nSTEP 2: Target Site Identification\n"
+
+    target_seq = target_genomic_loci.upper()
+    target_matches = []
+
+    for i, (guide, score) in enumerate(valid_guides):
+        # Find guide RNA target in genomic sequence (including PAM site NGG)
+        guide.upper() + "NGG"
+
+        # Check if guide sequence is in target (simplified)
+        if guide.upper() in target_seq:
+            position = target_seq.find(guide.upper())
+            # Check if there's a PAM sequence (NGG) after the guide
+            if position + len(guide) + 2 <= len(target_seq):
+                potential_pam = target_seq[position + len(guide) : position + len(guide) + 3]
+                if potential_pam[1:3] == "GG":
+                    pam_quality = "Found"
+                    score += 2
+                else:
+                    pam_quality = "Not found"
+            else:
+                pam_quality = "Out of bounds"
+
+            log += f"  Guide {i + 1}: Found at position {position} (PAM: {pam_quality})\n"
+            target_matches.append((guide, position, score))
+        else:
+            log += f"  Guide {i + 1}: No match found in target sequence\n"
+
+    if not target_matches:
+        log += "\nNo matching target sites found. Genome editing cannot proceed.\n"
+        return log
+
+    # Step 3: Simulate CRISPR-Cas9 delivery
+    log += "\nSTEP 3: CRISPR-Cas9 Delivery Simulation\n"
+
+    # Cell-specific delivery efficiencies (simplified model)
+    delivery_efficiencies = {
+        "hek293": 0.85,
+        "hela": 0.75,
+        "ipsc": 0.60,
+        "primary_neuron": 0.40,
+        "hematopoietic_stem_cell": 0.55,
+        "mouse_embryo": 0.70,
+        "plant_cell": 0.30,
+    }
+
+    # Get delivery efficiency based on cell type (default to 0.5 if unknown)
+    cell_type_key = cell_tissue_type.lower().replace(" ", "_")
+    delivery_efficiency = delivery_efficiencies.get(cell_type_key, 0.5)
+
+    log += f"  Delivery method: Lipofection for {cell_tissue_type}\n"
+    log += f"  Estimated delivery efficiency: {delivery_efficiency * 100:.1f}%\n"
+
+    # Step 4: Simulate genome editing
+    log += "\nSTEP 4: Genome Editing Simulation\n"
+
+    # Select best guide based on score
+    best_guide, best_position, best_score = sorted(target_matches, key=lambda x: x[2], reverse=True)[0]
+
+    log += f"  Selected guide RNA: {best_guide} (highest efficiency score)\n"
+    log += f"  Target position: {best_position} to {best_position + len(best_guide) - 1}\n"
+
+    # Simulate editing outcome
+    edit_success_rate = delivery_efficiency * (0.5 + (best_score * 0.1))  # Between 50-90% based on guide quality
+
+    # Cut site (typically 3 bases upstream of PAM)
+    cut_position = best_position + len(best_guide) - 3
+    log += f"  Predicted cut site: Between positions {cut_position} and {cut_position + 1}\n"
+
+    # Simulate editing outcomes
+    indel_size = random.randint(1, 5)  # Random indel size between 1-5 bp
+
+    # Create modified sequence (simulate a deletion for simplicity)
+    modified_sequence = target_seq[:cut_position] + target_seq[cut_position + indel_size :]
+
+    log += f"  Simulated edit: {indel_size}bp deletion at cut site\n"
+    log += f"  Predicted editing efficiency: {edit_success_rate * 100:.1f}%\n"
+
+    # Step 5: Analysis of editing outcomes
+    log += "\nSTEP 5: Editing Outcome Analysis\n"
+
+    # Calculate basic stats
+    log += f"  Original sequence length: {len(target_seq)} bp\n"
+    log += f"  Modified sequence length: {len(modified_sequence)} bp\n"
+
+    # Save sequences to files
+    os.makedirs("crispr_results", exist_ok=True)
+
+    original_file = "crispr_results/original_sequence.txt"
+    with open(original_file, "w") as f:
+        f.write(f">Original_Sequence\n{target_seq}\n")
+
+    modified_file = "crispr_results/modified_sequence.txt"
+    with open(modified_file, "w") as f:
+        f.write(f">Modified_Sequence\n{modified_sequence}\n")
+
+    log += f"  Original sequence saved to: {original_file}\n"
+    log += f"  Modified sequence saved to: {modified_file}\n"
+
+    # Summary
+    log += "\nSUMMARY:\n"
+    log += f"  CRISPR-Cas9 editing successfully simulated for {cell_tissue_type}\n"
+    log += f"  {indel_size}bp deletion introduced at position {cut_position}\n"
+    log += f"  Expected success rate in cell population: {edit_success_rate * 100:.1f}%\n"
+
+    return log
+
+
+def analyze_calcium_imaging_data(image_stack_path, output_dir="./"):
+    """Analyze calcium imaging data to quantify neuronal activity metrics.
+
+    This function processes fluorescence microscopy images of GCaMP-labeled neurons
+    to extract quantitative metrics of neuronal activity, including cell counts,
+    event rates, decay times, and signal-to-noise ratios.
+
+    Parameters
+    ----------
+    image_stack_path : str
+        Path to the time-series stack of fluorescence microscopy images (TIFF format)
+    output_dir : str, optional
+        Directory to save output files (default: "./")
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+
+    import numpy as np
+    import pandas as pd
+    from scipy import ndimage, signal
+    from scipy.optimize import curve_fit
+    from skimage import feature, filters, io, measure, segmentation
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Step 1: Load the image stack
+    log = "CALCIUM IMAGING ANALYSIS LOG\n"
+    log += "===========================\n\n"
+    log += f"Loading image stack from: {image_stack_path}\n"
+
+    try:
+        image_stack = io.imread(image_stack_path)
+        num_frames, height, width = image_stack.shape
+        log += f"Successfully loaded {num_frames} frames of size {height}x{width}\n\n"
+    except Exception as e:
+        return f"Error loading image stack: {str(e)}"
+
+    # Step 2: Calculate mean image for segmentation
+    log += "Step 1: Preprocessing and neuron segmentation\n"
+    mean_image = np.mean(image_stack, axis=0)
+
+    # Apply Gaussian filter to reduce noise
+    smooth_mean = filters.gaussian(mean_image, sigma=2)
+
+    # Step 3: Segment neurons using watershed
+    # Find local maxima (potential cell centers)
+    distance = ndimage.distance_transform_edt(smooth_mean)
+    # Create a mask for local maxima instead of using indices=False parameter
+    coordinates = feature.peak_local_max(distance, min_distance=10)
+
+    # Handle case where no local maxima are found
+    if len(coordinates) == 0:
+        log += "No local maxima detected. Using simple thresholding instead.\n"
+        # Create a simple binary mask using thresholding as fallback
+        binary_mask = smooth_mean > filters.threshold_otsu(smooth_mean)
+        markers = measure.label(binary_mask)
+    else:
+        local_max = np.zeros_like(distance, dtype=bool)
+        for coord in coordinates:
+            local_max[coord[0], coord[1]] = True
+        markers = measure.label(local_max)
+
+    # Watershed segmentation
+    segmented = segmentation.watershed(-smooth_mean, markers, mask=smooth_mean > filters.threshold_otsu(smooth_mean))
+
+    # Get region properties
+    regions = measure.regionprops(segmented)
+    cell_count = len(regions)
+    log += f"Detected {cell_count} neurons in the field of view\n\n"
+
+    # Step 4: Extract time-series data for each neuron
+    log += "Step 2: Extracting fluorescence time-series for each neuron\n"
+    time_series_data = []
+
+    for _i, region in enumerate(regions):
+        mask = segmented == region.label
+        cell_time_series = []
+
+        for frame in range(num_frames):
+            intensity = np.mean(image_stack[frame][mask])
+            cell_time_series.append(intensity)
+
+        time_series_data.append(cell_time_series)
+
+    time_series_array = np.array(time_series_data)
+
+    # Step 5: Detect calcium events and calculate metrics
+    log += "Step 3: Calculating neuronal activity metrics\n"
+
+    # Function to fit exponential decay
+    def exp_decay(x, a, tau, c):
+        return a * np.exp(-x / tau) + c
+
+    event_rates = []
+    decay_times = []
+    snr_values = []
+
+    for i, ts in enumerate(time_series_data):
+        # Normalize time series
+        baseline = np.percentile(ts, 20)
+        ts_norm = [(x - baseline) / baseline for x in ts]
+
+        # Simple event detection (threshold crossing)
+        threshold = np.std(ts_norm) * 2
+        events = []
+        in_event = False
+
+        for j, val in enumerate(ts_norm):
+            if not in_event and val > threshold:
+                events.append(j)
+                in_event = True
+            elif in_event and val < threshold:
+                in_event = False
+
+        # Calculate event rate (events per minute, assuming 10 Hz acquisition)
+        acquisition_rate = 10  # Hz (assumption)
+        recording_time_minutes = num_frames / acquisition_rate / 60
+        event_rate = len(events) / recording_time_minutes
+        event_rates.append(event_rate)
+
+        # Calculate decay times for detected events
+        cell_decay_times = []
+        for event_start in events:
+            if event_start + 30 < len(ts_norm):  # Ensure enough frames after event
+                event_window = ts_norm[event_start : event_start + 30]
+                peak_idx = np.argmax(event_window)
+                decay_segment = event_window[peak_idx:]
+
+                try:
+                    # Fit exponential decay
+                    x_data = np.arange(len(decay_segment))
+                    popt, _ = curve_fit(
+                        exp_decay,
+                        x_data,
+                        decay_segment,
+                        p0=[decay_segment[0], 5, decay_segment[-1]],
+                        bounds=([0, 0, 0], [np.inf, np.inf, np.inf]),
+                    )
+                    tau = popt[1]  # Decay time constant
+                    cell_decay_times.append(tau / acquisition_rate)  # Convert to seconds
+                except Exception:
+                    # Skip if curve fitting fails
+                    pass
+
+        if cell_decay_times:
+            decay_times.append(np.mean(cell_decay_times))
+        else:
+            decay_times.append(np.nan)
+
+        # Calculate signal-to-noise ratio
+        signal = np.mean([ts_norm[e] for e in events]) if events else 0  # noqa: F811
+        noise = np.std([ts_norm[i] for i in range(len(ts_norm)) if all(abs(i - e) > 5 for e in events)])
+        snr = signal / noise if noise > 0 else 0
+        snr_values.append(snr)
+
+    # Step 6: Compile and save results
+    cell_metrics = pd.DataFrame(
+        {
+            "Cell_ID": range(1, cell_count + 1),
+            "Event_Rate_per_min": event_rates,
+            "Decay_Time_sec": decay_times,
+            "SNR": snr_values,
+        }
+    )
+
+    metrics_file = os.path.join(output_dir, "neuron_activity_metrics.csv")
+    cell_metrics.to_csv(metrics_file, index=False)
+
+    # Save time series data
+    time_series_file = os.path.join(output_dir, "neuron_time_series.csv")
+    time_series_df = pd.DataFrame(time_series_array.T)
+    time_series_df.columns = [f"Cell_{i + 1}" for i in range(cell_count)]
+    time_series_df.to_csv(time_series_file, index=False)
+
+    # Step 7: Summarize results
+    log += f"Cell count: {cell_count}\n"
+    log += f"Average event rate: {np.nanmean(event_rates):.2f} events/min\n"
+    log += f"Average decay time: {np.nanmean(decay_times):.2f} seconds\n"
+    log += f"Average SNR: {np.nanmean(snr_values):.2f}\n\n"
+
+    log += "Step 4: Results saved to files\n"
+    log += f"Neuron activity metrics saved to: {metrics_file}\n"
+    log += f"Time series data saved to: {time_series_file}\n"
+
+    return log
+
+
+def analyze_in_vitro_drug_release_kinetics(
+    time_points,
+    concentration_data,
+    drug_name="Drug",
+    total_drug_loaded=None,
+    output_dir="./",
+):
+    """Analyzes in vitro drug release kinetics from biomaterial formulations.
+
+    Parameters
+    ----------
+    time_points : list or numpy.ndarray
+        Time points at which drug concentrations were measured (in hours)
+    concentration_data : list or numpy.ndarray
+        Measured drug concentration at each time point
+    drug_name : str, optional
+        Name of the drug being analyzed (default: "Drug")
+    total_drug_loaded : float, optional
+        Total amount of drug initially loaded in the formulation.
+        If None, the maximum concentration is used as 100% (default: None)
+    output_dir : str, optional
+        Directory to save output files (default: "./")
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps, results, and saved file locations
+
+    """
+    import os
+    from datetime import datetime
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import pandas as pd
+    from scipy.optimize import curve_fit
+
+    # Ensure output directory exists
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Convert inputs to numpy arrays
+    time_points = np.array(time_points)
+    concentration_data = np.array(concentration_data)
+
+    # Calculate cumulative release percentage
+    if total_drug_loaded is None:
+        total_drug_loaded = np.max(concentration_data)
+
+    cumulative_release = (concentration_data / total_drug_loaded) * 100
+
+    # Create a DataFrame for easier manipulation
+    release_df = pd.DataFrame(
+        {
+            "Time (hours)": time_points,
+            "Concentration": concentration_data,
+            "Cumulative Release (%)": cumulative_release,
+        }
+    )
+
+    # Calculate release rate (simple approximation using differences)
+    release_df["Release Rate"] = np.gradient(release_df["Cumulative Release (%)"], release_df["Time (hours)"])
+
+    # Define kinetic models
+    def zero_order(t, k):
+        return k * t
+
+    def first_order(t, k):
+        return 100 * (1 - np.exp(-k * t))
+
+    def higuchi(t, k):
+        return k * np.sqrt(t)
+
+    def korsmeyer_peppas(t, k, n):
+        return 100 * (k * t) ** n
+
+    # Fit data to different kinetic models
+    models = {}
+    r2_values = {}
+
+    # Zero-order kinetics
+    try:
+        params, _ = curve_fit(zero_order, time_points, cumulative_release)
+        y_pred = zero_order(time_points, *params)
+        ss_total = np.sum((cumulative_release - np.mean(cumulative_release)) ** 2)
+        ss_residual = np.sum((cumulative_release - y_pred) ** 2)
+        r2 = 1 - (ss_residual / ss_total)
+        models["Zero-order"] = {
+            "params": params,
+            "equation": f"Release = {params[0]:.4f} * t",
+            "pred": y_pred,
+        }
+        r2_values["Zero-order"] = r2
+    except Exception:
+        models["Zero-order"] = {
+            "params": None,
+            "equation": "Fitting failed",
+            "pred": None,
+        }
+        r2_values["Zero-order"] = 0
+
+    # First-order kinetics
+    try:
+        params, _ = curve_fit(first_order, time_points, cumulative_release, bounds=(0, [1]))
+        y_pred = first_order(time_points, *params)
+        ss_total = np.sum((cumulative_release - np.mean(cumulative_release)) ** 2)
+        ss_residual = np.sum((cumulative_release - y_pred) ** 2)
+        r2 = 1 - (ss_residual / ss_total)
+        models["First-order"] = {
+            "params": params,
+            "equation": f"Release = 100 * (1 - exp(-{params[0]:.4f} * t))",
+            "pred": y_pred,
+        }
+        r2_values["First-order"] = r2
+    except Exception:
+        models["First-order"] = {
+            "params": None,
+            "equation": "Fitting failed",
+            "pred": None,
+        }
+        r2_values["First-order"] = 0
+
+    # Higuchi model
+    try:
+        params, _ = curve_fit(higuchi, time_points, cumulative_release)
+        y_pred = higuchi(time_points, *params)
+        ss_total = np.sum((cumulative_release - np.mean(cumulative_release)) ** 2)
+        ss_residual = np.sum((cumulative_release - y_pred) ** 2)
+        r2 = 1 - (ss_residual / ss_total)
+        models["Higuchi"] = {
+            "params": params,
+            "equation": f"Release = {params[0]:.4f} * sqrt(t)",
+            "pred": y_pred,
+        }
+        r2_values["Higuchi"] = r2
+    except Exception:
+        models["Higuchi"] = {"params": None, "equation": "Fitting failed", "pred": None}
+        r2_values["Higuchi"] = 0
+
+    # Korsmeyer-Peppas model
+    try:
+        # Only use the first 60% of release data for Korsmeyer-Peppas model
+        mask = cumulative_release <= 60
+        if sum(mask) >= 3:  # Need at least 3 points for fitting
+            params, _ = curve_fit(
+                korsmeyer_peppas,
+                time_points[mask],
+                cumulative_release[mask],
+                bounds=([0, 0], [1, 1]),
+            )
+            y_pred = korsmeyer_peppas(time_points, *params)
+            ss_total = np.sum((cumulative_release - np.mean(cumulative_release)) ** 2)
+            ss_residual = np.sum((cumulative_release - y_pred) ** 2)
+            r2 = 1 - (ss_residual / ss_total)
+            models["Korsmeyer-Peppas"] = {
+                "params": params,
+                "equation": f"Release = 100 * ({params[0]:.4f} * t)^{params[1]:.4f}",
+                "pred": y_pred,
+            }
+            r2_values["Korsmeyer-Peppas"] = r2
+        else:
+            models["Korsmeyer-Peppas"] = {
+                "params": None,
+                "equation": "Insufficient data points",
+                "pred": None,
+            }
+            r2_values["Korsmeyer-Peppas"] = 0
+    except Exception:
+        models["Korsmeyer-Peppas"] = {
+            "params": None,
+            "equation": "Fitting failed",
+            "pred": None,
+        }
+        r2_values["Korsmeyer-Peppas"] = 0
+
+    # Determine best model based on R² value
+    best_model = max(r2_values, key=r2_values.get)
+
+    # Calculate half-life (time to 50% release)
+    try:
+        # Use best model to calculate half-life
+        if best_model == "Zero-order":
+            k = models[best_model]["params"][0]
+            half_life = 50 / k if k > 0 else float("inf")
+        elif best_model == "First-order":
+            k = models[best_model]["params"][0]
+            half_life = -np.log(0.5) / k if k > 0 else float("inf")
+        elif best_model == "Higuchi":
+            k = models[best_model]["params"][0]
+            half_life = (50 / k) ** 2 if k > 0 else float("inf")
+        elif best_model == "Korsmeyer-Peppas":
+            k, n = models[best_model]["params"]
+            half_life = (0.5 ** (1 / n)) / k if k > 0 else float("inf")
+        else:
+            # Interpolate from data if model fitting failed
+            from scipy.interpolate import interp1d
+
+            if np.max(cumulative_release) >= 50:
+                f = interp1d(cumulative_release, time_points)
+                half_life = float(f(50))
+            else:
+                half_life = "Not reached"
+    except Exception:
+        half_life = "Could not calculate"
+
+    # Create plots
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    # 1. Cumulative release plot with model fits
+    plt.figure(figsize=(10, 6))
+    plt.plot(time_points, cumulative_release, "o-", label="Experimental data")
+
+    for model_name, model_data in models.items():
+        if model_data["pred"] is not None:
+            plt.plot(
+                time_points,
+                model_data["pred"],
+                "--",
+                label=f"{model_name} (R² = {r2_values[model_name]:.4f})",
+            )
+
+    plt.xlabel("Time (hours)")
+    plt.ylabel("Cumulative Release (%)")
+    plt.title(f"In Vitro Release Profile of {drug_name}")
+    plt.legend()
+    plt.grid(True, linestyle="--", alpha=0.7)
+    cumulative_plot_path = os.path.join(output_dir, f"cumulative_release_{timestamp}.png")
+    plt.savefig(cumulative_plot_path, dpi=300, bbox_inches="tight")
+    plt.close()
+
+    # 2. Release rate plot
+    plt.figure(figsize=(10, 6))
+    plt.plot(time_points, release_df["Release Rate"], "o-")
+    plt.xlabel("Time (hours)")
+    plt.ylabel("Release Rate (%/hour)")
+    plt.title(f"Release Rate of {drug_name}")
+    plt.grid(True, linestyle="--", alpha=0.7)
+    rate_plot_path = os.path.join(output_dir, f"release_rate_{timestamp}.png")
+    plt.savefig(rate_plot_path, dpi=300, bbox_inches="tight")
+    plt.close()
+
+    # Save data to CSV
+    csv_path = os.path.join(output_dir, f"drug_release_data_{timestamp}.csv")
+    release_df.to_csv(csv_path, index=False)
+
+    # Generate research log
+    log = f"""
+# In Vitro Drug Release Kinetics Analysis for {drug_name}
+
+## Analysis Summary
+- **Date/Time:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+- **Drug Analyzed:** {drug_name}
+- **Time Range:** {min(time_points)} to {max(time_points)} hours
+- **Number of Data Points:** {len(time_points)}
+- **Maximum Release Achieved:** {max(cumulative_release):.2f}%
+
+## Kinetic Models Analysis
+The release data was fitted to four standard kinetic models:
+
+1. **Zero-order Model:** {models["Zero-order"]["equation"]} (R² = {r2_values["Zero-order"]:.4f})
+2. **First-order Model:** {models["First-order"]["equation"]} (R² = {r2_values["First-order"]:.4f})
+3. **Higuchi Model:** {models["Higuchi"]["equation"]} (R² = {r2_values["Higuchi"]:.4f})
+4. **Korsmeyer-Peppas Model:** {models["Korsmeyer-Peppas"]["equation"]} (R² = {r2_values["Korsmeyer-Peppas"]:.4f})
+
+**Best-fitting Model:** {best_model} (R² = {r2_values[best_model]:.4f})
+
+## Release Metrics
+- **Half-life (t50%):** {half_life if isinstance(half_life, str) else f"{half_life:.2f} hours"}
+- **Initial Release Rate:** {release_df["Release Rate"].iloc[0]:.4f} %/hour
+- **Average Release Rate:** {np.mean(release_df["Release Rate"]):.4f} %/hour
+
+## Files Generated
+1. Cumulative Release Plot: {cumulative_plot_path}
+2. Release Rate Plot: {rate_plot_path}
+3. Data CSV: {csv_path}
+
+## Interpretation
+The drug release profile of {drug_name} best follows a {
+        best_model
+    } kinetic model, which suggests that the release mechanism is primarily driven by {
+        "diffusion through a porous matrix"
+        if best_model == "Higuchi"
+        else "diffusion with erosion"
+        if best_model == "Korsmeyer-Peppas" and 0.43 <= models[best_model]["params"][1] <= 0.85
+        else "Fickian diffusion"
+        if best_model == "Korsmeyer-Peppas" and models[best_model]["params"][1] < 0.43
+        else "case-II transport"
+        if best_model == "Korsmeyer-Peppas" and models[best_model]["params"][1] > 0.85
+        else "concentration-dependent diffusion"
+        if best_model == "First-order"
+        else "constant release rate independent of concentration"
+        if best_model == "Zero-order"
+        else "complex mechanisms"
+    }.
+"""
+
+    return log.strip()
+
+
+def analyze_myofiber_morphology(
+    image_path,
+    nuclei_channel=2,
+    myofiber_channel=1,
+    threshold_method="otsu",
+    output_dir="./",
+):
+    """Quantifies morphological properties of myofibers in microscopy images of tissue sections.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the microscopy image file (typically a multichannel image with nuclei and myofiber staining)
+    nuclei_channel : int, default=2
+        Channel index containing nuclei staining (DAPI, Hoechst, etc.)
+    myofiber_channel : int, default=1
+        Channel index containing myofiber staining (α-Actinin, etc.)
+    threshold_method : str, default='otsu'
+        Method for thresholding ('otsu', 'adaptive', or 'manual')
+    output_dir : str, default='./'
+        Directory to save output files
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import numpy as np
+    import pandas as pd
+    from skimage import exposure, filters, io, measure, morphology
+    from skimage.color import label2rgb
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Load the image
+    image = io.imread(image_path)
+
+    # Extract channels (assuming multichannel image)
+    if len(image.shape) > 2:
+        if len(image.shape) == 3:
+            # RGB image
+            nuclei_img = image[:, :, nuclei_channel] if nuclei_channel < image.shape[2] else image[:, :, 0]
+            myofiber_img = image[:, :, myofiber_channel] if myofiber_channel < image.shape[2] else image[:, :, 1]
+        else:
+            # Multichannel image (e.g., from confocal)
+            nuclei_img = image[nuclei_channel, :, :] if nuclei_channel < image.shape[0] else image[0, :, :]
+            myofiber_img = image[myofiber_channel, :, :] if myofiber_channel < image.shape[0] else image[1, :, :]
+    else:
+        # Single channel image - can't separate nuclei and myofibers
+        return "Error: Input image must be multichannel to separate nuclei and myofibers"
+
+    # Enhance contrast
+    nuclei_img = exposure.equalize_adapthist(nuclei_img)
+    myofiber_img = exposure.equalize_adapthist(myofiber_img)
+
+    # Segment nuclei
+    if threshold_method == "otsu":
+        nuclei_thresh = filters.threshold_otsu(nuclei_img)
+    elif threshold_method == "adaptive":
+        nuclei_thresh = filters.threshold_local(nuclei_img, block_size=35)
+    else:  # manual
+        nuclei_thresh = np.mean(nuclei_img) * 1.5
+
+    nuclei_binary = nuclei_img > nuclei_thresh
+    nuclei_binary = morphology.remove_small_objects(nuclei_binary, min_size=30)
+    nuclei_binary = morphology.binary_closing(nuclei_binary)
+
+    # Label nuclei
+    nuclei_labels = measure.label(nuclei_binary)
+    nuclei_props = measure.regionprops(nuclei_labels)
+
+    # Segment myofibers
+    if threshold_method == "otsu":
+        myofiber_thresh = filters.threshold_otsu(myofiber_img)
+    elif threshold_method == "adaptive":
+        myofiber_thresh = filters.threshold_local(myofiber_img, block_size=101)
+    else:  # manual
+        myofiber_thresh = np.mean(myofiber_img) * 1.2
+
+    myofiber_binary = myofiber_img > myofiber_thresh
+    myofiber_binary = morphology.remove_small_objects(myofiber_binary, min_size=500)
+    myofiber_binary = morphology.binary_closing(myofiber_binary, morphology.disk(3))
+
+    # Label myofibers
+    myofiber_labels = measure.label(myofiber_binary)
+    myofiber_props = measure.regionprops(myofiber_labels)
+
+    # Count nuclei inside myofibers
+    nuclei_inside = 0
+    nuclei_total = len(nuclei_props)
+
+    for nucleus in nuclei_props:
+        y, x = nucleus.centroid
+        y, x = int(y), int(x)
+        if myofiber_binary[y, x]:
+            nuclei_inside += 1
+
+    percent_inside = nuclei_inside / nuclei_total * 100 if nuclei_total > 0 else 0
+
+    # Calculate myofiber morphological properties
+    myofiber_data = []
+    for fiber in myofiber_props:
+        myofiber_data.append(
+            {
+                "Area": fiber.area,
+                "Perimeter": fiber.perimeter,
+                "Eccentricity": fiber.eccentricity,
+                "Solidity": fiber.solidity,
+                "Orientation": fiber.orientation,
+            }
+        )
+
+    # Save results
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_file = f"{output_dir}/myofiber_analysis_{timestamp}.csv"
+
+    if myofiber_data:
+        df = pd.DataFrame(myofiber_data)
+        df.to_csv(results_file, index=False)
+
+        # Calculate summary statistics
+        mean_area = df["Area"].mean()
+        mean_perimeter = df["Perimeter"].mean()
+        mean_eccentricity = df["Eccentricity"].mean()
+    else:
+        mean_area = mean_perimeter = mean_eccentricity = 0
+
+    # Save labeled image
+    labeled_image = label2rgb(myofiber_labels, image=myofiber_img)
+    labeled_image_path = f"{output_dir}/labeled_myofibers_{timestamp}.png"
+    io.imsave(labeled_image_path, (labeled_image * 255).astype(np.uint8))
+
+    # Create research log
+    log = f"""
+MYOFIBER MORPHOLOGICAL ANALYSIS REPORT
+======================================
+Date: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+Image: {image_path}
+
+ANALYSIS STEPS:
+1. Loaded multichannel microscopy image
+2. Extracted nuclei (channel {nuclei_channel}) and myofiber (channel {myofiber_channel}) signals
+3. Enhanced contrast using adaptive histogram equalization
+4. Segmented nuclei using {threshold_method} thresholding
+5. Segmented myofibers using {threshold_method} thresholding
+6. Performed morphological operations to refine segmentation
+7. Identified and measured individual myofibers and nuclei
+
+RESULTS:
+- Total myofibers detected: {len(myofiber_props)}
+- Total nuclei detected: {nuclei_total}
+- Nuclei inside myofibers: {nuclei_inside} ({percent_inside:.2f}%)
+- Mean myofiber area: {mean_area:.2f} pixels
+- Mean myofiber perimeter: {mean_perimeter:.2f} pixels
+- Mean myofiber eccentricity: {mean_eccentricity:.2f}
+
+FILES GENERATED:
+- Morphological measurements: {results_file}
+- Labeled myofiber image: {labeled_image_path}
+"""
+
+    return log
+
+
+def decode_behavior_from_neural_trajectories(neural_data, behavioral_data, n_components=10, output_dir="./"):
+    """Model neural activity trajectories and decode behavioral variables.
+
+    Parameters
+    ----------
+    neural_data : numpy.ndarray
+        Neural spiking activity data, shape (n_timepoints, n_neurons)
+    behavioral_data : numpy.ndarray
+        Behavioral data, shape (n_timepoints, n_behavioral_variables)
+    n_components : int, optional
+        Number of principal components to use for dimensionality reduction, default is 10
+    output_dir : str, optional
+        Directory to save output files, default is "./"
+
+    Returns
+    -------
+    str
+        Research log summarizing the steps taken and results
+
+    """
+    import os
+    import pickle
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from pykalman import KalmanFilter
+    from sklearn.decomposition import PCA
+    from sklearn.metrics import mean_squared_error
+    from sklearn.model_selection import train_test_split
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Initialize research log
+    log = "# Neural Trajectory Modeling and Decoding Research Log\n\n"
+
+    # Step 1: Preprocess the data
+    log += "## Step 1: Data Preprocessing\n"
+    log += f"- Neural data shape: {neural_data.shape}\n"
+    log += f"- Behavioral data shape: {behavioral_data.shape}\n"
+
+    # Check for NaN values and replace with zeros
+    neural_data = np.nan_to_num(neural_data)
+    behavioral_data = np.nan_to_num(behavioral_data)
+
+    # Split data into training and testing sets
+    X_train, X_test, y_train, y_test = train_test_split(neural_data, behavioral_data, test_size=0.2, random_state=42)
+    log += f"- Training set size: {X_train.shape[0]} samples\n"
+    log += f"- Testing set size: {X_test.shape[0]} samples\n\n"
+
+    # Step 2: Dimensionality reduction with PCA
+    log += "## Step 2: Dimensionality Reduction\n"
+    log += f"- Reducing neural data from {neural_data.shape[1]} dimensions to {n_components} components\n"
+
+    pca = PCA(n_components=n_components)
+    X_train_pca = pca.fit_transform(X_train)
+    X_test_pca = pca.transform(X_test)
+
+    explained_variance = np.sum(pca.explained_variance_ratio_) * 100
+    log += f"- Total variance explained: {explained_variance:.2f}%\n\n"
+
+    # Save PCA components visualization
+    try:
+        plt.figure(figsize=(10, 6))
+        plt.bar(range(1, n_components + 1), pca.explained_variance_ratio_)
+        plt.xlabel("Principal Component")
+        plt.ylabel("Explained Variance Ratio")
+        plt.title("PCA Components Explained Variance")
+        plt.xticks(range(1, n_components + 1))
+        plt.tight_layout()
+
+        pca_plot_path = os.path.join(output_dir, "pca_explained_variance.png")
+        plt.savefig(pca_plot_path, dpi=300)
+        plt.close()
+
+        log += f"- PCA components visualization saved to: {pca_plot_path}\n\n"
+    except Exception as e:
+        log += f"- Error creating PCA visualization: {str(e)}\n\n"
+
+    # Step 3: Train a Kalman filter for decoding
+    log += "## Step 3: Trajectory Modeling and Decoding\n"
+    log += "- Training Kalman filter to decode behavioral variables from neural trajectories\n"
+
+    # Initialize and train Kalman filter
+    kf = KalmanFilter(initial_state_mean=np.zeros(y_train.shape[1]), n_dim_obs=X_train_pca.shape[1])
+
+    # Fit the Kalman filter to the data
+    kf.em(X_train_pca, y_train)
+
+    # Step 4: Decode behavioral variables
+    log += "## Step 4: Decoding Behavioral Variables\n"
+
+    # Use the Kalman filter to predict behavioral variables
+    y_pred, _ = kf.filter(X_test_pca)
+
+    # Evaluate performance
+    mse = mean_squared_error(y_test, y_pred)
+    log += f"- Mean squared error on test set: {mse:.4f}\n\n"
+
+    # Save the decoded trajectories visualization
+    try:
+        if y_test.shape[1] >= 2:
+            # Create visualization of true vs. predicted trajectories (first 2 dimensions)
+            plt.figure(figsize=(12, 6))
+
+            # First behavioral variable
+            plt.subplot(1, 2, 1)
+            plt.plot(y_test[:, 0], label="True")
+            plt.plot(y_pred[:, 0], label="Predicted")
+            plt.xlabel("Time steps")
+            plt.ylabel("Behavioral Variable 1")
+            plt.title("Decoding Performance - Variable 1")
+            plt.legend()
+
+            # Second behavioral variable
+            plt.subplot(1, 2, 2)
+            plt.plot(y_test[:, 1], label="True")
+            plt.plot(y_pred[:, 1], label="Predicted")
+            plt.xlabel("Time steps")
+            plt.ylabel("Behavioral Variable 2")
+            plt.title("Decoding Performance - Variable 2")
+            plt.legend()
+
+            plt.tight_layout()
+
+            trajectory_plot_path = os.path.join(output_dir, "decoded_trajectories.png")
+            plt.savefig(trajectory_plot_path, dpi=300)
+            plt.close()
+
+            log += f"- Decoded trajectories visualization saved to: {trajectory_plot_path}\n"
+    except Exception as e:
+        log += f"- Error creating trajectory visualization: {str(e)}\n"
+
+    # Save the results as a pickle file
+    results = {
+        "true_behavior": y_test,
+        "predicted_behavior": y_pred,
+        "pca_model": pca,
+        "kalman_filter": kf,
+        "mse": mse,
+    }
+
+    results_file = os.path.join(output_dir, "neural_decoding_results.pkl")
+    with open(results_file, "wb") as f:
+        pickle.dump(results, f)
+
+    # Also save a CSV with the first few predicted vs. actual values for easier inspection
+    try:
+        import pandas as pd
+
+        n_samples = min(100, y_test.shape[0])
+        n_vars = y_test.shape[1]
+
+        results_data = {}
+        for i in range(n_vars):
+            results_data[f"true_var{i + 1}"] = y_test[:n_samples, i]
+            results_data[f"pred_var{i + 1}"] = y_pred[:n_samples, i]
+
+        results_df = pd.DataFrame(results_data)
+        csv_path = os.path.join(output_dir, "decoding_results_sample.csv")
+        results_df.to_csv(csv_path, index=False)
+
+        log += f"- Sample of decoding results saved to: {csv_path}\n"
+    except Exception as e:
+        log += f"- Error creating CSV results: {str(e)}\n"
+
+    log += "\n## Results\n"
+    log += f"- Full decoded behavioral trajectories saved to: {results_file}\n"
+    log += f"- Decoder performance (MSE): {mse:.4f}\n"
+
+    # Save the log to a file
+    log_file = os.path.join(output_dir, "neural_decoding_log.txt")
+    with open(log_file, "w") as f:
+        f.write(log)
+
+    log += f"- Analysis log saved to: {log_file}\n"
+
+    return log
+
+
+def simulate_whole_cell_ode_model(
+    initial_conditions,
+    parameters,
+    ode_function=None,
+    time_span=(0, 100),
+    time_points=1000,
+    method="LSODA",
+):
+    """Simulate a whole-cell model represented as a system of ordinary differential equations (ODEs).
+
+    Parameters
+    ----------
+    initial_conditions : dict or array-like
+        Initial values for each state variable in the model. If dict, keys are variable names
+        and values are initial concentrations/values. If array-like, order must match the
+        order expected by the ODE function.
+    parameters : dict
+        Model parameters required by the ODE function. Keys are parameter names and
+        values are parameter values.
+    ode_function : callable, optional
+        Function defining the system of ODEs. Should take arguments ``(t, y, *args)`` where
+        ``t`` is time, ``y`` is the state vector, and ``args`` contains additional parameters.
+        If None, a simple example whole-cell model will be used.
+    time_span : tuple, default=(0, 100)
+        Tuple of (start_time, end_time) for the simulation.
+    time_points : int, default=1000
+        Number of time points to evaluate.
+    method : str, default='LSODA'
+        Numerical integration method to use (e.g., 'RK45', 'LSODA', 'BDF').
+
+    Returns
+    -------
+    str
+        Research log summarizing the simulation steps and results. Results are saved
+        to a CSV file and the filename is included in the log.
+
+    """
+    from datetime import datetime
+
+    import numpy as np
+    import pandas as pd
+    from scipy.integrate import solve_ivp
+
+    # Define a default ODE function if none is provided
+    if ode_function is None:
+
+        def default_whole_cell_model(t, y, params):
+            # Unpack state variables
+            # Simple model with:
+            # - mRNA (y[0])
+            # - Protein (y[1])
+            # - Metabolite (y[2])
+            # - ATP (y[3])
+            mRNA, protein, metabolite, atp = y
+
+            # Unpack parameters
+            k_transcription = params["k_transcription"]  # mRNA synthesis rate
+            k_translation = params["k_translation"]  # Protein synthesis rate
+            k_mrna_deg = params["k_mrna_deg"]  # mRNA degradation rate
+            k_protein_deg = params["k_protein_deg"]  # Protein degradation rate
+            k_metabolism = params["k_metabolism"]  # Metabolite production rate
+            k_atp_production = params["k_atp_production"]  # ATP production rate
+            k_atp_consumption = params["k_atp_consumption"]  # ATP consumption rate
+
+            # ODEs
+            dmRNA_dt = k_transcription - k_mrna_deg * mRNA
+            dprotein_dt = k_translation * mRNA * atp - k_protein_deg * protein
+            dmetabolite_dt = k_metabolism * protein - k_atp_production * metabolite
+            datp_dt = k_atp_production * metabolite - k_atp_consumption * atp - k_translation * mRNA * atp
+
+            return [dmRNA_dt, dprotein_dt, dmetabolite_dt, datp_dt]
+
+        ode_function = default_whole_cell_model
+
+    # Prepare initial conditions as array
+    if isinstance(initial_conditions, dict):
+        y0_values = list(initial_conditions.values())
+        variable_names = list(initial_conditions.keys())
+    else:
+        y0_values = initial_conditions
+        variable_names = [f"Variable_{i}" for i in range(len(initial_conditions))]
+
+    # Set up time points
+    t_eval = np.linspace(time_span[0], time_span[1], time_points)
+
+    # Start research log
+    log = []
+    log.append("# Whole-Cell ODE Model Simulation")
+    log.append(f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append("\n## Simulation Setup")
+    log.append(f"- Integration method: {method}")
+    log.append(f"- Time span: {time_span[0]} to {time_span[1]} time units")
+    log.append(f"- Number of time points: {time_points}")
+    log.append(f"- Number of state variables: {len(y0_values)}")
+    log.append("\n## Initial Conditions")
+    for _i, (name, value) in enumerate(zip(variable_names, y0_values, strict=False)):
+        log.append(f"- {name}: {value}")
+
+    log.append("\n## Model Parameters")
+    for param, value in parameters.items():
+        log.append(f"- {param}: {value}")
+
+    # Solve the ODE system
+    log.append("\n## Running Simulation")
+    try:
+        solution = solve_ivp(
+            lambda t, y: ode_function(t, y, parameters),
+            time_span,
+            y0_values,
+            method=method,
+            t_eval=t_eval,
+        )
+
+        # Check if simulation was successful
+        if solution.success:
+            log.append("Simulation completed successfully.")
+            log.append(f"- Number of function evaluations: {solution.nfev}")
+            log.append(f"- Number of Jacobian evaluations: {solution.njev}")
+            log.append(f"- Number of steps: {len(solution.t)}")
+
+            # Create DataFrame with results
+            results_df = pd.DataFrame(solution.y.T, columns=variable_names)
+            results_df.insert(0, "Time", solution.t)
+
+            # Save results to CSV
+            filename = f"whole_cell_simulation_results_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+            results_df.to_csv(filename, index=False)
+
+            log.append("\n## Results Summary")
+            log.append(f"Simulation results saved to: {filename}")
+
+            # Calculate some basic statistics
+            final_state = results_df.iloc[-1].drop("Time").to_dict()
+            log.append("\n## Final State")
+            for var, value in final_state.items():
+                log.append(f"- {var}: {value:.6f}")
+
+        else:
+            log.append(f"Simulation failed with message: {solution.message}")
+
+    except Exception as e:
+        log.append(f"Error during simulation: {str(e)}")
+
+    # Return the research log
+    return "\n".join(log)

Biomanus_upload/biomni/tool/bioimaging.py

@@ -0,0 +1,1394 @@
+import logging
+import os
+import zipfile
+
+import matplotlib
+import requests
+
+matplotlib.use("Agg")  # Use non-interactive backend
+import nibabel as nib
+import numpy as np
+import SimpleITK as sitk
+import torch
+import torch.serialization
+from nnunet.inference.predict import predict_from_folder
+
+# Apply safe globals for torch serialization
+torch.serialization.add_safe_globals([tuple, list, dict, set, int, float, str, bytes, bytearray])
+torch.serialization.add_safe_globals([complex, slice, range])
+torch.serialization.add_safe_globals([np.core.multiarray.scalar])
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# SEGMENTATION CLASS
+# ============================================================================
+
+
+class SegmentationTool:
+    """
+    A comprehensive tool for medical image segmentation using nnUNet.
+    Handles BRATS dataset processing, modality splitting, and segmentation visualization.
+    """
+
+    def __init__(self):
+        """Initialize the SegmentationTool."""
+        self.supported_formats = [".nii", ".nii.gz"]
+        logger.info("SegmentationTool initialized")
+
+    def split_modalities(self, input_file, output_dir, case_name="BRAT"):
+        """
+        Split a 4D NIfTI file into separate modality files for nnUNet
+        Args:
+            input_file: Path to the 4D NIfTI file
+            output_dir: Directory to save the split files
+            case_name: Base name for the case (default: BRAT)
+        Returns:
+            output_dir: Path to directory containing split modality files
+        """
+        os.makedirs(output_dir, exist_ok=True)
+
+        # Load the 4D image
+        print(f"Loading {input_file}...")
+        img = nib.load(input_file)
+        data = img.get_fdata()
+
+        print(f"Image shape: {data.shape}")
+        print("Expected shape: (X, Y, Z, 4) for 4 modalities")
+
+        if len(data.shape) != 4:
+            raise ValueError(f"Expected 4D image, got {len(data.shape)}D")
+
+        if data.shape[3] != 4:
+            raise ValueError(f"Expected 4 modalities, got {data.shape[3]}")
+
+        # Split into separate files
+        modalities = ["FLAIR", "T1w", "t1gd", "T2w"]
+
+        for i, modality in enumerate(modalities):
+            # Extract the modality data
+            modality_data = data[:, :, :, i]
+
+            # Create a new NIfTI image with the same header but 3D data
+            modality_img = nib.Nifti1Image(modality_data, img.affine, img.header)
+
+            # Save with the expected naming convention
+            output_file = os.path.join(output_dir, f"{case_name}_{i:04d}.nii.gz")
+            nib.save(modality_img, output_file)
+
+            print(f"Saved {modality} modality to {output_file}")
+            print(f"  Shape: {modality_data.shape}, Data type: {modality_data.dtype}")
+
+        print(f"\nAll modalities saved to {output_dir}")
+        return output_dir
+
+    def prepare_input_for_nnunet(self, input_path, output_dir, case_name="BRAT"):
+        """
+        Prepare input data for nnUNet by handling both 4D and pre-split modality files
+        Args:
+            input_path: Path to input file or directory
+            output_dir: Directory to save prepared files
+            case_name: Base name for the case (default: BRAT)
+        Returns:
+            prepared_dir: Path to directory with nnUNet-ready files
+        """
+        os.makedirs(output_dir, exist_ok=True)
+
+        if os.path.isfile(input_path):
+            # Single file - check if it's 4D
+            if input_path.endswith((".nii", ".nii.gz")):
+                try:
+                    img = nib.load(input_path)
+                    if len(img.shape) == 4 and img.shape[3] == 4:
+                        print("4D NIfTI file detected, splitting modalities...")
+                        return self.split_modalities(input_path, output_dir, case_name)
+                    else:
+                        print("Single 3D file detected, copying to output directory...")
+                        # Copy single file with proper naming
+                        output_file = os.path.join(output_dir, f"{case_name}_0000.nii.gz")
+                        import shutil
+
+                        shutil.copy2(input_path, output_file)
+                        return output_dir
+                except Exception as e:
+                    print(f"Error reading file {input_path}: {e}")
+                    raise
+        elif os.path.isdir(input_path):
+            # Directory - check if it already has split modalities
+            files = [f for f in os.listdir(input_path) if f.endswith((".nii", ".nii.gz"))]
+
+            if any(f.endswith("_0000.nii.gz") for f in files):
+                print("Directory already contains split modality files, using as-is...")
+                # Copy existing files to output directory
+                for f in files:
+                    if f.endswith((".nii", ".nii.gz")):
+                        import shutil
+
+                        shutil.copy2(os.path.join(input_path, f), os.path.join(output_dir, f))
+                return output_dir
+            else:
+                # Check if there's a 4D file to split
+                for f in files:
+                    if f.endswith((".nii", ".nii.gz")):
+                        try:
+                            img = nib.load(os.path.join(input_path, f))
+                            if len(img.shape) == 4 and img.shape[3] == 4:
+                                print(f"4D NIfTI file {f} detected, splitting modalities...")
+                                return self.split_modalities(os.path.join(input_path, f), output_dir, case_name)
+                        except Exception as e:
+                            logging.debug("Skipping file %s during 4D check: %s", f, e)
+                            continue
+
+                print("No 4D files found, copying existing files...")
+                # Copy existing files to output directory
+                for f in files:
+                    if f.endswith((".nii", ".nii.gz")):
+                        import shutil
+
+                        shutil.copy2(os.path.join(input_path, f), os.path.join(output_dir, f))
+                return output_dir
+
+        raise ValueError(f"Input path {input_path} is neither a valid file nor directory")
+
+    def setup_nnunet_environment(self, results_folder=None, raw_data_base=None, preprocessed=None):
+        """
+        Setup nnU-Net environment variables according to official documentation
+        Args:
+            results_folder: Path to nnUNet results folder (default: ~/nnUNet_results)
+            raw_data_base: Path to raw data base (default: ~/nnUNet_raw_data_base)
+            preprocessed: Path to preprocessed data (default: ~/nnUNet_preprocessed)
+        """
+        # Set nnUNet environment variables as per official documentation
+        if results_folder:
+            os.environ["nnUNet_RESULTS_FOLDER"] = os.path.expanduser(results_folder)
+        elif "nnUNet_RESULTS_FOLDER" not in os.environ:
+            os.environ["nnUNet_RESULTS_FOLDER"] = os.path.expanduser("~/nnUNet_results")
+
+        if raw_data_base:
+            os.environ["nnUNet_raw_data_base"] = os.path.expanduser(raw_data_base)
+        elif "nnUNet_raw_data_base" not in os.environ:
+            os.environ["nnUNet_raw_data_base"] = os.path.expanduser("~/nnUNet_raw_data_base")
+
+        if preprocessed:
+            os.environ["nnUNet_preprocessed"] = os.path.expanduser(preprocessed)
+        elif "nnUNet_preprocessed" not in os.environ:
+            os.environ["nnUNet_preprocessed"] = os.path.expanduser("~/nnUNet_preprocessed")
+
+        # Create directories if they don't exist
+        for path in [
+            os.environ["nnUNet_RESULTS_FOLDER"],
+            os.environ["nnUNet_raw_data_base"],
+            os.environ["nnUNet_preprocessed"],
+        ]:
+            os.makedirs(path, exist_ok=True)
+
+        print("nnU-Net environment variables set:")
+        print(f"  nnUNet_RESULTS_FOLDER: {os.environ['nnUNet_RESULTS_FOLDER']}")
+        print(f"  nnUNet_raw_data_base: {os.environ['nnUNet_raw_data_base']}")
+        print(f"  nnUNet_preprocessed: {os.environ['nnUNet_preprocessed']}")
+
+    def _download_model_with_browser_headers(self, url, output_path):
+        """
+        Download model with browser-like headers to bypass Zenodo's anti-bot protection
+        """
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+            "Accept-Language": "en-US,en;q=0.5",
+            "Accept-Encoding": "gzip, deflate",
+            "Connection": "keep-alive",
+            "Upgrade-Insecure-Requests": "1",
+        }
+
+        logger.info(f"Downloading model from: {url}")
+
+        try:
+            response = requests.get(url, headers=headers, stream=True, timeout=300)
+            response.raise_for_status()
+
+            with open(output_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+
+            logger.info(f"Download completed: {output_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Download failed: {e}")
+            if os.path.exists(output_path):
+                os.remove(output_path)
+            return False
+
+    def _download_and_extract_model(self, task_id, model_type="3d_fullres"):
+        """
+        Download and extract nnUNet model with browser-like headers - extracts directly to nnUNet directory
+        """
+        results_folder = os.environ.get("nnUNet_RESULTS_FOLDER", "~/nnUNet_results")
+        results_folder = os.path.expanduser(results_folder)
+
+        # Create the nnUNet directory
+        nnunet_dir = os.path.join(results_folder, "nnUNet")
+        os.makedirs(nnunet_dir, exist_ok=True)
+
+        # Check if model already exists
+        task_dir = os.path.join(nnunet_dir, model_type, task_id)
+        if os.path.exists(task_dir):
+            # Check if it has the expected structure
+            plans_file = os.path.join(task_dir, "nnUNetTrainerV2__nnUNetPlansv2.1")
+            if os.path.exists(plans_file):
+                logger.info(f"Model already exists for task '{task_id}' with {model_type}")
+                return True
+
+        # Download URL for the task
+        download_url = f"https://zenodo.org/record/4003545/files/{task_id}.zip?download=1"
+
+        # Create temporary file for download
+        temp_zip = os.path.join(nnunet_dir, f"{task_id}_temp.zip")
+
+        # Download with browser headers
+        if self._download_model_with_browser_headers(download_url, temp_zip):
+            try:
+                logger.info(f"Extracting {temp_zip} to {nnunet_dir}")
+                with zipfile.ZipFile(temp_zip, "r") as zip_ref:
+                    zip_ref.extractall(nnunet_dir)
+
+                # Remove temporary zip file
+                os.remove(temp_zip)
+
+                # Verify extraction worked
+                if os.path.exists(task_dir):
+                    logger.info(f"Model successfully downloaded and extracted for task '{task_id}'")
+                    logger.info(f"Model directory: {task_dir}")
+                    return True
+                else:
+                    logger.error(f"Task directory not found after extraction: {task_dir}")
+                    return False
+
+            except Exception as e:
+                logger.error(f"Extraction failed: {e}")
+                if os.path.exists(temp_zip):
+                    os.remove(temp_zip)
+                return False
+        else:
+            return False
+
+    def segment_with_nn_unet(
+        self,
+        image_path,
+        output_dir,
+        task_id,
+        model_type="3d_fullres",
+        folds=None,
+        use_tta=False,
+        num_threads=1,
+        mixed_precision=True,
+        verbose=True,
+        auto_prepare_input=True,
+        results_folder=None,
+        auto_download=True,
+    ):
+        """
+        Segment images using nnUNet with proper environment setup and automatic model downloading
+        Args:
+            image_path: Path to input image file or directory
+            output_dir: Directory to save segmentation results
+            task_id: Task identifier (e.g., 'Task001_BrainTumour')
+            model_type: Model type (default: '3d_fullres')
+            folds: Model folds to use (default: [0, 1, 2, 3, 4])
+            use_tta: Use test time augmentation (default: False)
+            num_threads: Number of threads for preprocessing (default: 1)
+            mixed_precision: Use mixed precision (default: True)
+            verbose: Verbose logging (default: True)
+            auto_prepare_input: Automatically prepare input for nnUNet (default: True)
+            results_folder: Path to nnUNet results folder (default: None, will use environment variable or default)
+            auto_download: Automatically download missing models (default: True)
+        """
+        if folds is None:
+            folds = [0, 1, 2, 3, 4]
+        os.makedirs(output_dir, exist_ok=True)
+        logging.basicConfig(level=logging.INFO if verbose else logging.WARNING)
+
+        # Setup nnUNet environment first
+        self.setup_nnunet_environment(results_folder=results_folder)
+
+        # Prepare input data if requested
+        if auto_prepare_input:
+            temp_input_dir = os.path.join(output_dir, "temp_input")
+            prepared_input_dir = self.prepare_input_for_nnunet(image_path, temp_input_dir)
+            image_path = prepared_input_dir
+            logging.info(f"Input prepared for nnUNet: {image_path}")
+
+        logging.info("Verifying NIfTI input files...")
+
+        def verify_nifti_input(image_path):
+            if os.path.isfile(image_path):
+                nib.load(image_path)
+            else:
+                for file in os.listdir(image_path):
+                    if file.endswith(".nii") or file.endswith(".nii.gz"):
+                        nib.load(os.path.join(image_path, file))
+
+        verify_nifti_input(image_path)
+
+        # Get or set up the results folder
+        results_folder = os.environ.get("nnUNet_RESULTS_FOLDER")
+        if not results_folder:
+            # Try common locations
+            common_paths = [
+                "./models/nnUNet",
+                "~/nnUNet_results",
+                "~/biomni_models/nnUNet",
+            ]
+
+            for base_path in common_paths:
+                expanded_path = os.path.expanduser(base_path)
+                if os.path.exists(expanded_path):
+                    results_folder = expanded_path
+                    break
+
+            # If still no folder found, create one
+            if not results_folder:
+                results_folder = os.path.expanduser("~/nnUNet_results")
+                os.makedirs(results_folder, exist_ok=True)
+                logging.info(f"Created new results folder: {results_folder}")
+
+        os.environ["RESULTS_FOLDER"] = results_folder
+        os.environ["nnUNet_RESULTS_FOLDER"] = results_folder
+        logging.info(f"Set RESULTS_FOLDER environment variable to: {results_folder}")
+
+        # Construct the expected model path - using the correct structure
+        model_folder = os.path.join(results_folder, "nnUNet", model_type, task_id, "nnUNetTrainerV2__nnUNetPlansv2.1")
+
+        logging.info(f"Looking for model at: {model_folder}")
+
+        # Check if model files actually exist (not just the directory)
+        def check_model_files_exist(model_folder, folds):
+            """Check if actual model weight files exist for the specified folds"""
+            if not os.path.exists(model_folder):
+                return False
+
+            # Check for plans.pkl and other required files
+            required_files = ["plans.pkl"]
+            for req_file in required_files:
+                if not os.path.exists(os.path.join(model_folder, req_file)):
+                    return False
+
+            # Check if at least one fold has model files
+            for fold in folds:
+                fold_dir = os.path.join(model_folder, f"fold_{fold}")
+                if os.path.exists(fold_dir):
+                    # Look for model files (.model, .model.pkl, etc.)
+                    model_files = [f for f in os.listdir(fold_dir) if f.endswith((".model", ".model.pkl"))]
+                    if model_files:
+                        return True
+            return False
+
+        # Check if model exists, download if not
+        if not check_model_files_exist(model_folder, folds):
+            if auto_download:
+                logging.info(f"Model weights for {task_id} not found. Downloading...")
+                # Ensure the results folder structure exists
+                os.makedirs(os.path.dirname(model_folder), exist_ok=True)
+
+                # Download the model using our custom download function
+                if self._download_and_extract_model(task_id, model_type):
+                    logging.info(f"Downloaded pretrained model for {task_id} successfully.")
+                else:
+                    raise RuntimeError(f"Failed to download model for {task_id}")
+
+                # Verify the download worked
+                if not check_model_files_exist(model_folder, folds):
+                    raise RuntimeError(
+                        f"Model download completed but files not found at expected location: {model_folder}"
+                    )
+            else:
+                # Ask user for permission to download
+                user_input = (
+                    input(f"Model weights for {task_id} not found. Do you want to download them? (y/n): ")
+                    .strip()
+                    .lower()
+                )
+                if user_input == "y":
+                    # Download the model using our custom download function
+                    if self._download_and_extract_model(task_id, model_type):
+                        logging.info(f"Downloaded pretrained model for {task_id} successfully.")
+                    else:
+                        raise RuntimeError(f"Failed to download model for {task_id}")
+                else:
+                    raise RuntimeError("Model weights not found and download declined by user.")
+
+        # Double-check that we now have the model
+        if not check_model_files_exist(model_folder, folds):
+            raise RuntimeError(f"Model files still not found at {model_folder} after download attempt")
+
+        logging.info(f"Using model: {model_folder}")
+
+        # Patch torch.load for compatibility
+        original_torch_load = torch.load
+
+        def patched_torch_load(*args, **kwargs):
+            kwargs["weights_only"] = False
+            return original_torch_load(*args, **kwargs)
+
+        # Run the segmentation
+        torch.load = patched_torch_load
+        try:
+            predict_from_folder(
+                model=model_folder,
+                input_folder=image_path,
+                output_folder=output_dir,
+                folds=folds,
+                save_npz=False,
+                num_threads_preprocessing=num_threads,
+                num_threads_nifti_save=num_threads,
+                mixed_precision=mixed_precision,
+                lowres_segmentations=None,
+                part_id=0,
+                num_parts=1,
+                tta=use_tta,
+            )
+        finally:
+            # Restore original torch.load behavior
+            torch.load = original_torch_load
+
+        # Clean up temporary input directory if it was created
+        if auto_prepare_input and os.path.exists(temp_input_dir):
+            import shutil
+
+            shutil.rmtree(temp_input_dir)
+            logging.info("Cleaned up temporary input directory")
+
+        logging.info(f"Segmentation outputs stored at: {output_dir}")
+        return output_dir
+
+    def create_segmentation_visualization(self, original_mri, segmentation, output_dir="./visualization_output"):
+        """
+        Create and save visualization of segmentation results using nilearn
+        Args:
+            original_mri: Path to original MRI file
+            segmentation: Path to segmentation file
+            output_dir: Directory to save visualization images
+        Returns:
+            list: List of saved image file paths
+        """
+        try:
+            # Import nilearn here to avoid dependency issues
+            from nilearn import plotting
+
+            # Create output directory
+            os.makedirs(output_dir, exist_ok=True)
+
+            # Check if files exist
+            if not os.path.exists(original_mri):
+                raise FileNotFoundError(f"Original MRI file not found: {original_mri}")
+
+            if not os.path.exists(segmentation):
+                raise FileNotFoundError(f"Segmentation file not found: {segmentation}")
+
+            print("✅ Files found, creating visualizations...")
+            saved_files = []
+
+            # Create and save the main overlay plot
+            display = plotting.plot_roi(
+                segmentation,
+                bg_img=original_mri,
+                cmap="Set1",
+                alpha=0.6,
+                title="Segmentation Overlay",
+            )
+
+            # Save the main overlay plot
+            output_file = os.path.join(output_dir, "segmentation_overlay.png")
+            display.savefig(output_file, dpi=150, bbox_inches="tight")
+            saved_files.append(output_file)
+            print(f"✅ Main overlay saved to: {output_file}")
+            display.close()
+
+            # Create additional views and save them
+            # Axial view
+            display_axial = plotting.plot_roi(
+                segmentation,
+                bg_img=original_mri,
+                cmap="Set1",
+                alpha=0.6,
+                title="Segmentation Overlay - Axial View",
+                display_mode="z",
+            )
+            axial_file = os.path.join(output_dir, "segmentation_axial.png")
+            display_axial.savefig(axial_file, dpi=150, bbox_inches="tight")
+            saved_files.append(axial_file)
+            print(f"✅ Axial view saved to: {axial_file}")
+            display_axial.close()
+
+            # Sagittal view
+            display_sagittal = plotting.plot_roi(
+                segmentation,
+                bg_img=original_mri,
+                cmap="Set1",
+                alpha=0.6,
+                title="Segmentation Overlay - Sagittal View",
+                display_mode="x",
+            )
+            sagittal_file = os.path.join(output_dir, "segmentation_sagittal.png")
+            display_sagittal.savefig(sagittal_file, dpi=150, bbox_inches="tight")
+            saved_files.append(sagittal_file)
+            print(f"✅ Sagittal view saved to: {sagittal_file}")
+            display_sagittal.close()
+
+            # Coronal view
+            display_coronal = plotting.plot_roi(
+                segmentation,
+                bg_img=original_mri,
+                cmap="Set1",
+                alpha=0.6,
+                title="Segmentation Overlay - Coronal View",
+                display_mode="y",
+            )
+            coronal_file = os.path.join(output_dir, "segmentation_coronal.png")
+            display_coronal.savefig(coronal_file, dpi=150, bbox_inches="tight")
+            saved_files.append(coronal_file)
+            print(f"✅ Coronal view saved to: {coronal_file}")
+            display_coronal.close()
+
+            print(f"\n✅ All visualizations saved to: {output_dir}")
+            print("Files created:")
+            for file_path in saved_files:
+                print(f"  - {os.path.basename(file_path)}")
+
+            return saved_files
+
+        except ImportError:
+            print(" nilearn not available. Install with: pip install nilearn")
+            return []
+        except Exception as e:
+            print(f" Visualization failed: {e}")
+            import traceback
+
+            traceback.print_exc()
+            return []
+
+
+# ============================================================================
+# IMAGE REGISTRATION CLASS
+# ============================================================================
+
+
+class ImageRegistrationTool:
+    """
+    A comprehensive tool for medical image registration using SimpleITK.
+    Supports rigid, affine, and deformable registration with preprocessing and visualization.
+    """
+
+    def __init__(self):
+        """Initialize the ImageRegistrationTool."""
+        self.supported_formats = [".nii", ".nii.gz", ".nrrd", ".mha", ".mhd"]
+        logger.info("ImageRegistrationTool initialized")
+
+    def load_image(self, image_path: str) -> sitk.Image:
+        """
+        Load a medical image using SimpleITK.
+
+        Args:
+            image_path: Path to the image file
+
+        Returns:
+            SimpleITK Image object
+        """
+        if not os.path.exists(image_path):
+            raise FileNotFoundError(f"Image file not found: {image_path}")
+
+        logger.info(f"Loading image: {image_path}")
+        try:
+            image = sitk.ReadImage(image_path)
+            logger.info(f"Successfully loaded image with size: {image.GetSize()}")
+            return image
+        except Exception as e:
+            logger.error(f"Failed to load image {image_path}: {e}")
+            raise
+
+    def save_image(self, image: sitk.Image, output_path: str) -> None:
+        """
+        Save a SimpleITK image to file.
+
+        Args:
+            image: SimpleITK Image object
+            output_path: Path to save the image (must include filename and extension)
+        """
+        # Validate output path
+        if os.path.isdir(output_path):
+            raise ValueError(
+                f"Output path '{output_path}' is a directory. Please provide a file path with extension (e.g., '.nii.gz', '.png', '.jpg')"
+            )
+
+        if not os.path.splitext(output_path)[1]:
+            raise ValueError(
+                f"Output path '{output_path}' has no file extension. Please add an extension (e.g., '.nii.gz', '.png', '.jpg')"
+            )
+
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        logger.info(f"Saving image to: {output_path}")
+        try:
+            sitk.WriteImage(image, output_path)
+            logger.info("Image saved successfully")
+        except Exception as e:
+            logger.error(f"Failed to save image to {output_path}: {e}")
+            raise
+
+    def preprocess_image(self, image: sitk.Image, denoise: bool = True, normalize: bool = True) -> sitk.Image:
+        """
+        Preprocess an image with denoising and normalization.
+
+        Args:
+            image: Input SimpleITK image
+            denoise: Whether to apply denoising
+            normalize: Whether to apply normalization
+
+        Returns:
+            Preprocessed SimpleITK image
+        """
+        logger.info("Preprocessing image...")
+        processed_image = sitk.Image(image)
+
+        if denoise:
+            # Apply Gaussian smoothing for denoising
+            processed_image = sitk.SmoothingRecursiveGaussian(processed_image, sigma=1.0)
+            logger.info("Applied denoising")
+
+        if normalize:
+            # Normalize to [0, 1] range
+            min_max_filter = sitk.MinimumMaximumImageFilter()
+            min_max_filter.Execute(processed_image)
+            min_val = min_max_filter.GetMinimum()
+            max_val = min_max_filter.GetMaximum()
+
+            if max_val > min_val:
+                processed_image = sitk.IntensityWindowing(
+                    processed_image, windowMinimum=min_val, windowMaximum=max_val, outputMinimum=0.0, outputMaximum=1.0
+                )
+                logger.info("Applied normalization")
+
+        return processed_image
+
+    def create_rigid_transform(
+        self, fixed_image: sitk.Image, moving_image: sitk.Image, initial_transform: sitk.Transform | None = None
+    ) -> sitk.Transform:
+        """
+        Create a rigid transform for image registration.
+
+        Args:
+            fixed_image: Reference (fixed) image
+            moving_image: Image to be registered
+            initial_transform: Optional initial transform
+
+        Returns:
+            Rigid transform object
+        """
+        logger.info("Creating rigid transform...")
+
+        if initial_transform is None:
+            # Create identity transform
+            transform = sitk.Euler3DTransform()
+        else:
+            transform = initial_transform
+
+        return transform
+
+    def create_affine_transform(
+        self, fixed_image: sitk.Image, moving_image: sitk.Image, initial_transform: sitk.Transform | None = None
+    ) -> sitk.Transform:
+        """
+        Create an affine transform for image registration.
+
+        Args:
+            fixed_image: Reference (fixed) image
+            moving_image: Image to be registered
+            initial_transform: Optional initial transform
+
+        Returns:
+            Affine transform object
+        """
+        logger.info("Creating affine transform...")
+
+        if initial_transform is None:
+            # Create identity transform
+            transform = sitk.AffineTransform(3)
+        else:
+            transform = initial_transform
+
+        return transform
+
+    def create_deformable_transform(
+        self, fixed_image: sitk.Image, moving_image: sitk.Image, number_of_control_points: int = 4
+    ) -> sitk.Transform:
+        """
+        Create a deformable (B-spline) transform for image registration.
+
+        Args:
+            fixed_image: Reference (fixed) image
+            moving_image: Image to be registered
+            number_of_control_points: Number of B-spline control points per dimension
+
+        Returns:
+            Deformable transform object
+        """
+        logger.info("Creating deformable transform...")
+
+        # Create B-spline transform
+        transform = sitk.BSplineTransformInitializer(fixed_image, [number_of_control_points] * 3, order=3)
+
+        return transform
+
+    def setup_registration_method(
+        self,
+        transform: sitk.Transform,
+        metric: str = "mutual_information",
+        optimizer: str = "gradient_descent",
+        learning_rate: float = 0.01,
+        number_of_iterations: int = 100,
+        gradient_convergence_tolerance: float = 1e-6,
+    ) -> sitk.ImageRegistrationMethod:
+        """
+        Setup the registration method with specified parameters.
+
+        Args:
+            transform: Transform object
+            metric: Similarity metric name
+            optimizer: Optimizer name
+            learning_rate: Learning rate for gradient descent
+            number_of_iterations: Maximum number of iterations
+            gradient_convergence_tolerance: Convergence tolerance
+
+        Returns:
+            Configured registration method
+        """
+        logger.info(f"Setting up registration method: {metric} metric, {optimizer} optimizer")
+
+        registration_method = sitk.ImageRegistrationMethod()
+
+        # Set similarity metric
+        if metric == "mutual_information":
+            registration_method.SetMetricAsMattesMutualInformation(numberOfHistogramBins=50)
+        elif metric == "mean_squares":
+            registration_method.SetMetricAsMeanSquares()
+        elif metric == "correlation":
+            registration_method.SetMetricAsCorrelation()
+        elif metric == "normalized_correlation":
+            registration_method.SetMetricAsNormalizedCorrelation()
+        else:
+            logger.warning(f"Unknown metric {metric}, using mutual information")
+            registration_method.SetMetricAsMattesMutualInformation(numberOfHistogramBins=50)
+
+        # Set optimizer
+        if optimizer == "gradient_descent":
+            registration_method.SetOptimizerAsGradientDescent(
+                learningRate=learning_rate,
+                numberOfIterations=number_of_iterations,
+                convergenceMinimumValue=gradient_convergence_tolerance,
+            )
+        elif optimizer == "lbfgsb":
+            registration_method.SetOptimizerAsLBFGSB(
+                gradientConvergenceTolerance=gradient_convergence_tolerance, numberOfIterations=number_of_iterations
+            )
+        elif optimizer == "powell":
+            registration_method.SetOptimizerAsPowell(numberOfIterations=number_of_iterations, maximumLineIterations=20)
+        elif optimizer == "amoeba":
+            registration_method.SetOptimizerAsAmoeba(
+                numberOfIterations=number_of_iterations, parametersConvergenceTolerance=gradient_convergence_tolerance
+            )
+        else:
+            logger.warning(f"Unknown optimizer {optimizer}, using gradient descent")
+            registration_method.SetOptimizerAsGradientDescent(
+                learningRate=learning_rate,
+                numberOfIterations=number_of_iterations,
+                convergenceMinimumValue=gradient_convergence_tolerance,
+            )
+
+        # Set interpolator
+        registration_method.SetInterpolator(sitk.sitkLinear)
+
+        # Set initial transform
+        registration_method.SetInitialTransform(transform, inPlace=False)
+
+        return registration_method
+
+    def register_images(
+        self,
+        fixed_image: sitk.Image,
+        moving_image: sitk.Image,
+        transform: sitk.Transform,
+        registration_method: sitk.ImageRegistrationMethod,
+    ) -> tuple[sitk.Transform, sitk.Image]:
+        """
+        Perform image registration.
+
+        Args:
+            fixed_image: Reference (fixed) image
+            moving_image: Image to be registered
+            transform: Transform object
+            registration_method: Configured registration method
+
+        Returns:
+            Tuple of (final_transform, registered_image)
+        """
+        logger.info("Starting image registration...")
+
+        # Add iteration callback
+        def command_iteration():
+            logger.info(
+                f"Iteration: {registration_method.GetOptimizerIteration()}, "
+                f"Metric value: {registration_method.GetMetricValue():.6f}"
+            )
+
+        registration_method.AddCommand(sitk.sitkIterationEvent, command_iteration)
+
+        try:
+            # Execute registration
+            final_transform = registration_method.Execute(fixed_image, moving_image)
+
+            # Apply transform to moving image
+            resampler = sitk.ResampleImageFilter()
+            resampler.SetReferenceImage(fixed_image)
+            resampler.SetInterpolator(sitk.sitkLinear)
+            resampler.SetDefaultPixelValue(0)
+            resampler.SetTransform(final_transform)
+
+            registered_image = resampler.Execute(moving_image)
+
+            logger.info("Registration completed successfully")
+            return final_transform, registered_image
+
+        except Exception as e:
+            logger.error(f"Registration failed: {e}")
+            raise
+
+    def calculate_similarity_metrics(self, image1: sitk.Image, image2: sitk.Image) -> dict[str, float]:
+        """
+        Calculate similarity metrics between two images.
+
+        Args:
+            image1: First image
+            image2: Second image
+
+        Returns:
+            Dictionary of similarity metrics
+        """
+        logger.info("Calculating similarity metrics...")
+        metrics = {}
+
+        try:
+            # Convert to numpy arrays
+            array1 = sitk.GetArrayFromImage(image1)
+            array2 = sitk.GetArrayFromImage(image2)
+
+            # Flatten arrays
+            flat1 = array1.flatten()
+            flat2 = array2.flatten()
+
+            # Remove invalid values
+            valid_mask = np.isfinite(flat1) & np.isfinite(flat2)
+            flat1 = flat1[valid_mask]
+            flat2 = flat2[valid_mask]
+
+            if len(flat1) == 0:
+                logger.warning("No valid pixels for similarity calculation")
+                return {
+                    "mutual_information": 0.0,
+                    "mean_squares": 0.0,
+                    "correlation": 0.0,
+                    "normalized_correlation": 0.0,
+                }
+
+            # Mean Squared Error
+            mse = np.mean((flat1 - flat2) ** 2)
+            metrics["mean_squares"] = -mse  # Negative because we want to maximize
+
+            # Pearson Correlation
+            if np.std(flat1) > 0 and np.std(flat2) > 0:
+                correlation = np.corrcoef(flat1, flat2)[0, 1]
+                metrics["correlation"] = correlation if not np.isnan(correlation) else 0.0
+            else:
+                metrics["correlation"] = 0.0
+
+            # Normalized Cross Correlation
+            if np.std(flat1) > 0 and np.std(flat2) > 0:
+                ncc = np.corrcoef(flat1, flat2)[0, 1]
+                metrics["normalized_correlation"] = ncc if not np.isnan(ncc) else 0.0
+            else:
+                metrics["normalized_correlation"] = 0.0
+
+            # Mutual Information (simplified calculation)
+            try:
+                # Create 2D histogram
+                hist_2d, x_edges, y_edges = np.histogram2d(flat1, flat2, bins=50)
+                hist_2d = hist_2d + 1e-10  # Add small value to avoid log(0)
+
+                # Normalize histogram
+                pxy = hist_2d / np.sum(hist_2d)
+                px = np.sum(pxy, axis=1)
+                py = np.sum(pxy, axis=0)
+
+                # Calculate mutual information
+                mi = 0.0
+                for i in range(len(px)):
+                    for j in range(len(py)):
+                        if pxy[i, j] > 0 and px[i] > 0 and py[j] > 0:
+                            mi += pxy[i, j] * np.log2(pxy[i, j] / (px[i] * py[j]))
+
+                metrics["mutual_information"] = mi
+
+            except Exception as e:
+                logger.warning(f"Failed to calculate mutual information: {e}")
+                metrics["mutual_information"] = 0.0
+
+        except Exception as e:
+            logger.warning(f"Failed to calculate similarity metrics: {e}")
+            metrics = {
+                "mutual_information": 0.0,
+                "mean_squares": 0.0,
+                "correlation": 0.0,
+                "normalized_correlation": 0.0,
+            }
+
+        logger.info("Similarity metrics calculated")
+        return metrics
+
+
+# ============================================================================
+# CONVENIENCE FUNCTIONS FOR BIOMNI INTEGRATION
+# ============================================================================
+
+
+# Segmentation convenience functions
+def split_modalities(input_file, output_dir, case_name="BRAT"):
+    """Convenience function for splitting modalities"""
+    tool = SegmentationTool()
+    return tool.split_modalities(input_file, output_dir, case_name)
+
+
+def prepare_input_for_nnunet(input_path, output_dir, case_name="BRAT"):
+    """Convenience function for preparing nnUNet input"""
+    tool = SegmentationTool()
+    return tool.prepare_input_for_nnunet(input_path, output_dir, case_name)
+
+
+def segment_with_nn_unet(
+    image_path,
+    output_dir,
+    task_id,
+    model_type="3d_fullres",
+    folds=None,
+    use_tta=False,
+    num_threads=1,
+    mixed_precision=True,
+    verbose=True,
+    auto_prepare_input=True,
+    results_folder=None,
+):
+    """Convenience function for nnUNet segmentation"""
+    tool = SegmentationTool()
+    return tool.segment_with_nn_unet(
+        image_path,
+        output_dir,
+        task_id,
+        model_type,
+        folds,
+        use_tta,
+        num_threads,
+        mixed_precision,
+        verbose,
+        auto_prepare_input,
+        results_folder,
+    )
+
+
+def create_segmentation_visualization(original_mri, segmentation, output_dir="./visualization_output"):
+    """Convenience function for segmentation visualization"""
+    tool = SegmentationTool()
+    return tool.create_segmentation_visualization(original_mri, segmentation, output_dir)
+
+
+# Registration convenience functions
+def preprocess_image(image_path: str, output_path: str, denoise: bool = True, normalize: bool = True) -> str:
+    """
+    Standalone image preprocessing function for Biomni integration.
+
+    Args:
+        image_path: Path to input image
+        output_path: Path to save preprocessed image
+        denoise: Whether to apply denoising (default: True)
+        normalize: Whether to apply normalization (default: True)
+
+    Returns:
+        Path to the saved preprocessed image
+    """
+    tool = ImageRegistrationTool()
+    image = tool.load_image(image_path)
+    preprocessed_image = tool.preprocess_image(image, denoise, normalize)
+    tool.save_image(preprocessed_image, output_path)
+    return output_path
+
+
+def quick_rigid_registration(
+    fixed_image_path: str,
+    moving_image_path: str,
+    output_dir: str,
+    metric: str = "mutual_information",
+    optimizer: str = "gradient_descent",
+    preprocess: bool = True,
+    create_visualizations: bool = True,
+    learning_rate: float = 0.01,
+    number_of_iterations: int = 100,
+    gradient_convergence_tolerance: float = 1e-6,
+) -> dict:
+    """
+    Quick rigid registration function for Biomni integration.
+
+    Args:
+        fixed_image_path: Path to reference image
+        moving_image_path: Path to image to register
+        output_dir: Directory to save results
+        metric: Similarity metric
+        optimizer: Optimization method
+        preprocess: Whether to preprocess images
+        create_visualizations: Whether to create visualizations
+        learning_rate: Learning rate for optimizer
+        number_of_iterations: Maximum iterations
+        gradient_convergence_tolerance: Convergence tolerance
+
+    Returns:
+        Dictionary with registration results
+    """
+    tool = ImageRegistrationTool()
+
+    # Load images
+    fixed_image = tool.load_image(fixed_image_path)
+    moving_image = tool.load_image(moving_image_path)
+
+    # Preprocess if requested
+    if preprocess:
+        fixed_image = tool.preprocess_image(fixed_image)
+        moving_image = tool.preprocess_image(moving_image)
+
+    # Create transform and registration method
+    transform = tool.create_rigid_transform(fixed_image, moving_image)
+    registration_method = tool.setup_registration_method(
+        transform, metric, optimizer, learning_rate, number_of_iterations, gradient_convergence_tolerance
+    )
+
+    # Perform registration
+    final_transform, registered_image = tool.register_images(fixed_image, moving_image, transform, registration_method)
+
+    # Save results
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Save registered image
+    registered_path = os.path.join(output_dir, "rigid_registered.nii.gz")
+    tool.save_image(registered_image, registered_path)
+
+    # Save transform
+    transform_path = os.path.join(output_dir, "rigid_transform.tfm")
+    sitk.WriteTransform(final_transform, transform_path)
+
+    # Calculate metrics
+    metrics_before = tool.calculate_similarity_metrics(fixed_image, moving_image)
+    metrics_after = tool.calculate_similarity_metrics(fixed_image, registered_image)
+
+    results = {
+        "registered_image_path": registered_path,
+        "transform_path": transform_path,
+        "metrics_before": metrics_before,
+        "metrics_after": metrics_after,
+        "registration_type": "rigid",
+    }
+
+    return results
+
+
+def quick_affine_registration(
+    fixed_image_path: str,
+    moving_image_path: str,
+    output_dir: str,
+    metric: str = "mutual_information",
+    optimizer: str = "gradient_descent",
+    preprocess: bool = True,
+    create_visualizations: bool = True,
+    learning_rate: float = 0.01,
+    number_of_iterations: int = 100,
+    gradient_convergence_tolerance: float = 1e-6,
+) -> dict:
+    """
+    Quick affine registration function for Biomni integration.
+
+    Args:
+        fixed_image_path: Path to reference image
+        moving_image_path: Path to image to register
+        output_dir: Directory to save results
+        metric: Similarity metric
+        optimizer: Optimization method
+        preprocess: Whether to preprocess images
+        create_visualizations: Whether to create visualizations
+        learning_rate: Learning rate for optimizer
+        number_of_iterations: Maximum iterations
+        gradient_convergence_tolerance: Convergence tolerance
+
+    Returns:
+        Dictionary with registration results
+    """
+    tool = ImageRegistrationTool()
+
+    # Load images
+    fixed_image = tool.load_image(fixed_image_path)
+    moving_image = tool.load_image(moving_image_path)
+
+    # Preprocess if requested
+    if preprocess:
+        fixed_image = tool.preprocess_image(fixed_image)
+        moving_image = tool.preprocess_image(moving_image)
+
+    # Create transform and registration method
+    transform = tool.create_affine_transform(fixed_image, moving_image)
+    registration_method = tool.setup_registration_method(
+        transform, metric, optimizer, learning_rate, number_of_iterations, gradient_convergence_tolerance
+    )
+
+    # Perform registration
+    final_transform, registered_image = tool.register_images(fixed_image, moving_image, transform, registration_method)
+
+    # Save results
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Save registered image
+    registered_path = os.path.join(output_dir, "affine_registered.nii.gz")
+    tool.save_image(registered_image, registered_path)
+
+    # Save transform
+    transform_path = os.path.join(output_dir, "affine_transform.tfm")
+    sitk.WriteTransform(final_transform, transform_path)
+
+    # Calculate metrics
+    metrics_before = tool.calculate_similarity_metrics(fixed_image, moving_image)
+    metrics_after = tool.calculate_similarity_metrics(fixed_image, registered_image)
+
+    results = {
+        "registered_image_path": registered_path,
+        "transform_path": transform_path,
+        "metrics_before": metrics_before,
+        "metrics_after": metrics_after,
+        "registration_type": "affine",
+    }
+
+    return results
+
+
+def quick_deformable_registration(
+    fixed_image_path: str,
+    moving_image_path: str,
+    output_dir: str,
+    metric: str = "mutual_information",
+    optimizer: str = "gradient_descent",
+    preprocess: bool = True,
+    create_visualizations: bool = True,
+    learning_rate: float = 0.01,
+    number_of_iterations: int = 100,
+    gradient_convergence_tolerance: float = 1e-6,
+    number_of_control_points: int = 4,
+) -> dict:
+    """
+    Quick deformable registration function for Biomni integration.
+
+    Args:
+        fixed_image_path: Path to reference image
+        moving_image_path: Path to image to register
+        output_dir: Directory to save results
+        metric: Similarity metric
+        optimizer: Optimization method
+        preprocess: Whether to preprocess images
+        create_visualizations: Whether to create visualizations
+        learning_rate: Learning rate for optimizer
+        number_of_iterations: Maximum iterations
+        gradient_convergence_tolerance: Convergence tolerance
+        number_of_control_points: Number of B-spline control points
+
+    Returns:
+        Dictionary with registration results
+    """
+    tool = ImageRegistrationTool()
+
+    # Load images
+    fixed_image = tool.load_image(fixed_image_path)
+    moving_image = tool.load_image(moving_image_path)
+
+    # Preprocess if requested
+    if preprocess:
+        fixed_image = tool.preprocess_image(fixed_image)
+        moving_image = tool.preprocess_image(moving_image)
+
+    # Create transform and registration method
+    transform = tool.create_deformable_transform(fixed_image, moving_image, number_of_control_points)
+    registration_method = tool.setup_registration_method(
+        transform, metric, optimizer, learning_rate, number_of_iterations, gradient_convergence_tolerance
+    )
+
+    # Perform registration
+    final_transform, registered_image = tool.register_images(fixed_image, moving_image, transform, registration_method)
+
+    # Save results
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Save registered image
+    registered_path = os.path.join(output_dir, "deformable_registered.nii.gz")
+    tool.save_image(registered_image, registered_path)
+
+    # Save transform
+    transform_path = os.path.join(output_dir, "deformable_transform.tfm")
+    sitk.WriteTransform(final_transform, transform_path)
+
+    # Calculate metrics
+    metrics_before = tool.calculate_similarity_metrics(fixed_image, moving_image)
+    metrics_after = tool.calculate_similarity_metrics(fixed_image, registered_image)
+
+    results = {
+        "registered_image_path": registered_path,
+        "transform_path": transform_path,
+        "metrics_before": metrics_before,
+        "metrics_after": metrics_after,
+        "registration_type": "deformable",
+    }
+
+    return results
+
+
+def batch_register_images(
+    fixed_image_path: str,
+    moving_images_dir: str,
+    output_dir: str,
+    transform_type: str = "rigid",
+    metric: str = "mutual_information",
+    optimizer: str = "gradient_descent",
+    preprocess: bool = True,
+    create_visualizations: bool = True,
+    learning_rate: float = 0.01,
+    number_of_iterations: int = 100,
+    gradient_convergence_tolerance: float = 1e-6,
+) -> dict:
+    """
+    Batch registration of multiple images to a single reference.
+
+    Args:
+        fixed_image_path: Path to reference image
+        moving_images_dir: Directory containing images to register
+        output_dir: Directory to save results
+        transform_type: Type of registration ('rigid', 'affine', 'deformable')
+        metric: Similarity metric
+        optimizer: Optimization method
+        preprocess: Whether to preprocess images
+        create_visualizations: Whether to create visualizations
+        learning_rate: Learning rate for optimizer
+        number_of_iterations: Maximum iterations
+        gradient_convergence_tolerance: Convergence tolerance
+
+    Returns:
+        Dictionary with batch registration results
+    """
+    logger.info(f"Starting batch {transform_type} registration...")
+
+    # Find all image files in the directory
+    image_files = []
+    for file in os.listdir(moving_images_dir):
+        if any(file.endswith(ext) for ext in [".nii", ".nii.gz", ".nrrd", ".mha", ".mhd"]):
+            image_files.append(os.path.join(moving_images_dir, file))
+
+    if not image_files:
+        raise ValueError(f"No image files found in {moving_images_dir}")
+
+    logger.info(f"Found {len(image_files)} images to register")
+
+    # Create output directory
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Process each image
+    results = {}
+    ImageRegistrationTool()
+
+    for i, moving_image_path in enumerate(image_files):
+        logger.info(f"Processing {i + 1}/{len(image_files)}: {os.path.basename(moving_image_path)}")
+
+        # Create individual output directory
+        image_name = os.path.splitext(os.path.basename(moving_image_path))[0]
+        if image_name.endswith(".nii"):
+            image_name = os.path.splitext(image_name)[0]
+
+        individual_output_dir = os.path.join(output_dir, f"registration_{image_name}")
+
+        try:
+            if transform_type == "rigid":
+                result = quick_rigid_registration(
+                    fixed_image_path,
+                    moving_image_path,
+                    individual_output_dir,
+                    metric,
+                    optimizer,
+                    preprocess,
+                    create_visualizations,
+                    learning_rate,
+                    number_of_iterations,
+                    gradient_convergence_tolerance,
+                )
+            elif transform_type == "affine":
+                result = quick_affine_registration(
+                    fixed_image_path,
+                    moving_image_path,
+                    individual_output_dir,
+                    metric,
+                    optimizer,
+                    preprocess,
+                    create_visualizations,
+                    learning_rate,
+                    number_of_iterations,
+                    gradient_convergence_tolerance,
+                )
+            elif transform_type == "deformable":
+                result = quick_deformable_registration(
+                    fixed_image_path,
+                    moving_image_path,
+                    individual_output_dir,
+                    metric,
+                    optimizer,
+                    preprocess,
+                    create_visualizations,
+                    learning_rate,
+                    number_of_iterations,
+                    gradient_convergence_tolerance,
+                )
+            else:
+                raise ValueError(f"Unknown transform type: {transform_type}")
+
+            results[image_name] = result
+            logger.info(f"Successfully registered {image_name}")
+
+        except Exception as e:
+            logger.error(f"Failed to register {image_name}: {e}")
+            results[image_name] = {"error": str(e)}
+
+    logger.info(f"Batch registration completed. Processed {len(image_files)} images.")
+    return results
+
+
+def calculate_similarity_metrics(image1_path: str, image2_path: str) -> dict[str, float]:
+    """
+    Calculate similarity metrics between two images.
+
+    Args:
+        image1_path: Path to first image
+        image2_path: Path to second image
+
+    Returns:
+        Dictionary of similarity metrics
+    """
+    tool = ImageRegistrationTool()
+    image1 = tool.load_image(image1_path)
+    image2 = tool.load_image(image2_path)
+    return tool.calculate_similarity_metrics(image1, image2)

Biomanus_upload/biomni/tool/biophysics.py

@@ -0,0 +1,513 @@
+def predict_protein_disorder_regions(protein_sequence, threshold=0.5, output_file="disorder_prediction_results.csv"):
+    """Predicts intrinsically disordered regions (IDRs) in a protein sequence using IUPred2A.
+
+    Parameters
+    ----------
+    protein_sequence : str
+        The amino acid sequence of the protein to analyze
+    threshold : float, optional
+        The disorder score threshold above which a residue is considered disordered (default: 0.5)
+    output_file : str, optional
+        Filename to save the per-residue disorder scores (default: "disorder_prediction_results.csv")
+
+    Returns
+    -------
+    str
+        A research log summarizing the prediction process and results
+
+    """
+    import csv
+    import re
+
+    import requests
+
+    # Clean the input sequence
+    protein_sequence = "".join(re.findall(r"[A-Za-z]", protein_sequence))
+
+    # Step 1: Submit the sequence to IUPred2A web server
+    url = "https://iupred2a.elte.hu/iupred2a"
+    payload = {
+        "seq": protein_sequence,
+        "iupred2": "long",  # Use IUPred2 long disorder prediction
+        "anchor2": "no",  # Don't use ANCHOR2 prediction
+    }
+
+    try:
+        response = requests.post(url, data=payload)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        return f"Error accessing IUPred2A server: {str(e)}"
+
+    # Step 2: Parse the results to extract disorder scores
+    result_lines = response.text.split("\n")
+    scores = []
+
+    for line in result_lines:
+        if line.startswith("#") or not line.strip():
+            continue
+        parts = line.split()
+        if len(parts) >= 3:
+            try:
+                position = int(parts[0])
+                residue = parts[1]
+                score = float(parts[2])
+                scores.append((position, residue, score))
+            except (ValueError, IndexError):
+                continue
+
+    if not scores:
+        return "No valid prediction data was returned from the server."
+
+    # Step 3: Identify disordered regions
+    disordered_regions = []
+    current_region = []
+
+    for pos, _, score in scores:
+        if score >= threshold:
+            if not current_region:
+                current_region = [pos]
+            elif pos == current_region[-1] + 1:
+                current_region.append(pos)
+            else:
+                if len(current_region) > 1:
+                    disordered_regions.append((current_region[0], current_region[-1]))
+                current_region = [pos]
+        elif current_region and len(current_region) > 1:
+            disordered_regions.append((current_region[0], current_region[-1]))
+            current_region = []
+        elif current_region:
+            current_region = []
+
+    # Add the last region if it exists
+    if current_region and len(current_region) > 1:
+        disordered_regions.append((current_region[0], current_region[-1]))
+
+    # Step 4: Save results to CSV
+    with open(output_file, "w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["Position", "Amino_Acid", "Disorder_Score", "Is_Disordered"])
+        for pos, aa, score in scores:
+            is_disordered = "Yes" if score >= threshold else "No"
+            writer.writerow([pos, aa, score, is_disordered])
+
+    # Step 5: Generate the research log
+    total_residues = len(scores)
+    disordered_count = sum(1 for _, _, score in scores if score >= threshold)
+    disordered_percentage = (disordered_count / total_residues) * 100 if total_residues > 0 else 0
+
+    log = f"""
+Intrinsically Disordered Region (IDR) Prediction Research Log:
+=============================================================
+Analysis performed using IUPred2A algorithm (long disorder mode)
+Protein sequence length: {total_residues} amino acids
+Disorder threshold: {threshold}
+
+Results Summary:
+- {disordered_count} residues ({disordered_percentage:.2f}%) predicted as disordered
+- {len(disordered_regions)} distinct disordered regions identified
+
+Disordered Regions:
+"""
+
+    if disordered_regions:
+        for start, end in disordered_regions:
+            length = end - start + 1
+            log += f"- Region {start}-{end} (length: {length} residues)\n"
+    else:
+        log += "- No significant disordered regions found\n"
+
+    log += f"\nDetailed per-residue scores saved to: {output_file}"
+
+    return log
+
+
+def analyze_cell_morphology_and_cytoskeleton(image_path, output_dir="./results", threshold_method="otsu"):
+    """Quantifies cell morphology and cytoskeletal organization from fluorescence microscopy images.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the fluorescence microscopy image file
+    output_dir : str, optional
+        Directory to save output files (default: './results')
+    threshold_method : str, optional
+        Method for cell segmentation ('otsu', 'adaptive', or 'manual') (default: 'otsu')
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import cv2
+    import numpy as np
+    import pandas as pd
+    from skimage import exposure, feature, filters, io, measure, morphology
+    from skimage.color import rgb2gray
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Start log
+    log = f"Cell Morphology and Cytoskeleton Analysis Log - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+    log += f"Analyzing image: {image_path}\n\n"
+
+    # Load image
+    log += "Step 1: Loading and preprocessing image\n"
+    try:
+        image = io.imread(image_path)
+        # Convert to grayscale if RGB
+        if len(image.shape) > 2:
+            gray_image = rgb2gray(image)
+            log += "- Converted RGB image to grayscale\n"
+        else:
+            gray_image = image
+
+        # Enhance contrast
+        gray_image = exposure.equalize_hist(gray_image)
+        log += "- Enhanced image contrast\n"
+    except Exception as e:
+        return f"Error loading image: {str(e)}"
+
+    # Segment cells
+    log += "\nStep 2: Segmenting cells from background\n"
+    if threshold_method == "otsu":
+        thresh = filters.threshold_otsu(gray_image)
+        binary = gray_image > thresh
+        log += f"- Applied Otsu thresholding (threshold value: {thresh:.4f})\n"
+    elif threshold_method == "adaptive":
+        binary = filters.threshold_local(gray_image, block_size=35, offset=0.05)
+        binary = gray_image > binary
+        log += "- Applied adaptive thresholding\n"
+    else:  # manual
+        thresh = 0.5  # Default value, can be parameterized
+        binary = gray_image > thresh
+        log += f"- Applied manual thresholding (threshold value: {thresh:.4f})\n"
+
+    # Clean up binary image
+    binary = morphology.remove_small_objects(binary, min_size=100)
+    binary = morphology.remove_small_holes(binary, area_threshold=100)
+    binary = morphology.binary_closing(binary, morphology.disk(3))
+    log += "- Applied morphological operations to clean segmentation\n"
+
+    # Label cells
+    labeled_cells, num_cells = measure.label(binary, return_num=True)
+    log += f"- Identified {num_cells} cell regions\n"
+
+    # Analyze cell properties
+    log += "\nStep 3: Analyzing cell morphology\n"
+    cell_props = measure.regionprops_table(
+        labeled_cells,
+        gray_image,
+        properties=(
+            "area",
+            "perimeter",
+            "major_axis_length",
+            "minor_axis_length",
+            "eccentricity",
+            "orientation",
+            "solidity",
+        ),
+    )
+
+    # Convert to DataFrame for easier manipulation
+    cell_df = pd.DataFrame(cell_props)
+
+    # Calculate additional metrics
+    if len(cell_df) > 0:
+        cell_df["aspect_ratio"] = cell_df["major_axis_length"] / cell_df["minor_axis_length"]
+        cell_df["circularity"] = (4 * np.pi * cell_df["area"]) / (cell_df["perimeter"] ** 2)
+
+        # Summary statistics
+        log += f"- Average cell area: {cell_df['area'].mean():.2f} pixels\n"
+        log += f"- Average aspect ratio: {cell_df['aspect_ratio'].mean():.2f}\n"
+        log += f"- Average circularity: {cell_df['circularity'].mean():.2f}\n"
+        log += f"- Average eccentricity: {cell_df['eccentricity'].mean():.2f}\n"
+    else:
+        log += "- No cells detected for morphological analysis\n"
+
+    # Analyze cytoskeletal organization
+    log += "\nStep 4: Analyzing cytoskeletal organization\n"
+
+    # Edge detection to highlight cytoskeletal fibers
+    edges = feature.canny(gray_image, sigma=2)
+
+    # Use Hough transform to detect lines (cytoskeletal fibers)
+    if np.any(edges):
+        lines = cv2.HoughLinesP(
+            edges.astype(np.uint8),
+            1,
+            np.pi / 180,
+            threshold=10,
+            minLineLength=10,
+            maxLineGap=5,
+        )
+
+        if lines is not None:
+            # Calculate line orientations
+            orientations = []
+            for line in lines:
+                x1, y1, x2, y2 = line[0]
+                if x2 - x1 != 0:  # Avoid division by zero
+                    angle = np.arctan2(y2 - y1, x2 - x1) * 180 / np.pi
+                    orientations.append(angle)
+
+            if orientations:
+                # Convert to numpy array for calculations
+                orientations = np.array(orientations)
+
+                # Calculate alignment metrics
+                mean_orientation = np.mean(orientations)
+                # Normalize angles to -90 to 90 degrees
+                norm_angles = np.mod(orientations + 90, 180) - 90
+                std_orientation = np.std(norm_angles)
+
+                # Order parameter (measure of alignment, 1 = perfectly aligned, 0 = random)
+                # Convert angles to radians for calculation
+                rad_angles = np.radians(norm_angles)
+                order_parameter = np.sqrt(np.mean(np.cos(2 * rad_angles)) ** 2 + np.mean(np.sin(2 * rad_angles)) ** 2)
+
+                log += f"- Detected {len(orientations)} cytoskeletal fibers\n"
+                log += f"- Mean fiber orientation: {mean_orientation:.2f} degrees\n"
+                log += f"- Standard deviation of orientation: {std_orientation:.2f} degrees\n"
+                log += f"- Order parameter (alignment): {order_parameter:.4f} (0=random, 1=aligned)\n"
+
+                # Add fiber data to dataframe
+                fiber_df = pd.DataFrame({"fiber_orientation": orientations})
+            else:
+                log += "- No fiber orientations could be calculated\n"
+                fiber_df = pd.DataFrame()
+        else:
+            log += "- No cytoskeletal fibers detected\n"
+            fiber_df = pd.DataFrame()
+    else:
+        log += "- No edges detected for cytoskeletal analysis\n"
+        fiber_df = pd.DataFrame()
+
+    # Save results
+    log += "\nStep 5: Saving results\n"
+
+    # Save cell morphology data
+    if len(cell_df) > 0:
+        cell_csv_path = os.path.join(output_dir, "cell_morphology_data.csv")
+        cell_df.to_csv(cell_csv_path, index=False)
+        log += f"- Cell morphology data saved to: {cell_csv_path}\n"
+
+    # Save fiber orientation data
+    if len(fiber_df) > 0:
+        fiber_csv_path = os.path.join(output_dir, "fiber_orientation_data.csv")
+        fiber_df.to_csv(fiber_csv_path, index=False)
+        log += f"- Fiber orientation data saved to: {fiber_csv_path}\n"
+
+    # Save segmentation image
+    if num_cells > 0:
+        segmentation_path = os.path.join(output_dir, "cell_segmentation.png")
+        io.imsave(segmentation_path, labeled_cells.astype(np.uint8) * 50)
+        log += f"- Cell segmentation image saved to: {segmentation_path}\n"
+
+    # Summary
+    log += "\nAnalysis Summary:\n"
+    log += f"- Processed image: {image_path}\n"
+    log += f"- Detected {num_cells} cells\n"
+    if len(cell_df) > 0:
+        log += f"- Cell size range: {cell_df['area'].min():.1f} to {cell_df['area'].max():.1f} pixels\n"
+        log += f"- Cell shape: average aspect ratio = {cell_df['aspect_ratio'].mean():.2f}\n"
+    if "order_parameter" in locals():
+        log += f"- Cytoskeletal organization: alignment parameter = {order_parameter:.4f}\n"
+
+    return log
+
+
+def analyze_tissue_deformation_flow(image_sequence, output_dir="results", pixel_scale=1.0):
+    """Quantify tissue deformation and flow dynamics from microscopy image sequence.
+
+    Parameters
+    ----------
+    image_sequence : list or numpy.ndarray
+        Sequence of microscopy images (either a list of file paths or a 3D numpy array [time, height, width])
+    output_dir : str, optional
+        Directory to save results (default: "results")
+    pixel_scale : float, optional
+        Physical scale of pixels (e.g., μm/pixel) for proper scaling of metrics (default: 1.0)
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import cv2
+    import numpy as np
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Load images if paths are provided
+    if isinstance(image_sequence[0], str):
+        loaded_images = []
+        for img_path in image_sequence:
+            img = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE)
+            if img is None:
+                return f"Error: Could not load image {img_path}"
+            loaded_images.append(img)
+        frames = np.array(loaded_images)
+    else:
+        frames = image_sequence
+        # Convert to grayscale if needed
+        if len(frames.shape) > 3:  # Has color channels
+            frames = np.array(
+                [cv2.cvtColor(frame, cv2.COLOR_RGB2GRAY) if frame.shape[-1] == 3 else frame for frame in frames]
+            )
+
+    # Parameters for optical flow
+    lk_params = {
+        "winSize": (15, 15),
+        "maxLevel": 2,
+        "criteria": (cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 0.03),
+    }
+
+    # Metrics storage
+    num_frames = len(frames)
+    flow_fields = []
+    divergence_maps = []
+    curl_maps = []
+    strain_maps = []
+
+    # Log initialization
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log = f"Tissue Deformation and Flow Analysis - {timestamp}\n"
+    log += f"Number of frames analyzed: {num_frames}\n"
+    log += f"Image dimensions: {frames[0].shape[0]}x{frames[0].shape[1]} pixels\n"
+    log += f"Pixel scale: {pixel_scale} units/pixel\n\n"
+    log += "Analysis Steps:\n"
+
+    # Create feature points grid (evenly spaced points)
+    y, x = np.mgrid[0 : frames[0].shape[0] : 20, 0 : frames[0].shape[1] : 20]
+    feature_points = np.stack((x.flatten(), y.flatten()), axis=1).astype(np.float32)
+
+    for i in range(num_frames - 1):
+        log += f"Processing frame pair {i} and {i + 1}...\n"
+
+        # Calculate optical flow using Lucas-Kanade
+        prev_frame = frames[i]
+        next_frame = frames[i + 1]
+
+        # Compute flow for the grid points
+        next_points, status, _ = cv2.calcOpticalFlowPyrLK(prev_frame, next_frame, feature_points, None, **lk_params)
+
+        # Filter valid points
+        valid_idx = status.flatten() == 1
+        valid_prev_points = feature_points[valid_idx]
+        valid_next_points = next_points[valid_idx]
+
+        # Calculate displacement vectors
+        displacement = valid_next_points - valid_prev_points
+        points = valid_prev_points
+
+        # Interpolate flow field to full image resolution
+        flow_field = np.zeros((frames[0].shape[0], frames[0].shape[1], 2), dtype=np.float32)
+
+        # Simple nearest-neighbor interpolation for demonstration
+        # In a production system, you might use more sophisticated interpolation
+        for j, (x, y) in enumerate(points.astype(int)):
+            if 0 <= y < flow_field.shape[0] and 0 <= x < flow_field.shape[1]:
+                flow_field[y, x] = displacement[j]
+
+        # Calculate derivatives for deformation analysis
+        u = flow_field[:, :, 0]  # x-component of flow
+        v = flow_field[:, :, 1]  # y-component of flow
+
+        # Calculate divergence (expansion/contraction)
+        # Using central differences for derivatives
+        u_x = cv2.Sobel(u, cv2.CV_64F, 1, 0, ksize=3) / (8.0 * pixel_scale)
+        v_y = cv2.Sobel(v, cv2.CV_64F, 0, 1, ksize=3) / (8.0 * pixel_scale)
+        divergence = u_x + v_y
+
+        # Calculate curl (rotation)
+        u_y = cv2.Sobel(u, cv2.CV_64F, 0, 1, ksize=3) / (8.0 * pixel_scale)
+        v_x = cv2.Sobel(v, cv2.CV_64F, 1, 0, ksize=3) / (8.0 * pixel_scale)
+        curl = v_x - u_y
+
+        # Calculate strain tensor components
+        strain_xx = u_x
+        strain_yy = v_y
+        strain_xy = 0.5 * (u_y + v_x)
+
+        # Magnitude of strain tensor (Frobenius norm)
+        strain_magnitude = np.sqrt(strain_xx**2 + strain_yy**2 + 2 * strain_xy**2)
+
+        # Store results
+        flow_fields.append(flow_field)
+        divergence_maps.append(divergence)
+        curl_maps.append(curl)
+        strain_maps.append(strain_magnitude)
+
+        # Visualize flow field
+        flow_viz = np.zeros((frames[0].shape[0], frames[0].shape[1], 3), dtype=np.uint8)
+        flow_viz[..., 0] = next_frame  # Use next frame as background
+        flow_viz[..., 1] = next_frame
+        flow_viz[..., 2] = next_frame
+
+        # Draw flow vectors for visualization
+        step = 20
+        for y in range(0, flow_field.shape[0], step):
+            for x in range(0, flow_field.shape[1], step):
+                dx, dy = flow_field[y, x]
+                if abs(dx) > 0.5 or abs(dy) > 0.5:  # Only draw significant flow
+                    cv2.arrowedLine(
+                        flow_viz,
+                        (x, y),
+                        (int(x + dx), int(y + dy)),
+                        (0, 255, 0),  # Green
+                        1,
+                        tipLength=0.3,
+                    )
+
+        # Save visualizations
+        flow_viz_path = os.path.join(output_dir, f"flow_viz_{i:03d}.png")
+        divergence_path = os.path.join(output_dir, f"divergence_{i:03d}.npy")
+        curl_path = os.path.join(output_dir, f"curl_{i:03d}.npy")
+        strain_path = os.path.join(output_dir, f"strain_{i:03d}.npy")
+
+        cv2.imwrite(flow_viz_path, flow_viz)
+        np.save(divergence_path, divergence)
+        np.save(curl_path, curl)
+        np.save(strain_path, strain_magnitude)
+
+    # Calculate summary statistics
+    mean_divergence = np.mean([np.mean(div) for div in divergence_maps])
+    max_divergence = np.max([np.max(div) for div in divergence_maps])
+    mean_curl = np.mean([np.mean(np.abs(c)) for c in curl_maps])
+    mean_strain = np.mean([np.mean(s) for s in strain_maps])
+
+    # Add summary to log
+    log += "\nAnalysis Results:\n"
+    log += f"Mean tissue divergence: {mean_divergence:.6f} (expansion/contraction rate)\n"
+    log += f"Maximum divergence: {max_divergence:.6f}\n"
+    log += f"Mean absolute curl: {mean_curl:.6f} (rotation rate)\n"
+    log += f"Mean strain magnitude: {mean_strain:.6f} (deformation intensity)\n\n"
+
+    # Save summary data
+    summary_data = {
+        "mean_divergence": mean_divergence,
+        "max_divergence": max_divergence,
+        "mean_curl": mean_curl,
+        "mean_strain": mean_strain,
+    }
+    summary_path = os.path.join(output_dir, "deformation_summary.npy")
+    np.save(summary_path, summary_data)
+
+    log += "Files Generated:\n"
+    log += f"- Flow visualization images: {output_dir}/flow_viz_*.png\n"
+    log += f"- Divergence maps: {output_dir}/divergence_*.npy\n"
+    log += f"- Curl maps: {output_dir}/curl_*.npy\n"
+    log += f"- Strain maps: {output_dir}/strain_*.npy\n"
+    log += f"- Summary statistics: {output_dir}/deformation_summary.npy\n"
+
+    return log

Biomanus_upload/biomni/tool/cancer_biology.py

@@ -0,0 +1,1292 @@
+def analyze_ddr_network_in_cancer(expression_data_path, mutation_data_path, output_dir="./results"):
+    """Analyze DNA Damage Response (DDR) network alterations and dependencies in cancer samples.
+
+    This function reconstructs the DDR network from genomic data, identifies disruptions
+    in the network, and analyzes dependencies between DDR pathway components in cancer.
+
+    Parameters
+    ----------
+    expression_data_path : str
+        Path to gene expression data file (CSV format with genes as rows, samples as columns)
+    mutation_data_path : str
+        Path to mutation data file (CSV format with genes as rows, samples as columns,
+        values indicating mutation status)
+    output_dir : str, optional
+        Directory to save output files (default: "./results")
+
+    Returns
+    -------
+    str
+        Research log summarizing the DDR network analysis, findings about disruptions,
+        and potential therapeutic vulnerabilities
+
+    """
+    import os
+    from datetime import datetime
+
+    import gseapy as gp
+    import networkx as nx
+    import pandas as pd
+    from scipy.stats import pearsonr
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    research_log = f"DDR Network Analysis Research Log - {datetime.now().strftime('%Y-%m-%d %H:%M')}\n"
+    research_log += "=" * 80 + "\n\n"
+
+    # Step 1: Load and preprocess genomic data
+    research_log += "STEP 1: Loading and preprocessing genomic data\n"
+
+    try:
+        expr_data = pd.read_csv(expression_data_path, index_col=0)
+        mut_data = pd.read_csv(mutation_data_path, index_col=0)
+
+        research_log += f"- Loaded expression data: {expr_data.shape[0]} genes × {expr_data.shape[1]} samples\n"
+        research_log += f"- Loaded mutation data: {mut_data.shape[0]} genes × {mut_data.shape[1]} samples\n"
+
+        # Define core DDR genes (based on literature)
+        ddr_genes = [
+            # DNA damage sensors
+            "ATM",
+            "ATR",
+            "PRKDC",
+            "RAD50",
+            "MRE11",
+            "NBN",
+            # Signal transducers
+            "CHEK1",
+            "CHEK2",
+            "TP53",
+            "BRCA1",
+            "BRCA2",
+            "MDC1",
+            "H2AX",
+            # Effectors - Homologous Recombination
+            "RAD51",
+            "RAD52",
+            "PALB2",
+            "RAD54L",
+            # Effectors - Non-Homologous End Joining
+            "XRCC4",
+            "LIG4",
+            "XRCC5",
+            "XRCC6",
+            # Effectors - Base Excision Repair
+            "PARP1",
+            "APEX1",
+            "OGG1",
+            "XRCC1",
+            # Effectors - Nucleotide Excision Repair
+            "XPA",
+            "XPC",
+            "ERCC1",
+            "ERCC2",
+            "ERCC3",
+            "ERCC4",
+            "ERCC5",
+            # Effectors - Mismatch Repair
+            "MLH1",
+            "MSH2",
+            "MSH6",
+            "PMS2",
+        ]
+
+        # Filter expression and mutation data for DDR genes
+        ddr_expr = expr_data.loc[expr_data.index.isin(ddr_genes)]
+        ddr_mut = mut_data.loc[mut_data.index.isin(ddr_genes)]
+
+        research_log += f"- Filtered data for {len(ddr_genes)} DDR pathway genes\n"
+        research_log += f"- Found {ddr_expr.shape[0]} DDR genes in expression data\n"
+        research_log += f"- Found {ddr_mut.shape[0]} DDR genes in mutation data\n\n"
+
+    except Exception as e:
+        research_log += f"Error in data loading: {str(e)}\n\n"
+        return research_log
+
+    # Step 2: Network reconstruction
+    research_log += "STEP 2: Reconstructing DDR gene network\n"
+
+    # Create correlation-based network
+    G = nx.Graph()
+
+    # Add nodes (genes)
+    for gene in ddr_expr.index:
+        # Add node with mutation frequency information
+        mutation_freq = ddr_mut.loc[gene].mean() if gene in ddr_mut.index else 0
+
+        G.add_node(gene, mutation_freq=mutation_freq)
+
+    # Add edges based on gene expression correlation
+    for i, gene1 in enumerate(ddr_expr.index):
+        for gene2 in ddr_expr.index[i + 1 :]:
+            corr, p_value = pearsonr(ddr_expr.loc[gene1], ddr_expr.loc[gene2])
+            if abs(corr) > 0.4 and p_value < 0.05:  # Significant correlation threshold
+                G.add_edge(gene1, gene2, weight=abs(corr), correlation=corr)
+
+    research_log += f"- Constructed network with {G.number_of_nodes()} nodes and {G.number_of_edges()} edges\n"
+
+    # Save network for visualization
+    network_file = os.path.join(output_dir, "ddr_network.graphml")
+    nx.write_graphml(G, network_file)
+    research_log += f"- Network saved to: {network_file}\n\n"
+
+    # Step 3: Network analysis
+    research_log += "STEP 3: Analyzing DDR network properties\n"
+
+    # Calculate network centrality measures
+    degree_centrality = nx.degree_centrality(G)
+    betweenness_centrality = nx.betweenness_centrality(G)
+
+    # Identify hub genes (high degree centrality)
+    hub_genes = sorted(degree_centrality.items(), key=lambda x: x[1], reverse=True)[:5]
+
+    research_log += "- Top 5 hub genes (highest connectivity):\n"
+    for gene, centrality in hub_genes:
+        research_log += f"  * {gene}: {centrality:.4f}\n"
+
+    # Identify bottleneck genes (high betweenness centrality)
+    bottleneck_genes = sorted(betweenness_centrality.items(), key=lambda x: x[1], reverse=True)[:5]
+
+    research_log += "- Top 5 bottleneck genes (critical for information flow):\n"
+    for gene, centrality in bottleneck_genes:
+        research_log += f"  * {gene}: {centrality:.4f}\n"
+
+    # Identify frequently mutated DDR genes
+    mutation_freq = {node: G.nodes[node]["mutation_freq"] for node in G.nodes()}
+    frequently_mutated = sorted(mutation_freq.items(), key=lambda x: x[1], reverse=True)[:5]
+
+    research_log += "- Top 5 frequently mutated DDR genes:\n"
+    for gene, freq in frequently_mutated:
+        research_log += f"  * {gene}: {freq:.4f}\n\n"
+
+    # Step 4: Community detection to identify DDR sub-pathways
+    research_log += "STEP 4: Identifying DDR sub-pathways through community detection\n"
+
+    # Use Louvain method for community detection
+    try:
+        from community import best_partition
+
+        partition = best_partition(G)
+        communities = {}
+        for node, community_id in partition.items():
+            if community_id not in communities:
+                communities[community_id] = []
+            communities[community_id].append(node)
+
+        research_log += f"- Identified {len(communities)} DDR sub-pathways\n"
+
+        for i, (_, genes) in enumerate(communities.items()):
+            research_log += f"  * Sub-pathway {i + 1}: {', '.join(genes)}\n"
+
+    except ImportError:
+        research_log += "- Community detection skipped (python-louvain package not installed)\n"
+
+    # Step 5: Identify disrupted DDR pathways using GSEA
+    research_log += "\nSTEP 5: Pathway enrichment analysis of DDR genes\n"
+
+    try:
+        # Create gene list for GSEA
+        gene_list = ddr_expr.mean(axis=1).sort_values(ascending=False)
+
+        # Run GSEA with GO Biological Process
+        enrichr_results = gp.enrichr(
+            gene_list=gene_list.index.tolist(),
+            gene_sets=["GO_Biological_Process_2021"],
+            outdir=os.path.join(output_dir, "enrichr_output"),
+            cutoff=0.5,
+        )
+
+        # Filter for DNA repair related terms
+        ddr_terms = [
+            term
+            for term in enrichr_results.results["Term"]
+            if any(x in term.lower() for x in ["dna repair", "damage", "recombination", "checkpoint"])
+        ]
+
+        if ddr_terms:
+            research_log += "- Enriched DDR-related pathways:\n"
+            for term in ddr_terms[:5]:  # Top 5 DDR-related terms
+                research_log += f"  * {term}\n"
+        else:
+            research_log += "- No significant DDR pathway enrichment found\n"
+
+        # Save full enrichment results
+        enrichment_file = os.path.join(output_dir, "ddr_pathway_enrichment.csv")
+        enrichr_results.results.to_csv(enrichment_file)
+        research_log += f"- Full enrichment results saved to: {enrichment_file}\n\n"
+
+    except Exception as e:
+        research_log += f"- Pathway enrichment analysis error: {str(e)}\n\n"
+
+    # Step 6: Summary of findings
+    research_log += "SUMMARY OF FINDINGS\n"
+    research_log += "=" * 80 + "\n"
+
+    # Key hub genes (potential therapeutic targets)
+    research_log += "1. Key DDR hub genes that may serve as potential therapeutic targets:\n"
+    for gene, _ in hub_genes[:3]:
+        research_log += f"   - {gene}\n"
+
+    # Frequently mutated genes
+    research_log += "\n2. Frequently mutated DDR genes in the samples:\n"
+    for gene, freq in frequently_mutated[:3]:
+        research_log += f"   - {gene} (mutation frequency: {freq:.2%})\n"
+
+    # Network structure insights
+    research_log += "\n3. DDR network structure insights:\n"
+    research_log += f"   - Network density: {nx.density(G):.4f}\n"
+
+    try:
+        avg_clustering = nx.average_clustering(G)
+        research_log += f"   - Average clustering coefficient: {avg_clustering:.4f}\n"
+    except Exception:
+        pass
+
+    research_log += "\n4. Potential DDR dependencies and synthetic lethality targets:\n"
+    # Identify potential synthetic lethality pairs (genes with high correlation and one is frequently mutated)
+    synthetic_lethality_candidates = []
+    for gene1, gene2, data in G.edges(data=True):
+        if abs(data["correlation"]) > 0.6:  # Strong correlation
+            mut_freq1 = G.nodes[gene1]["mutation_freq"]
+            mut_freq2 = G.nodes[gene2]["mutation_freq"]
+            if (mut_freq1 > 0.1 and mut_freq2 < 0.05) or (mut_freq2 > 0.1 and mut_freq1 < 0.05):
+                if mut_freq1 > mut_freq2:
+                    synthetic_lethality_candidates.append((gene1, gene2, data["correlation"], mut_freq1))
+                else:
+                    synthetic_lethality_candidates.append((gene2, gene1, data["correlation"], mut_freq2))
+
+    if synthetic_lethality_candidates:
+        for mutated, target, _, _ in sorted(synthetic_lethality_candidates, key=lambda x: x[3], reverse=True)[:3]:
+            research_log += f"   - {mutated} (frequently mutated) and {target} (potential dependency)\n"
+    else:
+        research_log += "   - No strong synthetic lethality candidates identified\n"
+
+    return research_log
+
+
+def analyze_cell_senescence_and_apoptosis(fcs_file_path):
+    """Analyze flow cytometry data to quantify senescent and apoptotic cell populations.
+
+    Parameters
+    ----------
+    fcs_file_path : str
+        Path to the FCS file containing flow cytometry data with measurements for
+        senescence-associated β-galactosidase (SA-β-Gal) and Annexin V/7-AAD staining
+
+    Returns
+    -------
+    str
+        A research log summarizing the analysis steps and results, including percentages
+        of senescent and apoptotic cell populations
+
+    """
+    import os
+
+    import numpy as np
+    from FlowCytometryTools import FCMeasurement
+
+    log = "# Flow Cytometry Analysis of Cell Senescence and Apoptosis\n\n"
+
+    try:
+        # Step 1: Load the FCS file
+        log += "## Step 1: Loading Flow Cytometry Data\n"
+        log += f"- Loading FCS file from: {fcs_file_path}\n"
+
+        sample = FCMeasurement(ID="Sample", datafile=fcs_file_path)
+        log += f"- Successfully loaded data with {len(sample)} events\n"
+        log += f"- Available channels: {', '.join(sample.channel_names)}\n\n"
+
+        # Step 2: Apply compensation if needed (assuming pre-compensated data)
+        log += "## Step 2: Data Preprocessing\n"
+        log += "- Checking for outliers and debris based on forward/side scatter\n"
+
+        # Basic filtering to remove debris based on FSC and SSC
+        # Assuming FSC-A and SSC-A are the channel names (adjust if different)
+        fsc_channel = "FSC-A" if "FSC-A" in sample.channel_names else sample.channel_names[0]
+        ssc_channel = "SSC-A" if "SSC-A" in sample.channel_names else sample.channel_names[1]
+
+        # Filter out debris (low FSC and SSC)
+        sample_filtered = sample.gate(f"{fsc_channel} > 10000 and {ssc_channel} > 5000")
+
+        log += f"- Filtered out debris: {len(sample)} → {len(sample_filtered)} events ({len(sample_filtered) / len(sample) * 100:.1f}%)\n\n"
+
+        # Step 3: Identify senescent cells (SA-β-Gal positive)
+        log += "## Step 3: Identifying Senescent Cells (SA-β-Gal+)\n"
+
+        # Find SA-β-Gal channel (adjust based on actual channel name)
+        sa_bgal_channel = None
+        for channel in sample_filtered.channel_names:
+            if "GAL" in channel.upper() or "FITC" in channel.upper():
+                sa_bgal_channel = channel
+                break
+
+        if not sa_bgal_channel:
+            log += "- WARNING: Could not identify SA-β-Gal channel. Using first fluorescence channel as placeholder.\n"
+            # Use the first fluorescence channel as a fallback
+            for channel in sample_filtered.channel_names:
+                if any(x in channel.upper() for x in ["FL", "BL", "FITC", "PE", "APC"]):
+                    sa_bgal_channel = channel
+                    break
+
+        log += f"- Using {sa_bgal_channel} as SA-β-Gal activity indicator\n"
+
+        # Determine threshold for SA-β-Gal positivity (using a simple percentile approach)
+        # In practice, this would be based on controls or known thresholds
+        sa_bgal_threshold = np.percentile(sample_filtered.data[sa_bgal_channel], 80)
+        senescent_cells = sample_filtered.gate(f"{sa_bgal_channel} > {sa_bgal_threshold}")
+
+        senescent_percentage = (len(senescent_cells) / len(sample_filtered)) * 100
+        log += f"- Applied threshold at {sa_bgal_threshold:.1f} fluorescence intensity\n"
+        log += f"- Identified {len(senescent_cells)} senescent cells ({senescent_percentage:.2f}%)\n\n"
+
+        # Step 4: Identify apoptotic cells (Annexin V+/7-AAD+)
+        log += "## Step 4: Identifying Apoptotic Cells (Annexin V/7-AAD)\n"
+
+        # Find Annexin V and 7-AAD channels (adjust based on actual channel names)
+        annexin_channel = None
+        aad_channel = None
+
+        for channel in sample_filtered.channel_names:
+            if "ANNEXIN" in channel.upper() or "PE" in channel.upper():
+                annexin_channel = channel
+            if "7AAD" in channel.upper() or "AAD" in channel.upper() or "PerCP" in channel.upper():
+                aad_channel = channel
+
+        if not annexin_channel or not aad_channel:
+            log += "- WARNING: Could not identify Annexin V and/or 7-AAD channels. Using placeholder channels.\n"
+            # Use fallback channels
+            fluorescence_channels = [
+                ch
+                for ch in sample_filtered.channel_names
+                if any(x in ch.upper() for x in ["FL", "BL", "FITC", "PE", "APC", "PerCP"])
+            ]
+            if len(fluorescence_channels) >= 2:
+                if not annexin_channel:
+                    annexin_channel = fluorescence_channels[0]
+                if not aad_channel:
+                    aad_channel = fluorescence_channels[1]
+
+        log += f"- Using {annexin_channel} as Annexin V indicator\n"
+        log += f"- Using {aad_channel} as 7-AAD indicator\n"
+
+        # Determine thresholds for Annexin V and 7-AAD (using simple percentile approach)
+        annexin_threshold = np.percentile(sample_filtered.data[annexin_channel], 90)
+        aad_threshold = np.percentile(sample_filtered.data[aad_channel], 90)
+
+        # Early apoptotic: Annexin V+ / 7-AAD-
+        early_apoptotic = sample_filtered.gate(
+            f"{annexin_channel} > {annexin_threshold} and {aad_channel} < {aad_threshold}"
+        )
+        early_apoptotic_percentage = (len(early_apoptotic) / len(sample_filtered)) * 100
+
+        # Late apoptotic/necrotic: Annexin V+ / 7-AAD+
+        late_apoptotic = sample_filtered.gate(
+            f"{annexin_channel} > {annexin_threshold} and {aad_channel} > {aad_threshold}"
+        )
+        late_apoptotic_percentage = (len(late_apoptotic) / len(sample_filtered)) * 100
+
+        # Total apoptotic (early + late)
+        total_apoptotic_percentage = early_apoptotic_percentage + late_apoptotic_percentage
+
+        log += f"- Early apoptotic cells (Annexin V+/7-AAD-): {early_apoptotic_percentage:.2f}%\n"
+        log += f"- Late apoptotic cells (Annexin V+/7-AAD+): {late_apoptotic_percentage:.2f}%\n"
+        log += f"- Total apoptotic cells: {total_apoptotic_percentage:.2f}%\n\n"
+
+        # Step 5: Summary of results
+        log += "## Summary of Results\n"
+        log += f"- Total events analyzed: {len(sample_filtered)}\n"
+        log += f"- Senescent cells (SA-β-Gal+): {senescent_percentage:.2f}%\n"
+        log += f"- Early apoptotic cells (Annexin V+/7-AAD-): {early_apoptotic_percentage:.2f}%\n"
+        log += f"- Late apoptotic cells (Annexin V+/7-AAD+): {late_apoptotic_percentage:.2f}%\n"
+        log += f"- Total apoptotic cells: {total_apoptotic_percentage:.2f}%\n"
+
+        # Save results to CSV file
+        results_file = os.path.splitext(os.path.basename(fcs_file_path))[0] + "_results.csv"
+        with open(results_file, "w") as f:
+            f.write("Cell Population,Percentage\n")
+            f.write(f"Senescent cells,{senescent_percentage:.2f}\n")
+            f.write(f"Early apoptotic cells,{early_apoptotic_percentage:.2f}\n")
+            f.write(f"Late apoptotic cells,{late_apoptotic_percentage:.2f}\n")
+            f.write(f"Total apoptotic cells,{total_apoptotic_percentage:.2f}\n")
+
+        log += f"\nResults saved to: {results_file}\n"
+
+    except Exception as e:
+        log += "\n## ERROR: An error occurred during analysis\n"
+        log += f"- Error message: {str(e)}\n"
+
+    return log
+
+
+def detect_and_annotate_somatic_mutations(
+    tumor_bam, normal_bam, reference_genome, output_prefix, snpeff_database="GRCh38.105"
+):
+    """Detects and annotates somatic mutations in tumor samples compared to matched normal samples.
+
+    This function uses GATK Mutect2 for variant calling, GATK FilterMutectCalls for filtering,
+    and SnpEff for functional annotation of somatic mutations.
+
+    Parameters
+    ----------
+    tumor_bam : str
+        Path to the tumor sample BAM file
+    normal_bam : str
+        Path to the matched normal sample BAM file
+    reference_genome : str
+        Path to the reference genome FASTA file
+    output_prefix : str
+        Prefix for output files
+    snpeff_database : str, optional
+        SnpEff database to use for annotation (default: "GRCh38.105")
+
+    Returns
+    -------
+    str
+        A research log summarizing the steps performed and results obtained
+
+    """
+    import datetime
+    import os
+    import subprocess
+
+    # Initialize research log
+    log = "# Somatic Mutation Analysis Log\n"
+    log += f"Date: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+    log += "## Input Files\n"
+    log += f"- Tumor BAM: {tumor_bam}\n"
+    log += f"- Normal BAM: {normal_bam}\n"
+    log += f"- Reference Genome: {reference_genome}\n\n"
+
+    # Step 1: Run Mutect2 for somatic variant calling
+    log += "## Step 1: Somatic Variant Calling with Mutect2\n"
+    raw_vcf = f"{output_prefix}.unfiltered.vcf"
+
+    mutect2_cmd = [
+        "gatk",
+        "Mutect2",
+        "-R",
+        reference_genome,
+        "-I",
+        tumor_bam,
+        "-I",
+        normal_bam,
+        "-normal",
+        os.path.basename(normal_bam).split(".")[0],
+        "-O",
+        raw_vcf,
+    ]
+
+    log += f"Running command: {' '.join(mutect2_cmd)}\n"
+    try:
+        subprocess.run(mutect2_cmd, check=True, capture_output=True)
+        log += f"Successfully generated raw VCF: {raw_vcf}\n\n"
+    except subprocess.CalledProcessError as e:
+        log += f"Error running Mutect2: {str(e)}\n"
+        return log
+
+    # Step 2: Filter somatic calls
+    log += "## Step 2: Filtering Somatic Variants\n"
+    filtered_vcf = f"{output_prefix}.filtered.vcf"
+
+    filter_cmd = [
+        "gatk",
+        "FilterMutectCalls",
+        "-R",
+        reference_genome,
+        "-V",
+        raw_vcf,
+        "-O",
+        filtered_vcf,
+    ]
+
+    log += f"Running command: {' '.join(filter_cmd)}\n"
+    try:
+        subprocess.run(filter_cmd, check=True, capture_output=True)
+        log += f"Successfully filtered variants: {filtered_vcf}\n\n"
+    except subprocess.CalledProcessError as e:
+        log += f"Error filtering variants: {str(e)}\n"
+        return log
+
+    # Step 3: Annotate variants with SnpEff
+    log += "## Step 3: Functional Annotation with SnpEff\n"
+    annotated_vcf = f"{output_prefix}.annotated.vcf"
+
+    snpeff_cmd = ["snpEff", "-v", snpeff_database, filtered_vcf, ">", annotated_vcf]
+
+    log += f"Running command: {' '.join(snpeff_cmd)}\n"
+    try:
+        # Using shell=True because of the redirection
+        subprocess.run(" ".join(snpeff_cmd), shell=True, check=True)
+        log += f"Successfully annotated variants: {annotated_vcf}\n\n"
+    except subprocess.CalledProcessError as e:
+        log += f"Error annotating variants: {str(e)}\n"
+        return log
+
+    # Step 4: Generate summary statistics
+    log += "## Step 4: Generating Summary Statistics\n"
+    summary_file = f"{output_prefix}_mutation_summary.txt"
+
+    # Count total variants
+    count_cmd = f"grep -v '^#' {annotated_vcf} | wc -l"
+    try:
+        total_variants = subprocess.check_output(count_cmd, shell=True).decode().strip()
+        log += f"Total somatic variants detected: {total_variants}\n"
+    except subprocess.CalledProcessError as e:
+        log += f"Error counting variants: {str(e)}\n"
+
+    # Count by variant type
+    log += "Variant types:\n"
+    for variant_type in ["SNP", "INS", "DEL"]:
+        count_type_cmd = f"grep -v '^#' {annotated_vcf} | grep '{variant_type}' | wc -l"
+        try:
+            type_count = subprocess.check_output(count_type_cmd, shell=True).decode().strip()
+            log += f"- {variant_type}: {type_count}\n"
+        except subprocess.CalledProcessError:
+            log += f"- {variant_type}: Error counting\n"
+
+    # Count high impact variants
+    high_impact_cmd = f"grep -v '^#' {annotated_vcf} | grep 'HIGH' | wc -l"
+    try:
+        high_impact = subprocess.check_output(high_impact_cmd, shell=True).decode().strip()
+        log += f"High impact variants: {high_impact}\n\n"
+    except subprocess.CalledProcessError:
+        log += "High impact variants: Error counting\n\n"
+
+    # Step 5: Save summary to file
+    with open(summary_file, "w") as f:
+        f.write("Somatic Mutation Analysis Summary\n")
+        f.write(f"Date: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n")
+        f.write(f"Total somatic variants: {total_variants}\n")
+        f.write(f"Output VCF file: {annotated_vcf}\n")
+
+    log += "## Results\n"
+    log += "Analysis complete. Results saved to:\n"
+    log += f"- Annotated VCF: {annotated_vcf}\n"
+    log += f"- Summary file: {summary_file}\n\n"
+
+    return log
+
+
+def detect_and_characterize_structural_variations(
+    bam_file_path,
+    reference_genome_path,
+    output_dir,
+    cosmic_db_path=None,
+    clinvar_db_path=None,
+):
+    """Detects and characterizes structural variations (SVs) in genomic sequencing data.
+
+    This function uses LUMPY for SV detection followed by annotation with COSMIC and/or ClinVar
+    databases to identify and characterize various types of structural variations including
+    deletions, inversions, translocations, and duplications.
+
+    Parameters
+    ----------
+    bam_file_path : str
+        Path to the aligned sequencing data in BAM format
+    reference_genome_path : str
+        Path to the reference genome in FASTA format
+    output_dir : str
+        Directory where results will be saved
+    cosmic_db_path : str, optional
+        Path to the COSMIC database for cancer annotation
+    clinvar_db_path : str, optional
+        Path to the ClinVar database for clinical annotation
+
+    Returns
+    -------
+    str
+        A research log summarizing the steps performed and results obtained
+
+    """
+    import datetime
+    import os
+    import subprocess
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Initialize research log
+    log = []
+    log.append("## Structural Variation Detection and Characterization")
+    log.append(f"Started at: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append(f"Input BAM file: {bam_file_path}")
+    log.append(f"Reference genome: {reference_genome_path}")
+    log.append(f"Output directory: {output_dir}")
+    log.append("\n")
+
+    # Step 1: Extract discordant read-pairs and split-reads for LUMPY
+    log.append("### Step 1: Extracting discordant read-pairs and split-reads")
+
+    discordant_bam = os.path.join(output_dir, "discordant.bam")
+    split_bam = os.path.join(output_dir, "split.bam")
+
+    try:
+        # Extract discordant read pairs
+        subprocess.run(
+            [
+                "samtools",
+                "view",
+                "-b",
+                "-F",
+                "1294",
+                "-o",
+                discordant_bam,
+                bam_file_path,
+            ],
+            check=True,
+        )
+
+        # Extract split reads
+        subprocess.run(
+            [
+                "samtools",
+                "view",
+                "-h",
+                bam_file_path,
+                "|",
+                "extractSplitReads_BwaMem",
+                "-i",
+                "stdin",
+                "|",
+                "samtools",
+                "view",
+                "-Sb",
+                "-",
+                ">",
+                split_bam,
+            ],
+            shell=True,
+            check=True,
+        )
+
+        log.append("Successfully extracted discordant read-pairs and split-reads")
+    except subprocess.CalledProcessError as e:
+        log.append(f"Error during read extraction: {e}")
+        return "\n".join(log)
+
+    # Step 2: Run LUMPY for SV detection
+    log.append("\n### Step 2: Running LUMPY for structural variation detection")
+
+    vcf_output = os.path.join(output_dir, "structural_variants.vcf")
+
+    try:
+        subprocess.run(
+            [
+                "lumpyexpress",
+                "-B",
+                bam_file_path,
+                "-S",
+                split_bam,
+                "-D",
+                discordant_bam,
+                "-o",
+                vcf_output,
+            ],
+            check=True,
+        )
+
+        log.append("LUMPY analysis completed successfully")
+        log.append(f"Raw SV calls saved to: {vcf_output}")
+    except subprocess.CalledProcessError as e:
+        log.append(f"Error during LUMPY execution: {e}")
+        return "\n".join(log)
+
+    # Step 3: Filter SVs by quality and size
+    log.append("\n### Step 3: Filtering structural variants by quality and size")
+
+    filtered_vcf = os.path.join(output_dir, "filtered_structural_variants.vcf")
+
+    try:
+        # Filter SVs with quality score >= 100 and size >= 100bp
+        subprocess.run(
+            [
+                "bcftools",
+                "filter",
+                "-i",
+                "QUAL>=100 && SVLEN>=100",
+                "-o",
+                filtered_vcf,
+                vcf_output,
+            ],
+            check=True,
+        )
+
+        # Count SVs by type
+        sv_counts = {}
+        sv_types = ["DEL", "DUP", "INV", "BND", "INS"]
+
+        for sv_type in sv_types:
+            result = subprocess.run(
+                ["grep", "-c", f"SVTYPE={sv_type}", filtered_vcf],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+
+            count = 0
+            if result.returncode == 0:
+                count = int(result.stdout.strip())
+            sv_counts[sv_type] = count
+
+        log.append("SV filtering completed")
+        log.append(f"Filtered SVs saved to: {filtered_vcf}")
+        log.append("\nSV counts by type:")
+        for sv_type, count in sv_counts.items():
+            log.append(f"- {sv_type}: {count}")
+    except subprocess.CalledProcessError as e:
+        log.append(f"Error during SV filtering: {e}")
+        return "\n".join(log)
+
+    # Step 4: Annotate SVs with COSMIC and ClinVar (if databases provided)
+    log.append("\n### Step 4: Annotating structural variants")
+
+    annotated_vcf = os.path.join(output_dir, "annotated_structural_variants.vcf")
+
+    try:
+        annotation_cmd = ["annotate_sv.py", "-i", filtered_vcf, "-o", annotated_vcf]
+
+        if cosmic_db_path:
+            annotation_cmd.extend(["-c", cosmic_db_path])
+            log.append(f"Using COSMIC database: {cosmic_db_path}")
+
+        if clinvar_db_path:
+            annotation_cmd.extend(["-v", clinvar_db_path])
+            log.append(f"Using ClinVar database: {clinvar_db_path}")
+
+        # This is a placeholder for the annotation command
+        # In a real implementation, you would use a tool like AnnotSV, VEP, or a custom script
+        log.append("Note: Annotation step is simulated in this implementation")
+        log.append("In a real scenario, tools like AnnotSV or VEP would be used")
+
+        # Instead of running the command, we'll create a simple annotated file
+        with open(filtered_vcf) as infile, open(annotated_vcf, "w") as outfile:
+            for line in infile:
+                if line.startswith("#"):
+                    outfile.write(line)
+                else:
+                    outfile.write(line)
+                    # In a real implementation, annotation would be added here
+
+        log.append("SV annotation completed")
+        log.append(f"Annotated SVs saved to: {annotated_vcf}")
+    except Exception as e:
+        log.append(f"Error during SV annotation: {e}")
+        return "\n".join(log)
+
+    # Step 5: Generate summary report
+    log.append("\n### Step 5: Generating summary report")
+
+    summary_file = os.path.join(output_dir, "sv_summary_report.tsv")
+
+    try:
+        # Convert VCF to a tabular format for easier analysis
+        subprocess.run(
+            [
+                "bcftools",
+                "query",
+                "-f",
+                "%CHROM\t%POS\t%INFO/SVTYPE\t%INFO/SVLEN\t%QUAL\n",
+                "-o",
+                summary_file,
+                annotated_vcf,
+            ],
+            check=True,
+        )
+
+        log.append(f"Summary report generated: {summary_file}")
+    except subprocess.CalledProcessError as e:
+        log.append(f"Error generating summary report: {e}")
+        return "\n".join(log)
+
+    # Final summary
+    log.append("\n## Summary")
+    log.append(f"Total SVs detected: {sum(sv_counts.values())}")
+    log.append("SV types breakdown:")
+    for sv_type, count in sv_counts.items():
+        log.append(f"- {sv_type}: {count} ({count / sum(sv_counts.values()) * 100:.1f}%)")
+
+    log.append("\nFiles generated:")
+    log.append(f"- Raw SV calls: {vcf_output}")
+    log.append(f"- Filtered SVs: {filtered_vcf}")
+    log.append(f"- Annotated SVs: {annotated_vcf}")
+    log.append(f"- Summary report: {summary_file}")
+
+    log.append(f"\nAnalysis completed at: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+
+    return "\n".join(log)
+
+
+def perform_gene_expression_nmf_analysis(
+    expression_data_path,
+    n_components=10,
+    normalize=True,
+    output_dir="nmf_results",
+    random_state=42,
+):
+    """Performs Non-negative Matrix Factorization (NMF) on gene expression data to extract
+    metagenes and their associated sample weights for tumor subtype identification.
+
+    Parameters
+    ----------
+    expression_data_path : str
+        Path to a CSV or TSV file containing gene expression data with genes as rows and samples as columns.
+        Values should be non-negative (e.g., normalized counts or expression values).
+    n_components : int, default=10
+        Number of metagenes (components) to extract.
+    normalize : bool, default=True
+        Whether to normalize the expression data before applying NMF.
+    output_dir : str, default="nmf_results"
+        Directory to save the output files.
+    random_state : int, default=42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results.
+
+    """
+    import os
+    from datetime import datetime
+
+    import numpy as np
+    import pandas as pd
+    from sklearn.decomposition import NMF
+
+    # Start research log
+    log = []
+    log.append(f"NMF GENE EXPRESSION ANALYSIS - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append(f"Parameters: n_components={n_components}, normalize={normalize}")
+
+    # Load expression data from file
+    try:
+        if expression_data_path.endswith(".csv"):
+            expression_data = pd.read_csv(expression_data_path, index_col=0)
+        elif expression_data_path.endswith((".tsv", ".txt")):
+            expression_data = pd.read_csv(expression_data_path, sep="\t", index_col=0)
+        else:
+            log.append("ERROR: Unsupported file format. Please provide a CSV or TSV file.")
+            return "\n".join(log)
+
+        log.append(f"Successfully loaded expression data from {expression_data_path}")
+    except Exception as e:
+        log.append(f"ERROR: Failed to load expression data from {expression_data_path}. Error: {str(e)}")
+        return "\n".join(log)
+
+    # Extract gene and sample information
+    genes = expression_data.index.tolist()
+    samples = expression_data.columns.tolist()
+    X = expression_data.values
+    log.append(f"Input data: {len(genes)} genes × {len(samples)} samples")
+
+    # Check for non-negative values
+    if np.any(X < 0):
+        log.append("WARNING: Negative values found in expression data. Converting to absolute values.")
+        X = np.abs(X)
+
+    # Normalize data if requested
+    if normalize:
+        log.append("Normalizing expression data...")
+        X = X / np.sum(X, axis=0, keepdims=True) * 1000  # TPM-like normalization
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+        log.append(f"Created output directory: {output_dir}")
+
+    # Apply NMF
+    log.append(f"Applying NMF to extract {n_components} metagenes...")
+    model = NMF(
+        n_components=n_components,
+        init="random",
+        random_state=random_state,
+        max_iter=1000,
+    )
+
+    try:
+        # W: metagenes (genes × components)
+        # H: sample weights (components × samples)
+        W = model.fit_transform(X)
+        H = model.components_
+
+        log.append(f"NMF completed successfully in {model.n_iter_} iterations")
+        log.append(f"Explained variance: {model.reconstruction_err_:.4f}")
+
+        # Save metagenes (W matrix)
+        metagenes_file = os.path.join(output_dir, "metagenes.csv")
+        pd.DataFrame(W, index=genes, columns=[f"Metagene_{i + 1}" for i in range(n_components)]).to_csv(metagenes_file)
+        log.append(f"Saved metagenes to {metagenes_file}")
+
+        # Save sample weights (H matrix)
+        weights_file = os.path.join(output_dir, "sample_weights.csv")
+        pd.DataFrame(H, index=[f"Metagene_{i + 1}" for i in range(n_components)], columns=samples).to_csv(weights_file)
+        log.append(f"Saved sample weights to {weights_file}")
+
+        top_genes_file = os.path.join(output_dir, "top_genes_per_metagene.csv")
+        top_genes = {}
+        for i in range(n_components):
+            # Get indices of top 20 genes for this metagene
+            top_indices = np.argsort(W[:, i])[::-1][:20]
+            top_genes[f"Metagene_{i + 1}"] = [genes[idx] for idx in top_indices]
+
+        pd.DataFrame(top_genes).to_csv(top_genes_file)
+        log.append(f"Saved top genes per metagene to {top_genes_file}")
+
+    except Exception as e:
+        log.append(f"ERROR: NMF failed with error: {str(e)}")
+        return "\n".join(log)
+
+    log.append("\nSUMMARY:")
+    log.append(f"- Successfully extracted {n_components} metagenes from {X.shape[0]} genes across {X.shape[1]} samples")
+    log.append(f"- Results saved to: {output_dir}")
+    log.append("- Files generated: metagenes.csv, sample_weights.csv, top_genes_per_metagene.csv")
+    log.append("\nNEXT STEPS:")
+    log.append("- Analyze the metagenes to identify biological pathways")
+    log.append("- Cluster samples based on metagene weights to identify potential tumor subtypes")
+    log.append("- Correlate subtypes with clinical outcomes if available")
+
+    return "\n".join(log)
+
+
+def analyze_copy_number_purity_ploidy_and_focal_events(
+    tumor_bam,
+    reference_genome,
+    normal_bam=None,
+    output_dir="cn_analysis_results",
+    targets_bed=None,
+    antitargets_bed=None,
+    gene_bed=None,
+    focal_genes=None,
+    log2_amp_threshold=1.0,
+    log2_del_threshold=-1.0,
+):
+    """CNVkit-based copy number workflow: CNV segmentation, purity/ploidy & HRD approximation, focal events.
+
+    This function orchestrates a CNVkit-based copy number analysis workflow for tumor samples.
+    It performs CNV segmentation, derives approximate purity & ploidy metrics, calculates a simplified
+    HRD-style summary, and detects focal amplifications/deletions in key oncogenes / tumor suppressors.
+
+    Parameters
+    ----------
+    tumor_bam : str
+        Path to tumor BAM (indexed)
+    reference_genome : str
+        Path to reference FASTA (with index files present)
+    normal_bam : str, optional
+        Matched normal BAM (recommended for allele-specific & purity inference)
+    output_dir : str, default "cn_analysis_results"
+        Directory for all outputs
+    targets_bed : str, optional
+        BED of target regions (e.g. exome / panel) for CNVkit / gCNV
+    antitargets_bed : str, optional
+        BED of antitarget regions for CNVkit (if panel / exome)
+    gene_bed : str, optional
+        BED file with gene coordinates (chrom, start, end, gene). Used for focal event annotation
+    focal_genes : list[str], optional
+        List of genes to highlight for focal amplification/deletion; defaults to ["MYC","ERBB2","CDKN2A"]
+    log2_amp_threshold : float, default 1.0
+        Log2 ratio threshold to call focal amplification (~ >2x copy relative to baseline)
+    log2_del_threshold : float, default -1.0
+        Log2 ratio threshold to call focal deep deletion (~ homozygous loss)
+
+    Returns
+    -------
+    str
+        Research log summarizing steps, tool executions, and findings.
+    """
+    import datetime
+    import math
+    import os
+    import shutil
+    import statistics
+    import subprocess
+
+    import pandas as pd
+
+    log = []
+    ts = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    log.append(f"CNVKIT COPY NUMBER ANALYSIS WORKFLOW - {ts}")
+    log.append("=" * 80)
+    log.append(f"Tumor BAM: {tumor_bam}")
+    if normal_bam:
+        log.append(f"Normal BAM: {normal_bam}")
+    log.append(f"Reference genome: {reference_genome}")
+    log.append(f"Output directory: {output_dir}\n")
+
+    os.makedirs(output_dir, exist_ok=True)
+    sample_name = os.path.splitext(os.path.basename(tumor_bam))[0]
+
+    if focal_genes is None:
+        focal_genes = ["MYC", "ERBB2", "CDKN2A"]
+    # Single informative log line (was duplicated previously)
+    log.append(f"Focal genes for analysis: {', '.join(focal_genes)}")
+
+    # ----------------------------------------------------------------------------------
+    # STEP 1: CNV SEGMENTATION with CNVkit
+    # ----------------------------------------------------------------------------------
+    log.append("STEP 1: CNV Segmentation with CNVkit")
+    cnvkit_path = shutil.which("cnvkit.py") or shutil.which("cnvkit")
+    use_conda_env = False
+
+    # Check if CNVkit is available in biomni_e1 environment
+    if not cnvkit_path:
+        try:
+            result = subprocess.run(
+                ["conda", "run", "-n", "biomni_e1", "which", "cnvkit.py"], capture_output=True, text=True, check=True
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                cnvkit_path = "cnvkit.py"  # Will use via conda run
+                use_conda_env = True
+                log.append("- CNVkit found in biomni_e1 environment")
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    # Fallback to bio_env_py310
+    if not cnvkit_path:
+        try:
+            result = subprocess.run(
+                ["conda", "run", "-n", "bio_env_py310", "which", "cnvkit.py"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                cnvkit_path = "cnvkit.py"  # Will use via conda run
+                use_conda_env = True
+                log.append("- CNVkit found in bio_env_py310 environment")
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    if not cnvkit_path:
+        log.append("- CNVkit not detected in current PATH, biomni_e1, or bio_env_py310 environment")
+        log.append("- Install manually (e.g., pip install cnvkit==0.9.11) or run setup.sh")
+        log.append("- Workflow will exit without CNVkit")
+        return "\n".join(log)
+
+    cnvkit_cns = None
+    log.append(f"- CNVkit detected at: {cnvkit_path}")
+
+    # Determine environment prefix for CNVkit commands
+    env_prefix = ["conda", "run", "-n", "biomni_e1"] if use_conda_env else []
+
+    # CNVkit batch command
+    batch_cmd = env_prefix + [cnvkit_path, "batch", tumor_bam, "-d", output_dir, "-f", reference_genome]
+    if normal_bam:
+        batch_cmd.extend(["-n", normal_bam])
+    if targets_bed:
+        batch_cmd.extend(["-t", targets_bed])
+    if antitargets_bed:
+        batch_cmd.extend(["-a", antitargets_bed])
+    batch_cmd.extend(["--scatter", "--diagram"])
+
+    log.append(f"- Running CNVkit batch command: {' '.join(batch_cmd)}")
+    try:
+        subprocess.run(batch_cmd, check=True, capture_output=True)
+        log.append("- CNVkit batch completed successfully")
+    except subprocess.CalledProcessError as e:
+        log.append(f"- WARNING: CNVkit batch failed: {e}. Proceeding with limited downstream analyses")
+
+    # Check for CNVkit output and run call command
+    cnvkit_cns = os.path.join(output_dir, f"{sample_name}.cns")
+    if os.path.exists(cnvkit_cns):
+        call_cmd = env_prefix + [
+            cnvkit_path,
+            "call",
+            cnvkit_cns,
+            "-o",
+            os.path.join(output_dir, f"{sample_name}.call.cns"),
+            "-m",
+            "clonal",
+        ]
+        log.append(f"- Calling absolute CN: {' '.join(call_cmd)}")
+        try:
+            subprocess.run(call_cmd, check=True, capture_output=True)
+            cnvkit_cns = os.path.join(output_dir, f"{sample_name}.call.cns")
+            log.append("- CNVkit call succeeded")
+        except subprocess.CalledProcessError as e:
+            log.append(f"- WARNING: CNVkit call failed: {e}")
+    else:
+        log.append("- WARNING: Expected CNVkit .cns file not found")
+
+    # ----------------------------------------------------------------------------------
+    # STEP 2: Purity & ploidy approximation (based on CNVkit outputs)
+    # ----------------------------------------------------------------------------------
+    log.append("\nSTEP 2: Purity & Ploidy Approximation")
+    purity_est = None
+    ploidy_est = None
+    seg_source = None
+    seg_df = None
+    try:
+        if cnvkit_cns and os.path.exists(cnvkit_cns):
+            seg_source = cnvkit_cns
+            seg_df = pd.read_csv(cnvkit_cns, sep="\t")
+            log.append(f"- Using CNVkit segments from: {seg_source}")
+
+            # Harmonize columns
+            cols = [c.lower() for c in seg_df.columns]
+            seg_df.columns = cols
+
+            # Obtain log2 column
+            log2_col = None
+            for candidate in ["log2", "log2ratio", "cnlr", "logr"]:
+                if candidate in cols:
+                    log2_col = candidate
+                    break
+            for candidate in ["end", "chromend", "stop"]:
+                if candidate in cols:
+                    end_col = candidate
+                    break
+            for candidate in ["start", "chromstart", "begin"]:
+                if candidate in cols:
+                    start_col = candidate
+                    break
+
+            if log2_col and start_col and end_col:
+                seg_df["seg_length"] = seg_df[end_col] - seg_df[start_col]
+                # Weighted average absolute copy ratio -> approximate ploidy baseline
+                # Convert log2 ratio to absolute copy ratio (assuming diploid baseline = 2)
+                seg_df["abs_cn"] = 2 * (2 ** seg_df[log2_col])
+                weighted_mean_cn = (seg_df["abs_cn"] * seg_df["seg_length"]).sum() / seg_df["seg_length"].sum()
+                ploidy_est = weighted_mean_cn
+                # Approximate purity: higher variance in log2 ratios suggests purity; naive formula
+                mad_log2 = statistics.median([abs(x) for x in seg_df[log2_col] if not math.isnan(x)])
+                purity_est = min(1.0, max(0.2, 1 - mad_log2 / 1.5))  # heuristic clamp
+                log.append(f"- Estimated ploidy (weighted mean CN): {ploidy_est:.2f}")
+                log.append(f"- Estimated purity (heuristic from segmentation dispersion): {purity_est:.2f}")
+            else:
+                log.append("- WARNING: Could not identify necessary columns for purity/ploidy estimation")
+        else:
+            log.append("- No CNVkit segmentation available for purity/ploidy estimation")
+    except Exception as e:
+        log.append(f"- ERROR: Purity/ploidy estimation failed: {e}")
+
+    # ----------------------------------------------------------------------------------
+    # STEP 3: HRD-like summary (simplified proxy)
+    # ----------------------------------------------------------------------------------
+    log.append("\nSTEP 3: HRD Approximation (Simplified)")
+    hrd_metrics = {}
+    try:
+        if seg_df is not None and "seg_length" in seg_df:
+            # Count large-scale transitions (LST proxy: adjacent segments >10 Mb with log2 change >0.2)
+            seg_df_sorted = seg_df.sort_values(
+                by=[c for c in seg_df.columns if c.startswith("chrom") or c == "chrom" or c == "chromosome"][0]
+                if any(c.startswith("chrom") for c in seg_df.columns)
+                else seg_df.columns[0]
+            )
+            lst_count = 0
+            prev = None
+            for _, row in seg_df_sorted.iterrows():
+                if prev is not None:
+                    if row["seg_length"] >= 10_000_000 and prev["seg_length"] >= 10_000_000:
+                        if log2_col and abs(row[log2_col] - prev[log2_col]) > 0.2:
+                            lst_count += 1
+                prev = row
+            hrd_metrics["LST_like"] = lst_count
+            # HRD-LOH proxy: segments with log2 < -0.3 and length >15 Mb
+            if log2_col:
+                hrd_loh = ((seg_df[log2_col] < -0.3) & (seg_df["seg_length"] > 15_000_000)).sum()
+                hrd_metrics["HRD_LOH_like"] = int(hrd_loh)
+            # Telomeric AI proxy omitted (needs allele-specific data)
+            hrd_score = sum(hrd_metrics.values())
+            hrd_metrics["Simplified_HRD_score"] = hrd_score
+            log.append(f"- LST-like events: {hrd_metrics['LST_like']}")
+            log.append(f"- HRD-LOH-like events: {hrd_metrics['HRD_LOH_like']}")
+            log.append(f"- Simplified composite HRD score: {hrd_metrics['Simplified_HRD_score']}")
+            log.append("- NOTE: For clinical/research use, apply scarHRD or HRDetect with allele-specific data")
+        else:
+            log.append("- Segmentation not available; HRD approximation skipped")
+    except Exception as e:
+        log.append(f"- ERROR: HRD approximation failed: {e}")
+
+    # ----------------------------------------------------------------------------------
+    # STEP 4: Focal amplifications/deletions in key genes
+    # ----------------------------------------------------------------------------------
+    log.append("\nSTEP 4: Focal Amplifications / Deletions in Key Genes")
+    focal_events = []
+    try:
+        if seg_df is not None and gene_bed and os.path.exists(gene_bed):
+            genes_df = pd.read_csv(gene_bed, sep="\t", header=None, names=["chrom", "start", "end", "gene"])
+
+            # Normalize chromosome naming
+            def norm_chr(x):
+                return x.replace("chr", "") if isinstance(x, str) else x
+
+            seg_df["chr_norm"] = (
+                seg_df[[c for c in seg_df.columns if c in ["chrom", "chromosome", "chr"]][0]].astype(str).map(norm_chr)
+            )
+            genes_df["chr_norm"] = genes_df["chrom"].astype(str).map(norm_chr)
+            for gene in focal_genes:
+                region = genes_df[genes_df["gene"] == gene]
+                if region.empty:
+                    continue
+                r = region.iloc[0]
+                # Ensure we work on a copy to avoid SettingWithCopyWarning
+                overlaps = seg_df[
+                    (seg_df["chr_norm"] == r["chr_norm"])
+                    & (seg_df[start_col] <= r["end"])
+                    & (seg_df[end_col] >= r["start"])
+                ].copy()
+                if not overlaps.empty and log2_col:
+                    # Choose segment with largest overlap length
+                    r_end = r["end"]
+                    r_start = r["start"]
+                    overlaps["ov_len"] = overlaps.apply(
+                        lambda row, r_end=r_end, r_start=r_start: min(row[end_col], r_end)
+                        - max(row[start_col], r_start),
+                        axis=1,
+                    )
+                    best = overlaps.sort_values("ov_len", ascending=False).iloc[0]
+                    l2 = best[log2_col]
+                    status = None
+                    if l2 >= log2_amp_threshold:
+                        status = "AMPLIFICATION"
+                    elif l2 <= log2_del_threshold:
+                        status = "DELETION"
+                    if status:
+                        focal_events.append((gene, status, l2))
+            if focal_events:
+                for gene, status, l2 in focal_events:
+                    log.append(f"- {gene}: {status} (log2={l2:.2f})")
+            else:
+                log.append("- No focal events meeting thresholds in target genes")
+        else:
+            if not gene_bed:
+                log.append("- Skipped: gene_bed not provided")
+            else:
+                log.append("- Skipped: gene_bed file not found or segmentation unavailable")
+    except Exception as e:
+        log.append(f"- ERROR: Focal event detection failed: {e}")
+
+    # ----------------------------------------------------------------------------------
+    # STEP 5: Summaries & file outputs
+    # ----------------------------------------------------------------------------------
+    log.append("\nSTEP 5: Summary & Output Files")
+    summary = {
+        "purity_estimate": purity_est,
+        "ploidy_estimate": ploidy_est,
+    }
+    summary.update(hrd_metrics)
+    summary_file = os.path.join(output_dir, f"{sample_name}_cn_summary.tsv")
+    try:
+        pd.DataFrame([summary]).to_csv(summary_file, sep="\t", index=False)
+        log.append(f"- Saved summary metrics: {summary_file}")
+    except Exception as e:
+        log.append(f"- WARNING: Could not save summary file: {e}")
+
+    if focal_events:
+        focal_file = os.path.join(output_dir, f"{sample_name}_focal_events.tsv")
+        try:
+            pd.DataFrame(focal_events, columns=["Gene", "Event", "Log2"]).to_csv(focal_file, sep="\t", index=False)
+            log.append(f"- Saved focal events: {focal_file}")
+        except Exception as e:
+            log.append(f"- WARNING: Could not save focal events file: {e}")
+
+    log.append("\nNEXT STEPS:")
+    log.append("- For improved purity/ploidy estimation, consider ABSOLUTE, FACETS, PureCN, or Sequenza")
+    log.append("- For validated HRD scoring, use scarHRD or HRDetect with allele-specific data")
+    log.append("- Integrate CN events with expression data to assess driver gene activation/dosage")
+    log.append("- Visualize CNV profiles using CNVkit's built-in plotting functions")
+
+    return "\n".join(log)

Biomanus_upload/biomni/tool/cell_biology.py

@@ -0,0 +1,742 @@
+def quantify_cell_cycle_phases_from_microscopy(image_paths, output_dir="./results"):
+    """Quantify the percentage of cells in each cell cycle phase using Calcofluor white stained microscopy images.
+
+    This function processes microscopy images where cell walls/septa are stained with Calcofluor white,
+    segments individual cells, extracts features, and classifies each cell into G1, S, or G2/M phase.
+
+    Parameters
+    ----------
+    image_paths : list of str
+        List of file paths to microscopy images of cells stained with Calcofluor white
+    output_dir : str, optional
+        Directory to save results (default: './results')
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis process and results
+
+    """
+    import os
+
+    import numpy as np
+    import pandas as pd
+    from skimage import filters, io, measure, morphology
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Initialize log
+    log = "# Cell Cycle Phase Quantification Analysis Log\n\n"
+    log += f"Processing {len(image_paths)} microscopy images with Calcofluor white staining.\n\n"
+
+    # Initialize data structures to store results
+    all_cells = []
+    cell_features = []
+
+    # Step 1: Process images and segment cells
+    log += "## Image Processing and Cell Segmentation\n\n"
+
+    for i, img_path in enumerate(image_paths):
+        log += f"Processing image {i + 1}/{len(image_paths)}: {os.path.basename(img_path)}\n"
+
+        # Load image
+        img = io.imread(img_path)
+
+        # Convert to grayscale if needed
+        if len(img.shape) > 2:
+            img = np.mean(img, axis=2).astype(np.uint8)
+
+        # Preprocessing
+        filtered_img = filters.gaussian(img, sigma=1.0)
+
+        # Thresholding to identify cell walls
+        threshold = filters.threshold_otsu(filtered_img)
+        binary = filtered_img > threshold
+
+        # Clean up binary image
+        binary = morphology.remove_small_objects(binary, min_size=30)
+        binary = morphology.binary_closing(binary)
+
+        # Segment cells
+        labeled_cells = measure.label(binary)
+        cell_props = measure.regionprops(labeled_cells, intensity_image=img)
+
+        log += f"  - Found {len(cell_props)} cells\n"
+        all_cells.extend(cell_props)
+
+        # Extract features for each cell
+        for cell in cell_props:
+            # Basic morphological features
+            area = cell.area
+            perimeter = cell.perimeter
+            eccentricity = cell.eccentricity
+            mean_intensity = cell.mean_intensity
+
+            # Cell shape features
+            circularity = (4 * np.pi * area) / (perimeter**2) if perimeter > 0 else 0
+
+            # Check for septation (indicative of S or G2/M phase)
+            # Calcofluor white stains the septum more intensely
+            has_septum = False
+            if area > 50:  # Only check larger cells
+                intensity_profile = cell.intensity_image[cell.intensity_image > 0]
+                if intensity_profile.size > 0:
+                    intensity_std = np.std(intensity_profile)
+                    intensity_max = np.max(intensity_profile)
+                    # High standard deviation and max intensity suggests septum presence
+                    has_septum = intensity_std > 0.2 * np.mean(intensity_profile) and intensity_max > 1.5 * np.mean(
+                        intensity_profile
+                    )
+
+            # Store features
+            cell_features.append(
+                [
+                    area,
+                    perimeter,
+                    eccentricity,
+                    mean_intensity,
+                    circularity,
+                    has_septum,
+                    i,  # include image index
+                ]
+            )
+
+    log += f"\nTotal cells detected across all images: {len(all_cells)}\n\n"
+
+    # Step 2: Feature engineering and classification
+    log += "## Cell Cycle Phase Classification\n\n"
+
+    # Convert to numpy array for easier processing
+    X = np.array(cell_features)
+
+    # Simple rule-based classification
+    # This is a simplified approach - in practice, you would train a classifier on labeled data
+    # G1: Smaller cells, no septum
+    # S: Medium-sized cells, early septum formation
+    # G2/M: Larger cells, clear septum, often elongated
+
+    # Define classification rules based on features
+    phases = []
+    for i in range(X.shape[0]):
+        area = X[i, 0]
+        perimeter = X[i, 1]
+        eccentricity = X[i, 2]
+        has_septum = X[i, 5]
+
+        if has_septum and area > np.median(X[:, 0]) * 1.2:
+            # Larger cells with septum are likely in G2/M
+            phases.append("G2/M")
+        elif has_septum or (area > np.median(X[:, 0]) and eccentricity > 0.5):
+            # Cells with septum or larger elongated cells are likely in S
+            phases.append("S")
+        else:
+            # Smaller cells without septum are likely in G1
+            phases.append("G1")
+
+    # Calculate percentages
+    unique_phases, counts = np.unique(phases, return_counts=True)
+    percentages = (counts / len(phases)) * 100
+
+    # Create results table
+    results_df = pd.DataFrame({"Phase": unique_phases, "Count": counts, "Percentage": percentages})
+
+    # Save results
+    results_path = os.path.join(output_dir, "cell_cycle_phases.csv")
+    results_df.to_csv(results_path, index=False)
+
+    # Log results
+    log += "### Cell Cycle Phase Distribution\n\n"
+    for phase, count, percentage in zip(unique_phases, counts, percentages, strict=False):
+        log += f"- {phase}: {count} cells ({percentage:.2f}%)\n"
+
+    log += f"\nResults saved to: {results_path}\n"
+    log += "\nNote: This analysis uses simplified morphological features for classification. "
+    log += (
+        "For more accurate results, a supervised machine learning approach with labeled training data is recommended.\n"
+    )
+
+    return log
+
+
+def quantify_and_cluster_cell_motility(image_sequence_path, output_dir="./results", num_clusters=3):
+    """Quantify cell motility features from time-lapse microscopy images and cluster cells based on motility patterns.
+
+    Parameters
+    ----------
+    image_sequence_path : str
+        Path to directory containing time-lapse microscopy images in sequential order
+    output_dir : str
+        Directory to save output files (default: "./results")
+    num_clusters : int
+        Number of motility pattern clusters to identify (default: 3)
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis process and results
+
+    """
+    import os
+
+    import cv2
+    import numpy as np
+    import pandas as pd
+    from sklearn.cluster import KMeans
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Step 1: Load image sequence
+    image_files = sorted(
+        [f for f in os.listdir(image_sequence_path) if f.endswith((".tif", ".tiff", ".png", ".jpg", ".jpeg"))]
+    )
+
+    if len(image_files) < 2:
+        return "Error: Insufficient images found. At least 2 time points are required."
+
+    # Step 2: Initialize cell tracking
+    first_image = cv2.imread(os.path.join(image_sequence_path, image_files[0]), cv2.IMREAD_GRAYSCALE)
+
+    # Simple cell detection using thresholding and contour detection
+    _, binary = cv2.threshold(first_image, 127, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+    # Extract cell centroids from first frame
+    cells = []
+    for i, contour in enumerate(contours):
+        if cv2.contourArea(contour) > 50:  # Filter small noise
+            M = cv2.moments(contour)
+            if M["m00"] != 0:
+                cx = int(M["m10"] / M["m00"])
+                cy = int(M["m01"] / M["m00"])
+                cells.append({"id": i, "positions": [(cx, cy)], "frame_indices": [0]})
+
+    # Step 3: Track cells across frames
+    for frame_idx, img_file in enumerate(image_files[1:], 1):
+        img = cv2.imread(os.path.join(image_sequence_path, img_file), cv2.IMREAD_GRAYSCALE)
+        _, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+        # Get current frame centroids
+        current_centroids = []
+        for contour in contours:
+            if cv2.contourArea(contour) > 50:
+                M = cv2.moments(contour)
+                if M["m00"] != 0:
+                    cx = int(M["m10"] / M["m00"])
+                    cy = int(M["m01"] / M["m00"])
+                    current_centroids.append((cx, cy))
+
+        # Match cells with nearest centroids in current frame
+        for cell in cells:
+            if len(cell["positions"]) == frame_idx:  # Only track cells found in previous frame
+                prev_pos = cell["positions"][-1]
+
+                if current_centroids:
+                    # Calculate distances to all current centroids
+                    distances = [
+                        np.sqrt((prev_pos[0] - c[0]) ** 2 + (prev_pos[1] - c[1]) ** 2) for c in current_centroids
+                    ]
+                    min_idx = np.argmin(distances)
+
+                    # Only match if distance is below threshold (prevents incorrect matching)
+                    if distances[min_idx] < 50:  # Threshold distance in pixels
+                        cell["positions"].append(current_centroids[min_idx])
+                        cell["frame_indices"].append(frame_idx)
+                        current_centroids.pop(min_idx)  # Remove matched centroid
+
+    # Step 4: Calculate motility features for each cell
+    cell_features = []
+
+    for cell in cells:
+        # Only analyze cells tracked for at least 3 frames
+        if len(cell["positions"]) < 3:
+            continue
+
+        # Calculate displacements between consecutive positions
+        displacements = []
+        for i in range(1, len(cell["positions"])):
+            prev_pos = cell["positions"][i - 1]
+            curr_pos = cell["positions"][i]
+            displacement = np.sqrt((curr_pos[0] - prev_pos[0]) ** 2 + (curr_pos[1] - prev_pos[1]) ** 2)
+            displacements.append(displacement)
+
+        # Calculate speed (pixels per frame)
+        avg_speed = np.mean(displacements)
+
+        # Calculate directionality (displacement from start to end / total path length)
+        start_pos = cell["positions"][0]
+        end_pos = cell["positions"][-1]
+        net_displacement = np.sqrt((end_pos[0] - start_pos[0]) ** 2 + (end_pos[1] - start_pos[1]) ** 2)
+        total_path_length = np.sum(displacements)
+        directionality = net_displacement / total_path_length if total_path_length > 0 else 0
+
+        # Calculate mean squared displacement
+        msd = np.mean(
+            [
+                np.sqrt((cell["positions"][i][0] - start_pos[0]) ** 2 + (cell["positions"][i][1] - start_pos[1]) ** 2)
+                for i in range(1, len(cell["positions"]))
+            ]
+        )
+
+        # Calculate track duration
+        duration = cell["frame_indices"][-1] - cell["frame_indices"][0]
+
+        cell_features.append(
+            {
+                "cell_id": cell["id"],
+                "avg_speed": avg_speed,
+                "directionality": directionality,
+                "msd": msd,
+                "track_duration": duration,
+                "track_length": len(cell["positions"]),
+            }
+        )
+
+    # Step 5: Cluster cells based on motility features
+    if len(cell_features) < num_clusters:
+        return f"Error: Not enough cells ({len(cell_features)}) to form {num_clusters} clusters. Try reducing num_clusters."
+
+    # Create feature matrix for clustering
+    feature_df = pd.DataFrame(cell_features)
+    feature_matrix = feature_df[["avg_speed", "directionality", "msd"]].values
+
+    # Normalize features
+    feature_matrix = (feature_matrix - np.mean(feature_matrix, axis=0)) / np.std(feature_matrix, axis=0)
+
+    # Perform k-means clustering
+    kmeans = KMeans(n_clusters=num_clusters, random_state=42)
+    clusters = kmeans.fit_predict(feature_matrix)
+
+    # Add cluster assignments to dataframe
+    feature_df["cluster"] = clusters
+
+    # Save results to CSV
+    results_file = os.path.join(output_dir, "cell_motility_features.csv")
+    feature_df.to_csv(results_file, index=False)
+
+    # Calculate cluster statistics
+    cluster_stats = feature_df.groupby("cluster").agg(
+        {
+            "avg_speed": ["mean", "std"],
+            "directionality": ["mean", "std"],
+            "msd": ["mean", "std"],
+            "cell_id": "count",
+        }
+    )
+
+    # Save cluster statistics
+    stats_file = os.path.join(output_dir, "cluster_statistics.csv")
+    cluster_stats.to_csv(stats_file)
+
+    # Create research log
+    log = f"""
+Cell Motility Quantification and Clustering Analysis
+===================================================
+
+Analysis Steps:
+1. Loaded {len(image_files)} time-lapse microscopy images
+2. Detected and tracked {len(cells)} initial cells across time frames
+3. Calculated motility features for {len(cell_features)} cells with sufficient tracking data
+4. Performed k-means clustering to identify {num_clusters} distinct motility patterns
+
+Results Summary:
+- Detected {len(cells)} cells in the first frame
+- Successfully tracked {len(cell_features)} cells across multiple frames
+- Clustered cells into {num_clusters} motility pattern groups
+
+Cluster Statistics:
+{cluster_stats.to_string()}
+
+Output Files:
+- Cell motility features saved to: {results_file}
+- Cluster statistics saved to: {stats_file}
+
+Analysis Notes:
+- Features used for clustering: average speed, directionality, and mean squared displacement
+- Cells were required to be tracked for at least 3 frames to be included in the analysis
+"""
+
+    # Save research log
+    log_file = os.path.join(output_dir, "research_log.txt")
+    with open(log_file, "w") as f:
+        f.write(log)
+
+    return log
+
+
+def perform_facs_cell_sorting(
+    cell_suspension_data,
+    fluorescence_parameter,
+    threshold_min=None,
+    threshold_max=None,
+    output_file="sorted_cells.csv",
+):
+    """Performs Fluorescence-Activated Cell Sorting (FACS) to enrich cell populations based on fluorescence characteristics.
+
+    Parameters
+    ----------
+    cell_suspension_data : str
+        Path to the FCS file containing flow cytometry data
+    fluorescence_parameter : str
+        The fluorescence parameter to use for sorting (e.g., 'GFP', 'FITC', 'PE')
+    threshold_min : float, optional
+        Minimum threshold for the fluorescence parameter. Cells below this value will be excluded
+    threshold_max : float, optional
+        Maximum threshold for the fluorescence parameter. Cells above this value will be excluded
+    output_file : str, optional
+        Filename to save the sorted cell population data
+
+    Returns
+    -------
+    str
+        Research log detailing the FACS cell sorting process
+
+    """
+    import os
+
+    import pandas as pd
+
+    # Initialize research log
+    log = "# FACS-based Cell Sorting and Enrichment Research Log\n\n"
+
+    try:
+        # Load cell suspension data
+        log += "## Loading Cell Suspension Data\n"
+        if isinstance(cell_suspension_data, str):
+            # If data is provided as a file path
+            if cell_suspension_data.lower().endswith(".fcs"):
+                try:
+                    import flowkit as fk
+
+                    fcs_data = fk.Sample(cell_suspension_data)
+                    cell_df = pd.DataFrame(fcs_data.get_dataframe())
+                    log += f"Successfully loaded FCS file containing {len(cell_df)} cells\n"
+                except ImportError:
+                    # Fallback if flowkit is not available
+                    log += "FlowKit not available, attempting to load as CSV\n"
+                    cell_df = pd.read_csv(cell_suspension_data)
+            else:
+                # Assume CSV or other tabular format
+                cell_df = pd.read_csv(cell_suspension_data)
+                log += f"Loaded data file containing {len(cell_df)} cells\n"
+        else:
+            # Assume data is already a DataFrame
+            cell_df = cell_suspension_data.copy()
+            log += f"Using provided DataFrame containing {len(cell_df)} cells\n"
+
+        # Validate fluorescence parameter exists in data
+        if fluorescence_parameter not in cell_df.columns:
+            raise ValueError(f"Fluorescence parameter '{fluorescence_parameter}' not found in data")
+
+        # Apply gating strategy based on fluorescence thresholds
+        log += f"\n## Applying Gating Strategy for {fluorescence_parameter}\n"
+        original_count = len(cell_df)
+
+        # Filter cells based on min/max thresholds
+        if threshold_min is not None:
+            cell_df = cell_df[cell_df[fluorescence_parameter] >= threshold_min]
+            log += f"Applied minimum threshold of {threshold_min}: {len(cell_df)} cells remaining\n"
+
+        if threshold_max is not None:
+            cell_df = cell_df[cell_df[fluorescence_parameter] <= threshold_max]
+            log += f"Applied maximum threshold of {threshold_max}: {len(cell_df)} cells remaining\n"
+
+        # Calculate enrichment statistics
+        enrichment_percent = (len(cell_df) / original_count) * 100 if original_count > 0 else 0
+        log += "\n## Enrichment Results\n"
+        log += f"Original population: {original_count} cells\n"
+        log += f"Sorted population: {len(cell_df)} cells\n"
+        log += f"Enrichment percentage: {enrichment_percent:.2f}%\n"
+
+        # Calculate statistics of sorted population
+        mean_fluorescence = cell_df[fluorescence_parameter].mean()
+        median_fluorescence = cell_df[fluorescence_parameter].median()
+
+        log += f"Mean {fluorescence_parameter}: {mean_fluorescence:.2f}\n"
+        log += f"Median {fluorescence_parameter}: {median_fluorescence:.2f}\n"
+
+        # Save sorted population to file
+        cell_df.to_csv(output_file, index=False)
+        log += "\n## Output\n"
+        log += f"Sorted cell population saved to: {os.path.abspath(output_file)}\n"
+
+        return log
+
+    except Exception as e:
+        log += "\n## Error\n"
+        log += f"An error occurred during cell sorting: {str(e)}\n"
+        return log
+
+
+def analyze_flow_cytometry_immunophenotyping(
+    fcs_file_path, gating_strategy, compensation_matrix=None, output_dir="./results"
+):
+    """Analyze flow cytometry data to identify and quantify specific cell populations based on surface markers.
+
+    Parameters
+    ----------
+    fcs_file_path : str
+        Path to the FCS file containing flow cytometry data
+    gating_strategy : dict
+        Dictionary defining the gating strategy. Each key is a population name, and each value is a list of tuples
+        (marker, operator, threshold). For example: {'HSCs': [('Lin', '<', 100), ('Sca1', '>', 1000), ...]}
+    compensation_matrix : numpy.ndarray, optional
+        Spillover/compensation matrix to correct for fluorescence overlap
+    output_dir : str, optional
+        Directory to save the results
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+
+    import pandas as pd
+    from FlowCytometryTools import FCMeasurement
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Load the FCS file
+    sample = FCMeasurement(ID="Sample", datafile=fcs_file_path)
+
+    # Apply compensation if provided
+    if compensation_matrix is not None:
+        sample = sample.compensate(compensation_matrix)
+
+    # Initialize log
+    log = "Flow Cytometry Analysis Log\n"
+    log += "==========================\n"
+    log += f"File analyzed: {os.path.basename(fcs_file_path)}\n"
+    log += f"Total events: {len(sample)}\n\n"
+
+    # Create a dictionary to store population counts
+    populations = {}
+
+    # Apply gating strategy to identify cell populations
+    for pop_name, gates in gating_strategy.items():
+        # Start with all events
+        current_population = sample.copy()
+
+        log += f"Identifying {pop_name} population:\n"
+
+        # Apply each gate sequentially
+        for marker, operator, threshold in gates:
+            initial_count = len(current_population)
+
+            if operator == ">":
+                current_population = current_population.gate(f"{marker} > {threshold}")
+            elif operator == "<":
+                current_population = current_population.gate(f"{marker} < {threshold}")
+            elif operator == "between":
+                # For 'between', threshold should be a tuple (lower, upper)
+                lower, upper = threshold
+                current_population = current_population.gate(f"{marker} > {lower} and {marker} < {upper}")
+
+            final_count = len(current_population)
+            log += f"  Gate {marker} {operator} {threshold}: {initial_count} → {final_count} events\n"
+
+        # Store the final population
+        populations[pop_name] = current_population
+
+        # Calculate percentage of original sample
+        percentage = (len(current_population) / len(sample)) * 100
+        log += f"  Final {pop_name} count: {len(current_population)} events ({percentage:.2f}% of total)\n\n"
+
+    # Create a summary dataframe
+    summary_data = {"Population": [], "Count": [], "Percentage": []}
+
+    for pop_name, population in populations.items():
+        summary_data["Population"].append(pop_name)
+        summary_data["Count"].append(len(population))
+        summary_data["Percentage"].append((len(population) / len(sample)) * 100)
+
+    summary_df = pd.DataFrame(summary_data)
+
+    # Save the summary to a CSV file
+    summary_file = os.path.join(output_dir, "population_summary.csv")
+    summary_df.to_csv(summary_file, index=False)
+
+    log += "Summary of identified populations:\n"
+    for _, row in summary_df.iterrows():
+        log += f"  {row['Population']}: {row['Count']} events ({row['Percentage']:.2f}%)\n"
+
+    log += f"\nDetailed results saved to: {summary_file}\n"
+
+    return log
+
+
+def analyze_mitochondrial_morphology_and_potential(morphology_image_path, potential_image_path, output_dir="./output"):
+    """Quantifies metrics of mitochondrial morphology and membrane potential from fluorescence microscopy images.
+
+    Parameters
+    ----------
+    morphology_image_path : str
+        Path to the fluorescence microscopy image showing mitochondrial morphology (e.g., MTS-GFP)
+    potential_image_path : str
+        Path to the fluorescence microscopy image showing mitochondrial membrane potential (e.g., TMRE staining)
+    output_dir : str, optional
+        Directory to save output files, default is "./output"
+
+    Returns
+    -------
+    str
+        A research log summarizing the analysis steps and results
+
+    """
+    import datetime
+    import os
+
+    import cv2
+    import numpy as np
+    from scipy import ndimage
+    from skimage import filters, io, morphology, util
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    log = []
+    log.append(f"Mitochondrial Analysis - {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append("=" * 50)
+
+    # Load images
+    try:
+        morph_img = io.imread(morphology_image_path)
+        pot_img = io.imread(potential_image_path)
+
+        log.append(f"Successfully loaded morphology image: {morphology_image_path}")
+        log.append(f"Successfully loaded potential image: {potential_image_path}")
+        log.append(f"Morphology image shape: {morph_img.shape}")
+        log.append(f"Potential image shape: {pot_img.shape}")
+    except Exception as e:
+        return f"Error loading images: {str(e)}"
+
+    # Convert to grayscale if needed
+    if len(morph_img.shape) > 2:
+        morph_img = cv2.cvtColor(morph_img, cv2.COLOR_RGB2GRAY)
+        log.append("Converted morphology image to grayscale")
+    if len(pot_img.shape) > 2:
+        pot_img = cv2.cvtColor(pot_img, cv2.COLOR_RGB2GRAY)
+        log.append("Converted potential image to grayscale")
+
+    # Normalize images
+    morph_img = util.img_as_float(morph_img)
+    pot_img = util.img_as_float(pot_img)
+
+    log.append("\nMorphology Analysis:")
+    log.append("-" * 30)
+
+    # Denoise morphology image
+    morph_img_denoised = filters.gaussian(morph_img, sigma=1.0)
+
+    # Threshold to segment mitochondria
+    threshold_value = filters.threshold_otsu(morph_img_denoised)
+    binary_img = morph_img_denoised > threshold_value
+
+    # Remove small objects
+    binary_img = morphology.remove_small_objects(binary_img, min_size=20)
+
+    # Save binary image
+    binary_path = os.path.join(output_dir, "binary_mitochondria.png")
+    io.imsave(binary_path, util.img_as_ubyte(binary_img))
+    log.append(f"Binary segmentation saved to: {binary_path}")
+
+    # Skeletonize for network analysis
+    skeleton = morphology.skeletonize(binary_img)
+    skeleton_path = os.path.join(output_dir, "skeleton.png")
+    io.imsave(skeleton_path, util.img_as_ubyte(skeleton))
+    log.append(f"Skeleton image saved to: {skeleton_path}")
+
+    # Calculate morphology metrics
+    # 1. Count branches and junctions
+    # Label the skeleton
+    labeled_skeleton, num_branches = ndimage.label(skeleton)
+
+    # Find branch points (pixels with more than 2 neighbors)
+    kernel = np.ones((3, 3), dtype=np.uint8)
+    kernel[1, 1] = 0  # Don't count the center pixel
+    neighbor_count = ndimage.convolve(skeleton.astype(np.uint8), kernel)
+    junction_points = (neighbor_count > 2) & skeleton
+    num_junctions = np.sum(junction_points)
+
+    # 2. Calculate fragmentation metrics
+    labeled_objects, num_objects = ndimage.label(binary_img)
+    object_sizes = ndimage.sum(binary_img, labeled_objects, range(1, num_objects + 1))
+    mean_size = np.mean(object_sizes) if len(object_sizes) > 0 else 0
+
+    # Calculate network connectivity (ratio of junctions to branches)
+    connectivity = num_junctions / num_branches if num_branches > 0 else 0
+
+    # Calculate fragmentation index (inverse of mean object size, normalized)
+    fragmentation = 1 / (mean_size / np.max(object_sizes)) if mean_size > 0 and np.max(object_sizes) > 0 else 0
+
+    log.append(f"Number of mitochondrial fragments: {num_objects}")
+    log.append(f"Number of branches: {num_branches}")
+    log.append(f"Number of junction points: {num_junctions}")
+    log.append(f"Network connectivity index: {connectivity:.4f}")
+    log.append(f"Fragmentation index: {fragmentation:.4f}")
+    log.append(f"Mean fragment size: {mean_size:.2f} pixels")
+
+    # Membrane potential analysis
+    log.append("\nMembrane Potential Analysis:")
+    log.append("-" * 30)
+
+    # Create mask from morphology image to analyze only mitochondrial regions
+    mito_mask = binary_img
+
+    # Calculate potential metrics within mitochondrial regions
+    pot_intensity_raw = np.mean(pot_img)
+    pot_intensity_in_mito = np.mean(pot_img[mito_mask]) if np.sum(mito_mask) > 0 else 0
+
+    # Calculate potential heterogeneity (standard deviation of intensity)
+    pot_heterogeneity = np.std(pot_img[mito_mask]) if np.sum(mito_mask) > 0 else 0
+
+    # Calculate potential distribution
+    if np.sum(mito_mask) > 0:
+        percentiles = [10, 25, 50, 75, 90]
+        pot_percentiles = np.percentile(pot_img[mito_mask], percentiles)
+        percentile_str = ", ".join([f"{p}th: {v:.4f}" for p, v in zip(percentiles, pot_percentiles, strict=False)])
+    else:
+        percentile_str = "No mitochondrial regions detected"
+
+    log.append(f"Overall mean TMRE intensity: {pot_intensity_raw:.4f}")
+    log.append(f"Mean TMRE intensity in mitochondria: {pot_intensity_in_mito:.4f}")
+    log.append(f"TMRE intensity heterogeneity (std): {pot_heterogeneity:.4f}")
+    log.append(f"TMRE intensity percentiles: {percentile_str}")
+
+    # Create a combined results image
+    # Overlay potential intensity on morphology
+    overlay = np.zeros((morph_img.shape[0], morph_img.shape[1], 3), dtype=np.float32)
+    overlay[..., 0] = morph_img  # Red channel - morphology
+    overlay[..., 2] = pot_img  # Blue channel - potential
+    overlay = np.clip(overlay, 0, 1)
+
+    overlay_path = os.path.join(output_dir, "morphology_potential_overlay.png")
+    io.imsave(overlay_path, util.img_as_ubyte(overlay))
+    log.append(f"Overlay image saved to: {overlay_path}")
+
+    # Save quantitative results to CSV
+    import csv
+
+    results_path = os.path.join(output_dir, "mitochondrial_analysis_results.csv")
+    with open(results_path, "w", newline="") as csvfile:
+        writer = csv.writer(csvfile)
+        writer.writerow(["Metric", "Value"])
+        writer.writerow(["Number of fragments", num_objects])
+        writer.writerow(["Number of branches", num_branches])
+        writer.writerow(["Number of junctions", num_junctions])
+        writer.writerow(["Network connectivity", connectivity])
+        writer.writerow(["Fragmentation index", fragmentation])
+        writer.writerow(["Mean fragment size", mean_size])
+        writer.writerow(["Mean TMRE intensity", pot_intensity_in_mito])
+        writer.writerow(["TMRE heterogeneity", pot_heterogeneity])
+
+    log.append(f"Quantitative results saved to: {results_path}")
+    log.append("\nAnalysis complete.")
+
+    return "\n".join(log)