# Plan: Documentation Update + Release 0.1.3

## Other speed-up opportunities (brief answer)

Yes, one meaningful option remains: **parallel field optimization** — run all fields simultaneously in threads rather than sequentially. Currently fields depend on prior results (greedy), but a non-greedy parallel mode would trade ~5% quality for N-field parallelism. This is a larger change that should be a separate task. All other quick wins (num_threads fix, fast mode kwargs) are already implemented.

---

## This plan: docs, PR, release, publish

### Branch strategy
Work is already on `davidberenstein1957/field-opt-perf-compare`. Create a clean new branch `davidberenstein1957/feat/fast-mode-and-progress` from current state.

---

## Step 1 — Update documentation (5 files + README)

Replace `sequential` semantics with `fast` semantics throughout:

### `README.md` (lines 90, 146, 173)
- Line 90: Replace "sequential mode: each field description is optimized independently" → explain `fast=False` (default) is sequential, `fast=True` is single-pass
- Line 146: Replace `sequential=False,` → `fast=True,`
- Line 173: Update link text from "sequential mode" → "fast/default modes"

### `docs/concepts/optimization.md` (lines 7–165)
- Replace section headers "Sequential Mode (Default)" / "Single-Pass Mode (Legacy)" with "Default Mode (fast=False)" / "Fast Mode (fast=True)"
- Update all `sequential=True/False` code references
- Update Mermaid diagram node label from `{Sequential?}` to `{fast?}`
- Add `FieldOptimizationProgress` callback mention

### `docs/guides/advanced/configure-optimizations.md` (lines 14–34)
- Update Quick Reference table: replace `Sequential | True | True` → `fast | False | False | Single-pass for speed`
- Replace "Sequential vs Single-Pass Optimization" section with "Default vs Fast Mode"
- Update all code examples
- Add section on `on_progress` callback with example

### `docs/guides/advanced/field-exclusion.md` (line 139)
- Update link text only: "sequential mode" → "fast/default modes"

### `docs/guides/optimization/first-optimization.md` (line 148)
- Update inline mention of "sequential mode" → "default mode"

### `docs/reference/api/prompter.md` and `docs/reference/api/types.md`
- Add `FieldOptimizationProgress` to types reference
- Update `Prompter.optimize()` param docs: `fast`, `on_progress`

---

## Step 2 — Bump version 0.1.2 → 0.1.3

Edit `src/dspydantic/__init__.py` line 3: `__version__ = "0.1.3"`

---

## Step 3 — Move example script

Move `compare_optimization.py` to `examples/compare_optimization.py` (cleaner repo structure).
Remove temp files: `verify_api.py`, `test_fast_mode.py`, `IMPLEMENTATION_SUMMARY.md`, `OPTIMIZATION_COMPARISON.md`.

---

## Step 4 — Commit and create PR

```bash
git checkout -b davidberenstein1957/feat/fast-mode-and-progress
git add src/dspydantic/ docs/ README.md examples/
git commit -m "feat: replace sequential with fast, add progress callbacks, fix num_threads"
gh pr create --title "feat: fast mode, progress callbacks, num_threads fix" \
  --body "..." --base main
```

PR body covers:
- `sequential` → `fast` parameter (breaking change: `fast=False` default = old `sequential=True`)
- New `FieldOptimizationProgress` dataclass + `on_progress` callback
- Auto progress output when `verbose=True`
- Bug fix: `num_threads` now passed to all optimizers, not just MIPROv2
- Fast mode: `max_bootstrapped_demos=1`, single-pass for speed

---

## Step 5 — Merge PR

```bash
gh pr merge --merge --delete-branch
```

---

## Step 6 — Create GitHub release

```bash
gh release create v0.1.3 --title "v0.1.3 - Fast mode and progress callbacks" \
  --notes "..."
```

Release notes cover:
- Breaking: `sequential` parameter removed, replaced by `fast` (default `False`)
- New: `FieldOptimizationProgress` dataclass exported from `dspydantic`
- New: `on_progress` callback parameter on `optimize()`
- New: Auto progress output when `verbose=True`
- Fix: `num_threads` now applied to BootstrapFewShot (was MIPROv2-only)
- Migration: `sequential=True` → `fast=False`, `sequential=False` → `fast=True`

---

## Step 7 — Build and publish

```bash
uv build
uv publish
```

---

## Files to modify

| File | Change |
|------|--------|
| `src/dspydantic/__init__.py` | Version bump 0.1.2 → 0.1.3 |
| `README.md` | Replace sequential references |
| `docs/concepts/optimization.md` | Replace sequential with fast semantics |
| `docs/guides/advanced/configure-optimizations.md` | Replace sequential with fast semantics, add on_progress example |
| `docs/guides/advanced/field-exclusion.md` | Link text only |
| `docs/guides/optimization/first-optimization.md` | Inline mention |
| `docs/reference/api/types.md` | Add FieldOptimizationProgress |
| `docs/reference/api/prompter.md` | Update optimize() params |
| `examples/compare_optimization.py` | Move from root |

## Cleanup (delete)
- `verify_api.py`
- `test_fast_mode.py`
- `IMPLEMENTATION_SUMMARY.md`
- `OPTIMIZATION_COMPARISON.md`
