Skip to main content

​
Core Language Constructs

Based is built around a set of specialized constructs designed specifically for conversational AI workflows. These constructs provide a high-level abstraction that makes it easy to build complex interactions without getting lost in implementation details.

​
The say Function

The say function generates a response from the AI to the user without expecting a reply. It’s typically used to provide information, instructions, or acknowledgments. Syntax: 
say(message, exact=False, model=None)
Parameters:
  • message (string): The content to be processed and presented to the user
  • exact (boolean, optional): Controls how the message is processed
    • True: Outputs exactly what’s provided in the message parameter, verbatim
    • False (default): Allows the AI to rephrase the message while maintaining its meaning
  • model (string, optional): Specifies which AI model to use for processing the message (when exact=False)
Return Value:
  • Returns the response text, which can be stored in a variable for later use or simply executed for its side effect
Example: 
# Greet the user with an exact message
say("Welcome to BookBot! I'm here to help you find and reserve books.", exact=True)

# Generate a dynamic welcome based on intent
say("Generate a friendly welcome for a user looking for book recommendations")

# Store the response for later use
intro = say("Introduce yourself as a helpful assistant", model="anthropic/claude-3.7-sonnet")

​
The loop, talk, and until Pattern

In Based, the loop, talk, and until constructs form an essential pattern that must be used together. This pattern creates interactive conversation flows that can repeat until specific conditions are met. The talk function is not meant to be used in isolation. Syntax: 
loop:
    response = talk(
        system_prompt,
        first_prompt=True,
        default_values={},
        info={}
    )
until "Description of the completion condition":
    # Validation code that determines if the condition is met
    # The loop continues until this code completes successfully
Parameters for talk:
  • system_prompt (string): Instruction or prompt that guides the conversation
  • first_prompt (boolean, optional): Controls conversation initiation
    • True (default): AI starts by sending the prompt message to the user
    • False: AI waits for the user to send a message first
  • default_values (dict, optional): Example values to structure expected responses
  • info (dict, optional): Additional context for the conversation
The Loop-Until Pattern:
  • The loop keyword begins a repeatable conversation block
  • The talk function within the loop handles the conversation exchange
  • The until clause specifies a condition (in natural language) under which the loop should end
  • The code block after until validates whether the condition has been met
    • If the condition is met (the code executes successfully), the loop exits
    • If the condition is not met, the loop repeats from the beginning
Example: 
loop:
    book_preference = talk(
        "What genre of books do you enjoy reading?",
        True,
        {"genre": "mystery", "format": "paperback"}
    )
until "User provides a valid book genre and format":
    preference_data = book_preference.ask(
        question="Extract the user's book genre and preferred format.",
        example={"genre": "mystery", "format": "paperback"}
    )

    # Validate the genre and format
    if preference_data["genre"] not in ["mystery", "sci-fi", "romance", "non-fiction"]:
        print("Invalid genre provided. Re-prompting...")
        continue

    if preference_data["format"] not in ["paperback", "hardcover", "e-book", "audiobook"]:
        print("Invalid format provided. Re-prompting...")
        continue

    # If we reach here, both genre and format are valid
    print("Valid preferences received!")

​
Data Processing Methods

Based provides powerful methods to transform and extract information from data objects. These methods can be applied to any data object, not just conversation responses.

​
The .ask Method

The .ask method extracts structured data from any data object, transforming unstructured content into well-formed data that can be used programmatically. This method can be used with API responses, conversation results, or any other data. Syntax: 
data_object.ask(question, example=None, schema=None, model=None)
Parameters:
  • question (string): Instruction for extracting specific information from the data
  • example (dict, optional): Example object showing the expected output format
  • schema (dict, optional): JSON schema defining the expected structure
  • model (string, optional): AI model to use for extraction
Return Value:
  • Returns structured data according to the example or schema provided
Example: 
# Extract structured book preferences from a conversation response
preferences = response.ask(
    question="Extract the user's preferred book genre, format, and any specific authors they mentioned.",
    example={
        "genre": "mystery",
        "format": "audiobook",
        "authors": ["Agatha Christie", "Arthur Conan Doyle"]
    }
)

# Use .ask on an API response
response = requests.get(
    url='https://bookstore-api.example.com/books',
    headers={'Authorization': 'Bearer ' + auth_token},
    params={'genre': 'mystery'}
)
api_results = response.json().ask(
    question="Extract the book titles, authors, and prices from the API response.",
    example={"books": [{"title": "The Mystery", "author": "A. Writer", "price": "$12.99"}]}
)