Why RedNotebook AI?

Modern data teams jump between five tools to answer one question. RedNotebook AI puts all of it in one notebook:

• A real SQL workspace with Monaco, AG Grid, drag-to-reorder cells, and keyboard shortcuts.
• Premium charts powered by Apache ECharts with brand-aware theming.
• AI you can trust, pluggable across OpenAI, Anthropic, Ollama, or a deterministic offline mock. Privacy-safe by default, schema-only context, PII masking, secrets stripped.
• NotebookLM-style knowledge layer. Pull SQL, schemas, results, and charts into a notebook of sources. Ask grounded questions with [n] citation chips. Generate infographics and a Studio briefing (overview / FAQ / study guide / suggested next questions).
• Drag-and-drop file uploads. Drop a CSV, TSV, Parquet, or JSON file anywhere in the app — DuckDB attaches it instantly as a queryable table (SELECT * FROM customers Just Works).
• One-click publish. Mint a public, no-account-needed share link from any notebook. The published page is a self-contained HTML snapshot — your live data never leaves your machine.
• Read-only by default. A SQL guard backed by sqlglot blocks destructive statements unless you explicitly enable writes.
• Local-first. Runs on your laptop with no login. Flip a single env var (AUTH_ENABLED=true) to enable multi-user mode with local email+password, GitHub OAuth, API tokens, per-user namespacing, and admin invites.

Install

Just kicking the tires? The live demo at huggingface.co/spaces/heruwala/rednotebook-demo runs the published image with the sample notebook pre-loaded. No install required, no signup, your work isn't saved between sessions.

Docker (any OS)

docker run -d --name rednotebook \
  -p 8000:8000 \
  -v rednotebook-data:/data \
  ghcr.io/sanniheruwala/rednotebook-ai:latest

Then open http://localhost:8000.

Or with Compose:

cp .env.example .env  # edit as needed
docker compose up -d

Python

pip install rednotebook-ai          # from PyPI (when a release is tagged)
rednotebook run                      # starts the FastAPI server on :8000

Then in a second terminal:

cd frontend
npm install
npm run dev                          # starts the dev UI on :3000

From source

git clone https://github.com/sanniheruwala/RedNotebookAI.git
cd RedNotebookAI
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
rednotebook run

# in another terminal
cd frontend && npm install && npm run dev

Where can I run this safely?

RedNotebook AI is local-first. Today:

See docs/deployment.md for the full security model.

Pick a data source

In the UI top bar, click Configure connection. 13 connectors ship in the box — no extra pip install step, no driver setup, no ODBC dance.

See docs/connectors.md for the full per-dialect field reference.

Quick start: DuckDB (no server, instant)

The default. Pick "DuckDB (no server)" in the dialog. Two modes:

• In-memory (:memory:) — ephemeral playground. Great for one-off SQL against local files: SELECT * FROM read_csv_auto('orders.csv') WHERE …
• File (./local.duckdb) — persistent. Use it like a single-user warehouse: CREATE TABLE customers (…), INSERT …, etc.

Optionally set a "Working directory" so relative file paths in read_csv_auto / read_parquet resolve where you expect.

Trino HTTPS defaults via .env

For team analytics on real data warehouses, fill in the UI dialog or set defaults in .env:

TRINO_HOST=trino.example.com
TRINO_PORT=443
TRINO_SCHEME=https
TRINO_USER=alice
TRINO_PASSWORD=...
TRINO_CATALOG=hive
TRINO_SCHEMA=default
TRINO_VERIFY_SSL=true

Custom HTTP headers, session properties, query timeouts, and result limits are all supported.

Configure AI

Privacy defaults:

• Sample rows are not sent to AI unless AI_ALLOW_SAMPLE_ROWS=true.
• PII columns are masked when samples are shared.
• Secrets are stripped from SQL before any provider call.
• Credentials are never forwarded to AI.

See docs/ai.md for details.

Enable multi-user (optional)

AUTH_ENABLED=true
SECRET_KEY=$(openssl rand -hex 32)
COOKIE_SECURE=true              # set true when behind HTTPS
ALLOW_SELF_SIGNUP=false         # admin-invite only by default

The first registration becomes the workspace admin. Subsequent users need an invite (POST /api/auth/invite). GitHub OAuth and API tokens (PAT-style) are supported out of the box. See docs/deployment.md.

Architecture

rednotebook/        Python backend (FastAPI + core libs)
├── auth/           User store, JWT sessions, password hashing, OAuth, API tokens
├── server/         FastAPI app + routers
├── connectors/     Trino + DuckDB + 11 SQLAlchemy dialects + registry
├── ai/             Provider abstraction (mock, openai, anthropic, ollama)
├── notebook/       Notebook models, JSON storage, guard-aware runner
├── knowledge/      NotebookLM-style internal knowledge layer
├── visualization/  Recommender, chart spec, HTML infographic generator
├── profiling/      Stats + PII detector
├── security/       SQL guard, secret masking
├── migrations/     One-shot data migrations
└── cli/            Typer CLI

frontend/           Next.js + Tailwind + shadcn/ui
docs/               Architecture, AI, security, deployment, connectors, roadmap
tests/              pytest test suite

Full architecture write-up.

Documentation

• Architecture
• Deployment tiers
• Host a public demo on Hugging Face Spaces (free, no card)
• Host a public demo on Fly.io
• Connectors
• AI providers and privacy
• Security model
• Visualization
• Knowledge layer + NotebookLM integration
• Roadmap
• Contributing

Development

# Backend
pytest                              # 56+ tests
ruff check .

# Frontend
cd frontend
npm run typecheck
npm run lint
npm run build

Continuous integration runs the full suite on every push and PR. See .github/workflows.

Contributing

We follow the standard open-source flow. The short version:

1. Open an issue first. Use the bug report or feature request templates. Drive-by PRs with no linked issue may be closed without review.
2. Fork, branch, write, run the checks locally (pytest, ruff check ., npm run lint && npm run typecheck && npm run build).
3. Open a PR referencing the issue (Closes #123).
4. A maintainer reviews and approves before merge. main is a protected branch — direct pushes are blocked, every change needs ✅ green CI and ✅ approval from a CODEOWNER. No exceptions, even for admins.

See docs/contributing.md for the full flow, branch-naming conventions, what we say "no" to, and the maintainer rights. For security vulnerabilities, use private disclosure, never a public issue.

License

Apache-2.0. See LICENSE.