bmlibrarian-lite 0.3.0

Lightweight biomedical literature research tool - no PostgreSQL required

BMLibrarian Lite

A lightweight biomedical literature research tool - no PostgreSQL required.

BMLibrarian Lite is a simplified version of BMLibrarian that provides AI-powered literature search and analysis capabilities without requiring a PostgreSQL database nor a powerful GPU and fast memory for local AI. It uses only the PubMed E-utilities API for searching and fetching article metadata instead of a local database. It uses SQLite with sqlite-vec for vector storage and metadata, making it easy to install and use on any machine. Also, in order to allow it to run on computers with limited resources, it uses FastEmbed for local embeddings and allows to use cloud LLM providers like Anthropic Claude instead of relying exclusively on local inference. Using local models with ollama is optional.

Platform Support

BMLibrarian Lite is available on multiple platforms:

Platform	Technology	Status
Desktop	Python/PySide6	Production
iOS	Swift/SwiftUI	Production
macOS	Swift/SwiftUI	Production
Android	Kotlin/Jetpack Compose	Production

Features

Desktop Application (Python/PySide6)

Cross-platform desktop application for comprehensive systematic literature review.

• Systematic Literature Review: Search PubMed, score documents, extract citations, and generate reports
• Document Interrogation: Interactive Q&A with loaded documents
• PDF Discovery & Download: Automatic PDF retrieval from PubMed Central, Unpaywall, and DOI resolution
• Quality Assessment: Automated study quality evaluation with evidence grading
• Multi-Model Benchmarking: Compare LLM models on relevance scoring and quality classification
• Research Questions Management: Save, re-run, and manage past research questions
• Audit Trail: Real-time visibility into the review workflow with LLM reasoning transparency
• Multiple LLM Providers: Support for both Anthropic Claude (online) and Ollama (local)
• Unified SQLite Storage: Single database for metadata and vector embeddings - no external database needed

iOS App (Swift/SwiftUI)

Native iOS app for medical fact-checking on-the-go.

• Medical Fact Checker: Verify medical claims against peer-reviewed literature
• Dual Scoring System: LLM-based relevance scoring plus on-device NLEmbedding semantic similarity
• HyDE Enhancement: Hypothetical Document Embedding for improved semantic matching
• Budget Controls: Per-run and monthly spending limits with real-time cost tracking
• SwiftData Persistence: Local storage of sessions, documents, citations, and reports
• Clickable Citations: Tap references in reports to view source document details
• Smart Search: Automatic alternative query generation when initial results are insufficient
• iCloud Sync: CloudKit integration for syncing data across devices

macOS App (Swift/SwiftUI)

Native macOS app optimized for desktop workflows.

• Native macOS UI: Optimized layouts for larger screens with keyboard navigation
• PDF Export: Native AppKit-based PDF generation with A4/Letter paper sizes
• Full-Text Viewer: View retrieved full-text articles with JATS XML rendering
• Hybrid Search: Search both PubMed and Europe PMC simultaneously
• iCloud Sync: CloudKit integration for syncing with iOS devices
• Future-Ready: Architecture prepared for local LLM processing and PostgreSQL backend

Android App (Kotlin/Jetpack Compose)

Native Android app with Material 3 design.

• Material 3 Design: Modern UI following Google's Material You guidelines
• Medical Fact Checker: Same fact-checking workflow as iOS/macOS
• Jetpack Compose UI: Declarative, modern Android UI toolkit
• Room Database: Local persistence with SQLite via Room
• Hilt Dependency Injection: Clean architecture with Dagger Hilt
• Budget Controls: Per-run and monthly spending limits
• Multiple Search Providers: Support for PubMed and Europe PMC
• PDF Export: Generate evidence reports as PDF documents
• Session History: Browse and revisit past fact-check sessions

Quick Start

Desktop Installation

From PyPI (recommended):

pip install bmlibrarian-lite

From source:

# Clone the repository
git clone https://github.com/hherb/bmlibrarian-lite.git
cd bmlibrarian-lite

# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Configuration

1. Set your Anthropic API key (for Claude):

   export ANTHROPIC_API_KEY="your-api-key-here"
   

2. Or configure Ollama (for local models):

   # Install Ollama: https://ollama.ai
   ollama pull llama3.2
   export OLLAMA_HOST="http://localhost:11434"
   

