Adala

<picture> <source media="(prefers-color-scheme: dark)" srcset="/docs/src/img/logo-dark-mode.png" width="275" > <source media="(prefers-color-scheme: light)" srcset="/docs/src/img/logo.png" width="275" > <img alt="Shows Adala logo in light mode and dark mode." src="/docs/src/img/logo.png" width="275" > </picture>

Adala is an Autonomous DAta (Labeling) Agent framework.

Adala offers a robust framework for implementing agents specialized in data processing, with an emphasis on diverse data labeling tasks. These agents are autonomous, meaning they can independently acquire one or more skills through iterative learning. This learning process is influenced by their operating environment, observations, and reflections. Users define the environment by providing a ground truth dataset. Every agent learns and applies its skills in what we refer to as a "runtime", synonymous with LLM.

<!-- Offered as an HTTP server, users can interact with Adala via command line or RESTful API, and directly integrate its features in Python Notebooks or scripts. The self-learning mechanism leverages Large Language Models (LLMs) from providers like OpenAI and VertexAI. -->

📢 Why choose Adala?

• 🌟 Reliable agents: Agents are built upon a foundation of ground truth data. This ensures consistent and trustworthy results, making Adala a reliable choice for your data processing needs.

• 🎮 Controllable output: For every skill, you can configure the desired output and set specific constraints with varying degrees of flexibility. Whether you want strict adherence to particular guidelines or more adaptive outputs based on the agent's learning, Adala allows you to tailor results to your exact needs.

• 🎯 Specialized in data processing: While agents excel in diverse data labeling tasks, they can be customized for a wide range of data processing needs.

• 🧠 Autonomous learning: Adala agents aren't just automated; they're intelligent. They iteratively and independently develop skills based on environment, observations, and reflections.

• ✅ Flexible and extensible runtime: Adala's runtime environment is adaptable. A single skill can be deployed across multiple runtimes, facilitating dynamic scenarios like the student/teacher architecture. Moreover, the openness of framework invites the community to extend and tailor runtimes, ensuring continuous evolution and adaptability to diverse needs.

• 🚀 Easily customizable: Quickly customize and develop agents to address challenges specific to your needs, without facing a steep learning curve.

🫵 Who is Adala for?

Adala is a versatile framework designed for individuals and professionals in the field of AI and machine learning. Here's who can benefit:

• 🧡 AI engineers: Architect and design AI agent systems with modular, interconnected skills. Build production-level agent systems, abstracting low-level ML to Adala and LLMs.
• 💻 Machine learning researchers: Experiment with complex problem decomposition and causal reasoning.
• 📈 Data scientists: Apply agents to preprocess and postprocess your data. Interact with Adala natively through Python notebooks when working with large Dataframes.
• 🏫 Educators and students: Use Adala as a teaching tool or as a base for advanced projects and research.

While the roles highlighted above are central, it's pivotal to note that Adala is intricately designed to streamline and elevate the AI development journey, catering to all enthusiasts, irrespective of their specific niche in the field. 🥰

🔌Installation

Install Adala:

pip install adala

Adala frequently releases updates. In order to ensure that you are using the most up-to-date version, it is recommended that you install it from GitHub:

pip install git+https://github.com/HumanSignal/Adala.git

Developer installation:

git clone https://github.com/HumanSignal/Adala.git
cd Adala/
poetry install

<!-- If you're planning to use human-in-the-loop labeling, or need a labeling tool to produce ground truth datasets, we suggest installing Label Studio. Adala supports Label Studio format out of the box. ```sh pip install label-studio ``` -->

📝 Prerequisites

Set OPENAI_API_KEY (see instructions here)

export OPENAI_API_KEY='your-openai-api-key'

🎬 Quickstart

In this example we will use Adala as a standalone library directly inside Python notebook.

Click here to see an extended quickstart example.

import pandas as pd

from adala.agents import Agent
from adala.environments import StaticEnvironment
from adala.skills import ClassificationSkill
from adala.runtimes import OpenAIChatRuntime
from rich import print

