Merge branch 'master' into type-hints/base-classes

2026-07-08 04:42:11 +02:00 · 2026-04-16 09:55:49 +01:00 · 2026-04-16 09:55:49 +01:00 · 11ca2bec7f
commit 11ca2bec7f
parent 2c5d09f733 e64b0dbb2b
714 changed files with 243185 additions and 1975 deletions
--- a/.github/workflows/pull-request.yaml
+++ b/.github/workflows/pull-request.yaml
@ -22,7 +22,7 @@ jobs:
        uses: actions/checkout@v3

      - name: Setup packages
-        run: make update-package-versions VERSION=2.2.999
+        run: make update-package-versions VERSION=2.3.999

      - name: Setup environment
        run: python3 -m venv env
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@ -40,10 +40,9 @@ jobs:
      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

-  deploy-container-image:
+  build-platform-image:

-    name: Release container images
-    runs-on: ubuntu-24.04
+    name: Build ${{ matrix.container }} (${{ matrix.platform }})
    permissions:
      contents: write
      id-token: write
@ -52,14 +51,24 @@ jobs:
    strategy:
      matrix:
        container:
-          - trustgraph-base
-          - trustgraph-flow
-          - trustgraph-bedrock
-          - trustgraph-vertexai
-          - trustgraph-hf
-          - trustgraph-ocr
-          - trustgraph-unstructured
-          - trustgraph-mcp
+          - base
+          - flow
+          - bedrock
+          - vertexai
+          - hf
+          - ocr
+          - unstructured
+          - mcp
+        platform:
+          - amd64
+          - arm64
+        include:
+          - platform: amd64
+            runner: ubuntu-24.04
+          - platform: arm64
+            runner: ubuntu-24.04-arm
+
+    runs-on: ${{ matrix.runner }}

    steps:

@ -76,12 +85,48 @@ jobs:
        id: version
        run: echo VERSION=$(git describe --exact-match --tags | sed 's/^v//') >> $GITHUB_OUTPUT

-      - name: Put version into package manifests
-        run: make update-package-versions VERSION=${{ steps.version.outputs.VERSION }}
+      - name: Build container
+        run: make platform-${{ matrix.container }}-${{ matrix.platform }} VERSION=${{ steps.version.outputs.VERSION }}

-      - name: Build container - ${{ matrix.container }}
-        run: make container-${{ matrix.container }} VERSION=${{ steps.version.outputs.VERSION }}
+      - name: Push container
+        run: make push-platform-${{ matrix.container }}-${{ matrix.platform }} VERSION=${{ steps.version.outputs.VERSION }}

-      - name: Push container - ${{ matrix.container }}
-        run: make push-${{ matrix.container }} VERSION=${{ steps.version.outputs.VERSION }}
+  combine-manifests:

+    name: Combine manifest ${{ matrix.container }}
+    runs-on: ubuntu-24.04
+    needs: build-platform-image
+    permissions:
+      contents: write
+      id-token: write
+    environment:
+      name: release
+    strategy:
+      matrix:
+        container:
+          - base
+          - flow
+          - bedrock
+          - vertexai
+          - hf
+          - ocr
+          - unstructured
+          - mcp
+
+    steps:
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Docker Hub token
+        run: echo ${{ secrets.DOCKER_SECRET }} > docker-token.txt
+
+      - name: Authenticate with Docker hub
+        run: make docker-hub-login
+
+      - name: Get version
+        id: version
+        run: echo VERSION=$(git describe --exact-match --tags | sed 's/^v//') >> $GITHUB_OUTPUT
+
+      - name: Combine and push manifest
+        run: make combine-manifest-${{ matrix.container }} VERSION=${{ steps.version.outputs.VERSION }}
--- a/181
+++ b/181
@ -52,51 +52,12 @@ update-package-versions:
 	echo __version__ = \"${VERSION}\" > trustgraph/trustgraph/trustgraph_version.py
 	echo __version__ = \"${VERSION}\" > trustgraph-mcp/trustgraph/mcp_version.py

-FORCE:
+containers: container-base container-flow \
+container-bedrock container-vertexai \
+container-hf container-ocr \
+container-unstructured container-mcp

-containers: FORCE
-	${DOCKER} build -f containers/Containerfile.base \
-	    -t ${CONTAINER_BASE}/trustgraph-base:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.flow \
-	    -t ${CONTAINER_BASE}/trustgraph-flow:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.bedrock \
-	    -t ${CONTAINER_BASE}/trustgraph-bedrock:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.vertexai \
-	    -t ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.hf \
-	    -t ${CONTAINER_BASE}/trustgraph-hf:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.ocr \
-	    -t ${CONTAINER_BASE}/trustgraph-ocr:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.unstructured \
-	    -t ${CONTAINER_BASE}/trustgraph-unstructured:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.mcp \
-	    -t ${CONTAINER_BASE}/trustgraph-mcp:${VERSION} .
-
-some-containers:
-	${DOCKER} build -f containers/Containerfile.base \
-	    -t ${CONTAINER_BASE}/trustgraph-base:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.flow \
-	    -t ${CONTAINER_BASE}/trustgraph-flow:${VERSION} .
-#	${DOCKER} build -f containers/Containerfile.unstructured \
-#	    -t ${CONTAINER_BASE}/trustgraph-unstructured:${VERSION} .
-#	${DOCKER} build -f containers/Containerfile.vertexai \
-#	    -t ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION} .
-#	${DOCKER} build -f containers/Containerfile.mcp \
-#	    -t ${CONTAINER_BASE}/trustgraph-mcp:${VERSION} .
-#	${DOCKER} build -f containers/Containerfile.vertexai \
-#	    -t ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION} .
-#	${DOCKER} build -f containers/Containerfile.bedrock \
-#	    -t ${CONTAINER_BASE}/trustgraph-bedrock:${VERSION} .
-
-basic-containers: update-package-versions
-	${DOCKER} build -f containers/Containerfile.base \
-	    -t ${CONTAINER_BASE}/trustgraph-base:${VERSION} .
-	${DOCKER} build -f containers/Containerfile.flow \
-	    -t ${CONTAINER_BASE}/trustgraph-flow:${VERSION} .
-
-container.ocr:
-	${DOCKER} build -f containers/Containerfile.ocr \
-	    -t ${CONTAINER_BASE}/trustgraph-ocr:${VERSION} .
+some-containers: container-base container-flow

 push:
 	${DOCKER} push ${CONTAINER_BASE}/trustgraph-base:${VERSION}
@ -109,54 +70,60 @@ push:
 	${DOCKER} push ${CONTAINER_BASE}/trustgraph-mcp:${VERSION}

 # Individual container build targets
-container-trustgraph-base: update-package-versions
-	${DOCKER} build -f containers/Containerfile.base -t ${CONTAINER_BASE}/trustgraph-base:${VERSION} .
+container-%: update-package-versions
+	${DOCKER} build \
+	    -f containers/Containerfile.${@:container-%=%} \
+	    -t ${CONTAINER_BASE}/trustgraph-${@:container-%=%}:${VERSION} .

-container-trustgraph-flow: update-package-versions
-	${DOCKER} build -f containers/Containerfile.flow -t ${CONTAINER_BASE}/trustgraph-flow:${VERSION} .
+# Multi-arch: build both platforms sequentially into one manifest (local use)
+manifest-%: update-package-versions
+	-@${DOCKER} manifest rm \
+	    ${CONTAINER_BASE}/trustgraph-${@:manifest-%=%}:${VERSION}
+	${DOCKER} build --platform linux/amd64,linux/arm64 \
+	    -f containers/Containerfile.${@:manifest-%=%} \
+	    --manifest \
+	    ${CONTAINER_BASE}/trustgraph-${@:manifest-%=%}:${VERSION} .

-container-trustgraph-bedrock: update-package-versions
-	${DOCKER} build -f containers/Containerfile.bedrock -t ${CONTAINER_BASE}/trustgraph-bedrock:${VERSION} .
+# Multi-arch: build a single platform image (for parallel CI)
+platform-%-amd64: update-package-versions
+	${DOCKER} build --platform linux/amd64 \
+	    -f containers/Containerfile.${@:platform-%-amd64=%} \
+	    -t ${CONTAINER_BASE}/trustgraph-${@:platform-%-amd64=%}:${VERSION}-amd64 .

-container-trustgraph-vertexai: update-package-versions
-	${DOCKER} build -f containers/Containerfile.vertexai -t ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION} .
+platform-%-arm64: update-package-versions
+	${DOCKER} build --platform linux/arm64 \
+	    -f containers/Containerfile.${@:platform-%-arm64=%} \
+	    -t ${CONTAINER_BASE}/trustgraph-${@:platform-%-arm64=%}:${VERSION}-arm64 .

-container-trustgraph-hf: update-package-versions
-	${DOCKER} build -f containers/Containerfile.hf -t ${CONTAINER_BASE}/trustgraph-hf:${VERSION} .
+# Push a single platform image
+push-platform-%-amd64:
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-platform-%-amd64=%}:${VERSION}-amd64

-container-trustgraph-ocr: update-package-versions
-	${DOCKER} build -f containers/Containerfile.ocr -t ${CONTAINER_BASE}/trustgraph-ocr:${VERSION} .
+push-platform-%-arm64:
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-platform-%-arm64=%}:${VERSION}-arm64

-container-trustgraph-unstructured: update-package-versions
-	${DOCKER} build -f containers/Containerfile.unstructured -t ${CONTAINER_BASE}/trustgraph-unstructured:${VERSION} .
+# Combine per-platform images into a multi-arch manifest
+combine-manifest-%:
+	-@${DOCKER} manifest rm \
+	    ${CONTAINER_BASE}/trustgraph-${@:combine-manifest-%=%}:${VERSION}
+	${DOCKER} manifest create \
+	    ${CONTAINER_BASE}/trustgraph-${@:combine-manifest-%=%}:${VERSION} \
+	    docker://${CONTAINER_BASE}/trustgraph-${@:combine-manifest-%=%}:${VERSION}-amd64 \
+	    docker://${CONTAINER_BASE}/trustgraph-${@:combine-manifest-%=%}:${VERSION}-arm64
+	${DOCKER} manifest push \
+	    ${CONTAINER_BASE}/trustgraph-${@:combine-manifest-%=%}:${VERSION}

-container-trustgraph-mcp: update-package-versions
-	${DOCKER} build -f containers/Containerfile.mcp -t ${CONTAINER_BASE}/trustgraph-mcp:${VERSION} .
+# Push a container
+push-container-%:
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-container-%=%}:${VERSION}

-# Individual container push targets
-push-trustgraph-base:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-base:${VERSION}
-
-push-trustgraph-flow:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-flow:${VERSION}
-
-push-trustgraph-bedrock:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-bedrock:${VERSION}
-
-push-trustgraph-vertexai:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION}
-
-push-trustgraph-hf:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-hf:${VERSION}
-
-push-trustgraph-ocr:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-ocr:${VERSION}
-
-push-trustgraph-unstructured:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-unstructured:${VERSION}
-
-push-trustgraph-mcp:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-mcp:${VERSION}
+# Push a manifest (from local multi-arch build)
+push-manifest-%:
+	${DOCKER} manifest push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-manifest-%=%}:${VERSION}

 clean:
 	rm -rf wheels/
@ -164,52 +131,6 @@ clean:
 set-version:
 	echo '"${VERSION}"' > templates/values/version.jsonnet

-TEMPLATES=azure bedrock claude cohere mix llamafile mistral ollama openai vertexai \
-    openai-neo4j storage
-
-DCS=$(foreach template,${TEMPLATES},${template:%=tg-launch-%.yaml})
-
-MODELS=azure bedrock claude cohere llamafile mistral ollama openai vertexai
-GRAPHS=cassandra neo4j falkordb memgraph
-
-# tg-launch-%.yaml: templates/%.jsonnet templates/components/version.jsonnet
-# 	jsonnet -Jtemplates \
-# 	    -S ${@:tg-launch-%.yaml=templates/%.jsonnet} > $@
-
-# VECTORDB=milvus
-VECTORDB=qdrant
-
-JSONNET_FLAGS=-J templates -J .
-
-# Temporarily going back to how templates were built in 0.9 because this
-# is going away in 0.11.
-
-update-templates: update-dcs
-
-JSON_TO_YAML=python -c 'import sys, yaml, json; j=json.loads(sys.stdin.read()); print(yaml.safe_dump(j))'
-
-update-dcs: set-version
-	for graph in ${GRAPHS}; do \
-	    cm=$${graph},pulsar,${VECTORDB},grafana; \
-	    input=templates/opts-to-docker-compose.jsonnet; \
-	    output=tg-storage-$${graph}.yaml; \
-	    echo $${graph} '->' $${output}; \
-	    jsonnet ${JSONNET_FLAGS} \
-	         --ext-str options=$${cm} $${input} | \
-	         ${JSON_TO_YAML} > $${output}; \
-	done
-	for model in ${MODELS}; do \
-	  for graph in ${GRAPHS}; do \
-	    cm=$${graph},pulsar,${VECTORDB},embeddings-hf,graph-rag,grafana,trustgraph,$${model}; \
-	    input=templates/opts-to-docker-compose.jsonnet; \
-	    output=tg-launch-$${model}-$${graph}.yaml; \
-	    echo $${model} + $${graph} '->' $${output}; \
-	    jsonnet ${JSONNET_FLAGS} \
-	         --ext-str options=$${cm} $${input} | \
-                 ${JSON_TO_YAML} > $${output}; \
-	  done; \
-	done
-
 docker-hub-login:
 	cat docker-token.txt | \
 	    ${DOCKER} login -u trustgraph --password-stdin registry-1.docker.io
--- a/containers/Containerfile.hf
+++ b/containers/Containerfile.hf
@ -1,22 +1,22 @@

-# ----------------------------------------------------------------------------
-# Build an AI container.  This does the torch install which is huge, and I
-# like to avoid re-doing this.
-# ----------------------------------------------------------------------------
+# Torch is stable and compiles for ARM64 and AMD64 on Python 3.12

 FROM docker.io/fedora:42 AS ai

 ENV PIP_BREAK_SYSTEM_PACKAGES=1

-RUN dnf install -y python3.13 && \
-  alternatives --install /usr/bin/python python /usr/bin/python3.13 1 && \
+RUN dnf install -y python3.12 && \
+  alternatives --install /usr/bin/python python /usr/bin/python3.12 1 && \
  python -m ensurepip --upgrade && \
  pip3 install --no-cache-dir build wheel aiohttp && \
  pip3 install --no-cache-dir pulsar-client==3.7.0 && \
  dnf clean all

-RUN pip3 install torch==2.5.1+cpu \
-    --index-url https://download.pytorch.org/whl/cpu
+# This won't work on ARM
+#RUN pip3 install torch==2.5.1+cpu \
+#    --index-url https://download.pytorch.org/whl/cpu
+
+RUN pip3 install torch

 RUN pip3 install --no-cache-dir \
    langchain==0.3.25 langchain-core==0.3.60 langchain-huggingface==0.2.0 \
--- a/dev-tools/proc-group/README.md
+++ b/dev-tools/proc-group/README.md
@ -0,0 +1,117 @@
+# proc-group — run TrustGraph as a single process
+
+A dev-focused alternative to the per-container deployment. Instead of 30+
+containers each running a single processor, `processor-group` runs all the
+processors as asyncio tasks inside one Python process, sharing the event
+loop, Prometheus registry, and (importantly) resources on your laptop.
+
+This is **not** for production. Scale deployments should keep using
+per-processor containers — one failure bringing down the whole process,
+no horizontal scaling, and a single giant log are fine for dev and a
+bad idea in prod.
+
+## What this directory contains
+
+- `group.yaml` — the group runner config. One entry per processor, each
+  with the dotted class path and a params dict. Defaults (pubsub backend,
+  rabbitmq host, log level) are pulled in per-entry with a YAML anchor.
+- `README.md` — this file.
+
+## Prerequisites
+
+Install the TrustGraph packages into a venv:
+
+```
+pip install trustgraph-base trustgraph-flow trustgraph-unstructured
+```
+
+`trustgraph-base` provides the `processor-group` endpoint. The others
+provide the processor classes that `group.yaml` imports at runtime.
+`trustgraph-unstructured` is only needed if you want `document-decoder`
+(the `universal-decoder` processor).
+
+## Running it
+
+Start infrastructure (cassandra, qdrant, rabbitmq, garage, observability
+stack) with a working compose file. These aren't packable into the group -
+they're third-party services.  You may be able to run these as standalone
+services.
+
+To get Cassandra to be accessible from the host, you need to 
+set a couple of environment variables:
+```
+      CASSANDRA_BROADCAST_ADDRESS: 127.0.0.1
+      CASSANDRA_LISTEN_ADDRESS: 127.0.0.1
+```
+and also set `network: host`.  Then start services:
+
+```
+podman-compose up -d cassandra qdrant rabbitmq
+podman-compose up -d garage garage-init
+podman-compose up -d loki prometheus grafana
+podman-compose up -d init-trustgraph
+```
+
+`init-trustgraph` is a one-shot that seeds config and the default flow
+into cassandra/rabbitmq.  Don't leave too long a delay between starting
+`init-trustgraph` and running the processor-group, because it needs to
+talk to the config service.
+
+Run the api-gateway separately — it's an aiohttp HTTP server, not an
+`AsyncProcessor`, so the group runner doesn't host it:
+
+Raise the file descriptor limit — 30+ processors sharing one process
+open far more sockets than the default 1024 allows:
+
+```
+ulimit -n 65536
+```
+
+Then start the group from a terminal:
+
+```
+processor-group -c group.yaml --no-loki-enabled
+```
+
+You'll see every processor's startup messages interleaved in one log.
+Each processor has a supervisor that restarts it independently on
+failure, so a transient crash (or a dependency that isn't ready yet)
+only affects that one processor — siblings keep running and the failing
+one self-heals on the next retry.
+
+Finally when everything is running you can start the API gateway from
+its own terminal:
+
+```
+api-gateway \
+    --pubsub-backend rabbitmq --rabbitmq-host localhost \
+    --loki-url http://localhost:3100/loki/api/v1/push \
+    --no-metrics
+```
+
+
+
+## When things go wrong
+
+- **"Too many open files"** — raise `ulimit -n` further. 65536 is
+  usually plenty but some workflows need more.
+- **One processor failing repeatedly** — look for its id in the log. The
+  supervisor will log each failure before restarting. Fix the cause
+  (missing env var, unreachable dependency, bad params) and the
+  processor self-heals on the next 4-second retry without restarting
+  the whole group.
+- **Ctrl-C leaves the process hung** — the pika and cassandra drivers
+  spawn non-cooperative threads that asyncio can't cancel. Use Ctrl-\
+  (SIGQUIT) to force-kill. Not a bug in the group runner, just a
+  limitation of those libraries.
+
+## Environment variables
+
+Processors that talk to external LLMs or APIs read their credentials
+from env vars, same as in the per-container deployment:
+
+- `OPENAI_TOKEN`, `OPENAI_BASE_URL` — for `text-completion` /
+  `text-completion-rag`
+
+Export whatever your particular `group.yaml` needs before running.
+
--- a/dev-tools/proc-group/group.yaml
+++ b/dev-tools/proc-group/group.yaml
@ -0,0 +1,257 @@
+# Multi-processor group config, derived from docker-compose.yaml.
+#
+# Covers every AsyncProcessor-based service from the compose file.
+# Out of scope:
+#   - api-gateway       (aiohttp, not AsyncProcessor)
+#   - init-trustgraph   (one-shot init, not a processor)
+#   - document-decoder  (universal-decoder, trustgraph-unstructured package —
+#                        packable but lives in a separate image/package)
+#   - mcp-server        (trustgraph-mcp package, separate image)
+#   - ddg-mcp-server    (third-party image)
+#   - infrastructure    (cassandra, rabbitmq, qdrant, garage, grafana,
+#                        prometheus, loki, workbench-ui)
+#
+# Run with:
+#   processor-group -c group.yaml
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.agent.orchestrator.Processor
+    params:
+      <<: *defaults
+      id: agent-manager
+
+  - class: trustgraph.chunking.recursive.Processor
+    params:
+      <<: *defaults
+      id: chunker
+      chunk_size: 2000
+      chunk_overlap: 50
+
+  - class: trustgraph.config.service.Processor
+    params:
+      <<: *defaults
+      id: config-svc
+      cassandra_host: localhost
+
+  - class: trustgraph.decoding.universal.Processor
+    params:
+      <<: *defaults
+      id: document-decoder
+
+  - class: trustgraph.embeddings.document_embeddings.Processor
+    params:
+      <<: *defaults
+      id: document-embeddings
+
+  - class: trustgraph.retrieval.document_rag.Processor
+    params:
+      <<: *defaults
+      id: document-rag
+      doc_limit: 20
+
+  - class: trustgraph.embeddings.fastembed.Processor
+    params:
+      <<: *defaults
+      id: embeddings
+      concurrency: 1
+
+  - class: trustgraph.embeddings.graph_embeddings.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings
+
+  - class: trustgraph.retrieval.graph_rag.Processor
+    params:
+      <<: *defaults
+      id: graph-rag
+      concurrency: 1
+      entity_limit: 50
+      triple_limit: 30
+      edge_limit: 30
+      edge_score_limit: 10
+      max_subgraph_size: 100
+      max_path_length: 2
+
+  - class: trustgraph.extract.kg.agent.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-agent
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.definitions.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-definitions
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.ontology.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-ontology
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.relationships.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-relationships
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.rows.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-rows
+      concurrency: 1
+
+  - class: trustgraph.cores.service.Processor
+    params:
+      <<: *defaults
+      id: knowledge
+      cassandra_host: localhost
+
+  - class: trustgraph.storage.knowledge.store.Processor
+    params:
+      <<: *defaults
+      id: kg-store
+      cassandra_host: localhost
+
+  - class: trustgraph.librarian.Processor
+    params:
+      <<: *defaults
+      id: librarian
+      cassandra_host: localhost
+      object_store_endpoint: localhost:3900
+      object_store_access_key: GK000000000000000000000001
+      object_store_secret_key: b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
+      object_store_region: garage
+
+  - class: trustgraph.agent.mcp_tool.Service
+    params:
+      <<: *defaults
+      id: mcp-tool
+
+  - class: trustgraph.metering.Processor
+    params:
+      <<: *defaults
+      id: metering
+
+  - class: trustgraph.metering.Processor
+    params:
+      <<: *defaults
+      id: metering-rag
+
+  - class: trustgraph.retrieval.nlp_query.Processor
+    params:
+      <<: *defaults
+      id: nlp-query
+
+  - class: trustgraph.prompt.template.Processor
+    params:
+      <<: *defaults
+      id: prompt
+      concurrency: 1
+
+  - class: trustgraph.prompt.template.Processor
+    params:
+      <<: *defaults
+      id: prompt-rag
+      concurrency: 1
+
+  - class: trustgraph.query.doc_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: doc-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.query.graph_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.query.row_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.query.rows.cassandra.Processor
+    params:
+      <<: *defaults
+      id: rows-query
+      cassandra_host: localhost
+
+  - class: trustgraph.query.triples.cassandra.Processor
+    params:
+      <<: *defaults
+      id: triples-query
+      cassandra_host: localhost
+
+  - class: trustgraph.embeddings.row_embeddings.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings
+
+  - class: trustgraph.query.sparql.Processor
+    params:
+      <<: *defaults
+      id: sparql-query
+
+  - class: trustgraph.storage.doc_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: doc-embeddings-write
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.graph_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings-write
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.row_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings-write
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.rows.cassandra.Processor
+    params:
+      <<: *defaults
+      id: rows-write
+      cassandra_host: localhost
+
+  - class: trustgraph.storage.triples.cassandra.Processor
+    params:
+      <<: *defaults
+      id: triples-write
+      cassandra_host: localhost
+
+  - class: trustgraph.retrieval.structured_diag.Processor
+    params:
+      <<: *defaults
+      id: structured-diag
+
+  - class: trustgraph.retrieval.structured_query.Processor
+    params:
+      <<: *defaults
+      id: structured-query
+
+  - class: trustgraph.model.text_completion.openai.Processor
+    params:
+      <<: *defaults
+      id: text-completion
+      max_output: 8192
+      temperature: 0.0
+
+  - class: trustgraph.model.text_completion.openai.Processor
+    params:
+      <<: *defaults
+      id: text-completion-rag
+      max_output: 8192
+      temperature: 0.0
--- a/dev-tools/proc-group/groups/control.yaml
+++ b/dev-tools/proc-group/groups/control.yaml
@ -0,0 +1,47 @@
+# Control plane.  Stateful "always on" services that every flow depends on.
+# Cassandra-heavy, low traffic.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.config.service.Processor
+    params:
+      <<: *defaults
+      id: config-svc
+      cassandra_host: localhost
+
+  - class: trustgraph.librarian.Processor
+    params:
+      <<: *defaults
+      id: librarian
+      cassandra_host: localhost
+      object_store_endpoint: localhost:3900
+      object_store_access_key: GK000000000000000000000001
+      object_store_secret_key: b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
+      object_store_region: garage
+
+  - class: trustgraph.cores.service.Processor
+    params:
+      <<: *defaults
+      id: knowledge
+      cassandra_host: localhost
+
+  - class: trustgraph.storage.knowledge.store.Processor
+    params:
+      <<: *defaults
+      id: kg-store
+      cassandra_host: localhost
+
+  - class: trustgraph.metering.Processor
+    params:
+      <<: *defaults
+      id: metering
+
+  - class: trustgraph.metering.Processor
+    params:
+      <<: *defaults
+      id: metering-rag
--- a/dev-tools/proc-group/groups/embeddings-store.yaml
+++ b/dev-tools/proc-group/groups/embeddings-store.yaml
@ -0,0 +1,45 @@
+# Embeddings store.  All Qdrant-backed vector query/write processors.
+# One process owns the Qdrant driver pool for the whole group.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.query.doc_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: doc-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.doc_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: doc-embeddings-write
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.query.graph_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.graph_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings-write
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.query.row_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings-query
+      store_uri: http://localhost:6333
+
+  - class: trustgraph.storage.row_embeddings.qdrant.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings-write
+      store_uri: http://localhost:6333
--- a/dev-tools/proc-group/groups/embeddings.yaml
+++ b/dev-tools/proc-group/groups/embeddings.yaml
@ -0,0 +1,31 @@
+# Embeddings.  Memory-hungry — fastembed loads an ML model at startup.
+# Keep isolated from other groups so its memory footprint and restart
+# latency don't affect siblings.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.embeddings.fastembed.Processor
+    params:
+      <<: *defaults
+      id: embeddings
+      concurrency: 1
+
+  - class: trustgraph.embeddings.document_embeddings.Processor
+    params:
+      <<: *defaults
+      id: document-embeddings
+
+  - class: trustgraph.embeddings.graph_embeddings.Processor
+    params:
+      <<: *defaults
+      id: graph-embeddings
+
+  - class: trustgraph.embeddings.row_embeddings.Processor
+    params:
+      <<: *defaults
+      id: row-embeddings
--- a/dev-tools/proc-group/groups/ingest.yaml
+++ b/dev-tools/proc-group/groups/ingest.yaml
@ -0,0 +1,52 @@
+# Ingest pipeline.  Document-processing hot path.  Bursty, correlated
+# failures — if chunker dies the extractors have nothing to do anyway.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.chunking.recursive.Processor
+    params:
+      <<: *defaults
+      id: chunker
+      chunk_size: 2000
+      chunk_overlap: 50
+
+  - class: trustgraph.extract.kg.agent.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-agent
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.definitions.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-definitions
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.ontology.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-ontology
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.relationships.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-relationships
+      concurrency: 1
+
+  - class: trustgraph.extract.kg.rows.Processor
+    params:
+      <<: *defaults
+      id: kg-extract-rows
+      concurrency: 1
+
+  - class: trustgraph.prompt.template.Processor
+    params:
+      <<: *defaults
+      id: prompt
+      concurrency: 1
--- a/dev-tools/proc-group/groups/llm.yaml
+++ b/dev-tools/proc-group/groups/llm.yaml
@ -0,0 +1,24 @@
+# LLM.  Outbound text-completion calls.  Isolated because the upstream
+# LLM API is often the bottleneck and the most likely thing to need
+# restart (provider changes, model changes, API flakiness).
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.model.text_completion.openai.Processor
+    params:
+      <<: *defaults
+      id: text-completion
+      max_output: 8192
+      temperature: 0.0
+
+  - class: trustgraph.model.text_completion.openai.Processor
+    params:
+      <<: *defaults
+      id: text-completion-rag
+      max_output: 8192
+      temperature: 0.0
--- a/dev-tools/proc-group/groups/rag.yaml
+++ b/dev-tools/proc-group/groups/rag.yaml
@ -0,0 +1,64 @@
+# RAG / retrieval / agent.  Query-time serving path.  Drives outbound
+# LLM calls via prompt-rag.  sparql-query lives here because it's a
+# read-side serving endpoint, not a backend writer.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.agent.orchestrator.Processor
+    params:
+      <<: *defaults
+      id: agent-manager
+
+  - class: trustgraph.retrieval.graph_rag.Processor
+    params:
+      <<: *defaults
+      id: graph-rag
+      concurrency: 1
+      entity_limit: 50
+      triple_limit: 30
+      edge_limit: 30
+      edge_score_limit: 10
+      max_subgraph_size: 100
+      max_path_length: 2
+
+  - class: trustgraph.retrieval.document_rag.Processor
+    params:
+      <<: *defaults
+      id: document-rag
+      doc_limit: 20
+
+  - class: trustgraph.retrieval.nlp_query.Processor
+    params:
+      <<: *defaults
+      id: nlp-query
+
+  - class: trustgraph.retrieval.structured_query.Processor
+    params:
+      <<: *defaults
+      id: structured-query
+
+  - class: trustgraph.retrieval.structured_diag.Processor
+    params:
+      <<: *defaults
+      id: structured-diag
+
+  - class: trustgraph.query.sparql.Processor
+    params:
+      <<: *defaults
+      id: sparql-query
+
+  - class: trustgraph.prompt.template.Processor
+    params:
+      <<: *defaults
+      id: prompt-rag
+      concurrency: 1
+
+  - class: trustgraph.agent.mcp_tool.Service
+    params:
+      <<: *defaults
+      id: mcp-tool
--- a/dev-tools/proc-group/groups/rows-store.yaml
+++ b/dev-tools/proc-group/groups/rows-store.yaml
@ -0,0 +1,20 @@
+# Rows store.  Cassandra-backed structured row query/write.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.query.rows.cassandra.Processor
+    params:
+      <<: *defaults
+      id: rows-query
+      cassandra_host: localhost
+
+  - class: trustgraph.storage.rows.cassandra.Processor
+    params:
+      <<: *defaults
+      id: rows-write
+      cassandra_host: localhost
--- a/dev-tools/proc-group/groups/triples-store.yaml
+++ b/dev-tools/proc-group/groups/triples-store.yaml
@ -0,0 +1,20 @@
+# Triples store.  Cassandra-backed RDF triple query/write.
+
+_defaults: &defaults
+  pubsub_backend: rabbitmq
+  rabbitmq_host: localhost
+  log_level: INFO
+
+processors:
+
+  - class: trustgraph.query.triples.cassandra.Processor
+    params:
+      <<: *defaults
+      id: triples-query
+      cassandra_host: localhost
+
+  - class: trustgraph.storage.triples.cassandra.Processor
+    params:
+      <<: *defaults
+      id: triples-write
+      cassandra_host: localhost
--- a/dev-tools/tests/agent_dag/analyse_trace.py
+++ b/dev-tools/tests/agent_dag/analyse_trace.py
@ -131,21 +131,21 @@ async def analyse(path, url, flow, user, collection):

    for i, msg in enumerate(messages):
        resp = msg.get("response", {})
-        chunk_type = resp.get("chunk_type", "?")
+        message_type = resp.get("message_type", "?")

-        if chunk_type == "explain":
+        if message_type == "explain":
            explain_id = resp.get("explain_id", "")
            explain_ids.append(explain_id)
-            print(f"  {i:3d}  {chunk_type}  {explain_id}")
+            print(f"  {i:3d}  {message_type}  {explain_id}")
        else:
-            print(f"  {i:3d}  {chunk_type}")
+            print(f"  {i:3d}  {message_type}")

        # Rule 7: message_id on content chunks
-        if chunk_type in ("thought", "observation", "answer"):
+        if message_type in ("thought", "observation", "answer"):
            mid = resp.get("message_id", "")
            if not mid:
                errors.append(
-                    f"[msg {i}] {chunk_type} chunk missing message_id"
+                    f"[msg {i}] {message_type} chunk missing message_id"
                )

    print()
--- a/docs/README.api-docs.ar.md
+++ b/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`، دون الكشف عن هيكل الوحدة الداخلية.
--- a/docs/README.api-docs.es.md
+++ b/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.
--- a/docs/README.api-docs.he.md
+++ b/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`, מבלי לחשוף את המבנה הפנימי של המודול.
--- a/docs/README.api-docs.hi.md
+++ b/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` से आयात करते हैं, आंतरिक मॉड्यूल संरचना को उजागर किए बिना।
--- a/docs/README.api-docs.md
+++ b/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.
-
--- a/docs/README.api-docs.pt.md
+++ b/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.
--- a/docs/README.api-docs.ru.md
+++ b/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`, не раскрывая внутреннюю структуру модуля.
--- a/docs/README.api-docs.sw.md
+++ b/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.
--- a/docs/README.api-docs.tr.md
+++ b/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.
--- a/docs/README.api-docs.zh-cn.md
+++ b/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，而无需暴露内部模块结构。
--- a/docs/README.ar.md
+++ b/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.
--- a/docs/README.es.md
+++ b/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.
--- a/docs/README.he.md
+++ b/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.
--- a/docs/README.hi.md
+++ b/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) देखें।
--- a/docs/README.md
+++ b/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.
-
--- a/docs/README.pt.md
+++ b/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.
--- a/docs/README.ru.md
+++ b/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.
--- a/docs/README.sw.md
+++ b/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.
--- a/docs/README.tr.md
+++ b/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.
--- a/docs/README.zh-cn.md
+++ b/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 文档。
--- a/docs/api-gateway-changes-v1.8-to-v2.1.ar.md
+++ b/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`**: إضافية، وليست مُفسرة.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.es.md
+++ b/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.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.he.md
+++ b/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`**: נוסף, לא משבש.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.hi.md
+++ b/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` एंडपॉइंट**: यह एक अतिरिक्त परिवर्तन है, जो पहले से ही मौजूद है।
--- a/docs/api-gateway-changes-v1.8-to-v2.1.pt.md
+++ b/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.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.ru.md
+++ b/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".
--- a/docs/api-gateway-changes-v1.8-to-v2.1.sw.md
+++ b/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.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.tr.md
+++ b/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.
--- a/docs/api-gateway-changes-v1.8-to-v2.1.zh-cn.md
+++ b/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` 端点**: 添加的，非破坏性。
--- a/docs/cli-changes-v1.8-to-v2.1.ar.md
+++ b/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`.
--- a/docs/cli-changes-v1.8-to-v2.1.es.md
+++ b/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**.
--- a/docs/cli-changes-v1.8-to-v2.1.he.md
+++ b/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`.
--- a/docs/cli-changes-v1.8-to-v2.1.hi.md
+++ b/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` हटा दिए गए**।
--- a/docs/cli-changes-v1.8-to-v2.1.pt.md
+++ b/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**.
--- a/docs/cli-changes-v1.8-to-v2.1.ru.md
+++ b/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` удалены**.
--- a/docs/cli-changes-v1.8-to-v2.1.sw.md
+++ b/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.
--- a/docs/cli-changes-v1.8-to-v2.1.tr.md
+++ b/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ı.
--- a/docs/cli-changes-v1.8-to-v2.1.zh-cn.md
+++ b/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` 已移除**。
--- a/docs/contributor-licence-agreement.ar.md
+++ b/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)
--- a/docs/contributor-licence-agreement.es.md
+++ b/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)
--- a/docs/contributor-licence-agreement.he.md
+++ b/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)
--- a/docs/contributor-licence-agreement.hi.md
+++ b/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) पर हस्ताक्षर करें।
--- a/docs/contributor-licence-agreement.md
+++ b/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)
-
--- a/docs/contributor-licence-agreement.pt.md
+++ b/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)
--- a/docs/contributor-licence-agreement.ru.md
+++ b/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)
--- a/docs/contributor-licence-agreement.sw.md
+++ b/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)
--- a/docs/contributor-licence-agreement.tr.md
+++ b/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.
--- a/docs/contributor-licence-agreement.zh-cn.md
+++ b/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)
--- a/docs/lang-index-ar.md
+++ b/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.
--- a/docs/lang-index-es.md
+++ b/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.
--- a/docs/lang-index-he.md
+++ b/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.
--- a/docs/lang-index-hi.md
+++ b/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.
--- a/docs/lang-index-pt.md
+++ b/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.
--- a/docs/lang-index-ru.md
+++ b/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.
--- a/docs/lang-index-sw.md
+++ b/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.
--- a/docs/lang-index-tr.md
+++ b/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.
--- a/docs/lang-index-zh-cn.md
+++ b/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.
--- a/docs/python-api.ar.md
+++ b/docs/python-api.ar.md
--- a/docs/python-api.es.md
+++ b/docs/python-api.es.md
--- a/docs/python-api.he.md
+++ b/docs/python-api.he.md
--- a/docs/python-api.hi.md
+++ b/docs/python-api.hi.md
--- a/docs/python-api.md
+++ b/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


 ---
-
--- a/docs/python-api.pt.md
+++ b/docs/python-api.pt.md
--- a/docs/python-api.ru.md
+++ b/docs/python-api.ru.md
--- a/docs/python-api.sw.md
+++ b/docs/python-api.sw.md
--- a/docs/python-api.tr.md
+++ b/docs/python-api.tr.md
--- a/docs/python-api.zh-cn.md
+++ b/docs/python-api.zh-cn.md
--- a/docs/tech-specs/__TEMPLATE.ar.md
+++ b/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]
+
+## المراجع
+
+[المراجع إذا كانت قابلة للتطبيق]
--- a/docs/tech-specs/__TEMPLATE.es.md
+++ b/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]
--- a/docs/tech-specs/__TEMPLATE.he.md
+++ b/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]
+
+## מקורות
+
+[מקורות, אם רלוונטיים]
--- a/docs/tech-specs/__TEMPLATE.hi.md
+++ b/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]
+
+## संदर्भ
+
+[यदि लागू हो, तो संदर्भ]
--- a/docs/tech-specs/__TEMPLATE.md
+++ b/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
--- a/docs/tech-specs/__TEMPLATE.pt.md
+++ b/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]
--- a/docs/tech-specs/__TEMPLATE.ru.md
+++ b/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]
+
+## Ссылки
+
+[Ссылки, если применимо]
--- a/docs/tech-specs/__TEMPLATE.sw.md
+++ b/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]
--- a/docs/tech-specs/__TEMPLATE.tr.md
+++ b/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]
--- a/docs/tech-specs/__TEMPLATE.zh-cn.md
+++ b/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]
--- a/docs/tech-specs/agent-explainability.ar.md
+++ b/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 الخاص به)
+إرسال المصادر بشكل مستمر (إرسال البيانات أثناء العمل، وليس دفعة واحدة في النهاية)
--- a/docs/tech-specs/agent-explainability.es.md
+++ b/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)
--- a/docs/tech-specs/agent-explainability.he.md
+++ b/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 שלו)
+פליטת מקורות מידע בסטרימינג (לשלוח תוך כדי פעולה, ולא במקשה בסוף)
--- a/docs/tech-specs/agent-explainability.hi.md
+++ b/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"
+```
+
+## भविष्य की योजनाएं (इस पुल अनुरोध में नहीं)
+
+डीएजी निर्भरताएँ (जब विश्लेषण एन, पिछले कई विश्लेषणों के परिणामों का उपयोग करता है)
+टूल-विशिष्ट उत्पत्ति लिंकिंग (नॉलेजक्वेरी → इसका ग्राफआरएजी ट्रेस)
+स्ट्रीमिंग उत्पत्ति उत्सर्जन (जैसे-जैसे उत्पन्न होता है, अंत में बैच न करें)
--- a/docs/tech-specs/agent-explainability.md
+++ b/docs/tech-specs/agent-explainability.md
@ -1,272 +1,217 @@
+---
+layout: default
+title: "Agent Explainability: Provenance Recording"
+parent: "Tech Specs"
+---
+
 # Agent Explainability: Provenance Recording

