README.md

# AI Real Estate Sales Agent — Implementation Roadmap

## এই কোডটা কী

আগের ডিজাইন আলোচনায় ১২-১৪টা নোড, ৩টা এজেন্ট, ৫টা সাবগ্রাফ প্রস্তাব করা হয়েছিল।
সেটা ধারণাগতভাবে ঠিক, কিন্তু **প্রথম দিনেই সেটা বানাতে যাওয়া একটা ভুল** —
প্রতিটা নোড মানে একটা LLM round-trip, মানে বেশি latency + বেশি খরচ, আর ডিবাগ করা কঠিন।

তাই এখানে একটা **কাজ-চালানো ৪-নোড MVP** দেওয়া হলো, যেটা থেকে আপনি ইনক্রিমেন্টালি বাড়াবেন।

```
START
  │
  ▼
extract_profile      ← এক LLM call: profile update + intent + objection detect
  │
  ▼
evaluate_missing     ← pure python, LLM লাগে না
  │
  ▼
retrieve_and_rank    ← pure python filtering+scoring, LLM/RAG লাগে না
  │
  ▼
decide_and_respond   ← এক LLM call: strategy + স্বাভাবিক reply generation
  │
  ▼
END
```

মোট ২টা LLM call প্রতি টার্নে — এটাই production এ latency/cost ম্যানেজেবল রাখার চাবি।

## Gemini Free Tier Setup (ধাপে ধাপে)