# Train dataset
train_df = pd.DataFrame([
    ["It was the negative first impressions, and then it started working.", "Positive"],
    ["Not loud enough and doesn't turn on like it should.", "Negative"],
    ["I don't know what to say.", "Neutral"],
    ["Manager was rude, but the most important that mic shows very flat frequency response.", "Positive"],
    ["The phone doesn't seem to accept anything except CBR mp3s.", "Negative"],
    ["I tried it before, I bought this device for my son.", "Neutral"],
], columns=["text", "sentiment"])

# Test dataset
test_df = pd.DataFrame([
    "All three broke within two months of use.",
    "The device worked for a long time, can't say anything bad.",
    "Just a random line of text."
], columns=["text"])

agent = Agent(
    # connect to a dataset
    environment=StaticEnvironment(df=train_df),

    # define a skill
    skills=ClassificationSkill(
        name='sentiment',
        instructions="Label text as positive, negative or neutral.",
        labels=["Positive", "Negative", "Neutral"],
        input_template="Text: {text}",
        output_template="Sentiment: {sentiment}"
    ),

    # define all the different runtimes your skills may use
    runtimes = {
        # You can specify your OPENAI API KEY here via `OpenAIRuntime(..., api_key='your-api-key')`
        'openai': OpenAIChatRuntime(model='gpt-4o'),
    },
    teacher_runtimes = {
        # You can specify your OPENAI API KEY here via `OpenAIRuntime(..., api_key='your-api-key')`
        'default': OpenAIChatRuntime(model='gpt-4o'),
    },
    default_runtime='openai',
)

print(agent)
print(agent.skills)

agent.learn(learning_iterations=3, accuracy_threshold=0.95)

print('\n=> Run tests ...')
predictions = agent.run(test_df)
print('\n => Test results:')
print(predictions)

However, if you prefer to use Adala with Claude, Gemini, or other OpenAI compatible LLMs, you can do so by using OpenRouter.ai. Below is an example of how to use the OpenRouter API:

Start by setting the OPENROUTER_API_KEY environment variable, which you can get from OpenRouter.

export OPENROUTER_API_KEY='your-openrouter-api-key'

Then, let's see how to modify the previous example to use OpenRouter with Claude 3.5 Haiku.

import os
import pandas as pd

from adala.agents import Agent
from adala.environments import StaticEnvironment
from adala.skills import ClassificationSkill
from adala.runtimes import OpenAIChatRuntime
from rich import print

# Train dataset
train_df = pd.DataFrame([
    ["It was the negative first impressions, and then it started working.", "Positive"],
    ["Not loud enough and doesn't turn on like it should.", "Negative"],
    ["I don't know what to say.", "Neutral"],
    ["Manager was rude, but the most important that mic shows very flat frequency response.", "Positive"],
    ["The phone doesn't seem to accept anything except CBR mp3s.", "Negative"],
    ["I tried it before, I bought this device for my son.", "Neutral"],
], columns=["text", "sentiment"])

# Test dataset
test_df = pd.DataFrame([
    "All three broke within two months of use.",
    "The device worked for a long time, can't say anything bad.",
    "Just a random line of text."
], columns=["text"])

agent = Agent(
    # connect to a dataset
    environment=StaticEnvironment(df=train_df),

    # define a skill
    skills=ClassificationSkill(
        name='sentiment',
        instructions="Label text as positive, negative or neutral.",
        labels=["Positive", "Negative", "Neutral"],
        input_template="Text: {text}",
        output_template="Sentiment: {sentiment}"
    ),

    # define all the different runtimes your skills may use
    runtimes = {
        # You can specify your OpenRouter API Key here or set it ahead of time in your environment variable, OPENROUTER_API_KEY
        'openrouter': OpenAIChatRuntime(
            base_url="https://openrouter.ai/api/v1",
            model="anthropic/claude-3.5-haiku",
            api_key=os.getenv("OPENROUTER_API_KEY"),
            provider="Custom"
            ),
    },

    default_runtime='openrouter',

    teacher_runtimes = {
        "default" : OpenAIChatRuntime(
            base_url="https://openrouter.ai/api/v1",
            model="anthropic/claude-3.5-haiku",
            api_key=os.getenv("OPENROUTER_API_KEY"),
            provider="Custom"
        ),
    }
)

print(agent)
print(agent.skills)

agent.learn(learning_iterations=3, accuracy_threshold=0.95)

print('\n=> Run tests ...')
predictions = agent.run(test_df)
print('\n => T