Quickstart¶

Important: Ensure you have access to AI Refinery and your API key generated before proceeding. Visit this page to learn more about generating your API key.

Note: To better understand the platform, the Core Concepts page provides an architectural overview of AI Refinery’s architecture along with definitions of its key concepts.

Welcome to our Quickstart Guide! This guide is for developers, data scientists, and technical practitioners who want to get started with the AI Refinery SDK quickly. For more details on project setup, see our Project Guidelines.

In this quick start guide, we will provide:

Installation: How to set up the AI Refinery SDK.
Example Project: A simple project using both a custom and a built-in utility agent.

SDK Installation Steps¶

⚠️ Note: For Windows, use WSL (Windows Subsystem for Linux) with Ubuntu 22.04 or above.

Follow this guide to install WSL. All other required packages will be installed while installing the SDK.

Prerequisites¶

Python 3.12 or higher
pip (Python package installer)

Below are the steps to create a virtual environment, activate the virtual environment, install the SDK package, and deactivate the virtual environment. These steps are crucial in order to ensure a clean, isolated environment for your project, avoid dependency conflicts, and simplify package management.

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 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 the AI Refinery SDK and your API key ready (API key generation guide), you can create your first project. A project is the core building block of AI Refinery, giving you access to multi-agent workflows, and all other features offered by airefinery.

This section shows you how to set up and run a basic project using custom and built-in utility agents, giving you 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:

Using a .env file is a best practice as it keeps credentials secure, avoids accidental exposure in code repositories, and simplifies configuration management across environments.

API_KEY=<your_api_key>

Make sure to replace your_api_key with the actual API key you generated. The .env file will be used to load the API key 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. For more details, please refer to the Custom Agent page.

import asyncio
import os

from air import AsyncAIRefinery, DistillerClient
from dotenv import load_dotenv

load_dotenv() # loads your API_KEY from your local '.env' file
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
    """


    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(api_key=api_key)


    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(api_key=api_key)

    # Validate your configuration file before creating the project
    is_config_valid = distiller_client.validate_config(config_path="example.yaml")

    if not is_config_valid:
        # Abort if validation fails to avoid creating an invalid project
        print("Configuration validation failed!")
        return

    # 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.