SAGE

SAGE (Semantic Agentic Generation Engine) is an evidence-first report generation system for qualitative and mixed-method datasets.

This repository now ships a local-first, operator-hosted single-region SAGE platform slice:

• full-dataset L0 -> L1 -> L2 -> L3 -> compose -> critic synthesis
• multi-tenant tenant/project/workspace scope on jobs, runs, artifacts, and retrieval state
• local workflow queue, background worker CLI, HTTP API, browser operator console, and API-key-authenticated single-node control plane
• explicit job lifecycle with retries, lease recovery, in-flight lease heartbeats, queued/running cancel controls, bounded layer1 dispatch, cooperative CPU-loop abort checkpoints, batched embeddings cancellation guards, late-cancel completion guards, dead-letter handling, and persisted last-error state
• file-backed and sqlite-object artifact backends with mirrored reviewable run directories
• file-exact and sqlite-ann vector retrieval backends for persisted drill-down reuse
• stable better-sqlite3-backed SQLite platform metadata plus workflow/platform diagnostics for local operator inspection and SAGE_STATE_DB_PATH-anchored colocated state roots by default
• mock, OpenAI, Anthropic, and persisted phase-aware latency-aware multi-provider failover execution paths with automatic quarantine/recovery probes plus operator override and runtime repair controls
• platform snapshot export/import, restore-env handoff, active/standby replica sync, active-node drain mode, takeover preflight, queued-job carryover rewrite, promotion, and admin API workflows for node replacement or operator takeover
• benchmark suite against a simple retrieval-centric baseline across multiple local fixtures
• rubric evaluation plus blinded human-preference packet export, bundled external panel roster catalog with CLI/API import, SQLite-backed panel registry, invite-token recruiting, self-serve signup, waitlist capture/promotion, external CSV/JSON panel roster ingestion with bundled Prolific submissions JSON and Cint background CSV adapters, registry-backed campaign sourcing, notification/mail-merge bundle export, SQLite-backed delivery outbox with SMTP/local-copy/webhook dispatch, scheduled retry/backoff policy, worker/API drain paths, auto-classified SMTP bounce feedback, persisted sender-reputation scoring with throttle/pause guardrails, tokenized hosted panel assignment/response intake, first-party suppression/unsubscribe/bounce feedback state, panel campaign/assignment tooling, answer-key, judgment-template, and adjudication tooling
• finalized local CSP package v1, NDJSON packet stream, and import/validate tooling
• replayable run artifacts under output/runs/<run_id>/
• run analytics and budget-policy recommendations from persisted artifacts
• contradiction-aware theme synthesis, section grounding checks, and reviewer packets

The repository is licensed under Apache-2.0. The strategy notes in Beyond_RAG_Strategy.md and Beyond_RAG_Strategy-zh.md remain research documents, not automatic implementation guarantees.

What This Is

SAGE is built around one thesis: high-quality reports should be generated from synthesized understanding of the full dataset, not from a thin retrieval slice.

The current repository is intended to be:

• public and reviewable
• deterministic enough to inspect end-to-end
• product-like inside a single node
• modular at adapter boundaries
• explicit about evidence and operational boundaries

It is an operator-hosted single-region control plane with active/standby handoff, not a managed multi-region SaaS control plane. Release posture and remaining non-goals are described in docs/public-release.md.

Quick Start

Install dependencies:

nvm use 22.18.0
npm ci

If you change Node versions later, rebuild native dependencies before running tests:

npm rebuild better-sqlite3

Run the mock demo pipeline:

npm run demo

Install and run from npm:

npm install @mason131928/sage
npx sage --input examples/survey-dataset.json --output output/report.md

pnpm add @mason131928/sage
pnpm exec sage --input examples/survey-dataset.json --output output/report.md

Turn a folder of source files into a SAGE dataset, then generate a report:

npx sage-ingest \
  --input ./source-folder \
  --output data/source-folder.dataset.json \
  --title "Source Folder Analysis" \
  --language zh-TW \
  --profile evidence_audit

npx sage \
  --input data/source-folder.dataset.json \
  --output output/source-folder-report.md \
  --profile evidence_audit \
  --language zh-TW

