YILING0013/AI_NovelGenerator

AI Novel Generator is a writing workspace that runs on your computer. Write by hand or ask AI for a candidate, then review, edit, and save it. Characters, factions, relationships, story plans, and prose live in one project, with a progress panel to guide the next step.

Thanks to members of the LINUX DO community for providing community-run API resources that supported generation workflow testing during development.

These clips follow the fictional project Tidal Archives from creation to its first saved chapter, recorded in the current application. The demo uses preset model responses to show the workflow, not model quality.

01 · Create a novel: idea → story direction → review and save

The main route below uses Windows, PowerShell, and MongoDB in Docker. Installation downloads dependencies; AI generation also requires a model service you configure yourself.

Install Python 3.13, Node.js 24, Git, and Docker Desktop. Start Docker Desktop and wait for its engine to run. Check that python --version, node --version, and docker compose version print their versions. The frontend requires Node.js 20.9 or later.

git clone https://github.com/YILING0013/AI_NovelGenerator.git
cd AI_NovelGenerator
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
cd frontend
npm ci
cd ..

Saving arcs, chapters, and related records requires MongoDB multi-document transactions, so a replica set is required. The bundled compose.mongodb.yaml runs MongoDB 8.0 as a single-node replica set named rs0, available at 127.0.0.1:27017.

First check that another service is not using 27017 (on Windows: netstat -ano | findstr :27017). An existing standalone Windows MongoDB service cannot simply be mixed with this Docker instance or started on the same port. If you already have a writable replica set, use its connection address directly. Back up an existing standalone database before planning its conversion or a separate port. Do not delete volumes or recreate existing databases to resolve a port conflict.

From the project root:

docker compose -f compose.mongodb.yaml up -d
docker compose -f compose.mongodb.yaml exec mongodb mongosh

Only when using a new, empty data volume for the first time, run this once inside the MongoDB shell:

rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })
exit()

Back in PowerShell:

docker compose -f compose.mongodb.yaml ps

Wait until mongodb is healthy, meaning it is a writable primary. An uninitialized instance may show unhealthy; that is not a reason to erase its data. Subsequent starts need only up -d; do not initialize an existing replica set again.

Data persists in the named volumes novel-generator-mongodb-data and novel-generator-mongodb-config. docker compose -f compose.mongodb.yaml stop only stops the service. Do not use down -v to remove these data volumes.

Double-click start.bat in the project root and start both services in the desktop launcher. It uses the installed .venv; production mode builds the frontend on first use and after relevant code or configuration changes. start.bat does not install dependencies or MongoDB.

Open http://127.0.0.1:3300 and go to Settings → Database Configuration. Choose “Replace connection,” enter and confirm the URI, then fill in the database name and save the settings:

The configuration file defaults mongo_transaction_mode to required. Keep this value; no manual edit is needed for a fresh installation.

Once the connection checks pass, you can create a novel. The backend defaults to http://127.0.0.1:8200. For a port conflict, identify the existing service before changing ports in the launcher. Closing the launcher stops the services it started; Docker manages MongoDB separately.

Under Settings → LLM Provider Management, add and enable your service type, endpoint, API key, and model, then save. Choose and save a global default Provider under Novel Generation Workflow Configuration. Built-in workflows provide a starting point; individual nodes can also select their own model. The endpoint must support the selected adapter, parameters depend on the provider, and the provider charges for model usage.

After creating a novel, follow Writing Progress to prepare core material, plan volumes and their participants, then detail arcs, scenes, and chapter plans. Review generated results before saving, or write the manuscript directly. Chapter records help review changes to characters, relationships, items, and world rules.

.\.venv\Scripts\python.exe main.py

cd frontend
$env:NEXT_PUBLIC_API_BASE = "http://127.0.0.1:8200"
npm run build
npm run start -- --hostname 127.0.0.1 --port 3300

The character and faction graph brings relationships and membership together. Filter the graph, zoom, drag nodes, and inspect their details.

The interface supports Chinese and English, light and dark themes, and responsive layouts. These captures show the Chinese desktop interface. Built with Next.js 16, React 19, HeroUI, React Flow, FastAPI, PyMongo, and PySide6.

Current main is the rewritten application; the previous version is preserved on old. Their data structures differ, so use separate databases. Book archives now export v14; older application versions cannot read these archives.

The default user directory is user_data/ under the project. Set NOVEL_GENERATOR_USER_DATA_DIR to use a separate directory.

• Before updating: verify pending saves, export unsaved drafts, stop the application, and back up MongoDB and user files separately. Copying user_data or exporting one book is not a complete backup. Update the code, reinstall dependencies, and rebuild the frontend yourself.
• At startup: migration handles supported old file locations and data only. Recognized, unchanged built-in workflows using the latest default revision are backed up and upgraded; custom workflows and pinned older revisions are preserved. The application does not install MongoDB, download new code, or convert arbitrary historical databases.
• If migration fails: keep the original files, backups, and migration records, and resolve the reported conflict. Do not delete user_data or the database to retry. Generation recovery depends on the original backend process and page; refreshing or restarting does not guarantee recovery, and retrying a model call may incur another charge.

This application is intended for local use and has no public-facing user authentication. The bundled MongoDB has no password and binds only to the loopback address. Do not expose either directly to the internet. AI operations send the necessary story context to your configured model service.

Report problems through Issues, including the version, environment, reproduction steps, and redacted screenshots or logs. Read the contribution guide before contributing. Licensed under GNU AGPL v3.0.