commit fc44a7834ab36da42f41de501cb053378b891531 Author: Mike Wichers Date: Tue Feb 3 10:11:58 2026 -0500 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..d449cdc --- /dev/null +++ b/README.md @@ -0,0 +1,141 @@ +# 📚 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 ` 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 + ``` +3. **Access:** Log in and click the "Admin" link in the navigation bar. + +## � 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: + ```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:** `` + - **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`: `` + - `ADMIN_PASSWORD`: `` + - `FLASK_SECRET_KEY`: `` +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:** + ```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). +- **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. + +## � 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. \ No newline at end of file