Skip to content

Developer Manual

Welcome to the BM Librarian Developer Manual. This guide covers the architecture, APIs, and contribution guidelines for developers working with or extending BMLibrarian.

Documentation Index

Document Description
Architecture System architecture and design principles
Agent Architecture Multi-agent AI system design
API Reference Core APIs and module interfaces
Contributing Contribution guidelines and workflow

Project Structure

bmlibrarian/
├── src/bmlibrarian/
│   ├── agents/           # AI agent implementations
│   │   ├── base.py       # BaseAgent abstract class
│   │   ├── query_agent.py
│   │   ├── scoring_agent.py
│   │   ├── citation_agent.py
│   │   ├── reporting_agent.py
│   │   └── counterfactual_agent.py
│   ├── database/         # Database models and queries
│   ├── discovery/        # Document discovery and retrieval
│   ├── gui/              # User interfaces (Qt)
│   │   └── qt/
│   │       └── plugins/  # Tab plugins
│   ├── indexing/         # Document indexing pipelines
│   └── utils/            # Shared utilities
├── tests/                # Test suite
├── doc/                  # Documentation source
└── examples/             # Usage examples

Agent System Overview

Agent Responsibility
QueryAgent Natural language to database query conversion
DocumentScoringAgent Relevance scoring (1-5 scale)
CitationFinderAgent Passage extraction from documents
ReportingAgent Report synthesis with citations
CounterfactualAgent Contradictory evidence identification
EditorAgent Balanced report generation
FactCheckerAgent Statement evaluation
PaperCheckerAgent Abstract validation

Key Technologies

Technology Purpose
Python 3.12+ Core language
PostgreSQL Primary database
pgvector Vector similarity search
Ollama Local LLM inference
PySide6 Qt GUI framework
psycopg PostgreSQL adapter

Development Setup

Prerequisites

  • Python 3.12 or higher
  • PostgreSQL 12+ with pgvector extension
  • Ollama for local LLM inference
  • Git for version control
  • uv package manager (recommended)

Quick Start

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

# Install dependencies
uv sync

# Or with pip
pip install -e .[dev]

# Run tests
uv run pytest tests/

# Start development server
uv run python bmlibrarian_qt.py

Getting Started

  1. Read the Architecture document for system overview
  2. Understand the Agent Architecture for AI components
  3. Review the API Reference for interfaces
  4. Follow Contributing guidelines for contributions

Support