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.

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:

======
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}}

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.

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.

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 .

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.

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.

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)

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.

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.

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"
        ]
      }
    ]
  }'

Formatted prompt

If you ever need to see the fully formatted action prompt, you can use the gateway_prompt endpoint to get the fully formatted prompt.

from klu import Klu

klu = Klu('YOUR_TOKEN')

result = await klu.actions.get_action_prompt(
  experiment_guid="dbcc25d4-722c-433d-a1ea-548250badf8d",
  input={
    "question": "What is the capital of France?"
  })
print(result)

Run Action

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."
    })

{
"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
}