kbot_client 2.0.7
Client for Konverso Kbot.
License: MIT
Requires Python: <4.0,>=3.12

# kbot-py-client #
This package contains utilities which you may use to easily interact with Konverso Kbot application. 
 
In particular, you may:

* Invoke some of the APIs to view / update / create Kbot configuration objects such as Intents, Message, etc.
* Collect metrics showing how the bot is performing.
* Create a Conversation and interact with it, sending message and getting responses

# See also #

## Access Konverso Support
You may contact us: 

* For any commercial inquiry: contact@konverso.ai
* For support: https://konverso.atlassian.net/servicedesk/customer/portals
 
## License
This client code is open source such that you can freely view it, modify it, create your own version.
We of course appreciate any contribution and sharing of enhancements made.

# Installation #

You may use pip3 to install the software on your Kbot instance: 

    pip3 install kbot-py-client

Alternatively, you can invoke a more explicity pip installation request, with the URL path: 

	pip3 install -e git+https://github.com/konverso-ai/kbot-py-client.git#egg=kbot-py-client

# Usage #

You would typically first need to login and then invoke some of the API wrapped methods.

## Login ##

	import json
	
	from kbot_client import Client

### Using user / password ###

	cli = Client("mybot.konverso.ai")
	cli.login("myuser", "mysecretpassword")

The API Key may be created for a given user, with relevant permissions, from the Configuration / Users & Roles / Users / Accounts panel. Create an account of type "Local"

### Using and api key ###

	cli = Client("mybot.konverso.ai", api_key="xxxxxxxxxxxxxxxxxxx")

The API Key may be created for a given user, with relevant permissions, from the Configuration / Users & Roles / Users / Accounts panel. Create an account of type "API Key"

## Collect metrics
Once authenticated, you can for example retrieve useful usage metrics, these can be used by a Monitoring application or for some business intelligence rendering: 

	metrics = cli.metric().json()
	print("Collected metrics:")
	print(json.dumps(metrics, indent=4))

## Invoke a Workflow and retrieve result
This is the most powerful mechanism, that let you invoke any business and processing logic in a workflow, leveraging all the capabilities of our platform, and retrieve the result

    r = client.request("post",
        "workflow/execute",
        {
            "name": "Test API Workflow",
            "keywords": {
                "var1": "abc"
            },
            "result": ["response"]
        }
    )
    print(r.json())

## Invoke a search
You may invoke a search on any of the configured Search Contexts
Note the search context UUID passed in the URL, which you may retrieve from our Search Context portal. 

    r = client.request("post", "searchcontext/234923-235-sjdhfs-kdjf/search",
        {
            "sentence": "how to create a classifier",
            "num_results": 20,
            #"variables": {'kbs': {'value': ['Confluence_Security_KSEC']}}
        }
    )


## Retrieve object details
You may retrieve list of defined objects. Note that only objects visibled to the logged in users will be returned.

Here is a sample code that simply checks for a few objects existance: 

## Get list of objects and check if object with name is present in response
	for unit, name in (('intention' ,'Create ticket'),
	                   ('knowledge_base', 'faq'),
	                   ('workflow', 'Transfer to Agent')):
    	print(f"Get list of '{unit}'")
    	objs = cli.unit(unit)
    	if objs:
        	# Create dict with
        	# - key : object name
        	# - value : object json data
        	data = {obj['name']: obj for obj in objs}
        	if name in data:
            	print(f"'{name}' is present")
        	else:
            	print(f"'{name}' is not present")
    	else:
        	print("Get no data")
		
## Conversation test
In this example, we create a conversation between the logged in user and the bot and then sends a sentence, and check if we get some expected text in the response. This could for example be the basis of automated testing of the bot

    	r = cli.conversation(username='bot')
    	if r.status_code == 201:
    	    cid = r.json().get('id')
    	    print("Created conversation with id '%s'" %(cid,))

    	    response = cli.message(cid, 'hello')

    	    # Process bot response
    	    if response:
    	        for resp in response:
    	            for message in resp.get('message', []):
    	                responses.append(message.get('value', '')) # dict {message type: message value}
    	                resp_message = '\n'.join(responses)
                        print("Received response: ", resp_message)
                        if 'I am kbot' in resp_message:
                            print("Excepted response found")
                            break
                    else:
                        print("Did not receive the expected response")
    	    else:
    	        print("Did not receive any response")
    	else:
    	    print("Could not create conversation due to: ", r.text)
	

## Command line chatbot
The following sample is a complete example you may use to kick off a chat for a given user with the kbot chatbot.
Here there is no user authentication, but impersonation instead, and user/lookup. This example is a good starting point if you are looking at implementing your own chat interface on top of Kbot.
```
# Create a session using an API key with strong privileges
cli = Client("mytenant.konverso.ai", api_key="34exxxxxxxxxxxxxa7bfb6aeb")
 
# Lookup create the user in kbot
response = cli.post("user/lookup_create", data={
    "user_name": user_email,
    "account_name": user_email,
    "account_type": "local",
    "external_auth": "nice-in-connect",
})
response.raise_for_status()
 
cli.impersonate(user_email, 'local', 'nice-in-connect') #, application_uuid="b0d91200-833f-466c-b5fd-1b0402cc3a36")
 
# Start the client (loop… ends with Ctrl D)
AsyncChatClient(cli)
```

## Uploading one file to kbot

### Prerequisites
* A local file that you wish to send
* The UUID of the folder that will receive the files you want to upload

### Code sample
```
        current_top_folder = "uuid-of-a-folder"
        filepath = "/tmp/test.pdf"
        filename = os.path.basename(filepath)
        
        # Upload to remote filemanager
        with open(filepath, "rb") as fd:
            files = {
                        "upload_files": fd
                    }
            params= {
                        "override": False
                    }
            data = {
                        "folder": current_top_folder,
                        "name": file_name,
                    }
            response = self.client.post_file("attachment",
                                                     data=data,
                                                     params=params,
                                                     files=files)
```

## Uploading a batch of files to the file manager

### Prerequisites

* An API key
* The UUID of the folder that will receive the files you want to upload

### Code sample
In this example, we simply upload the content of a directory to a folder in the file manager.
```
        from kbot_client import Client
        from kbot_client.folder_sync import FolderSync

        client = Client("mybot.konverso.ai", api_key="17ebXXXXXXXXXXXXXXXXXXXXX")

        syncer = FolderSync(client)
        syncer.sync("/tmp/my_source_folder/", "1831f-XXXXXXXXXXXXXXXXXXXXXXX")
        print("Syncing is done :)")
```

## A command line chatbot
We provide a sample command line chatbot, available in Sync or Async mode

### Code sample
In this example, we simply initialize a chatbot client after creating a relevant User and Impersonating to it. 
This is a good example of implementation of a custom Client for the Kbot product.

```
# Create your client
import json
from kbot_client import Client
from kbot_client.chat_client import AsyncChatClient, SyncChatClient

cli = Client("mytenant.konverso.ai", api_key="mykey")

external_auth = "cmd-line-chatbot"
user_email = "a-user-name"
assistant = "225d9647-0b41-473d-b097-ef4be363958a"

# Create your target user
response = cli.post("user/lookup_create", data={
    "user_name": user_email,
    "account_name": user_email,
    "account_type": "local",
    "external_auth": external_auth,
})
response.raise_for_status()

# Impersonate accordingly
cli.impersonate(user_email, 'local', external_auth)

# Start the chat
AsyncChatClient(cli, assistant=assistant, convert_html_to_text=True)

```