Merge remote-tracking branch 'origin/master' into ts-port

.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.4.999
 
       - name: Setup environment
         run: python3 -m venv env

.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
+    name: Build ${{ matrix.container }} (${{ matrix.platform }})
-    runs-on: ubuntu-24.04
     permissions:
       contents: write
       id-token: write
@@ -52,14 +51,24 @@ jobs:
     strategy:
       matrix:
         container:
-          - trustgraph-base
+          - base
-          - trustgraph-flow
+          - flow
-          - trustgraph-bedrock
+          - bedrock
-          - trustgraph-vertexai
+          - vertexai
-          - trustgraph-hf
+          - hf
-          - trustgraph-ocr
+          - ocr
-          - trustgraph-unstructured
+          - unstructured
-          - trustgraph-mcp
+          - 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
+      - name: Build container
-        run: make update-package-versions VERSION=${{ steps.version.outputs.VERSION }}
+        run: make platform-${{ matrix.container }}-${{ matrix.platform }} VERSION=${{ steps.version.outputs.VERSION }}
 
-      - name: Build container - ${{ matrix.container }}
+      - name: Push container
-        run: make container-${{ matrix.container }} VERSION=${{ steps.version.outputs.VERSION }}
+        run: make push-platform-${{ matrix.container }}-${{ matrix.platform }} VERSION=${{ steps.version.outputs.VERSION }}
 
-      - name: Push container - ${{ matrix.container }}
+  combine-manifests:
-        run: make push-${{ matrix.container }} VERSION=${{ steps.version.outputs.VERSION }}
 
+    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 }}

.gitignore

@@ -15,4 +15,5 @@ trustgraph-parquet/trustgraph/parquet_version.py
 trustgraph-vertexai/trustgraph/vertexai_version.py
 trustgraph-unstructured/trustgraph/unstructured_version.py
 trustgraph-mcp/trustgraph/mcp_version.py
+trustgraph/trustgraph/trustgraph_version.py
 vertexai/

Makefile

@@ -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
+some-containers: container-base container-flow container-unstructured
-	${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} .
 
 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
+container-%: update-package-versions
-	${DOCKER} build -f containers/Containerfile.base -t ${CONTAINER_BASE}/trustgraph-base:${VERSION} .
+	${DOCKER} build \
+	    -f containers/Containerfile.${@:container-%=%} \
+	    -t ${CONTAINER_BASE}/trustgraph-${@:container-%=%}:${VERSION} .
 
-container-trustgraph-flow: update-package-versions
+# Multi-arch: build both platforms sequentially into one manifest (local use)
-	${DOCKER} build -f containers/Containerfile.flow -t ${CONTAINER_BASE}/trustgraph-flow:${VERSION} .
+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
+# Multi-arch: build a single platform image (for parallel CI)
-	${DOCKER} build -f containers/Containerfile.bedrock -t ${CONTAINER_BASE}/trustgraph-bedrock:${VERSION} .
+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
+platform-%-arm64: update-package-versions
-	${DOCKER} build -f containers/Containerfile.vertexai -t ${CONTAINER_BASE}/trustgraph-vertexai:${VERSION} .
+	${DOCKER} build --platform linux/arm64 \
+	    -f containers/Containerfile.${@:platform-%-arm64=%} \
+	    -t ${CONTAINER_BASE}/trustgraph-${@:platform-%-arm64=%}:${VERSION}-arm64 .
 
-container-trustgraph-hf: update-package-versions
+# Push a single platform image
-	${DOCKER} build -f containers/Containerfile.hf -t ${CONTAINER_BASE}/trustgraph-hf:${VERSION} .
+push-platform-%-amd64:
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-platform-%-amd64=%}:${VERSION}-amd64
 
-container-trustgraph-ocr: update-package-versions
+push-platform-%-arm64:
-	${DOCKER} build -f containers/Containerfile.ocr -t ${CONTAINER_BASE}/trustgraph-ocr:${VERSION} .
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-platform-%-arm64=%}:${VERSION}-arm64
 
-container-trustgraph-unstructured: update-package-versions
+# Combine per-platform images into a multi-arch manifest
-	${DOCKER} build -f containers/Containerfile.unstructured -t ${CONTAINER_BASE}/trustgraph-unstructured:${VERSION} .
+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
+# Push a container
-	${DOCKER} build -f containers/Containerfile.mcp -t ${CONTAINER_BASE}/trustgraph-mcp:${VERSION} .
+push-container-%:
+	${DOCKER} push \
+	    ${CONTAINER_BASE}/trustgraph-${@:push-container-%=%}:${VERSION}
 
-# Individual container push targets
+# Push a manifest (from local multi-arch build)
-push-trustgraph-base:
+push-manifest-%:
-	${DOCKER} push ${CONTAINER_BASE}/trustgraph-base:${VERSION}
+	${DOCKER} manifest push \
-
+	    ${CONTAINER_BASE}/trustgraph-${@:push-manifest-%=%}:${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}
 
 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

README.md

