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

১. ভূমিকা

১. চ্যালেঞ্জ

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

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

২. আপনি যা তৈরি করবেন

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

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

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

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

২. 🛠️ পরিবেশ প্রস্তুতি (আপনি ওয়ার্কশপে থাকলে এই অংশটি বাদ দিন)

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

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

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

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

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

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

   gcloud auth list
   

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

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

তৃতীয় পর্ব: একটি নতুন প্রজেক্ট তৈরি করুন

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

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

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

৩. 🛠️ পরিবেশ সেটআপ

১. ক্লাউড শেল খুলুন

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

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

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

২. প্রজেক্ট কনফিগার করুন

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

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 পরের লিঙ্কে ক্লিক করলে আপনি গুগল ক্লাউড কনসোল স্প্যানার খুলতে পারবেন।

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

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

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

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

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

২. গ্রাফের গঠন বোঝা (বৃহৎ চিত্র)

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

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

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

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

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

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

ডেটার মধ্যে 'Story' দেখতে চলুন কয়েকটি কোয়েরি চালানো যাক।

স্প্যানার গ্রাফ 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 টেবিল কোয়েরি করুন → দক্ষতাগুলো পান
• SkillTreatsNeed টেবিলটি কোয়েরি করুন → কোন চাহিদাগুলো মেলে তা খুঁজুন
• SurvivorHasNeed টেবিলটি কোয়েরি করুন → কাদের এই চাহিদাগুলো আছে তা খুঁজুন
• অ্যাপ্লিকেশন কোডে সমস্ত ফলাফল একত্রিত করুন

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

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

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

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

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

১. এমবেডিং কেন? (কোনো কাজ করতে হবে না, শুধু পড়ার জন্য)

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

প্রচলিত অনুসন্ধানের সমস্যা :

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

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

বাস্তব পরিস্থিতি : বেঁচে যাওয়া ব্যক্তি: Captain Tanaka has burns—we need medical help NOW!

'মেডিক' এর জন্য প্রচলিত কীওয়ার্ড অনুসন্ধান → ০টি ফলাফল ❌

এমবেডিং ব্যবহার করে শব্দার্থিক অনুসন্ধান → 'মেডিকেল ট্রেনিং', 'ফার্স্ট এইড' খুঁজে পাওয়া গেছে ✅

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

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

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

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

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

ML.PREDICT বলতে কী বোঝায়?

ML.PREDICT হলো স্প্যানারের একটি বিল্ট-ইন ফাংশন, যা আপনাকে সরাসরি SQL থেকে মেশিন লার্নিং মডেল কল করতে দেয় — কোনো পাইথন, এক্সপোর্ট/ইম্পোর্ট বা আলাদা সার্ভিসের প্রয়োজন নেই। এটিকে আপনার ডাটাবেস এবং ভার্টেক্স এআই-এর মধ্যে রিয়েল-টাইমে সংযোগ স্থাপনকারী হিসেবে ভাবা যেতে পারে।

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

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

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

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

এখন চলুন গুগলের 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; করবেন।

এটি যা করে :

• স্প্যানারে একটি ভার্চুয়াল মডেল তৈরি করে (মডেলের কোনো ওয়েট স্থানীয়ভাবে সংরক্ষিত থাকে না)
• ভার্টেক্স এআই-তে গুগলের text-embedding-004 নির্দেশ করে।
• চুক্তিটি সংজ্ঞায়িত করে: ইনপুট হলো টেক্সট, আউটপুট হলো একটি ৭৬৮-মাত্রার ফ্লোট অ্যারে।

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

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

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

এটি একটি "ভার্চুয়াল মডেল" তৈরি করে যা ভার্টেক্স এআই-এর টেক্সট-এম্বেডিং-০০৪-কে রেফারেন্স করে। স্প্যানার থেকে কোনো ডেটা বাইরে যায় না—এটি এপিআই-এর মাধ্যমে কল করা হয়।

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

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

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

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

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

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

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; করবেন।

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

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

👉 এমবেডিংগুলো তৈরি হয়েছে কিনা তা যাচাই করুন:

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))

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

৩. মিথুন রাশি প্রতিক্রিয়া সৃষ্টি করে :

"**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) প্রয়োগ করবেন – অর্থাৎ শুধু কীওয়ার্ড নয়, অর্থের মাধ্যমেও ফলাফল খুঁজে বের করবেন। পরবর্তীতে, আমরা ব্যাখ্যা করব কীভাবে হাইব্রিড সার্চ একাধিক পদ্ধতিকে একত্রিত করে।

