# ARIA — Architecture **ARIA** (Adaptive Response & Intelligence Agent) is a Messenger-style, event-driven, multimodal conversational agent deployed under the NNLABS brand. - Root showcase: `https://nnlabs.pl` (landing — ARIA listed alongside NINA / IRIS / LUNA) - App: `https://app.nnlabs.pl/aria` (the chat) - Brain: `https://nextneural-aria.hf.space` (Gradio Space, vision-capable) ## Locked decisions | Layer | Choice | |---|---| | Brain | Gradio HF Space + vision model, emits structured JSON bubbles | | Realtime | Durable Object (`AriaConversation`) + WebSocket; server-side idle alarm | | Placement | 4th persona, login-gated (reuses existing auth); own budget: **20 messages / 5h / user** | | Media | Cloudflare R2 (`aria-media` bucket), signed URLs passed to the brain | | Voice | Polish-first / auto-detect; witty young-adult friend, no emojis, rare "XD/lmao" | ## Topology ``` Browser (aria.html + aria-chat.js) │ HTTPS (REST: history, upload-url) │ WSS (live events/bubbles) ▼ ▼ Cloudflare Pages app.nnlabs.pl (APP_WEBSITE/_worker.js) • validates nnl_session cookie + usage window (REUSED) • /api/aria/* → service binding → aria-worker │ ▼ aria-worker (standard Worker) • routes REST + WS upgrade • binding: ARIA_DO (Durable Object) • binding: ARIA_MEDIA (R2) • binding: DB (D1, shared app-nnlabs-db) │ ┌───────────────┴───────────────┐ ▼ ▼ AriaConversation DO nextneural-aria.hf.space • per-conversation state (Gradio queue/join + SSE) • event log + clustering • vision + reasoning • idle alarm (10s) → proactive • returns JSON bubbles • fan-out bubbles over WS ``` **Why a separate Worker:** Cloudflare Pages Advanced Mode cannot *define* a Durable Object. The DO + R2 live in a standalone Worker; the existing Pages `_worker.js` forwards `/api/aria/*` to it via a service binding after enforcing auth. NINA/IRIS/LUNA code is never touched. ## Event-driven model Every input is an **event** (`{ id, ts, type, payload }`): - `message` — text. payload `{ text }` - `image` — image upload. payload `{ key, url, mime, name }` - `file` — generic file. payload `{ key, url, mime, name, size }` - `system_idle` — emitted by the DO after 10s of user inactivity. payload `{ since }` ### Turn lifecycle (inside the DO) 1. Client sends user event(s) over WS → DO appends to the event log, persists to D1. 2. DO **clusters** consecutive un-answered user events into one logical turn (debounced ~600ms so "i gruszki" sent right after "kup jabłka" is one context). 3. DO builds structured context (recent events + resolved topic) and calls the brain. 4. Brain returns `[{ bubble, target_event_id, type }]`. 5. DO streams `typing` then each `bubble` over WS, persists bubbles to D1. 6. DO (re)arms a 10s alarm. On fire it emits `system_idle`; the brain *may* return a `proactive` bubble (e.g. "co to?" for an image sent without text). Idle fires at most N times per turn to avoid nagging. ## Bubble contract (brain → DO → client) ```json [ { "bubble": "co to?", "target_event_id": "evt_123", "type": "proactive" }, { "bubble": "jabłka ogarnięte", "target_event_id": "evt_456", "type": "response" }, { "bubble": "gruszki też dorzucę", "target_event_id": "evt_457", "type": "follow_up" } ] ``` `type`: `response` (direct answer) · `follow_up` (continues a chained user msg like "i gruszki") · `proactive` (DO-initiated, usually after `system_idle` or a text-less image). ## WebSocket protocol (DO ↔ client) Client → DO: `{ t: "event", event: {id,ts,type,payload} }`, `{ t: "seen" }`, `{ t: "ping" }` DO → client: `{ t: "typing", on: true|false }`, `{ t: "bubble", bubble, target_event_id, kind }`, `{ t: "error", v }`, `{ t: "history", events, bubbles }`, `{ t: "pong" }` ## Persistence (D1 — see cloudflare/db/migration_aria.sql) - `aria_conversations` — one row per chat (user-owned, themed). - `aria_events` — append-only user/system event log. - `aria_bubbles` — assistant bubbles with their `target_event_id` + type. ## Usage budget ARIA enforces **20 messages per rolling 5h window per user**, tracked in its own `aria_usage` table (separate from the NINA/IRIS/LUNA `model_usage` pool — a messenger sends far more, shorter turns). The window starts at the first message and resets after 5h. Each user message (text, image, or file) costs one; `system_idle` and ARIA's own proactive bubbles never count. Enforcement lives in the Durable Object (`aria-worker/src/usage.js`) — the only layer that sees each message inside the socket. The DO pushes `{ t:"usage", remaining, resetAt }` on connect and after each message, and `{ t:"limit", resetAt }` when the budget is exhausted. ## Media Client uploads bytes via `POST /api/aria/conversations/:id/upload` (proxied to R2 by the worker), then sends an `image`/`file` event referencing the returned key. The DO mints a short-lived HMAC-signed GET URL to hand to the brain. An uploaded attachment is a message and so counts as one against the 20/5h budget. ## Reuse map (from NNLABS.PL/WEBSITE) - Auth, sessions, usage window, rate-limit → existing Pages `_worker.js` (unchanged). - Design tokens, `.chat-bubble`, `.chat-typing`, markdown renderer → reused by aria.css / aria-chat.js. - Gradio queue/join + SSE proxy pattern → reimplemented in aria-worker/orchestrator.js. - D1 database `app-nnlabs-db` → shared; ARIA adds its own tables only. ## Integration & safety `cloudflare/integrate.sh` copies the new files **additively** into the live site (no overwrites; refuses if a target exists and differs). The Pages `_worker.js` change is a small, reviewed snippet (`_worker.aria.js`) added by hand, not an overwrite.