Add files using upload-large-folder tool

Biomni/.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

Biomni/.gitignore

@@ -0,0 +1,234 @@
+.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/

Biomni/.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"]

Biomni/DETAILS.md

@@ -0,0 +1,364 @@
+# DETAILS.md
+
+🔍 **Powered by [Detailer](https://detailer.ginylil.com)** - Context-aware codebase analysis
+
+
+
+---
+
+## 1. Project Overview
+
+### Project Purpose & Domain
+
+This project is a comprehensive **biomedical AI toolkit and research platform** designed to facilitate **biomedical data analysis, knowledge extraction, and AI-driven reasoning**. It integrates large language models (LLMs), domain-specific bioinformatics tools, and scientific data processing pipelines to enable:
+
+- Automated extraction of biomedical knowledge from literature (e.g., bioRxiv papers)
+- Querying and integration of diverse biomedical databases and APIs
+- Execution of domain-specific computational biology and physiology analyses
+- AI agent orchestration for complex biomedical reasoning and tool invocation
+- Benchmarking and evaluation of biomedical tasks and datasets
+
+### Target Users and Use Cases
+
+- **Biomedical researchers and data scientists** seeking to automate literature mining, data retrieval, and analysis workflows.
+- **Bioinformaticians** requiring integrated access to multiple biological databases and computational tools.
+- **AI researchers** interested in applying LLMs and autonomous agents to biomedical problem solving.
+- **Developers and integrators** building domain-specific AI pipelines and scientific workflows.
+- Use cases include:
+  - Extracting structured biomedical tasks and entities from scientific papers
+  - Querying gene, protein, disease, and pathway databases via natural language prompts
+  - Running computational models of biological systems (e.g., metabolic networks, signaling)
+  - Performing image analysis and quantitative pathology workflows
+  - Orchestrating multi-step AI reasoning with tool use and self-criticism
+
+### Core Business Logic and Domain Models
+
+- **Biomedical domain models**: gene IDs, protein structures, pathways, disease ontologies, experimental assays.
+- **Task abstractions**: benchmark tasks with prompt/response evaluation (e.g., humanity last exam, lab bench).
+- **Tool metadata schemas**: declarative descriptions of biomedical tools and APIs for dynamic invocation.
+- **AI agent workflows**: ReAct-style reasoning graphs integrating LLMs, tool calls, retrieval, and self-critique.
+- **Data models**: structured JSON, pandas DataFrames, numpy arrays representing biological data and analysis results.
+
+---
+
+## 2. Architecture and Structure
+
+### High-Level Architecture
+
+The system is organized into modular layers and components:
+
+- **Core Library (`biomni/`)**: Contains main application logic, including:
+  - **Agent framework (`biomni/agent/`)**: Implements autonomous AI agents using LLMs and workflow graphs.
+  - **Task definitions (`biomni/task/`)**: Abstract base and concrete biomedical benchmark tasks.
+  - **Tool implementations (`biomni/tool/`)**: Domain-specific analysis functions, API clients, and computational biology workflows.
+  - **Tool metadata (`biomni/tool/tool_description/`)**: Declarative schemas describing tool APIs and parameters.
+  - **Model components (`biomni/model/`)**: AI-driven resource retriever for selecting relevant tools and data.
+  - **Utility modules (`biomni/utils.py`, `biomni/llm.py`, `biomni/env_desc.py`)**: Helpers for LLM instantiation, system commands, environment descriptions.
+  - **Versioning (`biomni/version.py`)**: Package version management.
+
+- **Environment Setup (`biomni_env/`)**: Scripts and configuration files for reproducible environment provisioning, including:
+  - Conda environment YAMLs (`environment.yml`, `bio_env.yml`)
+  - R package specifications (`r_packages.yml`)
+  - CLI tools installer (`install_cli_tools.sh`)
+  - Shell scripts for environment setup (`setup.sh`, `setup_path.sh`)
+
+- **Scripts (`biomni/biorxiv_scripts/`)**: Data processing pipelines for literature mining and task extraction.
+
+- **Documentation and Configuration**:
+  - Root-level files: `README.md`, `CONTRIBUTION.md`, `pyproject.toml`, `.pre-commit-config.yaml`.
+
+---
+
+### Complete Repository Structure
+
+```
+.
+├── biomni/ (90 items)
+│   ├── agent/
+│   │   ├── __init__.py
+│   │   ├── a1.py
+│   │   ├── env_collection.py
+│   │   ├── qa_llm.py
+│   │   └── react.py
+│   ├── biorxiv_scripts/
+│   │   ├── extract_biorxiv_tasks.py
+│   │   ├── generate_function.py
+│   │   └── process_all_subjects.py
+│   ├── model/
+│   │   ├── __init__.py
+│   │   └── retriever.py
+│   ├── task/
+│   │   ├── __init__.py
+│   │   ├── base_task.py
+│   │   ├── hle.py
+│   │   └── lab_bench.py
+│   ├── tool/ (65 items)
+│   │   ├── schema_db/ (25 items)
+│   │   │   ├── cbioportal.pkl
+│   │   │   ├── clinvar.pkl
+│   │   │   ├── dbsnp.pkl
+│   │   │   ├── emdb.pkl
+│   │   │   ├── ensembl.pkl
+│   │   │   ├── geo.pkl
+│   │   │   ├── gnomad.pkl
+│   │   │   ├── gtopdb.pkl
+│   │   │   ├── gwas_catalog.pkl
+│   │   │   ├── interpro.pkl
+│   │   │   └── ... (15 more files)
+│   │   ├── tool_description/ (18 items)
+│   │   │   ├── biochemistry.py
+│   │   │   ├── bioengineering.py
+│   │   │   ├── biophysics.py
+│   │   │   ├── cancer_biology.py
+│   │   │   ├── cell_biology.py
+│   │   │   ├── database.py
+│   │   │   ├── genetics.py
+│   │   │   ├── genomics.py
+│   │   │   ├── immunology.py
+│   │   │   ├── literature.py
+│   │   │   ├── microbiology.py
+│   │   │   ├── molecular_biology.py
+│   │   │   ├── pathology.py
+│   │   │   ├── pharmacology.py
+│   │   │   ├── physiology.py
+│   │   │   ├── support_tools.py
+│   │   │   ├── synthetic_biology.py
+│   │   │   └── systems_biology.py
+│   │   ├── __init__.py
+│   │   ├── biochemistry.py
+│   │   ├── bioengineering.py
+│   │   ├── biophysics.py
+│   │   ├── cancer_biology.py
+│   │   ├── cell_biology.py
+│   │   ├── database.py
+│   │   ├── genetics.py
+│   │   └── ... (12 more files)
+│   ├── __init__.py
+│   ├── env_desc.py
+│   ├── llm.py
+│   ├── utils.py
+│   └── version.py
+├── biomni_env/ (9 items)
+│   ├── README.md
+│   ├── bio_env.yml
+│   ├── cli_tools_config.json
+│   ├── environment.yml
+│   ├── install_cli_tools.sh
+│   ├── install_r_packages.R
+│   ├── r_packages.yml
+│   ├── setup.sh
+│   └── setup_path.sh
+├── figs/
+│   └── biomni_logo.png
+├── tutorials/
+│   ├── examples/
+│   │   └── cloning.ipynb
+│   ├── 101_biomni.ipynb
+│   └── biomni_101.ipynb
+├── .gitignore
+├── .pre-commit-config.yaml
+├── CONTRIBUTION.md
+├── LICENSE
+├── README.md
+└── pyproject.toml
+```
+
+---
+
+## 3. Technical Implementation Details
+
+### Core Modules and Their Roles
+
+#### `biomni/agent/`
+
+- Implements autonomous AI agents using the **ReAct paradigm**:
+  - `react.py`: Main ReAct agent class managing reasoning, tool invocation, retrieval, and self-criticism workflows.
+  - `env_collection.py`: Environment and data retrieval utilities.
+  - `qa_llm.py`: Question-answering LLM wrappers.
+  - `a1.py`: Possibly experimental or auxiliary agent code.
+
+- Uses **langgraph** for workflow graph orchestration and **langchain** for LLM integration.
+
+#### `biomni/task/`
+
+- Defines **benchmark tasks** with a common interface:
+  - `base_task.py`: Abstract base class specifying methods like `get_example()`, `evaluate()`, `output_class()`.
+  - `hle.py`: "Humanity Last Exam" task implementation.
+  - `lab_bench.py`: Lab bench dataset task.
+
+- Tasks load data (e.g., parquet files), generate prompts, and evaluate LLM responses.
+
+#### `biomni/tool/`
+
+- Contains **domain-specific scientific analysis functions** organized by subdomains:
+  - `biochemistry.py`, `bioengineering.py`, `biophysics.py`, `cancer_biology.py`, `cell_biology.py`, `genetics.py`, `pathology.py`, `physiology.py`, `systems_biology.py`, etc.
+  - Each file implements multiple functions performing analyses, simulations, or data processing workflows.
+  - Functions accept input files/parameters and return detailed textual logs and output files.
+
+- **API client modules** (e.g., `database.py`) provide facade functions to query external biomedical databases (UniProt, GWAS Catalog, Ensembl, etc.) via REST or GraphQL APIs, often using LLMs to generate query payloads from natural language prompts.
+
+- **Tool registry (`tool_registry.py`)** manages metadata about available tools, supporting dynamic registration and lookup.
+
+#### `biomni/tool/tool_description/`
+
+- Contains **declarative metadata schemas** describing tool APIs:
+  - Each file exports a `description` list of dictionaries defining tool names, descriptions, required and optional parameters with types and defaults.
+  - Supports **dynamic API generation, validation, and documentation**.
+  - Organized by biological domain (e.g., genetics, immunology, pathology).
+
+#### `biomni/model/retriever.py`
+
+- Implements `ToolRetriever` class for **AI-driven resource selection**:
+  - Uses LLMs (OpenAI or Anthropic) to parse user queries and select relevant tools, datasets, and libraries.
+  - Encapsulates prompt formatting and response parsing logic.
+
+#### `biomni/utils.py` and `biomni/llm.py`
+
+- `utils.py`: Utility functions for running system commands (R, Bash), file operations, schema generation, logging, and colorized printing.
+- `llm.py`: Factory functions to instantiate LLMs (OpenAI, Anthropic) with configurable parameters.
+
+#### `biomni/env_desc.py`
+
+- Contains **environment and dataset descriptions**, acting as a centralized metadata repository for datasets and experimental environments.
+
+---
+
+### Environment Setup (`biomni_env/`)
+
+- `setup.sh`: Main shell script to create conda environment, install R packages, and CLI bioinformatics tools.
+- `install_cli_tools.sh`: Automates downloading, compiling, and installing external bioinformatics command-line tools, managing PATH and verification.
+- `r_packages.yml`: Lists R packages required.
+- `environment.yml` and `bio_env.yml`: Conda environment specifications.
+- `setup_path.sh`: Shell script to update environment variables for CLI tools.
+
+---
+
+### Entry Points and Execution Flow
+
+- **Agent usage**: Instantiate `react` agent from `biomni.agent.react`, configure with tools and retrieval, then call `go(prompt)` to run reasoning workflows.
+- **Task evaluation**: Use classes in `biomni.task` to load datasets, generate prompts, and evaluate LLM outputs.
+- **Tool invocation**: Call functions in `biomni.tool` modules or use API facades in `database.py` to query external resources.
+- **Metadata-driven tool discovery**: Use `tool_registry.py` and `tool_description` schemas to dynamically discover and validate tools.
+- **Environment setup**: Run `biomni_env/setup.sh` to provision environment and install dependencies.
+
+---
+
+## 4. Development Patterns and Standards
+
+### Code Organization Principles
+
+- **Modular design**: Clear separation of concerns by domain and functionality (agent, task, tool, model).
+- **Functional programming style**: Most analysis modules use standalone functions with explicit inputs and outputs.
+- **Declarative metadata**: Tool descriptions and schemas are separated from implementation, enabling dynamic validation and UI generation.
+- **Abstract base classes**: Used in `biomni.task.base_task` to enforce consistent task interfaces.
+- **Factory pattern**: Used in `llm.py` to instantiate LLMs based on configuration.
+- **Strategy pattern**: Task implementations and tool retrieval use interchangeable strategies.
+
+### Testing and Coverage
+
+- No explicit test files detected; testing likely manual or via notebooks (`tutorials/`).
+- Tasks and tools return detailed logs suitable for manual verification.
+- Metadata schemas facilitate automated validation of inputs.
+
+### Error Handling and Logging
+
+- Use of try-except blocks around external calls and subprocesses.
+- Logging via custom callback handlers (`PromptLogger`, `NodeLogger`) in LLM interactions.
+- Utilities provide colorized printing and error wrappers for robustness.
+
+### Configuration Management
+
+- Environment variables for API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
+- YAML and JSON files for environment and tool configuration.
+- Dynamic loading of schemas from pickle files for API request generation.
+- CLI tools and R packages installed via scripted environment setup.
+
+---
+
+## 5. Integration and Dependencies
+
+### External Libraries
+
+- **LLM & AI Frameworks**: `langchain_core`, `langchain_openai`, `langchain_anthropic`
+- **Scientific Computing**: `numpy`, `pandas`, `scipy`, `scikit-image`, `matplotlib`, `BioPython`, `cobra`, `sklearn`
+- **Data Processing**: `pickle`, `json`, `requests`, `PyPDF2`
+- **System and OS**: `subprocess`, `os`, `sys`, `tempfile`, `multiprocessing`
+- **Others**: `tqdm` (progress bars), `enum`, `ast` (code introspection)
+
+### External APIs and Data Sources
+
+- Biomedical databases: UniProt, GWAS Catalog, Ensembl, ClinVar, dbSNP, EMDB, GEO, GnomAD, InterPro, etc.
+- Bioinformatics tools: PLINK, IQ-TREE, GCTA, MACS2, samtools, LUMPY, installed via CLI tools installer.
+- R packages for statistical and bioinformatics analyses.
+
+### Build and Deployment Dependencies
+
+- Python 3 environment managed via Conda (`environment.yml`).
+- R environment with specified packages (`r_packages.yml`).
+- Shell scripts for CLI tool installation and environment setup.
+- Pre-commit hooks for code quality and security.
+
+---
+
+## 6. Usage and Operational Guidance
+
+### Getting Started
+
+1. **Environment Setup**
+   - Run `biomni_env/setup.sh` to create the Conda environment, install R packages, and CLI tools.
+   - Source `biomni_env/setup_path.sh` or add it to your shell profile to configure PATH.
+
+2. **API Keys**
+   - Set environment variables `OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` for LLM access.
+
+3. **Running Agents**
+   - Import and instantiate the `react` agent from `biomni.agent.react`.
+   - Configure with desired tools and retrieval options.
+   - Call `go(prompt)` to execute reasoning workflows.
+
+4. **Executing Tasks**
+   - Use classes in `biomni.task` to load datasets and evaluate LLM responses.
+   - Implement new tasks by subclassing `base_task` and following the interface.
+
+5. **Querying Databases**
+   - Use `biomni.tool.database` functions (e.g., `query_uniprot`, `query_gwas_catalog`) to retrieve data via natural language or direct parameters.
+
+6. **Extending Tools**
+   - Add new tool metadata in `biomni/tool/tool_description/` as structured dictionaries.
+   - Implement corresponding analysis functions in `biomni/tool/`.
+   - Register tools in `tool_registry.py` for discovery.
+
+### Monitoring and Debugging
+
+- Use logging callbacks (`PromptLogger`, `NodeLogger`) to trace LLM interactions.
+- Check output logs returned by analysis functions for detailed execution info.
+- Use pre-commit hooks to maintain code quality.
+
+### Performance and Scalability
+
+- Modular design allows parallel execution of tasks and tools.
+- Timeout wrappers in agent tools prevent hanging executions.
+- Use of efficient numerical libraries (`numpy`, `scipy`) for computational tasks.
+- Large data handled via streaming and chunking (e.g., PDF text extraction).
+
+### Security Considerations
+
+- API keys managed via environment variables, not hardcoded.
+- Pre-commit hooks include security checks.
+- External tool installations verified via version commands.
+
+### Observability
+
+- Progress bars (`tqdm`) used in data processing scripts.
+- Structured logs and JSON outputs facilitate downstream analysis.
+- Agent workflows produce detailed message histories for audit.
+
+---
+
+## Summary
+
+This project is a **modular, extensible biomedical AI platform** integrating **LLM-powered agents**, **domain-specific scientific tools**, and **metadata-driven APIs** to automate complex biomedical research workflows. It emphasizes **declarative tool descriptions**, **dynamic resource retrieval**, and **robust environment provisioning** to enable researchers and developers to build, evaluate, and extend AI-driven biomedical applications efficiently.
+
+---
+
+# End of DETAILS.md

Biomni/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.

Biomni/MANIFEST.in

@@ -0,0 +1,27 @@
+# MANIFEST.in
+
+# Include all python files from the biomni package
+recursive-include biomni *.py
+
+# Include the .pkl database files
+recursive-include biomni/tool/schema_db *.pkl
+
+# Include specific files from biomni_env, but not the biomni_tools subdirectory
+recursive-include biomni_env *.py *.sh *.yml *.yaml *.txt *.md *.json *.R
+
+# Exclude specific directories that are not part of the package
+prune tutorials/data
+prune biomni_env/biomni_tools
+
+# Exclude build artifacts and caches
+global-exclude *.py[co]
+global-exclude __pycache__
+global-exclude .ruff_cache
+prune build
+prune dist
+prune *.egg-info
+
+# Include other necessary files
+include README.md
+include LICENSE
+include pyproject.toml

Biomni/biomni/__init__.py

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

Biomni/biomni/agent/__init__.py

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

Biomni/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

Biomni/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

Biomni/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

Biomni/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

Biomni/biomni/config.py

@@ -0,0 +1,99 @@
+"""
+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-5"
+    temperature: float = 0.7
+
+    # Tool settings
+    use_tool_retriever: bool = True
+
+    # 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_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,
+            "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()

Biomni/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.",
+}

Biomni/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.",
+}

Biomni/biomni/eval/__init__.py

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

Biomni/biomni/llm.py

@@ -0,0 +1,275 @@
+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}")
+
+        return ChatAnthropic(
+            model=model,
+            temperature=temperature,
+            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'"
+        )

Biomni/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"]

Biomni/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

Biomni/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

Biomni/biomni/tool/__init__.py

@@ -0,0 +1 @@
+from biomni.utils import get_tool_decorated_functions  # noqa: F401

Biomni/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)

Biomni/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)

Biomni/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

Biomni/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)

Biomni/biomni/tool/example_mcp_tools/pubmed_mcp.py

@@ -0,0 +1,38 @@
+import os
+
+from Bio import Entrez
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel
+
+Entrez.email = os.getenv("NCBI_EMAIL") or "YOUR_EMAIL"
+mcp = FastMCP("pubmed-live")
+
+
+class Article(BaseModel):
+    pmid: str
+    title: str | None = None
+    journal: str | None = None
+    year: str | None = None
+    abstract: str | None = None
+
+
+@mcp.tool()
+def search_pubmed(query: str, max_results: int = 10) -> list[Article]:
+    ids = Entrez.read(Entrez.esearch(db="pubmed", term=query, retmax=max_results))["IdList"]
+    summaries = Entrez.read(Entrez.esummary(db="pubmed", id=",".join(ids))) if ids else []
+    articles: list[Article] = []
+    for s in summaries:
+        articles.append(
+            Article(pmid=s["Id"], title=s["Title"], journal=s.get("FullJournalName", ""), year=s.get("PubDate", "")[:4])
+        )
+    return articles
+
+
+@mcp.tool()
+def get_article_abstract(pmid: str) -> str:
+    with Entrez.efetch(db="pubmed", id=pmid, rettype="abstract", retmode="text") as h:
+        return h.read()
+
+
+if __name__ == "__main__":
+    mcp.run()

Biomni/biomni/tool/genetics.py

@@ -0,0 +1,1672 @@
+def liftover_coordinates(
+    chromosome: str,
+    position: int,
+    input_format: str,
+    output_format: str,
+    data_path: str,
+) -> str:
+    """Perform liftover of genomic coordinates between hg19 and hg38 formats with detailed intermediate steps.
+
+    Args:
+        chromosome (str): Chromosome number (e.g., '1', 'X').
+        position (int): Genomic position.
+        input_format (str): Input genome build ('hg19' or 'hg38').
+        output_format (str): Output genome build ('hg19' or 'hg38').
+        data_path (str): Path to liftover chain files.
+
+    Returns:
+        str: A detailed string explaining the steps and the final result or any error encountered.
+
+    """
+    from pyliftover import LiftOver
+
+    steps = []
+
+    try:
+        steps.append(
+            f"Starting liftover process for chromosome {chromosome}, position {position} from {input_format} to {output_format}."
+        )
+
+        # Load the liftover chain files
+        steps.append("Loading liftover chain files...")
+        hg19_to_hg38_liftover = LiftOver(data_path + "/liftover/hg19ToHg38.over.chain.gz")
+        hg38_to_hg19_liftover = LiftOver(data_path + "/liftover/hg38ToHg19.over.chain.gz")
+        steps.append("Liftover chain files loaded successfully.")
+
+        # Choose the appropriate LiftOver object
+        if input_format == "hg19" and output_format == "hg38":
+            lo = hg19_to_hg38_liftover
+            steps.append("Selected liftover chain: hg19 to hg38.")
+        elif input_format == "hg38" and output_format == "hg19":
+            lo = hg38_to_hg19_liftover
+            steps.append("Selected liftover chain: hg38 to hg19.")
+        else:
+            steps.append("Error: Unsupported format conversion.")
+            return "\n".join(
+                steps
+                + ["Error: Unsupported format conversion. Supported formats are 'hg19' to 'hg38' or 'hg38' to 'hg19'."]
+            )
+
+        # Perform the liftover conversion
+        steps.append(f"Performing liftover for chr{chromosome}, position {position}...")
+        lifted_coordinates = lo.convert_coordinate(f"chr{chromosome}", position)
+
+        if lifted_coordinates:
+            result = (
+                f"Successfully lifted coordinates from {input_format} to {output_format}.\n"
+                f"Original: chr{chromosome}, position {position}.\n"
+                f"Lifted: chromosome {lifted_coordinates[0][0]}, position {lifted_coordinates[0][1]}, strand {lifted_coordinates[0][2]}."
+            )
+            steps.append(result)
+            return "\n".join(steps)
+        else:
+            steps.append("Error: Liftover failed. No coordinates found for the given input.")
+            return "\n".join(steps + ["Error: Liftover failed. No coordinates found."])
+
+    except Exception as e:
+        steps.append(f"Exception encountered: {str(e)}")
+        return "\n".join(steps)
+
+
+import os
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+import torch
+from torch import nn, optim
+
+
+def bayesian_finemapping_with_deep_vi(
+    gwas_summary_path,
+    ld_matrix,
+    n_iterations=5000,
+    learning_rate=0.01,
+    hidden_dim=64,
+    credible_threshold=0.95,
+):
+    """Performs Bayesian fine-mapping from GWAS summary statistics using deep variational inference.
+
+    This function implements a deep neural network-based variational inference approach to compute
+    posterior inclusion probabilities (PIPs) and credible sets for putative causal variants from
+    GWAS summary statistics and linkage disequilibrium (LD) information.
+
+    Parameters
+    ----------
+    gwas_summary_path : str
+        Path to CSV or TSV file containing GWAS summary statistics. Expected columns:
+        - 'variant_id': Identifier for each variant
+        - 'effect_size': Effect size (beta) for each variant
+        - 'pvalue': P-value for each variant
+        - 'se': Standard error for each variant (optional)
+
+    ld_matrix : numpy.ndarray
+        Linkage disequilibrium matrix with pairwise correlations between variants.
+
+    n_iterations : int, optional
+        Number of training iterations for the variational inference algorithm.
+        Default is 5000.
+
+    learning_rate : float, optional
+        Learning rate for the optimization algorithm. Default is 0.01.
+
+    hidden_dim : int, optional
+        Hidden dimension size for the neural network. Default is 64.
+
+    credible_threshold : float, optional
+        Threshold for defining the credible set (e.g., 0.95 for a 95% credible set).
+        Default is 0.95.
+
+    Returns
+    -------
+    str
+        A detailed research log of the fine-mapping analysis including:
+        - Number of variants analyzed
+        - Top variants ranked by posterior inclusion probability
+        - Credible set variants
+        - Visualizations of the posterior distributions
+
+    """
+    import matplotlib.pyplot as plt
+    import pandas as pd
+
+    # Initialize the research log
+    log = []
+    log.append(
+        f"# Bayesian Fine-mapping Analysis with Deep Variational Inference - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
+    )
+    log.append("\n## Data Preprocessing")
+
+    # Load data from file
+    try:
+        if gwas_summary_path.endswith(".csv"):
+            gwas_summary = pd.read_csv(gwas_summary_path)
+        elif gwas_summary_path.endswith((".tsv", ".txt")):
+            gwas_summary = pd.read_csv(gwas_summary_path, sep="\t")
+        else:
+            log.append("Error: Unsupported file format. Please provide a CSV or TSV file.")
+            return "\n".join(log)
+        log.append(f"Successfully loaded GWAS summary data from {gwas_summary_path}")
+    except Exception as e:
+        log.append(f"Error loading GWAS summary data: {str(e)}")
+        return "\n".join(log)
+
+    # Check input data
+    if gwas_summary is None:
+        log.append("Error: Failed to load GWAS summary data.")
+        return "\n".join(log)
+
+    if ld_matrix is None:
+        log.append("Error: LD matrix is required for fine-mapping analysis.")
+        return "\n".join(log)
+
+    n_variants = len(gwas_summary)
+    log.append(f"Analyzing {n_variants} genetic variants")
+
+    # Check if LD matrix dimensions match the number of variants
+    if ld_matrix.shape[0] != n_variants or ld_matrix.shape[1] != n_variants:
+        log.append(f"Error: LD matrix dimensions ({ld_matrix.shape}) do not match number of variants ({n_variants})")
+        return "\n".join(log)
+
+    # Prepare data for analysis
+    log.append("\nPreparing data for analysis...")
+
+    # Compute Z-scores if not already present
+    if "z_score" not in gwas_summary.columns:
+        log.append("Computing Z-scores from effect sizes and standard errors...")
+        if "se" in gwas_summary.columns:
+            gwas_summary["z_score"] = gwas_summary["effect_size"] / gwas_summary["se"]
+        else:
+            # Approximate Z-scores from p-values
+            log.append("Standard errors not available, approximating Z-scores from p-values...")
+            # Convert p-values to Z-scores (two-sided test)
+            from scipy.stats import norm
+
+            gwas_summary["z_score"] = (
+                gwas_summary["effect_size"].abs()
+                / gwas_summary["effect_size"]
+                * norm.ppf(1 - gwas_summary["pvalue"] / 2)
+            )
+
+    # Convert data to tensors
+    z_scores = torch.FloatTensor(gwas_summary["z_score"].values)
+    ld_tensor = torch.FloatTensor(ld_matrix)
+
+    log.append(f"Processed {len(z_scores)} z-scores from GWAS summary")
+    log.append("LD matrix shape: " + str(ld_matrix.shape))
+
+    # Define the variational inference model
+    class VariationalFineMapping(nn.Module):
+        def __init__(self, n_variants, hidden_dim):
+            super().__init__()
+            self.encoder = nn.Sequential(
+                nn.Linear(n_variants, hidden_dim),
+                nn.ReLU(),
+                nn.Linear(hidden_dim, hidden_dim),
+                nn.ReLU(),
+            )
+            # Output log alpha parameters for the Bernoulli variables
+            self.log_alpha = nn.Linear(hidden_dim, n_variants)
+
+        def forward(self, x):
+            h = self.encoder(x)
+            log_alpha = self.log_alpha(h)
+            # Apply sigmoid to get inclusion probabilities
+            return torch.sigmoid(log_alpha)
+
+        def elbo_loss(self, z_scores, ld_matrix, pips, n_samples=10):
+            # Sample from approximate posterior
+            samples = torch.bernoulli(pips.unsqueeze(0).repeat(n_samples, 1))
+
+            # Prior term (sparsity prior)
+            prior_term = -0.01 * torch.sum(pips)
+
+            # Likelihood term
+            likelihood_term = 0
+            for s in samples:
+                # Compute expected z-scores under the model
+                expected_z = torch.matmul(ld_matrix, s * z_scores)
+                # Compute likelihood
+                likelihood_term += -torch.sum((z_scores - expected_z) ** 2)
+
+            likelihood_term /= n_samples
+
+            return -(prior_term + likelihood_term)
+
+    # Initialize model, optimizer and training
+    log.append("\n## Initializing deep variational inference model")
+    model = VariationalFineMapping(n_variants, hidden_dim)
+    optimizer = optim.Adam(model.parameters(), lr=learning_rate)
+
+    # Training loop
+    log.append("\n## Training variational inference model")
+    losses = []
+
+    for i in range(n_iterations):
+        optimizer.zero_grad()
+        pips = model(z_scores)
+        loss = model.elbo_loss(z_scores, ld_tensor, pips)
+        loss.backward()
+        optimizer.step()
+
+        losses.append(loss.item())
+
+        if (i + 1) % (n_iterations // 5) == 0:
+            log.append(f"  Iteration {i + 1}/{n_iterations}, Loss: {loss.item():.4f}")
+
+    # Get final posterior inclusion probabilities
+    with torch.no_grad():
+        final_pips = model(z_scores).numpy()
+
+    # Create DataFrame with results
+    results_df = gwas_summary.copy()
+    results_df["pip"] = final_pips
+    results_df = results_df.sort_values("pip", ascending=False)
+
+    # Generate credible sets
+    log.append("\n## Generating credible sets")
+
+    # Sort variants by PIP
+    sorted_variants = results_df.sort_values("pip", ascending=False)
+
+    # Calculate cumulative sum of PIPs
+    sorted_variants["cumulative_pip"] = sorted_variants["pip"].cumsum()
+
+    # Identify variants in the credible set
+    credible_set = sorted_variants[sorted_variants["cumulative_pip"] <= credible_threshold]
+
+    if len(credible_set) == 0:
+        # If no variants meet the threshold, include at least the top variant
+        credible_set = sorted_variants.iloc[:1]
+
+    log.append(f"Identified {len(credible_set)} variants in the {credible_threshold * 100}% credible set")
+
+    # Save results to files
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_file = f"finemapping_results_{timestamp}.csv"
+    credible_set_file = f"credible_set_{timestamp}.csv"
+
+    results_df.to_csv(results_file, index=False)
+    credible_set.to_csv(credible_set_file, index=False)
+
+    log.append(f"\nFull results saved to: {results_file}")
+    log.append(f"Credible set saved to: {credible_set_file}")
+
+    # Summary of top variants
+    log.append("\n## Top variants by posterior inclusion probability (PIP)")
+    for i, (_, row) in enumerate(results_df.head(10).iterrows()):
+        log.append(f"  {i + 1}. Variant: {row['variant_id']}, PIP: {row['pip']:.4f}, P-value: {row['pvalue']:.2e}")
+
+    log.append("\n## Variants in the credible set")
+    for i, (_, row) in enumerate(credible_set.iterrows()):
+        log.append(f"  {i + 1}. Variant: {row['variant_id']}, PIP: {row['pip']:.4f}")
+
+    # Create a simple visualization
+    try:
+        plt.figure(figsize=(10, 6))
+        plt.bar(range(len(results_df[:50])), results_df["pip"][:50])
+        plt.xlabel("Variant index (sorted by PIP)")
+        plt.ylabel("Posterior Inclusion Probability")
+        plt.title("Top 50 variants by PIP")
+        plot_file = f"pip_plot_{timestamp}.png"
+        plt.savefig(plot_file)
+        plt.close()
+        log.append(f"\nPlot of PIPs saved to: {plot_file}")
+    except Exception as e:
+        log.append(f"\nCould not create visualization: {str(e)}")
+
+    log.append("\n## Analysis complete")
+
+    return "\n".join(log)
+
+
+def analyze_cas9_mutation_outcomes(
+    reference_sequences,
+    edited_sequences,
+    cell_line_info=None,
+    output_prefix="cas9_mutation_analysis",
+):
+    """Analyzes and categorizes mutations induced by Cas9 at target sites.
+
+    Parameters
+    ----------
+    reference_sequences : dict
+        Dictionary mapping sequence IDs to reference DNA sequences (strings)
+    edited_sequences : dict of dict
+        Nested dictionary: {sequence_id: {read_id: sequence}}
+        Contains the edited/mutated sequences for each reference
+    cell_line_info : dict, optional
+        Dictionary mapping sequence IDs to cell line information (e.g., wildtype, knockout gene)
+    output_prefix : str, optional
+        Prefix for output files
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    from collections import defaultdict
+
+    from Bio import pairwise2
+
+    # Initialize results storage
+    results = []
+    mutation_counts = defaultdict(lambda: defaultdict(int))
+
+    # Define mutation categories
+    categories = {
+        "no_mutation": "No mutation detected",
+        "short_deletion": "Short deletion (1-10 bp)",
+        "medium_deletion": "Medium deletion (11-30 bp)",
+        "long_deletion": "Long deletion (>30 bp)",
+        "single_insertion": "Single base insertion",
+        "longer_insertion": "Longer insertion (>1 bp)",
+        "indel": "Insertion and deletion",
+    }
+
+    log = "# Cas9-Induced Mutation Outcome Analysis\n\n"
+    log += "## Analysis Steps:\n\n"
+    log += "1. Loading and processing sequence data\n"
+    log += f"2. Analyzing {len(reference_sequences)} target sites\n"
+
+    # Process each reference sequence and its edited versions
+    for seq_id, ref_seq in reference_sequences.items():
+        cell_line = cell_line_info.get(seq_id, "Unknown") if cell_line_info else "Unknown"
+        log += f"\n### Processing target site: {seq_id} (Cell line: {cell_line})\n"
+
+        site_results = []
+        site_mutation_counts = defaultdict(int)
+        total_reads = len(edited_sequences.get(seq_id, {}))
+
+        if total_reads == 0:
+            log += f"No edited sequences found for {seq_id}\n"
+            continue
+
+        log += f"Analyzing {total_reads} sequence reads...\n"
+
+        # Process each edited sequence for this reference
+        for read_id, edited_seq in edited_sequences.get(seq_id, {}).items():
+            # Perform sequence alignment
+            alignments = pairwise2.align.globalms(ref_seq, edited_seq, 2, -1, -2, -0.5)
+
+            if not alignments:
+                log += f"Warning: Could not align read {read_id}\n"
+                continue
+
+            best_alignment = alignments[0]
+            ref_aligned, edited_aligned, score, start, end = best_alignment
+
+            # Analyze mutations
+            deletions = []
+            insertions = []
+            del_count = 0
+            ins_count = 0
+
+            i, j = 0, 0
+            while i < len(ref_aligned) and j < len(edited_aligned):
+                if ref_aligned[i] == "-":  # Insertion in edited sequence
+                    ins_start = j
+                    while i < len(ref_aligned) and ref_aligned[i] == "-":
+                        i += 1
+                        j += 1
+                    insertions.append((ins_start, j - ins_start))
+                    ins_count += j - ins_start
+                elif edited_aligned[j] == "-":  # Deletion in edited sequence
+                    del_start = i
+                    while j < len(edited_aligned) and edited_aligned[j] == "-":
+                        i += 1
+                        j += 1
+                    deletions.append((del_start, i - del_start))
+                    del_count += i - del_start
+                else:
+                    i += 1
+                    j += 1
+
+            # Categorize mutation
+            mutation_type = "no_mutation"
+            if del_count > 0 and ins_count > 0:
+                mutation_type = "indel"
+            elif del_count > 0:
+                if del_count <= 10:
+                    mutation_type = "short_deletion"
+                elif del_count <= 30:
+                    mutation_type = "medium_deletion"
+                else:
+                    mutation_type = "long_deletion"
+            elif ins_count > 0:
+                mutation_type = "single_insertion" if ins_count == 1 else "longer_insertion"
+
+            # Add to results
+            site_results.append(
+                {
+                    "sequence_id": seq_id,
+                    "read_id": read_id,
+                    "cell_line": cell_line,
+                    "mutation_type": mutation_type,
+                    "deletion_count": del_count,
+                    "insertion_count": ins_count,
+                }
+            )
+
+            site_mutation_counts[mutation_type] += 1
+            mutation_counts[cell_line][mutation_type] += 1
+
+        # Calculate percentages for this site
+        log += "\nMutation distribution for this target site:\n"
+        for mut_type, count in site_mutation_counts.items():
+            percentage = (count / total_reads) * 100
+            log += f"- {categories[mut_type]}: {count} reads ({percentage:.1f}%)\n"
+
+        # Add site results to overall results
+        results.extend(site_results)
+
+    # Create results dataframe and save to CSV
+    results_df = pd.DataFrame(results)
+    output_file = f"{output_prefix}_detailed_results.csv"
+    results_df.to_csv(output_file, index=False)
+
+    # Create summary dataframe
+    summary_data = []
+    for cell_line, mut_counts in mutation_counts.items():
+        total = sum(mut_counts.values())
+        for mut_type, count in mut_counts.items():
+            percentage = (count / total) * 100 if total > 0 else 0
+            summary_data.append(
+                {
+                    "cell_line": cell_line,
+                    "mutation_type": mut_type,
+                    "count": count,
+                    "percentage": percentage,
+                }
+            )
+
+    summary_df = pd.DataFrame(summary_data)
+    summary_file = f"{output_prefix}_summary.csv"
+    summary_df.to_csv(summary_file, index=False)
+
+    # Add summary to log
+    log += "\n## Overall Results Summary\n\n"
+    log += f"Total sequences analyzed: {len(results)}\n"
+    log += f"Detailed results saved to: {output_file}\n"
+    log += f"Summary results saved to: {summary_file}\n\n"
+
+    if cell_line_info:
+        log += "### Mutation Distribution by Cell Line\n\n"
+        for cell_line, mut_counts in mutation_counts.items():
+            total = sum(mut_counts.values())
+            if total == 0:
+                continue
+
+            log += f"#### {cell_line}\n"
+            for mut_type, count in sorted(mut_counts.items(), key=lambda x: x[1], reverse=True):
+                percentage = (count / total) * 100
+                log += f"- {categories[mut_type]}: {count} ({percentage:.1f}%)\n"
+            log += "\n"
+
+    return log
+
+
+def analyze_crispr_genome_editing(original_sequence, edited_sequence, guide_rna, repair_template=None):
+    """Analyzes CRISPR-Cas9 genome editing results by comparing original and edited sequences.
+
+    Parameters
+    ----------
+    original_sequence : str
+        The original DNA sequence before CRISPR-Cas9 editing
+    edited_sequence : str
+        The DNA sequence after CRISPR-Cas9 editing
+    guide_rna : str
+        The CRISPR guide RNA (crRNA) sequence used for targeting
+    repair_template : str, optional
+        The homology-directed repair template sequence, if used
+
+    Returns
+    -------
+    str
+        A research log summarizing the CRISPR-Cas9 editing analysis, including identified
+        mutations and characterization of the edited loci
+
+    """
+    import datetime
+
+    from Bio import pairwise2
+    from Bio.Seq import Seq
+
+    log = []
+    log.append(f"CRISPR-Cas9 Genome Editing Analysis - {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append("=" * 70)
+
+    # Step 1: Find the target site in the original sequence
+    log.append("\n1. Identifying target site in original sequence")
+    target_site = original_sequence.find(guide_rna)
+    if target_site == -1:
+        # Try with the reverse complement
+        guide_rna_seq = Seq(guide_rna)
+        rev_comp_guide = str(guide_rna_seq.reverse_complement())
+        target_site = original_sequence.find(rev_comp_guide)
+        if target_site != -1:
+            log.append(f"   - Target site found at position {target_site} (using reverse complement of guide RNA)")
+            guide_rna = rev_comp_guide
+        else:
+            log.append("   - Warning: Guide RNA sequence not found in original sequence")
+            target_site = None
+    else:
+        log.append(f"   - Target site found at position {target_site}")
+
+    # Step 2: Align sequences to identify mutations
+    log.append("\n2. Aligning original and edited sequences to identify mutations")
+    alignments = pairwise2.align.globalms(original_sequence, edited_sequence, 2, -1, -2, -0.5)
+    best_alignment = alignments[0]
+
+    # Extract aligned sequences
+    aligned_orig = best_alignment[0]
+    aligned_edit = best_alignment[1]
+
+    # Find mutations
+    mutations = []
+    indels = []
+
+    for i in range(len(aligned_orig)):
+        if aligned_orig[i] != aligned_edit[i]:
+            orig_base = aligned_orig[i]
+            edit_base = aligned_edit[i]
+
+            # Skip gaps in counting the actual position
+            actual_pos = len(aligned_orig[:i].replace("-", ""))
+
+            if orig_base == "-":  # Insertion
+                indels.append(f"Insertion of {edit_base} at position {actual_pos}")
+            elif edit_base == "-":  # Deletion
+                indels.append(f"Deletion of {orig_base} at position {actual_pos}")
+            else:  # Substitution
+                mutations.append(f"{orig_base}→{edit_base} at position {actual_pos}")
+
+    # Log mutations
+    if mutations:
+        log.append("   - Substitutions detected:")
+        for mutation in mutations:
+            log.append(f"     * {mutation}")
+    else:
+        log.append("   - No substitutions detected")
+
+    if indels:
+        log.append("   - Insertions/Deletions detected:")
+        for indel in indels:
+            log.append(f"     * {indel}")
+    else:
+        log.append("   - No insertions or deletions detected")
+
+    # Step 3: Check if editing occurred near the target site
+    if target_site is not None:
+        log.append("\n3. Analyzing mutations relative to target site")
+        target_end = target_site + len(guide_rna)
+        target_region = range(target_site - 3, target_end + 3)  # Include some buffer
+
+        on_target_edits = [m for m in mutations + indels if any(str(pos) in m for pos in target_region)]
+
+        if on_target_edits:
+            log.append("   - On-target edits detected near guide RNA binding site:")
+            for edit in on_target_edits:
+                log.append(f"     * {edit}")
+        else:
+            log.append("   - No edits detected near guide RNA binding site")
+
+    # Step 4: Check for homology-directed repair if template was provided
+    if repair_template:
+        log.append("\n4. Checking for homology-directed repair template incorporation")
+        # Look for unique sequence markers from the repair template
+        template_len = len(repair_template)
+        marker_size = min(10, template_len // 3)
+        marker = repair_template[template_len // 2 - marker_size // 2 : template_len // 2 + marker_size // 2]
+
+        if marker in edited_sequence and marker not in original_sequence:
+            log.append(f"   - Repair template marker '{marker}' found in edited sequence")
+            log.append("   - Homology-directed repair likely successful")
+        else:
+            log.append("   - No clear evidence of repair template incorporation")
+            log.append("   - Editing likely resulted from non-homologous end joining (NHEJ)")
+
+    # Step 5: Overall assessment
+    log.append("\n5. Overall assessment")
+    if mutations or indels:
+        log.append("   - CRISPR-Cas9 editing appears successful")
+        if target_site is not None and any(
+            str(pos) in "".join(mutations + indels) for pos in range(target_site, target_site + len(guide_rna))
+        ):
+            log.append("   - Edits occurred at the intended target site")
+        else:
+            log.append("   - Edits may have occurred outside the intended target site")
+    else:
+        log.append("   - No significant editing detected, CRISPR-Cas9 may not have been effective")
+
+    return "\n".join(log)
+
+
+def simulate_demographic_history(
+    num_samples=10,
+    sequence_length=100000,
+    recombination_rate=1e-8,
+    mutation_rate=1e-8,
+    demographic_model="constant",
+    demographic_params=None,
+    coalescent_model="kingman",
+    beta_coalescent_param=None,
+    random_seed=None,
+    output_file="simulated_sequences.vcf",
+):
+    """Simulate DNA sequences with specified demographic and coalescent histories using msprime.
+
+    Parameters
+    ----------
+    num_samples : int
+        Number of sample sequences to simulate
+    sequence_length : int
+        Length of the simulated sequence in base pairs
+    recombination_rate : float
+        Per-base recombination rate
+    mutation_rate : float
+        Per-base mutation rate
+    demographic_model : str
+        Type of demographic model to simulate. Options:
+        - "constant": Constant population size
+        - "bottleneck": Population bottleneck
+        - "expansion": Population expansion
+        - "contraction": Population contraction
+        - "sawtooth": Sawtooth pattern of population size changes
+    demographic_params : dict
+        Parameters specific to the chosen demographic model. Supported formats::
+
+            - For "constant": {"N": population size}
+            - For "bottleneck": {
+                "N_initial": initial pop size,
+                "N_bottleneck": bottleneck pop size,
+                "T_bottleneck": time of bottleneck (generations ago),
+                "T_recovery": time of recovery (generations ago)
+            }
+            - For "expansion": {"N_initial": initial pop size, "N_final": final pop size, "T_expansion": time of expansion (generations ago)}
+            - For "contraction": {"N_initial": initial pop size, "N_final": final pop size, "T_contraction": time of contraction (generations ago)}
+            - For "sawtooth": {"N_values": list of population sizes, "times": list of times for changes}
+    coalescent_model : str
+        Type of coalescent model to use. Options:
+        - "kingman": Standard Kingman coalescent
+        - "beta": Beta-coalescent model
+    beta_coalescent_param : float
+        Parameter for beta-coalescent model (required if coalescent_model="beta")
+    random_seed : int
+        Seed for random number generator (for reproducibility)
+    output_file : str
+        Filename to save the simulated sequences (VCF format)
+
+    Returns
+    -------
+    str
+        Research log summarizing the simulation parameters and results
+
+    """
+    import time
+
+    import msprime
+
+    start_time = time.time()
+    log = []
+    log.append("Demographic History Simulation using msprime")
+    log.append("=============================================")
+    log.append("Parameters:")
+    log.append(f"  - Number of samples: {num_samples}")
+    log.append(f"  - Sequence length: {sequence_length} bp")
+    log.append(f"  - Recombination rate: {recombination_rate}")
+    log.append(f"  - Mutation rate: {mutation_rate}")
+    log.append(f"  - Demographic model: {demographic_model}")
+    log.append(f"  - Coalescent model: {coalescent_model}")
+
+    # Set up demographic model
+    if demographic_params is None:
+        demographic_params = {"N": 10000}  # Default to constant population of 10000
+
+    demography = msprime.Demography()
+    demography.add_population(name="pop0", initial_size=1000)  # Default initial population
+
+    if demographic_model == "constant":
+        N = demographic_params.get("N", 10000)
+        demography.add_population(name="pop0", initial_size=N)
+        log.append(f"  - Constant population size: N = {N}")
+
+    elif demographic_model == "bottleneck":
+        N_initial = demographic_params.get("N_initial", 10000)
+        N_bottleneck = demographic_params.get("N_bottleneck", 1000)
+        T_bottleneck = demographic_params.get("T_bottleneck", 1000)
+        T_recovery = demographic_params.get("T_recovery", 500)
+
+        demography = msprime.Demography()
+        demography.add_population(name="pop0", initial_size=N_initial)
+        demography.add_population_parameters_change(time=T_recovery, initial_size=N_bottleneck)
+        demography.add_population_parameters_change(time=T_bottleneck, initial_size=N_initial)
+
+        log.append("  - Bottleneck model:")
+        log.append(f"    * Initial population size: {N_initial}")
+        log.append(f"    * Bottleneck population size: {N_bottleneck}")
+        log.append(f"    * Bottleneck time (generations ago): {T_bottleneck}")
+        log.append(f"    * Recovery time (generations ago): {T_recovery}")
+
+    elif demographic_model == "expansion":
+        N_initial = demographic_params.get("N_initial", 1000)
+        N_final = demographic_params.get("N_final", 10000)
+        T_expansion = demographic_params.get("T_expansion", 1000)
+
+        demography = msprime.Demography()
+        demography.add_population(name="pop0", initial_size=N_final)
+        demography.add_population_parameters_change(time=T_expansion, initial_size=N_initial)
+
+        log.append("  - Expansion model:")
+        log.append(f"    * Initial population size: {N_initial}")
+        log.append(f"    * Final population size: {N_final}")
+        log.append(f"    * Expansion time (generations ago): {T_expansion}")
+
+    elif demographic_model == "contraction":
+        N_initial = demographic_params.get("N_initial", 10000)
+        N_final = demographic_params.get("N_final", 1000)
+        T_contraction = demographic_params.get("T_contraction", 1000)
+
+        demography = msprime.Demography()
+        demography.add_population(name="pop0", initial_size=N_final)
+        demography.add_population_parameters_change(time=T_contraction, initial_size=N_initial)
+
+        log.append("  - Contraction model:")
+        log.append(f"    * Initial population size: {N_initial}")
+        log.append(f"    * Final population size: {N_final}")
+        log.append(f"    * Contraction time (generations ago): {T_contraction}")
+
+    elif demographic_model == "sawtooth":
+        N_values = demographic_params.get("N_values", [10000, 5000, 15000, 7500])
+        times = demographic_params.get("times", [500, 1000, 1500])
+
+        if len(N_values) != len(times) + 1:
+            raise ValueError("For sawtooth model, N_values should have one more element than times")
+
+        demography = msprime.Demography()
+        demography.add_population(name="pop0", initial_size=N_values[0])
+
+        for i, time in enumerate(times):
+            demography.add_population_parameters_change(time=time, initial_size=N_values[i + 1])
+
+        log.append("  - Sawtooth model:")
+        log.append(f"    * Population sizes: {N_values}")
+        log.append(f"    * Change times (generations ago): {times}")
+
+    else:
+        raise ValueError(f"Unknown demographic model: {demographic_model}")
+
+    # Set up coalescent model
+    model = None
+    if coalescent_model == "kingman":
+        model = msprime.StandardCoalescent()
+        log.append("  - Using standard Kingman coalescent")
+    elif coalescent_model == "beta":
+        if beta_coalescent_param is None:
+            beta_coalescent_param = 1.5
+        model = msprime.BetaCoalescent(alpha=beta_coalescent_param)
+        log.append(f"  - Using Beta-coalescent with alpha = {beta_coalescent_param}")
+    else:
+        raise ValueError(f"Unknown coalescent model: {coalescent_model}")
+
+    # Run simulation
+    log.append("\nRunning simulation...")
+
+    ts = msprime.sim_ancestry(
+        samples=num_samples,
+        recombination_rate=recombination_rate,
+        sequence_length=sequence_length,
+        demography=demography,
+        model=model,
+        random_seed=random_seed,
+    )
+
+    # Add mutations
+    mts = msprime.sim_mutations(ts, rate=mutation_rate, random_seed=random_seed)
+
+    # Save to VCF
+    with open(output_file, "w") as vcf_file:
+        mts.write_vcf(vcf_file)
+
+    # Calculate some basic statistics
+    diversity = mts.diversity()
+    num_sites = mts.num_sites
+    num_trees = mts.num_trees
+
+    # Log results
+    end_time = time.time()
+    runtime = end_time - start_time
+
+    log.append(f"Simulation completed in {runtime:.2f} seconds")
+    log.append("\nResults:")
+    log.append(f"  - Number of segregating sites: {num_sites}")
+    log.append(f"  - Number of trees in ARG: {num_trees}")
+    log.append(f"  - Nucleotide diversity (π): {diversity:.6f}")
+    log.append(f"  - Output saved to: {os.path.abspath(output_file)}")
+
+    return "\n".join(log)
+
+
+def identify_transcription_factor_binding_sites(sequence, tf_name, threshold=0.8, output_file=None):
+    """Identifies binding sites for a specific transcription factor in a genomic sequence.
+
+    Parameters
+    ----------
+    sequence : str
+        The genomic DNA sequence to analyze
+    tf_name : str
+        Name of the transcription factor to search for (e.g., 'Hsf1', 'GATA1')
+    threshold : float, optional
+        Minimum score threshold for reporting binding sites (0.0-1.0, default: 0.8)
+    output_file : str, optional
+        Path to save the results (default: None, results only in log)
+
+    Returns
+    -------
+    str
+        Research log detailing the binding site identification process and results
+
+    """
+    import datetime
+    import io
+
+    import requests
+    from Bio import motifs
+    from Bio.Seq import Seq
+
+    log = f"# Transcription Factor Binding Site Analysis: {tf_name}\n"
+    log += f"Date: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+
+    # Step 1: Get the PWM for the transcription factor from JASPAR database
+    log += "## Step 1: Retrieving transcription factor PWM\n"
+
+    try:
+        # Search for the TF in JASPAR database
+        jaspar_url = f"https://jaspar.genereg.net/api/v1/matrix/?name={tf_name}"
+        response = requests.get(jaspar_url)
+        tf_data = response.json()
+
+        if not tf_data["results"] or len(tf_data["results"]) == 0:
+            log += f"No PWM found for {tf_name} in JASPAR database.\n"
+            return log
+
+        # Get the first match's ID
+        matrix_id = tf_data["results"][0]["matrix_id"]
+        log += f"Found PWM with ID: {matrix_id}\n"
+
+        # Retrieve the PWM
+        pwm_url = f"https://jaspar.genereg.net/api/v1/matrix/{matrix_id}.pfm"
+        pwm_response = requests.get(pwm_url)
+
+        # Parse the PWM
+        handle = io.StringIO(pwm_response.text)
+        motif = motifs.read(handle, "jaspar")
+        log += f"Successfully retrieved PWM for {tf_name}\n"
+
+        # Calculate position-specific scoring matrix (PSSM)
+        pssm = motif.pssm
+
+        # Step 2: Scan the sequence for binding sites
+        log += "\n## Step 2: Scanning sequence for binding sites\n"
+        log += f"Sequence length: {len(sequence)} bp\n"
+        log += f"Using score threshold: {threshold}\n\n"
+
+        # Find binding sites
+        binding_sites = []
+        max_score = pssm.max
+        min_score = pssm.min
+
+        for position, score in pssm.search(Seq(sequence), threshold=threshold):
+            relative_score = (score - min_score) / (max_score - min_score)
+            if position >= 0:
+                strand = "+"
+                site_seq = sequence[position : position + len(pssm)]
+            else:
+                strand = "-"
+                site_seq = sequence[len(sequence) + position - len(pssm) : len(sequence) + position]
+
+            binding_sites.append(
+                {
+                    "position": abs(position),
+                    "strand": strand,
+                    "score": score,
+                    "relative_score": relative_score,
+                    "sequence": site_seq,
+                }
+            )
+
+        # Step 3: Summarize results
+        log += f"## Step 3: Results - Found {len(binding_sites)} potential binding sites\n\n"
+
+        if binding_sites:
+            # Sort by position
+            binding_sites.sort(key=lambda x: x["position"])
+
+            # Create a table of results
+            log += "| Position | Strand | Sequence | Score | Relative Score |\n"
+            log += "|----------|--------|----------|-------|---------------|\n"
+
+            for site in binding_sites:
+                log += f"| {site['position']} | {site['strand']} | {site['sequence']} | {site['score']:.2f} | {site['relative_score']:.2f} |\n"
+        else:
+            log += "No binding sites found meeting the threshold criteria.\n"
+
+        # Save results to file if specified
+        if output_file:
+            with open(output_file, "w") as f:
+                f.write(f"# {tf_name} binding sites in sequence\n")
+                f.write("Position\tStrand\tSequence\tScore\tRelative Score\n")
+
+                for site in binding_sites:
+                    f.write(
+                        f"{site['position']}\t{site['strand']}\t{site['sequence']}\t{site['score']:.2f}\t{site['relative_score']:.2f}\n"
+                    )
+
+            log += f"\nResults saved to file: {output_file}\n"
+
+    except Exception as e:
+        log += f"\n## Error occurred during analysis: {str(e)}\n"
+
+    log += "\n## Analysis complete\n"
+    return log
+
+
+def fit_genomic_prediction_model(
+    genotypes,
+    phenotypes,
+    fixed_effects=None,
+    model_type="additive",
+    output_file="genomic_prediction_results.csv",
+):
+    """Fit a linear mixed model for genomic prediction using genotype and phenotype data.
+
+    Parameters
+    ----------
+    genotypes : numpy.ndarray
+        Matrix of genotype data, with individuals in rows and markers in columns.
+        Values are typically coded as 0, 1, 2 for additive models or with specific
+        encoding for dominance effects.
+    phenotypes : numpy.ndarray
+        Vector or matrix of phenotype data, with individuals in rows and traits in columns.
+    fixed_effects : numpy.ndarray, optional
+        Matrix of fixed effects (e.g., environment, management), with individuals in rows
+        and effects in columns.
+    model_type : str, optional
+        Type of genetic model to fit: "additive" or "additive_dominance".
+    output_file : str, optional
+        File name to save the results.
+
+    Returns
+    -------
+    str
+        Research log summarizing the genomic prediction analysis, including model parameters,
+        variance components, breeding values, and prediction accuracy metrics.
+
+    """
+    import pandas as pd
+    from scipy import linalg
+
+    # Initialize research log
+    log = "# Multi-trait Genomic Prediction Analysis\n\n"
+    log += f"Model type: {model_type}\n"
+
+    # Basic validation
+    n_individuals, n_markers = genotypes.shape
+    n_pheno, n_traits = (phenotypes.shape[0], 1) if phenotypes.ndim == 1 else phenotypes.shape
+
+    if n_individuals != n_pheno:
+        raise ValueError(f"Number of individuals in genotypes ({n_individuals}) and phenotypes ({n_pheno}) don't match")
+
+    log += f"Number of individuals: {n_individuals}\n"
+    log += f"Number of markers: {n_markers}\n"
+    log += f"Number of traits: {n_traits}\n\n"
+
+    # Ensure phenotypes is 2D
+    if phenotypes.ndim == 1:
+        phenotypes = phenotypes.reshape(-1, 1)
+
+    # Center genotypes (common preprocessing step)
+    genotypes_centered = genotypes - np.mean(genotypes, axis=0)
+
+    # Create genomic relationship matrix (G)
+    if model_type == "additive":
+        # Additive genomic relationship matrix
+        G = np.dot(genotypes_centered, genotypes_centered.T) / n_markers
+        log += "Constructed additive genomic relationship matrix (G)\n\n"
+    elif model_type == "additive_dominance":
+        # For additive-dominance model, we need both A (additive) and D (dominance) matrices
+        # Assuming genotypes are coded as {0,1,2} for {aa,Aa,AA}
+        # Create dominance matrix - simple implementation assuming standard coding
+        dom_genotypes = np.zeros_like(genotypes)
+        # Code heterozygotes (1) as 1, homozygotes (0,2) as 0 for dominance effects
+        dom_genotypes[genotypes == 1] = 1
+        dom_genotypes_centered = dom_genotypes - np.mean(dom_genotypes, axis=0)
+
+        # Additive and dominance matrices
+        G_a = np.dot(genotypes_centered, genotypes_centered.T) / n_markers
+        G_d = np.dot(dom_genotypes_centered, dom_genotypes_centered.T) / n_markers
+        log += "Constructed additive (G_a) and dominance (G_d) genomic relationship matrices\n\n"
+    else:
+        raise ValueError(f"Unknown model type: {model_type}")
+
+    # Initialize results storage
+    trait_results = []
+
+    # Fit model for each trait
+    for trait_idx in range(n_traits):
+        trait_phenotypes = phenotypes[:, trait_idx]
+        log += f"## Trait {trait_idx + 1} Analysis\n\n"
+
+        # Handle fixed effects if provided
+        if fixed_effects is not None:
+            # Simple fixed effects adjustment - more complex models would use proper mixed model fitting
+            X = fixed_effects
+            # Fit fixed effects model
+            beta = np.linalg.lstsq(X, trait_phenotypes, rcond=None)[0]
+            # Adjust phenotypes for fixed effects
+            y_adj = trait_phenotypes - X @ beta
+            log += f"Applied adjustment for {X.shape[1]} fixed effects\n"
+        else:
+            y_adj = trait_phenotypes
+            log += "No fixed effects provided\n"
+
+        # Fit mixed model
+        if model_type == "additive":
+            # Simplified REML estimation for variance components
+            # In practice, specialized libraries like pyGWAS, GCTA or R's ASReml would be used
+
+            # Initial variance component estimates
+            var_g_init = np.var(y_adj) * 0.5  # genetic variance
+            var_e_init = np.var(y_adj) * 0.5  # residual variance
+
+            # Simple EM-like algorithm for variance component estimation
+            # (In practice, use dedicated software for proper REML)
+            for _ in range(5):  # Few iterations for demonstration
+                # Construct mixed model equations
+                V = var_g_init * G + var_e_init * np.eye(n_individuals)
+                V_inv = linalg.inv(V)
+
+                # Update variance components
+                P = V_inv - V_inv @ np.ones((n_individuals, 1)) @ np.ones((1, n_individuals)) @ V_inv / (
+                    np.ones((1, n_individuals)) @ V_inv @ np.ones((n_individuals, 1))
+                )
+                var_g_new = (y_adj.T @ P @ G @ P @ y_adj) / np.trace(P @ G)
+                var_e_new = (y_adj.T @ P @ P @ y_adj) / np.trace(P)
+
+                # Update estimates
+                var_g_init = max(0.01, var_g_new)
+                var_e_init = max(0.01, var_e_new)
+
+            # Final variance components
+            var_g = var_g_init
+            var_e = var_e_init
+
+            # Calculate heritability
+            heritability = var_g / (var_g + var_e)
+
+            # BLUP solutions for breeding values
+            V = var_g * G + var_e * np.eye(n_individuals)
+            V_inv = linalg.inv(V)
+            breeding_values = var_g * G @ V_inv @ y_adj
+
+            # Predicted phenotypes
+            predicted_phenotypes = breeding_values
+
+            # Calculate accuracy
+            accuracy = np.corrcoef(trait_phenotypes, predicted_phenotypes)[0, 1]
+
+            # Log results
+            log += f"Estimated additive genetic variance: {var_g:.4f}\n"
+            log += f"Estimated residual variance: {var_e:.4f}\n"
+            log += f"Estimated heritability: {heritability:.4f}\n"
+            log += f"Prediction accuracy (correlation): {accuracy:.4f}\n\n"
+
+            # Store results
+            trait_result = {
+                "trait": trait_idx + 1,
+                "var_g": var_g,
+                "var_e": var_e,
+                "heritability": heritability,
+                "accuracy": accuracy,
+                "breeding_values": breeding_values,
+                "predicted_phenotypes": predicted_phenotypes,
+            }
+            trait_results.append(trait_result)
+
+        elif model_type == "additive_dominance":
+            # Similar approach but with both additive and dominance effects
+            # Initial variance component estimates
+            var_a_init = np.var(y_adj) * 0.4  # additive variance
+            var_d_init = np.var(y_adj) * 0.1  # dominance variance
+            var_e_init = np.var(y_adj) * 0.5  # residual variance
+
+            # Simple estimation iterations
+            for _ in range(5):  # Few iterations for demonstration
+                # Construct mixed model equations
+                V = var_a_init * G_a + var_d_init * G_d + var_e_init * np.eye(n_individuals)
+                V_inv = linalg.inv(V)
+
+                # Update variance components (simplified)
+                P = V_inv - V_inv @ np.ones((n_individuals, 1)) @ np.ones((1, n_individuals)) @ V_inv / (
+                    np.ones((1, n_individuals)) @ V_inv @ np.ones((n_individuals, 1))
+                )
+                var_a_new = (y_adj.T @ P @ G_a @ P @ y_adj) / np.trace(P @ G_a)
+                var_d_new = (y_adj.T @ P @ G_d @ P @ y_adj) / np.trace(P @ G_d)
+                var_e_new = (y_adj.T @ P @ P @ y_adj) / np.trace(P)
+
+                # Update estimates
+                var_a_init = max(0.01, var_a_new)
+                var_d_init = max(0.01, var_d_new)
+                var_e_init = max(0.01, var_e_new)
+
+            # Final variance components
+            var_a = var_a_init
+            var_d = var_d_init
+            var_e = var_e_init
+
+            # Calculate heritabilities
+            narrow_heritability = var_a / (var_a + var_d + var_e)
+            broad_heritability = (var_a + var_d) / (var_a + var_d + var_e)
+
+            # BLUP solutions for breeding values and dominance deviations
+            V = var_a * G_a + var_d * G_d + var_e * np.eye(n_individuals)
+            V_inv = linalg.inv(V)
+            breeding_values = var_a * G_a @ V_inv @ y_adj
+            dominance_deviations = var_d * G_d @ V_inv @ y_adj
+
+            # Predicted phenotypes
+            predicted_phenotypes = breeding_values + dominance_deviations
+
+            # Calculate accuracy
+            accuracy = np.corrcoef(trait_phenotypes, predicted_phenotypes)[0, 1]
+
+            # Log results
+            log += f"Estimated additive genetic variance: {var_a:.4f}\n"
+            log += f"Estimated dominance genetic variance: {var_d:.4f}\n"
+            log += f"Estimated residual variance: {var_e:.4f}\n"
+            log += f"Estimated narrow-sense heritability: {narrow_heritability:.4f}\n"
+            log += f"Estimated broad-sense heritability: {broad_heritability:.4f}\n"
+            log += f"Prediction accuracy (correlation): {accuracy:.4f}\n\n"
+
+            # Store results
+            trait_result = {
+                "trait": trait_idx + 1,
+                "var_a": var_a,
+                "var_d": var_d,
+                "var_e": var_e,
+                "narrow_heritability": narrow_heritability,
+                "broad_heritability": broad_heritability,
+                "accuracy": accuracy,
+                "breeding_values": breeding_values,
+                "dominance_deviations": dominance_deviations,
+                "predicted_phenotypes": predicted_phenotypes,
+            }
+            trait_results.append(trait_result)
+
+    # Save results to file
+    results_df = pd.DataFrame()
+
+    for i, trait_result in enumerate(trait_results):
+        # Create individual-level results
+        ind_data = {
+            "individual": np.arange(1, n_individuals + 1),
+            f"trait_{i + 1}_observed": phenotypes[:, i],
+            f"trait_{i + 1}_predicted": trait_result["predicted_phenotypes"],
+            f"trait_{i + 1}_breeding_value": trait_result["breeding_values"],
+        }
+
+        if model_type == "additive_dominance":
+            ind_data[f"trait_{i + 1}_dominance_deviation"] = trait_result["dominance_deviations"]
+
+        # Create or append to dataframe
+        if i == 0:
+            results_df = pd.DataFrame(ind_data)
+        else:
+            for key, value in ind_data.items():
+                if key != "individual":  # Skip duplicating individual column
+                    results_df[key] = value
+
+    # Save to CSV
+    results_df.to_csv(output_file, index=False)
+    log += f"Results saved to {output_file}\n"
+
+    return log
+
+
+def perform_pcr_and_gel_electrophoresis(
+    genomic_dna,
+    forward_primer=None,
+    reverse_primer=None,
+    target_region=None,
+    annealing_temp=58,
+    extension_time=30,
+    cycles=35,
+    gel_percentage=2.0,
+    output_prefix="pcr_result",
+):
+    """Performs PCR amplification of a target transgene and visualizes results using agarose gel electrophoresis.
+
+    Parameters
+    ----------
+    genomic_dna : str
+        Path to file containing genomic DNA sequence in FASTA format or the sequence itself
+    forward_primer : str, optional
+        Forward primer sequence. If not provided, will be designed based on target_region
+    reverse_primer : str, optional
+        Reverse primer sequence. If not provided, will be designed based on target_region
+    target_region : tuple, optional
+        Tuple of (start, end) positions for the target region in the genomic DNA
+    annealing_temp : float, default=58
+        Annealing temperature for PCR in °C
+    extension_time : int, default=30
+        Extension time in seconds
+    cycles : int, default=35
+        Number of PCR cycles
+    gel_percentage : float, default=2.0
+        Percentage of agarose gel
+    output_prefix : str, default="pcr_result"
+        Prefix for output files
+
+    Returns
+    -------
+    str
+        Research log summarizing the PCR and gel electrophoresis procedures and results
+
+    """
+    import datetime
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from Bio import SeqIO
+    from Bio.Seq import Seq
+
+    log = f"PCR AMPLIFICATION AND GEL ELECTROPHORESIS LOG - {datetime.datetime.now().strftime('%Y-%m-%d %H:%M')}\n"
+    log += "=" * 80 + "\n\n"
+
+    # Step 1: Load the genomic DNA
+    log += "STEP 1: PREPARING GENOMIC DNA\n"
+    if os.path.isfile(genomic_dna):
+        try:
+            record = SeqIO.read(genomic_dna, "fasta")
+            dna_sequence = str(record.seq)
+            log += f"- Loaded genomic DNA from file: {genomic_dna}\n"
+            log += f"- Sequence length: {len(dna_sequence)} bp\n"
+        except Exception as e:
+            log += f"- Error loading DNA file: {str(e)}\n"
+            return log
+    else:
+        dna_sequence = genomic_dna
+        log += "- Using provided DNA sequence\n"
+        log += f"- Sequence length: {len(dna_sequence)} bp\n"
+
+    log += "\n"
+
+    # Step 2: Design or validate primers
+    log += "STEP 2: PCR PRIMER PREPARATION\n"
+
+    if forward_primer is None or reverse_primer is None:
+        if target_region is None:
+            log += "- Error: Either primers or target region must be provided\n"
+            return log
+
+        # Simple primer design based on target region
+        start, end = target_region
+
+        if forward_primer is None:
+            # Take 20bp from the start of the target region for forward primer
+            forward_primer = dna_sequence[start : start + 20]
+            log += "- Designed forward primer based on target region\n"
+
+        if reverse_primer is None:
+            # Take 20bp from the end of the target region for reverse primer (reverse complement)
+            reverse_seq = Seq(dna_sequence[end - 20 : end])
+            reverse_primer = str(reverse_seq.reverse_complement())
+            log += "- Designed reverse primer based on target region\n"
+
+    log += f"- Forward primer: 5'-{forward_primer}-3' ({len(forward_primer)} bp)\n"
+    log += f"- Reverse primer: 5'-{reverse_primer}-3' ({len(reverse_primer)} bp)\n"
+
+    # Step 3: PCR Setup and Amplification
+    log += "\nSTEP 3: PCR AMPLIFICATION\n"
+    log += "- PCR reaction setup:\n"
+    log += "  * Template DNA: Genomic DNA\n"
+    log += f"  * Forward primer: 5'-{forward_primer}-3'\n"
+    log += f"  * Reverse primer: 5'-{reverse_primer}-3'\n"
+    log += f"  * Annealing temperature: {annealing_temp}°C\n"
+    log += f"  * Extension time: {extension_time} seconds\n"
+    log += f"  * Number of cycles: {cycles}\n"
+
+    # Simulate PCR by finding binding sites and determining amplicon size
+    amplicon_size = None
+    amplicon_sequence = None
+
+    # Find forward primer binding site
+    fwd_pos = dna_sequence.find(forward_primer)
+    if fwd_pos == -1:
+        log += "- Warning: Forward primer binding site not found in sequence\n"
+
+    # Find reverse primer binding site (need to search for reverse complement)
+    rev_primer_seq = Seq(reverse_primer)
+    rev_primer_rc = str(rev_primer_seq.reverse_complement())
+    rev_pos = dna_sequence.find(rev_primer_rc)
+    if rev_pos == -1:
+        log += "- Warning: Reverse primer binding site not found in sequence\n"
+
+    # If we found both binding sites, calculate amplicon size
+    if fwd_pos != -1 and rev_pos != -1:
+        if fwd_pos < rev_pos:
+            amplicon_size = rev_pos + len(reverse_primer) - fwd_pos
+            amplicon_sequence = dna_sequence[fwd_pos : rev_pos + len(reverse_primer)]
+            log += "- PCR amplification successful\n"
+            log += f"- Amplicon size: {amplicon_size} bp\n"
+        else:
+            log += "- Error: Primer binding sites are in incorrect orientation\n"
+    # Simulate based on target region if provided
+    elif target_region is not None:
+        start, end = target_region
+        amplicon_size = end - start + len(forward_primer) + len(reverse_primer)
+        log += "- PCR amplification simulated based on target region\n"
+        log += f"- Expected amplicon size: {amplicon_size} bp\n"
+    else:
+        log += "- PCR amplification failed: could not determine amplicon size\n"
+        return log
+
+    # Step 4: Gel Electrophoresis
+    log += "\nSTEP 4: AGAROSE GEL ELECTROPHORESIS\n"
+    log += f"- Prepared {gel_percentage}% agarose gel\n"
+    log += "- Loaded PCR product alongside DNA ladder\n"
+    log += "- Ran electrophoresis at 100V for 45 minutes\n"
+
+    # Create a simulated gel image
+    fig, ax = plt.subplots(figsize=(6, 8))
+
+    # Draw gel lanes
+    ax.add_patch(plt.Rectangle((0, 0), 6, 10, color="lightgray", alpha=0.5))
+
+    # DNA Ladder (100bp increments)
+    ladder_sizes = [100, 200, 300, 500, 700, 1000, 1500, 2000]
+    ladder_positions = [10 - (np.log(size) / np.log(2000) * 8) for size in ladder_sizes]
+
+    # Plot ladder
+    for pos, size in zip(ladder_positions, ladder_sizes, strict=False):
+        ax.add_patch(plt.Rectangle((0.5, pos - 0.1), 1, 0.2, color="black", alpha=0.8))
+        ax.text(0.2, pos, f"{size}bp", fontsize=8, ha="right", va="center")
+
+    # Plot sample band
+    if amplicon_size:
+        sample_position = 10 - (np.log(amplicon_size) / np.log(2000) * 8)
+        ax.add_patch(plt.Rectangle((3.5, sample_position - 0.15), 1, 0.3, color="black", alpha=0.8))
+        ax.text(
+            4.5,
+            sample_position,
+            f"{amplicon_size}bp",
+            fontsize=8,
+            ha="left",
+            va="center",
+        )
+
+    # Set up the plot
+    ax.set_xlim(0, 6)
+    ax.set_ylim(0, 10)
+    ax.set_xticks([0.5, 3.5])
+    ax.set_xticklabels(["Ladder", "Sample"])
+    ax.set_yticks([])
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+    ax.set_title(f"{gel_percentage}% Agarose Gel")
+
+    # Save the gel image
+    gel_image_path = f"{output_prefix}_gel.png"
+    plt.savefig(gel_image_path, dpi=300, bbox_inches="tight")
+    plt.close()
+
+    log += f"- Gel image saved as: {gel_image_path}\n"
+
+    # Results interpretation
+    log += "\nRESULTS INTERPRETATION:\n"
+    if amplicon_size:
+        log += f"- Detected band at approximately {amplicon_size} bp\n"
+
+        # Save amplicon sequence if available
+        if amplicon_sequence:
+            seq_file = f"{output_prefix}_amplicon.fasta"
+            with open(seq_file, "w") as f:
+                f.write(f">PCR_Amplicon_{amplicon_size}bp\n")
+                f.write(amplicon_sequence)
+            log += f"- Amplicon sequence saved as: {seq_file}\n"
+    else:
+        log += "- No bands detected\n"
+
+    return log
+
+
+def analyze_protein_phylogeny(
+    fasta_sequences,
+    output_dir="./",
+    alignment_method="clustalw",
+    tree_method="fasttree",
+):
+    """Perform phylogenetic analysis on a set of protein sequences.
+
+    This function takes protein sequences in FASTA format, performs multiple sequence alignment,
+    constructs a phylogenetic tree, and visualizes the evolutionary relationships.
+
+    Parameters
+    ----------
+    fasta_sequences : str
+        Path to a FASTA file containing protein sequences or a string with FASTA-formatted sequences
+    output_dir : str, optional
+        Directory to save output files (default: current directory)
+    alignment_method : str, optional
+        Method for sequence alignment: "clustalw", "muscle", or "pre-aligned" (default: "clustalw")
+    tree_method : str, optional
+        Method for tree construction: "iqtree" (default: "iqtree")
+
+    Returns
+    -------
+    str
+        Research log summarizing the phylogenetic analysis process
+
+    """
+    import datetime
+    import subprocess
+    import tempfile
+
+    from Bio import AlignIO, Phylo, SeqIO
+    from Bio.Align.Applications import ClustalwCommandline, MuscleCommandline
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Initialize log
+    log = []
+    log.append(f"Phylogenetic Analysis - {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append("=" * 50)
+
+    # Check if input is a file path or string content
+    if os.path.isfile(fasta_sequences):
+        input_file = fasta_sequences
+        log.append(f"Using sequences from file: {input_file}")
+    else:
+        # Create temporary file with the string content
+        temp_fasta = tempfile.NamedTemporaryFile(delete=False, suffix=".fasta", dir=output_dir)
+        temp_fasta.write(fasta_sequences.encode())
+        temp_fasta.close()
+        input_file = temp_fasta.name
+        log.append(f"Created temporary FASTA file from provided sequences: {input_file}")
+
+    # Count sequences
+    try:
+        sequences = list(SeqIO.parse(input_file, "fasta"))
+        log.append(f"Loaded {len(sequences)} protein sequences")
+    except Exception as e:
+        log.append(f"Warning: Could not parse sequences as FASTA: {str(e)}")
+        # This might be pre-aligned data already
+        sequences = []
+
+    # Create filenames for outputs
+    base_name = os.path.splitext(os.path.basename(input_file))[0]
+    alignment_file = os.path.join(output_dir, f"{base_name}_aligned.aln")
+    tree_file = os.path.join(output_dir, f"{base_name}_tree.nwk")
+    tree_image = os.path.join(output_dir, f"{base_name}_phylogeny.png")
+
+    # Perform multiple sequence alignment
+    log.append("\nStep 1: Multiple Sequence Alignment")
+
+    # Special case for pre-aligned input
+    if alignment_method.lower() == "pre-aligned":
+        log.append("Using pre-aligned sequences")
+        try:
+            # If the input is already an alignment file, copy it to the alignment_file path
+            with open(input_file) as src, open(alignment_file, "w") as dst:
+                dst.write(src.read())
+            log.append(f"Copied pre-aligned file to: {alignment_file}")
+        except Exception as e:
+            log.append(f"Error processing pre-aligned sequences: {str(e)}")
+            return "\n".join(log)
+    elif alignment_method.lower() == "clustalw":
+        log.append("Using Clustal Omega for alignment")
+        try:
+            clustalw_cline = ClustalwCommandline("clustalw", infile=input_file, outfile=alignment_file)
+            stdout, stderr = clustalw_cline()
+            log.append("Alignment completed successfully")
+        except Exception as e:
+            log.append(f"Error during alignment: {str(e)}")
+            # Try alternative approach using MUSCLE if ClustalW fails
+            alignment_method = "muscle"
+
+    if alignment_method.lower() == "muscle":
+        log.append("Using MUSCLE for alignment")
+        try:
+            muscle_cline = MuscleCommandline("muscle", input=input_file, out=alignment_file)
+            stdout, stderr = muscle_cline()
+            log.append("Alignment completed successfully")
+        except Exception as e:
+            log.append(f"Error during MUSCLE alignment: {str(e)}")
+            log.append("Attempting to use Biopython's built-in pairwise2 alignment as fallback")
+
+            from Bio import pairwise2
+
+            # Create a simple progressive alignment
+            ref_seq = sequences[0]
+            alignments = []
+
+            for seq in sequences:
+                alignment = pairwise2.align.globalxx(ref_seq.seq, seq.seq)[0]
+                alignments.append(alignment)
+
+            # Write alignment to file in CLUSTAL format
+            with open(alignment_file, "w") as f:
+                f.write("CLUSTAL W (1.83) multiple sequence alignment\n\n")
+                for i, seq in enumerate(sequences):
+                    f.write(f"{seq.id.ljust(10)} {alignments[i][1]}\n")
+                # Add consensus line with asterisks
+                f.write(" " * 10 + " " * len(alignments[0][1]) + "\n")
+
+            log.append("Created basic alignment using Biopython's pairwise2")
+
+    # Verify alignment file exists
+    if not os.path.exists(alignment_file):
+        log.append(f"Error: Alignment file {alignment_file} does not exist")
+        return "\n".join(log)
+
+    # Build phylogenetic tree
+    log.append("\nStep 2: Phylogenetic Tree Construction")
+
+    if tree_method.lower() == "iqtree":
+        log.append("Using IQ-TREE for phylogenetic tree construction")
+        try:
+            cmd = f"iqtree -s {alignment_file} -m LG -bb 1000 -pre {os.path.join(output_dir, base_name)}"
+            subprocess.run(
+                cmd,
+                shell=True,
+                check=True,
+                capture_output=True,
+            )
+            # IQ-TREE creates files with .treefile extension
+            iqtree_file = os.path.join(output_dir, f"{base_name}.treefile")
+            if os.path.exists(iqtree_file):
+                # Rename to our standard name
+                os.rename(iqtree_file, tree_file)
+            log.append("Tree construction completed successfully")
+        except Exception as e:
+            log.append(f"Error during IQ-TREE execution: {str(e)}")
+            log.append("Falling back to neighbor-joining method")
+
+            try:
+                from Bio.Phylo.TreeConstruction import (
+                    DistanceCalculator,
+                    DistanceTreeConstructor,
+                )
+
+                # Try to read the alignment in different formats
+                alignment = None
+                for format in ["clustal", "fasta"]:
+                    try:
+                        alignment = AlignIO.read(alignment_file, format)
+                        break
+                    except Exception:
+                        continue
+
+                if alignment is None:
+                    log.append("Could not parse alignment file in any supported format")
+                    # Create a simple text-based tree file as a fallback
+                    with open(tree_file, "w") as f:
+                        f.write("(protein1:0.1,protein2:0.2,(protein3:0.3,protein4:0.4):0.5);")
+                    log.append("Created placeholder tree file")
+                else:
+                    # Calculate the distance matrix
+                    calculator = DistanceCalculator("identity")
+                    dm = calculator.get_distance(alignment)
+
+                    # Construct the tree
+                    constructor = DistanceTreeConstructor()
+                    tree = constructor.nj(dm)
+
+                    # Write the tree to file
+                    Phylo.write(tree, tree_file, "newick")
+                    log.append("Created tree using neighbor-joining method")
+            except Exception as e:
+                log.append(f"Error during fallback tree construction: {str(e)}")
+                # Create a simple text-based tree file as a final fallback
+                with open(tree_file, "w") as f:
+                    f.write("(protein1:0.1,protein2:0.2,(protein3:0.3,protein4:0.4):0.5);")
+                log.append("Created placeholder tree file as final fallback")
+    else:
+        log.append(f"Unsupported tree method: {tree_method}")
+        return "\n".join(log)
+
+    # Verify tree file exists
+    if not os.path.exists(tree_file):
+        log.append(f"Error: Tree file {tree_file} does not exist")
+        return "\n".join(log)
+
+    # Visualize the tree
+    log.append("\nStep 3: Phylogenetic Tree Visualization")
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")  # Use non-interactive backend
+        import matplotlib.pyplot as plt
+
+        tree = Phylo.read(tree_file, "newick")
+        fig = plt.figure(figsize=(10, len(sequences) * 0.3 if sequences else 5))
+        axes = fig.add_subplot(1, 1, 1)
+        Phylo.draw(tree, axes=axes, do_show=False)
+        plt.savefig(tree_image, dpi=300, bbox_inches="tight")
+        plt.close()
+        log.append(f"Tree visualization saved to: {tree_image}")
+    except Exception as e:
+        log.append(f"Error during tree visualization: {str(e)}")
+
+    # Summary
+    log.append("\nSummary:")
+    log.append(f"- Input sequences: {len(sequences) if sequences else 'pre-aligned data'}")
+    log.append(f"- Alignment file: {alignment_file}")
+    log.append(f"- Phylogenetic tree file: {tree_file}")
+    log.append(f"- Tree visualization: {tree_image}")
+
+    return "\n".join(log)

Biomni/biomni/tool/literature.py

@@ -0,0 +1,403 @@
+import os
+import re
+import time
+from io import BytesIO
+from urllib.parse import urljoin
+
+import PyPDF2
+import requests
+from bs4 import BeautifulSoup
+from googlesearch import search
+
+
+def fetch_supplementary_info_from_doi(doi: str, output_dir: str = "supplementary_info"):
+    """Fetches supplementary information for a paper given its DOI and returns a research log.
+
+    Args:
+        doi: The paper DOI.
+        output_dir: Directory to save supplementary files.
+
+    Returns:
+        dict: A dictionary containing a research log and the downloaded file paths.
+
+    """
+    research_log = []
+    research_log.append(f"Starting process for DOI: {doi}")
+
+    # CrossRef API to resolve DOI to a publisher page
+    crossref_url = f"https://doi.org/{doi}"
+    headers = {"User-Agent": "Mozilla/5.0"}
+    response = requests.get(crossref_url, headers=headers)
+
+    if response.status_code != 200:
+        log_message = f"Failed to resolve DOI: {doi}. Status Code: {response.status_code}"
+        research_log.append(log_message)
+        return {"log": research_log, "files": []}
+
+    publisher_url = response.url
+    research_log.append(f"Resolved DOI to publisher page: {publisher_url}")
+
+    # Fetch publisher page
+    response = requests.get(publisher_url, headers=headers)
+    if response.status_code != 200:
+        log_message = f"Failed to access publisher page for DOI {doi}."
+        research_log.append(log_message)
+        return {"log": research_log, "files": []}
+
+    # Parse page content
+    soup = BeautifulSoup(response.content, "html.parser")
+    supplementary_links = []
+
+    # Look for supplementary materials by keywords or links
+    for link in soup.find_all("a", href=True):
+        href = link.get("href")
+        text = link.get_text().lower()
+        if "supplementary" in text or "supplemental" in text or "appendix" in text:
+            full_url = urljoin(publisher_url, href)
+            supplementary_links.append(full_url)
+            research_log.append(f"Found supplementary material link: {full_url}")
+
+    if not supplementary_links:
+        log_message = f"No supplementary materials found for DOI {doi}."
+        research_log.append(log_message)
+        return research_log
+
+    # Create output directory
+    os.makedirs(output_dir, exist_ok=True)
+    research_log.append(f"Created output directory: {output_dir}")
+
+    # Download supplementary materials
+    downloaded_files = []
+    for link in supplementary_links:
+        file_name = os.path.join(output_dir, link.split("/")[-1])
+        file_response = requests.get(link, headers=headers)
+        if file_response.status_code == 200:
+            with open(file_name, "wb") as f:
+                f.write(file_response.content)
+            downloaded_files.append(file_name)
+            research_log.append(f"Downloaded file: {file_name}")
+        else:
+            research_log.append(f"Failed to download file from {link}")
+
+    if downloaded_files:
+        research_log.append(f"Successfully downloaded {len(downloaded_files)} file(s).")
+    else:
+        research_log.append(f"No files could be downloaded for DOI {doi}.")
+
+    return "\n".join(research_log)
+
+
+def query_arxiv(query: str, max_papers: int = 10) -> str:
+    """Query arXiv for papers based on the provided search query.
+
+    Parameters
+    ----------
+    - query (str): The search query string.
+    - max_papers (int): The maximum number of papers to retrieve (default: 10).
+
+    Returns
+    -------
+    - str: The formatted search results or an error message.
+
+    """
+    import arxiv
+
+    try:
+        client = arxiv.Client()
+        search = arxiv.Search(query=query, max_results=max_papers, sort_by=arxiv.SortCriterion.Relevance)
+        results = "\n\n".join([f"Title: {paper.title}\nSummary: {paper.summary}" for paper in client.results(search)])
+        return results if results else "No papers found on arXiv."
+    except Exception as e:
+        return f"Error querying arXiv: {e}"
+
+
+def query_scholar(query: str) -> str:
+    """Query Google Scholar for papers based on the provided search query.
+
+    Parameters
+    ----------
+    - query (str): The search query string.
+
+    Returns
+    -------
+    - str: The first search result formatted or an error message.
+
+    """
+    from scholarly import ProxyGenerator, scholarly
+
+    # Set up a ProxyGenerator object to use free proxies
+    # This needs to be done only once per session
+    pg = ProxyGenerator()
+    pg.FreeProxies()
+    scholarly.use_proxy(pg)
+    try:
+        search_query = scholarly.search_pubs(query)
+        result = next(search_query, None)
+        if result:
+            return f"Title: {result['bib']['title']}\nYear: {result['bib']['pub_year']}\nVenue: {result['bib']['venue']}\nAbstract: {result['bib']['abstract']}"
+        else:
+            return "No results found on Google Scholar."
+    except Exception as e:
+        return f"Error querying Google Scholar: {e}"
+
+
+def query_pubmed(query: str, max_papers: int = 10, max_retries: int = 3) -> str:
+    """Query PubMed for papers based on the provided search query.
+
+    Parameters
+    ----------
+    - query (str): The search query string.
+    - max_papers (int): The maximum number of papers to retrieve (default: 10).
+    - max_retries (int): Maximum number of retry attempts with modified queries (default: 3).
+
+    Returns
+    -------
+    - str: The formatted search results or an error message.
+
+    """
+    from pymed import PubMed
+
+    try:
+        pubmed = PubMed(tool="MyTool", email="your-email@example.com")  # Update with a valid email address
+
+        # Initial attempt
+        papers = list(pubmed.query(query, max_results=max_papers))
+
+        # Retry with modified queries if no results
+        retries = 0
+        while not papers and retries < max_retries:
+            retries += 1
+            # Simplify query with each retry by removing the last word
+            simplified_query = " ".join(query.split()[:-retries]) if len(query.split()) > retries else query
+            time.sleep(1)  # Add delay between requests
+            papers = list(pubmed.query(simplified_query, max_results=max_papers))
+
+        if papers:
+            results = "\n\n".join(
+                [f"Title: {paper.title}\nAbstract: {paper.abstract}\nJournal: {paper.journal}" for paper in papers]
+            )
+            return results
+        else:
+            return "No papers found on PubMed after multiple query attempts."
+    except Exception as e:
+        return f"Error querying PubMed: {e}"
+
+
+def search_google(query: str, num_results: int = 3, language: str = "en") -> list[dict]:
+    """Search using Google search.
+
+    Args:
+        query (str): The search query (e.g., "protocol text or seach question")
+        num_results (int): Number of results to return (default: 10)
+        language (str): Language code for search results (default: 'en')
+        pause (float): Pause between searches to avoid rate limiting (default: 2.0 seconds)
+
+    Returns:
+        List[dict]: List of dictionaries containing search results with title and URL
+
+    """
+    try:
+        results_string = ""
+        search_query = f"{query}"
+
+        print(f"Searching for {search_query} with {num_results} results and {language} language")
+
+        for res in search(search_query, num_results=num_results, lang=language, advanced=True):
+            print(f"Found result: {res.title}")
+            title = res.title
+            url = res.url
+            description = res.description
+
+            results_string += f"Title: {title}\nURL: {url}\nDescription: {description}\n\n"
+
+    except Exception as e:
+        print(f"Error performing search: {str(e)}")
+    return results_string
+
+
+def advanced_web_search_claude(
+    query: str,
+    max_searches: int = 1,
+    max_retries: int = 3,
+) -> tuple[str, list[dict[str, str]], list]:
+    """
+    Initiate an advanced web search by launching a specialized agent to collect relevant information and citations through multiple rounds of web searches for a given query.
+    Craft the query carefully for the search agent to find the most relevant information.
+
+    Parameters
+    ----------
+    query : str
+        The search phrase you want Claude to look up.
+    max_searches : int, optional
+        Upper-bound on searches Claude may issue inside this request.
+    max_retries : int, optional
+        Maximum number of retry attempts with exponential backoff.
+
+    Returns
+    -------
+    full_text : str
+        A formatted string containing the full text response from Claude and the citations.
+    """
+    import random
+
+    import anthropic
+
+    try:
+        from biomni.config import default_config
+
+        model = default_config.llm
+        api_key = default_config.api_key
+        if not api_key:
+            api_key = os.getenv("ANTHROPIC_API_KEY")
+    except ImportError:
+        model = "claude-4-sonnet-latest"
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+
+    if "claude" not in model:
+        raise ValueError("Model must be a Claude model.")
+
+    if not api_key:
+        raise ValueError("Set your api_key explicitly.")
+
+    client = anthropic.Anthropic(api_key=api_key)
+    tool_def = {
+        "type": "web_search_20250305",
+        "name": "web_search",
+        "max_uses": max_searches,
+    }
+
+    delay = random.randint(1, 10)
+
+    for attempt in range(1, max_retries + 1):
+        try:
+            response = client.messages.create(
+                model=model,
+                max_tokens=4096,
+                messages=[{"role": "user", "content": query}],
+                tools=[tool_def],
+            )
+
+            paragraphs, citations = [], []
+            response.content = response.content
+            formatted_response = ""
+            for blk in response.content:
+                if blk.type == "text":
+                    paragraphs.append(blk.text)
+                    formatted_response += blk.text
+
+                    if blk.citations:
+                        for cite in blk.citations:
+                            citations.append({"url": cite.url, "title": cite.title, "cited_text": cite.cited_text})
+                            formatted_response += f"(Citation: {cite.title} - {cite.url})"
+            return formatted_response
+
+        except Exception as e:
+            if attempt < max_retries:
+                time.sleep(delay)
+                delay *= 2
+                continue
+            print(f"Error performing web search after {max_retries} attempts: {str(e)}")
+            return f"Error performing web search after {max_retries} attempts: {str(e)}"
+
+
+def extract_url_content(url: str) -> str:
+    """Extract the text content of a webpage using requests and BeautifulSoup.
+
+    Args:
+        url: Webpage URL to extract content from
+
+    Returns:
+        Text content of the webpage
+
+    """
+    response = requests.get(url, headers={"User-Agent": "Mozilla/5.0"})
+
+    # Check if the response is in text format
+    if "text/plain" in response.headers.get("Content-Type", "") or "application/json" in response.headers.get(
+        "Content-Type", ""
+    ):
+        return response.text.strip()  # Return plain text or JSON response directly
+
+    # If it's HTML, use BeautifulSoup to parse
+    soup = BeautifulSoup(response.text, "html.parser")
+
+    # Try to find main content first, fallback to body
+    content = soup.find("main") or soup.find("article") or soup.body
+
+    # Remove unwanted elements
+    for element in content(["script", "style", "nav", "header", "footer", "aside", "iframe"]):
+        element.decompose()
+
+    # Extract text with better formatting
+    paragraphs = content.find_all(["p", "h1", "h2", "h3", "h4", "h5", "h6"])
+    cleaned_text = []
+
+    for p in paragraphs:
+        text = p.get_text().strip()
+        if text:  # Only add non-empty paragraphs
+            cleaned_text.append(text)
+
+    return "\n\n".join(cleaned_text)
+
+
+def extract_pdf_content(url: str) -> str:
+    """Extract the text content of a PDF file given its URL.
+
+    Args:
+        url: URL of the PDF file to extract text from
+
+    Returns:
+        The extracted text content from the PDF
+
+    """
+    try:
+        # Check if the URL ends with .pdf
+        if not url.lower().endswith(".pdf"):
+            # If not, try to find a PDF link on the page
+            response = requests.get(url, timeout=30)
+            if response.status_code == 200:
+                # Look for PDF links in the HTML content
+                pdf_links = re.findall(r'href=[\'"]([^\'"]+\.pdf)[\'"]', response.text)
+                if pdf_links:
+                    # Use the first PDF link found
+                    if not pdf_links[0].startswith("http"):
+                        # Handle relative URLs
+                        base_url = "/".join(url.split("/")[:3])
+                        url = base_url + pdf_links[0] if pdf_links[0].startswith("/") else base_url + "/" + pdf_links[0]
+                    else:
+                        url = pdf_links[0]
+                else:
+                    return f"No PDF file found at {url}. Please provide a direct link to a PDF file."
+
+        # Download the PDF
+        response = requests.get(url, timeout=30)
+
+        # Check if we actually got a PDF file (by checking content type or magic bytes)
+        content_type = response.headers.get("Content-Type", "").lower()
+        if "application/pdf" not in content_type and not response.content.startswith(b"%PDF"):
+            return f"The URL did not return a valid PDF file. Content type: {content_type}"
+
+        pdf_file = BytesIO(response.content)
+
+        # Try with PyPDF2 first
+        try:
+            text = ""
+            pdf_reader = PyPDF2.PdfReader(pdf_file)
+            for page_num in range(len(pdf_reader.pages)):
+                page = pdf_reader.pages[page_num]
+                text += page.extract_text() + "\n\n"
+        except Exception as e:
+            print(f"Error extracting text from PDF: {str(e)}")
+
+        # Clean up the text
+        text = re.sub(r"\s+", " ", text).strip()
+
+        if not text:
+            return "The PDF file did not contain any extractable text. It may be an image-based PDF requiring OCR."
+
+        return text
+
+    except requests.exceptions.RequestException as e:
+        return f"Error downloading PDF: {str(e)}"
+    except Exception as e:
+        return f"Error extracting text from PDF: {str(e)}"

Biomni/biomni/tool/pathology.py

@@ -0,0 +1,1034 @@
+def analyze_aortic_diameter_and_geometry(image_path, output_dir="./output"):
+    """Analyze aortic diameter and geometry from cardiovascular imaging data.
+
+    This function processes cardiovascular imaging data (ultrasound or CT/MRI) to
+    measure aortic root diameter, ascending aorta diameter, and calculate
+    geometric parameters such as tortuosity and dilation indices.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the cardiovascular imaging data (DICOM, JPG, PNG)
+    output_dir : str, optional
+        Directory to save output files (default: "./output")
+
+    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)
+
+    # Initialize research log
+    log = []
+    log.append(f"Aortic Diameter and Geometry Analysis - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append(f"Input image: {image_path}")
+
+    # Step 1: Load the image
+    log.append("\n1. Loading and preprocessing image")
+    try:
+        # Check if file exists
+        if not os.path.exists(image_path):
+            return f"Error: File {image_path} not found"
+
+        # Load image
+        image = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE)
+        if image is None:
+            return f"Error: Could not read image {image_path}"
+
+        log.append(f"  - Image loaded: {image.shape[1]}x{image.shape[0]} pixels")
+
+        # Basic preprocessing
+        image = cv2.GaussianBlur(image, (5, 5), 0)
+        log.append("  - Applied Gaussian blur for noise reduction")
+
+        # Enhance contrast
+        clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+        image = clahe.apply(image)
+        log.append("  - Enhanced contrast using CLAHE")
+
+    except Exception as e:
+        return f"Error during image loading: {str(e)}"
+
+    # Step 2: Segment the aorta
+    log.append("\n2. Aorta segmentation")
+    try:
+        # Otsu thresholding for initial segmentation
+        thresh_val, binary = cv2.threshold(image, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        log.append(f"  - Applied Otsu thresholding (threshold value: {thresh_val})")
+
+        # Morphological operations to clean up the binary image
+        kernel = np.ones((3, 3), np.uint8)
+        binary = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
+        binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
+        log.append("  - Applied morphological operations to refine segmentation")
+
+        # Find contours
+        contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        log.append(f"  - Detected {len(contours)} contours")
+
+        # Assuming the aorta is one of the largest contours
+        if len(contours) == 0:
+            return "Error: No contours detected in the image"
+
+        # Sort contours by area and take the largest
+        contours = sorted(contours, key=cv2.contourArea, reverse=True)
+        aorta_contour = contours[0]  # Assuming the largest contour is the aorta
+        log.append(f"  - Selected largest contour as aorta (area: {cv2.contourArea(aorta_contour)} px²)")
+
+    except Exception as e:
+        return f"Error during aorta segmentation: {str(e)}"
+
+    # Step 3: Measure aortic diameters
+    log.append("\n3. Measuring aortic diameters")
+    try:
+        # Create a mask of the aorta
+        aorta_mask = np.zeros_like(image)
+        cv2.drawContours(aorta_mask, [aorta_contour], 0, 255, -1)
+
+        # Find the centerline of the aorta (simplified approach)
+        # This is a simplified approach - in a real implementation, skeletonization would be better
+        M = cv2.moments(aorta_contour)
+        if M["m00"] != 0:
+            cx = int(M["m10"] / M["m00"])
+            cy = int(M["m01"] / M["m00"])
+            log.append(f"  - Aorta centroid: ({cx}, {cy})")
+        else:
+            cx, cy = 0, 0
+            log.append("  - Warning: Could not calculate aorta centroid")
+
+        # Measure aortic root diameter (assuming it's at the bottom of the contour)
+        aortic_root_points = sorted(aorta_contour.reshape(-1, 2), key=lambda p: p[1], reverse=True)[:20]
+        aortic_root_diameter = np.max([p[0] for p in aortic_root_points]) - np.min([p[0] for p in aortic_root_points])
+        log.append(f"  - Aortic root diameter: {aortic_root_diameter:.2f} pixels")
+
+        # Measure ascending aorta diameter (assuming it's at the middle of the contour)
+        y_mid = (
+            np.min([p[1] for p in aorta_contour.reshape(-1, 2)]) + np.max([p[1] for p in aorta_contour.reshape(-1, 2)])
+        ) // 2
+        ascending_points = [p for p in aorta_contour.reshape(-1, 2) if abs(p[1] - y_mid) < 10]
+        if ascending_points:
+            ascending_diameter = np.max([p[0] for p in ascending_points]) - np.min([p[0] for p in ascending_points])
+            log.append(f"  - Ascending aorta diameter: {ascending_diameter:.2f} pixels")
+        else:
+            ascending_diameter = 0
+            log.append("  - Warning: Could not measure ascending aorta diameter")
+
+    except Exception as e:
+        return f"Error during diameter measurements: {str(e)}"
+
+    # Step 4: Calculate geometric parameters
+    log.append("\n4. Calculating aortic geometry parameters")
+    try:
+        # Calculate tortuosity (simplified as the ratio of contour length to end-to-end distance)
+        contour_length = cv2.arcLength(aorta_contour, closed=True)
+
+        # Find the two most distant points (approximation for end-to-end distance)
+        hull = cv2.convexHull(aorta_contour)
+        hull_points = hull.reshape(-1, 2)
+        max_dist = 0
+        for i in range(len(hull_points)):
+            for j in range(i + 1, len(hull_points)):
+                dist = np.sqrt(
+                    (hull_points[i][0] - hull_points[j][0]) ** 2 + (hull_points[i][1] - hull_points[j][1]) ** 2
+                )
+                max_dist = max(max_dist, dist)
+
+        if max_dist > 0:
+            tortuosity = contour_length / max_dist
+            log.append(f"  - Aortic tortuosity index: {tortuosity:.2f}")
+        else:
+            tortuosity = 0
+            log.append("  - Warning: Could not calculate tortuosity")
+
+        # Calculate dilation index (ratio of max diameter to min diameter)
+        min_diameter = min(aortic_root_diameter, ascending_diameter)
+        max_diameter = max(aortic_root_diameter, ascending_diameter)
+
+        if min_diameter > 0:
+            dilation_index = max_diameter / min_diameter
+            log.append(f"  - Aortic dilation index: {dilation_index:.2f}")
+        else:
+            dilation_index = 0
+            log.append("  - Warning: Could not calculate dilation index")
+
+    except Exception as e:
+        return f"Error during geometry calculations: {str(e)}"
+
+    # Step 5: Save results
+    log.append("\n5. Saving results")
+    try:
+        # Create a visual output
+        output_image = cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+        cv2.drawContours(output_image, [aorta_contour], 0, (0, 255, 0), 2)
+
+        # Mark diameters
+        cv2.circle(output_image, (cx, cy), 5, (0, 0, 255), -1)
+
+        # Save the output image
+        output_filename = os.path.join(output_dir, f"aorta_analysis_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+        cv2.imwrite(output_filename, output_image)
+        log.append(f"  - Saved annotated image to: {output_filename}")
+
+        # Save measurements to a text file
+        measurements_filename = os.path.join(
+            output_dir,
+            f"aorta_measurements_{datetime.now().strftime('%Y%m%d_%H%M%S')}.txt",
+        )
+        with open(measurements_filename, "w") as f:
+            f.write(f"Aortic Root Diameter: {aortic_root_diameter:.2f} pixels\n")
+            f.write(f"Ascending Aorta Diameter: {ascending_diameter:.2f} pixels\n")
+            f.write(f"Tortuosity Index: {tortuosity:.2f}\n")
+            f.write(f"Dilation Index: {dilation_index:.2f}\n")
+        log.append(f"  - Saved measurements to: {measurements_filename}")
+
+    except Exception as e:
+        return f"Error during saving results: {str(e)}"
+
+    # Step 6: Summarize findings
+    log.append("\n6. Summary of findings")
+    log.append(f"  - Aortic root diameter: {aortic_root_diameter:.2f} pixels")
+    log.append(f"  - Ascending aorta diameter: {ascending_diameter:.2f} pixels")
+    log.append(f"  - Tortuosity index: {tortuosity:.2f}")
+    log.append(f"  - Dilation index: {dilation_index:.2f}")
+
+    return "\n".join(log)
+
+
+def analyze_atp_luminescence_assay(
+    data_file,
+    standard_curve_file,
+    normalization_method="cell_count",
+    normalization_data=None,
+):
+    """Analyze luminescence-based ATP assay data to determine intracellular ATP concentration.
+
+    Parameters
+    ----------
+    data_file : str
+        Path to CSV file containing luminescence readings from samples.
+        Expected format: columns for 'Sample_ID' and 'Luminescence_Value'.
+
+    standard_curve_file : str
+        Path to CSV file containing standard curve data.
+        Expected format: columns for 'ATP_Concentration' (in nM) and 'Luminescence_Value'.
+
+    normalization_method : str, optional
+        Method used to normalize ATP values, either 'cell_count' or 'protein_content'.
+        Default is 'cell_count'.
+
+    normalization_data : str or dict, optional
+        Either path to CSV file with normalization data or dictionary with sample IDs as keys.
+        For 'cell_count': values should be cell counts per sample.
+        For 'protein_content': values should be protein concentration (μg/mL).
+
+    Returns
+    -------
+    str
+        Research log summarizing the ATP content measurement process and results.
+
+    """
+    from datetime import datetime
+
+    import numpy as np
+    import pandas as pd
+
+    log = []
+    log.append(f"ATP Content Measurement Analysis - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    log.append("=" * 50)
+
+    # Step 1: Load the raw luminescence data
+    log.append("Step 1: Loading raw luminescence data")
+    try:
+        sample_data = pd.read_csv(data_file)
+        log.append(f"Successfully loaded data from {data_file}")
+        log.append(f"Number of samples: {len(sample_data)}")
+    except Exception as e:
+        log.append(f"Error loading sample data: {str(e)}")
+        return "\n".join(log)
+
+    # Step 2: Load the standard curve data
+    log.append("\nStep 2: Loading ATP standard curve data")
+    try:
+        std_curve_data = pd.read_csv(standard_curve_file)
+        log.append(f"Successfully loaded standard curve from {standard_curve_file}")
+    except Exception as e:
+        log.append(f"Error loading standard curve data: {str(e)}")
+        return "\n".join(log)
+
+    # Step 3: Generate standard curve equation (linear regression)
+    log.append("\nStep 3: Generating ATP standard curve")
+    try:
+        x = std_curve_data["Luminescence_Value"]
+        y = std_curve_data["ATP_Concentration"]
+        slope, intercept = np.polyfit(x, y, 1)
+        log.append(f"Standard curve equation: ATP_Concentration = {slope:.6f} × Luminescence + {intercept:.6f}")
+    except Exception as e:
+        log.append(f"Error generating standard curve: {str(e)}")
+        return "\n".join(log)
+
+    # Step 4: Calculate ATP concentrations for samples
+    log.append("\nStep 4: Calculating ATP concentrations for samples")
+    try:
+        sample_data["ATP_Concentration_nM"] = slope * sample_data["Luminescence_Value"] + intercept
+        log.append("ATP concentrations calculated for all samples")
+    except Exception as e:
+        log.append(f"Error calculating ATP concentrations: {str(e)}")
+        return "\n".join(log)
+
+    # Step 5: Normalize ATP concentrations
+    log.append(f"\nStep 5: Normalizing ATP concentrations by {normalization_method}")
+
+    # Load normalization data
+    if normalization_data:
+        try:
+            if isinstance(normalization_data, str):
+                norm_data = pd.read_csv(normalization_data)
+                norm_dict = dict(zip(norm_data["Sample_ID"], norm_data[normalization_method], strict=False))
+            else:
+                norm_dict = normalization_data
+
+            # Apply normalization
+            for idx, row in sample_data.iterrows():
+                sample_id = row["Sample_ID"]
+                if sample_id in norm_dict:
+                    if normalization_method == "cell_count":
+                        sample_data.at[idx, "ATP_pmol_per_million_cells"] = (
+                            row["ATP_Concentration_nM"] / norm_dict[sample_id] * 1000
+                        )
+                    elif normalization_method == "protein_content":
+                        sample_data.at[idx, "ATP_nmol_per_mg_protein"] = (
+                            row["ATP_Concentration_nM"] / norm_dict[sample_id]
+                        )
+
+            log.append(f"Successfully normalized ATP concentrations by {normalization_method}")
+        except Exception as e:
+            log.append(f"Error during normalization: {str(e)}")
+            log.append("Continuing with unnormalized ATP concentrations")
+    else:
+        log.append("No normalization data provided. Reporting unnormalized ATP concentrations.")
+
+    # Step 6: Save results
+    output_file = "atp_measurement_results.csv"
+    try:
+        sample_data.to_csv(output_file, index=False)
+        log.append(f"\nStep 6: Results saved to {output_file}")
+    except Exception as e:
+        log.append(f"\nStep 6: Error saving results: {str(e)}")
+
+    # Step 7: Summary statistics
+    log.append("\nStep 7: Summary of ATP measurement results")
+    try:
+        log.append("ATP Concentration Summary (nM):")
+        log.append(f"  Mean: {sample_data['ATP_Concentration_nM'].mean():.2f}")
+        log.append(f"  Median: {sample_data['ATP_Concentration_nM'].median():.2f}")
+        log.append(f"  Min: {sample_data['ATP_Concentration_nM'].min():.2f}")
+        log.append(f"  Max: {sample_data['ATP_Concentration_nM'].max():.2f}")
+
+        if normalization_method == "cell_count" and "ATP_pmol_per_million_cells" in sample_data.columns:
+            log.append("\nATP per Million Cells (pmol):")
+            log.append(f"  Mean: {sample_data['ATP_pmol_per_million_cells'].mean():.2f}")
+            log.append(f"  Median: {sample_data['ATP_pmol_per_million_cells'].median():.2f}")
+        elif normalization_method == "protein_content" and "ATP_nmol_per_mg_protein" in sample_data.columns:
+            log.append("\nATP per mg Protein (nmol):")
+            log.append(f"  Mean: {sample_data['ATP_nmol_per_mg_protein'].mean():.2f}")
+            log.append(f"  Median: {sample_data['ATP_nmol_per_mg_protein'].median():.2f}")
+    except Exception as e:
+        log.append(f"Error generating summary statistics: {str(e)}")
+
+    log.append("\nATP Content Measurement Analysis Complete")
+
+    return "\n".join(log)
+
+
+def analyze_thrombus_histology(image_path, output_dir="./output"):
+    """Analyze histological images of thrombus samples stained with H&E to identify and quantify
+    different thrombus components (fresh, cellular lysis, endothelialization, fibroblastic reaction).
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the histological image of thrombus sample stained with H&E
+    output_dir : str, optional
+        Directory to save output files (default: "./output")
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import cv2
+    import numpy as np
+    from skimage import color
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Initialize research log
+    log = f"# Thrombus Component Analysis - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+    log += f"Analyzing image: {image_path}\n\n"
+
+    # Step 1: Load and preprocess the image
+    log += "## Step 1: Image Loading and Preprocessing\n"
+    original_image = cv2.imread(image_path)
+    if original_image is None:
+        return f"Error: Could not load image from {image_path}"
+
+    # Convert to RGB (from BGR)
+    rgb_image = cv2.cvtColor(original_image, cv2.COLOR_BGR2RGB)
+    log += f"- Loaded image with dimensions: {rgb_image.shape[1]}x{rgb_image.shape[0]} pixels\n"
+
+    # Convert to LAB color space for better color segmentation
+    lab_image = color.rgb2lab(rgb_image)
+    log += "- Converted image to LAB color space for improved color-based segmentation\n\n"
+
+    # Step 2: Segment thrombus components based on color characteristics
+    log += "## Step 2: Thrombus Component Segmentation\n"
+
+    # Create masks for different components based on color thresholds
+    # These thresholds are approximate and may need adjustment for specific staining protocols
+
+    # Fresh thrombus: typically red (erythrocytes) with blue nuclei (leukocytes)
+    # Usually appears as bright red/pink areas with scattered dark blue/purple nuclei
+    fresh_mask = (
+        (lab_image[:, :, 0] > 50)  # Lightness
+        & (lab_image[:, :, 1] > 15)  # a* channel (red component)
+    )
+
+    # Cellular lysis: degraded cellular components, less intense staining
+    lysis_mask = (
+        (lab_image[:, :, 0] > 60)  # Lightness
+        & (lab_image[:, :, 1] < 15)  # Less red
+        & (lab_image[:, :, 1] > -5)
+        & (lab_image[:, :, 2] < 10)  # Less blue
+    )
+
+    # Endothelialization: endothelial cells lining the thrombus
+    # Typically appears as thin, organized cellular layers
+    endothel_mask = (
+        (lab_image[:, :, 0] > 40) & (lab_image[:, :, 0] < 70) & (lab_image[:, :, 2] < -5)  # More blue component
+    )
+
+    # Fibroblastic reaction: fibroblasts and collagen deposition
+    # Usually appears as pale pink/purple fibrous structures
+    fibro_mask = (
+        (lab_image[:, :, 0] > 70)  # Lighter areas
+        & (lab_image[:, :, 1] < 5)  # Less red
+        & (lab_image[:, :, 1] > -10)
+        & (lab_image[:, :, 2] > 0)  # Less blue
+    )
+
+    log += "- Created masks for each thrombus component based on color characteristics\n"
+
+    # Step 3: Quantify the components
+    log += "\n## Step 3: Component Quantification\n"
+
+    # Calculate total pixel count (excluding background)
+    total_pixels = fresh_mask.sum() + lysis_mask.sum() + endothel_mask.sum() + fibro_mask.sum()
+
+    # Calculate percentages
+    if total_pixels > 0:
+        fresh_percent = (fresh_mask.sum() / total_pixels) * 100
+        lysis_percent = (lysis_mask.sum() / total_pixels) * 100
+        endothel_percent = (endothel_mask.sum() / total_pixels) * 100
+        fibro_percent = (fibro_mask.sum() / total_pixels) * 100
+    else:
+        fresh_percent = lysis_percent = endothel_percent = fibro_percent = 0
+
+    log += f"- Fresh thrombus: {fresh_percent:.2f}%\n"
+    log += f"- Cellular lysis: {lysis_percent:.2f}%\n"
+    log += f"- Endothelialization: {endothel_percent:.2f}%\n"
+    log += f"- Fibroblastic reaction: {fibro_percent:.2f}%\n\n"
+
+    # Step 4: Visualize the results
+    log += "## Step 4: Visualization\n"
+
+    # Create a visualization image
+    visualization = np.zeros_like(rgb_image)
+
+    # Assign colors to different components
+    visualization[fresh_mask] = [255, 0, 0]  # Red for fresh thrombus
+    visualization[lysis_mask] = [0, 255, 0]  # Green for cellular lysis
+    visualization[endothel_mask] = [0, 0, 255]  # Blue for endothelialization
+    visualization[fibro_mask] = [255, 255, 0]  # Yellow for fibroblastic reaction
+
+    # Save the visualization
+    output_filename = os.path.join(output_dir, f"thrombus_components_{os.path.basename(image_path)}")
+    cv2.imwrite(output_filename, cv2.cvtColor(visualization, cv2.COLOR_RGB2BGR))
+
+    log += f"- Visualization saved as: {output_filename}\n"
+    log += "- Color legend:\n"
+    log += "  - Red: Fresh thrombus\n"
+    log += "  - Green: Cellular lysis\n"
+    log += "  - Blue: Endothelialization\n"
+    log += "  - Yellow: Fibroblastic reaction\n\n"
+
+    # Step 5: Summary
+    log += "## Summary\n"
+    log += "The histological analysis of the thrombus sample revealed the following composition:\n\n"
+    log += f"1. Fresh thrombus: {fresh_percent:.2f}%\n"
+    log += f"2. Cellular lysis: {lysis_percent:.2f}%\n"
+    log += f"3. Endothelialization: {endothel_percent:.2f}%\n"
+    log += f"4. Fibroblastic reaction: {fibro_percent:.2f}%\n\n"
+
+    # Save results to CSV
+    import csv
+
+    csv_filename = os.path.join(
+        output_dir,
+        f"thrombus_analysis_{os.path.basename(image_path).split('.')[0]}.csv",
+    )
+    with open(csv_filename, "w", newline="") as csvfile:
+        writer = csv.writer(csvfile)
+        writer.writerow(["Component", "Percentage"])
+        writer.writerow(["Fresh thrombus", f"{fresh_percent:.2f}"])
+        writer.writerow(["Cellular lysis", f"{lysis_percent:.2f}"])
+        writer.writerow(["Endothelialization", f"{endothel_percent:.2f}"])
+        writer.writerow(["Fibroblastic reaction", f"{fibro_percent:.2f}"])
+
+    log += f"Quantitative results saved to: {csv_filename}\n"
+
+    return log
+
+
+def analyze_intracellular_calcium_with_rhod2(
+    background_image_path, control_image_path, sample_image_path, output_dir="./output"
+):
+    """Analyzes intracellular calcium concentration using Rhod-2 fluorescent indicator from microscopy images.
+
+    Parameters
+    ----------
+    background_image_path : str
+        Path to the background image (no cells, just media)
+    control_image_path : str
+        Path to the control image (cells without calcium stimulus)
+    sample_image_path : str
+        Path to the sample image (cells with calcium stimulus)
+    output_dir : str, optional
+        Directory to save output files, default is "./output"
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import cv2
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Step 1: Load images
+    background = cv2.imread(background_image_path, cv2.IMREAD_GRAYSCALE).astype(float)
+    control = cv2.imread(control_image_path, cv2.IMREAD_GRAYSCALE).astype(float)
+    sample = cv2.imread(sample_image_path, cv2.IMREAD_GRAYSCALE).astype(float)
+
+    # Step 2: Background subtraction
+    control_corrected = np.maximum(control - background, 0)
+    sample_corrected = np.maximum(sample - background, 0)
+
+    # Step 3: Calculate fluorescence intensity (mean values)
+    control_intensity = np.mean(control_corrected)
+    sample_intensity = np.mean(sample_corrected)
+
+    # Step 4: Convert to calcium concentration using a standard calibration equation
+    # [Ca2+] = Kd * (F - Fmin) / (Fmax - F)
+    # For Rhod-2, Kd is approximately 570 nM
+    # We'll use control as Fmin and estimate Fmax as 2.5x the sample value (typical for max calcium response)
+    kd = 570  # nM
+    f_min = control_intensity
+    f_max = 2.5 * sample_intensity  # Estimated maximum
+    f = sample_intensity
+
+    # Guard against division by zero
+    calcium_concentration = float("inf") if f_max == f else kd * (f - f_min) / (f_max - f)
+
+    # Step 5: Generate heatmap visualization of calcium concentration
+    plt.figure(figsize=(10, 8))
+    calcium_map = (sample_corrected - control_corrected) / (f_max - control_corrected + 1e-10) * kd
+    plt.imshow(calcium_map, cmap="hot")
+    plt.colorbar(label="[Ca²⁺] (nM)")
+    plt.title("Intracellular Calcium Concentration Map")
+
+    # Save the visualization
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    result_filename = f"{output_dir}/calcium_map_{timestamp}.png"
+    plt.savefig(result_filename)
+    plt.close()
+
+    # Generate research log
+    log = f"""
+Intracellular Calcium Imaging Analysis Log - {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+------------------------------------------------------------
+1. Loaded microscopy images:
+   - Background image: {background_image_path}
+   - Control image: {control_image_path}
+   - Sample image: {sample_image_path}
+
+2. Performed background subtraction to correct for autofluorescence
+
+3. Calculated fluorescence intensity:
+   - Control intensity: {control_intensity:.2f} a.u.
+   - Sample intensity: {sample_intensity:.2f} a.u.
+
+4. Converted fluorescence to calcium concentration using Rhod-2 calibration:
+   - Kd value: {kd} nM
+   - Mean intracellular [Ca²⁺]: {calcium_concentration:.2f} nM
+
+5. Generated calcium concentration heatmap saved to:
+   - {result_filename}
+
+Analysis complete. The sample shows {calcium_concentration:.2f} nM intracellular calcium concentration.
+"""
+
+    return log
+
+
+def quantify_corneal_nerve_fibers(image_path, marker_type, output_dir="./output", threshold_method="otsu"):
+    """Quantify the volume/density of immunofluorescence-labeled corneal nerve fibers.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the immunofluorescence microscopy image file
+    marker_type : str
+        Type of nerve fiber marker (e.g., 'βIII-tubulin', 'SP', 'L1CAM')
+    output_dir : str, optional
+        Directory to save output files (default: './output')
+    threshold_method : str, optional
+        Method for thresholding ('otsu', 'adaptive', 'manual'), default is 'otsu'
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import numpy as np
+    from skimage import filters, io, measure, morphology, util
+    from skimage.color import rgb2gray
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Generate timestamp for unique filenames
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    base_filename = f"{marker_type.replace(' ', '_')}_{timestamp}"
+
+    # Step 1: Load the image
+    try:
+        image = io.imread(image_path)
+        # Convert to grayscale if RGB
+        if len(image.shape) > 2:
+            image = rgb2gray(image)
+    except Exception as e:
+        return f"Error loading image: {str(e)}"
+
+    # Step 2: Preprocess the image
+    # Normalize to 0-1 range
+    image_normalized = image.astype(float)
+    image_normalized = (image_normalized - image_normalized.min()) / (image_normalized.max() - image_normalized.min())
+
+    # Step 3: Segment the nerve fibers
+    if threshold_method == "otsu":
+        threshold_value = filters.threshold_otsu(image_normalized)
+    elif threshold_method == "adaptive":
+        threshold_value = filters.threshold_local(image_normalized, block_size=35)
+    else:  # manual
+        threshold_value = 0.5  # Default manual threshold
+
+    # Create binary mask
+    binary_mask = image_normalized > threshold_value
+
+    # Step 4: Clean up with morphological operations
+    # Remove small objects
+    cleaned_mask = morphology.remove_small_objects(binary_mask, min_size=50)
+    # Fill holes
+    cleaned_mask = morphology.closing(cleaned_mask, morphology.disk(2))
+
+    # Step 5: Quantify the nerve fibers
+    # Calculate total area of nerve fibers (in pixels)
+    fiber_area = np.sum(cleaned_mask)
+    # Calculate total image area
+    total_area = cleaned_mask.size
+    # Calculate fiber density (percentage of area covered by fibers)
+    fiber_density = (fiber_area / total_area) * 100
+
+    # Calculate properties of individual fiber segments
+    labeled_fibers = measure.label(cleaned_mask)
+    fiber_props = measure.regionprops(labeled_fibers)
+
+    # Calculate average fiber length and width
+    total_length = 0
+    total_width = 0
+    fiber_count = len(fiber_props)
+
+    if fiber_count > 0:
+        for prop in fiber_props:
+            # Approximating length as major axis length
+            total_length += prop.major_axis_length
+            # Approximating width as minor axis length
+            total_width += prop.minor_axis_length
+
+        avg_length = total_length / fiber_count
+        avg_width = total_width / fiber_count
+    else:
+        avg_length = 0
+        avg_width = 0
+
+    # Step 6: Save results
+    # Save segmented image
+    segmented_image_path = os.path.join(output_dir, f"{base_filename}_segmented.png")
+    io.imsave(segmented_image_path, util.img_as_ubyte(cleaned_mask))
+
+    # Save measurements to CSV
+    measurements_path = os.path.join(output_dir, f"{base_filename}_measurements.csv")
+    with open(measurements_path, "w") as f:
+        f.write("Metric,Value\n")
+        f.write(f"Marker Type,{marker_type}\n")
+        f.write(f"Fiber Area (pixels),{fiber_area}\n")
+        f.write(f"Total Image Area (pixels),{total_area}\n")
+        f.write(f"Fiber Density (%),{fiber_density:.2f}\n")
+        f.write(f"Fiber Count,{fiber_count}\n")
+        f.write(f"Average Fiber Length (pixels),{avg_length:.2f}\n")
+        f.write(f"Average Fiber Width (pixels),{avg_width:.2f}\n")
+
+    # Step 7: Generate research log
+    log = f"""
+Research Log: Quantification of {marker_type} Labeled Corneal Nerve Fibers
+Date: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+Image: {os.path.basename(image_path)}
+
+Analysis Steps:
+1. Loaded and preprocessed the immunofluorescence microscopy image
+2. Applied {threshold_method} thresholding for nerve fiber segmentation
+3. Performed morphological operations to clean the segmentation
+4. Quantified nerve fiber metrics
+
+Results:
+- Fiber Area: {fiber_area} pixels
+- Total Image Area: {total_area} pixels
+- Fiber Density: {fiber_density:.2f}%
+- Number of Fiber Segments: {fiber_count}
+- Average Fiber Length: {avg_length:.2f} pixels
+- Average Fiber Width: {avg_width:.2f} pixels
+
+Output Files:
+- Segmented Image: {os.path.basename(segmented_image_path)}
+- Measurements: {os.path.basename(measurements_path)}
+"""
+
+    return log
+
+
+def segment_and_quantify_cells_in_multiplexed_images(
+    image_path, markers_list, nuclear_channel_index=0, output_dir="./output"
+):
+    """Segment cells and quantify protein expression levels from multichannel tissue images.
+
+    Parameters
+    ----------
+    image_path : str
+        Path to the multichannel image file (tiff stack or similar format)
+    markers_list : list of str
+        List of marker names corresponding to each channel in the image
+    nuclear_channel_index : int, optional
+        Index of the nuclear marker channel (default: 0, typically DAPI)
+    output_dir : str, optional
+        Directory to save output files (default: "./output")
+
+    Returns
+    -------
+    str
+        Research log summarizing the steps performed and output file locations
+
+    """
+    import os
+    from datetime import datetime
+
+    import numpy as np
+    import pandas as pd
+    from scipy import ndimage  # Import ndimage for distance transform
+    from skimage import filters, io, measure, morphology, segmentation
+
+    # Initialize research log
+    log = []
+    log.append(
+        f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] Starting cell segmentation and protein quantification"
+    )
+
+    # 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}")
+
+    # Load the multichannel image
+    try:
+        log.append(f"Loading multichannel image from {image_path}")
+        image = io.imread(image_path)
+        log.append(f"Image loaded successfully. Shape: {image.shape}")
+
+        # Validate image dimensions
+        if len(image.shape) < 3:
+            return (
+                "Error: Image should be multichannel with shape (channels, height, width) or (height, width, channels)"
+            )
+
+        # Determine image format
+        if image.shape[0] == len(markers_list):
+            # Format is (channels, height, width)
+            num_channels, height, width = image.shape
+            # Extract nuclear channel
+            nuclear_channel = image[nuclear_channel_index]
+        elif image.shape[-1] == len(markers_list):
+            # Format is (height, width, channels)
+            height, width, num_channels = image.shape
+            # Extract nuclear channel
+            nuclear_channel = image[:, :, nuclear_channel_index]
+        else:
+            return f"Error: Number of channels in image ({image.shape}) doesn't match markers list length ({len(markers_list)})"
+
+        log.append(f"Processing image with {num_channels} channels, dimensions: {height}x{width}")
+
+    except Exception as e:
+        return f"Error loading image: {str(e)}"
+
+    # Segment nuclei
+    log.append("Performing nuclear segmentation")
+    # Apply threshold to nuclear channel
+    threshold = filters.threshold_otsu(nuclear_channel)
+    binary_nuclei = nuclear_channel > threshold
+
+    # Clean up binary image
+    binary_nuclei = morphology.remove_small_objects(binary_nuclei, min_size=50)
+    binary_nuclei = morphology.binary_closing(binary_nuclei, morphology.disk(2))
+
+    # Label nuclei
+    labeled_nuclei = measure.label(binary_nuclei)
+    log.append(f"Identified {np.max(labeled_nuclei)} potential nuclei")
+
+    # Create cell masks by expanding nuclei
+    log.append("Expanding nuclear masks to approximate cell boundaries")
+    cell_masks = segmentation.watershed(
+        -ndimage.distance_transform_edt(~binary_nuclei),  # Use ndimage for distance transform
+        labeled_nuclei,
+        mask=morphology.binary_dilation(binary_nuclei, morphology.disk(10)),
+    )
+
+    # Get region properties for nuclei
+    regions = measure.regionprops(cell_masks)
+    log.append(f"Segmented {len(regions)} cells")
+
+    # Create a dataframe to store cell features
+    log.append("Extracting features and quantifying marker intensities")
+    cell_data = []
+
+    for i, region in enumerate(regions):
+        cell_features = {
+            "cell_id": i + 1,
+            "centroid_y": region.centroid[0],
+            "centroid_x": region.centroid[1],
+            "area": region.area,
+        }
+
+        # Extract intensity for each marker
+        for channel_idx, marker_name in enumerate(markers_list):
+            if image.shape[0] == len(markers_list):
+                # Format is (channels, height, width)
+                marker_image = image[channel_idx]
+            else:
+                # Format is (height, width, channels)
+                marker_image = image[:, :, channel_idx]
+
+            # Create mask for current cell
+            cell_mask = cell_masks == region.label
+
+            # Calculate mean intensity within the cell mask
+            mean_intensity = np.mean(marker_image[cell_mask])
+            cell_features[f"{marker_name}_mean_intensity"] = mean_intensity
+
+        cell_data.append(cell_features)
+
+    # Create dataframe
+    cell_df = pd.DataFrame(cell_data)
+
+    # Save results
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_file = os.path.join(output_dir, f"cell_features_{timestamp}.csv")
+    cell_df.to_csv(results_file, index=False)
+    log.append(f"Saved spatial feature table to {results_file}")
+
+    # Save segmentation mask for visualization
+    mask_file = os.path.join(output_dir, f"cell_segmentation_mask_{timestamp}.tiff")
+    io.imsave(mask_file, cell_masks.astype(np.uint16))
+    log.append(f"Saved cell segmentation mask to {mask_file}")
+
+    # Summarize results
+    log.append(f"Analysis complete. Processed {num_channels} markers across {len(regions)} cells.")
+    log.append("Output files:")
+    log.append(f"  - Spatial feature table: {results_file}")
+    log.append(f"  - Cell segmentation mask: {mask_file}")
+
+    return "\n".join(log)
+
+
+def analyze_bone_microct_morphometry(input_file_path, output_dir="./results", threshold_value=None):
+    """Analyze bone microarchitecture parameters from 3D micro-CT images.
+
+    Performs quantitative analysis of bone microstructure to calculate bone mineral density (BMD),
+    bone volume (BV), trabecular number (Tb.N), trabecular thickness (Tb.Th), and
+    trabecular separation (Tb.S) from micro-CT data.
+
+    Parameters
+    ----------
+    input_file_path : str
+        Path to the micro-CT scan data file (TIFF stack or similar 3D format)
+    output_dir : str, optional
+        Directory to save output files, default is "./results"
+    threshold_value : float, optional
+        Threshold value for bone segmentation. If None, Otsu's method will be used
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import json
+    import os
+    from datetime import datetime
+
+    import numpy as np
+    from scipy import ndimage
+    from skimage import filters, io
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Start research log
+    log = [
+        "# Micro-CT Bone Morphometry Analysis",
+        f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"Input file: {input_file_path}",
+    ]
+
+    # Step 1: Load the micro-CT data
+    log.append("\n## 1. Data Loading")
+    try:
+        log.append(f"Loading 3D micro-CT data from {input_file_path}")
+        # Load the 3D image data
+        image_data = io.imread(input_file_path)
+        if image_data.ndim < 3:
+            log.append("Warning: Input appears to be 2D. Converting to 3D.")
+            image_data = np.expand_dims(image_data, axis=0)
+
+        log.append(f"Data loaded successfully. Dimensions: {image_data.shape}")
+        voxel_count = image_data.size
+        log.append(f"Total voxels: {voxel_count}")
+    except Exception as e:
+        error_msg = f"Error loading data: {str(e)}"
+        log.append(error_msg)
+        return "\n".join(log)
+
+    # Step 2: Preprocess the data
+    log.append("\n## 2. Preprocessing")
+    log.append("Applying median filter to reduce noise")
+    filtered_data = ndimage.median_filter(image_data, size=2)
+
+    # Step 3: Segmentation of bone tissue
+    log.append("\n## 3. Bone Segmentation")
+    if threshold_value is None:
+        log.append("Calculating optimal threshold using Otsu's method")
+        threshold_value = filters.threshold_otsu(filtered_data)
+
+    log.append(f"Segmenting bone using threshold value: {threshold_value}")
+    binary_image = filtered_data > threshold_value
+
+    # Step 4: Calculate bone morphometry parameters
+    log.append("\n## 4. Morphometry Analysis")
+
+    # 4.1 Calculate BMD (simplified as mean intensity in bone regions)
+    bmd = np.mean(image_data[binary_image])
+    log.append(f"Bone Mineral Density (BMD): {bmd:.2f} arbitrary units")
+
+    # 4.2 Calculate BV (bone volume)
+    bone_volume = np.sum(binary_image)
+    total_volume = binary_image.size
+    bv_tv_ratio = bone_volume / total_volume
+    log.append(f"Bone Volume (BV): {bone_volume} voxels")
+    log.append(f"BV/TV Ratio: {bv_tv_ratio:.4f}")
+
+    # 4.3 Calculate trabecular thickness (Tb.Th)
+    # Using distance transform method
+    log.append("Calculating trabecular thickness (Tb.Th)")
+    distance_map = ndimage.distance_transform_edt(binary_image)
+    tb_th_mean = np.mean(distance_map[binary_image]) * 2  # Multiply by 2 for diameter
+    log.append(f"Trabecular Thickness (Tb.Th): {tb_th_mean:.2f} voxels")
+
+    # 4.4 Calculate trabecular separation (Tb.S)
+    log.append("Calculating trabecular separation (Tb.S)")
+    distance_map_inv = ndimage.distance_transform_edt(~binary_image)
+    tb_s_mean = np.mean(distance_map_inv[~binary_image])
+    log.append(f"Trabecular Separation (Tb.S): {tb_s_mean:.2f} voxels")
+
+    # 4.5 Calculate trabecular number (Tb.N)
+    # Simplified calculation: Tb.N = (BV/TV) / Tb.Th
+    log.append("Calculating trabecular number (Tb.N)")
+    tb_n = bv_tv_ratio / tb_th_mean if tb_th_mean > 0 else 0
+    log.append(f"Trabecular Number (Tb.N): {tb_n:.4f} 1/voxel")
+
+    # Step 5: Save results
+    log.append("\n## 5. Saving Results")
+
+    # Save binary segmentation as a sample slice
+    middle_slice = binary_image.shape[0] // 2
+    segmentation_file = os.path.join(output_dir, "bone_segmentation_slice.tif")
+    io.imsave(segmentation_file, binary_image[middle_slice].astype(np.uint8) * 255)
+    log.append(f"Sample segmentation slice saved to: {segmentation_file}")
+
+    # Save numerical results as JSON
+    results = {
+        "BMD": float(bmd),
+        "BV": int(bone_volume),
+        "BV/TV": float(bv_tv_ratio),
+        "Tb.Th": float(tb_th_mean),
+        "Tb.S": float(tb_s_mean),
+        "Tb.N": float(tb_n),
+    }
+
+    results_file = os.path.join(output_dir, "bone_morphometry_results.json")
+    with open(results_file, "w") as f:
+        json.dump(results, f, indent=4)
+    log.append(f"Numerical results saved to: {results_file}")
+
+    # Summary of results
+    log.append("\n## 6. Summary of Bone Morphometry Results")
+    log.append(f"- Bone Mineral Density (BMD): {bmd:.2f} arbitrary units")
+    log.append(f"- Bone Volume (BV): {bone_volume} voxels")
+    log.append(f"- BV/TV Ratio: {bv_tv_ratio:.4f}")
+    log.append(f"- Trabecular Thickness (Tb.Th): {tb_th_mean:.2f} voxels")
+    log.append(f"- Trabecular Separation (Tb.S): {tb_s_mean:.2f} voxels")
+    log.append(f"- Trabecular Number (Tb.N): {tb_n:.4f} 1/voxel")
+
+    return "\n".join(log)

Biomni/biomni/tool/protocols/thermofisher/Cell Freezing Protocols _ Thermo Fisher Scientific - US.txt

@@ -0,0 +1,105 @@
+PROTOCOL: Cell Freezing Protocols
+SOURCE: https://www.thermofisher.com/us/en/home/references/gibco-cell-culture-basics/cell-culture-protocols/freezing-cells.html
+================================================================================
+
+OVERVIEW
+================================================================================
+
+After subculturing your adherent or suspension cells, you may need to freeze any cells not required for immediate experiments. This cell freezing protocol outlines the necessary preparations and materials to order before beginning the freezing process. It also provides step-by-step instructions that you can follow during the procedure or refer to for future use.
+
+Cryopreservation of cells, or the freezing of cells, is a technique used to store living cells and tissues at extremely low temperatures to preserve their structure over an indefinite period. By lowering the temperature to below –130°C, extracellular ice forms, decreasing kinetic and molecular activity within the cells and slowing biological aging.
+
+Why freeze your cells?
+
+• Freezing cells is crucial for maintaining an adequate cell stock
+• Cell lines are valuable resources whose replacement is both expensive and time-consuming
+• Cryopreservation of finite cell lines prevents aging and transformation
+• Freezing cells in continuous culture can prevent:
+  - genetic drift
+  - senescence
+  - microbial contamination
+  - equipment failure
+
+When a small surplus of cells becomes available from subculturing, a highly effective method is to freeze them as a seed stock, keeping them protected and not available for general laboratory use. Working stocks can be prepared and replenished from these frozen seed stocks. If the seed stocks become depleted, cryopreserved working stocks can serve as a source for preparing fresh seed stock with minimal generation increase from the initial freezing.
+
+MATERIALS REQUIRED
+================================================================================
+
+We suggest using the following materials for the cell freezing protocol:
+
+• Log-phase cultured cells
+• Complete growth medium: basal medium, serum, and supplements pre-warmed to 37°C
+• Cryoprotective agent such as DMSO (use a bottle set aside for cell culture; open only in a laminar flow hood) or a freezing medium such as Synth-a-Freeze Cryopreservation Medium or Recovery Cell Culture Freezing Medium
+• Disposable, sterile 15 mL or 50 mL conical tubes
+• Reagents and equipment to determine viable and total cell counts (e.g., Countess Automated Cell Counter, or hemocytometer, cell counter, and Trypan Blue)
+• Sterile cryogenic storage vials (i.e., cryovials)
+• Controlled rate freezing apparatus or isopropanol chamber
+• Liquid nitrogen storage container
+
+For freezing adherent cells, in addition to the above materials, you will need:
+
+• Balanced salt solution such as Gibco Dulbecco's Phosphate Buffered Saline (DPBS), containing no calcium, magnesium, or phenol red
+• Dissociation reagent such as trypsin or Gibco TrypLE Express, without phenol red
+
+Catalog numbers: J66650.AK, 339650, 5000-0020, 5100-0050, 14190250, 25200072, 12604039, 15250061, 12648010, R00550, A49862
+
+MEDIUM FOR FREEZING CELLS
+================================================================================
+
+Cryoprotective agents reduce the freezing point of the medium and slow the cooling rate, greatly reducing the risk of ice crystal formation, which can damage cells and cause cell death. Media for cryopreservation typically includes a base medium, a cryopreservative, and a protein source, but we recommend that you closely follow your cell line and product-specific instructions to determine the best cryopreservation media for your experiment. When included, the cryopreservative and protein protect the cells from the stress of the freeze-thaw process. The cells are then frozen in liquid nitrogen for preservation.
+
+For media with serum, the constituents may be:
+
+• complete medium containing 10% glycerol
+• complete medium containing 10% DMSO (dimethyl sulfoxide)
+• 50% cell-conditioned medium with 50% fresh medium with 10% glycerol or 10% DMSO
+
+Safety Note: DMSO solutions are known to facilitate the entry process of organic molecules into tissues. You should always handle reagents containing DMSO using equipment and practices appropriate for the hazards posed by such materials and dispose of the reagents in compliance with local regulations.
+
+A serum-free medium has generally low or no protein; but you can still use it as a base for a cryopreservative medium in the following formulations:
+
+• 50% cell-conditioned serum-free medium with 50% fresh serum-free medium containing 7.5% DMSO
+• fresh serum-free medium containing 7.5% DMSO and 10% cell culture–grade BSA
+
+You may also use a specially formulated complete cryopreservation medium such as:
+
+• Gibco Recovery Cell Culture Freezing is a ready-to-use complete cryopreservation medium for mammalian cell cultures with an optimized ratio of fetal bovine serum to bovine serum for improved cell viability and cell recovery after thawing.
+• Gibco Synth-a-Freeze Cryopreservation Medium is a chemically defined, protein-free, sterile cryopreservation medium with 10% DMSO that is suitable for the cryopreservation of many stem and primary cell types apart from melanocytes.
+
+PROTOCOL
+================================================================================
+
+The proper way to freeze cells and cryopreserve your cell lines for future use requires diligent attention to passaging procedures and storage requirements. Remember to always wear personal protective equipment and use proper sterile technique when freezing cells.
+
+The general freezing method is the same for adherent and suspension cells, except that adherent cells need to be removed from the culture plates before starting the freezing procedure. The following cell freezing protocol is a general procedure for cryopreserving cultured cells. Optimal freezing conditions depend on the cell line in use—for detailed protocols, always refer to the cell-specific product insert.
+
+Prior to cryopreservation, cells should be characterized and checked for contamination. Freeze cells in log phase, at a high concentration of at least 90% viability, and at as low a passage number as possible, as this will lead to the best outcomes when your stock is thawed.
+
+1. Prepare freezing medium and store at 2° to 8°C until use.
+
+2. For adherent cells, gently detach cells from the tissue culture vessel following the procedure used during subculture. Detach as gently as possible to minimize damage to the cells.
+
+3. Resuspend the detached cells in the complete growth medium.
+
+4. Find the total number of cells and percent viability using a hemocytometer or the Countess Automated Cell Counter and Trypan Blue exclusion.
+
+5. According to the desired viable cell density, calculate the required volume of freezing medium.
+
+6. Centrifuge the cell suspension at approximately 100–400 × g for 5 to 10 minutes (centrifugation speed and duration varies depending on the cell type). Using a pipette, aseptically withdraw the supernatant to the smallest volume without disturbing the cell pellet and discard.
+
+7. Resuspend the cell pellet in cold freezing medium at the recommended viable cell density for the specific cell type.
+
+8. Dispense aliquots of the cell suspension into sterile cryogenic storage vials. As you aliquot them, gently and often mix the cells to maintain a homogeneous cell suspension.
+
+9. Freeze the cells slowly by reducing the temperature at approximately 1°C per minute using a controlled rate cryo-freezer or a cryo-freezing container such as "Mr. Frosty," available from Thermo Scientific Nalgene labware (Nalgene Nunc). Alternatively, place the cryovials containing the cells in an isopropanol chamber and store them at –80°C overnight.
+
+10. Transfer frozen cells to liquid nitrogen and store them in the gas phase above the liquid nitrogen below –135°C.
+
+Safety Note: Biohazardous materials must be stored in the gas phase above the liquid nitrogen. Storing the sealed cryovials in the gas phase reduces the risk of explosion. If you are using liquid-phase storage, be aware of the explosion hazard with both glass and plastic cryovials and always wear a face shield or goggles.
+
+REFERENCES
+================================================================================
+
+Freshney, R. (1987) Culture of Animal Cells: A Manual of Basic Technique, p. 220, Alan R. Liss, Inc., New York.
+
+Mohamed, H. M., Sundar, P., Ridwan, N. A. A., Cheong, A. J., Mohamad Salleh, N. A., Sulaiman, N., Mh Busra, F., & Maarof, M. (2024). Optimisation of cryopreservation conditions, including storage duration and revival methods, for the viability of human primary cells. BMC Molecular & Cell Biology, 25(1), 1–14. https://doi.org/10.1186/s12860-024-00516-6.

Biomni/biomni/tool/synthetic_biology.py

@@ -0,0 +1,1351 @@
+def engineer_bacterial_genome_for_therapeutic_delivery(bacterial_genome_file, genetic_parts):
+    """Engineer a bacterial genome by integrating therapeutic genetic parts for therapeutic delivery.
+
+    Parameters
+    ----------
+    bacterial_genome_file : str
+        Path to the file containing the bacterial genome sequence in FASTA format
+    genetic_parts : dict
+        Dictionary containing genetic parts to be integrated::
+
+        {
+            'promoters': list of dict with 'name', 'sequence', and 'position',
+            'genes': list of dict with 'name', 'sequence', and 'position',
+            'terminators': list of dict with 'name', 'sequence', and 'position',
+            'cargo': dict with 'name' and 'sequence' of the therapeutic cargo
+        }
+
+    Returns
+    -------
+    str
+        Research log summarizing the engineering process, including the filename of the
+        engineered genome and plasmid map
+
+    """
+    import datetime
+
+    from Bio import SeqIO
+    from Bio.Graphics import GenomeDiagram
+    from Bio.Seq import Seq
+    from Bio.SeqFeature import FeatureLocation, SeqFeature
+    from Bio.SeqRecord import SeqRecord
+    from reportlab.lib import colors
+
+    # Initialize research log
+    log = ["# Bacterial Genome Engineering for Therapeutic Delivery\n"]
+    log.append(f"Date: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+
+    # Step 1: Load the bacterial genome
+    log.append("## Step 1: Loading Bacterial Genome")
+    try:
+        genome_record = SeqIO.read(bacterial_genome_file, "fasta")
+        genome_seq = genome_record.seq
+        log.append(f"Successfully loaded genome: {genome_record.id}")
+        log.append(f"Genome length: {len(genome_seq)} bp\n")
+    except Exception as e:
+        log.append(f"Error loading genome: {str(e)}")
+        return "\n".join(log)
+
+    # Step 2: Design and integrate genetic parts
+    log.append("## Step 2: Integrating Genetic Parts")
+
+    # Create a new genome sequence for modifications
+    # In newer BioPython versions, Seq objects are mutable by default
+    # or we can convert to a string and modify it, then convert back to Seq
+    engineered_seq = str(genome_seq)
+
+    # Track features for visualization
+    features = []
+
+    # Keep track of position adjustments as we add sequences
+    position_adjustment = 0
+
+    # Add promoters
+    if "promoters" in genetic_parts:
+        log.append("### Adding Promoters:")
+        for promoter in genetic_parts["promoters"]:
+            position = promoter["position"] + position_adjustment
+
+            # Insert the sequence at the position
+            engineered_seq = engineered_seq[:position] + promoter["sequence"] + engineered_seq[position:]
+            position_adjustment += len(promoter["sequence"])
+
+            # Adjust positions of subsequent elements
+            for part_type in ["genes", "terminators"]:
+                if part_type in genetic_parts:
+                    for part in genetic_parts[part_type]:
+                        if part["position"] > promoter["position"]:
+                            part["position"] += len(promoter["sequence"])
+
+            # Add feature for visualization
+            feature = SeqFeature(
+                FeatureLocation(position, position + len(promoter["sequence"])),
+                type="promoter",
+                qualifiers={"label": promoter["name"]},
+            )
+            features.append(feature)
+
+            log.append(f"  - Added promoter {promoter['name']} at position {position}")
+
+    # Add genes
+    if "genes" in genetic_parts:
+        log.append("### Adding Genes:")
+        for gene in genetic_parts["genes"]:
+            position = gene["position"] + position_adjustment
+
+            # Insert the sequence at the position
+            engineered_seq = engineered_seq[:position] + gene["sequence"] + engineered_seq[position:]
+            position_adjustment += len(gene["sequence"])
+
+            # Adjust positions of subsequent elements
+            for part_type in ["terminators"]:
+                if part_type in genetic_parts:
+                    for part in genetic_parts[part_type]:
+                        if part["position"] > gene["position"]:
+                            part["position"] += len(gene["sequence"])
+
+            # Add feature for visualization
+            feature = SeqFeature(
+                FeatureLocation(position, position + len(gene["sequence"])),
+                type="gene",
+                qualifiers={"label": gene["name"]},
+            )
+            features.append(feature)
+
+            log.append(f"  - Added gene {gene['name']} at position {position}")
+
+    # Add terminators
+    if "terminators" in genetic_parts:
+        log.append("### Adding Terminators:")
+        for terminator in genetic_parts["terminators"]:
+            position = terminator["position"] + position_adjustment
+
+            # Insert the sequence at the position
+            engineered_seq = engineered_seq[:position] + terminator["sequence"] + engineered_seq[position:]
+            position_adjustment += len(terminator["sequence"])
+
+            # Add feature for visualization
+            feature = SeqFeature(
+                FeatureLocation(position, position + len(terminator["sequence"])),
+                type="terminator",
+                qualifiers={"label": terminator["name"]},
+            )
+            features.append(feature)
+
+            log.append(f"  - Added terminator {terminator['name']} at position {position}")
+
+    # Add therapeutic cargo
+    if "cargo" in genetic_parts:
+        cargo = genetic_parts["cargo"]
+        # Find a suitable position (after the last added element)
+        position = max([f.location.end for f in features]) if features else len(engineered_seq) // 2
+
+        # Insert the sequence at the position
+        engineered_seq = engineered_seq[:position] + cargo["sequence"] + engineered_seq[position:]
+
+        # Add feature for visualization
+        feature = SeqFeature(
+            FeatureLocation(position, position + len(cargo["sequence"])),
+            type="therapeutic_cargo",
+            qualifiers={"label": cargo["name"]},
+        )
+        features.append(feature)
+
+        log.append("### Added Therapeutic Cargo:")
+        log.append(f"  - Added {cargo['name']} at position {position}")
+        log.append(f"  - Cargo length: {len(cargo['sequence'])} bp\n")
+
+    # Step 3: Create the engineered genome record
+    log.append("## Step 3: Finalizing Engineered Genome")
+    engineered_genome = SeqRecord(
+        seq=Seq(engineered_seq),
+        id=f"{genome_record.id}_engineered",
+        name=f"{genome_record.id}_engineered",
+        description=f"Engineered {genome_record.id} for therapeutic delivery",
+    )
+
+    # Add all features to the engineered genome
+    engineered_genome.features = features
+
+    # Save the engineered genome to a file
+    output_genome_file = f"{genome_record.id}_engineered.fasta"
+    SeqIO.write(engineered_genome, output_genome_file, "fasta")
+    log.append(f"Engineered genome saved to: {output_genome_file}")
+    log.append(f"Total genome length: {len(engineered_genome.seq)} bp\n")
+
+    # Step 4: Generate a plasmid map
+    log.append("## Step 4: Generating Plasmid Map")
+
+    # Create the diagram
+    gd_diagram = GenomeDiagram.Diagram("Engineered Bacterial Genome")
+    gd_track = gd_diagram.new_track(1, name="Engineered Features")
+    gd_feature_set = gd_track.new_set()
+
+    # Add features with different colors
+    for feature in features:
+        if feature.type == "promoter":
+            color = colors.green
+        elif feature.type == "gene":
+            color = colors.blue
+        elif feature.type == "terminator":
+            color = colors.red
+        elif feature.type == "therapeutic_cargo":
+            color = colors.purple
+        else:
+            color = colors.grey
+
+        gd_feature_set.add_feature(feature, color=color, label=True)
+
+    # Draw and save the plasmid map
+    plasmid_map_file = f"{genome_record.id}_engineered_map.pdf"
+    gd_diagram.draw(format="circular", circular=True, pagesize=(1000, 1000))
+    gd_diagram.write(plasmid_map_file, "PDF")
+
+    log.append(f"Plasmid map generated and saved to: {plasmid_map_file}\n")
+
+    # Step 5: Final summary
+    log.append("## Summary of Engineered Bacterial Strain")
+    log.append(f"- Base strain: {genome_record.id}")
+    log.append("- Added genetic parts:")
+
+    if "promoters" in genetic_parts:
+        log.append(f"  - Promoters: {len(genetic_parts['promoters'])}")
+    if "genes" in genetic_parts:
+        log.append(f"  - Genes: {len(genetic_parts['genes'])}")
+    if "terminators" in genetic_parts:
+        log.append(f"  - Terminators: {len(genetic_parts['terminators'])}")
+    if "cargo" in genetic_parts:
+        log.append(f"  - Therapeutic cargo: {genetic_parts['cargo']['name']}")
+
+    log.append("\nThe engineered bacterial strain is ready for transformation and selection.")
+
+    return "\n".join(log)
+
+
+def analyze_bacterial_growth_rate(time_points, od_measurements, strain_name="Unknown strain", output_dir="./"):
+    """Analyze bacterial growth data and extract growth parameters from OD600 measurements.
+
+    Parameters
+    ----------
+    time_points : list or numpy.ndarray
+        Time points at which OD600 measurements were taken (in hours)
+    od_measurements : list or numpy.ndarray
+        Optical density (OD600) measurements corresponding to each time point
+    strain_name : str, optional
+        Name of the bacterial strain being analyzed, default is "Unknown strain"
+    output_dir : str, optional
+        Directory where to save the output files, default is current directory
+
+    Returns
+    -------
+    str
+        A research log summarizing the analysis steps, fitted parameters, and results
+
+    """
+    import os
+    from datetime import datetime
+
+    import matplotlib
+
+    matplotlib.use("Agg")  # Use non-interactive backend
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from scipy.optimize import curve_fit
+
+    # Ensure output directory exists
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Convert inputs to numpy arrays if they aren't already
+    time_points = np.array(time_points)
+    od_measurements = np.array(od_measurements)
+
+    # Define the Gompertz growth model function
+    def gompertz_model(t, lag, mu_max, A):
+        """Gompertz growth model.
+
+        Parameters
+        ----------
+        t: time points
+        lag: lag time (hours)
+        mu_max: maximum growth rate (per hour)
+        A: carrying capacity (maximum OD)
+
+        """
+        return A * np.exp(-np.exp(mu_max * np.exp(1) * (lag - t) / A + 1))
+
+    # Initial parameter guesses
+    p0 = [
+        np.mean(time_points) / 3,  # lag time guess: 1/3 of the mean time
+        0.5,  # growth rate guess: 0.5 per hour
+        max(od_measurements) * 1.1,  # carrying capacity: slightly above max OD
+    ]
+
+    # Fit the model to the data
+    try:
+        popt, pcov = curve_fit(
+            gompertz_model,
+            time_points,
+            od_measurements,
+            p0=p0,
+            bounds=([0, 0, 0], [np.inf, np.inf, np.inf]),
+        )
+        lag_time, mu_max, carrying_capacity = popt
+
+        # Calculate doubling time (ln(2)/μ)
+        doubling_time = np.log(2) / mu_max
+
+        # Generate fitted curve for plotting
+        t_smooth = np.linspace(min(time_points), max(time_points), 100)
+        od_fit = gompertz_model(t_smooth, *popt)
+
+        # Create growth curve plot
+        plt.figure(figsize=(10, 6))
+        plt.scatter(time_points, od_measurements, label="Observed OD600")
+        plt.plot(t_smooth, od_fit, "r-", label="Fitted Gompertz model")
+        plt.xlabel("Time (hours)")
+        plt.ylabel("Optical Density (OD600)")
+        plt.title(f"Bacterial Growth Curve: {strain_name}")
+        plt.legend()
+        plt.grid(True, linestyle="--", alpha=0.7)
+
+        # Save the plot
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        plot_filename = os.path.join(output_dir, f"{strain_name.replace(' ', '_')}_{timestamp}_growth_curve.png")
+        plt.savefig(plot_filename)
+        plt.close()
+
+        # Create research log
+        log = f"""## Bacterial Growth Rate Analysis: {strain_name}
+
+### Analysis Summary
+- **Date and Time:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+- **Sample:** {strain_name}
+- **Data Points:** {len(time_points)} measurements over {max(time_points) - min(time_points):.2f} hours
+
+### Growth Parameters (Gompertz Model)
+- **Lag Phase Duration:** {lag_time:.2f} hours
+- **Maximum Growth Rate (μ_max):** {mu_max:.4f} per hour
+- **Doubling Time:** {doubling_time:.2f} hours
+- **Carrying Capacity (max OD):** {carrying_capacity:.4f} OD600 units
+
+### Methods
+1. OD600 measurements were taken at various time points
+2. Data was fitted to the Gompertz growth model
+3. Growth parameters were extracted from the fitted model
+4. Growth curve was plotted and saved as: {plot_filename}
+
+### Note
+The Gompertz model provides a good representation of bacterial growth phases including lag, exponential, and stationary phases.
+"""
+
+        return log
+
+    except RuntimeError as e:
+        return f"""## Bacterial Growth Rate Analysis: {strain_name}
+
+### Error in Analysis
+Failed to fit the growth model to the provided data: {str(e)}
+
+### Suggestions
+- Check if the data shows a typical growth pattern
+- Ensure sufficient data points are provided
+- Try different initial parameter guesses or a different growth model
+"""
+
+
+def analyze_barcode_sequencing_data(
+    input_file,
+    barcode_pattern=None,
+    flanking_seq_5prime=None,
+    flanking_seq_3prime=None,
+    min_count=5,
+    output_dir="./results",
+):
+    """Analyze sequencing data to extract, quantify and determine lineage relationships of barcodes.
+
+    Parameters
+    ----------
+    input_file : str
+        Path to the input sequencing file in FASTQ or FASTA format
+    barcode_pattern : str, optional
+        Regular expression pattern to identify barcodes. If None, will use flanking sequences
+    flanking_seq_5prime : str, optional
+        5' flanking sequence of the barcode region
+    flanking_seq_3prime : str, optional
+        3' flanking sequence of the barcode region
+    min_count : int, default=5
+        Minimum count threshold for considering a barcode
+    output_dir : str, default="./results"
+        Directory to save output files
+
+    Returns
+    -------
+    str
+        Research log summarizing the analysis steps and results
+
+    """
+    import os
+    import re
+    from collections import Counter
+
+    import numpy as np
+    from Bio import SeqIO
+    from scipy.cluster.hierarchy import fcluster, linkage
+    from scipy.spatial.distance import pdist
+
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Initialize research log
+    log = "# Barcode Sequencing Analysis Research Log\n\n"
+    log += f"## Input Data\n- File: {input_file}\n\n"
+
+    # Step 1: Read sequences and extract barcodes
+    log += "## Step 1: Extracting barcodes from sequencing data\n"
+
+    # Determine file format based on extension
+    file_format = "fastq" if input_file.endswith((".fastq", ".fq")) else "fasta"
+
+    barcodes = []
+    total_reads = 0
+
+    for record in SeqIO.parse(input_file, file_format):
+        total_reads += 1
+        seq_str = str(record.seq)
+
+        # Extract barcode using pattern or flanking sequences
+        if barcode_pattern:
+            match = re.search(barcode_pattern, seq_str)
+            if match:
+                barcodes.append(match.group(0))
+        elif flanking_seq_5prime and flanking_seq_3prime:
+            pattern = f"{flanking_seq_5prime}(.*?){flanking_seq_3prime}"
+            match = re.search(pattern, seq_str)
+            if match:
+                barcodes.append(match.group(1))
+
+    log += f"- Total reads processed: {total_reads}\n"
+    log += f"- Barcodes extracted: {len(barcodes)}\n\n"
+
+    if len(barcodes) == 0:
+        log += "ERROR: No barcodes found. Check your barcode pattern or flanking sequences.\n"
+        return log
+
+    # Step 2: Quantify barcode abundances
+    log += "## Step 2: Quantifying barcode abundances\n"
+    barcode_counts = Counter(barcodes)
+
+    # Filter low-abundance barcodes
+    filtered_barcodes = {bc: count for bc, count in barcode_counts.items() if count >= min_count}
+
+    log += f"- Unique barcodes: {len(barcode_counts)}\n"
+    log += f"- Barcodes with count ≥ {min_count}: {len(filtered_barcodes)}\n"
+
+    # Save barcode counts to file
+    count_file = os.path.join(output_dir, "barcode_counts.tsv")
+    with open(count_file, "w") as f:
+        f.write("Barcode\tCount\tFrequency\n")
+        for bc, count in sorted(filtered_barcodes.items(), key=lambda x: x[1], reverse=True):
+            freq = count / total_reads
+            f.write(f"{bc}\t{count}\t{freq:.6f}\n")
+
+    log += f"- Barcode abundances saved to: {count_file}\n\n"
+
+    # Step 3: Analyze barcode relationships (lineage analysis)
+    log += "## Step 3: Analyzing barcode relationships and lineages\n"
+
+    # Only proceed if we have enough barcodes
+    if len(filtered_barcodes) < 2:
+        log += "- Not enough barcodes for lineage analysis after filtering\n\n"
+    else:
+        # Convert barcodes to numerical representation for distance calculation
+        barcode_list = list(filtered_barcodes.keys())
+
+        # Create a simple distance matrix based on Hamming distance
+        def hamming_distance(s1, s2):
+            # If sequences have different lengths, pad the shorter one
+            if len(s1) != len(s2):
+                max_len = max(len(s1), len(s2))
+                s1 = s1.ljust(max_len)
+                s2 = s2.ljust(max_len)
+            return sum(c1 != c2 for c1, c2 in zip(s1, s2, strict=False))
+
+        # Create distance matrix
+        n = len(barcode_list)
+        dist_matrix = np.zeros((n, n))
+        for i in range(n):
+            for j in range(i + 1, n):
+                dist = hamming_distance(barcode_list[i], barcode_list[j])
+                dist_matrix[i, j] = dist
+                dist_matrix[j, i] = dist
+
+        # Perform hierarchical clustering
+        try:
+            condensed_dist = pdist(dist_matrix)
+            Z = linkage(condensed_dist, method="average")
+            max_dist = 3  # Max Hamming distance to consider barcodes in same lineage
+            clusters = fcluster(Z, max_dist, criterion="distance")
+
+            # Count clusters
+            cluster_counts = Counter(clusters)
+
+            log += f"- Identified {len(cluster_counts)} potential lineages\n"
+            log += f"- Largest lineage contains {max(cluster_counts.values())} barcodes\n"
+
+            # Save lineage information
+            lineage_file = os.path.join(output_dir, "barcode_lineages.tsv")
+            with open(lineage_file, "w") as f:
+                f.write("Barcode\tCount\tLineage\n")
+                for i, bc in enumerate(barcode_list):
+                    f.write(f"{bc}\t{filtered_barcodes[bc]}\t{clusters[i]}\n")
+
+            log += f"- Lineage assignments saved to: {lineage_file}\n\n"
+        except Exception as e:
+            log += f"- Error in lineage analysis: {str(e)}\n\n"
+
+    # Step 4: Summary
+    log += "## Summary\n"
+    log += f"- Processed {total_reads} sequencing reads\n"
+    log += f"- Identified {len(barcode_counts)} unique barcodes\n"
+    log += f"- {len(filtered_barcodes)} barcodes passed abundance threshold (≥ {min_count})\n"
+
+    return log
+
+
+def analyze_bifurcation_diagram(time_series_data, parameter_values, system_name="Dynamical System", output_dir="./"):
+    """Performs bifurcation analysis on a dynamical system and generates a bifurcation diagram.
+
+    Parameters
+    ----------
+    time_series_data : numpy.ndarray
+        A 2D array where each row represents a time series for a specific parameter value.
+        Shape should be (n_parameter_values, n_time_points).
+    parameter_values : numpy.ndarray
+        1D array of parameter values corresponding to each time series.
+        Shape should be (n_parameter_values,).
+    system_name : str, optional
+        Name of the dynamical system being analyzed, used for plot titles.
+    output_dir : str, optional
+        Directory to save the output files.
+
+    Returns
+    -------
+    str
+        Research log summarizing the bifurcation analysis process and results.
+
+    """
+    import os
+
+    import matplotlib
+
+    matplotlib.use("Agg")  # Use non-interactive backend
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from scipy.signal import find_peaks
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Initialize research log
+    research_log = f"# Bifurcation Analysis for {system_name}\n\n"
+    research_log += "## Analysis Steps\n\n"
+
+    # Step 1: Verify input data
+    research_log += "### Step 1: Data Verification\n"
+    if len(parameter_values) != time_series_data.shape[0]:
+        research_log += "Error: Number of parameter values does not match number of time series.\n"
+        return research_log
+
+    research_log += f"- Analyzed {len(parameter_values)} parameter values\n"
+    research_log += f"- Each time series contains {time_series_data.shape[1]} data points\n\n"
+
+    # Step 2: Calculate indicators for different dynamical regimes
+    research_log += "### Step 2: Calculating Dynamical Indicators\n"
+
+    # Initialize arrays to store results
+    local_maxima_counts = np.zeros(len(parameter_values))
+    lyapunov_estimates = np.zeros(len(parameter_values))
+    attractor_points = []
+
+    for i, series in enumerate(time_series_data):
+        # Use the last 70% of the time series to avoid transients
+        steady_state = series[int(0.7 * len(series)) :]
+
+        # Find local maxima (peaks) to identify periodicity
+        peaks, _ = find_peaks(steady_state)
+        local_maxima_counts[i] = len(peaks)
+
+        # Simple estimate of the largest Lyapunov exponent
+        # Positive values suggest chaos, negative values suggest stability
+        if len(steady_state) > 10:
+            diffs = np.abs(np.diff(steady_state))
+            if np.mean(diffs) > 0:
+                lyapunov_estimates[i] = np.log(np.mean(diffs))
+            else:
+                lyapunov_estimates[i] = -1.0  # Stable behavior
+
+        # Collect points for the bifurcation diagram
+        # We use local maxima as sampling points for the attractor
+        if len(peaks) > 0:
+            attractor_points.append((parameter_values[i], steady_state[peaks]))
+        else:
+            # If no peaks, use the last few points
+            attractor_points.append((parameter_values[i], steady_state[-5:]))
+
+    research_log += "- Calculated approximate Lyapunov exponents\n"
+    research_log += "- Identified local maxima for periodicity analysis\n"
+    research_log += "- Sampled attractor points for bifurcation diagram\n\n"
+
+    # Step 3: Classify dynamical regimes
+    research_log += "### Step 3: Classifying Dynamical Regimes\n"
+
+    # Initialize arrays for regime classification
+    regimes = np.full(len(parameter_values), "unknown", dtype=object)
+
+    # Classify based on Lyapunov exponent and periodicity
+    for i in range(len(parameter_values)):
+        if lyapunov_estimates[i] > 0.05:
+            regimes[i] = "chaotic"
+        elif local_maxima_counts[i] == 0:
+            regimes[i] = "stable"
+        elif local_maxima_counts[i] == 1:
+            regimes[i] = "period-1"
+        elif local_maxima_counts[i] == 2:
+            regimes[i] = "period-2"
+        elif local_maxima_counts[i] == 4:
+            regimes[i] = "period-4"
+        elif local_maxima_counts[i] > 4:
+            if lyapunov_estimates[i] > 0:
+                regimes[i] = "chaotic"
+            else:
+                regimes[i] = f"period-{int(local_maxima_counts[i])}"
+
+    # Count regime types
+    unique_regimes = np.unique(regimes)
+    for regime in unique_regimes:
+        count = np.sum(regimes == regime)
+        research_log += f"- Identified {count} parameter values in '{regime}' regime\n"
+
+    research_log += "\n"
+
+    # Step 4: Create bifurcation diagram
+    research_log += "### Step 4: Creating Bifurcation Diagram\n"
+
+    plt.figure(figsize=(12, 8))
+
+    # Plot bifurcation points
+    for param_val, points in attractor_points:
+        y_values = points.flatten()  # Flatten in case points is multi-dimensional
+        plt.plot([param_val] * len(y_values), y_values, "k.", markersize=0.5)
+
+    # Highlight different regimes with colored background
+    regime_changes = np.where(regimes[:-1] != regimes[1:])[0]
+    regime_boundaries = (
+        [parameter_values[0]] + [parameter_values[i + 1] for i in regime_changes] + [parameter_values[-1]]
+    )
+
+    colors = {
+        "stable": "lightblue",
+        "period-1": "lightgreen",
+        "period-2": "lightyellow",
+        "period-4": "lightpink",
+        "chaotic": "salmon",
+    }
+
+    for i in range(len(regime_boundaries) - 1):
+        start_idx = list(parameter_values).index(regime_boundaries[i])
+        regime = regimes[start_idx]
+        if regime in colors:
+            plt.axvspan(
+                regime_boundaries[i],
+                regime_boundaries[i + 1],
+                alpha=0.3,
+                color=colors.get(regime, "lightgray"),
+            )
+
+    plt.xlabel("Parameter Value")
+    plt.ylabel("State Variable")
+    plt.title(f"Bifurcation Diagram for {system_name}")
+
+    # Add legend for regimes
+    from matplotlib.patches import Patch
+
+    legend_elements = [
+        Patch(facecolor=colors.get(regime, "lightgray"), alpha=0.3, label=regime)
+        for regime in unique_regimes
+        if regime in colors
+    ]
+    plt.legend(handles=legend_elements, loc="upper right")
+
+    # Save the figure
+    output_file = os.path.join(output_dir, f"{system_name.replace(' ', '_')}_bifurcation_diagram.png")
+    plt.savefig(output_file, dpi=300)
+    plt.close()
+
+    research_log += "- Created bifurcation diagram showing different dynamical regimes\n"
+    research_log += f"- Diagram saved as: {output_file}\n\n"
+
+    # Step 5: Identify regime transitions
+    research_log += "### Step 5: Identifying Regime Transitions\n"
+
+    if len(regime_changes) > 0:
+        for i in regime_changes:
+            research_log += f"- Transition from '{regimes[i]}' to '{regimes[i + 1]}' at parameter value ≈ {parameter_values[i + 1]:.4f}\n"
+    else:
+        research_log += "- No regime transitions detected in the parameter range\n"
+
+    research_log += "\n### Summary\n"
+    research_log += f"Bifurcation analysis completed for {system_name}. "
+    research_log += f"The system exhibits {len(unique_regimes)} different dynamical regimes "
+    research_log += f"across the parameter range [{parameter_values[0]:.4f}, {parameter_values[-1]:.4f}].\n"
+
+    return research_log
+
+
+def create_biochemical_network_sbml_model(reaction_network, kinetic_parameters, output_file="biochemical_model.xml"):
+    """Generate a mathematical model of a biochemical network in SBML format.
+
+    Parameters
+    ----------
+    reaction_network : list of dict
+        List of dictionaries, each representing a reaction with keys:
+        - 'id': Reaction identifier
+        - 'name': Reaction name
+        - 'reactants': Dict of reactant species IDs and their stoichiometry
+        - 'products': Dict of product species IDs and their stoichiometry
+        - 'reversible': Boolean indicating if reaction is reversible
+
+    kinetic_parameters : dict
+        Dictionary mapping reaction IDs to their kinetic law parameters.
+        Each entry should contain:
+        - 'law_type': Type of kinetic law (e.g., 'mass_action', 'michaelis_menten')
+        - 'parameters': Dict of parameter names and values
+
+    output_file : str, optional
+        File path to save the SBML model (default: "biochemical_model.xml")
+
+    Returns
+    -------
+    str
+        Research log summarizing the model creation process
+
+    """
+    import os
+
+    import libsbml
+
+    log = "# Biochemical Network SBML Model Creation Log\n\n"
+
+    # Step 1: Create an SBML document
+    log += "## Step 1: Creating SBML document\n"
+    sbml_ns = libsbml.SBMLNamespaces(3, 2)  # SBML Level 3 Version 2
+    document = libsbml.SBMLDocument(sbml_ns)
+    model = document.createModel()
+    model.setId("biochemical_network_model")
+    model.setName("Biochemical Network Model")
+    log += "- Created SBML Level 3 Version 2 document\n"
+    log += "- Created model with ID 'biochemical_network_model'\n\n"
+
+    # Step 2: Create default compartment
+    log += "## Step 2: Creating default compartment\n"
+    compartment = model.createCompartment()
+    compartment.setId("default")
+    compartment.setConstant(True)
+    compartment.setSize(1.0)
+    compartment.setSpatialDimensions(3)
+    log += "- Created default compartment\n\n"
+
+    # Step 3: Create species
+    log += "## Step 3: Creating species\n"
+    species_set = set()
+
+    # Collect all unique species from reactions
+    for reaction in reaction_network:
+        for species_id in list(reaction["reactants"].keys()) + list(reaction["products"].keys()):
+            species_set.add(species_id)
+
+    # Create species in the model
+    for species_id in species_set:
+        species = model.createSpecies()
+        species.setId(species_id)
+        species.setCompartment("default")
+        species.setInitialConcentration(0.0)  # Default initial concentration
+        species.setHasOnlySubstanceUnits(False)
+        species.setBoundaryCondition(False)
+        species.setConstant(False)
+        log += f"- Created species '{species_id}'\n"
+    log += "\n"
+
+    # Step 4: Create reactions
+    log += "## Step 4: Creating reactions and kinetic laws\n"
+    for reaction_data in reaction_network:
+        reaction = model.createReaction()
+        reaction.setId(reaction_data["id"])
+        reaction.setName(reaction_data["name"])
+        reaction.setReversible(reaction_data["reversible"])
+        reaction.setFast(False)
+
+        # Add reactants
+        for reactant_id, stoichiometry in reaction_data["reactants"].items():
+            species_ref = reaction.createReactant()
+            species_ref.setSpecies(reactant_id)
+            species_ref.setStoichiometry(stoichiometry)
+            species_ref.setConstant(True)
+
+        # Add products
+        for product_id, stoichiometry in reaction_data["products"].items():
+            species_ref = reaction.createProduct()
+            species_ref.setSpecies(product_id)
+            species_ref.setStoichiometry(stoichiometry)
+            species_ref.setConstant(True)
+
+        # Create kinetic law
+        if reaction_data["id"] in kinetic_parameters:
+            kinetic_data = kinetic_parameters[reaction_data["id"]]
+            kinetic_law = reaction.createKineticLaw()
+
+            # Add parameters to kinetic law
+            for param_name, param_value in kinetic_data["parameters"].items():
+                parameter = kinetic_law.createParameter()
+                parameter.setId(param_name)
+                parameter.setValue(param_value)
+
+            # Set the appropriate formula based on the law type
+            if kinetic_data["law_type"] == "mass_action":
+                # Simple mass action kinetics
+                reactants_formula = " * ".join([f"{reactant_id}" for reactant_id in reaction_data["reactants"]])
+                formula = f"k * {reactants_formula}" if reactants_formula else "k"
+                kinetic_law.setMath(libsbml.parseL3Formula(formula))
+            elif kinetic_data["law_type"] == "michaelis_menten":
+                # Michaelis-Menten kinetics (assuming single substrate)
+                substrate = list(reaction_data["reactants"].keys())[0] if reaction_data["reactants"] else "S"
+                formula = f"Vmax * {substrate} / (Km + {substrate})"
+                kinetic_law.setMath(libsbml.parseL3Formula(formula))
+            # Custom formula provided in the parameters
+            elif "formula" in kinetic_data:
+                kinetic_law.setMath(libsbml.parseL3Formula(kinetic_data["formula"]))
+
+        log += f"- Created reaction '{reaction_data['id']}' ({reaction_data['name']})\n"
+        if reaction_data["id"] in kinetic_parameters:
+            log += f"  - Added kinetic law of type '{kinetic_parameters[reaction_data['id']]['law_type']}'\n"
+    log += "\n"
+
+    # Step 5: Validate the model
+    log += "## Step 5: Validating the SBML model\n"
+    document.setConsistencyChecks(libsbml.LIBSBML_CAT_UNITS_CONSISTENCY, False)
+    consistent = document.checkConsistency()
+    if consistent == 0:
+        log += "- Model passed consistency check\n"
+    else:
+        log += "- Model has consistency issues:\n"
+        for i in range(document.getNumErrors()):
+            error = document.getError(i)
+            log += f"  - {error.getMessage()}\n"
+    log += "\n"
+
+    # Step 6: Write model to file
+    log += "## Step 6: Saving the SBML model\n"
+    libsbml.writeSBMLToFile(document, output_file)
+    log += f"- Model saved to '{os.path.abspath(output_file)}'\n\n"
+
+    # Step 7: Summary
+    log += "## Summary\n"
+    log += f"- Created SBML model with {len(species_set)} species and {len(reaction_network)} reactions\n"
+    log += f"- Model saved as '{output_file}'\n"
+
+    return log
+
+
+def optimize_codons_for_heterologous_expression(target_sequence, host_codon_usage):
+    """Analyzes and optimizes a DNA/RNA sequence for improved expression in a heterologous host organism.
+
+    Parameters
+    ----------
+    target_sequence : str
+        The DNA or RNA sequence of the target gene to be optimized.
+        Should contain complete codons (length divisible by 3).
+
+    host_codon_usage : dict
+        Dictionary mapping codons to their usage frequency in the host organism.
+        Format: {'AUG': 0.8, 'GCC': 0.6, ...} or {'ATG': 0.8, 'GCC': 0.6, ...}
+
+    Returns
+    -------
+    str
+        A research log summarizing the optimization process and results.
+
+    """
+    from Bio.Data import CodonTable
+
+    # Initialize research log
+    log = "# Codon Optimization Analysis Research Log\n\n"
+
+    # Check if sequence is DNA or RNA and standardize to DNA
+    is_rna = "U" in target_sequence
+    working_seq = target_sequence.replace("U", "T") if is_rna else target_sequence
+
+    log += "## Input Sequence Analysis\n"
+    log += f"- Sequence type: {'RNA' if is_rna else 'DNA'}\n"
+    log += f"- Sequence length: {len(working_seq)} nucleotides\n"
+
+    # Verify sequence length is divisible by 3
+    if len(working_seq) % 3 != 0:
+        log += (
+            f"- WARNING: Sequence length ({len(working_seq)}) is not divisible by 3. Optimization may be incomplete.\n"
+        )
+
+    # Extract codons from the sequence
+    original_codons = [working_seq[i : i + 3] for i in range(0, len(working_seq), 3)]
+    log += f"- Number of codons: {len(original_codons)}\n\n"
+
+    # Get standard genetic code
+    standard_table = CodonTable.standard_dna_table
+
+    # Create codon to amino acid mapping
+    codon_to_aa = {}
+    for codon, amino_acid in standard_table.forward_table.items():
+        codon_to_aa[codon] = amino_acid
+
+    # Add stop codons
+    for stop_codon in standard_table.stop_codons:
+        codon_to_aa[stop_codon] = "*"  # * represents stop codon
+
+    # Create amino acid to codon mapping with host frequencies
+    aa_to_codons = {}
+    for codon, aa in codon_to_aa.items():
+        if aa not in aa_to_codons:
+            aa_to_codons[aa] = []
+        # Use host frequency or default to 0 if not provided
+        frequency = host_codon_usage.get(codon, 0)
+        aa_to_codons[aa].append((codon, frequency))
+
+    # Sort codons by frequency for each amino acid
+    for aa in aa_to_codons:
+        aa_to_codons[aa] = sorted(aa_to_codons[aa], key=lambda x: x[1], reverse=True)
+
+    # Optimize codons
+    optimized_codons = []
+    for codon in original_codons:
+        try:
+            aa = codon_to_aa[codon]
+            # Select the highest frequency codon for this amino acid
+            best_codon = aa_to_codons[aa][0][0] if aa_to_codons[aa] else codon
+            optimized_codons.append(best_codon)
+        except KeyError:
+            # If codon not in standard table, keep original
+            optimized_codons.append(codon)
+            log += f"- WARNING: Non-standard codon detected: {codon}. Keeping original.\n"
+
+    # Combine optimized codons into sequence
+    optimized_sequence = "".join(optimized_codons)
+
+    # Convert back to RNA if input was RNA
+    if is_rna:
+        optimized_sequence = optimized_sequence.replace("T", "U")
+
+    # Calculate optimization statistics
+    codon_changes = sum(1 for i, j in zip(original_codons, optimized_codons, strict=False) if i != j)
+    percent_changed = (codon_changes / len(original_codons)) * 100 if original_codons else 0
+
+    log += "## Optimization Results\n"
+    log += f"- Codons modified: {codon_changes} out of {len(original_codons)} ({percent_changed:.2f}%)\n"
+
+    # Save sequences to files
+    with open("original_sequence.txt", "w") as f:
+        f.write(target_sequence)
+
+    with open("optimized_sequence.txt", "w") as f:
+        f.write(optimized_sequence)
+
+    log += "- Original sequence saved to: original_sequence.txt\n"
+    log += "- Optimized sequence saved to: optimized_sequence.txt\n\n"
+
+    # Add summary
+    log += "## Summary\n"
+    log += "The target gene sequence has been optimized for expression in the provided host organism. "
+    log += f"The optimization process replaced {codon_changes} codons ({percent_changed:.2f}%) "
+    log += "with synonymous codons that have higher usage frequency in the host.\n"
+
+    return log
+
+
+def simulate_gene_circuit_with_growth_feedback(
+    circuit_topology,
+    kinetic_params,
+    growth_params,
+    simulation_time=100,
+    time_points=1000,
+):
+    """Simulate gene regulatory circuit dynamics with growth feedback.
+
+    Parameters
+    ----------
+    circuit_topology : numpy.ndarray
+        Adjacency matrix representing the gene circuit topology.
+        Positive values indicate activation, negative values indicate repression.
+        Shape should be (n_genes, n_genes) where n_genes is the number of genes in the circuit.
+
+    kinetic_params : dict
+        Dictionary containing kinetic parameters:
+        - 'basal_rates': list of basal expression rates for each gene
+        - 'degradation_rates': list of degradation rates for each gene
+        - 'hill_coefficients': list of Hill coefficients for regulatory interactions
+        - 'threshold_constants': list of threshold constants for regulatory interactions
+
+    growth_params : dict
+        Dictionary containing growth-related parameters:
+        - 'max_growth_rate': maximum cell growth rate
+        - 'growth_inhibition': how gene expression affects growth
+        - 'gene_growth_weights': weights for how each gene affects growth
+
+    simulation_time : float, optional
+        Total simulation time (default: 100)
+
+    time_points : int, optional
+        Number of time points to sample (default: 1000)
+
+    Returns
+    -------
+    str
+        Research log summarizing the simulation and results with file names of saved data
+
+    """
+    import datetime
+    import json
+    import os
+
+    import numpy as np
+    from scipy.integrate import solve_ivp
+
+    # Extract parameters
+    n_genes = circuit_topology.shape[0]
+    basal_rates = kinetic_params["basal_rates"]
+    degradation_rates = kinetic_params["degradation_rates"]
+    hill_coefficients = kinetic_params["hill_coefficients"]
+    threshold_constants = kinetic_params["threshold_constants"]
+
+    max_growth_rate = growth_params["max_growth_rate"]
+    growth_inhibition = growth_params["growth_inhibition"]
+    gene_growth_weights = growth_params["gene_growth_weights"]
+
+    # Define the ODE system
+    def gene_circuit_odes(t, state):
+        # Extract state variables
+        gene_expressions = state[:n_genes]
+        cell_mass = state[n_genes]
+
+        # Initialize derivatives
+        dxdt = np.zeros(n_genes + 1)
+
+        # Gene expression dynamics
+        for i in range(n_genes):
+            # Basal expression
+            production = basal_rates[i]
+
+            # Regulatory influences
+            for j in range(n_genes):
+                if circuit_topology[i, j] != 0:
+                    # Calculate regulatory effect
+                    regulation = gene_expressions[j] ** hill_coefficients[j] / (
+                        threshold_constants[j] ** hill_coefficients[j] + gene_expressions[j] ** hill_coefficients[j]
+                    )
+
+                    if circuit_topology[i, j] > 0:  # Activation
+                        production *= 1 + circuit_topology[i, j] * regulation
+                    else:  # Repression
+                        production *= 1 + circuit_topology[i, j] * (1 - regulation)
+
+            # Dilution due to growth and degradation
+            dilution = degradation_rates[i] + (dxdt[n_genes] / cell_mass if cell_mass > 0 else 0)
+
+            # Final rate equation for gene i
+            dxdt[i] = production - dilution * gene_expressions[i]
+
+        # Cell growth dynamics
+        growth_burden = sum(gene_growth_weights[i] * gene_expressions[i] for i in range(n_genes))
+        dxdt[n_genes] = max_growth_rate * cell_mass / (1 + growth_inhibition * growth_burden)
+
+        return dxdt
+
+    # Initial conditions (starting with low gene expression and unit cell mass)
+    initial_state = np.zeros(n_genes + 1)
+    initial_state[:n_genes] = 0.1  # Low initial gene expression
+    initial_state[n_genes] = 1.0  # Initial cell mass
+
+    # Solve the ODE system
+    t_span = (0, simulation_time)
+    t_eval = np.linspace(0, simulation_time, time_points)
+
+    solution = solve_ivp(
+        gene_circuit_odes,
+        t_span,
+        initial_state,
+        method="LSODA",
+        t_eval=t_eval,
+        rtol=1e-6,
+        atol=1e-9,
+    )
+
+    # Extract results
+    time_series = solution.t
+    gene_expression_time_series = solution.y[:n_genes, :]
+    cell_growth_time_series = solution.y[n_genes, :]
+
+    # Save results to files
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    results_dir = "gene_circuit_results"
+
+    if not os.path.exists(results_dir):
+        os.makedirs(results_dir)
+
+    # Save time series data
+    data_filename = f"{results_dir}/gene_circuit_simulation_{timestamp}.npz"
+    np.savez(
+        data_filename,
+        time=time_series,
+        gene_expression=gene_expression_time_series,
+        cell_growth=cell_growth_time_series,
+    )
+
+    # Save parameters for reference
+    params_filename = f"{results_dir}/simulation_params_{timestamp}.json"
+    params_dict = {
+        "circuit_topology": circuit_topology.tolist(),
+        "kinetic_params": kinetic_params,
+        "growth_params": growth_params,
+        "simulation_time": simulation_time,
+        "time_points": time_points,
+    }
+
+    with open(params_filename, "w") as f:
+        json.dump(params_dict, f, indent=2)
+
+    # Create research log
+    log = f"""Gene Regulatory Circuit Simulation with Growth Feedback - {timestamp}
+
+SIMULATION SUMMARY:
+- Simulated a gene regulatory circuit with {n_genes} genes
+- Incorporated growth feedback mechanisms
+- Total simulation time: {simulation_time} time units
+- Collected {time_points} data points
+
+PARAMETERS:
+- Basal expression rates: {basal_rates}
+- Degradation rates: {degradation_rates}
+- Max growth rate: {max_growth_rate}
+- Growth inhibition factor: {growth_inhibition}
+
+RESULTS:
+- Final gene expression levels: {gene_expression_time_series[:, -1].tolist()}
+- Final cell mass: {cell_growth_time_series[-1]:.4f}
+- Growth rate at end of simulation: {max_growth_rate / (1 + growth_inhibition * sum(gene_growth_weights[i] * gene_expression_time_series[i, -1] for i in range(n_genes))):.4f}
+
+FILES:
+- Time series data saved to: {data_filename}
+- Simulation parameters saved to: {params_filename}
+"""
+
+    return log
+
+
+def identify_fas_functional_domains(sequence, sequence_type="protein", output_file="fas_domains_report.txt"):
+    """Identifies functional domains within a Fatty Acid Synthase (FAS) sequence and predicts their roles.
+
+    Parameters
+    ----------
+    sequence : str
+        The nucleotide or protein sequence of a FAS gene
+    sequence_type : str
+        Type of sequence provided - "protein" or "nucleotide" (default: "protein")
+    output_file : str
+        Name of the output file to save the detailed domain report (default: "fas_domains_report.txt")
+
+    Returns
+    -------
+    str
+        A research log summarizing the steps taken and results of the domain analysis
+
+    """
+    import json
+    import time
+
+    import requests
+    from Bio.Seq import Seq
+
+    research_log = "# Fatty Acid Synthase (FAS) Domain Analysis\n\n"
+    research_log += "## Input Sequence Analysis\n"
+    research_log += f"- Sequence type: {sequence_type}\n"
+    research_log += (
+        f"- Sequence length: {len(sequence)} {'nucleotides' if sequence_type == 'nucleotide' else 'amino acids'}\n\n"
+    )
+
+    # Convert nucleotide to protein if needed
+    if sequence_type == "nucleotide":
+        research_log += "## Sequence Translation\n"
+        research_log += "- Converting nucleotide sequence to protein\n"
+        try:
+            protein_seq = str(Seq(sequence).translate())
+            research_log += f"- Translated protein length: {len(protein_seq)} amino acids\n\n"
+        except Exception as e:
+            research_log += f"- Error in translation: {str(e)}\n"
+            return research_log
+    else:
+        protein_seq = sequence
+
+    # FAS domain information dictionary
+    fas_domains = {
+        "ketoacyl-synt": {
+            "name": "Ketoacyl Synthase (KS)",
+            "function": "Catalyzes the condensation of malonyl-ACP with the growing fatty acid chain",
+        },
+        "Ketoacyl-synt_C": {
+            "name": "Ketoacyl Synthase C-terminal (KS-C)",
+            "function": "C-terminal domain of KS, involved in substrate binding",
+        },
+        "Acyl_transf_1": {
+            "name": "Acyltransferase (AT)",
+            "function": "Transfers acyl groups from acyl-CoA to ACP",
+        },
+        "ketoacyl-red": {
+            "name": "Ketoacyl Reductase (KR)",
+            "function": "Reduces the beta-ketoacyl group to a beta-hydroxyacyl group",
+        },
+        "Thioesterase": {
+            "name": "Thioesterase (TE)",
+            "function": "Releases the fatty acid from ACP by hydrolysis",
+        },
+        "PS-DH": {
+            "name": "Dehydratase (DH)",
+            "function": "Removes water from beta-hydroxyacyl-ACP to form trans-2-enoyl-ACP",
+        },
+        "Enoyl_red": {
+            "name": "Enoyl Reductase (ER)",
+            "function": "Reduces the double bond in enoyl-ACP to a saturated acyl-ACP",
+        },
+        "ACP": {
+            "name": "Acyl Carrier Protein (ACP)",
+            "function": "Carries the growing fatty acid chain between enzyme domains",
+        },
+        "PP-binding": {
+            "name": "Phosphopantetheine Binding Domain",
+            "function": "Attachment site for the phosphopantetheine prosthetic group in ACP",
+        },
+    }
+
+    # HMMER web API for domain identification
+    research_log += "## Domain Identification\n"
+    research_log += "- Using HMMER web API to search against Pfam database\n"
+
+    url = "https://www.ebi.ac.uk/Tools/hmmer/search/hmmscan"
+    headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    data = {"hmmdb": "pfam", "seq": protein_seq}
+
+    try:
+        response = requests.post(url, data=json.dumps(data), headers=headers)
+        if response.status_code != 200:
+            research_log += f"- Error: HMMER API returned status code {response.status_code}\n"
+            return research_log
+
+        result_url = response.headers.get("Location", "")
+        if not result_url:
+            research_log += "- Error: No result URL returned from HMMER API\n"
+            return research_log
+
+        # Wait for results to be ready
+        time.sleep(2)
+
+        # Get results
+        result_response = requests.get(f"{result_url}.json")
+        if result_response.status_code != 200:
+            research_log += "- Error: Could not retrieve results from HMMER API\n"
+            return research_log
+
+        results = result_response.json()
+
+        # Process results
+        domains_found = []
+        if "results" in results and "hits" in results["results"]:
+            hits = results["results"]["hits"]
+            for hit in hits:
+                if "domains" in hit:
+                    for domain in hit["domains"]:
+                        domain_name = hit.get("name", "").split(".")[0]
+                        domain_desc = hit.get("desc", "Unknown")
+                        domain_start = domain.get("ali_from", 0)
+                        domain_end = domain.get("ali_to", 0)
+
+                        domains_found.append(
+                            {
+                                "name": domain_name,
+                                "description": domain_desc,
+                                "start": domain_start,
+                                "end": domain_end,
+                                "score": domain.get("score", 0),
+                            }
+                        )
+
+        # Check for FAS domains
+        research_log += f"- Found {len(domains_found)} domains in total\n\n"
+        research_log += "## FAS Functional Domains Identified\n"
+
+        fas_domains_found = []
+        for domain in domains_found:
+            for fas_key, fas_info in fas_domains.items():
+                if fas_key.lower() in domain["name"].lower():
+                    fas_domains_found.append(
+                        {
+                            "name": fas_info["name"],
+                            "pfam_id": domain["name"],
+                            "start": domain["start"],
+                            "end": domain["end"],
+                            "function": fas_info["function"],
+                        }
+                    )
+
+        if not fas_domains_found:
+            research_log += "- No specific FAS domains identified in the sequence\n"
+        else:
+            research_log += f"- Found {len(fas_domains_found)} FAS-related domains\n"
+            for i, domain in enumerate(fas_domains_found, 1):
+                research_log += f"\n### {i}. {domain['name']} (Positions {domain['start']}-{domain['end']})\n"
+                research_log += f"- Pfam ID: {domain['pfam_id']}\n"
+                research_log += f"- Function: {domain['function']}\n"
+
+        # Save detailed report to file
+        with open(output_file, "w") as f:
+            f.write("# Fatty Acid Synthase (FAS) Domain Analysis Detailed Report\n\n")
+            f.write("## Input Sequence\n")
+            f.write(f"- Type: {sequence_type}\n")
+            f.write(f"- Length: {len(sequence)} {'nucleotides' if sequence_type == 'nucleotide' else 'amino acids'}\n")
+            if sequence_type == "nucleotide":
+                f.write(f"- Translated protein length: {len(protein_seq)} amino acids\n")
+
+            f.write("\n## All Domains Found\n")
+            for i, domain in enumerate(domains_found, 1):
+                f.write(f"\n### {i}. {domain['name']} (Positions {domain['start']}-{domain['end']})\n")
+                f.write(f"- Description: {domain['description']}\n")
+                f.write(f"- Score: {domain['score']}\n")
+
+            f.write("\n## FAS Functional Domains\n")
+            if not fas_domains_found:
+                f.write("- No specific FAS domains identified in the sequence\n")
+            else:
+                for i, domain in enumerate(fas_domains_found, 1):
+                    f.write(f"\n### {i}. {domain['name']} (Positions {domain['start']}-{domain['end']})\n")
+                    f.write(f"- Pfam ID: {domain['pfam_id']}\n")
+                    f.write(f"- Function: {domain['function']}\n")
+
+        research_log += "\n## Summary\n"
+        research_log += f"- Detailed domain analysis saved to: {output_file}\n"
+        if fas_domains_found:
+            research_log += "- The sequence contains multiple domains characteristic of Fatty Acid Synthase\n"
+            research_log += "- The identified domains suggest this sequence is involved in fatty acid biosynthesis\n"
+        else:
+            research_log += "- The sequence does not contain typical FAS domains\n"
+            research_log += "- This may not be a Fatty Acid Synthase gene or may be a partial sequence\n"
+
+    except Exception as e:
+        research_log += f"- Error in domain identification: {str(e)}\n"
+
+    return research_log

Biomni/biomni/tool/systems_biology.py

@@ -0,0 +1,926 @@
+def query_chatnt(question, sequence, device=-1):
+    """
+    Call ChatNT to answer a question about a DNA sequence.
+
+    Parameters:
+    -----------
+    question : str
+        Question to ask about the DNA sequence
+    sequence : str
+        DNA sequence to analyze
+    device : int, optional
+        Device to use for the ChatNT model. Default is -1 (CPU).
+
+    Returns:
+    --------
+    str
+        Answer to the question
+    """
+    from transformers import pipeline
+
+    pipe = pipeline(model="InstaDeepAI/ChatNT", trust_remote_code=True, device=device)
+
+    # Define custom inputs (note that the number of <DNA> token in the english sequence must be equal to len(dna_sequences))
+    english_sequence = f"{question} <DNA> ?"
+    dna_sequences = [sequence]
+
+    # Generate sequence
+    generated_english_sequence = pipe(inputs={"english_sequence": english_sequence, "dna_sequences": dna_sequences})
+
+    return generated_english_sequence
+
+
+def perform_flux_balance_analysis(model_file, constraints=None, objective_reaction=None, output_file="fba_results.csv"):
+    """
+    Perform Flux Balance Analysis (FBA) on a genome-scale metabolic network model.
+
+    FBA is a computational technique that predicts metabolic flux distributions
+    by formulating and solving a linear optimization problem.
+
+    Parameters:
+    -----------
+    model_file : str
+        Path to the metabolic model file (SBML or JSON format)
+    constraints : dict, optional
+        Dictionary of reaction constraints where keys are reaction IDs and
+        values are tuples of (lower_bound, upper_bound)
+    objective_reaction : str, optional
+        Reaction ID to use as the objective function (e.g., biomass reaction)
+        If None, uses the model's default objective
+    output_file : str, optional
+        File name to save the flux distribution results
+
+    Returns:
+    --------
+    str
+        Research log summarizing the FBA process and results
+    """
+
+    import cobra
+    import pandas as pd
+
+    # Initialize research log
+    log = "# Flux Balance Analysis (FBA) Research Log\n\n"
+
+    # Step 1: Load the metabolic network model
+    log += "## Step 1: Loading metabolic model\n"
+    try:
+        if model_file.endswith(".xml") or model_file.endswith(".sbml"):
+            model = cobra.io.read_sbml_model(model_file)
+        elif model_file.endswith(".json"):
+            model = cobra.io.load_json_model(model_file)
+        else:
+            model = cobra.io.load_model(model_file)
+        log += f"- Successfully loaded model from {model_file}\n"
+        log += f"- Model contains {len(model.reactions)} reactions and {len(model.metabolites)} metabolites\n\n"
+    except Exception as e:
+        log += f"- Error loading model: {str(e)}\n"
+        return log
+
+    # Step 2: Set constraints
+    log += "## Step 2: Setting constraints\n"
+    if constraints:
+        log += "- Applied the following constraints:\n"
+        for reaction_id, (lb, ub) in constraints.items():
+            try:
+                reaction = model.reactions.get_by_id(reaction_id)
+                reaction.bounds = (lb, ub)
+                log += f"  * {reaction_id}: lower_bound={lb}, upper_bound={ub}\n"
+            except Exception as e:
+                log += f"  * Error setting constraint for {reaction_id}: {str(e)}\n"
+    else:
+        log += "- No additional constraints specified, using model defaults\n"
+    log += "\n"
+
+    # Step 3: Set objective function
+    log += "## Step 3: Setting objective function\n"
+    if objective_reaction:
+        try:
+            model.objective = objective_reaction
+            log += f"- Set objective function to maximize {objective_reaction}\n\n"
+        except Exception as e:
+            log += f"- Error setting objective function: {str(e)}\n"
+            log += "- Using model's default objective function\n\n"
+    else:
+        log += f"- Using model's default objective function: {model.objective.expression}\n\n"
+
+    # Step 4: Solve the FBA problem
+    log += "## Step 4: Solving FBA optimization problem\n"
+    try:
+        solution = model.optimize()
+        log += f"- Optimization status: {solution.status}\n"
+        log += f"- Objective value: {solution.objective_value:.6f}\n\n"
+    except Exception as e:
+        log += f"- Error during optimization: {str(e)}\n"
+        return log
+
+    # Step 5: Save and report results
+    log += "## Step 5: Analyzing flux distribution\n"
+
+    # Create a dataframe with the flux distribution
+    flux_distribution = pd.DataFrame(
+        {
+            "reaction_id": [r.id for r in model.reactions],
+            "reaction_name": [r.name for r in model.reactions],
+            "flux": [solution.fluxes[r.id] for r in model.reactions],
+            "lower_bound": [r.lower_bound for r in model.reactions],
+            "upper_bound": [r.upper_bound for r in model.reactions],
+        }
+    )
+
+    # Save to file
+    flux_distribution.to_csv(output_file, index=False)
+    log += f"- Flux distribution saved to {output_file}\n"
+
+    # Report active reactions (non-zero flux)
+    active_reactions = flux_distribution[abs(flux_distribution["flux"]) > 1e-6]
+    log += f"- Number of active reactions (flux > 1e-6): {len(active_reactions)}\n"
+
+    # Report top reactions by absolute flux
+    top_reactions = flux_distribution.iloc[abs(flux_distribution["flux"]).argsort()[::-1]].head(10)
+    log += "- Top 10 reactions by absolute flux magnitude:\n"
+    for _, row in top_reactions.iterrows():
+        log += f"  * {row['reaction_id']} ({row['reaction_name']}): {row['flux']:.6f}\n"
+
+    log += f"\nFBA analysis complete. Full results available in {output_file}\n"
+
+    return log
+
+
+def model_protein_dimerization_network(monomer_concentrations, dimerization_affinities, network_topology):
+    """
+    Model protein dimerization networks to find equilibrium concentrations of dimers.
+
+    Parameters:
+    -----------
+    monomer_concentrations : dict
+        Dictionary mapping monomer names to their initial concentrations (in arbitrary units)
+    dimerization_affinities : dict
+        Dictionary mapping dimer names (as 'A-B' strings) to their association constants (Ka)
+    network_topology : list of tuples
+        List of (monomer1, monomer2) pairs that can form dimers
+
+    Returns:
+    --------
+    str
+        Research log summarizing the modeling process and results
+    """
+    import time
+
+    import numpy as np
+    from scipy.integrate import solve_ivp
+
+    # Start timing
+    start_time = time.time()
+
+    # Extract unique monomers and create mapping to indices
+    all_monomers = list(monomer_concentrations.keys())
+    monomer_to_idx = {monomer: i for i, monomer in enumerate(all_monomers)}
+
+    # Create mapping from dimer indices to names
+    dimer_pairs = []
+    dimer_names = []
+    dimer_affinities = []
+
+    for m1, m2 in network_topology:
+        dimer_name = f"{m1}-{m2}"
+        if dimer_name in dimerization_affinities:
+            affinity = dimerization_affinities[dimer_name]
+        else:
+            # Try reverse order
+            dimer_name = f"{m2}-{m1}"
+            if dimer_name in dimerization_affinities:
+                affinity = dimerization_affinities[dimer_name]
+            else:
+                raise ValueError(f"No affinity found for dimer pair {m1}-{m2}")
+
+        dimer_pairs.append((monomer_to_idx[m1], monomer_to_idx[m2]))
+        dimer_names.append(dimer_name)
+        dimer_affinities.append(affinity)
+
+    # Initial conditions (monomer concentrations followed by dimer concentrations)
+    num_monomers = len(all_monomers)
+    num_dimers = len(dimer_pairs)
+    y0 = np.zeros(num_monomers + num_dimers)
+
+    for monomer, conc in monomer_concentrations.items():
+        y0[monomer_to_idx[monomer]] = conc
+
+    # Define ODE system
+    def dimerization_odes(t, y):
+        dydt = np.zeros_like(y)
+
+        # Extract current concentrations
+        monomer_concs = y[:num_monomers]
+        dimer_concs = y[num_monomers:]
+
+        # Calculate rate of change for each species
+        for i, ((m1_idx, m2_idx), affinity) in enumerate(zip(dimer_pairs, dimer_affinities, strict=False)):
+            # Formation rate: kon * [A] * [B]
+            # Dissociation rate: koff * [AB]
+            # At equilibrium: kon/koff = Ka (affinity)
+            # For simplicity, set kon = Ka and koff = 1
+
+            kon = affinity
+            koff = 1.0
+
+            # Dimer formation/dissociation
+            dimer_idx = num_monomers + i
+
+            # Rate of change
+            formation_rate = kon * monomer_concs[m1_idx] * monomer_concs[m2_idx]
+            dissociation_rate = koff * dimer_concs[i]
+            net_rate = formation_rate - dissociation_rate
+
+            # Update rates for monomers and dimers
+            dydt[m1_idx] -= net_rate
+            dydt[m2_idx] -= net_rate
+            dydt[dimer_idx] += net_rate
+
+        return dydt
+
+    # Solve ODE system to equilibrium
+    # Using a long enough time to reach equilibrium
+    t_span = (0, 1000)  # Arbitrary long time to reach equilibrium
+
+    sol = solve_ivp(
+        dimerization_odes,
+        t_span,
+        y0,
+        method="BDF",  # Good for stiff problems
+        rtol=1e-6,
+        atol=1e-9,
+    )
+
+    # Extract final concentrations (equilibrium)
+    final_monomer_concs = {monomer: sol.y[idx][-1] for monomer, idx in monomer_to_idx.items()}
+    final_dimer_concs = {dimer_name: sol.y[num_monomers + i][-1] for i, dimer_name in enumerate(dimer_names)}
+
+    # Calculate time taken
+    elapsed_time = time.time() - start_time
+
+    # Generate research log
+    log = "Protein Dimerization Network Modeling\n"
+    log += "=====================================\n\n"
+    log += "Network summary:\n"
+    log += f"- Number of monomers: {num_monomers}\n"
+    log += f"- Number of possible dimers: {num_dimers}\n\n"
+
+    log += "Initial conditions:\n"
+    for monomer, conc in monomer_concentrations.items():
+        log += f"- {monomer}: {conc:.4f}\n"
+    log += "\n"
+
+    log += "Dimerization affinities:\n"
+    for dimer, affinity in zip(dimer_names, dimer_affinities, strict=False):
+        log += f"- {dimer}: {affinity:.4e}\n"
+    log += "\n"
+
+    log += "Equilibrium concentrations:\n"
+    log += "Monomers:\n"
+    for monomer, conc in final_monomer_concs.items():
+        log += f"- {monomer}: {conc:.4f}\n"
+
+    log += "\nDimers:\n"
+    for dimer, conc in final_dimer_concs.items():
+        log += f"- {dimer}: {conc:.4f}\n"
+    log += "\n"
+
+    log += f"Simulation completed in {elapsed_time:.2f} seconds.\n"
+
+    return log
+
+
+def simulate_metabolic_network_perturbation(
+    model_file, initial_concentrations, perturbation_params, simulation_time=100, time_points=1000
+):
+    """
+    Construct and simulate kinetic models of metabolic networks and analyze their responses to perturbations.
+
+    Parameters:
+    -----------
+    model_file : str
+        Path to the COBRA model file (SBML format)
+    initial_concentrations : dict
+        Dictionary mapping metabolite IDs to their initial concentrations
+    perturbation_params : dict
+        Dictionary with the following keys:
+        - 'time': float, time at which perturbation is applied
+        - 'metabolite': str, ID of the metabolite to perturb
+        - 'factor': float, multiplication factor for the metabolite concentration
+    simulation_time : float, optional
+        Total simulation time (default: 100)
+    time_points : int, optional
+        Number of time points to simulate (default: 1000)
+
+    Returns:
+    --------
+    str
+        Research log summarizing the steps taken and results obtained
+    """
+
+    import cobra
+    import numpy as np
+    import pandas as pd
+    from scipy.integrate import solve_ivp
+
+    # Step 1: Load the metabolic model
+    try:
+        model = cobra.io.read_sbml_model(model_file)
+        log = f"Loaded metabolic model from {model_file} with {len(model.reactions)} reactions and {len(model.metabolites)} metabolites.\n\n"
+    except Exception as e:
+        return f"Error loading model: {str(e)}"
+
+    # Step 2: Set up metabolite list and initial concentrations
+    metabolites = list(model.metabolites)
+    metabolite_ids = [m.id for m in metabolites]
+
+    # Set default initial concentrations for metabolites not specified
+    conc_array = np.ones(len(metabolites))
+    for i, m_id in enumerate(metabolite_ids):
+        if m_id in initial_concentrations:
+            conc_array[i] = initial_concentrations[m_id]
+
+    log += "Initial concentrations set up for all metabolites.\n\n"
+
+    # Step 3: Define kinetic model using simple mass-action kinetics
+    def mass_action_kinetics(reaction, concentrations, metabolite_ids):
+        # Simple mass-action kinetics: product of substrate concentrations
+        rate = 1.0
+        for metabolite, coeff in reaction.metabolites.items():
+            if coeff < 0:  # Substrate
+                idx = metabolite_ids.index(metabolite.id)
+                rate *= concentrations[idx] ** abs(coeff)
+        return rate
+
+    # Step 4: Define ODE system
+    def ode_system(t, concentrations, metabolite_ids, reactions, perturbation):
+        dC_dt = np.zeros(len(concentrations))
+
+        # Apply perturbation if we're at or past the perturbation time
+        if t >= perturbation["time"]:
+            perturb_idx = metabolite_ids.index(perturbation["metabolite"])
+            if not perturbation.get("applied", False):
+                concentrations[perturb_idx] *= perturbation["factor"]
+                perturbation["applied"] = True
+
+        # Calculate reaction rates
+        rates = {}
+        for reaction in reactions:
+            rates[reaction.id] = mass_action_kinetics(reaction, concentrations, metabolite_ids)
+
+        # Update concentration changes based on stoichiometry and rates
+        for i, metabolite_id in enumerate(metabolite_ids):
+            for reaction in reactions:
+                if metabolite_id in [m.id for m in reaction.metabolites]:
+                    coeff = reaction.metabolites[model.metabolites.get_by_id(metabolite_id)]
+                    dC_dt[i] += coeff * rates[reaction.id]
+
+        return dC_dt
+
+    log += "Kinetic model defined using mass-action kinetics for all reactions.\n\n"
+
+    # Step 5: Simulate the system
+    perturbation = perturbation_params.copy()
+    perturbation["applied"] = False
+
+    t_span = (0, simulation_time)
+    t_eval = np.linspace(0, simulation_time, time_points)
+
+    log += f"Starting simulation for {simulation_time} time units with perturbation of {perturbation['metabolite']} "
+    log += f"by factor {perturbation['factor']} at time {perturbation['time']}.\n\n"
+
+    try:
+        solution = solve_ivp(
+            lambda t, y: ode_system(t, y, metabolite_ids, model.reactions, perturbation),
+            t_span,
+            conc_array,
+            t_eval=t_eval,
+            method="LSODA",
+        )
+
+        log += f"Simulation completed successfully with {len(solution.t)} time points.\n\n"
+    except Exception as e:
+        return f"Error during simulation: {str(e)}"
+
+    # Step 6: Calculate fluxes at each time point
+    fluxes = np.zeros((len(solution.t), len(model.reactions)))
+    reaction_ids = [r.id for r in model.reactions]
+
+    for t_idx, t in enumerate(solution.t):
+        concentrations = solution.y[:, t_idx]
+        perturbation_temp = perturbation.copy()
+        if t >= perturbation["time"]:
+            perturbation_temp["applied"] = True
+
+        for r_idx, reaction in enumerate(model.reactions):
+            fluxes[t_idx, r_idx] = mass_action_kinetics(reaction, concentrations, metabolite_ids)
+
+    log += "Calculated reaction fluxes for all time points.\n\n"
+
+    # Step 7: Save results to files
+    conc_df = pd.DataFrame(solution.y.T, columns=metabolite_ids)
+    conc_df["time"] = solution.t
+    conc_file = "metabolite_concentrations.csv"
+    conc_df.to_csv(conc_file, index=False)
+
+    flux_df = pd.DataFrame(fluxes, columns=reaction_ids)
+    flux_df["time"] = solution.t
+    flux_file = "reaction_fluxes.csv"
+    flux_df.to_csv(flux_file, index=False)
+
+    log += f"Results saved to {conc_file} and {flux_file}.\n\n"
+
+    # Step 8: Analyze perturbation response
+    perturb_time_idx = np.where(solution.t >= perturbation["time"])[0][0]
+    pre_perturb = solution.y[:, perturb_time_idx - 1]
+    post_perturb = solution.y[:, perturb_time_idx]
+
+    # Find metabolites with significant changes
+    significant_changes = []
+    for i, m_id in enumerate(metabolite_ids):
+        rel_change = abs(post_perturb[i] - pre_perturb[i]) / pre_perturb[i] if pre_perturb[i] > 0 else 0
+        if rel_change > 0.05:  # 5% change threshold
+            significant_changes.append((m_id, rel_change))
+
+    log += "Perturbation Analysis Results:\n"
+    log += f"Perturbation of {perturbation['metabolite']} at time {perturbation['time']} by factor {perturbation['factor']}.\n"
+    log += f"Number of metabolites with significant immediate response: {len(significant_changes)}.\n"
+
+    if significant_changes:
+        log += "Top 5 most affected metabolites (by relative concentration change):\n"
+        for m_id, change in sorted(significant_changes, key=lambda x: x[1], reverse=True)[:5]:
+            log += f"  - {m_id}: {change * 100:.2f}% change\n"
+
+    log += "\nSimulation and perturbation analysis completed successfully."
+
+    return log
+
+
+def simulate_protein_signaling_network(
+    network_structure, reaction_params, species_params, simulation_time=100, time_points=1000
+):
+    """
+    Simulate protein signaling network dynamics using ODE-based logic modeling with normalized Hill functions.
+
+    Parameters:
+    -----------
+    network_structure : dict
+        Dictionary defining the network topology. Each key is a target protein and its value is a list of tuples
+        (regulator, regulation_type) where regulation_type is 1 for activation and -1 for inhibition.
+
+    reaction_params : dict
+        Dictionary of reaction parameters. Keys are tuples (regulator, target) and values are dictionaries
+        with keys 'W' (weight), 'n' (Hill coefficient), and 'EC50' (half-maximal effective concentration).
+
+    species_params : dict
+        Dictionary of species parameters. Keys are protein names and values are dictionaries
+        with keys 'tau' (time constant), 'y0' (initial concentration), and 'ymax' (maximum concentration).
+
+    simulation_time : float, optional
+        Total simulation time in arbitrary time units. Default is 100.
+
+    time_points : int, optional
+        Number of time points for the simulation. Default is 1000.
+
+    Returns:
+    --------
+    str
+        Research log summarizing the simulation process and results.
+    """
+    import csv
+
+    import numpy as np
+    from scipy.integrate import solve_ivp
+
+    # Extract all unique protein species
+    all_proteins = set(network_structure.keys())
+    for _target, regulators in network_structure.items():
+        for regulator, _ in regulators:
+            all_proteins.add(regulator)
+
+    # Create ordered list of proteins for indexing
+    proteins = sorted(all_proteins)
+    protein_indices = {protein: i for i, protein in enumerate(proteins)}
+
+    # Define the normalized Hill function
+    def hill_function(x, n, ec50):
+        return x**n / (x**n + ec50**n)
+
+    # Define the ODE system
+    def ode_system(t, y):
+        dydt = np.zeros_like(y)
+
+        for target, regulators in network_structure.items():
+            target_idx = protein_indices[target]
+            target_params = species_params[target]
+
+            # Calculate regulation term for each regulator
+            regulation_terms = []
+            for regulator, reg_type in regulators:
+                regulator_idx = protein_indices[regulator]
+                params = reaction_params.get((regulator, target), {})
+
+                if not params:
+                    continue
+
+                x = y[regulator_idx]
+                n = params["n"]
+                ec50 = params["EC50"]
+                weight = params["W"]
+
+                # Apply Hill function based on regulation type
+                if reg_type == 1:  # Activation
+                    term = weight * hill_function(x, n, ec50)
+                else:  # Inhibition
+                    term = weight * (1 - hill_function(x, n, ec50))
+
+                regulation_terms.append(term)
+
+            # Combine regulation terms (if any)
+            if regulation_terms:
+                # Simple summation of regulation terms
+                regulation = sum(regulation_terms) / len(regulation_terms)
+
+                # Ensure regulation stays within [0, 1]
+                regulation = max(0, min(1, regulation))
+
+                # Calculate rate of change
+                tau = target_params["tau"]
+                ymax = target_params["ymax"]
+                dydt[target_idx] = (1 / tau) * (regulation * ymax - y[target_idx])
+
+        return dydt
+
+    # Set up initial conditions
+    y0 = np.zeros(len(proteins))
+    for protein, params in species_params.items():
+        if protein in protein_indices:
+            y0[protein_indices[protein]] = params["y0"]
+
+    # Set up time points
+    t_span = (0, simulation_time)
+    t_eval = np.linspace(0, simulation_time, time_points)
+
+    # Solve the ODE system
+    solution = solve_ivp(ode_system, t_span, y0, method="LSODA", t_eval=t_eval, rtol=1e-6, atol=1e-9)
+
+    # Save results to CSV
+    output_file = "protein_signaling_simulation_results.csv"
+    with open(output_file, "w", newline="") as f:
+        writer = csv.writer(f)
+        # Write header
+        header = ["Time"] + proteins
+        writer.writerow(header)
+
+        # Write data
+        for i in range(len(solution.t)):
+            row = [solution.t[i]] + list(solution.y[:, i])
+            writer.writerow(row)
+
+    # Generate research log
+    log = "ODE-based Logic Modeling of Protein Signaling Networks\n"
+    log += "=============================================\n\n"
+    log += f"Network structure: {len(network_structure)} target proteins, {len(proteins)} total proteins\n"
+    log += f"Simulation time: {simulation_time} time units\n"
+    log += f"Number of time points: {time_points}\n\n"
+
+    log += "Simulation steps:\n"
+    log += "1. Initialized protein concentrations based on provided initial values\n"
+    log += "2. Set up ODE system using normalized Hill functions for protein interactions\n"
+    log += "3. Solved the ODE system using LSODA integration method\n"
+    log += "4. Saved time-series data for all protein concentrations\n\n"
+
+    log += f"Results saved to: {output_file}\n\n"
+
+    # Add summary statistics
+    log += "Summary of final protein concentrations:\n"
+    for i, protein in enumerate(proteins):
+        final_conc = solution.y[i, -1]
+        log += f"- {protein}: {final_conc:.4f}\n"
+
+    return log
+
+
+def compare_protein_structures(pdb_file1, pdb_file2, chain_id1="A", chain_id2="A", output_prefix="protein_comparison"):
+    """
+    Compares two protein structures to identify structural differences and conformational changes.
+
+    Parameters:
+    -----------
+    pdb_file1 : str
+        Path to the first PDB file
+    pdb_file2 : str
+        Path to the second PDB file
+    chain_id1 : str, optional
+        Chain ID to analyze in the first structure (default: 'A')
+    chain_id2 : str, optional
+        Chain ID to analyze in the second structure (default: 'A')
+    output_prefix : str, optional
+        Prefix for output files (default: "protein_comparison")
+
+    Returns:
+    --------
+    str
+        A research log summarizing the structural comparison analysis
+    """
+    import warnings
+
+    import numpy as np
+    from Bio.PDB import PDBIO, PDBParser, Select, Superimposer
+    from Bio.PDB.PDBExceptions import PDBConstructionWarning
+
+    # Suppress PDB parsing warnings
+    warnings.filterwarnings("ignore", category=PDBConstructionWarning)
+
+    research_log = []
+    research_log.append("# Protein Structure Comparison Analysis\n")
+    research_log.append(f"Comparing structures from {pdb_file1} and {pdb_file2}\n")
+
+    # Initialize parser
+    parser = PDBParser()
+
+    # Parse structures
+    research_log.append("## Loading PDB structures")
+    structure1 = parser.get_structure("structure1", pdb_file1)
+    structure2 = parser.get_structure("structure2", pdb_file2)
+
+    # Get specified chains
+    try:
+        chain1 = structure1[0][chain_id1]
+        chain2 = structure2[0][chain_id2]
+        research_log.append(f"Successfully loaded chain {chain_id1} from {pdb_file1}")
+        research_log.append(f"Successfully loaded chain {chain_id2} from {pdb_file2}")
+    except KeyError as e:
+        return f"Error: Chain not found: {str(e)}"
+
+    # Get CA atoms for alignment
+    ca_atoms1 = []
+    ca_atoms2 = []
+
+    # Create residue mappings based on residue ID
+    residues1 = {residue.id[1]: residue for residue in chain1 if residue.has_id("CA")}
+    residues2 = {residue.id[1]: residue for residue in chain2 if residue.has_id("CA")}
+
+    # Find common residues
+    common_residues = sorted(set(residues1.keys()) & set(residues2.keys()))
+
+    if len(common_residues) == 0:
+        return "Error: No common residues with CA atoms found between the structures"
+
+    research_log.append(f"Found {len(common_residues)} common residues for alignment\n")
+
+    # Get paired atoms for alignment
+    for res_id in common_residues:
+        ca_atoms1.append(residues1[res_id]["CA"])
+        ca_atoms2.append(residues2[res_id]["CA"])
+
+    # Perform structural alignment
+    research_log.append("## Structural Alignment")
+    super_imposer = Superimposer()
+    super_imposer.set_atoms(ca_atoms1, ca_atoms2)
+    super_imposer.apply(structure2.get_atoms())
+
+    # Calculate RMSD
+    rmsd = super_imposer.rms
+    research_log.append(f"Overall RMSD: {rmsd:.4f} Å\n")
+
+    # Calculate per-residue distance after alignment
+    research_log.append("## Conformational Differences Analysis")
+
+    # Find regions with significant differences
+    distance_data = []
+    significant_changes = []
+    threshold = 2.0  # Angstroms threshold for significant difference
+
+    for res_id in common_residues:
+        res1 = residues1[res_id]
+        res2 = residues2[res_id]
+
+        # Calculate distance between CA atoms
+        ca1 = res1["CA"]
+        ca2 = res2["CA"]
+        distance = np.linalg.norm(ca1.coord - ca2.coord)
+
+        distance_data.append((res_id, distance))
+
+        if distance > threshold:
+            significant_changes.append((res_id, res1.get_resname(), distance))
+
+    # Save alignment as PDB files
+    aligned_file1 = f"{output_prefix}_ref.pdb"
+    aligned_file2 = f"{output_prefix}_aligned.pdb"
+
+    io = PDBIO()
+    io.set_structure(structure1)
+    io.save(aligned_file1, select=Select())
+
+    io.set_structure(structure2)
+    io.save(aligned_file2, select=Select())
+
+    research_log.append(f"Aligned structures saved as {aligned_file1} and {aligned_file2}")
+
+    # Report on significant differences
+    if significant_changes:
+        research_log.append(
+            f"\nIdentified {len(significant_changes)} residues with significant conformational changes:"
+        )
+        for res_id, res_name, distance in significant_changes:
+            research_log.append(f"  - Residue {res_name}{res_id}: {distance:.2f} Å displacement")
+    else:
+        research_log.append("\nNo significant conformational changes detected (threshold: 2.0 Å)")
+
+    # Save per-residue distance data
+    distance_file = f"{output_prefix}_residue_distances.csv"
+    with open(distance_file, "w") as f:
+        f.write("Residue_ID,Distance(Å)\n")
+        for res_id, distance in distance_data:
+            f.write(f"{res_id},{distance:.4f}\n")
+
+    research_log.append(f"\nPer-residue distance data saved to {distance_file}")
+
+    # Identify regions with continuous changes
+    regions = []
+    current_region = []
+
+    for res_id, _, distance in significant_changes:
+        if not current_region or res_id == current_region[-1][0] + 1:
+            current_region.append((res_id, distance))
+        else:
+            if len(current_region) >= 3:  # Consider regions with at least 3 consecutive residues
+                regions.append(current_region)
+            current_region = [(res_id, distance)]
+
+    if current_region and len(current_region) >= 3:
+        regions.append(current_region)
+
+    if regions:
+        research_log.append("\n## Continuous Regions with Conformational Changes")
+        for i, region in enumerate(regions, 1):
+            start_res = region[0][0]
+            end_res = region[-1][0]
+            avg_dist = sum(r[1] for r in region) / len(region)
+            research_log.append(f"Region {i}: Residues {start_res}-{end_res} (Average displacement: {avg_dist:.2f} Å)")
+
+    research_log.append("\n## Summary")
+    research_log.append(f"- Compared structures from {pdb_file1} and {pdb_file2}")
+    research_log.append(f"- Overall RMSD: {rmsd:.4f} Å")
+    research_log.append(f"- {len(significant_changes)} residues with significant conformational changes")
+    research_log.append(f"- {len(regions)} continuous regions of conformational change")
+    research_log.append(f"- Files generated: {aligned_file1}, {aligned_file2}, {distance_file}")
+
+    return "\n".join(research_log)
+
+
+def simulate_renin_angiotensin_system_dynamics(
+    initial_concentrations, rate_constants, feedback_params, simulation_time=48, time_points=100
+):
+    """
+    Simulate the time-dependent concentrations of renin-angiotensin system (RAS) components.
+
+    Parameters:
+    -----------
+    initial_concentrations : dict
+        Initial concentrations of RAS components with keys:
+        'renin', 'angiotensinogen', 'angiotensin_I', 'angiotensin_II',
+        'ACE2_angiotensin_II', 'angiotensin_1_7'
+
+    rate_constants : dict
+        Kinetic rate constants with keys:
+        'k_ren' (renin production), 'k_agt' (angiotensinogen production),
+        'k_ace' (ACE conversion rate), 'k_ace2' (ACE2 conversion rate),
+        'k_at1r' (AT1R binding rate), 'k_mas' (Mas receptor binding rate)
+
+    feedback_params : dict
+        Parameters controlling feedback mechanisms with keys:
+        'fb_ang_II' (angiotensin II feedback), 'fb_ace2' (ACE2 feedback)
+
+    simulation_time : float, optional
+        Total simulation time in hours (default: 48)
+
+    time_points : int, optional
+        Number of time points to evaluate (default: 100)
+
+    Returns:
+    --------
+    str
+        Research log summarizing the simulation steps and results
+    """
+
+    import numpy as np
+    import pandas as pd
+    from scipy.integrate import solve_ivp
+
+    # Extract initial concentrations
+    y0 = [
+        initial_concentrations["renin"],
+        initial_concentrations["angiotensinogen"],
+        initial_concentrations["angiotensin_I"],
+        initial_concentrations["angiotensin_II"],
+        initial_concentrations["ACE2_angiotensin_II"],
+        initial_concentrations["angiotensin_1_7"],
+    ]
+
+    # Define the system of ODEs
+    def ras_ode_system(t, y):
+        renin, agt, ang_I, ang_II, ace2_ang_II, ang_1_7 = y
+
+        # Production rates with feedback
+        renin_production = rate_constants["k_ren"] * (1 / (1 + feedback_params["fb_ang_II"] * ang_II))
+        agt_production = rate_constants["k_agt"]
+
+        # Conversion rates
+        ang_I_formation = renin * agt
+        ang_II_formation = rate_constants["k_ace"] * ang_I
+        ace2_binding = rate_constants["k_ace2"] * ang_II
+        ang_1_7_formation = ace2_ang_II
+
+        # Clearance/degradation (simplified as proportional to concentration)
+        renin_clearance = 0.1 * renin
+        agt_clearance = 0.05 * agt
+        ang_I_clearance = 0.2 * ang_I
+        ang_II_clearance = 0.3 * ang_II + rate_constants["k_at1r"] * ang_II
+        ace2_ang_II_clearance = 0.15 * ace2_ang_II
+        ang_1_7_clearance = 0.25 * ang_1_7 + rate_constants["k_mas"] * ang_1_7
+
+        # ODEs
+        drenin_dt = renin_production - renin_clearance
+        dagt_dt = agt_production - agt_clearance - ang_I_formation
+        dang_I_dt = ang_I_formation - ang_I_clearance - ang_II_formation
+        dang_II_dt = ang_II_formation - ang_II_clearance - ace2_binding
+        dace2_ang_II_dt = ace2_binding - ace2_ang_II_clearance - ang_1_7_formation
+        dang_1_7_dt = ang_1_7_formation - ang_1_7_clearance
+
+        return [drenin_dt, dagt_dt, dang_I_dt, dang_II_dt, dace2_ang_II_dt, dang_1_7_dt]
+
+    # Time points for simulation
+    t_span = (0, simulation_time)
+    t_eval = np.linspace(0, simulation_time, time_points)
+
+    # Solve the ODE system
+    solution = solve_ivp(ras_ode_system, t_span, y0, method="RK45", t_eval=t_eval, rtol=1e-6)
+
+    # Create DataFrame with results
+    component_names = [
+        "Renin",
+        "Angiotensinogen",
+        "Angiotensin I",
+        "Angiotensin II",
+        "ACE2-Angiotensin II",
+        "Angiotensin 1-7",
+    ]
+    results_df = pd.DataFrame(solution.y.T, columns=component_names)
+    results_df.insert(0, "Time (hours)", solution.t)
+
+    # Save results to CSV
+    results_file = "ras_simulation_results.csv"
+    results_df.to_csv(results_file, index=False)
+
+    # Create research log
+    log = f"""RAS ODE Modeling Simulation Log:
+
+1. Initialized RAS component concentrations:
+   - Renin: {initial_concentrations["renin"]}
+   - Angiotensinogen: {initial_concentrations["angiotensinogen"]}
+   - Angiotensin I: {initial_concentrations["angiotensin_I"]}
+   - Angiotensin II: {initial_concentrations["angiotensin_II"]}
+   - ACE2-Angiotensin II complex: {initial_concentrations["ACE2_angiotensin_II"]}
+   - Angiotensin 1-7: {initial_concentrations["angiotensin_1_7"]}
+
+2. Applied rate constants:
+   - Renin production (k_ren): {rate_constants["k_ren"]}
+   - Angiotensinogen production (k_agt): {rate_constants["k_agt"]}
+   - ACE conversion rate (k_ace): {rate_constants["k_ace"]}
+   - ACE2 conversion rate (k_ace2): {rate_constants["k_ace2"]}
+   - AT1R binding rate (k_at1r): {rate_constants["k_at1r"]}
+   - Mas receptor binding rate (k_mas): {rate_constants["k_mas"]}
+
+3. Feedback parameters:
+   - Angiotensin II feedback (fb_ang_II): {feedback_params["fb_ang_II"]}
+   - ACE2 feedback (fb_ace2): {feedback_params["fb_ace2"]}
+
+4. Simulation parameters:
+   - Total simulation time: {simulation_time} hours
+   - Number of time points: {time_points}
+
+5. Solved system of ODEs using SciPy's solve_ivp with RK45 method.
+
+6. Final concentrations at {simulation_time} hours:
+   - Renin: {results_df["Renin"].iloc[-1]:.4f}
+   - Angiotensinogen: {results_df["Angiotensinogen"].iloc[-1]:.4f}
+   - Angiotensin I: {results_df["Angiotensin I"].iloc[-1]:.4f}
+   - Angiotensin II: {results_df["Angiotensin II"].iloc[-1]:.4f}
+   - ACE2-Angiotensin II complex: {results_df["ACE2-Angiotensin II"].iloc[-1]:.4f}
+   - Angiotensin 1-7: {results_df["Angiotensin 1-7"].iloc[-1]:.4f}
+
+7. Results saved to file: {results_file}
+
+8. Key observations:
+   - The model captures the conversion of Angiotensinogen to Angiotensin I via Renin
+   - Angiotensin I is converted to Angiotensin II via ACE
+   - Angiotensin II binds with ACE2 to form the ACE2-Angiotensin II complex
+   - The complex is converted to Angiotensin 1-7
+   - Feedback mechanisms regulate the production rates
+"""
+
+    return log

Biomni/biomni/tool/tool_registry.py

@@ -0,0 +1,89 @@
+import pickle
+
+import pandas as pd
+
+
+class ToolRegistry:
+    def __init__(self, tools):
+        self.tools = []
+        self.next_id = 0
+
+        for j in tools.values():
+            for tool in j:
+                self.register_tool(tool)
+
+        docs = []
+        for tool_id in range(len(self.tools)):
+            docs.append([int(tool_id), self.get_tool_by_id(int(tool_id))])
+        self.document_df = pd.DataFrame(docs, columns=["docid", "document_content"])
+
+        # self.langchain_tools = {}
+        # for module, api_list in tools.items():
+        #    self.langchain_tools.update({self.get_id_by_name(api['name']): api_schema_to_langchain_tool(api, mode = 'custom_tool', module_name = module) for api in api_list})
+
+    def register_tool(self, tool):
+        if self.validate_tool(tool):
+            tool["id"] = self.next_id
+            self.tools.append(tool)
+            self.next_id += 1
+        else:
+            raise ValueError("Invalid tool format")
+
+    def validate_tool(self, tool):
+        required_keys = ["name", "description", "required_parameters"]
+        return all(key in tool for key in required_keys)
+
+    def get_tool_by_name(self, name):
+        for tool in self.tools:
+            if tool["name"] == name:
+                return tool
+        return None
+
+    def get_tool_by_id(self, tool_id):
+        for tool in self.tools:
+            if tool["id"] == tool_id:
+                return tool
+        return None
+
+    def get_id_by_name(self, name):
+        for tool in self.tools:
+            if tool["name"] == name:
+                return tool["id"]
+        return None
+
+    def get_name_by_id(self, tool_id):
+        for tool in self.tools:
+            if tool["id"] == tool_id:
+                return tool["name"]
+        return None
+
+    def list_tools(self):
+        return [{"name": tool["name"], "id": tool["id"]} for tool in self.tools]
+
+    def remove_tool_by_id(self, tool_id):
+        # Remove the tool with the given id
+        tool = self.get_tool_by_id(tool_id)
+        if tool:
+            self.tools = [t for t in self.tools if t["id"] != tool_id]
+            return True
+        return False
+
+    def remove_tool_by_name(self, name):
+        # Remove the tool with the given name
+        tool = self.get_tool_by_name(name)
+        if tool:
+            self.tools = [t for t in self.tools if t["name"] != name]
+            return True
+        return False
+
+    def save_registry(self, filename):
+        with open(filename, "wb") as file:
+            pickle.dump(self, file)
+
+    # def get_langchain_tool_by_id(self, id):
+    #     return self.langchain_tools[id]
+
+    @staticmethod
+    def load_registry(filename):
+        with open(filename, "rb") as file:
+            return pickle.load(file)

Biomni/biomni/utils.py

@@ -0,0 +1,2469 @@
+import ast
+import enum
+import importlib
+import json
+import os
+import pickle
+import subprocess
+import tempfile
+import traceback
+import zipfile
+from typing import Any, ClassVar
+from urllib.parse import urljoin
+
+import pandas as pd
+import requests
+import tqdm  # Add tqdm for progress bar
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.messages.base import get_msg_title_repr
+from langchain_core.tools import StructuredTool
+from langchain_core.utils.interactive_env import is_interactive_env
+from pydantic import BaseModel, Field, ValidationError
+
+
+# Add these new functions for running R code and CLI commands
+def run_r_code(code: str) -> str:
+    """Run R code using subprocess.
+
+    Args:
+        code: R code to run
+
+    Returns:
+        Output of the R code
+
+    """
+    try:
+        # Create a temporary file to store the R code
+        with tempfile.NamedTemporaryFile(suffix=".R", mode="w", delete=False) as f:
+            f.write(code)
+            temp_file = f.name
+
+        # Run the R code using Rscript
+        result = subprocess.run(["Rscript", temp_file], capture_output=True, text=True, check=False)
+
+        # Clean up the temporary file
+        os.unlink(temp_file)
+
+        # Return the output
+        if result.returncode != 0:
+            return f"Error running R code:\n{result.stderr}"
+        else:
+            return result.stdout
+    except Exception as e:
+        return f"Error running R code: {str(e)}"
+
+
+def run_bash_script(script: str) -> str:
+    """Run a Bash script using subprocess.
+
+    Args:
+        script: Bash script to run
+
+    Returns:
+        Output of the Bash script
+
+    Example:
+        This is how to use the function
+
+        .. code-block:: python
+
+            # Example of a complex Bash script
+            script = '''
+            #!/bin/bash
+
+            # Define variables
+            DATA_DIR="/path/to/data"
+            OUTPUT_FILE="results.txt"
+
+            # Create output directory if it doesn't exist
+            mkdir -p $(dirname $OUTPUT_FILE)
+
+            # Loop through files
+            for file in $DATA_DIR/*.txt; do
+                echo "Processing $file..."
+                # Count lines in each file
+                line_count=$(wc -l < $file)
+                echo "$file: $line_count lines" >> $OUTPUT_FILE
+            done
+
+            echo "Processing complete. Results saved to $OUTPUT_FILE"
+            '''
+            result = run_bash_script(script)
+            print(result)
+
+    """
+    try:
+        # Trim any leading/trailing whitespace
+        script = script.strip()
+
+        # If the script is empty, return an error
+        if not script:
+            return "Error: Empty script"
+
+        # Create a temporary file to store the Bash script
+        with tempfile.NamedTemporaryFile(suffix=".sh", mode="w", delete=False) as f:
+            # Add shebang if not present
+            if not script.startswith("#!/"):
+                f.write("#!/bin/bash\n")
+            # Add set -e to exit on error
+            if "set -e" not in script:
+                f.write("set -e\n")
+            f.write(script)
+            temp_file = f.name
+
+        # Make the script executable
+        os.chmod(temp_file, 0o755)
+
+        # Get current environment variables and working directory
+        env = os.environ.copy()
+        cwd = os.getcwd()
+
+        # Run the Bash script with the current environment and working directory
+        result = subprocess.run(
+            [temp_file],
+            shell=True,
+            capture_output=True,
+            text=True,
+            check=False,
+            env=env,
+            cwd=cwd,
+        )
+
+        # Clean up the temporary file
+        os.unlink(temp_file)
+
+        # Return the output
+        if result.returncode != 0:
+            traceback.print_stack()
+            print(result)
+            return f"Error running Bash script (exit code {result.returncode}):\n{result.stderr}"
+        else:
+            return result.stdout
+    except Exception as e:
+        traceback.print_exc()
+        return f"Error running Bash script: {str(e)}"
+
+
+# Keep the run_cli_command for backward compatibility
+def run_cli_command(command: str) -> str:
+    """Run a CLI command using subprocess.
+
+    Args:
+        command: CLI command to run
+
+    Returns:
+        Output of the CLI command
+
+    """
+    try:
+        # Trim any leading/trailing whitespace
+        command = command.strip()
+
+        # If the command is empty, return an error
+        if not command:
+            return "Error: Empty command"
+
+        # Split the command into a list of arguments, handling quoted arguments correctly
+        import shlex
+
+        args = shlex.split(command)
+
+        # Run the command
+        result = subprocess.run(args, capture_output=True, text=True, check=False)
+
+        # Return the output
+        if result.returncode != 0:
+            return f"Error running command '{command}':\n{result.stderr}"
+        else:
+            return result.stdout
+    except Exception as e:
+        return f"Error running command '{command}': {str(e)}"
+
+
+def run_with_timeout(func, args=None, kwargs=None, timeout=600):
+    """Run a function with a timeout using threading instead of multiprocessing.
+    This allows variables to persist in the global namespace between function calls.
+    Returns the function result or a timeout error message.
+    """
+    if args is None:
+        args = []
+    if kwargs is None:
+        kwargs = {}
+
+    import ctypes
+    import queue
+    import threading
+
+    result_queue = queue.Queue()
+
+    def thread_func(func, args, kwargs, result_queue):
+        """Function to run in a separate thread."""
+        try:
+            result = func(*args, **kwargs)
+            result_queue.put(("success", result))
+        except Exception as e:
+            result_queue.put(("error", str(e)))
+
+    # Start a separate thread
+    thread = threading.Thread(target=thread_func, args=(func, args, kwargs, result_queue))
+    thread.daemon = True  # Set as daemon so it will be killed when main thread exits
+    thread.start()
+
+    # Wait for the specified timeout
+    thread.join(timeout)
+
+    # Check if the thread is still running after timeout
+    if thread.is_alive():
+        print(f"TIMEOUT: Code execution timed out after {timeout} seconds")
+
+        # Unfortunately, there's no clean way to force terminate a thread in Python
+        # The recommended approach is to use daemon threads and let them be killed when main thread exits
+        # Here, we'll try to raise an exception in the thread to make it stop
+        try:
+            # Get thread ID and try to terminate it
+            thread_id = thread.ident
+            if thread_id:
+                # This is a bit dangerous and not 100% reliable
+                # It attempts to raise a SystemExit exception in the thread
+                res = ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_long(thread_id), ctypes.py_object(SystemExit))
+                if res > 1:
+                    # Oops, we raised too many exceptions
+                    ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_long(thread_id), None)
+        except Exception as e:
+            print(f"Error trying to terminate thread: {e}")
+
+        return f"ERROR: Code 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 available
+    try:
+        status, result = result_queue.get(block=False)
+        return result if status == "success" else f"Error in execution: {result}"
+    except queue.Empty:
+        return "Error: Execution completed but no result was returned"
+
+
+class api_schema(BaseModel):
+    """api schema specification."""
+
+    api_schema: str | None = Field(description="The api schema as a dictionary")
+
+
+def function_to_api_schema(function_string, llm):
+    prompt = """
+    Based on a code snippet and help me write an API docstring in the format like this:
+
+    {{'name': 'get_gene_set_enrichment',
+    'description': 'Given a list of genes, identify a pathway that is enriched for this gene set. Return a list of pathway name, p-value, z-scores.',
+    'required_parameters': [{{'name': 'genes',
+    'type': 'List[str]',
+    'description': 'List of g`ene symbols to analyze',
+    'default': None}}],
+    'optional_parameters': [{{'name': 'top_k',
+    'type': 'int',
+    'description': 'Top K pathways to return',
+    'default': 10}},  {{'name': 'database',
+    'type': 'str',
+    'description': 'Name of the database to use for enrichment analysis',
+    'default': "gene_ontology"}}]}}
+
+    Strictly follow the input from the function - don't create fake optional parameters.
+    For variable without default values, set them as None, not null.
+    For variable with boolean values, use capitalized True or False, not true or false.
+    Do not add any return type in the docstring.
+    Be as clear and succint as possible for the descriptions. Please do not make it overly verbose.
+    Here is the code snippet:
+    {code}
+    """
+    llm = llm.with_structured_output(api_schema)
+
+    for _ in range(7):
+        try:
+            api = llm.invoke(prompt.format(code=function_string)).dict()["api_schema"]
+            return ast.literal_eval(api)  # -> prefer "default": None
+            # return json.loads(api) # -> prefer "default": null
+        except Exception as e:
+            print("API string:", api)
+            print("Error parsing the API string:", e)
+            continue
+
+    return "Error: Could not parse the API schema"
+    # return
+
+
+def get_all_functions_from_file(file_path):
+    with open(file_path) as file:
+        file_content = file.read()
+
+    # Parse the file content into an AST (Abstract Syntax Tree)
+    tree = ast.parse(file_content)
+
+    # List to hold the top-level functions as strings
+    functions = []
+
+    # Walk through the AST nodes
+    for node in tree.body:  # Only consider top-level nodes in the body
+        if isinstance(node, ast.FunctionDef):  # Check if the node is a function definition
+            # Skip if function name starts with underscore
+            if node.name.startswith("_"):
+                continue
+
+            start_line = node.lineno - 1  # Get the starting line of the function
+            end_line = node.end_lineno  # Get the ending line of the function (only available in Python 3.8+)
+            func_code = file_content.splitlines()[start_line:end_line]
+            functions.append("\n".join(func_code))  # Join lines of the function and add to the list
+
+    return functions
+
+
+def write_python_code(request: str):
+    from langchain_anthropic import ChatAnthropic
+    from langchain_core.output_parsers import StrOutputParser
+    from langchain_core.prompts import ChatPromptTemplate
+
+    model = ChatAnthropic(model="claude-3-5-sonnet-20240620")
+    template = """Write some python code to solve the user's problem.
+
+    Return only python code in Markdown format, e.g.:
+
+    ```python
+    ....
+    ```"""
+    prompt = ChatPromptTemplate.from_messages([("system", template), ("human", "{input}")])
+
+    def _sanitize_output(text: str):
+        _, after = text.split("```python")
+        return after.split("```")[0]
+
+    chain = prompt | model | StrOutputParser() | _sanitize_output
+    return chain.invoke({"input": "write a code that " + request})
+
+
+def execute_graphql_query(
+    query: str,
+    variables: dict,
+    api_address: str = "https://api.genetics.opentargets.org/graphql",
+) -> dict:
+    """Executes a GraphQL query with variables and returns the data as a dictionary."""
+    headers = {"Content-Type": "application/json"}
+    response = requests.post(api_address, json={"query": query, "variables": variables}, headers=headers)
+    if response.status_code == 200:
+        return response.json()
+    else:
+        print(response.text)
+        response.raise_for_status()
+
+
+def get_tool_decorated_functions(relative_path):
+    import ast
+    import importlib.util
+    import os
+
+    # Get the directory of the current file (__init__.py)
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # Construct the absolute path from the relative path
+    file_path = os.path.join(current_dir, relative_path)
+
+    with open(file_path) as file:
+        tree = ast.parse(file.read(), filename=file_path)
+
+    tool_function_names = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            for decorator in node.decorator_list:
+                if (
+                    isinstance(decorator, ast.Name)
+                    and decorator.id == "tool"
+                    or (
+                        isinstance(decorator, ast.Call)
+                        and isinstance(decorator.func, ast.Name)
+                        and decorator.func.id == "tool"
+                    )
+                ):
+                    tool_function_names.append(node.name)
+
+    # Calculate the module name from the relative path
+    package_path = os.path.relpath(file_path, start=current_dir)
+    module_name = package_path.replace(os.path.sep, ".").rsplit(".", 1)[0]
+
+    # Import the module and get the function objects
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    tool_functions = [getattr(module, name) for name in tool_function_names]
+
+    return tool_functions
+
+
+def process_bio_retrieval_ducoment(documents_df):
+    ir_corpus = {}
+    corpus2tool = {}
+    for row in documents_df.itertuples():
+        doc = row.document_content
+        ir_corpus[row.docid] = (
+            (doc.get("name", "") or "")
+            + ", "
+            + (doc.get("description", "") or "")
+            + ", "
+            + (doc.get("url", "") or "")
+            + ", "
+            + ", required_params: "
+            + json.dumps(doc.get("required_parameters", ""))
+            + ", optional_params: "
+            + json.dumps(doc.get("optional_parameters", ""))
+        )
+
+        corpus2tool[
+            (doc.get("name", "") or "")
+            + ", "
+            + (doc.get("description", "") or "")
+            + ", "
+            + (doc.get("url", "") or "")
+            + ", "
+            + ", required_params: "
+            + json.dumps(doc.get("required_parameters", ""))
+            + ", optional_params: "
+            + json.dumps(doc.get("optional_parameters", ""))
+        ] = doc["name"]
+    return ir_corpus, corpus2tool
+
+
+def load_pickle(file):
+    import pickle
+
+    with open(file, "rb") as f:
+        return pickle.load(f)
+
+
+def pretty_print(message, printout=True):
+    if isinstance(message, tuple):
+        title = message
+    elif isinstance(message.content, list):
+        title = get_msg_title_repr(message.type.title().upper() + " Message", bold=is_interactive_env())
+        if message.name is not None:
+            title += f"\nName: {message.name}"
+
+        for i in message.content:
+            if i["type"] == "text":
+                title += f"\n{i['text']}\n"
+            elif i["type"] == "tool_use":
+                title += f"\nTool: {i['name']}"
+                title += f"\nInput: {i['input']}"
+        if printout:
+            print(f"{title}")
+    else:
+        title = get_msg_title_repr(message.type.title() + " Message", bold=is_interactive_env())
+        if message.name is not None:
+            title += f"\nName: {message.name}"
+        title += f"\n\n{message.content}"
+        if printout:
+            print(f"{title}")
+    return title
+
+
+class CustomBaseModel(BaseModel):
+    api_schema: ClassVar[dict] = None  # Class variable to store api_schema
+
+    # Add model_config with arbitrary_types_allowed=True
+    model_config = {"arbitrary_types_allowed": True}
+
+    @classmethod
+    def set_api_schema(cls, schema: dict):
+        cls.api_schema = schema
+
+    @classmethod
+    def model_validate(cls, obj):
+        try:
+            return super().model_validate(obj)
+        except (ValidationError, AttributeError) as e:
+            if not cls.api_schema:
+                raise e  # If no api_schema is set, raise original error
+
+            error_msg = "Required Parameters:\n"
+            for param in cls.api_schema["required_parameters"]:
+                error_msg += f"- {param['name']} ({param['type']}): {param['description']}\n"
+
+            error_msg += "\nErrors:\n"
+            for err in e.errors():
+                field = err["loc"][0] if err["loc"] else "input"
+                error_msg += f"- {field}: {err['msg']}\n"
+
+            if not obj:
+                error_msg += "\nNo input provided"
+            else:
+                error_msg += "\nProvided Input:\n"
+                for key, value in obj.items():
+                    error_msg += f"- {key}: {value}\n"
+
+                missing_params = {param["name"] for param in cls.api_schema["required_parameters"]} - set(obj.keys())
+                if missing_params:
+                    error_msg += "\nMissing Parameters:\n"
+                    for param in missing_params:
+                        error_msg += f"- {param}\n"
+
+            # # Create proper validation error structure
+            raise ValidationError.from_exception_data(
+                title="Validation Error",
+                line_errors=[
+                    {
+                        "type": "value_error",
+                        "loc": ("input",),
+                        "input": obj,
+                        "ctx": {
+                            "error": error_msg,
+                        },
+                    }
+                ],
+            ) from None
+
+
+def safe_execute_decorator(func):
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            return str(e)
+
+    return wrapper
+
+
+def api_schema_to_langchain_tool(api_schema, mode="generated_tool", module_name=None):
+    if mode == "generated_tool":
+        module = importlib.import_module("biomni.tool.generated_tool." + api_schema["tool_name"] + ".api")
+    elif mode == "custom_tool":
+        module = importlib.import_module(module_name)
+
+    api_function = getattr(module, api_schema["name"])
+    api_function = safe_execute_decorator(api_function)
+
+    # Define a mapping from string type names to actual Python type objects
+    type_mapping = {
+        "string": str,
+        "integer": int,
+        "boolean": bool,
+        "pandas": pd.DataFrame,  # Use the imported pandas.DataFrame directly
+        "str": str,
+        "int": int,
+        "bool": bool,
+        "List[str]": list[str],
+        "List[int]": list[int],
+        "Dict": dict,
+        "Any": Any,
+    }
+
+    # Create the fields and annotations
+    annotations = {}
+    for param in api_schema["required_parameters"]:
+        param_type = param["type"]
+        if param_type in type_mapping:
+            annotations[param["name"]] = type_mapping[param_type]
+        else:
+            # For types not in the mapping, try a safer approach than direct eval
+            try:
+                annotations[param["name"]] = eval(param_type)
+            except (NameError, SyntaxError):
+                # Default to Any for unknown types
+                annotations[param["name"]] = Any
+
+    fields = {param["name"]: Field(description=param["description"]) for param in api_schema["required_parameters"]}
+
+    # Create the ApiInput class dynamically
+    ApiInput = type("Input", (CustomBaseModel,), {"__annotations__": annotations, **fields})
+    # Set the api_schema
+    ApiInput.set_api_schema(api_schema)
+
+    # Create the StructuredTool
+    api_tool = StructuredTool.from_function(
+        func=api_function,
+        name=api_schema["name"],
+        description=api_schema["description"],
+        args_schema=ApiInput,
+        return_direct=True,
+    )
+
+    return api_tool
+
+
+class ID(enum.Enum):
+    ENTREZ = "Entrez"
+    ENSEMBL = "Ensembl without version"  # e.g. ENSG00000123374
+    ENSEMBL_W_VERSION = "Ensembl with version"  # e.g. ENSG00000123374.10 (needed for GTEx)
+
+
+def get_gene_id(gene_symbol: str, id_type: ID):
+    """Get the ID for a gene symbol. If no match found, returns None."""
+    if id_type == ID.ENTREZ:
+        return _get_gene_id_entrez(gene_symbol)
+    elif id_type == ID.ENSEMBL:
+        return _get_gene_id_ensembl(gene_symbol)
+    elif id_type == ID.ENSEMBL_W_VERSION:
+        return _get_gene_id_ensembl_with_version(gene_symbol)
+    else:
+        raise ValueError(f"ID type {id_type} not supported")
+
+
+def _get_gene_id_entrez(gene_symbol: str):
+    """Get the Entrez ID for a gene symbol. If no match found, returns None
+    e.g. 1017 (CDK2).
+    """
+    api_call = f"https://mygene.info/v3/query?species=human&q=symbol:{gene_symbol}"
+    response = requests.get(api_call)
+    response_json = response.json()
+
+    if len(response_json["hits"]) == 0:
+        return None
+    else:
+        return response_json["hits"][0]["entrezgene"]
+
+
+def _get_gene_id_ensembl(gene_symbol):
+    """Get the Ensembl ID for a gene symbol. If no match found, returns None
+    e.g. ENSG00000123374.
+    """
+    api_call = f"https://mygene.info/v3/query?species=human&fields=ensembl&q=symbol:{gene_symbol}"
+    response = requests.get(api_call)
+    response_json = response.json()
+
+    if len(response_json["hits"]) == 0:
+        return None
+    else:
+        ensembl = response_json["hits"][0]["ensembl"]
+        if isinstance(ensembl, list):
+            return ensembl[0][
+                "gene"
+            ]  # Sometimes returns a list, for example RNH1 (first elem is on chr11, second is on scaffold_hschr11)
+        else:
+            return ensembl["gene"]
+
+
+def _get_gene_id_ensembl_with_version(gene_symbol):
+    """Get the Ensembl ID for a gene symbol. If no match found, returns None
+    e.g. ENSG00000123374.10.
+    """
+    api_base = "https://gtexportal.org/api/v2/reference/gene"
+    params = {"geneId": gene_symbol}
+    response_json = requests.get(api_base, params=params).json()
+
+    if len(response_json["data"]) == 0:
+        return None
+    else:
+        return response_json["data"][0]["gencodeId"]
+
+
+def save_pkl(f, filename):
+    with open(filename, "wb") as file:
+        pickle.dump(f, file)
+
+
+def load_pkl(filename):
+    with open(filename, "rb") as file:
+        return pickle.load(file)
+
+
+_TEXT_COLOR_MAPPING = {
+    "blue": "36;1",
+    "yellow": "33;1",
+    "pink": "38;5;200",
+    "green": "32;1",
+    "red": "31;1",
+}
+
+
+def color_print(text, color="blue"):
+    color_str = _TEXT_COLOR_MAPPING[color]
+    print(f"\u001b[{color_str}m\033[1;3m{text}\u001b[0m")
+
+
+class PromptLogger(BaseCallbackHandler):
+    def on_chat_model_start(self, serialized, messages, **kwargs):
+        for message in messages[0]:
+            color_print(message.pretty_repr(), color="green")
+
+
+class NodeLogger(BaseCallbackHandler):
+    def on_llm_end(self, response, **kwargs):  # response of type LLMResult
+        for generations in response.generations:  # response.generations of type List[List[Generations]] becuase "each input could have multiple candidate generations"
+            for generation in generations:
+                generated_text = generation.message.content
+                # token_usage = generation.message.response_metadata["token_usage"]
+                color_print(generated_text, color="yellow")
+
+    def on_agent_action(self, action, **kwargs):
+        color_print(action.log, color="pink")
+
+    def on_agent_finish(self, finish, **kwargs):
+        color_print(finish, color="red")
+
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        tool_name = serialized.get("name")
+        color_print(f"Calling {tool_name} with inputs: {input_str}", color="pink")
+
+    def on_tool_end(self, output, **kwargs):
+        output = str(output)
+        color_print(output, color="blue")
+
+
+class TokenUsageTracker(BaseCallbackHandler):
+    """Collect provider-reported token usage across LangChain LLM calls."""
+
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.prompt_tokens = 0
+        self.completion_tokens = 0
+        self.total_tokens = 0
+        self.call_count = 0
+
+    def snapshot(self):
+        return {
+            "prompt_tokens": int(self.prompt_tokens),
+            "completion_tokens": int(self.completion_tokens),
+            "total_tokens": int(self.total_tokens),
+            "llm_call_count": int(self.call_count),
+        }
+
+    def on_llm_end(self, response, **kwargs):
+        usage = self._extract_usage(response)
+        if not usage:
+            return
+        self.prompt_tokens += usage.get("prompt_tokens", 0)
+        self.completion_tokens += usage.get("completion_tokens", 0)
+        self.total_tokens += usage.get("total_tokens", 0)
+        self.call_count += 1
+
+    def _extract_usage(self, response):
+        llm_output = getattr(response, "llm_output", None)
+        if isinstance(llm_output, dict):
+            usage = self._normalize_usage(llm_output)
+            if usage:
+                return usage
+
+        generations = getattr(response, "generations", None) or []
+        for generation_group in generations:
+            for generation in generation_group:
+                message = getattr(generation, "message", None)
+                metadata = getattr(message, "response_metadata", None)
+                usage = self._normalize_usage(metadata)
+                if usage:
+                    return usage
+                usage_meta = getattr(message, "usage_metadata", None)
+                usage = self._normalize_usage(usage_meta)
+                if usage:
+                    return usage
+                generation_info = getattr(generation, "generation_info", None)
+                usage = self._normalize_usage(generation_info)
+                if usage:
+                    return usage
+        return None
+
+    def _normalize_usage(self, payload):
+        if not isinstance(payload, dict):
+            return None
+        nested = None
+        for key in ("token_usage", "usage", "usage_metadata"):
+            value = payload.get(key)
+            if isinstance(value, dict):
+                nested = value
+                break
+        source = nested or payload
+
+        prompt = self._first_int(
+            source,
+            "prompt_tokens",
+            "input_tokens",
+            "prompt_token_count",
+        )
+        completion = self._first_int(
+            source,
+            "completion_tokens",
+            "output_tokens",
+            "completion_token_count",
+        )
+        total = self._first_int(
+            source,
+            "total_tokens",
+            "total_token_count",
+        )
+        if total is None and prompt is not None and completion is not None:
+            total = prompt + completion
+        if prompt is None and completion is None and total is None:
+            return None
+        return {
+            "prompt_tokens": int(prompt or 0),
+            "completion_tokens": int(completion or 0),
+            "total_tokens": int(total or 0),
+        }
+
+    @staticmethod
+    def _first_int(payload, *keys):
+        for key in keys:
+            value = payload.get(key)
+            if isinstance(value, int):
+                return value
+            if isinstance(value, float):
+                return int(value)
+        return None
+
+
+def check_or_create_path(path=None):
+    # Set a default path if none is provided
+    if path is None:
+        path = os.path.join(os.getcwd(), "tmp_directory")
+
+    # Check if the path exists
+    if not os.path.exists(path):
+        # If it doesn't exist, create the directory
+        os.makedirs(path)
+        print(f"Directory created at: {path}")
+    else:
+        print(f"Directory already exists at: {path}")
+
+    return path
+
+
+def langchain_to_gradio_message(message):
+    # Build the title and content based on the message type
+    if isinstance(message.content, list):
+        # For a message with multiple content items (like text and tool use)
+        gradio_messages = []
+        for item in message.content:
+            gradio_message = {
+                "role": "user" if message.type == "human" else "assistant",
+                "content": "",
+                "metadata": {},
+            }
+
+            if item["type"] == "text":
+                item["text"] = item["text"].replace("<think>", "\n")
+                item["text"] = item["text"].replace("</think>", "\n")
+                gradio_message["content"] += f"{item['text']}\n"
+                gradio_messages.append(gradio_message)
+            elif item["type"] == "tool_use":
+                if item["name"] == "run_python_repl":
+                    gradio_message["metadata"]["title"] = "🛠️ Writing code..."
+                    # input = "```python {code_block}```\n".format(code_block=item['input']["command"])
+                    gradio_message["metadata"]["log"] = "Executing Code block..."
+                    gradio_message["content"] = f"##### Code: \n ```python \n {item['input']['command']} \n``` \n"
+                else:
+                    gradio_message["metadata"]["title"] = f"🛠️ Used tool ```{item['name']}```"
+                    to_print = ";".join([i + ": " + str(j) for i, j in item["input"].items()])
+                    gradio_message["metadata"]["log"] = f"🔍 Input -- {to_print}\n"
+                gradio_message["metadata"]["status"] = "pending"
+                gradio_messages.append(gradio_message)
+
+    else:
+        gradio_message = {
+            "role": "user" if message.type == "human" else "assistant",
+            "content": "",
+            "metadata": {},
+        }
+        print(message)
+        content = message.content
+        content = content.replace("<think>", "\n")
+        content = content.replace("</think>", "\n")
+        content = content.replace("<solution>", "\n")
+        content = content.replace("</solution>", "\n")
+
+        gradio_message["content"] = content
+        gradio_messages = [gradio_message]
+    return gradio_messages
+
+
+def parse_hpo_obo(file_path):
+    """Parse the HPO OBO file and create a dictionary mapping HP IDs to phenotype descriptions.
+
+    Args:
+        file_path (str): Path to the HPO OBO file.
+
+    Returns:
+        dict: A dictionary where keys are HP IDs and values are phenotype descriptions.
+
+    """
+    hp_dict = {}
+    current_id = None
+    current_name = None
+
+    with open(file_path) as file:
+        for line in file:
+            line = line.strip()
+            if line.startswith("[Term]"):
+                # If a new term block starts, save the previous term
+                if current_id and current_name:
+                    hp_dict[current_id] = current_name
+                current_id = None
+                current_name = None
+            elif line.startswith("id: HP:"):
+                current_id = line.split(": ")[1]
+            elif line.startswith("name:"):
+                current_name = line.split(": ", 1)[1]
+
+        # Add the last term to the dictionary
+        if current_id and current_name:
+            hp_dict[current_id] = current_name
+
+    return hp_dict
+
+
+def textify_api_dict(api_dict):
+    """Convert a nested API dictionary to a nicely formatted string."""
+    lines = []
+    for category, methods in api_dict.items():
+        lines.append(f"Import file: {category}")
+        lines.append("=" * (len("Import file: ") + len(category)))
+        for method in methods:
+            lines.append(f"Method: {method.get('name', 'N/A')}")
+            lines.append(f"  Description: {method.get('description', 'No description provided.')}")
+
+            # Process required parameters
+            req_params = method.get("required_parameters", [])
+            if req_params:
+                lines.append("  Required Parameters:")
+                for param in req_params:
+                    param_name = param.get("name", "N/A")
+                    param_type = param.get("type", "N/A")
+                    param_desc = param.get("description", "No description")
+                    param_default = param.get("default", "None")
+                    lines.append(f"    - {param_name} ({param_type}): {param_desc} [Default: {param_default}]")
+
+            # Process optional parameters
+            opt_params = method.get("optional_parameters", [])
+            if opt_params:
+                lines.append("  Optional Parameters:")
+                for param in opt_params:
+                    param_name = param.get("name", "N/A")
+                    param_type = param.get("type", "N/A")
+                    param_desc = param.get("description", "No description")
+                    param_default = param.get("default", "None")
+                    lines.append(f"    - {param_name} ({param_type}): {param_desc} [Default: {param_default}]")
+
+            lines.append("")  # Empty line between methods
+        lines.append("")  # Extra empty line after each category
+
+    return "\n".join(lines)
+
+
+def read_module2api():
+    fields = [
+        "literature",
+        "biochemistry",
+        "bioimaging",
+        "bioengineering",
+        "biophysics",
+        "glycoengineering",
+        "cancer_biology",
+        "cell_biology",
+        "molecular_biology",
+        "genetics",
+        "genomics",
+        "immunology",
+        "microbiology",
+        "pathology",
+        "pharmacology",
+        "physiology",
+        "synthetic_biology",
+        "systems_biology",
+        "support_tools",
+        "database",
+        "lab_automation",
+        "protocols",
+    ]
+
+    module2api = {}
+    for field in fields:
+        module_name = f"biomni.tool.tool_description.{field}"
+        module = importlib.import_module(module_name)
+        module2api[f"biomni.tool.{field}"] = module.description
+    return module2api
+
+
+def download_and_unzip(url: str, dest_dir: str) -> str:
+    """Download a zip file from a URL and extract it to the destination directory.
+
+    Args:
+        url: The URL to download the zip file from.
+        dest_dir: The directory to extract the contents to.
+
+    Returns:
+        The path to the extracted directory, or an error message.
+
+    """
+    try:
+        os.makedirs(dest_dir, exist_ok=True)
+        print(f"Downloading from {url} ...")
+        with requests.get(url, stream=True) as r:
+            r.raise_for_status()
+            total_size = int(r.headers.get("content-length", 0))
+            chunk_size = 8192
+            with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp_file:
+                with tqdm.tqdm(
+                    total=total_size / (1024**3),
+                    unit="GB",
+                    unit_scale=True,
+                    desc="Downloading",
+                    ncols=80,
+                ) as pbar:
+                    for chunk in r.iter_content(chunk_size=chunk_size):
+                        if chunk:
+                            tmp_file.write(chunk)
+                            pbar.update(len(chunk) / (1024**3))
+                tmp_zip_path = tmp_file.name
+        print(f"Downloaded to {tmp_zip_path}. Extracting...")
+        with zipfile.ZipFile(tmp_zip_path, "r") as zip_ref:
+            zip_ref.extractall(dest_dir)
+        os.unlink(tmp_zip_path)
+        print(f"Extraction complete to {dest_dir}")
+        return dest_dir
+    except Exception as e:
+        print(f"Error downloading or extracting zip: {e}")
+        return f"Error: {e}"
+
+
+def check_and_download_s3_files(
+    s3_bucket_url: str, local_data_lake_path: str, expected_files: list[str], folder: str = "data_lake"
+) -> dict[str, bool]:
+    """Check for missing files in the local data lake and download them from S3 bucket.
+
+    Args:
+        s3_bucket_url: Base URL of the S3 bucket (e.g., "https://biomni-release.s3.amazonaws.com")
+        local_data_lake_path: Local path to the data lake directory
+        expected_files: List of expected file names in the data lake
+        folder: S3 folder name ("data_lake" or "benchmark")
+
+    Returns:
+        Dictionary mapping file names to download success status
+    """
+
+    os.makedirs(local_data_lake_path, exist_ok=True)
+    download_results = {}
+
+    def download_with_progress(url: str, file_path: str, desc: str) -> bool:
+        """Download file with progress bar."""
+        try:
+            response = requests.get(url, stream=True)
+            response.raise_for_status()
+
+            total_size = int(response.headers.get("content-length", 0))
+
+            with open(file_path, "wb") as f:
+                if total_size > 0:
+                    with tqdm.tqdm(total=total_size, unit="B", unit_scale=True, desc=desc, ncols=80) as pbar:
+                        for chunk in response.iter_content(chunk_size=8192):
+                            if chunk:
+                                f.write(chunk)
+                                pbar.update(len(chunk))
+                else:
+                    for chunk in response.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+            return True
+        except Exception as e:
+            print(f"✗ Failed to download {desc}: {e}")
+            if os.path.exists(file_path):
+                try:
+                    os.remove(file_path)
+                except OSError:
+                    pass
+            return False
+
+    def cleanup_file(file_path: str):
+        """Clean up file if it exists."""
+        if os.path.exists(file_path):
+            try:
+                os.remove(file_path)
+            except OSError:
+                pass
+
+    # Handle benchmark folder (download as zip)
+    if folder == "benchmark":
+        print(f"Downloading entire {folder} folder structure...")
+        s3_zip_url = urljoin(s3_bucket_url + "/", folder + ".zip")
+
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp_zip:
+            tmp_zip_path = tmp_zip.name
+
+            if download_with_progress(s3_zip_url, tmp_zip_path, f"{folder}.zip"):
+                print(f"Extracting {folder}.zip...")
+                try:
+                    with zipfile.ZipFile(tmp_zip_path, "r") as zip_ref:
+                        zip_ref.extractall(local_data_lake_path)
+                    print(f"✓ Successfully downloaded and extracted {folder} folder")
+                    download_results = dict.fromkeys(expected_files, True)
+                except Exception as e:
+                    print(f"✗ Error extracting {folder}.zip: {e}")
+                    download_results = dict.fromkeys(expected_files, False)
+                finally:
+                    cleanup_file(tmp_zip_path)
+            else:
+                download_results = dict.fromkeys(expected_files, False)
+
+        return download_results
+
+    # Handle data_lake folder (download individual files)
+    for filename in expected_files:
+        local_file_path = os.path.join(local_data_lake_path, filename)
+
+        if os.path.exists(local_file_path):
+            download_results[filename] = True
+            continue
+
+        s3_file_url = urljoin(s3_bucket_url + "/" + folder + "/", filename)
+        print(f"Downloading {filename} from {folder}...")
+
+        if download_with_progress(s3_file_url, local_file_path, filename):
+            print(f"✓ Successfully downloaded: {filename}")
+            download_results[filename] = True
+        else:
+            download_results[filename] = False
+
+    return download_results
+
+
+def clean_message_content(content: str) -> str:
+    """Clean message content by removing ANSI escape codes.
+
+    This function removes ANSI escape sequences (like color codes) from text content
+    that might be present in terminal output or console messages. This ensures clean
+    text for markdown generation and PDF conversion.
+
+    Args:
+        content: The raw message content that may contain ANSI escape codes
+
+    Returns:
+        Cleaned content with ANSI escape codes removed
+
+    Example:
+        >>> clean_message_content("Hello \x1b[31mworld\x1b[0m!")
+        "Hello world!"
+    """
+    import re
+
+    return re.sub(r"\x1b\[[0-9;]*m", "", content)
+
+
+def should_skip_message(clean_output: str) -> bool:
+    """Check if message should be skipped during markdown generation.
+
+    This function determines whether a message should be excluded from the final
+    markdown output. It skips empty or meaningless messages but preserves important
+    error messages that should be displayed to users.
+
+    Args:
+        clean_output: The cleaned message content to evaluate
+
+    Returns:
+        True if the message should be skipped, False otherwise
+
+    Note:
+        Parsing error messages are intentionally not skipped as they provide
+        important feedback to users about conversation flow issues.
+    """
+    return (
+        clean_output.strip() in ["", "None", "null", "undefined"]
+        # Don't skip parsing error messages - they should be displayed and increment step counter
+        # or "There are no tags" in clean_output
+        # or "Execution terminated due to repeated parsing errors" in clean_output
+    )
+
+
+def has_execution_results(clean_output: str, execution_results) -> bool:
+    """Check if message contains code execution and has associated results.
+
+    This function determines whether a message contains executable code and has
+    corresponding execution results available for display in the markdown output.
+
+    Args:
+        clean_output: The cleaned message content to check for execute tags
+        execution_results: List of execution results from the agent's execution history
+
+    Returns:
+        True if the message contains <execute> tags and has execution results available
+    """
+    return "<execute>" in clean_output and execution_results is not None and execution_results
+
+
+def find_matching_execution(clean_output: str, execution_results) -> dict | None:
+    """Find the execution result that matches the given message content.
+
+    This function searches through the execution results to find the one that
+    corresponds to the current message. It matches based on the triggering message
+    content to associate execution results with their originating AI messages.
+
+    Args:
+        clean_output: The cleaned message content to match against
+        execution_results: List of execution result dictionaries containing
+                         triggering messages and execution data
+
+    Returns:
+        The matching execution result dictionary if found, None otherwise
+
+    Note:
+        The matching is bidirectional - it checks if either the triggering message
+        is contained in the current output or vice versa to handle partial matches.
+    """
+    for exec_result in execution_results:
+        if exec_result["triggering_message"] in clean_output or clean_output in exec_result["triggering_message"]:
+            return exec_result
+    return None
+
+
+def create_parsing_error_html() -> str:
+    """Create HTML markup for displaying parsing errors in markdown output.
+
+    This function generates a styled HTML block that displays parsing errors
+    when the agent's response doesn't contain the required tags. The HTML
+    uses CSS classes for consistent styling in the final PDF output.
+
+    Returns:
+        HTML string containing a styled parsing error message box
+
+    Note:
+        The returned HTML uses CSS classes defined in get_pdf_css_content()
+        for consistent styling across the document.
+    """
+    return """
+<div class="parsing-error-box">
+    <div class="parsing-error-header">Parsing Error</div>
+    <div class="parsing-error-content">Each response must include thinking process followed by either execute or solution tag. But there are no tags in the current response.</div>
+</div>
+"""
+
+
+def parse_tool_calls_from_code(code: str, module2api: dict, custom_functions: dict = None) -> list[str]:
+    """Parse code to detect imported tools by analyzing import statements.
+
+    This function analyzes Python code to identify which tools/functions are being
+    imported and used. It extracts tool names from import statements and function
+    calls, then returns a deduplicated list of detected tool names.
+
+    Args:
+        code: The Python code string to analyze for tool imports
+        module2api: Dictionary mapping module names to their available API tools
+        custom_functions: Optional dictionary of custom functions that have been
+                         added to the agent
+
+    Returns:
+        Sorted list of unique tool names detected in the code
+
+    Example:
+        >>> code = "from biomni.tool import analyze_data\nimport pandas as pd"
+        >>> parse_tool_calls_from_code(code, module2api)
+        ['analyze_data', 'pandas']
+    """
+    tool_module_pairs = parse_tool_calls_with_modules(code, module2api, custom_functions)
+    return sorted({pair[0] for pair in tool_module_pairs})
+
+
+def parse_tool_calls_with_modules(code: str, module2api: dict, custom_functions: dict = None) -> list[tuple[str, str]]:
+    """Parse code to detect imported tools and their associated modules.
+
+    This function performs detailed analysis of Python code to identify which
+    tools/functions are being imported and which modules they belong to. It
+    handles various import patterns including direct imports, from-imports,
+    and module.function patterns.
+
+    Args:
+        code: The Python code string to analyze for tool imports
+        module2api: Dictionary mapping module names to their available API tools
+        custom_functions: Optional dictionary of custom functions that have been
+                         added to the agent
+
+    Returns:
+        List of tuples containing (tool_name, module_name) pairs for each
+        detected tool and its associated module
+
+    Note:
+        The function uses regex patterns to match various import statement
+        formats and also detects direct function calls without explicit imports.
+    """
+    import re
+
+    detected_tools = set()
+
+    # Get all available tools from module2api
+    all_tools = {}
+    for module_name, module_tools in module2api.items():
+        for tool in module_tools:
+            if isinstance(tool, dict) and "name" in tool:
+                tool_name = tool["name"]
+                if tool_name not in all_tools:
+                    all_tools[tool_name] = []
+                all_tools[tool_name].append(module_name)
+
+    # Add custom tools
+    if custom_functions:
+        for tool_name in custom_functions.keys():
+            if tool_name not in all_tools:
+                all_tools[tool_name] = []
+            all_tools[tool_name].append("custom_tools")
+
+    # Look for import statements in the code
+    import_patterns = [
+        r"from\s+([\w.]+)\s+import\s+([\w,\s]+)",  # from module import tool1, tool2
+        r"import\s+([\w.]+)",  # import module
+    ]
+
+    for pattern in import_patterns:
+        matches = re.findall(pattern, code)
+        for match in matches:
+            if len(match) == 2:  # from module import tools
+                module_name, tools_str = match
+                # Split tools by comma and clean up
+                tools = [tool.strip() for tool in tools_str.split(",")]
+
+                for tool in tools:
+                    # Check if this tool exists in any module
+                    if tool in all_tools:
+                        # Find the best matching module
+                        best_module = find_best_module_match(module_name, all_tools[tool])
+                        detected_tools.add((tool, best_module))
+                    # Also check if it's a module.function pattern
+                    elif "." in tool:
+                        parts = tool.split(".")
+                        if len(parts) == 2:
+                            module_part, func_part = parts
+                            if func_part in all_tools:
+                                best_module = find_best_module_match(module_part, all_tools[func_part])
+                                detected_tools.add((func_part, best_module))
+
+            elif len(match) == 1:  # import module
+                module_name = match[0]
+                # Check if any tools from this module are used
+                for tool_name, modules in all_tools.items():
+                    if any(module_name in mod for mod in modules):
+                        # Look for usage of this tool in the code
+                        if re.search(rf"\b{tool_name}\s*\(", code):
+                            best_module = find_best_module_match(module_name, modules)
+                            detected_tools.add((tool_name, best_module))
+
+    # Also look for direct function calls without imports
+    function_call_pattern = r"(\w+)\s*\("
+    function_calls = re.findall(function_call_pattern, code)
+
+    for func_call in function_calls:
+        if func_call in all_tools:
+            # For direct calls, use the first available module
+            best_module = all_tools[func_call][0]
+            detected_tools.add((func_call, best_module))
+
+    return sorted(detected_tools)
+
+
+def find_best_module_match(target_module: str, available_modules: list[str]) -> str:
+    """Find the best matching module from a list of available modules.
+
+    This function attempts to match a target module name against a list of
+    available modules using various matching strategies: exact match, partial
+    substring matches, and fallback to the first available module.
+
+    Args:
+        target_module: The module name we're trying to match
+        available_modules: List of available module names to search through
+
+    Returns:
+        The best matching module name from the available modules list.
+        Returns "unknown" if no modules are available.
+
+    Note:
+        The matching strategy prioritizes exact matches, then partial matches
+        (where either the target is contained in the module name or vice versa),
+        and finally falls back to the first available module.
+    """
+    # First try exact match
+    if target_module in available_modules:
+        return target_module
+
+    # Try partial matches
+    for module in available_modules:
+        if target_module in module or module in target_module:
+            return module
+
+    # Return the first available module as fallback
+    return available_modules[0] if available_modules else "unknown"
+
+
+def inject_custom_functions_to_repl(custom_functions: dict):
+    """Inject custom functions into the Python REPL execution environment.
+
+    This function makes custom tools available during code execution by injecting
+    them into both the persistent execution namespace and the builtins module.
+    This allows the agent to call custom functions that users have added via
+    agent.add_tool() when executing Python code in <execute> blocks.
+
+    Args:
+        custom_functions: Dictionary mapping function names to their callable objects
+
+    Note:
+        The function modifies both the persistent namespace used by run_python_repl
+        and the builtins module to ensure maximum compatibility and accessibility
+        of custom functions during code execution.
+    """
+    if custom_functions:
+        # Access the persistent namespace used by run_python_repl
+        from biomni.tool.support_tools import _persistent_namespace
+
+        # Inject all custom functions into the execution namespace
+        for name, func in custom_functions.items():
+            _persistent_namespace[name] = func
+
+        # Also make them available in builtins for broader access
+        import builtins
+
+        if not hasattr(builtins, "_biomni_custom_functions"):
+            builtins._biomni_custom_functions = {}
+        builtins._biomni_custom_functions.update(custom_functions)
+
+
+def format_execute_tags_in_content(content: str, parse_tool_calls_with_modules_func) -> str:
+    """Format execute tags in content by extracting code and creating highlighted tool call blocks.
+
+    This function processes content that contains <execute>...</execute> tags and
+    converts them into styled HTML blocks that display the code with syntax highlighting
+    and information about which tools are being used.
+
+    Args:
+        content: The content string that may contain <execute> tags
+        parse_tool_calls_with_modules_func: Function to parse tool calls with modules
+                                          (typically parse_tool_calls_with_modules)
+
+    Returns:
+        Formatted content with execute tags converted to highlighted tool call blocks.
+        Also processes <solution> tags in the same pass.
+
+    Note:
+        The function also calls format_solution_tags_in_content() to handle
+        solution tags in the same processing pass.
+    """
+    import re
+
+    # Pattern to match <execute>...</execute> blocks
+    execute_pattern = r"<execute>(.*?)</execute>"
+
+    def replace_execute_tag(match):
+        code_content = match.group(1).strip()
+        language, tool_name = detect_code_language_and_tool(code_content)
+        code_content = clean_code_content(code_content, language)
+
+        # Parse tools from the code content with module information
+        detected_tool_modules = parse_tool_calls_with_modules_func(code_content)
+
+        # Create the formatted block
+        formatted_block = create_tool_call_block(code_content, language, tool_name, detected_tool_modules)
+        return formatted_block
+
+    # Replace all execute tags with formatted tool call blocks
+    formatted_content = re.sub(execute_pattern, replace_execute_tag, content, flags=re.DOTALL)
+
+    # Also format solution tags
+    formatted_content = format_solution_tags_in_content(formatted_content)
+
+    return formatted_content
+
+
+def detect_code_language_and_tool(code_content: str) -> tuple[str, str]:
+    """Detect the programming language and tool name from code content.
+
+    This function analyzes code content to determine the programming language
+    and appropriate tool name based on language markers at the beginning of
+    the code block.
+
+    Args:
+        code_content: The code content to analyze for language markers
+
+    Returns:
+        Tuple containing (language, tool_name) where:
+        - language: The detected programming language ("python", "r", "bash")
+        - tool_name: The human-readable tool name for display
+
+    Example:
+        >>> detect_code_language_and_tool("#!R\nlibrary(ggplot2)")
+        ("r", "R REPL")
+        >>> detect_code_language_and_tool("#!BASH\necho 'hello'")
+        ("bash", "Bash Script")
+    """
+    if code_content.startswith("#!R") or code_content.startswith("# R code") or code_content.startswith("# R script"):
+        return "r", "R REPL"
+    elif code_content.startswith("#!BASH") or code_content.startswith("# Bash script"):
+        return "bash", "Bash Script"
+    elif code_content.startswith("#!CLI"):
+        return "bash", "CLI Command"
+    else:
+        return "python", "Python REPL"
+
+
+def clean_code_content(code_content: str, language: str) -> str:
+    """Clean code content by removing language markers.
+
+    This function removes language-specific markers from the beginning of code
+    content to prepare it for display in code blocks. The markers are used
+    internally for language detection but should not appear in the final output.
+
+    Args:
+        code_content: The raw code content that may contain language markers
+        language: The detected programming language ("python", "r", "bash")
+
+    Returns:
+        Cleaned code content with language markers removed
+
+    Example:
+        >>> clean_code_content("#!R\nlibrary(ggplot2)", "r")
+        "library(ggplot2)"
+        >>> clean_code_content("#!BASH\necho 'hello'", "bash")
+        "echo 'hello'"
+    """
+    import re
+
+    if language == "r":
+        return re.sub(r"^#!R|^# R code|^# R script", "", code_content, count=1).strip()
+    elif language == "bash":
+        if code_content.startswith("#!BASH") or code_content.startswith("# Bash script"):
+            return re.sub(r"^#!BASH|^# Bash script", "", code_content, count=1).strip()
+        elif code_content.startswith("#!CLI"):
+            return re.sub(r"^#!CLI", "", code_content, count=1).strip()
+    return code_content
+
+
+def create_tool_call_block(code_content: str, language: str, tool_name: str, detected_tool_modules: list) -> str:
+    """Create the HTML block for tool call highlighting.
+
+    This function generates a styled HTML block that displays code execution
+    information including the code itself, syntax highlighting, and a list of
+    tools that were used during execution.
+
+    Args:
+        code_content: The cleaned code content to display
+        language: The programming language for syntax highlighting
+        tool_name: The default tool name to display if no specific tools detected
+        detected_tool_modules: List of (tool_name, module_name) tuples for tools used
+
+    Returns:
+        HTML string containing a styled tool call block with code and tool information
+
+    Note:
+        The HTML uses CSS classes defined in get_pdf_css_content() for styling.
+        If no specific tools are detected, it falls back to a default tool name.
+    """
+    # Create the formatted block with code and tools used
+    formatted_block = f"""<div class="tool-call-highlight">
+<div class="tool-call-header">
+<strong>Code Execution</strong>
+</div>
+<div class="tool-call-input">
+```{language}
+{code_content}
+```
+</div>"""
+
+    # Add tools used section
+    if detected_tool_modules:
+        tools_list = format_detected_tools(detected_tool_modules)
+        formatted_block += f"""
+<div class="tools-used">
+<strong>Tools Used:</strong> {tools_list}
+</div>"""
+    else:
+        formatted_block += format_default_tool_name(language, tool_name)
+
+    formatted_block += "</div>"
+    return formatted_block
+
+
+def format_detected_tools(detected_tool_modules: list) -> str:
+    """Format detected tools with their modules for display.
+
+    This function takes a list of (tool_name, module_name) tuples and formats
+    them into a human-readable string for display in the tool call blocks.
+    It handles special cases for common tools and formats module names appropriately.
+
+    Args:
+        detected_tool_modules: List of (tool_name, module_name) tuples
+
+    Returns:
+        Comma-separated string of formatted tool descriptions
+
+    Example:
+        >>> format_detected_tools([("analyze_data", "biomni.tool"), ("pandas", "pandas")])
+        "biomni → analyze_data, pandas → pandas"
+    """
+    tool_descriptions = []
+    for tool_name, module_name in detected_tool_modules:
+        if tool_name == "python_repl":
+            tool_descriptions.append("Python REPL")
+        elif tool_name == "r_repl":
+            tool_descriptions.append("R REPL")
+        elif "bash" in tool_name.lower():
+            tool_descriptions.append("Bash Script")
+        else:
+            # Extract the last part of the module name for display
+            display_module = module_name.split(".")[-1] if "." in module_name else module_name
+            tool_descriptions.append(f"{display_module} → {tool_name}")
+
+    return ", ".join(sorted(tool_descriptions))
+
+
+def format_default_tool_name(language: str, tool_name: str) -> str:
+    """Format default tool name based on programming language.
+
+    This function generates HTML for displaying the default tool name when
+    no specific tools are detected in the code. It maps programming languages
+    to their appropriate default tool names.
+
+    Args:
+        language: The programming language ("python", "r", "bash")
+        tool_name: The detected tool name (used for bash CLI vs script distinction)
+
+    Returns:
+        HTML string containing a styled tools-used section
+
+    Note:
+        For bash, it distinguishes between CLI commands and bash scripts
+        based on the tool_name parameter.
+    """
+    if language == "r":
+        return """
+<div class="tools-used">
+<strong>Tools Used:</strong> R REPL
+</div>"""
+    elif language == "bash":
+        if tool_name == "CLI Command":
+            return """
+<div class="tools-used">
+<strong>Tools Used:</strong> CLI Command
+</div>"""
+        else:
+            return """
+<div class="tools-used">
+<strong>Tools Used:</strong> Bash Script
+</div>"""
+    else:
+        return """
+<div class="tools-used">
+<strong>Tools Used:</strong> Python REPL
+</div>"""
+
+
+def format_solution_tags_in_content(content: str) -> str:
+    """Format solution tags in content by extracting text and formatting as solution blocks.
+
+    This function processes content that contains <solution>...</solution> tags and
+    converts them into styled HTML blocks that display solution content with appropriate
+    formatting and CSS classes.
+
+    Args:
+        content: The content string that may contain <solution> tags
+
+    Returns:
+        Formatted content with solution tags converted to styled solution blocks
+
+    Note:
+        The solution blocks use the "title-text summary" CSS class for consistent
+        styling with other content blocks in the markdown output.
+    """
+    import re
+
+    # Pattern to match <solution>...</solution> blocks
+    solution_pattern = r"<solution>(.*?)</solution>"
+
+    def replace_solution_tag(match):
+        solution_content = match.group(1).strip()
+        # Format as regular text, not terminal
+        return f"""<div class="title-text summary">
+<div class="title-text-header">
+<strong>Summary and Solution</strong>
+</div>
+<div class="title-text-content">
+{solution_content}
+</div>
+</div>"""
+
+    # Replace all solution tags with formatted solution blocks
+    formatted_content = re.sub(solution_pattern, replace_solution_tag, content, flags=re.DOTALL)
+
+    return formatted_content
+
+
+def format_observation_as_terminal(content: str) -> str | None:
+    """Format observation content with terminal-like styling.
+
+    This function processes observation content from the agent's execution results
+    and formats it as a styled terminal block. It handles both text and image content,
+    with length limits to ensure the output fits within PDF page constraints.
+
+    Args:
+        content: The observation content string, potentially containing <observation> tags
+
+    Returns:
+        Formatted HTML content with terminal styling, or None if observation is
+        empty, invalid, or contains only meaningless content
+
+    Note:
+        - Content is limited to 10,000 characters to fit within 2 A4 pages
+        - Handles both text and base64-encoded images
+        - Uses CSS classes for consistent styling with other content blocks
+    """
+    import re
+
+    # Character limit for 2 A4 pages (approximately 10,000 characters)
+    MAX_OBSERVATION_LENGTH = 10000
+
+    # Remove the <observation> tags and extract the content
+    observation_pattern = r"<observation>(.*?)</observation>"
+    observation_match = re.search(observation_pattern, content, re.DOTALL)
+
+    if observation_match:
+        observation_content = observation_match.group(1).strip()
+    else:
+        # Fallback if no observation tags found - check if content is meaningful
+        if not (content.strip() and content.strip() not in ["", "None", "null", "undefined"]):
+            return None
+        observation_content = content.strip()
+
+    # Skip empty observations
+    if not observation_content or observation_content in ["", "None", "null", "undefined"]:
+        return None
+
+    # Check if observation is too long for 2 pages
+    if len(observation_content) > MAX_OBSERVATION_LENGTH:
+        cropped_content = observation_content[:MAX_OBSERVATION_LENGTH]
+        truncation_notice = f"\n\n[Output truncated - content was too long to display here ({len(observation_content)} characters total)]"
+        observation_content = cropped_content + truncation_notice
+
+    # Check if it contains plot data (base64 images)
+    if "data:image/" in observation_content:
+        content_html = process_observation_with_images(observation_content)
+    else:
+        # Regular text output - format as terminal output
+        content_html = f"```terminal\n{observation_content}\n```"
+
+    return f"""<div class="title-text observation">
+<div class="title-text-header">
+<strong>Observation</strong>
+</div>
+<div class="title-text-content">
+{content_html}
+</div>
+</div>"""
+
+
+def process_observation_with_images(observation_content: str) -> str:
+    """Process observation content that contains both text and base64-encoded images.
+
+    This function handles observation content that includes both text output and
+    base64-encoded images (typically plots from data analysis). It separates the
+    text and image content and formats them appropriately for markdown display.
+
+    Args:
+        observation_content: The observation content containing both text and images
+
+    Returns:
+        HTML string containing formatted text (as terminal blocks) and images
+        (as markdown image tags)
+
+    Note:
+        The function uses "data:image/" as a delimiter to split content into
+        text and image parts, then processes each part separately.
+    """
+    # Split content into text and image parts
+    parts = observation_content.split("data:image/")
+    text_parts = []
+    image_parts = []
+
+    for i, part in enumerate(parts):
+        if i == 0:
+            # First part is text only
+            if part.strip():
+                text_parts.append(part.strip())
+        else:
+            # Find the end of the base64 data
+            end_markers = ["\n", "\r", " ", "\t", ">", "<", "]", ")", "}"]
+            image_end = len(part)
+            for marker in end_markers:
+                marker_pos = part.find(marker)
+                if marker_pos != -1 and marker_pos < image_end:
+                    image_end = marker_pos
+
+            # Extract image data
+            image_data = "data:image/" + part[:image_end]
+            image_parts.append(image_data)
+
+            # Extract remaining text
+            remaining_text = part[image_end:].strip()
+            if remaining_text:
+                text_parts.append(remaining_text)
+
+    # Build the content
+    content_html = ""
+    if text_parts:
+        # Add text content as terminal output
+        text_content = "\n".join(text_parts)
+        content_html += f"```terminal\n{text_content}\n```\n\n"
+
+    if image_parts:
+        # Add image content
+        for image_data in image_parts:
+            content_html += f"![Plot]({image_data})\n\n"
+
+    return content_html
+
+
+def remove_emojis_from_text(text: str) -> str:
+    """Remove emojis from text for markdown/PDF output.
+
+    This function removes common emojis used in the system prompt and configuration
+    display from text content before it's converted to markdown or PDF. This ensures
+    clean, professional output while preserving emojis in the console display.
+
+    Args:
+        text: The text content that may contain emojis
+
+    Returns:
+        Text content with emojis removed
+
+    Note:
+        The function targets specific emojis used in the Biomni system:
+        - 🔧 for tools
+        - 📊 for data
+        - ⚙️ for software
+        - 📋 for configuration
+        - 🤖 for agent
+    """
+    import re
+
+    # Remove common emojis used in the system prompt, this makes conversion simpler
+    emoji_patterns = [
+        r"🔧\s*",  # Tool emoji
+        r"📊\s*",  # Data emoji
+        r"⚙️\s*",  # Software emoji
+        r"📋\s*",  # Config emoji
+        r"🤖\s*",  # Agent emoji
+    ]
+
+    for pattern in emoji_patterns:
+        text = re.sub(pattern, "", text)
+
+    return text
+
+
+def format_lists_in_text(text: str) -> str:
+    """Format numbered lists and bullet points in text to proper markdown format.
+
+    This function processes text content to identify and format various types of lists,
+    including numbered lists with checkboxes, regular lists, and plan structures.
+    It also handles preprocessing tasks like removing bold formatting from plan titles
+    and removing emojis for clean PDF output.
+
+    Args:
+        text: The text content to process for list formatting
+
+    Returns:
+        Formatted text with properly structured lists and cleaned formatting
+
+    Note:
+        The function performs several preprocessing steps:
+        - Removes bold formatting from plan titles
+        - Removes emojis for PDF output
+        - Identifies and formats checkbox lists
+        - Processes regular text blocks
+    """
+    import re
+
+    # Preprocess to remove bold formatting from plan titles
+    # Remove **Plan:**, **Updated Plan:**, **Completed Plan:**, etc.
+    text = re.sub(r"\*\*([Pp]lan|Updated [Pp]lan|Completed [Pp]lan|Final [Pp]lan):\*\*", r"\1:", text)
+    # Also handle cases without colons
+    text = re.sub(r"\*\*([Pp]lan|Updated [Pp]lan|Completed [Pp]lan|Final [Pp]lan)\*\*", r"\1", text)
+    # Handle any other bold formatting patterns for plan titles
+    text = re.sub(r"<strong>([Pp]lan|Updated [Pp]lan|Completed [Pp]lan|Final [Pp]lan):</strong>", r"\1:", text)
+    text = re.sub(r"<strong>([Pp]lan|Updated [Pp]lan|Completed [Pp]lan|Final [Pp]lan)</strong>", r"\1", text)
+
+    # Remove emojis from the text for markdown/PDF output
+    text = remove_emojis_from_text(text)
+
+    lines = text.split("\n")
+    list_blocks = identify_list_blocks(lines)
+
+    # Process each block
+    result_blocks = []
+    for block_text, is_checkbox_list in list_blocks:
+        if is_checkbox_list:
+            result_blocks.append(format_single_list(block_text))
+        else:
+            result_blocks.append(block_text)
+
+    return "\n".join(result_blocks)
+
+
+def identify_list_blocks(lines: list) -> list[tuple[str, bool]]:
+    """Identify blocks of text that contain lists.
+
+    This function analyzes a list of text lines to identify contiguous blocks
+    that contain numbered lists with checkboxes. It groups lines into blocks
+    and marks whether each block contains a checkbox list or regular text.
+
+    Args:
+        lines: List of text lines to analyze
+
+    Returns:
+        List of tuples containing (block_text, is_checkbox_list) where:
+        - block_text: The text content of the block
+        - is_checkbox_list: True if the block contains numbered items with checkboxes
+
+    Note:
+        The function looks for patterns like "1. [ ]", "2. [✓]", "3. [✗]" to
+        identify checkbox sequences and groups them into separate blocks.
+    """
+    import re
+
+    list_blocks = []
+    current_block = []
+    in_checkbox_sequence = False
+
+    for line in lines:
+        line_stripped = line.strip()
+
+        # Check if this line starts a numbered item with checkbox
+        if re.match(r"^\d+\.\s*\[[ ✓✗]\]", line_stripped):
+            if not in_checkbox_sequence:
+                # Start of a new checkbox sequence
+                if current_block:
+                    list_blocks.append(("\n".join(current_block), False))
+                current_block = [line]
+                in_checkbox_sequence = True
+            else:
+                # Continue the sequence
+                current_block.append(line)
+        else:
+            if in_checkbox_sequence:
+                # End of checkbox sequence
+                if current_block:
+                    list_blocks.append(("\n".join(current_block), True))
+                current_block = []
+                in_checkbox_sequence = False
+            current_block.append(line)
+
+    # Handle the last block
+    if current_block:
+        if in_checkbox_sequence:
+            list_blocks.append(("\n".join(current_block), True))
+        else:
+            list_blocks.append(("\n".join(current_block), False))
+
+    return list_blocks
+
+
+def format_single_list(text: str) -> str:
+    """Format a single list block with checkboxes and plan titles.
+
+    This function processes a text block that may contain numbered lists with
+    checkboxes and plan titles. It converts checkbox symbols to HTML list items
+    and wraps the content in a styled container with appropriate CSS classes.
+
+    Args:
+        text: The text block to format, potentially containing numbered lists
+
+    Returns:
+        HTML string containing either a formatted list with plan title or
+        regular text if no list items are found
+
+    Note:
+        The function recognizes plan titles like "Plan", "Updated Plan", "Completed Plan"
+        and converts checkbox symbols (✓, ✗) to HTML format ([x], [ ]).
+    """
+    import re
+
+    lines = text.split("\n")
+    list_items = []
+    has_list_items = False
+    plan_title = "Plan"  # Default title
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+
+        # Check for plan title patterns
+        if re.match(r"^(Plan|Updated Plan|Completed Plan)$", line, re.IGNORECASE):
+            plan_title = line
+            continue
+
+        # Check for numbered lists with checkboxes (1. [ ] or 1. [✓] or 1. [✗])
+        if re.match(r"^\d+\.\s*\[[ ✓✗]\]", line):
+            has_list_items = True
+            # Extract the content after the checkbox
+            content = re.sub(r"^\d+\.\s*\[[ ✓✗]\]\s*", "", line)
+
+            # Replace checkbox symbols with text format
+            if "[✓]" in line:
+                list_items.append(f"<li><strong>[x]</strong> {content}</li>")
+            elif "[✗]" in line:
+                list_items.append(f"<li><strong>[ ]</strong> {content}</li>")
+            else:
+                list_items.append(f"<li><strong>[ ]</strong> {content}</li>")
+        else:
+            # Regular text - add as is (don't convert to list items)
+            list_items.append(line)
+
+    if has_list_items and list_items:
+        # This is a list - return with container div and styled title
+        return f"""<div class="title-text plan">
+<div class="title-text-header">
+<span class="plan-title">{plan_title}</span>
+</div>
+<div class="title-text-content">
+<ul>
+{chr(10).join(list_items)}
+</ul>
+</div>
+</div>"""
+    else:
+        # Regular text
+        return "\n".join(list_items)
+
+
+def convert_markdown_to_pdf(markdown_path: str, pdf_path: str) -> None:
+    """Convert markdown file to PDF using weasyprint or fallback libraries.
+
+    This function converts a markdown file to PDF format using multiple fallback
+    strategies. It prioritizes weasyprint for better layout control, then falls back
+    to markdown2pdf and finally pandoc if the preferred libraries are not available.
+
+    Args:
+        markdown_path: Path to the input markdown file
+        pdf_path: Path where the output PDF file should be saved
+
+    Raises:
+        ImportError: If no PDF conversion library is available
+        Exception: If PDF conversion fails for any other reason
+
+    Note:
+        The function uses minimal markdown extensions for better performance
+        and applies custom CSS styling for consistent formatting.
+    """
+    try:
+        # Try weasyprint first (better for complex layouts)
+        from weasyprint import HTML
+        from weasyprint.text.fonts import FontConfiguration
+
+        # Read markdown content
+        with open(markdown_path, encoding="utf-8") as f:
+            markdown_content = f.read()
+
+        # Convert markdown to HTML with minimal extensions for better performance
+        import markdown
+
+        # Use minimal extensions to improve performance
+        html_content = markdown.markdown(
+            markdown_content,
+            extensions=["fenced_code"],  # Removed codehilite for better performance
+        )
+
+        # Add CSS styling
+        css_content = get_pdf_css_content()
+
+        # Create HTML document
+        html_doc = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="utf-8">
+            <title>Biomni Conversation History</title>
+            <style>{css_content}</style>
+        </head>
+        <body>
+            {html_content}
+        </body>
+        </html>
+        """
+
+        # Convert to PDF with performance optimizations
+        font_config = FontConfiguration()
+        html_obj = HTML(string=html_doc)
+        html_obj.write_pdf(pdf_path, font_config=font_config, optimize_images=True)
+
+    except ImportError:
+        # Fallback to markdown2pdf if weasyprint is not available
+        try:
+            from markdown2pdf import markdown2pdf
+
+            markdown2pdf(markdown_path, pdf_path)
+        except ImportError:
+            # Final fallback - try using pandoc if available
+            import subprocess
+
+            try:
+                subprocess.run(["pandoc", markdown_path, "-o", pdf_path], check=True)
+            except (subprocess.CalledProcessError, FileNotFoundError) as e:
+                raise ImportError(
+                    "No PDF conversion library available. Please install weasyprint, markdown2pdf, or pandoc."
+                ) from e
+    except Exception as e:
+        raise Exception(f"PDF conversion failed: {e}") from e
+
+
+def get_pdf_css_content() -> str:
+    """Get the CSS content for PDF generation.
+
+    This function returns a comprehensive CSS stylesheet designed specifically
+    for PDF generation from markdown content. It includes styling for all
+    HTML elements that may appear in the converted markdown, with optimized
+    typography, spacing, and layout for print media.
+
+    Returns:
+        CSS string containing all styles needed for PDF generation
+
+    Note:
+        The CSS includes styles for:
+        - Typography and font families
+        - Headings and text formatting
+        - Code blocks and syntax highlighting
+        - Tables and lists
+        - Custom classes for tool calls, observations, and plans
+        - Print-optimized spacing and layout
+    """
+    return """
+    body {
+        /* Previously: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif, 'Noto Color Emoji', 'Apple Color Emoji', 'Segoe UI Emoji', 'Twemoji', 'EmojiOne Color' */
+        font-family: sans-serif;
+        font-size: 9pt;
+        line-height: 1.4;
+        max-width: 800px;
+        margin: 0 auto;
+        padding: 15px;
+        color: #333;
+    }
+    h1, h2, h3, h4, h5, h6 {
+        /* Previously: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif, 'Noto Color Emoji', 'Apple Color Emoji', 'Segoe UI Emoji', 'Twemoji', 'EmojiOne Color' */
+        font-family: sans-serif;
+        color: #2c3e50;
+        margin-top: 1em;
+        margin-bottom: 0.5em;
+    }
+    h1 {
+        border-bottom: 2px solid #3498db;
+        padding-bottom: 8px;
+        font-size: 16pt;
+    }
+    h2 {
+        border-bottom: 1px solid #bdc3c7;
+        padding-bottom: 3px;
+        font-size: 14pt;
+    }
+    h3 {
+        font-size: 12pt;
+    }
+    h4 {
+        font-size: 10pt;
+        margin-top: 0.8em;
+        margin-bottom: 0.3em;
+    }
+    h5, h6 {
+        font-size: 9pt;
+        margin-top: 0.6em;
+        margin-bottom: 0.2em;
+    }
+    code {
+        background-color: #f8f9fa;
+        padding: 1px 3px;
+        border-radius: 2px;
+        font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+        font-size: 8pt;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    pre {
+        background-color: #f8f9fa;
+        padding: 10px;
+        border-radius: 3px;
+        overflow-x: auto;
+        border-left: 3px solid #3498db;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+        font-size: 8pt;
+        margin: 0.5em 0;
+    }
+    pre code {
+        background-color: transparent;
+        padding: 0;
+        border-radius: 0;
+        font-size: 8pt;
+    }
+    /* Code header styling */
+    strong {
+        font-size: 9pt;
+        font-weight: normal;
+        color: #6c757d;
+        font-style: italic;
+    }
+    blockquote {
+        border-left: 3px solid #bdc3c7;
+        margin: 0.5em 0;
+        padding-left: 15px;
+        color: #7f8c8d;
+        font-size: 8pt;
+    }
+    table {
+        border-collapse: collapse;
+        width: 100%;
+        margin: 0.5em 0;
+        font-size: 8pt;
+    }
+    th, td {
+        border: 1px solid #bdc3c7;
+        padding: 4px 8px;
+        text-align: left;
+    }
+    th {
+        background-color: #ecf0f1;
+        font-weight: bold;
+    }
+    img {
+        max-width: 100%;
+        height: auto;
+        display: block;
+        margin: 10px auto;
+        border: 1px solid #ddd;
+        border-radius: 3px;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    }
+    p {
+        /* Previously: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif, 'Noto Color Emoji', 'Apple Color Emoji', 'Segoe UI Emoji', 'Twemoji', 'EmojiOne Color' */
+        font-family: sans-serif;
+        margin: 0.3em 0;
+    }
+    /* Tool call highlighting - matching observation and code formatting */
+    .tool-call-highlight {
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 3px;
+        padding: 0;
+        margin: 10px 0;
+        overflow: hidden;
+    }
+    .tool-call-header {
+        background-color: #e9ecef;
+        color: #495057;
+        padding: 8px 12px;
+        margin: 0;
+        font-weight: normal;
+        font-size: 9pt;
+        font-style: italic;
+        border-bottom: 1px solid #dee2e6;
+    }
+    .tool-call-input {
+        background-color: #f8f9fa;
+        border: none;
+        border-radius: 0;
+        padding: 10px 12px;
+        margin: 0;
+        color: #333;
+        font-size: 8pt;
+        line-height: 1.4;
+    }
+    .tool-call-input strong {
+        color: #495057;
+        font-weight: normal;
+        font-size: 8pt;
+        font-style: italic;
+    }
+    .tool-call-input pre {
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 3px;
+        padding: 10px;
+        margin: 0;
+        font-size: 8pt;
+        line-height: 1.4;
+        overflow-x: auto;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    .tool-call-input code {
+        background-color: transparent;
+        padding: 0;
+        border-radius: 0;
+        font-size: 8pt;
+        color: #2c3e50;
+    }
+    .tools-used {
+        background-color: #f8f9fa;
+        border-top: 1px solid #dee2e6;
+        padding: 8px 12px;
+        margin: 0;
+        font-size: 8pt;
+        color: #6c757d;
+    }
+    .tools-used strong {
+        color: #6c757d;
+        font-weight: normal;
+        font-size: 8pt;
+        font-style: italic;
+    }
+    /* Title-text styling - unified for observations, plans, and solutions */
+    .title-text {
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 3px;
+        padding: 0;
+        margin: 10px 0;
+        overflow: hidden;
+    }
+    .title-text-header {
+        background-color: #e9ecef;
+        color: #495057;
+        padding: 8px 12px;
+        margin: 0;
+        font-weight: normal;
+        font-size: 9pt;
+        font-style: italic;
+        border-bottom: 1px solid #dee2e6;
+    }
+    .title-text-header strong {
+        color: #495057;
+        font-weight: normal;
+        font-size: 9pt;
+        font-style: italic;
+    }
+    .title-text-content {
+        background-color: #f8f9fa;
+        border: none;
+        border-radius: 0;
+        padding: 10px 12px;
+        margin: 0;
+        color: #333;
+        font-size: 8pt;
+        line-height: 1.4;
+    }
+    /* Plan-specific styling - soft blue pastel */
+    .title-text.plan {
+        background-color: #e3f2fd;
+        border-color: #bbdefb;
+    }
+    .title-text.plan .title-text-header {
+        background-color: #bbdefb;
+        color: #1976d2;
+    }
+    .title-text.plan .title-text-content {
+        background-color: #e3f2fd;
+    }
+    .plan-title {
+        font-style: italic;
+        font-weight: normal;
+        color: #1565c0;
+        text-shadow: 0 1px 2px rgba(0,0,0,0.1);
+    }
+    .plan-title strong {
+        font-weight: normal;
+    }
+    /* Code execution-specific styling - matching title-text styling */
+    .tool-call-highlight {
+        background-color: #f8f9fa;
+        border-color: #e9ecef;
+    }
+    .tool-call-header {
+        background-color: #e9ecef;
+        color: #495057;
+    }
+    .tool-call-input {
+        background-color: #f8f9fa;
+        color: #333;
+    }
+    /* Observation-specific styling - soft purple pastel */
+    .title-text.observation {
+        background-color: #f3e5f5;
+        border-color: #e1bee7;
+    }
+    .title-text.observation .title-text-header {
+        background-color: #e1bee7;
+        color: #7b1fa2;
+    }
+    .title-text.observation .title-text-content {
+        background-color: #f3e5f5;
+    }
+    /* Summary and solution-specific styling - soft orange pastel, no overlay */
+    .title-text.summary {
+        background-color: #fff3e0;
+        border-color: #ffcc02;
+    }
+    .title-text.summary .title-text-header {
+        background-color: #ffcc02;
+        color: #f57c00;
+    }
+    .title-text.summary .title-text-content {
+        background-color: #fff3e0;
+    }
+    .title-text-content ul {
+        background-color: transparent;
+        border: none;
+        border-radius: 0;
+        padding: 0;
+        margin: 0;
+        color: #333;
+        font-size: 8pt;
+        line-height: 1.4;
+    }
+    .title-text-content li {
+        margin: 3px 0;
+        color: #333;
+    }
+    .title-text-content li strong {
+        color: #495057;
+        font-weight: normal;
+        font-size: 8pt;
+        font-style: italic;
+    }
+    .title-text-content li code {
+        background-color: #e9ecef;
+        color: #333;
+        padding: 1px 3px;
+        border-radius: 2px;
+        font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+        font-size: 7pt;
+    }
+    .title-text-content pre {
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 3px;
+        padding: 10px;
+        margin: 0;
+        font-size: 8pt;
+        line-height: 1.4;
+        overflow-x: auto;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    .title-text-content code {
+        background-color: transparent;
+        padding: 0;
+        border-radius: 0;
+        font-size: 8pt;
+        color: #2c3e50;
+    }
+    /* Parsing error display styling */
+    .parsing-error-box {
+        background-color: #ffebee;
+        border: 1px solid #f44336;
+        border-radius: 4px;
+        padding: 8px 12px;
+        margin: 8px 0;
+        font-size: 9pt;
+        color: #c62828;
+        box-shadow: 0 2px 4px rgba(244, 67, 54, 0.1);
+    }
+    .parsing-error-header {
+        font-weight: bold;
+        margin-bottom: 4px;
+        color: #d32f2f;
+    }
+    .parsing-error-content {
+        font-family: 'Courier New', monospace;
+        background-color: #ffcdd2;
+        padding: 4px 6px;
+        border-radius: 2px;
+        margin-top: 4px;
+        font-size: 8pt;
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    """

Biomni/biomni/version.py

@@ -0,0 +1 @@
+__version__ = "0.0.8"  # pragma: no cover

Biomni/license_info.md

@@ -0,0 +1,52 @@
+# Biomni Data Source License Information
+
+This document provides an overview of the data sources used by Biomni, their licenses, and suitability for internal hosting and commercial use.
+
+A significant portion of the data used in Biomni requires a commercial license for any commercial application. Several datasets are explicitly licensed for non-commercial use only, which would prohibit their use in a commercial product without a separate agreement. Before proceeding with any commercial use, a thorough legal review of the licenses for each dataset you intend to use is strongly recommended.
+
+## Data License and Internal Hosting Analysis
+
+| Data Source Category | Example Files | License | Internal Hosting | Source |
+| :--- | :--- | :--- | :--- | :--- |
+| **COSMIC** | `Cosmic_*.csv`, `Cosmic_*.parquet` | Requires commercial license for commercial use. | Yes, with a valid commercial license. | [Sanger Institute](https://cancer.sanger.ac.uk/cosmic) |
+| **BindingDB** | `BindingDB_All_202409.tsv` | Custom, non-commercial use granted. Commercial use requires a license. | Yes, with a commercial license. | [BindingDB](https://www.bindingdb.org) |
+| **Broad Repurposing Hub** | `broad_repurposing_hub_*.parquet` | CC BY 4.0 | Yes | [Broad Institute](https://www.broadinstitute.org/drug-repurposing-hub) |
+| **DDInter** | `ddinter_*.csv` | CC BY-NC-SA 4.0 | No, non-commercial use only. | [DDInter](http://ddinter.scbdd.com/) |
+| **DisGeNET** | `DisGeNET.parquet` | CC BY-NC-SA 4.0 | No, non-commercial use only. | [DisGeNET](https://www.disgenet.org/) |
+| **Enamine** | `enamine_cloud_library_smiles.pkl` | Proprietary. Requires license for screening. | Yes, with a valid license. | [Enamine](https://enamine.net/) |
+| **EveBio** | `evebio_*.csv` | Appears to be proprietary data from EveBio. | Requires permission from EveBio. | EveBio |
+| **Gene Ontology (GO)** | `go-plus.json` | CC BY 4.0 | Yes | [Gene Ontology Consortium](http://geneontology.org/) |
+| **GTEx** | `gtex_tissue_gene_tpm.parquet` | dbGaP controlled access. | Yes, with authorization. | [GTEx Portal](https://gtexportal.org/) |
+| **Human Protein Atlas** | `proteinatlas.tsv` | CC BY-SA 3.0 | Yes | [Human Protein Atlas](https://www.proteinatlas.org/) |
+| **MSigDB** | `msigdb_human_*.parquet` | Custom, requires license for commercial use. | Yes, with a license. | [Broad Institute](https://www.gsea-msigdb.org/gsea/msigdb) |
+| **OMIM** | `omim.parquet` | Custom, requires license for commercial use. | Yes, with a license. | [OMIM](https://omim.org/) |
+| **BioGRID** | `affinity_capture-ms.parquet`, etc. | OSL 3.0 | Yes | [BioGRID](https://thebiogrid.org/) |
+| **CZI Cell Census** | `czi_census_datasets_v4.parquet` | CC BY 4.0 | Yes | [Chan Zuckerberg Initiative](https://cellxgene.cziscience.com/census) |
+| **DepMap** | `DepMap_*.csv` | CC BY 4.0 | Yes | [Broad Institute DepMap](https://depmap.org/) |
+| **Genebass** | `genebass_*.pkl` | ODC-By v1.0 | Yes | [Genebass](https://genebass.org/) |
+| **GWAS Catalog** | `gwas_catalog.pkl` | Apache 2.0 | Yes | [EBI GWAS Catalog](https://www.ebi.ac.uk/gwas/) |
+| **HPO** | `hp.obo` | Custom, free for all uses. | Yes | [Human Phenotype Ontology](https://hpo.jax.org/) |
+| **McPAS-TCR** | `McPAS-TCR.parquet` | CC BY-NC-SA 4.0 | No, non-commercial use only. | [McPAS-TCR](http://friedmanlab.weizmann.ac.il/McPAS-TCR/) |
+| **miRDB** | `miRDB_v6.0_results.parquet` | Custom, free for non-commercial use. | No, non-commercial use only. | [miRDB](http://mirdb.org/) |
+| **miRTarBase** | `miRTarBase_*.parquet` | CC BY-NC 4.0 | No, non-commercial use only. | [miRTarBase](https://mirtarbase.cuhk.edu.cn/) |
+| **MouseMine** | `mousemine_*.parquet` | CC BY 4.0 | Yes | [MouseMine](http://www.mousemine.org/) |
+| **P-HIPSTER** | `Virus-Host_PPI_P-HIPSTER_2020.parquet` | CC BY 4.0 | Yes | [P-HIPSTER](http://phipster.org) |
+| **TXGNN** | `txgnn_*.pkl` | MIT License | Yes | - |
+
+## Configuration for Commercial Use
+
+To manage which datasets are used based on licensing, Biomni provides a configuration option. You can set the `commercial_mode` flag to `True` in your configuration to automatically exclude datasets that are not licensed for commercial use.
+
+### Usage
+
+```python
+from biomni.agent import A1
+
+# For commercial use (excludes non-commercial datasets)
+agent = A1(commercial_mode=True)
+
+# For academic/research use (includes all datasets)
+agent = A1(commercial_mode=False)  # default
+```
+
+This configuration automatically selects the appropriate data environment description file and ensures compliance with licensing requirements.

Biomni/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "biomni"
+dynamic = ["version"]
+description = "Biomni"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Biomni Team", email = "kexinh@cs.stanford.edu"}
+]
+requires-python = ">=3.11"
+dependencies = ["pydantic", "langchain", "python-dotenv"]
+
+[project.urls]
+Homepage = "https://github.com/snap-stanford/biomni"
+Repository = "https://github.com/snap-stanford/biomni"
+
+[project.optional-dependencies]
+gradio = ["gradio>=5.0,<6.0"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = {attr = "biomni.version.__version__"}
+
+[tool.setuptools.packages.find]
+exclude = ["test*", "tutorials*"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 120
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "F",      # Errors detected by Pyflakes
+    "E",      # Error detected by Pycodestyle
+    "W",      # Warning detected by Pycodestyle
+    "I",      # isort
+    #"D",      # pydocstyle
+    "B",      # flake8-bugbear
+    "TID",    # flake8-tidy-imports
+    "C4",     # flake8-comprehensions
+    "BLE",    # flake8-blind-except
+    "UP",     # pyupgrade
+    "RUF100", # Report unused noqa directives
+    "TCH",    # Typing imports
+    #"NPY",    # Numpy specific rules
+    #"PTH",    # Use pathlib
+    #"PL"      # pylint
+]
+ignore = [
+    # line too long -> we accept long comment lines; black gets rid of long code lines
+    "E501",
+    # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
+    "E731",
+    # allow I, O, l as variable names -> I is the identity matrix
+    "E741",
+    # Missing docstring in public package
+    "D104",
+    # Missing docstring in public module
+    "D100",
+    # Missing docstring in __init__
+    "D107",
+    # Errors from function calls in argument defaults. These are fine when the result is immutable.
+    "B008",
+    # __magic__ methods are are often self-explanatory, allow missing docstrings
+    "D105",
+    # first line should end with a period [Bug: doesn't work with single-line docstrings]
+    "D400",
+    # First line should be in imperative mood; try rephrasing
+    "D401",
+    ## Disable one in each pair of mutually incompatible rules
+    # We don’t want a blank line before a class docstring
+    "D203",
+    # We want docstrings to start immediately after the opening triple quote
+    "D213",
+    # camcelcase imported as lowercase
+    "N813",
+    # module import not at top level of file
+    "E402",
+    # Too many arguments in function definition
+    "PLR0913",
+    # Too many branches
+    "PLR0912",
+    # magic value used in comparison
+    "PLR2004",
+    # Too many statements
+    "PLR0915",
+    # Extracting value from dictionary without calling `.items()` - clashes with sim
+    "PLC0206",
+    # import should be at top of file
+    "PLC0415",
+    # do not catch blind exception
+    "BLE001",
+    # strip with multi characters
+    "B005"
+]

cloningscenarios_all_models_cloning_20260524_163903.log

@@ -0,0 +1,7 @@
+RUN_ID=cloning_20260524_163903
+Logs: /225040511/project/cloningscenarios_logs/cloning_20260524_163903
+Biomanus PID: 115392
+Biomni scales PID: 115393
+Biomni-ReAct PID: 115394
+React+code PID: 115395
+All CloningScenarios jobs finished for RUN_ID=cloning_20260524_163903

ollama.log

@@ -0,0 +1,13 @@
+nohup: ignoring input
+time=2025-12-21T13:03:10.395Z level=INFO source=routes.go:1554 msg="server config" env="map[CUDA_VISIBLE_DEVICES: GGML_VK_VISIBLE_DEVICES: GPU_DEVICE_ORDINAL: HIP_VISIBLE_DEVICES: HSA_OVERRIDE_GFX_VERSION: HTTPS_PROXY: HTTP_PROXY: NO_PROXY: OLLAMA_CONTEXT_LENGTH:4096 OLLAMA_DEBUG:INFO OLLAMA_FLASH_ATTENTION:false OLLAMA_GPU_OVERHEAD:0 OLLAMA_HOST:http://127.0.0.1:11434 OLLAMA_KEEP_ALIVE:5m0s OLLAMA_KV_CACHE_TYPE: OLLAMA_LLM_LIBRARY: OLLAMA_LOAD_TIMEOUT:5m0s OLLAMA_MAX_LOADED_MODELS:0 OLLAMA_MAX_QUEUE:512 OLLAMA_MODELS:/225040511/project/ollama/models OLLAMA_MULTIUSER_CACHE:false OLLAMA_NEW_ENGINE:false OLLAMA_NOHISTORY:false OLLAMA_NOPRUNE:false OLLAMA_NUM_PARALLEL:1 OLLAMA_ORIGINS:[http://localhost https://localhost http://localhost:* https://localhost:* http://127.0.0.1 https://127.0.0.1 http://127.0.0.1:* https://127.0.0.1:* http://0.0.0.0 https://0.0.0.0 http://0.0.0.0:* https://0.0.0.0:* app://* file://* tauri://* vscode-webview://* vscode-file://*] OLLAMA_REMOTES:[ollama.com] OLLAMA_SCHED_SPREAD:false OLLAMA_VULKAN:false ROCR_VISIBLE_DEVICES: http_proxy: https_proxy: no_proxy:]"
+time=2025-12-21T13:03:10.395Z level=INFO source=images.go:493 msg="total blobs: 0"
+time=2025-12-21T13:03:10.396Z level=INFO source=images.go:500 msg="total unused blobs removed: 0"
+time=2025-12-21T13:03:10.396Z level=INFO source=routes.go:1607 msg="Listening on 127.0.0.1:11434 (version 0.13.5)"
+time=2025-12-21T13:03:10.396Z level=INFO source=runner.go:67 msg="discovering available GPUs..."
+time=2025-12-21T13:03:10.397Z level=INFO source=server.go:429 msg="starting runner" cmd="/usr/local/bin/ollama runner --ollama-engine --port 41421"
+time=2025-12-21T13:03:10.589Z level=INFO source=server.go:429 msg="starting runner" cmd="/usr/local/bin/ollama runner --ollama-engine --port 39047"
+time=2025-12-21T13:03:10.687Z level=INFO source=runner.go:106 msg="experimental Vulkan support disabled.  To enable, set OLLAMA_VULKAN=1"
+time=2025-12-21T13:03:10.687Z level=INFO source=server.go:429 msg="starting runner" cmd="/usr/local/bin/ollama runner --ollama-engine --port 46809"
+time=2025-12-21T13:03:10.863Z level=INFO source=types.go:42 msg="inference compute" id=GPU-a680880b-cb7f-062f-fa43-501d14dbbd89 filter_id="" library=CUDA compute=8.9 name=CUDA0 description="NVIDIA GeForce RTX 4090" libdirs=ollama,cuda_v12 driver=12.8 pci_id=0000:27:00.0 type=discrete total="48.0 GiB" available="47.4 GiB"
+[GIN] 2025/12/21 - 13:03:21 | 200 |      66.064µs |       127.0.0.1 | HEAD     "/"
+[GIN] 2025/12/21 - 13:03:21 | 200 |     522.445µs |       127.0.0.1 | GET      "/api/tags"

rerun_base_deepseek_cloningscenarios_50shards.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from pathlib import Path
+
+
+PROJECT_ROOT = Path("/225040511/project")
+PYTHON_BIN = Path(os.getenv("LAB_BENCH_RUNNER_PYTHON", "/225040511/miniconda3/envs/biomni_e1/bin/python"))
+RUNNER = PROJECT_ROOT / "react_code_bioagent_deepseek/react_code_bioagent/labbench_runner.py"
+OUT = Path(
+    os.getenv(
+        "OUT",
+        str(PROJECT_ROOT / "base_llm_labbench/results/cloningscenarios_base_deepseek_cloning_50shards_20260524_174548"),
+    )
+)
+SHARD_COUNT = int(os.getenv("SHARD_COUNT", "50"))
+SHARD_CONCURRENCY = int(os.getenv("SHARD_CONCURRENCY", "5"))
+SEED = os.getenv("SEED", "20260514")
+
+
+def load_env_file(path: Path) -> None:
+    if not path.exists():
+        return
+    for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def count_rows(path: Path) -> int:
+    if not path.exists():
+        return 0
+    return sum(1 for _ in path.open("r", encoding="utf-8", errors="replace"))
+
+
+def main() -> int:
+    for env_file in [
+        PROJECT_ROOT / ".env",
+        PROJECT_ROOT / "LAB-Bench/.env",
+        PROJECT_ROOT / "base_llm_labbench/.env",
+    ]:
+        load_env_file(env_file)
+
+    env = os.environ.copy()
+    env.setdefault("DEEPSEEK_BASE_URL", "https://api.deepseek.com/v1")
+    env.setdefault("DEEPSEEK_MODEL_NAME", "deepseek-chat")
+
+    OUT.mkdir(parents=True, exist_ok=True)
+    shard_log_dir = OUT / "shard_logs"
+    shard_log_dir.mkdir(parents=True, exist_ok=True)
+
+    result_file = OUT / "cloningscenarios_results.jsonl"
+    reasoning_log = OUT / "cloningscenarios_reasoning.log"
+    result_file.write_text("", encoding="utf-8")
+    reasoning_log.write_text("", encoding="utf-8")
+    for old_log in shard_log_dir.glob("base_deepseek_cloningscenarios_shard*.log"):
+        old_log.unlink()
+
+    (OUT / "run_config.txt").write_text(
+        "\n".join(
+            [
+                "model=base DeepSeek",
+                f"deepseek_model={env['DEEPSEEK_MODEL_NAME']}",
+                "eval=CloningScenarios",
+                "dev_size=0",
+                "test_size=33",
+                f"shard_count={SHARD_COUNT}",
+                f"shard_concurrency={SHARD_CONCURRENCY}",
+                f"seed={SEED}",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    print(f"output={OUT}", flush=True)
+    print(f"model={env['DEEPSEEK_MODEL_NAME']}", flush=True)
+    print(f"shard_count={SHARD_COUNT}", flush=True)
+    print(f"shard_concurrency={SHARD_CONCURRENCY}", flush=True)
+
+    running: list[tuple[int, subprocess.Popen[bytes], object]] = []
+    failures = 0
+    next_shard = 0
+
+    while next_shard < SHARD_COUNT or running:
+        while next_shard < SHARD_COUNT and len(running) < SHARD_CONCURRENCY:
+            shard = next_shard
+            next_shard += 1
+            label = f"base_deepseek_cloningscenarios_shard{shard + 1:02d}of{SHARD_COUNT:02d}"
+            log_handle = (shard_log_dir / f"{label}.log").open("wb")
+            cmd = [
+                str(PYTHON_BIN),
+                str(RUNNER),
+                "--evals",
+                "CloningScenarios",
+                "--splits",
+                "test",
+                "--dev-size",
+                "0",
+                "--test-size",
+                "33",
+                "--seed",
+                SEED,
+                "--n-threads",
+                "1",
+                "--shard-index",
+                str(shard),
+                "--shard-count",
+                str(SHARD_COUNT),
+                "--output-root",
+                str(OUT),
+                "--compact-results-path",
+                str(result_file),
+                "--reasoning-log-path",
+                str(reasoning_log),
+                "--skip-existing-results",
+                "--model",
+                env["DEEPSEEK_MODEL_NAME"],
+                "--base-url",
+                env["DEEPSEEK_BASE_URL"],
+            ]
+            proc = subprocess.Popen(cmd, stdout=log_handle, stderr=subprocess.STDOUT, env=env)
+            running.append((shard, proc, log_handle))
+            print(f"started shard={shard + 1}/{SHARD_COUNT} pid={proc.pid}", flush=True)
+
+        time.sleep(2)
+        still_running: list[tuple[int, subprocess.Popen[bytes], object]] = []
+        for shard, proc, log_handle in running:
+            rc = proc.poll()
+            if rc is None:
+                still_running.append((shard, proc, log_handle))
+                continue
+            log_handle.close()
+            if rc != 0:
+                failures += 1
+                print(f"finished shard={shard + 1}/{SHARD_COUNT} rc={rc}", flush=True)
+        running = still_running
+        print(f"progress rows={count_rows(result_file)} active={len(running)} failures={failures}", flush=True)
+
+    print(f"after_rows={count_rows(result_file)}", flush=True)
+    print(f"failures={failures}", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rerun_base_deepseek_cloningscenarios_50shards.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -u
+
+PROJECT_ROOT="/225040511/project"
+PYTHON_BIN="${LAB_BENCH_RUNNER_PYTHON:-/225040511/miniconda3/envs/biomni_e1/bin/python}"
+RUNNER="${PROJECT_ROOT}/react_code_bioagent_deepseek/react_code_bioagent/labbench_runner.py"
+OUT="${OUT:-${PROJECT_ROOT}/base_llm_labbench/results/cloningscenarios_base_deepseek_cloning_50shards_20260524_174548}"
+SHARD_COUNT="${SHARD_COUNT:-50}"
+SHARD_CONCURRENCY="${SHARD_CONCURRENCY:-5}"
+SEED="${SEED:-20260514}"
+
+for ENV_FILE in "${PROJECT_ROOT}/.env" "${PROJECT_ROOT}/LAB-Bench/.env" "${PROJECT_ROOT}/base_llm_labbench/.env"; do
+  if [[ -f "${ENV_FILE}" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "${ENV_FILE}"
+    set +a
+  fi
+done
+
+export DEEPSEEK_BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
+export DEEPSEEK_MODEL_NAME="${DEEPSEEK_MODEL_NAME:-deepseek-chat}"
+
+mkdir -p "${OUT}/shard_logs"
+: > "${OUT}/cloningscenarios_results.jsonl"
+: > "${OUT}/cloningscenarios_reasoning.log"
+rm -f "${OUT}/shard_logs"/base_deepseek_cloningscenarios_shard*.log
+
+{
+  echo "model=base DeepSeek"
+  echo "deepseek_model=${DEEPSEEK_MODEL_NAME}"
+  echo "eval=CloningScenarios"
+  echo "dev_size=0"
+  echo "test_size=33"
+  echo "shard_count=${SHARD_COUNT}"
+  echo "shard_concurrency=${SHARD_CONCURRENCY}"
+  echo "seed=${SEED}"
+} > "${OUT}/run_config.txt"
+
+echo "output=${OUT}"
+echo "model=${DEEPSEEK_MODEL_NAME}"
+echo "shard_count=${SHARD_COUNT}"
+echo "shard_concurrency=${SHARD_CONCURRENCY}"
+
+active=0
+for ((shard=0; shard<SHARD_COUNT; shard++)); do
+  label="$(printf "base_deepseek_cloningscenarios_shard%02dof%02d" "$((shard + 1))" "${SHARD_COUNT}")"
+  "${PYTHON_BIN}" "${RUNNER}" \
+    --evals CloningScenarios \
+    --splits test \
+    --dev-size 0 \
+    --test-size 33 \
+    --seed "${SEED}" \
+    --n-threads 1 \
+    --shard-index "${shard}" \
+    --shard-count "${SHARD_COUNT}" \
+    --output-root "${OUT}" \
+    --compact-results-path "${OUT}/cloningscenarios_results.jsonl" \
+    --reasoning-log-path "${OUT}/cloningscenarios_reasoning.log" \
+    --skip-existing-results \
+    --model "${DEEPSEEK_MODEL_NAME}" \
+    --base-url "${DEEPSEEK_BASE_URL}" \
+    > "${OUT}/shard_logs/${label}.log" 2>&1 &
+  active=$((active + 1))
+  if [[ "${active}" -ge "${SHARD_CONCURRENCY}" ]]; then
+    wait -n || true
+    active=$((active - 1))
+  fi
+done
+
+while [[ "${active}" -gt 0 ]]; do
+  wait -n || true
+  active=$((active - 1))
+done
+
+rows=0
+if [[ -f "${OUT}/cloningscenarios_results.jsonl" ]]; then
+  rows="$(wc -l < "${OUT}/cloningscenarios_results.jsonl")"
+fi
+echo "after_rows=${rows}"

run_base_openai_labbench_three_tasks_50shards.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+set -u
+
+RUN_ID="${RUN_ID:-openai_labbench_$(date -u +%Y%m%d_%H%M%S)}"
+PROJECT_ROOT="/225040511/project"
+PYTHON_BIN="${LAB_BENCH_RUNNER_PYTHON:-/225040511/miniconda3/envs/biomni_e1/bin/python}"
+RUNNER="${PROJECT_ROOT}/react_code_bioagent_deepseek/react_code_bioagent/labbench_runner.py"
+RESULT_ROOT="${PROJECT_ROOT}/base_llm_labbench/results/base_openai_${RUN_ID}"
+LOG_ROOT="${PROJECT_ROOT}/base_llm_labbench/logs/base_openai_${RUN_ID}"
+SHARD_COUNT="${LABBENCH_SHARD_COUNT:-50}"
+SHARD_CONCURRENCY="${LABBENCH_SHARD_CONCURRENCY:-5}"
+SEED="${LABBENCH_SEED:-20260514}"
+OPENAI_MODEL_NAME="${OPENAI_MODEL_NAME:-${OPENAI_MODEL:-gpt-4o-mini}}"
+OPENAI_BASE_URL="${OPENAI_BASE_URL:-https://api.openai.com/v1}"
+
+mkdir -p "${RESULT_ROOT}" "${LOG_ROOT}"
+
+for ENV_FILE in "${PROJECT_ROOT}/.env" "${PROJECT_ROOT}/LAB-Bench/.env" "${PROJECT_ROOT}/base_llm_labbench/.env"; do
+  if [[ -f "${ENV_FILE}" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "${ENV_FILE}"
+    set +a
+  fi
+done
+
+if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+  echo "Missing OPENAI_API_KEY. Put it in ${PROJECT_ROOT}/.env or export it before launching." >&2
+  exit 2
+fi
+
+wait_limited() {
+  local -n pid_array="$1"
+  if [[ "${#pid_array[@]}" -lt "${SHARD_CONCURRENCY}" ]]; then
+    return
+  fi
+  local pid="${pid_array[0]}"
+  wait "${pid}" || true
+  pid_array=("${pid_array[@]:1}")
+}
+
+count_rows() {
+  local file="$1"
+  if [[ -f "${file}" ]]; then
+    wc -l < "${file}"
+  else
+    echo 0
+  fi
+}
+
+run_eval() {
+  local eval_name="$1"
+  local dev_size="$2"
+  local test_size="$3"
+  local eval_lower
+  eval_lower="$(echo "${eval_name}" | tr '[:upper:]' '[:lower:]')"
+  local out="${RESULT_ROOT}/${eval_lower}"
+  local result="${out}/${eval_lower}_results.jsonl"
+  local reasoning="${out}/${eval_lower}_reasoning.log"
+  local shard_log_dir="${out}/shard_logs"
+  mkdir -p "${shard_log_dir}"
+  touch "${result}" "${reasoning}"
+
+  {
+    echo "run_id=${RUN_ID}"
+    echo "model=baseLLM OpenAI"
+    echo "openai_model=${OPENAI_MODEL_NAME}"
+    echo "eval=${eval_name}"
+    echo "dev_size=${dev_size}"
+    echo "test_size=${test_size}"
+    echo "shard_count=${SHARD_COUNT}"
+    echo "shard_concurrency=${SHARD_CONCURRENCY}"
+    echo "seed=${SEED}"
+  } > "${out}/run_config.txt"
+
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] eval=${eval_name} before_rows=$(count_rows "${result}")"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "base_openai_%s_shard%02dof%02d" "${eval_lower}" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${RUNNER}" \
+      --evals "${eval_name}" \
+      --splits test \
+      --dev-size "${dev_size}" \
+      --test-size "${test_size}" \
+      --seed "${SEED}" \
+      --n-threads 1 \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --output-root "${out}" \
+      --compact-results-path "${result}" \
+      --reasoning-log-path "${reasoning}" \
+      --skip-existing-results \
+      --model "${OPENAI_MODEL_NAME}" \
+      --base-url "${OPENAI_BASE_URL}" \
+      --api-key "${OPENAI_API_KEY}" \
+      > "${shard_log_dir}/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] eval=${eval_name} after_rows=$(count_rows "${result}")"
+}
+
+echo "RUN_ID=${RUN_ID}"
+echo "RESULT_ROOT=${RESULT_ROOT}"
+echo "LOG_ROOT=${LOG_ROOT}"
+echo "OPENAI_MODEL_NAME=${OPENAI_MODEL_NAME}"
+echo "SHARD_COUNT=${SHARD_COUNT}"
+echo "SHARD_CONCURRENCY=${SHARD_CONCURRENCY}"
+
+run_eval DbQA 45 315 > "${LOG_ROOT}/dbqa.log" 2>&1 &
+pid_dbqa=$!
+run_eval SeqQA 45 315 > "${LOG_ROOT}/seqqa.log" 2>&1 &
+pid_seqqa=$!
+run_eval CloningScenarios 0 33 > "${LOG_ROOT}/cloningscenarios.log" 2>&1 &
+pid_cloning=$!
+
+echo "dbqa_pid=${pid_dbqa}"
+echo "seqqa_pid=${pid_seqqa}"
+echo "cloningscenarios_pid=${pid_cloning}"
+
+wait "${pid_dbqa}" || true
+wait "${pid_seqqa}" || true
+wait "${pid_cloning}" || true
+
+echo "finished RUN_ID=${RUN_ID}"

run_biomni_nomcp_cloningscenarios.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -u
+
+RUN_ID="${RUN_ID:-cloning_nomcp_$(date -u +%Y%m%d_%H%M%S)}"
+PYTHON_BIN="${LAB_BENCH_RUNNER_PYTHON:-${BIOMNI_EXECUTION_PYTHON:-/225040511/miniconda3/envs/biomni_e1/bin/python}}"
+BIOMNI_ROOT="/225040511/project/Biomni"
+LAB_BENCH_ROOT="/225040511/project/LAB-Bench"
+RUNNER="${BIOMNI_ROOT}/experiments/lab_bench/run_labbench_with_biomni.py"
+OUT_ROOT="${BIOMNI_ROOT}/experiments/lab_bench/results/biomni_no_mcp_cloningscenarios_${RUN_ID}"
+LOG_ROOT="/225040511/project/cloningscenarios_logs/${RUN_ID}"
+EVAL_NAME="CloningScenarios"
+EVAL_LOWER="cloningscenarios"
+DEV_SIZE="${CLONING_DEV_SIZE:-0}"
+TEST_SIZE="${CLONING_TEST_SIZE:-33}"
+SHARD_COUNT="${CLONING_SHARD_COUNT:-33}"
+SHARD_CONCURRENCY="${CLONING_SHARD_CONCURRENCY:-5}"
+SEED="${CLONING_SEED:-20260514}"
+
+mkdir -p "${OUT_ROOT}/agent_runtime" "${OUT_ROOT}/shard_logs/${EVAL_LOWER}" "${LOG_ROOT}"
+
+for ENV_FILE in "/225040511/project/.env" "${BIOMNI_ROOT}/.env" "${LAB_BENCH_ROOT}/.env"; do
+  if [[ -f "${ENV_FILE}" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "${ENV_FILE}"
+    set +a
+  fi
+done
+
+export BIOMNI_CUSTOM_API_KEY="${BIOMNI_CUSTOM_API_KEY:-${DEEPSEEK_API_KEY:-}}"
+export BIOMNI_CUSTOM_BASE_URL="${BIOMNI_CUSTOM_BASE_URL:-${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}}"
+export BIOMNI_LLM="${BIOMNI_LLM:-${DEEPSEEK_MODEL_NAME:-deepseek-chat}}"
+export BIOMNI_SOURCE="${BIOMNI_SOURCE:-Custom}"
+
+{
+  echo "run_id=${RUN_ID}"
+  echo "model=Biomni no MCP"
+  echo "eval=${EVAL_NAME}"
+  echo "dev_size=${DEV_SIZE}"
+  echo "test_size=${TEST_SIZE}"
+  echo "shard_count=${SHARD_COUNT}"
+  echo "shard_concurrency=${SHARD_CONCURRENCY}"
+  echo "seed=${SEED}"
+  echo "use_mcp=false"
+  echo "use_tool_retriever=false"
+} > "${OUT_ROOT}/run_config.txt"
+
+count_rows() {
+  local file="$1"
+  if [[ -f "${file}" ]]; then
+    wc -l < "${file}"
+  else
+    echo 0
+  fi
+}
+
+wait_limited() {
+  local -n pid_array="$1"
+  if [[ "${#pid_array[@]}" -lt "${SHARD_CONCURRENCY}" ]]; then
+    return
+  fi
+  local pid="${pid_array[0]}"
+  wait "${pid}" || true
+  pid_array=("${pid_array[@]:1}")
+}
+
+RESULT_FILE="${OUT_ROOT}/${EVAL_LOWER}_results.jsonl"
+REASONING_LOG="${OUT_ROOT}/${EVAL_LOWER}_reasoning.log"
+touch "${RESULT_FILE}" "${REASONING_LOG}"
+
+echo "RUN_ID=${RUN_ID}"
+echo "output=${OUT_ROOT}"
+echo "log_root=${LOG_ROOT}"
+echo "before_rows=$(count_rows "${RESULT_FILE}")"
+
+pids=()
+for ((shard=0; shard<SHARD_COUNT; shard++)); do
+  label="$(printf "biomni_nomcp_%s_shard%02dof%02d" "${EVAL_LOWER}" "$((shard + 1))" "${SHARD_COUNT}")"
+  "${PYTHON_BIN}" "${RUNNER}" \
+    --eval "${EVAL_NAME}" \
+    --split test \
+    --dev-size "${DEV_SIZE}" \
+    --test-size "${TEST_SIZE}" \
+    --seed "${SEED}" \
+    --repeat 1 \
+    --n_threads 1 \
+    --output-root "${OUT_ROOT}" \
+    --agent-root "${OUT_ROOT}/agent_runtime" \
+    --run-label "${label}" \
+    --shard-index "${shard}" \
+    --shard-count "${SHARD_COUNT}" \
+    --reasoning-log-path "${REASONING_LOG}" \
+    --compact-results-path "${RESULT_FILE}" \
+    --compact-output-only \
+    --skip-existing-results \
+    --no-mcp \
+    --no-use-tool-retriever \
+    > "${OUT_ROOT}/shard_logs/${EVAL_LOWER}/${label}.log" 2>&1 &
+  pids+=("$!")
+  wait_limited pids
+done
+
+for pid in "${pids[@]}"; do
+  wait "${pid}" || true
+done
+
+echo "after_rows=$(count_rows "${RESULT_FILE}")"
+echo "finished output=${OUT_ROOT}"

run_cloningscenarios_all_models.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+RUN_ID="${RUN_ID:-cloning_$(date -u +%Y%m%d_%H%M%S)}"
+PYTHON_BIN="${LAB_BENCH_RUNNER_PYTHON:-${BIOMNI_EXECUTION_PYTHON:-/225040511/miniconda3/envs/biomni_e1/bin/python}}"
+EVAL_NAME="CloningScenarios"
+EVAL_LOWER="cloningscenarios"
+DEV_SIZE="${CLONING_DEV_SIZE:-0}"
+TEST_SIZE="${CLONING_TEST_SIZE:-33}"
+SHARD_COUNT="${CLONING_SHARD_COUNT:-33}"
+SHARD_CONCURRENCY="${CLONING_SHARD_CONCURRENCY:-33}"
+SEED="${CLONING_SEED:-20260514}"
+SCALES_TEXT="${CLONING_TOOL_SCALES:-100 500 1000 2000}"
+
+PROJECT_ROOT="/225040511/project"
+LAB_BENCH_ROOT="${PROJECT_ROOT}/LAB-Bench"
+BIOMANUS_ROOT="${PROJECT_ROOT}/Biomanus"
+BIOMNI_ROOT="${PROJECT_ROOT}/Biomni"
+BIOMNI_REACT_ROOT="${PROJECT_ROOT}/Biomni-ReAct"
+REACT_CODE_ROOT="${PROJECT_ROOT}/React+code_labbench"
+LOG_ROOT="${PROJECT_ROOT}/cloningscenarios_logs/${RUN_ID}"
+
+mkdir -p "${LOG_ROOT}"
+
+for ENV_FILE in "${PROJECT_ROOT}/.env" "${BIOMANUS_ROOT}/.env" "${BIOMNI_ROOT}/.env" "${BIOMNI_REACT_ROOT}/.env" "${LAB_BENCH_ROOT}/.env"; do
+  if [[ -f "${ENV_FILE}" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "${ENV_FILE}"
+    set +a
+  fi
+done
+
+export DEEPSEEK_BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
+export DEEPSEEK_MODEL_NAME="${DEEPSEEK_MODEL_NAME:-deepseek-chat}"
+export BIOMNI_CUSTOM_API_KEY="${BIOMNI_CUSTOM_API_KEY:-${DEEPSEEK_API_KEY:-}}"
+export BIOMNI_CUSTOM_BASE_URL="${BIOMNI_CUSTOM_BASE_URL:-${DEEPSEEK_BASE_URL}}"
+export BIOMNI_LLM="${BIOMNI_LLM:-${DEEPSEEK_MODEL_NAME}}"
+export BIOMNI_SOURCE="${BIOMNI_SOURCE:-Custom}"
+export BIOMNI_REACT_API_KEY="${BIOMNI_REACT_API_KEY:-${DEEPSEEK_API_KEY:-${BIOMNI_CUSTOM_API_KEY:-}}}"
+export BIOMNI_REACT_BASE_URL="${BIOMNI_REACT_BASE_URL:-${DEEPSEEK_BASE_URL}}"
+export BIOMNI_REACT_MODEL="${BIOMNI_REACT_MODEL:-${DEEPSEEK_MODEL_NAME}}"
+export REACT_CODE_API_KEY="${REACT_CODE_API_KEY:-${DEEPSEEK_API_KEY:-${BIOMNI_CUSTOM_API_KEY:-}}}"
+export REACT_CODE_BASE_URL="${REACT_CODE_BASE_URL:-${DEEPSEEK_BASE_URL}}"
+export REACT_CODE_MODEL="${REACT_CODE_MODEL:-${DEEPSEEK_MODEL_NAME}}"
+
+if [[ -z "${DEEPSEEK_API_KEY:-}" && -z "${BIOMNI_CUSTOM_API_KEY:-}" && -z "${OPENAI_API_KEY:-}" && -z "${ANTHROPIC_API_KEY:-}" ]]; then
+  echo "Missing API key. Set DEEPSEEK_API_KEY, BIOMNI_CUSTOM_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY." >&2
+  exit 2
+fi
+
+latest_biomanus_graph() {
+  local graph
+  graph="$(find "${BIOMANUS_ROOT}/graph_outputs" -maxdepth 1 -type d -name 'mcp_generated_graph_all_*' 2>/dev/null | sort | tail -n 1 || true)"
+  if [[ -n "${graph}" && -d "${graph}" ]]; then
+    echo "${graph}"
+  else
+    echo "${BIOMANUS_ROOT}/graph_outputs/labbench_dbqa_seqqa_subgraph"
+  fi
+}
+
+wait_limited() {
+  local -n pid_array="$1"
+  if [[ "${#pid_array[@]}" -lt "${SHARD_CONCURRENCY}" ]]; then
+    return
+  fi
+  local pid
+  pid="${pid_array[0]}"
+  wait "${pid}" || true
+  pid_array=("${pid_array[@]:1}")
+}
+
+run_biomanus() {
+  local out_root="${BIOMANUS_ROOT}/experiments/lab_bench/results/cloningscenarios_biomanus_${RUN_ID}"
+  local agent_root="${out_root}/agent_runtime"
+  local shard_log_dir="${out_root}/shard_logs"
+  local result_file="${out_root}/${EVAL_LOWER}_results.jsonl"
+  local reasoning_log="${out_root}/${EVAL_LOWER}_reasoning.log"
+  local graph_dir
+  graph_dir="$(latest_biomanus_graph)"
+  mkdir -p "${out_root}" "${agent_root}" "${shard_log_dir}"
+  {
+    echo "run_id=${RUN_ID}"
+    echo "model=Biomanus"
+    echo "eval=${EVAL_NAME}"
+    echo "dev_size=${DEV_SIZE}"
+    echo "test_size=${TEST_SIZE}"
+    echo "shard_count=${SHARD_COUNT}"
+    echo "shard_concurrency=${SHARD_CONCURRENCY}"
+    echo "graph_dir=${graph_dir}"
+  } > "${out_root}/run_config.txt"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "biomanus_%s_shard%02dof%02d" "${EVAL_LOWER}" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${BIOMANUS_ROOT}/experiments/lab_bench/scripts/run_labbench_with_hypobioos.py" \
+      --evals "${EVAL_NAME}" \
+      --splits test \
+      --dev-size "${DEV_SIZE}" \
+      --test-size "${TEST_SIZE}" \
+      --seed "${SEED}" \
+      --repeat 1 \
+      --n_threads 1 \
+      --output-root "${out_root}" \
+      --agent-root "${agent_root}" \
+      --graph-dir "${graph_dir}" \
+      --run-label "${label}" \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --reasoning-log-path "${reasoning_log}" \
+      --compact-results-path "${result_file}" \
+      --compact-output-only \
+      --skip-existing-results \
+      --use-graph-retriever \
+      --use-mcp \
+      > "${shard_log_dir}/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "Biomanus done: ${out_root}"
+}
+
+run_biomni_scale() {
+  local scale="$1"
+  local log="${LOG_ROOT}/biomni_scale_${scale}.log"
+  RUN_ID="${RUN_ID}" \
+  LAB_BENCH_TOOL_SCALES="${scale}" \
+  LAB_BENCH_EVALS="${EVAL_NAME}" \
+  LAB_BENCH_DEV_SIZE="${DEV_SIZE}" \
+  LAB_BENCH_TEST_SIZE="${TEST_SIZE}" \
+  LAB_BENCH_TEST_SHARD_COUNT="${SHARD_COUNT}" \
+  LAB_BENCH_SHARD_CONCURRENCY="${SHARD_CONCURRENCY}" \
+  WAIT_FOR_EXISTING_LABBENCH=0 \
+  "${BIOMNI_ROOT}/experiments/lab_bench/run_labbench_tool_scales_biomni.sh" > "${log}" 2>&1
+  echo "Biomni scale ${scale} done"
+}
+
+run_biomni_scales() {
+  local scale_pids=()
+  local scale
+  read -r -a scales <<< "${SCALES_TEXT}"
+  for scale in "${scales[@]}"; do
+    run_biomni_scale "${scale}" &
+    scale_pids+=("$!")
+  done
+  for pid in "${scale_pids[@]}"; do wait "${pid}" || true; done
+}
+
+run_biomni_react() {
+  local out_root="${BIOMNI_REACT_ROOT}/LAB-bench/cloningscenarios_${RUN_ID}"
+  local shard_log_dir="${out_root}/shard_logs"
+  local result_file="${out_root}/${EVAL_LOWER}_results.jsonl"
+  local reasoning_log="${out_root}/${EVAL_LOWER}_reasoning.log"
+  mkdir -p "${out_root}" "${shard_log_dir}"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "biomni_react_%s_shard%02dof%02d" "${EVAL_LOWER}" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${BIOMNI_REACT_ROOT}/scripts/run_labbench_dbqa.py" \
+      --eval "${EVAL_NAME}" \
+      --split test \
+      --dev-size "${DEV_SIZE}" \
+      --test-size "${TEST_SIZE}" \
+      --seed "${SEED}" \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --output-root "${out_root}" \
+      --result-file "${result_file}" \
+      --reasoning-log "${reasoning_log}" \
+      --skip-existing-results \
+      > "${shard_log_dir}/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "Biomni-ReAct done: ${out_root}"
+}
+
+run_react_code() {
+  local out_root="${REACT_CODE_ROOT}/results/cloningscenarios_${RUN_ID}"
+  local shard_log_dir="${out_root}/shard_logs"
+  local result_file="${out_root}/${EVAL_LOWER}_results.jsonl"
+  local reasoning_log="${out_root}/${EVAL_LOWER}_reasoning.log"
+  mkdir -p "${out_root}" "${shard_log_dir}"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "react_code_%s_shard%02dof%02d" "${EVAL_LOWER}" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${REACT_CODE_ROOT}/run_labbench_react_code.py" \
+      --eval "${EVAL_NAME}" \
+      --split test \
+      --dev-size "${DEV_SIZE}" \
+      --test-size "${TEST_SIZE}" \
+      --seed "${SEED}" \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --output-root "${out_root}" \
+      --result-file "${result_file}" \
+      --reasoning-log "${reasoning_log}" \
+      --skip-existing-results \
+      > "${shard_log_dir}/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "React+code done: ${out_root}"
+}
+
+echo "RUN_ID=${RUN_ID}"
+echo "Logs: ${LOG_ROOT}"
+
+run_biomanus > "${LOG_ROOT}/biomanus.log" 2>&1 &
+pid_biomanus=$!
+run_biomni_scales > "${LOG_ROOT}/biomni_scales.log" 2>&1 &
+pid_biomni=$!
+run_biomni_react > "${LOG_ROOT}/biomni_react.log" 2>&1 &
+pid_biomni_react=$!
+run_react_code > "${LOG_ROOT}/react_code.log" 2>&1 &
+pid_react_code=$!
+
+echo "Biomanus PID: ${pid_biomanus}"
+echo "Biomni scales PID: ${pid_biomni}"
+echo "Biomni-ReAct PID: ${pid_biomni_react}"
+echo "React+code PID: ${pid_react_code}"
+
+wait "${pid_biomanus}" || true
+wait "${pid_biomni}" || true
+wait "${pid_biomni_react}" || true
+wait "${pid_react_code}" || true
+
+echo "All CloningScenarios jobs finished for RUN_ID=${RUN_ID}"

run_cloningscenarios_reactcode_and_base_50shards.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -u
+
+RUN_ID="${RUN_ID:-cloning_50shards_$(date -u +%Y%m%d_%H%M%S)}"
+PROJECT_ROOT="/225040511/project"
+PYTHON_BIN="${LAB_BENCH_RUNNER_PYTHON:-/225040511/miniconda3/envs/biomni_e1/bin/python}"
+LOG_ROOT="${PROJECT_ROOT}/cloningscenarios_logs/${RUN_ID}"
+SHARD_COUNT="${CLONING_SHARD_COUNT:-50}"
+SHARD_CONCURRENCY="${CLONING_SHARD_CONCURRENCY:-5}"
+DEV_SIZE="${CLONING_DEV_SIZE:-0}"
+TEST_SIZE="${CLONING_TEST_SIZE:-33}"
+SEED="${CLONING_SEED:-20260514}"
+
+mkdir -p "${LOG_ROOT}"
+
+for ENV_FILE in "${PROJECT_ROOT}/.env" "${PROJECT_ROOT}/react_code_bioagent_deepseek/.env" "${PROJECT_ROOT}/LAB-Bench/.env"; do
+  if [[ -f "${ENV_FILE}" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "${ENV_FILE}"
+    set +a
+  fi
+done
+
+export DEEPSEEK_BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
+export DEEPSEEK_MODEL_NAME="${DEEPSEEK_MODEL_NAME:-deepseek-chat}"
+export REACT_CODE_API_KEY="${REACT_CODE_API_KEY:-${DEEPSEEK_API_KEY:-${BIOMNI_CUSTOM_API_KEY:-}}}"
+export REACT_CODE_BASE_URL="${REACT_CODE_BASE_URL:-${DEEPSEEK_BASE_URL}}"
+export REACT_CODE_MODEL="${REACT_CODE_MODEL:-${DEEPSEEK_MODEL_NAME}}"
+
+wait_limited() {
+  local -n pid_array="$1"
+  if [[ "${#pid_array[@]}" -lt "${SHARD_CONCURRENCY}" ]]; then
+    return
+  fi
+  local pid="${pid_array[0]}"
+  wait "${pid}" || true
+  pid_array=("${pid_array[@]:1}")
+}
+
+count_rows() {
+  local file="$1"
+  if [[ -f "${file}" ]]; then
+    wc -l < "${file}"
+  else
+    echo 0
+  fi
+}
+
+run_react_code_bioagent() {
+  local runner="${PROJECT_ROOT}/React+code_labbench/run_labbench_react_code.py"
+  local out="${PROJECT_ROOT}/react_code_bioagent_deepseek/labbench_runs/react_code_cloningscenarios_${RUN_ID}"
+  local result="${out}/cloningscenarios_results.jsonl"
+  local reasoning="${out}/cloningscenarios_reasoning.log"
+  mkdir -p "${out}/shard_logs"
+  touch "${result}" "${reasoning}"
+  echo "react_code_bioagent output=${out}"
+  echo "react_code_bioagent before_rows=$(count_rows "${result}")"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "react_code_bioagent_cloningscenarios_shard%02dof%02d" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${runner}" \
+      --eval CloningScenarios \
+      --split test \
+      --dev-size "${DEV_SIZE}" \
+      --test-size "${TEST_SIZE}" \
+      --seed "${SEED}" \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --output-root "${out}" \
+      --result-file "${result}" \
+      --reasoning-log "${reasoning}" \
+      --skip-existing-results \
+      > "${out}/shard_logs/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "react_code_bioagent after_rows=$(count_rows "${result}")"
+}
+
+run_base_deepseek() {
+  local runner="${PROJECT_ROOT}/react_code_bioagent_deepseek/react_code_bioagent/labbench_runner.py"
+  local out="${PROJECT_ROOT}/base_llm_labbench/results/cloningscenarios_base_deepseek_${RUN_ID}"
+  local result="${out}/cloningscenarios_results.jsonl"
+  local reasoning="${out}/cloningscenarios_reasoning.log"
+  mkdir -p "${out}/shard_logs"
+  touch "${result}" "${reasoning}"
+  echo "base_deepseek output=${out}"
+  echo "base_deepseek before_rows=$(count_rows "${result}")"
+  local pids=()
+  for ((shard=0; shard<SHARD_COUNT; shard++)); do
+    local label
+    label="$(printf "base_deepseek_cloningscenarios_shard%02dof%02d" "$((shard + 1))" "${SHARD_COUNT}")"
+    "${PYTHON_BIN}" "${runner}" \
+      --evals CloningScenarios \
+      --splits test \
+      --dev-size "${DEV_SIZE}" \
+      --test-size "${TEST_SIZE}" \
+      --seed "${SEED}" \
+      --n-threads 1 \
+      --shard-index "${shard}" \
+      --shard-count "${SHARD_COUNT}" \
+      --output-root "${out}" \
+      --compact-results-path "${result}" \
+      --reasoning-log-path "${reasoning}" \
+      --skip-existing-results \
+      > "${out}/shard_logs/${label}.log" 2>&1 &
+    pids+=("$!")
+    wait_limited pids
+  done
+  for pid in "${pids[@]}"; do wait "${pid}" || true; done
+  echo "base_deepseek after_rows=$(count_rows "${result}")"
+}
+
+echo "RUN_ID=${RUN_ID}"
+echo "SHARD_COUNT=${SHARD_COUNT}"
+echo "SHARD_CONCURRENCY=${SHARD_CONCURRENCY}"
+
+run_react_code_bioagent > "${LOG_ROOT}/react_code_bioagent_deepseek.log" 2>&1 &
+pid_react=$!
+run_base_deepseek > "${LOG_ROOT}/base_deepseek.log" 2>&1 &
+pid_base=$!
+
+echo "react_code_bioagent_pid=${pid_react}"
+echo "base_deepseek_pid=${pid_base}"
+echo "log_root=${LOG_ROOT}"
+
+wait "${pid_react}" || true
+wait "${pid_base}" || true
+echo "finished RUN_ID=${RUN_ID}"