Visual Embeds API - Handa Uncle Platform

Visual embeds are quote images that get attached to AI responses based on semantic matching. Each embed belongs to a category and stores a GCS image URL plus optional quote text.

Quick facts

Base path: /api/v1/visual-embeds
MongoDB collections: visual_embeds, visual_categories
Auto-seeds from hardcoded manifest on first startup
Service caches DB results for 5 minutes

Surface area

Action	Endpoint	Description
List	`GET /api/v1/visual-embeds`	All embeds, optionally filter by `category_id`
Get	`GET /api/v1/visual-embeds/{id}`	Single embed by MongoDB ID
Create	`POST /api/v1/visual-embeds`	Add new embed
Bulk create	`POST /api/v1/visual-embeds/bulk`	Add multiple embeds
Update	`PATCH /api/v1/visual-embeds/{id}`	Modify embed
Delete	`DELETE /api/v1/visual-embeds/{id}`	Remove embed
Categories	`GET /api/v1/visual-embeds/categories`	List all categories

See the endpoint pages for request bodies, parameter constraints, and example responses pulled directly from the OpenAPI schema.

Categories

ID	Display Name	Keywords
`AssetAllocation`	Asset Allocation	asset allocation, portfolio mix, rebalance
`Debt_Fix_Income`	Debt & Fixed Income	debt, fixed income, bonds
`EmergencyFund`	Emergency Fund	emergency fund, liquidity
`Goal_Based_Investing`	Goal-Based Investing	goal based, education goal
`Insurance`	Insurance	insurance, term insurance
`Mutual_Funds`	Mutual Funds	mutual fund, sip, index fund
`Portfolio_Review`	Portfolio Review	portfolio review
`Real_Estate`	Real Estate	real estate, property
`Retirement_Planning`	Retirement Planning	retirement, corpus
`Tax_Planning`	Tax Planning	tax, 80C, deduction

How it works

Chat service generates AI response
Visual Planner (LLM) decides if visual should attach
Visual Embed Service queries visual_embeds by category
Business rules checked in Redis (max 3/session, no repeats)
Visual URL attached to response

Images stored in GCS: gs://handa-visuals/{Category}/{filename.png}