# Brainstorm: Chapter List Filtering

**Date:** 2026-03-08
**Status:** Draft

## What We're Building

Improve `get_chapters()` to return only meaningful content chapters by filtering out two types of noise:

1. **Meta entries** — Non-content chapters like "Copyright", "Dedication", "Contents", "Notes", "About the Authors", "Remerciements", "Dédicace", etc.
2. **Sub-sections** — Section titles within chapters that are detected as separate chapters (e.g., "What is your reason for being?" inside "I: IKIGAI").

### Example

**Before (current):**
```
['TITLE PAGE', 'COPYRIGHT', 'DEDICATION', 'EPIGRAPH', 'CONTENTS',
 'PROLOGUE: Ikigai: A mysterious word', 'I: IKIGAI',
 'What is your reason for being?', 'Whatever you do, don't retire!', ...]
```

**After (expected):**
```
['PROLOGUE: Ikigai: A mysterious word', 'I: IKIGAI',
 'II: ANTIAGING SECRETS', 'III: FROM LOGOTHERAPY TO IKIGAI', ...]
```

## Why This Approach

### Decision 1: Level-1 TOC entries only

The sub-section problem comes from including level-2 TOC entries. Restricting `_detect_from_toc` to level-1 entries eliminates sub-sections cleanly.

- Simple, predictable behavior
- Aligns with how most books structure their TOC (chapters = level 1)

### Decision 2: Multi-language blocklist for meta entries

A hardcoded blocklist of common non-content chapter names in multiple languages (English, French, Spanish, German, etc.) filters out meta entries.

- No API calls, no latency cost
- Easy to extend as new languages or patterns are encountered
- Case-insensitive exact matching (normalize to lowercase)

### Decision 3: Filtering scope — TOC-based detection only

The blocklist filtering applies only to Tier 1 (TOC-based detection). Tier 2 (heading heuristics) is already selective due to its font-size threshold and regex patterns.

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| TOC depth | Level 1 only | Sub-sections are level-2 entries |
| Filtering method | Multi-language blocklist | Simple, no API cost, predictable |
| Matching strategy | Case-insensitive exact | Avoids false positives |
| Filtering scope | TOC detection only | Heading heuristics already selective |

## Open Questions

None — all key decisions resolved.

## Implementation Notes

Changes will be localized to `condensr/parser.py`, specifically the `_detect_from_toc` function:
1. Change `level <= 2` filter to `level == 1`
2. Add a blocklist set and filter out matching titles