**ধাপ ১ — API Key নিন (কোনো কার্ড লাগবে না)**
[aistudio.google.com/apikey](https://aistudio.google.com/apikey) এ যান, Google
অ্যাকাউন্ট দিয়ে লগ ইন করুন, "Create API key" ক্লিক করুন। একটা নতুন Google Cloud
project auto-create হবে, key কপি করে রাখুন।

**ধাপ ২ — Package ইনস্টল করুন**
```bash
pip install -r requirements.txt
```
(এতে `langchain-google-genai` আছে, `ChatAnthropic` এর জায়গায় এখন
`ChatGoogleGenerativeAI` ব্যবহার হচ্ছে — `app/nodes.py` এ পরিবর্তন করা আছে)

**ধাপ ৩ — Key কে environment variable হিসেবে সেট করুন**
```bash
export GOOGLE_API_KEY=your_key_here
```
(LangChain এই ভ্যারিয়েবলটা নিজে থেকেই খুঁজে নেয়, কোডে key hardcode করার দরকার নেই)

**ধাপ ৪ — টেস্ট করুন**
```bash
python main.py
```

**কোন মডেল ব্যবহার করছি ও কেন**
`app/nodes.py` এ `gemini-2.5-flash` সেট করা আছে — free tier এ প্রতিদিন ~1500
রিকোয়েস্ট পাওয়া যায় এবং quality/cost ব্যালান্স ভালো। `gemini-2.0-flash` ব্যবহার
করবেন না — সেটা deprecated হয়ে গেছে। বেশি quota দরকার হলে (কিন্তু সামান্য কম
quality) `gemini-2.5-flash-lite` তে বদলাতে পারেন — শুধু `nodes.py` এর model
নাম পরিবর্তন করলেই হবে।

**⚠️ গুরুত্বপূর্ণ সতর্কতা — Free tier ডেটা প্রাইভেসি**
Free tier এ পাঠানো ডেটা (কাস্টমারের নাম, বাজেট, পছন্দ ইত্যাদি) Google তাদের মডেল
উন্নত করতে ব্যবহার করতে পারে (paid/billing enabled tier এ এটা হয় না)। যেহেতু
আপনি রিয়েল কাস্টমারদের ব্যক্তিগত ও আর্থিক তথ্য প্রসেস করছেন, প্রোডাকশনে যাওয়ার
আগে অন্তত billing enable করে নেওয়া বিবেচনা করুন — free tier টা শুধু development/
টেস্টিং পর্যায়ে ব্যবহার করুন।

**Rate limit হ্যান্ডলিং**
Free tier এ heavy testing করলে মাঝেমধ্যে `429` error আসতে পারে। `ChatGoogleGenerativeAI`
এর `max_retries` parameter ব্যবহার করে সহজেই retry যোগ করা যায়:
```python
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", temperature=0.3, max_retries=3)
```

**পরে Anthropic/Claude এ ফিরতে চাইলে**
`app/nodes.py` এ শুধু import ও `llm = ...` লাইনটা বদলে দিন:
```python
from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(model="claude-sonnet-4-6", temperature=0.3)
```
আর `requirements.txt` এ `langchain-anthropic` যোগ করুন — বাকি কোড (state, graph,
nodes এর logic) অপরিবর্তিত থাকবে, কারণ LLM provider swap করাটা LangChain এর
abstraction layer এর কারণে সহজ।

CLI তে কথা বলে টেস্ট করুন — প্রতিটা টার্নে `customer_profile` কীভাবে ধীরে ধীরে ভরে
উঠছে সেটা `app/state.py` এর `REQUIRED_FIELDS` দিয়ে বুঝতে পারবেন।

## বিল্ড অর্ডার (এই সিকোয়েন্সে করুন)

**Step 1 — Project DB আলাদাভাবে টেস্ট করুন**
`app/project_data.py` এর `rank_projects()` ফাংশনে হাতে কয়েকটা profile dict দিয়ে
কল করুন, দেখুন ranking যুক্তিসঙ্গত হচ্ছে কিনা। এখানে কোনো LLM নেই — এটা ঠিক না
হলে বাকি সিস্টেম যতই ভালো হোক, ভুল প্রজেক্ট সাজেস্ট হবে।

**Step 2 — MVP গ্রাফ CLI তে টেস্ট করুন**
`python main.py` দিয়ে ৫-৬ টা বাস্তব কাস্টমার সিনারিও ম্যানুয়ালি চালান।
লক্ষ্য করুন কোথায় extraction ভুল করছে (যেমন বাজেট ভুল বুঝছে) বা কোথায়
reply অপ্রাসঙ্গিক শোনাচ্ছে।

**Step 3 — যেখানে ভুল হচ্ছে, সেই অংশটাকেই আলাদা নোড করুন**
- Objection ঠিকমতো হ্যান্ডল হচ্ছে না? → `handle_objection` নামে আলাদা নোড বানান,
  conditional edge দিয়ে `objection` field non-null হলে সেখানে রুট করুন।
- Visit booking কনফার্ম করতে গিয়ে গোলমাল হচ্ছে? → `book_visit` নোড বানান, একটা
  actual calendar/slots tool যোগ করুন (Google Calendar API বা নিজের DB slot টেবিল)।
- Follow-up মেসেজ (কাস্টমার চুপ হয়ে গেলে) লাগবে? → এটা গ্রাফের ভিতরে না,
  বরং একটা cron job যেটা N দিন silent থাকা leads দের জন্য আলাদাভাবে
  `app_graph.invoke()` কল করে একটা follow-up মেসেজ পাঠায়।

**Step 4 — CRM persistence যোগ করুন**
`SqliteSaver` এখন শুধু conversation state রাখছে prototype এর জন্য। প্রোডাকশনে
`decide_and_respond` এর পরে একটা `save_crm_node` যোগ করুন যেটা Postgres এ
লিখবে: lead_score, interested_project, budget, pain_point, visit_status,
next_follow_up_date। এটা আলাদা টেবিল হবে state checkpoint থেকে — checkpoint
হলো "কথোপকথন resume করার মেমরি", CRM হলো "বিজনেস রিপোর্টিং ডেটা"।

**Step 5 — Facebook Messenger এ কানেক্ট করুন**
`fastapi_webhook.py` স্কেলিটন ব্যবহার করুন। দরকার হবে:
- Meta Developer অ্যাকাউন্টে একটা App + Messenger product
- Page Access Token ও একটা Verify Token (.env এ রাখুন, কোডে না)
- Webhook URL পাবলিকলি HTTPS এ হোস্ট করা থাকতে হবে

প্রতিটা Facebook ইউজারের PSID কে `thread_id` হিসেবে ব্যবহার করুন — এতে
প্রতিটা কাস্টমারের কথোপকথন আলাদাভাবে persist থাকবে।

**Step 6 — Lead scoring যোগ করুন**
`state.py` তে `lead_score: int` field আছে কিন্তু এখনো ব্যবহার হচ্ছে না।
`evaluate_missing_node` এর পাশে একটা সাধারণ rule-based scorer যোগ করুন
(যেমন: budget জানা +20, timeline "this_month" +30, decision_maker "self" +15
ইত্যাদি) — এর জন্য LLM লাগবে না, শুধু if/else যথেষ্ট।

## যখন সত্যিই Multi-Agent দরকার হবে

যদি Step 3 এর পরেও দেখেন যে single `decide_and_respond` prompt টা অনেক বড় ও
অনির্ভরযোগ্য হয়ে যাচ্ছে (৫০+ লাইনের system prompt, ইনকনসিসটেন্ট আউটপুট),
তখনই সেটাকে ২টা নোডে ভাগ করুন:
- `sales_strategy_node` → শুধু `next_action` ঠিক করবে (কোনো reply লিখবে না)
- `response_generator_node` → শুধু `next_action` অনুযায়ী reply লিখবে

এই বিভাজনটা আগের ডিজাইনে যেটা বলা হয়েছিল সেটাই, কিন্তু এখন করবেন
*evidence-based* — যখন দেখবেন এক-নোড approach আর কাজ করছে না, তখন।
শুরু থেকে বানালে আপনি এমন জটিলতা debug করবেন যেটার প্রয়োজনই হয়তো ছিল না।

## ফাইল স্ট্রাকচার

```
real_estate_sales_agent/
├── requirements.txt
├── README.md
├── main.py                 ← CLI টেস্ট লুপ
├── fastapi_webhook.py       ← Facebook Messenger integration
└── app/
    ├── state.py             ← SalesState schema
    ├── project_data.py      ← Project DB + filter/ranking (no LLM)
    ├── nodes.py              ← ৪টা LangGraph node
    └── graph.py              ← Graph wiring + checkpointer
```