Built-in report profiles are task types rather than vertical domains:

• research_synthesis
• decision_brief
• evidence_audit
• stakeholder_analysis

Run tests:

npm test

Run the full verification workflow:

npm run verify

Generate the public benchmark suite plus human-preference packet artifacts:

npm run benchmark

Analyze accumulated run history:

npm run analyze

Refresh the local reviewer packet for the latest run:

npm run review

Submit and inspect workflow jobs:

npm run workflow -- submit --input examples/survey-dataset.json --tenant-id local --project-id default --workspace-id default
npm run workflow -- list
npm run workflow -- show --job <job_id>
npm run workflow -- cancel --job <job_id>
npm run workflow -- resume --job <job_id>
npm run workflow -- inspect-state

Tune local abort responsiveness for larger datasets or slower providers:

SAGE_LAYER1_CONCURRENCY=4 \
SAGE_COOPERATIVE_YIELD_INTERVAL=16 \
SAGE_OPENAI_EMBEDDINGS_BATCH_SIZE=64 \
SAGE_WORKFLOW_LEASE_RENEW_INTERVAL_MS=600000 \
npm run worker -- --workflow-root output/workflow --interval-ms 3000 --lease-ms 1800000

Export a single-node snapshot and restore it onto a replacement root:

npm run workflow -- snapshot-export \
  --workflow-root output/workflow \
  --artifacts-root output/runs \
  --state-root output/state \
  --snapshot-root output/snapshots

npm run workflow -- snapshot-import \
  --snapshot output/snapshots/<snapshot_id> \
  --target-root output/restored-node

cat output/restored-node/sage-restore.env

Sync a standby replica, inspect its state, and promote it when the active node must be replaced:

npm run workflow -- standby-sync \
  --workflow-root output/workflow \
  --artifacts-root output/runs \
  --state-root output/state \
  --standby-root output/standby-node \
  --snapshot-retention 3

npm run workflow -- standby-status --standby-root output/standby-node
npm run workflow -- standby-promote --standby-root output/standby-node
cat output/standby-node/node/sage-promote.env

Quiesce the active node, inspect takeover readiness, and perform a one-shot standby takeover:

npm run workflow -- node-drain-enable \
  --workflow-root output/workflow \
  --state-root output/state \
  --reason operator_takeover

npm run workflow -- standby-takeover-plan \
  --workflow-root output/workflow \
  --artifacts-root output/runs \
  --state-root output/state \
  --standby-root output/standby-node

npm run workflow -- standby-takeover \
  --workflow-root output/workflow \
  --artifacts-root output/runs \
  --state-root output/state \
  --standby-root output/standby-node \
  --reason operator_takeover

Run the local background worker:

npm run worker -- --workflow-root output/workflow --interval-ms 3000 --lease-ms 1800000 --lease-renew-interval-ms 600000

Optionally let the same worker drain due panel-delivery notifications:

SAGE_STATE_DB_PATH=output/state/sage-platform.sqlite \
SAGE_PANEL_DELIVERY_TRANSPORT=smtp \
SAGE_PANEL_SMTP_HOST=127.0.0.1 \
SAGE_PANEL_SMTP_PORT=1025 \
SAGE_PANEL_SMTP_FROM="SAGE Research Ops <[email protected]>" \
npm run worker -- --workflow-root output/workflow --interval-ms 3000 --lease-ms 1800000

Start the operator API and open the browser console:

npm run api -- --port 8787
open http://127.0.0.1:8787/

Bootstrap an authenticated single-node control plane and expose it on the network:

npm run workflow -- auth-bootstrap \
  --tenant-id local \
  --project-id default \
  --workspace-id default \
  --user-id admin \
  --email [email protected] \
  --display-name "SAGE Admin"

npm run api -- --host 0.0.0.0 --port 8787

Operator diagnostics endpoints:

