omnimod-sdk 0.1.0__tar.gz

omnimod_sdk-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# OS/editor files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Secrets and local environment
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+
+# Node / frontend
+node_modules/
+.next/
+out/
+coverage/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Logs and local artifacts
+*.log
+tmp/
+temp/
+.cache/
+

omnimod_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Kavach LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omnimod_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: omnimod-sdk
+Version: 0.1.0
+Summary: Python SDK for the OmniMod moderation API
+Project-URL: Homepage, https://omnimod.net
+Project-URL: Documentation, https://omnimod.net/docs
+Project-URL: Source, https://github.com/DivyaHemantCareer/OmniModApp
+Project-URL: Support, https://omnimod.net/support
+Author-email: OmniMod <info@omnimod.net>
+Maintainer-email: OmniMod <info@omnimod.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: content-moderation,moderation,safety,trust-and-safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OmniMod Python SDK
+
+Small dependency-free Python client for the OmniMod API.
+
+## Install
+
+```bash
+python -m pip install omnimod-sdk
+```
+
+The package is published as `omnimod-sdk` and imported as `omnimod_sdk`.
+It requires Python 3.11 or newer and an approved OmniMod API key.
+
+## Usage
+
+```python
+from omnimod_sdk import OmniModClient
+
+client = OmniModClient(api_key="omad_live_...")
+result = client.moderate_text("hello community", policy="community-default")
+
+if result.is_blocked:
+    print("blocked", result.severity)
+```
+
+The SDK starts with text moderation. OpenAPI, TypeScript SDK, image helpers, async helpers, and richer typed policy/event APIs are planned after the core API contract stabilizes.

omnimod_sdk-0.1.0/README.md

@@ -0,0 +1,26 @@
+# OmniMod Python SDK
+
+Small dependency-free Python client for the OmniMod API.
+
+## Install
+
+```bash
+python -m pip install omnimod-sdk
+```
+
+The package is published as `omnimod-sdk` and imported as `omnimod_sdk`.
+It requires Python 3.11 or newer and an approved OmniMod API key.
+
+## Usage
+
+```python
+from omnimod_sdk import OmniModClient
+
+client = OmniModClient(api_key="omad_live_...")
+result = client.moderate_text("hello community", policy="community-default")
+
+if result.is_blocked:
+    print("blocked", result.severity)
+```
+
+The SDK starts with text moderation. OpenAPI, TypeScript SDK, image helpers, async helpers, and richer typed policy/event APIs are planned after the core API contract stabilizes.

