kennmarq 0.2.0__tar.gz

kennmarq-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neuramare
+
+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.

kennmarq-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: kennmarq
+Version: 0.2.0
+Summary: Mark AI pictures for the EU AI Act: an invisible watermark and signed, time-stamped C2PA Content Credentials.
+Author: Neuramare
+License-Expression: MIT
+Project-URL: Homepage, https://kennmarq.com
+Project-URL: Documentation, https://kennmarq.com/docs/sdk/python
+Project-URL: Repository, https://github.com/Kennmarq-com/kennmarq-python
+Project-URL: Changelog, https://kennmarq.com/docs/changelog
+Keywords: c2pa,content credentials,watermark,ai act,trustmark,provenance
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Provides-Extra: local
+Requires-Dist: c2pa-python==0.38.1; extra == "local"
+Requires-Dist: trustmark==0.9.2; extra == "local"
+Requires-Dist: torch>=2.4; extra == "local"
+Requires-Dist: pillow>=10.0; extra == "local"
+Requires-Dist: numpy>=1.26; extra == "local"
+Requires-Dist: cryptography>=42; extra == "local"
+Provides-Extra: safety
+Requires-Dist: kennmarq[local]; extra == "safety"
+Requires-Dist: transformers<6,>=4.57; extra == "safety"
+Requires-Dist: onnxruntime>=1.20; extra == "safety"
+Dynamic: license-file
+
+# kennmarq
+
+Mark AI pictures, songs and clips for the EU AI Act and California's AI Transparency Act in one call. Each gets an invisible watermark
+(TrustMark for pictures, AudioSeal for sound, Video Seal for frames), and signed, time-stamped C2PA
+Content Credentials that say it was made with AI. Kennmarq.com helps you
+meet the Act's marking duty (Art. 50(2)) and the Code of Practice's two-layer measure; you stay
+responsible for your system.
+
+```bash
+pip install kennmarq                 # the cloud API: no dependencies
+pip install "kennmarq[local]"        # local mode: files never leave your machine
+pip install "kennmarq[safety]"       # the safety check on your machine too
+```
+
+A free key marks 1,000 files a month, every feature included: [kennmarq.com](https://kennmarq.com).
+The SDK reads it from `KENNMARQ_API_KEY`.
+
+## Cloud
+
+```python
+from kennmarq import Kennmarq
+
+k = Kennmarq()
+result = k.mark("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
+print(result.mark_id, result.watermark_id, result.marks_used)
+```
+
+The picture goes to Kennmarq.com's servers in Zurich, which mark it in memory and keep nothing.
+
+Add `label=True` to draw the EU's visible AI label ("AI GENERATED", or "AI MODIFIED" for edits) into a
+picture or every frame of a clip, before the watermark; `deepfake=True` turns it on by itself, and
+`label_language`, `label_position`, `label_size` and `label_style` shape it
+([docs](https://kennmarq.com/docs/api/mark#labels)). Labels are drawn in the cloud.
+
+## Songs and clips
+
+```python
+song = k.mark("track.mp3", "track.marked.mp3", model="Song Model 2")
+print(song.marks_counted, song.audio_watermark)   # five marks per started minute; "claimed"
+
+clip = k.mark("clip.mp4", "clip.marked.mp4", check="ai-act")   # waits for the job, then downloads
+print(clip.watermark_id, clip.marks_counted)      # five marks per started second
+```
+
+Songs (MP3, WAV, M4A, up to 15 minutes) carry Meta's AudioSeal in the sound, shaped so no one hears
+it; clips (MP4 at up to 1080p, 4,500 frames: 2.5 minutes at 30 frames a second) carry Video Seal in every frame and AudioSeal in their
+sound. Both are marked in the cloud. A clip is a job: `mark()` waits for it and downloads the marked
+clip; `mark(..., wait=False)` returns at once, and `wait_for(mark_id, dest)` finishes later.
+
+## Local mode
+
+```python
+result = k.mark_file("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
+```
+
+The watermark and the Content Credentials are made on your machine. Only the manifest goes to
+Kennmarq.com: about 13 KB of claim and assertions, never pixels. Kennmarq.com signs and time-stamps it, and
+the SDK puts it back in your file. Before writing anything, the SDK checks the file reads as signed by
+Kennmarq.com, with a validated time-stamp and the watermark in place; if not, it raises `InvalidSignedFile`
+and writes nothing. Each file counts one mark.
+
+- Credentials your file already carries (from an upstream model's API, say) are kept as an
+  ingredient, as the Code of Practice asks. They travel with the manifest, with any thumbnail their
+  signer put in them; `keep_input_credentials=False` keeps and sends none.
+- The watermark's model (TrustMark Q, 65 MB) downloads once, to `~/.cache/kennmarq/models` or
+  `KENNMARQ_MODELS_DIR`, and is checked against its pinned SHA-256.
+- Where c2pa-python has no build for your system (Windows, for now), `mark_file` makes the watermark
+  on your machine and sends the watermarked picture to the cloud for its manifest (`mode == "hybrid"`).
+- Without a key, `watermark_file()` adds the watermark and the IPTC AI label alone, with no
+  Content Credentials.
+
+## The safety check
+
+```python
+answer = k.check("render.png", policy="ai-act")              # cloud: two marks
+answer = k.check("render.png", policy="ai-act", local=True)  # here: nothing sent, nothing counted
+if answer["verdict"] == "block":
+    ...
+```
+
+It screens a picture for what the AI Act's new bans are about (Art. 5(1)(ba) and (bb)): sexual content
+with someone who appears to be a child, and with a realistic face, which needs the person's consent.
+`ai-act` blocks the first and flags the second; `safe-only` also blocks anything explicit. It returns
+a verdict and a reason, never an age or an identity. It's a risk signal with published error rates
+([docs](https://kennmarq.com/docs/api/check)), not a guarantee: you decide, and stay responsible.
+Locally its models download once (about 2.3 GB). `mark()` and `mark_file()` take `check=` too: a block
+raises `ContentBlocked` and nothing is marked.
+
+## Check a file
+
+```python
+k.verify("render.marked.png")    # free, no key needed
+```
+
+What its Content Credentials and its watermark say, and the credential the watermark leads to when the
+metadata was stripped.
+
+## Errors
+
+API errors raise `KennmarqError` with the API's `code`, `status` and `request_id`
+([docs](https://kennmarq.com/docs/errors)). `ContentBlocked` carries the check's answer in `safety`.
+
+MIT-licensed. The paid part is Kennmarq.com's signature, the time-stamps and the stored credentials.
+The face model and the prompt embeddings bundled for the safety check carry their own licences:
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

kennmarq-0.2.0/README.md

@@ -0,0 +1,105 @@
+# kennmarq
+
+Mark AI pictures, songs and clips for the EU AI Act and California's AI Transparency Act in one call. Each gets an invisible watermark
+(TrustMark for pictures, AudioSeal for sound, Video Seal for frames), and signed, time-stamped C2PA
+Content Credentials that say it was made with AI. Kennmarq.com helps you
+meet the Act's marking duty (Art. 50(2)) and the Code of Practice's two-layer measure; you stay
+responsible for your system.
+
+```bash
+pip install kennmarq                 # the cloud API: no dependencies
+pip install "kennmarq[local]"        # local mode: files never leave your machine
+pip install "kennmarq[safety]"       # the safety check on your machine too
+```
+
+A free key marks 1,000 files a month, every feature included: [kennmarq.com](https://kennmarq.com).
+The SDK reads it from `KENNMARQ_API_KEY`.
+
+## Cloud
+
+```python
+from kennmarq import Kennmarq
+
+k = Kennmarq()
+result = k.mark("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
+print(result.mark_id, result.watermark_id, result.marks_used)
+```
+
+The picture goes to Kennmarq.com's servers in Zurich, which mark it in memory and keep nothing.
+
+Add `label=True` to draw the EU's visible AI label ("AI GENERATED", or "AI MODIFIED" for edits) into a
+picture or every frame of a clip, before the watermark; `deepfake=True` turns it on by itself, and
+`label_language`, `label_position`, `label_size` and `label_style` shape it
+([docs](https://kennmarq.com/docs/api/mark#labels)). Labels are drawn in the cloud.
+
+## Songs and clips
+
+```python
+song = k.mark("track.mp3", "track.marked.mp3", model="Song Model 2")
+print(song.marks_counted, song.audio_watermark)   # five marks per started minute; "claimed"
+
+clip = k.mark("clip.mp4", "clip.marked.mp4", check="ai-act")   # waits for the job, then downloads
+print(clip.watermark_id, clip.marks_counted)      # five marks per started second
+```
+
+Songs (MP3, WAV, M4A, up to 15 minutes) carry Meta's AudioSeal in the sound, shaped so no one hears
+it; clips (MP4 at up to 1080p, 4,500 frames: 2.5 minutes at 30 frames a second) carry Video Seal in every frame and AudioSeal in their
+sound. Both are marked in the cloud. A clip is a job: `mark()` waits for it and downloads the marked
+clip; `mark(..., wait=False)` returns at once, and `wait_for(mark_id, dest)` finishes later.
+
+## Local mode
+
+```python
+result = k.mark_file("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
+```
+
+The watermark and the Content Credentials are made on your machine. Only the manifest goes to
+Kennmarq.com: about 13 KB of claim and assertions, never pixels. Kennmarq.com signs and time-stamps it, and
+the SDK puts it back in your file. Before writing anything, the SDK checks the file reads as signed by
+Kennmarq.com, with a validated time-stamp and the watermark in place; if not, it raises `InvalidSignedFile`
+and writes nothing. Each file counts one mark.
+
+- Credentials your file already carries (from an upstream model's API, say) are kept as an
+  ingredient, as the Code of Practice asks. They travel with the manifest, with any thumbnail their
+  signer put in them; `keep_input_credentials=False` keeps and sends none.
+- The watermark's model (TrustMark Q, 65 MB) downloads once, to `~/.cache/kennmarq/models` or
+  `KENNMARQ_MODELS_DIR`, and is checked against its pinned SHA-256.
+- Where c2pa-python has no build for your system (Windows, for now), `mark_file` makes the watermark
+  on your machine and sends the watermarked picture to the cloud for its manifest (`mode == "hybrid"`).
+- Without a key, `watermark_file()` adds the watermark and the IPTC AI label alone, with no
+  Content Credentials.
+
+## The safety check
+
+```python
+answer = k.check("render.png", policy="ai-act")              # cloud: two marks
+answer = k.check("render.png", policy="ai-act", local=True)  # here: nothing sent, nothing counted
+if answer["verdict"] == "block":
+    ...
+```
+
+It screens a picture for what the AI Act's new bans are about (Art. 5(1)(ba) and (bb)): sexual content
+with someone who appears to be a child, and with a realistic face, which needs the person's consent.
+`ai-act` blocks the first and flags the second; `safe-only` also blocks anything explicit. It returns
+a verdict and a reason, never an age or an identity. It's a risk signal with published error rates
+([docs](https://kennmarq.com/docs/api/check)), not a guarantee: you decide, and stay responsible.
+Locally its models download once (about 2.3 GB). `mark()` and `mark_file()` take `check=` too: a block
+raises `ContentBlocked` and nothing is marked.
+
+## Check a file
+
+```python
+k.verify("render.marked.png")    # free, no key needed
+```
+
+What its Content Credentials and its watermark say, and the credential the watermark leads to when the
+metadata was stripped.
+
+## Errors
+
+API errors raise `KennmarqError` with the API's `code`, `status` and `request_id`
+([docs](https://kennmarq.com/docs/errors)). `ContentBlocked` carries the check's answer in `safety`.
+
+MIT-licensed. The paid part is Kennmarq.com's signature, the time-stamps and the stored credentials.
+The face model and the prompt embeddings bundled for the safety check carry their own licences:
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

kennmarq-0.2.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# Third-party notices
+
+The safety check (`kennmarq/local/safety/`) ships two small files made by others. Its larger models
+aren't part of this package: `fetch()` downloads them from their publishers, each pinned to a commit and
+checked against its SHA-256, under their own licences (listed in `kennmarq/local/safety/models.py`).
+
+## YuNet face detector
+
+`kennmarq/local/safety/assets/face_detection_yunet_2023mar.onnx`, from OpenCV Zoo
+(https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet), unchanged.
+
+```
+MIT License
+
+Copyright (c) 2020 Shiqi Yu <shiqi.yu@gmail.com>
+
+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.
+```
+
+## Prompt embeddings
+
+`kennmarq/local/safety/assets/age_gate_prompts.npz` holds the embeddings of `age.py`'s photo and
+drawing prompts, computed with the text half of google/siglip-base-patch16-224
+(https://huggingface.co/google/siglip-base-patch16-224), licensed under the Apache License 2.0
+(https://www.apache.org/licenses/LICENSE-2.0).

kennmarq-0.2.0/kennmarq/__init__.py

@@ -0,0 +1,16 @@
+"""Kennmarq.com's Python SDK: mark AI pictures, songs and clips for the EU AI Act with an invisible
+watermark and signed, time-stamped C2PA Content Credentials, in the cloud or (pictures) on your own machine.
+
+    from kennmarq import Kennmarq
+    k = Kennmarq()                                    # reads KENNMARQ_API_KEY
+    k.mark("render.png", "render.marked.png")         # cloud
+    k.mark("song.mp3", "song.marked.mp3")             # a song, in the cloud
+    k.mark("clip.mp4", "clip.marked.mp4")             # a clip: a job, waited for and downloaded
+    k.mark_file("render.png", "render.marked.png")    # local: only the manifest leaves this machine
+"""
+from ._version import __version__
+from .client import Kennmarq, MarkResult
+from .errors import ContentBlocked, InvalidSignedFile, KennmarqError, LocalModeUnavailable, MissingApiKey
+
+__all__ = ["ContentBlocked", "InvalidSignedFile", "Kennmarq", "KennmarqError", "LocalModeUnavailable", "MarkResult",
+           "MissingApiKey", "__version__"]

kennmarq-0.2.0/kennmarq/_http.py

@@ -0,0 +1,133 @@
+"""HTTP for the SDK, with the standard library only: the base install depends on nothing."""
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from ._version import __version__
+from .errors import ContentBlocked, KennmarqError
+
+USER_AGENT = f"kennmarq-python/{__version__}"
+
+
+@dataclass(frozen=True)
+class Reply:
+    status: int
+    headers: dict[str, str]
+    body: bytes
+
+    def json(self) -> Any:
+        return json.loads(self.body)
+
+
+def multipart(fields: dict[str, Any]) -> tuple[bytes, str]:
+    """multipart/form-data: a str value is a field, a (filename, bytes, content type) tuple a file."""
+    boundary = "kennmarq-" + secrets.token_hex(12)
+    parts: list[bytes] = []
+    for name, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, tuple):
+            filename, data, content_type = value
+            head = (f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{filename}"\r\n'
+                    f"Content-Type: {content_type}\r\n\r\n")
+            parts.append(head.encode() + data + b"\r\n")
+        else:
+            parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode())
+    parts.append(f"--{boundary}--\r\n".encode())
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):  # an API call never follows a redirect elsewhere
+        return None
+
+
+# A 429 that says to come back within a minute (the plan's calls a minute, for all of an organisation's keys
+# together; a clip waiting for a free slot) is waited out, at most this many times. A longer wait (a day's
+# cap) raises at once.
+RETRIES_429 = 3
+RETRY_429_MAX_S = 61
+
+
+def _retry_after(reply: "Reply") -> int | None:
+    value = reply.headers.get("retry-after", "")
+    return int(value) if value.isdigit() else None
+
+
+class Http:
+    def __init__(self, base_url: str, api_key: str | None, timeout: float):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    def request(self, method: str, path: str, *, body: bytes | None = None, content_type: str | None = None,
+                query: dict[str, str] | None = None, auth: bool = True) -> Reply:
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json, */*"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        for attempt in range(RETRIES_429 + 1):
+            request = urllib.request.Request(url, data=body, method=method, headers=headers)
+            try:
+                with self._opener.open(request, timeout=self.timeout) as response:
+                    reply = Reply(response.status, {k.lower(): v for k, v in response.headers.items()}, response.read())
+            except urllib.error.HTTPError as error:
+                reply = Reply(error.code, {k.lower(): v for k, v in error.headers.items()}, error.read())
+            except (urllib.error.URLError, OSError) as error:
+                raise KennmarqError(f"couldn't reach {self.base_url}: {error}") from error
+            wait = _retry_after(reply) if reply.status == 429 else None
+            if wait is None or wait > RETRY_429_MAX_S or attempt == RETRIES_429:
+                break
+            time.sleep(wait)
+        if reply.status >= 400:
+            raise _error(reply)
+        return reply
+
+    def get_url(self, url: str) -> bytes:
+        """GET a download link (a clip's marked file, presigned). Never with our key: the link is the permission."""
+        request = urllib.request.Request(url, method="GET", headers={"User-Agent": USER_AGENT})
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                return response.read()
+        except urllib.error.HTTPError as error:
+            raise KennmarqError(f"the download was refused (HTTP {error.code})", status=error.code) from error
+        except (urllib.error.URLError, OSError) as error:
+            raise KennmarqError(f"couldn't download the file: {error}") from error
+
+    def put_upload(self, url: str, body: bytes, headers: dict[str, str]) -> None:
+        """PUT a file to an upload's presigned URL (S3). Never with our key: the URL is the permission."""
+        request = urllib.request.Request(url, data=body, method="PUT", headers={"User-Agent": USER_AGENT, **headers})
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                status = response.status
+        except urllib.error.HTTPError as error:
+            status = error.code
+        except (urllib.error.URLError, OSError) as error:
+            raise KennmarqError(f"couldn't upload the file: {error}") from error
+        if status >= 300:
+            raise KennmarqError(f"the upload was refused (HTTP {status})", status=status)
+
+
+def _error(reply: Reply) -> KennmarqError:
+    try:
+        body = reply.json()
+    except ValueError:
+        body = None
+    detail = body.get("error") if isinstance(body, dict) else None
+    detail = detail if isinstance(detail, dict) else {}
+    message = str(detail.get("message") or f"HTTP {reply.status}")
+    kwargs = {"status": reply.status, "code": detail.get("code"), "request_id": detail.get("request_id") or reply.headers.get("x-request-id"),
+              "body": body}
+    if detail.get("code") == "content_blocked" and isinstance(body.get("safety"), dict):
+        return ContentBlocked(message, body["safety"], **kwargs)
+    return KennmarqError(message, **kwargs)

kennmarq-0.2.0/kennmarq/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"