BetaGrace vI
(https://github.com/thesweetlord/BetaGraceVI_GOLDEN) TypeScript Node [Tests
BetaGrace vI is a full-stack AI agent platform designed for adult creative writing, multi-modal generation (text, image, video), and deep narrative exploration. Built on TypeScript, React, Express, and PostgreSQL — runs entirely on free-tier AI providers.
Current Version: 4.3 — May 27, 2026 Test Status: npm run test:fast — 76/78 smoke tests passing (97.4%); 2 local-synthesis debug retrieval checks currently return 401 Unauthorized.
Image Generation Benchmark
High-Density Constraint-Locking Evaluation
20 / 27 canonical concepts passed (81.5%) under strict zero-tolerance visual verification.
This public benchmark tests whether an image-generation system can hold a dense set of precise, verifiable constraints at once, including laterality, exact text placement and material, dual lighting temperatures, micro-details, and object states. One missing or unverifiable critical constraint is a FAIL; aspect ratio is excluded from the pass/fail metric.
The result applies to the documented prompts, endpoints, attempt budgets, and visual verification rules. It does not claim that the underlying image model was modified or retrained, universal superiority across prompts or model versions, or statistical dominance from the small head-to-head sample.
Benchmark package: IMAGE BENCHMARK.zip README · master report · 27-prompt table · passing images · failed images · public image logs
What is BetaGrace?
BetaGrace is an AI agent platform with 8 specialized writing modes, a cinematic video generation pipeline, a 7-section academic paper builder, image generation with 42 mix-and-match style descriptors, code graph intelligence, a full GDPR compliance layer (Art. 17 + Art. 20), and an in-app admin dashboard — all running as a single self-contained server you can deploy anywhere.
It runs entirely on free-tier AI providers (OpenRouter + Local Synthesis). No paid API keys are required to get started.
Features
8 AI Modes
ModeDescription
StandardBalanced writing and general-purpose assistant
Flesh ArchitectDark, intense, body-horror and gothic creative writing
SanctuarySafe, gentle, protective tone for sensitive topics
Advanced ReasoningDeep structured thinking for complex questions
AutonomousMulti-step task execution without hand-holding
Video GeneratorCinematic storyboard → frame generation → FFmpeg MP4 assembly
Code GraphPaste code → live SVG force-directed dependency graph (JS/TS/Python)
Academic Research70×7 pipeline: Guard Loop → 7-section paper, written and downloaded independently
Smart Toggles
Faith Enhancement — adds spiritual voice and grace-forward imagery to responses
Advanced Reasoning — deeper, structured thinking in any mode
AI Provider Chain (fully free)
Requests cascade through providers until one succeeds:
OpenRouter — primary, fastest
Local Synthesis Engine — always available, zero external dependencies
70×7 Academic Artifact Builder
Type /full [topic] in chat or click the Write Artifact toolbar button
DuckDuckGo Guard Loop validates the topic before any writing begins
7-section paper generated in the background — no proxy timeouts
Live progress bar: Section X/7 — updated every 3 seconds
Completed paper downloads as a Markdown file
Artifacts persisted to PostgreSQL — survive server restarts
Video Generation Pipeline
Storyboard hydration engine generates 10–20 cinematically distinct scenes
Each frame individually prompted with unique shot angles, lighting, atmosphere, and seed
FFmpeg assembles frames into a streaming MP4 (H.264, CRF 23, fast preset)
Real-time storyboard preview with scene captions during processing
Automatic cleanup of temp frames after assembly
Full mobile support (iOS + Android)
Image Generation
Pollinations Flux API — no key required for basic use
42 mix-and-match style descriptors — 150+ effective style combinations
Hand-validation loop with up to 3 auto-retries for anatomical correctness
High / ultra quality options
Code Graph Panel
Paste any JS, TypeScript, or Python snippet
SVG force-directed graph renders live in the browser using Graphology
Nodes = files/classes/functions, edges = import/call relationships
Works on mobile (pinch-zoom recommended for large graphs)
Memory & Learning System
Per-session parallel learning engine analyzes writing patterns in real time
Long-term semantic compression stores insights across sessions
Anti-cascade protocol: learning data survives session deletion (ON DELETE SET NULL)
All memory stored in PostgreSQL — persists across restarts
Admin endpoint: GET /api/health/learning (requires ADMIN_TOKEN)
Retrieval debug endpoint: POST /api/synthesis/test-retrieval lets you inspect the top local BM25/fallback matches and scores without affecting normal chat behavior
Privacy & GDPR Compliance
GDPR Article 20 — Right to Data Portability
One-click ZIP export from Settings → Data tab — 6 JSON files + README.txt
Files: session.json, conversations.json, messages.json, consent.json, learning_data.json, long_term_memory.json
GDPR Article 17 — Right to Erasure
Formal deletion request form in Settings → Data tab (reason + optional message)
Request logged to DB, admin email notification via configurable SMTP
30-day processing window with status tracking (pending → processing → completed)
Instant Self-Service Deletion
"Delete All My Data" button hard-deletes everything immediately via cascade
Additional
COPPA-compliant 18+ age verification gate
30-day rolling retention auto-purge (based on last interaction, not session creation)
12-month consent record auto-purge
6-category granular cookie consent
Full Privacy Policy and Terms of Service served as API endpoints
In-App Admin Panel
Access via Settings → Admin tab with your ADMIN_TOKEN:
PanelFunction
Learning Health DashboardLive DB counts for learning data, long-term memory, anti-cascade proof. Auto-refreshes every 30s
GDPR Deletion RequestsAll Art. 17 requests with session IDs, timestamps, user messages. One-click Mark Complete / Processing / Failed
Session Consent LookupLook up any session's consent record and cookie preferences by session ID
Tech Stack
LayerTechnology
FrontendReact 18 + Vite + TypeScript
StylingTailwind CSS + shadcn/ui (Radix UI)
StateZustand + TanStack Query
BackendExpress + TypeScript (tsx)
DatabasePostgreSQL 14+ via Drizzle ORM
AI / TextOpenRouter + Local Synthesis
AI / ImagesPollinations Flux API
VideoFFmpeg (ffmpeg-static, no install required)
Emailnodemailer (SMTP — optional, graceful skip when unconfigured)
AuthSession-based with fingerprint fallback
RoutingWouter (client), Express (server)
Quick Start
Prerequisites
Node.js 20+
PostgreSQL 14+ (or a free hosted instance — Neon, Supabase, Railway)
- Clone & install
git clone https://github.com/thesweetlord/BetAGracevI.git
cd betagrace
npm install
- Configure environment
cp .env.example .env
Edit .env — the three required values:
DATABASE_URL=postgresql://user:password@localhost:5432/betagrace
SESSION_SECRET=<generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))">
ADMIN_TOKEN=
DEV_PASSWORD=
Everything else is optional. The app works fully without any paid API keys.
Optional — for better AI performance:
POLLINATIONS_API_KEY=your_key_here
Optional — for GDPR Art. 17 email alerts:
ADMIN_EMAIL=Emails are not allowed
SMTP_FROM=Emails are not allowed
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_USER=your_smtp_username
SMTP_PASS=your_smtp_password
- Set up the database
npx drizzle-kit push
- Start the server
npm run dev
Open http://localhost:5000 — you'll see the age verification screen, then the full platform.
Running Tests
Fast mode (78 tests, ~23s) — skips long-polling artifact waits
npm run test:fast
Full suite (includes artifact polling and may take several minutes)
npm run test
The fast suite covers: all 8 AI modes, full session lifecycle, SSE streaming, artifact builder pipeline, video mode guards, code graph analysis, memory system, guardrails (injection + oversized message), privacy endpoints (export/delete/anti-cascade), admin token auth, GDPR flows, feature toggles, concurrent session isolation, session edge cases, max-token validation, and database schema checks. The current run passes 76 of 78 checks; the two failures are local-synthesis debug retrieval checks receiving 401 Unauthorized.
Project Structure
betagrace/
├── client/ # React + Vite frontend
│ └── src/
│ ├── components/
│ │ ├── ChatInterface.tsx # Main chat UI (~2,050 lines)
│ │ ├── CodeGraphPanel.tsx # SVG code graph renderer
│ │ ├── ModeSelector.tsx # AI mode switcher
│ │ └── ...
│ └── pages/
│ ├── Dashboard.tsx # Main app page
│ └── Settings.tsx # Settings + Admin panel (1,399 lines)
├── server/
│ ├── routes.ts # All API endpoints (6,659 lines)
│ ├── ai.ts # Multi-provider AI orchestration
│ ├── academic-research-engine.ts # 70x7 Artifact Builder + Guard Loop
│ ├── guardrails.ts # Content safety layer (1,175 lines)
│ ├── storage.ts # Data access layer (1,133 lines)
│ ├── email.ts # SMTP email service (GDPR Art. 17)
│ ├── video-engine-hydration.ts # Storyboard + scene hydration
│ ├── synthesis-engine.ts # Memory synthesis system
│ ├── parallel-learning.ts # Behavioral pattern engine
│ └── code-graph-analyzer.ts # JS/TS/Python graph builder
├── shared/
│ └── schema.ts # Drizzle ORM schema (10 tables)
├── smoke-tests.ts # Integration smoke-test suite
├── BETAGRACE_REPORT.md # Full technical & operational report
├── CAPABILITY_LIST.md # Feature reference
├── compatibility-list.md # Browser, Node, DB, email compatibility
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Setup guide for contributors
└── .env.example # All environment variables documented
API Overview
Session
MethodEndpointDescription
POST/api/sessionCreate or retrieve session
POST/api/session/verify-ageSet 18+ verification flag
GET/api/session/statusGet current session state
Chat
MethodEndpointDescription
POST/api/chatSend message — all 8 modes supported
GET/api/chat/streamSSE streaming chat
Academic Artifact Builder
MethodEndpointDescription
POST/api/academic/artifact/buildStart 70×7 job → {jobId} in <1s
GET/api/academic/artifact/status/:jobIdPoll build progress
Image & Video
MethodEndpointDescription
POST/api/generate-imageGenerate image
POST/api/videoQueue video generation job
GET/api/video-status/:jobIdPoll video job status
GET/api/video/:filenameStream completed MP4
Privacy (GDPR)
MethodEndpointDescription
GET/api/privacy/export-dataExport full session JSON (Art. 20)
GET/api/privacy/export-data/zipDownload ZIP archive (Art. 20)
POST/api/privacy/delete-dataHard-delete session + all data instantly
POST/api/privacy/deletion-requestSubmit formal Art. 17 erasure request
GET/api/privacy/deletion-requestGet current session's request status
Admin (requires X-Admin-Token header)
MethodEndpointDescription
GET/api/health/learningLearning system metrics
GET/api/admin/deletion-requestsList all Art. 17 requests
PATCH/api/admin/deletion-requests/:idUpdate request status
GET/api/admin/consent-auditSession consent lookup
Synthesis / Local Memory Debug
MethodEndpointDescription
GET/api/synthesis/statsLive BM25/local synthesis engine stats
POST/api/synthesis/test-retrievalRead-only debug: inspect top retrieved memory records + scores for a query
POST/api/synthesis/distillForce a distillation pass (prune + reindex)
Example retrieval debug request:
curl -X POST http://localhost:5000/api/synthesis/test-retrieval \
-H "Content-Type: application/json" \
-d '{
"userMessage": "how does the admin panel memory system work?",
"systemPrompt": "You are BetaGrace vI in STANDARD mode.",
"mode": "standard",
"k": 5
}'
This endpoint is read-only. It does not generate chat output, mutate sessions, or change stored memories. It only shows which local memory records the synthesis engine would retrieve and how they scored.
Health
MethodEndpointDescription
GET/api/healthServer + DB health check
GET/api/privacy-policyFull privacy policy text
GET/api/terms-of-serviceFull terms of service text
Full API reference: see BETAGRACE_REPORT.md
Security
8-layer middleware stack (CORS, body limit 50kb, security headers, HTTPS enforce, cache-control, concurrency limiter 1,000 req, 120s timeout, rate limiter 100 req/60s)
4-layer guardrail system (perimeter defense, age check, jailbreak detection, content filtering)
ADMIN_TOKEN ships blank — forks cannot use a preset default
DEV_PASSWORD ships blank — /api/dev/push-to-code disabled in production
Zero hardcoded credentials anywhere in source
Contributing
See CONTRIBUTING.md for the full setup guide and PR process.
License
BetaGrace vI is free software released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). Copyright (C) 2026 Jesse J. Wheeler Jr.
You may use, modify, and distribute this software under the terms of the AGPL-3.0. Any derivative work or hosted service built on BetaGrace must also be released under the same license. See the LICENSE file for the full text.