paperhub 0.1.0__tar.gz

paperhub-0.1.0/.env.example

@@ -0,0 +1,21 @@
+# Copy to .env for local live-provider runs. Do not commit .env.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=
+
+# Defaults may be overridden by PaperHub(...).
+PAPERHUB_PROVIDER=openai
+
+# Optional global override. Leave empty to use the selected provider's default.
+PAPERHUB_MODEL=
+
+# Provider-specific defaults used when PaperHub(..., model=None).
+PAPERHUB_OPENAI_MODEL=gpt-5.4-mini
+PAPERHUB_OPENAI_REASONING_EFFORT=xhigh
+PAPERHUB_ANTHROPIC_MODEL=claude-haiku-4-5-20251001
+PAPERHUB_GOOGLE_MODEL=gemini-3-flash-preview
+
+PAPERHUB_CONCURRENCY=5
+PAPERHUB_MAX_PDF_CHARS=60000
+PAPERHUB_CACHE_DIR=
+PAPERHUB_REQUEST_TIMEOUT_S=30

paperhub-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+site/
+.venv/
+venv/
+env/
+
+# PaperHub runtime artifacts
+.paperhub/
+*.sqlite
+*.sqlite3
+*.db
+*.pdf
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Development-only AI / agent scaffolding
+.claude/
+.codex/
+.cursor/
+.continue/
+.aider*
+.mcp.json
+CLAUDE.md
+CLAUDE.local.md
+START_PROMPT.md
+SETUP.md
+starter-template/
+paperhub_roadmap.md
+docs/PUBLISHING.md
+
+# Secrets
+.env
+.env.*
+!.env.example
+*.pem
+secrets/
+
+# OS/editor
+.DS_Store
+.idea/
+.vscode/

paperhub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PaperHub maintainers
+
+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.

