voxelion 0.1.0__tar.gz

voxelion-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

voxelion-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+First release. Targets `/api/v1`.
+
+- `dedup()` — synchronous batch deduplication
+- `submit_job()` / `JobHandle.wait()` — the queued path, with polling backoff
+- `list_reports()` / `get_report()` / `manifest()`
+- `balance()`
+- Typed exceptions per API error code
+- Retries: `Retry-After` on 429, exponential backoff with full jitter on 5xx,
+  nothing else retried
+- Streaming uploads — an archive is never read into memory

voxelion-0.1.0/LICENSE

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

voxelion-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: voxelion
+Version: 0.1.0
+Summary: Perceptual deduplication for image datasets — the official Python client for the Voxelion API.
+Project-URL: Homepage, https://voxelion.ai
+Project-URL: Documentation, https://voxelion.ai/docs/
+Project-URL: Changelog, https://github.com/Asekun/bioHarmonix/blob/main/sdk/python/CHANGELOG.md
+Author: Voxelion
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-quality,dataset,deduplication,dicom,machine-learning,perceptual-hash
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# voxelion
+
+Perceptual deduplication for image datasets — the official Python client for the
+[Voxelion API](https://voxelion.ai/docs/).
+
+Voxelion finds the files in a dataset that are the *same image* — after
+re-encoding, resizing, format conversion or a metadata rewrite — and tells you
+which ones are redundant. It never deletes anything.
+
+```bash
+pip install voxelion
+```
+
+## Quickstart
+
+```python
+from voxelion import Voxelion
+
+vx = Voxelion()                       # reads VOXELION_API_KEY
+report = vx.dedup(["a.png", "b.png", "c.png"], engine="curate")
+
+print(f"{report.leakage:.1%} redundant across {report.count} images")
+for cluster in report.clusters:
+    print("same image:", ", ".join(cluster))
+```
+
+Create a key in the console under **API Keys**, then:
+
+```bash
+export VOXELION_API_KEY=pk_live_...
+```
+
+## Large datasets
+
+A batch that fits in one upload goes through `dedup()`. Anything larger is
+queued, which survives a disconnect and reports progress:
+
+```python
+job = vx.submit_job("corpus.zip", engine="curate")
+print(job.id, job.status)
+
+report = job.wait()                   # polls with backoff
+plan = vx.manifest(report.id)
+print(f"keep {len(plan.keep)}, drop {len(plan.drop)}")
+```
+
+`plan.drop` is a list of filenames. **Voxelion does not delete them** — what
+you do with the plan is yours to decide.
+
+## Engines
+
+| Engine | For |
+|---|---|
+| `health` | Medical imaging. DICOM-aware: a CT or MR series is deduplicated as a scan, not as loose slices. |
+| `curate` | General image archives — product photography, scraped corpora, generated output. |
+
+Omit `engine=` to use your account's default. The engine that actually ran is
+on the report either way:
+
+```python
+report = vx.dedup(files)
+print(report.engine)                  # "curate"
+```
+
+## Errors
+
+Exceptions are typed by what went wrong, not by status code:
+
+```python
+from voxelion import InsufficientCreditError, ConsentRequiredError
+
+try:
+    report = vx.dedup(files)
+except InsufficientCreditError as e:
+    print(f"needs {e.required_cents}c, have {e.available_cents}c")
+except ConsentRequiredError:
+    print("Grant data-processing consent in the console first.")
+```
+
+`429` responses honour the server's `Retry-After` automatically, and `5xx`
+retries with exponential backoff. Nothing else is retried: a `402` will not
+become affordable by asking again.
+
+## Sandbox
+
+The sandbox is a separate deployment with its own database and accounts. It is
+the same client with a different base URL:
+
+```python
+from voxelion import Voxelion, SANDBOX_BASE_URL
+
+vx = Voxelion(base_url=SANDBOX_BASE_URL)
+```
+
+## Checking cost before spending
+
+```python
+account = vx.balance()
+print(account.spendable_cents)        # not balance_cents — see below
+```
+
+`spendable_cents` is the balance minus credit already held against runs in
+flight. It is the number that decides whether the next call succeeds.
+
+## Development
+
+Models in `src/voxelion/models.py` are **generated** from the API's OpenAPI
+document. Do not edit them by hand:
+
+```bash
+./scripts-generate.sh
+```
+
+```bash
+pytest                      # unit tests, no network
+pytest -m live              # against a real deployment; needs VOXELION_API_KEY
+```

voxelion-0.1.0/README.md

@@ -0,0 +1,117 @@
+# voxelion
+
+Perceptual deduplication for image datasets — the official Python client for the
+[Voxelion API](https://voxelion.ai/docs/).
+
+Voxelion finds the files in a dataset that are the *same image* — after
+re-encoding, resizing, format conversion or a metadata rewrite — and tells you
+which ones are redundant. It never deletes anything.
+
+```bash
+pip install voxelion
+```
+
+## Quickstart
+
+```python
+from voxelion import Voxelion
+
+vx = Voxelion()                       # reads VOXELION_API_KEY
+report = vx.dedup(["a.png", "b.png", "c.png"], engine="curate")
+
+print(f"{report.leakage:.1%} redundant across {report.count} images")
+for cluster in report.clusters:
+    print("same image:", ", ".join(cluster))
+```
+
+Create a key in the console under **API Keys**, then:
+
+```bash
+export VOXELION_API_KEY=pk_live_...
+```
+
+## Large datasets
+
+A batch that fits in one upload goes through `dedup()`. Anything larger is
+queued, which survives a disconnect and reports progress:
+
+```python
+job = vx.submit_job("corpus.zip", engine="curate")
+print(job.id, job.status)
+
+report = job.wait()                   # polls with backoff
+plan = vx.manifest(report.id)
+print(f"keep {len(plan.keep)}, drop {len(plan.drop)}")
+```
+
+`plan.drop` is a list of filenames. **Voxelion does not delete them** — what
+you do with the plan is yours to decide.
+
+## Engines
+
+| Engine | For |
+|---|---|
+| `health` | Medical imaging. DICOM-aware: a CT or MR series is deduplicated as a scan, not as loose slices. |
+| `curate` | General image archives — product photography, scraped corpora, generated output. |
+
+Omit `engine=` to use your account's default. The engine that actually ran is
+on the report either way:
+
+```python
+report = vx.dedup(files)
+print(report.engine)                  # "curate"
+```
+
+## Errors
+
+Exceptions are typed by what went wrong, not by status code:
+
+```python
+from voxelion import InsufficientCreditError, ConsentRequiredError
+
+try:
+    report = vx.dedup(files)
+except InsufficientCreditError as e:
+    print(f"needs {e.required_cents}c, have {e.available_cents}c")
+except ConsentRequiredError:
+    print("Grant data-processing consent in the console first.")
+```
+
+`429` responses honour the server's `Retry-After` automatically, and `5xx`
+retries with exponential backoff. Nothing else is retried: a `402` will not
+become affordable by asking again.
+
+## Sandbox
+
+The sandbox is a separate deployment with its own database and accounts. It is
+the same client with a different base URL:
+
+```python
+from voxelion import Voxelion, SANDBOX_BASE_URL
+
+vx = Voxelion(base_url=SANDBOX_BASE_URL)
+```
+
+## Checking cost before spending
+
+```python
+account = vx.balance()
+print(account.spendable_cents)        # not balance_cents — see below
+```
+
+`spendable_cents` is the balance minus credit already held against runs in
+flight. It is the number that decides whether the next call succeeds.
+
+## Development
+
+Models in `src/voxelion/models.py` are **generated** from the API's OpenAPI
+document. Do not edit them by hand:
+
+```bash
+./scripts-generate.sh
+```
+
+```bash
+pytest                      # unit tests, no network
+pytest -m live              # against a real deployment; needs VOXELION_API_KEY
+```

voxelion-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "voxelion"
+dynamic = ["version"]
+description = "Perceptual deduplication for image datasets — the official Python client for the Voxelion API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Voxelion" }]
+keywords = ["deduplication", "dataset", "perceptual-hash", "dicom", "machine-learning", "data-quality"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Image Processing",
+  "Typing :: Typed",
+]
+
+# Two runtime dependencies and no more. Every dependency an SDK adds is one its
+# users must resolve against their own pins, and a data-science environment is
+# already the hardest place in Python to add a constraint.
+dependencies = [
+  "httpx>=0.24,<1",
+  "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://voxelion.ai"
+Documentation = "https://voxelion.ai/docs/"
+Changelog = "https://github.com/Asekun/bioHarmonix/blob/main/sdk/python/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-httpx>=0.30", "mypy>=1.8", "ruff>=0.4"]
+
+[tool.hatch.version]
+path = "src/voxelion/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voxelion"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Live tests need a sandbox key and are skipped without one.
+markers = ["live: talks to a real deployment (needs VOXELION_API_KEY)"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+
+# The TESTS are type-checked too, but not at library strictness.
+#
+# They went unchecked entirely until the TypeScript side turned out to have the
+# same blind spot — its tsconfig excluded `test/`, so every type assertion in
+# every test there was inert. The same was true here.
+#
+# Annotating every pytest function and fixture buys noise, not safety, so the
+# annotation REQUIREMENT is relaxed while real type errors — a wrong argument,
+# a field that does not exist on a model — are still caught.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_calls = false
+# Generated file: its style is the generator's business, not ours.
+[[tool.mypy.overrides]]
+module = "voxelion.models"
+ignore_errors = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+# models.py is generated from the OpenAPI document. Its formatting is the
+# generator's business; linting it would mean either editing a generated file
+# or carrying a permanent list of ignores.
+extend-exclude = ["src/voxelion/models.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

voxelion-0.1.0/scripts-generate.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Regenerate the models from the API's OpenAPI document.
+#
+#   cd sdk/python && ./scripts-generate.sh
+#
+# Run this after any change to backend/src/schemas.js. The generated file is
+# committed so that installing the SDK never requires the generator.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+(cd ../../backend && npm run openapi >/dev/null)
+
+.venv/bin/datamodel-codegen \
+  --input ../../backend/openapi.json --input-file-type openapi \
+  --output src/voxelion/models.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --target-python-version 3.9 \
+  --use-schema-description --use-field-description \
+  --field-constraints --use-double-quotes --use-standard-collections \
+  --snake-case-field --allow-population-by-field-name --use-subclass-enum \
+  --custom-file-header "# GENERATED FROM backend/openapi.json — DO NOT EDIT BY HAND.
+#
+# Regenerate with:  ./scripts-generate.sh
+#
+# Derived from the API's own OpenAPI document, which is generated from
+# apiDocs(). Hand-editing here would create a third description of the API that
+# drifts from the other two, and that drift surfaces as a wrong type in
+# somebody else's program."
+
+echo "models regenerated: $(grep -c '^class' src/voxelion/models.py) classes"

voxelion-0.1.0/src/voxelion/__init__.py

@@ -0,0 +1,64 @@
+"""Voxelion — perceptual deduplication for image datasets.
+
+    from voxelion import Voxelion
+
+    vx = Voxelion()                                   # reads VOXELION_API_KEY
+    report = vx.dedup(["a.png", "b.png"], engine="curate")
+    print(report.leakage, len(report.clusters))
+
+Nothing here ever deletes a file. A report and its manifest tell you what is
+redundant; acting on that stays your decision.
+"""
+
+from ._client import (
+    DEFAULT_BASE_URL,
+    SANDBOX_BASE_URL,
+    JobHandle,
+    Voxelion,
+)
+from ._transport import ApiKeyProvider, ApiKeySource
+from ._version import __version__
+from .errors import (
+    AccountNotActiveError,
+    APIConnectionError,
+    AuthenticationError,
+    ConsentRequiredError,
+    InsufficientCreditError,
+    InvalidRequestError,
+    JobFailedError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    VoxelionError,
+)
+from .models import (
+    AutoTopUp,
+    BillingAccount,
+    Card,
+    DedupReport,
+    Engine,
+    Hash,
+    Job,
+    Manifest,
+    ManifestCluster,
+    Pair,
+    ReportSummary,
+    ReportVolume,
+    ReportVolumePair,
+)
+from .models import (
+    Report as StoredReport,
+)
+
+__all__ = [
+    "ApiKeyProvider", "ApiKeySource",
+    "__version__",
+    "Voxelion", "JobHandle", "DEFAULT_BASE_URL", "SANDBOX_BASE_URL",
+    "VoxelionError", "AuthenticationError", "ConsentRequiredError",
+    "AccountNotActiveError", "InsufficientCreditError", "InvalidRequestError",
+    "NotFoundError", "RateLimitError", "ServerError", "APIConnectionError",
+    "JobFailedError",
+    "DedupReport", "StoredReport", "ReportSummary", "ReportVolume", "ReportVolumePair",
+    "Manifest", "ManifestCluster", "Job",
+    "BillingAccount", "Card", "AutoTopUp", "Hash", "Pair", "Engine",
+]