# HOMMICA — Design (Living Document)
**Hyperpersonalized · Omnichannel · Multi-modal · Multi-lingual · Interactive · Conversational Assistant for a Bank** *(né Omica)*
> Status: v0.7 — **physicalized and deployed** on the AWS-native stack (with the deliberate hybrid at the voice edge). Contracts held (MCP is the one protocol for tools, surfaces, agents). Design goal: **simple, robust, super-delightful** — and grown by adding config files, not code.
_Last updated: 2026-07-09_
---
## 1. What Omica is (one line)
Omica is **one assistant across every channel, for customers and employees** — a voice-first, real-time conversational presence with a deep multimodal persona, that converses first, owns its own memory, co-drives interactive surfaces, and quietly orchestrates a Personalization/Risk/Pricing brain, enterprise context, and background helper agents — in the customer's own (often Thai-English code-mixed) voice, across all sales and service intents up to wealth advisory and financial concierge.
## 2. Guiding principles (the invariants)
1. **One assistant, every surface, both audiences.** One continuous conversation, one memory. Serves customers and employees (RMs, advisors, contact-center, branch) on the same engine.
2. **Voice-first, client-independent, provider-agnostic.** Voice is the native lead modality. The voice-to-voice engine is chosen by performance (esp. Thai), decoupled at the edge, and swappable without touching the brain.
3. **Any conversation is the entry point.** Live voice, voice message, text, SMS, LINE, image — openings of the same conversation.
4. **Persona is a deep, multimodal object — distinct from the orchestrator.** Voice, tone, register, empathy, language-mix, brand, across voice/text/visual. Shifts by segment × context × audience. The orchestrator drives *intent*; the persona *embodies*.
5. **Identity and context travel with the subject, not the channel.**
6. **Conversation-first; events are a byproduct, not a subsystem.** Omica converses and simply *emits* a structured record (`lead` / `service_request` / `complaint`) when the moment arises. No standing event-mining stream — it's just conversation flow.
7. **Like a good human agent.** On call-landing, memory + real-time context are retrieved so the agent picks up *already knowing the person*. Once the customer reveals intent, that intent becomes a **deterministic outcome the orchestrator drives toward**, while the persona **manages the expectation** (pacing, reassuring) in real time. The human feel comes from expectation management, not speculation (§6).
8. **Interactive by co-experience.** Omica summons and drives surfaces as MCP tools — show a calculator, co-fill a form. **Only submit/approve stay with the human.**
9. **Omica orchestrates; it delegates heavy work.** Specialist/background agents are reached as MCP entries in the enterprise context layer — not a separate registry to maintain.
10. **Probabilistic brain ≠ deterministic brain.** The **Personalization, Risk & Pricing (PRP) brain** decides personalization, offers/NBA, risk, pricing, routing, eligibility — auditable. Omica presents; it never originates a commercial or risk decision.
11. **We own the memory substrate.** MECE by type (§8). CRM is *mined from* it.
12. **Trust is inline.** Grounding, authorization, PII, disclosures, consent, audit — cross-cutting.
13. **Composability via MCP.** Tools, surfaces (BFF), agents, PRP brain — all register and invoke over MCP.
14. **Externalize and scale by configuration.** Events, memory rules, personas, playbooks live in md/skill config. Start minimal; grow by *adding files*, never by complicating the core.
## 3. North star (ranked bundle)
Effortless continuity · proactive advice · resolution speed · easy to understand · barge-in/interruptible · segment- and tier-aware · speaks the customer's language (Thai-English, regional nuance) · co-experience (talks *and* shows/does). Overriding aim: **simple, robust, super-delightful.**
## 4. Audiences & coverage
**Audiences:** customers **and** employees — same engine; persona + permissions shift by audience.
**Coverage:** all sales + service intents across all channels — everyday service, product sales & onboarding (incl. mortgages, insurance), **wealth advisory** and **financial concierge** (both **capabilities of Omica**, not external agents).
## 5. Architecture — layers as MCP-registrable contracts
| # | Layer | Responsibility |
|---|-------|----------------|
| 1 | **Surfaces / entry** | Deployed: website chat widget — **text, full-duplex live voice (barge-in), document/image attachments**, able to **navigate, show context, co-fill forms, keep living checklists, and offer the bank's real pages**. Any conversation form; customer or employee. |
| 2 | **Persona layer** | Deep multimodal identity (voice, tone, register, empathy, language-mix, brand). Shifts by segment × context × audience. Distinct from orchestrator. |
| 3 | **Real-time interaction layer (fast loop)** | Embodies persona. Provider-agnostic speech-to-speech, turn-taking, barge-in, backchannel. Holds the floor. (Deployed: TWO selectable engines behind the same seam — OpenAI Realtime GA (gpt-realtime-2.1) and Gemini Live (gemini-3.1-flash-live-preview), each with per-persona voices, consulting the deep brain via one tool. Nova Sonic still lacks Thai.) |
| 4 | **Modality adapters** | Normalize any input → canonical turn; render out (speak/text/visual). |
| 5 | **Identity & continuity** | Resolve subject (customer/employee); stitch sessions; continuity token. |
| 6 | **Orchestrator (HOMMICA core)** | Converse, understand, orchestrate intents, emit event records, read/write memory, call tools/agents via MCP. Brain on Amazon Bedrock, model-agnostic (DeepSeek V3.2 today; Claude one env var away, pending a Marketplace payment unlock). |
| 7 | **Memory substrate (owned)** | MECE memory + memory agents (§8). Source the CRM mines. (Deployed: DynamoDB — persists across redeploys, native TTLs on tokens/parked threads; fs driver for keyless local dev; `npm run reset-demo` returns to seeds.) |
| 8 | **Personalization, Risk & Pricing brain** | Deterministic decisions (personalization, NBA/offer, risk, pricing, routing, eligibility). Auditable. **Stubbed day-1**; consumes/emits whatever shape the bank exposes, behind the MCP contract. |
| 9 | **Enterprise Context Layer** | Broader than a knowledge base: product/policy knowledge **+** system-of-record context **+** available tools & specialist agents (as MCP entries). What is true about the bank/world. |
| 10 | **Capabilities / actions + surface control** | Typed MCP tools: read, write, BFF surface-control. Submit/approve human-gated. |
| 11 | **Trust, guardrails, observability, audit** | Cross-cutting. |
## 6. How it works — like a good human agent
Three beats, in order. No speculation, no branch pre-fetching.
```
1) CALL LANDS
   → retrieve memory + real-time context for this subject
   → the persona-embodied agent picks up ALREADY KNOWING the person
        (continuity, history, who they are — like a good rep with your file open)
2) CUSTOMER REVEALS INTENT (through conversation)
   → the revealed intent becomes a DETERMINISTIC OUTCOME
   → the ORCHESTRATOR drives toward that outcome:
        · PRP brain for decisions (offer / risk / price / eligibility)
        · specialist agents via MCP for heavy work (ops, doc-read, analytics)
        · enterprise context + memory fused as needed
        · surface-control tools to show/co-fill  [submit/approve = human]
3) THROUGHOUT
   → the PERSONA manages the expectation in real time:
        holds the floor, paces, reassures ("let me get that sorted"),
        so the async work behind it feels human and immediate.
```
**Why it's simple & robust:** the orchestrator is driving one revealed intent to a determinate end, not juggling speculative work; the persona's job is expectation management, not prediction. Fan-out to tools/agents happens over MCP *only when the driven outcome needs it*.
## 7. The primitive flow
```
conversation opens (open dialogue — voice/text/image/etc.)
  → persona-embodied real-time layer holds the floor
  → resolve subject identity & continuity
  → on landing: retrieve memory + real-time context (agent picks up already knowing the person)
  → Omica: converse until intent is revealed → drive it as a deterministic outcome
      ├─ decision needed?  → PRP brain (NBA / offer / risk / price / route / eligibility)
      ├─ heavy task?       → specialist agent via MCP (ops, doc-read, analytics)
      └─ show/do?          → BFF surface-control tool (calculator, co-fill form)  [submit/approve = human]
  → guardrail + authorize + consent check
  → persona renders response across modality (voice/tone/depth/segment/tier/audience/code-mix)
  → emit event record if warranted (lead / service_request / complaint)
  → memory formation: consolidate + distill
```
## 8. Memory model (owned substrate) — MECE
**Axes:** *type* × *lifecycle*; governance cross-cutting.
| Type | Holds | Scope |
|------|-------|-------|
| **Working** | Live attention buffer + staged helper results for the turn | In-turn, ephemeral |
| **Conversational / Session** | Full dialogue state (*parked* = suspended-but-resumable, any channel) | Session |
| **Episodic** | Time-indexed record of what happened across the relationship | Long-term, raw |
| **Semantic** | Distilled durable truths: identity, preferences, financial profile, goals/desires, relationships | Long-term, distilled |
| **Procedural** | Learned playbooks, resolution paths, skills | Long-term, distilled |
| **Consent / Regulatory** | Permissions, disclosures, KYC/AML state, data-use scope | Long-term, governed |
**Lifecycle:** capture → consolidate → distill (episodic → semantic/procedural) → decay/forget → **mine** (CRM & downstream derived from semantic + episodic).
**Governance (every item):** provenance · confidence · source-of-truth pointer · access scope (customer/employee/regulator) · retention/TTL.
**Subject:** memory keyed to a subject (customer or employee).
**Memory agents (externalized, rules-driven; prompt-directed for now):**
- **Formation** — what to consolidate/distill.
- **Retriever** — fetch the right memory for the turn (runs as a background helper).
- **Miner** — apply rules to surface patterns for CRM / PRP brain.
### 8.1 Memory ↔ Enterprise Context (how they interact)
Two clean stores with clear ownership:
- **Enterprise Context** = *shared, authoritative, about the bank/world* — products, policies, system-of-record state, available tools/agents.
- **Memory** = *subject-specific, owned, about this person/relationship.*
Interaction each turn: the orchestrator (via helpers) **fuses both** — memory answers *who this is and what happened*; enterprise context answers *what's true and possible now*. Memory often acts as a **personalized index into** enterprise context (e.g., "your mortgage" → resolves to the enterprise loan record). Semantic memory is distilled partly from what surfaces in enterprise context; conversely the **CRM (enterprise) is mined from memory**. Ownership stays one-directional even though data flows both ways.
## 9. Events (emitted, not mined) — starter set, externalized
Website day-1 needs only three; each an externalized md/skill definition, extended by adding files.
| Event | Fires when the customer... | Consumer |
|-------|----------------------------|----------|
| `lead` | shows interest in **any product** | PRP brain → CRM |
| `service_request` | needs **any servicing** action | orchestrator / specialist agent |
| `complaint` | expresses a **complaint / dissatisfaction** | service routing + audit |
Uniform object: `{ id, subject_id, type, payload, evidence, confidence, channel, timestamp, status }`. Emitted inline as part of conversation flow.
## 10. Persona catalog — starter, externalized
Externalized definitions selected by `segment (income × age) × context × audience`. Seed with 3; add more as files.
| Persona | Segment | Register (illustrative) |
|---------|---------|-------------------------|
| **Kao (น้องเก้า)** (P1) | Everyday mass — low income any age + middle-income seniors | Slower, warmer, plainer; patient, reassuring; heavier Thai |
| **Friday** (P2) | Affluent & young/working age (also the employee default) | Efficient, friendly, balanced Thai-English; practical |
| **Jarvis** (P3) | Wealthy — private-banking tier, any age | Polished, concise, advisory; discreet concierge tone |
## 11. Settled decisions
- MCP is the single protocol for tools, surfaces (BFF), agents, PRP brain.
- Voice-first, provider-agnostic; Thai drives engine choice — OpenAI Realtime (GA, gpt-realtime-2.1) deployed behind the swappable edge adapter. Voice external, brain/memory/tools on AWS — deliberate hybrid, running in production.
- Persona = deep multimodal object, distinct from orchestrator; shifts by segment × context × audience.
- Deterministic brain = **Personalization, Risk & Pricing** brain.
- Serves customers **and** employees; entry from any conversation form.
- Events are **emitted inline** (`lead` / `service_request` / `complaint`), not a mining subsystem.
- **Enterprise Context Layer** replaces the knowledge layer and absorbs the specialist-agent registry (agents = MCP entries).
- Works like a good human agent: retrieve memory + real-time context on landing; revealed intent → deterministic outcome the orchestrator drives; persona manages expectation. No speculation; fan-out over MCP only when the driven outcome needs it.
- Omica owns memory (MECE); CRM mined from it. Submit/approve human-gated.
- Externalize everything behavioral as md/skill config. Starter: 3 events, 3 personas, memory agents prompt-directed.
- Deployed surface: website chat widget (text / full-duplex live voice / document attachments) with navigate, show-context, calculators, portfolio & benefit-illustration views, living checklists, co-fill forms (submit human-gated), and real-bank-page link cards. The voice-message (record-then-transcribe) path was retired in favor of full duplex.
## 12. Open questions (to resolve next)
- **Claude on Bedrock** — the model responds; blocked only by an AWS Marketplace payment-instrument issue on the account. One env var to flip when cleared.
- **Scale-out** — memory writes are serialized in-process (service runs one task); move to conditional writes before running multiple tasks.
- **Sharing gate** — the demo URL is public; add a passcode gate before wide circulation.
- **Response streaming** — replies land whole; streaming the brain's output would cut perceived latency further (hold-lines now cover the wait, but streaming is the real fix).
- **Event consumers** — events are durable (CloudWatch) with a status lifecycle, but the lead→CRM / complaint→routing consumers remain stubs until integration.
- **Working-memory construct** — the design's in-turn attention buffer is currently the raw message history; a distinct working-memory layer is deferred.
*Deferred to integration time:* PRP decision-object shape (stubbed; consume what the bank exposes), segment/tier source of truth, employee-mode permission specifics.
*Resolved:* physicalization — deployed on CloudFront → ALB → Fargate + Bedrock + DynamoDB + CodeBuild/ECR + Secrets Manager (details: infra/aws.md; repo: github.com/prankiie/omica).
---
_Changelog_
- v0.7.5b (2026-07-28): Streaming gate moved to its proper layer — the Bedrock adapter owns the DeepSeek stream-after-tools quirk (orchestrator is provider-agnostic again); models without the quirk (e.g. Claude, once unlocked) stream the FULL tool loop automatically, watchdog unchanged.
- v0.7.5 (2026-07-28): Latency & scope, from field feedback. Acknowledgment now truly instantaneous (sent at the socket, before the turn queue — ~1ms); replies STREAM into the widget as drafts (Bedrock ConverseStream, first round; stall watchdog falls back to non-streaming); independent tool calls execute in parallel; efficiency prompt rules (batch tools, ≤2 rounds for simple questions). SCOPE hard rule added to brain and both voice fast-loops: banking/SCBX only — off-topic questions (news, sports, trivia) get a one-line decline + redirect, never an answer. Flagship refi turn: ack 1ms · first text +1.9s · calculator +2.9s · complete +7.1s.
- v0.7.4 (2026-07-09): Conformance hardening after a 34-agent design audit (26 confirmed findings): chat↔voice now share live conversational state both ways (voice briefing + fast-loop notes folded into the deep brain's history); access-scope governance ENFORCED (was a no-op — internal notes now fenced from customers, recall/miner scope-filtered, miner PII-redacted); audit/events/PRP trails mirrored to CloudWatch (were ephemeral); turns serialized per session (no interleaved histories); landing is instant with the greeting streaming behind; hold-line fires at turn start; PRP decision_refs verified against actually-issued decisions; event status lifecycle added (update_event_status); parked summaries carry a resumable tail; ✕ truly ends the session (park + formation); calculator chrome bilingual; neutral bilingual fallback line; last "Sathorn Bank" residue purged from the voice edge; retired voice-message code fully removed.
- v0.7.3 (2026-07-09): §6 beat 3 physicalized in VOICE: the deep-brain consult now runs asynchronously on both engines — Gemini via native NON_BLOCKING tools + INTERRUPT scheduling, OpenAI via a relay state machine that speaks one hold line whenever a consult outlives the calling turn, then delivers the answer the moment it lands. No more dead air on product questions; the persona holds the floor while the orchestrator works.
- v0.7.2 (2026-07-09): Voice-edge swappability PROVEN: second live engine added — Gemini Live (gemini-3.1-flash-live-preview, 16kHz in/24kHz out, auto language detection) beside OpenAI Realtime, runtime-selectable in the widget; per-persona voices on both (Kao=Aoede/coral, Friday=Puck/marin, Jarvis=Charon/cedar). The brain, personas, and tools were untouched — exactly the §2.2 claim.
- v0.7.1 (2026-07-09): Resilience for real visitors: ALB session stickiness (chat + voice pin to one task through rolling deploys) and widget auto-reconnect via continuity token (a dropped socket resumes instead of dying). Root cause: a visitor during a deploy window could land chat and voice on different tasks or get drained mid-conversation.
- v0.7 (2026-07-09): **Physicalized & deployed.** AWS: CloudFront→ALB→Fargate core, Bedrock brain (DeepSeek V3.2; Claude pending Marketplace unlock), DynamoDB persistent memory (native TTLs; `npm run reset-demo`), CodeBuild→ECR pipeline, Secrets Manager. Voice: full-duplex OpenAI Realtime GA relay (gpt-realtime-2.1, semantic VAD, barge-in, per-persona voices); voice-message path retired. Modality adapters: document/image attachments via a Bedrock vision doc-reader. Surface catalog: calculator, portfolio (PRP-grounded rebalance with decision provenance), benefit illustration (downside scenarios enforced), living checklist, declarative cards, real-bank-page link cards; mortgage document-collection journey. PRP gains a deterministic `rebalance` kind. Personas named **Kao/Friday/Jarvis** per segment spec. Enterprise context: real public SCBX facts, sourced & dated. Demo guide on the home page; language rule = customer's comfortable language (any language).
- v0.6.3 (2026-07-09): Working name adopted: **HOMMICA** — Hyperpersonalized Omnichannel Multi-modal Multi-lingual Interactive Conversational Assistant. Multi-lingual promoted to first-class (Thai, English, SEA-neighbour languages, expats & digital nomads). Vision (north star) and guiding principles presented separately in the demo. Mortgage-initiation document-collection journey added (living checklist + doc-reader + human-gated application).
- v0.6.2 (2026-07-09): PRP brain marked stubbed day-1 (consume/emit whatever the bank exposes, behind MCP); open questions trimmed to physicalization, rest deferred to integration.
- v0.6.1 (2026-07-09): Removed speculation from the interaction model. Reframed §6 to the good-human-agent model: retrieve memory + real-time context on landing; revealed intent → deterministic outcome the orchestrator drives; persona manages expectation.
- v0.6 (2026-07-09): Voice provider-agnostic (Thai: Nova Sonic unsupported → OpenAI Realtime candidate; hybrid). Knowledge → Enterprise Context Layer; specialist-agent registry absorbed as MCP entries. Event-mining stream removed — events emitted inline. Added foreground/background helper ("dwarves") collaboration model. Added Memory ↔ Enterprise Context interaction. Website widget scope fixed (text/voice message/live voice + navigate/show).
- v0.5 (2026-07-09): Externalize-and-scale principle; starter events; memory agents; starter persona catalog.
- v0.4 (2026-07-09): Persona split out; dual audience; PRP brain rename; MECE memory.
- v0.3 (2026-07-09): Conversation-first; events mined; wealth/concierge = capabilities.
- v0.2 (2026-07-08): Voice-first; two-brain voice; co-experience; owned memory.
- v0.1 (2026-07-08): Principles, north star, layers, flow.