# 📚 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.

## � 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_USERNAME`: `admin` (Or your preferred username)
   - `ADMIN_PASSWORD`: `<secure-password-for-web-ui>`
   - `FLASK_SECRET_KEY`: `<random-string>`
   - `FLASK_DEBUG`: `False` (Set to `True` only for troubleshooting)
   
   **Optional (Advanced / Vertex AI):**
   - `GCP_PROJECT`: Your Google Cloud Project ID (Required for Imagen 3/Vertex AI).
   - `GCP_LOCATION`: `us-central1` (Default).
   - `MODEL_LOGIC`: Override the logic model (e.g., `models/gemini-1.5-pro-latest`).
   - `MODEL_WRITER`: Override the writer model.
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.

## �️ 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.

## � 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"]
  }
}
```