API documentation (#221)

README.md

@@ -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
 

docs/apis/README.md

@@ -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)
+

docs/apis/api-agent.md

@@ -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

docs/apis/api-document-load.md

@@ -0,0 +1,3 @@
+
+Coming soon
+

docs/apis/api-embeddings.md

@@ -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
+

docs/apis/api-graph-embeddings.md

@@ -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
+
+
+
+
+
+
+
+

docs/apis/api-graph-rag.md

@@ -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
+

docs/apis/api-prompt.md

@@ -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
+

docs/apis/api-text-completion.md

@@ -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
+

docs/apis/api-triples-query.md

@@ -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
+
+
+
+
+
+
+
+

docs/apis/pulsar.md

@@ -0,0 +1,3 @@
+
+Coming soon
+

docs/apis/websocket.md

@@ -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
+}
+```
+

prometheus/prometheus.yml

@@ -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: 'agent-manager'
-  - job_name: 'pulsar'
     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'