Forem: Tushar Singh

Image Annotation Applications: A Complete

Tushar Singh — Fri, 21 Nov 2025 11:08:27 +0000

How does your phone recognize faces in photos? Or how self-driving cars know where the road is? The answer is image annotation. This technology is changing our world, and it's easier to understand than you might think.

What Is Image Annotation?

Image annotation is the process of adding labels or tags to images to help computers understand what they're seeing. People draw boxes around objects, highlight areas, or add descriptive tags to pictures. These labeled images then teach artificial intelligence (AI) systems to recognize similar objects in new, unlabeled images. It's like teaching a child to identify animals using flashcards with labels.

Think of image annotation as creating training wheels for AI. Just as training wheels help you learn to ride a bike, annotated images help AI learn to "see." Without these labels, computers would just see random shapes and colors without understanding what they mean.

Why Do We Need Image Annotation Applications?

We need image annotation applications because manually labeling thousands of images takes too much time and effort. These specialized tools make the process faster, more accurate, and consistent. They provide features like automatic labeling assistance, quality checks, and collaboration tools that allow teams to work together efficiently on large annotation projects.

Modern image annotation applications have transformed how we prepare data for AI systems. Companies like Labellerr AI have developed platforms that combine human expertise with machine learning to create high-quality training data efficiently.

Common Image Annotation Techniques

There are several ways to annotate images, each useful for different purposes:

Bounding Boxes: Drawing rectangles around objects (like cars, people, or animals)
Polygon Annotation: Creating precise shapes around irregular objects
Semantic Segmentation: Coloring each pixel to show what object it belongs to
Landmark Annotation: Marking specific points on objects (like facial features)
Text Annotation: Adding labels or descriptions to parts of an image

How Do Image Annotation Tools Help Machine Learning?

Image annotation tools provide the labeled data that machine learning algorithms need to learn pattern recognition. These tools create training datasets where each image has accurate labels identifying objects, boundaries, or features. The AI studies these examples to learn what different objects look like from various angles, lighting conditions, and contexts, eventually becoming able to identify them in new, unlabeled images.

According to research from Stanford University, the quality of annotation directly impacts how well AI models perform. Poor labeling leads to confused AI, while precise annotations create smarter systems.

Benefits of Using Professional Annotation Tools

Using specialized image annotation applications offers several advantages:

Time Savings: Automated features speed up the labeling process
Better Accuracy: Quality control tools reduce mistakes
Team Collaboration: Multiple people can work on the same project
Consistency: Standardized labeling across all images
Scalability: Ability to handle large projects with thousands of images

The Nature Journal of Machine Intelligence highlights that as AI systems become more advanced, the demand for high-quality annotated data continues to grow exponentially.

Where Are Image Annotation Applications Used?

You might be surprised how many areas use image annotation:

Self-Driving Cars: Identifying pedestrians, other vehicles, and traffic signs
Medical Imaging: Spotting diseases in X-rays, MRIs, and CT scans
Retail: Recognizing products for inventory management and visual search
Agriculture: Monitoring crop health and detecting pests
Security: Identifying suspicious activities or objects
Social Media: Automatically tagging people in photos

Companies developing these technologies rely on image annotation applications to create the training data their AI needs. For instance, Labellerr AI provides annotation services that help businesses across these industries build better computer vision models.

Challenges in Image Annotation

Despite technological advances, image annotation still faces some difficulties:

Subjectivity: Different people might label the same object differently
Complex Objects: Some items have unclear boundaries or change shape
Time-Consuming: Detailed annotation requires significant human effort
Cost: High-quality annotation can be expensive for large datasets
Quality Control: Ensuring consistent quality across all annotations

A study by ACM found that inconsistent annotations are one of the biggest challenges in computer vision projects.

What Makes a Good Image Annotation Tool?

A good image annotation tool provides an intuitive interface, supports multiple annotation types (boxes, polygons, etc.), includes quality assurance features, enables team collaboration, offers automation capabilities to speed up labeling, and maintains data security. The best tools balance ease of use with powerful features suitable for both beginners and expert annotators working on complex projects.

When evaluating image annotation applications, consider these key features:

User-Friendly Interface: Easy to learn and use
Multiple Annotation Types: Supports different labeling methods
Collaboration Features: Allows team members to work together
Quality Control: Tools to check and maintain annotation quality
Automation: AI-assisted labeling to speed up the process
Data Security: Protects sensitive images and information

The Future of Image Annotation

Image annotation is evolving quickly. Here are some exciting developments:

AI-Assisted Annotation: Tools that learn from human input and suggest labels
3D Annotation: Labeling objects in three-dimensional space
Video Annotation: Tracking objects across multiple video frames
Active Learning: Systems that identify which images would be most valuable to annotate
Synthetic Data: Computer-generated images with automatic labels

As noted by Forbes, the future of AI depends heavily on improvements in data preparation, including image annotation.

Frequently Asked Questions

What's the difference between image annotation and image labeling?

Image labeling typically means adding a single tag to an entire image (like "cat"), while image annotation involves marking specific regions or objects within an image (like drawing a box around each cat in a picture with multiple animals).

How long does it take to annotate an image?

It depends on the complexity. A simple bounding box around one object might take seconds, while detailed segmentation of multiple complex objects could take several minutes per image.

Can image annotation be completely automated?

Not yet. While AI can help with annotation, human review is still needed for accuracy, especially for complex or unusual cases. The best approach combines AI efficiency with human quality control.

Ready to Learn More About Image Annotation?

Understanding image annotation applications is the first step toward leveraging this powerful technology. Whether you're a student, developer, or business professional, mastering image annotation can open doors to exciting opportunities in AI and machine learning.

Visit Labellerr AI to explore how professional image annotation tools can help with your computer vision projects and take your AI initiatives to the next level.

Image Annotation Applications: A Complete Guide

Tushar Singh — Fri, 21 Nov 2025 10:59:18 +0000

What Is Image Annotation?

Why Do We Need Image Annotation Applications?

Common Image Annotation Techniques

There are several ways to annotate images, each useful for different purposes:

Bounding Boxes: Drawing rectangles around objects (like cars, people, or animals)
Polygon Annotation: Creating precise shapes around irregular objects
Semantic Segmentation: Coloring each pixel to show what object it belongs to
Landmark Annotation: Marking specific points on objects (like facial features)
Text Annotation: Adding labels or descriptions to parts of an image

How Do Image Annotation Tools Help Machine Learning?

Benefits of Using Professional Annotation Tools

Using specialized image annotation applications offers several advantages:

Time Savings: Automated features speed up the labeling process
Better Accuracy: Quality control tools reduce mistakes
Team Collaboration: Multiple people can work on the same project
Consistency: Standardized labeling across all images
Scalability: Ability to handle large projects with thousands of images

The Nature Journal of Machine Intelligence highlights that as AI systems become more advanced, the demand for high-quality annotated data continues to grow exponentially.

Where Are Image Annotation Applications Used?

You might be surprised how many areas use image annotation:

Self-Driving Cars: Identifying pedestrians, other vehicles, and traffic signs
Medical Imaging: Spotting diseases in X-rays, MRIs, and CT scans
Retail: Recognizing products for inventory management and visual search
Agriculture: Monitoring crop health and detecting pests
Security: Identifying suspicious activities or objects
Social Media: Automatically tagging people in photos

Challenges in Image Annotation

Despite technological advances, image annotation still faces some difficulties:

Subjectivity: Different people might label the same object differently
Complex Objects: Some items have unclear boundaries or change shape
Time-Consuming: Detailed annotation requires significant human effort
Cost: High-quality annotation can be expensive for large datasets
Quality Control: Ensuring consistent quality across all annotations

A study by ACM found that inconsistent annotations are one of the biggest challenges in computer vision projects.

What Makes a Good Image Annotation Tool?

When evaluating image annotation applications, consider these key features:

