Metadata-Version: 2.4
Name: paperlab
Version: 0.1.9
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

Requires Python 3.11 or 3.12. Python 3.14 is not yet supported (some transitive dependencies do not build on 3.14).

```bash
pipx install --python python3.12 paperlab
paperlab init
```

Alternative — install with pip inside a project venv:

```bash
python3.12 -m venv .venv && source .venv/bin/activate
pip install paperlab
paperlab init
```

Install from source:

```bash
git clone https://github.com/zhakhatoff/paperlab.git
cd paperlab
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
paperlab --help
```

`paperlab init` creates `~/.paperlab/` with a default `config.toml` and a `sessions/` subdirectory. Run with `--force` to overwrite an existing config.

**pipx broken on Python 3.14?** If `pipx install` fails with `ensurepip` errors, your pipx shared venv is running on Python 3.14. Pin it to 3.12:

```bash
rm -rf ~/.local/pipx/shared
PIPX_DEFAULT_PYTHON=$(brew --prefix python@3.12)/bin/python3.12 pipx ensurepath
```

### CLI

| Command | What it does |
|---|---|
| `paperlab version` | Print installed version |
| `paperlab init [--force]` | Create `~/.paperlab/{config.toml, sessions/}` |
| `paperlab read <paper.pdf>` | Run the 4-agent review (see flags below) |
| `paperlab list` | Table of past sessions |
| `paperlab show <session-id> [--format markdown\|json]` | Reprint a past session |
| `paperlab config get <key>` | Read `provider` / `model` / `mode` / `lang` / `extra.<k>` |
| `paperlab config set <key> <value>` | Update config.toml |
| `paperlab web` | Launch Gradio dashboard |

`paperlab read` flags:

| Flag | Values | Default |
|---|---|---|
| `--mode` | `rigorous`, `learning` | from config |
| `--lang` | `en`, `ru` | from config |
| `--provider` | see table below | from config |
| `--model` | any model string the provider accepts | from config |
| `--format` | `markdown`, `json` | `markdown` |
| `--output` | file path | stdout |
| `--skip-preflight` | skip provider readiness checks | off |

The global `--verbose` / `-v` flag turns on debug logging to stderr. Before starting a review paperlab runs a preflight check: for `ollama` — that the service is running; for cloud providers — that an API key is saved. If not, it prints a clear hint and exits without running the review. Use `--skip-preflight` to bypass.

```bash
paperlab read paper.pdf --mode rigorous --lang en
paperlab read paper.pdf --mode learning --lang ru --provider ollama --model qwen2.5:7b
paperlab read paper.pdf --format json --output report.json
```

### Providers

paperlab uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood. Supported provider names:

| Name | Where it runs | Auth | Model string example |
|---|---|---|---|
| `ollama` | Local (default) | none | `qwen2.5:7b`, `llama3.2:3b` |
| `openrouter` | Cloud | `OPENROUTER_API_KEY` | `openrouter/anthropic/claude-3.5-sonnet` |
| `together` | Cloud | `TOGETHERAI_API_KEY` | `together_ai/meta-llama/Llama-3-70b-chat-hf` |
| `groq` | Cloud | `GROQ_API_KEY` | `groq/llama-3.1-70b-versatile` |
| `gemini` | Cloud | `GEMINI_API_KEY` | `gemini/gemini-1.5-pro` |
| `anthropic` | Cloud | `ANTHROPIC_API_KEY` | `claude-3-5-sonnet-20241022` |
| `openai` | Cloud | `OPENAI_API_KEY` | `gpt-4o` |
| `custom` | Any OpenAI-compatible endpoint | as needed | LiteLLM convention |
| `fake` | In-process test double | none | any |

Switch globally with `paperlab config set provider <name>` or per invocation with `--provider`.

**API keys.** The web dashboard (`paperlab web`) lets you pick a provider, save its API key, and browse available models. Keys are stored locally in `~/.paperlab/keys.toml` (file mode 600, never leaves your machine); environment variables take precedence over the stored file. For Ollama the dashboard detects whether it is installed and running, lists installed models with sizes, and recommends models that fit your RAM.

### 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` — мягкий разбор для студентов, читающих первые статьи

Два языка вывода: английский или русский.

### Установка

Требуется Python 3.11 или 3.12. Python 3.14 пока не поддерживается (часть транзитивных зависимостей не собирается на 3.14).

```bash
pipx install --python python3.12 paperlab
paperlab init
```

Или через pip в проектном venv:

```bash
python3.12 -m venv .venv && source .venv/bin/activate
pip install paperlab
paperlab init
```

Из исходников:

```bash
git clone https://github.com/zhakhatoff/paperlab.git
cd paperlab
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
paperlab --help
```

**pipx падает на Python 3.14?** Если `pipx install` валится с ошибкой про `ensurepip`, у pipx общий venv на Python 3.14. Перегони его на 3.12:

```bash
rm -rf ~/.local/pipx/shared
PIPX_DEFAULT_PYTHON=$(brew --prefix python@3.12)/bin/python3.12 pipx ensurepath
```

Команда `paperlab init` создаёт `~/.paperlab/` с дефолтным `config.toml` и поддиректорией `sessions/`. Флаг `--force` перезаписывает существующий конфиг.

### Использование

| Команда | Что делает |
|---|---|
| `paperlab version` | Печатает установленную версию |
| `paperlab init [--force]` | Создаёт `~/.paperlab/{config.toml, sessions/}` |
| `paperlab read <paper.pdf>` | Запускает разбор четырьмя агентами (флаги ниже) |
| `paperlab list` | Таблица прошлых разборов |
| `paperlab show <session-id> [--format markdown\|json]` | Печатает прошлый разбор |
| `paperlab config get <key>` | Читает `provider` / `model` / `mode` / `lang` / `extra.<k>` |
| `paperlab config set <key> <value>` | Обновляет `config.toml` |
| `paperlab web` | Запускает Gradio-дашборд |

Флаги `paperlab read`:

| Флаг | Значения | По умолчанию |
|---|---|---|
| `--mode` | `rigorous`, `learning` | из конфига |
| `--lang` | `en`, `ru` | из конфига |
| `--provider` | см. таблицу провайдеров | из конфига |
| `--model` | любая строка, которую понимает провайдер | из конфига |
| `--format` | `markdown`, `json` | `markdown` |
| `--output` | путь к файлу | stdout |
| `--skip-preflight` | пропустить проверку готовности провайдера | off |

```bash
paperlab read paper.pdf --mode rigorous --lang ru
paperlab read paper.pdf --mode learning --lang en --provider ollama --model qwen2.5:7b
paperlab read paper.pdf --format json --output report.json
```

Глобальный флаг `--verbose` (`-v`) включает подробный лог в stderr. Перед запуском разбора paperlab делает preflight-проверку: для `ollama` — что сервис запущен, для облачных провайдеров — что API-ключ сохранён; при отсутствии печатает понятную подсказку и выходит без прогона. Пропустить проверку можно флагом `--skip-preflight`.

### Провайдеры

Работает с любым из этих без изменений в коде:

- `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
