paperlab 0.1.0__py3-none-any.whl

paperlab/__init__.py

@@ -0,0 +1,9 @@
+"""paperlab — multi-agent LLM tool for critically reading biomedical research papers."""
+
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _v
+
+    __version__ = _v("paperlab")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

paperlab/agents/__init__.py

@@ -0,0 +1,19 @@
+"""paperlab.agents — Agent base class and concrete agents."""
+
+from paperlab.agents.base import Agent, AgentReport
+from paperlab.agents.contextualizer import ContextualizerAgent
+from paperlab.agents.critic import CriticAgent
+from paperlab.agents.methodologist import MethodologistAgent
+from paperlab.agents.summarizer import SummarizerAgent
+
+ALL_AGENTS = [SummarizerAgent, MethodologistAgent, CriticAgent, ContextualizerAgent]
+
+__all__ = [
+    "Agent",
+    "AgentReport",
+    "SummarizerAgent",
+    "MethodologistAgent",
+    "CriticAgent",
+    "ContextualizerAgent",
+    "ALL_AGENTS",
+]

paperlab/agents/base.py

@@ -0,0 +1,82 @@
+"""Base Agent class and AgentReport model."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from paperlab.prompts import load_prompt, render
+from paperlab.providers.base import LLMProvider
+
+
+class AgentReport(BaseModel):
+    agent_name: str
+    mode: str
+    lang: str
+    model: str
+    output: dict
+    raw: str
+    error: str | None = None
+
+
+def _parse_json(raw: str) -> tuple[dict, str | None]:
+    """Try to parse *raw* as JSON.
+
+    First attempt: parse the whole string directly.
+    Second attempt: extract the first ``{...}`` block (greedy, DOTALL) and parse that.
+    Failure: return ``({}, error_message)``.
+    """
+    # Direct parse
+    try:
+        obj = json.loads(raw)
+        if isinstance(obj, dict):
+            return obj, None
+    except json.JSONDecodeError:
+        pass
+
+    # Extract first {...} block
+    match = re.search(r"\{.*\}", raw, re.DOTALL)
+    if match:
+        try:
+            obj = json.loads(match.group())
+            if isinstance(obj, dict):
+                return obj, None
+        except json.JSONDecodeError:
+            pass
+
+    return {}, "JSON parse error: could not extract a JSON object from raw response"
+
+
+class Agent:
+    NAME: ClassVar[str] = ""
+
+    def __init__(
+        self,
+        provider: LLMProvider,
+        mode: str,
+        lang: str,
+        model: str,
+    ) -> None:
+        self._provider = provider
+        self._mode = mode
+        self._lang = lang
+        self._model = model
+
+    async def run(self, paper_text: str) -> AgentReport:
+        name = self.NAME
+        prompt = load_prompt(name, self._mode, self._lang)
+        user = render(prompt["user_template"], paper_text=paper_text)
+        raw = await self._provider.complete(prompt["system"], user, self._model)
+        output, error = _parse_json(raw)
+        return AgentReport(
+            agent_name=name,
+            mode=self._mode,
+            lang=self._lang,
+            model=self._model,
+            output=output,
+            raw=raw,
+            error=error,
+        )

paperlab/agents/contextualizer.py

@@ -0,0 +1,5 @@
+from paperlab.agents.base import Agent
+
+
+class ContextualizerAgent(Agent):
+    NAME = "contextualizer"

paperlab/agents/critic.py

@@ -0,0 +1,5 @@
+from paperlab.agents.base import Agent
+
+
+class CriticAgent(Agent):
+    NAME = "critic"

paperlab/agents/methodologist.py

@@ -0,0 +1,5 @@
+from paperlab.agents.base import Agent
+
+
+class MethodologistAgent(Agent):
+    NAME = "methodologist"

paperlab/agents/summarizer.py

@@ -0,0 +1,5 @@
+from paperlab.agents.base import Agent
+
+
+class SummarizerAgent(Agent):
+    NAME = "summarizer"

paperlab/cli/config.py

@@ -0,0 +1,105 @@
+"""paperlab configuration model and helpers."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+from pydantic import BaseModel, Field
+
+
+class PaperlabConfig(BaseModel):
+    provider: str = "ollama"
+    model: str = "qwen2.5:7b"
+    mode: str = "rigorous"
+    lang: str = "en"
+    extra: dict = Field(default_factory=dict)
+
+
+_TOP_LEVEL_FIELDS: frozenset[str] = frozenset(PaperlabConfig.model_fields)
+
+
+def default_home() -> Path:
+    """Return the paperlab home directory.
+
+    Uses PAPERLAB_HOME environment variable if set, otherwise ~/.paperlab.
+    """
+    home = os.environ.get("PAPERLAB_HOME")
+    if home:
+        return Path(home)
+    return Path.home() / ".paperlab"
+
+
+def default_config_path() -> Path:
+    """Return the default config.toml path."""
+    return default_home() / "config.toml"
+
+
+def load_config(path: Path | None = None) -> PaperlabConfig:
+    """Load configuration from *path*.
+
+    Returns a default ``PaperlabConfig`` if the file does not exist.
+    """
+    path = path or default_config_path()
+    if not path.exists():
+        return PaperlabConfig()
+    with open(path, "rb") as fh:
+        data = tomllib.load(fh)
+    return PaperlabConfig(**data)
+
+
+def save_config(cfg: PaperlabConfig, path: Path | None = None) -> Path:
+    """Write *cfg* to *path* in TOML format. Creates parent directories."""
+    path = path or default_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "wb") as fh:
+        tomli_w.dump(cfg.model_dump(), fh, multiline_strings=True)
+    return path
+
+
+def get_field(cfg: PaperlabConfig, dotted: str) -> Any:
+    """Return a config value by dotted key.
+
+    Supports top-level keys (``provider``, ``model``, ``mode``, ``lang``,
+    ``extra``) and one level of nesting for ``extra`` (e.g. ``extra.foo``).
+
+    Raises
+    ------
+    KeyError
+        If the key is not valid.
+    """
+    parts = dotted.split(".", 1)
+    if parts[0] not in _TOP_LEVEL_FIELDS:
+        raise KeyError(f"Unknown config key: {dotted!r}")
+    if len(parts) == 1:
+        return getattr(cfg, parts[0])
+    if parts[0] != "extra":
+        raise KeyError(f"Nested access only supported for 'extra', not {parts[0]!r}")
+    extra: dict = cfg.extra
+    if parts[1] not in extra:
+        raise KeyError(f"Key not found in extra: {parts[1]!r}")
+    return extra[parts[1]]
+
+
+def set_field(cfg: PaperlabConfig, dotted: str, value: str) -> PaperlabConfig:
+    """Return a new config with *dotted* field set to *value*.
+
+    Raises
+    ------
+    KeyError
+        If the key is not valid.
+    """
+    parts = dotted.split(".", 1)
+    if parts[0] not in _TOP_LEVEL_FIELDS:
+        raise KeyError(f"Unknown config key: {dotted!r}")
+    data = cfg.model_dump()
+    if len(parts) == 1:
+        data[parts[0]] = value
+    else:
+        if parts[0] != "extra":
+            raise KeyError(f"Nested access only supported for 'extra', not {parts[0]!r}")
+        data["extra"][parts[1]] = value
+    return PaperlabConfig(**data)

