# AI Agent — capabilities roadmap (2026-06-11)

The operator's capability brainstorm, mapped honestly against what exists.
WhatsApp access is currently suspended; everything marked **buildable now**
can be built and tested via the Playground/eval before the number returns.

Legend: ✅ live · 🔨 shipped this session · 📋 buildable now (no blockers) ·
🔌 needs WhatsApp back · 🔒 needs management approval / verified data.

## Qualification intelligence

| Capability | Status | Notes |
|---|---|---|
| Progressive profiling | ✅ live | Prompt-driven (budget, timeline, unit type, residency woven into conversation, never a form) + durable per-contact memory so nothing is re-asked across sessions. |
| Intent scoring (hot/warm/cold) | 🔨 shipped | `crm_lead` now requires a temperature read on every call; notes land in LeadRat prefixed `[HOT]/[WARM]/[COLD]`, re-graded as the conversation develops. **Open**: investigate whether LeadRat's `PUT /lead` exposes a proper tier/tag field instead of the note prefix. |
| Buyer type detection | 🔨 shipped | `buyerType` (end_user / investor / nri) on `crm_lead`, written into the CRM note; the prompt teaches when to infer it. Tone adaptation per type = a steering line in the Behaviour tab. |
| Returning lead detection | ✅ live | Bot recognises a contact with an existing CRM lead, skips re-qualification, and carries the memory profile into the prompt. |

## Property discovery

| Capability | Status | Notes |
|---|---|---|
| Project search (area/price/beds/handover) | 🔒 | Needs a listings/inventory source — management approval explicitly pending (behaviour charter). Once a source exists (developer XML feeds, an inventory sheet, or LeadRat projects), this is one `search_projects` tool + an import job. |
| Listing details on demand | 🔒 | Same dependency. |
| Area guide Q&A | 🔨 shipped (staged) | 9 area guides written in `docs/kb-pack/` (Marina, Downtown, Palm, Business Bay, JVC, Hills, Creek Harbour, Ranches, JLT) — qualitative, no unverified figures, import-ready. |
| Personalised recommendations | 🔒 v2 | Profile (already captured) × inventory (pending) — design is straightforward once listings exist. |
| Project comparison | 🔒 v2 | Same. |

## Education & trust building

| Capability | Status | Notes |
|---|---|---|
| Buying process explainer | 🔨 shipped (staged) | Three docs: ready-property step-by-step (MOU → NOC → DLD transfer), off-plan (escrow/Oqood/payment plans), buying remotely (POA). |
| Cost breakdown | 🔨 staged, 🔒 verify | Full DLD/agency/NOC/trustee/mortgage-fee doc written but `enabled: false` until the team verifies each figure. |
| Visa eligibility guide | 🔨 staged, 🔒 verify | Detailed Golden Visa + 2-year investor visa doc, `enabled: false` pending verification. |
| Mortgage calculator | 📋 next | Deterministic `mortgage_calculator` tool (LTV cap by profile, DBR check, monthly payment). Blocked only by the same verification: the team must sign off the LTV/DBR rules in `mortgages-verified.md` first, then the tool encodes them. |
| ROI & yield context | 🔨 staged, 🔒 verify | Yield-by-segment doc written, `enabled: false` until sales confirms current ranges. |

## CRM & data capture

| Capability | Status | Notes |
|---|---|---|
| Lead creation | ✅ live | First-contact lead in LeadRat, deduped, enriched via notes on every subsequent call, assignee configurable in the Behaviour tab. |
| Tag & segment writing | 📋 partial | Service, temperature, and buyer type already land in the CRM note. Real LeadRat tag-field writes need an API investigation; local platform tags (Contact.tags) are writable today and could mirror the same labels for in-app segments. |
| Conversation summary | ✅ partial / 📋 | A compact profile is maintained on the contact after every turn (memory service). A per-session structured note pushed to the CRM record is a small worker job on top. |
| Hot lead alert | 📋 logic / 🔌 delivery | Trigger is trivial now that temperature exists (`crm_lead` with `hot` → notify the assigned agent). Delivery needs WhatsApp back (or email/n8n meanwhile). |
| Re-engagement trigger | 🔌 + template | Phase-3 W3 as planned: hourly worker, 24h-window logic, one nudge cap. Needs WhatsApp + an approved re-engagement template. |

## Conversation management

| Capability | Status | Notes |
|---|---|---|
| Arabic / English | ✅ live | Per-message detection incl. code-switching; KB search is Unicode-aware. (KB content itself is still English-only — Arabic versions of the pack are a good follow-up.) |
| Session memory | ✅ live | In-conversation history (4h session scoping) + durable cross-session memory. |
| Out-of-scope handling | ✅ live | Prompt boundaries: declines off-topic/rude/competitor, steers back. |
| Human handoff | ✅ partial / 📋 | CRM-centric handoff is the live model (lead lands graded, team follows up). An explicit "talk to a human" tool — flag the conversation + alert the team mid-chat — is buildable now. |
| After-hours awareness | 📋 small | Inject Dubai time + business hours into the prompt; offer a callback window while continuing to qualify. |

## The enabler while WhatsApp is down: the eval harness (phase-3 W2)

The single highest-leverage build right now. Scripted multi-turn conversations
run against the real agent in dry-run (no sends, no CRM writes), producing a
readable transcript report per run. It is exactly what we CAN do without a
number, and it gates everything else: prompt edits, the KB pack going live,
temperature-grading quality, the DeepSeek swap, and the eventual cutover.
~15 fixtures are already specified in `plans/agent-phase-3-plan.md`.

> **Architecture note (2026-06-11):** before building the tool expansion below,
> read `plans/agent-architecture-review.md` — verified research says keep the
> single agent, but consolidate to ~8–12 namespaced workflow tools, modularize
> the prompt behind an intent route, and move retrieval to hybrid
> (pgvector + lexical, RRF) BEFORE the 50-doc KB lands.

## Suggested order (while WhatsApp is suspended)

1. **Team verifies the 4 staged figure docs** (`docs/kb-pack/*-verified.md`) →
   import the pack (`tools/kb-import`) → enable in the UI. The bot's factual
   range roughly triples.
2. **Eval harness** (W2) — then every later change ships with evidence.
3. **Mortgage calculator tool** (encodes the verified rules from step 1).
4. **Hot-lead alert + human-handoff tool + after-hours awareness** — small,
   independent, all testable in the Playground.
5. **LeadRat tag-field investigation** — upgrade temperature from note prefix
   to a real field/tag if the API allows.
6. When WhatsApp returns: live canary test → re-engagement worker (W3) →
   DeepSeek eval comparison (W4) → cutover gate (W5).
7. When management approves inventory: listings search/details/compare/
   recommendations as one workstream.