User-Friendly Interface: Easy to learn and use
Multiple Annotation Types: Supports different labeling methods
Collaboration Features: Allows team members to work together
Quality Control: Tools to check and maintain annotation quality
Automation: AI-assisted labeling to speed up the process
Data Security: Protects sensitive images and information

The Future of Image Annotation

Image annotation is evolving quickly. Here are some exciting developments:

AI-Assisted Annotation: Tools that learn from human input and suggest labels
3D Annotation: Labeling objects in three-dimensional space
Video Annotation: Tracking objects across multiple video frames
Active Learning: Systems that identify which images would be most valuable to annotate
Synthetic Data: Computer-generated images with automatic labels

As noted by Forbes, the future of AI depends heavily on improvements in data preparation, including image annotation.

Frequently Asked Questions

Ready to Learn More About Image Annotation?

Visit Labellerr AI to explore how professional image annotation tools can help with your computer vision projects and take your AI initiatives to the next level.

Labellerr SDK & YOLOv8: Cars and Number Plate Detection Practical, Step-by-Step

Tushar Singh — Thu, 06 Nov 2025 04:03:17 +0000

Project Overview

In this project, we will build a complete end-to-end pipeline for detecting cars and their number plates using a custom-trained object detection model. The workflow is structured and beginner-friendly: we will first label images in Labellerr, then export those annotations, convert them into the YOLOv8 compatible format, and finally train and evaluate the model to see real detection results.

What is Labellerr?

Labellerr is a smart data annotation platform designed specifically for computer vision workflows.
It helps teams create high-quality labeled datasets efficiently, without the usual hassle of managing annotation tasks manually.

Key advantages of using Labellerr:

Intuitive bounding box annotation UI ideal for object detection tasks
Built-in quality review workflows ensures consistency across annotations
Direct export support for YOLO formats no manual formatting or conversion required

In short, Labellerr saves both time and effort while maintaining annotation quality, which is crucial for achieving good model performance.

For more details and examples, refer to the official documentation:
https://docs.labellerr.com/

What is YOLOv8?

YOLOv8(by Ultralytics) is one of the most widely used state-of-the-art object detection models.
It is known for delivering high accuracy, while still being fast enough for real-time detection.

Why YOLOv8 works well here:

Fast inference speed even on modest hardware
Straightforward training workflow
Excellent accuracy for object localization

This makes it a strong choice for real-world applications such as vehicle surveillance, traffic monitoring, and automated license plate recognition systems.

Why Use Labellerr and YOLOv8 Together?

Both tools complement each other perfectly:

Tool	Role in the Pipeline	Benefit
Labellerr	Label images clearly and consistently	High-quality dataset preparation
YOLOv8	Train and evaluate the detection model	Strong real-world performance with minimal setup

The workflow becomes:

Label → Export → Train → Detect,
without any messy intermediate steps or custom conversion scripts.

This results in a clean, reliable, and efficient pipeline from annotation to model deployment.

Project Setup

Step 1:

In this step, we will install all the required libraries including Labellerr SDK and YOLOv8.

Install all dependencies in one go.

!python -m pip install --upgrade pip
!python -m pip install --quiet https://github.com/tensormatics/SDKPython/releases/download/prod/labellerr_sdk-1.0.0.tar.gz kaggle Pillow requests python-dotenv opencv-python numpy scikit-learn

Step 2: Setting Up Kaggle Credentials

Since we are downloading the dataset from Kaggle, we first need to configure our Kaggle API credentials inside Google Colab.
This allows us to download datasets directly using commands like kaggle datasets download.

Steps:

Go to your Kaggle account settings
Scroll to API section
Click on Create New API Token
A file named kaggle.json will be downloaded
We will programmatically place this file in the correct location

import os, json, shutil
from pathlib import Path
from getpass import getpass
from IPython.display import display, Markdown

# Get Kaggle credentials from user input
KAGGLE_USERNAME = input("Enter your Kaggle username: ")
KAGGLE_KEY = getpass("Enter your Kaggle API key: ")

# Create .kaggle directory in user's home folder
kaggle_dir = Path.home() / ".kaggle"
kaggle_dir.mkdir(exist_ok=True)

# Write credentials to kaggle.json file
with open(kaggle_dir / "kaggle.json", "w") as f:
    json.dump({"username": KAGGLE_USERNAME, "key": KAGGLE_KEY}, f)

# Set proper permissions (600 = read/write for owner only)
os.chmod(kaggle_dir / "kaggle.json", 0o600)

display(Markdown("Kaggle credentials configured at `~/.kaggle/kaggle.json`"))
display(Markdown("Credentials securely stored with proper file permissions"))

What This Code Does:

Part / Line	Purpose
`input()` / `getpass()`	Securely capture username & API key (key not echoed)
`~/.kaggle/` directory	Required location for Kaggle CLI credentials
`kaggle.json` write	Stores `{username, key}` for authentication
`os.chmod(..., 0o600)`	Restricts file permissions to owner only
`display(Markdown(...))`	Shows friendly confirmation messages

Step 3: Downloading the Dataset from Kaggle

Now that our Kaggle credentials are configured, we can download the dataset directly into Google Colab using the Kaggle CLI.
This avoids manual upload and ensures fast + clean workflow.

Dataset Used:

andrewmvd/car-plate-detection

from pathlib import Path
from IPython.display import display, Markdown

# Download dataset via Kaggle CLI
DATASET = "andrewmvd/car-plate-detection"
DATA_DIR = Path("datasets/car")
DATA_DIR.mkdir(parents=True, exist_ok=True)

!kaggle datasets download -d {DATASET} -p {str(DATA_DIR)} --unzip

display(Markdown(f" Downloaded dataset `{DATASET}` to `{DATA_DIR}`"))

What This Code Does

Line / Component	Purpose
`DATASET`	Specifies the dataset to download from Kaggle
`Path("datasets/car")`	Sets the directory where dataset will be stored
`mkdir(parents=True, exist_ok=True)`	Creates folder if it doesn’t already exist
`kaggle datasets download`	Fetches dataset using Kaggle CLI
`--unzip`	Automatically extracts the files after download
`display(Markdown(...))`	Outputs a friendly completion message

Step 4: Preparing Sample Images for Inspection

Before labeling and training, it's always a good idea to preview a few images from the dataset.
This helps us verify:

The dataset downloaded correctly
The images are relevant
Their quality is suitable for training

Here, we will randomly pick 10 sample images and store them in a separate folder for quick review.

from pathlib import Path
from IPython.display import display, Markdown
import random
import shutil

# Prepare 10 sample images (ripe/unripe bananas subset if present; otherwise any images)
SEARCH_DIRS = [
    DATA_DIR,
]
IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".bmp", ".tiff"}

all_images = []
for base in SEARCH_DIRS:
    for p in base.rglob("*"):
        if p.is_file() and p.suffix.lower() in IMAGE_EXTS:
            all_images.append(p)

random.shuffle(all_images)

SAMPLE_DIR = Path("sample_images")
SAMPLE_DIR.mkdir(exist_ok=True)

selected = all_images[:10]
for i, src in enumerate(selected, start=1):
    dst = SAMPLE_DIR / f"car_{i:02d}{src.suffix.lower()}"
    shutil.copy2(src, dst)

display(Markdown(f" Prepared {len(selected)} images in `{SAMPLE_DIR}`"))

What This Code Does

Part / Line	Purpose
`DATA_DIR`	Directory containing the downloaded dataset
`IMAGE_EXTS`	Defines valid image file extensions
`rglob("*")`	Recursively searches all folders for images
`random.shuffle()`	Randomizes image selection
`SAMPLE_DIR.mkdir()`	Creates a folder named `sample_images`
`copy2()`	Copies selected sample images to that folder
`display(Markdown(...))`	Prints a neat confirmation message

Step 5: Connecting to Labellerr (Authentication)

Now we'll connect to the Labellerr platform. This cell will prompt you for your Labellerr credentials to initialize the API client.

Client ID: Your workspace-specific ID.
Email: The email associated with your Labellerr account.
API Key & Secret: Found in your Labellerr account settings. These will be entered securely with hidden input.