+## Status
+
+Implemented
+
 ## Overview

-Add provenance recording to the React agent loop so agent sessions can be traced and debugged using the same explainability infrastructure as GraphRAG.
+Agent sessions are traced and debugged using the same explainability infrastructure as GraphRAG and Document RAG. Provenance is written to `urn:graph:retrieval` and delivered inline on the explain stream.

-**Design Decisions:**
- Write to `urn:graph:retrieval` (generic explainability graph)
- Linear dependency chain for now (analysis N → wasDerivedFrom → analysis N-1)
- Tools are opaque black boxes (record input/output only)
- DAG support deferred to future iteration
+The canonical vocabulary for all predicates and types is published as an OWL ontology at `specs/ontology/trustgraph.ttl`.

 ## Entity Types

-Both GraphRAG and Agent use PROV-O as the base ontology with TrustGraph-specific subtypes:
+All services use PROV-O as the base ontology with TrustGraph-specific subtypes.

 ### GraphRAG Types
-| Entity | PROV-O Type | TG Types | Description |
-|--------|-------------|----------|-------------|
-| Question | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | The user's query |
-| Exploration | `prov:Entity` | `tg:Exploration` | Edges retrieved from knowledge graph |
-| Focus | `prov:Entity` | `tg:Focus` | Selected edges with reasoning |
-| Synthesis | `prov:Entity` | `tg:Synthesis` | Final answer |
-
-### Agent Types
-| Entity | PROV-O Type | TG Types | Description |
-|--------|-------------|----------|-------------|
-| Question | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | The user's query |
-| Analysis | `prov:Entity` | `tg:Analysis` | Each think/act/observe cycle |
-| Conclusion | `prov:Entity` | `tg:Conclusion` | Final answer |
+| Entity | TG Types | Description |
+|--------|----------|-------------|
+| Question | `tg:Question`, `tg:GraphRagQuestion` | The user's query |
+| Grounding | `tg:Grounding` | Concept extraction from query |
+| Exploration | `tg:Exploration` | Edges retrieved from knowledge graph |
+| Focus | `tg:Focus` | Selected edges with reasoning |
+| Synthesis | `tg:Synthesis`, `tg:Answer` | Final answer |

 ### Document RAG Types
