Distiller API

Distiller is AI Refinery’s underlying multi-agent collaboration framework. It provides convenient abstractions that let developers quickly create autonomous, collaborative agents capable of advanced reasoning and decision-making.

Before you begin, you must create an authenticated AsyncAIRefinery client, as shown below. All Distiller-related APIs are accessed via client.distiller.

import os
from air import login, AsyncAIRefinery

# Log in with your credentials
auth = login(
    account=str(os.getenv("ACCOUNT")),
    api_key=str(os.getenv("API_KEY")),
)
client = AsyncAIRefinery(api_key=api_key)

---

Preliminaries

Creating Your Project

client.distiller.create_project() (synchronous)

Creates a new project based on the specified YAML configuration file.

Parameters:

• config_path (str): The path to the YAML configuration file.
• project (str): A name for your project (letters, digits, hyphens, underscores only).

Returns:

• bool: True if the project is successfully created.

Project Versioning:

• Distiller automatically handles project versioning, starting at version 0.
• The first time you create a project with a given name, it is assigned version 0. If you create another project with the same name, Distiller increments the version to 1, and so on.

Example:

# This command registers the project "example" using the "example.yaml" configuration file.
client.distiller.create_project(config_path="example.yaml", project="example")

---

Downloading Your Project Configuration

client.distiller.download_project() (synchronous)

Retrieves the configuration of a specified project from the server.

Parameters:

• project (str): The name of the project whose configuration you want to download.
• project_version (str, optional): The version of the project configuration to download. Defaults to the latest version if not provided.

Returns:

• dict: A Python dictionary containing the downloaded configuration.

Example:

# This command downloads version "1" of the "example" project.
project_config = client.distiller.download_project(project="example", project_version="1")

---

Connecting to Distiller

client.distiller.__call__() (asynchronous)

Establishes an asynchronous connection (via a WebSocket) to the Distiller endpoint for a specific project. Usage of this function within an async context manager allows easy management of all Distiller-related operations.

Parameters:

• project (str): The project name (letters, digits, hyphens, underscores only).
• uuid (str): A unique user identifier (letters, digits, hyphens, underscores only).
• executor_dict (dict[str, Callable], optional): A dictionary mapping custom agent names to callable functions. These callables are invoked when their corresponding agents are triggered by the super agent or orchestrator. Defaults to {}.
• project_version (str, optional): The project version to connect to. If not provided, Distiller uses the latest version.

Returns:

• _DistillerContextManager: An asynchronous context manager that handles operations within the given project.

Example:

async with client.distiller(
    project="example",
    uuid="test"
) as dc:
    # Your asynchronous operations here
    pass

---

client.distiller.query() (asynchronous)

Sends a query message to the WebSocket asynchronously.

Parameters:

• query (str): The text of your query.
• image (Optional[str], optional): An image to include in the query. Defaults to None.
• **kwargs: Additional keyword arguments.

Returns:

• Coroutine: A coroutine that, when awaited, sends the query request.

Example:

async with client.distiller(
    project="example",
    uuid="test"
) as dc:
    responses = await dc.query(query="hi")
    async for response in responses:
        print(response)

---

client.distiller.add_memory() (asynchronous)

Adds memory to the WebSocket asynchronously.

Parameters:

• **kwargs: Any keyword arguments you want to store as memory.

Returns:

• Coroutine: A coroutine that, when awaited, adds the specified memory.

Example:

async with client.distiller(
    project="example",
    uuid="test"
) as dc:
    # Adding environment variables to memory
    await dc.add_memory(
        source="env_variable",
        variables_dict={"travel_destinations": "Hidden gems and cultural hotspots"},
    )

---

client.distiller.retrieve_memory() (asynchronous)

Retrieves memory from the WebSocket asynchronously.

Parameters:

• **kwargs: Keyword arguments for memory retrieval.

Returns:

• Coroutine: A coroutine that, when awaited, retrieves the requested memory.

Example:

async with client.distiller(
    project="example",
    uuid="test"
) as dc:
    # Retrieve environment variables
    retrieved_env_variables = await dc.retrieve_memory(
        source="env_variable"
    )

---

AsyncAIRefinery.distiller.reset_memory() (asynchronous)

Resets memory in the WebSocket asynchronously.

Parameters:

• **kwargs: Keyword arguments indicating which memory to reset (if applied).

Returns:

• Coroutine: A coroutine that, when awaited, resets the specified memory.

Example:

async with client.distiller(
    project="example",
    uuid="test"
) as dc:
    # Reset Memory
    await dc.reset_memory()

---

To learn more about Distiller, visit the Distiller section in the AI Refinery documentation. For detailed examples of building complex multi-agent projects, check out the Tutorial pages.