🤖 গ্রাফ RAG, ADK এবং মেমোরি ব্যাংক দিয়ে একটি মাল্টিমোডাল AI এজেন্ট তৈরি করুন

1. ভূমিকা

১. চ্যালেঞ্জ

দুর্যোগ মোকাবেলার পরিস্থিতিতে, বিভিন্ন স্থানে বিভিন্ন দক্ষতা, সম্পদ এবং চাহিদার সাথে বেঁচে থাকা ব্যক্তিদের সমন্বয় করার জন্য বুদ্ধিমান ডেটা ব্যবস্থাপনা এবং অনুসন্ধান ক্ষমতা প্রয়োজন। এই কর্মশালা আপনাকে একটি উৎপাদন কৃত্রিম বুদ্ধিমত্তা ব্যবস্থা তৈরি করতে শেখায় যা নিম্নলিখিত বিষয়গুলিকে একত্রিত করে:

1. 🗄️ গ্রাফ ডাটাবেস (স্প্যানার) : বেঁচে থাকা ব্যক্তি, দক্ষতা এবং সম্পদের মধ্যে জটিল সম্পর্ক সংরক্ষণ করুন
2. 🔍 এআই-চালিত অনুসন্ধান : এম্বেডিং ব্যবহার করে শব্দার্থিক + কীওয়ার্ড হাইব্রিড অনুসন্ধান
3. 📸 মাল্টিমোডাল প্রসেসিং : ছবি, টেক্সট এবং ভিডিও থেকে স্ট্রাকচার্ড ডেটা বের করুন
4. 🤖 মাল্টি-এজেন্ট অর্কেস্ট্রেশন : জটিল কর্মপ্রবাহের জন্য বিশেষায়িত এজেন্টদের সমন্বয় করুন
5. 🧠 দীর্ঘমেয়াদী স্মৃতি : ভার্টেক্স এআই মেমোরি ব্যাংকের সাহায্যে ব্যক্তিগতকরণ

২. তুমি কী তৈরি করবে

একটি সারভাইভার নেটওয়ার্ক গ্রাফ ডাটাবেস যার সাথে:

• 🗺️ বেঁচে থাকা সম্পর্কের 3D ইন্টারেক্টিভ গ্রাফ ভিজ্যুয়ালাইজেশন
• 🔍 বুদ্ধিমান অনুসন্ধান (কীওয়ার্ড, শব্দার্থিক এবং হাইব্রিড)
• 📸 মাল্টিমোডাল আপলোড পাইপলাইন (ছবি/ভিডিও থেকে সত্তা বের করুন)
• 🤖 জটিল কাজের জন্য মাল্টি-এজেন্ট সিস্টেম
• 🧠 ব্যক্তিগতকৃত মিথস্ক্রিয়ার জন্য মেমোরি ব্যাংক ইন্টিগ্রেশন

৩. মূল প্রযুক্তি

উপাদান	প্রযুক্তি	উদ্দেশ্য
ডাটাবেস	ক্লাউড স্প্যানার গ্রাফ	স্টোর নোড (বেঁচে থাকা ব্যক্তি, দক্ষতা) এবং প্রান্ত (সম্পর্ক)
এআই অনুসন্ধান	মিথুন + এম্বেডিং	শব্দার্থিক বোধগম্যতা + সাদৃশ্য অনুসন্ধান
এজেন্ট ফ্রেমওয়ার্ক	ADK (এজেন্ট ডেভেলপমেন্ট কিট)	এআই কর্মপ্রবাহের ব্যবস্থা করুন
স্মৃতি	ভার্টেক্স এআই মেমোরি ব্যাংক	দীর্ঘমেয়াদী ব্যবহারকারীর পছন্দের সঞ্চয়স্থান
ফ্রন্টএন্ড	প্রতিক্রিয়া + থ্রি.জেএস	ইন্টারেক্টিভ 3D গ্রাফ ভিজ্যুয়ালাইজেশন

২. পরিবেশগত প্রস্তুতি (কর্মশালায় থাকলে এড়িয়ে যান)

আপনি যদি গুগল ওয়েব্যাকহোম ওয়ার্কশপে অংশগ্রহণকারী হন এবং ইতিমধ্যেই লেভেল ০ এবং লেভেল ১ শেষ করে থাকেন, তাহলে অনুগ্রহ করে এই সেশনটি এড়িয়ে যান!

প্রথম অংশ: বিলিং অ্যাকাউন্ট সক্ষম করুন

• ৫ ডলার ক্রেডিট দিয়ে আপনার বিলিং অ্যাকাউন্ট দাবি করার জন্য, আপনার এটি স্থাপনের জন্য প্রয়োজন হবে। আপনার জিমেইল অ্যাকাউন্টটি নিশ্চিত করুন।

কোনও ক্রেডিট কার্ড বা পেমেন্টের প্রয়োজন নেই — আপনি $5 বিনামূল্যে ক্রেডিট পাবেন। এতে 2 মিনিটেরও কম সময় লাগে, শুধু আপনার নাম লিখুন এবং ক্রেডিট গ্রহণ করুন।

দ্বিতীয় অংশ: উন্মুক্ত পরিবেশ

1. 👉 সরাসরি ক্লাউড শেল এডিটরে যেতে এই লিঙ্কে ক্লিক করুন।
2. 👉 আজই যদি যেকোনো সময় অনুমোদনের অনুরোধ জানানো হয়, তাহলে চালিয়ে যেতে অনুমোদনে ক্লিক করুন।
3. 👉 যদি স্ক্রিনের নীচে টার্মিনালটি না দেখা যায়, তাহলে এটি খুলুন:
   • ভিউ ক্লিক করুন
   • টার্মিনাল ক্লিক করুন
4. 👉💻 টার্মিনালে, নিম্নলিখিত কমান্ড ব্যবহার করে যাচাই করুন যে আপনি ইতিমধ্যেই প্রমাণীকরণপ্রাপ্ত এবং প্রকল্পটি আপনার প্রকল্প আইডিতে সেট করা আছে:

   gcloud auth list
   

5. 👉💻 GitHub থেকে বুটস্ট্র্যাপ প্রকল্পটি ক্লোন করুন:

   git clone https://github.com/google-americas/way-back-home.git
   

3. পরিবেশ সেটআপ

১. আরম্ভ করুন

ক্লাউড শেল এডিটর টার্মিনালে, যদি টার্মিনালটি স্ক্রিনের নীচে না দেখা যায়, তাহলে এটি খুলুন:

• ভিউ ক্লিক করুন
• টার্মিনাল ক্লিক করুন

যদি আপনি ওয়ার্কশপে থাকেন এবং লক্ষ্য করেন যে আপনি (.venv) এ আছেন, তাহলে এগিয়ে যাওয়ার আগে deactivate করে নিন।

👉💻 টার্মিনালে, init স্ক্রিপ্টটি এক্সিকিউটেবল করুন এবং এটি চালান:

cd ~/way-back-home/level_2
./init.sh

⚠️ প্রজেক্ট আইডি সম্পর্কে দ্রষ্টব্য: স্ক্রিপ্টটি আপনাকে একটি নতুন গুগল ক্লাউড প্রজেক্ট তৈরি করতে বলবে। আপনি ডিফল্ট এলোমেলোভাবে তৈরি প্রজেক্ট আইডি গ্রহণ করতে পারেন অথবা আপনার নিজস্ব নির্দিষ্ট করতে পারেন।

2. প্রকল্প কনফিগার করুন

👉💻 আপনার প্রোজেক্ট আইডি সেট করুন:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 প্রয়োজনীয় API গুলি সক্ষম করুন (এতে ~২-৩ মিনিট সময় লাগে):

gcloud services enable compute.googleapis.com \
                       aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       spanner.googleapis.com \
                       storage.googleapis.com

৩. সেটআপ স্ক্রিপ্ট চালান

👉💻 সেটআপ স্ক্রিপ্টটি কার্যকর করুন:

cd ~/way-back-home/level_2
./setup.sh

এটি আপনার জন্য .env তৈরি করবে। আপনার ক্লাউডশেলে, way_back_home প্রজেক্ট খুলুন। level_2 ফোল্ডারের অধীনে, আপনি দেখতে পাবেন যে .env ফাইলটি আপনার জন্য তৈরি করা হয়েছে। যদি আপনি এটি খুঁজে না পান, তাহলে আপনি এটি দেখতে View -> Toggle Hidden File ক্লিক করতে পারেন।

৪. নমুনা ডেটা লোড করুন

👉💻 ব্যাকএন্ডে নেভিগেট করুন এবং নির্ভরতা ইনস্টল করুন:

cd ~/way-back-home/level_2/backend
uv sync

👉💻 প্রাথমিক বেঁচে থাকা তথ্য লোড করুন:

uv run python ~/way-back-home/level_2/backend/setup_data.py

এটি তৈরি করে:

• স্প্যানার ইনস্ট্যান্স ( survivor-network )
• ডাটাবেস ( graph-db )
• সকল নোড এবং এজ টেবিল
• কোয়েরি করার জন্য সম্পত্তি গ্রাফ প্রত্যাশিত আউটপুট :

============================================================
SUCCESS! Database setup complete.
============================================================

Instance:  survivor-network
Database:  graph-db
Graph:     SurvivorGraph

Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome

আউটপুটে Access your database at পরে লিঙ্কে ক্লিক করলে, আপনি Google Cloud Console Spanner খুলতে পারবেন।

আর তুমি গুগল ক্লাউড কনসোলে স্প্যানার দেখতে পাবে!

৪. স্প্যানার স্টুডিওতে গ্রাফ ডেটা ভিজ্যুয়ালাইজ করা

এই নির্দেশিকাটি আপনাকে স্প্যানার স্টুডিও ব্যবহার করে গুগল ক্লাউড কনসোলে সরাসরি সারভাইভার নেটওয়ার্ক গ্রাফ ডেটা কল্পনা করতে এবং তার সাথে ইন্টারঅ্যাক্ট করতে সাহায্য করে। আপনার এআই এজেন্ট তৈরি করার আগে আপনার ডেটা যাচাই করার এবং গ্রাফ কাঠামো বোঝার এটি একটি দুর্দান্ত উপায়।

১. স্প্যানার স্টুডিও অ্যাক্সেস করুন

1. শেষ ধাপে, নিশ্চিত করুন যে আপনি লিঙ্কটিতে ক্লিক করেছেন এবং স্প্যানার স্টুডিওটি খুলছেন।

2. গ্রাফ কাঠামো বোঝা ("বড় ছবি")

সারভাইভার নেটওয়ার্ক ডেটাসেটকে একটি লজিক পাজল বা একটি গেম স্টেট হিসেবে ভাবুন:

সত্তা	সিস্টেমে ভূমিকা	উপমা
বেঁচে থাকা ব্যক্তিরা	এজেন্ট/খেলোয়াড়রা	খেলোয়াড়রা
বায়োম	তারা কোথায় অবস্থিত	মানচিত্র অঞ্চল
দক্ষতা	তারা কি করতে পারে	ক্ষমতা
চাহিদা	তাদের কী অভাব (সঙ্কট)	কোয়েস্ট/মিশন
রিসোর্স	পৃথিবীতে পাওয়া জিনিসপত্র	লুট

লক্ষ্য : এআই এজেন্টের কাজ হল দক্ষতা (সমাধান) কে চাহিদা (সমস্যা) এর সাথে সংযুক্ত করা, জৈবিক (অবস্থানের সীমাবদ্ধতা) বিবেচনা করে।

🔗 প্রান্ত (সম্পর্ক):

• SurvivorInBiome : অবস্থান ট্র্যাকিং
• SurvivorHasSkill : দক্ষতার তালিকা
• SurvivorHasNeed : সক্রিয় সমস্যার তালিকা
• SurvivorFoundResource : আইটেমের তালিকা
• SurvivorCanHelp : অনুমানকৃত সম্পর্ক (এআই এটি গণনা করে!)

৩. গ্রাফটি অনুসন্ধান করা

ডেটাতে "গল্প" দেখার জন্য কয়েকটি কোয়েরি রান করা যাক।

স্প্যানার গ্রাফ GQL (গ্রাফ কোয়েরি ল্যাঙ্গুয়েজ) ব্যবহার করে। একটি কোয়েরি চালানোর জন্য, GRAPH SurvivorNetwork ব্যবহার করুন এবং তারপরে আপনার ম্যাচ প্যাটার্ন ব্যবহার করুন।

👉 প্রশ্ন ১: গ্লোবাল রোস্টার (কে কোথায়?) এটি আপনার ভিত্তি - উদ্ধার অভিযানের জন্য অবস্থান বোঝা অত্যন্ত গুরুত্বপূর্ণ।

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result

নীচের মত ফলাফল দেখতে আশা করি:

কেন এটি গুরুত্বপূর্ণ:

• প্রেরণকারীদের জন্য : আপনি ক্রায়ো জোনে কাউকে উদ্ধার করার জন্য আগ্নেয়গিরি অঞ্চল থেকে কাউকে পাঠাতে পারবেন না।
• এআই এজেন্টের জন্য : যখন একজন ব্যবহারকারী জিজ্ঞাসা করেন "কে বনে আছে?" , তখন এজেন্ট এই কোয়েরি প্যাটার্নটি ব্যবহার করে।
• ভিজ্যুয়ালাইজেশন : আপনি ৪টি বায়োমে ছড়িয়ে থাকা ৪ জন বেঁচে থাকা ব্যক্তিকে দেখতে পাবেন - এটি আপনার "মানচিত্র দৃশ্য"।

👉 প্রশ্ন ২: দক্ষতা ম্যাট্রিক্স (ক্ষমতা) এখন আপনি জানেন যে সবাই কোথায় , তারা কী করতে পারে তা খুঁজে বের করুন।

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result

নীচের মত ফলাফল দেখতে আশা করি:

কেন এটি গুরুত্বপূর্ণ:

• প্রেরণকারীদের জন্য : এক নজরে আপনার চিকিৎসক, প্রকৌশলী এবং নেভিগেটরদের সনাক্ত করুন।
• এআই এজেন্টের জন্য : যখন একজন ব্যবহারকারী জিজ্ঞাসা করেন "কে প্রাথমিক চিকিৎসা জানে?" , এই প্রশ্নটি তাদের খুঁজে বের করে।
• দক্ষতার স্তর : লক্ষ্য করুন প্রান্ত h একটি proficiency বৈশিষ্ট্য রয়েছে (বিশেষজ্ঞ/দক্ষ/মৌলিক) - গ্রাফটি সম্পর্কের মেটাডেটা সঞ্চয় করে!

👉 প্রশ্ন ৩: কারা সংকটে আছেন? ("মিশন বোর্ড") বেঁচে থাকা ব্যক্তিদের দেখুন যাদের সাহায্যের প্রয়োজন এবং তাদের কী প্রয়োজন।

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result

নীচের মত ফলাফল দেখতে আশা করি:

কেন এটি গুরুত্বপূর্ণ:

• প্রেরণকারীদের জন্য : জরুরি ভিত্তিতে উদ্ধার অভিযানকে অগ্রাধিকার দিন।
• এআই এজেন্টের জন্য : এটি "করণীয় তালিকা" - এই সমস্যাগুলি সমাধানের অপেক্ষায় রয়েছে।

🔎 উন্নত: ম্যাচমেকিং - কে কাকে সাহায্য করতে পারে?

এখানেই গ্রাফটি শক্তিশালী হয়ে ওঠে! এই অনুসন্ধানে এমন জীবিতদের খুঁজে বের করা হয়েছে যাদের দক্ষতা রয়েছে যা অন্যান্য জীবিতদের চাহিদা মেটাতে পারে ।

GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result

নীচের মত ফলাফল দেখতে আশা করি:

ইতিবাচক দিক হলো , এই কোয়েরিটি কী করে:

"প্রাথমিক চিকিৎসায় পোড়ার চিকিৎসা করা হয়" দেখানোর পরিবর্তে (যা স্কিমা থেকে স্পষ্ট), এই কোয়েরিটি খুঁজে পায়:

• ডাঃ এলেনা ফ্রস্ট (যার চিকিৎসা প্রশিক্ষণ আছে) → চিকিৎসা করতে পারেন → ক্যাপ্টেন তানাকা (যার পোড়া)
• ডেভিড চেন (যার প্রাথমিক চিকিৎসা আছে) → চিকিৎসা করতে পারেন → লেফটেন্যান্ট পার্ক (যার গোড়ালি মচকে গেছে)

কেন এটি শক্তিশালী:

গ্রাফের সুবিধা : এটি একটি ৪-হপ ট্র্যাভার্সাল:

1. একজন সাহায্যকারী (বেঁচে থাকা) দিয়ে শুরু করুন
2. তাদের দক্ষতা খুঁজে বের করুন
3. তাদের চাহিদার সাথে দক্ষতা মেলান
4. সেইসব বেঁচে থাকা ব্যক্তিদের খুঁজে বের করুন যাদের এই চাহিদা আছে

গ্রাফ ছাড়া , আপনার প্রয়োজন হবে:

• SurvivorHasSkill টেবিল জিজ্ঞাসা করুন → দক্ষতা অর্জন করুন
• SkillTreatsQuery টেবিলের প্রয়োজন → কোনটির সাথে মিল প্রয়োজন তা খুঁজুন
• SurvivorHasNeed টেবিলটি জিজ্ঞাসা করুন → কার এই চাহিদা আছে তা খুঁজে বের করুন
• অ্যাপ্লিকেশন কোডে সমস্ত ফলাফল যোগ করুন

স্প্যানার গ্রাফের সাহায্যে , এটি একটি একক কোয়েরি যা ডাটাবেস আপনার জন্য অপ্টিমাইজ করে।

আপনার এআই এজেন্ট কী করবে:

যখন একজন ব্যবহারকারী জিজ্ঞাসা করেন "পোড়ার চিকিৎসা কে করতে পারে?" , তখন এজেন্ট নিম্নলিখিতগুলি করবেন:

1. একই ধরণের গ্রাফ কোয়েরি চালান
2. প্রত্যাবর্তন: "ডঃ ফ্রস্টের চিকিৎসা প্রশিক্ষণ আছে এবং তিনি ক্যাপ্টেন তানাকাকে সাহায্য করতে পারেন"
3. ব্যবহারকারীর মধ্যবর্তী টেবিল বা সম্পর্ক সম্পর্কে জানার দরকার নেই!

৫. স্প্যানারে এআই-চালিত এমবেডিং

১. কেন এম্বেডিং? (কোনও পদক্ষেপ নেই, কেবল পঠনযোগ্য)

বেঁচে থাকার ক্ষেত্রে, সময় অত্যন্ত গুরুত্বপূর্ণ । যখন একজন বেঁচে থাকা ব্যক্তি জরুরি অবস্থার কথা জানায়, যেমন I need someone who can treat burns অথবা Looking for a medic , তখন তারা ডাটাবেসে সঠিক দক্ষতার নাম অনুমান করে সময় নষ্ট করতে পারে না।

ঐতিহ্যবাহী অনুসন্ধানের সমস্যা :

• সঠিক মিল : "medic" শব্দটির জন্য একটি কীওয়ার্ড অনুসন্ধান "Medical Training" বা "First Aid" খুঁজে পাবে না।
• শব্দভান্ডারের অমিল : বেঁচে থাকা ব্যক্তিরা হয়তো "ডাক্তার", "নিরাময়কারী", "প্যারামেডিক" বলতে পারেন কিন্তু ডাটাবেসে আনুষ্ঠানিক দক্ষতার নাম সংরক্ষণ করা হয়
• প্রেক্ষাপটের ক্ষতি : "পোড়ার চিকিৎসা" বলতে "চিকিৎসা প্রশিক্ষণ" এবং "প্রাথমিক চিকিৎসা" উভয়ই খুঁজে পাওয়া উচিত, কিন্তু সহজ টেক্সট অনুসন্ধান করলে শব্দার্থিক সম্পর্ক বোঝা যাবে না।

সমাধান: এম্বেডিং সহ শব্দার্থিক অনুসন্ধান : এম্বেডিংগুলি পাঠ্যকে 768-মাত্রিক ভেক্টরে রূপান্তরিত করে যা কেবল বানান নয়, অর্থ ধারণ করে। ভেক্টর স্পেসে অনুরূপ ধারণাগুলি একত্রিত হয়, তাই "medic" স্বাভাবিকভাবেই "medical Training" খুঁজে পায় এমনকি শূন্য শব্দ ওভারল্যাপ থাকা সত্ত্বেও।

আসল দৃশ্য : বেঁচে থাকা ব্যক্তি: Captain Tanaka has burns—we need medical help NOW!

"medic" এর জন্য ঐতিহ্যবাহী কীওয়ার্ড অনুসন্ধান → 0 ফলাফল ❌

এম্বেডিং সহ শব্দার্থিক অনুসন্ধান → "চিকিৎসা প্রশিক্ষণ", "প্রাথমিক চিকিৎসা" খুঁজে বের করে ✅

এজেন্টদের ঠিক এটাই প্রয়োজন: বুদ্ধিমান, মানুষের মতো অনুসন্ধান যা কেবল কীওয়ার্ড নয়, উদ্দেশ্য বোঝে।

স্প্যানার কেন? : পাইথনে ডেটা রপ্তানি করার পরিবর্তে, বাহ্যিকভাবে এম্বেডিং তৈরি করা এবং পুনরায় আমদানি করা (ধীর, ত্রুটি-প্রবণ), স্প্যানারের ML.PREDICT আপনাকে এটি করতে দেয়:

• Vertex AI মডেল ব্যবহার করে সরাসরি SQL-এ এম্বেডিং তৈরি করুন
• গ্রাফ ডেটার পাশাপাশি ভেক্টর সংরক্ষণ করুন (কোনও পৃথক ভেক্টর ডাটাবেস নেই)
• গ্রাফ ট্র্যাভার্সালের সময় রিয়েল-টাইমে সিমান্টিক সার্চ কোয়েরি সম্পাদন করুন

এটি একটি শক্তিশালী গ্রাফ RAG সিস্টেম তৈরি করে: গ্রাফ সম্পর্ক (কার কী দক্ষতা আছে) + শব্দার্থিক অনুসন্ধান (অর্থ অনুসারে দক্ষতা খুঁজুন) = বুদ্ধিমান এজেন্ট অনুসন্ধান।

2. এম্বেডিং মডেল তৈরি করুন

ML.PREDICT কি?