• GET /health
• GET /auth/status
• GET /auth/me
• GET /overview
• GET /diagnostics
• GET /platform/snapshots
• GET /platform/snapshots/inspect?snapshot_path=...
• GET /platform/node/drain
• GET /platform/standby
• GET /platform/standby/takeover-plan?standby_root=...
• GET /provider-router/routers
• GET /control-plane/tenants
• GET /control-plane/users
• GET /control-plane/memberships
• GET /control-plane/api-keys
• POST /provider-router/overrides
• POST /provider-router/runtime
• POST /platform/snapshots/export
• POST /platform/snapshots/import
• POST /platform/node/drain
• POST /platform/standby/sync
• POST /platform/standby/promote
• POST /platform/standby/takeover
• GET /panel/bundles
• POST /panel/bundles/:bundleId/import
• GET /panel/invites
• POST /panel/invites
• GET /panel/invites/:inviteId?token=...
• POST /panel/invites/:inviteId/status
• GET /panel/waitlist
• POST /panel/waitlist/:waitlistId/status
• POST /panel/waitlist/:waitlistId/promote
• GET /panel/panelists
• POST /panel/panelists
• POST /panel/panelists/:panelistId/status
• POST /panel/panelists/signup
• GET /panel/reputation
• GET /panel/suppressions
• GET /panel/delivery-feedback
• POST /panel/delivery-feedback
• GET /panel/campaigns/:campaignId
• GET /panel/campaigns/:campaignId/delivery
• GET /panel/campaigns/:campaignId/responses
• POST /panel/campaigns/:campaignId/delivery/dispatch
• GET /panel/assignments/:assignmentId?token=...
• POST /panel/assignments/:assignmentId/responses?token=...
• POST /panel/assignments/:assignmentId/unsubscribe?token=...
• GET /runs/:runId/review
• POST /runs/:runId/review/decisions

Issue a reviewer key and record a remote approval:

curl -X POST http://127.0.0.1:8787/control-plane/tenants \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"tenant_id":"tenant-a","display_name":"Tenant A"}'

curl -X POST http://127.0.0.1:8787/control-plane/users \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"user_id":"reviewer-a","email":"[email protected]","display_name":"Reviewer A","global_role":"reviewer"}'

curl -X POST http://127.0.0.1:8787/control-plane/memberships \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"user_id":"reviewer-a","tenant_id":"local","project_id":"default","workspace_id":"default","role":"reviewer"}'

curl -X POST http://127.0.0.1:8787/control-plane/api-keys \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"user_id":"reviewer-a","label":"reviewer-a-key"}'

curl -X POST http://127.0.0.1:8787/runs/<run_id>/review/decisions \
  -H "authorization: Bearer <reviewer_api_key>" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve","notes":"Remote approval from the single-node control plane."}'

Export a node handoff bundle and restore it through the admin API:

curl -X POST http://127.0.0.1:8787/platform/snapshots/export \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"snapshot_root":"output/snapshots","workflow_root":"output/workflow","artifacts_root":"output/runs","state_root":"output/state"}'

curl -X POST http://127.0.0.1:8787/platform/snapshots/import \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"snapshot_path":"output/snapshots/<snapshot_id>","target_root":"output/restored-node"}'

curl -X POST http://127.0.0.1:8787/platform/standby/sync \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"workflow_root":"output/workflow","artifacts_root":"output/runs","state_root":"output/state","standby_root":"output/standby-node","snapshot_retention":3}'

curl -X POST http://127.0.0.1:8787/platform/standby/promote \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"standby_root":"output/standby-node"}'

curl -X POST http://127.0.0.1:8787/platform/node/drain \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"enabled":true,"reason":"operator_takeover"}'

curl "http://127.0.0.1:8787/platform/standby/takeover-plan?standby_root=output/standby-node" \
  -H "authorization: Bearer <admin_api_key>"

curl -X POST http://127.0.0.1:8787/platform/standby/takeover \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"workflow_root":"output/workflow","artifacts_root":"output/runs","state_root":"output/state","standby_root":"output/standby-node","reason":"operator_takeover"}'

Export blinded human-preference packets from benchmark output:

npm run evaluate -- export --benchmarks-dir output/benchmarks --output-dir output/evaluations

Adjudicate completed human judgments:

