تفاصيل مشروع MemoRizz

نظرة عامة على المشروع

MemoRizz هي مكتبة بايثون لإدارة الذاكرة مصممة خصيصًا لتطبيقات الذكاء الاصطناعي، وتوفر لوكلاء الذكاء الاصطناعي القدرة على تخزين المعلومات بشكل دائم، وواعي بالسياق، وقابل للبحث الدلالي. يمنح هذا المشروع الوكلاء وظائف معرفية معقدة، بما في ذلك تتبع سجل المحادثات، وإدارة استخدام الأدوات، والحفاظ على دور متسق، من خلال التكامل السلس لـ MongoDB مع تقنيات تضمين المتجهات.

⚠️ تحذير هام: MemoRizz هي مكتبة تجريبية مخصصة للأغراض التعليمية فقط. لا يُنصح باستخدامها في بيئات الإنتاج أو مع البيانات الحساسة.

الميزات الأساسية

🧠 ذاكرة دائمة

• تمكن وكلاء الذكاء الاصطناعي من الاحتفاظ بالذاكرة بين الجلسات.
• تدعم تخزين واسترجاع المعلومات طويلة الأمد.
• إدارة الذاكرة الواعية بالسياق.

🔍 البحث الدلالي

• استخدام اللغة الطبيعية للعثور على المعلومات ذات الصلة.
• البحث عن التشابه بناءً على تضمينات المتجهات.
• تكامل البحث المتجه في MongoDB Atlas.

🛠️ تكامل الأدوات

• الاكتشاف التلقائي وتنفيذ الدوال.
• تحويل دوال بايثون إلى أدوات قابلة للاستدعاء بواسطة نماذج اللغة الكبيرة (LLM).
• الفهرسة الدلالية للأدوات واكتشافها باللغة الطبيعية.

👤 نظام الأدوار

• إنشاء أدوار وكلاء ذكاء اصطناعي متخصصة ومتسقة.
• تخصيص سلوك الوكيل وأسلوب الاستجابة.
• تحديد خلفية الدور وأهدافه.

📊 البحث المتجه

• استرجاع فعال باستخدام البحث المتجه في MongoDB Atlas.
• التضمين والفهرسة التلقائية للمعلومات المخزنة.
• دعم تصنيف أنواع الذاكرة المتعددة.

بنية النظام

┌─────────────────┐
│ MemAgent        │ ← واجهة الوكيل الذكي المتقدمة
├─────────────────┤
│ Persona         │ ← شخصية الوكيل وسلوكه
├─────────────────┤
│ Toolbox         │ ← تسجيل الدوال واكتشافها
├─────────────────┤
│ Memory Provider │ ← طبقة تجريد التخزين
├─────────────────┤
│ Vector Search   │ ← التشابه الدلالي والاسترجاع
├─────────────────┤
│ MongoDB         │ ← الواجهة الخلفية للتخزين الدائم
└─────────────────┘

متطلبات التثبيت

• بايثون 3.7+
• حساب MongoDB Atlas (أو MongoDB محلي مع البحث المتجه)
• مفتاح API الخاص بـ OpenAI (لوظائف التضمين ونماذج اللغة الكبيرة)

طريقة التثبيت

pip install memorizz

أمثلة الاستخدام الأساسية

1. إعداد الوكيل الأساسي

import os
from memorizz.memory_provider.mongodb.provider import MongoDBConfig, MongoDBProvider
from memorizz.memagent import MemAgent
from memorizz.llms.openai import OpenAI

# إعداد مفتاح API
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# تهيئة مزود ذاكرة MongoDB
mongodb_config = MongoDBConfig(uri="your-mongodb-atlas-uri")
memory_provider = MongoDBProvider(mongodb_config)

# إنشاء MemAgent
agent = MemAgent(
    model=OpenAI(model="gpt-4"),
    instruction="You are a helpful assistant with persistent memory.",
    memory_provider=memory_provider
)

# بدء المحادثة - سيحتفظ الوكيل بالذاكرة بين الجلسات
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# لاحقًا في جلسة أخرى...
response = agent.run("What did I tell you about myself?")
print(response)  # الوكيل يتذكر أن جون مهندس برمجيات

2. استخدام نظام الأدوار

from memorizz.persona import Persona

# إنشاء دور خبير تقني
tech_expert = Persona(
    name="TechExpert",
    role="Senior Software Engineer",
    goals="Help developers solve complex technical problems with detailed explanations.",
    background="10+ years experience in Python, AI/ML, and distributed systems."
)

