sillstone 0.2.0__tar.gz

sillstone-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: sillstone
+Version: 0.2.0
+Summary: Pure-Rust zero-dependency multimedia, hashing, and array computing suite
+Author: Sillstone Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/sillstone/sillstone
+Project-URL: Repository, https://github.com/sillstone/sillstone
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown

sillstone-0.2.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sillstone"
+version = "0.2.0"
+description = "Pure-Rust zero-dependency multimedia, hashing, and array computing suite"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Sillstone Contributors" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/sillstone/sillstone"
+Repository = "https://github.com/sillstone/sillstone"

sillstone-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sillstone-0.2.0/sillstone/__init__.py

@@ -0,0 +1,551 @@
+"""Sillstone Python SDK: Zero-dependency multimedia, hashing, and array computing suite."""
+
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass
+from pathlib import Path
+import struct
+
+from ._generated import (
+    LIB,
+    sillstone_version_major_raw,
+    sillstone_version_minor_raw,
+    sillstone_version_patch_raw,
+    sillstone_buffer_checksum_raw,
+    sillstone_digest_sha256_raw,
+    sillstone_digest_sha3_256_raw,
+    sillstone_digest_sha3_512_raw,
+    sillstone_digest_blake2b_512_raw,
+    sillstone_digest_blake3_raw,
+    sillstone_math_dst1_raw,
+    sillstone_math_dst2_raw,
+    sillstone_math_dst3_raw,
+    sillstone_unicode_grapheme_count_raw,
+    sillstone_unicode_char_category_raw,
+    sillstone_image_phash_raw,
+    sillstone_image_ahash_raw,
+    sillstone_image_dhash_raw,
+    sillstone_image_whash_raw,
+    sillstone_image_colorhash_raw,
+    sillstone_text_tlsh_raw,
+    sillstone_text_tlsh_distance_raw,
+    sillstone_curator_detect_raw,
+    sillstone_curator_content_hash_raw,
+    sillstone_curator_signature_raw,
+    sillstone_curator_describe_raw,
+    sillstone_curator_match_raw,
+    sillstone_curator_free_raw,
+)
+
+__version__ = "0.2.0b1"
+
+__all__ = [
+    "version",
+    "buffer_checksum",
+    "sha256",
+    "sha3_256",
+    "sha3_512",
+    "blake2b_512",
+    "blake3",
+    "dst1",
+    "dst2",
+    "dst3",
+    "grapheme_count",
+    "char_category",
+    "phash",
+    "ahash",
+    "dhash",
+    "whash",
+    "colorhash",
+    "tlsh",
+    "tlsh_distance",
+    "detect",
+    "content_hash",
+    "signature",
+    "describe",
+    "match_signatures",
+    "parse_signature",
+    "parse_describe",
+    "fnv1a64",
+    "Detection",
+    "Signature",
+    "Description",
+    "MatchResult",
+    "FfiError",
+    "FORMATS",
+    "MODALITIES",
+    "MATCH_TAGS",
+    "STATUS_OK",
+    "STATUS_INVALID",
+    "STATUS_REJECTED",
+]
+
+#: Status codes
+STATUS_OK = 0
+STATUS_INVALID = -1
+STATUS_REJECTED = -2
+
+#: Format names by wire code (declaration order)
+FORMATS = ("png", "jpeg", "bmp", "zip", "mp4", "mp3", "wav", "flac", "pdf", "gif", "unknown")
+
+#: Modality names by wire code (declaration order)
+MODALITIES = ("image", "audio", "text", "binary", "video")
+
+#: Match-outcome tags by wire code (declaration order)
+MATCH_TAGS = ("image", "audio", "text", "binary", "video")
+
+#: Signature-stream tag bytes (declaration order)
+SIGNATURE_TAGS = ("image", "audio", "text", "binary", "video")
+
+
+class FfiError(Exception):
+    """A non-zero status code came back from the cdylib."""
+
+    def __init__(self, op: str, status: int) -> None:
+        kind = {
+            STATUS_INVALID: "invalid argument",
+            STATUS_REJECTED: "input rejected",
+        }.get(status, "unknown failure")
+        super().__init__(f"{op} failed: {kind} (status {status})")
+        self.status = status
+
+
+@dataclass(frozen=True)
+class Detection:
+    """Container sniffing result."""
+    format: str
+    modality: str
+    pending: bool
+
+
+@dataclass(frozen=True)
+class Signature:
+    """A tier-2 signature, re-expressed from the signature stream."""
+    modality: str
+    phash: int | None = None
+    peak_count: int | None = None
+    frames: int | None = None
+    peaks: tuple[tuple[int, int], ...] | None = None
+    peaks_bytes: bytes | None = None
+    word_count: int | None = None
+    words: tuple[int, ...] | None = None
+    chunk_count: int | None = None
+    digest_bytes: bytes | None = None
+    frame_count: int | None = None
+    width: int | None = None
+    height: int | None = None
+    duration_bits: int | None = None
+    frame_hashes: tuple[int, ...] | None = None
+    minhash: tuple[int, ...] | None = None
+
+
+@dataclass(frozen=True)
+class Description:
+    """Both tiers plus facts, re-expressed from the describe stream."""
+    format: str
+    modality: str
+    tier1: str
+    signature: Signature
+    facts: dict
+
+
+@dataclass(frozen=True)
+class MatchResult:
+    """A match outcome, re-expressed from the slots."""
+    tag: str
+    slots: tuple[int, ...]
+    matched: bool
+
+    def slot_float(self, index: int) -> float:
+        """Reinterprets slot `index` as an IEEE-754 double."""
+        return struct.unpack("<d", struct.pack("<Q", self.slots[index]))[0]
+
+
+def version() -> str:
+    """Returns library version string."""
+    return f"{sillstone_version_major_raw()}.{sillstone_version_minor_raw()}.{sillstone_version_patch_raw()}"
+
+
+def buffer_checksum(data: bytes) -> int:
+    """Computes standard 64-bit FNV-1a checksum over input bytes."""
+    return int(sillstone_buffer_checksum_raw(data, len(data)))
+
+
+def sha256(data: bytes) -> bytes:
+    """Computes 32-byte SHA-256 digest."""
+    out = ctypes.create_string_buffer(32)
+    rc = sillstone_digest_sha256_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("sha256", rc)
+    return out.raw
+
+
+def sha3_256(data: bytes) -> bytes:
+    """Computes 32-byte SHA-3-256 digest."""
+    out = ctypes.create_string_buffer(32)
+    rc = sillstone_digest_sha3_256_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("sha3_256", rc)
+    return out.raw
+
+
+def sha3_512(data: bytes) -> bytes:
+    """Computes 64-byte SHA-3-512 digest."""
+    out = ctypes.create_string_buffer(64)
+    rc = sillstone_digest_sha3_512_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("sha3_512", rc)
+    return out.raw
+
+
+def blake2b_512(data: bytes) -> bytes:
+    """Computes 64-byte unkeyed BLAKE2b digest."""
+    out = ctypes.create_string_buffer(64)
+    rc = sillstone_digest_blake2b_512_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("blake2b_512", rc)
+    return out.raw
+
+
+def blake3(data: bytes) -> bytes:
+    """Computes 32-byte BLAKE3 digest."""
+    out = ctypes.create_string_buffer(32)
+    rc = sillstone_digest_blake3_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("blake3", rc)
+    return out.raw
+
+
+def dst1(data: list[float]) -> list[float]:
+    """Computes orthonormal DST-I over input float array."""
+    c_in = (ctypes.c_double * len(data))(*data)
+    c_out = (ctypes.c_double * len(data))()
+    rc = sillstone_math_dst1_raw(c_in, len(data), c_out)
+    if rc != 0:
+        raise FfiError("dst1", rc)
+    return list(c_out)
+
+
+def dst2(data: list[float]) -> list[float]:
+    """Computes orthonormal DST-II over input float array."""
+    c_in = (ctypes.c_double * len(data))(*data)
+    c_out = (ctypes.c_double * len(data))()
+    rc = sillstone_math_dst2_raw(c_in, len(data), c_out)
+    if rc != 0:
+        raise FfiError("dst2", rc)
+    return list(c_out)
+
+
+def dst3(data: list[float]) -> list[float]:
+    """Computes orthonormal DST-III over input float array."""
+    c_in = (ctypes.c_double * len(data))(*data)
+    c_out = (ctypes.c_double * len(data))()
+    rc = sillstone_math_dst3_raw(c_in, len(data), c_out)
+    if rc != 0:
+        raise FfiError("dst3", rc)
+    return list(c_out)
+
+
+def grapheme_count(text: str) -> int:
+    """Counts UAX #29 grapheme clusters in a string."""
+    raw = text.encode("utf-8")
+    count = ctypes.c_size_t()
+    rc = sillstone_unicode_grapheme_count_raw(raw, len(raw), ctypes.byref(count))
+    if rc != 0:
+        raise FfiError("grapheme_count", rc)
+    return count.value
+
+
+def char_category(char: str) -> int:
+    """Returns general category tag for a single character."""
+    cp = ord(char[0])
+    cat = ctypes.c_uint8()
+    rc = sillstone_unicode_char_category_raw(cp, ctypes.byref(cat))
+    if rc != 0:
+        raise FfiError("char_category", rc)
+    return cat.value
+
+
+def phash(data: bytes, width: int, height: int, layout: int = 0) -> int:
+    """Computes 64-bit perceptual hash (pHash) of an image."""
+    out = ctypes.c_uint64()
+    rc = sillstone_image_phash_raw(data, len(data), width, height, layout, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("phash", rc)
+    return out.value
+
+
+def ahash(data: bytes, width: int, height: int, layout: int = 0) -> int:
+    """Computes 64-bit average hash (aHash) of an image."""
+    out = ctypes.c_uint64()
+    rc = sillstone_image_ahash_raw(data, len(data), width, height, layout, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("ahash", rc)
+    return out.value
+
+
+def dhash(data: bytes, width: int, height: int, layout: int = 0) -> int:
+    """Computes 64-bit difference hash (dHash) of an image."""
+    out = ctypes.c_uint64()
+    rc = sillstone_image_dhash_raw(data, len(data), width, height, layout, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("dhash", rc)
+    return out.value
+
+
+def whash(data: bytes, width: int, height: int, layout: int = 0) -> int:
+    """Computes 64-bit wavelet hash (wHash) of an image."""
+    out = ctypes.c_uint64()
+    rc = sillstone_image_whash_raw(data, len(data), width, height, layout, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("whash", rc)
+    return out.value
+
+
+def colorhash(data: bytes, width: int, height: int, layout: int = 0) -> int:
+    """Computes 64-bit color distribution hash of an image."""
+    out = ctypes.c_uint64()
+    rc = sillstone_image_colorhash_raw(data, len(data), width, height, layout, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("colorhash", rc)
+    return out.value
+
+
+def tlsh(data: bytes) -> str:
+    """Computes 70-hex-char TrendMicro Locality Sensitive Hash string."""
+    out = ctypes.create_string_buffer(72)
+    rc = sillstone_text_tlsh_raw(data, len(data), out)
+    if rc != 0:
+        raise FfiError("tlsh", rc)
+    return out.raw.decode("ascii", errors="replace")
+
+
+def tlsh_distance(hash_a: str | bytes, hash_b: str | bytes) -> int:
+    """Computes TLSH distance between two 70-hex-char hashes."""
+    a_bytes = hash_a.encode("ascii") if isinstance(hash_a, str) else hash_a
+    b_bytes = hash_b.encode("ascii") if isinstance(hash_b, str) else hash_b
+    out = ctypes.c_uint32()
+    rc = sillstone_text_tlsh_distance_raw(a_bytes, b_bytes, ctypes.byref(out))
+    if rc != 0:
+        raise FfiError("tlsh_distance", rc)
+    return out.value
+
+
+def fnv1a64(data: bytes) -> int:
+    """The 64-bit FNV-1a fold the reference sub-digests use."""
+    h = 0xCBF29CE484222325
+    for b in data:
+        h ^= b
+        h = (h * 0x100000001B3) & 0xFFFFFFFFFFFFFFFF
+    return h
+
+
+def detect(data: bytes) -> Detection:
+    """Sniffs container and modality without full decode."""
+    fmt = ctypes.c_uint32()
+    mod = ctypes.c_uint32()
+    pending = ctypes.c_uint32()
+    rc = sillstone_curator_detect_raw(
+        data, len(data), ctypes.byref(fmt), ctypes.byref(mod), ctypes.byref(pending)
+    )
+    if rc != 0:
+        raise FfiError("curator_detect", rc)
+    return Detection(
+        format=FORMATS[fmt.value],
+        modality=MODALITIES[mod.value],
+        pending=pending.value == 1,
+    )
+
+
+def content_hash(data: bytes) -> bytes:
+    """Computes 32-byte tier-1 content digest."""
+    buf = (ctypes.c_ubyte * 32)()
+    out_len = ctypes.c_size_t()
+    rc = sillstone_curator_content_hash_raw(data, len(data), buf, len(buf), ctypes.byref(out_len))
+    if rc != 0:
+        raise FfiError("curator_content_hash", rc)
+    return bytes(buf)
+
+
+def _stream_op(raw_fn, data: bytes) -> bytes:
+    out = ctypes.c_void_p()
+    out_len = ctypes.c_size_t()
+    rc = raw_fn(data, len(data), ctypes.byref(out), ctypes.byref(out_len))
+    if rc != 0:
+        raise FfiError(raw_fn.__name__, rc)
+    try:
+        return ctypes.string_at(out, out_len.value)
+    finally:
+        sillstone_curator_free_raw(out, out_len.value)
+
+
+def signature(data: bytes) -> Signature:
+    """Computes tier-2 signature stream and parses it into a Signature object."""
+    return parse_signature(_stream_op(sillstone_curator_signature_raw, data))
+
+
+def describe(data: bytes) -> Description:
+    """Computes both tiers and parses the describe stream."""
+    return parse_describe(_stream_op(sillstone_curator_describe_raw, data))
+
+
+def match_signatures(a: bytes, b: bytes) -> MatchResult:
+    """Scores two raw inputs across modalities."""
+    tag = ctypes.c_uint32()
+    slots = (ctypes.c_uint64 * 4)()
+    matched = ctypes.c_uint32()
+    rc = sillstone_curator_match_raw(
+        a, len(a), b, len(b), ctypes.byref(tag), slots, len(slots), ctypes.byref(matched)
+    )
+    if rc != 0:
+        raise FfiError("curator_match", rc)
+    return MatchResult(
+        tag=MATCH_TAGS[tag.value],
+        slots=tuple(int(s) for s in slots),
+        matched=matched.value == 1,
+    )
+
+def parse_signature(raw: bytes) -> Signature:
+    """Re-expresses the canonical signature stream as a Signature."""
+    if len(raw) < 1:
+        raise ValueError("signature stream is empty")
+    tag = raw[0]
+    if tag >= len(SIGNATURE_TAGS):
+        raise ValueError(f"unknown signature tag {tag}")
+    modality = SIGNATURE_TAGS[tag]
+    if modality == "image":
+        if len(raw) != 9:
+            raise ValueError("image stream is not tag + u64")
+        return Signature(modality=modality, phash=int.from_bytes(raw[1:9], "big"))
+    if modality == "audio":
+        if len(raw) < 13:
+            raise ValueError("audio stream is shorter than its 13-byte header")
+        peak_count = int.from_bytes(raw[1:9], "big")
+        frames = int.from_bytes(raw[9:13], "big")
+        payload = raw[13:]
+        if peak_count != len(payload) or len(payload) % 6 != 0:
+            raise ValueError("audio peak count disagrees with the payload")
+        peaks = tuple(
+            (
+                int.from_bytes(payload[i : i + 4], "little"),
+                int.from_bytes(payload[i + 4 : i + 6], "little"),
+            )
+            for i in range(0, len(payload), 6)
+        )
+        return Signature(
+            modality=modality,
+            peak_count=peak_count,
+            frames=frames,
+            peaks=peaks,
+            peaks_bytes=payload,
+        )
+    if modality == "text":
+        if len(raw) < 9:
+            raise ValueError("text stream is shorter than its 9-byte header")
+        word_count = int.from_bytes(raw[1:9], "big")
+        payload = raw[9:]
+        if word_count != len(payload) or len(payload) % 8 != 0:
+            raise ValueError("text word count disagrees with the payload")
+        words = tuple(int.from_bytes(payload[i : i + 8], "big") for i in range(0, len(payload), 8))
+        return Signature(modality=modality, word_count=word_count, words=words)
+    if modality == "binary":
+        if len(raw) < 9:
+            raise ValueError("binary stream is shorter than its 9-byte header")
+        chunk_count = int.from_bytes(raw[1:9], "big")
+        payload = raw[9:]
+        if chunk_count != len(payload) or len(payload) % 32 != 0:
+            raise ValueError("binary chunk count disagrees with the payload")
+        return Signature(modality=modality, chunk_count=chunk_count, digest_bytes=payload)
+    # video
+    if len(raw) < 18:
+        raise ValueError("video stream is shorter than its 18-byte header")
+    frame_count = int.from_bytes(raw[1:5], "big")
+    width = int.from_bytes(raw[5:9], "big")
+    height = int.from_bytes(raw[9:13], "big")
+    duration_bits = int.from_bytes(raw[13:21], "big")
+    rest = raw[21:]
+    if frame_count > len(rest) or frame_count % 8 != 0:
+        raise ValueError("video frame count disagrees with the payload")
+    frames_payload = rest[:frame_count]
+    minhash_payload = rest[frame_count:]
+    if len(minhash_payload) % 8 != 0:
+        raise ValueError("video minhash payload is not whole words")
+    return Signature(
+        modality=modality,
+        frame_count=frame_count,
+        width=width,
+        height=height,
+        duration_bits=duration_bits,
+        frame_hashes=tuple(
+            int.from_bytes(frames_payload[i : i + 8], "little")
+            for i in range(0, len(frames_payload), 8)
+        ),
+        minhash=tuple(
+            int.from_bytes(minhash_payload[i : i + 8], "little")
+            for i in range(0, len(minhash_payload), 8)
+        ),
+    )
+
+
+def parse_describe(raw: bytes) -> Description:
+    """Re-expresses the canonical describe stream as a Description."""
+    if len(raw) < 35:
+        raise ValueError("describe stream is shorter than its 35-byte header")
+    fmt = raw[0]
+    mod = raw[1]
+    if fmt >= len(FORMATS) or mod >= len(MODALITIES):
+        raise ValueError(f"unknown describe codes {fmt}/{mod}")
+    tier1 = raw[2:34].hex()
+    modality = MODALITIES[mod]
+    sig_end = len(raw) - _facts_len(modality)
+    sig = parse_signature(raw[34:sig_end])
+    facts_raw = raw[sig_end:]
+    facts: dict = {}
+    if modality == "image":
+        _need(facts_raw, 16)
+        facts = {"width": _be32(facts_raw, 0), "height": _be32(facts_raw, 4), "keypoints": _be64(facts_raw, 8)}
+    elif modality == "audio":
+        _need(facts_raw, 18)
+        facts = {
+            "sample_rate": _be32(facts_raw, 0),
+            "channels": int.from_bytes(facts_raw[4:6], "big"),
+            "frames": _be32(facts_raw, 6),
+            "peaks": _be64(facts_raw, 10),
+        }
+    elif modality == "text":
+        _need(facts_raw, 16)
+        facts = {"words": _be64(facts_raw, 0), "canonical_len": _be64(facts_raw, 8)}
+    elif modality == "binary":
+        _need(facts_raw, 16)
+        facts = {"len": _be64(facts_raw, 0), "chunks": _be64(facts_raw, 8)}
+    else:
+        _need(facts_raw, 24)
+        facts = {
+            "width": _be32(facts_raw, 0),
+            "height": _be32(facts_raw, 4),
+            "duration_bits": _be64(facts_raw, 8),
+            "frames_sampled": _be64(facts_raw, 16),
+        }
+    return Description(format=FORMATS[fmt], modality=modality, tier1=tier1, signature=sig, facts=facts)
+
+
+def _be32(raw: bytes, off: int) -> int:
+    return int.from_bytes(raw[off : off + 4], "big")
+
+
+def _be64(raw: bytes, off: int) -> int:
+    return int.from_bytes(raw[off : off + 8], "big")
+
+
+def _need(raw: bytes, n: int) -> None:
+    if len(raw) != n:
+        raise ValueError(f"facts block is {len(raw)} bytes, want {n}")
+
+
+def _facts_len(modality: str) -> int:
+    if modality == "audio":
+        return 18
+    if modality == "video":
+        return 24
+    return 16

sillstone-0.2.0/sillstone/_generated.py

@@ -0,0 +1,238 @@
+# Generated by sillstone-idl-gen. DO NOT EDIT.
+import ctypes
+import os
+import sys
+
+def _load_lib():
+    ext = '.dll' if sys.platform == 'win32' else ('.dylib' if sys.platform == 'darwin' else '.so')
+    prefix = '' if sys.platform == 'win32' else 'lib'
+    lib_name = f'{prefix}sillstone_ffi{ext}'
+    dir_path = os.path.dirname(os.path.abspath(__file__))
+    candidates = [
+        os.path.join(dir_path, lib_name),
+        os.path.join(dir_path, '..', '..', '..', 'target', 'release', lib_name),
+        os.path.join(dir_path, '..', '..', '..', 'target', 'debug', lib_name),
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return ctypes.CDLL(c)
+    return None
+
+LIB = _load_lib()
+
+def sillstone_version_major_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_version_major')
+    fn.restype = ctypes.c_uint32
+    fn.argtypes = []
+    return fn(*args)
+
+def sillstone_version_minor_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_version_minor')
+    fn.restype = ctypes.c_uint32
+    fn.argtypes = []
+    return fn(*args)
+
+def sillstone_version_patch_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_version_patch')
+    fn.restype = ctypes.c_uint32
+    fn.argtypes = []
+    return fn(*args)
+
+def sillstone_buffer_checksum_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_buffer_checksum')
+    fn.restype = ctypes.c_uint64
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t]
+    return fn(*args)
+
+def sillstone_digest_sha256_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_digest_sha256')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_digest_sha3_256_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_digest_sha3_256')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_digest_sha3_512_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_digest_sha3_512')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_digest_blake2b_512_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_digest_blake2b_512')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_digest_blake3_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_digest_blake3')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_math_dst1_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_math_dst1')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.c_size_t, ctypes.POINTER(ctypes.c_double)]
+    return fn(*args)
+
+def sillstone_math_dst2_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_math_dst2')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.c_size_t, ctypes.POINTER(ctypes.c_double)]
+    return fn(*args)
+
+def sillstone_math_dst3_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_math_dst3')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.c_size_t, ctypes.POINTER(ctypes.c_double)]
+    return fn(*args)
+
+def sillstone_unicode_grapheme_count_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_unicode_grapheme_count')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_size_t)]
+    return fn(*args)
+
+def sillstone_unicode_char_category_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_unicode_char_category')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_uint32, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_curator_detect_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_detect')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_uint32), ctypes.POINTER(ctypes.c_uint32), ctypes.POINTER(ctypes.c_uint32)]
+    return fn(*args)
+
+def sillstone_curator_content_hash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_content_hash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_size_t)]
+    return fn(*args)
+
+def sillstone_curator_signature_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_signature')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(ctypes.c_size_t)]
+    return fn(*args)
+
+def sillstone_curator_describe_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_describe')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(ctypes.c_size_t)]
+    return fn(*args)
+
+def sillstone_curator_match_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_match')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p, ctypes.c_size_t, ctypes.POINTER(ctypes.c_uint32), ctypes.POINTER(ctypes.c_uint64), ctypes.c_size_t, ctypes.POINTER(ctypes.c_uint32)]
+    return fn(*args)
+
+def sillstone_curator_free_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_curator_free')
+    fn.restype = None
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t]
+    return fn(*args)
+
+def sillstone_image_phash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_image_phash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)]
+    return fn(*args)
+
+def sillstone_image_ahash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_image_ahash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)]
+    return fn(*args)
+
+def sillstone_image_dhash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_image_dhash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)]
+    return fn(*args)
+
+def sillstone_image_whash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_image_whash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)]
+    return fn(*args)
+
+def sillstone_image_colorhash_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_image_colorhash')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)]
+    return fn(*args)
+
+def sillstone_text_tlsh_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_text_tlsh')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p]
+    return fn(*args)
+
+def sillstone_text_tlsh_distance_raw(*args):
+    if LIB is None:
+        raise RuntimeError('sillstone_ffi library not loaded')
+    fn = getattr(LIB, 'sillstone_text_tlsh_distance')
+    fn.restype = ctypes.c_int32
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_uint32)]
+    return fn(*args)
+