ML.PREDICT হল Spanner-এর অন্তর্নির্মিত ফাংশন যা আপনাকে SQL থেকে সরাসরি মেশিন লার্নিং মডেলগুলিতে কল করতে দেয় — কোনও পাইথন নেই, কোনও রপ্তানি/আমদানি নেই, কোনও পৃথক পরিষেবা নেই। এটিকে রিয়েল-টাইমে আপনার ডাটাবেস এবং Vertex AI-এর মধ্যে সেতুবন্ধন হিসেবে ভাবুন।

কিভাবে এটা কাজ করে :

1. আপনি স্প্যানারে একটি ভার্চুয়াল মডেল তৈরি করেন (শুধুমাত্র একটি রেফারেন্স, স্থানীয়ভাবে কোনও মডেল ওজন সংরক্ষণ করা হয় না)
2. যখন আপনি একটি কোয়েরিতে ML.PREDICT(model, data) ব্যবহার করেন, তখন Spanner আপনার ডেটা API এর মাধ্যমে Vertex AI-তে পাঠায়।
3. Vertex AI এটি প্রক্রিয়া করে এবং আপনার SQL ফলাফলে কলাম হিসেবে ফলাফল ফেরত দেয়।

কেন এটি শক্তিশালী :

• ✅ জিরো-ইটিএল : ডেটা যেখানে থাকে সেখানে প্রক্রিয়া করুন—পাইথন স্ক্রিপ্টে রপ্তানি করা হবে না
• ✅ রিয়েল-টাইম : প্রশ্নের সময় এম্বেডিং বা LLM প্রতিক্রিয়া তৈরি করুন
• ✅ স্কেলেবল : স্প্যানার অর্কেস্ট্রেশন পরিচালনা করে, ভার্টেক্স এআই কম্পিউট পরিচালনা করে

এখন আসুন এমন একটি মডেল তৈরি করি যা গুগলের text-embedding-004 ব্যবহার করে টেক্সটকে এম্বেডিংয়ে রূপান্তর করে।

👉 স্প্যানার স্টুডিওতে, এই SQL চালান ( $YOUR_PROJECT_ID আপনার প্রকৃত প্রজেক্ট আইডি দিয়ে প্রতিস্থাপন করুন):

$YOUR_PROJECT_ID প্রতিস্থাপন করতে ভুলবেন না। আপনি আপনার .env ফাইলে আপনার প্রকৃত প্রকল্প আইডি খুঁজে পেতে পারেন।

‼️ ক্লাউড শেল এডিটরে , পুরো প্রকল্পটি দেখতে File -> Open Folder -> way-back-home/level_2 খুলুন।

👉 নিচের কোয়েরিটি কপি করে পেস্ট করে স্প্যানার স্টুডিওতে এই কোয়েরিটি চালান, এবং তারপর রান বোতামে ক্লিক করুন:

CREATE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);

যদি আপনি $YOUR_PROJECT_ID প্রতিস্থাপন করতে ভুলে যান এবং ইতিমধ্যেই এটি চালান, তাহলে পুনরায় চেষ্টা করার আগে DROP MODEL TextEmbeddings; করতে ভুলবেন না।

এর কাজ কী :

• স্প্যানারে একটি ভার্চুয়াল মডেল তৈরি করে (স্থানীয়ভাবে কোনও মডেল ওজন সংরক্ষণ করা হয় না)
• Vertex AI-তে Google-এর text-embedding-004 দিকে ইঙ্গিত করা হচ্ছে
• চুক্তি সংজ্ঞায়িত করে: ইনপুট হল টেক্সট, আউটপুট হল একটি 768-মাত্রা ফ্লোট অ্যারে

"রিমোট অপশন" কেন?

• স্প্যানার নিজেই মডেলটি চালায় না।
• ML.PREDICT ব্যবহার করার সময় এটি API এর মাধ্যমে Vertex AI কল করে।
• জিরো-ইটিএল : পাইথনে ডেটা রপ্তানি, প্রক্রিয়াকরণ এবং পুনরায় আমদানি করার প্রয়োজন নেই।

Run বাটনে ক্লিক করুন, একবার এটি সফল হয়ে গেলে, আপনি নীচের মত ফলাফল দেখতে পাবেন:

এটি একটি "ভার্চুয়াল মডেল" তৈরি করে যা Vertex AI এর text-embedding-004 উল্লেখ করে। Spanner থেকে কোনও ডেটা বাদ যায় না—এটি API এর মাধ্যমে ডাকা হয়।

৩. এম্বেডিং কলাম যোগ করুন

👉 এম্বেডিং সংরক্ষণ করতে একটি কলাম যোগ করুন:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

Run বাটনে ক্লিক করুন, একবার এটি সফল হয়ে গেলে, আপনি নীচের মত ফলাফল দেখতে পাবেন:

৪. এম্বেডিং তৈরি করুন

👉 প্রতিটি দক্ষতার জন্য ভেক্টর এম্বেডিং তৈরি করতে AI ব্যবহার করুন:

UPDATE Skills
SET skill_embedding = (
    SELECT embeddings.values
    FROM ML.PREDICT(
        MODEL TextEmbeddings,
        (SELECT name AS content)
    )
)
WHERE skill_embedding IS NULL;

Run বাটনে ক্লিক করুন, একবার এটি সফল হয়ে গেলে, আপনি নীচের মত ফলাফল দেখতে পাবেন:

যদি আপনি অনুমতি ত্রুটি দেখতে পান, তাহলে অনুগ্রহ করে দ্বিতীয় ধাপে এম্বেডিং মডেল তৈরি করুন । পুনরায় চেষ্টা করার আগে DROP MODEL TextEmbeddings;

কী ঘটে : প্রতিটি দক্ষতার নাম (যেমন, "প্রাথমিক চিকিৎসা") একটি 768-মাত্রার ভেক্টরে রূপান্তরিত হয় যা এর শব্দার্থিক অর্থ উপস্থাপন করে।

৫. এম্বেডিং যাচাই করুন

👉 এম্বেডিং তৈরি করা হয়েছে কিনা তা পরীক্ষা করুন:

SELECT 
    skill_id,
    name,
    ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;

প্রত্যাশিত আউটপুট :

৬. শব্দার্থিক অনুসন্ধান পরীক্ষা করুন

এখন আমরা আমাদের পরিস্থিতি থেকে সঠিক ব্যবহারের ক্ষেত্রে পরীক্ষা করব : "চিকিৎসক" শব্দটি ব্যবহার করে চিকিৎসা দক্ষতা খুঁজে বের করা।

👉 "চিকিৎসক" এর মতো দক্ষতা খুঁজুন:

WITH query_embedding AS (
    SELECT embeddings.values AS val
    FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
    s.name AS skill_name,
    s.category,
    COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;

• ব্যবহারকারীর অনুসন্ধান শব্দ "medic" কে একটি এম্বেডিংয়ে রূপান্তরিত করে
• এটিকে query_embedding অস্থায়ী টেবিলে সংরক্ষণ করে।

প্রত্যাশিত ফলাফল (কম দূরত্ব = আরও অনুরূপ):

৭. বিশ্লেষণের জন্য মিথুন মডেল তৈরি করুন

👉 একটি জেনারেটিভ এআই মডেল রেফারেন্স তৈরি করুন ( $YOUR_PROJECT_ID আপনার প্রকৃত প্রজেক্ট আইডি দিয়ে প্রতিস্থাপন করুন):

$YOUR_PROJECT_ID প্রতিস্থাপন করতে ভুলবেন না। আপনি আপনার .env ফাইলে আপনার প্রকৃত প্রকল্প আইডি খুঁজে পেতে পারেন।

CREATE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
    default_batch_size = 1
);

যদি আপনি $YOUR_PROJECT_ID প্রতিস্থাপন করতে ভুলে যান এবং ইতিমধ্যেই এটি চালান, > পুনরায় চেষ্টা করার আগে DROP MODEL GeminiPro; করতে ভুলবেন না।

এম্বেডিং মডেল থেকে পার্থক্য :

• এম্বেডিং : টেক্সট → ভেক্টর (সাদৃশ্য অনুসন্ধানের জন্য)
• মিথুন : টেক্সট → জেনারেটেড টেক্সট (যুক্তি/বিশ্লেষণের জন্য)

৮. সামঞ্জস্য বিশ্লেষণের জন্য জেমিনি ব্যবহার করুন

👉 মিশনের সামঞ্জস্যের জন্য বেঁচে থাকা জোড়া বিশ্লেষণ করুন:

WITH PairData AS (
    SELECT
        s1.name AS Name_A,
        s2.name AS Name_B,
        CONCAT(
            "Assess compatibility of these two survivors for a resource-gathering mission. ",
            "Survivor 1: ", s1.name, ". ",
            "Survivor 2: ", s2.name, ". ",
            "Give a score from 1-10 and a 1-sentence reason."
        ) AS prompt
    FROM Survivors s1
    JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
    LIMIT 1
)
SELECT
    Name_A,
    Name_B,
    content AS ai_assessment
FROM ML.PREDICT(
    MODEL GeminiPro,
    (SELECT Name_A, Name_B, prompt FROM PairData)
);

প্রত্যাশিত আউটপুট :

Name_A          | Name_B            | ai_assessment
----------------|-------------------|----------------
"David Chen"    | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."

এটা কিভাবে কাজ করে :

১. ডেটা থেকে প্রম্পট তৈরি করুন :

CONCAT("Assess compatibility...", "Survivor 1: ", s1.name, ...)

ফলাফল: "Assess compatibility of these two survivors for a resource-gathering mission. Survivor 1: David Chen. Survivor 2: Dr. Elena Frost. Give a score from 1-10 and a 1-sentence reason."

২. মিথুন রাশিতে পাঠান :

ML.PREDICT(MODEL GeminiPro, (SELECT prompt FROM PairData))

স্প্যানার জেমিনি API-তে প্রম্পট পাঠায়।

৩. মিথুন রাশি প্রতিক্রিয়া তৈরি করে :

"**Score: 9/10** Their compatibility is extremely high as David's practical, 
hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized 
knowledge to identify critical medical supplies and avoid biological hazards."

৪. কলাম হিসেবে রিটার্ন : তৈরি করা টেক্সট content কলাম হিসেবে রিটার্ন করা হয়।

কেন ইন-ডাটাবেস এলএলএম কল?

• পাইথনে ডেটা রপ্তানি করার দরকার নেই
• যেখানে তথ্য থাকে সেখানে প্রক্রিয়া করুন
• লক্ষ লক্ষ সারি পর্যন্ত স্কেল করা যেতে পারে (ব্যাচ প্রক্রিয়াকরণ)

৬. হাইব্রিড অনুসন্ধানের মাধ্যমে আপনার গ্রাফ RAG এজেন্ট তৈরি করা

১. সিস্টেম আর্কিটেকচার ওভারভিউ

এই বিভাগটি একটি বহু-পদ্ধতিগত অনুসন্ধান ব্যবস্থা তৈরি করে যা আপনার এজেন্টকে বিভিন্ন ধরণের প্রশ্ন পরিচালনা করার নমনীয়তা দেয়। সিস্টেমটিতে তিনটি স্তর রয়েছে: এজেন্ট স্তর , সরঞ্জাম স্তর , পরিষেবা স্তর ।

তিন স্তর কেন?

