Add native pHash deduplication acceleration

Author: vinay553

.circleci/config.yml

@@ -80,6 +80,12 @@ jobs:
       - image: cimg/python:3.10
     steps:
       - checkout # checkout source code to working directory
+      - setup_remote_docker
+      - run:
+          name: Install Build Tools
+          command: |
+            pip install --upgrade pip
+            pip install poetry cibuildwheel
       - run:
           name: Validate Tag Version # Check if the tag name matches the package version
           command: |
@@ -99,9 +105,18 @@ jobs:
                 exit 1;
             fi
       - run:
-          name: Build
+          name: Build sdist and Linux wheels
           command: | # install env dependencies
-            poetry build
+            rm -rf dist
+            poetry build --format sdist
+
+            export CIB_ARCHS_LINUX="x86_64"
+            export CIB_BUILD="cp310-manylinux_x86_64 cp311-manylinux_x86_64 cp312-manylinux_x86_64 cp313-manylinux_x86_64 cp314-manylinux_x86_64"
+            export CIB_SKIP="pp* *-musllinux_*"
+            export CIB_TEST_COMMAND='python -c "import nucleus._native_dedup as native; assert native.deduplicate_phashes([0, (1 << 10) - 1, (1 << 11) - 1], 10) == [0, 2]"'
+            python -m cibuildwheel --platform linux --output-dir dist
+
+            ls -lh dist
       - run:
           name: Publish to PyPI
           command: |
@@ -173,4 +188,3 @@ workflows:
               ignore: /.*/ # Runs for none of the branches
             tags:
               only: /^v\d+\.\d+\.\d+$/ # Runs only for tags with the format [v1.2.3]
-

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to the [Nucleus Python Client](https://github.com/scaleapi/n
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.5](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.18.5) - 2026-06-08
+
+### Added
+- Native C acceleration for `deduplicate_by_phash`. When the compiled extension is available, all threshold values are handled in native code: thresholds `0` through `11` use the chunked Hamming index, thresholds `12` through `63` use a native linear scan, and threshold `64` uses the keep-first fast path. The public Python API is unchanged and falls back to the pure-Python implementation when the native extension is unavailable.
+
+### Tooling / CI
+- Publish Linux `x86_64` wheels for Python 3.10 through 3.14 using `cibuildwheel`, alongside the source distribution.
+
 ## [0.18.4](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.18.4) - 2026-06-08
 
 ### Added

build.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import sys
+
+from setuptools import Extension
+
+
+def build(setup_kwargs):
+    extra_compile_args = []
+    if sys.platform != "win32":
+        extra_compile_args.extend(["-std=c11", "-O3"])
+
+    setup_kwargs.update(
+        {
+            "ext_modules": [
+                Extension(
+                    "nucleus._native_dedup",
+                    ["nucleus/_native_dedup.c"],
+                    extra_compile_args=extra_compile_args,
+                    optional=True,
+                )
+            ],
+        }
+    )