gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/biomni/references/api_reference.md

Biomni API Reference

Comprehensive API documentation for the biomni framework.

A1 Agent Class

The A1 class is the primary interface for interacting with biomni.

Initialization

from biomni.agent import A1

agent = A1(
    path: str,              # Path to data lake directory
    llm: str,               # LLM model identifier
    verbose: bool = True,   # Enable verbose logging
    mcp_config: str = None  # Path to MCP server configuration
)

Parameters:

• path (str, required) - Directory path for biomni data lake (~11GB). Data is automatically downloaded on first use if not present.

• llm (str, required) - LLM model identifier. Options include:

  • 'claude-sonnet-4-20250514' - Recommended for balanced performance
  • 'claude-opus-4-20250514' - Maximum capability
  • 'gpt-4', 'gpt-4-turbo' - OpenAI models
  • 'gemini-2.0-flash-exp' - Google Gemini
  • 'llama-3.3-70b-versatile' - Via Groq
  • Custom model endpoints via provider configuration

• verbose (bool, optional, default=True) - Enable detailed logging of agent reasoning, tool use, and code execution.

• mcp_config (str, optional) - Path to MCP (Model Context Protocol) server configuration file for external tool integration.

Example:

# Basic initialization
agent = A1(path='./biomni_data', llm='claude-sonnet-4-20250514')

# With MCP integration
agent = A1(
    path='./biomni_data',
    llm='claude-sonnet-4-20250514',
    mcp_config='./.biomni/mcp_config.json'
)

Core Methods

go(query: str) -> str

Execute a biomedical research task autonomously.

result = agent.go(query: str)

Parameters:

• query (str) - Natural language description of the biomedical task to execute

Returns:

• str - Final answer or analysis result from the agent

Behavior:

1. Decomposes query into executable sub-tasks
2. Retrieves relevant knowledge from integrated databases
3. Generates and executes Python code for analysis
4. Iterates on results until task completion
5. Returns final synthesized answer

Example:

result = agent.go("""
Identify genes associated with Alzheimer's disease from GWAS data.
Perform pathway enrichment analysis on top hits.
""")
print(result)

save_conversation_history(output_path: str, format: str = 'pdf')

Save complete conversation history including task, reasoning, code, and results.

agent.save_conversation_history(
    output_path: str,
    format: str = 'pdf'
)

Parameters:

• output_path (str) - File path for saved report
• format (str, optional, default='pdf') - Output format: 'pdf', 'html', or 'markdown'

Example:

agent.save_conversation_history('reports/alzheimers_gwas_analysis.pdf')

reset()

Reset agent state and clear conversation history.

agent.reset()

Use when starting a new independent task to clear previous context.

Example:

# Task 1
agent.go("Analyze dataset A")
agent.save_conversation_history("task1.pdf")

# Reset for fresh context
agent.reset()

# Task 2 - independent of Task 1
agent.go("Analyze dataset B")

Configuration via default_config

Global configuration parameters accessible via biomni.config.default_config.

from biomni.config import default_config

# LLM Configuration
default_config.llm = "claude-sonnet-4-20250514"
default_config.llm_temperature = 0.7

# Execution Parameters
default_config.timeout_seconds = 1200  # 20 minutes
default_config.max_iterations = 50     # Max reasoning loops
default_config.max_tokens = 4096       # Max tokens per LLM call

# Code Execution
default_config.enable_code_execution = True
default_config.sandbox_mode = False    # Enable for restricted execution

# Data and Caching
default_config.data_cache_dir = "./biomni_cache"
default_config.enable_caching = True

Key Parameters:

• timeout_seconds (int, default=1200) - Maximum time for task execution. Increase for complex analyses.

• max_iterations (int, default=50) - Maximum agent reasoning loops. Prevents infinite loops.

• enable_code_execution (bool, default=True) - Allow agent to execute generated code. Disable for code generation only.

• sandbox_mode (bool, default=False) - Enable sandboxed code execution (requires additional setup).

BiomniEval1 Evaluation Framework

Framework for benchmarking agent performance on biomedical tasks.

Initialization

from biomni.eval import BiomniEval1

evaluator = BiomniEval1(
    dataset_path: str = None,  # Path to evaluation dataset
    metrics: list = None        # Evaluation metrics to compute
)

Example:

evaluator = BiomniEval1()

Methods

evaluate(task_type: str, instance_id: str, answer: str) -> float

Evaluate agent answer against ground truth.

score = evaluator.evaluate(
    task_type: str,     # Task category
    instance_id: str,   # Specific task instance
    answer: str         # Agent-generated answer
)

Parameters:

• task_type (str) - Task category: 'crispr_design', 'scrna_analysis', 'gwas_interpretation', 'drug_admet', 'clinical_diagnosis'
• instance_id (str) - Unique identifier for task instance from dataset
• answer (str) - Agent's answer to evaluate

Returns:

• float - Evaluation score (0.0 to 1.0)

Example:

# Generate answer
result = agent.go("Design CRISPR screen for autophagy genes")

# Evaluate
score = evaluator.evaluate(
    task_type='crispr_design',
    instance_id='autophagy_001',
    answer=result
)
print(f"Score: {score:.2f}")

load_dataset() -> dict

Load the Biomni-Eval1 benchmark dataset.

dataset = evaluator.load_dataset()