3. Optional: Set your email for PubMed (recommended):

   export NCBI_EMAIL="[e-mail]"
   

4. Optional: Configure PDF Discovery (for Unpaywall API):

   • Go to Settings in the GUI
   • Enter your email address for Unpaywall API access
   • Configure OpenAthens if you have institutional access

Running the Application

# Launch the GUI (short command)
bmll

# Or using the full name
bmlibrarian-lite

# Or using Python module
python -m bmlibrarian_lite

CLI Commands

# Show storage statistics
bmll stats

# Validate configuration
bmll validate --verbose

# Show current configuration
bmll config

# Clear all data
bmll clear

# Show version
bmll --version

iOS App

The iOS app is located in ios/MedicalFactChecker/. To build:

1. Open in Xcode: Open ios/MedicalFactChecker/MedicalFactChecker.xcodeproj
2. Configure signing: Set your development team in project settings
3. Build and run: Select your target device/simulator and build

Configuration in iOS:

• Open Settings tab to configure:
  • LLM API endpoint and key (OpenAI-compatible APIs)
  • NCBI email for PubMed API
  • Per-run and monthly budget limits
  • Enable/disable embedding scoring

macOS App

The macOS app is a separate project located in macos/MedicalFactCheckerMac/. To build:

1. Open in Xcode: Open macos/MedicalFactCheckerMac/MedicalFactCheckerMac.xcodeproj
2. Configure signing: Set your development team in project settings
3. Build and run: Select "My Mac" as the target and build

Or build from command line:

cd macos/MedicalFactCheckerMac
xcodebuild -project MedicalFactCheckerMac.xcodeproj \
           -scheme MedicalFactCheckerMac \
           -configuration Debug \
           build

The macOS app shares the same core functionality as iOS but is designed to evolve independently with features like local LLM support and PostgreSQL backend.

Android App

The Android app is located in android/MedicalFactChecker/. To build:

1. Open in Android Studio: Open the android/MedicalFactChecker directory
2. Sync Gradle: Android Studio will automatically sync dependencies
3. Build and run: Select your target device/emulator and click Run

Or build from command line:

cd android/MedicalFactChecker
./gradlew assembleDebug

Configuration in Android:

• Open Settings screen to configure:
  • LLM provider and API endpoint (OpenAI, Anthropic, or custom)
  • API key (stored securely in EncryptedSharedPreferences)
  • NCBI email for PubMed API
  • Per-run and monthly budget limits
  • Search provider preferences (PubMed, Europe PMC, or both)

Requirements:

• Android 8.0 (API 26) or higher
• Internet connection for API access

Usage

Systematic Review Workflow

1. Enter your research question in the main text area
2. Click "Search" to query PubMed
3. Review found articles and adjust filters as needed
4. Score documents for relevance (1-5 scale)
5. Extract citations from high-scoring documents
6. Generate a report synthesizing the evidence

Research Questions Tab

The Research Questions tab helps you manage and revisit past research:

• View past questions: See all research questions with document counts and scores
• Re-run searches: Incrementally search for new documents with automatic deduplication
• Context menu actions: Re-classify study designs, re-score relevance, or delete questions
• Run benchmarks: Compare model performance directly from saved questions

Multi-Model Benchmarking

Compare how different LLM models perform on your documents:

• Relevance Score Benchmarking: Compare scoring consistency across models

  • Agreement matrices showing model-to-model consistency
  • Score distribution analysis
  • Cost and latency tracking per model

• Quality Assessment Benchmarking: Compare study design classification

  • Design agreement matrix
  • Tier agreement for quality levels
  • Document-level disagreement highlighting

Access benchmarking from the Systematic Review tab after scoring documents.

Audit Trail

The Audit Trail tab provides real-time visibility into the systematic review workflow:

• Queries Tab: View generated PubMed queries and search statistics
• Literature Tab: Browse document cards with relevance scores and quality badges
  • Click cards to expand and view abstracts
  • See LLM rationales for scoring and quality decisions
  • Quality badges show study design (RCT, Systematic Review, etc.)
• Citations Tab: View extracted citation passages with highlighting

Right-click any document card to send it to the Document Interrogator for deeper analysis.

iOS Medical Fact Checker

