Skip to main content
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

ActionEndpointDescription
ListGET /api/v1/visual-embedsAll embeds, optionally filter by category_id
GetGET /api/v1/visual-embeds/{id}Single embed by MongoDB ID
CreatePOST /api/v1/visual-embedsAdd new embed
Bulk createPOST /api/v1/visual-embeds/bulkAdd multiple embeds
UpdatePATCH /api/v1/visual-embeds/{id}Modify embed
DeleteDELETE /api/v1/visual-embeds/{id}Remove embed
CategoriesGET /api/v1/visual-embeds/categoriesList all categories
See the endpoint pages for request bodies, parameter constraints, and example responses pulled directly from the OpenAPI schema.

​
Categories

IDDisplay NameKeywords
AssetAllocationAsset Allocationasset allocation, portfolio mix, rebalance
Debt_Fix_IncomeDebt & Fixed Incomedebt, fixed income, bonds
EmergencyFundEmergency Fundemergency fund, liquidity
Goal_Based_InvestingGoal-Based Investinggoal based, education goal
InsuranceInsuranceinsurance, term insurance
Mutual_FundsMutual Fundsmutual fund, sip, index fund
Portfolio_ReviewPortfolio Reviewportfolio review
Real_EstateReal Estatereal estate, property
Retirement_PlanningRetirement Planningretirement, corpus
Tax_PlanningTax Planningtax, 80C, deduction

​
How it works

  1. Chat service generates AI response
  2. Visual Planner (LLM) decides if visual should attach
  3. Visual Embed Service queries visual_embeds by category
  4. Business rules checked in Redis (max 3/session, no repeats)
  5. Visual URL attached to response
Images stored in GCS: gs://handa-visuals/{Category}/{filename.png}