mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 00:16:23 +02:00
API documentation (#221)
This commit is contained in:
cybermaggedon
GitHub
parent
74ea3b8b96
commit
2d3802e001
13 changed files with 1163 additions and 20 deletions
|
|
@ -125,9 +125,13 @@ Once the knowledge graph has been built or a knowledge core has been loaded, Gra
|
|||
tg-query-graph-rag -q "Write a blog post about the 5 key takeaways from SB1047 and how they will impact AI development."
|
||||
```
|
||||
|
||||
## API documentation
|
||||
|
||||
[Developing on TrustGraph using APIs](docs/api/README.md)
|
||||
|
||||
## Deploy and Manage TrustGraph
|
||||
|
||||
[🚀 Full Deployment Guide 🚀](https://trustgraph.ai/docs/getstarted)
|
||||
[🚀🙏 Full Deployment Guide 🚀🙏](https://trustgraph.ai/docs/getstarted)
|
||||
|
||||
## TrustGraph Developer's Guide
|
||||
|
||||
|
|
|
|||
72
docs/apis/README.md
Normal file
72
docs/apis/README.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
|
||||
# TrustGraph APIs
|
||||
|
||||
## Overview
|
||||
|
||||
If you want to interact with TrustGraph through APIs, there are 3
|
||||
forms of API which may be of interest to you:
|
||||
|
||||
### Pulsar APIs
|
||||
|
||||
Apache Pulsar is a pub/sub system used to deliver messages between TrustGraph
|
||||
components. Using Pulsar, you can communicate with TrustGraph components.
|
||||
|
||||
Pros:
|
||||
- Provides complete access to all TrustGraph functionality
|
||||
- Simple integration with metrics and observability
|
||||
|
||||
Cons:
|
||||
- Integration is non-trivial, requires a special-purpose Pulsar client
|
||||
library
|
||||
- The Pulsar interfaces are likely something that you would not want to
|
||||
expose outside of the processing cluster in a production or well-secured
|
||||
deployment
|
||||
|
||||
### REST APIs
|
||||
|
||||
A component, `api-gateway`, provides a bridge between Pulsar internals and
|
||||
the REST API which allows many services to be invoked using REST APIs.
|
||||
|
||||
Pros:
|
||||
- Uses standard REST approach can be easily integrated into many kinds
|
||||
of technology
|
||||
- Can be easily protected with authentication and TLS for production-grade
|
||||
or secure deployments
|
||||
|
||||
Cons:
|
||||
- For a complex application, a long series of REST invocations has
|
||||
latency and performance overheads - HTTP has limits on the number
|
||||
of concurrent service invocations
|
||||
- Lower coverage of functionality - service interfaces need to be added to
|
||||
`api-gateway` to permit REST invocation
|
||||
|
||||
### Websocket API
|
||||
|
||||
The `api-gateway` component also provides access to services through a
|
||||
websocket API.
|
||||
|
||||
Pros:
|
||||
- Usable through a standard websocket library
|
||||
- Can be easily protected with authentication and TLS for production-grade
|
||||
or secure deployments
|
||||
- Supports concurrent service invocations
|
||||
|
||||
Cons:
|
||||
- Websocket service invocation is a little more complex to develop than
|
||||
using a basic REST API, particular if you want to cover all of the error
|
||||
scenarios well
|
||||
|
||||
## See also
|
||||
|
||||
- [TrustGraph websocket overview](websocket.md)
|
||||
- [TrustGraph Pulsar overview](pulsar.md)
|
||||
- API details
|
||||
- [Text completion](api-text-completion.md)
|
||||
- [Prompt completion](api-prompt.md)
|
||||
- [Graph RAG](api-graph-rag.md)
|
||||
- [Agent](api-agent.md)
|
||||
- [Embeddings](api-embeddings.md)
|
||||
- [Graph embeddings](api-graph-embeddings.md)
|
||||
- [Triples query](api-triples-query.md)
|
||||
- [Document load](api-document-load.md)
|
||||
|
||||
135
docs/apis/api-agent.md
Normal file
135
docs/apis/api-agent.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
|
||||
# TrustGraph Agent API
|
||||
|
||||
The REST service provides incomplete functionality: The agent service
|
||||
is able to provide multi-part responses containing 'thought' and
|
||||
'observation' messages as the agent manager iterates over resolution of the
|
||||
question. These responses are provided in the websocket, but not the REST
|
||||
API.
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `question`: A string, the question which the agent API must resolve
|
||||
- `plan`: Optional, not used
|
||||
- `state`: Optional, not used
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `thought`: Optional, a string, provides an interim agent thought
|
||||
- `observation`: Optional, a string, provides an interim agent thought
|
||||
- `answer`: Optional, a string, provides the final answer
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the question field.
|
||||
The response is a JSON object containing the `answer` field. Interim
|
||||
responses are not provided.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"question": "What does NASA stand for?"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"answer": "National Aeronautics and Space Administration"
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Agent requests have a `request` object containing the `question` field.
|
||||
Responses have a `response` object containing `thought`, `observation`
|
||||
and `answer` fields in multi-part responses. The final `answer` response
|
||||
has `complete` set to `true`.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"service": "agent",
|
||||
"request": {
|
||||
"question": "What does NASA stand for?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"thought": "I need to query a knowledge base"
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"observation": "National Aeronautics and Space Administration."
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"thought": "I now know the final answer"
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"answer": "National Aeronautics and Space Administration"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Agent API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/agent.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/agent`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/agent`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.AgentRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.AgentResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.AgentClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/agent_client.py
|
||||
3
docs/apis/api-document-load.md
Normal file
3
docs/apis/api-document-load.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
|
||||
Coming soon
|
||||
|
||||
106
docs/apis/api-embeddings.md
Normal file
106
docs/apis/api-embeddings.md
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
|
||||
# TrustGraph Embeddings API
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `text`: A string, the text to apply the embedding to
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `vectors`: Embeddings response, an array of arrays. An embedding is
|
||||
an array of floating-point numbers. As multiple embeddings may be
|
||||
returned, an array of embeddings is returned, hence an array
|
||||
of arrays.
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the question field.
|
||||
The response is a JSON object containing the `answer` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"text": "What does NASA stand for?"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"vectors": [ 0.231341245, ... ]
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Embeddings requests have a `request` object containing the `text` field.
|
||||
Responses have a `response` object containing `vectors` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-2",
|
||||
"service": "embeddings",
|
||||
"request": {
|
||||
"text": "What is a cat?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
```
|
||||
|
||||
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-2",
|
||||
"response": {
|
||||
"vectors": [
|
||||
[
|
||||
0.04013510048389435,
|
||||
0.07536131888628006,
|
||||
...
|
||||
-0.023531345650553703,
|
||||
0.03591292351484299
|
||||
]
|
||||
]
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Embeddings API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/models.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/embeddings`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/embeddings`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.EmbeddingsRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.EmbeddingsResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.EmbeddingsClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/embeddings_client.py
|
||||
|
||||
155
docs/apis/api-graph-embeddings.md
Normal file
155
docs/apis/api-graph-embeddings.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
|
||||
# TrustGraph Graph Embeddings API
|
||||
|
||||
The purpose of this API is to search for knowledge graph entities
|
||||
by embeddings. The request is a list of embeddings, the response is
|
||||
a list of knowledge graph entities. The search is performed using a
|
||||
vector store.
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `vectors`: An array of embeddings. Each embedding is itself an array
|
||||
of numbers.
|
||||
- `limit`: Optional: a limit on the number of graph entities to return.
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `entities`: An array of graph entities. The entity type is described here:
|
||||
|
||||
TrustGraph uses the same schema for knowledge graph elements:
|
||||
- `value`: the entity URI or literal value depending on whether this is
|
||||
graph entity or literal value.
|
||||
- `is_uri`: A boolean value which is true if this is a graph entity i.e.
|
||||
`value` is a URI, not a literal value.
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the `vectors` field.
|
||||
The response is a JSON object containing the `entities` field.
|
||||
|
||||
To reduce the size of the JSON, the graph entities are encoded as an
|
||||
object with `value` and `is_uri` mapped to `v` and `e` respectively.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"vectors": [
|
||||
[
|
||||
0.04013510048389435,
|
||||
0.07536131888628006,
|
||||
...
|
||||
-0.10790473222732544,
|
||||
0.03591292351484299
|
||||
]
|
||||
],
|
||||
"limit": 15
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
{
|
||||
"v": "http://trustgraph.ai/e/rocket-propellants",
|
||||
"e": true
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
The websocket service accepts a request object containing the `vectors` field.
|
||||
The response is a JSON object containing the `entities` field.
|
||||
|
||||
To reduce the size of the JSON, the graph entities are encoded as an
|
||||
object with `value` and `is_uri` mapped to `v` and `e` respectively.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-3",
|
||||
"service": "graph-embeddings-query",
|
||||
"request": {
|
||||
"vectors": [
|
||||
[
|
||||
0.04013510048389435,
|
||||
0.07536131888628006,
|
||||
...
|
||||
-0.10790473222732544,
|
||||
0.03591292351484299
|
||||
]
|
||||
],
|
||||
"limit": 15
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-3",
|
||||
"response": {
|
||||
"entities": [
|
||||
{
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
{
|
||||
"v": "http://trustgraph.ai/e/rocket-propellants",
|
||||
"e": true
|
||||
},
|
||||
]
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Graph Embeddings API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/graph.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/graph-embeddings`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/graph-embeddings`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.GraphEmbeddingsRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.GraphEmbeddingsResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.GraphEmbeddingsClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/graph_embeddings.py
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
97
docs/apis/api-graph-rag.md
Normal file
97
docs/apis/api-graph-rag.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
|
||||
# TrustGraph Graph RAG API
|
||||
|
||||
This presents a prompt to the Graph RAG service and retrieves the answer.
|
||||
This makes use of a number of the other APIs behind the scenes:
|
||||
Embeddings, Graph Embeddings, Prompt, TextCompletion, Triples Query.
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `query`: The question to answer
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `response`: LLM response
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the `query` field.
|
||||
The response is a JSON object containing the `response` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"query": "What does NASA stand for?"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"response": "National Aeronautics and Space Administration"
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Requests have a `request` object containing the `query` field.
|
||||
Responses have a `response` object containing `response` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-14",
|
||||
"service": "graph-rag",
|
||||
"request": {
|
||||
"query": "What does NASA stand for?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-14",
|
||||
"response": {
|
||||
"response": "National Aeronautics and Space Administration"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Graph RAG API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/retrieval.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/graph-rag`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/graph-rag`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.GraphRagRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.GraphRagResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.GraphRagClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/graph_rag_client.py
|
||||
|
||||
140
docs/apis/api-prompt.md
Normal file
140
docs/apis/api-prompt.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
|
||||
# TrustGraph Prompt API
|
||||
|
||||
This is a higher-level interface to the LLM service. The input
|
||||
specifies a prompt template by ID and some variables to include in the
|
||||
template.
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `id`: A prompt template ID
|
||||
- `variables`: A set of key/values describing the variables
|
||||
|
||||
### Response
|
||||
|
||||
The request contains either of these fields:
|
||||
- `text`: A plain text response
|
||||
- `object`: A structured object, JSON-encoded
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts `id` and `variables` fields, the variables are
|
||||
encoded as a JSON object.
|
||||
|
||||
e.g.
|
||||
|
||||
In this example, the template takes a `text` variable and returns an
|
||||
array of entity definitions in t he `object` field. The value is
|
||||
JSON-encoded.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"id": "extract-definitions",
|
||||
"variables": {
|
||||
"text": "A cat is a domesticated Felidae animal"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"object": "[{\"entity\": \"cat\", \"definition\": \"a domesticated Felidae animal\"}]"
|
||||
},
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Requests have `id` and `variables` fields.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "akshfkiehfkseffh-142",
|
||||
"service": "prompt",
|
||||
"request": {
|
||||
"id": "extract-definitions",
|
||||
"variables": {
|
||||
"text": "A cat is a domesticated Felidae animal"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "akshfkiehfkseffh-142",
|
||||
"response": {
|
||||
"object": "[{\"entity\": \"cat\", \"definition\": \"a domesticated Felidae animal\"}]"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
e.g.
|
||||
|
||||
An example which returns plain text
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "akshfkiehfkseffh-141",
|
||||
"service": "prompt",
|
||||
"request": {
|
||||
"id": "question",
|
||||
"variables": {
|
||||
"question": "What is 2 + 2?"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "akshfkiehfkseffh-141",
|
||||
"response": {
|
||||
"text": "2 + 2 = 4"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Prompt API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/prompt.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/prompt`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/prompt`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.PromptRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.PromptResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.PromptClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/prompt_client.py
|
||||
|
||||
105
docs/apis/api-text-completion.md
Normal file
105
docs/apis/api-text-completion.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
|
||||
# TrustGraph Text Completion API
|
||||
|
||||
This is a low-level interface to the LLM service. For a higher-level
|
||||
interface with template management, consider the
|
||||
[Prompt API](api-prompt.md).
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
Some LLM system permit specifying a separate `system` prompt. When
|
||||
the same system prompt is used repeatedly, this can result in lower
|
||||
token costs for the system part or quicker LLM response.
|
||||
|
||||
The request contains the following fields:
|
||||
- `system`: A string, the system part
|
||||
- `prompt`: A string, the user part
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `response`: LLM response
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the question field.
|
||||
The response is a JSON object containing the `answer` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"system": "You are a helpful agent",
|
||||
"prompt": "What does NASA stand for?"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"response": "National Aeronautics and Space Administration"
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Requests have a `request` object containing the `system` and
|
||||
`prompt` fields.
|
||||
Responses have a `response` object containing `response` field.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-1",
|
||||
"service": "text-completion",
|
||||
"request": {
|
||||
"system": "You are a helpful agent",
|
||||
"prompt": "What does NASA stand for?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-1",
|
||||
"response": {
|
||||
"response": "National Aeronautics and Space Administration"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Text Completion API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/models.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/text-completion`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/text-completion`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.TextCompletionRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.TextCompletionResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.LlmClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/llm_client.py
|
||||
|
||||
187
docs/apis/api-triples-query.md
Normal file
187
docs/apis/api-triples-query.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
|
||||
# TrustGraph Triples Query API
|
||||
|
||||
This is a service which queries the knowledge graph for triples ("facts").
|
||||
|
||||
## Request/response
|
||||
|
||||
### Request
|
||||
|
||||
The request contains the following fields:
|
||||
- `s`: Optional, if included specifies a match for the subject part of a
|
||||
triple.
|
||||
- `p`: Optional, if included specifies a match for the subject part of a
|
||||
triple.
|
||||
- `o`: Optional, if included specifies a match for the subject part of a
|
||||
triple.
|
||||
- `limit`: Optional, if included specifies the maximum number of triples to
|
||||
return. If not specified, an arbitrary value is used.
|
||||
|
||||
Returned triples will match all of `s`, `p` and `o` where provided.
|
||||
|
||||
### Response
|
||||
|
||||
The request contains the following fields:
|
||||
- `response`: A list of triples.
|
||||
|
||||
Each triple contains `s`, `p` and `o` fields describing the
|
||||
subject, predicate and object part of each triple.
|
||||
|
||||
Each triple element uses the same schema:
|
||||
- `value`: the entity URI or literal value depending on whether this is
|
||||
graph entity or literal value.
|
||||
- `is_uri`: A boolean value which is true if this is a graph entity i.e.
|
||||
`value` is a URI, not a literal value.
|
||||
|
||||
## REST service
|
||||
|
||||
The REST service accepts a request object containing the `s`, `p`, `o`
|
||||
and `limit` fields.
|
||||
The response is a JSON object containing the `response` field.
|
||||
|
||||
To reduce the size of the JSON, the graph entities are encoded as an
|
||||
object with `value` and `is_uri` mapped to `v` and `e` respectively.
|
||||
|
||||
e.g.
|
||||
|
||||
This example query matches triples with a subject of
|
||||
`http://trustgraph.ai/e/space-station-modules` and a predicate of
|
||||
`http://www.w3.org/2000/01/rdf-schema#label`. This predicate
|
||||
represents the RDF schema 'label' relationship.
|
||||
|
||||
The response is a single triple - the `o` element contains the
|
||||
literal "space station modules" which is the label for
|
||||
`http://trustgraph.ai/e/space-station-modules`.
|
||||
|
||||
Request:
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-4",
|
||||
"service": "triples-query",
|
||||
"request": {
|
||||
"s": {
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
"p": {
|
||||
"v": "http://www.w3.org/2000/01/rdf-schema#label",
|
||||
"e": true
|
||||
},
|
||||
"limit": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
"response": [
|
||||
{
|
||||
"s": {
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
"p": {
|
||||
"v": "http://www.w3.org/2000/01/rdf-schema#label",
|
||||
"e": true
|
||||
},
|
||||
"o": {
|
||||
"v": "space station modules",
|
||||
"e": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Websocket
|
||||
|
||||
Requests have a `request` object containing the `system` and
|
||||
`prompt` fields.
|
||||
Responses have a `response` object containing `response` field.
|
||||
|
||||
To reduce the size of the JSON, the graph entities are encoded as an
|
||||
object with `value` and `is_uri` mapped to `v` and `e` respectively.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-4",
|
||||
"service": "triples-query",
|
||||
"request": {
|
||||
"s": {
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
"p": {
|
||||
"v": "http://www.w3.org/2000/01/rdf-schema#label",
|
||||
"e": true
|
||||
},
|
||||
"limit": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-4",
|
||||
"response": {
|
||||
"response": [
|
||||
{
|
||||
"s": {
|
||||
"v": "http://trustgraph.ai/e/space-station-modules",
|
||||
"e": true
|
||||
},
|
||||
"p": {
|
||||
"v": "http://www.w3.org/2000/01/rdf-schema#label",
|
||||
"e": true
|
||||
},
|
||||
"o": {
|
||||
"v": "space station modules",
|
||||
"e": false
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pulsar
|
||||
|
||||
The Pulsar schema for the Triples Query API is defined in Python code here:
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/graph.py
|
||||
|
||||
Default request queue:
|
||||
`non-persistent://tg/request/triples-query`
|
||||
|
||||
Default response queue:
|
||||
`non-persistent://tg/response/triples-query`
|
||||
|
||||
Request schema:
|
||||
`trustgraph.schema.TriplesQueryRequest`
|
||||
|
||||
Response schema:
|
||||
`trustgraph.schema.TriplesQueryResponse`
|
||||
|
||||
## Pulsar Python client
|
||||
|
||||
The client class is
|
||||
`trustgraph.clients.TriplesQueryClient`
|
||||
|
||||
https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/triples_query_client.py
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3
docs/apis/pulsar.md
Normal file
3
docs/apis/pulsar.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
|
||||
Coming soon
|
||||
|
||||
136
docs/apis/websocket.md
Normal file
136
docs/apis/websocket.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
|
||||
# TrustGraph websocket overview
|
||||
|
||||
The websocket service is provided by the `api-gateway` service on port
|
||||
8088.
|
||||
|
||||
## URL
|
||||
|
||||
Depending on how the service is hosted, the websocket is invoked on this
|
||||
URL on `api-gateway`:
|
||||
|
||||
```
|
||||
/api/v1/socket
|
||||
```
|
||||
|
||||
When hosted using docker compose, you can access the service at
|
||||
`ws://localhost:8088/api/v1/socket`
|
||||
|
||||
## Request
|
||||
|
||||
A request message is a JSON message containing 3 fields:
|
||||
|
||||
- `id`: A unique ID which is used to correlate requests and responses.
|
||||
You should make sure it is unique.
|
||||
- `service`: The name of the service to invoke.
|
||||
- `request`: The request body which is passed to the service - this is
|
||||
defined in the API documentation for that service.
|
||||
|
||||
e.g.
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-1",
|
||||
"service": "graph-rag",
|
||||
"request": {
|
||||
"query": "What does NASA stand for?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
A response message is JSON encoded, and may contain the following fields:
|
||||
|
||||
- `id`: This is the same value provided on the request and shows which
|
||||
request this response is returned for.
|
||||
- `error`: If an error occured, this field is provided, and provides an
|
||||
error message.
|
||||
- `response`: For a non-error case, this provides a response from the
|
||||
service - the response structure depends on the service invoked. It is
|
||||
not provided if the `error` field is provided.
|
||||
- `complete`: A boolean value indicating whether this response is the
|
||||
final response from the service. If set to false, the response values
|
||||
are intermediate values. It is not provided if the `error` field is
|
||||
provided.
|
||||
|
||||
An error response completes a request - no further responses
|
||||
will be provided.
|
||||
|
||||
e.g.
|
||||
|
||||
```
|
||||
{
|
||||
"id": "qgzw1287vfjc8wsk-1",
|
||||
"response": {
|
||||
"response": "National Aeronautics and Space Administration."
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-part response
|
||||
|
||||
For a multi-part response, a number of responses are provided with the
|
||||
same ID until the final message which has the `complete` field set to
|
||||
true.
|
||||
|
||||
Note that multi-part responses are a feature of the websocket API which
|
||||
the request/response nature of the REST API is not able to provide.
|
||||
|
||||
e.g.
|
||||
|
||||
Request:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"service": "agent",
|
||||
"request": {
|
||||
"question": "What does NASA stand for?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Responses:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"thought": "I need to query a knowledge base"
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"observation": "National Aeronautics and Space Administration."
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"thought": "I now know the final answer"
|
||||
},
|
||||
"complete": false
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
{
|
||||
"id": "blrqotfefnmnh7de-20",
|
||||
"response": {
|
||||
"answer": "National Aeronautics and Space Administration"
|
||||
},
|
||||
"complete": true
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -14,6 +14,12 @@ scrape_configs:
|
|||
# The job name is added as a label `job=<job_name>` to any timeseries
|
||||
# scraped from this config.
|
||||
|
||||
- job_name: 'pulsar'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'pulsar:8080'
|
||||
|
||||
- job_name: 'pdf-decoder'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
|
|
@ -26,122 +32,116 @@ scrape_configs:
|
|||
- targets:
|
||||
- 'chunker:8000'
|
||||
|
||||
|
||||
- job_name: 'vectorize'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'vectorize:8000'
|
||||
|
||||
|
||||
- job_name: 'embeddings'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'embeddings:8000'
|
||||
|
||||
|
||||
- job_name: 'kg-extract-definitions'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'kg-extract-definitions:8000'
|
||||
|
||||
|
||||
- job_name: 'kg-extract-topics'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'kg-extract-topics:8000'
|
||||
|
||||
|
||||
- job_name: 'kg-extract-relationships'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'kg-extract-relationships:8000'
|
||||
|
||||
|
||||
- job_name: 'metering'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'metering:8000'
|
||||
|
||||
|
||||
- job_name: 'metering-rag'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'metering-rag:8000'
|
||||
|
||||
|
||||
- job_name: 'store-graph-embeddings'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'store-graph-embeddings:8000'
|
||||
|
||||
|
||||
- job_name: 'store-triples'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'store-triples:8000'
|
||||
|
||||
|
||||
- job_name: 'text-completion'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'text-completion:8000'
|
||||
|
||||
|
||||
- job_name: 'text-completion-rag'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'text-completion-rag:8000'
|
||||
|
||||
|
||||
- job_name: 'graph-rag'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'graph-rag:8000'
|
||||
|
||||
|
||||
- job_name: 'prompt'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'prompt:8000'
|
||||
|
||||
|
||||
- job_name: 'prompt-rag'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'prompt-rag:8000'
|
||||
|
||||
|
||||
- job_name: 'query-graph-embeddings'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'query-graph-embeddings:8000'
|
||||
|
||||
|
||||
- job_name: 'query-triples'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'query-triples:8000'
|
||||
|
||||
|
||||
- job_name: 'pulsar'
|
||||
- job_name: 'agent-manager'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'pulsar:8080'
|
||||
- 'agent-manager:8000'
|
||||
|
||||
- job_name: 'api-gateway'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'api-gateway:8000'
|
||||
|
||||
- job_name: 'workbench-ui'
|
||||
scrape_interval: 5s
|
||||
static_configs:
|
||||
- targets:
|
||||
- 'workbench-ui:8000'
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue