Introducing Variables and Natural Language Description

Introduction

Enabling LLM continuation rails made our chatbot more adaptable by letting the language model handle anything not covered by your rules. However, this approach has limits: you can’t directly control the prompts sent to the LLM or how it gathers and formats information. For more advanced, context-aware bots, you need greater control. That’s where variables and Natural Language Description (NLD) come in—they let you store and manipulate data, craft precise prompts, and guide the LLM’s output to fit your needs. In this lesson, we’ll cover how to use variables in Colang 2.0 to store and manage data, and how to leverage Natural Language Description (NLD) to craft precise prompts and control LLM output. You’ll learn about variable assignment, types, and mutability, as well as best practices for extracting and validating structured information from the LLM.

Variables in Colang 2.0: Assignment, Types, and Mutability

Colang 2.0 allows you to use variables much like Python. Variables start with a $ and are assigned values using =. The variable’s type is inferred from the assigned value. Immutable types (strings, integers, floats) are copied when assigned to another variable. Mutable types (lists, sets, dictionaries) are referenced, so changes to one variable affect all references. Examples: text$greeting = "Hello there" # String $year = 2023 # Integer $temperature = 22.5 # Float $colors = ["red", "green", "blue"] # List of strings $prime_numbers = [2, 3, 5, 7] # List of integers $unique_ids = {101, 102, 103} # Set of integers $user_profile = {"name": "Alex", "age": 30} # Dictionary Mutability in Practice: text$tasks_today = ["email", "meeting"] $my_tasks = $tasks_today $my_tasks.append("review") # Both $tasks_today and $my_tasks are now ["email", "meeting", "review"] $score = 15 $backup_score = $score $backup_score = 20 # $score remains 15, $backup_score is 20 Variables help you capture user input, maintain state, and transfer data between flows. Understanding mutability helps prevent unexpected changes.

Flow Parameters

Flows in Colang 2.0 can accept parameters, allowing you to pass data into a flow when you activate it. Parameters are defined in the flow header using the $ prefix. This makes flows reusable and flexible. Example: textflow main $user_name = "Jack" greet_user $user_name flow greet_user $name bot say "Hello, {$name}!" In this example, the greet_user flow takes a $name parameter. When you call the flow from main, you pass in the value of $user_name. Inside the flow, you can use $name just like any other variable. Key Points: Parameters are only accessible within the flow where they are defined. You can pass multiple parameters by listing them in the flow header: flow example $param1 $param2. When activating a flow, provide arguments in the same order as the parameters. Using parameters helps you write modular, maintainable Colang code by avoiding unnecessary global variables and making flows more general-purpose.

Global Variables

By default, variables defined inside a flow have local scope and are not accessible from other flows. To share information between flows, declare a variable as global using the global keyword at the top of each flow that needs access. Example: text flow main global $counter $counter = 0 activate increment_flow flow increment_flow global $counter $counter = $counter + 1 You must declare the variable as global in every flow that needs to access or modify it. Otherwise, a local variable with the same name will hide the global one. Use global variables sparingly, as overuse can indicate a non-optimal Colang design.

Natural Language Description (NLD) and the Generation Operator

NLD lets you use everyday language to tell the LLM what you want. The generation operator ... sends your prompt to the LLM and stores the result in a variable. You don’t need to import anything to use the generation operator in Colang 2.0. It’s built into the language and available by default. For example, you can ask: text$capital_city = ..."What is the capital of France? Respond with just the city name." Here, the prompt inside the quotes is sent to the LLM, and its response (e.g., Paris) is stored in the $capital_city variable. You can ask the LLM to format and extract structured data: text$shopping_list = ..."List the items the user wants to buy as an array, e.g. ['milk', 'bread']" The LLM returns a list you can use in your logic. You can also reference variables in your prompts with curly braces: text$summary = ..."Summarize the following shopping list: '{$shopping_list}'" The LLM sees the actual list and generates a summary. Best Practices: Specify the format you want (e.g., “Return a list of items in JSON array format”). Use {$variable} to reference variables in prompts. Check the output with helper functions like is_str() or is_list().

Defining Flows with NLD Docstrings

Important Notes and Troubleshooting NLD

NLD may not always yield the format you want. If the LLM’s output isn’t as expected, clarify your prompt (e.g., “Return a string in single quotes”). Always validate outputs with type-checking functions to ensure correct data types. Be precise in your instructions, especially when you need structured data or a specific response format. Use {$var} inside prompts sent to the LLM with the generation operator (...). This inserts the value of the variable directly into the prompt string. Use {{ var }} inside docstrings at the top of a flow. When the docstring is used as an LLM prompt (e.g., with a standalone ...), {{ var }} is replaced with the value of the variable. This is useful for templating the docstring prompt with dynamic values.

Summary

Variables and NLD in Colang 2.0 give you fine-grained control over data and LLM-driven actions. You can store and manipulate information, extract structured responses, and guide the LLM to generate the exact output your application needs. This enables you to build more capable, adaptable bots. In the next practice, you’ll apply these features to create advanced conversational flows.