bookapp/README.md

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

1. **Register:** Create a normal account via the Web UI (`/register`).
2. **Promote:** Run the included script to promote your user to Admin:
   ```bash
   python make_admin.py <your_username>
   ```
3. **Access:** Log in and click the "Admin" link in the navigation bar.

## <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>`
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).
- **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/projects/`**: Stores your book projects.
- **`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.

## 📂 Output Folder Structure
- **Project_Name/**: A folder created based on your book or series title.
  - **bible.json**: The master plan containing characters, settings, and plot outlines for the series.
  - **runs/**: Contains generation attempts.
    - **bible/**:
      - **run_#/**: Each generation attempt gets its own numbered folder.
        - **Book_1_Title/**: Specific folder for the generated book.
          - **final_blueprint.json**: The final plan used for this run.
          - **manuscript.json**: The raw text data.
          - **Book_Title.epub**: The final generated ebook.
          - **cover.png**: The AI-designed cover art.