البيئة والتوافق

FactLane تطبيق Python محلي مع خادم MCP يُشغَّل بأمر. وجود مفسّر Python متوافق ضروري لكنه غير كافٍ: إصدار SQLite المرتبط بذلك المفسّر هو ما يحدد ما إذا كان عقد التخزين يستطيع العمل بأمان.

بيئة التشغيل المطلوبة

المكوّن	المتطلب
Python	3.11 أو أحدث.
SQLite المرتبط	3.42.0 أو أحدث.
التبعيات	ملف المشروع uv.lock، مثبّت داخل بيئة يملكها المشروع.
مضيف MCP	عميل stdio محلي قائم على الأوامر.
التضمينات	Ollama محلي متاح عبر loopback مع نموذج مطابق ومثبّت.

الإعداد المعتمد على CPU فقط مدعوم. ولا تُعد GPU أو Docker أو cloud LLM أو remote embedding API أو daemon دائم التشغيل لـFactLane متطلبات مسبقة.

بعد تثبيت المشروع، افحص إصدار SQLite عبر بيئة Python نفسها التي يستخدمها FactLane:

uv sync --frozen
uv run python -c 'import sqlite3; print(sqlite3.sqlite_version)'
uv run factlane --help

يفشل بدء التشغيل باستخدام BACKEND_COMPATIBILITY_MISMATCH عندما يكون إصدار SQLite المرتبط أقل من 3.42.0، وذلك قبل أن ينشئ المحرك قاعدة البيانات أو يفتحها. هذا الحد الأدنى مطلوب لتصفية الصفوف المؤهلة داخل sqlite-vec KNN، ولإمكانات FTS5 secure-delete المستخدمة في استعادة الذاكرة الحساسة. تتحقق عملية الاستعادة من إمكانات FTS5 بصورة مستقلة؛ وأهلية الإصدار لا تتجاوز فحص الميزات.

ملفات تعريف النماذج

يتحقق FactLane من هوية النموذج وبصمته، وأبعاد الإدخال/الإخراج الأصلية، وسعة السياق، وسياسة حجم الإدخال مقابل ملف التعريف المحدد. ولا ينزّل نموذجًا ضمنيًا. ثبّت النموذج في مثيل Ollama المحلي قبل تشغيل الخادم.

ملف التعريف المضمّن	نموذج Ollama	ملاحظات
embeddinggemma-300m-768	embeddinggemma:300m	ملف التعريف المستخدم في الإعداد المحلي المضبوط للمشروع؛ 768 بُعدًا للإخراج.
nomic-768	nomic-embed-text:latest	نموذج Nomic مع 768 بُعدًا للإخراج.
nomic-512	nomic-embed-text:latest	النموذج المصدر نفسه، مع إسقاط إلى 512 بُعدًا.
nomic-256	nomic-embed-text:latest	النموذج المصدر نفسه، مع إسقاط إلى 256 بُعدًا.
minilm-384	all-minilm:l6-v2	مضمّن، لكن حدود السياق المرصودة قد ترفض حقيقة بأقصى طول ضمن سياسة عدم الاقتطاع. تحقّق من الملاءمة قبل الاستخدام.

بالنسبة إلى ملف التعريف الأول:

ollama pull embeddinggemma:300m
uv run factlane --help

يجب أن يتطابق اسم ملف التعريف مع النموذج المحدد وإعداد التخزين. لا ينتج ترتيب عام يصلح للجميع من بيانات اختبار مشروع واحد. قيّم مزيج اللغات لديك، وأحجام الحقائق، والعتاد، وزمن الاستجابة، واحتياجات الجودة. سلوك EXACT وKEYWORD للعربية/المحتوى متعدد اللغات مدعوم من خلال معالجة Unicode نفسها المستخدمة مع النصوص الأخرى، بينما تظل الملاءمة الدلالية مرتبطة بعبء العمل ويجب التحقق منها مقابل corpus المقصود. يقلل الاختيار المتنوع حسب المصدر إحدى آليات ازدحام المستندات، لكنه لا يمثل ضمانًا عامًا للترتيب.

