If you need programmatic access to the Nahw platform, look no further. The Nahw Python SDK gives you convenient access to our API, with functions for creating projects, uploading tasks in bulk, managing the project lifecycle, and exporting results. It's open-source and available on PyPI today.

In this post, we'll walk through a sample project from start to finish.

1. Installation

First, install the package via pip:

pip install nahw-python

Requires Python 3.10+.

2. Authentication

Your API key is available on your profile page. Pass it directly to the client:

from nahw import NahwClient
 
client = NahwClient(api_key="nhw_...")

Or set it as an environment variable and leave the constructor empty:

export NAHW_API_KEY=nhw_...

The client also supports context manager usage if you prefer to manage the connection explicitly:

with NahwClient(api_key="nhw_...") as client:
    projects = client.projects.list()

3. Creating a project

Create a new labeling project with a name, instructions for the workforce, and payment settings:

project = client.projects.create(
    "Arabic Sentiment Labels",
    instructions="Label the sentiment of each Arabic audio clip.",
    num_workers_per_task=3,
    payment_per_response=0.10,
)

4. Adding tasks

Once your project exists, add the data you want labeled. Each item becomes a task that gets sent to a worker.

Add a single task:

client.tasks.create(project["id"], fields={"text": "أنا سعيد جداً بهذا المنتج"})

Or upload in bulk (up to 10,000 at a time):

client.tasks.create_bulk(project["id"], [
    {"fields": {"text": "خدمة ممتازة"}},
    {"fields": {"text": "تجربة سيئة للغاية"}},
])

You can also load directly from a CSV:

import csv
 
with open("clips.csv") as f:
    rows = list(csv.DictReader(f))
 
client.tasks.create_from_csv(project["id"], rows)

5. Launching the project

When your tasks are ready, launch the project to send it to the workforce:

client.projects.launch(project["id"])

You can pause and resume at any time:

client.projects.pause(project["id"])
client.projects.resume(project["id"])

6. Setting gold standards

Gold standards let you verify worker quality by embedding tasks with known correct answers. Any worker who gets them wrong is flagged for review.

client.tasks.set_gold_standard("task_123", answers={"sentiment": "positive"})

7. Exporting results

Once labeling is complete, generate a report and download it:

client.reports.create(project["id"], type="json")
 
# Check status
status = client.reports.get_status(project["id"])
 
# Download when ready
client.reports.download("rpt_123", "results.json")

Reports are also available in CSV, aggregated CSV, and flattened CSV formats.

Error handling

All API errors raise typed exceptions so you can handle them precisely:

from nahw import NahwNotFoundError, NahwAuthenticationError
 
try:
    client.projects.get("nonexistent")
except NahwNotFoundError as e:
    print(f"Not found: {e.message}")
except NahwAuthenticationError:
    print("Check your API key.")

Get started

The SDK is open-source on GitHub. Install it with pip install nahw-python and book a demo if you want to talk through your use case.