📖 Automatic Novel Generation Tool

中文文档 | English

Currently I don't have much energy to maintain this project. The project brings no revenue, and with graduation approaching I have many other priorities. If time permits in the future I may consider a refactor using newer technologies. — 2025/09/24

Update (2026/03/09): This project will be refactored soon, featuring modern implementations and fresh creative concepts.

✨ Core Features ✨

Module	Key Capabilities
🎨 Novel Setting Workshop	Worldbuilding / Character Design / Plot Blueprint
📖 Intelligent Chapter Generation	Multi-stage generation to ensure plot coherence
🧠 State Tracking System	Character development trajectory / Foreshadowing management
🔍 Semantic Search Engine	Vector-based long-term context consistency
📚 Knowledge Base Integration	Supports local document references
✅ Automatic Proofreading	Detects plot contradictions and logical conflicts
🖥 Visual Workbench	Full-process GUI for configuration / generation / proofreading

A multifunctional novel generator built on large language models. Helps you efficiently create long-form stories with consistent settings and rigorous logic.

---

📑 Table of Contents

1. Environment Preparation
2. Project Structure
3. Configuration Guide
4. Run Instructions
5. User Guide
6. FAQ

---

🛠 Environment Preparation

Ensure the environment meets the following requirements:

• Python 3.9+ (recommended 3.10–3.12)
• pip package manager
• Valid API keys:
  • Cloud services: OpenAI / DeepSeek, etc.
  • Local services: Ollama or other OpenAI-compatible interfaces

---

📥 Installation

1. Download the project

   • Download the project ZIP from GitHub or clone the repository:

     git clone https://github.com/YILING0013/AI_NovelGenerator

2. Install build tools (optional)

   • If some packages fail to install, visit Visual Studio Build Tools to download and install C++ build tools required by some modules.
   • By default the installer includes MSBuild only; make sure to select C++ Desktop Development from the workload list.

3. Install dependencies and run

   • Open a terminal and change to the project directory:

     cd AI_NovelGenerator

   • Install project dependencies:

     pip install -r requirements.txt

   • After installation run the main program:

     python main.py

If some dependencies are still missing, manually run:

pip install <package-name>

to install them.

🗂 Project Structure

novel-generator/
├── main.py                      # Entry file, runs the GUI
├── consistency_checker.py       # Consistency checks to prevent plot conflicts
|—— chapter_directory_parser.py  # Directory parsing
|—— embedding_adapters.py        # Embedding interface wrappers
|—— llm_adapters.py              # LLM interface wrappers
├── prompt_definitions.py        # AI prompt templates
├── utils.py                     # Utility functions and file operations
├── config_manager.py            # Configuration manager (API keys, base URL)
├── config.json                  # User configuration (optional)
├── novel_generator/             # Core chapter generation logic
├── ui/                          # Graphical user interface
└── vectorstore/                 # (Optional) Local vector DB storage

---

⚙️ Configuration Guide

📌 Basic configuration (config.json)

{
   "api_key": "sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "base_url": "https://api.openai.com/v1",
   "interface_format": "OpenAI",
   "model_name": "gpt-4o-mini",
   "temperature": 0.7,
   "max_tokens": 4096,
   "embedding_api_key": "sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "embedding_interface_format": "OpenAI",
   "embedding_url": "https://api.openai.com/v1",
   "embedding_model_name": "text-embedding-ada-002",
   "embedding_retrieval_k": 4,
   "topic": "The protagonist of Star Rail travels to Genshin Impact's Teyvat continent, saves it, and develops complex relationships with its characters.",
   "genre": "Fantasy",
   "num_chapters": 120,
   "word_number": 4000,
   "filepath": "D:/AI_NovelGenerator/filepath"
}

🔧 Explanation