omnimod_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "omnimod-sdk"
+version = "0.1.0"
+description = "Python SDK for the OmniMod moderation API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "OmniMod", email = "info@omnimod.net" },
+]
+maintainers = [
+    { name = "OmniMod", email = "info@omnimod.net" },
+]
+keywords = [
+    "content-moderation",
+    "moderation",
+    "safety",
+    "trust-and-safety",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://omnimod.net"
+Documentation = "https://omnimod.net/docs"
+Source = "https://github.com/DivyaHemantCareer/OmniModApp"
+Support = "https://omnimod.net/support"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omnimod_sdk"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

omnimod_sdk-0.1.0/src/omnimod_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""Python SDK for the OmniMod moderation API."""
+
+__version__ = "0.1.0"
+
+from omnimod_sdk.client import OmniModClient
+from omnimod_sdk.errors import (
+    OmniModAPIError,
+    OmniModAuthenticationError,
+    OmniModConnectionError,
+    OmniModError,
+    OmniModQuotaError,
+    OmniModRateLimitError,
+)
+from omnimod_sdk.models import ModerationResponse
+
+__all__ = [
+    "ModerationResponse",
+    "OmniModAPIError",
+    "OmniModAuthenticationError",
+    "OmniModClient",
+    "OmniModConnectionError",
+    "OmniModError",
+    "OmniModQuotaError",
+    "OmniModRateLimitError",
+]

omnimod_sdk-0.1.0/src/omnimod_sdk/client.py

@@ -0,0 +1,132 @@
+"""Synchronous OmniMod API client."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from omnimod_sdk import __version__
+from omnimod_sdk.errors import (
+    OmniModAPIError,
+    OmniModAuthenticationError,
+    OmniModConnectionError,
+    OmniModQuotaError,
+    OmniModRateLimitError,
+)
+from omnimod_sdk.models import ModerationResponse
+
+DEFAULT_BASE_URL = "https://api.omnimod.net"
+
+
+class OmniModClient:
+    """Client for the OmniMod moderation API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._user_agent = user_agent or f"omnimod-python/{__version__}"
+
+    def moderate_text(
+        self,
+        text: str,
+        *,
+        policy: str | None = None,
+        force_fresh: bool = False,
+        metadata: dict[str, Any] | None = None,
+        request_id: str | None = None,
+    ) -> ModerationResponse:
+        """Moderate text and return the normalized OmniMod response."""
+
+        if not text:
+            raise ValueError("text is required")
+        payload: dict[str, Any] = {
+            "modality": "text",
+            "input": text,
+            "language": "auto",
+            "force_fresh": force_fresh,
+        }
+        if policy is not None:
+            payload["policy"] = policy
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = self._post_json("/v1/moderations", payload, request_id=request_id)
+        return ModerationResponse.from_dict(data)
+
+    def _post_json(self, path: str, payload: dict[str, Any], *, request_id: str | None = None) -> dict[str, Any]:
+        body = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+        if request_id:
+            headers["X-Request-ID"] = request_id
+        request = Request(
+            f"{self._base_url}{path}",
+            data=body,
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urlopen(request, timeout=self._timeout) as response:  # noqa: S310 - URL is explicit SDK client input.
+                return _decode_json(response.read())
+        except HTTPError as exc:
+            raise _api_error(exc) from exc
+        except URLError as exc:
+            raise OmniModConnectionError(str(exc.reason)) from exc
+
+
+def _decode_json(body: bytes) -> dict[str, Any]:
+    if not body:
+        return {}
+    value = json.loads(body.decode("utf-8"))
+    if not isinstance(value, dict):
+        raise OmniModAPIError(status_code=0, message="Expected JSON object response", detail=value)
+    return value
+
+
+def _api_error(exc: HTTPError) -> OmniModAPIError:
+    body = exc.read()
+    try:
+        payload = _decode_json(body)
+    except (json.JSONDecodeError, UnicodeDecodeError, OmniModAPIError):
+        payload = {"detail": body.decode("utf-8", errors="replace")}
+    detail = payload.get("detail")
+    code = _detail_code(detail)
+    message = _detail_message(detail) or exc.reason or f"HTTP {exc.code}"
+    if exc.code in {401, 403}:
+        return OmniModAuthenticationError(status_code=exc.code, message=message, detail=detail, code=code)
+    if exc.code == 429 and code == "quota_exceeded":
+        return OmniModQuotaError(status_code=exc.code, message=message, detail=detail, code=code)
+    if exc.code == 429:
+        return OmniModRateLimitError(status_code=exc.code, message=message, detail=detail, code=code)
+    return OmniModAPIError(status_code=exc.code, message=message, detail=detail, code=code)
+
+
+def _detail_code(detail: Any) -> str | None:
+    if isinstance(detail, dict):
+        code = detail.get("code")
+        return str(code) if code is not None else None
+    return None
+
+
+def _detail_message(detail: Any) -> str | None:
+    if isinstance(detail, dict):
+        message = detail.get("message")
+        return str(message) if message is not None else None
+    if isinstance(detail, str):
+        return detail
+    return None

omnimod_sdk-0.1.0/src/omnimod_sdk/errors.py

@@ -0,0 +1,43 @@
+"""SDK exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OmniModError(Exception):
+    """Base exception for the OmniMod SDK."""
+
+
+class OmniModConnectionError(OmniModError):
+    """Raised when the SDK cannot reach the OmniMod API."""
+
+
+class OmniModAPIError(OmniModError):
+    """Raised when the OmniMod API returns an error response."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        message: str,
+        detail: Any = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.detail = detail
+        self.code = code
+
+
+class OmniModAuthenticationError(OmniModAPIError):
+    """Raised for invalid keys or disabled organizations."""
+
+
+class OmniModQuotaError(OmniModAPIError):
+    """Raised when monthly moderation quota is exhausted."""
+
+
+class OmniModRateLimitError(OmniModAPIError):
+    """Raised when the request is rate limited."""

omnimod_sdk-0.1.0/src/omnimod_sdk/models.py

@@ -0,0 +1,77 @@
+"""SDK response models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ModerationResponse:
+    """Normalized moderation response returned by OmniMod."""
+
+    id: str
+    request_id: str
+    decision: str
+    engine_action: str
+    modality: str
+    severity: str
+    scores: dict[str, float]
+    analyzer_results: list[dict[str, Any]]
+    policy: dict[str, Any]
+    provider: str
+    provider_version: str
+    provider_status: str
+    degraded_reason: str | None
+    routing: dict[str, Any]
+    language: dict[str, Any]
+    provider_usage: dict[str, Any]
+    processing_time_ms: float | None
+    created_at: str
+    cache: dict[str, Any]
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "ModerationResponse":
+        """Create a response model from the OmniMod API payload."""
+
+        return cls(
+            id=str(payload["id"]),
+            request_id=str(payload["request_id"]),
+            decision=str(payload["decision"]),
+            engine_action=str(payload["engine_action"]),
+            modality=str(payload["modality"]),
+            severity=str(payload["severity"]),
+            scores=dict(payload.get("scores") or {}),
+            analyzer_results=list(payload.get("analyzer_results") or []),
+            policy=dict(payload.get("policy") or {}),
+            provider=str(payload.get("provider") or ""),
+            provider_version=str(payload.get("provider_version") or ""),
+            provider_status=str(payload.get("provider_status") or ""),
+            degraded_reason=payload.get("degraded_reason"),
+            routing=dict(payload.get("routing") or {}),
+            language=dict(payload.get("language") or {}),
+            provider_usage=dict(payload.get("provider_usage") or {}),
+            processing_time_ms=payload.get("processing_time_ms"),
+            created_at=str(payload["created_at"]),
+            cache=dict(payload.get("cache") or {}),
+            raw=payload,
+        )
+
+    @property
+    def is_allowed(self) -> bool:
+        """Return whether the final decision is allow."""
+
+        return self.decision == "allow"
+
+    @property
+    def is_flagged(self) -> bool:
+        """Return whether the final decision is flag/review."""
+
+        return self.decision == "flag"
+
+    @property
+    def is_blocked(self) -> bool:
+        """Return whether the final decision is block."""
+
+        return self.decision == "block"

omnimod_sdk-0.1.0/src/omnimod_sdk/py.typed

@@ -0,0 +1 @@
+

omnimod_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from threading import Thread
+from typing import Any
+
+import pytest
+
+from omnimod_sdk import OmniModClient
+from omnimod_sdk.client import DEFAULT_BASE_URL
+from omnimod_sdk.errors import OmniModQuotaError, OmniModRateLimitError
+
+
+def test_default_base_url_uses_omnimod_net() -> None:
+    assert DEFAULT_BASE_URL == "https://api.omnimod.net"
+
+
+def test_moderate_text_sends_expected_request() -> None:
+    server = _TestServer(response=_moderation_payload())
+    try:
+        client = OmniModClient(api_key="omad_test_key", base_url=server.url)
+
+        result = client.moderate_text(
+            "hello community",
+            policy="community-default",
+            metadata={"external_id": "comment-1"},
+            request_id="req_sdk_test",
+        )
+
+        assert result.is_allowed is True
+        assert result.language == {"detected": "en", "confidence": 1.0}
+        assert result.routing == {"mode": "rules_only", "reason": "rules_clear"}
+        assert result.provider_usage == {"text_llm_credits": 0}
+        assert server.requests == [
+            {
+                "path": "/v1/moderations",
+                "authorization": "Bearer omad_test_key",
+                "request_id": "req_sdk_test",
+                "body": {
+                    "modality": "text",
+                    "input": "hello community",
+                    "language": "auto",
+                    "force_fresh": False,
+                    "policy": "community-default",
+                    "metadata": {"external_id": "comment-1"},
+                },
+            }
+        ]
+    finally:
+        server.close()
+
+
+def test_quota_error_maps_to_specific_exception() -> None:
+    server = _TestServer(
+        status=429,
+        response={
+            "detail": {
+                "code": "quota_exceeded",
+                "message": "Monthly moderation quota exceeded",
+                "remaining": 0,
+            }
+        },
+    )
+    try:
+        client = OmniModClient(api_key="omad_test_key", base_url=server.url)
+
+        with pytest.raises(OmniModQuotaError) as exc_info:
+            client.moderate_text("hello")
+
+        assert exc_info.value.status_code == 429
+        assert exc_info.value.code == "quota_exceeded"
+        assert exc_info.value.detail["remaining"] == 0
+    finally:
+        server.close()
+
+
+def test_rate_limit_error_maps_to_specific_exception() -> None:
+    server = _TestServer(
+        status=429,
+        response={
+            "detail": {
+                "code": "rate_limited",
+                "message": "Rate limit exceeded",
+                "reset_seconds": 60,
+            }
+        },
+    )
+    try:
+        client = OmniModClient(api_key="omad_test_key", base_url=server.url)
+
+        with pytest.raises(OmniModRateLimitError) as exc_info:
+            client.moderate_text("hello")
+
+        assert exc_info.value.status_code == 429
+        assert exc_info.value.code == "rate_limited"
+        assert exc_info.value.detail["reset_seconds"] == 60
+    finally:
+        server.close()
+
+
+class _TestServer:
+    def __init__(self, *, response: dict[str, Any], status: int = 200) -> None:
+        self.requests: list[dict[str, Any]] = []
+        self._response = response
+        self._status = status
+
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:  # noqa: N802
+                body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+                outer.requests.append(
+                    {
+                        "path": self.path,
+                        "authorization": self.headers.get("Authorization"),
+                        "request_id": self.headers.get("X-Request-ID"),
+                        "body": json.loads(body.decode("utf-8")),
+                    }
+                )
+                payload = json.dumps(outer._response).encode("utf-8")
+                self.send_response(outer._status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(payload)))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            def log_message(self, format: str, *args: object) -> None:
+                return None
+
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self._thread = Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    @property
+    def url(self) -> str:
+        host, port = self._server.server_address
+        return f"http://{host}:{port}"
+
+    def close(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        self._thread.join(timeout=2)
+
+
+def _moderation_payload() -> dict[str, Any]:
+    return {
+        "id": "mod_123",
+        "request_id": "req_sdk_test",
+        "decision": "allow",
+        "engine_action": "allow",
+        "modality": "text",
+        "severity": "none",
+        "scores": {"profanity": 0.0, "language": 0.0},
+        "analyzer_results": [],
+        "policy": {"id": "pol_123", "version_id": "pv_123", "version": 1},
+        "provider": "omnimod-engine",
+        "provider_version": "omnimod-engine-v1",
+        "provider_status": "complete",
+        "degraded_reason": None,
+        "routing": {"mode": "rules_only", "reason": "rules_clear"},
+        "language": {"detected": "en", "confidence": 1.0},
+        "provider_usage": {"text_llm_credits": 0},
+        "processing_time_ms": 12.5,
+        "created_at": "2026-05-07T00:00:00Z",
+        "cache": {"status": "miss", "content_hash": "sha256:abc"},
+    }