v2.0.0: Modularize project into single-responsibility packages
Replaced monolithic modules/ package with a clean architecture:
- core/ config.py, utils.py
- ai/ models.py (ResilientModel), setup.py (init_models)
- story/ planner.py, writer.py, editor.py, style_persona.py, bible_tracker.py
- marketing/ cover.py, blurb.py, fonts.py, assets.py
- export/ exporter.py
- web/ app.py (Flask factory), db.py, helpers.py, tasks.py, routes/{auth,project,run,persona,admin}.py
- cli/ engine.py (run_generation), wizard.py (BookWizard)
Flask routes split into 5 Blueprints; all templates updated with blueprint-
prefixed url_for() calls. Dockerfile and docker-compose updated to use
web.app entry point and new package paths.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
312
ai_blueprint.md
Normal file
312
ai_blueprint.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# AI Blueprint: Modularization Plan
|
||||
|
||||
This blueprint details the strategy to break down the monolithic files (`main.py`, `wizard.py`, `modules/story.py`, `modules/web_app.py`, `modules/marketing.py`, `modules/web_tasks.py`, `modules/ai.py`) into a small-file, Single Responsibility architecture.
|
||||
|
||||
## Proposed Folder Structure
|
||||
|
||||
```
|
||||
c:/Users/thethreemagi/OneDrive/Gemini/BookApp/
|
||||
├── core/
|
||||
│ ├── config.py
|
||||
│ └── utils.py
|
||||
├── ai/
|
||||
│ ├── setup.py
|
||||
│ └── models.py
|
||||
├── story/
|
||||
│ ├── planner.py
|
||||
│ ├── writer.py
|
||||
│ ├── editor.py
|
||||
│ ├── style_persona.py
|
||||
│ └── bible_tracker.py
|
||||
├── marketing/
|
||||
│ ├── blurb.py
|
||||
│ ├── cover.py
|
||||
│ ├── fonts.py
|
||||
│ └── assets.py
|
||||
├── export/
|
||||
│ └── exporter.py
|
||||
├── web/
|
||||
│ ├── app.py
|
||||
│ ├── db.py
|
||||
│ ├── tasks.py
|
||||
│ └── routes/
|
||||
│ ├── auth.py
|
||||
│ ├── project.py
|
||||
│ ├── run.py
|
||||
│ ├── admin.py
|
||||
│ └── persona.py
|
||||
├── cli/
|
||||
│ ├── engine.py
|
||||
│ └── wizard.py
|
||||
```
|
||||
|
||||
## Step-by-Step Migration Details
|
||||
|
||||
### 1. `core/` Module
|
||||
**New File: `core/config.py`**
|
||||
- Moves `config.py` unchanged.
|
||||
|
||||
**New File: `core/utils.py`**
|
||||
- Moves all functions from `modules/utils.py`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, datetime, time, threading, re
|
||||
from core import config
|
||||
```
|
||||
|
||||
### 2. `ai/` Module (Extracting from `modules/ai.py`)
|
||||
**New File: `ai/models.py`**
|
||||
- Extract `ResilientModel` class, and global model variables (`model_logic`, `model_writer`, etc.).
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import google.generativeai as genai
|
||||
from core import utils
|
||||
```
|
||||
|
||||
**New File: `ai/setup.py`**
|
||||
- Extract `init_models`, `select_best_models`, `get_optimal_model`, `get_default_models`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, time, warnings
|
||||
import google.generativeai as genai
|
||||
from core import config, utils
|
||||
from ai import models
|
||||
```
|
||||
|
||||
### 3. `story/` Module (Extracting from `modules/story.py`)
|
||||
**New File: `story/planner.py`**
|
||||
- Extract `enrich`, `plan_structure`, `expand`, `create_chapter_plan`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json, random
|
||||
from core import utils
|
||||
from ai import models as ai_models
|
||||
from story.bible_tracker import filter_characters
|
||||
```
|
||||
|
||||
**New File: `story/writer.py`**
|
||||
- Extract `write_chapter`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json, os
|
||||
from core import config, utils
|
||||
from ai import models as ai_models
|
||||
from story.style_persona import get_style_guidelines
|
||||
from story.editor import evaluate_chapter_quality
|
||||
```
|
||||
|
||||
**New File: `story/editor.py`**
|
||||
- Extract `evaluate_chapter_quality`, `check_pacing`, `analyze_consistency`, `rewrite_chapter_content`, `check_and_propagate`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json, os
|
||||
from core import config, utils
|
||||
from ai import models as ai_models
|
||||
from story.style_persona import get_style_guidelines
|
||||
```
|
||||
|
||||
**New File: `story/style_persona.py`**
|
||||
- Extract `get_style_guidelines`, `refresh_style_guidelines`, `create_initial_persona`, `refine_persona`, `update_persona_sample`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json, os, time
|
||||
from core import config, utils
|
||||
from ai import models as ai_models
|
||||
```
|
||||
|
||||
**New File: `story/bible_tracker.py`**
|
||||
- Extract `merge_selected_changes`, `filter_characters`, `update_tracking`, `harvest_metadata`, `refine_bible`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json
|
||||
from core import utils
|
||||
from ai import models as ai_models
|
||||
```
|
||||
|
||||
### 4. `marketing/` Module (Extracting from `modules/marketing.py`)
|
||||
**New File: `marketing/fonts.py`**
|
||||
- Extract `download_font`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, requests
|
||||
from core import config, utils
|
||||
```
|
||||
|
||||
**New File: `marketing/cover.py`**
|
||||
- Extract `generate_cover`, `evaluate_image_quality`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, shutil, textwrap, subprocess, sys
|
||||
from core import config, utils
|
||||
from ai import models as ai_models
|
||||
from marketing.fonts import download_font
|
||||
from rich.prompt import Confirm
|
||||
try:
|
||||
from PIL import Image, ImageDraw, ImageFont
|
||||
HAS_PIL = True
|
||||
except ImportError:
|
||||
HAS_PIL = False
|
||||
```
|
||||
|
||||
**New File: `marketing/blurb.py`**
|
||||
- Extract `generate_blurb`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os
|
||||
from core import utils
|
||||
from ai import models as ai_models
|
||||
```
|
||||
|
||||
**New File: `marketing/assets.py`**
|
||||
- Extract `create_marketing_assets`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
from marketing.blurb import generate_blurb
|
||||
from marketing.cover import generate_cover
|
||||
```
|
||||
|
||||
### 5. `export/` Module (Extracting from `modules/export.py`)
|
||||
**New File: `export/exporter.py`**
|
||||
- Extract `create_readme`, `compile_files`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, markdown
|
||||
from docx import Document
|
||||
from ebooklib import epub
|
||||
from core import utils
|
||||
```
|
||||
|
||||
### 6. `web/` Module (Extracting from `modules/web_app.py` and `modules/web_tasks.py`)
|
||||
**New File: `web/db.py`**
|
||||
- Extract models `User`, `Project`, `Run`, `LogEntry` from `modules/web_db.py`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
from flask_sqlalchemy import SQLAlchemy
|
||||
from flask_login import UserMixin
|
||||
from datetime import datetime
|
||||
db = SQLAlchemy()
|
||||
```
|
||||
|
||||
**New File: `web/tasks.py`**
|
||||
- Extract Huey configuration and tasks `generate_book_task`, `regenerate_artifacts_task`, `rewrite_chapter_task`, `refine_bible_task`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, time, sqlite3, shutil
|
||||
from datetime import datetime
|
||||
from huey import SqliteHuey
|
||||
from core import config, utils
|
||||
from ai import setup as ai_setup
|
||||
from story import planner, writer, editor, style_persona, bible_tracker
|
||||
from marketing import cover, assets
|
||||
from export import exporter
|
||||
from web.db import db, Run, User, Project
|
||||
```
|
||||
|
||||
**New File: `web/routes/auth.py`**
|
||||
- Extract `/login`, `/register`, `/logout`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
from flask import Blueprint, render_template, request, redirect, url_for, flash
|
||||
from flask_login import login_user, login_required, logout_user, current_user
|
||||
from werkzeug.security import generate_password_hash, check_password_hash
|
||||
from web.db import db, User
|
||||
```
|
||||
|
||||
**New File: `web/routes/project.py`**
|
||||
- Extract `/`, `/project/setup`, `/project/setup/refine`, `/project/create`, `/project/import`, `/project/<id>`, `/project/<id>/update`, `/project/<id>/clone`, `/project/<id>/add_book`, `/project/<id>/book/<book_num>/update`, `/project/<id>/delete_book/<book_num>`, `/project/<id>/import_characters`, `/project/<id>/set_persona`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json
|
||||
from datetime import datetime
|
||||
from flask import Blueprint, render_template, request, redirect, url_for, flash
|
||||
from flask_login import login_required, current_user
|
||||
from core import config, utils
|
||||
from ai import setup as ai_setup, models as ai_models
|
||||
from web.db import db, Project, Run
|
||||
from story import planner, bible_tracker
|
||||
```
|
||||
|
||||
**New File: `web/routes/run.py`**
|
||||
- Extract `/project/<id>/run`, `/run/<id>`, `/run/<id>/status`, `/run/<id>/stop`, `/run/<id>/restart`, `/project/<run_id>/regenerate_artifacts`, `/project/<run_id>/revise_book/<book>`, `/project/<run_id>/read/<book>`, `/project/<run_id>/save_chapter`, `/project/<run_id>/check_consistency/<book>`, `/project/<run_id>/sync_book/<book>`, `/project/<run_id>/rewrite_chapter`, `/project/<run_id>/download`, `/task_status/<task_id>`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, markdown
|
||||
from flask import Blueprint, render_template, request, redirect, url_for, flash, send_from_directory, session
|
||||
from flask_login import login_required, current_user
|
||||
from web.db import db, Project, Run, LogEntry
|
||||
from web.tasks import huey, generate_book_task, regenerate_artifacts_task, rewrite_chapter_task
|
||||
from core import config, utils
|
||||
from story import editor, bible_tracker, style_persona
|
||||
from export import exporter
|
||||
```
|
||||
|
||||
**New File: `web/routes/persona.py`**
|
||||
- Extract `/personas`, `/persona/new`, `/persona/<name>`, `/persona/save`, `/persona/delete/<name>`, `/persona/analyze`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json
|
||||
from flask import Blueprint, render_template, request, redirect, url_for, flash
|
||||
from flask_login import login_required
|
||||
from core import config, utils
|
||||
from ai import setup as ai_setup, models as ai_models
|
||||
```
|
||||
|
||||
**New File: `web/routes/admin.py`**
|
||||
- Extract `/admin`, `/admin/user/<id>/delete`, `/admin/project/<id>/delete`, `/admin/reset`, `/admin/spend`, `/admin/style`, `/admin/impersonate/<id>`, `/admin/stop_impersonate`, `/debug/routes`, `/system/optimize_models`, `/system/status`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, json, shutil
|
||||
from datetime import datetime, timedelta
|
||||
from flask import Blueprint, render_template, request, redirect, url_for, flash, session
|
||||
from flask_login import login_required, current_user, login_user
|
||||
from sqlalchemy import func
|
||||
from web.db import db, User, Project, Run
|
||||
from core import config, utils
|
||||
from story import style_persona
|
||||
from ai import setup as ai_setup, models as ai_models
|
||||
```
|
||||
|
||||
**New File: `web/app.py`**
|
||||
- Flask initialization, registering blueprints, and the `__main__` entry point.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os
|
||||
from flask import Flask
|
||||
from flask_login import LoginManager
|
||||
from core import config
|
||||
from web.db import db, User
|
||||
```
|
||||
|
||||
### 7. `cli/` Module
|
||||
**New File: `cli/engine.py`**
|
||||
- Extract `process_book` and `run_generation` from `main.py`.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import json, os, time, sys, shutil
|
||||
from rich.prompt import Confirm
|
||||
from core import config, utils
|
||||
from ai import setup as ai_setup
|
||||
from story import planner, writer, editor, style_persona, bible_tracker
|
||||
from marketing import cover, assets
|
||||
from export import exporter
|
||||
```
|
||||
|
||||
**New File: `cli/wizard.py`**
|
||||
- Move `wizard.py` here and update imports.
|
||||
- **Exact Imports:**
|
||||
```python
|
||||
import os, sys, json
|
||||
from rich.console import Console
|
||||
from rich.panel import Panel
|
||||
from rich.prompt import Prompt, IntPrompt, Confirm
|
||||
from rich.table import Table
|
||||
from flask import Flask
|
||||
from core import config, utils
|
||||
from ai import setup as ai_setup, models as ai_models
|
||||
from web.db import db, User, Project
|
||||
```
|
||||
|
||||
## HTML Template Changes
|
||||
The `templates/` folder contains HTML files. Ensure any `url_for()` calls reference the correct Blueprint names (e.g., `url_for('auth.login')` instead of `url_for('login')`).
|
||||
|
||||
Awaiting approval to begin creating files and making structural changes.
|
||||
Reference in New Issue
Block a user