API documentation (#221)

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
+