Fix/improve command line help (#145)

* Make command line consistent, fix incorrect documentation.

* Improve tg-invoke-prompt help

trustgraph-base/trustgraph/clients/prompt_client.py

@@ -57,13 +57,13 @@ class PromptClient(BaseClient):
             output_schema=PromptResponse,
         )
 
-    def request(self, id, terms, timeout=300):
+    def request(self, id, variables, timeout=300):
 
         resp = self.call(
             id=id,
             terms={
                 k: json.dumps(v)
-                for k, v in terms.items()
+                for k, v in variables.items()
             },
             timeout=timeout
         )
@@ -76,7 +76,7 @@ class PromptClient(BaseClient):
 
         defs = self.request(
             id="extract-definitions",
-            terms={
+            variables={
                 "text": chunk
             },
             timeout=timeout
@@ -91,7 +91,7 @@ class PromptClient(BaseClient):
 
         rels = self.request(
             id="extract-relationships",
-            terms={
+            variables={
                 "text": chunk
             },
             timeout=timeout
@@ -111,7 +111,7 @@ class PromptClient(BaseClient):
 
         topics = self.request(
             id="extract-topics",
-            terms={
+            variables={
                 "text": chunk
             },
             timeout=timeout
@@ -126,7 +126,7 @@ class PromptClient(BaseClient):
 
         return self.request(
             id="extract-rows",
-            terms={
+            variables={
                 "chunk": chunk,
                 "row-schema": {
                     "name": schema.name,
@@ -148,7 +148,7 @@ class PromptClient(BaseClient):
 
         return self.request(
             id="kg-prompt",
-            terms={
+            variables={
                 "query": query,
                 "knowledge": [
                     { "s": v[0], "p": v[1], "o": v[2] }
@@ -162,7 +162,7 @@ class PromptClient(BaseClient):
 
         return self.request(
             id="document-prompt",
-            terms={
+            variables={
                 "query": query,
                 "documents": documents,
             },

trustgraph-cli/scripts/tg-graph-show

@@ -27,7 +27,7 @@ def show_graph(pulsar, user, collection):
 def main():
 
     parser = argparse.ArgumentParser(
-        prog='graph-show',
+        prog='tg-graph-show',
         description=__doc__,
     )
 

trustgraph-cli/scripts/tg-graph-to-turtle

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 
 """
-Connects to the graph query service and dumps all graph edges.
+Connects to the graph query service and dumps all graph edges in Turtle
+format.
 """
 
 import argparse
@@ -50,7 +51,7 @@ def show_graph(pulsar):
 def main():
 
     parser = argparse.ArgumentParser(
-        prog='graph-show',
+        prog='tg-graph-to-turtle',
         description=__doc__,
     )
 

trustgraph-cli/scripts/tg-init-pulsar

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 """
-Initialises Pulsar with Trustgraph tenant / namespaces & policy
+Initialises Pulsar with Trustgraph tenant / namespaces & policy.
 """
 
 import requests

trustgraph-cli/scripts/tg-invoke-prompt

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 
 """
-Invokes the LLM prompt service by specifying a prompt identifier and template
-terms.  The prompt identifier identifies which prompt template to use.
-Standard template identifiers are: question, extract-relationship.
-The prompt terms specify keyword terms in the template to be replaced, and
-provide the values to replace them with.
+Invokes the LLM prompt service by specifying the prompt template to use
+and values for the variables in the prompt template.  The
+prompt template is identified by its template identifier e.g.
+question, extract-definitions.  Template variable values are specified
+using key=value arguments on the command line, and these replace
+{{key}} placeholders in the template.
 """
 
 import argparse
@@ -15,11 +16,11 @@ from trustgraph.clients.prompt_client import PromptClient
 
 default_pulsar_host = os.getenv("PULSAR_HOST", 'pulsar://localhost:6650')
 
-def query(pulsar_host, id, terms):
+def query(pulsar_host, template_id, variables):
 
     cli = PromptClient(pulsar_host=pulsar_host)
 
-    resp = cli.request(id=id, terms=terms)
+    resp = cli.request(id=template_id, variables=variables)
 
     if isinstance(resp, str):
         print(resp)
@@ -41,35 +42,37 @@ def main():
 
     parser.add_argument(
         'id',
+        metavar='template-id',
         nargs=1,
-        help=f'Prompt identifier e.g. question',
+        help=f'Prompt identifier e.g. question, extract-definitions',
     )
 
     parser.add_argument(
-        'term',
+        'variable',
         nargs='*',
-        help='''Prompt template terms of the form key=value, can be specified
-multiple times''',
+        metavar="variable=value",
+        help='''Prompt template terms of the form variable=value, can be
+specified multiple times''',
     )
 
     args = parser.parse_args()
 
-    terms = {}
+    variables = {}
 
-    for term in args.term:
+    for variable in args.variable:
 
-        toks = term.split("=", 1)
+        toks = variable.split("=", 1)
         if len(toks) != 2:
-            raise RuntimeError(f"Malformed term: {term}")
+            raise RuntimeError(f"Malformed variable: {variable}")
 
-        terms[toks[0]] = toks[1]
+        variables[toks[0]] = toks[1]
 
     try:
 
         query(
             pulsar_host=args.pulsar_host,
-            id=args.id[0],
-            terms=terms,
+            template_id=args.id[0],
+            variables=variables,
         )
 
     except Exception as e:

trustgraph-cli/scripts/tg-load-pdf

@@ -99,7 +99,7 @@ class Loader:
 def main():
 
     parser = argparse.ArgumentParser(
-        prog='loader',
+        prog='tg-load-pdf',
         description=__doc__,
     )
 

trustgraph-cli/scripts/tg-load-text

@@ -99,7 +99,7 @@ class Loader:
 def main():
 
     parser = argparse.ArgumentParser(
-        prog='loader',
+        prog='tg-load-text',
         description=__doc__,
     )