pulpgen

# 📚 pulpgen: Your Ghostwriter in the Machine - An AI Novel Drafting Agent


---

**What is it?** `pulpgen` is a command-line tool that uses AI (Google Gemini) to automatically write a complete first-draft novel based on your idea/prompt. It handles outlining, chapter writing, and interactive AI-assisted editing.

![screenshot](screenshot.png)

---

## ⚡ Quick Start

1.  **Install:** Requires Python 3.13+ and `uv`.
    ```bash
    # Clone or download the code first
    cd pulpgen
    uv sync
    ```
2.  **API Key:** Create a `.env` file in the `pulpgen` directory with `GEMINI_API_KEY=YOUR_KEY_HERE`
    API Key can be created in Google AI Studio: https://aistudio.google.com/app/apikey

4.  
    ```bash
    # Example using a prompt file:
    uv run python pulpgen.py --prompt your_idea.txt
    # Or run without --prompt to enter idea interactively
    ```
5.  **Run (Resume Project):**
    ```bash
    uv run python pulpgen.py --resume path/to/your/project_folder
    ```
6.  **Output:** Finds/creates a project folder (like `YYYYMMDD-slug-uuid`) containing XML state files and the final manuscript in `final.html`.

---


## Usage

Launch the `pulpgen` agent from your terminal within the project directory:

```bash
uv run python pulpgen.py [OPTIONS]
```

**Command-Line Options:**

*   `--resume FOLDER_PATH`: Point to an existing project folder (e.g., `20240315-space-opera-saga-f3a4b1c9`) to continue a previously started job.
*   `--prompt FILE_PATH`: Provide the path to a `.txt` file containing your book idea. This is only used when starting a *new* project (ignored if `--resume` is used).

## Project Files

`pulpgen` keeps its work organized in a dedicated project folder (e.g., `20240315-robot-romance-a1b2c3d4`):

*   **`YYYYMMDD-slug-uuid/` (Project Folder):** The main case file, named with the date, a slugified title, and a unique ID.
*   **`outline.xml`:** The initial blueprint. Contains metadata (title, synopsis, your idea), character profiles, and chapter summaries gen