التنفيذ الوحيد المضمّن لمزوّد التضمين يتواصل مع Ollama عبر loopback URL (افتراضيًا http://127.0.0.1:11434). تسمح واجهة المزوّد بتنفيذات مستقبلية، لكن remote endpoint أو automatic cloud fallback أو hosted embedding service ليست إعدادات مدعومة حاليًا.

عزل المضيف والتخزين

استخدم ملف FactLane التنفيذي والتبعيات المثبتة لهذا المشروع بدل استيراد حزم أو بيئة تشغيل خاصة من مضيف MCP. يلزم --host-id ثابت وغير سري. يحدد --db قاعدة بيانات SQLite؛ ويختار --profile أحد ملفات تعريف النماذج المعلنة. --write-profile إعداد موثوق للمشغّل، وليس صلاحية يمكن لطلب أداة أن يمنحها لنفسه. قيمته الافتراضية read-only؛ ويسمح delegated-candidate بمساهمات Candidate فقط.

تُثبَّت نسخة الـbackend الخارجي في pyproject.toml وتُحل التبعيات عبر uv.lock. وهو يوفر قفل اتصال SQLite القابل لإعادة الاستخدام، وإسناد العمل إلى thread، وWAL، ومحاولات إعادة محدودة عند حالتي locked/busy؛ بينما يوفّر FactLane سياسة النطاق ومعاملات revision/CAS. تجنب إدخال تبعية مكررة خاصة بالمضيف أو طبقة قفل ثانية عند إعادة إنتاج التثبيت.

يجب ألا تُضعف بيئة تشغيل الـbackend المحيطة وضع التخزين هذا. يحوّل FactLane خروج إعداد first-import من الـbackend المثبّت إلى BACKEND_COMPATIBILITY_MISMATCH بدل ترك العملية تنتهي خارج الحد المحكوم. لا يجوز لـMCP_MEMORY_SQLITE_PRAGMAS تغيير journal_mode بعيدًا عن WAL، أو خفض synchronous عن NORMAL، أو خفض busy_timeout عن 5000 ms. تُطبَّع الصيغ المؤهلة بالمخطط مثل main.synchronous=OFF إلى أسماء pragma المطلوبة نفسها، بحيث تُرفض التجاوزات العدائية قبل إنشاء قاعدة البيانات؛ كما يتحقق بدء التشغيل من pragmas الفعلية بعد تهيئة الـbackend.

تحمل حزمة مصدر FactLane وwheel أيضًا Skill المحمول using-factlane. تثبيت الحزمة لا يضبط مضيفًا بعينه ولا يسجّل ذلك Skill تلقائيًا.

الانتقال بين الإصدارات

نجاح تثبيت حزمة Python لا يثبت بحد ذاته أن قاعدة بيانات أنشأها أو عدّلها إصدار آخر من FactLane متوافقة. تعامل مع توافق الحزمة/بيئة التشغيل وتوافق البيانات/المخطط على أنهما عقدا إصدار منفصلان. احتفظ بالبيئة الحالية وبنسخة احتياطية متحقق منها يملكها المشغّل قبل أي انتقال إصدار قد يؤثر في البيانات الدائمة، ولا تشغّل binary أقدم مقابل قاعدة بيانات ربما خضعت لترحيل ما لم يوثق الإصدار المستهدف صراحة أن الرجوع آمن.

v0.1.3 هو أول إصدار إنتاج رسمي، لذلك لا يوجد له هدف تراجع إنتاجي رسمي أقدم. يمكن تثبيت حزمته المنشورة وإعادة التحقق منها بصورة مستقلة، لكن ذلك لا يعني وجود ضمان لترحيل بيانات الإنتاج بين الإصدارات أو للرجوع إلى إصدار أقدم. راجع عمليات الإصدار للحصول على هويات artifacts الدقيقة لـv0.1.3 وإجراء التثبيت/الترقية/التراجع القابل لإعادة الاستخدام للإصدارات اللاحقة.

حدود البيانات والنشر

حقيقة FactLane محدودة إلى 2,000 UTF-8 bytes. هذه الواجهة ليست crawler لمجلدات كبيرة، ولا مستودعًا للمحادثات، ولا فهرس مستندات بالجملة. تحتاج مجموعات المصادر الكبيرة جدًا إلى مرحلة ingestion/extraction منفصلة، وقد تكون لها متطلبات مختلفة في throughput والمزوّد؛ ولا توجد هنا أي مطالبة بمعدل ingestion على مستوى terabyte.

FactLane 0.1.3 مؤهّل للإنتاج ضمن ملف التعريف المحلي الموثق: Python 3.11+، وSQLite 3.42.0+ المرتبط، وMCP عبر stdio يُشغَّل بأمر، وتضمينات Ollama محلية مدعومة، وعقد التخزين/الاستعادة المحلي الموثق على POSIX. يشمل التأهيل توافق النسخ الاحتياطي/الاستعادة، والتشغيل المتزامن المحدود، والتراجع بعد crash/restart، وبدء تشغيل المضيف المضبوط، والاسترجاع المستمد من الإنتاج، وسلوك سعة SQLite الذي يفشل في وضع مغلق.

هذا بيان دعم محدود وليس ادعاء نشر عام. تحقّق من عبء العمل الخاص بك للغة/الترتيب ومن النطاق التشغيلي، وأبقِ بيانات الإنتاج والاحتفاظ بالنسخ الاحتياطية والمراقبة وعمليات الاستعادة تحت صلاحياتها وإجراءات التشغيل الخاصة بها. راجع الأمان، والبنية، والبدء السريع. توجد إجراءات التثبيت والانتقال المرتبطة بالإصدارات في عمليات الإصدار.