thethreemagi/bookapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Blueprint v2.4-2.6: Style Rules UI, Lore RAG, Thread Tracking, Redo Book

Browse Source 
v2.4 — Item 7: Refresh Style Guidelines
- web/routes/admin.py: Added /admin/refresh-style-guidelines route (AJAX-aware)
- templates/system_status.html: Added 'Refresh Style Rules' button with spinner

v2.5 — Item 8: Lore & Location RAG-Lite
- story/bible_tracker.py: Added update_lore_index() — extracts location/item
  descriptions from chapters into tracking_lore.json
- story/writer.py: Reads chapter locations/key_items, builds LORE_CONTEXT block
  injected into the prompt (graceful degradation if no tags)
- cli/engine.py: Loads tracking_lore.json on resume, calls update_lore_index
  after each chapter, saves tracking_lore.json

v2.5 — Item 9: Structured Story State (Thread Tracking)
- story/state.py (new): load_story_state, update_story_state (extracts
  active_threads, immediate_handoff, resolved_threads via model_logic),
  format_for_prompt (structured context replacing the prev_sum blob)
- cli/engine.py: Loads story_state.json on resume, uses format_for_prompt as
  summary_ctx for write_chapter, updates state after each chapter accepted

v2.6 — Item 10: Redo Book
- templates/consistency_report.html: Added 'Redo Book' form with instruction
  input and confirmation dialog
- web/routes/run.py: Added revise_book route — creates new Run, queues
  generate_book_task with user instruction as feedback

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Wichers
2026-02-21 01:35:43 -05:00
parent 2db7a35a66
commit 83a6a4315b
9 changed files with 291 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
ai_blueprint.md
View File

