Merge pull request #3 from rockenman1234/docs

Docs

docs/README.api-docs.ar.md

@@ -0,0 +1,53 @@
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، وعلامات HTML.
+- لا تقم بترجمة الكود الموجود داخل علامات backticks أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+
+# إنشاء الوثائق تلقائيًا
+
+## وثائق واجهة برمجة تطبيقات REST و WebSocket
+
+- `specs/build-docs.sh` - يقوم بإنشاء وثائق REST و WebSocket من مواصفات OpenAPI و AsyncAPI.
+
+## وثائق واجهة برمجة تطبيقات Python
+
+يتم إنشاء وثائق واجهة برمجة تطبيقات Python من سلاسل التوثيق باستخدام نص برمجي Python مخصص يقوم بتحليل حزمة `trustgraph.api`.
+
+### المتطلبات الأساسية
+
+يجب أن تكون حزمة trustgraph قابلة للاستيراد. إذا كنت تعمل في بيئة تطوير:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### إنشاء الوثائق
+
+من دليل الوثائق:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+يولد هذا ملف Markdown واحد يحتوي على وثائق واجهة برمجة تطبيقات كاملة، ويظهر:
+- دليل التثبيت والإرشادات السريعة
+- عبارات الاستيراد لكل فئة/نوع
+- سلاسل التوثيق الكاملة مع أمثلة
+- جدول محتويات مُنظمة حسب الفئة
+
+### أسلوب الوثائق
+
+تتبع جميع سلاسل التوثيق تنسيق Google:
+- ملخص موجز في سطر واحد
+- وصف تفصيلي
+- قسم Args مع أوصاف المعلمات
+- قسم Returns
+- قسم Raises (عندما يكون ذلك مناسبًا)
+- كتل كود مع تمييز نحوي مناسب
+
+تعرض الوثائق التي تم إنشاؤها واجهة برمجة التطبيقات العامة تمامًا كما يستوردها المستخدمون من `trustgraph.api`، دون الكشف عن هيكل الوحدة الداخلية.

docs/README.api-docs.es.md

@@ -0,0 +1,45 @@
+# Generación automática de documentación
+
+## Documentación de la API REST y WebSocket
+
+- `specs/build-docs.sh` - Genera la documentación de la API REST y WebSocket a partir de las especificaciones OpenAPI y AsyncAPI.
+
+## Documentación de la API Python
+
+La documentación de la API Python se genera a partir de los docstrings utilizando un script de Python personalizado que introspecciona el paquete `trustgraph.api`.
+
+### Requisitos previos
+
+El paquete `trustgraph` debe ser importable. Si estás trabajando en un entorno de desarrollo:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Generación de documentación
+
+Desde el directorio `docs`:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Esto genera un único archivo Markdown con documentación de la API completa, mostrando:
+- Guía de instalación y inicio rápido
+- Declaraciones de importación para cada clase/tipo
+- Docstrings completos con ejemplos
+- Tabla de contenidos organizada por categoría
+
+### Estilo de documentación
+
+Todos los docstrings siguen el formato de Google:
+- Resumen breve de una línea
+- Descripción detallada
+- Sección Args con descripciones de parámetros
+- Sección Returns
+- Sección Raises (cuando corresponda)
+- Bloques de código de ejemplo con resaltado de sintaxis adecuado
+
+La documentación generada muestra la API pública exactamente como los usuarios la importan desde `trustgraph.api`, sin exponer la estructura interna del módulo.

docs/README.api-docs.he.md

@@ -0,0 +1,45 @@
+# יצירת תיעוד אוטומטית
+
+## תיעוד REST ו-WebSocket API
+
+- `specs/build-docs.sh` - יוצר את תיעוד ה-REST וה-WebSocket מהמפרטים של OpenAPI ו-AsyncAPI.
+
+## תיעוד API בפייתון
+
+תיעוד ה-API בפייתון נוצר מתוך מחרוזות תיאור (docstrings) באמצעות סקריפט פייתון מותאם, אשר סוקר את החבילה `trustgraph.api`.
+
+### תנאים מוקדמים
+
+חבילת `trustgraph` חייבת להיות ניתנת לייבוא. אם אתם עובדים בסביבת פיתוח:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### יצירת תיעוד
+
+מתוך תיקיית התיעוד:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+זה יוצר קובץ Markdown אחד עם תיעוד API מלא, המציג:
+- מדריך התקנה והתחלה מהירה
+- הצהרות ייבוא עבור כל מחלקה/סוג
+- מחרוזות תיאור מלאות עם דוגמאות
+- תוכן עזר מאורגן לפי קטגוריות
+
+### סגנון התיעוד
+
+כל מחרוזות התיאור עוקבות אחר פורמט Google:
+- סיכום קצר בשורה אחת
+- תיאור מפורט
+- סעיף "Args" עם תיאורי פרמטרים
+- סעיף "Returns"
+- סעיף "Raises" (במידת הצורך)
+- בלוקי קוד לדוגמה עם הדגשת תחביר מתאימה
+
+התיעוד שנוצר מציג את ה-API הציבורי בדיוק כפי שהמשתמשים מייבאים אותו מ-`trustgraph.api`, מבלי לחשוף את המבנה הפנימי של המודול.

docs/README.api-docs.hi.md

@@ -0,0 +1,53 @@
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर के कोड का अनुवाद न करें।
+- केवल अनुवादित पाठ प्रस्तुत करें, बिना किसी प्रारंभिक या स्पष्टीकरण के।
+
+अनुवाद करने के लिए पाठ:
+
+# स्वचालित रूप से दस्तावेज़ उत्पन्न करना
+
+## REST और WebSocket API दस्तावेज़
+
+- `specs/build-docs.sh` - OpenAPI और AsyncAPI विनिर्देशों से REST और WebSocket दस्तावेज़ बनाता है।
+
+## पायथन API दस्तावेज़
+
+पायथन API दस्तावेज़, `trustgraph.api` पैकेज का विश्लेषण करके एक कस्टम पायथन स्क्रिप्ट का उपयोग करके docstrings से उत्पन्न होते हैं।
+
+### पूर्व आवश्यकताएँ
+
+trustgraph पैकेज आयात करने योग्य होना चाहिए। यदि आप एक विकास वातावरण में काम कर रहे हैं, तो:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### दस्तावेज़ उत्पन्न करना
+
+दस्तावेज़ निर्देशिका से:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+यह एक एकल Markdown फ़ाइल उत्पन्न करता है जिसमें संपूर्ण API दस्तावेज़ शामिल है, जिसमें निम्नलिखित शामिल हैं:
+- स्थापना और त्वरित शुरुआत गाइड
+- प्रत्येक वर्ग/प्रकार के लिए आयात कथन
+- पूर्ण docstrings के साथ उदाहरण
+- श्रेणियों द्वारा व्यवस्थित सामग्री तालिका
+
+### दस्तावेज़ शैली
+
+सभी docstrings Google-शैली का पालन करते हैं:
+- संक्षिप्त एक-पंक्ति सारांश
+- विस्तृत विवरण
+- पैरामीटर विवरण के साथ Args अनुभाग
+- रिटर्न अनुभाग
+- प्रासंगिक होने पर Raises अनुभाग
+- उचित सिंटैक्स हाइलाइटिंग के साथ उदाहरण कोड ब्लॉक
+
+उत्पन्न दस्तावेज़ सार्वजनिक API को ठीक उसी तरह दिखाता है जैसे उपयोगकर्ता इसे `trustgraph.api` से आयात करते हैं, आंतरिक मॉड्यूल संरचना को उजागर किए बिना।

docs/README.api-docs.pt.md

@@ -0,0 +1,48 @@
+
+# Geração automática de documentação
+
+## Documentação da API REST e WebSocket
+
+`specs/build-docs.sh` - Constrói a documentação REST e WebSocket a partir das
+  especificações OpenAPI e AsyncAPI.
+
+## Documentação da API Python
+
+A documentação da API Python é gerada a partir de docstrings usando um script Python personalizado que inspeciona o pacote `trustgraph.api`.
+
+### Pré-requisitos
+
+O pacote trustgraph deve ser importável. Se você estiver trabalhando em um ambiente de desenvolvimento:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Gerando Documentação
+
+A partir do diretório de documentação:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Isso gera um único arquivo Markdown com documentação completa da API, mostrando:
+Instruções de instalação e guia de início rápido
+Declarações de importação para cada classe/tipo
+Documentação completa com exemplos
+Sumário organizado por categoria
+
+### Estilo da Documentação
+
+Todas as documentações seguem o formato do Google:
+Resumo breve de uma linha
+Descrição detalhada
+Seção "Args" com descrições dos parâmetros
+Seção "Returns"
+Seção "Raises" (quando aplicável)
+Blocos de código de exemplo com realce de sintaxe adequado
+
+A documentação gerada mostra a API pública exatamente como os usuários a importam de `trustgraph.api`, sem expor a estrutura interna do módulo.
+

docs/README.api-docs.ru.md

@@ -0,0 +1,45 @@
+# Автоматическое создание документации
+
+## Документация REST и WebSocket API
+
+- `specs/build-docs.sh` - Создает документацию для REST и WebSocket API на основе спецификаций OpenAPI и AsyncAPI.
+
+## Документация Python API
+
+Документация Python API генерируется из docstrings с использованием пользовательского скрипта Python, который анализирует пакет `trustgraph.api`.
+
+### Требования
+
+Пакет `trustgraph` должен быть импортируемым. Если вы работаете в среде разработки:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Генерация документации
+
+Из каталога `docs`:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Это создает один файл Markdown с полной документацией API, в котором показаны:
+- Инструкции по установке и быстрому запуску
+- Заявления импорта для каждого класса/типа
+- Полные docstrings с примерами
+- Содержание, организованное по категориям
+
+### Стиль документации
+
+Все docstrings следуют формату Google-style:
+- Краткое однострочное описание
+- Подробное описание
+- Раздел "Args" с описаниями параметров
+- Раздел "Returns"
+- Раздел "Raises" (при необходимости)
+- Блоки с примерами кода с правильной подсветкой синтаксиса
+
+Сгенерированная документация отображает публичный API точно так, как его импортируют из `trustgraph.api`, не раскрывая внутреннюю структуру модуля.

docs/README.api-docs.sw.md

@@ -0,0 +1,54 @@
+**MAELEZI MUHIMU:**
+
+- Hifadhi KILA muundo wa Markdown, vichwa, viungo, na alama za HTML.
+- EISI tafsiri code ndani ya ` ` au katika mistari ya code.
+- Toa KAMA, tu maandishi iliyotumwa bila maelezo au maelekezo.
+
+Maandishi ya kutafsiri:
+
+# Kuunda hati moja kwa moja
+
+## Ufafanuzi wa API za REST na WebSocket
+
+- `specs/build-docs.sh` - Inaunda hati za REST na WebSocket kutoka kwenye
+  maelezo za OpenAPI na AsyncAPI.
+
+## Ufafanuzi wa API ya Python
+
+Ufafanuzi wa API ya Python unaoandaliwa kutoka kwa maelezo (docstrings) kwa kutumia skripti ya Python inayotumia, ambayo inaangalia pakiti `trustgraph.api`.
+
+### Vigezo
+
+Pakiti ya trustgraph lazima iweze kuagizwa. Ikiwa unatumia mazingira ya utengenezaji:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Kuunda hati
+
+Kutoka kwenye orodha ya hati:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Hii inaunda faili moja ya markdown yenye hati kamili ya API, inayoeleza:
+- Mwongozo wa usanidi na wa kuanza
+- Maelezo za kuagiza kwa kila sinema/aina
+- Maelezo kamili (docstrings) na mifano
+- Orodha ya maudhui iliyopangwa kwa kategoria
+
+### Mtindo wa hati
+
+Maelezo yote (docstrings) yanatumia mtindo wa Google:
+- Muhtasari wa mstari moja
+- Maelezo kamili
+- Kitengo cha "Args" na maelezo ya thamani
+- Kitengo cha "Returns"
+- Kitengo cha "Raises" (kama inatumika)
+- Mistari ya code na umbo sahihi
+
+Hati iliyoundwa inaonyesha API iliyo na umbo, kama watumiaji wanavyoagiza kutoka kwa `trustgraph.api`, bila kuonyesha muundo wa moduli.

docs/README.api-docs.tr.md

@@ -0,0 +1,48 @@
+
+# Otomatik olarak dokümantasyon oluşturma
+
+## REST ve WebSocket API Dokümantasyonu
+
+`specs/build-docs.sh` - REST ve websocket dokümantasyonunu OpenAPI ve AsyncAPI özelliklerinden oluşturur.
+  
+## Python API Dokümantasyonu
+
+
+Python API dokümantasyonu, `trustgraph.api` paketini inceleyen özel bir Python betiği kullanılarak, dokümantasyon dizelerinden (docstrings) oluşturulur.
+
+### Ön Koşullar
+
+trustgraph paketi içe aktarılabilir olmalıdır. Geliştirme ortamında çalışıyorsanız:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Belgeler Oluşturma
+
+"docs" dizininden:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Bu, eksiksiz API dokümantasyonunu içeren tek bir Markdown dosyası oluşturur ve şunları gösterir:
+Kurulum ve hızlı başlangıç kılavuzu
+Her sınıf/tip için içe aktarma ifadeleri
+Örneklerle birlikte tam dokümanlar
+Kategoriye göre düzenlenmiş içindekiler tablosu
+
+### Dokümantasyon Stili
+
+Tüm dokümanlar, Google stili biçimini izler:
+Kısa, tek satırlık özet
+Ayrıntılı açıklama
+Parametre açıklamalarıyla birlikte "Args" bölümü
+"Returns" bölümü
+"Raises" bölümü (uygulanabilir olduğunda)
+Doğru sözdizimi vurgulamasıyla birlikte örnek kod blokları
+
+Oluşturulan dokümantasyon, kullanıcıların `trustgraph.api`'dan içe aktardığı şekilde, tam olarak kamu API'sini gösterir ve dahili modül yapısını ortaya çıkarmaz.
+

docs/README.api-docs.zh-cn.md

@@ -0,0 +1,45 @@
+# 自动生成文档
+
+## REST 和 WebSocket API 文档
+
+- `specs/build-docs.sh` - 从 OpenAPI 和 AsyncAPI 规范生成 REST 和 WebSocket 文档。
+
+## Python API 文档
+
+Python API 文档是从 docstrings 使用自定义 Python 脚本生成的，该脚本会反向解析 `trustgraph.api` 包。
+
+### 预先条件
+
+`trustgraph` 包必须可导入。 如果您在开发环境中工作，请执行以下操作：
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### 生成文档
+
+从 `docs` 目录：
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+这将生成一个包含完整 API 文档的单个 Markdown 文件，其中包含：
+- 安装和快速入门指南
+- 每个类/类型的导入语句
+- 完整的 docstrings（包含示例）
+- 按类别组织的目录
+
+### 文档风格
+
+所有 docstrings 均遵循 Google 风格：
+- 简短的一行摘要
+- 详细描述
+- 参数描述的 Args 部分
+- Returns 部分
+- Raises 部分（如果适用）
+- 带有正确语法高亮的代码块（示例）
+
+生成的文档显示了用户从 `trustgraph.api` 中导入的公共 API，而无需暴露内部模块结构。

docs/README.ar.md

@@ -0,0 +1,27 @@
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، ووسوم HTML.
+- لا تترجم أي كود داخل علامات التنصيص المزدوجة أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون أي مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+# وثائق TrustGraph
+
+مرحبًا بكم في TrustGraph! للحصول على وثائق شاملة، يرجى زيارة:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+يتضمن الموقع الرئيسي الوثائق:
+
+- **[نظرة عامة](https://docs.trustgraph.ai/overview)** - مقدمة لمفاهيم وهيكل TrustGraph
+- **[دليل المستخدم](https://docs.trustgraph.ai/guides)** - دروس تعليمية خطوة بخطوة وإرشادات
+- **[التثبيت](https://docs.trustgraph.ai/deployment)** - خيارات التثبيت والإعداد
+- **[مرجع](https://docs.trustgraph.ai/reference)** - مواصفات API ووثائق سطر الأوامر
+
+## البدء
+
+**هل أنت جديد في TrustGraph؟** ابدأ بـ [نظرة عامة](https://docs.trustgraph.ai/overview) لفهم النظام.
+
+**هل أنت مستعد للتثبيت؟** تحقق من [دليل التثبيت](https://docs.trustgraph.ai/deployment).
+
+**هل تقوم بدمج الكود؟** راجع [مرجع API](https://docs.trustgraph.ai/reference) للحصول على وثائق REST و WebSocket و SDK.

docs/README.es.md

@@ -0,0 +1,20 @@
+# Documentación de TrustGraph
+
+¡Bienvenido a TrustGraph! Para una documentación completa, por favor visite:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+El sitio principal de documentación incluye:
+
+- **[Descripción general](https://docs.trustgraph.ai/overview)** - Introducción a los conceptos y la arquitectura de TrustGraph
+- **[Guías](https://docs.trustgraph.ai/guides)** - Tutoriales paso a paso y guías de cómo hacerlo
+- **[Implementación](https://docs.trustgraph.ai/deployment)** - Opciones de implementación y configuración
+- **[Referencia](https://docs.trustgraph.ai/reference)** - Especificaciones de la API y documentación de la línea de comandos
+
+## Primeros Pasos
+
+**¿Eres nuevo en TrustGraph?** Comienza con la [Descripción general](https://docs.trustgraph.ai/overview) para comprender el sistema.
+
+**¿Listo para implementar?** Consulta la [Guía de implementación](https://docs.trustgraph.ai/deployment).
+
+**¿Integrando con código?** Consulta la [Referencia de la API](https://docs.trustgraph.ai/reference) para la documentación de REST, WebSocket y SDK.

docs/README.he.md

@@ -0,0 +1,26 @@
+**הוראות חשובות:**
+- שמרו על כל הפורמט של Markdown, כותרות, קישורים ותגי HTML.
+- אל תתרגמו קוד בתוך סימוני backticks או בלוקי קוד.
+- צרו רק את הטקסט המתורגם, ללא הקדמה או הסברים.
+
+טקסט לתרגום:
+# TrustGraph Documentation
+
+ברוכים הבאים ל-TrustGraph! עבור תיעוד מקיף, אנא בקרו ב:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+אתר התיעוד הראשי כולל:
+
+- **[סקירה](https://docs.trustgraph.ai/overview)** - מבוא להגדרות ואדריכלות של TrustGraph
+- **[מדריכים](https://docs.trustgraph.ai/guides)** - מדריכים וורסטיים
+- **[התקנה](https://docs.trustgraph.ai/deployment)** - אפשרויות התקנה והגדרות
+- **[מדריך](https://docs.trustgraph.ai/reference)** - ספקציפיות API ותיעוד CLI
+
+## התחלה
+
+**חדש ב-TrustGraph?** התחילו עם [הסקירה](https://docs.trustgraph.ai/overview) כדי להבין את המערכת.
+
+**מוכנים להתקין?** בדקו את [מדריך ההתקנה](https://docs.trustgraph.ai/deployment).
+
+**שילוב עם קוד?** עיינו ב-[מדריך ה-API](https://docs.trustgraph.ai/reference) עבור תיעוד REST, WebSocket ו-SDK.

docs/README.hi.md

@@ -0,0 +1,27 @@
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown स्वरूपण, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैकटिक या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट प्रदान करें, बिना किसी संवाद पूर्व-परिभाषा या स्पष्टीकरण के।
+
+अनुवाद के लिए पाठ:
+# ट्रस्टग्राफ दस्तावेज़
+
+ट्रस्टग्राफ में आपका स्वागत है! व्यापक दस्तावेज़ के लिए, कृपया इस पर जाएँ:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+मुख्य दस्तावेज़ साइट में शामिल हैं:
+
+- **[अवलोकन](https://docs.trustgraph.ai/overview)** - ट्रस्टग्राफ अवधारणाओं और वास्तुकला का परिचय
+- **[निर्देश](https://docs.trustgraph.ai/guides)** - चरण-दर-चरण ट्यूटोरियल और कैसे करें गाइड
+- **[परिनियोजन](https://docs.trustgraph.ai/deployment)** - परिनियोजन विकल्प और कॉन्फ़िगरेशन
+- **[संदर्भ](https://docs.trustgraph.ai/reference)** - एपीआई विनिर्देश और कमांड-लाइन दस्तावेज़
+
+## शुरुआत कैसे करें
+
+**क्या आप ट्रस्टग्राफ के नए हैं?** सिस्टम को समझने के लिए [अवलोकन](https://docs.trustgraph.ai/overview) से शुरुआत करें।
+
+**क्या आप परिनियोजित करने के लिए तैयार हैं?** [परिनियोजन गाइड](https://docs.trustgraph.ai/deployment) देखें।
+
+**कोड के साथ एकीकृत करना?** REST, WebSocket और SDK दस्तावेज़ के लिए [एपीआई संदर्भ](https://docs.trustgraph.ai/reference) देखें।

docs/README.pt.md

@@ -0,0 +1,21 @@
+# Documentação do TrustGraph
+
+Bem-vindo ao TrustGraph! Para documentação completa, visite:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+O site de documentação principal inclui:
+
+**[Visão Geral](https://docs.trustgraph.ai/overview)** - Introdução aos conceitos e arquitetura do TrustGraph
+**[Guias](https://docs.trustgraph.ai/guides)** - Tutoriais passo a passo e guias de como fazer
+**[Implantação](https://docs.trustgraph.ai/deployment)** - Opções de implantação e configuração
+**[Referência](https://docs.trustgraph.ai/reference)** - Especificações da API e documentação da CLI
+
+## Começando
+
+**Novo no TrustGraph?** Comece com a [Visão Geral](https://docs.trustgraph.ai/overview) para entender o sistema.
+
+**Pronto para implantar?** Consulte o [Guia de Implantação](https://docs.trustgraph.ai/deployment).
+
+**Integrando com código?** Consulte a [Referência da API](https://docs.trustgraph.ai/reference) para documentação REST, WebSocket e SDK.
+

docs/README.ru.md

@@ -0,0 +1,20 @@
+# Документация TrustGraph
+
+Добро пожаловать в TrustGraph! Для получения исчерпывающей документации, пожалуйста, посетите:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Основной сайт документации включает:
+
+- **[Обзор](https://docs.trustgraph.ai/overview)** - Введение в концепции и архитектуру TrustGraph
+- **[Руководства](https://docs.trustgraph.ai/guides)** - Пошаговые руководства и инструкции
+- **[Развертывание](https://docs.trustgraph.ai/deployment)** - Варианты развертывания и конфигурация
+- **[Справочник](https://docs.trustgraph.ai/reference)** - Спецификации API и документация CLI
+
+## Начало работы
+
+**Вы новичок в TrustGraph?** Начните с [Обзора](https://docs.trustgraph.ai/overview), чтобы понять систему.
+
+**Готовы к развертыванию?** Обратитесь к [Руководству по развертыванию](https://docs.trustgraph.ai/deployment).
+
+**Интеграция с кодом?** Посмотрите [Справочник по API](https://docs.trustgraph.ai/reference) для документации REST, WebSocket и SDK.

docs/README.sw.md

@@ -0,0 +1,21 @@
+# Miongozo ya TrustGraph
+
+Karibu kwenye TrustGraph! Kwa miongozo kamili, tafadhali tembelea:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Tovuti kuu ya miongozo inajumuisha:
+
+**[Mawasilisho](https://docs.trustgraph.ai/overview)** - Utangulizi wa dhana na muundo wa TrustGraph
+**[Mwongozo](https://docs.trustgraph.ai/guides)** - Mafunzo ya hatua kwa hatua na mwongozo wa jinsi ya
+**[Ufungaji](https://docs.trustgraph.ai/deployment)** - Chaguo za ufungaji na usanidi
+**[Marejeleo](https://docs.trustgraph.ai/reference)** - Vipimo vya API na miongozo ya CLI
+
+## Kuanza
+
+**Je, wewe ni mpya katika TrustGraph?** Anza na [Mawasilisho](https://docs.trustgraph.ai/overview) ili kuelewa mfumo.
+
+**Uko tayari kufunga?** Angalia [Mwongozo wa Ufungaji](https://docs.trustgraph.ai/deployment).
+
+**Je, unataka kuunganisha na programu?** Angalia [Marejeleo ya API](https://docs.trustgraph.ai/reference) kwa miongozo ya REST, WebSocket, na SDK.
+

docs/README.tr.md

@@ -0,0 +1,21 @@
+# TrustGraph Belgeleri
+
+TrustGraph'a hoş geldiniz! Kapsamlı belgeler için lütfen şu adresi ziyaret edin:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Ana belge sitesi şunları içerir:
+
+**[Genel Bakış](https://docs.trustgraph.ai/overview)** - TrustGraph kavramlarına ve mimarisine giriş
+**[Kılavuzlar](https://docs.trustgraph.ai/guides)** - Adım adım eğitimler ve nasıl yapılır kılavuzları
+**[Dağıtım](https://docs.trustgraph.ai/deployment)** - Dağıtım seçenekleri ve yapılandırma
+**[Referans](https://docs.trustgraph.ai/reference)** - API özellikleri ve CLI belgeleri
+
+## Başlangıç
+
+**TrustGraph'e yeni mi geldiniz?** Sistemi anlamak için [Genel Bakış](https://docs.trustgraph.ai/overview) bölümüne bakın.
+
+**Dağıtıma hazır mısınız?** [Dağıtım Kılavuzu](https://docs.trustgraph.ai/deployment) bölümüne göz atın.
+
+**Koduyla entegre mi olmak istiyorsunuz?** REST, WebSocket ve SDK belgeleri için [API Referansı](https://docs.trustgraph.ai/reference) bölümüne bakın.
+

docs/README.zh-cn.md

@@ -0,0 +1,20 @@
+# TrustGraph 文档
+
+欢迎使用 TrustGraph！为了获得全面的文档，请访问：
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+主文档站点包含：
+
+- **[概述](https://docs.trustgraph.ai/overview)** - 介绍 TrustGraph 的概念和架构
+- **[指南](https://docs.trustgraph.ai/guides)** - 逐步教程和操作指南
+- **[部署](https://docs.trustgraph.ai/deployment)** - 部署选项和配置
+- **[参考](https://docs.trustgraph.ai/reference)** - API 规范和 CLI 文档
+
+## 快速入门
+
+**您是 TrustGraph 的新手吗？** 请从 [概述](https://docs.trustgraph.ai/overview) 开始，了解系统。
+
+**准备部署了吗？** 请查看 [部署指南](https://docs.trustgraph.ai/deployment)。
+
+**要与代码集成？** 请查看 [API 参考](https://docs.trustgraph.ai/reference)，其中包含 REST、WebSocket 和 SDK 文档。

docs/api-gateway-changes-v1.8-to-v2.1.ar.md

@@ -0,0 +1,100 @@
+# تغييرات في واجهة برمجة التطبيقات: v1.8 إلى v2.1
+
+## ملخص
+
+حصلت واجهة برمجة التطبيقات على مُسِير خدمات WebSocket الجديدة لإرسال استعلامات "التضمين"، ونقطة نهاية REST الجديدة للتدفق لمحتوى المستند، وتم إجراء تغيير كبير في تنسيق الكود من "القيمة" إلى "الحد". تم إعادة تسمية خدمة "الكائنات" إلى "الصفوف".
+
+---
+
+## مُسِير خدمات WebSocket الجديدة
+
+هذه هي خدمات طلب/استجابة جديدة متاحة من خلال مُضاعِف WebSocket في `/api/v1/socket` (محدد على مستوى التدفق):
+
+| مفتاح الخدمة | الوصف |
+|---|---|
+| `document-embeddings` | استعلام عن أجزاء المستند بناءً على التشابه النصي. يستخدم الطلب/الاستجابة مخططات `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | استعلام عن صفوف البيانات المنظمة بناءً على التشابه النصي في الحقول المفهرسة. يستخدم الطلب/الاستجابة مخططات `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+تضاف إلى مُسِير "graph-embeddings" الحالي (الذي كان موجودًا بالفعل في v1.8 ولكنه قد تم تحديثه).
+
+### قائمة كاملة بمُسِير خدمات تدفق WebSocket (v2.1)
+
+خدمات طلب/استجابة (عبر `/api/v1/flow/{flow}/service/{kind}` أو مُضاعِف WebSocket):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## نقطة نهاية REST الجديدة
+
+| الطريقة | المسار | الوصف |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | تدفق محتوى المستند من المكتبة كبيانات خام. معلمات الاستعلام: `user` (مطلوب)، `document-id` (مطلوب)، `chunk-size` (اختياري، القيمة الافتراضية 1 ميجابايت). يُرجع محتوى المستند بتنسيق نقل متقطع، مع فك ترميزه من base64 داخليًا. |
+
+---
+
+## إعادة تسمية الخدمة: "objects" إلى "rows"
+
+| v1.8 | v2.1 | الملاحظات |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | تغير المخطط من `ObjectsQueryRequest`/`ObjectsQueryResponse` إلى `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | مُسِير الاستيراد للبيانات المنظمة. |
+
+تغير مفتاح خدمة WebSocket من `"objects"` إلى `"rows"`, وتغير مفتاح مُسِير الاستيراد بشكل مشابه من `"objects"` إلى `"rows"`.
+
+---
+
+## تغيير تنسيق الكود: Value إلى Term
+
+تم إعادة كتابة طبقة التسلسل (serialize.py) لاستخدام النوع الجديد "Term" بدلاً من النوع القديم "Value".
+
+### التنسيق القديم (v1.8 — Value)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: القيمة (سلسلة)
+- `e`: علامة منطقية تشير إلى ما إذا كانت القيمة عبارة عن URI
+
+### التنسيق الجديد (v2.1 — Term)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Literals:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Quoted triples (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: مُحدد النوع — `"i"` (URI)، `"l"` (حرف)، `"r"` (ثلاثي مُقتبس)، `"b"` (عقدة فارغة)
+- الآن يتم تفويض التسلسل إلى `TermTranslator` و `TripleTranslator` من `trustgraph.messaging.translators.primitives`
+
+### تغييرات التسلسل الأخرى
+
+| الحقل | v1.8 | v2.1 |
+|---|---|---|
+| البيانات الوصفية | `metadata.metadata` (البريد الفرعي) | `metadata.root` (قيمة بسيطة) |
+| كيان تضمينات الرسم البياني | `entity.vectors` (مجموع) | `entity.vector` (مفرد) |
+| جزء تضمين المستند | `chunk.vectors` + `chunk.chunk` (النص) | `chunk.vector` + `chunk.chunk_id` (مرجع المعرّف) |
+
+---
+
+## تغييرات في الكسر
+
+- **تنسيق الكود Value إلى Term**: يجب على جميع العملاء الذين يرسلون/يستقبلون ثلاثيات أو سياقات الكائنات أو التضمينات من خلال واجهة برمجة التطبيقات تحديثها إلى التنسيق الجديد Term.
+- **إعادة تسمية "objects" إلى "rows"**: تغير مفتاح خدمة WebSocket ومفتاح الاستيراد.
+- **تغيير حقل البيانات الوصفية**: تم استبدال `metadata.metadata` (مجموعة فرعية مُسلسلة) بـ `metadata.root` (قيمة بسيطة).
+- **تغييرات حقول التضمين**: أصبح `vectors` (مجموع) هو `vector` (مفرد)، وتستخدم تضمينات المستند الآن `chunk_id` بدلاً من النص المضمن.
+- **نقطة نهاية جديدة `/api/v1/document-stream`**: إضافية، وليست مُفسرة.

docs/api-gateway-changes-v1.8-to-v2.1.es.md

@@ -0,0 +1,100 @@
+# Cambios en el API Gateway: v1.8 a v2.1
+
+## Resumen
+
+El gateway de API ha obtenido nuevos despachadores de servicios WebSocket para consultas de incrustaciones, un nuevo punto final REST para el streaming de contenido de documentos, y ha experimentado un cambio significativo en el formato del cableado de `Value` a `Term`. El "servicio de objetos" se ha renombrado a "filas".
+
+---
+
+## Nuevos Despachadores de Servicios WebSocket
+
+Estos son nuevos servicios de solicitud/respuesta disponibles a través del multiplexador WebSocket en `/api/v1/socket` (con ámbito de flujo):
+
+| Clave de servicio | Descripción |
+|-------------|-------------|
+| `document-embeddings` | Consulta fragmentos de documentos por similitud de texto. La solicitud/respuesta utiliza los esquemas `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | Consulta filas de datos estructurados por similitud de texto en campos indexados. La solicitud/respuesta utiliza los esquemas `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+Estos se unen al existente `graph-embeddings` dispatcher (que ya estaba presente en v1.8 pero puede que se haya actualizado).
+
+### Lista completa de despachadores de servicios de flujo WebSocket (v2.1)
+
+Servicios de solicitud/respuesta (a través de `/api/v1/flow/{flow}/service/{kind}` o multiplexador WebSocket):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## Nuevo Punto Final REST
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET` | `/api/v1/document-stream` | Transmite contenido de documentos desde la biblioteca como bytes brutos. Parámetros de consulta: `user` (obligatorio), `document-id` (obligatorio), `chunk-size` (opcional, predeterminado 1MB). Devuelve el contenido del documento con el codificado de transferencia en fragmentos, decodificado internamente en base64. |
+
+---
+
+## Servicio Renombrado: "objects" a "rows"
+
+| v1.8 | v2.1 | Notas |
+|------|------|-------|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | El esquema cambiado de `ObjectsQueryRequest`/`ObjectsQueryResponse` a `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Despachador de importación para datos estructurados. |
+
+La clave del servicio WebSocket cambió de `"objects"` a `"rows"`, y la clave del despachador de importación cambió de `"objects"` a `"rows"`.
+
+---
+
+## Cambio de Formato del Cable: Value a Term
+
+La capa de serialización (`serialize.py`) se ha reescrito para utilizar el nuevo tipo `Term` en lugar del antiguo tipo `Value`.
+
+### Formato antiguo (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: el valor (cadena)
+- `e`: indicador booleano que indica si el valor es un URI
+
+### Formato nuevo (v2.1 — `Term`)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Literales:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Triples con comillas (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: discriminador de tipo — `"i"` (URI), `"l"` (literal), `"r"` (triple con comillas), `"b"` (nodo en blanco)
+- La serialización ahora delega a `TermTranslator` y `TripleTranslator` de `trustgraph.messaging.translators.primitives`
+
+### Otros cambios en la serialización
+
+| Campo | v1.8 | v2.1 |
+|-------|------|------|
+| Metadatos | `metadata.metadata` (subgrafo) | `metadata.root` (valor simple) |
+| Entidad de incrustación | `entity.vectors` (plural) | `entity.vector` (singular) |
+| Fragmento de incrustación de documento | `chunk.vectors` + `chunk.chunk` (texto) | `chunk.vector` + `chunk.chunk_id` (ID de referencia) |
+
+---
+
+## Cambios que Rompen
+
+- **Cambio de formato del cable `Value` a `Term`**: Todos los clientes que envían/reciben triples, incrustaciones o contextos de entidad a través del gateway deben actualizar al nuevo formato Term.
+- **Cambio de nombre de `objects` a `rows`**: Se ha modificado la clave del servicio WebSocket y la clave del despachador de importación.
+- **Cambio del campo de metadatos**: `metadata.metadata` (un subgrafo serializado) reemplazado por `metadata.root` (un valor simple).
+- **Cambios en los campos de incrustación**: `vectors` (plural) se convirtió en `vector` (singular); las incrustaciones de documentos ahora hacen referencia a `chunk_id` en lugar de a `chunk` de texto.
+- **Nuevo punto final `/api/v1/document-stream`**: Aditivo, no rompe.

docs/api-gateway-changes-v1.8-to-v2.1.he.md

@@ -0,0 +1,98 @@
+# שינויים ב-API Gateway: v1.8 ל-v2.1
+
+## תקציר
+
+ה-API Gateway קיבל ספקי שירות WebSocket חדשים עבור שאילתות של "embeddings", סוף שירות REST חדש להעברת תוכן מסמך, וכן שינוי משמעותי בפורמט של קוד: מ-"Value" ל-"Term". השירות "objects" שונה לשם "rows".
+
+---
+
+## ספקי שירות WebSocket חדשים
+
+אלו הם שירותי בקשה/תגובה חדשים הזמינים דרך המולטיפלקסר של WebSocket בכתובת `/api/v1/socket` (הקשור למערכת זרימה):
+
+| מפתח שירות | תיאור |
+|---|---|
+| `document-embeddings` | מבקש חלקים של מסמך על סמך דמיון טקסט. הבקשה/תגובה משתמשים בתבניות `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | מבקש שורות של נתונים מובנים על סמך דמיון טקסט בשדות המצביעים. הבקשה/תגובה משתמשות בתבניות `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+הם מצטרפים למספק הקיים `graph-embeddings` (שהיה קיים כבר ב-v1.8 אך ייתכן ששונה),
+
+### רשימה מלאה של ספקי שירות זרימה של WebSocket (v2.1)
+
+שירותי בקשה/תגובה (דרך `/api/v1/flow/{flow}/service/{kind}` או מולטיפלקסר WebSocket):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## סוף שירות REST חדש
+
+| שיטה | נתיב | תיאור |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | מעביר תוכן מסמך מהספרייה כביטים גולמיים. פרמטרי שאילתה: `user` (חובה), `document-id` (חובה), `chunk-size` (אופציונלי, ברירת מחדל 1MB). מחזיר את תוכן המסמך בתבנית העברת ביטים, לאחר פעולת Base64 פנימית. |
+
+---
+
+## שינוי שם שירות: "objects" ל-"rows"
+
+| v1.8 | v2.1 | הערות |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | התבנית שונתה מ-`ObjectsQueryRequest`/`ObjectsQueryResponse` ל-`RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | ספק ייבוא לנתונים מובנים. |
+
+מפתח השירות של WebSocket שונה מ-"objects" ל-"rows", וממילא מפתח ספק הייבוא שונה מ-"objects" ל-"rows".
+
+---
+
+## שינוי פורמט קוד: Value ל-Term
+
+שכבת הסריאליזציה (`serialize.py`) שונתה כדי להשתמש בסוג ה-"Term" החדש במקום בסוג ה-"Value" הישן.
+
+### פורמט ישן (v1.8 — Value)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: הערך (מחרוזת)
+- `e`: דגל בוליאני המציין אם הערך הוא URI
+
+### פורמט חדש (v2.1 — Term)
+
+- IRI:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+- רשימות:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+- טריפלים מוערים (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: מחלקת סוג — `"i"` (IRI), `"l"` (רשימה), `"r"` (טריפל מוער), `"b"` (צומת ריק)
+- הסריאליזציה כעת מקפלת ל-`TermTranslator` ו-`TripleTranslator` מ-`trustgraph.messaging.translators.primitives
+
+### שינויי סריאליזציה אחרים
+
+| שדה | v1.8 | v2.1 |
+|---|---|---|
+| Metadata | `metadata.metadata` (סופר-גרף) | `metadata.root` (ערך פשוט) |
+| סוגי embeddings | `entity.vectors` (רשימה) | `entity.vector` (יחיד) |
+| חלקים של embeddings | `chunk.vectors` + `chunk.chunk` (טקסט) | `chunk.vector` + `chunk.chunk_id` (מזהה התייחסות) |
+
+---
+
+## שינויים משמעותיים
+
+- **פורמט קוד Value ל-Term:** כל לקוחות המשדרים/מקבלים טריפלים, embeddings או הקשרים של ישויות דרך ה-gateway צריכים לעדכן לפורמט ה-Term החדש.
+- **שינוי שם של "objects" ל-"rows":** שינוי מפתח שירות של WebSocket ומפתח ייבוא.
+- **שינוי שדה Metadata:** `metadata.metadata` (גרף סריאלי) הוחלף ב-`metadata.root` (ערך פשוט).
+- **שינויים בשדות Embeddings:** `vectors` (רשימה) הפך ל-`vector` (יחיד); embeddings של מסמכים כעת מתייחסים ל-`chunk_id` במקום הטקסט של ה-`chunk`
+- **סוף שירות חדש `/api/v1/document-stream`**: נוסף, לא משבש.

docs/api-gateway-changes-v1.8-to-v2.1.hi.md

@@ -0,0 +1,100 @@
+## API गेटवे में बदलाव: v1.8 से v2.1
+
+## सारांश
+
+API गेटवे में एम्बेडिंग प्रश्नों के लिए नए WebSocket सेवा डिस्पैचर, दस्तावेज़ सामग्री के लिए एक नया REST स्ट्रीमिंग एंडपॉइंट, और `Value` से `Term` में एक महत्वपूर्ण वायर प्रारूप परिवर्तन शामिल है। "ऑब्जेक्ट्स" सेवा को "रो" के रूप में पुनः नाम दिया गया।
+
+---
+
+## नए WebSocket सेवा डिस्पैचर
+
+ये `/api/v1/socket` पर उपलब्ध नए अनुरोध/प्रतिक्रिया सेवाएँ हैं (फ्लो-स्कोप):
+
+| सेवा कुंजी | विवरण |
+|---|---|
+| `document-embeddings` | टेक्स्ट समानता के आधार पर दस्तावेज़ टुकड़ों के लिए क्वेरी करता है। अनुरोध/प्रतिक्रिया `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse` स्कीमा का उपयोग करते हैं। |
+| `row-embeddings` | इंडेक्स किए गए फ़ील्ड में टेक्स्ट समानता के आधार पर संरचित डेटा पंक्तियों के लिए क्वेरी करता है। अनुरोध/प्रतिक्रिया `RowEmbeddingsRequest`/`RowEmbeddingsResponse` स्कीमा का उपयोग करते हैं। |
+
+ये मौजूदा `graph-embeddings` डिस्पैचर (जो पहले से ही v1.8 में मौजूद है, लेकिन अपडेट किया जा सकता है) के साथ जुड़ते हैं।
+
+### WebSocket फ़्लो सेवा डिस्पैचर की पूरी सूची (v2.1)
+
+अनुरोध/प्रतिक्रिया सेवाएँ (`/api/v1/flow/{flow}/service/{kind}` या WebSocket मक्स) के माध्यम से:
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## नया REST एंडपॉइंट
+
+| विधि | पथ | विवरण |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | लाइब्रेरी से मूल बाइट के रूप में दस्तावेज़ सामग्री स्ट्रीम करता है। क्वेरी पैरामीटर: `user` (आवश्यक), `document-id` (आवश्यक), `chunk-size` (वैकल्पिक, डिफ़ॉल्ट 1MB)। आंतरिक रूप से base64 से डिकोड करके दस्तावेज़ सामग्री को chunked transfer encoding में लौटाता है। |
+
+---
+
+## पुनः नामकरण की गई सेवा: "objects" से "rows"
+
+| v1.8 | v2.1 | नोट्स |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | `ObjectsQueryRequest`/`ObjectsQueryResponse` से `RowsQueryRequest`/`RowsQueryResponse` स्कीमा में बदलाव। |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | संरचित डेटा के लिए आयात डिस्पैचर। |
+
+WebSocket सेवा कुंजी `"objects"` से `"rows"` में बदल गई है, और आयात डिस्पैचर कुंजी `"objects"` से `"rows"` में बदल गई है।
+
+---
+
+## वायर प्रारूप में बदलाव: Value से Term
+
+`serialize.py` में serialization लेयर को नए `Term` प्रकार का उपयोग करने के लिए फिर से लिखा गया है, बजाय पुराने `Value` प्रकार का।
+
+### पुराना प्रारूप (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: मान (स्ट्रिंग)
+- `e`: एक बूलियन ध्वज जो दर्शाता है कि मान एक URI है या नहीं
+
+### नया प्रारूप (v2.1 — `Term`)
+
+IRI:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+प्रत्यक्ष:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+कोटेड ट्रिपल (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: प्रकार डिस्‍क्रिमिनेटर — `"i"` (IRI), `"l"` (प्रत्यक्ष), `"r"` (कोटेड ट्रिपल), `"b"` (ब्लैंक नोड)
+- serialization अब `trustgraph.messaging.translators.primitives` से `TermTranslator` और `TripleTranslator` को सौंपता है।
+
+### अन्य serialization में बदलाव
+
+| फ़ील्ड | v1.8 | v2.1 |
+|---|---|---|
+| मेटाडेटा | `metadata.metadata` (उप-ग्राफ) | `metadata.root` (सरल मान) |
+| ग्राफ एम्बेडिंग इकाई | `entity.vectors` (बहु) | `entity.vector` (एकल) |
+| दस्तावेज़ एम्बेडिंग टुकड़ा | `chunk.vectors` + `chunk.chunk` (टेक्स्ट) | `chunk.vector` + `chunk.chunk_id` (आईडी संदर्भ) |
+
+---
+
+## महत्वपूर्ण बदलाव
+
+- **`Value` से `Term` वायर प्रारूप**: गेटवे के माध्यम से ट्रिपल, एम्बेडिंग या इकाई संदर्भ भेजने/प्राप्त करने वाले सभी क्लाइंट को नए Term प्रारूप के साथ अपडेट करना होगा।
+- **`objects` से `rows` का नामकरण**: WebSocket सेवा कुंजी और आयात कुंजी में बदलाव।
+- **मेटाडेटा फ़ील्ड में बदलाव**: `metadata.metadata` (एक serialized उप-ग्राफ) को `metadata.root` (एक सरल मान) से बदला गया।
+- **एम्बेडिंग फ़ील्ड में बदलाव**: `vectors` (बहु) को `vector` (एकल) से बदला गया; दस्तावेज़ एम्बेडिंग अब `chunk_id` को संदर्भित करती हैं, बजाय inline `chunk` टेक्स्ट के।
+- **नया `/api/v1/document-stream` एंडपॉइंट**: यह एक अतिरिक्त परिवर्तन है, जो पहले से ही मौजूद है।

docs/api-gateway-changes-v1.8-to-v2.1.pt.md

@@ -0,0 +1,108 @@
+# Alterações no API Gateway: da versão 1.8 para a versão 2.1
+
+## Resumo
+
+O gateway de API ganhou novos distribuidores de serviços WebSocket para consultas de incorporações
+e um novo endpoint REST para streaming de conteúdo de documentos, e passou por
+uma mudança significativa no formato de comunicação, de `Value` para `Term`. O serviço "objects"
+foi renomeado para "rows".
+
+--
+
+## Novos Distribuidores de Serviços WebSocket
+
+Estes são novos serviços de solicitação/resposta disponíveis através do
+multiplexador WebSocket em `/api/v1/socket` (com escopo de fluxo):
+
+| Chave do Serviço | Descrição |
+|-------------|-------------|
+| `document-embeddings` | Consulta de trechos de documentos por similaridade de texto. Solicitação/resposta usa os esquemas `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | Consulta de linhas de dados estruturados por similaridade de texto em campos indexados. Solicitação/resposta usa os esquemas `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+Estes se juntam ao distribuidor existente `graph-embeddings` (que já
+estava presente na versão 1.8, mas pode ter sido atualizado).
+
+### Lista completa de distribuidores de serviços de fluxo WebSocket (versão 2.1)
+
+Serviços de solicitação/resposta (via `/api/v1/flow/{flow}/service/{kind}` ou
+multiplexador WebSocket):
+
+`agent`, `text-completion`, `prompt`, `mcp-tool`
+`graph-rag`, `document-rag`
+`embeddings`, `graph-embeddings`, `document-embeddings`
+`triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+`row-embeddings`
+
+--
+
+## Novo Endpoint REST
+
+| Método | Caminho | Descrição |
+|--------|------|-------------|
+| `GET` | `/api/v1/document-stream` | Transmite o conteúdo do documento da biblioteca como bytes brutos. Parâmetros de consulta: `user` (obrigatório), `document-id` (obrigatório), `chunk-size` (opcional, padrão 1MB). Retorna o conteúdo do documento em codificação de transferência em blocos, decodificado de base64 internamente. |
+
+--
+
+## Serviço Renomeado: "objects" para "rows"
+
+| v1.8 | v2.1 | Notas |
+|------|------|-------|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Esquema alterado de `ObjectsQueryRequest`/`ObjectsQueryResponse` para `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Distribuidor de importação para dados estruturados. |
+
+A chave do serviço WebSocket foi alterada de `"objects"` para `"rows"`, e a
+chave do distribuidor de importação foi alterada de `"objects"` para `"rows"`.
+
+--
+
+## Mudança no Formato de Comunicação: Valor para Termo
+
+A camada de serialização (`serialize.py`) foi reescrita para usar o novo tipo `Term`
+em vez do tipo antigo `Value`.
+
+### Formato antigo (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+`v`: o valor (string)
+`e`: flag booleano que indica se o valor é um URI
+
+### Novo formato (v2.1 — `Term`)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Literais:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Triplas citadas (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+`t`: tipo de discriminador — `"i"` (IRI), `"l"` (literal), `"r"` (tripla entre aspas), `"b"` (nó vazio)
+A serialização agora delega para `TermTranslator` e `TripleTranslator` a partir de `trustgraph.messaging.translators.primitives`
+
+### Outras alterações de serialização
+
+| Campo | v1.8 | v2.1 |
+|-------|------|------|
+| Metadados | `metadata.metadata` (subgrafo) | `metadata.root` (valor simples) |
+| Incorporação de entidade | `entity.vectors` (plural) | `entity.vector` (singular) |
+| Incorporação de fragmento de documento | `chunk.vectors` + `chunk.chunk` (texto) | `chunk.vector` + `chunk.chunk_id` (referência de ID) |
+
+--
+
+## Alterações Incompatíveis
+
+**Formato de fio de `Value` para `Term`**: Todos os clientes que enviam ou recebem triplas, incorporações ou contextos de entidade através do gateway devem atualizar para o novo formato de Termo.
+**Renomeação de `objects` para `rows`**: A chave do serviço WebSocket e a chave de importação foram alteradas.
+**Alteração do campo de metadados**: `metadata.metadata` (um subgrafo serializado) foi substituído por `metadata.root` (um valor simples).
+**Alterações nos campos de incorporação**: `vectors` (plural) se tornou `vector` (singular); as incorporações de documento agora fazem referência a `chunk_id` em vez de texto `chunk` inline.
+**Novo endpoint `/api/v1/document-stream`**: Aditivo, não quebra a compatibilidade.

docs/api-gateway-changes-v1.8-to-v2.1.ru.md

@@ -0,0 +1,100 @@
+# Изменения в API Gateway: v1.8 до v2.1
+
+## Обзор
+
+API Gateway получил новые диспетчеры WebSocket для запросов на основе встраивания, новый REST-endpoint для потоковой передачи содержимого документов, и претерпел значительные изменения в формате представления данных, перейдя с `Value` на `Term`. Сервис "objects" был переименован в "rows".
+
+---
+
+## Новые диспетчеры WebSocket
+
+Это новые сервисы запросов/ответов, доступные через WebSocket-мультиплексор по адресу `/api/v1/socket` (с фокусом на flow):
+
+| Ключ сервиса | Описание |
+|---|---|
+| `document-embeddings` | Запросы на фрагменты документов по текстовому сходству. Используются схемы `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | Запросы на структурированные данные по текстовому сходству по индексированным полям. Используются схемы `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+Эти диспетчеры работают вместе с существующим диспетчером `graph-embeddings` (который уже был в v1.8, но мог быть обновлен).
+
+### Полный список диспетчеров WebSocket (v2.1)
+
+Сервисы запросов/ответов (через `/api/v1/flow/{flow}/service/{kind}` или WebSocket-мультиплексор):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## Новый REST Endpoint
+
+| Метод | Путь | Описание |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | Потоковая передача содержимого документов из библиотеки в виде сырых байтов. Параметры запроса: `user` (обязательно), `document-id` (обязательно), `chunk-size` (необязательно, значение по умолчанию 1MB). Возвращает содержимое документа в коде transfer encoding, который декодируется из base64 внутри. |
+
+---
+
+## Переименованный сервис: "objects" в "rows"
+
+| v1.8 | v2.1 | Примечания |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Схема изменена с `ObjectsQueryRequest`/`ObjectsQueryResponse` на `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Импорт для структурированных данных. |
+
+Ключ WebSocket-сервиса изменился с `"objects"` на `"rows"`, а ключ импорт-диспатчера аналогично — с `"objects"` на `"rows"`.
+
+---
+
+## Изменение формата представления данных: Value на Term
+
+Слой сериализации (`serialize.py`) был переписан для использования нового типа `Term` вместо старого типа `Value`.
+
+### Старый формат (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: значение (строка)
+- `e`: булевский флаг, указывающий, является ли значение URI
+
+### Новый формат (v2.1 — `Term`)
+
+URI:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Литералы:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Тройки, указанные в кавычках (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: дискриминатор типа — `"i"` (URI), `"l"` (литерал), `"r"` (тройка), `"b"` (blank node)
+- Сериализация теперь делегируется `TermTranslator` и `TripleTranslator` из `trustgraph.messaging.translators.primitives`
+
+### Другие изменения в сериализации
+
+| Поле | v1.8 | v2.1 |
+|---|---|---|
+| Metadata | `metadata.metadata` (подграфа) | `metadata.root` (простое значение) |
+| Graph embeddings entity | `entity.vectors` (множественное) | `entity.vector` (одиночное) |
+| Document embeddings chunk | `chunk.vectors` + `chunk.chunk` (текст) | `chunk.vector` + `chunk.chunk_id` (ссылка на ID) |
+
+---
+
+## Изменения, требующие внимания
+
+- **Формат представления данных Value в Term**: Все клиенты, отправляющие/получающие тройки, встраивания или контексты сущностей через gateway, должны обновиться до нового формата Term.
+- **Переименование объектов в rows**: Изменился ключ WebSocket-сервиса и ключ импорт-диспатчера.
+- **Изменение поля metadata**: `metadata.metadata` (сериализованная подграфа) заменено на `metadata.root` (простое значение).
+- **Изменения полей embeddings**: `vectors` (множественное) стало `vector` (одиночное); теперь встраивания документов ссылаются на `chunk_id` вместо inline `chunk`.
+- **Новый endpoint `/api/v1/document-stream`**: Дополнительный, не является "breaking".

docs/api-gateway-changes-v1.8-to-v2.1.sw.md

@@ -0,0 +1,106 @@
+**MAELEZO MAZOE:**
+- Weka ВИWAMU za muundo, vichungi, viungo na alama za HTML.
+- Usitafsiri nakala ndani ya alama za ``` au katika blok za nakala.
+- Toa NA TUJUI tu, bila utangulizi au maelezo.
+
+Nakala inayohitajika:
+# Mabadiliko ya API Gateway: v1.8 hadi v2.1
+
+## Muhtasari
+
+API gateway imepata mpya wa huduma za WebSocket kwa ajili ya majabuzi, kiungo cha mpya cha REST kwa maudhui, na imepitia mabadiliko muhimu katika muundo wa data kutoka `Value` hadi `Term`. Huduma "objects" imebadilishwa na "rows".
+
+---
+
+## Wengine Wepya wa Huduma za WebSocket
+
+Hizi ni huduma mpya za ombi/majibu zinazopatikana kupitia multiplexer ya WebSocket katika `/api/v1/socket` (na msingi wa "flow"):
+
+| Key ya Huduma | Maelezo |
+|-------------|-------------|
+| `document-embeddings` | Inatafuta sehemu za hati kwa utofauti wa maandishi. Ombi/majibu hutumia miundo `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | Inatafuta data iliyoandaliwa kwa utofauti wa maandishi kwenye majina iliyosawazwa. Ombi/majibu hutumia miundo `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+Hizi zinaunganishwa na `graph-embeddings` iliyopo tayari katika v1.8, lakini inaweza kuwa imeboreshwa.
+
+### Orodha kamili ya huduma za WebSocket (v2.1)
+
+Huduma za ombi/majibu (kupitia `/api/v1/flow/{flow}/service/{kind}` au WebSocket mux):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## Kiungo cha REST cha Mpya
+
+| Njia | Path | Maelezo |
+|--------|------|-------------|
+| `GET` | `/api/v1/document-stream` | Inatoa maudhui ya hati kutoka kwenye makala kama data ya msingi. Parametari za ombi: `user` (lazima), `document-id` (lazima), `chunk-size` (bora, chaguo, 1MB). Inarudisha maudhui ya hati kama data iliyobadilishwa, na inatumia teknolojia ya "chunked transfer encoding" ya base64. |
+
+---
+
+## Huduma iliyobadilishwa: "objects" hadi "rows"
+
+| v1.8 | v2.1 | Maelezo |
+|------|------|-------|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Muundo umebadilishwa kutoka `ObjectsQueryRequest`/`ObjectsQueryResponse` hadi `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Huduma ya import kwa data iliyoandaliwa. |
+
+Key ya huduma ya WebSocket imebadilishwa kutoka "objects" hadi "rows", na key ya import pia imebadilishwa.
+
+---
+
+## Mabadiliko ya Muundo: Value hadi Term
+
+Sura ya usimamizaji (`serialize.py`) imeandikwa upya ili kutumia aina mpya ya "Term" badala ya aina ya "Value" iliyokuwa.
+
+### Sura ya awali (v1.8 — Value)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: thamani (string)
+- `e`: bendera ya booleani inayoeleza kama thamani ni URI
+
+### Sura mpya (v2.1 — Term)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Literals:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Triple za mlangano (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: makazi - `"i"` (URI), `"l"` (thamini), `"r"` (triple), `"b"` (blank node)
+- Usimamizi sasa unaendeleza kwa `TermTranslator` na `TripleTranslator` kutoka `trustgraph.messaging.translators.primitives`
+
+### Mabadiliko mengine ya usimamizaji
+
+| Kipa | v1.8 | v2.1 |
+|-------|------|------|
+| Metadata | `metadata.metadata` (subgraph) | `metadata.root` (thamini rahisi) |
+| Graph embeddings entity | `entity.vectors` (pl) | `entity.vector` (singular) |
+| Document embeddings chunk | `chunk.vectors` + `chunk.chunk` (text) | `chunk.vector` + `chunk.chunk_id` (ID reference) |
+
+---
+
+## Mabadiliko Muhimu
+
+- **Muundo Value hadi Term**: Wote wa wateja wanaotumia nakala, ujumizi, au maudhui wanapaswa kubadilishwa kwa muundo mpya wa Term.
+- **"objects" hadi "rows"**: Key ya huduma na key ya import zimebadilishwa.
+- **Mabadiliko ya key ya Metadata**: `metadata.metadata` (subgraph iliyosimamizwa) imebadilishwa na `metadata.root` (thamini rahisi).
+- **Mabadiliko ya key ya Embeddings**: `vectors` (plural) imebadilishwa na `vector` (singular); ujumizi wa hati sasa inaangalia `chunk_id` badala ya "chunk" ya msingi.
+- **Kiungo cha mpya `/api/v1/document-stream`**: Haiathiri.

docs/api-gateway-changes-v1.8-to-v2.1.tr.md

@@ -0,0 +1,108 @@
+# API Ağ Geçidi Değişiklikleri: v1.8'den v2.1'e
+
+## Özet
+
+API ağ geçidi, gömülü sorgular için yeni WebSocket hizmet yönlendiricileri, belge içeriği için yeni bir REST akış uç noktası kazandı ve ⟦CODE_0⟧'dan ⟦CODE_1⟧'e önemli bir veri formatı değişikliğine uğradı. "objects" hizmeti "rows" olarak yeniden adlandırıldı.
+sorguları, belge içeriği için yeni bir REST akış uç noktası ve aşağıdaki değişiklikleri içerdi:
+önemli bir tel format değişikliği, `Value`'dan `Term`'e geçiş. "Nesneler"
+
+
+--
+
+## Yeni WebSocket Hizmet Yönlendiricileri
+
+Bunlar, WebSocket üzerinden sunulan yeni istek/yanıt servisleridir.
+`/api/v1/socket` adresindeki çoklayıcı (akış kapsamlı):
+
+| Servis Anahtarı | Açıklama |
+|-------------|-------------|
+| `document-embeddings` | Metin benzerliği ile belge parçalarını sorgular. İstek/yanıt, `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse` şemalarını kullanır. |
+| `row-embeddings` | İndekslenmiş alanlarda metin benzerliği ile yapılandırılmış veri satırlarını sorgular. İstek/yanıt, `RowEmbeddingsRequest`/`RowEmbeddingsResponse` şemalarını kullanır. |
+
+Bunlar, mevcut `graph-embeddings` dağıtım aracına (v1.8'de zaten
+bulunan ancak güncellenmiş olabilecek) eklenir.
+
+### WebSocket akış hizmeti dağıtım araçlarının tam listesi (v2.1)
+
+İstek/yanıt hizmetleri (`/api/v1/flow/{flow}/service/{kind}` veya
+WebSocket çoklayıcısı aracılığıyla):
+
+`agent`, `text-completion`, `prompt`, `mcp-tool`
+`graph-rag`, `document-rag`
+`embeddings`, `graph-embeddings`, `document-embeddings`
+`triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+`row-embeddings`
+
+--
+
+## Yeni REST Uç Noktası
+
+| Yöntem | Yol | Açıklama |
+|--------|------|-------------|
+| `GET` | `/api/v1/document-stream` | Kütüphaneden belge içeriğini ham baytlar olarak aktarır. Sorgu parametreleri: `user` (gerekli), `document-id` (gerekli), `chunk-size` (isteğe bağlı, varsayılan 1MB). Belge içeriğini, dahili olarak base64'ten çözülmüş olarak, parçalı aktarım kodlamasıyla döndürür. |
+
+--
+
+## Yeniden Adlandırılan Hizmet: "objects" -> "rows"
+
+| v1.8 | v2.1 | Notlar |
+|------|------|-------|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Şema, `ObjectsQueryRequest`/`ObjectsQueryResponse`'den `RowsQueryRequest`/`RowsQueryResponse`'ye dönüştürüldü. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Yapılandırılmış veri için import yöneticisi. |
+
+WebSocket hizmet anahtarı `"objects"`'dan `"rows"`'e değişti ve
+import yöneticisi anahtarı da benzer şekilde `"objects"`'dan `"rows"`'e değişti.
+
+--
+
+## Kablo Formatındaki Değişiklik: Değerden Terime
+
+Seri hale getirme katmanı (`serialize.py`), yeni `Term`'i kullanmak üzere yeniden yazıldı.
+eski `Value` türünün yerine bu türü kullanın.
+
+### Eski format (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+`v`: değer (string)
+`e`: değerin bir URI olup olmadığını gösteren boolean işaretleyici
+
+### Yeni format (v2.1 — `Term`)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Sabitler:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Tırnak içinde belirtilen üçlüler (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+`t`: tür belirleyici — `"i"` (IRI), `"l"` (literal), `"r"` (tırnak içinde belirtilmiş üçlü), `"b"` (boş düğüm)
+Serileştirme artık `trustgraph.messaging.translators.primitives`'den `TermTranslator` ve `TripleTranslator`'e devrediliyor.
+
+### Diğer serileştirme değişiklikleri
+
+| Alan | v1.8 | v2.1 |
+|-------|------|------|
+| Meta veri | `metadata.metadata` (alt grafik) | `metadata.root` (basit değer) |
+| Grafik gömme varlığı | `entity.vectors` (çoğul) | `entity.vector` (tekil) |
+| Belge gömme parçası | `chunk.vectors` + `chunk.chunk` (metin) | `chunk.vector` + `chunk.chunk_id` (ID referansı) |
+
+--
+
+## Uyumsuz Değişiklikler
+
+**`Value`'dan `Term`'e kablo formatı**: Ağ geçidi üzerinden üçlü, gömme veya varlık bağlamı gönderen/alan tüm istemcilerin, yeni Terim formatına güncellenmesi gerekir.
+**`objects`'dan `rows`'e yeniden adlandırma**: WebSocket hizmet anahtarı ve içe aktarma anahtarı değiştirildi.
+**Meta veri alanı değişikliği**: `metadata.metadata` (serileştirilmiş bir alt grafik), `metadata.root` (basit bir değer) ile değiştirildi.
+**Gömme alanı değişiklikleri**: `vectors` (çoğul), `vector` (tekil) haline geldi; belge gömmeleri artık iç içe `chunk` metni yerine `chunk_id`'yi referans alıyor.
+**Yeni `/api/v1/document-stream` uç noktası**: Uyumsuz değil, eklemeli.

docs/api-gateway-changes-v1.8-to-v2.1.zh-cn.md

@@ -0,0 +1,100 @@
+# API 网关变更：v1.8 到 v2.1
+
+## 摘要
+
+API 网关新增了用于嵌入查询的 WebSocket 服务分发器，新增了 REST 串流端点，用于文档内容，并进行了重要的 Wire 格式变化，从 `Value` 变为 `Term`。 "对象" 服务已被重命名为 "行"。
+
+---
+
+## 新的 WebSocket 服务分发器
+
+这些是可通过 WebSocket 多路复用器 `/api/v1/socket` (范围限定) 访问的新请求/响应服务：
+
+| 服务键 | 描述 |
+|---|---|
+| `document-embeddings` | 通过文本相似性查询文档块。 请求/响应使用 `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse` 模式。 |
+| `row-embeddings` | 通过在索引字段上对结构化数据行进行文本相似性查询。 请求/响应使用 `RowEmbeddingsRequest`/`RowEmbeddingsResponse` 模式。 |
+
+这些与现有的 `graph-embeddings` 分发器 (已存在于 v1.8 但可能已被更新) 关联。
+
+### WebSocket 流程服务分发器的完整列表 (v2.1)
+
+请求/响应服务 (通过 `/api/v1/flow/{flow}/service/{kind}` 或 WebSocket 多路复用器):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## 新的 REST 端点
+
+| 方法 | 路径 | 描述 |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | 从库中流式传输文档内容为原始字节。 查询参数：`user` (必需), `document-id` (必需), `chunk-size` (可选, 默认 1MB)。 返回文档内容，通过内部进行 base64 解码，并以块传输编码传输。 |
+
+---
+
+## 重命名服务： "objects" 为 "rows"
+
+| v1.8 | v2.1 | 备注 |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | 模式从 `ObjectsQueryRequest`/`ObjectsQueryResponse` 变为 `RowsQueryRequest`/`RowsQueryResponse`。 |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | 结构化数据导入分发器。 |
+
+WebSocket 服务键已从 `"objects"` 变为 `"rows"`，以及导入分发器的键也从 `"objects"` 变为 `"rows"`。
+
+---
+
+## Wire 格式变化： Value 为 Term
+
+`serialize.py` (序列化层) 已重写为使用新的 `Term` 类型，而不是旧的 `Value` 类型。
+
+### 旧格式 (v1.8 - `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: 值 (字符串)
+- `e`: 布尔标志，指示值是否为 URI
+
+### 新格式 (v2.1 - `Term`)
+
+IRI:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+字面量：
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+带引号的三元组 (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: 类型区分值 — `"i"` (IRI), `"l"` (字面量), `"r"` (带引号的三元组), `"b"` (空节点)
+- 序列化现在委托给 `trustgraph.messaging.translators.primitives` 中的 `TermTranslator` 和 `TripleTranslator`
+
+### 其他序列化更改
+
+| 字段 | v1.8 | v2.1 |
+|---|---|---|
+| 元数据 | `metadata.metadata` (子图) | `metadata.root` (简单值) |
+| 图嵌入实体 | `entity.vectors` (复数) | `entity.vector` (单数) |
+| 文档嵌入块 | `chunk.vectors` + `chunk.chunk` (文本) | `chunk.vector` + `chunk.chunk_id` (ID 引用) |
+
+---
+
+## 破坏性变更
+
+- **Value 到 Term 的 Wire 格式**: 任何通过网关发送/接收三元组、嵌入或实体上下文的客户端都必须更新为新的 Term 格式。
+- **objects 到 rows 的重命名**: WebSocket 服务键和导入键已更改。
+- **元数据字段更改**: `metadata.metadata` (序列化的子图) 已被 `metadata.root` (简单值) 替换。
+- **嵌入字段更改**: `vectors` (复数) 变为 `vector` (单数)；文档嵌入现在引用 `chunk_id` 而不是内联 `chunk` 文本。
+- **新的 `/api/v1/document-stream` 端点**: 添加的，非破坏性。

docs/cli-changes-v1.8-to-v2.1.ar.md

@@ -0,0 +1,111 @@
+# تغييرات واجهة سطر الأوامر: من v1.8 إلى v2.1
+
+## ملخص
+
+تمت إضافة العديد من الميزات إلى واجهة سطر الأوامر (`trustgraph-cli`)، مع التركيز على ثلاثة مجالات:
+**القابلية للتفسير/الأصل،** **الوصول إلى التضمينات،** و **استعلامات الرسم البياني.**
+تم إزالة أدوات قديمة، وتم تغيير اسم أداة واحدة، وحصلت العديد من الأدوات الموجودة على قدرات جديدة.
+
+---
+
+## أدوات واجهة سطر الأوامر الجديدة
+
+### القابلية للتفسير والأصل
+
+| الأمر | الوصف |
+|---|---|
+| `tg-list-explain-traces` | يسرد جميع جلسات القابلية للتفسير (GraphRAG و Agent) في المجموعة، مع عرض معرفات الجلسة ونوعها ونص السؤال وتوقيتات الإصدار. |
+| `tg-show-explain-trace` | يعرض مسار القابلية للتفسير الكامل لجلسة. لـ GraphRAG: مرحلة السؤال، والبحث/التنقيب، والتركيز، والتوليف. لـ Agent: مرحلة الجلسة، والتكرارات (فكر/عمل/ملاحظة)، والإجابة النهائية. يكتشف تلقائيًا نوع المسار. يدعم الخيارات `--show-provenance` لتتبع الحواف مرة أخرى إلى المستندات المصدر. |
+| `tg-show-extraction-provenance` | بالنظر إلى معرف المستند، فإنه يتتبع سلسلة الأصل: المستند -> الصفحات -> القطع -> الحواف، باستخدام علاقات `prov:wasDerivedFrom`. يدعم الخيارات `--show-content` و `--max-content`. |
+
+### التضمينات
+
+| الأمر | الوصف |
+|---|---|
+| `tg-invoke-embeddings` | يحول النص إلى تضمين متجه عبر خدمة التضمينات. يقبل إدخالات نصية واحدة أو أكثر، ويعيد المتجهات كمصفوفات من الأرقام العشرية. |
+| `tg-invoke-graph-embeddings` | يستعلم عن الكيانات في الرسم البياني باستخدام التضمينات النصية. يعيد الكيانات المطابقة مع درجات التشابه. |
+| `tg-invoke-document-embeddings` | يستعلم عن قطع المستند باستخدام التضمينات النصية. يعيد معرّفات القطع المطابقة مع درجات التشابه. |
+| `tg-invoke-row-embeddings` | يستعلم عن صفوف البيانات المهيكلة باستخدام التشابه النصي على الحقول الفهرسية. يعيد الصفوف المطابقة مع قيم الفهرس ودرجاتها. يتطلب `--schema-name` ويدعم `--index-name`. |
+
+### استعلام الرسم البياني
+
+| الأمر | الوصف |
+|---|---|
+| `tg-query-graph` | استعلام مخزن ثلاثي يعتمد على الأنماط. على عكس `tg-show-graph` (الذي يعرض كل شيء)، فإنه يسمح بالاستعلامات الانتقائية باستخدام أي مجموعة من الموضوع والصفة والكائن والرسم البياني. يكتشف تلقائيًا أنواع القيم: IRIs (`http://...`, `urn:...`, `<...>`)، ثلاثيات مُقتبسة (`<<s p o>>`)، والمفردات. |
+| `tg-get-document-content` | يسترجع محتوى المستند من المكتبة بمعرف المستند. يمكن إخراجها إلى ملف أو stdout، ويدعم كلًا من المحتوى النصي والمحتوى الثنائي. |
+
+---
+
+## أدوات واجهة سطر الأوامر المحذوفة
+
+| الأمر | الملاحظات |
+|---|---|
+| `tg-load-pdf` | تم حذفه. يتم الآن التعامل مع تحميل المستند من خلال المكتبة/مسار المعالجة. |
+| `tg-load-text` | تم حذفه. يتم الآن التعامل مع تحميل المستند من خلال المكتبة/مسار المعالجة. |
+
+---
+
+## تغيير أسماء أدوات واجهة سطر الأوامر
+
+| الاسم القديم | الاسم الجديد | الملاحظات |
+|---|---|---|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | يعكس تغيير التسمية من "الكائنات" إلى "الصفوف" للبيانات المهيكلة. |
+
+---
+
+## تغييرات كبيرة في الأدوات الموجودة
+
+### `tg-invoke-graph-rag`
+
+- **دعم القابلية للتفسير:** يدعم الآن مسار قابلية تفسير مكون من 4 مراحل (السؤال، والبحث/التنقيب، والتركيز، والتوليف) مع عرض متكامل للأحداث المتعلقة بالأصل.
+- **الاستمرارية:** يستخدم بث WebSocket لإخراج في الوقت الفعلي.
+- **تتبع الأصل:** يمكن تتبع الحواف المحددة مرة أخرى إلى المستندات المصدر من خلال إعادة التشكيل و سلاسل `prov:wasDerivedFrom`.
+- زادت من حوالي 30 سطرًا إلى 760 سطرًا لاستيعاب مسار القابلية للتفسير الكامل.
+
+### `tg-invoke-document-rag`
+
+- **دعم القابلية للتفسير:** أضاف وضع `question_explainable()` الذي يخرج استجابات RAG للمستند مع أحداث الأصل المتداخلة (مراحل السؤال، والبحث، والتنقيب، والتوليف).
+
+### `tg-invoke-agent`
+
+- **دعم القابلية للتفسير:** أضاف وضع `question_explainable()` الذي يعرض أحداث الأصل المتداخلة أثناء تنفيذ الوكيل (مراحل السؤال، والتحليل، والاستنتاج، و AgentThought، و AgentObservation، و AgentAnswer).
+- يظهر الوضع التفصيلي سلاسل فكر/ملاحظة مع بادئات رموز تعبيرية.
+
+### `tg-show-graph`
+
+- **وضع الاستمرارية:** يستخدم الآن `triples_query_stream()` مع أحجام دفع قابلة للتكوين للحصول على النتيجة الأولى في أدنى وقت وتقليل الحمل الزائد للذاكرة.
+- **دعم الرسم البياني المسمى:** خيار جديد `--graph`. يكتشف الرسوم البيانية المسماة:
+  - الرسم البياني الافتراضي (فارغ): حقائق المعرفة الأساسية.
+  - `urn:graph:source`: الأصل لاستخراج
+  - `urn:graph:retrieval`: استعلام في وقت التشغيل للقابلية للتفسير
+- **عرض عمود الرسم البياني:** علامة جديدة `--show-graph` لعرض الرسم البياني المسماة لكل ثلاثي.
+- **حدود قابلة للتكوين:** خيارات جديدة `--limit` و `--batch-size`.
+
+### `tg-graph-to-turtle`
+
+- **دعم RDF-star:** يتعامل الآن مع الثلاثيات المقتبسة (إعادة تشكيل RDF-star).
+- **وضع الاستمرارية:** يستخدم الاستمرارية للتحقيق في وقت المعالجة في أدنى وقت.
+- **معالجة تنسيق الكابل:** تم تحديثه لاستخدام تنسيق الكابل الجديد (`{"t": "i", "i": uri}` لـ IRIs، و `{"t": "l", "v": value}` للمفردات، و `{"t": "r", "r": {...}}` للاثلاثيات المقتبسة).
+- **دعم الرسم البياني المسمى:** خيار جديد `--graph`.
+
+### `tg-set-tool`
+
+- **نوع أداة جديد:** `row-embeddings-query` للبحث الدلالي عن فهارس البيانات المهيكلة.
+- **خيارات جديدة:** `--schema-name` و `--index-name` و `--limit` لتكوين أدوات استعلام تضمينات الصفوف.
+
+### `tg-show-tools`
+
+- يعرض نوع الأداة الجديد `row-embeddings-query` مع حقول `schema-name` و `index-name` و `limit`.
+
+### `tg-load-knowledge`
+
+- **إعداد التقارير عن التقدم:** الآن يحسب ويسجل عدد ثلاثيات وسياقات الكيانات التي تم تحميلها لكل ملف بشكل إجمالي.
+- **تحديث تنسيق المصطلح:** تتضمن سياقات الكيانات الآن تنسيق المصطلح الجديد (`{"t": "i", "i": uri}`) بدلاً من تنسيق القيمة القديم (`{"v": entity, "e": True}`).
+
+---
+
+## تغييرات مدمرة
+
+- **تغيير التسمية:** تم تغيير اسم مخطط `Value` إلى `Term` في جميع أنحاء النظام (PR #622). وهذا يؤثر على الأدوات التي تتفاعل مع مخزن الرسم البياني والتي تستخدم تنسيق الكابل الجديد. يستخدم التنسيق الجديد `{"t": "i", "i": uri}` لـ IRIs و `{"t": "l", "v": value}` للمفردات، بدلاً من التنسيق القديم `{"v": ..., "e": ...}`.
+- **`tg-invoke-objects-query` تم تغيير الاسم** إلى `tg-invoke-rows-query`.
+- تم حذف `tg-load-pdf` و `tg-load-text`.

docs/cli-changes-v1.8-to-v2.1.es.md

@@ -0,0 +1,112 @@
+# Cambios en la CLI: v1.8 a v2.1
+
+## Resumen
+
+La CLI (`trustgraph-cli`) tiene importantes adiciones centradas en tres temas:
+**explicabilidad/origen**, **acceso a embeddings** y **consultas en el grafo**.
+Se eliminaron dos herramientas heredadas, una se renombró y varias herramientas existentes
+adquirieron nuevas capacidades.
+
+---
+
+## Nuevas Herramientas CLI
+
+### Explicabilidad y Origen
+
+| Comando | Descripción |
+|---------|-------------|
+| `tg-list-explain-traces` | Lista todas las sesiones de explicabilidad (GraphRAG y Agent) en una colección, mostrando los IDs de sesión, tipo, texto de la pregunta y marcas de tiempo. |
+| `tg-show-explain-trace` | Muestra la traza completa de explicabilidad para una sesión. Para GraphRAG: Etapas de Pregunta, Exploración, Enfoque, Síntesis. Para Agent: Etapas de Sesión, Iteraciones (pensamiento/acción/observación), Respuesta Final. Detecta automáticamente el tipo de traza. Soporta la opción `--show-provenance` para rastrear los bordes de vuelta a los documentos originales. |
+| `tg-show-extraction-provenance` | Dados un ID de documento, recorre la cadena de origen: Documento -> Páginas -> Bloques -> Bordes, utilizando las relaciones `prov:wasDerivedFrom`. Soporta las opciones `--show-content` y `--max-content`. |
+
+### Embeddings
+
+| Comando | Descripción |
+|---------|-------------|
+| `tg-invoke-embeddings` | Convierte texto en un embedding vectorial a través del servicio de embeddings. Acepta uno o más entradas de texto, devuelve vectores como listas de flotantes. |
+| `tg-invoke-graph-embeddings` | Consulta entidades del grafo por similitud de texto utilizando embeddings vectoriales. Devuelve las entidades coincidentes con puntuaciones de similitud. |
+| `tg-invoke-document-embeddings` | Consulta fragmentos de documentos por similitud de texto utilizando embeddings vectoriales. Devuelve los IDs de fragmentos coincidentes con puntuaciones de similitud. |
+| `tg-invoke-row-embeddings` | Consulta filas de datos estructurados por similitud de texto en campos indexados. Devuelve las filas coincidentes con valores de índice y puntuaciones. Requiere `--schema-name` y soporta `--index-name`. |
+
+### Consultas en el grafo
+
+| Comando | Descripción |
+|---------|-------------|
+| `tg-query-graph` | Consulta basada en patrones para el almacén de triples. A diferencia de `tg-show-graph` (que muestra todo), esto permite consultas selectivas para cualquier combinación de sujeto, predicado, objeto y grafo. Detecta automáticamente los tipos de valor: IRIs (`http://...`, `urn:...`, `<...>`), triples anclados (`<<s p o>>`), y literales. |
+| `tg-get-document-content` | Recupera el contenido del documento de la biblioteca por ID de documento. Puede mostrar en un archivo o en stdout, maneja tanto contenido de texto como binario. |
+
+---
+
+## Herramientas CLI eliminadas
+
+| Comando | Notas |
+|---------|-------|
+| `tg-load-pdf` | Eliminado. La carga de documentos ahora se maneja a través de la biblioteca/pipeline de procesamiento. |
+| `tg-load-text` | Eliminado. La carga de documentos ahora se maneja a través de la biblioteca/pipeline de procesamiento. |
+
+---
+
+## Herramientas CLI renombradas
+
+| Nombre antiguo | Nombre nuevo | Notas |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | Refleja el cambio de terminología de "objetos" a "filas" para datos estructurados. |
+
+---
+
+## Cambios Significativos en Herramientas Existentes
+
+### `tg-invoke-graph-rag`
+
+- **Soporte de explicabilidad**: Ahora soporta una tubería de explicabilidad de 4 etapas (Pregunta, Fundamentación/Exploración, Enfoque, Síntesis) con visualización de eventos de origen en línea.
+- **Streaming**: Utiliza el streaming de WebSocket para la salida en tiempo real.
+- **Rastreo de origen**: Puede rastrear bordes seleccionados de vuelta a los documentos originales a través de la reificación y cadenas `prov:wasDerivedFrom`.
+- Crecer de ~30 líneas a ~760 líneas para acomodar la tubería de explicabilidad completa.
+
+### `tg-invoke-document-rag`
+
+- **Soporte de explicabilidad**: Añadido el modo `question_explainable()` que transmite las respuestas de RAG de Documento con eventos de origen en línea (etapas de Pregunta, Fundamentación, Exploración, Síntesis).
+
+### `tg-invoke-agent`
+
+- **Soporte de explicabilidad**: Añadido el modo `question_explainable()` que muestra los eventos de origen en línea durante la ejecución del agente (etapas de Pregunta, Análisis, Conclusión, AgentThought, AgentObservation, AgentAnswer).
+- El modo verboso muestra las transmisiones de pensamentos/observaciones con prefijos de emojis.
+
+### `tg-show-graph`
+
+- **Modo de streaming**: Ahora utiliza `triples_query_stream()` con tamaños de lote configurables para un tiempo de primer resultado más bajo y una menor sobrecarga de memoria.
+- **Soporte de grafo nombrado**: Nueva opción `--graph` de filtro. Reconoce grafos nombrados:
+  - Grafo predeterminado (vacío): Hechos de conocimiento básicos
+  - `urn:graph:source`: Origen de extracción
+  - `urn:graph:retrieval`: Explicabilidad en tiempo de consulta
+- **Mostrar columna de grafo**: Nueva bandera `--show-graph` para mostrar el grafo nombrado para cada triple.
+- **Límites configurables**: Nuevas opciones `--limit` y `--batch-size`.
+
+### `tg-graph-to-turtle`
+
+- **Soporte de RDF-star**: Ahora maneja triples anclados (reificación de RDF-star).
+- **Modo de streaming**: Utiliza streaming para un tiempo de procesamiento más rápido.
+- **Manejo del formato de cable**: Actualizado para utilizar el nuevo formato de cable (`{"t": "i", "i": uri}` para IRIs, `{"t": "l", "v": value}` para literales, `{"t": "r", "r": {...}}` para triples anclados)
+- **Soporte de grafo nombrado**: Nueva opción `--graph` de filtro.
+
+### `tg-set-tool`
+
+- **Nuevo tipo de herramienta**: `row-embeddings-query` para búsqueda semántica en índices de datos estructurados.
+- **Nuevas opciones**: `--schema-name`, `--index-name`, `--limit` para configurar herramientas de consulta de embeddings de fila.
+
+### `tg-show-tools`
+
+- Muestra el nuevo tipo de herramienta `row-embeddings-query` con sus campos `schema-name`, `index-name` y `limit`.
+
+### `tg-load-knowledge`
+
+- **Informes de progreso**: Ahora cuenta y reporta los triples y contextos de entidad cargados por archivo y en total.
+- **Actualización del formato de término**: Los contextos de entidad ahora utilizan el nuevo formato de término (`{"t": "i", "i": uri}`) en lugar del formato de valor antiguo (`{"v": ..., "e": ...}`).
+
+---
+
+## Cambios de rompimiento
+
+- **Cambio de terminología**: El esquema `Value` se renombró a `Term` en todo el sistema (PR #622). Esto afecta al formato de cable utilizado por las herramientas CLI que interactúan con el almacén de grafos. El nuevo formato utiliza `{"t": "i", "i": uri}` para IRIs y `{"t": "l", "v": value}` para literales, reemplazando el formato antiguo `{"v": ..., "e": ...}`.
+- **`tg-invoke-objects-query` renombrado** a `tg-invoke-rows-query`.
+- **`tg-load-pdf` y `tg-load-text` eliminados**.

docs/cli-changes-v1.8-to-v2.1.he.md

@@ -0,0 +1,111 @@
+# שינויים ב-CLI: מ-v1.8 ל-v2.1
+
+## סיכום
+
+ה-CLI (`trustgraph-cli`) כולל שינויים משמעותיים המתמקדים בשלוש תחומים:
+**הסבר/מקוריות**, **גישה להטמעות**, ו**שאילתות גרף**.
+שני כלי ישנים הוסרו, אחד שונה שמו, ורבים מכלי קיימים קיבלו יכולות חדשות.
+
+---
+
+## כלים חדשים ב-CLI
+
+### הסבר ומקוריות
+
+| פקודה | תיאור |
+|---|---|
+| `tg-list-explain-traces` | רשימת כל סשנים של הסבר (GraphRAG ו-Agent) בקולקציה, המציגים מזהי סשן, סוג, טקסט שאלה, וחותמות זמן. |
+| `tg-show-explain-trace` | מציג את הרשומת ההסבר המלאה לסשן. עבור GraphRAG: שלב השאלה, החקירה, ההתמקדות, והסינתזה. עבור Agent: שלב הסשן, איטרציות (מחשבה/פעולה/תצפית), התשובה הסופית. מזהה אוטומטית את סוג הרשומת. תומך באפשרות `--show-provenance` כדי לעקוב אחר קצוות בחזרה לתיקי המסמך המקוריים. |
+| `tg-show-extraction-provenance` | בהתבסס על מזהה מסמך, עובר על שרשרת המקוריות: מסמך -> עמודים -> קטעים -> קצוות, תוך שימוש ביחסים של `prov:wasDerivedFrom`. תומך באפשרויות `--show-content` ו-`--max-content`. |
+
+### הטמעות
+
+| פקודה | תיאור |
+|---|---|
+| `tg-invoke-embeddings` | ממיר טקסט לייצוג וקטורי באמצעות שירות ההטמעות. מקבל אחד או יותר של קלדי טקסט, ומחזיר וקטורים כרשימות של מספרים ממשיים. |
+| `tg-invoke-graph-embeddings` | שאילת ישויות גרף באמצעות טקסט על סמך ייצוגים וקטוריים. מחזיר ישויות תואמות עם ציוני דמיון. |
+| `tg-invoke-document-embeddings` | שאילת קטעי מסמך באמצעות טקסט על סמך ייצוגים וקטוריים. מחזיר מזהי קטעים תואמים עם ציוני דמיון. |
+| `tg-invoke-row-embeddings` | שאילת שורות של נתונים מובנים על סמך טקסט על שדות מסומנים. מחזיר שורות תואמות עם ערכי אינדקס וציון. דורש `--schema-name` ומקבל תמיכה ב-`--index-name`. |
+
+### שאילתות גרף
+
+| פקודה | תיאור |
+|---|---|
+| `tg-query-graph` | שאילתת אחסון טריפלים מבוססת תבנית. בניגוד ל-`tg-show-graph` (שמציג הכל), זה מאפשר שאילתות סלקטיביות באמצעות כל שילוב של נושא, תחביר, אובייקט וגרף. מזהה באופן אוטומטי סוגי ערכים: IRI (`http://...`, `urn:...`, `<...>`), טריפלים מוטבעים (`<<s p o>>`), וערכים. |
+| `tg-get-document-content` | אחזר תוכן מסמך מהספרייה על סמך מזהה מסמך. יכול להפיק לתיק או ל-stdout, ומטפל גם בתוכן טקסט וגם בתוכן בינארי. |
+
+---
+
+## כלים שהוסרו ב-CLI
+
+| פקודה | הערות |
+|---|---|
+| `tg-load-pdf` | הוסר. טעינת מסמך מטופלת כעת באמצעות הספריה/צינור העיבוד. |
+| `tg-load-text` | הוסר. טעינת מסמך מטופלת כעת באמצעות הספריה/צינור העיבוד. |
+
+---
+
+## שמות כלים חדשים
+
+| שם ישן | שם חדש | הערות |
+|---|---|---|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | משקף את השינוי בשם המושג מ"אובייקטים" ל"שורות" עבור נתונים מובנים. |
+
+---
+
+## שינויים משמעותיים בכלים קיימים
+
+### `tg-invoke-graph-rag`
+
+- **תמיכה בהסבר**: תומך כעת בפונקציית הסבר של 4 שלבים (שאלה, חקירה/התמקדות, סינתזה) עם הצגת אירועי מקוריות מקומיים.
+- **זרם**: משתמש בזרם WebSocket עבור פלט בזמן אמת.
+- **מעקב אחר מקוריות**: יכול לעקוב אחר קצוות שנבחרו בחזרה למסמכים מקוריים באמצעות ריפוי ושרשראות של `prov:wasDerivedFrom`.
+- גדל מ-~30 שורות ל-~760 שורות כדי להסב את כל פונקציית ההסבר.
+
+### `tg-invoke-document-rag`
+
+- **תמיכה בהסבר**: הוספה של מצב `question_explainable()` המפיק תגובות של RAG עבור מסמכים עם אירועי מקוריות מקומיים (שלבי שאלה, חקירה, התמקדות, סינתזה).
+
+### `tg-invoke-agent`
+
+- **תמיכה בהסבר**: הוספת מצב `question_explainable()` המציג אירועי מקוריות במהלך ביצוע סוכן (שלבי שאלה, ניתוח, מסקנה, AgentThought, AgentObservation, AgentAnswer).
+- מצב מפורט מציג זרימות של מחשבה/תצפית עם קידומים של סמלים.
+
+### `tg-show-graph`
+
+- **מצב זרימה**: משתמש כעת ב-`triples_query_stream()` עם גדלי אצווה מוגדרים כדי להפחית את זמן התגובה הראשון ולהקטין את צריכת הזיכרון.
+- **תמיכה בגרף משמות**: אפשרות חדשה `--graph`. מזהה גרפים משמות:
+  - גרף ברירת מחדל (ריק): עובדות ידע בסיסיות
+  - `urn:graph:source`: מקוריות של הסתרה
+  - `urn:graph:retrieval`: הסבר בזמן שאילתה
+- **הצגת עמוד גרף**: תגית חדשה `--show-graph` להצגת הגרף המשמות לכל טריפל.
+- **גבולות ניתנים להתאמה**: אפשרויות חדשות `--limit` ו-`--batch-size`.
+
+### `tg-graph-to-turtle`
+
+- **תמיכה ב-RDF-star**: מטפל בטריפלים מוטבעים (ריפוי RDF-star).
+- **מצב זרימה**: משתמש בזרם להפחתת זמן התגובה הראשון.
+- **טיפול בפורמט חוטי**: מעודכן כדי להשתמש בפורמט החוט החדש (`{"t": "i", "i": uri}` עבור IRI, `{"t": "l", "v": value}` עבור ערכים, `{"t": "r", "r": {...}}` עבור טריפלים מוטבעים).
+- **תמיכה בגרף משמות**: אפשרות חדשה `--graph`.
+
+### `tg-set-tool`
+
+- **סוג כלי חדש**: `row-embeddings-query` לשאילתות סמנטיות על אינדקסים של נתונים מובנים.
+- **אפשרויות חדשות**: `--schema-name`, `--index-name`, `--limit` כדי להגדיר כלים לשאילתות הטמעות שורות.
+
+### `tg-show-tools`
+
+- מציג את סוג הכלי החדש `row-embeddings-query` עם השדות שלו `schema-name`, `index-name`, ו-`limit`.
+
+### `tg-load-knowledge`
+
+- **דיווח התקדמות**: סופר ומדווח על מספר הטרפולים ועל הקטעי של ישויות המועמסים, לפי קובץ וגם בסך הכל.
+- **עדכון פורמט מונח**: קטעי ישויות משתמשים כעת בפורמט המונח החדש (`{"t": "i", "i": uri}`) במקום בפורמט הערך הישן (`{"v": entity, "e": True}`).
+
+---
+
+## שינויים שבורים
+
+- **שינוי שמות**: הסכימה `Value` שונתה לשם `Term` בכל המערכת (PR #622). זה משפיע על הציוד שמשתמש בכלי ה-CLI שמתקשר עם מאגר הגרף. הפורמט החדש משתמש ב-`{"t": "i", "i": uri}` עבור IRI ו-`{"t": "l", "v": value}` עבור ערכים, במקום הפורמט הישן `{"v": ..., "e": ...}`.
+- **השינוי בשם של `tg-invoke-objects-query`** ל- `tg-invoke-rows-query`.
+- **הוסרו `tg-load-pdf` ו-`tg-load-text`.

docs/cli-changes-v1.8-to-v2.1.hi.md

@@ -0,0 +1,111 @@
+# CLI में परिवर्तन: v1.8 से v2.1
+
+## सारांश
+
+CLI (`trustgraph-cli`) में तीन मुख्य क्षेत्रों पर ध्यान केंद्रित किए गए महत्वपूर्ण परिवर्धन शामिल हैं:
+**व्याख्यात्मकता/उत्पत्ति, एम्बेडिंग एक्सेस, और ग्राफ़ क्वेरी।**
+दो पुरानी उपकरण हटा दिए गए थे, एक का नाम बदल दिया गया, और कई मौजूदा उपकरणों में नई क्षमताएं जोड़ी गईं।
+
+---
+
+## नए CLI उपकरण
+
+### व्याख्यात्मकता और उत्पत्ति
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-list-explain-traces` | एक संग्रह में सभी व्याख्या सत्रों (GraphRAG और एजेंट) की सूची, जिसमें सत्र आईडी, प्रकार, प्रश्न पाठ और टाइमस्टैम्प शामिल हैं। |
+| `tg-show-explain-trace` | किसी सत्र के लिए पूरी व्याख्यात्मक ट्रेस प्रदर्शित करता है। GraphRAG के लिए: प्रश्न, खोज, ध्यान केंद्रित, संश्लेषण चरण। एजेंट के लिए: सत्र, पुनरावृत्तियाँ (सोच/क्रिया/अवलोकन), अंतिम उत्तर। स्वचालित रूप से ट्रेस प्रकार का पता लगाता है। `--show-provenance` का उपयोग करके स्रोत दस्तावेजों तक किनारों को ट्रेस करने का समर्थन करता है। |
+| `tg-show-extraction-provenance` | एक दस्तावेज़ आईडी दिए जाने पर, `prov:wasDerivedFrom` संबंधों का उपयोग करके उत्पत्ति श्रृंखला को पार करता है: दस्तावेज़ -> पृष्ठ -> खंड -> किनारे। `--show-content` और `--max-content` विकल्पों का समर्थन करता है। |
+
+### एम्बेडिंग
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-invoke-embeddings` | एम्बेडिंग सेवा के माध्यम से टेक्स्ट को वेक्टर एम्बेडिंग में परिवर्तित करता है। एक या अधिक टेक्स्ट इनपुट स्वीकार करता है, और फ़्लोट की सूची के रूप में वेक्टर लौटाता है। |
+| `tg-invoke-graph-embeddings` | वेक्टर एम्बेडिंग का उपयोग करके ग्राफ संस्थाओं को क्वेरी करता है। मिलान संस्थाओं और समानता स्कोर लौटाता है। |
+| `tg-invoke-document-embeddings` | वेक्टर एम्बेडिंग का उपयोग करके दस्तावेज़ खंडों को क्वेरी करता है। मिलान खंड आईडी और समानता स्कोर लौटाता है। |
+| `tg-invoke-row-embeddings` | इंडेक्स किए गए फ़ील्ड पर टेक्स्ट समानता का उपयोग करके संरचित डेटा पंक्तियों को क्वेरी करता है। मिलान पंक्तियों और स्कोर लौटाता है। `--schema-name` और `--index-name` का समर्थन करता है। |
+
+### ग्राफ़ क्वेरी
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-query-graph` | पैटर्न-आधारित ट्रिपल स्टोर क्वेरी। `tg-show-graph` (जो सब कुछdumps करता है) के विपरीत, यह किसी भी संयोजन के विषय, विधेय, वस्तु और ग्राफ़ द्वारा चयनशील क्वेरी की अनुमति देता है। स्वचालित रूप से मूल्य प्रकार का पता लगाता है: IRI (`http://...`, `urn:...`, `<...>`), उद्धृत ट्रिपल (`<<s p o>>`), और अक्षर। |
+| `tg-get-document-content` | लाइब्रेरी से दस्तावेज़ आईडी द्वारा दस्तावेज़ सामग्री प्राप्त करता है। फ़ाइल या stdout पर आउटपुट कर सकता है, और टेक्स्ट और बाइनरी सामग्री दोनों को संभालता है। |
+
+---
+
+## हटाए गए CLI उपकरण
+
+| कमांड | नोट्स |
+|---------|-------|
+| `tg-load-pdf` | हटा दिया गया। दस्तावेज़ लोडिंग अब लाइब्रेरी/प्रसंस्करण पाइपलाइन के माध्यम से संभाली जाती है। |
+| `tg-load-text` | हटा दिया गया। दस्तावेज़ लोडिंग अब लाइब्रेरी/प्रसंस्करण पाइपलाइन के माध्यम से संभाली जाती है। |
+
+---
+
+## नाम बदले गए CLI उपकरण
+
+| पुराना नाम | नया नाम | नोट्स |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | संरचित डेटा के लिए "ऑब्जेक्ट" से "पंक्ति" के शब्दावली में बदलाव को दर्शाता है। |
+
+---
+
+## मौजूदा उपकरणों में महत्वपूर्ण परिवर्तन
+
+### `tg-invoke-graph-rag`
+
+- **व्याख्यात्मकता समर्थन**: 4-चरण व्याख्यात्मक पाइपलाइन (प्रश्न, ग्राउंडिंग/खोज, ध्यान केंद्रित, संश्लेषण) का समर्थन करता है जिसमें इनलाइन उत्पत्ति घटना प्रदर्शन भी शामिल है।
+- **स्ट्रीमिंग**: वास्तविक समय के आउटपुट के लिए WebSocket स्ट्रीमिंग का उपयोग करता है।
+- **उत्पत्ति ट्रेसिंग**: पुनरावर्तन और `prov:wasDerivedFrom` श्रृंखलाओं के माध्यम से चयनित किनारों को स्रोत दस्तावेजों तक ट्रेस कर सकता है।
+- ~30 पंक्तियों से ~760 पंक्तियों तक बढ़ गया है ताकि पूरे व्याख्यात्मक पाइपलाइन को समायोजित किया जा सके।
+
+### `tg-invoke-document-rag`
+
+- **व्याख्यात्मकता समर्थन**: `question_explainable()` मोड जोड़ा गया जो दस्तावेज़ RAG प्रतिक्रियाओं को इनलाइन उत्पत्ति घटनाओं (प्रश्न, ग्राउंडिंग, खोज, संश्लेषण चरण) के साथ प्रवाहित करता है।
+
+### `tg-invoke-agent`
+
+- **व्याख्यात्मकता समर्थन**: `question_explainable()` मोड जोड़ा गया जो एजेंट निष्पादन के दौरान इनलाइन उत्पत्ति घटनाओं (प्रश्न, विश्लेषण, निष्कर्ष, एजेंटसोच, एजेंटअवलोकन, एजेंटउत्तर) को प्रदर्शित करता है।
+- वर्बोस मोड में, इमोजी उपसर्ग के साथ सोच/अवलोकन धाराओं को दिखाया जाता है।
+
+### `tg-show-graph`
+
+- **स्ट्रीमिंग मोड**: `triples_query_stream()` का उपयोग करता है जिसमें कम समय-से-पहले-परिणाम और कम मेमोरी ओवरहेड के लिए कॉन्फ़िगरेबल बैच आकार होते हैं।
+- **नाम वाले ग्राफ़ समर्थन**: नया `--graph` फ़िल्टर विकल्प। निम्नलिखित नाम वाले ग्राफ़ को पहचानता है:
+  - डिफ़ॉल्ट ग्राफ़ (खाली): मुख्य ज्ञान तथ्य
+  - `urn:graph:source`: निष्कर्षण उत्पत्ति
+  - `urn:graph:retrieval`: क्वेरी-समय व्याख्यात्मकता
+- **ग्राफ़ कॉलम दिखाना**: `--show-graph` ध्वज जोड़ा गया।
+- **कॉन्फ़िगरेबल सीमाएँ**: नए `--limit` और `--batch-size` विकल्प।
+
+### `tg-graph-to-turtle`
+
+- **RDF-स्टार समर्थन**: उद्धृत ट्रिपल (RDF-स्टार पुनरावर्तन) को संभालता है।
+- **स्ट्रीमिंग मोड**: कम समय-से-पहले-प्रसंस्करण के लिए स्ट्रीमिंग का उपयोग करता है।
+- **वायर फॉर्मेट हैंडलिंग**: नई वायर फॉर्मेट (`{"t": "i", "i": uri}` के लिए IRI, `{"t": "l", "v": value}` के लिए अक्षर, `{"t": "r", "r": {...}}` के लिए उद्धृत ट्रिपल) का उपयोग करने के लिए अपडेट किया गया है।
+- **नाम वाले ग्राफ़ समर्थन**: नया `--graph` फ़िल्टर विकल्प।
+
+### `tg-set-tool`
+
+- **नया उपकरण प्रकार**: संरचित डेटा सूचकांकों पर अर्थपूर्ण खोज के लिए `row-embeddings-query`।
+- **नया विकल्प**: संरचित डेटा क्वेरी टूल के लिए `--schema-name`, `--index-name`, `--limit` विकल्प जोड़े गए।
+
+### `tg-show-tools`
+
+- `row-embeddings-query` के नए उपकरण प्रकार और उसके `schema-name`, `index-name` और `limit` फ़ील्ड को प्रदर्शित करता है।
+
+### `tg-load-knowledge`
+
+- **प्रगति रिपोर्टिंग**: प्रत्येक फ़ाइल और कुल में लोड किए गए ट्रिपल और संस्था संदर्भों की गणना और रिपोर्ट करता है।
+- **टर्म फॉर्मेट अपडेट**: संस्था संदर्भ अब नए टर्म फॉर्मेट (`{"t": "i", "i": uri}`) का उपयोग करते हैं, जबकि पुराने मूल्य फॉर्मेट (`{"v": entity, "e": True}`) का उपयोग किया जाता था।
+
+---
+
+## ब्रेकिंग परिवर्तन
+
+- **शब्दावली का नाम बदलना**: `Value` स्कीम को पूरे सिस्टम में `Term` नाम दिया गया है (PR #622)। यह CLI टूल के लिए जो ग्राफ स्टोर के साथ इंटरैक्ट करते हैं, उनके वायर फॉर्मेट को प्रभावित करता है। नया फॉर्मेट `{"t": "i", "i": uri}` IRI के लिए और `{"t": "l", "v": value}` अक्षर के लिए, पिछले `{"v": ..., "e": ...}` फॉर्मेट के स्थान पर उपयोग करता है।
+- **`tg-invoke-objects-query` को `tg-invoke-rows-query` में नाम बदला गया**।
+- **`tg-load-pdf` और `tg-load-text` हटा दिए गए**।

docs/cli-changes-v1.8-to-v2.1.pt.md

@@ -0,0 +1,112 @@
+# Alterações na CLI: da v1.8 para v2.1
+
+## Resumo
+
+A CLI (`trustgraph-cli`) possui adições significativas focadas em três temas:
+**explicabilidade/proveniência**, **acesso a embeddings** e **consulta de grafos**.
+Duas ferramentas legadas foram removidas, uma foi renomeada e várias ferramentas existentes
+adquiriram novas funcionalidades.
+
+--
+
+## Novas Ferramentas da CLI
+
+### Explicabilidade e Proveniência
+
+| Comando | Descrição |
+|---------|-------------|
+| `tg-list-explain-traces` | Lista todas as sessões de explicabilidade (GraphRAG e Agent) em uma coleção, mostrando IDs de sessão, tipo, texto da pergunta e carimbos de data/hora. |
+| `tg-show-explain-trace` | Exibe o rastreamento completo de explicabilidade para uma sessão. Para GraphRAG: Estágios de Pergunta, Exploração, Foco, Síntese. Para Agent: Sessão, Iterações (pensamento/ação/observação), Resposta Final. Detecta automaticamente o tipo de rastreamento. Suporta `--show-provenance` para rastrear arestas de volta para documentos de origem. |
+| `tg-show-extraction-provenance` | Dado um ID de documento, percorre a cadeia de proveniência: Documento -> Páginas -> Trechos -> Arestas, usando relacionamentos `prov:wasDerivedFrom`. Suporta opções `--show-content` e `--max-content`. |
+
+### Embeddings
+
+| Comando | Descrição |
+|---------|-------------|
+| `tg-invoke-embeddings` | Converte texto em um embedding vetorial por meio do serviço de embeddings. Aceita uma ou mais entradas de texto, retorna vetores como listas de floats. |
+| `tg-invoke-graph-embeddings` | Consulta entidades de grafo por similaridade de texto usando embeddings vetoriais. Retorna entidades correspondentes com pontuações de similaridade. |
+| `tg-invoke-document-embeddings` | Consulta trechos de documentos por similaridade de texto usando embeddings vetoriais. Retorna IDs de trechos correspondentes com pontuações de similaridade. |
+| `tg-invoke-row-embeddings` | Consulta linhas de dados estruturados por similaridade de texto em campos indexados. Retorna linhas correspondentes com valores de índice e pontuações. Requer `--schema-name` e suporta `--index-name`. |
+
+### Consulta de Grafos
+
+| Comando | Descrição |
+|---------|-------------|
+| `tg-query-graph` | Consulta de grafo baseada em padrões. Diferentemente de `tg-show-graph` (que despeja tudo), isso permite consultas seletivas por qualquer combinação de sujeito, predicado, objeto e grafo. Detecta automaticamente os tipos de valor: IRIs (`http://...`, `urn:...`, `<...>`), triplas entre aspas (`<<s p o>>`) e literais. |
+| `tg-get-document-content` | Recupera o conteúdo do documento da biblioteca por ID do documento. Pode ser direcionado para um arquivo ou stdout, lida com conteúdo de texto e binário. |
+
+--
+
+## Ferramentas da CLI Removidas
+
+| Comando | Notas |
+|---------|-------|
+| `tg-load-pdf` | Removido. O carregamento de documentos é agora tratado por meio do pipeline de biblioteca/processamento. |
+| `tg-load-text` | Removido. O carregamento de documentos é agora tratado por meio do pipeline de biblioteca/processamento. |
+
+--
+
+## Ferramentas da CLI Renomeadas
+
+| Nome Antigo | Novo Nome | Notas |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | Reflete a alteração de terminologia de "objetos" para "linhas" para dados estruturados. |
+
+--
+
+## Mudanças Significativas em Ferramentas Existentes
+
+### `tg-invoke-graph-rag`
+
+**Suporte para explicabilidade**: Agora suporta um pipeline de explicabilidade de 4 etapas (Pergunta, Fundamentação/Exploração, Foco, Síntese) com exibição inline de eventos de rastreabilidade.
+**Streaming**: Utiliza streaming WebSocket para saída em tempo real.
+**Rastreabilidade**: Pode rastrear arestas selecionadas de volta para documentos de origem por meio de reificação e cadeias `prov:wasDerivedFrom`.
+Cresceu de ~30 linhas para ~760 linhas para acomodar o pipeline completo de explicabilidade.
+
+### `tg-invoke-document-rag`
+
+**Suporte para explicabilidade**: Adicionado modo `question_explainable()` que transmite respostas do Document RAG com eventos de rastreabilidade inline (etapas de Pergunta, Fundamentação, Exploração, Síntese).
+
+### `tg-invoke-agent`
+
+**Suporte para explicabilidade**: Adicionado modo `question_explainable()` que exibe eventos de rastreabilidade inline durante a execução do agente (etapas de Pergunta, Análise, Conclusão, AgentThought, AgentObservation, AgentAnswer).
+O modo verboso exibe fluxos de pensamento/observação com prefixos de emoji.
+
+### `tg-show-graph`
+
+**Modo de streaming**: Agora usa `triples_query_stream()` com tamanhos de lote configuráveis para um tempo de primeiro resultado menor e menor sobrecarga de memória.
+**Suporte para grafos nomeados**: Nova opção de filtro `--graph`. Reconhece grafos nomeados:
+  Grafo padrão (vazio): Fatos de conhecimento principais
+  `urn:graph:source`: Rastreabilidade de extração
+  `urn:graph:retrieval`: Explicabilidade no momento da consulta
+**Mostrar coluna do grafo**: Nova flag `--show-graph` para exibir o grafo nomeado para cada tripla.
+**Limites configuráveis**: Novas opções `--limit` e `--batch-size`.
+
+### `tg-graph-to-turtle`
+
+**Suporte para RDF-star**: Agora lida com triplas citadas (reificação RDF-star).
+**Modo de streaming**: Utiliza streaming para um tempo de processamento inicial menor.
+**Manipulação de formato de fio**: Atualizado para usar o novo formato de fio de termos (`{"t": "i", "i": uri}` para IRIs, `{"t": "l", "v": value}` para literais, `{"t": "r", "r": {...}}` para triplas citadas).
+**Suporte para grafos nomeados**: Nova opção de filtro `--graph`.
+
+### `tg-set-tool`
+
+**Novo tipo de ferramenta**: `row-embeddings-query` para pesquisa semântica em índices de dados estruturados.
+**Novas opções**: `--schema-name`, `--index-name`, `--limit` para configurar ferramentas de consulta de incorporações de linhas.
+
+### `tg-show-tools`
+
+Exibe o novo tipo de ferramenta `row-embeddings-query` com seus campos `schema-name`, `index-name` e `limit`.
+
+### `tg-load-knowledge`
+
+**Relatório de progresso**: Agora conta e relata triplas e contextos de entidade carregados por arquivo e no total.
+**Atualização do formato de termo**: Os contextos de entidade agora usam o novo formato de Termo (`{"t": "i", "i": uri}`) em vez do formato de Valor antigo (`{"v": entity, "e": True}`).
+
+--
+
+## Mudanças Incompatíveis
+
+**Renomeação de terminologia**: O esquema `Value` foi renomeado para `Term` em todo o sistema (PR #622). Isso afeta o formato de fio usado por ferramentas de linha de comando que interagem com o armazenamento de grafo. O novo formato usa `{"t": "i", "i": uri}` para IRIs e `{"t": "l", "v": value}` para literais, substituindo o formato antigo `{"v": ..., "e": ...}`.
+**`tg-invoke-objects-query` renomeado** para `tg-invoke-rows-query`.
+**`tg-load-pdf` e `tg-load-text` removidos**.

docs/cli-changes-v1.8-to-v2.1.ru.md

@@ -0,0 +1,111 @@
+# Изменения в CLI: v1.8 to v2.1
+
+## Обзор
+
+CLI (`trustgraph-cli`) включает в себя значительные дополнения, ориентированные на три основные темы:
+**объяснимость/происхождение**, **доступ к вложениям** и **запросы к графу**.
+Два устарелых инструмента были удалены, один был переименован, а несколько существующих инструментов получили новые возможности.
+
+---
+
+## Новые инструменты CLI
+
+### Объяснимость и происхождение
+
+| Команда | Описание |
+|---------|-------------|
+| `tg-list-explain-traces` | Перечисляет все сеансы объяснения (GraphRAG и Agent) в коллекции, показывая идентификаторы сеансов, тип, текст вопроса и временные метки. |
+| `tg-show-explain-trace` | Отображает полный трас сеанса объяснения. Для GraphRAG: этапы Вопрос, Исследование, Фокусировка, Синтез. Для Agent: этапы Сеанс, Итерации (мысль/действие/наблюдение), Конечный ответ. Автоматически определяет тип траса. Поддерживает опцию `--show-provenance` для отслеживания связей обратно к исходным документам. |
+| `tg-show-extraction-provenance` | Принимает идентификатор документа, проходящего по цепочке происхождения: Документ -> Страницы -> Блоки -> Связи, используя отношения `prov:wasDerivedFrom`. Поддерживает опции `--show-content` и `--max-content`. |
+
+### Вложения
+
+| Команда | Описание |
+|---------|-------------|
+| `tg-invoke-embeddings` | Преобразует текст в векторное представление посредством сервиса вложений. Принимает один или несколько текстовых входных данных, возвращает векторы в виде списков чисел с плавающей точкой. |
+| `tg-invoke-graph-embeddings` | Запрашивает сущности графа по текстовому сходству с использованием векторных представлений. Возвращает соответствующие сущности со значениями сходства. |
+| `tg-invoke-document-embeddings` | Запрашивает текстовые блоки документа по текстовому сходству с использованием векторных представлений. Возвращает идентификаторы соответствующих текстовых блоков со значениями сходства. |
+| `tg-invoke-row-embeddings` | Запрашивает структурированные данные строк по текстовому сходству в индексированных полях. Возвращает соответствующие строки со значениями индексов и значениями сходства. Требует опции `--schema-name` и поддерживает `--index-name`. |
+
+### Запросы к графу
+
+| Команда | Описание |
+|---------|-------------|
+| `tg-query-graph` | Запрос хранилища троек на основе шаблона. В отличие от `tg-show-graph` (который отображает всё), это позволяет осуществлять выборочные запросы с использованием любой комбинации субъекта, предиката, объекта и графа. Автоматически определяет типы значений: URI (`http://...`, `urn:...`, `<...>`), закодированные тройки (`<<s p o>>`) и литералы. |
+| `tg-get-document-content` | Получает содержимое документа из библиотеки по идентификатору документа. Может отображать в файл или stdout, обрабатывает как текст, так и двоичные данные. |
+
+---
+
+## Удаленные инструменты CLI
+
+| Команда | Примечания |
+|---------|-------|
+| `tg-load-pdf` | Удалено. Загрузка документов теперь осуществляется через библиотеку/процессную цепочку. |
+| `tg-load-text` | Удалено. Загрузка документов теперь осуществляется через библиотеку/процессную цепочку. |
+
+---
+
+## Переименованные инструменты CLI
+
+| Старое имя | Новое имя | Примечания |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | Отражает изменение терминологии с "объектов" на "строки" для структурированных данных. |
+
+---
+
+## Значительные изменения существующих инструментов
+
+### `tg-invoke-graph-rag`
+
+- **Поддержка объяснимости:** Поддерживает четырехэтапную пайплайн объяснения (Вопрос, Поиск/Исследование, Фокусировка, Синтез) с отображением событий происхождения.
+- **Стриминг:** Использует стриминг WebSocket для получения результатов в реальном времени.
+- **Отслеживание происхождения:** Может отслеживать выбранные связи обратно к исходным документам с использованием рефикации и цепочек `prov:wasDerivedFrom`.
+- Увеличился размер кода с ~30 строк до ~760 строк, чтобы вместить полный пайплайн объяснения.
+
+### `tg-invoke-document-rag`
+
+- **Поддержка объяснимости:** Добавлен режим `question_explainable()`, который отображает ответы RAG для документов со встроенными событиями происхождения (этапы Вопрос, Поиск, Исследование, Синтез).
+
+### `tg-invoke-agent`
+
+- **Поддержка объяснимости:** Добавлен режим `question_explainable()`, который отображает происхождение во время выполнения агента (этапы Вопрос, Анализ, Вывод, AgentThought, AgentObservation, AgentAnswer).
+- Режим "verbose" показывает потоки мыслей/наблюдений с префиксами эмодзи.
+
+### `tg-show-graph`
+
+- **Режим стриминга:** Теперь использует `triples_query_stream()` с настраиваемыми размерами пакетов для более быстрого получения первого результата и снижения использования памяти.
+- **Поддержка именованного графа:** Новая опция `--graph`. Распознает именованные графы:
+  - Основной граф (пустой): Основные факты знаний
+  - `urn:graph:source`: Происхождение извлечения
+  - `urn:graph:retrieval`: Объяснение в момент запроса
+- **Отображение столбца графа:** Ножная опция `--show-graph` для отображения именованного графа для каждой тройки.
+- **Конфигурируемые лимиты:** Новые опции `--limit` и `--batch-size`.
+
+### `tg-graph-to-turtle`
+
+- **Поддержка RDF-star:** Теперь обрабатывает закодированные тройки (рефикация RDF-star).
+- **Режим стриминга:** Использует стриминг для более быстрого получения первого результата.
+- **Обработка формата wire:** Обновлено для использования нового формата wire (`{"t": "i", "i": uri}` для URI, `{"t": "l", "v": value}` для литералов, `{"t": "r", "r": {...}}` для закодированных троек).
+- **Поддержка именованного графа:** Новая опция `--graph`.
+
+### `tg-set-tool`
+
+- **Новый тип инструмента:** `row-embeddings-query` для семантического поиска по индексированным структурированным данным.
+- **Новые опции:** `--schema-name`, `--index-name`, `--limit` для настройки инструментов запроса вложений строк.
+
+### `tg-show-tools`
+
+- Отображает новый тип инструмента `row-embeddings-query` с его полями `schema-name`, `index-name` и `limit`.
+
+### `tg-load-knowledge`
+
+- **Отчет о прогрессе:** Теперь считает и отображает количество загруженных троек и контекстов сущностей в файл и в целом.
+- **Обновление формата термина:** Контексты сущностей теперь используют новый формат термина (`{"t": "i", "i": uri}`) вместо старого формата значения (`{"v": ..., "e": ...}`).
+
+---
+
+## Разрывные изменения
+
+- **Переименование терминологии:** Схема `Value` была переименована в `Term` во всей системе (PR #622). Это влияет на формат wire, используемый инструментами CLI, взаимодействующими с хранилищем графов. Новый формат использует `{"t": "i", "i": uri}` для URI и `{"t": "l", "v": value}` для литералов, заменяя старый формат `{"v": ..., "e": ...}`.
+- **`tg-invoke-objects-query` переименовано** в `tg-invoke-rows-query`.
+- **`tg-load-pdf` и `tg-load-text` удалены**.

docs/cli-changes-v1.8-to-v2.1.sw.md

@@ -0,0 +1,115 @@
+**MAELEMAZO MAKUUUUU:**
+- Hifadhi FORMATI YOTE ya Markdown, vichungi, viungo na alama za HTML.
+- Usitafsiri code ndani ya apostrophe au makundi ya code.
+- Onyesho TU MAELEZO bila maelezo au maelezo.
+
+MAELEZO YA KUTAFSIRI:
+# Mabadiliko ya CLI: v1.8 hadi v2.1
+
+## Muhtasari
+
+CLI (`trustgraph-cli`) ina ongezeko kubwa, iliyoangazia vipande tatu:
+**ufafanuzi/asili,** **ufaa wa data,** na **utafutaji wa graphs.**
+Zochorwa zote, mojawapo ilibadilishwa, na zochorwa za soko zimepata uwezo mpya.
+
+---
+
+## Zochorwa Mpya za CLI
+
+### Ufafanuzi na Asili
+| Amri | Maelezo |
+|---------|-------------|
+| `tg-list-explain-traces` | Inaorodha zote za ufafanuzi (GraphRAG na Agent) katika mkusanyiko, inaonyesha ID za mkusanyiko, aina, maandishi ya swali, na tarehe. |
+| `tg-show-explain-trace` | Inaonyesha mstari kamili wa ufafanuzi kwa mkusanyiko. Kwa GraphRAG: Swali, Tafuta, Futa, na Safu za Mfumo. Kwa Agent: Mkusanyiko, Iterasi (fikra/hatua/taarifa), Jibu. Inaagizwa moja kwa moja. Inaunga mkono `--show-provenance` ili kurudisha miisho kwenye hati za asili. |
+| `tg-show-extraction-provenance` | Ikiwa na ID ya hati, inaendesha mkondo wa asili: Hati -> Kurasa -> Chunks -> Miisho, kwa kutumia mahusiano ya `prov:wasDerivedFrom`. Inaunga mkono chaguzi `--show-content` na `--max-content`. |
+
+### Data
+| Amri | Maelezo |
+|---------|-------------|
+| `tg-invoke-embeddings` | Hufanya maandishi kuwa na upinzani wa vector kupitia huduma ya upinzani. Inasoma moja au zaidi maandishi, inaondoa vipindi kama orodha. |
+| `tg-invoke-graph-embeddings` | Inaweka maandishi na graphs kupitia upinzani. Inaondoa vipindi kama orodha. |
+| `tg-invoke-document-embeddings` | Inaweka maandishi kupitia upinzani. Inaondoa vipindi kama orodha. |
+| `tg-invoke-row-embeddings` | Inaweka data iliyoandaliwa kupitia upinzani. Inaondoa vipindi kama orodha. |
+
+### Tafutaji wa Graphs
+
+| Amri | Maelezo |
+|---------|-------------|
+| `tg-query-graph` | Tafutaji la triple store. Mbali na `tg-show-graph` (ambayo inatumia kila kitu), inawezesha tafuta maalum kwa uwingi wa majimbo, mahusiano, na graphs. Inaagiza orodha moja kwa moja. Inaunga mkono `http://...`, `urn:...`, na `<...>`. |
+| `tg-get-document-content` | Inaagiza maudhui ya hati kutoka kwenye library kupitia ID ya hati. Inaweza kuonyesha kwenye faili au stdout, na inaweza kuuza maandishi na data. |
+
+---
+
+## Zochorwa Zilizoondolewa za CLI
+
+| Amri | Maelezo |
+|---------|-------|
+| `tg-load-pdf` | Imeondolewa. Utoaaji wa hati sasa unaendesha kupitia pipeline ya library/utumiaji. |
+| `tg-load-text` | Imeondolewa. Utoaaji wa hati sasa unaendesha kupitia pipeline ya library/utumiaji. |
+
+---
+
+## Zochorwa Zilizo badilishwa za CLI
+
+| Jina la Zamani | Jina la mpya | Maelezo |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | Ina maelezo kuhusu jina. |
+
+---
+
+## Mabadiliko Makubwa katika Zochorwa za Soko
+
+### `tg-invoke-graph-rag`
+
+- **Ufafanuzi**: Sasa ina 4-stage pipeline ya ufafanuzi (Swali, Tafuta/Tafuta, Futa, Mfumo) na maonyesho ya matukio ya asili.
+- **Streami**: Inaendesha WebSocket kwa matokeo ya muda halisi.
+- **Ufafanuzi**: Inawezesha kufuatilia miisho kwenye hati za asili kupitia reification na miisho ya `prov:wasDerivedFrom`.
+- Imebadilishwa na ~30 mistari hadi ~760 mistari ili kukidhi pipeline ya ufafanuzi.
+
+### `tg-invoke-document-rag`
+
+- **Ufafanuzi**: Inaongeza mode `question_explainable()` ambayo inatumia Graph RAG na maonyesho ya matukio ya asili.
+
+### `tg-invoke-agent`
+
+- **Ufafanuzi**: Inaongeza mode `question_explainable()` inayoeleza matukio ya asili wakati wa utumiaji wa agent (Swali, Tafuta, Mfumo, AgentThought, AgentObservation, AgentAnswer).
+- Mode ya verbose inaonyesha miisho za fikra/taarifa na prefixes za emoji.
+
+### `tg-show-graph`
+
+- **Mode ya Streami**: Inaendesha `triples_query_stream()` na ukubwa wa chombo configurable kwa muda wa matokeo wa kwanza na uzoefu wa kughushi.
+- **Uunganisho wa graph**: Mpya `--graph` chaguo. Inaagiza graphs:
+  - Graph chungu (tupu): Hekalu
+  - `urn:graph:source`: Asili
+  - `urn:graph:retrieval`: Tafuta
+- **Maonyesho ya graph**: Mpya `--show-graph` flag. Inaonyesha graph iliyochorwa kwa kila triple.
+- **Ukubwa wa Chaguzi**: Mpya `--limit` na chaguzi `--batch-size`.
+
+### `tg-graph-to-turtle`
+
+- **RDF-star support**: Inaendesha miisho za apostrophe (RDF-star reification).
+- **Mode ya Streami**: Inaendesha stream kwa muda wa matokezo wa kwanza.
+- **Uhandishi wa format**: Inaendesha format mpya (`{"t": "i", "i": uri}` kwa IRIs, `{"t": "l", "v": value}` kwa literals, `{"t": "r", "r": {...}}` kwa miisho).
+- **Uunganisho wa graph**: Mpya `--graph` chaguo.
+
+### `tg-set-tool`
+
+- **Aina mpya ya tool**: `row-embeddings-query` kwa utafutaji wa semantic kwenye data iliyoandaliwa.
+- **Chaguzi mpya**: `--schema-name`, `--index-name`, `--limit` kwa kuunda zochorwa za upinzani.
+
+### `tg-show-tools`
+
+- Inaonyesha zochorwa za mpya za `row-embeddings-query` na chaguzi zake.
+
+### `tg-load-knowledge`
+
+- **Ripoti za Maendeleo**: Inahesabu na inaonyesha miisho na miisho za entity za ililoandaliwa kwa kila faili na kwa jumla.
+- **Mbadilisho wa format**: Miisho za entity sasa inaformat mpya (`{"t": "i", "i": uri}`) badala ya format ya awali (`{"v": ..., "e": ...}`).
+
+---
+
+## Mabadiliko Masharti
+
+- **Jina la jumla**: Jina la `Value` lilibadilishwa kuwa `Term` katika mfumo kote (PR #622). Hii inafanya na format mpya `{"t": "i", "i": uri}` kwa IRIs na `{"t": "l", "v": value}` kwa literals, badala ya format ya zamani `{"v": ..., "e": ...}`.
+- **`tg-invoke-objects-query`** lilibadilishwa kuwa `tg-invoke-rows-query`.
+- **`tg-load-pdf`** na **`tg-load-text`** liliondolewa.

docs/cli-changes-v1.8-to-v2.1.tr.md

@@ -0,0 +1,112 @@
+# CLI Değişiklikleri: v1.8'den v2.1'e
+
+## Özet
+
+CLI (`trustgraph-cli`), üç tema üzerine odaklanmış önemli eklemeler içerir:
+**açıklanabilirlik/kaynak**, **gömme erişimi** ve **graf sorgulama**.
+İki eski araç kaldırıldı, biri yeniden adlandırıldı ve birkaç mevcut araç
+yeni yetenekler kazandı.
+
+--
+
+## Yeni CLI Araçları
+
+### Açıklanabilirlik ve Kaynak
+
+| Komut | Açıklama |
+|---------|-------------|
+| `tg-list-explain-traces` | Bir koleksiyondaki tüm açıklanabilirlik oturumlarını (GraphRAG ve Agent) listeler, oturum kimliklerini, türü, soru metnini ve zaman damgalarını gösterir. |
+| `tg-show-explain-trace` | Bir oturum için tam açıklanabilirlik izini görüntüler. GraphRAG için: Soru, Keşif, Odak, Sentez aşamaları. Agent için: Oturum, Yinelemeler (düşünce/eylem/gözlem), Son Cevap. İz türünü otomatik olarak algılar. `--show-provenance` ile kaynak belgelere kadar kenarları izlemeyi destekler. |
+| `tg-show-extraction-provenance` | Bir belge kimliği verildiğinde, kaynak zincirini izler: Belge -> Sayfalar -> Parçalar -> Kenarlar, `prov:wasDerivedFrom` ilişkilerini kullanarak. `--show-content` ve `--max-content` seçeneklerini destekler. |
+
+### Gömme (Embeddings)
+
+| Komut | Açıklama |
+|---------|-------------|
+| `tg-invoke-embeddings` | Metni, gömme hizmeti aracılığıyla bir vektör gömmesine dönüştürür. Bir veya daha fazla metin girişi alır, vektörleri kayan nokta listeleri olarak döndürür. |
+| `tg-invoke-graph-embeddings` | Vektör gömmelerini kullanarak grafik varlıklarını metin benzerliğiyle sorgular. Eşleşen varlıkları benzerlik puanlarıyla döndürür. |
+| `tg-invoke-document-embeddings` | Vektör gömmelerini kullanarak belge parçalarını metin benzerliğiyle sorgular. Eşleşen parça kimliklerini benzerlik puanlarıyla döndürür. |
+| `tg-invoke-row-embeddings` | Vektör gömmelerini kullanarak dizinlenmiş alanlarda yapılandırılmış veri satırlarını metin benzerliğiyle sorgular. Eşleşen satırları, indeks değerlerini ve puanları döndürür. `--schema-name` gerektirir ve `--index-name`'yi destekler. |
+
+### Graf Sorgulama
+
+| Komut | Açıklama |
+|---------|-------------|
+| `tg-query-graph` | Desen tabanlı üçlü depolama sorgusu. `tg-show-graph`'in aksine (her şeyi dökerek), bu, herhangi bir konu, yüklem, nesne ve graf kombinasyonuyla seçici sorgular yapmayı sağlar. Değer türlerini otomatik olarak algılar: IRI'lar (`http://...`, `urn:...`, `<...>`), tırnak işaretli üçlüler (`<<s p o>>`) ve literal'lar. |
+| `tg-get-document-content` | Belge kimliğine göre kütüphaneden belge içeriğini alır. Dosyaya veya standart çıktıya yazabilir, hem metin hem de ikili içeriği işler. |
+
+--
+
+## Kaldırılan CLI Araçları
+
+| Komut | Notlar |
+|---------|-------|
+| `tg-load-pdf` | Kaldırıldı. Belge yükleme artık kütüphane/işlem hattı aracılığıyla yapılır. |
+| `tg-load-text` | Kaldırıldı. Belge yükleme artık kütüphane/işlem hattı aracılığıyla yapılır. |
+
+--
+
+## Yeniden Adlandırılan CLI Araçları
+
+| Eski Ad | Yeni Ad | Notlar |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | Yapılandırılmış veri için "nesneler" teriminin "satırlar" terimine dönüştürülmesini yansıtır. |
+
+--
+
+## Mevcut Araçlara Yönelik Önemli Değişiklikler
+
+### `tg-invoke-graph-rag`
+
+**Açıklanabilirlik desteği**: Artık, yerleşik kaynak olay gösterimiyle (Question, Grounding/Exploration, Focus, Synthesis) 4 aşamalı bir açıklanabilirlik işlem hattını destekler.
+**Akış**: Gerçek zamanlı çıktı için WebSocket akışını kullanır.
+**Kaynak takibi**: Seçilen kenarları yeniden yapılandırma ve `prov:wasDerivedFrom` zincirleri aracılığıyla kaynak belgelere kadar izleyebilir.
+Tam açıklanabilirlik işlem hattını barındırmak için ~30 satırdan ~760 satıra yükseldi.
+
+### `tg-invoke-document-rag`
+
+**Açıklanabilirlik desteği**: İçerik tabanlı yanıtları (Document RAG) yerleşik kaynak olaylarıyla (Question, Grounding, Exploration, Synthesis aşamaları) akışla gönderen `question_explainable()` modunu ekledi.
+
+### `tg-invoke-agent`
+
+**Açıklanabilirlik desteği**: Ajan yürütülmesi sırasında kaynak olaylarını yerleşik olarak gösteren `question_explainable()` modunu ekledi (Question, Analysis, Conclusion, AgentThought, AgentObservation, AgentAnswer).
+Ayrıntılı mod, düşünce/gözlem akışlarını emoji ön ekleriyle gösterir.
+
+### `tg-show-graph`
+
+**Akış modu**: Daha düşük ilk sonuç süresi ve azaltılmış bellek yükü için yapılandırılabilir toplu boyutlarla `triples_query_stream()`'ı kullanır.
+**Adlandırılmış grafik desteği**: Yeni `--graph` filtre seçeneği. Adlandırılmış grafikleri tanır:
+  Varsayılan grafik (boş): Temel bilgi gerçekleri
+  `urn:graph:source`: Çıkarma kaynağı
+  `urn:graph:retrieval`: Sorgu zamanı açıklanabilirliği
+**Grafik sütununu göster**: Her üçlü için adlandırılmış grafiği görüntülemek için yeni `--show-graph` bayrağı.
+**Yapılandırılabilir sınırlar**: Yeni `--limit` ve `--batch-size` seçenekleri.
+
+### `tg-graph-to-turtle`
+
+**RDF-star desteği**: Artık tırnaklı üçlüleri (RDF-star yeniden yapılandırması) işler.
+**Akış modu**: Daha düşük ilk işleme süresi için akışı kullanır.
+**Tel formatı işleme**: IRIs için `{"t": "i", "i": uri}`, literal'lar için `{"t": "l", "v": value}` ve tırnaklı üçlüler için `{"t": "r", "r": {...}}` kullanan yeni terim tel formatını kullanmak üzere güncellendi.
+**Adlandırılmış grafik desteği**: Yeni `--graph` filtre seçeneği.
+
+### `tg-set-tool`
+
+**Yeni araç türü**: Yapılandırılmış veri dizinlerinde semantik arama için `row-embeddings-query`.
+**Yeni seçenekler**: Satır gömme sorgu araçlarını yapılandırmak için `--schema-name`, `--index-name`, `--limit`.
+
+### `tg-show-tools`
+
+`schema-name`, `index-name` ve `limit` alanlarıyla yeni `row-embeddings-query` araç türünü görüntüler.
+
+### `tg-load-knowledge`
+
+**İlerleme raporlama**: Her dosya ve toplamda yüklenen üçlü ve varlık bağlamlarının sayısını sayar ve raporlar.
+**Terim formatı güncellemesi**: Varlık bağlamları artık eski Değer formatının (`{"v": entity, "e": True}`) yerine yeni Terim formatını (`{"t": "i", "i": uri}`) kullanır.
+
+--
+
+## Uyumluluk Sorunları
+
+**Terminoloji yeniden adlandırması**: `Value` şeması, sistem genelinde `Term` olarak yeniden adlandırıldı (PR #622). Bu, grafik deposuyla etkileşimde bulunan CLI araçları tarafından kullanılan tel formatını etkiler. Yeni format, eski `{"v": ..., "e": ...}` formatının yerini alarak IRIs için `{"t": "i", "i": uri}` ve literal'lar için `{"t": "l", "v": value}` kullanır.
+`tg-invoke-objects-query` yeniden adlandırıldı `tg-invoke-rows-query`.
+`tg-load-pdf` ve `tg-load-text` kaldırıldı.

docs/cli-changes-v1.8-to-v2.1.zh-cn.md

@@ -0,0 +1,111 @@
+# CLI 修改：v1.8 到 v2.1
+
+## 摘要
+
+CLI (`trustgraph-cli`) 包含大量新增功能，主要集中在以下三个方面：
+**可解释性/来源追溯**, **嵌入式访问**, 和 **图查询**。
+移除两个旧工具，一个重命名，并且多个现有工具获得了新的功能。
+
+---
+
+## 新的 CLI 工具
+
+### 可解释性 & 来源追溯
+
+| 命令 | 描述 |
+|---------|-------------|
+| `tg-list-explain-traces` | 列出集合中所有 Explain 实例（GraphRAG 和 Agent），显示实例 ID、类型、问题文本和时间戳。 |
+| `tg-show-explain-trace` | 显示 Explain 实例的完整追溯信息。 对于 GraphRAG：问题、探索、聚焦、合成阶段。 对于 Agent：会话、迭代（思考/行动/观察）、最终答案。 自动检测追溯类型。 支持 `--show-provenance` 选项，用于追溯边缘到源文档。 |
+| `tg-show-extraction-provenance` | 给出文档 ID，遍历来源链：文档 -> 页面 -> 块 -> 边缘，使用 `prov:wasDerivedFrom` 关系。 支持 `--show-content` 和 `--max-content` 选项。 |
+
+### 嵌入式
+
+| 命令 | 描述 |
+|---------|-------------|
+| `tg-invoke-embeddings` | 通过嵌入服务将文本转换为向量嵌入。 接受一个或多个文本输入，返回向量为浮点数的列表。 |
+| `tg-invoke-graph-embeddings` | 使用向量嵌入根据文本相似性查询图实体。 返回匹配的实体以及相似度得分。 |
+| `tg-invoke-document-embeddings` | 使用向量嵌入根据文本相似性查询文档块。 返回匹配的块 ID 以及相似度得分。 |
+| `tg-invoke-row-embeddings` | 使用在索引字段上进行的文本相似性查询，查询结构化数据行。 返回与索引值和得分匹配的行。 需要 `--schema-name` 且支持 `--index-name`。 |
+
+### 图查询
+
+| 命令 | 描述 |
+|---------|-------------|
+| `tg-query-graph` | 基于模式的图存储查询。 与 `tg-show-graph` 不同（它会显示所有内容），这允许通过任何组合的子句、谓词、对象和图进行选择性查询。 自动检测值类型：IRI (`http://...`, `urn:...`, `<...>`)、带有引号的三重 (`<<s p o>>`) 和字面量。 |
+| `tg-get-document-content` | 从库中通过文档 ID 获取文档内容。 可以输出到文件或 stdout，支持文本和二进制内容。 |
+
+---
+
+## 已移除的 CLI 工具
+
+| 命令 | 备注 |
+|---------|-------|
+| `tg-load-pdf` | 已移除。 文档加载现在通过库/处理流程进行。 |
+| `tg-load-text` | 已移除。 文档加载现在通过库/处理流程进行。 |
+
+---
+
+## 重命名后的 CLI 工具
+
+| 旧名称 | 新名称 | 备注 |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | 反映了从 "对象" 到 "行" 的术语重命名，用于结构化数据。 |
+
+---
+
+## 现有工具的重要变更
+
+### `tg-invoke-graph-rag`
+
+- **可解释性支持**: 现在支持 4 阶段的可解释性管道（问题、基础/探索、聚焦、合成），并显示内联来源事件。
+- **流式传输**: 使用 WebSocket 流式传输实现实时输出。
+- **来源追溯**: 可以通过重构和 `prov:wasDerivedFrom` 链，追溯选定的边缘回源文档。
+- 从约 30 行增长到约 760 行，以适应完整的可解释性管道。
+
+### `tg-invoke-document-rag`
+
+- **可解释性支持**: 添加了 `question_explainable()` 模式，可以流式传输带有内联来源事件的文档 RAG 响应（问题、基础、探索、合成阶段）。
+
+### `tg-invoke-agent`
+
+- **可解释性支持**: 添加了 `question_explainable()` 模式，在执行代理时显示内联来源事件（问题、分析、结论、AgentThought、AgentObservation、AgentAnswer）。
+- 详细模式显示了带有表情符号前缀的思考/观察流。
+
+### `tg-show-graph`
+
+- **流式传输模式**: 现在使用 `triples_query_stream()` 与可配置的批次大小，实现更快的首次结果时间和减少内存开销。
+- **命名图支持**: 新的 `--graph` 过滤选项。 识别命名图：
+  - 默认图 (空): 核心知识的事实
+  - `urn:graph:source`: 提取来源
+  - `urn:graph:retrieval`: 查询时追溯
+- **显示图列**: 新的 `--show-graph` 标志，显示每个三元组的命名图。
+- **可配置的限制**: 新的 `--limit` 和 `--batch-size` 选项。
+
+### `tg-graph-to-turtle`
+
+- **RDF-star 支持**: 现在可以处理带有引号的三元 (`RDF-star reification`)。
+- **流式传输模式**: 使用流式传输实现更快的首次处理时间。
+- **Wire 格式处理**: 已更新为使用新的 wire 格式 (`{"t": "i", "i": uri}` 用于 IRI，`{"t": "l", "v": value}` 用于字面量，`{"t": "r", "r": {...}}` 用于带有引号的三元)，代替旧的 `{"v": ..., "e": ...}` 格式。
+- **命名图支持**: 新的 `--graph` 过滤选项。
+
+### `tg-set-tool`
+
+- **新的工具类型**: `row-embeddings-query` 用于在结构化数据索引上进行语义搜索。
+- **新的选项**: `--schema-name`, `--index-name`, `--limit` 用于配置 `row-embeddings-query` 工具。
+
+### `tg-show-tools`
+
+- 显示新的 `row-embeddings-query` 工具类型及其 `schema-name`、`index-name` 和 `limit` 字段。
+
+### `tg-load-knowledge`
+
+- **进度报告**: 现在统计并报告每个文件的加载三元和实体上下文的数量，以及总数。
+- **术语格式更新**: 实体上下文现在使用新的术语格式 (`{"t": "i", "i": uri}`) 代替旧的 Value 格式 (`{"v": entity, "e": True}`)。
+
+---
+
+## 破坏性变更
+
+- **术语重命名**: `Value` 模式已重命名为 `Term`，该重命名影响了与图存储交互的 CLI 工具。 新格式使用 `{"t": "i", "i": uri}` 用于 IRI，`{"t": "l", "v": value}` 用于字面量，代替旧的 `{"v": ..., "e": ...}` 格式。
+- **`tg-invoke-objects-query` 重命名**为 `tg-invoke-rows-query`。
+- **`tg-load-pdf` 和 `tg-load-text` 已移除**。

docs/contributor-licence-agreement.ar.md

@@ -0,0 +1,8 @@
+# اتفاقية الترخيص للمساهمين
+
+نطلب من كل المساهمين التوقيع على اتفاقية الترخيص للمساهمين قبل أن نتمكن من دمج طلب السحب. لا تنقل اتفاقية الترخيص حقوق الطبع والنشر - أنت تحتفظ بالملكية الكاملة لعملك. إنها ببساطة تمنح مشروع TrustGraph ترخيصًا دائمًا، وخاليًا من الرسوم، لتوزيع مساهمتك بموجب ترخيص [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) الخاص بالمشروع، وتؤكد أن لديك الحق في تقديم المساهمة. وهذا يحمي المشروع ومستخدميه من خلال ضمان أن لكل مساهمة الأساس القانوني الواضح.
+
+عندما تفتح طلب سحب، سيقوم روبوت اتفاقية الترخيص بنشر تعليق يطلب منك مراجعة وتوقيع الاتفاقية المناسبة - ويستغرق ذلك لحظة فقط، وعليك القيام بذلك مرة واحدة فقط عبر جميع مستودعات TrustGraph.
+
+- المساهمة ك**فرد**؟ قم بتوقيع [اتفاقية الترخيص الفردية](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- المساهمة **بالنيابة عن شركة أو منظمة**؟ قم بتوقيع [اتفاقية الترخيص التنظيمية](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.es.md

@@ -0,0 +1,8 @@
+# Acuerdo de Licencia para Contribuyentes
+
+Solicitamos que todos los contribuyentes firmen un Acuerdo de Licencia para Contribuyentes antes de que podamos fusionar una solicitud de extracción. El acuerdo **no** transfiere la propiedad del copyright; usted mantiene la propiedad total de su trabajo. Simplemente otorga al proyecto TrustGraph una licencia perpetua, sin regalías, para distribuir su contribución bajo la licencia [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), y confirma que tiene el derecho de hacer la contribución. Esto protege tanto al proyecto como a sus usuarios, garantizando que cada contribución tenga una base legal clara.
+
+Cuando abra una solicitud de extracción, el bot de CLA publicará un comentario solicitándole que revise y firme el acuerdo correspondiente; solo requiere un momento y solo necesita hacerlo una vez en todos los repositorios de TrustGraph.
+
+- ¿Contribuyendo como **individuo**? Firme el [Acuerdo de Licencia para Contribuyentes Individual](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- ¿Contribuyendo en nombre de una **empresa o organización**? Firme el [Acuerdo de Licencia para Contribuyentes de Entidad](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.he.md

@@ -0,0 +1,8 @@
+# הסכם רישיון לתורמים
+
+אנו מבקשים מכל תורם לחתום על הסכם רישיון לתורמים לפני שנוכל לשלב בקשת פול. ההסכם **אינו** מעביר זכויות יוצרים – אתם שומרים על בעלות מלאה על עבודתכם. הוא פשוט מעניק לפרויקט TrustGraph רישיון נצחי, ללא תמלוגים, להפצת התרומה שלכם על פי הרישיון [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), וכן מאשר שאתם רשאים להעביר את התרומה. זה מגן הן על הפרויקט והן על המשתמשים שלו, על ידי הבטחת שכל תרומה תהיה בעלת בסיס משפטי ברור.
+
+כשאתם פותחים בקשת פול, בוט ה-CLA יפרסם הערה המבקש מכם לבדוק ולחתום על ההסכם המתאים – זה לוקח רק רגע, ואתם צריכים לעשות זאת רק פעם אחת בכל מאגרי ה-TrustGraph.
+
+- תורמים כ**אינדיבידואל**? חתמו על [הסכם רישיון אינדיבידואלי](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- תורמים **מטעמ חברה או ארגון**? חתמו על [הסכם רישיון עבור ארגון](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.hi.md

@@ -0,0 +1,16 @@
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बनाए रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट को ही आउटपुट करें, जिसमें कोई भी प्रारंभिक या स्पष्टीकरण शामिल न हों।
+
+अनुवाद करने के लिए पाठ:
+
+# योगदानकर्ता लाइसेंस समझौता (CLA)
+
+हम हर योगदानकर्ता से एक योगदानकर्ता लाइसेंस समझौते पर हस्ताक्षर करने का अनुरोध करते हैं, इससे पहले कि हम किसी पुल अनुरोध को मर्ज कर सकें। CLA कॉपीराइट को **नहीं** हस्तांतरित करता है — आप अपने कार्य का पूर्ण स्वामित्व बनाए रखते हैं। यह केवल TrustGraph परियोजना को आपके योगदान को परियोजना के [Apache 2.0 लाइसेंस](https://www.apache.org/licenses/LICENSE-2.0) के तहत वितरित करने का एक स्थायी, रॉयल्टी-मुक्त लाइसेंस प्रदान करता है, और यह पुष्टि करता है कि आपके पास योगदान करने का अधिकार है। यह परियोजना और उसके उपयोगकर्ताओं दोनों की रक्षा करता है, यह सुनिश्चित करके कि प्रत्येक योगदान का एक स्पष्ट कानूनी आधार है।
+
+जब आप एक पुल अनुरोध खोलते हैं, तो CLA बॉट आपसे उचित समझौते की समीक्षा और हस्ताक्षर करने के लिए एक टिप्पणी पोस्ट करेगा - इसमें केवल एक पल लगता है और आपको इसे ट्रस्टग्राफ रिपॉजिटरी के सभी में केवल एक बार करने की आवश्यकता है।
+
+- एक **व्यक्ति** के रूप में योगदान कर रहे हैं? [व्यक्तिगत CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md) पर हस्ताक्षर करें।
+- एक **कंपनी या संगठन** की ओर से योगदान कर रहे हैं? [कंपनी CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md) पर हस्ताक्षर करें।

docs/contributor-licence-agreement.pt.md

@@ -0,0 +1,19 @@
+# Acordo de Licença para Contribuintes (CLA)
+
+Pedimos a cada contribuinte que assine um Acordo de Licença para Contribuintes antes
+que possamos mesclar um pull request. O CLA não transfere os direitos autorais —
+você mantém a propriedade total do seu trabalho. Ele simplesmente concede ao projeto TrustGraph
+uma licença perpétua e sem royalties para distribuir sua
+contribuição sob a licença
+[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) do projeto, e
+confirma que você tem o direito de fazer a contribuição. Isso protege
+tanto o projeto quanto seus usuários, garantindo que cada contribuição tenha
+uma base legal clara.
+
+Quando você abre um pull request, o bot do CLA postará um comentário pedindo que você
+revise e assine o acordo apropriado — leva apenas um momento
+e você só precisa fazer isso uma vez em todos os repositórios do TrustGraph.
+
+Contribuindo como um **indivíduo**? Assine o [CLA Individual](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+Contribuindo em nome de uma **empresa ou organização**? Assine o [CLA para Entidades](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)
+

docs/contributor-licence-agreement.ru.md

@@ -0,0 +1,8 @@
+# Договор лицензии для вкладчиков
+
+Мы требуем, чтобы каждый вкладчик подписал Договор лицензии для вкладчиков, прежде чем мы сможем принять ваш запрос на слияние. Договор лицензии **не** передаёт авторские права — вы сохраняете полное право собственности на свою работу. Он просто предоставляет проекту TrustGraph пожизненную, без роялти лицензию на распространение вашего вклада в соответствии с лицензией [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), а также подтверждает, что у вас есть право внести вклад. Это защищает как проект, так и его пользователей, обеспечивая, чтобы каждый вклад имел четкое юридическое обоснование.
+
+Когда вы создаёте запрос на слияние, бот CLA опубликует комментарий, в котором попросит вас ознакомиться и подписать соответствующий договор — это занимает всего несколько минут, и вам нужно сделать это только один раз для всех репозиториев TrustGraph.
+
+- Вклад в качестве **индивидуального** участника? Подпишите [Индивидуальный договор лицензии](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- Вклад от имени **компании или организации**? Подпишите [Организационный договор лицензии](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.sw.md

@@ -0,0 +1,16 @@
+**MAELEZI MUHIMU:**
+- Hifadhi KILA muundo wa Markdown, vichwa, viungo, na lebo za HTML.
+- EISIUSHA kutafsiri kodio iliyo ndani ya leseni (`code`) au katika blok za kodio.
+- Toa TU matini iliyotafsiri bila maelezo au utangulizi.
+
+Matini ya kutafsiri:
+# Mkataba wa Lisensi wa Mhudumu (CLA)
+
+Tunatoa ombi kwa kila mhudumu kusaini Mkataba wa Lisensi wa Mhudumu kabla
+tunaweza kuingiza ombi la "pull". Mkataba huu **sisi** huhamisha haki za udani —
+unaendelea kuwa mmiliki kamili wa kazi yako. Hii kwa upande wake huipa Mradi wa TrustGraph lisensi ya kudumu, bila malipo, ya kusambaza mchango wako chini ya lisensi ya [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), na ina hakikisha kuwa una haki ya kufanya mchango. Hii inalinda kila mmoja, mradi na watumiaji, kwa kuhakikisha kwamba kila mchango una msingi wa kisheria.
+
+Unapouingiza ombi la "pull", bot ya CLA italeta maoni ya kukuelekeza kukagua na kusaini mkataba unaofaa— hili lina kuchukua tu dakika nadra, na unahitaji kufanya hivyo mara moja kwenye lahat ya TrustGraph.
+
+- Kichango kama **mshiriki binafsi**? Saini [Mkataba wa Lisensi wa Mshiriki](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- Kichango kwa niaba ya **kampuni au shirika**? Saini [Mkataba wa Lisensi wa Shirika](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.tr.md

@@ -0,0 +1,19 @@
+# Katkıda Bulunanlar Lisans Sözleşmesi (KBL)
+
+Her katkıda bulunan kişiden, bir çekme isteğini (pull request) birleştirmeden önce, bir Katkıda Bulunan Lisans Sözleşmesi (Contributor Licence Agreement) imzalamasını rica ediyoruz.
+CLA, telif hakkını devretmez;
+siz, yaptığınız işin tam mülkiyetini koruyorsunuz. Sadece TrustGraph
+projesine, katkınızı projenin
+altında dağıtmak için kalıcı, telifsiz bir lisans verir.
+[Apache 2.0 lisansı](https://www.apache.org/licenses/LICENSE-2.0) ve
+katkıyı yapma hakkınız olduğunu teyit eder. Bu, her katkının açık bir yasal temele sahip olmasını sağlayarak hem projeyi hem de kullanıcılarını korur.
+
+
+
+Bir çekme isteği (pull request) açtığınızda, CLA bot'u size uygun sözleşmeyi incelemeniz ve imzalamanız için bir yorum yayınlayacaktır; bu sadece birkaç dakika sürer.
+Ve bunu yalnızca TrustGraph'taki tüm depolarda bir kez yapmanız gerekir.
+
+
+**Bireysel** olarak katkıda bulunuyor musunuz? [Bireysel CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md) sözleşmesini imzalayın.
+Bir **şirket veya kuruluş** adına katkıda bulunuyor musunuz? [Kuruluş CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md) sözleşmesini imzalayın.
+

docs/contributor-licence-agreement.zh-cn.md

@@ -0,0 +1,8 @@
+# 贡献者许可协议 (CLA)
+
+我们要求所有贡献者在合并拉取请求之前签署贡献者许可协议。该协议**不**会转移版权——您仍然拥有您的作品的全部所有权。它仅授予 TrustGraph 项目一项永久、免版税的使用许可，以在项目的 [Apache 2.0 许可](https://www.apache.org/licenses/LICENSE-2.0) 下分发您的贡献，并确认您有权进行贡献。这既保护了项目本身，也保护了其用户，确保每个贡献都有明确的法律依据。
+
+当您提交拉取请求时，CLA 机器人会发布一条评论，要求您审查并签署相应的协议——这只需要几秒钟，您只需要在所有 TrustGraph 仓库中执行一次。
+
+- 作为**个人**贡献？请签署 [个人 CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- 代表**公司或组织**贡献？请签署 [实体 CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/tech-specs/__TEMPLATE.ar.md

@@ -0,0 +1,127 @@
+# المواصفات الفنية لتحميل المعرفة من سطر الأوامر
+
+## نظرة عامة
+
+تصف هذه المواصفة واجهات سطر الأوامر لتحميل المعرفة إلى TrustGraph، مما يمكّن المستخدمين من استيراد البيانات من مصادر مختلفة من خلال أدوات سطر الأوامر. تدعم هذه التكامل أربع حالات استخدام رئيسية:
+
+1. **[حالة الاستخدام 1]**: [الوصف]
+2. **[حالة الاستخدام 2]**: [الوصف]
+3. **[حالة الاستخدام 3]**: [الوصف]
+4. **[حالة الاستخدام 4]**: [الوصف]
+
+## الأهداف
+
+- **[الهدف 1]**: [الوصف]
+- **[الهدف 2]**: [الوصف]
+- **[الهدف 3]**: [الوصف]
+- **[الهدف 4]**: [الوصف]
+- **[الهدف 5]**: [الوصف]
+- **[الهدف 6]**: [الوصف]
+- **[الهدف 7]**: [الوصف]
+- **[الهدف 8]**: [الوصف]
+
+## الخلفية
+
+[صف الحالة الحالية والقيود التي تعالجها هذه المواصفة]
+
+تشمل القيود الحالية:
+- [القيد 1]
+- [القيد 2]
+- [القيد 3]
+- [القيد 4]
+
+تعالج هذه المواصفة هذه الثغرات من خلال [الوصف]. من خلال [القدرة]، يمكن لـ TrustGraph:
+- [الفائدة 1]
+- [الفائدة 2]
+- [الفائدة 3]
+- [الفائدة 4]
+
+## التصميم الفني
+
+### البنية
+
+يتطلب تحميل المعرفة من سطر الأوامر المكونات الفنية التالية:
+
+1. **[المكون 1]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+   
+   الوحدة: [مسار-الوحدة]
+
+2. **[المكون 2]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+
+   الوحدة: [مسار-الوحدة]
+
+3. **[المكون 3]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+
+   الوحدة: [مسار-الوحدة]
+
+### نماذج البيانات
+
+#### [نموذج البيانات 1]
+
+[وصف نموذج البيانات والبنية]
+
+مثال:
+```
+[Example data structure]
+```
+
+هذا النهج يسمح بما يلي:
+- [الفائدة 1]
+- [الفائدة 2]
+- [الفائدة 3]
+- [الفائدة 4]
+
+### واجهات برمجة التطبيقات (APIs)
+
+واجهات برمجة تطبيقات جديدة:
+- [وصف واجهة برمجة التطبيقات 1]
+- [وصف واجهة برمجة التطبيقات 2]
+- [وصف واجهة برمجة التطبيقات 3]
+
+واجهات برمجة تطبيقات مُعدَّلة:
+- [واجهة برمجة تطبيقات مُعدَّلة 1] - [وصف التغييرات]
+- [واجهة برمجة تطبيقات مُعدَّلة 2] - [وصف التغييرات]
+
+### تفاصيل التنفيذ
+
+[نهج التنفيذ والاصطلاحات]
+
+[ملاحظات إضافية حول التنفيذ]
+
+## اعتبارات الأمان
+
+[اعتبارات الأمان الخاصة بهذا التنفيذ]
+
+## اعتبارات الأداء
+
+[اعتبارات الأداء والاختناقات المحتملة]
+
+## استراتيجية الاختبار
+
+[نهج واستراتيجية الاختبار]
+
+## خطة الترحيل
+
+[استراتيجية الترحيل إذا كانت قابلة للتطبيق]
+
+## الجدول الزمني
+
+[معلومات حول الجدول الزمني إذا تم تحديدها]
+
+## أسئلة مفتوحة
+
+- [سؤال مفتوح 1]
+- [سؤال مفتوح 2]
+
+## المراجع
+
+[المراجع إذا كانت قابلة للتطبيق]

docs/tech-specs/__TEMPLATE.es.md

@@ -0,0 +1,127 @@
+# Especificación Técnica de Carga de Conocimiento desde la Línea de Comandos
+
+## Resumen
+
+Esta especificación describe las interfaces de línea de comandos para cargar conocimiento en TrustGraph, permitiendo a los usuarios importar datos de diversas fuentes a través de herramientas de línea de comandos. La integración admite cuatro casos de uso principales:
+
+1. **[Caso de Uso 1]**: [Descripción]
+2. **[Caso de Uso 2]**: [Descripción]
+3. **[Caso de Uso 3]**: [Descripción]
+4. **[Caso de Uso 4]**: [Descripción]
+
+## Objetivos
+
+- **[Objetivo 1]**: [Descripción]
+- **[Objetivo 2]**: [Descripción]
+- **[Objetivo 3]**: [Descripción]
+- **[Objetivo 4]**: [Descripción]
+- **[Objetivo 5]**: [Descripción]
+- **[Objetivo 6]**: [Descripción]
+- **[Objetivo 7]**: [Descripción]
+- **[Objetivo 8]**: [Descripción]
+
+## Antecedentes
+
+[Describa el estado actual y las limitaciones que esta especificación aborda]
+
+Las limitaciones actuales incluyen:
+- [Limitación 1]
+- [Limitación 2] 
+- [Limitación 3]
+- [Limitación 4]
+
+Esta especificación aborda estas deficiencias mediante [descripción]. Al [capacidad], TrustGraph puede:
+- [Beneficio 1]
+- [Beneficio 2]
+- [Beneficio 3]
+- [Beneficio 4]
+
+## Diseño Técnico
+
+### Arquitectura
+
+La carga de conocimiento desde la línea de comandos requiere los siguientes componentes técnicos:
+
+1. **[Componente 1]**
+   - [Descripción de la funcionalidad del componente]
+   - [Características clave]
+   - [Puntos de integración]
+   
+   Módulo: [module-path]
+
+2. **[Componente 2]**
+   - [Descripción de la funcionalidad del componente]
+   - [Características clave]
+   - [Puntos de integración]
+
+   Módulo: [module-path]
+
+3. **[Componente 3]**
+   - [Descripción de la funcionalidad del componente]
+   - [Características clave]
+   - [Puntos de integración]
+
+   Módulo: [module-path]
+
+### Modelos de Datos
+
+#### [Modelo de Datos 1]
+
+[Descripción del modelo de datos y su estructura]
+
+Ejemplo:
+```
+[Example data structure]
+```
+
+Este enfoque permite:
+- [Beneficio 1]
+- [Beneficio 2]
+- [Beneficio 3]
+- [Beneficio 4]
+
+### APIs
+
+Nuevas APIs:
+- [Descripción de la API 1]
+- [Descripción de la API 2]
+- [Descripción de la API 3]
+
+APIs modificadas:
+- [API modificada 1] - [Descripción de los cambios]
+- [API modificada 2] - [Descripción de los cambios]
+
+### Detalles de implementación
+
+[Enfoque y convenciones de implementación]
+
+[Notas adicionales de implementación]
+
+## Consideraciones de seguridad
+
+[Consideraciones de seguridad específicas de esta implementación]
+
+## Consideraciones de rendimiento
+
+[Consideraciones de rendimiento y posibles cuellos de botella]
+
+## Estrategia de pruebas
+
+[Enfoque y estrategia de pruebas]
+
+## Plan de migración
+
+[Estrategia de migración si es aplicable]
+
+## Cronograma
+
+[Información del cronograma si se especifica]
+
+## Preguntas abiertas
+
+- [Pregunta abierta 1]
+- [Pregunta abierta 2]
+
+## Referencias
+
+[Referencias si es aplicable]

docs/tech-specs/__TEMPLATE.he.md

@@ -0,0 +1,127 @@
+# Command-Line Loading Knowledge Technical Specification
+
+## Overview
+
+מפרט זה מתאר את ממשקי שורת הפקודה לטעינת ידע לתוך TrustGraph, ומאפשר למשתמשים לקלוט נתונים ממקורות שונים באמצעות כלי שורת פקודה. האינטגרציה תומכת בארבעה תרחישי שימוש עיקריים:
+
+1. **[Use Case 1]**: [Description]
+2. **[Use Case 2]**: [Description]
+3. **[Use Case 3]**: [Description]
+4. **[Use Case 4]**: [Description]
+
+## Goals
+
+- **[Goal 1]**: [Description]
+- **[Goal 2]**: [Description]
+- **[Goal 3]**: [Description]
+- **[Goal 4]**: [Description]
+- **[Goal 5]**: [Description]
+- **[Goal 6]**: [Description]
+- **[Goal 7]**: [Description]
+- **[Goal 8]**: [Description]
+
+## Background
+
+[Describe the current state and limitations that this specification addresses]
+
+מגבלות נוכחיות כוללות:
+- [Limitation 1]
+- [Limitation 2]
+- [Limitation 3]
+- [Limitation 4]
+
+מפרט זה מתייחס לפערים אלה על ידי [description]. באמצעות [capability], TrustGraph יכול:
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+- [Benefit 4]
+
+## Technical Design
+
+### Architecture
+
+טעינת ידע משורת הפקודה דורשת את הרכיבים הטכניים הבאים:
+
+1. **[Component 1]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+   
+   Module: [module-path]
+
+2. **[Component 2]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+
+   Module: [module-path]
+
+3. **[Component 3]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+
+   Module: [module-path]
+
+### Data Models
+
+#### [Data Model 1]
+
+[Description of data model and structure]
+
+Example:
+```
+[Example data structure]
+```
+
+גישה זו מאפשרת:
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+- [Benefit 4]
+
+### ממשקי API
+
+ממשקי API חדשים:
+- [API description 1]
+- [API description 2]
+- [API description 3]
+
+ממשקי API ששונו:
+- [Modified API 1] - [Description of changes]
+- [Modified API 2] - [Description of changes]
+
+### פרטי יישום
+
+[גישת יישום ועקרונות]
+
+[הערות נוספות בנוגע ליישום]
+
+## שיקולי אבטחה
+
+[שיקולי אבטחה ספציפיים ליישום זה]
+
+## שיקולי ביצועים
+
+[שיקולי ביצועים וצווארי בקבוק פוטנציאליים]
+
+## אסטרטגיית בדיקות
+
+[גישת אסטרטגיית בדיקות]
+
+## תוכנית מעבר
+
+[אסטרטגיית מעבר, אם רלוונטית]
+
+## ציר זמן
+
+[מידע על ציר הזמן, אם מצוין]
+
+## שאלות פתוחות
+
+- [Open question 1]
+- [Open question 2]
+
+## מקורות
+
+[מקורות, אם רלוונטיים]

docs/tech-specs/__TEMPLATE.hi.md

@@ -0,0 +1,127 @@
+# कमांड-लाइन लोडिंग नॉलेज टेक्निकल स्पेसिफिकेशन
+
+## अवलोकन
+
+यह स्पेसिफिकेशन ट्रस्टग्राफ में नॉलेज लोड करने के लिए कमांड-लाइन इंटरफेस का वर्णन करता है, जो उपयोगकर्ताओं को कमांड-लाइन टूल के माध्यम से विभिन्न स्रोतों से डेटा प्राप्त करने में सक्षम बनाता है। एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
+
+1. **[उपयोग मामला 1]**: [विवरण]
+2. **[उपयोग मामला 2]**: [विवरण]
+3. **[उपयोग मामला 3]**: [विवरण]
+4. **[उपयोग मामला 4]**: [विवरण]
+
+## लक्ष्य
+
+- **[लक्ष्य 1]**: [विवरण]
+- **[लक्ष्य 2]**: [विवरण]
+- **[लक्ष्य 3]**: [विवरण]
+- **[लक्ष्य 4]**: [विवरण]
+- **[लक्ष्य 5]**: [विवरण]
+- **[लक्ष्य 6]**: [विवरण]
+- **[लक्ष्य 7]**: [विवरण]
+- **[लक्ष्य 8]**: [विवरण]
+
+## पृष्ठभूमि
+
+[वर्तमान स्थिति और सीमाओं का वर्णन करें जिन्हें यह स्पेसिफिकेशन संबोधित करता है]
+
+वर्तमान सीमाओं में शामिल हैं:
+- [सीमा 1]
+- [सीमा 2] 
+- [सीमा 3]
+- [सीमा 4]
+
+यह स्पेसिफिकेशन इन कमियों को [विवरण] द्वारा संबोधित करता है। [क्षमता] के माध्यम से, ट्रस्टग्राफ:
+- [लाभ 1]
+- [लाभ 2]
+- [लाभ 3]
+- [लाभ 4]
+
+## तकनीकी डिजाइन
+
+### आर्किटेक्चर
+
+कमांड-लाइन नॉलेज लोडिंग के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
+
+1. **[घटक 1]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+   
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+2. **[घटक 2]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+3. **[घटक 3]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+### डेटा मॉडल
+
+#### [डेटा मॉडल 1]
+
+[डेटा मॉडल और संरचना का विवरण]
+
+उदाहरण:
+```
+[Example data structure]
+```
+
+यह दृष्टिकोण निम्नलिखित की अनुमति देता है:
+- [लाभ 1]
+- [लाभ 2]
+- [लाभ 3]
+- [लाभ 4]
+
+### एपीआई (APIs)
+
+नए एपीआई (APIs):
+- [एपीआई विवरण 1]
+- [एपीआई विवरण 2]
+- [एपीआई विवरण 3]
+
+संशोधित एपीआई (APIs):
+- [संशोधित एपीआई 1] - [परिवर्तनों का विवरण]
+- [संशोधित एपीआई 2] - [परिवर्तनों का विवरण]
+
+### कार्यान्वयन विवरण
+
+[कार्यान्वयन दृष्टिकोण और परंपराएं]
+
+[अतिरिक्त कार्यान्वयन नोट्स]
+
+## सुरक्षा संबंधी विचार
+
+[इस कार्यान्वयन के लिए विशिष्ट सुरक्षा संबंधी विचार]
+
+## प्रदर्शन संबंधी विचार
+
+[प्रदर्शन संबंधी विचार और संभावित बाधाएं]
+
+## परीक्षण रणनीति
+
+[परीक्षण दृष्टिकोण और रणनीति]
+
+## माइग्रेशन योजना
+
+[यदि लागू हो, तो माइग्रेशन रणनीति]
+
+## समयरेखा
+
+[यदि निर्दिष्ट किया गया है, तो समयरेखा जानकारी]
+
+## अनुत्तरित प्रश्न
+
+- [अनुत्तरित प्रश्न 1]
+- [अनुत्तरित प्रश्न 2]
+
+## संदर्भ
+
+[यदि लागू हो, तो संदर्भ]

docs/tech-specs/__TEMPLATE.pt.md

@@ -0,0 +1,127 @@
+# Especificação Técnica de Carregamento de Conhecimento via Linha de Comando
+
+## Visão Geral
+
+Esta especificação descreve as interfaces de linha de comando para carregar conhecimento no TrustGraph, permitindo que os usuários ingiram dados de várias fontes por meio de ferramentas de linha de comando. A integração suporta quatro casos de uso primários:
+
+1. **[Caso de Uso 1]**: [Descrição]
+2. **[Caso de Uso 2]**: [Descrição]
+3. **[Caso de Uso 3]**: [Descrição]
+4. **[Caso de Uso 4]**: [Descrição]
+
+## Objetivos
+
+- **[Objetivo 1]**: [Descrição]
+- **[Objetivo 2]**: [Descrição]
+- **[Objetivo 3]**: [Descrição]
+- **[Objetivo 4]**: [Descrição]
+- **[Objetivo 5]**: [Descrição]
+- **[Objetivo 6]**: [Descrição]
+- **[Objetivo 7]**: [Descrição]
+- **[Objetivo 8]**: [Descrição]
+
+## Contexto
+
+[Descreva o estado atual e as limitações que esta especificação aborda]
+
+As limitações atuais incluem:
+- [Limitação 1]
+- [Limitação 2] 
+- [Limitação 3]
+- [Limitação 4]
+
+Esta especificação aborda essas lacunas ao [descrição]. Ao [capacidade], o TrustGraph pode:
+- [Benefício 1]
+- [Benefício 2]
+- [Benefício 3]
+- [Benefício 4]
+
+## Design Técnico
+
+### Arquitetura
+
+O carregamento de conhecimento via linha de comando requer os seguintes componentes técnicos:
+
+1. **[Componente 1]**
+   - [Descrição da funcionalidade do componente]
+   - [Características principais]
+   - [Pontos de integração]
+   
+   Módulo: [caminho-do-módulo]
+
+2. **[Componente 2]**
+   - [Descrição da funcionalidade do componente]
+   - [Características principais]
+   - [Pontos de integração]
+
+   Módulo: [caminho-do-módulo]
+
+3. **[Componente 3]**
+   - [Descrição da funcionalidade do componente]
+   - [Características principais]
+   - [Pontos de integração]
+
+   Módulo: [caminho-do-módulo]
+
+### Modelos de Dados
+
+#### [Modelo de Dados 1]
+
+[Descrição do modelo de dados e estrutura]
+
+Exemplo:
+```
+[Example data structure]
+```
+
+Esta abordagem permite:
+- [Benefício 1]
+- [Benefício 2]
+- [Benefício 3]
+- [Benefício 4]
+
+### APIs
+
+Novas APIs:
+- [Descrição da API 1]
+- [Descrição da API 2]
+- [Descrição da API 3]
+
+APIs modificadas:
+- [API modificada 1] - [Descrição das alterações]
+- [API modificada 2] - [Descrição das alterações]
+
+### Detalhes de implementação
+
+[Abordagem e convenções de implementação]
+
+[Notas adicionais de implementação]
+
+## Considerações de segurança
+
+[Considerações de segurança específicas para esta implementação]
+
+## Considerações de desempenho
+
+[Considerações de desempenho e possíveis gargalos]
+
+## Estratégia de testes
+
+[Abordagem e estratégia de testes]
+
+## Plano de migração
+
+[Estratégia de migração, se aplicável]
+
+## Cronograma
+
+[Informações sobre o cronograma, se especificadas]
+
+## Perguntas pendentes
+
+- [Pergunta pendente 1]
+- [Pergunta pendente 2]
+
+## Referências
+
+[Referências, se aplicável]

docs/tech-specs/__TEMPLATE.ru.md

@@ -0,0 +1,127 @@
+# Техническая спецификация загрузки знаний через командную строку
+
+## Обзор
+
+Эта спецификация описывает интерфейсы командной строки для загрузки знаний в TrustGraph, позволяя пользователям загружать данные из различных источников с помощью инструментов командной строки. Интеграция поддерживает четыре основных сценария использования:
+
+1. **[Сценарий использования 1]**: [Описание]
+2. **[Сценарий использования 2]**: [Описание]
+3. **[Сценарий использования 3]**: [Описание]
+4. **[Сценарий использования 4]**: [Описание]
+
+## Цели
+
+- **[Цель 1]**: [Описание]
+- **[Цель 2]**: [Описание]
+- **[Цель 3]**: [Описание]
+- **[Цель 4]**: [Описание]
+- **[Цель 5]**: [Описание]
+- **[Цель 6]**: [Описание]
+- **[Цель 7]**: [Описание]
+- **[Цель 8]**: [Описание]
+
+## Предыстория
+
+[Опишите текущее состояние и ограничения, которые решает эта спецификация]
+
+Текущие ограничения включают:
+- [Ограничение 1]
+- [Ограничение 2]
+- [Ограничение 3]
+- [Ограничение 4]
+
+Эта спецификация устраняет эти недостатки, [описание]. Благодаря [возможности], TrustGraph может:
+- [Преимущество 1]
+- [Преимущество 2]
+- [Преимущество 3]
+- [Преимущество 4]
+
+## Технический дизайн
+
+### Архитектура
+
+Загрузка знаний через командную строку требует следующих технических компонентов:
+
+1. **[Компонент 1]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+   
+   Модуль: [путь_к_модулю]
+
+2. **[Компонент 2]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+
+   Модуль: [путь_к_модулю]
+
+3. **[Компонент 3]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+
+   Модуль: [путь_к_модулю]
+
+### Модели данных
+
+#### [Модель данных 1]
+
+[Описание модели данных и ее структуры]
+
+Пример:
+```
+[Example data structure]
+```
+
+Этот подход позволяет:
+- [Преимущество 1]
+- [Преимущество 2]
+- [Преимущество 3]
+- [Преимущество 4]
+
+### API
+
+Новые API:
+- [Описание API 1]
+- [Описание API 2]
+- [Описание API 3]
+
+Измененные API:
+- [Измененный API 1] - [Описание изменений]
+- [Измененный API 2] - [Описание изменений]
+
+### Детали реализации
+
+[Подход к реализации и соглашения]
+
+[Дополнительные примечания по реализации]
+
+## Вопросы безопасности
+
+[Вопросы безопасности, специфичные для данной реализации]
+
+## Вопросы производительности
+
+[Вопросы производительности и потенциальные узкие места]
+
+## Стратегия тестирования
+
+[Подход и стратегия тестирования]
+
+## План миграции
+
+[Стратегия миграции, если применимо]
+
+## Сроки
+
+[Информация о сроках, если указана]
+
+## Открытые вопросы
+
+- [Открытый вопрос 1]
+- [Открытый вопрос 2]
+
+## Ссылки
+
+[Ссылки, если применимо]

docs/tech-specs/__TEMPLATE.sw.md

@@ -0,0 +1,127 @@
+# Vipimo vya Kiufundi vya Kujaza Habari Kupitia Amri ya Kamba
+
+## Muhtasari
+
+Vipimo hivi vinaelezea interface za amri ya kamba kwa ajili ya kujaza habari katika TrustGraph, na kuwezesha watumiaji kusambaza data kutoka vyanzo mbalimbali kupitia zana za amri ya kamba. Uunganishaji huu unaunga mkono matumizi manne makuu:
+
+1. **[Matumizi ya 1]**: [Maelezo]
+2. **[Matumizi ya 2]**: [Maelezo]
+3. **[Matumizi ya 3]**: [Maelezo]
+4. **[Matumizi ya 4]**: [Maelezo]
+
+## Lengo
+
+- **[Lengo la 1]**: [Maelezo]
+- **[Lengo la 2]**: [Maelezo]
+- **[Lengo la 3]**: [Maelezo]
+- **[Lengo la 4]**: [Maelezo]
+- **[Lengo la 5]**: [Maelezo]
+- **[Lengo la 6]**: [Maelezo]
+- **[Lengo la 7]**: [Maelezo]
+- **[Lengo la 8]**: [Maelezo]
+
+## Asili
+
+[Eleza hali ya sasa na vikwazo ambavyo vipimo hivi vinashughulikia]
+
+Vikwazo vya sasa ni pamoja na:
+- [Vikwazo 1]
+- [Vikwazo 2] 
+- [Vikwazo 3]
+- [Vikwazo 4]
+
+Vipimo hivi vinashughulikia pengo hizi kwa [maelezo]. Kwa [uwezo], TrustGraph inaweza:
+- [Faida 1]
+- [Faida 2]
+- [Faida 3]
+- [Faida 4]
+
+## Muundo wa Kiufundi
+
+### Usanifu
+
+Kujaza habari kupitia amri ya kamba inahitaji vipengele vifuatavyo vya kiufundi:
+
+1. **[Kipengele cha 1]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+   
+   Moduli: [njia-ya-moduli]
+
+2. **[Kipengele cha 2]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+
+   Moduli: [njia-ya-moduli]
+
+3. **[Kipengele cha 3]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+
+   Moduli: [njia-ya-moduli]
+
+### Mifano ya Data
+
+#### [Mifano ya Data 1]
+
+[Maelezo ya mfano wa data na muundo]
+
+Mfano:
+```
+[Example data structure]
+```
+
+Mbinu hii inaruhusu:
+- [Faida 1]
+- [Faida 2]
+- [Faida 3]
+- [Faida 4]
+
+### API
+
+API mpya:
+- [Maelezo ya API 1]
+- [Maelezo ya API 2]
+- [Maelezo ya API 3]
+
+API zilizobadilishwa:
+- [API iliyobadilishwa 1] - [Maelezo ya mabadiliko]
+- [API iliyobadilishwa 2] - [Maelezo ya mabadiliko]
+
+### Maelezo ya Utendaji
+
+[Mbinu na miongozo ya utendaji]
+
+[Maelezo ya ziada ya utendaji]
+
+## Masuala ya Usalama
+
+[Masuala ya usalama maalum kwa utendaji huu]
+
+## Masuala ya Utendaji
+
+[Masuala ya utendaji na vizuizi vinavyowezekana]
+
+## Mkakati wa Majaribio
+
+[Mbinu na mkakati wa majaribio]
+
+## Mpango wa Uhamisho
+
+[Mkakati wa uhamisho ikiwa unafaa]
+
+## Ratiba
+
+[Habari ya ratiba ikiwa imebainishwa]
+
+## Maswali Yaliyobaki
+
+- [Swali lililobaki 1]
+- [Swali lililobaki 2]
+
+## Marejeleo
+
+[Marejeleo ikiwa yanafaa]

docs/tech-specs/__TEMPLATE.tr.md

@@ -0,0 +1,127 @@
+# Komut Satırı ile Bilgi Yükleme Teknik Özellikleri
+
+## Genel Bakış
+
+Bu teknik özellik, TrustGraph'a bilgi yüklemek için komut satırı arayüzlerini tanımlar ve kullanıcıların komut satırı araçları aracılığıyla çeşitli kaynaklardan veri almasını sağlar. Bu entegrasyon, dört ana kullanım senaryosunu destekler:
+
+1. **[Kullanım Senaryosu 1]**: [Açıklama]
+2. **[Kullanım Senaryosu 2]**: [Açıklama]
+3. **[Kullanım Senaryosu 3]**: [Açıklama]
+4. **[Kullanım Senaryosu 4]**: [Açıklama]
+
+## Hedefler
+
+- **[Hedef 1]**: [Açıklama]
+- **[Hedef 2]**: [Açıklama]
+- **[Hedef 3]**: [Açıklama]
+- **[Hedef 4]**: [Açıklama]
+- **[Hedef 5]**: [Açıklama]
+- **[Hedef 6]**: [Açıklama]
+- **[Hedef 7]**: [Açıklama]
+- **[Hedef 8]**: [Açıklama]
+
+## Arka Plan
+
+[Mevcut durumu ve bu teknik özelliğin ele aldığı sınırlamaları açıklayın]
+
+Mevcut sınırlamalar şunlardır:
+- [Sınırlama 1]
+- [Sınırlama 2] 
+- [Sınırlama 3]
+- [Sınırlama 4]
+
+Bu teknik özellik, bu eksiklikleri [açıklama] ile giderir. [Yeteneği] sayesinde, TrustGraph şunları yapabilir:
+- [Fayda 1]
+- [Fayda 2]
+- [Fayda 3]
+- [Fayda 4]
+
+## Teknik Tasarım
+
+### Mimari
+
+Komut satırı ile bilgi yükleme, aşağıdaki teknik bileşenleri gerektirir:
+
+1. **[Bileşen 1]**
+   - [Bileşenin işlevselliğinin açıklaması]
+   - [Temel özellikler]
+   - [Entegrasyon noktaları]
+   
+   Modül: [modül-yolu]
+
+2. **[Bileşen 2]**
+   - [Bileşenin işlevselliğinin açıklaması]
+   - [Temel özellikler]
+   - [Entegrasyon noktaları]
+
+   Modül: [modül-yolu]
+
+3. **[Bileşen 3]**
+   - [Bileşenin işlevselliğinin açıklaması]
+   - [Temel özellikler]
+   - [Entegrasyon noktaları]
+
+   Modül: [modül-yolu]
+
+### Veri Modelleri
+
+#### [Veri Modeli 1]
+
+[Veri modelinin ve yapısının açıklaması]
+
+Örnek:
+```
+[Example data structure]
+```
+
+Bu yaklaşım şunları sağlar:
+- [Fayda 1]
+- [Fayda 2]
+- [Fayda 3]
+- [Fayda 4]
+
+### API'ler
+
+Yeni API'ler:
+- [API açıklaması 1]
+- [API açıklaması 2]
+- [API açıklaması 3]
+
+Değiştirilen API'ler:
+- [Değiştirilen API 1] - [Değişikliklerin açıklaması]
+- [Değiştirilen API 2] - [Değişikliklerin açıklaması]
+
+### Uygulama Detayları
+
+[Uygulama yaklaşımı ve kurallar]
+
+[Ek uygulama notları]
+
+## Güvenlik Hususları
+
+[Bu uygulamanın özel güvenlik hususları]
+
+## Performans Hususları
+
+[Performans hususları ve olası darboğazlar]
+
+## Test Stratejisi
+
+[Test yaklaşımı ve stratejisi]
+
+## Geçiş Planı
+
+[Gerekliyse geçiş stratejisi]
+
+## Zaman Çizelgesi
+
+[Belirtilmişse zaman çizelgesi bilgileri]
+
+## Açık Sorular
+
+- [Açık soru 1]
+- [Açık soru 2]
+
+## Referanslar
+
+[Gerekliyse referanslar]

docs/tech-specs/__TEMPLATE.zh-cn.md

@@ -0,0 +1,127 @@
+# 命令行加载知识的技术规范
+
+## 概述
+
+本规范描述了用于将知识加载到 TrustGraph 的命令行接口，使用户能够通过命令行工具从各种来源导入数据。该集成支持四个主要用例：
+
+1. **[用例 1]**: [描述]
+2. **[用例 2]**: [描述]
+3. **[用例 3]**: [描述]
+4. **[用例 4]**: [描述]
+
+## 目标
+
+- **[目标 1]**: [描述]
+- **[目标 2]**: [描述]
+- **[目标 3]**: [描述]
+- **[目标 4]**: [描述]
+- **[目标 5]**: [描述]
+- **[目标 6]**: [描述]
+- **[目标 7]**: [描述]
+- **[目标 8]**: [描述]
+
+## 背景
+
+[描述当前状态以及本规范所解决的限制]
+
+当前的限制包括：
+- [限制 1]
+- [限制 2]
+- [限制 3]
+- [限制 4]
+
+本规范通过 [描述] 解决了这些差距。 通过 [功能]，TrustGraph 可以：
+- [优势 1]
+- [优势 2]
+- [优势 3]
+- [优势 4]
+
+## 技术设计
+
+### 架构
+
+命令行知识加载需要以下技术组件：
+
+1. **[组件 1]**
+   - [组件功能描述]
+   - [主要特性]
+   - [集成点]
+   
+   模块: [module-path]
+
+2. **[组件 2]**
+   - [组件功能描述]
+   - [主要特性]
+   - [集成点]
+
+   模块: [module-path]
+
+3. **[组件 3]**
+   - [组件功能描述]
+   - [主要特性]
+   - [集成点]
+
+   模块: [module-path]
+
+### 数据模型
+
+#### [数据模型 1]
+
+[数据模型和结构的描述]
+
+示例:
+```
+[Example data structure]
+```
+
+这种方法允许：
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+- [Benefit 4]
+
+### APIs
+
+新的 API：
+- [API description 1]
+- [API description 2]
+- [API description 3]
+
+修改后的 API：
+- [Modified API 1] - [Description of changes]
+- [Modified API 2] - [Description of changes]
+
+### 实现细节
+
+[Implementation approach and conventions]
+
+[Additional implementation notes]
+
+## 安全性考虑
+
+[Security considerations specific to this implementation]
+
+## 性能考虑
+
+[Performance considerations and potential bottlenecks]
+
+## 测试策略
+
+[Testing approach and strategy]
+
+## 迁移计划
+
+[Migration strategy if applicable]
+
+## 时间线
+
+[Timeline information if specified]
+
+## 待解决问题
+
+- [Open question 1]
+- [Open question 2]
+
+## 参考文献
+
+[References if applicable]

docs/tech-specs/agent-explainability.ar.md

@@ -0,0 +1,272 @@
+# شرح عمل الوكيل: تسجيل المصدر
+
+## نظرة عامة
+
+أضف تسجيل المصدر إلى حلقة الوكيل في React حتى يمكن تتبع جلسات الوكيل وتصحيحها باستخدام نفس البنية التحتية للشرح كما هو الحال في GraphRAG.
+
+**قرارات التصميم:**
+الكتابة إلى `urn:graph:retrieval` (رسم بياني للشرح العام)
+سلسلة اعتماد خطية في الوقت الحالي (تحليل N → تم اشتقاقه من → تحليل N-1)
+الأدوات هي صناديق سوداء (تسجيل الإدخال/الإخراج فقط)
+دعم الرسم البياني الموجه غير المتصل (DAG) مؤجل للتكرار المستقبلي
+
+## أنواع الكيانات
+
+يستخدم كل من GraphRAG والوكيل PROV-O كعلم الوجود الأساسي مع أنواع فرعية خاصة بـ TrustGraph:
+
+### أنواع GraphRAG
+| الكيان | نوع PROV-O | أنواع TG | الوصف |
+|--------|-------------|----------|-------------|
+| سؤال | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | استعلام المستخدم |
+| استكشاف | `prov:Entity` | `tg:Exploration` | الحواف المستردة من الرسم البياني المعرفي |
+| تركيز | `prov:Entity` | `tg:Focus` | الحواف المحددة مع الاستدلال |
+| توليف | `prov:Entity` | `tg:Synthesis` | الإجابة النهائية |
+
+### أنواع الوكيل
+| الكيان | نوع PROV-O | أنواع TG | الوصف |
+|--------|-------------|----------|-------------|
+| سؤال | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | استعلام المستخدم |
+| تحليل | `prov:Entity` | `tg:Analysis` | كل دورة تفكير/فعل/ملاحظة |
+| استنتاج | `prov:Entity` | `tg:Conclusion` | الإجابة النهائية |
+
+### أنواع RAG للوثائق
+| الكيان | نوع PROV-O | أنواع TG | الوصف |
+|--------|-------------|----------|-------------|
+| سؤال | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | استعلام المستخدم |
+| استكشاف | `prov:Entity` | `tg:Exploration` | أجزاء مستردة من مستودع المستندات |
+| توليف | `prov:Entity` | `tg:Synthesis` | الإجابة النهائية |
+
+**ملاحظة:** يستخدم RAG للوثائق مجموعة فرعية من أنواع GraphRAG (لا توجد خطوة "تركيز" نظرًا لعدم وجود مرحلة اختيار/استدلال للحواف).
+
+### أنواع فرعية للأسئلة
+
+تشترك جميع كيانات "سؤال" في `tg:Question` كنوع أساسي ولكنها تحتوي على نوع فرعي محدد لتحديد آلية الاسترداد:
+
+| النوع الفرعي | نمط URI | الآلية |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG للرسم البياني المعرفي |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG للوثائق/الأجزاء |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | وكيل ReAct |
+
+يتيح ذلك الاستعلام عن جميع الأسئلة عبر `tg:Question` مع التصفية حسب آلية معينة عبر النوع الفرعي.
+
+## نموذج المصدر
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### نموذج تتبع أصل المستندات (Document RAG Provenance Model)
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## التغييرات المطلوبة
+
+### 1. تغييرات المخطط
+
+**الملف:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+أضف الحقول `session_id` و `collection` إلى `AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**الملف:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+تحديث المترجم للتعامل مع `session_id` و `collection` في كل من `to_pulsar()` و `from_pulsar()`.
+
+### 2. إضافة مُنتج الشفافية إلى خدمة الوكيل
+
+**الملف:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+تسجيل مُنتج "الشفافية" (بنفس النمط مثل GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. توليد الثلاثيات المتعلقة بالأصل.
+
+**الملف:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+إنشاء دوال مساعدة (مشابهة لدوال `question_triples` و `exploration_triples`، إلخ في GraphRAG):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. تعريفات الأنواع
+
+**الملف:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+أضف أنواع الكيانات الخاصة بالتفسير والعبارات الخاصة بالوكيل:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## الملفات التي تم تعديلها
+
+| الملف | التغيير |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | إضافة session_id و collection إلى AgentRequest |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | تحديث المترجم للحقول الجديدة |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | إضافة أنواع الكيانات، وعبارات الوكيل، وأنواع Document RAG |
+| `trustgraph-base/trustgraph/provenance/triples.py` | إضافة أنواع TG إلى أدوات بناء الثلاثيات GraphRAG، وإضافة أدوات بناء الثلاثيات Document RAG |
+| `trustgraph-base/trustgraph/provenance/uris.py` | إضافة مولدات URI لـ Document RAG |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | تصدير الأنواع والعبارات الجديدة ووظائف Document RAG |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | إضافة explain_id و explain_graph إلى DocumentRagResponse |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | تحديث DocumentRagResponseTranslator للحقول الخاصة بالقدرة على الشرح |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | إضافة منطق الإنتاج والتسجيل الخاص بالقدرة على الشرح |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | إضافة استدعاء رد (callback) خاص بالقدرة على الشرح وإصدار ثلاثيات المصدر |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | إضافة مُنتج القدرة على الشرح وربطه بالاستدعاء الردي |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | معالجة أنواع تتبع الوكيل |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | عرض جلسات الوكيل جنبًا إلى جنب مع GraphRAG |
+
+## الملفات التي تم إنشاؤها
+
+| الملف | الغرض |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | مولدات ثلاثيات خاصة بالوكيل |
+
+## تحديثات واجهة سطر الأوامر (CLI)
+
+**الكشف:** كل من GraphRAG والأسئلة الخاصة بالوكيل لهما نوع `tg:Question`. يتم التمييز بينهما بواسطة:
+1. نمط URI: `urn:trustgraph:agent:` مقابل `urn:trustgraph:question:`
+2. الكيانات المشتقة: `tg:Analysis` (الوكيل) مقابل `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+يعرض عمود النوع (الوكيل مقابل GraphRAG)
+
+**`show_explain_trace.py`:**
+يكتشف تلقائيًا نوع التتبع
+يعرض عرض الوكيل: سؤال → خطوة(ات) تحليل → استنتاج
+
+## التوافق مع الإصدارات السابقة
+
+`session_id` افتراضيًا إلى `""` - تعمل الطلبات القديمة، ولكن لن تحتوي على معلومات المصدر |
+`collection` افتراضيًا إلى `"default"` - حل بديل معقول |
+تتعامل واجهة سطر الأوامر (CLI) بأمان مع كلا نوعي التتبع |
+
+## التحقق
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## الأعمال المستقبلية (ليست جزءًا من هذا التعديل)
+
+تبعيات الرسم البياني الموجه (عندما يعتمد التحليل N على نتائج تحليلات سابقة متعددة)
+ربط المصادر الخاص بالأدوات (KnowledgeQuery ← تتبع GraphRAG الخاص به)
+إرسال المصادر بشكل مستمر (إرسال البيانات أثناء العمل، وليس دفعة واحدة في النهاية)

docs/tech-specs/agent-explainability.es.md

@@ -0,0 +1,272 @@
+# Explicabilidad del Agente: Registro de Origen
+
+## Resumen
+
+Agregar el registro de origen al bucle del agente de React para que las sesiones del agente puedan ser rastreadas y depuradas utilizando la misma infraestructura de explicabilidad que GraphRAG.
+
+**Decisiones de Diseño:**
+- Escribir en `urn:graph:retrieval` (grafo de explicabilidad genérico)
+- Cadena de dependencia lineal por ahora (análisis N → derivado de → análisis N-1)
+- Las herramientas son cajas negras opacas (registrar solo la entrada/salida)
+- El soporte de DAG se pospone a una iteración futura
+
+## Tipos de Entidades
+
+Tanto GraphRAG como Agent utilizan PROV-O como la ontología base con subtipos específicos de TrustGraph:
+
+### Tipos de GraphRAG
+| Entidad | Tipo PROV-O | Tipos TG | Descripción |
+|--------|-------------|----------|-------------|
+| Pregunta | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | La consulta del usuario |
+| Exploración | `prov:Entity` | `tg:Exploration` | Bordes recuperados del grafo de conocimiento |
+| Enfoque | `prov:Entity` | `tg:Focus` | Bordes seleccionados con razonamiento |
+| Síntesis | `prov:Entity` | `tg:Synthesis` | Respuesta final |
+
+### Tipos de Agente
+| Entidad | Tipo PROV-O | Tipos TG | Descripción |
+|--------|-------------|----------|-------------|
+| Pregunta | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | La consulta del usuario |
+| Análisis | `prov:Entity` | `tg:Analysis` | Cada ciclo de pensar/actuar/observar |
+| Conclusión | `prov:Entity` | `tg:Conclusion` | Respuesta final |
+
+### Tipos de Document RAG
+| Entidad | Tipo PROV-O | Tipos TG | Descripción |
+|--------|-------------|----------|-------------|
+| Pregunta | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | La consulta del usuario |
+| Exploración | `prov:Entity` | `tg:Exploration` | Fragmentos recuperados del almacén de documentos |
+| Síntesis | `prov:Entity` | `tg:Synthesis` | Respuesta final |
+
+**Nota:** Document RAG utiliza un subconjunto de los tipos de GraphRAG (no hay un paso de "Enfoque" ya que no hay una fase de selección/razonamiento de bordes).
+
+### Subtipos de Pregunta
+
+Todas las entidades de "Pregunta" comparten `tg:Question` como un tipo base, pero tienen un subtipo específico para identificar el mecanismo de recuperación:
+
+| Subtipo | Patrón URI | Mecanismo |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG de grafo de conocimiento |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG de documento/fragmento |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | Agente ReAct |
+
+Esto permite consultar todas las preguntas a través de `tg:Question` mientras se filtra por un mecanismo específico a través del subtipo.
+
+## Modelo de Origen
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### Modelo de Origen (Provenance) del Documento RAG
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## Cambios Requeridos
+
+### 1. Cambios en el Esquema
+
+**Archivo:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+Agregar los campos `session_id` y `collection` a `AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**Archivo:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+Actualizar el traductor para manejar `session_id` y `collection` tanto en `to_pulsar()` como en `from_pulsar()`.
+
+### 2. Agregar un Productor de Explicabilidad al Servicio de Agente
+
+**Archivo:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+Registrar un productor de "explicabilidad" (mismo patrón que GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. Generación de Triples de Proveniencia
+
+**Archivo:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+Crear funciones auxiliares (similares a `question_triples`, `exploration_triples`, etc. de GraphRAG):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. Definiciones de tipo
+
+**Archivo:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+Agregar tipos de entidad de explicabilidad y predicados de agente:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## Archivos Modificados
+
+| Archivo | Cambio |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | Agregar session_id y collection a AgentRequest |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Actualizar el traductor para nuevos campos |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | Agregar tipos de entidad, predicados de agente y predicados de Document RAG |
+| `trustgraph-base/trustgraph/provenance/triples.py` | Agregar tipos de TG a los constructores de triples de GraphRAG, agregar constructores de triples de Document RAG |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Agregar generadores de URI de Document RAG |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | Exportar nuevos tipos, predicados y funciones de Document RAG |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Agregar explain_id y explain_graph a DocumentRagResponse |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Actualizar DocumentRagResponseTranslator para campos de explicabilidad |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | Agregar lógica de productor y registro de explicabilidad |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Agregar devolución de llamada de explicabilidad y emitir triples de procedencia |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Agregar productor de explicabilidad y conectar la devolución de llamada |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Manejar tipos de traza de agente |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Listar sesiones de agente junto con GraphRAG |
+
+## Archivos Creados
+
+| Archivo | Propósito |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Generadores de triples específicos del agente |
+
+## Actualizaciones de la CLI
+
+**Detección:** Tanto GraphRAG como las Preguntas del Agente tienen el tipo `tg:Question`. Se distinguen por:
+1. Patrón de URI: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
+2. Entidades derivadas: `tg:Analysis` (agente) vs `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+- Muestra la columna Tipo (Agente vs GraphRAG)
+
+**`show_explain_trace.py`:**
+- Detecta automáticamente el tipo de traza
+- La representación del agente muestra: Pregunta → Paso(s) de análisis → Conclusión
+
+## Compatibilidad con versiones anteriores
+
+- `session_id` por defecto es `""` - las solicitudes antiguas funcionan, pero no tendrán procedencia
+- `collection` por defecto es `"default"` - alternativa razonable
+- La CLI maneja correctamente ambos tipos de traza
+
+## Verificación
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## Trabajo Futuro (No Incluido en esta Solicitud de Incorporación)
+
+- Dependencias de DAG (cuando el análisis N utiliza resultados de múltiples análisis anteriores)
+- Enlace de procedencia específico de la herramienta (KnowledgeQuery → su traza GraphRAG)
+- Emisión de procedencia en streaming (emitir a medida que se avanza, no en lote al final)

docs/tech-specs/agent-explainability.he.md

@@ -0,0 +1,272 @@
+# הסברתיות של סוכן: רישום מקורות
+
+## סקירה כללית
+
+הוספת רישום מקורות ללולאת הסוכן של React כך שניתן יהיה לעקוב אחר סשנים של סוכנים ולבצע ניפוי באגים באמצעות אותה תשתית הסברתיות כמו GraphRAG.
+
+**החלטות עיצוב:**
+כתיבה ל-`urn:graph:retrieval` (גרף הסברתיות גנרי)
+שרשרת תלות ליניארית כרגע (ניתוח N → נגזר מ → ניתוח N-1)
+כלים הם תיבות שחורות (רישום קלט/פלט בלבד)
+תמיכה ב-DAG (גרף מכוון) נדחית למהלך עתידי
+
+## סוגי ישויות
+
+גם GraphRAG וגם Agent משתמשים ב-PROV-O כאונטולוגיה בסיסית עם תת-סוגים ספציפיים ל-TrustGraph:
+
+### סוגי GraphRAG
+| ישות | סוג PROV-O | סוגי TG | תיאור |
+|--------|-------------|----------|-------------|
+| שאלה | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | השאלה של המשתמש |
+| חקירה | `prov:Entity` | `tg:Exploration` | צמתים שאוחזרו מגרף ידע |
+| מיקוד | `prov:Entity` | `tg:Focus` | צמתים שנבחרו עם נימוק |
+| סינתזה | `prov:Entity` | `tg:Synthesis` | תשובה סופית |
+
+### סוגי סוכן
+| ישות | סוג PROV-O | סוגי TG | תיאור |
+|--------|-------------|----------|-------------|
+| שאלה | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | השאלה של המשתמש |
+| ניתוח | `prov:Entity` | `tg:Analysis` | כל מחזור חשיבה/פעולה/תצפית |
+| מסקנה | `prov:Entity` | `tg:Conclusion` | תשובה סופית |
+
+### סוגי RAG של מסמכים
+| ישות | סוג PROV-O | סוגי TG | תיאור |
+|--------|-------------|----------|-------------|
+| שאלה | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | השאלה של המשתמש |
+| חקירה | `prov:Entity` | `tg:Exploration` | חלקים שאוחזרו מחנות מסמכים |
+| סינתזה | `prov:Entity` | `tg:Synthesis` | תשובה סופית |
+
+**הערה:** RAG של מסמכים משתמש בתת-קבוצה של סוגים של GraphRAG (אין שלב מיקוד מכיוון שאין שלב בחירת/נימוק צמתים).
+
+### תת-סוגים של שאלה
+
+כל ישויות השאלה חולקות את `tg:Question` כסוג בסיסי אך יש להן תת-סוג ספציפי כדי לזהות את מנגנון השליפה:
+
+| תת-סוג | תבנית URI | מנגנון |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG של גרף ידע |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG של מסמכים/חלקים |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | סוכן ReAct |
+
+זה מאפשר שאילתא של כל השאלות באמצעות `tg:Question` תוך סינון לפי מנגנון ספציפי באמצעות תת-הסוג.
+
+## מודל מקורות
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### מודל מקור (Provenance) של מסמכים בשיטת RAG
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## שינויים נדרשים
+
+### 1. שינויים בסכימה
+
+**קובץ:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+הוסף את השדות `session_id` ו-`collection` ל-`AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**קובץ:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+עדכון המתרגם כדי לטפל ב-`session_id` וב-`collection` הן ב-`to_pulsar()` והן ב-`from_pulsar()`.
+
+### 2. הוספת יצרן הסברות לשירות הסוכנים
+
+**קובץ:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+רישום יצרן "הסברות" (באותו דפוס כמו GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. יצירת משולש מוצא
+
+**קובץ:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+צור פונקציות עזר (בדומה ל-`question_triples`, `exploration_triples` וכו' של GraphRAG):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. הגדרות סוג
+
+**קובץ:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+הוסף סוגי ישויות הסבר ופרדיקטים של סוכנים:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## קבצים ששונו
+
+| קובץ | שינוי |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | הוספת session_id ו-collection ל-AgentRequest |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | עדכון מתרגם עבור שדות חדשים |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | הוספת סוגי ישויות, טענות של סוכן וטענות של Document RAG |
+| `trustgraph-base/trustgraph/provenance/triples.py` | הוספת סוגי TG לבונים של משולשים של GraphRAG, הוספת בונים של משולשים של Document RAG |
+| `trustgraph-base/trustgraph/provenance/uris.py` | הוספת יוצרי URI של Document RAG |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | ייצוא סוגים, טענות ופונקציות חדשות של Document RAG |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | הוספת explain_id ו-explain_graph ל-DocumentRagResponse |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | עדכון DocumentRagResponseTranslator עבור שדות הסברתיות |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | הוספת מפיק הסברתיות + לוגיקת הקלטה |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | הוספת קריאה חוזרת של הסברתיות ופליטת משולשים של מקור |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | הוספת מפיק הסברתיות וחיבור הקריאה החוזרת |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | טיפול בסוגי מעקב של סוכן |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | הצגת סשנים של סוכן לצד GraphRAG |
+
+## קבצים שנוצרו
+
+| קובץ | מטרה |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | יוצרי משולשים ספציפיים לסוכן |
+
+## עדכוני CLI
+
+**זיהוי:** גם לשאלות GraphRAG וגם לשאלות סוכן יש סוג `tg:Question`. מובחנים על ידי:
+1. תבנית URI: `urn:trustgraph:agent:` לעומת `urn:trustgraph:question:`
+2. ישויות נגזרות: `tg:Analysis` (סוכן) לעומת `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+מציג את עמודת הסוג (סוכן לעומת GraphRAG)
+
+**`show_explain_trace.py`:**
+מזהה אוטומטית את סוג המעקב
+הצגת סוכן מציגה: שאלה → שלב(ים) של ניתוח → מסקנה
+
+## תאימות לאחור
+
+`session_id` כברירת מחדל הוא `""` - בקשות ישנות עובדות, פשוט לא יהיו להן נתונים של מקור
+`collection` כברירת מחדל הוא `"default"` - חזרה סבירה
+ה-CLI מטפל בצורה חלקה בשני סוגי המעקב
+
+## אימות
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## עבודה עתידית (לא בבקשה הזו)
+
+תלותיות DAG (כאשר ניתוח N משתמש בתוצאות ממספר ניתוחים קודמים)
+קישור מקורות מידע ספציפי לכלי (KnowledgeQuery → המעקב GraphRAG שלו)
+פליטת מקורות מידע בסטרימינג (לשלוח תוך כדי פעולה, ולא במקשה בסוף)

docs/tech-specs/agent-explainability.hi.md

@@ -0,0 +1,272 @@
+# एजेंट स्पष्टता: उत्पत्ति रिकॉर्डिंग
+
+## अवलोकन
+
+रिएक्ट एजेंट लूप में उत्पत्ति रिकॉर्डिंग जोड़ें ताकि एजेंट सत्रों को ट्रैक और डीबग किया जा सके, जो कि ग्राफआरएजी के समान स्पष्टता बुनियादी ढांचे का उपयोग करके किया जा सके।
+
+**डिजाइन निर्णय:**
+`urn:graph:retrieval` (सामान्य स्पष्टता ग्राफ) में लिखें
+फिलहाल रैखिक निर्भरता श्रृंखला (विश्लेषण N → wasDerivedFrom → विश्लेषण N-1)
+उपकरण अपार ब्लैक बॉक्स हैं (केवल इनपुट/आउटपुट रिकॉर्ड करें)
+डीएजी समर्थन भविष्य के पुनरावृत्ति के लिए स्थगित है
+
+## इकाई प्रकार
+
+ग्राफआरएजी और एजेंट दोनों ही ट्रस्टग्राफ-विशिष्ट उपप्रकारों के साथ पीआरओवी-ओ को आधार ऑन्टोलॉजी के रूप में उपयोग करते हैं:
+
+### ग्राफआरएजी प्रकार
+| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
+|--------|-------------|----------|-------------|
+| प्रश्न | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | उपयोगकर्ता का प्रश्न |
+| अन्वेषण | `prov:Entity` | `tg:Exploration` | ज्ञान ग्राफ से प्राप्त किनारे |
+| फोकस | `prov:Entity` | `tg:Focus` | तर्क के साथ चयनित किनारे |
+| संश्लेषण | `prov:Entity` | `tg:Synthesis` | अंतिम उत्तर |
+
+### एजेंट प्रकार
+| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
+|--------|-------------|----------|-------------|
+| प्रश्न | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | उपयोगकर्ता का प्रश्न |
+| विश्लेषण | `prov:Entity` | `tg:Analysis` | प्रत्येक सोच/कार्य/अवलोकन चक्र |
+| निष्कर्ष | `prov:Entity` | `tg:Conclusion` | अंतिम उत्तर |
+
+### दस्तावेज़ आरएजी प्रकार
+| इकाई | पीआरओवी-ओ प्रकार | टीजी प्रकार | विवरण |
+|--------|-------------|----------|-------------|
+| प्रश्न | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | उपयोगकर्ता का प्रश्न |
+| अन्वेषण | `prov:Entity` | `tg:Exploration` | दस्तावेज़ भंडार से प्राप्त टुकड़े |
+| संश्लेषण | `prov:Entity` | `tg:Synthesis` | अंतिम उत्तर |
+
+**ध्यान दें:** दस्तावेज़ आरएजी ग्राफआरएजी के प्रकारों का एक उपसमुच्चय का उपयोग करता है (कोई फोकस चरण नहीं है क्योंकि कोई किनारा चयन/तर्क चरण नहीं है)।
+
+### प्रश्न उपप्रकार
+
+सभी प्रश्न इकाइयों में `tg:Question` को एक आधार प्रकार के रूप में साझा किया जाता है, लेकिन पुनर्प्राप्ति तंत्र की पहचान करने के लिए एक विशिष्ट उपप्रकार होता है:
+
+| उपप्रकार | यूआरआई पैटर्न | तंत्र |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | ज्ञान ग्राफ आरएजी |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | दस्तावेज़/टुकड़ा आरएजी |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | रीएक्ट एजेंट |
+
+यह सभी प्रश्नों को `tg:Question` के माध्यम से क्वेरी करने की अनुमति देता है, जबकि उपप्रकार के माध्यम से विशिष्ट तंत्र द्वारा फ़िल्टर किया जा सकता है।
+
+## उत्पत्ति मॉडल
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### दस्तावेज़ आरएजी उत्पत्ति मॉडल
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## आवश्यक परिवर्तन
+
+### 1. स्कीमा परिवर्तन
+
+**फ़ाइल:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+`AgentRequest` में `session_id` और `collection` फ़ील्ड जोड़ें:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**फ़ाइल:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+अनुवादक को `session_id` और `collection` को `to_pulsar()` और `from_pulsar()` दोनों में संभालने के लिए अपडेट करें।
+
+### 2. एजेंट सेवा में "एक्सप्लेनेबिलिटी" उत्पादक जोड़ें
+
+**फ़ाइल:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+एक "एक्सप्लेनेबिलिटी" उत्पादक को पंजीकृत करें (ग्राफआरएजी के समान पैटर्न):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. उत्पत्ति त्रिक निर्माण
+
+**फ़ाइल:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+सहायक फ़ंक्शन बनाएँ (ग्राफ़आरएजी के `question_triples`, `exploration_triples`, आदि के समान):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. प्रकार की परिभाषाएँ
+
+**फ़ाइल:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+व्याख्यात्मकता इकाई प्रकार और एजेंट विधेयकों को जोड़ें:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## संशोधित फ़ाइलें
+
+| फ़ाइल | परिवर्तन |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | AgentRequest में session_id और collection जोड़ें |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | नए फ़ील्ड के लिए ट्रांसलेटर को अपडेट करें |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | एंटिटी प्रकार, एजेंट प्रेडिकेट और Document RAG प्रेडिकेट जोड़ें |
+| `trustgraph-base/trustgraph/provenance/triples.py` | GraphRAG ट्रिपल बिल्डरों में TG प्रकार जोड़ें, Document RAG ट्रिपल बिल्डर जोड़ें |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Document RAG URI जनरेटर जोड़ें |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | नए प्रकार, प्रेडिकेट और Document RAG फ़ंक्शन निर्यात करें |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | DocumentRagResponse में explain_id और explain_graph जोड़ें |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | व्याख्यात्मक फ़ील्ड के लिए DocumentRagResponseTranslator को अपडेट करें |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | व्याख्यात्मक उत्पादक + रिकॉर्डिंग लॉजिक जोड़ें |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | व्याख्यात्मक कॉलबैक जोड़ें और प्रोवेनेंस ट्रिपल उत्सर्जित करें |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | व्याख्यात्मक उत्पादक जोड़ें और कॉलबैक को कनेक्ट करें |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | एजेंट ट्रेस प्रकारों को संभालें |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | GraphRAG के साथ एजेंट सत्रों को सूचीबद्ध करें |
+
+## बनाई गई फ़ाइलें
+
+| फ़ाइल | उद्देश्य |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | एजेंट-विशिष्ट ट्रिपल जनरेटर |
+
+## CLI अपडेट
+
+**पहचान:** GraphRAG और Agent Questions दोनों में `tg:Question` प्रकार होता है। निम्नलिखित द्वारा पहचाना जाता है:
+1. URI पैटर्न: `urn:trustgraph:agent:` बनाम `urn:trustgraph:question:`
+2. व्युत्पन्न एंटिटीज: `tg:Analysis` (एजेंट) बनाम `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+टाइप कॉलम दिखाता है (एजेंट बनाम GraphRAG)
+
+**`show_explain_trace.py`:**
+स्वचालित रूप से ट्रेस प्रकार का पता लगाता है
+एजेंट रेंडरिंग दिखाता है: प्रश्न → विश्लेषण चरण(s) → निष्कर्ष
+
+## पिछली अनुकूलता
+
+`session_id` डिफ़ॉल्ट रूप से `""` होता है - पुराने अनुरोध काम करते हैं, लेकिन उनमें प्रोवेनेंस नहीं होगा
+`collection` डिफ़ॉल्ट रूप से `"default"` होता है - उचित बैकअप
+CLI दोनों ट्रेस प्रकारों को आसानी से संभालता है
+
+## सत्यापन
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## भविष्य की योजनाएं (इस पुल अनुरोध में नहीं)
+
+डीएजी निर्भरताएँ (जब विश्लेषण एन, पिछले कई विश्लेषणों के परिणामों का उपयोग करता है)
+टूल-विशिष्ट उत्पत्ति लिंकिंग (नॉलेजक्वेरी → इसका ग्राफआरएजी ट्रेस)
+स्ट्रीमिंग उत्पत्ति उत्सर्जन (जैसे-जैसे उत्पन्न होता है, अंत में बैच न करें)

docs/tech-specs/agent-explainability.pt.md

@@ -0,0 +1,272 @@
+# Explicabilidade do Agente: Registro de Proveniência
+
+## Visão Geral
+
+Adicionar o registro de proveniência ao loop do agente React para que as sessões do agente possam ser rastreadas e depuradas usando a mesma infraestrutura de explicabilidade do GraphRAG.
+
+**Decisões de Design:**
+- Escrever em `urn:graph:retrieval` (grafo de explicabilidade genérico)
+- Cadeia de dependência linear por enquanto (análise N → foiDerivadoDe → análise N-1)
+- As ferramentas são caixas pretas (registrar apenas entrada/saída)
+- Suporte a DAG (Directed Acyclic Graph - Grafo Acíclico Direcionado) adiado para uma iteração futura
+
+## Tipos de Entidade
+
+Tanto o GraphRAG quanto o Agent usam PROV-O como a ontologia base, com subtipos específicos do TrustGraph:
+
+### Tipos do GraphRAG
+| Entidade | Tipo PROV-O | Tipos TG | Descrição |
+|--------|-------------|----------|-------------|
+| Pergunta | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | A consulta do usuário |
+| Exploração | `prov:Entity` | `tg:Exploration` | Arestas recuperadas do grafo de conhecimento |
+| Foco | `prov:Entity` | `tg:Focus` | Arestas selecionadas com raciocínio |
+| Síntese | `prov:Entity` | `tg:Synthesis` | Resposta final |
+
+### Tipos do Agente
+| Entidade | Tipo PROV-O | Tipos TG | Descrição |
+|--------|-------------|----------|-------------|
+| Pergunta | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | A consulta do usuário |
+| Análise | `prov:Entity` | `tg:Analysis` | Cada ciclo de pensar/agir/observar |
+| Conclusão | `prov:Entity` | `tg:Conclusion` | Resposta final |
+
+### Tipos do Document RAG
+| Entidade | Tipo PROV-O | Tipos TG | Descrição |
+|--------|-------------|----------|-------------|
+| Pergunta | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | A consulta do usuário |
+| Exploração | `prov:Entity` | `tg:Exploration` | Trechos recuperados do armazenamento de documentos |
+| Síntese | `prov:Entity` | `tg:Synthesis` | Resposta final |
+
+**Observação:** O Document RAG usa um subconjunto dos tipos do GraphRAG (sem a etapa de Foco, pois não há seleção/raciocínio de arestas).
+
+### Subtipos de Pergunta
+
+Todas as entidades de Pergunta compartilham `tg:Question` como um tipo base, mas têm um subtipo específico para identificar o mecanismo de recuperação:
+
+| Subtipo | Padrão URI | Mecanismo |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG de grafo de conhecimento |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG de documento/trecho |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | Agente ReAct |
+
+Isso permite consultar todas as perguntas via `tg:Question`, filtrando por mecanismo específico através do subtipo.
+
+## Modelo de Proveniência
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### Modelo de Proveniência de Documentos RAG
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## Alterações Necessárias
+
+### 1. Alterações no Esquema
+
+**Arquivo:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+Adicionar os campos `session_id` e `collection` a `AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**Arquivo:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+Atualizar o tradutor para lidar com `session_id` e `collection` tanto em `to_pulsar()` quanto em `from_pulsar()`.
+
+### 2. Adicionar Produtor de Explicabilidade ao Serviço de Agente
+
+**Arquivo:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+Registrar um "produtor de explicabilidade" (mesmo padrão do GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. Geração de Triplas de Proveniência
+
+**Arquivo:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+Crie funções auxiliares (semelhantes a `question_triples`, `exploration_triples`, etc. do GraphRAG):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. Definições de Tipo
+
+**Arquivo:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+Adicionar tipos de entidade de explicabilidade e predicados de agente:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## Arquivos Modificados
+
+| Arquivo | Alteração |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | Adiciona session_id e collection a AgentRequest |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Atualiza o tradutor para novos campos |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | Adiciona tipos de entidade, predicados de agente e predicados Document RAG |
+| `trustgraph-base/trustgraph/provenance/triples.py` | Adiciona tipos TG aos construtores de triplas GraphRAG, adiciona construtores de triplas Document RAG |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Adiciona geradores de URI Document RAG |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | Exporta novos tipos, predicados e funções Document RAG |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Adiciona explain_id e explain_graph a DocumentRagResponse |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Atualiza DocumentRagResponseTranslator para campos de explicabilidade |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | Adiciona lógica de produção e gravação de explicabilidade |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Adiciona callback de explicabilidade e emite triplas de procedência |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Adiciona produtor de explicabilidade e conecta o callback |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Lida com tipos de rastreamento de agente |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Lista sessões de agente junto com GraphRAG |
+
+## Arquivos Criados
+
+| Arquivo | Propósito |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Geradores de triplas específicos para agente |
+
+## Atualizações da CLI
+
+**Detecção:** Tanto GraphRAG quanto Agent Questions têm o tipo `tg:Question`. Distinguido por:
+1. Padrão de URI: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
+2. Entidades derivadas: `tg:Analysis` (agente) vs `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+- Mostra a coluna Tipo (Agente vs GraphRAG)
+
+**`show_explain_trace.py`:**
+- Detecta automaticamente o tipo de rastreamento
+- A renderização do agente mostra: Pergunta → Etapa(s) de análise → Conclusão
+
+## Compatibilidade com versões anteriores
+
+- `session_id` padrão é `""` - solicitações antigas funcionam, mas não terão procedência
+- `collection` padrão é `"default"` - fallback razoável
+- A CLI lida graciosamente com ambos os tipos de rastreamento
+
+## Verificação
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## Trabalhos Futuros (Não Neste PR)
+
+- Dependências de DAG (quando a análise N usa resultados de várias análises anteriores)
+- Vinculação de rastreabilidade específica da ferramenta (KnowledgeQuery → seu rastreamento GraphRAG)
+- Emissão de rastreabilidade em fluxo (emitir continuamente, não em lote no final)

docs/tech-specs/agent-explainability.ru.md

@@ -0,0 +1,272 @@
+# Объяснимость работы агента: Регистрация происхождения
+
+## Обзор
+
+Добавьте регистрацию происхождения в цикл работы агента React, чтобы сеансы работы агента можно было отслеживать и отлаживать с использованием той же инфраструктуры объяснимости, что и в GraphRAG.
+
+**Принятые решения:**
+Запись в `urn:graph:retrieval` (общий граф объяснимости)
+Линейная цепочка зависимостей на данный момент (анализ N → был получен из → анализ N-1)
+Инструменты являются непрозрачными "черными ящиками" (записывайте только входные и выходные данные)
+Поддержка DAG отложена до будущей итерации
+
+## Типы сущностей
+
+И GraphRAG, и Agent используют PROV-O в качестве базовой онтологии с подтипами, специфичными для TrustGraph:
+
+### Типы GraphRAG
+| Сущность | Тип PROV-O | Типы TG | Описание |
+|--------|-------------|----------|-------------|
+| Вопрос | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Запрос пользователя |
+| Исследование | `prov:Entity` | `tg:Exploration` | Ряды, извлеченные из графа знаний |
+| Фокус | `prov:Entity` | `tg:Focus` | Выбранные ряды с обоснованием |
+| Синтез | `prov:Entity` | `tg:Synthesis` | Окончательный ответ |
+
+### Типы Agent
+| Сущность | Тип PROV-O | Типы TG | Описание |
+|--------|-------------|----------|-------------|
+| Вопрос | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Запрос пользователя |
+| Анализ | `prov:Entity` | `tg:Analysis` | Каждый цикл "думай/действуй/наблюдай" |
+| Вывод | `prov:Entity` | `tg:Conclusion` | Окончательный ответ |
+
+### Типы Document RAG
+| Сущность | Тип PROV-O | Типы TG | Описание |
+|--------|-------------|----------|-------------|
+| Вопрос | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Запрос пользователя |
+| Исследование | `prov:Entity` | `tg:Exploration` | Части, извлеченные из хранилища документов |
+| Синтез | `prov:Entity` | `tg:Synthesis` | Окончательный ответ |
+
+**Примечание:** Document RAG использует подмножество типов GraphRAG (нет этапа "Фокус", поскольку нет этапа выбора/обоснования ребер).
+
+### Подтипы вопросов
+
+Все сущности "Вопрос" имеют `tg:Question` в качестве базового типа, но имеют определенный подтип для идентификации механизма извлечения:
+
+| Подтип | Шаблон URI | Механизм |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG на основе графа знаний |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG на основе документов/частей |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | Агент ReAct |
+
+Это позволяет запрашивать все вопросы через `tg:Question`, одновременно фильтруя по конкретному механизму с помощью подтипа.
+
+## Модель происхождения
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### Модель происхождения документов RAG
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## Необходимые изменения
+
+### 1. Изменения схемы
+
+**Файл:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+Добавить поля `session_id` и `collection` в `AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**Файл:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+Обновить переводчик для обработки `session_id` и `collection` как в `to_pulsar()`, так и в `from_pulsar()`.
+
+### 2. Добавить компонент "Explainability Producer" в сервис Agent
+
+**Файл:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+Зарегистрировать компонент "explainability" (в соответствии с тем же шаблоном, что и GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. Генерация триплетов происхождения
+
+**Файл:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+Создайте вспомогательные функции (подобные `question_triples`, `exploration_triples` и т.д. в GraphRAG):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. Определения типов
+
+**Файл:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+Добавить типы сущностей, обеспечивающих объяснимость, и предикаты агентов:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## Измененные файлы
+
+| Файл | Изменение |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | Добавлены session_id и collection в AgentRequest |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Обновлен переводчик для новых полей |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | Добавлены типы сущностей, предикаты агента и предикаты Document RAG |
+| `trustgraph-base/trustgraph/provenance/triples.py` | Добавлены типы TG для конструкторов троек GraphRAG, добавлены конструкторы троек Document RAG |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Добавлены генераторы URI для Document RAG |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | Экспортированы новые типы, предикаты и функции Document RAG |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Добавлены explain_id и explain_graph в DocumentRagResponse |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Обновлен DocumentRagResponseTranslator для полей, связанных с объяснением |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | Добавлена логика создания и записи информации о объяснении |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Добавлен колбэк для информации о объяснении и выводятся тройки, содержащие информацию о происхождении |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Добавлен генератор информации о объяснении и подключен колбэк |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Обработка типов трассировки агента |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Отображение сессий агента вместе с GraphRAG |
+
+## Созданные файлы
+
+| Файл | Назначение |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Генераторы троек, специфичные для агента |
+
+## Обновления CLI
+
+**Обнаружение:** И GraphRAG, и вопросы агента имеют тип `tg:Question`. Отличаются следующим:
+1. Шаблон URI: `urn:trustgraph:agent:` против `urn:trustgraph:question:`
+2. Выводимые сущности: `tg:Analysis` (агент) против `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+Отображает столбец "Тип" (Агент против GraphRAG)
+
+**`show_explain_trace.py`:**
+Автоматически определяет тип трассировки
+Отображение информации об агенте: Вопрос → Шаги анализа → Вывод
+
+## Обратная совместимость
+
+`session_id` по умолчанию равно `""` - старые запросы работают, но не будут содержать информацию о происхождении
+`collection` по умолчанию равно `"default"` - разумная альтернатива
+CLI корректно обрабатывает оба типа трассировки
+
+## Проверка
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## Будущие задачи (не входят в этот PR)
+
+Зависимости DAG (когда анализ N использует результаты нескольких предыдущих анализов)
+Связь с конкретными инструментами (KnowledgeQuery → его трассировка GraphRAG)
+Потоковая передача метаданных (отправлять по мере выполнения, а не пакетами в конце)

docs/tech-specs/agent-explainability.sw.md

@@ -0,0 +1,272 @@
+# Ufafanuzi wa Mwakala: Urekodaji wa Asili
+
+## Muhtasari
+
+Ongeza urekodaji wa asili kwenye mzunguko wa wakala wa React ili vipindi vya wakala viweze kufuatiliwa na kurekebishwa kwa kutumia miundomino sawa ya ufafanuzi kama GraphRAG.
+
+**Maamuzi ya Ubunifu:**
+- Andika kwenye `urn:graph:retrieval` (picha ya ufafanuzi ya jumla)
+- Mnyororo wa utegemezi wa mstari kwa sasa (uchambuzi N → ilitokana na → uchambuzi N-1)
+- Zana ni masanduku meusi (rekodi tu ingizo/patto)
+- Usaidizi wa DAG umeahirishwa hadi toleo la baadaye
+
+## Aina za Vitambulisho
+
+GraphRAG na Agent hutumia PROV-O kama ontolojia ya msingi na aina za ziada maalum za TrustGraph:
+
+### Aina za GraphRAG
+| Vitambulisho | Aina ya PROV-O | Aina za TG | Maelezo |
+|--------|-------------|----------|-------------|
+| Swali | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Uliza wa mtumiaji |
+| Uchunguzi | `prov:Entity` | `tg:Exploration` | Edges iliyopatikana kutoka kwenye grafu ya maarifa |
+| Lengo | `prov:Entity` | `tg:Focus` | Edges iliyochaguliwa na hoja |
+| Muunganisho | `prov:Entity` | `tg:Synthesis` | Jibu la mwisho |
+
+### Aina za Wakala
+| Vitambulisho | Aina ya PROV-O | Aina za TG | Maelezo |
+|--------|-------------|----------|-------------|
+| Swali | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Uliza wa mtumiaji |
+| Uchambuzi | `prov:Entity` | `tg:Analysis` | Kila mzunguko wa kufikiria/kutenda/kuona |
+| Hitimisho | `prov:Entity` | `tg:Conclusion` | Jibu la mwisho |
+
+### Aina za RAG za Hati
+| Vitambulisho | Aina ya PROV-O | Aina za TG | Maelezo |
+|--------|-------------|----------|-------------|
+| Swali | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Uliza wa mtumiaji |
+| Uchunguzi | `prov:Entity` | `tg:Exploration` | Sehemu zilizopatikana kutoka kwenye duka la hati |
+| Muunganisho | `prov:Entity` | `tg:Synthesis` | Jibu la mwisho |
+
+**Kumbuka:** RAG ya Hati hutumia sehemu ya aina za GraphRAG (hakuna hatua ya Lengo kwa sababu hakuna awamu ya uteuzi/hoja ya edge).
+
+### Aina za Ndogo za Swali
+
+Aina zote za Swali hushiriki `tg:Question` kama aina ya msingi lakini zina aina maalum ili kutambua utaratibu wa urejesho:
+
+| Aina | Mfumo wa URI | Utaratibu |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG ya grafu ya maarifa |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG ya hati/sehemu |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | Wakala wa ReAct |
+
+Hii inaruhusu kuuliza maswali yote kupitia `tg:Question` huku ikiwezesha kuchujwa kwa utaratibu maalum kupitia aina.
+
+## Mfumo wa Asili
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### Mfumo wa Asili ya Hati ya RAG
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## Mabadiliko Yanayohitajika
+
+### 1. Mabadiliko ya Muundo
+
+**Faili:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+Ongeza sehemu za `session_id` na `collection` kwenye `AgentRequest`:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**Faidio:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+Sasisha mtafsiri ili kushughulikia `session_id` na `collection` katika `to_pulsar()` na `from_pulsar()`.
+
+### 2. Ongeza Mzalishaji wa Ufafanuzi kwa Huduma ya Wakala
+
+**Faidio:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+Sajili "mzalishaji wa ufafanuzi" (mfumo sawa na GraphRAG):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. Uzalishaji wa Mfumo wa Asili
+
+**Faili:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+Unda kazi za msaada (kama zile za GraphRAG, kama `question_triples`, `exploration_triples`, n.k.):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. Ufafanuzi wa Aina
+
+**Faili:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+Ongeza aina za vitu vya uelewaji na sentensi za wakala:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## Faili Yaliyobadilishwa
+
+| Faili | Mabadiliko |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | Ongeza `session_id` na `collection` kwenye `AgentRequest` |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Sasisha `translator` kwa ajili ya sehemu mpya |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | Ongeza aina za `entity`, `agent predicates`, na `Document RAG predicates` |
+| `trustgraph-base/trustgraph/provenance/triples.py` | Ongeza aina za `TG` kwenye `GraphRAG triple builders`, ongeza `Document RAG triple builders` |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Ongeza `Document RAG URI generators` |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | Export aina mpya, `predicates`, na `Document RAG functions` |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Ongeza `explain_id` na `explain_graph` kwenye `DocumentRagResponse` |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Sasisha `DocumentRagResponseTranslator` kwa ajili ya sehemu za `explainability` |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | Ongeza mzalishaji wa `explainability` + mantiki ya kurekodi |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Ongeza `explainability callback` na toa `provenance triples` |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Ongeza mzalishaji wa `explainability` na uunganishe `callback` |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Shirikisha aina za `agent trace` |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Orodha `agent sessions` pamoja na `GraphRAG` |
+
+## Faili Zilizoundwa
+
+| Faili | Madhumuni |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Wazalishaji wa `triple` maalum kwa `agent` |
+
+## Mabadiliko ya CLI
+
+**Kugundua:** Maswali ya `GraphRAG` na `Agent` yana aina ya `tg:Question`. Hutofautishwa na:
+1. Mfumo wa `URI`: `urn:trustgraph:agent:` dhidi ya `urn:trustgraph:question:`
+2. Vipengele vilivyotokana: `tg:Analysis` (`agent`) dhidi ya `tg:Exploration` (`GraphRAG`)
+
+**`list_explain_traces.py`:**
+- Inaonyesha safu ya Aina (Agent vs GraphRAG)
+
+**`show_explain_trace.py`:**
+- Hugundua kiotomatiki aina ya `trace`
+- Uonyesho wa `agent` unaonyesha: Swali → Hatua za uchambuzi → Hitimisho
+
+## Utangamano na Mifumo ya Zamani
+
+- `session_id` huenda kwa `""` - maombi ya zamani hufanya kazi, lakini hayata na `provenance`
+- `collection` huenda kwa `"default"` - `fallback` inayofaa
+- CLI hushughulikia aina zote za `trace` kwa utulivu
+
+## Uthibitisho
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## Kazi Zinazotarajiwa (Sio Katika Mradi Huyu)
+
+- Utendakazi wa utegemezi wa DAG (wakati uchambuzi N hutumia matokeo kutoka kwa uchambuzi kadhaa uliopita)
+- Uunganisho wa utambulisho wa zana maalum (KnowledgeQuery → faili yake ya GraphRAG)
+- Utumaji wa utambulisho wa mtiririko (tumia kwa wakati, sio kwa wingi mwisho)

docs/tech-specs/agent-explainability.tr.md

@@ -0,0 +1,272 @@
+# Ajan Açıklanabilirliği: Kaynak Kaydı
+
+## Genel Bakış
+
+Ajan oturumlarının izlenebilmesi ve GraphRAG ile aynı açıklanabilirlik altyapısı kullanılarak hata ayıklanabilmesi için, React ajan döngüsüne kaynak kaydı ekleyin.
+
+**Tasarım Kararları:**
+- `urn:graph:retrieval`'a yazın (genel açıklanabilirlik grafiği)
+- Şu anda doğrusal bağımlılık zinciri (analiz N → wasDerivedFrom → analiz N-1)
+- Araçlar, kayıt alınmayan, opak kara kutulardır (sadece girdi/çıktı kaydedilir)
+- DAG desteği, gelecekteki bir yinelemeye ertelenmiştir
+
+## Varlık Türleri
+
+Hem GraphRAG hem de Agent, TrustGraph'e özgü alt türlere sahip olan PROV-O'yu temel ontoloji olarak kullanır:
+
+### GraphRAG Türleri
+| Varlık | PROV-O Türü | TG Türleri | Açıklama |
+|--------|-------------|----------|-------------|
+| Soru | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Kullanıcının sorgusu |
+| Keşif | `prov:Entity` | `tg:Exploration` | Bilgi grafiğinden alınan kenarlar |
+| Odak | `prov:Entity` | `tg:Focus` | Akıl yürütmeyle seçilen kenarlar |
+| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
+
+### Ajan Türleri
+| Varlık | PROV-O Türü | TG Türleri | Açıklama |
+|--------|-------------|----------|-------------|
+| Soru | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Kullanıcının sorgusu |
+| Analiz | `prov:Entity` | `tg:Analysis` | Her düşünme/eylem/gözlem döngüsü |
+| Sonuç | `prov:Entity` | `tg:Conclusion` | Sonuç |
+
+### Belge RAG Türleri
+| Varlık | PROV-O Türü | TG Türleri | Açıklama |
+|--------|-------------|----------|-------------|
+| Soru | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Kullanıcının sorgusu |
+| Keşif | `prov:Entity` | `tg:Exploration` | Belge deposundan alınan parçalar |
+| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
+
+**Not:** Belge RAG, GraphRAG'ın türlerinin bir alt kümesini kullanır (kenar seçimi/akıl yürütme aşaması olmadığından Odak adımı yoktur).
+
+### Soru Alt Türleri
+
+Tüm Soru varlıkları `tg:Question`'ı temel tür olarak paylaşır, ancak geri alma mekanizmasını tanımlamak için özel bir alt türe sahiptir:
+
+| Alt Tür | URI Kalıbı | Mekanizma |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | Bilgi grafiği RAG |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | Belge/parça RAG |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | ReAct ajanı |
+
+Bu, tüm soruların `tg:Question` aracılığıyla sorgulanabilmesini sağlarken, alt tür aracılığıyla belirli bir mekanizma ile filtrelenmesini sağlar.
+
+## Kaynak Modeli
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### Belge RAG (Retrieval-Augmented Generation) Kaynak Modeli
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## Gerekli Değişiklikler
+
+### 1. Şema Değişiklikleri
+
+**Dosya:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+`AgentRequest`'ye `session_id` ve `collection` alanlarını ekleyin:
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**Dosya:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+Çeviriciyi, `session_id` ve `collection`'i hem `to_pulsar()` hem de `from_pulsar()` içinde işleyebilecek şekilde güncelleyin.
+
+### 2. Ajan Hizmetine Açıklanabilirlik Üreticisini Ekle
+
+**Dosya:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+Bir "açıklanabilirlik" üreticisi kaydedin (GraphRAG ile aynı yapı):
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. Kaynak Üçlü Oluşturma
+
+**Dosya:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+Yardımcı fonksiyonlar oluşturun (GraphRAG'in `question_triples`, `exploration_triples`, vb. gibi):
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. Tür Tanımları
+
+**Dosya:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+Açıklanabilirlik varlık türlerini ve ajan özniteliklerini ekleyin:
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## Değiştirilen Dosyalar
+
+| Dosya | Değişiklik |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | AgentRequest'e session_id ve collection eklendi |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Yeni alanlar için çevirici güncellendi |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | Varlık türleri, ajan önişlemleri ve Document RAG önişlemleri eklendi |
+| `trustgraph-base/trustgraph/provenance/triples.py` | GraphRAG üçlü oluşturucularına TG türleri eklendi, Document RAG üçlü oluşturucuları eklendi |
+| `trustgraph-base/trustgraph/provenance/uris.py` | Document RAG URI oluşturucuları eklendi |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | Yeni türler, önişlemler ve Document RAG fonksiyonları dışa aktarıldı |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | DocumentRagResponse'a explain_id ve explain_graph eklendi |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Açıklanabilirlik alanları için DocumentRagResponseTranslator güncellendi |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | Açıklanabilirlik üretici + kayıt mantığı eklendi |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Açıklanabilirlik geri çağırması eklendi ve kaynak üçlüleri yayıldı |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Açıklanabilirlik üretici eklendi ve geri çağırma ile bağlandı |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Ajan izleme türleri işlendi |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Ajan oturumları, GraphRAG ile birlikte listelendi |
+
+## Oluşturulan Dosyalar
+
+| Dosya | Amaç |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Ajan özel üçlü oluşturucuları |
+
+## CLI Güncellemeleri
+
+**Algılama:** Hem GraphRAG hem de Ajan Soruları `tg:Question` türündedir. Aşağıdakilerle ayırt edilir:
+1. URI kalıbı: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
+2. Türetilen varlıklar: `tg:Analysis` (ajan) vs `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+- Tür sütununu (Ajan vs GraphRAG) gösterir
+
+**`show_explain_trace.py`:**
+- İzleme türünü otomatik olarak algılar
+- Ajan işleme, şu öğeleri gösterir: Soru → Analiz adımı(ları) → Sonuç
+
+## Geriye Dönük Uyumluluk
+
+- `session_id` varsayılan olarak `""`'dir - eski istekler çalışır, ancak kaynak bilgisi olmayacaktır
+- `collection` varsayılan olarak `"default"`'dir - makul bir yedekleme
+- CLI, her iki izleme türünü de sorunsuz bir şekilde işler
+
+## Doğrulama
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## Gelecek Çalışmalar (Bu PR'de Değil)
+
+- DAG bağımlılıkları (analiz N, birden fazla önceki analizden sonuçları kullandığında)
+- Araçlara özel köken bağlantısı (KnowledgeQuery → GraphRAG izi)
+- Akışlı köken yayını (sonunda toplu olarak değil, işlem sırasında yayınla)

docs/tech-specs/agent-explainability.zh-cn.md

@@ -0,0 +1,272 @@
+# Agent Explainability: Provenance Recording
+
+## 概述
+
+为使代理会话可追溯和可调试，并将代理循环中的溯源记录添加到 React 代理中，从而使用与 GraphRAG 相同的可解释性基础设施。
+
+**设计决策：**
+写入 `urn:graph:retrieval` (通用可解释性图)
+目前采用线性依赖链 (分析 N → wasDerivedFrom → 分析 N-1)
+工具是不可见的黑盒 (仅记录输入/输出)
+DAG 支持计划在未来迭代中实现
+
+## 实体类型
+
+GraphRAG 和 Agent 都使用 PROV-O 作为基础本体，并具有 TrustGraph 特定的子类型：
+
+### GraphRAG 类型
+| 实体 | PROV-O 类型 | TG 类型 | 描述 |
+|--------|-------------|----------|-------------|
+| 问题 | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | 用户的查询 |
+| 探索 | `prov:Entity` | `tg:Exploration` | 从知识图谱检索的边 |
+| 重点 | `prov:Entity` | `tg:Focus` | 带有推理的选定边 |
+| 合成 | `prov:Entity` | `tg:Synthesis` | 最终答案 |
+
+### Agent 类型
+| 实体 | PROV-O 类型 | TG 类型 | 描述 |
+|--------|-------------|----------|-------------|
+| 问题 | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | 用户的查询 |
+| 分析 | `prov:Entity` | `tg:Analysis` | 每个思考/行动/观察周期 |
+| 结论 | `prov:Entity` | `tg:Conclusion` | 最终答案 |
+
+### Document RAG 类型
+| 实体 | PROV-O 类型 | TG 类型 | 描述 |
+|--------|-------------|----------|-------------|
+| 问题 | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | 用户的查询 |
+| 探索 | `prov:Entity` | `tg:Exploration` | 从文档存储中检索的块 |
+| 合成 | `prov:Entity` | `tg:Synthesis` | 最终答案 |
+
+**注意：** Document RAG 使用 GraphRAG 类型的子集 (没有“重点”步骤，因为没有边选择/推理阶段)。
+
+### 问题子类型
+
+所有“问题”实体都共享 `tg:Question` 作为基本类型，但具有特定的子类型以标识检索机制：
+
+| 子类型 | URI 模式 | 机制 |
+|---------|-------------|-----------|
+| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | 知识图谱 RAG |
+| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | 文档/块 RAG |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | ReAct 代理 |
+
+这允许通过 `tg:Question` 查询所有问题，同时通过子类型过滤特定机制。
+
+## 溯源模型
+
+```
+Question (urn:trustgraph:agent:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis1 (urn:trustgraph:agent:{uuid}/i1)
+    │
+    │  tg:thought = "I need to query the knowledge base..."
+    │  tg:action = "knowledge-query"
+    │  tg:arguments = {"question": "..."}
+    │  tg:observation = "Result from tool..."
+    │  rdf:type = prov:Entity, tg:Analysis
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Analysis2 (urn:trustgraph:agent:{uuid}/i2)
+    │  ...
+    ↓ prov:wasDerivedFrom
+    │
+Conclusion (urn:trustgraph:agent:{uuid}/final)
+    │
+    │  tg:answer = "The final response..."
+    │  rdf:type = prov:Entity, tg:Conclusion
+```
+
+### 文档检索增强生成（RAG）溯源模型
+
+```
+Question (urn:trustgraph:docrag:{uuid})
+    │
+    │  tg:query = "User's question"
+    │  prov:startedAtTime = timestamp
+    │  rdf:type = prov:Activity, tg:Question
+    │
+    ↓ prov:wasGeneratedBy
+    │
+Exploration (urn:trustgraph:docrag:{uuid}/exploration)
+    │
+    │  tg:chunkCount = 5
+    │  tg:selectedChunk = "chunk-id-1"
+    │  tg:selectedChunk = "chunk-id-2"
+    │  ...
+    │  rdf:type = prov:Entity, tg:Exploration
+    │
+    ↓ prov:wasDerivedFrom
+    │
+Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
+    │
+    │  tg:content = "The synthesized answer..."
+    │  rdf:type = prov:Entity, tg:Synthesis
+```
+
+## 需要修改的内容
+
+### 1. 模式更改
+
+**文件:** `trustgraph-base/trustgraph/schema/services/agent.py`
+
+向 `AgentRequest` 添加 `session_id` 和 `collection` 字段：
+```python
+@dataclass
+class AgentRequest:
+    question: str = ""
+    state: str = ""
+    group: list[str] | None = None
+    history: list[AgentStep] = field(default_factory=list)
+    user: str = ""
+    collection: str = "default"  # NEW: Collection for provenance traces
+    streaming: bool = False
+    session_id: str = ""         # NEW: For provenance tracking across iterations
+```
+
+**文件:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+
+更新翻译器，使其能够处理 `session_id` 和 `collection`，并在 `to_pulsar()` 和 `from_pulsar()` 中均能正确处理。
+
+### 2. 向 Agent Service 添加可解释性生产者
+
+**文件:** `trustgraph-flow/trustgraph/agent/react/service.py`
+
+注册一个“可解释性”生产者（与 GraphRAG 相同模式）：
+```python
+from ... base import ProducerSpec
+from ... schema import Triples
+
+# In __init__:
+self.register_specification(
+    ProducerSpec(
+        name = "explainability",
+        schema = Triples,
+    )
+)
+```
+
+### 3. 溯源三元组生成
+
+**文件:** `trustgraph-base/trustgraph/provenance/agent.py`
+
+创建辅助函数（类似于 GraphRAG 的 `question_triples`、`exploration_triples` 等）：
+```python
+def agent_session_triples(session_uri, query, timestamp):
+    """Generate triples for agent Question."""
+    return [
+        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
+        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
+        Triple(s=session_uri, p=TG_QUERY, o=query),
+        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
+    ]
+
+def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
+    """Generate triples for one Analysis step."""
+    return [
+        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
+        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
+        Triple(s=iteration_uri, p=TG_ACTION, o=action),
+        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
+        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
+        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+
+def agent_final_triples(final_uri, parent_uri, answer):
+    """Generate triples for Conclusion."""
+    return [
+        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
+        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
+        Triple(s=final_uri, p=TG_ANSWER, o=answer),
+        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
+    ]
+```
+
+### 4. 类型定义
+
+**文件:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+
+添加可解释性实体类型和代理谓词：
+```python
+# Explainability entity types (used by both GraphRAG and Agent)
+TG_QUESTION = TG + "Question"
+TG_EXPLORATION = TG + "Exploration"
+TG_FOCUS = TG + "Focus"
+TG_SYNTHESIS = TG + "Synthesis"
+TG_ANALYSIS = TG + "Analysis"
+TG_CONCLUSION = TG + "Conclusion"
+
+# Agent predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+```
+
+## 文件修改
+
+| 文件 | 更改 |
+|------|--------|
+| `trustgraph-base/trustgraph/schema/services/agent.py` | 向 AgentRequest 添加 session_id 和 collection |
+| `trustgraph-base/trustgraph/messaging/translators/agent.py` | 更新翻译器以适应新字段 |
+| `trustgraph-base/trustgraph/provenance/namespaces.py` | 添加实体类型、agent谓词和 Document RAG 谓词 |
+| `trustgraph-base/trustgraph/provenance/triples.py` | 向 GraphRAG 三元组构建器添加 TG 类型，添加 Document RAG 三元组构建器 |
+| `trustgraph-base/trustgraph/provenance/uris.py` | 添加 Document RAG URI 生成器 |
+| `trustgraph-base/trustgraph/provenance/__init__.py` | 导出新类型、谓词和 Document RAG 函数 |
+| `trustgraph-base/trustgraph/schema/services/retrieval.py` | 向 DocumentRagResponse 添加 explain_id 和 explain_graph |
+| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | 更新 DocumentRagResponseTranslator 以适应可解释性字段 |
+| `trustgraph-flow/trustgraph/agent/react/service.py` | 添加可解释性生产者 + 记录逻辑 |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | 添加可解释性回调并发出溯源三元组 |
+| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | 添加可解释性生产者并连接回调 |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | 处理 agent 跟踪类型 |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | 在 GraphRAG 旁边列出 agent 会话 |
+
+## 创建的文件
+
+| 文件 | 目的 |
+|------|---------|
+| `trustgraph-base/trustgraph/provenance/agent.py` | Agent 相关的三元组生成器 |
+
+## CLI 更新
+
+**检测：** 无论是 GraphRAG 还是 Agent 问题，都具有 `tg:Question` 类型。通过以下方式区分：
+1. URI 模式：`urn:trustgraph:agent:` vs `urn:trustgraph:question:`
+2. 派生实体：`tg:Analysis` (agent) vs `tg:Exploration` (GraphRAG)
+
+**`list_explain_traces.py`:**
+显示类型列（Agent vs GraphRAG）
+
+**`show_explain_trace.py`:**
+自动检测跟踪类型
+Agent 渲染显示：问题 → 分析步骤(s) → 结论
+
+## 向后兼容性
+
+`session_id` 默认为 `""` - 旧请求有效，但将不具有溯源信息
+`collection` 默认为 `"default"` - 合理的备选方案
+CLI 能够优雅地处理两种跟踪类型
+
+## 验证
+
+```bash
+# Run an agent query
+tg-invoke-agent -q "What is the capital of France?"
+
+# List traces (should show agent sessions with Type column)
+tg-list-explain-traces -U trustgraph -C default
+
+# Show agent trace
+tg-show-explain-trace "urn:trustgraph:agent:xxx"
+```
+
+## 未来工作（不在本次 PR 中）
+
+DAG 依赖关系（当分析 N 使用来自多个先前分析的结果时）
+特定于工具的溯源链接（KnowledgeQuery → 它的 GraphRAG 跟踪）
+流式溯源输出（在过程中输出，而不是在最后批量输出）

docs/tech-specs/architecture-principles.ar.md

@@ -0,0 +1,106 @@
+# أسس هيكل الرسم البياني للمعرفة
+
+## الأساس الأول: نموذج الرسم البياني للعلاقة بين الموضوع والمسند والموضوع (SPO)
+**القرار**: اعتماد نموذج SPO/RDF كنموذج تمثيل المعرفة الأساسي
+
+**السبب**:
+يوفر أقصى قدر من المرونة وقابلية التشغيل البيني مع تقنيات الرسم البياني الحالية
+يمكّن الترجمة السلسة إلى لغات استعلام عن الرسم البياني الأخرى (مثل SPO → Cypher، ولكن ليس العكس)
+يخلق أساسًا "يفتح الكثير" من القدرات اللاحقة
+يدعم كل من علاقات العقدة إلى العقدة (SPO) وعلاقات العقدة إلى القيمة الحرفية (RDF)
+
+**التنفيذ**:
+الهيكل الأساسي للبيانات: `node → edge → {node | literal}`
+الحفاظ على التوافق مع معايير RDF مع دعم عمليات SPO الموسعة
+
+## الأساس الثاني: تكامل الرسم البياني الأصلي لنماذج اللغة الكبيرة (LLM)
+**القرار**: تحسين هيكل وعمليات الرسم البياني للتفاعل مع نماذج اللغة الكبيرة
+
+**السبب**:
+الحالة الرئيسية هي تفاعل نماذج اللغة الكبيرة مع الرسوم البيانية للمعرفة
+يجب أن تعطي خيارات تقنية الرسم البياني الأولوية لتوافق نماذج اللغة الكبيرة على اعتبارات أخرى
+يمكّن سير عمل معالجة اللغة الطبيعية التي تستفيد من المعرفة المنظمة
+
+**التنفيذ**:
+تصميم مخططات الرسم البياني التي يمكن لنماذج اللغة الكبيرة الاستدلال عليها بشكل فعال
+التحسين لأنماط التفاعل الشائعة لنماذج اللغة الكبيرة
+
+## الأساس الثالث: التنقل في الرسم البياني القائم على التضمين
+**القرار**: تنفيذ تعيين مباشر من استعلامات اللغة الطبيعية إلى عقد الرسم البياني عبر التضمينات
+
+**السبب**:
+يمكّن المسار الأبسط من استعلام معالجة اللغة الطبيعية إلى التنقل في الرسم البياني
+يتجنب خطوات توليد استعلام وسيطة معقدة
+يوفر قدرات بحث دلالي فعالة داخل هيكل الرسم البياني
+
+**التنفيذ**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+الحفاظ على تمثيلات التضمين لجميع كيانات الرسم البياني
+دعم مطابقة تشابه دلالي مباشر لحل الاستعلامات
+
+## الأساس الرابع: حل الكيانات الموزع مع المعرفات الحتمية
+**القرار**: دعم استخراج المعرفة المتوازي مع تحديد الكيانات الحتمي (قاعدة 80٪)
+
+**السبب**:
+**مثالي**: يتيح استخراج العملية الفردية مع رؤية حالة كاملة حل الكيانات المثالي
+**الواقع**: تتطلب متطلبات قابلية التوسع قدرات معالجة متوازية
+**حل وسط**: التصميم من أجل تحديد الكيانات الحتمي عبر العمليات الموزعة
+
+**التنفيذ**:
+تطوير آليات لتوليد معرفات متسقة وفريدة عبر أدوات استخراج المعرفة المختلفة
+يجب أن يتم حل نفس الكيان المذكور في عمليات مختلفة إلى نفس المعرف
+الاعتراف بأنه قد تتطلب ~20٪ من الحالات الخاصة نماذج معالجة بديلة
+تصميم آليات احتياطية لسيناريوهات حل الكيانات المعقدة
+
+## الأساس الخامس: بنية قائمة على الأحداث مع النشر والاشتراك
+**القرار**: تنفيذ نظام رسائل النشر والاشتراك لتنسيق النظام
+
+**السبب**:
+يمكّن الفصل بين مكونات استخراج وتخزين واستعلام المعرفة
+يدعم التحديثات والإشعارات في الوقت الفعلي عبر النظام
+يسهل سير عمل معالجة موزعة وقابلة للتطوير
+
+**التنفيذ**:
+تنسيق مدفوع بالرسائل بين مكونات النظام
+تدفقات الأحداث لتحديثات المعرفة وإكمال الاستخراج ونتائج الاستعلام
+
+## الأساس السادس: تواصل الوكيل القابل لإعادة الدخول
+**القرار**: دعم عمليات النشر والاشتراك القابلة لإعادة الدخول لمعالجة قائمة على الوكلاء
+
+**السبب**:
+يمكّن سير عمل الوكيل المعقد حيث يمكن للوكلاء تشغيل والرد على بعضهم البعض
+يدعم خطوط أنابيب معالجة المعرفة المعقدة والمتعددة الخطوات
+يسمح بأنماط المعالجة التكرارية والتكرارية
+
+**التنفيذ**:
+يجب أن يتعامل نظام النشر والاشتراك مع المكالمات القابلة لإعادة الدخول بأمان
+آليات تنسيق الوكيل التي تمنع الحلقات اللانهائية
+دعم تنسيق سير عمل الوكيل
+
+## الأساس السابع: تكامل متجر البيانات العمودي
+**القرار**: ضمان توافق الاستعلام مع أنظمة التخزين العمودية
+
+**السبب**:
+يمكّن الاستعلامات التحليلية الفعالة على مجموعات بيانات المعرفة الكبيرة
+يدعم حالات استخدام ذكاء الأعمال وإعداد التقارير
+يربط بين تمثيل المعرفة القائم على الرسم البياني وسير العمل التحليلي التقليدي
+
+**التنفيذ**:
+طبقة ترجمة الاستعلام: استعلامات الرسم البياني → استعلامات عمودية
+استراتيجية تخزين هجينة تدعم عمليات الرسم البياني وأحمال العمل التحليلية
+الحفاظ على أداء الاستعلام عبر كلا النماذجين
+
+--
+
+## ملخص مبادئ البنية
+
+1. **المرونة أولاً**: يوفر نموذج SPO أقصى قدر من القدرة على التكيف
+2. **التحسين لنماذج اللغة الكبيرة**: تأخذ جميع القرارات التصميمية في الاعتبار متطلبات تفاعل نماذج اللغة الكبيرة
+3. **الكفاءة الدلالية**: تعيين مباشر من التضمين إلى العقدة لأداء استعلام أمثل
+4. **قابلية التوسع العملية**: الموازنة بين الدقة المثالية والمعالجة الموزعة العملية
+5. **التنسيق القائم على الأحداث**: يمكّن النشر والاشتراك من الفصل وقابلية التوسع
+6. **صديقة للوكيل**: دعم سير عمل معالجة متعددة الوكلاء
+7. **التوافق التحليلي**: ربط بين نماذج الرسم البياني والأعمدة للاستعلامات الشاملة
+
+تحدد هذه الأسس بنية رسم بياني للمعرفة تحقق التوازن بين الدقة النظرية ومتطلبات قابلية التوسع العملية، ومحسنة للتكامل مع نماذج اللغة الكبيرة والمعالجة الموزعة.
+

docs/tech-specs/architecture-principles.es.md

@@ -0,0 +1,106 @@
+# Fundamentos de la Arquitectura del Gráfico de Conocimiento
+
+## Fundamento 1: Modelo de Gráfico Sujeto-Predicado-Objeto (SPO)
+**Decisión**: Adoptar SPO/RDF como el modelo de representación de conocimiento central.
+
+**Justificación**:
+Proporciona la máxima flexibilidad e interoperabilidad con las tecnologías de gráficos existentes.
+Permite la traducción fluida a otros lenguajes de consulta de gráficos (por ejemplo, SPO → Cypher, pero no al revés).
+Crea una base que "desbloquea muchas" capacidades posteriores.
+Admite tanto relaciones de nodo a nodo (SPO) como relaciones de nodo a literal (RDF).
+
+**Implementación**:
+Estructura de datos central: `node → edge → {node | literal}`
+Mantener la compatibilidad con los estándares RDF al tiempo que se admiten operaciones SPO extendidas.
+
+## Fundamento 2: Integración Nativa del Gráfico de Conocimiento con LLM
+**Decisión**: Optimizar la estructura y las operaciones del gráfico de conocimiento para la interacción con LLM.
+
+**Justificación**:
+El caso de uso principal implica que los LLM interactúen con los gráficos de conocimiento.
+Las opciones de tecnología de gráficos deben priorizar la compatibilidad con LLM por encima de otras consideraciones.
+Permite flujos de trabajo de procesamiento del lenguaje natural que aprovechan el conocimiento estructurado.
+
+**Implementación**:
+Diseñar esquemas de gráficos que los LLM puedan comprender y razonar eficazmente.
+Optimizar para patrones de interacción comunes con LLM.
+
+## Fundamento 3: Navegación del Gráfico Basada en Incrustaciones
+**Decisión**: Implementar un mapeo directo de las consultas de lenguaje natural a los nodos del gráfico a través de incrustaciones.
+
+**Justificación**:
+Permite la ruta más sencilla posible desde la consulta de PNL hasta la navegación del gráfico.
+Evita pasos complejos de generación de consultas intermedias.
+Proporciona capacidades de búsqueda semántica eficientes dentro de la estructura del gráfico.
+
+**Implementación**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+Mantener representaciones de incrustación para todas las entidades del gráfico.
+Admitir la coincidencia de similitud semántica directa para la resolución de consultas.
+
+## Fundamento 4: Resolución de Entidades Distribuidas con Identificadores Deterministas
+**Decisión**: Admitir la extracción de conocimiento en paralelo con la identificación determinista de entidades (regla del 80%).
+
+**Justificación**:
+**Ideal**: La extracción en un solo proceso con visibilidad completa del estado permite una resolución de entidades perfecta.
+**Realidad**: Los requisitos de escalabilidad exigen capacidades de procesamiento en paralelo.
+**Compromiso**: Diseñar para la identificación determinista de entidades en procesos distribuidos.
+
+**Implementación**:
+Desarrollar mecanismos para generar identificadores consistentes y únicos en diferentes extractores de conocimiento.
+La misma entidad mencionada en diferentes procesos debe resolverse en el mismo identificador.
+Reconocer que aproximadamente el 20% de los casos extremos pueden requerir modelos de procesamiento alternativos.
+Diseñar mecanismos de respaldo para escenarios complejos de resolución de entidades.
+
+## Fundamento 5: Arquitectura Orientada a Eventos con Publicación-Suscripción
+**Decisión**: Implementar un sistema de mensajería de publicación-suscripción para la coordinación del sistema.
+
+**Justificación**:
+Permite un acoplamiento débil entre los componentes de extracción, almacenamiento y consulta de conocimiento.
+Admite actualizaciones y notificaciones en tiempo real en todo el sistema.
+Facilita flujos de trabajo de procesamiento distribuidos y escalables.
+
+**Implementación**:
+Coordinación basada en mensajes entre los componentes del sistema.
+Flujos de eventos para actualizaciones de conocimiento, finalización de la extracción y resultados de consultas.
+
+## Fundamento 6: Comunicación de Agentes Reentrantes
+**Decisión**: Admitir operaciones de publicación-suscripción reentrantes para el procesamiento basado en agentes.
+
+**Justificación**:
+Permite flujos de trabajo sofisticados de agentes donde los agentes pueden activar y responder entre sí.
+Admite canalizaciones complejas de procesamiento de conocimiento con varios pasos.
+Permite patrones de procesamiento recursivos e iterativos.
+
+**Implementación**:
+El sistema de publicación-suscripción debe manejar las llamadas reentrantes de forma segura.
+Mecanismos de coordinación de agentes que previenen bucles infinitos.
+Soporte para la orquestación de flujos de trabajo de agentes.
+
+## Fundamento 7: Integración con Almacenes de Datos Columnares
+**Decisión**: Asegurar la compatibilidad de las consultas con los sistemas de almacenamiento columnar.
+
+**Justificación**:
+Permite consultas analíticas eficientes sobre grandes conjuntos de datos de conocimiento.
+Admite casos de uso de inteligencia empresarial e informes.
+Une la representación de conocimiento basada en gráficos con los flujos de trabajo analíticos tradicionales.
+
+**Implementación**:
+Capa de traducción de consultas: Consultas de gráfico → Consultas de columna.
+Estrategia de almacenamiento híbrida que admite tanto operaciones de gráfico como cargas de trabajo analíticas.
+Mantener el rendimiento de las consultas en ambos paradigmas.
+
+--
+
+## Resumen de los Principios de la Arquitectura
+
+1. **Flexibilidad Primero**: El modelo SPO/RDF proporciona la máxima adaptabilidad.
+2. **Optimización para LLM**: Todas las decisiones de diseño consideran los requisitos de interacción con LLM.
+3. **Eficiencia Semántica**: Mapeo directo de incrustaciones a nodos para un rendimiento de consulta óptimo.
+4. **Escalabilidad Pragmática**: Equilibrar la precisión perfecta con el procesamiento distribuido práctico.
+5. **Coordinación Orientada a Eventos**: La publicación-suscripción permite un acoplamiento débil y la escalabilidad.
+6. **Amigable para Agentes**: Admite flujos de trabajo complejos de procesamiento basados en agentes.
+7. **Compatibilidad Analítica**: Une los paradigmas de gráficos y columnas para consultas integrales.
+
+Estos fundamentos establecen una arquitectura de gráfico de conocimiento que equilibra la rigurosidad teórica con los requisitos prácticos de escalabilidad, optimizada para la integración con LLM y el procesamiento distribuido.
+

docs/tech-specs/architecture-principles.he.md

@@ -0,0 +1,106 @@
+# יסודות ארכיטקטורת גרף ידע
+
+## יסוד 1: מודל גרף נושא-תכונה-אובייקט (SPO)
+**החלטה**: לאמץ את מודל SPO/RDF כמודל הייצוג הבסיסי של ידע.
+
+**הצדקה**:
+מספק גמישות מרבית ותאימות עם טכנולוגיות גרף קיימות.
+מאפשר המרה חלקה לשפות שאילתות גרף אחרות (לדוגמה, SPO → Cypher, אך לא להיפך).
+יוצר בסיס ש"פותח הרבה" יכולות נלוות.
+תומך הן בקשרים בין צמתים (SPO) והן בקשרים בין צמתים לערכים (RDF).
+
+**יישום**:
+מבנה נתונים מרכזי: `node → edge → {node | literal}`
+שמירה על תאימות לתקני RDF תוך תמיכה בפעולות SPO מורחבות.
+
+## יסוד 2: שילוב גרף ידע מותאם למודלי שפה גדולים (LLM)
+**החלטה**: אופטימיזציה של מבנה ותפעול גרף ידע לאינטראקציה עם LLM.
+
+**הצדקה**:
+מקרה שימוש עיקרי כולל LLM באינטראקציה עם גרפי ידע.
+בחירות טכנולוגיות גרף חייבות לתעדף תאימות ל-LLM על פני שיקולים אחרים.
+מאפשר זרימות עבודה של עיבוד שפה טבעית המנצלות ידע מובנה.
+
+**יישום**:
+תכנון סכימות גרף ש-LLM יכולים להסיק מהן בצורה יעילה.
+אופטימיזציה לדפוסי אינטראקציה נפוצים של LLM.
+
+## יסוד 3: ניווט גרף מבוסס הטבעות (Embeddings)
+**החלטה**: יישום מיפוי ישיר משאילתות בשפה טבעית לצמתים בגרף באמצעות הטבעות.
+
+**הצדקה**:
+מאפשר את הנתיב הפשוט ביותר משאילת NLP לניווט בגרף.
+נמנע משלבי יצירת שאילתות ביניים מורכבים.
+מספק יכולות חיפוש סמנטיות יעילות בתוך מבנה הגרף.
+
+**יישום**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+שמירה על ייצוגי הטבעות עבור כל ישויות הגרף.
+תמיכה בהתאמת דמיון סמנטי ישירה לפתרון שאילתות.
+
+## יסוד 4: פתרון ישויות מבוזר עם מזהים דטרמיניסטיים
+**החלטה**: תמיכה בחילוץ ידע מקבילי עם זיהוי ישויות דטרמיניסטי (כלל 80%).
+
+**הצדקה**:
+**אידיאלי**: חילוץ בתהליך יחיד עם נראות של מצב מלא מאפשר פתרון ישויות מושלם.
+**מציאות**: דרישות סקיילביליות מחייבות יכולות עיבוד מקבילי.
+**פשרה**: תכנון לזיהוי ישויות דטרמיניסטי בכל תהליכים מבוזרים.
+
+**יישום**:
+פיתוח מנגנונים ליצירת מזהים עקביים וייחודיים בכל חולצי הידע.
+אותה ישות המוזכרת בתהליכים שונים חייבת להתפרש לאותו מזהה.
+יש להכיר בכך ש~20% מהמקרים המיוחדים עשויים לדרוש מודלי עיבוד חלופיים.
+תכנון מנגנוני ברירת מחדל עבור תרחישי פתרון ישויות מורכבים.
+
+## יסוד 5: ארכיטקטורה מונעת אירועים עם פרסום-מנוי
+**החלטה**: יישום מערכת הודעות מבוססת פרסום-מנוי לתיאום מערכות.
+
+**הצדקה**:
+מאפשר צימוד רופף בין רכיבי חילוץ, אחסון ושאילתות ידע.
+תומך בעדכונים והתראות בזמן אמת ברחבי המערכת.
+מקל על זרימות עבודה מבוזרות וניתנות להרחבה.
+
+**יישום**:
+תיאום מונחה הודעות בין רכיבי מערכת.
+זרמי אירועים לעדכוני ידע, השלמת חילוץ ושליחת תוצאות שאילתות.
+
+## יסוד 6: תקשורת סוכנים חוזרת
+**החלטה**: תמיכה בפעולות פרסום-מנוי חוזרות לעיבוד מבוסס סוכנים.
+
+**הצדקה**:
+מאפשר זרימות עבודה מורכבות של סוכנים שבהם סוכנים יכולים להפעיל ולהגיב זה לזה.
+תומך בצינורות עיבוד ידע מורכבים, רב-שלביים.
+מאפשר דפוסי עיבוד רקורסיביים ואיטרטיביים.
+
+**יישום**:
+מערכת הפרסום-מנוי חייבת לטפל בשיחות חוזרות בצורה בטוחה.
+מנגנוני תיאום סוכנים שמונעים לולאות אינסופיות.
+תמיכה בתיאום זרימות עבודה של סוכנים.
+
+## יסוד 7: שילוב עם חנות נתונים טבלאית
+**החלטה**: הבטחת תאימות שאילתות למערכות אחסון טבלאיות.
+
+**הצדקה**:
+מאפשר שאילתות אנליטיות יעילות על פני מערכי ידע גדולים.
+תומך במקרי שימוש של מודיעין עסקי ודיווח.
+גשר בין ייצוג ידע מבוסס גרף לבין זרימות עבודה אנליטיות מסורתיות.
+
+**יישום**:
+שכבת תרגום שאילתות: שאילתות גרף → שאילתות טבלאיות.
+אסטרטגיית אחסון היברידית התומכת הן בפעולות גרף והן בעומסי עבודה אנליטיים.
+שמירה על ביצועי שאילתות בשני הפרדיגמות.
+
+--
+
+## סיכום עקרונות ארכיטקטורה
+
+1. **גמישות ראשית**: מודל SPO/RDF מספק יכולת הסתגלות מרבית.
+2. **אופטימיזציה ל-LLM**: כל החלטות התכנון מתייחסות לאינטראקציה עם LLM.
+3. **ניווט יעיל**: שימוש בטבעות (Embeddings) לניווט יעיל בגרף.
+4. **פתרון ישויות מבוזר**: תמיכה בחילוץ ידע מקבילי עם מזהים דטרמיניסטיים.
+5. **תיאום מערכות**: שימוש במערכת הודעות מבוססת פרסום-מנוי.
+6. **עיבוד סוכנים חוזר**: תמיכה בפעולות פרסום-מנוי חוזרות לעיבוד מבוסס סוכנים.
+7. **תאימות שאילתות**: הבטחת תאימות שאילתות למערכות אחסון טבלאיות.
+
+יסודות אלה מציבים ארכיטקטורת גרף ידע המאזנת בין דיוק תיאורטי לדרישות מדרגיות מעשיות, ומותאמת לאינטגרציה עם מודלי שפה גדולים (LLM) ולעיבוד מבוזר.
+

docs/tech-specs/architecture-principles.hi.md

@@ -0,0 +1,106 @@
+# नॉलेज ग्राफ आर्किटेक्चर फाउंडेशन
+
+## फाउंडेशन 1: सब्जेक्ट-प्रेडिकेट-ऑब्जेक्ट (एसपीओ) ग्राफ मॉडल
+**निर्णय**: एस.पी.ओ./आर.डी.एफ. को मुख्य नॉलेज रिप्रेजेंटेशन मॉडल के रूप में अपनाएं
+
+**तर्क**:
+यह अधिकतम लचीलापन और मौजूदा ग्राफ तकनीकों के साथ इंटरऑपरेबिलिटी प्रदान करता है।
+यह अन्य ग्राफ क्वेरी भाषाओं (जैसे, एस.पी.ओ. → साइफर, लेकिन इसके विपरीत नहीं) में सहज अनुवाद को सक्षम बनाता है।
+यह एक ऐसा आधार बनाता है जो "बहुत सारी" डाउनस्ट्रीम क्षमताओं को "अनलॉक" करता है।
+यह नोड-टू-नोड संबंधों (एस.पी.ओ.) और नोड-टू-लिटरल संबंधों (आर.डी.एफ.) दोनों का समर्थन करता है।
+
+**कार्यान्वयन**: 
+मुख्य डेटा संरचना: `node → edge → {node | literal}`
+विस्तारित एस.पी.ओ. ऑपरेशनों का समर्थन करते हुए आर.डी.एफ. मानकों के साथ अनुकूलता बनाए रखें।
+
+## फाउंडेशन 2: एलएलएम-नेटिव नॉलेज ग्राफ इंटीग्रेशन
+**निर्णय**: एलएलएम इंटरैक्शन के लिए नॉलेज ग्राफ संरचना और ऑपरेशनों को अनुकूलित करें
+
+**तर्क**:
+प्राथमिक उपयोग मामला एलएलएम का नॉलेज ग्राफ के साथ इंटरफेस करना है।
+ग्राफ तकनीक विकल्पों को अन्य विचारों की तुलना में एलएलएम अनुकूलता को प्राथमिकता देनी चाहिए।
+यह प्राकृतिक भाषा प्रसंस्करण वर्कफ़्लो को संरचित ज्ञान का लाभ उठाने में सक्षम बनाता है।
+
+**कार्यान्वयन**:
+ऐसे ग्राफ स्कीमा डिज़ाइन करें जिन्हें एलएलएम प्रभावी ढंग से तर्क दे सकें।
+सामान्य एलएलएम इंटरैक्शन पैटर्न के लिए अनुकूलित करें।
+
+## फाउंडेशन 3: एम्बेडिंग-आधारित ग्राफ नेविगेशन
+**निर्णय**: प्राकृतिक भाषा प्रश्नों को एम्बेडिंग के माध्यम से ग्राफ नोड्स पर सीधे मैप करें
+
+**तर्क**:
+यह एनएलपी क्वेरी से ग्राफ नेविगेशन के लिए सबसे सरल पथ को सक्षम करता है।
+जटिल मध्यवर्ती क्वेरी पीढ़ी चरणों से बचें।
+ग्राफ संरचना के भीतर कुशल सिमेंटिक खोज क्षमताओं को प्रदान करता है।
+
+**कार्यान्वयन**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+सभी ग्राफ एंटिटीज के लिए एम्बेडिंग रिप्रेजेंटेशन बनाए रखें।
+क्वेरी रिज़ॉल्यूशन के लिए प्रत्यक्ष सिमेंटिक समानता मिलान का समर्थन करें।
+
+## फाउंडेशन 4: डिस्ट्रीब्यूटेड एंटिटी रिज़ॉल्यूशन विद डिटर्मिनिस्टिक आइडेंटिफायर्स
+**निर्णय**: डिस्ट्रीब्यूटेड एंटिटी आइडेंटिफिकेशन (80% नियम) के साथ समानांतर नॉलेज एक्सट्रैक्शन का समर्थन करें
+
+**तर्क**:
+**आदर्श**: पूर्ण राज्य दृश्यता के साथ सिंगल-प्रोसेस एक्सट्रैक्शन सही एंटिटी रिज़ॉल्यूशन को सक्षम करता है।
+**वास्तविकता**: स्केलेबिलिटी आवश्यकताओं के लिए समानांतर प्रसंस्करण क्षमताओं की आवश्यकता होती है।
+**समझौता**: वितरित प्रक्रियाओं में नियतात्मक एंटिटी पहचान के लिए डिज़ाइन करें।
+
+**कार्यान्वयन**:
+ऐसे तंत्र विकसित करें जो विभिन्न नॉलेज एक्सट्रैक्टर्स में सुसंगत, अद्वितीय पहचानकर्ता उत्पन्न करते हैं।
+विभिन्न प्रक्रियाओं में उल्लिखित एक ही एंटिटी को समान पहचानकर्ता पर हल किया जाना चाहिए।
+इस बात को स्वीकार करें कि ~20% एज केस के लिए वैकल्पिक प्रसंस्करण मॉडल की आवश्यकता हो सकती है।
+जटिल एंटिटी रिज़ॉल्यूशन परिदृश्यों के लिए फॉलबैक तंत्र डिज़ाइन करें।
+
+## फाउंडेशन 5: इवेंट-ड्रिवन आर्किटेक्चर विद पब्लिश-सब्सक्राइब
+**निर्णय**: सिस्टम समन्वय के लिए एक पब-सब मैसेजिंग सिस्टम लागू करें
+
+**तर्क**:
+यह नॉलेज एक्सट्रैक्शन, स्टोरेज और क्वेरी घटकों के बीच ढीला युग्मन को सक्षम करता है।
+यह पूरे सिस्टम में रीयल-टाइम अपडेट और नोटिफिकेशन का समर्थन करता है।
+यह स्केलेबल, वितरित प्रसंस्करण वर्कफ़्लो को सुविधाजनक बनाता है।
+
+**कार्यान्वयन**:
+सिस्टम घटकों के बीच मैसेज-ड्रिवन समन्वय।
+नॉलेज अपडेट, एक्सट्रैक्शन पूरा होने और क्वेरी परिणामों के लिए इवेंट स्ट्रीम।
+
+## फाउंडेशन 6: रीएंट्रेंट एजेंट कम्युनिकेशन
+**निर्णय**: एजेंट-आधारित प्रसंस्करण के लिए रीएंट्रेंट पब-सब ऑपरेशंस का समर्थन करें
+
+**तर्क**:
+यह परिष्कृत एजेंट वर्कफ़्लो को सक्षम करता है जहां एजेंट एक-दूसरे को ट्रिगर और प्रतिक्रिया कर सकते हैं।
+यह जटिल, बहु-चरणीय नॉलेज प्रोसेसिंग पाइपलाइनों का समर्थन करता है।
+यह पुनरावर्ती और पुनरावृत्त प्रसंस्करण पैटर्न की अनुमति देता है।
+
+**कार्यान्वयन**:
+पब-सब सिस्टम को सुरक्षित रूप से रीएंट्रेंट कॉल को संभालना चाहिए।
+एजेंट समन्वय तंत्र जो अनंत लूप को रोकते हैं।
+एजेंट वर्कफ़्लो ऑर्केस्ट्रेशन के लिए समर्थन।
+
+## फाउंडेशन 7: कॉलम डेटा स्टोर इंटीग्रेशन
+**निर्णय**: कॉलम स्टोरेज सिस्टम के साथ क्वेरी अनुकूलता सुनिश्चित करें
+
+**तर्क**:
+यह बड़े नॉलेज डेटासेट पर कुशल विश्लेषणात्मक प्रश्नों को सक्षम करता है।
+यह बिजनेस इंटेलिजेंस और रिपोर्टिंग उपयोग मामलों का समर्थन करता है।
+यह ग्राफ-आधारित नॉलेज रिप्रेजेंटेशन को पारंपरिक विश्लेषणात्मक वर्कफ़्लो के साथ जोड़ता है।
+
+**कार्यान्वयन**:
+क्वेरी ट्रांसलेशन लेयर: ग्राफ क्वेरी → कॉलम क्वेरी
+एक हाइब्रिड स्टोरेज रणनीति जो ग्राफ ऑपरेशंस और विश्लेषणात्मक वर्कलोड दोनों का समर्थन करती है।
+दोनों प्रतिमानों में क्वेरी प्रदर्शन बनाए रखें।
+
+--
+
+## आर्किटेक्चर प्रिंसिपल्स समरी
+
+1. **लचीलापन पहले**: एस.पी.ओ./आर.डी.एफ. मॉडल अधिकतम अनुकूलन क्षमता प्रदान करता है।
+2. **एलएलएम अनुकूलन**: सभी डिज़ाइन निर्णयों पर एलएलएम इंटरैक्शन आवश्यकताओं पर विचार किया जाता है।
+3. **सिमेंटिक दक्षता**: इष्टतम क्वेरी प्रदर्शन के लिए प्रत्यक्ष एम्बेडिंग-टू-नोड मैपिंग।
+4. **व्यावहारिक स्केलेबिलिटी**: सही सटीकता को व्यावहारिक वितरित प्रसंस्करण के साथ संतुलित करें।
+5. **इवेंट-ड्रिवन समन्वय**: पब-सब ढीला युग्मन और स्केलेबिलिटी को सक्षम करता है।
+6. **एजेंट-फ्रेंडली**: जटिल, बहु-एजेंट प्रसंस्करण वर्कफ़्लो का समर्थन करें।
+7. **विश्लेषणात्मक अनुकूलता**: व्यापक क्वेरी के लिए ग्राफ और कॉलम प्रतिमानों को जोड़ें।
+
+ये फाउंडेशन एक नॉलेज ग्राफ आर्किटेक्चर स्थापित करते हैं जो सैद्धांतिक कठोरता को व्यावहारिक स्केलेबिलिटी आवश्यकताओं के साथ संतुलित करता है, जो एलएलएम एकीकरण और वितरित प्रसंस्करण के लिए अनुकूलित है।
+

docs/tech-specs/architecture-principles.pt.md

@@ -0,0 +1,106 @@
+# Arquitetura de Grafos de Conhecimento: Fundamentos
+
+## Fundamento 1: Modelo de Grafo Sujeito-Predicado-Objeto (SPO)
+**Decisão**: Adotar SPO/RDF como o modelo central de representação de conhecimento
+
+**Justificativa**:
+- Fornece máxima flexibilidade e interoperabilidade com tecnologias de grafos existentes
+- Permite a tradução perfeita para outras linguagens de consulta de grafos (por exemplo, SPO → Cypher, mas não o contrário)
+- Cria uma base que "desbloqueia muitas" capacidades subsequentes
+- Suporta relacionamentos de nó para nó (SPO) e relacionamentos de nó para literal (RDF)
+
+**Implementação**:
+- Estrutura de dados principal: `node → edge → {node | literal}`
+- Manter a compatibilidade com os padrões RDF, ao mesmo tempo em que suporta operações SPO estendidas
+
+## Fundamento 2: Integração Nativa de Grafos de Conhecimento com LLMs
+**Decisão**: Otimizar a estrutura e as operações do grafo de conhecimento para a interação com LLMs
+
+**Justificativa**:
+- O caso de uso primário envolve LLMs interagindo com grafos de conhecimento
+- As escolhas da tecnologia de grafos devem priorizar a compatibilidade com LLMs em vez de outras considerações
+- Permite fluxos de trabalho de processamento de linguagem natural que aproveitam o conhecimento estruturado
+
+**Implementação**:
+- Projetar esquemas de grafo que os LLMs possam entender e usar efetivamente
+- Otimizar para padrões comuns de interação com LLMs
+
+## Fundamento 3: Navegação de Grafos Baseada em Incorporações
+**Decisão**: Implementar um mapeamento direto de consultas de linguagem natural para nós de grafos por meio de incorporações
+
+**Justificativa**:
+- Permite o caminho mais simples possível de uma consulta de PNL para a navegação no grafo
+- Evita etapas complexas de geração de consultas intermediárias
+- Fornece capacidades de pesquisa semântica eficientes dentro da estrutura do grafo
+
+**Implementação**:
+- `NLP Query → Graph Embeddings → Graph Nodes`
+- Manter representações de incorporação para todas as entidades do grafo
+- Suporte para correspondência de similaridade semântica direta para a resolução de consultas
+
+## Fundamento 4: Resolução Distribuída de Entidades com Identificadores Determinísticos
+**Decisão**: Suportar a extração de conhecimento paralela com identificação determinística de entidades (regra dos 80%)
+
+**Justificativa**:
+- **Ideal**: A extração em um único processo com visibilidade completa do estado permite a resolução perfeita de entidades
+- **Realidade**: Os requisitos de escalabilidade exigem capacidades de processamento paralelo
+- **Compromisso**: Projetar para identificação determinística de entidades em processos distribuídos
+
+**Implementação**:
+- Desenvolver mecanismos para gerar identificadores consistentes e exclusivos em diferentes extratores de conhecimento
+- A mesma entidade mencionada em processos diferentes deve resolver para o mesmo identificador
+- Reconhecer que ~20% dos casos extremos podem exigir modelos de processamento alternativos
+- Projetar mecanismos de fallback para cenários complexos de resolução de entidades
+
+## Fundamento 5: Arquitetura Orientada a Eventos com Publicação-Subscrição
+**Decisão**: Implementar um sistema de mensagens pub-sub para a coordenação do sistema
+
+**Justificativa**:
+- Permite o acoplamento frouxo entre os componentes de extração, armazenamento e consulta de conhecimento
+- Suporta atualizações e notificações em tempo real em todo o sistema
+- Facilita fluxos de trabalho de processamento distribuídos e escaláveis
+
+**Implementação**:
+- Coordenação orientada a mensagens entre os componentes do sistema
+- Streams de eventos para atualizações de conhecimento, conclusão da extração e resultados de consultas
+
+## Fundamento 6: Comunicação de Agentes Reentrantes
+**Decisão**: Suportar operações pub-sub reentrantes para o processamento baseado em agentes
+
+**Justificativa**:
+- Permite fluxos de trabalho sofisticados de agentes, nos quais os agentes podem acionar e responder uns aos outros
+- Suporta pipelines complexos de processamento de conhecimento de várias etapas
+- Permite padrões de processamento recursivos e iterativos
+
+**Implementação**:
+- O sistema pub-sub deve lidar com chamadas reentrantes com segurança
+- Mecanismos de coordenação de agentes que evitam loops infinitos
+- Suporte para orquestração de fluxos de trabalho de agentes
+
+## Fundamento 7: Integração com Armazenamento de Dados Colunares
+**Decisão**: Garantir a compatibilidade das consultas com sistemas de armazenamento colunar.
+
+**Justificativa**:
+- Permite consultas analíticas eficientes em grandes conjuntos de dados de conhecimento.
+- Suporta casos de uso de inteligência de negócios e relatórios.
+- Integra a representação de conhecimento baseada em grafos com fluxos de trabalho analíticos tradicionais.
+
+**Implementação**:
+- Camada de tradução de consultas: Consultas de grafos → Consultas colunares.
+- Estratégia de armazenamento híbrida que suporta tanto operações de grafos quanto cargas de trabalho analíticas.
+- Manter o desempenho das consultas em ambos os paradigmas.
+
+---
+
+## Resumo dos Princípios da Arquitetura
+
+1. **Flexibilidade em Primeiro Lugar**: O modelo SPO/RDF fornece a máxima adaptabilidade.
+2. **Otimização para LLM**: Todas as decisões de design consideram os requisitos de interação com LLM.
+3. **Eficiência Semântica**: Mapeamento direto de embeddings para nós para desempenho ideal da consulta.
+4. **Escalabilidade Pragmática**: Equilibrar a precisão perfeita com o processamento distribuído prático.
+5. **Coordenação Orientada a Eventos**: Pub-sub permite o acoplamento fraco e a escalabilidade.
+6. **Compatível com Agentes**: Suporta fluxos de trabalho complexos de processamento multi-agentes.
+7. **Compatibilidade Analítica**: Integra os paradigmas de grafos e colunares para consultas abrangentes.
+
+Essas bases estabelecem uma arquitetura de grafo de conhecimento que equilibra a rigidez teórica com os requisitos práticos de escalabilidade, otimizada para a integração com LLM e o processamento distribuído.
+

docs/tech-specs/architecture-principles.ru.md

@@ -0,0 +1,106 @@
+# Основы архитектуры графа знаний
+
+## Основа 1: Модель графа "Субъект-Предикат-Объект" (SPO)
+**Решение**: Принять SPO/RDF в качестве основной модели представления знаний.
+
+**Обоснование**:
+Обеспечивает максимальную гибкость и совместимость с существующими технологиями графов.
+Позволяет беспрепятственно переводить в другие языки запросов к графам (например, SPO → Cypher, но не наоборот).
+Создает основу, которая "открывает множество" возможностей для дальнейшей разработки.
+Поддерживает как отношения между узлами (SPO), так и отношения между узлами и литералами (RDF).
+
+**Реализация**:
+Основная структура данных: `node → edge → {node | literal}`
+Поддерживать совместимость со стандартами RDF, одновременно поддерживая расширенные операции SPO.
+
+## Основа 2: Интеграция графа знаний, оптимизированная для LLM
+**Решение**: Оптимизировать структуру и операции графа знаний для взаимодействия с LLM.
+
+**Обоснование**:
+Основной сценарий использования включает взаимодействие LLM с графами знаний.
+Выбор технологий графов должен отдавать приоритет совместимости с LLM, а не другим соображениям.
+Обеспечивает потоки обработки естественного языка, использующие структурированные знания.
+
+**Реализация**:
+Разрабатывать схемы графов, которые LLM могут эффективно использовать для рассуждений.
+Оптимизировать для распространенных шаблонов взаимодействия LLM.
+
+## Основа 3: Навигация по графу на основе встраиваний
+**Решение**: Реализовать прямое сопоставление между запросами на естественном языке и узлами графа с помощью встраиваний.
+
+**Обоснование**:
+Обеспечивает самый простой путь от запроса на естественном языке к навигации по графу.
+Избегает сложных промежуточных этапов генерации запросов.
+Предоставляет возможности семантического поиска в структуре графа.
+
+**Реализация**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+Поддерживать представления встраиваний для всех сущностей графа.
+Поддерживать прямое семантическое сопоставление сходства для разрешения запросов.
+
+## Основа 4: Распределенное разрешение сущностей с детерминированными идентификаторами
+**Решение**: Поддерживать параллельное извлечение знаний с детерминированной идентификацией сущностей (правило 80%).
+
+**Обоснование**:
+**Идеально**: Извлечение в одном процессе с полной видимостью состояния обеспечивает идеальное разрешение сущностей.
+**Реальность**: Требования к масштабируемости требуют возможностей параллельной обработки.
+**Компромисс**: Разработать для детерминированной идентификации сущностей в распределенных процессах.
+
+**Реализация**:
+Разработать механизмы для генерации согласованных, уникальных идентификаторов в различных инструментах извлечения знаний.
+Одна и та же сущность, упомянутая в разных процессах, должна разрешаться в один и тот же идентификатор.
+Признать, что ~20% крайних случаев могут потребовать альтернативных моделей обработки.
+Разработать механизмы отката для сложных сценариев разрешения сущностей.
+
+## Основа 5: Архитектура, управляемая событиями, с публикацией и подпиской
+**Решение**: Реализовать систему обмена сообщениями pub-sub для координации системы.
+
+**Обоснование**:
+Обеспечивает слабую связанность между компонентами извлечения знаний, хранения и запросов.
+Поддерживает обновления в режиме реального времени и уведомления по всей системе.
+Облегчает масштабируемые, распределенные рабочие процессы.
+
+**Реализация**:
+Координация между компонентами системы с помощью управляемых сообщениями.
+Потоки событий для обновлений знаний, завершения извлечения и результатов запросов.
+
+## Основа 6: Взаимодействие агентов с возможностью повторного входа
+**Решение**: Поддерживать операции pub-sub с возможностью повторного входа для обработки на основе агентов.
+
+**Обоснование**:
+Позволяет создавать сложные рабочие процессы агентов, в которых агенты могут инициировать и реагировать друг на друга.
+Поддерживает сложные, многоступенчатые конвейеры обработки знаний.
+Позволяет использовать рекурсивные и итеративные шаблоны обработки.
+
+**Реализация**:
+Система pub-sub должна безопасно обрабатывать вызовы с повторным входом.
+Механизмы координации агентов, предотвращающие бесконечные циклы.
+Поддержка оркестровки рабочих процессов агентов.
+
+## Основа 7: Интеграция с хранилищем данных в столбцовом формате
+**Решение**: Обеспечить совместимость запросов с системами хранения данных в столбцовом формате.
+
+**Обоснование**:
+Обеспечивает эффективные аналитические запросы к большим наборам данных знаний.
+Поддерживает сценарии бизнес-аналитики и отчетности.
+Объединяет представление знаний на основе графов с традиционными аналитическими рабочими процессами.
+
+**Реализация**:
+Слой перевода запросов: Запросы графов → Запросы в столбцовом формате.
+Гибридная стратегия хранения, поддерживающая как операции графов, так и аналитические рабочие нагрузки.
+Поддерживать производительность запросов в обеих парадигмах.
+
+--
+
+## Краткое изложение принципов архитектуры
+
+1. **Гибкость прежде всего**: Модель SPO/RDF обеспечивает максимальную адаптируемость.
+2. **Оптимизация для LLM**: Все решения в области проектирования учитывают требования взаимодействия с LLM.
+3. **Семантическая эффективность**: Прямое сопоставление встраиваний с узлами для оптимальной производительности запросов.
+4. **Прагматическая масштабируемость**: Баланс между идеальной точностью и практическими возможностями распределенной обработки.
+5. **Координация, управляемая событиями**: Pub-sub обеспечивает слабую связанность и масштабируемость.
+6. **Поддержка агентов**: Поддержка сложных рабочих процессов, основанных на нескольких агентах.
+7. **Совместимость с аналитикой**: Объединение парадигм графов и столбцов для всестороннего запроса.
+
+Эта архитектура графа знаний сочетает теоретическую строгость с практическими требованиями масштабируемости, оптимизированная для интеграции с LLM и распределенной обработки.
+

docs/tech-specs/architecture-principles.sw.md

@@ -0,0 +1,106 @@
+# Msingi wa Usanifu wa Grafu ya Maarifa
+
+## Msingi wa 1: Mfumo wa Grafu wa Mada-Kitendawili-Jambo (SPO)
+**Uamuzi**: Kubali SPO/RDF kama mfumo mkuu wa uwakilishi wa maarifa
+
+**Sababu**:
+Hutoa uwezekano mwingi na utangamano na teknolojia za grafu zilizopo
+Inawezesha tafsiri rahisi kwa lugha zingine za kuuliza grafu (e.g., SPO → Cypher, lakini si kinyume chake)
+Huunda msingi ambao "unawezesha mengi" ya uwezo wa baadaye
+Inasaidia uhusiano wa kutoka-kwenye-node (SPO) na uhusiano wa kutoka-kwenye-jambo (RDF)
+
+**Utendaji**:
+Muundo mkuu wa data: `node → edge → {node | literal}`
+Endelea utangamano na viwango vya RDF huku ukiunga mkono operesheni zilizopanuliwa za SPO
+
+## Msingi wa 2: Uunganishaji wa Asili wa Grafu ya Maarifa na LLM
+**Uamuzi**: Boresha muundo na operesheni za grafu ya maarifa ili kuendana na mwingiliano wa LLM
+
+**Sababu**:
+Matumizi kuu yanahusisha LLM zinazofanya kazi na grafu za maarifa
+Chaguo za teknolojia za grafu lazima zipende utangamano wa LLM kuliko mambo mengine
+Inawezesha mchakato wa usindikaji wa lugha ya asili ambao hutumia maarifa yaliyopangwa
+
+**Utendaji**:
+Unda schema za grafu ambazo LLM zinaweza kuzielewa vizuri
+Boresha kwa mifumo ya kawaida ya mwingiliano wa LLM
+
+## Msingi wa 3: Uramaji wa Grafu kwa Kutumia Uingizwaji
+**Uamuzi**: Tengeneza uhusiano wa moja kwa moja kutoka maswali ya lugha ya asili hadi node za grafu kupitia uingizwaji
+
+**Sababu**:
+Inawezesha njia rahisi iwezekanavyo kutoka swali la NLP hadi uramaji wa grafu
+Inazuia hatua ngumu za kati za kuunda swali
+Hutoa uwezo wa utafutaji wa kiufundi ndani ya muundo wa grafu
+
+**Utendaji**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+Endelea uwakilishi wa uingizwaji kwa vyombo vyote vya grafu
+Unga mlingano wa moja kwa moja wa kiufundi kwa utatuzi wa swali
+
+## Msingi wa 4: Utatuzi Ulio Msingi wa Vitambulisho vya Ufafu na Ufumbuzi Ulio Msingi wa Vitambulisho
+**Uamuzi**: Unga uongezaji wa maarifa kwa usindikaji sambamba kwa kutumia utambulisho wa vitu vya ufafu (kanuni ya 80%)
+
+**Sababu**:
+**Lengo**: Uongezaji wa mchakato mmoja kwa hali kamili unawezesha utatuzi kamili wa vitu
+**Ukwereti**: Mahitaji ya uongezaji yanahitaji uwezo wa usindikaji sambamba
+**Suluhisho la Kompromi**: Unda kwa utambulisho wa vitu vya ufafu katika mchakato uliogawanyika
+
+**Utendaji**:
+Unda mitambo ya kuzalisha vitambulisho sawa na vya kipekee katika viboreshaji tofauti vya maarifa
+Kitu kimoja kinachotajwa katika mchakato tofauti lazima kiwe na kitambulisho kimoja
+Amini kwamba ~20% ya hali ngumu zinaweza kuhitaji modeli zingine za usindikaji
+Unda mitambo ya dharura kwa hali ngumu za utatuzi wa vitu
+
+## Msingi wa 5: Usanifu Ulioendeshwa na Tukio na Uchukuzi-Ulisikilizaji
+**Uamuzi**: Tengeneza mfumo wa ujumbe wa pub-sub kwa upangaji wa mfumo
+
+**Sababu**:
+Inawezesha kuunganishwa kwa huru kati ya uongezaji wa maarifa, uhifadhi, na vipengele vya kuuliza
+Inasaidia sasisho na arifa za wakati halisi katika mfumo
+Inawezesha mchakato wa usindikaji uliogawanyika na unaoweza kupanuka
+
+**Utendaji**:
+Uunganisho uliodumishwa na ujumbe kati ya vipengele vya mfumo
+Mito ya matukio kwa sasisho za maarifa, kukamilika kwa uongezaji, na matokeo ya kuuliza
+
+## Msingi wa 6: Mawasiliano ya Wakala wa Kurejea
+**Uamuzi**: Unga operesheni za pub-sub za kurejea kwa usindikaji wa wakala
+
+**Sababu**:
+Inawezesha mchakato wa wakala wa hali ya juu ambapo wakala wanaweza kuchochea na kujibu kila mmoja
+Inasaidia njia ngumu za usindikaji wa maarifa
+Inaruhusu mifumo ya usindikaji ya kurudia na ya mara kwa mara
+
+**Utendaji**:
+Mfumo wa pub-sub lazima uweze kushughulikia simu za kurejea kwa usalama
+Mitambo ya upangaji wa wakala ambayo inazuia mzunguko usio na mwisho
+Usaidizi wa upangaji wa mchakato wa wakala
+
+## Msingi wa 7: Uunganishaji wa Duka la Data ya Safu
+**Uamuzi**: Hakikisha utangamano wa kuuliza na mifumo ya uhifadhi wa safu
+
+**Sababu**:
+Inawezesha maswali ya uchambuzi ya ufanisi juu ya data kubwa ya maarifa
+Inasaidia matumizi ya biashara ya ujasusi na ripoti
+Huunganisha uwakilishi wa maarifa ya grafu na mchakato wa uchambuzi wa jadi
+
+**Utendaji**:
+Safu ya tafsiri ya kuuliza: Maswali ya grafu → Maswali ya safu
+Mkakati wa uhifadhi wa mchanganyiko unaounga mkono operesheni za grafu na mizigo ya uchambuzi
+Endelea utendaji wa kuuliza katika pande zote
+
+--
+
+## Muhtasari wa Kanuni za Usanifu
+
+1. **Uwezekano Kwanza**: Mfumo wa SPO hutoa uwezekano mwingi
+2. **Uongezaji wa LLM**: Maamuzi yote ya usanifu yanafikiria mahitaji ya mwingiliano wa LLM
+3. **Ufanisi wa Kiufundi**: Uramaji wa moja kwa moja wa uingizwaji hadi node kwa utendaji bora wa swali
+4. **Uongezaji wa Kimapokeo**: Panga usahihi kamili na uwezo wa usindikaji uliogawanyika
+5. **Usaidizi wa Vitambulisho**: Ufafu wa vitu na utatuzi wa vitu
+6. **Mawasiliano ya Wakala**: Usaidizi wa mchakato wa wakala
+7. **Uunganishaji wa Duka la Data**: Usaidizi wa maswali ya uchambuzi
+
+Misingi hizi huunda usanifu wa mfumo wa kujua ambao unachanganua umakini wa kinadharia na mahitaji ya utendakazi, ukiwa umeboreshwa kwa ajili ya ujumuishaji wa LLM na usindikaji ulioenelea.
+

docs/tech-specs/architecture-principles.tr.md

@@ -0,0 +1,106 @@
+# Bilgi Grafiği Mimarisi Temelleri
+
+## Temel 1: Özne-Yüklem-Nesne (ÖYY) Grafik Modeli
+**Karar**: Çekirdek bilgi gösterim modeli olarak SPO/RDF'yi benimse
+
+**Gerekçe**:
+- Mevcut grafik teknolojileriyle maksimum esneklik ve uyumluluk sağlar
+- Diğer grafik sorgu dillerine (örneğin, SPO → Cypher, ancak tersi değil) sorunsuz çeviri sağlar
+- "Birçok" sonraki yeteneği "açığa çıkaran" bir temel oluşturur
+- Hem düğüm-düğüm ilişkilerini (ÖYY) hem de düğüm-literal ilişkilerini (RDF) destekler
+
+**Uygulama**:
+- Temel veri yapısı: `node → edge → {node | literal}`
+- RDF standartlarıyla uyumluluğu korurken, gelişmiş SPO işlemlerini destekler
+
+## Temel 2: LLM-Yerel Bilgi Grafiği Entegrasyonu
+**Karar**: Bilgi grafiği yapısını ve işlemlerini LLM etkileşimi için optimize et
+
+**Gerekçe**:
+- Birincil kullanım durumu, LLM'lerin bilgi grafikleriyle etkileşimini içerir
+- Grafik teknolojisi seçimleri, diğer hususlara kıyasla LLM uyumluluğuna öncelik vermelidir
+- Yapılandırılmış bilgiyi kullanan doğal dil işleme iş akışlarını sağlar
+
+**Uygulama**:
+- LLM'lerin etkili bir şekilde akıl yürütebileceği grafik şemalarını tasarla
+- Yaygın LLM etkileşim kalıpları için optimize et
+
+## Temel 3: Gömme Tabanlı Grafik Navigasyonu
+**Karar**: Doğal dil sorgularını, gömmeler aracılığıyla doğrudan grafik düğümlerine eşleyin
+
+**Gerekçe**:
+- NLP sorgusundan grafik navigasyonuna en basit yolu sağlar
+- Karmaşık ara sorgu oluşturma adımlarından kaçının
+- Grafik yapısı içinde verimli semantik arama yetenekleri sağlar
+
+**Uygulama**:
+- `NLP Query → Graph Embeddings → Graph Nodes`
+- Tüm grafik varlıkları için gömme gösterimlerini koru
+- Sorgu çözümlemesi için doğrudan semantik benzerlik eşleştirmesini destekle
+
+## Temel 4: Dağıtılmış Varlık Çözümlemesi ve Belirleyici Tanımlayıcılar
+**Karar**: Paralel bilgi çıkarma işlemini, deterministik varlık tanımlamasıyla (80% kuralı) destekle
+
+**Gerekçe**:
+- **İdeal**: Tam durum görünürlüğü sağlayan tek işlem çıkarma, mükemmel varlık çözümlemesine olanak tanır
+- **Gerçeklik**: Ölçeklenebilirlik gereksinimleri, paralel işleme yetenekleri gerektirir
+- **Uzlaşma**: Dağıtılmış işlemler arasında deterministik varlık tanımlaması için tasarla
+
+**Uygulama**:
+- Farklı bilgi çıkarıcılar arasında tutarlı, benzersiz tanımlayıcılar oluşturmak için mekanizmalar geliştir
+- Farklı işlemlerde bahsedilen aynı varlık, aynı tanımlayıcıya çözümlenmelidir
+- Yaklaşık olarak %20'lik bir oranın, alternatif işleme modelleri gerektirebilecek uç durumlara karşılık geldiğinin farkında olun
+- Karmaşık varlık çözümleme senaryoları için yedek mekanizmalar tasarla
+
+## Temel 5: Yayın-Abonelik ile Olay Odaklı Mimari
+**Karar**: Sistem koordinasyonu için bir yayın-abone mesajlaşma sistemi uygula
+
+**Gerekçe**:
+- Bilgi çıkarma, depolama ve sorgu bileşenleri arasında gevşek bir bağlama olanak tanır
+- Sistem genelinde gerçek zamanlı güncellemeleri ve bildirimleri destekler
+- Ölçeklenebilir, dağıtılmış iş akışlarını kolaylaştırır
+
+**Uygulama**:
+- Sistem bileşenleri arasındaki mesaj odaklı koordinasyon
+- Bilgi güncellemeleri, çıkarma tamamlama ve sorgu sonuçları için olay akışları
+
+## Temel 6: Geri Çağrılabilir Ajan İletişimi
+**Karar**: Ajan tabanlı işleme için geri çağrılabilir yayın-abone işlemlerini destekle
+
+**Gerekçe**:
+- Ajanların birbirini tetikleyebildiği ve yanıtlayabildiği gelişmiş ajan iş akışlarına olanak tanır
+- Karmaşık, çok aşamalı bilgi işleme boru hatlarını destekler
+- Yinelemeli ve yinelemeli işleme kalıplarına izin verir
+
+**Uygulama**:
+- Yayın-abone sistemi, geri çağrılabilir çağrıları güvenli bir şekilde işlemelidir
+- Sonsuz döngüleri önleyen ajan koordinasyon mekanizmaları
+- Ajan iş akışı orkestrasyonu desteği
+
+## Temel 7: Sütun Veri Depolama Entegrasyonu
+**Karar**: Sorgu uyumluluğunun, sütunlu depolama sistemleriyle sağlanması.
+
+**Gerekçe**:
+- Büyük bilgi veri kümeleri üzerinde verimli analitik sorgulara olanak tanır.
+- İş zekası ve raporlama kullanım senaryolarını destekler.
+- Grafik tabanlı bilgi gösterimini geleneksel analitik iş akışlarıyla birleştirir.
+
+**Uygulama**:
+- Sorgu çevirme katmanı: Grafik sorguları → Sütunlu sorgular.
+- Hem grafik işlemlerini hem de analitik iş yüklerini destekleyen hibrit depolama stratejisi.
+- Her iki paradigma için de sorgu performansını koruyun.
+
+---
+
+## Mimari İlkeler Özeti
+
+1. **Öncelikli Olarak Esneklik**: SPO/RDF modeli, maksimum uyarlanabilirlik sağlar.
+2. **LLM Optimizasyonu**: Tüm tasarım kararları, LLM etkileşim gereksinimlerini dikkate alır.
+3. **Anlamsal Verimlilik**: Optimum sorgu performansı için doğrudan gömülü-düğüm eşlemesi.
+4. **Pratik Ölçeklenebilirlik**: Mükemmel doğruluğu, pratik dağıtılmış işleme ile dengeleyin.
+5. **Olay Odaklı Koordinasyon**: Yayın-abone, gevşek bağlama ve ölçeklenebilirliğe olanak tanır.
+6. **Ajan Dostu**: Karmaşık, çoklu ajan iş akışlarını destekler.
+7. **Analitik Uyumluluk**: Kapsamlı sorgulama için grafik ve sütunlu paradigmaları birleştirir.
+
+Bu temeller, teorik titizliği pratik ölçeklenebilirlik gereksinimleriyle dengeleyen, LLM entegrasyonu ve dağıtılmış işleme için optimize edilmiş bir bilgi grafiği mimarisi oluşturur.
+

docs/tech-specs/architecture-principles.zh-cn.md

@@ -0,0 +1,128 @@
+# 知识图谱架构基础
+
+## 基础 1：主谓宾 (SPO) 图模型
+**决策**: 采用 SPO/RDF 作为核心知识表示模型
+
+**理由**:
+提供最大的灵活性和与现有图技术的互操作性
+能够无缝转换为其他图查询语言 (例如，SPO → Cypher，反之则不行)
+奠定基础，"解锁"许多下游功能
+支持节点到节点的关系 (SPO) 和节点到字面值关系 (RDF)
+
+**实施**:
+核心数据结构: `node → edge → {node | literal}`
+在支持扩展的 SPO 操作的同时，保持与 RDF 标准的兼容性
+
+## 基础 2：原生于 LLM 的知识图谱集成
+**决策**: 优化知识图谱结构和操作，以实现与 LLM 的交互
+
+**理由**:
+主要用例涉及 LLM 与知识图谱的交互
+图技术选择必须优先考虑与 LLM 的兼容性，而不是其他考虑因素
+能够实现利用结构化知识的自然语言处理工作流程
+
+**实施**:
+设计 LLM 可以有效推理的图模式
+针对常见的 LLM 交互模式进行优化
+
+## 基础 3：基于嵌入的图导航
+**决策**: 通过嵌入将自然语言查询直接映射到图节点
+
+**理由**:
+实现从 NLP 查询到图导航的最简单路径
+避免复杂的中间查询生成步骤
+提供图结构内部高效的语义搜索功能
+
+**实施**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+维护所有图实体的嵌入表示
+支持用于查询解析的直接语义相似性匹配
+
+## 基础 4：分布式实体解析与确定性标识符
+**决策**: 支持并行知识提取，并使用确定性实体标识 (80% 规则)
+
+**理由**:
+**理想**: 单进程提取，具有完整的状态可见性，可以实现完美的实体解析
+<<<<<<< HEAD
+**现实**: 可扩展性要求需要并行处理能力
+=======
+**现实**: 扩展性要求需要并行处理能力
+>>>>>>> 82edf2d (New md files from RunPod)
+**折衷**: 设计用于在分布式进程中实现确定性实体标识
+
+**实施**:
+开发机制，以生成在不同知识提取器中保持一致且唯一的标识符
+在不同的进程中提到的相同实体必须解析为相同的标识符
+承认约 20% 的边缘情况可能需要替代处理模型
+设计用于处理复杂实体解析场景的后备机制
+
+## 基础 5：事件驱动架构与发布-订阅
+<<<<<<< HEAD
+**决策**: 实施 pub-sub 消息系统，用于系统协调
+=======
+**决策**: 实现发布-订阅消息系统，用于系统协调
+>>>>>>> 82edf2d (New md files from RunPod)
+
+**理由**:
+允许知识提取、存储和查询组件之间的松散耦合
+支持实时更新和跨系统的通知
+促进可扩展的分布式处理工作流程
+
+**实施**:
+使用消息驱动的系统组件协调
+用于知识更新、提取完成和查询结果的事件流
+
+## 基础 6：可重入代理通信
+**决策**: 支持用于基于代理的处理的可重入发布-订阅操作
+
+**理由**:
+允许代理触发和响应彼此，从而实现复杂的代理工作流程
+支持复杂的多步骤知识处理管道
+允许递归和迭代处理模式
+
+<<<<<<< HEAD
+**实施**:
+pub-sub 系统必须安全地处理可重入调用
+=======
+**实现**:
+发布-订阅系统必须安全地处理可重入调用
+>>>>>>> 82edf2d (New md files from RunPod)
+防止无限循环的代理协调机制
+支持代理工作流程编排
+
+## 基础 7：列式数据存储集成
+**决策**: 确保查询与列式存储系统兼容
+
+**理由**:
+能够对大型知识数据集执行高效的分析查询
+支持商业智能和报告用例
+桥接基于图的知识表示与传统的分析工作流程
+
+**实施**:
+查询转换层：图查询 → 列式查询
+<<<<<<< HEAD
+支持图操作和分析工作负载的混合存储策略
+=======
+混合存储策略，支持图操作和分析工作负载
+>>>>>>> 82edf2d (New md files from RunPod)
+在这两种范例中保持查询性能
+
+--
+
+## 架构原则摘要
+
+1. **灵活性至上**: SPO/RDF 模型提供最大的适应性
+2. **LLM 优化**: 所有设计决策都考虑 LLM 交互要求
+3. **语义效率**: 直接的嵌入到节点映射，以实现最佳的查询性能
+<<<<<<< HEAD
+4. **务实的扩展性**: 在完美准确性和实际的分布式处理之间取得平衡
+5. **事件驱动协调**: pub-sub 实现松散耦合和可扩展性
+=======
+4. **务实的扩展性**: 在完美的准确性与实际的分布式处理之间取得平衡
+5. **事件驱动协调**: 发布-订阅实现松散耦合和可扩展性
+>>>>>>> 82edf2d (New md files from RunPod)
+6. **代理友好**: 支持复杂的多代理处理工作流程
+7. **分析兼容性**: 桥接图和列式范例，以实现全面的查询
+
+这些基础构建了一个知识图谱架构，该架构在理论严谨性和实际可扩展性之间取得了平衡，并针对 LLM 集成和分布式处理进行了优化。
+

docs/tech-specs/cassandra-consolidation.ar.md

@@ -0,0 +1,331 @@
+# مواصفات فنية: توحيد إعدادات Cassandra
+
+**الحالة:** مسودة
+**المؤلف:** مساعد
+**التاريخ:** 2024-09-03
+
+## نظرة عامة
+
+تتناول هذه المواصفة عدم الاتساق في أسماء وأنماط إعدادات معلمات اتصال Cassandra عبر قاعدة بيانات TrustGraph. حاليًا، توجد مخططان مختلفان لتسمية المعلمات (`cassandra_*` مقابل `graph_*`)، مما يؤدي إلى الارتباك وتعقيد الصيانة.
+
+## بيان المشكلة
+
+تستخدم قاعدة البيانات حاليًا مجموعتين متميزتين من معلمات إعداد Cassandra:
+
+1. **وحدات المعرفة/التكوين/المكتبة** تستخدم:
+   `cassandra_host` (قائمة المضيفين)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **وحدات الرسم البياني/التخزين** تستخدم:
+   `graph_host` (مضيف واحد، يتم تحويله أحيانًا إلى قائمة)
+   `graph_username`
+   `graph_password`
+
+3. **عرض غير متسق عبر سطر الأوامر**:
+   بعض المعالجات (مثل `kg-store`) لا تعرض إعدادات Cassandra كمعلمات سطر أوامر
+   تعرض معالجات أخرى هذه الإعدادات بأسماء وتنسيقات مختلفة
+   لا يعكس نص المساعدة القيم الافتراضية لمتغيرات البيئة
+
+تتصل كلتا مجموعتي المعلمات بنفس مجموعة Cassandra ولكن باتفاقيات تسمية مختلفة، مما يسبب:
+ارتباك في التكوين للمستخدمين
+زيادة العبء على الصيانة
+توثيق غير متسق
+احتمال حدوث سوء تكوين
+عدم القدرة على تجاوز الإعدادات عبر سطر الأوامر في بعض المعالجات
+
+## الحل المقترح
+
+### 1. توحيد أسماء المعلمات
+
+ستستخدم جميع الوحدات أسماء معلمات متسقة `cassandra_*`:
+`cassandra_host` - قائمة المضيفين (مخزنة داخليًا كقائمة)
+`cassandra_username` - اسم المستخدم للمصادقة
+`cassandra_password` - كلمة المرور للمصادقة
+
+### 2. معلمات سطر الأوامر
+
+يجب على جميع المعالجات عرض إعدادات تكوين Cassandra عبر معلمات سطر الأوامر:
+`--cassandra-host` - قائمة مفصولة بفواصل من المضيفين
+`--cassandra-username` - اسم المستخدم للمصادقة
+`--cassandra-password` - كلمة المرور للمصادقة
+
+### 3. الاعتماد على متغيرات البيئة
+
+إذا لم يتم توفير معلمات سطر الأوامر بشكل صريح، فسيتحقق النظام من متغيرات البيئة:
+`CASSANDRA_HOST` - قائمة مفصولة بفواصل من المضيفين
+`CASSANDRA_USERNAME` - اسم المستخدم للمصادقة
+`CASSANDRA_PASSWORD` - كلمة المرور للمصادقة
+
+### 4. القيم الافتراضية
+
+إذا لم يتم تحديد أي من معلمات سطر الأوامر أو متغيرات البيئة:
+`cassandra_host` افتراضيًا إلى `["cassandra"]`
+`cassandra_username` افتراضيًا إلى `None` (بدون مصادقة)
+`cassandra_password` افتراضيًا إلى `None` (بدون مصادقة)
+
+### 5. متطلبات نص المساعدة
+
+يجب أن يعرض الإخراج `--help`:
+إظهار قيم متغيرات البيئة كقيم افتراضية عند تعيينها
+عدم عرض قيم كلمات المرور مطلقًا (إظهار `****` أو `<set>` بدلاً من ذلك)
+الإشارة بوضوح إلى ترتيب الحل في نص المساعدة
+
+مثال على إخراج المساعدة:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## تفاصيل التنفيذ
+
+### ترتيب حل المعلمات
+
+لكل معلمة في Cassandra، سيكون ترتيب الحل كما يلي:
+1. قيمة وسيط سطر الأوامر
+2. متغير البيئة (`CASSANDRA_*`)
+3. القيمة الافتراضية
+
+### معالجة معلمات المضيف
+
+المعلمة `cassandra_host`:
+يقبل سطر الأوامر سلسلة مفصولة بفواصل: `--cassandra-host "host1,host2,host3"`
+يقبل متغير البيئة سلسلة مفصولة بفواصل: `CASSANDRA_HOST="host1,host2,host3"`
+يتم تخزينها دائمًا داخليًا كقائمة: `["host1", "host2", "host3"]`
+مضيف واحد: `"localhost"` → يتم تحويله إلى `["localhost"]`
+إذا كانت بالفعل قائمة: `["host1", "host2"]` → يتم استخدامها كما هي
+
+### منطق المصادقة
+
+سيتم استخدام المصادقة عندما يتم توفير كل من `cassandra_username` و `cassandra_password`:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## الملفات المراد تعديلها
+
+### الوحدات التي تستخدم معلمات `graph_*` (يجب تغييرها):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### الوحدات التي تستخدم معلمات `cassandra_*` (يجب تحديثها مع استخدام الإعدادات الافتراضية للبيئة):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### ملفات الاختبار المراد تحديثها:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## استراتيجية التنفيذ
+
+### المرحلة الأولى: إنشاء أداة مساعدة للإعدادات المشتركة
+إنشاء دوال مساعدة لتوحيد إعدادات Cassandra عبر جميع المعالجات:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### المرحلة الثانية: تحديث الوحدات باستخدام معلمات `graph_*`
+1. تغيير أسماء المعلمات من `graph_*` إلى `cassandra_*`
+2. استبدال طرق `add_args()` المخصصة بطرق `add_cassandra_args()` القياسية
+3. استخدام الدوال المساعدة الشائعة للتكوين
+4. تحديث سلاسل التوثيق
+
+مثال على التحويل:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### المرحلة الثالثة: تحديث الوحدات باستخدام معلمات `cassandra_*`
+1. إضافة دعم للوسائط الخاصة بسطر الأوامر في الحالات التي تفتقر إليها (مثل: `kg-store`)
+2. استبدال تعريفات الوسائط الحالية بـ `add_cassandra_args()`
+3. استخدام `resolve_cassandra_config()` لتحقيق التوافق
+4. التأكد من معالجة متسقة لقائمة المضيفين
+
+### المرحلة الرابعة: تحديث الاختبارات والوثائق
+1. تحديث جميع ملفات الاختبار لاستخدام أسماء المعلمات الجديدة
+2. تحديث وثائق واجهة سطر الأوامر
+3. تحديث وثائق واجهة برمجة التطبيقات
+4. إضافة وثائق لمتغيرات البيئة
+
+## التوافق مع الإصدارات السابقة
+
+للحفاظ على التوافق مع الإصدارات السابقة أثناء الانتقال:
+
+1. **تحذيرات الإيقاف التدريجي** لمعلمات `graph_*`
+2. **تسمية بديلة للمعلمات** - قبول الأسماء القديمة والجديدة في البداية
+3. **نشر تدريجي** على مدار عدة إصدارات
+4. **تحديثات الوثائق** مع دليل الترحيل
+
+مثال على كود التوافق مع الإصدارات السابقة:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## استراتيجية الاختبار
+
+1. **اختبارات الوحدة** لمنطق حل التكوين.
+2. **اختبارات التكامل** مع مجموعات تكوين مختلفة.
+3. **اختبارات متغيرات البيئة**.
+4. **اختبارات التوافق مع الإصدارات السابقة** مع المعلمات التي تم إيقافها.
+5. **اختبارات Docker Compose** مع متغيرات البيئة.
+
+## تحديثات التوثيق
+
+1. تحديث جميع وثائق أوامر واجهة سطر الأوامر.
+2. تحديث وثائق واجهة برمجة التطبيقات.
+3. إنشاء دليل ترحيل.
+4. تحديث أمثلة Docker Compose.
+5. تحديث وثائق مرجع التكوين.
+
+## المخاطر والتخفيف
+
+| المخاطر | التأثير | التخفيف |
+|------|--------|------------|
+| تغييرات تؤثر على المستخدمين | مرتفع | تطبيق فترة التوافق مع الإصدارات السابقة. |
+| ارتباك في التكوين أثناء الانتقال | متوسط | توثيق واضح وتحذيرات إيقاف. |
+| فشل الاختبارات | متوسط | تحديثات شاملة للاختبارات. |
+| مشاكل في نشر Docker | مرتفع | تحديث جميع أمثلة Docker Compose. |
+
+## معايير النجاح
+
+[ ] تستخدم جميع الوحدات أسماء معلمات `cassandra_*` متسقة.
+[ ] تعرض جميع المعالجات إعدادات Cassandra عبر وسيطات سطر الأوامر.
+[ ] يعرض نص المساعدة الخاص بسطر الأوامر القيم الافتراضية لمتغيرات البيئة.
+[ ] لا يتم عرض قيم كلمات المرور في نص المساعدة.
+[ ] يعمل التراجع إلى متغيرات البيئة بشكل صحيح.
+[ ] يتم التعامل مع `cassandra_host` باستمرار كقائمة داخليًا.
+[ ] تم الحفاظ على التوافق مع الإصدارات السابقة لمدة إصدارين على الأقل.
+[ ] تجتاز جميع الاختبارات مع نظام التكوين الجديد.
+[ ] تم تحديث التوثيق بالكامل.
+[ ] تعمل أمثلة Docker Compose مع متغيرات البيئة.
+
+## الجدول الزمني
+
+**الأسبوع 1:** تنفيذ أداة مساعدة شائعة للتكوين وتحديث وحدات `graph_*`.
+**الأسبوع 2:** إضافة دعم لمتغيرات البيئة إلى وحدات `cassandra_*` الحالية.
+**الأسبوع 3:** تحديث الاختبارات والتوثيق.
+**الأسبوع 4:** اختبار التكامل وتصحيح الأخطاء.
+
+## اعتبارات مستقبلية
+
+ضع في اعتبارك توسيع هذا النمط ليشمل تكوينات قواعد بيانات أخرى (مثل Elasticsearch).
+تنفيذ التحقق من صحة التكوين ورسائل خطأ أفضل.
+إضافة دعم لتكوين تجميع الاتصالات لـ Cassandra.
+ضع في اعتبارك إضافة دعم لملفات التكوين (ملفات .env).

docs/tech-specs/cassandra-consolidation.es.md

@@ -0,0 +1,241 @@
+# Especificación Técnica: Consolidación de la Configuración de Cassandra
+
+**Estado:** Borrador
+**Autor:** Asistente
+**Fecha:** 2024-09-03
+
+## Visión General
+
+Esta especificación aborda los patrones de nombres y configuración inconsistentes para los parámetros de conexión de Cassandra en todo el código base de TrustGraph. Actualmente, existen dos esquemas de nombres de parámetros diferentes (`cassandra_*` frente a `graph_*`), lo que provoca confusión y complejidad en el mantenimiento.
+
+## Declaración del Problema
+
+El código base actualmente utiliza dos conjuntos distintos de parámetros de configuración de Cassandra:
+
+1. **Módulos de Conocimiento/Config/Biblioteca** utilizan:
+   - `cassandra_host` (lista de hosts)
+   - `cassandra_usuario`
+   - `cassandra_contraseña`
+
+2. **Módulos de Gráficos/Almacenamiento** utilizan:
+   - `graph_host` (único host, a veces convertido en lista)
+   - `graph_username`
+   - `graph_password`
+
+3. **Exposición inconsistente de la línea de comandos:**
+   - Algunos procesadores (p. ej., `kg-store`) no expone la configuración de Cassandra como argumentos de línea de comandos
+   - Otros procesadores los expone con nombres y formatos diferentes
+   - El texto de ayuda no refleja los valores predeterminados de las variables de entorno
+
+Ambos conjuntos de parámetros se conectan al mismo clúster de Cassandra, pero con diferentes convenciones de nombres, lo que provoca:
+- Confusión en la configuración para los usuarios
+- Mayor carga de mantenimiento
+- Documentación inconsistente
+- Posibilidad de configuración incorrecta
+- Incapacidad de anular la configuración mediante argumentos de línea de comandos en algunos procesadores
+
+## Solución Propuesta
+
+### 1. Estandarizar los Nombres de los Parámetros
+
+Todos los módulos utilizarán nombres de parámetros consistentes `cassandra_*`:
+- `cassandra_host` - Lista de hosts (almacenado internamente como lista)
+- `cassandra_username` - Nombre de usuario para la autenticación
+- `cassandra_contraseña` - Contraseña para la autenticación
+
+### 2. Argumentos de Línea de Comandos
+
+Todos los procesadores DEBEN exponer la configuración de Cassandra a través de argumentos de línea de comandos:
+- `--cassandra-host` - Lista separada por comas de hosts
+- `--cassandra-username` - Nombre de usuario para la autenticación
+- `--cassandra-password` - Contraseña para la autenticación
+
+### 3. Fallback de Variables de Entorno
+
+Si los parámetros de la línea de comandos no se proporcionan explícitamente, el sistema verificará las variables de entorno:
+- `CASSANDRA_HOST` - Lista separada por comas de hosts
+- `CASSANDRA_USERNAME` - Nombre de usuario para la autenticación
+- `CASSANDRA_PASSWORD` - Contraseña para la autenticación
+
+### 4. Valores Predeterminados
+
+Si ni los parámetros de la línea de comandos ni las variables de entorno no se especifican:
+- `cassandra_host` se establece en `["cassandra"]`
+- `cassandra_username` se establece en `None` (sin autenticación)
+- `cassandra_password` se establece en `None` (sin autenticación)
+
+### 5. Requisitos de Ayuda
+
+La salida `--help` DEBE:
+- Mostrar los valores predeterminados de las variables de entorno
+- Nunca mostrar los valores de la contraseña (mostrar `****` o `<set>` en su lugar)
+- Indicar claramente el orden de resolución en la ayuda
+
+Ejemplo de salida de ayuda:
+```
+--cassandra-host HOST
+    Lista de hosts de Cassandra, separada por comas (predeterminado: prod-cluster-1,prod-cluster-2)
+    [desde la variable de entorno CASSANDRA_HOST]
+
+--cassandra-username USERNAME
+    Nombre de usuario de Cassandra (predeterminado: cassandra_user)
+    [desde la variable de entorno CASSANDRA_USERNAME]
+
+--cassandra-password PASSWORD
+    Contraseña de Cassandra (predeterminado: <establecido desde el entorno>)
+```
+
+## Detalles de Implementación
+
+### Orden de Resolución
+Para cada parámetro de Cassandra, el orden de resolución será:
+1. Valor del argumento de la línea de comandos
+2. Variable de entorno (`CASSANDRA_*`)
+3. Valor predeterminado
+
+### Manejo del parámetro Host
+El parámetro `cassandra_host`:
+- La línea de comandos acepta una cadena separada por comas: `--cassandra-host "host1,host2,host3"`
+- La variable de entorno acepta una cadena separada por comas: `CASSANDRA_HOST="host1,host2,host3"`
+- Internamente siempre se almacena como una lista: `["host1", "host2", "host3"]`
+
+### Código de Ejemplo
+```python
+# Código antiguo
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help='Host del gráfico (predeterminado: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help='Nombre de usuario de Cassandra'
+    )
+
+# Código nuevo
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Usa el asistente estándar
+```
+
+### Actualización de Módulos que Utilizan `graph_*` Parámetros
+1. Cambiar los nombres de los parámetros de `graph_*` a `cassandra_*`
+2. Reemplazar los métodos `add_args()` personalizados
+3. Utilizar las funciones `add_cassandra_args()` estándar
+4. Actualizar las cadenas de documentación
+
+Ejemplo de transformación:
+```python
+# Código antiguo
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Host del gráfico (predeterminado: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Nombre de usuario de Cassandra'
+    )
+
+# Código nuevo
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Usa el asistente estándar
+```
+
+### Actualización de Módulos que Utilizan `cassandra_*` Parámetros
+1. Agregar soporte para argumentos de línea de comandos (p. ej., `kg-store`)
+2. Reemplazar las definiciones de argumentos existentes con `add_cassandra_args()`
+3. Utilizar las funciones `resolve_cassandra_config()` para una resolución consistente
+4. Asegurar el manejo consistente de las listas de hosts
+
+### Actualización de Pruebas y Documentación
+1. Actualizar todos los archivos de prueba
+2. Actualizar la documentación de la línea de comandos
+3. Actualizar la documentación de la API
+4. Actualizar los ejemplos de Docker Compose
+5. Actualizar la documentación de referencia de la configuración
+
+## Compatibilidad con versiones anteriores
+
+Para mantener la compatibilidad con versiones anteriores durante la transición:
+
+1. **Advertencias de desuso** para los parámetros `graph_*`
+2. **Alias de parámetros** - aceptar nombres antiguos y nuevos inicialmente
+3. **Implementación gradual** durante varios lanzamientos
+4. **Actualizaciones de documentación** con guía de migración
+
+Ejemplo de código para la compatibilidad con versiones anteriores:
+```python
+def __init__(self, **params):
+    # Manejar parámetros graph_* desactualizados
+    if 'graph_host' in params:
+        warnings.warn("graph_host está desactualizado, usa cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+
+    if 'graph_username' in params:
+        warnings.warn("graph_username está desactualizado, usa cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+
+    # ... continuar con la resolución estándar
+```
+
+## Estrategia de Pruebas
+
+1. **Pruebas unitarias** para la lógica de resolución de la configuración
+2. **Pruebas de integración** con diversas combinaciones de configuración
+3. **Pruebas de variables de entorno**
+4. **Pruebas de compatibilidad con versiones anteriores** con parámetros desactualizados
+5. **Pruebas de Docker compose** con variables de entorno
+
+## Actualizaciones de Documentación
+
+1. Actualizar toda la documentación de la línea de comandos
+2. Actualizar la documentación de la API
+3. Crear una guía de migración
+4. Actualizar los ejemplos de Docker Compose
+5. Actualizar la documentación de referencia de la configuración
+
+## Riesgos y Mitigación
+
+| Riesgo | Impacto | Mitigación |
+|------|--------|------------|
+| Cambios que rompen para los usuarios | Alto | Implementar un período de compatibilidad con versiones anteriores |
+| Confusión en la configuración durante la transición | Medio | Documentación clara y advertencias de desuso |
+| Fallos de prueba | Medio | Actualizaciones exhaustivas de prueba |
+| Problemas de implementación de Docker | Alto | Actualizar todos los ejemplos de Docker Compose |
+
+## Criterios de Éxito
+
+- [ ] Todos los módulos utilizan nombres de parámetros consistentes `cassandra_*`
+- [ ] Todos los procesadores expone la configuración de Cassandra a través de argumentos de línea de comandos
+- [ ] La salida de la ayuda muestra los valores predeterminados de las variables de entorno
+- [ ] Los valores de la contraseña nunca se muestran en la ayuda
+- [ ] La retroalimentación de las variables de entorno funciona correctamente
+- [ ] El parámetro `cassandra_host` se gestiona de forma consistente como una lista internamente
+- [ ] Se mantiene la compatibilidad con versiones anteriores durante al menos 2 lanzamientos
+- [ ] Todas las pruebas pasan con el nuevo sistema de configuración
+- [ ] La documentación está actualizada
+- [ ] Los ejemplos de Docker Compose funcionan con las variables de entorno
+
+## Cronograma
+
+- **Semana 1:** Implementar el asistente de configuración común y actualizar los módulos que utilizan `graph_*`
+- **Semana 2:** Agregar soporte de variable de entorno a los módulos existentes que utilizan `cassandra_*`
+- **Semana 3:** Actualizar las cadenas de documentación
+- **Semana 4:** Pruebas de integración y correcciones de errores
+
+## Consideraciones Futuras
+
+- Considerar extender este patrón a otras configuraciones de bases de datos (p. ej., Elasticsearch)
+- Implementar la validación de la configuración y mejores mensajes de error
+- Agregar soporte para la configuración de conexión de piscina (connection pooling)
+- Considerar agregar soporte para archivos `.env`

docs/tech-specs/cassandra-consolidation.he.md

@@ -0,0 +1,331 @@
+# מפרט טכני: איחוד תצורת Cassandra
+
+**סטטוס:** טיוטה
+**כותב:** עוזר
+**תאריך:** 2024-09-03
+
+## סקירה כללית
+
+מפרט זה עוסק בדפוסי שמות ותצורות לא עקביים עבור פרמטרי חיבור ל-Cassandra ברחבי בסיס הקוד של TrustGraph. כיום, קיימים שני סכימות שמות פרמטרים שונות (`cassandra_*` לעומת `graph_*`), מה שמוביל לבלבול ולמורכבות תחזוקה.
+
+## הצגת הבעיה
+
+בסיס הקוד משתמש כיום בשתי קבוצות נפרדות של פרמטרי תצורה של Cassandra:
+
+1. **מודולים של Knowledge/Config/Library** משתמשים:
+   `cassandra_host` (רשימת מארחים)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **מודולים של Graph/Storage** משתמשים:
+   `graph_host` (מאריך יחיד, לעיתים מומר לרשימה)
+   `graph_username`
+   `graph_password`
+
+3. **חשיפה לא עקבית דרך שורת הפקודה**:
+   חלק מהמעבדים (לדוגמה, `kg-store`) אינם חושפים הגדרות Cassandra כארגומנטים של שורת הפקודה
+   מעבדים אחרים חושפים אותם עם שמות ופורמטים שונים
+   טקסט העזרה אינו משקף ערכי משתני סביבה ברירת מחדל
+
+שתי קבוצות הפרמטרים מתחברות לאותו кластер Cassandra, אך עם קונבנציות שמות שונות, מה שגורם ל:
+בלבול בתצורת משתמשים
+עומס תחזוקה מוגבר
+תיעוד לא עקבי
+פוטנציאל לטעות בתצורה
+חוסר יכולת לשנות הגדרות דרך שורת הפקודה בחלק מהמעבדים
+
+## פתרון מוצע
+
+### 1. סטנדרטיזציה של שמות פרמטרים
+
+כל המודולים ישתמשו בשמות פרמטרים עקביים של `cassandra_*`:
+`cassandra_host` - רשימת מארחים (מאוחסנת פנימית כרשימה)
+`cassandra_username` - שם משתמש לאימות
+`cassandra_password` - סיסמה לאימות
+
+### 2. ארגומנטים של שורת הפקודה
+
+כל המעבדים חייבים לחשוף את תצורת Cassandra דרך ארגומנטים של שורת הפקודה:
+`--cassandra-host` - רשימה מופרדת בפסיקים של מארחים
+`--cassandra-username` - שם משתמש לאימות
+`--cassandra-password` - סיסמה לאימות
+
+### 3. חלופה של משתני סביבה
+
+אם לא סופקו פרמטרים של שורת הפקודה, המערכת תבדוק משתני סביבה:
+`CASSANDRA_HOST` - רשימה מופרדת בפסיקים של מארחים
+`CASSANDRA_USERNAME` - שם משתמש לאימות
+`CASSANDRA_PASSWORD` - סיסמה לאימות
+
+### 4. ערכי ברירת מחדל
+
+אם לא צוינו פרמטרים של שורת פקודה ולא משתני סביבה:
+`cassandra_host` ברירת המחדל היא `["cassandra"]`
+`cassandra_username` ברירת המחדל היא `None` (ללא אימות)
+`cassandra_password` ברירת המחדל היא `None` (ללא אימות)
+
+### 5. דרישות טקסט עזרה
+
+הפלט של `--help` חייב:
+להציג ערכי משתני סביבה כברירות מחדל כאשר הם מוגדרים
+לעולם לא להציג ערכי סיסמה (להציג `****` או `<set>` במקום)
+לציין בבירור את סדר הפתרון בטקסט העזרה
+
+דוגמה לפלט עזרה:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## פרטי יישום
+
+### סדר פתרון פרמטרים
+
+עבור כל פרמטר של Cassandra, סדר הפתרון יהיה:
+1. ערך ארגומנט שורת הפקודה
+2. משתנה סביבה (`CASSANDRA_*`)
+3. ערך ברירת מחדל
+
+### טיפול בפרמטרים של מארחים
+
+הפרמטר `cassandra_host`:
+שורת הפקודה מקבלת מחרוזת מופרדת בפסיקים: `--cassandra-host "host1,host2,host3"`
+משתנה סביבה מקבל מחרוזת מופרדת בפסיקים: `CASSANDRA_HOST="host1,host2,host3"`
+באופן פנימי תמיד מאוחסן כרשימה: `["host1", "host2", "host3"]`
+מארח בודד: `"localhost"` → מומר ל-`["localhost"]`
+כבר רשימה: `["host1", "host2"]` → משמש כפי שהוא
+
+### לוגיקת אימות
+
+אימות ישמש כאשר גם `cassandra_username` וגם `cassandra_password` מסופקים:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## קבצים שיש לשנות
+
+### מודולים המשתמשים בפרמטרים `graph_*` (שיש לשנות):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### מודולים המשתמשים בפרמטרים `cassandra_*` (שיש לעדכן עם אפשרות חלופה):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### קבצי בדיקה שיש לעדכן:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## אסטרטגיית יישום
+
+### שלב 1: יצירת כלי עזר להגדרות משותפות
+צור פונקציות עזר לסטנדרטיזציה של הגדרות Cassandra בכל המעבדים:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### שלב 2: עדכון מודולים באמצעות פרמטרים `graph_*`
+1. שנה שמות הפרמטרים מ-`graph_*` ל-`cassandra_*`
+2. החלף שיטות `add_args()` מותאמות אישית בשיטות `add_cassandra_args()` סטנדרטיות
+3. השתמש בפונקציות העזר לתצורה נפוצות
+4. עדכן מחרוזות תיעוד
+
+דוגמה לטרנספורמציה:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### שלב 3: עדכון מודולים באמצעות פרמטרים `cassandra_*`
+1. הוספת תמיכה בארגומנטים משורת הפקודה היכן שחסרים (לדוגמה, `kg-store`)
+2. החלפת הגדרות ארגומנטים קיימות ב-`add_cassandra_args()`
+3. שימוש ב-`resolve_cassandra_config()` עבור פתרון עקבי
+4. הבטחת טיפול עקבי ברשימת השרתים
+
+### שלב 4: עדכון בדיקות ותיעוד
+1. עדכון כל קבצי הבדיקה לשימוש בשמות פרמטרים חדשים
+2. עדכון תיעוד שורת הפקודה (CLI)
+3. עדכון תיעוד API
+4. הוספת תיעוד עבור משתני סביבה
+
+## תאימות לאחור
+
+על מנת לשמור על תאימות לאחור במהלך המעבר:
+
+1. **אזהרות הפסקה** עבור פרמטרים `graph_*`
+2. **כינוי פרמטרים** - קבלת שמות ישנים וחדשים בתחילה
+3. **פריסה מדורגת** על פני מספר גרסאות
+4. **עדכוני תיעוד** עם מדריך מעבר
+
+דוגמה לקוד תאימות לאחור:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## אסטרטגיית בדיקות
+
+1. **בדיקות יחידה** עבור לוגיקת פתרון תצורה
+2. **בדיקות אינטגרציה** עם שילובים שונים של תצורות
+3. **בדיקות משתני סביבה** 
+4. **בדיקות תאימות לאחור** עם פרמטרים מיושנים
+5. **בדיקות Docker Compose** עם משתני סביבה
+
+## עדכוני תיעוד
+
+1. עדכון כל התיעוד של פקודות שורת הפקודה
+2. עדכון תיעוד API
+3. יצירת מדריך מעבר
+4. עדכון דוגמאות Docker Compose
+5. עדכון תיעוד הפניה לתצורה
+
+## סיכונים ודרכי התמודדות
+
+| סיכון | השפעה | דרך התמודדות |
+|------|--------|------------|
+| שינויים שעלולים לפגוע במשתמשים | גבוהה | יישום תקופת תאימות לאחור |
+| בלבול בתצורה במהלך המעבר | בינונית | תיעוד ברור ואזהרות על הפסקה |
+| כשלים בבדיקות | בינונית | עדכוני בדיקות מקיפים |
+| בעיות בפריסת Docker | גבוהה | עדכון כל דוגמאות Docker Compose |
+
+## קריטריוני הצלחה
+
+[ ] כל המודולים משתמשים בשמות פרמטרים אחידים `cassandra_*`
+[ ] כל המעבדים חושפים הגדרות Cassandra באמצעות ארגומנטים של שורת הפקודה
+[ ] טקסט העזרה של שורת הפקודה מציג ערכי ברירת מחדל של משתני סביבה
+[ ] ערכי סיסמה לעולם אינם מוצגים בטקסט העזרה
+[ ] מנגנון החלפה למשתני סביבה פועל כהלכה
+[ ] `cassandra_host` מטופל באופן עקבי כרשימה באופן פנימי
+[ ] תאימות לאחור נשמרת לפחות עבור 2 גרסאות
+[ ] כל הבדיקות עוברות עם מערכת התצורה החדשה
+[ ] התיעוד מעודכן במלואו
+[ ] דוגמאות Docker Compose עובדות עם משתני סביבה
+
+## ציר זמן
+
+**שבוע 1:** יישום עזר תצורה משותף ועדכון מודולי `graph_*`
+**שבוע 2:** הוספת תמיכה במשתני סביבה למודולי `cassandra_*` קיימים
+**שבוע 3:** עדכון בדיקות ותיעוד
+**שבוע 4:** בדיקות אינטגרציה ותיקון באגים
+
+## שיקולים עתידיים
+
+שקול להרחיב את התבנית הזו לתצורות מסדי נתונים אחרות (לדוגמה, Elasticsearch)
+יישום אימות תצורה והודעות שגיאה טובות יותר
+הוספת תמיכה בתצורת חיבור בריכת חיבורים של Cassandra
+שקול להוסיף תמיכה בקבצי תצורה (.env files)

docs/tech-specs/cassandra-consolidation.hi.md

@@ -0,0 +1,331 @@
+# तकनीकी विनिर्देश: कैसेंड्रा कॉन्फ़िगरेशन समेकन
+
+**स्थिति:** मसौदा
+**लेखक:** सहायक
+**तिथि:** 2024-09-03
+
+## अवलोकन
+
+यह विनिर्देश ट्रस्टग्राफ कोडबेस में कैसेंड्रा कनेक्शन मापदंडों के लिए असंगत नामकरण और कॉन्फ़िगरेशन पैटर्न को संबोधित करता है। वर्तमान में, दो अलग-अलग पैरामीटर नामकरण योजनाएं मौजूद हैं (`cassandra_*` बनाम `graph_*`), जिससे भ्रम और रखरखाव जटिलता होती है।
+
+## समस्या विवरण
+
+कोडबेस वर्तमान में कैसेंड्रा कॉन्फ़िगरेशन मापदंडों के दो अलग-अलग सेट का उपयोग करता है:
+
+1. **ज्ञान/कॉन्फ़िग/लाइब्रेरी मॉड्यूल** निम्नलिखित का उपयोग करते हैं:
+   `cassandra_host` (होस्ट की सूची)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **ग्राफ/भंडारण मॉड्यूल** निम्नलिखित का उपयोग करते हैं:
+   `graph_host` (एकल होस्ट, कभी-कभी सूची में परिवर्तित)
+   `graph_username`
+   `graph_password`
+
+3. **असंगत कमांड-लाइन एक्सपोजर**:
+   कुछ प्रोसेसर (जैसे, `kg-store`) कैसेंड्रा सेटिंग्स को कमांड-लाइन तर्कों के रूप में उजागर नहीं करते हैं
+   अन्य प्रोसेसर उन्हें अलग-अलग नामों और प्रारूपों के साथ उजागर करते हैं
+   सहायता पाठ पर्यावरण चर डिफ़ॉल्ट को प्रतिबिंबित नहीं करता है
+
+दोनों पैरामीटर सेट एक ही कैसेंड्रा क्लस्टर से जुड़ते हैं, लेकिन अलग-अलग नामकरण सम्मेलनों के साथ, जिससे:
+उपयोगकर्ताओं के लिए कॉन्फ़िगरेशन भ्रम
+रखरखाव का बढ़ता बोझ
+असंगत प्रलेखन
+गलत कॉन्फ़िगरेशन की संभावना
+कुछ प्रोसेसर में कमांड-लाइन के माध्यम से सेटिंग्स को ओवरराइड करने में असमर्थता
+
+## प्रस्तावित समाधान
+
+### 1. पैरामीटर नामों का मानकीकरण
+
+सभी मॉड्यूल सुसंगत `cassandra_*` पैरामीटर नामों का उपयोग करेंगे:
+`cassandra_host` - होस्ट की सूची (आंतरिक रूप से सूची के रूप में संग्रहीत)
+`cassandra_username` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
+`cassandra_password` - प्रमाणीकरण के लिए पासवर्ड
+
+### 2. कमांड-लाइन तर्क
+
+सभी प्रोसेसर को कैसेंड्रा कॉन्फ़िगरेशन को कमांड-लाइन तर्कों के माध्यम से उजागर करना होगा:
+`--cassandra-host` - होस्ट की अल्पविराम-विभाजित सूची
+`--cassandra-username` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
+`--cassandra-password` - प्रमाणीकरण के लिए पासवर्ड
+
+### 3. पर्यावरण चर बैकअप
+
+यदि कमांड-लाइन पैरामीटर स्पष्ट रूप से प्रदान नहीं किए जाते हैं, तो सिस्टम पर्यावरण चर की जांच करेगा:
+`CASSANDRA_HOST` - होस्ट की अल्पविराम-विभाजित सूची
+`CASSANDRA_USERNAME` - प्रमाणीकरण के लिए उपयोगकर्ता नाम
+`CASSANDRA_PASSWORD` - प्रमाणीकरण के लिए पासवर्ड
+
+### 4. डिफ़ॉल्ट मान
+
+यदि न तो कमांड-लाइन पैरामीटर और न ही पर्यावरण चर निर्दिष्ट हैं:
+`cassandra_host` डिफ़ॉल्ट रूप से `["cassandra"]` है
+`cassandra_username` डिफ़ॉल्ट रूप से `None` है (कोई प्रमाणीकरण नहीं)
+`cassandra_password` डिफ़ॉल्ट रूप से `None` है (कोई प्रमाणीकरण नहीं)
+
+### 5. सहायता पाठ आवश्यकताएँ
+
+`--help` आउटपुट को:
+जब सेट किया गया हो तो पर्यावरण चर मानों को डिफ़ॉल्ट के रूप में दिखाना चाहिए
+पासवर्ड मानों को कभी भी प्रदर्शित नहीं करना चाहिए (इसके बजाय `****` या `<set>` दिखाएं)
+सहायता पाठ में समाधान क्रम को स्पष्ट रूप से इंगित करना चाहिए
+
+उदाहरण सहायता आउटपुट:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## कार्यान्वयन विवरण
+
+### पैरामीटर समाधान का क्रम
+
+प्रत्येक कैसेंड्रा पैरामीटर के लिए, समाधान का क्रम इस प्रकार होगा:
+1. कमांड-लाइन तर्क मान
+2. पर्यावरण चर (`CASSANDRA_*`)
+3. डिफ़ॉल्ट मान
+
+### होस्ट पैरामीटर हैंडलिंग
+
+`cassandra_host` पैरामीटर:
+कमांड-लाइन अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: `--cassandra-host "host1,host2,host3"`
+पर्यावरण चर अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: `CASSANDRA_HOST="host1,host2,host3"`
+आंतरिक रूप से हमेशा सूची के रूप में संग्रहीत किया जाता है: `["host1", "host2", "host3"]`
+एकल होस्ट: `"localhost"` → `["localhost"]` में परिवर्तित
+पहले से ही एक सूची: `["host1", "host2"]` → जैसा है उपयोग किया जाता है
+
+### प्रमाणीकरण तर्क
+
+प्रमाणीकरण का उपयोग तब किया जाएगा जब `cassandra_username` और `cassandra_password` दोनों प्रदान किए जाते हैं:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## संशोधित करने योग्य फ़ाइलें
+
+### `graph_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें बदला जाना है):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### `cassandra_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें पर्यावरण बैकअप के साथ अपडेट किया जाना है):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### अपडेट करने योग्य परीक्षण फ़ाइलें:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## कार्यान्वयन रणनीति
+
+### चरण 1: सामान्य कॉन्फ़िगरेशन हेल्पर बनाएं
+सभी प्रोसेसरों में कैसेंड्रा कॉन्फ़िगरेशन को मानकीकृत करने के लिए उपयोगिता फ़ंक्शन बनाएं:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### चरण 2: `graph_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें
+1. पैरामीटर नामों को `graph_*` से `cassandra_*` में बदलें
+2. कस्टम `add_args()` विधियों को मानकीकृत `add_cassandra_args()` से बदलें
+3. सामान्य कॉन्फ़िगरेशन सहायक फ़ंक्शन का उपयोग करें
+4. दस्तावेज़ स्ट्रिंग को अपडेट करें
+
+उदाहरण परिवर्तन:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### चरण 3: `cassandra_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें
+1. उन स्थानों पर कमांड-लाइन तर्क समर्थन जोड़ें जहां यह गायब है (उदाहरण के लिए, `kg-store`)
+2. मौजूदा तर्क परिभाषाओं को `add_cassandra_args()` से बदलें
+3. सुसंगत समाधान के लिए `resolve_cassandra_config()` का उपयोग करें
+4. सुसंगत होस्ट सूची प्रबंधन सुनिश्चित करें
+
+### चरण 4: परीक्षण और दस्तावेज़ को अपडेट करें
+1. सभी परीक्षण फ़ाइलों को नए पैरामीटर नामों का उपयोग करने के लिए अपडेट करें
+2. CLI दस्तावेज़ को अपडेट करें
+3. API दस्तावेज़ को अपडेट करें
+4. पर्यावरण चर दस्तावेज़ जोड़ें
+
+## पिछली अनुकूलता
+
+संक्रमण के दौरान पिछली अनुकूलता बनाए रखने के लिए:
+
+1. `graph_*` पैरामीटर के लिए **अवरोधन चेतावनी**
+2. **पैरामीटर उपनाम** - शुरू में पुराने और नए दोनों नामों को स्वीकार करें
+3. कई रिलीज़ में **चरणबद्ध कार्यान्वयन**
+4. माइग्रेशन गाइड के साथ **दस्तावेज़ अपडेट**
+
+पिछली अनुकूलता कोड का उदाहरण:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## परीक्षण रणनीति
+
+1. **यूनिट परीक्षण** कॉन्फ़िगरेशन रिज़ॉल्यूशन लॉजिक के लिए
+2. विभिन्न कॉन्फ़िगरेशन संयोजनों के साथ **एकीकरण परीक्षण**
+3. **पर्यावरण चर परीक्षण**
+4. **पिछड़ा संगतता परीक्षण** अप्रचलित मापदंडों के साथ
+5. **डॉकर कंपोज़ परीक्षण** पर्यावरण चर के साथ
+
+## दस्तावेज़ अपडेट
+
+1. सभी CLI कमांड दस्तावेज़ों को अपडेट करें
+2. API दस्तावेज़ों को अपडेट करें
+3. माइग्रेशन गाइड बनाएं
+4. डॉकर कंपोज़ उदाहरणों को अपडेट करें
+5. कॉन्फ़िगरेशन संदर्भ दस्तावेज़ को अपडेट करें
+
+## जोखिम और निवारण
+
+| जोखिम | प्रभाव | निवारण |
+|------|--------|------------|
+| उपयोगकर्ताओं के लिए ब्रेकिंग परिवर्तन | उच्च | पिछड़े संगतता अवधि लागू करें |
+| संक्रमण के दौरान कॉन्फ़िगरेशन भ्रम | मध्यम | स्पष्ट दस्तावेज़ और अवमूल्यन चेतावनियाँ |
+| परीक्षण विफलताएँ | मध्यम | व्यापक परीक्षण अपडेट |
+| डॉकर परिनियोजन मुद्दे | उच्च | सभी डॉकर कंपोज़ उदाहरणों को अपडेट करें |
+
+## सफलता मानदंड
+
+[ ] सभी मॉड्यूल सुसंगत `cassandra_*` पैरामीटर नामों का उपयोग करते हैं
+[ ] सभी प्रोसेसर कमांड-लाइन तर्कों के माध्यम से कैसेंड्रा सेटिंग्स को उजागर करते हैं
+[ ] कमांड-लाइन सहायता पाठ पर्यावरण चर डिफ़ॉल्ट दिखाता है
+[ ] पासवर्ड मान कभी भी सहायता पाठ में प्रदर्शित नहीं होते हैं
+[ ] पर्यावरण चर बैकअप सही ढंग से काम करता है
+[ ] `cassandra_host` को आंतरिक रूप से लगातार एक सूची के रूप में संभाला जाता है
+[ ] कम से कम 2 रिलीज़ के लिए पिछड़े संगतता बनाए रखी जाती है
+[ ] सभी परीक्षण नए कॉन्फ़िगरेशन सिस्टम के साथ पास होते हैं
+[ ] दस्तावेज़ पूरी तरह से अपडेट किया गया है
+[ ] डॉकर कंपोज़ उदाहरण पर्यावरण चर के साथ काम करते हैं
+
+## समयरेखा
+
+**सप्ताह 1:** सामान्य कॉन्फ़िगरेशन हेल्पर लागू करें और `graph_*` मॉड्यूल को अपडेट करें
+**सप्ताह 2:** मौजूदा `cassandra_*` मॉड्यूल में पर्यावरण चर समर्थन जोड़ें
+**सप्ताह 3:** परीक्षण और दस्तावेज़ अपडेट करें
+**सप्ताह 4:** एकीकरण परीक्षण और बग फिक्स
+
+## भविष्य के विचार
+
+अन्य डेटाबेस कॉन्फ़िगरेशन (जैसे, Elasticsearch) के लिए इस पैटर्न को विस्तारित करने पर विचार करें
+कॉन्फ़िगरेशन सत्यापन और बेहतर त्रुटि संदेश लागू करें
+कैसेंड्रा कनेक्शन पूलिंग कॉन्फ़िगरेशन के लिए समर्थन जोड़ें
+कॉन्फ़िगरेशन फ़ाइल समर्थन (.env फ़ाइलें) जोड़ने पर विचार करें

docs/tech-specs/cassandra-consolidation.pt.md

@@ -0,0 +1,331 @@
+# Especificação Técnica: Consolidação da Configuração do Cassandra
+
+**Status:** Rascunho
+**Autor:** Assistente
+**Data:** 2024-09-03
+
+## Visão Geral
+
+Esta especificação aborda os padrões de nomenclatura e configuração inconsistentes para os parâmetros de conexão do Cassandra em todo o código-fonte do TrustGraph. Atualmente, existem dois esquemas de nomenclatura de parâmetros diferentes (`cassandra_*` vs `graph_*`), o que leva à confusão e à complexidade da manutenção.
+
+## Declaração do Problema
+
+O código-fonte atualmente usa dois conjuntos distintos de parâmetros de configuração do Cassandra:
+
+1. **Módulos Knowledge/Config/Library** usam:
+   `cassandra_host` (lista de hosts)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **Módulos Graph/Storage** usam:
+   `graph_host` (um único host, às vezes convertido em lista)
+   `graph_username`
+   `graph_password`
+
+3. **Exposição inconsistente na linha de comando**:
+   Alguns processadores (por exemplo, `kg-store`) não expõem as configurações do Cassandra como argumentos de linha de comando
+   Outros processadores os expõem com nomes e formatos diferentes
+   O texto de ajuda não reflete os valores padrão das variáveis de ambiente
+
+Ambos os conjuntos de parâmetros se conectam ao mesmo cluster Cassandra, mas com convenções de nomenclatura diferentes, causando:
+Confusão na configuração para os usuários
+Aumento da carga de manutenção
+Documentação inconsistente
+Potencial para configuração incorreta
+Impossibilidade de substituir as configurações via linha de comando em alguns processadores
+
+## Solução Proposta
+
+### 1. Padronização dos Nomes dos Parâmetros
+
+Todos os módulos usarão nomes de parâmetros `cassandra_*` consistentes:
+`cassandra_host` - Lista de hosts (armazenada internamente como lista)
+`cassandra_username` - Nome de usuário para autenticação
+`cassandra_password` - Senha para autenticação
+
+### 2. Argumentos da Linha de Comando
+
+Todos os processadores DEVEM expor a configuração do Cassandra por meio de argumentos de linha de comando:
+`--cassandra-host` - Lista separada por vírgulas de hosts
+`--cassandra-username` - Nome de usuário para autenticação
+`--cassandra-password` - Senha para autenticação
+
+### 3. Fallback de Variáveis de Ambiente
+
+Se os parâmetros da linha de comando não forem fornecidos explicitamente, o sistema verificará as variáveis de ambiente:
+`CASSANDRA_HOST` - Lista separada por vírgulas de hosts
+`CASSANDRA_USERNAME` - Nome de usuário para autenticação
+`CASSANDRA_PASSWORD` - Senha para autenticação
+
+### 4. Valores Padrão
+
+Se nem os parâmetros da linha de comando nem as variáveis de ambiente forem especificados:
+`cassandra_host` tem como padrão `["cassandra"]`
+`cassandra_username` tem como padrão `None` (sem autenticação)
+`cassandra_password` tem como padrão `None` (sem autenticação)
+
+### 5. Requisitos do Texto de Ajuda
+
+A saída `--help` deve:
+Mostrar os valores das variáveis de ambiente como padrões quando definidos
+Nunca exibir valores de senha (exibir `****` ou `<set>` em vez disso)
+Indicar claramente a ordem de resolução no texto de ajuda
+
+Exemplo de saída de ajuda:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## Detalhes de Implementação
+
+### Ordem de Resolução de Parâmetros
+
+Para cada parâmetro do Cassandra, a ordem de resolução será:
+1. Valor do argumento de linha de comando
+2. Variável de ambiente (`CASSANDRA_*`)
+3. Valor padrão
+
+### Tratamento de Parâmetros de Host
+
+O parâmetro `cassandra_host`:
+A linha de comando aceita uma string separada por vírgulas: `--cassandra-host "host1,host2,host3"`
+A variável de ambiente aceita uma string separada por vírgulas: `CASSANDRA_HOST="host1,host2,host3"`
+Internamente sempre armazenado como uma lista: `["host1", "host2", "host3"]`
+Host único: `"localhost"` → convertido para `["localhost"]`
+Já é uma lista: `["host1", "host2"]` → usado como está
+
+### Lógica de Autenticação
+
+A autenticação será usada quando tanto `cassandra_username` quanto `cassandra_password` forem fornecidos:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## Arquivos a serem modificados
+
+### Módulos que utilizam parâmetros `graph_*` (a serem alterados):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### Módulos que utilizam parâmetros `cassandra_*` (a serem atualizados com fallback do ambiente):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### Arquivos de teste a serem atualizados:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## Estratégia de implementação
+
+### Fase 1: Criar um utilitário de configuração comum
+Crie funções utilitárias para padronizar a configuração do Cassandra em todos os processadores:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### Fase 2: Atualizar Módulos Usando Parâmetros `graph_*`
+1. Alterar os nomes dos parâmetros de `graph_*` para `cassandra_*`
+2. Substituir os métodos personalizados `add_args()` por métodos padronizados `add_cassandra_args()`
+3. Usar as funções auxiliares de configuração comuns
+4. Atualizar as strings de documentação
+
+Exemplo de transformação:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### Fase 3: Atualizar Módulos Usando Parâmetros `cassandra_*`
+1. Adicionar suporte para argumentos de linha de comando onde estiver faltando (por exemplo, `kg-store`)
+2. Substituir as definições de argumentos existentes por `add_cassandra_args()`
+3. Usar `resolve_cassandra_config()` para resolução consistente
+4. Garantir o tratamento consistente da lista de hosts
+
+### Fase 4: Atualizar Testes e Documentação
+1. Atualizar todos os arquivos de teste para usar os novos nomes de parâmetros
+2. Atualizar a documentação da CLI
+3. Atualizar a documentação da API
+4. Adicionar documentação de variáveis de ambiente
+
+## Compatibilidade com Versões Anteriores
+
+Para manter a compatibilidade com versões anteriores durante a transição:
+
+1. **Avisos de descontinuação** para parâmetros `graph_*`
+2. **Aliasing de parâmetros** - aceitar tanto os nomes antigos quanto os novos inicialmente
+3. **Implementação gradual** ao longo de várias versões
+4. **Atualizações na documentação** com um guia de migração
+
+Exemplo de código de compatibilidade com versões anteriores:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## Estratégia de Testes
+
+1. **Testes unitários** para a lógica de resolução de configuração
+2. **Testes de integração** com várias combinações de configuração
+3. **Testes de variáveis de ambiente**
+4. **Testes de compatibilidade retroativa** com parâmetros obsoletos
+5. **Testes do Docker Compose** com variáveis de ambiente
+
+## Atualizações da Documentação
+
+1. Atualizar toda a documentação dos comandos da linha de comando
+2. Atualizar a documentação da API
+3. Criar um guia de migração
+4. Atualizar os exemplos do Docker Compose
+5. Atualizar a documentação de referência de configuração
+
+## Riscos e Mitigações
+
+| Risco | Impacto | Mitigação |
+|------|--------|------------|
+| Mudanças que podem afetar os usuários | Alto | Implementar um período de compatibilidade retroativa |
+| Confusão na configuração durante a transição | Médio | Documentação clara e avisos de descontinuação |
+| Falhas nos testes | Médio | Atualizações abrangentes nos testes |
+| Problemas de implantação do Docker | Alto | Atualizar todos os exemplos do Docker Compose |
+
+## Critérios de Sucesso
+
+[ ] Todos os módulos usam nomes de parâmetros `cassandra_*` consistentes
+[ ] Todos os processadores expõem as configurações do Cassandra por meio de argumentos da linha de comando
+[ ] O texto de ajuda da linha de comando mostra os valores padrão das variáveis de ambiente
+[ ] Os valores de senha nunca são exibidos no texto de ajuda
+[ ] O fallback de variáveis de ambiente funciona corretamente
+[ ] `cassandra_host` é tratado de forma consistente como uma lista internamente
+[ ] A compatibilidade retroativa é mantida por pelo menos 2 versões
+[ ] Todos os testes passam com o novo sistema de configuração
+[ ] A documentação está totalmente atualizada
+[ ] Os exemplos do Docker Compose funcionam com variáveis de ambiente
+
+## Cronograma
+
+**Semana 1:** Implementar o utilitário de configuração comum e atualizar os módulos `graph_*`
+**Semana 2:** Adicionar suporte a variáveis de ambiente aos módulos `cassandra_*` existentes
+**Semana 3:** Atualizar testes e documentação
+**Semana 4:** Testes de integração e correção de bugs
+
+## Considerações Futuras
+
+Considerar a extensão desse padrão para outras configurações de banco de dados (por exemplo, Elasticsearch)
+Implementar validação de configuração e melhores mensagens de erro
+Adicionar suporte para configuração de pool de conexões do Cassandra
+Considerar a adição de suporte para arquivos de configuração (.env)

docs/tech-specs/cassandra-consolidation.ru.md

@@ -0,0 +1,331 @@
+# Техническое описание: Консолидация конфигурации Cassandra
+
+**Статус:** Черновик
+**Автор:** Assistant
+**Дата:** 2024-09-03
+
+## Обзор
+
+Данное техническое описание посвящено неконсистентности именования и шаблонов конфигурации параметров подключения к Cassandra в кодовой базе TrustGraph. В настоящее время существуют две различные схемы именования параметров (`cassandra_*` против `graph_*`), что приводит к путанице и усложняет обслуживание.
+
+## Описание проблемы
+
+В кодовой базе в настоящее время используются два различных набора параметров конфигурации Cassandra:
+
+1. **Модули Knowledge/Config/Library** используют:
+   `cassandra_host` (список хостов)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **Модули Graph/Storage** используют:
+   `graph_host` (один хост, иногда преобразуется в список)
+   `graph_username`
+   `graph_password`
+
+3. **Неконсистентное использование в командной строке**:
+   Некоторые процессоры (например, `kg-store`) не предоставляют параметры Cassandra в качестве аргументов командной строки
+   Другие процессоры предоставляют их с разными именами и форматами
+   Тексты справки не отражают значения переменных окружения по умолчанию
+
+Оба набора параметров подключаются к одному кластеру Cassandra, но с разными соглашениями об именовании, что приводит к:
+Путанице в конфигурации для пользователей
+Увеличенной нагрузке на обслуживание
+Неконсистентной документации
+Возможности неправильной конфигурации
+Невозможности перезаписать настройки через командную строку в некоторых процессорах
+
+## Предлагаемое решение
+
+### 1. Стандартизация имен параметров
+
+Все модули будут использовать согласованные имена параметров `cassandra_*`:
+`cassandra_host` - Список хостов (хранится внутри как список)
+`cassandra_username` - Имя пользователя для аутентификации
+`cassandra_password` - Пароль для аутентификации
+
+### 2. Аргументы командной строки
+
+Все процессоры ДОЛЖНЫ предоставлять конфигурацию Cassandra через аргументы командной строки:
+`--cassandra-host` - Список хостов, разделенный запятыми
+`--cassandra-username` - Имя пользователя для аутентификации
+`--cassandra-password` - Пароль для аутентификации
+
+### 3. Передача через переменные окружения
+
+Если параметры командной строки не указаны явно, система будет проверять переменные окружения:
+`CASSANDRA_HOST` - Список хостов, разделенный запятыми
+`CASSANDRA_USERNAME` - Имя пользователя для аутентификации
+`CASSANDRA_PASSWORD` - Пароль для аутентификации
+
+### 4. Значения по умолчанию
+
+Если ни параметры командной строки, ни переменные окружения не указаны:
+`cassandra_host` по умолчанию `["cassandra"]`
+`cassandra_username` по умолчанию `None` (без аутентификации)
+`cassandra_password` по умолчанию `None` (без аутентификации)
+
+### 5. Требования к тексту справки
+
+Вывод команды `--help` должен:
+Показывать значения переменных окружения в качестве значений по умолчанию, если они установлены
+Никогда не отображать значения паролей (показывать `****` или `<set>` вместо этого)
+Четко указывать порядок разрешения в тексте справки
+
+Пример вывода справки:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## Детали реализации
+
+### Порядок разрешения параметров
+
+Для каждого параметра Cassandra порядок разрешения будет следующим:
+1. Значение аргумента командной строки
+2. Значение переменной окружения (`CASSANDRA_*`)
+3. Значение по умолчанию
+
+### Обработка параметров хостов
+
+Параметр `cassandra_host`:
+Командная строка принимает строку, разделенную запятыми: `--cassandra-host "host1,host2,host3"`
+Переменная окружения принимает строку, разделенную запятыми: `CASSANDRA_HOST="host1,host2,host3"`
+Внутри всегда хранится в виде списка: `["host1", "host2", "host3"]`
+Один хост: `"localhost"` → преобразуется в `["localhost"]`
+Уже является списком: `["host1", "host2"]` → используется как есть
+
+### Логика аутентификации
+
+Аутентификация будет использоваться, когда указаны и `cassandra_username`, и `cassandra_password`:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## Файлы для изменения
+
+### Модули, использующие параметры `graph_*` (которые необходимо изменить):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### Модули, использующие параметры `cassandra_*` (которые необходимо обновить с использованием резервного варианта из среды):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### Тестовые файлы для обновления:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## Стратегия реализации
+
+### Этап 1: Создание общего вспомогательного класса конфигурации
+Создайте вспомогательные функции для стандартизации конфигурации Cassandra во всех процессорах:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### Фаза 2: Обновление модулей с использованием параметров `graph_*`
+1. Изменить имена параметров с `graph_*` на `cassandra_*`
+2. Заменить собственные методы `add_args()` на стандартизированные методы `add_cassandra_args()`
+3. Использовать общие вспомогательные функции конфигурации
+4. Обновить строки документации
+
+Пример преобразования:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### Фаза 3: Обновление модулей с использованием параметров `cassandra_*`
+1. Добавить поддержку аргументов командной строки там, где это отсутствует (например, `kg-store`).
+2. Заменить существующие определения аргументов на `add_cassandra_args()`.
+3. Использовать `resolve_cassandra_config()` для обеспечения согласованности разрешения.
+4. Обеспечить согласованную обработку списка хостов.
+
+### Фаза 4: Обновление тестов и документации
+1. Обновить все файлы тестов для использования новых имен параметров.
+2. Обновить документацию CLI.
+3. Обновить документацию API.
+4. Добавить документацию по переменным окружения.
+
+## Обратная совместимость
+
+Для поддержания обратной совместимости во время перехода:
+
+1. **Предупреждения об устаревании** для параметров `graph_*`.
+2. **Псевдонимы параметров** - изначально принимать как старые, так и новые имена.
+3. **Поэтапное внедрение** в течение нескольких релизов.
+4. **Обновления документации** с руководством по миграции.
+
+Пример кода обратной совместимости:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## Стратегия тестирования
+
+1. **Юнит-тесты** для логики разрешения конфигурации
+2. **Интеграционные тесты** с различными комбинациями конфигурации
+3. **Тесты переменных окружения**
+4. **Тесты обратной совместимости** с устаревшими параметрами
+5. **Тесты Docker Compose** с переменными окружения
+
+## Обновления документации
+
+1. Обновить всю документацию по командам CLI
+2. Обновить документацию API
+3. Создать руководство по миграции
+4. Обновить примеры Docker Compose
+5. Обновить справочную документацию по конфигурации
+
+## Риски и меры по их снижению
+
+| Риск | Влияние | Меры по снижению |
+|------|--------|------------|
+| Изменения, нарушающие работу пользователей | Высокое | Реализовать период обратной совместимости |
+| Спутанность конфигурации во время перехода | Среднее | Четкая документация и предупреждения об устаревании |
+| Сбои в тестах | Среднее | Комплексное обновление тестов |
+| Проблемы при развертывании Docker | Высокое | Обновить все примеры Docker Compose |
+
+## Критерии успеха
+
+[ ] Все модули используют согласованные имена параметров `cassandra_*`
+[ ] Все процессоры предоставляют настройки Cassandra через аргументы командной строки
+[ ] Текстовая справка по командной строке показывает значения переменных окружения по умолчанию
+[ ] Значения паролей никогда не отображаются в справке
+[ ] Механизм отката к переменным окружения работает правильно
+[ ] `cassandra_host` последовательно обрабатывается как список внутри
+[ ] Обратная совместимость поддерживается не менее 2 версий
+[ ] Все тесты проходят с новой системой конфигурации
+[ ] Документация полностью обновлена
+[ ] Примеры Docker Compose работают с переменными окружения
+
+## План
+
+**Неделя 1:** Реализовать общий помощник конфигурации и обновить модули `graph_*`
+**Неделя 2:** Добавить поддержку переменных окружения в существующие модули `cassandra_*`
+**Неделя 3:** Обновить тесты и документацию
+**Неделя 4:** Интеграционное тестирование и исправление ошибок
+
+## Будущие соображения
+
+Рассмотреть возможность расширения этой модели на другие конфигурации баз данных (например, Elasticsearch)
+Реализовать проверку конфигурации и улучшенные сообщения об ошибках
+Добавить поддержку конфигурации пула соединений Cassandra
+Рассмотреть возможность добавления поддержки файлов конфигурации (.env)

docs/tech-specs/cassandra-consolidation.sw.md

@@ -0,0 +1,331 @@
+# Maelekezo ya Kisaikolojia: Uunganishaji wa Vipengele vya Usanidi wa Cassandra
+
+**Hali:** Rasimu
+**Mwandishi:** Msaidizi
+**Tarehe:** 2024-09-03
+
+## Muhtasari
+
+Maelekezo haya yanashughulikia utofauti katika majina na mifumo ya usanidi kwa vigezo vya muunganisho wa Cassandra katika mfumo wa TrustGraph. Kwa sasa, mifumo miwili tofauti ya majina ya vigezo ipo (`cassandra_*` vs `graph_*`), ambayo husababisha mchanganyiko na ugumu wa matengenezo.
+
+## Tatizo
+
+Mfumo wa programu hutumia seti mbili tofauti za vigezo vya usanidi wa Cassandra:
+
+1. **Moduli za /Config/Library za Maarifa** hutumia:
+   `cassandra_host` (orodha ya seva)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **Moduli za /Storage za Grafu** hutumia:
+   `graph_host` (seva moja, wakati mwingine hubadilishwa kuwa orodha)
+   `graph_username`
+   `graph_password`
+
+3. **Uonyeshaji usio sawa wa amri:**
+   Baadhi ya vichakata (e.g., `kg-store`) hazionyeshi mipangilio ya Cassandra kama hoja za amri
+   Vichakata vingine huonyesha kwa majina na muundo tofauti
+   Nakala ya usaidizi haionyeshi maadili chaguo-msingi ya vigezo vya mazingira
+
+Seti zote mbili za vigezo zinaunganisha na kundi sawa la Cassandra lakini kwa mikataba tofauti ya majina, na kusababisha:
+Mchanganyiko wa usanidi kwa watumiaji
+Ongezeko la mzigo wa matengenezo
+Nyaraka zisizo sawa
+Uwezekano wa usanidi usio sahihi
+Uwezo wa kutofanya ubadilishaji wa mipangilio kupitia hoja za amri katika vichakata vingine
+
+## Suluhisho Lililopendekezwa
+
+### 1. Kuweka Majina ya Vigezo
+
+Moduli zote zitatumia majina sawa ya vigezo ya `cassandra_*`:
+`cassandra_host` - Orodha ya seva (hifadhiwa ndani kama orodha)
+`cassandra_username` - Jina la mtumiaji kwa uthibitishaji
+`cassandra_password` - Nenosiri kwa uthibitishaji
+
+### 2. Hoja za Amri
+
+Vichakata vyote WILIVYO na kuonyesha usanidi wa Cassandra kupitia hoja za amri:
+`--cassandra-host` - Orodha iliyoachwa na alama ya mwelekeo wa koma ya seva
+`--cassandra-username` - Jina la mtumiaji kwa uthibitishaji
+`--cassandra-password` - Nenosiri kwa uthibitishaji
+
+### 3. Usaidizi wa Vigezo vya Mazingira
+
+Ikiwa hoja za amri hazitolewi wazi, mfumo utangalia vigezo vya mazingira:
+`CASSANDRA_HOST` - Orodha iliyoachwa na alama ya mwelekeo wa koma ya seva
+`CASSANDRA_USERNAME` - Jina la mtumiaji kwa uthibitishaji
+`CASSANDRA_PASSWORD` - Nenosiri kwa uthibitishaji
+
+### 4. Maadili Chaguo-msingi
+
+Ikiwa hoja za amri wala vigezo vya mazingira hazibainishwi:
+`cassandra_host` huanguka kwenye `["cassandra"]`
+`cassandra_username` huanguka kwenye `None` (hakuna uthibitishaji)
+`cassandra_password` huanguka kwenye `None` (hakuna uthibitishaji)
+
+### 5. Mahitaji ya Nakala ya Usaidizi
+
+Pato la `--help` lazima:
+Kuonyesha maadili ya vigezo vya mazingira kama chaguo-msingi wakati yamepangwa
+Kamwe kuonyesha maadili ya nenosiri (onyesha `****` au `<set>` badala yake)
+Kuonyesha wazi utaratibu wa utatuzi katika nakala ya usaidizi
+
+Mfano wa pato la usaidizi:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## Maelezo ya Utendaji
+
+### Utaratibu wa Uamuzi wa Vigezo
+
+Kwa kila kiparamu cha Cassandra, utaratibu wa uamuzi utakuwa:
+1. Thamani ya hoja ya mstari wa amri
+2. Kigezo cha mazingira (`CASSANDRA_*`)
+3. Thamani chaguo-msingi
+
+### Usimamizi wa Kiparamu cha Host
+
+Kiparamu cha `cassandra_host`:
+Mstari wa amri unapokea mnyororo ulioachiliwa na alama ya kung'aa: `--cassandra-host "host1,host2,host3"`
+Kigezo cha mazingira kinapokea mnyororo ulioachiliwa na alama ya kung'aa: `CASSANDRA_HOST="host1,host2,host3"`
+Daima kuhifadhiwa kama orodha ndani: `["host1", "host2", "host3"]`
+Host moja: `"localhost"` → inabadilishwa kuwa `["localhost"]`
+Tayari ni orodha: `["host1", "host2"]` → inatumika kama ilivyo
+
+### Mantiki ya Uthibitisho
+
+Uthibitisho utatumika wakati `cassandra_username` na `cassandra_password` zote zimetolewa:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## Faili Zinazohitaji Marekebisho
+
+### Moduli zinazotumia vigezo vya `graph_*` (zinazohitaji kubadilishwa):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### Moduli zinazotumia vigezo vya `cassandra_*` (zinazohitaji kusasishwa na chaguo-msingi la mazingira):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### Faili za Majaribio Zinazohitaji Kusasishwa:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## Mbinu ya Utendaji
+
+### Hatua ya 1: Unda Msaidizi wa Mpangilio wa Msingi
+Unda kazi za matumizi ili kuhakikisha mpangilio wa Cassandra ni sawa katika vichakata vyote:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### Awamu ya 2: Sasisha Moduli Ukitumia Vigezo vya `graph_*`
+1. Badilisha majina ya vigezo kutoka `graph_*` hadi `cassandra_*`
+2. Badilisha mbinu (methods) maalum za `add_args()` kwa mbinu za kawaida za `add_cassandra_args()`
+3. Tumia kazi (functions) za kawaida za usaidizi wa usanidi
+4. Sasisha maandishi ya utangazaji (documentation strings)
+
+Mfano wa mabadiliko:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### Awamu ya 3: Sasisha Moduli Ukitumia Vigezo vya `cassandra_*`
+1. Ongeza uunganisha wa hoja za mstari wa amri ambapo haipo (k.m., `kg-store`)
+2. Badilisha ufafanuzi wa hoja zilizopo kwa `add_cassandra_args()`
+3. Tumia `resolve_cassandra_config()` kwa utaratibu thabiti
+4. Hakikisha utunzaji thabiti wa orodha ya seva
+
+### Awamu ya 4: Sasisha Vipimo na Nyaraka
+1. Sasisha faili zote za vipimo ili zitumie majina mapya ya vigezo
+2. Sasisha nyaraka za CLI
+3. Sasisha nyaraka za API
+4. Ongeza nyaraka za vigezo vya mazingira
+
+## Ulinganishaji na Mifumo ya Zamani
+
+Ili kudumisha ulinganishaji na mifumo ya zamani wakati wa mabadiliko:
+
+1. **Maonyo ya kutolewa nje** kwa vigezo vya `graph_*`
+2. **Ujumuishaji wa vigezo** - kukubali majina ya zamani na mapya awali
+3. **Utoaji wa hatua kwa hatua** katika matoleo mengi
+4. **Sasisho za nyaraka** pamoja na mwongozo wa uhamishaji
+
+Mfano wa msimbo wa ulinganishaji na mifumo ya zamani:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## Mbinu ya Majaribio
+
+1. **Majaribio ya kitengo** kwa mantiki ya utatuzi wa usanidi
+2. **Majaribio ya ujumuishaji** na mchanganyiko mbalimbali wa usanidi
+3. **Majaribio ya vigezo vya mazingira**
+4. **Majaribio ya utangamano wa nyuma** na vigezo vilivyotolewa
+5. **Majaribio ya Docker compose** na vigezo vya mazingira
+
+## Sasisho za Nyaraka
+
+1. Sasisha nyaraka zote za amri za CLI
+2. Sasisha nyaraka za API
+3. Unda mwongozo wa uhamishaji
+4. Sasisha mifano ya Docker compose
+5. Sasisha nyaraka za kumbukumbu ya usanidi
+
+## Hatari na Kupunguza Madhara
+
+| Hatari | Athari | Kupunguza Madhara |
+|------|--------|------------|
+| Mabadiliko yanayoweza kusababisha matatizo kwa watumiaji | Ya juu | Tekeleza kipindi cha utangamano wa nyuma |
+| Uchanganyifu wa usanidi wakati wa mabadiliko | Ya kati | Nyaraka wazi na onyo la kutolewa |
+| Kushindwa kwa majaribio | Ya kati | Sasisho kamili ya majaribio |
+| Matatizo ya usakinishaji wa Docker | Ya juu | Sasisha mifano yote ya Docker compose |
+
+## Vigezo vya Mafanikio
+
+[ ] Moduli zote hutumia majina ya vigezo `cassandra_*` yanayofanana
+[ ] Wasindikaji wote huonyesha mipangilio ya Cassandra kupitia hoja za mstari wa amri
+[ ] Nakala ya msaada wa mstari wa amri inaonyesha chaguo-msingi ya vigezo vya mazingira
+[ ] Maelezo ya nenosiri hayajaonyeshwa katika nakala ya msaada
+[ ] Mfumo wa kurudisha nyuma wa vigezo vya mazingira unafanya kazi vizuri
+[ ] `cassandra_host` inashughulikiwa kwa utaratibu kama orodha ndani
+[ ] Utangamano wa nyuma umeendelezwa kwa angalau matoleo 2
+[ ] Majaribio yote hupita na mfumo mpya wa usanidi
+[ ] Nyaraka zimesasishwa kikamilifu
+[ ] Mifano ya Docker compose inafanya kazi na vigezo vya mazingira
+
+## Ratiba
+
+**Wiki ya 1:** Tekeleza kusaidia usanidi wa kawaida na sasisha moduli za `graph_*`
+**Wiki ya 2:** Ongeza usaidizi wa vigezo vya mazingira kwa moduli zilizopo za `cassandra_*`
+**Wiki ya 3:** Sasisha majaribio na nyaraka
+**Wiki ya 4:** Majaribio ya ujumuishaji na urekebishaji wa hitilafu
+
+## Mambo ya Kuzingatia ya Baadaye
+
+Fikiria kuongeza muundo huu kwa usanidi mwingine wa hifadhidata (e.g., Elasticsearch)
+Tekeleza uthibitisho wa usanidi na ujumbe bora wa kosa
+Ongeza usaidizi wa usanidi wa muunganisho wa Cassandra (e.g., pooli)
+Fikiria kuongeza usaidizi wa faili za usanidi (.env files)

docs/tech-specs/cassandra-consolidation.tr.md

@@ -0,0 +1,331 @@
+# Cassandra Yapılandırma Birleştirme: Teknik Özellikler
+
+**Durum:** Taslak
+**Yazar:** Yardımcı
+**Tarih:** 2024-09-03
+
+## Genel Bakış
+
+Bu özellik, TrustGraph kod tabanındaki Cassandra bağlantı parametreleri için tutarsız adlandırma ve yapılandırma kalıplarını ele almaktadır. Şu anda, iki farklı parametre adlandırma şeması bulunmaktadır (`cassandra_*` ve `graph_*`), bu da kafa karışıklığına ve bakım karmaşıklığına yol açmaktadır.
+
+## Sorun Tanımı
+
+Kod tabanı şu anda iki farklı Cassandra yapılandırma parametre seti kullanmaktadır:
+
+1. **Bilgi/Yapılandırma/Kütüphane modülleri** aşağıdaki parametreleri kullanır:
+   `cassandra_host` (sunucu listesi)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **Grafik/Depolama modülleri** aşağıdaki parametreleri kullanır:
+   `graph_host` (tek bir sunucu, bazen listeye dönüştürülür)
+   `graph_username`
+   `graph_password`
+
+3. **Tutarsız komut satırı kullanımı**:
+   Bazı işleme birimleri (örneğin, `kg-store`), Cassandra ayarlarını komut satırı argümanları olarak sunmaz
+   Diğer işleme birimleri bunları farklı adlar ve formatlarla sunar
+   Yardım metni, ortam değişkeni varsayılanlarını yansıtmaz
+
+Her iki parametre seti de aynı Cassandra kümesine bağlanır, ancak farklı adlandırma kuralları kullanır, bu da şunlara neden olur:
+Kullanıcılar için yapılandırma karışıklığı
+Artan bakım yükü
+Tutarsız dokümantasyon
+Yanlış yapılandırma riski
+Bazı işleme birimlerinde ayarları komut satırı aracılığıyla geçersiz kılma imkansızlığı
+
+## Önerilen Çözüm
+
+### 1. Parametre Adlarını Standartlaştırın
+
+Tüm modüller, tutarlı `cassandra_*` parametre adlarını kullanacaktır:
+`cassandra_host` - Sunucu listesi (içeride liste olarak saklanır)
+`cassandra_username` - Kimlik doğrulama için kullanıcı adı
+`cassandra_password` - Kimlik doğrulama için parola
+
+### 2. Komut Satırı Argümanları
+
+TÜM işleme birimleri, Cassandra yapılandırmasını komut satırı argümanları aracılığıyla sunmalıdır:
+`--cassandra-host` - Virgülle ayrılmış sunucu listesi
+`--cassandra-username` - Kimlik doğrulama için kullanıcı adı
+`--cassandra-password` - Kimlik doğrulama için parola
+
+### 3. Ortam Değişkeni Geri Düşüşü
+
+Komut satırı parametreleri açıkça sağlanmadığında, sistem ortam değişkenlerini kontrol edecektir:
+`CASSANDRA_HOST` - Virgülle ayrılmış sunucu listesi
+`CASSANDRA_USERNAME` - Kimlik doğrulama için kullanıcı adı
+`CASSANDRA_PASSWORD` - Kimlik doğrulama için parola
+
+### 4. Varsayılan Değerler
+
+Ne komut satırı parametreleri ne de ortam değişkenleri belirtilmediğinde:
+`cassandra_host`, `["cassandra"]`'e varsayılan olarak ayarlanır
+`cassandra_username`, `None`'e (kimlik doğrulama yok) varsayılan olarak ayarlanır
+`cassandra_password`, `None`'e (kimlik doğrulama yok) varsayılan olarak ayarlanır
+
+### 5. Yardım Metni Gereksinimleri
+
+`--help` çıktısı şunları içermelidir:
+Ortam değişkeni değerleri ayarlandığında, bunları varsayılan değerler olarak göstermelidir
+Parola değerlerini asla göstermemelidir (bunun yerine `****` veya `<set>` göstermelidir)
+Çözüm sırasını yardım metninde açıkça belirtmelidir
+
+Örnek yardım çıktısı:
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## Uygulama Detayları
+
+### Parametre Çözümleme Sırası
+
+Her Cassandra parametresi için, çözümleme sırası aşağıdaki olacaktır:
+1. Komut satırı argümanı değeri
+2. Ortam değişkeni (`CASSANDRA_*`)
+3. Varsayılan değer
+
+### Ana Bilgisayar Parametreleri Yönetimi
+
+`cassandra_host` parametresi:
+Komut satırı, virgülle ayrılmış bir dize kabul eder: `--cassandra-host "host1,host2,host3"`
+Ortam değişkeni, virgülle ayrılmış bir dize kabul eder: `CASSANDRA_HOST="host1,host2,host3"`
+İçeride her zaman bir liste olarak saklanır: `["host1", "host2", "host3"]`
+Tek bir ana bilgisayar: `"localhost"` → `["localhost"]`'e dönüştürülür
+Zaten bir liste: `["host1", "host2"]` → olduğu gibi kullanılır
+
+### Kimlik Doğrulama Mantığı
+
+Kimlik doğrulama, hem `cassandra_username` hem de `cassandra_password` sağlandığında kullanılacaktır:
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## Değiştirilecek Dosyalar
+
+### `graph_*` parametrelerini kullanan modüller (değiştirilecek):
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### `cassandra_*` parametrelerini kullanan modüller (ortam değişkeni geri dönüşü ile güncellenecek):
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### Güncellenecek Test Dosyaları:
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## Uygulama Stratejisi
+
+### Aşama 1: Ortak Yapılandırma Yardımcı Programı Oluşturma
+Tüm işlemcilerde Cassandra yapılandırmasını standartlaştırmak için yardımcı işlevler oluşturun:
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### 2. Aşama: `graph_*` Parametrelerini Kullanan Modülleri Güncelleme
+1. Parametre adlarını `graph_*`'dan `cassandra_*`'e değiştirin.
+2. Özel `add_args()` yöntemlerini standart `add_cassandra_args()` yöntemleriyle değiştirin.
+3. Ortak yapılandırma yardımcı fonksiyonlarını kullanın.
+4. Dokümantasyon metinlerini güncelleyin.
+
+Örnek dönüşüm:
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### 3. Aşama: `cassandra_*` Parametrelerini Kullanarak Modülleri Güncelleme
+1. Eksik olan yerlerde komut satırı argümanı desteğini ekleyin (örneğin, `kg-store`)
+2. Mevcut argüman tanımlarını `add_cassandra_args()` ile değiştirin
+3. Tutarlı çözümleme için `resolve_cassandra_config()`'ı kullanın
+4. Tutarlı ana bilgisayar listesi işleme sağlayın
+
+### 4. Aşama: Testleri ve Belgeleri Güncelleme
+1. Tüm test dosyalarını yeni parametre adlarını kullanacak şekilde güncelleyin
+2. Komut satırı (CLI) belgelerini güncelleyin
+3. API belgelerini güncelleyin
+4. Ortam değişkeni belgelerini ekleyin
+
+## Geriye Dönük Uyumluluk
+
+Geçiş sırasında geriye dönük uyumluluğu korumak için:
+
+1. `graph_*` parametreleri için **kullanımdan kaldırma uyarıları**
+2. **Parametre takma adları** - başlangıçta hem eski hem de yeni adları kabul edin
+3. **Aşamalı dağıtım** birden fazla sürümde
+4. **Belge güncellemeleri** ve geçiş kılavuzu
+
+Örnek geriye dönük uyumluluk kodu:
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## Test Stratejisi
+
+1. **Birim testleri**, yapılandırma çözümleme mantığı için
+2. **Entegrasyon testleri**, çeşitli yapılandırma kombinasyonlarıyla
+3. **Ortam değişkeni testleri**
+4. **Geriye dönük uyumluluk testleri**, kullanımdan kaldırılmış parametrelerle
+5. **Docker compose testleri**, ortam değişkenleriyle
+
+## Dokümantasyon Güncellemeleri
+
+1. Tüm CLI komutu dokümantasyonunu güncelleyin
+2. API dokümantasyonunu güncelleyin
+3. Geçiş kılavuzu oluşturun
+4. Docker compose örneklerini güncelleyin
+5. Yapılandırma referans dokümantasyonunu güncelleyin
+
+## Riskler ve Azaltma
+
+| Risk | Etki | Azaltma |
+|------|--------|------------|
+| Kullanıcılar için bozucu değişiklikler | Yüksek | Geriye dönük uyumluluk süresi uygulayın |
+| Geçiş sırasında yapılandırma karışıklığı | Orta | Açık dokümantasyon ve kullanımdan kaldırma uyarıları |
+| Test hataları | Orta | Kapsamlı test güncellemeleri |
+| Docker dağıtım sorunları | Yüksek | Tüm Docker compose örneklerini güncelleyin |
+
+## Başarı Kriterleri
+
+[ ] Tüm modüller, tutarlı `cassandra_*` parametre adlarını kullanır
+[ ] Tüm işlemciler, Cassandra ayarlarını komut satırı argümanları aracılığıyla sunar
+[ ] Komut satırı yardım metni, ortam değişkeni varsayılanlarını gösterir
+[ ] Parola değerleri, yardım metninde asla görüntülenmez
+[ ] Ortam değişkeni yedeklemesi doğru şekilde çalışır
+[ ] `cassandra_host`, dahili olarak tutarlı bir şekilde bir liste olarak işlenir
+[ ] Geriye dönüştürülebilirlik, en az 2 sürüm için korunur
+[ ] Tüm testler, yeni yapılandırma sistemiyle geçer
+[ ] Dokümantasyon tamamen güncellenmiştir
+[ ] Docker compose örnekleri, ortam değişkenleriyle çalışır
+
+## Zaman Çizelgesi
+
+**1. Hafta:** Ortak yapılandırma yardımcı programını uygulayın ve `graph_*` modüllerini güncelleyin
+**2. Hafta:** Mevcut `cassandra_*` modüllerine ortam değişkeni desteği ekleyin
+**3. Hafta:** Testleri ve dokümantasyonu güncelleyin
+**4. Hafta:** Entegrasyon testi ve hata düzeltmeleri
+
+## Gelecek Hususlar
+
+Bu kalıbı diğer veritabanı yapılandırmalarına (örneğin, Elasticsearch) genişletmeyi düşünün
+Yapılandırma doğrulama ve daha iyi hata mesajları uygulayın
+Cassandra bağlantı havuzu yapılandırması desteği ekleyin
+Yapılandırma dosyası desteği eklemeyi düşünün (.env dosyaları)

docs/tech-specs/cassandra-consolidation.zh-cn.md

@@ -0,0 +1,331 @@
+# 技术规范：Cassandra 配置整合
+
+**状态：** 草稿
+**作者：** 助理
+**日期：** 2024-09-03
+
+## 概述
+
+本规范旨在解决 TrustGraph 代码库中 Cassandra 连接参数命名和配置模式的不一致问题。目前，存在两种不同的参数命名方案（`cassandra_*` 与 `graph_*`），这导致了混乱和维护复杂性。
+
+## 问题陈述
+
+当前代码库使用两组不同的 Cassandra 配置参数：
+
+1. **知识/配置/库模块** 使用：
+   `cassandra_host` (主机列表)
+   `cassandra_user`
+   `cassandra_password`
+
+2. **图/存储模块** 使用：
+   `graph_host` (单个主机，有时转换为列表)
+   `graph_username`
+   `graph_password`
+
+3. **命令行暴露不一致：**
+   一些处理器（例如，`kg-store`）不将 Cassandra 设置作为命令行参数暴露
+   其他处理器以不同的名称和格式暴露这些设置
+   帮助文本未反映环境变量的默认值
+
+这两组参数都连接到同一个 Cassandra 集群，但使用不同的命名约定，导致：
+用户配置混乱
+维护负担增加
+文档不一致
+可能出现配置错误
+在某些处理器中，无法通过命令行覆盖设置
+
+## 解决方案
+
+### 1. 标准化参数名称
+
+所有模块都将使用一致的 `cassandra_*` 参数名称：
+`cassandra_host` - 主机列表（内部存储为列表）
+`cassandra_username` - 身份验证用户名
+`cassandra_password` - 身份验证密码
+
+### 2. 命令行参数
+
+所有处理器都必须通过命令行参数暴露 Cassandra 配置：
+`--cassandra-host` - 逗号分隔的主机列表
+`--cassandra-username` - 身份验证用户名
+`--cassandra-password` - 身份验证密码
+
+### 3. 环境变量回退
+
+如果未显式提供命令行参数，系统将检查环境变量：
+`CASSANDRA_HOST` - 逗号分隔的主机列表
+`CASSANDRA_USERNAME` - 身份验证用户名
+`CASSANDRA_PASSWORD` - 身份验证密码
+
+### 4. 默认值
+
+如果未指定命令行参数或环境变量：
+`cassandra_host` 默认为 `["cassandra"]`
+`cassandra_username` 默认为 `None` (无身份验证)
+`cassandra_password` 默认为 `None` (无身份验证)
+
+### 5. 帮助文本要求
+
+`--help` 输出必须：
+显示已设置的环境变量值作为默认值
+绝不显示密码值（显示 `****` 或 `<set>` 代替）
+在帮助文本中清楚地指示解析顺序
+
+示例帮助输出：
+```
+--cassandra-host HOST
+    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
+    [from CASSANDRA_HOST environment variable]
+
+--cassandra-username USERNAME
+    Cassandra username (default: cassandra_user)
+    [from CASSANDRA_USERNAME environment variable]
+    
+--cassandra-password PASSWORD  
+    Cassandra password (default: <set from environment>)
+```
+
+## 实现细节
+
+### 参数解析顺序
+
+对于每个 Cassandra 参数，解析顺序如下：
+1. 命令行参数值
+2. 环境变量 (`CASSANDRA_*`)
+3. 默认值
+
+### 主机参数处理
+
+`cassandra_host` 参数：
+命令行接受逗号分隔的字符串：`--cassandra-host "host1,host2,host3"`
+环境变量接受逗号分隔的字符串：`CASSANDRA_HOST="host1,host2,host3"`
+内部始终存储为列表：`["host1", "host2", "host3"]`
+单个主机：`"localhost"` → 转换为 `["localhost"]`
+已经是列表：`["host1", "host2"]` → 保持原样
+
+### 认证逻辑
+
+当同时提供 `cassandra_username` 和 `cassandra_password` 时，将使用认证：
+```python
+if cassandra_username and cassandra_password:
+    # Use SSL context and PlainTextAuthProvider
+else:
+    # Connect without authentication
+```
+
+## 需要修改的文件
+
+### 使用 `graph_*` 参数的模块（需要修改）：
+`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
+`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+
+### 使用 `cassandra_*` 参数的模块（需要更新，并使用环境变量回退）：
+`trustgraph-flow/trustgraph/tables/config.py`
+`trustgraph-flow/trustgraph/tables/knowledge.py`
+`trustgraph-flow/trustgraph/tables/library.py`
+`trustgraph-flow/trustgraph/storage/knowledge/store.py`
+`trustgraph-flow/trustgraph/cores/knowledge.py`
+`trustgraph-flow/trustgraph/librarian/librarian.py`
+`trustgraph-flow/trustgraph/librarian/service.py`
+`trustgraph-flow/trustgraph/config/service/service.py`
+`trustgraph-flow/trustgraph/cores/service.py`
+
+### 需要更新的测试文件：
+`tests/unit/test_cores/test_knowledge_manager.py`
+`tests/unit/test_storage/test_triples_cassandra_storage.py`
+`tests/unit/test_query/test_triples_cassandra_query.py`
+`tests/integration/test_objects_cassandra_integration.py`
+
+## 实施策略
+
+### 第一阶段：创建通用的配置辅助工具
+创建实用函数，以标准化所有处理器中的 Cassandra 配置：
+
+```python
+import os
+import argparse
+
+def get_cassandra_defaults():
+    """Get default values from environment variables or fallback."""
+    return {
+        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
+        'username': os.getenv('CASSANDRA_USERNAME'),
+        'password': os.getenv('CASSANDRA_PASSWORD')
+    }
+
+def add_cassandra_args(parser: argparse.ArgumentParser):
+    """
+    Add standardized Cassandra arguments to an argument parser.
+    Shows environment variable values in help text.
+    """
+    defaults = get_cassandra_defaults()
+    
+    # Format help text with env var indication
+    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
+    if 'CASSANDRA_HOST' in os.environ:
+        host_help += " [from CASSANDRA_HOST]"
+    
+    username_help = f"Cassandra username"
+    if defaults['username']:
+        username_help += f" (default: {defaults['username']})"
+        if 'CASSANDRA_USERNAME' in os.environ:
+            username_help += " [from CASSANDRA_USERNAME]"
+    
+    password_help = "Cassandra password"
+    if defaults['password']:
+        password_help += " (default: <set>)"
+        if 'CASSANDRA_PASSWORD' in os.environ:
+            password_help += " [from CASSANDRA_PASSWORD]"
+    
+    parser.add_argument(
+        '--cassandra-host',
+        default=defaults['host'],
+        help=host_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-username',
+        default=defaults['username'],
+        help=username_help
+    )
+    
+    parser.add_argument(
+        '--cassandra-password',
+        default=defaults['password'],
+        help=password_help
+    )
+
+def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
+    """
+    Convert argparse args to Cassandra configuration.
+    
+    Returns:
+        tuple: (hosts_list, username, password)
+    """
+    # Convert host string to list
+    if isinstance(args.cassandra_host, str):
+        hosts = [h.strip() for h in args.cassandra_host.split(',')]
+    else:
+        hosts = args.cassandra_host
+    
+    return hosts, args.cassandra_username, args.cassandra_password
+```
+
+### 第二阶段：使用 `graph_*` 参数更新模块
+1. 将参数名称从 `graph_*` 更改为 `cassandra_*`
+2. 将自定义 `add_args()` 方法替换为标准化的 `add_cassandra_args()`
+3. 使用通用的配置辅助函数
+4. 更新文档字符串
+
+示例转换：
+```python
+# OLD CODE
+@staticmethod
+def add_args(parser):
+    parser.add_argument(
+        '-g', '--graph-host',
+        default="localhost",
+        help=f'Graph host (default: localhost)'
+    )
+    parser.add_argument(
+        '--graph-username',
+        default=None,
+        help=f'Cassandra username'
+    )
+
+# NEW CODE  
+@staticmethod
+def add_args(parser):
+    FlowProcessor.add_args(parser)
+    add_cassandra_args(parser)  # Use standard helper
+```
+
+### 第三阶段：使用 `cassandra_*` 参数更新模块
+1. 在缺失的地方添加命令行参数支持（例如：`kg-store`）
+2. 将现有的参数定义替换为 `add_cassandra_args()`
+3. 使用 `resolve_cassandra_config()` 以实现一致的解析
+4. 确保一致的主机列表处理
+
+### 第四阶段：更新测试和文档
+1. 更新所有测试文件以使用新的参数名称
+2. 更新命令行界面 (CLI) 文档
+3. 更新 API 文档
+4. 添加环境变量文档
+
+## 向后兼容性
+
+为了在过渡期间保持向后兼容性：
+
+1. **弃用警告**，用于 `graph_*` 参数
+2. **参数别名** - 初始阶段接受旧名称和新名称
+3. **分阶段发布**，在多个版本中进行
+4. **文档更新**，包含迁移指南
+
+示例向后兼容代码：
+```python
+def __init__(self, **params):
+    # Handle deprecated graph_* parameters
+    if 'graph_host' in params:
+        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
+        params.setdefault('cassandra_host', params.pop('graph_host'))
+    
+    if 'graph_username' in params:
+        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
+        params.setdefault('cassandra_username', params.pop('graph_username'))
+    
+    # ... continue with standard resolution
+```
+
+## 测试策略
+
+1. **单元测试**，用于配置解析逻辑
+2. **集成测试**，使用各种配置组合
+3. **环境变量测试**
+4. **向后兼容性测试**，针对已弃用的参数
+5. **Docker Compose 测试**，使用环境变量
+
+## 文档更新
+
+1. 更新所有 CLI 命令文档
+2. 更新 API 文档
+3. 创建迁移指南
+4. 更新 Docker Compose 示例
+5. 更新配置参考文档
+
+## 风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|--------|------------|
+| 对用户的破坏性更改 | 高 | 实施向后兼容性过渡期 |
+| 转换期间的配置混淆 | 中 | 清晰的文档和弃用警告 |
+| 测试失败 | 中 | 全面的测试更新 |
+| Docker 部署问题 | 高 | 更新所有 Docker Compose 示例 |
+
+## 成功标准
+
+[ ] 所有模块使用一致的 `cassandra_*` 参数名称
+[ ] 所有处理器通过命令行参数暴露 Cassandra 设置
+[ ] 命令行帮助文本显示环境变量的默认值
+[ ] 密码值绝不在帮助文本中显示
+[ ] 环境变量回退工作正常
+[ ] `cassandra_host` 内部始终被处理为列表
+[ ] 至少在 2 个版本中保持向后兼容性
+[ ] 所有测试在新配置系统中通过
+[ ] 文档已完全更新
+[ ] Docker Compose 示例使用环境变量
+
+## 时间线
+
+**第一周：** 实施通用的配置助手，并更新 `graph_*` 模块
+**第二周：** 为现有的 `cassandra_*` 模块添加环境变量支持
+**第三周：** 更新测试和文档
+**第四周：** 集成测试和错误修复
+
+## 未来考虑
+
+考虑将此模式扩展到其他数据库配置（例如，Elasticsearch）
+实施配置验证和更好的错误消息
+添加对 Cassandra 连接池配置的支持
+考虑添加对配置文件支持（.env 文件）

docs/tech-specs/cassandra-performance-refactor.ar.md

@@ -0,0 +1,679 @@
+# المواصفات الفنية: إعادة هيكلة أداء قاعدة المعرفة Cassandra
+
+**الحالة:** مسودة
+**المؤلف:** مساعد
+**التاريخ:** 2025-09-18
+
+## نظرة عامة
+
+تتناول هذه المواصفة مشكلات الأداء في تطبيق قاعدة المعرفة Cassandra TrustGraph وتقترح تحسينات لتخزين واستعلام ثلاثيات RDF.
+
+## التنفيذ الحالي
+
+### تصميم المخطط
+
+يستخدم التنفيذ الحالي تصميم جدول واحد في `trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**الفهارس الثانوية:**
+`triples_s` على `s` (الموضوع)
+`triples_p` على `p` (المُتَعَدِّي)
+`triples_o` على `o` (المفعول به)
+
+### أنماط الاستعلام
+
+تدعم التنفيذ الحالي 8 أنماط استعلام متميزة:
+
+1. **get_all(collection, limit=50)** - استرجاع جميع الثلاثيات لمجموعة
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - الاستعلام بناءً على الموضوع.
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - الاستعلام بناءً على شرط.
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - الاستعلام بناءً على الكائن.
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - الاستعلام بناءً على الموضوع + المسند.
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - الاستعلام بناءً على الشرط + الكائن ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - الاستعلام بناءً على الكائن والموضوع ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - تطابق ثلاثي دقيق.
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### البنية التحتية الحالية
+
+**الملف: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+فئة `KnowledgeGraph` واحدة تتعامل مع جميع العمليات.
+تجميع الاتصالات من خلال قائمة `_active_clusters` عامة.
+اسم جدول ثابت: `"triples"`.
+مساحة مفاتيح لكل نموذج مستخدم.
+استنساخ SimpleStrategy بعامل 1.
+
+**نقاط التكامل:**
+**مسار الكتابة:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`.
+**مسار الاستعلام:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`.
+**مخزن المعرفة:** `trustgraph-flow/trustgraph/tables/knowledge.py`.
+
+## المشكلات المتعلقة بالأداء التي تم تحديدها
+
+### مشكلات على مستوى المخطط
+
+1. **تصميم مفتاح أساسي غير فعال**
+   الحالي: `PRIMARY KEY (collection, s, p, o)`.
+   يؤدي إلى تجميع ضعيف لأنماط الوصول الشائعة.
+   يجبر على استخدام فهرس ثانوي مكلف.
+
+2. **إفراط في استخدام الفهرس الثانوي** ⚠️
+   ثلاثة فهارس ثانوية على أعمدة ذات قيم عالية (s، p، o).
+   الفهارس الثانوية في Cassandra مكلفة ولا تتوسع بشكل جيد.
+   تتطلب الاستعلامات 6 و 7 `ALLOW FILTERING` مما يشير إلى نموذج بيانات ضعيف.
+
+3. **خطر التقسيم الساخن**
+   يمكن أن يؤدي مفتاح التقسيم الواحد `collection` إلى إنشاء تقسيمات ساخنة.
+   ستتركز المجموعات الكبيرة على عقد فردية.
+   لا توجد استراتيجية توزيع لتحقيق موازنة التحميل.
+
+### مشكلات على مستوى الاستعلام
+
+1. **استخدام ALLOW FILTERING** ⚠️
+   يتطلب نوعان من الاستعلامات (get_po، get_os) `ALLOW FILTERING`.
+   هذه الاستعلامات تفحص العديد من التقسيمات وهي مكلفة للغاية.
+   يتدهور الأداء خطيًا مع حجم البيانات.
+
+2. **أنماط وصول غير فعالة**
+   لا توجد تحسينات لأنماط استعلام RDF الشائعة.
+   فهارس مركبة مفقودة لتوليفات الاستعلامات المتكررة.
+   لا توجد اعتبارات لأنماط اجتياز الرسم البياني.
+
+3. **نقص في تحسين الاستعلام**
+   لا يوجد تخزين مؤقت لبيانات الاستعلامات المُعدة.
+   لا توجد تلميحات أو استراتيجيات لتحسين الاستعلام.
+   لا توجد اعتبارات للتقسيم إلى صفحات تتجاوز LIMIT البسيطة.
+
+## بيان المشكلة
+
+يحتوي تطبيق قاعدة المعرفة الحالي في Cassandra على نقطتي اختناق أداء حاسمتين:
+
+### 1. أداء استعلام get_po غير فعال
+
+الاستعلام `get_po(collection, p, o)` غير فعال للغاية لأنه يتطلب `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**لماذا هذه مشكلة:**
+`ALLOW FILTERING` تجبر Cassandra على فحص جميع الأقسام داخل المجموعة.
+تتدهور الأداء بشكل خطي مع حجم البيانات.
+هذا نمط استعلام RDF شائع (إيجاد الموضوعات التي لها علاقة محددة بين الفاعل والمفعول به).
+يؤدي ذلك إلى زيادة كبيرة في الحمل على المجموعة مع نمو البيانات.
+
+### 2. استراتيجية تجميع غير فعالة
+
+المفتاح الأساسي الحالي `PRIMARY KEY (collection, s, p, o)` يوفر فوائد تجميع محدودة:
+
+**المشاكل المتعلقة بالتجميع الحالي:**
+`collection` كمفتاح قسم لا يوزع البيانات بشكل فعال.
+تحتوي معظم المجموعات على بيانات متنوعة مما يجعل التجميع غير فعال.
+لا توجد اعتبارات لأنماط الوصول الشائعة في استعلامات RDF.
+تخلق المجموعات الكبيرة أقسامًا "ساخنة" على عقد فردية.
+لا تعمل أعمدة التجميع (s، p، o) على تحسين أنماط اجتياز الرسم البياني النموذجية.
+
+**التأثير:**
+لا تستفيد الاستعلامات من قرب البيانات.
+استخدام ضعيف لذاكرة التخزين المؤقت.
+توزيع غير متساوٍ للحمل عبر عقد المجموعة.
+اختناقات في قابلية التوسع مع نمو المجموعات.
+
+## الحل المقترح: استراتيجية إلغاء التسوية باستخدام 4 جداول
+
+### نظرة عامة
+
+استبدل الجدول `triples` الواحد بأربعة جداول مصممة خصيصًا، كل منها مُحسَّن لأنماط استعلام محددة. هذا يلغي الحاجة إلى الفهارس الثانوية و ALLOW FILTERING مع توفير أداء مثالي لجميع أنواع الاستعلامات. يتيح الجدول الرابع حذف المجموعات بكفاءة على الرغم من مفاتيح الأقسام المركبة.
+
+### تصميم المخطط الجديد
+
+**الجدول 1: الاستعلامات المرتكزة على الموضوع (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**تحسينات:** get_s، get_sp، get_os
+**مفتاح التقسيم:** (collection, s) - توزيع أفضل من مجرد استخدام collection وحده.
+**التجميع:** (p, o) - يتيح عمليات بحث فعالة عن المحددات/الكائنات لكيان معين.
+
+**الجدول 2: استعلامات المحدد-الكائن (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**تحسين:** get_p, get_po (يزيل الحاجة إلى ALLOW FILTERING!)
+**مفتاح التقسيم:** (collection, p) - وصول مباشر عبر الشرط.
+**التجميع:** (o, s) - تصفح فعال للكائنات والموضوعات.
+
+**الجدول 3: الاستعلامات المرتكزة على الكائنات (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**التحسينات:** get_o
+**مفتاح التقسيم:** (collection, o) - وصول مباشر عن طريق الكائن
+**التجميع:** (s, p) - تصفح فعال للموضوع والمسند
+
+**الجدول 4: إدارة المجموعات والاستعلامات SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**التحسينات:** get_spo، delete_collection
+**مفتاح التقسيم:** مجموعة فقط - يتيح عمليات فعالة على مستوى المجموعة.
+**التجميع:** (s, p, o) - ترتيب ثلاثي قياسي.
+**الغرض:** استخدام مزدوج للبحث الدقيق عن SPO وكمؤشر للحذف.
+
+### تعيين الاستعلام
+
+| الاستعلام الأصلي | الجدول الهدف | تحسين الأداء |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | السماح بالتصفية (مقبول للمسح) |
+| get_s(collection, s) | triples_s | وصول مباشر إلى التقسيم |
+| get_p(collection, p) | triples_p | وصول مباشر إلى التقسيم |
+| get_o(collection, o) | triples_o | وصول مباشر إلى التقسيم |
+| get_sp(collection, s, p) | triples_s | التقسيم + التجميع |
+| get_po(collection, p, o) | triples_p | **لا مزيد من السماح بالتصفية!** |
+| get_os(collection, o, s) | triples_o | التقسيم + التجميع |
+| get_spo(collection, s, p, o) | triples_collection | بحث مباشر عن المفتاح |
+| delete_collection(collection) | triples_collection | قراءة الفهرس، حذف مجمع |
+
+### استراتيجية حذف المجموعة
+
+مع مفاتيح التقسيم المركبة، لا يمكننا ببساطة تنفيذ `DELETE FROM table WHERE collection = ?`. بدلاً من ذلك:
+
+1. **مرحلة القراءة:** استعلام `triples_collection` لسرد جميع الثلاثيات:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   هذا فعال لأنه `collection` هو مفتاح التقسيم لهذه الجدولة.
+
+2. **مرحلة الحذف:** لكل ثلاثية (s, p, o)، قم بالحذف من جميع الجداول الأربعة باستخدام مفاتيح التقسيم الكاملة:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   يتم تجميع البيانات في مجموعات مكونة من 100 عنصر لتحقيق الكفاءة.
+
+**تحليل المقايضات:**
+✅ يحافظ على الأداء الأمثل للاستعلامات مع الأقسام الموزعة.
+✅ لا توجد أقسام "ساخنة" للمجموعات الكبيرة.
+❌ منطق حذف أكثر تعقيدًا (قراءة ثم حذف).
+❌ وقت الحذف يتناسب مع حجم المجموعة.
+
+### المزايا
+
+1. **يزيل الحاجة إلى ALLOW FILTERING** - كل استعلام لديه مسار وصول أمثل (باستثناء فحص get_all).
+2. **لا توجد فهارس ثانوية** - كل جدول هو الفهرس لنمط الاستعلام الخاص به.
+3. **توزيع أفضل للبيانات** - مفاتيح التقسيم المركبة توزع الحمل بشكل فعال.
+4. **أداء متوقع** - وقت الاستعلام يتناسب مع حجم النتيجة، وليس إجمالي البيانات.
+5. **يستفيد من نقاط قوة Cassandra** - مصمم ليتناسب مع بنية Cassandra.
+6. **يمكن حذف المجموعات** - تعمل triples_collection كفهرس للحذف.
+
+## خطة التنفيذ
+
+### الملفات التي تتطلب تغييرات
+
+#### الملف الأساسي للتنفيذ
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - مطلوب إعادة كتابة كاملة.
+
+**الطرق الحالية التي تتطلب إعادة هيكلة:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### ملفات التكامل (لا يلزم إجراء أي تغييرات منطقية)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+لا يلزم إجراء أي تغييرات - تستخدم واجهة برمجة تطبيقات KnowledgeGraph الحالية.
+تستفيد تلقائيًا من تحسينات الأداء.
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+لا يلزم إجراء أي تغييرات - تستخدم واجهة برمجة تطبيقات KnowledgeGraph الحالية.
+تستفيد تلقائيًا من تحسينات الأداء.
+
+### ملفات الاختبار التي تتطلب تحديثات
+
+#### اختبارات الوحدة
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+تحديث توقعات الاختبار للتغييرات في المخطط.
+إضافة اختبارات لضمان الاتساق بين الجداول المتعددة.
+التحقق من عدم وجود ALLOW FILTERING في خطط الاستعلام.
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+تحديث التأكيدات المتعلقة بالأداء.
+اختبار جميع أنماط الاستعلام الثمانية مقابل الجداول الجديدة.
+التحقق من توجيه الاستعلام إلى الجداول الصحيحة.
+
+#### اختبارات التكامل
+**`tests/integration/test_cassandra_integration.py`**
+اختبار شامل مع المخطط الجديد.
+مقارنات قياس الأداء.
+التحقق من اتساق البيانات عبر الجداول.
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+تحديث اختبارات التحقق من صحة المخطط.
+اختبار سيناريوهات الترحيل.
+
+### استراتيجية التنفيذ
+
+#### المرحلة الأولى: المخطط والطرق الأساسية
+1. **إعادة كتابة الطريقة `init()`** - إنشاء أربعة جداول بدلاً من جدول واحد.
+2. **إعادة كتابة الطريقة `insert()`** - عمليات كتابة مجمعة إلى جميع الجداول الأربعة.
+3. **تنفيذ عبارات مُعدة** - للحصول على أداء مثالي.
+4. **إضافة منطق توجيه الجدول** - لتوجيه الاستعلامات إلى الجداول المثلى.
+5. **تنفيذ حذف المجموعة** - القراءة من triples_collection، وحذف مجمع من جميع الجداول.
+
+#### المرحلة الثانية: تحسين طريقة الاستعلام
+1. **إعادة كتابة كل طريقة get_*** لاستخدام الجدول الأمثل.
+2. **إزالة جميع استخدامات ALLOW FILTERING**.
+3. **تنفيذ استخدام فعال لمفتاح التجميع**.
+4. **إضافة تسجيل أداء الاستعلام**.
+
+#### المرحلة الثالثة: إدارة المجموعة
+1. **تحديث `delete_collection()`** - إزالتها من جميع الجداول الثلاثة.
+2. **إضافة التحقق من الاتساق** - لضمان بقاء جميع الجداول متزامنة.
+3. **تنفيذ عمليات مجمعة** - لعمليات متعددة الجداول ذرية.
+
+### تفاصيل التنفيذ الرئيسية
+
+#### استراتيجية الكتابة المجمعة
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### منطق توجيه الاستعلامات
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### منطق حذف المجموعة
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+### تحسين عبارات SQL المُعدة (Prepared Statements)
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## استراتيجية الترحيل
+
+### نهج ترحيل البيانات
+
+#### الخيار الأول: النشر الأزرق-الأخضر (موصى به)
+1. **نشر المخطط الجديد جنبًا إلى جنب مع المخطط الحالي** - استخدم أسماء جداول مختلفة مؤقتًا.
+2. **فترة الكتابة المزدوجة** - الكتابة إلى كل من المخططين القديم والجديد خلال فترة الانتقال.
+3. **ترحيل البيانات في الخلفية** - نسخ البيانات الموجودة إلى الجداول الجديدة.
+4. **توجيه عمليات القراءة** - توجيه الاستعلامات إلى الجداول الجديدة بمجرد ترحيل البيانات.
+5. **إزالة الجداول القديمة** - بعد فترة التحقق.
+
+#### الخيار الثاني: الترحيل في المكان
+1. **إضافة المخطط** - إنشاء جداول جديدة في مساحة المفاتيح الحالية.
+2. **برنامج ترحيل البيانات** - نسخ دفعي من الجدول القديم إلى الجداول الجديدة.
+3. **تحديث التطبيق** - نشر التعليمات البرمجية الجديدة بعد اكتمال الترحيل.
+4. **تنظيف الجدول القديم** - إزالة الجدول القديم والفهارس.
+
+### التوافق مع الإصدارات السابقة
+
+#### استراتيجية النشر
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### نص ترحيل
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### استراتيجية التحقق من الصحة
+
+#### فحوصات تناسق البيانات
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## استراتيجية الاختبار
+
+### اختبار الأداء
+
+#### سيناريوهات قياس الأداء
+1. **مقارنة أداء الاستعلامات**
+   مقاييس الأداء قبل وبعد لجميع أنواع الاستعلامات الثمانية.
+   التركيز على تحسين أداء `get_po` (إزالة `ALLOW FILTERING`).
+   قياس زمن استجابة الاستعلامات تحت أحجام بيانات مختلفة.
+
+2. **اختبار التحميل**
+   تنفيذ استعلامات متزامنة.
+   معدل نقل البيانات مع العمليات الدفعية.
+   استخدام الذاكرة ووحدة المعالجة المركزية.
+
+3. **اختبار قابلية التوسع**
+   الأداء مع زيادة أحجام المجموعات.
+   توزيع الاستعلامات عبر مجموعات متعددة.
+   استخدام عقد المجموعة.
+
+#### مجموعات بيانات الاختبار
+**صغيرة:** 10 آلاف ثلاثية لكل مجموعة.
+**متوسطة:** 100 ألف ثلاثية لكل مجموعة.
+**كبيرة:** أكثر من مليون ثلاثية لكل مجموعة.
+**مجموعات متعددة:** اختبار توزيع التقسيم.
+
+### اختبار وظيفي
+
+#### تحديثات اختبار الوحدات
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### تحديثات اختبار التكامل
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### خطة التراجع
+
+#### استراتيجية تراجع سريعة
+1. **تبديل متغيرات البيئة** - العودة إلى الجداول القديمة على الفور.
+2. **الاحتفاظ بالجداول القديمة** - لا تقم بإزالتها حتى يتم إثبات الأداء.
+3. **تنبيهات المراقبة** - تشغيل تلقائي للتراجع بناءً على معدلات الخطأ/زمن الاستجابة.
+
+#### التحقق من التراجع
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## المخاطر والاعتبارات
+
+### مخاطر الأداء
+**زيادة زمن الاستجابة للكتابة** - 4 عمليات كتابة لكل عملية إدخال (أكثر بنسبة 33٪ من مقاربة الجدول الثلاثي)
+**العبء التخزيني** - 4 أضعاف متطلبات التخزين (أكثر بنسبة 33٪ من مقاربة الجدول الثلاثي)
+**فشل عمليات الكتابة المجمعة** - الحاجة إلى معالجة الأخطاء بشكل صحيح
+**تعقيد الحذف** - يتطلب حذف المجموعة حلقة قراءة ثم حذف
+
+### المخاطر التشغيلية
+**تعقيد الترحيل** - ترحيل البيانات لمجموعات البيانات الكبيرة
+**تحديات الاتساق** - ضمان بقاء جميع الجداول متزامنة
+**فجوات المراقبة** - الحاجة إلى مقاييس جديدة لعمليات الجداول المتعددة
+
+### استراتيجيات التخفيف
+1. **النشر التدريجي** - ابدأ بمجموعات صغيرة
+2. **مراقبة شاملة** - تتبع جميع مقاييس الأداء
+3. **التحقق الآلي** - فحص الاتساق المستمر
+4. **إمكانية التراجع السريع** - اختيار الجدول بناءً على البيئة
+
+## معايير النجاح
+
+### تحسينات الأداء
+[ ] **إزالة ALLOW FILTERING** - تعمل الاستعلامات get_po و get_os بدون تصفية
+[ ] **تقليل زمن استجابة الاستعلام** - تحسن بنسبة 50٪ أو أكثر في أوقات استجابة الاستعلام
+[ ] **توزيع أفضل للعبء** - لا توجد أقسام "ساخنة"، وتوزيع متساوٍ عبر عقد المجموعة
+[ ] **أداء قابل للتوسع** - وقت الاستعلام يتناسب مع حجم النتيجة، وليس إجمالي البيانات
+
+### المتطلبات الوظيفية
+[ ] **توافق واجهة برمجة التطبيقات (API)** - يستمر جميع التعليمات البرمجية الحالية في العمل دون تغيير
+[ ] **اتساق البيانات** - تظل جميع الجداول الثلاثة متزامنة
+[ ] **عدم فقدان البيانات** - يحافظ الترحيل على جميع الثلاثيات الموجودة
+[ ] **التوافق مع الإصدارات السابقة** - القدرة على العودة إلى المخطط القديم
+
+### المتطلبات التشغيلية
+[ ] **ترحيل آمن** - نشر أخضر/أزرق مع إمكانية التراجع
+[ ] **تغطية المراقبة** - مقاييس شاملة لعمليات الجداول المتعددة
+[ ] **تغطية الاختبار** - تم اختبار جميع أنماط الاستعلام باستخدام معايير الأداء
+[ ] **التوثيق** - تحديث إجراءات النشر والتشغيل
+
+## الجدول الزمني
+
+### المرحلة 1: التنفيذ
+[ ] إعادة كتابة `cassandra_kg.py` باستخدام مخطط الجداول المتعددة
+[ ] تنفيذ عمليات الكتابة المجمعة
+[ ] إضافة تحسينات باستخدام عبارات مُعدة
+[ ] تحديث اختبارات الوحدة
+
+### المرحلة 2: اختبار التكامل
+[ ] تحديث اختبارات التكامل
+[ ] قياس الأداء
+[ ] اختبار التحميل باستخدام أحجام بيانات واقعية
+[ ] نصوص التحقق من اتساق البيانات
+
+### المرحلة 3: تخطيط الترحيل
+[ ] نصوص النشر الأخضر/الأزرق
+[ ] أدوات ترحيل البيانات
+[ ] تحديثات لوحة معلومات المراقبة
+[ ] إجراءات التراجع
+
+### المرحلة 4: النشر في بيئة الإنتاج
+[ ] النشر التدريجي في بيئة الإنتاج
+[ ] مراقبة الأداء والتحقق من صحته
+[ ] تنظيف الجداول القديمة
+[ ] تحديثات التوثيق
+
+## الخلاصة
+
+تعالج هذه الاستراتيجية لإلغاء التسوية متعددة الجداول بشكل مباشر عنقودين رئيسيين للأداء:
+
+1. **تقضي على ALLOW FILTERING المكلفة** من خلال توفير هياكل جداول مثالية لكل نمط استعلام
+2. **تحسين فعالية التجميع** من خلال مفاتيح التقسيم المركبة التي توزع الحمل بشكل صحيح
+
+تستفيد هذه الطريقة من نقاط قوة Cassandra مع الحفاظ على توافق كامل مع واجهة برمجة التطبيقات (API)، مما يضمن أن التعليمات البرمجية الحالية تستفيد تلقائيًا من تحسينات الأداء.

docs/tech-specs/cassandra-performance-refactor.es.md

@@ -0,0 +1,679 @@
+# Especificación Técnica: Refactorización del Rendimiento de la Base de Conocimiento Cassandra
+
+**Estado:** Borrador
+**Autor:** Asistente
+**Fecha:** 2025-09-18
+
+## Resumen
+
+Esta especificación aborda los problemas de rendimiento en la implementación de la base de conocimiento TrustGraph Cassandra y propone optimizaciones para el almacenamiento y la consulta de triples RDF.
+
+## Implementación Actual
+
+### Diseño del Esquema
+
+La implementación actual utiliza un diseño de tabla única en `trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**Índices Secundarios:**
+`triples_s` EN `s` (sujeto)
+`triples_p` EN `p` (predicado)
+`triples_o` EN `o` (objeto)
+
+### Patrones de Consulta
+
+La implementación actual admite 8 patrones de consulta distintos:
+
+1. **get_all(colección, límite=50)** - Recupera todas las triples para una colección
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(colección, s, límite=10)** - Consulta por tema.
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(colección, p, límite=10)** - Consulta por predicado
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(colección, o, límite=10)** - Consulta por objeto
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(colección, s, p, limit=10)** - Consulta por sujeto + predicado
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - Consulta por predicado + objeto ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - Consulta por objeto + sujeto ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(colección, s, p, o, límite=10)** - Coincidencia exacta de tripleta.
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### Arquitectura Actual
+
+**Archivo: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+Clase única `KnowledgeGraph` que gestiona todas las operaciones
+Agrupación de conexiones a través de una lista global `_active_clusters`
+Nombre de tabla fijo: `"triples"`
+Espacio de claves por modelo de usuario
+Replicación SimpleStrategy con factor 1
+
+**Puntos de Integración:**
+**Ruta de Escritura:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**Ruta de Consulta:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**Almacén de Conocimiento:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## Problemas de Rendimiento Identificados
+
+### Problemas a Nivel de Esquema
+
+1. **Diseño de Clave Primaria Ineficiente**
+   Actual: `PRIMARY KEY (collection, s, p, o)`
+   Resulta en un agrupamiento deficiente para patrones de acceso comunes
+   Obliga al uso de índices secundarios costosos
+
+2. **Uso Excesivo de Índices Secundarios** ⚠️
+   Tres índices secundarios en columnas de alta cardinalidad (s, p, o)
+   Los índices secundarios en Cassandra son costosos y no escalan bien
+   Las consultas 6 y 7 requieren `ALLOW FILTERING`, lo que indica un modelado de datos deficiente
+
+3. **Riesgo de Particiones Calientes**
+   Una única clave de partición `collection` puede crear particiones calientes
+   Las colecciones grandes se concentrarán en nodos individuales
+   No hay estrategia de distribución para el equilibrio de carga
+
+### Problemas a Nivel de Consulta
+
+1. **Uso de ALLOW FILTERING** ⚠️
+   Dos tipos de consulta (get_po, get_os) requieren `ALLOW FILTERING`
+   Estas consultas escanean múltiples particiones y son extremadamente costosas
+   El rendimiento disminuye linealmente con el tamaño de los datos
+
+2. **Patrones de Acceso Ineficientes**
+   No hay optimización para patrones de consulta RDF comunes
+   Faltan índices compuestos para combinaciones de consulta frecuentes
+   No se tiene en cuenta los patrones de recorrido de grafos
+
+3. **Falta de Optimización de Consultas**
+   No hay almacenamiento en caché de sentencias preparadas
+   No hay sugerencias de consulta ni estrategias de optimización
+   No se tiene en cuenta la paginación más allá de un simple LIMIT
+
+## Declaración del Problema
+
+La implementación actual de la base de conocimiento de Cassandra tiene dos cuellos de botella críticos de rendimiento:
+
+### 1. Rendimiento Ineficiente de la Consulta get_po
+
+La consulta `get_po(collection, p, o)` es extremadamente ineficiente debido a que requiere `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**¿Por qué esto es problemático:**
+`ALLOW FILTERING` obliga a Cassandra a escanear todas las particiones dentro de la colección.
+El rendimiento disminuye linealmente con el tamaño de los datos.
+Este es un patrón de consulta RDF común (encontrar sujetos que tengan una relación específica de predicado-objeto).
+Crea una carga significativa en el clúster a medida que los datos crecen.
+
+### 2. Estrategia de Clustering Deficiente
+
+La clave primaria actual `PRIMARY KEY (collection, s, p, o)` proporciona beneficios de clustering mínimos:
+
+**Problemas con el clustering actual:**
+`collection` como clave de partición no distribuye los datos de manera efectiva.
+La mayoría de las colecciones contienen datos diversos, lo que hace que el clustering sea ineficaz.
+No se tiene en cuenta los patrones de acceso comunes en las consultas RDF.
+Las colecciones grandes crean particiones "calientes" en nodos individuales.
+Las columnas de clustering (s, p, o) no optimizan para los patrones típicos de recorrido de grafos.
+
+**Impacto:**
+Las consultas no se benefician de la localidad de los datos.
+Utilización deficiente de la caché.
+Distribución desigual de la carga en los nodos del clúster.
+Cuellos de botella de escalabilidad a medida que las colecciones crecen.
+
+## Solución Propuesta: Estrategia de Desnormalización de 4 Tablas
+
+### Resumen
+
+Reemplace la única tabla `triples` con cuatro tablas diseñadas específicamente, cada una optimizada para patrones de consulta específicos. Esto elimina la necesidad de índices secundarios y ALLOW FILTERING, al tiempo que proporciona un rendimiento óptimo para todos los tipos de consulta. La cuarta tabla permite una eliminación eficiente de colecciones a pesar de las claves de partición compuestas.
+
+### Nuevo Diseño de Esquema
+
+**Tabla 1: Consultas Centradas en el Sujeto (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**Optimiza:** get_s, get_sp, get_os
+**Clave de partición:** (colección, s) - Mejor distribución que solo la colección.
+**Agrupamiento:** (p, o) - Permite búsquedas eficientes de predicados/objetos para un sujeto.
+
+**Tabla 2: Consultas Predicado-Objeto (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**Optimiza:** get_p, get_po (¡elimina ALLOW FILTERING!)
+**Clave de partición:** (colección, p) - Acceso directo mediante predicado
+**Agrupamiento:** (o, s) - Recorrido eficiente de objeto a sujeto
+
+**Tabla 3: Consultas centradas en objetos (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**Optimiza:** get_o
+**Clave de partición:** (colección, o) - Acceso directo por objeto
+**Clustering:** (s, p) - Recorrido eficiente de sujeto-predicado
+
+**Tabla 4: Gestión de colecciones y consultas SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**Optimiza:** get_spo, delete_collection
+**Clave de partición:** solo colección - Permite operaciones eficientes a nivel de colección.
+**Clustering:** (s, p, o) - Orden estándar de tripletas.
+**Propósito:** Uso dual para búsquedas exactas de SPO y como índice de eliminación.
+
+### Mapeo de consultas
+
+| Consulta original | Tabla de destino | Mejora de rendimiento |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | PERMITE FILTRADO (aceptable para escaneo) |
+| get_s(collection, s) | triples_s | Acceso directo a la partición |
+| get_p(collection, p) | triples_p | Acceso directo a la partición |
+| get_o(collection, o) | triples_o | Acceso directo a la partición |
+| get_sp(collection, s, p) | triples_s | Partición + clustering |
+| get_po(collection, p, o) | triples_p | **¡Ya no se permite ALLOW FILTERING!** |
+| get_os(collection, o, s) | triples_o | Partición + clustering |
+| get_spo(collection, s, p, o) | triples_collection | Búsqueda exacta de clave |
+| delete_collection(collection) | triples_collection | Lee el índice, eliminación por lotes de todos |
+
+### Estrategia de eliminación de colecciones
+
+Con claves de partición compuestas, no podemos simplemente ejecutar `DELETE FROM table WHERE collection = ?`. En cambio:
+
+1. **Fase de lectura:** Consulta `triples_collection` para enumerar todas las tripletas:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   Esto es eficiente ya que `collection` es la clave de partición para esta tabla.
+
+2. **Fase de eliminación:** Para cada triple (s, p, o), elimine de las 4 tablas utilizando claves de partición completas:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   Agrupado en lotes de 100 para mayor eficiencia.
+
+**Análisis de compensaciones:**
+✅ Mantiene un rendimiento óptimo de las consultas con particiones distribuidas.
+✅ No hay particiones con alta carga para colecciones grandes.
+❌ Lógica de eliminación más compleja (leer y luego eliminar).
+❌ Tiempo de eliminación proporcional al tamaño de la colección.
+
+### Beneficios
+
+1. **Elimina ALLOW FILTERING** - Cada consulta tiene una ruta de acceso óptima (excepto el escaneo get_all).
+2. **No se requieren índices secundarios** - Cada tabla ES el índice para su patrón de consulta.
+3. **Mejor distribución de datos** - Las claves de partición compuestas distribuyen la carga de manera efectiva.
+4. **Rendimiento predecible** - El tiempo de consulta es proporcional al tamaño del resultado, no a los datos totales.
+5. **Aprovecha las fortalezas de Cassandra** - Diseñado para la arquitectura de Cassandra.
+6. **Permite la eliminación de colecciones** - triples_collection sirve como índice de eliminación.
+
+## Plan de implementación
+
+### Archivos que requieren cambios
+
+#### Archivo de implementación principal
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Se requiere una reescritura completa.
+
+**Métodos actuales a refactorizar:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### Archivos de Integración (No se requieren cambios en la lógica)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+No se necesitan cambios: utiliza la API KnowledgeGraph existente.
+Se beneficia automáticamente de las mejoras de rendimiento.
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+No se necesitan cambios: utiliza la API KnowledgeGraph existente.
+Se beneficia automáticamente de las mejoras de rendimiento.
+
+### Archivos de Prueba que Requieren Actualizaciones
+
+#### Pruebas Unitarias
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+Actualizar las expectativas de las pruebas para los cambios en el esquema.
+Agregar pruebas para la consistencia de múltiples tablas.
+Verificar que no haya "ALLOW FILTERING" en los planes de consulta.
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+Actualizar las aserciones de rendimiento.
+Probar los 8 patrones de consulta contra las nuevas tablas.
+Verificar el enrutamiento de consultas a las tablas correctas.
+
+#### Pruebas de Integración
+**`tests/integration/test_cassandra_integration.py`**
+Pruebas de extremo a extremo con el nuevo esquema.
+Comparaciones de referencia de rendimiento.
+Verificación de la consistencia de los datos en todas las tablas.
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+Actualizar las pruebas de validación de esquema.
+Probar escenarios de migración.
+
+### Estrategia de Implementación
+
+#### Fase 1: Esquema y Métodos Centrales
+1. **Reescribir el método `init()`** - Crear cuatro tablas en lugar de una.
+2. **Reescribir el método `insert()`** - Escrituras por lotes a las cuatro tablas.
+3. **Implementar sentencias preparadas** - Para un rendimiento óptimo.
+4. **Agregar lógica de enrutamiento de tablas** - Dirigir las consultas a las tablas óptimas.
+5. **Implementar la eliminación de colecciones** - Leer de triples_collection, eliminar por lotes de todas las tablas.
+
+#### Fase 2: Optimización de Métodos de Consulta
+1. **Reescribir cada método get_*** para usar la tabla óptima.
+2. **Eliminar todo el uso de ALLOW FILTERING**.
+3. **Implementar el uso eficiente de la clave de clustering**.
+4. **Agregar registro del rendimiento de las consultas**.
+
+#### Fase 3: Gestión de Colecciones
+1. **Actualizar `delete_collection()`** - Eliminar de las tres tablas.
+2. **Agregar verificación de consistencia** - Asegurar que todas las tablas se mantengan sincronizadas.
+3. **Implementar operaciones por lotes** - Para operaciones multi-tabla atómicas.
+
+### Detalles Clave de la Implementación
+
+#### Estrategia de Escritura por Lotes
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### Lógica de enrutamiento de consultas
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### Lógica de eliminación de colecciones
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### Optimización de sentencias preparadas
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## Estrategia de Migración
+
+### Enfoque de Migración de Datos
+
+#### Opción 1: Despliegue Blue-Green (Recomendado)
+1. **Implementar el nuevo esquema junto con el existente** - Utilizar nombres de tabla diferentes temporalmente
+2. **Período de escritura dual** - Escribir tanto en el esquema antiguo como en el nuevo durante la transición
+3. **Migración en segundo plano** - Copiar los datos existentes a las nuevas tablas
+4. **Cambiar las lecturas** - Dirigir las consultas a las nuevas tablas una vez que los datos se hayan migrado
+5. **Eliminar las tablas antiguas** - Después del período de verificación
+
+#### Opción 2: Migración In-Place
+1. **Adición de esquema** - Crear nuevas tablas en el keyspace existente
+2. **Script de migración de datos** - Copia por lotes de la tabla antigua a las nuevas tablas
+3. **Actualización de la aplicación** - Implementar el nuevo código después de que se complete la migración
+4. **Limpieza de la tabla antigua** - Eliminar la tabla antigua e índices
+
+### Compatibilidad hacia atrás
+
+#### Estrategia de Despliegue
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### Script de Migración
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### Estrategia de Validación
+
+#### Comprobaciones de Consistencia de Datos
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## Estrategia de Pruebas
+
+### Pruebas de Rendimiento
+
+#### Escenarios de Referencia
+1. **Comparación del Rendimiento de Consultas**
+   Métricas de rendimiento antes y después para los 8 tipos de consultas
+   Centrarse en la mejora del rendimiento de get_po (eliminar ALLOW FILTERING)
+   Medir la latencia de las consultas bajo varios tamaños de datos
+
+2. **Pruebas de Carga**
+   Ejecución concurrente de consultas
+   Rendimiento de escritura con operaciones por lotes
+   Utilización de memoria y CPU
+
+3. **Pruebas de Escalabilidad**
+   Rendimiento con tamaños de colección crecientes
+   Distribución de consultas de múltiples colecciones
+   Utilización de nodos del clúster
+
+#### Conjuntos de Datos de Prueba
+**Pequeño:** 10K triples por colección
+**Mediano:** 100K triples por colección
+**Grande:** 1M+ triples por colección
+**Múltiples colecciones:** Probar la distribución de particiones
+
+### Pruebas Funcionales
+
+#### Actualizaciones de Pruebas Unitarias
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### Actualizaciones de la prueba de integración
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### Plan de Reversión
+
+#### Estrategia de Reversión Rápida
+1. **Alternancia de variables de entorno** - Vuelva a las tablas heredadas inmediatamente.
+2. **Mantenga las tablas heredadas** - No las elimine hasta que se demuestre el rendimiento.
+3. **Alertas de monitoreo** - Desencadenadores de reversión automatizados basados en tasas de error/latencia.
+
+#### Validación de la Reversión
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## Riesgos y Consideraciones
+
+### Riesgos de Rendimiento
+**Aumento de la latencia de escritura** - 4 operaciones de escritura por inserción (un 33% más que el enfoque de 3 tablas)
+**Sobrecarga de almacenamiento** - 4 veces más espacio de almacenamiento requerido (un 33% más que el enfoque de 3 tablas)
+**Fallos en la escritura por lotes** - Se necesita un manejo adecuado de errores
+**Complejidad de la eliminación** - La eliminación de la colección requiere un bucle de lectura y eliminación
+
+### Riesgos Operacionales
+**Complejidad de la migración** - Migración de datos para conjuntos de datos grandes
+**Desafíos de consistencia** - Asegurar que todas las tablas permanezcan sincronizadas
+**Lagunas de monitoreo** - Se necesitan nuevas métricas para las operaciones de múltiples tablas
+
+### Estrategias de Mitigación
+1. **Implementación gradual** - Comenzar con colecciones pequeñas
+2. **Monitoreo integral** - Realizar un seguimiento de todas las métricas de rendimiento
+3. **Validación automatizada** - Verificación continua de la consistencia
+4. **Capacidad de reversión rápida** - Selección de tablas basada en el entorno
+
+## Criterios de Éxito
+
+### Mejoras de Rendimiento
+[ ] **Eliminar ALLOW FILTERING** - Las consultas get_po y get_os se ejecutan sin filtrado
+[ ] **Reducción de la latencia de la consulta** - Mejora del 50% o más en los tiempos de respuesta de las consultas
+[ ] **Mejor distribución de la carga** - Sin particiones "calientes", distribución uniforme de la carga en los nodos del clúster
+[ ] **Rendimiento escalable** - El tiempo de consulta es proporcional al tamaño del resultado, no a la cantidad total de datos
+
+### Requisitos Funcionales
+[ ] **Compatibilidad de la API** - Todo el código existente continúa funcionando sin cambios
+[ ] **Consistencia de datos** - Las tres tablas permanecen sincronizadas
+[ ] **Cero pérdida de datos** - La migración preserva todas las triples existentes
+[ ] **Compatibilidad con versiones anteriores** - Capacidad de volver al esquema heredado
+
+### Requisitos Operacionales
+[ ] **Migración segura** - Implementación blue-green con capacidad de reversión
+[ ] **Cobertura de monitoreo** - Métricas integrales para operaciones de múltiples tablas
+[ ] **Cobertura de pruebas** - Todos los patrones de consulta se prueban con puntos de referencia de rendimiento
+[ ] **Documentación** - Procedimientos de implementación y operación actualizados
+
+## Cronograma
+
+### Fase 1: Implementación
+[ ] Reescribir `cassandra_kg.py` con el esquema de múltiples tablas
+[ ] Implementar operaciones de escritura por lotes
+[ ] Agregar optimización de sentencias preparadas
+[ ] Actualizar pruebas unitarias
+
+### Fase 2: Pruebas de Integración
+[ ] Actualizar pruebas de integración
+[ ] Pruebas de rendimiento
+[ ] Pruebas de carga con volúmenes de datos realistas
+[ ] Scripts de validación para la consistencia de los datos
+
+### Fase 3: Planificación de la Migración
+[ ] Scripts de implementación blue-green
+[ ] Herramientas de migración de datos
+[ ] Actualizaciones del panel de monitoreo
+[ ] Procedimientos de reversión
+
+### Fase 4: Despliegue en Producción
+[ ] Implementación gradual en producción
+[ ] Monitoreo y validación del rendimiento
+[ ] Limpieza de tablas heredadas
+[ ] Actualizaciones de la documentación
+
+## Conclusión
+
+Esta estrategia de desnormalización de múltiples tablas aborda directamente los dos cuellos de botella de rendimiento críticos:
+
+1. **Elimina el costoso ALLOW FILTERING** al proporcionar estructuras de tabla óptimas para cada patrón de consulta
+2. **Mejora la eficacia de la agrupación** a través de claves de partición compuestas que distribuyen la carga de manera adecuada
+
+El enfoque aprovecha las fortalezas de Cassandra al tiempo que mantiene la compatibilidad total de la API, lo que garantiza que el código existente se beneficie automáticamente de las mejoras de rendimiento.

docs/tech-specs/cassandra-performance-refactor.he.md

@@ -0,0 +1,679 @@
+# מפרט טכני: שיפור ביצועים של בסיס הידע Cassandra
+
+**סטטוס:** טיוטה
+**כותב:** עוזר
+**תאריך:** 2025-09-18
+
+## סקירה כללית
+
+מפרט זה עוסק בבעיות ביצועים ביישום בסיס הידע Cassandra של TrustGraph ומציע אופטימיזציות לאחסון ושליפה של משולשות RDF.
+
+## יישום נוכחי
+
+### עיצוב הסכימה
+
+היישום הנוכחי משתמש בעיצוב טבלה יחידה ב-`trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**אינדקסים משניים:**
+`triples_s` על `s` (נושא)
+`triples_p` על `p` (נשוא)
+`triples_o` על `o` (אובייקט)
+
+### תבניות שאילתה
+
+המימוש הנוכחי תומך ב-8 תבניות שאילתה מובחנות:
+
+1. **get_all(collection, limit=50)** - שליפה של כל השלשות עבור אוסף
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - שאילתה לפי נושא.
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - שאילתה לפי תנאי.
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - שאילתה לפי אובייקט.
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - שאילתה לפי נושא + טענה
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - שאילתה לפי תנאי + אובייקט ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - שאילתה לפי אובייקט + נושא ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - התאמה מדויקת לשלושה חלקים (subject, predicate, object).
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### ארכיטקטורה נוכחית
+
+**קובץ: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+מחלקה יחידה `KnowledgeGraph` המטפלת בכל הפעולות
+בריכת חיבורים באמצעות רשימה גלובלית `_active_clusters`
+שם טבלה קבוע: `"triples"`
+מרחב מפתחות לכל מודל משתמש
+שכפול SimpleStrategy עם גורם 1
+
+**נקודות אינטגרציה:**
+**נתיב כתיבה:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**נתיב שאילתה:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**מאגר ידע:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## בעיות ביצועים שזוהו
+
+### בעיות ברמת הסכימה
+
+1. **עיצוב מפתח ראשי לא יעיל**
+   נוכחי: `PRIMARY KEY (collection, s, p, o)`
+   גורם לקיבוץ לקוי עבור דפוסי גישה נפוצים
+   מחייב שימוש באינדקסים משניים יקרים
+
+2. **שימוש יתר באינדקסים משניים** ⚠️
+   שלושה אינדקסים משניים על עמודות עם קרדינליות גבוהה (s, p, o)
+   אינדקסים משניים ב-Cassandra הם יקרים ואינם מתאימים להרחבה
+   שאילתות 6 ו-7 דורשות `ALLOW FILTERING` המצביע על מודל נתונים לקוי
+
+3. **סיכון לחלוקות חמות**
+   מפתח חלוקה יחיד `collection` יכול ליצור חלוקות חמות
+   אוספים גדולים יתרכזו בצמתים בודדים
+   אין אסטרטגיית חלוקה לאיזון עומסים
+
+### בעיות ברמת השאילתה
+
+1. **שימוש ב-ALLOW FILTERING** ⚠️
+   שני סוגי שאילתות (get_po, get_os) דורשים `ALLOW FILTERING`
+   שאילתות אלו סורקות מספר חלוקות ויקרות מאוד
+   הביצועים יורדים באופן ליניארי עם גודל הנתונים
+
+2. **דפוסי גישה לא יעילים**
+   אין אופטימיזציה עבור דפוסי שאילתות RDF נפוצים
+   חסרים אינדקסים מורכבים עבור שילובים תכופים של שאילתות
+   אין התחשבות בדפוסי מעבר גרפים
+
+3. **חוסר באופטימיזציה של שאילתות**
+   אין שמירת מטמון של הצהרות מוכנות
+   אין רמזים או אסטרטגיות אופטימיזציה לשאילתות
+   אין התחשבות בדף אחרי דף מעבר לפונקציית LIMIT פשוטה
+
+## הצהרת בעיה
+
+ליישום בסיס הידע הנוכחי של Cassandra ישנם שני צווארי בקבוק ביצועים קריטיים:
+
+### 1. ביצועים לא יעילים של שאילתת get_po
+
+השאילתה `get_po(collection, p, o)` אינה יעילה מאוד מכיוון שהיא דורשת `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**מדוע זה בעייתי:**
+`ALLOW FILTERING` גורם לקסנדרה לסרוק את כל המחיצות בתוך האוסף.
+הביצועים יורדים באופן ליניארי עם גודל הנתונים.
+זהו דפוס שאילתות RDF נפוץ (מציאת נושאים שיש להם קשר ספציפי של נשוא-פועל-מושא).
+זה יוצר עומס משמעותי על האשכול ככל שהנתונים גדלים.
+
+### 2. אסטרטגיית קיבוץ לקויה
+
+המפתח הראשי הנוכחי `PRIMARY KEY (collection, s, p, o)` מספק יתרונות קיבוץ מינימליים:
+
+**בעיות עם הקיבוץ הנוכחי:**
+`collection` כמפתח מחיצה לא מפזר את הנתונים בצורה יעילה.
+רוב האוספים מכילים נתונים מגוונים, מה שהופך את הקיבוץ ללא יעיל.
+אין התחשבות בדפוסי גישה נפוצים בשאילתות RDF.
+אוספים גדולים יוצרים מחיצות "חמות" על צמתים בודדים.
+עמודות הקיבוץ (s, p, o) אינן מייעלות עבור דפוסי מעבר גרפים טיפוסיים.
+
+**השפעה:**
+שאילתות אינן נהנות ממיקום נתונים.
+ניצולת מטמון לקויה.
+חלוקת עומסים לא אחידה בין צמתי האשכול.
+צווארי בקבוק של יכולת הרחבה ככל שהאוספים גדלים.
+
+## פתרון מוצע: אסטרטגיית דה-נורמליזציה של 4 טבלאות
+
+### סקירה כללית
+
+החליפו את הטבלה הבודדת `triples` בארבע טבלאות ייעודיות, כל אחת מותאמת לדפוסי שאילתות ספציפיים. זה מבטל את הצורך באינדקסים משניים וב-ALLOW FILTERING תוך מתן ביצועים אופטימליים לכל סוגי השאילתות. הטבלה הרביעית מאפשרת מחיקת אוספים יעילה למרות מפתחות מחיצה מורכבים.
+
+### עיצוב סכימה חדש
+
+**טבלה 1: שאילתות ממוקדות בנושא (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**משפר:** get_s, get_sp, get_os
+**מפתח מחיצה:** (collection, s) - פיזור טוב יותר מאשר רק collection
+**קיבוץ:** (p, o) - מאפשר חיפושים יעילים של טווחים/אובייקטים עבור נושא
+
+**טבלה 2: שאילתות של טריפלטים (predicate-object) (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**משפר:** get_p, get_po (מבטל את ALLOW FILTERING!)
+**מפתח מחיצה:** (collection, p) - גישה ישירה באמצעות תנאי
+**קיבוץ:** (o, s) - מעבר יעיל בין אובייקט לנושא
+
+**טבלה 3: שאילתות ממוקדות אובייקט (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**אופטימיזציה:** get_o
+**מפתח מחיצה:** (collection, o) - גישה ישירה באמצעות אובייקט
+**קיבוץ:** (s, p) - מעבר יעיל בין נושא ופועל
+
+**טבלה 4: ניהול אוספים ושאילתות SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**אופטימיזציה:** get_spo, delete_collection
+**מפתח מחיצה:** רק אוסף - מאפשר פעולות יעילות ברמת האוסף.
+**קיבוץ:** (s, p, o) - סדר משולש סטנדרטי.
+**מטרה:** שימוש כפול לחיפושים מדויקים של SPO וגם כמדד למחיקה.
+
+### מיפוי שאילתות
+
+| שאילתה מקורית | טבלה יעד | שיפור ביצועים |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | ALLOW FILTERING (מתאים לסריקה) |
+| get_s(collection, s) | triples_s | גישה ישירה למחיצה |
+| get_p(collection, p) | triples_p | גישה ישירה למחיצה |
+| get_o(collection, o) | triples_o | גישה ישירה למחיצה |
+| get_sp(collection, s, p) | triples_s | מחיצה + קיבוץ |
+| get_po(collection, p, o) | triples_p | **אין יותר ALLOW FILTERING!** |
+| get_os(collection, o, s) | triples_o | מחיצה + קיבוץ |
+| get_spo(collection, s, p, o) | triples_collection | חיפוש מפתח מדויק |
+| delete_collection(collection) | triples_collection | קריאת מדד, מחיקה אצווה של הכל |
+
+### אסטרטגיית מחיקת אוסף
+
+עם מפתחות מחיצה מורכבים, אי אפשר פשוט לבצע `DELETE FROM table WHERE collection = ?`. במקום זאת:
+
+1. **שלב קריאה:** שאילתא `triples_collection` כדי לרשום את כל המשולשים:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   זה יעיל מכיוון ש-`collection` הוא מפתח החלוקה עבור הטבלה הזו.
+
+2. **שלב המחיקה:** עבור כל שלישייה (s, p, o), מחקו מכל 4 הטבלאות תוך שימוש במפתחות חלוקה מלאים:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   מחולק לקבוצות של 100 רשומות לטובת יעילות.
+
+**ניתוח פשרות:**
+✅ שומר על ביצועי שאילתות אופטימליים עם מחיצות מבוזרות.
+✅ אין מחיצות עמוסות עבור אוספים גדולים.
+❌ לוגיקת מחיקה מורכבת יותר (קריאה ואז מחיקה).
+❌ זמן מחיקה תלוי בגודל האוסף.
+
+### יתרונות
+
+1. **מבטל את ALLOW FILTERING** - לכל שאילתה יש נתיב גישה אופטימלי (מלבד סריקת get_all).
+2. **ללא אינדקסים משניים** - כל טבלה היא האינדקס לדפוס השאילתה שלה.
+3. **הפצת נתונים טובה יותר** - מפתחות מחיצה מורכבים מפזרים את העומס בצורה יעילה.
+4. **ביצועים צפויים** - זמן שאילתה תלוי בגודל התוצאה, ולא בגודל הנתונים הכולל.
+5. **מנצל את החוזקות של Cassandra** - תוכנן עבור ארכיטקטורת Cassandra.
+6. **מאפשר מחיקת אוספים** - triples_collection משמש כמחירון מחיקה.
+
+## תוכנית יישום
+
+### קבצים הדורשים שינוי
+
+#### קובץ יישום ראשי
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - נדרש כתיבה מחדש מלאה.
+
+**שיטות שיש לשכתב:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### קבצי אינטגרציה (אין צורך בשינויים לוגיים)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+אין צורך בשינויים - משתמשים ב-API של KnowledgeGraph הקיים
+נהנים אוטומטית משיפורי ביצועים
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+אין צורך בשינויים - משתמשים ב-API של KnowledgeGraph הקיים
+נהנים אוטומטית משיפורי ביצועים
+
+### קבצי בדיקה הדורשים עדכונים
+
+#### בדיקות יחידה
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+עדכון ציפיות הבדיקה עבור שינויים בסכימה
+הוספת בדיקות עבור עקביות בין טבלאות מרובות
+אימות היעדר ALLOW FILTERING בתוכניות שאילתות
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+עדכון טענות ביצועים
+בדיקת כל 8 דפוסי השאילתות מול טבלאות חדשות
+אימות ניתוב השאילתות לטבלאות הנכונות
+
+#### בדיקות אינטגרציה
+**`tests/integration/test_cassandra_integration.py`**
+בדיקות מקצה לקצה עם סכימה חדשה
+השוואות ביצועים
+אימות עקביות נתונים בין טבלאות
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+עדכון בדיקות אימות סכימה
+בדיקת תרחישי מעבר
+
+### אסטרטגיית יישום
+
+#### שלב 1: סכימה ושיטות ליבה
+1. **כתיבת מחדש של `init()`** - יצירת ארבע טבלאות במקום אחת
+2. **כתיבת מחדש של `insert()`** - כתיבה באצווה לכל ארבע הטבלאות
+3. **יישום הצהרות מוכנות** - לביצועים אופטימליים
+4. **הוספת לוגיקת ניתוב טבלאות** - הפניית שאילתות לטבלאות האופטימליות
+5. **יישום מחיקת אוספים** - קריאה מ-triples_collection, מחיקה באצווה מכל הטבלאות
+
+#### שלב 2: אופטימיזציה של שיטות שאילתה
+1. **כתיבת מחדש של כל שיטת get_*** לשימוש בטבלה האופטימלית
+2. **הסרת כל השימושים ב-ALLOW FILTERING**
+3. **יישום שימוש יעיל במפתח מיון**
+4. **הוספת רישום ביצועי שאילתות**
+
+#### שלב 3: ניהול אוספים
+1. **עדכון `delete_collection()`** - הסרה מכל שלושת הטבלאות
+2. **הוספת אימות עקביות** - הבטחת סנכרון בין כל הטבלאות
+3. **יישום פעולות באצווה** - לפעולות מרובות טבלאות אטומיות
+
+### פרטי יישום מרכזיים
+
+#### אסטרטגיית כתיבה באצווה
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### לוגיקת ניתוב שאילתות
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### לוגיקת מחיקת אוספים
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### אופטימיזציה של הצהרת הכנה (Prepared Statement)
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## אסטרטגיית מעבר
+
+### גישת מעבר נתונים
+
+#### אפשרות 1: פריסה בצבע כחול-ירוק (מומלץ)
+1. **פריסת הסכימה החדשה לצד הקיימת** - השתמש בשמות טבלאות שונים באופן זמני
+2. **תקופת כתיבה כפולה** - כתיבה גם לסכימה הישנה וגם לחדשה במהלך המעבר
+3. **מעבר נתונים ברקע** - העתקת נתונים קיימים לטבלאות חדשות
+4. **הפניית שאילתות** - הפניית שאילתות לטבלאות החדשות לאחר שהנתונים עברו
+5. **מחיקת הטבלאות הישנות** - לאחר תקופת אימות
+
+#### אפשרות 2: מעבר במקום
+1. **הוספת סכימה** - יצירת טבלאות חדשות במרחב מפתחות קיים
+2. **סקריפט מעבר נתונים** - העתקה באצווה מטבלה ישנה לטבלאות חדשות
+3. **עדכון יישום** - פריסת קוד חדש לאחר השלמת המעבר
+4. **ניקוי הטבלה הישנה** - הסרת הטבלה הישנה והאינדקסים
+
+### תאימות לאחור
+
+#### אסטרטגיית פריסה
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### סקריפט הגירה
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### אסטרטגיית אימות
+
+#### בדיקות עקביות נתונים
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## אסטרטגיית בדיקות
+
+### בדיקות ביצועים
+
+#### תרחישי ביצוע
+1. **השוואת ביצועי שאילתות**
+   מדדי ביצועים לפני ואחרי עבור כל 8 סוגי השאילתות
+   התמקדות בשיפור ביצועים של שאילתת get_po (הסרת ALLOW FILTERING)
+   מדידת השהייה של שאילתות בתנאי גדלי נתונים שונים
+
+2. **בדיקות עומסים**
+   ביצוע שאילתות במקביל
+   קצב כתיבה עם פעולות אצווה
+   ניצול זיכרון ו-CPU
+
+3. **בדיקות סקלאביליות**
+   ביצועים עם גדלי אוספים גדלים
+   חלוקת שאילתות בין אוספים מרובים
+   ניצול צמתים באשכול
+
+#### סטי נתוני בדיקה
+**קטן:** 10 אלף משולשים לאוסף
+**בינוני:** 100 אלף משולשים לאוסף
+**גדול:** 1 מיליון+ משולשים לאוסף
+**אוספים מרובים:** בדיקת חלוקת מחיצות
+
+### בדיקות פונקציונליות
+
+#### עדכוני בדיקות יחידה
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### עדכונים לבדיקות אינטגרציה
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### תוכנית חזרה אחורה
+
+#### אסטרטגיה מהירה לחזרה אחורה
+1. **החלפת משתנה סביבה** - חזרה מיידית לטבלאות הישנות.
+2. **שמירה על הטבלאות הישנות** - לא למחוק עד שיוכח שיפור בביצועים.
+3. **התראות ניטור** - הפעלת חזרה אוטומטית בהתבסס על שיעורי שגיאות/השהייה.
+
+#### אימות חזרה אחורה
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## סיכונים ושיקולים
+
+### סיכוני ביצועים
+**עלייה בלעדי כתיבה** - 4 פעולות כתיבה לכל הוספה (33% יותר מהגישה של 3 טבלאות)
+**תקורת אחסון** - דרישת אחסון של 4x (33% יותר מהגישה של 3 טבלאות)
+**כשלים בכתיבה אצווה** - יש צורך בטיפול תקין בשגיאות
+**מורכבות מחיקה** - מחיקת אוסף דורשת לולאה של קריאה ולאחר מכן מחיקה
+
+### סיכונים תפעוליים
+**מורכבות העברה** - העברת נתונים עבור מערכי נתונים גדולים
+**אתגרים של עקביות** - הבטחת סנכרון של כל הטבלאות
+**פערים בניטור** - יש צורך במדדים חדשים עבור פעולות מרובות טבלאות
+
+### אסטרטגיות הפחתת סיכונים
+1. **פריסה הדרגתית** - התחילו עם אוספים קטנים
+2. **ניטור מקיף** - מעקב אחר כל מדדי הביצועים
+3. **אימות אוטומטי** - בדיקת עקביות רציפה
+4. **יכולת ביטול מהירה** - בחירת טבלה מבוססת סביבה
+
+## קריטריוני הצלחה
+
+### שיפורי ביצועים
+[ ] **ביטול ALLOW FILTERING** - שאילתות get_po ו-get_os פועלות ללא סינון
+[ ] **הפחתת השהייה בשאילתות** - שיפור של 50%+ בזמני תגובה של שאילתות
+[ ] **חלוקת עומסים טובה יותר** - ללא מחיצות "חמות", חלוקת עומסים שווה על פני צמתים בקלאסטר
+[ ] **ביצועים ניתנים להרחבה** - זמן שאילתה תלוי בגודל התוצאה, ולא בנפח הנתונים הכולל
+
+### דרישות פונקציונליות
+[ ] **תאימות API** - כל הקוד הקיים ממשיך לעבוד ללא שינוי
+[ ] **עקביות נתונים** - שלוש הטבלאות נשארות מסונכרנות
+[ ] **אפס אובדן נתונים** - העברה שומרת על כל הטרפלים הקיימים
+[ ] **תאימות לאחור** - אפשרות לחזור לסקמה הישנה
+
+### דרישות תפעוליות
+[ ] **העברה בטוחה** - פריסה בצורה כחולה-ירוקה עם יכולת ביטול
+[ ] **כיסוי ניטור** - מדדים מקיפים עבור פעולות מרובות טבלאות
+[ ] **כיסוי בדיקות** - כל דפוסי השאילתות נבדקו עם מדדי ביצועים
+[ ] **תיעוד** - עדכון נהלי פריסה ותפעול
+
+## ציר זמן
+
+### שלב 1: יישום
+[ ] כתיבה מחדש של `cassandra_kg.py` עם סכימת טבלאות מרובות
+[ ] יישום פעולות כתיבה אצווה
+[ ] הוספת אופטימיזציה של הצהרות מוכנות
+[ ] עדכון בדיקות יחידה
+
+### שלב 2: בדיקות אינטגרציה
+[ ] עדכון בדיקות אינטגרציה
+[ ] מדידת ביצועים
+[ ] בדיקת עומסים עם נפחי נתונים ריאליים
+[ ] סקריפטים לאימות עקביות נתונים
+
+### שלב 3: תכנון העברה
+[ ] סקריפטים לפריסה בצורה כחולה-ירוקה
+[ ] כלים להעברת נתונים
+[ ] עדכוני לוח מחוונים לניטור
+[ ] נהלי ביטול
+
+### שלב 4: פריסה לייצור
+[ ] פריסה הדרגתית לסביבת ייצור
+[ ] ניטור ואימות ביצועים
+[ ] ניקוי טבלאות ישנות
+[ ] עדכוני תיעוד
+
+## מסקנה
+
+אסטרטגיית הדה-נורמליזציה מרובת טבלאות פותרת ישירות את שני צווארי הבקבוק הקריטיים בביצועים:
+
+1. **מבטלת את ALLOW FILTERING היקר** על ידי מתן מבני טבלאות אופטימליים עבור כל דפוס שאילתה
+2. **משפרת את יעילות הקיבוץ** באמצעות מפתחות מחיצה מורכבים שמפיצים את העומס כראוי
+
+הגישה ממנפת את החוזקות של Cassandra תוך שמירה על תאימות API מלאה, ומבטיחה שלקוד הקיים יש יתרונות אוטומטיים משיפורי הביצועים.

docs/tech-specs/cassandra-performance-refactor.hi.md

@@ -0,0 +1,679 @@
+# तकनीकी विनिर्देश: कैसेंड्रा नॉलेज बेस प्रदर्शन पुनर्निर्माण
+
+**स्थिति:** मसौदा
+**लेखक:** सहायक
+**तिथि:** 2025-09-18
+
+## अवलोकन
+
+यह विनिर्देश ट्रस्टग्राफ कैसेंड्रा नॉलेज बेस कार्यान्वयन में प्रदर्शन संबंधी मुद्दों को संबोधित करता है और आरडीएफ ट्रिपल भंडारण और क्वेरी के लिए अनुकूलन प्रस्तावित करता है।
+
+## वर्तमान कार्यान्वयन
+
+### स्कीमा डिज़ाइन
+
+वर्तमान कार्यान्वयन `trustgraph-flow/trustgraph/direct/cassandra_kg.py` में एक एकल तालिका डिज़ाइन का उपयोग करता है:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**माध्यमिक अनुक्रमणिकाएँ:**
+`triples_s` ON `s` (विषय)
+`triples_p` ON `p` (क्रिया)
+`triples_o` ON `o` (वस्तु)
+
+### क्वेरी पैटर्न
+
+वर्तमान कार्यान्वयन 8 अलग-अलग क्वेरी पैटर्न का समर्थन करता है:
+
+1. **get_all(संग्रह, सीमा=50)** - एक संग्रह के लिए सभी त्रिगुट प्राप्त करें
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(संग्रह, s, सीमा=10)** - विषय द्वारा खोज।
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(संग्रह, p, सीमा=10)** - विधेय द्वारा खोज
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(संग्रह, o, सीमा=10)** - ऑब्जेक्ट द्वारा क्वेरी करें।
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(संग्रह, s, p, सीमा=10)** - विषय + विधेय द्वारा खोज।
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - पूर्व निर्धारित शर्तों और वस्तुओं के आधार पर खोज ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(संग्रह, o, s, सीमा=10)** - ऑब्जेक्ट + विषय द्वारा क्वेरी ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(संग्रह, s, p, o, सीमा=10)** - सटीक त्रिगुट मिलान
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### वर्तमान आर्किटेक्चर
+
+**फ़ाइल: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+सभी कार्यों को संभालने वाली एकल `KnowledgeGraph` क्लास
+वैश्विक `_active_clusters` सूची के माध्यम से कनेक्शन पूलिंग
+निश्चित टेबल नाम: `"triples"`
+प्रति उपयोगकर्ता मॉडल के लिए कीस्पेस
+फैक्टर 1 के साथ सिंपलस्ट्रैटेजी प्रतिकृति
+
+**एकीकरण बिंदु:**
+**राइट पाथ:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**क्वेरी पाथ:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**नॉलेज स्टोर:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## पहचाने गए प्रदर्शन संबंधी मुद्दे
+
+### स्कीमा-स्तरीय मुद्दे
+
+1. **अकुशल प्राइमरी की डिज़ाइन**
+   वर्तमान: `PRIMARY KEY (collection, s, p, o)`
+   सामान्य एक्सेस पैटर्न के लिए खराब क्लस्टरिंग का कारण बनता है
+   महंगे सेकेंडरी इंडेक्स के उपयोग को मजबूर करता है
+
+2. **सेकेंडरी इंडेक्स का अत्यधिक उपयोग** ⚠️
+   उच्च कार्डिनलिटी कॉलम (s, p, o) पर तीन सेकेंडरी इंडेक्स
+   कैसेंड्रा में सेकेंडरी इंडेक्स महंगे होते हैं और अच्छी तरह से स्केल नहीं होते हैं
+   क्वेरी 6 और 7 को `ALLOW FILTERING` की आवश्यकता होती है, जो खराब डेटा मॉडलिंग का संकेत देती है
+
+3. **हॉट पार्टिशन का जोखिम**
+   एकल पार्टीशन कुंजी `collection` हॉट पार्टिशन बना सकती है
+   बड़े संग्रह एकल नोड्स पर केंद्रित होंगे
+   लोड बैलेंसिंग के लिए कोई वितरण रणनीति नहीं
+
+### क्वेरी-स्तरीय मुद्दे
+
+1. **ALLOW FILTERING का उपयोग** ⚠️
+   दो क्वेरी प्रकार (get_po, get_os) को `ALLOW FILTERING` की आवश्यकता होती है
+   ये क्वेरी कई पार्टिशन को स्कैन करती हैं और बेहद महंगी हैं
+   डेटा के आकार के साथ प्रदर्शन रैखिक रूप से खराब होता है
+
+2. **अकुशल एक्सेस पैटर्न**
+   सामान्य आरडीएफ क्वेरी पैटर्न के लिए कोई अनुकूलन नहीं
+   बार-बार उपयोग किए जाने वाले क्वेरी संयोजनों के लिए कोई कंपाउंड इंडेक्स नहीं
+   ग्राफ ट्रैवर्सल पैटर्न पर कोई विचार नहीं
+
+3. **क्वेरी अनुकूलन की कमी**
+   कोई तैयार स्टेटमेंट कैशिंग नहीं
+   कोई क्वेरी संकेत या अनुकूलन रणनीतियाँ नहीं
+   साधारण LIMIT से परे पेजिंग पर कोई विचार नहीं
+
+## समस्या विवरण
+
+वर्तमान कैसेंड्रा नॉलेज बेस कार्यान्वयन में दो महत्वपूर्ण प्रदर्शन संबंधी बाधाएं हैं:
+
+### 1. अकुशल get_po क्वेरी प्रदर्शन
+
+`get_po(collection, p, o)` क्वेरी `ALLOW FILTERING` की आवश्यकता के कारण बेहद अकुशल है:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**यह समस्याग्रस्त क्यों है:**
+`ALLOW FILTERING` कैसेंड्रा को संग्रह के भीतर सभी विभाजन को स्कैन करने के लिए मजबूर करता है।
+डेटा के आकार के साथ प्रदर्शन रैखिक रूप से घटता है।
+यह एक सामान्य आरडीएफ क्वेरी पैटर्न है (उन विषयों को खोजना जिनके पास एक विशिष्ट विधेय-वस्तु संबंध है)।
+जैसे-जैसे डेटा बढ़ता है, यह क्लस्टर पर महत्वपूर्ण भार डालता है।
+
+### 2. खराब क्लस्टरिंग रणनीति
+
+वर्तमान प्राथमिक कुंजी `PRIMARY KEY (collection, s, p, o)` न्यूनतम क्लस्टरिंग लाभ प्रदान करती है:
+
+**वर्तमान क्लस्टरिंग के साथ समस्याएं:**
+विभाजन कुंजी के रूप में `collection` डेटा को प्रभावी ढंग से वितरित नहीं करता है।
+अधिकांश संग्रहों में विविध डेटा होता है, जिससे क्लस्टरिंग अप्रभावी हो जाती है।
+आरडीएफ प्रश्नों में सामान्य एक्सेस पैटर्न पर कोई विचार नहीं किया गया है।
+बड़े संग्रह एकल नोड्स पर "हॉट" विभाजन बनाते हैं।
+क्लस्टरिंग कॉलम (s, p, o) विशिष्ट ग्राफ ट्रैवर्सल पैटर्न के लिए अनुकूलित नहीं हैं।
+
+**प्रभाव:**
+क्वेरी डेटा स्थानीयता से लाभान्वित नहीं होती हैं।
+खराब कैश उपयोग।
+क्लस्टर नोड्स में असमान लोड वितरण।
+जैसे-जैसे संग्रह बढ़ते हैं, स्केलेबिलिटी बाधाएं।
+
+## प्रस्तावित समाधान: 4-टेबल डीनॉर्मलाइज़ेशन रणनीति
+
+### अवलोकन
+
+एकल `triples` तालिका को चार उद्देश्य-निर्मित तालिकाओं से बदलें, प्रत्येक विशिष्ट क्वेरी पैटर्न के लिए अनुकूलित है। यह द्वितीयक अनुक्रमणिकाओं और ALLOW FILTERING की आवश्यकता को समाप्त करता है, जबकि सभी प्रकार की क्वेरी के लिए इष्टतम प्रदर्शन प्रदान करता है। चौथी तालिका समग्र विभाजन कुंजियों के बावजूद कुशल संग्रह हटाने को सक्षम बनाती है।
+
+### नया स्कीमा डिज़ाइन
+
+**टेबल 1: विषय-केंद्रित क्वेरी (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**अनुकूलन:** get_s, get_sp, get_os
+**विभाजन कुंजी:** (संग्रह, s) - केवल संग्रह की तुलना में बेहतर वितरण
+**समूहीकरण:** (p, o) - विषय के लिए कुशल विधेय/वस्तु लुकअप को सक्षम करता है
+
+**तालिका 2: विधेय-वस्तु प्रश्न (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**अनुकूलन:** get_p, get_po (ALLOW FILTERING को हटाता है!)
+**पार्टिशन कुंजी:** (संग्रह, p) - विधेय द्वारा प्रत्यक्ष पहुंच
+**क्लस्टरिंग:** (o, s) - कुशल ऑब्जेक्ट-विषय ट्रैवर्सल
+
+**तालिका 3: ऑब्जेक्ट-केंद्रित प्रश्न (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**अनुकूलन:** get_o
+**विभाजन कुंजी:** (संग्रह, o) - वस्तु द्वारा प्रत्यक्ष पहुंच
+**समूहीकरण:** (s, p) - कुशल विषय-क्रियापद ट्रैवर्सल
+
+**तालिका 4: संग्रह प्रबंधन और एस.पी.ओ. प्रश्न (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**अनुकूलन:** get_spo, delete_collection
+**विभाजन कुंजी:** केवल संग्रह - कुशल संग्रह-स्तरीय संचालन को सक्षम करता है
+**समूहीकरण:** (s, p, o) - मानक त्रिगुट क्रम
+**उद्देश्य:** सटीक SPO लुकअप के लिए दोहरे उपयोग और एक हटाने अनुक्रमणिका के रूप में
+
+### क्वेरी मैपिंग
+
+| मूल क्वेरी | लक्ष्य तालिका | प्रदर्शन सुधार |
+|----------------|-------------|------------------------|
+| get_all(संग्रह) | triples_s | ALLOW FILTERING (स्कैन के लिए स्वीकार्य) |
+| get_s(संग्रह, s) | triples_s | प्रत्यक्ष विभाजन पहुंच |
+| get_p(संग्रह, p) | triples_p | प्रत्यक्ष विभाजन पहुंच |
+| get_o(संग्रह, o) | triples_o | प्रत्यक्ष विभाजन पहुंच |
+| get_sp(संग्रह, s, p) | triples_s | विभाजन + समूहीकरण |
+| get_po(संग्रह, p, o) | triples_p | **अब ALLOW FILTERING नहीं!** |
+| get_os(संग्रह, o, s) | triples_o | विभाजन + समूहीकरण |
+| get_spo(संग्रह, s, p, o) | triples_collection | सटीक कुंजी लुकअप |
+| delete_collection(संग्रह) | triples_collection | अनुक्रमणिका पढ़ें, सभी को बैच में हटाएं |
+
+### संग्रह हटाने की रणनीति
+
+संयुक्त विभाजन कुंजियों के साथ, हम सीधे `DELETE FROM table WHERE collection = ?` निष्पादित नहीं कर सकते। इसके बजाय:
+
+1. **पढ़ने का चरण:** सभी त्रिगुटों को सूचीबद्ध करने के लिए `triples_collection` क्वेरी करें:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   यह कुशल है क्योंकि `collection` इस तालिका के लिए विभाजन कुंजी है।
+
+2. **हटाने का चरण:** प्रत्येक ट्रिपल (s, p, o) के लिए, सभी 4 तालिकाओं से पूर्ण विभाजन कुंजियों का उपयोग करके हटाएं:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   दक्षता के लिए 100 के समूहों में समूहीकृत किया गया।
+
+**ट्रेड-ऑफ विश्लेषण:**
+✅ वितरित विभाजनों के साथ इष्टतम क्वेरी प्रदर्शन बनाए रखता है।
+✅ बड़े संग्रहों के लिए कोई "हॉट" विभाजन नहीं।
+❌ अधिक जटिल हटाने का तर्क (पढ़ें-फिर-हटाएं)।
+❌ हटाने का समय संग्रह के आकार के समानुपाती होता है।
+
+### लाभ
+
+1. **ALLOW FILTERING को समाप्त करता है** - प्रत्येक क्वेरी में एक इष्टतम एक्सेस पथ होता है (सिवाय get_all स्कैन के)।
+2. **कोई द्वितीयक इंडेक्स नहीं** - प्रत्येक तालिका अपने क्वेरी पैटर्न के लिए इंडेक्स है।
+3. **बेहतर डेटा वितरण** - समग्र विभाजन कुंजियाँ प्रभावी रूप से लोड फैलाती हैं।
+4. **अनुमानित प्रदर्शन** - क्वेरी समय परिणाम के आकार के समानुपाती होता है, कुल डेटा के नहीं।
+5. **कैसेंड्रा की ताकत का लाभ उठाता है** - कैसेंड्रा के आर्किटेक्चर के लिए डिज़ाइन किया गया।
+6. **संग्रह हटाने को सक्षम बनाता है** - triples_collection हटाने के इंडेक्स के रूप में कार्य करता है।
+
+## कार्यान्वयन योजना
+
+### उन फ़ाइलों की आवश्यकता है जिनमें परिवर्तन आवश्यक हैं
+
+#### प्राथमिक कार्यान्वयन फ़ाइल
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - पूर्ण पुनर्लेखन आवश्यक है।
+
+**वर्तमान विधियाँ जिन्हें रिफैक्टर करने की आवश्यकता है:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### एकीकरण फ़ाइलें (कोई लॉजिक परिवर्तन आवश्यक नहीं)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+कोई बदलाव आवश्यक नहीं - मौजूदा नॉलेज ग्राफ एपीआई का उपयोग करता है
+प्रदर्शन में स्वचालित सुधार से लाभ
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+कोई बदलाव आवश्यक नहीं - मौजूदा नॉलेज ग्राफ एपीआई का उपयोग करता है
+प्रदर्शन में स्वचालित सुधार से लाभ
+
+### अपडेट की आवश्यकता वाली परीक्षण फ़ाइलें
+
+#### यूनिट टेस्ट
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+स्कीमा परिवर्तनों के लिए परीक्षण अपेक्षाओं को अपडेट करें
+मल्टी-टेबल स्थिरता के लिए परीक्षण जोड़ें
+क्वेरी योजनाओं में कोई ALLOW FILTERING न होने की पुष्टि करें
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+प्रदर्शन दावों को अपडेट करें
+नए तालिकाओं के खिलाफ सभी 8 क्वेरी पैटर्न का परीक्षण करें
+सही तालिकाओं में क्वेरी रूटिंग की पुष्टि करें
+
+#### एकीकरण परीक्षण
+**`tests/integration/test_cassandra_integration.py`**
+नए स्कीमा के साथ एंड-टू-एंड परीक्षण
+प्रदर्शन बेंचमार्किंग तुलना
+तालिकाओं में डेटा स्थिरता सत्यापन
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+स्कीमा सत्यापन परीक्षणों को अपडेट करें
+माइग्रेशन परिदृश्यों का परीक्षण करें
+
+### कार्यान्वयन रणनीति
+
+#### चरण 1: स्कीमा और कोर विधियाँ
+1. **`init()` विधि को फिर से लिखें** - एक के बजाय चार तालिकाओं का निर्माण करें
+2. **`insert()` विधि को फिर से लिखें** - सभी चार तालिकाओं में बैच राइट्स
+3. **तैयार कथनों को लागू करें** - इष्टतम प्रदर्शन के लिए
+4. **टेबल रूटिंग लॉजिक जोड़ें** - प्रश्नों को इष्टतम तालिकाओं पर निर्देशित करें
+5. **संग्रह हटाने को लागू करें** - triples_collection से पढ़ें, सभी तालिकाओं से बैच हटाएं
+
+#### चरण 2: क्वेरी विधि अनुकूलन
+1. **प्रत्येक get_* विधि को फिर से लिखें** ताकि इष्टतम तालिका का उपयोग किया जा सके
+2. **सभी ALLOW FILTERING उपयोग को हटा दें**
+3. **कुशल क्लस्टरिंग कुंजी उपयोग को लागू करें**
+4. **क्वेरी प्रदर्शन लॉगिंग जोड़ें**
+
+#### चरण 3: संग्रह प्रबंधन
+1. **`delete_collection()` को अपडेट करें** - सभी तीन तालिकाओं से हटाएं
+2. **संगति सत्यापन जोड़ें** - सुनिश्चित करें कि सभी तालिकाओं को सिंक में रखा जाए
+3. **बैच ऑपरेशंस लागू करें** - परमाणु मल्टी-टेबल ऑपरेशंस के लिए
+
+### प्रमुख कार्यान्वयन विवरण
+
+#### बैच राइट रणनीति
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### प्रश्न रूटिंग लॉजिक (Query Routing Logic)
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### संग्रह हटाने का तर्क
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### तैयार स्टेटमेंट अनुकूलन (तैयार कथन अनुकूलन)
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## माइग्रेशन रणनीति
+
+### डेटा माइग्रेशन दृष्टिकोण
+
+#### विकल्प 1: ब्लू-ग्रीन परिनियोजन (अनुशंसित)
+1. **नए स्कीमा को मौजूदा स्कीमा के साथ तैनात करें** - अस्थायी रूप से अलग-अलग टेबल नामों का उपयोग करें
+2. **डबल-राइट अवधि** - संक्रमण के दौरान पुराने और नए दोनों स्कीमा में लिखें
+3. **बैकग्राउंड माइग्रेशन** - मौजूदा डेटा को नई तालिकाओं में कॉपी करें
+4. **रीड स्विच करें** - डेटा माइग्रेट होने के बाद प्रश्नों को नई तालिकाओं पर रूट करें
+5. **पुराने तालिकाओं को हटाएं** - सत्यापन अवधि के बाद
+
+#### विकल्प 2: इन-प्लेस माइग्रेशन
+1. **स्कीमा जोड़ना** - मौजूदा कीस्पेस में नई तालिकाएँ बनाएँ
+2. **डेटा माइग्रेशन स्क्रिप्ट** - बैच कॉपी पुराने टेबल से नई तालिकाओं में
+3. **एप्लिकेशन अपडेट** - माइग्रेशन पूरा होने के बाद नया कोड तैनात करें
+4. **पुरानी टेबल की सफाई** - पुरानी टेबल और इंडेक्स हटाएं
+
+### पश्चगामी अनुकूलता
+
+#### परिनियोजन रणनीति
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### माइग्रेशन स्क्रिप्ट
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### सत्यापन रणनीति
+
+#### डेटा संगति जांच
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## परीक्षण रणनीति
+
+### प्रदर्शन परीक्षण
+
+#### बेंचमार्क परिदृश्य
+1. **क्वेरी प्रदर्शन तुलना**
+   सभी 8 क्वेरी प्रकारों के लिए पूर्व/पश्च प्रदर्शन मेट्रिक्स
+   `get_po` प्रदर्शन सुधार पर ध्यान केंद्रित करें (ALLOW FILTERING को हटाना)
+   विभिन्न डेटा आकारों के तहत क्वेरी विलंबता को मापें
+
+2. **लोड परीक्षण**
+   समवर्ती क्वेरी निष्पादन
+   बैच ऑपरेशनों के साथ लेखन थ्रूपुट
+   मेमोरी और सीपीयू उपयोग
+
+3. **स्केलेबिलिटी परीक्षण**
+   बढ़ते संग्रह आकारों के साथ प्रदर्शन
+   मल्टी-कलेक्शन क्वेरी वितरण
+   क्लस्टर नोड उपयोग
+
+#### परीक्षण डेटा सेट
+**छोटा:** प्रति संग्रह 10K त्रिगुण
+**मध्यम:** प्रति संग्रह 100K त्रिगुण
+**बड़ा:** 1M+ त्रिगुण
+**एकाधिक संग्रह:** परीक्षण विभाजन वितरण
+
+### कार्यात्मक परीक्षण
+
+#### यूनिट टेस्ट अपडेट
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### एकीकरण परीक्षण अपडेट
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### रोलबैक योजना
+
+#### त्वरित रोलबैक रणनीति
+1. **पर्यावरण चर स्विच** - तुरंत पुराने तालिकाओं पर वापस स्विच करें
+2. **पुराने तालिकाओं को बनाए रखें** - प्रदर्शन साबित होने तक उन्हें हटाएं नहीं
+3. **निगरानी अलर्ट** - त्रुटि दर/विलंबता के आधार पर स्वचालित रोलबैक ट्रिगर
+
+#### रोलबैक सत्यापन
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## जोखिम और विचार
+
+### प्रदर्शन जोखिम
+**लेखन विलंबता में वृद्धि** - प्रति सम्मिलित 4x लेखन संचालन (3-तालिका दृष्टिकोण से 33% अधिक)
+**भंडारण ओवरहेड** - 4x भंडारण आवश्यकता (3-तालिका दृष्टिकोण से 33% अधिक)
+**बैच लेखन विफलताएं** - उचित त्रुटि प्रबंधन की आवश्यकता
+**हटाने की जटिलता** - संग्रह हटाने के लिए रीड-देन-डिलीट लूप की आवश्यकता होती है
+
+### परिचालन जोखिम
+**स्थानांतरण जटिलता** - बड़े डेटासेट के लिए डेटा स्थानांतरण
+**संगति चुनौतियां** - यह सुनिश्चित करना कि सभी तालिकाएं सिंक्रनाइज़ रहें
+**निगरानी अंतराल** - मल्टी-टेबल ऑपरेशनों के लिए नए मेट्रिक्स की आवश्यकता
+
+### शमन रणनीतियाँ
+1. **धीरे-धीरे रोलआउट** - छोटे संग्रहों से शुरुआत करें
+2. **व्यापक निगरानी** - सभी प्रदर्शन मेट्रिक्स को ट्रैक करें
+3. **स्वचालित सत्यापन** - निरंतर संगति जांच
+4. **त्वरित रोलबैक क्षमता** - पर्यावरण-आधारित तालिका चयन
+
+## सफलता मानदंड
+
+### प्रदर्शन सुधार
+[ ] **ALLOW FILTERING को समाप्त करें** - get_po और get_os क्वेरी फ़िल्टरिंग के बिना चलती हैं
+[ ] **क्वेरी विलंबता में कमी** - क्वेरी प्रतिक्रिया समय में 50%+ सुधार
+[ ] **बेहतर लोड वितरण** - कोई हॉट विभाजन नहीं, क्लस्टर नोड्स में समान लोड
+[ ] **स्केलेबल प्रदर्शन** - क्वेरी समय परिणाम आकार के समानुपाती, कुल डेटा के समानुपाती नहीं
+
+### कार्यात्मक आवश्यकताएँ
+[ ] **एपीआई संगतता** - सभी मौजूदा कोड अपरिवर्तित रूप से काम करना जारी रखता है
+[ ] **डेटा संगति** - तीनों तालिकाओं को सिंक्रनाइज़ रखा जाता है
+[ ] **कोई डेटा हानि नहीं** - माइग्रेशन सभी मौजूदा त्रिगुणों को संरक्षित करता है
+[ ] **पिछड़ा संगतता** - विरासत स्कीमा पर वापस रोलबैक करने की क्षमता
+
+### परिचालन आवश्यकताएँ
+[ ] **सुरक्षित स्थानांतरण** - रोलबैक क्षमता के साथ ब्लू-ग्रीन परिनियोजन
+[ ] **निगरानी कवरेज** - मल्टी-टेबल ऑपरेशनों के लिए व्यापक मेट्रिक्स
+[ ] **परीक्षण कवरेज** - सभी क्वेरी पैटर्न प्रदर्शन बेंचमार्क के साथ परीक्षण किए गए
+[ ] **प्रलेखन** - अद्यतन परिनियोजन और परिचालन प्रक्रियाएं
+
+## समयरेखा
+
+### चरण 1: कार्यान्वयन
+[ ] मल्टी-टेबल स्कीमा के साथ `cassandra_kg.py` को फिर से लिखें
+[ ] बैच लेखन संचालन लागू करें
+[ ] तैयार स्टेटमेंट अनुकूलन जोड़ें
+[ ] यूनिट परीक्षण अपडेट करें
+
+### चरण 2: एकीकरण परीक्षण
+[ ] एकीकरण परीक्षण अपडेट करें
+[ ] प्रदर्शन बेंचमार्किंग
+[ ] यथार्थवादी डेटा वॉल्यूम के साथ लोड परीक्षण
+[ ] डेटा संगति के लिए सत्यापन स्क्रिप्ट
+
+### चरण 3: माइग्रेशन योजना
+[ ] ब्लू-ग्रीन परिनियोजन स्क्रिप्ट
+[ ] डेटा माइग्रेशन उपकरण
+[ ] निगरानी डैशबोर्ड अपडेट
+[ ] रोलबैक प्रक्रियाएं
+
+### चरण 4: उत्पादन परिनियोजन
+[ ] उत्पादन में क्रमिक रोलआउट
+[ ] प्रदर्शन निगरानी और सत्यापन
+[ ] विरासत तालिका सफाई
+[ ] प्रलेखन अपडेट
+
+## निष्कर्ष
+
+यह मल्टी-टेबल डीनॉर्मलाइज़ेशन रणनीति दो महत्वपूर्ण प्रदर्शन बाधाओं को सीधे संबोधित करती है:
+
+1. **महंगे ALLOW FILTERING को समाप्त करता है** प्रत्येक क्वेरी पैटर्न के लिए इष्टतम तालिका संरचनाएं प्रदान करके
+2. **बेहतर क्लस्टरिंग प्रभावशीलता** समग्र विभाजन कुंजियों के माध्यम से जो लोड को ठीक से वितरित करते हैं
+
+यह दृष्टिकोण कैसेंड्रा की ताकत का लाभ उठाता है जबकि पूर्ण एपीआई संगतता बनाए रखता है, यह सुनिश्चित करता है कि मौजूदा कोड प्रदर्शन सुधारों से स्वचालित रूप से लाभान्वित होता है।

docs/tech-specs/cassandra-performance-refactor.pt.md

@@ -0,0 +1,679 @@
+# Especificação Técnica: Refatoração de Desempenho da Base de Conhecimento Cassandra
+
+**Status:** Rascunho
+**Autor:** Assistente
+**Data:** 2025-09-18
+
+## Visão Geral
+
+Esta especificação aborda problemas de desempenho na implementação da base de conhecimento Cassandra TrustGraph e propõe otimizações para o armazenamento e consulta de triplas RDF.
+
+## Implementação Atual
+
+### Design do Esquema
+
+A implementação atual utiliza um design de tabela única em `trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**Índices Secundários:**
+`triples_s` EM `s` (sujeito)
+`triples_p` EM `p` (predicado)
+`triples_o` EM `o` (objeto)
+
+### Padrões de Consulta
+
+A implementação atual suporta 8 padrões de consulta distintos:
+
+1. **get_all(coleção, limite=50)** - Recupera todas as triplas para uma coleção
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - Consulta por assunto
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - Consulta por predicado
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - Consulta por objeto
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - Consulta por sujeito + predicado
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - Consulta por predicado + objeto ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - Consulta por objeto + sujeito ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - Correspondência exata de tripla.
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### Arquitetura Atual
+
+**Arquivo: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+Classe única `KnowledgeGraph` que gerencia todas as operações
+Pool de conexões através de uma lista global `_active_clusters`
+Nome de tabela fixo: `"triples"`
+Modelo de keyspace por usuário
+Replicação SimpleStrategy com fator 1
+
+**Pontos de Integração:**
+**Caminho de Escrita:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**Caminho de Consulta:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**Armazenamento de Conhecimento:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## Problemas de Desempenho Identificados
+
+### Problemas no Nível do Schema
+
+1. **Design de Chave Primária Ineficiente**
+   Atual: `PRIMARY KEY (collection, s, p, o)`
+   Resulta em agrupamento inadequado para padrões de acesso comuns
+   Força o uso de índices secundários caros
+
+2. **Uso Excessivo de Índices Secundários** ⚠️
+   Três índices secundários em colunas de alta cardinalidade (s, p, o)
+   Índices secundários em Cassandra são caros e não escalam bem
+   As consultas 6 e 7 requerem `ALLOW FILTERING`, indicando modelagem de dados inadequada
+
+3. **Risco de Partições Quentes**
+   Uma única chave de partição `collection` pode criar partições quentes
+   Grandes coleções se concentrarão em nós únicos
+   Não há estratégia de distribuição para balanceamento de carga
+
+### Problemas no Nível da Consulta
+
+1. **Uso de ALLOW FILTERING** ⚠️
+   Dois tipos de consulta (get_po, get_os) requerem `ALLOW FILTERING`
+   Essas consultas escaneiam várias partições e são extremamente caras
+   O desempenho degrada linearmente com o tamanho dos dados
+
+2. **Padrões de Acesso Ineficientes**
+   Não há otimização para padrões de consulta RDF comuns
+   Índices compostos ausentes para combinações de consulta frequentes
+   Não há consideração para padrões de travessia de grafos
+
+3. **Falta de Otimização de Consulta**
+   Não há cache de prepared statements
+   Não há dicas de consulta ou estratégias de otimização
+   Não há consideração para paginação além de um simples LIMIT
+
+## Declaração do Problema
+
+A implementação atual da base de conhecimento Cassandra tem dois gargalos críticos de desempenho:
+
+### 1. Desempenho Ineficiente da Consulta get_po
+
+A consulta `get_po(collection, p, o)` é extremamente ineficiente devido à necessidade de `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**Por que isso é problemático:**
+`ALLOW FILTERING` força o Cassandra a escanear todas as partições dentro da coleção.
+O desempenho diminui linearmente com o tamanho dos dados.
+Este é um padrão de consulta RDF comum (encontrar sujeitos que têm um relacionamento específico de predicado-objeto).
+Cria uma carga significativa no cluster à medida que os dados crescem.
+
+### 2. Estratégia de Clustering Inadequada
+
+A chave primária atual `PRIMARY KEY (collection, s, p, o)` oferece benefícios mínimos de clustering:
+
+**Problemas com o clustering atual:**
+`collection` como chave de partição não distribui os dados de forma eficaz.
+A maioria das coleções contém dados diversos, tornando o clustering ineficaz.
+Não há consideração para padrões de acesso comuns em consultas RDF.
+Coleções grandes criam partições quentes em nós únicos.
+As colunas de clustering (s, p, o) não otimizam para padrões típicos de travessia de grafos.
+
+**Impacto:**
+As consultas não se beneficiam da localidade dos dados.
+Utilização inadequada do cache.
+Distribuição desigual de carga entre os nós do cluster.
+Gargalos de escalabilidade à medida que as coleções crescem.
+
+## Solução Proposta: Estratégia de Desnormalização de 4 Tabelas
+
+### Visão Geral
+
+Substitua a única tabela `triples` por quatro tabelas projetadas especificamente, cada uma otimizada para padrões de consulta específicos. Isso elimina a necessidade de índices secundários e ALLOW FILTERING, ao mesmo tempo em que fornece desempenho ideal para todos os tipos de consulta. A quarta tabela permite a exclusão eficiente de coleções, apesar das chaves de partição compostas.
+
+### Novo Design de Esquema
+
+**Tabela 1: Consultas Centradas no Sujeito (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**Otimiza:** get_s, get_sp, get_os
+**Chave de Partição:** (coleção, s) - Melhor distribuição do que apenas a coleção
+**Agrupamento:** (p, o) - Permite pesquisas eficientes de predicados/objetos para um sujeito
+
+**Tabela 2: Consultas Predicado-Objeto (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**Otimiza:** get_p, get_po (elimina ALLOW FILTERING!)
+**Chave de Partição:** (coleção, p) - Acesso direto por predicado
+**Agrupamento:** (o, s) - Traversal eficiente de objeto-sujeito
+
+**Tabela 3: Consultas Orientadas a Objetos (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**Otimiza:** get_o
+**Chave de Partição:** (coleção, o) - Acesso direto por objeto
+**Agrupamento:** (s, p) - Traversal eficiente de sujeito-predicado
+
+**Tabela 4: Gerenciamento de Coleções e Consultas SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**Otimiza:** get_spo, delete_collection
+**Chave de Partição:** coleção apenas - Permite operações eficientes no nível da coleção.
+**Agrupamento:** (s, p, o) - Ordenação padrão de triplas.
+**Propósito:** Uso duplo para pesquisas exatas de SPO e como índice de exclusão.
+
+### Mapeamento de Consultas
+
+| Consulta Original | Tabela de Destino | Melhoria de Desempenho |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | PERMITE FILTRAGEM (aceitável para varredura) |
+| get_s(collection, s) | triples_s | Acesso direto à partição |
+| get_p(collection, p) | triples_p | Acesso direto à partição |
+| get_o(collection, o) | triples_o | Acesso direto à partição |
+| get_sp(collection, s, p) | triples_s | Partição + agrupamento |
+| get_po(collection, p, o) | triples_p | **Não mais PERMITE FILTRAGEM!** |
+| get_os(collection, o, s) | triples_o | Partição + agrupamento |
+| get_spo(collection, s, p, o) | triples_collection | Pesquisa de chave exata |
+| delete_collection(collection) | triples_collection | Lê o índice, exclusão em lote de todos |
+
+### Estratégia de Exclusão de Coleção
+
+Com chaves de partição compostas, não podemos simplesmente executar `DELETE FROM table WHERE collection = ?`. Em vez disso:
+
+1. **Fase de Leitura:** Consulta `triples_collection` para enumerar todas as triplas:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   Isso é eficiente, já que `collection` é a chave de partição para esta tabela.
+
+2. **Fase de Exclusão:** Para cada tripla (s, p, o), exclua de todas as 4 tabelas usando as chaves de partição completas:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   Agrupado em lotes de 100 para maior eficiência.
+
+**Análise de Compromissos:**
+✅ Mantém o desempenho ideal das consultas com partições distribuídas.
+✅ Sem partições com alta carga para grandes coleções.
+❌ Lógica de exclusão mais complexa (leitura e depois exclusão).
+❌ Tempo de exclusão proporcional ao tamanho da coleção.
+
+### Benefícios
+
+1. **Elimina ALLOW FILTERING** - Cada consulta tem um caminho de acesso ideal (exceto a varredura get_all).
+2. **Sem Índices Secundários** - Cada tabela É o índice para seu padrão de consulta.
+3. **Melhor Distribuição de Dados** - As chaves de partição compostas distribuem a carga de forma eficaz.
+4. **Desempenho Previsível** - O tempo de consulta é proporcional ao tamanho do resultado, não ao tamanho total dos dados.
+5. **Aproveita os Pontos Fortes do Cassandra** - Projetado para a arquitetura do Cassandra.
+6. **Permite a Exclusão de Coleções** - triples_collection serve como índice de exclusão.
+
+## Plano de Implementação
+
+### Arquivos que Requerem Alterações
+
+#### Arquivo de Implementação Primário
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Reescrita completa necessária.
+
+**Métodos Atuais a Serem Refatorados:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### Arquivos de Integração (Nenhuma Alteração de Lógica Necessária)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+Nenhuma alteração necessária - utiliza a API KnowledgeGraph existente
+Beneficia automaticamente das melhorias de desempenho
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+Nenhuma alteração necessária - utiliza a API KnowledgeGraph existente
+Beneficia automaticamente das melhorias de desempenho
+
+### Arquivos de Teste que Requerem Atualizações
+
+#### Testes Unitários
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+Atualizar as expectativas dos testes para as alterações no esquema
+Adicionar testes para a consistência de várias tabelas
+Verificar se não há ALLOW FILTERING nos planos de consulta
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+Atualizar as asserções de desempenho
+Testar todos os 8 padrões de consulta contra as novas tabelas
+Verificar o roteamento da consulta para as tabelas corretas
+
+#### Testes de Integração
+**`tests/integration/test_cassandra_integration.py`**
+Testes de ponta a ponta com o novo esquema
+Comparativos de benchmarking de desempenho
+Verificação da consistência dos dados entre as tabelas
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+Atualizar os testes de validação de esquema
+Testar cenários de migração
+
+### Estratégia de Implementação
+
+#### Fase 1: Esquema e Métodos Principais
+1. **Reescrever o método `init()`** - Criar quatro tabelas em vez de uma
+2. **Reescrever o método `insert()`** - Gravações em lote em todas as quatro tabelas
+3. **Implementar instruções preparadas** - Para desempenho ideal
+4. **Adicionar lógica de roteamento de tabela** - Direcionar consultas para as tabelas mais adequadas
+5. **Implementar a exclusão de coleções** - Ler de triples_collection, excluir em lote de todas as tabelas
+
+#### Fase 2: Otimização do Método de Consulta
+1. **Reescrever cada método get_*** para usar a tabela mais adequada
+2. **Remover todo o uso de ALLOW FILTERING**
+3. **Implementar o uso eficiente da chave de agrupamento**
+4. **Adicionar registro de desempenho da consulta**
+
+#### Fase 3: Gerenciamento de Coleções
+1. **Atualizar `delete_collection()`** - Remover de todas as três tabelas
+2. **Adicionar verificação de consistência** - Garantir que todas as tabelas permaneçam sincronizadas
+3. **Implementar operações em lote** - Para operações multi-tabela atômicas
+
+### Detalhes Chave da Implementação
+
+#### Estratégia de Gravação em Lote
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### Lógica de Roteamento de Consultas
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### Lógica de Exclusão de Coleções
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### Otimização de Instruções Preparadas
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## Estratégia de Migração
+
+### Abordagem de Migração de Dados
+
+#### Opção 1: Implantação Blue-Green (Recomendada)
+1. **Implantar o novo esquema junto com o existente** - Use nomes de tabelas diferentes temporariamente
+2. **Período de escrita dupla** - Escrever tanto no esquema antigo quanto no novo durante a transição
+3. **Migração em segundo plano** - Copiar dados existentes para novas tabelas
+4. **Alternar leituras** - Direcionar consultas para novas tabelas assim que os dados forem migrados
+5. **Remover tabelas antigas** - Após o período de verificação
+
+#### Opção 2: Migração no Local
+1. **Adição de esquema** - Criar novas tabelas no keyspace existente
+2. **Script de migração de dados** - Copiar em lote da tabela antiga para as novas tabelas
+3. **Atualização do aplicativo** - Implantar novo código após a conclusão da migração
+4. **Limpeza da tabela antiga** - Remover a tabela antiga e os índices
+
+### Compatibilidade com Versões Anteriores
+
+#### Estratégia de Implantação
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### Script de Migração
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### Estratégia de Validação
+
+#### Verificações de Consistência de Dados
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## Estratégia de Testes
+
+### Testes de Desempenho
+
+#### Cenários de Benchmark
+1. **Comparação de Desempenho de Consultas**
+   Métricas de desempenho antes/depois para todos os 8 tipos de consulta
+   Foco na melhoria de desempenho de `get_po` (eliminar `ALLOW FILTERING`)
+   Medir a latência da consulta sob vários tamanhos de dados
+
+2. **Testes de Carga**
+   Execução de consultas concorrentes
+   Taxa de transferência de escrita com operações em lote
+   Utilização de memória e CPU
+
+3. **Testes de Escalabilidade**
+   Desempenho com tamanhos de coleção crescentes
+   Distribuição de consultas em várias coleções
+   Utilização de nós do cluster
+
+#### Conjuntos de Dados de Teste
+**Pequeno:** 10K triplas por coleção
+**Médio:** 100K triplas por coleção
+**Grande:** 1M+ triplas por coleção
+**Múltiplas coleções:** Testar a distribuição de partições
+
+### Testes Funcionais
+
+#### Atualizações de Testes Unitários
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### Atualizações do Teste de Integração
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### Plano de Reversão
+
+#### Estratégia de Reversão Rápida
+1. **Alternância de variáveis de ambiente** - Retorne imediatamente para as tabelas legadas.
+2. **Mantenha as tabelas legadas** - Não as exclua até que o desempenho seja comprovado.
+3. **Alertas de monitoramento** - Disparos de reversão automatizados com base em taxas de erro/latência.
+
+#### Validação da Reversão
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## Riscos e Considerações
+
+### Riscos de Desempenho
+**Aumento da latência de escrita** - 4 operações de escrita por inserção (33% a mais do que a abordagem de 3 tabelas)
+**Sobrecarga de armazenamento** - 4x o requisito de armazenamento (33% a mais do que a abordagem de 3 tabelas)
+**Falhas de escrita em lote** - Necessidade de tratamento adequado de erros
+**Complexidade da exclusão** - A exclusão da coleção requer um loop de leitura e exclusão
+
+### Riscos Operacionais
+**Complexidade da migração** - Migração de dados para grandes conjuntos de dados
+**Desafios de consistência** - Garantir que todas as tabelas permaneçam sincronizadas
+**Lacunas de monitoramento** - Necessidade de novas métricas para operações de várias tabelas
+
+### Estratégias de Mitigação
+1. **Implantação gradual** - Começar com pequenas coleções
+2. **Monitoramento abrangente** - Rastrear todas as métricas de desempenho
+3. **Validação automatizada** - Verificação contínua de consistência
+4. **Capacidade de reversão rápida** - Seleção de tabela baseada no ambiente
+
+## Critérios de Sucesso
+
+### Melhorias de Desempenho
+[ ] **Eliminar ALLOW FILTERING** - as consultas get_po e get_os são executadas sem filtragem
+[ ] **Redução da latência da consulta** - melhoria de 50% ou mais nos tempos de resposta da consulta
+[ ] **Melhor distribuição de carga** - Sem partições quentes, distribuição uniforme entre os nós do cluster
+[ ] **Desempenho escalável** - Tempo de consulta proporcional ao tamanho do resultado, não ao volume total de dados
+
+### Requisitos Funcionais
+[ ] **Compatibilidade da API** - Todo o código existente continua a funcionar sem alterações
+[ ] **Consistência de dados** - As três tabelas permanecem sincronizadas
+[ ] **Nenhuma perda de dados** - A migração preserva todas as triplas existentes
+[ ] **Compatibilidade com versões anteriores** - Capacidade de reverter para o esquema legado
+
+### Requisitos Operacionais
+[ ] **Migração segura** - Implantação blue-green com capacidade de reversão
+[ ] **Cobertura de monitoramento** - Métricas abrangentes para operações de várias tabelas
+[ ] **Cobertura de teste** - Todos os padrões de consulta testados com benchmarks de desempenho
+[ ] **Documentação** - Procedimentos de implantação e operação atualizados
+
+## Cronograma
+
+### Fase 1: Implementação
+[ ] Reescrever `cassandra_kg.py` com o esquema de várias tabelas
+[ ] Implementar operações de escrita em lote
+[ ] Adicionar otimização de declaração preparada
+[ ] Atualizar testes unitários
+
+### Fase 2: Testes de Integração
+[ ] Atualizar testes de integração
+[ ] Benchmarking de desempenho
+[ ] Teste de carga com volumes de dados realistas
+[ ] Scripts de validação para consistência de dados
+
+### Fase 3: Planejamento da Migração
+[ ] Scripts de implantação blue-green
+[ ] Ferramentas de migração de dados
+[ ] Atualizações do painel de monitoramento
+[ ] Procedimentos de reversão
+
+### Fase 4: Implantação em Produção
+[ ] Implantação gradual em produção
+[ ] Monitoramento e validação de desempenho
+[ ] Limpeza de tabelas legadas
+[ ] Atualizações de documentação
+
+## Conclusão
+
+Esta estratégia de desnormalização multi-tabela aborda diretamente os dois gargalos de desempenho críticos:
+
+1. **Elimina o ALLOW FILTERING caro** fornecendo estruturas de tabela ideais para cada padrão de consulta
+2. **Melhora a eficácia do agrupamento** por meio de chaves de partição compostas que distribuem a carga adequadamente
+
+A abordagem aproveita os pontos fortes do Cassandra, mantendo a compatibilidade total da API, garantindo que o código existente se beneficie automaticamente das melhorias de desempenho.

docs/tech-specs/cassandra-performance-refactor.ru.md

@@ -0,0 +1,679 @@
+# Технические спецификации: Оптимизация производительности базы знаний Cassandra
+
+**Статус:** Черновик
+**Автор:** Ассистент
+**Дата:** 2025-09-18
+
+## Обзор
+
+Данная спецификация рассматривает проблемы производительности в реализации базы знаний TrustGraph на Cassandra и предлагает оптимизации для хранения и запросов RDF-тройных.
+
+## Текущая реализация
+
+### Структура данных
+
+Текущая реализация использует структуру данных с одной таблицей в `trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**Вторичные индексы:**
+`triples_s` по `s` (субъект)
+`triples_p` по `p` (предикат)
+`triples_o` по `o` (объект)
+
+### Шаблоны запросов
+
+Текущая реализация поддерживает 8 различных шаблонов запросов:
+
+1. **get_all(collection, limit=50)** - Получить все тройки для коллекции
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - Запрос по теме.
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - Запрос по предикату.
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - Запрос по объекту.
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - Запрос по субъекту + предикату.
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - Запрос по предикату + объекту ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - Запрос по объекту + субъекту ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - Точное соответствие тройке.
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### Текущая архитектура
+
+**Файл: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+Один класс `KnowledgeGraph`, обрабатывающий все операции
+Объединение подключений через глобальный список `_active_clusters`
+Фиксированное имя таблицы: `"triples"`
+Пространство ключей для каждой модели пользователя
+Репликация SimpleStrategy с коэффициентом 1
+
+**Точки интеграции:**
+**Путь записи:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**Путь запроса:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**Хранилище знаний:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## Выявленные проблемы с производительностью
+
+### Проблемы на уровне схемы
+
+1. **Неэффективный дизайн первичного ключа**
+   Текущий: `PRIMARY KEY (collection, s, p, o)`
+   Приводит к плохой кластеризации для распространенных шаблонов доступа
+   Заставляет использовать дорогостоящие вторичные индексы
+
+2. **Чрезмерное использование вторичных индексов** ⚠️
+   Три вторичных индекса на столбцах с высокой кардинальностью (s, p, o)
+   Вторичные индексы в Cassandra дороги и плохо масштабируются
+   Запросы 6 и 7 требуют `ALLOW FILTERING`, что указывает на плохое моделирование данных
+
+3. **Риск "горячих" разделов**
+   Один ключ раздела `collection` может создавать "горячие" разделы
+   Большие коллекции будут концентрироваться на отдельных узлах
+   Отсутствует стратегия распределения для балансировки нагрузки
+
+### Проблемы на уровне запросов
+
+1. **Использование ALLOW FILTERING** ⚠️
+   Два типа запросов (get_po, get_os) требуют `ALLOW FILTERING`
+   Эти запросы сканируют несколько разделов и чрезвычайно дороги
+   Производительность ухудшается линейно с увеличением объема данных
+
+2. **Неэффективные шаблоны доступа**
+   Отсутствует оптимизация для распространенных шаблонов запросов RDF
+   Отсутствуют составные индексы для часто используемых комбинаций запросов
+   Не учитываются шаблоны обхода графов
+
+3. **Отсутствие оптимизации запросов**
+   Отсутствует кэширование подготовленных выражений
+   Отсутствуют подсказки или стратегии оптимизации запросов
+   Не учитывается постраничная навигация, кроме простого LIMIT
+
+## Описание проблемы
+
+Текущая реализация базы знаний Cassandra имеет два критических узких места в производительности:
+
+### 1. Неэффективная производительность запроса get_po
+
+Запрос `get_po(collection, p, o)` крайне неэффективен, поскольку требует `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**Почему это является проблемой:**
+`ALLOW FILTERING` заставляет Cassandra сканировать все разделы внутри коллекции.
+Производительность ухудшается линейно с увеличением размера данных.
+Это распространенный шаблон запросов RDF (поиск объектов, имеющих определенную связь "субъект-предикат-объект").
+Это создает значительную нагрузку на кластер по мере роста данных.
+
+### 2. Неоптимальная стратегия кластеризации
+
+Текущий первичный ключ `PRIMARY KEY (collection, s, p, o)` обеспечивает минимальные преимущества кластеризации:
+
+**Проблемы с текущей кластеризацией:**
+`collection` в качестве ключа раздела не обеспечивает эффективное распределение данных.
+Большинство коллекций содержат разнообразные данные, что делает кластеризацию неэффективной.
+Отсутствует учет типичных шаблонов доступа в запросах RDF.
+Большие коллекции создают "горячие" разделы на отдельных узлах.
+Столбцы кластеризации (s, p, o) не оптимизированы для типичных шаблонов обхода графа.
+
+**Влияние:**
+Запросы не получают выгоды от локальности данных.
+Плохое использование кэша.
+Неравномерное распределение нагрузки между узлами кластера.
+"Узкие места" масштабируемости по мере роста коллекций.
+
+## Предлагаемое решение: Стратегия денормализации с использованием 4 таблиц
+
+### Обзор
+
+Замените одну таблицу `triples` на четыре специализированные таблицы, каждая из которых оптимизирована для конкретных шаблонов запросов. Это устраняет необходимость во вторичных индексах и использовании ALLOW FILTERING, обеспечивая при этом оптимальную производительность для всех типов запросов. Четвертая таблица обеспечивает эффективное удаление коллекций, несмотря на составные ключи разделов.
+
+### Новая структура схемы
+
+**Таблица 1: Запросы, ориентированные на субъекты (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**Оптимизирует:** get_s, get_sp, get_os
+**Ключ разделения:** (collection, s) - Обеспечивает лучшую распределенность, чем только collection.
+**Кластеризация:** (p, o) - Обеспечивает эффективный поиск по предикатам/объектам для субъекта.
+
+**Таблица 2: Запросы предикат-объект (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**Оптимизирует:** get_p, get_po (исключает ALLOW FILTERING!)
+**Ключ партиции:** (collection, p) - Прямой доступ по предикату
+**Кластеризация:** (o, s) - Эффективный обход объектов и субъектов
+
+**Таблица 3: Объектно-ориентированные запросы (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**Оптимизирует:** get_o
+**Ключ разделения:** (collection, o) - Прямой доступ по объекту
+**Кластеризация:** (s, p) - Эффективный обход по субъекту-предикату
+
+**Таблица 4: Управление коллекциями и запросы SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**Оптимизирует:** get_spo, delete_collection
+**Разделительный ключ:** только коллекция - Обеспечивает эффективные операции на уровне коллекций.
+**Кластеризация:** (s, p, o) - Стандартный порядок троек.
+**Назначение:** Двойное использование для точного поиска SPO и в качестве индекса удаления.
+
+### Отображение запросов
+
+| Исходный запрос | Целевая таблица | Улучшение производительности |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | ALLOW FILTERING (приемлемо для сканирования) |
+| get_s(collection, s) | triples_s | Прямой доступ к разделу |
+| get_p(collection, p) | triples_p | Прямой доступ к разделу |
+| get_o(collection, o) | triples_o | Прямой доступ к разделу |
+| get_sp(collection, s, p) | triples_s | Раздел + кластеризация |
+| get_po(collection, p, o) | triples_p | **Больше не требуется ALLOW FILTERING!** |
+| get_os(collection, o, s) | triples_o | Раздел + кластеризация |
+| get_spo(collection, s, p, o) | triples_collection | Точный поиск по ключу |
+| delete_collection(collection) | triples_collection | Чтение индекса, пакетное удаление всех |
+
+### Стратегия удаления коллекций
+
+С составными раздельными ключами мы не можем просто выполнить `DELETE FROM table WHERE collection = ?`. Вместо этого:
+
+1. **Фаза чтения:** Запрос `triples_collection` для перечисления всех троек:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   Это эффективно, поскольку `collection` является ключом секции для этой таблицы.
+
+2. **Фаза удаления:** Для каждой тройки (s, p, o) удалите из всех 4 таблиц, используя полные ключи секций:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   Обрабатывается пакетами по 100 элементов для повышения эффективности.
+
+**Анализ компромиссов:**
+✅ Поддерживает оптимальную производительность запросов с использованием распределенных разделов.
+✅ Отсутствуют "горячие" разделы для больших коллекций.
+❌ Более сложная логика удаления (чтение, а затем удаление).
+❌ Время удаления пропорционально размеру коллекции.
+
+### Преимущества
+
+1. **Устраняет ALLOW FILTERING** - Каждый запрос имеет оптимальный путь доступа (за исключением полного сканирования).
+2. **Не требуются вторичные индексы** - Каждая таблица ЯВЛЯЕТСЯ индексом для своего шаблона запросов.
+3. **Более равномерное распределение данных** - Композитные ключи разделов эффективно распределяют нагрузку.
+4. **Предсказуемая производительность** - Время выполнения запроса пропорционально размеру результата, а не общему объему данных.
+5. **Использует сильные стороны Cassandra** - Разработана с учетом архитектуры Cassandra.
+6. **Позволяет удалять коллекции** - `triples_collection` служит индексом для удаления.
+
+## План реализации
+
+### Файлы, требующие изменений
+
+#### Основной файл реализации
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Требуется полная переработка.
+
+**Методы, требующие рефакторинга:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### Интеграционные файлы (изменения в логике не требуются)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+Изменения не требуются - используется существующий API KnowledgeGraph.
+Автоматически получает преимущества от улучшений производительности.
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+Изменения не требуются - используется существующий API KnowledgeGraph.
+Автоматически получает преимущества от улучшений производительности.
+
+### Файлы для тестирования, требующие обновления
+
+#### Юнит-тесты
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+Обновить ожидаемые результаты тестов в связи с изменениями схемы.
+Добавить тесты для обеспечения согласованности между несколькими таблицами.
+Проверить отсутствие использования ALLOW FILTERING в планах запросов.
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+Обновить утверждения о производительности.
+Протестировать все 8 шаблонов запросов для новых таблиц.
+Проверить маршрутизацию запросов к правильным таблицам.
+
+#### Интеграционные тесты
+**`tests/integration/test_cassandra_integration.py`**
+Комплексное тестирование с новой схемой.
+Сравнение результатов бенчмаркинга производительности.
+Проверка согласованности данных между таблицами.
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+Обновить тесты проверки схемы.
+Протестировать сценарии миграции.
+
+### Стратегия реализации
+
+#### Фаза 1: Схема и основные методы
+1. **Переписать метод `init()`** - Создать четыре таблицы вместо одной.
+2. **Переписать метод `insert()`** - Выполнять пакетные записи во все четыре таблицы.
+3. **Реализовать подготовленные запросы** - Для оптимальной производительности.
+4. **Добавить логику маршрутизации таблиц** - Направлять запросы к оптимальным таблицам.
+5. **Реализовать удаление коллекций** - Читать из triples_collection, пакетно удалять из всех таблиц.
+
+#### Фаза 2: Оптимизация методов запросов
+1. **Переписать каждый метод get_*** для использования оптимальной таблицы.
+2. **Удалить все случаи использования ALLOW FILTERING**.
+3. **Реализовать эффективное использование ключей кластеризации**.
+4. **Добавить логирование производительности запросов**.
+
+#### Фаза 3: Управление коллекциями
+1. **Обновить `delete_collection()`** - Удалить из всех трех таблиц.
+2. **Добавить проверку согласованности** - Обеспечить синхронизацию всех таблиц.
+3. **Реализовать пакетные операции** - Для атомарных операций с несколькими таблицами.
+
+### Ключевые детали реализации
+
+#### Стратегия пакетной записи
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### Логика маршрутизации запросов
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### Логика удаления коллекции
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### Оптимизация подготовленных выражений
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## Стратегия миграции
+
+### Подход к миграции данных
+
+#### Вариант 1: Развертывание Blue-Green (Рекомендуется)
+1. **Разверните новую схему параллельно с существующей** - Временно используйте разные имена таблиц.
+2. **Период двойной записи** - Записывайте данные как в старую, так и в новую схемы во время перехода.
+3. **Фоновая миграция** - Скопируйте существующие данные в новые таблицы.
+4. **Перенаправление операций чтения** - Направляйте запросы к новым таблицам после миграции данных.
+5. **Удаление старых таблиц** - После периода проверки.
+
+#### Вариант 2: Миграция на месте
+1. **Добавление схемы** - Создайте новые таблицы в существующем пространстве ключей.
+2. **Скрипт миграции данных** - Пакетная копия из старой таблицы в новые таблицы.
+3. **Обновление приложения** - Разверните новый код после завершения миграции.
+4. **Очистка старой таблицы** - Удалите старую таблицу и индексы.
+
+### Обратная совместимость
+
+#### Стратегия развертывания
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### Скрипт миграции
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### Стратегия проверки
+
+#### Проверки согласованности данных
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## Стратегия тестирования
+
+### Тестирование производительности
+
+#### Сценарии для бенчмаркинга
+1. **Сравнение производительности запросов**
+   Показатели производительности до и после для всех 8 типов запросов
+   Акцент на улучшении производительности запроса `get_po` (удаление `ALLOW FILTERING`)
+   Измерение задержки запросов при различных объемах данных
+
+2. **Тестирование нагрузки**
+   Одновременное выполнение запросов
+   Скорость записи с использованием пакетных операций
+   Использование памяти и ЦП
+
+3. **Тестирование масштабируемости**
+   Производительность при увеличении размеров коллекций
+   Распределение запросов по нескольким коллекциям
+   Использование узлов кластера
+
+#### Наборы тестовых данных
+**Маленький:** 10 тысяч троек на коллекцию
+**Средний:** 100 тысяч троек на коллекцию
+**Большой:** 1 миллион и более троек на коллекцию
+**Несколько коллекций:** Тестирование распределения партиций
+
+### Функциональное тестирование
+
+#### Обновления модульных тестов
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### Обновления результатов интеграционного тестирования
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### План отката
+
+#### Быстрая стратегия отката
+1. **Переключение переменной окружения** - Немедленный возврат к устаревшим таблицам.
+2. **Сохранение устаревших таблиц** - Не удалять до тех пор, пока производительность не будет подтверждена.
+3. **Сигналы мониторинга** - Автоматический запуск отката на основе показателей ошибок/задержек.
+
+#### Проверка отката
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## Риски и соображения
+
+### Риски производительности
+**Увеличение времени записи** - 4 операции записи на каждую вставку (на 33% больше, чем при использовании 3-х таблиц)
+**Избыточность хранения** - В 4 раза больше места для хранения (на 33% больше, чем при использовании 3-х таблиц)
+**Сбои пакетной записи** - Требуется правильная обработка ошибок
+**Сложность удаления** - Удаление коллекции требует цикла "чтение-удаление"
+
+### Операционные риски
+**Сложность миграции** - Миграция данных для больших наборов данных
+**Проблемы с согласованностью** - Обеспечение синхронизации всех таблиц
+**Недостаточность мониторинга** - Необходимы новые метрики для операций с несколькими таблицами
+
+### Стратегии смягчения
+1. **Постепенное внедрение** - Начните с небольших коллекций
+2. **Комплексный мониторинг** - Отслеживайте все метрики производительности
+3. **Автоматизированная проверка** - Постоянная проверка согласованности
+4. **Возможность быстрого отката** - Выбор таблицы на основе среды
+
+## Критерии успеха
+
+### Улучшения производительности
+[ ] **Устранение ALLOW FILTERING** - Запросы get_po и get_os выполняются без фильтрации
+[ ] **Сокращение задержки запросов** - Улучшение времени отклика запросов на 50% или более
+[ ] **Более равномерное распределение нагрузки** - Отсутствие "горячих" партиций, равномерная нагрузка на узлы кластера
+[ ] **Масштабируемая производительность** - Время запроса пропорционально размеру результата, а не общему объему данных
+
+### Функциональные требования
+[ ] **Совместимость API** - Весь существующий код продолжает работать без изменений
+[ ] **Согласованность данных** - Все три таблицы остаются синхронизированными
+[ ] **Отсутствие потери данных** - Миграция сохраняет все существующие тройки
+[ ] **Обратная совместимость** - Возможность отката к устаревшей схеме
+
+### Операционные требования
+[ ] **Безопасная миграция** - Развертывание по принципу "синий-зеленый" с возможностью отката
+[ ] **Покрытие мониторингом** - Комплексные метрики для операций с несколькими таблицами
+[ ] **Покрытие тестами** - Все шаблоны запросов протестированы с использованием эталонных показателей производительности
+[ ] **Документация** - Обновленные процедуры развертывания и эксплуатации
+
+## План
+
+### Фаза 1: Реализация
+[ ] Переписать `cassandra_kg.py` с использованием схемы нескольких таблиц
+[ ] Реализовать пакетные операции записи
+[ ] Добавить оптимизацию с использованием подготовленных выражений
+[ ] Обновить модульные тесты
+
+### Фаза 2: Интеграционное тестирование
+[ ] Обновить интеграционные тесты
+[ ] Эталонное тестирование производительности
+[ ] Тестирование нагрузки с использованием реалистичных объемов данных
+[ ] Скрипты проверки согласованности данных
+
+### Фаза 3: Планирование миграции
+[ ] Скрипты развертывания по принципу "синий-зеленый"
+[ ] Инструменты миграции данных
+[ ] Обновления панели мониторинга
+[ ] Процедуры отката
+
+### Фаза 4: Развертывание в производственной среде
+[ ] Поэтапное развертывание в производственной среде
+[ ] Мониторинг и проверка производительности
+[ ] Очистка устаревших таблиц
+[ ] Обновление документации
+
+## Заключение
+
+Эта стратегия денормализации с использованием нескольких таблиц напрямую решает две критические проблемы производительности:
+
+1. **Устраняет дорогостоящий ALLOW FILTERING**, предоставляя оптимальные структуры таблиц для каждого шаблона запроса
+2. **Улучшает эффективность кластеризации** за счет составных ключей партиций, которые правильно распределяют нагрузку
+
+Этот подход использует сильные стороны Cassandra, сохраняя при этом полную совместимость API, что обеспечивает автоматическое получение преимуществ от улучшений производительности для существующего кода.

docs/tech-specs/cassandra-performance-refactor.sw.md

@@ -0,0 +1,679 @@
+# Maelezo ya Kiufundi: Uboreshaji wa Utendaji wa Hifadhidata ya Maarifa ya Cassandra
+
+**Hali:** Rasimu
+**Mwandishi:** Msaidizi
+**Tarehe:** 2025-09-18
+
+## Muhtasari
+
+Maelezo haya yanashughulikia masuala ya utendaji katika utekelezaji wa hifadhidata ya maarifa ya TrustGraph ya Cassandra na yanapendekeza uboreshaji kwa uhifadhi na utafutaji wa data ya RDF.
+
+## Utendaji wa Sasa
+
+### Muundo wa Skimu
+
+Utendaji wa sasa hutumia muundo wa jedwali moja katika `trustgraph-flow/trustgraph/direct/cassandra_kg.py`:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**Faharasa Pili:**
+`triples_s` KWA `s` (somo)
+`triples_p` KWA `p` (kitenzi)
+`triples_o` KWA `o` (kielele)
+
+### Mifumo ya Umasiliano
+
+Utaratibu wa sasa unaoendeshwa unao na mifumo 8 tofauti ya masiliano:
+
+1. **get_all(mkusanyiko, kikomo=50)** - Pata vitriple vyote kwa mkusanyiko
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - Utafiti kwa mada.
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - Utafiti kwa kutumia vigezo.
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - Utafiti kwa kutumia kitu.
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - Utafiti kwa mada + predikati
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - Utafiti kwa kutumia vigezo na kitu ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - Utafiti kwa kutumia kitu pamoja na mada ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - Mechi kamili ya triple.
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### Muundo wa Sasa
+
+**Faili: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+Darasa moja la `KnowledgeGraph` linaloshughulikia shughuli zote
+Uunganisho wa kikundi kupitia orodha ya kimataifa ya `_active_clusters`
+Jina la jedwali lililobainishwa: `"triples"`
+Spishi kwa kila mfumo wa mtumiaji
+Nakala ya SimpleStrategy kwa sababu 1
+
+**Maeneo ya Uunganisho:**
+**Njia ya Kuandika:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**Njia ya Umasilisho:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**Hifadhi ya Maarifa:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## Matatizo ya Utendaji Yanayobainika
+
+### Matatizo ya Ngazi ya Muundo
+
+1. **Muundo Usiofaa wa Ufunguo Mkuu**
+   Sasa: `PRIMARY KEY (collection, s, p, o)`
+   Hupelekea uwekaji duni wa data kwa mifumo ya kawaida ya ufikiaji
+   Inahitaji matumizi ya gharama kubwa ya fahirisi za sekondari
+
+2. **Matumizi Mengi ya Fahirisi za Sekondari** ⚠️
+   Fahirisi tatu za sekondari kwenye safu zenye maadili mengi (s, p, o)
+   Fahirisi za sekondari katika Cassandra ni ghali na hazipunguzi kasi vizuri
+   Maswali 6 na 7 yanahitaji `ALLOW FILTERING`, ambayo inaonyesha muundo duni wa data
+
+3. **Hatari ya Sehemu Zenye Trafiki Kubwa**
+   Ufunguo mmoja wa sehemu `collection` unaweza kuunda sehemu zenye trafiki kubwa
+   Mkusanyiko mkubwa utajikuta katika nodi moja
+   Hakuna mkakati wa usambazaji wa mizigo
+
+### Matatizo ya Ngazi ya Umasilisho
+
+1. **Matumizi ya ALLOW FILTERING** ⚠️
+   Aina mbili za maswali (get_po, get_os) zinahitaji `ALLOW FILTERING`
+   Maswali haya husifia sehemu nyingi na ni ghali sana
+   Utendaji unapungua kwa kasi kadri ya ukubwa wa data
+
+2. **Mifumo ya Ufikiaji Yasiyo na Ufanisi**
+   Hakuna uboreshaji kwa mifumo ya kawaida ya maswali ya RDF
+   Hakuna fahirisi za pamoja kwa mchanganyiko wa maswali unaoonekana mara kwa mara
+   Hakuna utambuzi wa mifumo ya utaftaji wa grafu
+
+3. **Ukosefu wa Uboreshaji wa Umasilisho**
+   Hakuna kuhifadhi kwa masimulizi yaliyotayarishwa
+   Hakuna vidokezo au mikakati ya uboreshaji wa maswali
+   Hakuna utambuzi wa upangishaji zaidi ya LIMIT rahisi
+
+## Taarifa ya Tatizo
+
+Utekelezaji wa sasa wa hifadhi ya maarifa ya Cassandra una matatizo mawili muhimu ya utendaji:
+
+### 1. Utendaji Usio na Ufanisi wa Maswali ya get_po
+
+Swali la `get_po(collection, p, o)` halipunguzi kasi kwa sababu linahitaji `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**Sababu ya kuwa hii ni tatizo:**
+`ALLOW FILTERING` inalazimisha Cassandra kuchanganua kila sehemu ndani ya mkusanyiko.
+Utendaji hupungua kwa mstari sawa na ukubwa wa data.
+Hii ni muundo wa kawaida wa swali la RDF (kutafuta vitu ambavyo vina uhusiano maalum wa tabia-jambo).
+Huunda mzigo mkubwa kwenye kundi kadri data inavyoongezeka.
+
+### 2. Mkakati Usiofaa wa Uwekaji Pamoja
+
+Ufunguo mkuu wa sasa `PRIMARY KEY (collection, s, p, o)` hutoa faida ndogo katika uwekaji pamoja:
+
+**Matatizo na uwekaji pamoja wa sasa:**
+`collection` kama funguo ya sehemu haisambati data kwa ufanisi.
+Makusanyiko mengi yana data tofauti, na kuifanya uwekaji pamoja kuwa usiofaa.
+Hakuna utambuzi kwa mifumo ya kawaida ya ufikiaji katika maswali ya RDF.
+Makusanyiko makubwa huunda sehemu zenye mzigo mwingi kwenye nodi moja.
+Safu za uwekaji pamoja (s, p, o) haziboreshi kwa mifumo ya kawaida ya utaftaji wa grafu.
+
+**Athari:**
+Maswali hayanapata faida kutoka kwa ukaribu wa data.
+Matumizi duni ya kumbukumbu (cache).
+Usambazaji usio sawa wa mzigo katika nodi za kundi.
+Zuio la uwezo wa kupanuka (scalability) kadri makusanyiko yanavyoongezeka.
+
+## Suluhisho Lililopendekezwa: Mkakati wa Utofauti wa Jedwali 4
+
+### Muhtasari
+
+Badilisha jedwali moja `triples` na jedwali nne zilizoundwa kwa madhumuni maalum, kila moja iliyoboreshwa kwa mifumo maalum ya swali. Hii inafutilia hitaji la fahirisi za sekondari na ALLOW FILTERING huku ikiwapa utendaji bora kwa aina zote za swali. Jedwali la nne linaruhusu uondoaji wa makusanyiko kwa ufanisi licha ya funguo za sehemu zilizounganishwa.
+
+### Muundo Mpya wa Skimu
+
+**Jedwali la 1: Maswali Yanayozingatia Sijali (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**Inaboresha:** get_s, get_sp, get_os
+**Ufunguo wa Sehemu:** (mkusanyiko, s) - Usambazaji bora kuliko mkusanyiko pekee
+**Kukusanya:** (p, o) - Huwezesha utafutaji wa ufanisi wa vigezo/vitendo kwa ajili ya somo
+
+**Jedwali 2: Maswali ya Vigezo-Vitendo (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**Inaboresha:** get_p, get_po (inabadilisha ALLOW FILTERING!)
+**Ufunguo wa Sehemu:** (mkusanyiko, p) - Ufikiaji wa moja kwa moja kupitia kigezo.
+**Kukusanyika:** (o, s) - Ufuatiliaji wa vitu na masomo unaofaa.
+
+**Jedwali la 3: Maswali Yanayozingatia Vitu (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**Inaboresha:** get_o
+**Ufunguo wa Sehemu:** (mkusanyiko, o) - Ufikiaji wa moja kwa moja kwa kutumia kitu
+**Kukusanya:** (s, p) - Ufuatiliaji wa ufanisi wa somo-tabia
+
+**Jedwali la 4: Usimamizi wa Mkusaniko na Maswali ya SPO (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**Inaboresha:** get_spo, delete_collection
+**Ufunguo wa Sehemu (Partition Key):** mkusanyiko pekee - Huwezesha operesheni bora za kiwango cha mkusanyiko.
+**Kukusanyika (Clustering):** (s, p, o) - Mpangilio wa kawaida wa triple.
+**Madhumuni:** Matumizi mawili, kwa utafutaji sahihi wa SPO na kama faharasa ya kufuta.
+
+### Ramani ya Utafutaji (Query Mapping)
+
+| Utafutaji Asili | Jedwali Linalolengwa | Ubora wa Kuboresha |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | RUHASA YA KUCHANUA (inayokubalika kwa skani) |
+| get_s(collection, s) | triples_s | Ufikiaji wa moja kwa moja wa sehemu. |
+| get_p(collection, p) | triples_p | Ufikiaji wa moja kwa moja wa sehemu. |
+| get_o(collection, o) | triples_o | Ufikiaji wa moja kwa moja wa sehemu. |
+| get_sp(collection, s, p) | triples_s | Sehemu + kukusanyika. |
+| get_po(collection, p, o) | triples_p | **HAKUNA tena RUHASA LA KUCHANUA!** |
+| get_os(collection, o, s) | triples_o | Sehemu + kukusanyika. |
+| get_spo(collection, s, p, o) | triples_collection | Utafutaji wa ufunguo wa moja kwa moja. |
+| delete_collection(collection) | triples_collection | Soma faharasa, futa kwa wingi. |
+
+### Mkakati wa Kufuta Mkusaniko
+
+Pamoja na ufunguo wa sehemu mchanganyiko, hatuwezi tu kutekeleza `DELETE FROM table WHERE collection = ?`. Badala yake:
+
+1. **Awamu ya Kusoma:** Tafuta `triples_collection` ili kuorodhesha triple zote:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   Hii ni bora kwa sababu `collection` ndiyo ufunguo wa kundi kwa jedwali hili.
+
+2. **Awamu ya Ufutilishaji:** Kwa kila seti tatu (s, p, o), futa kutoka kwenye meza zote 4 kwa kutumia ufunguo kamili wa kundi:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   Imefunganishwa katika makundi ya 100 ili kuongeza ufanisi.
+
+**Uchambuzi wa Usawa:**
+✅ Inaendelea kudumisha utendaji bora wa maswali kwa kutumia vipande vilivyogawanywa.
+✅ Hakuna vipande ambavyo hupita kasi kwa makusanyo makubwa.
+❌ Mantiki ya kufuta ni ngumu zaidi (soma kisha futa).
+❌ Muda wa kufuta unalingana na ukubwa wa mkusanyiko.
+
+### Faida
+
+1. **Inaondoa ALLOW FILTERING** - Kila swali lina njia bora ya kufikia (isipokuwa skani ya get_all).
+2. **Hakuna Faharasa za Pili** - Kila jedwali NI faharasa kwa mtindo wake wa swali.
+3. **Usambazaji Bora wa Data** - Funguo za pamoja za kugawanya zinapanua mzigo kwa ufanisi.
+4. **Utendaji Unaoweza Kushawishiwa** - Muda wa swali unalingana na ukubwa wa matokeo, sio data jumla.
+5. **Inatumia Nguvu za Cassandra** - Imeundwa kwa usanifu wa Cassandra.
+6. **Inaruhusu Ufuta wa Makusanyo** - triples_collection hutumika kama faharasa ya kufuta.
+
+## Mpango wa Utendaji
+
+### Faili Zinazohitaji Marekebisho
+
+#### Faili Kuu ya Utendaji
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Inahitajika kuandikwa upya kabisa.
+
+**Mbinu Zinazohitajika Kubadilishwa:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### Faili za Uunganishaji (Hakuna Mabadiliko ya Mantiki Yanayohitajika)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+Hakuna mabadiliko yanayohitajika - hutumia API ya KnowledgeGraph iliyopo
+Inafaidika moja kwa moja kutoka kwa uboreshaji wa utendaji
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+Hakuna mabadiliko yanayohitajika - hutumia API ya KnowledgeGraph iliyopo
+Inafaidika moja kwa moja kutoka kwa uboreshaji wa utendaji
+
+### Faili za Majaribio Zinazohitaji Mabadiliko
+
+#### Majaribio ya Kitengo
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+Sasisha matarajio ya majaribio kwa mabadiliko ya schema
+Ongeza majaribio kwa utangamano wa meza nyingi
+Hakikisha hakuna ALLOW FILTERING katika mipango ya swali
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+Sasisha madai ya utendaji
+Jaribu mifumo yote 8 ya swali dhidi ya meza mpya
+Hakikisha uelekezaji wa swali hadi meza sahihi
+
+#### Majaribio ya Uunganishaji
+**`tests/integration/test_cassandra_integration.py`**
+Majaribio ya mwisho na schema mpya
+Ulinganisho wa benchmarking wa utendaji
+Uthibitisho wa utangamano wa data katika meza
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+Sasisha majaribio ya uthibitisho wa schema
+Jaribu hali za uhamishaji
+
+### Mkakati wa Utendaji
+
+#### Awamu ya 1: Schema na Mbinu za Msingi
+1. **Andika upya mbinu ya `init()`** - Unda meza nne badala ya moja
+2. **Andika upya mbinu ya `insert()`** - Andika kwa wingi kwenye meza zote nne
+3. **Teleza taarifa zilizotayarishwa** - Kwa utendaji bora
+4. **Ongeza mantiki ya uelekezaji wa meza** - Elekeza maswali hadi meza bora
+5. **Teleza uondoaji wa mkusanyiko** - Soma kutoka kwa triples_collection, ondoa kwa wingi kutoka kwenye meza zote
+
+#### Awamu ya 2: Uboreshaji wa Mbinu ya Swali
+1. **Andika upya kila mbinu ya get_*** ili itumie meza bora
+2. **Ondoa matumizi yote ya ALLOW FILTERING**
+3. **Teleza matumizi bora ya ufunguo wa uwekaji**
+4. **Ongeza uandikaji wa utendaji wa swali**
+
+#### Awamu ya 3: Usimamizi wa Mkusaniko
+1. **Sasisha `delete_collection()`** - Ondoa kutoka kwenye meza zote tatu
+2. **Ongeza uthibitisho wa utangamano** - Hakikisha meza zote zinaendelea kuwa sawa
+3. **Teleza shughuli za wingi** - Kwa shughuli za meza nyingi za atomiki
+
+### Maelezo Muhimu ya Utendaji
+
+#### Mkakati wa Kuandika kwa Wingi
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### Mantiki ya Uelekezaji wa Maswali
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### Mantiki ya Ufutilishaji wa Mkusanyiko
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### Uboreshaji wa Matamshi Yaliyotayarishwa
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## Mkakati wa Uhamishaji
+
+### Mbinu ya Uhamishaji wa Data
+
+#### Chaguo la 1: Uwekaji wa Blue-Green (Inapendekezwa)
+1. **Weka mfumo mpya pamoja na mfumo uliopo** - Tumia majina tofauti ya jedwali kwa muda
+2. **Kipindi cha kuandika mara mbili** - Andika kwenye mifumo ya zamani na mipya wakati wa mabadiliko
+3. **Uhamishaji wa nyuma** - Nakili data iliyopo kwenye jedwali jipya
+4. **Badilisha maswali** - Elekeza maswali kwenye jedwali jipya baada ya uhamishaji wa data
+5. **Futa jedwali la zamani** - Baada ya kipindi cha uhakiki
+
+#### Chaguo la 2: Uhamishaji wa Moja kwa Moja
+1. **Kuongeza mfumo** - Unda jedwali jipya kwenye eneo la funguo lililopo
+2. **Skripti ya uhamishaji wa data** - Nakili kwa wingi kutoka kwenye jedwali la zamani hadi kwenye jedwali jipya
+3. **Sasisho la programu** - Weka programu mpya baada ya uhamishaji kukamilika
+4. **Kusafisha jedwali la zamani** - Ondoa jedwali la zamani na fahirisi
+
+### Utangamano wa Nyuma
+
+#### Mkakati wa Uwekaji
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### Skripti ya Uhamishaji
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### Mbinu ya Uthibitisho
+
+#### Vipimo vya Ulinganifu wa Data
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## Mbinu ya Majaribio
+
+### Majaribio ya Utendaji
+
+#### Hali za Majaribio ya Kiwango
+1. **Ulinganisho wa Utendaji wa Maswali**
+   Vipimo vya utendaji kabla na baada kwa aina zote 8 za maswali
+   Lenga uboreshaji wa utendaji wa `get_po` (ondoa `ALLOW FILTERING`)
+   Pima muda wa maswali chini ya saizi tofauti za data
+
+2. **Majaribio ya Upakiaji**
+   Utendaji wa maswali kwa wakati mmoja
+   Uwezo wa kuandika na shughuli za kikundi
+   Matumizi ya kumbukumbu na CPU
+
+3. **Majaribio ya Uwezo wa Kupanuka**
+   Utendaji na saizi zinazoongezeka za mkusanyiko
+   Usambazaji wa maswali ya mkusanyiko mwingi
+   Matumizi ya nodi za kundi
+
+#### Kijiko cha Majaribio
+**Kidogo:** 10K ya vitatu kwa kila mkusanyiko
+**Katikati:** 100K ya vitatu kwa kila mkusanyiko
+**Kubwa:** 1M+ ya vitatu kwa kila mkusanyiko
+**Mkusanyiko mwingi:** Jaribu usambazaji wa sehemu
+
+### Majaribio ya Utendaji
+
+#### Marekebisho ya Majaribio ya Kitengo
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### Sasisho la Mtihani wa Uunganishaji
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### Mpango wa Kurudisha Nyuma
+
+#### Mbinu ya Kurudisha Nyuma Haraka
+1. **Kubadili jenereta la mazingira** - Rudi kwenye jedwali la zamani mara moja
+2. **Endelea kutumia jedwali la zamani** - Usifute hadi utendaji uthibitishwe
+3. **Arifa za ufuatiliaji** - Vinjari vya kiotomatiki vya kurudisha nyuma kulingana na viwango vya makosa/uwezekano wa kuchelewesha
+
+#### Uthibitisho wa Kurudisha Nyuma
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## Hatari na Mambo ya Kuzingatia
+
+### Hatari za Utendaji
+**Kuongezeka kwa muda wa kuandika** - Operesheni 4 za kuandika kwa kila kuingiza (33% zaidi kuliko mfumo wa meza 3)
+**Uongezekaji wa matumizi ya nafasi** - Mahitaji 4 ya nafasi (33% zaidi kuliko mfumo wa meza 3)
+**Hitilafu za kuandika kwa wingi** - Inahitajika udhibiti wa makosa unaofaa
+**Uchaguzi wa kufuta** - Kufuta kwa mkusanyiko inahitaji mzunguko wa kusoma na kisha kufuta
+
+### Hatari za Uendeshaji
+**Uchaguzi wa uhamisho** - Uhamishaji wa data kwa data kubwa
+**Changamoto za utangamano** - Kuhakikisha meza zote zinaendelea kusawazishwa
+**Mapungufu ya ufuatiliaji** - Inahitajika metriki mpya kwa operesheni za meza nyingi
+
+### Mikakati ya Kupunguza Hatari
+1. **Uanzishaji wa hatua kwa hatua** - Anza na mkusanyiko mdogo
+2. **Ufuatiliaji kamili** - Fuatilia metriki zote za utendaji
+3. **Uthibitisho otomatiki** - Uchunguzi wa utangamano wa mara kwa mara
+4. **Uwezo wa kurejesha haraka** - Uchaguzi wa meza kulingana na mazingira
+
+## Vigezo vya Mafanikio
+
+### Maboresho ya Utendaji
+[ ] **Kuondoa ALLOW FILTERING** - Maswali ya `get_po` na `get_os` yanatumika bila kuchujwa
+[ ] **Kupunguza muda wa swali** - Kuboresha kwa 50% au zaidi katika muda wa majibu ya swali
+**Usambazaji bora wa mzigo** - Hakuna sehemu zenye mzigo mwingi, usambazaji sare katika kila nodi ya kundi
+[ ] **Utendaji unaoweza kuongezeka** - Muda wa swali unalingana na ukubwa wa matokeo, sio data jumla
+
+### Mahitaji ya Utendaji
+[ ] **Ulinganishaji wa API** - Msimbo wote uliopo unaendelea kufanya kazi bila mabadiliko
+[ ] **Utangamano wa data** - Meza zote tatu zinaendelea kusawazishwa
+[ ] **Hakuna upotevu wa data** - Uhamishaji unahifadhi triples zote zilizopo
+[ ] **Ulinganishaji wa nyuma** - Uwezo wa kurejea kwenye mpango wa zamani
+
+### Mahitaji ya Uendeshaji
+[ ] **Uhamisho salama** - Uanzishaji wa kijani na bluu na uwezo wa kurejesha
+[ ] **Mazingira ya ufuatiliaji** - Metri kamili kwa operesheni za meza nyingi
+[ ] **Mazingira ya majaribio** - Mfumo wote wa maswali umejaribiwa na viwango vya utendaji
+[ ] **Nyaraka** - Mbinu zilizosasishwa za uanzishaji na uendeshaji
+
+## Ratiba
+
+### Awamu ya 1: Utendaji
+[ ] Andika upya `cassandra_kg.py` na mpango wa meza nyingi
+[ ] Leta operesheni za kuandika kwa wingi
+[ ] Ongeza utendaji wa tamko lililoboreshwa
+[ ] Sasisha vipimo vya kitengo
+
+### Awamu ya 2: Majaribio ya Uunganisho
+[ ] Sasisha vipimo vya uunganisho
+[ ] Vipimo vya utendaji
+[ ] Majaribio ya mzigo na kiasi cha data ya kweli
+[ ] Skripti za uthibitisho wa utangamano wa data
+
+### Awamu ya 3: Upangaji wa Uhamishaji
+[ ] Skripti za uanzishaji wa kijani na bluu
+[ ] Zana za uhamishaji wa data
+[ ] Sasisho za dashibodi ya ufuatiliaji
+[ ] Taratibu za kurejesha
+
+### Awamu ya 4: Uanzishaji wa Uzalishaji
+[ ] Uanzishaji wa hatua kwa hatua katika uzalishaji
+[ ] Ufuatiliaji na uthibitisho wa utendaji
+[ ] Usafishaji wa meza za zamani
+[ ] Sasisho za nyaraka
+
+## Hitimisho
+
+Mbinu hii ya kupunguza data katika meza nyingi inashughulikia moja kwa moja matatizo mawili muhimu ya utendaji:
+
+1. **Inaondoa ALLOW FILTERING iliyogharimu** kwa kutoa miundo bora ya meza kwa kila mfumo wa swali
+2. **Inaboresha ufanisi wa uwekaji** kupitia ufunguo wa pamoja wa sehemu ambazo husambaza mzigo vizuri
+
+Mbinu hii inatumia nguvu za Cassandra huku ikiendelea kudumisha ulinganishaji kamili wa API, kuhakikisha kuwa msimbo uliopo unafaidika kiotomatiki kutoka kwa maboresho ya utendaji.

docs/tech-specs/cassandra-performance-refactor.tr.md

@@ -0,0 +1,679 @@
+# Teknik Özellikler: Cassandra Bilgi Tabanı Performans Yenilemesi
+
+**Durum:** Taslak
+**Yazar:** Yardımcı
+**Tarih:** 2025-09-18
+
+## Genel Bakış
+
+Bu özellik, TrustGraph Cassandra bilgi tabanı uygulamasındaki performans sorunlarına değinmekte ve RDF üçlü depolama ve sorgulama için optimizasyonlar önermektedir.
+
+## Mevcut Uygulama
+
+### Şema Tasarımı
+
+Mevcut uygulama, `trustgraph-flow/trustgraph/direct/cassandra_kg.py`'da tek bir tablo tasarımı kullanmaktadır:
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**İkincil İndeksler:**
+`triples_s` ON `s` (özne)
+`triples_p` ON `p` (yüklem)
+`triples_o` ON `o` (nesne)
+
+### Sorgu Desenleri
+
+Mevcut uygulama, 8 farklı sorgu desenini desteklemektedir:
+
+1. **get_all(collection, limit=50)** - Bir koleksiyon için tüm üçlüleri getirir.
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - Konuya göre sorgulama
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - Öznitelik kullanarak sorgulama
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - Nesneye göre sorgulama
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - Konu + yüklem ile sorgulama
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - Öznitelik + nesneye göre sorgulama ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - Nesne + konu ile sorgulama ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - Tam üçlü eşleşme
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### Mevcut Mimari
+
+**Dosya: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+Tüm işlemleri yöneten tek `KnowledgeGraph` sınıfı
+Küresel `_active_clusters` listesi aracılığıyla bağlantı havuzu
+Sabit tablo adı: `"triples"`
+Kullanıcı modeli başına keyspace
+Faktörü 1 olan SimpleStrategy replikasyonu
+
+**Entegrasyon Noktaları:**
+**Yazma Yolu:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**Sorgu Yolu:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**Bilgi Deposu:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## Tespit Edilen Performans Sorunları
+
+### Şema Seviyesi Sorunlar
+
+1. **Verimsiz Birincil Anahtar Tasarımı**
+   Mevcut: `PRIMARY KEY (collection, s, p, o)`
+   Sık erişim kalıpları için zayıf kümelenmeye neden olur
+   Pahalı ikincil indeks kullanımını zorlar
+
+2. **İkincil İndeks Aşırı Kullanımı** ⚠️
+   Yüksek kardinaliteli sütunlarda (s, p, o) üç ikincil indeks
+   Cassandra'daki ikincil indeksler pahalıdır ve iyi ölçeklenmez
+   6 ve 7 numaralı sorgular `ALLOW FILTERING` gerektirir, bu da zayıf veri modellemesini gösterir
+
+3. **Sıcak Bölüm Riski**
+   Tek bölüm anahtarı `collection`, sıcak bölümlere neden olabilir
+   Büyük koleksiyonlar tek düğümlere yoğunlaşacaktır
+   Yük dengeleme için dağıtım stratejisi yoktur
+
+### Sorgu Seviyesi Sorunlar
+
+1. **ALLOW FILTERING Kullanımı** ⚠️
+   İki sorgu türü (get_po, get_os) `ALLOW FILTERING` gerektirir
+   Bu sorgular birden fazla bölümü tarar ve son derece pahalıdır
+   Performans, veri boyutuyla doğrusal olarak düşer
+
+2. **Verimsiz Erişim Kalıpları**
+   Yaygın RDF sorgu kalıpları için optimizasyon yoktur
+   Sık sorgu kombinasyonları için bileşik indeksler eksiktir
+   Grafik geçiş kalıpları dikkate alınmamıştır
+
+3. **Sorgu Optimizasyonu Eksikliği**
+   Hazırlanmış ifade önbelleği yok
+   Sorgu ipuçları veya optimizasyon stratejileri yok
+   Basit LIMIT'in ötesinde sayfalama dikkate alınmamıştır
+
+## Problem Tanımı
+
+Mevcut Cassandra bilgi tabanı uygulaması, iki kritik performans darboğazına sahiptir:
+
+### 1. Verimsiz get_po Sorgusu Performansı
+
+`get_po(collection, p, o)` sorgusu, `ALLOW FILTERING` gerektirdiği için son derece verimsizdir:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**Neden bunun sorunlu olduğu:**
+`ALLOW FILTERING`, Cassandra'nın koleksiyon içindeki tüm bölümleri taramasını zorlar.
+Performans, veri boyutuyla doğrusal olarak düşer.
+Bu, yaygın bir RDF sorgu desenidir (belirli bir öznelik-nesne ilişkisine sahip konuları bulmak).
+Veri büyüdükçe kümede önemli bir yük oluşturur.
+
+### 2. Kötü Kümeleme Stratejisi
+
+Mevcut birincil anahtar `PRIMARY KEY (collection, s, p, o)`, minimum kümeleme faydası sağlar:
+
+**Mevcut kümeleme ile ilgili sorunlar:**
+Bölüm anahtarı olarak `collection`, verileri etkili bir şekilde dağıtmaz.
+Çoğu koleksiyon, kümelemeyi etkisiz hale getiren çeşitli veriler içerir.
+RDF sorgularındaki yaygın erişim kalıpları dikkate alınmamıştır.
+Büyük koleksiyonlar, tek düğümlerde "sıcak" bölümler oluşturur.
+Kümeleme sütunları (s, p, o), tipik grafik geçiş kalıpları için optimize edilmemiştir.
+
+**Etkisi:**
+Sorgular, veri yerelliğinden faydalanmaz.
+Kötü önbellek kullanımı.
+Küme düğümleri arasında düzensiz yük dağılımı.
+Koleksiyonlar büyüdükçe ölçeklenebilirlik darboğazları.
+
+## Önerilen Çözüm: 4-Tablolu Normalizasyon Stratejisi
+
+### Genel Bakış
+
+Tek `triples` tablosunu, belirli sorgu kalıpları için optimize edilmiş dört özel amaçlı tabloyla değiştirin. Bu, ikincil dizinlere ve ALLOW FILTERING'e olan ihtiyacı ortadan kaldırırken, tüm sorgu türleri için optimum performans sağlar. Dördüncü tablo, bileşik bölüm anahtarlarına rağmen verimli koleksiyon silme olanağı sağlar.
+
+### Yeni Şema Tasarımı
+
+**Tablo 1: Konu Odaklı Sorgular (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**Optimize eder:** get_s, get_sp, get_os
+**Bölüm Anahtarı:** (collection, s) - Yalnızca collection'dan daha iyi dağılım sağlar
+**Kümeleme:** (p, o) - Bir konu için verimli öznelik/nesne aramalarını sağlar
+
+**Tablo 2: Öznelik-Nesne Sorguları (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**Optimize eder:** get_p, get_po (ALLOW FILTERING özelliğini ortadan kaldırır!)
+**Bölüm Anahtarı:** (collection, p) - Öznitelik yoluyla doğrudan erişim
+**Kümeleme:** (o, s) - Verimli nesne-özne geçişi
+
+**Tablo 3: Nesne Odaklı Sorgular (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**Optimize eder:** get_o
+**Bölüm Anahtarı:** (collection, o) - Nesneye doğrudan erişim
+**Kümeleme:** (s, p) - Verimli özne-yüklem geçişi
+
+**Tablo 4: Koleksiyon Yönetimi ve SPO Sorguları (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**Optimize eder:** get_spo, delete_collection
+**Bölüm Anahtarı:** sadece koleksiyon - Verimli koleksiyon seviyesindeki işlemleri sağlar.
+**Kümeleme:** (s, p, o) - Standart üçlü sıralama
+**Amaç:** Hem tam SPO aramaları için hem de silme indeksi olarak çift amaçlı kullanım.
+
+### Sorgu Eşlemesi
+
+| Orijinal Sorgu | Hedef Tablo | Performans İyileştirmesi |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | FİLTRELEME İZNİ VERİLEBİLİR (taramaya uygun) |
+| get_s(collection, s) | triples_s | Doğrudan bölüm erişimi |
+| get_p(collection, p) | triples_p | Doğrudan bölüm erişimi |
+| get_o(collection, o) | triples_o | Doğrudan bölüm erişimi |
+| get_sp(collection, s, p) | triples_s | Bölüm + kümeleme |
+| get_po(collection, p, o) | triples_p | **Artık FİLTRELEME İZNİ YOK!** |
+| get_os(collection, o, s) | triples_o | Bölüm + kümeleme |
+| get_spo(collection, s, p, o) | triples_collection | Tam anahtar araması |
+| delete_collection(collection) | triples_collection | İndeksi oku, tümünü toplu olarak sil |
+
+### Koleksiyon Silme Stratejisi
+
+Birleşik bölüm anahtarlarıyla, `DELETE FROM table WHERE collection = ?`'ı doğrudan çalıştıramayız. Bunun yerine:
+
+1. **Okuma Aşaması:** Tüm üçlüleri saymak için `triples_collection` sorgusunu kullanın:
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   Bu, `collection`'ın bu tablo için bölümleme anahtarı olması nedeniyle verimlidir.
+
+2. **Silme Aşaması:** Her (s, p, o) üçlüsü için, tüm 4 tablodan, tam bölümleme anahtarlarını kullanarak silin:
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   Verimlilik için 100'lük gruplar halinde işlenir.
+
+**Ayrılık Analizi:**
+✅ Dağıtılmış bölümlerle optimum sorgu performansını korur.
+✅ Büyük koleksiyonlar için "sıcak" bölümler yoktur.
+❌ Daha karmaşık silme mantığı (okuyup sonra sil).
+❌ Silme süresi, koleksiyon boyutuna orantılıdır.
+
+### Avantajlar
+
+1. **ALLOW FILTERING'i ortadan kaldırır** - Her sorgunun optimum bir erişim yolu vardır (get_all taraması hariç).
+2. **İkincil İndeks Yok** - Her tablo, kendi sorgu deseninin indeksidir.
+3. **Daha İyi Veri Dağılımı** - Bileşik bölüm anahtarları, yükü etkili bir şekilde dağıtır.
+4. **Öngörülebilir Performans** - Sorgu süresi, toplam veriye değil, sonuç boyutuna orantılıdır.
+5. **Cassandra'nın Güçlerinden Yararlanır** - Cassandra'nın mimarisi için tasarlanmıştır.
+6. **Koleksiyon Silme İşlemini Etkinleştirir** - triples_collection, silme indeksi olarak hizmet eder.
+
+## Uygulama Planı
+
+### Değiştirilmesi Gereken Dosyalar
+
+#### Birincil Uygulama Dosyası
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Tamamen yeniden yazılması gerekir.
+
+**Yeniden Düzenlenmesi Gereken Mevcut Yöntemler:**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### Entegrasyon Dosyaları (Herhangi Bir Mantıksal Değişiklik Gerekmiyor)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+Herhangi bir değişiklik gerekmiyor - mevcut KnowledgeGraph API'sini kullanır.
+Performans iyileştirmelerinden otomatik olarak faydalanır.
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+Herhangi bir değişiklik gerekmiyor - mevcut KnowledgeGraph API'sini kullanır.
+Performans iyileştirmelerinden otomatik olarak faydalanır.
+
+### Güncelleme Gerektiren Test Dosyaları
+
+#### Birim Testleri
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+Şema değişiklikleri için test beklentilerini güncelleyin.
+Çok tablolu tutarlılık için testler ekleyin.
+Sorgu planlarında ALLOW FILTERING kullanımını doğrulayın.
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+Performans doğrulama ifadelerini güncelleyin.
+Tüm 8 sorgu desenini yeni tablolara karşı test edin.
+Sorgu yönlendirmesinin doğru tablolara yapıldığını doğrulayın.
+
+#### Entegrasyon Testleri
+**`tests/integration/test_cassandra_integration.py`**
+Yeni şemayla uçtan uca testler.
+Performans karşılaştırma ölçümleri.
+Tablolar arasındaki veri tutarlılığının doğrulanması.
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+Şema doğrulama testlerini güncelleyin.
+Geçiş senaryolarını test edin.
+
+### Uygulama Stratejisi
+
+#### 1. Aşama: Şema ve Temel Yöntemler
+1. **`init()` yöntemini yeniden yazın** - Dört tablo oluşturun, bir yerine.
+2. **`insert()` yöntemini yeniden yazın** - Tüm dört tabloya toplu yazma işlemleri.
+3. **Hazırlanmış ifadeleri uygulayın** - Optimum performans için.
+4. **Tablo yönlendirme mantığını ekleyin** - Sorguları en uygun tablolara yönlendirin.
+5. **Toplu silme işlemini uygulayın** - triples_collection'dan okuyun, tüm tablolardan toplu olarak silin.
+
+#### 2. Aşama: Sorgu Yöntemi Optimizasyonu
+1. **Her get_* yöntemini yeniden yazın** - En uygun tabloyu kullanmak için.
+2. **Tüm ALLOW FILTERING kullanımını kaldırın**.
+3. **Verimli kümeleme anahtar kullanımı uygulayın**.
+4. **Sorgu performansını kaydetme özelliğini ekleyin**.
+
+#### 3. Aşama: Koleksiyon Yönetimi
+1. **`delete_collection()`'ı güncelleyin** - Tüm üç tablodan kaldırın.
+2. **Tutarlılık doğrulamasını ekleyin** - Tüm tabloların senkronize kalmasını sağlayın.
+3. **Toplu işlemleri uygulayın** - Atomik çok tablolu işlemler için.
+
+### Önemli Uygulama Detayları
+
+#### Toplu Yazma Stratejisi
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### Sorgu Yönlendirme Mantığı
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### Koleksiyon Silme Mantığı
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### Hazırlanmış İfade Optimizasyonu
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## Göç Stratejisi
+
+### Veri Göç Yaklaşımı
+
+#### Seçenek 1: Mavi-Yeşil Dağıtım (Önerilen)
+1. **Yeni şemayı mevcut olanın yanında dağıtın** - Geçici olarak farklı tablo adları kullanın
+2. **Çift yazma dönemi** - Geçiş sırasında hem eski hem de yeni şemalara yazın
+3. **Arka planda veri taşıma** - Mevcut verileri yeni tablolara kopyalayın
+4. **Okuma yönlendirmesini değiştirin** - Veriler taşındıktan sonra sorguları yeni tablolara yönlendirin
+5. **Eski tabloları kaldırın** - Doğrulama süresinden sonra
+
+#### Seçenek 2: Yerinde Göç
+1. **Şema ekleme** - Yeni tabloları mevcut anahtar uzayında oluşturun
+2. **Veri taşıma betiği** - Eski tablodan yeni tablolara toplu olarak veri kopyalayın
+3. **Uygulama güncellemesi** - Göç tamamlandıktan sonra yeni kodu dağıtın
+4. **Eski tablo temizliği** - Eski tabloyu ve indeksleri kaldırın
+
+### Geriye Dönük Uyumluluk
+
+#### Dağıtım Stratejisi
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### Göç Script'i
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### Doğrulama Stratejisi
+
+#### Veri Tutarlılık Kontrolleri
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## Test Stratejisi
+
+### Performans Testi
+
+#### Benchmark Senaryoları
+1. **Sorgu Performansı Karşılaştırması**
+   Tüm 8 sorgu türü için performans metrikleri (önce/sonra)
+   get_po performans iyileştirmesine odaklanın (ALLOW FILTERING'i kaldırın)
+   Çeşitli veri boyutları altında sorgu gecikmesini ölçün
+
+2. **Yük Testi**
+   Eşzamanlı sorgu yürütme
+   Toplu işlemlerle yazma hızı
+   Bellek ve CPU kullanımı
+
+3. **Ölçeklenebilirlik Testi**
+   Artan koleksiyon boyutlarıyla performans
+   Çoklu koleksiyon sorgu dağıtımı
+   Küme düğümü kullanımı
+
+#### Test Veri Kümeleri
+**Küçük:** Koleksiyon başına 10K üçlü
+**Orta:** Koleksiyon başına 100K üçlü
+**Büyük:** Koleksiyon başına 1M+ üçlü
+**Çoklu koleksiyonlar:** Test bölüm dağıtımı
+
+### Fonksiyonel Test
+
+#### Birim Testi Güncellemeleri
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### Entegrasyon Testi Güncellemeleri
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### Geri Alma Planı
+
+#### Hızlı Geri Alma Stratejisi
+1. **Ortam değişkeni geçişi** - Eski tablolara hemen geri dönün.
+2. **Eski tablolara devam edin** - Performans kanıtlanana kadar silmeyin.
+3. **İzleme uyarıları** - Hata oranlarına/gecikmelere göre otomatik geri alma tetikleyicileri.
+
+#### Geri Alma Doğrulama
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## Riskler ve Dikkat Edilmesi Gerekenler
+
+### Performans Riskleri
+**Yazma gecikmesi artışı** - Her eklemeye 4 yazma işlemi (3 tablolu yaklaşıma göre %33 daha fazla)
+**Depolama alanı kullanımı** - 4 kat daha fazla depolama alanı gereksinimi (3 tablolu yaklaşıma göre %33 daha fazla)
+**Toplu yazma hataları** - Uygun hata yönetimi gereklidir
+**Silme karmaşıklığı** - Koleksiyon silme işlemi, okuma-sonra-silme döngüsü gerektirir
+
+### İşletim Riskleri
+**Geçiş karmaşıklığı** - Büyük veri kümeleri için veri geçişi
+**Tutarlılık sorunları** - Tüm tabloların senkronize olduğundan emin olmak
+**İzleme eksiklikleri** - Çok tablolu işlemler için yeni metrikler gereklidir
+
+### Azaltma Stratejileri
+1. **Aşamalı dağıtım** - Küçük koleksiyonlarla başlayın
+2. **Kapsamlı izleme** - Tüm performans metriklerini takip edin
+3. **Otomatik doğrulama** - Sürekli tutarlılık kontrolü
+4. **Hızlı geri alma yeteneği** - Ortam tabanlı tablo seçimi
+
+## Başarı Kriterleri
+
+### Performans İyileştirmeleri
+[ ] **ALLOW FILTERING'i ortadan kaldırın** - get_po ve get_os sorguları filtreleme olmadan çalışır
+[ ] **Sorgu gecikmesi azaltma** - Sorgu yanıt sürelerinde %50 veya daha fazla iyileşme
+[ ] **Daha iyi yük dağılımı** - Hiçbir "sıcak" bölüm yok, küme düğümleri arasında eşit yük dağılımı
+[ ] **Ölçeklenebilir performans** - Sorgu süresi, toplam veri miktarı yerine sonuç büyüklüğüne orantılı
+
+### Fonksiyonel Gereksinimler
+[ ] **API uyumluluğu** - Tüm mevcut kod, herhangi bir değişiklik olmadan çalışmaya devam eder
+[ ] **Veri tutarlılığı** - Tüm üç tablo senkronize kalır
+[ ] **Sıfır veri kaybı** - Geçiş, tüm mevcut üçlüleri korur
+[ ] **Geriye dönme uyumluluğu** - Eski şemaya geri dönme yeteneği
+
+### İşletim Gereksinimleri
+[ ] **Güvenli geçiş** - Geri alma yeteneği olan mavi-yeşil dağıtım
+[ ] **İzleme kapsamı** - Çok tablolu işlemler için kapsamlı metrikler
+[ ] **Test kapsamı** - Tüm sorgu kalıpları, performans kıyaslamalarıyla test edilmiştir
+[ ] **Belgeleme** - Güncellenmiş dağıtım ve işletim prosedürleri
+
+## Zaman Çizelgesi
+
+### 1. Aşama: Uygulama
+[ ] `cassandra_kg.py`'ı çok tablolu şemayla yeniden yazın
+[ ] Toplu yazma işlemlerini uygulayın
+[ ] Hazırlanmış ifade optimizasyonunu ekleyin
+[ ] Birim testlerini güncelleyin
+
+### 2. Aşama: Entegrasyon Testi
+[ ] Entegrasyon testlerini güncelleyin
+[ ] Performans kıyaslaması
+[ ] Gerçekçi veri hacimleriyle yük testi
+[ ] Veri tutarlılığı için doğrulama betikleri
+
+### 3. Aşama: Geçiş Planlaması
+[ ] Mavi-yeşil dağıtım betikleri
+[ ] Veri geçiş araçları
+[ ] İzleme panosu güncellemeleri
+[ ] Geri alma prosedürleri
+
+### 4. Aşama: Üretim Dağıtımı
+[ ] Üretime aşamalı dağıtım
+[ ] Performans izleme ve doğrulama
+[ ] Eski tabloların temizlenmesi
+[ ] Belgeleme güncellemeleri
+
+## Sonuç
+
+Bu çok tablolu normalleştirme stratejisi, doğrudan iki kritik performans darboğazını ele almaktadır:
+
+1. **Pahalı ALLOW FILTERING'i ortadan kaldırır** ve her sorgu kalıbı için optimum tablo yapıları sağlar.
+2. **Kompozit bölüm anahtarları aracılığıyla kümeleme etkinliğini artırır** ve yükü düzgün bir şekilde dağıtır.
+
+Bu yaklaşım, Cassandra'nın güçlü yönlerinden yararlanırken, mevcut kodun performans iyileştirmelerinden otomatik olarak yararlanmasını sağlayan tam API uyumluluğunu korur.

docs/tech-specs/cassandra-performance-refactor.zh-cn.md

@@ -0,0 +1,679 @@
+# 技术规范：Cassandra 知识库性能重构
+
+**状态：** 草稿
+**作者：** 助理
+**日期：** 2025-09-18
+
+## 概述
+
+本规范解决了 TrustGraph Cassandra 知识库实现中的性能问题，并提出了针对 RDF 三元组存储和查询的优化方案。
+
+## 当前实现
+
+### 模式设计
+
+当前实现使用单表设计，位于 `trustgraph-flow/trustgraph/direct/cassandra_kg.py`：
+
+```sql
+CREATE TABLE triples (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+
+**次级索引：**
+`triples_s` ON `s` (主语)
+`triples_p` ON `p` (谓语)
+`triples_o` ON `o` (宾语)
+
+### 查询模式
+
+当前实现支持 8 种不同的查询模式：
+
+1. **get_all(collection, limit=50)** - 检索集合中的所有三元组
+   ```sql
+   SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
+   ```
+
+2. **get_s(collection, s, limit=10)** - 通过主题进行查询
+   ```sql
+   SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
+   ```
+
+3. **get_p(collection, p, limit=10)** - 通过谓词进行查询
+   ```sql
+   SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
+   ```
+
+4. **get_o(collection, o, limit=10)** - 通过对象查询
+   ```sql
+   SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
+   ```
+
+5. **get_sp(collection, s, p, limit=10)** - 通过主语 + 谓语进行查询。
+   ```sql
+   SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
+   ```
+
+6. **get_po(collection, p, o, limit=10)** - 通过谓词 + 对象进行查询 ⚠️
+   ```sql
+   SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+7. **get_os(collection, o, s, limit=10)** - 通过对象 + 主题进行查询 ⚠️
+   ```sql
+   SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
+   ```
+
+8. **get_spo(collection, s, p, o, limit=10)** - 精确三元组匹配
+   ```sql
+   SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
+   ```
+
+### 当前架构
+
+**文件: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
+单个 `KnowledgeGraph` 类处理所有操作
+通过全局 `_active_clusters` 列表进行连接池管理
+固定的表名: `"triples"`
+每个用户模型的 keyspace
+复制策略为 SimpleStrategy，因子为 1
+
+**集成点:**
+**写入路径:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+**查询路径:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
+**知识存储:** `trustgraph-flow/trustgraph/tables/knowledge.py`
+
+## 识别出的性能问题
+
+### 模式层级问题
+
+1. **低效的主键设计**
+   当前: `PRIMARY KEY (collection, s, p, o)`
+   导致常见访问模式下的聚类效果不佳
+   强制使用昂贵的二级索引
+
+2. **过度使用二级索引** ⚠️
+   在高基数列（s, p, o）上使用了三个二级索引
+   Cassandra 中的二级索引很昂贵，并且扩展性较差
+   查询 6 和 7 需要 `ALLOW FILTERING`，表明数据建模存在问题
+
+3. **分区热点风险**
+   单个分区键 `collection` 可能会创建分区热点
+   大型集合会集中在单个节点上
+   没有用于负载均衡的分布策略
+
+### 查询层级问题
+
+1. **ALLOW FILTERING 的使用** ⚠️
+   两种查询类型（get_po, get_os）需要 `ALLOW FILTERING`
+   这些查询会扫描多个分区，并且非常昂贵
+   性能会随着数据量的增加而线性下降
+
+2. **低效的访问模式**
+   没有针对常见的 RDF 查询模式进行优化
+   缺少用于频繁查询组合的复合索引
+   没有考虑图遍历模式
+
+3. **缺乏查询优化**
+   没有预处理语句缓存
+   没有查询提示或优化策略
+   没有考虑简单的 LIMIT 之外的分页
+
+## 问题陈述
+
+当前的 Cassandra 知识库实现存在两个关键的性能瓶颈：
+
+### 1. get_po 查询性能低效
+
+`get_po(collection, p, o)` 查询非常低效，因为它需要 `ALLOW FILTERING`:
+
+```sql
+SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
+```
+
+**问题所在：**
+`ALLOW FILTERING` 迫使 Cassandra 扫描集合中的所有分区。
+性能会随着数据量的线性增长而下降。
+这是一个常见的 RDF 查询模式（查找具有特定谓词-对象关系的实体）。
+随着数据增长，这会在集群上产生显著的负载。
+
+### 2. 聚类策略不佳
+
+当前主键 `PRIMARY KEY (collection, s, p, o)` 提供的聚类优势有限：
+
+**当前聚类的存在问题：**
+将 `collection` 作为分区键，无法有效分布数据。
+大多数集合包含各种数据，这使得聚类无效。
+未考虑 RDF 查询中的常见访问模式。
+大型集合会在单个节点上创建热点分区。
+聚类列 (s, p, o) 未针对典型的图遍历模式进行优化。
+
+**影响：**
+查询无法受益于数据局部性。
+缓存利用率低下。
+集群节点上的负载分布不均匀。
+随着集合的增长，会出现可扩展性瓶颈。
+
+## 建议的解决方案：4 表反规范化策略
+
+### 概述
+
+用四个专门设计的表替换单个 `triples` 表，每个表针对特定的查询模式进行了优化。 这消除了对辅助索引和 ALLOW FILTERING 的需求，同时为所有类型的查询提供最佳性能。 第四个表实现了在复合分区键下高效地删除集合的功能。
+
+### 新的模式设计
+
+**表 1：以实体为中心的查询 (triples_s)**
+```sql
+CREATE TABLE triples_s (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY ((collection, s), p, o)
+);
+```
+**优化：** get_s, get_sp, get_os
+**分区键：** (collection, s) - 比仅使用 collection 的分区方式分布更好
+**聚类：** (p, o) - 允许对主语进行高效的谓词/对象查找
+
+**表 2：谓词-对象查询 (triples_p)**
+```sql
+CREATE TABLE triples_p (
+    collection text,
+    p text,
+    o text,
+    s text,
+    PRIMARY KEY ((collection, p), o, s)
+);
+```
+**优化：** get_p, get_po (消除 ALLOW FILTERING!)
+**分区键：** (collection, p) - 通过谓词直接访问
+**聚类：** (o, s) - 高效的对象-主体遍历
+
+**表 3：面向对象的查询 (triples_o)**
+```sql
+CREATE TABLE triples_o (
+    collection text,
+    o text,
+    s text,
+    p text,
+    PRIMARY KEY ((collection, o), s, p)
+);
+```
+**优化：** get_o
+**分区键：** (collection, o) - 通过对象直接访问
+**聚类：** (s, p) - 高效的主体-谓语遍历
+
+**表 4：集合管理与 SPO 查询 (triples_collection)**
+```sql
+CREATE TABLE triples_collection (
+    collection text,
+    s text,
+    p text,
+    o text,
+    PRIMARY KEY (collection, s, p, o)
+);
+```
+**优化：** get_spo, delete_collection
+**分区键：** 仅限集合 - 启用高效的集合级别操作
+**聚类：** (s, p, o) - 标准三元组排序
+**目的：** 既用于精确的SPO查找，也用作删除索引
+
+### 查询映射
+
+| 原始查询 | 目标表 | 性能提升 |
+|----------------|-------------|------------------------|
+| get_all(collection) | triples_s | 允许过滤 (对于扫描是可以接受的) |
+| get_s(collection, s) | triples_s | 直接分区访问 |
+| get_p(collection, p) | triples_p | 直接分区访问 |
+| get_o(collection, o) | triples_o | 直接分区访问 |
+| get_sp(collection, s, p) | triples_s | 分区 + 聚类 |
+| get_po(collection, p, o) | triples_p | **不再需要 ALLOW FILTERING!** |
+| get_os(collection, o, s) | triples_o | 分区 + 聚类 |
+| get_spo(collection, s, p, o) | triples_collection | 精确键查找 |
+| delete_collection(collection) | triples_collection | 读取索引，批量删除所有 |
+
+### 集合删除策略
+
+对于复合分区键，我们不能简单地执行 `DELETE FROM table WHERE collection = ?`。 而是：
+
+1. **读取阶段：** 查询 `triples_collection` 以枚举所有三元组：
+   ```sql
+   SELECT s, p, o FROM triples_collection WHERE collection = ?
+   ```
+   这很高效，因为 `collection` 是此表的分割键。
+
+2. **删除阶段：** 对于每个三元组 (s, p, o)，使用完整的分割键从所有 4 个表中删除数据。
+   ```sql
+   DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
+   DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
+   DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
+   ```
+   批量处理，每次100个，以提高效率。
+
+**权衡分析：**
+✅ 保持最佳查询性能，采用分布式分区。
+✅ 大型集合不会出现热点分区。
+❌ 删除逻辑更复杂（先读取，再删除）。
+❌ 删除时间与集合大小成正比。
+
+### 优点
+
+1. **消除 ALLOW FILTERING** - 每个查询都有最佳访问路径（除了全表扫描）。
+2. **无需二级索引** - 每个表本身就是其查询模式的索引。
+3. **更好的数据分布** - 组合分区键能有效分散负载。
+4. **可预测的性能** - 查询时间与结果大小成正比，而不是总数据量。
+5. **利用 Cassandra 的优势** - 专为 Cassandra 的架构设计。
+6. **支持集合删除** - `triples_collection` 作为删除索引。
+
+## 实施计划
+
+### 需要修改的文件
+
+#### 主要实施文件
+
+**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - 需要完全重写。
+
+**需要重构的现有方法：**
+```python
+# Schema initialization
+def init(self) -> None  # Replace single table with three tables
+
+# Insert operations
+def insert(self, collection, s, p, o) -> None  # Write to all three tables
+
+# Query operations (API unchanged, implementation optimized)
+def get_all(self, collection, limit=50)      # Use triples_by_subject
+def get_s(self, collection, s, limit=10)     # Use triples_by_subject
+def get_p(self, collection, p, limit=10)     # Use triples_by_po
+def get_o(self, collection, o, limit=10)     # Use triples_by_object
+def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
+def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
+def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
+def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
+
+# Collection management
+def delete_collection(self, collection) -> None  # Delete from all three tables
+```
+
+#### 集成文件 (无需修改任何逻辑)
+
+**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
+无需修改 - 使用现有的知识图谱 API
+自动受益于性能改进
+
+**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
+无需修改 - 使用现有的知识图谱 API
+自动受益于性能改进
+
+### 需要更新的测试文件
+
+#### 单元测试
+**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
+更新测试预期，以适应模式更改
+添加多表一致性测试
+验证查询计划中是否包含 ALLOW FILTERING
+
+**`tests/unit/test_query/test_triples_cassandra_query.py`**
+更新性能断言
+对所有 8 种查询模式进行针对新表的测试
+验证查询是否路由到正确的表
+
+#### 集成测试
+**`tests/integration/test_cassandra_integration.py`**
+使用新模式进行端到端测试
+性能基准测试比较
+跨表的数据一致性验证
+
+**`tests/unit/test_storage/test_cassandra_config_integration.py`**
+更新模式验证测试
+测试迁移场景
+
+### 实施策略
+
+#### 第一阶段：模式和核心方法
+1. **重写 `init()` 方法** - 创建四个表而不是一个
+2. **重写 `insert()` 方法** - 批量写入所有四个表
+3. **实现预处理语句** - 以获得最佳性能
+4. **添加表路由逻辑** - 将查询定向到最佳表
+5. **实现集合删除** - 从 triples_collection 中读取，批量删除所有表中的数据
+
+#### 第二阶段：查询方法优化
+1. **重写每个 get_* 方法** 以使用最佳表
+2. **删除所有 ALLOW FILTERING 的用法**
+3. **实现高效的聚类键使用**
+4. **添加查询性能日志记录**
+
+#### 第三阶段：集合管理
+1. **更新 `delete_collection()`** - 从所有三个表中删除
+2. **添加一致性验证** - 确保所有表保持同步
+3. **实现批量操作** - 用于原子级多表操作
+
+### 关键实施细节
+
+#### 批量写入策略
+```python
+def insert(self, collection, s, p, o):
+    batch = BatchStatement()
+
+    # Insert into all four tables
+    batch.add(self.insert_subject_stmt, (collection, s, p, o))
+    batch.add(self.insert_po_stmt, (collection, p, o, s))
+    batch.add(self.insert_object_stmt, (collection, o, s, p))
+    batch.add(self.insert_collection_stmt, (collection, s, p, o))
+
+    self.session.execute(batch)
+```
+
+#### 查询路由逻辑
+```python
+def get_po(self, collection, p, o, limit=10):
+    # Route to triples_p table - NO ALLOW FILTERING!
+    return self.session.execute(
+        self.get_po_stmt,
+        (collection, p, o, limit)
+    )
+
+def get_spo(self, collection, s, p, o, limit=10):
+    # Route to triples_collection table for exact SPO lookup
+    return self.session.execute(
+        self.get_spo_stmt,
+        (collection, s, p, o, limit)
+    )
+```
+
+#### 集合删除逻辑
+```python
+def delete_collection(self, collection):
+    # Step 1: Read all triples from collection table
+    rows = self.session.execute(
+        f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
+        (collection,)
+    )
+
+    # Step 2: Batch delete from all 4 tables
+    batch = BatchStatement()
+    count = 0
+
+    for row in rows:
+        s, p, o = row.s, row.p, row.o
+
+        # Delete using full partition keys for each table
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
+        ), (collection, p, o, s))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
+        ), (collection, o, s, p))
+
+        batch.add(SimpleStatement(
+            f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
+        ), (collection, s, p, o))
+
+        count += 1
+
+        # Execute every 100 triples to avoid oversized batches
+        if count % 100 == 0:
+            self.session.execute(batch)
+            batch = BatchStatement()
+
+    # Execute remaining deletions
+    if count % 100 != 0:
+        self.session.execute(batch)
+
+    logger.info(f"Deleted {count} triples from collection {collection}")
+```
+
+#### 预处理语句优化
+```python
+def prepare_statements(self):
+    # Cache prepared statements for better performance
+    self.insert_subject_stmt = self.session.prepare(
+        f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_po_stmt = self.session.prepare(
+        f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_object_stmt = self.session.prepare(
+        f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
+    )
+    self.insert_collection_stmt = self.session.prepare(
+        f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
+    )
+    # ... query statements
+```
+
+## 迁移策略
+
+### 数据迁移方法
+
+#### 选项 1：蓝绿部署（推荐）
+1. **并行部署新模式和现有模式** - 暂时使用不同的表名
+2. **双写期** - 在过渡期间同时写入旧模式和新模式
+3. **后台迁移** - 将现有数据复制到新表中
+4. **切换读取** - 在数据迁移完成后，将查询路由到新表中
+5. **删除旧表** - 在验证期结束后
+
+#### 选项 2：原地迁移
+1. **模式添加** - 在现有键空间中创建新表
+2. **数据迁移脚本** - 批量从旧表复制到新表
+3. **应用程序更新** - 在迁移完成后部署新代码
+4. **清理旧表** - 删除旧表和索引
+
+### 向后兼容性
+
+#### 部署策略
+```python
+# Environment variable to control table usage during migration
+USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
+
+class KnowledgeGraph:
+    def __init__(self, ...):
+        if USE_LEGACY_TABLES:
+            self.init_legacy_schema()
+        else:
+            self.init_optimized_schema()
+```
+
+#### 迁移脚本
+```python
+def migrate_data():
+    # Read from old table
+    old_triples = session.execute("SELECT collection, s, p, o FROM triples")
+
+    # Batch write to new tables
+    for batch in batched(old_triples, 100):
+        batch_stmt = BatchStatement()
+        for row in batch:
+            # Add to all three new tables
+            batch_stmt.add(insert_subject_stmt, row)
+            batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
+            batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
+        session.execute(batch_stmt)
+```
+
+### 验证策略
+
+#### 数据一致性检查
+```python
+def validate_migration():
+    # Count total records in old vs new tables
+    old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
+    new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
+
+    assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
+
+    # Spot check random samples
+    sample_queries = generate_test_queries()
+    for query in sample_queries:
+        old_result = execute_legacy_query(query)
+        new_result = execute_optimized_query(query)
+        assert old_result == new_result, f"Query results differ for {query}"
+```
+
+## 测试策略
+
+### 性能测试
+
+#### 基准测试场景
+1. **查询性能比较**
+   所有 8 种查询类型的性能指标（测试前后）
+   重点关注 get_po 性能改进（消除 ALLOW FILTERING）
+   测量不同数据规模下的查询延迟
+
+2. **负载测试**
+   并发查询执行
+   批量操作的写入吞吐量
+   内存和 CPU 利用率
+
+3. **可伸缩性测试**
+   随着集合大小增加的性能
+   多集合查询的分布
+   集群节点利用率
+
+#### 测试数据集
+**小型:** 每个集合 10K 个三元组
+**中型:** 每个集合 100K 个三元组
+**大型:** 1M+ 个三元组
+**多个集合:** 测试分区分布
+
+### 功能测试
+
+#### 单元测试更新
+```python
+# Example test structure for new implementation
+class TestCassandraKGPerformance:
+    def test_get_po_no_allow_filtering(self):
+        # Verify get_po queries don't use ALLOW FILTERING
+        with patch('cassandra.cluster.Session.execute') as mock_execute:
+            kg.get_po('test_collection', 'predicate', 'object')
+            executed_query = mock_execute.call_args[0][0]
+            assert 'ALLOW FILTERING' not in executed_query
+
+    def test_multi_table_consistency(self):
+        # Verify all tables stay in sync
+        kg.insert('test', 's1', 'p1', 'o1')
+
+        # Check all tables contain the triple
+        assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
+        assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
+        assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
+```
+
+#### 集成测试更新
+```python
+class TestCassandraIntegration:
+    def test_query_performance_regression(self):
+        # Ensure new implementation is faster than old
+        old_time = benchmark_legacy_get_po()
+        new_time = benchmark_optimized_get_po()
+        assert new_time < old_time * 0.5  # At least 50% improvement
+
+    def test_end_to_end_workflow(self):
+        # Test complete write -> query -> delete cycle
+        # Verify no performance degradation in integration
+```
+
+### 回滚计划
+
+#### 快速回滚策略
+1. **环境变量切换** - 立即切换回旧版表
+2. **保留旧版表** - 在性能得到验证之前，不要删除
+3. **监控警报** - 基于错误率/延迟的自动化回滚触发
+
+#### 回滚验证
+```python
+def rollback_to_legacy():
+    # Set environment variable
+    os.environ['CASSANDRA_USE_LEGACY'] = 'true'
+
+    # Restart services to pick up change
+    restart_cassandra_services()
+
+    # Validate functionality
+    run_smoke_tests()
+```
+
+## 风险与考量
+
+### 性能风险
+**写入延迟增加** - 每个插入操作需要 4 次写入（比 3 表方案多 33%）
+**存储开销** - 需要 4 倍的存储空间（比 3 表方案多 33%）
+**批量写入失败** - 需要适当的错误处理
+**删除复杂性** - 集合删除需要先读取再删除的循环
+
+### 运维风险
+**迁移复杂性** - 大数据集的数据迁移
+**一致性挑战** - 确保所有表保持同步
+**监控缺失** - 需要新的指标来监控多表操作
+
+### 缓解策略
+1. **逐步推广** - 从小型集合开始
+2. **全面监控** - 跟踪所有性能指标
+3. **自动化验证** - 持续进行一致性检查
+4. **快速回滚能力** - 基于环境选择表
+
+## 成功标准
+
+### 性能改进
+[ ] **消除 ALLOW FILTERING** - `get_po` 和 `get_os` 查询在没有过滤的情况下运行
+[ ] **查询延迟降低** - 查询响应时间提高 50% 以上
+[ ] **更好的负载分布** - 没有热分区，集群节点上的负载分布均匀
+[ ] **可扩展的性能** - 查询时间与结果大小成正比，而不是与总数据量成正比
+
+### 功能需求
+[ ] **API 兼容性** - 所有现有代码继续保持不变
+[ ] **数据一致性** - 所有三个表保持同步
+[ ] **零数据丢失** - 迁移保留所有现有三元组
+[ ] **向后兼容性** - 能够回滚到旧模式
+
+### 运维需求
+[ ] **安全迁移** - 蓝绿部署，具有回滚能力
+[ ] **监控覆盖** - 针对多表操作的全面指标
+[ ] **测试覆盖** - 所有查询模式都经过性能基准测试
+[ ] **文档** - 更新部署和运维流程
+
+## 时间线
+
+### 第一阶段：实施
+[ ] 使用多表模式重写 `cassandra_kg.py`
+[ ] 实施批量写入操作
+[ ] 添加准备语句优化
+[ ] 更新单元测试
+
+### 第二阶段：集成测试
+[ ] 更新集成测试
+[ ] 性能基准测试
+[ ] 使用真实数据量的负载测试
+[ ] 数据一致性验证脚本
+
+### 第三阶段：迁移规划
+[ ] 蓝绿部署脚本
+[ ] 数据迁移工具
+[ ] 监控仪表板更新
+[ ] 回滚流程
+
+### 第四阶段：生产部署
+[ ] 逐步推广到生产环境
+[ ] 性能监控和验证
+[ ] 清理旧表
+[ ] 文档更新
+
+## 结论
+
+这种多表反规范化策略直接解决了两个关键的性能瓶颈：
+
+1. **消除昂贵的 ALLOW FILTERING**，通过为每种查询模式提供最佳的表结构
+2. **提高聚类效率**，通过复合分区键来合理地分配负载
+
+该方法利用了 Cassandra 的优势，同时保持完整的 API 兼容性，确保现有代码能够自动受益于性能改进。