pdf2notes 1.0.0__tar.gz

pdf2notes-1.0.0/LICENSE

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

pdf2notes-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pdf2notes
+Version: 1.0.0
+Summary: Turn a PDF page range into AI-generated study notes (Markdown) for Obsidian/Notion
+Author: Sandeep Singh
+License: MIT
+Project-URL: Homepage, https://github.com/SandeepSinghSethi/pdf2notes
+Keywords: pdf,notes,obsidian,notion,study,ai,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber>=0.11.0
+Requires-Dist: openai>=1.0.0
+Dynamic: license-file
+
+# pdf2notes
+
+Turn a page range of a PDF book into descriptive, review-ready study notes
+(Markdown) — ready to drop into **Obsidian** or import into **Notion**.
+
+Works with any **OpenAI-compatible** chat completion API: NVIDIA NIM
+(`integrate.api.nvidia.com`), OpenAI, Groq, Together AI, OpenRouter, or a
+local server (Ollama, vLLM, LM Studio). You bring your own API key.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Get an API key (NVIDIA NIM example — free tier available)
+
+1. Go to https://build.nvidia.com
+2. Sign in, pick a model (e.g. `meta/llama-3.1-70b-instruct`), click "Get API Key"
+3. Export it:
+   ```bash
+   export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxx"
+   ```
+
+Any other OpenAI-compatible provider works the same way — just pass
+`--base-url` and `--api-key-env` for that provider.
+
+## Usage
+
+```bash
+python pdf2notes.py --pdf book.pdf --pages 120-180 --api-key-env NVIDIA_API_KEY
+```
+
+This writes `book_notes_120-180.md` in the current folder. Requests run
+concurrently and are throttled to a requests-per-minute cap, so a 100-page
+range finishes in a couple of minutes instead of an hour.
+
+If the run is interrupted, hits a persistent error, or you just Ctrl-C it,
+**rerun the exact same command** — chunks already saved in the output file
+are detected and skipped, so you only pay for/wait on what's missing.
+
+### Common options
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--pdf` | Path to the source PDF | required |
+| `--pages` | Page range, e.g. `120-180` (1-indexed, inclusive) | required |
+| `--output` | Output `.md` path | `<pdf-name>_notes_<range>.md` |
+| `--style` | `descriptive`, `cornell`, `qa`, or `outline` | `descriptive` |
+| `--chunk-chars` | Max source characters sent per API call | `6000` |
+| `--concurrency` | Max simultaneous API requests | `5` |
+| `--rpm` | Max API requests per minute (across all workers) | `40` |
+| `--model` | Model name as your provider expects it | `nvidia/llama-3.3-nemotron-super-49b-v1.5` |
+| `--base-url` | OpenAI-compatible API base URL | NVIDIA NIM endpoint |
+| `--api-key-env` | Env var holding your key | `NVIDIA_API_KEY` |
+
+**Tune `--rpm` to your actual plan.** NVIDIA's free tier, OpenAI's free/low
+tiers, etc. all cap requests per minute — check your provider's dashboard
+and set `--rpm` a bit under that. Setting it too high just means the tool
+eats a 429 and backs off; setting `--concurrency` too high does the same
+without helping speed once you're rpm-bound.
+
+**Model IDs get retired.** NVIDIA (and other providers) periodically pull
+old model IDs from the catalog — you'll get an HTTP 404/410 if that
+happens. The tool detects this as non-retryable and fails immediately with
+the error instead of burning your rate-limit budget retrying a request
+that will never succeed. Check https://build.nvidia.com/models for current
+IDs and pass the right one via `--model`.
+
+### Examples
+
+Using OpenAI instead of NVIDIA:
+```bash
+export OPENAI_API_KEY="sk-..."
+python pdf2notes.py --pdf book.pdf --pages 1-50 \
+  --base-url https://api.openai.com/v1 \
+  --model gpt-4o-mini \
+  --api-key-env OPENAI_API_KEY
+```
+
+Q&A flashcard-style notes instead of descriptive prose:
+```bash
+python pdf2notes.py --pdf book.pdf --pages 200-260 --style qa
+```
+
+## Notes on how it works
+
+1. Extracts text from the given page range with `pdfplumber`.
+2. Groups pages into chunks (default ~6000 chars each) so each API call
+   covers a coherent span without blowing past context limits.
+3. Sends each chunk to the model with a prompt tuned to produce **learnable
+   notes**, not a shortened summary — definitions, examples, and important
+   details are preserved and explained.
+4. Stitches everything into one Markdown file with YAML frontmatter
+   (title, source, page range, style, timestamp) so it's ready to file
+   straight into Obsidian, or import into Notion via *Import → Markdown*.
+
+## Limitations
+
+- **Scanned/image-only PDFs** won't extract text — OCR the PDF first (e.g.
+  with `pytesseract` + `pdf2image`), then run this tool on the OCR'd version.
+- Very dense chunking settings (`--chunk-chars` too high) can exceed your
+  model's context window — 6000–8000 is a safe default for most models.
+- Quality depends on the model you point it at — bigger instruction-tuned
+  models produce noticeably better notes than small ones.
+- **Memory**: page text is extracted one page at a time and each page's
+  internal pdfplumber cache (fonts, layout objects) is flushed immediately,
+  so memory stays roughly proportional to a chunk's text, not the whole
+  page range. For genuinely huge ranges (500+ pages in one run), consider
+  splitting into a couple of `--pages` calls instead of one giant one.
+- **A crash/segfault message *after* "Done."**: if you see a SIGSEGV or
+  similar right as the process exits but *after* your notes file is
+  already complete and readable, it's happening during Python interpreter
+  teardown, not during note generation — a known quirk of some PDF C
+  extensions (e.g. pypdfium2, used internally by pdfplumber) not tearing
+  down cleanly at exit. It doesn't affect your output file. If you want to
+  suppress the noise, run with `python pdf2notes.py ... ; true` in a
+  script, or ignore the exit code.

pdf2notes-1.0.0/README.md

@@ -0,0 +1,118 @@
+# pdf2notes
+
+Turn a page range of a PDF book into descriptive, review-ready study notes
+(Markdown) — ready to drop into **Obsidian** or import into **Notion**.
+
+Works with any **OpenAI-compatible** chat completion API: NVIDIA NIM
+(`integrate.api.nvidia.com`), OpenAI, Groq, Together AI, OpenRouter, or a
+local server (Ollama, vLLM, LM Studio). You bring your own API key.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Get an API key (NVIDIA NIM example — free tier available)
+
+1. Go to https://build.nvidia.com
+2. Sign in, pick a model (e.g. `meta/llama-3.1-70b-instruct`), click "Get API Key"
+3. Export it:
+   ```bash
+   export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxx"
+   ```
+
+Any other OpenAI-compatible provider works the same way — just pass
+`--base-url` and `--api-key-env` for that provider.
+
+## Usage
+
+```bash
+python pdf2notes.py --pdf book.pdf --pages 120-180 --api-key-env NVIDIA_API_KEY
+```
+
+This writes `book_notes_120-180.md` in the current folder. Requests run
+concurrently and are throttled to a requests-per-minute cap, so a 100-page
+range finishes in a couple of minutes instead of an hour.
+
+If the run is interrupted, hits a persistent error, or you just Ctrl-C it,
+**rerun the exact same command** — chunks already saved in the output file
+are detected and skipped, so you only pay for/wait on what's missing.
+
+### Common options
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--pdf` | Path to the source PDF | required |
+| `--pages` | Page range, e.g. `120-180` (1-indexed, inclusive) | required |
+| `--output` | Output `.md` path | `<pdf-name>_notes_<range>.md` |
+| `--style` | `descriptive`, `cornell`, `qa`, or `outline` | `descriptive` |
+| `--chunk-chars` | Max source characters sent per API call | `6000` |
+| `--concurrency` | Max simultaneous API requests | `5` |
+| `--rpm` | Max API requests per minute (across all workers) | `40` |
+| `--model` | Model name as your provider expects it | `nvidia/llama-3.3-nemotron-super-49b-v1.5` |
+| `--base-url` | OpenAI-compatible API base URL | NVIDIA NIM endpoint |
+| `--api-key-env` | Env var holding your key | `NVIDIA_API_KEY` |
+
+**Tune `--rpm` to your actual plan.** NVIDIA's free tier, OpenAI's free/low
+tiers, etc. all cap requests per minute — check your provider's dashboard
+and set `--rpm` a bit under that. Setting it too high just means the tool
+eats a 429 and backs off; setting `--concurrency` too high does the same
+without helping speed once you're rpm-bound.
+
+**Model IDs get retired.** NVIDIA (and other providers) periodically pull
+old model IDs from the catalog — you'll get an HTTP 404/410 if that
+happens. The tool detects this as non-retryable and fails immediately with
+the error instead of burning your rate-limit budget retrying a request
+that will never succeed. Check https://build.nvidia.com/models for current
+IDs and pass the right one via `--model`.
+
+### Examples
+
+Using OpenAI instead of NVIDIA:
+```bash
+export OPENAI_API_KEY="sk-..."
+python pdf2notes.py --pdf book.pdf --pages 1-50 \
+  --base-url https://api.openai.com/v1 \
+  --model gpt-4o-mini \
+  --api-key-env OPENAI_API_KEY
+```
+
+Q&A flashcard-style notes instead of descriptive prose:
+```bash
+python pdf2notes.py --pdf book.pdf --pages 200-260 --style qa
+```
+
+## Notes on how it works
+
+1. Extracts text from the given page range with `pdfplumber`.
+2. Groups pages into chunks (default ~6000 chars each) so each API call
+   covers a coherent span without blowing past context limits.
+3. Sends each chunk to the model with a prompt tuned to produce **learnable
+   notes**, not a shortened summary — definitions, examples, and important
+   details are preserved and explained.
+4. Stitches everything into one Markdown file with YAML frontmatter
+   (title, source, page range, style, timestamp) so it's ready to file
+   straight into Obsidian, or import into Notion via *Import → Markdown*.
+
+## Limitations
+
+- **Scanned/image-only PDFs** won't extract text — OCR the PDF first (e.g.
+  with `pytesseract` + `pdf2image`), then run this tool on the OCR'd version.
+- Very dense chunking settings (`--chunk-chars` too high) can exceed your
+  model's context window — 6000–8000 is a safe default for most models.
+- Quality depends on the model you point it at — bigger instruction-tuned
+  models produce noticeably better notes than small ones.
+- **Memory**: page text is extracted one page at a time and each page's
+  internal pdfplumber cache (fonts, layout objects) is flushed immediately,
+  so memory stays roughly proportional to a chunk's text, not the whole
+  page range. For genuinely huge ranges (500+ pages in one run), consider
+  splitting into a couple of `--pages` calls instead of one giant one.
+- **A crash/segfault message *after* "Done."**: if you see a SIGSEGV or
+  similar right as the process exits but *after* your notes file is
+  already complete and readable, it's happening during Python interpreter
+  teardown, not during note generation — a known quirk of some PDF C
+  extensions (e.g. pypdfium2, used internally by pdfplumber) not tearing
+  down cleanly at exit. It doesn't affect your output file. If you want to
+  suppress the noise, run with `python pdf2notes.py ... ; true` in a
+  script, or ignore the exit code.

