API Reference¶

BMLibrarian provides APIs for managing database migrations with PostgreSQL and orchestrating AI-powered research workflows.

Core Modules¶

bmlibrarian.migrations¶

Database migration management module.

MigrationManager¶

The primary class for migration management.

from bmlibrarian.migrations import MigrationManager

manager = MigrationManager(
    host: str = "localhost",
    port: int = 5432,
    user: str = None,      # Required
    password: str = None,  # Required
    database: str = None   # Required
)

Methods:

Method	Returns	Description
`initialize_database()`	`None`	Set up database with baseline schema
`apply_pending_migrations()`	`int`	Apply pending migrations, return count
`get_applied_migrations()`	`List[str]`	List of applied migration filenames
`validate_migrations()`	`bool`	Validate migration checksums

Example:

manager = MigrationManager(
    host="localhost",
    port=5432,
    user="username",
    password="password",
    database="knowledgebase"
)

# Initialize new database
manager.initialize_database()

# Apply any pending migrations
count = manager.apply_pending_migrations()
print(f"Applied {count} migrations")

bmlibrarian.app¶

Application-level convenience functions.

initialize_app()¶

Initialize application with automatic migration.

from bmlibrarian.app import initialize_app

initialize_app()

Reads database configuration from environment variables and applies pending migrations.

get_database_connection()¶

Get a configured database connection.

from bmlibrarian.app import get_database_connection

conn = get_database_connection()
with conn.cursor() as cur:
    cur.execute("SELECT COUNT(*) FROM pubmed_articles")
    count = cur.fetchone()[0]

bmlibrarian.cli¶

Command-line interface module.

create_parser()¶

Create argument parser for CLI.

from bmlibrarian.cli import create_parser

parser = create_parser()
args = parser.parse_args()

main()¶

Main entry point for CLI.

from bmlibrarian.cli import main

main()

Agent APIs¶

bmlibrarian.agents¶

AI agent module for research tasks.

BaseAgent¶

Abstract base class for all agents.

from bmlibrarian.agents import BaseAgent

class CustomAgent(BaseAgent):
    def get_agent_type(self) -> str:
        return "custom_agent"

Constructor Parameters:

Parameter	Type	Default	Description
`model`	`str`	`"gpt-oss:20b"`	Ollama model name
`host`	`str`	`"http://localhost:11434"`	Ollama server URL
`temperature`	`float`	`0.1`	Response randomness
`top_p`	`float`	`0.9`	Nucleus sampling
`callback`	`Callable`	`None`	Progress callback

Common Methods:

Method	Returns	Description
`test_connection()`	`bool`	Test Ollama connectivity
`get_available_models()`	`List[str]`	List available models

QueryAgent¶

Natural language to database query conversion.

from bmlibrarian.agents import QueryAgent

agent = QueryAgent(model="gpt-oss:20b")

# Convert question to query
query = agent.convert_question("cardiovascular benefits of exercise")
# Returns: "cardiovascular & (benefit | benefits) & exercise"

# Search with integrated database
for doc in agent.find_abstracts("COVID vaccines", max_results=100):
    print(doc['title'])

DocumentScoringAgent¶

Document relevance scoring.

from bmlibrarian.agents import DocumentScoringAgent

agent = DocumentScoringAgent()

# Score single document
result = agent.evaluate_document(
    question="What causes diabetes?",
    document={"title": "...", "abstract": "..."}
)
# Returns: {"score": 4, "reasoning": "..."}

# Batch scoring
scored = agent.batch_evaluate_documents(
    question="What causes diabetes?",
    documents=documents,
    batch_size=50
)

CitationFinderAgent¶

Citation extraction from documents.

from bmlibrarian.agents import CitationFinderAgent

agent = CitationFinderAgent()

citations = agent.process_scored_documents_for_citations(
    user_question="What causes diabetes?",
    scored_documents=scored_docs,
    relevance_threshold=0.6
)

ReportingAgent¶

Report synthesis from citations.

from bmlibrarian.agents import ReportingAgent

agent = ReportingAgent()

report = agent.synthesize_report(
    question="What causes diabetes?",
    citations=citations
)

# Format for output
formatted = agent.format_report_output(report)

Configuration¶

Environment Variables¶

Required:

Variable	Description
`POSTGRES_USER`	Database username
`POSTGRES_PASSWORD`	Database password

Optional:

Variable	Default	Description
`POSTGRES_HOST`	`"localhost"`	Database host
`POSTGRES_PORT`	`"5432"`	Database port
`POSTGRES_DB`	`"bmlibrarian_dev"`	Database name
`OLLAMA_BASE_URL`	`"http://localhost:11434"`	Ollama server URL

Configuration File¶

Location: ~/.bmlibrarian/config.json

{
  "general": {
    "ollama_base_url": "http://localhost:11434",
    "database_params": {
      "host": "localhost",
      "port": 5432,
      "database": "knowledgebase",
      "user": "username",
      "password": "password"
    }
  },
  "agents": {
    "query_agent": {
      "model": "gpt-oss:20b",
      "temperature": 0.1,
      "top_p": 0.9
    }
  }
}

Error Handling¶

Standard Exceptions¶

Exception	Cause
`ValueError`	Configuration or parameter issues
`FileNotFoundError`	Missing migration or config files
`psycopg.Error`	Database operation failures
`ConnectionError`	Ollama connection issues

Example Error Handling¶

from bmlibrarian.migrations import MigrationManager
import psycopg

try:
    manager = MigrationManager(...)
    manager.apply_pending_migrations()
except ValueError as e:
    print(f"Configuration error: {e}")
except psycopg.Error as e:
    print(f"Database error: {e}")

Performance Notes¶

Best Practices¶

Avoid creating MigrationManager instances repeatedly
Close database connections promptly
Use connection pooling for frequent operations
Large SQL files consume memory when read

Threading¶

Not Thread-Safe

MigrationManager is not thread-safe. Use separate instances for concurrent operations.

Requirements¶

Python: 3.12+
PostgreSQL: 12+
Extensions: pgvector, pg_trgm, uuid-ossp