implicant 0.2.0__py3-none-any.whl

implicant/config.py

@@ -0,0 +1,46 @@
+"""User-level SDK configuration persisted as TOML.
+
+Crypto parameters are *not* configured here — they come from each model's
+``circuit_meta.json`` (§5.1). This config only holds client-local knobs:
+where the platform lives and where to keep the public-key cache.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_DEFAULT_HOME = Path("~/.implicant").expanduser()
+_DEFAULT_PATH = _DEFAULT_HOME / "config.toml"
+
+
+class ImplicantConfig(BaseModel):
+    """Configuration loaded from ``~/.implicant/config.toml``."""
+
+    model_config = ConfigDict(frozen=True)
+
+    api_url: str = Field(default="https://api.implicant.local")
+    key_cache_dir: str = Field(default=str(_DEFAULT_HOME / "keys"))
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> "ImplicantConfig":
+        """Load config from ``path``, returning defaults if missing."""
+        target = path or _DEFAULT_PATH
+        if not target.is_file():
+            return cls()
+        return cls.model_validate(tomllib.loads(target.read_text()))
+
+    def dump_toml(self) -> str:
+        """Serialize to a minimal TOML string."""
+        return (
+            f'api_url = "{self.api_url}"\n'
+            f'key_cache_dir = "{self.key_cache_dir}"\n'
+        )
+
+    def save(self, path: Path | None = None) -> Path:
+        target = path or _DEFAULT_PATH
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(self.dump_toml())
+        return target

implicant/envelope.py

@@ -0,0 +1,76 @@
+"""§3 ciphertext envelope — wraps N SEAL ciphertext blobs in one body.
+
+This is the ``application/octet-stream`` framing the SDK sends as a predict
+request body and receives as the response body. It is *outer* framing: each
+``seal_bytes`` item is already a self-contained per-ciphertext blob produced
+by ``ClientContext.encrypt_input_bits`` (raw ``Ciphertext::save`` with its
+own SEALHeader), and the server returns items of the same shape.
+
+Layout (§3):
+
+    magic   : 8 bytes ASCII = "IMPLCTX\\0"
+    version : u32 little-endian = 1
+    count   : u32 little-endian
+    [ length : u64 LE | seal_bytes : <length> bytes ] × count
+
+The request ``count`` is the client-derived input-ct count
+(``ceil(circuit.input_bits / (slot_count/2))``); the server re-derives and
+guards it (§3, P4). The response ``count`` is the variant-determined output
+shape, read from ``len(unpack_envelope(...))`` — not from the manifest
+(``n_input_ciphertexts`` / ``n_output_ciphertexts`` are not manifest fields).
+
+Reference: ``platform/docs/FHE_INTERFACE_SPEC.md §3``.
+"""
+
+from __future__ import annotations
+
+import struct
+
+__all__ = ["pack_envelope", "unpack_envelope", "EnvelopeError", "MAGIC", "VERSION"]
+
+MAGIC = b"IMPLCTX\x00"
+VERSION = 1
+
+_HEADER = struct.Struct("<II")  # version, count
+_LEN = struct.Struct("<Q")  # per-item length prefix
+
+
+class EnvelopeError(ValueError):
+    """Raised when an envelope is malformed or truncated."""
+
+
+def pack_envelope(ciphertexts: list[bytes]) -> bytes:
+    """Frame ``ciphertexts`` into a single §3 envelope body."""
+    out = bytearray(MAGIC)
+    out += _HEADER.pack(VERSION, len(ciphertexts))
+    for blob in ciphertexts:
+        out += _LEN.pack(len(blob))
+        out += blob
+    return bytes(out)
+
+
+def unpack_envelope(body: bytes) -> list[bytes]:
+    """Parse a §3 envelope body back into its list of ciphertext blobs.
+
+    Raises:
+        EnvelopeError: on bad magic, unknown version, or truncation.
+    """
+    if body[:8] != MAGIC:
+        raise EnvelopeError("bad envelope magic")
+    version, count = _HEADER.unpack_from(body, 8)
+    if version != VERSION:
+        raise EnvelopeError(f"unsupported envelope version {version}")
+
+    items: list[bytes] = []
+    offset = 8 + _HEADER.size
+    for i in range(count):
+        if offset + _LEN.size > len(body):
+            raise EnvelopeError(f"truncated length prefix at item {i}")
+        (length,) = _LEN.unpack_from(body, offset)
+        offset += _LEN.size
+        end = offset + length
+        if end > len(body):
+            raise EnvelopeError(f"truncated ciphertext body at item {i}")
+        items.append(body[offset:end])
+        offset = end
+    return items

implicant/keys.py

@@ -0,0 +1,172 @@
+"""Key lifecycle for the SDK.
+
+Two cohesive pieces, one domain:
+
+- :class:`KeySession` — owns the live ``helut.client.ClientContext`` (and
+  therefore the secret key) for the duration of a process. Generates keys,
+  exposes the three public blobs, and is the only object able to encrypt /
+  decrypt.
+- :class:`PublicKeyCache` — persists ``key_id`` + the three *public* blobs
+  to ``~/.implicant/keys/<key_id>/`` so the client can skip re-upload when
+  the server already holds them.
+
+**No secret material is ever written to disk.** The `helut` binding exposes
+no secret-key serialization (verified against the compiled module), so a
+``KeySession`` cannot be restored from disk — a fresh process must re-run
+keygen before it can decrypt.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import numpy as np
+from helut.client import (
+    ClientContext,
+    KeyBundle,
+    Params,
+    generate_keys,
+    key_id_from_params,
+)
+
+__all__ = ["KeySession", "PublicKeyCache"]
+
+
+class KeySession:
+    """A live secret-key-holding context for one parameter set.
+
+    Construction runs BGV keygen (cost scales with ``poly_modulus_degree``),
+    so a session is created once per ``key_id`` and reused for every
+    encrypt/decrypt in the process. The secret key lives only inside the C++
+    ``ClientContext`` and is never serialized (see the module docstring).
+    """
+
+    def __init__(self, ctx: ClientContext, bundle: KeyBundle, key_id: str) -> None:
+        self._ctx = ctx
+        self._bundle = bundle
+        self._key_id = key_id
+
+    @classmethod
+    def generate(cls, params: Params) -> "KeySession":
+        """Run keygen for ``params`` and wrap the resulting context (§7)."""
+        ctx, bundle = generate_keys(params)
+        return cls(ctx, bundle, key_id_from_params(params))
+
+    @property
+    def key_id(self) -> str:
+        """Stable identifier the server indexes public blobs by (§1)."""
+        return self._key_id
+
+    @property
+    def public_bundle(self) -> KeyBundle:
+        """The three public blobs to upload (§2). No secret material."""
+        return self._bundle
+
+    def encrypt_bits(self, bits: np.ndarray) -> list[bytes]:
+        """Encrypt a flat bit vector into one or more input ciphertexts (§3).
+
+        Uses the chunked encoder so any length is supported; the client
+        derives the input-ct count from the chunking
+        (``ceil(len / (slot_count/2))``). Returns a one-element list when the
+        input fits a single row.
+
+        Args:
+            bits: 1-D ``uint8`` array from :func:`implicant.binarize.encode_row`.
+
+        Returns:
+            List of wire-format ciphertext blobs (envelope items).
+        """
+        return self._ctx.encrypt_input_bits_chunked(bits)
+
+    def decrypt_slots(self, ciphertext: bytes, n: int | None = None) -> np.ndarray:
+        """Decrypt one output ciphertext blob to its **unsigned** slot values.
+
+        The binding always returns ``uint64`` residues (§7, P14) — there is no
+        ``signed`` flag. For Variant B class scores, pass the result through
+        :func:`helut.client.decode_class_scores` (with :attr:`plain_modulus`)
+        to recover the signed logits; raw bits (Variant A) are used as-is.
+
+        Args:
+            ciphertext: One §3 envelope item returned by the server.
+            n: Truncate to the first ``n`` slots (``num_classes`` for B, the
+                last layer's LUT count for A).
+
+        Returns:
+            Slot array (``uint64`` unsigned).
+        """
+        if n is not None:
+            return self._ctx.decrypt_output_slots(ciphertext, n=n)
+        return self._ctx.decrypt_output_slots(ciphertext)
+
+    @property
+    def plain_modulus(self) -> int:
+        """The BGV plaintext modulus prime, for the Variant B signed decode.
+
+        Needed by :func:`helut.client.decode_class_scores` (balanced residue);
+        ``params.plain_modulus_bits`` is only the bit width, not the prime."""
+        return int(self._ctx.plain_modulus)
+
+
+# Blob filename → KeyBundle attribute. Single source of truth for the
+# on-disk layout, shared by read() and write().
+_BLOBS = {
+    "public_key.bin": "public_key",
+    "relin_keys.bin": "relin_keys",
+    "galois_keys.bin": "galois_keys",
+}
+
+
+class PublicKeyCache:
+    """Filesystem cache of uploaded public key blobs, keyed by ``key_id``.
+
+    Layout::
+
+        <root>/<key_id>/
+            public_key.bin
+            relin_keys.bin
+            galois_keys.bin
+
+    Lets the client check whether the public material for a ``key_id`` was
+    already produced/uploaded, so a session can skip re-sending ~28 MB of
+    Galois keys. **Public material only** — there is intentionally no
+    ``secret_key.bin``. Writes are atomic (tmp file + ``os.replace``); public
+    blobs are not secret, so no special permissions are enforced.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def _dir(self, key_id: str) -> Path:
+        return self._root / key_id
+
+    def has(self, key_id: str) -> bool:
+        """True iff all three public blobs are present for ``key_id``."""
+        d = self._dir(key_id)
+        return all((d / name).is_file() for name in _BLOBS)
+
+    def write(self, key_id: str, bundle: KeyBundle) -> None:
+        """Persist a bundle's three public blobs under ``key_id`` atomically."""
+        d = self._dir(key_id)
+        d.mkdir(parents=True, exist_ok=True)
+        for name, attr in _BLOBS.items():
+            self._write_atomic(d / name, getattr(bundle, attr))
+
+    def read(self, key_id: str) -> KeyBundle:
+        """Load the cached public blobs for ``key_id`` into a KeyBundle.
+
+        Raises:
+            FileNotFoundError: if any blob is missing.
+        """
+        d = self._dir(key_id)
+        return KeyBundle(
+            public_key=(d / "public_key.bin").read_bytes(),
+            relin_keys=(d / "relin_keys.bin").read_bytes(),
+            galois_keys=(d / "galois_keys.bin").read_bytes(),
+        )
+
+    @staticmethod
+    def _write_atomic(path: Path, data: bytes) -> None:
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_bytes(data)
+        os.replace(tmp, path)

