stackspot 1.0.0

Stackspot API bindings for Python

from stackspot.stackspot_dict_types import QuickCommandPollExecutionOpts

Stackspot

Stackspot API bindings for Python.

---

Content

• Installation
• Usage
  • ⚙ Configuration
  • 🌐 Using behind proxy
• Methods
  • ✨ AI
    • AI - KS - Create a new Knowledge Source
    • AI - KS - Upload new file to a Knowledge Source
    • AI - KS - Remove files from a Knowledge Source
    • AI - Quick Command - Create a new execution
    • AI - Quick Command - Get execution
    • AI - Quick Command - Poll execution until it's done
  • 🗝️ Auth
    • Auth - Get the access token
• License

---

Installation

To install, simply add the package using pip:

pip install stackspot

---

Usage

You can start using the global instance:

from stackspot import Stackspot

# By default, the global instance will configure itself using the environment variables:
# - STACKSPOT_CLIENT_ID
# - STACKSPOT_CLIENT_SECRET
# - STACKSPOT_REALM

# Creating a new 'Knowledge Source' for example:
Stackspot.instance().ai.ks.create_ks('new-ks-test-api-2', 'New KS test', 'This is a test KS', 'CUSTOM')

---

⚙ Configuration

You can configure the global instance:

from stackspot import Stackspot

# Using the 'config(opts)' method, to update the all the settings at once:
Stackspot.instance().config({
	'client_id': '...',
	'client_secret': '...',
	'realm': '...',
})



# Or update them individually:
Stackspot.instance() \
	.set_client_id('...') \
	.set_client_secret('...')

If you want to create your own Stackspot instance, you can either pass the settings on the constructor, use the 'config' method, or configure individual properties as well:

from stackspot import Stackspot

# Creating a new stackspot instance (instead of using the 'global' one):
my_instance = Stackspot({
	'client_id': '...',
	'client_secret': '...',
	'realm': '...'
})


# If you want, it's possible to call the 'config(opts)' method of this instance as well to update the settings:
my_instance.config({ ... })


# Or configure properties individually:
my_instance.set_client_id('...')

---

🌐 Using behind proxy

Internally it uses the requests module to make requests, so you can just provide the standard HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables.

See more: Proxies with 'requests' module.

---

Methods

Here are all the available methods of this package:

✨ AI

All the AI related functions are bellow Stackspot.instance().ai namespace.

AI - KS - Create a new Knowledge Source

To create a new Knowledge Source, just run:

from stackspot import Stackspot

Stackspot.instance().ai.ks.create_ks('my-new-ks', 'My new KS', 'A test KS', 'CUSTOM')

For more info about the KS creation, check out the official documentation: https://ai.stackspot.com/docs/knowledge-source/create-knowledge-source

AI - KS - Upload new file to a Knowledge Source

You can add or update existing objects inside a Knowledge Source:

from stackspot import Stackspot

# This creates/updates a KS object named 'test.txt' containing 'Hello World' text:
Stackspot.instance().ai.ks.upload_ks_object('my-ks-slug', 'test.txt', 'Hello World')

AI - KS - Remove files from a Knowledge Source

To batch remove files from a Knowledge Source:

from stackspot import Stackspot

# This removes ALL objects from the KS:
Stackspot.instance().ai.ks.batch_remove_ks_objects('my-ks-slug', 'ALL')

from stackspot import Stackspot

# This removes only the STANDALONE objects from the KS:
Stackspot.instance().ai.ks.batch_remove_ks_objects('my-ks-slug', 'STANDALONE')

from stackspot import Stackspot

# This removes only the UPLOADED objects from the KS:
Stackspot.instance().ai.ks.batch_remove_ks_objects('my-ks-slug', 'UPLOADED')

AI - Quick Command - Create a new execution

To manually create a new Quick Command execution:

from stackspot import Stackspot

execution_id = Stackspot.instance().ai.quick_command.create_execution('my-quick-command-slug', 'Input for this execution')
# Return example: "06J85YZZ5HVO1XXCKKR4TJ16N2"

AI - Quick Command - Get execution

After creating a new Quick Command execution, you may want to check it to see if it has completed successfully, and get its result:

from stackspot import Stackspot

execution = Stackspot.instance().ai.quick_command.get_execution('06J85YZZ5HVO1XXCKKR4TJ16N2')

print('status: ' + execution['progress']['status'])

Obs.: Note that, at the time this call have been made, the execution may not yet be done, so you have to write some polling logic, or use the 'poll_execution' method.

AI - Quick Command - Poll execution until it's done

It can be cumbersome to write the logic to poll a Quick Command execution after its creation to check if it's done. This library gets you covered on that:

from stackspot import Stackspot

# Just create a new execution:
execution_id = Stackspot.instance().ai.quick_command.create_execution('my-quick-command-slug', 'Input for this execution')

# And call the poll method:
# This will check the execution status until it's done and then return the execution object (the 'opts' argument is optional):
execution = Stackspot.instance().ai.quick_command.poll_execution(execution_id, { 'delay': 0.5, 'on_callback_response': lambda e: print('status: ' + e['progress']['status']) })

print('final status: ' + execution['progress']['status']) # 'COMPLETED'
print('result: ' + execution['result']) # The Quick Command result.

---

🗝️ Auth

The library methods already handles the authentication process, but you can access the auth methods by yourself using the Stackspot.instance().auth namespace:

Auth - Get the access token

This will get the cached token, or fetch a new one if they aren't valid anymore:

from stackspot import Stackspot

Stackspot.instance().auth.get_access_token()

Obs.: To configure the authentication properties like client_id, client_secret, and realm, head back to the Usage section.

---

License

MIT