** How to Get Your Client ID**
The method depends on your Labellerr plan:

If you're using a Pro or Enterprise plan, you can simply contact Labellerr Support and they will share your Client ID.
If you're on the Free plan, you can request your Client ID by sending a short message to: support@tensormatics.com (mention the email you used to sign up on Labellerr that’s it.)

from getpass import getpass
from labellerr.client import LabellerrClient
from labellerr.exceptions import LabellerrError
from IPython.display import display, Markdown

# --- Interactive Input for Labellerr Credentials ---
print("Please enter your Labellerr API credentials.")
LABELLERR_CLIENT_ID = input("Labellerr Client ID: ")
LABELLERR_EMAIL = input("Labellerr Email: ")
LABELLERR_API_KEY = getpass("Labellerr API Key (input will be hidden): ")
LABELLERR_API_SECRET = getpass("Labellerr API Secret (input will be hidden): ")

# --- Initialize Labellerr Client ---
try:
    if not all([LABELLERR_API_KEY, LABELLERR_API_SECRET, LABELLERR_CLIENT_ID, LABELLERR_EMAIL]):
        raise ValueError("One or more required fields were left empty.")

    client = LabellerrClient(LABELLERR_API_KEY, LABELLERR_API_SECRET)

    display(Markdown(" Labellerr client initialized successfully!"))

except (LabellerrError, ValueError) as e:
    display(Markdown(f" **Client Initialization Failed:** {e}"))
    client = None

What This Code Does

Line / Component	Purpose
`getpass()`	Safely hides API key input while typing
`LabellerrClient()`	Creates authenticated Labellerr session
`ValueError` check	Ensures no fields were left empty
`try / except`	Catches invalid credentials and prevents crashes
`display(Markdown(...))`	Prints clean success/failure messages

Step 6: Creating Annotation Schema in Labellerr

Before labeling, we need to define what objects we want to annotate (Car & License Plate).
This step tells Labellerr which classes to display in the labeling UI.

ANNOTATION_QUESTIONS = [
    {
        "question_number": 1,
        "question": "Car",
        "question_id": "car-bbox-001",
        "option_type": "BoundingBox",
        "required": False,
        "options": [
            {"option_id": "opt-001", "option_name": "#FF0000"}
        ],
        "question_metadata": []
    },
    {
        "question_number": 2,
        "question": "License Plate",
        "question_id": "plate-bbox-002",
        "option_type": "BoundingBox",
        "required": False,
        "options": [
            {"option_id": "opt-002", "option_name": "#00FF00"}
        ],
        "question_metadata": []
    }
]




PROJECT_NAME = "Vehicle Object Detection new"
DATASET_NAME = "vehicle_dataset_sample_new"
DATASET_DESCRIPTION = "10 vehicle images including cars, plates"
DATA_TYPE = "image"

What This Code Defines

Field / Section	Meaning / Purpose
`ANNOTATION_QUESTIONS`	List of labeling tasks the annotator will perform
`question`	Name shown in labeling UI (Car, License Plate)
`option_type = "BoundingBox"`	Means user will draw bounding boxes
`option_name = "#FF0000"` / `"#00FF00"`	Box color to visually differentiate classes
`PROJECT_NAME`	Name of the project inside Labellerr
`DATASET_NAME`	Dataset title where labeled images will be stored
`DATASET_DESCRIPTION`	Short description for dataset organization
`DATA_TYPE = "image"`	Specifies dataset type important for correct processing

Step 7: Create Annotation Template in Labellerr

We’ll create an annotation guideline template (schema) in Labellerr using our questions (Car, License Plate).
Different SDK versions may return either a UUID string or a JSON dict, so we’ll handle both safely.

import json
from IPython.display import display, Markdown
from labellerr.exceptions import LabellerrError

template_id = None
try:
    res_str = client.create_annotation_guideline(
        client_id=LABELLERR_CLIENT_ID,
        questions=ANNOTATION_QUESTIONS,  
        template_name=f"{PROJECT_NAME} Template",
        data_type=DATA_TYPE,
    )

    #  Handle UUID-only or dict response
    if isinstance(res_str, str) and len(res_str) == 36 and res_str.count('-') == 4:
        template_id = res_str
        display(Markdown(f"Template created: `{template_id}`"))
    else:
        try:
            res = json.loads(res_str) if isinstance(res_str, str) else res_str
            template_id = res.get("response", {}).get("template_id")
            if template_id:
                display(Markdown(f"Template created: `{template_id}`"))
            else:
                display(Markdown(" Could not find template_id in response"))
                display(Markdown(f"Raw response: `{res_str}`"))
        except json.JSONDecodeError as e:
            display(Markdown(f" Response parsing issue: `{e}`"))
            display(Markdown(f"Raw response: `{res_str}`"))
            if isinstance(res_str, str) and len(res_str) > 20:
                template_id = res_str
                display(Markdown(f"Using response as template_id: `{template_id}`"))


except LabellerrError as e:
    display(Markdown(f"Template creation failed: `{e}`"))

What This Code Does

Line / Component	Purpose
`create_annotation_guideline(...)`	Creates a labeling template in Labellerr
`questions=ANNOTATION_QUESTIONS`	Passes your schema (Car, License Plate)
`template_name`	Human-readable name for the template
`data_type=DATA_TYPE`	Ensures correct modality (e.g., `"image"`)
UUID check (`len==36` & 4 dashes)	Detects raw UUID responses from older SDKs
`json.loads(...)`	Parses JSON response from newer SDKs
`res["response"]["template_id"]`	Extracts template ID when returned inside a dict
`except LabellerrError`	Catches SDK errors and prints a clean message
Fallback to `template_id = res_str`	Uses response as template ID if no JSON found

Expected Success Output

Template created: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 8: Creating the Project in Labellerr & Uploading Images

Once our annotation template is ready, the next step is to create a project in Labellerr and link our dataset.
We will also upload the sample images folder so annotators can begin labeling.

import json
from IPython.display import display, Markdown

project_id = None
if template_id:
    try:
        print("Creating project and linking dataset...")

        payload = {
            "client_id": LABELLERR_CLIENT_ID,
            "dataset_name": DATASET_NAME,
            "dataset_description": DATASET_DESCRIPTION,
            "data_type": DATA_TYPE,
            "created_by": LABELLERR_EMAIL,
            "project_name": PROJECT_NAME,
            "annotation_template_id": template_id,
            "rotation_config": {
                "annotation_rotation_count": 1,
                "review_rotation_count": 1,
                "client_review_rotation_count": 1
            },
            "autolabel": False,
            "folder_to_upload": "/content/sample_images"
        }

        # Pass as a single payload dictionary
        res = client.initiate_create_project(payload)

        # Handle response
        if isinstance(res, str) and len(res) == 36 and res.count('-') == 4:
            project_id = res
            display(Markdown(f"Project created: `{project_id}`"))
        else:
            try:
                res_obj = json.loads(res) if isinstance(res, str) else res
                project_id = res_obj.get("response", {}).get("project_id")
                if project_id:
                    display(Markdown(f" Project created: `{project_id}`"))
                else:
                    display(Markdown(" Could not find project_id in response"))
                    display(Markdown(f"Raw response: `{res}`"))
            except Exception as e:
                display(Markdown(f" Response parsing issue: `{e}`"))
                display(Markdown(f"Raw response: `{res}`"))

    except LabellerrError as e:
        display(Markdown(f" Project creation failed: `{e}`"))

What This Code Does

Line / Component	Purpose
`payload = {...}`	Contains all project settings and metadata
`dataset_name` / `project_name`	Organized names in Labellerr dashboard
`annotation_template_id`	Attaches the schema we made earlier
`folder_to_upload`	Directory containing images to upload to Labellerr
`initiate_create_project(payload)`	Creates project + uploads dataset
UUID response check	Handles cases where API returns raw UUID
JSON parse fallback	Handles cases where API returns JSON object
`except LabellerrError`	Catches SDK errors cleanly