implicant/manifest.py

@@ -0,0 +1,115 @@
+"""``circuit_meta.json`` handling — the client's sole source of crypto truth.
+
+The platform publishes one ``circuit_meta.json`` per model (§5.1). The SDK
+fetches it, validates it, rehydrates a typed ``helut.Params`` from its
+``key_params`` block, and derives the ``required_key_id`` used for key-cache
+lookup (§1). The client never *guesses* crypto params — it only reads them
+from this manifest.
+
+Validation is delegated to ``helut.io.validate_circuit_meta`` so the SDK
+and the worker share one schema guard. This module adds a thin typed view
+(:class:`CircuitMeta`) for ergonomic access to the envelope counts the
+transport layer needs.
+
+Reference: ``platform/docs/FHE_INTERFACE_SPEC.md §1, §5.1``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from helut.client import (  # provided by implicant-fhe
+    CircuitMetaError,
+    Params,
+    key_id_from_params,
+    validate_circuit_meta,
+)
+
+__all__ = ["CircuitMeta", "CircuitMetaError"]
+
+
+@dataclass(frozen=True, slots=True)
+class CircuitMeta:
+    """Typed, validated view over a fetched ``circuit_meta.json`` dict.
+
+    Holds the raw dict (the canonical artifact) plus the few fields the
+    SDK reads directly. ``Params`` and ``required_key_id`` are derived,
+    never stored redundantly on the wire.
+    """
+
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, meta: dict[str, Any]) -> "CircuitMeta":
+        """Validate ``meta`` against §5.1 and wrap it.
+
+        Raises:
+            CircuitMetaError: if the manifest fails schema validation.
+        """
+        validate_circuit_meta(meta)
+        return cls(raw=meta)
+
+    @property
+    def params(self) -> Params:
+        """Rehydrate the typed crypto params from ``key_params`` (§5.1).
+
+        This is the only place the SDK builds a ``Params``; the result
+        feeds ``generate_keys`` and the encrypt/decrypt calls.
+        """
+        return Params.from_dict(self.raw)
+
+    @property
+    def required_key_id(self) -> str:
+        """Stable key identifier the server indexes public blobs by (§1)."""
+        return key_id_from_params(self.params)
+
+    @property
+    def input_bits(self) -> int:
+        """Flat select-bit vector length the client encrypts (§5.1).
+
+        The number of input ciphertexts is derived by the client
+        (chunking ``ceil(input_bits / (poly_modulus_degree/2))``), so it is
+        not carried in the manifest.
+        """
+        return int(self.raw["circuit"]["input_bits"])
+
+    @property
+    def variant(self) -> str:
+        """Circuit variant (§5.1, P7): ``"A"`` (raw LUT bits) or ``"B"``
+        (server-side FHE classifier head → contiguous class scores)."""
+        return str(self.raw["circuit"]["variant"])
+
+    @property
+    def output_slots_per_ciphertext(self) -> int:
+        """Variant-A only: meaningful raw-bit slots ``[0, K)`` per output ct.
+
+        Forbidden for Variant B under schema v2 (B uses ``num_classes`` and
+        contiguous scores). Prefer :attr:`output_slot_count`, which is
+        variant-aware; this raw accessor ``KeyError``s on a B manifest.
+        """
+        return int(self.raw["circuit"]["output_slots_per_ciphertext"])
+
+    @property
+    def num_classes(self) -> int | None:
+        """Class count when ``variant == "B"`` (required there); else None."""
+        v = self.raw["circuit"].get("num_classes")
+        return int(v) if v is not None else None
+
+    @property
+    def output_slot_count(self) -> int:
+        """Meaningful slots to decrypt per output ct, **variant-aware** (§5.1).
+
+        Variant B → ``num_classes`` (one ct, contiguous scores ``[0, C)``);
+        Variant A → ``output_slots_per_ciphertext`` (raw LUT bits). The
+        output-ciphertext *count* comes from the response envelope length,
+        not the manifest.
+        """
+        if self.variant == "B":
+            return int(self.raw["circuit"]["num_classes"])
+        return int(self.raw["circuit"]["output_slots_per_ciphertext"])
+
+    @property
+    def binarization_spec_uri(self) -> str:
+        """Where to fetch the §4 BinarizationSpec for this model."""
+        return str(self.raw["binarization_spec_uri"])

implicant/postprocess.py

@@ -0,0 +1,73 @@
+"""Post-processing: decrypted signed class logits → predicted label.
+
+Variant B (§6): the linear head (``W·bits + b``) is evaluated **under FHE**,
+server-side. Each output ciphertext carries ``num_classes`` signed class
+logits in slots ``[0, num_classes)`` — NOT raw LUT bits. The SDK never sees
+``W`` / ``b`` / scale / bundle; its only job is threshold (binary) or argmax
+(multi-class) over the signed logits.
+
+Decode convention matches ``implicant-fhe/src/bench_tabular.cpp``:
+binary (C=1) → ``logit > 0``; multi-class (C>1) → ``argmax``.
+
+Reference: ``platform/docs/FHE_INTERFACE_SPEC.md §6`` (changelog 2026-06-18).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = ["ClassPrediction", "predict_label"]
+
+
+@dataclass(frozen=True, slots=True)
+class ClassPrediction:
+    """Result of decoding the decrypted class logits."""
+
+    label_index: int
+    scores: tuple[int, ...]
+    label: str | None = None
+
+
+def predict_label(
+    logit_slots: list[np.ndarray],
+    class_names: tuple[str, ...] | None = None,
+) -> ClassPrediction:
+    """Reduce decrypted signed-logit slots to a predicted label.
+
+    Args:
+        logit_slots: One signed-logit array per output ciphertext. Variant B
+            returns a single ct, so this has length 1 and its array holds the
+            ``C = num_classes`` signed class logits (already balanced-residue
+            decoded by ``decode_class_scores``).
+        class_names: Optional labels; length must equal the logit count.
+
+    Returns:
+        The predicted class as a :class:`ClassPrediction`. Binary (``C==1``)
+        uses a strict ``> 0`` threshold; multi-class uses argmax.
+
+    Raises:
+        ValueError: on empty input or class-name count mismatch.
+    """
+    if not logit_slots:
+        raise ValueError("no output ciphertexts to post-process")
+
+    logits = logit_slots[0]
+    scores = tuple(int(v) for v in logits)
+
+    # Binary models emit a single signed logit but choose between TWO labels
+    # (threshold at 0); multi-class emits one logit per class.
+    expected_names = 2 if len(scores) == 1 else len(scores)
+    if class_names is not None and len(class_names) != expected_names:
+        raise ValueError(
+            f"class_names has {len(class_names)} entries but the model has "
+            f"{expected_names} classes"
+        )
+
+    if len(scores) == 1:
+        best = 1 if scores[0] > 0 else 0
+    else:
+        best = int(np.argmax(logits))
+
+    label = class_names[best] if class_names is not None else None
+    return ClassPrediction(label_index=best, scores=scores, label=label)

