Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages

docs/tech-specs/ar/structured-data.ar.md

@@ -0,0 +1,260 @@
+---
+layout: default
+title: "المواصفات الفنية للبيانات المهيكلة"
+parent: "Arabic (Beta)"
+---
+
+# المواصفات الفنية للبيانات المهيكلة
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## نظرة عامة
+
+تصف هذه المواصفات دمج TrustGraph مع تدفقات البيانات المهيكلة، مما يمكّن النظام من العمل مع البيانات التي يمكن تمثيلها كصفوف في الجداول أو كائنات في مخازن الكائنات. يدعم هذا التكامل أربع حالات استخدام رئيسية:
+
+1. **الاستخراج من غير المهيكل إلى المهيكل**: قراءة مصادر البيانات غير المهيكلة، وتحديد واستخراج هياكل الكائنات، وتخزينها بتنسيق جدولي.
+2. **استيعاب البيانات المهيكلة**: تحميل البيانات الموجودة بالفعل بتنسيقات مهيكلة مباشرة إلى المتجر المهيكل جنبًا إلى جنب مع البيانات المستخرجة.
+3. **الاستعلام باللغة الطبيعية**: تحويل الأسئلة باللغة الطبيعية إلى استعلامات مهيكلة لاستخراج البيانات المطابقة من المتجر.
+4. **الاستعلام المهيكل المباشر**: تنفيذ استعلامات مهيكلة مباشرة مقابل مخزن البيانات لاسترجاع البيانات بدقة.
+
+## الأهداف
+
+**واجهة وصول موحدة للبيانات**: توفير واجهة واحدة للوصول إلى كل من البيانات المهيكلة وغير المهيكلة داخل TrustGraph.
+**تكامل سلس**: تمكين التوافق السلس بين تمثيل المعرفة القائم على الرسم البياني في TrustGraph وتنسيقات البيانات المهيكلة التقليدية.
+**استخراج مرن**: دعم الاستخراج التلقائي للبيانات المهيكلة من مصادر غير مهيكلة متنوعة (المستندات، والنصوص، وما إلى ذلك).
+**تنوع الاستعلام**: السماح للمستخدمين بالاستعلام عن البيانات باستخدام كل من اللغة الطبيعية ولغات الاستعلام المهيكلة.
+**اتساق البيانات**: الحفاظ على سلامة البيانات واتساقها عبر تمثيلات البيانات المختلفة.
+**تحسين الأداء**: ضمان تخزين واسترجاع فعال للبيانات المهيكلة على نطاق واسع.
+**مرونة المخطط**: دعم كل من مناهج "المخطط عند الكتابة" و "المخطط عند القراءة" لاستيعاب مصادر البيانات المتنوعة.
+**التوافق مع الإصدارات السابقة**: الحفاظ على وظائف TrustGraph الحالية مع إضافة إمكانات البيانات المهيكلة.
+
+## الخلفية
+
+تتفوق TrustGraph حاليًا في معالجة البيانات غير المهيكلة وإنشاء الرسوم البيانية المعرفية من مصادر متنوعة. ومع ذلك، تتضمن العديد من حالات الاستخدام في المؤسسات بيانات مهيكلة بشكل متأصل - سجلات العملاء، وسجلات المعاملات، وقواعد بيانات المخزون، ومجموعات بيانات جدولية أخرى. غالبًا ما تحتاج هذه مجموعات البيانات المهيكلة إلى تحليلها جنبًا إلى جنب مع المحتوى غير المهيكل لتقديم رؤى شاملة.
+
+القيود الحالية تشمل:
+لا يوجد دعم أصلي لاستيعاب تنسيقات البيانات المهيكلة مسبقًا (CSV، ومصفوفات JSON، وتصديرات قواعد البيانات).
+عدم القدرة على الحفاظ على الهيكل المتأصل عند استخراج البيانات الجدولية من المستندات.
+عدم وجود آليات استعلام فعالة لأنماط البيانات المهيكلة.
+عدم وجود جسر بين استعلامات تشبه SQL واستعلامات الرسم البياني في TrustGraph.
+
+تعالج هذه المواصفات هذه الفجوات من خلال تقديم طبقة بيانات مهيكلة تكمل إمكانات TrustGraph الحالية. من خلال دعم البيانات المهيكلة أصلاً، يمكن لـ TrustGraph:
+أن تكون منصة موحدة لتحليل كل من البيانات المهيكلة وغير المهيكلة.
+تمكين الاستعلامات الهجينة التي تمتد عبر علاقات الرسم البياني والبيانات الجدولية.
+توفير واجهات مألوفة للمستخدمين الذين اعتادوا العمل مع البيانات المهيكلة.
+إطلاق حالات استخدام جديدة في تكامل البيانات وذكاء الأعمال.
+
+## التصميم الفني
+
+### البنية
+
+يتطلب تكامل البيانات المهيكلة المكونات الفنية التالية:
+
+1. **خدمة NLP-to-Structured-Query**
+   تحويل الأسئلة باللغة الطبيعية إلى استعلامات مهيكلة.
+   يدعم أهداف لغة استعلام متعددة (في البداية بناء الجملة المشابه لـ SQL).
+   يتكامل مع إمكانات NLP الحالية في TrustGraph.
+   
+   الوحدة: trustgraph-flow/trustgraph/query/nlp_query/cassandra
+
+2. **دعم مخطط التكوين** ✅ **[مكتمل]**
+   نظام تكوين موسع لتخزين مخططات البيانات المهيكلة.
+   دعم لتعريف هياكل الجداول وأنواع الحقول والعلاقات.
+   إمكانيات إصدار وترحيل المخططات.
+
+3. **وحدة استخراج الكائنات** ✅ **[مكتمل]**
+   تكامل محسن لتدفق استخراج المعرفة.
+   تحديد واستخراج كائنات مهيكلة من مصادر غير مهيكلة.
+   الحفاظ على الأصل ودرجات الثقة.
+   يسجل معالج تكوين (مثال: trustgraph-flow/trustgraph/prompt/template/service.py) لتلقي بيانات التكوين وفك تشفير معلومات المخطط.
+   يتلقى الكائنات ويفك تشفيرها إلى كائنات ExtractedObject للتسليم على قائمة الانتظار Pulsar.
+   ملاحظة: يوجد رمز موجود في `trustgraph-flow/trustgraph/extract/object/row/`. كان هذا محاولة سابقة وسيتطلب إعادة هيكلة كبيرة لأنه لا يتوافق مع واجهات برمجة التطبيقات الحالية. استخدمه إذا كان مفيدًا، وابدأ من البداية إذا لم يكن كذلك.
+   يتطلب واجهة سطر أوامر: `kg-extract-objects`
+
+   الوحدة: trustgraph-flow/trustgraph/extract/kg/objects/
+
+4. **وحدة كاتب المتجر المهيكل** ✅ **[مكتمل]**
+   يتلقى الكائنات بتنسيق ExtractedObject من قوائم انتظار Pulsar.
+   التنفيذ الأولي يستهدف Apache Cassandra كمتجر البيانات المهيكل.
+   يتعامل مع إنشاء الجداول الديناميكي بناءً على المخططات التي تمت مواجهتها.
+   يدير تعيين المخطط إلى جدول Cassandra وتحويل البيانات.
+   يوفر عمليات كتابة مجمعة وتدفق لتحسين الأداء.
+   لا توجد مخرجات Pulsar - هذه خدمة نهائية في تدفق البيانات.
+
+   **معالجة المخططات**:
+   يراقب رسائل ExtractedObject الواردة للإشارة إلى المخططات.
+   عندما يتم مواجهة مخطط جديد لأول مرة، يقوم تلقائيًا بإنشاء جدول Cassandra المقابل.
+   يحتفظ بخزنة للمخططات المعروفة لتجنب محاولات إنشاء جداول متكررة.
+   يجب أن تأخذ في الاعتبار ما إذا كان سيتم تلقي تعريفات المخططات مباشرة أو الاعتماد على أسماء المخططات في رسائل ExtractedObject.
+
+   **ربط جدول Cassandra**:
+   يتم تسمية مساحة المفاتيح (Keyspace) بناءً على الحقل `user` من بيانات التعريف (Metadata) الخاصة بـ ExtractedObject.
+   يتم تسمية الجدول بناءً على الحقل `schema_name` الخاص بـ ExtractedObject.
+   تصبح المجموعة (Collection) من بيانات التعريف جزءًا من مفتاح التقسيم (partition key) لضمان:
+     توزيع البيانات بشكل طبيعي عبر عقد Cassandra.
+     استعلامات فعالة داخل مجموعة معينة.
+     عزل منطقي بين عمليات استيراد البيانات/المصادر المختلفة.
+   هيكل المفتاح الأساسي: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`.
+     تكون المجموعة دائمًا المكون الأول من مفتاح التقسيم.
+     تتبع حقول المفتاح الأساسي المعرفة في المخطط (schema) كجزء من مفتاح التقسيم المركب.
+     يتطلب هذا تحديد المجموعة في الاستعلامات، مما يضمن أداءً متوقعًا.
+   يتم تعيين تعريفات الحقول إلى أعمدة Cassandra مع تحويلات الأنواع:
+     `string` → `text`.
+     `integer` → `int` أو `bigint` بناءً على تلميح الحجم.
+     `float` → `float` أو `double` بناءً على احتياجات الدقة.
+     `boolean` → `boolean`.
+     `timestamp` → `timestamp`.
+     `enum` → `text` مع التحقق من الصحة على مستوى التطبيق.
+   تقوم الحقول المفهرسة بإنشاء فهارس ثانوية لـ Cassandra (باستثناء الحقول الموجودة بالفعل في المفتاح الأساسي).
+   يتم فرض الحقول المطلوبة على مستوى التطبيق (لا تدعم Cassandra NOT NULL).
+
+   **تخزين الكائنات (Object Storage)**:
+   يستخرج القيم من خريطة ExtractedObject.values.
+   يقوم بتحويل النوع والتحقق من الصحة قبل الإدراج.
+   يتعامل مع الحقول الاختيارية المفقودة بأمان.
+   يحتفظ ببيانات وصفية حول أصل الكائن (مستند المصدر، درجات الثقة).
+   يدعم عمليات الكتابة المتطابقة (idempotent writes) للتعامل مع سيناريوهات إعادة إرسال الرسائل.
+
+   **ملاحظات التنفيذ**:
+   الكود الحالي الموجود في `trustgraph-flow/trustgraph/storage/objects/cassandra/` قديم ولا يتوافق مع واجهات برمجة التطبيقات (APIs) الحالية.
+   يجب الرجوع إلى `trustgraph-flow/trustgraph/storage/triples/cassandra` كمثال على معالج تخزين يعمل.
+   يجب تقييم الكود الحالي بحثًا عن أي مكونات قابلة لإعادة الاستخدام قبل اتخاذ قرار بإعادة هيكلة أو إعادة كتابة.
+
+   الوحدة: trustgraph-flow/trustgraph/storage/objects/cassandra
+
+5. **خدمة الاستعلامات المهيكلة** ✅ **[مكتمل]**
+   تقبل استعلامات مهيكلة بتنسيقات محددة.
+   تنفذ الاستعلامات على المستودع المهيكل.
+   تُرجع الكائنات التي تتطابق مع معايير الاستعلام.
+   تدعم التقسيم والترشيح للنتائج.
+
+   الوحدة: trustgraph-flow/trustgraph/query/objects/cassandra
+
+6. **تكامل أدوات الوكيل (Agent Tool Integration)**
+   فئة أداة جديدة لأطر عمل الوكيل.
+   تمكن الوكلاء من الاستعلام عن مستودعات البيانات المهيكلة.
+   توفر واجهات استعلام باللغة الطبيعية والمهيكلة.
+   تتكامل مع عمليات اتخاذ القرار الحالية للوكلاء.
+
+7. **خدمة استيعاب البيانات المهيكلة**
+   تقبل بيانات مهيكلة بتنسيقات متعددة (JSON، CSV، XML).
+   تقوم بتحليل والتحقق من صحة البيانات الواردة مقابل المخططات المحددة.
+   تحول البيانات إلى تدفقات كائنات مُنظمة.
+   تُصدر الكائنات إلى قوائم انتظار الرسائل المناسبة للمعالجة.
+   تدعم عمليات التحميل المجمعة والاستيعاب المتدفق.
+
+   الوحدة: trustgraph-flow/trustgraph/decoding/structured
+
+8. **خدمة تضمين الكائنات (Object Embedding Service)**
+   تولد تضمينات متجهة للكائنات المهيكلة.
+   تمكن البحث الدلالي عبر البيانات المهيكلة.
+   تدعم البحث الهجين الذي يجمع بين الاستعلامات المهيكلة والتشابه الدلالي.
+   تتكامل مع مخازن المتجهات الحالية.
+
+   الوحدة: trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant
+
+### نماذج البيانات
+
+#### آلية تخزين المخططات
+
+يتم تخزين المخططات في نظام تكوين TrustGraph باستخدام الهيكل التالي:
+
+**النوع (Type)**: `schema` (قيمة ثابتة لجميع مخططات البيانات المهيكلة).
+**المفتاح (Key)**: الاسم/المعرف الفريد للمخطط (مثل `customer_records`، `transaction_log`).
+**القيمة (Value)**: تعريف مخطط JSON يحتوي على الهيكل.
+
+مثال على إدخال التكوين:
+```
+Type: schema
+Key: customer_records
+Value: {
+  "name": "customer_records",
+  "description": "Customer information table",
+  "fields": [
+    {
+      "name": "customer_id",
+      "type": "string",
+      "primary_key": true
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": true
+    },
+    {
+      "name": "email",
+      "type": "string",
+      "required": true
+    },
+    {
+      "name": "registration_date",
+      "type": "timestamp"
+    },
+    {
+      "name": "status",
+      "type": "string",
+      "enum": ["active", "inactive", "suspended"]
+    }
+  ],
+  "indexes": ["email", "registration_date"]
+}
+```
+
+هذا النهج يسمح بما يلي:
+تعريف مخطط ديناميكي دون تغييرات في التعليمات البرمجية
+تحديثات سهلة للمخططات وإصداراتها
+تكامل متسق مع إدارة التكوين الحالية لـ TrustGraph
+دعم مخططات متعددة داخل عملية نشر واحدة
+
+### واجهات برمجة التطبيقات (APIs)
+
+واجهات برمجة تطبيقات جديدة:
+  مخططات Pulsar للأنواع المذكورة أعلاه
+  واجهات Pulsar في التدفقات الجديدة
+  هناك حاجة إلى وسيلة لتحديد أنواع المخططات في التدفقات حتى تعرف التدفقات
+    أنواع المخططات التي يجب تحميلها
+  تمت إضافة واجهات برمجة تطبيقات إلى البوابة والبوابة العكسية
+
+واجهات برمجة تطبيقات معدلة:
+نقاط نهاية استخراج المعرفة - إضافة خيار إخراج كائن منظم
+نقاط نهاية الوكيل - إضافة دعم لأدوات البيانات المنظمة
+
+### تفاصيل التنفيذ
+
+باتباع الاتفاقيات الحالية - هذه مجرد وحدات معالجة جديدة.
+كل شيء موجود في حزم trustgraph-flow باستثناء عناصر المخطط
+الموجودة في trustgraph-base.
+
+هناك حاجة إلى بعض الأعمال لواجهة المستخدم في Workbench لتمكين عرض / تجربة هذه
+الإمكانية.
+
+## اعتبارات الأمان
+
+لا توجد اعتبارات إضافية.
+
+## اعتبارات الأداء
+
+بعض الأسئلة حول استخدام استعلامات وفهارس Cassandra بحيث لا تبطئ الاستعلامات.
+
+## استراتيجية الاختبار
+
+استخدم استراتيجية الاختبار الحالية، سيتم إنشاء اختبارات الوحدة والاتفاقية والتكامل.
+
+## خطة الترحيل
+
+لا يوجد.
+
+## الجدول الزمني
+
+
+لم يتم تحديده.
+
+## أسئلة مفتوحة
+
+هل يمكن جعل هذا يعمل مع أنواع تخزين أخرى؟ نحن نهدف إلى استخدام
+  واجهات تجعل الوحدات التي تعمل مع تخزين واحد قابلة للتطبيق على
+  تخزين آخر.
+
+## المراجع
+
+غير متوفر.