bmlibrarian-lite 0.1.0__py3-none-any.whl

bmlibrarian_lite/__init__.py

@@ -0,0 +1,83 @@
+"""
+BMLibrarian Lite - Lightweight biomedical literature research tool.
+
+A simplified interface for:
+- Systematic literature review (search, score, extract, report)
+- Document interrogation (Q&A with loaded documents)
+
+Features:
+- ChromaDB for vector storage (embedded, no PostgreSQL)
+- SQLite for metadata (embedded)
+- FastEmbed for local embeddings (CPU-optimized, no PyTorch)
+- Anthropic Claude or Ollama for LLM inference
+- NCBI E-utilities for PubMed search (online)
+
+No PostgreSQL required.
+"""
+
+from .config import LiteConfig
+from .storage import LiteStorage
+from .embeddings import LiteEmbedder
+from .data_models import (
+    LiteDocument,
+    LiteChunk,
+    SearchSession,
+    ReviewCheckpoint,
+    ScoredDocument,
+    Citation,
+    InterrogationSession,
+)
+from .exceptions import (
+    LiteError,
+    ConfigurationError,
+    LiteStorageError,
+    EmbeddingError,
+    LLMError,
+)
+from .pdf_discovery import PDFDiscoverer, PDFSource, DiscoveryResult, close_browser_session
+
+__version__ = "0.1.0"
+
+
+def main() -> int:
+    """
+    Main entry point for BMLibrarian Lite.
+
+    This is a convenience wrapper that imports and calls the main function
+    from the CLI module.
+
+    Returns:
+        Application exit code
+    """
+    from .cli import main as cli_main
+    return cli_main()
+
+
+__all__ = [
+    # Configuration
+    "LiteConfig",
+    # Storage
+    "LiteStorage",
+    "LiteEmbedder",
+    # Data models
+    "LiteDocument",
+    "LiteChunk",
+    "SearchSession",
+    "ReviewCheckpoint",
+    "ScoredDocument",
+    "Citation",
+    "InterrogationSession",
+    # PDF Discovery
+    "PDFDiscoverer",
+    "PDFSource",
+    "DiscoveryResult",
+    "close_browser_session",
+    # Exceptions
+    "LiteError",
+    "ConfigurationError",
+    "LiteStorageError",
+    "EmbeddingError",
+    "LLMError",
+    # Version
+    "__version__",
+]

bmlibrarian_lite/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running as python -m bmlibrarian_lite."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bmlibrarian_lite/agents/__init__.py

@@ -0,0 +1,57 @@
+"""
+Lite agents for BMLibrarian Lite.
+
+This module provides simplified, stateless agents that work without PostgreSQL,
+using ChromaDB and SQLite for persistence and online LLM providers for inference.
+
+Agents:
+    LiteBaseAgent: Base class with LLM communication
+    LiteSearchAgent: PubMed search and caching
+    LiteScoringAgent: Document relevance scoring
+    LiteCitationAgent: Citation extraction
+    LiteReportingAgent: Report generation
+    LiteInterrogationAgent: Document Q&A
+
+Usage:
+    from bmlibrarian_lite.agents import (
+        LiteSearchAgent,
+        LiteScoringAgent,
+        LiteCitationAgent,
+        LiteReportingAgent,
+        LiteInterrogationAgent,
+    )
+
+    # Create agents with shared config
+    from bmlibrarian_lite import LiteConfig, LiteStorage
+
+    config = LiteConfig.load()
+    storage = LiteStorage(config)
+
+    search_agent = LiteSearchAgent(storage=storage, config=config)
+    scoring_agent = LiteScoringAgent(config=config)
+    citation_agent = LiteCitationAgent(config=config)
+    reporting_agent = LiteReportingAgent(config=config)
+    interrogation_agent = LiteInterrogationAgent(storage=storage, config=config)
+
+    # Execute a research workflow
+    session, documents = search_agent.search("cardiovascular effects of exercise")
+    scored = scoring_agent.score_documents("cardiovascular effects", documents)
+    citations = citation_agent.extract_all_citations("cardiovascular effects", scored)
+    report = reporting_agent.generate_report("cardiovascular effects", citations)
+"""
+
+from .base import LiteBaseAgent
+from .search_agent import LiteSearchAgent
+from .scoring_agent import LiteScoringAgent
+from .citation_agent import LiteCitationAgent
+from .reporting_agent import LiteReportingAgent
+from .interrogation_agent import LiteInterrogationAgent
+
+__all__ = [
+    "LiteBaseAgent",
+    "LiteSearchAgent",
+    "LiteScoringAgent",
+    "LiteCitationAgent",
+    "LiteReportingAgent",
+    "LiteInterrogationAgent",
+]