npm run evaluate -- adjudicate \
  --packet output/evaluations/human-preference-packet.json \
  --answer-key output/evaluations/human-preference-answer-key.json \
  --judgments output/evaluations/judgment-a.json,output/evaluations/judgment-b.json

Import an external roster into the persisted local panel registry and inspect eligible panelists:

npm run evaluate -- panel-bundle-list

npm run evaluate -- panel-import \
  --panel-roster examples/panel-roster.csv \
  --state-db output/state/sage-platform.sqlite

npm run evaluate -- panel-list \
  --state-db output/state/sage-platform.sqlite \
  --panel-status active \
  --panel-require-email true

Import bundled marketplace exports without hand-normalizing the source file first:

npm run evaluate -- panel-import \
  --panel-bundle prolific-submissions \
  --state-db output/state/sage-platform.sqlite

npm run evaluate -- panel-import \
  --panel-bundle cint-panel-roster \
  --state-db output/state/sage-platform.sqlite

Use panel-roster-csv or panel-roster-json for the generic shipped sample rosters. The marketplace adapter auto-detects bundled contracts; pass --panel-provider prolific or --panel-provider cint if you need to force the parser.

Issue a quota-limited recruitment invite for hosted panel signup:

npm run evaluate -- panel-invite-create \
  --state-db output/state/sage-platform.sqlite \
  --label "April Research Recruit" \
  --max-claims 5 \
  --expires-at 2026-04-30T00:00:00.000Z \
  --tags enterprise,qual \
  --locale en-US

npm run evaluate -- panel-invite-list \
  --state-db output/state/sage-platform.sqlite \
  --invite-status open

npm run evaluate -- panel-waitlist-list \
  --state-db output/state/sage-platform.sqlite \
  --waitlist-status pending

Export per-panelist campaign packets from the local registry or an external reviewer roster:

npm run evaluate -- panel-export \
  --packet output/benchmarks/human-preference/packet.json \
  --panel-source registry \
  --panel-status active \
  --panel-require-email true \
  --panel-limit 6 \
  --due-at 2026-04-15T00:00:00.000Z \
  --response-base-url https://sage.local/panel \
  --delivery-transport smtp \
  --deliver-after 2026-03-30T09:00:00.000Z \
  --delivery-max-attempts 4 \
  --sender "Research Ops" \
  --state-db output/state/sage-platform.sqlite \
  --output-dir output/evaluations

Or source the campaign directly from a CSV/JSON roster file:

npm run evaluate -- panel-export \
  --packet output/benchmarks/human-preference/packet.json \
  --panel-roster examples/panel-roster.csv \
  --due-at 2026-04-15T00:00:00.000Z \
  --response-base-url https://sage.local/panel \
  --delivery-transport smtp \
  --deliver-after 2026-03-30T09:00:00.000Z \
  --delivery-max-attempts 4 \
  --sender "Research Ops" \
  --state-db output/state/sage-platform.sqlite \
  --output-dir output/evaluations

Bundled marketplace exports use the same panel-export path and annotate the resulting campaign plus mail-merge artifacts with provider metadata:

npm run evaluate -- panel-export \
  --packet output/benchmarks/human-preference/packet.json \
  --panel-bundle prolific-submissions \
  --response-base-url https://sage.local/panel \
  --delivery-transport local-copy \
  --state-db output/state/sage-platform.sqlite \
  --output-dir output/evaluations

Dispatch the persisted notification outbox through a single-node SMTP, local-copy, or webhook transport:

npm run evaluate -- panel-deliver \
  --campaign output/evaluations/human-preference-panel-campaign.json \
  --state-db output/state/sage-platform.sqlite \
  --transport smtp \
  --smtp-host 127.0.0.1 \
  --smtp-port 1025 \
  --smtp-from "SAGE Research Ops <[email protected]>" \
  --output-dir output/evaluations

Drain all due notifications from the persisted outbox without naming a specific campaign:

npm run evaluate -- panel-deliver-due \
  --state-db output/state/sage-platform.sqlite \
  --transport local-copy \
  --outbox-dir output/evaluations/delivery \
  --output-dir output/evaluations

Inspect local suppressions, sender reputation, or record delivery feedback from the CLI:

