---
status: pending
priority: p2
issue_id: "004"
tags: [code-review, type-safety, python, api]
---

# Missing `__all__`, return type, and `on_chapter` type annotation

## Problem Statement

Three related type annotation gaps in the public API that affect library quality and IDE/mypy support:

1. **No `__all__`** — `condensr` package exports all 7 imported names (`detect_chapters`, `extract_chapter_text`, `extract_full_text`, `get_book_title`, `summarize_text`, `get_chapters`, `summarize`), when only the last two are public.
2. **`summarize()` has no return type** — It's a generator yielding `tuple[str, str]` but the annotation is absent.
3. **`on_chapter` is untyped** — IDEs can't autocomplete callback signatures; mypy can't verify arity.

## Findings

**`condensr/__init__.py:3-7`:**
```python
from condensr.parser import detect_chapters, extract_chapter_text, ...  # all become public
from condensr.summarizer import summarize_text                          # also public

def summarize(pdf_path: str, *, model: str = ..., api_key: str | None = None, on_chapter=None):  # no return type, on_chapter untyped
```

## Proposed Solution

```python
# condensr/__init__.py
from __future__ import annotations
from collections.abc import Callable, Generator
from condensr.parser import Chapter, detect_chapters, extract_chapter_text, extract_full_text, get_book_title
from condensr.summarizer import summarize_text

__all__ = ["get_chapters", "summarize"]


def summarize(
    pdf_path: str,
    *,
    model: str = "mistral-small-latest",
    api_key: str | None = None,
    on_chapter: Callable[[str, str], None] | None = None,
) -> Generator[tuple[str, str], None, None]:
    ...
```

## Technical Details

- **File:** `condensr/__init__.py`

## Acceptance Criteria

- [ ] `__all__ = ["get_chapters", "summarize"]` defined in `__init__.py`
- [ ] `summarize()` annotated with `-> Generator[tuple[str, str], None, None]`
- [ ] `on_chapter` typed as `Callable[[str, str], None] | None`
- [ ] `from collections.abc import Callable, Generator` imported
- [ ] `mypy condensr/` passes (or shows only expected SDK-related issues)