@@ -7,6 +7,8 @@
 [![Discord](https://img.shields.io/discord/1251652173201149994
 )](https://discord.gg/sQMwkRz5GX) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/trustgraph-ai/trustgraph)
 
+[![trustgraph on Cossmology](https://vpxherzezesqifjloaxx.supabase.co/functions/v1/generate-badge?shortname=trustgraph&siteUrl=https%3A%2F%2Fcossmology.com&v=2)](https://cossmology.com/organizations/trustgraph)
+
 [**Website**](https://trustgraph.ai) | [**Docs**](https://docs.trustgraph.ai) | [**YouTube**](https://www.youtube.com/@TrustGraphAI?sub_confirmation=1) | [**Configuration Terminal**](https://config-ui.demo.trustgraph.ai/) | [**Discord**](https://discord.gg/sQMwkRz5GX) | [**Blog**](https://blog.trustgraph.ai/subscribe)
 
 <a href="https://trendshift.io/repositories/17291" target="_blank"><img src="https://trendshift.io/api/badge/repositories/17291" alt="trustgraph-ai%2Ftrustgraph | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

containers/Containerfile.hf

@@ -1,22 +1,22 @@
 
-# ----------------------------------------------------------------------------
+# Torch is stable and compiles for ARM64 and AMD64 on Python 3.12
-# Build an AI container.  This does the torch install which is huge, and I
-# like to avoid re-doing this.
-# ----------------------------------------------------------------------------
 
 FROM docker.io/fedora:42 AS ai
 
 ENV PIP_BREAK_SYSTEM_PACKAGES=1
 
-RUN dnf install -y python3.13 && \
+RUN dnf install -y python3.12 && \
-  alternatives --install /usr/bin/python python /usr/bin/python3.13 1 && \
+  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 \
+# This won't work on ARM
-    --index-url https://download.pytorch.org/whl/cpu
+#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 \

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.
+

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

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

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

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

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

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

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

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

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

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()

docs/README.api-docs.ar.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: "إنشاء الوثائق تلقائيًا"
+parent: "Arabic (Beta)"
+---
+
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، وعلامات HTML.
+- لا تقم بترجمة الكود الموجود داخل علامات backticks أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+
+# إنشاء الوثائق تلقائيًا
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## وثائق واجهة برمجة تطبيقات REST و WebSocket
+
+- `specs/build-docs.sh` - يقوم بإنشاء وثائق REST و WebSocket من مواصفات OpenAPI و AsyncAPI.
+
+## وثائق واجهة برمجة تطبيقات Python
+
+يتم إنشاء وثائق واجهة برمجة تطبيقات Python من سلاسل التوثيق باستخدام نص برمجي Python مخصص يقوم بتحليل حزمة `trustgraph.api`.
+
+### المتطلبات الأساسية
+
+يجب أن تكون حزمة trustgraph قابلة للاستيراد. إذا كنت تعمل في بيئة تطوير:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### إنشاء الوثائق
+
+من دليل الوثائق:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+يولد هذا ملف Markdown واحد يحتوي على وثائق واجهة برمجة تطبيقات كاملة، ويظهر:
+- دليل التثبيت والإرشادات السريعة
+- عبارات الاستيراد لكل فئة/نوع
+- سلاسل التوثيق الكاملة مع أمثلة
+- جدول محتويات مُنظمة حسب الفئة
+
+### أسلوب الوثائق
+
+تتبع جميع سلاسل التوثيق تنسيق Google:
+- ملخص موجز في سطر واحد
+- وصف تفصيلي
+- قسم Args مع أوصاف المعلمات
+- قسم Returns
+- قسم Raises (عندما يكون ذلك مناسبًا)
+- كتل كود مع تمييز نحوي مناسب
+
+تعرض الوثائق التي تم إنشاؤها واجهة برمجة التطبيقات العامة تمامًا كما يستوردها المستخدمون من `trustgraph.api`، دون الكشف عن هيكل الوحدة الداخلية.

docs/README.api-docs.es.md

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

docs/README.api-docs.he.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: "יצירת תיעוד אוטומטית"
+parent: "Hebrew (Beta)"
+---
+
+# יצירת תיעוד אוטומטית
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## תיעוד REST ו-WebSocket API
+
+- `specs/build-docs.sh` - יוצר את תיעוד ה-REST וה-WebSocket מהמפרטים של OpenAPI ו-AsyncAPI.
+
+## תיעוד API בפייתון
+
+תיעוד ה-API בפייתון נוצר מתוך מחרוזות תיאור (docstrings) באמצעות סקריפט פייתון מותאם, אשר סוקר את החבילה `trustgraph.api`.
+
+### תנאים מוקדמים
+
+חבילת `trustgraph` חייבת להיות ניתנת לייבוא. אם אתם עובדים בסביבת פיתוח:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### יצירת תיעוד
+
+מתוך תיקיית התיעוד:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+זה יוצר קובץ Markdown אחד עם תיעוד API מלא, המציג:
+- מדריך התקנה והתחלה מהירה
+- הצהרות ייבוא עבור כל מחלקה/סוג
+- מחרוזות תיאור מלאות עם דוגמאות
+- תוכן עזר מאורגן לפי קטגוריות
+
+### סגנון התיעוד
+
+כל מחרוזות התיאור עוקבות אחר פורמט Google:
+- סיכום קצר בשורה אחת
+- תיאור מפורט
+- סעיף "Args" עם תיאורי פרמטרים
+- סעיף "Returns"
+- סעיף "Raises" (במידת הצורך)
+- בלוקי קוד לדוגמה עם הדגשת תחביר מתאימה
+
+התיעוד שנוצר מציג את ה-API הציבורי בדיוק כפי שהמשתמשים מייבאים אותו מ-`trustgraph.api`, מבלי לחשוף את המבנה הפנימי של המודול.

docs/README.api-docs.hi.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: "स्वचालित रूप से दस्तावेज़ उत्पन्न करना"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर के कोड का अनुवाद न करें।
+- केवल अनुवादित पाठ प्रस्तुत करें, बिना किसी प्रारंभिक या स्पष्टीकरण के।
+
+अनुवाद करने के लिए पाठ:
+
+# स्वचालित रूप से दस्तावेज़ उत्पन्न करना
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## REST और WebSocket API दस्तावेज़
+
+- `specs/build-docs.sh` - OpenAPI और AsyncAPI विनिर्देशों से REST और WebSocket दस्तावेज़ बनाता है।
+
+## पायथन API दस्तावेज़
+
+पायथन API दस्तावेज़, `trustgraph.api` पैकेज का विश्लेषण करके एक कस्टम पायथन स्क्रिप्ट का उपयोग करके docstrings से उत्पन्न होते हैं।
+
+### पूर्व आवश्यकताएँ
+
+trustgraph पैकेज आयात करने योग्य होना चाहिए। यदि आप एक विकास वातावरण में काम कर रहे हैं, तो:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### दस्तावेज़ उत्पन्न करना
+
+दस्तावेज़ निर्देशिका से:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+यह एक एकल Markdown फ़ाइल उत्पन्न करता है जिसमें संपूर्ण API दस्तावेज़ शामिल है, जिसमें निम्नलिखित शामिल हैं:
+- स्थापना और त्वरित शुरुआत गाइड
+- प्रत्येक वर्ग/प्रकार के लिए आयात कथन
+- पूर्ण docstrings के साथ उदाहरण
+- श्रेणियों द्वारा व्यवस्थित सामग्री तालिका
+
+### दस्तावेज़ शैली
+
+सभी docstrings Google-शैली का पालन करते हैं:
+- संक्षिप्त एक-पंक्ति सारांश
+- विस्तृत विवरण
+- पैरामीटर विवरण के साथ Args अनुभाग
+- रिटर्न अनुभाग
+- प्रासंगिक होने पर Raises अनुभाग
+- उचित सिंटैक्स हाइलाइटिंग के साथ उदाहरण कोड ब्लॉक
+
+उत्पन्न दस्तावेज़ सार्वजनिक API को ठीक उसी तरह दिखाता है जैसे उपयोगकर्ता इसे `trustgraph.api` से आयात करते हैं, आंतरिक मॉड्यूल संरचना को उजागर किए बिना।

docs/README.api-docs.md

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

docs/README.api-docs.pt.md

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

docs/README.api-docs.ru.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: "Автоматическое создание документации"
+parent: "Russian (Beta)"
+---
+
+# Автоматическое создание документации
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## Документация REST и WebSocket API
+
+- `specs/build-docs.sh` - Создает документацию для REST и WebSocket API на основе спецификаций OpenAPI и AsyncAPI.
+
+## Документация Python API
+
+Документация Python API генерируется из docstrings с использованием пользовательского скрипта Python, который анализирует пакет `trustgraph.api`.
+
+### Требования
+
+Пакет `trustgraph` должен быть импортируемым. Если вы работаете в среде разработки:
+
+```bash
+cd trustgraph-base
+pip install -e .
+```
+
+### Генерация документации
+
+Из каталога `docs`:
+
+```bash
+cd docs
+python3 generate-api-docs.py > python-api.md
+```
+
+Это создает один файл Markdown с полной документацией API, в котором показаны:
+- Инструкции по установке и быстрому запуску
+- Заявления импорта для каждого класса/типа
+- Полные docstrings с примерами
+- Содержание, организованное по категориям
+
+### Стиль документации
+
+Все docstrings следуют формату Google-style:
+- Краткое однострочное описание
+- Подробное описание
+- Раздел "Args" с описаниями параметров
+- Раздел "Returns"
+- Раздел "Raises" (при необходимости)
+- Блоки с примерами кода с правильной подсветкой синтаксиса
+
+Сгенерированная документация отображает публичный API точно так, как его импортируют из `trustgraph.api`, не раскрывая внутреннюю структуру модуля.

docs/README.api-docs.sw.md

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

docs/README.api-docs.tr.md

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

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

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

docs/README.ar.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: "وثائق TrustGraph"
+parent: "Arabic (Beta)"
+---
+
+**تعليمات مهمة:**
+
+- الحفاظ على جميع تنسيقات Markdown، والعناوين، والروابط، ووسوم HTML.
+- لا تترجم أي كود داخل علامات التنصيص المزدوجة أو كتل الكود.
+- قم بإخراج النص المترجم فقط، بدون أي مقدمات أو تفسيرات.
+
+النص المراد ترجمته:
+# وثائق TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+مرحبًا بكم في TrustGraph! للحصول على وثائق شاملة، يرجى زيارة:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+يتضمن الموقع الرئيسي الوثائق:
+
+- **[نظرة عامة](https://docs.trustgraph.ai/overview)** - مقدمة لمفاهيم وهيكل TrustGraph
+- **[دليل المستخدم](https://docs.trustgraph.ai/guides)** - دروس تعليمية خطوة بخطوة وإرشادات
+- **[التثبيت](https://docs.trustgraph.ai/deployment)** - خيارات التثبيت والإعداد
+- **[مرجع](https://docs.trustgraph.ai/reference)** - مواصفات API ووثائق سطر الأوامر
+
+## البدء
+
+**هل أنت جديد في TrustGraph؟** ابدأ بـ [نظرة عامة](https://docs.trustgraph.ai/overview) لفهم النظام.
+
+**هل أنت مستعد للتثبيت؟** تحقق من [دليل التثبيت](https://docs.trustgraph.ai/deployment).
+
+**هل تقوم بدمج الكود؟** راجع [مرجع API](https://docs.trustgraph.ai/reference) للحصول على وثائق REST و WebSocket و SDK.

docs/README.es.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "Documentación de TrustGraph"
+parent: "Spanish (Beta)"
+---
+
+# Documentación de TrustGraph
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+¡Bienvenido a TrustGraph! Para una documentación completa, por favor visite:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+El sitio principal de documentación incluye:
+
+- **[Descripción general](https://docs.trustgraph.ai/overview)** - Introducción a los conceptos y la arquitectura de TrustGraph
+- **[Guías](https://docs.trustgraph.ai/guides)** - Tutoriales paso a paso y guías de cómo hacerlo
+- **[Implementación](https://docs.trustgraph.ai/deployment)** - Opciones de implementación y configuración
+- **[Referencia](https://docs.trustgraph.ai/reference)** - Especificaciones de la API y documentación de la línea de comandos
+
+## Primeros Pasos
+
+**¿Eres nuevo en TrustGraph?** Comienza con la [Descripción general](https://docs.trustgraph.ai/overview) para comprender el sistema.
+
+**¿Listo para implementar?** Consulta la [Guía de implementación](https://docs.trustgraph.ai/deployment).
+
+**¿Integrando con código?** Consulta la [Referencia de la API](https://docs.trustgraph.ai/reference) para la documentación de REST, WebSocket y SDK.

docs/README.he.md

@@ -0,0 +1,34 @@
+---
+layout: default
+title: "TrustGraph Documentation"
+parent: "Hebrew (Beta)"
+---
+
+**הוראות חשובות:**
+- שמרו על כל הפורמט של Markdown, כותרות, קישורים ותגי HTML.
+- אל תתרגמו קוד בתוך סימוני backticks או בלוקי קוד.
+- צרו רק את הטקסט המתורגם, ללא הקדמה או הסברים.
+
+טקסט לתרגום:
+# TrustGraph Documentation
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+ברוכים הבאים ל-TrustGraph! עבור תיעוד מקיף, אנא בקרו ב:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+אתר התיעוד הראשי כולל:
+
+- **[סקירה](https://docs.trustgraph.ai/overview)** - מבוא להגדרות ואדריכלות של TrustGraph
+- **[מדריכים](https://docs.trustgraph.ai/guides)** - מדריכים וורסטיים
+- **[התקנה](https://docs.trustgraph.ai/deployment)** - אפשרויות התקנה והגדרות
+- **[מדריך](https://docs.trustgraph.ai/reference)** - ספקציפיות API ותיעוד CLI
+
+## התחלה
+
+**חדש ב-TrustGraph?** התחילו עם [הסקירה](https://docs.trustgraph.ai/overview) כדי להבין את המערכת.
+
+**מוכנים להתקין?** בדקו את [מדריך ההתקנה](https://docs.trustgraph.ai/deployment).
+
+**שילוב עם קוד?** עיינו ב-[מדריך ה-API](https://docs.trustgraph.ai/reference) עבור תיעוד REST, WebSocket ו-SDK.

docs/README.hi.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: "ट्रस्टग्राफ दस्तावेज़"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown स्वरूपण, हेडर, लिंक और HTML टैग को बरकरार रखें।
+- बैकटिक या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट प्रदान करें, बिना किसी संवाद पूर्व-परिभाषा या स्पष्टीकरण के।
+
+अनुवाद के लिए पाठ:
+# ट्रस्टग्राफ दस्तावेज़
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+ट्रस्टग्राफ में आपका स्वागत है! व्यापक दस्तावेज़ के लिए, कृपया इस पर जाएँ:
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+मुख्य दस्तावेज़ साइट में शामिल हैं:
+
+- **[अवलोकन](https://docs.trustgraph.ai/overview)** - ट्रस्टग्राफ अवधारणाओं और वास्तुकला का परिचय
+- **[निर्देश](https://docs.trustgraph.ai/guides)** - चरण-दर-चरण ट्यूटोरियल और कैसे करें गाइड
+- **[परिनियोजन](https://docs.trustgraph.ai/deployment)** - परिनियोजन विकल्प और कॉन्फ़िगरेशन
+- **[संदर्भ](https://docs.trustgraph.ai/reference)** - एपीआई विनिर्देश और कमांड-लाइन दस्तावेज़
+
+## शुरुआत कैसे करें
+
+**क्या आप ट्रस्टग्राफ के नए हैं?** सिस्टम को समझने के लिए [अवलोकन](https://docs.trustgraph.ai/overview) से शुरुआत करें।
+
+**क्या आप परिनियोजित करने के लिए तैयार हैं?** [परिनियोजन गाइड](https://docs.trustgraph.ai/deployment) देखें।
+
+**कोड के साथ एकीकृत करना?** REST, WebSocket और SDK दस्तावेज़ के लिए [एपीआई संदर्भ](https://docs.trustgraph.ai/reference) देखें।

docs/README.md

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

docs/README.pt.md

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

docs/README.ru.md

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

docs/README.sw.md

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

docs/README.tr.md

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

docs/README.zh-cn.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: "TrustGraph 文档"
+parent: "Chinese (Beta)"
+---
+
+# TrustGraph 文档
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+欢迎使用 TrustGraph！为了获得全面的文档，请访问：
+
+## 📖 [https://docs.trustgraph.ai](https://docs.trustgraph.ai)
+
+主文档站点包含：
+
+- **[概述](https://docs.trustgraph.ai/overview)** - 介绍 TrustGraph 的概念和架构
+- **[指南](https://docs.trustgraph.ai/guides)** - 逐步教程和操作指南
+- **[部署](https://docs.trustgraph.ai/deployment)** - 部署选项和配置
+- **[参考](https://docs.trustgraph.ai/reference)** - API 规范和 CLI 文档
+
+## 快速入门
+
+**您是 TrustGraph 的新手吗？** 请从 [概述](https://docs.trustgraph.ai/overview) 开始，了解系统。
+
+**准备部署了吗？** 请查看 [部署指南](https://docs.trustgraph.ai/deployment)。
+
+**要与代码集成？** 请查看 [API 参考](https://docs.trustgraph.ai/reference)，其中包含 REST、WebSocket 和 SDK 文档。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/contributor-licence-agreement.ar.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "اتفاقية الترخيص للمساهمين"
+parent: "Arabic (Beta)"
+---
+
+# اتفاقية الترخيص للمساهمين
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+نطلب من كل المساهمين التوقيع على اتفاقية الترخيص للمساهمين قبل أن نتمكن من دمج طلب السحب. لا تنقل اتفاقية الترخيص حقوق الطبع والنشر - أنت تحتفظ بالملكية الكاملة لعملك. إنها ببساطة تمنح مشروع TrustGraph ترخيصًا دائمًا، وخاليًا من الرسوم، لتوزيع مساهمتك بموجب ترخيص [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) الخاص بالمشروع، وتؤكد أن لديك الحق في تقديم المساهمة. وهذا يحمي المشروع ومستخدميه من خلال ضمان أن لكل مساهمة الأساس القانوني الواضح.
+
+عندما تفتح طلب سحب، سيقوم روبوت اتفاقية الترخيص بنشر تعليق يطلب منك مراجعة وتوقيع الاتفاقية المناسبة - ويستغرق ذلك لحظة فقط، وعليك القيام بذلك مرة واحدة فقط عبر جميع مستودعات TrustGraph.
+
+- المساهمة ك**فرد**؟ قم بتوقيع [اتفاقية الترخيص الفردية](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- المساهمة **بالنيابة عن شركة أو منظمة**؟ قم بتوقيع [اتفاقية الترخيص التنظيمية](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.es.md

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

docs/contributor-licence-agreement.he.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "הסכם רישיון לתורמים"
+parent: "Hebrew (Beta)"
+---
+
+# הסכם רישיון לתורמים
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+אנו מבקשים מכל תורם לחתום על הסכם רישיון לתורמים לפני שנוכל לשלב בקשת פול. ההסכם **אינו** מעביר זכויות יוצרים – אתם שומרים על בעלות מלאה על עבודתכם. הוא פשוט מעניק לפרויקט TrustGraph רישיון נצחי, ללא תמלוגים, להפצת התרומה שלכם על פי הרישיון [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), וכן מאשר שאתם רשאים להעביר את התרומה. זה מגן הן על הפרויקט והן על המשתמשים שלו, על ידי הבטחת שכל תרומה תהיה בעלת בסיס משפטי ברור.
+
+כשאתם פותחים בקשת פול, בוט ה-CLA יפרסם הערה המבקש מכם לבדוק ולחתום על ההסכם המתאים – זה לוקח רק רגע, ואתם צריכים לעשות זאת רק פעם אחת בכל מאגרי ה-TrustGraph.
+
+- תורמים כ**אינדיבידואל**? חתמו על [הסכם רישיון אינדיבידואלי](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- תורמים **מטעמ חברה או ארגון**? חתמו על [הסכם רישיון עבור ארגון](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.hi.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: "योगदानकर्ता लाइसेंस समझौता (CLA)"
+parent: "Hindi (Beta)"
+---
+
+**महत्वपूर्ण निर्देश:**
+
+- सभी Markdown फॉर्मेटिंग, हेडर, लिंक और HTML टैग को बनाए रखें।
+- बैक टिक (` `) या कोड ब्लॉक के अंदर मौजूद कोड का अनुवाद न करें।
+- केवल अनुवादित टेक्स्ट को ही आउटपुट करें, जिसमें कोई भी प्रारंभिक या स्पष्टीकरण शामिल न हों।
+
+अनुवाद करने के लिए पाठ:
+
+# योगदानकर्ता लाइसेंस समझौता (CLA)
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+हम हर योगदानकर्ता से एक योगदानकर्ता लाइसेंस समझौते पर हस्ताक्षर करने का अनुरोध करते हैं, इससे पहले कि हम किसी पुल अनुरोध को मर्ज कर सकें। CLA कॉपीराइट को **नहीं** हस्तांतरित करता है — आप अपने कार्य का पूर्ण स्वामित्व बनाए रखते हैं। यह केवल TrustGraph परियोजना को आपके योगदान को परियोजना के [Apache 2.0 लाइसेंस](https://www.apache.org/licenses/LICENSE-2.0) के तहत वितरित करने का एक स्थायी, रॉयल्टी-मुक्त लाइसेंस प्रदान करता है, और यह पुष्टि करता है कि आपके पास योगदान करने का अधिकार है। यह परियोजना और उसके उपयोगकर्ताओं दोनों की रक्षा करता है, यह सुनिश्चित करके कि प्रत्येक योगदान का एक स्पष्ट कानूनी आधार है।
+
+जब आप एक पुल अनुरोध खोलते हैं, तो CLA बॉट आपसे उचित समझौते की समीक्षा और हस्ताक्षर करने के लिए एक टिप्पणी पोस्ट करेगा - इसमें केवल एक पल लगता है और आपको इसे ट्रस्टग्राफ रिपॉजिटरी के सभी में केवल एक बार करने की आवश्यकता है।
+
+- एक **व्यक्ति** के रूप में योगदान कर रहे हैं? [व्यक्तिगत CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md) पर हस्ताक्षर करें।
+- एक **कंपनी या संगठन** की ओर से योगदान कर रहे हैं? [कंपनी CLA](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md) पर हस्ताक्षर करें।

docs/contributor-licence-agreement.md

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

docs/contributor-licence-agreement.pt.md

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

docs/contributor-licence-agreement.ru.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "Договор лицензии для вкладчиков"
+parent: "Russian (Beta)"
+---
+
+# Договор лицензии для вкладчиков
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+Мы требуем, чтобы каждый вкладчик подписал Договор лицензии для вкладчиков, прежде чем мы сможем принять ваш запрос на слияние. Договор лицензии **не** передаёт авторские права — вы сохраняете полное право собственности на свою работу. Он просто предоставляет проекту TrustGraph пожизненную, без роялти лицензию на распространение вашего вклада в соответствии с лицензией [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), а также подтверждает, что у вас есть право внести вклад. Это защищает как проект, так и его пользователей, обеспечивая, чтобы каждый вклад имел четкое юридическое обоснование.
+
+Когда вы создаёте запрос на слияние, бот CLA опубликует комментарий, в котором попросит вас ознакомиться и подписать соответствующий договор — это занимает всего несколько минут, и вам нужно сделать это только один раз для всех репозиториев TrustGraph.
+
+- Вклад в качестве **индивидуального** участника? Подпишите [Индивидуальный договор лицензии](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Fiduciary-Contributor-License-Agreement.md)
+- Вклад от имени **компании или организации**? Подпишите [Организационный договор лицензии](https://github.com/trustgraph-ai/contributor-license-agreement/blob/main/Entity-Fiduciary-Contributor-License-Agreement.md)

docs/contributor-licence-agreement.sw.md

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

docs/contributor-licence-agreement.tr.md

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

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

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

docs/lang-index-ar.md

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

docs/lang-index-es.md

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

docs/lang-index-he.md

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

docs/lang-index-hi.md

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

docs/lang-index-pt.md

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

docs/lang-index-ru.md

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

docs/lang-index-sw.md

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

docs/lang-index-tr.md

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

docs/lang-index-zh-cn.md

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

docs/python-api.md

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

docs/tech-specs/__TEMPLATE.md

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

docs/tech-specs/active-flow-key-restructure.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: "Active-Flow Key Restructure"
+parent: "Tech Specs"
+---
+
+# Active-Flow Key Restructure
+
+## Problem
+
+Active-flow config uses `('active-flow', processor)` as its key, where
+each processor's value is a JSON blob containing all flow variants
+assigned to that processor:
+
+```
+('active-flow', 'chunker') -> { "default": {...}, "flow2": {...} }
+```
+
+This causes two problems:
+
+1. **Read-modify-write on every change.** Starting or stopping a flow
+   requires fetching the processor's current blob, parsing it, adding
+   or removing a variant, serialising it, and writing it back. This is
+   a concurrency hazard if two flow operations target the same
+   processor simultaneously.
+
+2. **Noisy config pushes.** Config subscribers subscribe to a type,
+   not a specific key. Every active-flow write triggers a config push
+   that causes every processor in the system to fetch the full config
+   and re-evaluate, even though only one processor's config changed.
+   With N processors in a blueprint, a single flow start/stop causes
+   N writes and N^2 config fetches across the system.
+
+## Proposed Change
+
+Restructure the key to `('active-flow', 'processor:variant')` where
+each key holds a single flow variant's configuration:
+
+```
+('active-flow', 'chunker:default') -> { "topics": {...}, "parameters": {...} }
+('active-flow', 'chunker:flow2')   -> { "topics": {...}, "parameters": {...} }
+```
+
+Starting a flow is a set of clean puts. Stopping a flow is a set of
+clean deletes. No read-modify-write. No JSON blob merging.
+
+The config push problem (all processors fetching on every change)
+remains — that's a limitation of the config subscription model and
+would require per-key subscriptions to solve. But eliminating the
+read-modify-write removes the concurrency hazard and simplifies the
+flow service code.
+
+## What Changes
+
+- **Flow service** (`flow.py`): `handle_start_flow` writes individual
+  keys per processor:variant instead of merging into per-processor
+  blobs. `handle_stop_flow` deletes individual keys instead of
+  read-modify-write.
+- **FlowProcessor** (`flow_processor.py`): `on_configure_flows`
+  currently looks up `config["active-flow"][self.id]` to find a JSON
+  blob of all its variants. Needs to scan all active-flow keys for
+  entries prefixed with `self.id:` and assemble its flow list from
+  those.
+- **Config client**: May benefit from a prefix-scan or pattern-match
+  query to support the FlowProcessor lookup efficiently.
+- **Initial config / bootstrapping**: Any code that seeds active-flow
+  entries at deployment time needs to use the new key format.

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:**
+The canonical vocabulary for all predicates and types is published as an OWL ontology at `specs/ontology/trustgraph.ttl`.
-- 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
 
 ## 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 |
+| Entity | TG Types | Description |
-|--------|-------------|----------|-------------|
+|--------|----------|-------------|
-| Question | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | The user's query |
+| Question | `tg:Question`, `tg:GraphRagQuestion` | The user's query |
-| Exploration | `prov:Entity` | `tg:Exploration` | Edges retrieved from knowledge graph |
+| Grounding | `tg:Grounding` | Concept extraction from query |
-| Focus | `prov:Entity` | `tg:Focus` | Selected edges with reasoning |
+| Exploration | `tg:Exploration` | Edges retrieved from knowledge graph |
-| Synthesis | `prov:Entity` | `tg:Synthesis` | Final answer |
+| Focus | `tg:Focus` | Selected edges with reasoning |
-
+| Synthesis | `tg:Synthesis`, `tg:Answer` | 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 |
 
 ### Document RAG Types
-| Entity | PROV-O Type | TG Types | Description |
+| Entity | TG Types | Description |
-|--------|-------------|----------|-------------|
+|--------|----------|-------------|
-| Question | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | The user's query |
+| Question | `tg:Question`, `tg:DocRagQuestion` | The user's query |
-| Exploration | `prov:Entity` | `tg:Exploration` | Chunks retrieved from document store |
+| Grounding | `tg:Grounding` | Concept extraction from query |
-| Synthesis | `prov:Entity` | `tg:Synthesis` | Final answer |
+| 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})
+Question → Grounding → Exploration → Focus → Synthesis
-    │
-    │  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
+### Document RAG
 
 ```
-Question (urn:trustgraph:docrag:{uuid})
+Question → Grounding → Exploration → Synthesis
-    │
-    │  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
 ```
 
-## Changes Required
+### Agent React
 
-### 1. Schema Changes
+```
-
+Question → PatternDecision → Analysis(1) → Observation(1) → Analysis(2) → ... → Conclusion
-**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
 ```
 
-**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`
+```
-
+Question → PatternDecision → Plan → StepResult(0) → StepResult(1) → ... → Synthesis
-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,
-    )
-)
 ```
 
-### 3. Provenance Triple Generation
+### Agent Supervisor
 
-**File:** `trustgraph-base/trustgraph/provenance/agent.py`
+```
-
+Question → PatternDecision → Decomposition → [fan-out sub-agents]
-Create helper functions (similar to GraphRAG's `question_triples`, `exploration_triples`, etc.):
+                                           → Finding(0) → Finding(1) → ... → Synthesis
-```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. 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:
+### Session / Question
-```python
+| Predicate | Type | Description |
-# Explainability entity types (used by both GraphRAG and Agent)
+|-----------|------|-------------|
-TG_QUESTION = TG + "Question"
+| `tg:query` | string | The user's query text |
-TG_EXPLORATION = TG + "Exploration"
+| `prov:startedAtTime` | string | ISO timestamp |
-TG_FOCUS = TG + "Focus"
-TG_SYNTHESIS = TG + "Synthesis"
-TG_ANALYSIS = TG + "Analysis"
-TG_CONCLUSION = TG + "Conclusion"
 
-# Agent predicates
+### Pattern Decision
-TG_THOUGHT = TG + "thought"
+| Predicate | Type | Description |
-TG_ACTION = TG + "action"
+|-----------|------|-------------|
-TG_ARGUMENTS = TG + "arguments"
+| `tg:pattern` | string | Selected pattern (react, plan-then-execute, supervisor) |
-TG_OBSERVATION = TG + "observation"
+| `tg:taskType` | string | Identified task type (general, research, etc.) |
-TG_ANSWER = TG + "answer"
-```
 
-## 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 |
+### Observation
-|------|--------|
+| Predicate | Type | Description |
-| `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 |
+| `tg:document` | IRI | Librarian document reference |
-| `trustgraph-base/trustgraph/provenance/namespaces.py` | Add entity types, agent predicates, and Document RAG predicates |
+| `tg:toolDurationMs` | integer | Tool execution time in milliseconds |
-| `trustgraph-base/trustgraph/provenance/triples.py` | Add TG types to GraphRAG triple builders, add Document RAG triple builders |
+| `tg:toolError` | string | Error message (tool failure or LLM parse error) |
-| `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 |
 
-## Files Created
+When `tg:toolError` is present, the Observation also carries the `tg:Error` mixin type.
 
-| File | Purpose |
+### Conclusion / Synthesis
-|------|---------|
+| Predicate | Type | Description |
-| `trustgraph-base/trustgraph/provenance/agent.py` | Agent-specific triple generators |
+|-----------|------|-------------|
+| `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:
+### Decomposition
-1. URI pattern: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
+| Predicate | Type | Description |
-2. Derived entities: `tg:Analysis` (agent) vs `tg:Exploration` (GraphRAG)
+|-----------|------|-------------|
+| `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`:**
+### Plan
-- Shows Type column (Agent vs GraphRAG)
+| 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`:**
+### Token Counts on RAG Events
-- Auto-detects trace type
-- Agent rendering shows: Question → Analysis step(s) → Conclusion
 
-## 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
+## Error Handling
-- `collection` defaults to `"default"` - reasonable fallback
+
-- CLI gracefully handles both trace types
+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
+# Run an agent query with explainability
-tg-invoke-agent -q "What is the capital of France?"
+tg-invoke-agent -q "What is quantum computing?" -x
 
-# List traces (should show agent sessions with Type column)
+# Run with token usage
-tg-list-explain-traces -U trustgraph -C default
+tg-invoke-agent -q "What is quantum computing?" --show-usage
 
-# Show agent trace
+# GraphRAG with explainability
-tg-show-explain-trace "urn:trustgraph:agent:xxx"
+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)

docs/tech-specs/agent-orchestration.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: "TrustGraph Agent Orchestration — Technical Specification"
+parent: "Tech Specs"
+---
+
 # TrustGraph Agent Orchestration — Technical Specification
 
 ## Overview
@@ -862,7 +868,7 @@ independently.
 Response chunk fields:
     message_id          UUID for this message (groups chunks)
     session_id          Which agent session produced this chunk
-    chunk_type          "thought" | "observation" | "answer" | ...
+    message_type          "thought" | "observation" | "answer" | ...
     content             The chunk text
     end_of_message      True on the final chunk of this message
     end_of_dialog       True on the final message of the entire execution

docs/tech-specs/ar/__TEMPLATE.ar.md

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

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

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

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

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

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

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

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

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

docs/tech-specs/ar/collection-management.ar.md

@@ -0,0 +1,410 @@
+---
+layout: default
+title: "مواصفات فنية لإدارة المجموعات"
+parent: "Arabic (Beta)"
+---
+
+# مواصفات فنية لإدارة المجموعات
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## نظرة عامة
+
+تصف هذه المواصفات إمكانات إدارة المجموعات لـ TrustGraph، والتي تتطلب إنشاء مجموعات بشكل صريح وتوفر تحكمًا مباشرًا في دورة حياة المجموعة. يجب إنشاء المجموعات بشكل صريح قبل استخدامها، مما يضمن المزامنة الصحيحة بين بيانات وصفية أمين المكتبة وجميع الواجهات الخلفية للتخزين. تدعم هذه الميزة أربع حالات استخدام رئيسية:
+
+1. **إنشاء المجموعة**: إنشاء مجموعات بشكل صريح قبل تخزين البيانات
+2. **قائمة المجموعات**: عرض جميع المجموعات الموجودة في النظام
+3. **إدارة بيانات وصفية المجموعة**: تحديث أسماء المجموعات والأوصاف والعلامات
+4. **حذف المجموعة**: إزالة المجموعات والبيانات المرتبطة بها عبر جميع أنواع التخزين
+
+## الأهداف
+
+**إنشاء المجموعة بشكل صريح**: تتطلب أن يتم إنشاء المجموعات قبل تخزين البيانات
+**مزامنة التخزين**: ضمان وجود المجموعات في جميع الواجهات الخلفية للتخزين (المتجهات، والكائنات، والثلاثيات)
+**إمكانية رؤية المجموعة**: تمكين المستخدمين من سرد وفحص جميع المجموعات في بيئتهم
+**تنظيف المجموعة**: السماح بحذف المجموعات التي لم تعد مطلوبة
+**تنظيم المجموعة**: دعم العلامات والملصقات لتتبع واكتشاف المجموعة بشكل أفضل
+**إدارة البيانات الوصفية**: ربط بيانات وصفية ذات مغزى بالمجموعات من أجل الوضوح التشغيلي
+**اكتشاف المجموعة**: تسهيل العثور على مجموعات معينة من خلال التصفية والبحث
+**الشفافية التشغيلية**: توفير رؤية واضحة لدورة حياة المجموعة واستخدامها
+**إدارة الموارد**: تمكين تنظيف المجموعات غير المستخدمة لتحسين استخدام الموارد
+**سلامة البيانات**: منع وجود مجموعات معزولة في التخزين بدون تتبع البيانات الوصفية
+
+## الخلفية
+
+في السابق، كانت المجموعات في TrustGraph يتم إنشاؤها ضمنيًا أثناء عمليات تحميل البيانات، مما أدى إلى مشاكل في المزامنة حيث يمكن أن توجد المجموعات في الواجهات الخلفية للتخزين بدون بيانات وصفية مقابلة في أمين المكتبة. وقد أدى ذلك إلى تحديات إدارية وإمكانية وجود بيانات معزولة.
+
+يعالج نموذج إنشاء المجموعة الصريح هذه المشكلات عن طريق:
+طلب إنشاء المجموعات قبل استخدامها عبر `tg-set-collection`
+بث إنشاء المجموعة إلى جميع الواجهات الخلفية للتخزين
+الحفاظ على حالة متزامنة بين بيانات وصفية أمين المكتبة والتخزين
+منع الكتابة إلى المجموعات غير الموجودة
+توفير إدارة واضحة لدورة حياة المجموعة
+
+تحدد هذه المواصفات نموذج إدارة المجموعة الصريح. من خلال طلب إنشاء المجموعة بشكل صريح، تضمن TrustGraph:
+تتبع المجموعات في بيانات وصفية أمين المكتبة من لحظة إنشائها
+أن تكون جميع الواجهات الخلفية للتخزين على علم بالمجموعات قبل استقبال البيانات
+عدم وجود مجموعات معزولة في التخزين
+رؤية وتحكم واضحين في دورة حياة المجموعة
+معالجة أخطاء متسقة عند الإشارة العمليات إلى مجموعات غير موجودة
+
+## التصميم الفني
+
+### البنية التحتية
+
+سيتم تنفيذ نظام إدارة المجموعة داخل البنية التحتية الحالية لـ TrustGraph:
+
+1. **تكامل خدمة أمين المكتبة**
+   سيتم إضافة عمليات إدارة المجموعة إلى خدمة أمين المكتبة الحالية
+   لا توجد خدمة جديدة مطلوبة - تستفيد من أنماط المصادقة والوصول الحالية
+   تتعامل مع قائمة المجموعات وحذفها وإدارة بياناتها الوصفية
+
+   الوحدة: trustgraph-librarian
+
+2. **جدول بيانات وصفية المجموعة في Cassandra**
+   جدول جديد في مساحة مفاتيح أمين المكتبة الحالية
+   يخزن بيانات وصفية المجموعة مع وصول المستخدم
+   المفتاح الأساسي: (user_id, collection_id) لضمان تعدد المستأجرين المناسب
+
+   الوحدة: trustgraph-librarian
+
+3. **واجهة سطر الأوامر لإدارة المجموعة**
+   واجهة سطر أوامر لعمليات المجموعة
+   يوفر أوامر للقائمة والحذف والملصقات والعلامات
+   يتكامل مع إطار عمل سطر الأوامر الحالي
+
+   الوحدة: trustgraph-cli
+
+### نماذج البيانات
+
+#### جدول بيانات وصفية المجموعة في Cassandra
+
+سيتم تخزين بيانات وصفية المجموعة في جدول Cassandra منظم في مساحة مفاتيح أمين المكتبة:
+
+```sql
+CREATE TABLE collections (
+    user text,
+    collection text,
+    name text,
+    description text,
+    tags set<text>,
+    created_at timestamp,
+    updated_at timestamp,
+    PRIMARY KEY (user, collection)
+);
+```
+
+هيكل الجدول:
+**user**: + **collection**: مفتاح أساسي مركب يضمن عزل المستخدم
+**name**: اسم المجموعة الذي يمكن قراءته بواسطة الإنسان
+**description**: وصف تفصيلي لغرض المجموعة
+**tags**: مجموعة من العلامات لتصنيف وتصفية
+**created_at**: طابع زمني لإنشاء المجموعة
+**updated_at**: طابع زمني لآخر تعديل
+
+هذا النهج يسمح بـ:
+إدارة مجموعات متعددة المستأجرين مع عزل المستخدم
+استعلام فعال حسب المستخدم والمجموعة
+نظام تصنيف مرن للتنظيم
+تتبع دورة حياة المجموعة للحصول على رؤى تشغيلية
+
+#### دورة حياة المجموعة
+
+يتم إنشاء المجموعات بشكل صريح في المكتبة قبل أن تتمكن عمليات البيانات من المضي قدمًا:
+
+1. **إنشاء المجموعة** (مساران):
+
+   **المسار أ: الإنشاء الذي يبدأه المستخدم** عبر `tg-set-collection`:
+   يقوم المستخدم بتوفير معرف المجموعة والاسم والوصف والعلامات
+   تقوم المكتبة بإنشاء سجل بيانات وصفية في جدول `collections`
+   تقوم المكتبة ببث "إنشاء مجموعة" إلى جميع الواجهات الخلفية للتخزين
+   تقوم جميع معالجات التخزين بإنشاء المجموعة وتأكيد النجاح
+   أصبحت المجموعة الآن جاهزة لعمليات البيانات
+
+   **المسار ب: الإنشاء التلقائي عند إرسال المستند**:
+   يقوم المستخدم بإرسال مستند يحدد معرف مجموعة
+   تتحقق المكتبة مما إذا كانت المجموعة موجودة في جدول البيانات الوصفية
+   إذا لم تكن موجودة: تقوم المكتبة بإنشاء بيانات وصفية مع القيم الافتراضية (الاسم = معرف المجموعة، وصف/علامات فارغة)
+   تقوم المكتبة ببث "إنشاء مجموعة" إلى جميع الواجهات الخلفية للتخزين
+   تقوم جميع معالجات التخزين بإنشاء المجموعة وتأكيد النجاح
+   تستمر معالجة المستند مع إنشاء المجموعة الآن
+
+   يضمن كلا المسارين وجود المجموعة في بيانات المكتبة الوصفية وجميع الواجهات الخلفية للتخزين قبل السماح بعمليات البيانات.
+
+2. **التحقق من التخزين**: تتحقق عمليات الكتابة من وجود المجموعة:
+   تتحقق معالجات التخزين من حالة المجموعة قبل قبول عمليات الكتابة
+   تؤدي عمليات الكتابة إلى مجموعات غير موجودة إلى إرجاع خطأ
+   يمنع هذا عمليات الكتابة المباشرة التي تتجاوز منطق إنشاء المجموعة الخاص بالمكتبة
+
+3. **سلوك الاستعلام**: تتعامل عمليات الاستعلام مع المجموعات غير الموجودة بأمان:
+   تؤدي الاستعلامات إلى مجموعات غير موجودة إلى إرجاع نتائج فارغة
+   لا يتم إرجاع أي خطأ لعمليات الاستعلام
+   يسمح بالاستكشاف دون الحاجة إلى وجود المجموعة
+
+4. **تحديثات البيانات الوصفية**: يمكن للمستخدمين تحديث بيانات وصفية للمجموعة بعد الإنشاء:
+   قم بتحديث الاسم والوصف والعلامات عبر `tg-set-collection`
+   تنطبق التحديثات على بيانات المكتبة الوصفية فقط
+   تحتفظ الواجهات الخلفية للتخزين بالمجموعة ولكن لا يتم نشر تحديثات البيانات الوصفية
+
+5. **الحذف الصريح**: يقوم المستخدمون بحذف المجموعات عبر `tg-delete-collection`:
+   تقوم المكتبة ببث "حذف مجموعة" إلى جميع الواجهات الخلفية للتخزين
+   تنتظر تأكيدًا من جميع معالجات التخزين
+   تحذف سجل بيانات المكتبة الوصفية فقط بعد اكتمال تنظيف التخزين
+   يضمن عدم وجود بيانات متبقية في التخزين
+
+**المبدأ الأساسي**: المكتبة هي نقطة التحكم الوحيدة لإنشاء المجموعة. سواء تم بدءها بأمر المستخدم أو بإرسال مستند، تضمن المكتبة تتبع البيانات الوصفية المناسبة ومزامنة الواجهة الخلفية للتخزين قبل السماح بعمليات البيانات.
+
+العمليات المطلوبة:
+**إنشاء مجموعة**: عملية المستخدم عبر `tg-set-collection` أو تلقائيًا عند إرسال مستند
+**تحديث بيانات وصفية للمجموعة**: عملية المستخدم لتعديل الاسم والوصف والعلامات
+**حذف مجموعة**: عملية المستخدم لإزالة المجموعة والبيانات المرتبطة بها عبر جميع المتاجر
+**قائمة المجموعات**: عملية المستخدم لعرض المجموعات مع التصفية حسب العلامات
+
+#### إدارة المجموعة عبر المتاجر
+
+توجد المجموعات عبر واجهات خلفية تخزين متعددة في TrustGraph:
+**مخازن المتجهات** (Qdrant، Milvus، Pinecone): تخزن التضمينات والبيانات المتجهة
+**مخازن الكائنات** (Cassandra): تخزن المستندات وبيانات الملف
+**مخازن الثلاثيات** (Cassandra، Neo4j، Memgraph، FalkorDB): تخزن بيانات الرسم البياني/RDF
+
+Each store type implements:
+**Collection State Tracking**: Maintain knowledge of which collections exist
+**Collection Creation**: Accept and process "create-collection" operations
+**Collection Validation**: Check collection exists before accepting writes
+**Collection Deletion**: Remove all data for specified collection
+
+The librarian service coordinates collection operations across all store types, ensuring:
+Collections created in all backends before use
+All backends confirm creation before returning success
+Synchronized collection lifecycle across storage types
+Consistent error handling when collections don't exist
+
+#### Collection State Tracking by Storage Type
+
+Each storage backend tracks collection state differently based on its capabilities:
+
+**Cassandra Triple Store:**
+Uses existing `triples_collection` table
+Creates system marker triple when collection created
+Query: `SELECT collection FROM triples_collection WHERE collection = ? LIMIT 1`
+Efficient single-partition check for collection existence
+
+**Qdrant/Milvus/Pinecone Vector Stores:**
+Native collection APIs provide existence checking
+Collections created with proper vector configuration
+`collection_exists()` method uses storage API
+Collection creation validates dimension requirements
+
+**Neo4j/Memgraph/FalkorDB Graph Stores:**
+Use `:CollectionMetadata` nodes to track collections
+Node properties: `{user, collection, created_at}`
+Query: `MATCH (c:CollectionMetadata {user: $user, collection: $collection})`
+Separate from data nodes for clean separation
+Enables efficient collection listing and validation
+
+**Cassandra Object Store:**
+Uses collection metadata table or marker rows
+Similar pattern to triple store
+Validates collection before document writes
+
+### APIs
+
+Collection Management APIs (Librarian):
+**Create/Update Collection**: Create new collection or update existing metadata via `tg-set-collection`
+**List Collections**: Retrieve collections for a user with optional tag filtering
+**Delete Collection**: Remove collection and associated data, cascading to all store types
+
+Storage Management APIs (All Storage Processors):
+**Create Collection**: Handle "create-collection" operation, establish collection in storage
+**Delete Collection**: Handle "delete-collection" operation, remove all collection data
+**Collection Exists Check**: Internal validation before accepting write operations
+
+Data Operation APIs (Modified Behavior):
+**Write APIs**: Validate collection exists before accepting data, return error if not
+**Query APIs**: Return empty results for non-existent collections without error
+
+### Implementation Details
+
+The implementation will follow existing TrustGraph patterns for service integration and CLI command structure.
+
+#### Collection Deletion Cascade
+
+When a user initiates collection deletion through the librarian service:
+
+1. **Metadata Validation**: Verify collection exists and user has permission to delete
+2. **Store Cascade**: Librarian coordinates deletion across all store writers:
+   Vector store writer: Remove embeddings and vector indexes for the user and collection
+   Object store writer: Remove documents and files for the user and collection
+   Triple store writer: Remove graph data and triples for the user and collection
+3. **Metadata Cleanup**: Remove collection metadata record from Cassandra
+4. **Error Handling**: If any store deletion fails, maintain consistency through rollback or retry mechanisms
+
+#### Collection Management Interface
+
+**⚠️ LEGACY APPROACH - REPLACED BY CONFIG-BASED PATTERN**
+
+The queue-based architecture described below has been replaced with a config-based approach using `CollectionConfigHandler`. All storage backends now receive collection updates via config push messages instead of dedicated management queues.
+
+~~All store writers implement a standardized collection management interface with a common schema:~~
+
+~~**Message Schema (`StorageManagementRequest`):**~~
+```json
+{
+  "operation": "create-collection" | "delete-collection",
+  "user": "user123",
+  "collection": "documents-2024"
+}
+```
+
+~~**هيكلة قائمة الانتظار:**~~
+~~**قائمة انتظار إدارة مخزن المتجهات** (`vector-storage-management`): مخازن المتجهات/التضمينات~~
+~~**قائمة انتظار إدارة مخزن الكائنات** (`object-storage-management`): مخازن الكائنات/المستندات~~
+~~**قائمة انتظار إدارة مخزن الثلاثيات** (`triples-storage-management`): مخازن الرسم البياني/RDF~~
+~~**قائمة انتظار استجابة التخزين** (`storage-management-response`): يتم إرسال جميع الاستجابات هنا~~
+
+**التنفيذ الحالي:**
+
+تستخدم جميع واجهات التخزين الخلفية الآن `CollectionConfigHandler`:
+**تكامل دفع التكوين**: تسجل خدمات التخزين للحصول على إشعارات دفع التكوين
+**المزامنة التلقائية**: يتم إنشاء/حذف المجموعات بناءً على تغييرات التكوين
+**نموذج تصريحي**: يتم تعريف المجموعات في خدمة التكوين، وتقوم الواجهات الخلفية بالمزامنة للمطابقة
+**لا يوجد طلب/استجابة**: يلغي تكامل التنسيق وتتبع الاستجابة
+**تتبع حالة المجموعة**: يتم الحفاظ عليه عبر ذاكرة التخزين المؤقت `known_collections`
+**عمليات قابلة للعكس**: من الآمن معالجة نفس التكوين عدة مرات
+
+تقوم كل واجهة تخزين خلفية بتنفيذ:
+`create_collection(user: str, collection: str, metadata: dict)` - إنشاء هياكل المجموعة
+`delete_collection(user: str, collection: str)` - إزالة جميع بيانات المجموعة
+`collection_exists(user: str, collection: str) -> bool` - التحقق من الصحة قبل الكتابة
+
+#### إعادة هيكلة مخزن الثلاثيات Cassandra
+
+كجزء من هذا التنفيذ، سيتم إعادة هيكلة مخزن الثلاثيات Cassandra من نموذج جدول لكل مجموعة إلى نموذج جدول موحد:
+
+**الهيكلة الحالية:**
+مساحة مفاتيح لكل مستخدم، وجدول منفصل لكل مجموعة
+المخطط: `(s, p, o)` مع `PRIMARY KEY (s, p, o)`
+أسماء الجداول: تصبح مجموعات المستخدمين جداول Cassandra منفصلة
+
+**الهيكلة الجديدة:**
+مساحة مفاتيح لكل مستخدم، وجدول "ثلاثيات" واحد لجميع المجموعات
+المخطط: `(collection, s, p, o)` مع `PRIMARY KEY (collection, s, p, o)`
+عزل المجموعة من خلال تقسيم المجموعة
+
+**التغييرات المطلوبة:**
+
+1. **إعادة هيكلة فئة TrustGraph** (`trustgraph/direct/cassandra.py`):
+   إزالة المعلمة `table` من المُنشئ، واستخدام جدول "ثلاثيات" ثابت
+   إضافة المعلمة `collection` إلى جميع الطرق
+   تحديث المخطط لتضمين المجموعة كأول عمود
+   **تحديثات الفهرس**: سيتم إنشاء فهارس جديدة لدعم جميع أنماط الاستعلام الثمانية:
+     فهرس على `(s)` للاستعلامات المستندة إلى الموضوع
+     فهرس على `(p)` للاستعلامات المستندة إلى الرابط
+     فهرس على `(o)` للاستعلامات المستندة إلى الكائن
+     ملاحظة: لا تدعم Cassandra فهارس ثانوية متعددة الأعمدة، لذا هذه هي فهارس أحادية العمود
+
+   **أداء نمط الاستعلام:**
+     ✅ `get_all()` - فحص التقسيم على `collection`
+     ✅ `get_s(s)` - يستخدم المفتاح الأساسي بكفاءة (`collection, s`)
+     ✅ `get_p(p)` - يستخدم `idx_p` مع تصفية `collection`
+     ✅ `get_o(o)` - يستخدم `idx_o` مع تصفية `collection`
+     ✅ `get_sp(s, p)` - يستخدم المفتاح الأساسي بكفاءة (`collection, s, p`)
+     ⚠️ `get_po(p, o)` - يتطلب `ALLOW FILTERING` (يستخدم إما `idx_p` أو `idx_o` بالإضافة إلى التصفية)
+     ✅ `get_os(o, s)` - يستخدم `idx_o` مع تصفية إضافية على `s`
+     ✅ `get_spo(s, p, o)` - يستخدم المفتاح الأساسي بكفاءة
+
+   **ملاحظة حول ALLOW FILTERING**: يتطلب نمط استعلام `get_po` `ALLOW FILTERING` لأنه يحتاج إلى كل من قيود الرابط والكائن بدون فهرس مركب مناسب. هذا مقبول لأن نمط الاستعلام هذا أقل شيوعًا من الاستعلامات المستندة إلى الموضوع في الاستخدام النموذجي لمخزن الثلاثيات.
+
+2. **تحديثات كاتب التخزين** (`trustgraph/storage/triples/cassandra/write.py`):
+   الحفاظ على اتصال TrustGraph واحد لكل مستخدم بدلاً من لكل (مستخدم، مجموعة)
+   تمرير المجموعة إلى عمليات الإدراج
+   تحسين استخدام الموارد مع عدد أقل من الاتصالات
+
+3. **تحديثات خدمة الاستعلام** (`trustgraph/query/triples/cassandra/service.py`):
+   اتصال TrustGraph واحد لكل مستخدم
+   تمرير المجموعة إلى جميع عمليات الاستعلام
+   الحفاظ على نفس منطق الاستعلام مع معلمة المجموعة
+
+**الفوائد:**
+**تبسيط حذف المجموعة**: حذف باستخدام مفتاح التقسيم `collection` عبر جميع الجداول الأربعة
+**كفاءة الموارد**: عدد أقل من اتصالات قاعدة البيانات وكائنات الجدول
+**العمليات عبر المجموعات**: من الأسهل تنفيذ العمليات التي تمتد عبر مجموعات متعددة
+**هيكلة متسقة**: تتماشى مع نهج بيانات التعريف الموحد للمجموعة
+**التحقق من صحة المجموعة**: من السهل التحقق من وجود المجموعة عبر جدول `triples_collection`
+
+ستكون عمليات المجموعة ذرية قدر الإمكان، وستوفر معالجة أخطاء والتحقق المناسبين.
+
+## اعتبارات الأمان
+
+تتطلب عمليات إدارة المجموعة تفويضًا مناسبًا لمنع الوصول غير المصرح به أو حذف المجموعات. سيتم مواءمة التحكم في الوصول مع نماذج الأمان الحالية لـ TrustGraph.
+
+## اعتبارات الأداء
+
+قد تتطلب عمليات سرد المجموعة الترقيم في البيئات التي تحتوي على عدد كبير من المجموعات. يجب تحسين استعلامات البيانات الوصفية للأنماط الشائعة للتصفية.
+
+## استراتيجية الاختبار
+
+ستغطي الاختبارات الشاملة ما يلي:
+سير عمل إنشاء المجموعة من البداية إلى النهاية
+مزامنة الواجهة الخلفية للتخزين
+التحقق من صحة الكتابة للمجموعات غير الموجودة
+معالجة الاستعلامات للمجموعات غير الموجودة
+حذف المجموعة بالتتالي عبر جميع المستودعات
+معالجة الأخطاء وسيناريوهات الاسترداد
+اختبارات الوحدة لكل واجهة خلفية للتخزين
+اختبارات التكامل للعمليات عبر المستودعات
+
+## حالة التنفيذ
+
+### ✅ المكونات المكتملة
+
+1. **خدمة إدارة المجموعة Librarian** (`trustgraph-flow/trustgraph/librarian/collection_manager.py`)
+   عمليات CRUD للبيانات الوصفية للمجموعة (القائمة، التحديث، الحذف)
+   تكامل جدول بيانات وصفية للمجموعة في Cassandra عبر `LibraryTableStore`
+   تنسيق حذف المجموعة بالتتالي عبر جميع أنواع التخزين
+   معالجة الطلبات/الاستجابات غير المتزامنة مع إدارة الأخطاء المناسبة
+
+2. **مخطط البيانات الوصفية للمجموعة** (`trustgraph-base/trustgraph/schema/services/collection.py`)
+   مخططات `CollectionManagementRequest` و `CollectionManagementResponse`
+   مخطط `CollectionMetadata` لسجلات المجموعة
+   تعريفات موضوع قائمة انتظار الطلبات/الاستجابات للمجموعة
+
+3. **مخطط إدارة التخزين** (`trustgraph-base/trustgraph/schema/services/storage.py`)
+   مخططات `StorageManagementRequest` و `StorageManagementResponse`
+   تم تعريف مواضيع قائمة انتظار إدارة التخزين
+   تنسيق الرسائل لعمليات المجموعة على مستوى التخزين
+
+4. **مخطط Cassandra المكون من 4 جداول** (`trustgraph-flow/trustgraph/direct/cassandra_kg.py`)
+   مفاتيح تقسيم مركبة لأداء الاستعلام
+   جدول `triples_collection` لاستعلامات SPO وتتبع الحذف
+   تم تنفيذ حذف المجموعة بنمط القراءة ثم الحذف
+
+### ✅ الترحيل إلى النمط المستند إلى التكوين - مكتمل
+
+**تم ترحيل جميع الواجهات الخلفية للتخزين من نمط قائمة الانتظار إلى النمط المستند إلى التكوين `CollectionConfigHandler`.**
+
+عمليات الترحيل المكتملة:
+✅ `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
+✅ `trustgraph-flow/trustgraph/storage/triples/neo4j/write.py`
+✅ `trustgraph-flow/trustgraph/storage/triples/memgraph/write.py`
+✅ `trustgraph-flow/trustgraph/storage/triples/falkordb/write.py`
+✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
+✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py`
+✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
+✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py`
+✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
+✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py`
+✅ `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
+
+جميع الواجهات الخلفية الآن:
+ترث من `CollectionConfigHandler`
+تسجيل للحصول على إشعارات دفع التكوين عبر `self.register_config_handler(self.on_collection_config)`
+تنفيذ `create_collection(user, collection, metadata)` و `delete_collection(user, collection)`
+استخدام `collection_exists(user, collection)` للتحقق قبل الكتابة
+المزامنة التلقائية مع تغييرات خدمة التكوين
+
+تم إزالة البنية التحتية لقائمة الانتظار القديمة:
+✅ تمت إزالة مخططات `StorageManagementRequest` و `StorageManagementResponse`
+✅ تمت إزالة تعريفات موضوع قائمة انتظار إدارة التخزين
+✅ تمت إزالة المستهلك/المنتج لإدارة التخزين من جميع الواجهات الخلفية
+✅ تمت إزالة معالجات `on_storage_management` من جميع الواجهات الخلفية

docs/tech-specs/ar/document-embeddings-chunk-id.ar.md

@@ -0,0 +1,144 @@
+---
+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.
+
+## نظرة عامة
+
+تخزين تضمينات المستندات يخزن حاليًا نص الجزء مباشرةً في حمولة مخزن المتجهات، مما يكرر البيانات الموجودة في Garage. يحل هذا المخطط تخزين نص الجزء باستخدام مراجع `chunk_id`.
+
+## الحالة الحالية
+
+```python
+@dataclass
+class ChunkEmbeddings:
+    chunk: bytes = b""
+    vectors: list[list[float]] = field(default_factory=list)
+
+@dataclass
+class DocumentEmbeddingsResponse:
+    error: Error | None = None
+    chunks: list[str] = field(default_factory=list)
+```
+
+حمولة تخزين المتجهات:
+```python
+payload={"doc": chunk}  # Duplicates Garage content
+```
+
+## التصميم
+
+### تغييرات المخطط
+
+**ChunkEmbeddings** - استبدال "chunk" بـ "chunk_id":
+```python
+@dataclass
+class ChunkEmbeddings:
+    chunk_id: str = ""
+    vectors: list[list[float]] = field(default_factory=list)
+```
+
+**DocumentEmbeddingsResponse** - إرجاع معرفات الأجزاء (chunk_ids) بدلاً من الأجزاء نفسها:
+```python
+@dataclass
+class DocumentEmbeddingsResponse:
+    error: Error | None = None
+    chunk_ids: list[str] = field(default_factory=list)
+```
+
+### حمولة مستودع المتجهات
+
+جميع المستودعات (Qdrant، Milvus، Pinecone):
+```python
+payload={"chunk_id": chunk_id}
+```
+
+### التغييرات في معالج مستند RAG
+
+يقوم معالج مستند RAG باسترداد محتوى الأجزاء من نظام Garage:
+
+```python
+# Get chunk_ids from embeddings store
+chunk_ids = await self.rag.doc_embeddings_client.query(...)
+
+# Fetch chunk content from Garage
+docs = []
+for chunk_id in chunk_ids:
+    content = await self.rag.librarian_client.get_document_content(
+        chunk_id, self.user
+    )
+    docs.append(content)
+```
+
+### التغييرات في واجهة برمجة التطبيقات (API) / مجموعة تطوير البرمجيات (SDK)
+
+**DocumentEmbeddingsClient** تُرجع `chunk_ids`:
+```python
+return resp.chunk_ids  # Changed from resp.chunks
+```
+
+**تنسيق البيانات** (DocumentEmbeddingsResponseTranslator):
+```python
+result["chunk_ids"] = obj.chunk_ids  # Changed from chunks
+```
+
+### تغييرات واجهة سطر الأوامر (CLI)
+
+تعرض أداة واجهة سطر الأوامر (CLI) معرفات الأجزاء (يمكن للمستخدمين استرداد المحتوى بشكل منفصل إذا لزم الأمر).
+
+## الملفات التي يجب تعديلها
+
+### المخطط (Schema)
+`trustgraph-base/trustgraph/schema/knowledge/embeddings.py` - ChunkEmbeddings
+`trustgraph-base/trustgraph/schema/services/query.py` - DocumentEmbeddingsResponse
+
+### الرسائل/المترجمات
+`trustgraph-base/trustgraph/messaging/translators/embeddings_query.py` - DocumentEmbeddingsResponseTranslator
+
+### العميل (Client)
+`trustgraph-base/trustgraph/base/document_embeddings_client.py` - إرجاع معرفات الأجزاء
+
+### حزمة تطوير البرمجيات (SDK) / واجهة برمجة التطبيقات (API) بلغة بايثون
+`trustgraph-base/trustgraph/api/flow.py` - document_embeddings_query
+`trustgraph-base/trustgraph/api/socket_client.py` - document_embeddings_query
+`trustgraph-base/trustgraph/api/async_flow.py` - إذا كان ذلك ممكنًا
+`trustgraph-base/trustgraph/api/bulk_client.py` - استيراد/تصدير تضمينات المستندات
+`trustgraph-base/trustgraph/api/async_bulk_client.py` - استيراد/تصدير تضمينات المستندات
+
+### خدمة التضمينات
+`trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py` - تمرير معرف الجزء
+
+### أدوات الكتابة في التخزين
+`trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
+`trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
+`trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
+
+### خدمات الاستعلام
+`trustgraph-flow/trustgraph/query/doc_embeddings/qdrant/service.py`
+`trustgraph-flow/trustgraph/query/doc_embeddings/milvus/service.py`
+`trustgraph-flow/trustgraph/query/doc_embeddings/pinecone/service.py`
+
+### البوابة (Gateway)
+`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_query.py`
+`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_export.py`
+`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_import.py`
+
+### استرجاع المعلومات من المستندات (Document RAG)
+`trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` - إضافة عميل أمين المكتبة
+`trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` - الاسترداد من Garage
+
+### واجهة سطر الأوامر (CLI)
+`trustgraph-cli/trustgraph/cli/invoke_document_embeddings.py`
+`trustgraph-cli/trustgraph/cli/save_doc_embeds.py`
+`trustgraph-cli/trustgraph/cli/load_doc_embeds.py`
+
+## الفوائد
+
+1. مصدر واحد للحقيقة - نص الأجزاء فقط في Garage
+2. تقليل مساحة التخزين في مخزن المتجهات
+3. يتيح تتبع مصدر المعلومات في وقت الاستعلام عبر معرف الجزء.

docs/tech-specs/ar/embeddings-batch-processing.ar.md

@@ -0,0 +1,675 @@
+---
+layout: default
+title: "المواصفات الفنية لمعالجة الدفعات لخدمة التضمينات (Embeddings)"
+parent: "Arabic (Beta)"
+---
+
+# المواصفات الفنية لمعالجة الدفعات لخدمة التضمينات (Embeddings)
+
+> **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. **عدم كفاءة معالجة النصوص الفردية**: يغلف التنفيذ الحالي النصوص الفردية في قائمة، مما يؤدي إلى عدم الاستفادة الكاملة من قدرات الدفعات في FastEmbed.
+2. **العبء الزائد لكل طلب نص**: يتطلب كل نص رسالة Pulsar منفصلة، مما يتطلب جولة ذهاب وإياب.
+3. **عدم كفاءة استنتاج النموذج**: نماذج التضمين لها عبء ثابت لكل دفعة؛ فإن الدفعات الصغيرة تهدر موارد وحدة معالجة الرسومات (GPU) ووحدة المعالجة المركزية (CPU).
+4. **المعالجة التسلسلية في التطبيقات**: تقوم الخدمات الرئيسية بالتكرار على العناصر واستدعاء التضمينات واحدًا تلو الآخر.
+
+## الأهداف
+
+**دعم واجهة برمجة تطبيقات (API) للدفعات**: تمكين معالجة نصوص متعددة في طلب واحد.
+**التوافق مع الإصدارات السابقة**: الحفاظ على دعم الطلبات التي تتضمن نصًا واحدًا فقط.
+**تحسين كبير في الإنتاجية**: استهداف تحسين في الإنتاجية يتراوح بين 5 إلى 10 مرات للعمليات الجماعية.
+**تقليل زمن الوصول لكل نص**: تقليل زمن الوصول المتوسط عند تضمين نصوص متعددة.
+**كفاءة الذاكرة**: معالجة الدفعات دون استهلاك مفرط للذاكرة.
+**الاستقلالية عن المزود**: دعم التجميع عبر FastEmbed و Ollama ومزودين آخرين.
+**تحديث التطبيقات**: تحديث جميع تطبيقات التضمين لاستخدام واجهة برمجة تطبيقات الدفعات عند الإمكان.
+
+## الخلفية
+
+### التنفيذ الحالي - خدمة التضمينات
+
+يُظهر تطبيق التضمينات في `trustgraph-flow/trustgraph/embeddings/fastembed/processor.py` عدم كفاءة كبيرة في الأداء:
+
+```python
+# fastembed/processor.py line 56
+async def on_embeddings(self, text, model=None):
+    use_model = model or self.default_model
+    self._load_model(use_model)
+
+    vecs = self.embeddings.embed([text])  # Single text wrapped in list
+
+    return [v.tolist() for v in vecs]
+```
+
+**المشاكل:**
+
+1. **حجم الدفعة 1**: طريقة `embed()` في FastEmbed مُحسّنة للمعالجة الدفعية، ولكننا نستدعيها دائمًا مع `[text]` - دفعة بحجم 1.
+
+2. **التكلفة لكل طلب**: كل طلب تضمين يتضمن:
+   تسلسل/إلغاء تسلسل رسالة Pulsar.
+   زمن انتقال الشبكة.
+   تكلفة بدء تشغيل الاستدلال للنموذج.
+   تكلفة جدولة المهام غير المتزامنة في Python.
+
+3. **قيود المخطط**: مخطط `EmbeddingsRequest` يدعم نصًا واحدًا فقط:
+   ```python
+   @dataclass
+   class EmbeddingsRequest:
+       text: str = ""  # Single text only
+   ```
+
+### المستخدمون الحاليون - المعالجة التسلسلية
+
+#### 1. بوابة واجهة برمجة التطبيقات (API Gateway)
+
+**الملف:** `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
+
+تقبل البوابة طلبات تضمين النصوص الفردية عبر HTTP/WebSocket وتوجهها إلى خدمة التضمين. حاليًا، لا يوجد نقطة نهاية للدفعات.
+
+```python
+class EmbeddingsRequestor(ServiceRequestor):
+    # Handles single EmbeddingsRequest -> EmbeddingsResponse
+    request_schema=EmbeddingsRequest,  # Single text only
+    response_schema=EmbeddingsResponse,
+```
+
+**التأثير:** يجب على العملاء الخارجيين (تطبيقات الويب، النصوص البرمجية) إجراء N طلب HTTP لتضمين N نص.
+
+#### 2. خدمة تضمين المستندات
+
+**الملف:** `trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
+
+يعالج أجزاء المستندات واحدة تلو الأخرى:
+
+```python
+async def on_message(self, msg, consumer, flow):
+    v = msg.value()
+
+    # Single chunk per request
+    resp = await flow("embeddings-request").request(
+        EmbeddingsRequest(text=v.chunk)
+    )
+    vectors = resp.vectors
+```
+
+**التأثير:** تتطلب كل جزء من المستند استدعاءً منفصلاً لعملية التضمين. المستند الذي يتكون من 100 جزء = 100 طلب تضمين.
+
+#### 3. خدمة تضمين الرسوم البيانية
+
+**الملف:** `trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
+
+يتكرر على الكيانات ويقوم بتضمين كل منها بالتسلسل:
+
+```python
+async def on_message(self, msg, consumer, flow):
+    for entity in v.entities:
+        # Serial embedding - one entity at a time
+        vectors = await flow("embeddings-request").embed(
+            text=entity.context
+        )
+        entities.append(EntityEmbeddings(
+            entity=entity.entity,
+            vectors=vectors,
+            chunk_id=entity.chunk_id,
+        ))
+```
+
+**التأثير:** رسالة تحتوي على 50 كيانًا = 50 طلب تضمين تسلسلي. هذا يمثل عنق زجاجة رئيسي أثناء بناء الرسم البياني المعرفي.
+
+#### 4. خدمة تضمين الصفوف
+
+**الملف:** `trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
+
+يتكرر على النصوص الفريدة ويضمّن كل منها بشكل تسلسلي:
+
+```python
+async def on_message(self, msg, consumer, flow):
+    for text, (index_name, index_value) in texts_to_embed.items():
+        # Serial embedding - one text at a time
+        vectors = await flow("embeddings-request").embed(text=text)
+
+        embeddings_list.append(RowIndexEmbedding(
+            index_name=index_name,
+            index_value=index_value,
+            text=text,
+            vectors=vectors
+        ))
+```
+
+**التأثير:** معالجة جدول يحتوي على 100 قيمة فريدة مفهرسة = 100 طلب تضمين متسلسل.
+
+#### 5. EmbeddingsClient (العميل الأساسي)
+
+**الملف:** `trustgraph-base/trustgraph/base/embeddings_client.py`
+
+العميل المستخدم من قبل جميع معالجات التدفق يدعم فقط تضمين النصوص الفردية:
+
+```python
+class EmbeddingsClient(RequestResponse):
+    async def embed(self, text, timeout=30):
+        resp = await self.request(
+            EmbeddingsRequest(text=text),  # Single text
+            timeout=timeout
+        )
+        return resp.vectors
+```
+
+**التأثير:** جميع المستخدمين الذين يعتمدون على هذا البرنامج يقتصرون على العمليات النصية البسيطة.
+
+#### 6. أدوات سطر الأوامر
+
+**الملف:** `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
+
+أداة سطر الأوامر تقبل وسيط نصي واحد:
+
+```python
+def query(url, flow_id, text, token=None):
+    result = flow.embeddings(text=text)  # Single text
+    vectors = result.get("vectors", [])
+```
+
+**التأثير:** لا يمكن للمستخدمين إجراء تضمين مجمّع من سطر الأوامر. يتطلب معالجة ملف من النصوص عدد N من الاستدعاءات.
+
+#### 7. حزمة تطوير البرمجيات (SDK) الخاصة بـ Python
+
+توفر حزمة تطوير البرمجيات الخاصة بـ Python فئتين من العملاء للتفاعل مع خدمات TrustGraph. تدعم كلتاهما فقط التضمين لنص واحد.
+
+**الملف:** `trustgraph-base/trustgraph/api/flow.py`
+
+```python
+class FlowInstance:
+    def embeddings(self, text):
+        """Get embeddings for a single text"""
+        input = {"text": text}
+        return self.request("service/embeddings", input)["vectors"]
+```
+
+**الملف:** `trustgraph-base/trustgraph/api/socket_client.py`
+
+```python
+class SocketFlowInstance:
+    def embeddings(self, text: str, **kwargs: Any) -> Dict[str, Any]:
+        """Get embeddings for a single text via WebSocket"""
+        request = {"text": text}
+        return self.client._send_request_sync(
+            "embeddings", self.flow_id, request, False
+        )
+```
+
+**التأثير:** يجب على مطوري بايثون الذين يستخدمون مجموعة تطوير البرامج (SDK) المرور على النصوص وإجراء مكالمات واجهة برمجة التطبيقات (API) منفصلة. لا يوجد دعم لعمليات الدمج المجمعة لمستخدمي مجموعة تطوير البرامج.
+
+### تأثير الأداء
+
+بالنسبة لاستيعاب المستندات النموذجي (1000 جزء نصي):
+**الحالي:** 1000 طلب منفصل، و1000 استدعاء لنموذج الاستدلال.
+**مجمعة (batch_size=32):** 32 طلبًا، و32 استدعاء لنموذج الاستدلال (انخفاض بنسبة 96.8٪).
+
+بالنسبة لدمج الرسم البياني (رسالة تحتوي على 50 كيانًا):
+**الحالي:** 50 استدعاء انتظار متسلسل، من 5 إلى 10 ثوانٍ تقريبًا.
+**مجمعة:** 1-2 استدعاء مجمع، من 0.5 إلى 1 ثانية تقريبًا (تحسين بمقدار 5-10 مرات).
+
+تحقق مكتبات FastEmbed والمكتبات المماثلة تقريبًا من قابلية التوسع الخطية في الإنتاجية مع حجم الدفعة حتى حدود الأجهزة (عادةً ما تكون 32-128 نصًا لكل دفعة).
+
+## التصميم الفني
+
+### البنية
+
+يتطلب تحسين معالجة الدفعات لإنشاء تضمينات تغييرات في المكونات التالية:
+
+#### 1. **تحسين المخطط**
+   قم بتوسيع `EmbeddingsRequest` لدعم نصوص متعددة.
+   قم بتوسيع `EmbeddingsResponse` لإرجاع مجموعات متجهات متعددة.
+   حافظ على التوافق مع الإصدارات السابقة مع طلبات النص الواحد.
+
+   الوحدة: `trustgraph-base/trustgraph/schema/services/llm.py`
+
+#### 2. **تحسين الخدمة الأساسية**
+   قم بتحديث `EmbeddingsService` للتعامل مع الطلبات المجمعة.
+   أضف تكوين حجم الدفعة.
+   قم بتنفيذ معالجة الطلبات الواعية بالدفعة.
+
+   الوحدة: `trustgraph-base/trustgraph/base/embeddings_service.py`
+
+#### 3. **تحديثات معالج المزود**
+   قم بتحديث معالج FastEmbed لتمرير الدفعة الكاملة إلى `embed()`.
+   قم بتحديث معالج Ollama للتعامل مع الدفعات (إذا تم الدعم).
+   أضف معالجة تسلسلية احتياطية للمزودين الذين لا يدعمون الدفعات.
+
+   الوحدات:
+   `trustgraph-flow/trustgraph/embeddings/fastembed/processor.py`
+   `trustgraph-flow/trustgraph/embeddings/ollama/processor.py`
+
+#### 4. **تحسين العميل**
+   أضف طريقة إنشاء تضمينات مجمعة إلى `EmbeddingsClient`.
+   دعم كل من واجهات برمجة التطبيقات الفردية والمجمعة.
+   أضف تجميعًا تلقائيًا للمدخلات الكبيرة.
+
+   الوحدة: `trustgraph-base/trustgraph/base/embeddings_client.py`
+
+#### 5. **تحديثات المتصل - معالجات التدفق**
+   قم بتحديث `graph_embeddings` لتجميع سياقات الكيانات.
+   قم بتحديث `row_embeddings` لتجميع نصوص الفهرس.
+   قم بتحديث `document_embeddings` إذا كان تجميع الرسائل ممكنًا.
+
+   الوحدات:
+   `trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
+   `trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
+   `trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
+
+#### 6. **تحسين بوابة واجهة برمجة التطبيقات**
+   أضف نقطة نهاية لإنشاء تضمينات مجمعة.
+   دعم مصفوفة من النصوص في نص الطلب.
+
+   الوحدة: `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
+
+#### 7. **تحسين أداة سطر الأوامر**
+   أضف دعمًا للنصوص المتعددة أو إدخال الملف.
+   أضف معلمة حجم الدفعة.
+
+   الوحدة: `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
+
+#### 8. **تحسين مجموعة تطوير البرامج (SDK) الخاصة بـ Python**
+   أضف طريقة `embeddings_batch()` إلى `FlowInstance`.
+   أضف طريقة `embeddings_batch()` إلى `SocketFlowInstance`.
+   دعم كل من واجهات برمجة التطبيقات الفردية والمجمعة لمستخدمي مجموعة تطوير البرامج.
+
+   الوحدات:
+   `trustgraph-base/trustgraph/api/flow.py`
+   `trustgraph-base/trustgraph/api/socket_client.py`
+
+### نماذج البيانات
+
+#### EmbeddingsRequest
+
+```python
+@dataclass
+class EmbeddingsRequest:
+    texts: list[str] = field(default_factory=list)
+```
+
+الاستخدام:
+نص مفرد: `EmbeddingsRequest(texts=["hello world"])`
+دفعة: `EmbeddingsRequest(texts=["text1", "text2", "text3"])`
+
+#### EmbeddingsResponse
+
+```python
+@dataclass
+class EmbeddingsResponse:
+    error: Error | None = None
+    vectors: list[list[list[float]]] = field(default_factory=list)
+```
+
+هيكل الاستجابة:
+`vectors[i]` يحتوي على مجموعة المتجهات لـ `texts[i]`
+كل مجموعة متجهات هي `list[list[float]]` (قد تُرجع النماذج عدة متجهات لكل نص)
+مثال: 3 نصوص → `vectors` يحتوي على 3 إدخالات، كل منها يحتوي على تضمينات هذا النص
+
+### واجهات برمجة التطبيقات (APIs)
+
+#### EmbeddingsClient
+
+```python
+class EmbeddingsClient(RequestResponse):
+    async def embed(
+        self,
+        texts: list[str],
+        timeout: float = 300,
+    ) -> list[list[list[float]]]:
+        """
+        Embed one or more texts in a single request.
+
+        Args:
+            texts: List of texts to embed
+            timeout: Timeout for the operation
+
+        Returns:
+            List of vector sets, one per input text
+        """
+        resp = await self.request(
+            EmbeddingsRequest(texts=texts),
+            timeout=timeout
+        )
+        if resp.error:
+            raise RuntimeError(resp.error.message)
+        return resp.vectors
+```
+
+#### نقطة نهاية تضمين بوابة واجهة برمجة التطبيقات (API Gateway).
+
+تم تحديث نقطة النهاية لدعم التضمين الفردي أو الدفعي:
+
+```
+POST /api/v1/embeddings
+Content-Type: application/json
+
+{
+    "texts": ["text1", "text2", "text3"],
+    "flow_id": "default"
+}
+
+Response:
+{
+    "vectors": [
+        [[0.1, 0.2, ...]],
+        [[0.3, 0.4, ...]],
+        [[0.5, 0.6, ...]]
+    ]
+}
+```
+
+### تفاصيل التنفيذ
+
+#### المرحلة الأولى: تغييرات المخطط
+
+**EmbeddingsRequest:**
+```python
+@dataclass
+class EmbeddingsRequest:
+    texts: list[str] = field(default_factory=list)
+```
+
+**الاستجابة المضمنة:**
+```python
+@dataclass
+class EmbeddingsResponse:
+    error: Error | None = None
+    vectors: list[list[list[float]]] = field(default_factory=list)
+```
+
+**تم تحديث `EmbeddingsService.on_request`:**
+```python
+async def on_request(self, msg, consumer, flow):
+    request = msg.value()
+    id = msg.properties()["id"]
+    model = flow("model")
+
+    vectors = await self.on_embeddings(request.texts, model=model)
+    response = EmbeddingsResponse(error=None, vectors=vectors)
+
+    await flow("response").send(response, properties={"id": id})
+```
+
+#### المرحلة الثانية: تحديث معالج FastEmbed
+
+**الحالي (غير فعال):**
+```python
+async def on_embeddings(self, text, model=None):
+    use_model = model or self.default_model
+    self._load_model(use_model)
+    vecs = self.embeddings.embed([text])  # Batch of 1
+    return [v.tolist() for v in vecs]
+```
+
+**تحديث:**
+```python
+async def on_embeddings(self, texts: list[str], model=None):
+    """Embed texts - processes all texts in single model call"""
+    if not texts:
+        return []
+
+    use_model = model or self.default_model
+    self._load_model(use_model)
+
+    # FastEmbed handles the full batch efficiently
+    all_vecs = list(self.embeddings.embed(texts))
+
+    # Return list of vector sets, one per input text
+    return [[v.tolist()] for v in all_vecs]
+```
+
+#### المرحلة الثالثة: تحديث خدمة تضمين الرسوم البيانية
+
+**الحالي (التسلسلي):**
+```python
+async def on_message(self, msg, consumer, flow):
+    entities = []
+    for entity in v.entities:
+        vectors = await flow("embeddings-request").embed(text=entity.context)
+        entities.append(EntityEmbeddings(...))
+```
+
+**تحديث (مجموعة):**
+```python
+async def on_message(self, msg, consumer, flow):
+    # Collect all contexts
+    contexts = [entity.context for entity in v.entities]
+
+    # Single batch embedding call
+    all_vectors = await flow("embeddings-request").embed(texts=contexts)
+
+    # Pair results with entities
+    entities = [
+        EntityEmbeddings(
+            entity=entity.entity,
+            vectors=vectors[0],  # First vector from the set
+            chunk_id=entity.chunk_id,
+        )
+        for entity, vectors in zip(v.entities, all_vectors)
+    ]
+```
+
+#### المرحلة الرابعة: تحديث خدمة تضمين الصفوف
+
+**الحالي (تسلسلي):**
+```python
+for text, (index_name, index_value) in texts_to_embed.items():
+    vectors = await flow("embeddings-request").embed(text=text)
+    embeddings_list.append(RowIndexEmbedding(...))
+```
+
+**تحديث (مجموعة):**
+```python
+# Collect texts and metadata
+texts = list(texts_to_embed.keys())
+metadata = list(texts_to_embed.values())
+
+# Single batch embedding call
+all_vectors = await flow("embeddings-request").embed(texts=texts)
+
+# Pair results
+embeddings_list = [
+    RowIndexEmbedding(
+        index_name=meta[0],
+        index_value=meta[1],
+        text=text,
+        vectors=vectors[0]  # First vector from the set
+    )
+    for text, meta, vectors in zip(texts, metadata, all_vectors)
+]
+```
+
+#### المرحلة الخامسة: تحسين أداة سطر الأوامر.
+
+**سطر الأوامر المحدث:**
+```python
+def main():
+    parser = argparse.ArgumentParser(...)
+
+    parser.add_argument(
+        'text',
+        nargs='*',  # Zero or more texts
+        help='Text(s) to convert to embedding vectors',
+    )
+
+    parser.add_argument(
+        '-f', '--file',
+        help='File containing texts (one per line)',
+    )
+
+    parser.add_argument(
+        '--batch-size',
+        type=int,
+        default=32,
+        help='Batch size for processing (default: 32)',
+    )
+```
+
+الاستخدام:
+```bash
+# Single text (existing)
+tg-invoke-embeddings "hello world"
+
+# Multiple texts
+tg-invoke-embeddings "text one" "text two" "text three"
+
+# From file
+tg-invoke-embeddings -f texts.txt --batch-size 64
+```
+
+#### المرحلة السادسة: تحسين حزمة تطوير البرمجيات (SDK) الخاصة بـ Python
+
+**FlowInstance (عميل HTTP):**
+
+```python
+class FlowInstance:
+    def embeddings(self, texts: list[str]) -> list[list[list[float]]]:
+        """
+        Get embeddings for one or more texts.
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector sets, one per input text
+        """
+        input = {"texts": texts}
+        return self.request("service/embeddings", input)["vectors"]
+```
+
+**مثيل SocketFlow (عميل WebSocket):**
+
+```python
+class SocketFlowInstance:
+    def embeddings(self, texts: list[str], **kwargs: Any) -> list[list[list[float]]]:
+        """
+        Get embeddings for one or more texts via WebSocket.
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector sets, one per input text
+        """
+        request = {"texts": texts}
+        response = self.client._send_request_sync(
+            "embeddings", self.flow_id, request, False
+        )
+        return response["vectors"]
+```
+
+**أمثلة على استخدام الـ SDK:**
+
+```python
+# Single text
+vectors = flow.embeddings(["hello world"])
+print(f"Dimensions: {len(vectors[0][0])}")
+
+# Batch embedding
+texts = ["text one", "text two", "text three"]
+all_vectors = flow.embeddings(texts)
+
+# Process results
+for text, vecs in zip(texts, all_vectors):
+    print(f"{text}: {len(vecs[0])} dimensions")
+```
+
+## اعتبارات الأمان
+
+**حدود حجم الطلب**: فرض الحد الأقصى لحجم الدفعة لمنع استنزاف الموارد.
+**معالجة انتهاء المهلة**: قم بتعيين قيم انتهاء المهلة بشكل مناسب لحجم الدفعة.
+**حدود الذاكرة**: راقب استخدام الذاكرة للدفعات الكبيرة.
+**التحقق من صحة الإدخال**: تحقق من صحة جميع النصوص في الدفعة قبل المعالجة.
+
+## اعتبارات الأداء
+
+### التحسينات المتوقعة
+
+**معدل الإنتاجية:**
+نص واحد: ~10-50 نصًا/ثانية (حسب النموذج)
+دفعة (حجم 32): ~200-500 نص/ثانية (تحسين بمقدار 5-10 مرات)
+
+**زمن الوصول لكل نص:**
+نص واحد: 50-200 مللي ثانية لكل نص
+دفعة (حجم 32): 5-20 مللي ثانية لكل نص (متوسط)
+
+**التحسينات الخاصة بالخدمة:**
+
+| الخدمة | الحالي | الدفعات | التحسين |
+|---------|---------|---------|-------------|
+| تضمينات الرسم البياني (50 كيانًا) | 5-10 ثوانٍ | 0.5-1 ثانية | 5-10 مرات |
+| تضمينات الصفوف (100 نص) | 10-20 ثانية | 1-2 ثانية | 5-10 مرات |
+| استيعاب المستندات (1000 جزء) | 100-200 ثانية | 10-30 ثانية | 5-10 مرات |
+
+### معلمات التكوين
+
+```python
+# Recommended defaults
+DEFAULT_BATCH_SIZE = 32
+MAX_BATCH_SIZE = 128
+BATCH_TIMEOUT_MULTIPLIER = 2.0
+```
+
+## استراتيجية الاختبار
+
+### اختبار الوحدات
+تضمين نص واحد (التوافق مع الإصدارات السابقة)
+معالجة الدُفعات الفارغة
+فرض الحد الأقصى لحجم الدفعة
+معالجة الأخطاء في حالة فشل بعض عناصر الدفعة
+
+### اختبار التكامل
+تضمين الدُفعات من البداية إلى النهاية عبر Pulsar
+معالجة الدُفعات لخدمة تضمينات الرسم البياني
+معالجة الدُفعات لخدمة تضمينات الصفوف
+نقطة نهاية الدُفعات لبوابة واجهة برمجة التطبيقات
+
+### اختبار الأداء
+قياس الإنتاجية الفردية مقابل الإنتاجية عند استخدام الدُفعات
+استخدام الذاكرة تحت أحجام دفعات مختلفة
+تحليل توزيع زمن الاستجابة
+
+## خطة الترحيل
+
+هذا إصدار يتضمن تغييرات جذرية. يتم تنفيذ جميع المراحل معًا.
+
+### المرحلة الأولى: تغييرات المخطط
+استبدال `text: str` بـ `texts: list[str]` في EmbeddingsRequest
+تغيير نوع `vectors` إلى `list[list[list[float]]]` في EmbeddingsResponse
+
+### المرحلة الثانية: تحديثات المعالج
+تحديث توقيع `on_embeddings` في معالجات FastEmbed و Ollama
+معالجة الدفعة بأكملها في استدعاء واحد للنموذج
+
+### المرحلة الثالثة: تحديثات العميل
+تحديث `EmbeddingsClient.embed()` لقبول `texts: list[str]`
+
+### المرحلة الرابعة: تحديثات المستخدم
+تحديث graph_embeddings لمعالجة سياقات الكيانات على شكل دفعات
+تحديث row_embeddings لمعالجة نصوص الفهرس على شكل دفعات
+تحديث document_embeddings لاستخدام المخطط الجديد
+تحديث أداة سطر الأوامر
+
+### المرحلة الخامسة: بوابة واجهة برمجة التطبيقات
+تحديث نقطة نهاية تضمين للمخطط الجديد
+
+### المرحلة السادسة: حزمة تطوير البرمجيات بلغة بايثون
+تحديث توقيع `FlowInstance.embeddings()`
+تحديث توقيع `SocketFlowInstance.embeddings()`
+
+## أسئلة مفتوحة
+
+**معالجة الدُفعات الكبيرة جدًا**: هل يجب أن ندعم إرجاع النتائج على شكل دفعات صغيرة جدًا للدُفعات الكبيرة جدًا (أكثر من 100 نص)؟
+**القيود الخاصة بالمزودين**: كيف يجب أن نتعامل مع المزودين الذين لديهم أحجام دفعات قصوى مختلفة؟
+**معالجة حالات الفشل الجزئية**: إذا فشل أحد النصوص في الدفعة، فهل يجب أن نفشل الدفعة بأكملها أم أن نرجع النتائج الجزئية؟
+**تجميع تضمينات المستندات**: هل يجب أن نقوم بتجميع البيانات عبر رسائل Chunk متعددة أم أن نحافظ على المعالجة لكل رسالة؟
+
+## المراجع
+
+[وثائق FastEmbed](https://github.com/qdrant/fastembed)
+[واجهة برمجة تطبيقات Ollama Embeddings](https://github.com/ollama/ollama)
+[تنفيذ EmbeddingsService](trustgraph-base/trustgraph/base/embeddings_service.py)
+[تحسين أداء GraphRAG](graphrag-performance-optimization.md)

docs/tech-specs/ar/entity-centric-graph.ar.md

@@ -0,0 +1,268 @@
+---
+layout: default
+title: "تخزين الرسم البياني المعرفي المرتكز على الكيانات على Cassandra"
+parent: "Arabic (Beta)"
+---
+
+# تخزين الرسم البياني المعرفي المرتكز على الكيانات على Cassandra
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## نظرة عامة
+
+يصف هذا المستند نموذج تخزين للرسوم البيانية المعرفية بنمط RDF على Apache Cassandra. يستخدم النموذج نهجًا **مرتكزًا على الكيانات** حيث يعرف كل كيان كل رباعية يشارك فيها والدور الذي يلعبه. هذا يحل محل نهج تبديل SPO متعدد الجداول باستخدام جدولين فقط.
+
+## الخلفية والدوافع
+
+### النهج التقليدي
+
+يتطلب متجر رباعي RDF قياسي على Cassandra جداول متعددة غير طبيعية لتغطية أنماط الاستعلام - عادةً 6 جداول أو أكثر تمثل تبديلات مختلفة للموضوع والمسند والموضوع ومجموعة البيانات (SPOD). يتم كتابة كل رباعية في كل جدول، مما يؤدي إلى تضخيم كبير في عمليات الكتابة، والنفقات التشغيلية، وتعقيد المخطط.
+
+بالإضافة إلى ذلك، يتطلب تحليل التسميات (جلب أسماء قابلة للقراءة للبشر للكيانات) استعلامات إضافية، وهو أمر مكلف بشكل خاص في حالات استخدام الذكاء الاصطناعي و GraphRAG حيث تعتبر التسميات ضرورية لسياق LLM.
+
+### الرؤية المرتكزة على الكيانات
+
+تتضمن كل رباعية `(D, S, P, O)` ما يصل إلى 4 كيانات. من خلال كتابة صف لكل مشاركة للكيان في الرباعية، نضمن أن **أي استعلام يحتوي على عنصر معروف واحد سيضرب مفتاح التقسيم**. يغطي هذا جميع أنماط الاستعلام الـ 16 باستخدام جدول بيانات واحد.
+
+الفوائد الرئيسية:
+
+**جدولان** بدلاً من 7 أو أكثر
+**4 عمليات كتابة لكل رباعية** بدلاً من 6 أو أكثر
+**تحليل التسميات مجانًا** - يتم تخزين تسميات الكيان مع علاقاته، مما يؤدي بشكل طبيعي إلى تسخين ذاكرة التخزين المؤقت للتطبيق
+**جميع أنماط الاستعلام الـ 16** يتم تقديمها من خلال قراءات ذات قسم واحد
+**عمليات أبسط** - جدول بيانات واحد للضبط والضغط والإصلاح
+
+## المخطط
+
+### الجدول 1: quads_by_entity
+
+الجدول الرئيسي للبيانات. يحتوي كل كيان على قسم يحتوي على جميع الرباعيات التي يشارك فيها. تم تسميته ليعكس نمط الاستعلام (البحث حسب الكيان).
+
+```sql
+CREATE TABLE quads_by_entity (
+    collection text,       -- Collection/tenant scope (always specified)
+    entity     text,       -- The entity this row is about
+    role       text,       -- 'S', 'P', 'O', 'G' — how this entity participates
+    p          text,       -- Predicate of the quad
+    otype      text,       -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
+    s          text,       -- Subject of the quad
+    o          text,       -- Object of the quad
+    d          text,       -- Dataset/graph of the quad
+    dtype      text,       -- XSD datatype (when otype = 'L'), e.g. 'xsd:string'
+    lang       text,       -- Language tag (when otype = 'L'), e.g. 'en', 'fr'
+    PRIMARY KEY ((collection, entity), role, p, otype, s, o, d, dtype, lang)
+);
+```
+
+**مفتاح التقسيم:** `(collection, entity)` - محدد للنطاق ضمن المجموعة، قسم واحد لكل كيان.
+
+**المنطق وراء ترتيب أعمدة التجميع:**
+
+1. **role** - معظم الاستعلامات تبدأ بـ "أين يقع هذا الكيان كموضوع/موضوع؟"
+2. **p** - المرشح الأكثر شيوعًا بعد ذلك، "أعطني جميع `knows` العلاقات".
+3. **otype** - يتيح التصفية حسب العلاقات ذات القيم المحددة بواسطة URI مقابل العلاقات ذات القيم الحرفية.
+4. **s, o, d** - الأعمدة المتبقية لضمان التفرد.
+5. **dtype, lang** - التمييز بين القيم الحرفية التي لها نفس القيمة ولكن بيانات تعريف نوع مختلفة (على سبيل المثال، `"thing"` مقابل `"thing"@en` مقابل `"thing"^^xsd:string`).
+
+### الجدول 2: quads_by_collection
+
+يدعم الاستعلامات والإجراءات الحذف على مستوى المجموعة. يوفر قائمة بجميع الرباعيات التي تنتمي إلى مجموعة. تم تسميته ليعكس نمط الاستعلام (البحث حسب المجموعة).
+
+```sql
+CREATE TABLE quads_by_collection (
+    collection text,
+    d          text,       -- Dataset/graph of the quad
+    s          text,       -- Subject of the quad
+    p          text,       -- Predicate of the quad
+    o          text,       -- Object of the quad
+    otype      text,       -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
+    dtype      text,       -- XSD datatype (when otype = 'L')
+    lang       text,       -- Language tag (when otype = 'L')
+    PRIMARY KEY (collection, d, s, p, o, otype, dtype, lang)
+);
+```
+
+يتم التجميع بناءً على مجموعة البيانات أولاً، مما يتيح الحذف على مستوى المجموعة أو مستوى مجموعة البيانات. يتم تضمين الأعمدة `otype` و `dtype` و `lang` في مفتاح التجميع للتمييز بين القيم الحرفية التي لها نفس القيمة ولكن بيانات تعريف نوع مختلفة - في RDF، `"thing"` و `"thing"@en` و `"thing"^^xsd:string` هي قيم متميزة دلاليًا.
+
+## مسار الكتابة
+
+لكل مجموعة رباعية `(D, S, P, O)` واردة ضمن مجموعة `C`، اكتب **4 صفوف** إلى `quads_by_entity` و **صف واحد** إلى `quads_by_collection`.
+
+### مثال
+
+بالنظر إلى المجموعة الرباعية في المجموعة `tenant1`:
+
+```
+Dataset:  https://example.org/graph1
+Subject:  https://example.org/Alice
+Predicate: https://example.org/knows
+Object:   https://example.org/Bob
+```
+
+اكتب 4 صفوف إلى `quads_by_entity`:
+
+| collection | entity | role | p | otype | s | o | d |
+|---|---|---|---|---|---|---|---|
+| tenant1 | https://example.org/graph1 | G | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
+| tenant1 | https://example.org/Alice | S | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
+| tenant1 | https://example.org/knows | P | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
+| tenant1 | https://example.org/Bob | O | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
+
+اكتب صفًا واحدًا إلى `quads_by_collection`:
+
+| collection | d | s | p | o | otype | dtype | lang |
+|---|---|---|---|---|---|---|---|
+| tenant1 | https://example.org/graph1 | https://example.org/Alice | https://example.org/knows | https://example.org/Bob | U | | |
+
+### مثال حرفي
+
+بالنسبة لثلاثية التسمية:
+
+```
+Dataset:  https://example.org/graph1
+Subject:  https://example.org/Alice
+Predicate: http://www.w3.org/2000/01/rdf-schema#label
+Object:   "Alice Smith" (lang: en)
+```
+
+الرمز `otype` هو `'L'`، و `dtype` هو `'xsd:string'`، و `lang` هو `'en'`. يتم تخزين القيمة الحرفية `"Alice Smith"` في `o`. هناك حاجة إلى 3 صفوف فقط في `quads_by_entity` - لا يتم كتابة أي صف للقيمة الحرفية ككيان، نظرًا لأن القيم الحرفية ليست كيانات قابلة للاستعلام بشكل مستقل.
+
+## أنماط الاستعلام
+
+### جميع أنماط DSPO الـ 16
+
+في الجدول أدناه، تعني عبارة "بادئة مثالية" أن الاستعلام يستخدم بادئة متجاورة لأعمدة التجميع. تعني عبارة "فحص التقسيم + التصفية" أن Cassandra تقرأ جزءًا من التقسيم وتقوم بالتصفية في الذاكرة - لا يزال فعالاً، ولكنه ليس تطابقًا خالصًا للبادئة.
+
+| # | Known | Lookup entity | Clustering prefix | Efficiency |
+|---|---|---|---|---|
+| 1 | D,S,P,O | entity=S, role='S', p=P | تطابق كامل | بادئة مثالية |
+| 2 | D,S,P,? | entity=S, role='S', p=P | التصفية على D | فحص التقسيم + التصفية |
+| 3 | D,S,?,O | entity=S, role='S' | التصفية على D، O | فحص التقسيم + التصفية |
+| 4 | D,?,P,O | entity=O, role='O', p=P | التصفية على D | فحص التقسيم + التصفية |
+| 5 | ?,S,P,O | entity=S, role='S', p=P | التصفية على O | فحص التقسيم + التصفية |
+| 6 | D,S,?,? | entity=S, role='S' | التصفية على D | فحص التقسيم + التصفية |
+| 7 | D,?,P,? | entity=P, role='P' | التصفية على D | فحص التقسيم + التصفية |
+| 8 | D,?,?,O | entity=O, role='O' | التصفية على D | فحص التقسيم + التصفية |
+| 9 | ?,S,P,? | entity=S, role='S', p=P | — | **بادئة مثالية** |
+| 10 | ?,S,?,O | entity=S, role='S' | التصفية على O | فحص التقسيم + التصفية |
+| 11 | ?,?,P,O | entity=O, role='O', p=P | — | **بادئة مثالية** |
+| 12 | D,?,?,? | entity=D, role='G' | — | **بادئة مثالية** |
+| 13 | ?,S,?,? | entity=S, role='S' | — | **بادئة مثالية** |
+| 14 | ?,?,P,? | entity=P, role='P' | — | **بادئة مثالية** |
+| 15 | ?,?,?,O | entity=O, role='O' | — | **بادئة مثالية** |
+| 16 | ?,?,?,? | — | فحص كامل | استكشاف فقط |
+
+**النتيجة الرئيسية:** 7 من أنماط الـ 15 غير التافهة هي تطابقات مثالية لبادئة التجميع. أما الـ 8 المتبقية فهي قراءات لتقسيم واحد مع تصفية داخل التقسيم. كل استعلام يحتوي على عنصر معروف واحد يطابق مفتاح التقسيم.
+
+نمط 16 (?,?,?,?) لا يحدث في الممارسة العملية لأنه يتم دائمًا تحديد المجموعة، مما يقلله إلى النمط 12.
+
+### أمثلة شائعة للاستعلام
+
+**كل شيء عن كيان:**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice';
+```
+
+**جميع العلاقات الخارجة لكيان:**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
+AND role = 'S';
+```
+
+**شرط محدد لكيان:**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
+AND role = 'S' AND p = 'https://example.org/knows';
+```
+
+**تسمية لكيان (بلغة محددة):**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
+AND role = 'S' AND p = 'http://www.w3.org/2000/01/rdf-schema#label'
+AND otype = 'L';
+```
+
+ثم قم بالتصفية باستخدام `lang = 'en'` من جانب التطبيق إذا لزم الأمر.
+
+**فقط العلاقات التي تحمل قيمًا من نوع URI (روابط من كيان إلى كيان):**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
+AND role = 'S' AND p = 'https://example.org/knows' AND otype = 'U';
+```
+
+**البحث العكسي - ما الذي يشير إلى هذا الكيان:**
+
+```sql
+SELECT * FROM quads_by_entity
+WHERE collection = 'tenant1' AND entity = 'https://example.org/Bob'
+AND role = 'O';
+```
+
+## حل التسميات وتدفئة ذاكرة التخزين المؤقت
+
+أحد أهم مزايا النموذج المرتكز على الكيانات هو أن **يصبح حل التسميات تأثيرًا ثانويًا مجانيًا**.
+
+في النموذج التقليدي متعدد الجداول، يتطلب استرداد التسميات استعلامات منفصلة: استرداد الثلاثيات، وتحديد معرفات الكيانات في النتائج، ثم استرداد `rdfs:label` لكل منها. هذا النمط N+1 مكلف.
+
+في النموذج المرتكز على الكيانات، يُرجع الاستعلام عن كيان **جميع** رباعياته - بما في ذلك تسمياته وأنواعه وخصائصه الأخرى. عندما يقوم التطبيق بتخزين نتائج الاستعلام مؤقتًا، يتم تدفئة التسميات مسبقًا قبل أن يطلبها أي شيء.
+
+يؤكد نظامان للاستخدام على أن هذا يعمل بشكل جيد في الممارسة:
+
+**الاستعلامات الموجهة للمستخدم**: مجموعات نتائج صغيرة بشكل طبيعي، والتسميات ضرورية. يؤدي قراءة الكيانات إلى تدفئة ذاكرة التخزين المؤقت مسبقًا.
+**استعلامات الذكاء الاصطناعي/الكمية الكبيرة**: مجموعات نتائج كبيرة مع حدود صارمة. التسميات إما غير ضرورية أو مطلوبة فقط لمجموعة فرعية من الكيانات تم تخزينها بالفعل في ذاكرة التخزين المؤقت.
+
+يتم تخفيف المخاوف النظرية المتعلقة بحل التسميات لمجموعات نتائج ضخمة (مثل 30000 كيان) بالملاحظة العملية القائلة بأنه لا يمكن لأي مستهلك بشري أو ذكاء اصطناعي معالجة هذا العدد الكبير من التسميات. تضمن حدود الاستعلام على مستوى التطبيق أن يظل ضغط ذاكرة التخزين المؤقت قابلاً للإدارة.
+
+## التقسيمات العريضة وإعادة التعريف
+
+يؤدي إعادة التعريف (عبارات على شكل RDF-star حول العبارات) إلى إنشاء كيانات مركزية - على سبيل المثال، مستند مصدر يدعم آلاف الحقائق المستخرجة. يمكن أن يؤدي هذا إلى تقسيمات عريضة.
+
+عوامل تخفيف:
+
+**حدود الاستعلام على مستوى التطبيق**: تفرض جميع استعلامات GraphRAG والاستعلامات الموجهة للمستخدم حدودًا صارمة، لذلك لا يتم فحص التقسيمات العريضة بالكامل على مسار القراءة الساخنة.
+**تتعامل Cassandra بكفاءة مع القراءات الجزئية**: يعد فحص عمود التجميع مع إيقاف مبكر أمرًا سريعًا حتى على التقسيمات الكبيرة.
+**حذف المجموعة** (العملية الوحيدة التي قد تتجاوز التقسيمات الكاملة) هي عملية خلفية مقبولة.
+
+## حذف المجموعة
+
+يتم تشغيله بواسطة استدعاء واجهة برمجة التطبيقات، ويعمل في الخلفية (متسق في النهاية).
+
+1. اقرأ `quads_by_collection` للمجموعة المستهدفة للحصول على جميع الرباعيات.
+2. استخرج الكيانات الفريدة من الرباعيات (قيم s و p و o و d).
+3. لكل كيان فريد، احذف التقسيم من `quads_by_entity`.
+4. احذف الصفوف من `quads_by_collection`.
+
+يوفر جدول `quads_by_collection` الفهرس المطلوب لتحديد موقع جميع تقسيمات الكيانات دون فحص كامل للجدول. عمليات حذف التقسيمات فعالة نظرًا لأن `(collection, entity)` هو مفتاح التقسيم.
+
+## مسار الترحيل من النموذج متعدد الجداول
+
+يمكن للنموذج المرتكز على الكيانات أن يتعايش مع النموذج متعدد الجداول الحالي أثناء الترحيل:
+
+1. نشر جداول `quads_by_entity` و `quads_by_collection` جنبًا إلى جنب مع الجداول الحالية.
+2. الكتابة المزدوجة للرباعيات الجديدة إلى كل من الجداول القديمة والجديدة.
+3. ملء البيانات الموجودة في الجداول الجديدة.
+4. ترحيل مسارات القراءة نمط استعلام واحد في كل مرة.
+5. إلغاء تنشيط الجداول القديمة بمجرد ترحيل جميع عمليات القراءة.
+
+## ملخص
+
+| الجانب | تقليدي (6 جداول) | مرتكز على الكيانات (جدولان) |
+|---|---|---|
+| الجداول | 7+ | 2 |
+| عمليات الكتابة لكل رباعية | 6+ | 5 (4 بيانات + 1 بيان) |
+| حل التسميات | استعلامات منفصلة | مجاني عبر تدفئة ذاكرة التخزين المؤقت |
+| أنماط الاستعلام | 16 عبر 6 جداول | 16 على جدول واحد |
+| تعقيد المخطط | مرتفع | منخفض |
+| النفقات التشغيلية | 6 جداول للتعديل/الإصلاح | جدول بيانات واحد |
+| دعم إعادة التعريف | تعقيد إضافي | مناسب بشكل طبيعي |
+| تصفية أنواع الكائنات | غير متوفر | أصلي (عبر التجميع حسب نوع الكائن) |

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

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

docs/tech-specs/ar/extraction-flows.ar.md

@@ -0,0 +1,355 @@
+---
+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، بدءًا من تقديم المستندات وصولًا إلى تخزينها في مستودعات المعرفة.
+
+## نظرة عامة
+
+```
+┌──────────┐     ┌─────────────┐     ┌─────────┐     ┌────────────────────┐
+│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge          │
+│          │     │ (PDF only)  │     │         │     │ Extraction         │
+│          │────────────────────────▶│         │     │                    │
+└──────────┘     └─────────────┘     └─────────┘     └────────────────────┘
+                                          │                    │
+                                          │                    ├──▶ Triples
+                                          │                    ├──▶ Entity Contexts
+                                          │                    └──▶ Rows
+                                          │
+                                          └──▶ Document Embeddings
+```
+
+## تخزين المحتوى
+
+### تخزين الكائنات (S3/Minio)
+
+يتم تخزين محتوى المستندات في تخزين الكائنات المتوافق مع S3:
+تنسيق المسار: `doc/{object_id}` حيث object_id هو معرف فريد عالمي (UUID)
+يتم تخزين جميع أنواع المستندات هنا: المستندات المصدر، الصفحات، الأجزاء
+
+### تخزين البيانات الوصفية (Cassandra)
+
+يتم تخزين البيانات الوصفية للمستندات في Cassandra وتشمل:
+معرف المستند، العنوان، النوع (نوع MIME)
+مرجع إلى تخزين الكائنات `object_id`
+مرجع إلى المستندات الفرعية (الصفحات، الأجزاء) `parent_id`
+`document_type`: "source"، "page"، "chunk"، "answer"
+
+### عتبة التضمين مقابل التدفق
+
+نقل المحتوى يستخدم استراتيجية تعتمد على الحجم:
+**أقل من 2 ميجابايت**: يتم تضمين المحتوى مباشرة في الرسالة (مشفر بـ base64).
+**أكبر من أو يساوي 2 ميجابايت**: يتم إرسال `document_id` فقط؛ يقوم المعالج باسترداد البيانات عبر واجهة برمجة التطبيقات الخاصة بالمكتبة.
+
+## المرحلة الأولى: تقديم المستند (المكتبة)
+
+### نقطة الدخول
+
+تدخل المستندات إلى النظام عبر عملية `add-document` الخاصة بالمكتبة:
+1. يتم تحميل المحتوى إلى مساحة تخزين الكائنات.
+2. يتم إنشاء سجل بيانات وصفية في Cassandra.
+3. يتم إرجاع معرف المستند.
+
+### بدء عملية الاستخراج
+
+عملية `add-processing` تبدأ عملية الاستخراج:
+تحدد `document_id`، و `flow` (معرف المسار)، و `collection` (مخزن الهدف).
+تقوم عملية `load_document()` الخاصة بالمكتبة باسترداد المحتوى ونشره في قائمة انتظار الإدخال الخاصة بالتدفق.
+
+### المخطط: المستند
+
+```
+Document
+├── metadata: Metadata
+│   ├── id: str              # Document identifier
+│   ├── user: str            # Tenant/user ID
+│   ├── collection: str      # Target collection
+│   └── metadata: list[Triple]  # (largely unused, historical)
+├── data: bytes              # PDF content (base64, if inline)
+└── document_id: str         # Librarian reference (if streaming)
+```
+
+**التوجيه:** بناءً على الحقل `kind`:
+`application/pdf` → قائمة انتظار `document-load` → وحدة فك ترميز PDF
+`text/plain` → قائمة انتظار `text-load` → وحدة تقسيم
+
+## المرحلة الثانية: وحدة فك ترميز PDF
+
+تحويل مستندات PDF إلى صفحات نصية.
+
+### العملية
+
+1. استرجاع المحتوى (مضمن في `data` أو عبر `document_id` من أمين المكتبة)
+2. استخراج الصفحات باستخدام PyPDF
+3. لكل صفحة:
+   حفظ كـ مستند فرعي في أمين المكتبة (`{doc_id}/p{page_num}`)
+   إرسال ثلاثيات المصدر (الصفحة مشتقة من المستند)
+   توجيه إلى وحدة التقسيم
+
+### المخطط: TextDocument
+
+```
+TextDocument
+├── metadata: Metadata
+│   ├── id: str              # Page URI (e.g., https://trustgraph.ai/doc/xxx/p1)
+│   ├── user: str
+│   ├── collection: str
+│   └── metadata: list[Triple]
+├── text: bytes              # Page text content (if inline)
+└── document_id: str         # Librarian reference (e.g., "doc123/p1")
+```
+
+## المرحلة الثالثة: تقسيم النص إلى أجزاء
+
+يقسم النص إلى أجزاء عند الحجم المحدد.
+
+### المعلمات (قابلة للتكوين من خلال التدفق)
+
+`chunk_size`: الحجم المستهدف للجزء الواحد بالأحرف (الافتراضي: 2000)
+`chunk_overlap`: التداخل بين الأجزاء (الافتراضي: 100)
+
+### العملية
+
+1. استرجاع محتوى النص (مباشرة أو عبر أمين المكتبة)
+2. التقسيم باستخدام مقسم الأحرف التكراري
+3. لكل جزء:
+   حفظ كوثيقة فرعية في أمين المكتبة (`{parent_id}/c{index}`)
+   إرسال بيانات المصدر (الجزء مشتق من صفحة/مستند)
+   توجيه إلى معالجات الاستخراج
+
+### المخطط: جزء
+
+```
+Chunk
+├── metadata: Metadata
+│   ├── id: str              # Chunk URI
+│   ├── user: str
+│   ├── collection: str
+│   └── metadata: list[Triple]
+├── chunk: bytes             # Chunk text content
+└── document_id: str         # Librarian chunk ID (e.g., "doc123/p1/c3")
+```
+
+### التسلسل الهرمي لمعرف المستند
+
+تقوم المستندات الفرعية بتشفير أصلها في المعرف:
+المصدر: `doc123`
+الصفحة: `doc123/p5`
+جزء من الصفحة: `doc123/p5/c2`
+جزء من النص: `doc123/c2`
+
+## المرحلة 4: استخراج المعرفة
+
+تتوفر أنماط استخراج متعددة، يتم اختيارها بواسطة إعدادات التدفق.
+
+### النمط أ: GraphRAG الأساسي
+
+معالجتان متوازيتان:
+
+**kg-extract-definitions**
+المدخلات: جزء
+المخرجات: ثلاثيات (تعريفات الكيانات)، سياقات الكيانات
+يستخرج: تسميات الكيانات، التعريفات
+
+**kg-extract-relationships**
+المدخلات: جزء
+المخرجات: ثلاثيات (علاقات)، سياقات الكيانات
+يستخرج: علاقات الفاعل-الفعل-المفعول
+
+### النمط ب: مدفوع بالدلالات (kg-extract-ontology)
+
+المدخلات: جزء
+المخرجات: ثلاثيات، سياقات الكيانات
+يستخدم دلالات مُكوّنة لتوجيه الاستخراج
+
+### النمط ج: قائم على الوكيل (kg-extract-agent)
+
+المدخلات: جزء
+المخرجات: ثلاثيات، سياقات الكيانات
+يستخدم إطار عمل الوكيل للاستخراج
+
+### النمط د: استخراج الصفوف (kg-extract-rows)
+
+المدخلات: جزء
+المخرجات: صفوف (بيانات منظمة، وليست ثلاثيات)
+يستخدم تعريف المخطط لاستخراج سجلات منظمة
+
+### المخطط: ثلاثيات
+
+```
+Triples
+├── metadata: Metadata
+│   ├── id: str
+│   ├── user: str
+│   ├── collection: str
+│   └── metadata: list[Triple]  # (set to [] by extractors)
+└── triples: list[Triple]
+    └── Triple
+        ├── s: Term              # Subject
+        ├── p: Term              # Predicate
+        ├── o: Term              # Object
+        └── g: str | None        # Named graph
+```
+
+### المخطط: سياقات الكيانات
+
+```
+EntityContexts
+├── metadata: Metadata
+└── entities: list[EntityContext]
+    └── EntityContext
+        ├── entity: Term         # Entity identifier (IRI)
+        ├── context: str         # Textual description for embedding
+        └── chunk_id: str        # Source chunk ID (provenance)
+```
+
+### المخطط: الصفوف
+
+```
+Rows
+├── metadata: Metadata
+├── row_schema: RowSchema
+│   ├── name: str
+│   ├── description: str
+│   └── fields: list[Field]
+└── rows: list[dict[str, str]]   # Extracted records
+```
+
+## المرحلة الخامسة: توليد التضمينات
+
+### تضمينات الرسم البياني
+
+تحويل سياقات الكيانات إلى تضمينات متجهة.
+
+**العملية:**
+1. استقبال سياقات الكيانات.
+2. استدعاء خدمة التضمينات مع نص السياق.
+3. إخراج تضمينات الرسم البياني (ت mapping بين الكيان والمتجه).
+
+**النموذج: تضمينات الرسم البياني**
+
+```
+GraphEmbeddings
+├── metadata: Metadata
+└── entities: list[EntityEmbeddings]
+    └── EntityEmbeddings
+        ├── entity: Term         # Entity identifier
+        ├── vector: list[float]  # Embedding vector
+        └── chunk_id: str        # Source chunk (provenance)
+```
+
+### تضمينات المستندات
+
+يحول النص المقسم مباشرةً إلى تضمينات متجهة.
+
+**العملية:**
+1. استقبال الجزء
+2. استدعاء خدمة التضمينات باستخدام نص الجزء
+3. إخراج تضمينات المستندات
+
+**التركيب: تضمينات المستندات**
+
+```
+DocumentEmbeddings
+├── metadata: Metadata
+└── chunks: list[ChunkEmbeddings]
+    └── ChunkEmbeddings
+        ├── chunk_id: str        # Chunk identifier
+        └── vector: list[float]  # Embedding vector
+```
+
+### تضمينات الصفوف
+
+تحويل حقول فهرس الصف إلى تضمينات متجهة.
+
+**العملية:**
+1. استقبال الصفوف
+2. تضمين حقول الفهرس المحددة
+3. الإخراج إلى مخزن المتجهات الصفية
+
+## المرحلة 6: التخزين
+
+### مخزن ثلاثي
+
+يستقبل: ثلاثيات
+التخزين: Cassandra (جداول تركز على الكيانات)
+الرسوم البيانية المسماة تفصل المعرفة الأساسية عن المصادر:
+  `""` (افتراضي): حقائق المعرفة الأساسية
+  `urn:graph:source`: تتبع المصادر
+  `urn:graph:retrieval`: إمكانية الشرح في وقت الاستعلام
+
+### مخزن المتجهات (تضمينات الرسم البياني)
+
+يستقبل: تضمينات الرسم البياني
+التخزين: Qdrant، Milvus، أو Pinecone
+مفهرس بواسطة: IRI الكيان
+البيانات الوصفية: chunk_id لتتبع المصادر
+
+### مخزن المتجهات (تضمينات المستندات)
+
+يستقبل: تضمينات المستندات
+التخزين: Qdrant، Milvus، أو Pinecone
+مفهرس بواسطة: chunk_id
+
+### مخزن الصفوف
+
+يستقبل: صفوف
+التخزين: Cassandra
+هيكل الجدول الموجه بالمخطط
+
+### مخزن المتجهات الصفية
+
+يستقبل: تضمينات الصفوف
+التخزين: قاعدة بيانات المتجهات
+مفهرس بواسطة: حقول فهرس الصف
+
+## تحليل حقول البيانات الوصفية
+
+### الحقول المستخدمة بنشاط
+
+| الحقل | الاستخدام |
+|-------|-------|
+| `metadata.id` | معرف المستند/الكتلة، التسجيل، تتبع المصادر |
+| `metadata.user` | تعدد المستأجرين، توجيه التخزين |
+| `metadata.collection` | اختيار المجموعة المستهدفة |
+| `document_id` | مرجع أمين المكتبة، ربط تتبع المصادر |
+| `chunk_id` | تتبع المصادر عبر مسار العمل |
+
+<<<<<<< HEAD
+### الحقول التي قد تكون زائدة عن الحاجة
+
+| الحقل | الحالة |
+|-------|--------|
+| `metadata.metadata` | يتم تعيينه على `[]` بواسطة جميع المستخرجات؛ يتم التعامل مع بيانات وصفية على مستوى المستند الآن بواسطة أمين المكتبة في وقت الإرسال |
+=======
+### الحقول التي تمت إزالتها
+
+| الحقل | الحالة |
+|-------|--------|
+| `metadata.metadata` | تمت إزالته من الفئة `Metadata`. يتم الآن إرسال ثلاثيات البيانات الوصفية على مستوى المستند مباشرةً بواسطة أمين المكتبة إلى مخزن الثلاثيات في وقت الإرسال، ولا يتم نقلها عبر مسار العمل. |
+>>>>>>> e3bcbf73 (قائمة البيانات الوصفية (الثلاثيات) في فئة مسار العمل Metadata)
+
+### نمط حقول البايت
+
+جميع حقول المحتوى (`data`، `text`، `chunk`) هي `bytes` ولكن يتم فك ترميزها على الفور إلى سلاسل UTF-8 بواسطة جميع المعالجات. لا يستخدم أي معالج بايت خام.
+
+## تكوين التدفق
+
+يتم تعريف التدفقات خارجيًا وتقديمها إلى أمين المكتبة عبر خدمة التكوين. يحدد كل تدفق:
+
+قوائم انتظار الإدخال (`text-load`، `document-load`)
+سلسلة المعالجات
+المعلمات (حجم الكتلة، طريقة الاستخراج، إلخ.)
+
+أمثلة على أنماط التدفق:
+`pdf-graphrag`: PDF → Decoder → Chunker → Definitions + Relationships → Embeddings
+`text-graphrag`: Text → Chunker → Definitions + Relationships → Embeddings
+`pdf-ontology`: PDF → Decoder → Chunker → Ontology Extraction → Embeddings
+`text-rows`: Text → Chunker → Row Extraction → Row Store

docs/tech-specs/ar/extraction-provenance-subgraph.ar.md

@@ -0,0 +1,265 @@
+---
+layout: default
+title: "أصل الاستخراج: نموذج الرسم البياني الفرعي"
+parent: "Arabic (Beta)"
+---
+
+<<<<<<< HEAD
+# أصل الاستخراج: نموذج الرسم البياني الفرعي
+
+> **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.
+
+## المشكلة
+
+حاليًا، يقوم تتبع أصل الاستخراج بإنشاء تجسيد كامل لكل ثلاثية مستخرجة:
+معرف فريد `stmt_uri`، و `activity_uri`، وبيانات وصفية PROV-O مرتبطة
+لكل حقيقة معرفية. يؤدي معالجة جزء واحد ينتج عنه 20 علاقة إلى إنتاج حوالي 220 ثلاثية لتتبع الأصل بالإضافة إلى
+حوالي 20 ثلاثية معرفية - وهو عبء إضافي يقدر بحوالي 10:1.
+
+=======
+# المصدر: نموذج الرسم البياني الفرعي.
+
+## المشكلة
+
+في الوقت الحالي، تقوم عملية تتبع مصدر البيانات في وقت الاستخراج بإنشاء تجسيد كامل لكل
+ثلاثية مستخرجة: معرف فريد `stmt_uri`، و `activity_uri`، والبيانات الوصفية المرتبطة بـ PROV-O لكل حقيقة معرفية. معالجة جزء واحد
+...
+والتي تؤدي إلى 20 علاقة، تنتج حوالي 220 ثلاثية بيانات أصلية بالإضافة إلى
+حوالي 20 ثلاثية معرفة - وهو عبء إضافي يقدر بحوالي 10:1.
+>>>>>>> 82edf2d (New md files from RunPod)
+
+هذا مكلف للغاية (من حيث التخزين والفهرسة والنقل) وغير دقيق من الناحية الدلالية.
+تتم معالجة كل جزء بواسطة استدعاء واحد لنموذج اللغة الكبير (LLM) ينتج
+جميع الثلاثيات الخاصة به في معاملة واحدة.
+يخفي النموذج الحالي لكل ثلاثية ذلك من خلال خلق وهم بوجود 20 عملية استخراج
+مستقلة.
+
+بالإضافة إلى ذلك، لا توجد أي معلومات عن مصدرين من أصل أربعة معالجات للاستخراج (kg-extract-ontology،
+kg-extract-agent)، مما يترك فجوات في مسار التدقيق.
+
+
+## الحل
+
+<<<<<<< HEAD
+استبدال عملية التجسيد لكل ثلاثية بنموذج **رسم بياني فرعي**: سجل واحد للبيانات الوصفية لكل جزء مستخرج، ويتم مشاركته عبر جميع الثلاثيات الناتجة عن هذا الجزء.
+=======
+استبدل عملية التجسيد لكل ثلاثية بنموذج **رسم بياني فرعي**: سجل واحد للبيانات الوصفية لكل جزء مستخرج، ويتم مشاركته عبر جميع الثلاثيات الناتجة عن هذا الجزء.
+>>>>>>> 82edf2d (New md files from RunPod)
+
+
+
+### تغيير في المصطلحات
+
+| القديم | الجديد |
+|-----|-----|
+| `stmt_uri` (`https://trustgraph.ai/stmt/{uuid}`) | `subgraph_uri` (`https://trustgraph.ai/subgraph/{uuid}`) |
+| `statement_uri()` | `subgraph_uri()` |
+<<<<<<< HEAD
+| `tg:reifies` (1:1، تطابق) | `tg:contains` (1:كثير، احتواء) |
+=======
+| `tg:reifies` (1:1، تطابق) | `tg:contains` (1:متعدد، احتواء) |
+>>>>>>> 82edf2d (New md files from RunPod)
+
+### الهيكل المستهدف
+
+يجب أن تضاف جميع الثلاثيات المتعلقة بأصل البيانات إلى الرسم البياني المسمى `urn:graph:source`.
+
+```
+# Subgraph contains each extracted triple (RDF-star quoted triples)
+<subgraph> tg:contains <<s1 p1 o1>> .
+<subgraph> tg:contains <<s2 p2 o2>> .
+<subgraph> tg:contains <<s3 p3 o3>> .
+
+# Derivation from source chunk
+<subgraph> prov:wasDerivedFrom <chunk_uri> .
+<subgraph> prov:wasGeneratedBy <activity> .
+
+# Activity: one per chunk extraction
+<activity> rdf:type          prov:Activity .
+<activity> rdfs:label        "{component_name} extraction" .
+<activity> prov:used         <chunk_uri> .
+<activity> prov:wasAssociatedWith <agent> .
+<activity> prov:startedAtTime "2026-03-13T10:00:00Z" .
+<activity> tg:componentVersion "0.25.0" .
+<activity> tg:llmModel       "gpt-4" .          # if available
+<activity> tg:ontology        <ontology_uri> .   # if available
+
+# Agent: stable per component
+<agent> rdf:type   prov:Agent .
+<agent> rdfs:label "{component_name}" .
+```
+
+### مقارنة الحجم
+
+لكل جزء ينتج عنه N من الثلاثيات المستخرجة:
+
+| | القديم (لكل ثلاثية) | الجديد (الرسم البياني الفرعي) |
+|---|---|---|
+| `tg:contains` / `tg:reifies` | N | N |
+| ثلاثيات النشاط | ~9 × N | ~9 |
+| ثلاثيات الوكيل | 2 × N | 2 |
+| بيانات التعريف/الرسم البياني الفرعي | 2 × N | 2 |
+| **إجمالي ثلاثيات التتبع** | **~13N** | **N + 13** |
+| **مثال (N=20)** | **~260** | **33** |
+
+## النطاق
+
+### المعالجات التي سيتم تحديثها (التتبع الحالي، لكل ثلاثية)
+
+**kg-extract-definitions**
+(`trustgraph-flow/trustgraph/extract/kg/definitions/extract.py`)
+
+حاليًا، تستدعي `statement_uri()` + `triple_provenance_triples()` داخل
+حلقة التعريف لكل عنصر.
+
+التغييرات:
+نقل إنشاء `subgraph_uri()` و `activity_uri()` قبل الحلقة
+جمع ثلاثيات `tg:contains` داخل الحلقة
+إخراج كتلة النشاط/الوكيل/الاشتقاق المشتركة مرة واحدة بعد الحلقة
+
+**kg-extract-relationships**
+(`trustgraph-flow/trustgraph/extract/kg/relationships/extract.py`)
+
+نفس النمط مثل التعريفات. نفس التغييرات.
+
+<<<<<<< HEAD
+### المعالجات التي يجب إضافتها للتتبع (مفقودة حاليًا)
+=======
+### المعالجات التي سيتم إضافة التتبع إليها (مفقودة حاليًا)
+>>>>>>> 82edf2d (New md files from RunPod)
+
+**kg-extract-ontology**
+(`trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`)
+
+<<<<<<< HEAD
+حاليًا، يقوم بإخراج ثلاثيات بدون مصدر. أضف مصدر الرسم البياني الفرعي.
+=======
+حاليًا، يقوم بإخراج ثلاثيات بدون مصدر. أضف مصدر الرسوم البيانية الفرعية.
+>>>>>>> 82edf2d (New md files from RunPod)
+باستخدام نفس النمط: رسم بياني فرعي واحد لكل جزء، `tg:contains` لكل
+ثلاثية مستخرجة.
+
+**kg-extract-agent**
+(`trustgraph-flow/trustgraph/extract/kg/agent/extract.py`)
+
+<<<<<<< HEAD
+حاليًا، يقوم بإخراج ثلاثيات بدون مصدر. أضف مصدر الرسم البياني الفرعي
+=======
+حاليًا، يقوم بإخراج ثلاثيات بدون مصدر. أضف مصدر الرسوم البيانية الفرعية
+>>>>>>> 82edf2d (New md files from RunPod)
+باستخدام نفس النمط.
+
+### تغييرات في مكتبة المصادر المشتركة
+
+**`trustgraph-base/trustgraph/provenance/triples.py`**
+
+استبدل `triple_provenance_triples()` بـ `subgraph_provenance_triples()`
+<<<<<<< HEAD
+تقبل الدالة الجديدة قائمة بالثلاثيات المستخرجة بدلاً من ثلاثية واحدة.
+تقوم بإنشاء `tg:contains` واحد لكل ثلاثية، كتلة نشاط/وكيل مشتركة.
+قم بإزالة `triple_provenance_triples()` القديم.
+=======
+تقبل الدالة الجديدة قائمة بالثلاثيات المستخرجة بدلاً من ثلاثية واحدة
+تقوم بإنشاء `tg:contains` واحد لكل ثلاثية، كتلة نشاط/وكيل مشتركة
+قم بإزالة `triple_provenance_triples()` القديم
+>>>>>>> 82edf2d (New md files from RunPod)
+
+**`trustgraph-base/trustgraph/provenance/uris.py`**
+
+استبدل `statement_uri()` بـ `subgraph_uri()`
+
+**`trustgraph-base/trustgraph/provenance/namespaces.py`**
+
+استبدل `TG_REIFIES` بـ `TG_CONTAINS`
+
+<<<<<<< HEAD
+### ليس ضمن النطاق
+=======
+### خارج النطاق
+>>>>>>> 82edf2d (New md files from RunPod)
+
+**kg-extract-topics**: معالج بنمط قديم، ولا يتم استخدامه حاليًا في
+  العمليات القياسية.
+**kg-extract-rows**: ينتج صفوفًا وليست ثلاثيات، ومن مصدر مختلف.
+  نموذج.
+**تتبع المصدر في وقت الاستعلام** (`urn:graph:retrieval`): مسألة منفصلة،
+  تستخدم بالفعل نمطًا مختلفًا (سؤال/استكشاف/تركيز/توليف).
+**أصل المستند/الصفحة/الجزء** (فك تشفير PDF، تقسيم النص): تستخدم بالفعل.
+  `derived_entity_triples()` وهو خاص بكل كيان، وليس لكل ثلاثية - لا.
+  مشكلة التكرار.
+
+## ملاحظات حول التنفيذ
+
+### إعادة هيكلة حلقة المعالج
+
+قبل (لكل ثلاثية، في العلاقات):
+```python
+for rel in rels:
+    # ... build relationship_triple ...
+    stmt_uri = statement_uri()
+    prov_triples = triple_provenance_triples(
+        stmt_uri=stmt_uri,
+        extracted_triple=relationship_triple,
+        ...
+    )
+    triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
+```
+
+<<<<<<< HEAD
+بعد (رسم بياني فرعي):
+=======
+بعد (الرسم البياني الفرعي):
+>>>>>>> 82edf2d (New md files from RunPod)
+```python
+sg_uri = subgraph_uri()
+
+for rel in rels:
+    # ... build relationship_triple ...
+    extracted_triples.append(relationship_triple)
+
+prov_triples = subgraph_provenance_triples(
+    subgraph_uri=sg_uri,
+    extracted_triples=extracted_triples,
+    chunk_uri=chunk_uri,
+    component_name=default_ident,
+    component_version=COMPONENT_VERSION,
+    llm_model=llm_model,
+    ontology_uri=ontology_uri,
+)
+triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
+```
+
+### التوقيع المساعد الجديد
+
+```python
+def subgraph_provenance_triples(
+    subgraph_uri: str,
+    extracted_triples: List[Triple],
+    chunk_uri: str,
+    component_name: str,
+    component_version: str,
+    llm_model: Optional[str] = None,
+    ontology_uri: Optional[str] = None,
+    timestamp: Optional[str] = None,
+) -> List[Triple]:
+    """
+    Build provenance triples for a subgraph of extracted knowledge.
+
+    Creates:
+    - tg:contains link for each extracted triple (RDF-star quoted)
+    - One prov:wasDerivedFrom link to source chunk
+    - One activity with agent metadata
+    """
+```
+
+### تغيير جذري
+
+<<<<<<< HEAD
+هذا تغيير جذري في نموذج التتبع. لم يتم
+تم إصدارها، لذا لا توجد حاجة إلى ترحيل. الكود القديم `tg:reifies` /
+يمكن إزالة كود `statement_uri` تمامًا.
+=======
+هذا تغيير جذري في نموذج التتبع. لم يتم إصدار التتبع بعد، لذا لا توجد حاجة إلى ترحيل. يمكن إزالة الكود القديم ⟦CODE_0⟧ / ⟦CODE_0⟧ مباشرةً.
+been released, so no migration is needed. The old `tg:reifies` /
+`statement_uri` code can be removed outright.
+>>>>>>> 82edf2d (New md files from RunPod)