implicant/transport/__init__.py

@@ -0,0 +1,24 @@
+"""Transport layer: the wire boundary between the SDK and the platform.
+
+The byte contracts are fixed by ``FHE_INTERFACE_SPEC.md``: the three public
+blobs (§2) and the §3 ciphertext envelope. The :class:`Transport` Protocol
+captures those operations; :class:`HttpxTransport` implements them over the
+platform REST API (``/api/v1/fhe``, routes per ``implicant/platform#361 §2``),
+and :class:`MockTransport` runs the server role in-process for demos/tests.
+"""
+
+from __future__ import annotations
+
+from .base import PredictResponse, Transport
+from .errors import KeyDepthInsufficientError, TransportError
+from .http import HttpxTransport
+from .mock import MockTransport
+
+__all__ = [
+    "Transport",
+    "PredictResponse",
+    "HttpxTransport",
+    "MockTransport",
+    "TransportError",
+    "KeyDepthInsufficientError",
+]

implicant/transport/base.py

@@ -0,0 +1,52 @@
+"""Transport Protocol and shared response types.
+
+The Protocol is intentionally small and byte-oriented. Each method maps to
+one platform interaction the client workflow needs; the exact HTTP routes
+that back them are Phase 3.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from helut.client import KeyBundle
+
+__all__ = ["Transport", "PredictResponse"]
+
+
+@dataclass(frozen=True, slots=True)
+class PredictResponse:
+    """Server response to a predict call.
+
+    ``body`` is the raw §3 envelope; the client unpacks it and takes the
+    output-ct count from ``len(unpack_envelope(body))`` (the variant-determined
+    response shape), not from the manifest (§3, P4).
+    """
+
+    body: bytes
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Operations the client needs from the platform."""
+
+    def fetch_circuit_meta(self, model_id: str) -> dict[str, Any]:
+        """Fetch the model's ``circuit_meta.json`` (§5.1) as a dict."""
+        ...
+
+    def fetch_binarization_spec(self, uri: str) -> dict[str, Any]:
+        """Fetch the §4 BinarizationSpec the manifest points at."""
+        ...
+
+    def register_keys(self, key_id: str, bundle: KeyBundle) -> None:
+        """Upload the three public blobs (§2) under ``key_id``."""
+        ...
+
+    def has_keys(self, key_id: str) -> bool:
+        """Whether the server already holds public material for ``key_id``."""
+        ...
+
+    def predict(self, model_id: str, key_id: str, envelope: bytes) -> PredictResponse:
+        """Run inference: POST the §3 request envelope, get the response one."""
+        ...