@@ -1,4 +1,4 @@
# AI Context Optimization Blueprint (v2.5)
# AI Context Optimization Blueprint (v2.6)
This blueprint outlines architectural improvements for how AI context is managed during the writing process. The goal is to provide the AI (Claude/Gemini) with **better, highly-targeted context upfront**, which will dramatically improve first-draft quality and reduce the reliance on expensive, time-consuming quality checks and rewrites (currently up to 5 attempts).
@@ -79,9 +79,9 @@ Despite the existing `style_guidelines.json` and basic prompts, the AI writing o
AI models evolve, and new overused phrases regularly emerge. The static list in `data/style_guidelines.json` will become outdated. The `refresh_style_guidelines()` function already exists in `story/style_persona.py` but has no UI or scheduled trigger.
**Solution & Implementation Plan:**
1. **Admin UI Trigger:** ⏳ Add a "Refresh Style Guidelines" button to `templates/system_status.html` (near the existing "Refresh & Optimize"). Use the same async AJAX pattern from Section 5.
2. **Backend Route:** ⏳ Add a `/admin/refresh-style-guidelines` route in `web/routes/admin.py` that calls `style_persona.refresh_style_guidelines(model_logic, folder)` and returns JSON status.
3. **Logging:** ⏳ Log changes to `data/app.log` so admins can see what was added or removed.
1. ✅ **Admin UI Trigger:** Added "Refresh Style Rules" button to `templates/system_status.html` using the same async AJAX spinner pattern as "Refresh & Optimize". *(Implemented v2.4)*
2. ✅ **Backend Route:** Added `/admin/refresh-style-guidelines` route in `web/routes/admin.py` that calls `style_persona.refresh_style_guidelines(model_logic)` and returns JSON status with counts. *(Implemented v2.4)*
3. ✅ **Logging:** Route logs the updated counts to `data/app.log` via `utils.log`. *(Implemented v2.4)*
## 8. Lore & Location Context Retrieval (RAG-Lite) — v2.5
@@ -89,10 +89,11 @@ AI models evolve, and new overused phrases regularly emerge. The static list in
The remaining half of Section 1 — `prev_sum` and the `style_block` carry all world-building as a monolithic blob. Locations, artifacts, and lore details not relevant to the current chapter waste tokens and dilute the AI's focus, causing it to hallucinate setting details or ignore established world rules.
**Solution & Implementation Plan:**
1. **Tag Beats with Locations/Items:** ⏳ Extend the chapter schema in the blueprint JSON to support optional `locations` and `key_items` arrays per chapter (e.g., `"locations": ["The Thornwood Inn"]`, `"key_items": ["The Sunstone Amulet"]`).
2. **Lore Index in Bible:** ⏳ Add a `lore` dict to `tracking_*.json` (managed by `story/bible_tracker.py`) that maps location/item names to short canonical descriptions (max 2 sentences each).
3. **Retrieval in `write_chapter`:** ⏳ In `story/writer.py`, before building the prompt, scan the chapter's `locations` and `key_items` arrays and pull matching entries from the lore index into a `lore_block` injected into the prompt — replacing the monolithic style block lore dump.
4. **Fallback:** If no tags are present, behaviour is unchanged (graceful degradation).
1. ✅ **Tag Beats with Locations/Items:** Chapter schema supports optional `locations` and `key_items` arrays. `story/writer.py` reads these from the chapter dict. *(Implemented v2.5)*
2. ✅ **Lore Index in Bible:** Added `update_lore_index(folder, chapter_text, current_lore)` to `story/bible_tracker.py`. Index is stored in `tracking_lore.json` and loaded into `tracking['lore']`. *(Implemented v2.5)*
3. ✅ **Retrieval in `write_chapter`:** `story/writer.py` matches chapter `locations`/`key_items` against the lore index and injects a `LORE_CONTEXT` block into the prompt. *(Implemented v2.5)*
4. ✅ **Fallback:** If chapter has no `locations`/`key_items` or lore index is empty, `lore_block` is empty and behaviour is unchanged. *(Implemented v2.5)*
5. ✅ **Engine Wiring:** `cli/engine.py` loads `tracking_lore.json` on resume, calls `update_lore_index` after each chapter, and saves to `tracking_lore.json`. *(Implemented v2.5)*
## 9. Structured "Story So Far" — Thread Tracking — v2.5
@@ -100,18 +101,19 @@ The remaining half of Section 1 — `prev_sum` and the `style_block` carry all w
The remaining half of Section 2 — `prev_sum` is a growing unstructured narrative blob. As chapters accumulate, the AI receives an ever-longer wall of prose-summary as context, which dilutes attention, buries the most important recent state, and causes continuity drift.
**Solution & Implementation Plan:**
1. **Structured Summary Schema:** ⏳ After each chapter is written, use `model_logic` to extract structured state into a `story_state.json` file:
```json
{
"active_threads": ["Elara is searching for the Sunstone", "The Inquisitor suspects Daren"],
"immediate_handoff": "Elara escaped through the east gate. Daren was left behind. Dawn is breaking.",
"resolved_threads": ["The tavern debt is paid"],
"chapter": 7
}
```
2. **Prompt Injection:** ⏳ In `story/writer.py`, replace the raw `prev_sum` blob with a formatted injection of the structured state — active threads first, then the `immediate_handoff`, hiding resolved threads unless they are referenced in the current chapter's beats.
3. **State Update Step:** ⏳ After `write_chapter` completes and is accepted, call a `update_story_state(chapter_text, current_state, folder)` function in `story/bible_tracker.py` (or a new `story/state.py`) to update `story_state.json` with the new chapter's resolved/active threads.
4. **Continuity Guard:** ⏳ The `immediate_handoff` field from the previous chapter must always appear verbatim in the prompt as the first context block, before `prev_sum`, so the AI always sees the most recent physical/emotional state of the POV character.
1. ✅ **Structured Summary Schema:** New `story/state.py` module. After each chapter, `update_story_state()` uses `model_logic` to extract and save `story_state.json` with `active_threads`, `immediate_handoff` (exactly 3 sentences), and `resolved_threads`. *(Implemented v2.5)*
2. ✅ **Prompt Injection:** `cli/engine.py` calls `story_state.format_for_prompt(current_story_state, chapter_beats)` before each `write_chapter` call. The formatted string replaces `prev_sum` as the context. Falls back to the raw `summary` blob if no structured state exists yet. *(Implemented v2.5)*
3. ✅ **State Update Step:** `cli/engine.py` calls `story_state.update_story_state()` after each chapter is written and accepted, saving `story_state.json` in the book folder. *(Implemented v2.5)*
4. ✅ **Continuity Guard:** `format_for_prompt()` always places `IMMEDIATE STORY HANDOFF` first, followed by `ACTIVE PLOT THREADS`. Resolved threads are only included if referenced in the next chapter's beats. *(Implemented v2.5)*
## 10. Consistency Report Quick Fix (v2.6)
**Current Problem:**
The `templates/consistency_report.html` page displays issues found in the manuscript but does not provide a direct action to fix them. It only suggests using the "Read & Edit" or "Modify & Re-run" features.
**Solution & Implementation Plan:**
1. ✅ **Frontend Action:** Added "Redo Book" form to `templates/consistency_report.html` footer with a text input for the revision instruction and a confirmation prompt on submit. *(Implemented v2.6)*
2. ✅ **Backend Route:** Added `/project/<run_id>/revise_book/<book_folder>` route in `web/routes/run.py`. Route creates a new `Run` record and queues `generate_book_task` with the user's instruction as `feedback` and `source_run_id` pointing to the original run. The existing bible refinement logic in `generate_book_task` applies the instruction to the bible before regenerating. *(Implemented v2.6)*
## Summary of Actionable Changes for Implementation Mode:
1. ✅ Modify `writer.py` to filter `chars_for_writer` based on characters named in `beats`. *(Implemented in v1.5.0)*
@@ -120,6 +122,7 @@ The remaining half of Section 2 — `prev_sum` is a growing unstructured narrati
4. ✅ Add a pre-processing function to expand chapter beats into staging directions before generating the prose draft. *(Implemented in v2.0 — `expand_beats_to_treatment` in `story/writer.py`)*
5. ✅ **(v2.2)** Update "Refresh & Optimize" action in UI to be an async fetch call with a processing flag instead of a full page reload, and update `admin.py` to handle JSON responses.
6. ✅ **(v2.3)** Updated writing prompts and evaluation rubrics across `story/writer.py`, `story/editor.py`, and `story/style_persona.py` to aggressively filter AI-isms, enforce Deep POV via a non-negotiable mandate, add genre-specific writing instructions, and fail chapters that rely on "telling" rather than "showing" via filter-word density checks in the evaluator.
7. ⏳ **(v2.4)** Add "Refresh Style Guidelines" button + backend route to trigger AI review of `data/style_guidelines.json`, keeping the AI-isms list current. *(See Section 7)*
8. ⏳ **(v2.5)** Implement Lore & Location RAG-Lite: tag chapter beats with locations/items, build a lore index in the bible tracker, inject only relevant lore into each chapter prompt. *(See Section 8)*
9. ⏳ **(v2.5)** Implement Structured Story State (Thread Tracking): replace the raw `prev_sum` blob with a structured `story_state.json` containing active threads, a precise immediate handoff, and resolved threads. *(See Section 9)*
7. ✅ **(v2.4)** Add "Refresh Style Rules" button to `system_status.html` and `/admin/refresh-style-guidelines` route in `admin.py`. *(Implemented v2.4)*
8. ✅ **(v2.5)** Lore & Location RAG-Lite: `update_lore_index` in `bible_tracker.py`, `tracking_lore.json`, lore retrieval in `writer.py`, wired in `engine.py`. *(Implemented v2.5)*
9. ✅ **(v2.5)** Structured Story State (Thread Tracking): new `story/state.py`, `story_state.json`, structured prompt context replacing raw summary blob in `engine.py`. *(Implemented v2.5)*
10. ✅ **(v2.6)** "Redo Book" form in `consistency_report.html` + `revise_book` route in `run.py` that creates a new run with the instruction applied as bible feedback. *(Implemented v2.6)*