# تطبيق الدور على الوكيل
agent.set_persona(tech_expert)
agent.save()

# الآن سيستجيب الوكيل بصفته خبيرًا تقنيًا
response = agent.run("How should I design a scalable microservices architecture?")

3. تكامل الأدوات

from memorizz.database.mongodb import MongoDBTools, MongoDBToolsConfig

# تهيئة قاعدة بيانات الأدوات
tools_config = MongoDBToolsConfig(
    uri="your-mongodb-atlas-uri",
    database_name="my_tools_db"
)

# تسجيل الأدوات باستخدام المزخرف (Decorator)
with MongoDBTools(tools_config) as tools:
    toolbox = tools.mongodb_toolbox()
    
    @toolbox
    def calculate_compound_interest(principal: float, rate: float, time: int) -> float:
        """Calculate compound interest for financial planning."""
        return principal * (1 + rate) ** time
    
    @toolbox
    def get_weather(city: str) -> str:
        """Get current weather for a city."""
        # كود تكامل API الطقس الخاص بك
        return f"Weather in {city}: 72°F, sunny"

# إضافة الأدوات إلى الوكيل
agent.add_tool(toolbox=tools)

# يمكن للوكيل الآن اكتشاف هذه الأدوات واستخدامها تلقائيًا
response = agent.run("What's the weather in San Francisco and calculate interest on $1000 at 5% for 3 years?")

أنواع الذاكرة

يدعم MemoRizz فئات ذاكرة مختلفة لتنظيم المعلومات:

• Conversation: سجل الدردشة وسياق المحادثة
• Task: معلومات موجهة نحو الهدف وتتبع التقدم
• Workflow: معلومات عملية متعددة الخطوات
• General: المعرفة الواقعية والمعلومات التصريحية
• Working: مساحة معالجة مؤقتة (سياق LLM)

الميزات المتقدمة

تخزين الذاكرة واسترجاعها

# تخزين المعلومات مع التضمين التلقائي
agent.store_memory("I prefer Python for backend development", memory_type="general")

# لاحقًا، ستسترجع الاستعلامات ذات الصلة الدلالية هذه المعلومات
response = agent.run("What programming languages do I like?")
# سيجد الوكيل التفضيل المخزن ويستخدمه

التحكم في الذاكرة باستخدام البيانات الوصفية

# تخزين المعلومات مع البيانات الوصفية
agent.store_memory(
    content="Completed project X with React and Node.js",
    memory_type="task",
    metadata={"project": "X", "technologies": ["React", "Node.js"]}
)

# استرجاع ذاكرة محددة
memories = agent.retrieve_memories(
    query="projects with React",
    memory_type="task",
    limit=5
)

إعدادات البيئة

# مطلوب
export OPENAI_API_KEY="your-openai-api-key"
export MONGODB_URI="your-mongodb-atlas-uri"

# اختياري
export MONGODB_DB_NAME="memorizz"  # اسم قاعدة البيانات الافتراضي

خطوات الإعداد

1. إنشاء مجموعة MongoDB Atlas.
2. تمكين البحث المتجه على المجموعة.
3. إنشاء قاعدة بيانات ومجموعات لوكيلك.
4. الحصول على سلسلة الاتصال.

الأسئلة الشائعة

• اتصال MongoDB: تأكد من أن عنوان IP الخاص بك مدرج في القائمة البيضاء في Atlas.
• البحث المتجه: تحقق من تمكين البحث المتجه على المجموعة.
• مفتاح API: تحقق من أن مفتاح API الخاص بـ OpenAI صالح وبه رصيد.

مشاريع أمثلة

راجع الأمثلة العملية الكاملة في دليل examples/:

• وكيل أساسي: وكيل محادثة بسيط مع ذاكرة.
• وكيل متخصص: خبير تقني ذو دور.
• تكامل الأدوات: وكيل مع استدعاء دوال مخصصة.
• إدارة الذاكرة: تخزين واسترجاع الذاكرة المتقدم.

القيمة التعليمية التقنية

توضح هذه المكتبة المفاهيم الأساسية التالية:

• بنية وكيل الذكاء الاصطناعي: الذاكرة، الاستدلال، واستخدام الأدوات.
• قواعد بيانات المتجهات: البحث الدلالي والاسترجاع.
• تكامل نماذج اللغة الكبيرة (LLM): استدعاء الدوال وإدارة السياق.
• تصميم البرمجيات: تجريدات واضحة وبنية قابلة للتوسع.