Feat: TrustGraph i18n & Documentation Translation Updates (#781)

Native CLI i18n: The TrustGraph CLI has built-in translation support
that dynamically loads language strings. You can test and use
different languages by simply passing the --lang flag (e.g., --lang
es for Spanish, --lang ru for Russian) or by configuring your
environment's LANG variable.

Automated Docs Translations: This PR introduces autonomously
translated Markdown documentation into several target languages,
including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew,
Arabic, Simplified Chinese, and Russian.

docs/README.api-docs.ar.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: "إنشاء الوثائق تلقائيًا"
+parent: "Arabic (Beta)"
+---
+
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، وعلامات HTML.
+- لا تقم بترجمة الكود الموجود داخل علامات backticks أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+
+# إنشاء الوثائق تلقائيًا
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## وثائق واجهة برمجة تطبيقات 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,53 @@
+---
+layout: default
+title: "Generación automática de documentación"
+parent: "Spanish (Beta)"
+---
+
+# Generación automática de documentación
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 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,53 @@
+---
+layout: default
+title: "יצירת תיעוד אוטומטית"
+parent: "Hebrew (Beta)"
+---
+
+# יצירת תיעוד אוטומטית
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## תיעוד 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,61 @@
+---
+layout: default
+title: "स्वचालित रूप से दस्तावेज़ उत्पन्न करना"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर के कोड का अनुवाद न करें।
+- केवल अनुवादित पाठ प्रस्तुत करें, बिना किसी प्रारंभिक या स्पष्टीकरण के।
+
+अनुवाद करने के लिए पाठ:
+
+# स्वचालित रूप से दस्तावेज़ उत्पन्न करना
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 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.md

@@ -1,3 +1,8 @@
+---
+layout: default
+title: "Auto-generating docs"
+nav_order: 2
+---
 
 # Auto-generating docs
 
@@ -45,4 +50,3 @@ All docstrings follow Google-style format:
 - Example code blocks with proper syntax highlighting
 
 The generated documentation shows the public API exactly as users import it from `trustgraph.api`, without exposing internal module structure.
-

docs/README.api-docs.pt.md

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

docs/README.api-docs.ru.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: "Автоматическое создание документации"
+parent: "Russian (Beta)"
+---
+
+# Автоматическое создание документации
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Документация 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,62 @@
+---
+layout: default
+title: "Kuunda hati moja kwa moja"
+parent: "Swahili (Beta)"
+---
+
+**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
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Ufafanuzi wa API za REST na WebSocket
+
+- `specs/build-docs.sh` - Inaunda hati za REST na WebSocket kutoka kwenye
+  maelezo za OpenAPI na AsyncAPI.
+
+## Ufafanuzi wa API ya Python
+
+Ufafanuzi wa API ya Python unaoandaliwa kutoka kwa maelezo (docstrings) kwa kutumia skripti ya Python inayotumia, ambayo inaangalia pakiti `trustgraph.api`.
+
+### Vigezo
+
+Pakiti ya trustgraph lazima iweze kuagizwa. Ikiwa unatumia mazingira ya utengenezaji:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Kuunda hati
+
+Kutoka kwenye orodha ya hati:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Hii inaunda faili moja ya markdown yenye hati kamili ya API, inayoeleza:
+- Mwongozo wa usanidi na wa kuanza
+- Maelezo za kuagiza kwa kila sinema/aina
+- Maelezo kamili (docstrings) na mifano
+- Orodha ya maudhui iliyopangwa kwa kategoria
+
+### Mtindo wa hati
+
+Maelezo yote (docstrings) yanatumia mtindo wa Google:
+- Muhtasari wa mstari moja
+- Maelezo kamili
+- Kitengo cha "Args" na maelezo ya thamani
+- Kitengo cha "Returns"
+- Kitengo cha "Raises" (kama inatumika)
+- Mistari ya code na umbo sahihi
+
+Hati iliyoundwa inaonyesha API iliyo na umbo, kama watumiaji wanavyoagiza kutoka kwa `trustgraph.api`, bila kuonyesha muundo wa moduli.

docs/README.api-docs.tr.md

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

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

@@ -0,0 +1,53 @@
+---
+layout: default
+title: "自动生成文档"
+parent: "Chinese (Beta)"
+---
+
+# 自动生成文档
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 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,35 @@
+---
+layout: default
+title: "وثائق TrustGraph"
+parent: "Arabic (Beta)"
+---
+
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، ووسوم HTML.
+- لا تترجم أي كود داخل علامات التنصيص المزدوجة أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون أي مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+# وثائق TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+مرحبًا بكم في TrustGraph! للحصول على وثائق شاملة، يرجى زيارة:
+
+## 📖 [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,28 @@
+---
+layout: default
+title: "Documentación de TrustGraph"
+parent: "Spanish (Beta)"
+---
+
+# Documentación de TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+¡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,34 @@
+---
+layout: default
+title: "TrustGraph Documentation"
+parent: "Hebrew (Beta)"
+---
+
+**הוראות חשובות:**
+- שמרו על כל הפורמט של Markdown, כותרות, קישורים ותגי HTML.
+- אל תתרגמו קוד בתוך סימוני backticks או בלוקי קוד.
+- צרו רק את הטקסט המתורגם, ללא הקדמה או הסברים.
+
+טקסט לתרגום:
+# TrustGraph Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+ברוכים הבאים ל-TrustGraph! עבור תיעוד מקיף, אנא בקרו ב:
+
+## 📖 [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,35 @@
+---
+layout: default
+title: "ट्रस्टग्राफ दस्तावेज़"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown स्वरूपण, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैकटिक या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट प्रदान करें, बिना किसी संवाद पूर्व-परिभाषा या स्पष्टीकरण के।
+
+अनुवाद के लिए पाठ:
+# ट्रस्टग्राफ दस्तावेज़
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+ट्रस्टग्राफ में आपका स्वागत है! व्यापक दस्तावेज़ के लिए, कृपया इस पर जाएँ:
+
+## 📖 [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.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "Home"
+nav_order: 1
+---
+
 # TrustGraph Documentation
 
 Welcome to TrustGraph! For comprehensive documentation, please visit:
@@ -18,4 +24,3 @@ The main documentation site includes:
 **Ready to deploy?** Check out the [Deployment Guide](https://docs.trustgraph.ai/deployment).
 
 **Integrating with code?** See the [API Reference](https://docs.trustgraph.ai/reference) for REST, WebSocket, and SDK documentation.
-

docs/README.pt.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "Documentação do TrustGraph"
+parent: "Portuguese (Beta)"
+---
+
+# Documentação do TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Bem-vindo ao TrustGraph! Para documentação completa, visite:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+O site de documentação principal inclui:
+
+**[Visão Geral](https://docs.trustgraph.ai/overview)** - Introdução aos conceitos e arquitetura do TrustGraph
+**[Guias](https://docs.trustgraph.ai/guides)** - Tutoriais passo a passo e guias de como fazer
+**[Implantação](https://docs.trustgraph.ai/deployment)** - Opções de implantação e configuração
+**[Referência](https://docs.trustgraph.ai/reference)** - Especificações da API e documentação da CLI
+
+## Começando
+
+**Novo no TrustGraph?** Comece com a [Visão Geral](https://docs.trustgraph.ai/overview) para entender o sistema.
+
+**Pronto para implantar?** Consulte o [Guia de Implantação](https://docs.trustgraph.ai/deployment).
+
+**Integrando com código?** Consulte a [Referência da API](https://docs.trustgraph.ai/reference) para documentação REST, WebSocket e SDK.

docs/README.ru.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "Документация TrustGraph"
+parent: "Russian (Beta)"
+---
+
+# Документация TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Добро пожаловать в TrustGraph! Для получения исчерпывающей документации, пожалуйста, посетите:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Основной сайт документации включает:
+
+- **[Обзор](https://docs.trustgraph.ai/overview)** - Введение в концепции и архитектуру TrustGraph
+- **[Руководства](https://docs.trustgraph.ai/guides)** - Пошаговые руководства и инструкции
+- **[Развертывание](https://docs.trustgraph.ai/deployment)** - Варианты развертывания и конфигурация
+- **[Справочник](https://docs.trustgraph.ai/reference)** - Спецификации API и документация CLI
+
+## Начало работы
+
+**Вы новичок в TrustGraph?** Начните с [Обзора](https://docs.trustgraph.ai/overview), чтобы понять систему.
+
+**Готовы к развертыванию?** Обратитесь к [Руководству по развертыванию](https://docs.trustgraph.ai/deployment).
+
+**Интеграция с кодом?** Посмотрите [Справочник по API](https://docs.trustgraph.ai/reference) для документации REST, WebSocket и SDK.

docs/README.sw.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "Miongozo ya TrustGraph"
+parent: "Swahili (Beta)"
+---
+
+# Miongozo ya TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Karibu kwenye TrustGraph! Kwa miongozo kamili, tafadhali tembelea:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Tovuti kuu ya miongozo inajumuisha:
+
+**[Mawasilisho](https://docs.trustgraph.ai/overview)** - Utangulizi wa dhana na muundo wa TrustGraph
+**[Mwongozo](https://docs.trustgraph.ai/guides)** - Mafunzo ya hatua kwa hatua na mwongozo wa jinsi ya
+**[Ufungaji](https://docs.trustgraph.ai/deployment)** - Chaguo za ufungaji na usanidi
+**[Marejeleo](https://docs.trustgraph.ai/reference)** - Vipimo vya API na miongozo ya CLI
+
+## Kuanza
+
+**Je, wewe ni mpya katika TrustGraph?** Anza na [Mawasilisho](https://docs.trustgraph.ai/overview) ili kuelewa mfumo.
+
+**Uko tayari kufunga?** Angalia [Mwongozo wa Ufungaji](https://docs.trustgraph.ai/deployment).
+
+**Je, unataka kuunganisha na programu?** Angalia [Marejeleo ya API](https://docs.trustgraph.ai/reference) kwa miongozo ya REST, WebSocket, na SDK.

docs/README.tr.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "TrustGraph Belgeleri"
+parent: "Turkish (Beta)"
+---
+
+# TrustGraph Belgeleri
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+TrustGraph'a hoş geldiniz! Kapsamlı belgeler için lütfen şu adresi ziyaret edin:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+Ana belge sitesi şunları içerir:
+
+**[Genel Bakış](https://docs.trustgraph.ai/overview)** - TrustGraph kavramlarına ve mimarisine giriş
+**[Kılavuzlar](https://docs.trustgraph.ai/guides)** - Adım adım eğitimler ve nasıl yapılır kılavuzları
+**[Dağıtım](https://docs.trustgraph.ai/deployment)** - Dağıtım seçenekleri ve yapılandırma
+**[Referans](https://docs.trustgraph.ai/reference)** - API özellikleri ve CLI belgeleri
+
+## Başlangıç
+
+**TrustGraph'e yeni mi geldiniz?** Sistemi anlamak için [Genel Bakış](https://docs.trustgraph.ai/overview) bölümüne bakın.
+
+**Dağıtıma hazır mısınız?** [Dağıtım Kılavuzu](https://docs.trustgraph.ai/deployment) bölümüne göz atın.
+
+**Koduyla entegre mi olmak istiyorsunuz?** REST, WebSocket ve SDK belgeleri için [API Referansı](https://docs.trustgraph.ai/reference) bölümüne bakın.

docs/README.zh-cn.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "TrustGraph 文档"
+parent: "Chinese (Beta)"
+---
+
+# TrustGraph 文档
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+欢迎使用 TrustGraph！为了获得全面的文档，请访问：
+
+## 📖 [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,108 @@
+---
+layout: default
+title: "تغييرات في واجهة برمجة التطبيقات: v1.8 إلى v2.1"
+parent: "Arabic (Beta)"
+---
+
+# تغييرات في واجهة برمجة التطبيقات: v1.8 إلى v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## ملخص
+
+حصلت واجهة برمجة التطبيقات على مُسِير خدمات 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,108 @@
+---
+layout: default
+title: "Cambios en el API Gateway: v1.8 a v2.1"
+parent: "Spanish (Beta)"
+---
+
+# Cambios en el API Gateway: v1.8 a v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 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,106 @@
+---
+layout: default
+title: "שינויים ב-API Gateway: v1.8 ל-v2.1"
+parent: "Hebrew (Beta)"
+---
+
+# שינויים ב-API Gateway: v1.8 ל-v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## תקציר
+
+ה-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,108 @@
+---
+layout: default
+title: "Api Gateway Changes V1.8 To V2.1.Hi"
+parent: "Hindi (Beta)"
+---
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## API गेटवे में बदलाव: v1.8 से v2.1
+
+## सारांश
+
+API गेटवे में एम्बेडिंग प्रश्नों के लिए नए WebSocket सेवा डिस्पैचर, दस्तावेज़ सामग्री के लिए एक नया REST स्ट्रीमिंग एंडपॉइंट, और `Value` से `Term` में एक महत्वपूर्ण वायर प्रारूप परिवर्तन शामिल है। "ऑब्जेक्ट्स" सेवा को "रो" के रूप में पुनः नाम दिया गया।
+
+---
+
+## नए WebSocket सेवा डिस्पैचर
+
+ये `/api/v1/socket` पर उपलब्ध नए अनुरोध/प्रतिक्रिया सेवाएँ हैं (फ्लो-स्कोप):
+
+| सेवा कुंजी | विवरण |
+|---|---|
+| `document-embeddings` | टेक्स्ट समानता के आधार पर दस्तावेज़ टुकड़ों के लिए क्वेरी करता है। अनुरोध/प्रतिक्रिया `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse` स्कीमा का उपयोग करते हैं। |
+| `row-embeddings` | इंडेक्स किए गए फ़ील्ड में टेक्स्ट समानता के आधार पर संरचित डेटा पंक्तियों के लिए क्वेरी करता है। अनुरोध/प्रतिक्रिया `RowEmbeddingsRequest`/`RowEmbeddingsResponse` स्कीमा का उपयोग करते हैं। |
+
+ये मौजूदा `graph-embeddings` डिस्पैचर (जो पहले से ही v1.8 में मौजूद है, लेकिन अपडेट किया जा सकता है) के साथ जुड़ते हैं।
+
+### WebSocket फ़्लो सेवा डिस्पैचर की पूरी सूची (v2.1)
+
+अनुरोध/प्रतिक्रिया सेवाएँ (`/api/v1/flow/{flow}/service/{kind}` या WebSocket मक्स) के माध्यम से:
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## नया REST एंडपॉइंट
+
+| विधि | पथ | विवरण |
+|---|---|---|
+| `GET` | `/api/v1/document-stream` | लाइब्रेरी से मूल बाइट के रूप में दस्तावेज़ सामग्री स्ट्रीम करता है। क्वेरी पैरामीटर: `user` (आवश्यक), `document-id` (आवश्यक), `chunk-size` (वैकल्पिक, डिफ़ॉल्ट 1MB)। आंतरिक रूप से base64 से डिकोड करके दस्तावेज़ सामग्री को chunked transfer encoding में लौटाता है। |
+
+---
+
+## पुनः नामकरण की गई सेवा: "objects" से "rows"
+
+| v1.8 | v2.1 | नोट्स |
+|---|---|---|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | `ObjectsQueryRequest`/`ObjectsQueryResponse` से `RowsQueryRequest`/`RowsQueryResponse` स्कीमा में बदलाव। |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | संरचित डेटा के लिए आयात डिस्पैचर। |
+
+WebSocket सेवा कुंजी `"objects"` से `"rows"` में बदल गई है, और आयात डिस्पैचर कुंजी `"objects"` से `"rows"` में बदल गई है।
+
+---
+
+## वायर प्रारूप में बदलाव: Value से Term
+
+`serialize.py` में serialization लेयर को नए `Term` प्रकार का उपयोग करने के लिए फिर से लिखा गया है, बजाय पुराने `Value` प्रकार का।
+
+### पुराना प्रारूप (v1.8 — `Value`)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: मान (स्ट्रिंग)
+- `e`: एक बूलियन ध्वज जो दर्शाता है कि मान एक URI है या नहीं
+
+### नया प्रारूप (v2.1 — `Term`)
+
+IRI:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+प्रत्यक्ष:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+कोटेड ट्रिपल (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: प्रकार डिस्‍क्रिमिनेटर — `"i"` (IRI), `"l"` (प्रत्यक्ष), `"r"` (कोटेड ट्रिपल), `"b"` (ब्लैंक नोड)
+- serialization अब `trustgraph.messaging.translators.primitives` से `TermTranslator` और `TripleTranslator` को सौंपता है।
+
+### अन्य serialization में बदलाव
+
+| फ़ील्ड | v1.8 | v2.1 |
+|---|---|---|
+| मेटाडेटा | `metadata.metadata` (उप-ग्राफ) | `metadata.root` (सरल मान) |
+| ग्राफ एम्बेडिंग इकाई | `entity.vectors` (बहु) | `entity.vector` (एकल) |
+| दस्तावेज़ एम्बेडिंग टुकड़ा | `chunk.vectors` + `chunk.chunk` (टेक्स्ट) | `chunk.vector` + `chunk.chunk_id` (आईडी संदर्भ) |
+
+---
+
+## महत्वपूर्ण बदलाव
+
+- **`Value` से `Term` वायर प्रारूप**: गेटवे के माध्यम से ट्रिपल, एम्बेडिंग या इकाई संदर्भ भेजने/प्राप्त करने वाले सभी क्लाइंट को नए Term प्रारूप के साथ अपडेट करना होगा।
+- **`objects` से `rows` का नामकरण**: WebSocket सेवा कुंजी और आयात कुंजी में बदलाव।
+- **मेटाडेटा फ़ील्ड में बदलाव**: `metadata.metadata` (एक serialized उप-ग्राफ) को `metadata.root` (एक सरल मान) से बदला गया।
+- **एम्बेडिंग फ़ील्ड में बदलाव**: `vectors` (बहु) को `vector` (एकल) से बदला गया; दस्तावेज़ एम्बेडिंग अब `chunk_id` को संदर्भित करती हैं, बजाय inline `chunk` टेक्स्ट के।
+- **नया `/api/v1/document-stream` एंडपॉइंट**: यह एक अतिरिक्त परिवर्तन है, जो पहले से ही मौजूद है।

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

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

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

@@ -0,0 +1,108 @@
+---
+layout: default
+title: "Изменения в API Gateway: v1.8 до v2.1"
+parent: "Russian (Beta)"
+---
+
+# Изменения в API Gateway: v1.8 до v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Обзор
+
+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,114 @@
+---
+layout: default
+title: "Mabadiliko ya API Gateway: v1.8 hadi v2.1"
+parent: "Swahili (Beta)"
+---
+
+**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
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Muhtasari
+
+API gateway imepata mpya wa huduma za WebSocket kwa ajili ya majabuzi, kiungo cha mpya cha REST kwa maudhui, na imepitia mabadiliko muhimu katika muundo wa data kutoka `Value` hadi `Term`. Huduma "objects" imebadilishwa na "rows".
+
+---
+
+## Wengine Wepya wa Huduma za WebSocket
+
+Hizi ni huduma mpya za ombi/majibu zinazopatikana kupitia multiplexer ya WebSocket katika `/api/v1/socket` (na msingi wa "flow"):
+
+| Key ya Huduma | Maelezo |
+|-------------|-------------|
+| `document-embeddings` | Inatafuta sehemu za hati kwa utofauti wa maandishi. Ombi/majibu hutumia miundo `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse`. |
+| `row-embeddings` | Inatafuta data iliyoandaliwa kwa utofauti wa maandishi kwenye majina iliyosawazwa. Ombi/majibu hutumia miundo `RowEmbeddingsRequest`/`RowEmbeddingsResponse`. |
+
+Hizi zinaunganishwa na `graph-embeddings` iliyopo tayari katika v1.8, lakini inaweza kuwa imeboreshwa.
+
+### Orodha kamili ya huduma za WebSocket (v2.1)
+
+Huduma za ombi/majibu (kupitia `/api/v1/flow/{flow}/service/{kind}` au WebSocket mux):
+
+- `agent`, `text-completion`, `prompt`, `mcp-tool`
+- `graph-rag`, `document-rag`
+- `embeddings`, `graph-embeddings`, `document-embeddings`
+- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag`
+- `row-embeddings`
+
+---
+
+## Kiungo cha REST cha Mpya
+
+| Njia | Path | Maelezo |
+|--------|------|-------------|
+| `GET` | `/api/v1/document-stream` | Inatoa maudhui ya hati kutoka kwenye makala kama data ya msingi. Parametari za ombi: `user` (lazima), `document-id` (lazima), `chunk-size` (bora, chaguo, 1MB). Inarudisha maudhui ya hati kama data iliyobadilishwa, na inatumia teknolojia ya "chunked transfer encoding" ya base64. |
+
+---
+
+## Huduma iliyobadilishwa: "objects" hadi "rows"
+
+| v1.8 | v2.1 | Maelezo |
+|------|------|-------|
+| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Muundo umebadilishwa kutoka `ObjectsQueryRequest`/`ObjectsQueryResponse` hadi `RowsQueryRequest`/`RowsQueryResponse`. |
+| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Huduma ya import kwa data iliyoandaliwa. |
+
+Key ya huduma ya WebSocket imebadilishwa kutoka "objects" hadi "rows", na key ya import pia imebadilishwa.
+
+---
+
+## Mabadiliko ya Muundo: Value hadi Term
+
+Sura ya usimamizaji (`serialize.py`) imeandikwa upya ili kutumia aina mpya ya "Term" badala ya aina ya "Value" iliyokuwa.
+
+### Sura ya awali (v1.8 — Value)
+
+```json
+{"v": "http://example.org/entity", "e": true}
+```
+
+- `v`: thamani (string)
+- `e`: bendera ya booleani inayoeleza kama thamani ni URI
+
+### Sura mpya (v2.1 — Term)
+
+IRIs:
+```json
+{"t": "i", "i": "http://example.org/entity"}
+```
+
+Literals:
+```json
+{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"}
+```
+
+Triple za mlangano (RDF-star):
+```json
+{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}}
+```
+
+- `t`: makazi - `"i"` (URI), `"l"` (thamini), `"r"` (triple), `"b"` (blank node)
+- Usimamizi sasa unaendeleza kwa `TermTranslator` na `TripleTranslator` kutoka `trustgraph.messaging.translators.primitives`
+
+### Mabadiliko mengine ya usimamizaji
+
+| Kipa | v1.8 | v2.1 |
+|-------|------|------|
+| Metadata | `metadata.metadata` (subgraph) | `metadata.root` (thamini rahisi) |
+| Graph embeddings entity | `entity.vectors` (pl) | `entity.vector` (singular) |
+| Document embeddings chunk | `chunk.vectors` + `chunk.chunk` (text) | `chunk.vector` + `chunk.chunk_id` (ID reference) |
+
+---
+
+## Mabadiliko Muhimu
+
+- **Muundo Value hadi Term**: Wote wa wateja wanaotumia nakala, ujumizi, au maudhui wanapaswa kubadilishwa kwa muundo mpya wa Term.
+- **"objects" hadi "rows"**: Key ya huduma na key ya import zimebadilishwa.
+- **Mabadiliko ya key ya Metadata**: `metadata.metadata` (subgraph iliyosimamizwa) imebadilishwa na `metadata.root` (thamini rahisi).
+- **Mabadiliko ya key ya Embeddings**: `vectors` (plural) imebadilishwa na `vector` (singular); ujumizi wa hati sasa inaangalia `chunk_id` badala ya "chunk" ya msingi.
+- **Kiungo cha mpya `/api/v1/document-stream`**: Haiathiri.

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

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

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

@@ -0,0 +1,108 @@
+---
+layout: default
+title: "API 网关变更：v1.8 到 v2.1"
+parent: "Chinese (Beta)"
+---
+
+# API 网关变更：v1.8 到 v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 摘要
+
+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,119 @@
+---
+layout: default
+title: "تغييرات واجهة سطر الأوامر: من v1.8 إلى v2.1"
+parent: "Arabic (Beta)"
+---
+
+# تغييرات واجهة سطر الأوامر: من v1.8 إلى v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## ملخص
+
+تمت إضافة العديد من الميزات إلى واجهة سطر الأوامر (`trustgraph-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,120 @@
+---
+layout: default
+title: "Cambios en la CLI: v1.8 a v2.1"
+parent: "Spanish (Beta)"
+---
+
+# Cambios en la CLI: v1.8 a v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 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,119 @@
+---
+layout: default
+title: "שינויים ב-CLI: מ-v1.8 ל-v2.1"
+parent: "Hebrew (Beta)"
+---
+
+# שינויים ב-CLI: מ-v1.8 ל-v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## סיכום
+
+ה-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,119 @@
+---
+layout: default
+title: "CLI में परिवर्तन: v1.8 से v2.1"
+parent: "Hindi (Beta)"
+---
+
+# CLI में परिवर्तन: v1.8 से v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## सारांश
+
+CLI (`trustgraph-cli`) में तीन मुख्य क्षेत्रों पर ध्यान केंद्रित किए गए महत्वपूर्ण परिवर्धन शामिल हैं:
+**व्याख्यात्मकता/उत्पत्ति, एम्बेडिंग एक्सेस, और ग्राफ़ क्वेरी।**
+दो पुरानी उपकरण हटा दिए गए थे, एक का नाम बदल दिया गया, और कई मौजूदा उपकरणों में नई क्षमताएं जोड़ी गईं।
+
+---
+
+## नए CLI उपकरण
+
+### व्याख्यात्मकता और उत्पत्ति
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-list-explain-traces` | एक संग्रह में सभी व्याख्या सत्रों (GraphRAG और एजेंट) की सूची, जिसमें सत्र आईडी, प्रकार, प्रश्न पाठ और टाइमस्टैम्प शामिल हैं। |
+| `tg-show-explain-trace` | किसी सत्र के लिए पूरी व्याख्यात्मक ट्रेस प्रदर्शित करता है। GraphRAG के लिए: प्रश्न, खोज, ध्यान केंद्रित, संश्लेषण चरण। एजेंट के लिए: सत्र, पुनरावृत्तियाँ (सोच/क्रिया/अवलोकन), अंतिम उत्तर। स्वचालित रूप से ट्रेस प्रकार का पता लगाता है। `--show-provenance` का उपयोग करके स्रोत दस्तावेजों तक किनारों को ट्रेस करने का समर्थन करता है। |
+| `tg-show-extraction-provenance` | एक दस्तावेज़ आईडी दिए जाने पर, `prov:wasDerivedFrom` संबंधों का उपयोग करके उत्पत्ति श्रृंखला को पार करता है: दस्तावेज़ -> पृष्ठ -> खंड -> किनारे। `--show-content` और `--max-content` विकल्पों का समर्थन करता है। |
+
+### एम्बेडिंग
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-invoke-embeddings` | एम्बेडिंग सेवा के माध्यम से टेक्स्ट को वेक्टर एम्बेडिंग में परिवर्तित करता है। एक या अधिक टेक्स्ट इनपुट स्वीकार करता है, और फ़्लोट की सूची के रूप में वेक्टर लौटाता है। |
+| `tg-invoke-graph-embeddings` | वेक्टर एम्बेडिंग का उपयोग करके ग्राफ संस्थाओं को क्वेरी करता है। मिलान संस्थाओं और समानता स्कोर लौटाता है। |
+| `tg-invoke-document-embeddings` | वेक्टर एम्बेडिंग का उपयोग करके दस्तावेज़ खंडों को क्वेरी करता है। मिलान खंड आईडी और समानता स्कोर लौटाता है। |
+| `tg-invoke-row-embeddings` | इंडेक्स किए गए फ़ील्ड पर टेक्स्ट समानता का उपयोग करके संरचित डेटा पंक्तियों को क्वेरी करता है। मिलान पंक्तियों और स्कोर लौटाता है। `--schema-name` और `--index-name` का समर्थन करता है। |
+
+### ग्राफ़ क्वेरी
+
+| कमांड | विवरण |
+|---------|-------------|
+| `tg-query-graph` | पैटर्न-आधारित ट्रिपल स्टोर क्वेरी। `tg-show-graph` (जो सब कुछdumps करता है) के विपरीत, यह किसी भी संयोजन के विषय, विधेय, वस्तु और ग्राफ़ द्वारा चयनशील क्वेरी की अनुमति देता है। स्वचालित रूप से मूल्य प्रकार का पता लगाता है: IRI (`http://...`, `urn:...`, `<...>`), उद्धृत ट्रिपल (`<<s p o>>`), और अक्षर। |
+| `tg-get-document-content` | लाइब्रेरी से दस्तावेज़ आईडी द्वारा दस्तावेज़ सामग्री प्राप्त करता है। फ़ाइल या stdout पर आउटपुट कर सकता है, और टेक्स्ट और बाइनरी सामग्री दोनों को संभालता है। |
+
+---
+
+## हटाए गए CLI उपकरण
+
+| कमांड | नोट्स |
+|---------|-------|
+| `tg-load-pdf` | हटा दिया गया। दस्तावेज़ लोडिंग अब लाइब्रेरी/प्रसंस्करण पाइपलाइन के माध्यम से संभाली जाती है। |
+| `tg-load-text` | हटा दिया गया। दस्तावेज़ लोडिंग अब लाइब्रेरी/प्रसंस्करण पाइपलाइन के माध्यम से संभाली जाती है। |
+
+---
+
+## नाम बदले गए CLI उपकरण
+
+| पुराना नाम | नया नाम | नोट्स |
+|----------|----------|-------|
+| `tg-invoke-objects-query` | `tg-invoke-rows-query` | संरचित डेटा के लिए "ऑब्जेक्ट" से "पंक्ति" के शब्दावली में बदलाव को दर्शाता है। |
+
+---
+
+## मौजूदा उपकरणों में महत्वपूर्ण परिवर्तन
+
+### `tg-invoke-graph-rag`
+
+- **व्याख्यात्मकता समर्थन**: 4-चरण व्याख्यात्मक पाइपलाइन (प्रश्न, ग्राउंडिंग/खोज, ध्यान केंद्रित, संश्लेषण) का समर्थन करता है जिसमें इनलाइन उत्पत्ति घटना प्रदर्शन भी शामिल है।
+- **स्ट्रीमिंग**: वास्तविक समय के आउटपुट के लिए WebSocket स्ट्रीमिंग का उपयोग करता है।
+- **उत्पत्ति ट्रेसिंग**: पुनरावर्तन और `prov:wasDerivedFrom` श्रृंखलाओं के माध्यम से चयनित किनारों को स्रोत दस्तावेजों तक ट्रेस कर सकता है।
+- ~30 पंक्तियों से ~760 पंक्तियों तक बढ़ गया है ताकि पूरे व्याख्यात्मक पाइपलाइन को समायोजित किया जा सके।
+
+### `tg-invoke-document-rag`
+
+- **व्याख्यात्मकता समर्थन**: `question_explainable()` मोड जोड़ा गया जो दस्तावेज़ RAG प्रतिक्रियाओं को इनलाइन उत्पत्ति घटनाओं (प्रश्न, ग्राउंडिंग, खोज, संश्लेषण चरण) के साथ प्रवाहित करता है।
+
+### `tg-invoke-agent`
+
+- **व्याख्यात्मकता समर्थन**: `question_explainable()` मोड जोड़ा गया जो एजेंट निष्पादन के दौरान इनलाइन उत्पत्ति घटनाओं (प्रश्न, विश्लेषण, निष्कर्ष, एजेंटसोच, एजेंटअवलोकन, एजेंटउत्तर) को प्रदर्शित करता है।
+- वर्बोस मोड में, इमोजी उपसर्ग के साथ सोच/अवलोकन धाराओं को दिखाया जाता है।
+
+### `tg-show-graph`
+
+- **स्ट्रीमिंग मोड**: `triples_query_stream()` का उपयोग करता है जिसमें कम समय-से-पहले-परिणाम और कम मेमोरी ओवरहेड के लिए कॉन्फ़िगरेबल बैच आकार होते हैं।
+- **नाम वाले ग्राफ़ समर्थन**: नया `--graph` फ़िल्टर विकल्प। निम्नलिखित नाम वाले ग्राफ़ को पहचानता है:
+  - डिफ़ॉल्ट ग्राफ़ (खाली): मुख्य ज्ञान तथ्य
+  - `urn:graph:source`: निष्कर्षण उत्पत्ति
+  - `urn:graph:retrieval`: क्वेरी-समय व्याख्यात्मकता
+- **ग्राफ़ कॉलम दिखाना**: `--show-graph` ध्वज जोड़ा गया।
+- **कॉन्फ़िगरेबल सीमाएँ**: नए `--limit` और `--batch-size` विकल्प।
+
+### `tg-graph-to-turtle`
+
+- **RDF-स्टार समर्थन**: उद्धृत ट्रिपल (RDF-स्टार पुनरावर्तन) को संभालता है।
+- **स्ट्रीमिंग मोड**: कम समय-से-पहले-प्रसंस्करण के लिए स्ट्रीमिंग का उपयोग करता है।
+- **वायर फॉर्मेट हैंडलिंग**: नई वायर फॉर्मेट (`{"t": "i", "i": uri}` के लिए IRI, `{"t": "l", "v": value}` के लिए अक्षर, `{"t": "r", "r": {...}}` के लिए उद्धृत ट्रिपल) का उपयोग करने के लिए अपडेट किया गया है।
+- **नाम वाले ग्राफ़ समर्थन**: नया `--graph` फ़िल्टर विकल्प।
+
+### `tg-set-tool`
+
+- **नया उपकरण प्रकार**: संरचित डेटा सूचकांकों पर अर्थपूर्ण खोज के लिए `row-embeddings-query`।
+- **नया विकल्प**: संरचित डेटा क्वेरी टूल के लिए `--schema-name`, `--index-name`, `--limit` विकल्प जोड़े गए।
+
+### `tg-show-tools`
+
+- `row-embeddings-query` के नए उपकरण प्रकार और उसके `schema-name`, `index-name` और `limit` फ़ील्ड को प्रदर्शित करता है।
+
+### `tg-load-knowledge`
+
+- **प्रगति रिपोर्टिंग**: प्रत्येक फ़ाइल और कुल में लोड किए गए ट्रिपल और संस्था संदर्भों की गणना और रिपोर्ट करता है।
+- **टर्म फॉर्मेट अपडेट**: संस्था संदर्भ अब नए टर्म फॉर्मेट (`{"t": "i", "i": uri}`) का उपयोग करते हैं, जबकि पुराने मूल्य फॉर्मेट (`{"v": entity, "e": True}`) का उपयोग किया जाता था।
+
+---
+
+## ब्रेकिंग परिवर्तन
+
+- **शब्दावली का नाम बदलना**: `Value` स्कीम को पूरे सिस्टम में `Term` नाम दिया गया है (PR #622)। यह CLI टूल के लिए जो ग्राफ स्टोर के साथ इंटरैक्ट करते हैं, उनके वायर फॉर्मेट को प्रभावित करता है। नया फॉर्मेट `{"t": "i", "i": uri}` IRI के लिए और `{"t": "l", "v": value}` अक्षर के लिए, पिछले `{"v": ..., "e": ...}` फॉर्मेट के स्थान पर उपयोग करता है।
+- **`tg-invoke-objects-query` को `tg-invoke-rows-query` में नाम बदला गया**।
+- **`tg-load-pdf` और `tg-load-text` हटा दिए गए**।

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

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

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

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

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

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

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

@@ -0,0 +1,119 @@
+---
+layout: default
+title: "CLI 修改：v1.8 到 v2.1"
+parent: "Chinese (Beta)"
+---
+
+# CLI 修改：v1.8 到 v2.1
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 摘要
+
+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,16 @@
+---
+layout: default
+title: "اتفاقية الترخيص للمساهمين"
+parent: "Arabic (Beta)"
+---
+
+# اتفاقية الترخيص للمساهمين
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+نطلب من كل المساهمين التوقيع على اتفاقية الترخيص للمساهمين قبل أن نتمكن من دمج طلب السحب. لا تنقل اتفاقية الترخيص حقوق الطبع والنشر - أنت تحتفظ بالملكية الكاملة لعملك. إنها ببساطة تمنح مشروع TrustGraph ترخيصًا دائمًا، وخاليًا من الرسوم، لتوزيع مساهمتك بموجب ترخيص [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,16 @@
+---
+layout: default
+title: "Acuerdo de Licencia para Contribuyentes"
+parent: "Spanish (Beta)"
+---
+
+# Acuerdo de Licencia para Contribuyentes
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+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,16 @@
+---
+layout: default
+title: "הסכם רישיון לתורמים"
+parent: "Hebrew (Beta)"
+---
+
+# הסכם רישיון לתורמים
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+אנו מבקשים מכל תורם לחתום על הסכם רישיון לתורמים לפני שנוכל לשלב בקשת פול. ההסכם **אינו** מעביר זכויות יוצרים – אתם שומרים על בעלות מלאה על עבודתכם. הוא פשוט מעניק לפרויקט TrustGraph רישיון נצחי, ללא תמלוגים, להפצת התרומה שלכם על פי הרישיון [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,24 @@
+---
+layout: default
+title: "योगदानकर्ता लाइसेंस समझौता (CLA)"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बनाए रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट को ही आउटपुट करें, जिसमें कोई भी प्रारंभिक या स्पष्टीकरण शामिल न हों।
+
+अनुवाद करने के लिए पाठ:
+
+# योगदानकर्ता लाइसेंस समझौता (CLA)
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+हम हर योगदानकर्ता से एक योगदानकर्ता लाइसेंस समझौते पर हस्ताक्षर करने का अनुरोध करते हैं, इससे पहले कि हम किसी पुल अनुरोध को मर्ज कर सकें। 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.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "Contributor Licence Agreement (CLA)"
+nav_order: 4
+---
+
 # Contributor Licence Agreement (CLA)
 
 We ask every contributor to sign a Contributor Licence Agreement before
@@ -16,4 +22,3 @@ and you only need to do it once across all TrustGraph repositories.
 
 - Contributing as an **individual**? Sign the [Individual CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
 - Contributing on behalf of a **company or organisation**? Sign the [Entity CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)
-

docs/contributor-licence-agreement.pt.md

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

docs/contributor-licence-agreement.ru.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "Договор лицензии для вкладчиков"
+parent: "Russian (Beta)"
+---
+
+# Договор лицензии для вкладчиков
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Мы требуем, чтобы каждый вкладчик подписал Договор лицензии для вкладчиков, прежде чем мы сможем принять ваш запрос на слияние. Договор лицензии **не** передаёт авторские права — вы сохраняете полное право собственности на свою работу. Он просто предоставляет проекту TrustGraph пожизненную, без роялти лицензию на распространение вашего вклада в соответствии с лицензией [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,24 @@
+---
+layout: default
+title: "Mkataba wa Lisensi wa Mhudumu (CLA)"
+parent: "Swahili (Beta)"
+---
+
+**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)
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Tunatoa ombi kwa kila mhudumu kusaini Mkataba wa Lisensi wa Mhudumu kabla
+tunaweza kuingiza ombi la "pull". Mkataba huu **sisi** huhamisha haki za udani —
+unaendelea kuwa mmiliki kamili wa kazi yako. Hii kwa upande wake huipa Mradi wa TrustGraph lisensi ya kudumu, bila malipo, ya kusambaza mchango wako chini ya lisensi ya [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), na ina hakikisha kuwa una haki ya kufanya mchango. Hii inalinda kila mmoja, mradi na watumiaji, kwa kuhakikisha kwamba kila mchango una msingi wa kisheria.
+
+Unapouingiza ombi la "pull", bot ya CLA italeta maoni ya kukuelekeza kukagua na kusaini mkataba unaofaa— hili lina kuchukua tu dakika nadra, na unahitaji kufanya hivyo mara moja kwenye lahat ya TrustGraph.
+
+- Kichango kama **mshiriki binafsi**? Saini [Mkataba wa Lisensi wa Mshiriki](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- Kichango kwa niaba ya **kampuni au shirika**? Saini [Mkataba wa Lisensi wa Shirika](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.tr.md

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

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

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "贡献者许可协议 (CLA)"
+parent: "Chinese (Beta)"
+---
+
+# 贡献者许可协议 (CLA)
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+我们要求所有贡献者在合并拉取请求之前签署贡献者许可协议。该协议**不**会转移版权——您仍然拥有您的作品的全部所有权。它仅授予 TrustGraph 项目一项永久、免版税的使用许可，以在项目的 [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/lang-index-ar.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Arabic (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Arabic (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-es.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Spanish (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Spanish (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-he.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Hebrew (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Hebrew (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-hi.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Hindi (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Hindi (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-pt.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Portuguese (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Portuguese (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-ru.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Russian (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Russian (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-sw.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Swahili (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Swahili (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-tr.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Turkish (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Turkish (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/lang-index-zh-cn.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: "Chinese (Beta)"
+has_children: true
+nav_order: 99
+---
+
+# Chinese (Beta) Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

docs/python-api.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "TrustGraph Python API Reference"
+nav_order: 5
+---
+
 # TrustGraph Python API Reference
 
 ## Installation
@@ -3569,4 +3575,3 @@ Base class for all TrustGraph service errors
 
 
 ---
-

docs/tech-specs/__TEMPLATE.ar.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: "المواصفات الفنية لتحميل المعرفة من سطر الأوامر"
+parent: "Arabic (Beta)"
+---
+
+# المواصفات الفنية لتحميل المعرفة من سطر الأوامر
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## نظرة عامة
+
+تصف هذه المواصفة واجهات سطر الأوامر لتحميل المعرفة إلى TrustGraph، مما يمكّن المستخدمين من استيراد البيانات من مصادر مختلفة من خلال أدوات سطر الأوامر. تدعم هذه التكامل أربع حالات استخدام رئيسية:
+
+1. **[حالة الاستخدام 1]**: [الوصف]
+2. **[حالة الاستخدام 2]**: [الوصف]
+3. **[حالة الاستخدام 3]**: [الوصف]
+4. **[حالة الاستخدام 4]**: [الوصف]
+
+## الأهداف
+
+- **[الهدف 1]**: [الوصف]
+- **[الهدف 2]**: [الوصف]
+- **[الهدف 3]**: [الوصف]
+- **[الهدف 4]**: [الوصف]
+- **[الهدف 5]**: [الوصف]
+- **[الهدف 6]**: [الوصف]
+- **[الهدف 7]**: [الوصف]
+- **[الهدف 8]**: [الوصف]
+
+## الخلفية
+
+[صف الحالة الحالية والقيود التي تعالجها هذه المواصفة]
+
+تشمل القيود الحالية:
+- [القيد 1]
+- [القيد 2]
+- [القيد 3]
+- [القيد 4]
+
+تعالج هذه المواصفة هذه الثغرات من خلال [الوصف]. من خلال [القدرة]، يمكن لـ TrustGraph:
+- [الفائدة 1]
+- [الفائدة 2]
+- [الفائدة 3]
+- [الفائدة 4]
+
+## التصميم الفني
+
+### البنية
+
+يتطلب تحميل المعرفة من سطر الأوامر المكونات الفنية التالية:
+
+1. **[المكون 1]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+   
+   الوحدة: [مسار-الوحدة]
+
+2. **[المكون 2]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+
+   الوحدة: [مسار-الوحدة]
+
+3. **[المكون 3]**
+   - [وصف وظيفة المكون]
+   - [الميزات الرئيسية]
+   - [نقاط التكامل]
+
+   الوحدة: [مسار-الوحدة]
+
+### نماذج البيانات
+
+#### [نموذج البيانات 1]
+
+[وصف نموذج البيانات والبنية]
+
+مثال:
+```
+[Example data structure]
+```
+
+هذا النهج يسمح بما يلي:
+- [الفائدة 1]
+- [الفائدة 2]
+- [الفائدة 3]
+- [الفائدة 4]
+
+### واجهات برمجة التطبيقات (APIs)
+
+واجهات برمجة تطبيقات جديدة:
+- [وصف واجهة برمجة التطبيقات 1]
+- [وصف واجهة برمجة التطبيقات 2]
+- [وصف واجهة برمجة التطبيقات 3]
+
+واجهات برمجة تطبيقات مُعدَّلة:
+- [واجهة برمجة تطبيقات مُعدَّلة 1] - [وصف التغييرات]
+- [واجهة برمجة تطبيقات مُعدَّلة 2] - [وصف التغييرات]
+
+### تفاصيل التنفيذ
+
+[نهج التنفيذ والاصطلاحات]
+
+[ملاحظات إضافية حول التنفيذ]
+
+## اعتبارات الأمان
+
+[اعتبارات الأمان الخاصة بهذا التنفيذ]
+
+## اعتبارات الأداء
+
+[اعتبارات الأداء والاختناقات المحتملة]
+
+## استراتيجية الاختبار
+
+[نهج واستراتيجية الاختبار]
+
+## خطة الترحيل
+
+[استراتيجية الترحيل إذا كانت قابلة للتطبيق]
+
+## الجدول الزمني
+
+[معلومات حول الجدول الزمني إذا تم تحديدها]
+
+## أسئلة مفتوحة
+
+- [سؤال مفتوح 1]
+- [سؤال مفتوح 2]
+
+## المراجع
+
+[المراجع إذا كانت قابلة للتطبيق]

docs/tech-specs/__TEMPLATE.es.md

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

docs/tech-specs/__TEMPLATE.he.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: "Command-Line Loading Knowledge Technical Specification"
+parent: "Hebrew (Beta)"
+---
+
+# Command-Line Loading Knowledge Technical Specification
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Overview
+
+מפרט זה מתאר את ממשקי שורת הפקודה לטעינת ידע לתוך TrustGraph, ומאפשר למשתמשים לקלוט נתונים ממקורות שונים באמצעות כלי שורת פקודה. האינטגרציה תומכת בארבעה תרחישי שימוש עיקריים:
+
+1. **[Use Case 1]**: [Description]
+2. **[Use Case 2]**: [Description]
+3. **[Use Case 3]**: [Description]
+4. **[Use Case 4]**: [Description]
+
+## Goals
+
+- **[Goal 1]**: [Description]
+- **[Goal 2]**: [Description]
+- **[Goal 3]**: [Description]
+- **[Goal 4]**: [Description]
+- **[Goal 5]**: [Description]
+- **[Goal 6]**: [Description]
+- **[Goal 7]**: [Description]
+- **[Goal 8]**: [Description]
+
+## Background
+
+[Describe the current state and limitations that this specification addresses]
+
+מגבלות נוכחיות כוללות:
+- [Limitation 1]
+- [Limitation 2]
+- [Limitation 3]
+- [Limitation 4]
+
+מפרט זה מתייחס לפערים אלה על ידי [description]. באמצעות [capability], TrustGraph יכול:
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+- [Benefit 4]
+
+## Technical Design
+
+### Architecture
+
+טעינת ידע משורת הפקודה דורשת את הרכיבים הטכניים הבאים:
+
+1. **[Component 1]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+   
+   Module: [module-path]
+
+2. **[Component 2]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+
+   Module: [module-path]
+
+3. **[Component 3]**
+   - [Description of component functionality]
+   - [Key features]
+   - [Integration points]
+
+   Module: [module-path]
+
+### Data Models
+
+#### [Data Model 1]
+
+[Description of data model and structure]
+
+Example:
+```
+[Example data structure]
+```
+
+גישה זו מאפשרת:
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+- [Benefit 4]
+
+### ממשקי API
+
+ממשקי API חדשים:
+- [API description 1]
+- [API description 2]
+- [API description 3]
+
+ממשקי API ששונו:
+- [Modified API 1] - [Description of changes]
+- [Modified API 2] - [Description of changes]
+
+### פרטי יישום
+
+[גישת יישום ועקרונות]
+
+[הערות נוספות בנוגע ליישום]
+
+## שיקולי אבטחה
+
+[שיקולי אבטחה ספציפיים ליישום זה]
+
+## שיקולי ביצועים
+
+[שיקולי ביצועים וצווארי בקבוק פוטנציאליים]
+
+## אסטרטגיית בדיקות
+
+[גישת אסטרטגיית בדיקות]
+
+## תוכנית מעבר
+
+[אסטרטגיית מעבר, אם רלוונטית]
+
+## ציר זמן
+
+[מידע על ציר הזמן, אם מצוין]
+
+## שאלות פתוחות
+
+- [Open question 1]
+- [Open question 2]
+
+## מקורות
+
+[מקורות, אם רלוונטיים]

docs/tech-specs/__TEMPLATE.hi.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: "कमांड-लाइन लोडिंग नॉलेज टेक्निकल स्पेसिफिकेशन"
+parent: "Hindi (Beta)"
+---
+
+# कमांड-लाइन लोडिंग नॉलेज टेक्निकल स्पेसिफिकेशन
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## अवलोकन
+
+यह स्पेसिफिकेशन ट्रस्टग्राफ में नॉलेज लोड करने के लिए कमांड-लाइन इंटरफेस का वर्णन करता है, जो उपयोगकर्ताओं को कमांड-लाइन टूल के माध्यम से विभिन्न स्रोतों से डेटा प्राप्त करने में सक्षम बनाता है। एकीकरण चार प्राथमिक उपयोग मामलों का समर्थन करता है:
+
+1. **[उपयोग मामला 1]**: [विवरण]
+2. **[उपयोग मामला 2]**: [विवरण]
+3. **[उपयोग मामला 3]**: [विवरण]
+4. **[उपयोग मामला 4]**: [विवरण]
+
+## लक्ष्य
+
+- **[लक्ष्य 1]**: [विवरण]
+- **[लक्ष्य 2]**: [विवरण]
+- **[लक्ष्य 3]**: [विवरण]
+- **[लक्ष्य 4]**: [विवरण]
+- **[लक्ष्य 5]**: [विवरण]
+- **[लक्ष्य 6]**: [विवरण]
+- **[लक्ष्य 7]**: [विवरण]
+- **[लक्ष्य 8]**: [विवरण]
+
+## पृष्ठभूमि
+
+[वर्तमान स्थिति और सीमाओं का वर्णन करें जिन्हें यह स्पेसिफिकेशन संबोधित करता है]
+
+वर्तमान सीमाओं में शामिल हैं:
+- [सीमा 1]
+- [सीमा 2] 
+- [सीमा 3]
+- [सीमा 4]
+
+यह स्पेसिफिकेशन इन कमियों को [विवरण] द्वारा संबोधित करता है। [क्षमता] के माध्यम से, ट्रस्टग्राफ:
+- [लाभ 1]
+- [लाभ 2]
+- [लाभ 3]
+- [लाभ 4]
+
+## तकनीकी डिजाइन
+
+### आर्किटेक्चर
+
+कमांड-लाइन नॉलेज लोडिंग के लिए निम्नलिखित तकनीकी घटकों की आवश्यकता होती है:
+
+1. **[घटक 1]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+   
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+2. **[घटक 2]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+3. **[घटक 3]**
+   - [घटक कार्यक्षमता का विवरण]
+   - [मुख्य विशेषताएं]
+   - [एकीकरण बिंदु]
+
+   मॉड्यूल: [मॉड्यूल-पाथ]
+
+### डेटा मॉडल
+
+#### [डेटा मॉडल 1]
+
+[डेटा मॉडल और संरचना का विवरण]
+
+उदाहरण:
+```
+[Example data structure]
+```
+
+यह दृष्टिकोण निम्नलिखित की अनुमति देता है:
+- [लाभ 1]
+- [लाभ 2]
+- [लाभ 3]
+- [लाभ 4]
+
+### एपीआई (APIs)
+
+नए एपीआई (APIs):
+- [एपीआई विवरण 1]
+- [एपीआई विवरण 2]
+- [एपीआई विवरण 3]
+
+संशोधित एपीआई (APIs):
+- [संशोधित एपीआई 1] - [परिवर्तनों का विवरण]
+- [संशोधित एपीआई 2] - [परिवर्तनों का विवरण]
+
+### कार्यान्वयन विवरण
+
+[कार्यान्वयन दृष्टिकोण और परंपराएं]
+
+[अतिरिक्त कार्यान्वयन नोट्स]
+
+## सुरक्षा संबंधी विचार
+
+[इस कार्यान्वयन के लिए विशिष्ट सुरक्षा संबंधी विचार]
+
+## प्रदर्शन संबंधी विचार
+
+[प्रदर्शन संबंधी विचार और संभावित बाधाएं]
+
+## परीक्षण रणनीति
+
+[परीक्षण दृष्टिकोण और रणनीति]
+
+## माइग्रेशन योजना
+
+[यदि लागू हो, तो माइग्रेशन रणनीति]
+
+## समयरेखा
+
+[यदि निर्दिष्ट किया गया है, तो समयरेखा जानकारी]
+
+## अनुत्तरित प्रश्न
+
+- [अनुत्तरित प्रश्न 1]
+- [अनुत्तरित प्रश्न 2]
+
+## संदर्भ
+
+[यदि लागू हो, तो संदर्भ]

docs/tech-specs/__TEMPLATE.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "Command-Line Loading Knowledge Technical Specification"
+parent: "Tech Specs"
+---
+
 # Command-Line Loading Knowledge Technical Specification
 
 ## Overview

docs/tech-specs/__TEMPLATE.pt.md

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

docs/tech-specs/__TEMPLATE.ru.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: "Техническая спецификация загрузки знаний через командную строку"
+parent: "Russian (Beta)"
+---
+
+# Техническая спецификация загрузки знаний через командную строку
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Обзор
+
+Эта спецификация описывает интерфейсы командной строки для загрузки знаний в TrustGraph, позволяя пользователям загружать данные из различных источников с помощью инструментов командной строки. Интеграция поддерживает четыре основных сценария использования:
+
+1. **[Сценарий использования 1]**: [Описание]
+2. **[Сценарий использования 2]**: [Описание]
+3. **[Сценарий использования 3]**: [Описание]
+4. **[Сценарий использования 4]**: [Описание]
+
+## Цели
+
+- **[Цель 1]**: [Описание]
+- **[Цель 2]**: [Описание]
+- **[Цель 3]**: [Описание]
+- **[Цель 4]**: [Описание]
+- **[Цель 5]**: [Описание]
+- **[Цель 6]**: [Описание]
+- **[Цель 7]**: [Описание]
+- **[Цель 8]**: [Описание]
+
+## Предыстория
+
+[Опишите текущее состояние и ограничения, которые решает эта спецификация]
+
+Текущие ограничения включают:
+- [Ограничение 1]
+- [Ограничение 2]
+- [Ограничение 3]
+- [Ограничение 4]
+
+Эта спецификация устраняет эти недостатки, [описание]. Благодаря [возможности], TrustGraph может:
+- [Преимущество 1]
+- [Преимущество 2]
+- [Преимущество 3]
+- [Преимущество 4]
+
+## Технический дизайн
+
+### Архитектура
+
+Загрузка знаний через командную строку требует следующих технических компонентов:
+
+1. **[Компонент 1]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+   
+   Модуль: [путь_к_модулю]
+
+2. **[Компонент 2]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+
+   Модуль: [путь_к_модулю]
+
+3. **[Компонент 3]**
+   - [Описание функциональности компонента]
+   - [Основные характеристики]
+   - [Точки интеграции]
+
+   Модуль: [путь_к_модулю]
+
+### Модели данных
+
+#### [Модель данных 1]
+
+[Описание модели данных и ее структуры]
+
+Пример:
+```
+[Example data structure]
+```
+
+Этот подход позволяет:
+- [Преимущество 1]
+- [Преимущество 2]
+- [Преимущество 3]
+- [Преимущество 4]
+
+### API
+
+Новые API:
+- [Описание API 1]
+- [Описание API 2]
+- [Описание API 3]
+
+Измененные API:
+- [Измененный API 1] - [Описание изменений]
+- [Измененный API 2] - [Описание изменений]
+
+### Детали реализации
+
+[Подход к реализации и соглашения]
+
+[Дополнительные примечания по реализации]
+
+## Вопросы безопасности
+
+[Вопросы безопасности, специфичные для данной реализации]
+
+## Вопросы производительности
+
+[Вопросы производительности и потенциальные узкие места]
+
+## Стратегия тестирования
+
+[Подход и стратегия тестирования]
+
+## План миграции
+
+[Стратегия миграции, если применимо]
+
+## Сроки
+
+[Информация о сроках, если указана]
+
+## Открытые вопросы
+
+- [Открытый вопрос 1]
+- [Открытый вопрос 2]
+
+## Ссылки
+
+[Ссылки, если применимо]

docs/tech-specs/__TEMPLATE.sw.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: "Vipimo vya Kiufundi vya Kujaza Habari Kupitia Amri ya Kamba"
+parent: "Swahili (Beta)"
+---
+
+# Vipimo vya Kiufundi vya Kujaza Habari Kupitia Amri ya Kamba
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Muhtasari
+
+Vipimo hivi vinaelezea interface za amri ya kamba kwa ajili ya kujaza habari katika TrustGraph, na kuwezesha watumiaji kusambaza data kutoka vyanzo mbalimbali kupitia zana za amri ya kamba. Uunganishaji huu unaunga mkono matumizi manne makuu:
+
+1. **[Matumizi ya 1]**: [Maelezo]
+2. **[Matumizi ya 2]**: [Maelezo]
+3. **[Matumizi ya 3]**: [Maelezo]
+4. **[Matumizi ya 4]**: [Maelezo]
+
+## Lengo
+
+- **[Lengo la 1]**: [Maelezo]
+- **[Lengo la 2]**: [Maelezo]
+- **[Lengo la 3]**: [Maelezo]
+- **[Lengo la 4]**: [Maelezo]
+- **[Lengo la 5]**: [Maelezo]
+- **[Lengo la 6]**: [Maelezo]
+- **[Lengo la 7]**: [Maelezo]
+- **[Lengo la 8]**: [Maelezo]
+
+## Asili
+
+[Eleza hali ya sasa na vikwazo ambavyo vipimo hivi vinashughulikia]
+
+Vikwazo vya sasa ni pamoja na:
+- [Vikwazo 1]
+- [Vikwazo 2] 
+- [Vikwazo 3]
+- [Vikwazo 4]
+
+Vipimo hivi vinashughulikia pengo hizi kwa [maelezo]. Kwa [uwezo], TrustGraph inaweza:
+- [Faida 1]
+- [Faida 2]
+- [Faida 3]
+- [Faida 4]
+
+## Muundo wa Kiufundi
+
+### Usanifu
+
+Kujaza habari kupitia amri ya kamba inahitaji vipengele vifuatavyo vya kiufundi:
+
+1. **[Kipengele cha 1]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+   
+   Moduli: [njia-ya-moduli]
+
+2. **[Kipengele cha 2]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+
+   Moduli: [njia-ya-moduli]
+
+3. **[Kipengele cha 3]**
+   - [Maelezo ya utendaji wa kipengele]
+   - [Sifa muhimu]
+   - [Maeneo ya kuunganisha]
+
+   Moduli: [njia-ya-moduli]
+
+### Mifano ya Data
+
+#### [Mifano ya Data 1]
+
+[Maelezo ya mfano wa data na muundo]
+
+Mfano:
+```
+[Example data structure]
+```
+
+Mbinu hii inaruhusu:
+- [Faida 1]
+- [Faida 2]
+- [Faida 3]
+- [Faida 4]
+
+### API
+
+API mpya:
+- [Maelezo ya API 1]
+- [Maelezo ya API 2]
+- [Maelezo ya API 3]
+
+API zilizobadilishwa:
+- [API iliyobadilishwa 1] - [Maelezo ya mabadiliko]
+- [API iliyobadilishwa 2] - [Maelezo ya mabadiliko]
+
+### Maelezo ya Utendaji
+
+[Mbinu na miongozo ya utendaji]
+
+[Maelezo ya ziada ya utendaji]
+
+## Masuala ya Usalama
+
+[Masuala ya usalama maalum kwa utendaji huu]
+
+## Masuala ya Utendaji
+
+[Masuala ya utendaji na vizuizi vinavyowezekana]
+
+## Mkakati wa Majaribio
+
+[Mbinu na mkakati wa majaribio]
+
+## Mpango wa Uhamisho
+
+[Mkakati wa uhamisho ikiwa unafaa]
+
+## Ratiba
+
+[Habari ya ratiba ikiwa imebainishwa]
+
+## Maswali Yaliyobaki
+
+- [Swali lililobaki 1]
+- [Swali lililobaki 2]
+
+## Marejeleo
+
+[Marejeleo ikiwa yanafaa]

docs/tech-specs/__TEMPLATE.tr.md

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

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

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

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

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

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

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

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

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

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

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

docs/tech-specs/agent-explainability.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "Agent Explainability: Provenance Recording"
+parent: "Tech Specs"
+---
+
 # Agent Explainability: Provenance Recording
 
 ## Status

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

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

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

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

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

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

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

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

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

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

docs/tech-specs/agent-orchestration.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "TrustGraph Agent Orchestration — Technical Specification"
+parent: "Tech Specs"
+---
+
 # TrustGraph Agent Orchestration — Technical Specification
 
 ## Overview

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

@@ -0,0 +1,113 @@
+---
+layout: default
+title: "أسس هيكل الرسم البياني للمعرفة"
+parent: "Arabic (Beta)"
+---
+
+# أسس هيكل الرسم البياني للمعرفة
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## الأساس الأول: نموذج الرسم البياني للعلاقة بين الموضوع والمسند والموضوع (SPO)
+**القرار**: اعتماد نموذج SPO/RDF كنموذج تمثيل المعرفة الأساسي
+
+**السبب**:
+يوفر أقصى قدر من المرونة وقابلية التشغيل البيني مع تقنيات الرسم البياني الحالية
+يمكّن الترجمة السلسة إلى لغات استعلام عن الرسم البياني الأخرى (مثل SPO → Cypher، ولكن ليس العكس)
+يخلق أساسًا "يفتح الكثير" من القدرات اللاحقة
+يدعم كل من علاقات العقدة إلى العقدة (SPO) وعلاقات العقدة إلى القيمة الحرفية (RDF)
+
+**التنفيذ**:
+الهيكل الأساسي للبيانات: `node → edge → {node | literal}`
+الحفاظ على التوافق مع معايير RDF مع دعم عمليات SPO الموسعة
+
+## الأساس الثاني: تكامل الرسم البياني الأصلي لنماذج اللغة الكبيرة (LLM)
+**القرار**: تحسين هيكل وعمليات الرسم البياني للتفاعل مع نماذج اللغة الكبيرة
+
+**السبب**:
+الحالة الرئيسية هي تفاعل نماذج اللغة الكبيرة مع الرسوم البيانية للمعرفة
+يجب أن تعطي خيارات تقنية الرسم البياني الأولوية لتوافق نماذج اللغة الكبيرة على اعتبارات أخرى
+يمكّن سير عمل معالجة اللغة الطبيعية التي تستفيد من المعرفة المنظمة
+
+**التنفيذ**:
+تصميم مخططات الرسم البياني التي يمكن لنماذج اللغة الكبيرة الاستدلال عليها بشكل فعال
+التحسين لأنماط التفاعل الشائعة لنماذج اللغة الكبيرة
+
+## الأساس الثالث: التنقل في الرسم البياني القائم على التضمين
+**القرار**: تنفيذ تعيين مباشر من استعلامات اللغة الطبيعية إلى عقد الرسم البياني عبر التضمينات
+
+**السبب**:
+يمكّن المسار الأبسط من استعلام معالجة اللغة الطبيعية إلى التنقل في الرسم البياني
+يتجنب خطوات توليد استعلام وسيطة معقدة
+يوفر قدرات بحث دلالي فعالة داخل هيكل الرسم البياني
+
+**التنفيذ**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+الحفاظ على تمثيلات التضمين لجميع كيانات الرسم البياني
+دعم مطابقة تشابه دلالي مباشر لحل الاستعلامات
+
+## الأساس الرابع: حل الكيانات الموزع مع المعرفات الحتمية
+**القرار**: دعم استخراج المعرفة المتوازي مع تحديد الكيانات الحتمي (قاعدة 80٪)
+
+**السبب**:
+**مثالي**: يتيح استخراج العملية الفردية مع رؤية حالة كاملة حل الكيانات المثالي
+**الواقع**: تتطلب متطلبات قابلية التوسع قدرات معالجة متوازية
+**حل وسط**: التصميم من أجل تحديد الكيانات الحتمي عبر العمليات الموزعة
+
+**التنفيذ**:
+تطوير آليات لتوليد معرفات متسقة وفريدة عبر أدوات استخراج المعرفة المختلفة
+يجب أن يتم حل نفس الكيان المذكور في عمليات مختلفة إلى نفس المعرف
+الاعتراف بأنه قد تتطلب ~20٪ من الحالات الخاصة نماذج معالجة بديلة
+تصميم آليات احتياطية لسيناريوهات حل الكيانات المعقدة
+
+## الأساس الخامس: بنية قائمة على الأحداث مع النشر والاشتراك
+**القرار**: تنفيذ نظام رسائل النشر والاشتراك لتنسيق النظام
+
+**السبب**:
+يمكّن الفصل بين مكونات استخراج وتخزين واستعلام المعرفة
+يدعم التحديثات والإشعارات في الوقت الفعلي عبر النظام
+يسهل سير عمل معالجة موزعة وقابلة للتطوير
+
+**التنفيذ**:
+تنسيق مدفوع بالرسائل بين مكونات النظام
+تدفقات الأحداث لتحديثات المعرفة وإكمال الاستخراج ونتائج الاستعلام
+
+## الأساس السادس: تواصل الوكيل القابل لإعادة الدخول
+**القرار**: دعم عمليات النشر والاشتراك القابلة لإعادة الدخول لمعالجة قائمة على الوكلاء
+
+**السبب**:
+يمكّن سير عمل الوكيل المعقد حيث يمكن للوكلاء تشغيل والرد على بعضهم البعض
+يدعم خطوط أنابيب معالجة المعرفة المعقدة والمتعددة الخطوات
+يسمح بأنماط المعالجة التكرارية والتكرارية
+
+**التنفيذ**:
+يجب أن يتعامل نظام النشر والاشتراك مع المكالمات القابلة لإعادة الدخول بأمان
+آليات تنسيق الوكيل التي تمنع الحلقات اللانهائية
+دعم تنسيق سير عمل الوكيل
+
+## الأساس السابع: تكامل متجر البيانات العمودي
+**القرار**: ضمان توافق الاستعلام مع أنظمة التخزين العمودية
+
+**السبب**:
+يمكّن الاستعلامات التحليلية الفعالة على مجموعات بيانات المعرفة الكبيرة
+يدعم حالات استخدام ذكاء الأعمال وإعداد التقارير
+يربط بين تمثيل المعرفة القائم على الرسم البياني وسير العمل التحليلي التقليدي
+
+**التنفيذ**:
+طبقة ترجمة الاستعلام: استعلامات الرسم البياني → استعلامات عمودية
+استراتيجية تخزين هجينة تدعم عمليات الرسم البياني وأحمال العمل التحليلية
+الحفاظ على أداء الاستعلام عبر كلا النماذجين
+
+--
+
+## ملخص مبادئ البنية
+
+1. **المرونة أولاً**: يوفر نموذج SPO أقصى قدر من القدرة على التكيف
+2. **التحسين لنماذج اللغة الكبيرة**: تأخذ جميع القرارات التصميمية في الاعتبار متطلبات تفاعل نماذج اللغة الكبيرة
+3. **الكفاءة الدلالية**: تعيين مباشر من التضمين إلى العقدة لأداء استعلام أمثل
+4. **قابلية التوسع العملية**: الموازنة بين الدقة المثالية والمعالجة الموزعة العملية
+5. **التنسيق القائم على الأحداث**: يمكّن النشر والاشتراك من الفصل وقابلية التوسع
+6. **صديقة للوكيل**: دعم سير عمل معالجة متعددة الوكلاء
+7. **التوافق التحليلي**: ربط بين نماذج الرسم البياني والأعمدة للاستعلامات الشاملة
+
+تحدد هذه الأسس بنية رسم بياني للمعرفة تحقق التوازن بين الدقة النظرية ومتطلبات قابلية التوسع العملية، ومحسنة للتكامل مع نماذج اللغة الكبيرة والمعالجة الموزعة.

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

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

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

@@ -0,0 +1,113 @@
+---
+layout: default
+title: "יסודות ארכיטקטורת גרף ידע"
+parent: "Hebrew (Beta)"
+---
+
+# יסודות ארכיטקטורת גרף ידע
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## יסוד 1: מודל גרף נושא-תכונה-אובייקט (SPO)
+**החלטה**: לאמץ את מודל SPO/RDF כמודל הייצוג הבסיסי של ידע.
+
+**הצדקה**:
+מספק גמישות מרבית ותאימות עם טכנולוגיות גרף קיימות.
+מאפשר המרה חלקה לשפות שאילתות גרף אחרות (לדוגמה, SPO → Cypher, אך לא להיפך).
+יוצר בסיס ש"פותח הרבה" יכולות נלוות.
+תומך הן בקשרים בין צמתים (SPO) והן בקשרים בין צמתים לערכים (RDF).
+
+**יישום**:
+מבנה נתונים מרכזי: `node → edge → {node | literal}`
+שמירה על תאימות לתקני RDF תוך תמיכה בפעולות SPO מורחבות.
+
+## יסוד 2: שילוב גרף ידע מותאם למודלי שפה גדולים (LLM)
+**החלטה**: אופטימיזציה של מבנה ותפעול גרף ידע לאינטראקציה עם LLM.
+
+**הצדקה**:
+מקרה שימוש עיקרי כולל LLM באינטראקציה עם גרפי ידע.
+בחירות טכנולוגיות גרף חייבות לתעדף תאימות ל-LLM על פני שיקולים אחרים.
+מאפשר זרימות עבודה של עיבוד שפה טבעית המנצלות ידע מובנה.
+
+**יישום**:
+תכנון סכימות גרף ש-LLM יכולים להסיק מהן בצורה יעילה.
+אופטימיזציה לדפוסי אינטראקציה נפוצים של LLM.
+
+## יסוד 3: ניווט גרף מבוסס הטבעות (Embeddings)
+**החלטה**: יישום מיפוי ישיר משאילתות בשפה טבעית לצמתים בגרף באמצעות הטבעות.
+
+**הצדקה**:
+מאפשר את הנתיב הפשוט ביותר משאילת NLP לניווט בגרף.
+נמנע משלבי יצירת שאילתות ביניים מורכבים.
+מספק יכולות חיפוש סמנטיות יעילות בתוך מבנה הגרף.
+
+**יישום**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+שמירה על ייצוגי הטבעות עבור כל ישויות הגרף.
+תמיכה בהתאמת דמיון סמנטי ישירה לפתרון שאילתות.
+
+## יסוד 4: פתרון ישויות מבוזר עם מזהים דטרמיניסטיים
+**החלטה**: תמיכה בחילוץ ידע מקבילי עם זיהוי ישויות דטרמיניסטי (כלל 80%).
+
+**הצדקה**:
+**אידיאלי**: חילוץ בתהליך יחיד עם נראות של מצב מלא מאפשר פתרון ישויות מושלם.
+**מציאות**: דרישות סקיילביליות מחייבות יכולות עיבוד מקבילי.
+**פשרה**: תכנון לזיהוי ישויות דטרמיניסטי בכל תהליכים מבוזרים.
+
+**יישום**:
+פיתוח מנגנונים ליצירת מזהים עקביים וייחודיים בכל חולצי הידע.
+אותה ישות המוזכרת בתהליכים שונים חייבת להתפרש לאותו מזהה.
+יש להכיר בכך ש~20% מהמקרים המיוחדים עשויים לדרוש מודלי עיבוד חלופיים.
+תכנון מנגנוני ברירת מחדל עבור תרחישי פתרון ישויות מורכבים.
+
+## יסוד 5: ארכיטקטורה מונעת אירועים עם פרסום-מנוי
+**החלטה**: יישום מערכת הודעות מבוססת פרסום-מנוי לתיאום מערכות.
+
+**הצדקה**:
+מאפשר צימוד רופף בין רכיבי חילוץ, אחסון ושאילתות ידע.
+תומך בעדכונים והתראות בזמן אמת ברחבי המערכת.
+מקל על זרימות עבודה מבוזרות וניתנות להרחבה.
+
+**יישום**:
+תיאום מונחה הודעות בין רכיבי מערכת.
+זרמי אירועים לעדכוני ידע, השלמת חילוץ ושליחת תוצאות שאילתות.
+
+## יסוד 6: תקשורת סוכנים חוזרת
+**החלטה**: תמיכה בפעולות פרסום-מנוי חוזרות לעיבוד מבוסס סוכנים.
+
+**הצדקה**:
+מאפשר זרימות עבודה מורכבות של סוכנים שבהם סוכנים יכולים להפעיל ולהגיב זה לזה.
+תומך בצינורות עיבוד ידע מורכבים, רב-שלביים.
+מאפשר דפוסי עיבוד רקורסיביים ואיטרטיביים.
+
+**יישום**:
+מערכת הפרסום-מנוי חייבת לטפל בשיחות חוזרות בצורה בטוחה.
+מנגנוני תיאום סוכנים שמונעים לולאות אינסופיות.
+תמיכה בתיאום זרימות עבודה של סוכנים.
+
+## יסוד 7: שילוב עם חנות נתונים טבלאית
+**החלטה**: הבטחת תאימות שאילתות למערכות אחסון טבלאיות.
+
+**הצדקה**:
+מאפשר שאילתות אנליטיות יעילות על פני מערכי ידע גדולים.
+תומך במקרי שימוש של מודיעין עסקי ודיווח.
+גשר בין ייצוג ידע מבוסס גרף לבין זרימות עבודה אנליטיות מסורתיות.
+
+**יישום**:
+שכבת תרגום שאילתות: שאילתות גרף → שאילתות טבלאיות.
+אסטרטגיית אחסון היברידית התומכת הן בפעולות גרף והן בעומסי עבודה אנליטיים.
+שמירה על ביצועי שאילתות בשני הפרדיגמות.
+
+--
+
+## סיכום עקרונות ארכיטקטורה
+
+1. **גמישות ראשית**: מודל SPO/RDF מספק יכולת הסתגלות מרבית.
+2. **אופטימיזציה ל-LLM**: כל החלטות התכנון מתייחסות לאינטראקציה עם LLM.
+3. **ניווט יעיל**: שימוש בטבעות (Embeddings) לניווט יעיל בגרף.
+4. **פתרון ישויות מבוזר**: תמיכה בחילוץ ידע מקבילי עם מזהים דטרמיניסטיים.
+5. **תיאום מערכות**: שימוש במערכת הודעות מבוססת פרסום-מנוי.
+6. **עיבוד סוכנים חוזר**: תמיכה בפעולות פרסום-מנוי חוזרות לעיבוד מבוסס סוכנים.
+7. **תאימות שאילתות**: הבטחת תאימות שאילתות למערכות אחסון טבלאיות.
+
+יסודות אלה מציבים ארכיטקטורת גרף ידע המאזנת בין דיוק תיאורטי לדרישות מדרגיות מעשיות, ומותאמת לאינטגרציה עם מודלי שפה גדולים (LLM) ולעיבוד מבוזר.

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

@@ -0,0 +1,113 @@
+---
+layout: default
+title: "नॉलेज ग्राफ आर्किटेक्चर फाउंडेशन"
+parent: "Hindi (Beta)"
+---
+
+# नॉलेज ग्राफ आर्किटेक्चर फाउंडेशन
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## फाउंडेशन 1: सब्जेक्ट-प्रेडिकेट-ऑब्जेक्ट (एसपीओ) ग्राफ मॉडल
+**निर्णय**: एस.पी.ओ./आर.डी.एफ. को मुख्य नॉलेज रिप्रेजेंटेशन मॉडल के रूप में अपनाएं
+
+**तर्क**:
+यह अधिकतम लचीलापन और मौजूदा ग्राफ तकनीकों के साथ इंटरऑपरेबिलिटी प्रदान करता है।
+यह अन्य ग्राफ क्वेरी भाषाओं (जैसे, एस.पी.ओ. → साइफर, लेकिन इसके विपरीत नहीं) में सहज अनुवाद को सक्षम बनाता है।
+यह एक ऐसा आधार बनाता है जो "बहुत सारी" डाउनस्ट्रीम क्षमताओं को "अनलॉक" करता है।
+यह नोड-टू-नोड संबंधों (एस.पी.ओ.) और नोड-टू-लिटरल संबंधों (आर.डी.एफ.) दोनों का समर्थन करता है।
+
+**कार्यान्वयन**: 
+मुख्य डेटा संरचना: `node → edge → {node | literal}`
+विस्तारित एस.पी.ओ. ऑपरेशनों का समर्थन करते हुए आर.डी.एफ. मानकों के साथ अनुकूलता बनाए रखें।
+
+## फाउंडेशन 2: एलएलएम-नेटिव नॉलेज ग्राफ इंटीग्रेशन
+**निर्णय**: एलएलएम इंटरैक्शन के लिए नॉलेज ग्राफ संरचना और ऑपरेशनों को अनुकूलित करें
+
+**तर्क**:
+प्राथमिक उपयोग मामला एलएलएम का नॉलेज ग्राफ के साथ इंटरफेस करना है।
+ग्राफ तकनीक विकल्पों को अन्य विचारों की तुलना में एलएलएम अनुकूलता को प्राथमिकता देनी चाहिए।
+यह प्राकृतिक भाषा प्रसंस्करण वर्कफ़्लो को संरचित ज्ञान का लाभ उठाने में सक्षम बनाता है।
+
+**कार्यान्वयन**:
+ऐसे ग्राफ स्कीमा डिज़ाइन करें जिन्हें एलएलएम प्रभावी ढंग से तर्क दे सकें।
+सामान्य एलएलएम इंटरैक्शन पैटर्न के लिए अनुकूलित करें।
+
+## फाउंडेशन 3: एम्बेडिंग-आधारित ग्राफ नेविगेशन
+**निर्णय**: प्राकृतिक भाषा प्रश्नों को एम्बेडिंग के माध्यम से ग्राफ नोड्स पर सीधे मैप करें
+
+**तर्क**:
+यह एनएलपी क्वेरी से ग्राफ नेविगेशन के लिए सबसे सरल पथ को सक्षम करता है।
+जटिल मध्यवर्ती क्वेरी पीढ़ी चरणों से बचें।
+ग्राफ संरचना के भीतर कुशल सिमेंटिक खोज क्षमताओं को प्रदान करता है।
+
+**कार्यान्वयन**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+सभी ग्राफ एंटिटीज के लिए एम्बेडिंग रिप्रेजेंटेशन बनाए रखें।
+क्वेरी रिज़ॉल्यूशन के लिए प्रत्यक्ष सिमेंटिक समानता मिलान का समर्थन करें।
+
+## फाउंडेशन 4: डिस्ट्रीब्यूटेड एंटिटी रिज़ॉल्यूशन विद डिटर्मिनिस्टिक आइडेंटिफायर्स
+**निर्णय**: डिस्ट्रीब्यूटेड एंटिटी आइडेंटिफिकेशन (80% नियम) के साथ समानांतर नॉलेज एक्सट्रैक्शन का समर्थन करें
+
+**तर्क**:
+**आदर्श**: पूर्ण राज्य दृश्यता के साथ सिंगल-प्रोसेस एक्सट्रैक्शन सही एंटिटी रिज़ॉल्यूशन को सक्षम करता है।
+**वास्तविकता**: स्केलेबिलिटी आवश्यकताओं के लिए समानांतर प्रसंस्करण क्षमताओं की आवश्यकता होती है।
+**समझौता**: वितरित प्रक्रियाओं में नियतात्मक एंटिटी पहचान के लिए डिज़ाइन करें।
+
+**कार्यान्वयन**:
+ऐसे तंत्र विकसित करें जो विभिन्न नॉलेज एक्सट्रैक्टर्स में सुसंगत, अद्वितीय पहचानकर्ता उत्पन्न करते हैं।
+विभिन्न प्रक्रियाओं में उल्लिखित एक ही एंटिटी को समान पहचानकर्ता पर हल किया जाना चाहिए।
+इस बात को स्वीकार करें कि ~20% एज केस के लिए वैकल्पिक प्रसंस्करण मॉडल की आवश्यकता हो सकती है।
+जटिल एंटिटी रिज़ॉल्यूशन परिदृश्यों के लिए फॉलबैक तंत्र डिज़ाइन करें।
+
+## फाउंडेशन 5: इवेंट-ड्रिवन आर्किटेक्चर विद पब्लिश-सब्सक्राइब
+**निर्णय**: सिस्टम समन्वय के लिए एक पब-सब मैसेजिंग सिस्टम लागू करें
+
+**तर्क**:
+यह नॉलेज एक्सट्रैक्शन, स्टोरेज और क्वेरी घटकों के बीच ढीला युग्मन को सक्षम करता है।
+यह पूरे सिस्टम में रीयल-टाइम अपडेट और नोटिफिकेशन का समर्थन करता है।
+यह स्केलेबल, वितरित प्रसंस्करण वर्कफ़्लो को सुविधाजनक बनाता है।
+
+**कार्यान्वयन**:
+सिस्टम घटकों के बीच मैसेज-ड्रिवन समन्वय।
+नॉलेज अपडेट, एक्सट्रैक्शन पूरा होने और क्वेरी परिणामों के लिए इवेंट स्ट्रीम।
+
+## फाउंडेशन 6: रीएंट्रेंट एजेंट कम्युनिकेशन
+**निर्णय**: एजेंट-आधारित प्रसंस्करण के लिए रीएंट्रेंट पब-सब ऑपरेशंस का समर्थन करें
+
+**तर्क**:
+यह परिष्कृत एजेंट वर्कफ़्लो को सक्षम करता है जहां एजेंट एक-दूसरे को ट्रिगर और प्रतिक्रिया कर सकते हैं।
+यह जटिल, बहु-चरणीय नॉलेज प्रोसेसिंग पाइपलाइनों का समर्थन करता है।
+यह पुनरावर्ती और पुनरावृत्त प्रसंस्करण पैटर्न की अनुमति देता है।
+
+**कार्यान्वयन**:
+पब-सब सिस्टम को सुरक्षित रूप से रीएंट्रेंट कॉल को संभालना चाहिए।
+एजेंट समन्वय तंत्र जो अनंत लूप को रोकते हैं।
+एजेंट वर्कफ़्लो ऑर्केस्ट्रेशन के लिए समर्थन।
+
+## फाउंडेशन 7: कॉलम डेटा स्टोर इंटीग्रेशन
+**निर्णय**: कॉलम स्टोरेज सिस्टम के साथ क्वेरी अनुकूलता सुनिश्चित करें
+
+**तर्क**:
+यह बड़े नॉलेज डेटासेट पर कुशल विश्लेषणात्मक प्रश्नों को सक्षम करता है।
+यह बिजनेस इंटेलिजेंस और रिपोर्टिंग उपयोग मामलों का समर्थन करता है।
+यह ग्राफ-आधारित नॉलेज रिप्रेजेंटेशन को पारंपरिक विश्लेषणात्मक वर्कफ़्लो के साथ जोड़ता है।
+
+**कार्यान्वयन**:
+क्वेरी ट्रांसलेशन लेयर: ग्राफ क्वेरी → कॉलम क्वेरी
+एक हाइब्रिड स्टोरेज रणनीति जो ग्राफ ऑपरेशंस और विश्लेषणात्मक वर्कलोड दोनों का समर्थन करती है।
+दोनों प्रतिमानों में क्वेरी प्रदर्शन बनाए रखें।
+
+--
+
+## आर्किटेक्चर प्रिंसिपल्स समरी
+
+1. **लचीलापन पहले**: एस.पी.ओ./आर.डी.एफ. मॉडल अधिकतम अनुकूलन क्षमता प्रदान करता है।
+2. **एलएलएम अनुकूलन**: सभी डिज़ाइन निर्णयों पर एलएलएम इंटरैक्शन आवश्यकताओं पर विचार किया जाता है।
+3. **सिमेंटिक दक्षता**: इष्टतम क्वेरी प्रदर्शन के लिए प्रत्यक्ष एम्बेडिंग-टू-नोड मैपिंग।
+4. **व्यावहारिक स्केलेबिलिटी**: सही सटीकता को व्यावहारिक वितरित प्रसंस्करण के साथ संतुलित करें।
+5. **इवेंट-ड्रिवन समन्वय**: पब-सब ढीला युग्मन और स्केलेबिलिटी को सक्षम करता है।
+6. **एजेंट-फ्रेंडली**: जटिल, बहु-एजेंट प्रसंस्करण वर्कफ़्लो का समर्थन करें।
+7. **विश्लेषणात्मक अनुकूलता**: व्यापक क्वेरी के लिए ग्राफ और कॉलम प्रतिमानों को जोड़ें।
+
+ये फाउंडेशन एक नॉलेज ग्राफ आर्किटेक्चर स्थापित करते हैं जो सैद्धांतिक कठोरता को व्यावहारिक स्केलेबिलिटी आवश्यकताओं के साथ संतुलित करता है, जो एलएलएम एकीकरण और वितरित प्रसंस्करण के लिए अनुकूलित है।

docs/tech-specs/architecture-principles.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "Knowledge Graph Architecture Foundations"
+parent: "Tech Specs"
+---
+
 # Knowledge Graph Architecture Foundations
 
 ## Foundation 1: Subject-Predicate-Object (SPO) Graph Model
@@ -103,4 +109,3 @@
 7. **Analytical Compatibility**: Bridge graph and columnar paradigms for comprehensive querying
 
 These foundations establish a knowledge graph architecture that balances theoretical rigor with practical scalability requirements, optimized for LLM integration and distributed processing.
-

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

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

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

@@ -0,0 +1,113 @@
+---
+layout: default
+title: "Основы архитектуры графа знаний"
+parent: "Russian (Beta)"
+---
+
+# Основы архитектуры графа знаний
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Основа 1: Модель графа "Субъект-Предикат-Объект" (SPO)
+**Решение**: Принять SPO/RDF в качестве основной модели представления знаний.
+
+**Обоснование**:
+Обеспечивает максимальную гибкость и совместимость с существующими технологиями графов.
+Позволяет беспрепятственно переводить в другие языки запросов к графам (например, SPO → Cypher, но не наоборот).
+Создает основу, которая "открывает множество" возможностей для дальнейшей разработки.
+Поддерживает как отношения между узлами (SPO), так и отношения между узлами и литералами (RDF).
+
+**Реализация**:
+Основная структура данных: `node → edge → {node | literal}`
+Поддерживать совместимость со стандартами RDF, одновременно поддерживая расширенные операции SPO.
+
+## Основа 2: Интеграция графа знаний, оптимизированная для LLM
+**Решение**: Оптимизировать структуру и операции графа знаний для взаимодействия с LLM.
+
+**Обоснование**:
+Основной сценарий использования включает взаимодействие LLM с графами знаний.
+Выбор технологий графов должен отдавать приоритет совместимости с LLM, а не другим соображениям.
+Обеспечивает потоки обработки естественного языка, использующие структурированные знания.
+
+**Реализация**:
+Разрабатывать схемы графов, которые LLM могут эффективно использовать для рассуждений.
+Оптимизировать для распространенных шаблонов взаимодействия LLM.
+
+## Основа 3: Навигация по графу на основе встраиваний
+**Решение**: Реализовать прямое сопоставление между запросами на естественном языке и узлами графа с помощью встраиваний.
+
+**Обоснование**:
+Обеспечивает самый простой путь от запроса на естественном языке к навигации по графу.
+Избегает сложных промежуточных этапов генерации запросов.
+Предоставляет возможности семантического поиска в структуре графа.
+
+**Реализация**:
+`NLP Query → Graph Embeddings → Graph Nodes`
+Поддерживать представления встраиваний для всех сущностей графа.
+Поддерживать прямое семантическое сопоставление сходства для разрешения запросов.
+
+## Основа 4: Распределенное разрешение сущностей с детерминированными идентификаторами
+**Решение**: Поддерживать параллельное извлечение знаний с детерминированной идентификацией сущностей (правило 80%).
+
+**Обоснование**:
+**Идеально**: Извлечение в одном процессе с полной видимостью состояния обеспечивает идеальное разрешение сущностей.
+**Реальность**: Требования к масштабируемости требуют возможностей параллельной обработки.
+**Компромисс**: Разработать для детерминированной идентификации сущностей в распределенных процессах.
+
+**Реализация**:
+Разработать механизмы для генерации согласованных, уникальных идентификаторов в различных инструментах извлечения знаний.
+Одна и та же сущность, упомянутая в разных процессах, должна разрешаться в один и тот же идентификатор.
+Признать, что ~20% крайних случаев могут потребовать альтернативных моделей обработки.
+Разработать механизмы отката для сложных сценариев разрешения сущностей.
+
+## Основа 5: Архитектура, управляемая событиями, с публикацией и подпиской
+**Решение**: Реализовать систему обмена сообщениями pub-sub для координации системы.
+
+**Обоснование**:
+Обеспечивает слабую связанность между компонентами извлечения знаний, хранения и запросов.
+Поддерживает обновления в режиме реального времени и уведомления по всей системе.
+Облегчает масштабируемые, распределенные рабочие процессы.
+
+**Реализация**:
+Координация между компонентами системы с помощью управляемых сообщениями.
+Потоки событий для обновлений знаний, завершения извлечения и результатов запросов.
+
+## Основа 6: Взаимодействие агентов с возможностью повторного входа
+**Решение**: Поддерживать операции pub-sub с возможностью повторного входа для обработки на основе агентов.
+
+**Обоснование**:
+Позволяет создавать сложные рабочие процессы агентов, в которых агенты могут инициировать и реагировать друг на друга.
+Поддерживает сложные, многоступенчатые конвейеры обработки знаний.
+Позволяет использовать рекурсивные и итеративные шаблоны обработки.
+
+**Реализация**:
+Система pub-sub должна безопасно обрабатывать вызовы с повторным входом.
+Механизмы координации агентов, предотвращающие бесконечные циклы.
+Поддержка оркестровки рабочих процессов агентов.
+
+## Основа 7: Интеграция с хранилищем данных в столбцовом формате
+**Решение**: Обеспечить совместимость запросов с системами хранения данных в столбцовом формате.
+
+**Обоснование**:
+Обеспечивает эффективные аналитические запросы к большим наборам данных знаний.
+Поддерживает сценарии бизнес-аналитики и отчетности.
+Объединяет представление знаний на основе графов с традиционными аналитическими рабочими процессами.
+
+**Реализация**:
+Слой перевода запросов: Запросы графов → Запросы в столбцовом формате.
+Гибридная стратегия хранения, поддерживающая как операции графов, так и аналитические рабочие нагрузки.
+Поддерживать производительность запросов в обеих парадигмах.
+
+--
+
+## Краткое изложение принципов архитектуры
+
+1. **Гибкость прежде всего**: Модель SPO/RDF обеспечивает максимальную адаптируемость.
+2. **Оптимизация для LLM**: Все решения в области проектирования учитывают требования взаимодействия с LLM.
+3. **Семантическая эффективность**: Прямое сопоставление встраиваний с узлами для оптимальной производительности запросов.
+4. **Прагматическая масштабируемость**: Баланс между идеальной точностью и практическими возможностями распределенной обработки.
+5. **Координация, управляемая событиями**: Pub-sub обеспечивает слабую связанность и масштабируемость.
+6. **Поддержка агентов**: Поддержка сложных рабочих процессов, основанных на нескольких агентах.
+7. **Совместимость с аналитикой**: Объединение парадигм графов и столбцов для всестороннего запроса.
+
+Эта архитектура графа знаний сочетает теоретическую строгость с практическими требованиями масштабируемости, оптимизированная для интеграции с LLM и распределенной обработки.

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,249 @@
+---
+layout: default
+title: "Especificación Técnica: Consolidación de la Configuración de Cassandra"
+parent: "Spanish (Beta)"
+---
+
+# Especificación Técnica: Consolidación de la Configuración de Cassandra
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+**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`