snapwonders 0.1.0__tar.gz

snapwonders-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+# Runs on the standalone snapWONDERS-SDK-Python repo (this file becomes .github/workflows/ci.yml
+# there after `git subtree split`). Offline tests need no API key; the integration job only
+# runs when SNAPWONDERS_TEST_API_KEY is configured as a repository secret.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test — Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with dev extras)
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+      - name: Offline test suite
+        run: pytest -q
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - name: Validate package metadata
+        run: python -m twine check dist/*

snapwonders-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# Python build / cache artefacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/

snapwonders-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to the `snapwonders` Python client are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026
+
+Initial release.
+
+- Official Python client for the snapWONDERS API, covering all three product areas:
+  `client.stego` (hide & reveal), `client.analyse` (forensic media analysis), and `client.convert`
+  (media conversion).
+- Resumable upload and the session → job → poll → download flow wrapped internally, so a whole job
+  is a single call (e.g. `client.stego.hide([...], password=...)`). One-shot helpers plus
+  step-by-step session/job control.
+- Polling backs off with jitter and honours a server-supplied poll interval, to stay light under load.
+- Typed exceptions (`SnapwondersError` base): `AuthError`, `ProRequiredError`, `SessionExpiredError`,
+  `RateLimitError`, `MaintenanceError`, `JobFailedError`, `TusUploadError`, `NetworkError`, `ApiError`.
+- Minimal dependency surface: `httpx` only.

snapwonders-0.1.0/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 Kenneth Springer @ snapWONDERS
+
+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.
+
+---
+
+SCOPE OF THIS LICENCE
+
+The MIT licence above applies **only** to the source code of this client library
+(the "Software"). It grants no rights in, and says nothing about the licensing of,
+the snapWONDERS API, service, website, data, trained models, or algorithms that
+this library communicates with — all of which are proprietary and remain the
+exclusive property of Kenneth Springer @ snapWONDERS.
+
+This library merely formats HTTP requests to the snapWONDERS API; it contains none
+of the API's implementation. Use of the snapWONDERS API requires a valid API key,
+is subject to rate limits and plan tiers, and is governed by the snapWONDERS Terms
+of Service (https://snapwonders.com/terms). Nothing in the MIT grant above waives
+those terms or confers any right to access the service itself.

snapwonders-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: snapwonders
+Version: 0.1.0
+Summary: Official Python SDK for the snapWONDERS API — steganography (hide & reveal), forensic media analysis, and format conversion.
+Project-URL: Homepage, https://snapwonders.com/developers#sdk
+Project-URL: Documentation, https://snapwonders.com/api
+Project-URL: Repository, https://github.com/snapWONDERS/snapWONDERS-SDK-Python
+Project-URL: Issues, https://github.com/snapWONDERS/snapWONDERS-SDK-Python/issues
+Project-URL: Changelog, https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/CHANGELOG.md
+Author-email: "Kenneth Springer @ snapWONDERS" <kenneth@snapwonders.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-image-detection,api-client,c2pa,content-credentials,forensics,hide-and-reveal,image-conversion,image-forensics,mcp,media-analysis,snapwonders,steganography,vaultify,watermark-detection
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+    <a href="https://www.snapwonders.com/" target="_blank">
+        <img src="https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/.github/social-preview.jpg" alt="snapWONDERS Python SDK" width="640" />
+    </a>
+</p>
+
+snapWONDERS — Expose what's hidden. Hide what's yours.
+
+
+# snapwonders — Python client for the snapWONDERS API
+
+The official Python client for the snapWONDERS API: steganography, forensic media analysis, and
+format conversion. The client wraps the resumable TUS upload and the session → job → poll → download
+choreography so that a whole job is a couple of lines.
+
+All the snapWONDERS API services are available over the Clearnet / **Web** and Dark Web **Tor** and
+**I2P**.
+
+> **Status.** Initial release (`0.1.0`). Not yet published to PyPI.
+
+
+# See it in action
+
+Hide a secret image inside a cover — the stego output looks pixel-identical, but carries the hidden
+file, recoverable only with the password:
+
+| Secret (hidden inside) | Cover (input) | Stego output (carries the secret) |
+|---|---|---|
+| ![secret](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/assets/secret.png) | ![cover](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/sample-output/input.png) | ![stego](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/sample-output/stego-output.webp) |
+
+The full walkthrough — steganography, forensic analysis (with a real graded result), and conversion —
+is in **[`examples/WALKTHROUGH.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/WALKTHROUGH.md)**.
+
+
+# Installation and setup
+
+## snapWONDERS API key
+You will need a snapWONDERS API key before you can get started:
+
+* Sign up and create an account at [snapWONDERS sign-up](https://snapwonders.com/sign-up). If you
+  wish to create an account via Tor or I2P then you can do so by accessing snapWONDERS through the
+  Tor or I2P portals. For the dark web links visit
+  [browsing safely](https://snapwonders.com/browsing-safely).
+* Under your account settings, generate an API key. New keys start with `sw_`. It is sent as the
+  `X-Api-Key` header on every request — keep it secret.
+
+## Install the package
+
+```bash
+pip install snapwonders    # once published
+```
+
+
+# Quickstart
+
+```python
+from snapwonders import Client
+
+client = Client(api_key="sw_your_key_here")   # base_url defaults to https://snapwonders.com
+print(client.status())                          # no key needed for status
+
+# Hide a secret inside a cover image (the last file is the cover).
+job = client.stego.hide(["secret.png", "cover.jpg"], password="Str0ng!Pass")
+for result in job.results():
+    result.download("out/")                     # "out/" is a directory — the server filename is kept
+
+# Reveal it again.
+job = client.stego.reveal("out/cover-share.avif", password="Str0ng!Pass")
+job.results()[0].download("recovered/")
+```
+
+`client.analyse` (forensic analysis) and `client.convert` (media conversion) follow the same shape —
+one call in, results out:
+
+```python
+# Forensic analysis — grade each file A–F, collect the overlay assets it produced.
+job = client.analyse.run(["photo.jpg"], face_detection=True)
+for item in job.results():
+    print(item.filename, item.grade, item.face_count)
+    for asset in item.assets:        # ELA map, face overlay, …
+        asset.download("out/")
+
+# Convert media — the image format key is `image_format` (jpeg/png/webp/avif/heic/jxl).
+job = client.convert.run(["photo.png"], image_format="webp")
+job.results()[0].download("out/")
+```
+
+Prefer to drive each stage yourself? The step-by-step surface is public too:
+`create_session` → `upload(path, step=…)` → `wait_for_uploads()` → `start_job(**opts)` → `wait()` →
+`results()`.
+
+
+# Examples
+
+Runnable end-to-end examples live in [`examples/`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/tree/main/examples) — steganography, forensic analysis,
+and conversion, each a self-contained script with a bundled sample image:
+
+```bash
+export SNAPWONDERS_API_KEY=sw_your_key_here
+python examples/hide_and_reveal.py     # hide a file in an image, then reveal it
+python examples/analyse.py             # grade an image A–F + download overlay assets
+python examples/convert.py             # JPEG → WebP
+```
+
+See [`examples/WALKTHROUGH.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/WALKTHROUGH.md) for the real input/output images and a live forensic-analysis JSON result, or [`examples/README.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/README.md) for how to run them.
+
+
+# Errors
+
+Every failure the SDK raises is a typed subclass of `SnapwondersError`, so you can branch on the
+kind of failure rather than inspecting HTTP status codes:
+
+| Exception | Raised when |
+|-----------|-------------|
+| `AuthError` | Missing, malformed, unknown, or revoked API key |
+| `ProRequiredError` | A Pro-only option was used on a free account |
+| `SessionExpiredError` | The 24-hour upload session window has passed |
+| `RateLimitError` | Rate limited — carries `retry_after` when the server supplies it |
+| `MaintenanceError` | snapWONDERS is temporarily unavailable for maintenance — carries `retry_after` |
+| `JobFailedError` | A job finished as `failed` — carries the server's reason |
+| `TusUploadError` | A resumable-upload step failed |
+| `NetworkError` | The API could not be reached |
+| `ApiError` | Any other non-2xx response |
+
+
+# Running the tests
+
+```bash
+pip install -e ".[dev]"
+pytest                       # offline smoke tests — no API key required
+# integration tests need SNAPWONDERS_TEST_API_KEY set against the dev API
+```
+
+
+# Documentation
+
+Useful documentation can be found at:
+
+* The interactive Swagger UI and full endpoint reference:
+  [snapWONDERS API](https://snapwonders.com/api)
+* A guided, step-by-step integration walkthrough:
+  [snapWONDERS Developers](https://snapwonders.com/developers)
+
+
+# Contact
+
+## For security concerns
+If you have spotted any security concerns then please reach out via
+[contacting snapWONDERS](https://snapwonders.com/contact) and set the subject to
+**"SECURITY CONCERNS"** and provide the information about your concerns. If you wish to contact via
+Tor or I2P then you can do so by accessing snapWONDERS through the Tor or I2P portals. For the dark
+web links visit [browsing safely](https://snapwonders.com/browsing-safely).
+
+## For FAQ and questions
+It may be that your question is already answered in the [FAQ](https://snapwonders.com/faq). Be sure
+to check the FAQ content first. Otherwise you may reach out via
+[contacting snapWONDERS](https://snapwonders.com/contact).
+
+## For contacting the author
+Use this link to contact the author [Kenneth Springer](https://kennethbspringer.au/).
+
+
+# Licence
+
+MIT — Copyright (c) 2026 Kenneth Springer @ snapWONDERS. See [LICENSE](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/LICENSE).
+
+**Scope.** The MIT licence covers **this client library only**. It grants no rights in the
+snapWONDERS API, service, data, models, or algorithms it communicates with — these are **proprietary**
+and remain the property of Kenneth Springer @ snapWONDERS. This library only sends HTTP requests to
+the API; it contains none of its implementation. Using the API requires a valid API key and is
+governed by the [snapWONDERS Terms of Service](https://snapwonders.com/terms).

snapwonders-0.1.0/README.md

@@ -0,0 +1,171 @@
+<p align="center">
+    <a href="https://www.snapwonders.com/" target="_blank">
+        <img src="https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/.github/social-preview.jpg" alt="snapWONDERS Python SDK" width="640" />
+    </a>
+</p>
+
+snapWONDERS — Expose what's hidden. Hide what's yours.
+
+
+# snapwonders — Python client for the snapWONDERS API
+
+The official Python client for the snapWONDERS API: steganography, forensic media analysis, and
+format conversion. The client wraps the resumable TUS upload and the session → job → poll → download
+choreography so that a whole job is a couple of lines.
+
+All the snapWONDERS API services are available over the Clearnet / **Web** and Dark Web **Tor** and
+**I2P**.
+
+> **Status.** Initial release (`0.1.0`). Not yet published to PyPI.
+
+
+# See it in action
+
+Hide a secret image inside a cover — the stego output looks pixel-identical, but carries the hidden
+file, recoverable only with the password:
+
+| Secret (hidden inside) | Cover (input) | Stego output (carries the secret) |
+|---|---|---|
+| ![secret](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/assets/secret.png) | ![cover](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/sample-output/input.png) | ![stego](https://raw.githubusercontent.com/snapWONDERS/snapWONDERS-SDK-Python/main/examples/sample-output/stego-output.webp) |
+
+The full walkthrough — steganography, forensic analysis (with a real graded result), and conversion —
+is in **[`examples/WALKTHROUGH.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/WALKTHROUGH.md)**.
+
+
+# Installation and setup
+
+## snapWONDERS API key
+You will need a snapWONDERS API key before you can get started:
+
+* Sign up and create an account at [snapWONDERS sign-up](https://snapwonders.com/sign-up). If you
+  wish to create an account via Tor or I2P then you can do so by accessing snapWONDERS through the
+  Tor or I2P portals. For the dark web links visit
+  [browsing safely](https://snapwonders.com/browsing-safely).
+* Under your account settings, generate an API key. New keys start with `sw_`. It is sent as the
+  `X-Api-Key` header on every request — keep it secret.
+
+## Install the package
+
+```bash
+pip install snapwonders    # once published
+```
+
+
+# Quickstart
+
+```python
+from snapwonders import Client
+
+client = Client(api_key="sw_your_key_here")   # base_url defaults to https://snapwonders.com
+print(client.status())                          # no key needed for status
+
+# Hide a secret inside a cover image (the last file is the cover).
+job = client.stego.hide(["secret.png", "cover.jpg"], password="Str0ng!Pass")
+for result in job.results():
+    result.download("out/")                     # "out/" is a directory — the server filename is kept
+
+# Reveal it again.
+job = client.stego.reveal("out/cover-share.avif", password="Str0ng!Pass")
+job.results()[0].download("recovered/")
+```
+
+`client.analyse` (forensic analysis) and `client.convert` (media conversion) follow the same shape —
+one call in, results out:
+
+```python
+# Forensic analysis — grade each file A–F, collect the overlay assets it produced.
+job = client.analyse.run(["photo.jpg"], face_detection=True)
+for item in job.results():
+    print(item.filename, item.grade, item.face_count)
+    for asset in item.assets:        # ELA map, face overlay, …
+        asset.download("out/")
+
+# Convert media — the image format key is `image_format` (jpeg/png/webp/avif/heic/jxl).
+job = client.convert.run(["photo.png"], image_format="webp")
+job.results()[0].download("out/")
+```
+
+Prefer to drive each stage yourself? The step-by-step surface is public too:
+`create_session` → `upload(path, step=…)` → `wait_for_uploads()` → `start_job(**opts)` → `wait()` →
+`results()`.
+
+
+# Examples
+
+Runnable end-to-end examples live in [`examples/`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/tree/main/examples) — steganography, forensic analysis,
+and conversion, each a self-contained script with a bundled sample image:
+
+```bash
+export SNAPWONDERS_API_KEY=sw_your_key_here
+python examples/hide_and_reveal.py     # hide a file in an image, then reveal it
+python examples/analyse.py             # grade an image A–F + download overlay assets
+python examples/convert.py             # JPEG → WebP
+```
+
+See [`examples/WALKTHROUGH.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/WALKTHROUGH.md) for the real input/output images and a live forensic-analysis JSON result, or [`examples/README.md`](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/examples/README.md) for how to run them.
+
+
+# Errors
+
+Every failure the SDK raises is a typed subclass of `SnapwondersError`, so you can branch on the
+kind of failure rather than inspecting HTTP status codes:
+
+| Exception | Raised when |
+|-----------|-------------|
+| `AuthError` | Missing, malformed, unknown, or revoked API key |
+| `ProRequiredError` | A Pro-only option was used on a free account |
+| `SessionExpiredError` | The 24-hour upload session window has passed |
+| `RateLimitError` | Rate limited — carries `retry_after` when the server supplies it |
+| `MaintenanceError` | snapWONDERS is temporarily unavailable for maintenance — carries `retry_after` |
+| `JobFailedError` | A job finished as `failed` — carries the server's reason |
+| `TusUploadError` | A resumable-upload step failed |
+| `NetworkError` | The API could not be reached |
+| `ApiError` | Any other non-2xx response |
+
+
+# Running the tests
+
+```bash
+pip install -e ".[dev]"
+pytest                       # offline smoke tests — no API key required
+# integration tests need SNAPWONDERS_TEST_API_KEY set against the dev API
+```
+
+
+# Documentation
+
+Useful documentation can be found at:
+
+* The interactive Swagger UI and full endpoint reference:
+  [snapWONDERS API](https://snapwonders.com/api)
+* A guided, step-by-step integration walkthrough:
+  [snapWONDERS Developers](https://snapwonders.com/developers)
+
+
+# Contact
+
+## For security concerns
+If you have spotted any security concerns then please reach out via
+[contacting snapWONDERS](https://snapwonders.com/contact) and set the subject to
+**"SECURITY CONCERNS"** and provide the information about your concerns. If you wish to contact via
+Tor or I2P then you can do so by accessing snapWONDERS through the Tor or I2P portals. For the dark
+web links visit [browsing safely](https://snapwonders.com/browsing-safely).
+
+## For FAQ and questions
+It may be that your question is already answered in the [FAQ](https://snapwonders.com/faq). Be sure
+to check the FAQ content first. Otherwise you may reach out via
+[contacting snapWONDERS](https://snapwonders.com/contact).
+
+## For contacting the author
+Use this link to contact the author [Kenneth Springer](https://kennethbspringer.au/).
+
+
+# Licence
+
+MIT — Copyright (c) 2026 Kenneth Springer @ snapWONDERS. See [LICENSE](https://github.com/snapWONDERS/snapWONDERS-SDK-Python/blob/main/LICENSE).
+
+**Scope.** The MIT licence covers **this client library only**. It grants no rights in the
+snapWONDERS API, service, data, models, or algorithms it communicates with — these are **proprietary**
+and remain the property of Kenneth Springer @ snapWONDERS. This library only sends HTTP requests to
+the API; it contains none of its implementation. Using the API requires a valid API key and is
+governed by the [snapWONDERS Terms of Service](https://snapwonders.com/terms).

snapwonders-0.1.0/examples/.gitignore

@@ -0,0 +1 @@
+out/

snapwonders-0.1.0/examples/README.md

@@ -0,0 +1,21 @@
+# Examples — snapWONDERS Python SDK
+
+Runnable, self-contained examples. Each needs an API key
+([sign up free](https://snapwonders.com/sign-up)) in the `SNAPWONDERS_API_KEY` environment variable.
+
+```bash
+pip install snapwonders          # or:  pip install -e ..
+export SNAPWONDERS_API_KEY=sw_your_key_here
+
+python examples/hide_and_reveal.py     # steganography: hide a file in an image, then reveal it
+python examples/analyse.py             # forensic analysis: grade an image A–F + overlay assets
+python examples/convert.py             # media conversion: JPEG → WebP
+```
+
+Outputs are written to `examples/out/` (git-ignored). `assets/sample.png` is a generated placeholder
+— pass your own image to `analyse.py` (`python examples/analyse.py my-photo.jpg`) or swap the file in
+`assets/` for richer results.
+
+## See it in action
+
+[**WALKTHROUGH.md**](WALKTHROUGH.md) shows the real input/output images and a real forensic analysis JSON result from running these examples.

snapwonders-0.1.0/examples/WALKTHROUGH.md

@@ -0,0 +1,86 @@
+# Walkthrough — inputs, outputs & a real analyse result
+
+What each example actually produces, using the bundled sample image. Everything below was generated by
+running the scripts in this folder against the live API.
+
+> The bundled `sample.png` is an **AI-generated image that carries C2PA Content Credentials**. Analyse
+> grades it **D** — the honest provenance metadata is a positive authenticity signal, so it scores
+> better than an image with no provenance at all, but it is still not an original photograph. Swap
+> `assets/sample.png` for a real photo and re-run to see a higher grade —
+> `python examples/analyse.py your-photo.jpg`.
+
+---
+
+## 1. Steganography — `hide_and_reveal.py`
+
+Hide a secret image inside a cover image. The output is **visually identical** to the cover — that is
+the whole point — but it carries the hidden file, recoverable only with the password.
+
+| Secret (hidden inside) | Cover (input) | Stego output (carries the secret) |
+|---|---|---|
+| ![secret](assets/secret.png) | ![cover](sample-output/input.png) | ![stego](sample-output/stego-output.webp) |
+
+`reveal()` with the same password extracts the secret back out. The stego output is a **lossless**
+image (here WebP) — re-encoding it to a lossy format would destroy the hidden data.
+
+---
+
+## 2. Forensic analysis — `analyse.py`
+
+`client.analyse.run([...])` grades each file, returns the forensic **verdicts**, and gives
+downloadable overlays.
+
+The full response is [`sample-output/analyse-result.json`](sample-output/analyse-result.json).
+Abridged:
+
+```jsonc
+[
+  {
+    "name": "sample.png",
+    "grade": "D",
+    "face_count": 0,
+    "text_region_count": 0,
+    "watermark_flagged": false,
+    "verdicts": {
+      "ai_generation": { "verdict": "possible_aigc" },
+      "c2pa": { "verdict": "valid", "applicable": true, "has_manifest": true, "trusted": true },
+      "camera_fingerprint": { "matched": true, "encoder_name": "Adobe Photoshop",
+                              "encoder_family": "adobe", "quality_level": 90 },
+      "findings": [
+        { "label": "Declared AI-generated (C2PA Content Credentials)", "severity": "info" },
+        { "label": "No camera capture metadata present", "severity": "medium" },
+        { "label": "Noise pattern inconsistent with a single capture", "severity": "high" }
+      ]
+    },
+    "assets": [
+      { "asset_id": "…", "category": "forensic_noise_map", "mime_type": "image/jpeg",
+        "file_size": 298396, "download_path": "/api/analyse/asset/…" }
+    ]
+  }
+]
+```
+
+- **`verdicts`** — the curated, user-safe forensic verdicts (mirrors what the web report shows, never
+  internal data): `ai_generation.verdict`, `c2pa.{verdict,applicable,has_manifest,trusted}`,
+  `camera_fingerprint.{matched,encoder_name,encoder_family,quality_level}` (the device match itself,
+  never any underlying signature), and `findings[].{label,severity}`. In the SDK: `item.verdicts`.
+- **`grade`** — overall A–F forensic grade (`D` here — see the note at the top). The grade also
+  factors in C2PA/provenance, which is why this AI sample scores `D` rather than `F`.
+- **`assets`** — downloadable overlay maps (`asset.download(...)`); each has a relative `download_path`.
+
+---
+
+## 3. Conversion — `convert.py`
+
+`client.convert.run([...], image_format="webp")` re-encodes media. Input → output:
+
+| Input (`sample.png`) | Output (`webp`) |
+|---|---|
+| ![in](sample-output/input.png) | ![out](sample-output/convert-output.webp) |
+
+Formats: `image_format` = `jpeg` `png` `webp` `avif` `heic` `jxl`; video uses `video_format`.
+
+---
+
+*Regenerate every artifact in `sample-output/` by running the three example scripts with a valid
+`SNAPWONDERS_API_KEY`.*

snapwonders-0.1.0/examples/analyse.py

@@ -0,0 +1,54 @@
+#
+# snapWONDERS API — Python SDK example
+#
+# Copyright (c) 2026 Kenneth Springer @ snapWONDERS. MIT Licensed — see LICENSE.
+# Author: Kenneth Springer @ snapWONDERS <kenneth@snapwonders.com> (https://kennethbspringer.au)
+#
+# Forensic analysis: grade an image A–F and download the overlay assets it produces.
+# Run:  SNAPWONDERS_API_KEY=sw_... python examples/analyse.py [path/to/image.jpg]
+#
+
+import os
+import sys
+from pathlib import Path
+
+from snapwonders import Client
+
+HERE = Path(__file__).parent
+OUT = HERE / "out" / "analyse"
+
+
+def main() -> None:
+    key = os.environ.get("SNAPWONDERS_API_KEY")
+    if not key:
+        raise SystemExit("Set SNAPWONDERS_API_KEY (get one at https://snapwonders.com/sign-up)")
+
+    image = sys.argv[1] if len(sys.argv) > 1 else str(HERE / "assets" / "sample.png")
+    client = Client(api_key=key)
+
+    print(f"Analysing {image} …")
+    job = client.analyse.run([image], face_detection=True)
+    print(f"  status: {job.status}")
+
+    for item in job.results():
+        print(f"\n  {item.filename}")
+        print(f"    grade         : {item.grade}")
+        print(f"    faces         : {item.face_count}")
+        print(f"    text regions  : {item.text_region_count}")
+        print(f"    watermark     : {item.watermark_flagged}")
+        v = item.verdicts
+        if v:
+            print(f"    AI generation : {(v.get('ai_generation') or {}).get('verdict')}")
+            print(f"    C2PA          : {(v.get('c2pa') or {}).get('verdict')}")
+            print(f"    camera match  : {(v.get('camera_fingerprint') or {}).get('encoder_name')}")
+            for finding in v.get("findings", []):
+                print(f"    finding       : {finding.get('label')} ({finding.get('severity')})")
+        for asset in item.assets:          # e.g. ELA map, face overlay
+            path = asset.download(str(OUT) + "/")
+            print(f"    asset         : {asset.name} → {path}")
+
+    print("\nDone. See", OUT)
+
+
+if __name__ == "__main__":
+    main()