AffiBio

Gene and variant analysis tool combining Affinage (literature evidence) with Biomni (LLM-powered biomedical reasoning) to produce comprehensive reports.

Quick Start

Windows

setup.bat
notepad .env
run.bat

Linux / macOS

chmod +x setup.sh run.sh
./setup.sh
nano .env
./run.sh

Editable install (any platform)

pip install -e .
biomni-analyze --help

CLI directly

biomni-analyze analyze --genes TP53 BRCA1
biomni-analyze analyze --vcf variants.vcf
biomni-analyze analyze --phenotype "hereditary breast cancer"

Web Interface

streamlit run app.py

Opens browser at http://localhost:8501. Supports gene symbols, phenotype, and VCF file upload (.vcf or .vcf.gz).

LLM Providers

Provider	Cost	API Key	Env Variable
LM Studio	Free (local)	None needed	LLM_PROVIDER=lmstudio
Groq	Free tier	console.groq.com	GROQ_API_KEY=gsk_...
Gemini	Free tier	aistudio.google.com	GEMINI_API_KEY=AIza...
Ollama	Free (local)	None needed	LLM_PROVIDER=ollama
NIM	Free tier	build.nvidia.com	NIM_API_KEY=nvapi-...
Cerebras	Free tier	cerebras.ai	CEREBRAS_API_KEY=csk-...

Set provider in .env:

LLM_PROVIDER=lmstudio
LLM_BASE_URL=http://localhost:1234/v1
LLM_MODEL_NAME=qwen2.5-vl-3b-instruct

Analysis Pipeline

Input (gene / phenotype / VCF)
        |
        v
  [1] VEP Annotation  ─── Ensembl REST API (VCF only)
        |
        v
  [2] Affinage Lookup ─── ClinVar + PubMed evidence
        |
        v
  [3] Biomni Analysis ─── LLM-powered biomedical reasoning
        |                  (dynamic tool selection + structured enforcement)
        v
  [4] HTML Report

• VEP: Annotates variants with HGVS nomenclature via Ensembl (GRCh38). Skips gracefully if API unreachable.
• Affinage: Fetches clinical significance, literature citations, and phenotype associations. Uses gene symbols only.
• Biomni: LLM agent with dynamic tool selection and structured output enforcement.

Dynamic Tool Selection

Biomni ships 218+ tools across biochemistry, genomics, pharmacology, etc. Loading all of them into the system prompt blows past local 16K context windows. The tool filter selects only the tools relevant to each query type:

Query Type	Tools Kept	Examples
variant	~25	clinvar, gnomad, ensembl, dbsnp, opentarget, somatic mutation detection
gene	~20	uniprot, alphafold, pdb, kegg, stringdb, gene sequence tools
phenotype	~20	opentarget, monarch, gwas, clinicaltrials, drug interaction tools

Core tools (pubmed, google search, python REPL) are always included. Dead-end tools (advanced_web_search_claude, query_scholar) are always excluded.

Selective Datalake Download

Biomni's full datalake is ~11GB across 76 files. Instead of downloading everything, the system only fetches files needed by the tools selected for each query type:

Query Type	Datalake Files	What's Downloaded
variant	16	hp.obo, variant_table, gene_info, genebass_.pkl, omim, gwas_catalog, ddinter_.csv
gene	8	ddinter_*.csv only
phenotype	9	ddinter_*.csv + gwas_catalog.pkl

Most tools (ClinVar, gnomAD API, PubMed, Ensembl, dbSNP, OpenTargets, STRING, KEGG, Reactome) use live REST APIs and need zero datalake files. Only tools that read local parquet/pkl/csv/txt trigger downloads. Gene-specific filtering happens naturally via the API query parameters (e.g., query_gnomad("TP53") only fetches TP53 data from the live API).

Structured Agent Enforcement

The Biomni A1 harness has a known defect: the model can mark checklist items [✓] without a matching <observation> in the execution trace. The structured enforcement layer:

1. Parses the agent's actual <execute> / <observation> log
2. For each [✓] checklist item, checks if the referenced tool produced an observation
3. Downgrades unsupported [✓] to [✗] with a log message

This prevents fabricated claims from appearing as confirmed results in reports.

Project Structure

bioinfo/
  .gitignore            # Git ignore rules
  .env                  # Configuration (LLM provider, API keys) — not committed
  .env.example          # Template
  app.py                # Streamlit web interface
  pyproject.toml        # Modern Python packaging (pip install -e .)
  requirements.txt      # Pip dependencies
  setup.bat             # Windows installer
  setup.sh              # Linux/macOS installer (creates .venv)
  run.bat               # Windows interactive CLI menu
  run.sh                # Linux/macOS interactive CLI menu
  web.bat               # Windows quick web launcher
  affinage_biomni/
    __init__.py
    cli.py              # Click CLI commands
    config.py           # .env config loader
    models.py           # Pydantic data models
    pipeline.py         # 5-stage analysis pipeline
    affinage/           # Affinage API client (ClinVar/PubMed)
    biomni/             # Biomni agent wrapper
      agent.py          # Agent runner, tool filtering, structured enforcement
      tool_filter.py    # Dynamic tool selection + selective datalake by query type
    report/             # HTML report generation
    utils/              # File I/O helpers
    vcf/                # VCF parser + VEP client
  tests/                # Test files

API Keys

API keys are masked in CLI output (only last 4 chars shown). Never commit .env to version control.

Known Limitations

• Ensembl/gnomAD: May be unreachable from some networks (DNS timeout). Pipeline skips VEP gracefully if unavailable.
• Context window: Local models with small context (16K) may still struggle. Dynamic tool selection reduces tool count from 218 to ~25, which helps significantly.
• Biomni upstream bug: Agent can self-certify checklist steps without tool execution. Mitigated by structured enforcement (downgrades unverified [✓] to [✗]) + warning banners in reports.

Requirements

• Python 3.10+
• Windows (.bat), Linux/macOS (.sh), or any platform via pip install -e .
• LM Studio running locally (for lmstudio provider), or a cloud API key