pip install git+https://github.com/munshi007/Aura-State.git

from aura_state import AuraEngine, Node, CompiledTransition
from pydantic import BaseModel, Field
from openai import OpenAI

# تعريف ما تريد استخراجه
class LeadData(BaseModel):
    name: str = Field(description="الاسم الكامل")
    budget: int = Field(description="الميزانية بالدولار الأمريكي")
    timeline: str = Field(description="الجدول الزمني للشراء")

# تعريف عقدة تستخرجه
class ExtractLead(Node):
    system_prompt = "استخرج معلومات العميل المحتمل من نص مكالمة مبيعات."
    extracts = LeadData

    def handle(self, user_text, extracted_data=None, memory=None):
        return "QualifyBudget", extracted_data.model_dump()

# تعريف عقدة تقوم بحساب رياضي قطعي (بدون LLM)
class QualifyBudget(Node):
    system_prompt = "سجل العميل المحتمل."
    sandbox_rule = "result = budget > 100000"  # يُنفذ في صندوق رمل AST، وليس LLM

    def handle(self, user_text, extracted_data=None, memory=None):
        return "END", memory

# ربطها
engine = AuraEngine(llm_client=OpenAI())
engine.register(ExtractLead, QualifyBudget)
engine.connect([
    CompiledTransition(from_node=ExtractLead, to_node=QualifyBudget),
])

# تشغيل
next_state, data = engine.process("ExtractLead", user_text="مرحبًا، أنا سارة. الميزانية 450 ألف دولار.")

1. الفحص الصحي للرسم البياني التكيفي     →  هل يجب تخطي هذه العقدة أو إعادة محاولتها؟
2. البحث في ذاكرة التخزين المؤقت GraphRAG →  هل رأينا هذا الإدخال نفسه من قبل؟ تخطى LLM.
3. حقن الأمثلة القليلة                   →  اعثر على نجاحات سابقة مشابهة، واحقنها كأمثلة.
4. استخراج LLM + التحقق                 →  استخرج البيانات، وتحقق باستخدام Z3، وأعد المحاولة إذا كان خطأ.
5. طريقة handle() الخاصة بعقدتك        →  منطق عملك يُنفذ هنا.
6. توجيه MCTS (UCB1)                 →  سجل الفروع باستخدام UCB1 + مقاييس الرسم البياني التكيفي.
7. تسلسل الحالة                         →  احفظ الحالة لتصحيح الأخطاء عبر الزمن.
8. التنفيذ التخميني                     →  احسب مسبقًا العقد التالية المحتملة بالتوازي.

from aura_state import verify_engine, reachability, mutual_exclusion, eventual_completion

results = verify_engine(engine, [
    {"description": "QualifyBudget يمكن الوصول إليها", "formula": reachability("QualifyBudget")},
    {"description": "جميع المسارات تنتهي", "formula": eventual_completion("QualifyBudget")},
])
# النتيجة: PROVEN أو VIOLATED، مع الحالات الدقيقة التي تحقق/تخالف

from aura_state import prove_extraction

result = prove_extraction(
    {"budget": 450000, "cost_per_sqft": 3, "total": 1350000},
    obligations=["budget > 0", "total == budget * cost_per_sqft"],
)
# result.verified = True
# إذا كانت False، يعطيك Z3 مثالًا مضادًا يظهر بالضبط ما الذي أخطأ

from aura_state import conformal_interval

budgets = [450000, 452000, 448000, 450000, 451000]
ci = conformal_interval(budgets, confidence=0.95)
# ci.lower = 447800, ci.upper = 452200

الحقل                      الدقة
──────────────            ──────────
name                       100%
budget                     100%
bedrooms                   100%
pre_approved                90%
timeline                    90%
city                        80%

الخصائص الزمنية:                  3/3 مثبتة
التزامات إثبات Z3:              20/20 ناجحة
دقة التوجيه:                      90%
متوسط زمن الاستجابة:              1.4 ثانية

# جرب بنفسك — لا حاجة لمفتاح API
python examples/benchmark/run_benchmark.py

# مع استدعاءات LLM حقيقية (يحتاج OPENAI_API_KEY في .env)
python examples/benchmark/run_live.py --model gpt-4o-mini --runs 3

aura_state/
├── core/
│   ├── engine.py              # المحرك الرئيسي — process() + توجيه MCTS/UCB1
│   ├── adaptive_graph.py      # مراقبة صحة العقدة
│   ├── verification_loop.py   # حلقة استخراج → تحقق → إعادة محاولة
│   └── providers.py           # توجيه متعدد النماذج + تتبع التكاليف
├── compiler/
│   ├── schema_compiler.py     # JSON Schema ← فئات العقد
│   └── dspy_tuner.py          # اختيار نماذج قليلة باستخدام KNN
├── verification/
│   ├── temporal_verifier.py   # فحص نموذج Kripke + CTL
│   ├── conformal.py           # فترات التنبؤ المطابق
│   └── proof_engine.py        # براهين Z3
├── execution/
│   ├── tracer.py              # تسلسل الحالة (تصحيح أخطاء عبر الزمن)
│   └── sandbox.py             # تنفيذ رياضي آمن (التحقق من AST)
├── memory/
│   ├── trajectory_cache.py    # ذاكرة تخزين مؤقت لإيزومورفيزم الرسم البياني الفرعي
│   └── pruner.py              # تحسين نافذة السياق
└── consensus/
    └── auto_vote.py           # استخراج متعدد الجولات مع التصويت

pip install git+https://github.com/munshi007/Aura-State.git

python -m pytest tests/ -v
# 65 اختبارًا ناجحًا