• উদ্বেগের বিচ্ছেদ : এজেন্ট উদ্দেশ্যের উপর, সরঞ্জামগুলির উপর ইন্টারফেস, পরিষেবা বাস্তবায়নের উপর দৃষ্টি নিবদ্ধ করে
• নমনীয়তা : এজেন্ট নির্দিষ্ট পদ্ধতি জোর করতে পারে অথবা AI-কে স্বয়ংক্রিয়ভাবে রুট করতে দিতে পারে
• অপ্টিমাইজেশন : পদ্ধতি জানা থাকলে ব্যয়বহুল এআই বিশ্লেষণ এড়িয়ে যেতে পারে

এই বিভাগে, আপনি প্রাথমিকভাবে শব্দার্থিক অনুসন্ধান (RAG) বাস্তবায়ন করবেন - কেবল কীওয়ার্ড নয়, অর্থ দিয়ে ফলাফল খুঁজে বের করা। পরে, আমরা ব্যাখ্যা করব কিভাবে হাইব্রিড অনুসন্ধান একাধিক পদ্ধতিকে একত্রিত করে।

২. আরএজি পরিষেবা বাস্তবায়ন

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py

মন্তব্যটি সনাক্ত করুন # TODO: REPLACE_SQL

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

        # This is your working query from the successful run!
        sql = """
            WITH query_embedding AS (
                SELECT embeddings.values AS val
                FROM ML.PREDICT(
                    MODEL TextEmbeddings,
                    (SELECT @query AS content)
                )
            )
            SELECT
                s.survivor_id,
                s.name AS survivor_name,
                s.biome,
                sk.skill_id,
                sk.name AS skill_name,
                sk.category,
                COSINE_DISTANCE(
                    sk.skill_embedding, 
                    (SELECT val FROM query_embedding)
                ) AS distance
            FROM Survivors s
            JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
            JOIN Skills sk ON shs.skill_id = sk.skill_id
            WHERE sk.skill_embedding IS NOT NULL
            ORDER BY distance ASC
            LIMIT @limit
        """

এই কোয়েরিটি কী করে :

এটি একটি গ্রাফ RAG কোয়েরি যা দুটি শক্তিশালী কৌশলকে একত্রিত করে:

1. গ্রাফ সম্পর্ক (স্প্যানারের গ্রাফ টেবিলে SQL JOIN এর মাধ্যমে)
2. শব্দার্থিক অনুসন্ধান (এমবেডিং এবং COSINE_DISTANCE এর মাধ্যমে)

অপেক্ষা করুন, এটা কি শুধু SQL?

হ্যাঁ! স্প্যানার গ্রাফ আপনাকে JOIN স্টেটমেন্ট সহ স্ট্যান্ডার্ড SQL ব্যবহার করে গ্রাফ সম্পর্ক অনুসন্ধান করতে দেয়। গ্রাফ কাঠামো (Survivors → Skills via SurvivorHasSkill edges) রিলেশনাল টেবিলে সংরক্ষণ করা হয় যা আপনি একসাথে যুক্ত করতে পারেন। এটি ঐতিহ্যবাহী গ্রাফ ডাটাবেস থেকে আলাদা যেখানে সাইফার বা গ্রেমলিনের মতো বিশেষায়িত কোয়েরি ভাষা প্রয়োজন।

কেন এটি "গ্রাফ RAG" :

• গ্রাফ : আমরা গ্রাফ কাঠামোতে সংরক্ষিত সম্পর্কগুলি (বেঁচে থাকা → দক্ষতা) অতিক্রম করছি।
• RAG : আমরা শব্দার্থগতভাবে অনুরূপ বিষয়বস্তু পুনরুদ্ধার করতে এম্বেডিং ব্যবহার করছি (পুনরুদ্ধার-বর্ধিত প্রজন্ম)
• ফলাফল : গ্রাফ সংযোগ অনুসরণ করে, তাদের দক্ষতার অর্থের ভিত্তিতে বেঁচে থাকা ব্যক্তিদের খুঁজুন।

উদাহরণ : "চিকিৎসক" এর জন্য অনুসন্ধান → "চিকিৎসা প্রশিক্ষণ" বা "প্রাথমিক চিকিৎসা" দক্ষতা সম্পন্ন বেঁচে থাকা ব্যক্তিদের খুঁজে বের করে, যদিও "চিকিৎসক" ডাটাবেসে ঠিকভাবে উপস্থিত হয় না।

৩. শব্দার্থিক অনুসন্ধান সরঞ্জামের সংজ্ঞা

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py

hybrid_search_tools.py তে, মন্তব্যটি সনাক্ত করুন # TODO: REPLACE_SEMANTIC_SEARCH_TOOL

👉 এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

async def semantic_search(query: str, limit: int = 10) -> str:
    """
    Force semantic (RAG) search using embeddings.
    
    Use this when you specifically want to find things by MEANING,
    not just matching keywords. Great for:
    - Finding conceptually similar items
    - Handling vague or abstract queries
    - When exact terms are unknown
    
    Example: "healing abilities" will find "first aid", "surgery", 
    "herbalism" even though no keywords match exactly.
    
    Args:
        query: What you're looking for (describe the concept)
        limit: Maximum results
        
    Returns:
        Semantically similar results ranked by relevance
    """
    try:
        service = _get_service()
        result = service.smart_search(
            query, 
            force_method=SearchMethod.RAG,
            limit=limit
        )
        
        return _format_results(
            result["results"],
            result["analysis"],
            show_analysis=True
        )
        
    except Exception as e:
        return f"Error in semantic search: {str(e)}"

যখন এজেন্ট ব্যবহার করে :

• সাদৃশ্যের জন্য জিজ্ঞাসা করা প্রশ্ন ("X এর অনুরূপ খুঁজুন")
• ধারণাগত প্রশ্ন ("নিরাময় ক্ষমতা")
• যখন অর্থ বোঝা অত্যন্ত গুরুত্বপূর্ণ

৪. এজেন্ট সিদ্ধান্ত নির্দেশিকা (নির্দেশনা)

এজেন্ট সংজ্ঞায়, নির্দেশের সাথে শব্দার্থিক অনুসন্ধান সম্পর্কিত অংশটি কপি পেস্ট করুন।

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

এজেন্ট সঠিক টুলটি নির্বাচন করতে এই নির্দেশিকাটি ব্যবহার করে:

agent.py ফাইলে, মন্তব্যটি সনাক্ত করুন # TODO: REPLACE_SEARCH_LOGIC , এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

- `semantic_search`: Force RAG/embedding search
  Use for: "Find similar to X", conceptual queries, unknown terminology
  Example: "Find skills related to healing"

👉মন্তব্যটি সনাক্ত করুন # TODO: ADD_SEARCH_TOOL এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    semantic_search,         # Force RAG

৫. হাইব্রিড অনুসন্ধান কীভাবে কাজ করে তা বোঝা (কেবলমাত্র পঠনযোগ্য, কোনও পদক্ষেপের প্রয়োজন নেই)

ধাপ ২-৪-এ, আপনি শব্দার্থিক অনুসন্ধান (RAG) প্রয়োগ করেছেন, মূল অনুসন্ধান পদ্ধতি যা অর্থ অনুসারে ফলাফল খুঁজে বের করে। কিন্তু আপনি হয়তো লক্ষ্য করেছেন যে সিস্টেমটিকে "হাইব্রিড অনুসন্ধান" বলা হয়। এখানে সবকিছু একসাথে কীভাবে খাপ খায়:

তিনটি অনুসন্ধান পদ্ধতি উপলব্ধ :

1. সিমান্টিক সার্চ (RAG) - আপনি যা বাস্তবায়িত করেছেন

• এম্বেডিং + COSINE_DISTANCE ব্যবহার করে
• এর জন্য সেরা: ধারণাগত প্রশ্ন, "X এর অনুরূপ" খুঁজে বের করা
• উদাহরণ: "নিরাময় ক্ষমতা" "প্রাথমিক চিকিৎসা", "অস্ত্রোপচার", "ভেষজ চিকিৎসা" খুঁজে পায়

2. কীওয়ার্ড অনুসন্ধান - ঐতিহ্যবাহী SQL ফিল্টারিং

• LIKE ধারা এবং সঠিক বিভাগের মিল ব্যবহার করে
• এর জন্য সেরা: বায়োম, বিভাগ এর মতো নির্দিষ্ট ফিল্টার
• উদাহরণ: "বনে চিকিৎসা দক্ষতা" বিভাগ এবং অবস্থান অনুসারে ফিল্টার

3. হাইব্রিড অনুসন্ধান - উভয় পদ্ধতি একত্রিত করে

• উভয় অনুসন্ধান চালায় এবং ফলাফলগুলিকে ওজনযুক্ত স্কোরের সাথে মার্জ করে
• এর জন্য সেরা: ধারণা এবং ফিল্টার উভয় সহ জটিল প্রশ্ন
• উদাহরণ: "পাহাড়ে নিরাময়ে কে সাহায্য করতে পারে?"

হাইব্রিড মার্জ কিভাবে কাজ করে :

way-back-home/level_2/backend/services/hybrid_search_service.py ফাইলে, যখন hybrid_search() কল করা হয়, তখন পরিষেবাটি উভয় অনুসন্ধান চালায় এবং ফলাফল একত্রিত করে:

# Location: backend/services/hybrid_search_service.py

    rank_kw = keyword_ranks.get(surv_id, float('inf'))
    rank_rag = rag_ranks.get(surv_id, float('inf'))

    rrf_score = 0.0
    if rank_kw != float('inf'):
        rrf_score += 1.0 / (K + rank_kw)
    if rank_rag != float('inf'):
        rrf_score += 1.0 / (K + rank_rag)

    combined_score = rrf_score

যখন hybrid_search() কল করা হয়, তখন পরিষেবাটি উভয় অনুসন্ধান চালায় এবং Reciprocal Rank Fusion (RRF) ব্যবহার করে ফলাফল একত্রিত করে।

RRF কী? RRF হল একটি স্ট্যান্ডার্ড অ্যালগরিদম যা বিভিন্ন সার্চ ইঞ্জিন থেকে র‍্যাঙ্ক করা তালিকাগুলিকে তাদের স্কোর স্বাভাবিক করার প্রয়োজন ছাড়াই একত্রিত করে। এটি র‍্যাঙ্ক পজিশনের (১ম, ২য়, ৩য়) উপর ভিত্তি করে একটি স্কোর দিয়ে কাজ করে, কাঁচা সাদৃশ্য স্কোরের পরিবর্তে।

প্রতিটি পদ্ধতি কখন ব্যবহার করা হয়?

এজেন্ট ( backend/agent/agent.py ) কোয়েরির উপর ভিত্তি করে সিদ্ধান্ত নেয়:

কোয়েরির ধরণ	এজেন্ট পছন্দ করে	কেন
"বনে বেঁচে থাকাদের খুঁজে বের করো"	keyword_search	সহজ ফিল্টার, কোন অর্থবোধক শব্দের প্রয়োজন নেই
"আঘাত কে সারাতে পারে?"	semantic_search	ধারণাগত, অর্থের প্রয়োজন
"পাহাড়ে চিকিৎসা সহায়তা"	hybrid_search	ধারণা + ফিল্টার উভয়ই আছে

এই কোডল্যাবের জন্য , আপনি সিমেন্টিক সার্চ কম্পোনেন্ট (RAG) বাস্তবায়ন করেছেন, যা ভিত্তি। কীওয়ার্ড এবং হাইব্রিড পদ্ধতিগুলি ইতিমধ্যেই পরিষেবাটিতে প্রয়োগ করা হয়েছে - আপনার এজেন্ট তিনটিই ব্যবহার করতে পারে!

