🧬 Biomedical Knowledge Lookup

A unified Python library for biological concept lookup across 29+ biomedical knowledge sources including BioPortal, OLS, UMLS, ChEMBL, DisGeNET, and more. Built for bioinformatics researchers, knowledge graph developers, and biomedical data scientists.

✨ Features

• 🔍 29+ Knowledge Sources: Comprehensive coverage of biomedical ontologies and databases
• ✅ CURIE Validation: Built-in CURIE/URI validation and normalization using bioregistry
• ⚡ Unified API: Single interface for all sources with consistent results
• 🔄 Multi-source Annotation: Cross-reference concepts across multiple databases
• 📊 RDF Export: Convert results to RDF format for knowledge graphs
• 💾 Intelligent Caching: Built-in caching system for performance optimization
• 🔄 Async Support: Asynchronous operations for scalable applications
• 🧪 Comprehensive Testing: Full test suite with unit and integration tests
• 📚 Rich Documentation: Extensive examples and API documentation

🚀 Quick Start

Installation

# core — all HTTP-only adapters (OLS, BioPortal, MONDO, HPO, UniProt, DrugBank,
# OxO, Zooma, PubChem, Ensembl, …), CURIE parsing, RDF export
pip install biomedical-knowledge-lookup

# optional feature groups (add one or more)
pip install "biomedical-knowledge-lookup[curie]"        # bioregistry/curies/pyobo CURIE normalization
pip install "biomedical-knowledge-lookup[umls]"         # UMLS adapter (needs a UMLS API key)
pip install "biomedical-knowledge-lookup[chembl]"       # ChEMBL adapter
pip install "biomedical-knowledge-lookup[bioservices]"  # EUtils / QuickGO / UniChem adapters
pip install "biomedical-knowledge-lookup[tyto]"         # Tyto adapter (owlready2)
pip install "biomedical-knowledge-lookup[agents]"       # LangGraph LLM agent workflow
pip install "biomedical-knowledge-lookup[export]"       # pandas DataFrame / Excel export
pip install "biomedical-knowledge-lookup[all]"          # everything

# from source
git clone https://github.com/JonasHeinickeBio/biomedical-knowledge-lookup.git
cd biomedical-knowledge-lookup
poetry install                          # core + dev
poetry install --all-extras             # everything
poetry install --extras "curie umls"    # selected groups

The core install pulls no heavy dependencies — every optional dependency guards its own import, so import knowledge_lookup and all HTTP-only adapters work without any extra, and an adapter/feature that needs a missing extra is simply disabled (a clear ImportError if you instantiate it directly). CURIE validation via the curie extra enables bioregistry-based CURIE/URI parsing, validation, and normalization using the bioregistry, curies, and pyobo libraries.

Basic Usage

from knowledge_lookup import CentralKnowledgeLookup, KnowledgeSource

# Initialize the lookup system
lookup = CentralKnowledgeLookup()

# Search for concepts across multiple sources
results = await lookup.search_concepts(
    "diabetes mellitus",
    sources=[KnowledgeSource.BIOPORTAL, KnowledgeSource.OLS, KnowledgeSource.UMLS]
)

# Get detailed information about a specific concept
concept_details = await lookup.get_concept_details("DOID:9351")

Advanced Usage with Multi-source Annotation

from knowledge_lookup import MultiSourceAnnotator

# Annotate text with concepts from multiple sources
annotator = MultiSourceAnnotator()
annotations = await annotator.annotate_text(
    "Type 2 diabetes is associated with insulin resistance",
    confidence_threshold=0.7
)

# Get consensus annotations across sources
consensus = annotator.get_consensus_annotations(annotations)

📋 Supported Knowledge Sources

🏗️ Architecture

knowledge_lookup/
├── adapters/           # Individual source adapters
├── models.py          # Data models and enums
├── central_lookup.py  # Main lookup coordinator
├── multi_source_annotator.py  # Cross-source annotation
├── rdf_converter.py   # RDF export utilities
├── cache.py          # Caching system
└── base.py           # Abstract base classes