paperhub-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: paperhub
+Version: 0.1.0
+Summary: Fetch HuggingFace Daily Papers and produce Jupyter-friendly AI summaries — one paper, one agent.
+Project-URL: Homepage, https://github.com/paperhub/paperhub
+Project-URL: Issues, https://github.com/paperhub/paperhub/issues
+Author: PaperHub maintainers
+License: MIT
+License-File: LICENSE
+Keywords: arxiv,huggingface,llm,papers,summarization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: ipython>=8
+Requires-Dist: openai>=2.32
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: pypdf>=4
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: rich>=13
+Requires-Dist: tenacity>=8
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.95; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-python-dateutil; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-genai>=1.56; extra == 'google'
+Description-Content-Type: text/markdown
+
+# PaperHub
+
+PaperHub fetches HuggingFace Daily Papers by programmatic date filters, assigns
+each paper to its own AI summarization agent, and renders Jupyter-friendly
+summaries by default.
+
+Two ways to use PaperHub:
+
+1. **Terminal CLI** (`paperhub`) — interactive launcher with a REPL interface. **Primary mode.**
+2. **Python / Jupyter** — import `PaperHub` and call `hub.run(...)` directly.
+
+## Install
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+Optional provider extras:
+
+```bash
+python3 -m pip install -e ".[anthropic]"  # adds the Anthropic client
+python3 -m pip install -e ".[google]"     # adds the Google Gemini client
+```
+
+## Environment Variables
+
+PaperHub reads configuration from environment variables (or a `.env` file at
+the project root). Copy `.env.example` to `.env` to start:
+
+```bash
+cp .env.example .env
+```
+
+| Variable                           | Purpose                                                       |
+|------------------------------------|---------------------------------------------------------------|
+| `OPENAI_API_KEY`                   | Default provider key                                          |
+| `ANTHROPIC_API_KEY`                | Optional, used when `--provider anthropic`                    |
+| `GOOGLE_API_KEY`                   | Optional, used when `--provider google`                       |
+| `PAPERHUB_PROVIDER`                | Override default provider (default: openai)                   |
+| `PAPERHUB_MODEL`                   | Optional global model override                                |
+| `PAPERHUB_OPENAI_MODEL`            | OpenAI default model (default: gpt-5.4-mini)                  |
+| `PAPERHUB_OPENAI_REASONING_EFFORT` | OpenAI reasoning effort (default: xhigh)                      |
+| `PAPERHUB_ANTHROPIC_MODEL`         | Anthropic default model (default: claude-haiku-4-5-20251001)  |
+| `PAPERHUB_GOOGLE_MODEL`            | Google default model (default: gemini-3-flash-preview)        |
+| `PAPERHUB_CONCURRENCY`             | Max concurrent paper agents (default: 5)                      |
+| `PAPERHUB_MAX_PDF_CHARS`           | Truncation cap for PDF text (default: 60000)                  |
+| `PAPERHUB_CACHE_DIR`               | Override the on-disk cache location                           |
+
+## Terminal CLI (Primary)
+
+Start the interactive launcher:
+
+```bash
+paperhub
+```
+
+The launcher opens a REPL with a status dashboard showing the current provider,
+model, API key state, date range, and top paper count. Use commands to configure
+and run:
+
+```text
+/provider
+/provider openai
+/model
+/model gpt-5.4-mini
+/model default
+/language
+/date 2026-05
+/date 2026-05-15
+/date 2026-W18
+/date 2026-05-01 2026-05-31
+/top 5
+/metadata
+/run
+/api-keys
+/quit
+```
+
+### Date formats for `/date`
+
+| Example                        | Period   | Description           |
+|-------------------------------|----------|-----------------------|
+| `/date 2026-05`               | month    | May 2026              |
+| `/date 2026`                  | year     | Full year 2026        |
+| `/date 2026-05-15`            | day      | Single day            |
+| `/date 2026-W18`              | week     | ISO week 18 of 2026   |
+| `/date 2026-05-01 2026-05-31` | custom   | Inclusive date range  |
+
+`/metadata` fetches HuggingFace paper metadata only and does not call an LLM.
+If the selected provider key is missing, `/run` prints setup guidance and the
+launcher can render `docs/API_KEYS.md` with `/api-keys`.
+
+You can also pass startup flags:
+
+```bash
+paperhub --provider anthropic
+paperhub --model claude-haiku-4-5-20251001
+paperhub --top-n 10
+```
+
+## Python / Jupyter API
+
+```python
+from datetime import date
+from paperhub import PaperHub
+
+hub = PaperHub(provider="openai")
+
+# Month
+hub.run(period="month", year=2026, month=5, top_n=10)
+
+# Single day
+hub.run(period="day", year=2026, month=5, day=1, top_n=5)
+
+# ISO week
+hub.run(period="week", year=2026, week=18, top_n=5)
+
+# Full year
+hub.run(period="year", year=2026, top_n=20)
+
+# Custom range
+hub.run(period="custom", start=date(2026, 4, 15), end=date(2026, 4, 30), top_n=15)
+```
+
+`run` returns a `list[PaperSummary]`; in non-Jupyter contexts pass
+`display=False` and call `render_plain` yourself if you do not need the
+Markdown side effect.
+
+For a step-by-step notebook, open `examples/03_jupyter_quickstart.ipynb`.
+
+## Provider Selection
+
+```python
+PaperHub(provider="openai")                             # OpenAI default model
+PaperHub(provider="openai", model="gpt-5.4-mini")
+PaperHub(provider="anthropic")                          # Anthropic default model
+PaperHub(model="claude-haiku-4-5-20251001", provider="anthropic")
+PaperHub(model="gemini-3-flash-preview", provider="google")
+```
+
+If `model` is omitted, PaperHub picks the selected provider's default model.
+Provider-specific `.env` values such as `PAPERHUB_OPENAI_MODEL` override those
+defaults. `PAPERHUB_MODEL` remains available as a global override. OpenAI uses
+`PAPERHUB_OPENAI_REASONING_EFFORT=xhigh` by default; set it to an empty value
+to let the OpenAI API choose its model default.
+
+Provider SDKs are imported lazily — installing `paperhub` includes OpenAI by
+default, and does not require Anthropic or Google packages unless you use those
+providers.
+
+## Caching
+
+PaperHub caches metadata, PDF text, and summaries in
+`~/.cache/paperhub/paperhub.sqlite` (override with `PAPERHUB_CACHE_DIR`).
+Summary entries are keyed by `(arxiv_id, model, language)`, so swapping models
+or output language gives you a clean re-run while keeping the PDF download
+free.
+
+A second invocation with the same papers and model:
+
+- Reuses the cached PDF text (no arXiv hit, no extraction).
+- Reuses the cached summary (no LLM call).
+
+## Tests, Lint, Typecheck, Build
+
+```bash
+python3 -m pytest          # unit tests, no live network or LLM keys needed
+python3 -m ruff check .
+python3 -m ruff format --check .
+python3 -m mypy src tests
+python3 -m build           # build wheel + sdist
+```
+
+The unit tests use a fake LLM client and `httpx.MockTransport`; no real
+provider keys are required.
+
+## Project Layout
+
+```
+src/paperhub/
+  __init__.py           # PaperHub public API
+  config.py             # Settings (pydantic-settings)
+  models.py             # PaperMeta, PaperSummary, RunRequest
+  dates.py              # period → (start, end)
+  fetchers/             # HF JSON API (default) + HTML fallback
+  pdf/                  # arXiv download + text extraction
+  agents/               # LLMClient protocol + provider clients + PaperAgent
+  orchestrator.py       # asyncio.Semaphore parallelism
+  cache.py              # SQLite cache
+  formatter.py          # Markdown / plain-text rendering
+  interactive_cli.py    # `paperhub` interactive launcher
+tests/                  # pytest suite, mocked HTTP and fake LLM
+docs/ARCHITECTURE.md
+docs/HOW_TO_START.md
+docs/API_KEYS.md
+examples/README.md
+examples/03_jupyter_quickstart.ipynb
+```
+
+## Troubleshooting
+
+- *"No papers found"*: HuggingFace may not yet have published Daily Papers
+  for that date. Use `/metadata` in the interactive launcher to check the
+  fetcher without an LLM call.
+- *PDF text comes back tiny*: some arXiv PDFs use unusual layouts. PaperHub
+  falls back to `pdfplumber`; if both extractors are short, the agent will
+  pass through the abstract as the input text instead of failing.