২. 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
        """

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

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

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

দাঁড়ান, এটা তো শুধু SQL?

হ্যাঁ! স্প্যানার গ্রাফ আপনাকে JOIN স্টেটমেন্ট সহ স্ট্যান্ডার্ড SQL ব্যবহার করে গ্রাফের সম্পর্কগুলো কোয়েরি করার সুযোগ দেয়। গ্রাফের কাঠামো ( SurvivorHasSkill এজ-এর মাধ্যমে সারভাইভার → স্কিল) রিলেশনাল টেবিলে সংরক্ষিত থাকে, যেগুলোকে আপনি একসাথে জয়েন করতে পারেন। এটি প্রচলিত গ্রাফ ডেটাবেস থেকে ভিন্ন, যেগুলোর জন্য সাইফার (Cypher) বা গ্রেমলিন (Gremlin)-এর মতো বিশেষায়িত কোয়েরি ল্যাঙ্গুয়েজের প্রয়োজন হয়।

কেন একে 'গ্রাফ র‍্যাগ' বলা হয় :

• গ্রাফ : আমরা গ্রাফ কাঠামোতে সংরক্ষিত সম্পর্কগুলো (উত্তরাধিকারী → দক্ষতা) পরিভ্রমণ করছি।
• 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() কল করা হয়, তখন সার্ভিসটি রেসিপ্রোকাল র‍্যাঙ্ক ফিউশন (RRF) ব্যবহার করে উভয় সার্চ চালায় এবং ফলাফলগুলোকে মার্জ করে।

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

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

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

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

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

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

৭. 🚀 ADK Web দিয়ে আপনার এজেন্ট পরীক্ষা করা

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

১. এজেন্ট চালানো

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

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

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

agent/agent.py

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

👉 ইউআরএলটি খুলুন:

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

ইউআরএল-টিতে ক্লিক করলে আপনি এডিকে ওয়েব ইউআই দেখতে পাবেন। উপরের বাম কোণ থেকে 'এজেন্ট' নির্বাচন করতে ভুলবেন না।

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

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

🧬 এ. গ্রাফ র‍্যাগ (সিমান্টিক সার্চ)

কীওয়ার্ড না মিললেও অর্থ ও ধারণার ভিত্তিতে আইটেম খুঁজে বের করে।

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

Who can help with injuries?

What abilities are related to survival?

কী কী দেখতে হবে:

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

🔀 খ. হাইব্রিড সার্চ

জটিল কোয়েরির জন্য কীওয়ার্ড ফিল্টার এবং শব্দার্থগত উপলব্ধির সমন্বয় ঘটায়।

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

Find someone who can fly 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"
)

১. অ্যাপ্লিকেশন শুরু করুন

যদি আগের টার্মিনালটি এখনও চালু থাকে, তাহলে Ctrl+C চেপে সেটি বন্ধ করুন।

👉💻 অ্যাপটি চালু করুন:

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

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

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

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

প্রশ্ন :

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 চেপে এটি বন্ধ করুন।

৪. (শুধুমাত্র কর্মশালার অংশগ্রহণকারীদের জন্য) আপনার অবস্থান হালনাগাদ করুন।

👉💻 সমাপ্তি স্ক্রিপ্টটি চালান:

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

আপনি যদি কর্মশালায় অংশগ্রহণ না করে লেভেল ০ সম্পন্ন না করেন, তাহলে একটি ত্রুটির বার্তা দেখতে পাবেন।

এখন waybackhome.dev খুলুন, এবং আপনি দেখতে পাবেন আপনার অবস্থান আপডেট হয়ে গেছে। লেভেল ২ সফলভাবে সম্পন্ন করার জন্য অভিনন্দন!

৯. ☕️ [ঐচ্ছিক] মাল্টিমোডাল পাইপলাইন (শুধুমাত্র পঠনযোগ্য) — টুলিং লেয়ার

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

বেঁচে থাকার নেটওয়ার্ক শুধু টেক্সট-ভিত্তিক নয়। মাঠে থাকা বেঁচে থাকা ব্যক্তিরা সরাসরি চ্যাটের মাধ্যমে অসংগঠিত ডেটা পাঠান:

• 📸 ছবি : সম্পদ, বিপদ বা সরঞ্জামের ছবি
• 🎥 ভিডিও : অবস্থার প্রতিবেদন বা জরুরি সাহায্যের বার্তা
• 📄 পাঠ্য : মাঠের নোট বা লগ

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

বাস্তব পরিস্থিতি :

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

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

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

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

পূর্ববর্তী ধাপে আমরা বিদ্যমান ডেটা অনুসন্ধান করলেও, এখানে আমরা ব্যবহারকারীর আপলোড করা ফাইলগুলো প্রসেস করি। chat.py ইন্টারফেসটি ফাইল অ্যাটাচমেন্টগুলো ডাইনামিকভাবে পরিচালনা করে:

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

পরিকল্পিত পদ্ধতি: অনুক্রমিক এজেন্ট পাইপলাইন

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

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

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

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

👉💻 level_2/backend/agent/tools/extraction_tools.py ফাইলটি খুলুন অথবা টার্মিনালে নিম্নলিখিত কমান্ডটি টাইপ করুন। একটি নতুন টার্মিনাল খুলুন। টার্মিনালে, ক্লাউড শেল এডিটর-এ ফাইলটি খুলুন:

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

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

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

👉 def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]: এর মধ্যে, নিম্নলিখিত কোডটি GCS-এ ফাইল আপলোড করার পদ্ধতি এবং ফাইলের ধরন শনাক্ত করা সম্পর্কিত:

    """
    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 পরীক্ষা করে এবং সঠিক এক্সট্র্যাক্টরে (টেক্সট, ইমেজ বা ভিডিও) প্রেরণ করে।

