Final changes and update
This commit is contained in:
129
README.md
129
README.md
@@ -17,12 +17,11 @@ If you prefer the command line:
|
||||
## 🛡️ 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.
|
||||
**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.
|
||||
|
||||
## <20> Docker Setup (Recommended for Raspberry Pi)
|
||||
This is the best way to run the Web Dashboard on a server using Portainer.
|
||||
@@ -63,6 +62,7 @@ Since secrets and database files shouldn't be in Git, you need to place them on
|
||||
- `GEMINI_API_KEY`: `<your-api-key>`
|
||||
- `ADMIN_PASSWORD`: `<secure-password-for-web-ui>`
|
||||
- `FLASK_SECRET_KEY`: `<random-string>`
|
||||
- `FLASK_DEBUG`: `False` (Set to `True` only for troubleshooting)
|
||||
6. Click **Deploy the stack**.
|
||||
|
||||
Portainer will pull the code from Git, build the image, and mount the secrets/data from your server folder.
|
||||
@@ -100,6 +100,9 @@ If you prefer to run the web app without Docker:
|
||||
- **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.
|
||||
|
||||
@@ -118,7 +121,6 @@ If you prefer to run the web app without Docker:
|
||||
- **`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.
|
||||
|
||||
@@ -135,14 +137,105 @@ The **Length Settings** control not just the word count, but the **structural co
|
||||
|
||||
> **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.
|
||||
## 📂 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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user