mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
Update docs for API/CLI changes in 1.0 (#421)
* Update some API basics for the 0.23/1.0 API change
This commit is contained in:
cybermaggedon
GitHub
parent
f907ea7db8
commit
44bdd29f51
69 changed files with 19981 additions and 407 deletions
310
docs/apis/api-knowledge.md
Normal file
310
docs/apis/api-knowledge.md
Normal file
|
|
@ -0,0 +1,310 @@
|
|||
# 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:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
### GET-KG-CORE - Retrieve Knowledge Core
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"operation": "get-kg-core",
|
||||
"id": "core-123"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"operation": "list-kg-cores",
|
||||
"user": "alice"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"ids": ["core-123", "core-456", "core-789"]
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE-KG-CORE - Delete Knowledge Core
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"operation": "delete-kg-core",
|
||||
"user": "alice",
|
||||
"id": "core-123"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
### LOAD-KG-CORE - Load Knowledge Core into Flow
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"operation": "load-kg-core",
|
||||
"id": "core-123",
|
||||
"flow": "qa-flow",
|
||||
"collection": "research"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
### UNLOAD-KG-CORE - Unload Knowledge Core from Flow
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"operation": "unload-kg-core",
|
||||
"id": "core-123"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
## 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:
|
||||
```json
|
||||
{
|
||||
"id": "unique-request-id",
|
||||
"service": "knowledge",
|
||||
"request": {
|
||||
"operation": "list-kg-cores",
|
||||
"user": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```python
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue