NovelForge AI

NovelForge AI is a multi-agent long-form fiction production system. The repository includes a FastAPI backend, a Next.js frontend, and an engineered workflow for planning, chapter generation, scheduling, and style guidance.

中文文档请见 README_CN.md.

Project Status

NovelForge AI focuses on turning long-form fiction production into a structured, repeatable workflow for planning, drafting, reviewing, and style adaptation.

• Production-oriented multi-agent writing workflow
• Author template and style guidance workflow
• Open-source-safe repository boundaries for data, models, and secrets

Core Capabilities

• Create, list, export, and delete novel projects.
• Create chapters, run scheduling workflows, track status, and retry or roll back work.
• Maintain an author style template library and recommendation flow.
• Provide chapter QA checks, graph views, and progress tracking.
• Support DashScope cloud models.

Tech Stack

• Backend: FastAPI, Pydantic, Loguru
• Frontend: Next.js 16, React 19, TypeScript
• LLM: DashScope (required)
• Retrieval and style indexing: txtai, sentence-transformers (optional)

Repository Layout

.
├── src/                # FastAPI services, scheduler, and core business logic
├── frontend/           # Next.js frontend
├── scripts/            # Startup helpers, public sample data, and utility scripts
├── tests/              # Python tests
├── data/               # Local data directory (public release should only keep safe examples)
├── requirements.txt    # Python dependencies and optional enhancement notes
└── .env.example        # Backend environment template

Requirements

• Python 3.11+
• Node.js 20+
• npm 10+
• DashScope API key

Quick Start

1. Install backend dependencies

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

If you want style indexing enhancements, install the optional packages:

pip install txtai sentence-transformers

2. Install frontend dependencies

cd frontend
npm ci
cd ..

3. Configure environment variables

Copy the root template and fill in your own secrets:

cp .env.example .env

The root .env file is read by the backend and supports the following settings:

• DASHSCOPE_API_KEY: required
• DASHSCOPE_MODEL: optional, default qwen3-max
• DASHSCOPE_ENABLE_THINKING: optional thinking mode toggle
• WRITING_ENV: optional runtime profile (dev, prod, or test)
• BACKEND_HOST / BACKEND_PORT / BACKEND_RELOAD: backend bind and reload settings
• FRONTEND_HOST / FRONTEND_PORT: used by local helpers and default inference
• CORS_ALLOW_ORIGINS: comma-separated backend CORS allow list The frontend supports the following optional environment variables in frontend/.env.local:

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_API_CANDIDATES=http://127.0.0.1:8000,http://localhost:8001
NEXT_PUBLIC_API_DISCOVERY=true
NEXT_PUBLIC_API_DISCOVERY_PORTS=8000,8001

4. Start the backend

source .venv/bin/activate
python -m uvicorn src.main:app --host 127.0.0.1 --port 8000 --reload

After startup, you can access:

• API root: http://localhost:8000/
• OpenAPI docs: http://localhost:8000/docs

5. Start the frontend

cd frontend
npm run dev -- -p 3000

Open http://localhost:3000 in your browser.

6. One-command startup script

The repository includes scripts/start_services.sh. By default it only checks for occupied ports and prints guidance. It does not kill existing processes unless KILL_EXISTING_SERVICES=true is explicitly set.

Example:

BACKEND_HOST=127.0.0.1 FRONTEND_HOST=127.0.0.1 ./scripts/start_services.sh

If you hit a port conflict, you can switch ports directly:

BACKEND_PORT=8010 FRONTEND_PORT=3010 ./scripts/start_services.sh

Dependency Notes

requirements.txt is structured as core runtime dependencies plus optional enhancement notes.

• Core runtime dependencies: enough to start the FastAPI service, call DashScope, and use the standard API flow.
• Optional enhancements: only needed for vector indexing and style retrieval workflows.
• Test dependencies: used by contributors running pytest.

Testing

At minimum, run:

source .venv/bin/activate
pytest

For a smoke-style API verification run:

python src/smoke_test.py

Note: src/smoke_test.py starts services and hits generation endpoints, so it requires valid model settings and credentials.

Data and Model Boundaries

For the public release, keep the following boundaries:

• Do not commit real .env files, cloud credentials, or account secrets.
• Do not commit private corpora, copyrighted source text, or runtime business data.
• Do not commit local model weights, index caches, or training artifacts.
• Keep only minimal public-safe sample data. All private data should be prepared locally by the user.

If you need private reference text, style DNA files, indexes, or local models, place them locally and ensure they stay ignored by Git.

This open-source edition no longer provides any external-site novel crawling capability. Reference text should come from user-managed local data or the public-safe sample generated by scripts/download_reference_novel.py.

FAQ

Missing DASHSCOPE_API_KEY

Check that the root .env exists and contains a valid DASHSCOPE_API_KEY.

Frontend cannot reach backend

Check the following first:

• Whether the backend is actually running on 8000 or 8001
• Whether NEXT_PUBLIC_API_BASE_URL is explicitly set in frontend/.env.local
• Whether the browser can open http://localhost:8000/openapi.json

Contributing

Contributions via Issues and Pull Requests are welcome. Please read CONTRIBUTING.md before submitting changes.

License

This project is released under the MIT License. See LICENSE for details.