thethreemagi/bookapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Mike Wichers
2026-02-03 10:11:58 -05:00
commit fc44a7834a
1 changed files with 141 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
README.md Normal file
View File

@@ -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 <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).
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:** `<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:**
```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.