bmlibrarian_lite/agents/base.py

@@ -0,0 +1,183 @@
+"""
+Base class for BMLibrarian Lite agents.
+
+Provides common functionality for LLM communication and configuration.
+All Lite agents inherit from this base class to share the unified LLM client
+interface and configuration management.
+"""
+
+import logging
+from typing import Optional
+
+from bmlibrarian_lite.llm import LLMClient, LLMMessage
+from ..config import LiteConfig, TaskModelConfig
+
+logger = logging.getLogger(__name__)
+
+
+class LiteBaseAgent:
+    """
+    Base class for all Lite agents.
+
+    Provides common functionality for LLM communication and configuration.
+    Agents inheriting from this class gain access to:
+    - Configured LLM client with provider selection
+    - Task-based model configuration
+    - Helper methods for creating chat messages
+    - Configuration management
+
+    Subclasses should set TASK_ID to their task identifier for automatic
+    model configuration lookup.
+
+    Attributes:
+        config: Lite configuration instance
+        TASK_ID: Task identifier for model configuration (override in subclass)
+    """
+
+    # Override in subclasses to set the task type for model configuration
+    TASK_ID: str = "default"
+
+    def __init__(
+        self,
+        config: Optional[LiteConfig] = None,
+        llm_client: Optional[LLMClient] = None,
+    ) -> None:
+        """
+        Initialize the base agent.
+
+        Args:
+            config: Lite configuration (uses defaults if not provided)
+            llm_client: Optional pre-configured LLM client
+        """
+        self.config = config or LiteConfig()
+        self._llm_client = llm_client
+
+    @property
+    def llm_client(self) -> LLMClient:
+        """
+        Get or create LLM client.
+
+        The client is lazily created on first access.
+
+        Returns:
+            Configured LLMClient instance
+        """
+        if self._llm_client is None:
+            self._llm_client = LLMClient()
+        return self._llm_client
+
+    def _get_task_config(self, task_id: Optional[str] = None) -> TaskModelConfig:
+        """
+        Get model configuration for a task.
+
+        Args:
+            task_id: Task identifier (uses class TASK_ID if not specified)
+
+        Returns:
+            TaskModelConfig with effective settings for the task
+        """
+        task_id = task_id or self.TASK_ID
+        return self.config.models.get_task_config(task_id)
+
+    def _get_model(self, task_id: Optional[str] = None) -> str:
+        """
+        Get the configured model string for a task.
+
+        Combines provider and model name into the format expected
+        by LLMClient (e.g., "anthropic:claude-3-haiku-20240307").
+
+        Args:
+            task_id: Task identifier (uses class TASK_ID if not specified)
+
+        Returns:
+            Model string with provider prefix
+        """
+        task_id = task_id or self.TASK_ID
+        return self.config.models.get_model_string(task_id)
+
+    def _chat(
+        self,
+        messages: list[LLMMessage],
+        task_id: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False,
+    ) -> str:
+        """
+        Send a chat request to the LLM.
+
+        Uses task-specific configuration if available, otherwise falls back
+        to defaults. Temperature and max_tokens can be overridden per-call.
+
+        Args:
+            messages: List of conversation messages
+            task_id: Task identifier for config lookup (uses class TASK_ID if None)
+            temperature: Optional temperature override
+            max_tokens: Optional max tokens override
+            json_mode: Request JSON-formatted output
+
+        Returns:
+            Response text from the LLM
+        """
+        task_config = self._get_task_config(task_id)
+        response = self.llm_client.chat(
+            messages=messages,
+            model=f"{task_config.provider}:{task_config.model}",
+            temperature=temperature if temperature is not None else task_config.temperature,
+            max_tokens=max_tokens if max_tokens is not None else task_config.max_tokens,
+            top_p=task_config.top_p,
+            json_mode=json_mode,
+        )
+        return response.content
+
+    def _create_system_message(self, content: str) -> LLMMessage:
+        """
+        Create a system message for the LLM.
+
+        Args:
+            content: System prompt content
+
+        Returns:
+            LLMMessage with role="system"
+        """
+        return LLMMessage(role="system", content=content)
+
+    def _create_user_message(self, content: str) -> LLMMessage:
+        """
+        Create a user message for the LLM.
+
+        Args:
+            content: User message content
+
+        Returns:
+            LLMMessage with role="user"
+        """
+        return LLMMessage(role="user", content=content)
+
+    def _create_assistant_message(self, content: str) -> LLMMessage:
+        """
+        Create an assistant message for conversation history.
+
+        Args:
+            content: Assistant message content
+
+        Returns:
+            LLMMessage with role="assistant"
+        """
+        return LLMMessage(role="assistant", content=content)
+
+    def test_connection(self) -> bool:
+        """
+        Test if the LLM provider is available.
+
+        Returns:
+            True if connection is successful
+        """
+        try:
+            # Simple test message
+            messages = [self._create_user_message("Hello")]
+            self._chat(messages, max_tokens=10)
+            return True
+        except Exception as e:
+            logger.warning(f"LLM connection test failed: {e}")
+            return False

