diff --git a/READMEEN.md b/READMEEN.md new file mode 100644 index 0000000..e08f366 --- /dev/null +++ b/READMEEN.md @@ -0,0 +1,231 @@ +# πŸ“– Automatic Novel Generation Tool + +>- 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 + +
+ +✨ **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](#-environment-preparation) +2. [Project Structure](#-project-structure) +3. [Configuration Guide](#βš™οΈ-configuration-guide) +4. [Run Instructions](#πŸš€-run-instructions) +5. [User Guide](#πŸ“˜-user-guide) +6. [FAQ](#❓-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](https://github.com) or clone the repository: + ```bash + git clone https://github.com/YILING0013/AI_NovelGenerator + ``` + + +2. **Install build tools (optional)** + - If some packages fail to install, visit [Visual Studio Build Tools](https://visualstudio.microsoft.com/zh-hans/visual-cpp-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: + ```bash + cd AI_NovelGenerator + ``` + - Install project dependencies: + ```bash + pip install -r requirements.txt + ``` + - After installation run the main program: + ```bash + python main.py + ``` + +If some dependencies are still missing, manually run: +```bash +pip install +``` +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`) +```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 +```bash +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**: +```bash +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: +> ```bash +> 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.