-| Entity | PROV-O Type | TG Types | Description |
-|--------|-------------|----------|-------------|
-| Question | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | The user's query |
-| Exploration | `prov:Entity` | `tg:Exploration` | Chunks retrieved from document store |
-| Synthesis | `prov:Entity` | `tg:Synthesis` | Final answer |
+| Entity | TG Types | Description |
+|--------|----------|-------------|
+| Question | `tg:Question`, `tg:DocRagQuestion` | The user's query |
+| Grounding | `tg:Grounding` | Concept extraction from query |
+| Exploration | `tg:Exploration` | Chunks retrieved from document store |
+| Synthesis | `tg:Synthesis`, `tg:Answer` | Final answer |

-**Note:** Document RAG uses a subset of GraphRAG's types (no Focus step since there's no edge selection/reasoning phase).
+### Agent Types (React)
+| Entity | TG Types | Description |
+|--------|----------|-------------|
+| Question | `tg:Question`, `tg:AgentQuestion` | The user's query (session start) |
+| PatternDecision | `tg:PatternDecision` | Meta-router routing decision |
+| Analysis | `tg:Analysis`, `tg:ToolUse` | One think/act cycle |
+| Thought | `tg:Reflection`, `tg:Thought` | Agent reasoning (sub-entity of Analysis) |
+| Observation | `tg:Reflection`, `tg:Observation` | Tool result (standalone entity) |
+| Conclusion | `tg:Conclusion`, `tg:Answer` | Final answer |
+
+### Agent Types (Orchestrator — Plan)
+| Entity | TG Types | Description |
+|--------|----------|-------------|
+| Plan | `tg:Plan` | Structured plan of steps |
+| StepResult | `tg:StepResult`, `tg:Answer` | Result from executing one plan step |
+| Synthesis | `tg:Synthesis`, `tg:Answer` | Final synthesised answer |
+
+### Agent Types (Orchestrator — Supervisor)
+| Entity | TG Types | Description |
+|--------|----------|-------------|
+| Decomposition | `tg:Decomposition` | Question decomposed into sub-goals |
+| Finding | `tg:Finding`, `tg:Answer` | Result from a sub-agent |
+| Synthesis | `tg:Synthesis`, `tg:Answer` | Final synthesised answer |
+
+### Mixin Types
+| Type | Description |
+|------|-------------|
+| `tg:Answer` | Unifying type for terminal answers (Synthesis, Conclusion, Finding, StepResult) |
+| `tg:Reflection` | Unifying type for intermediate commentary (Thought, Observation) |
+| `tg:ToolUse` | Applied to Analysis when a tool is invoked |
+| `tg:Error` | Applied to Observation events where a failure occurred (tool error or LLM parse error) |

 ### Question Subtypes

-All Question entities share `tg:Question` as a base type but have a specific subtype to identify the retrieval mechanism:
-
 | Subtype | URI Pattern | Mechanism |
 |---------|-------------|-----------|
 | `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | Knowledge graph RAG |
 | `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | Document/chunk RAG |
-| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | ReAct agent |
+| `tg:AgentQuestion` | `urn:trustgraph:agent:session:{uuid}` | Agent orchestrator |

-This allows querying all questions via `tg:Question` while filtering by specific mechanism via the subtype.
+## Provenance Chains

-## Provenance Model
+All chains use `prov:wasDerivedFrom` links. Each entity is a `prov:Entity`.
+
+### GraphRAG

 ```
-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 → Grounding → Exploration → Focus → Synthesis
 ```

-### Document RAG Provenance Model
+### Document 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
+Question → Grounding → Exploration → Synthesis
 ```

-## Changes Required
+### Agent React

-### 1. Schema Changes
-
-**File:** `trustgraph-base/trustgraph/schema/services/agent.py`
-
-Add `session_id` and `collection` fields to `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
+```
+Question → PatternDecision → Analysis(1) → Observation(1) → Analysis(2) → ... → Conclusion
 ```

-**File:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
+The PatternDecision entity records which execution pattern the meta-router selected. It is only emitted on the first iteration when routing occurs.

-Update translator to handle `session_id` and `collection` in both `to_pulsar()` and `from_pulsar()`.
+Thought sub-entities derive from their parent Analysis. Observation entities derive from their parent Analysis (or from a sub-trace entity if the tool produced its own explainability, e.g. a GraphRAG query).

-### 2. Add Explainability Producer to Agent Service
+### Agent Plan-then-Execute

-**File:** `trustgraph-flow/trustgraph/agent/react/service.py`
-
-Register an "explainability" producer (same pattern as GraphRAG):
-```python
-from ... base import ProducerSpec
-from ... schema import Triples
-
-# In __init__:
-self.register_specification(
-    ProducerSpec(
-        name = "explainability",
-        schema = Triples,
-    )
-)
+```
+Question → PatternDecision → Plan → StepResult(0) → StepResult(1) → ... → Synthesis
 ```

-### 3. Provenance Triple Generation
+### Agent Supervisor

-**File:** `trustgraph-base/trustgraph/provenance/agent.py`
-
-Create helper functions (similar to GraphRAG's `question_triples`, `exploration_triples`, etc.):
-```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),
-    ]
+```
+Question → PatternDecision → Decomposition → [fan-out sub-agents]
+                                           → Finding(0) → Finding(1) → ... → Synthesis
 ```

-### 4. Type Definitions
+Each sub-agent runs its own session with `wasDerivedFrom` linking back to the parent's Decomposition. Findings derive from their sub-agent's Conclusion.

-**File:** `trustgraph-base/trustgraph/provenance/namespaces.py`
+## Predicates

-Add explainability entity types and agent predicates:
-```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"
+### Session / Question
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:query` | string | The user's query text |
+| `prov:startedAtTime` | string | ISO timestamp |

-# Agent predicates
-TG_THOUGHT = TG + "thought"
-TG_ACTION = TG + "action"
-TG_ARGUMENTS = TG + "arguments"
-TG_OBSERVATION = TG + "observation"
-TG_ANSWER = TG + "answer"
-```
+### Pattern Decision
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:pattern` | string | Selected pattern (react, plan-then-execute, supervisor) |
+| `tg:taskType` | string | Identified task type (general, research, etc.) |

-## Files Modified
+### Analysis (Iteration)
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:action` | string | Tool name selected by the agent |
+| `tg:arguments` | string | JSON-encoded arguments |
+| `tg:thought` | IRI | Link to Thought sub-entity |
+| `tg:toolCandidate` | string | Tool name available to the LLM (one per candidate) |
+| `tg:stepNumber` | integer | 1-based iteration counter |
+| `tg:llmDurationMs` | integer | LLM call duration in milliseconds |
+| `tg:inToken` | integer | Input token count |
+| `tg:outToken` | integer | Output token count |
+| `tg:llmModel` | string | Model identifier |

-| File | Change |
-|------|--------|
-| `trustgraph-base/trustgraph/schema/services/agent.py` | Add session_id and collection to AgentRequest |
-| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Update translator for new fields |
-| `trustgraph-base/trustgraph/provenance/namespaces.py` | Add entity types, agent predicates, and Document RAG predicates |
-| `trustgraph-base/trustgraph/provenance/triples.py` | Add TG types to GraphRAG triple builders, add Document RAG triple builders |
-| `trustgraph-base/trustgraph/provenance/uris.py` | Add Document RAG URI generators |
-| `trustgraph-base/trustgraph/provenance/__init__.py` | Export new types, predicates, and Document RAG functions |
-| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Add explain_id, explain_graph, and explain_triples to DocumentRagResponse |
-| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Update DocumentRagResponseTranslator for explainability fields including inline triples |
-| `trustgraph-flow/trustgraph/agent/react/service.py` | Add explainability producer + recording logic |
-| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Add explainability callback and emit provenance triples |
-| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Add explainability producer and wire up callback |
-| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Handle agent trace types |
-| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | List agent sessions alongside GraphRAG |
+### Observation
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:document` | IRI | Librarian document reference |
+| `tg:toolDurationMs` | integer | Tool execution time in milliseconds |
+| `tg:toolError` | string | Error message (tool failure or LLM parse error) |

-## Files Created
+When `tg:toolError` is present, the Observation also carries the `tg:Error` mixin type.

-| File | Purpose |
-|------|---------|
-| `trustgraph-base/trustgraph/provenance/agent.py` | Agent-specific triple generators |
+### Conclusion / Synthesis
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:document` | IRI | Librarian document reference |
+| `tg:terminationReason` | string | Why the loop stopped |
+| `tg:inToken` | integer | Input token count (synthesis LLM call) |
+| `tg:outToken` | integer | Output token count |
+| `tg:llmModel` | string | Model identifier |

-## CLI Updates
+Termination reason values:
+- `final-answer` -- LLM produced a confident answer (react)
+- `plan-complete` -- all plan steps executed (plan-then-execute)
+- `subagents-complete` -- all sub-agents reported back (supervisor)

-**Detection:** Both GraphRAG and Agent Questions have `tg:Question` type. Distinguished by:
-1. URI pattern: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
-2. Derived entities: `tg:Analysis` (agent) vs `tg:Exploration` (GraphRAG)
+### Decomposition
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:subagentGoal` | string | Goal assigned to a sub-agent (one per goal) |
+| `tg:inToken` | integer | Input token count |
+| `tg:outToken` | integer | Output token count |

-**`list_explain_traces.py`:**
- Shows Type column (Agent vs GraphRAG)
+### Plan
+| Predicate | Type | Description |
+|-----------|------|-------------|
+| `tg:planStep` | string | Goal for a plan step (one per step) |
+| `tg:inToken` | integer | Input token count |
+| `tg:outToken` | integer | Output token count |

-**`show_explain_trace.py`:**
- Auto-detects trace type
- Agent rendering shows: Question → Analysis step(s) → Conclusion
+### Token Counts on RAG Events

-## Backwards Compatibility
+Grounding, Focus, and Synthesis events on GraphRAG and Document RAG also carry `tg:inToken`, `tg:outToken`, and `tg:llmModel` for the LLM calls associated with that step.

- `session_id` defaults to `""` - old requests work, just won't have provenance
- `collection` defaults to `"default"` - reasonable fallback
- CLI gracefully handles both trace types
+## Error Handling
+
+Tool execution errors and LLM parse errors are captured as Observation events rather than crashing the agent:
+
+- The error message is recorded on `tg:toolError`
+- The Observation carries the `tg:Error` mixin type
+- The error text becomes the observation content, visible to the LLM on the next iteration
+- The provenance chain is preserved (Observation derives from Analysis)
+- The agent gets another iteration to retry or choose a different approach
+
+## Vocabulary Reference
+
+The full OWL ontology covering all classes and predicates is at `specs/ontology/trustgraph.ttl`.

 ## Verification

 ```bash
-# Run an agent query
-tg-invoke-agent -q "What is the capital of France?"
+# Run an agent query with explainability
+tg-invoke-agent -q "What is quantum computing?" -x

-# List traces (should show agent sessions with Type column)
-tg-list-explain-traces -U trustgraph -C default
+# Run with token usage
+tg-invoke-agent -q "What is quantum computing?" --show-usage

-# Show agent trace
-tg-show-explain-trace "urn:trustgraph:agent:xxx"
+# GraphRAG with explainability
+tg-invoke-graph-rag -q "Tell me about AI" -x
+
+# Document RAG with explainability
+tg-invoke-document-rag -q "Summarize the findings" -x
 ```
-
-## Future Work (Not This PR)
-
- DAG dependencies (when analysis N uses results from multiple prior analyses)
- Tool-specific provenance linking (KnowledgeQuery → its GraphRAG trace)
- Streaming provenance emission (emit as we go, not batch at end)
--- a/docs/tech-specs/agent-explainability.pt.md
+++ b/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)
--- a/docs/tech-specs/agent-explainability.ru.md
+++ b/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)
+Потоковая передача метаданных (отправлять по мере выполнения, а не пакетами в конце)
--- a/docs/tech-specs/agent-explainability.sw.md
+++ b/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)
--- a/Show more
+++ b/Show more