The following shows how to invoke the tool. The help section is automagically generated and needs some rework. Thus, see below for some real usage or read the README in the GitHub repository.



In [3]:

    
%%sh
python wctool.py -h









    



usage: wctool [-h] [-l] [-c] [-u] [-d] [-g] [-full] [-id WORKSPACEID]
              [-o OUTFILE] [-i INFILE] [-name WSNAME] [-desc WSDESCRIPTION]
              [-lang WSLANG] [-intents] [-entities] [-dialog_nodes]
              [-counterexamples] [-metadata]

Process my Watson Conversation Commands

optional arguments:
  -h, --help           show this help message and exit
  -l                   list workspaces
  -c                   create workspace
  -u                   update workspace
  -d                   delete workspace
  -g                   get details for single workspace
  -full                get the full workspace
  -id WORKSPACEID      Workspace ID
  -o OUTFILE           output file
  -i INFILE            input file
  -name WSNAME         Workspace Name
  -desc WSDESCRIPTION  Workspace Description
  -lang WSLANG         Workspace Language
  -intents             Intents
  -entities            Entities
  -dialog_nodes        Dialog Nodes
  -counterexamples     Counterexamples
  -metadata            Metadata

The first command lists the existing workspaces. Before you can use the tool you need to put your credentials for Watson Conversation into the file config.json. A template is provided as config.json.sample.



In [5]:

    
%%sh
python wctool.py -l









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=False, getWorkspace=False, inFile=None, listWorkspaces=True, outFile=None, updateWorkspace=False, workspaceID=None, wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName=None)
{
  "pagination": {
    "refresh_url": "/v1/workspaces?version=2017-02-03"
  }, 
  "workspaces": [
    {
      "updated": "2017-03-07T13:39:18.836Z", 
      "description": "Workspace to be used for testing and training.", 
      "language": "en", 
      "created": "2017-03-07T13:39:18.836Z", 
      "workspace_id": "6dc1e2b8-4066-45a3-a5e5-ddfb3b2392a5", 
      "name": "Ana", 
      "metadata": null
    }, 
    {
      "updated": "2017-03-07T13:38:03.496Z", 
      "description": "tests with dashDB", 
      "language": "en", 
      "created": "2016-07-12T07:59:00.869Z", 
      "workspace_id": "81ec3507-5ccc-47f0-a5aa-c99a813459db", 
      "name": "dbtest", 
      "metadata": {
        "runtime_version": null
      }
    }, 
    {
      "updated": "2017-03-07T13:38:20.371Z", 
      "description": null, 
      "language": "de", 
      "created": "2017-01-24T09:13:57.422Z", 
      "workspace_id": "411624b8-733b-4467-a656-6df75a253f15", 
      "name": "Ger2", 
      "metadata": {
        "runtime_version": null
      }
    }, 
    {
      "updated": "2017-03-27T13:28:30.671Z", 
      "description": "Test der Deutschkenntnisse", 
      "language": "de", 
      "created": "2017-01-20T16:38:21.718Z", 
      "workspace_id": "3ecf2f27-3668-489e-b5cd-39f8cc6f3159", 
      "name": "GermanUpdated", 
      "metadata": {
        "runtime_version": null
      }
    }, 
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": "Now it is an updated workspace", 
      "language": "de", 
      "created": "2017-03-28T07:24:36.488Z", 
      "workspace_id": "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5", 
      "name": "GermanUpdated", 
      "metadata": {
        "runtime_version": null
      }
    }
  ]
}

Get the details for one of the existing workspaces. There is not much extra information compared to the LIST command.



In [6]:

    
%%sh
python wctool.py -g -id "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5"









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=False, getWorkspace=True, inFile=None, listWorkspaces=False, outFile=None, updateWorkspace=False, workspaceID='93fac4d7-2fab-4a02-b282-ce28a1d9f3f5', wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName=None)
{
  "status": "Available", 
  "updated": "2017-03-28T07:32:12.111Z", 
  "description": "Now it is an updated workspace", 
  "language": "de", 
  "created": "2017-03-28T07:24:36.488Z", 
  "workspace_id": "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5", 
  "name": "GermanUpdated", 
  "metadata": {
    "runtime_version": null
  }
}

However, when using the option "-full", then the entire workspace is returned.



