condensr 0.4.0

Summarize books chapter by chapter using AI

Condensr

Summarize books chapter by chapter using AI.

Condensr takes a PDF book as input and produces a structured Markdown summary. It detects chapters automatically and summarizes each one individually (max ~500 words per chapter) using Mistral AI.

Installation

pip install condensr

Quick Start

Python API

import condensr

# Preview detected chapters (no API calls)
chapters = condensr.get_chapters("book.pdf")
print(chapters)
# ["Introduction", "Chapter 1: Origins", "Chapter 2: Growth"]

# Summarize chapter by chapter
for title, summary in condensr.summarize("book.pdf"):
    print(f"## {title}\n{summary}\n")

CLI

condensr book.pdf
# Writes book-summary.md with progress output

API Reference

condensr.get_chapters(pdf_path, *, toc_level=1)

Detect and return chapter titles from a PDF. Uses heuristic detection only (no API calls). Returns an empty list if no chapters are found.

Parameters:

• pdf_path (str) — Path to the PDF file.
• toc_level (int) — Maximum TOC depth to include. Default: 1 (main chapters only). Use 2 to include sub-sections.

Returns: list[str] — Chapter titles.

condensr.summarize(pdf_path, *, model, api_key, on_chapter, toc_level=1)

Summarize a PDF book chapter by chapter. Returns a generator yielding (title, summary_markdown) tuples.

If no chapters are detected, summarizes the entire book as one unit.

Parameters:

• pdf_path (str) — Path to the PDF file.
• model (str) — Mistral model name. Default: "mistral-small-latest".
• api_key (str | None) — Mistral API key. Falls back to MISTRAL_API_KEY env var.
• on_chapter (callable | None) — Optional callback(title, summary) fired before each yield.
• toc_level (int) — Maximum TOC depth to include. Default: 1. Use 2 to include sub-sections.

Yields: tuple[str, str] — (chapter_title, summary_markdown).

Callback Example

def on_chapter(title, summary):
    save_to_db(title, summary)

for title, summary in condensr.summarize("book.pdf", on_chapter=on_chapter):
    display(title, summary)

CLI Reference

Usage: condensr [OPTIONS] PDF_PATH

  Summarize a PDF book chapter by chapter.

Options:
  -o, --output PATH    Output file path. Default: <book>-summary.md
  -m, --model TEXT     Mistral model name.
  -t, --toc-level INT  Chapter detection depth: 1 for main chapters only,
                       2 to include sub-sections. [default: 1]
  --help               Show this message and exit.

Configuration

Set your Mistral API key as an environment variable:

export MISTRAL_API_KEY="your-api-key"

Or pass it programmatically:

for title, summary in condensr.summarize("book.pdf", api_key="your-api-key"):
    ...

Privacy Notice

Condensr sends the text content of your PDF to Mistral AI's API servers for summarization. Do not use Condensr with confidential or sensitive documents unless you are comfortable with this data being transmitted to a third-party service. Review Mistral's privacy policy for details on how your data is handled.

License

AGPL-3.0-or-later

Release Process

This project uses Commitizen for automated versioning and twine for local PyPI publishing.

How to release a new version

1. Ensure all your changes are committed on the main branch.
2. Run the bump command to update CHANGELOG.md and create a new Git tag:

   cz bump
   

3. Build and upload the package:

   rm -rf dist/ build/
   python -m build
   twine upload dist/*
   

4. Push the changes and new tag to GitLab:

   git push origin main --tags
   

Troubleshooting

If cz bump fails with "No tag found to do an incremental changelog", the CHANGELOG.md file is out of sync with the Git tags. Regenerate it with:

cz changelog

Then commit the updated changelog before running cz bump again.

For detailed instructions, see docs/RELEASE_PROCESS.md.