Returns:

• dict - Dictionary with task instances organized by task type

Example:

dataset = evaluator.load_dataset()

for task_type, instances in dataset.items():
    print(f"{task_type}: {len(instances)} instances")

run_benchmark(agent: A1, task_types: list = None) -> dict

Run full benchmark evaluation on agent.

results = evaluator.run_benchmark(
    agent: A1,
    task_types: list = None  # Specific task types or None for all
)

Returns:

• dict - Results with scores, timing, and detailed metrics per task

Example:

results = evaluator.run_benchmark(
    agent=agent,
    task_types=['crispr_design', 'scrna_analysis']
)

print(f"Overall accuracy: {results['mean_score']:.2f}")
print(f"Average time: {results['mean_time']:.1f}s")

Data Lake API

Access integrated biomedical databases programmatically.

Gene Database Queries

from biomni.data import GeneDB

gene_db = GeneDB(path='./biomni_data')

# Query gene information
gene_info = gene_db.get_gene('BRCA1')
# Returns: {'symbol': 'BRCA1', 'name': '...', 'function': '...', ...}

# Search genes by pathway
pathway_genes = gene_db.search_by_pathway('DNA repair')
# Returns: List of gene symbols in pathway

# Get gene interactions
interactions = gene_db.get_interactions('TP53')
# Returns: List of interacting genes with interaction types

Protein Structure Access

from biomni.data import ProteinDB

protein_db = ProteinDB(path='./biomni_data')

# Get AlphaFold structure
structure = protein_db.get_structure('P38398')  # BRCA1 UniProt ID
# Returns: Path to PDB file or structure object

# Search PDB database
pdb_entries = protein_db.search_pdb('kinase', resolution_max=2.5)
# Returns: List of PDB IDs matching criteria

Clinical Data Access

from biomni.data import ClinicalDB

clinical_db = ClinicalDB(path='./biomni_data')

# Query ClinVar variants
variant_info = clinical_db.get_variant('rs429358')  # APOE4 variant
# Returns: {'significance': '...', 'disease': '...', 'frequency': ...}

# Search OMIM for disease
disease_info = clinical_db.search_omim('Alzheimer')
# Returns: List of OMIM entries with gene associations

Literature Search

from biomni.data import LiteratureDB

lit_db = LiteratureDB(path='./biomni_data')

# Search PubMed abstracts
papers = lit_db.search('CRISPR screening cancer', max_results=10)
# Returns: List of paper dictionaries with titles, abstracts, PMIDs

# Get citations for paper
citations = lit_db.get_citations('PMID:12345678')
# Returns: List of citing papers

MCP Server Integration

Extend biomni with external tools via Model Context Protocol.

Configuration Format

Create .biomni/mcp_config.json:

{
  "servers": {
    "fda-drugs": {
      "command": "python",
      "args": ["-m", "mcp_server_fda"],
      "env": {
        "FDA_API_KEY": "${FDA_API_KEY}"
      }
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Using MCP Tools in Tasks

# Initialize with MCP config
agent = A1(
    path='./data',
    llm='claude-sonnet-4-20250514',
    mcp_config='./.biomni/mcp_config.json'
)

# Agent can now use MCP tools automatically
result = agent.go("""
Search for FDA-approved drugs targeting EGFR.
Get their approval dates and indications.
""")
# Agent uses fda-drugs MCP server automatically

Error Handling

Common exceptions and handling strategies:

from biomni.exceptions import (
    BiomniException,
    LLMError,
    CodeExecutionError,
    DataNotFoundError,
    TimeoutError
)

try:
    result = agent.go("Complex biomedical task")
except TimeoutError:
    # Task exceeded timeout_seconds
    print("Task timed out. Consider increasing timeout.")
    default_config.timeout_seconds = 3600
except CodeExecutionError as e:
    # Generated code failed to execute
    print(f"Code execution error: {e}")
    # Review generated code in conversation history
except DataNotFoundError:
    # Required data not in data lake
    print("Data not found. Ensure data lake is downloaded.")
except LLMError as e:
    # LLM API error
    print(f"LLM error: {e}")
    # Check API keys and rate limits

Best Practices

Efficient API Usage

1. Reuse agent instances for related tasks to maintain context
2. Set appropriate timeouts based on task complexity
3. Use caching to avoid redundant data downloads
4. Monitor iterations to detect reasoning loops early

Production Deployment

from biomni.agent import A1
from biomni.config import default_config
import logging

# Configure logging
logging.basicConfig(level=logging.INFO)

# Production settings
default_config.timeout_seconds = 3600
default_config.max_iterations = 100
default_config.sandbox_mode = True  # Enable sandboxing

# Initialize with error handling
try:
    agent = A1(path='/data/biomni', llm='claude-sonnet-4-20250514')
    result = agent.go(task_query)
    agent.save_conversation_history(f'reports/{task_id}.pdf')
except Exception as e:
    logging.error(f"Task {task_id} failed: {e}")
    # Handle failure appropriately

Memory Management

For large-scale analyses:

# Process datasets in chunks
chunk_results = []
for chunk in dataset_chunks:
    agent.reset()  # Clear memory between chunks
    result = agent.go(f"Analyze chunk: {chunk}")
    chunk_results.append(result)

# Combine results
final_result = combine_results(chunk_results)