Spaces:
Paused
Paused
Malina
Claude Opus 4.8
ARIA: event-driven multimodal agent (brain + Cloudflare backend + Messenger UI)
4131875 |
Download ARIA_ARCHITECTURE.md from NextNeural/ARIA: direct link, hf CLI and curl.
- Browser
- Download file 6.3 kB
-
https://huggingface.co/spaces/NextNeural/ARIA/resolve/main/ARIA_ARCHITECTURE.md
- Command line
-
hf download hf://spaces/NextNeural/ARIA/ARIA_ARCHITECTURE.md
-
curl -L -o ARIA_ARCHITECTURE.md https://huggingface.co/spaces/NextNeural/ARIA/resolve/main/ARIA_ARCHITECTURE.md
6.3 kB
| # 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. | |