AI_NovelGenerator: a Python GUI for long-form AI novels with state tracking

What AI_NovelGenerator solves, and who it is actually for

Long-form generation breaks down at the seams. A model writes chapter one well, then drifts: a character's eye colour changes, a planted object never returns, and the outline stops constraining anything. AI_NovelGenerator is built around that failure. Its README lists a State Tracking System for character development trajectory and foreshadowing management, plus a Semantic Search Engine that retrieves vector-based long-term context, and a consistency checker file, consistency_checker.py, that the project describes as detecting plot contradictions and logical conflicts. The intended user is a writer who is willing to run a Python program, hold an API key from OpenAI, DeepSeek, Gemini, Azure or an OpenAI-compatible local server such as Ollama, and pay per token. The GUI is built with customtkinter, so it is a desktop application, not a web service. Anyone expecting a hosted editor with a subscription and no local setup is not the audience.

How the chapter pipeline and vector store fit together

The repository layout shows the split clearly. main.py runs the GUI, ui/ holds the interface, and novel_generator/ contains the core chapter generation logic. Around that core sit llm_adapters.py and embedding_adapters.py, which wrap the model and embedding interfaces so the rest of the code does not care which provider you configured. prompt_definitions.py and prompt_definitions_en.py hold the prompt templates, and chapter_directory_parser.py parses the chapter directory that the outline step produces. The data flow implied by the config is a routing table: choose_configs assigns different jobs to different models. In the README example, architecture_llm and chapter_outline_llm both point at a Gemini preset, prompt_draft_llm and consistency_review_llm point at a cheaper DeepSeek preset, and final_chapter_llm points at a larger one with max_tokens 32768. That is a deliberate cost design: plan and review on the cheap model, write the final prose on the expensive one. Embeddings go to a separate provider block, and vectorstore/ is described as optional local vector DB storage, backed by chromadb and langchain-chroma in requirements.txt. The README also mentions a Knowledge Base Integration for local document references, which is how you feed setting notes back into retrieval.

Installing AI_NovelGenerator and running the first chapter

The README asks for Python 3.9 or newer, with 3.10 to 3.12 recommended, plus pip and a valid API key. Clone the repository and enter it:

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

A virtual environment is optional but the README documents it, including the fallback when python is not on PATH:

python -m venv .venv
# if that doesn't work, try:
# python3 -m venv .venv

Activate it per platform, then install the pinned dependencies:

# On Windows:
.venv/Scripts/activate

# On Linux/Mac:
source .venv/bin/activate

pip install -r requirements.txt

requirements.txt pins chromadb==1.0.20, langchain==0.3.27, langchain-openai==0.3.32, openai==1.106.1, customtkinter==5.2.2 and numpy==2.3.2, among others. The README warns that some modules need C++ build tools and points to Visual Studio Build Tools, where you must select C++ Desktop Development rather than the default MSBuild-only install. Then start the GUI:

python main.py

Configuration lives in config.json, with config.example.json as the complete example. Copy it and fill in the preset you intend to use; the README shows presets keyed by name, each carrying api_key, base_url, interface_format, model_name, temperature, max_tokens and timeout:

{
  "last_llm_config_name": "DeepSeek V4 Flash",
  "llm_configs": {
    "DeepSeek V4 Flash": {
      "api_key": "",
      "base_url": "https://api.deepseek.com",
      "interface_format": "DeepSeek",
      "model_name": "deepseek-v4-flash",
      "temperature": 0.7,
      "max_tokens": 8192,
      "timeout": 600
    }
  }
}

Note that the README's explanation section still refers to older flat keys such as embedding_model_name, embedding_url and embedding_retrieval_k, while the JSON example groups embeddings under embedding_configs with retrieval_k. Treat the example file as authoritative and check the key names there before editing by hand. Once configured, the workbench walks through Novel Setting Workshop (worldbuilding, characters, plot blueprint), then chapter generation, then proofreading. The README does not document a dry-run mode, so the first real spend happens when you generate.

Where the design costs you: provider drift, pinned versions, and no documented rollback

The config example names models such as deepseek-v4-flash, deepseek-v4-pro and gemini-3.5-flash. Those strings are passed straight to the provider, so when a vendor renames or retires a model, your preset stops working and the fix is a manual edit of config.json. Nothing in the README describes validation at startup. Pinning chromadb==1.0.20 and langchain==0.3.27 keeps installs reproducible, but it also means upgrading one of them is your problem, not the project's. The consistency checker is the feature most likely to disappoint: the README says it detects plot contradictions, and it does so by sending text to the consistency_review_llm you routed. It is another model call, not a formal verifier, so it can miss contradictions and can report ones that are not there. Cost is the other constraint. Every chapter involves an outline call, a draft call, a final call and a review call, plus embedding calls for retrieval, against your own key. The README does not document rollback or versioning of generated chapters, so if a bad regeneration overwrites good prose, recovery is on you. Finally, the README states the author has limited time for the project and that a refactor with only the main framework done is being developed on a dev branch. The last push to main was on 2026-08-01.

How it differs from NovelAI and from a plain chat window

The search results around this project mostly point at NovelAI, which is a hosted service with its own models, its own subscription and no local installation. NovelAI gives you a polished editor and no API keys to manage; AI_NovelGenerator gives you a local customtkinter workbench and makes you supply the models. The practical difference is control and cost shape. With AI_NovelGenerator you can route planning to a cheap model and final prose to an expensive one, point base_url at a local Ollama instance, and keep the vector store in vectorstore/ on your own disk. With NovelAI you cannot swap the model, and your manuscript lives on someone else's server. The second comparison is a plain chat window. Pasting chapter summaries into a chat is free and needs no install, but nothing tracks character state between sessions and nothing retrieves the relevant earlier passage automatically. That retrieval step, plus the foreshadowing table, is the actual product here. If you are happy re-explaining your world every session, you do not need this.

Licence and the cost of staying current

The repository is licensed AGPL-3.0. For someone running main.py locally to write a novel, that is unremarkable. It matters if you plan to host a modified version as a network service, because the AGPL's network clause reaches users who interact with it over a network, not just those who receive a copy. If you intend to build a paid hosted writing tool on this code, read the licence text and take your own advice; this is a description of the licence, not legal advice. The dependency list is narrow enough to audit: chromadb, langchain, langchain-openai, langchain-chroma, openai, google-genai, azure-ai-inference, customtkinter, nltk, numpy, protobuf, requests and wheel. Upgrade cost is dominated by that pinning. Moving to a newer chromadb or langchain means testing the embedding adapters and the vector store yourself, and the README gives no compatibility matrix to work from.

Editorial conclusion

AI_NovelGenerator suits writers and Python users who already pay for an OpenAI-compatible or Gemini API and want a local GUI that keeps character state and foreshadowing across chapters, rather than a hosted subscription editor. It is the wrong choice if you want a zero-config web app, a free unlimited writer, or a tool with a documented rollback path, because the README does not describe one. Before committing, verify that chromadb==1.0.20 and langchain==0.3.27 install cleanly on your Python version, that your embedding endpoint accepts the model_name you configure, and that the dev branch mentioned in the README contains the refactor you expect.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. YILING0013/AI_NovelGenerator on GitHub