implicant/transport/errors.py

@@ -0,0 +1,58 @@
+"""Transport-layer exceptions raised by :class:`HttpxTransport`.
+
+These map platform HTTP failures (§2) to typed errors the client can branch
+on, instead of leaking raw ``httpx`` status codes upward.
+"""
+
+from __future__ import annotations
+
+__all__ = ["TransportError", "KeyDepthInsufficientError"]
+
+
+class TransportError(Exception):
+    """A platform request failed.
+
+    Carries the HTTP ``status_code`` and the parsed JSON ``payload`` (when the
+    server returned one) for callers that want to inspect the failure.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class KeyDepthInsufficientError(TransportError):
+    """The registered key supports fewer multiplicative levels than the model needs.
+
+    Raised on the platform's ``400 {"error": "key_depth_insufficient"}`` response
+    to ``predict`` (§2 / #361 §4.4 depth guard).
+    """
+
+    def __init__(
+        self,
+        *,
+        key_id: str,
+        key_L: int | None,
+        required_L: int | None,
+    ) -> None:
+        self.key_id = key_id
+        self.key_L = key_L
+        self.required_L = required_L
+        super().__init__(
+            f"key_depth_insufficient: key supports L={key_L}, "
+            f"model needs L={required_L} (key_id={key_id})",
+            status_code=400,
+            payload={
+                "error": "key_depth_insufficient",
+                "key_id": key_id,
+                "key_L": key_L,
+                "required_L": required_L,
+            },
+        )