অভিনন্দন! আপনি হাইব্রিড অনুসন্ধানের মাধ্যমে আপনার গ্রাফ আরএজি এজেন্ট সফলভাবে শেষ করেছেন!

৭. ADK ওয়েবের মাধ্যমে আপনার এজেন্টের পরীক্ষা করা

আপনার এজেন্ট পরীক্ষা করার সবচেয়ে সহজ উপায় হল adk web কমান্ড ব্যবহার করা, যা আপনার এজেন্টকে একটি অন্তর্নির্মিত চ্যাট ইন্টারফেসের মাধ্যমে চালু করে।

১. এজেন্ট পরিচালনা

👉💻 ব্যাকএন্ড ডিরেক্টরিতে নেভিগেট করুন (যেখানে আপনার এজেন্ট সংজ্ঞায়িত) এবং ওয়েব ইন্টারফেস চালু করুন::

cd ~/way-back-home/level_2/backend
uv run adk web

এই কমান্ডটি সংজ্ঞায়িত এজেন্ট শুরু করে

agent/agent.py

এবং পরীক্ষার জন্য একটি ওয়েব ইন্টারফেস খোলে।

👉 URL খুলুন:

কমান্ডটি একটি স্থানীয় URL আউটপুট করবে (সাধারণত http://127.0.0.1:8000 বা অনুরূপ)। এটি আপনার ব্রাউজারে খুলুন।

URL-এ ক্লিক করার পর, আপনি ADK ওয়েব UI দেখতে পাবেন। উপরের বাম কোণ থেকে "এজেন্ট" নির্বাচন করুন।

2. অনুসন্ধান ক্ষমতা পরীক্ষা করা

এজেন্টটি আপনার প্রশ্নের বুদ্ধিমত্তার সাথে সমাধান করার জন্য ডিজাইন করা হয়েছে। বিভিন্ন অনুসন্ধান পদ্ধতি কার্যকরভাবে দেখতে চ্যাট উইন্ডোতে নিম্নলিখিত ইনপুটগুলি চেষ্টা করুন।

🧬 A. গ্রাফ RAG (শব্দার্থিক অনুসন্ধান)

অর্থ এবং ধারণার উপর ভিত্তি করে আইটেমগুলি খুঁজে বের করে, এমনকি যদি কীওয়ার্ডগুলি মিল নাও হয়।

পরীক্ষার প্রশ্ন: (নীচের যেকোনো একটি বেছে নিন)

Who can help with injuries?

What abilities are related to survival?

কী খুঁজবেন:

• যুক্তিতে শব্দার্থিক বা RAG অনুসন্ধান উল্লেখ করা উচিত।
• আপনার ধারণাগতভাবে সম্পর্কিত ফলাফল দেখতে পাওয়া উচিত (যেমন, "প্রাথমিক চিকিৎসা" জিজ্ঞাসা করার সময় "অস্ত্রোপচার")।
• ফলাফলে 🧬 আইকন থাকবে।

🔀 খ. হাইব্রিড অনুসন্ধান

জটিল প্রশ্নের জন্য শব্দার্থিক বোঝার সাথে কীওয়ার্ড ফিল্টারগুলিকে একত্রিত করে।

পরীক্ষার প্রশ্ন: (নীচের যেকোনো একটি বেছে নিন)

Find someone who can ply a plane in the volcanic area

Who has healing abilities in the FOSSILIZED?

Who has healing abilities in the mountains?

কী খুঁজবেন:

• যুক্তিতে হাইব্রিড অনুসন্ধানের কথা উল্লেখ করা উচিত।
• ফলাফল উভয় মানদণ্ডের (ধারণা + অবস্থান/বিভাগ) সাথে মিলিত হওয়া উচিত।
• উভয় পদ্ধতিতে পাওয়া ফলাফলে 🔀 আইকন থাকবে এবং সর্বোচ্চ স্থান পাবে।

👉💻 পরীক্ষা শেষ হলে, আপনার কমান্ড লাইনে Ctrl+C টিপে প্রক্রিয়াটি শেষ করুন।

৮. সম্পূর্ণ আবেদনপত্র চালানো

ফুল স্ট্যাক আর্কিটেকচার ওভারভিউ

সেশন সার্ভিস এবং রানার যোগ করুন

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে chat.py ফাইলটি চালু করুন (এগিয়ে যাওয়ার আগে পূর্ববর্তী প্রক্রিয়াটি শেষ করতে "ctrl+C" করেছেন কিনা তা নিশ্চিত করুন):

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

chat.py ফাইলে, মন্তব্যটি খুঁজুন # TODO: REPLACE_INMEMORY_SERVICES , এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    session_service = InMemorySessionService()
    memory_service = InMemoryMemoryService()

chat.py ফাইলে, মন্তব্যটি সনাক্ত করুন # TODO: REPLACE_RUNNER , এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

runner = Runner(
    agent=root_agent, 
    session_service=session_service,
    memory_service=memory_service,
    app_name="survivor-network"
)

1. আবেদন শুরু করুন

যদি পূর্ববর্তী টার্মিনালটি এখনও চলমান থাকে, তাহলে Ctrl+C টিপে এটি শেষ করুন।

👉💻 অ্যাপ শুরু করুন:

cd ~/way-back-home/level_2/
./start_app.sh

যখন এটি সফলভাবে ব্যাকএন্ড শুরু করবে, তখন আপনি নীচের মত Local: http://localhost:5173/" দেখতে পাবেন:

👉 টার্মিনাল থেকে Local: http://localhost:5173/ এ ক্লিক করুন।

2. শব্দার্থিক অনুসন্ধান পরীক্ষা করুন

প্রশ্ন :

Find skills similar to healing

কি হয় :

• এজেন্ট সাদৃশ্য অনুরোধ স্বীকৃতি দেয়
• "নিরাময়" এর জন্য এম্বেডিং তৈরি করে
• শব্দার্থগতভাবে অনুরূপ দক্ষতা খুঁজে পেতে কোসাইন দূরত্ব ব্যবহার করে
• রিটার্নস: প্রাথমিক চিকিৎসা (যদিও নামগুলি "নিরাময়" এর সাথে মেলে না)

৩. হাইব্রিড অনুসন্ধান পরীক্ষা করুন

প্রশ্ন :

Find medical skills in the mountains

কি হয় :

1. কীওয়ার্ড কম্পোনেন্ট : category='medical' এর জন্য ফিল্টার করুন
2. শব্দার্থিক উপাদান : "চিকিৎসা" এম্বেড করুন এবং সাদৃশ্য অনুসারে র‌্যাঙ্ক করুন
3. মার্জ করুন : উভয় পদ্ধতিতে পাওয়া ফলাফলগুলিকে অগ্রাধিকার দিয়ে একত্রিত করুন 🔀

প্রশ্ন (ঐচ্ছিক) :

Who is good at survival and in the forest?

কি হয় :

• কীওয়ার্ড খুঁজে পায়: biome='forest'
• শব্দার্থিক আবিষ্কার: "বেঁচে থাকার" মতো দক্ষতা
• হাইব্রিড সেরা ফলাফলের জন্য উভয়কেই একত্রিত করে

👉💻 যখন আপনি পরীক্ষা শেষ করবেন, টার্মিনালে, Ctrl+C টিপে এটি শেষ করুন।

৯. মাল্টিমোডাল পাইপলাইন — টুলিং লেয়ার

কেন আমাদের একটি মাল্টিমোডাল পাইপলাইনের প্রয়োজন?

বেঁচে থাকার নেটওয়ার্ক কেবল টেক্সট নয়। ক্ষেত্রের বেঁচে থাকা ব্যক্তিরা সরাসরি চ্যাটের মাধ্যমে অসংগঠিত তথ্য পাঠান:

• 📸 ছবি : সম্পদ, বিপদ, বা সরঞ্জামের ছবি
• 🎥 ভিডিও : স্ট্যাটাস রিপোর্ট বা SOS সম্প্রচার
• 📄 টেক্সট : ফিল্ড নোট বা লগ

চ্যালেঞ্জ : এই তথ্য অনুসন্ধানযোগ্য করার জন্য ("জল কোথায়?"), আমাদের এই ফাইলগুলি থেকে কাঠামোগত সত্তা (ব্যক্তি, সম্পদ, অবস্থান) বের করে গ্রাফে সংরক্ষণ করতে হবে।

বাস্তব-বিশ্বের দৃশ্যপট :

একজন ব্যবহারকারী চ্যাটে একটি মেডিকেল কিটের ছবি আপলোড করেন।

সিস্টেমটি অবশ্যই :

1. ফাইলটি GCS-এ আপলোড করুন।
2. মেডিকেল কিট "দেখতে" জেমিনি ব্যবহার করুন
3. স্প্যানারে একটি "রিসোর্স" নোড সংরক্ষণ করুন।
4. ব্যবহারকারীকে নিশ্চিত করুন: "আমি মেডিকেল কিটটি ডাটাবেসে সংরক্ষণ করেছি।"

আমরা কোন ফাইলগুলি প্রক্রিয়া করছি?

আগের ধাপে যেখানে আমরা বিদ্যমান ডেটা অনুসন্ধান করেছি, তার বিপরীতে, এখানে আমরা User-Uploaded Files প্রক্রিয়া করি। chat.py ইন্টারফেসটি গতিশীলভাবে ফাইল সংযুক্তি পরিচালনা করে:

উৎস	কন্টেন্ট	লক্ষ্য
ব্যবহারকারীর সংযুক্তি	ছবি/ভিডিও/টেক্সট	গ্রাফে যোগ করার জন্য তথ্য
চ্যাট প্রসঙ্গ	"এখানে সরবরাহের একটি ছবি"	উদ্দেশ্য এবং অতিরিক্ত বিবরণ

পরিকল্পিত পদ্ধতি: সিকোয়েন্সিয়াল এজেন্ট পাইপলাইন

আমরা একটি সিকোয়েন্সিয়াল এজেন্ট ( multimedia_agent.py ) ব্যবহার করি যা বিশেষায়িত এজেন্টদের একসাথে শৃঙ্খলিত করে:

এটিকে backend/agent/multimedia_agent.py তে SequentialAgent হিসেবে সংজ্ঞায়িত করা হয়েছে।

টুলিং লেয়ারটি এজেন্টদের জন্য প্রয়োজনীয় ক্ষমতা প্রদান করে। টুলগুলি "কীভাবে" পরিচালনা করে — ফাইল আপলোড করা, সত্তা বের করা এবং ডাটাবেসে সংরক্ষণ করা।

১. টুলস ফাইলটি খুলুন

👉💻 একটি নতুন টার্মিনাল খুলুন। টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py

2. upload_media টুলটি বাস্তবায়ন করুন

এই টুলটি গুগল ক্লাউড স্টোরেজে একটি স্থানীয় ফাইল আপলোড করে।

👉 extraction_tools.py তে, মন্তব্য pass # TODO: REPLACE_UPLOAD_MEDIA_FUNCTION ।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    """
    Upload media file to GCS and detect its type.
    
    Args:
        file_path: Path to the local file
        survivor_id: Optional survivor ID to associate with upload
        
    Returns:
        Dict with gcs_uri, media_type, and status
    """
    try:
        if not file_path:
            return {"status": "error", "error": "No file path provided"}
        
        # Strip quotes if present
        file_path = file_path.strip().strip("'").strip('"')
        
        if not os.path.exists(file_path):
            return {"status": "error", "error": f"File not found: {file_path}"}
        
        gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
        
        return {
            "status": "success",
            "gcs_uri": gcs_uri,
            "signed_url": signed_url,
            "media_type": media_type.value,
            "file_name": os.path.basename(file_path),
            "survivor_id": survivor_id
        }
    except Exception as e:
        logger.error(f"Upload failed: {e}")
        return {"status": "error", "error": str(e)}

৩. extract_from_media টুলটি বাস্তবায়ন করুন

এই টুলটি একটি রাউটার — এটি media_type পরীক্ষা করে এবং সঠিক এক্সট্র্যাক্টরে (টেক্সট, ছবি, বা ভিডিও) প্রেরণ করে।

extraction_tools.py তে, মন্তব্য pass # TODO: REPLACE_EXTRACT_FROM_MEDIA ।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    """
    Extract entities and relationships from uploaded media.
    
    Args:
        gcs_uri: GCS URI of the uploaded file
        media_type: Type of media (text/image/video)
        signed_url: Optional signed URL for public/temporary access
        
    Returns:
        Dict with extraction results
    """
    try:
        if not gcs_uri:
             return {"status": "error", "error": "No GCS URI provided"}

        # Select appropriate extractor
        if media_type == MediaType.TEXT.value or media_type == "text":
            result = await text_extractor.extract(gcs_uri)
        elif media_type == MediaType.IMAGE.value or media_type == "image":
            result = await image_extractor.extract(gcs_uri)
        elif media_type == MediaType.VIDEO.value or media_type == "video":
            result = await video_extractor.extract(gcs_uri)
        else:
            return {"status": "error", "error": f"Unsupported media type: {media_type}"}
            
        # Inject signed URL into broadcast info if present
        if signed_url:
            if not result.broadcast_info:
                result.broadcast_info = {}
            result.broadcast_info['thumbnail_url'] = signed_url
        
        return {
            "status": "success",
            "extraction_result": result.to_dict(), # Return valid JSON dict instead of object
            "summary": result.summary,
            "entities_count": len(result.entities),
            "relationships_count": len(result.relationships),
            "entities": [e.to_dict() for e in result.entities],
            "relationships": [r.to_dict() for r in result.relationships]
        }
    except Exception as e:
        logger.error(f"Extraction failed: {e}")
        return {"status": "error", "error": str(e)}

মূল বাস্তবায়নের বিবরণ:

• মাল্টিমোডাল ইনপুট : আমরা টেক্সট প্রম্পট ( _get_extraction_prompt() ) এবং ইমেজ অবজেক্ট উভয়কেই generate_content এ পাস করি।
• স্ট্রাকচার্ড আউটপুট : response_mime_type="application/json" নিশ্চিত করে যে LLM বৈধ JSON প্রদান করে, যা পাইপলাইনের জন্য অত্যন্ত গুরুত্বপূর্ণ।
• ভিজ্যুয়াল এন্টিটি লিঙ্কিং : প্রম্পটে পরিচিত এন্টিটি অন্তর্ভুক্ত থাকে যাতে মিথুন নির্দিষ্ট অক্ষর চিনতে পারে।

৪. save_to_spanner টুলটি প্রয়োগ করুন

এই টুলটি স্প্যানার গ্রাফ ডিবিতে নিষ্কাশিত সত্তা এবং সম্পর্কগুলিকে ধরে রাখে।

extraction_tools.py তে, মন্তব্য pass # TODO: REPLACE_SPANNER_AGENT সনাক্ত করুন।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    """
    Save extracted entities and relationships to Spanner Graph DB.
    
    Args:
        extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
        survivor_id: Optional survivor ID to associate with the broadcast
        
    Returns:
        Dict with save statistics
    """
    try:
        # Handle if extraction_result is passed as the wrapper dict from extract_from_media
        result_obj = extraction_result
        if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
             result_obj = extraction_result['extraction_result']
        
        # If result_obj is a dict (from to_dict()), reconstruct it
        if isinstance(result_obj, dict):
            from extractors.base_extractor import ExtractionResult
            result_obj = ExtractionResult.from_dict(result_obj)
        
        if not result_obj:
            return {"status": "error", "error": "No extraction result provided"}
            
        stats = spanner_service.save_extraction_result(result_obj, survivor_id)
        
        return {
            "status": "success",
            "entities_created": stats['entities_created'],
            "entities_existing": stats['entities_found_existing'],
            "relationships_created": stats['relationships_created'],
            "broadcast_id": stats['broadcast_id'],
            "errors": stats['errors'] if stats['errors'] else None
        }
    except Exception as e:
        logger.error(f"Spanner save failed: {e}")
        return {"status": "error", "error": str(e)}

এজেন্টদের উচ্চ-স্তরের সরঞ্জাম প্রদানের মাধ্যমে, আমরা এজেন্টের যুক্তি ক্ষমতা ব্যবহার করে ডেটা অখণ্ডতা নিশ্চিত করি।

৫. GCS পরিষেবা আপডেট করুন

GCSService গুগল ক্লাউড স্টোরেজে প্রকৃত ফাইল আপলোড পরিচালনা করে।

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py

👉 gcs_service.py ফাইলে, upload_file ফাংশনের ভিতরে # TODO: REPLACE_SAVE_TO_GCS মন্তব্যটি খুঁজুন।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

        blob = self.bucket.blob(blob_name)
        blob.upload_from_filename(file_path)

এটিকে একটি পরিষেবাতে সংক্ষেপিত করে, এজেন্টকে GCS বাকেট, ব্লব নাম, অথবা স্বাক্ষরিত URL জেনারেশন সম্পর্কে জানতে হবে না। এটি কেবল "আপলোড" করতে বলে।

৬. (কেবল পঠনযোগ্য) কেন এজেন্টিক কর্মপ্রবাহ > ঐতিহ্যবাহী পদ্ধতি?

এই পাইপলাইন তৈরির দুটি ঐতিহ্যবাহী উপায় আছে। উভয়েরই বড় ধরনের ত্রুটি রয়েছে যা এজেন্টিক ওয়ার্কফ্লো সমাধান করে।

❌ পদ্ধতি ১: ব্যাচ ডেটা পাইপলাইন (সহজ কিন্তু ভঙ্গুর)

একটি সাধারণ ব্যাচ স্ক্রিপ্ট যা ধারাবাহিকভাবে ফাইল প্রক্রিয়া করে:

# Traditional batch pipeline
for file in ["broadcast_1.txt", "broadcast_2.png", "broadcast_3.mp4"]:
   gcs_uri = upload_to_gcs(file)        # Fails if file corrupted → CRASH
   entities = extract_entities(gcs_uri) # No error handling
   save_to_db(entities)                 # Saves even if extraction empty → WASTE
   # How do you tell the user progress? Print to console?

সমস্যা:

• ❌ কোন অভিযোজনযোগ্যতা নেই : যদি একটি ফাইল ব্যর্থ হয়, তাহলে পুরো স্ক্রিপ্টটি ক্র্যাশ হয়ে যায়।
• ❌ কোন প্রসঙ্গ নেই : ব্যবহারকারীর অভিপ্রায়ের উপর ভিত্তি করে আচরণ সামঞ্জস্য করা যাচ্ছে না ("এটি জরুরি!")
• ❌ নীরব ব্যর্থতা : লগে লুকানো ত্রুটি, ব্যবহারকারী জানেন না কী ঘটেছে
• ❌ ব্যবহারকারীর কোনও প্রতিক্রিয়া নেই : স্ক্রিপ্টটি ব্যাকগ্রাউন্ডে চলে, ব্যবহারকারী অন্ধভাবে অপেক্ষা করে

❌ পদ্ধতি ২: ইভেন্ট-চালিত স্থাপত্য (ক্লাউড-নেটিভ কিন্তু জটিল)

ঐতিহ্যবাহী ক্লাউড সেটআপ:

1. GCS-এ ব্যবহারকারীর আপলোড
2. GCS ইভেন্ট ক্লাউড ফাংশন ট্রিগার করে
3. ফাংশন কল ভিশন এপিআই
4. ফাংশনটি ডিবিতে লেখে
5. ...ব্যবহারকারীকে আমরা কীভাবে বলব যে এটি শেষ হয়েছে? (ওয়েবসকেট/পোলিং প্রয়োজন)

সমস্যা:

• ❌ উচ্চ জটিলতা : ৫+ পরিষেবা পরিচালনা করুন (GCS, Eventarc, Cloud Functions, Pub/Sub...)
• ❌ ডিকপলড অবস্থা : ইভেন্ট হ্যান্ডলারের মধ্যে ডেটা স্থানান্তর করা কঠিন
• ❌ দুঃস্বপ্নের ডিবাগিং : একাধিক পরিষেবা জুড়ে ছড়িয়ে ছিটিয়ে থাকা লগ
• ❌ ব্যবহারকারীর সাথে সংযোগ বিচ্ছিন্ন : ইভেন্টগুলি পটভূমিতে চলে, কোনও কথোপকথনের প্রসঙ্গ নেই

✅ আমাদের পদ্ধতি: এজেন্টিক সিকোয়েন্সিয়াল পাইপলাইন

multimedia_agent.py একটি SequentialAgent ব্যবহার করে যা বুদ্ধিমত্তার সাথে পাইপলাইন পরিচালনা করে:

# Agentic pipeline (simplified conceptual view)
Agent: "I'll upload your file..."
Tool: upload_media → Success ✅
Agent: "Great! Now extracting entities..."
Tool: extract_from_media → Found 3 survivors, 2 resources ✅
Agent: "Perfect! Saving to database..."
Tool: save_to_spanner → Saved as broadcast #456 ✅
Agent: "Done! I found 3 survivors and 2 resources in your image. Saved to the graph."

এজেন্টিক সুবিধা:

বৈশিষ্ট্য	ব্যাচ পাইপলাইন	ইভেন্ট-চালিত	এজেন্টিক কর্মপ্রবাহ
জটিলতা	কম (১টি স্ক্রিপ্ট)	উচ্চ (৫+ পরিষেবা)	নিম্ন (১টি পাইথন ফাইল: multimedia_agent.py )
রাজ্য ব্যবস্থাপনা	গ্লোবাল ভেরিয়েবল	শক্ত (বিচ্ছিন্ন)	ইউনিফাইড (এজেন্ট স্টেট)
ত্রুটি পরিচালনা	ক্র্যাশ	নীরব লগ	ইন্টারেক্টিভ ("আমি সেই ফাইলটি পড়তে পারিনি")
ব্যবহারকারীর প্রতিক্রিয়া	কনসোল প্রিন্ট	পোলিং প্রয়োজন	তাৎক্ষণিক (চ্যাটের অংশ)
অভিযোজনযোগ্যতা	স্থির যুক্তি	অনমনীয় ফাংশন	বুদ্ধিমান (এলএলএম পরবর্তী পদক্ষেপ নির্ধারণ করে)
প্রসঙ্গ সচেতনতা	কোনটিই নয়	কোনটিই নয়	সম্পূর্ণ (ব্যবহারকারীর উদ্দেশ্য জানে)

বাস্তব-বিশ্বের উদাহরণ:

ব্যাচ স্ক্রিপ্ট :

Processing file 1... Done.
Processing file 2... ERROR: Corrupted image
[CRASH - User has to restart entire batch]

এজেন্টিক কর্মপ্রবাহ :

User: "Here are 3 images of our supply cache"
Agent: "Processing image 1... Found medical supplies ✅"
Agent: "Processing image 2... This file seems corrupted. Skipping. ⚠️"
Agent: "Processing image 3... Found food supplies ✅"
Agent: "Summary: I successfully processed 2 of 3 images. Would you like to re-upload image 2?"

কেন এটি গুরুত্বপূর্ণ: multimedia_agent.py (৪টি সাব-এজেন্ট সহ একটি SequentialAgent: আপলোড → এক্সট্র্যাক্ট → সংরক্ষণ → সারাংশ) ব্যবহার করে, আমরা জটিল অবকাঠামো এবং ভঙ্গুর স্ক্রিপ্টগুলিকে বুদ্ধিমান, কথোপকথনমূলক অ্যাপ্লিকেশন লজিক দিয়ে প্রতিস্থাপন করি।

১০. মাল্টিমোডাল পাইপলাইন — এজেন্ট স্তর

এজেন্ট স্তরটি বুদ্ধিমত্তাকে সংজ্ঞায়িত করে — এজেন্টরা কাজ সম্পন্ন করার জন্য সরঞ্জাম ব্যবহার করে। প্রতিটি এজেন্টের একটি নির্দিষ্ট ভূমিকা থাকে এবং প্রসঙ্গটি পরবর্তীটিতে প্রেরণ করে। নীচে মাল্টিএজেন্ট সিস্টেমের জন্য আর্কিটেকচার ডায়াগ্রাম দেওয়া হল।

১. এজেন্ট ফাইলটি খুলুন

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

2. আপলোড এজেন্টের সংজ্ঞা দিন

এই এজেন্ট ব্যবহারকারীর বার্তা থেকে একটি ফাইল পাথ বের করে এবং GCS-এ আপলোড করে।

multimedia_agent.py ফাইলে, # TODO: REPLACE_UPLOAD_AGENT মন্তব্যটি খুঁজুন।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

upload_agent = LlmAgent(
    name="UploadAgent",
    model="gemini-2.5-flash",
    instruction="""Extract the file path from the user's message and upload it.

Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.

Return the upload result with gcs_uri and media_type.""",
    tools=[upload_media],
    output_key="upload_result"
)

৩. নিষ্কাশন এজেন্টের সংজ্ঞা দাও

এই এজেন্ট আপলোড করা মিডিয়া "দেখে" এবং জেমিনি ভিশন ব্যবহার করে স্ট্রাকচার্ড ডেটা বের করে।

multimedia_agent.py ফাইলে, # TODO: REPLACE_EXTRACT_AGENT মন্তব্যটি খুঁজুন।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

extraction_agent = LlmAgent(
    name="ExtractionAgent", 
    model="gemini-2.5-flash",
    instruction="""Extract information from the uploaded media.

Previous step result: {upload_result}

Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].