npm run evaluate -- panel-suppression-list \
  --state-db output/state/sage-platform.sqlite \
  --status active

npm run evaluate -- panel-delivery-feedback \
  --state-db output/state/sage-platform.sqlite \
  --assignment-id <assignment_id> \
  --type hard_bounce \
  --source smtp_feedback \
  --notes "550 mailbox unavailable"

npm run evaluate -- panel-delivery-reputation \
  --state-db output/state/sage-platform.sqlite \
  --campaign-id <campaign_id>

Inspect or redrive panel delivery from the authenticated API:

curl http://127.0.0.1:8787/panel/campaigns/<campaign_id>/delivery \
  -H "authorization: Bearer <admin_api_key>"

curl -X POST http://127.0.0.1:8787/panel/campaigns/<campaign_id>/delivery/dispatch \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"transport":"local-copy","outbox_dir":"output/evaluations/delivery"}'

curl http://127.0.0.1:8787/panel/suppressions?status=active \
  -H "authorization: Bearer <admin_api_key>"

curl -X POST http://127.0.0.1:8787/panel/delivery-feedback \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"assignment_id":"<assignment_id>","feedback_type":"delivery_restored","notes":"Operator restored deliverability."}'

curl http://127.0.0.1:8787/panel/reputation?campaign_id=<campaign_id> \
  -H "authorization: Bearer <admin_api_key>"

Accept self-serve panelist signups and approve them into the single-node registry:

curl -X POST http://127.0.0.1:8787/panel/panelists/signup \
  -H 'content-type: application/json' \
  -d '{"display_name":"Hosted Judge","email":"[email protected]","tags":["enterprise","qual"],"consent_acknowledged":true}'

curl http://127.0.0.1:8787/panel/panelists?statuses=pending \
  -H "authorization: Bearer <admin_api_key>"

curl -X POST http://127.0.0.1:8787/panel/panelists/<panelist_id>/status \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"status":"active","max_active_assignments":2,"notes":"Approved for the local panel registry."}'

POST /panel/panelists/signup rejects duplicate email registrations inside the same scope, and GET /panel/panelists returns both the filtered registry rows and summary counts by status, delivery status, and source type for operator review.

Issue an invite-scoped recruitment token and inspect it over the hosted API:

curl -X POST http://127.0.0.1:8787/panel/invites \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"label":"April Invite Cohort","max_claims":5,"tags":["enterprise","qual"],"locale":"en-US"}'

curl "http://127.0.0.1:8787/panel/invites/<invite_id>?token=<sage_inv_token>"

curl -X POST http://127.0.0.1:8787/panel/panelists/signup \
  -H 'content-type: application/json' \
  -d '{"display_name":"Invited Judge","email":"[email protected]","consent_acknowledged":true,"invite_token":"<sage_inv_token>"}'

curl -X POST http://127.0.0.1:8787/panel/panelists/signup \
  -H 'content-type: application/json' \
  -d '{"display_name":"Waitlisted Judge","email":"[email protected]","consent_acknowledged":true,"invite_token":"<sage_inv_token>","waitlist_if_unavailable":true}'

curl http://127.0.0.1:8787/panel/waitlist?status=pending \
  -H "authorization: Bearer <admin_api_key>"

curl -X POST http://127.0.0.1:8787/panel/waitlist/<waitlist_id>/promote \
  -H "authorization: Bearer <admin_api_key>" \
  -H 'content-type: application/json' \
  -d '{"status":"active","max_active_assignments":2}'

Hosted assignments now expose a token-scoped unsubscribe route that records first-party suppression state:

curl -X POST "http://127.0.0.1:8787/panel/assignments/<assignment_id>/unsubscribe?token=<sage_eval_token>" \
  -H 'content-type: application/json' \
  -d '{"notes":"Please remove me from future panel email."}'

Inspect a hosted panel assignment and submit a response through the single-node API:

npm run api -- --host 0.0.0.0 --port 8787

curl "http://127.0.0.1:8787/panel/assignments/<assignment_id>?token=<sage_eval_token>"

