Python SDK

Installation (Coming Soon)

pip install sieve-mod

Quick Example (Coming Soon)

from sieve import Sieve

client = Sieve(api_key=os.environ["SIEVE_API_KEY"])

result = client.moderate.text(
    text="Message to moderate",
    context="chat",
    username="player123",
)

if result.action == "block":
    print(f"Blocked for: {result.primary_category}")

Using the API Directly

Until the SDK is available, use requests to call the Sieve API:

import os
import requests

def moderate(text: str, context: str = "default", username: str = None) -> dict:
    response = requests.post(
        "https://api.getsieve.dev/v1/moderate/text",
        headers={
            "Authorization": f"Bearer {os.environ['SIEVE_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "text": text,
            "context": context,
            "username": username,
        },
    )
    response.raise_for_status()
    return response.json()

result = moderate("Hello world", context="chat", username="player123")

match result["action"]:
    case "block":
        print(f"Blocked for: {result['primary_category']}")
    case "flag":
        print(f"Flagged for review: {result['primary_category']}")
    case "allow":
        print("Content is clean")

import os
import httpx

async def moderate(text: str, context: str = "default", username: str = None) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.getsieve.dev/v1/moderate/text",
            headers={
                "Authorization": f"Bearer {os.environ['SIEVE_API_KEY']}",
            },
            json={
                "text": text,
                "context": context,
                "username": username,
            },
        )
        response.raise_for_status()
        return response.json()

result = await moderate("Hello world", context="chat")
print(result["action"])  # "allow" | "flag" | "block"

import os
import aiohttp

async def moderate(text: str, context: str = "default", username: str = None) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.getsieve.dev/v1/moderate/text",
            headers={
                "Authorization": f"Bearer {os.environ['SIEVE_API_KEY']}",
                "Content-Type": "application/json",
            },
            json={
                "text": text,
                "context": context,
                "username": username,
            },
        ) as response:
            response.raise_for_status()
            return await response.json()

Django Integration

import requests
from django.conf import settings

class SieveModerationMiddleware:
    """Moderate user-generated content before saving."""

    @staticmethod
    def moderate(text, context="default", username=None):
        try:
            response = requests.post(
                "https://api.getsieve.dev/v1/moderate/text",
                headers={"Authorization": f"Bearer {settings.SIEVE_API_KEY}"},
                json={"text": text, "context": context, "username": username},
                timeout=2,
            )
            response.raise_for_status()
            return response.json()
        except requests.RequestException:
            # Fail open
            return {"action": "allow"}

# views.py
def create_post(request):
    result = SieveModerationMiddleware.moderate(
        text=request.POST["body"],
        context="forum_post",
        username=request.user.username,
    )

    if result["action"] == "block":
        return JsonResponse({"error": "Content violates community guidelines"}, status=422)

    # Save and publish
    post = Post.objects.create(body=request.POST["body"], author=request.user)
    return JsonResponse({"id": post.id})

Error Handling

import requests

try:
    response = requests.post(
        "https://api.getsieve.dev/v1/moderate/text",
        headers={"Authorization": f"Bearer {os.environ['SIEVE_API_KEY']}"},
        json={"text": text, "context": "chat"},
        timeout=2,
    )
    response.raise_for_status()
    result = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 429:
        retry_after = e.response.headers.get("Retry-After", 1)
        print(f"Rate limited. Retry after {retry_after}s")
    elif e.response.status_code == 401:
        print("Invalid API key")
    else:
        print(f"API error: {e.response.status_code}")
    # Fail open
    result = {"action": "allow"}
except requests.exceptions.Timeout:
    print("Request timed out")
    result = {"action": "allow"}