Escriba is a desktop-browser writing assistant for managing drafts, reviewing non-authoritative AI-likeness signals, and generating configurable rewrite suggestions. The app uses a local backend with SQLite or PostgreSQL for documents, model catalog configuration, and full analysis logs.
Writing assistants often collapse authorship signals, model calls, rewriting, and document persistence into one opaque interaction. Escriba separates those concerns so a user can keep control of the draft, inspect non-authoritative signals, compare model behavior, and retain the evidence behind an analysis.
- Model access stays behind the backend. The React client never receives provider credentials. A shared upstream gate bounds concurrency and start frequency, while retry behavior uses exponential backoff.
- Durable work instead of browser-owned jobs. Benchmark jobs are checkpointed in the database and can resume after interruption. This adds persistence complexity but avoids losing long-running evaluations on a page reload.
- SQLite first, PostgreSQL when needed. SQLite keeps local setup and backup simple. PostgreSQL supports a shared service deployment, with an explicit migration path rather than two unrelated persistence models.
- Calibration is evidence-driven but deliberately non-authoritative. Piecewise score calibration supports stored fixtures and model-specific profiles. The public edition includes synthetic smoke fixtures only; they demonstrate the pipeline rather than validate detector accuracy.
- Full analysis logs favor reproducibility over minimal retention. Prompts and upstream responses are stored for inspection. A production deployment should add a retention and privacy policy appropriate to its data.
React editor
|
v
Express API -----> SQLite or PostgreSQL
|
v
request gate + retry policy
|
v
configured model provider
|
v
analysis log + calibrated feedback
- Vite
- React
- TypeScript
- Tailwind CSS v4
- pnpm
- Express backend
- SQLite or PostgreSQL
- Docker Compose
- Target: desktop browser.
- Required port:
8559. - Detection results are non-authoritative writing feedback.
- Model calls happen only in the backend so the bearer token stays server-side.
- Documents and analysis logs are persisted in SQLite or PostgreSQL.
pnpm install
cp .env.example .env
pnpm start:backendIn another terminal:
pnpm dev --host 0.0.0.0 --port 8559Open http://localhost:8559.
The backend runs on http://localhost:8560. Vite proxies /api to the backend.
pnpm buildpnpm lint
pnpm test
pnpm buildThe automated suite covers detection units and chunking, calibration profiles and tuning, upstream request/response handling, usage accounting, editor text behavior, benchmark persistence, and PostgreSQL client behavior. GitHub Actions runs lint, tests, and the production build for pushes and pull requests.
Tailwind CSS uses the v4 Vite plugin and @import "tailwindcss" in src/index.css. New UI work should follow the project Tailwind rules in AGENTS.md: no @apply, no deprecated utilities, gap-based spacing, min-h-dvh, and text size line-height modifiers such as text-xs/5.
Optional production preview:
pnpm preview --host 0.0.0.0 --port 8559docker compose up --buildDocker Compose reads values from .env automatically when present. The app can start without it, but analysis requires UPSTREAM_API_BASE_URL and BEARER_TOKEN.
Open http://localhost:8561 (nginx reverse proxy). Direct service ports 8559 (frontend) and 8560 (backend) remain available for debugging.
- Desktop two-panel writing workspace.
- Left document sidebar with persisted documents.
- Auto-created persisted starter document when SQLite has no documents.
- Controlled text editor with word and character counters.
- Configurable suggestion profile: goal, tone, audience, strictness, and preserve-meaning toggle.
- Backend-fetched model selector from SQLite seeded models.
- Backend model call through the configured upstream
/ai/{model}endpoint. - Non-authoritative AI-likeness score with confidence label.
- Flagged passage view with reasons.
- Config-aware suggestion list with rewrite candidates.
- Full analysis logging in SQLite, including full prompt and full upstream response.
Create .env from .env.example and set:
UPSTREAM_API_BASE_URL: base URL that exposes/ai/{model}.BEARER_TOKEN: bearer token used by the backend only.PROVIDER: global fallback when a model has no stored provider and slug inference yieldslocalai. Per-model overrides live in Settings.SQLITE_PATH: SQLite database path (used whenDATABASE_URLis unset).DATABASE_URL: PostgreSQL connection string (when set, backend uses Postgres instead of SQLite).
Seeded models are stored in the database on first startup. Update the models table directly for now if the available model list needs to change.
Create a dedicated database on your Postgres server (separate from other apps):
CREATE DATABASE escriba;Set in .env:
DATABASE_URL=postgresql://user:password@localhost:5432/escribaWhen DATABASE_URL is set, Docker and host-run backends connect to Postgres. SQLITE_PATH remains the fallback when DATABASE_URL is empty.
One-time migration from SQLite (stop the backend first):
pnpm migrate:postgres
# re-import: pnpm migrate:postgres --forceThe script reads SQLITE_PATH, applies the Postgres schema, copies all tables in FK order, and resets serial sequences. Settings Download backup / Restore from backup remain SQLite-only until a Postgres backup flow is added.
Escriba uses a single SQLite file (default backend/data/escriba.db) with WAL journaling. Settings includes Download backup and Restore from backup (full replace). The CLI script pnpm backup:db writes timestamped copies under backend/data/backups/ (or DATABASE_BACKUP_DIR).
Online backup (backend may be running):
pnpm backup:db
# or
sqlite3 backend/data/escriba.db ".backup 'backend/data/escriba-backup.db'"Restore / clone to another machine:
- Back up the target
backend/datadirectory first. - Stop the backend:
docker compose stop backendor stop the localpnpm start:backendprocess. - Replace
backend/data/escriba.dbwith the backup file; deleteescriba.db-walandescriba.db-shmif present. - Start the backend again and verify
curl --fail http://localhost:8560/api/health.
Cross-instance copy: export from the source (Settings download or pnpm backup:db), transfer the .db file, then restore on the destination with a full replace. There is no merge of two databases—only overwrite.
WAL note: When copying files manually, copy escriba.db together with escriba.db-wal and escriba.db-shm, or stop the backend first. .backup and the in-app export produce a single consistent file.
Single backend instance: Only one backend process may open backend/data/escriba.db at a time. Do not run pnpm start:backend while the Docker backend is up (or vice versa). The backend refuses to start if another instance already holds the database lock; pnpm restart:stack stops stray local backends before restarting Docker.
Import via Settings replaces all documents, models, logs, and benchmarks in place (no server restart required). Reload the editor after a restore.
Unit scores pass through a piecewise calibration curve before they become document and passage scores. The curve has two layers: a global default (used by every model) and optional per-model overrides. The pnpm tune:calibration script grid-searches calibration parameters against registered fixtures under tests/.
The original evaluation corpus is intentionally excluded from this public edition because it contained private writing samples. The three bundled fixtures are synthetic smoke data for exercising the benchmark workflow; do not treat their illustrative target probabilities as calibration evidence.
The script previously hardcoded a per-model slug and could not retune the global default. It now selects the target model from the environment and supports both layers.
Retune the global default curve (writes backend/eval/score-calibration.json plus the synced default block in shared/detection/scoreCalibrationProfiles.ts and backend/eval/score-calibration-profiles.json):
pnpm tune:calibration --default # dry run, prints the tuned config
pnpm tune:calibration --default --write # apply the tuned configIn --default mode the model resolves from CALIBRATION_MODEL, then EVAL_MODEL, then the built-in baseline (gpt-5.4-nano), and all registered fixtures are used.
Tune a per-model override (adds or updates an entry in modelScoreCalibrationProfiles; the global default is left unchanged):
TUNE_MODEL=gemma-4-e2b pnpm tune:calibration --writePer-model runs default to the three bundled smoke fixtures; pass --fixtures=full_ai/text1,full_human/text1,... to override. Tuning the baseline slug as a per-model override is rejected—use --default instead.
Avoid repeated live calls. Live collection reuses the backend upstream gate, retry, and timeout settings (UPSTREAM_*, REQUEST_TIMEOUT_MS). To reuse scores from a prior run, run a baseline benchmark from the UI at /settings/benchmarks, then tune from the stored logs:
pnpm tune:calibration --default --from-db --write
# pass --job-id=<uuid> if the most recent job cannot be auto-detectedNote that CALIBRATION_MODEL also selects the baseline model for the UI benchmarks; the tuning script now reads the same variable in --default mode.
Regularized, outlier-robust objective. The grid search minimizes robustWeightedError + λ · smoothnessPenalty instead of raw weighted error, reducing the chance that a single false-positive fixture collapses the curve into a near-binary step:
TUNE_ERROR_CAP(default60) clamps each fixture's error so a single outlier cannot dominate.TUNE_TRIM_WORST(default1) drops the worst non-anchor fixture before averaging; high-weight anchors (clean human, canonical AI) are never trimmed.TUNE_SMOOTHNESS_LAMBDA(default8) andTUNE_SMOOTHNESS_MAX_SLOPE(default3) penalize curves whose calibrated output changes too sharply across the raw range, keeping mid-range scores reachable.
Set TUNE_SMOOTHNESS_LAMBDA=0 and TUNE_TRIM_WORST=0 to recover the old raw-error behavior.
- The AI-likeness score is assistive writing feedback, not a real authorship verdict.
- Results must not be treated as an absolute authorship verdict.
- Suggestions are not automatically applied to the draft.
- No accounts or admin model-management UI is included in the MVP.
- Add admin UI for enabling/disabling seeded models.
- Add environment-based provider mapping and fallback behavior.
- Improve confidence calibration and explainability for flagged passages.
- Add saved settings and versioned analysis history UI.
- Add optional auth, workspaces, and shareable read-only report links.
- Add browser-level coverage for the complete analyze and recovery flows.
- Expand the evaluation dataset and track detector-quality metrics over time.
- Add deployment hardening, health checks, observability, and performance testing.
This repository starts with a clean public history. Private deployment configuration, local data, credentials, and internal operational files are intentionally excluded.
MIT