clawid 0.1.0__tar.gz

clawid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 hawky.ai (https://hawky.ai)
+
+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.

clawid-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: clawid
+Version: 0.1.0
+Summary: Invisible & visible watermarking SDK for AI-generated images and video
+Author-email: "hawky.ai Research" <research@hawky.ai>
+License: MIT
+Project-URL: Homepage, https://hawky.ai
+Project-URL: Repository, https://github.com/Hawky-ai/clawID
+Project-URL: Bug Tracker, https://github.com/Hawky-ai/clawID/issues
+Keywords: watermarking,steganography,AI,image,provenance,SynthID,C2PA,digital-rights,generative-ai,hawky
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: PyWavelets>=1.3.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.23.0; extra == "api"
+Requires-Dist: python-multipart>=0.0.6; extra == "api"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.0.0; extra == "mongo"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0.0; extra == "redis"
+Provides-Extra: video
+Requires-Dist: imageio[ffmpeg]>=2.28.0; extra == "video"
+Provides-Extra: spaces
+Requires-Dist: gradio>=4.0.0; extra == "spaces"
+Provides-Extra: all
+Requires-Dist: clawid[api,mongo,postgres,redis,video]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+# clawID
+
+**Invisible & visible watermarking SDK for AI-generated images and video.**
+
+[![PyPI](https://img.shields.io/pypi/v/clawid)](https://pypi.org/project/clawid/)
+[![Python](https://img.shields.io/pypi/pyversions/clawid)](https://pypi.org/project/clawid/)
+[![CI](https://github.com/Hawky-ai/clawID/actions/workflows/ci.yml/badge.svg)](https://github.com/Hawky-ai/clawID/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> A research project by **[hawky.ai](https://hawky.ai)** — the AI content provenance platform.
+
+clawID embeds a UUID-based watermark into images and video frames — invisible to the human eye but detectable by the SDK. Inspired by Google SynthID. Built for AI-generated asset provenance tracking.
+
+---
+
+## Features
+
+- **Invisible watermarking** via DWT-QIM (Discrete Wavelet Transform + Quantization Index Modulation)
+- **Resize-robust mode** (`algorithm='fm'`) — survives ±35% resize, JPEG compression, and minor edits
+- **Visible watermarking** — overlay text/logo with configurable opacity and position
+- **Video support** — watermark every Nth frame; detect from any single watermarked frame
+- **REST API** — FastAPI server with `/embed` and `/detect` endpoints
+- **Storage backends** — SQLite, PostgreSQL, MongoDB, Redis
+- **CLI** — `clawid embed`, `clawid detect`, `clawid embed-video`, `clawid detect-video`
+
+---
+
+## Installation
+
+```bash
+# Core (images only)
+pip install clawid
+
+# With video support
+pip install "clawid[video]"
+
+# With REST API
+pip install "clawid[api]"
+
+# Everything
+pip install "clawid[all]"
+```
+
+---
+
+## Quick Start
+
+### Images
+
+```python
+from clawid import embed, detect
+
+# Embed invisible watermark
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123', 'platform': 'hawky.ai'},
+)
+print(meta['clawid'])  # e.g. "3f2a1b4c-..."
+
+# Detect
+result = detect('photo_wm.png')
+print(result['uid'])       # creator123
+print(result['platform'])  # hawky.ai
+```
+
+### Resize-robust mode
+
+```python
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123'},
+    algorithm='fm',   # survives ±35% resize
+)
+```
+
+### Video
+
+```python
+from clawid import embed_video, detect_video
+
+meta = embed_video(
+    'input.mp4',
+    'output_wm.mp4',
+    metadata={'uid': 'creator123', 'platform': 'hawky.ai'},
+    frame_stride=5,   # watermark every 5th frame
+)
+
+result = detect_video('output_wm.mp4')
+print(result['uid'])  # creator123
+```
+
+### Visible watermark
+
+```python
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123'},
+    mode='visible',     # or 'both' for invisible + visible
+    opacity=0.6,
+    position='bottom-right',
+)
+```
+
+---
+
+## CLI
+
+```bash
+# Embed
+clawid embed -i photo.jpg -o photo_wm.png --uid creator123 --platform hawky.ai
+
+# Embed (resize-robust)
+clawid embed -i photo.jpg -o photo_wm.png --uid creator123 --algorithm fm
+
+# Detect
+clawid detect -i photo_wm.png
+
+# Video
+clawid embed-video -i input.mp4 -o output_wm.mp4 --uid creator123
+clawid detect-video -i output_wm.mp4
+
+# Save to SQLite store on embed, enrich on detect
+clawid embed -i photo.jpg -o wm.png --uid creator123 --store sqlite:///clawid.db
+clawid detect -i wm.png --store sqlite:///clawid.db
+```
+
+---
+
+## REST API
+
+```bash
+pip install "clawid[api]"
+clawid serve --store sqlite:///clawid.db --port 8000
+```
+
+**Endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/embed` | Upload image, get back watermarked image + metadata |
+| `POST` | `/detect` | Upload image, get back detected metadata |
+| `GET`  | `/docs`   | Interactive Swagger UI |
+
+```bash
+# Embed via API
+curl -X POST http://localhost:8000/embed \
+  -F "file=@photo.jpg" \
+  -F "uid=creator123" \
+  -F "platform=hawky.ai" \
+  --output photo_wm.png
+
+# Detect via API
+curl -X POST http://localhost:8000/detect \
+  -F "file=@photo_wm.png"
+```
+
+---
+
+## Storage Backends
+
+```python
+from clawid.storage import from_uri
+
+# SQLite (local)
+with from_uri('sqlite:///clawid.db') as store:
+    store.save(meta['clawid'], meta)
+    record = store.get(meta['clawid'])
+
+# PostgreSQL
+with from_uri('postgresql://user:pass@localhost/mydb') as store:
+    store.save(meta['clawid'], meta)
+
+# MongoDB
+with from_uri('mongodb://localhost:27017/mydb') as store:
+    store.save(meta['clawid'], meta)
+
+# Redis
+with from_uri('redis://localhost:6379/0') as store:
+    store.save(meta['clawid'], meta)
+```
+
+---
+
+## How It Works
+
+### Invisible watermark (DWT-QIM)
+
+The payload (UUID + metadata, CBOR-encoded + CRC-checked) is serialised to bits, then each bit is embedded by quantizing a coefficient in the Haar wavelet LL2 sub-band. Each LL2 coefficient represents a 4×4 pixel block, so a change of `delta/16 ≈ 2+ pixels` per block — above the uint8 quantization step — making the watermark survive JPEG compression and format round-trips.
+
+| Mode | Delta | PSNR | Survives |
+|------|-------|------|---------|
+| `qim` (default) | 32 | ~51 dB | PNG/JPEG q≥75, minor edits |
+| `fm` (resize-robust) | 192 | ~36 dB | ±35% resize, PNG/JPEG q≥75 |
+
+### Video watermarking
+
+Each video is processed frame by frame. Every Nth frame (`frame_stride`, default 5) receives the same DWT-QIM watermark with the same `clawid` UUID. Detection samples up to 10 frames and uses majority vote — detection succeeds as long as at least one watermarked frame survives.
+
+---
+
+## Docker
+
+```bash
+docker compose up
+# API available at http://localhost:8000
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Hawky-ai/clawID
+cd clawid
+pip install -e ".[dev,api,video]"
+pytest
+```
+
+---
+
+## License
+
+MIT

clawid-0.1.0/README.md

@@ -0,0 +1,226 @@
+# clawID
+
+**Invisible & visible watermarking SDK for AI-generated images and video.**
+
+[![PyPI](https://img.shields.io/pypi/v/clawid)](https://pypi.org/project/clawid/)
+[![Python](https://img.shields.io/pypi/pyversions/clawid)](https://pypi.org/project/clawid/)
+[![CI](https://github.com/Hawky-ai/clawID/actions/workflows/ci.yml/badge.svg)](https://github.com/Hawky-ai/clawID/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> A research project by **[hawky.ai](https://hawky.ai)** — the AI content provenance platform.
+
+clawID embeds a UUID-based watermark into images and video frames — invisible to the human eye but detectable by the SDK. Inspired by Google SynthID. Built for AI-generated asset provenance tracking.
+
+---
+
+## Features
+
+- **Invisible watermarking** via DWT-QIM (Discrete Wavelet Transform + Quantization Index Modulation)
+- **Resize-robust mode** (`algorithm='fm'`) — survives ±35% resize, JPEG compression, and minor edits
+- **Visible watermarking** — overlay text/logo with configurable opacity and position
+- **Video support** — watermark every Nth frame; detect from any single watermarked frame
+- **REST API** — FastAPI server with `/embed` and `/detect` endpoints
+- **Storage backends** — SQLite, PostgreSQL, MongoDB, Redis
+- **CLI** — `clawid embed`, `clawid detect`, `clawid embed-video`, `clawid detect-video`
+
+---
+
+## Installation
+
+```bash
+# Core (images only)
+pip install clawid
+
+# With video support
+pip install "clawid[video]"
+
+# With REST API
+pip install "clawid[api]"
+
+# Everything
+pip install "clawid[all]"
+```
+
+---
+
+## Quick Start
+
+### Images
+
+```python
+from clawid import embed, detect
+
+# Embed invisible watermark
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123', 'platform': 'hawky.ai'},
+)
+print(meta['clawid'])  # e.g. "3f2a1b4c-..."
+
+# Detect
+result = detect('photo_wm.png')
+print(result['uid'])       # creator123
+print(result['platform'])  # hawky.ai
+```
+
+### Resize-robust mode
+
+```python
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123'},
+    algorithm='fm',   # survives ±35% resize
+)
+```
+
+### Video
+
+```python
+from clawid import embed_video, detect_video
+
+meta = embed_video(
+    'input.mp4',
+    'output_wm.mp4',
+    metadata={'uid': 'creator123', 'platform': 'hawky.ai'},
+    frame_stride=5,   # watermark every 5th frame
+)
+
+result = detect_video('output_wm.mp4')
+print(result['uid'])  # creator123
+```
+
+### Visible watermark
+
+```python
+meta = embed(
+    source='photo.jpg',
+    output_path='photo_wm.png',
+    metadata={'uid': 'creator123'},
+    mode='visible',     # or 'both' for invisible + visible
+    opacity=0.6,
+    position='bottom-right',
+)
+```
+
+---
+
+## CLI
+
+```bash
+# Embed
+clawid embed -i photo.jpg -o photo_wm.png --uid creator123 --platform hawky.ai
+
+# Embed (resize-robust)
+clawid embed -i photo.jpg -o photo_wm.png --uid creator123 --algorithm fm
+
+# Detect
+clawid detect -i photo_wm.png
+
+# Video
+clawid embed-video -i input.mp4 -o output_wm.mp4 --uid creator123
+clawid detect-video -i output_wm.mp4
+
+# Save to SQLite store on embed, enrich on detect
+clawid embed -i photo.jpg -o wm.png --uid creator123 --store sqlite:///clawid.db
+clawid detect -i wm.png --store sqlite:///clawid.db
+```
+
+---
+
+## REST API
+
+```bash
+pip install "clawid[api]"
+clawid serve --store sqlite:///clawid.db --port 8000
+```
+
+**Endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/embed` | Upload image, get back watermarked image + metadata |
+| `POST` | `/detect` | Upload image, get back detected metadata |
+| `GET`  | `/docs`   | Interactive Swagger UI |
+
+```bash
+# Embed via API
+curl -X POST http://localhost:8000/embed \
+  -F "file=@photo.jpg" \
+  -F "uid=creator123" \
+  -F "platform=hawky.ai" \
+  --output photo_wm.png
+
+# Detect via API
+curl -X POST http://localhost:8000/detect \
+  -F "file=@photo_wm.png"
+```
+
+---
+
+## Storage Backends
+
+```python
+from clawid.storage import from_uri
+
+# SQLite (local)
+with from_uri('sqlite:///clawid.db') as store:
+    store.save(meta['clawid'], meta)
+    record = store.get(meta['clawid'])
+
+# PostgreSQL
+with from_uri('postgresql://user:pass@localhost/mydb') as store:
+    store.save(meta['clawid'], meta)
+
+# MongoDB
+with from_uri('mongodb://localhost:27017/mydb') as store:
+    store.save(meta['clawid'], meta)
+
+# Redis
+with from_uri('redis://localhost:6379/0') as store:
+    store.save(meta['clawid'], meta)
+```
+
+---
+
+## How It Works
+
+### Invisible watermark (DWT-QIM)
+
+The payload (UUID + metadata, CBOR-encoded + CRC-checked) is serialised to bits, then each bit is embedded by quantizing a coefficient in the Haar wavelet LL2 sub-band. Each LL2 coefficient represents a 4×4 pixel block, so a change of `delta/16 ≈ 2+ pixels` per block — above the uint8 quantization step — making the watermark survive JPEG compression and format round-trips.
+
+| Mode | Delta | PSNR | Survives |
+|------|-------|------|---------|
+| `qim` (default) | 32 | ~51 dB | PNG/JPEG q≥75, minor edits |
+| `fm` (resize-robust) | 192 | ~36 dB | ±35% resize, PNG/JPEG q≥75 |
+
+### Video watermarking
+
+Each video is processed frame by frame. Every Nth frame (`frame_stride`, default 5) receives the same DWT-QIM watermark with the same `clawid` UUID. Detection samples up to 10 frames and uses majority vote — detection succeeds as long as at least one watermarked frame survives.
+
+---
+
+## Docker
+
+```bash
+docker compose up
+# API available at http://localhost:8000
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Hawky-ai/clawID
+cd clawid
+pip install -e ".[dev,api,video]"
+pytest
+```
+
+---
+
+## License
+
+MIT

clawid-0.1.0/clawid/__init__.py

@@ -0,0 +1,18 @@
+from .core.embed import embed
+from .core.detect import detect
+from .video import embed_video, detect_video
+from .storage import ClawIDStore, SQLiteStore, PostgreSQLStore, MongoDBStore, RedisStore, from_uri
+
+__version__ = "0.1.0"
+__all__ = [
+    "embed",
+    "detect",
+    "embed_video",
+    "detect_video",
+    "ClawIDStore",
+    "SQLiteStore",
+    "PostgreSQLStore",
+    "MongoDBStore",
+    "RedisStore",
+    "from_uri",
+]

clawid-0.1.0/clawid/algorithms/dwt_qim.py

@@ -0,0 +1,144 @@
+"""
+Invisible watermarking via DWT + QIM (Quantization Index Modulation).
+
+Algorithm:
+  1. Compute luminance channel: Y = 0.299·R + 0.587·G + 0.114·B (float64, no color conversion)
+  2. Apply 2-level Haar DWT → extract LL2 sub-band (low-frequency, most robust region)
+  3. Embed bits using QIM:
+       bit=0 → quantize coefficient to nearest multiple of delta
+       bit=1 → quantize coefficient to nearest half-multiple (N+0.5)·delta
+  4. Reconstruct modified Y via inverse DWT
+  5. Distribute the per-pixel Y change back to all three RGB channels equally
+  6. Detect: apply same transform and read fractional parts of LL2 coefficients
+
+Working in float64 luminance and distributing back to RGB avoids YCbCr roundtrip errors.
+Each bit is stored REPEAT times; majority vote recovers the bit on detection.
+"""
+
+import numpy as np
+import pywt
+from PIL import Image
+from typing import List
+
+DELTA = 32.0   # quantization step — higher = more robust, slightly more visible
+               # 32 gives PSNR ~51 dB (imperceptible) and survives JPEG q≥85
+REPEAT = 3     # repetition factor for error correction via majority vote
+MIN_DIM = 256  # minimum image dimension in pixels
+
+
+def _luminance(arr: np.ndarray) -> np.ndarray:
+    """Compute perceptual luminance channel from float64 RGB array (H, W, 3)."""
+    return 0.299 * arr[:, :, 0] + 0.587 * arr[:, :, 1] + 0.114 * arr[:, :, 2]
+
+
+def embed_bits(
+    image: Image.Image,
+    bits: List[int],
+    delta: float = DELTA,
+    repeat: int = REPEAT,
+) -> Image.Image:
+    """
+    Embed a list of bits into an image invisibly using DWT-QIM.
+
+    Args:
+        image:  RGB PIL Image
+        bits:   list of 0/1 values to embed
+        delta:  quantization step (default 32.0)
+        repeat: repetition per bit for error correction (default 3)
+
+    Returns:
+        Watermarked RGB PIL Image (visually identical to input, PSNR > 50 dB)
+    """
+    if min(image.size) < MIN_DIM:
+        raise ValueError(
+            f"Image must be at least {MIN_DIM}×{MIN_DIM} pixels "
+            f"(got {image.size[0]}×{image.size[1]})"
+        )
+
+    # Expand bits with repetition code
+    repeated = [b for bit in bits for b in [bit] * repeat]
+
+    arr = np.array(image.convert('RGB'), dtype=np.float64)
+    Y = _luminance(arr)
+    h, w = Y.shape
+
+    # 2-level Haar DWT on luminance
+    LL, (LH, HL, HH) = pywt.dwt2(Y, 'haar')
+    LL2, (LH2, HL2, HH2) = pywt.dwt2(LL, 'haar')
+
+    flat = LL2.flatten().copy()
+
+    if len(repeated) > len(flat):
+        raise ValueError(
+            f"Payload too large: need {len(repeated)} coefficient slots, "
+            f"image provides {len(flat)}. Use a larger image or reduce payload."
+        )
+
+    # QIM embedding
+    for i, bit in enumerate(repeated):
+        c = flat[i]
+        if bit == 0:
+            flat[i] = np.round(c / delta) * delta
+        else:
+            flat[i] = (np.round(c / delta - 0.5) + 0.5) * delta
+
+    # Reconstruct modified luminance
+    LL2_w = flat.reshape(LL2.shape)
+    LL_w = pywt.idwt2((LL2_w, (LH2, HL2, HH2)), 'haar')
+    Y_w = pywt.idwt2((LL_w, (LH, HL, HH)), 'haar')
+    Y_w = Y_w[:h, :w]
+
+    # Distribute the luminance delta equally to all RGB channels
+    delta_Y = Y_w - Y
+    arr_wm = arr.copy()
+    for ch in range(3):
+        arr_wm[:, :, ch] = np.clip(arr[:, :, ch] + delta_Y, 0, 255)
+
+    return Image.fromarray(arr_wm.astype(np.uint8), 'RGB')
+
+
+def extract_bits(
+    image: Image.Image,
+    n_bits: int,
+    delta: float = DELTA,
+    repeat: int = REPEAT,
+) -> List[int]:
+    """
+    Extract n_bits from a (possibly watermarked) image using QIM detection.
+
+    Args:
+        image:  RGB PIL Image
+        n_bits: number of bits to extract (before repetition)
+        delta:  quantization step (must match embed)
+        repeat: repetition factor (must match embed)
+
+    Returns:
+        List of detected bits (0 or 1)
+    """
+    arr = np.array(image.convert('RGB'), dtype=np.float64)
+    Y = _luminance(arr)
+
+    LL, _ = pywt.dwt2(Y, 'haar')
+    LL2, _ = pywt.dwt2(LL, 'haar')
+    flat = LL2.flatten()
+
+    n_needed = n_bits * repeat
+    if n_needed > len(flat):
+        raise ValueError(
+            f"Cannot extract {n_bits} bits from this image "
+            f"(max capacity: {len(flat) // repeat} bits)"
+        )
+
+    # QIM detection: frac near 0/1 → bit 0, frac near 0.5 → bit 1
+    raw = []
+    for i in range(n_needed):
+        frac = (flat[i] / delta) % 1.0
+        raw.append(1 if 0.25 <= frac < 0.75 else 0)
+
+    # Majority vote over repeated copies
+    bits = []
+    for i in range(n_bits):
+        chunk = raw[i * repeat:(i + 1) * repeat]
+        bits.append(1 if sum(chunk) > repeat / 2 else 0)
+
+    return bits