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.
MacOS¶
Open Terminal and run the following command:
2. Activate the Virtual Environment¶
In Command Prompt/PowerShell/Terminal, run the following command to activate the virtual environment:
3. Install the SDK Wheel Package¶
Install it by executing the following command in your terminal:
4. Deactivating the Virtual Environment¶
When you are done working in the virtual environment, you can deactivate it by running:
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:
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 theexample.yaml
file. Details ofexample.yaml
are provided in the next section. - Adds the previously defined
simple_agent
to theexecutor_dict
under the nameData 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
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 namedexample.py
and place all the Python code mentioned above into this file. - Also, within the
example
directory, create a YAML file namedexample.yaml
and paste the provided YAML configuration into this file. - Additionally, create a
.env
file within theexample
directory and add your environment variables as specified earlier.
This gives us the following project structure:
Execution¶
To execute the example project, run the following commands on your terminal:
Running these commands will create the project on the AI Refinery server. You can now interact with the agents directly from your terminal.