bmlibrarian_lite/agents/citation_agent.py

@@ -0,0 +1,247 @@
+"""
+Lite citation extraction agent.
+
+This agent extracts relevant passages from documents that help answer
+a research question. It identifies specific quotes and findings that
+can be used as citations in a research report.
+"""
+
+import json
+import logging
+import re
+from typing import Optional, Callable
+
+from ..data_models import Citation, ScoredDocument
+from .base import LiteBaseAgent
+
+logger = logging.getLogger(__name__)
+
+# System prompt for citation extraction
+CITATION_SYSTEM_PROMPT = """You are a medical research citation extractor. Your task is to identify the most relevant passages from a document that help answer a research question.
+
+Extract 1-3 key passages that:
+1. Directly address the research question
+2. Contain specific findings, data, or conclusions
+3. Are self-contained and understandable out of context
+4. Could be quoted in a research summary
+
+Guidelines:
+- Extract exact quotes from the abstract when possible
+- Focus on passages with specific numbers, percentages, or outcomes
+- Include key conclusions or recommendations
+- Each passage should add unique value
+
+Respond in JSON format:
+{
+    "passages": [
+        {
+            "text": "<exact or close quote from the abstract>",
+            "relevance": "<brief explanation of why this passage is relevant>"
+        }
+    ]
+}"""
+
+
+class LiteCitationAgent(LiteBaseAgent):
+    """
+    Stateless citation extraction agent.
+
+    Extracts relevant passages from documents that answer a research question.
+    These passages can be used as citations in a research report.
+
+    This agent:
+    1. Takes a research question and scored document
+    2. Uses LLM to identify relevant passages
+    3. Returns citations with source attribution
+    """
+
+    TASK_ID = "citation_extraction"
+
+    def extract_citations(
+        self,
+        question: str,
+        scored_doc: ScoredDocument,
+    ) -> list[Citation]:
+        """
+        Extract citations from a scored document.
+
+        Args:
+            question: Research question
+            scored_doc: Document with relevance score
+
+        Returns:
+            List of extracted citations
+        """
+        doc = scored_doc.document
+
+        user_prompt = f"""Research Question: {question}
+
+Document Title: {doc.title}
+Authors: {doc.formatted_authors}
+Year: {doc.year or 'Unknown'}
+Journal: {doc.journal or 'Unknown'}
+Relevance Score: {scored_doc.score}/5
+
+Abstract:
+{doc.abstract}
+
+Extract the most relevant passages that help answer the research question."""
+
+        messages = [
+            self._create_system_message(CITATION_SYSTEM_PROMPT),
+            self._create_user_message(user_prompt),
+        ]
+
+        try:
+            response = self._chat(messages, temperature=0.1, json_mode=True)
+            passages = self._parse_citation_response(response)
+
+            citations = []
+            for passage in passages:
+                citation = Citation(
+                    document=doc,
+                    passage=passage["text"],
+                    relevance_score=scored_doc.score,
+                    context=passage.get("relevance", ""),
+                )
+                citations.append(citation)
+
+            return citations
+
+        except Exception as e:
+            logger.error(f"Failed to extract citations from {doc.id}: {e}")
+            # Return a basic citation using the abstract
+            truncated = doc.abstract[:500] if len(doc.abstract) > 500 else doc.abstract
+            return [Citation(
+                document=doc,
+                passage=truncated,
+                relevance_score=scored_doc.score,
+                context="Full abstract (extraction failed)",
+            )]
+
+    def extract_all_citations(
+        self,
+        question: str,
+        scored_documents: list[ScoredDocument],
+        min_score: int = 3,
+        progress_callback: Optional[Callable[[int, int], None]] = None,
+    ) -> list[Citation]:
+        """
+        Extract citations from all scored documents.
+
+        Args:
+            question: Research question
+            scored_documents: Documents to extract from
+            min_score: Minimum score to process
+            progress_callback: Optional callback(current, total)
+
+        Returns:
+            List of all extracted citations
+        """
+        all_citations = []
+        eligible = [d for d in scored_documents if d.score >= min_score]
+        total = len(eligible)
+
+        logger.info(f"Extracting citations from {total} documents")
+
+        for i, scored_doc in enumerate(eligible):
+            if progress_callback:
+                progress_callback(i + 1, total)
+
+            citations = self.extract_citations(question, scored_doc)
+            all_citations.extend(citations)
+
+            logger.debug(
+                f"Extracted {len(citations)} citations from {scored_doc.document.id}"
+            )
+
+        logger.info(
+            f"Extracted {len(all_citations)} total citations from {total} documents"
+        )
+        return all_citations
+
+    def _parse_citation_response(self, response: str) -> list[dict]:
+        """
+        Parse LLM response to extract passages.
+
+        Args:
+            response: LLM response text
+
+        Returns:
+            List of passage dictionaries
+        """
+        try:
+            # Try to find JSON with passages array
+            # Handle various JSON formats
+            json_match = re.search(
+                r'\{\s*"passages"\s*:\s*\[.*?\]\s*\}',
+                response,
+                re.DOTALL
+            )
+            if json_match:
+                data = json.loads(json_match.group())
+                passages = data.get("passages", [])
+                # Validate passages
+                valid_passages = []
+                for p in passages:
+                    if isinstance(p, dict) and "text" in p:
+                        valid_passages.append(p)
+                return valid_passages
+
+            # Try parsing the entire response as JSON
+            data = json.loads(response)
+            if "passages" in data:
+                return data["passages"]
+
+        except (json.JSONDecodeError, ValueError, TypeError) as e:
+            logger.debug(f"JSON parsing failed: {e}")
+
+        # Fallback: return empty list
+        logger.warning(f"Could not parse citations from: {response[:100]}...")
+        return []
+
+    def group_citations_by_document(
+        self,
+        citations: list[Citation],
+    ) -> dict[str, list[Citation]]:
+        """
+        Group citations by their source document.
+
+        Args:
+            citations: List of citations
+
+        Returns:
+            Dictionary mapping document IDs to their citations
+        """
+        grouped: dict[str, list[Citation]] = {}
+        for citation in citations:
+            doc_id = citation.document.id
+            if doc_id not in grouped:
+                grouped[doc_id] = []
+            grouped[doc_id].append(citation)
+        return grouped
+
+    def deduplicate_citations(
+        self,
+        citations: list[Citation],
+    ) -> list[Citation]:
+        """
+        Remove duplicate citations based on passage text.
+
+        Args:
+            citations: List of citations
+
+        Returns:
+            Deduplicated list of citations
+        """
+        seen_passages: set[str] = set()
+        unique_citations = []
+
+        for citation in citations:
+            # Normalize passage for comparison
+            normalized = citation.passage.strip().lower()
+            if normalized not in seen_passages:
+                seen_passages.add(normalized)
+                unique_citations.append(citation)
+
+        return unique_citations