Step 9: Linking an Existing Dataset to the Project in Labellerr

If your dataset is already uploaded to Labellerr, you do not need to upload images again.
Instead, you simply need to copy its Dataset ID from the Labellerr dashboard and pass it into the project creation function.

How to Get Dataset ID:

Open Labellerr Dashboard
Go to Datasets section
Select your dataset
Copy the Dataset ID shown in the details panel

This Dataset ID is what we will use in the code.

Code to Link Dataset With Project

rotation_config = {
    "annotation_rotation_count": 1,
    "review_rotation_count": 1,
    "client_review_rotation_count": 1
}

print("Creating project and linking existing dataset...")

res = client.create_project(
    project_name=PROJECT_NAME,
    data_type=DATA_TYPE,
    client_id=LABELLERR_CLIENT_ID,
    dataset_id="b7954c7f-a071-4eb7-b4e0-1980b3505e2b",   # ✅ Paste your Dataset ID here
    annotation_template_id=template_id,
    rotation_config=rotation_config
)

print("Project created successfully:")
print(res)

Explanation

Field / Parameter	Meaning
`dataset_id`	The dataset you selected from Labellerr → copied from dashboard
`annotation_template_id`	The annotation schema we created earlier (Car + License Plate)
`rotation_config`	How many people annotate → review → client verify
`create_project()`	Creates a new project and links your dataset + labeling workflow

Step 10:Labeling Workflow in Labellerr (Step-by-Step)

Once your dataset is linked to the project, you can start labeling right inside Labellerr.
Follow these clear steps to go from Label → Review → Accept.

Steps:

1. Go to Projects

Open Labellerr Dashboard → Projects tab.

2. Open Your Project

Select the project you created/linked (e.g., Vehicle Object Detection).

3. Go to the Label Section

_ Inside the project, click Label to open the annotation interface._

4. Start Labeling

- Choose the right tool (e.g., Bounding Box).
- Draw boxes around each Car and License Plate as per your schema.
- Assign the correct class from the sidebar.

5. Save / Submit

Save the annotation for each image (as per UI button in your workspace).

6. Move to Review

Go to Review tab. The images you labeled will show up for verification.

7. Accept or Send Back

- If the annotation looks good → Accept
- If changes needed → Send back to labeling.

Step 11: Exporting Labeled Dataset from Labellerr

After labeling + review, we export annotations from Labellerr.
This script automates 3 steps: Create export → Poll status → Download & Validate.

# --- Car Dataset Export Script ---
from IPython.display import display, Markdown
import requests
import json
import time
from pathlib import Path
import logging
import traceback
import uuid
from labellerr.exceptions import LabellerrError

project_id = "magdaia_joyous_peafowl_21008"

# CONFIGURE LOGGER
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
    force=True
)
logger = logging.getLogger(__name__)

# --- GLOBAL VARS ---
downloaded_annotations = None

# Step 1: Create Export
def create_export(client, project_id, client_id, export_config):
    """Initiates an export job on the Labellerr platform."""
    logger.info("Step 1: Creating export for car dataset...")
    try:
        res = client.create_local_export(project_id, client_id, export_config)
        export_id = res["response"]["report_id"]
        logger.info(f"Export created successfully. Export ID: {export_id}")
        return export_id
    except LabellerrError as e:
        logger.error(f"Export creation failed: `{e}`")
        return None

# Step 2: Poll Export Status
def poll_export_status(client, api_key, api_secret, project_id, export_id, client_id, max_wait_time=300, wait_interval=10):
    """Polls Labellerr API for export completion status."""
    logger.info(f"Step 2: Polling for export completion (max {max_wait_time}s)...")
    elapsed_time = 0
    while elapsed_time < max_wait_time:
        raw_status = client.check_export_status(
            api_key=api_key,
            api_secret=api_secret,
            project_id=project_id,
            report_ids=[export_id],
            client_id=client_id
        )

        status_obj = None
        if isinstance(raw_status, dict):
            status_obj = raw_status
        elif isinstance(raw_status, str):
            try:
                status_obj = json.loads(raw_status)
            except json.JSONDecodeError:
                logger.warning(f"Could not parse status string: '{raw_status}'")

        if status_obj and status_obj.get('status') and len(status_obj['status']) > 0:
            export_status = status_obj['status'][0]
            is_completed = export_status.get('is_completed', False)
            export_status_text = export_status.get('export_status', 'Unknown')
            logger.info(f"Current status: '{export_status_text}' (Completed: {is_completed})")
            if is_completed:
                logger.info("Export completed! Proceeding to download.")
                return True
            elif export_status_text.lower() == "failed":
                logger.error("Export failed!")
                return False

        time.sleep(wait_interval)
        elapsed_time += wait_interval

    logger.warning(f"Export timeout after {max_wait_time}s.")
    return False

# Step 3: Download & Validate Export
def download_and_validate_export(client, api_key, api_secret, project_id, export_id, client_id):
    """Fetches download URL, downloads, and validates the exported data."""
    logger.info("Step 3: Fetching download URL and validating data...")
    try:
        download_uuid = str(uuid.uuid4())
        raw_download_result = client.fetch_download_url(
            api_key=api_key,
            api_secret=api_secret,
            project_id=project_id,
            uuid=download_uuid,
            export_id=export_id,
            client_id=client_id
        )

        download_obj = None
        if isinstance(raw_download_result, dict):
            download_obj = raw_download_result
        elif isinstance(raw_download_result, str):
            try:
                download_obj = json.loads(raw_download_result)
            except json.JSONDecodeError:
                logger.warning(f"Could not parse download URL string: '{raw_download_result}'")

        download_url = (
            download_obj.get('url')
            or download_obj.get('response', {}).get('download_url')
        )

        if download_url:
            logger.info("Download URL fetched successfully.")
            logger.info(f"DOWNLOAD LINK (expires in ~1 hour): {download_url}")

            exports_dir = Path("exports")
            exports_dir.mkdir(exist_ok=True)
            export_file = exports_dir / f"car_dataset_export_{export_id}.json"

            response = requests.get(download_url)
            if response.status_code == 200:
                with open(export_file, 'wb') as f:
                    f.write(response.content)
                logger.info(f"Export downloaded to {export_file}")

                # Validate JSON structure
                try:
                    json_data = json.loads(response.content)
                    annotated_count = sum(
                        1 for ann in json_data
                        if ann.get("latest_answer") and len(ann["latest_answer"]) > 0
                    )

                    logger.info(f"VALIDATION: {annotated_count}/{len(json_data)} images have annotations.")
                    if annotated_count == 0:
                        logger.error(" No annotations found! Please ensure images are labeled.")
                        return False
                    else:
                        logger.info("Annotation data validated successfully!")
                        return True

                except json.JSONDecodeError:
                    logger.error(" Invalid JSON format in downloaded export.")
                    return False
            else:
                logger.error(f"Failed to download export file. HTTP {response.status_code}")
                return False

        else:
            logger.error(f"No download URL found. Raw response: {raw_download_result}")
            return False

    except Exception as e:
        logger.error(f" Error during download: {e}\n{traceback.format_exc()}")
        return False


#  MAIN EXECUTION
if project_id:
    try:
        export_config = {
            "export_name": "CarDatasetExport",
            "export_description": "Export of all annotated car images",
            "export_format": "json",
            "statuses": ['review', 'r_assigned', 'client_review', 'cr_assigned', 'accepted'],
            "export_destination": "local",
            "question_ids": ["all"]
        }

        export_id = create_export(client, project_id, LABELLERR_CLIENT_ID, export_config)

        if export_id:
            if poll_export_status(client, LABELLERR_API_KEY, LABELLERR_API_SECRET, project_id, export_id, LABELLERR_CLIENT_ID):
                download_and_validate_export(client, LABELLERR_API_KEY, LABELLERR_API_SECRET, project_id, export_id, LABELLERR_CLIENT_ID)

    except Exception as e:
        logger.error(f" Unexpected error in main block: {e}\n{traceback.format_exc()}")