paperlab/cli/main.py

@@ -0,0 +1,205 @@
+"""paperlab CLI entrypoint."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from paperlab import __version__
+from paperlab.ingest import extract_text
+from paperlab.providers.factory import make_provider
+
+# ---------------------------------------------------------------------------
+# Runtime shim — replace fields in tests to avoid real I/O.
+# ---------------------------------------------------------------------------
+_RUNTIME = SimpleNamespace(
+    extract_text=extract_text,
+    make_provider=make_provider,
+)
+
+# ---------------------------------------------------------------------------
+# Typer apps
+# ---------------------------------------------------------------------------
+app = typer.Typer(
+    name="paperlab",
+    help="Multi-agent LLM tool for critically reading biomedical research papers.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+config_app = typer.Typer(
+    name="config",
+    help="Get or set configuration values.",
+    no_args_is_help=True,
+)
+app.add_typer(config_app, name="config")
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def version() -> None:
+    """Show paperlab version."""
+    typer.echo(f"paperlab {__version__}")
+
+
+@app.command()
+def init(
+    force: bool = typer.Option(False, "--force", help="Overwrite existing config."),
+) -> None:
+    """Create ~/.paperlab with config.toml and sessions/."""
+    from paperlab.cli.config import PaperlabConfig, default_config_path, default_home, save_config
+
+    home = default_home()
+    sessions_dir = home / "sessions"
+    config_path = default_config_path()
+
+    if config_path.exists() and not force:
+        typer.echo(f"Config already exists: {config_path}", err=True)
+        typer.echo("Use --force to overwrite.", err=True)
+        raise typer.Exit(code=1)
+
+    sessions_dir.mkdir(parents=True, exist_ok=True)
+    save_config(PaperlabConfig(), config_path)
+
+    typer.echo(f"home:     {home}")
+    typer.echo(f"sessions: {sessions_dir}")
+    typer.echo(f"config:   {config_path}")
+
+
+@app.command()
+def read(
+    paper: Path = typer.Argument(..., help="Path to the PDF file"),
+    mode: str | None = typer.Option(None, help="rigorous | learning"),
+    lang: str | None = typer.Option(None, help="en | ru"),
+    model: str | None = typer.Option(None, help="Override the configured model"),
+    provider: str | None = typer.Option(None, help="Provider name"),
+    format: str = typer.Option("markdown", help="markdown | json"),
+    output: Path | None = typer.Option(None, help="Write report to file"),
+) -> None:
+    """Run the multi-agent review on a paper."""
+    from paperlab.cli.config import load_config
+    from paperlab.orchestrator import review
+    from paperlab.sessions import save_report, to_json, to_markdown
+
+    cfg = load_config()
+    effective_mode = mode or cfg.mode
+    effective_lang = lang or cfg.lang
+    effective_model = model or cfg.model
+    effective_provider = provider or cfg.provider
+
+    provider_instance = _RUNTIME.make_provider(effective_provider)
+    paper_obj = _RUNTIME.extract_text(paper)
+
+    report = asyncio.run(
+        review(paper_obj, provider_instance, effective_mode, effective_lang, effective_model)
+    )
+    save_report(report)
+
+    content = to_json(report) if format == "json" else to_markdown(report)
+    print(content)
+
+    if output:
+        output.write_text(content, encoding="utf-8")
+
+    print(f"session: {report.session_id}")
+
+
+@app.command(name="list")
+def list_sessions_cmd() -> None:
+    """List past review sessions."""
+    from paperlab.sessions import list_sessions
+
+    sessions = list_sessions()
+    if not sessions:
+        typer.echo("No sessions found.")
+        raise typer.Exit(code=0)
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("session_id")
+    table.add_column("created_at")
+    table.add_column("mode")
+    table.add_column("lang")
+    table.add_column("model")
+    for s in sessions:
+        table.add_row(s.session_id, s.created_at, s.mode, s.lang, s.model)
+    console.print(table)
+
+
+@app.command()
+def show(
+    session_id: str = typer.Argument(..., help="Session ID to display"),
+    format: str = typer.Option("markdown", help="markdown | json"),
+) -> None:
+    """Show a past review session."""
+    from paperlab.sessions import load_report, to_json, to_markdown
+
+    report = load_report(session_id)
+    print(to_json(report) if format == "json" else to_markdown(report))
+
+
+@app.command()
+def web() -> None:
+    """Launch the local Gradio web dashboard."""
+    try:
+        from paperlab.web import launch
+    except ImportError as exc:
+        typer.echo(
+            f"Could not import paperlab.web: {exc}\n"
+            "Install the web extras: pip install paperlab[web]",
+            err=True,
+        )
+        raise typer.Exit(code=1) from None
+    launch()
+
+
+# ---------------------------------------------------------------------------
+# config sub-commands
+# ---------------------------------------------------------------------------
+
+
+@config_app.command(name="get")
+def config_get(
+    key: str = typer.Argument(..., help="Config key (e.g. provider, model, extra.foo)"),
+) -> None:
+    """Print the value of a config key."""
+    from paperlab.cli.config import get_field, load_config
+
+    cfg = load_config()
+    try:
+        value = get_field(cfg, key)
+    except KeyError:
+        typer.echo(f"Unknown key: {key}", err=True)
+        raise typer.Exit(code=1) from None
+    typer.echo(value)
+
+
+@config_app.command(name="set")
+def config_set(
+    key: str = typer.Argument(..., help="Config key"),
+    value: str = typer.Argument(..., help="New value"),
+) -> None:
+    """Set a config key to a new value."""
+    from paperlab.cli.config import load_config, save_config, set_field
+
+    cfg = load_config()
+    try:
+        cfg = set_field(cfg, key, value)
+    except KeyError:
+        typer.echo(f"Unknown key: {key}", err=True)
+        raise typer.Exit(code=1) from None
+    save_config(cfg)
+    typer.echo(f"{key} = {value}")
+
+
+if __name__ == "__main__":
+    app()

paperlab/ingest/__init__.py

@@ -0,0 +1,5 @@
+"""paperlab.ingest — PDF ingestion utilities."""
+
+from paperlab.ingest.pdf import IngestedPaper, IngestError, extract_text
+
+__all__ = ["extract_text", "IngestedPaper", "IngestError"]

paperlab/ingest/pdf.py

@@ -0,0 +1,70 @@
+"""PDF text extraction for paperlab."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+class IngestError(Exception):
+    """Raised when PDF conversion fails."""
+
+
+class IngestedPaper(BaseModel):
+    source_path: str
+    title: str | None = None
+    text: str
+    num_pages: int | None = None
+    backend: str
+
+
+def extract_text(path: Path | str, converter=None) -> IngestedPaper:
+    """Extract text from a PDF file.
+
+    Parameters
+    ----------
+    path:
+        Path to the PDF file.
+    converter:
+        Optional docling DocumentConverter instance. Created lazily if None.
+
+    Returns
+    -------
+    IngestedPaper
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"PDF file not found: {path}")
+
+    if path.suffix.lower() != ".pdf":
+        raise ValueError(f"Expected a .pdf file, got: {path.suffix!r} ({path})")
+
+    if converter is None:
+        from docling.document_converter import DocumentConverter  # lazy import
+
+        converter = DocumentConverter()
+
+    try:
+        result = converter.convert(str(path))
+    except Exception as exc:
+        raise IngestError(f"Failed to convert {path}: {exc}") from exc
+
+    text = result.document.export_to_markdown()
+
+    num_pages: int | None = None
+    if hasattr(result, "pages"):
+        num_pages = len(result.pages)
+
+    title: str | None = None
+    if hasattr(result.document, "title"):
+        title = result.document.title
+
+    return IngestedPaper(
+        source_path=str(path),
+        title=title,
+        text=text,
+        num_pages=num_pages,
+        backend="docling",
+    )

paperlab/orchestrator/__init__.py

@@ -0,0 +1,5 @@
+"""paperlab.orchestrator — parallel review orchestration."""
+
+from paperlab.orchestrator.runner import ReviewReport, review
+
+__all__ = ["review", "ReviewReport"]

paperlab/orchestrator/runner.py

@@ -0,0 +1,67 @@
+"""paperlab.orchestrator.runner — parallel review runner."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from paperlab.agents import ALL_AGENTS, AgentReport
+from paperlab.ingest import IngestedPaper
+from paperlab.providers.base import LLMProvider
+
+
+class ReviewReport(BaseModel):
+    paper: IngestedPaper
+    mode: str
+    lang: str
+    model: str
+    session_id: str
+    created_at: str  # ISO 8601 UTC
+    agents: dict[str, AgentReport]
+
+
+async def review(
+    paper: IngestedPaper,
+    provider: LLMProvider,
+    mode: str,
+    lang: str,
+    model: str,
+    session_id: str | None = None,
+) -> ReviewReport:
+    session_id = session_id or uuid.uuid4().hex[:12]
+    created_at = datetime.now(UTC).isoformat()
+
+    agent_instances = [cls(provider, mode, lang, model) for cls in ALL_AGENTS]
+
+    results = await asyncio.gather(
+        *[agent.run(paper.text) for agent in agent_instances],
+        return_exceptions=True,
+    )
+
+    agents: dict[str, AgentReport] = {}
+    for agent, result in zip(agent_instances, results, strict=False):
+        if isinstance(result, Exception):
+            agents[agent.NAME] = AgentReport(
+                agent_name=agent.NAME,
+                mode=mode,
+                lang=lang,
+                model=model,
+                output={},
+                raw="",
+                error=str(result),
+            )
+        else:
+            agents[agent.NAME] = result
+
+    return ReviewReport(
+        paper=paper,
+        mode=mode,
+        lang=lang,
+        model=model,
+        session_id=session_id,
+        created_at=created_at,
+        agents=agents,
+    )

