8000 GitHub - Deland78/blue-pencil · GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Blue Pencil

A local-first AI writing workspace where the writer holds the pen.

Blue Pencil is a desktop-grade fiction-writing app you run on your own machine. Instead of a chatbot that writes for you, it puts an AI Editor and Writer at a shared table — "The Table Read" — where you stay the author. Every AI edit is attributed and reversible, every AI call is logged with its cost, and your manuscript, outline, and story canon all live in one workspace.

It talks to a single external service — the Anthropic API — and stores everything else locally in MongoDB. Clone it, point it at your own Anthropic key, and make it yours.

Blue Pencil is a personal project shared as-is. It's built to be forked and customized, not to be a turnkey product.


What's inside

  • The Table Read — a chat-first workspace. Bring a passage "to the table" and ask the Editor for a read or the Writer for a draft; replies stream in and cite their sources. You accept, revise, or decline every suggestion — nothing touches your manuscript without your say-so.
  • Manuscript editor — a rich-text editor (TipTap) with autosave, rolling auto-snapshots, full version history, diff, and restore. A backspace can never silently destroy your text.
  • Outline — a free-form block outliner (BlockNote) that sits between concept and draft, with per-beat status.
  • Canon (your story bible) — structured, searchable facts about your world and characters. Ask the canon a question and get a cited answer; run a continuity crosscheck to catch contradictions between your draft and established canon.
  • Attribution you can trust — AI-written prose is tinted (a "blue pencil"); edit it by hand and it becomes yours. Server-side write rules mean an AI job can never overwrite text you own.
  • The Trace Ledger — every AI call is logged with its prompt, output, model, token counts, dollar cost, and latency. No hidden spend.

Architecture

Layer Stack
Frontend React 19 · Vite · TypeScript · TipTap 3 · BlockNote (frontend/)
Backend FastAPI · Python 3.10+ (backend/app/)
AI provider Anthropic Python SDK, behind a provider factory (ANTHROPIC_API_KEY only)
Database MongoDB (synchronous PyMongo)
Jobs & streaming Persisted background jobs with Server-Sent Events
Auth Local single-user mode — no login screen

The backend uses synchronous PyMongo, so DB-touching handlers are plain def, not async def. AI access goes through backend/app/services/provider_factory.py; every call is recorded by the ledger (services/ledger.py).

Quickstart

Prerequisites: Python 3.10+, Node.js 18+, MongoDB (local or Atlas), and an Anthropic API key.

# 1. Clone
git clone https://github.com/Deland78/blue-pencil.git
cd blue-pencil

# 2. Install backend + frontend deps
bash setup.sh          # Windows: setup.bat

# 3. Configure your key
cp backend/.env.example backend/.env
#   then edit backend/.env and set ANTHROPIC_API_KEY (and MONGO_URI if not localhost)

# 4. Run both servers
bash start-servers.sh  # Windows: start-servers.bat

Then open http://localhost:5173. The backend serves on http://localhost:8000 (GET /health for a status check).

macOS setup, including installing MongoDB, is walked through in docs/INSTALL-mac.md.

To run the servers by hand instead:

cd backend && uvicorn app.main:app --reload      # backend on :8000
cd frontend && npm run dev                        # frontend on :5173

Project layout

backend/           FastAPI app
  app/routers/     HTTP endpoints (table, story, canon, documents, reviews, jobs, …)
  app/services/    provider factory, jobs, ledger, canon, continuity gate, …
  app/models/      Pydantic models
  tests/unit/      pytest suite
frontend/
  src/workspace/   the Table Read UI (galley, table pane, canon, outline, history)
docs/              design specs, plans, and architecture notes (the build journey)

Testing

# Backend (CI runs the same, minus retired-code tests):
cd backend && python -m pytest tests/unit -q -m "not legacy"

# Frontend:
cd frontend && npm run lint && npx tsc --noEmit && npm run test:run && npm run build

Configuration

All backend config lives in backend/.env (template: backend/.env.example). Model choices per workflow (Opus / Sonnet / Haiku) are managed in-app via the Studio "Models" panel and in backend/app/core/config.py. Optional local trace capture is toggled with TRACING_ENABLED.

Contributing

Contributions and forks are welcome — see CONTRIBUTING.md. Please keep the test gates green.

License

MIT © David Eland.

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0