# PROJECT.md — Agent Engine

**Source of truth for what this product is and what actually exists.**
Rules → `CLAUDE.md`. Design → `ARCHITECTURE.md`. Open questions → `THREADS.md`.

*Last verified against the live Supabase project and the `dev` branch: 2026-09-08.*

---

## 1. What Agent Engine is

A **marketplace of AI agents that any website can embed with one `<script>` tag**.

A customer signs up, creates an **organization**, creates a **project** (one project = one website domain), connects an agent from the catalog, gives it knowledge — uploaded documents, a live database connection, or both — and pastes an embed snippet into their site. Visitors on that site then chat with the agent, and the customer sees conversations and analytics in a dashboard.

Built by **Webbrains Technologies Private Limited**.

### The core design pattern

**Context injection.** The agent is not fine-tuned per customer. At request time the runtime assembles context — retrieved document chunks, live database rows, conversation summary, widget configuration, per-project system instructions — and injects it into the prompt. Everything a customer configures is data, not code.

### Tenancy model

```
user → organization → project (1 domain) → project_agent (a connected agent)
                                         → documents / database connections
                                         → API key
```

- A user may own several organizations; an organization may hold several projects.
- **One project links exactly one domain.** Requests are rejected if the browser `Origin` does not match `projects.domain`, or if `is_domain_verified` is false.
- **Subscription plans apply per project, not per user** — though billing rolls up to the organization.
- The project API key (`aepk_…`) is generated per project, hashed at rest, revealed once, and regenerable.

---

## 2. Status at a glance

| | |
|---|---|
| **Shipped and working** | Auth, organizations, projects, API keys, own-LLM-key configuration and per-visitor rate limiting, document storage + embedding pipeline, RAG agent with SSE streaming, live database connections (MySQL/MariaDB/MongoDB), uploaded DB exports, query templates, the embeddable widget, widget preview, analytics, notifications, global search |
| **Partly built** | Query-template parameterization (9 open items), widget build pipeline, analytics depth |
| **Placeholder UI only** | Agent Flow, Logs, API Docs, Integrations, Advisors, Help |
| **Designed, not built** | Billing and subscriptions, lead-qualification agent, follow-up agent, marketplace and pricing pages, plugins/SDKs |
| **Known broken** | Nothing currently. Partitions were fixed 2026-09-09 — see §6 |

---

## 3. What is shipped

### Identity and tenancy
- Supabase Auth sign-up / sign-in, with session-expiry handling and token refresh in `src/proxy.ts`.
- Organization creation with plan selection, members and roles (`is_org_member`, `has_org_role`).
- Project creation with a single linked domain, project statuses, project settings, project deletion.
- Dashboard: organizations list, projects per organization, global search, notifications.

### Project API keys
Server-generated `aepk_…` keys stored as `key_hash` + `key_prefix`. List, search, paginate, optional expiry, one active key per project with a confirmation step before rotating, and a single one-time plaintext reveal.

### Knowledge: documents (RAG)
- Upload to Supabase Storage with extension allow-listing and upload-conflict checks.
- A job lands in `document_processing_jobs`; the **embedding pipeline worker** downloads it, extracts text (PDF, DOCX, RTF, TXT), chunks it, embeds it with **the project's own embedding provider and key** (Google `gemini-embedding-001` or OpenAI `text-embedding-3-*`, always 1536 dimensions), and writes `document_chunks` plus `embedding_usage_events`. Uploading is refused until the Conversational Agent has an embedding key.
- Retrieval is the `match_document_chunks` pgvector RPC.

### Knowledge: databases
Two distinct paths, both shipped:
- **Uploaded exports** — a phpMyAdmin JSON export becomes `document_database_schemas` + `document_database_table_data`, loaded into an in-memory **SQLite** database at query time.
- **Live connections** — MySQL / MariaDB (including WordPress-shaped schemas) and MongoDB. Credentials in `database_connection_secrets`, schema introspected into `database_connection_schemas` via sync-schema.

### Query templates and query modes
Customers pre-define named queries with placeholders — `:param` for SQL, `{{param}}` for Mongo — optional `parameter_schema`, and card-rendering config for carousel output.

Three modes exist in the code: `template_only`, `template_preferred`, `generated`. **Only `template_only` is currently accepted** — a deliberate product restriction enforced in both the UI and the server guard. See `docs/task-queue/temporary-query-mode-restriction.md`.

### The RAG agent
A FastAPI service called server-to-server by the web app. Per turn: a router LLM classifies the question as `rag`, `db`, or `both`; the RAG branch does vector retrieval; the DB branch loads schema context, picks a template or generates SELECT-only SQL/Mongo, verifies it, executes it; results merge into one answer with citations, carousel cards, and follow-up suggestions.

Providers: **the customer's own.** Each project chooses Google, OpenAI, Anthropic or OpenRouter, types the model name, and supplies its own API key (see *Own API keys and rate limiting* below); every LLM call of the turn uses it. Text-to-SQL runs through LangChain by default, with LlamaIndex as a secondary path, both on the project's model.

Streaming is Server-Sent Events with a versioned event contract — `start`, `delta`, `phase`, `done`, `error`, `cancelled` — documented in `docs/architecture/rag-agent-sse-protocol.md`.

### Own API keys and rate limiting (Conversational Agent)
Configured per project in the Connected Agents card under **AI PROVIDER & LIMITS**:

- **LLM** — provider (Google, OpenAI, Anthropic, OpenRouter), model name, API key.
- **Embedding** — provider (Google or OpenAI; Anthropic has no embeddings API), model name, API key. Left empty, the LLM key is reused when the provider is the same.
- **Rate limit** — per second or per minute, 1–1000 chat messages per visitor (per visitor id, plus 5× that per IP so clearing `localStorage` does not reset it). Empty = no limit. Excess messages get HTTP 429 and a translated "please wait" message in the widget; the dashboard preview is exempt.

**Agent Engine provides no LLM key.** Until both keys are saved the embed script is not shown, the preview is disabled, chat answers "not set up yet" without calling any provider, and document uploads are refused. On save, each changed key/model is test-called (one tiny chat call, one embedding call checking 1536 dimensions); a failure leaves everything unsaved and shows the provider's error. Keys are write-only — the card shows only `••••` + the last four characters.

Changing the embedding model while documents embedded with another model exist is refused with a message to delete those documents first, since their vectors would no longer match.

### The widget
`apps/web/public/scripts/rag-agent-widget.js` — 2,424 lines of dependency-free vanilla JS. Shipped features: launcher avatar as Lucide icon / image / GIF / MP4, per-device avatar sizing (mobile / tablet / desktop), theme colour, custom agent name, configurable greetings, streamed replies, carousel cards with images and links, an in-chat contact form with configurable required fields, follow-up suggestion chips, and conversation persistence via `visitor_id` / `conversation_id` in `localStorage`.

### Dashboard extras
- **Connected Agents** — connect/disconnect agents, own LLM / embedding keys and rate limit (Conversational Agent), per-agent system instructions, full widget configuration, and a live preview that renders the customer's real website behind the widget using Playwright.
- **Analytics** — visitor and conversation views per project.

---

## 4. What is placeholder UI

These project tabs render a title and a sentence. There is no logic behind them:

**Agent Flow**, **Logs**, **API Docs**, **Integrations**, **Advisors**, and the topbar **Help** button (an intentional no-op).

---

## 5. What is designed but not built

- **Billing and subscriptions.** `subscriptions`, `invoices`, `payments`, `payment_methods`, `plans`, `plan_prices` all exist as tables, and `docs/db-schema/revenue-model-i3.md` specifies 670 lines of plan tiers, multi-currency pricing, overage, gateway selection, and lifecycle. **None of it is implemented.** Organization creation only sets `organizations.plan_id`.
- **Lead-qualification agent** and **instant follow-up agent** — in the original architecture, absent from the codebase.
- **Upstash Redis** for queues and rate limiting — the embedding pipeline polls Postgres, and chat rate limiting uses a Postgres counter (`consume_chat_rate_limit`).
- **Twilio SMS / WhatsApp / SendGrid email** — no integration exists.
- **Marketplace, pricing, home, and agent-detail pages** — wireframes exist in `design/wireframes/`; only the dashboard is built.
- **Plugins, React/Next SDK, mobile SDKs, public API product** — scope, not work in progress.

---

## 6. Monthly partitions and retention

`messages`, `agent_executions`, and `audit_logs` are range-partitioned by month on `created_at`. Until 2026-09-09 partitions existed only for 2026-03…06, so every chat message insert failed. Migration `0037` added partitions through 2027-12, a `DEFAULT` safety partition, and the rotation functions; `create-monthly-partitions` keeps six months ahead.

Retention follows the design spec and **deletes, it does not export**: `agent_executions` months older than 90 days and `messages` months older than 365 days are dropped on the 1st of each month. The first run (2026-10-01) dropped `agent_executions` for 2026-03…06. Whether to keep this policy is open in `THREADS.md`.

---

## 7. Deployment

**DigitalOcean App Platform**, deploying `apps/web` from the `main` branch on Node 20 LTS. The runbook is `docs/web-production-deployment-handoff.md`.

The Vercel + Render + Cloudflare arrangement described in `README.md` was planning, never adopted. `README.md` is inaccurate on this and several other points and is being narrowed to a short public overview.

The RAG agent and the embedding worker have no production deployment defined yet; Dockerising them is a tracked thread.

---

## 8. Stack

| Layer | Choice |
|-------|--------|
| Dashboard + API | Next.js 16.1.6, React 19.2.3, TypeScript, Tailwind 4, shadcn/ui, Node 20 LTS |
| Agent runtime | Python 3.12, FastAPI, LangChain, LlamaIndex |
| Worker | Python 3.12 |
| Database / Auth / Storage / Vector | Supabase — Postgres 17.6 with pgvector, project `Agent Engine` (`xbkcqtqrgrnbepunsayc`, Sydney) |
| Default LLM | Google Gemini; OpenAI, Anthropic, OpenRouter supported |
| Embeddings | `gemini-embedding-001`, 1536 dimensions |
| Widget | Vanilla JS, no framework, no build step yet |
| Hosting | DigitalOcean App Platform |

Provider cost assumptions are in `COSTING.md` and reflect the original Vercel/Render/Twilio plan — they need revising for the DigitalOcean reality.

---

## 9. Non-negotiables

1. **The public API is a published contract.** `/api/public/rag/chat` and the SSE events are live on customer sites. Additive changes only.
2. **One project, one domain.** `Origin` is checked against `projects.domain` and the domain must be verified.
3. **Generated queries are SELECT-only**, verified before execution, on both the SQL and Mongo paths.
4. **The service role key never reaches the browser.** The widget authenticates with a project API key; the web app authenticates to the RAG agent with a shared internal secret.
5. **Latency has a budget.** Target blocking path ~2.0–3.3s, one primary generation call per turn. See `docs/architecture/rag-agent-latency-playbook.md`.
