# BookWorm AI

Production-ready AI book summarization for EPUB, PDF, MOBI/AZW, and plain-text books. BookWorm AI creates coherent, hierarchical, genre-aware summaries with any OpenAI-compatible LLM and exports them to Markdown, JSON, HTML, PDF, or EPUB.

It is built for long-form reading: bounded context, chapter-level understanding, cross-chapter synthesis, evidence-aware editing, and polished document output.

The repository contains source code and tests only. No book files, generated summaries, credentials, or private endpoint configuration are committed.

## Features

- EPUB, PDF, MOBI/AZW, and TXT input
- Markdown, JSON, HTML, PDF, and EPUB output
- Automatic genre detection with explicit theme overrides
- Hierarchical processing for books larger than the model context window
- Bounded overlapping chunks for oversized chapters
- Chapter cards, section synthesis, global book memory, and final integration
- Optional deep editorial review with coverage, coherence, fidelity, and issue reporting
- English prompt contracts with Portuguese user-facing output by default
- Strict JSON-object responses, required-key validation, and one repair attempt
- Streaming, retries, bounded concurrency, and checkpointed resume
- Unicode-safe, searchable PDF output with a dedicated contextual appendix
- OpenAI, Anthropic, Google, OpenRouter, and arbitrary OpenAI-compatible gateways

## Requirements

- Python 3.10–3.13
- An API key for an OpenAI-compatible chat-completions endpoint
- A Unicode font available to ReportLab for PDF output; BookWorm detects common system fonts automatically

## Installation

For local development:

```bash
uv sync --extra dev
```

With pip:

```bash
pip install -e ".[dev]"
```

## Configuration

BookWorm reads configuration from environment variables. Nothing is hardcoded for a private deployment.

```bash
export BOOKWORM_API_KEY="your-api-key"
export BOOKWORM_BASE_URL="https://your-gateway.example/v1"
export BOOKWORM_MODEL="auto"
```

`BOOKWORM_BASE_URL` may be a gateway root, a `/v1` URL, or a `/chat/completions` URL; BookWorm normalizes it. Provider-specific environment variables such as `OPENAI_API_KEY` are also supported.

The same values can be stored locally with `bookworm config`. Local configuration is written below `~/.bookworm` with owner-only permissions and is ignored by Git.

## Usage

```bash
# Automatically detect the work type and write Markdown
bookworm process book.epub --theme auto --format markdown --output summary.md

# Create a searchable PDF
bookworm process book.pdf --theme technical --format pdf --output summary.pdf

# Create an EPUB summary for a novel
bookworm process novel.mobi --theme story --format epub --output summary.epub

# Create machine-readable output
bookworm process biography.epub --theme biography --format json --output summary.json

# Run the slower editorial review stage
bookworm process book.epub --deep-review --format pdf --output reviewed.pdf

# Resume an interrupted run
bookworm process book.epub --resume --format pdf --output summary.pdf
```

Available themes: `auto`, `general`, `technical`, `story`, `academic`, `business`, `history`, and `biography`.

Summaries are written in Portuguese by default. Prompts, schemas, source code, and repository documentation are maintained in English.

## Processing model

1. Parse and normalize the source into chapters.
2. Skip duplicate or irrelevant front matter by default.
3. Split only oversized chapters into bounded, overlapping chunks.
4. Extract structured notes or a chapter card from each chapter.
5. Consolidate chapter cards into independent section summaries.
6. Reduce large section collections recursively when necessary.
7. Generate global memory and one integrated final summary.
8. Optionally run a separate editorial review with `--deep-review`.
9. Render every output format from the same `BookSummary` model.

Chapter work runs in controlled waves, while independent section requests run concurrently. Each completed chapter is checkpointed so an interrupted run can resume without restarting completed work.

## Project layout

```text
src/bookworm/
  cli/          Command-line interface and checkpoint management
  core/         Shared data models
  formatters/   Markdown, JSON, HTML, PDF, and EPUB renderers
  llm/          OpenAI-compatible client, retries, streaming, and usage tracking
  parsers/      EPUB, PDF, MOBI/AZW, and text parsing
  summarizer/   Legacy chapter API and the hierarchical production pipeline
tests/          Parser, client, formatter, and hierarchical pipeline tests
```

## Development

```bash
uv sync --extra dev
uv run pytest -q
uv run python -m compileall -q src
uv run ruff check src tests
```

The test suite covers parser behavior, configuration, checkpointing, Unicode PDF output, nested structured data, chunk boundaries, malformed JSON repair, and hierarchical aggregation.

## Privacy and safety

BookWorm sends extracted book text to the configured LLM endpoint. Do not process copyrighted or confidential material unless you have the right to do so and the endpoint is appropriate for that data. API keys and local progress files stay outside the repository. Review important claims against the original book.

## License

MIT. See [LICENSE](LICENSE).