How trustgraph-ai/trustgraph works
1. Repository shape
This is a Python monorepo split into a shared core library plus many service packages. The main runtime code lives under trustgraph-flow, while trustgraph-base provides reusable client, messaging, schema, and service primitives. Other top-level packages are narrow adapters or CLIs (trustgraph-cli, trustgraph-mcp, trustgraph-ocr, trustgraph-unstructured, trustgraph-bedrock, trustgraph-vertexai, trustgraph-embeddings-hf).
2. Primary architectural boundary: gateway vs workers
The central runtime boundary is the API gateway in trustgraph-flow/trustgraph/gateway, which exposes HTTP/OpenAPI and websocket/streaming endpoints. The gateway does not do the heavy work itself; it dispatches requests into backend services through the messaging layer. This makes the system event-driven and lets the same operations be invoked via REST, websocket, or CLI clients.
3. Control plane vs data plane
The repo models a clear control plane/data plane split:
- Control plane: IAM, config, workspace/collection management, flow lifecycle, prompt management, tool registration, and bootstrap.
- Data plane: ingestion, decoding, chunking, embeddings, extraction, storage, retrieval, RAG, and agent execution.
The workspace → collection → flow hierarchy in the README is reflected across the codebase and is the main tenancy/isolation model.
4. Messaging and service orchestration
trustgraph-base/trustgraph/base/pubsub.py plus backends for Kafka, Pulsar, and RabbitMQ define the messaging abstraction. The service packages in trustgraph-flow are arranged around request/response or producer/consumer patterns, with processor_group, consumer, publisher, and subscriber helpers. This is the main internal transport between gateway, long-running workers, and specialized services.
5. Ingestion and knowledge pipeline
Document and structured-data intake flows start with decoding/parsing, then chunking, then optional extraction, then persistence. Key stages are:
- decoding services for PDF/OCR/unstructured text
- chunking services (token, recursive)
- knowledge extraction services (extract/kg/...)
- storage services for documents, rows, triples, and embeddings
The pipeline is designed to turn raw content into queryable knowledge artifacts, not just text blobs.
6. Knowledge representation layer
The repo distinguishes several knowledge forms:
- Triples / graph facts for symbolic context
- Rows for tabular/structured records
- Document embeddings and graph embeddings for semantic retrieval
- Ontology-driven extraction for schema-aware graph construction
The trustgraph-base/trustgraph/schema/knowledge and trustgraph-flow/trustgraph/extract/kg/ontology directories show that ontology and provenance are first-class parts of the domain model.
7. Storage backends
Storage is abstracted behind service-specific implementations:
- Cassandra for core multi-model and tabular storage
- Qdrant / Milvus / Pinecone for vector-backed embedding storage and retrieval
- Neo4j / Memgraph / FalkorDB / Cassandra for triple/graph storage and queries
- Garage / S3-compatible object storage for blobs and large artifacts
- FTS5 for keyword index support
The architecture is backend-pluggable; query and storage services are organized by capability and by backend.
8. Retrieval and RAG
Retrieval services are separated by modality:
- document_rag for document-centric retrieval
- graph_rag for graph-grounded retrieval with explainability
- nlp_query and structured_query for natural-language-to-query workflows
- sparql_query, rows_query, triples_query, and embedding query services for direct access paths
The system emphasizes explainable retrieval, using graph traversal and provenance rather than only nearest-neighbor vector matches.
9. Agent orchestration and tool use
trustgraph-flow/trustgraph/agent contains agent execution patterns: ReAct, Plan, Supervisor, and an orchestrator/aggregator/meta-router. There is also an MCP tool service, which implies external tool invocation through a standard protocol boundary. This subsystem consumes context from retrieval services and emits streaming reasoning/explainability events back through the gateway.
10. Model/provider adapters
LLM and embedding execution are not hardwired to one provider. There are dedicated adapters for:
- text completion: OpenAI, Azure OpenAI, Anthropic/Claude, Cohere, Mistral, Ollama, vLLM, TGI, LM Studio, Llamafile
- embeddings: Hugging Face / fastembed / Ollama variants
- OCR: Mistral OCR and related decoders
These adapters sit behind common client/service abstractions in trustgraph-base, so the higher-level flows can switch providers without changing the orchestration layer.
11. Public contracts and generated specs
specs/api and specs/websocket are the authoritative interface contracts. They define REST/OpenAPI shapes, websocket message envelopes, and request/response schemas for the major services. The repo also includes versioned docs, tech specs, and tests that appear to lock down behavior and serialization formats across these boundaries.
12. CLI, bootstrap, and operations
trustgraph-cli provides operational entry points for provisioning IAM, creating workspaces/collections, loading knowledge, managing flows, invoking services, and inspecting state. trustgraph-flow/bootstrap contains startup initializers such as workspace setup and default flow startup. This indicates the system is designed to be deployed as a set of cooperating containers, with operational workflows driven from CLI and automation rather than a monolithic app.
13. Observability, explainability, and audit
Explainability is not an add-on; it is wired into the architecture via provenance packages, audit publishing, metrics, and streaming explain-trace endpoints. The service and gateway layers include explicit support for audit events, metrics, and streaming response handling so that retrieval and agent decisions can be inspected after the fact.
14. Testing and release posture
The repo has deep unit, contract, integration, and end-to-end style tests, plus manual test fixtures and API test cases. That suggests the architecture is contract-heavy: components are expected to communicate through stable schemas, and cross-backend compatibility is an explicit concern.
15. How to draw the diagram
A good architecture diagram should show:
- clients/CLI/UI entering through the gateway
- gateway dispatching to pub/sub-backed service workers
- ingestion/extraction pipeline feeding storage layers
- retrieval services reading from graph/vector/tabular/object stores
- agent orchestration calling retrieval and model adapters
- IAM/config/workspace services spanning everything as shared control-plane services
- explicit spec boundaries for REST and websocket contracts
Main entry points: pubsub.py Pub/Sub · gateway API gateway · decoding Ingest · storage Storage
Components 22
Contracts
Public API and websocket specifications.
Base Library
Shared clients, messaging, schema, and service primitives.
- Pub/Sub · Broker-agnostic producer/consumer layer with Kafka, Pulsar, and RabbitMQ backends.
trustgraph-base/trustgraph/base/pubsub.py - Schemas · Shared request, response, service, and knowledge schemas used across packages.
trustgraph-base/trustgraph/schema - Clients · Reusable Python clients for gateway-facing service APIs.
trustgraph-base/trustgraph/clients
Flow Runtime
Gateway, workers, pipelines, retrieval, and storage services.
- API gateway · Public entrypoint that serves REST and websocket endpoints and routes work to workers.
trustgraph-flow/trustgraph/gateway - IAM · Authentication, authorization, and identity workspace bootstrap.
trustgraph-flow/trustgraph/iam - Config · System configuration management and runtime config delivery.
trustgraph-flow/trustgraph/config/service - Flow mgmt · Flow class definitions, startup, and runtime lifecycle management.
trustgraph-flow/trustgraph/flow/service - Librarian · Object storage and document lifecycle management for large artifacts.
trustgraph-flow/trustgraph/librarian - Ingest · Document and structured-data intake: decode, parse, and chunk content.
trustgraph-flow/trustgraph/decoding - KG extract · Ontology-driven and heuristic extraction into triples, entities, and contexts.
trustgraph-flow/trustgraph/extract/kg - Embeddings · Document, graph, and row embedding generation workers.
trustgraph-flow/trustgraph/embeddings - Storage · Capability-specific writers for knowledge, rows, triples, embeddings, and keyword index.
trustgraph-flow/trustgraph/storage - Query · Modality-specific query services for vectors, rows, triples, SPARQL, and structured NLP.
trustgraph-flow/trustgraph/query - RAG · Document and graph grounded retrieval with explainability and reranking.
trustgraph-flow/trustgraph/retrieval - Agent · ReAct, plan, supervisor, and meta-router execution over retrieval and tools.
trustgraph-flow/trustgraph/agent
Adapters
Standalone runtime packages for providers and external protocols.
- LLM adapters · Provider-specific text completion runtimes behind a common service abstraction.
trustgraph-flow/trustgraph/model/text_completion - Embed adapters · Standalone embedding provider packages such as Hugging Face.
trustgraph-embeddings-hf/trustgraph/embeddings/hf/hf.py - Decode adapters · Standalone OCR and universal decoding packages used by the ingest pipeline.
trustgraph-ocr/trustgraph/decoding/ocr/pdf_decoder.py
Connections 29
- REST spec → API gateway: HTTP contract · REST shapes define the gateway's public request/response surface.
- WS spec → API gateway: stream contract · Websocket envelopes and streaming events define async gateway behavior.
- Pub/Sub → API gateway: dispatch transport · Gateway routes work to backend services through pub/sub messaging.
- Schemas → API gateway: shared models · Gateway and services share canonical schemas and service contracts.
- Schemas → IAM: identity models · IAM uses shared service schemas and records.
- Schemas → Flow mgmt: flow models · Flow lifecycle and blueprint definitions use shared schemas.
- Pub/Sub → Ingest: worker transport · Ingestion workers are orchestrated as pub/sub services.
- Pub/Sub → KG extract: worker transport · Extraction runs as backend services on the messaging layer.
- Pub/Sub → Embeddings: worker transport · Embedding generation is executed by backend workers.
- Pub/Sub → Storage: worker transport · Writers consume messages and persist artifacts.
- Pub/Sub → Query: worker transport · Query services are exposed as messaging-backed workers.
- Pub/Sub → RAG: worker transport · Retrieval services are invoked through the messaging layer.
- Pub/Sub → Agent: worker transport · Agent execution is coordinated through request/response messaging.
- Librarian → Ingest: documents in · Large artifacts are fetched from the librarian before decoding and chunking.
- Ingest → KG extract: content flow · Decoded text and structure feed knowledge extraction.
- KG extract → Storage: knowledge out · Triples, rows, and provenance are written to storage backends.
- Embeddings → Storage: vector out · Embedding workers persist vectors to vector stores or indexes.
- Storage → Query: read path · Query services read from the backend-specific storage layer.
- Query → RAG: retrieval context · RAG composes answers from query results across modalities.
- RAG → Agent: grounding · Agents consume retrieved context and explainable evidence.
- LLM adapters → Agent: reasoning model · Agent patterns call shared LLM completion providers.
- LLM adapters → RAG: rerank/generate · Retrieval pipelines use model-backed generation and ranking.
- Embed adapters → Embeddings: embed provider · Embedding workers delegate to provider adapters.
- Decode adapters → Ingest: decode provider · Ingestion uses OCR and universal decoding adapters.
- CLI → API gateway: operates via API · CLI commands target the same public gateway surface as other clients.
- CLI → Bootstrap: admin flow · CLI drives bootstrap and workspace initialization workflows.
- Bootstrap → IAM: provisions · Bootstrap initializes identities and workspaces.
- Bootstrap → Flow mgmt: starts defaults · Bootstrap can seed default flows and topology.
- Clients → API gateway: sdk · Reusable clients wrap gateway-facing APIs for callers.