Klu Actions

Actions are the core of Klu and working with Actions will be the bulk of your development work. Klu Actions encapsulate everything needed to run the same prompt generation at scale. This section provides examples of common Action interactions, as well as detailed API information.

Klu Actions power content generation using dynamic variables, business operations workflows, content analysis and summarization, internal context-based question answering, customer feedback analysis, sentiment or intent analysis, and topic and category classification, and more. Klu unlocks your imagination.

Action model

Actions need an input to run the generation. Depending on your Action, your input is either a string, or key-value pairs with variable name as the key and variable input as the value. Actions return a response with the generated text, however you can also stream the response or run the Action asynchronously. Actions also return a feedback URL that you can use to provide Feedback on the generation.

Streamed Actions return a stream URL that you can use to stream the response token-by-token.

Asynchronous Actions return a Generation GUID that you can use to retrieve the generated output.


Run Action & Variables

Here are common examples for how to use Klu Actions in your applications.

Run Action

Get your Action GUID from Klu Studio. You can also use the API to list your Actions.

Run Action

POST
/v1/actions
from klu import Klu
klu = Klu('YOUR_API_KEY')

result = await klu.actions.prompt(
  '6942f034-6872-4eed-9bb3-7e3bf18e5743', 
  'Write a sentence about Machine Learning.'
)
print(result)

Dynamic Variables

Klu Actions support {{dynamic variables}} that you can use in prompt generations.

Here is an example prompt template with variables:

Prompt Template

======
System Message: You are a helpful writing assistant.
====== 
Review this content and make the following changes:
{{task}}
If no changes, do not output anything and explain why. If there are changes,
explain in a table what you changed and why.
======
{{content}}

Run Action with Variables

POST
/v1/actions
from klu import Klu

klu = Klu('YOUR_API_KEY')
result = klu.actions.prompt(action='6942f034-6872-4eed-9bb3-7e3bf18e5743',
    input={
      "topic": "Machine Learning.",
      "task": "Correct any grammar or spelling mistakes."
    })

Environments & Cache

Klu supports Production, Staging, Preview, and custom environment names. Deploy your Action to a different environment and specify the environment when running the Action. Seen here with response cache enabled.

Action Environments

POST
/v1/actions
from klu import Klu
klu = Klu('YOUR_API_KEY')

result = await klu.actions.prompt(
  '6942f034-6872-4eed-9bb3-7e3bf18e5743', 
  'Write a sentence about Machine Learning.', 
  environment='Preview'
)
print(result)

Associate Users

Action generations provide an optional capability to link a generation with a unique external identifier extUserId – this could be an organization, a username, an email, or any other unique reference. This allows you to connect the generated content with your own systems for improved tracking and management.

Associate External User ID

POST
/v1/actions
from klu import Klu
klu = Klu('YOUR_API_KEY')

result = await klu.actions.prompt(
  '6942f034-6872-4eed-9bb3-7e3bf18e5743', 
  'Write a sentence about Machine Learning.', 
  extUserId='[email protected]',
)
print(result)

Save User Feedback

Klu Actions return a Feedback URL feedback_url containing the data point GUID that you can use to provide Feedback on the generation. The SDK only needs the GUID to save the feedback. Note: for ratings, the SDK accepts Negative and Positive ratings, but direct API calls use 1 and 2 for negative and positive, respectively .

Save Feedback

POST
/v1/feedback
from klu import Klu
klu = Klu('YOUR_API_KEY')

result = await klu.feedback.log(
  guid="69420c8bz-22z2-446d-af2e-e525b39dafda",
  correction="Machine Learning, a category of artificial intelligence, is a process where computers analyze data to learn patterns or behaviors, equipping them with the capability to make decisions independently, without someone having to write specific instructions for each task.",
  rating="Positive",
  issue="Vague")
print(result)

Context w/ Filtering

Utilize the filter parameter to narrow down to specific Context documents by matching input with the document's metadata. Klu enables you to filter by one or many document attributes. This is beneficial when you want to reuse an Action across different documents in the same Context library, such as documents belonging to different tenants, users, or products. Klu Studio automatically creates file-based metadata for each document or URL. You can also add custom metadata to each document via the API.

Run Action with Filtered Context

POST
/v1/actions
from klu import Klu
klu = Klu('YOUR_TOKEN')

