[{"_1":2,"_184":-5,"_185":-5},"loaderData",{"_3":4,"_18":19,"_25":26,"_163":164},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16,"_17":11},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","dockerRebrandTour","routes/_layout",{"_20":-5,"_21":22,"_23":11,"_24":22},"username","isAskGordonEnabled",true,"showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_89":90,"_113":114,"_151":-5,"_152":11,"_153":22,"_154":11,"_155":11,"_156":-5,"_157":11,"_158":-5,"_159":160,"_161":115,"_162":-7},"canonicalUrl","https://hub.docker.com/r/unfoldingword/bp-assistant/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","unfoldingword","reponame","bp-assistant","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":73,"_74":75,"_80":11,"_81":82,"_86":33,"_87":88},"categories",[],"content_types",[44],"image","date_registered","2026-03-26T13:23:18.153464Z","description","Zulip bot that orchestrates AI-assisted creation of unfoldingWord Book Packages.","is_private","last_updated","2026-10-29T20:52:11.804448Z","last_modified","2026-10-29T20:52:27.254141Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",12595,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# BP Assistant — Zulip Bot\n\n[![GitHub](https://img.shields.io/badge/github-unfoldingWord%2Fbp--assistant-blue)](https://github.com/unfoldingWord/bp-assistant)\n\nZulip bot that orchestrates AI-assisted creation of unfoldingWord Book Packages. Monitors a Zulip channel and DMs, matches messages against routes via regex + NLU fallback, and dispatches to Claude SDK pipelines for Bible translation content generation.\n\n**Companion repo:** [bp-assistant-skills](https://github.com/unfoldingWord/bp-assistant-skills) — Claude Code skills and reference data that power the translation pipelines.\n\n## Prerequisites\n\n- Docker and Docker Compose\n- A Zulip organization with a bot account\n- A [Door43/Gitea](https://git.door43.org) account with API token\n- An Anthropic API key (for the Haiku NLU intent classifier)\n- Claude Code CLI authentication (for the Agent SDK pipelines)\n\n## Quick start\n\n### Docker (recommended)\n\n```bash\n# 1. Clone both repos side by side:\n# /srv/bot/app/ (this repo)\n# /srv/bot/workspace/ (bp-assistant-skills)\n# /srv/bot/config/ (secrets + env, see below)\n\n# 2. Create config directory and secrets\nmkdir -p /srv/bot/config/secrets\ncp .env.example /srv/bot/config/.env\n# Edit .env and populate all values\n\n# Create secret files (one value per file, no trailing newline):\necho -n \"your-token\" > /srv/bot/config/secrets/door43_token\necho -n \"your-username\" > /srv/bot/config/secrets/door43_username\necho -n \"your-key\" > /srv/bot/config/secrets/zulip_api_key\necho -n \"your-email\" > /srv/bot/config/secrets/zulip_email\n\n# 3. Create external Docker resources\ndocker volume create bot_claude-config\ndocker network create work-net # if not already present\n\n# 4. Build and run\ndocker compose up -d\ndocker logs zulip-bot --tail 30 -f\n```\n\n### Host cron automation\n\nHost-side automation now lives in the separate `bp-assistant-auto-issue-handler` repo. This app repo no longer owns cron scripts or host cron configuration.\n\n### Local development\n\n```bash\ncp .env.example .env\n# Fill in credentials\nnpm install\nnpm start\n```\n\nYou should see:\n\n```\n[bot] Authenticated as user@org.org (id: ...)\n[bot] Registered stream queue for \"CONTENT - UR\"\n[bot] Registered DM queue\n[bot] Watching topics: Psalms BP, AI Work, Workflow, ...\n[bot] Listening for messages...\n```\n\n## What it watches\n\nConfigured in `config.json`:\n\n- **Channel:** `CONTENT - UR`\n- **Topics:** Psalms BP, AI Work, Workflow, BP Proofreading, Proofreading Queue, Jeremiah BP, Habakkuk BP, Bot testing\n- **DMs:** Admin only (configured in `config.local.json`)\n\nMessages in other channels/topics are ignored. Messages you send yourself are always ignored (no echo loops).\n\n## Authorization\n\n- `config.local.json` (gitignored) holds `adminUserId` and `authorizedUserIds`\n- Stream @-mentions from unauthorized users get a canned reply\n- Only admin can DM the bot\n- All stream commands require an @-mention plus confirmation before running\n\n## How routing works\n\nWhen someone posts a message in a watched topic (or DMs you), the bot checks `config.json` routes top to bottom. The first regex match wins.\n\nIf no regex matches, the **Haiku NLU fallback** (`intent-classifier.js`) classifies the natural-language request into `generate / notes / editor-review / editor-note / unknown`. Unknown sends a help message.\n\n### Current routes\n\n| Route | Trigger | Pipeline | Description |\n|---|---|---|---|\n| `editor-note` | `note BOOK [CH] text` | `editor-note` | File an editor observation to `data/editor-notes/BOOK.md` |\n| `generate-content` | `generate BOOK CH[-CH]` | `sdk` | Run initial-pipeline (ULT + issues + UST) + alignment + Door43 push |\n| `write-notes` | `write notes [for] BOOK CH` | `notes` | Run post-edit-review/deep-issue-id, tn-writer, tn-quality-check + Door43 push |\n| `editor-review` | `BOOK CH review/compare` | `interactive-dm` | Multi-turn session running editor-compare skill |\n| DM default | any unmatched DM from admin | `interactive-dm` | Open-ended Claude conversation in /workspace context |\n\n### Confirmation flow\n\nAll stream commands show a confirmation message with a token/time estimate before running:\n\n> I'll generate the initial content (ULT & UST, issues draft) for **PSA 79**. Sound right? (yes/no)\n\nThe user must reply `yes` (or variants like `y`, `yep`, `go ahead`) to proceed. `no` cancels.\n\n### Multi-turn interactive sessions\n\nDMs to admin and `editor-review` channel commands maintain conversation state across messages using `session-store.js` (file-backed in `data/sessions/`).\n\n- `/reset` or `reset conversation` clears the session\n- `switch to sonnet/haiku/opus` changes the model mid-conversation\n- Messages are prefixed with `O:`, `S:`, or `H:` to indicate which model replied\n- Stream sessions auto-clear after `maxExchanges` (default 6 for editor-review)\n\n## Pipeline types\n\n### `sdk` (generate-content)\nUses the Claude Agent SDK `query()` to run skills in `/workspace`. The `generate-pipeline.js` module:\n1. Runs `initial-pipeline --lite` for each chapter (ULT + issues + UST)\n2. Runs `align-all-parallel` for ULT and UST alignment\n3. Pushes to Door43 via deterministic JS code (`door43-push.js`)\n4. Verifies each push via Gitea API (`repo-verify.js`)\n\n### `notes` (write-notes)\nThe `notes-pipeline.js` module runs a skill chain per chapter:\n1. `post-edit-review` or `deep-issue-id` (reconcile/find issues)\n2. Issue normalization (parallelism capping, deduplication) via `issue-normalizer.js`\n3. Mechanical prep in Node.js (prepare notes, fill Hebrew orig_quotes, resolve GL quotes, flag narrow quotes) — runs before `tn-writer` so Claude skips those MCP tool calls\n4. `tn-writer` (generate notes from issues)\n5. Quality mechanical prep in Node.js (fix trailing newlines, run all mechanical quality checks) — runs before `tn-quality-check` so Claude reads pre-run findings\n6. `tn-quality-check` (semantic review + one fix pass)\n7. Door43 push + verify\n\n#### Notes pipeline contract updates\n\n- Preparation now emits canonical metadata for each issue: `chosen_template_id`, `at_required`, `scope_mode`, and `issue_span_gl_quote`. These fields drive the downstream writer/AT calls instead of raw TSV hints.\n- Template candidates are filtered deterministically, and AI selectors (template choice + quote scope) return the winning template ID plus rationale so Claude never re-scans for templates.\n- Alternate translations are generated only when `at_required` is true (derived from the chosen template slot and explicit overrides) so quality checks and AT packets share the same enforcement contract.\n- Quote scope policy is enforced in code using the new `scope_mode`; the `tn-writer` and AT prompts now include the scoped English span plus scope mode context that maps back to Hebrew via `issue_span_gl_quote`.\n\n### `editor-note`\nAppends an observation to `data/editor-notes/BOOK.md`. Simple file-append operation via `note-pipeline.js`.\n\n### `interactive-dm`\nMulti-turn Claude sessions via SDK `resume`. Used for editor-review and admin DMs. See \"Multi-turn interactive sessions\" above.\n\n## Door43 integration\n\nContent is pushed to Door43/Gitea repos via deterministic JS code -- no Claude involved in the push itself.\n\n- `door43-push.js` / `door43-push-cli.js` -- Git operations + Gitea API PR creation\n- `repo-verify.js` -- Confirms PR merged to master by querying Gitea API\n- `door43-users.json` (gitignored) -- Maps email addresses to Door43 usernames\n- Requires `DOOR43_TOKEN` (or `GITEA_TOKEN`) env var for Gitea API access, plus `DOOR43_USERNAME` (or `GITEA_USERNAME`) for commit attribution\n\n## MCP server\n\nThe bot runs an MCP (Model Context Protocol) server on port 3001 that exposes Bible translation reference data and USFM processing tools to Claude during pipeline execution. Key tools include:\n\n- **Reference data**: Strong's concordance, glossary, issue types, published translations\n- **USFM processing**: `create_aligned_usfm` (mapping JSON → aligned USFM), `merge_aligned_usfm` (assemble N partial files into one chapter), `read_usfm_chapter`, `curly_quotes`, `check_ust_passives`\n- **TN processing**: `prepare_notes`, `fill_orig_quotes`, `resolve_gl_quotes`, `flag_narrow_quotes`, `fill_tsv_ids`, `assemble_notes`, `fix_trailing_newlines`\n- **Quality**: `validate_tn_tsv`, `check_tn_quality`\n- **Index builders**: `build_strongs_index`, `build_tn_index`, `build_ust_index`\n\nThe server starts automatically with the bot. Tool implementations live in `src/workspace-tools/`.\n\n## Usage tracking\n\nEvery SDK call writes to `data/metrics/usage.jsonl`. Pre-flight checks combine `ccusage` (CLI/desktop usage) with the bot's JSONL log to estimate headroom in the 5-hour token window.\n\n- Auto-calibrates budget when rate limits are hit\n- Verse-based timeout scaling: `verses x operations x 5min/op`, clamped 10-60 min\n- Verse counts from `verse-counts.js`\n\nBootstrap cost estimates (from 101+ observed runs) are in `src/usage-tracker.js` (`BOOTSTRAP_DEFAULTS`). The `estimateTokens()` function blends bootstrap with observed medians as data accumulates.\n\n## Environment variables & secrets\n\nIn Docker, credentials are loaded from Docker secrets (files mounted at `/run/secrets/`). The `.env` file provides non-secret configuration.\n\n### `.env` (non-secret config)\n\n| Variable | Description |\n|---|---|\n| `ZULIP_REALM` | Zulip server URL |\n| `PORT` | (optional) HTTP port for MCP server (default: 3001) |\n| `ANTHROPIC_API_KEY` | API key for Haiku NLU intent classifier |\n\n### Docker secrets\n\n| Secret | Description |\n|---|---|\n| `zulip_api_key` | Zulip bot API key |\n| `zulip_email` | Zulip bot email |\n| `door43_token` | Door43/Gitea API token for repo pushes |\n| `door43_username` | Door43/Gitea username |\n| `claude_oauth_token` | Claude Code OAuth token (for Agent SDK) |\n| `bt_mcp_api_token` | Bible translation MCP API token |\n\nFor local development without Docker, set these in `.env` directly (see `.env.example`).\n\n## File structure\n\n```\n.env.example <- Template for local development\nconfig.json <- Channel, topics, routes, usage tracking config\nconfig.local.json <- Admin/authorized user IDs (gitignored)\ndoor43-users.json <- Email-to-Door43 username map (gitignored)\nDockerfile <- Multi-stage: node:22-slim build → Chainguard distroless runtime\ndocker-compose.yml <- Mounts workspace, config, data; uses Docker secrets\npackage.json <- Dependencies: claude-agent-sdk, anthropic, zulip-js\n\nsrc/\n index.js <- Event loop: auth, poll Zulip events, filter, call router\n router.js <- Route matching, confirmation flow, pending merges, Haiku fallback\n config.js <- Merges config.json + config.local.json\n secrets.js <- Docker secrets loader (reads /run/secrets/* files)\n pipeline-runner.js <- Dispatcher: sdk / notes / editor-note / interactive-dm\n pipeline-context.js <- Shared pipeline context (book, chapter, config)\n pipeline-checkpoints.js <- Checkpoint save/restore for pipeline resumption\n issue-normalizer.js <- Parallelism capping and deduplication for issue TSVs\n check-ult-edits.js <- Detect human ULT edits (for post-edit-review gating)\n claude-runner.js <- SDK query() wrapper with timeout, abort, metrics hooks\n generate-pipeline.js <- ULT+UST generation + alignment + Door43 push\n notes-pipeline.js <- TN skill chain (issue-id -> tn-writer -> quality-check) + Door43 push\n note-pipeline.js <- Editor note filing (appends to data/editor-notes/BOOK.md)\n interactive-dm-pipeline.js <- Multi-turn Claude sessions (admin DMs + stream sessions)\n insertion-resume.js <- Resume interrupted repo-insert operations\n intent-classifier.js <- Haiku NLU fallback for natural-language commands\n mcp-server.js <- MCP server (port 3001) exposing Bible translation data\n usage-tracker.js <- JSONL metrics, token estimates, preflight checks, ccusage\n door43-push.js <- Deterministic Git+Gitea API push (isomorphic-git)\n door43-push-cli.js <- CLI wrapper for door43-push\n repo-verify.js <- Gitea API verification that PR merged to master\n session-store.js <- File-backed Claude session persistence\n auth-refresh.js <- Proactive OAuth token refresh (8h tokens, 30min margin)\n pending-merges.js <- File-backed pending merge state\n zulip-client.js <- Zulip API wrapper (send, DM, reactions, file upload)\n pipeline-utils.js <- Book name normalization, output file resolution, timeouts\n verse-counts.js <- Verse count lookup for timeout/estimate calculations\n\ndata/\n metrics/usage.jsonl <- Token usage log (auto-created)\n sessions/ <- Multi-turn session state (auto-created)\n editor-notes/ <- Filed editor observations (auto-created)\n```\n\n## Config reference\n\n```jsonc\n{\n \"adminUserId\": null, // Set in config.local.json\n \"authorizedUserIds\": [], // Set in config.local.json\n \"channel\": \"CONTENT - UR\", // Stream to monitor\n \"topics\": [\"Topic A\", ...], // Only these topics (exact match)\n \"watchDMs\": true, // Monitor direct messages (admin only)\n \"routes\": [ // Checked top-to-bottom, first match wins\n {\n \"name\": \"route-name\", // Label for logging\n \"match\": \"/regex/i\", // Trigger pattern\n \"type\": \"sdk|notes|editor-note|interactive-dm\",\n \"reply\": true, // Post output back to Zulip?\n \"confirmMessage\": \"...\", // Shown before running (supports $1, $2 captures)\n \"operations\": 3, // For timeout calculation (verses x ops x 5min)\n \"maxExchanges\": 6, // For interactive sessions\n \"cwd\": \"/workspace\" // Working directory for Claude\n }\n ],\n \"defaultPipeline\": null, // Script for unmatched stream messages (null = skip)\n \"dmDefaultPipeline\": { // Pipeline for unmatched admin DMs\n \"type\": \"interactive-dm\",\n \"cwd\": \"/workspace\"\n },\n \"usageTracking\": {\n \"windowBudgetTokens\": 220000,\n \"windowHours\": 5,\n \"warnThreshold\": 0.7,\n \"ccusagePath\": \"npx ccusage@latest\"\n }\n}\n```\n","has_starred","hub_user","jaapjanswijnenburg","immutable_tags_settings",{"_76":11,"_77":78},"enabled","rules",[79],".*","is_automated","permissions",{"_83":22,"_84":11,"_85":11},"read","write","admin","user","storage_size",31928611002,"orgData",{"_91":92,"_93":94,"_95":96,"_97":33,"_98":99,"_100":101,"_102":99,"_103":104,"_105":106,"_107":108,"_109":101,"_110":111,"_112":22},"id","7f743aab810248b0942c443a677a5a26","uuid","7f743aab-8102-48b0-942c-443a677a5a26","type","organization","orgname","full_name","unfoldingWord","location","","company","profile_url","https://unfoldingword.org","date_joined","2018-07-20T18:13:34.701841Z","gravatar_url","https://www.gravatar.com/avatar/f0a858590d900eacc3b598002540ac27?s=80&r=g&d=mm","gravatar_email","badge","open_source","is_active","recentTags",[115],{"_116":44,"_117":118,"_119":120,"_121":122,"_91":123,"_124":125,"_50":140,"_141":118,"_142":33,"_143":56,"_57":144,"_145":146,"_147":131,"_148":140,"_149":66,"_150":22},"content_type","creator",3578561,"digest","sha256:3c0b42a160166274917f6f28b67e9d46228cd6911ac53e0b1ba68f3d36079b19","full_size",208125392,1112786998,"images",[126],{"_127":128,"_119":120,"_129":101,"_130":131,"_132":133,"_134":135,"_136":101,"_137":-5,"_138":122,"_63":66,"_139":-5},"architecture","amd64","features","last_pulled","2026-11-03T03:59:15.658186866Z","last_pushed","2026-10-29T20:52:11.358110905Z","os","linux","os_features","os_version","size","variant","2026-10-29T20:52:11.652283Z","last_updater","last_updater_username","media_type","latest","repository",30563216,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":165,"_172":173,"_159":182,"_183":11},{"_40":166,"_42":167,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":168,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":73,"_74":169,"_80":11,"_81":171,"_86":33,"_87":88},[],[44],[56],{"_76":11,"_77":170},[79],{"_83":22,"_84":11,"_85":11},"tags",{"_174":64,"_175":-5,"_176":-5,"_177":178},"count","next","previous","results",[179],{"_116":44,"_117":118,"_119":120,"_121":122,"_91":123,"_124":180,"_50":140,"_141":118,"_142":33,"_143":56,"_57":144,"_145":146,"_147":131,"_148":140,"_149":66,"_150":22},[181],{"_127":128,"_119":120,"_129":101,"_130":131,"_132":133,"_134":135,"_136":101,"_137":-5,"_138":122,"_63":66,"_139":-5},[],"canDeleteTags","actionData","errors"]

unfoldingword/bp-assistant

Tags for unfoldingword/bp-assistant