Skip to content

Qt GUI User Guide

BMLibrarian Qt GUI is a modern desktop application for biomedical literature research. It provides a powerful, user-friendly interface for searching, analyzing, and reviewing biomedical literature using AI-powered agents.

Key Features

  • Multi-Tab Interface: Organize different research tasks in separate tabs
  • AI-Powered Search: Natural language queries converted to database searches
  • Document Scoring: AI relevance scoring for research questions
  • Citation Extraction: Automatic extraction of relevant passages
  • Report Generation: Professional research reports with citations
  • Fact-Checking: Review and annotate biomedical statements
  • Dark Theme: Comfortable viewing in low-light environments
  • Customizable: Configure plugins, themes, and preferences

Installation and Setup

Prerequisites

  • Python: Version 3.12 or higher
  • PostgreSQL: Database with pgvector extension
  • Ollama: Local AI model server (running on http://localhost:11434)

Installation Steps

  1. Clone the Repository: 

    git clone https://github.com/hherb/bmlibrarian.git
cd bmlibrarian

  2. Install Dependencies: 

    uv sync

  3. Configure Database:

  4. Edit .env file with your PostgreSQL credentials

  5. Run database setup: uv run python initial_setup_and_download.py test.env

  6. Start Ollama (if not already running): 

    ollama serve

  7. Launch the Application: 

    uv run python bmlibrarian_qt.py

User Interface Overview

Main Window Components

┌─────────────────────────────────────────────────────────────┐
│ File   View   Tools   Help                        Menu Bar  │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────┬──────────┬──────────┬────────────┬───────────┐ │
│ │Research │  Search  │  Fact    │ Query Lab  │   Config  │ │
│ └─────────┴──────────┴──────────┴────────────┴───────────┘ │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │                                                       │ │
│  │                 Active Tab Content                    │ │
│  │                                                       │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│ Ready                                              Status   │
└─────────────────────────────────────────────────────────────┘
  • File: Export, Exit
  • View: Tab navigation, Theme selection, Reload plugins
  • Tools: Configuration
  • Help: About BMLibrarian, About Qt

Using the Tabs

Research Tab

The Research tab provides a complete workflow for biomedical literature research.

Workflow

  1. Enter Research Question: 

    "What are the cardiovascular benefits of exercise?"

  2. Generate Query: AI converts your question to a database query

  3. Search Documents: Execute search and review results

  4. Score Documents: AI scores relevance (1-5 scale)

  5. Extract Citations: Get relevant passages from high-scoring documents

  6. Generate Report: Create a professional research report

  7. Export: Save report to file

Best Practice

Be specific in your research questions. Review the generated SQL query for accuracy.

Search Tab

Advanced document search with multiple filter criteria.

Features

  • Text Search: Search titles and abstracts
  • Year Range Filter: Filter by publication year
  • Journal Filter: Search specific journals
  • Source Filter: PubMed, medRxiv, or all
  • Result Limit: Control number of results
  • Document Cards: Visual result display

How to Use

  1. Enter search terms in the text field
  2. Apply filters (year range, journal, source)
  3. Set result limit (10-1000)
  4. Click "Search" button
  5. Click any document card for details

Configuration Tab

Manage application settings and agent configurations.

Sections

General Settings:

  • Ollama server URL
  • Database connection
  • Default parameters

Agent Configuration:

  • Query Agent: Model, temperature, top-p for query generation
  • Scoring Agent: Model and parameters for document scoring
  • Citation Agent: Settings for citation extraction
  • Reporting Agent: Report generation configuration

Multi-Model Query Generation:

  • Enable/disable multi-model queries
  • Select models to use
  • Configure query diversity

Fact-Checker Tab

Review and annotate biomedical statements for fact-checking.

How to Use

  1. Load statements from file
  2. Review statement and AI evaluation
  3. Examine supporting citations
  4. Select: Yes / Maybe / No
  5. Enter explanation for your decision
  6. Navigate to next statement

Keyboard Shortcuts

Global Shortcuts

Shortcut Action
Ctrl+Q Quit application
Ctrl+E Export (when available)
Ctrl+, Open Configuration
Ctrl+R Reload plugins
F1 Show Help/About

Tab Navigation

Shortcut Action
Alt+1 Go to first tab
Alt+2 Go to second tab
Alt+3 Go to third tab
Ctrl+Tab Next tab
Ctrl+Shift+Tab Previous tab

Theme

Shortcut Action
Ctrl+Shift+T Toggle light/dark theme

Customization

Themes

BMLibrarian supports two built-in themes:

  • Light Theme (Default): Clean, professional appearance
  • Dark Theme: Reduced eye strain in low light

To change themes:

  1. Menu: View → Theme → Light Theme / Dark Theme
  2. Keyboard: Press Ctrl+Shift+T
  3. Restart application when prompted

Configuration File

Edit ~/.bmlibrarian/gui_config.json to customize:

{
  "gui": {
    "theme": "dark",
    "tabs": {
      "enabled_plugins": [
        "research",
        "search",
        "fact_checker",
        "query_lab",
        "configuration"
      ],
      "default_tab": "research"
    }
  }
}

Troubleshooting

Application Won't Start

  1. Check Python version: python --version (must be 3.12+)
  2. Verify dependencies: uv sync
  3. Check logs: ~/.bmlibrarian/gui_qt.log
  4. Delete config and retry: rm ~/.bmlibrarian/gui_config.json

Database Connection Error

  1. Verify PostgreSQL is running
  2. Check .env file credentials
  3. Test connection: psql -h localhost -U your_user -d knowledgebase

Ollama Not Available

  1. Start Ollama: ollama serve
  2. Verify: curl http://localhost:11434
  3. Install models: ollama pull gpt-oss:20b

FAQ

Q: Do I need an internet connection?

A: No, once the database is populated and Ollama models are downloaded, BMLibrarian works entirely offline.

Q: How much disk space do I need?

A: Depends on database size:

  • Minimal (100K articles): ~10 GB
  • Medium (1M articles): ~100 GB
  • Full PubMed (38M articles): ~500+ GB

Q: Where are my settings stored?

A: Two configuration files:

  • GUI settings: ~/.bmlibrarian/gui_config.json
  • Agent settings: ~/.bmlibrarian/config.json