curl -X POST "http://127.0.0.1:8787/panel/assignments/<assignment_id>/responses?token=<sage_eval_token>" \
  -H 'content-type: application/json' \
  -d @output/evaluations/panel/<panelist_id>/response.json

Adjudicate completed panel responses from files or directly from SQLite-backed hosted intake:

npm run evaluate -- panel-adjudicate \
  --campaign output/evaluations/human-preference-panel-campaign.json \
  --answer-key output/benchmarks/human-preference/answer-key.json \
  --state-db output/state/sage-platform.sqlite

npm run evaluate -- panel-adjudicate \
  --campaign output/evaluations/human-preference-panel-campaign.json \
  --answer-key output/benchmarks/human-preference/answer-key.json \
  --responses output/evaluations/panel/panelist-alex/response.json,output/evaluations/panel/panelist-blair/response.json

Validate or import a CSP package:

npm run csp -- validate --package output/runs/<run_id>/csp-package.json --stream output/runs/<run_id>/csp-package.ndjson
npm run csp -- import --package output/runs/<run_id>/csp-package.json --stream output/runs/<run_id>/csp-package.ndjson

Provider Usage

Use the OpenAI Responses API adapter:

SAGE_PROVIDER=openai \
OPENAI_API_KEY=your_key \
SAGE_OPENAI_DISTILL_MODEL=gpt-5.4-mini \
SAGE_OPENAI_META_MODEL=gpt-5.4-mini \
SAGE_OPENAI_QA_MODEL=gpt-5.4-mini \
SAGE_OPENAI_PREFLIGHT_TOKENS=true \
node src/index.js --input examples/survey-dataset.json

Use Anthropic for generation while keeping mock embeddings:

SAGE_PROVIDER=anthropic \
ANTHROPIC_API_KEY=your_key \
SAGE_ANTHROPIC_DISTILL_MODEL=claude-3-5-sonnet-latest \
SAGE_ANTHROPIC_META_MODEL=claude-3-5-sonnet-latest \
SAGE_ANTHROPIC_QA_MODEL=claude-3-5-sonnet-latest \
node src/index.js --input examples/survey-dataset.json

Use persisted failover routing:

SAGE_PROVIDER_CHAIN=anthropic,openai,mock \
SAGE_EMBEDDINGS_PROVIDER_CHAIN=openai,mock \
ANTHROPIC_API_KEY=your_key \
OPENAI_API_KEY=your_key \
node src/index.js --input examples/survey-dataset.json

Inspect, override, or repair persisted router policy:

npm run workflow -- provider-router-list --adapter-type llm

npm run workflow -- provider-router-override \
  --adapter-type llm \
  --providers anthropic,openai,mock \
  --provider anthropic \
  --force-phases section_compose \
  --manual-bias 18 \
  --note "Pin section composition to Anthropic during launch week."

npm run workflow -- provider-router-runtime \
  --adapter-type llm \
  --providers anthropic,openai,mock \
  --provider anthropic \
  --release-quarantine true \
  --clear-cooldown true \
  --reset-failures true \
  --clear-last-error true \
  --reset-phase-stats true

Use SQLite/object-backed artifacts and ANN retrieval:

SAGE_ARTIFACT_BACKEND=sqlite-object \
SAGE_VECTOR_BACKEND=sqlite-ann \
SAGE_STATE_DB_PATH=output/state/sage-platform.sqlite \
SAGE_OBJECT_STORE_ROOT=output/state/objects \
node src/index.js --input examples/survey-dataset.json

Useful runtime controls:

