paperlab 0.1.0__tar.gz

paperlab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy src/paperlab || true
+
+      - name: Run tests
+        run: pytest -q

paperlab-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check package metadata
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

paperlab-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+.venv/
+venv/
+env/
+ENV/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+.env
+.env.local
+*.log
+
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# paperlab runtime data (should live in ~/.paperlab, not the repo)
+.paperlab/
+# Ignore top-level sessions/ dir (runtime data), but not src/tests subdirectories
+/sessions/
+*.jsonl.bak
+
+# scratch and experiments
+scratchpad/
+.scratch/

paperlab-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to paperlab
+
+Thanks for wanting to help. This project is built to serve students and researchers reading biomedical papers — practical contributions matter more than theoretical polish.
+
+## How you can help
+
+- **Report bugs** — open an issue with the PDF that broke it (if shareable), your OS, and the exact command.
+- **Improve prompts** — the agents in `src/paperlab/prompts/` are YAML files. Better prompts = better reviews. PRs welcome.
+- **Add a benchmark paper** — `tests/benchmark/` holds papers with expected critiques. More examples = more accurate agents.
+- **Add a domain profile** — biomed is the default, but pharma subfields (oncology, immunology, PK/PD) can have their own critique rubrics.
+- **Improve docs** — especially for non-programmers. Screenshots, videos, translations.
+
+## Development setup
+
+```bash
+git clone https://github.com/zhakhatoff/paperlab
+cd paperlab
+python -m venv .venv
+source .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Code style
+
+- `ruff format` and `ruff check` before commit
+- Type hints on public APIs
+- Tests for anything non-trivial
+
+## Branches and PRs
+
+- `main` is protected
+- Branch names: `feat/`, `fix/`, `docs/`, `chore/`
+- Keep PRs small and focused
+- One approval to merge
+
+## Questions
+
+Open a GitHub Discussion or issue. Russian and English are both fine.

paperlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paperlab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paperlab-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: paperlab
+Version: 0.1.0
+Summary: Multi-agent LLM tool for critically reading biomedical and pharmacology research papers
+Project-URL: Homepage, https://github.com/zhakhatoff/paperlab
+Project-URL: Repository, https://github.com/zhakhatoff/paperlab
+Project-URL: Issues, https://github.com/zhakhatoff/paperlab/issues
+Author: paperlab contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,biomedical,llm,pdf,pharmacology,research,science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: docling>=2.0.0
+Requires-Dist: gradio>=5.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: paper-qa>=5.0.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paperlab
+
+[English](#english) | [Русский](#русский)
+
+---
+
+## English
+
+**paperlab** is an open-source multi-agent LLM tool for critically reading biomedical and pharmacology research papers. Local by default, provider-agnostic, built for students and researchers.
+
+### What it does
+
+You give paperlab a PDF of a research paper. Four AI agents read it in parallel:
+
+- **Summarizer** — what the paper actually claims
+- **Methodologist** — study design, CONSORT/PRISMA/STROBE compliance, reproducibility
+- **Critic** — statistical weaknesses, p-hacking, cherry-picking, conflicts of interest
+- **Contextualizer** — where this fits in the field, related work
+
+You get a structured report in Markdown or JSON. Two modes:
+
+- `rigorous` — strict peer-review style critique for postgrads and researchers
+- `learning` — gentle explanation for undergraduates reading their first papers
+
+Two output languages: English or Russian.
+
+### Install
+
+```bash
+pipx install paperlab
+paperlab init
+```
+
+`paperlab init` creates `~/.paperlab/` with a default `config.toml` and a `sessions/` subdirectory. Run with `--force` to overwrite an existing config.
+
+### Use
+
+```bash
+paperlab read paper.pdf --mode rigorous --lang en
+paperlab read paper.pdf --mode learning --lang ru --provider ollama --model qwen2.5:7b
+paperlab list                    # your review history
+paperlab show <session-id>       # revisit a past review
+paperlab web                     # open the browser dashboard (phase 8)
+```
+
+Output format:
+
+```bash
+paperlab read paper.pdf --format markdown          # default
+paperlab read paper.pdf --format json --output report.json
+```
+
+### Providers
+
+paperlab uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood, so any of these work out of the box:
+
+- `ollama` (local, default, free)
+- `openrouter` (unified access to GPT, Claude, Gemini, Llama, etc.)
+- `together`, `groq`, `gemini`, `anthropic`, `openai`
+- `custom` (any OpenAI-compatible endpoint, e.g. your university's GPU cluster)
+
+Switch with `paperlab config set provider ollama` or pass `--provider` per invocation.
+
+### Config
+
+```bash
+paperlab config get provider          # print current value
+paperlab config set provider openai   # update config.toml
+paperlab config set model gpt-4o
+paperlab config set extra.base_url http://localhost:11434
+```
+
+Config is stored in `~/.paperlab/config.toml` (or `$PAPERLAB_HOME/config.toml`).
+
+### Privacy
+
+Everything runs locally. PDFs never leave your machine unless you explicitly configure a cloud provider. History is stored in `~/.paperlab/sessions/` as JSONL — grep, back up, delete freely.
+
+### Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### License
+
+MIT
+
+---
+
+## Русский
+
+**paperlab** — open source инструмент для критического чтения биомедицинских и фармакологических научных статей с помощью команды ИИ-агентов. Локальный по умолчанию, поддерживает разных провайдеров, сделан для студентов и исследователей.
+
+### Что делает
+
+Вы даёте paperlab PDF научной статьи. Четыре агента читают её параллельно:
+
+- **Summarizer** — что статья реально утверждает
+- **Methodologist** — дизайн исследования, соответствие CONSORT/PRISMA/STROBE, воспроизводимость
+- **Critic** — статистические слабости, p-hacking, cherry-picking, конфликты интересов
+- **Contextualizer** — место в поле, связь с литературой
+
+Получаете структурированный разбор в Markdown или JSON. Два режима:
+
+- `rigorous` — жёсткая критика в стиле peer-review для аспирантов и исследователей
+- `learning` — мягкий разбор для студентов, читающих первые статьи
+
+Два языка вывода: английский или русский.
+
+### Установка
+
+```bash
+pipx install paperlab
+paperlab init
+```
+
+Команда `paperlab init` создаёт `~/.paperlab/` с дефолтным `config.toml` и поддиректорией `sessions/`. Флаг `--force` перезаписывает существующий конфиг.
+
+### Использование
+
+```bash
+paperlab read paper.pdf --mode rigorous --lang ru
+paperlab read paper.pdf --mode learning --lang en --provider ollama --model qwen2.5:7b
+paperlab list                    # история разборов
+paperlab show <session-id>       # открыть прошлый разбор
+paperlab web                     # веб-интерфейс в браузере (фаза 8)
+```
+
+Формат вывода:
+
+```bash
+paperlab read paper.pdf --format markdown          # по умолчанию
+paperlab read paper.pdf --format json --output report.json
+```
+
+### Провайдеры
+
+Работает с любым из этих без изменений в коде:
+
+- `ollama` (локально, по умолчанию, бесплатно)
+- `openrouter` (единый доступ к GPT, Claude, Gemini, Llama и т.д.)
+- `together`, `groq`, `gemini`, `anthropic`, `openai`
+- `custom` (любой OpenAI-совместимый endpoint)
+
+Переключение: `paperlab config set provider ollama` или флаг `--provider` при запуске.
+
+### Конфигурация
+
+```bash
+paperlab config get provider          # показать текущее значение
+paperlab config set provider openai   # обновить config.toml
+paperlab config set model gpt-4o
+paperlab config set extra.base_url http://localhost:11434
+```
+
+Конфиг хранится в `~/.paperlab/config.toml` (или `$PAPERLAB_HOME/config.toml`).
+
+### Приватность
+
+Всё работает локально. PDF не покидает вашу машину, если вы явно не настроили облачного провайдера. История хранится в `~/.paperlab/sessions/` в формате JSONL — можно грепать, бэкапить, удалять.
+
+### Участие в разработке
+
+См. [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Лицензия
+
+MIT

paperlab-0.1.0/README.md

@@ -0,0 +1,167 @@
+# paperlab
+
+[English](#english) | [Русский](#русский)
+
+---
+
+## English
+
+**paperlab** is an open-source multi-agent LLM tool for critically reading biomedical and pharmacology research papers. Local by default, provider-agnostic, built for students and researchers.
+
+### What it does
+
+You give paperlab a PDF of a research paper. Four AI agents read it in parallel:
+
+- **Summarizer** — what the paper actually claims
+- **Methodologist** — study design, CONSORT/PRISMA/STROBE compliance, reproducibility
+- **Critic** — statistical weaknesses, p-hacking, cherry-picking, conflicts of interest
+- **Contextualizer** — where this fits in the field, related work
+
+You get a structured report in Markdown or JSON. Two modes:
+
+- `rigorous` — strict peer-review style critique for postgrads and researchers
+- `learning` — gentle explanation for undergraduates reading their first papers
+
+Two output languages: English or Russian.
+
+### Install
+
+```bash
+pipx install paperlab
+paperlab init
+```
+
+`paperlab init` creates `~/.paperlab/` with a default `config.toml` and a `sessions/` subdirectory. Run with `--force` to overwrite an existing config.
+
+### Use
+
+```bash
+paperlab read paper.pdf --mode rigorous --lang en
+paperlab read paper.pdf --mode learning --lang ru --provider ollama --model qwen2.5:7b
+paperlab list                    # your review history
+paperlab show <session-id>       # revisit a past review
+paperlab web                     # open the browser dashboard (phase 8)
+```
+
+Output format:
+
+```bash
+paperlab read paper.pdf --format markdown          # default
+paperlab read paper.pdf --format json --output report.json
+```
+
+### Providers
+
+paperlab uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood, so any of these work out of the box:
+
+- `ollama` (local, default, free)
+- `openrouter` (unified access to GPT, Claude, Gemini, Llama, etc.)
+- `together`, `groq`, `gemini`, `anthropic`, `openai`
+- `custom` (any OpenAI-compatible endpoint, e.g. your university's GPU cluster)
+
+Switch with `paperlab config set provider ollama` or pass `--provider` per invocation.
+
+### Config
+
+```bash
+paperlab config get provider          # print current value
+paperlab config set provider openai   # update config.toml
+paperlab config set model gpt-4o
+paperlab config set extra.base_url http://localhost:11434
+```
+
+Config is stored in `~/.paperlab/config.toml` (or `$PAPERLAB_HOME/config.toml`).
+
+### Privacy
+
+Everything runs locally. PDFs never leave your machine unless you explicitly configure a cloud provider. History is stored in `~/.paperlab/sessions/` as JSONL — grep, back up, delete freely.
+
+### Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### License
+
+MIT
+
+---
+
+## Русский
+
+**paperlab** — open source инструмент для критического чтения биомедицинских и фармакологических научных статей с помощью команды ИИ-агентов. Локальный по умолчанию, поддерживает разных провайдеров, сделан для студентов и исследователей.
+
+### Что делает
+
+Вы даёте paperlab PDF научной статьи. Четыре агента читают её параллельно:
+
+- **Summarizer** — что статья реально утверждает
+- **Methodologist** — дизайн исследования, соответствие CONSORT/PRISMA/STROBE, воспроизводимость
+- **Critic** — статистические слабости, p-hacking, cherry-picking, конфликты интересов
+- **Contextualizer** — место в поле, связь с литературой
+
+Получаете структурированный разбор в Markdown или JSON. Два режима:
+
+- `rigorous` — жёсткая критика в стиле peer-review для аспирантов и исследователей
+- `learning` — мягкий разбор для студентов, читающих первые статьи
+
+Два языка вывода: английский или русский.
+
+### Установка
+
+```bash
+pipx install paperlab
+paperlab init
+```
+
+Команда `paperlab init` создаёт `~/.paperlab/` с дефолтным `config.toml` и поддиректорией `sessions/`. Флаг `--force` перезаписывает существующий конфиг.
+
+### Использование
+
+```bash
+paperlab read paper.pdf --mode rigorous --lang ru
+paperlab read paper.pdf --mode learning --lang en --provider ollama --model qwen2.5:7b
+paperlab list                    # история разборов
+paperlab show <session-id>       # открыть прошлый разбор
+paperlab web                     # веб-интерфейс в браузере (фаза 8)
+```
+
+Формат вывода:
+
+```bash
+paperlab read paper.pdf --format markdown          # по умолчанию
+paperlab read paper.pdf --format json --output report.json
+```
+
+### Провайдеры
+
+Работает с любым из этих без изменений в коде:
+
+- `ollama` (локально, по умолчанию, бесплатно)
+- `openrouter` (единый доступ к GPT, Claude, Gemini, Llama и т.д.)
+- `together`, `groq`, `gemini`, `anthropic`, `openai`
+- `custom` (любой OpenAI-совместимый endpoint)
+
+Переключение: `paperlab config set provider ollama` или флаг `--provider` при запуске.
+
+### Конфигурация
+
+```bash
+paperlab config get provider          # показать текущее значение
+paperlab config set provider openai   # обновить config.toml
+paperlab config set model gpt-4o
+paperlab config set extra.base_url http://localhost:11434
+```
+
+Конфиг хранится в `~/.paperlab/config.toml` (или `$PAPERLAB_HOME/config.toml`).
+
+### Приватность
+
+Всё работает локально. PDF не покидает вашу машину, если вы явно не настроили облачного провайдера. История хранится в `~/.paperlab/sessions/` в формате JSONL — можно грепать, бэкапить, удалять.
+
+### Участие в разработке
+
+См. [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Лицензия
+
+MIT

paperlab-0.1.0/docs/architecture.md

@@ -0,0 +1,50 @@
+# paperlab architecture
+
+High-level view of how the pieces fit together.
+
+## Data flow
+
+```
+PDF file
+  │
+  ▼
+[ingest]  docling → structured Document (+ optional GROBID for references)
+  │
+  ▼
+[orchestrator]  LangGraph DAG
+  │
+  ├── Summarizer      ──┐
+  ├── Methodologist   ──┤
+  ├── Critic          ──┼──► Merge
+  └── Contextualizer  ──┘        (paper-qa retrieval for citations)
+  │
+  ▼
+Report (Markdown + JSON)  →  ~/.paperlab/sessions/<id>.jsonl
+```
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `ingest/` | PDF → structured Document via docling; optional GROBID sidecar |
+| `agents/` | Prompt loading, per-agent LLM calls, output schemas |
+| `orchestrator/` | LangGraph state machine, token budgeting, streaming |
+| `providers/` | LiteLLM wrapper: Ollama / OpenRouter / Together / Gemini / Anthropic / custom |
+| `cli/` | Typer commands: init, config, read, list, show, web |
+| `web/` | Gradio dashboard, reuses core modules |
+| `prompts/` | YAML files: 4 agents × 2 modes × 2 languages |
+
+## Key design decisions
+
+- **Local by default.** Ollama is the default provider so anything works offline and free.
+- **One LLM abstraction.** LiteLLM handles all providers — no bespoke wrappers.
+- **Prompts as data.** YAML in `prompts/` so users and contributors can iterate without touching Python.
+- **JSONL session log.** Same pattern as codbash — grep-friendly, easy to back up.
+- **CLI and web share the core.** `paperlab read` and `paperlab web` both call the same orchestrator.
+
+## Non-goals for 0.1.0
+
+- Uploading data to a cloud service
+- Training or fine-tuning models
+- Non-biomedical domains (comes later via profile system)
+- Non-PDF inputs (comes later)

paperlab-0.1.0/docs/user-research.md

@@ -0,0 +1,43 @@
+# User research — Week 1 interviews
+
+Target: 5 postgraduate students or researchers in biomedicine, pharmacology, biochemistry, or molecular biology who read papers regularly.
+
+## Interview script
+
+Introduce paperlab in one sentence, then ask:
+
+### Current workflow
+
+1. How do you decide which papers to read this week? What's your source (PubMed alert, journal RSS, supervisor, Twitter)?
+2. Walk me through the last paper you read. How long did it take? What did you skim vs read carefully?
+3. What tools do you use? (Zotero, Mendeley, Notion, plain PDF reader, ChatGPT, NotebookLM, Elicit, SciSpace?)
+4. What frustrates you about reading papers?
+
+### Critique needs
+
+5. When you review a paper, what do you check for in methodology? Do you follow any checklist (CONSORT, PRISMA, STROBE)?
+6. Have you ever missed a methodological problem in a paper and only caught it later?
+7. Would you trust an AI to point out weaknesses in a paper? Under what conditions?
+
+### paperlab specific
+
+8. Two modes — rigorous (peer-review style) vs learning (gentle explanation). Which would you use?
+9. Would you run a tool locally on your laptop, or do you prefer a web app?
+10. Do you have a GPU? Would 3–5 minutes per paper on CPU be acceptable?
+11. If it's free, open source, and runs locally — would you install it? What would stop you?
+
+### Willingness
+
+12. Would you try a beta version in month 2? Would you introduce it to your lab?
+
+## Notes template
+
+For each interviewee:
+
+- **Name / role / field:**
+- **Current workflow:**
+- **Biggest frustration:**
+- **Would use rigorous / learning / both:**
+- **Local vs cloud preference:**
+- **Willing to beta test (Y/N):**
+- **Follow-up ideas:**