Quickstart¶

Welcome to our Quickstart Guide! This guide is designed to help you get up and running with the AI Refinery SDK as quickly and smoothly as possible. For a more detailed overview of our project creation guidelines, visit our Project Guidelines page. In this quickstart guide, we will:

Installation Process: Start with an walkthrough of the AI Refinery SDK installation steps.
Example Project Creation: Develop a simple example project that incorporates both a custom utility agent and a built-in utility agent, showcasing their capabilities and interactions.

SDK Installation¶

⚠️ Note: For Windows setup, please use WSL (Windows Subsystem Linux), a Linux kernel you can access from Windows. For instructions on installing WSL, please visit this page. Please use Ubuntu Distro 22.04 or above.

Prerequisites¶

Python 3.12 or higher
pip (Python package installer)

Steps¶

1. Create a Virtual Environment¶

Windows (WSL) or Linux¶

Open Command Prompt/PowerShell/Terminal and run the following commands to create a new virtual environment with a name of your choice.

mkdir ~/.venv
python -m venv ~/.venv/[name of your environment]

MacOS¶

Open Terminal and run the following command:

python3 -m venv ~/.venv/[name of your environment]

2. Activate the Virtual Environment¶

In Command Prompt/PowerShell/Terminal, run the following command to activate the virtual environment:

source ~/.venv/[name of your environment]/bin/activate

3. Install the SDK Wheel Package¶

Install it by executing the following command in your terminal:

pip install airefinery-sdk

4. Deactivating the Virtual Environment¶

When you are done working in the virtual environment, you can deactivate it by running:

deactivate

You can now start using the AI Refinery™ SDK to build AI systems.

Feel free to copy and paste this content into your README.md file.

Your First Project¶

With your environment ready and the AI Refinery SDK installed, let's create your first project. This section will walk you through setting up and running a basic project using custom and built-in utility agents, providing hands-on experience with AI Refinery.

Configuring Credentials with a .env File¶

To facilitate seamless login to the AI Refinery service, begin by creating a .env file in your project directory and adding the following lines:

ACCOUNT=<your_account>  
API_KEY=<your_api_key>

Make sure to replace your_account and your_api_key with your actual account details and API key for AI Refinery. The .env file will be used to load these credentials into your application.

Creating a Custom Agent¶

A custom agent is a Python function designed to process a string query and return a single output. An example of a custom utility agent can be seen below:

import asyncio
import os

from air import AsyncAIRefinery, DistillerClient, login
from dotenv import load_dotenv

load_dotenv() # This loads your ACCOUNT and API_KEY from your local '.env' file

# login to AI Refinery with your credentials
auth = login(
    account=str(os.getenv("ACCOUNT")),
    api_key=str(os.getenv("API_KEY")),
)

async def simple_agent(query: str):
    """
    A simple custom agent that generates synthetic data
    using Chat Completions API
    """
    global auth

    prompt = f"""Your task is to generate some synthetic data so that it will be useful to answer the user question. Do not mention this is synthetic data in your answer.\n\n{query}"""
    client = AsyncAIRefinery(**auth.openai())


    response = await client.chat.completions.create(
        messages=[{"role": "user", "content": prompt}],
        model="meta-llama/Llama-3.1-70B-Instruct",
    )

    return response.choices[0].message.content

In this example, the simple_agent generates synthetic data in response to a user's query using the Chat Completions API. Depending on your requirements, you can customize the agent to be simpler (e.g., returning "hello" for every input query) or more complex (e.g., interacting with other agents or retrieving relevant information using RAG). You can achieve this by modifying the provided function accordingly.

Creating Your Project¶

Next, use our DistillerClient API to create a distiller client. This client will interface with the AI Refinery service to run your project. Below is a function that sets up the distiller client. Here's what it does:

Instantiates a DistillerClient.
Creates a project named example using the configuration specified in the example.yaml file. Details of example.yaml are provided in the next section.
Adds the previously defined simple_agent to the executor_dict under the name Data Scientist Agent.
Sends a query to AI Refinery service to be processed, and then prints the recieved response.

async def quickstart_demo():
    distiller_client = DistillerClient()

    # upload your config file to register a new distiller project
    distiller_client.create_project(config_path="example.yaml", project="example") 

    # Define a mapping between your custom agent to Callable.
    # When the custom agent is summoned by the super agent / orchestrator,
    # distiller-sdk will run the custom agent and send its response back to the
    # multi-agent system.
    executor_dict = {
        "Data Scientist Agent": simple_agent,
    }

    # connect to the created project
    async with distiller_client(
        project="example",
        uuid="test_user",
        executor_dict=executor_dict
    ) as dc:
        responses = await dc.query(query="Who won the FIFA world cup 2022?") # send a query to project
        async for response in responses:
            print(response['content']) 

if __name__ == "__main__":
     asyncio.run(quickstart_demo())

⚠️ Note: project name & uuid must conform to our naming conventions.

Project Configuration¶

Next, you will need to configure your project by using YAML.

orchestrator:   
  agent_list:   
    # List of agents available in the orchestrator. Each agent must be configure under utility_agents below. 
    - agent_name: "Data Scientist Agent"  
    - agent_name: "Search Agent"           

utility_agents:   
  - agent_class: CustomAgent  
    agent_name: "Data Scientist Agent"  
    agent_description: "An agent for generating synthetic data."  # Description of the Data Scientist Agent  
    config: {}  # Configuration details for the Data Scientist Agent  

  - agent_class: SearchAgent  
    agent_name: "Search Agent"  
    # Configuration and description for Search Agent can be added here

As you can see, the orchestrator for this project is configured to have access to only the Data Scientist Agent from the executor_dict and a built-in utility agent named Search Agent. The settings for each of these utility agents are specified under utility_agents. You have the flexibility to expand your project based on your requirements. You can add additional custom agents that you define in the future or integrate built-in agents from our agent library.

Project Setup & Execution¶

Now that you have all the necessary code needed for the project, let us set it up and execute it.

Structure¶

Create a directory named example.
Inside the example directory, create a Python file named example.py and place all the Python code mentioned above into this file.
Also, within the example directory, create a YAML file named example.yaml and paste the provided YAML configuration into this file.
Additionally, create a .env file within the example directory and add your environment variables as specified earlier.

This gives us the following project structure:

example/  
│    
├── example.py  
├── example.yaml  
├── .env

Execution¶

To execute the example project, run the following commands on your terminal:

cd example/
python example.py

Running these commands will create the project on the AI Refinery server. You can now interact with the agents directly from your terminal.