1. Enter a medical claim or question (e.g., "Vitamin D reduces COVID-19 severity")
2. Tap "Check Evidence" to start the workflow
3. Review scored documents with dual LLM/Embedding scores
4. View the evidence report with verdict and supporting citations
5. Tap citations to view source document details

Score Comparison:

• LLM scores use AI reasoning about document relevance
• Embedding scores use on-device NLEmbedding with HyDE (Hypothetical Document Embedding)
• Agreement indicators show when scores align or differ

Android Medical Fact Checker

1. Enter a medical claim on the Fact Check screen
2. Tap "Check" to start the fact-checking workflow
3. Review scored documents as they are processed
4. Optionally fetch more documents if initial results are insufficient
5. View the evidence report with verdict badge and supporting citations
6. Tap references to view source document details
7. Export as PDF to share or save the report

Features:

• Progress indicators show each workflow step
• Budget tracking displays estimated costs before and during runs
• History tab shows all past sessions for easy reference

Document Interrogation

1. Switch to the "Document Interrogation" tab
2. Load a document (PDF, TXT, or MD file)
3. Ask questions about the document content
4. Get AI-powered answers with source references

Configuration

Configuration is stored in ~/.bmlibrarian_lite/config.json:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "embeddings": {
    "model": "BAAI/bge-small-en-v1.5"
  },
  "pubmed": {
    "email": "[e-mail]"
  },
  "search": {
    "chunk_size": 512,
    "chunk_overlap": 50,
    "similarity_threshold": 0.7,
    "max_results": 100
  }
}

LLM Providers

Anthropic Claude (default):

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Ollama (local):

{
  "llm": {
    "provider": "ollama",
    "model": "llama3.2"
  }
}

You can also use the model string format: anthropic:claude-sonnet-4-20250514 or ollama:llama3.2

Requirements

• Python 3.12+
• Internet connection (for PubMed search and Claude API)
• ~500MB disk space for embeddings cache

Dependencies

• sqlite-vec: Vector similarity search extension for SQLite
• fastembed: CPU-optimized embeddings
• anthropic: Claude API client
• ollama: Ollama API client
• PySide6: GUI framework
• PyMuPDF: PDF processing

Differences from Full BMLibrarian

BMLibrarian Lite is designed for ease of use and portability:

Feature	BMLibrarian	Desktop (Python)	iOS App	macOS App	Android App
Database	PostgreSQL + pgvector	SQLite + sqlite-vec	SwiftData	SwiftData*	Room (SQLite)
Embeddings	Ollama (local)	FastEmbed (CPU)	Apple NLEmbedding	Apple NLEmbedding	N/A
PDF Discovery	Full	Included	N/A	N/A	N/A
PDF Export	N/A	N/A	Included	Included	Included
Multi-Agent Workflow	Full orchestration	Simplified	Streamlined	Streamlined	Streamlined
Plugin System	Lab plugins	N/A	N/A	N/A	N/A
Multi-Model Benchmarking	N/A	Included	N/A	N/A	N/A
Research Questions	N/A	Save & re-run	History view	History view	History view
Budget Controls	N/A	N/A	Per-run & monthly	Per-run & monthly	Per-run & monthly
HyDE Embedding	N/A	N/A	Included	Included	N/A
Local LLM Support	N/A	Ollama	N/A	Planned	N/A
Search Providers	N/A	PubMed	PubMed + Europe PMC	PubMed + Europe PMC	PubMed + Europe PMC
Installation	Complex	pip install	Xcode build	Xcode build	Android Studio

*macOS app is designed to support PostgreSQL backend in future versions.

Documentation

Documentation is organized into three categories:

• User Documentation (doc/user/): End-user guides and tutorials
• Developer Documentation (doc/developer/): Architecture, API, and contribution guides
• LLM Context (doc/llm/): Context for AI assistants working with the codebase
  • golden_rules.md - Coding standards
  • database-schema.md - Database schema reference

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy src/

License

Copyright (C) 2024-2025 Dr Horst Herb

AGPL-3.0 License - see LICENSE file for details.

Acknowledgments

BMLibrarian Lite is derived from BMLibrarian, a comprehensive biomedical literature research platform.

Support

• Issues: GitHub Issues
• Documentation: See the doc/ directory for detailed guides