sillstone-0.2.0/sillstone.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: sillstone
+Version: 0.2.0
+Summary: Pure-Rust zero-dependency multimedia, hashing, and array computing suite
+Author: Sillstone Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/sillstone/sillstone
+Project-URL: Repository, https://github.com/sillstone/sillstone
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown

sillstone-0.2.0/sillstone.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+pyproject.toml
+sillstone/__init__.py
+sillstone/_generated.py
+sillstone.egg-info/PKG-INFO
+sillstone.egg-info/SOURCES.txt
+sillstone.egg-info/dependency_links.txt
+sillstone.egg-info/top_level.txt
+tests/test_checksum.py
+tests/test_reference_vectors.py

sillstone-0.2.0/sillstone.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sillstone-0.2.0/sillstone.egg-info/top_level.txt

@@ -0,0 +1 @@
+sillstone

sillstone-0.2.0/tests/test_checksum.py

@@ -0,0 +1,63 @@
+import unittest
+import sys
+import os
+
+# Add sdk/python to sys.path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+import sillstone
+
+
+class TestSillstonePython(unittest.TestCase):
+    def test_version(self):
+        v = sillstone.version()
+        self.assertEqual(v, "0.2.0")
+
+    def test_checksum_sample(self):
+        data = b"sillstone pure rust zero dep"
+        res = sillstone.buffer_checksum(data)
+        # Expected FNV-1a 64-bit checksum
+        # Compute reference in pure Python
+        h = 0xcbf29ce484222325
+        for b in data:
+            h ^= b
+            h = (h * 0x0100000001b3) & 0xffffffffffffffff
+        self.assertEqual(res, h)
+
+    def test_digests(self):
+        import hashlib
+        data = b"abc"
+        self.assertEqual(sillstone.sha256(data).hex(), hashlib.sha256(data).hexdigest())
+        self.assertEqual(sillstone.sha3_256(data).hex(), hashlib.sha3_256(data).hexdigest())
+        self.assertEqual(sillstone.sha3_512(data).hex(), hashlib.sha3_512(data).hexdigest())
+        self.assertEqual(sillstone.blake2b_512(data).hex(), hashlib.blake2b(data).hexdigest())
+        # BLAKE3 "abc" reference
+        self.assertEqual(sillstone.blake3(b"").hex(), "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262")
+
+    def test_dst(self):
+        x = [1.0, 2.0, 3.0, 4.0]
+        d1 = sillstone.dst1(x)
+        self.assertEqual(len(d1), 4)
+        # dst1 is self-inverse when orthonormal
+        rec1 = sillstone.dst1(d1)
+        for a, b in zip(x, rec1):
+            self.assertAlmostEqual(a, b, places=10)
+
+        # dst2 and dst3 are mutually inverse
+        d2 = sillstone.dst2(x)
+        rec2 = sillstone.dst3(d2)
+        for a, b in zip(x, rec2):
+            self.assertAlmostEqual(a, b, places=10)
+
+    def test_unicode(self):
+        # Family emoji (4 emoji chars + 3 ZWJ): 1 grapheme cluster
+        fam = "👨‍👩‍👧‍👦"
+        self.assertEqual(sillstone.grapheme_count(fam), 1)
+        self.assertEqual(sillstone.grapheme_count("Hello"), 5)
+        self.assertEqual(sillstone.grapheme_count(""), 0)
+        cat_a = sillstone.char_category("A")
+        self.assertGreaterEqual(cat_a, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

sillstone-0.2.0/tests/test_reference_vectors.py

@@ -0,0 +1,367 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 pith-hash / sillstone Contributors
+"""Hex-exact conformance: the committed reference vectors through Python.
+
+Every one of the 45 vectors in the repository-root reference.json is replayed
+through Python ctypes and compared against every recorded field:
+  - 13 detect codes
+  - 14 tier-2 signature fold sets (pHash, audio peaks, text/video minhash,
+    cdc chunk digests, frame hashes)
+  - 7 tier-1 / tier-2 describe packets
+  - 9 match-outcome slot vectors
+  - 2 pinned refusal errors (cross-modality, non-AVC video)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import struct
+import unittest
+from pathlib import Path
+
+from sillstone import (
+    FORMATS,
+    FfiError,
+    MatchResult,
+    MODALITIES,
+    Description,
+    Detection,
+    Signature,
+    content_hash,
+    describe,
+    detect,
+    fnv1a64,
+    match_signatures,
+    signature,
+)
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+REFERENCE = json.loads((REPO_ROOT / "reference.json").read_text(encoding="utf-8"))["vectors"]
+BY_NAME = {v["name"]: v for v in REFERENCE}
+FIXTURES = REPO_ROOT / "tests" / "fixtures"
+
+MASK64 = (1 << 64) - 1
+
+
+# ---------------------------------------------------------------------
+# The deterministic inline corpus (transcribed from tools/gen-reference)
+# ---------------------------------------------------------------------
+
+
+class SplitMix64:
+    """The 64-bit generator behind every inline recipe."""
+
+    def __init__(self, seed: int) -> None:
+        self.s = seed & MASK64
+
+    def next_u64(self) -> int:
+        self.s = (self.s + 0x9E3779B97F4A7C15) & MASK64
+        z = self.s
+        z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & MASK64
+        z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & MASK64
+        return z ^ (z >> 31)
+
+
+def splitmix_bytes(seed: int, length: int) -> bytes:
+    """One next_u64 per byte, low byte kept — the upstream recipe."""
+    rng = SplitMix64(seed)
+    return bytes(rng.next_u64() & 0xFF for _ in range(length))
+
+
+def blob48(seed: int) -> bytes:
+    """The 48 KiB pseudo-file recipe of the upstream facade suite."""
+    return splitmix_bytes(seed, 48 * 1024)
+
+
+VOCAB = (
+    "hash", "image", "audio", "signal", "codec", "block", "frame", "sample", "stream",
+    "vector", "median", "kernel", "window", "raster", "pixel", "tone", "hash", "luma",
+    "delta", "chunk", "radix", "filter", "table", "edge",
+)
+
+
+def prose(seed: int, size: int) -> str:
+    """Seeded vocabulary words, one space apart, truncated to `size`."""
+    rng = SplitMix64(seed)
+    out = ""
+    while len(out) < size:
+        out += VOCAB[rng.next_u64() % len(VOCAB)] + " "
+    return out[:size]
+
+
+def patterned_pixels(seed: int, w: int, h: int) -> bytes:
+    """Smooth periodic RGB content with real low-frequency energy."""
+    rng = SplitMix64(seed)
+    fx = float(rng.next_u64() % 5 + 1)
+    fy = float(rng.next_u64() % 5 + 1)
+    p1 = (rng.next_u64() % 628) / 100.0
+    p2 = (rng.next_u64() % 628) / 100.0
+    px = bytearray()
+    for y in range(h):
+        for x in range(w):
+            u = x / w
+            v = y / h
+            r = 127.5 + 120.0 * math.sin(u * fx * (2 * math.pi) + p1)
+            g = 127.5 + 120.0 * math.sin(v * fy * (2 * math.pi) + p2)
+            b = 127.5 + 120.0 * math.sin((u + v) * (fx + fy) + p1 + p2)
+            px += bytes((int(r) & 0xFF, int(g) & 0xFF, int(b) & 0xFF))
+    return bytes(px)
+
+
+def bmp24(w: int, h: int, rgb: bytes) -> bytes:
+    """Bottom-up 24-bit BMP — the suite's deterministic fixture encoder."""
+    assert len(rgb) == w * h * 3
+    row = ((w * 3 + 3) // 4) * 4
+    img = row * h
+    f = bytearray()
+    f += b"BM"
+    f += struct.pack("<I", 54 + img)
+    f += b"\x00\x00\x00\x00"
+    f += struct.pack("<I", 54)
+    f += struct.pack("<I", 40)
+    f += struct.pack("<ii", w, h)
+    f += struct.pack("<hh", 1, 24)
+    f += b"\x00" * 24
+    for y in range(h - 1, -1, -1):
+        for x in range(w):
+            i = (y * w + x) * 3
+            f += bytes((rgb[i + 2], rgb[i + 1], rgb[i]))
+        f += b"\x00" * (row - w * 3)
+    return bytes(f)
+
+
+def fixture(name: str) -> bytes:
+    p = FIXTURES / name
+    if not p.is_file():
+        raise FileNotFoundError(f"Fixture {p} is missing")
+    return p.read_bytes()
+
+
+# Pinned payloads constructed identically to tools/gen-reference:
+PNG48 = fixture("phash_rgb8_48x40.png")
+GRAY40 = fixture("phash_gray8_40x32.png")
+PNG_BASE = fixture("base_444.png")
+JPG_BASE = fixture("base_444.jpg")
+WAV = fixture("tone.wav")
+FLAC = fixture("tone.flac")
+MP3 = fixture("l3_short.mp3")
+MP4 = fixture("a_64x48.mp4")
+MOV = fixture("a_64x48.mov")
+MP4V = fixture("e_mp4v.mp4")
+PDF = fixture("text_page.pdf")
+
+BMP_SYNTH = bmp24(48, 40, patterned_pixels(0xBEEF_0001, 48, 40))
+BLOB = blob48(0xD15E_5EED)
+BLOB_SHIFTED = b"\xaa" + blob48(0xD15E_5EED)
+BLOB_OTHER = blob48(0xBADC_0FFE)
+PROSE_A = prose(0xD1, 4096).encode()
+PROSE_B = prose(0xD2, 4096).encode()
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def le_words(words) -> bytes:
+    """The canonical word fold: little-endian words concatenated."""
+    return b"".join(struct.pack("<Q", w & MASK64) for w in words)
+
+
+MATCH_INPUTS = {
+    "match-image-self": (PNG48, PNG48, "image"),
+    "match-image-distinct": (PNG48, GRAY40, "image"),
+    "match-image-png-vs-jpeg-same-pixels": (PNG_BASE, JPG_BASE, "image"),
+    "match-audio-self": (WAV, WAV, "audio"),
+    "match-text-self": (PROSE_A, PROSE_A, "text"),
+    "match-text-distinct": (PROSE_A, PROSE_B, "text"),
+    "match-binary-near-duplicate": (BLOB, BLOB_SHIFTED, "binary"),
+    "match-binary-unrelated": (BLOB, BLOB_OTHER, "binary"),
+    "match-video-mp4-vs-mov": (MP4, MOV, "video"),
+}
+
+
+class TestReferenceVectors(unittest.TestCase):
+    def test_detect_vectors(self):
+        cases = [
+            ("detect-png", PNG48),
+            ("detect-jpeg", JPG_BASE),
+            ("detect-bmp", BMP_SYNTH),
+            ("detect-wav", WAV),
+            ("detect-flac", FLAC),
+            ("detect-mp3", MP3),
+            ("detect-mp4", MP4),
+            ("detect-mov", MOV),
+            ("detect-pdf", PDF),
+            ("detect-zip", b"PK\x03\x04\x14\x00\x00\x00\x00\x00"),
+            ("detect-gif", b"GIF89a\x01\x00\x01\x00"),
+            ("detect-text", b"just some words"),
+            ("detect-binary", b"\x00\xff\x02\xfe"),
+        ]
+        for name, data in cases:
+            with self.subTest(vector=name):
+                rec = BY_NAME[name]
+                d: Detection = detect(data)
+                self.assertEqual(d.format, rec["format"])
+                self.assertEqual(d.modality, rec["modality"])
+                self.assertEqual(d.pending, rec["pending"])
+                self.assertIn(FORMATS.index(d.format), range(len(FORMATS)))
+                self.assertIn(MODALITIES.index(d.modality), range(len(MODALITIES)))
+
+    def assert_signature_matches(self, sig: Signature, rec: dict):
+        self.assertEqual(sig.modality, rec["modality"])
+        if sig.modality == "image":
+            self.assertEqual(sig.phash, int(rec["phash"], 16))
+        elif sig.modality == "audio":
+            self.assertEqual(sig.peak_count, rec["peak_count"])
+            self.assertEqual(sig.frames, rec["frames"])
+            self.assertEqual(fnv1a64(sig.peaks_bytes), int(rec["peaks_fnv1a64"], 16))
+            self.assertEqual(sha256_hex(sig.peaks_bytes), rec["peaks_sha256"])
+        elif sig.modality == "text":
+            self.assertEqual(sig.word_count, rec["minhash_words"])
+            fold = le_words(sig.words)
+            self.assertEqual(len(fold), sig.word_count)
+            self.assertEqual(fnv1a64(fold), int(rec["minhash_fnv1a64"], 16))
+        elif sig.modality == "binary":
+            self.assertEqual(sig.chunk_count, rec["chunk_count"])
+            self.assertEqual(fnv1a64(sig.digest_bytes), int(rec["chunks_fnv1a64"], 16))
+            self.assertEqual(sha256_hex(sig.digest_bytes), rec["chunks_sha256"])
+        else:  # video
+            self.assertEqual(sig.frame_count, rec["frame_count"])
+            frames_fold = le_words(sig.frame_hashes)
+            self.assertEqual(len(frames_fold), sig.frame_count)
+            self.assertEqual(fnv1a64(frames_fold), int(rec["frames_fnv1a64"], 16))
+            self.assertEqual(sha256_hex(frames_fold), rec["frames_sha256"])
+            self.assertIsNotNone(sig.minhash)
+            minhash_fold = le_words(sig.minhash)
+            self.assertEqual(len(minhash_fold), rec["minhash_words"])
+            self.assertEqual(fnv1a64(minhash_fold), int(rec["minhash_fnv1a64"], 16))
+            self.assertEqual(sig.width, rec["width"])
+            self.assertEqual(sig.height, rec["height"])
+            self.assertEqual(f"{sig.duration_bits:016x}", rec["duration_bits"])
+
+    def test_signature_vectors(self):
+        cases = [
+            ("sig-image-phash_rgb8_48x40", PNG48),
+            ("sig-image-phash_gray8_40x32", GRAY40),
+            ("sig-image-base_444-png", PNG_BASE),
+            ("sig-image-base_444-jpeg", JPG_BASE),
+            ("sig-image-bmp-patterned-48x40", BMP_SYNTH),
+            ("sig-audio-tone-wav", WAV),
+            ("sig-audio-tone-flac", FLAC),
+            ("sig-audio-l3_short-mp3", MP3),
+            ("sig-text-prose-4kib", PROSE_A),
+            ("sig-binary-splitmix64-48kib", BLOB),
+            ("sig-binary-splitmix64-48kib-prefix-insert", BLOB_SHIFTED),
+            ("sig-binary-splitmix64-48kib-unrelated", BLOB_OTHER),
+            ("sig-video-a_64x48-mp4", MP4),
+            ("sig-pdf-text_page", PDF),
+        ]
+        for name, data in cases:
+            with self.subTest(vector=name):
+                self.assert_signature_matches(signature(data), BY_NAME[name])
+
+    def test_describe_vectors(self):
+        cases = [
+            ("describe-image-phash_rgb8_48x40", PNG48),
+            ("describe-image-bmp-patterned-48x40", BMP_SYNTH),
+            ("describe-audio-tone-wav", WAV),
+            ("describe-text-prose-4kib", PROSE_A),
+            ("describe-binary-splitmix64-48kib", BLOB),
+            ("describe-video-a_64x48-mp4", MP4),
+            ("describe-pdf-text_page", PDF),
+        ]
+        for name, data in cases:
+            with self.subTest(vector=name):
+                rec = BY_NAME[name]
+                d: Description = describe(data)
+                self.assertEqual(d.format, rec["format"])
+                self.assertEqual(d.modality, rec["modality"])
+                self.assertEqual(d.tier1, rec["tier1"])
+                self.assert_signature_matches(d.signature, rec)
+                facts = d.facts
+                if d.modality == "image":
+                    self.assertEqual(facts["width"], rec["facts"]["width"])
+                    self.assertEqual(facts["height"], rec["facts"]["height"])
+                    self.assertEqual(facts["keypoints"], rec["facts"]["keypoints"])
+                elif d.modality == "audio":
+                    self.assertEqual(facts["sample_rate"], rec["facts"]["sample_rate"])
+                    self.assertEqual(facts["channels"], rec["facts"]["channels"])
+                    self.assertEqual(facts["frames"], rec["facts"]["frames"])
+                    self.assertEqual(facts["peaks"], rec["facts"]["peaks"])
+                elif d.modality == "text":
+                    self.assertEqual(facts["words"], rec["facts"]["words"])
+                    self.assertEqual(facts["canonical_len"], rec["facts"]["canonical_len"])
+                elif d.modality == "binary":
+                    self.assertEqual(facts["len"], rec["facts"]["len"])
+                    self.assertEqual(facts["chunks"], rec["facts"]["chunks"])
+                else:  # video
+                    self.assertEqual(facts["width"], rec["facts"]["width"])
+                    self.assertEqual(facts["height"], rec["facts"]["height"])
+                    self.assertEqual(f"{facts['duration_bits']:016x}", rec["facts"]["duration_bits"])
+                    self.assertEqual(facts["frames_sampled"], rec["facts"]["frames_sampled"])
+
+    def test_match_vectors(self):
+        for name in sorted(MATCH_INPUTS):
+            with self.subTest(vector=name):
+                a, b, kind = MATCH_INPUTS[name]
+                rec = BY_NAME[name]
+                r: MatchResult = match_signatures(a, b)
+                self.assertEqual(r.tag, kind)
+                self.assertEqual(r.matched, rec["matched"])
+                if kind == "image":
+                    self.assertEqual(r.slots[0], rec["hamming"])
+                elif kind == "audio":
+                    if "votes" in rec and rec["votes"]:
+                        self.assertEqual(r.slots[0], rec["votes"])
+                        self.assertEqual(r.slots[1], rec["delta_t"] & MASK64)
+                    else:
+                        self.assertEqual(r.slots[0], 0)
+                elif kind == "video":
+                    self.assertEqual(f"{r.slots[0]:016x}", rec["score_bits"])
+                    self.assertEqual(f"{r.slots[1]:016x}", rec["minhash_jaccard_bits"])
+                else:
+                    self.assertEqual(f"{r.slots[0]:016x}", rec["jaccard_bits"])
+
+    def test_match_cross_modality_is_pinned_refusal(self):
+        rec = BY_NAME["match-error-cross-modality"]
+        with self.assertRaises(FfiError) as ctx:
+            match_signatures(PNG48, PROSE_A)
+        self.assertEqual(ctx.exception.status, -2)
+
+    def test_error_video_non_avc_is_pinned_refusal(self):
+        rec = BY_NAME["error-video-non-avc"]
+        with self.assertRaises(FfiError) as ctx:
+            signature(MP4V)
+        self.assertEqual(ctx.exception.status, -2)
+
+    def test_corrupt_image_is_rejected(self):
+        corrupt = b"\x89PNG\r\n\x1a\ngarbage"
+        with self.assertRaises(FfiError) as ctx:
+            signature(corrupt)
+        self.assertEqual(ctx.exception.status, -2)
+
+        with self.assertRaises(FfiError) as ctx:
+            describe(corrupt)
+        self.assertEqual(ctx.exception.status, -2)
+
+        with self.assertRaises(FfiError) as ctx:
+            content_hash(corrupt)
+        self.assertEqual(ctx.exception.status, -2)
+
+    def test_malformed_pdf_is_rejected(self):
+        with self.assertRaises(FfiError) as ctx:
+            signature(b"%PDF-1.4 garbage not a pdf")
+        self.assertEqual(ctx.exception.status, -2)
+
+    def test_content_hash_literal_pin(self):
+        self.assertEqual(
+            content_hash(PNG48).hex(),
+            "1f7637f88725b1f3c1b60fb5559486349298b2a5525bac5fb1df196651e0cb74",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()