Local-first, open-source novel → series comic generator.
_{Built on the free Agnes multimodal API — no GPU, no paid key, grind your novel into comics.}

"Grind your novel into comics."

Inkstone is a local-first, open-source novel → series comic generator. It reads a local txt novel and, through the free Agnes multimodal API, produces comic pages with cross-panel character consistency — exported as PDF / PNG. No GPU, no paid plan: just one free API key. Image generation sits behind a pluggable ImageProvider, so you can switch to any OpenAI-compatible endpoint with a single line.

• Features
• Why Inkstone
• Quick Start
• Gallery
• Web UI
• Configuration
• How it works
• Resources
• Contributing

• Free & local-first — one AGNES_API_KEY, no GPU, no paid plan.
• Agnes-native multimodal — agnes-2.0-flash for scripting, agnes-image-2.1-flash for t2i and i2i consistency.
• Pluggable ImageProvider — Agnes by default; one line switches to any OpenAI-compatible endpoint.
• Character consistency engine — L1 prompt hard-description + L2 reference img2img, the robust path under no-GPU. An optional L3 PIL/OpenCV face overlay exists but is off by default (it deforms stylized faces when pose/lighting differ, so it's opt-in via INKSTONE_L3=1).
• Reliability layer — token-bucket rate limiting, exponential-backoff retries, and error collection against 429/503.
• Resumable long-form runs — chapter-split generation with a persisted state.json checkpoint.

Every novel-to-comic tool we surveyed in 2026 runs on a paid model — Gemini, OpenAI, Doubao, Wenxin, or Claude. Inkstone is built differently: it is Agnes-native and zero-cost, the one combination no other open-source generator occupies.

Inkstone is an independent implementation, not a fork — inspired by lcy362/agnes-video-generator (MIT) but carrying none of its source tree. Attribution is recorded in NOTICE.

An honest trade-off. Free, cloud-only Agnes with no GPU caps how far character consistency can reach. The strongest approaches (IP-Adapter / InsightFace) need a local GPU running SDXL/Flux — incompatible with Inkstone's zero-cost premise. So Inkstone trades perfect consistency for zero-cost + no-GPU + out-of-the-box, using L1+L2+L3 as the best feasible strategy. Stated plainly, not hidden.

Prerequisites: Python 3.10+, conda, and a free Agnes API key (Free Access tier).

# 1. Create & activate the conda environment
conda create -n inkstone python=3.12 -y
conda activate inkstone
# Verify the env is active — `which python` must point inside the env
# (e.g. .../envs/inkstone/bin/python). If it still shows /opt/homebrew/... or
# /usr/bin, run `conda init zsh` and open a new terminal, then reactivate.

# 2. Install Inkstone (runtime + dev/test tooling)
python -m pip install -e ".[dev]"

# 3. Provide your API key
cp .env.example .env
#    then open .env and set AGNES_API_KEY=sk-xxx

Generate your first panel — the runnable example lives at examples/first_panel.py:

$ python examples/first_panel.py   # run from the repo root
saved -> panel.png

Verify the install — the test suite runs fully offline:

$ python -m pytest
# validates providers, schemas, layout/export, consistency, screenwriter,
# pipeline resume and content-safety behavior without real API calls

Status: M1–M4 (provider foundation, comic pipeline, long-form hardening and open-source release) have shipped. See the Roadmap for released capability, local prototypes and the approved long-form plan.

Prefer a single command? The launcher sets up the environment, installs deps, loads your key from .env, and runs the generator:

./scripts/start.sh                                   # runs examples/scene1.txt -> comic_out (page PDF)
./scripts/start.sh examples/sample_novel.txt --format webtoon

On Windows use .\scripts\start.ps1. Both reuse an already-active venv/conda env instead of nesting one. Sample inputs ship in examples/ (scene1.txt, sample_novel.txt).

Sample panels and the full webtoon strip are rendered live on the GitHub Pages site:

https://phaethix.github.io/inkstone/

They were generated from the bundled sample (examples/scene1.txt) with the default L1+L2 pipeline — no L3, straight from the model. Consistency here is "medium" by design — the honest ceiling of a free, no-GPU model. L1 prompt hard-description + L2 reference img2img carry identity; the optional L3 face overlay is off by default because it deforms stylized faces.

A zero-dependency local UI (Tailwind SPA + a http.server backend — no new pip package) wraps the same pipeline:

AGNES_API_KEY=sk-xxx python web/server.py
# open http://127.0.0.1:8000

Paste a novel, optionally set a project id (resume the same comic_out/<id>/), pick webtoon/page, and hit Generate. The backend runs an unattended supervisor around creative_comic: timeouts and free-tier 503s are retried automatically with backoff until the comic finishes, or until the wall-clock deadline (INKSTONE_RUN_DEADLINE_HOURS, default 24h) pauses the job with progress saved — same project id continues later. Artifacts land under comic_out/<project_id>/. After generation, the UI surfaces alias review (merge / dismiss — never silent), skipped panels with retry, and redraw affected after a merge.

The key is read from the environment or .env.

The same web/index.html is also deployed to GitHub Pages. The SPA auto-detects whether a backend is present: locally it generates your comic; on the static site it runs in demo mode and showcases a real generated sample with the identical interface and operations. What you run locally is what's on the page — see https://phaethix.github.io/inkstone/ (goes live once Pages is enabled in repo settings).

Inkstone is configured through environment variables (copy .env.example → .env):

A txt novel is split into segments → characters & scenes are extracted with agnes-2.0-flash → storyboard prompts are generated → the ImageProvider (Agnes by default) paints each panel → panels are laid out and exported to PDF/PNG. The core challenge — cross-panel character consistency without a GPU — is handled by a layered strategy (L1 Appearance-derived prompt hard-description + L2 reference img2img; optional L3 face overlay is off by default), backed by a reliability layer (rate limiting, retries, and state.json resumption). Alias variants are flagged for human merge/dismiss (never silent); merges mark affected panels stale for selective redraw. Longer-form adaptation work is tracked in the roadmap.

• Implementation status — docs/ROADMAP.md
• Colab CLI (close the laptop) — docs/guides/colab-cli.md + scripts/colab_run.sh
• Historical plans / specs — docs/superpowers/
• Contributing guide — CONTRIBUTING.md
• Issues & feedback — GitHub Issues

See CONTRIBUTING.md. All code, docs, and commit messages are in English; commits follow Conventional Commits.

MIT License — LICENSE