mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-05-04 04:42:36 +02:00
The context development platform. Store, enrich, and retrieve structured knowledge with graph-native infrastructure, semantic retrieval, and portable context cores.
https://trustgraph.ai
agentagent-memoryaiai-infraai-toolsbackendchatbotcontextcontext-backendcontext-engineeringcontext-graphdata-sciencedeveloper-toolsgraphknowledge-graphontologyontology-engineeringopen-sourcerdfsparql
67b2fc448f
Replaces the legacy GATEWAY_SECRET shared-token gate with an IAM-backed
identity and authorisation model. The gateway no longer has an
"allow-all" or "no auth" mode; every request is authenticated via the
IAM service, authorised against a capability model that encodes both
the operation and the workspace it targets, and rejected with a
deliberately-uninformative 401 / 403 on any failure.
IAM service (trustgraph-flow/trustgraph/iam, trustgraph-base/schema/iam)
-----------------------------------------------------------------------
* New backend service (iam-svc) owning users, workspaces, API keys,
passwords and JWT signing keys in Cassandra. Reached over the
standard pub/sub request/response pattern; gateway is the only
caller.
* Operations: bootstrap, resolve-api-key, login, get-signing-key-public,
rotate-signing-key, create/list/get/update/disable/delete/enable-user,
change-password, reset-password, create/list/get/update/disable-
workspace, create/list/revoke-api-key.
* Ed25519 JWT signing (alg=EdDSA). Key rotation writes a new kid and
retires the previous one; validation is grace-period friendly.
* Passwords: PBKDF2-HMAC-SHA-256, 600k iterations, per-user salt.
* API keys: 128-bit random, SHA-256 hashed. Plaintext returned once.
* Bootstrap is explicit: --bootstrap-mode {token,bootstrap} is a
required startup argument with no permissive default. Masked
"auth failure" errors hide whether a refused bootstrap request was
due to mode, state, or authorisation.
Gateway authentication (trustgraph-flow/trustgraph/gateway/auth.py)
-------------------------------------------------------------------
* IamAuth replaces the legacy Authenticator. Distinguishes JWTs
(three-segment dotted) from API keys by shape; verifies JWTs
locally using the cached IAM public key; resolves API keys via
IAM with a short-TTL hash-keyed cache. Every failure path
surfaces the same 401 body ("auth failure") so callers cannot
enumerate credential state.
* Public key is fetched at gateway startup with a bounded retry loop;
traffic does not begin flowing until auth has started.
Capability model (trustgraph-flow/trustgraph/gateway/capabilities.py)
---------------------------------------------------------------------
* Roles have two dimensions: a capability set and a workspace scope.
OSS ships reader / writer / admin; the first two are workspace-
assigned, admin is cross-workspace ("*"). No "cross-workspace"
pseudo-capability — workspace permission is a property of the role.
* check(identity, capability, target_workspace=None) is the single
authorisation test: some role must grant the capability *and* be
active in the target workspace.
* enforce_workspace validates a request-body workspace against the
caller's role scopes and injects the resolved value. Cross-
workspace admin is permitted by role scope, not by a bypass.
* Gateway endpoints declare a required capability explicitly — no
permissive default. Construction fails fast if omitted. Enterprise
editions can replace the role table without changing the wire
protocol.
WebSocket first-frame auth (dispatch/mux.py, endpoint/socket.py)
----------------------------------------------------------------
* /api/v1/socket handshake unconditionally accepts; authentication
runs on the first WebSocket frame ({"type":"auth","token":"..."})
with {"type":"auth-ok","workspace":"..."} / {"type":"auth-failed"}.
The socket stays open on failure so the client can re-authenticate
— browsers treat a handshake-time 401 as terminal, breaking
reconnection.
* Mux.receive rejects every non-auth frame before auth succeeds,
enforces the caller's workspace (envelope + inner payload) using
the role-scope resolver, and supports mid-session re-auth.
* Flow import/export streaming endpoints keep the legacy ?token=
handshake (URL-scoped short-lived transfers; no re-auth need).
Auth surface
------------
* POST /api/v1/auth/login — public, returns a JWT.
* POST /api/v1/auth/bootstrap — public; forwards to IAM's bootstrap
op which itself enforces mode + tables-empty.
* POST /api/v1/auth/change-password — any authenticated user.
* POST /api/v1/iam — admin-only generic forwarder for the rest of
the IAM API (per-op REST endpoints to follow in a later change).
Removed / breaking
------------------
* GATEWAY_SECRET / --api-token / default_api_token and the legacy
Authenticator.permitted contract. The gateway cannot run without
IAM.
* ?token= on /api/v1/socket.
* DispatcherManager and Mux both raise on auth=None — no silent
downgrade path.
CLI tools (trustgraph-cli)
--------------------------
tg-bootstrap-iam, tg-login, tg-create-user, tg-list-users,
tg-disable-user, tg-enable-user, tg-delete-user, tg-change-password,
tg-reset-password, tg-create-api-key, tg-list-api-keys,
tg-revoke-api-key, tg-create-workspace, tg-list-workspaces. Passwords
read via getpass; tokens / one-time secrets written to stdout with
operator context on stderr so shell composition works cleanly.
AsyncSocketClient / SocketClient updated to the first-frame auth
protocol.
Specifications
--------------
* docs/tech-specs/iam.md updated with the error policy, workspace
resolver extension point, and OSS role-scope model.
* docs/tech-specs/iam-protocol.md (new) — transport, dataclasses,
operation table, error taxonomy, bootstrap modes.
* docs/tech-specs/capabilities.md (new) — capability vocabulary, OSS
role bundles, agent-as-composition note, enforcement-boundary
policy, enterprise extensibility.
Tests
-----
* test_auth.py (rewritten) — IamAuth + JWT round-trip with real
Ed25519 keypairs + API-key cache behaviour.
* test_capabilities.py (new) — role table sanity, check across
role x workspace combinations, enforce_workspace paths,
unknown-cap / unknown-role fail-closed.
* Every endpoint test construction now names its capability
explicitly (no permissive defaults relied upon). New tests pin
the fail-closed invariants: DispatcherManager / Mux refuse
auth=None; i18n path-traversal defense is exercised.
* test_socket_graceful_shutdown rewritten against IamAuth.
|
||
|---|---|---|
| .github/workflows | ||
| containers | ||
| dev-tools | ||
| docs | ||
| specs | ||
| test-api | ||
| tests | ||
| tests.manual | ||
| trustgraph | ||
| trustgraph-base | ||
| trustgraph-bedrock | ||
| trustgraph-cli | ||
| trustgraph-embeddings-hf | ||
| trustgraph-flow | ||
| trustgraph-mcp | ||
| trustgraph-ocr | ||
| trustgraph-unstructured | ||
| trustgraph-vertexai | ||
| .coveragerc | ||
| .gitignore | ||
| check_imports.py | ||
| context7.json | ||
| DEVELOPER_GUIDE.md | ||
| iam-testing.txt | ||
| install_packages.sh | ||
| LICENSE | ||
| Makefile | ||
| ontology-prompt.md | ||
| product-platform-diagram.svg | ||
| prompt.txt | ||
| README.md | ||
| requirements.txt | ||
| run_tests.sh | ||
| schema.ttl | ||
| SECURITY.md | ||
| TEST_CASES.md | ||
| TEST_SETUP.md | ||
| TEST_STRATEGY.md | ||
| TESTS.md | ||
| TG-fullname-logo.svg | ||
| TG-hero-diagram.svg | ||
Building applications that need to know things requires more than a database. TrustGraph is the context development platform: graph-native infrastructure for storing, enriching, and retrieving structured knowledge at any scale. Think like Supabase but built around context graphs: multi-model storage, semantic retrieval pipelines, portable context cores, and a full developer toolkit out of the box. Deploy locally or in the cloud. No unnecessary API keys. Just context, engineered.
The platform:
- Multi-model and multimodal database system
- Tabular/relational, key-value
- Document, graph, and vectors
- Images, video, and audio
- Automated data ingest and loading
- Quick ingest with semantic similarity retrieval
- Ontology structuring for precision retrieval
- Out-of-the-box RAG pipelines
- DocumentRAG
- GraphRAG
- OntologyRAG
- 3D GraphViz for exploring context
- Fully Agentic System
- Single Agent
- Multi Agent
- MCP integration
- Run anywhere
- Deploy locally with Docker
- Deploy in cloud with Kubernetes
- Support for all major LLMs
- API support for Anthropic, Cohere, Gemini, Mistral, OpenAI, and others
- Model inferencing with vLLM, Ollama, TGI, LM Studio, and Llamafiles
- Developer friendly
No API Keys Required
How many times have you cloned a repo and opened the .env.example to see the dozens of API keys for 3rd party dependencies needed to make the services work? There are only 3 things in TrustGraph that might need an API key:
- 3rd party LLM services like Anthropic, Cohere, Gemini, Mistral, OpenAI, etc.
- 3rd party OCR like Mistral OCR
- The API key you set for the TrustGraph API gateway
Everything else is included.
- Managed Multi-model storage in Cassandra
- Managed Vector embedding storage in Qdrant
- Managed File and Object storage in Garage (S3 compatible)
- Managed High-speed Pub/Sub messaging fabric with Pulsar
- Complete LLM inferencing stack for open LLMs with vLLM, TGI, Ollama, LM Studio, and Llamafiles
Quickstart
There's no need to clone this repo, unless you want to build from source. TrustGraph is a fully containerized app that deploys as a set of Docker containers. To configure TrustGraph on the command line:
npx @trustgraph/config
The config process will generate an app config that can be run locally with Docker, Podman, or Minikube. The process will output:
deploy.zipwith either adocker-compose.yamlfile for a Docker/Podman orresources.yamlfor Kubernetes- Deployment instructions as
INSTALLATION.md
For a browser based configuration, try the Configuration Terminal.
Watch What is a Context Graph?
Watch Context Graphs in Action
Getting Started with TrustGraph
Workbench
The Workbench provides tools for all major features of TrustGraph. The Workbench is on port 8888 by default.
- Vector Search: Search the installed knowledge bases
- Agentic, GraphRAG and LLM Chat: Chat interface for agents, GraphRAG queries, or direct to LLMs
- Relationships: Analyze deep relationships in the installed knowledge bases
- Graph Visualizer: 3D GraphViz of the installed knowledge bases
- Library: Staging area for installing knowledge bases
- Flow Classes: Workflow preset configurations
- Flows: Create custom workflows and adjust LLM parameters during runtime
- Knowledge Cores: Manage resuable knowledge bases
- Prompts: Manage and adjust prompts during runtime
- Schemas: Define custom schemas for structured data knowledge bases
- Ontologies: Define custom ontologies for unstructured data knowledge bases
- Agent Tools: Define tools with collections, knowledge cores, MCP connections, and tool groups
- MCP Tools: Connect to MCP servers
TypeScript Library for UIs
There are 3 libraries for quick UI integration of TrustGraph services.
Context Cores
A Context Core is a portable, versioned bundle of context that you can ship between projects and environments, pin in production, and reuse across agents. It packages the “stuff agents need to know” (structured knowledge + embeddings + evidence + policies) into a single artifact, so you can treat context like code: build it, test it, version it, promote it, and roll it back. TrustGraph is built to support this kind of end-to-end context engineering and orchestration workflow.
What’s inside a Context Core
A Context Core typically includes:
- Ontology (your domain schema) and mappings
- Context Graph (entities, relationships, supporting evidence)
- Embeddings / vector indexes for fast semantic entry-point lookup
- Source manifests + provenance (where facts came from, when, and how they were derived)
- Retrieval policies (traversal rules, freshness, authority ranking)
Tech Stack
TrustGraph provides component flexibility to optimize agent workflows.
LLM APIs
- Anthropic
- AWS Bedrock
- AzureAI
- AzureOpenAI
- Cohere
- Google AI Studio
- Google VertexAI
- Mistral
- OpenAI
LLM Orchestration
- LM Studio
- Llamafiles
- Ollama
- TGI
- vLLM
Multi-model storage
- Apache Cassandra
VectorDB
- Qdrant
File and Object Storage
- Garage
Observability
- Prometheus
- Grafana
- Loki
Data Streaming
- Apache Pulsar
Clouds
- AWS
- Azure
- Google Cloud
- OVHcloud
- Scaleway
Observability & Telemetry
Once the platform is running, access the Grafana dashboard at:
http://localhost:3000
Default credentials are:
user: admin
password: admin
The default Grafana dashboard tracks the following:
Telemetry
- LLM Latency
- Error Rate
- Service Request Rates
- Queue Backlogs
- Chunking Histogram
- Error Source by Service
- Rate Limit Events
- CPU usage by Service
- Memory usage by Service
- Models Deployed
- Token Throughput (Tokens/second)
- Cost Throughput (Cost/second)
Contributing
License
TrustGraph is licensed under Apache 2.0.
Copyright 2024-2025 TrustGraph
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.