Python API

You can view the Python Chai package on GitHub.

Authenticating

You must authenticate using your developer id and key before various operations are possible.

>>> from chai_py.auth import set_auth

>>> set_auth('my_developer_uid', 'my_developer_key')

You can create a key through the developer portal

Defining a bot

A bot must inherit from Chai base bot and define an on_message method which responds to a user update with a string response.

For example a chatbot which just just copies what the users says looks like

>>> from chai_py import ChaiBot, Update

>>> class EchoBot(ChaiBot):
       """ A simple example bot. """

       def setup(self):
           self.name = 'Echo'

       async def on_message(self, update: Update):
           return f"{self.name}: {update.latest_message.text}"

You should use a setup method to run code on bot initialisation, you cannot override the __init__ method of a bot.

Bot state

A bot instance and its state exists for the lifetime of a single conversation with a single user.

Lets say you incremented a counter self.num_messages every time a user messaged the bot. If one user sent a message to the bot then the counter is incremented for that conversation but not for any other users or for another conversation the same user was having with the same bot.

State persists even if the app is closed, as long as the user continues with the same conversation later.

Sending an initial bot message

A bot is automatically sent the string self.FIRST_MESSAGE_STRING when a new conversation begins. This will allow you to customise the initial greeting message.

>>> class DummyBot(ChaiBot):

    async def on_message(self, update):
        if update.latest_message.text == self.FIRST_MESSAGE_STRING:
            response = 'Welcome to the conversation!'
        else:
            response = 'hello again'
        return response

Including an image in the bot response

The bot response accepts markdown and so you can include an image like ![image_name](http://image-url/file.jpg)

Packaging your bot

A bot class once defined must be packaged before it can be uploaded

>>> from chai_py import package, Metadata

>>> package(
        Metadata(
            name="Echo Bot",
            image_url='http://image-url/file.png',
            description="Just a simple example.",
            developer_uid='test123',
            input_class=EchoBot,
            memory=256
        ),
        requirements=["transformers[torch]"],
    )

The bot metadata lets you configure the bot and accepts the arguments

Package also accepts a requirements argument where you can configure python dependencies of the bot.

The result of calling package is to create a file _package.zip in the current directory which can then be uploaded.

Uploading a bot

In order to upload a bot you pass a path to the package and a unique bot ID which must begin with _bot

>>> from from chai_py import upload_and_deploy

>>> bot_uid = upload_and_deploy('_package.zip', bot_uid=None)

If you do not provide a bot ID then one will be automatically generated and written to a file _deployment which you will be prompted to reuse the next time you upload.

After uploading a bot you can poll for it to finish uploading.

>>> from chai_py import wait_for_deployment

>>> wait_for_deployment(bot_uid)

Viewing or sharing your bot

In order to interact with or share your deployed plot you can produce a QR code from the bot ID and scan this with your phone

>>> from chai_py.deployment import advertise_deployed_bot

>>> advertise_deployed_bot(bot_uid)

You will be promopted to either view your QR code directly or save it to a file.

Querying for your deployed bots

You can retrieve a list of the bots you have deployed by calling

>>> from chai_py import deployed

>>> my_bots = deployed.get_bots()

This is useful to find you deployed bot IDs and whether they are visible to users of the app.

>>> print(my_bots[0])

DeployedBot(bot_uid='_bot_example', name='Echo Bot', developer_uid='abc123', status='inactive')

Making a deployed bot visible to other users

By default an uploaded bot is only visible using a QR code. If you want it to be discoverable on the app you must activate it first using the bot ID.

>>> from chai_py import deployed

>>> deployed.activate_bot(bot_uid)

In order to prevent your bot from being dicovered by users you can call

>>> deployed.deactivate_bot(bot_uid)

Currently users must be whitelisted to be able to activate their bot, speak to us over WhatsApp or Discord and we can give you permission.

Debugging a bot with errors

If your bot is failing to respond it may be that it has an error. You can retrieve the logs in order to investigate further

>>> from chai_py import cloud_logs
>>> logs = cloud_logs.get_logs(bot_uid)
>>> cloud_logs.display_logs(logs)