{"id":45899177,"url":"https://github.com/hherb/bmlibrarian","last_synced_at":"2026-02-27T22:02:21.103Z","repository":{"id":310201435,"uuid":"1039057338","full_name":"hherb/bmlibrarian","owner":"hherb","description":"Multi-agentic biomedical literature research system with counterfactual analsyis and extensive citation system","archived":false,"fork":false,"pushed_at":"2026-02-12T11:27:41.000Z","size":26016,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-12T20:00:08.015Z","etag":null,"topics":["agents","biomedical","citations","literature-review","local-llm","medical","medical-research","medical-research-agent","medrxiv","open-access-research","pubmed","unpaywall"],"latest_commit_sha":null,"homepage":"https://bmlibrarian.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hherb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audit_validation_gui.py","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-16T11:42:50.000Z","updated_at":"2026-02-12T11:27:45.000Z","dependencies_parsed_at":"2025-08-16T13:46:49.880Z","dependency_job_id":"47a4b977-3afe-4ed6-b280-fdbb32163421","html_url":"https://github.com/hherb/bmlibrarian","commit_stats":null,"previous_names":["hherb/bmlibrarian"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/hherb/bmlibrarian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hherb%2Fbmlibrarian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hherb%2Fbmlibrarian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hherb%2Fbmlibrarian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hherb%2Fbmlibrarian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hherb","download_url":"https://codeload.github.com/hherb/bmlibrarian/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hherb%2Fbmlibrarian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29917207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"ssl_error","status_checked_at":"2026-02-27T19:37:41.463Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","biomedical","citations","literature-review","local-llm","medical","medical-research","medical-research-agent","medrxiv","open-access-research","pubmed","unpaywall"],"created_at":"2026-02-27T22:02:20.432Z","updated_at":"2026-02-27T22:02:21.078Z","avatar_url":"https://github.com/hherb.png","language":"Python","funding_links":[],"categories":["Multi-Agent Medical Systems"],"sub_categories":[],"readme":"# BMLibrarian\n\n**The Biomedical Researcher's AI Workbench**\n\nBMLibrarian is a comprehensive AI-powered platform designed to be a complete workbench for biomedical researchers, clinicians, and systematic reviewers. It provides evidence-based answers to clinical questions, peer-review quality automated assessment of research papers, and systematic fact-checking of biomedical statements—all powered by local AI models requiring no cloud APIs or external services.\n\n## Why BMLibrarian?\n\n### Evidence-Based Answers to Clinical Questions\n\nAsk questions like *\"What are the cardiovascular benefits of exercise?\"* or *\"Does metformin reduce mortality in diabetic patients?\"* and receive comprehensive, citation-backed reports synthesizing evidence from the latest biomedical literature.\n\n### Automated Research Quality Assessment\n\nEvaluate research papers with the rigor of peer review:\n- **Paper Weight Assessment**: Evaluate the evidential weight of studies based on study design, sample size, methodological quality, and risk of bias\n- **PRISMA 2020 Compliance**: Assess systematic reviews against the 27-item PRISMA 2020 checklist\n- **PICO Extraction**: Automatically extract Population, Intervention, Comparison, and Outcome components for systematic reviews\n\n### Robust Fact-Checking\n\nValidate biomedical statements with literature evidence:\n- **Statement Fact-Checker**: Evaluate claims like *\"Vaccine X causes Y\"* against published literature\n- **PaperChecker**: Validate research abstract claims by systematically searching for contradictory evidence\n- **Counterfactual Analysis**: Actively search for evidence that contradicts initial findings for balanced conclusions\n\n### Works Offline—Critical for Global Health\n\nBMLibrarian is designed for clinicians and researchers working in areas with limited or unreliable internet connectivity:\n\n- **Runs entirely with local AI models** via Ollama—no cloud APIs required\n- **Local database** of PubMed and medRxiv publications with full-text PDFs where available\n- **No API keys, subscriptions, or external services needed**\n- **Periodic synchronization** with PubMed and medRxiv when connected\n- **Complete functionality offline** after initial data import\n\nThis makes BMLibrarian uniquely valuable for healthcare workers in remote regions, field hospitals, developing nations, or any environment where reliable internet cannot be guaranteed.\n\n### Multiple Search Strategies with AI Assistance\n\nBMLibrarian employs sophisticated multi-strategy search capabilities:\n- **Multi-model query generation**: Use multiple AI models to generate diverse database queries\n- **Semantic search**: Vector-based similarity search using document embeddings\n- **HyDE (Hypothetical Document Embeddings)**: Generate hypothetical answers to improve search relevance\n- **Keyword extraction**: Traditional keyword-based search as fallback\n- **Counterfactual search**: Actively search for contradictory evidence\n\n### Privacy-Preserving AI\n\nAll AI processing happens locally on your hardware:\n- **No data leaves your machine**—perfect for sensitive patient data or pre-publication research\n- **No usage tracking or telemetry**\n- **Complete control over model selection and parameters**\n\n## What's New\n\n**Latest Features (02/2026):**\n\n### Paper Reviewer Lab\n\nA comprehensive paper assessment tool that combines all of BMLibrarian's analysis agents into a single unified workflow. Accepts input via DOI, PMID, PDF file, or pasted text.\n\n```bash\n# Launch the Paper Reviewer Lab\nuv run python scripts/paper_reviewer_lab.py\n```\n\n**11-Step Assessment Workflow:**\n1. Resolve Input (fetch document metadata via DOI/PMID/PDF/text)\n2. Generate Summary (2-3 sentence synopsis)\n3. Extract Hypothesis (identify core claims)\n4. Detect Study Type (classify research methodology)\n5. PICO Analysis (Population/Intervention/Comparison/Outcome)\n6. PRISMA 2020 Assessment (systematic review checklist, if applicable)\n7. Paper Weight Assessment (evidential weight scoring)\n8. Study Quality Assessment (trustworthiness evaluation)\n9. Synthesize Strengths/Weaknesses\n10. Search Contradictory Evidence (optional PubMed search)\n11. Compile Comprehensive Report\n\n**Key Features:**\n- Multiple input methods: DOI, PMID, PDF file, pasted abstract text\n- Real-time workflow progress visualization (PySide6/Qt)\n- Model selection from available Ollama models\n- Results display in Markdown and JSON\n- Export to Markdown, PDF, or JSON\n\n### Systematic Literature Review Agent\n\nA complete systematic review automation system with human oversight and audit trails. Conducts AI-assisted literature reviews following PRISMA 2020 guidelines with configurable search strategies, quality assessment, and composite scoring.\n\n```bash\n# Run a systematic review\nuv run python systematic_review_cli.py --question \"Effect of statins on CVD prevention\" \\\n    --include \"RCTs\" \"Human studies\" --exclude \"Animal studies\"\n\n# GUI with checkpoint-based resume capability\nuv run python systematic_review_gui.py\n```\n\n**Key Capabilities:**\n- **Multi-strategy search**: Semantic, keyword, hybrid, and HyDE queries with PICO analysis\n- **9-phase workflow**: Search planning, execution, filtering, scoring, quality assessment, composite scoring, classification, evidence synthesis, reporting\n- **Cochrane/GRADE assessment**: Integrated quality assessment with GRADE formatting\n- **Checkpoint-based resume**: Save and resume reviews across sessions\n- **Human checkpoints**: Interactive mode pauses at key decision points for human review\n- **Quality assessment**: Integrates StudyAssessmentAgent, PaperWeightAssessmentAgent, PICOAgent, and PRISMA2020Agent\n- **Complete audit trail**: Full reproducibility with JSON, Markdown, CSV, and PRISMA flow diagram outputs\n- **Configurable weights**: Customize relevance, quality, recency, and source reliability weights\n\n### Europe PMC Full-Text and PDF Import\n\nDownload and import full-text articles and PDFs from Europe PMC's Open Access repository.\n\n```bash\n# List available Europe PMC packages (~1000+ files, ~100 articles each)\nuv run python europe_pmc_bulk_cli.py list\n\n# Download and import full-text XML with Markdown conversion\nuv run python europe_pmc_bulk_cli.py sync --output-dir ~/europepmc\n\n# Download Open Access PDFs\nuv run python europe_pmc_pdf_cli.py download --output-dir ~/europepmc_pdf\n```\n\n**Key Features:**\n- JATS XML to Markdown conversion (headers, figures, tables, emphasis)\n- Resumable downloads with progress tracking\n- Configurable rate limiting (polite mode)\n- Year-based PDF organization\n- PMCID range filtering\n\n### PubMed Search Lab\n\nInteractive PubMed search directly via the PubMed API, without requiring a local database.\n\n```bash\nuv run python scripts/pubmed_search_lab.py\n```\n\n**Key Features:**\n- Natural language to PubMed query conversion\n- MeSH term lookup and expansion\n- Search results display with abstracts\n- No local database required\n\n### Audit Trail Validation GUI\n\nA human review interface for validating automated evaluations in the systematic review audit trail.\n\n```bash\nuv run python audit_validation_gui.py --user alice\nuv run python audit_validation_gui.py --user alice --incremental\n```\n\n**Key Features:**\n- Tab-per-step organization for Queries, Scores, Citations, Reports, and Counterfactuals\n- Validation statuses: Validated, Incorrect, Uncertain, or Needs Review\n- Error categorization with 25+ predefined categories\n- Statistics dashboard with reviewer performance tracking\n- Multi-reviewer support for inter-rater reliability studies\n\n### Citation-Aware Writing Editor\n\nA markdown editor with integrated citation management for academic writing.\n\n**Key Features:**\n- Citation markers with `[@id:12345:Smith2023]` format\n- Semantic search for finding references\n- Multiple citation styles: Vancouver, APA, Harvard, Chicago\n- Autosave with version history\n- Export with formatted reference lists\n- PostgreSQL-backed document persistence\n\n### Other Recent Features\n\n- **Paper Weight Assessment**: Evaluate research papers across five quality dimensions (study design, sample size, methodology, bias risk, replication)\n- **PICO Extraction**: Automatically extract Population, Intervention, Comparison, and Outcome for systematic reviews\n- **PRISMA 2020 Compliance**: Assess systematic reviews against the full 27-item PRISMA 2020 checklist\n- **Document Interrogation**: Interactive Q\u0026A interface for asking questions about loaded PDF, Markdown, or text documents\n- **Full-Text PDF Discovery**: Automated discovery and download from PMC, Unpaywall, DOI resolution, and OpenAthens\n- **Transparency Assessment**: Detect undisclosed bias risk by evaluating funding disclosure, COI statements, data availability, trial registration, and author contributions (CLI, Lab GUI, bulk metadata enrichment)\n- **PaperChecker System**: Fact-check medical abstracts by searching for contradictory literature evidence\n- **Fact Checker System**: LLM training data auditing with literature validation (CLI, desktop GUI, blind mode, incremental mode, SQLite integration)\n- **Multi-Model Query Generation**: Use up to 3 AI models simultaneously for 20-40% more relevant documents\n- **Semantic Chunking**: Multiple chunking strategies (adaptive, sentence-based, SpaCy NLP) with vector embeddings for improved retrieval\n- **LLM Provider Abstraction**: Unified interface across multiple LLM providers with token tracking\n- **Thesaurus/MeSH Expansion**: Term expansion and synonym lookup for improved search coverage\n- **User Authentication**: Login system with per-user database-backed settings\n- **PubMed Download Repair**: CLI for detecting and fixing corrupted gzip files in bulk downloads\n- **PostgreSQL Audit Trail**: Complete persistent tracking of research workflow sessions\n- **Automatic Database Migrations**: Zero-configuration schema updates on startup\n\n## Overview\n\nBMLibrarian transforms how researchers interact with biomedical literature by combining AI-powered natural language processing with robust database infrastructure. The system employs multiple specialized AI agents that work together to convert research questions into comprehensive, evidence-based medical reports with proper citations and balanced analysis of contradictory evidence.\n\n## ARCHITECTURAL SCALE\n\n### Codebase Statistics\n\n- **728 Python files** organized in hierarchical module structure\n- **1,390 classes** implementing specialized functionality\n- **9,671 functions** providing granular capabilities\n- **~211,000 lines of code** (excluding comments, docstrings, and blank lines; ~298,000 total)\n- **~8,800 docstrings** for comprehensive documentation\n- **145 test files** with comprehensive test coverage\n- **272 documentation files** (Markdown)\n- **100% type hints** for all public APIs and data structures\n- **26 top-level CLI/GUI applications**\n- **17 GUI plugins** in the Qt plugin system\n\n### Comparison to Established Systems\n\n| System | Lines of Code | Domain | Status |\n|--------|---------------|--------|--------|\n| Redis | ~30,000 | Database | Production |\n| nginx | ~100,000 | Web server | Production |\n| Django | ~300,000 | Web framework | Production |\n| **BMLibrarian** | **~211,000** | **Biomedical AI** | **Production-ready** |\n\n**BMLibrarian exceeds the scale of many mature, widely-deployed infrastructure software projects.**\n\n---\n\n## WHAT THIS SCALE REPRESENTS\n\n### Not a PhD Side Project — Infrastructure Software\n\n**Multi-layer architecture:**\n- **Core database layer:** PostgreSQL integration with custom query optimization\n- **Vector search layer:** pgvector integration with HNSW indexing at 40M+ document scale\n- **Agent orchestration layer:** 15+ specialized AI agents with sophisticated coordination\n- **Workflow management layer:** Persistent task queuing, state management, error recovery\n- **Multiple user interfaces:** CLI, desktop GUI (PySide6/Qt), laboratory tools\n- **Full-text discovery system:** Multi-source PDF retrieval with browser automation\n- **Semantic chunking system:** Multiple chunking strategies with vector embeddings\n- **LLM provider abstraction:** Unified interface with token tracking across providers\n- **Research quality assessment:** PRISMA 2020, PICO extraction, study design evaluation, paper weight scoring\n- **Fact-checking infrastructure:** Statement validation, training data auditing, abstract fact-checking\n- **Systematic review automation:** Checkpoint-based reviews with Cochrane/GRADE assessment\n- **Configuration management:** Hierarchical config system with database-backed user settings\n- **User authentication:** Login system with per-user settings and session management\n- **Database migrations:** Automatic schema updates with version tracking\n- **Comprehensive documentation:** 272 markdown files covering user guides + developer docs\n\n### Development Methodology\n\n**Professional software engineering practices:**\n- Type hints throughout (Python 3.12+)\n- Comprehensive unit testing (134 test files)\n- Modular architecture with clear separation of concerns\n- Configuration-driven design (no hardcoded parameters)\n- Extensive error handling and logging\n- Database transaction management and connection pooling\n- Async/parallel processing where appropriate\n- GUI/CLI separation for testability\n- Plugin architecture for extensibility (17 GUI plugins)\n---\n\n## Fact Checker System\n\nThe **BMLibrarian Fact Checker** is a specialized tool for auditing biomedical statements in LLM training datasets, medical knowledge bases, and research claims. It evaluates statement veracity by searching literature databases and comparing claims against published evidence.\n\n### Core Capabilities\n\n- **Automated Verification**: Evaluates biomedical statements as yes/no/maybe based on literature evidence\n- **Evidence Extraction**: Provides specific citations with stance indicators (supports/contradicts/neutral)\n- **Batch Processing**: Process hundreds of statements from JSON input files\n- **Confidence Assessment**: Rates confidence (high/medium/low) based on evidence strength and consistency\n- **Citation Validation**: Prevents hallucination by validating all citations reference real database documents\n- **Human Review Interface**: Desktop GUI for annotation, comparison, and quality control\n\n### Key Features\n\n#### CLI Tool (`fact_checker_cli.py`)\n- **Batch fact-checking** from JSON input files\n- **Incremental processing** - smart detection of previously evaluated statements\n- **SQLite database storage** for persistent results and annotations\n- **Flexible thresholds** for relevance scoring and citation extraction\n- **Quick mode** for faster testing with reduced document sets\n- **Detailed output** with evidence metadata and validation statistics\n\n#### Review GUI (`fact_checker_review_gui.py`)\n- **Interactive human review** with statement-by-statement navigation\n- **Blind mode** - hide AI evaluations to prevent bias during human annotation\n- **Incremental mode** - filter to show only unannotated statements for efficient review\n- **Database integration** - automatic SQLite database creation from JSON files\n- **Intelligent merging** - import new statements without overwriting existing annotations\n- **Citation inspection** - expandable cards with full abstracts and highlighted passages\n- **Multi-user support** - track annotations by different reviewers\n- **Export functionality** - save human-annotated results for analysis\n\n### Use Cases\n\n1. **LLM Training Data Auditing**: Verify factual accuracy of biomedical statements in training datasets\n2. **Medical Knowledge Validation**: Check medical claims against current literature\n3. **Dataset Quality Control**: Identify potentially incorrect statements in medical corpora\n4. **Evidence-Based Verification**: Validate medical facts with specific literature references\n5. **Research Claim Verification**: Evaluate research statements before publication\n\n### Database Workflow\n\nThe fact checker uses SQLite databases for persistent storage:\n\n1. **First run with JSON**: Creates `.db` file alongside input JSON (e.g., `results.json` → `results.db`)\n2. **Subsequent runs**: Intelligently merges new statements from JSON without overwriting existing evaluations/annotations\n3. **Real-time persistence**: All AI evaluations and human annotations saved immediately to database\n4. **Incremental processing**: Skip already-evaluated statements with `--incremental` flag\n5. **Cross-tool compatibility**: CLI and GUI share the same database format\n\n### Example Workflow\n\n```bash\n# Step 1: Generate fact-check results from statements\nuv run python fact_checker_cli.py statements.json -o results.json\n# Creates: results.json (JSON output) and results.db (SQLite database)\n\n# Step 2: Review with GUI in blind mode (no AI bias)\nuv run python fact_checker_review_gui.py --input-file results.db --blind --user alice\n# Human reviewer annotates statements without seeing AI evaluations\n\n# Step 3: Review remaining statements in normal mode\nuv run python fact_checker_review_gui.py --input-file results.db --incremental --user alice\n# Shows only statements not yet annotated by alice\n\n# Step 4: Export annotated results\n# Use GUI \"Save Reviews\" button → results_annotated.json\n\n# Step 5: Analyze results\nuv run python analyze_factcheck_progress.py results_annotated.json\n```\n\n## PaperChecker System\n\nThe **BMLibrarian PaperChecker** is a sophisticated fact-checking system for medical abstracts that validates research claims by systematically searching for and analyzing contradictory evidence.\n\n### Core Capabilities\n\n- **Statement Extraction**: Identifies core research claims (hypothesis, finding, conclusion) from abstracts\n- **Counter-Evidence Search**: Multi-strategy search (semantic + HyDE + keyword) for contradictory literature\n- **Evidence-Based Verdicts**: Three-class classification (supports/contradicts/undecided) with confidence levels\n- **Complete Audit Trail**: Full provenance tracking from search to final verdict\n- **Batch Processing**: CLI for processing multiple abstracts with database persistence\n\n### Key Features\n\n#### CLI Tool (`paper_checker_cli.py`)\n- **Batch fact-checking** of medical abstracts from JSON or by PMID\n- **Multi-strategy search** combining semantic, HyDE, and keyword approaches\n- **Counter-report generation** synthesizing contradictory evidence\n- **Markdown export** for detailed reports per abstract\n- **Database persistence** in PostgreSQL `papercheck` schema\n\n#### Laboratory GUI (`paper_checker_lab.py`)\n- **Interactive testing** with step-by-step workflow visualization\n- **Real-time progress** showing each processing stage\n- **Results inspection** for all intermediate outputs\n- **Native desktop application** (PySide6/Qt)\n\n### Workflow Overview\n\n```\nAbstract → Statement Extraction → Counter-Statement Generation →\nMulti-Strategy Search → Document Scoring → Citation Extraction →\nCounter-Report Generation → Verdict Analysis → JSON/Markdown Output\n```\n\n### Example Usage\n\n```bash\n# Check abstracts from JSON file\nuv run python paper_checker_cli.py abstracts.json -o results.json\n\n# Export detailed markdown reports\nuv run python paper_checker_cli.py abstracts.json --export-markdown reports/\n\n# Check abstracts by PMID from database\nuv run python paper_checker_cli.py --pmid 12345678 23456789\n\n# Quick mode for testing\nuv run python paper_checker_cli.py abstracts.json --quick\n\n# Interactive laboratory\nuv run python paper_checker_lab.py\n```\n\n### Documentation\n\n- [User Guide](doc/users/paper_checker_guide.md) - Overview and quick start\n- [CLI Guide](doc/users/paper_checker_cli_guide.md) - Command-line reference\n- [Laboratory Guide](doc/users/paper_checker_lab_guide.md) - Interactive testing\n- [Architecture](doc/developers/paper_checker_architecture.md) - System design\n\n## Paper Weight Assessment\n\nThe **Paper Weight Assessment** system evaluates the evidential strength of biomedical research papers based on multiple dimensions, providing a comprehensive quality score that helps researchers and clinicians assess how much weight to give to study findings.\n\n### Assessment Dimensions\n\n| Dimension | Weight | What It Evaluates |\n|-----------|--------|-------------------|\n| **Study Design** | 25% | Research methodology (RCT, cohort, case-control, etc.) |\n| **Sample Size** | 15% | Statistical power, confidence intervals, power calculations |\n| **Methodological Quality** | 30% | Randomization, blinding, protocol registration, ITT analysis |\n| **Risk of Bias** | 20% | Selection, performance, detection, and reporting biases |\n| **Replication Status** | 10% | Whether findings have been replicated by other studies |\n\n### Example Usage\n\n```bash\n# Launch the Paper Weight Laboratory (GUI)\nuv run python paper_weight_lab.py\n\n# Features:\n# - Search documents by PMID, DOI, or title\n# - Real-time assessment progress tracking\n# - Detailed audit trail for each dimension\n# - Configurable dimension weights\n# - Export to Markdown or JSON\n```\n\n### Documentation\n\n- [User Guide](doc/users/paper_weight_lab_guide.md) - Complete laboratory guide\n\n## PICO Extraction System\n\nThe **PICO Agent** extracts structured components from biomedical research papers using the PICO framework—essential for systematic reviews and evidence-based medicine.\n\n### What is PICO?\n\n- **P**opulation: Who was studied? (demographics, condition, setting)\n- **I**ntervention: What was done? (treatment, test, exposure)\n- **C**omparison: What was the control? (placebo, alternative treatment)\n- **O**utcome: What was measured? (effects, results, endpoints)\n\n### Example Usage\n\n```python\nfrom bmlibrarian.agents import PICOAgent\n\nagent = PICOAgent(model=\"gpt-oss:20b\")\nextraction = agent.extract_pico_from_document(document)\n\nprint(f\"Population: {extraction.population}\")\nprint(f\"Intervention: {extraction.intervention}\")\nprint(f\"Comparison: {extraction.comparison}\")\nprint(f\"Outcome: {extraction.outcome}\")\nprint(f\"Confidence: {extraction.extraction_confidence:.1%}\")\n```\n\n```bash\n# Interactive PICO Laboratory\nuv run python pico_lab.py\n\n# Batch process documents\n# Export to CSV for systematic review tools (Covidence, DistillerSR)\n```\n\n### Use Cases\n\n- **Systematic Reviews**: Rapidly extract PICO from hundreds of papers\n- **Meta-Analysis**: Standardize study data for quantitative synthesis\n- **Research Gap Analysis**: Identify understudied populations or outcomes\n- **Grant Writing**: Structure research questions using evidence-based frameworks\n\n### Documentation\n\n- [User Guide](doc/users/pico_agent_guide.md) - Complete PICO extraction guide\n- [Developer Documentation](doc/developers/pico_agent.md) - API reference\n\n## PRISMA 2020 Compliance Assessment\n\nThe **PRISMA 2020 Agent** assesses systematic reviews and meta-analyses against the PRISMA 2020 (Preferred Reporting Items for Systematic reviews and Meta-Analyses) 27-item checklist.\n\n### Assessment Process\n\n1. **Suitability Check**: Automatically determines if the document is a systematic review or meta-analysis\n2. **27-Item Assessment**: Evaluates all PRISMA checklist items with detailed explanations\n3. **Compliance Scoring**: Provides overall compliance percentage and category\n\n### Scoring System\n\n| Score | Category | Interpretation |\n|-------|----------|----------------|\n| 90-100% | Excellent | Outstanding adherence to PRISMA 2020 |\n| 75-89% | Good | Strong reporting with minor gaps |\n| 60-74% | Adequate | Acceptable with room for improvement |\n| 40-59% | Poor | Significant reporting deficiencies |\n| 0-39% | Very Poor | Major reporting failures |\n\n### Example Usage\n\n```bash\n# Launch the PRISMA 2020 Laboratory (GUI)\nuv run python prisma2020_lab.py\n\n# Features:\n# - Automatic suitability screening\n# - Color-coded compliance cards for each item\n# - Export assessments to JSON or CSV\n# - Batch processing multiple reviews\n```\n\n### Use Cases\n\n- **Self-assessment** before submitting systematic reviews to journals\n- **Peer review** of systematic review manuscripts\n- **Editorial screening** for journal submissions\n- **Training** on PRISMA 2020 standards\n\n### Documentation\n\n- [User Guide](doc/users/prisma2020_guide.md) - Complete assessment guide\n- [Developer Documentation](doc/developers/prisma2020_system.md) - System architecture\n\n## Document Interrogation\n\nThe **Document Interrogation** interface provides an interactive chat experience for asking questions about loaded documents (PDFs, Markdown, or text files).\n\n### Features\n\n- **Split-pane interface**: Document viewer (60%) and chat interface (40%)\n- **Multiple document formats**: PDF, Markdown (.md), text (.txt)\n- **Dialogue-style chat**: User and AI messages in distinct bubbles\n- **Full conversation history**: Scrollable message history\n- **Model selection**: Choose any available Ollama model\n\n### Example Usage\n\n```bash\n# Launch the Configuration GUI (includes Document Interrogation tab)\nuv run python bmlibrarian_config_gui.py\n\n# Workflow:\n# 1. Navigate to \"Document Interrogation\" tab\n# 2. Load a document (PDF, MD, or TXT)\n# 3. Select an Ollama model\n# 4. Ask questions about the document\n```\n\n### Example Questions\n\n- *\"What are the main findings of this study?\"*\n- *\"What methods did the authors use?\"*\n- *\"Are there any limitations mentioned?\"*\n- *\"Summarize the introduction section\"*\n\n### Documentation\n\n- [User Guide](doc/users/document_interrogation_guide.md) - Complete usage guide\n\n## Full-Text PDF Discovery\n\nThe **Full-Text Discovery** system automatically finds and downloads PDF versions of academic papers through legal open access channels.\n\n### Discovery Sources (in priority order)\n\n1. **PubMed Central (PMC)** - Verified open access repository\n2. **Unpaywall** - Open access aggregator (millions of papers)\n3. **DOI Resolution** - CrossRef and doi.org content negotiation\n4. **Direct URL** - Existing PDF URLs from database\n5. **OpenAthens** - Institutional proxy (if configured)\n\n### Example Usage\n\n```python\nfrom bmlibrarian.discovery import FullTextFinder, DocumentIdentifiers\n\n# Create finder with Unpaywall email\nfinder = FullTextFinder(unpaywall_email=\"your@email.com\")\n\n# Discover PDF sources\nidentifiers = DocumentIdentifiers(doi=\"10.1038/nature12373\")\nresult = finder.discover(identifiers)\n\nif result.best_source:\n    print(f\"Found: {result.best_source.url}\")\n    print(f\"Access: {result.best_source.access_type.value}\")\n```\n\n```bash\n# Download PDFs for documents in database\nuv run python -c \"from bmlibrarian.discovery import download_pdf_for_document; ...\"\n```\n\n### Key Features\n\n- **Multi-source discovery**: Searches PMC, Unpaywall, CrossRef, DOI.org\n- **Priority-based selection**: Automatically selects best source (open access preferred)\n- **Browser fallback**: Handles Cloudflare and anti-bot protections via Playwright\n- **Year-based organization**: PDFs stored in `YYYY/filename.pdf` structure\n- **Database integration**: Automatically updates document records with PDF paths\n\n### Documentation\n\n- [User Guide](doc/users/full_text_discovery_guide.md) - Complete discovery guide\n- [Developer Documentation](doc/developers/full_text_discovery_system.md) - System architecture\n\n## Key Features\n\n### Multi-Agent AI System\n- **QueryAgent**: Natural language to PostgreSQL query conversion\n- **SemanticQueryAgent**: Vector-based semantic search with embeddings\n- **DocumentScoringAgent**: Relevance scoring for research questions (1-5 scale)\n- **CitationFinderAgent**: Extracts relevant passages from high-scoring documents\n- **ReportingAgent**: Synthesizes citations into medical publication-style reports\n- **CounterfactualAgent**: Analyzes documents to generate research questions for finding contradictory evidence\n- **EditorAgent**: Creates balanced comprehensive reports integrating all evidence\n- **FactCheckerAgent**: Evaluates biomedical statements (yes/no/maybe) with literature evidence\n- **PaperCheckerAgent**: Validates medical abstract claims against contradictory literature evidence\n- **PaperReviewerAgent**: Comprehensive paper assessment combining all analysis agents in an 11-step workflow\n- **PICOAgent**: Extracts Population, Intervention, Comparison, and Outcome components\n- **PRISMA2020Agent**: Assesses systematic reviews against the 27-item PRISMA 2020 checklist\n- **StudyAssessmentAgent**: Evaluates research quality, study design, and bias risk\n- **PaperWeightAgent**: Evidential weight scoring across five quality dimensions\n- **TransparencyAgent**: Undisclosed bias risk detection via funding, COI, data availability, and trial registration analysis\n- **DocumentInterrogationAgent**: Interactive Q\u0026A with loaded documents (PDF, Markdown, text)\n- **SystematicReviewAgent**: Automated systematic literature review with Cochrane/GRADE assessment\n\n### Advanced Workflow Orchestration\n- **Enum-Based Workflow**: Flexible step orchestration with meaningful names\n- **Iterative Processing**: Query refinement, threshold adjustment, citation requests\n- **Task Queue System**: SQLite-based persistent task queuing for memory-efficient processing\n- **Human-in-the-Loop**: Interactive decision points with auto-mode support\n- **Branching Logic**: Conditional step execution and error recovery\n\n### Production-Ready Infrastructure\n- **Database Migration System**: Automated schema initialization and incremental updates with startup integration\n- **PostgreSQL + pgvector**: Semantic search with vector embeddings at 40M+ document scale\n- **Semantic Chunking**: Multiple strategies (adaptive, sentence-based, SpaCy NLP) with vector embeddings\n- **PostgreSQL Audit Trail**: Comprehensive tracking of research workflow sessions\n- **User Authentication**: Login system with per-user database-backed settings\n- **LLM Provider Abstraction**: Unified interface with token tracking across providers\n- **Local LLM Integration**: Ollama service for privacy-preserving AI inference\n- **134 Test Files**: Comprehensive test coverage across all modules\n- **16 GUI Plugins**: Modular PySide6/Qt plugin architecture\n- **Browser-Based Downloader**: Playwright automation for Cloudflare-protected PDFs (optional)\n\n### Advanced Analytics\n- **Multi-Model Query Generation**: Use multiple AI models (up to 3) to generate diverse database queries for 20-40% improved document retrieval\n- **Query Performance Tracking**: Real-time analysis of which models and parameters find the most relevant documents\n- **Counterfactual Analysis**: Systematic search for contradictory evidence with progressive audit trail\n- **Evidence Strength Assessment**: Quality evaluation with citation validation and rejection reasoning\n- **Temporal Precision**: Specific year references instead of vague temporal terms\n- **Document Verification**: Real database ID validation to prevent hallucination\n- **Citation Validation**: AI-powered verification that citations actually support counterfactual claims\n- **User Override Capability**: Expert users can override AI rejection decisions with custom reasoning\n- **Research Workflow Audit Trail**: PostgreSQL-based persistent tracking of complete research sessions\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/hherb/bmlibrarian.git\ncd bmlibrarian\n\n# Install dependencies using uv (recommended)\nuv sync\n```\n\n### Prerequisites\n\n- **Python**: 3.12+ (required for modern type hints and performance)\n- **Database**: PostgreSQL 12+ with pgvector extension\n- **AI/LLM**: Ollama server for local language model inference\n- **Extensions**: `pgvector`, `pg_trgm` for semantic search capabilities\n\n### Environment Setup\n\n1. **Configure database and AI settings:**\n```bash\n# Create .env file in project directory\ncat \u003e .env \u003c\u003c EOF\n# Database Configuration\nPOSTGRES_USER=your_username\nPOSTGRES_PASSWORD=your_password\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=5432\nPOSTGRES_DB=knowledgebase\n\n# File System\nPDF_BASE_DIR=~/knowledgebase/pdf\n\n# AI/LLM Configuration (Ollama typically runs on localhost:11434)\nOLLAMA_BASE_URL=http://localhost:11434\nEOF\n```\n\n2. **Start required services:**\n```bash\n# Start Ollama service (for AI inference)\nollama serve\n\n# Ensure PostgreSQL is running with pgvector extension\npsql -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\n```\n\n### Usage Examples\n\n#### Interactive Research CLI\n```bash\n# Start the comprehensive medical research CLI\nuv run python bmlibrarian_cli.py\n\n# Quick testing mode\nuv run python bmlibrarian_cli.py --quick\n\n# Automated mode with research question\nuv run python bmlibrarian_cli.py --auto \"What are the cardiovascular benefits of exercise?\"\n```\n\n#### Desktop Research Application\n```bash\n# Launch the GUI research application\nuv run python bmlibrarian_research_gui.py\n\n# Features:\n# - Visual workflow progress with collapsible step cards\n# - Real-time agent execution with model configuration\n# - Multi-model query generation with smart pagination and result tracking\n# - Query performance statistics showing model effectiveness\n# - Progressive counterfactual audit trail showing claims, queries, searches, and results\n# - Formatted markdown report preview with scrolling\n# - Direct file save functionality\n# - Complete transparency into citation validation and rejection reasoning\n# - Automatic audit trail persistence to PostgreSQL database\n```\n\n#### Configuration GUI\n```bash\n# Launch the configuration interface\nuv run python bmlibrarian_config_gui.py\n\n# Configure agents, models, and parameters through GUI:\n# - Model selection with live refresh from Ollama\n# - Parameter tuning with interactive sliders\n# - Multi-model query generation configuration tab\n# - Connection testing and validation\n# - Visual value displays for all configuration parameters\n```\n\n#### Fact Checker CLI for LLM Training Data Auditing\n```bash\n# Check biomedical statements against literature evidence\nuv run python fact_checker_cli.py input.json -o results.json\n\n# Input format (input.json):\n# [\n#   {\"statement\": \"All cases of childhood UC require colectomy\", \"answer\": \"no\"},\n#   {\"statement\": \"Vitamin D deficiency is common in IBD\", \"answer\": \"yes\"}\n# ]\n\n# This creates TWO outputs:\n#   - results.json: JSON file with fact-check results\n#   - results.db: SQLite database for persistent storage\n\n# Incremental mode - skip already-evaluated statements\nuv run python fact_checker_cli.py input.json -o results.json --incremental\n# Only processes new statements, preserves existing evaluations\n\n# Quick mode for faster testing\nuv run python fact_checker_cli.py input.json -o results.json --quick\n\n# Custom thresholds for precision control\nuv run python fact_checker_cli.py input.json -o results.json \\\n  --score-threshold 3.0 --max-search-results 100 --max-citations 15\n\n# Verbose mode with detailed output\nuv run python fact_checker_cli.py input.json -o results.json -v --detailed\n\n# Custom model selection\nuv run python fact_checker_cli.py input.json -o results.json \\\n  --model medgemma-27b-text-it-Q8_0:latest --temperature 0.15\n\n# Run demonstration\nuv run python examples/fact_checker_demo.py\n```\n\n#### Fact-Checker Review GUI\n```bash\n# Human review and annotation of fact-checking results\nuv run python fact_checker_review_gui.py\n\n# Load JSON file (auto-creates SQLite database for annotations)\nuv run python fact_checker_review_gui.py --input-file results.json\n\n# Load existing database directly\nuv run python fact_checker_review_gui.py --input-file results.db\n\n# BLIND MODE - hide AI evaluations to prevent annotation bias\nuv run python fact_checker_review_gui.py --input-file results.db --blind --user alice\n# Perfect for unbiased human annotation without AI influence\n\n# INCREMENTAL MODE - show only unannotated statements\nuv run python fact_checker_review_gui.py --input-file results.db --incremental --user alice\n# Efficiently review only statements you haven't annotated yet\n\n# Multi-user workflow with user tracking\nuv run python fact_checker_review_gui.py --input-file results.db --user bob\n# Track annotations by different reviewers\n\n# Features:\n# - Automatic SQLite database creation from JSON files\n# - Intelligent merging: import new statements without overwriting existing annotations\n# - Real-time persistence: all annotations saved immediately to database\n# - Statement-by-statement review with progress tracking\n# - Compare original, AI, and human annotations side-by-side\n# - Expandable citation cards with full abstracts and highlighted passages\n# - Color-coded stance indicators (supports/contradicts/neutral)\n# - Blind mode for unbiased annotation (hide AI evaluations)\n# - Incremental mode for efficient review (filter unannotated statements)\n# - Multi-user support with annotator metadata\n# - Export reviewed annotations to JSON file\n# - Perfect for quality control and training data validation\n```\n\n#### Browser-Based PDF Download (Optional)\n\nFor PDFs protected by Cloudflare or anti-bot measures:\n\n```bash\n# Install browser automation support (optional)\nuv add --optional browser\nuv run python -m playwright install chromium\n\n# Download PDFs using browser automation\nuv run python download_pdfs_with_browser.py --batch-size 20\n\n# Run with visible browser (for debugging)\nuv run python download_pdfs_with_browser.py --visible\n\n# Test the browser downloader\nuv run python test_browser_download.py\n```\n\nSee [BROWSER_DOWNLOADER.md](BROWSER_DOWNLOADER.md) for detailed documentation on:\n- Cloudflare bypass techniques\n- CAPTCHA handling\n- Stealth mode configuration\n- Performance optimization\n\n#### Multi-Agent Workflow (Programmatic)\n```python\nfrom bmlibrarian.agents import (\n    QueryAgent, DocumentScoringAgent, CitationFinderAgent, \n    ReportingAgent, CounterfactualAgent, EditorAgent, \n    AgentOrchestrator\n)\nfrom bmlibrarian.cli.workflow_steps import (\n    create_default_research_workflow, WorkflowExecutor\n)\n\n# Initialize orchestration system\norchestrator = AgentOrchestrator(max_workers=4)\nworkflow = create_default_research_workflow()\nexecutor = WorkflowExecutor(workflow)\n\n# Initialize specialized agents\nquery_agent = QueryAgent(orchestrator=orchestrator)\nscoring_agent = DocumentScoringAgent(orchestrator=orchestrator)\ncitation_agent = CitationFinderAgent(orchestrator=orchestrator)\nreporting_agent = ReportingAgent(orchestrator=orchestrator)\ncounterfactual_agent = CounterfactualAgent(orchestrator=orchestrator)\neditor_agent = EditorAgent(orchestrator=orchestrator)\n\n# Execute research workflow\nresearch_question = \"What are the cardiovascular benefits of exercise?\"\nexecutor.add_context('research_question', research_question)\n\n# The workflow handles: query generation, document search, scoring,\n# citation extraction, report generation, and counterfactual analysis\nfinal_report = executor.get_context('comprehensive_report')\n```\n\n## Architecture Overview\n\n### Multi-Agent System Architecture\n\nBMLibrarian employs a sophisticated multi-agent architecture where specialized AI agents collaborate to process biomedical literature:\n\n```mermaid\ngraph TD\n    A[Research Question] --\u003e B[QueryAgent]\n    B --\u003e C[Database Search]\n    C --\u003e D[DocumentScoringAgent]\n    D --\u003e E[CitationFinderAgent]\n    E --\u003e F[ReportingAgent]\n    F --\u003e G{Counterfactual Analysis?}\n    G --\u003e|Yes| H[CounterfactualAgent]\n    G --\u003e|No| I[EditorAgent]\n    H --\u003e J[Contradictory Evidence Search]\n    J --\u003e I\n    I --\u003e K[Comprehensive Report]\n```\n\n### Workflow Orchestration System\n\nThe enum-based workflow system provides flexible step orchestration:\n\n- **WorkflowStep Enum**: Meaningful step names instead of brittle numbering\n- **Repeatable Steps**: Query refinement, threshold adjustment, citation requests\n- **Branching Logic**: Conditional step execution and error recovery\n- **Context Management**: State preservation across step executions\n- **Auto Mode Support**: Graceful handling of non-interactive execution\n\n### Task Queue System\n\n- **QueueManager**: SQLite-based persistent task queuing\n- **AgentOrchestrator**: Coordinates multi-agent workflows\n- **Task Priorities**: HIGH, NORMAL, LOW priority levels\n- **Batch Processing**: Memory-efficient handling of large document sets\n\n## Application Suite\n\n### Command Line Interface (CLI)\nThe interactive medical research CLI (`bmlibrarian_cli.py`) provides:\n- Full 12-step research workflow with enum-based orchestration\n- Human-in-the-loop decision points with auto-mode support\n- Query refinement and threshold adjustment capabilities\n- Counterfactual analysis for comprehensive evidence evaluation\n- Enhanced markdown export with proper citation formatting\n\n### Fact-Checker CLI\nThe fact-checking command-line tool (`fact_checker_cli.py`) provides:\n- **Batch processing** of biomedical statements from JSON files\n- **Literature validation** with AI-powered yes/no/maybe evaluations\n- **SQLite database storage** for persistent results and incremental processing\n- **Evidence extraction** with citation stance indicators and confidence assessment\n- **Incremental mode** - skip already-evaluated statements for efficient processing\n- **Flexible thresholds** - control relevance scoring and citation extraction\n- **Validation support** - compare AI evaluations against expected answers\n- **Detailed output** - comprehensive metadata, statistics, and evidence lists\n\n### Fact-Checker Review GUI\nThe human review desktop application (`fact_checker_review_gui.py`) provides:\n- **Interactive review interface** with statement-by-statement navigation\n- **Blind mode** - hide AI evaluations to prevent annotation bias for unbiased human judgments\n- **Incremental mode** - filter to show only unannotated statements for efficient review\n- **Database integration** - automatic SQLite database creation and intelligent JSON import/merge\n- **Citation inspection** - expandable cards with full abstracts and highlighted passages\n- **Multi-user support** - track annotations by different reviewers with metadata\n- **Comparison view** - see original annotations, AI evaluations, and human annotations side-by-side\n- **Real-time persistence** - all annotations saved immediately to database\n- **Export functionality** - save human-annotated results to JSON for analysis\n- **Quality control** - perfect for training data validation and model evaluation\n\n### Desktop Research Application\nThe GUI research application (`bmlibrarian_research_gui.py`) offers:\n- Native cross-platform desktop interface built with PySide6/Qt\n- Visual workflow progress with collapsible step cards\n- Multi-model query generation with smart pagination and result tracking\n- Progressive counterfactual audit trail with real-time updates\n- PostgreSQL audit trail for persistent session tracking\n- Real-time agent execution with configured AI models\n- Formatted markdown report preview with scrollable display\n- Direct file save functionality\n- Complete transparency into citation validation and rejection reasoning\n\n### Configuration Interface\nThe configuration GUI (`bmlibrarian_config_gui.py`) provides:\n- Tabbed interface for agent-specific configuration\n- Model selection with live refresh from Ollama server\n- Parameter adjustment with interactive sliders and visual value displays\n- **Multi-model query generation configuration tab** for setting up multiple models\n- Connection testing and validation tools\n- Support for configuring query diversity, pagination, and performance tracking\n\n### Laboratory Tools\n- **Paper Reviewer Lab** (`paper_reviewer_lab.py`): Comprehensive paper assessment with 11-step unified workflow (PySide6/Qt)\n- **Paper Checker Lab** (`paper_checker_lab.py`): Interactive medical abstract fact-checking with step-by-step visualization\n- **Paper Weight Lab** (`paper_weight_lab.py`): Evidential weight assessment across five quality dimensions (PySide6/Qt)\n- **PubMed Search Lab** (`pubmed_search_lab.py`): Search PubMed API directly without local database (PySide6/Qt)\n- **QueryAgent Lab** (`query_lab.py`): Experimental interface for natural language to SQL conversion\n- **PICO Lab** (`pico_lab.py`): Interactive PICO component extraction from research papers\n- **PRISMA 2020 Lab** (`prisma2020_lab.py`): Systematic review compliance assessment against 27-item checklist\n- **Transparency Lab** (`transparency_lab.py`): Undisclosed bias risk assessment for research papers\n- **Study Assessment Lab** (`study_assessment_lab.py`): Research quality and trustworthiness evaluation\n- **Citation Lab** (`citation_lab.py`): Citation extraction experimentation\n- **Agent Demonstrations**: Examples showcasing multi-agent capabilities in `examples/` directory\n\n## Configuration System\n\n### Configuration File Locations\nBMLibrarian uses a hierarchical configuration system:\n\n- **Primary**: `~/.bmlibrarian/config.json` (recommended, OS agnostic)\n- **Legacy fallback**: `bmlibrarian_config.json` in current directory\n- **GUI default**: Always saves to `~/.bmlibrarian/config.json`\n\n### Agent Configuration\nEach agent can be individually configured with:\n- **Model Selection**: Choose from available Ollama models\n- **Temperature**: Control creativity/randomness (0.0-1.0)\n- **Top-P**: Control nucleus sampling (0.0-1.0)\n- **Agent-Specific Settings**: Citation count limits, scoring thresholds, etc.\n\n### Multi-Model Query Generation Configuration\nConfigure query diversity for improved document retrieval:\n- **Multi-Model Enabled**: Toggle feature on/off (default: disabled)\n- **Models**: Select up to 3 different AI models for query generation\n- **Queries Per Model**: Generate 1-3 diverse queries per model\n- **Execution Mode**: Serial execution optimized for local instances\n- **De-duplication**: Automatic query and document de-duplication\n- **User Control**: Option to review and select generated queries before execution\n\nExample configuration:\n```json\n{\n  \"query_generation\": {\n    \"multi_model_enabled\": true,\n    \"models\": [\"medgemma-27b-text-it-Q8_0:latest\", \"gpt-oss:20b\", \"medgemma4B_it_q8:latest\"],\n    \"queries_per_model\": 1,\n    \"execution_mode\": \"serial\",\n    \"deduplicate_results\": true,\n    \"show_all_queries_to_user\": true,\n    \"allow_query_selection\": true\n  }\n}\n```\n\n### Environment Variables\n\n```bash\n# Database Configuration\nPOSTGRES_USER=your_username\nPOSTGRES_PASSWORD=your_password  \nPOSTGRES_HOST=localhost          # Default: localhost\nPOSTGRES_PORT=5432              # Default: 5432\nPOSTGRES_DB=knowledgebase       # Default: knowledgebase\n\n# File System\nPDF_BASE_DIR=~/knowledgebase/pdf # Base directory for PDF files\n\n# AI/LLM Configuration  \nOLLAMA_BASE_URL=http://localhost:11434  # Ollama server URL\n```\n\n### Using .env Files\n\nCreate a `.env` file in your project directory:\n```env\n# Database settings\nPOSTGRES_USER=bmlib_user\nPOSTGRES_PASSWORD=secure_password\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=5432\nPOSTGRES_DB=knowledgebase\n\n# AI settings\nOLLAMA_BASE_URL=http://localhost:11434\nPDF_BASE_DIR=~/knowledgebase/pdf\n```\n\n### Default AI Models\n- **Complex Tasks**: `gpt-oss:20b` (comprehensive analysis, report generation)\n- **Fast Processing**: `medgemma4B_it_q8:latest` (quick scoring, classification)\n- **Multi-Model Query Generation**: Combine multiple models for query diversity:\n  - `medgemma-27b-text-it-Q8_0:latest` (medical domain specialist)\n  - `gpt-oss:20b` (general purpose with strong reasoning)\n  - `medgemma4B_it_q8:latest` (fast queries with medical focus)\n\n## Documentation\n\nComprehensive documentation is available in the `doc/` directory:\n\n### User Guides\n- **[Getting Started](doc/users/getting_started.md)** - Quick start guide and installation\n- **[Configuration Guide](doc/users/configuration_guide.md)** - System configuration and settings\n- **[CLI Guide](doc/users/cli_guide.md)** - Command-line interface usage\n- **[Research GUI Guide](doc/users/research_gui_guide.md)** - Desktop research application\n- **[Config GUI Guide](doc/users/config_gui_guide.md)** - Configuration interface\n- **[Paper Reviewer Lab Guide](doc/users/paper_reviewer_lab_guide.md)** - Comprehensive paper assessment\n- **[Fact Checker Guide](doc/users/fact_checker_guide.md)** - LLM training data auditing and statement verification\n- **[Fact Checker Review Guide](doc/users/fact_checker_review_guide.md)** - Human annotation and review GUI\n- **[Paper Checker Guide](doc/users/paper_checker_guide.md)** - Medical abstract fact-checking\n- **[Paper Weight Lab Guide](doc/users/paper_weight_lab_guide.md)** - Evidential weight assessment\n- **[PICO Agent Guide](doc/users/pico_agent_guide.md)** - PICO component extraction for systematic reviews\n- **[PRISMA 2020 Guide](doc/users/prisma2020_guide.md)** - Systematic review compliance assessment\n- **[Study Assessment Guide](doc/users/study_assessment_guide.md)** - Research quality evaluation\n- **[Transparency Assessment Guide](doc/users/transparency_assessment_guide.md)** - Undisclosed bias risk detection\n- **[Document Interrogation Guide](doc/users/document_interrogation_guide.md)** - Interactive document Q\u0026A\n- **[Full-Text Discovery Guide](doc/users/full_text_discovery_guide.md)** - PDF discovery and download\n- **[PDF Export Guide](doc/users/pdf_export_guide.md)** - Markdown to PDF export\n- **[Query Agent Guide](doc/users/query_agent_guide.md)** - Natural language query processing\n- **[Multi-Model Query Guide](doc/users/multi_model_query_guide.md)** - Multi-model query generation\n- **[Citation Guide](doc/users/citation_guide.md)** - Citation extraction and formatting\n- **[Reporting Guide](doc/users/reporting_guide.md)** - Report generation and export\n- **[Counterfactual Guide](doc/users/counterfactual_guide.md)** - Contradictory evidence analysis\n- **[Systematic Review Guide](doc/users/systematic_review_guide.md)** - Systematic literature review workflow\n- **[Audit Validation Guide](doc/users/audit_validation_guide.md)** - Human validation of audit trail items\n- **[Writing Plugin Guide](doc/users/writing_plugin_guide.md)** - Citation-aware markdown editor\n- **[Settings Migration Guide](doc/users/settings_migration_guide.md)** - Database-backed settings migration\n- **[OpenAthens Guide](doc/users/openathens_guide.md)** - Institutional proxy authentication\n- **[MedRxiv Import Guide](doc/users/medrxiv_import_guide.md)** - MedRxiv preprint import\n- **[Document Embedding Guide](doc/users/document_embedding_guide.md)** - Document embedding generation\n- **[Workflow Guide](doc/users/workflow_guide.md)** - Workflow orchestration system\n- **[Troubleshooting](doc/users/troubleshooting.md)** - Common issues and solutions\n\n### Developer Documentation\n- **[Agent Module](doc/developers/agent_module.md)** - Multi-agent system architecture\n- **[Citation System](doc/developers/citation_system.md)** - Citation processing internals\n- **[Reporting System](doc/developers/reporting_system.md)** - Report generation system\n- **[Counterfactual System](doc/developers/counterfactual_system.md)** - Evidence analysis framework\n- **[Fact Checker System](doc/developers/fact_checker_system.md)** - Fact-checking architecture and internals\n- **[Paper Checker Architecture](doc/developers/paper_checker_architecture.md)** - PaperChecker system design\n- **[PICO Agent](doc/developers/pico_agent.md)** - PICO extraction system internals\n- **[PRISMA 2020 System](doc/developers/prisma2020_system.md)** - PRISMA compliance assessment system\n- **[Study Assessment System](doc/developers/study_assessment_system.md)** - Research quality evaluation system\n- **[Transparency Assessment System](doc/developers/transparency_assessment_system.md)** - Bias risk detection architecture\n- **[Full-Text Discovery System](doc/developers/full_text_discovery_system.md)** - PDF discovery architecture\n- **[Document Card Factory](doc/developers/document_card_factory_system.md)** - GUI document card system\n- **[Multi-Model Architecture](doc/developers/multi_model_architecture.md)** - Multi-model query generation\n- **[Audit Validation System](doc/developers/audit_validation_system.md)** - Human validation architecture\n- **[Writing System](doc/developers/writing_system.md)** - Citation-aware editor internals\n\n## Development\n\n### Development Environment Setup\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/hherb/bmlibrarian.git\ncd bmlibrarian\n```\n\n2. **Install dependencies using uv (recommended):**\n```bash\nuv sync\n```\n\n3. **Set up environment:**\n```bash\n# Copy example environment file\ncp .env.example .env\n# Edit .env with your database and Ollama settings\n```\n\n4. **Start required services:**\n```bash\n# Start Ollama service for AI inference\nollama serve\n\n# Ensure PostgreSQL is running with pgvector\npsql -c \"CREATE EXTENSION IF NOT EXISTS vector;\"\n```\n\n5. **Database migrations run automatically:**\n```bash\n# No manual migration required! The system automatically:\n# - Detects your database schema version\n# - Applies any pending migrations on first startup\n# - Creates audit trail tables for research tracking\n# - Tracks migration history for safe upgrades\n```\n\n### Testing\n\nBMLibrarian includes comprehensive testing for all agents and workflow components:\n\n```bash\n# Run all tests with coverage\nuv run python -m pytest tests/ --cov=src/bmlibrarian\n\n# Test specific components\nuv run python -m pytest tests/test_query_agent.py\nuv run python -m pytest tests/test_scoring_agent.py\nuv run python -m pytest tests/test_citation_agent.py\nuv run python -m pytest tests/test_reporting_agent.py\nuv run python -m pytest tests/test_counterfactual_agent.py\n\n# Run integration tests (requires database)\nuv run python -m pytest tests/ -m integration\n\n# Test CLI and GUI applications\nuv run python bmlibrarian_cli.py --quick\nuv run python bmlibrarian_research_gui.py --auto \"test question\" --quick\nuv run python bmlibrarian_config_gui.py --debug\n```\n\nTest suite: **145 test files** across all modules\n\n### Development Commands\n\n```bash\n# Run agent demonstrations\nuv run python examples/agent_demo.py\nuv run python examples/citation_demo.py  \nuv run python examples/reporting_demo.py\nuv run python examples/counterfactual_demo.py\n\n# Launch laboratory tools\nuv run python query_lab.py  # QueryAgent experimental interface\n\n# Run applications in development mode\nuv run python bmlibrarian_cli.py --debug\nuv run python bmlibrarian_research_gui.py --debug\nuv run python bmlibrarian_config_gui.py --debug\n```\n\n### Development Principles\n\n- **Modern Python Standards**: Uses Python ≥3.12 with type hints and pyproject.toml\n- **Enum-Based Architecture**: Flexible workflow orchestration with meaningful step names\n- **Comprehensive Testing**: Unit tests for all agents with realistic test data\n- **Documentation First**: Both user guides and developer documentation for all features\n- **AI-Powered**: Local LLM integration via Ollama for privacy-preserving processing\n- **Scalable Architecture**: Queue-based processing for memory-efficient large-scale operations\n- **Database-First Design**: PostgreSQL audit trail for complete research workflow tracking\n- **Performance Monitoring**: Built-in query performance tracking and optimization insights\n- **Zero-Configuration Migrations**: Automatic database schema updates on startup\n\n### Code Quality Standards\n\n- **BaseAgent Pattern**: All agents inherit from BaseAgent with standardized interfaces\n- **Configuration Integration**: Agents use `get_model()` and `get_agent_config()` from config system\n- **Document ID Integrity**: Always use real database IDs, never mock/fabricated references\n- **Workflow Integration**: Agents support enum-based workflow system execution\n- **No Artificial Limits**: Process ALL documents unless explicitly configured otherwise\n\n## Security \u0026 Best Practices\n\n- **Credentials**: Never hardcode passwords; use environment variables and .env files\n- **Local AI Processing**: Uses local Ollama service to keep research data private\n- **Database Safety**: Never modify production database \"knowledgebase\" without permission\n- **Data Integrity**: All document IDs are programmatically verified to prevent hallucination\n- **Input Validation**: All user inputs and LLM outputs are validated and sanitized\n- **Error Handling**: Robust error recovery and logging throughout the system\n\n## Contributing\n\nWe welcome contributions to BMLibrarian! Areas for contribution include:\n\n### Agent Development\n- New specialized agents for literature analysis tasks\n- Enhanced natural language processing capabilities\n- Improved evidence synthesis and reporting algorithms\n\n### Workflow Enhancement  \n- Additional workflow steps for specialized research domains\n- Enhanced iterative capabilities and human-in-the-loop features\n- Integration with external biomedical databases and APIs\n\n### User Experience\n- GUI improvements and new interface features\n- Enhanced visualization of research workflow progress\n- Mobile and web-based interface development\n\n### Documentation \u0026 Testing\n- Expanded user guides and tutorials\n- Additional agent demonstrations and examples\n- Performance testing and optimization\n\n## Project Status \u0026 Maturity\n\nBMLibrarian is a **production-ready** system with:\n\n- **15+ Specialized AI Agents**: Full multi-agent architecture with sophisticated coordination\n- **Systematic Review Automation**: Checkpoint-based reviews with Cochrane/GRADE assessment\n- **Comprehensive Workflow System**: 12-step research process with iterative capabilities\n- **Robust Infrastructure**: Queue orchestration, error handling, semantic chunking, and progress tracking\n- **26 CLI/GUI Applications**: Research, configuration, fact-checking, systematic review, import tools\n- **16 GUI Plugins**: Modular PySide6/Qt plugin architecture\n- **134 Test Files**: Comprehensive test coverage across all modules\n- **272 Documentation Files**: User guides and developer documentation for every component\n- **Privacy-First**: All AI processing runs locally via Ollama\n\n## License\n\n[License information to be added]\n\n## Support \u0026 Community\n\n- **Documentation**: Comprehensive guides available in the [doc/](doc/) directory\n- **Issues**: Report bugs and feature requests via GitHub issues  \n- **Discussions**: Join our community discussions for questions and collaboration\n- **Examples**: Review demonstration scripts in the [examples/](examples/) directory\n\n## Acknowledgments\n\nBMLibrarian builds upon the power of:\n- **PostgreSQL + pgvector**: High-performance semantic search capabilities\n- **Ollama**: Local, privacy-preserving language model inference\n- **PySide6/Qt**: Cross-platform native desktop GUI framework\n- **ReportLab**: Professional PDF generation (BSD license)\n- **Playwright**: Browser automation for PDF discovery and OpenAthens authentication\n- **Python Ecosystem**: Modern Python \u003e=3.12 with comprehensive typing support\n\n---\n\n*BMLibrarian: The Biomedical Researcher's AI Workbench—evidence-based answers, peer-review quality assessment, and systematic fact-checking, all running locally on your hardware.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhherb%2Fbmlibrarian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhherb%2Fbmlibrarian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhherb%2Fbmlibrarian/lists"}