In [7]:

    
%%sh
python wctool.py -g -id "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5" -full









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=True, getWorkspace=True, inFile=None, listWorkspaces=False, outFile=None, updateWorkspace=False, workspaceID='93fac4d7-2fab-4a02-b282-ce28a1d9f3f5', wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName=None)
{
  "status": "Available", 
  "intents": [
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "intent": "Begruessung", 
      "examples": [
        {
          "text": "Guten Morgen", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Guten Tag", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Hallo, wie ist die Lage?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Moin, moin, moin", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Moin, wie geht's?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Tach, alles klar bei dir?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Wie geht es", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "created": "2017-03-28T07:32:12.111Z"
    }, 
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "intent": "Regen", 
      "examples": [
        {
          "text": "Am Dienstag wird es im Tagesverlauf regnen", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Der Regen geht in Schnee \u00fcber", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Es ziehen Regenwolken auf.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Gibt es morgen Regen?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Morgen wird es Regen geben.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "created": "2017-03-28T07:32:12.111Z"
    }, 
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "intent": "Sonne", 
      "examples": [
        {
          "text": "Am Nachmittag h\u00f6rt der Regen auf und die Sonne setzt sich durch.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Am Nachmittag kommt die Sonne durch.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Der Tag bringt mehr Sonne als Wolken.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Der Tag wird \u00fcberwiegend sonnig.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Die Sonne wird den gesamten Tag \u00fcber scheinen.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "created": "2017-03-28T07:32:12.111Z"
    }, 
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "intent": "verabschiedung", 
      "examples": [
        {
          "text": "Alles Gute", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Auf Wiedersehen", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Bis dann", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Na dann, bis demn\u00e4chst.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Tschau", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Tsch\u00fcss, bis bald", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "created": "2017-03-28T07:32:12.111Z"
    }, 
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "intent": "Wetter", 
      "examples": [
        {
          "text": "Es kommt zu Wetterbesserungen.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "In den n\u00e4chsten Tagen wird das Wetter wieder freundlicher.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Lass uns \u00fcber das Wetter sprechen.", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Was macht das Wetter?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Wie ist heute das Wetter?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Wie wird das Wetter am Samstag? Wird es schneien?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "text": "Wie wird morgen das Wetter sein?", 
          "updated": "2017-03-28T07:32:12.111Z", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "created": "2017-03-28T07:32:12.111Z"
    }
  ], 
  "name": "GermanUpdated", 
  "language": "de", 
  "created": "2017-03-28T07:24:36.488Z", 
  "workspace_id": "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5", 
  "description": "Now it is an updated workspace", 
  "updated": "2017-03-28T07:32:12.111Z", 
  "entities": [
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "created": "2017-03-28T07:32:12.111Z", 
      "entity": "wetterlage", 
      "source": null, 
      "open_list": false, 
      "values": [
        {
          "updated": "2017-03-28T07:32:12.111Z", 
          "metadata": null, 
          "synonyms": [
            "Niederschlag", 
            "regnerisch", 
            "Schauer", 
            "tr\u00f6pfeln"
          ], 
          "value": "Regen", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "updated": "2017-03-28T07:32:12.111Z", 
          "metadata": null, 
          "synonyms": [
            "klar", 
            "sonnig"
          ], 
          "value": "Sonne", 
          "created": "2017-03-28T07:32:12.111Z"
        }, 
        {
          "updated": "2017-03-28T07:32:12.111Z", 
          "metadata": null, 
          "synonyms": [
            "frostig", 
            "hei\u00df", 
            "kalt", 
            "K\u00e4lte", 
            "k\u00fchl", 
            "lauwarm", 
            "warm", 
            "W\u00e4rme"
          ], 
          "value": "Temperatur", 
          "created": "2017-03-28T07:32:12.111Z"
        }
      ], 
      "type": null
    }
  ], 
  "counterexamples": [], 
  "dialog_nodes": [
    {
      "updated": "2017-03-28T07:32:12.111Z", 
      "description": null, 
      "parent": null, 
      "created": "2017-03-28T07:32:12.111Z", 
      "dialog_node": "beginn", 
      "previous_sibling": null, 
      "context": null, 
      "output": {}, 
      "metadata": null, 
      "conditions": "#begr\u00fc\u00dfung", 
      "go_to": null
    }
  ], 
  "metadata": {
    "runtime_version": null
  }
}

Instead of printing the workspace to the screen, it can be saved to a file. When the "-o" (output) option is used it is assumed that you are interested in the full workspace.



In [8]:

    
%%sh
python wctool.py -g -id "93fac4d7-2fab-4a02-b282-ce28a1d9f3f5" -o henriksWorkspace.json









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=False, getWorkspace=True, inFile=None, listWorkspaces=False, outFile='henriksWorkspace.json', updateWorkspace=False, workspaceID='93fac4d7-2fab-4a02-b282-ce28a1d9f3f5', wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName=None)
Document saved to henriksWorkspace.json

An existing workspace can be used to populate a new workspace. So here is how to create one:



In [9]:

    
%%sh
python wctool.py -c -name HenriksNewWorkspace -desc "Test for my blog" -lang de -i henriksWorkspace.json









    



Namespace(createWorkspace=True, deleteWorkspace=False, fullWorkspace=False, getWorkspace=False, inFile='henriksWorkspace.json', listWorkspaces=False, outFile=None, updateWorkspace=False, workspaceID=None, wsCounterexamples=False, wsDescription='Test for my blog', wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang='de', wsMetadata=False, wsName='HenriksNewWorkspace')
{
  "updated": "2017-03-28T09:00:08.181Z", 
  "description": "Test for my blog", 
  "language": "de", 
  "created": "2017-03-28T09:00:08.181Z", 
  "workspace_id": "f5db2447-55dd-4c7e-a764-2319a17dbfee", 
  "name": "HenriksNewWorkspace", 
  "metadata": {
    "runtime_version": null
  }
}

An existing workspace can be updated and the name, its language or the description be changed. It is also possible to replace intents, entities and other parts of the workspace (shown in the step hereafter).



In [10]:

    
%%sh
python wctool.py -u -id "f5db2447-55dd-4c7e-a764-2319a17dbfee" -name "Henrik renamed it"









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=False, getWorkspace=False, inFile=None, listWorkspaces=False, outFile=None, updateWorkspace=True, workspaceID='f5db2447-55dd-4c7e-a764-2319a17dbfee', wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName='Henrik renamed it')
Workspace updated - new workspace
{
  "updated": "2017-03-28T09:01:30.078Z", 
  "description": "Test for my blog", 
  "language": "de", 
  "created": "2017-03-28T09:00:08.181Z", 
  "workspace_id": "f5db2447-55dd-4c7e-a764-2319a17dbfee", 
  "name": "Henrik renamed it", 
  "metadata": {
    "runtime_version": null
  }
}

Now you would edit the local file to make changes to intents, entities or dialog node and store the changes back to the file henriksWorkspace.json. That file is taken as input for the UPDATE command. Only those section specified as options are updated. In the sample below only intents and counterexamples are updated.



In [11]:

    
%%sh
python wctool.py -u -id "f5db2447-55dd-4c7e-a764-2319a17dbfee" -intents -counterexamples -i henriksWorkspace.json









    



Namespace(createWorkspace=False, deleteWorkspace=False, fullWorkspace=False, getWorkspace=False, inFile='henriksWorkspace.json', listWorkspaces=False, outFile=None, updateWorkspace=True, workspaceID='f5db2447-55dd-4c7e-a764-2319a17dbfee', wsCounterexamples=True, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=True, wsLang=None, wsMetadata=False, wsName=None)
Workspace updated - new workspace
{
  "updated": "2017-03-28T09:03:32.121Z", 
  "description": "Test for my blog", 
  "language": "de", 
  "created": "2017-03-28T09:00:08.181Z", 
  "workspace_id": "f5db2447-55dd-4c7e-a764-2319a17dbfee", 
  "name": "Henrik renamed it", 
  "metadata": {
    "runtime_version": null
  }
}

A workspace can also be deleted. Use with care...



In [12]:

    
%%sh
python wctool.py -d -id "f5db2447-55dd-4c7e-a764-2319a17dbfee"









    



Namespace(createWorkspace=False, deleteWorkspace=True, fullWorkspace=False, getWorkspace=False, inFile=None, listWorkspaces=False, outFile=None, updateWorkspace=False, workspaceID='f5db2447-55dd-4c7e-a764-2319a17dbfee', wsCounterexamples=False, wsDescription=None, wsDialogNodes=False, wsEntities=False, wsIntents=False, wsLang=None, wsMetadata=False, wsName=None)
Workspace deleted

Use the logs option to obtain dialog logs. Using the -filter option you can pass a filter string (see README.md).



In [3]:

    
%%sh
python wctool.py -logs -id "09969794-a510-4eab-95f3-b482d94a7ac6" -filter "request.input.text:Hello"









    



{
  "pagination": {}, 
  "logs": [
    {
      "log_id": "bcd12227-02af-4381-b703-b5ba2d389e2c", 
      "response_timestamp": "2017-07-03T12:58:22.446Z", 
      "request": {
        "input": {
          "text": "Hello"
        }, 
        "alternate_intents": "true", 
        "context": {}
      }, 
      "response": {
        "entities": [], 
        "intents": [
          {
            "confidence": 0.11482968330383302, 
            "intent": "Display"
          }
        ], 
        "output": {
          "text": [
            "Ich habe Sie nicht verstanden. Bitte formulieren Sie Ihre Aussage neu."
          ], 
          "log_messages": [], 
          "nodes_visited": [
            "Andernfalls"
          ]
        }, 
        "context": {
          "conversation_id": "b6b449c0-76cc-46cc-901f-ae2c89becf19", 
          "system": {
            "dialog_stack": [
              {
                "dialog_node": "root"
              }
            ], 
            "dialog_request_counter": 1, 
            "dialog_turn_counter": 1, 
            "branch_exited": true, 
            "_node_output_map": {
              "Andernfalls": [
                0
              ]
            }, 
            "branch_exited_reason": "completed"
          }
        }, 
        "input": {
          "text": "Hello"
        }
      }, 
      "request_timestamp": "2017-07-03T12:58:22.404Z"
    }
  ]
}

A powerful option is -dialog. It allows to testdrive a dialog:



In [5]:

    
%%sh
python wctool.py -dialog -id "09969794-a510-4eab-95f3-b482d94a7ac6"









    



Starting a conversation, stop by Ctrl+C or saying 'bye'
======================================================

Please enter your input message:






    



Traceback (most recent call last):
  File "wctool.py", line 217, in <module>
    converse(parms.workspaceID)
  File "wctool.py", line 157, in converse
    minput = raw_input("\nPlease enter your input message:\n")
EOFError: EOF when reading a line

The above shows the beginning of a dialog. It is interactive and can be aborted (stopped) by either using Ctrl+C or typing "bye" as a input message.



In [ ]: