wealth-alpha-chat-widget 1.0.1 → 1.0.2

package/docs/BACKEND_CHAT_WIDGET.md

@@ -1,357 +0,0 @@
-# Chat Widget Backend — Design & Frontend Integration Guide
-
-> **Scope of this doc**: covers only the two files I authored for the chat widget:
-> - `app/api_v1/chat_widget.py` — the widget's HTTP router (chip + multi-step + proxy)
-> - `app/api_v1/chat_formatters.py` — converts upstream JSON into chat-bubble text
->
-> The team-authored files (`chat.py` for persistence, `intent.py`, `ama.py`) are **out of scope** here.
-
----
-
-## 1. What problem does `chat_widget.py` solve?
-
-The npm library (`wealth-alpha-chat`) speaks one tiny protocol:
-
-```
-GET  /me                  → who is logged in?
-POST /chip/{chip_id}      → user clicked a chip
-POST /message             → user typed text
-```
-
-Each response is a `BotResponse`:
-
-```jsonc
-{
-  "message":   "text to show in the bubble",
-  "chips":     [{ "id": "...", "label": "...", "icon": "..." }],   // next chips
-  "sessionId": "ses_...",
-  "endOfFlow": false,
-  "metadata":  { "endpoint": "/api/v1/...", "inputs": { ... } }
-}
-```
-
-But your **business endpoints** (the 20 upstream telegram-api routes) speak a completely different language — they need specific query params (`symbol`, `entry_price`, `side`, `category`, `stance`, `market_range`, …) and return structured templates (`LONG_TERM`, `SWING`, `CRYPTO_ANALYSIS`, …).
-
-`chat_widget.py` is the **adapter** between those two worlds.
-
-```
-Browser (npm lib)
-  │ POST /chat-widget/chip/act_long_term  {sessionId:"abc"}
-  ▼
-chat_widget.py
-  │ chip "act_long_term" → prompt user for symbol
-  ▼ returns {message: "Type ticker", chips: [Back], awaiting: "symbol"}
-Browser shows prompt
-  │
-User types RELIANCE
-  │ POST /chat-widget/message  {message:"RELIANCE", sessionId:"abc"}
-  ▼
-chat_widget.py
-  │ session.awaiting=symbol → fill collected["symbol"]="RELIANCE"
-  │ all fields collected → call upstream
-  ▼ httpx GET /api/v1/stock-analysis/long-term_analysis?symbol=RELIANCE
-upstream returns JSON {template: "LONG_TERM", price_snapshot: {...}, signal: {...}, ...}
-  │
-  ▼ chat_formatters.format_payload(payload)
-  │ dispatches by `template` → format_long_term() → multi-line text with ₹, •, secti.ons
-  ▼ returns BotResponse {message: "📈 LONG-TERM\n...\n*SIGNAL*\n...", chips: [Back], endOfFlow: true}
-Browser shows formatted result in chat bubble
-```
-
----
-
-## 2. The three building blocks of `chat_widget.py`
-
-### A. Chip tree (`ROOT_CHIPS`, `NAV_TREE`, `ACTIONS`, `DIRECT_CALLS`)
-
-A chip is one of three kinds:
-
-| Kind | Data structure | Behavior on click |
-|---|---|---|
-| **nav** | entry in `NAV_TREE` | Returns next-level chips. No upstream call. (e.g. `stock_analysis` → 6 analysis-type chips) |
-| **action** | entry in `ACTIONS` | Starts a multi-step flow: prompts the user for one field at a time, then fires the upstream call. (e.g. `act_position_summary` asks ticker → entry price → LONG/SHORT) |
-| **direct** | entry in `DIRECT_CALLS` | One click → immediately fires the upstream call with bundled params. (e.g. `macro_monetary` → `GET /market-forecast/macro?category=MONETARY`) |
-
-Special chip IDs:
-- `__root__` — return to the main 8-chip menu, clear pending state
-- `__set:FIELD=VALUE` — a chip that fills the currently-awaited field (e.g. `__set:side=LONG`)
-
-### B. Multi-step session store (`_SessionStore`)
-
-In-memory dict keyed by `sessionId`. Each entry:
-
-```python
-{
-  "action":     "act_position_summary",
-  "collected":  {"symbol": "BPCL", "entry_price": 310.0},
-  "awaiting":   "side",
-  "updated_at": 1716800000.0,
-}
-```
-
-TTL is 30 minutes (matches the frontend session). Each `/chip` or `/message` request either:
-- starts a new action (creates the entry with `collected={}`, `awaiting=fields[0].name`)
-- advances an action (fills `collected[awaiting]`, sets `awaiting` to next missing field)
-- fires the call (when all fields collected → `httpx` → format → response)
-
-> ⚠️ **Production note**: the dict lives in process memory. For multi-instance deploys, swap `_SessionStore` for a Redis-backed implementation. The interface (`get`, `set`, `clear`) is small enough that this is a 1-hour swap.
-
-### C. Upstream proxy (`_call_upstream`)
-
-Async `httpx.AsyncClient` that:
-- Re-uses the **caller's** `Authorization` header → upstream sees the same JWT
-- Derives base URL from the incoming `Request` → works under any host/scheme without config
-- Maps upstream HTTP errors into clean `{"_error": "..."}` payloads:
-  - `401`/`403` → "auth failed / premium required"
-  - `404` → "no data for these inputs"
-  - `5xx` → "try again shortly"
-
-The formatter (next section) checks for `_error` first and returns it as-is, so error text shows up in the chat bubble.
-
----
-
-## 3. How `chat_formatters.py` works
-
-One Python function per template. Each turns a JSON payload into bubble-friendly text using `•` bullets, `*headings*`, `₹` / `$`, `+/−` percentages.
-
-### Dispatcher
-
-```python
-_TEMPLATE_MAP = {
-    "LONG_TERM":          format_long_term,
-    "LONG_TERM_DETAILED": format_long_term_detailed,
-    "SWING":              format_swing,
-    "INTRADAY":           format_intraday,
-    "POSITION_SUMMARY":   format_position_summary,
-    "POSITION_DETAILED":  format_position_detailed,
-    "PORTFOLIO_CONSTRUCT":  format_portfolio_construct,
-    "EXISTING_PORTFOLIO":   format_existing_portfolio,
-    "PORTFOLIO_REBALANCE":  format_portfolio_rebalance,
-    "MACRO_EVENT_UPDATE":   format_macro_event,
-    "MACRO_OVERVIEW":       format_macro_event,
-    "CRYPTO_ANALYSIS":      format_crypto_analysis,
-    "CRYPTO_LIST":          format_crypto_list,
-    "CRYPTO_LIST_ITEM":     format_crypto_list_item,
-    "SMART_MONEY_PICKS":    format_smart_money_picks,
-    "POTENTIAL_STARS":      format_potential_stars,
-    "EXIT_WATCH":           format_exit_watch,
-    "PEER_COMPARISON":      format_peer_comparison,
-}
-
-def format_payload(payload, fallback_prefix=""):
-    # 1. error short-circuit
-    if isinstance(payload, dict) and "_error" in payload:
-        return payload["_error"]
-    # 2. shape detection for sector-news / discovery / IPO (no template field)
-    # 3. template dispatch via _TEMPLATE_MAP
-    # 4. unknown → compact JSON dump
-```
-
-### Helper toolbox
-
-Shared building blocks all formatters use:
-- `_money_rs(value)` → `₹1,450.25`
-- `_money_usd(value)` → `$2,369.41`
-- `_pct(value)` → `+1.23%` / `-4.47%`
-- `_bullet_list(items, limit=10)` → `• item1\n• item2\n• … and 5 more`
-- `_section(title, body)` → `\n*TITLE*\nbody`
-- `_format_signal()`, `_format_invalidation()`, `_format_business_health()`, `_format_indicators()`, `_format_peers()` — composable sub-blocks reused across LONG_TERM, SWING, POSITION_*, etc.
-
-### Why backend-side formatting
-
-| | Format on backend | Format on frontend |
-|---|---|---|
-| Iterate text without rebuilding library | ✅ | ❌ npm publish/install loop |
-| Bundle size | Smaller (no 16 formatters in JS) | Larger |
-| Reusable for Telegram bot | ✅ same Python code | ❌ would need a JS port |
-| Compliance redaction (omit fields) | ✅ at the boundary | ❌ raw data already in browser |
-| Trade-off: structured rich UI (cards) later | Need to switch to passing raw JSON | Already raw on client |
-
-The current `BotResponse.message` is plain text. `BotResponse.metadata` includes `endpoint` and `inputs` for tracing/debugging — and if you later want structured rendering, you can move the raw payload there.
-
----
-
-## 4. The 20 upstream endpoints — exact mapping
-
-Every chip ID lives in one of these dicts (in `chat_widget.py`):
-
-### `ACTIONS` (multi-step — collect inputs then fire)
-
-| Chip ID | Upstream | Fields collected |
-|---|---|---|
-| `act_long_term` | `GET /api/v1/stock-analysis/long-term_analysis` | `symbol` |
-| `act_long_term_detail` | `GET /api/v1/stock-analysis/long-term_detail_analysis` | `symbol` |
-| `act_swing_trade` | `GET /api/v1/stock-analysis/swing_trade_analysis` | `symbol` |
-| `act_intraday` | `GET /api/v1/stock-analysis/intraday_analysis` | `symbol` |
-| `act_position_summary` | `GET /api/v1/stock-analysis/existing_investor_position_analysis` | `symbol`, `entry_price`, `side` |
-| `act_position_detail` | `GET /api/v1/stock-analysis/existing_investor_position_analysis_detailed` | `symbol`, `entry_price`, `side` |
-| `act_portfolio_construct` | `POST /api/v1/portfolio-construct/construct` (body) | `capital`, `risk_port_pct` |
-| `act_portfolio_analyze` | `GET /api/v1/portfolio-existing/analyze` | `portfolio_id` |
-| `act_portfolio_rebalance` | `GET /api/v1/portfolio-existing/rebalance` | `portfolio_id` |
-| `act_sector_news` | `GET /api/v1/market-forecast/sector-news` | `sector` |
-| `act_crypto_analyze` | `GET /api/v1/crypto/analyze` | `symbol` |
-| `act_crypto_coin` | `GET /api/v1/crypto/coin` | `symbol` |
-| `act_peer_compare` | `GET /api/v1/peer-analysis` | `symbol` |
-
-### `DIRECT_CALLS` (one click — params bundled)
-
-| Chip ID | Upstream | Bundled params |
-|---|---|---|
-| `macro_{monetary,economic,markets,policy,global}` | `GET /market-forecast/macro` | `category=…` |
-| `crypto_list_{investible,watchlist,avoid}` | `GET /crypto/crypto_list` | `stance=…` |
-| `smart_money_{large,mid,small}` | `GET /tg-tradable-candidate/smart-money-picks` | `market_range=…` |
-| `stars_{large,mid,small}` | `GET /tg-tradable-candidate/potential-stars` | `market_range=…` |
-| `exit_{large,mid,small}` | `GET /tg-tradable-candidate/exit-watch` | `market_range=…` |
-| `discover_{large,mid,small}` | `GET /stock-ranks/discovery/stocks` | `sector=all, market_range=…, timeframe=D` |
-| `ipo_{large,mid,small}` | `GET /stock-ranks/discovery/ipo-stocks` | `sector=all, market_range=…` |
-
----
-
-## 5. How the frontend library plugs into this
-
-```tsx
-<WealthChat
-  apiBase="http://localhost:8013/api/v1/chat-widget"   // ← the chat router prefix
-  authCheck="/me"                                       // → GET {apiBase}/me
-  loginUrl="/login"
-  sessionTTL={1800}                                     // 30 min sliding
-  brandName="Wealth Alpha AI"
-  brandColor="#1a2d5a"
-  position="bottom-right"
-/>
-```
-
-The library appends `/me`, `/chip/{id}`, `/message` to `apiBase`. **Do not include `/chat/` in apiBase or it doubles up** (was the recent 404 cause).
-
-### Token discovery (no bridge required)
-
-`readSession()` looks for a JWT in this order:
-1. `localStorage["wac_session"].token` (full session — written by the library itself, or by the host app for custom flows)
-2. `localStorage["token"]` (your app's normal login key)
-3. `localStorage["access_token"]`, `localStorage["auth_token"]`, `localStorage["jwt"]` (other common keys)
-
-If a raw JWT is found, the library decodes its `exp` and `id` claims, builds a session on the fly, and persists it as `wac_session` for subsequent reads. On logout (the fallback key is removed), the library clears `wac_session` automatically — no host-side sync code needed.
-
----
-
-## 6. Three ways to improve / extend on the library side
-
-Pick one based on how much surface area you want to give the host app. Each is independent and can be done without touching the backend.
-
-### Option A — Render structured cards instead of plain text (highest visual impact)
-
-Today the bubble shows `BotResponse.message` as `pre-wrap` text. Cards would render:
-
-```
-┌─ RELIANCE — Reliance Industries Ltd ────────┐
-│ Energy · As of 27 May 2026                  │
-│ Price ₹1,450.25   +1.23%                    │
-│ 52W high ₹1,600 (-9.36%)  low ₹1,100 (+32%) │
-│ ─── SIGNAL ─────────────────────────────    │
-│ [BUY] Long · Entry ₹1,455 · Stop ₹1,390     │
-│ T1 ₹1,550 (+6.5%)  R/R 1:2.1                │
-└─────────────────────────────────────────────┘
-```
-
-**What to change:**
-- Backend: stop formatting in `chat_formatters.py` — put the raw payload in `BotResponse.metadata.payload`
-- Library: add a `<TemplateCard template={metadata.template} data={metadata.payload} />` component, with sub-components per template (`<LongTermCard>`, `<SwingCard>`, `<PositionCard>`, …)
-- Trade-off: ~16 React components to write + maintain. Library bundle ~2× larger. But the UI is dramatically better.
-
-### Option B — Streaming token-by-token responses (best perceived speed)
-
-When you add the AI Research Analyst (LLM-powered free-text), responses can take 5–10 s. Streaming makes them feel instant.
-
-**What to change:**
-- Backend: add `/chat-widget/stream` SSE endpoint that yields chunks
-- Library: open an `EventSource` instead of `fetch`, append tokens to the active bubble as they arrive
-- Trade-off: ~150 lines of new code; requires CORS to allow `text/event-stream`; harder to retry on disconnect
-
-### Option C — Pluggable token / chat-tree config (most reusable across projects)
-
-Make the library generic enough to drop into any host app or any backend.
-
-**What to change:**
-- Add props: `getToken?: () => string | null`, `tokenStorageKey?: string`, `welcomeBuilder?: (user) => string`
-- Add prop: `chipTree?: ChipTree` — let the host app override the root chips and labels without touching the npm package
-- Trade-off: more API surface; documentation effort
-
-### Honorable mention — Persist chat history server-side
-
-The team's new `chat.py` already exposes `/api/v1/chat/conversation` and `/api/v1/chat/session/{id}`. Have the library `POST /chat/conversation` after each turn so the conversation is recoverable across devices, not just `localStorage`. ~50 lines, big UX win.
-
----
-
-## 7. Where each piece lives — file map
-
-```
-WealthAlpha-Backend/
-  app/api_v1/
-    chat_widget.py        ← chip router, multi-step state, upstream proxy
-    chat_formatters.py    ← 18 templates → text
-    router.py             ← includes chat_widget at prefix "/chat-widget"
-  app/utils/auth.py       ← get_current_user dep (reused, untouched)
-
-Wealth-alpha-chat-UI/    (the npm library)
-  src/
-    components/WealthChat.tsx     ← entry component, props, welcome
-    components/AuthGate.tsx       ← login required panel + disclaimer
-    components/ChatBody.tsx       ← scrolling message list
-    components/MessageBubble.tsx  ← single message + chips
-    api/chatApi.ts                ← fetch wrapper (timeout, retry, auth, abort)
-    hooks/useAuth.ts              ← /me check
-    hooks/useChat.ts              ← message state + sendText
-    hooks/useChip.ts              ← chip click → sendChip
-    hooks/useSession.ts           ← TTL, sliding window, storage events
-    utils/session.ts              ← localStorage adapter (auto-discovers JWT)
-
-WealthAlpha-Frontend/    (consumer)
-  src/app/layout.tsx              ← <WealthChat apiBase="…/chat-widget" />
-  .env.local                      ← NEXT_PUBLIC_API_BASE, NEXT_PUBLIC_CHAT_DEMO
-```
-
----
-
-## 8. The 4 reliable commands while developing
-
-```bash
-# Backend reload (when chat_widget.py or chat_formatters.py changes)
-cd WealthAlpha-Backend && source venv/bin/activate
-uvicorn main:app --reload --port 8013
-
-# Library rebuild & ship (when src/ changes)
-cd Wealth-alpha-chat-UI
-npm run typecheck && npm run build && npm pack
-
-# Frontend pickup
-cd ../WealthAlpha-Frontend
-npm install ../Wealth-alpha-chat-UI/wealth-alpha-chat-0.1.0.tgz --force
-rm -rf .next && npm run dev
-
-# Smoke-test from terminal (no UI needed)
-TOKEN=$(curl -s -X POST http://localhost:8013/api/v1/auth/login \
-  -H 'Content-Type: application/json' \
-  -d '{"email":"you@example.com","password":"…"}' | jq -r '.data')
-
-curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8013/api/v1/chat-widget/me
-curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-  -X POST http://localhost:8013/api/v1/chat-widget/chip/stock_analysis \
-  -d '{"chipId":"stock_analysis","sessionId":"test"}'
-```
-
----
-
-## 9. Common failures & exact fixes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| `404 /chat-widget/chat/chip/…` (path doubled) | `apiBase` ended with `/chat-widget` AND library prefixed `/chat/` | Fixed in chatApi.ts — now uses `/chip/{id}` & `/message` |
-| `401 Unauthorized` on `/chat-widget/me` | Library couldn't find a JWT, OR JWT expired | Library now reads `localStorage["token"]` as fallback. Or re-login to refresh the JWT. |
-| Chat shows AuthGate even when logged in | `wac_session` has stale token, host's `token` key not detected | `localStorage.removeItem("wac_session"); location.reload();` |
-| `Upstream /api/v1/… is unreachable` | The 14 telegram-api routes not registered in `router.py` | Already fixed — they're included at the bottom of router.py |
-| `503` or `httpx.SSL` after deploy | Reverse proxy strips `X-Forwarded-Proto` | `uvicorn main:app --proxy-headers --forwarded-allow-ips='*'` |
-| Chip click does nothing | Chip ID not in `ROOT_CHIPS`/`NAV_TREE`/`ACTIONS`/`DIRECT_CALLS` | Check `chat_widget.py` — add the entry, restart backend |
-
----
-
-*Doc version: 1.0 — kept beside the npm library for easy reference. Update when the chip tree or formatter list changes.*