Return the extraction results including entities and relationships found.""",
    tools=[extract_from_media],
    output_key="extraction_result"
)

লক্ষ্য করুন কিভাবে instruction {upload_result} উল্লেখ করে — ADK-তে এজেন্টদের মধ্যে এইভাবে অবস্থা প্রেরণ করা হয় ।

৪. স্প্যানার এজেন্টের সংজ্ঞা দাও

এই এজেন্টটি এক্সট্র্যাক্ট করা সত্তা এবং সম্পর্কগুলিকে গ্রাফ ডাটাবেসে সংরক্ষণ করে।

multimedia_agent.py ফাইলে, মন্তব্যটি # TODO: REPLACE_SPANNER_AGENT খুঁজুন।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

spanner_agent = LlmAgent(
    name="SpannerAgent",
    model="gemini-2.5-flash", 
    instruction="""Save the extracted information to the database.

Upload result: {upload_result}
Extraction result: {extraction_result}

Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.

Return the save statistics.""",
    tools=[save_to_spanner],
    output_key="spanner_result"
)

এই এজেন্টটি পূর্ববর্তী উভয় ধাপ ( upload_result এবং extraction_result ) থেকে প্রসঙ্গ গ্রহণ করে।

৫. সারাংশ এজেন্ট সংজ্ঞায়িত করুন

এই এজেন্টটি পূর্ববর্তী সমস্ত পদক্ষেপের ফলাফলগুলিকে একটি ব্যবহারকারী-বান্ধব প্রতিক্রিয়ায় সংশ্লেষিত করে।

multimedia_agent.py ফাইলে, মন্তব্য summary_instruction="" # TODO: REPLACE_SUMMARY_AGENT_PROMPT ।

এই পুরো লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""

summary_instruction = f"""Provide a user-friendly summary of the media processing.

Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}

Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}

