Skip to content

Latest commit

 

History

History
235 lines (190 loc) · 9.13 KB

README.md

File metadata and controls

235 lines (190 loc) · 9.13 KB

📖 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.