What Each Part Does:

Block / Line	Purpose
`logging.basicConfig(...)`	Shows clean, timestamped logs in console
`create_local_export(...)`	Starts export job on Labellerr (returns `report_id`)
`poll_export_status(...)`	Re-checks export status until completed/failed
`fetch_download_url(...)`	Retrieves temporary download link for export file
`requests.get(download_url)`	Downloads export into `exports/*.json`
Annotation Validation	Confirms labeled data actually exists
`statuses=[...]`	Controls which workflow stages to include in export
`question_ids=["all"]`	Ensures all annotation question categories are exported

Step 12: Installing YOLOv8 (Ultralytics)

Before we start training our object detection model, we need to install Ultralytics, which contains YOLOv8.

!python -m pip install ultralytics

Step 13: Convert Labellerr Export (JSON) → YOLOv8 Dataset + Train/Val Split

Labellerr exports annotations in JSON format, but YOLOv8 requires images and labels in a specific directory structure along with .txt annotation files in normalized YOLO format (class x_center y_center width height).

In this step, we will:

Load the exported JSON file
Split the dataset into train and val sets
Convert bounding boxes into YOLO normalized coordinates
Copy images to the correct folders
Create annotation .txt files

import json, shutil, random
from pathlib import Path
from sklearn.model_selection import train_test_split

# --- Paths ---
EXPORT_FILE = Path("/content/exports/car_dataset_export_NfKqUBdOqPEz2HPfnSw4.json")
IMAGE_SOURCE_DIR = Path("/content/sample_images")  # your 10 images here
YOLO_DATA_DIR = Path("/content/yolo_Car_dataset")

# --- Classes ---
CLASS_NAMES = ["Car", "License Plate"]
CLASS_MAP = {name: i for i, name in enumerate(CLASS_NAMES)}

# --- Reset dataset folder ---
if YOLO_DATA_DIR.exists():
    shutil.rmtree(YOLO_DATA_DIR)

for split in ["train", "val"]:
    (YOLO_DATA_DIR / "images" / split).mkdir(parents=True, exist_ok=True)
    (YOLO_DATA_DIR / "labels" / split).mkdir(parents=True, exist_ok=True)

# --- Load JSON ---
with open(EXPORT_FILE, "r") as f:
    data = json.load(f)

print(f"Loaded {len(data)} items")

# --- Split Train/Val ---
train_data, val_data = train_test_split(data, test_size=0.2, random_state=42)

def convert_and_save(items, split):
    for item in items:
        file_name = item["file_name"]
        width = item["file_metadata"]["image_width"]
        height = item["file_metadata"]["image_height"]

        # Copy image
        src = IMAGE_SOURCE_DIR / file_name
        dst = YOLO_DATA_DIR / "images" / split / file_name
        if src.exists():
            shutil.copy(src, dst)
        else:
            print(f" Missing image: {src}")
            continue

        # Prepare label file
        label_path = YOLO_DATA_DIR / "labels" / split / f"{Path(file_name).stem}.txt"
        lines = []

        for ans_group in item.get("latest_answer", []):
            for ann in ans_group.get("answer", []):
                label = ann.get("label")
                if label not in CLASS_MAP:
                    continue
                cls_id = CLASS_MAP[label]
                bbox = ann["answer"]

                # YOLO normalized format
                x_center = ((bbox["xmin"] + bbox["xmax"]) / 2) / width
                y_center = ((bbox["ymin"] + bbox["ymax"]) / 2) / height
                w = (bbox["xmax"] - bbox["xmin"]) / width
                h = (bbox["ymax"] - bbox["ymin"]) / height

                lines.append(f"{cls_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}")

        with open(label_path, "w") as f:
            f.write("\n".join(lines))

# --- Run conversion ---
convert_and_save(train_data, "train")
convert_and_save(val_data, "val")

print("\n YOLO dataset structure created successfully at:", YOLO_DATA_DIR)
print("Classes:", CLASS_MAP)

What This Script Does

Step	Action	Explanation
1	Load JSON export	Reads annotation and metadata from Labellerr
2	Define class mapping	Assigns each object category a numerical class ID
3	Create `/images/` and `/labels/` folders	Matches the expected YOLO dataset layout
4	Split data into train & val	Ensures proper supervised learning workflow
5	Copy images to destination folders	Prepares dataset structure for YOLO
6	Convert bounding boxes → YOLO format	Normalizes coordinates between 0–1
7	Write `.txt` annotation files	YOLO uses one annotation text file per image

Resulting Dataset Structure

yolo_Car_dataset/
 ├─ images/
 │   ├─ train/
 │   └─ val/
 └─ labels/
     ├─ train/
     └─ val/

Step 14: Convert Labellerr Annotations → YOLOv8 Labels (Function)

This helper converts Labellerr’s JSON annotations into YOLO normalized TXT labels and copies images into the correct split folders.

def convert_labellerr_to_yolo(data, split):
    """Converts Labellerr bounding box annotations to YOLO format."""
    for ann in data:
        image_name = ann.get("file_name")
        image_width = ann.get("file_metadata", {}).get("image_width", 1)
        image_height = ann.get("file_metadata", {}).get("image_height", 1)

        # Copy image
        source_image_path = IMAGE_SOURCE_DIR / image_name
        dest_image_path = YOLO_DATA_DIR / "images" / split / image_name
        if source_image_path.exists():
            shutil.copy2(source_image_path, dest_image_path)
        else:
            print(f"Warning: Source image not found: {source_image_path}")
            continue

        # Label file path
        label_path = YOLO_DATA_DIR / "labels" / split / f"{Path(image_name).stem}.txt"

        with open(label_path, "w") as f:
            for qa in ann.get("latest_answer", []):  # iterate over each question (Car, License Plate, etc.)
                for ans in qa.get("answer", []):     # iterate over each bounding box inside that question
                    class_name = ans.get("label")
                    if class_name not in CLASS_MAP:
                        continue

                    class_id = CLASS_MAP[class_name]
                    box = ans.get("answer", {})

                    if not all(k in box for k in ["xmin", "ymin", "xmax", "ymax"]):
                        continue

                    xmin, ymin, xmax, ymax = (
                        float(box["xmin"]),
                        float(box["ymin"]),
                        float(box["xmax"]),
                        float(box["ymax"]),
                    )

                    # Convert to YOLO normalized format
                    x_center = ((xmin + xmax) / 2) / image_width
                    y_center = ((ymin + ymax) / 2) / image_height
                    width = (xmax - xmin) / image_width
                    height = (ymax - ymin) / image_height

                    f.write(f"{class_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}\n")

        # Check for empty file
        if label_path.stat().st_size == 0:
            print(f"Warning: Empty label file -> {label_path.name}")

What This Function Does

Piece	Purpose
`data`	List of Labellerr JSON items (one per image)
`split`	Either `"train"` or `"val"`; controls which folder images & labels go into
Copy image → `images/split/`	Places each image inside YOLO dataset structure
Create TXT → `labels/split/`	Creates YOLO annotation files matching each image
`CLASS_MAP` mapping	Converts class names like `"Car"` into numeric YOLO class IDs
Normalize bbox	Converts bounding box to YOLO normalized format (`x_center y_center width height`)
Empty label warning	Alerts when an image has no valid annotations (good for debugging)

Step 15: Creating dataset.yaml for YOLOv8

YOLOv8 needs a dataset.yaml file that tells it where the images & labels are located and which classes the model will learn.
The script below automatically generates it based on your dataset folder and class mapping.

import yaml
from pathlib import Path # Added import
from IPython.display import display, Markdown # Added import

# Define the dataset configuration
yaml_content = {
    'path': str(YOLO_DATA_DIR.resolve()), # The absolute path to the dataset directory
    'train': 'images/train',             # Path to training images (relative to 'path')
    'val': 'images/val',                 # Path to validation images (relative to 'path')
    'names': {v: k for k, v in CLASS_MAP.items()} # Class names map (e.g., {0: 'Ripe Banana', 1: 'Unripe Banana'})
}

