PropPulse AI
An AI sales assistant for an independent real-estate broker in Addis Ababa. Buyers chat on Telegram or on the website in English or Amharic; the agent finds matching units, answers worries from stored facts, books site visits and calls, protects the broker's commission, and follows up on its own. The broker watches and steers everything from a live Command Center.
Stack: FastAPI · LangGraph · Gemini · Supabase Postgres + pgvector (RAG) · Scrapy + scrapy-playwright · Next.js 14 · Telegram · Google Calendar · Mapbox · Render + Vercel + GitHub Actions (all free).
Live: website proppulseagent.vercel.app (the broker's Command Center is at /console), Telegram bot @prop_plus_bot, backend health at https://proppulse-agent-44qv.onrender.com/health.
Where to look first
How it fits together
Buyer ── Telegram / web chat ──▶ FastAPI ──▶ LangGraph agent ──▶ Gemini (text, structured, embeddings, voice, images)
│ │
GitHub Actions cron ─────────┤ ├─▶ Supabase Postgres + pgvector (units, projects, buyers, chats, checkpoints, event log)
(reminders, daily run, │ ├─▶ Google Calendar (availability, bookings)
LLM sweep) │ └─▶ Mapbox (routes), Resend (developer emails)
│
Small developer sites ──▶ httpx + BeautifulSoup ──▶ Gemini ──┐
Large portals ──▶ Scrapy on GitHub Actions ──▶ local extraction (Gemini only as a fallback) ──┤
▼ ▼
Durable event log ──live stream──▶ Next.js Command Center IngestionService ─▶ units / projects
(CRM, takeover, board, map, brain, analytics, studio, projects, portals)
LangGraph: the agent
Each turn runs a LangGraph state machine and its state is checkpointed in Postgres, so conversations survive restarts.
flowchart LR
S([start]) --> intake
intake -- "human asked / frustrated" --> handoff
intake --> router
router -- search --> discovery
router -- details --> details
router -- affordability --> affordability
router -- compare --> analyst
router -- "book visit or call" --> scheduler
router -- small_talk --> smalltalk
discovery -- matches --> recommend
discovery -- "none, steps left" --> relaxer --> discovery
discovery -- "none, steps used up" --> waitlist
scheduler --> human_gate
intake: language, prompt-injection and hand-off checks, voice-note transcription, history compaction.router: button taps and known phrases are parsed in code; only free text costs a model call (one structured extraction).discovery → relaxer → discovery: a bounded loop that widens the search by rule when nothing fits (budget +12% and neighbouring areas, then +24% and any area), without ever changing what the buyer actually asked for.scheduler → human_gate: books through the calendar, orders multi-stop routes, registers the lead with the developer; a high-value booking hands the chat to the broker.- Every node is traced; the Agent Brain page draws the live graph and every step with timings, tokens and fall-backs.
RAG: how search works
- What is embedded: every unit (type, area, size, price, description and floor-plan tags read by the vision model), every project, and every buyer's preferences (Gemini embeddings, 768 dimensions, pgvector with HNSW).
- Forward search is hybrid: hard SQL filters (available, budget, bedrooms, areas) first, then cosine similarity with a tuned floor (0.64) so weak matches are dropped, then a nudge toward the more reliable developer (
match_properties_hybrid).
- Rules beat similarity where they should: "the cheapest" and "the largest" are deterministic SQL rankings with no embedding.
- Reverse search: a price drop or a new unit is matched against every buyer's preference vector (
match_buyers_for_property) so the right people are messaged privately.
- Retrieval is measured: 58 labelled messages, hit@3 100%, MRR 0.99 (table below).
Details, file names and the SQL: docs/ARCHITECTURE.md.
Two ingestion strategies
Listings arrive two ways and meet in one pipeline (IngestionService), which skips unchanged units for free, records price changes, and embeds only genuinely new units.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
