Configure GuardrailsColangColang Usage Examples

Extract User-provided Values

View as Markdown

This guide teaches you how to extract user-provided values (for example, a name, a date, a query) from a user utterance and store them in context variables. You can then use these values in bot responses or follow-up logic.

Overview

In Colang 2.0, you use Natural Language Descriptions (NLD) with the generation operator (...) to extract values. The NLD is placed inline after the ... operator:

$variable_name = ..."Instructions on how to extract the value."

The NLD together with the variable name is interpreted by the LLM directly. Be specific about the format and type you expect.

... is not a placeholder; it is the actual syntax (the generation operator).

Single Values

You can extract single values from user input:

import core
import llm
flow main
  activate llm continuation
  user provided name
  $name = ..."Extract the name of the user. Return the name as a single string."
  bot say "Hello, {$name}!"
flow user provided name
  user said "my name is" or user said "I am" or user said "call me"

Lists of Values

You can instruct the LLM to extract a list of values:

import core
import llm
flow main
  activate llm continuation
  user requested add items to cart
  $item_list = ..."Generate a list of the menu items that the user requested to be added to the cart, e.g. ['french fries', 'double protein burger', 'lemonade']. If user specifies no menu items, return an empty list []."
  # Process the items
  bot say "Adding {$item_list} to your cart."
flow user requested add items to cart
  user said "add to cart"
    or user said "I want to order"
    or user said "can I get"

Multiple Values

You can extract values for multiple variables from the same user input:

import core
import llm
flow main
  activate llm continuation
  user requested book flight
  $origin_city = ..."Extract the origin city from the user's request. If not specified, return 'unknown'."
  $destination_city = ..."Extract the destination city from the user's request. If not specified, return 'unknown'."
  bot say "Booking flight from {$origin_city} to {$destination_city}."
flow user requested book flight
  user said "I want to book a flight"
    or user said "I want to fly"
    or user said "I need a flight"

Contextual Queries

This mechanism can enable contextual queries. For example, to answer math questions using Wolfram Alpha with follow-up context:

Example conversation:

user: "What is the largest prime factor for 1024?"
bot: "The largest prime factor is 2."
user: "And its square root?"
bot: "The square root for 1024 is 32"
import core
import llm
flow main
  activate llm continuation
  user asked math question
  $math_query = ..."Extract the math question from the user's input. Include any contextual references from the conversation."
  $result = await WolframAlphaAction(query=$math_query)
  bot say $result
flow user asked math question
  user said "what is"
    or user said "calculate"
    or user said "and its"

Best Practices

Be specific in your NLDs:

# Good - specific format and fallback
$user_name = ..."Return the user name as a single string between quotes. If no user name is available, return 'friend'."
# Good - specific list format
$items = ..."Return the items as a Python list, e.g. ['item1', 'item2']. Return [] if no items found."
# Avoid - too vague
$value = ..."Get the value."

Use variables in NLDs for context:

$order_info = ..."Extract the order details."
$summary = ..."Provide a brief summary of the current order. Order Information: '{$order_info}'"

Key Differences

FeatureColang 2.0Colang 1.0
Instruction placementInline after ...Comment above assignment
Syntax$var = ..."instruction"# instruction
$var = ...
String interpolation{$var} in stringsContext variable access
Flow definitionflow namedefine flow
Action executionawait ActionName()execute action_name()