# Write the configuration to a file
yaml_file = YOLO_DATA_DIR / "dataset.yaml"
with open(yaml_file, 'w') as f:
    yaml.dump(yaml_content, f, default_flow_style=False, sort_keys=False)

print(f"Created dataset configuration at '{yaml_file}'")
print("\n--- dataset.yaml content ---")
print(yaml.dump(yaml_content, sort_keys=False))

Understanding the `dataset.yaml` Fields

Field	Meaning
`path`	Root directory of the YOLO dataset
`train`	Folder containing training images (relative to `path`)
`val`	Folder containing validation images (relative to `path`)
`names`	Class index → Class name dictionary used by YOLO during training

Example dataset.yaml (Generated Output)

Created dataset configuration at '/content/yolo_Car_dataset/dataset.yaml'
--- dataset.yaml content ---
path: /content/yolo_Car_dataset
train: images/train
val: images/val
names:
0: Car
1: License Plate

Step 16: Training YOLOv8 on Our Dataset

Now that our dataset is structured and the dataset.yaml file is ready, we can train a YOLOv8 model.
Here, we use YOLOv8m (medium variant) for better accuracy.

from ultralytics import YOLO
from pathlib import Path

# Load medium model for better accuracy
model = YOLO('yolov8m.pt')

results = model.train(
    data=str(yaml_file),   # Path to your dataset YAML
    epochs=100,            # Increase training epochs for better learning
    imgsz=640,
    batch=4,
    freeze=0,
    project='car_license_training',
    name='yolov8m_finetuned'
)

print("\n YOLOv8m Object Detection Training Complete!")

What This Code Does

Parameter	Description
`YOLO('yolov8m.pt')`	Loads the YOLOv8 Medium model (balanced accuracy & speed)
`data=str(yaml_file)`	Uses the dataset YAML we generated earlier
`epochs=100`	Number of training cycles (higher = better accuracy)
`imgsz=640`	Input image resolution (default recommended for YOLOv8)
`batch=4`	Number of images processed per training step
`freeze=0`	Allows full fine-tuning of entire model
`project=`	Folder where training logs & weights are stored
`name=`	Name of the trained model checkpoint subfolder

** Tip**

To get higher accuracy, you may later increase:

epochs = 150 or 200

Step 17: Inference: Test the Trained YOLOv8 Model on Validation Images

Now that training is complete, let’s load the best weights and run inference on a few validation images.
We’ll draw colored boxes: green for license plates, yellow for cars.

from ultralytics import YOLO
from pathlib import Path
from IPython.display import display, Markdown
from PIL import Image
import cv2
import numpy as np

# Load best weights
best_weights = Path("/content/car_license_training/yolov8m_finetuned/weights/best.pt")
if best_weights.exists():
    infer_model = YOLO(str(best_weights))
    display(Markdown(f"Using best weights: `{best_weights}`"))
else:
    raise FileNotFoundError(" best.pt not found!")

# Load validation images
val_dir = Path("/content/yolo_Car_dataset/images/val")
test_images = [p for p in val_dir.glob("*") if p.suffix.lower() in {".jpg", ".jpeg", ".png"}][:6]
if not test_images:
    raise FileNotFoundError("No validation images found.")

# Inference
display(Markdown("###  Running inference with lower confidence (0.10)..."))

