DETAILS.md

# 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