paperlab/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Prompt loading for paperlab agents."""
+
+from paperlab.prompts.loader import load_prompt, render
+
+__all__ = ["load_prompt", "render"]

paperlab/prompts/contextualizer.yaml

@@ -0,0 +1,63 @@
+en:
+  rigorous:
+    system: >
+      You are an expert in mapping scientific papers to their research landscape.
+      Determine where this paper sits within its field based solely on what the authors state,
+      identify related work they explicitly cite or compare against, and assess the novelty claims
+      the authors make without adding external knowledge.
+      Be precise and cite specific passages where possible.
+    user_template: |
+      Paper text:
+      {paper_text}
+
+      Return a JSON object with fields:
+      - field_position: string describing where this paper positions itself within its research field
+      - related_work: list of prior works or comparators the authors explicitly mention
+      - novelty: list of novelty claims the authors make for their contribution
+
+  learning:
+    system: >
+      You are a research context tutor helping a student understand where a paper fits in the literature.
+      Explain in accessible terms how the authors describe their field, what prior work they compare to,
+      and what they claim is new about their contribution.
+      Draw only from the text of the paper itself.
+    user_template: |
+      Paper text:
+      {paper_text}
+
+      Return a JSON object with fields:
+      - field_position: plain-language description of where this paper places itself in its field
+      - related_work: list of prior works or comparators the authors mention
+      - novelty: list of what the authors claim is new or different about their work
+
+ru:
+  rigorous:
+    system: >
+      Вы — эксперт по позиционированию научных работ в исследовательском ландшафте.
+      Определяйте место статьи в её области, опираясь исключительно на то, что утверждают авторы;
+      выявляйте работы, которые они явно цитируют или с которыми сравниваются;
+      оценивайте заявленную новизну без привлечения внешних знаний.
+      Будьте точны и по возможности ссылайтесь на конкретные фрагменты текста.
+    user_template: |
+      Текст статьи:
+      {paper_text}
+
+      Верните JSON-объект с полями:
+      - field_position: строка, описывающая, как авторы позиционируют работу в своей области
+      - related_work: список предшествующих работ или объектов сравнения, явно упомянутых авторами
+      - novelty: список заявленных авторами новшеств их вклада
+
+  learning:
+    system: >
+      Вы — наставник по научному контексту, помогающий студенту понять, какое место статья занимает в литературе.
+      Доступным языком объясните, как авторы описывают своё поле, с какими предшествующими работами сравниваются
+      и что именно они считают новым в своём вкладе.
+      Опирайтесь только на текст самой статьи.
+    user_template: |
+      Текст статьи:
+      {paper_text}
+
+      Верните JSON-объект с полями:
+      - field_position: описание простым языком того, как авторы позиционируют работу в своей области
+      - related_work: список предшествующих работ или объектов сравнения, упомянутых авторами
+      - novelty: список того, что авторы считают новым или отличительным в своей работе