for img_path in test_images:
    preds = infer_model.predict(source=str(img_path), imgsz=640, conf=0.10, save=False, verbose=False)

    result = preds[0]

    img = cv2.imread(str(img_path))
    if img is None:
        print(f" Could not read image: {img_path}")
        continue

    for box in result.boxes:
        x1, y1, x2, y2 = map(int, box.xyxy[0])
        cls = int(box.cls[0])
        conf = float(box.conf[0])
        class_name = infer_model.names[cls]
        label = f"{class_name} {conf:.2f}"

        #  Color code
        if class_name.lower() in ["license plate", "plate"]:
            color = (0, 255, 0)   # Green for license plate
        else:
            color = (0, 255, 255) # Yellow for car

        cv2.rectangle(img, (x1, y1), (x2, y2), color, 2)
        cv2.putText(img, label, (x1, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)

    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    display(Image.fromarray(img_rgb))

display(Markdown("Inference complete  check if license plates appear now!"))

What This Inference Code Does

Part	Purpose
Load `best.pt`	Uses the best checkpoint from training for inference
Collect validation images	Selects sample images to test predictions
`infer_model.predict(...)`	Runs YOLOv8 inference on each image
Draw bounding boxes + confidence scores	Visualizes detection results clearly
Color coding	Green = License Plate, Yellow = Car
Display results inline	Shows final annotated images directly in notebook/output

Expected Output

Using
best weights: /content/car_license_training/yolov8m_finetuned/weights/best.pt
Running inference with lower confidence (0.10)...

Google Colab Notebook

Run the full workflow, experiment with the dataset, or retrain the model:

https://colab.research.google.com/drive/1KmontQoTchCJ9oqqGeBaZ0mxCD4eVZTU#scrollTo=2SdNLRuRVLDt

Thanks for reading! If you found this helpful, feel free to connect or leave feedback

🧠 Behind the Scenes of ClarityCare.AI: CAMEL-AI Toolkits That Power Your AI Wellness Companion

Tushar Singh — Fri, 20 Jun 2025 08:05:06 +0000

ClarityCare.AI is more than just a chatbot. It's a thoughtfully crafted AI mental wellness assistant designed to promote mindfulness, manage stress, and track emotional well-being. Let’s take a deep dive into the powerful toolkits, technologies, and design patterns used in this project.

🎬 Project Demo

Here’s a quick demo of my project in action. Watch it below:

🧹 Core Technology Stack

1. 🤖 CAMEL-AI Agents + Mistral API — Role-Based AI Reasoning

The centerpiece of ClarityCare.AI is its AI therapist agent. This agent is created using CAMEL-AI, a framework that specializes in role-based reasoning.
With CAMEL-AI’s ChatAgent, we define a personal for our agent using a system_message. In this case, the agent acts like a compassionate therapist—calm, empathetic, and emotionally intelligent.

🔧 Agent Creation Code:

from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType
from camel.configs import MistralConfig

mistral_model = ModelFactory.create(
    model_platform=ModelPlatformType.MISTRAL,
    model_type=ModelType.MISTRAL_LARGE,
    model_config_dict=MistralConfig(temperature=0.7).as_dict(),
)

agent = ChatAgent(
    system_message="You are a compassionate AI therapist. Provide empathetic and helpful guidance.",
    model=mistral_model,
)

This allows ClarityCare to simulate announced, context-aware, and emotionally appropriate dialogue using Mistral's LLM API.

Benefits of using CAMEL + Mistral:

Clear role definition (Therapist, Coach, Mentor, etc.)

Flexible model switching (OpenAI, Mistral, Claude, etc.)

Reusable agents for other domains (career coach, fitness advisor, etc.)

2. 🔍 SearchToolkit – Real-Time Mental Health Info

Understanding mental health often requires current, up-to-date information. To support this, we integrate CAMEL’s SearchToolkit, which performs real-time web search using DuckDuckGo.

from camel.toolkits import SearchToolkit

def search_outside_agent(query: str) -> str:
    search_tool = SearchToolkit().search_duckduckgo
    return search_tool(query)

The query result is appended to the user’s message before it's sent to the LLM, improving response depth.

3. 🔢 Arxiv Toolkit Wrapper – Evidence-Based Mental Health Papers

The app also taps into scientific knowledge using a custom arxiv_toolkit_wrapper. This connects to Arxiv.org and fetches latest research in:

Mindfulness therapy

CBT (Cognitive Behavioral Therapy)

Mental health tech

from toolkits.arxiv_toolkit_wrapper import get_mental_health_papers
papers = get_mental_health_papers()

This keeps the user informed through a science-first lens and ensures the app promotes evidence-based advice.

4. 📊 Mood Score Toolkit – Track Emotional Well-Being Over Time

Tracking how you feel daily is crucial for emotional growth. That’s where our math_toolkit_wrapper comes in. This simple but effective tool computes a mood score from the user’s mood rating.

from toolkits.math_toolkit_wrapper import calculate_mood_score
score = calculate_mood_score([mood])

Paired with a Matplotlib + Pandas graph, users can visualize trends in their emotional state, identifying:

1. High-stress weeks
2. Positive growth periods
3. Patterns related to sleep, anxiety, or focus

** Architecture Overview**

app.py: Core Streamlit logic with sidebar, chat interface, and insight panels.

therapist_agent.py: Handles agent creation and real-time search logic.

toolkits/: Each AI utility like search, math, and arXiv research is modularized.

claritycare-ai
├── app.py
├── therapist_agent.py
├── toolkits
│   ├── arxiv_toolkit_wrapper.py
│   ├── math_toolkit_wrapper.py
│   ├── news_toolkit_wrapper.py
│
|___ api.env

This design makes it easy to scale, modify, or replace any component (e.g. swap Mistral with OpenAI).

💡 Final Thoughts

ClarityCare.AI is a fusion of research, compassion, and AI. By integrating toolkits like CAMEL Agents, Mistral LLMs, and live search capabilities, it offers not just answers—but support, clarity, and presence.

It proves that AI can be not only intelligent—but also emotionally supportive.

💬 "Therapists may not be replaced—but they can be assisted by tools that help millions begin their journey to well-being."

🐪 CAMEL-AI: Architecting the Future of Autonomous Multi-Agent Collaboration with LLMs

Tushar Singh — Tue, 27 May 2025 12:27:30 +0000

“The next big leap in AI isn’t just about larger models—it’s about how they think, talk, and collaborate.”

✨ Introduction

With the explosion of powerful large language models (LLMs) like GPT-4, Claude, and LLaMA-4, we're witnessing machines that can translate languages, write code, generate poetry, and even pass professional exams.

But here’s a question:

Can we build systems of agents that simulate human-like discussion, disagreement, and collaboration to solve complex tasks?

Enter CAMEL-AI revolutionary open-source framework that enables developers to build multi-agent AI systems where each agent plays a unique role, has its own perspective, and works together to solve a shared goal.

In this deep-dive blog post, we’ll explore:

🔍 What is CAMEL-AI?
🧠 Why multi-agent reasoning matters
🧱 Core architecture and components
⚙️ Step-by-step implementation with code
🚀 Use case: AI Legal Advisor with dual-agent deliberation
📌 Best practices
🔮 Real-world applications and future roadmap

🔍 What is CAMEL-AI?

CAMEL-AI (Communicative Agents for Mindful Engagement and Learning) is a framework that brings the multi-agent paradigm to life using LLMs.

It allows you to simulate:

🧑‍⚖️ Agent-level personalities (roles)
🧠 Goal-oriented discussions
🗣️ Multi-turn conversations between agents
✅ Task execution with alignment and negotiation
In CAMEL-AI:
Every agent is a ChatAgent
Each message carries a role context
Conversations are orchestrated using the AgentChatManager
The shared objective is defined through a TaskPromptTemplate

This structure mirrors how real-world teams solve problems: through debate, alignment, and collaboration.

🧠 Why Multi-Agent AI Systems?

Single-agent LLMs:

Can hallucinate facts
Lack self-reflection
Often follow instructions blindly

Multi-agent systems:
✅ Encourage disagreement and evaluation
✅ Improve planning and reasoning
✅ Simulate real-world role dynamics
✅ Allow for decentralized decision-making

In essence, multi-agent setups like CAMEL-AI allow LLMs to "think with others", just like humans.

🧱 CAMEL-AI Architecture
Here’s a high-level diagram of CAMEL-AI:

 ┌────────────────────┐
 │  TaskPromptTemplate│
 └────────┬───────────┘
          ↓
 ┌──────────────┐      ┌──────────────┐
 │  ChatAgent A │ ◄──► │  ChatAgent B │
 └────┬─────────┘      └────┬─────────┘
      ↓                        ↓
  Role Message A          Role Message B
     (BaseMessage)           (BaseMessage)
          ↓                        ↓
       LLM Call                LLM Call

📦 Installing CAMEL-AI

pip install camel-ai

Set your LLM provider keys (OpenAI, Groq, TogetherAI, etc.):

# .env
GROQ_API_KEY="your_api_key"

Use python-dotenv to load them safely in your script:

from dotenv import load_dotenv
load_dotenv()

⚙️ Project: AI Legal Advisor

Let’s build a CAMEL-AI system that simulates a legal assistant and a client advocate discussing a legal case and producing a summary opinion.

🎭 Roles

Legal Assistant: Interprets the legal facts and provides advice
Client Advocate: Represents the client’s perspective and challenges the assistant

1️⃣ Define Role Messages

from camel.messages import BaseMessage
from camel.types import RoleType

legal_assistant_msg = BaseMessage(
    role_name="Legal Assistant",
    role_type=RoleType.ASSISTANT,
    content="You are an experienced legal advisor. Analyze the given case with reference to applicable laws and provide a professional opinion."
)

client_advocate_msg = BaseMessage(
    role_name="Client Advocate",
    role_type=RoleType.USER,
    content="You are defending the client's perspective. Your role is to challenge, clarify, and ensure the best interest of the client is protected."
)

2️⃣ Define the Shared Objective

from camel.prompts import TaskPromptTemplate

task_prompt = TaskPromptTemplate().format(
    assistant_role="Legal Assistant",
    user_role="Client Advocate",
    task="Evaluate a case where an employee was terminated for social media activity. Discuss if the firing was legal and what remedies are available."
)

3️⃣ Initialize Agents

from camel.agents import ChatAgent

assistant = ChatAgent(legal_assistant_msg)
advocate = ChatAgent(client_advocate_msg)

4️⃣ Set Up Chat Manager

from camel.agents import AgentChatManager

chat_manager = AgentChatManager(
    agent1=assistant,
    agent2=advocate,
    task_prompt=task_prompt
)

5️⃣ Simulate the Conversation

chat_messages = chat_manager.init_chat()

for step in range(8):
    result = chat_manager.step()
    chat_messages.append(result.msgs)

    print(f"\n--- Round {step + 1} ---")
    for msg in result.msgs:
        print(f"{msg.role_name}: {msg.content}")

    if result.terminated:
        print("\n✅ Final Opinion Reached.")
        break

Sample Output:

Round 1
Legal Assistant: Based on U.S. labor law, employers can act on public social media content...
Client Advocate: However, was the post protected under First Amendment or NLRA Section 7?
...

You now have a live simulation of a legal team reasoning together using LLM agents.

🧠 Key Learnings

Clear Role Definitions lead to more purposeful interactions.
Agents that disagree and debate surface better decisions.
CAMEL-AI allows fine-grained control over multi-agent dialog.
Easily extendable to more agents with specialized knowledge.

💡 Final Thoughts

CAMEL-AI is more than just a framework—it’s a paradigm shift. We’re moving from instruction-following AIs to reasoning, negotiating, and collaborative agents that can truly scale with complexity.

If you’re building AI agents for real-world use—legal, educational, healthcare, or product—you owe it to yourself to explore CAMEL-AI.

“Don’t just think bigger. Think together.”

🧑‍💻 About the Author

I’m a developer and researcher passionate about building agentic AI systems with real-world impact. I work with CAMEL-AI, RAG, Groq, Streamlit, and open-source LLMs to prototype tools that think collaboratively.

📬 Reach out on LinkedIn | 🧵 Follow on Twitter | ⭐ Star on GitHub

MedAI Pro: Building an AI-Powered Medical Report Assistant Using GROQ,CAMEL-AI, and LLaMA 4

Tushar Singh — Sun, 04 May 2025 20:53:35 +0000

In today's digital health era, there's a growing need for tools that help users make sense of complex medical documents. This is where MedAI Pro comes into play — a streamlined, AI-powered assistant built with Streamlit, CAMEL-AI Agent, and LLaMA 4 via the GROQ-API, designed to interpret and explain PDF-based medical reports in a conversational manner.

In this blog, we’ll break down how the project works, explore the key technologies used, and guide you through how you can run or extend the app yourself.

✨ What is MedAI Pro?
MedAI Pro is a web application where users can upload their medical reports in PDF format, ask natural language questions about the content, and receive both a written and spoken response powered by a Large Language Model.

Key Features:

Upload and parse medical reports in PDF format
Chat interface for asking questions
Text and audio-based responses
Role-based CAMEL-AI agents for contextual answers

🩺 Imagine this... You're a doctor, student, or just someone trying to understand a lab report. You open a 50-page PDF filled with blood work, medical terms, and charts.

You have one question:

“Is the patient’s WBC count normal?”

But you're stuck scanning through paragraphs.

"Imagine asking a question and receiving the answer in just seconds—delivered seamlessly in both text and audio formats. Instant, accurate, and fully interactive!"

🔥 Meet Med-AI Med-AI is a blazing-fast PDF Q&A assistant for medical documents.

🗂 Project Structure
Here’s what the repository contains:

MedAi/
├── app.py                # Streamlit frontend and orchestrator
├── camel_agents.py       # CAMEL-style agent logic with LLaMA 4 and Groq API
├── parse_report.py       # PDF parsing logic using PyMuPDF
├── requirements.txt      # All required Python packages
├── .env                  # For storing API keys securely

🔍 Under the Hood: Code Breakdown
app.py: The Streamlit Web Interface
The main UI and logic control center. It lets users upload a
medical PDF, input a question, and then displays (and plays)
the AI’s response.

Streamlit is used to create an intuitive UI
PDF Uploading: st.file_uploader() allows users to upload a PDF
Parsing: Calls parse_report.py to extract readable text
Query Handling: User question and extracted report are sent to
camel_agents.py
Response: Displays the model's answer and converts it to audio
using gTTS

parse_report.py: Extracting Text from PDF
This module uses PyMuPDF (fitz) to read and extract text from
every page of the uploaded PDF.

import fitz  # PyMuPDF

   def extract_text_from_pdf(file):
       pdf = fitz.open(stream=file.read(), filetype="pdf")
       text = "\n".join(page.get_text() for page in pdf)
       return text

This ensures that medical data is accurately captured for AI processing

camel_agents.py: Role-Based Prompting with CAMEL + LLaMA 4

This module goes beyond traditional prompt engineering and implements a true CAMEL-style role-based agent architecture, using the official CAMEL AI structure — including:

ChatAgent

BaseMessage

RoleTypeonse.

👨‍⚕️ Role: Doctor Agent
Instead of just using raw strings to define prompts, MedAI uses a Doctor agent object with predefined role behavior. Here's how it looks:


   doctor = ChatAgent(
    system_message=BaseMessage(
        role_name="Doctor",
        role_type=RoleType.ASSISTANT,
        content="""You are a medical expert. Analyze reports and 
                 provide concise, medically accurate answers. 
                 Focus on lab values, terminology, and 
                conditions. Be factual, not speculative."""
    )
)

⚙️ Model Initialization: LLaMA 4 via Groq with CAMEL’s ModelFactory

The MedAI project leverages CAMEL AI’s modular model factory to connect with the latest LLaMA 4 model hosted on Groq. This is done through the ModelFactory API provided in the CAMEL agent framework.

self.model = ModelFactory.create(
    model_platform=ModelPlatformType.GROQ,
    model_type="meta-llama/llama-4-maverick-17b-128e-instruct"
)

.env: API Security

The .env file stores your Groq API key safely. It’s loaded using python-dotenv

   GROQ_API_KEY=your_actual_key_here

🚀 Running the Project

Step 1: Clone the Repo

git clone https://github.com/tushar80rt/MedAi
cd MedAi

Step 2:📦 Installation

camel-ai[all]

PyMuPDF==1.23.9

python-dotenv==1.0.1

streamlit

gTTS==2.5.1

groq

Step 3: Install Dependencies

pip install -r requirements.txt

Step 3: Add Your API Key

Create a .env file with your Groq key:

GROQ_API_KEY=your_api_key

Step 4: Run the App

streamlit run app.py

Visit http://localhost:8501, upload a report, and start asking questions.

🌐 Tech Stack

Frontend: Streamlit

PDF Parsing: PyMuPDF

LLM: LLaMA 4 via Groq API

Prompting Strategy: CAMEL AI-style agents

Audio Output: gTTS

🙌 Final Thoughts

MedAI Pro is a powerful yet minimalistic prototype that combines the power of modern LLMs, voice output, and agent-style prompting to deliver valuable insights from medical reports. By leveraging the CAMEL AI architecture and Groq-hosted LLaMA 4, it sets a strong foundation for future intelligent healthcare tools.

Fork it, run it, and build something impactful.

GitHub: https://github.com/tushar80rt/MedAi
Author: Tushar Singh

Have questions or suggestions? Drop a comment or open an issue!

Forem: Tushar Singh

Image Annotation Applications: A Complete

What Is Image Annotation?

Why Do We Need Image Annotation Applications?

Common Image Annotation Techniques

How Do Image Annotation Tools Help Machine Learning?

Benefits of Using Professional Annotation Tools

Where Are Image Annotation Applications Used?

Challenges in Image Annotation

What Makes a Good Image Annotation Tool?

The Future of Image Annotation

Frequently Asked Questions

Ready to Learn More About Image Annotation?

Image Annotation Applications: A Complete Guide

What Is Image Annotation?

Why Do We Need Image Annotation Applications?

Common Image Annotation Techniques

How Do Image Annotation Tools Help Machine Learning?

Benefits of Using Professional Annotation Tools

Where Are Image Annotation Applications Used?

Challenges in Image Annotation

What Makes a Good Image Annotation Tool?

The Future of Image Annotation

Frequently Asked Questions

Ready to Learn More About Image Annotation?

Labellerr SDK & YOLOv8: Cars and Number Plate Detection Practical, Step-by-Step

Project Overview

What is Labellerr?

What is YOLOv8?

Why Use Labellerr and YOLOv8 Together?

Project Setup

Step 1:

Step 2: Setting Up Kaggle Credentials

Step 3: Downloading the Dataset from Kaggle

Step 4: Preparing Sample Images for Inspection

Step 5: Connecting to Labellerr (Authentication)

Step 6: Creating Annotation Schema in Labellerr

Step 7: Create Annotation Template in Labellerr

What This Code Does

Step 8: Creating the Project in Labellerr & Uploading Images

Step 9: Linking an Existing Dataset to the Project in Labellerr

Step 10:Labeling Workflow in Labellerr (Step-by-Step)

Step 11: Exporting Labeled Dataset from Labellerr

Step 12: Installing YOLOv8 (Ultralytics)

Step 13: Convert Labellerr Export (JSON) → YOLOv8 Dataset + Train/Val Split

What This Script Does

Step 14: Convert Labellerr Annotations → YOLOv8 Labels (Function)

What This Function Does

Step 15: Creating dataset.yaml for YOLOv8

Understanding the dataset.yaml Fields

Step 16: Training YOLOv8 on Our Dataset

Step 17: Inference: Test the Trained YOLOv8 Model on Validation Images

What This Inference Code Does

Google Colab Notebook

🧠 Behind the Scenes of ClarityCare.AI: CAMEL-AI Toolkits That Power Your AI Wellness Companion

🎬 Project Demo

🐪 CAMEL-AI: Architecting the Future of Autonomous Multi-Agent Collaboration with LLMs

MedAI Pro: Building an AI-Powered Medical Report Assistant Using GROQ,CAMEL-AI, and LLaMA 4

Understanding the `dataset.yaml` Fields