📖 Documentation

• Getting Started Guide
• API Reference
• CURIE Management - CURIE/URI parsing, validation, and normalization
• Adapter Documentation
• Examples
• Contributing Guide

Additional Resources

• Documentation Improvement Summary
• Project Overview

Example Notebooks

Explore interactive examples in the examples/ directory:

• Basic concept lookup
• Multi-source annotation
• RDF export and knowledge graph construction
• Performance benchmarking

🔧 Configuration

CURIE Validation

The curie extra adds a standalone curie_utils toolkit built on bioregistry for validating and normalizing CURIEs and URIs. It is not yet wired into CentralKnowledgeLookup's query parsing or deduplication — see CURIE Management for the full picture and for cross-ontology mapping via find_mappings()/OxO.

from knowledge_lookup.curie_utils import normalize_curie, validate_prefix

# Validate prefixes
is_valid = validate_prefix("doid")  # True
is_valid = validate_prefix("invalid_prefix")  # False

# Normalize a CURIE's prefix to bioregistry's canonical form (same ontology,
# not a cross-ontology mapping)
normalized = normalize_curie("DOID:9351")  # "doid:9351"

API Keys

Some sources require API keys. Set them as environment variables:

export BIOPORTAL_API_KEY="your_key_here"
export UMLS_API_KEY="your_key_here"
# ... etc

Or create a .env file:

BIOPORTAL_API_KEY=your_key_here
UMLS_API_KEY=your_key_here

Advanced Configuration

from knowledge_lookup import LookupConfig

config = LookupConfig(
    rate_limits={
        KnowledgeSource.BIOPORTAL: 10,  # requests per second
        KnowledgeSource.OLS: 20,
    },
    cache_enabled=True,
    cache_dir="./cache"
)

lookup = CentralKnowledgeLookup(config)

🧪 Testing

# Run all tests
poetry run pytest

# Run specific test categories
poetry run pytest -m "unit"        # Unit tests only
poetry run pytest -m "integration" # Integration tests
poetry run pytest -m "not slow"    # Skip slow tests

# Run with coverage
poetry run pytest --cov=knowledge_lookup

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Adding New Adapters

1. Extend KnowledgeSourceAdapter in base.py
2. Implement required methods: search_concepts(), get_concept_details()
3. Add CURIE validation using curie_utils module
4. Add to adapters/__init__.py
5. Add tests in tests/unit/test_adapters/
6. Update documentation

CURIE Validation in Adapters

When implementing adapters, use the curie_utils module for CURIE validation:

from ..curie_utils import validate_prefix, normalize_curie, parse_curie_or_uri

# Validate prefix before queries
if validate_prefix("doid"):
    logger.debug("doid is a known bioregistry prefix")

# Parse query as CURIE/URI
parsed = parse_curie_or_uri(query)
if parsed:
    prefix, identifier = parsed

# Normalize a CURIE's prefix to its canonical bioregistry form
normalized = normalize_curie("DOID:9351")  # "doid:9351"

Development Setup

git clone https://github.com/JonasHeinickeBio/biomedical-knowledge-lookup.git
cd biomedical-knowledge-lookup
poetry install
poetry run pre-commit install

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built upon the AID-PAIS Knowledge Graph project
• Thanks to all contributors and the biomedical research community
• Special thanks to the maintainers of the various knowledge sources

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: jonas.heinicke@helmholtz-hzi.de

🔬 Citation

If you use this library in your research, please cite:

@software{heinicke_biomedical_knowledge_lookup_2025,
  author = {Heinicke, Jonas},
  title = {Biomedical Knowledge Lookup: Unified biological concept lookup across 29+ biomedical knowledge sources},
  url = {https://github.com/JonasHeinickeBio/biomedical-knowledge-lookup},
  version = {1.0.0},
  year = {2025}
}

⭐ Star this repository if you find it useful!