> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuteliq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK
> Install and use the Tuteliq Python SDK
The Tuteliq Python SDK provides both synchronous and asynchronous clients for the Tuteliq child safety API. It supports Python 3.9+.
## Installation
```bash theme={"dark"}
pip install tuteliq
```
## Initialize the client
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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
```python theme={"dark"}
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
Explore the full API specification.
See the Node.js SDK guide.