result = await klu.actions.prompt(
  action="6942f034-6872-4eed-9bb3-7e3bf18e5743",
  metadata_filter={
    "user-id": "00379-28829999a",
    "tenant-id": "aa882-bb873"
  },
  input={
    "topic": "Machine Learning.",
    "task": "Write a help center article"
  })
print(result)

Sessions & Memory

Klu Actions support session memory that you can use to store and retrieve data across multiple prompt generations. This is useful for conversational experiences like copilots or coaches, where you want to retain the context of the conversation. This is a 2-step process: first create a new session, then use the session GUID in subsequent Action generations.

You can also specify an optional external user ID extUserId when creating a session for organizing and retrieving sessions later. This external user ID can then be used to connect the activity across multiple generations and sessions in other analytics or observability systems.

Create Session

POST
/v1/sessions
from klu import Klu
klu = Klu('YOUR_TOKEN')

result = await klu.sessions.create(
  action="6942f034-6872-4eed-9bb3-7e3bf18e5743",
  extUserId="[email protected]",
  name="A conversation about X.com with Elon Musk")
print(result)

Run Action in Session

POST
/v1/actions
from klu import Klu

klu = Klu('YOUR_TOKEN')

result = await klu.actions.prompt(
  action="6942f034-6872-4eed-9bb3-7e3bf18e5743",
  input={
    "topic": "Machine Learning.",
    "task": "Help me build my first ML feature"
  },
  session="3b7c1d28-8f21-4b6a-a9d2-1a7b9c2d6a57")

print(result)

A/B Experiments

Klu Experiments allow for A/B testing of two Actions via one endpoint. This is useful for comparing the performance of two Actions on the same input, but with different configurations (Prompt, Model Provider, Model, Model Config, Context, etc). If the Actions have two different sets of variables you must provide all inputs in the request.

Run A/B Generation

POST
/v1/experiments
from klu import Klu

klu = Klu('YOUR_TOKEN')

result = await klu.experiments.prompt(
  experiment_guid="dbcc25d4-722c-433d-a1ea-548250badf8d",
  input={
    "topic": "Machine Learning.",
    "task": "Help me build my first ML feature"
  })
print(result)

Multi-modal Capabilities

Klu Actions are compatible with GPT-4V and other multi-modal models. They can process images either as Base64 or from a URL that is publicly accessible, which are then utilized in the model generation.

Multi-modal Actions with GPT-4V

POST
/v1/actions
curl --location 'https://api.klu.ai/v1/actions/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{ 
    "action": "6942f034-6872-4eed-9bb3-7e3bf18e5743",
    "input":  "",
    "messages": [
      {
        "role": "user",
        "content": "What is in this image?",
        "files": [
          "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
        ]
      }
    ]
  }'

POST/v1/actions

Run Action

Detailed documentation for the Actions endpoint. The Action GUID and input is required to run an Action, all other attributes are optional.

Required attributes

  • Name
    action
    Type
    string
    Description

    Action GUID to run.

  • Name
    input
    Type
    string / object
    Description

    Input string (no variables) or key-value variable object to pass to Action.

Optional attributes

  • Name
    streaming
    Type
    boolean
    Description

    Enable streaming response.

  • Name
    async_mode
    Type
    boolean
    Description

    Enable async response.

  • Name
    cache
    Type
    boolean
    Description

    Use cached response if available.

  • Name
    session
    Type
    string
    Description

    Assign a session to the Action generation.

  • Name
    metadata_filter
    Type
    object
    Description

    Filter by Metadata to retrieve specific Context used by Action.

  • Name
    experiment
    Type
    string
    Description

    Pass the experiment GUID to run the action in a specific experiment. Only recommended if you are manually controlling experiment traffic.

Request

GET
/v1/actions
from klu import Klu

klu = Klu('YOUR_API_KEY')
result = klu.actions.prompt(action='6942f034-6872-4eed-9bb3-7e3bf18e5743',
    input={ "Write a sentence about Machine Learning."
    })

Response

{
"msg":"Machine learning is a branch of artificial intelligence that allows computer systems to learn and improve from experience without being explicitly programmed.",
"feedback_url":"https://api.klu.ai/v1/data/123e4567-e89b-12d3-a456-426655440000",
"streaming":false
}