TrustGraph Knowledge API

This API provides knowledge graph management for TrustGraph. It handles storage, retrieval, and flow integration of knowledge cores containing RDF triples and graph embeddings with multi-tenant support.

Request/response

Request

The request contains the following fields:

  • operation: The operation to perform (see operations below)
  • user: User identifier (for user-specific operations)
  • id: Knowledge core identifier
  • flow: Flow identifier (for load operations)
  • collection: Collection identifier (for load operations)
  • triples: RDF triples data (for put operations)
  • graph_embeddings: Graph embeddings data (for put operations)

Response

The response contains the following fields:

  • error: Error information if operation fails
  • ids: Array of knowledge core IDs (returned by list operation)
  • eos: End of stream indicator for streaming responses
  • triples: RDF triples data (returned by get operation)
  • graph_embeddings: Graph embeddings data (returned by get operation)

Operations

PUT-KG-CORE - Store Knowledge Core

Request:

{
    "operation": "put-kg-core",
    "user": "alice",
    "id": "core-123",
    "triples": {
        "metadata": {
            "id": "core-123",
            "user": "alice",
            "collection": "research"
        },
        "triples": [
            {
                "s": {"value": "Person1", "is_uri": true},
                "p": {"value": "hasName", "is_uri": true},
                "o": {"value": "John Doe", "is_uri": false}
            },
            {
                "s": {"value": "Person1", "is_uri": true},
                "p": {"value": "worksAt", "is_uri": true},
                "o": {"value": "Company1", "is_uri": true}
            }
        ]
    },
    "graph_embeddings": {
        "metadata": {
            "id": "core-123",
            "user": "alice",
            "collection": "research"
        },
        "entities": [
            {
                "entity": {"value": "Person1", "is_uri": true},
                "vectors": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]
            }
        ]
    }
}

Response:

{}

GET-KG-CORE - Retrieve Knowledge Core

Request:

{
    "operation": "get-kg-core",
    "id": "core-123"
}

Response:

{
    "triples": {
        "metadata": {
            "id": "core-123",
            "user": "alice",
            "collection": "research"
        },
        "triples": [
            {
                "s": {"value": "Person1", "is_uri": true},
                "p": {"value": "hasName", "is_uri": true},
                "o": {"value": "John Doe", "is_uri": false}
            }
        ]
    },
    "graph_embeddings": {
        "metadata": {
            "id": "core-123",
            "user": "alice",
            "collection": "research"
        },
        "entities": [
            {
                "entity": {"value": "Person1", "is_uri": true},
                "vectors": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]
            }
        ]
    }
}

LIST-KG-CORES - List Knowledge Cores

Request:

{
    "operation": "list-kg-cores",
    "user": "alice"
}

Response:

{
    "ids": ["core-123", "core-456", "core-789"]
}

DELETE-KG-CORE - Delete Knowledge Core

Request:

{
    "operation": "delete-kg-core",
    "user": "alice",
    "id": "core-123"
}

Response:

{}

LOAD-KG-CORE - Load Knowledge Core into Flow

Request:

{
    "operation": "load-kg-core",
    "id": "core-123",
    "flow": "qa-flow",
    "collection": "research"
}

Response:

{}

UNLOAD-KG-CORE - Unload Knowledge Core from Flow

Request:

{
    "operation": "unload-kg-core",
    "id": "core-123"
}

Response:

{}

Data Structures

Triple Structure

Each RDF triple contains:

  • s: Subject (Value object)
  • p: Predicate (Value object)
  • o: Object (Value object)

Value Structure

  • value: The actual value as string
  • is_uri: Boolean indicating if value is a URI
  • type: Data type of the value (optional)

Triples Structure

  • metadata: Metadata including ID, user, collection
  • triples: Array of Triple objects

Graph Embeddings Structure

  • metadata: Metadata including ID, user, collection
  • entities: Array of EntityEmbeddings objects

Entity Embeddings Structure

  • entity: The entity being embedded (Value object)
  • vectors: Array of vector embeddings (Array of Array of Double)

REST service

The REST service is available at /api/v1/knowledge and accepts the above request formats.

Websocket

Requests have a request object containing the operation fields. Responses have a response object containing the response fields.

Request:

{
    "id": "unique-request-id",
    "service": "knowledge",
    "request": {
        "operation": "list-kg-cores",
        "user": "alice"
    }
}

Response:

{
    "id": "unique-request-id",
    "response": {
        "ids": ["core-123", "core-456"]
    },
    "complete": true
}

Pulsar

The Pulsar schema for the Knowledge API is defined in Python code here:

https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/knowledge.py

Default request queue: non-persistent://tg/request/knowledge

Default response queue: non-persistent://tg/response/knowledge

Request schema: trustgraph.schema.KnowledgeRequest

Response schema: trustgraph.schema.KnowledgeResponse

Python SDK

The Python SDK provides convenient access to the Knowledge API:

from trustgraph.api.knowledge import KnowledgeClient

client = KnowledgeClient()

# List knowledge cores
cores = await client.list_kg_cores("alice")

# Get a knowledge core
core = await client.get_kg_core("core-123")

# Store a knowledge core
await client.put_kg_core(
    user="alice",
    id="core-123",
    triples=triples_data,
    graph_embeddings=embeddings_data
)

# Load core into flow
await client.load_kg_core("core-123", "qa-flow", "research")

# Delete a knowledge core
await client.delete_kg_core("alice", "core-123")

Features

  • Knowledge Core Management: Store, retrieve, list, and delete knowledge cores
  • Dual Data Types: Support for both RDF triples and graph embeddings
  • Flow Integration: Load knowledge cores into processing flows
  • Multi-tenant Support: User-specific knowledge cores with isolation
  • Streaming Support: Efficient transfer of large knowledge cores
  • Collection Organization: Group knowledge cores by collection
  • Semantic Reasoning: RDF triples enable symbolic reasoning
  • Vector Similarity: Graph embeddings enable neural approaches

Use Cases

  • Knowledge Base Construction: Build semantic knowledge graphs from documents
  • Question Answering: Load knowledge cores for graph-based QA systems
  • Semantic Search: Use embeddings for similarity-based knowledge retrieval
  • Multi-domain Knowledge: Organize knowledge by user and collection
  • Hybrid Reasoning: Combine symbolic (triples) and neural (embeddings) approaches
  • Knowledge Transfer: Export and import knowledge cores between systems