• SAGE_PROVIDER_CHAIN
• SAGE_EMBEDDINGS_PROVIDER_CHAIN
• SAGE_PROVIDER_FAILOVER_COOLDOWN_MS
• SAGE_PROVIDER_FAILOVER_PHASE_AWARE
• SAGE_PROVIDER_FAILOVER_LATENCY_AWARE
• SAGE_PROVIDER_FAILOVER_LATENCY_STEP_MS
• SAGE_PROVIDER_FAILOVER_LATENCY_EMA_ALPHA
• SAGE_ARTIFACT_BACKEND
• SAGE_VECTOR_BACKEND
• SAGE_STATE_DB_PATH
• SAGE_OBJECT_STORE_ROOT
• SAGE_TENANT_ID, SAGE_PROJECT_ID, SAGE_WORKSPACE_ID
• SAGE_PANEL_DELIVERY_TRANSPORT
• SAGE_PANEL_DELIVERY_OUTBOX_DIR
• SAGE_PANEL_DELIVERY_WEBHOOK_URL
• SAGE_PANEL_DELIVERY_TIMEOUT_MS
• SAGE_PANEL_SMTP_HOST
• SAGE_PANEL_SMTP_PORT
• SAGE_PANEL_SMTP_SECURE
• SAGE_PANEL_SMTP_STARTTLS
• SAGE_PANEL_SMTP_USERNAME
• SAGE_PANEL_SMTP_PASSWORD
• SAGE_PANEL_SMTP_FROM
• SAGE_PANEL_SMTP_REPLY_TO
• SAGE_OPENAI_MAX_RETRIES
• SAGE_OPENAI_RETRY_BASE_MS
• SAGE_OPENAI_RETRY_MAX_MS
• SAGE_OPENAI_REQUEST_TIMEOUT_MS

Verification

npm run verify now does ten things:

1. runs the full automated test suite
2. executes a fresh end-to-end SAGE pipeline run on the sample dataset
3. validates CSP package integrity for that run
4. executes a scoped sqlite-object + sqlite-ann verification run
5. submits a workflow job and completes it through the background worker CLI
6. proves worker failure isolation by failing one queued job and then completing a later queued job
7. boots an API-key-authenticated control plane, issues a scoped reviewer key, and records a remote approval through the HTTP API
8. builds analytics plus workflow/platform diagnostics from the verification run
9. runs the multi-fixture SAGE-vs-retrieval benchmark suite plus human-preference packet, panel registry import/list, registry-backed campaign export, scheduled notification outbox delivery drain, tokenized hosted panel assignment/response intake, panel campaign, and adjudication verification
10. verifies that reviewer, retrieval-index, CSP package, artifact-manifest, worker, evaluation, and control-plane outputs were emitted

This is the strongest single command in the repo for release checks and CI.

Output Artifacts

Each run writes a reviewable artifact bundle under output/runs/<run_id>/, including:

• dataset.json, layer0.json, layer1.json, layer2.json, layer3.json
• retrieval-index.json
• section-plans.json, section-budgets.json, drill-down.json, section-review.json
• report.json, critic.json
• review-state.json, review-packet.json, review-packet.md
• csp-preview.json
• csp-package.json, csp-package.ndjson
• token-usage.json, provider-events.json, runtime-observability.json
• artifacts.manifest.json
• summary.json

Benchmark output is written under output/benchmarks/ and includes:

• public-release-suite.json
• public-release-suite.md
• fixtures/<dataset_id>-comparison.json
• fixtures/<dataset_id>-comparison.md
• human-preference/packet.json
• human-preference/packet.md
• human-preference/answer-key.json
• human-preference/judgment-template.json

Human adjudication output is typically written under output/evaluations/ and includes:

• human-preference-packet.json
• human-preference-packet.md
• human-preference-answer-key.json
• human-preference-judgment-template.json
• human-preference-panel-campaign.json
• human-preference-panel-campaign.md
• human-preference-panel-roster.json
• human-preference-panel-notifications.json
• human-preference-panel-notifications.md
• human-preference-panel-mail-merge.csv Includes source type/label plus marketplace provider, contract, reference id, and marketplace status when the roster came from a bundled external panel adapter.
• human-preference-panel-delivery.json
• human-preference-panel-delivery.md
• human-preference-panel-delivery-due.json
• human-preference-panel-delivery-due.md
• delivery/<campaign_id>/<assignment_id>/notification.json
• panel/<panelist_id>/assignment.json
• panel/<panelist_id>/notification.json
• panel/<panelist_id>/notification.md
• panel/<panelist_id>/packet.json
• panel/<panelist_id>/packet.md
• panel/<panelist_id>/judgment-template.json
• human-preference-adjudication.json
• human-preference-adjudication.md
• human-preference-panel-response-summary.json
• human-preference-panel-response-summary.md

