Lucille Documentation

Lucille is a multi-tenant personal assistant backend with persistent memory, a job queue, and a worker loop. The backend uses Supabase Auth (JWT via JWKS) and Postgres (async SQLAlchemy).

What’s in these docs

• AI docs — Low-cost context for AI agents (digest.md + one module brief).
• Architecture — High-level design, deployment, HTTP node contract, marketplace, thoughts, delegations.
• Product requirements — Canonical completion contract for Lucille's low-cognitive-load assistant vision.
• Frontend: marketplace & job tracking — Plan for frontend to track scheduled jobs, claimed status, and optional marketplace results (hand-off for subagent or developer).
• Subscription & revenue — Revenue strategies: subscription (credit-based tiers/top-ups) vs bring-your-own API keys (BYOK); evaluation and open questions.
• Guides — How-to guides (e.g. iOS Shortcut note capture).
• Human docs — Long-form docs not included in default AI context.
• Legacy — Deprecated deploy/ops material.

Quick links

• Repo README — Setup, run locally, VM deploy, API examples.
• AGENTS.md — Notes for AI agents working on the codebase.

Stack

Component	Tech
Backend	FastAPI, async SQLAlchemy, Supabase Auth
Worker	Python loop, claims jobs from backend
Web	Next.js 14 (app router), Vercel
Data	Postgres (Supabase or self-hosted)

All data is tenant-scoped by user_id (JWT sub). Worker endpoints use X-Worker-Token; admin endpoints require users.is_admin = true.