paperhub-0.1.0/README.md

@@ -0,0 +1,207 @@
+# PaperHub
+
+PaperHub fetches HuggingFace Daily Papers by programmatic date filters, assigns
+each paper to its own AI summarization agent, and renders Jupyter-friendly
+summaries by default.
+
+Two ways to use PaperHub:
+
+1. **Terminal CLI** (`paperhub`) — interactive launcher with a REPL interface. **Primary mode.**
+2. **Python / Jupyter** — import `PaperHub` and call `hub.run(...)` directly.
+
+## Install
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+Optional provider extras:
+
+```bash
+python3 -m pip install -e ".[anthropic]"  # adds the Anthropic client
+python3 -m pip install -e ".[google]"     # adds the Google Gemini client
+```
+
+## Environment Variables
+
+PaperHub reads configuration from environment variables (or a `.env` file at
+the project root). Copy `.env.example` to `.env` to start:
+
+```bash
+cp .env.example .env
+```
+
+| Variable                           | Purpose                                                       |
+|------------------------------------|---------------------------------------------------------------|
+| `OPENAI_API_KEY`                   | Default provider key                                          |
+| `ANTHROPIC_API_KEY`                | Optional, used when `--provider anthropic`                    |
+| `GOOGLE_API_KEY`                   | Optional, used when `--provider google`                       |
+| `PAPERHUB_PROVIDER`                | Override default provider (default: openai)                   |
+| `PAPERHUB_MODEL`                   | Optional global model override                                |
+| `PAPERHUB_OPENAI_MODEL`            | OpenAI default model (default: gpt-5.4-mini)                  |
+| `PAPERHUB_OPENAI_REASONING_EFFORT` | OpenAI reasoning effort (default: xhigh)                      |
+| `PAPERHUB_ANTHROPIC_MODEL`         | Anthropic default model (default: claude-haiku-4-5-20251001)  |
+| `PAPERHUB_GOOGLE_MODEL`            | Google default model (default: gemini-3-flash-preview)        |
+| `PAPERHUB_CONCURRENCY`             | Max concurrent paper agents (default: 5)                      |
+| `PAPERHUB_MAX_PDF_CHARS`           | Truncation cap for PDF text (default: 60000)                  |
+| `PAPERHUB_CACHE_DIR`               | Override the on-disk cache location                           |
+
+## Terminal CLI (Primary)
+
+Start the interactive launcher:
+
+```bash
+paperhub
+```
+
+The launcher opens a REPL with a status dashboard showing the current provider,
+model, API key state, date range, and top paper count. Use commands to configure
+and run:
+
+```text
+/provider
+/provider openai
+/model
+/model gpt-5.4-mini
+/model default
+/language
+/date 2026-05
+/date 2026-05-15
+/date 2026-W18
+/date 2026-05-01 2026-05-31
+/top 5
+/metadata
+/run
+/api-keys
+/quit
+```
+
+### Date formats for `/date`
+
+| Example                        | Period   | Description           |
+|-------------------------------|----------|-----------------------|
+| `/date 2026-05`               | month    | May 2026              |
+| `/date 2026`                  | year     | Full year 2026        |
+| `/date 2026-05-15`            | day      | Single day            |
+| `/date 2026-W18`              | week     | ISO week 18 of 2026   |
+| `/date 2026-05-01 2026-05-31` | custom   | Inclusive date range  |
+
+`/metadata` fetches HuggingFace paper metadata only and does not call an LLM.
+If the selected provider key is missing, `/run` prints setup guidance and the
+launcher can render `docs/API_KEYS.md` with `/api-keys`.
+
+You can also pass startup flags:
+
+```bash
+paperhub --provider anthropic
+paperhub --model claude-haiku-4-5-20251001
+paperhub --top-n 10
+```
+
+## Python / Jupyter API
+
+```python
+from datetime import date
+from paperhub import PaperHub
+
+hub = PaperHub(provider="openai")
+
+# Month
+hub.run(period="month", year=2026, month=5, top_n=10)
+
+# Single day
+hub.run(period="day", year=2026, month=5, day=1, top_n=5)
+
+# ISO week
+hub.run(period="week", year=2026, week=18, top_n=5)
+
+# Full year
+hub.run(period="year", year=2026, top_n=20)
+
+# Custom range
+hub.run(period="custom", start=date(2026, 4, 15), end=date(2026, 4, 30), top_n=15)
+```
+
+`run` returns a `list[PaperSummary]`; in non-Jupyter contexts pass
+`display=False` and call `render_plain` yourself if you do not need the
+Markdown side effect.
+
+For a step-by-step notebook, open `examples/03_jupyter_quickstart.ipynb`.
+
+## Provider Selection
+
+```python
+PaperHub(provider="openai")                             # OpenAI default model
+PaperHub(provider="openai", model="gpt-5.4-mini")
+PaperHub(provider="anthropic")                          # Anthropic default model
+PaperHub(model="claude-haiku-4-5-20251001", provider="anthropic")
+PaperHub(model="gemini-3-flash-preview", provider="google")
+```
+
+If `model` is omitted, PaperHub picks the selected provider's default model.
+Provider-specific `.env` values such as `PAPERHUB_OPENAI_MODEL` override those
+defaults. `PAPERHUB_MODEL` remains available as a global override. OpenAI uses
+`PAPERHUB_OPENAI_REASONING_EFFORT=xhigh` by default; set it to an empty value
+to let the OpenAI API choose its model default.
+
+Provider SDKs are imported lazily — installing `paperhub` includes OpenAI by
+default, and does not require Anthropic or Google packages unless you use those
+providers.
+
+## Caching
+
+PaperHub caches metadata, PDF text, and summaries in
+`~/.cache/paperhub/paperhub.sqlite` (override with `PAPERHUB_CACHE_DIR`).
+Summary entries are keyed by `(arxiv_id, model, language)`, so swapping models
+or output language gives you a clean re-run while keeping the PDF download
+free.
+
+A second invocation with the same papers and model:
+
+- Reuses the cached PDF text (no arXiv hit, no extraction).
+- Reuses the cached summary (no LLM call).
+
+## Tests, Lint, Typecheck, Build
+
+```bash
+python3 -m pytest          # unit tests, no live network or LLM keys needed
+python3 -m ruff check .
+python3 -m ruff format --check .
+python3 -m mypy src tests
+python3 -m build           # build wheel + sdist
+```
+
+The unit tests use a fake LLM client and `httpx.MockTransport`; no real
+provider keys are required.
+
+## Project Layout
+
+```
+src/paperhub/
+  __init__.py           # PaperHub public API
+  config.py             # Settings (pydantic-settings)
+  models.py             # PaperMeta, PaperSummary, RunRequest
+  dates.py              # period → (start, end)
+  fetchers/             # HF JSON API (default) + HTML fallback
+  pdf/                  # arXiv download + text extraction
+  agents/               # LLMClient protocol + provider clients + PaperAgent
+  orchestrator.py       # asyncio.Semaphore parallelism
+  cache.py              # SQLite cache
+  formatter.py          # Markdown / plain-text rendering
+  interactive_cli.py    # `paperhub` interactive launcher
+tests/                  # pytest suite, mocked HTTP and fake LLM
+docs/ARCHITECTURE.md
+docs/HOW_TO_START.md
+docs/API_KEYS.md
+examples/README.md
+examples/03_jupyter_quickstart.ipynb
+```
+
+## Troubleshooting
+
+- *"No papers found"*: HuggingFace may not yet have published Daily Papers
+  for that date. Use `/metadata` in the interactive launcher to check the
+  fetcher without an LLM call.
+- *PDF text comes back tiny*: some arXiv PDFs use unusual layouts. PaperHub
+  falls back to `pdfplumber`; if both extractors are short, the agent will
+  pass through the abstract as the input text instead of failing.

