📚 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:

   python make_admin.py <your_username>
   

3. Access: Log in and click the "Admin" link in the navigation bar.

<EFBFBD> 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).
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:

   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: <your-git-repo-url>
   • Compose path: docker-compose.yml
4. 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>
5. 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:

   pip install -r modules/requirements_web.txt
   

2. Start the App:

   python -m modules.web_app
   

3. Access: Open http://localhost:5000 in a browser.

<EFBFBD>️ 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.

<EFBFBD> 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.