init translations

Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>

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.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.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.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.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.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.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.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.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.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.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/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/explainability-cli.ar.md

@@ -0,0 +1,170 @@
+# مواصفات سطر الأوامر لـ "Explainability CLI"
+
+## الحالة
+
+مُقترح
+
+## نظرة عامة
+
+تصف هذه المواصفة أدوات سطر الأوامر لتصحيح الأخطاء واستكشاف بيانات الشرح في TrustGraph. تسمح هذه الأدوات للمستخدمين بتتبع كيفية استخلاص الإجابات وتصحيح سلسلة الأصل من الحواف إلى المستندات المصدر.
+
+ثلاث أدوات سطر أوامر:
+
+1. **`tg-show-document-hierarchy`** - عرض تسلسل المستند → الصفحة → الجزء → الحافة
+2. **`tg-list-explain-traces`** - سرد جميع جلسات GraphRAG مع الأسئلة
+3. **`tg-show-explain-trace`** - عرض مسار الشرح الكامل لجلسة
+
+## الأهداف
+
+- **تصحيح الأخطاء**: تمكين المطورين من فحص نتائج معالجة المستندات
+- **قابلية التدقيق**: تتبع أي حقيقة مستخرجة إلى مستندها المصدر
+- **الشفافية**: إظهار بالضبط كيف اشتق GraphRAG إجابة
+- **سهولة الاستخدام**: واجهة سطر أوامر بسيطة مع قيم افتراضية معقولة
+
+## الخلفية
+
+يحتوي TrustGraph على نظامين لتعقب:
+
+1. **تعقب وقت الاستخراج** (انظر `extraction-time-provenance.md`): يسجل علاقات المستند → الصفحة → الجزء → الحافة أثناء الاستيعاب. يتم تخزينها في رسم بياني يسمى `urn:graph:source` باستخدام `prov:wasDerivedFrom`.
+
+2. **شرح قابل للتفسير في وقت الاستعلام** (انظر `query-time-explainability.md`): يسجل سلسلة السؤال → الاستكشاف → التركيز → التجميع أثناء استعلامات GraphRAG. يتم تخزينها في رسم بياني يسمى `urn:graph:retrieval`.
+
+القيود الحالية:
+- لا توجد طريقة سهلة لتصور تسلسل المستند بعد المعالجة
+- يجب الاستعلام يدويًا عن المثلثات لعرض بيانات الشرح
+- لا يوجد عرض موحد لجلسة GraphRAG
+
+## التصميم الفني
+
+### الأداة 1: tg-show-document-hierarchy
+
+**الغرض**: إعطاء معرف المستند، والتحرك وعرض جميع الكيانات المشتقة.
+
+**الاستخدام**:
+```bash
+tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
+tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
+```
+
+**الوسائط**:
+| الوسيط | الوصف |
+|---|---|
+| `document_id` | URI للمستند (موضعي) |
+| `-u/--api-url` | عنوان URL لـ Gateway |
+| `-t/--token` | رمز المصادقة |
+| `-U/--user` | معرف المستخدم |
+| `-C/--collection` | المجموعة |
+| `--show-content` | تضم محتوى Blob/المستند |
+| `--max-content` | أقصى عدد من الأحرف في Blob (افتراضي: 200) |
+| `--format` | الإخراج: `tree` (افتراضي)، `json` |
+
+**التنفيذ**:
+1. استعلام عن المثلثات: `?child prov:wasDerivedFrom <document_id>` في `urn:graph:source`
+2. استعلام بشكل متكرر عن الأطفال لكل نتيجة
+3. بناء بنية الشجرة: المستند → الصفحات → الأجزاء
+4. إذا كان `--show-content`، فقم باسترداد المحتوى من واجهة برمجة التطبيقات الخاصة بالمكتبة
+5. عرض كشجرة مسطحة أو JSON
+
+**مثال على الإخراج**:
+```
+المستند: urn:trustgraph:doc:abc123
+  العنوان: "Sample PDF"
+  النوع: application/pdf
+
+  └── الصفحة 1: urn:trustgraph:doc:abc123/p1
+      ├── الجزء 0: urn:trustgraph:doc:abc123/p1/c0
+          المحتوى: "The quick brown fox..." [مقتطف]
+      └── الجزء 1: urn:trustgraph:doc:abc123/p1/c1
+          المحتوى: "Machine learning is..." [مقتطف]
+```
+
+### الأداة 2: tg-list-explain-traces
+
+**الغرض**: سرد جميع جلسات GraphRAG (الأسئلة) في مجموعة.
+
+**الاستخدام**:
+```bash
+tg-list-explain-traces
+tg-list-explain-traces --limit 20 --format json
+```
+
+**الوسائط**:
+| الوسيط | الوصف |
+|---|---|
+| `-u/--api-url` | عنوان URL لـ Gateway |
+| `-t/--token` | رمز المصادقة |
+| `-U/--user` | معرف المستخدم |
+| `-C/--collection` | المجموعة |
+| `--limit` | أقصى عدد من النتائج (افتراضي: 50) |
+| `--format` | الإخراج: `table` (افتراضي)، `json` |
+
+**التنفيذ**:
+1. استعلام: `?session tg:query ?text` في `urn:graph:retrieval`
+2. استعلام عن الطوابع الزمنية: `?session prov:startedAtTime ?time`
+3. عرض كجدول
+
+**مثال على الإخراج**:
+```
+معرف الجلسة                                 | السؤال                        | الوقت
+----------------------------------------------|--------------------------------|---------------------
+urn:trustgraph:question:abc123                | What was the War on Terror?    | 2024-01-15 10:30:00
+urn:trustgraph:question:def456                | Who founded OpenAI?            | 2024-01-15 09:15:00
+```
+
+### الأداة 3: tg-show-explain-trace
+
+**الغرض**: عرض مسار الشرح الكامل لجلسة GraphRAG.
+
+**الاستخدام**:
+```bash
+tg-show-explain-trace "urn:trustgraph:question:abc123"
+tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
+```
+
+**الوسائط**:
+| الوسيط | الوصف |
+|---|---|
+| `question_id` | معرف السؤال (موضعي) |
+| `-u/--api-url` | عنوان URL لـ Gateway |
+| `-t/--token` | رمز المصادقة |
+| `-U/--user` | معرف المستخدم |
+| `-C/--collection` | المجموعة |
+| `--max-answer` | أقصى عدد من الأحرف للإجابة (افتراضي: 500) |
+| `--show-provenance` | تتبع الحواف إلى المستندات المصدر |
+| `--format` | الإخراج: `text` (افتراضي)، `json` |
+
+**التنفيذ**:
+1. الحصول على نص السؤال من البُعد `tg:query`
+2. العثور على الاستكشاف: `?exp prov:wasGeneratedBy <question_id>`
+3. العثور على التركيز: `?focus prov:wasDerivedFrom <exploration_id>`
+4. الحصول على الحواف المحددة: `<focus_id> tg:selectedEdge ?edge`
+5. لكل حافة، الحصول على `tg:edge` (سلسلة RDF) و `tg:reasoning`
+6. العثور على التجميع: `?synth prov:wasDerivedFrom <focus_id>`
+7. الحصول على الإجابة من `tg:document` عبر واجهة برمجة التطبيقات
+8. إذا كان `--show-provenance`، فقم بتتبع الحواف إلى المستندات المصدر
+
+**مثال على الإخراج**:
+```
+=== جلسة GraphRAG: urn:trustgraph:question:abc123 ===
+
+السؤال: What was the War on Terror?
+الوقت: 2024-01-15 10:30:00
+
+الإجابة: [إجابة]
+
+مسار الشرح:
+- السؤال: What was the War on Terror?
+  - استخراج: [ملف]
+  - تجميع: [إطار عمل]
+  - استجابة: [إجابة]
+- السؤال: What was the War on Terror?
+  - استخراج: [ملف]
+  - تجميع: [إطار عمل]
+  - استجابة: [إجابة]
+```
+
+## المراجع
+
+- شرح قابل للتفسير: `docs/tech-specs/query-time-explainability.md`
+- تتبع وقت الاستخراج: `docs/tech-specs/extraction-time-provenance.md`
+- مثال سطر الأوامر: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`

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

@@ -0,0 +1,180 @@
+# Especificación Técnica de la CLI para Explicabilidad
+
+## Estado
+
+Borrador
+
+## Visión General
+
+Esta especificación describe las herramientas de CLI para depurar y explorar datos de explicabilidad en TrustGraph. Estas herramientas permiten a los usuarios rastrear cómo se derivaron las respuestas y depurar la cadena de origen desde los bordes hasta los documentos fuente.
+
+Tres herramientas de CLI:
+
+1.  **`tg-show-document-hierarchy`** - Muestra la jerarquía documento → página → fragmento → borde
+2.  **`tg-list-explain-traces`** - Lista todas las sesiones GraphRAG con preguntas
+3.  **`tg-show-explain-trace`** - Muestra la trazabilidad completa de explicabilidad para una sesión
+
+## Objetivos
+
+-   **Depuración**: Permitir a los desarrolladores inspeccionar los resultados del procesamiento de documentos.
+-   **Auditabilidad**: Rastrear cualquier hecho extraído hasta su documento fuente.
+-   **Transparencia**: Mostrar exactamente cómo GraphRAG derivó una respuesta.
+-   **Usabilidad**: Interfaz CLI sencilla con valores predeterminados apropiados.
+
+## Antecedentes
+
+TrustGraph tiene dos sistemas de origen:
+
+1.  **Origen en tiempo de extracción** (ver `extraction-time-provenance.md`): Registra las relaciones documento → página → fragmento → borde durante la ingestión. Almacenado en el gráfico llamado `urn:graph:source` utilizando `prov:wasDerivedFrom`.
+
+2.  **Explicabilidad en tiempo de consulta** (ver `query-time-explainability.md`): Registra la cadena de pregunta → exploración → enfoque → síntesis durante las consultas GraphRAG. Almacenado en el gráfico llamado `urn:graph:retrieval`.
+
+Limitaciones actuales:
+
+-   No hay una manera fácil de visualizar la jerarquía del documento después del procesamiento.
+-   Se deben consultar manualmente los triples para ver los datos de explicabilidad.
+-   No hay una vista consolidada de una sesión GraphRAG.
+
+## Diseño Técnico
+
+### Herramienta 1: `tg-show-document-hierarchy`
+
+**Propósito**: Dado un ID de documento, recorrer y mostrar todas las entidades derivadas.
+
+**Uso**:
+```bash
+tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
+tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
+```
+
+**Argumentos**:
+| Arg | Descripción |
+|---|---|
+| `document_id` | URI del documento (posicional) |
+| `-u/--api-url` | URL del gateway (por defecto: `$TRUSTGRAPH_URL`) |
+| `-t/--token` | Token de autenticación (por defecto: `$TRUSTGRAPH_TOKEN`) |
+| `-U/--user` | ID de usuario (por defecto: `trustgraph`) |
+| `-C/--collection` | Colección (por defecto: `default`) |
+| `--show-content` | Incluir el contenido del blob/documento |
+| `--max-content` | Máx. caracteres por blob (por defecto: 200) |
+| `--format` | Salida: `tree` (por defecto), `json` |
+
+**Implementación**:
+1.  Consultar triples: `?child prov:wasDerivedFrom <document_id>` en `urn:graph:source`
+2.  Consultar recursivamente los hijos de cada resultado
+3.  Construir la estructura del árbol: Documento → Páginas → Fragmentos
+4.  Si `--show-content`, recuperar el contenido de la API del bibliotecario
+5.  Mostrar como árbol anidado o JSON
+
+**Ejemplo de Salida**:
+```
+Document: urn:trustgraph:doc:abc123
+  Título: "Sample PDF"
+  Tipo: application/pdf
+
+  └── Página 1: urn:trustgraph:doc:abc123/p1
+      ├── Fragmento 0: urn:trustgraph:doc:abc123/p1/c0
+          Contenido: "The quick brown fox..." [truncado]
+      └── Fragmento 1: urn:trustgraph:doc:abc123/p1/c1
+          Contenido: "Machine learning is..." [truncado]
+```
+
+### Herramienta 2: `tg-list-explain-traces`
+
+**Propósito**: Listar todas las sesiones GraphRAG (preguntas) en una colección.
+
+**Uso**:
+```bash
+tg-list-explain-traces
+tg-list-explain-traces --limit 20 --format json
+```
+
+**Argumentos**:
+| Arg | Descripción |
+|---|---|
+| `-u/--api-url` | URL del gateway |
+| `-t/--token` | Token de autenticación |
+| `-U/--user` | ID de usuario |
+| `-C/--collection` | Colección |
+| `--limit` | Máx. resultados (por defecto: 50) |
+| `--format` | Salida: `table` (por defecto), `json` |
+
+**Implementación**:
+1.  Consultar: `?session tg:query ?text` en `urn:graph:retrieval`
+2.  Consultar los tiempos: `?session prov:startedAtTime ?time`
+3.  Mostrar como tabla
+
+**Ejemplo de Salida**:
+```
+Session ID                                    | Pregunta                        | Tiempo
+----------------------------------------------|--------------------------------|---------------------
+urn:trustgraph:question:abc123                | ¿Cuál fue la Guerra Fría?    | 2024-01-15 10:30:00
+urn:trustgraph:question:def456                | ¿Quién fundó la NASA?            | 2024-01-15 09:15:00
+```
+
+### Herramienta 3: `tg-show-explain-trace`
+
+**Propósito**: Mostrar la trazabilidad completa de explicabilidad para una sesión GraphRAG.
+
+**Uso**:
+```bash
+tg-show-explain-trace "urn:trustgraph:question:abc123"
+tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
+```
+
+**Argumentos**:
+| Arg | Descripción |
+|---|---|
+| `question_id` | URI de la pregunta (posicional) |
+| `-u/--api-url` | URL del gateway |
+| `-t/--token` | Token de autenticación |
+| `-U/--user` | ID de usuario |
+| `-C/--collection` | Colección |
+| `--max-answer` | Máx. caracteres para la respuesta (por defecto: 500) |
+| `--show-provenance` | Rastrear los bordes hasta los documentos fuente |
+| `--format` | Salida: `text` (por defecto), `json` |
+
+**Implementación**:
+1.  Obtener el texto de la pregunta del predicado `tg:query`
+2.  Encontrar la exploración: `?exp prov:wasGeneratedBy <question_id>`
+3.  Encontrar el enfoque: `?focus prov:wasDerivedFrom <exploration_id>`
+4.  Obtener los bordes seleccionados: `<focus_id> tg:selectedEdge ?edge`
+5.  Para cada borde, obtener `tg:edge` (triple acotado) y `tg:reasoning`
+6.  Encontrar la síntesis: `?synth prov:wasDerivedFrom <focus_id>`
+7.  Obtener la respuesta del documento a través de la API del bibliotecario
+8.  Si `--show-provenance`, rastrear los bordes hasta los documentos fuente
+
+**Ejemplo de Salida**:
+```
+=== Sesión GraphRAG: urn:trustgraph:question:abc123 ===
+
+Pregunta: ¿Cuál fue la Guerra Fría?
+Tiempo: 2024-01-15 10:30:00
+
+--- Exploración ---
+Se recuperaron 50 bordes de la gráfica de conocimiento
+
+--- Enfoque (Selección de Bordes) ---
+Se seleccionaron 12 bordes:
+
+  1.  "The Cold War"
+  2.  "Yuri Andropov"
+  3.  "Khrushchev"
+  4.  "NATO"
+  5.  "Warsaw Pact"
+  6.  "Berlin Wall"
+  7.  "Cuban Missile Crisis"
+  8.  "Detente"
+  9.  "Détente"
+  10. "Joseph Stalin"
+  11. "Nikita Khrushchev"
+  12. "US-Soviet Relations"
+
+--- Trazabilidad ---
+```
+
+## Referencias
+
+-   CLI de explicabilidad: `docs/tech-specs/query-time-explainability.md`
+-   Origen en tiempo de extracción: `docs/tech-specs/extraction-time-provenance.md`
+-   Ejemplo de CLI: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`

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

@@ -0,0 +1,184 @@
+# 可解释 CLI 技术规范
+
+## 状态
+
+草稿
+
+## 概述
+
+本规范描述了用于在 TrustGraph 中调试和探索可解释数据的 CLI 工具。这些工具使用户能够跟踪答案的生成方式，并从边向源文档追溯查询的来源链。
+
+三个 CLI 工具：
+
+1. **`tg-show-document-hierarchy`** - 显示文档 → 页面 → 块 → 边层级结构
+2. **`tg-list-explain-traces`** - 列出所有 GraphRAG 会话，包含问题
+3. **`tg-show-explain-trace`** - 显示会话的完整可解释性跟踪
+
+## 目标
+
+- **调试**: 允许开发者检查文档处理结果
+- **可追溯性**: 追踪任何提取的事实，追溯到其原始文档
+- **透明性**: 明确显示 GraphRAG 如何得出答案
+- **易用性**: 简单的 CLI 界面，带有合理的默认设置
+
+## 背景
+
+TrustGraph 拥有两个来源系统：
+
+1. **摄取时来源**: (见 `extraction-time-provenance.md`) - 记录文档 → 页面 → 块 → 边的关系，发生在摄取时。存储在名为 `urn:graph:source` 的图表中，使用 `prov:wasDerivedFrom` 属性。
+
+2. **查询时可解释性**: (见 `query-time-explainability.md`) - 记录问题 → 探索 → 重点 → 总结链，发生在 GraphRAG 查询时。存储在名为 `urn:graph:retrieval` 的图表中。
+
+当前限制：
+- 没有简单的方法来可视化文档层级结构，在处理后
+- 必须手动查询三元组来查看可解释性数据
+- 没有 GraphRAG 会话的综合视图
+
+## 技术设计
+
+### 工具 1: `tg-show-document-hierarchy`
+
+**目的**: 针对特定文档 ID，遍历并显示所有派生的实体。
+
+**用法**:
+```bash
+tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
+tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
+```
+
+**参数**:
+| 参数 | 描述 |
+|---|---|
+| `document_id` | 文档 URI (位置参数) |
+| `-u/--api-url` | API URL |
+| `-t/--token` | 身份验证令牌 |
+| `-U/--user` | 用户 ID (默认: `trustgraph`) |
+| `-C/--collection` | 集合 (默认: `default`) |
+| `--show-content` | 包含内容 (blob/文档内容) |
+| `--max-content` | 每个 blob 的最大字符数 (默认: 200) |
+| `--format` | 输出格式: `tree` (默认), `json` |
+
+**实现**:
+1. 查询三元组: `?child prov:wasDerivedFrom <document_id>` 在 `urn:graph:source` 图表中
+2. 递归查询每个结果的子节点
+3. 构建树结构: 文档 → 页面 → 块
+4. 如果 `--show-content`，则从 librarian API 获取内容
+5. 以缩进树或 JSON 格式显示
+
+**输出示例**:
+```
+Document: urn:trustgraph:doc:abc123
+  Title: "Sample PDF"
+  Type: application/pdf
+
+  └── Page 1: urn:trustgraph:doc:abc123/p1
+      ├── Chunk 0: urn:trustgraph:doc:abc123/p1/c0
+          Content: "The quick brown fox..." [truncated]
+      └── Chunk 1: urn:trustgraph:doc:abc123/p1/c1
+          Content: "Machine learning is..." [truncated]
+```
+
+### 工具 2: `tg-list-explain-traces`
+
+**目的**: 列出 GraphRAG 会话（问题）在集合中的所有实例。
+
+**用法**:
+```bash
+tg-list-explain-traces
+tg-list-explain-traces --limit 20 --format json
+```
+
+**参数**:
+| 参数 | 描述 |
+|---|---|
+| `-u/--api-url` | API URL |
+| `-t/--token` | 身份验证令牌 |
+| `-U/--user` | 用户 ID |
+| `-C/--collection` | 集合 |
+| `--limit` | 最大结果数 (默认: 50) |
+| `--format` | 输出格式: `table` (默认), `json` |
+
+**实现**:
+1. 查询: `?session tg:query ?text` 在 `urn:graph:retrieval` 图表中
+2. 查询时间戳: `?session prov:startedAtTime ?time`
+3. 以表格形式显示
+
+**输出示例**:
+```
+Session ID                                    | Question                        | Time
+----------------------------------------------|--------------------------------|---------------------
+urn:trustgraph:question:abc123                | What was the War on Terror?    | 2024-01-15 10:30:00
+urn:trustgraph:question:def456                | Who founded OpenAI?            | 2024-01-15 09:15:00
+```
+
+### 工具 3: `tg-show-explain-trace`
+
+**目的**: 显示 GraphRAG 会话的完整可解释性跟踪。
+
+**用法**:
+```bash
+tg-show-explain-trace "urn:trustgraph:question:abc123"
+tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
+```
+
+**参数**:
+| 参数 | 描述 |
+|---|---|
+| `question_id` | 问题 URI (位置参数) |
+| `-u/--api-url` | API URL |
+| `-t/--token` | 身份验证令牌 |
+| `-U/--user` | 用户 ID |
+| `-C/--collection` | 集合 |
+| `--max-answer` | 答案的最大字符数 (默认: 500) |
+| `--show-provenance` | 显示来源文档的边 |
+| `--format` | 输出格式: `text` (默认), `json` |
+
+**实现**:
+1. 从 `tg:query` 谓词中获取问题文本
+2. 查找探索: `?exp prov:wasGeneratedBy <question_id>`
+3. 查找重点: `?focus prov:wasDerivedFrom <exploration_id>`
+4. 获取选定的边: `<focus_id> tg:selectedEdge ?edge`
+5. 对于每个边，获取 `tg:edge` (三元组) 和 `tg:reasoning`
+6. 查找总结: `?synth prov:wasDerivedFrom <focus_id>`
+7. 通过 librarian API 获取答案
+8. 如果 `--show-provenance`，则跟踪指向来源文档的边
+
+**输出示例**:
+```
+=== GraphRAG Session: urn:trustgraph:question:abc123 ===
+
+Question: What was the War on Terror?
+Time: 2024-01-15 10:30:00
+
+--- Exploration ---
+Retrieved 50 edges from knowledge graph
+
+--- Focus (Edge Selection) ---
+Selected 12 edges:
+
+  1. (War on Terror, definition, "A military campaign...")
+     Reasoning: Directly defines the subject of the query
+     Source: chunk → page 2 → "Beyond the Vigilant State"
+
+  2. (Guantanamo Bay, part_of, War on Terror)
+     Reasoning: Shows key component of the campaign
+
+--- Synthesis ---
+Answer:
+  The War on Terror was a military campaign initiated...
+  [truncated at 500 chars]
+```
+
+## 创建的文件
+
+| 文件 | 目的 |
+|---|---|
+| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | 工具 1 |
+| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | 工具 2 |
+| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | 工具 3 |
+
+## 引用
+
+- 咨询时间可解释性: `docs/tech-specs/query-time-explainability.md`
+- 摄取时来源: `docs/tech-specs/extraction-time-provenance.md`
+- 现有 CLI 示例: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`

docs/tech-specs/jsonl-prompt-output.ru.md

@@ -0,0 +1,114 @@
+# Спецификация технической реализации JSONL для выходных данных запросов
+
+## Обзор
+
+Эта спецификация описывает реализацию формата выходных данных JSONL (JSON Lines) для ответов на запросы в TrustGraph. JSONL позволяет надежно извлекать структурированные данные из ответов LLM, решая критические проблемы, связанные с повреждением выходных JSON-массивов при достижении LLM лимитов токенов.
+
+Эта реализация поддерживает следующие сценарии использования:
+
+1. **Надежное извлечение при обрезании**: Извлечение действительных частичных результатов даже при обрезании ответа LLM в середине запроса
+2. **Масштабируемое извлечение**: Обработка извлечения множества элементов без риска полного сбоя из-за ограничений токенов
+3. **Извлечение нескольких типов**: Поддержка извлечения нескольких типов сущностей (определения, взаимосвязи, сущности, атрибуты) в одном запросе
+4. **Вывод, совместимый со стримингом**: Обеспечение возможности последующего стриминга/инкрементной обработки результатов извлечения
+
+## Цели
+
+- **Совместимость с предыдущими версиями**: Существующие запросы, использующие `response-type: "text"` и `response-type: "json"`, продолжают работать без изменений
+- **Надежное извлечение при обрезании**: Частичные ответы LLM дают частичные валидные результаты вместо полного сбоя
+- **Валидация схемы**: Поддержка валидации JSON Schema для отдельных объектов
+- **Гибкость**: Поддержка различных сценариев извлечения, включая извлечение нескольких типов сущностей и использование стриминга
+
+## Реализация
+
+*   **Обработка JSONL**: Метод `parse_jsonl` парсит входные данные JSONL построчно, обрабатывая ошибки при обнаружении невалидного JSON. Он возвращает список словарей, где каждый словарь представляет собой успешно обработанный объект.
+*   **Обработка JSON**: Метод `parse_json` парсит входные данные JSON, используя стандартную библиотеку `json`. Он возвращает объект Python, соответствующий структуре JSON.
+*   **Валидация схемы**: Функция `validate` проверяет, соответствует ли объект заданным требованиям JSON Schema.
+*   **Формат вывода**: Метод `PromptManager.invoke` возвращает список словарей Python, где каждый словарь представляет собой успешно обработанный объект.
+*   **Обработка ошибок**:
+    *   Если входные данные JSONL не валидны или результат обрезания, метод возвращает пустой список (`[]`).
+    *   Если при валидации схемы произошла ошибка, метод возвращает пустой список (`[]`) и выводит предупреждающие сообщения в лог.
+    *   Если произошла ошибка парсинга JSON, метод выводит ошибку и выбрасывает исключение.
+*   **Совместимость**:
+    *   Клиентский код, ожидающий список в качестве результата извлечения, не требует изменений при переходе на JSONL.
+    *   Формат вывода для `response-type: "json"` (массив) и `response-type: "jsonl"` (список) одинаковый: Python `list`
+*   **API изменения**:
+    *   **Клиентская перспектива**: Разбор JSONL выполняется на стороне сервера в сервисе запросов, и результат возвращается через стандартное поле `PromptResponse.object` в виде сериализованного JSON-массива.
+    *   **Формат возвращаемого значения**: Для `response-type: "jsonl"`, метод `PromptManager.invoke()` возвращает `list[dict]`, содержащий все успешно обработанные объекты. Этот список сериализуется в JSON для поля `PromptResponse.object`.
+    *   **Обработка ошибок**:
+        *   Пустой результат: возвращает пустой список `[]` с сообщением в логе
+        *   Частичная ошибка парсинга: возвращает список успешно обработанных объектов с сообщениями об ошибках
+        *   Полная ошибка парсинга: возвращает пустой список `[]` с сообщениями об ошибках
+*   **Пример конфигурации**:
+
+    ```json
+    {
+      "prompt": "Извлеките все сущности и их определения из следующего текста. Выведите один JSON объект на строку.\n\nТекст:\n{{text}}\n\nФормат вывода на строку:\n{\"entity\": \"<name>\", \"definition\": \"<definition>\"}",
+      "response-type": "jsonl",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "entity": {
+            "type": "string",
+            "description": "Имя сущности"
+          },
+          "definition": {
+            "type": "string",
+            "description": "Четкое определение сущности"
+          }
+        },
+        "required": ["entity", "definition"]
+      }
+    }
+    ```
+*   **Изменения в запросах**:
+
+| ID запроса | Описание | Поле типа |
+|---|---|---|
+| `extract-definitions` | Извлечение всех сущностей и их определений из следующего текста. Выведите один JSON объект на строку. | Нет (один тип) |
+| `extract-relationships` | Извлечение взаимосвязей | Нет (один тип) |
+| `extract-topics` | Извлечение темы и определений | Нет (один тип) |
+| `extract-rows` | Извлечение структурированных строк | Нет (один тип) |
+| `agent-kg-extract` | Совместное извлечение определения и взаимосвязи | Да: `"definition"`, `"relationship"` |
+| `extract-with-ontologies` / `ontology-extract` | Извлечение на основе онтологий | Да: `"entity"`, `"relationship"`, `"attribute"` |
+
+## Безопасность
+
+*   **Валидация входных данных**: Используется стандартная библиотека `json.loads()` для парсинга, что безопасно от возможных атак внедрением.
+*   **Валидация схемы**: Используется `jsonschema.validate()` для проверки соответствия схемы.
+*   **Отсутствие новых уязвимостей**: Разбор JSONL безопаснее, чем разбор JSON-массивов, из-за построчной обработки.
+
+## Производительность
+
+*   **Память**: Построчный разбор требует меньше памяти, чем загрузка всего JSON-массива.
+*   **Задержка**: Производительность парсинга сопоставима с разбором JSON-массивов.
+*   **Валидация**: Валидация объекта происходит для каждого объекта, что может привести к накладным расходам, но обеспечивает частичную валидацию при ошибках.
+
+## Стратегия тестирования
+
+*   **Юнит-тесты**:
+    *   Разбор JSONL с валидными данными
+    *   Разбор JSONL с пустыми строками
+    *   Разбор JSONL с маркерами markdown
+    *   Разбор JSONL с обрезаными последними строками
+    *   Разбор JSONL с невалидным JSON
+    *   Валидация схемы с использованием `oneOf`
+    *   Совместимость: существующие запросы `"text"` и `"json"` не изменяются
+*   **Интеграционные тесты**:
+    *   Извлечение с JSONL-запросами
+    *   Симулированное обрезание ответа LLM (искусственно ограниченный ответ)
+    *   Извлечение нескольких типов сущностей с использованием поля типа
+    *   Извлечение на основе онтологий
+*   **Тесты качества извлечения**:
+    *   Сравнение результатов извлечения: JSONL vs JSON
+    *   Проверка на надежное извлечение при обрезании: JSONL дает частичные результаты, где JSON не работает
+
+## Вопросы
+
+В настоящее время вопросов нет.
+
+## Ссылки
+
+*   Реализация: `trustgraph-flow/trustgraph/template/prompt_manager.py`
+*   Спецификация JSON Lines: https://jsonlines.org/
+*   Спецификация JSON Schema `oneOf`: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
+*   Связанная спецификация: Streaming LLM Responses (`docs/tech-specs/streaming-llm-responses.md`)

docs/tech-specs/jsonl-prompt-output.zh-cn.md

@@ -0,0 +1,172 @@
+## JSONL 提示输出技术规范
+
+## 概述
+
+本规范描述了在 TrustGraph 中实现 JSONL (JSON Lines) 输出格式的提示响应。JSONL 允许以容错的方式从 LLM 响应中提取结构化数据，从而解决了 JSON 数组输出在 LLM 响应达到输出令牌限制时发生损坏的问题。
+
+此实现支持以下用例：
+
+1. **容错提取**: 即使 LLM 输出被截断，仍可提取有效的部分结果
+2. **大规模提取**: 能够在不因令牌限制而完全失败的情况下，处理大量项的提取
+3. **混合类型提取**: 支持在单个提示中提取多种实体类型（定义、关系、实体、属性）
+4. **流兼容输出**: 启用提取结果的未来流式/增量处理
+
+## 目标
+
+- **向后兼容性**: 使用 `response-type: "text"` 和 `response-type: "json"` 的现有提示无需修改即可继续工作
+- **容错提取**: 部分 LLM 输出产生部分有效的结果，而不是完全失败
+- **模式验证**: 支持对单个对象进行 JSON 模式验证
+- **区分联合**: 使用 `type` 字段作为区分器，支持混合类型输出
+- **最小的 API 更改**: 通过添加新的响应类型和模式键来扩展现有提示配置
+
+## 背景
+
+### 当前架构
+
+提示服务支持两种响应类型：
+
+1. `response-type: "text"` - 原始文本响应作为是返回
+2. `response-type: "json"` - 从响应中解析，并根据可选的 `schema` 进行验证
+
+### 影响的提示
+
+以下提示应迁移到 JSONL 格式：
+
+| 提示 ID | 描述 | 类型字段 |
+|---|---|---|
+| `extract-definitions` | 提取所有实体及其定义 | 无 (单个类型) |
+| `extract-relationships` | 提取关系 | 无 (单个类型) |
+| `extract-topics` | 提取主题/定义 | 无 (单个类型) |
+| `extract-rows` | 提取结构化行 | 无 (单个类型) |
+| `agent-kg-extract` | 组合定义 + 关系提取 | 是: `"definition"`, `"relationship"` |
+| `extract-with-ontologies` / `ontology-extract` | 提取本体 | 是: `"entity"`, `"relationship"`, `"attribute"` |
+
+### API 更改
+
+#### 客户端视角
+
+JSONL 解析对提示服务调用者透明。解析发生在提示服务内部，响应通过标准 `PromptResponse.object` 字段作为序列化的 JSON 数组返回。
+
+当客户端调用提示服务（通过 `PromptClient.prompt()` 或类似方法）时：
+
+- `response-type: "json"` (带数组模式) → 客户端接收 Python `list`
+- `response-type: "jsonl"` → 客户端接收 Python `list`
+
+从客户端的视角来看，两者都返回相同的数据结构。 区别在于 LLM 响应如何在服务器端进行解析：
+
+- JSON 数组格式：执行一个 `json.loads()` 调用；如果被截断则完全失败
+- JSONL 格式：逐行解析；如果被截断则产生部分结果
+
+这意味着预期的以 JSON 格式返回提取结果的代码，无需在迁移到 JSONL 格式的提示时进行更改。
+
+#### 服务器返回值
+
+对于 `response-type: "jsonl"`，`PromptManager.invoke()` 方法返回一个 `list[dict]`，其中包含成功解析和验证的对象。 此列表随后通过 `PromptResponse.object` 字段作为 JSON 序列化。
+
+#### 错误处理
+
+- 无结果: 返回空列表 `[]`，带有警告日志
+- 部分解析失败: 返回成功解析对象的列表，带有失败的警告日志
+- 完全解析失败: 返回空列表 `[]`，带有警告日志
+
+与 `response-type: "json"` 相比，这种行为是故意的，旨在提供容错性。
+
+### 性能考虑
+
+- 内存：逐行解析比加载完整的 JSON 数组使用更少的峰值内存
+- 延迟：解析的性能与 JSON 数组解析相似
+- 验证：按对象运行模式验证，这会增加开销，但允许在验证失败时产生部分结果
+
+## 测试策略
+
+### 单元测试
+
+- JSONL 格式的有效输入解析
+- 空行的 JSONL 解析
+- Markdown 代码块的 JSONL 解析
+- 最后的行被截断的 JSONL 解析
+- 无效 JSON 行的 JSONL 解析
+- 带有 `oneOf` 的区分联合的模式验证
+- 现有 `"text"` 和 `"json"` 提示的向后兼容性
+
+### 集成测试
+
+- 使用 JSONL 提示的端到端提取
+- 模拟截断响应（人为限制响应）
+- 使用类型区分器的混合类型提取
+- 使用所有三种类型的本体提取
+
+### 提取质量测试
+
+- 比较 JSONL 和 JSON 数组格式的提取结果
+- 验证容错性: JSONL 在被截断时产生部分结果，而 JSON 失败
+- 验证混合类型提取的类型字段
+
+### 迁移计划
+
+### 阶段 1：实现
+
+1. 在 `PromptManager` 中实现 `parse_jsonl()` 方法
+2. 扩展 `invoke()` 以处理 `response-type: "jsonl"`
+3. 添加单元测试
+
+### 阶段 2：提示迁移
+
+1. 迁移 `extract-definitions` 提示和配置
+2. 迁移 `extract-relationships` 提示和配置
+3. 迁移 `extract-topics` 提示和配置
+4. 迁移 `extract-rows` 提示和配置
+5. 迁移 `agent-kg-extract` 提示和配置
+6. 迁移 `extract-with-ontologies` 提示和配置
+
+### 阶段 3：下游更新
+
+1. 更新消费提取结果的代码以处理列表返回类型
+2. 更新对按 `type` 字段对混合类型提取进行分类的代码
+3. 更新断言提取结果格式的测试
+
+## 安全考虑
+
+- 输入验证：使用标准 `json.loads()` 进行 JSON 解析，这可以防止注入攻击
+- 模式验证：使用 `jsonschema.validate()` 进行模式强制
+- 无新攻击面：逐行解析比 JSON 数组解析更安全，因为它不会导致问题
+
+## 性能考虑
+
+- 内存：逐行解析使用更少的峰值内存，而不是加载完整的 JSON 数组
+- 延迟：解析性能与 JSON 数组解析相似
+- 验证：按对象运行模式验证，这会增加开销，但允许在验证失败时产生部分结果
+
+## 迁移计划
+
+### 阶段 1：实现
+
+1. 在 `PromptManager` 中实现 `parse_jsonl()` 方法
+2. 扩展 `invoke()` 以处理 `response-type: "jsonl"`
+3. 添加单元测试
+
+### 阶段 2：提示迁移
+
+1. 迁移 `extract-definitions` 提示和配置
+2. 迁移 `extract-relationships` 提示和配置
+3. 迁移 `extract-topics` 提示和配置
+4. 迁移 `extract-rows` 提示和配置
+5. 迁移 `agent-kg-extract` 提示和配置
+6. 迁移 `extract-with-ontologies` 提示和配置
+
+### 阶段 3：下游更新
+
+1. 更新消费提取结果的代码以处理列表返回类型
+2. 更新对按 `type` 字段对混合类型提取进行分类的代码
+3. 更新断言提取结果格式的测试
+
+## 开放问题
+
+目前没有。
+
+## 参考
+
+- 当前实现：`trustgraph-flow/trustgraph/template/prompt_manager.py`
+- JSON Lines 规范：https://jsonlines.org/
+- JSON Schema `oneOf`：https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
+- 相关规范：流式 LLM 响应 (`docs/tech-specs/streaming-llm-responses.md`)

docs/tech-specs/logging-strategy.es.md

@@ -0,0 +1,207 @@
+# Estrategia de Registro de TrustGraph
+
+## Visión general
+
+TrustGraph utiliza el módulo integrado de Python `logging` para todas las operaciones de registro, con una configuración centralizada y la integración opcional de Loki para la agregación de registros. Esto proporciona un enfoque estandarizado y flexible para el registro en todos los componentes del sistema.
+
+## Configuración predeterminada
+
+### Nivel de registro
+- **Nivel predeterminado**: `INFO`
+- **Configurable a través de**: Argumento de línea de comandos `--log-level`
+- **Opciones**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+### Destinos de salida
+1. **Consola (stdout)**: Siempre habilitado - asegura la compatibilidad con entornos contenedorizados
+2. **Loki**: Agregación centralizada de registros opcional (habilitado por defecto, se puede deshabilitar)
+
+## Módulo de registro centralizado
+
+Todas las configuraciones de registro se gestionan mediante el módulo `trustgraph.base.logging`, que proporciona:
+- `add_logging_args(parser)` - Agrega argumentos de línea de comandos estándar para registro
+- `setup_logging(args)` - Configura el registro a partir de los argumentos analizados
+
+Este módulo se utiliza en todos los componentes del lado del servidor:
+- Servicios basados en AsyncProcessor
+- API Gateway
+- Servidor MCP
+
+## Guía de implementación
+
+### 1. Inicialización del registrador
+
+Cada módulo debe crear su propio registrador utilizando el nombre del módulo:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+El nombre del registrador se utiliza automáticamente como etiqueta en Loki para filtrar y buscar.
+
+### 2. Inicialización del servicio
+
+Todos los servicios del lado del servidor obtienen automáticamente la configuración de registro a través del módulo centralizado:
+
+```python
+from trustgraph.base import add_logging_args, setup_logging
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser()
+
+    # Agrega argumentos estándar de registro (incluida la configuración de Loki)
+    add_logging_args(parser)
+
+    # Agrega tus argumentos específicos del servicio
+    parser.add_argument('--port', type=int, default=8080)
+
+    args = parser.parse_args()
+    args = vars(args)
+
+    # Configura el registro temprano en el inicio
+    setup_logging(args)
+
+    # Resto de la inicialización del servicio
+    logger = logging.getLogger(__name__)
+    logger.info("Servicio iniciado...")
+```
+
+### 3. Argumentos de línea de comandos
+
+Todos los servicios admiten estos argumentos de registro:
+
+**Nivel de registro:**
+```bash
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+```
+
+**Configuración de Loki:**
+```bash
+--loki-enabled              # Habilita Loki (predeterminado)
+--no-loki-enabled           # Deshabilita Loki
+--loki-url URL              # URL de envío a Loki (predeterminado: http://loki:3100/loki/api/v1/push)
+--loki-username USERNAME    # Nombre de usuario opcional de autenticación
+--loki-password PASSWORD    # Contraseña opcional de autenticación
+```
+
+**Ejemplos:**
+```bash
+# Predeterminado - nivel INFO, Loki habilitado
+./my-service
+
+# Modo DEBUG, solo consola
+./my-service --log-level DEBUG --no-loki-enabled
+
+# URL de Loki personalizada con autenticación
+./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
+             --loki-username admin --loki-password secret
+```
+
+### 4. Variables de entorno
+
+La configuración de Loki admite los valores predeterminados de las variables de entorno:
+
+```bash
+export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
+export LOKI_USERNAME=admin
+export LOKI_PASSWORD=secret
+```
+
+Los argumentos de la línea de comandos tienen prioridad sobre las variables de entorno.
+
+### 5. Mejores prácticas de registro
+
+#### Uso de los niveles de registro
+- **DEBUG**: Información detallada para diagnosticar problemas (valores de variables, entrada/salida de funciones)
+- **INFO**: Mensajes informativos generales (servicio iniciado, configuración cargada, hitos de procesamiento)
+- **WARNING**: Mensajes de advertencia para situaciones potencialmente dañinas (características obsoletas, errores recuperables)
+- **ERROR**: Mensajes de error para problemas serios (operaciones fallidas, excepciones)
+- **CRITICAL**: Mensajes críticos para fallas del sistema que requieren atención inmediata
+
+#### Formato de mensaje
+```python
+# Bueno - incluye contexto
+logger.info(f"Procesando documento: {doc_id}, tamaño: {doc_size} bytes")
+logger.error(f"No se pudo conectar a la base de datos: {error}", exc_info=True)
+
+# No bueno - carece de contexto
+logger.info("Procesando documento")
+logger.error("Conexión fallida")
+```
+
+#### Consideraciones de rendimiento
+```python
+# Usa la incrustación para operaciones costosas
+logger.debug("Resultado de la operación costosa: %s", expensive_function())
+
+# Comprueba el nivel de registro para operaciones de depuración muy costosas
+if logger.isEnabledFor(logging.DEBUG):
+    debug_data = compute_expensive_debug_info()
+    logger.debug(f"Datos de depuración: {debug_data}")
+```
+
+#### 6. Registro estructurado con Loki
+
+Para datos complejos, usa el registro estructurado con etiquetas adicionales para Loki:
+
+```python
+logger.info("Solicitud procesada", extra={
+    'tags': {
+        'request_id': request_id,
+        'user_id': user_id,
+        'status': 'éxito'
+    }
+})
+```
+
+Estas etiquetas se convierten en etiquetas de búsqueda en Loki, además de las etiquetas automáticas:
+- `severity` - Nivel de registro (DEBUG, INFO, etc.)
+- `logger` - Nombre del módulo (del `__name__`)
+
+### 7. Registro de excepciones
+
+Siempre incluye trazas de pila para las excepciones:
+
+```python
+try:
+    process_data()
+except Exception as e:
+    logger.error(f"No se pudo procesar los datos: {e}", exc_info=True)
+```
+
+### 8. Dependencias
+
+El módulo centralizado de registro requiere:
+- `python-logging-loki` - Para la integración de Loki (opcional, funciona si falta)
+
+Ya incluido en `trustgraph-base/pyproject.toml` y `requirements.txt`.
+
+## Migración
+
+Para código existente:
+
+1. **Servicios que ya utilizan AsyncProcessor**: No se necesita cambios, la integración de Loki es automática
+2. **Servicios que no utilizan AsyncProcessor** (api-gateway, mcp-server): Ya actualizado
+3. **Herramientas de línea de comandos**: Fuera del alcance - continúe usando `print()` o registro simple
+
+### De `print()` a registro:
+```python
+# Antes
+print(f"Procesando documento {doc_id}")
+
+# Después
+logger = logging.getLogger(__name__)
+logger.info(f"Procesando documento {doc_id}")
+```
+
+## Resumen de configuración
+
+| Argumento | Predeterminado | Variable de entorno | Descripción |
+|---|---|---|---|
+| `--log-level` | `INFO` | - | Nivel de registro en la consola y Loki |
+| `--loki-enabled` | `True` | - | Habilita el registro de Loki |
+| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | Puntero al API de Loki |
+| `--loki-username` | `None` | `LOKI_USERNAME` | Nombre de usuario de autenticación para Loki |
+| `--loki-password` | `None` | `LOKI_PASSWORD` | Contraseña de autenticación para Loki |

docs/tech-specs/logging-strategy.ru.md

@@ -0,0 +1,205 @@
+# Стратегия логирования TrustGraph
+
+## Обзор
+
+TrustGraph использует встроенный модуль `logging` Python для всех операций логирования, с централизованной конфигурацией и опциональной интеграцией с Loki для агрегации логов. Это обеспечивает стандартизированный и гибкий подход к логированию для всех компонентов системы.
+
+## Параметры конфигурации по умолчанию
+
+### Уровень логирования
+- **Уровень по умолчанию**: `INFO`
+- **Указывается через**: аргумент командной строки `--log-level`
+- **Возможные значения**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+### Направления вывода
+1. **Консоль (stdout)**: Всегда включено - обеспечивает совместимость с контейнерными средами
+2. **Loki**: Опциональная централизованная агрегация логов (включена по умолчанию, может быть отключена)
+
+## Модуль централизованного логирования
+
+Вся конфигурация логирования управляется модулем `trustgraph.base.logging`, который предоставляет:
+- `add_logging_args(parser)` - Добавляет стандартные аргументы командной строки для логирования
+- `setup_logging(args)` - Настраивает логирование на основе предоставленных аргументов
+
+Этот модуль используется всеми серверными компонентами:
+- Сервисы, основанные на AsyncProcessor
+- API Gateway
+- Сервер MCP
+
+## Рекомендации по реализации
+
+### 1. Инициализация логгера
+
+Каждый модуль должен создавать свой собственный логгер, используя `__name__` модуля:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+Имя логгера автоматически используется как метка в Loki для фильтрации и поиска.
+
+### 2. Инициализация сервиса
+
+Все серверные сервисы автоматически получают конфигурацию логирования через централизованный модуль:
+
+```python
+from trustgraph.base import add_logging_args, setup_logging
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser()
+
+    # Добавляем стандартные аргументы логирования (включая конфигурацию Loki)
+    add_logging_args(parser)
+
+    # Добавляем свои аргументы для сервиса
+    parser.add_argument('--port', type=int, default=8080)
+
+    args = parser.parse_args()
+    args = vars(args)
+
+    # Настраиваем логирование в начале запуска
+    setup_logging(args)
+
+    # Остальная часть инициализации сервиса
+    logger = logging.getLogger(__name__)
+    logger.info("Сервис запущен...")
+```
+
+### 3. Аргументы командной строки
+
+Все сервисы поддерживают следующие аргументы логирования:
+
+**Уровень логирования:**
+```bash
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+```
+
+**Конфигурация Loki:**
+```bash
+--loki-enabled              # Включить Loki (по умолчанию)
+--no-loki-enabled           # Отключить Loki
+--loki-url URL              # URL для отправки логов в Loki (по умолчанию: http://loki:3100/loki/api/v1/push)
+--loki-username USERNAME    # Необязательное имя пользователя для аутентификации
+--loki-password PASSWORD    # Необязательный пароль для аутентификации
+```
+
+**Примеры:**
+```bash
+# По умолчанию - уровень INFO, Loki включен
+./my-service
+
+# Режим отладки, только консоль
+./my-service --log-level DEBUG --no-loki-enabled
+
+# Пользовательский сервер Loki с аутентификацией
+./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
+             --loki-username admin --loki-password secret
+```
+
+### 4. Переменные окружения
+
+Конфигурация Loki поддерживает использование переменных окружения:
+
+```
+export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
+export LOKI_USERNAME=admin
+export LOKI_PASSWORD=secret
+```
+
+Аргументы командной строки имеют приоритет над переменными окружения.
+
+### 5. Рекомендации по логированию
+
+#### Использование уровней логирования
+- **DEBUG**: Детальная информация для диагностики проблем (значения переменных, вход/выход функций)
+- **INFO**: Общие информационные сообщения (запуск сервиса, загрузка конфигурации, этапы обработки)
+- **WARNING**: Предупреждающие сообщения о потенциально опасных ситуациях (устаревшие функции, восстанавливаемые ошибки)
+- **ERROR**: Сообщения об ошибках о серьезных проблемах (неудачные операции, исключения)
+- **CRITICAL**: Критические сообщения о системных сбоях, требующих немедленного внимания
+
+#### Формат сообщений
+```python
+# Хорошо - включает контекст
+logger.info(f"Обработка документа: {doc_id}, размер: {doc_size} байт")
+logger.error(f"Не удалось подключиться к базе данных: {error}", exc_info=True)
+
+# Плохо - не включает контекст
+logger.info("Обработка документа")
+logger.error("Не удалось подключиться")
+```
+
+#### Соображения производительности
+```python
+# Используйте ленивую адресацию для дорогостоящих операций
+logger.debug("Результат дорогостоящей операции: %s", expensive_function())
+
+# Проверяйте уровень логирования для очень дорогих операций DEBUG
+if logger.isEnabledFor(logging.DEBUG):
+    debug_data = compute_expensive_debug_info()
+    logger.debug(f"Данные для отладки: {debug_data}")
+```
+
+### 6. Структурированное логирование с использованием Loki
+
+Для сложных данных используйте структурированное логирование с дополнительными метками для Loki:
+
+```python
+logger.info("Запрос обработан", extra={
+    'tags': {
+        'request_id': request_id,
+        'user_id': user_id,
+        'status': 'успешно'
+    }
+})
+```
+
+Эти метки становятся поисковыми метками в Loki, а также автоматически создаваемыми:
+- `severity` - Уровень логирования (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- `logger` - Имя модуля (из `__name__`)
+
+### Зависимости
+
+Модуль централизованного логирования требует:
+- `python-logging-loki` - Для интеграции с Loki (необязательно, функционирует без него)
+
+Уже включен в `trustgraph-base/pyproject.toml` и `requirements.txt`.
+
+## Переход
+
+Для существующего кода:
+
+1. **Сервисы, уже использующие AsyncProcessor**: Не требуется никаких изменений, интеграция с Loki автоматическая
+2. **Сервисы, которые не используют AsyncProcessor** (api-gateway, mcp-server): Уже обновлены
+3. **Инструменты командной строки**: Не относится - продолжайте использовать `print()` или простое логирование
+
+### Переход от `print()` к `logging`:
+```python
+# Предыдущий код
+print(f"Обработка документа {doc_id}")
+
+# Новый код
+import logging
+logger = logging.getLogger(__name__)
+logger.info(f"Обработка документа {doc_id}")
+```
+
+## Безопасность
+
+- **Никогда не логируйте конфиденциальную информацию** (пароли, API-ключи, персональные данные, токены)
+- **Фильтруйте пользовательский ввод** перед логированием
+- **Используйте плейсхолдеры** для конфиденциальных полей: `user_id=****1234`
+- **Используйте аутентификацию** для Loki с помощью `--loki-username` и `--loki-password` в производственной среде
+- **Безопасный транспорт**: Используйте HTTPS для URL Loki в производственной среде: `https://loki.prod:3100/loki/api/v1/push`
+
+## Обзор конфигурации
+
+| Аргумент | Значение по умолчанию | Переменная окружения | Описание |
+|---|---|---|---|
+| `--log-level` | `INFO` | - | Уровень логирования в консоли и Loki |
+| `--loki-enabled` | `True` | - | Включить логирование Loki |
+| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | URL для отправки логов в Loki |
+| `--loki-username` | `None` | `LOKI_USERNAME` | Имя пользователя для аутентификации Loki |
+| `--loki-password` | `None` | `LOKI_PASSWORD` | Пароль для аутентификации Loki |

docs/tech-specs/logging-strategy.zh-cn.md

@@ -0,0 +1,223 @@
+## TrustGraph 日志策略
+
+## 概述
+
+TrustGraph 使用 Python 内置的 `logging` 模块进行所有日志操作，并具有集中配置以及可选的 Loki 集成，用于日志聚合。 这提供了一种标准且灵活的方式，可在系统的所有组件中进行日志记录。
+
+## 默认配置
+
+### 日志级别
+- **默认级别**: `INFO`
+- **可通过**: `--log-level` 命令行参数配置
+- **选项**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+### 输出目标
+1. **控制台 (stdout)**: 始终启用 - 确保与容器化环境兼容
+2. **Loki**: 可选的集中式日志聚合 (默认启用，可禁用)
+
+## 集中式日志模块
+
+所有日志配置都由 `trustgraph.base.logging` 模块管理，该模块提供：
+- `add_logging_args(parser)` - 添加标准的日志 CLI 参数
+- `setup_logging(args)` - 从解析的参数配置日志
+
+该模块用于所有服务器端组件：
+- 基于 AsyncProcessor 的服务
+- API 网关
+- MCP 服务器
+
+## 实现指南
+
+### 1. 日志记录器初始化
+
+每个模块应使用模块的 `__name__` 创建自己的日志记录器：
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+日志记录器的名称会自动用作在 Loki 中用于过滤和搜索的标签。
+
+### 2. 服务初始化
+
+所有服务器端服务都通过集中化模块自动获取日志配置：
+
+```python
+from trustgraph.base import add_logging_args, setup_logging
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser()
+
+    # 添加标准的日志参数 (包括 Loki 配置)
+    add_logging_args(parser)
+
+    # 添加您自己的服务特定的参数
+    parser.add_argument('--port', type=int, default=8080)
+
+    args = parser.parse_args()
+    args = vars(args)
+
+    # 提前设置日志
+    setup_logging(args)
+
+    # 剩余的服务初始化
+    logger = logging.getLogger(__name__)
+    logger.info("服务开始...")
+```
+
+### 3. 命令行参数
+
+所有服务都支持以下日志参数：
+
+**日志级别:**
+```bash
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+```
+
+**Loki 配置:**
+```bash
+--loki-enabled              # 启用 Loki (默认)
+--no-loki-enabled           # 禁用 Loki
+--loki-url URL              # Loki 推送 URL (默认: http://loki:3100/loki/api/v1/push)
+--loki-username USERNAME    # 可选身份验证
+--loki-password PASSWORD    # 可选身份验证
+```
+
+**示例:**
+```bash
+# 默认 - INFO 级别，启用 Loki
+./my-service
+
+# 调试模式，仅控制台
+./my-service --log-level DEBUG --no-loki-enabled
+
+# 自定义 Loki 服务器，带身份验证
+./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
+             --loki-username admin --loki-password secret
+```
+
+### 4. 环境变量
+
+Loki 配置支持环境变量的后备：
+
+```bash
+export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
+export LOKI_USERNAME=admin
+export LOKI_PASSWORD=secret
+```
+
+命令行参数优先于环境变量。
+
+### 5. 日志记录最佳实践
+
+#### 日志级别使用
+- **DEBUG**: 用于诊断问题的详细信息 (变量值、函数入口/退出)
+- **INFO**: 通用信息消息 (服务启动、配置加载、处理里程碑)
+- **WARNING**: 警告消息，用于潜在的危险情况 (弃用功能、可恢复错误)
+- **ERROR**: 错误消息，用于严重问题 (失败的操作、异常)
+- **CRITICAL**: 关键消息，用于系统故障，需要立即关注
+
+#### 消息格式
+```python
+# 良好 - 包含上下文
+logger.info(f"处理文档: {doc_id}, 大小: {doc_size} 字节")
+logger.error(f"无法连接到数据库: {error}", exc_info=True)
+
+# 不好 - 缺少上下文
+logger.info("处理文档")
+logger.error("连接失败")
+```
+
+#### 性能考虑
+```python
+# 使用延迟格式化进行昂贵的操作
+logger.debug("昂贵操作结果: %s", expensive_function())
+
+# 检查日志级别以进行非常昂贵的调试操作
+if logger.isEnabledFor(logging.DEBUG):
+    debug_data = compute_expensive_debug_info()
+    logger.debug(f"调试数据: {debug_data}")
+```
+
+### 6. 使用 Loki 的结构化日志记录
+
+对于复杂的结构化数据，可以使用结构化日志记录，并添加额外的标签以供 Loki 使用：
+
+```python
+logger.info("请求已处理", extra={
+    'tags': {
+        'request_id': request_id,
+        'user_id': user_id,
+        'status': 'success'
+    }
+})
+```
+
+这些标签将作为 Loki 中的可搜索标签：
+- `severity` - 日志级别 (DEBUG, INFO, 等)
+- `logger` - 模块名称 (来自 `__name__`)
+
+### 7. 异常日志记录
+
+始终包含异常堆栈跟踪：
+
+```python
+try:
+    process_data()
+except Exception as e:
+    logger.error(f"无法处理数据: {e}", exc_info=True)
+    raise
+```
+
+### 8. 异步日志记录的注意事项
+
+日志系统使用非阻塞的队列处理程序进行 Loki 集成：
+- 控制台输出是同步的 (快速)
+- Loki 输出是异步排队 (500 条消息缓冲区)
+- 后台线程处理 Loki 传输
+- 没有阻塞主应用程序代码
+
+```python
+import asyncio
+import logging
+
+async def async_operation():
+    logger = logging.getLogger(__name__)
+    # 日志记录是线程安全的，不会阻塞异步操作
+    logger.info(f"在任务中开始异步操作: {asyncio.current_task().get_name()}")
+```
+
+## Loki 集成
+
+### 架构
+
+日志系统使用 Python 内置的 `logging` 模块进行 Loki 集成：
+- `python-logging-loki` - 用于 Loki 集成 (可选，如果缺少则回退)
+
+已经在 `trustgraph-base/pyproject.toml` 和 `requirements.txt` 中包含。
+
+### 从 print() 到 logging：
+```python
+# 之前
+print(f"处理文档 {doc_id}")
+
+# 之后
+logger = logging.getLogger(__name__)
+logger.info(f"处理文档 {doc_id}")
+```
+
+## 安全注意事项
+
+- **永远不要记录敏感信息** (密码、API 密钥、个人数据、令牌)
+- **清理用户输入** 之前进行日志记录
+- **使用占位符** 来记录敏感字段： `user_id=****1234`
+- **使用 Loki 身份验证**： 对于生产环境，使用 `--loki-username` 和 `--loki-password`
+- **安全传输**： 在生产中使用 HTTPS： `https://loki.prod:3100/loki/api/v1/push`
+
+## 依赖
+
+集中式日志模块需要：
+- `python-logging-loki` - 用于 Loki 集成 (可选，如果缺失则回退)

docs/tech-specs/mcp-tool-arguments.ar.md

@@ -0,0 +1,155 @@
+# مواصفات معاملات أداة MCP
+
+## نظرة عامة
+**اسم الميزة**: دعم معاملات أداة MCP
+**المؤلف**: مساعد كود كلوود
+**التاريخ**: 2025-08-21
+**الحالة**: نهائية
+
+### ملخص تنفيذي
+
+تمكين عوامل ReACT من استدعاء أدوات MCP (بروتوكول سياق النموذج) مع المعاملات المحددة بشكل صحيح عن طريق إضافة دعم مواصفات المعاملات إلى تكوينات أدوات MCP، على غرار الطريقة التي تعمل بها أدوات القالب الحالية.
+
+### بيان المشكلة
+
+في الوقت الحالي، لا يمكن لأدوات MCP في إطار عمل ReACT تحديد المعاملات المتوقعة. تُرجع طريقة `McpToolImpl.get_arguments()` قائمة فارغة، مما يجبر نماذج اللغة الكبيرة (LLMs) على تخمين هيكل المعلمات بناءً على أسماء وأوصاف الأدوات فقط. هذا يؤدي إلى:
+- استدعاء أدوات غير موثوق به بسبب تخمين المعلمات
+- تجربة مستخدم سيئة عندما تفشل الأدوات بسبب معاملات غير صحيحة
+- عدم التحقق من معلمات الأداة قبل التنفيذ
+- عدم وجود توثيق لمعلمات الأداة في مطالبات الوكيل
+
+### الأهداف
+
+- [ ] السماح بتكوينات أدوات MCP بتحديد المعاملات المتوقعة (الاسم، النوع، الوصف)
+- [ ] تحديث مدير الوكيل للكشف عن معاملات أداة MCP لـ LLMs عبر المطالبات
+- [ ] الحفاظ على التوافق مع الإصدارات الحالية من تكوينات أدوات MCP
+- [ ] دعم التحقق من صحة المعاملات على غرار أدوات القالب
+
+### الأهداف غير المحققة
+- اكتشاف ديناميكي للمعاملات من خوادم MCP (تحسين مستقبلي)
+- التحقق من نوع المعاملات بالإضافة إلى الهيكل الأساسي
+- مخططات المعاملات المعقدة (الكائنات المتداخلة، المصفوفات)
+
+## الخلفية والسياق
+
+### الحالة الحالية
+يتم تكوين أدوات MCP في نظام ReACT مع بيانات وصفية قليلة:
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance",
+  "description": "Get bank account balance",
+  "mcp-tool": "get_bank_balance"
+}
+```
+
+تُرجع طريقة `McpToolImpl.get_arguments()` قائمة فارغة، لذلك لا تتلقى LLMs أي إرشادات حول المعاملات في مطالباتها.
+
+### القيود
+
+1. **عدم وجود مواصفات للمعاملات**: لا يمكن لأدوات MCP تحديد المعلمات المتوقعة
+
+2. **تخمين المعلمات بواسطة LLM**: يجب على الوكلاء استنتاج المعلمات من أسماء/وصف الأدوات
+
+3. **نقص معلومات المطالبة**: لا تعرض مطالبات الوكيل تفاصيل المعاملات لأدوات MCP
+
+4. **عدم التحقق**: يتم التقاط المعلمات غير الصالحة فقط عند وقت تنفيذ أداة MCP
+
+### المكونات ذات الصلة
+- **trustgraph-flow/agent/react/service.py**: تحميل تكوين الأداة وإنشاء AgentManager
+- **trustgraph-flow/agent/react/tools.py**: تنفيذ McpToolImpl
+- **trustgraph-flow/agent/react/agent_manager.py**: إنشاء المطالبات بمعاملات الأداة
+- **CLI tools**: أدوات سطر الأوامر لإدارة أدوات MCP
+- **Workbench**: واجهة المستخدم الخارجية لتكوين أدوات الوكيل
+
+## المتطلبات
+
+### المتطلبات الوظيفية
+
+1. **معاملات أداة MCP**: يجب أن تدعم تكوينات أدوات MCP مصفوفة اختيارية "arguments" مع حقول الاسم والنوع والوصف
+2. **الكشف عن المعاملات**: يجب أن تُرجع طريقة `McpToolImpl.get_arguments()` المعاملات المحددة بدلاً من قائمة فارغة
+3. **التكامل مع المطالبة**: يجب أن تتضمن المطالبات الخاصة بالوكيل تفاصيل معامل أداة MCP عند تحديد المعاملات
+4. **التوافق مع الإصدارات الحالية**: يجب أن تستمر تكوينات أدوات MCP الحالية بدون معاملات في العمل
+5. **دعم CLI**: يدعم CLI الحالي `tg-invoke-mcp-tool` المعاملات (مُنفذ بالفعل)
+
+### المتطلبات غير الوظيفية
+1. **التوافق مع الإصدارات الحالية**: لا توجد تغييرات مدمرة في تكوينات أدوات MCP الحالية
+2. **الأداء**: عدم وجود تأثير كبير على توليد المطالبات للوكلاء
+3. **الاتساق**: يجب أن يطابق معالجة المعاملات أنماط أدوات القالب
+
+### قصص المستخدم
+
+1. بصفتي **مطور الوكيل**: أرغب في تحديد معاملات أداة MCP في التكوين حتى تتمكن نماذج اللغة الكبيرة من استدعاء الأدوات بمعلمات صحيحة
+2. بصفتي **مستخدم واجهة Workbench**: أرغب في تكوين معاملات أداة MCP في واجهة المستخدم حتى تستخدم الوكلاء الأدوات بشكل صحيح
+3. بصفتي **نموذج لغة كبيرة في وكيل ReACT**: أرغب في رؤية مواصفات معامل الأداة في المطالبات حتى أتمكن من توفير المعلمات الصحيحة
+
+## التصميم
+
+### الهندسة المعمارية عالية المستوى
+لتحقيق التوافق مع أنماط أدوات القالب، قم بتوسيع تكوين أداة MCP عن طريق:
+1. إضافة مصفوفة اختيارية "arguments" إلى تكوينات أدوات MCP
+2. تعديل `McpToolImpl` لقبول وإرجاع المعاملات المحددة
+3. تحديث تحميل تكوين الأداة للتعامل مع معاملات أدوات MCP
+4. التأكد من تضمين معلومات معامل أداة MCP في المطالبات
+
+### مخطط التكوين
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance", 
+  "description": "Get bank account balance",
+  "mcp-tool": "get_bank_balance",
+  "arguments": [
+    {
+      "name": "account_id",
+      "type": "string", 
+      "description": "Bank account identifier"
+    },
+    {
+      "name": "date",
+      "type": "string",
+      "description": "Date for balance query (optional, format: YYYY-MM-DD)"
+    }
+  ]
+}
+```
+
+### تدفق البيانات
+1. **تحميل التكوين**: يتم تحميل تكوين أداة MCP مع المعاملات بواسطة `on_tools_config()`
+2. **إنشاء الأداة**: يتم تحليل المعاملات وتمريرها إلى `McpToolImpl` من خلال المُنشئ
+3. **توليد المطالبة**: تتلقى LLMs معلومات المعاملات من الأداة، مما يسمح لها بإنشاء مطالبات مناسبة.
+4. **تنفيذ الأداة**: يتم تنفيذ أداة MCP باستخدام المعاملات التي تم تمريرها.
+
+### تأثير الأداء
+- **وقت تشغيل ضئيل**: يحدث تحليل المعاملات فقط أثناء تحميل التكوين، وليس لكل طلب
+- **حجم المطالبة**: قد تزيد المطالبات الخاصة بالوكيل قليلاً بسبب تضمين تفاصيل معامل أداة MCP.
+- **استخدام الذاكرة**: زيادة ضئيلة لتخزين مواصفات المعاملات في كائنات الأداة.
+
+## الوثائق
+
+### وثائق المستخدم
+- [ ] تحديث دليل تكوين أداة MCP مع أمثلة للمعاملات
+- [ ] إضافة مواصفات المعامل إلى نص مساعد أدوات سطر الأوامر
+- [ ] إنشاء أمثلة لأنماط معلمات أداة MCP الشائعة
+
+### وثائق المطور
+- [ ] تحديث وثائق فئة `McpToolImpl`
+- [ ] إضافة تعليقات توضيحية حول منطق تحليل المعاملات
+- [ ] توثيق تدفق المعامل في الهندسة المعمارية للنظام
+
+## الأسئلة المفتوحة
+1. **التحقق من صحة المعاملات**: هل يجب علينا التحقق من أنواع المعاملات/تنسيقاتها بالإضافة إلى التحقق الأساسي من الهيكل؟
+2. **اكتشاف ديناميكي**: هل نريد الاستعلام عن خوادم MCP عن مخططات أدوات بشكل تلقائي؟
+
+## البدائل التي تم النظر فيها
+1. **اكتشاف مخططات MCP الديناميكية**: الاستعلام عن خوادم MCP عن مخططات أدوات المعامل في وقت التشغيل - تم رفضها بسبب التعقيد ومخاوف الموثوقية
+2. **سجل المعاملات المنفصل**: تخزين معاملات أداة MCP في قسم تكوين منفصل - تم رفضه للحفاظ على التوافق مع نهج أدوات القالب
+3. **التحقق من نوع المعامل**: التحقق الكامل من مخطط JSON للمعاملات - تم تأجيله للحفاظ على البساطة في التنفيذ الأولي
+
+## المراجع
+- [المواصفات الخاصة ببروتوكول MCP](https://github.com/modelcontextprotocol/spec)
+- [تنفيذ أداة MCP](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
+- [تنفيذ أداة MCP الحالي](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
+
+## الملحق
+[أي معلومات إضافية، أو مخططات، أو أمثلة]

docs/tech-specs/mcp-tool-arguments.es.md

@@ -0,0 +1,160 @@
+# Especificación de Argumentos para la Herramienta MCP
+
+## Visión General
+**Nombre de la característica**: Soporte para Argumentos de la Herramienta MCP
+**Autor**: Asistente de Código Claude
+**Fecha**: 21/08/2025
+**Estado**: Finalizado
+
+### Resumen Ejecutivo
+
+Permitir que los agentes ReACT invoquen las herramientas MCP (Protocolo de Contexto del Modelo) con argumentos definidos correctamente, agregando soporte para la especificación de argumentos a las configuraciones de las herramientas MCP, de manera similar a como funcionan actualmente las herramientas de plantillas de prompts.
+
+### Declaración del Problema
+
+Actualmente, las herramientas MCP en el marco de agentes ReACT no pueden especificar sus argumentos esperados. El método `McpToolImpl.get_arguments()` devuelve una lista vacía, lo que obliga a los LLMs a adivinar la estructura de parámetros correcta basándose únicamente en los nombres y las descripciones de las herramientas. Esto conduce a:
+- Invocaciones de herramientas poco fiables debido a la adivinación de parámetros
+- Mala experiencia de usuario cuando las herramientas fallan debido a argumentos incorrectos
+- Falta de validación de parámetros de la herramienta antes de la ejecución
+- Falta de documentación de parámetros en los prompts del agente
+
+### Objetivos
+
+- [ ] Permitir que las configuraciones de las herramientas MCP especifiquen los argumentos esperados (nombre, tipo, descripción)
+- [ ] Actualizar el administrador de agentes para exponer los argumentos de las herramientas MCP a los LLMs a través de prompts
+- [ ] Mantener la compatibilidad hacia atrás con las configuraciones existentes de las herramientas MCP
+- [ ] Soporte para la validación de argumentos similar a las herramientas de plantillas de prompts
+
+### Objetivos No
+- Descubrimiento dinámico de argumentos de los servidores MCP (mejoras futuras)
+- Validación de tipos de argumentos más allá de la estructura básica
+- Esquemas de argumentos complejos (objetos anidados, arrays)
+
+## Antecedentes y Contexto
+
+### Estado Actual
+Las herramientas MCP se configuran en el sistema de agente ReACT con metadatos mínimos:
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance",
+  "description": "Obtener el saldo de la cuenta bancaria",
+  "mcp-tool": "get_bank_balance"
+}
+```
+
+El método `McpToolImpl.get_arguments()` devuelve `[]`, lo que significa que los LLMs no reciben ninguna guía de argumentos en sus prompts.
+
+### Limitaciones
+
+1. **Sin especificación de argumentos**: Las herramientas MCP no pueden definir parámetros esperados
+
+2. **Inferencia de parámetros por parte del LLM**: Los agentes deben deducir parámetros a partir de los nombres/descripciones de las herramientas
+
+3. **Falta de información en el prompt**: Los prompts de los agentes no muestran detalles de los argumentos para las herramientas MCP
+
+4. **Sin validación**: Los parámetros inválidos solo se detectan en el momento de la ejecución de la herramienta MCP
+
+### Componentes Relacionados
+- **trustgraph-flow/agent/react/service.py**: Carga de la configuración de las herramientas y creación del AgentManager
+- **trustgraph-flow/agent/react/tools.py**: Implementación de McpToolImpl
+- **trustgraph-flow/agent/react/agent_manager.py**: Generación de prompts con argumentos de las herramientas
+- **CLI tools**: Herramientas de línea de comandos para la gestión de herramientas MCP
+- **Workbench**: Interfaz de usuario externa para la configuración de las herramientas de los agentes
+
+## Requisitos
+
+### Requisitos Funcionales
+
+1. **Argumentos de la Configuración de la Herramienta MCP**: Las configuraciones de las herramientas MCP **DEBEN** soportar un array opcional de `arguments` con campos de nombre, tipo y descripción
+2. **Exposición de Argumentos**: El método `McpToolImpl.get_arguments()` **DEBE** devolver los argumentos configurados en lugar de una lista vacía
+3. **Integración en el Prompt**: Los prompts de los agentes **DEBEN** incluir detalles de los argumentos de las herramientas MCP cuando se especifican
+4. **Compatibilidad hacia atrás**: Las configuraciones existentes de las herramientas MCP sin argumentos **DEBEN** seguir funcionando
+5. **Soporte CLI**: Las herramientas CLI existentes (`tg-invoke-mcp-tool`) soportan argumentos (ya implementado)
+
+### Requisitos No Funcionales
+1. **Compatibilidad hacia atrás**: Sin cambios que rompan con las configuraciones existentes de las herramientas MCP
+2. **Rendimiento**: Sin impacto significativo en el rendimiento de la generación de prompts
+3. **Consistencia**: El manejo de argumentos **DEBE** seguir los patrones de las herramientas de plantillas de prompts
+
+### Historias de Usuario
+
+1. Como **desarrollador de agentes**, quiero especificar argumentos para las herramientas MCP en la configuración, para que los LLMs puedan invocar las herramientas con los parámetros correctos
+2. Como **usuario de Workbench**, quiero configurar argumentos para las herramientas MCP en la interfaz de usuario, para que los agentes usen las herramientas correctamente
+3. Como **LLM en un agente ReACT**, quiero ver las especificaciones de argumentos de las herramientas en los prompts, para poder proporcionar los parámetros correctos
+
+## Diseño
+
+### Arquitectura de Alto Nivel
+Extender la configuración de las herramientas MCP para que coincidan con el patrón de las plantillas de prompts, agregando:
+1. Un array opcional de `arguments` a las configuraciones de las herramientas MCP
+2. Modificar `McpToolImpl` para aceptar y devolver los argumentos configurados
+3. Actualizar la carga de la configuración de las herramientas para manejar los argumentos de las herramientas MCP
+4. Asegurar que los prompts de los agentes incluyan información sobre los argumentos de las herramientas MCP
+
+### Esquema de Configuración
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance", 
+  "description": "Obtener el saldo de la cuenta bancaria",
+  "mcp-tool": "get_bank_balance",
+  "arguments": [
+    {
+      "name": "account_id",
+      "type": "string", 
+      "description": "Identificador de la cuenta bancaria"
+    },
+    {
+      "name": "date",
+      "type": "string",
+      "description": "Fecha para la consulta de saldo (opcional, formato: YYYY-MM-DD)"
+    }
+  ]
+}
+```
+
+### Flujo de Datos
+1. **Carga de la configuración**: La configuración de la herramienta MCP con argumentos se carga por `on_tools_config()`
+2. **Creación de la herramienta**: Los argumentos se parsean y se pasan a `McpToolImpl` a través del constructor
+3. **Generación del prompt**: `agent_manager.py` llama a `tool.arguments` para incluirlos en los prompts de los LLMs
+4. **Invocación de la herramienta**: El LLM proporciona los parámetros, que se pasan sin cambios a las herramientas MCP
+
+## Consideraciones de Seguridad
+- **Sin nueva superficie de ataque**: Los argumentos se parsean a partir de las fuentes de configuración existentes sin nuevas entradas
+- **Validación de parámetros**: Los argumentos se pasan a las herramientas MCP sin cambios - la validación permanece a nivel de la herramienta MCP
+- **Integridad de la configuración**: Las especificaciones de argumentos son parte de la configuración de la herramienta - el mismo modelo de seguridad aplica
+
+## Impacto en el Rendimiento
+- **Sobrehead mínimo**: El análisis de argumentos ocurre solo durante la carga de la configuración, no por solicitud
+- **Aumento del tamaño del prompt**: Los prompts del agente incluirán detalles de los argumentos de las herramientas MCP, aumentando ligeramente el uso de tokens
+- **Uso de la memoria**: Aumento insignificante para almacenar las especificaciones de argumentos en los objetos de la herramienta
+
+## Documentación
+
+### Documentación del Usuario
+- [ ] Actualizar la guía de configuración de las herramientas MCP con ejemplos de argumentos
+- [ ] Agregar especificación de argumentos a la ayuda de la línea de comandos
+- [ ] Crear ejemplos de patrones comunes de argumentos de la herramienta MCP
+
+### Documentación del Desarrollador
+- [ ] Documentar la clase `McpToolImpl` con la lógica de análisis de argumentos
+- [ ] Agregar comentarios en el código para la lógica de análisis de argumentos
+- [ ] Documentar el flujo de argumentos en la arquitectura del sistema
+
+## Preguntas Abiertas
+1. **Validación de tipos**: ¿Deberíamos validar los tipos/formatos de los argumentos más allá de una verificación básica de estructura?
+2. **Descubrimiento dinámico**: ¿Una futura mejora para consultar automáticamente los esquemas de las herramientas MCP de los servidores?
+
+## Alternativas Consideradas
+1. **Descubrimiento dinámico de esquemas MCP**: Consultar los servidores MCP para obtener los esquemas de las herramientas a tiempo de ejecución - rechazado debido a preocupaciones de complejidad y fiabilidad
+2. **Registro de argumentos separado**: Almacenar los argumentos de las herramientas MCP en una sección de configuración separada - rechazado por mantener la consistencia con el enfoque de las plantillas de prompts
+3. **Validación de tipo**: Validación completa de esquema JSON para los argumentos - aplazado como una mejora futura para mantener la implementación inicial simple
+
+## Referencias
+- [Especificación del Protocolo MCP](https://github.com/modelcontextprotocol/spec)
+- [Implementación de las herramientas MCP](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
+- [Implementación actual de las herramientas MCP](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
+
+## Apéndice
+[Cualquier información, diagramas o ejemplos adicionales]

docs/tech-specs/mcp-tool-arguments.he.md

@@ -0,0 +1,118 @@
+# מפרט ארגומנטים של כלי MCP
+
+## סקירה כללית
+**שם פיצ'ר**: תמיכה בארגומנטים של כלי MCP
+**מחבר**: עוזר קוד של Claude
+**תאריך**: 2025-08-21
+**סטטוס**: סופי
+
+### סיכום מנהלים
+
+לאפשר למייצגי ReACT להפעיל כלי MCP (פרוטוקול הקשר של מודל) עם
+ארגומנטים מוגדרים כראוי, על ידי הוספת תמיכה במפרט ארגומנטים
+ליצור הגדרות כלי MCP, בדומה לאופן שבו כלי תבנית הנחייה
+פועלים כיום.
+
+### הצגת הבעיה
+
+כרגע, כלי MCP בתוך מסגרת ה-ReACT אינם יכולים לציין את
+הארגומנטים הצפויים שלהם. מתודת `McpToolImpl.get_arguments()`
+מחזירה רשימה ריקה, ולכן LLMs חייבים לנחש את המבנה של הפרמטרים
+רק על סמך שמות וכותרות כלים. זה גורם ל:
+- קריאות כלים לא אמינות עקב ניחוש פרמטרים
+- חוויית משתמש גרועה כאשר כלים נכשלים עקב ארגומנטים שגויים
+- אי אימות של פרמטרי כלים לפני ביצוע
+- אי עליית תיעוד פרמטרים בהנחיית הסוכן
+
+### מטרות
+
+- [ ] לאפשר להגדרות כלי MCP לציין ארגומנטים צפויים (שם, סוג, תיאור)
+- [ ] לעדכן את מנהל הסוכן כדי לחשוף ארגומנטי כלי MCP ל-LLMs באמצעות הנחיה
+- [ ] לשמור על תאימות לאחור להגדרות כלי MCP קיימות
+- [ ] לתמוך באימות ארגומנטים בדומה לכלי תבנית הנחיה
+
+### מטרות לא
+- גילוי דינמי של ארגומנטים מהשרתים של MCP (שיפור עתידי)
+- אימות סוגי ארגומנט מעבר למבנה בסיסי
+- סכימות ארגומנטים מורכבות (אובייקטים מקובצים, מערכים)
+
+## רקע והקשר
+
+### מצב נוכחי
+כלי MCP מוגדרים במערכת ה-ReACT עם מידע מינימלי:
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance",
+  "description": "Get bank account balance",
+  "mcp-tool": "get_bank_balance"
+}
+```
+
+המתודת `McpToolImpl.get_arguments()` מחזירה `[]`, ולכן LLMs לא מקבלים הדרכה לגבי ארגומנטים בהנחייתם.
+
+### מגבלות
+1. **אין מפרט ארגומנטים**: כלי MCP אינם יכולים להגדיר פרמטרים צפויים
+2. **ניחוש פרמטרים על ידי LLM**: הסוכן חייב להסיק פרמטרים משמות/תיאורים של כלים
+3. **מידע הנחיה חסר**: הנחיות הסוכן אינן מציגות פרטים לגבי ארגומנטים של כלי MCP
+4. **אין אימות**: פרמטרים לא חוקיים מתגלים רק בזמן ביצוע כלי MCP
+
+### רכיבים קשורים
+- **trustgraph-flow/agent/react/service.py**: טעינת הגדרות כלי וליצירת מנהל סוכן
+- **trustgraph-flow/agent/react/tools.py**: יישום של McpToolImpl
+- **trustgraph-flow/agent/react/agent_manager.py**: יצירת הנחיה עם ארגומנטי כלי
+- **trustgraph-cli**: כלים של שורת פקודה לניהול כלי MCP
+- **Workbench**: ממשק משתמש חיצוני להגדרת כלי סוכן
+
+## דרישות
+
+### דרישות פונקציונליות
+1. **הגדרות ארגומנטים של כלי MCP**: הגדרות כלי MCP חייבות לתמוך במערך אופציונלי של `arguments` עם שדות שם, סוג ותיאור
+2. **חשיפת ארגומנטים**: `McpToolImpl.get_arguments()` חייב להחזיר את הארגומנטים המוגדרים במקום רשימה ריקה
+3. **אינטגרציה עם הנחיה**: הנחיית הסוכן חייבת לכלול פרטים של ארגומנטי כלי MCP כאשר הם מוגדרים
+4. **תאימות לאחור**: הגדרות כלי MCP קיימות ללא ארגומנטים חייבות להמשיך לעבוד
+5. **תמיכה ב-CLI**: כלי ה-CLI הקיים `tg-invoke-mcp-tool` תומך בארגומנטים (כבר מיושם)
+
+### דרישות לא פונקציונליות
+1. **תאימות לאחור**: ללא שינויים שמשבשים בהגדרות כלי MCP קיימות
+2. **ביצועים**: ללא השפעה משמעותית על יצירת הנחיות סוכן
+3. **עקביות**: טיפול בארגומנטים חייב להתאים לתבניות של כלי תבנית הנחיה
+
+### סיפורי משתמש
+1. כ**מפתח סוכן**, אני רוצה לציין ארגומנטים של כלי MCP בהגדרות, כך ש-LLMs יוכלו להפעיל כלים עם פרמטרים נכונים
+2. כ**משתמש ב-Workbench**, אני רוצה להגדיר ארגומנטים של כלי MCP בממשק ה-UI, כך שהסוכן ישתמש בכלים כראוי
+3. כ**LLM בסוכן ReACT**, אני רוצה לראות את המפרט של ארגומנטי כלי בהנחיות, כך שאוכל לספק פרמטרים נכונים
+
+## עיצוב
+
+### ארכיטקטורה ברמה גבוהה
+להרחיב את הגדרת כלי MCP כך שתתאים לתבנית כלי תבנית הנחיה על ידי:
+1. הוספת מערך אופציונלי של `arguments` להגדרות כלי MCP
+2. שינוי המחלקה `McpToolImpl` כדי לקבל את הארגומנטים
+3. לשמור על התאמה לאחור להגדרות כלי MCP קיימות
+
+### דוגמה
+```python
+class McpToolImpl:
+    def get_arguments(self):
+        # ... קוד לקבלת ארגומנטים ...
+        return arguments
+```
+
+## שאלות פתוחות
+1. **אימות ארגומנטים**: האם אמור להיות אימות סוגים/פורמטים של ארגומנט מעבר לבדיקות מבני בסיסיות?
+2. **גילוי דינמי**: האם עדיף לשאול את שרתי ה-MCP עבור סכימות כלי באופן אוטומטי?
+3. **מבנה ארגומנטים**: האם הארגומנטים צריכים להיות בפורמט מובנה (לדוגמה, JSON)?
+
+## אפשרויות שנשקלו
+1. **גילוי דינמי של סכימת MCP**: לשאול את שרתי ה-MCP עבור סכימות של כלי בזמן ריצה - נדחה עקב מורכבות וחששות לגבי אמינות
+2. **רשום ארגומנטים נפרד**: לאחסן את ארגומנטי הכלי בפרטי הגדרה נפרדים - נדחה עקב עקביות עם הגישה של תבנית הנחיה
+3. **אימות סוג**: אימות JSON מלא של ארגומנטים - מוחזר כשיפור עתידי כדי לשמור על היישום הראשוני פשוט
+
+## מקורות
+- [מפרט פרוטוקול MCP](https://github.com/modelcontextprotocol/spec)
+- [יישום כלי תבנית הנחיה](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
+- [יישום כלי MCP נוכחי](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
+
+## נספחים
+[כל מידע, דיאגרמות או דוגמאות נוספות]

docs/tech-specs/mcp-tool-arguments.ru.md

@@ -0,0 +1,120 @@
+# Спецификация аргументов для инструмента MCP
+
+## Обзор
+**Имя функции**: Поддержка аргументов для инструмента MCP
+**Автор**: Claude Code Assistant
+**Дата**: 21.08.2025
+**Статус**: Завершено
+
+### Краткое описание
+
+Позволить агентам ReACT использовать инструменты MCP (Протокол контекста модели) с правильно определенными аргументами, добавив поддержку спецификации аргументов в конфигурацию инструмента MCP, аналогично тому, как работают инструменты с шаблонами запросов.
+
+### Проблема
+
+В настоящее время инструменты MCP в фреймворке агента ReACT не могут указывать ожидаемые аргументы. Метод `McpToolImpl.get_arguments()` возвращает пустой список, заставляя LLM угадывать правильную структуру параметров, основываясь только на именах и описаниях инструментов. Это приводит к:
+- Ненадежным вызовам инструментов из-за угадывания параметров
+- Плохой пользовательской опыту, когда инструменты не работают из-за неправильных аргументов
+- Отсутствию проверки параметров инструментов перед выполнением
+- Отсутствия документации параметров в запросах агента
+
+### Цели
+
+- [ ] Разрешить конфигурации инструментов MCP указывать ожидаемые аргументы (имя, тип, описание)
+- [ ] Обновить менеджер агентов, чтобы он предоставлял аргументы инструментов MCP LLM через запросы
+- [ ] Сохранить обратную совместимость с существующими конфигурациями инструментов MCP
+- [ ] Поддерживать проверку аргументов, аналогичную инструментам с шаблонами запросов
+
+### Нецелевые области
+- Динамическое обнаружение аргументов от серверов MCP (будущее улучшение)
+- Проверка типов аргументов за пределами базовой структуры
+- Сложные схемы аргументов (вложенные объекты, массивы)
+
+## Предыстория и контекст
+
+### Текущее состояние
+Инструменты MCP настраиваются в системе агента ReACT с минимальными метаданными:
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance",
+  "description": "Получить баланс банковского счета",
+  "mcp-tool": "get_bank_balance"
+}
+```
+Метод `McpToolImpl.get_arguments()` возвращает `[]`, поэтому LLM не получают никаких указаний по аргументам в своих запросах.
+
+### Ограничения
+
+1. **Отсутствие спецификации аргументов**: Инструменты MCP не могут определять ожидаемые параметры
+2. **Угадывание параметров LLM**: Агенты должны выводить параметры из имен/описаний инструментов
+3. **Отсутствие информации в запросах**: Запросы агента не содержат деталей аргументов для инструментов MCP
+4. **Отсутствие проверки**: Неправильные параметры обнаруживаются только во время выполнения инструмента MCP
+
+### Связанные компоненты
+- **trustgraph-flow/agent/react/service.py**: Загрузка конфигурации инструментов и создание AgentManager
+- **trustgraph-flow/agent/react/tools.py**: Реализация McpToolImpl
+- **trustgraph-flow/agent/react/agent_manager.py**: Генерация запросов с аргументами инструментов
+- **tg-invoke-mcp-tool**: Клиентские инструменты для управления инструментами MCP
+- **Workbench**: Внешний UI для конфигурации инструментов агента
+
+## Требования
+
+### Функциональные требования
+
+1. **Конфигурация аргументов для инструмента MCP**: Конфигурации инструментов MCP ДОЛЖНЫ поддерживать необязательный массив `arguments` с полями `name`, `type` и `description`
+2. **Предоставление аргументов**: `McpToolImpl.get_arguments()` ДОЛЖЕН возвращать сконфигурированные аргументы, а не пустой список
+3. **Интеграция с запросами**: Запросы агента ДОЛЖНЫ содержать детали аргументов инструментов MCP, когда аргументы указаны
+4. **Обратная совместимость**: Существующие конфигурации инструментов MCP без аргументов ДОЛЖНЫ продолжать работать
+5. **Поддержка CLI**: Существующие CLI инструменты tg-invoke-mcp-tool поддерживают аргументы (уже реализовано)
+
+### Нефункциональные требования
+1. **Обратная совместимость**: Без каких-либо изменений для существующих конфигураций инструментов MCP
+2. **Производительность**: Отсутствие существенного влияния на генерацию запросов агента
+3. **Согласованность**: Обработка аргументов ДОЛЖНА соответствовать шаблонам инструментов с шаблонами запросов
+
+### Истории пользователей
+
+1. Как **разработчик агента**, я хочу указывать аргументы инструментов MCP в конфигурации, чтобы LLM могли вызывать инструменты с правильными параметрами
+2. Как **пользователь Workbench**, я хочу настраивать аргументы инструментов MCP в UI, чтобы агенты использовали инструменты правильно
+3. Как **LLM в ReACT агенте**, я хочу видеть спецификации аргументов инструментов в запросах, чтобы я мог предоставлять правильные параметры
+
+## Проектирование
+
+### Высокоуровневая архитектура
+Расширить конфигурацию инструмента MCP, чтобы соответствовать шаблону инструмента с шаблоном запросов, путем:
+1. Добавления необязательного массива `arguments` в конфигурацию инструментов MCP
+2. Модификации `McpToolImpl` для приема и возврата сконфигурированных аргументов
+3. Обновления загрузки конфигурации инструментов для обработки аргументов инструментов MCP
+4. Обеспечения включения информации об аргументах инструментов MCP в запросы агента
+
+### Схема конфигурации
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance", 
+  "description": "Get bank account balance",
+  "mcp-tool": "get_bank_balance",
+  "arguments": [
+    {
+      "name": "account_id",
+      "type": "string", 
+      "description": "Bank account identifier"
+    },
+    {
+      "name": "date",
+      "type": "string",
+      "description": "Date for balance query (optional, format: YYYY-MM-DD)"
+    }
+  ]
+}
+```
+
+### Поток данных
+1. **Загрузка конфигурации**: Конфигурация инструмента MCP с аргументами загружается с помощью `on_tools_config()`
+2. **Создание инструмента**: Аргументы парсятся и передаются в `McpToolImpl` через конструктор
+3. **Генерация запросов**: `agent_manager.py` вызывает `tool.arguments` для включения в LLM запросы
+4. **Вызов инструмента**: LLM предоставляет параметры, которые передаются инструменту MCP без изменений
+
+### Изменения API
+Нет изменений API - это чисто внутренняя конфигурация и обработка аргументов

docs/tech-specs/mcp-tool-arguments.zh-cn.md

@@ -0,0 +1,195 @@
+# MCP 工具参数规范
+
+## 概述
+**功能名称**: MCP 工具参数支持
+**作者**: Claude 代码助手
+**日期**: 2025-08-21
+**状态**: 最终
+
+### 摘要
+
+启用 ReACT 代理调用带有正确定义的参数的 MCP (模型上下文协议) 工具，通过在 MCP 工具配置中添加参数规范支持，类似于当前提示模板工具的工作方式。
+
+### 问题陈述
+
+目前，ReACT 代理框架中的 MCP 工具无法指定其预期的参数。`McpToolImpl.get_arguments()` 方法返回一个空列表，迫使 LLM 仅根据工具名称和描述来猜测正确的参数结构。这会导致：
+- 由于参数猜测导致的不可靠工具调用
+- 当工具因错误的参数而失败时，用户体验不佳
+- 在执行之前无法验证工具参数
+- 代理提示中缺少参数文档
+
+### 目标
+
+- [ ] 允许 MCP 工具配置指定预期的参数（名称、类型、描述）
+- [ ] 更新代理管理器，通过提示向 LLM 暴露 MCP 工具参数
+- [ ] 保持与现有 MCP 工具配置的向后兼容性
+- [ ] 支持与提示模板工具类似的参数验证
+
+### 不属于目标
+- 从 MCP 服务器动态发现参数（未来增强功能）
+- 参数类型验证，超出基本结构
+- 复杂的参数模式（嵌套对象、数组）
+
+## 背景和上下文
+
+### 现状
+MCP 工具在 ReACT 代理系统中配置为具有最小的元数据：
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance",
+  "description": "获取银行账户余额",
+  "mcp-tool": "get_bank_balance"
+}
+```
+
+`McpToolImpl.get_arguments()` 方法返回 `[]`，因此 LLM 在提示中不会收到任何参数指导。
+
+### 局限性
+
+1. **缺少参数指定**: MCP 工具无法定义预期的参数
+2. **LLM 参数猜测**: 代理必须根据工具名称/描述推断参数
+3. **提示信息缺失**: 代理提示中不包含 MCP 工具的参数详情
+4. **无验证**: 无效参数仅在 MCP 工具执行时捕获
+
+### 相关组件
+- **trustgraph-flow/agent/react/service.py**: 工具配置加载和 AgentManager 创建
+- **trustgraph-flow/agent/react/tools.py**: McpToolImpl 实现
+- **trustgraph-flow/agent/react/agent_manager.py**: 使用工具参数生成提示
+- **tg-invoke-mcp-tool**: 用于 MCP 工具管理的 CLI 工具
+- **Workbench**: 代理工具配置的外部 UI
+
+## 要求
+
+### 功能要求
+
+1. **MCP 工具配置参数**: MCP 工具配置 **必须** 支持一个可选的 `arguments` 数组，包含名称、类型和描述字段
+2. **参数暴露**: `McpToolImpl.get_arguments()` **必须** 返回配置的参数，而不是空列表
+3. **提示集成**: 代理提示 **必须** 在指定有参数时，包含 MCP 工具参数详情
+4. **向后兼容性**: 没有参数的现有 MCP 工具配置 **必须** 保持正常工作
+5. **CLI 支持**: 现有的 `tg-invoke-mcp-tool` CLI 支持参数（已实现）
+
+### 非功能要求
+1. **向后兼容性**: 现有 MCP 工具配置零中断
+2. **性能**: 代理提示生成没有显著性能影响
+3. **一致性**: 参数处理 **必须** 与提示模板工具模式匹配
+
+### 用户故事
+
+1. 作为 **代理开发者**，我希望在配置中指定 MCP 工具参数，以便 LLM 可以使用正确的参数调用工具
+2. 作为 **Workbench 用户**，我希望在 UI 中配置 MCP 工具参数，以便代理正确使用工具
+3. 作为 **ReACT 代理中的 LLM**，我希望在提示中看到工具参数规范，以便我可以提供正确的参数
+
+## 设计
+
+### 高级架构
+通过以下方式，扩展 MCP 工具配置以匹配提示模板模式：
+1. 在 MCP 工具配置中添加可选的 `arguments` 数组，包含名称、类型和描述字段
+2. 修改 `McpToolImpl` 以接受和返回配置的参数
+3. 修改工具配置加载以处理 MCP 工具参数
+4. 确保代理提示包含 MCP 工具参数信息
+
+### 配置方案
+```json
+{
+  "type": "mcp-tool",
+  "name": "get_bank_balance", 
+  "description": "获取银行账户余额",
+  "mcp-tool": "get_bank_balance",
+  "arguments": [
+    {
+      "name": "account_id",
+      "type": "string", 
+      "description": "银行账户标识符"
+    },
+    {
+      "name": "date",
+      "type": "string",
+      "description": "查询余额的日期（可选，格式：YYYY-MM-DD）"
+    }
+  ]
+}
+```
+
+### 数据流程
+1. **配置加载**: 使用参数的 MCP 工具配置通过 `on_tools_config()` 加载
+2. **工具创建**: 参数解析并传递给 `McpToolImpl` 通过构造函数
+3. **提示生成**: `agent_manager.py` 调用 `tool.arguments` 以包含在 LLM 提示中
+4. **工具调用**: LLM 提供参数，这些参数传递给 MCP 服务不变
+
+### API 更改
+- 无外部 API 更改 - 这是一个纯粹的内部配置和参数处理
+
+### 组件详情
+
+#### 组件 1: service.py (工具配置加载)
+- **目的**: 解析 MCP 工具配置并创建工具实例
+- **更改要求**:  解析 MCP 工具配置中的参数（类似于提示工具）
+- **新功能**: 从 MCP 工具配置中提取 `arguments` 数组，并创建 `Argument` 对象
+
+#### 组件 2: tools.py (McpToolImpl)
+- **目的**: MCP 工具实现包装器
+- **更改要求**: 接受构造函数中的参数并从 `get_arguments()` 中返回
+- **新功能**: 存储并公开配置的参数，而不是返回空列表
+
+#### 组件 3: Workbench (外部仓库)
+- **目的**: 代理工具配置的 UI
+- **更改要求**: 为 MCP 工具添加参数规范 UI
+- **新功能**: 允许用户添加/编辑/删除 MCP 工具的参数
+
+#### 组件 4: CLI 工具
+- **目的**: 命令列工具管理
+- **更改要求**: 支持在工具创建/更新命令中指定参数
+- **新功能**: 在工具配置命令中接受 `arguments` 参数
+
+## 实施计划
+
+### 阶段 1: 核心代理框架更改
+- [ ] 更新 `McpToolImpl` 构造函数以接受 `arguments` 参数
+- [ ] 修改 `McpToolImpl.get_arguments()` 以返回存储的参数，而不是空列表
+- [ ] 修改 `service.py` 中的 MCP 工具配置解析以处理参数
+- [ ] 添加 MCP 工具参数的测试
+- [ ] 更新 McpToolImpl 类文档
+- [ ] 添加参数解析逻辑的注释
+- [ ] 更新系统架构中的参数流程文档
+
+### 阶段 4: 生产部署
+- 核心更改具有向后兼容性 - 无需回滚，因为功能正常
+- 如果出现问题，请通过回滚 MCP 工具配置加载逻辑来禁用参数解析
+- Workbench 和 CLI 更改是独立的，可以单独回滚
+
+## 安全注意事项
+- **没有新的攻击面**: 参数是从现有配置源解析的，没有新的输入
+- **参数验证**: 参数传递给 MCP 工具不变 - 验证在 MCP 工具级别
+- **配置完整性**: 参数规范是工具配置的一部分 - 相同的安全模型适用
+
+## 性能影响
+- **极小的开销**: 参数解析仅在配置加载期间发生，而不是请求时
+- **提示大小增加**: 代理提示将包含 MCP 工具参数详情，稍微增加令牌使用量
+- **内存使用**: 存储参数规范在对象中的增加，可以忽略不计
+
+## 文档
+
+### 用户文档
+- [ ] 更新 MCP 工具配置指南，提供参数示例
+- [ ] 在 CLI 工具的帮助文本中添加参数规范
+- [ ] 创建常见 MCP 工具参数模式的示例
+
+### 开发者文档
+- [ ] 更新 `McpToolImpl` 类文档
+- [ ] 添加参数解析逻辑的注释
+- [ ] 文档系统架构中的参数流程
+
+## 未解决的问题
+1. **参数验证**: 是否应该在基本结构检查之外验证参数类型/格式？
+2. **动态发现**: 将来增强功能，以在运行时自动从 MCP 服务器查询工具模式？
+
+## 考虑的替代方案
+1. **动态的 MCP 模式发现**: 在运行时查询 MCP 服务器以获取工具参数模式 - 已拒绝，因为它复杂且不可靠
+2. **单独的参数注册表**: 将 MCP 工具参数存储在单独的配置部分中 - 已拒绝，因为与提示模板方法保持一致
+3. **类型验证**: JSON 模式验证参数 - 延迟，以便在初始实现中保持简单
+
+## 引用
+- [MCP 协议规范](https://github.com/modelcontextprotocol/spec)
+- [提示模板工具实现](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
+- [当前的 MCP 工具实现](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)

docs/tech-specs/more-config-cli.ar.md

@@ -0,0 +1,151 @@
+# مواصفات فنية لسطر الأوامر لتكوين
+
+## نظرة عامة
+
+تصف هذه المواصفات قدرات التكوين المتقدمة لسطر الأوامر لـ TrustGraph، مما يمكّن المستخدمين من إدارة عناصر التكوين الفردية من خلال أوامر سطر الأوامر التفصيلية. يدعم التكامل أربعة حالات استخدام رئيسية:
+
+1.  **قائمة عناصر التكوين**: عرض مفاتيح التكوين لنوع معين
+2.  **الحصول على عنصر التكوين**: استرداد قيم التكوين المحددة
+3.  **تطبيق عنصر التكوين**: تعيين أو تحديث عناصر التكوين الفردية
+4.  **حذف عنصر التكوين**: إزالة عناصر التكوين المحددة
+
+## الأهداف
+
+*   **التحكم التفصيلي**: تمكين إدارة عناصر التكوين الفردية بدلاً من العمليات المجمعة
+*   **قائمة بناءً على النوع**: السماح للمستخدمين باستكشاف عناصر التكوين حسب النوع
+*   **عمليات عنصر واحد**: توفير أوامر للحصول على/تطبيق/حذف عناصر التكوين الفردية
+*   **تكامل API**: الاستفادة من واجهة API الحالية للتكوين لجميع العمليات
+*   **نمط سطر أوامر متسق**: اتباع قواعد TrustGraph CLI الراسخة وأنماطها
+*   **معالجة الأخطاء**: توفير رسائل خطأ واضحة لعمليات غير صالحة
+*   **إخراج JSON**: دعم الإخراج المنظم للاستخدام البرمجي
+*   **التوثيق**: تضمين مساعدة شاملة وأمثلة للاستخدام
+
+## الخلفية
+
+يوفر TrustGraph حاليًا إدارة التكوين من خلال واجهة API للتكوين وأمر سطر أوامر واحد `tg-show-config` الذي يعرض التكوين بأكمله. على الرغم من أن هذا يعمل في عرض التكوين، إلا أنه يفتقر إلى قدرات الإدارة التفصيلية.
+
+تشمل القيود الحالية ما يلي:
+*   لا توجد طريقة لقائمة عناصر التكوين حسب النوع من سطر الأوامر
+*   لا يوجد أمر سطر أوامر لاسترداد قيم التكوين المحددة
+*   لا يوجد أمر سطر أوامر لتعيين عناصر التكوين الفردية
+*   لا يوجد أمر سطر أوامر لحذف عناصر التكوين المحددة
+
+تتعالج هذه المواصفات هذه الثغرات من خلال إضافة أربعة أوامر سطر أوامر جديدة التي توفر إدارة التكوين التفصيلية. من خلال الكشف عن عمليات واجهة API للتكوين الفردية من خلال أوامر سطر الأوامر، يمكن لـ TrustGraph:
+*   تمكين إدارة التكوين المبرمجة
+*   السماح باستكشاف هيكل التكوين حسب النوع
+*   دعم تحديثات التكوين المستهدفة
+*   توفير تحكم دقيق في التكوين
+
+## التصميم الفني
+
+### الهندسة المعمارية
+
+يتطلب التكوين المتقدم لسطر الأوامر المكونات الفنية التالية:
+
+1.  **tg-list-config-items**
+    *   قائمة مفاتيح التكوين لنوع معين
+    *   استدعاء طريقة واجهة API `Config.list(type)`
+    *   إخراج قائمة بمفاتيح التكوين
+    
+    وحدة: `trustgraph.cli.list_config_items`
+
+2.  **tg-get-config-item**
+    *   استرداد عنصر تكوين معين(أو أكثر)
+    *   استدعاء طريقة واجهة API `Config.get([ConfigKey(type, key)])`
+    *   إخراج قيم التكوين بتنسيق JSON
+
+    وحدة: `trustgraph.cli.get_config_item`
+
+3.  **tg-put-config-item**
+    *   تعيين أو تحديث عنصر تكوين
+    *   استدعاء طريقة واجهة API `Config.put([ConfigValue(type, key, value)])`
+    *   قبول معلمات النوع والمفتاح والقيمة
+
+    وحدة: `trustgraph.cli.put_config_item`
+
+4.  **tg-delete-config-item**
+    *   إزالة عنصر تكوين
+    *   استدعاء طريقة واجهة API `Config.delete([ConfigKey(type, key)])`
+    *   قبول معلمات النوع والمفتاح
+
+    وحدة: `trustgraph.cli.delete_config_item`
+
+### نماذج البيانات
+
+#### ConfigKey و ConfigValue
+
+تستخدم الأوامر هياكل البيانات الموجودة من `trustgraph.api.types`:
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+يسمح هذا النهج بما يلي:
+*   معالجة متسقة للبيانات عبر سطر الأوامر وواجهة API
+*   عمليات تكوين آمنة من النوع
+*   تنسيقات إدخال/إخراج منظمة
+*   التكامل مع واجهة API للتكوين الحالية
+
+### مواصفات سطر الأوامر
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
+```
+*   **الغرض**: قائمة بمفاتيح التكوين لنمط معين
+*   **استدعاء واجهة API**: `Config.list(type)`
+*   **الإخراج**:
+    *   `text` (افتراضي): مفاتيح التكوين مفصولة بأسطر جديدة
+    *   `json`: مصفوفة JSON من مفاتيح التكوين
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
+```
+*   **الغرض**: استرداد عنصر التكوين المحدد
+*   **استدعاء واجهة API**: `Config.get([ConfigKey(type, key)])`
+*   **الإخراج**:
+    *   `text` (افتراضي): سلسلة خام
+    *   `json`: سلسلة JSON منقذة
+    
+#### tg-put-config-item
+```bash
+tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
+tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
+```
+*   **الغرض**: تعيين أو تحديث عنصر التكوين
+*   **استدعاء واجهة API**: `Config.put([ConfigValue(type, key, value)])`
+*   **خيارات الإدخال**:
+    *   `--value <value>`: قيمة
+    *   `--stdin`: إدخال من stdin
+*   `--key <key>`: المفتاح
+*   `--type <type>`: النوع
+
+#### tg-delete-config-item
+```bash
+tg-delete-config-item --type <type> --key <key>
+```
+*   **الغرض**: حذف عنصر التكوين
+*   `--key <key>`: المفتاح
+*   `--type <type>`: النوع
+
+## أسئلة مفتوحة
+
+*   هل يجب أن تدعم الأوامر عمليات دفعة (مفاتيح متعددة) بالإضافة إلى العناصر الفردية؟
+*   ما هو تنسيق الإخراج الذي يجب استخدامه لإعادة التأكيد على النجاح؟
+*   كيف يجب توثيق/اكتشاف أنواع التكوين للمستخدمين؟
+
+## المراجع
+
+*   واجهة API للتكوين: `trustgraph/api/config.py`
+*   أنماط سطر الأوامر: `trustgraph-cli/trustgraph/cli/show_config.py`
+*   أنواع البيانات: `trustgraph/api/types.py`

docs/tech-specs/more-config-cli.es.md

@@ -0,0 +1,157 @@
+# Especificación Técnica de la CLI para Configuración
+
+## Descripción general
+
+Esta especificación describe las capacidades mejoradas de configuración a través de la línea de comandos para TrustGraph, lo que permite a los usuarios gestionar elementos de configuración individuales utilizando comandos CLI granulares. La integración soporta cuatro casos de uso principales:
+
+1. **Listar Elementos de Configuración**: Mostrar las claves de configuración de un tipo específico.
+2. **Obtener Elemento de Configuración**: Recuperar los valores de configuración específicos.
+3. **Establecer Elemento de Configuración**: Establecer o actualizar elementos de configuración individuales.
+4. **Eliminar Elemento de Configuración**: Eliminar elementos de configuración específicos.
+
+## Objetivos
+
+- **Control Granular**: Permitir la gestión de elementos de configuración individuales en lugar de operaciones masivas.
+- **Listado Basado en Tipo**: Permitir a los usuarios explorar los elementos de configuración por tipo.
+- **Operaciones en Elemento Individual**: Proporcionar comandos para obtener/establecer/eliminar elementos de configuración individuales.
+- **Integración con API**: Aprovechar la API de Config existente para todas las operaciones.
+- **Patrón CLI Consistente**: Seguir las convenciones y patrones CLI establecidos de TrustGraph.
+- **Manejo de Errores**: Proporcionar mensajes de error claros para operaciones inválidas.
+- **Salida JSON**: Soporte para salida estructurada para uso programático.
+- **Documentación**: Incluir ayuda y ejemplos de uso completos.
+
+## Antecedentes
+
+Actualmente, TrustGraph proporciona la gestión de la configuración a través de la API de Config y un único comando de línea de comandos `tg-show-config` que muestra toda la configuración. Si bien esto funciona para la visualización de la configuración, carece de capacidades de gestión granular.
+
+Las limitaciones actuales incluyen:
+- No hay forma de listar los elementos de configuración por tipo desde la línea de comandos.
+- No hay ningún comando de línea de comandos para recuperar valores de configuración específicos.
+- No hay ningún comando de línea de comandos para establecer elementos de configuración individuales.
+- No hay ningún comando de línea de comandos para eliminar elementos de configuración específicos.
+
+Esta especificación aborda estas lagunas agregando cuatro nuevos comandos de línea de comandos que proporcionan la gestión de configuración granular. Al exponer las operaciones de la API de Config individual a través de comandos CLI, TrustGraph puede:
+- Permitir la gestión de la configuración a través de scripts.
+- Permitir la exploración de la estructura de la configuración por tipo.
+- Soporte para actualizaciones de configuración dirigidas.
+- Proporcionar un control granular de la configuración.
+
+## Diseño Técnico
+
+### Arquitectura
+
+La configuración CLI mejorada requiere los siguientes componentes técnicos:
+
+1. **tg-list-config-items**
+   - Lista las claves de configuración para un tipo específico.
+   - Llama al método de API `Config.list(type)`.
+   - Salida la lista de claves de configuración.
+
+   Módulo: `trustgraph.cli.list_config_items`
+
+2. **tg-get-config-item**
+   - Recupera el(los) elemento(s) de configuración específico(s).
+   - Llama al método de API `Config.get([ConfigKey(type, key)])`.
+   - Salida los valores de configuración en formato JSON.
+
+   Módulo: `trustgraph.cli.get_config_item`
+
+3. **tg-put-config-item**
+   - Establece o actualiza un elemento de configuración.
+   - Llama al método de API `Config.put([ConfigValue(type, key, value)])`.
+   - Acepta los parámetros de tipo, clave y valor.
+
+   Módulo: `trustgraph.cli.put_config_item`
+
+4. **tg-delete-config-item**
+   - Elimina un elemento de configuración.
+   - Llama al método de API `Config.delete([ConfigKey(type, key)])`.
+   - Acepta los parámetros de tipo y clave.
+
+   Módulo: `trustgraph.cli.delete_config_item`
+
+### Modelos de Datos
+
+#### ConfigKey y ConfigValue
+
+Los comandos utilizan las estructuras de datos existentes de `trustgraph.api.types`:
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+Esto permite:
+- Manejo de datos consistente entre la CLI y la API.
+- Operaciones de configuración seguras por tipo.
+- Formatos de entrada/salida estructurados.
+- Integración con la API de Config existente.
+
+### Especificaciones de la CLI
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <tipo-de-configuración> [--formato texto|json] [--url-api <url>]
+```
+- **Propósito**: Listar todas las claves de configuración para un tipo dado.
+- **Llamada a la API**: `Config.list(type)`
+- **Salida**:
+  - `texto` (predeterminado): Claves de configuración separadas por nuevas líneas.
+  - `json`: Array JSON de claves de configuración.
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <tipo-de-configuración> --clave <clave> [--formato texto|json] [--url-api <url>]
+```
+- **Propósito**: Recuperar el elemento de configuración específico.
+- **Llamada a la API**: `Config.get([ConfigKey(type, key)])`
+- **Salida**:
+  - `texto` (predeterminado): Cadena de texto sin comillas ni codificación.
+  - `json`: Cadena de texto codificada en JSON.
+
+#### tg-put-config-item
+```bash
+tg-put-config-item --type <tipo-de-configuración> --clave <clave> --valor <valor> [--url-api <url>]
+tg-put-config-item --type <tipo-de-configuración> --clave <clave> --stdin [--url-api <url>]
+```
+- **Propósito**: Establecer o actualizar el elemento de configuración.
+- **Llamada a la API**: `Config.put([ConfigValue(type, key, value)])`
+- **Opciones de entrada**:
+  - `--valor`: Valor de cadena proporcionado directamente en la línea de comandos.
+  - `--stdin`: Leer todo el valor de entrada desde la entrada estándar como el valor del elemento de configuración.
+- **Salida**: Confirmación de éxito
+
+#### tg-delete-config-item
+```bash
+tg-delete-config-item --type <tipo-de-configuración> --clave <clave> [--url-api <url>]
+```
+- **Propósito**: Eliminar el elemento de configuración.
+- **Llamada a la API**: `Config.delete([ConfigKey(type, key)])`
+- **Salida**: Confirmación de éxito
+
+### Detalles de Implementación
+
+- Se debe usar un formato JSON para la salida de la API.
+- Se debe usar un formato de texto sin comillas para la salida de la API.
+- Se deben usar los parámetros de línea de comandos para especificar el tipo, la clave y el valor.
+- Se debe proporcionar una confirmación de éxito para las operaciones de la línea de comandos.
+
+## Preguntas Abiertas
+
+- ¿Deberían los comandos admitir operaciones en lote (múltiples claves) además de elementos individuales?
+- ¿Cuál debe ser el formato de salida para las confirmaciones de éxito?
+- ¿Cómo deberían descubrir los usuarios los tipos de configuración?
+
+## Referencias
+
+- API de Config existente: `trustgraph/api/config.py`
+- Patrones de CLI: `trustgraph-cli/trustgraph/cli/show_config.py`
+- Tipos de datos: `trustgraph/api/types.py`

docs/tech-specs/more-config-cli.he.md

@@ -0,0 +1,143 @@
+# מפרט טכני של שורת הפקודה עבור תצורות
+
+## סקירה כללית
+
+מסמך זה מתאר יכולות תצורה משופרות של שורת הפקודה עבור TrustGraph, ומאפשר למשתמשים לנהל פריטי תצורה בודדים באמצעות פקודות שורת פקודה מפורטות. האינטגרציה תומכת ברשיות שימושיות עיקריות:
+
+1. **רשימת פריטי תצורה**: הצגת מפתחות התצורה של סוג מסוים
+2. **קבלת פריט תצורה**: שליפת ערכי התצורה הספציפיים
+3. **הגדרת פריט תצורה**: הגדרת או עדכון פריטי תצורה בודדים
+4. **מחיקת פריט תצורה**: הסרת פריטי תצורה ספציפיים
+
+## יעדים
+
+- **שליטה מפורטת**: אפשר ניהול של פריטי תצורה בודדים ולא פעולות מקובצות
+- **רשימה לפי סוג**: לאפשר למשתמשים לחקור פריטי תצורה לפי סוג
+- **פעולות על פריט בודד**: לספק פקודות לקבלת/הגדרה/מחיקה של פריטי תצורה בודדים
+- **אינטגרציה של API**: לנצל את ה-API הקיים של התצורה עבור כל הפעולות
+- **תבנית שורת פקודה עקבית**: לעקוב אחר התקנות והתבניות הסטנדרטיות של TrustGraph
+- **טיפול בשגיאות**: לספק הודעות שגיאה ברורות עבור פעולות לא חוקיות
+- **פלט JSON**: תמיכה בפלט מובנה לשימוש תכנותי
+- **תיעוד**: לכלול עזרה מקיפה ודוגמאות שימוש
+
+## רקע
+
+TrustGraph מספקת כיום ניהול תצורה באמצעות ה-API של התצורה ופקודה בודדת בשם `tg-show-config` המציגה את כל התצורה. אמנם זה עובד לצורך הצגת התצורה, אך הוא חסר יכולות ניהול מפורטות.
+
+הגבלות נוכחיות כוללות:
+- אין דרך לרשום פריטי תצורה לפי סוג מתוך שורת הפקודה
+- אין פקודה בשורת הפקודה לקבלת ערכי תצורה ספציפיים
+- אין פקודה בשורת הפקודה להגדרת פריטי תצורה בודדים
+- אין פקודה בשורת הפקודה למחיקת פריטי תצורה ספציפיים
+
+מסמך זה מטפל בחוסרים אלה על ידי הוספת ארבע פקודות שורת פקודה חדשות המספקות ניהול תצורה מפורט. על ידי חשיפת פעולות API של התצורה הבודדות דרך פקודות שורת פקודה, TrustGraph יכול:
+- לאפשר ניהול תצורה מבוסס תסריט
+- לאפשר חקירה של מבנה התצורה לפי סוג
+- לתמוך בעדכונים ממוקדי תצורה
+- לספק שליטה מפורטת על התצורה
+
+## עיצוב טכני
+
+### ארכיטקטורה
+
+התצורה המשופרת של שורת הפקודה דורשת את הרכיבים הטכניים הבאים:
+
+1. **tg-list-config-items**
+   - רשימת מפתחות תצורה עבור סוג ספציפי
+   - קוראת לשיטת ה-API `Config.list(type)`
+   - פלט של רשימת מפתחות התצורה
+   
+   מודול: `trustgraph.cli.list_config_items`
+
+2. **tg-get-config-item**
+   - השגת פריט תצורה ספציפי(ים)
+   - קוראת לשיטת ה-API `Config.get(keys)`
+   - פלט של ערכי התצורה בפורמט JSON
+
+   מודול: `trustgraph.cli.get_config_item`
+
+3. **tg-put-config-item**
+   - הגדרת או עדכון פריט תצורה
+   - קוראת לשיטת ה-API `Config.put(values)`
+   - מקבל את פרמטרי הטיפוס, המפתח והערך
+
+   מודול: `trustgraph.cli.put_config_item`
+
+4. **tg-delete-config-item**
+   - הסרת פריט תצורה
+   - קוראת לשיטת ה-API `Config.delete(keys)`
+   - מקבל את פרמטרי הטיפוס והמפתח
+
+   מודול: `trustgraph.cli.delete_config_item`
+
+### מודלים של נתונים
+
+#### ConfigKey ו-ConfigValue
+
+הפקודות משתמשות במבני נתונים הקיימים מ-`trustgraph.api.types`:
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+גישה זו מאפשרת:
+- טיפול עקבי בנתונים בכל ה-CLI וה-API
+- פעולות תצורה מסוג-יציבות
+- פורמטי קלט/פלט מובנים
+- שילוב עם ה-API של התצורה הקיים
+
+### מפרטי פקודות שורת הפקודה
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
+```
+- **מטרה**: רשימת מפתחות התצורה עבור סוג נתון
+- **קריאה ל-API**: `Config.list(type)`
+- **פלט**:
+  - `text` (ברירת מחדל): מפתחות התצורה מופרדים ברווחים
+  - `json`: מערך JSON של מפתחות התצורה
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
+```
+- **מטרה**: השגת פריט תצורה ספציפי
+- **קריאה ל-API**: `Config.get([ConfigKey(type, key)])`
+- **פלט**: ערך התצורה
+
+#### הגדרת פריט תצורה
+```bash
+tg-put-config-item --type <type> --key <key> --value <value>
+```
+- **מטרה**: הגדרת או עדכון פריט תצורה
+- **קריאה ל-API**: `Config.put(key, value)`
+- **פרמטרים**:
+  - `<type>`: סוג פריט התצורה (לדוגמה, "prompt", "system-prompt")
+  - `<key>`: המפתח של פריט התצורה
+  - `<value>`: הערך של פריט התצורה
+
+#### מחיקת פריט תצורה
+```bash
+tg-delete-config-item --type <type> --key <key>
+```
+- **מטרה**: הסרת פריט תצורה
+- **קריאה ל-API**: `Config.delete(key)`
+- **פרמטרים**:
+  - `<type>`: סוג פריט התצורה
+  - `<key>`: המפתח של פריט התצורה
+
+## שאלות פתוחות
+
+- האם יש לשנות את הפקודות לתמוך בפעולות מקובצות (מפתחות מרובים) בנוסף לפריטים בודדים?
+- איזה פורמט פלט צריך להיות בשימוש עבור אישור הצלחה?
+- איך המשתמשים יכולים לגלות או לתעד את סוגי התצורה?

docs/tech-specs/more-config-cli.ru.md

@@ -0,0 +1,202 @@
+# Техническая спецификация CLI для конфигурации
+
+## Обзор
+
+Эта спецификация описывает расширенные возможности конфигурации через командную строку для TrustGraph, позволяя пользователям управлять отдельными элементами конфигурации с помощью команд CLI с гранулярным уровнем доступа. Интеграция поддерживает четыре основных сценария использования:
+
+1. **Перечисление элементов конфигурации**: Отображение ключей конфигурации определенного типа
+2. **Получение элемента конфигурации**: Получение конкретных значений конфигурации
+3. **Установка элемента конфигурации**: Установка или обновление отдельных элементов конфигурации
+4. **Удаление элемента конфигурации**: Удаление конкретных элементов конфигурации
+
+## Цели
+
+- **Детализированный контроль**: Обеспечение управления отдельными элементами конфигурации, а не пакетными операциями
+- **Список по типу**: Предоставление пользователям возможности исследовать элементы конфигурации по типу
+- **Операции для отдельных элементов**: Предоставление команд для получения/установки/удаления отдельных элементов конфигурации
+- **Интеграция с API**: Использование существующего API для конфигурации для всех операций
+- **Единый шаблон CLI**: Соблюдение установленных норм и шаблонов CLI для TrustGraph
+- **Обработка ошибок**: Предоставление понятных сообщений об ошибках для некорректных операций
+- **Вывод в формате JSON**: Поддержка структурированного вывода для программного использования
+- **Документация**: Включение подробной справки и примеров использования
+
+## Предыстория
+
+TrustGraph в настоящее время предоставляет управление конфигурацией через API для конфигурации и один командный интерфейс `tg-show-config`, который отображает всю конфигурацию. Хотя это работает для просмотра конфигурации, оно не обеспечивает возможности детального управления.
+
+Текущие ограничения включают:
+- Отсутствие возможности перечисления элементов конфигурации по типу через командную строку
+- Отсутствие командной строки для получения конкретных значений конфигурации
+- Отсутствие командной строки для установки отдельных элементов конфигурации
+- Отсутствие командной строки для удаления отдельных элементов конфигурации
+
+Эта спецификация решает эти проблемы, добавляя четыре новые команды CLI, которые обеспечивают детальное управление конфигурацией. Предоставляя отдельные операции API через команды CLI, TrustGraph может:
+- Обеспечить управление конфигурацией через скрипты
+- Предоставить пользователям возможность исследовать структуру конфигурации по типу
+- Обеспечить целевые обновления конфигурации
+- Обеспечить детальный контроль над конфигурацией
+
+## Техническое проектирование
+
+### Архитектура
+
+Для расширенного CLI необходимо следующее техническое:
+
+1. **tg-list-config-items**
+   - Перечисление ключей конфигурации для указанного типа
+   - Вызов API-метода Config.list(type)
+   - Вывод списка ключей конфигурации
+
+   Модуль: `trustgraph.cli.list_config_items`
+
+2. **tg-get-config-item**
+   - Получение конкретного элемента конфигурации(й)
+   - Вызов API-метода Config.get(keys)
+   - Вывод значений конфигурации в формате JSON
+
+   Модуль: `trustgraph.cli.get_config_item`
+
+3. **tg-put-config-item**
+   - Установка или обновление элемента конфигурации
+   - Вызов API-метода Config.put(values)
+   - Прием параметров type, key и value
+
+   Модуль: `trustgraph.cli.put_config_item`
+
+4. **tg-delete-config-item**
+   - Удаление элемента конфигурации
+   - Вызов API-метода Config.delete(keys)
+   - Прием параметров type и key
+
+   Модуль: `trustgraph.cli.delete_config_item`
+
+### Модели данных
+
+#### ConfigKey и ConfigValue
+
+Команды используют существующие структуры данных из `trustgraph.api.types`:
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+Это обеспечивает:
+- Последовательную обработку данных в CLI и API
+- Типобезопасное управление конфигурацией
+- Структурированные форматы ввода/вывода
+- Интеграцию с существующим API для конфигурации
+
+### Спецификации команд CLI
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
+```
+- **Назначение**: Отобразить все ключи конфигурации для данного типа
+- **API-вызов**: `Config.list(type)`
+- **Вывод**:
+  - `text` (по умолчанию): Ключи конфигурации, разделенные новыми строками
+  - `json`: Массив строк JSON с ключами конфигурации
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
+```
+- **Назначение**: Получить конкретный элемент конфигурации
+- **API-вызов**: `Config.get([ConfigKey(type, key)])`
+- **Вывод**:
+  - `text` (по умолчанию): Сырая текстовая строка
+  - `json`: JSON-кодированная строка значения
+
+#### tg-put-config-item
+```bash
+tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
+tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
+```
+- **Назначение**: Установить или обновить элемент конфигурации
+- **API-вызов**: `Config.put([ConfigValue(type, key, value)])`
+- **Варианты ввода**:
+  - `--value <строка>`: Строковое значение, указанное непосредственно в командной строке
+  - `--stdin`: Чтение всего ввода как значения конфигурации
+- **Вывод**: Подтверждение успеха
+
+#### tg-delete-config-item
+```bash
+tg-delete-config-item --type <type> --key <key> [--api-url <url>]
+```
+- **Назначение**: Удалить элемент конфигурации
+- **API-вызов**: `Config.delete([ConfigKey(type, key)])`
+- **Вывод**: Подтверждение успеха
+
+### Детали реализации
+
+Все команды следуют установленной схеме CLI для TrustGraph:
+- Использование `argparse` для разбора командной строки
+- Импорт и использование `trustgraph.api.Api` для взаимодействия с backend
+- Соблюдение тех же схем обработки ошибок, что и у существующих CLI
+- Поддержка стандартного параметра `--api-url` для настройки URL API
+- Предоставление описательного справки и примеров использования
+
+#### Обработка форматов вывода
+
+**Текст:**
+```bash
+tg-list-config-items --type prompt
+template-1
+template-2
+system-prompt
+```
+
+**JSON:**
+```bash
+tg-list-config-items --type prompt --format json
+["template-1", "template-2", "system-prompt"]
+```
+
+**Текст:**
+```bash
+tg-get-config-item --type prompt --key template-1
+You are a helpful assistant. Please respond to: {query}
+```
+
+**JSON:**
+```bash
+tg-get-config-item --type prompt --key template-1 --format json
+"You are a helpful assistant. Please respond to: {query}"
+```
+
+**Текст:**
+```bash
+tg-put-config-item --type prompt --key new-template --value "Custom prompt: {input}"
+```
+
+**JSON:**
+```bash
+tg-put-config-item --type prompt --key complex-template --stdin < ./prompt-template.txt
+```
+
+**Текст:**
+```bash
+tg-delete-config-item --type prompt --key old-template
+```
+
+## Открытые вопросы
+
+- Следует ли командам поддерживать пакетные операции (несколько ключей) помимо отдельных элементов?
+- Какой формат вывода следует использовать для подтверждений успеха?
+- Как следует документировать и узнавать пользователями типы конфигурации?
+
+## Ссылки
+
+- Существующий API для конфигурации: `trustgraph/api/config.py`
+- Шаблоны CLI: `trustgraph-cli/trustgraph/cli/show_config.py`
+- Типы данных: `trustgraph/api/types.py`

docs/tech-specs/more-config-cli.zh-cn.md

@@ -0,0 +1,178 @@
+# 更高级的 CLI 技术规格
+
+## 概述
+
+该规范描述了 TrustGraph 的增强型命令行配置功能，允许用户通过精细的 CLI 命令来管理单个配置项。 该集成支持四个主要用例：
+
+1.  **列出配置项**: 显示特定类型的配置键
+2.  **获取配置项**: 获取特定配置值
+3.  **设置配置项**: 设置或更新单个配置项
+4.  **删除配置项**: 删除特定配置项
+
+## 目标
+
+-   **精细控制**: 能够管理单个配置项，而不是批量操作
+-   **基于类型的列出**: 允许用户按类型探索配置项
+-   **单个项操作**: 提供获取/设置/删除单个配置项的命令
+-   **API 集成**: 利用现有的 Config API 进行所有操作
+-   **一致的 CLI 模式**: 遵循 TrustGraph 的标准 CLI 约定和模式
+-   **错误处理**: 提供无效操作的清晰错误消息
+-   **JSON 输出**: 支持结构化输出，用于程序化使用
+-   **文档**: 包含全面的帮助和用法示例
+
+## 背景
+
+目前，TrustGraph 通过 Config API 和一个名为 `tg-show-config` 的单一 CLI 命令来管理配置。 该命令显示整个配置。 虽然这对于查看配置有效，但缺乏精细的管理功能。
+
+目前存在以下限制：
+-   无法从 CLI 列出按类型配置项
+-   没有 CLI 命令用于检索特定配置值
+-   没有 CLI 命令用于设置单个配置项
+-   没有 CLI 命令用于删除特定配置项
+
+该规范通过添加四个新的 CLI 命令来解决这些问题，从而提供精细的配置管理。 通过将单个 Config API 操作暴露到 CLI 命令中，TrustGraph 可以：
+-   启用脚本化的配置管理
+-   允许用户按类型探索配置结构
+-   支持有针对性的配置更新
+-   提供精细的配置控制
+
+## 技术设计
+
+### 架构
+
+增强的 CLI 配置需要以下技术组件：
+
+1.  **tg-list-config-items**
+    -   列出指定类型的配置键
+    -   调用 Config.list(type) API 方法
+    -   输出配置键列表
+
+    模块：`trustgraph.cli.list_config_items`
+
+2.  **tg-get-config-item**
+    -   检索特定配置项
+    -   调用 Config.get(keys) API 方法
+    -   以 JSON 格式输出配置值
+
+    模块：`trustgraph.cli.get_config_item`
+
+3.  **tg-put-config-item**
+    -   设置或更新配置项
+    -   调用 Config.put(values) API 方法
+    -   接受类型、键和值参数
+
+    模块：`trustgraph.cli.put_config_item`
+
+4.  **tg-delete-config-item**
+    -   删除配置项
+    -   调用 Config.delete(keys) API 方法
+    -   接受类型和键参数
+
+    模块：`trustgraph.cli.delete_config_item`
+
+### 数据模型
+
+#### ConfigKey 和 ConfigValue
+
+这些命令使用来自 `trustgraph.api.types` 的现有数据结构：
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+这种方法允许：
+-   在 CLI 和 API 中保持数据的一致性
+-   类型安全的配置操作
+-   结构化输入/输出格式
+-   与现有的 Config API 集成
+
+### CLI 命令规范
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
+```
+-   **目的**: 列出给定类型的所有配置键
+-   **API 调用**: `Config.list(type)`
+-   **输出**:
+    -   `text` (默认): 键按换行分隔
+    -   `json`: 键的 JSON 数组
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
+```
+-   **目的**: 获取特定配置项
+-   **API 调用**: `Config.get([ConfigKey(type, key)])`
+-   **输出**:
+    -   `text` (默认): 原始字符串值
+    -   `json`: JSON 编码的字符串值
+
+#### tg-put-config-item
+```bash
+tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
+tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
+```
+-   **目的**: 设置或更新配置项
+-   **API 调用**: `Config.put([ConfigValue(type, key, value)])`
+-   **输入选项**:
+    -   `--value <字符串>`: 直接在命令行中提供的字符串值
+    -   `--stdin`: 从标准输入读取整个输入作为配置值
+    -   标准输入读取为原始文本 (保留换行符、空格等)
+    -   支持通过文件、命令或交互式输入
+
+#### tg-delete-config-item
+```bash
+tg-delete-config-item --type <type> --key <key> [--api-url <url>]
+```
+-   **目的**: 删除配置项
+-   **API 调用**: `Config.delete([ConfigKey(type, key)])`
+-   **输出**: 成功确认
+
+### 实现细节
+
+所有命令都遵循 TrustGraph 的标准 CLI 模式：
+-   使用 `argparse` 进行命令行参数解析
+-   导入和使用 `trustgraph.api.Api` 进行后端通信
+-   遵循现有 CLI 命令的相同错误处理模式
+-   支持标准 `--api-url` 参数，用于配置 API 端点
+-   提供描述性的帮助文本和用法示例
+
+#### 输出格式处理
+
+**文本格式 (默认)**:
+-   `tg-list-config-items`: 键按新行分隔，纯文本
+-   `tg-get-config-item`: 原始字符串值，无引号或编码
+
+**JSON 格式**:
+-   `tg-list-config-items`: 字符串数组 `["key1", "key2", "key3"]`
+-   `tg-get-config-item`: JSON 编码的字符串值 `"实际字符串值"`
+
+#### 输入处理
+
+**tg-put-config-item** 支持两种互斥的输入方法：
+-   `--value <字符串>`: 命令行中的直接字符串值
+-   `--stdin`: 从标准输入读取整个输入作为配置值
+-   标准输入读取为原始文本 (保留换行符、空格等)
+-   支持通过文件、命令或交互式输入
+
+## 安全性
+
+-   如果配置项包含敏感信息，如何安全地处理这些信息？
+-   如何验证用户输入，以防止恶意攻击？
+-   如何控制对配置项的访问权限？
+
+## 开放问题
+
+-   是否应该支持命令以批量操作 (多个键) 之外的单个项？
+-   成功确认消息应该使用哪种格式？
+-   用户应该如何发现和使用配置类型？

docs/tech-specs/neo4j-user-collection-isolation.es.md

@@ -0,0 +1,209 @@
+# Soporte de aislamiento de usuarios/colecciones en Neo4j
+
+## Declaración del problema
+
+La implementación actual de almacenamiento y consulta de triples en Neo4j carece de aislamiento de usuarios/colecciones, lo que genera una vulnerabilidad de seguridad para entornos multi-inquilinos. Todos los triples se almacenan en el mismo espacio de grafo sin ningún mecanismo para evitar que los usuarios accedan a los datos de otros usuarios o mezclen colecciones.
+
+A diferencia de otros backends de almacenamiento en TrustGraph:
+- **Cassandra**: Utiliza espacios de claves y tablas separados por usuario y colección
+- **Almacenes vectoriales** (Milvus, Qdrant, Pinecone): Utilizan espacios de nombres específicos de la colección
+- **Neo4j**: Actualmente comparte todos los datos en un único grafo (vulnerabilidad de seguridad)
+
+## Arquitectura actual
+
+### Modelo de datos
+- **Nodos**: Etiqueta `:Node` con propiedad `uri`, etiqueta `:Literal` con propiedad `value`
+- **Relaciones**: Etiqueta `:Rel` con propiedad `uri`
+- **Índices**: `Node.uri`, `Literal.value`, `Rel.uri`
+
+### Flujo de mensajes
+- Los mensajes `Triples` contienen los campos `metadata.user` y `metadata.collection`
+- El servicio de almacenamiento recibe la información del usuario/colección, pero la ignora
+- El servicio de consulta espera `user` y `collection` en `TriplesQueryRequest`, pero los ignora
+
+### Problema de seguridad actual
+```cypher
+# Cualquier usuario puede consultar cualquier dato - sin aislamiento
+MATCH (src:Node)-[rel:Rel]->(dest:Node) 
+RETURN src.uri, rel.uri, dest.uri
+```
+
+## Solución propuesta: Filtrado basado en propiedades (Recomendado)
+
+### Descripción general
+Añadir las propiedades `user` y `collection` a todos los nodos y relaciones, y luego filtrar todas las operaciones por estas propiedades. Este enfoque proporciona un fuerte aislamiento manteniendo la flexibilidad de consulta y la compatibilidad con versiones anteriores.
+
+### Cambios en el modelo de datos
+
+#### Estructura de nodos mejorada
+```cypher
+// Entidades de nodo
+CREATE (n:Node {
+  uri: "http://example.com/entity1",
+  user: "john_doe", 
+  collection: "production_v1"
+})
+
+// Entidades de literal
+CREATE (n:Literal {
+  value: "literal value",
+  user: "john_doe",
+  collection: "production_v1" 
+})
+```
+
+#### Estructura de relaciones mejorada
+```cypher
+// Relaciones con propiedades user/collection
+CREATE (src)-[:Rel {
+  uri: "http://example.com/predicate1",
+  user: "john_doe",
+  collection: "production_v1"
+}]->(dest)
+```
+
+#### Índices actualizados
+```cypher
+// Índices compuestos para un filtrado eficiente
+CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
+CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
+CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
+
+// Mantener índices existentes para la compatibilidad con versiones anteriores (opcional)
+CREATE INDEX Node_uri FOR (n:Node) ON (n.uri);
+CREATE INDEX Literal_value FOR (n:Literal) ON (n.value);
+CREATE INDEX Rel_uri FOR ()-[r:Rel]-() ON (r.uri);
+```
+
+### Cambios de implementación
+
+#### Servicio de almacenamiento (`write.py`)
+
+**Código actual:**
+```python
+def create_node(self, uri):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri})",
+        uri=uri, database_=self.db,
+    ).summary
+```
+
+**Código actualizado:**
+```python
+def create_node(self, uri, user, collection):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri, user: $user, collection: $collection})",
+        uri=uri, user=user, collection=collection, database_=self.db,
+    ).summary
+```
+
+#### Función query
+```python
+def query_triples(self, query):
+    # Implementar lógica para filtrar por usuario y colección en la consulta
+    # Por ejemplo, reemplazar 'user' y 'collection' en la consulta
+    # Usar la función de ejecución de consultas de Neo4j para reemplazar
+    # los marcadores de posición con los valores del usuario y la colección
+    # y luego ejecutar la consulta.
+    # Ejemplo (pseudocódigo):
+    # resultado = neo4j.execute_query(query.replace("user", self.user), self.collection)
+    # return resultado
+    pass
+```
+
+#### Función store_triples
+```python
+def store_triples(self, triples):
+    # Implementar lógica para almacenar triples con las propiedades user y collection
+    # Por ejemplo, añadir las propiedades user y collection a los nodos al crear
+    #  nuevos nodos y relaciones.
+    pass
+```
+
+### Pruebas
+
+### Pruebas unitarias
+```python
+def test_user_collection_isolation():
+    # Almacenar triples para user1/collection1
+    processor.store_triples(triples_user1_coll1)
+    
+    # Almacenar triples para user2/collection2
+    processor.store_triples(triples_user2_coll2)
+    
+    # Consultar como user1 solo debería devolver datos de user1/collection1
+    resultados = processor.query_triples(query_user1_coll1)
+    assert all_results_belong_to_user1_coll1(resultados)
+    
+    # Consultar como user2 solo debería devolver datos de user2/collection2
+    resultados = processor.query_triples(query_user2_coll2)
+    assert all_results_belong_to_user2_coll2(resultados)
+```
+
+### Pruebas de integración
+- Escenarios de múltiples usuarios con datos superpuestos
+- Consultas de cross-colección (deberían fallar)
+- Pruebas de migración con datos existentes
+- Pruebas de rendimiento con grandes conjuntos de datos
+
+### Pruebas de seguridad
+- Intentar consultar datos de otros usuarios
+- Ataques de inyección SQL en parámetros de usuario/colección
+- Verificar el aislamiento completo bajo diferentes patrones de consulta
+
+## Consideraciones de rendimiento
+
+### Estrategia de índice
+- Índices compuestos en `(user, collection, uri)` para un filtrado óptimo
+- Considerar índices parciales si algunas colecciones son mucho más grandes
+- Supervisar el uso y el rendimiento de los índices
+
+### Optimización de consultas
+- Utilizar EXPLAIN para verificar el uso de índices en las consultas filtradas
+- Considerar el almacenamiento en caché de resultados para datos accedidos con frecuencia
+- Perfilar el uso de memoria con un gran número de usuarios/colecciones
+
+### Escalabilidad
+- Cada combinación de usuario/colección crea islas de datos separadas
+- Supervisar el tamaño de la base de datos y el uso de la piscina de conexiones
+- Considerar estrategias de escalado horizontal si es necesario
+
+## Seguridad y cumplimiento
+
+### Garantías de aislamiento de datos
+- **Físico**: Todos los datos del usuario almacenados con propiedades de usuario/colección explícitas
+- **Lógico**: Todas las consultas filtradas por contexto de usuario/colección
+- **Control de acceso**: Validación a nivel de servicio para evitar el acceso no autorizado
+
+### Requisitos de auditoría
+- Registrar todos los accesos de datos con contexto de usuario/colección
+- Rastrear las actividades de migración y los movimientos de datos
+- Supervisar los intentos de violar el aislamiento
+
+### Consideraciones de cumplimiento
+- GDPR: Mayor capacidad para localizar y eliminar datos específicos del usuario
+- SOC2: Claros controles de aislamiento de datos y acceso
+- HIPAA: Fuerte aislamiento de inquilinos para datos de atención médica
+
+## Riesgos y mitigaciones
+
+| Riesgo | Impacto | Probabilidad | Mitigación |
+|------|--------|------------|------------|
+| Consulta sin filtro de usuario/colección | Alto | Medio | Validación obligatoria, pruebas exhaustivas |
+| Degradación del rendimiento | Medio | Bajo | Optimización del índice, perfilado de consultas |
+| Corrupción de datos durante la migración | Alto | Bajo | Estrategia de copia de seguridad, procedimientos de reversión |
+| Complejidad de consultas multi-colección | Medio | Medio | Documentar los patrones de consulta, proporcionar ejemplos |
+
+## Criterios de éxito
+
+1. **Seguridad**: Cero acceso de datos cruzado de usuarios en producción
+2. **Rendimiento**: <10% de impacto en el rendimiento de las consultas en comparación con las consultas no filtradas
+3. **Migración**: 100% de los datos existentes migrados sin pérdida de datos
+4. **Usabilidad**: Todos los patrones de consulta existentes funcionan con contexto de usuario/colección
+5. **Cumplimiento**: Rastro de auditoría completo del acceso de datos de usuario/colección
+
+## Conclusión
+
+El enfoque de filtrado basado en propiedades proporciona el mejor equilibrio de seguridad, rendimiento y mantenibilidad para añadir aislamiento de usuarios/colecciones a Neo4j. Se alinea con los patrones de multi-inquilinos existentes de TrustGraph al tiempo que aprovecha las fortalezas de Neo4j en la consulta y el indexado de grafos.
+
+Esta solución garantiza que el backend de Neo4j de TrustGraph cumpla con los mismos estándares de seguridad que otros backends de almacenamiento, evitando las vulnerabilidades de aislamiento de datos al tiempo que mantiene la flexibilidad y el poder de las consultas de grafos.

docs/tech-specs/neo4j-user-collection-isolation.he.md

@@ -0,0 +1,188 @@
+# תמיכה ביסודות משתמשים/מערכות ב-Neo4j
+
+## הצגת הבעיה
+
+המימוש הנוכחי של אחסון שאילתות ב-Neo4j סובל מחוסר ביסודות משתמשים/מערכות, מה שיוצר בעיות אבטחה במצב רב-משתמשים. כל השלישים מאוחסנים במרחב גרף אחד ללא מנגנון למניעת משתמשים מגישה לנתונים של משתמשים אחרים או מיזוג מערכות.
+
+בניגוד למערכות אחסון אחרות ב-TrustGraph:
+- **Cassandra**: משתמשת במרחבי מפתחות נפרדים לכל משתמש וטבלאות לכל מערכת
+- **אחסון וקטורי** (Milvus, Qdrant, Pinecone): משתמשים בשמות מרחבים ספציפיים למערכות
+- **Neo4j**: כיום, משתמשת בכל הנתונים במרחב גרף אחד (פגיעות אבטחה)
+
+## ארכיטקטורה נוכחית
+
+### מודל נתונים
+- **צמתים**: תוויות `:Node` עם תכונה `uri`, תוויות `:Literal` עם תכונה `value`
+- **קשרים**: תוויות `:Rel` עם תכונת `uri`
+- **אינדקסים**: `Node.uri`, `Literal.value`, `Rel.uri`
+
+### זרימת הודעות
+- הודעות `Triples` מכילות שדות `metadata.user` ו-`metadata.collection`
+- שירות האחסון מקבל מידע על משתמשים/מערכות אך מתעלם ממנו
+- שירות השאילתות מצפה לשדות `user` ו-`collection` בבקשת `TriplesQueryRequest` אך מתעלם מהם
+
+### בעיית אבטחה נוכחית
+```cypher
+# כל משתמש יכול לשאול כל נתונים - אין ביסודות
+MATCH (src:Node)-[rel:Rel]->(dest:Node)
+RETURN src.uri, rel.uri, dest.uri
+```
+
+## פתרון מוצע: סינון מבוסס תכונות (מומלץ)
+
+### סקירה כללית
+הוסף תכונות `user` ו-`collection` לכל הצמתים והקשרים, ואז לסנן את כל הפעולות לפי התכונות הללו. גישה זו מספקת ביסודות חזקות תוך שמירה על גמישות שאילתות והתאמה לגרסאות קודמות.
+
+### שינויים במודל נתונים
+
+#### מבנה צומת משופר
+```cypher
+// ישויות צומת
+CREATE (n:Node {
+  uri: "http://example.com/entity1",
+  user: "john_doe",
+  collection: "production_v1"
+})
+
+// ישויות Literal
+CREATE (n:Literal {
+  value: "literal value",
+  user: "john_doe",
+  collection: "production_v1"
+})
+```
+
+#### מבנה קשר משופר
+```cypher
+// קשרים עם תכונות משתמש/מערכת
+CREATE (src)-[:Rel {
+  uri: "http://example.com/predicate1",
+  user: "john_doe",
+  collection: "production_v1"
+}]->(dest)
+```
+
+#### אינדקסים מעודכנים
+```cypher
+// אינדקסים משולבים לסינון יעיל
+CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
+CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
+CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
+
+// שמירה על אינדקסים קיימים לאחור התאמה (אופציונלי)
+```
+
+## תוכנית יישום
+
+### שלב 1: יסודות (שבוע 1)
+1. [ ] עדכן את שירות האחסון לקבל ולשמור תכונות משתמש/מערכת
+2. [ ] הוסף אינדקסים משולבים לביצוע שאילתות מיטבי
+3. [ ] יישם שכבת התאמה לגרסאות קודמות
+4. [ ] צור בדיקות יחידה לפונקציונליות החדשה
+
+### שלב 2: עדכוני שאילתות (שבוע 2)
+1. [ ] עדכן את כל דפוסי השאילתות כדי לכלול סינון משתמש/מערכת
+2. [ ] הוסף אימות שאילתות ובקרת אבטחה
+3. [ ] עדכן בדיקות אינטגרציה
+4. [ ] בדיקות ביצוע עם שאילתות מסוננות
+
+### שלב 3: העברה והפצה (שבוע 3)
+1. [ ] צור סקריפטים להעברת נתונים עבור מופעי Neo4j קיימים
+2. [ ] תיעוד והוראות הפעלה
+3. [ ] ניטור והתראות על הפרות ביסודות
+4. [ ] בדיקות סיום עם מספר משתמשים/מערכות
+
+### שלב 4: חיזוק (שבוע 4)
+1. [ ] הסר את מצב ההתאמה לגרסאות קודמות
+2. [ ] הוסף רישום ביקורת מקיף
+3. [ ] ביקורת אבטחה וגישה
+4. [ ] בדיקות ביצוע 
+
+## אסטרטגיית בדיקה
+
+### בדיקות יחידה
+```python
+def test_user_collection_isolation():
+    # שמור שליש עבור משתמש1/מערכת1
+    processor.store_triples(triples_user1_coll1)
+    
+    # שמור שליש עבור משתמש2/מערכת2
+    processor.store_triples(triples_user2_coll2)
+    
+    # שאילת משתמש1 צריך רק להחזיר את הנתונים של משתמש1
+    results = processor.query_triples(query_user1_coll1)
+    assert all_results_belong_to_user1_coll1(results)
+    
+    # שאילת משתמש2 צריך רק להחזיר את הנתונים של משתמש2
+    results = processor.query_triples(query_user2_coll2)
+    assert all_results_belong_to_user2_coll2(results)
+```
+
+### בדיקות אינטגרציה
+- תרחישים רב-משתמשים עם נתונים חופפים
+- שאילתות בין מערכות (צריכות להיכשל)
+- בדיקות העברה עם נתונים קיימים
+- ביצועים - שורה עם מערכות נתונים גדולות
+
+### בדיקות אבטחה
+- ניסיון לשאול נתונים של משתמשים אחרים
+- התקפות SQL על פרמטרים של משתמש/מערכת
+- אימות של ביסודות תחת דפוסי שאילתות שונים
+
+## שיקולי ביצועים
+
+### אסטרטגיית אינדקס
+- אינדקסים משולבים על `(user, collection, uri)` לביצוע שאילתות מיטבי
+- שקול אינדקסים חלקיים אם יש למערכות רבות יותר גודל גדול
+- עקוב אחר שימוש באינדקס וביצוע שאילתות
+
+### אופטימיזציה של שאילתות
+- השתמש ב-EXPLAIN כדי לוודא שימוש באינדקס בשאילתות מסוננות
+- שקול אחסון תוצאות שאילתות לשימוש חוזר
+- פרופיל שימוש בזיכרון עם מספר משתמשים/מערכות גדולים
+
+### סקלאביליות
+- כל מערכת משתמשים/מערכת יוצרת איזולציה נפרדת של נתונים
+- עקוב אחר גודל מסד הנתונים ושימוש בבריאת חיבורים
+- שקול אסטרטגיות סקלאביליות אופקיות במידת הצורך
+
+## אבטחה ותאימות
+
+### ביסודות נתונים
+- **פיזי**: כל הנתונים של משתמש מאוחסנים עם תכונות משתמש/מערכת ספציפיות
+- **לוגי**: כל השאילתות מסוננות על ידי הקשר משתמש/מערכת
+- **בקרה**: שכבת שירות מאמתת גישה
+
+### דרישות ביקורת
+- רשום את כל גישה לנתונים עם הקשר משתמש/מערכת
+- עקוב אחר פעילויות העברה
+- עקוב אחר ניסיונות הפרות ביסודות
+
+### שיקולים תאימות
+- GDPR: יכולת טובה יותר למצוא ולמחוק נתונים ספציפיים למשתמשים
+- SOC2: בקרה בסיסית וגישה של משתמשים
+- HIPAA: ביסודות חזקים עבור נתונים בתחום הבריאות
+
+## סיכונים ותיקונים
+
+| סיכון | השפעה | הסתברות | תיקון |
+|------|--------|------------|------------|
+| שאילתות חסרות סינון משתמש/מערכת | גבוה | בינונית | אימות חובה, בדיקות מקיפות |
+| ירידה בביצועים | בינונית | נמוכה | אופטימיזציה של אינדקס, פרופיל שאילתות |
+| אובדן נתונים בהעברה | גבוה | נמוכה | אסטרטגיית גיבוי, פרוצדורות שלבים אחורה |
+| קשיים בהתאמה לגרסאות קודמות | בינונית | בינונית | תוכנית יישום, תיעוד |
+| קשיים בביצוע שאילתות מורכבות | בינונית | בינונית | תיעוד דפוסי שאילתות |
+
+## קריטריוני הצלחה
+
+1. **אבטחה**: אין גישה בין משתמשים בייצור
+2. **ביצועים**: <10% השפעה על ביצועי השאילתות בהשוואה לשאילתות לא מסוננות
+3. **העברה**: 100% נתונים קיימים מוצלחים בהעברה ללא אובדן
+4. **שימושיות**: כל דפוסי השאילתות הקיימים עובדים עם הקשר משתמש/מערכת
+5. **תאימות**: תיעוד מלא של גישה לנתונים מבוסס משתמש/מערכת
+
+## מסקנה
+
+הגישה המבוססת על תכונות מספקת את האיזון הטוב ביותר של אבטחה, ביצועים וקלות תחזוקה להוספת ביסודות משתמשים/מערכות ב-Neo4j. היא תואמת עם דפוסי הרב-משתמשים הקיימים ב-TrustGraph תוך ניצול החוזקות של Neo4j בשאילתות גרפים ואינדקסים.
+
+פתרון זה מבטיח שהבסיס של ה-Neo4j ב-TrustGraph עומד בסטנדרטים אבטחיים כמו מערכות אחסון אחרות, ומספק ביסודות תוך שמירה על גמישות וגודל שאילתות.

docs/tech-specs/neo4j-user-collection-isolation.ru.md

@@ -0,0 +1,215 @@
+# Поддержка изоляции пользователя/коллекции в Neo4j
+
+## Формулировка проблемы
+
+Текущая реализация хранения и запросов в Neo4j не обеспечивает изоляцию пользователя/коллекции, что создает проблему безопасности многопользовательской среды. Все тройки хранятся в одном графе без каких-либо механизмов для предотвращения доступа пользователей к данным других пользователей или смешения коллекций.
+
+В отличие от других бэкендов хранения в TrustGraph:
+- **Cassandra**: использует отдельные пространства ключей для каждого пользователя и таблицы для каждой коллекции.
+- **Vector-хранилища** (Milvus, Qdrant, Pinecone): используют пространства имен, специфичные для коллекции.
+- **Neo4j**: в настоящее время все данные хранятся в одном графе (уязвимость для безопасности).
+
+## Текущая архитектура
+
+### Модель данных
+- **Узлы**: метка `:Node` с свойством `uri`, метка `:Literal` с свойством `value`
+- **Отношения**: метка `:Rel` с свойством `uri`
+- **Индексы**: `Node.uri`, `Literal.value`, `Rel.uri`
+
+### Поток сообщений
+- Сообщения `Triples` содержат поля `metadata.user` и `metadata.collection`
+- Сервис хранения получает информацию о пользователе/коллекции, но игнорирует ее
+- Сервис запросов ожидает `user` и `collection` в `TriplesQueryRequest`, но игнорирует их
+
+### Текущая проблема безопасности
+```cypher
+# Любой пользователь может запросить любые данные - нет изоляции
+MATCH (src:Node)-[rel:Rel]->(dest:Node)
+RETURN src.uri, rel.uri, dest.uri
+```
+
+## Предлагаемое решение: Фильтрация на основе свойств (Рекомендуется)
+
+### Обзор
+Добавьте свойства `user` и `collection` ко всем узлам и отношениям, а затем фильтруйте все операции по этим свойствам. Этот подход обеспечивает надежную изоляцию, сохраняя при этом гибкость запросов и обратную совместимость.
+
+### Изменения в модели данных
+
+#### Улучшенная структура узла
+```cypher
+// Узел
+CREATE (n:Node {
+  uri: "http://example.com/entity1",
+  user: "john_doe",
+  collection: "production_v1"
+})
+
+// Литеральные сущности
+CREATE (n:Literal {
+  value: "literal value",
+  user: "john_doe",
+  collection: "production_v1"
+})
+```
+
+#### Улучшенная структура отношений
+```cypher
+// Отношения с свойствами user/collection
+CREATE (src)-[:Rel {
+  uri: "http://example.com/predicate1",
+  user: "john_doe",
+  collection: "production_v1"
+}]->(dest)
+```
+
+#### Обновленные индексы
+```cypher
+// Комплексные индексы для эффективного фильтра
+CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
+CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
+CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
+
+// Сохранение существующих индексов для обратной совместимости (необязательно)
+CREATE INDEX Node_uri FOR (n:Node) ON (n.uri);
+CREATE INDEX Literal_value FOR (n:Literal) ON (n.value);
+CREATE INDEX Rel_uri FOR ()-[r:Rel]-() ON (r.uri);
+```
+
+### Изменения в реализации
+
+#### Сервис хранения (`write.py`)
+
+**Текущий код:**
+```python
+def create_node(self, uri):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri})",
+        uri=uri, database_=self.db,
+    ).summary
+```
+
+**Обновленный код:**
+```python
+def create_node(self, uri, user, collection):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri})",
+        uri=uri, user=user, collection=collection, database_=self.db,
+    ).summary
+```
+
+#### Сервис запросов
+- Добавьте фильтры для user и collection в запросы, чтобы обеспечить изоляцию.
+
+### План реализации
+
+### Этап 1: Основа (Неделя 1)
+1. [ ] Обновление сервиса хранения для приема и хранения свойств user/collection
+2. [ ] Создание комплексных индексов для эффективного запроса
+3. [ ] Реализация обратной совместимости
+4. [ ] Создание модульных тестов для новой функциональности
+
+### Этап 2: Обновление запросов (Неделя 2)
+1. [ ] Обновление всех шаблонов запросов для включения фильтров user/collection
+2. [ ] Добавление валидации запросов и мер безопасности
+3. [ ] Обновление интеграционных тестов
+4. [ ] Тестирование производительности с запросами, отфильтрованными
+
+### Этап 3: Миграция и развертывание (Неделя 3)
+1. [ ] Создание скриптов миграции для существующих экземпляров Neo4j
+2. [ ] Документация и руководства по развертыванию
+3. [ ] Мониторинг и оповещения об изоляции
+4. [ ] Тестирование конвейера
+
+### Этап 4: Усиление (Неделя 4)
+1. [ ] Удаление режима обратной совместимости
+2. [ ] Добавление комплексной журнализации
+3. [ ] Проверка безопасности и тестирование на проникновение
+4. [ ] Оптимизация производительности
+
+## Стратегия тестирования
+
+### Модульные тесты
+```python
+def test_user_collection_isolation():
+    # Храним тройки для user1/collection1
+    processor.store_triples(triples_user1_coll1)
+
+    # Храним тройки для user2/collection2
+    processor.store_triples(triples_user2_coll2)
+
+    # Запрос как user1 должен возвращать только данные user1
+    results = processor.query_triples(query_user1_coll1)
+    assert all_results_belong_to_user1_coll1(results)
+
+    # Запрос как user2 должен возвращать только данные user2
+    results = processor.query_triples(query_user2_coll2)
+    assert all_results_belong_to_user2_coll2(results)
+```
+
+### Интеграционные тесты
+- Сценарии многопользовательского взаимодействия с перекрывающимися данными
+- Запросы к перекрестным коллекциям (должны завершаться неудачей)
+- Тестирование миграции с существующими данными
+- Тестирование производительности с большими наборами данных
+
+### Тесты безопасности
+- Попытки запросить данные других пользователей
+- Атаки SQL injection на параметры user/collection
+- Проверка полной изоляции при различных шаблонах запросов
+
+## Соображения производительности
+
+### Стратегия индексирования
+- Комплексные индексы на `(user, collection, uri)` для оптимальной фильтрации
+- Рассмотрите частичные индексы, если некоторые коллекции значительно больше
+- Отслеживайте использование и производительность индекса
+
+### Оптимизация запросов
+- Используйте EXPLAIN для проверки использования индекса в запросах, отфильтрованных по user/collection
+- Рассмотрите кэширование результатов запросов для часто используемых данных
+- Профилируйте использование памяти с большим количеством пользователей/коллекций
+
+### Масштабируемость
+- Каждая комбинация пользователя/коллекции создает отдельные "острова данных"
+- Отслеживайте размер базы данных и использование пула соединений
+- Рассмотрите стратегии горизонтального масштабирования, если необходимо
+
+## Безопасность и соответствие
+
+### Гарантии изоляции данных
+- **Физическая**: Все данные пользователя хранятся с явными свойствами user/collection
+- **Логическая**: Все запросы фильтруются по контексту user/collection
+- **Контроль доступа**: Уровень сервиса обеспечивает проверку доступа
+
+### Требования к отчетности
+- Отслеживайте доступ к данным с контекстом user/collection
+- Отслеживайте активности миграции и перемещения данных
+- Мониторинг попыток нарушить изоляцию
+
+### Соображения соответствия
+- GDPR: Улучшенная возможность находить и удалять данные, специфичные для пользователя
+- SOC2: Четкая изоляция и контроль доступа
+- HIPAA: Сильная изоляция для данных о здравоохранении
+
+## Риски и смягчающие факторы
+
+| Риск | Влияние | Вероятность | Смягчение |
+|------|--------|------------|------------|
+| Отсутствие фильтра user/collection в запросе | Высокий | Средняя | Обязательная валидация, комплексное тестирование |
+| Снижение производительности | Средний | Низкая | Оптимизация индекса, профилирование запросов |
+| Повреждение данных во время миграции | Высокий | Низкая | Стратегия резервного копирования, процедуры отката |
+| Уязвимость для безопасности | Высокий | Низкая | Проверка безопасности, тестирование на проникновение |
+
+## Критерии успеха
+
+1. **Безопасность**: Полная изоляция данных между пользователями в производственной среде
+2. **Производительность**: <10% влияния на производительность запросов по сравнению с нефильтрованными запросами
+3. **Миграция**: 100% данных существующего экземпляра Neo4j успешно мигрированы без потерь
+4. **Удобство использования**: Все существующие шаблоны запросов работают с контекстом user/collection
+5. **Соответствие**: Полный журнал доступа к данным с контекстом user/collection
+
+## Заключение
+
+Предлагаемый подход на основе фильтрации свойств обеспечивает наилучший баланс между безопасностью, производительностью и удобством обслуживания для добавления изоляции пользователя/коллекции в Neo4j. Он соответствует существующим многопользовательским шаблонам TrustGraph, одновременно используя возможности Neo4j в области запросов и индексирования графов.
+
+Это решение гарантирует, что бэкенд Neo4j TrustGraph соответствует тем же стандартам безопасности, что и другие бэкенды, обеспечивая при этом изоляцию данных, одновременно сохраняя гибкость и мощь запросов графов.

docs/tech-specs/neo4j-user-collection-isolation.zh-cn.md

@@ -0,0 +1,202 @@
+# Neo4j 用户/集合隔离支持
+
+## 问题陈述
+
+Neo4j 的三元存储和查询实现目前缺乏用户/集合隔离，从而导致多租户安全问题。所有三元都存储在同一个图空间中，且没有任何机制来防止用户访问其他用户的或混合集合的数据。
+
+与 TrustGraph 中的其他存储后端不同：
+- **Cassandra**: 使用每个用户和每个集合的单独键空间和表
+- **向量存储**（Milvus、Qdrant、Pinecone）: 使用集合特定的命名空间
+- **Neo4j**: 目前共享所有数据在一个图（安全漏洞）
+
+## 现有架构
+
+### 数据模型
+- **节点**: 标签为 `:Node`，具有 `uri` 属性，标签为 `:Literal`，具有 `value` 属性
+- **关系**: 标签为 `:Rel`，具有 `uri` 属性
+- **索引**: `Node.uri`、`Literal.value`、`Rel.uri`
+
+### 消息流程
+- `Triples` 消息包含 `metadata.user` 和 `metadata.collection` 字段
+- 存储服务接收用户/集合信息，但忽略它们
+- 查询服务期望在 `TriplesQueryRequest` 中包含 `user` 和 `collection`，但忽略它们
+
+### 现有安全问题
+```cypher
+# 任何用户都可以查询任何数据 - 无隔离
+MATCH (src:Node)-[rel:Rel]->(dest:Node)
+RETURN src.uri, rel.uri, dest.uri
+```
+
+## 建议解决方案：基于属性的过滤（推荐）
+
+### 概述
+添加所有节点的和关系的 `user` 和 `collection` 属性，然后使用这些属性对所有操作进行过滤。 这种方法在保持查询灵活性和向后兼容性的同时，提供强大的隔离。
+
+### 数据模型更改
+
+#### 增强的节点结构
+```cypher
+// 节点实体
+CREATE (n:Node {
+  uri: "http://example.com/entity1",
+  user: "john_doe",
+  collection: "production_v1"
+})
+
+// 字面量实体
+CREATE (n:Literal {
+  value: "literal value",
+  user: "john_doe",
+  collection: "production_v1"
+})
+```
+
+#### 增强的关系结构
+```cypher
+// 具有 user/collection 属性的关系
+CREATE (src)-[:Rel {
+  uri: "http://example.com/predicate1",
+  user: "john_doe",
+  collection: "production_v1"
+}]->(dest)
+```
+
+#### 更新的索引
+```cypher
+// 用于高效过滤的复合索引
+CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
+CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
+CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
+
+// 保持现有索引以实现向后兼容性（可选）
+CREATE INDEX Node_uri FOR (n:Node) ON (n.uri);
+CREATE INDEX Literal_value FOR (n:Literal) ON (n.value);
+CREATE INDEX Rel_uri FOR ()-[r:Rel]-() ON (r.uri);
+```
+
+### 实现更改
+
+#### 存储服务 (`write.py`)
+
+**当前代码：**
+```python
+def create_node(self, uri):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri})",
+        uri=uri, database_=self.db,
+    ).summary
+```
+
+**更新后的代码：**
+```python
+def create_node(self, uri, user, collection):
+    summary = self.io.execute_query(
+        "MERGE (n:Node {uri: $uri, user: $user, collection: $collection})",
+        uri=uri, user=user, collection=collection, database_=self.db,
+    ).summary
+```
+
+**增强的 store_triples 方法：**
+```python
+async def store_triples(self, message):
+    user = message.metadata.user
+    collection = message.metadata.collection
+    # 存储 triples
+    # ...
+```
+
+#### 查询更新
+（此处应包含修改查询模式以包含 user 和 collection 的代码。 示例：`query_user1_coll1 = "MATCH (n)-[:Rel]->(m) WHERE n.user = 'john_doe' AND n.collection = 'production_v1' RETURN n, m"`）
+
+### 阶段 2：查询更新（第 2 周）
+（此处应包含修改查询模式以包含 user 和 collection 的代码。 示例：`query_user1_coll1 = "MATCH (n)-[:Rel]->(m) WHERE n.user = 'john_doe' AND n.collection = 'production_v1' RETURN n, m"`）
+1. [ ] 更新所有查询模式，以便包含 user/collection 过滤器
+2. [ ] 添加查询验证和安全检查
+3. [ ] 更新集成测试
+4. [ ] 性能测试，使用过滤后的查询
+
+### 阶段 3：迁移和部署（第 3 周）
+1. [ ] 创建现有 Neo4j 实例的迁移脚本
+2. [ ] 部署文档和操作手册
+3. [ ] 监控和警报，用于隔离违规
+4. [ ] 端到端测试，使用多个用户/集合
+
+### 阶段 4：强化（第 4 周）
+1. [ ] 移除兼容性模式
+2. [ ] 添加全面的审计日志
+3. [ ] 安全审查和渗透测试
+4. [ ] 性能优化
+
+## 测试策略
+
+### 单元测试
+（此处应包含使用 user 和 collection 进行隔离的单元测试示例。 示例：`def test_user_collection_isolation(): ...`）
+
+### 集成测试
+- 具有重叠数据的多用户场景
+- 跨集合查询（应失败）
+- 迁移测试，使用现有数据
+- 性能基准测试，使用大量数据
+
+### 安全测试
+- 尝试查询其他用户的
+- 尝试 SQL 注入，利用 user/collection 参数
+- 验证在各种查询模式下是否完全隔离
+
+## 性能考虑
+
+### 索引策略
+- 使用 `(user, collection, uri)` 的复合索引，以实现最佳过滤
+- 如果某些集合非常大，请考虑使用部分索引
+- 监控索引使用情况和查询性能
+
+### 查询优化
+- 使用 EXPLAIN 验证过滤查询是否使用了索引
+- 考虑查询结果缓存，用于频繁访问的数据
+- 剖析与大量用户/集合一起使用时的内存使用情况
+
+### 可扩展性
+- 每个用户/集合组合都会创建一个单独的数据岛
+- 监控数据库大小和连接池使用情况
+- 考虑所需的水平扩展策略
+
+## 安全与合规
+
+### 数据隔离保证
+- **物理**: 所有用户数据都带有明确的用户/集合属性
+- **逻辑**: 所有查询都通过用户/集合上下文过滤
+- **访问控制**: 服务级别的验证防止未经授权的访问
+
+### 审计要求
+- 记录所有数据访问，包括用户/集合上下文
+- 跟踪数据移动和迁移活动
+- 监控隔离违规尝试
+
+### 合规性考虑
+- GDPR：更好地定位和删除用户特定数据
+- SOC2：清晰的数据隔离和访问控制
+- HIPAA：为医疗数据提供强大的租户隔离
+
+## 风险与缓解措施
+
+| 风险 | 影响 | 可能性 | 缓解措施 |
+|------|--------|------------|------------|
+| 缺少用户/集合过滤器 | 高 | 中 | 强制验证，全面测试 |
+| 查询性能下降 | 中 | 低 | 索引优化，查询剖析 |
+| 迁移数据损坏 | 高 | 低 | 备份策略，回滚程序 |
+| 复杂的跨集合查询 | 中 | 中 | 文档查询模式，提供示例 |
+
+## 成功标准
+
+1. **安全性**: 在生产环境中，没有任何跨用户的数据访问
+2. **性能**: 与未过滤的查询相比，影响小于 10%
+3. **迁移**: 100% 的现有 Neo4j 数据成功迁移，且没有数据丢失
+4. **可用性**: 所有现有的查询模式都与用户/集合上下文工作
+5. **合规性**: 完整地记录用户/集合数据访问
+
+## 结论
+
+基于属性的过滤方法，是实现 Neo4j 用户/集合隔离的最佳平衡方案，它既能保证安全性，又能保持查询的灵活性和强大的图查询功能。
+
+这个解决方案确保 TrustGraph 的 Neo4j 后端符合其他存储后端的相同安全标准，同时最大限度地发挥图查询和索引的优势。

docs/tech-specs/ontology.he.md

@@ -0,0 +1,200 @@
+# מבנה אונטולוגי - מפרט טכני
+
+## סקירה כללית
+
+מפרט זה מתאר את המבנה והפורמט של אונטולוגיות במערכת TrustGraph. אונטולוגיות מספקות מודלים פורמליים של ידע המגדירים מחלקות, תכונות ויחסים, ומאפשרים יכולות של הסקה והסקת מסקנות. המערכת משתמשת בפורמט תצורה השואב השראה מ-OWL, ומייצג באופן כללי מושגי OWL/RDFS תוך התאמה לדרישות של TrustGraph.
+
+**נוהל שמות:** הפרויקט משתמש בפורמט "קאב-קייז" (kebab-case) לכל המזהים (מפתחות תצורה, נקודות קצה של API, שמות מודולים, וכו') במקום "סנקה_קייז" (snake_case).
+
+## מטרות
+
+- **ניהול מחלקות ותכונות:** הגדרת מחלקות "דו-צורתיות" עם תכונות, תחומים, טווחי ערכים ומגבלות סוג
+- **תמיכה סמנטית עשירה:** אפשרות לתכונות RDFS/OWL מקיפות, כולל תוויות, תמיכה רב-לשונית ומגבלות פורמליות
+- **תמיכה באונטולוגיות מרובות:** אפשרות לאונטולוגיות מרובות להתקיים ולפעול יחד
+- **אימות והסקה:** הבטחת עמידה של האונטולוגיות בתקנים דמויי-OWL תוך בדיקות עקביות ותמיכה בהסקה
+- **תאימות לתקנים:** תמיכה בייבוא/ייצוא בפורמטים סטנדרטיים (Turtle, RDF/XML, OWL/XML) תוך שמירה על אופטימיזציה פנימית
+
+## רקע
+
+TrustGraph מאחסן אונטולוגיות כפריטים תצורה במערכת מבוססת מפתח-ערך גמישה. למרות שהפורמט מושפע מ-OWL (שפת אונטולוגיה ווב), הוא מותאם במיוחד לשימושים הספציפיים של TrustGraph ואינו עומד במלואן בכל המפרטים של OWL.
+
+אונטולוגיות ב-TrustGraph מאפשרות:
+- הגדרה של סוגי אובייקט פורמליים והתכונות שלהם
+- הגדרה של תחומים, טווחי ערכים ומגבלות סוג
+- הסקה וסקת מסקנות
+- יחסים מורכבים ומגבלות כמותיות
+- תמיכה רב-לשונית לבינלאומיות
+
+## מבנה אונטולוגי
+
+### אחסון תצורה
+
+אונטולוגיות מאוחסנות כפריטי תצורה עם התבנית הבאה:
+- **סוג:** `ontology`
+- **מפתח:** מזהה אונטולוגי ייחודי (למשל, `natural-world`, `domain-model`)
+- **ערך:** האונטולוגיה השלמה בפורמט JSON
+
+### מבנה JSON
+
+פורמט ה-JSON של האונטולוגיה מורכב מארבעה חלקים עיקריים:
+
+#### 1. מטא-נתונים
+
+מכיל מידע ניהולי ותיאורי על האונטולוגיה:
+
+```json
+{
+  "metadata": {
+    "name": "העולם הטבעי",
+    "description": "אונטולוגיה המכסה את הסדר הטבעי",
+    "version": "1.0.0",
+    "created": "2025-09-20T12:07:37.068Z",
+    "modified": "2025-09-20T12:12:20.725Z",
+    "creator": "משתמש נוכחי",
+    "namespace": "http://trustgraph.ai/ontologies/natural-world",
+    "imports": ["http://www.w3.org/2002/07/owl#"]
+  }
+}
+```
+
+**שדות:**
+- `name`: שם אנושי של האונטולוגיה
+- `description`: תיאור קצר של מטרת האונטולוגיה
+- `version`: מספר גרסה סמנטי
+- `created`: תאריך ושעה של יצירה בפורמט ISO 8601
+- `modified`: תאריך ושעה של העדכון האחרון בפורמט ISO 8601
+- `creator`: מזהה המשתמש/מערכת שיוצרת
+- `namespace`: URI בסיסי עבור אלמנטי האונטולוגיה
+- `imports`: מערך של URI של אונטולוגיות ייבוא
+
+#### 2. מחלקות
+
+מגדיר סוגי אובייקט ויחסים היררכיים:
+
+```json
+{
+  "classes": {
+    "animal": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#animal",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Animal", "lang": "en"}],
+      "rdfs:comment": "בעל חיים",
+      "rdfs:subClassOf": "lifeform"
+    },
+    "cat": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#cat",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Cat", "lang": "en"}],
+      "rdfs:comment": "חתול",
+      "rdfs:subClassOf": "animal"
+    },
+    "dog": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#dog",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Dog", "lang": "en"}],
+      "rdfs:comment": "כלב",
+      "rdfs:subClassOf": "animal",
+      "owl:disjointWith": ["cat"]
+    }
+  }
+}
+```
+
+#### 3. תכונות
+
+מגדיר יחסים בין מחלקות:
+
+```json
+{
+  "objectProperties": {},
+  "datatypeProperties": {
+    "number-of-legs": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
+      "type": "owl:DatatypeProperty",
+      "rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
+      "rdfs:comment": "ספירת הרגלי הבעל חיים",
+      "rdfs:range": "xsd:nonNegativeInteger",
+      "rdfs:domain": "animal"
+    }
+  }
+}
+```
+
+#### 4. קובץ JSON לדוגמה (סגנון)
+
+```json
+{
+  "metadata": {
+    "name": "אונטולוגיית בעלי חיים",
+    "version": "1.0",
+    "description": "אונטולוגיה המגדירה סוגי בעלי חיים",
+    "created": "2024-01-01T00:00:00Z",
+    "modified": "2024-01-01T00:00:00Z",
+    "creator": "המשתמש"
+  },
+  "classes": {
+    "בעל חיים": {
+      "uri": "http://example.com/animals#Animal",
+      "type": "owl:Class",
+      "rdfs:label": {
+        "value": "בעל חיים",
+        "lang": "en"
+      }
+    },
+    "חתול": {
+      "uri": "http://example.com/animals#Cat",
+      "type": "owl:Class",
+      "rdfs:label": {
+        "value": "חתול",
+        "lang": "en"
+      },
+      "rdfs:subClassOf": "בעל חיים"
+    },
+    "כלב": {
+      "uri": "http://example.com/animals#Dog",
+      "type": "owl:Class",
+      "rdfs:label": {
+        "value": "כלב",
+        "lang": "en"
+      },
+      "rdfs:subClassOf": "בעל חיים",
+      "owl:disjointWith": [
+        "חתול"
+      ]
+    }
+  },
+  "properties": {
+    "hasBody": {
+      "type": "owl:ObjectProperty",
+      "domain": "בעל חיים",
+      "range": "http://example.com/things#Body"
+    }
+  }
+}
+```
+
+## כללי אימות
+
+### אימות מבני
+
+1. **עקביות URI:** כל ה-URI צריכים להיות בפורמט `{namespace}#{identifier}`
+2. **היררכיית מחלקות:** אין ירושה מעגלית ב-`rdfs:subClassOf`
+3. **תחומים/טווח תכונות:** צריכים להתייחס למחלקות קיימות או לסוגי XSD תקינים
+4. **מחלקות חופפות:** לא יכולות להיות תחת מחלקות אחרות
+5. **תכונות דו-כיוניות:** אם מצוינות, חייבות להיות דו-כיוניות
+
+### אימות סמנטי
+
+1. **מזהים ייחודיים:** מזהי מחלקות ותכונות צריכים להיות ייחודיים באונטולוגיה
+2. **תוויות שפה:** צריכות להיות בפורמט BCP 47
+3. **מגבלות כמותיות:** `minCardinality` ≤ `maxCardinality` כאשר שניהם מצוינים
+4. **תכונות פונקציונליות:** לא צריכות להכיל `maxCardinality` > 1
+
+## תמיכה בפורמט ייבוא/ייצוא
+
+למרות שהפורמט הפנימי הוא JSON, המערכת תומכת בהמרה בין פורמטים סטנדרטיים של אונטולוגיות:
+
+- **Turtle (.ttl)** - פורמט RDF קומפקטי
+- **RDF/XML (.rdf, .owl)** - פורמט W3C סטנדרטי
+- **OWL/XML (.owx)** - פורמט OWL ספציפי ל-XML
+- **JSON-LD (.jsonld)** - JSON עבור נתונים מקושרים

docs/tech-specs/ontology.ru.md

@@ -0,0 +1,152 @@
+# Структура Онтологии: Техническая Спецификация
+
+## Обзор
+
+Эта спецификация описывает структуру и формат онтологий в системе TrustGraph. Онтологии предоставляют формальные модели знаний, определяя классы, свойства и отношения, обеспечивая возможности для рассуждения и вывода. Система использует формат конфигурации, вдохновленный OWL, который широко представляет концепции OWL/RDFS, оптимизированный для требований TrustGraph.
+
+**Конвенция именования**: Для всех идентификаторов (ключей конфигурации, конечных точек API, названий модулей и т.д.) используется формат kebab-case, а не snake_case.
+
+## Цели
+
+- **Управление классами и свойствами**: Определение классов, похожих на OWL, с свойствами, доменами, диапазонами и ограничениями типов.
+- **Поддержка богатых семантических возможностей**: Обеспечение полных возможностей RDFS/OWL, включая метки, поддержку нескольких языков и формальные ограничения.
+- **Поддержка нескольких онтологий**: Разрешение одновременного существования и взаимодействия нескольких онтологий.
+- **Валидация и рассуждение**: Обеспечение соответствия онтологий стандартам, похожим на OWL, с проверкой согласованности и поддержкой вывода.
+- **Совместимость со стандартами**: Поддержка импорта/экспорта в стандартных форматах (Turtle, RDF/XML, OWL/XML), сохраняя оптимизацию.
+
+## Предыстория
+
+TrustGraph хранит онтологии как элементы конфигурации в гибкой системе ключ-значение. Хотя формат вдохновлен OWL (Web Ontology Language), он оптимизирован для конкретных случаев использования TrustGraph и не строго соответствует всем спецификациям OWL.
+
+Онтологии в TrustGraph обеспечивают:
+- Определение формальных типов объектов и их свойств.
+- Спецификацию доменов, диапазонов и ограничений типов свойств.
+- Логическое рассуждение и вывод.
+- Сложные отношения и ограничения кардинальности.
+- Поддержку нескольких языков для международного использования.
+
+## Структура Онтологии
+
+### Хранение конфигурации
+
+Онтологии хранятся как элементы конфигурации с следующим шаблоном:
+- **Тип**: `ontology`
+- **Ключ**: Уникальный идентификатор онтологии (например, `natural-world`, `domain-model`)
+- **Значение**: Полная онтология в формате JSON
+
+### JSON структура
+
+Формат JSON для онтологии состоит из четырех основных разделов:
+
+#### 1. Метаданные
+
+Содержит административную и описательную информацию об онтологии:
+
+```json
+{
+  "metadata": {
+    "name": "The natural world",
+    "description": "Ontology covering the natural order",
+    "version": "1.0.0",
+    "created": "2025-09-20T12:07:37.068Z",
+    "modified": "2025-09-20T12:12:20.725Z",
+    "creator": "current-user",
+    "namespace": "http://trustgraph.ai/ontologies/natural-world",
+    "imports": ["http://www.w3.org/2002/07/owl#"]
+  }
+}
+```
+
+**Поля:**
+- `name`: Человекочитаемое имя онтологии
+- `description`: Краткое описание цели онтологии
+- `version`: Семантическая версия
+- `created`: Дата создания в формате ISO 8601
+- `modified`: Дата последнего изменения в формате ISO 8601
+- `creator`: Идентификатор пользователя/системы, создавшей онтологию
+- `namespace`: Базовый URI для элементов онтологии
+- `imports`: Массив URI импортируемых онтологий
+
+#### 2. Классы
+
+Определяет типы объектов и их иерархические отношения:
+
+```json
+{
+  "classes": {
+    "animal": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#animal",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Animal", "lang": "en"}],
+      "rdfs:comment": "An animal",
+      "rdfs:subClassOf": "lifeform",
+      "owl:equivalentClass": ["creature"],
+      "owl:disjointWith": ["plant"],
+      "dcterms:identifier": "ANI-001"
+    }
+  }
+}
+```
+
+**Поддерживаемые свойства:**
+- `uri`: Полный URI класса
+- `type`: Всегда `"owl:Class"`
+- `rdfs:label`: Массив меток с указанием языка
+- `rdfs:comment`: Описание класса
+- `rdfs:subClassOf`: Идентификатор родительского класса (наследование)
+- `owl:equivalentClass`: Массив идентификаторов эквивалентных классов
+- `owl:disjointWith`: Массив идентификаторов классов, отличных друг от друга
+- `dcterms:identifier`: Опциональный внешний идентификатор
+
+#### 3. Объектные свойства
+
+Свойства, связывающие экземпляры между собой:
+
+```json
+{
+  "objectProperties": {}
+}
+```
+
+#### 4. Свойства данных
+
+```json
+{
+  "datatypeProperties": {
+    "number-of-legs": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
+      "type": "owl:DatatypeProperty",
+      "rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
+      "rdfs:comment": "Count of number of legs of the animal",
+      "rdfs:range": "xsd:nonNegativeInteger",
+      "rdfs:domain": "animal"
+    }
+  }
+}
+```
+
+## Правила валидации
+
+### Структурная валидация
+
+1. **Уникальность URI**: Все URI должны соответствовать формату `{namespace}#{identifier}`
+2. **Иерархия классов**: Не должно быть циклической иерархии в `rdfs:subClassOf`
+3. **Области/Диапазоны свойств**: Должны ссылаться на существующие классы или допустимые типы XSD
+4. **Отличные классы**: Не могут быть подклассами друг друга
+5. **Обратные свойства**: Должны быть двусторонними, если указаны
+
+### Семантическая валидация
+
+1. **Уникальные идентификаторы**: Идентификаторы классов и свойств должны быть уникальными в онтологии
+2. **Языковые теги**: Должны соответствовать формату BCP 47
+3. **Ограничения кардинальности**: `minCardinality` ≤ `maxCardinality` при указании обоих
+4. **Функциональные свойства**: Не должны иметь `maxCardinality` > 1
+
+## Поддержка импорта/экспорта
+
+Хотя внутренний формат - JSON, система поддерживает преобразование в/из стандартных форматов онтологий:
+
+- **Turtle (.ttl)** - компактная RDF-сериализация
+- **RDF/XML (.rdf, .owl)** - стандартный формат W3C
+- **OWL/XML (.owx)** - XML-формат OWL
+- **JSON-LD (.jsonld)** - JSON для Linked Data

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

@@ -0,0 +1,233 @@
+# 本体结构技术规范
+
+## 概述
+
+本规范描述了 TrustGraph 系统中本体的结构和格式。 本体提供正式的知识模型，定义类、属性、以及它们之间的关系，从而支持推理和推断功能。 该系统采用基于 OWL 的配置格式，广泛地表示 OWL/RDFS 概念，同时针对 TrustGraph 的特定需求进行了优化。
+
+**命名约定**: 该项目使用 kebab-case 格式（例如，`natural-world`、`domain-model`、`configuration keys`、`API endpoints`、`module names` 等）来表示所有标识符，而不是 snake_case。
+
+## 目标
+
+- **类和属性管理**: 定义类似 OWL 的类，并包含属性、域、范围以及类型约束
+- **强大的语义支持**: 启用全面的 RDFS/OWL 属性，包括标签、多语言支持以及正式约束
+- **多本体支持**: 允许多个本体共存并相互协作
+- **验证和推理**: 确保本体符合 OWL 类似的标准，包括一致性检查和推理支持
+- **标准兼容性**: 支持以标准格式（Turtle、RDF/XML、OWL/XML）进行导入/导出，同时保持内部优化
+
+## 背景
+
+TrustGraph 将本体存储为配置项，采用灵活的键值系统。 尽管该格式受到 OWL (Web Ontology Language) 的启发，但它针对 TrustGraph 的特定用例进行了优化，并且并非完全符合所有 OWL 规范。
+
+在 TrustGraph 中，本体能够实现以下功能：
+
+- 定义对象类型及其属性
+- 规范属性的域、范围和类型约束
+- 进行逻辑推理
+- 定义复杂的关系和数量约束
+- 支持多种语言，用于国际化
+
+## 本体结构
+
+### 配置存储
+
+本体以配置项的形式存储，具有以下模式：
+
+- **类型**: `ontology`
+- **键**: 唯一本体标识符（例如，`natural-world`、`domain-model`）
+- **值**: 完整的本体，采用 JSON 格式
+
+### JSON 结构
+
+本体的 JSON 格式主要包含四个部分：
+
+#### 1. 元数据
+
+包含本体的行政和描述性信息：
+
+```json
+{
+  "metadata": {
+    "name": "The natural world",
+    "description": "Ontology covering the natural order",
+    "version": "1.0.0",
+    "created": "2025-09-20T12:07:37.068Z",
+    "modified": "2025-09-20T12:12:20.725Z",
+    "creator": "current-user",
+    "namespace": "http://trustgraph.ai/ontologies/natural-world",
+    "imports": ["http://www.w3.org/2002/07/owl#"]
+  }
+}
+```
+
+**字段**:
+- `name`: 本体的人类可读名称
+- `description`: 本体目的的简要描述
+- `version`: 语义版本号
+- `created`: 创建时间 (ISO 8601 格式)
+- `modified`: 最后修改时间 (ISO 8601 格式)
+- `creator`: 创建用户的/系统的标识符
+- `namespace`: 本体元素的基 URI
+- `imports`: 导入本体 URI 数组
+
+#### 2. 类
+
+定义对象类型及其层次关系：
+
+```json
+{
+  "classes": {
+    "animal": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#animal",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Animal", "lang": "en"}],
+      "rdfs:comment": "An animal",
+      "rdfs:subClassOf": "lifeform",
+      "owl:equivalentClass": ["creature"],
+      "owl:disjointWith": ["plant"],
+      "dcterms:identifier": "ANI-001"
+    }
+  }
+}
+```
+
+**支持的属性**:
+- `uri`: 类的完整 URI
+- `type`: 始终为 `"owl:Class"`
+- `rdfs:label`: 语言标记的标签数组
+- `rdfs:comment`: 类的描述
+- `rdfs:subClassOf`: 上级类的标识符 (单继承)
+- `owl:equivalentClass`: 等效类的标识符数组
+- `owl:disjointWith`: 互斥类的标识符数组
+- `dcterms:identifier`: 外部参考标识符 (可选)
+
+#### 3. 对象属性
+
+用于链接实例的对象属性：
+
+```json
+{
+  "objectProperties": {
+    "has-parent": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#has-parent",
+      "type": "owl:ObjectProperty",
+      "rdfs:label": [{"value": "has parent", "lang": "en"}],
+      "rdfs:comment": "Links an animal to its parent",
+      "rdfs:domain": "animal",
+      "rdfs:range": "animal",
+      "owl:inverseOf": "parent-of",
+      "owl:functionalProperty": false
+    }
+  }
+}
+```
+
+**支持的属性**:
+- `uri`: 属性的完整 URI
+- `type`: 始终为 `"owl:ObjectProperty"`
+- `rdfs:label`: 语言标记的标签数组
+- `rdfs:comment`: 属性的描述
+- `rdfs:domain`: 域的标识符
+- `rdfs:range`: 范围的标识符
+- `owl:inverseOf`: 互反属性的标识符
+- `owl:functionalProperty`: 功能属性的标识符 (可选)
+
+#### 4. 数据类型属性
+
+```json
+{
+  "datatypeProperties": {
+    "number-of-legs": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
+      "type": "owl:DatatypeProperty",
+      "rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
+      "rdfs:comment": "Count of number of legs of the animal",
+      "rdfs:range": "xsd:nonNegativeInteger",
+      "rdfs:domain": "animal"
+    }
+  }
+}
+```
+
+#### 5. 示例本体
+
+```json
+{
+  "metadata": {
+    "name": "The natural world",
+    "description": "Ontology covering the natural order",
+    "version": "1.0.0",
+    "created": "2025-09-20T12:07:37.068Z",
+    "modified": "2025-09-20T12:12:20.725Z",
+    "creator": "current-user",
+    "namespace": "http://trustgraph.ai/ontologies/natural-world",
+    "imports": ["http://www.w3.org/2002/07/owl#"]
+  },
+  "classes": {
+    "animal": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#animal",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Animal", "lang": "en"}],
+      "rdfs:comment": "An animal"
+    },
+    "cat": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#cat",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Cat", "lang": "en"}],
+      "rdfs:comment": "A cat",
+      "rdfs:subClassOf": "animal"
+    },
+    "dog": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#dog",
+      "type": "owl:Class",
+      "rdfs:label": [{"value": "Dog", "lang": "en"}],
+      "rdfs:comment": "A dog",
+      "rdfs:subClassOf": "animal",
+      "owl:disjointWith": ["cat"]
+    }
+  },
+  "objectProperties": {},
+  "datatypeProperties": {
+    "number-of-legs": {
+      "uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
+      "type": "owl:DatatypeProperty",
+      "rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
+      "rdfs:comment": "Count of number of legs of the animal",
+      "rdfs:range": "xsd:nonNegativeInteger",
+      "rdfs:domain": "animal"
+    }
+  }
+}
+```
+
+## 验证规则
+
+### 结构验证
+
+1. **URI 约束**: 所有 URI 必须遵循模式 `{namespace}#{identifier}`
+2. **类层次**: 避免在 `rdfs:subClassOf` 中出现循环继承
+3. **属性域/范围**: 必须引用现有类或有效的 XSD 类型
+4. **互斥类**: 互斥类不能是互斥类的子类
+5. **互反属性**: 如果指定，必须是双向的
+
+### 语义验证
+
+1. **唯一标识符**: 类的标识符和属性标识符必须是唯一的
+2. **语言标签**: 必须符合 BCP 47 语言标签格式
+3. **数量约束**: `minCardinality` ≤ `maxCardinality`，当两者都指定时
+4. **功能属性**: 不能有 `maxCardinality` > 1
+
+## 导入/导出格式支持
+
+虽然内部格式为 JSON，但该系统支持与标准本体格式的转换：
+
+- **Turtle (.ttl)** - 紧凑的 RDF 序列化
+- **RDF/XML (.rdf, .owl)** - W3C 标准格式
+- **OWL/XML (.owx)** - OWL 特定 XML 格式
+- **JSON-LD (.jsonld)** - 用于链接数据的 JSON
+
+## 参考文献
+
+- [OWL 2 Web Ontology Language](https://www.w3.org/TR/owl2-overview/)
+- [RDF Schema 1.1](https://www.w3.org/TR/rdf-schema/)
+- [XML Schema Datatypes](https://www.w3.org/TR/xmlschema-2/)
+- [BCP 47 Language Tags](https://tools.ietf.org/html/bcp47)

docs/tech-specs/query-time-explainability.es.md

@@ -0,0 +1,200 @@
+# Explicabilidad en Tiempo de Consulta
+
+## Estado
+
+Implementado
+
+## Descripción General
+
+Esta especificación describe cómo GraphRAG registra y comunica datos de explicabilidad durante la ejecución de consultas. El objetivo es una trazabilidad completa: desde la respuesta final, a través de los bordes seleccionados, hasta los documentos de origen.
+
+La explicabilidad en tiempo de consulta captura lo que hizo la tubería de GraphRAG durante el razonamiento. Se conecta con la trazabilidad de la extracción de tiempo, que registra de dónde provienen los hechos del grafo de conocimiento.
+
+## Terminología
+
+| Término | Definición |
+|---|---|
+| **Explicabilidad** | El registro de cómo se derivó un resultado |
+| **Sesión** | Una ejecución de consulta de GraphRAG |
+| **Selección de borde** | Selección de bordes relevantes basada en LLM, con razonamiento |
+| **Cadena de trazabilidad** | Ruta desde el borde → fragmento → página → documento |
+
+## Arquitectura
+
+### Flujo de Explicabilidad
+
+```
+Consulta de GraphRAG
+    │
+    ├─► Actividad de la Sesión
+    │       └─► Texto de la consulta, marca de tiempo
+    │
+    ├─► Entidad de Recuperación
+    │       └─► Todos los bordes recuperados del subgrafo
+    │
+    ├─► Entidad de Selección
+    │       └─► Bordes seleccionados con razonamiento del LLM
+    │           └─► Cada borde enlaza con la trazabilidad de extracción
+    │
+    └─► Entidad de Respuesta
+            └─► Referencia a la respuesta sintetizada (en el bibliotecario)
+```
+
+### Tubería de GraphRAG de Dos Etapas
+
+1. **Selección de borde:** El LLM selecciona bordes relevantes del subgrafo, proporcionando una justificación para cada uno
+2. **Síntesis:** El LLM genera la respuesta a partir de los bordes seleccionados
+
+Esta separación permite la explicabilidad: sabemos exactamente qué bordes contribuyeron.
+
+### Almacenamiento
+
+- Los triples de explicabilidad se almacenan en una colección configurable (por defecto: `explainability`)
+- Utiliza la ontología PROV-O para las relaciones de trazabilidad
+- Reificación RDF para referencias a bordes
+- El contenido de la respuesta se almacena en el servicio del bibliotecario (no en línea, demasiado grande)
+
+### Streaming en Tiempo Real
+
+Los eventos de explicabilidad se transmiten al cliente a medida que se ejecuta la consulta:
+
+1. Se crea la sesión → se emite un evento
+2. Se recuperan los bordes → se emite un evento
+3. Se seleccionan los bordes con razonamiento → se emite un evento
+4. Se sintetiza la respuesta → se emite un evento
+
+El cliente recibe `explain_id` y `explain_collection` para obtener los detalles completos.
+
+## Estructura de URI
+
+Todos los URI utilizan el espacio de nombres `urn:trustgraph:` con UUIDs:
+
+| Entidad | Patrón de URI |
+|---|---|
+| Sesión | `urn:trustgraph:session:{uuid}` |
+| Recuperación | `urn:trustgraph:prov:retrieval:{uuid}` |
+| Selección | `urn:trustgraph:prov:selection:{uuid}` |
+| Respuesta | `urn:trustgraph:prov:answer:{uuid}` |
+| Selección de borde | `urn:trustgraph:prov:edge:{uuid}:{index}` |
+
+## Modelo RDF (PROV-O)
+
+### Actividad de la Sesión
+
+```turtle
+<session-uri> a prov:Activity ;
+    rdfs:label "Sesión de consulta GraphRAG" ;
+    prov:startedAtTime "2024-01-15T10:30:00Z" ;
+    tg:query "¿Cuál fue la Guerra contra el Terrorismo?" .
+```
+
+### Entidad de Recuperación
+
+```turtle
+<retrieval-uri> a prov:Entity ;
+    rdfs:label "Bordes recuperados" ;
+    prov:wasGeneratedBy <session-uri> ;
+    tg:edgeCount 50 .
+```
+
+### Entidad de Selección
+
+```turtle
+<selection-uri> a prov:Entity ;
+    rdfs:label "Bordes seleccionados" ;
+    prov:wasDerivedFrom <retrieval-uri> ;
+    tg:selectedEdge <edge-sel-0> ;
+    tg:selectedEdge <edge-sel-1> .
+
+<edge-sel-0> tg:edge << <s> <p> <o> >> ;
+    tg:reasoning "Este borde establece la relación clave..." .
+```
+
+### Entidad de Respuesta
+
+```turtle
+<answer-uri> a prov:Entity ;
+    rdfs:label "Respuesta de GraphRAG" ;
+    prov:wasDerivedFrom <selection-uri> ;
+    tg:document <urn:trustgraph:answer:{uuid}> .
+```
+
+La `tg:document` hace referencia a la respuesta almacenada en el servicio del bibliotecario.
+
+## Constantes de Espacio de Nombres
+
+Definidas en `trustgraph-base/trustgraph/provenance/namespaces.py`:
+
+| Constante | URI |
+|---|---|
+| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
+| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
+| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
+| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
+| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
+| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
+| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
+
+## Esquema GraphRagResponse
+
+```python
+@dataclass
+class GraphRagResponse:
+    error: Error | None = None
+    response: str = ""
+    end_of_stream: bool = False
+    explain_id: str | None = None
+    explain_collection: str | None = None
+    message_type: str = ""  # "chunk" or "explain"
+    end_of_session: bool = False
+```
+
+### Tipos de Mensaje
+
+| message_type | Propósito |
+|---|---|
+| `chunk` | Texto de la respuesta (streaming o final) |
+| `explain` | Evento de explicabilidad con referencia IRI |
+
+### Ciclo de Vida de la Sesión
+
+1. Múltiples mensajes `explain` (sesión, recuperación, selección, respuesta)
+2. Múltiples mensajes `chunk` (respuesta en streaming)
+3. Final `chunk` con `end_of_session=True`
+
+## Formato de Selección de Bordes
+
+El LLM devuelve un JSONL con los bordes seleccionados:
+
+```jsonl
+{"id": "edge-hash-1", "reasoning": "Este borde muestra la relación clave..."}
+{"id": "edge-hash-2", "reasoning": "Proporciona evidencia de apoyo..."}
+```
+
+El `id` es un hash de `(labeled_s, labeled_p, labeled_o)` calculado por `edge_id()`.
+
+## Preservación de URI
+
+### El Problema
+
+GraphRAG muestra etiquetas legibles para el LLM, pero la explicabilidad necesita los URI originales para el rastreo de la trazabilidad.
+
+### Solución
+
+`get_labelgraph()` devuelve:
+- `labeled_edges`: Lista de `(label_s, label_p, label_o)` para el LLM
+- `uri_map`: Diccionario que mapea `edge_id(labels)` → `(uri_s, uri_p, uri_o)`
+
+Cuando se guarda la información de explicabilidad, se utilizan los URI de `uri_map`.
+
+## Rastreando la Trazabilidad
+
+### Desde el borde hasta la fuente
+
+Se pueden rastrear los bordes seleccionados de vuelta a la fuente:
+
+### Referencias
+
+- PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/
+- RDF-star: https://w3c.github.io/rdf-star/
+- Trazabilidad de tiempo de extracción: `docs/tech-specs/extraction-time-provenance.md`

docs/tech-specs/query-time-explainability.he.md

@@ -0,0 +1,179 @@
+## הסבר על יכולת הסבר בזמן שאילתה
+
+## סטטוס
+
+יישום
+
+## סקירה כללית
+
+מפרט זה מתאר כיצד GraphRAG מתעד ומעביר נתוני הסבר במהלך ביצוע שאילתה. המטרה היא מעקב מלא: מהתשובה הסופית בחזרה דרך הקצוות שנבחרו לתיקי המסמכים המקוריים.
+
+הסבר בזמן שאילתה לוכד מה שהצינור של GraphRAG עשה במהלך ההיגיון. הוא מתחבר להקשר של ביצוע שאילתה, אשר מתעד היכן העובדות בגרף הידע מקורות.
+
+## מונחים
+
+| מונח | הגדרה |
+|---|---|
+| **הסבר** | תיעוד של איך התוצאה הושגה |
+| **סשן** | ביצוע שאילתה בודד של GraphRAG |
+| **בחירת קצה** | בחירה מבוססת LLM של קצוות רלוונטיים עם היגיון |
+| **שרשרת הקשר** | נתיב מ-קצה → חתיכה → עמוד → מסמך |
+
+## ארכיטקטורה
+
+### זרימת הסבר
+
+```
+שאילת GraphRAG
+    │
+    ├─► פעילות סשן
+    │       └─► טקסט שאילתה, חותם זמן
+    │
+    ├─► ישות אחזור
+    │       └─► כל הקצוות שנשלפו מהסובגרף
+    │
+    ├─► ישות בחירה
+    │       └─► קצוות שנבחרו עם היגיון LLM
+    │           └─► כל קצה מקושר להקשר של הסרת מידע
+    │
+    └─► ישות תשובה
+            └─► הפניה לתשובה שנוצרה (בספריית הניהול)
+```
+
+### צינור GraphRAG בשני שלבים
+
+1. **בחירת קצה:** LLM בוחר קצוות רלוונטיים מהסובגרף, ומספק הסבר לכל אחד
+2. **סינתזה:** LLM מייצר תשובה מקצוות שנבחרו בלבד
+
+ההפרדה מאפשרת הסבר - אנחנו יודעים בדיוק אילו קצוות תרמו.
+
+### אחסון
+
+- טריפלי הסבר מאוחסנים בספרייה שניתן להגדיר (ברירת מחדל: `explainability`)
+- משתמש ב-אונטולוגיה של PROV-O ליחסי הקשר
+- ייצוג RDF-star עבור הפניות לקצוות
+- תוכן התשובה מאוחסן בשירות הספרייה (לא באופן ישיר - גדול מדי)
+
+### סטרימינג בזמן אמת
+
+אירועי הסבר זורמים ללקוח בזמן ביצוע השאילתה:
+
+1. סשן נוצר → הודעה נשלחת
+2. קצוות נשלפים → הודעה נשלחת
+3. קצוות נבחרו עם הסבר → הודעה נשלחת
+4. תשובה נוצרה → הודעה נשלחת
+
+הלקוח מקבל `explain_id` ו-`explain_collection` כדי לשלוף פרטים מלאים.
+
+## מבנה URI
+
+כל ה-URIs משתמשים בשם מרחב שמות `urn:trustgraph:`, עם UUIDs:
+
+| ישות | תבנית URI |
+|---|---|
+| סשן | `urn:trustgraph:session:{uuid}` |
+| אחזור | `urn:trustgraph:prov:retrieval:{uuid}` |
+| בחירה | `urn:trustgraph:prov:selection:{uuid}` |
+| תשובה | `urn:trustgraph:prov:answer:{uuid}` |
+| בחירת קצה | `urn:trustgraph:prov:edge:{uuid}:{index}` |
+
+## מודל RDF (PROV-O)
+
+### פעילות סשן
+
+```turtle
+<session-uri> a prov:Activity ;
+    rdfs:label "שאילת GraphRAG" ;
+    prov:startedAtTime "2024-01-15T10:30:00Z" ;
+    tg:query "מה היה מלחמת הטרור?" .
+```
+
+### ישות אחזור
+
+```turtle
+<retrieval-uri> a prov:Entity ;
+    rdfs:label "קצוות שאובים" ;
+    prov:wasGeneratedBy <session-uri> ;
+    tg:edgeCount 50 .
+```
+
+### ישות בחירה
+
+```turtle
+<selection-uri> a prov:Entity ;
+    rdfs:label "קצוות שנבחרו" ;
+    prov:wasDerivedFrom <retrieval-uri> ;
+    tg:selectedEdge <edge-sel-0> ;
+    tg:selectedEdge <edge-sel-1> .
+
+<edge-sel-0> tg:edge << <s> <p> <o> >> ;
+    tg:reasoning "קצה זה מייצג את הקשר המרכזי..." .
+```
+
+### ישות תשובה
+
+```turtle
+<answer-uri> a prov:Entity ;
+    rdfs:label "תשובת GraphRAG" ;
+    prov:wasDerivedFrom <selection-uri> ;
+    tg:document <urn:trustgraph:answer:{uuid}> .
+```
+
+הפניה `tg:document` מתייחסת לתשובה המאוחסנת בשירות הספרייה.
+
+## קבועי מרחב שמות
+
+מוגדרים ב-`trustgraph-base/trustgraph/provenance/namespaces.py`:
+
+| קבוע | URI |
+|---|---|
+| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
+| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
+| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
+| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
+| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
+| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
+| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
+
+## תרשים GraphRagResponse
+
+```python
+@dataclass
+class GraphRagResponse:
+    error: Error | None = None
+    response: str = ""
+    end_of_stream: bool = False
+    explain_id: str | None = None
+    explain_collection: str | None = None
+    message_type: str = ""  # "chunk" or "explain"
+    end_of_session: bool = False
+```
+
+### סוגי הודעות
+
+| message_type | מטרת |
+|---|---|
+| `chunk` | טקסט תגובה (זרם או סופי) |
+| `explain` | אירוע הסבר עם הפניה IRI |
+
+### מחזור חיים של סשן
+
+1. מספר הודעות `explain` (סשן, אחזור, בחירה, תשובה)
+2. מספר הודעות `chunk` (טקסט זרם)
+3. הודעת `chunk` סופית עם `end_of_session=True`
+
+## פורמט בחירת קצה
+
+LLM מחזיר JSONL עם הקצוות שנבחרו:
+
+```jsonl
+{"id": "edge-hash-1", "reasoning": "קצה זה מראה את הקשר המרכזי..."}
+{"id": "edge-hash-2", "reasoning": "מספק ראיות תומכות..."}
+```
+
+ה-`id` הוא פאש של `(labeled_s, labeled_p, labeled_o)`
+ה-`reasoning` הוא הסבר של ה-LLM.
+
+## יישומים
+
+- `docs/tech-specs/extraction-time-provenance.md`

docs/tech-specs/query-time-explainability.zh-cn.md

@@ -0,0 +1,225 @@
+# 查询时可解释性
+
+## 状态
+
+已实现
+
+## 概述
+
+本规范描述了 GraphRAG 如何记录和在查询执行期间传递可解释性数据。目标是实现完全的可追溯性：从最终答案，再到选择的边，最后到源文档。
+
+查询时可解释性捕获了 GraphRAG 管道在推理过程中的行为。它与提取时的来源信息相关联，该信息记录了知识图谱事实的来源。
+
+## 术语
+
+| 术语 | 定义 |
+|---|---|
+| **可解释性** | 结果的推导方式 |
+| **会话** | 单个 GraphRAG 查询执行 |
+| **边选择** | 使用 LLM 进行相关边的选择，并提供推理 |
+| **来源链** | 从边 → 块 → 页面 → 文档 |
+
+## 架构
+
+### 可解释性流程
+
+```
+GraphRAG 查询
+    │
+    ├─► 会话活动
+    │       └─► 查询文本，时间戳
+    │
+    ├─► 检索实体
+    │       └─► 从子图检索的所有边
+    │
+    ├─► 选择实体
+    │       └─► 使用 LLM 推理选择的边
+    │           └─► 每条边都与提取来源关联
+    │
+    └─► 答案实体
+            └─► 指向合成响应 (在库员中)
+```
+
+### 两阶段 GraphRAG 管道
+
+1. **边选择**：LLM 从子图中选择相关的边，并提供每个边的推理
+2. **合成**：LLM 从选择的边生成答案
+
+这种分离实现了可解释性：我们知道哪些边贡献了结果。
+
+### 存储
+
+- 可解释性三元组存储在可配置的集合中 (默认：`explainability`)
+- 使用 PROV-O 语义网进行来源关系
+- 使用 RDF-star 重新表达进行边引用
+- 答案内容存储在库员服务中 (不在内联位置 - 过于庞大)
+
+### 实时流
+
+可解释性事件在查询执行时流式传输到客户端：
+
+1. 创建会话 → 发出事件
+2. 检索边 → 发出事件
+3. 使用推理选择边 → 发出事件
+4. 答案合成 → 发出事件
+
+客户端接收 `explain_id` 和 `explain_collection` 以获取完整详细信息。
+
+## URI 结构
+
+所有 URI 使用 `urn:trustgraph:` 命名空间和 UUID：
+
+| 实体 | URI 模式 |
+|---|---|
+| 会话 | `urn:trustgraph:session:{uuid}` |
+| 检索 | `urn:trustgraph:prov:retrieval:{uuid}` |
+| 选择 | `urn:trustgraph:prov:selection:{uuid}` |
+| 答案 | `urn:trustgraph:prov:answer:{uuid}` |
+| 边选择 | `urn:trustgraph:prov:edge:{uuid}:{index}` |
+
+## RDF 模型 (PROV-O)
+
+### 会话活动
+
+```turtle
+<session-uri> a prov:Activity ;
+    rdfs:label "GraphRAG 查询会话" ;
+    prov:startedAtTime "2024-01-15T10:30:00Z" ;
+    tg:query "What was the War on Terror?" .
+```
+
+### 检索实体
+
+```turtle
+<retrieval-uri> a prov:Entity ;
+    rdfs:label "检索的边" ;
+    prov:wasGeneratedBy <session-uri> ;
+    tg:edgeCount 50 .
+```
+
+### 选择实体
+
+```turtle
+<selection-uri> a prov:Entity ;
+    rdfs:label "选择的边" ;
+    prov:wasDerivedFrom <retrieval-uri> ;
+    tg:selectedEdge <edge-sel-0> ;
+    tg:selectedEdge <edge-sel-1> .
+
+<edge-sel-0> tg:edge << <s> <p> <o> >> ;
+    tg:reasoning "This edge establishes the key relationship..." .
+```
+
+### 答案实体
+
+```turtle
+<answer-uri> a prov:Entity ;
+    rdfs:label "GraphRAG 答案" ;
+    prov:wasDerivedFrom <selection-uri> ;
+    tg:document <urn:trustgraph:answer:{uuid}> .
+```
+
+`tg:document` 引用库员服务中存储的答案。
+
+## 名称空间常量
+
+定义在 `trustgraph-base/trustgraph/provenance/namespaces.py`：
+
+| 常量 | URI |
+|---|---|
+| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
+| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
+| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
+| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
+| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
+| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
+| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
+
+## GraphRagResponse 模式
+
+```python
+@dataclass
+class GraphRagResponse:
+    error: None | None = None
+    response: str = ""
+    end_of_stream: bool = False
+    explain_id: str | None = None
+    explain_collection: str | None = None
+    message_type: str = ""  # "chunk" 或 "explain"
+    end_of_session: bool = False
+```
+
+### 消息类型
+
+| message_type | 目的 |
+|---|---|
+| `chunk` | 响应文本 (流式或最终) |
+| `explain` | 可解释性事件，包含 IRI 引用 |
+
+### 会话生命周期
+
+1. 多个 `explain` 消息 (会话、检索、选择、答案)
+2. 多个 `chunk` 消息 (流式响应)
+3. 最终的 `chunk`，`end_of_session=True`
+
+## 边选择格式
+
+LLM 返回 JSONL 格式的边：
+
+```jsonl
+{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
+{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
+```
+
+`id` 是使用 `edge_id()` 计算的 `(labeled_s, labeled_p, labeled_o)` 的哈希值。
+
+## URI 保留
+
+### 问题
+
+GraphRAG 向 LLM 显示了人类可读的标签，但为了可追溯性，需要原始 URI。
+
+### 解决方案
+
+`get_labelgraph()` 返回：
+- `labeled_edges`: 包含 `(label_s, label_p, label_o)` 的列表，供 LLM 使用
+- `uri_map`: 将 `edge_id(labels)` 映射到 `(uri_s, uri_p, uri_o)` 的字典
+
+在存储可解释性数据时，使用 `uri_map` 中的 URI。
+
+## 来源追踪
+
+### 从边到源
+
+可以追踪选择的边：
+
+1. 查询包含的子图：`?subgraph tg:contains <<s p o>>`
+2. 遵循 `prov:wasDerivedFrom` 链，找到根文档
+3. 每个步骤中的链：块 → 页面 → 文档
+
+### 支持 Cassandra 引用
+
+Cassandra 查询服务支持引用：
+
+```python
+# 在 get_term_value() 中：
+elif term.type == TRIPLE:
+    return serialize_triple(term.triple)
+```
+
+这允许查询：
+```
+?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
+```
+
+## CLI 使用
+
+```bash
+tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
+```
+
+## 参考
+
+- PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/
+- RDF-star: https://w3c.github.io/rdf-star/
+- 提取时的来源信息: `docs/tech-specs/extraction-time-provenance.md`

docs/tech-specs/rag-streaming-support.ar.md

@@ -0,0 +1,166 @@
+# مواصفات فنية لدعم التدفق في RAG
+
+## نظرة عامة
+
+تصف هذه المواصفات إضافة دعم التدفق إلى خدمات GraphRAG و DocumentRAG، مما يمكّن من الحصول على استجابات على شكل أجزاء (token-by-token) في الوقت الفعلي للاستعلامات المتعلقة باسترجاع المعرفة ورؤوس المستندات. هذا يوسع البنية المعمارية الحالية للتدفق، والتي تم تنفيذها بالفعل لخدمات إكمال النص، والتعليمات البرمجية، ووكلاء LLM.
+
+## الأهداف
+
+- **تجربة تدفق متسقة**: توفير تجربة تدفق متسقة عبر جميع خدمات TrustGraph.
+- **تغييرات واجهة برمجة تطبيقات (API) قليلة**: إضافة دعم التدفق باستخدام علامة واحدة (`streaming`)، وفقًا للأنماط المتبعة.
+- **التوافق مع الإصدارات السابقة**: الحفاظ على سلوك غير تدفق بشكل افتراضي.
+- **استخدام البنية التحتية الحالية**: الاستفادة من تدفق PromptClient المطبق بالفعل.
+- **دعم البوابة**: تمكين التدفق من خلال بوابة websocket للتطبيقات العميلة.
+
+## الخلفية
+
+خدمات التدفق الحالية:
+- **خدمة إكمال النص للـ LLM**: المرحلة 1 - التدفق من مزودي LLM.
+- **خدمة التعليمات البرمجية**: المرحلة 2 - التدفق من خلال قوالب التعليمات البرمجية.
+- **خدمة الوكيل**: المراحل 3-4 - استجابات ReAct مع أجزاء فكرية/ملاحظات/إجابات متزايدة.
+
+قيود الحالية لخدمات RAG:
+- GraphRAG و DocumentRAG تدعم فقط الاستجابات المتوقفة.
+- يجب على المستخدمين الانتظار حتى استلام الرد الكامل من LLM قبل رؤية أي مخرجات.
+- تجربة مستخدم (UX) سيئة للاستجابات الطويلة من استعلامات الرسم البياني المعرفي أو المستندات.
+- تجربة غير متسقة مقارنة بـ خدمات TrustGraph الأخرى.
+
+تستجيب هذه المواصفات لهذه الثغرات من خلال إضافة دعم التدفق إلى GraphRAG و DocumentRAG. من خلال تمكين الاستجابات على شكل أجزاء، يمكن لـ TrustGraph:
+- توفير تجربة تدفق متسقة عبر جميع أنواع الاستعلام.
+- تقليل التأخير المتوقع في استعلامات RAG.
+- تمكين ملاحظات تقدم أفضل للاستعلامات الطويلة الأمد.
+- دعم العرض في الوقت الفعلي في تطبيقات العملاء.
+
+## التصميم الفني
+
+### البنية
+
+يستفيد تنفيذ التدفق في RAG من البنية التحتية الحالية:
+
+1.  **تدفق PromptClient** (مطبق بالفعل)
+    -   يستقبل `kg_prompt()` و `document_prompt()` بالفعل معلمات `streaming` و `chunk_callback`.
+    -   تستدعي هذه `prompt()` داخليًا مع دعم التدفق.
+    -   لا يلزم إجراء أي تغييرات على PromptClient.
+
+    الوحدة: `trustgraph-base/trustgraph/base/prompt_client.py`
+
+2.  **خدمة GraphRAG** (تحتاج إلى تمرير معلمة التدفق)
+    -   إضافة معلمة `streaming` إلى طريقة `query()`.
+    -   تمرير علامة التدفق والوظائف المرجعية إلى `prompt_client.kg_prompt()`.
+    -   يجب أن يحتوي مخطط GraphRag على حقل `streaming`.
+
+    الوحدات:
+    -   `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
+    -   `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (المعالجة)
+    -   `trustgraph-base/trustgraph/schema/graph_rag.py` (مخطط الطلب)
+    -   `trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (البوابة)
+
+3.  **خدمة DocumentRAG** (تحتاج إلى تمرير معلمة التدفق)
+    -   إضافة معلمة `streaming` إلى طريقة `query()`.
+    -   تمرير علامة التدفق والوظائف المرجعية إلى `prompt_client.document_prompt()`.
+    -   يجب أن يحتوي مخطط DocumentRag على حقل `streaming`.
+
+    الوحدات:
+    -   `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
+    -   `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (المعالجة)
+    -   `trustgraph-base/trustgraph/schema/document_rag.py` (مخطط الطلب)
+    -   `trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (البوابة)
+
+### تدفق البيانات
+
+**غير تدفق (الحالي)**:
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=False)
+                                   ↓
+                                Prompt Service → LLM
+                                   ↓
+                                رد كامل
+                                   ↓
+Client ← Gateway ← RAG Service ←  الرد
+```
+
+**تدفق (مقترح)**:
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
+                                   ↓
+                                Prompt Service → LLM (streaming)
+                                   ↓
+                                جزء → وظيفة مرجعية → رد RAG (جزء)
+                                   ↓                       ↓
+Client ← Gateway ← ────────────────────────────────── رد التدفق
+```
+
+### واجهات برمجة التطبيقات (APIs)
+
+**تغييرات GraphRAG**:
+
+1.  **GraphRag.query()** - إضافة معلمات التدفق
+```python
+async def query(
+    self, query, user, collection,
+    verbose=False, streaming=False, chunk_callback=None  # NEW
+):
+    # ... كود موجود ...
+
+    if streaming and chunk_callback:
+        resp = await self.prompt_client.kg_prompt(
+            query, kg,
+            streaming=True,
+            chunk_callback=chunk_callback
+        )
+    else:
+        resp = await self.prompt_client.kg_prompt(query, kg)
+
+    return resp
+```
+
+2.  **مخطط GraphRagRequest** - إضافة حقل التدفق
+```python
+class GraphRagRequest(Record):
+    query = String()
+    user = String()
+    collection = String()
+    streaming = Boolean()  # NEW
+```
+
+3.  **مخطط GraphRagResponse** - إضافة حقول التدفق (اتبع نمط الوكيل)
+```python
+class GraphRagResponse(Record):
+    response = String()
+    metadata = dict
+    # ... حقول أخرى ...
+```
+
+**تغييرات DocumentRAG**:
+(نفس التغييرات الموضحة أعلاه)
+
+### التغييرات في البوابة
+
+(نفس التغييرات الموضحة أعلاه)
+
+## خطة النقل
+
+لا توجد حاجة لنقل:
+- التدفق هو خيار، وتكون القيمة الافتراضية هي False.
+- لا تزال العملاء الحالية تعمل بشكل طبيعي.
+- يمكن للعملاء الجدد اختيار التدفق.
+
+## الجدول الزمني
+
+الوقت المقدر للتنفيذ: 4-6 ساعات
+- المرحلة 1 (2 ساعات): دعم التدفق في GraphRAG
+- المرحلة 2 (2 ساعات): دعم التدفق في DocumentRAG
+- المرحلة 3 (1-2 ساعات): تحديثات البوابة وعلامات سطر الأوامر (CLI)
+- الاختبار: تم تضمينه في كل مرحلة
+
+## الأسئلة المفتوحة
+
+- هل يجب إضافة دعم التدفق لخدمة NLP Query أيضًا؟
+- هل نريد تدفق خطوات وسيطة (مثل "جاري استرداد الكيانات..."، "استعلام عن الرسم البياني") أم فقط مخرجات LLM؟
+- هل يجب تضمين بيانات وصفية للجزء (مثل رقم الجزء، العدد الإجمالي المتوقع) في استجابات GraphRAG/DocumentRAG؟
+
+## المراجع
+
+- التنفيذ الحالي: `docs/tech-specs/streaming-llm-responses.md`
+- تدفق PromptClient: `trustgraph-base/trustgraph/base/prompt_client.py`
+- تدفق الوكيل: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`

docs/tech-specs/rag-streaming-support.es.md

@@ -0,0 +1,188 @@
+# Especificación Técnica de Soporte de Streaming para RAG
+
+## Visión general
+
+Esta especificación describe la adición de soporte de streaming a los servicios GraphRAG y DocumentRAG, permitiendo respuestas en tiempo real, token por token, para consultas de recuperación de conocimiento y documentos. Esto extiende la arquitectura de streaming existente, ya implementada para servicios de completado de texto, prompts y agentes de LLM.
+
+## Objetivos
+
+- **Experiencia de usuario consistente**: Proporcionar la misma experiencia de streaming en todos los servicios TrustGraph.
+- **Cambios mínimos en la API**: Añadir soporte de streaming con una única bandera `streaming`, siguiendo patrones establecidos.
+- **Compatibilidad hacia atrás**: Mantener el comportamiento no de streaming existente como predeterminado.
+- **Reutilizar la infraestructura existente**: Aprovechar el streaming ya implementado en PromptClient.
+- **Soporte de Gateway**: Permitir el streaming a través de un gateway websocket para aplicaciones cliente.
+
+## Antecedentes
+
+Servicios de streaming actualmente implementados:
+
+- **Servicio de completado de texto de LLM**: Fase 1 - Streaming desde proveedores de LLM.
+- **Servicio de prompts**: Fase 2 - Streaming a través de plantillas de prompts.
+- **Servicio de agente**: Fase 3-4 - Streaming de respuestas ReAct con fragmentos incrementales de "pensamiento/observación/respuesta".
+
+Limitaciones actuales para servicios RAG:
+
+- GraphRAG y DocumentRAG solo soportan respuestas de bloqueo.
+- Los usuarios deben esperar a que la respuesta completa del LLM antes de ver cualquier salida.
+- Mala experiencia de usuario para respuestas largas de consultas de conocimiento o documentos.
+- Experiencia inconsistente en comparación con otros servicios de TrustGraph.
+
+Esta especificación aborda estas limitaciones añadiendo soporte de streaming a GraphRAG y DocumentRAG. Al permitir respuestas token por token, TrustGraph puede:
+
+- Proporcionar una experiencia de usuario consistente de streaming para todos los tipos de consultas.
+- Reducir la latencia percibida para las consultas RAG.
+- Facilitar una mejor retroalimentación del progreso para las consultas de ejecución prolongada.
+- Soporte para visualización en tiempo real en aplicaciones cliente.
+
+## Diseño Técnico
+
+### Arquitectura
+
+La implementación de streaming de RAG aprovecha la infraestructura existente:
+
+1.  **Streaming de PromptClient** (Ya implementado)
+    -   `kg_prompt()` y `document_prompt()` ya aceptan los parámetros `streaming` y `chunk_callback`.
+    -   Estos llaman `prompt()` internamente con soporte de streaming.
+    -   No se necesitan cambios en PromptClient.
+    -   Módulo: `trustgraph-base/trustgraph/base/prompt_client.py`
+
+2.  **Servicio GraphRAG** (Necesita pasar el parámetro `streaming`)
+    -   Añadir el parámetro `streaming` al método `query()`.
+    -   Pasar la bandera de streaming y los callbacks a `prompt_client.kg_prompt()`.
+    -   El esquema GraphRagRequest debe incluir el campo `streaming`.
+    -   Módulos:
+        -   `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
+        -   `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (Procesador)
+        -   `trustgraph-base/trustgraph/schema/graph_rag.py` (Esquema de solicitud)
+        -   `trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (Gateway)
+
+3.  **Servicio DocumentRAG** (Necesita pasar el parámetro `streaming`)
+    -   Añadir el parámetro `streaming` al método `query()`.
+    -   Pasar la bandera de streaming y los callbacks a `prompt_client.document_prompt()`.
+    -   El esquema DocumentRagRequest debe incluir el campo `streaming`.
+    -   Módulos:
+        -   `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
+        -   `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (Procesador)
+        -   `trustgraph-base/trustgraph/schema/document_rag.py` (Esquema de solicitud)
+        -   `trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (Gateway)
+
+### Flujo de datos
+
+**No de streaming (actual)**:
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=False)
+                                   ↓
+                                Prompt Service → LLM
+                                   ↓
+                                Respuesta completa
+                                   ↓
+Client ← Gateway ← RAG Service ←  Respuesta
+```
+
+**Streaming (propuesto)**:
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
+                                   ↓
+                                Prompt Service → LLM (streaming)
+                                   ↓
+                                Fragmento → callback → Respuesta RAG (fragmento)
+                                   ↓                       ↓
+Client ← Gateway ← ────────────────────────────────── Flujo de respuesta
+```
+
+### APIs
+
+**Cambios en GraphRAG**:
+
+1.  **GraphRag.query()** - Añadir parámetros de streaming
+```python
+async def query(
+    self, query, user, collection,
+    verbose=False, streaming=False, chunk_callback=None  # NUEVO
+):
+    # ... código existente de recuperación de entidades/triples ...
+
+    if streaming and chunk_callback:
+        resp = await self.prompt_client.kg_prompt(
+            query, kg,
+            streaming=True,
+            chunk_callback=chunk_callback
+        )
+    else:
+        resp = await self.prompt_client.kg_prompt(query, kg)
+
+    return resp
+```
+
+2.  **Esquema GraphRagRequest** - Añadir campo de streaming
+```python
+class GraphRagRequest(Record):
+    query = String()
+    user = String()
+    collection = String()
+    streaming = Boolean()  # NUEVO
+```
+
+3.  **Esquema GraphRagResponse** - Añadir campos de streaming (seguir el patrón de Agent)
+```python
+class GraphRagResponse(Record):
+    response = String()    # LEGADO: respuesta completa
+    chunk = String()       # NUEVO: fragmento de streaming
+    end_of_stream = Boolean()  # NUEVO: indica el último fragmento
+```
+
+4.  **Procesador** - Pasar el streaming a través
+```python
+async def handle(self, msg):
+    # ... código existente ...
+
+    async def send_chunk(chunk):
+        await self.respond(GraphRagResponse(
+            chunk=chunk,
+            end_of_stream=False,
+            response=None
+        ))
+
+    if request.streaming:
+        resp = await self.prompt_client.kg_prompt(
+            request.query,
+            request.context,
+            streaming=True
+        )
+    else:
+        resp = await self.prompt_client.kg_prompt(
+            request.query,
+            request.context
+        )
+
+    # Procesar respuesta
+    # ...
+```
+
+### Plan de migración
+
+No se requiere migración:
+
+- El soporte de streaming es opcional a través del parámetro `streaming` (predeterminado a False).
+- Los clientes existentes siguen funcionando sin cambios.
+- Los nuevos clientes pueden optar por habilitar el streaming.
+
+## Cronograma
+
+Tiempo estimado de implementación: 4-6 horas.
+- Fase 1 (2 horas): Soporte de streaming para GraphRAG.
+- Fase 2 (2 horas): Soporte de streaming para DocumentRAG.
+- Fase 3 (1-2 horas): Actualizaciones del Gateway y banderas de la CLI.
+- Pruebas: Integradas en cada fase.
+
+## Preguntas abiertas
+
+- ¿Deberíamos añadir soporte de streaming al servicio NLP Query también?
+- ¿Queremos transmitir solo los pasos intermedios (por ejemplo, "Recuperando entidades...", "Consultando el gráfico...") o también la salida del LLM?
+- ¿Debería GraphRAG/DocumentRAG incluir metadatos del fragmento (por ejemplo, número de fragmento, número total esperado)?
+
+## Referencias
+
+- Implementación existente: `docs/tech-specs/streaming-llm-responses.md`
+- Streaming de PromptClient: `trustgraph-base/trustgraph/base/prompt_client.py`
+- Streaming de Agent: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`

docs/tech-specs/rag-streaming-support.he.md

@@ -0,0 +1,168 @@
+# תמיכה בסטרימינג של RAG - ספציפיציה טכנית
+
+## סקירה כללית
+
+מסמך זה מתאר את הוספת תמיכה בסטרימינג לשירותי GraphRAG ו-DocumentRAG, המאפשרות תגובות בזמן אמת, שוט אחר שוט, עבור שאילתות שליפה של גרפי ידע ומסמכים. זה מרחיב את הארכיטקטורה הסטנדרטית לסטרימינג, אשר כבר מיושמת עבור שירותי LLM להשלמת טקסט, בקשות וסוכנים.
+
+## מטרות
+
+- **חוויית משתמש סטנדרטית בסטרימינג**: לספק חוויית סטרימינג אחידה בכל שירותי TrustGraph.
+- **שינויים מינימליים בממשק API**: להוסיף תמיכה בסטרימינג באמצעות דגל `streaming` יחיד, תוך עמידה בדפוסי העבודה הקיימים.
+- **תאימות לאחור**: לשמור על התנהגות לא סטנדרטית קיימת כברירת מחדל.
+- **ניצול תשתית קיימת**: להשתמש בסטרימינג הקיים, אשר כבר מיושם עבור ה-PromptClient.
+- **תמיכה בדגלים**: לאפשר סטרימינג באמצעות דגל websocket עבור יישומי לקוח.
+
+## רקע
+
+שירותי סטרימינג קיימים:
+- **שירות השלמת טקסט של LLM**: שלב 1 - סטרימינג מספקי LLM
+- **שירות בקשות**: שלב 2 - סטרימינג באמצעות תבניות בקשות
+- **שירות סוכן**: שלבים 3-4 - סטרימינג של תגובות ReAct עם חלקים של מחשבה/תצפית/תשובה
+
+מגבלות נוכחיות לשירותי RAG:
+- GraphRAG ו-DocumentRAG תומכים רק בתגובות בלתי סטנדרטיות.
+- משתמשים צריכים לחכות לתגובה שלמה של LLM לפני קבלת כל תוצאה.
+- חוויית משתמש גרועה עבור תגובות ארוכות לשאילתות של גרפי ידע או מסמכים.
+- חוויה לא עקבית בהשוואה לשירותי TrustGraph אחרים.
+
+מסמך זה מטפל בבעיות אלו על ידי הוספת תמיכה בסטרימינג ל-GraphRAG ו-DocumentRAG. על ידי אפשרות תגובות שוט אחר שוט, TrustGraph יכול:
+- לספק חוויית משתמש סטנדרטית בסטרימינג עבור כל סוגי השאילתות.
+- להפחית את הפיגור הרגשי עבור שאילתות RAG.
+- לאפשר משוב מתקדם עבור שאילתות ארוכות.
+- לתמוך בהצגה בזמן אמת ביישומים של לקוח.
+
+## עיצוב טכני
+
+### ארכיטקטורה
+
+היישום הסטנדרטי של RAG של מנצל את התשתית הקיימת:
+
+1. **סטרימינג של PromptClient** (כבר מיושם)
+   - הפרמטרים `kg_prompt()` ו-`document_prompt()` כבר מקבלים את הפרמטרים `streaming` ו-`chunk_callback`.
+   - הפרמטרים אלו קוראים לפונקציה `prompt()` עם תמיכה בסטרימינג.
+   - אין צורך לשנות את ה-PromptClient.
+   - מודול: `trustgraph-base/trustgraph/base/prompt_client.py`
+
+2. **שירות GraphRAG** (דורש העברת פרמטר סטרימינג)
+   - להוסיף את הפרמטר `streaming` למתודה `query()`.
+   - להעביר את הדגל הסטרימינג ואת ה-callbacks ל-`prompt_client.kg_prompt()`.
+   - סכימת ה-GraphRagRequest צריכה לכלול את השדה `streaming`.
+   - מודולים:
+     - `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
+     - `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (Processor)
+     - `trustgraph-base/trustgraph/schema/graph_rag.py` (סכימת בקשה)
+     - `trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (Gateway)
+
+3. **שירות DocumentRAG** (דורש העברת פרמטר סטרימינג)
+   - להוסיף את הפרמטר `streaming` למתודה `query()`.
+   - להעביר את הדגל הסטרימינג ואת ה-callbacks ל-`prompt_client.document_prompt()`.
+   - סכימת ה-DocumentRagRequest צריכה לכלול את השדה `streaming`.
+   - מודולים:
+     - `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
+     - `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (Processor)
+     - `trustgraph-base/trustgraph/schema/document_rag.py` (סכימת בקשה)
+     - `trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (Gateway)
+
+### זרימת נתונים
+
+**לא סטנדרטי (נוכחי)**:
+```
+לקוח → דגל → שירות RAG → PromptClient.kg_prompt(streaming=False)
+                       ↓
+שירות בקשות → LLM
+                       ↓
+תגובה שלמה
+                       ↓
+לקוח ← דגל ← שירות RAG ← תגובה
+```
+
+**סטנדרטי (מוצע)**:
+```
+לקוח → דגל → שירות RAG → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
+                       ↓
+שירות בקשות → LLM (סטרימינג)
+                       ↓
+חלק → Callback → תגובת RAG (חלק)
+                       ↓                       ↓
+לקוח ← דגל ← ────────────────────────────────── זרם תגובה
+```
+
+### ממשקי API
+
+**שינויים ב-GraphRAG**:
+
+1. **GraphRag.query()** - הוספת פרמטרים סטרימינג
+```python
+async def query(
+    self, query, user, collection,
+    streaming=False, chunk_callback=None
+):
+    # ...
+```
+2. **שינויים ב-DocumentRAG**:
+   - כפי שמתואר עבור GraphRAG.
+
+### בדיקות
+
+**בדיקות יחידות**:
+- בדיקת GraphRag.query() עם `streaming=True/False`.
+- בדיקת DocumentRAG.query() עם `streaming=True/False`.
+- שימוש ב-Mock עבור PromptClient כדי לבדוק את קריאות ה-callbacks.
+
+**בדיקות אינטגרציה**:
+- בדיקת זרימת הסטרימינג המלאה של GraphRAG (בדיקות דומות לבדיקות סטרימינג של סוכן קיימות).
+- בדיקת זרימת הסטרימינג המלאה של DocumentRAG.
+- בדיקת העברת דגל ה-סטרימינג.
+- בדיקת הפלט של ה-CLI עם סטרימינג.
+
+**בדיקות ידניות**:
+- `tg-invoke-graph-rag -q "מהו למידת מכונה?"` (סטרימינג כברירת מחדל).
+- `tg-invoke-document-rag -q "סכם את המסמכים על AI"` (סטרימינג כברירת מחדל).
+- `tg-invoke-graph-rag --no-streaming -q "..."` (בדיקת מצב לא סטנדרטי).
+- בדיקה שהחלקים מופיעים בסטרימינג.
+
+## תכנון בדיקות
+
+**בדיקות יחידות**:
+- בדיקת GraphRag.query() עם `streaming=True/False`.
+- בדיקת DocumentRAG.query() עם `streaming=True/False`.
+- שימוש ב-Mock עבור PromptClient כדי לבדוק את קריאות ה-callbacks.
+
+**בדיקות אינטגרציה**:
+- בדיקת זרימת הסטרימינג המלאה של GraphRAG (בדיקות דומות לבדיקות סטרימינג של סוכן קיימות).
+- בדיקת זרימת הסטרימינג המלאה של DocumentRAG.
+- בדיקת העברת דגל ה-סטרימינג.
+- בדיקת הפלט של ה-CLI עם סטרימינג.
+
+**בדיקות ידניות**:
+- `tg-invoke-graph-rag -q "מהו למידת מכונה?"` (סטרימינג כברירת מחדל).
+- `tg-invoke-document-rag -q "סכם את המסמכים על AI"` (סטרימינג כברירת מחדל).
+- `tg-invoke-graph-rag --no-streaming -q "..."` (בדיקת מצב לא סטנדרטי).
+- בדיקה שהחלקים מופיעים בסטרימינג.
+
+## תכנון המיגרציה
+
+אין צורך במיגרציה:
+- הסטרימינג הוא "אופציונלי" באמצעות הפרמטר `streaming` (ברירת מחדל היא False).
+- לקוחות קיימים ממשיכים לעבוד ללא שינוי.
+- לקוחות חדשים יכולים לבחור בסטרימינג.
+
+## לוח זמנים
+
+הערכת זמן ליישום: 4-6 שעות
+- שלב 1 (2 שעות): תמיכה בסטרימינג של GraphRAG.
+- שלב 2 (2 שעות): תמיכה בסטרימינג של DocumentRAG.
+- שלב 3 (1-2 שעות): עדכוני דגל ו-CLI.
+- בדיקות: בונה לתוך כל שלב.
+
+## שאלות פתוחות
+
+- האם עלינו להוסיף תמיכה בסטרימינג לשירות ה-NLP Query גם כן?
+- האם עלינו להזרים גם את השלבים הביניים (לדוגמה, "שליפת ישויות...", "שאילתה על הגרף...") או רק את הפלט של ה-LLM?
+- האם עלינו לכלול מידע על החלקים בתגובות של RAG (לדוגמה, מספר החלק, מספר כולל צפוי)?
+
+## מקורות
+
+- יישום קיימת: `docs/tech-specs/streaming-llm-responses.md`
+- סטרימינג של PromptClient: `trustgraph-base/trustgraph/base/prompt_client.py`
+- סטרימינג של סוכן: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`

docs/tech-specs/rag-streaming-support.ru.md

@@ -0,0 +1,172 @@
+# Техническая спецификация поддержки потоковой передачи для RAG
+
+## Обзор
+
+Эта спецификация описывает добавление поддержки потоковой передачи для сервисов GraphRAG и DocumentRAG, позволяя получать ответы по частям (токен за токеном) для запросов из графа знаний и документов. Это расширяет существующую архитектуру потоковой передачи, уже реализованную для LLM-сервисов для завершения текста, запросов и агентов.
+
+## Цели
+
+- **Консистентный UX потоковой передачи**: Обеспечить одинаковый опыт потоковой передачи для всех сервисов TrustGraph.
+- **Минимальные изменения API**: Добавить поддержку потоковой передачи с помощью одного флага `streaming`, следуя установленным шаблонам.
+- **Совместимость со старыми версиями**: Поддерживать существующее поведение без потоковой передачи по умолчанию.
+- **Использование существующей инфраструктуры**: Использовать существующую функциональность потоковой передачи PromptClient.
+- **Поддержка Gateways**: Включить потоковую передачу через websocket Gateway для клиентских приложений.
+
+## Предыстория
+
+Текущие сервисы, поддерживающие потоковую передачу:
+- **Сервис завершения текста LLM**: Фаза 1 - потоковая передача от LLM-провайдеров.
+- **Сервис запросов**: Фаза 2 - потоковая передача через шаблоны запросов.
+- **Сервис агента**: Фазы 3-4 - потоковая передача ReAct с последовательными частями/данными/ответами.
+
+Текущие ограничения для сервисов RAG:
+- GraphRAG и DocumentRAG поддерживают только не потоковые ответы.
+- Пользователям необходимо ждать полного ответа LLM, прежде чем видеть какой-либо результат.
+- Плохой UX для длинных ответов из запросов к графу знаний или документам.
+- Несогласованный опыт по сравнению с другими сервисами TrustGraph.
+
+Эта спецификация решает эти проблемы, добавляя поддержку потоковой передачи для GraphRAG и DocumentRAG.  Благодаря потоковой передаче по частям, TrustGraph может:
+- Обеспечить консистентный UX потоковой передачи для всех типов запросов.
+- Снизить воспринимаемую задержку для запросов RAG.
+- Обеспечить лучший прогресс для длительных запросов.
+- Поддерживать отображение в реальном времени в клиентских приложениях.
+
+## Технический дизайн
+
+### Архитектура
+
+Реализация потоковой передачи для RAG использует существующую инфраструктуру:
+
+1. **PromptClient Streaming** (Уже реализовано)
+   - `kg_prompt()` и `document_prompt()` уже принимают параметры `streaming` и `chunk_callback`.
+   - Эти вызывают `prompt()` с поддержкой потоковой передачи.
+   - Изменения не требуются для PromptClient.
+
+   Модуль: `trustgraph-base/trustgraph/base/prompt_client.py`
+
+2. **Сервис GraphRAG** (Требуется передача параметра `streaming`)
+   - Добавить параметр `streaming` к методу `query()`.
+   - Передавать флаг `streaming` и обратные вызовы в `prompt_client.kg_prompt()`.
+   - Схема GraphRagRequest должна иметь поле `streaming`.
+
+   Модули:
+   - `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
+   - `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (Обработчик)
+   - `trustgraph-base/trustgraph/schema/graph_rag.py` (Схема запроса)
+   - `trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (Gateway)
+
+3. **Сервис DocumentRAG** (Требуется передача параметра `streaming`)
+   - Добавить параметр `streaming` к методу `query()`.
+   - Передавать флаг `streaming` и обратные вызовы в `prompt_client.document_prompt()`.
+   - Схема DocumentRagRequest должна иметь поле `streaming`.
+
+   Модули:
+   - `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
+   - `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (Обработчик)
+   - `trustgraph-base/trustgraph/schema/document_rag.py` (Схема запроса)
+   - `trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (Gateway)
+
+### Поток данных
+
+**Не потоковая передача (текущая)**:
+```
+Клиент → Gateway → Сервис RAG → PromptClient.kg_prompt(streaming=False)
+                                   ↓
+                                Сервис запросов → LLM
+                                   ↓
+                                Полный ответ
+                                   ↓
+Клиент ← Gateway ← Сервис RAG ←  Ответ
+```
+
+**Потоковая передача (предлагаемая)**:
+```
+Клиент → Gateway → Сервис RAG → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
+                                   ↓
+                                Сервис запросов → LLM (streaming)
+                                   ↓
+                                Часть → обратный вызов → Ответ RAG (часть)
+                                   ↓                       ↓
+Клиент ← Gateway ← ────────────────────────────────── Поток ответа
+```
+
+### API
+
+**Изменения для GraphRAG**:
+
+1. **GraphRag.query()** - Добавлены параметры потоковой передачи
+```python
+async def query(
+    self, query, user, collection,
+    verbose=False, streaming=False, chunk_callback=None  # NEW
+):
+    # ... существующая работа с сущностями/триплетами ...
+
+    if streaming and chunk_callback:
+        resp = await self.prompt_client.kg_prompt(
+            query, kg,
+            streaming=True,
+            chunk_callback=chunk_callback
+        )
+    else:
+        resp = await self.prompt_client.kg_prompt(query, kg)
+
+    return resp
+```
+
+2. **GraphRagRequest schema** - Добавлен параметр `streaming`
+```python
+class GraphRagRequest(Record):
+    query = String()
+    user = String()
+    collection = String()
+    streaming = Boolean()  # NEW
+```
+
+3. **GraphRagResponse schema** - Добавлены поля для потоковой передачи (следовать паттерну Agent)
+```python
+class GraphRagResponse(Record):
+    response = String()    # Legacy: полный ответ
+    chunk = String()       # NEW: часть для потоковой передачи
+    end_of_stream = Boolean()  # NEW: указывает, что это последняя часть
+```
+
+4. **Обработчик** - Передача потоковой передачи
+```python
+async def handle(self, ...):
+    # ... существующий код ...
+    response = await self.query(...)
+    if response and streaming:
+        # ... логика для отправки части
+    else:
+        # ... логика для отправки полного ответа
+```
+
+**Изменения для DocumentRAG**: Аналогично GraphRAG.
+
+## График миграции
+
+Не требуется миграция:
+- Поддержка потоковой передачи является опцией (по умолчанию отключена)
+- Существующие клиенты продолжают работать без изменений.
+- Новые клиенты могут включить поддержку потоковой передачи.
+
+## Сроки
+
+Оценка времени реализации: 4-6 часов
+- Фаза 1 (2 часа): Поддержка потоковой передачи для GraphRAG.
+- Фаза 2 (2 часа): Поддержка потоковой передачи для DocumentRAG.
+- Фаза 3 (1-2 часа): Обновления Gateway и флаги командной строки.
+- Тестирование: Встроено в каждую фазу.
+
+## Открытые вопросы
+
+- Должна ли также поддерживаться потоковая передача для сервиса NLP Query?
+- Хотим ли мы передавать только выход LLM (например, "Извлечь сущности...", "Запрос к графу...") или только его?
+- Должны ли ответы GraphRAG/DocumentRAG содержать метаданные части (например, номер части, общее количество)?
+
+## Ссылки
+
+- Существующая реализация: `docs/tech-specs/streaming-llm-responses.md`
+- Потоковая передача LLM: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`
+- Потоковая передача PromptClient: `trustgraph-base/trustgraph/base/prompt_client.py`

docs/tech-specs/rag-streaming-support.zh-cn.md

@@ -0,0 +1,191 @@
+# RAG 实时支持技术规范
+
+## 概述
+
+本规范描述了为 GraphRAG 和 DocumentRAG 服务添加实时支持的方法，从而实现知识图谱和文档检索查询的实时分块响应。 这扩展了现有的实时架构，该架构已针对 LLM 文本补全、提示和代理服务实施。
+
+## 目标
+
+- **一致的实时体验**: 在所有 TrustGraph 服务中提供相同的时间体验
+- **最小的 API 更改**: 通过单个 `streaming` 标志添加实时支持，遵循已建立的模式
+- **保持现有兼容性**: 保持现有非实时行为作为默认
+- **重用现有基础设施**: 利用 PromptClient 现有的实时功能
+- **网关支持**: 通过 websocket 网关为客户端应用程序启用实时
+
+## 背景
+
+当前已实现的实时服务：
+- **LLM 文本补全服务**: 第一阶段 - 从 LLM 提供商获取
+- **提示服务**: 第二阶段 - 通过提示模板进行流式传输
+- **代理服务**: 第三阶段 - 使用 ReAct 响应和分块的思考/观察/答案进行流式传输
+
+RAG 服务的当前限制：
+- GraphRAG 和 DocumentRAG 仅支持块响应
+- 用户必须等待 LLM 响应完成才能看到任何输出
+- 针对知识图谱或文档查询的较长响应给用户体验带来不便
+- 与其他 TrustGraph 服务相比，体验不一致
+
+本规范通过为 GraphRAG 和 DocumentRAG 添加实时支持来解决这些问题。 通过实现分块响应，TrustGraph 可以：
+- 在所有查询类型中提供一致的实时体验
+- 减少 RAG 查询的感知延迟
+- 允许长时间运行查询的更好进度反馈
+- 客户端应用程序支持实时显示
+
+## 技术设计
+
+### 架构
+
+RAG 实时实现利用了现有的基础设施：
+
+1. **PromptClient 实时** (已实现)
+   - `kg_prompt()` 和 `document_prompt()` 已经接受 `streaming` 和 `chunk_callback` 参数
+   - 这些调用 `prompt()` 内部，并启用实时功能
+   - PromptClient 不需要任何更改
+
+   模块： `trustgraph-base/trustgraph/base/prompt_client.py`
+
+2. **GraphRAG 服务** (需要传递实时参数)
+   - 将 `streaming` 参数添加到 `query()` 方法
+   - 将实时标志和回调函数传递给 `prompt_client.kg_prompt()`
+   - GraphRagRequest 模式需要包含 `streaming` 字段
+
+   模块：
+   - `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
+   - `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (处理器)
+   - `trustgraph-base/trustgraph/schema/graph_rag.py` (Request 模式)
+   - `trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (网关)
+
+3. **DocumentRAG 服务** (需要传递实时参数)
+   - 将 `streaming` 参数添加到 `query()` 方法
+   - 将实时标志和回调函数传递给 `prompt_client.document_prompt()`
+   - DocumentRagRequest 模式需要包含 `streaming` 字段
+
+   模块：
+   - `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
+   - `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (处理器)
+   - `trustgraph-base/trustgraph/schema/document_rag.py` (Request 模式)
+   - `trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (网关)
+
+### 数据流
+
+**非实时 (当前)**：
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=False)
+                                   ↓
+                                Prompt Service → LLM
+                                   ↓
+                                完整响应
+                                   ↓
+Client ← Gateway ← RAG Service ←  Response
+```
+
+**实时 (提案)**：
+```
+Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
+                                   ↓
+                                Prompt Service → LLM (streaming)
+                                   ↓
+                                块 → 回调 → RAG 响应 (块)
+                                   ↓                       ↓
+Client ← Gateway ← ────────────────────────────────── 响应流
+```
+
+### API
+
+**GraphRAG 更改**:
+
+1. **GraphRag.query()** - 添加实时参数
+```python
+async def query(
+    self, query, user, collection,
+    verbose=False, streaming=False, chunk_callback=None  # NEW
+):
+    # ... 现有实体/三元组检索 ...
+
+    if streaming and chunk_callback:
+        resp = await self.prompt_client.kg_prompt(
+            query, kg,
+            streaming=True,
+            chunk_callback=chunk_callback
+        )
+    else:
+        resp = await self.prompt_client.kg_prompt(query, kg)
+
+    return resp
+```
+
+2. **GraphRagRequest 模式** - 添加实时字段
+```python
+class GraphRagRequest(Record):
+    query = String()
+    user = String()
+    collection = String()
+    streaming = Boolean()  # NEW
+```
+
+3. **GraphRagResponse 模式** - 添加实时字段 (遵循 Agent 模式)
+```python
+class GraphRagResponse(Record):
+    response = String()    # Legacy: complete response
+    chunk = String()       # NEW: streaming chunk
+    end_of_stream = Boolean()  # NEW: indicates last chunk
+```
+
+4. **Processor** - 传递实时
+```python
+async def handle(self, msg):
+    # ... 现有代码 ...
+
+    async def send_chunk(chunk):
+        await self.respond(GraphRagResponse(
+            chunk=chunk,
+            end_of_stream=False,
+            response=None
+        ))
+
+    if request.streaming:
+        full_response = await self.rag.query(
+            query=request.query,
+            user=request.user,
+            collection=request.collection,
+            streaming=True,
+            chunk_callback=send_chunk
+        )
+        # 发送最终消息
+        await self.respond(GraphRagResponse(
+            chunk=None,
+            end_of_stream=True,
+            response=full_response
+        ))
+    else:
+        # 现有非实时路径
+        response = await self.rag.query(...)
+        await self.respond(GraphRagResponse(response=response))
+```
+
+**DocumentRAG 更改**:
+
+与 GraphRAG 相同模式：
+1. 将 `streaming` 和 `chunk_callback` 参数添加到 `DocumentRag.query()`
+2. 将 `streaming` 字段添加到 `DocumentRagRequest`
+3. 将 `streaming` 字段添加到 `DocumentRagResponse`
+
+### 时间线
+
+估计实现时间：4-6 小时
+- 第一阶段 (2 小时)： GraphRAG 实时支持
+- 第二阶段 (2 小时)： DocumentRAG 实时支持
+- 第三阶段 (1-2 小时)： 网关更新和 CLI 标志
+- 测试： 已包含在每个阶段
+
+## 开放问题
+
+- 是否应该为 NLP 查询服务添加实时支持？
+- 我们是否只想要实时输出中间步骤 (例如 "检索实体..."、"查询图...")，还是也想要实时输出？
+- GraphRAG/DocumentRAG 响应是否应该包含块元数据 (例如块编号、预期总数)？
+
+## 参考
+
+- 现有实现： `docs/tech-specs/streaming-llm-responses.md`
+- Agent 实时： `trustgraph-flow/trustgraph/agent/react/agent_manager.py`
+- PromptClient 实时： `trustgraph-base/trustgraph/base/prompt_client.py`

docs/tech-specs/schema-refactoring-proposal.ar.md

@@ -0,0 +1,91 @@
+# اقتراح إعادة هيكلة دليل المخطط
+
+## المشاكل الحالية
+
+1.  **هيكل مسطح** - وجود جميع المخططات في مجلد واحد يجعل من الصعب فهم العلاقات
+2.  **مزيج من المعايير** - أنواع أساسية، كائنات مجال، وعقود واجهة برمجة تطبيقات كلها مدمجة معًا
+3.  **أسماء غير واضحة** - الملفات مثل "object.py"، "types.py"، "topic.py" لا تشير بوضوح إلى الغرض منها
+4.  **لا يوجد تباين واضح** - من الصعب معرفة ما يعتمد على ماذا
+
+## الهيكل المقترح
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # أنواع أساسية أولية مستخدمة في كل مكان
+│   ├── __init__.py
+│   ├── primitives.py  # Error, Value, Triple, Field, RowSchema
+│   ├── metadata.py    # سجل البيانات الوصفية
+│   └── topic.py       # أدوات الموضوع
+│
+├── knowledge/         # نماذج مجال المعرفة واستخراجها
+│   ├── __init__.py
+│   ├── graph.py       # EntityContext, EntityEmbeddings, Triples
+│   ├── document.py    # Document, TextDocument, Chunk
+│   ├── knowledge.py   # أنواع استخراج المعرفة
+│   ├── embeddings.py  # جميع أنواع الاستعلامات المتعلقة بالاستعلام (تم نقلها من ملفات متعددة)
+│   └── nlp.py         # أنواع Definition, Topic, Relationship, Fact
+│
+└── services/          # عقود طلب/استجابة الخدمة
+    ├── __init__.py
+    ├── llm.py         # TextCompletion, Embeddings, Tool requests/responses
+    ├── retrieval.py   # GraphRAG, DocumentRAG queries/responses
+    ├── query.py       # GraphEmbeddingsRequest/Response, DocumentEmbeddingsRequest/Response
+    ├── agent.py       # Agent requests/responses
+    ├── flow.py        # Flow requests/responses
+    ├── prompt.py      # طلبات/استجابات خدمة Prompt
+    ├── config.py      # خدمة التكوين
+    ├── library.py     # خدمة المكتبة
+    └── lookup.py      # خدمة البحث
+```
+
+## التغييرات الرئيسية
+
+1.  **تنظيم هرمي** - فصل واضح بين الأنواع الأساسية، نماذج المعرفة، وعقود الخدمة
+2.  **أسماء أفضل**:
+    -   `types.py` → `core/primitives.py` (الغرض أكثر وضوحًا)
+    -   `object.py` → تقسيم بين الملفات المناسبة بناءً على المحتوى الفعلي
+    -   `documents.py` → `knowledge/document.py` (فردي، متسق)
+    -   `models.py` → `services/llm.py` (نوع النماذج أكثر وضوحًا)
+    -   `prompt.py` → تقسيم: أجزاء الخدمة إلى `services/prompt.py`، أنواع البيانات إلى `knowledge/nlp.py`
+
+3.  **تجميع منطقي**:
+    -   جميع أنواع الاستعلامات مجمعة في `knowledge/embeddings.py`
+    -   جميع العقود المتعلقة بالخدمة LLM في `services/llm.py`
+    -   فصل واضح لزوجات الطلب/الاستجابة في دليل الخدمة
+    -   تجميع أنواع استخراج المعرفة مع نماذج المعرفة الأخرى
+
+4.  **وضوح الاعتماد**:
+    -   الأنواع الأساسية ليس لها تبعيات
+    -   تعتمد نماذج المعرفة فقط على الأساس
+    -   يمكن أن تعتمد عقود الخدمة على كل من الأساس ونماذج المعرفة
+
+## فوائد الهجرة
+
+1.  **سهولة التنقل** - يمكن للمطورين العثور بسرعة على ما يحتاجون إليه
+2.  **تحسين الوحدات** - حدود واضحة بين مختلف المعايير
+3.  **استيراد أبسط** - مسارات استيراد أكثر بديهية
+4.  **قابلية التوسع** - من السهل إضافة أنواع معرف أو خدمات جديدة دون تضييق
+
+## أمثلة على تغييرات الاستيراد
+
+```python
+# قبل
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# بعد
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## ملاحظات التنفيذ
+
+1.  الحفاظ على التوافق مع الإصدارات السابقة عن طريق الحفاظ على الاستيرادات في `__init__.py` الجذر
+2.  نقل الملفات تدريجيًا، مع تحديث الاستيرادات حسب الحاجة
+3.  ضع في اعتبارك إضافة `legacy.py` الذي يستورد كل شيء لفاصل زمني الانتقال
+4.  تحديث الوثائق لتعكس الهيكل الجديد
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "Examination of the current schema directory structure", "status": "completed", "priority": "high"}, {"id": "2", "content": "Analyze schema files and their purposes", "status": "completed", "priority": "high"}, {"id": "3", "content": "Propose improved naming and structure", "status": "completed", "priority": "high"}]

docs/tech-specs/schema-refactoring-proposal.es.md

@@ -0,0 +1,91 @@
+# Propuesta de Refactorización del Directorio de Esquemas
+
+## Problemas Actuales
+
+1. **Estructura plana** - Tener todos los esquemas en un solo directorio dificulta la comprensión de las relaciones.
+2. **Preocupaciones mixtas** - Tipos centrales, objetos de dominio y contratos de API mezclados.
+3. **Nombres poco claros** - Archivos como "object.py", "types.py", "topic.py" no indican claramente su propósito.
+4. **Sin capa clara** - No es fácil ver qué depende de qué.
+
+## Estructura Propuesta
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # Tipos primitivos centrales utilizados en todas partes
+│   ├── __init__.py
+│   ├── primitives.py  # Error, Value, Triple, Field, RowSchema
+│   ├── metadata.py    # Registro de metadatos
+│   └── topic.py       # Utilitarios de tema
+│
+├── knowledge/         # Modelos del dominio de conocimiento y extracción
+│   ├── __init__.py
+│   ├── graph.py       # EntityContext, EntityEmbeddings, Triples
+│   ├── document.py    # Document, TextDocument, Chunk
+│   ├── knowledge.py   # Tipos de extracción de conocimiento
+│   ├── embeddings.py  # Todos los tipos relacionados con la incorporación (movidos de múltiples archivos)
+│   └── nlp.py         # Tipos de Definición, Tema, Relación, Hecho
+│
+└── services/          # Contratos de solicitud/respuesta de servicios
+    ├── __init__.py
+    ├── llm.py         # TextCompletion, Embeddings, Solicitudes/respuestas de Herramientas
+    ├── retrieval.py   # Consultas/respuestas de GraphRAG, DocumentRAG
+    ├── query.py       # Consultas/respuestas de GraphEmbeddingsRequest, DocumentEmbeddingsRequest
+    ├── agent.py       # Solicitudes/respuestas del agente
+    ├── flow.py        # Solicitudes/respuestas de flujo
+    ├── prompt.py      # Solicitudes/respuestas del servicio de prompt
+    ├── config.py      # Servicio de configuración
+    ├── library.py     # Servicio de bibliotecario
+    └── lookup.py      # Servicio de búsqueda
+```
+
+## Cambios Clave
+
+1. **Organización jerárquica** - Separación clara entre tipos centrales, modelos de conocimiento y contratos de servicio.
+2. **Nombres mejorados**:
+   - `types.py` → `core/primitives.py` (propósito más claro)
+   - `object.py` → Dividir entre archivos apropiados según el contenido real
+   - `documents.py` → `knowledge/document.py` (singular, consistente)
+   - `models.py` → `services/llm.py` (qué tipo de modelos)
+   - `prompt.py` → Dividir: partes del servicio a `services/prompt.py`, tipos de datos a `knowledge/nlp.py`
+
+3. **Agrupamiento lógico**:
+   - Todos los tipos de incorporación consolidados en `knowledge/embeddings.py`
+   - Todos los contratos de servicio relacionados con LLM en `services/llm.py`
+   - Separación clara de pares de solicitud/respuesta en el directorio de servicios
+   - Grupos de tipos de extracción de conocimiento con otros modelos de dominio de conocimiento
+
+4. **Claridad de dependencias**:
+   - Los tipos centrales no tienen dependencias
+   - Los modelos de conocimiento dependen solo de los centrales
+   - Los contratos de servicio pueden depender de los centrales y de los modelos de conocimiento
+
+## Beneficios de la Migración
+
+1. **Navegación más fácil** - Los desarrolladores pueden encontrar rápidamente lo que necesitan.
+2. **Mejor modularidad** - Límites claros entre diferentes preocupaciones.
+3. **Importaciones más simples** - Rutas de importación más intuitivas.
+4. **Futurizable** - Fácil de agregar nuevos tipos de conocimiento o servicios sin desorden.
+
+## Cambios de Importación de Ejemplo
+
+```python
+# Antes
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# Después
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## Notas de Implementación
+
+1. Mantener la compatibilidad hacia atrás manteniendo las importaciones en el `__init__.py` raíz.
+2. Mover los archivos gradualmente, actualizando las importaciones según sea necesario.
+3. Considerar agregar un `legacy.py` que importe todo para el período de transición.
+4. Actualizar la documentación para reflejar la nueva estructura.
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "Examinar la estructura actual del directorio de esquemas", "status": "completed", "priority": "high"}, {"id": "2", "content": "Analizar los archivos de esquema y sus propósitos", "status": "completed", "priority": "high"}, {"id": "3", "content": "Proponer una estructura y nombres mejorados", "status": "completed", "priority": "high"}]

docs/tech-specs/schema-refactoring-proposal.he.md

@@ -0,0 +1,91 @@
+# הצעה לשחזור תיקיית הסכימה
+
+## בעיות נוכחיות
+
+1. **מבנה שטוח** - כל הסכימות במקום אחד מקשות על הבנת הקשרים
+2. **שילוב דאגות** - סוגי ליבה, אובייקטים של תחום, וחוזים של API משולבים יחד
+3. **שמות לא ברורים** - קבצים כמו "object.py", "types.py", "topic.py" לא מציינים בבירור את מטרתם
+4. **ללא שכבות ברורות** - קשה לראות מה תלוי במה
+
+## מבנה מוצע
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # סוגי ליבה בסיסיים המשמשים בכל מקום
+│   ├── __init__.py
+│   ├── primitives.py  # שגיאה, ערך, טריפל, שדה, סכימת שורה
+│   ├── metadata.py    # רשומת מטא-דאטה
+│   └── topic.py       # כלי לטיפול בנושאים
+│
+├── knowledge/         # מודלים של תחום ידע ואיסוף
+│   ├── __init__.py
+│   ├── graph.py       # EntityContext, EntityEmbeddings, Triples
+│   ├── document.py    # מסמך, TextDocument, חתיכה
+│   ├── knowledge.py   # סוגי איסוף ידע
+│   ├── embeddings.py  # כל סוגי הסתמכות הקשורים (הועברו מקבצים רבים)
+│   └── nlp.py         # סוגי הגדרה, נושא, קשר, עובדה
+│
+└── services/          # חוזים של בקשות/תגובות שירות
+    ├── __init__.py
+    ├── llm.py         # TextCompletion, Embeddings, בקשות/תגובות של כלי
+    ├── retrieval.py   # שאילתות/תגובות של GraphRAG, DocumentRAG
+    ├── query.py       # בקשות/תגובות של GraphEmbeddings, DocumentEmbeddings
+    ├── agent.py       # בקשות/תגובות של סוכן
+    ├── flow.py        # בקשות/תגובות של זרימה
+    ├── prompt.py      # בקשות/תגובות של שירות בקשות
+    ├── config.py      # שירות תצורה
+    ├── library.py     # שירות ספרייה
+    └── lookup.py      # שירות חיפוש
+```
+
+## שינויים מרכזיים
+
+1. **ארגון היררכי** - הפרדה ברורה בין סוגים ליבה, מודלים של ידע, וחוזים של שירות
+2. **שמות טובים יותר**:
+   - `types.py` → `core/primitives.py` (מטרה ברורה יותר)
+   - `object.py` → פירוק בין קבצים מתאימים בהתאם לתוכן
+   - `documents.py` → `knowledge/document.py` (יחיד, עקבי)
+   - `models.py` → `services/llm.py` (סוגי מודלים ברורים יותר)
+   - `prompt.py` → פירוק: חלקי שירות ל- `services/prompt.py`, סוגי נתונים ל- `knowledge/nlp.py`
+
+3. **קבוצות לוגיות**:
+   - כל סוגי ההסתמכות הועברו ל- `knowledge/embeddings.py`
+   - כל חוזי השירות הקשורים ל-LLM ב- `services/llm.py`
+   - הפרדה ברורה של זוגות בקשות/תגובות בספריית השירותים
+   - סוגי איסוף ידע מקובצים עם מודלים אחרים של תחום ידע
+
+4. **בהירות תלות**:
+   - סוגים ליבה אין תלות
+   - מודלים של ידע תלויים רק בסוגים ליבה
+   - חוזי שירות יכולים להיות תלויים בשני סוגים ליבה ומודלים של ידע
+
+## יתרונות המעבר
+
+1. **ניווט קל יותר** - מפתחים יכולים למצוא במהירות את מה שהם צריכים
+2. **מודולריות טובה יותר** - גבולות ברורים בין דאגות שונות
+3. **ייבוא פשוט יותר** - מסלולי ייבוא אינטואיטיביים יותר
+4. **עתידי** - קל להוסיף סוגי ידע חדשים או שירותים ללא בלבול
+
+## שינויים דוגמה לייבוא
+
+```python
+# לפני
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# אחרי
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## הערות ליישום
+
+1. שמירה על תאימות אחורה על ידי שמירה על ייבוא ב- `__init__.py`
+2. העברת קבצים בהדרגה, תוך עדכון ייבוא לפי הצורך
+3. שקול להוסיף קובץ `legacy.py` שיבוא הכל עבור תקופת המעבר
+4. עדכון תיעוד כדי לשקף את המבנה החדש
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "להעריך את מבנה תיקיית הסכימה הנוכחי", "status": "completed", "priority": "high"}, {"id": "2", "content": "לנתח את הקבצים של הסכימה ולמטרות שלהם", "status": "completed", "priority": "high"}, {"id": "3", "content": "להציע מבנה ושמות טובים יותר", "status": "completed", "priority": "high"}]

docs/tech-specs/schema-refactoring-proposal.hi.md

@@ -0,0 +1,91 @@
+## स्कीमा निर्देशिका का पुनर्गठन प्रस्ताव
+
+## वर्तमान मुद्दे
+
+1. **सममित संरचना** - सभी स्कीमा एक ही निर्देशिका में होने से उनके बीच के संबंधों को समझना मुश्किल हो जाता है
+2. **विभिन्न चिंताएं** - कोर प्रकार, डोमेन ऑब्जेक्ट और एपीआई अनुबंध सभी एक साथ
+3. **अस्पष्ट नामकरण** - फ़ाइलें जैसे "object.py", "types.py", "topic.py" स्पष्ट रूप से उनकी propósito नहीं दर्शाती हैं
+4. **स्पष्ट परतें नहीं** - यह स्पष्ट नहीं है कि कौन सी चीज़ किससे जुड़ी है
+
+## प्रस्तावित संरचना
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # हर जगह उपयोग किए जाने वाले कोर मूल प्रकार
+│   ├── __init__.py
+│   ├── primitives.py  # त्रुटि, मूल्य, त्रिक, फ़ील्ड, पंक्ति स्कीमा
+│   ├── metadata.py    # मेटाडेटा रिकॉर्ड
+│   └── topic.py       # विषय उपयोगिताएं
+│
+├── knowledge/         # ज्ञान डोमेन मॉडल और निष्कर्षण
+│   ├── __init__.py
+│   ├── graph.py       # एंटिटीसंदर्भ, एंटिटी एम्बेडिंग, त्रिक
+│   ├── document.py    # दस्तावेज़, टेक्स्टदस्तावेज़, टुकड़ा
+│   ├── knowledge.py   # ज्ञान निष्कर्षण प्रकार
+│   ├── embeddings.py  # सभी एम्बेडिंग संबंधित प्रकार (कई फ़ाइलों से स्थानांतरित)
+│   └── nlp.py         # परिभाषा, विषय, संबंध, तथ्य प्रकार
+│
+└── services/          # सेवा अनुरोध/प्रतिक्रिया अनुबंध
+    ├── __init__.py
+    ├── llm.py         # टेक्स्टकम्प्लीशन, एम्बेडिंग, टूल अनुरोध/प्रतिक्रिया
+    ├── retrieval.py   # ग्राफ़RAG, दस्तावेज़RAG क्वेरी/प्रतिक्रिया
+    ├── query.py       # ग्राफ़एम्बेडिंग अनुरोध/प्रतिक्रिया, दस्तावेज़एम्बेडिंग अनुरोध/प्रतिक्रिया
+    ├── agent.py       # एजेंट अनुरोध/प्रतिक्रिया
+    ├── flow.py        # फ़्लो अनुरोध/प्रतिक्रिया
+    ├── prompt.py      # प्रॉम्प्ट सेवा अनुरोध/प्रतिक्रिया
+    ├── config.py      # कॉन्फ़िगरेशन सेवा
+    ├── library.py     # लाइब्रेरियन सेवा
+    └── lookup.py      # लुकअप सेवा
+```
+
+## मुख्य परिवर्तन
+
+1. **पदानुक्रमित संगठन** - स्पष्ट विभाजन कोर प्रकारों, ज्ञान मॉडल और सेवा अनुबंधों के बीच
+2. **बेहतर नामकरण**:
+   - `types.py` → `core/primitives.py` (अधिक स्पष्ट उद्देश्य)
+   - `object.py` → वास्तविक सामग्री के आधार पर उचित फ़ाइलों में विभाजित
+   - `documents.py` → `knowledge/document.py` (एकल, सुसंगत)
+   - `models.py` → `services/llm.py` (अधिक स्पष्ट रूप से किस प्रकार के मॉडल)
+   - `prompt.py` → विभाजित: सेवा भागों को `services/prompt.py` में, डेटा प्रकारों को `knowledge/nlp.py` में
+
+3. **तार्किक समूहीकरण**:
+   - सभी एम्बेडिंग प्रकारों को `knowledge/embeddings.py` में समेकित किया गया है
+   - सभी LLM-संबंधित सेवा अनुबंधों को `services/llm.py` में रखा गया है
+   - सेवाओं की निर्देशिका में अनुरोध/प्रतिक्रिया जोड़े का स्पष्ट विभाजन
+   - ज्ञान निष्कर्षण प्रकारों को अन्य ज्ञान डोमेन मॉडल के साथ समूहीकृत किया गया है
+
+4. **निर्भरता स्पष्टता**:
+   - कोर प्रकारों में कोई निर्भरता नहीं है
+   - ज्ञान मॉडल केवल कोर पर निर्भर होते हैं
+   - सेवा अनुबंध कोर और ज्ञान मॉडल दोनों पर निर्भर हो सकते हैं
+
+## माइग्रेशन के लाभ
+
+1. **आसान नेविगेशन** - डेवलपर्स आसानी से वह ढूंढ सकते हैं जिसकी उन्हें आवश्यकता है
+2. **बेहतर मॉड्यूलरिटी** - विभिन्न चिंताओं के बीच स्पष्ट सीमाएं
+3. **सरल आयात** - अधिक सहज आयात पथ
+4. **भविष्य के लिए तैयार** - बिना किसी अव्यवस्था के, नई ज्ञान प्रकारों या सेवाओं को आसानी से जोड़ा जा सकता है
+
+## उदाहरण आयात परिवर्तन
+
+```python
+# पहले
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# बाद में
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## कार्यान्वयन नोट्स
+
+1. मूल `__init__.py` में आयात को बनाए रखकर पिछड़े अनुकूलता बनाए रखें
+2. धीरे-धीरे फ़ाइलों को स्थानांतरित करें, आवश्यक अनुसार आयात को अपडेट करें
+3. एक `legacy.py` जोड़ने पर विचार करें जो एक संक्रमण अवधि के लिए सब कुछ आयात करता है
+4. नए संरचना को दर्शाने के लिए दस्तावेज़ अपडेट करें
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "वर्तमान स्कीमा निर्देशिका संरचना की जाँच करें", "status": "पूर्ण", "प्राथमिकता": "उच्च"}, {"id": "2", "content": "स्कीमा फ़ाइलों और उनके उद्देश्यों का विश्लेषण करें", "status": "पूर्ण", "प्राथमिकता": "उच्च"}, {"id": "3", "content": "बेहतर नामकरण और संरचना का प्रस्ताव", "status": "पूर्ण", "प्राथमिकता": "उच्च"}]

docs/tech-specs/schema-refactoring-proposal.ru.md

@@ -0,0 +1,91 @@
+# Схема: Предложение по реорганизации каталога
+
+## Текущие проблемы
+
+1. **Плоская структура** - Все схемы в одном каталоге затрудняют понимание взаимосвязей
+2. **Смешанные задачи** - Ядро типов, объекты домена и контракты API смешаны вместе
+3. **Неясное наименование** - Файлы, такие как "object.py", "types.py", "topic.py", не указывают четко их назначение
+4. **Отсутствие четкого уровня** - Трудно понять, на что зависит что
+
+## Предлагаемая структура
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # Основные примитивные типы, используемые везде
+│   ├── __init__.py
+│   ├── primitives.py  # Ошибка, Значение, Трипл, Поле, Схема строк
+│   ├── metadata.py    # Запись метаданных
+│   └── topic.py       # Утилиты для тем
+│
+├── knowledge/         # Модели домена знаний и извлечение
+│   ├── __init__.py
+│   ├── graph.py       # EntityContext, EntityEmbeddings, Триплы
+│   ├── document.py    # Документ, TextDocument, Chunk
+│   ├── knowledge.py   # Типы извлечения знаний
+│   ├── embeddings.py  # Все типы, связанные с встраиванием (перенесены из нескольких файлов)
+│   └── nlp.py         # Типы Определение, Тема, Отношение, Факты
+│
+└── services/          # Контракты запросов/ответов сервисов
+    ├── __init__.py
+    ├── llm.py         # TextCompletion, Embeddings, Запросы/ответы инструментов
+    ├── retrieval.py   # Запросы/ответы GraphRAG, DocumentRAG
+    ├── query.py       # Запросы/ответы GraphEmbeddingsRequest/Response, DocumentEmbeddingsRequest/Response
+    ├── agent.py       # Запросы/ответы агента
+    ├── flow.py        # Запросы/ответы потока
+    ├── prompt.py      # Запросы/ответы сервиса подсказок
+    ├── config.py      # Конфигурационный сервис
+    ├── library.py     # Сервис библиотека
+    └── lookup.py      # Сервис поиска
+```
+
+## Ключевые изменения
+
+1. **Иерархическая организация** - Четкое разделение между основными типами, моделями знаний и контрактами сервисов
+2. **Улучшенное наименование:**
+   - `types.py` → `core/primitives.py` (более четкое назначение)
+   - `object.py` → Разделение на соответствующие файлы на основе фактического содержимого
+   - `documents.py` → `knowledge/document.py` (одинаковое, согласованное)
+   - `models.py` → `services/llm.py` (более четко, какие модели)
+   - `prompt.py` → Разделение: части сервиса в `services/prompt.py`, типы данных в `knowledge/nlp.py`
+
+3. **Логическая группировка:**
+   - Все типы встраивания консолидированы в `knowledge/embeddings.py`
+   - Все контракты сервисов LLM в `services/llm.py`
+   - Четкое разделение пар запросов/ответов в каталоге сервисов
+   - Типы извлечения знаний сгруппированы с другими моделями домена знаний
+
+4. **Ясность зависимостей:**
+   - Основные типы не имеют зависимостей
+   - Модели знаний зависят только от основных
+   - Контракты сервисов могут зависеть как от основных, так и от моделей знаний
+
+## Преимущества миграции
+
+1. **Легче навигация** - Разработчики могут быстро найти то, что им нужно
+2. **Улучшенная модульность** - Четкие границы между разными задачами
+3. **Проще импорт** - Более интуитивные пути импорта
+4. **Готовность к будущему** - Легко добавлять новые типы знаний или сервисы, не загромождая
+
+## Пример изменений импорта
+
+```python
+# Изначально
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# После
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## Заметки по реализации
+
+1. Сохраняйте обратную совместимость, поддерживая импорт в корневом файле `__init__.py`
+2. Перемещайте файлы постепенно, обновляя импорты по мере необходимости
+3. Рассмотрите возможность добавления файла `legacy.py`, который импортирует всё для переходного периода
+4. Обновите документацию, чтобы отразить новую структуру
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "Оценить текущую структуру каталога схемы", "status": "completed", "priority": "high"}, {"id": "2", "content": "Проанализировать файлы схемы и их назначение", "status": "completed", "priority": "high"}, {"id": "3", "content": "Предложить улучшенное наименование и структуру", "status": "completed", "priority": "high"}]

docs/tech-specs/schema-refactoring-proposal.zh-cn.md

@@ -0,0 +1,91 @@
+# 方案：Schema 目录重构
+
+## 当前问题
+
+1. **扁平结构** - 所有 Schema 都位于同一目录下，难以理解它们之间的关系
+2. **混杂的关注点** - 核心类型、领域对象和 API 契约都混合在一起
+3. **不明确的命名** - 文件如 "object.py", "types.py", "topic.py" 并不能清晰地表明其用途
+4. **缺乏明确的层级** - 无法轻松地看出哪些依赖于哪些
+
+## 建议的结构
+
+```
+trustgraph-base/trustgraph/schema/
+├── __init__.py
+├── core/              # 核心基本类型，在所有地方使用
+│   ├── __init__.py
+│   ├── primitives.py  # Error, Value, Triple, Field, RowSchema
+│   ├── metadata.py    # 元数据记录
+│   └── topic.py       # Topic 工具
+│
+├── knowledge/         # 知识领域模型和提取
+│   ├── __init__.py
+│   ├── graph.py       # EntityContext, EntityEmbeddings, Triples
+│   ├── document.py    # Document, TextDocument, Chunk
+│   ├── knowledge.py   # 知识提取类型
+│   ├── embeddings.py  # 所有与嵌入相关的类型（从多个文件中移动）
+│   └── nlp.py         # Definition, Topic, Relationship, Fact 类型
+│
+└── services/          # 服务请求/响应契约
+    ├── __init__.py
+    ├── llm.py         # TextCompletion, Embeddings, Tool 请求/响应
+    ├── retrieval.py   # GraphRAG, DocumentRAG 查询/响应
+    ├── query.py       # GraphEmbeddingsRequest/Response, DocumentEmbeddingsRequest/Response
+    ├── agent.py       # Agent 请求/响应
+    ├── flow.py        # Flow 请求/响应
+    ├── prompt.py      # Prompt 服务请求/响应
+    ├── config.py      # 配置服务
+    ├── library.py     # 库服务
+    └── lookup.py      # 查找服务
+```
+
+## 关键变更
+
+1. **分层组织** - 清晰地将核心类型、知识模型和服务契约分开
+2. **更好的命名**：
+   - `types.py` → `core/primitives.py` (更清晰的用途)
+   - `object.py` → 根据实际内容将文件拆分
+   - `documents.py` → `knowledge/document.py` (单数，一致)
+   - `models.py` → `services/llm.py` (更清晰地表明模型类型)
+   - `prompt.py` → 拆分：服务部分到 `services/prompt.py`，数据类型到 `knowledge/nlp.py`
+
+3. **逻辑分组**：
+   - 所有嵌入类型集中在 `knowledge/embeddings.py`
+   - 所有与 LLM 相关的服务契约在 `services/llm.py`
+   - 在 services 目录中明确区分请求/响应对
+   - 知识提取类型与其它知识领域模型分组
+
+4. **依赖关系清晰**：
+   - 核心类型没有依赖
+   - 知识模型仅依赖核心
+   - 服务契约可以依赖核心和知识模型
+
+## 迁移的好处
+
+1. **更轻松的导航** - 开发者可以快速找到所需的内容
+2. **更好的模块化** - 区分不同关注点更清晰
+3. **更简单的导入** - 更有意义的导入路径
+4. **更具未来性** - 轻松添加新的知识类型或服务，而无需增加混乱
+
+## 示例导入变更
+
+```python
+# 之前
+from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
+
+# 之后
+from trustgraph.schema.core import Error, Triple
+from trustgraph.schema.knowledge import GraphEmbeddings
+from trustgraph.schema.services import TextCompletionRequest
+```
+
+## 实施说明
+
+1. 通过在根的 `__init__.py` 中保持导入，保持与以前的兼容性
+2. 逐步移动文件，并在需要时更新导入
+3. 考虑添加一个 `legacy.py`，用于在过渡期间导入所有内容
+4. 更新文档以反映新的结构
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"id": "1", "content": "检查当前 Schema 目录结构", "status": "completed", "priority": "high"}, {"id": "2", "content": "分析 Schema 文件及其用途", "status": "completed", "priority": "high"}, {"id": "3", "content": "提出改进的命名和结构", "status": "completed", "priority": "high"}]

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

@@ -0,0 +1,131 @@
+# مخطط بيانات البنية: تغييرات مخطط Pulsar
+
+## نظرة عامة
+
+استنادًا إلى مواصفات `STRUCTURED_DATA.md`، تقترح هذه الوثيقة الإضافات والتعديلات اللازمة على مخطط Pulsar لدعم قدرات البيانات المنظمة في TrustGraph.
+
+## تغييرات مخطط مطلوبة
+
+### 1. تحسينات مخطط أساسية
+
+#### تعريف الحقل المحسّن
+تحتاج الفئة الحالية `Field` في `core/primitives.py` إلى خصائص إضافية:
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # حقول جديدة:
+    required = Boolean()  # ما إذا كان الحقل مطلوبًا
+    enum_values = Array(String())  # للحقول من نوع Enum
+    indexed = Boolean()  # ما إذا كان يجب فهرسة الحقل
+```
+
+### 2. مخططات معرفة جديدة
+
+#### 2.1 إرسال بيانات منظمة
+ملف جديد: `knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # مرجع إلى المخطط في التكوين
+    data = Bytes()  # البيانات الخام للإدخال
+    options = Map(String())  # خيارات محددة بالتنسيق
+```
+
+### 3. مخططات الخدمات الجديدة
+
+#### 3.1 خدمة استعلام NLP إلى منظمة
+ملف جديد: `services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # تلميحات سياق اختيارية لتوليد الاستعلام
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # استعلام GraphQL المُنشأ
+    variables = Map(String())  # متغيرات GraphQL إذا كانت موجودة
+    detected_schemas = Array(String())  # المخططات التي يستهدفها الاستعلام
+    confidence = Double()
+```
+
+#### 3.2 خدمة استعلام منظمة
+ملف جديد: `services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # استعلام GraphQL
+    variables = Map(String())  # متغيرات GraphQL
+    operation_name = String()  # اسم العملية الاختياري للمستندات متعددة العمليات
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # بيانات استجابة GraphQL المُشفرة بتنسيق JSON
+    errors = Array(String())  # أخطاء GraphQL إذا كانت موجودة
+```
+
+#### 2.2 مخرجات استخراج الكائنات
+ملف جديد: `knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # أي مخطط ينتمي إليه هذا الكائن
+    values = Map(String())  # اسم الحقل -> القيمة
+    confidence = Double()
+    source_span = String()  # نطاق النص الذي تم فيه العثور على الكائن
+```
+
+### 4. مخططات معرفة محسّنة
+
+#### 4.1 تحسين تضمين الكائنات
+قم بتحديث `knowledge/embeddings.py` لدعم تضمين الكائنات المنظمة بشكل أفضل:
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # قيمة المفتاح الأساسي
+    field_embeddings = Map(Array(Double()))  # تضمينات الحقول
+```
+
+## نقاط التكامل
+
+### تكامل التدفق
+
+سيتم استخدام المخططات في وحدات تدفق جديدة:
+- `trustgraph-flow/trustgraph/decoding/structured` - يستخدم StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - يستخدم مخططات استعلام NLP
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - يستخدم مخططات استعلام منظمة
+- `trustgraph-flow/trustgraph/extract/object/row/` - يستهلك Chunk، وينتج ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - يستخدم مخطط Rows
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - يستخدم مخططات تضمين الكائنات
+
+## ملاحظات التنفيذ
+
+1. **إصدار المخطط**: ضع في اعتبارك إضافة حقل `version` إلى RowSchema لدعم الترحيل المستقبلي
+2. **نظام الأنواع**: يجب أن يدعم `Field.type` جميع أنواع بيانات Cassandra الأصلية
+3. **عمليات المجموعة**: يجب أن يدعم معظم الخدمات العمليات الفردية والمجمعة
+4. **معالجة الأخطاء**: يجب أن يكون للإبلاغ عن الأخطاء باستمرار عبر جميع الخدمات الجديدة
+5. **التوافق مع الإصدارات السابقة**: تظل المخططات الحالية دون تغيير باستثناء التحسينات الطفيفة للملفات

docs/tech-specs/structured-data-schemas.es.md

@@ -0,0 +1,137 @@
+# Cambios en el Esquema de Datos Estructurados en Pulsar
+
+## Visión general
+
+Basado en la especificación `STRUCTURED_DATA.md`, este documento propone las adiciones y modificaciones necesarias en el esquema de Pulsar para soportar las capacidades de datos estructurados en TrustGraph.
+
+## Cambios de Esquema Requeridos
+
+### 1. Mejoras en el Esquema Central
+
+#### Definición de Campo Mejorada
+La clase `Field` existente en `core/primitives.py` necesita propiedades adicionales:
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # CAMPOS NUEVOS:
+    required = Boolean()  # Indica si el campo es obligatorio
+    enum_values = Array(String())  # Para campos de tipo enum
+    indexed = Boolean()  # Indica si el campo debe ser indexado
+```
+
+### 2. Nuevos Esquemas de Conocimiento
+
+#### 2.1 Envío de Datos Estructurados
+Nuevo archivo: `knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # Referencia al esquema en la configuración
+    data = Bytes()  # Datos brutos para ingerir
+    options = Map(String())  # Opciones específicas del formato
+```
+
+#### 2.2 Nuevo Servicio de Consulta Estructurada
+Nuevo archivo: `services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # Contexto opcional para la generación de consulta
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # Consulta GraphQL generada
+    variables = Map(String())  # Variables de GraphQL si existen
+    detected_schemas = Array(String())  # Esquemas a los que apunta la consulta
+    confidence = Double()
+```
+
+#### 2.2 Servicio de Consulta Estructurada
+Nuevo archivo: `services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # Consulta GraphQL
+    variables = Map(String())  # Variables de GraphQL
+    operation_name = String()  # Nombre opcional de operación para documentos con múltiples operaciones
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # Datos de respuesta GraphQL codificados en JSON
+    errors = Array(String())  # Errores GraphQL si existen
+```
+
+#### 2.2 Salida de Extracción de Objetos
+Nuevo archivo: `knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # Esquema al que pertenece este objeto
+    values = Map(String())  # Nombre del campo -> valor
+    confidence = Double()
+    source_span = String()  # Rango de texto donde se encontró el objeto
+```
+
+### 4. Esquemas de Conocimiento Mejorados
+
+#### 4.1 Mejora en la Incorporación de Objetos
+Actualiza `knowledge/embeddings.py` para soportar una mejor incorporación de objetos estructurados:
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # Valor clave primaria
+    field_embeddings = Map(Array(Double()))  # Incorporaciones por campo
+```
+
+## Puntos de Integración
+
+### Integración de Flujo
+
+Los esquemas se utilizarán en nuevos módulos de flujo:
+- `trustgraph-flow/trustgraph/decoding/structured` - Utiliza StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - Utiliza esquemas de consulta NLP
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - Utiliza esquemas de consulta estructurada
+- `trustgraph-flow/trustgraph/extract/object/row/` - Consumo de Chunk, produce ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - Utiliza Esquema de Filas
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - Utiliza esquemas de incorporación de objetos
+
+## Notas de Implementación
+
+1. **Versionado del Esquema**: Considerar añadir un campo `version` al Esquema de Fila para soporte de migración futuro.
+2. **Sistema de Tipos**: El `Field.type` debería soportar todos los tipos nativos de Cassandra.
+3. **Operaciones en Lotes**: La mayoría de los servicios deben soportar tanto operaciones individuales como en lote.
+4. **Manejo de Errores**: Reporte de errores consistente en todos los nuevos servicios.
+5. **Compatibilidad hacia atrás**: Los esquemas existentes permanecen sin cambios, excepto por las pequeñas mejoras en los Campos.
+
+## Próximos Pasos
+
+1. Implementar los archivos de esquema en la nueva estructura.
+2. Actualizar los servicios existentes para reconocer los nuevos tipos de esquema.
+3. Implementar los módulos de flujo que utilicen estos esquemas.
+4. Añadir puntos finales gateway/rev-gateway para los nuevos servicios.
+5. Crear pruebas unitarias para la validación del esquema.

docs/tech-specs/structured-data-schemas.he.md

@@ -0,0 +1,139 @@
+# שינויים בסכימת נתונים מובנית עבור פולסר
+
+## סקירה כללית
+
+בהתבסס על מפרט ה-STRUCTURED_DATA.md, המסמך מציע את התוספות והשינויים הנדרשים בסכימת פולסר כדי לתמוך ביכולות נתונים מובנות ב-TrustGraph.
+
+## שינויים בסכימה נדרשים
+
+### 1. שיפורים בסכימה הליבה
+
+#### הגדרת שדה משופרת
+המחלקה `Field` הקיימת בקובץ `core/primitives.py` זקוקה לתכונות נוספות:
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # שדות חדשים:
+    required = Boolean()  # האם השדה נדרש
+    enum_values = Array(String())  # עבור סוגי שדות enum
+    indexed = Boolean()  # האם השדה צריך להיות מצביע
+```
+
+### 2. סכימות ידע חדשות
+
+#### 2.1 שליחת נתונים מובנים
+קובץ חדש: `knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # הפניה לסכימה בקונפיגורציה
+    data = Bytes()  # נתונים גולמיים לשליחה
+    options = Map(String())  # אפשרויות ספציפיות לפורמט
+```
+
+#### 3. סכימות שירות חדשות
+
+#### 3.1 שירות שאילתות NLP לנתונים מובנים
+קובץ חדש: `services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # הקשר אופציונלי לשליפת שאילתה
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # שאילתת GraphQL שנוצרה
+    variables = Map(String())  # משתני GraphQL אם יש
+    detected_schemas = Array(String())  # אילו סכימות השאילתה מכוונות
+    confidence = Double()
+```
+
+#### 3.2 שירות שאילתות מובנות
+קובץ חדש: `services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # שאילתת GraphQL
+    variables = Map(String())  # משתני GraphQL
+    operation_name = String()  # שם פעולה אופציונלי למסמכים מרובי פעולות
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # נתוני התגובה של GraphQL מקודדים ב-JSON
+    errors = Array(String())  # שגיאות GraphQL אם יש
+```
+
+#### 2.2 פלט חילוץ אובייקטים
+קובץ חדש: `knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # לאיזו סכימה השם הזה שייך
+    values = Map(String())  # שם שדה -> ערך
+    confidence = Double()
+    source_span = String()  # טקסט השדה בו נמצא האובייקט
+```
+
+### 4. סכימות ידע משופרות
+
+#### 4.1 שיפור אמצעי הטבע
+עדכן את `knowledge/embeddings.py` כדי לתמוך טוב יותר באמצעי הטבע מובנים:
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # ערך מפתח ראשי
+    field_embeddings = Map(Array(Double()))  # אמצעי הטבע לכל שדה
+```
+
+## נקודות אינטגרציה
+
+### אינטגרציה של זרימה
+
+הסכימות ישמשו על ידי מודולי זרימה חדשים:
+- `trustgraph-flow/trustgraph/decoding/structured` - משתמש ב-StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - משתמש בסכימות שאילתות NLP
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - משתמש בסכימות שאילתות מובנות
+- `trustgraph-flow/trustgraph/extract/object/row/` - צורך Chunk, מייצר ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - משתמש בסכימה Rows
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - משתמש בסכימות אמצעי הטבע
+
+## הערות על יישום
+
+1. **גרסת סכימה**: כדאי להוסיף שדה `version` ל-RowSchema לתמיכה בעדכונים עתידיים.
+2. **מערכת סוגים**: ה-`Field.type` צריך לתמוך בכל סוגי הנתונים המקוריים של Cassandra.
+3. **פעולות אצווה**: רוב השירותים צריכים לתמוך הן בפעולות בודדות והן בפעולות אצווה.
+4. **טיפול בשגיאות**: דיווח אחיד על שגיאות בכל השירותים החדשים.
+5. **תאימות לאחור**: הסכימות הקיימות נשארות ללא שינוי, מלבד שיפורים קטנים בשדות.
+
+## שלבים הבאים
+
+1. יישום קבצי הסכימה במבנה החדש.
+2. עדכון שירותים קיימים כדי לזהות סוגי סכימה חדשים.
+3. יישום מודולי זרימה המשתמשים בסכימות אלה.
+4. הוספת סיומות גשר/rev-גשר לשירותים החדשים.
+5. יצירת בדיקות יחידה עבור אימות סכימה.

docs/tech-specs/structured-data-schemas.ru.md

@@ -0,0 +1,139 @@
+# Структурированные данные Pulsar: Изменения схемы
+
+## Обзор
+
+На основе спецификации `STRUCTURED_DATA.md`, этот документ предлагает необходимые дополнения и изменения схемы Pulsar для поддержки возможностей работы со структурированными данными в TrustGraph.
+
+## Необходимые изменения схемы
+
+### 1. Улучшения основной схемы
+
+#### Улучшенное определение поля
+Сущность `Field` в файле `core/primitives.py` требует дополнительных свойств:
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # НОВЫЕ ПОЛЯ:
+    required = Boolean()  # Требуется ли поле
+    enum_values = Array(String())  # Для полей типа enum
+    indexed = Boolean()  # Нужно ли индексировать поле
+```
+
+### 2. Новые схемы знаний
+
+#### 2.1 Отправка структурированных данных
+Новый файл: `knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # Ссылка на схему в конфигурации
+    data = Bytes()  # Сырые данные для обработки
+    options = Map(String())  # Опции, специфичные для формата
+```
+
+#### 2.2 Структурированный запрос
+
+#### 3.1 Преобразование NLP в структурированный запрос
+Новый файл: `services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # Дополнительный контекст для генерации запроса
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # Сгенерированный GraphQL запрос
+    variables = Map(String())  # Переменные GraphQL, если есть
+    detected_schemas = Array(String())  # Какие схемы затрагивает запрос
+    confidence = Double()
+```
+
+#### 3.2 Структурированный запрос
+Новый файл: `services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # GraphQL запрос
+    variables = Map(String())  # Переменные GraphQL
+    operation_name = String()  # Дополнительное имя операции для документов с несколькими операциями
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # JSON-кодированный формат данных GraphQL
+    errors = Array(String())  # Ошибки GraphQL, если есть
+```
+
+#### 2.2 Вывод извлечения объектов
+Новый файл: `knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # Какая схема принадлежит этому объекту
+    values = Map(String())  # Имя поля -> значение
+    confidence = Double()
+    source_span = String()  # Текстовый фрагмент, где был найден объект
+```
+
+### 4. Улучшенные схемы знаний
+
+#### 4.1 Улучшение встраивания объектов
+Обновите `knowledge/embeddings.py` для лучшей поддержки встраивания структурированных объектов:
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # Основной ключ
+    field_embeddings = Map(Array(Double()))  # Встраивание для каждого поля
+```
+
+## Точки интеграции
+
+### Интеграция потоков
+
+Схемы будут использоваться в новых модулях потоков:
+- `trustgraph-flow/trustgraph/decoding/structured` - Использует StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - Использует схемы запросов NLP
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - Использует схемы структурированных запросов
+- `trustgraph-flow/trustgraph/extract/object/row/` - Потребляет Chunk, производит ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - Использует схему Rows
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - Использует схемы встраивания объектов
+
+## Примечания по реализации
+
+1. **Версионирование схемы**: Рассмотрите возможность добавления поля `version` к схеме RowSchema для поддержки будущих миграций.
+2. **Система типов**: `Field.type` должна поддерживать все родные типы Cassandra.
+3. **Операции пакета**: Большинство сервисов должны поддерживать как одиночные, так и пакетные операции.
+4. **Обработка ошибок**: Необходимо обеспечить единообразное сообщение об ошибках во всех новых сервисах.
+5. **Совместимость с существующими схемами**: Существующие схемы остаются неизменными, за исключением незначительных улучшений поля.
+
+## Следующие шаги
+
+1. Реализуйте файлы схем в новой структуре.
+2. Обновите существующие сервисы для распознавания новых типов схем.
+3. Реализуйте модули потоков, использующие эти схемы.
+4. Добавьте конечные точки gateway/rev-gateway для новых сервисов.
+5. Создайте модульные тесты для проверки схемы.

docs/tech-specs/structured-data-schemas.sw.md

@@ -0,0 +1,122 @@
+# Mfano wa Data, Mbadala ya Pulsar
+
+## Maelezo
+
+Kulingana na toleo la `STRUCTURED_DATA.md`, hati hii inatoa mabadiliko muhimu ya mfano wa Pulsar na mabadiliko, ili kupendeza uwezo wa data iliyoundwa katika TrustGraph.
+
+## Mabadiliko muhimu ya mfano
+
+### 1. Uboreshaji wa mfano
+#### Maelezo ya shamba
+Sasa, kwenye `Field` class katika `core/primitives.py`, lazima ipate mali zaidi:
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # MAELEZO MPYA:
+    required = Boolean()  # Mara kama shamba ni muhimu
+    enum_values = Array(String())  # Kwa miundo ya shamba
+    indexed = Boolean()  # Mara kama shamba linahitajika
+```
+
+### 2. Mfano mpya wa Maarifa
+
+#### 2.1 Utumaji Data Iliyoundwa
+Faili mpya: `knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # Mara kama mfano katika faili
+    data = Bytes()  # Data iliyoundwa
+    options = Map(String())  # Chaguzi maalum kwa format
+```
+
+### 3. Mfano mpya wa Huduma
+
+#### 3.1 Huduma ya NLP hadi Sarani ya Data
+Faili mpya: `services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # Mara kama mawasiliano kwa utengenezaji wa sarani
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # Sarani GraphQL iliyoundwa
+    variables = Map(String())  # Chaguzi GraphQL
+    detected_schemas = Array(String())  # Miundo ambazo sarani huangalia
+    confidence = Double()
+```
+
+#### 3.2 Sarani ya Data
+Faili mpya: `services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # Sarani GraphQL
+    variables = Map(String())  # Chaguzi GraphQL
+    operation_name = String()  # Mara kama jina la operesheni kwa hati za mfululizo
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # Data iliyoundwa kwa JSON
+    errors = Array(String())  # Mara kama ada GraphQL
+```
+
+#### 2.2 Pato la Uteuzi wa Madhara
+Faili mpya: `knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # Mara kama mfano
+    values = Map(String())  # Jina la shamba -> thamani
+    confidence = Double()
+    source_span = String()  # Mara kama kitanzi
+```
+
+### 4. Mfano wa Maarifa
+
+#### 4.1 Uboreshaji wa Embedings
+Badilisha `knowledge/embeddings.py` ili kusaidia uhifadhi wa madhara iliyoundwa:
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # Thamani muhimu
+    field_embeddings = Map(Array(Double()))  # Embedings kwa kila shamba
+```
+
+## Vitu vya Uunganishi
+
+### Uunganishi wa Mzunguko
+
+Mifano itatumika na moduli mpya za mzunguko:
+- `trustgraph-flow/trustgraph/decoding/structured` - Inatumia StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - Inatumia mifano za sarani
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - Inatumia mifano za sarani
+- `trustgraph-flow/trustgraph/extract/object/row/` - Inatumia Chunk, inatoa ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - Inatumia mfano wa Rows
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - Inatumia mifano za embedings

docs/tech-specs/structured-data-schemas.zh-cn.md

@@ -0,0 +1,139 @@
+# 结构化数据 Pulsar 模式更改
+
+## 概述
+
+根据 `STRUCTURED_DATA.md` 规范，本文件提出必要的 Pulsar 模式添加和修改，以支持 TrustGraph 中的结构化数据功能。
+
+## 必需的模式更改
+
+### 1. 核心模式增强
+
+#### 增强的字段定义
+现有的 `Field` 类在 `core/primitives.py` 中需要额外的属性：
+
+```python
+class Field(Record):
+    name = String()
+    type = String()  # int, string, long, bool, float, double, timestamp
+    size = Integer()
+    primary = Boolean()
+    description = String()
+    # 新字段：
+    required = Boolean()  # 字段是否必需
+    enum_values = Array(String())  # 针对枚举类型的字段
+    indexed = Boolean()  # 字段是否应进行索引
+```
+
+### 2. 新的知识模式
+
+#### 2.1 结构化数据提交
+新的文件：`knowledge/structured.py`
+
+```python
+from pulsar.schema import Record, String, Bytes, Map
+from ..core.metadata import Metadata
+
+class StructuredDataSubmission(Record):
+    metadata = Metadata()
+    format = String()  # "json", "csv", "xml"
+    schema_name = String()  # 引用配置中的模式
+    data = Bytes()  # 原始数据，用于导入
+    options = Map(String())  # 格式特定的选项
+```
+
+#### 2.2 结构化查询模式
+
+#### 3.1 NLP 到结构化查询服务
+新的文件：`services/nlp_query.py`
+
+```python
+from pulsar.schema import Record, String, Array, Map, Integer, Double
+from ..core.primitives import Error
+
+class NLPToStructuredQueryRequest(Record):
+    natural_language_query = String()
+    max_results = Integer()
+    context_hints = Map(String())  # 针对查询生成的可选上下文
+
+class NLPToStructuredQueryResponse(Record):
+    error = Error()
+    graphql_query = String()  # 生成的 GraphQL 查询
+    variables = Map(String())  # 如果有的话，GraphQL 变量
+    detected_schemas = Array(String())  # 查询的目标模式
+    confidence = Double()
+```
+
+#### 3.2 结构化查询服务
+新的文件：`services/structured_query.py`
+
+```python
+from pulsar.schema import Record, String, Map, Array
+from ..core.primitives import Error
+
+class StructuredQueryRequest(Record):
+    query = String()  # GraphQL 查询
+    variables = Map(String())  # GraphQL 变量
+    operation_name = String()  # 针对多操作文档的可选操作名称
+
+class StructuredQueryResponse(Record):
+    error = Error()
+    data = String()  # JSON 编码的 GraphQL 响应数据
+    errors = Array(String())  # 如果有的话，GraphQL 错误
+```
+
+#### 2.2 对象提取输出
+新的文件：`knowledge/object.py`
+
+```python
+from pulsar.schema import Record, String, Map, Double
+from ..core.metadata import Metadata
+
+class ExtractedObject(Record):
+    metadata = Metadata()
+    schema_name = String()  # 此对象属于哪个模式
+    values = Map(String())  # 字段名称 -> 值
+    confidence = Double()
+    source_span = String()  # 对象所在的文本范围
+```
+
+### 4. 增强的知识模式
+
+#### 4.1 对象嵌入增强
+更新 `knowledge/embeddings.py` 以更好地支持结构化对象嵌入：
+
+```python
+class StructuredObjectEmbedding(Record):
+    metadata = Metadata()
+    vectors = Array(Array(Double()))
+    schema_name = String()
+    object_id = String()  # 主键值
+    field_embeddings = Map(Array(Double()))  # 针对每个字段的嵌入
+```
+
+## 集成点
+
+### 流集成
+
+这些模式将由新的流模块使用：
+- `trustgraph-flow/trustgraph/decoding/structured` - 使用 StructuredDataSubmission
+- `trustgraph-flow/trustgraph/query/nlp_query/cassandra` - 使用 NLP 查询模式
+- `trustgraph-flow/trustgraph/query/objects/cassandra` - 使用结构化查询模式
+- `trustgraph-flow/trustgraph/extract/object/row/` - 消耗 Chunk，产生 ExtractedObject
+- `trustgraph-flow/trustgraph/storage/objects/cassandra` - 使用 Rows 模式
+- `trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - 使用对象嵌入模式
+
+## 实现说明
+
+1. **模式版本控制**: 考虑为 RowSchema 添加 `version` 字段，以便进行未来迁移支持
+2. **类型系统**: `Field.type` 应该支持所有 Cassandra 原生类型
+3. **批量操作**: 大多数服务都应该支持单个和批量操作
+4. **错误处理**: 所有新服务的错误报告应保持一致
+5. **向后兼容性**: 现有的模式不受影响，只有字段进行了轻微增强
+
+## 接下来要做的事
+
+1. 在新的结构中实现模式文件
+2. 更新现有服务以识别新的模式类型
+3. 实现使用这些模式的流模块
+4. 为新的服务添加网关/反向网关端点
+5. 创建模式验证的单元测试

docs/tech-specs/tool-services.ar.md

@@ -0,0 +1,96 @@
+**تعليمات مهمة:**
+
+- احتفظ بجميع التنسيقات (العناوين، الروابط، علامات HTML) بشكل صحيح.
+- لا تترجم أي شي داخل علامات backticks أو كتل التعليمات البرمجية.
+- قم بإخراج النص المترجم فقط، بدون أي مقدمة أو تفسيرات.
+
+**النص المراد ترجمته:**
+
+# خدمات الأداة: أدوات الوكلاء القابلة للتوصيل ديناميكيًا
+
+## الحالة
+
+مُنفَّذ
+
+## نظرة عامة
+
+يحدد هذا المواصفق آلية لأدوات الوكلاء القابلة للتوصيل ديناميكيًا تسمى "خدمات الأدوات". على عكس أنواع الأدوات المدمجة الموجودة (`KnowledgeService`, `McPTool`), لا تتطلب هذه الطريقة إعداد مسبق.
+
+## مفاهيم أساسية
+
+*   **خدمات الأدوات:** مكونات قابلة للتوصيل ديناميكيًا يمكن للوكيل استدعائها.
+*   **الوكيل:** التطبيق الذي يستخدم خدمات الأدوات.
+*   **موضوع الرسائل:** قناة اتصال بين الوكيل وخدمة الأدوات.
+
+## التصميم
+
+يعمل نظام خدمات الأدوات على مبدأ "الطلب والاستجابة". يقوم الوكيل بإنشاء طلب (رسالة) إلى خدمة الأدوات، وتقوم خدمة الأدوات بمعالجة الطلب وإرجاع استجابة (رسالة) إلى الوكيل.
+
+## بنية الطلب والاستجابة
+
+تستخدم خدمات الأدوات تنسيق رسائل بسيط وموحد لتبادل البيانات بين الوكيل وخدمة الأدوات. تتكون كل رسالة من جزئين:
+
+*   **الطلب:** يحتوي على بيانات الإدخال المطلوبة لخدمة الأدوات.
+*   **الاستجابة:** تحتوي على نتيجة معالجة الطلب من قبل خدمة الأدوات.
+
+## مثال
+
+لنفترض أن الوكيل يريد معرفة الطقس في مدينة معينة. يمكن للوكيل إنشاء طلب يحتوي على اسم المدينة وإرساله إلى خدمة الطقس. تتلقى خدمة الطقس الطلب، وتحقق من بيانات الطقس، وترسل استجابة تحتوي على معلومات الطقس إلى الوكيل.
+
+## تنفيذ
+
+يتم تنفيذ خدمات الأدوات كعمليات متزامنة. تسمح هذه الطريقة لخدمات الأدوات بالاستجابة بسرعة لطلبات الوكيل.
+
+## أمثلة
+
+*   **خدمة الطقس:** تتلقى طلبًا يحتوي على اسم المدينة وترجع معلومات الطقس.
+*   **محرك البحث:** يتلقى طلبًا يحتوي على عبارة بحث ويرجع قائمة بالنتائج.
+
+## مزايا
+
+*   **مرونة:** يمكن إضافة خدمات أدوات جديدة دون تعديل الوكيل.
+*   **قابلية التوسع:** يمكن للوكيل استخدام العديد من خدمات الأدوات في وقت واحد.
+*   **سهولة الصيانة:** يمكن تحديث خدمات الأدوات بشكل مستقل عن الوكيل.
+
+## الاعتبارات
+
+*   يجب أن تكون خدمات الأدوات مصممة لتكون خفيفة الوزن وفعالة.
+*   يجب أن تكون خدمات الأدوات قادرة على التعامل مع طلبات متعددة من وكلاء مختلفين.
+*   يجب أن تكون خدمات الأدوات آمنة وموثوقة.
+
+## مثال
+
+لنفترض أن الوكيل يريد البحث عن معلومات حول موضوع معين. يمكن للوكيل إنشاء طلب يحتوي على عبارة البحث وإرساله إلى محرك البحث. يتلقى محرك البحث الطلب، ويقوم بإجراء البحث، ويرجع قائمة بالنتائج إلى الوكيل.
+
+## الوحدة (Module)
+
+يتم تنظيم نظام خدمات الأدوات في وحدات (modules). كل وحدة مسؤولة عن تنفيذ وظيفة معينة. على سبيل المثال، قد يكون هناك وحدة للطقس ومحرك بحث ووحدة للتحقق من صحة البيانات.
+
+## واجهات برمجة التطبيقات (APIs)
+
+توفر وحدات خدمات الأدوات واجهات برمجة تطبيقات (APIs) للوكلاء للتفاعل معها. تتضمن هذه الواجهات ما يلي:
+
+*   **واجهة طلب:** تحدد تنسيق الرسائل المستخدمة لإنشاء طلبات.
+*   **واجهة استجابة:** تحدد تنسيق الرسائل المستخدمة لتلقي الاستجابات.
+
+## الأمان
+
+يتم تأمين نظام خدمات الأدوات باستخدام آليات الأمان القياسية. تتضمن هذه الآليات ما يلي:
+
+*   **التحقق من الهوية:** التحقق من هوية الوكيل قبل السماح له بالوصول إلى خدمات الأدوات.
+*   **الترخيص:** تحديد صلاحيات الوصول التي يتمتع بها كل وكيل.
+*   **التشفير:** تشفير جميع البيانات المرسلة بين الوكيل وخدمات الأدوات.
+
+## التوثيق
+
+يتم توثيق نظام خدمات الأدوات بشكل كامل. يتضمن التوثيق ما يلي:
+
+*   **وصف للواجهات:** وصف لواجهات برمجة التطبيقات (APIs) المتاحة.
+*   **أمثلة التعليمات البرمجية:** أمثلة للتعليمات البرمجية توضح كيفية استخدام خدمات الأدوات.
+*   **دليل المستخدم:** دليل المستخدم الذي يشرح كيفية استخدام نظام خدمات الأدوات.
+
+## الإصدارات المستقبلية
+
+*   **التعلم الآلي:** يمكن استخدام التعلم الآلي لتحسين أداء خدمات الأدوات.
+*   **الذكاء الاصطناعي:** يمكن استخدام الذكاء الاصطناعي لتمكين خدمات الأدوات من أداء مهام أكثر تعقيدًا.
+*   **الأمن:** يمكن تحسين أمان نظام خدمات الأدوات باستخدام تقنيات أمان جديدة.

docs/tech-specs/tool-services.he.md

@@ -0,0 +1,98 @@
+## שירותי כלי: כלים מתואמים
+
+## סטטוס
+
+יישום
+
+## סקירה כללית
+
+מפרט זה מגדיר מנגנון לכלים מתואמים של כלי, המכונים "שירותי כלי". בניגוד לסוגי הכלים הקיצוניים המובנים (`KnowledgeQueryImpl`, `McpToolImpl` וכו'), שירותי כלי מאפשרים להטמיע כלים חדשים על ידי:
+
+1. פריסת שירות פולסר חדש
+2. הוספת תיאור תצורה שמורה לאגנט כיצד להפעיל אותו
+
+זה מאפשר הרחבה מבלי לשנות את המסגרת הליבה של `agent-flow`.
+
+## איך להשתמש
+
+1.  הגדירו שירות כלי בתצורה, כולל שמות הנושאים עבור בקשות ותגובות.
+2.  הגדירו כלי באמצעות הגדרות שירות כלי.
+3.  השתמשו בכלי בתוך קוד ה-agent.
+4.  הגדירו את סוג הכלים בתיאור התצורה.
+
+## דוגמה
+
+הנה דוגמה להגדרת שירות כלי בשם "joke-service":
+
+1.  **שירות כלי:**
+
+    ```json
+    {
+      "id": "joke-service",
+      "request-queue": "non-persistent://tg/request/joke",
+      "response-queue": "non-persistent://tg/response/joke",
+      "config-params": [
+        {"name": "style", "required": false}
+      ]
+    }
+    ```
+
+2.  **כלי:**
+
+    ```json
+    {
+      "type": "tool-service",
+      "name": "tell-joke",
+      "description": "Tell a joke on a given topic",
+      "service": "joke-service",
+      "style": "pun",
+      "arguments": [
+        {"name": "topic", "type": "string", "description": "The topic for the joke"}
+      ]
+    }
+    ```
+
+3.  **קוד ה-agent (פסאודו-קוד):**
+
+    ```python
+    # Load the joke service configuration
+    tool_service_config = tg_get_config_item("tool-service/joke-service")
+
+    # Load the tool configuration
+    tool_config = tg_get_config_item("tool/tell-joke")
+
+    # Instantiate the tool service
+    joke_service = DynamicToolService(
+        request_queue=tool_service_config["request-queue"],
+        response_queue=tool_service_config["response-queue"],
+        config_values=tool_config["config-params"],  # Map config parameters
+        arguments=tool_config["arguments"],
+    )
+
+    # Call the tool service
+    user_name = get_user_name()  # Get the current user
+    joke_topic = "programming"  # Or get this from the LLM
+    joke = joke_service.invoke(user_name, {}, {"topic": joke_topic})
+
+    # Display the joke
+    print(f"Hey {user_name}! Here's a {tool_config['style']} for you:\n\n{joke}")
+    ```
+
+## הערות חשובות
+
+*   **`tg-put-config-item`**: השתמשו בפקודה הזו כדי לטעון את תצורות השירות והכלי. לדוגמה, `tg-put-config-item tool-service/joke-service < joke-service.json`.
+*   **`agent-flow`**: קוד ה-agent חייב להיות מותאם כך שיתפקד בהתאם למפרט. שימו לב במיוחד ל-`DynamicToolService` ואיך הוא מעובד.
+*   **שמות נושאים**: שימו לב לשמות הנושאים. הם חייבים להיות תואמים למה שמוגדר ב-`trustgraph-base/trustgraph/schema/services/tool_service.py`.
+*   **תצורת כלי**: שימו לב לתצורת הכלי, במיוחד לשדות ה-`type` (חייב להיות `"tool-service"`) ו-`arguments`.
+*   **תצורה דינמית**: השירותים עצמם יצטרכו לקרוא את תצורת ה-`tool-service` כדי לדעת מה לקבל, ולאחר מכן להגדיר את הלקוח (Client).
+*   **קוד דוגמה**: קוד הדוגמה מספק תצורה מפורטת, אבל הוא רק דוגמה. אתם צריכים להבין איך קוד ה-agent קורא לתצורה הזו.
+
+## שאלות נפוצות
+
+*   **איך למצוא את הקוד המתאים?**  הקודים שצוינו נמצאים ב-`trustgraph-flow/trustgraph/agent/react/tools.py`, `trustgraph-flow/trustgraph/agent/react/service.py`, `trustgraph-flow/trustgraph/base/dynamic_tool_service.py`, ו-`trustgraph-flow/trustgraph/schema/services/tool_service.py`.
+*   **מהו `tg-put-config-item`?**  זו פקודה שמשמשת לטעינת תצורות.
+*   **איך אני יודע מתי הכל עובד?**  בדקו שהכלים מוגדרים כראוי, ושהתצורה מועברת נכון.  השתמשו ב-logging כדי לראות אם התהליכים מתחילים, מסיטים בקשות, ומחזירים תגובות.
+
+## סיכום
+
+ההגדרה הזו מספקת מסגרת לשימוש בכלים מתואמים בתוך `trustgraph-flow`. על ידי הבנת התצורה, הקוד, והדגמים, תוכלו לשלב כלים חדשים בקלות.

docs/tech-specs/tool-services.zh-cn.md

@@ -0,0 +1,134 @@
+# 工具服务：动态可插拔的代理工具
+
+## 状态
+
+已实现
+
+## 概述
+
+该规范定义了一种动态可插拔的代理工具机制，称为“工具服务”。 与现有的内置工具类型（如 `KnowledgeQueryImpl`、`McpToolImpl` 等），工具服务允许通过以下方式引入新的工具：
+
+1.  部署一个新的基于 Pulsar 的服务
+2.  添加一个配置描述符，告诉代理如何调用它
+
+这使得无需修改核心 agent-react 框架即可实现扩展。
+
+## 术语
+
+| 术语 | 定义 |
+|---|---|
+| **内置工具** | 具有在 `tools.py` 中硬编码实现的现有工具类型 |
+| **工具服务** | 一个基于 Pulsar 的服务，可以被其他工具调用 |
+| **配置描述符** | 用于配置工具服务的 JSON 格式文件 |
+
+## 实现细节
+
+### 流程
+
+1.  **服务启动:** 服务将自身注册到 agent，包含服务名称、队列路径等信息
+2.  **工具配置:** 客户端通过加载配置描述符，动态注册服务
+3.  **调用服务:**  客户端使用 `ToolServiceClient` 调用服务
+
+### 架构
+
+```
+[客户端 (agent-react)] <-> [ToolServiceClient] <-> [服务 (dynamic_tool_service)] <-> [Pulsar 队列]
+```
+
+### 示例
+
+```python
+# 客户端 (agent-react)
+async def call_service(service_name, args):
+  # 从配置中获取 service_配置
+  service_config = get_config(service_name)
+  # 创建 ToolServiceClient
+  client = ToolServiceClient(service_config)
+  # 调用服务
+  response = await client.call(args)
+  return response
+```
+
+### 示例配置描述符
+
+```json
+{
+  "id": "joke-service",
+  "request-queue": "non-persistent://tg/request/joke",
+  "response-queue": "non-persistent://tg/response/joke",
+  "config-params": [
+    {"name": "style", "required": false}
+  ]
+}
+```
+
+### 示例工具配置
+
+```json
+{
+  "type": "tool-service",
+  "name": "tell-joke",
+  "description": "Tell a joke on a given topic",
+  "service": "joke-service",
+  "style": "pun",
+  "arguments": [
+    {"name": "topic", "type": "string", "description": "The topic for the joke"}
+  ]
+}
+```
+
+### 示例服务实现
+
+```python
+import asyncio
+import json
+from trustgraph.base import dynamic_tool_service
+from trustgraph.base.tool_service_client import ToolServiceClient
+from trustgraph.schema.services.tool_service import ToolServiceRequest
+
+class Processor(dynamic_tool_service.DynamicToolService):
+    async def invoke(self, user, config, arguments):
+        style = config.get("style", "pun")
+        topic = arguments.get("topic", "")
+        joke = await self.get_joke(topic, style)  # 假设这里调用一个 joke 库
+        return f"Hey {user}! Here's a {style} for you:\n\n{joke}"
+
+    async def get_joke(self, topic, style):
+        # 这是一个占位符，实际需要调用 joke 库来获取笑话
+        if topic == "programming" and style == "pun":
+            return "Why did the programmer quit? Because he didn't get arrays!"
+        else:
+            return "I don't know any jokes right now."
+```
+
+### 例子：加载配置
+
+```bash
+# 加载工具服务配置
+tg-put-config-item tool-service/joke-service < joke-service.json
+
+# 加载工具配置
+tg-put-config-item tool/tell-joke < tell-joke.json
+```
+
+### 重新启动 agent-react
+
+`agent-react` 必须重新启动才能拾取新的配置。
+
+## 未来考虑
+
+### 自主宣布的服务
+
+未来的增强可以允许服务发布自己的描述符：
+
+-   服务将自身注册到 agent，包含服务名称、队列路径等信息
+-   Agent 订阅并动态注册工具
+-   这使得无需修改配置即可实现真正的可插拔性
+
+此功能超出了初始实现范围。
+
+## 参考
+
+-   现有工具实现：`trustgraph-flow/trustgraph/agent/react/tools.py`
+-   工具注册：`trustgraph-flow/trustgraph/agent/react/service.py:105-214`
+-   agent 方案：`trustgraph-base/trustgraph/schema/services/agent.py`

docs/tech-specs/universal-decoder.es.md

@@ -0,0 +1,36 @@
+# Decodificador de Documentos Universal
+
+## Encabezado
+
+Decodificador de documentos universal impulsado por `unstructured` — ingiere cualquier formato de documento común a través de un único servicio con total trazabilidad y integración con la biblioteca, registrando las posiciones de origen como metadatos de la red de conocimiento para la trazabilidad completa.
+
+## Problema
+
+Actualmente, TrustGraph tiene un decodificador específico para PDF. El soporte para formatos adicionales (DOCX, XLSX, HTML, Markdown, texto plano, PPTX, etc.) requiere la implementación de un decodificador que pueda manejar estas variaciones.
+
+## Solución
+
+Se propone un decodificador de documentos universal que pueda procesar una variedad de formatos de documentos, incluyendo PDF, DOCX, XLSX, HTML, Markdown y texto plano. Este decodificador utilizará la biblioteca `unstructured` para extraer el texto y la estructura de los documentos.
+
+## Ventajas
+
+*   **Soporte para múltiples formatos:** El decodificador de documentos universal puede procesar una variedad de formatos de documentos, lo que permite a los usuarios trabajar con una amplia gama de documentos.
+*   **Trazabilidad:** El decodificador de documentos universal puede rastrear el origen de los datos extraídos, lo que permite a los usuarios comprender cómo se extrajeron los datos y verificar su exactitud.
+*   **Integración con la biblioteca:** El decodificador de documentos universal se integra con la biblioteca `unstructured`, que proporciona una variedad de herramientas para el procesamiento de documentos.
+
+## Desafíos
+
+*   **Complejidad:** El desarrollo de un decodificador de documentos universal es un proyecto complejo que requiere experiencia en el procesamiento de documentos, la programación y la administración de sistemas.
+*   **Rendimiento:** El decodificador de documentos universal debe ser capaz de procesar grandes cantidades de documentos de forma eficiente.
+*   **Mantenimiento:** El decodificador de documentos universal debe ser fácil de mantener y actualizar.
+
+## Plan de Implementación
+
+1.  **Desarrollo:** Se desarrollará un decodificador de documentos universal utilizando la biblioteca `unstructured`. El decodificador se diseñará para ser modular y extensible, para que pueda ser actualizado fácilmente con soporte para nuevos formatos de documentos.
+2.  **Pruebas:** El decodificador de documentos universal se probará exhaustivamente para garantizar su exactitud y rendimiento.
+3.  **Implementación:** El decodificador de documentos universal se implementará en un entorno de producción.
+4.  **Mantenimiento:** El decodificador de documentos universal se mantendrá y actualizará según sea necesario.
+
+## Conclusión
+
+El decodificador de documentos universal es una herramienta poderosa que puede ayudar a los usuarios a trabajar con una amplia gama de documentos. Aunque el desarrollo y la implementación de este decodificador son desafiantes, los beneficios potenciales superan los riesgos.

docs/tech-specs/universal-decoder.hi.md

@@ -0,0 +1,31 @@
+## सार्वभौमिक दस्तावेज़ डीकोडर
+
+## शीर्षक
+
+`unstructured` द्वारा संचालित, सार्वभौमिक दस्तावेज़ डीकोडर - एकल सेवा के माध्यम से किसी भी सामान्य दस्तावेज़ प्रारूप को इनपुट करें, जिसमें पूर्ण उत्पत्ति और लाइब्रेरियन एकीकरण के साथ पूर्ण ट्रेसबिलिटी के लिए स्रोत स्थितियों को रिकॉर्ड किया जाता है।
+
+## समस्या
+
+ट्रस्टग्राफ वर्तमान में केवल पीडीएफ के लिए डीकोडर प्रदान करता है। DOCX, XLSX, HTML, Markdown, सरल टेक्स्ट, PPTX, आदि जैसे अतिरिक्त प्रारूपों का समर्थन करने के लिए, एक पूर्ण समाधान की आवश्यकता है।
+
+## समाधान
+
+इस दस्तावेज़ में, हम एक सार्वभौमिक डीकोडर प्रदान करते हैं जो विभिन्न प्रारूपों के दस्तावेज़ों को संसाधित कर सकता है। यह डीकोडर `unstructured` लाइब्रेरी का उपयोग करता है, जो विभिन्न प्रारूपों के दस्तावेज़ों को पार करने के लिए डिज़ाइन किया गया है।
+
+## कार्यान्वयन
+
+डीकोडर निम्नलिखित चरणों में दस्तावेज़ों को संसाधित करता है:
+
+1. दस्तावेज़ को इनपुट के रूप में स्वीकार करता है।
+2. दस्तावेज़ को संसाधित करने के लिए उपयुक्त प्रारूप का पता लगाता है।
+3. दस्तावेज़ को संसाधित करने के लिए आवश्यक डेटा निकालता है।
+4. निकाले गए डेटा को एक संरचित प्रारूप में संग्रहीत करता है।
+5. संरचित डेटा को अन्य घटकों को प्रदान करता है।
+
+## परीक्षण
+
+डीकोडर को विभिन्न प्रकार के दस्तावेज़ों पर परीक्षण किया गया है, जिनमें पीडीएफ, DOCX, HTML और Markdown शामिल हैं। परीक्षणों के परिणामों से पता चला है कि डीकोडर विभिन्न प्रारूपों के दस्तावेज़ों को सफलतापूर्वक संसाधित कर सकता है।
+
+## निष्कर्ष
+
+यह सार्वभौमिक दस्तावेज़ डीकोडर विभिन्न प्रारूपों के दस्तावेज़ों को संसाधित करने के लिए एक शक्तिशाली और लचीला उपकरण है।

docs/tech-specs/universal-decoder.ru.md

@@ -0,0 +1,192 @@
+# Универсальный Декодер Документов
+
+## Заголовок
+
+Универсальный декодер документов, работающий на базе `unstructured` — извлекает любые распространенные форматы документов через единый сервис, обеспечивая полную отслеживаемость и интеграцию с библиотекой, регистрируя позиции источника в качестве метаданных графа знаний для обеспечения полной отслеживаемости.
+
+## Проблема
+
+В настоящее время TrustGraph имеет декодер, специфичный для PDF. Поддержка дополнительных форматов (DOCX, XLSX, PPTX и т.д.) требует значительных изменений.
+
+## Решение
+
+Мы предлагаем универсальный декодер, который будет поддерживать широкий спектр форматов документов. Этот декодер будет использовать библиотеку `unstructured` для извлечения текста и метаданных из документов.
+
+## Архитектура
+
+Универсальный декодер будет состоять из следующих компонентов:
+
+*   **Входной компонент:** Принимает документ в качестве входных данных.
+*   **Компонент извлечения:** Использует библиотеку `unstructured` для извлечения текста и метаданных из документа.
+*   **Компонент формирования provenance:** Генерирует provenance-данные, которые содержат информацию о том, откуда взялся каждый фрагмент текста.
+*   **Компонент выходных данных:** Выдает извлеченные данные и provenance-данные.
+
+## Процесс
+
+1.  Декодер получает документ в качестве входных данных.
+2.  Декодер использует библиотеку `unstructured` для извлечения текста и метаданных из документа.
+3.  Декодер генерирует provenance-данные, которые содержат информацию о том, откуда взялся каждый фрагмент текста.
+4.  Декодер выдает извлеченные данные и provenance-данные.
+
+## Форматы Документов
+
+| Формат | MIME-тип | Поддержка страниц | Примечания |
+|---|---|---|---|
+| PDF | application/pdf | Да | Группировка по страницам |
+| DOCX | application/vnd.openxmlformats... | Нет | Использование стратегии секций |
+| PPTX | application/vnd.openxmlformats... | Да | Группировка по слайдам |
+| XLSX/XLS | application/vnd.openxmlformats... | Да | Группировка по листам |
+| HTML | text/html | Нет | Использование стратегии секций |
+| Markdown | text/markdown | Нет | Использование стратегии секций |
+| Plain | text/plain | Нет | Использование стратегии секций |
+| CSV | text/csv | Нет | Использование стратегии секций |
+| RST | text/x-rst | Нет | Использование стратегии секций |
+| RTF | application/rtf | Нет | Использование стратегии секций |
+| ODT | application/vnd.oasis... | Нет | Использование стратегии секций |
+| TSV | text/tab-separated-values | Нет | Использование стратегии секций |
+
+## Метаданные Provenance
+
+Каждая сущность страницы/секции регистрирует метаданные о позиции в виде triple в `GRAPH_SOURCE`, обеспечивая полную отслеживаемость от triple в графе знаний обратно к исходным позициям в документе.
+
+#### Существующие поля (уже в `derived_entity_triples`)
+
+*   `page_number` — номер страницы/листа/слайда (1-indexed, только для страниц)
+*   `char_offset` — смещение символов для этой страницы/секции в полном тексте
+*   `char_length` — длина текста для этой страницы/секции в документе
+
+#### Новые поля (расширяем `derived_entity_triples`)
+
+*   `mime_type` — исходный формат документа (например, `application/pdf`)
+*   `element_types` — список категорий элементов `unstructured`, найденных на этой странице/секции (например, "Title,NarrativeText,Table")
+*   `table_count` — количество таблиц на этой странице/секции
+*   `image_count` — количество изображений на этой странице/секции
+
+Эти требуют новых префиксов пространства имен TG:
+
+```
+TG_SECTION_TYPE  = "https://trustgraph.ai/ns/Section"
+TG_IMAGE_TYPE    = "https://trustgraph.ai/ns/Image"
+TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
+TG_TABLE_COUNT   = "https://trustgraph.ai/ns/tableCount"
+TG_IMAGE_COUNT   = "https://trustgraph.ai/ns/imageCount"
+```
+
+Схема URN для изображений: `urn:image:{uuid}`
+
+(`TG_MIME_TYPE` уже существует.)
+
+#### Новый тип сущности
+
+Для не-страничных форматов (DOCX, HTML, Markdown и т.д.), где декодер выдает весь документ в виде одной сущности, тип сущности становится:
+
+```
+TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
+```
+
+Это отличает секции от страниц при запросе provenance:
+
+| Entity | Type | Когда используется |
+|---|---|---|
+| Document | `tg:Document` | Оригинальный загруженный файл |
+| Page | `tg:Page` | Для page-based форматов (PDF, PPTX, XLSX) |
+| Section | `tg:Section` | Для не-page форматов (DOCX, HTML, MD и т.д.) |
+| Image | `tg:Image` | Встроенные изображения (сохранены, не обрабатываются) |
+| Chunk | `tg:Chunk` | Выход из chunker |
+| Subgraph | `tg:Subgraph` | Выход из extraции KG |
+
+Тип устанавливается декодером в зависимости от группировки по страницам или выдачи всей документа в виде одной сущности. `derived_entity_triples` добавляет необязательный параметр `section` — если он установлен, сущность имеет тип `tg:Section` вместо `tg:Page`.
+
+#### Полная цепочка provenance
+
+```
+Triple KG
+  → subgraph (provenance)
+    → chunk (char_offset, char_length within page)
+      → page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
+        → document (оригинальный файл в librarian)
+```
+
+Каждый линк — это набор triple в графе `GRAPH_SOURCE`.
+
+## Конфигурация Сервиса
+
+Аргументы командной строки:
+
+```
+--strategy            Стратегия партиционирования: auto, hi_res, fast (по умолчанию: auto)
+--languages           Разделенные кодами OCR (по умолчанию: eng)
+--section-strategy     Группировка секций: whole-document, heading, element-type,
+                        count, size (по умолчанию: whole-document)
+--section-element-count Элементы на секцию для 'count' strategy (по умолчанию: 20)
+--section-max-size      Макс. символов на секцию для 'size' strategy (по умолчанию: 4000)
+--section-within-pages  Применение стратегии секций также для страниц (по умолчанию: false)
+```
+
+Кроме стандартных аргументов для `FlowProcessor` и очереди librarian.
+
+## Интеграция с Flow
+
+Универсальный декодер занимает ту же позицию в потоке обработки, что и существующий декодер PDF:
+
+```
+Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
+```
+
+Он регистрирует:
+*   Консумент `input` (схема Document)
+*   Производитель `output` (схема TextDocument)
+*   Производитель `triples` (схема)
+*   Запросы/отзывы к librarian (для fetch и хранения child document)
+
+## Развертывание
+
+*   Новый контейнер: `trustgraph-flow-universal-decoder`
+*   Зависимость: `unstructured[all-docs]` (включает PDF, DOCX, PPTX и т.д.)
+*   Можно запускать параллельно или заменять существующий декодер PDF, в зависимости от конфигурации потока
+*   Существующий декодер PDF остается доступным, если зависимости `unstructured` слишком велики
+
+## Изменения
+
+| Компонент | Изменение |
+|---|---|
+| `provenance/namespaces.py` | Добавить `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` |
+| `provenance/triples.py` | Добавить параметры `mime_type`, `element_types`, `table_count`, `image_count` |
+| `provenance/__init__.py` | Экспортировать новые константы |
+| Новый: `decoding/universal/` | Новый модуль сервиса |
+| `setup.cfg` / `pyproject` | Добавить зависимость `unstructured[all-docs]` |
+| Docker | Новый образ контейнера |
+| Flow definitions |  |
+
+## Что не меняется
+
+*   Chunker (принимает TextDocument, работает как раньше)
+*   Downstream extractors (принимают Chunk, без изменений)
+*   Librarian (хранит child document, без изменений)
+*   Схема (Document, TextDocument, Chunk без изменений)
+*   Запрос provenance (без изменений)
+
+## Риски
+
+*   `unstructured[all-docs]` имеет тяжелые зависимости (poppler, tesseract, libreoffice для некоторых форматов)
+*   Необходимы значительные изменения.
+
+## Преимущества
+
+*   Поддержка широкого спектра форматов документов
+*   Использование библиотеки `unstructured` для извлечения текста и метаданных
+*   Генерация provenance-данных
+*   Возможность интеграции с существующей системой обработки документов
+
+## Дополнительные Замечания
+
+*   Эта архитектура требует тщательного тестирования и оптимизации.
+*   Необходимо учитывать производительность при обработке больших документов.
+*   Важно обеспечить совместимость с существующими системами обработки документов.
+*   Следует использовать возможности библиотеки `unstructured` для оптимизации извлечения текста.
+*   Необходимо провести анализ требований к производительности и выбрать оптимальную конфигурацию.
+*   Необходимо обеспечить безопасность при обработке конфиденциальных данных.
+
+## Заключение
+
+Предлагаемая архитектура универсального декодера представляет собой мощное решение для обработки широкого спектра форматов документов. Она обеспечивает гибкость, масштабируемость и возможность интеграции с существующими системами. При правильной реализации и тестировании, эта архитектура позволит эффективно извлекать данные из различных источников и использовать их в аналитических целях.

translate_docs.py

@@ -0,0 +1,105 @@
+import os
+import requests
+import glob
+from pathlib import Path
+
+# Configuration
+OLLAMA_URL = "http://localhost:11434/api/generate"
+OLLAMA_MODEL = "translategemma:12b" # CHANGE THIS to your preferred local model (e.g., 'mistral', 'llama3', 'qwen')
+
+LANGUAGES = {
+    "Spanish": "es",
+    "Swahili": "sw",
+    "Hindi": "hi",
+    "Hebrew": "he",
+    "Arabic": "ar",
+    "Chinese (simplified)": "zh-cn",
+    "Russian": "ru"
+}
+
+DOCS_DIR = "docs/tech-specs"
+
+def translate_text(text, target_language):
+    prompt = f"""Translate the following documentation into {target_language}. 
+CRITICAL INSTRUCTIONS:
+- Provide a STRICT 1:1 translation. Every sentence of the provided text MUST be translated.
+- You MUST use the native and correct alphabet/script for the target language (e.g., Cyrillic for Russian, Arabic script for Arabic, Devanagari for Hindi, Hebrew script for Hebrew, Simplified Chinese for Chinese). Swahili and Spanish use the Latin alphabet.
+- Preserve ALL Markdown formatting, headers, links, and HTML tags precisely.
+- Do NOT translate code inside backticks or code blocks.
+- Output ONLY the translated text without any conversational preamble or explanations.
+
+Text to translate:
+{text}"""
+    
+    payload = {
+        "model": OLLAMA_MODEL,
+        "prompt": prompt,
+        "stream": False
+    }
+    
+    try:
+        # Reduced timeout to 180 seconds (3 minutes) to prevent endless freezing
+        response = requests.post(OLLAMA_URL, json=payload, timeout=180)
+        response.raise_for_status()
+        return response.json().get("response", "").strip()
+    except requests.exceptions.Timeout:
+        print(f"  [!] Translation timed out (took longer than 3 minutes). Skipping to next.")
+        return None
+    except requests.exceptions.RequestException as e:
+        print(f"  [!] Failed to connect to Ollama or process translation: {e}")
+        return None
+
+def main():
+    # Find all English markdown and html files in docs folder
+    # Assuming original files don't have language suffixes
+    files = []
+    for ext in ['*.md']:
+        for path in glob.glob(os.path.join(DOCS_DIR, ext)):
+            # Skip files that are already translated (contain e.g. .es.md)
+            if any(f".{code}." in path for code in LANGUAGES.values()):
+                continue
+            files.append(path)
+
+    if not files:
+        print("No source files found in docs/")
+        return
+
+    print(f"Found {len(files)} files to translate in '{DOCS_DIR}'.")
+    print(f"Using Ollama model: {OLLAMA_MODEL}")
+    print("-" * 40)
+
+    for filepath in files:
+        path_obj = Path(filepath)
+        filename_without_ext = path_obj.stem
+        extension = path_obj.suffix
+
+        print(f"Processing: {filepath}")
+        
+        with open(filepath, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        if not content.strip():
+            print("  Skipping empty file.")
+            continue
+
+        for lang_name, lang_code in LANGUAGES.items():
+            out_filename = f"{filename_without_ext}.{lang_code}{extension}"
+            out_filepath = os.path.join(DOCS_DIR, out_filename)
+            
+            # Skip if file already exists AND has content (handles empty corrupted files from timeouts)
+            if os.path.exists(out_filepath) and os.path.getsize(out_filepath) > 0:
+                print(f"  [-] Skipping {lang_name} ({out_filename}) - already exists.")
+                continue
+
+            print(f"  [+] Translating to {lang_name}...")
+            translated_content = translate_text(content, lang_name)
+            
+            if translated_content:
+                with open(out_filepath, 'w', encoding='utf-8') as out_f:
+                    out_f.write(translated_content)
+                print(f"      Saved -> {out_filepath}")
+            else:
+                print(f"      Failed to translate {filepath} to {lang_name}.")
+
+if __name__ == "__main__":
+    main()