CalmLens Python SDK

Server-side Python SDK for CalmLens content moderation, storage and CDN delivery. It requires Python 3.10 or later, has no runtime dependencies and is fully typed (py.typed, checked with mypy --strict).

Install

python -m pip install calmlens

Quick start

Create an API key and copy your project ID as described in Authentication. Keep both on your server.

from calmlens import CalmLensServerClient

# Reads CALMLENS_API_KEY and CALMLENS_PROJECT_ID from the environment when not passed.
client = CalmLensServerClient()

asset = client.text.classify(text="Great photo!", external_id="comment-42")
if asset["classification"]["moderation"]["status"] == "allowed":
    print("Allowed: safe to show")

with open("photo.jpg", "rb") as file:  # streamed, not read into memory
    queued = client.assets.create(name="photo.jpg", content={"data": file, "type": "image/jpeg"})

decided = client.assets.wait_for_decision(asset_id=queued["id"], timeout=30)

Methods take snake_case keyword arguments, or one options dict with the API's camelCase keys (client.assets.retrieve({"assetId": "..."})). Responses are plain dicts with the API's camelCase field names, typed as TypedDicts in calmlens.types.

assets.create queues processing; assets.classify and text.classify wait for the decision. Act on classification.moderation.status:

Treat a status you don't recognise, and a failed request, as not allowed.

What you can do

• Moderate text, images, audio and video and read the classification report.
• Stream uploads, including multipart uploads and uploads from a URL.
• Moderate replies with their conversation.
• Sign upload tokens for upload presets used from browsers.
• Manage assets: list, search, update, move, retry, record reviewer decisions, explain decisions and delete content.
• Organise assets in folders and compare uploads with hash lists.
• Deliver content through the CDN with lenses and transforms, signed URLs and viewer claims.
• Verify and parse webhooks from Flask, Django or FastAPI, or poll the events feed.
• Handle errors with stable error codes, and rely on safe retries and idempotency keys.
• Configure the client: timeouts, proxies, connection reuse across threads and forked workers, and use from asyncio.

Testing

MockCalmLensServerClient from calmlens.testing is the real client with an in-memory API behind it, for offline tests. Its generate_test_text_code, paint_test_image and generate_media_test_code make signed test inputs that the real API answers with the scenario you choose, using your project's test input key. See Python testing.

Command-line tool

Use the standalone CalmLens CLI to forward signed webhook events to your machine and trigger test uploads.

Links

• Documentation
• SDK reference
• API reference
• Changelog
• License (MIT)