👉 async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]: ` ফাংশনের মধ্যে, আপলোড করা মিডিয়া থেকে কীভাবে এনটিটি এবং রিলেশনশিপ বের করতে হয়, নিচের কোডটি তা-ই দেখায়।

    """
    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)}

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

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

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

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

👉 def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]: এর মধ্যে, নিম্নলিখিত কোডটি স্প্যানার গ্রাফ ডিবি-তে এক্সট্র্যাক্ট করা এনটিটি এবং রিলেশনশিপগুলি কীভাবে সেভ করতে হয়, তা নিয়ে আলোচনা করে।

    """
    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 গুগল ক্লাউড স্টোরেজে ফাইল আপলোডের কাজটি পরিচালনা করে।

👉💻 level_2/backend/services/gcs_service.py ফাইলটি খুলুন, অথবা ক্লাউড শেল এডিটরে ফাইলটি খোলার জন্য টার্মিনালে টাইপ করুন:

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

👉 def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]: মধ্যে, নিম্নলিখিত কোডটি স্প্যানার গ্রাফ ডিবি-তে এক্সট্র্যাক্ট করা এনটিটি এবং রিলেশনশিপগুলি কীভাবে সেভ করতে হয়, তা নিয়ে আলোচনা করে।

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

এই বিষয়টিকে একটি সার্ভিসে রূপান্তরিত করার ফলে, এজেন্টের আর GCS বাকেট, ব্লব নেম বা সাইনড ইউআরএল জেনারেশন সম্পর্কে জানার প্রয়োজন হয় না। এটি শুধু 'আপলোড' করার জন্য অনুরোধ করে।

৬. কেন এজেন্টিক ওয়ার্কফ্লো > প্রচলিত পদ্ধতিসমূহ?

এই পাইপলাইনটি তৈরি করার দুটি প্রচলিত উপায় আছে। দুটিরই বড় ধরনের অসুবিধা রয়েছে, যেগুলোর সমাধান করে এজেন্টিক ওয়ার্কফ্লো ।

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

একটি সাধারণ ব্যাচ স্ক্রিপ্ট যা ফাইলগুলিকে ক্রমানুসারে প্রক্রিয়া করে:

# 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 (একটি সিকোয়েনশিয়ালএজেন্ট যার ৪টি সাব-এজেন্ট রয়েছে: আপলোড → এক্সট্র্যাক্ট → সেভ → সামারি) ব্যবহার করে, আমরা জটিল পরিকাঠামো এবং ভঙ্গুর স্ক্রিপ্টগুলোকে বুদ্ধিমান, কথোপকথনমূলক অ্যাপ্লিকেশন লজিক দিয়ে প্রতিস্থাপন করি।

১০. ☕️ [ঐচ্ছিক] মাল্টিমোডাল পাইপলাইন (শুধুমাত্র পঠনযোগ্য) — এজেন্ট লেয়ার

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

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

👉💻 level_2/backend/agent/multimedia_agent.py ফাইলটি খুলুন অথবা টার্মিনালে নিম্নলিখিত কমান্ডটি টাইপ করুন। একটি নতুন টার্মিনাল খুলুন। টার্মিনালে, ক্লাউড শেল এডিটর-এ ফাইলটি খুলুন:

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

২. আপলোড এজেন্ট নির্ধারণ করুন

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

multimedia_agent.py ফাইলে নিচের কোডটির সাহায্যে upload_agent তৈরি করা হয়, যা GCS-এ আপলোড করে:

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 ফাইলে নিচের কোডটি extraction_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 ফাইলে নিচের কোডটি ব্যবহার করে 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_agent জন্য প্রম্পট নির্ধারণ করা হয়, যা ফলাফলের সারসংক্ষেপ করে:

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. ডেটা এক্সট্র্যাক্ট (Extraction) না করা পর্যন্ত আপনি তা সেভ করতে পারবেন না।
3. ফলাফল না পাওয়া পর্যন্ত আপনি সারসংক্ষেপ করতে পারবেন না (সংরক্ষণ করুন)।

এর জন্য একটি SequentialAgent একদম উপযুক্ত। এটি একটি এজেন্টের আউটপুটকে পরবর্তী এজেন্টের কনটেক্সট/ইনপুট হিসেবে প্রেরণ করে।

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

চলুন দেখে নেওয়া যাক 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-তে আপলোড করুন:

• test_photo1 ,
• test_photo2 ,
• test_photo3 ,
• পরীক্ষার ছবি ৪

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

Here is the survivor note

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

👉💻 টার্মিনালে, টেস্টিং শেষ হলে প্রসেসটি বন্ধ করতে "Ctrl+C" চাপুন।

নেপথ্যে যা ঘটে :

1. আপলোডএজেন্ট :

• গুগল ক্লাউড স্টোরেজে ফাইল আপলোড করে
• মিডিয়ার ধরণ (ছবি/টেক্সট/ভিডিও) শনাক্ত করে।
• অ্যাক্সেসের জন্য স্বাক্ষরিত URL তৈরি করে

2. নিষ্কাশন এজেন্ট :

• GCS থেকে ছবি ডাউনলোড করুন
• নিষ্কাশনের অনুরোধ সহ জেমিনি ভিশনে পাঠানো হয়েছে
• এআই ছবি বিশ্লেষণ করে:
  • উত্তরজীবীরা (নাম, অবস্থা, ভূমিকা)
  • সম্পদ (চিকিৎসা সামগ্রী, সরঞ্জাম)
  • অবস্থান (বায়োম, স্থানাঙ্ক)
  • সম্পর্ক (কার কী আছে, কে কোথায় আছে)

3. স্প্যানারএজেন্ট :

• স্প্যানারে নতুন এনটিটি নোড তৈরি করে
• সম্পর্কের প্রান্ত তৈরি করে
• থাম্বনেইল সহ সম্প্রচার রেকর্ড তৈরি করে

4. সারসংক্ষেপ এজেন্ট :

• ব্যবহারকারী-বান্ধব সারসংক্ষেপ সংশ্লেষণ করে
• কাঠামোগত প্রতিবেদন ফেরত

৬. GCS বাকেটে মাল্টিমোডাল আপলোডিং যাচাই করুন

• গুগল ক্লাউড কনসোল স্টোরেজ খুলুন।
• ক্লাউড স্টোরেজে 'বাকেট' নির্বাচন করুন

• আপনার বাকেটটি নির্বাচন করুন এবং media ক্লিক করুন।

• আপনার আপলোড করা ছবিটি এখানে দেখুন।

৭. স্প্যানারে মাল্টিমোডাল আপলোডিং যাচাই করুন (ঐচ্ছিক)

নিচে test_photo1 এর জন্য UI-তে আউটপুটের একটি উদাহরণ দেওয়া হলো।

একবার আপনি test_photo1 Here is the survivor note নোটসহ আপলোড করলে, আপনি বার্তাটি দেখতে পাবেন।

**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:

এক্ষেত্রে, আমাদের যাচাই করতে হবে যে স্প্যানার সফলভাবে নিম্নলিখিত তথ্যগুলো আপডেট করেছে কি না:

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

• গুগল ক্লাউড কনসোল স্প্যানারটি খুলুন।
• আপনার ইনস্ট্যান্স নির্বাচন করুন: Survivor Network
• আপনার ডাটাবেস নির্বাচন করুন: graph-db
• বাম সাইডবারে, স্প্যানার স্টুডিও- তে ক্লিক করুন।

👉 স্প্যানার স্টুডিওতে নতুন ডেটা কোয়েরি করুন:

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;

আমরা নীচের ফলাফলটি দেখে এটি যাচাই করতে পারি:

১২. ☕️ [ঐচ্ছিক] এজেন্ট ইঞ্জিন সহ মেমরি ব্যাংক

১. স্মৃতি কীভাবে কাজ করে

সিস্টেমটি তাৎক্ষণিক প্রেক্ষাপট এবং দীর্ঘমেয়াদী শিক্ষা উভয়ই পরিচালনা করতে একটি দ্বৈত-স্মৃতি পদ্ধতি ব্যবহার করে।

২. স্মৃতি বিষয়ক বিষয়গুলো কী?

মেমোরি টপিকস সেইসব তথ্যের বিভাগ নির্ধারণ করে যা এজেন্টকে বিভিন্ন কথোপকথন জুড়ে মনে রাখতে হবে। এগুলোকে ব্যবহারকারীর বিভিন্ন ধরনের পছন্দের জন্য ফাইল ক্যাবিনেট হিসেবে ভাবা যেতে পারে।

কেন শুধু একটি বড় স্মৃতি নয়?

• ❌ জেনেরিক মেমোরি : "ব্যবহারকারী অনুসন্ধান... এবং চাহিদা... এবং বায়োম... সম্পর্কে কিছু একটা বলেছিলেন।"
• ✅ সুসংগঠিত বিষয়সমূহ : অনুসন্ধানমূলক আচরণ এবং জরুরি পর্যবেক্ষণের মধ্যে সুস্পষ্ট বিভাজন

আমাদের দুটি বিষয়:

1. search_preferences : ব্যবহারকারী কীভাবে অনুসন্ধান করতে পছন্দ করেন
   • তারা কি কীওয়ার্ড নাকি সিমান্টিক সার্চ পছন্দ করেন?
   • তারা প্রায়শই কোন দক্ষতা/বায়োমগুলো অনুসন্ধান করে?
   • উদাহরণ মেমরি: "ব্যবহারকারী চিকিৎসা দক্ষতার জন্য শব্দার্থিক অনুসন্ধান পছন্দ করেন"
2. urgent_needs_context : তারা কোন সংকটগুলো পর্যবেক্ষণ করছে
   • তারা কোন সম্পদগুলো পর্যবেক্ষণ করছে?
   • তারা কোন বেঁচে থাকা ব্যক্তিদের নিয়ে চিন্তিত?
   • উদাহরণ মেমরি: "ব্যবহারকারী নর্দার্ন ক্যাম্পে ওষুধের ঘাটতি ট্র্যাক করছেন"

কেন ২টি বিষয়?

• নির্ভুলতা : এলএলএম তথ্যগুলোকে সঠিক শ্রেণীতে বিন্যস্ত করতে পারে।
• তথ্য পুনরুদ্ধার : যখন ব্যবহারকারী "চিকিৎসা দক্ষতা সম্পন্ন জীবিতদের খুঁজুন" জিজ্ঞাসা করেন, তখন এজেন্ট search_preferences থেকে সম্পর্কহীন জরুরি চাহিদার ডেটা পুনরুদ্ধার করে।
• সম্প্রসারণযোগ্যতা : আপনি পরে আরও বিষয় যোগ করতে পারেন (যেমন, favorite_survivors , alliance_tracking )।

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

৩. স্মৃতি বিষয়ক বিষয়বস্তু নির্ধারণ করা

কাস্টম মেমরি টপিকগুলো নির্ধারণ করে যে এজেন্ট কী মনে রাখবে। এজেন্ট ইঞ্জিন ডেপ্লয় করার সময় এগুলো কনফিগার করা হয়।

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

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

এটি আপনার এডিটরে ~/way-back-home/level_2/backend/deploy_agent.py খুলবে।

কোন তথ্য নিষ্কাশন ও সংরক্ষণ করতে হবে, সে বিষয়ে এলএলএম-কে নির্দেশনা দেওয়ার জন্য আমরা MemoryTopic ) স্ট্রাকচার অবজেক্ট সংজ্ঞায়িত করি।

deploy_agent.py ফাইলে, # TODO: SET_UP_TOPIC নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন:

# 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."
                """,
            )
        )
    ]

৪. এজেন্ট ইন্টিগ্রেশন

তথ্য সংরক্ষণ ও পুনরুদ্ধার করার জন্য এজেন্ট কোডকে অবশ্যই মেমোরি ব্যাংক সম্পর্কে অবগত থাকতে হবে।

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

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

এটি আপনার এডিটরে ~/way-back-home/level_2/backend/agent/agent.py খুলবে।

এজেন্ট তৈরি

এজেন্ট তৈরি করার সময়, ইন্টারঅ্যাকশনের পরে সেশনগুলো মেমরিতে সংরক্ষিত হয় তা নিশ্চিত করতে আমরা after_agent_callback ফাংশনটি পাস করি। চ্যাট প্রতিক্রিয়ার গতি কমে যাওয়া এড়াতে add_session_to_memory ফাংশনটি অ্যাসিঙ্ক্রোনাসভাবে চলে।

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

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")

পটভূমি সংরক্ষণ

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

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

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

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

ভার্টেক্স এআই সেশন সার্ভিস সেট আপ করুন

👉💻 টার্মিনালে, ক্লাউড শেল এডিটর-এ chat.py ফাইলটি খুলতে নিম্নলিখিত কমান্ডটি চালান:

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

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

    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
    )

১৩. ☕️ [ঐচ্ছিক] এজেন্টকে এজেন্ট ইঞ্জিনের সাথে সংযুক্ত করুন

১. সেটআপ ও স্থাপন

মেমরি ফিচারগুলো পরীক্ষা করার আগে, আপনাকে নতুন মেমরি টপিকগুলো সহ এজেন্টটি ডেপ্লয় করতে হবে এবং আপনার পরিবেশটি সঠিকভাবে কনফিগার করা আছে কিনা তা নিশ্চিত করতে হবে।

এই প্রক্রিয়াটি পরিচালনা করার জন্য আমরা একটি সুবিধাজনক স্ক্রিপ্ট প্রদান করেছি।

ডিপ্লয়মেন্ট স্ক্রিপ্ট চালানো হচ্ছে

👉💻 টার্মিনালে, ডিপ্লয়মেন্ট স্ক্রিপ্টটি চালান:

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

এই স্ক্রিপ্টটি নিম্নলিখিত কাজগুলো সম্পাদন করে:

• Vertex AI-এর সাথে এজেন্ট এবং মেমরি টপিকগুলো রেজিস্টার করার জন্য backend/deploy_agent.py রান করা হয়।
• নতুন এজেন্ট ইঞ্জিন আইডিটি ধারণ করে।
• AGENT_ENGINE_ID দিয়ে আপনার .env ফাইলটি স্বয়ংক্রিয়ভাবে আপডেট করে।
• আপনার .env ফাইলে USE_MEMORY_BANK=TRUE সেট করা আছে কিনা তা নিশ্চিত করুন।

[গুরুত্বপূর্ণ] আপনি যদি deploy_agent.py তে custom_topics এ কোনো পরিবর্তন করেন, তাহলে এজেন্ট ইঞ্জিন আপডেট করার জন্য আপনাকে অবশ্যই এই স্ক্রিপ্টটি পুনরায় চালাতে হবে।

মেমরি ব্যাংক যাচাই করুন

এখন আপনি এজেন্টকে একটি পছন্দ শিখিয়ে এবং সেটি বিভিন্ন সেশন জুড়ে টিকে থাকে কিনা তা পরীক্ষা করে মেমরি ব্যাংকটি কাজ করছে কিনা তা যাচাই করতে পারেন।

প্রথম ধাপ। অ্যাপ্লিকেশনটি খুলুন।

নিচের নির্দেশনা অনুসরণ করে অ্যাপ্লিকেশনটি পুনরায় খুলুন: যদি পূর্ববর্তী টার্মিনালটি এখনও চালু থাকে, তবে Ctrls+C চেপে সেটি বন্ধ করুন।

👉💻 অ্যাপটি চালু করুন:

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

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

দ্বিতীয় ধাপ। টেক্সটের মাধ্যমে মেমরি ব্যাংক পরীক্ষা করা।

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

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

👉 ব্যাকগ্রাউন্ডে মেমরি প্রসেস হওয়ার জন্য প্রায় ৩০ সেকেন্ড অপেক্ষা করুন ।

ধাপ তিন। একটি নতুন সেশন শুরু করুন।

বর্তমান কথোপকথনের ইতিহাস (স্বল্পমেয়াদী স্মৃতি) মুছে ফেলার জন্য পৃষ্ঠাটি রিফ্রেশ করুন।

পূর্বে আপনার দেওয়া প্রেক্ষাপটের উপর ভিত্তি করে একটি প্রশ্ন করুন:

"What kind of missions am I interested in?"

প্রত্যাশিত প্রতিক্রিয়া :

আপনার পূর্ববর্তী কথোপকথনের ভিত্তিতে, আপনি নিম্নলিখিত বিষয়গুলিতে আগ্রহী:

• চিকিৎসা উদ্ধার অভিযান
• পর্বত/উচ্চ-উচ্চতার কার্যক্রম
• প্রয়োজনীয় দক্ষতা: প্রাথমিক চিকিৎসা, আরোহণ

আপনি কি চান আমি এই মানদণ্ডগুলোর সাথে মেলে এমন জীবিত ব্যক্তিদের খুঁজে বের করি?

চতুর্থ ধাপ। ছবি আপলোড করে পরীক্ষা করুন।

একটি ছবি আপলোড করুন এবং জিজ্ঞাসা করুন:

remember this

আপনি এখান থেকে যেকোনো ছবি অথবা আপনার নিজের ছবি বেছে নিয়ে UI-তে আপলোড করতে পারেন:

• test_photo1 ,
• test_photo2 ,
• test_photo3 ,
• পরীক্ষার ছবি ৪

পঞ্চম ধাপ। ভার্টেক্স এআই এজেন্ট ইঞ্জিনে যাচাই করুন।

গুগল ক্লাউড কনসোল এজেন্ট ইঞ্জিনে যান

1. নিশ্চিত করুন যে আপনি উপরের বাম দিকের প্রজেক্ট সিলেক্টর থেকে প্রজেক্টটি নির্বাচন করেছেন:
2. পূর্ববর্তী কমান্ড use_memory_bank.sh থেকে আপনি এইমাত্র স্থাপন করা এজেন্ট ইঞ্জিনটি যাচাই করুন: আপনি এইমাত্র যে এজেন্ট ইঞ্জিনটি তৈরি করেছেন, সেটিতে ক্লিক করুন।
3. এই ডেপ্লয় করা এজেন্টের Memories ট্যাবে ক্লিক করলে, আপনি এখানে সমস্ত মেমোরি দেখতে পাবেন।

👉💻 টেস্টিং শেষ হলে, প্রসেসটি বন্ধ করতে আপনার টার্মিনালে "Ctrl + C" চাপুন।

🎉 অভিনন্দন! আপনি এইমাত্র আপনার এজেন্টের সাথে মেমোরি ব্যাংকটি সংযুক্ত করেছেন!

১৪. ☕️ [ঐচ্ছিক] ক্লাউড রানে ডেপ্লয় করুন

১. ডিপ্লয়মেন্ট স্ক্রিপ্টটি চালান

👉💻 ডেপ্লয়মেন্ট স্ক্রিপ্টটি চালান:

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

সফলভাবে ডেপ্লয় হওয়ার পর আপনি ইউআরএলটি পাবেন, এটিই আপনার জন্য ডেপ্লয়েড ইউআরএল!

👉💻 ইউআরএলটি নেওয়ার আগে, নিম্নলিখিত কমান্ডটি চালিয়ে অনুমতি দিন:

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

ডেপ্লয় করা ইউআরএল-এ যান, এবং আপনি সেখানে আপনার অ্যাপ্লিকেশনটি লাইভ দেখতে পাবেন!

২. বিল্ড পাইপলাইন বোঝা

cloudbuild.yaml ফাইলটি নিম্নলিখিত ধারাবাহিক ধাপগুলো সংজ্ঞায়িত করে:

1. ব্যাকএন্ড বিল্ড : backend/Dockerfile থেকে ডকার ইমেজ তৈরি করে।
2. ব্যাকএন্ড ডিপ্লয় : ব্যাকএন্ড কন্টেইনারটিকে ক্লাউড রান-এ ডিপ্লয় করে।
3. ক্যাপচার ইউআরএল : নতুন ব্যাকএন্ড ইউআরএলটি সংগ্রহ করে।
4. ফ্রন্টএন্ড বিল্ড :
   • নির্ভরতাগুলো ইনস্টল করে।
   • VITE_API_URL= ইনজেক্ট করে React অ্যাপটি তৈরি করে। VITE_API_URL= .
5. ফ্রন্টএন্ড ইমেজ : frontend/Dockerfile থেকে ডকার ইমেজ তৈরি করে (স্ট্যাটিক অ্যাসেটগুলো প্যাকেজ করে)।
6. ফ্রন্টএন্ড ডিপ্লয় : ফ্রন্টএন্ড কন্টেইনারটি ডিপ্লয় করে।

৩. ডেপ্লয়মেন্ট যাচাই করুন

বিল্ড সম্পন্ন হলে (স্ক্রিপ্ট দ্বারা প্রদত্ত লগ লিঙ্কটি দেখুন), আপনি যাচাই করতে পারেন:

1. ক্লাউড রান কনসোলে যান।
2. survivor-frontend সার্ভিসটি খুঁজুন।
3. অ্যাপ্লিকেশনটি খুলতে ইউআরএল-টিতে ক্লিক করুন।
4. ফ্রন্টএন্ড যাতে ব্যাকএন্ডের সাথে যোগাযোগ করতে পারে, তা নিশ্চিত করার জন্য একটি সার্চ কোয়েরি চালান।

(ঐচ্ছিক) ৪. ম্যানুয়াল ডেপ্লয়মেন্ট

যদি আপনি কমান্ডগুলো ম্যানুয়ালি চালাতে চান বা প্রক্রিয়াটি আরও ভালোভাবে বুঝতে চান, তাহলে সরাসরি cloudbuild.yaml ব্যবহার করার পদ্ধতিটি এখানে দেওয়া হলো।

cloudbuild.yaml লেখা হচ্ছে

cloudbuild.yaml ফাইলটি গুগল ক্লাউড বিল্ডকে বলে দেয় কোন কোন পদক্ষেপ সম্পাদন করতে হবে।

• ধাপসমূহ : ধারাবাহিক কাজের একটি তালিকা। প্রতিটি ধাপ একটি কন্টেইনারে (যেমন, docker , gcloud , node , bash ) চলে।
• প্রতিস্থাপন : ভেরিয়েবল যা বিল্ড টাইমে পাস করা যেতে পারে (যেমন, $_REGION )।
• ওয়ার্কস্পেস : একটি শেয়ার করা ডিরেক্টরি যেখানে স্টেপগুলো ফাইল শেয়ার করতে পারে (যেমন আমরা backend_url.txt শেয়ার করি)।

ডিপ্লয়মেন্ট চালানো হচ্ছে

স্ক্রিপ্ট ছাড়া ম্যানুয়ালি ডেপ্লয় করতে, gcloud builds submit কমান্ডটি ব্যবহার করুন। আপনাকে অবশ্যই প্রয়োজনীয় সাবস্টিটিউশন ভ্যারিয়েবলগুলো পাস করতে হবে।

# 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"

১৫. উপসংহার

১. আপনি যা তৈরি করেছেন

✅ গ্রাফ ডেটাবেস : নোড (সারভাইভার, দক্ষতা) এবং এজ (সম্পর্ক) সহ স্প্যানার
✅ এআই সার্চ : এমবেডিং সহ কীওয়ার্ড, সিমান্টিক এবং হাইব্রিড সার্চ
✅ মাল্টিমোডাল পাইপলাইন : জেমিনি ব্যবহার করে ছবি/ভিডিও থেকে এনটিটি শনাক্ত করুন
✅ মাল্টি-এজেন্ট সিস্টেম : ADK-এর সাথে সমন্বিত কর্মপ্রবাহ
✅ মেমোরি ব্যাংক : ভার্টেক্স এআই-এর সাহায্যে দীর্ঘমেয়াদী ব্যক্তিগতকরণ
✅ প্রোডাকশন ডেপ্লয়মেন্ট : ক্লাউড রান + এজেন্ট ইঞ্জিন

২. স্থাপত্যের সারাংশ

৩. মূল শিক্ষাসমূহ

1. গ্রাফ র‍্যাগ (Graph RAG) : বুদ্ধিদীপ্ত অনুসন্ধানের জন্য গ্রাফ ডেটাবেস কাঠামোর সাথে সিমান্টিক এমবেডিংয়ের সমন্বয় ঘটায়।
2. মাল্টি-এজেন্ট প্যাটার্ন : জটিল, বহু-ধাপের কর্মপ্রবাহের জন্য অনুক্রমিক পাইপলাইন
3. মাল্টিমোডাল এআই : অসংগঠিত মিডিয়া (ছবি/ভিডিও) থেকে সংগঠিত ডেটা নিষ্কাশন করা
4. স্টেটফুল এজেন্ট : মেমরি ব্যাংক বিভিন্ন সেশন জুড়ে ব্যক্তিগতকরণের সুযোগ দেয়

৪. কর্মশালার বিষয়বস্তু

• স্তর ০ : নিজেকে শনাক্ত করুন
• স্তর ১ : সুনির্দিষ্ট অবস্থান
• লেভেল ২ এইটি : গ্রাফ র‍্যাগ, এডিকে এবং মেমরি ব্যাংক ব্যবহার করে একটি মাল্টিমোডাল এআই এজেন্ট তৈরি করুন
• স্তর ৩ : একটি ADK দ্বি-মুখী স্ট্রিমিং এজেন্ট তৈরি করা
• লেভেল ৪ : লাইভ দ্বিমুখী মাল্টি-এজেন্ট সিস্টেম
• লেভেল ৫ : গুগল এডিকে, এ২এ, এবং কাফকা সহ ইভেন্ট-চালিত আর্কিটেকচার

৫. সম্পদ

• ADK ডকুমেন্টেশন
• স্প্যানার গ্রাফ
• মেমরি ব্যাংক গাইড
• গিটহাব রিপোজিটরি

অভিনন্দন! আপনি গ্রাফ ডেটাবেস, র‍্যাগ সার্চ, মাল্টিমোডাল প্রসেসিং এবং লং-টার্ম মেমরি ব্যবহার করে একটি প্রোডাকশন-গ্রেড এআই এজেন্ট সিস্টেম তৈরি করেছেন। এই প্যাটার্নগুলো লজিস্টিকস থেকে শুরু করে স্বাস্থ্যসেবা ও গ্রাহক পরিষেবা পর্যন্ত, বুদ্ধিমান ডেটা সমন্বয়ের প্রয়োজন এমন যেকোনো ক্ষেত্রে প্রযোজ্য।