pdf2notes-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdf2notes"
+version = "1.0.0"
+description = "Turn a PDF page range into AI-generated study notes (Markdown) for Obsidian/Notion"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Sandeep Singh" }]
+keywords = ["pdf", "notes", "obsidian", "notion", "study", "ai", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "pdfplumber>=0.11.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+pdf2notes = "pdf2notes.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/SandeepSinghSethi/pdf2notes"
+
+[tool.setuptools.packages.find]
+where = ["src"]

pdf2notes-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdf2notes-1.0.0/src/pdf2notes/__init__.py

@@ -0,0 +1,3 @@
+"""pdf2notes — turn a PDF page range into AI-generated study notes."""
+
+__version__ = "1.0.0"

pdf2notes-1.0.0/src/pdf2notes/cli.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""
+pdf2notes — Turn a page range of a PDF book into descriptive, review-ready
+study notes (Markdown), ready to drop into Obsidian or Notion.
+
+Works with ANY OpenAI-compatible chat completion API: NVIDIA NIM
+(integrate.api.nvidia.com), OpenAI, Groq, Together AI, OpenRouter, a local
+vLLM/Ollama server, etc. You bring your own API key and base URL.
+
+Requests run concurrently (bounded by --concurrency) and are throttled to
+stay under --rpm (requests/minute), so large page ranges finish in minutes
+instead of hours without tripping your provider's rate limit.
+
+USAGE
+-----
+    python pdf2notes.py --pdf book.pdf --pages 120-180 \
+        --api-key-env NVIDIA_API_KEY \
+        --base-url https://integrate.api.nvidia.com/v1 \
+        --model nvidia/llama-3.3-nemotron-super-49b-v1.5 \
+        --style descriptive \
+        --concurrency 5 --rpm 40 \
+        --output notes.md
+
+Set the API key as an environment variable first, e.g.:
+    export NVIDIA_API_KEY="nvapi-xxxxxxxx"
+
+NOTE: NVIDIA (and other providers) periodically retire model IDs. If you
+get an HTTP 404/410 error, check the current catalog at
+https://build.nvidia.com/models and pass the correct --model.
+
+If a run is interrupted or fails partway, just rerun the exact same
+command — chunks already written to the output file are skipped.
+
+Run `python pdf2notes.py --help` for all options.
+"""
+
+import argparse
+import asyncio
+import os
+import re
+import sys
+import time
+from collections import deque
+from datetime import datetime
+
+import pdfplumber
+from openai import (
+    AsyncOpenAI,
+    APIStatusError,
+    APIConnectionError,
+    RateLimitError,
+    InternalServerError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Prompt templates per note style
+# ---------------------------------------------------------------------------
+
+STYLE_PROMPTS = {
+    "descriptive": (
+        "You are an expert study-notes writer. Turn the given book excerpt into "
+        "detailed, descriptive notes a learner can review later WITHOUT rereading "
+        "the original text. Explain concepts in your own words, don't just "
+        "shorten sentences. Include definitions, examples, cause-effect "
+        "relationships, and any numbers, names, or terms that matter. "
+        "Use Markdown headers (##, ###) for structure and bullet points for "
+        "detail. Where useful, add a one-line 'Why it matters' or 'Key "
+        "takeaway' callout. Do not skip content just because it seems minor — "
+        "the goal is a faithful, learnable rewrite, not a compressed summary."
+    ),
+    "cornell": (
+        "You are an expert study-notes writer using the Cornell Notes method. "
+        "For the given book excerpt, produce Markdown with three parts: "
+        "1) '## Cues' — a bullet list of key terms/questions, "
+        "2) '## Notes' — detailed explanatory notes matching each cue, "
+        "3) '## Summary' — a short paragraph summarizing the excerpt. "
+        "Be thorough in the Notes section — this is what the learner studies from."
+    ),
+    "qa": (
+        "You are an expert study-notes writer. Convert the given book excerpt "
+        "into a thorough set of Markdown Q&A flashcard-style notes: "
+        "'### Q: <question>' followed by a detailed '**A:** <answer>'. Cover "
+        "every important concept, definition, and detail in the excerpt — "
+        "write enough questions to fully capture the material, not just the "
+        "obvious ones."
+    ),
+    "outline": (
+        "You are an expert study-notes writer. Convert the given book excerpt "
+        "into a deeply nested Markdown outline (using #, ##, ###, and nested "
+        "bullet points) that mirrors the structure of the content and captures "
+        "every important detail, definition, and example in the source."
+    ),
+}
+
+SYSTEM_SUFFIX = (
+    "\n\nFormatting rules:\n"
+    "- Output ONLY Markdown, no preamble like 'Here are the notes'.\n"
+    "- Start directly with a level-2 heading (##) that names the topic of "
+    "this excerpt.\n"
+    "- Reference page numbers in parentheses, e.g. (p. 42), when introducing "
+    "a major concept, so the notes stay traceable to the source.\n"
+    "- Never say things like 'the author discusses' — just present the "
+    "content directly, as notes.\n"
+)
+
+
+# ---------------------------------------------------------------------------
+# PDF extraction (memory-conscious: flush pdfplumber's per-page cache
+# immediately after pulling text, instead of letting fonts/layout objects
+# for the whole range pile up in memory)
+# ---------------------------------------------------------------------------
+
+def extract_pages(pdf_path, start_page, end_page):
+    """Returns list of (page_number, text) for the given 1-indexed inclusive range."""
+    pages = []
+    with pdfplumber.open(pdf_path) as pdf:
+        total = len(pdf.pages)
+        if start_page < 1 or end_page > total or start_page > end_page:
+            raise ValueError(
+                f"Invalid page range {start_page}-{end_page}. "
+                f"This PDF has {total} pages."
+            )
+        for i in range(start_page - 1, end_page):
+            page = pdf.pages[i]
+            text = page.extract_text() or ""
+            pages.append((i + 1, text))
+            # Release this page's cached fonts/chars/layout objects now —
+            # otherwise pdfplumber keeps them alive for the whole range.
+            page.flush_cache()
+    return pages
+
+
+def chunk_pages(pages, max_chars=6000):
+    """
+    Groups consecutive pages into chunks under max_chars, so each API call
+    covers a coherent span of pages. Returns list of (first_pg, last_pg, text).
+    """
+    chunks = []
+    cur_text = []
+    cur_start = None
+    cur_len = 0
+    last_pg_seen = None
+
+    for pg_num, text in pages:
+        last_pg_seen = pg_num
+        text = text.strip()
+        if not text:
+            continue
+        if cur_start is None:
+            cur_start = pg_num
+        addition = f"\n\n[--- page {pg_num} ---]\n{text}"
+        if cur_len + len(addition) > max_chars and cur_text:
+            chunks.append((cur_start, pg_num - 1, "".join(cur_text)))
+            cur_text = [addition]
+            cur_start = pg_num
+            cur_len = len(addition)
+        else:
+            cur_text.append(addition)
+            cur_len += len(addition)
+
+    if cur_text:
+        chunks.append((cur_start, last_pg_seen, "".join(cur_text)))
+
+    return chunks
+
+
+# ---------------------------------------------------------------------------
+# Resume support: figure out which chunks are already in the output file
+# ---------------------------------------------------------------------------
+
+def load_completed_ranges(output_path):
+    if not os.path.exists(output_path):
+        return set()
+    with open(output_path, "r", encoding="utf-8") as f:
+        content = f.read()
+    return {
+        (int(a), int(b))
+        for a, b in re.findall(r"<!-- pages (\d+)-(\d+) -->", content)
+    }
+
+
+# ---------------------------------------------------------------------------
+# Rate limiter (sliding window, requests/minute) — shared across all
+# concurrent workers so total request rate stays under your provider's limit
+# ---------------------------------------------------------------------------
+
+class RateLimiter:
+    def __init__(self, rpm):
+        self.rpm = max(rpm, 1)
+        self.lock = asyncio.Lock()
+        self.timestamps = deque()
+
+    async def acquire(self):
+        async with self.lock:
+            while True:
+                now = time.monotonic()
+                while self.timestamps and now - self.timestamps[0] > 60:
+                    self.timestamps.popleft()
+                if len(self.timestamps) < self.rpm:
+                    self.timestamps.append(now)
+                    return
+                wait = 60 - (now - self.timestamps[0]) + 0.05
+                await asyncio.sleep(max(wait, 0.05))
+
+
+# ---------------------------------------------------------------------------
+# AI call (async, with retry only for transient errors)
+# ---------------------------------------------------------------------------
+
+NON_RETRYABLE_HINT = (
+    "This usually means the --model name is wrong or has been retired, or "
+    "the API key / --base-url is invalid. Check your provider's current "
+    "model list (e.g. https://build.nvidia.com/models) and retry with the "
+    "correct --model."
+)
+
+
+async def generate_notes_for_chunk(client, limiter, semaphore, model, style,
+                                    chunk_text, first_pg, last_pg, stop_event,
+                                    max_retries=4):
+    system_prompt = STYLE_PROMPTS[style] + SYSTEM_SUFFIX
+    user_prompt = f"Book excerpt covering pages {first_pg}-{last_pg}:\n\n{chunk_text}"
+
+    async with semaphore:
+        delay = 2
+        for attempt in range(1, max_retries + 1):
+            if stop_event.is_set():
+                raise RuntimeError("cancelled: a fatal error occurred elsewhere")
+
+            await limiter.acquire()
+            try:
+                resp = await client.chat.completions.create(
+                    model=model,
+                    messages=[
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    temperature=0.3,
+                )
+                return resp.choices[0].message.content.strip()
+
+            except (RateLimitError, InternalServerError, APIConnectionError) as e:
+                if attempt == max_retries:
+                    raise RuntimeError(
+                        f"gave up after {max_retries} attempts (pages "
+                        f"{first_pg}-{last_pg}): {e}"
+                    ) from e
+                print(f"  [pages {first_pg}-{last_pg}] transient error "
+                      f"({type(e).__name__}), retrying in {delay}s...", file=sys.stderr)
+                await asyncio.sleep(delay)
+                delay *= 2
+
+            except APIStatusError as e:
+                # Non-retryable: bad model, auth, deprecated model (404/410), etc.
+                # Retrying this would just waste your rate-limit budget.
+                raise RuntimeError(
+                    f"HTTP {e.status_code} on pages {first_pg}-{last_pg}: "
+                    f"{e.message}. {NON_RETRYABLE_HINT}"
+                ) from e
+
+
+# ---------------------------------------------------------------------------
+# Async pipeline
+# ---------------------------------------------------------------------------
+
+async def run_pipeline(args, chunks, output_path, frontmatter, api_key):
+    completed = load_completed_ranges(output_path)
+
+    if not os.path.exists(output_path):
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(frontmatter)
+
+    pending = [
+        (i, f, l, t) for i, (f, l, t) in enumerate(chunks) if (f, l) not in completed
+    ]
+
+    already_done = len(chunks) - len(pending)
+    if already_done:
+        print(f"{already_done} chunk(s) already in {output_path} — skipping those.")
+    if not pending:
+        print("Nothing left to generate.")
+        return 0, None
+
+    print(f"Generating {len(pending)} chunk(s) "
+          f"(concurrency={args.concurrency}, rate limit={args.rpm}/min)...")
+
+    client = AsyncOpenAI(api_key=api_key, base_url=args.base_url)
+    limiter = RateLimiter(args.rpm)
+    semaphore = asyncio.Semaphore(args.concurrency)
+    stop_event = asyncio.Event()
+
+    results = {}
+    errors = {}
+
+    async def worker(idx, first_pg, last_pg, text):
+        if stop_event.is_set():
+            return
+        try:
+            notes = await generate_notes_for_chunk(
+                client, limiter, semaphore, args.model, args.style,
+                text, first_pg, last_pg, stop_event,
+            )
+            results[idx] = (first_pg, last_pg, notes)
+            print(f"  done: pages {first_pg}-{last_pg} "
+                  f"({len(results)}/{len(pending)})")
+        except RuntimeError as e:
+            errors[idx] = (first_pg, last_pg, e)
+            stop_event.set()
+
+    try:
+        tasks = [asyncio.create_task(worker(i, f, l, t)) for i, f, l, t in pending]
+        await asyncio.gather(*tasks)
+    finally:
+        await client.close()
+
+    # Flush a *contiguous* prefix of newly-completed chunks in page order.
+    # Anything after the first gap (still running/failed) is left for a
+    # rerun — resume picks it up via the <!-- pages a-b --> markers.
+    written = 0
+    with open(output_path, "a", encoding="utf-8") as fh:
+        for i, (f, l, _t) in enumerate(chunks):
+            if (f, l) in completed:
+                continue
+            if i not in results:
+                break
+            first_pg, last_pg, notes = results[i]
+            fh.write(f"\n\n<!-- pages {first_pg}-{last_pg} -->\n{notes}\n")
+            written += 1
+
+    fatal = None
+    if errors:
+        first_idx = min(errors)
+        fatal = errors[first_idx]
+
+    return written, fatal
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def parse_page_range(s):
+    m = re.match(r"^\s*(\d+)\s*-\s*(\d+)\s*$", s)
+    if not m:
+        raise argparse.ArgumentTypeError("Pages must look like START-END, e.g. 120-180")
+    return int(m.group(1)), int(m.group(2))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="pdf2notes",
+        description="Convert a PDF page range into AI-generated study notes."
+    )
+    parser.add_argument("--pdf", required=True, help="Path to the source PDF")
+    parser.add_argument("--pages", required=True, type=parse_page_range,
+                         help="Page range, e.g. 120-180 (inclusive, 1-indexed)")
+    parser.add_argument("--output", default=None,
+                         help="Output .md file (default: <pdf-name>_notes_<range>.md)")
+    parser.add_argument("--style", choices=list(STYLE_PROMPTS.keys()),
+                         default="descriptive", help="Note style (default: descriptive)")
+    parser.add_argument("--chunk-chars", type=int, default=6000,
+                         help="Max characters of source text per API call (default 6000)")
+    parser.add_argument("--concurrency", type=int, default=30,
+                         help="Max simultaneous API requests (default 5)")
+    parser.add_argument("--rpm", type=int, default=40,
+                         help="Max API requests per minute, across all workers (default 40) "
+                              "— set this to match your provider's actual rate limit")
+    parser.add_argument("--model", default="nvidia/llama-3.3-nemotron-super-49b-v1.5",
+                         help="Model name as your provider expects it. Providers retire "
+                              "model IDs periodically — check your provider's current "
+                              "catalog if this default 404s/410s.")
+    parser.add_argument("--base-url", default="https://integrate.api.nvidia.com/v1",
+                         help="OpenAI-compatible API base URL "
+                              "(default: NVIDIA NIM). Use https://api.openai.com/v1 "
+                              "for OpenAI, http://localhost:11434/v1 for local, etc.")
+    parser.add_argument("--api-key", default=None,
+                         help="API key (avoid this on shared machines — prefer --api-key-env)")
+    parser.add_argument("--api-key-env", default="NVIDIA_API_KEY",
+                         help="Env var name holding the API key (default: NVIDIA_API_KEY)")
+    args = parser.parse_args()
+
+    api_key = args.api_key or os.environ.get(args.api_key_env)
+    if not api_key:
+        print(
+            f"No API key found. Set it with:\n"
+            f"  export {args.api_key_env}=\"your-key-here\"\n"
+            f"or pass --api-key directly.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    start_page, end_page = args.pages
+    output_path = args.output or (
+        f"{os.path.splitext(os.path.basename(args.pdf))[0]}"
+        f"_notes_{start_page}-{end_page}.md"
+    )
+
+    print(f"Extracting pages {start_page}-{end_page} from {args.pdf} ...")
+    pages = extract_pages(args.pdf, start_page, end_page)
+
+    non_empty = sum(1 for _, t in pages if t.strip())
+    if non_empty == 0:
+        print(
+            "No extractable text found in this range — the PDF might be "
+            "scanned/image-based. This tool needs OCR'd text first "
+            "(e.g. run it through an OCR tool, then retry).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    chunks = chunk_pages(pages, max_chars=args.chunk_chars)
+    del pages  # done with raw page text; chunks hold what we still need
+    print(f"Split into {len(chunks)} chunk(s) for note generation.")
+
+    book_title = os.path.splitext(os.path.basename(args.pdf))[0].replace("_", " ")
+    frontmatter = (
+        "---\n"
+        f"title: \"{book_title} — Notes (pp. {start_page}-{end_page})\"\n"
+        f"source: \"{os.path.basename(args.pdf)}\"\n"
+        f"pages: \"{start_page}-{end_page}\"\n"
+        f"style: {args.style}\n"
+        f"generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}\n"
+        "tags: [book-notes]\n"
+        "---\n\n"
+    )
+
+    written, fatal = asyncio.run(
+        run_pipeline(args, chunks, output_path, frontmatter, api_key)
+    )
+
+    if fatal:
+        first_pg, last_pg, err = fatal
+        print(f"\nStopped due to an error on pages {first_pg}-{last_pg}:\n  {err}",
+              file=sys.stderr)
+        if written:
+            print(f"{written} new chunk(s) were still saved to {output_path}.",
+                  file=sys.stderr)
+        print("Fix the issue above, then rerun the exact same command — "
+              "completed chunks are skipped automatically.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"\nDone. Notes saved to: {output_path}")
+    print("Drop this file straight into your Obsidian vault, or import into Notion "
+          "(Import > Markdown).")
+
+
+if __name__ == "__main__":
+    main()

pdf2notes-1.0.0/src/pdf2notes.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pdf2notes
+Version: 1.0.0
+Summary: Turn a PDF page range into AI-generated study notes (Markdown) for Obsidian/Notion
+Author: Sandeep Singh
+License: MIT
+Project-URL: Homepage, https://github.com/SandeepSinghSethi/pdf2notes
+Keywords: pdf,notes,obsidian,notion,study,ai,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber>=0.11.0
+Requires-Dist: openai>=1.0.0
+Dynamic: license-file
+
+# pdf2notes
+
+Turn a page range of a PDF book into descriptive, review-ready study notes
+(Markdown) — ready to drop into **Obsidian** or import into **Notion**.
+
+Works with any **OpenAI-compatible** chat completion API: NVIDIA NIM
+(`integrate.api.nvidia.com`), OpenAI, Groq, Together AI, OpenRouter, or a
+local server (Ollama, vLLM, LM Studio). You bring your own API key.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Get an API key (NVIDIA NIM example — free tier available)
+
+1. Go to https://build.nvidia.com
+2. Sign in, pick a model (e.g. `meta/llama-3.1-70b-instruct`), click "Get API Key"
+3. Export it:
+   ```bash
+   export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxx"
+   ```
+
+Any other OpenAI-compatible provider works the same way — just pass
+`--base-url` and `--api-key-env` for that provider.
+
+## Usage
+
+```bash
+python pdf2notes.py --pdf book.pdf --pages 120-180 --api-key-env NVIDIA_API_KEY
+```
+
+This writes `book_notes_120-180.md` in the current folder. Requests run
+concurrently and are throttled to a requests-per-minute cap, so a 100-page
+range finishes in a couple of minutes instead of an hour.
+
+If the run is interrupted, hits a persistent error, or you just Ctrl-C it,
+**rerun the exact same command** — chunks already saved in the output file
+are detected and skipped, so you only pay for/wait on what's missing.
+
+### Common options
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--pdf` | Path to the source PDF | required |
+| `--pages` | Page range, e.g. `120-180` (1-indexed, inclusive) | required |
+| `--output` | Output `.md` path | `<pdf-name>_notes_<range>.md` |
+| `--style` | `descriptive`, `cornell`, `qa`, or `outline` | `descriptive` |
+| `--chunk-chars` | Max source characters sent per API call | `6000` |
+| `--concurrency` | Max simultaneous API requests | `5` |
+| `--rpm` | Max API requests per minute (across all workers) | `40` |
+| `--model` | Model name as your provider expects it | `nvidia/llama-3.3-nemotron-super-49b-v1.5` |
+| `--base-url` | OpenAI-compatible API base URL | NVIDIA NIM endpoint |
+| `--api-key-env` | Env var holding your key | `NVIDIA_API_KEY` |
+
+**Tune `--rpm` to your actual plan.** NVIDIA's free tier, OpenAI's free/low
+tiers, etc. all cap requests per minute — check your provider's dashboard
+and set `--rpm` a bit under that. Setting it too high just means the tool
+eats a 429 and backs off; setting `--concurrency` too high does the same
+without helping speed once you're rpm-bound.
+
+**Model IDs get retired.** NVIDIA (and other providers) periodically pull
+old model IDs from the catalog — you'll get an HTTP 404/410 if that
+happens. The tool detects this as non-retryable and fails immediately with
+the error instead of burning your rate-limit budget retrying a request
+that will never succeed. Check https://build.nvidia.com/models for current
+IDs and pass the right one via `--model`.
+
+### Examples
+
+Using OpenAI instead of NVIDIA:
+```bash
+export OPENAI_API_KEY="sk-..."
+python pdf2notes.py --pdf book.pdf --pages 1-50 \
+  --base-url https://api.openai.com/v1 \
+  --model gpt-4o-mini \
+  --api-key-env OPENAI_API_KEY
+```
+
+Q&A flashcard-style notes instead of descriptive prose:
+```bash
+python pdf2notes.py --pdf book.pdf --pages 200-260 --style qa
+```
+
+## Notes on how it works
+
+1. Extracts text from the given page range with `pdfplumber`.
+2. Groups pages into chunks (default ~6000 chars each) so each API call
+   covers a coherent span without blowing past context limits.
+3. Sends each chunk to the model with a prompt tuned to produce **learnable
+   notes**, not a shortened summary — definitions, examples, and important
+   details are preserved and explained.
+4. Stitches everything into one Markdown file with YAML frontmatter
+   (title, source, page range, style, timestamp) so it's ready to file
+   straight into Obsidian, or import into Notion via *Import → Markdown*.
+
+## Limitations
+
+- **Scanned/image-only PDFs** won't extract text — OCR the PDF first (e.g.
+  with `pytesseract` + `pdf2image`), then run this tool on the OCR'd version.
+- Very dense chunking settings (`--chunk-chars` too high) can exceed your
+  model's context window — 6000–8000 is a safe default for most models.
+- Quality depends on the model you point it at — bigger instruction-tuned
+  models produce noticeably better notes than small ones.
+- **Memory**: page text is extracted one page at a time and each page's
+  internal pdfplumber cache (fonts, layout objects) is flushed immediately,
+  so memory stays roughly proportional to a chunk's text, not the whole
+  page range. For genuinely huge ranges (500+ pages in one run), consider
+  splitting into a couple of `--pages` calls instead of one giant one.
+- **A crash/segfault message *after* "Done."**: if you see a SIGSEGV or
+  similar right as the process exits but *after* your notes file is
+  already complete and readable, it's happening during Python interpreter
+  teardown, not during note generation — a known quirk of some PDF C
+  extensions (e.g. pypdfium2, used internally by pdfplumber) not tearing
+  down cleanly at exit. It doesn't affect your output file. If you want to
+  suppress the noise, run with `python pdf2notes.py ... ; true` in a
+  script, or ignore the exit code.

pdf2notes-1.0.0/src/pdf2notes.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/pdf2notes/__init__.py
+src/pdf2notes/cli.py
+src/pdf2notes.egg-info/PKG-INFO
+src/pdf2notes.egg-info/SOURCES.txt
+src/pdf2notes.egg-info/dependency_links.txt
+src/pdf2notes.egg-info/entry_points.txt
+src/pdf2notes.egg-info/requires.txt
+src/pdf2notes.egg-info/top_level.txt

pdf2notes-1.0.0/src/pdf2notes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdf2notes-1.0.0/src/pdf2notes.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdf2notes = pdf2notes.cli:main

pdf2notes-1.0.0/src/pdf2notes.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pdfplumber>=0.11.0
+openai>=1.0.0

pdf2notes-1.0.0/src/pdf2notes.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdf2notes