Be concise but informative."""

এই এজেন্টের কোনও সরঞ্জামের প্রয়োজন নেই - এটি কেবল ভাগ করা প্রসঙ্গটি পড়ে এবং ব্যবহারকারীর জন্য একটি পরিষ্কার সারাংশ তৈরি করে।

🧠 স্থাপত্যের সারাংশ

স্তর	ফাইল	দায়িত্ব
টুলিং	extraction_tools.py + gcs_service.py	কিভাবে — আপলোড, এক্সট্র্যাক্ট, সংরক্ষণ
এজেন্ট	multimedia_agent.py	কী — পাইপলাইনটি সাজানো

১১. মাল্টিমোডাল ডেটা পাইপলাইন — অর্কেস্ট্রেশন

আমাদের নতুন সিস্টেমের মূল হলো backend/agent/multimedia_agent.py তে সংজ্ঞায়িত MultimediaExtractionPipeline পাইপলাইন। এটি ADK (এজেন্ট ডেভেলপমেন্ট কিট) থেকে সিকোয়েন্সিয়াল এজেন্ট প্যাটার্ন ব্যবহার করে।

১. কেন সিকোয়েনশিয়াল?

আপলোড প্রক্রিয়াকরণ একটি রৈখিক নির্ভরতা শৃঙ্খল:

1. ফাইল (আপলোড) না পাওয়া পর্যন্ত আপনি ডেটা বের করতে পারবেন না।
2. আপনি ডেটা এক্সট্রাক্ট না করা পর্যন্ত সংরক্ষণ করতে পারবেন না (এক্সট্রাকশন)।
3. ফলাফল না পাওয়া পর্যন্ত তুমি সারসংক্ষেপ করতে পারবে না (সংরক্ষণ করো)।

এর জন্য একটি SequentialAgent উপযুক্ত। এটি একটি এজেন্টের আউটপুটকে প্রসঙ্গ/ইনপুট হিসেবে অন্য এজেন্টে প্রেরণ করে।

2. এজেন্টের সংজ্ঞা

চলুন দেখি কিভাবে multimedia_agent.py এর নীচে পাইপলাইনটি একত্রিত করা হয়: 👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

এটি পূর্ববর্তী দুটি ধাপ থেকে ইনপুট গ্রহণ করে। মন্তব্যটি খুঁজুন # TODO: REPLACE_ORCHESTRATION । এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]

৩. রুট এজেন্টের সাথে সংযোগ করুন

👉💻 টার্মিনালে, ক্লাউড শেল এডিটরে ফাইলটি খুলুন:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

মন্তব্যটি সনাক্ত করুন # TODO: REPLACE_ADD_SUBAGENT । এই সম্পূর্ণ লাইনটি নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন :

    sub_agents=[multimedia_agent],

এই একক বস্তু কার্যকরভাবে চারজন "বিশেষজ্ঞ" কে একটি কলযোগ্য সত্তায় একত্রিত করে।

৪. এজেন্টদের মধ্যে তথ্য প্রবাহ

প্রতিটি এজেন্ট তার আউটপুট একটি ভাগ করা প্রসঙ্গে সংরক্ষণ করে যা পরবর্তী এজেন্টরা অ্যাক্সেস করতে পারে:

৫. অ্যাপ্লিকেশন খুলুন (অ্যাপটি এখনও চালু থাকলে এড়িয়ে যান)

যদি আপনার আগের অ্যাপ প্রক্রিয়াটি এখনও খোলা থাকে, তাহলে আপনি এই ধাপটি এড়িয়ে যেতে পারেন।

👉💻 অ্যাপ শুরু করুন:

cd ~/way-back-home/level_2/
./start_app.sh

👉 টার্মিনাল থেকে Local: http://localhost:5173/ এ ক্লিক করুন।

৬. পরীক্ষামূলক ছবি আপলোড

👉 চ্যাট ইন্টারফেসে, এখান থেকে যেকোনো একটি ছবি বেছে নিন এবং UI তে আপলোড করুন:

• পরীক্ষা_ছবি ১,
• পরীক্ষা_ছবি ২,
• পরীক্ষা_ছবি৩ ,
• পরীক্ষা_ছবি৪

চ্যাট ইন্টারফেসে, এজেন্টকে আপনার নির্দিষ্ট প্রেক্ষাপট সম্পর্কে বলুন:

Here is the survivor note

এবং তারপর ছবিটি এখানে সংযুক্ত করুন।

👉💻 টার্মিনালে, পরীক্ষা শেষ হলে, প্রক্রিয়াটি শেষ করতে "Ctrl+C" টিপুন।

What happens behind the scenes :

1. UploadAgent :

• Uploads file to Google Cloud Storage
• Detects media type (image/text/video)
• Generates signed URL for access

2. ExtractionAgent :

• Downloads image from GCS
• Sends to Gemini Vision with extraction prompt
• AI analyzes image for:
  • Survivors (names, conditions, roles)
  • Resources (medical supplies, tools)
  • Locations (biomes, coordinates)
  • Relationships (who has what, who is where)

3. SpannerAgent :

• Creates new entity nodes in Spanner
• Creates relationship edges
• Creates broadcast record with thumbnail

4. SummaryAgent :

• Synthesizes user-friendly summary
• Returns structured report

6. Verify Multimodal Uploading in GCS Bucket

• Open the Google Cloud Console Storage .
• Select "bucket" in cloud storage

• Select your bucket and click into media .

• View your uploaded image here.

7. Verify Multimodal Uploading in Spanner (Optional)

Below is example output in UI for test_photo1 .

Once you uploaded test_photo1 with note Here is the survivor note . You can see the message

**Summary:** A field report written on a clipboard details the discovery of an 'Energy Crystal' by David Chen in a 'Bioluminescent Forest', with the status marked as 'Critical'. The scene also includes a lit lantern, a pen, and a compass.

**Entities Found:**
*   **David Chen** (Survivor): The agent who filed this field report. His known role is Engineer.
*   **Engineer** (Skill): David Chen's known role or skill.
*   **Energy Crystal** (Resource): A newly discovered resource, depicted as a glowing blue crystal in a sketch on the report. Its purpose is implied to be energy-related.
*   **Bioluminescent Forest** (Biome): The location where the energy crystal was found. This matches the known biome description of a dark forest with glowing purple/neon plants and mushrooms.
*   **Critical Situation** (Need): The overall status of the situation is critical, indicating an urgent need for attention, response, or resource allocation.

**Relationships Found:**
*   **David Chen** (Survivor) found **Energy Crystal** (Resource).
*   **David Chen** (Survivor) is in **Bioluminescent Forest** (Biome).
*   **David Chen** (Survivor) has the skill **Engineer**.I have successfully saved the extracted information to the Spanner database.

Here are the save statistics:
*   **Broadcast ID:** `5892fb58-a120-46ca-80c2-0e04da7d6ea7`
*   **Entities Created:** 4
*   **Existing Entities:** 1
*   **Relationships Created:** 3
*   **Status:** successHere's a summary of the media processing:

In this case, we need to verify if spanner successfully updated information of:

*   **David Chen** (Survivor) found **Energy Crystal** (Resource).
*   **David Chen** (Survivor) is in **Bioluminescent Forest** (Biome).
*   **David Chen** (Survivor) has the skill **Engineer**.I have 

• Open the Google Cloud Console Spanner .
• Select your instance: Survivor Network
• Select your database: graph-db
• In the left sidebar, click Spanner Studio

👉 In Spanner Studio, query the new data:

SELECT 
  s.name AS Survivor,
  s.role AS Role,
  b.name AS Biome,
  r.name AS FoundResource,
  s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;

We can verify it by see the result below:

12. Memory Bank with Agent Engine

1. How Memory Works

The system uses a dual-memory approach to handle both immediate context and long-term learning.

2. What Are Memory Topics?

Memory Topics define the categories of information the agent should remember across conversations. Think of them as filing cabinets for different types of user preferences.

Why Not Just One Big Memory?

• ❌ Generic memory : "User said something about searching... and needs... and biomes..."
• ✅ Organized topics : Clear separation between search behavior vs. urgent monitoring

Our 2 Topics:

1. search_preferences : How the user likes to search
   • Do they prefer keyword or semantic search?
   • What skills/biomes do they search for often?
   • Example memory: "User prefers semantic search for medical skills"
2. urgent_needs_context : What crises they're tracking
   • What resources are they monitoring?
   • Which survivors are they concerned about?
   • Example memory: "User is tracking medicine shortage in Northern Camp"

Why 2 Topics?

• Precision : The LLM can extract facts into the correct category
• Retrieval : When the user asks "Find survivors with medical skills", the agent recalls from search_preferences , not unrelated urgent needs data
• Scalability : You can add more topics later (eg, favorite_survivors , alliance_tracking )

How It Works: When you chat with the agent, the Memory Bank automatically extracts facts that match these topic descriptions and saves them. Next time you start a new session, the agent retrieves relevant memories to personalize responses.

3. Setting Up Memory Topics

Custom memory topics define what the agent should remember. These are configured when deploying the Agent Engine.

👉💻 In the terminal, open the file in the Cloud Shell Editor by running:

cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py

This opens ~/way-back-home/level_2/backend/deploy_agent.py in your editor.

We define structure MemoryTopic objects to guide the LLM on what information to extract and save.

👉In the file deploy_agent.py , replace the # TODO: SET_UP_TOPIC with the following:

# backend/deploy_agent.py

    custom_topics = [
        # Topic 1: Survivor Search Preferences
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="search_preferences",
                description="""Extract the user's preferences for how they search for survivors. Include:
                - Preferred search methods (keyword, semantic, direct lookup)
                - Common filters used (biome, role, status)
                - Specific skills they value or frequently look for
                - Geographic areas of interest (e.g., "forest biome", "mountain outpost")
                
                Example: "User prefers semantic search for finding similar skills."
                Example: "User frequently checks for survivors in the Swamp Biome."
                """,
            )
        ),
        # Topic 2: Urgent Needs Context
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="urgent_needs_context",
                description="""Track the user's focus on urgent needs and resource shortages. Include:
                - Specific resources they are monitoring (food, medicine, ammo)
                - Critical situations they are tracking
                - Survivors they are particularly concerned about
                
                Example: "User is monitoring the medicine shortage in the Northern Camp."
                Example: "User is looking for a doctor for the injured survivors."
                """,
            )
        )
    ]

4. Agent Integration

The agent code must be aware of the Memory Bank to save and retrieve information.

👉💻 In the terminal, open the file in the Cloud Shell Editor by running:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

This opens ~/way-back-home/level_2/backend/agent/agent.py in your editor.

Agent Creation

When creating the agent, we pass the after_agent_callback to ensure sessions are saved to memory after interactions. The add_session_to_memory function runs asynchronously to avoid slowing down the chat response.

👉In the file agent.py , locate the comment # TODO: REPLACE_ADD_SESSION_MEMORY , Replace this whole line with the following code:

async def add_session_to_memory(
        callback_context: CallbackContext
) -> Optional[types.Content]:
    """Automatically save completed sessions to memory bank in the background"""
    if hasattr(callback_context, "_invocation_context"):
        invocation_context = callback_context._invocation_context
        if invocation_context.memory_service:
            # Use create_task to run this in the background without blocking the response
            asyncio.create_task(
                invocation_context.memory_service.add_session_to_memory(
                    invocation_context.session
                )
            )
            logger.info("Scheduled session save to memory bank in background")

Background Saving

👉In the file agent.py , locate the comment # TODO: REPLACE_ADD_MEMORY_BANK_TOOL , Replace this whole line with the following code:

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

👉In the file agent.py , locate the comment # TODO: REPLACE_ADD_CALLBACK , Replace this whole line with the following code:

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

Set Up Vertex AI Session Service

👉💻 In the terminal, open the file chat.py in the Cloud Shell Editor by running:

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

👉In chat.py file, locate the comment # TODO: REPLACE_VERTEXAI_SERVICES , Replace this whole line with the following code:

    session_service = VertexAiSessionService(
        project=project_id,
        location=location,
        agent_engine_id=agent_engine_id
    )
    memory_service = VertexAiMemoryBankService(
        project=project_id,
        location=location,
        agent_engine_id=agent_engine_id
    )

4. Setup & Deployment

Before testing the memory features, you need to deploy the agent with the new memory topics and ensure your environment is configured correctly.

We have provided a convenience script to handle this process.

Running the Deployment Script

👉💻 In the terminal, run the deployment script:

cd ~/way-back-home/level_2
./deploy_and_update_env.sh

This script performs the following actions:

• Runs backend/deploy_agent.py to register the agent and memory topics with Vertex AI.
• Captures the new Agent Engine ID .
• Automatically updates your .env file with AGENT_ENGINE_ID .
• Ensures USE_MEMORY_BANK=TRUE is set in your .env file.

[!IMPORTANT] If you make changes to custom_topics in deploy_agent.py , you must re-run this script to update the Agent Engine.

13. Verify Memory Bank with Multimodal Data

You can verify that the memory bank is working by teaching the agent a preference and checking if it persists across sessions.

1. Open the application (Skip this step if your application is already running)

Open the Application again by following the instruction below: If the previous terminal is still running, end it by pressing Ctrls+C .

👉💻 Start App:

cd ~/way-back-home/level_2/
./start_app.sh

👉 Click Local: http://localhost:5173/ from the terminal.

2. Testing Memory Bank with Text

In the chat interface, tell the agent about your specific context:

"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."

👉 Wait ~30 seconds for the memory to process in the background.

2. Start a New Session

Refresh the page to clear the current conversation history (short-term memory).

Ask a question that relies on the context you provided earlier:

"What kind of missions am I interested in?"

Expected Response :

"Based on your previous conversations, you're interested in:

• Medical rescue missions
• Mountain/high-altitude operations
• Skills needed: first aid, climbing

Would you like me to find survivors matching these criteria?"

3. Test with Image Upload

Upload an image, and ask:

remember this

You can choose any of the photo here or your own and upload to the UI:

• test_photo1 ,
• test_photo2 ,
• test_photo3 ,
• test_photo4

4. Verify in Vertex AI Agent Engine

Go to Google Cloud Console Agent Engine

1. Make sure you select the project from top left project selector:
2. Verify the agent engine you just deployed from previous command use_memory_bank.sh : Click into the agent engine you just created.
3. Click the Memories Tab in this deployed agent, you can view all the memory here.

👉💻 When you finish testing, in you terminal, click "Ctrl + C" to end the process.

🎉 Congratulations! You just attached the memory bank to your agent!

14. Deploy to Cloud Run

1. Run the Deployment Script

👉💻 Run the deployment script:

cd ~/way-back-home/level_2
./deploy_cloud_run.sh

After it successfully deployed, you will have the url, this is deployed url for you!

👉💻 Before you grab the url, grant the permission by running:

source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker

Go to the deployed url, and you will see you application live there!

2. Understanding the Build Pipeline

The cloudbuild.yaml file defines the following sequential steps:

1. Backend Build : Builds the Docker image from backend/Dockerfile .
2. Backend Deploy : Deploys the backend container to Cloud Run.
3. Capture URL : Gets the new Backend URL.
4. Frontend Build :
   • Installs dependencies.
   • Builds the React app, injecting VITE_API_URL= .
5. Frontend Image : Builds the Docker image from frontend/Dockerfile (packaging the static assets).
6. Frontend Deploy : Deploys the frontend container.

3. Verify Deployment

Once the build completes (check the logs link provided by the script), you can verify:

1. Go to the Cloud Run Console .
2. Find the survivor-frontend service.
3. Click the URL to open the application.
4. Perform a search query to ensure the frontend can talk to the backend.

4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location

👉💻 Run the completion script:

cd ~/way-back-home/level_2
./set_level_2.sh

If you haven't attended workshop and finished level 0, you will see error message.

Now open waybackhome.dev , and you will see your location has updated. Congratulations on finishing level 2!

(OPTIONAL) 5. Manual Deployment

If you prefer to run the commands manually or understand the process better, here is how to use cloudbuild.yaml directly.

Writing cloudbuild.yaml

A cloudbuild.yaml file tells Google Cloud Build what steps to execute.

• steps : A list of sequential actions. Each step runs in a container (eg, docker , gcloud , node , bash ).
• substitutions : Variables that can be passed at build time (eg, $_REGION ).
• workspace : A shared directory where steps can share files (like how we share backend_url.txt ).

Running the Deployment

To deploy manually without the script, use the gcloud builds submit command. You MUST pass the required substitution variables.

# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1

gcloud builds submit --config cloudbuild.yaml \
    --project "$PROJECT_ID" \
    --substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"

15. Conclusion

1. What You've Built

✅ Graph Database : Spanner with nodes (survivors, skills) and edges (relationships)
✅ AI Search : Keyword, semantic, and hybrid search with embeddings
✅ Multimodal Pipeline : Extract entities from images/video with Gemini
✅ Multi-Agent System : Coordinated workflow with ADK
✅ Memory Bank : Long-term personalization with Vertex AI
✅ Production Deployment : Cloud Run + Agent Engine

2. Architecture Summary

3. Key Learnings

1. Graph RAG : Combines graph database structure with semantic embeddings for intelligent search
2. Multi-Agent Patterns : Sequential pipelines for complex, multi-step workflows
3. Multimodal AI : Extract structured data from unstructured media (images/video)
4. Stateful Agents : Memory Bank enables personalization across sessions

4. Workshop Content

• Level0 : Identify Yourself
• Level1 : Pinpoint Location
• Level2 This One : Build a Multimodal AI Agent with Graph RAG, ADK & Memory Bank
• Level3 : Building an ADK Bi-Directional Streaming Agent
• Level4 : Live Bidirectional Multi-Agent system
• Level5 : Event-Driven Architecture with Google ADK, A2A, and Kafka

5. Resources

• ADK Documentation
• Spanner Graph
• Memory Bank Guide
• GitHub Repository

Congratulations! You've built a production-grade AI agent system with graph database, RAG search, multimodal processing, and long-term memory. These patterns apply to any domain requiring intelligent data coordination—from logistics to healthcare to customer service.