paperhub-0.1.0/docs/API_KEYS.md

@@ -0,0 +1,67 @@
+# PaperHub API Keys
+
+PaperHub only needs an API key for the provider you choose for summarization.
+Metadata-only checks do not require any LLM key.
+
+## Environment Variables
+
+| Provider | Environment variable | Extra install |
+|----------|----------------------|---------------|
+| OpenAI | `OPENAI_API_KEY` | included by default |
+| Anthropic | `ANTHROPIC_API_KEY` | `python3 -m pip install -e ".[anthropic]"` |
+| Google Gemini | `GOOGLE_API_KEY` | `python3 -m pip install -e ".[google]"` |
+
+## Recommended `.env` Setup
+
+From the repository root:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+PAPERHUB_PROVIDER=openai
+PAPERHUB_CONCURRENCY=2
+PAPERHUB_MAX_PDF_CHARS=60000
+```
+
+Do not commit `.env`; the repository `.gitignore` excludes it.
+
+## Provider Selection
+
+Use the launcher:
+
+```text
+/provider
+/provider openai
+/provider anthropic
+/provider google
+```
+
+## Missing Key Behavior
+
+If the selected provider key is missing, PaperHub will stop before making an
+LLM call and print setup guidance. You can still check the fetch pipeline:
+
+```text
+/metadata
+```
+
+In the interactive launcher, use:
+
+```text
+/status
+/provider
+/api-keys
+/metadata
+```
+
+`/status` shows the selected provider key state. `/provider` opens the full
+provider/API-key availability selector. `/api-keys` prints this guide in the
+terminal.