Elysia Documentation

Elysia tools can return or yield objects to the decision tree.

• Strings: When a tool yields or returns a string, it is treated as a direct response to the user (the agent's speech).
• Other Types (Result objects): Any other type (like a dictionary or list) is treated as a Result object and added to the tree's environment.
• Customizing Environment Objects: Yielding a dictionary allows you to control the keys added to the environment. Yielding a list of dictionaries adds multiple objects to the Result.

You can use an async generator to yield multiple items (e.g., a data dictionary for the environment and a string for the user response).

@tool
async def calculate_two_numbers(x: int, y: int):
    """
    This function calculates the sum, product, and difference of two numbers.
    """
    yield {
        "sum": x + y,
        "product": x * y,
        "difference": x - y,
    }
    yield f"I just performed some calculations on {x} and {y}."

The Decision Agent (run from the base_model) manages the execution of the decision tree by selecting tools or nodes for each step.

Core Components:

• Branches: Subcategories used to organize tools when many are available.
• Tools: Specific actions that perform tasks and add information to the Elysia environment.
• Environment: A shared state used by both the decision agent and tools to track retrieved or collected data.

Decision Agent Inputs:

• Tree Data: The current state of the process (see Tree Data).
• Tool Descriptions: Definitions of available actions.
• Branch Instructions: Guidance on how to choose between available tools within a specific branch.
• Metadata: Information including the current loop count and available future tools within a branch.

Decision Agent Outputs:

• The selected Tool to use.
• Inputs for the tool (if required).
• A flag indicating if the tree should end after this tool call (conditional on tool capability).
• A message update for the user.
• A flag indicating if the task is impossible based on current information.

The Environment is a persistent object used across all actions, tools, and decisions within an Elysia decision tree. It acts as a global store for information (like retrieved objects) that needs to be accessible across different tools and actions.

Data Structure

The environment is a nested dictionary structured as follows:

1. tool_name (str): The name of the tool that added the data.
2. name (str): A unique subkey associated with the specific result (e.g., a collection name).
3. List of Results: A list where each element is a dictionary containing:
   • objects (list[dict]): The actual data retrieved.
   • metadata (dict): Metadata shared among all objects in that specific result entry.

Automatic Assignment

When a Tool yields a Result object, Elysia automatically calls .add() on the environment. The Result.to_json() method is used to populate the objects and metadata fields under environment[tool_name][name]. If the tool_name and name already exist, the new result is appended to the existing list.

When running the tree function, the output provides both the conversational flow and the raw data retrieved from Weaviate.

Response String

The response variable is a single string that concatenates all assistant responses and decision-making outputs. For example:

# Example output
'I will now search for a science question... Here\'s a science question for you: "This organ removes excess glucose..."'

Retrieved Objects

The objects variable is a list of lists containing the dictionaries representing the objects found in Weaviate. Each dictionary includes the object's properties and metadata (like uuid and collection_name).

Example structure:

[
    [
        {
            'category': 'SCIENCE',
            'question': 'This organ removes excess glucose from the blood & stores it as glycogen',
            'answer': 'Liver',
            'uuid': 'b28ca48a-9a8d-417c-9ed1-e487132740ed',
            'collection_name': 'JeopardyQuestion',
            'chunk_spans': [],
            '_REF_ID': 'query_JeopardyQuestion_0_0'
        }
    ]
]

Tools can interact with the decision tree and frontend by yield-ing specific objects:

Status Updates

Yield any class inheriting from Update to send messages to the frontend/progress bar. A Status message is a common implementation:

yield Status("Processing data...")

Adding Results to Environment

Yield any class inheriting from Result to add objects to the tree's environment. This allows the LLM to 'see' the output and make subsequent decisions.

Result arguments:

• objects: A list of dictionaries containing your data.
• metadata: A dictionary for global/object-specific metadata.
• payload_type: A string describing the object type (e.g., table).
• mapping: A dictionary mapping frontend-aware fields to your object fields.

Note: If you manually call tree_data.add() and also yield Result(...) with the same items, you may create duplicates in the environment.

yield Result(
    objects = [
        {
            "title": "Example Result",
            "content": "This is just an example of a result"
        }
    ]
)