Metadata-Version: 2.5
Name: papers-app
Version: 0.2.0
Summary: An AI reading companion for research papers: skim, read, ask, recall. Runs on your computer.
Project-URL: Homepage, https://github.com/hBouanane/papers
Project-URL: Issues, https://github.com/hBouanane/papers/issues
Author: hBouanane
License-Expression: MIT
License-File: LICENSE
Keywords: ai,llm,papers,pdf,reading,research
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24
Requires-Dist: pdfplumber>=0.11
Requires-Dist: pypdf>=5
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# Papers

An AI reading companion for research papers. Define what you are working on, get relevant
papers, skim them Andrew Ng–style, read with an explainer that knows the whole paper, track
where you stopped, quiz yourself when you finish, ask "where did I read this idea?", and follow
reference chains. It runs on your computer; your papers and notes stay there.
See [SPEC.md](SPEC.md) for the design.

## Install

With Python 3.11 or newer, one command (like `npx` for Node):

```bash
uvx papers-app
```

or install it to keep it around, then start it with `papers`:

```bash
pipx install papers-app
```

`papers` opens http://localhost:8000 in your browser. Options: `--port 9000`, `--data D:\Papers` (where the
database and PDFs live), `--no-browser`, `--host 0.0.0.0` (reach it from other devices on your network; there
is no login, so only on networks you trust).

### With Docker

```bash
docker compose up -d
```

Then open http://localhost:8000. Your library is kept in the `papers-data` volume. See
[docker-compose.yml](docker-compose.yml) to use a folder on your computer for the library folder, or a model
running on your computer (Ollama, LM Studio). Subscriptions (Claude, ChatGPT) need their app on the same
computer, so in Docker use an API key or a local model.

### From the source

```bash
git clone https://github.com/hBouanane/papers && cd papers
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"     # macOS/Linux: .venv/bin/pip
.venv/Scripts/papers
```

## Choosing an AI model

Settings > AI model has one list of providers; each is set up the same way (key if it needs one, then
**List models** and pick one). Each provider keeps its own key and model, so you can switch freely.

- **Use your subscription**: Claude (Pro, Max) through [Claude Code](https://claude.com/claude-code), or
  ChatGPT (Plus, Pro) through OpenAI's [Codex CLI](https://developers.openai.com/codex/cli/reference)
  (`npm install -g @openai/codex`, then `codex login`). Both run on your computer with your own account,
  for your own use: don't host the app for others on your subscription.
- **Pay per use with an API key**: Anthropic, OpenAI, Google Gemini (has a free tier), Mistral, Groq, or
  OpenRouter (hundreds of models).
- **On this computer**: [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai). Free, and nothing
  leaves your machine.
- **Other**: any OpenAI-compatible server (vLLM, llama.cpp, a company gateway), by its address.

Small local models can't read a whole paper; *More options* can send just its beginning.
Keys are kept in your system's keychain (Windows Credential Manager, macOS Keychain, or the Secret Service on Linux),
so you paste each one once; Settings shows which provider has a key saved (its last four characters) and can forget
it. Where there's no keychain (Docker, servers) they stay in the app's database. Keys are never sent back to the page.

With a subscription the app runs the official CLI on your computer (`claude -p` or `codex exec`, with no
tools), which signs in with your own account; usage counts toward your plan. The app never reads or stores
those credentials. `PAPERS_CLAUDE_BIN` and `PAPERS_CODEX_BIN` point at a specific binary if needed.

## Asking the AI

Select text in a paper and press **Explain** (a short lesson: the problem, the idea, the formula read slowly, a worked
example, why it works, where it connects in the paper), **Simplify** (the same passage in plain English) or
**Translate**. Each starts a conversation you can keep going; **History** keeps them per paper, and **Add to chat**
attaches more passages.

Answers can contain formulas, clickable citations ([§3.4], [Fig. 1]), charts, diagrams, the paper's own figures with
"look here" boxes, and interactive widgets. Switch the chat to **Deep** and the AI first reads the sections, looks at
the figures and checks your notes and library before it answers; ask it to and it saves notes, words and
highlights, or adds a paper from the references (each with Undo). Deep mode works with Claude (subscription or API
key) and with models that support tool calling; in **More options**, tick *This model can see images* if yours does,
and *Interactive pages* to let the AI write small demos that run in a sealed frame.

## Library folder

In Settings, choose a folder (**Choose…** opens a folder browser with your usual folders and drives) and the app keeps a copy of your
library there: one folder per goal (`Unsorted` for the rest), each paper as `Author et al. Year - Title.pdf`
with a `.md` notes file next to it (key points, explanations, quiz, `[[links]]` to related papers, so
Obsidian shows them as a graph). PDFs dropped into its `Inbox` folder are imported within about 10 seconds.

## Settings from the environment

| Variable | What it does |
| --- | --- |
| `PAPERS_DATA` | Folder for the database, PDFs and figures (same as `--data`). Default: `%APPDATA%\Papers`, `~/Library/Application Support/Papers` or `~/.local/share/papers` |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | API keys, if you'd rather not type them in Settings |
| `S2_API_KEY` | A Semantic Scholar key; without one, search often falls back to arXiv because of rate limits |
| `PAPERS_MODEL` | The Claude model used by default (`claude-opus-5-5`) |
| `PAPERS_INBOX_POLL` | Seconds between Inbox checks (`0` turns it off) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md): how the code is laid out, how to run it and the tests, and where to
start for common changes.

## License

[MIT](LICENSE)
