241 lines
11 KiB
Markdown
241 lines
11 KiB
Markdown
# 📚 BookApp: AI-Powered Series Engine
|
||
|
||
An automated pipeline for planning, drafting, and publishing novels using Google Gemini.
|
||
|
||
## 🚀 Quick Start
|
||
1. **Install:** `pip install -r requirements.txt`
|
||
2. **Web Dependencies:** `pip install -r modules/requirements_web.txt`
|
||
3. **Setup:** Add your API key to `.env`.
|
||
4. **Launch Dashboard:** `python -m modules.web_app`
|
||
5. **Open Browser:** Go to `http://localhost:5000` to create projects, manage personas, and generate books.
|
||
|
||
### Alternative: CLI Mode
|
||
If you prefer the command line:
|
||
1. Run `python wizard.py` to create or edit your book settings interactively.
|
||
2. Run `python main.py <path_to_bible.json>` to generate the book(s).
|
||
|
||
## 🛡️ Admin Access
|
||
The application includes a protected Admin Dashboard at `/admin` for managing users and performing factory resets. Access is password-protected and restricted to users with the Admin role.
|
||
|
||
**Method 1: Environment Variables (Recommended for Docker)**
|
||
Set `ADMIN_USERNAME` and `ADMIN_PASSWORD` in your environment (or `docker-compose.yml`). The system will automatically create this admin account on startup.
|
||
|
||
**Method 2: Manual Promotion**
|
||
Register a normal account, then manually update the database row (`is_admin = 1`) or use a CLI script if available.
|
||
|
||
## <20> Docker Setup (Recommended for Raspberry Pi)
|
||
This is the best way to run the Web Dashboard on a server using Portainer.
|
||
|
||
### 1. Git Setup
|
||
1. Create a new Git repository (GitHub/GitLab).
|
||
- For local servers like Gitea, your URL will be something like `http://10.0.0.102:3000/thethreemagi/bookapp.git`.
|
||
2. Push this project code to the repository.
|
||
- **IMPORTANT:** Ensure `.env`, `token.json`, `credentials.json`, and the `data/` folder are in your `.gitignore`. Do **not** commit secrets to the repo.
|
||
|
||
### 2. Server Preparation (One-Time Setup)
|
||
|
||
Since secrets and database files shouldn't be in Git, you need to place them on your server manually.
|
||
|
||
1. **Authenticate Locally:** Run the app on your PC first (`python wizard.py`) to generate the `token.json` file (Google Login).
|
||
2. **SSH into your server** and create a folder for your app data:
|
||
```bash
|
||
mkdir -p /opt/bookapp # Or any other path you prefer
|
||
```
|
||
3. **Upload Files:** Use WinSCP or SCP to upload these two files from your PC to the folder you just created (e.g., `/opt/bookapp`):
|
||
- `token.json` (Generated in step 1)
|
||
- `credentials.json` (Your Google Cloud OAuth file)
|
||
The `data` subfolder, which stores your database and projects, will be created automatically by Docker when the container starts.
|
||
|
||
### 3. Portainer Stack Setup
|
||
1. Log in to **Portainer**.
|
||
2. Go to **Stacks** > **Add stack**.
|
||
3. Select **Repository**.
|
||
- **Repository URL:** `http://10.0.0.102:3000/thethreemagi/bookapp.git`
|
||
- **Compose path:** `docker-compose.yml`
|
||
4. **Enable Authentication:** Since your Gitea repository is private, you will need to provide credentials.
|
||
- Toggle on **Authentication**.
|
||
- **Username:** Your Gitea username (`thethreemagi`).
|
||
- **Password:** Use a **Personal Access Token** from Gitea, not your actual password.
|
||
- In Gitea, go to your **User Settings > Applications** and generate a new token with repository read access.
|
||
5. Under **Environment variables**, add the following:
|
||
- `HOST_PATH`: `/opt/bookapp` (The folder you created in Step 2)
|
||
- `GEMINI_API_KEY`: `<your-api-key>`
|
||
- `ADMIN_PASSWORD`: `<secure-password-for-web-ui>`
|
||
- `FLASK_SECRET_KEY`: `<random-string>`
|
||
- `FLASK_DEBUG`: `False` (Set to `True` only for troubleshooting)
|
||
6. Click **Deploy the stack**.
|
||
|
||
Portainer will pull the code from Git, build the image, and mount the secrets/data from your server folder.
|
||
|
||
### 4. Updating the App
|
||
To update the code:
|
||
1. Run the app **on your PC** first (using `python wizard.py` or `main.py`).
|
||
2. Push changes to Git.
|
||
3. In Portainer, go to your Stack.
|
||
4. Click **Editor** > **Pull and redeploy**.
|
||
|
||
### 📂 How to Manage Files (Input/Output)
|
||
The Docker setup uses a **Volume** to map the container's internal `/app/data` folder to a folder on your server. This path is defined by the `HOST_PATH` variable you set in Portainer.
|
||
|
||
- **To Add Personas/Fonts:** On your server, place files into the `${HOST_PATH}/data/personas/` or `${HOST_PATH}/data/fonts/` folders. The app will see them immediately.
|
||
- **To Download Books:** You can download generated EPUBs directly from the Web Dashboard.
|
||
- **To Backup:** Just create a backup of the entire `${HOST_PATH}` directory on your server. It contains the database, all projects, and generated books.
|
||
|
||
## 🐍 Native Web Setup (Alternative)
|
||
If you prefer to run the web app without Docker:
|
||
|
||
1. **Install Web Dependencies:**
|
||
```bash
|
||
pip install -r modules/requirements_web.txt
|
||
```
|
||
2. **Start the App:**
|
||
```bash
|
||
python -m modules.web_app
|
||
```
|
||
3. **Access:** Open `http://localhost:5000` in a browser.
|
||
|
||
## <20>️ Features
|
||
- **Interactive Wizard:** Create new books, series, or sequels. Edit existing blueprints with natural language commands.
|
||
- **Modular Architecture:** Logic is split into specialized modules for easier maintenance and upgrades.
|
||
- **Smart Resume:** If a run crashes, simply run the script again. It detects progress and asks to resume.
|
||
- **Marketing Assets:** Automatically generates a blurb, back cover text, and a cover image.
|
||
- **Rich Text:** Generates EPUBs with proper formatting (Bold, Italics, Headers).
|
||
- **Consistency Checker:** Scans the manuscript for plot holes and continuity errors.
|
||
- **Manual Editing:** Read and edit chapters directly in the browser; changes are preserved during file regeneration.
|
||
- **Metadata Sync:** Updates the "Story Bible" based on your manual edits to the text.
|
||
- **Dynamic Structure:** Automatically adapts the plot structure (e.g., "Hero's Journey" vs "Single Scene") based on the book length.
|
||
- **Series Support:** Automatically carries context, characters, and plot threads from Book 1 to Book 2, etc.
|
||
|
||
## 📂 Project Structure
|
||
|
||
### Core Files
|
||
- **`wizard.py`**: The interactive command-line interface for creating projects, managing personas, and editing the "Book Bible".
|
||
- **`main.py`**: The execution engine. It reads the Bible JSON and orchestrates the generation process using the modules.
|
||
- **`config.py`**: Central configuration for API keys, file paths, and model settings.
|
||
- **`utils.py`**: Shared utility functions for logging, JSON handling, and file I/O.
|
||
|
||
### Modules (`/modules`)
|
||
- **`ai.py`**: Handles authentication and connection to Google Gemini and Vertex AI.
|
||
- **`story.py`**: Contains the creative logic: enriching ideas, planning structure, and writing chapters.
|
||
- **`marketing.py`**: Generates cover art prompts, images, and blurbs.
|
||
- **`export.py`**: Compiles the final manuscript into DOCX and EPUB formats.
|
||
|
||
### Data Folders
|
||
- **`data/personas/`**: Stores author personas and writing samples.
|
||
- **`data/fonts/`**: Caches downloaded fonts for cover art.
|
||
|
||
## <20> Length Settings Explained
|
||
The **Length Settings** control not just the word count, but the **structural complexity** of the story.
|
||
|
||
| Type | Approx Words | Chapters | Description |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **Flash Fiction** | 500 - 1.5k | 1 | A single scene or moment. |
|
||
| **Short Story** | 5k - 10k | 5 | One conflict, few characters. |
|
||
| **Novella** | 20k - 40k | 15 | Developed plot, A & B stories. |
|
||
| **Novel** | 60k - 80k | 30 | Deep subplots, slow pacing. |
|
||
| **Epic** | 100k+ | 50 | Massive scope, world-building focus. |
|
||
|
||
> **Note:** This engine is designed for **linear fiction**. It does not currently support branching narratives like "Choose Your Own Adventure" books.
|
||
|
||
## 📂 Data Structure & File Dictionary
|
||
|
||
The application stores all data in the `data/` directory. This makes backup and migration easy.
|
||
|
||
### Folder Hierarchy
|
||
```text
|
||
data/
|
||
├── users/
|
||
│ └── {user_id}/ # User-specific data
|
||
│ └── {Project_Name}/ # Project Root
|
||
│ ├── bible.json # Project Source of Truth
|
||
│ └── runs/ # Generation History
|
||
│ └── run_{id}/ # Specific Job/Run
|
||
│ ├── web_console.log
|
||
│ └── Book_{N}_{Title}/ # Generated Book Artifacts
|
||
│ ├── manuscript.json
|
||
│ ├── tracking_events.json
|
||
│ ├── {Title}.epub
|
||
│ └── ...
|
||
├── personas/ # Global Author Personas
|
||
│ └── personas.json
|
||
├── fonts/ # Cached Google Fonts
|
||
└── style_guidelines.json # Global AI Writing Rules
|
||
```
|
||
|
||
### File Dictionary
|
||
|
||
| File | Scope | Description |
|
||
| :--- | :--- | :--- |
|
||
| **`bible.json`** | Project | The master plan. Contains the series title, author metadata, full character list, and the high-level plot outline for every book in the series. |
|
||
| **`manuscript.json`** | Book | **The Book.** A JSON array containing the raw text of every chapter written so far. Used to resume generation if interrupted. |
|
||
| **`events.json`** | Book | The structural outline (e.g., Hero's Journey beats) generated by the Architect. |
|
||
| **`chapters.json`** | Book | The detailed writing plan. Lists every chapter with its title, POV character, pacing, and estimated word count. |
|
||
| **`tracking_events.json`** | Book | The "Story So Far". Contains a cumulative summary of the plot and a log of key events to ensure continuity. |
|
||
| **`tracking_characters.json`** | Book | Tracks the current state of characters (e.g., "wearing a red dress", "lost an arm") to ensure visual consistency. |
|
||
| **`final_blueprint.json`** | Book | The final metadata state after the book is finished. Includes any new characters or plot points invented during writing. |
|
||
| **`usage_log.json`** | Book | A detailed report of AI token usage and estimated cost for this specific book. |
|
||
| **`cover_art_prompt.txt`** | Book | The exact prompt sent to the image generator (Imagen/Vertex) to create the cover. |
|
||
| **`{Title}.epub`** | Book | The compiled eBook file, ready for Kindle/Apple Books. |
|
||
| **`{Title}.docx`** | Book | The compiled Word document for editing. |
|
||
|
||
## 📖 JSON Data Schemas
|
||
|
||
Details on the internal structure of key data files.
|
||
|
||
### `bible.json`
|
||
Located at the root of the project folder.
|
||
```json
|
||
{
|
||
"project_metadata": {
|
||
"title": "Series Title",
|
||
"author": "Author Name",
|
||
"genre": "Sci-Fi",
|
||
"is_series": true,
|
||
"style": {
|
||
"tone": "Dark",
|
||
"pov_style": "Third Person Limited"
|
||
}
|
||
},
|
||
"characters": [
|
||
{
|
||
"name": "John Doe",
|
||
"role": "Protagonist",
|
||
"description": "Physical and personality details..."
|
||
}
|
||
],
|
||
"books": [
|
||
{
|
||
"book_number": 1,
|
||
"title": "Book One Title",
|
||
"manual_instruction": "High-level plot summary...",
|
||
"plot_beats": ["Beat 1", "Beat 2"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### `manuscript.json`
|
||
Located in each `Book_X` folder.
|
||
```json
|
||
[
|
||
{
|
||
"num": 1,
|
||
"title": "Chapter Title",
|
||
"pov_character": "John Doe",
|
||
"content": "# Chapter 1\n\nThe raw markdown text of the chapter..."
|
||
}
|
||
]
|
||
```
|
||
|
||
### `tracking_characters.json`
|
||
Located in each `Book_X` folder. Updates dynamically.
|
||
```json
|
||
{
|
||
"Character Name": {
|
||
"descriptors": ["Blue eyes", "Tall"],
|
||
"likes_dislikes": ["Loves coffee"],
|
||
"last_worn": "Red dress (Ch 4)",
|
||
"major_events": ["Injured leg in Ch 2"]
|
||
}
|
||
}
|
||
``` |