The csp-preview.json artifact remains the preview-layer semantic compression artifact. The finalized local transport contract is csp-package.json plus csp-package.ndjson.

Reviewer Workflow

review-packet.md is the fastest artifact for a human operator to inspect. It summarizes:

• critic status and severity counts
• the recommended report decision
• a prioritized section review queue
• per-section QA status, grounding counts, retrieved evidence counts, and key quotes

Refresh the packet for the latest run:

npm run review

Record a section revision request:

npm run review -- --run output/runs/<run_id> --section section_1 --decision revise --reviewer analyst --notes "Tighten the evidence bullets."

Record a report-level approval:

npm run review -- --run output/runs/<run_id> --decision approve --reviewer editor --notes "Ready for delivery."

Record a remote report-level approval through the authenticated API:

curl -X POST http://127.0.0.1:8787/runs/<run_id>/review/decisions \
  -H "authorization: Bearer <reviewer_api_key>" \
  -H 'content-type: application/json' \
  -d '{"decision":"approve","notes":"Approved from the remote reviewer surface."}'

See docs/reviewer-workflow.md for the review loop. See docs/operator-workflow.md for queue, worker, API, and UI operations.

Repository Map

• docs/sage-prd.md: product requirements and platform expectations
• docs/sage-technical-design.md: architecture, storage, retrieval, and protocol design
• docs/public-release.md: public posture, verification, and current boundaries
• docs/operator-workflow.md: queue, worker, API, and operator console
• docs/reviewer-workflow.md: reviewer packet and approval flow
• src/index.js: CLI entrypoint
• src/workflow.js: queue CLI
• src/worker.js: background worker CLI
• src/api.js: HTTP API entrypoint
• src/workflow/ui.js: operator console
• src/review.js: reviewer CLI
• src/benchmark.js: benchmark runner
• src/evaluation.js: human-preference packet, panel campaign, delivery outbox, and adjudication CLI
• src/evaluation/smtp.js: built-in SMTP relay transport for panel delivery
• src/csp.js: CSP validate/import CLI
• src/core/orchestrator.js: end-to-end pipeline runner
• src/core/sqlite-artifact-store.js: SQLite/object-backed artifact persistence
• src/storage/vector-index.js: filesystem exact vector index store
• src/storage/sqlite-ann-index.js: SQLite ANN-style retrieval store
• src/csp/package.js: CSP v1 package/export/import layer
• src/adapters/: mock, OpenAI, Anthropic, and failover adapters
• src/analytics/: cost analysis and budget-policy generation
• test/: automated regression coverage

Current Scope

Included:

• ingest and normalization
• answer-level distillation
• theme synthesis with contradiction tracking
• grounded section composition with drill-down
• section QA and critic validation
• finalized local CSP package v1 and NDJSON transport stream
• benchmark suite against a simple retrieval-centric baseline
• rubric evaluation plus blinded human-preference packet export, bundled external panel roster catalog, invite-token recruiting, waitlist capture/promotion, panel campaign exchange, scheduled delivery outbox dispatch, and adjudication templates
• local and remote reviewer workflow for explicit approval and revision decisions
• API-key-authenticated single-node workflow queue, HTTP API, browser operator console, and background worker loop
• snapshot restore plus active/standby replica sync, active-node drain, takeover preflight, queued-job carryover rewrite, standby write-lock, and promotion workflows
• multi-tenant tenant/project/workspace scope propagation
• tenant registry, user memberships, scoped API keys, and review-decision audit trails in the local platform database
• file and SQLite/object artifact backends with stable better-sqlite3 local persistence
• filesystem exact and SQLite ANN retrieval backends
• OpenAI token accounting and provider preflight checks
• OpenAI and Anthropic adapters plus persisted phase-aware latency-aware failover routing with quarantine/recovery probes and operator force/disable/bias/runtime-repair controls
• persisted artifact analytics and budget-policy generation

Managed-service limits still outside scope:

• the platform is still an operator-hosted single-region active/standby deployment rather than a managed multi-region SaaS