File size: 6,298 Bytes
4131875
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# 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.