Skip to main content
The Tuteliq Python SDK provides both synchronous and asynchronous clients for the Tuteliq child safety API. It supports Python 3.9+.

​
Installation

pip install tuteliq

​
Initialize the client

from tuteliq import Tuteliq

client = Tuteliq(api_key="YOUR_API_KEY")
Never hardcode API keys in source code. Use environment variables or a secrets manager.
import os
from tuteliq import Tuteliq

client = Tuteliq(api_key=os.environ["TUTELIQ_API_KEY"])

​
Detect unsafe content

Scan a single text input for harmful content across all KOSA categories. 
result = client.detect_unsafe(
    text="Let's meet at the park after school, don't tell your parents",
    age_group="10-12",
)

print(result.safe)        # False
print(result.severity)    # "high"
print(result.categories)  # ["grooming", "secrecy"]

​
Detect grooming patterns

Analyze a conversation history for grooming indicators. 
result = client.detect_grooming(
    messages=[
        {"role": "stranger", "text": "Hey, how old are you?"},
        {"role": "child", "text": "I'm 11"},
        {"role": "stranger", "text": "Cool. Do you have your own phone?"},
        {"role": "stranger", "text": "Let's talk on a different app, just us"},
    ],
    age_group="10-12",
)

print(result.grooming_detected)  # True
print(result.risk_score)         # 0.92
print(result.stage)              # "isolation"

​
Analyze emotions

Evaluate emotional well-being from conversation text. 
result = client.analyze_emotions(
    text="Nobody at school talks to me anymore. I just sit alone every day.",
    age_group="13-15",
)

print(result.emotions)    # [{"label": "sadness", "score": 0.87}, ...]
print(result.distress)    # True
print(result.risk_level)  # "elevated"

​
Analyze voice

Upload an audio file for transcription and safety analysis. 
result = client.analyze_voice(
    file=open("recording.wav", "rb"),
    age_group="13-15",
)

print(result.transcript)
print(result.safe)
print(result.emotions)

​
Fraud detection and safety extended

These methods cover financial exploitation, romance scams, and coercive behaviour targeting minors. Other endpoints — detect_app_fraud, detect_mule_recruitment, detect_gambling_harm, detect_coercive_control, and detect_radicalisation — follow the same call pattern shown here.

​
Detect social engineering

Identify manipulation tactics designed to trick a child into disclosing information or taking unsafe actions. 
result = client.detect_social_engineering(
    text="If you really trusted me you'd send me your home address. All my real friends do.",
    age_group="10-12",
)

print(result.detected)     # True
print(result.tactics)      # ["trust_exploitation", "peer_pressure"]
print(result.risk_score)   # 0.88

​
Detect romance scam

Analyze conversation text for romantic manipulation patterns that may indicate an adult posing as a peer. 
result = client.detect_romance_scam(
    messages=[
        {"role": "stranger", "text": "I've never felt this way about anyone before. You're so mature for your age."},
        {"role": "child", "text": "Really? That makes me really happy."},
        {"role": "stranger", "text": "I need you to keep us a secret. People wouldn't understand."},
    ],
    age_group="13-15",
)

print(result.detected)     # True
print(result.risk_score)   # 0.91
print(result.indicators)   # ["love_bombing", "secrecy_request", "age_flattery"]

​
Detect vulnerability exploitation

Detect attempts to identify and target emotional or situational vulnerabilities in a child. 
result = client.detect_vulnerability_exploitation(
    text="I know you said your parents don't listen to you. I'm different — I actually care. You can tell me anything.",
    age_group="13-15",
)

print(result.detected)          # True
print(result.risk_score)        # 0.85
print(result.vulnerabilities)   # ["parental_conflict", "emotional_neglect"]

​
Analyse multiple texts in one request

Run any supported detection across multiple texts in a single API call to reduce round-trips. 
result = client.analyse_multi(
    inputs=[
        {"text": "You're so special. Nobody else understands you like I do.", "age_group": "13-15"},
        {"text": "Can you keep a secret from your mum?", "age_group": "10-12"},
    ],
    detections=["social-engineering", "romance-scam", "grooming"],
)

print(result.results[0].detections)  # {"social_engineering": {"detected": True, ...}, ...}
print(result.results[1].detections)  # {"grooming": {"detected": True, ...}, ...}
analyse_multi is billed per individual input × detection combination, not per request.

​
Async support

For asynchronous applications, use the AsyncTuteliq client. It exposes the same methods with await syntax. 
import asyncio
from tuteliq import AsyncTuteliq

client = AsyncTuteliq(api_key=os.environ["TUTELIQ_API_KEY"])

async def main():
    result = await client.detect_unsafe(
        text="example message to analyze",
        age_group="13-15",
    )
    print(result.safe)

asyncio.run(main())
AsyncTuteliq is ideal for frameworks like FastAPI, aiohttp, and Django with ASGI. It uses httpx under the hood.

​
Error handling

The SDK raises typed exceptions that you can catch and inspect. 
from tuteliq import Tuteliq, TuteliqError

client = Tuteliq(api_key="YOUR_API_KEY")

try:
    result = client.detect_unsafe(
        text="some content",
        age_group="10-12",
    )
except TuteliqError as e:
    print(e.code)     # e.g. "AUTH_INVALID_KEY"
    print(e.message)  # human-readable description
    print(e.status)   # HTTP status code

​
Configuration options

client = Tuteliq(
    api_key=os.environ["TUTELIQ_API_KEY"],
    base_url="https://api.tuteliq.ai",  # default
    timeout=30.0,                         # request timeout in seconds
    retries=2,                            # automatic retries on failure
)

​
Next steps

API Reference

Explore the full API specification.

Node.js SDK

See the Node.js SDK guide.