1. Generation model configuration

   • api_key: API key for the LLM service
   • base_url: API endpoint (for local services use the Ollama address)
   • interface_format: Interface mode
   • model_name: Main generation model (e.g., gpt-4, claude-3)
   • temperature: Creativity parameter (0–1, higher is more creative)
   • max_tokens: Maximum model response length

2. Embedding model configuration

   • embedding_model_name: Embedding model name (e.g., Ollama's nomic-embed-text)
   • embedding_url: Service endpoint
   • embedding_retrieval_k: Number of nearest neighbors to retrieve

3. Novel parameters

   • topic: Core story theme
   • genre: Genre
   • num_chapters: Total number of chapters
   • word_number: Target words per chapter
   • filepath: Path to save generated files

---

🚀 Run Instructions

Method 1 — Run with Python

python main.py

This launches the GUI for interactive use.

Method 2 — Build an executable

If you want to run the tool on machines without Python, package it with PyInstaller:

pip install pyinstaller
pyinstaller main.spec

After packaging an executable (e.g., main.exe on Windows) will appear in the dist/ folder.

---

📘 User Guide

1. After launching the app, fill in the basic parameters:

   • API Key & Base URL (e.g., https://api.openai.com/v1)
   • Model name (e.g., gpt-3.5-turbo, gpt-4o)
   • Temperature (0–1, controls creative variance)
   • Topic (e.g., "AI uprising in a post-apocalyptic world")
   • Genre (e.g., "Sci-fi" / "Fantasy" / "Urban Fantasy")
   • Number of chapters and words per chapter (e.g., 10 chapters × ~3000 words)
   • Save path (create a new output folder for results)

2. Click "Step1. Generate Settings"

   • The system will generate, based on topic/genre/chapter count:
     • Novel_setting.txt: Worldbuilding, characters, trigger points and foreshadowing.
   • You can view or edit these settings after generation.

3. Click "Step2. Generate Directory"

   • The system will use Novel_setting.txt to produce:
     • Novel_directory.txt: Chapter titles and short prompts.
   • You can review and modify chapter titles and descriptions.

4. Click "Step3. Generate Chapter Draft"

   • Before generating a chapter you can:
     • Set the chapter number (e.g., 1)
     • Provide chapter-specific guidance in the "This chapter guidance" box
   • When you generate a chapter the system will:
     • Read prior settings, Novel_directory.txt, and finalized chapters
     • Use vector retrieval to recall relevant context for coherence
     • Produce an outline (outline_X.txt) and chapter text (chapter_X.txt)
   • You can view and edit the draft in the editor pane.

5. Click "Step4. Finalize Current Chapter"

   • The system will:
     • Update the global summary (global_summary.txt)
     • Update character states (character_state.txt)
     • Update the vector store (so future chapters can use the latest info)
     • Update major plot points (e.g., plot_arcs.txt)
   • After finalizing you will see the finalized text in chapter_X.txt.

6. Consistency check (optional)

   • Click the "[Optional] Consistency Proofread" button to scan the latest chapter for conflicts (character logic, plot contradictions, etc.).
   • If conflicts are detected, detailed messages will appear in the log area.

7. Repeat steps 4–6 until all chapters are generated and finalized.

Vector retrieval tips:

1. Explicitly set the embedding interface and model name.
2. For local Ollama embeddings start the Ollama service first:

   ollama serve  # Start the service
   ollama pull nomic-embed-text  # Download/enable the model

3. Clear the vectorstore directory after switching embedding models.
4. For cloud embeddings ensure the API permissions are enabled.

---

❓ FAQ

Q1: Expecting value: line 1 column 1 (char 0)

This error usually indicates the API did not return valid JSON—sometimes an HTML error page or other unexpected content was returned.

Q2: HTTP/1.1 504 Gateway Timeout?

Check the stability of the API endpoint and network connectivity.

Q3: How do I switch Embedding providers?

Enter the new provider settings in the GUI fields for embedding configuration.

---

If you have further questions or feature requests, please open an issue on the project repository.