implicant 0.2.0__py3-none-any.whl

implicant/app/wizard.py

@@ -0,0 +1,71 @@
+"""First-run onboarding dialog and the 'unsupported computer' message.
+
+The onboarding dialog collects the access key and stores it in the OS keychain.
+``show_unsupported`` is the friendly hard-stop for machines the engine can't run
+on.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import (
+    QDialog,
+    QLabel,
+    QLineEdit,
+    QMessageBox,
+    QPushButton,
+    QVBoxLayout,
+)
+
+from . import messages
+from .credentials import save_api_key
+
+if TYPE_CHECKING:
+    from .preflight import PreflightResult
+
+__all__ = ["OnboardingWizard", "show_unsupported"]
+
+
+class OnboardingWizard(QDialog):
+    """Collects the access key on first run and saves it to the keychain."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.setWindowTitle(messages.WIZARD_TITLE)
+        layout = QVBoxLayout(self)
+
+        welcome = QLabel(messages.WIZARD_WELCOME)
+        welcome.setWordWrap(True)
+        layout.addWidget(welcome)
+
+        self.key_field = QLineEdit()
+        self.key_field.setEchoMode(QLineEdit.EchoMode.Password)
+        self.key_field.setPlaceholderText(messages.ACCESS_KEY_PLACEHOLDER)
+        layout.addWidget(self.key_field)
+
+        self.error_label = QLabel("")
+        self.error_label.setWordWrap(True)
+        layout.addWidget(self.error_label)
+
+        self.save_button = QPushButton(messages.SAVE_AND_CONTINUE)
+        self.save_button.clicked.connect(self.on_save)
+        layout.addWidget(self.save_button)
+
+    def on_save(self) -> None:
+        key = self.key_field.text().strip()
+        if not key:
+            self.error_label.setText(messages.ACCESS_KEY_REQUIRED)
+            return
+        save_api_key(key)
+        self.accept()
+
+
+def show_unsupported(result: "PreflightResult") -> None:
+    """Show the friendly hard-stop message for an unsupported computer."""
+    box = QMessageBox()
+    box.setWindowTitle(messages.APP_TITLE)
+    box.setText(messages.UNSUPPORTED_TEXT)
+    box.setInformativeText(
+        messages.detected_platform_text(result.os_name, result.arch)
+    )
+    box.exec()

implicant/app/worker.py

@@ -0,0 +1,72 @@
+"""Background tasks: run the blocking prepare/predict off the UI thread and
+report progress via Qt signals. The GUI never calls the engine directly.
+
+The bare ``except Exception`` is intentional: a UI worker must surface ANY
+failure to the UI (via the ``failed`` signal) rather than crash the thread.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QRunnable, Signal
+
+if TYPE_CHECKING:  # type-only; avoids importing the native engine at runtime
+    from implicant.client import ImplicantClient, PreparedModel
+
+__all__ = ["WorkerSignals", "PrepareTask", "PredictTask"]
+
+
+class WorkerSignals(QObject):
+    stage = Signal(str)        # internal stage token
+    prepared = Signal(object)  # PreparedModel
+    finished = Signal(object)  # PredictResult
+    failed = Signal(object)    # Exception
+
+
+class PrepareTask(QRunnable):
+    """Runs ``client.prepare(model_id)`` and emits prepared/failed."""
+
+    def __init__(self, client: "ImplicantClient", model_id: str) -> None:
+        super().__init__()
+        self.signals = WorkerSignals()
+        self._client = client
+        self._model_id = model_id
+
+    def run(self) -> None:
+        try:
+            prepared = self._client.prepare(
+                self._model_id, on_stage=self.signals.stage.emit
+            )
+            self.signals.prepared.emit(prepared)
+        except Exception as exc:
+            self.signals.failed.emit(exc)
+
+
+class PredictTask(QRunnable):
+    """Runs ``client.predict_prepared(...)`` and emits finished/failed."""
+
+    def __init__(
+        self,
+        client: "ImplicantClient",
+        prepared: "PreparedModel",
+        row: dict[str, float],
+        class_labels: tuple[str, ...],
+    ) -> None:
+        super().__init__()
+        self.signals = WorkerSignals()
+        self._client = client
+        self._prepared = prepared
+        self._row = row
+        self._class_labels = class_labels
+
+    def run(self) -> None:
+        try:
+            result = self._client.predict_prepared(
+                self._prepared,
+                self._row,
+                class_names=self._class_labels,
+                on_stage=self.signals.stage.emit,
+            )
+            self.signals.finished.emit(result)
+        except Exception as exc:
+            self.signals.failed.emit(exc)

implicant/binarize.py

@@ -0,0 +1,169 @@
+"""BinarizationSpec (§4) — raw feature row → flat bit vector.
+
+The SDK owns this stage end to end; the server only ever sees the resulting
+bit vector through ciphertexts and never reads the spec. Two versions:
+
+* **v1 — thermometer** (``version: 1``, ``mode: "thermometer"``): per-feature
+  uniform min/max thermometer. ``ones = floor((x-min)/(max-min)*num_bits)``,
+  clamped to ``[0, num_bits]``; ``bits = [1]*ones + [0]*(num_bits-ones)``.
+
+* **v2 — per_feature** (``version: 2``, ``mode: "per_feature"``): per-feature
+  threshold encoding that reproduces the fitted ``TabularEncoder`` bit-for-bit.
+  The encoder standardizes (``StandardScaler`` mean/scale) then compares against
+  empirical quantile thresholds, so each feature carries ``mean``/``scale``/
+  ``thresholds`` (length ``num_bits``, ascending, in standardized space):
+  ``x_s = (x - mean)/scale``; bit ``b = 1 if x_s >= thresholds[b] else 0``.
+
+Feature ``i`` occupies the contiguous slot window
+``[Σ_{j<i} num_bits_j, Σ_{j<i} num_bits_j + num_bits_i)``; concatenated in
+declared order they form the flat input pool fed to ``encrypt_input_bits``.
+
+Reference: ``platform/docs/FHE_INTERFACE_SPEC.md §4``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Union
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+__all__ = ["ContinuousFeatureSpec", "ThresholdFeatureSpec", "BinarizationSpec", "encode_row"]
+
+_SUPPORTED_VERSIONS = frozenset({1, 2})
+
+
+class ContinuousFeatureSpec(BaseModel):
+    """One continuous feature's thermometer encoding parameters (§4 v1)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    kind: Literal["continuous"]
+    num_bits: int = Field(ge=1)
+    min: float
+    max: float
+
+    @model_validator(mode="after")
+    def _check_range(self) -> "ContinuousFeatureSpec":
+        if self.max <= self.min:
+            raise ValueError(
+                f"feature {self.name!r}: max ({self.max}) must exceed min ({self.min})"
+            )
+        return self
+
+
+class ThresholdFeatureSpec(BaseModel):
+    """One feature's per-feature threshold encoding parameters (§4 v2).
+
+    Reproduces the fitted ``TabularEncoder``: standardize then compare against
+    empirical quantile thresholds (ascending, in standardized space).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    kind: Literal["threshold"]
+    num_bits: int = Field(ge=1)
+    mean: float
+    scale: float
+    thresholds: tuple[float, ...]
+
+    @model_validator(mode="after")
+    def _check_thresholds(self) -> "ThresholdFeatureSpec":
+        if len(self.thresholds) != self.num_bits:
+            raise ValueError(
+                f"feature {self.name!r}: len(thresholds) ({len(self.thresholds)}) "
+                f"must equal num_bits ({self.num_bits})"
+            )
+        if self.scale == 0:
+            raise ValueError(f"feature {self.name!r}: scale must be non-zero")
+        return self
+
+
+FeatureSpecU = Annotated[
+    Union[ContinuousFeatureSpec, ThresholdFeatureSpec], Field(discriminator="kind")
+]
+
+
+class BinarizationSpec(BaseModel):
+    """Validated §4 spec for a whole model input row (v1 thermometer or v2 per_feature)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    version: Literal[1, 2]
+    mode: Literal["thermometer", "per_feature"]
+    n_ltt_features_total: int = Field(ge=1)
+    features: tuple[FeatureSpecU, ...]
+
+    @model_validator(mode="after")
+    def _check_version_mode(self) -> "BinarizationSpec":
+        if (self.version, self.mode) not in {(1, "thermometer"), (2, "per_feature")}:
+            raise ValueError(
+                f"version {self.version} and mode {self.mode!r} are inconsistent: "
+                f"v1 ⟺ thermometer, v2 ⟺ per_feature"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_total(self) -> "BinarizationSpec":
+        summed = sum(f.num_bits for f in self.features)
+        if summed != self.n_ltt_features_total:
+            raise ValueError(
+                f"n_ltt_features_total ({self.n_ltt_features_total}) must equal "
+                f"Σ num_bits ({summed})"
+            )
+        return self
+
+    @classmethod
+    def from_dict(cls, spec: dict[str, Any]) -> "BinarizationSpec":
+        """Parse + validate a fetched BinarizationSpec JSON dict.
+
+        Raises:
+            ValueError: on unknown version/mode or inconsistent widths.
+        """
+        version = spec.get("version")
+        if version not in _SUPPORTED_VERSIONS:
+            raise ValueError(
+                f"unsupported BinarizationSpec version {version!r}; "
+                f"this SDK understands versions {sorted(_SUPPORTED_VERSIONS)}"
+            )
+        return cls.model_validate(spec)
+
+
+def _encode_feature(
+    value: float, feature: ContinuousFeatureSpec | ThresholdFeatureSpec
+) -> list[int]:
+    """Encode one value to ``feature.num_bits`` bits (§4 v1 or v2)."""
+    if isinstance(feature, ContinuousFeatureSpec):
+        frac = (value - feature.min) / (feature.max - feature.min)
+        ones = int(np.floor(frac * feature.num_bits))
+        ones = max(0, min(feature.num_bits, ones))
+        return [1] * ones + [0] * (feature.num_bits - ones)
+    # ThresholdFeatureSpec — replicate TabularEncoder's exact float64 path:
+    # StandardScaler.transform then per-threshold >=.
+    x_s = (np.float64(value) - feature.mean) / feature.scale
+    return [1 if x_s >= t else 0 for t in feature.thresholds]
+
+
+def encode_row(row: dict[str, float], spec: BinarizationSpec) -> np.ndarray:
+    """Encode one input row to the flat ``uint8`` bit vector for §3 packing.
+
+    Args:
+        row: Feature name → raw numeric value. Must contain every feature
+            named in ``spec`` (extra keys are ignored).
+        spec: Validated §4 spec.
+
+    Returns:
+        1-D ``uint8`` array of length ``spec.n_ltt_features_total``, ready
+        to hand to ``helut.client.ClientContext.encrypt_input_bits``.
+
+    Raises:
+        KeyError: if ``row`` is missing a feature declared in ``spec``.
+    """
+    bits: list[int] = []
+    for feature in spec.features:
+        if feature.name not in row:
+            raise KeyError(f"input row missing feature {feature.name!r}")
+        bits.extend(_encode_feature(float(row[feature.name]), feature))
+    return np.asarray(bits, dtype=np.uint8)

implicant/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Implicant CLI (Typer)."""
+
+from .main import app
+
+__all__ = ["app"]

implicant/cli/main.py

@@ -0,0 +1,133 @@
+"""Implicant command-line interface.
+
+Crypto params live in each model's manifest, so the CLI no longer takes
+``--n`` / ``--num-layers``: keys are derived from the server's
+``circuit_meta.json`` at predict time. Commands:
+
+    implicant init [--api-url URL]      configure the client
+    implicant status                    show config + cached public keys
+    implicant predict -m MODEL -i FILE  run an encrypted prediction
+    implicant keys list                 list cached public-key bundles
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ..client import ImplicantClient
+from ..config import ImplicantConfig
+from ..transport import HttpxTransport
+
+app = typer.Typer(
+    name="implicant",
+    help="Client SDK for the Implicant FHE inference platform.",
+    no_args_is_help=True,
+)
+keys_app = typer.Typer(help="Inspect cached public-key bundles.")
+app.add_typer(keys_app, name="keys")
+
+
+def _make_client(config: ImplicantConfig) -> ImplicantClient:
+    api_key = os.environ.get("IMPLICANT_API_KEY", "")
+    transport = HttpxTransport(base_url=config.api_url, api_key=api_key)
+    return ImplicantClient(transport=transport, key_cache_dir=config.key_cache_dir)
+
+
+@app.command()
+def init(
+    api_url: Annotated[
+        str | None, typer.Option(help="Override the configured API URL.")
+    ] = None,
+) -> None:
+    """Write the local configuration to ``~/.implicant/config.toml``."""
+    config = ImplicantConfig.load()
+    if api_url:
+        config = config.model_copy(update={"api_url": api_url})
+    path = config.save()
+    typer.echo(f"Wrote config to {path}")
+    typer.echo(f"  api_url       = {config.api_url}")
+    typer.echo(f"  key_cache_dir = {config.key_cache_dir}")
+
+
+@app.command()
+def status() -> None:
+    """Show the active configuration and cached public-key bundles."""
+    config = ImplicantConfig.load()
+    typer.echo(f"api_url:       {config.api_url}")
+    typer.echo(f"key_cache_dir: {config.key_cache_dir}")
+
+    cache_dir = Path(config.key_cache_dir)
+    bundles = sorted(p.name for p in cache_dir.glob("*") if p.is_dir()) if cache_dir.is_dir() else []
+    if not bundles:
+        typer.echo("No cached public-key bundles.")
+        return
+    typer.echo("Cached public-key bundles:")
+    for key_id in bundles:
+        typer.echo(f"  - {key_id}")
+
+
+@app.command()
+def predict(
+    model: Annotated[str, typer.Option("--model", "-m", help="Model id.")],
+    input: Annotated[
+        Path,
+        typer.Option(
+            "--input", "-i", exists=True, dir_okay=False, readable=True,
+            help="JSON object or single-row CSV of feature values.",
+        ),
+    ],
+) -> None:
+    """Run an encrypted prediction against a model on the platform."""
+    config = ImplicantConfig.load()
+    row = _load_row(input)
+    client = _make_client(config)
+    result = client.predict(model, row)
+    typer.echo(
+        json.dumps(
+            {
+                "key_id": result.key_id,
+                "label_index": result.prediction.label_index,
+                "label": result.prediction.label,
+                "scores": list(result.prediction.scores),
+            },
+            indent=2,
+        )
+    )
+
+
+@keys_app.command("list")
+def keys_list() -> None:
+    """List cached public-key bundles by key_id."""
+    config = ImplicantConfig.load()
+    cache_dir = Path(config.key_cache_dir)
+    if not cache_dir.is_dir():
+        return
+    for path in sorted(cache_dir.glob("*")):
+        if path.is_dir():
+            typer.echo(path.name)
+
+
+def _load_row(path: Path) -> dict[str, float]:
+    text = path.read_text()
+    if path.suffix.lower() == ".json":
+        raw = json.loads(text)
+    elif path.suffix.lower() == ".csv":
+        rows = list(csv.DictReader(text.splitlines()))
+        if len(rows) != 1:
+            raise typer.BadParameter(
+                f"CSV input must contain exactly one data row, got {len(rows)}"
+            )
+        raw = rows[0]
+    else:
+        raise typer.BadParameter(f"Unsupported input format: {path.suffix}")
+    return {k: float(v) for k, v in raw.items()}
+
+
+if __name__ == "__main__":
+    app()

implicant/client.py

@@ -0,0 +1,212 @@
+"""ImplicantClient — the end-to-end client workflow facade.
+
+One ``predict`` call walks the whole §-contract pipeline:
+
+    fetch circuit_meta (§5.1)  →  validate + rehydrate Params (§1)
+        →  ensure key session (keygen if needed) + register public blobs (§2)
+        →  fetch + apply BinarizationSpec (§4)   →  flat bit vector
+        →  encrypt → §3 request envelope         →  transport.predict
+        →  §3 response envelope → decrypt slots   →  argmax (§6 head, server-side)
+
+Key sessions (secret-key holders) are created lazily per ``key_id`` and kept
+in memory for the process lifetime; the on-disk cache only records which
+public blobs were already uploaded so re-registration can be skipped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from helut.client import decode_class_scores
+
+from .binarize import BinarizationSpec, encode_row
+from .envelope import pack_envelope, unpack_envelope
+from .keys import KeySession, PublicKeyCache
+from .manifest import CircuitMeta
+from .postprocess import ClassPrediction, predict_label
+from .transport import Transport
+
+__all__ = ["ImplicantClient", "PredictResult", "PreparedModel"]
+
+
+@dataclass(frozen=True, slots=True)
+class PredictResult:
+    """Outcome of one encrypted prediction."""
+
+    prediction: ClassPrediction
+    key_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedModel:
+    """A model fetched and key-warmed, ready for repeated predictions.
+
+    Produced by :meth:`ImplicantClient.prepare`. ``feature_names`` is the
+    ordered list of input fields the caller should collect (e.g. to render a
+    form); the session for ``key_id`` is already generated and registered.
+    """
+
+    model_id: str
+    meta: CircuitMeta
+    spec: BinarizationSpec
+    key_id: str
+    feature_names: tuple[str, ...]
+
+
+class ImplicantClient:
+    """Orchestrates the encrypted-inference workflow over a Transport."""
+
+    def __init__(self, transport: Transport, key_cache_dir: str | Path) -> None:
+        self._transport = transport
+        self._cache = PublicKeyCache(Path(key_cache_dir))
+        self._sessions: dict[str, KeySession] = {}
+
+    def predict(
+        self,
+        model_id: str,
+        row: dict[str, float],
+        class_names: tuple[str, ...] | None = None,
+        *,
+        on_stage: Callable[[str], None] | None = None,
+    ) -> PredictResult:
+        """Run an encrypted prediction for one input ``row``.
+
+        Convenience wrapper: prepares the model (fetch + keygen) then runs one
+        prediction. Identical in behavior to the prior implementation.
+        """
+        prepared = self.prepare(model_id, on_stage=on_stage)
+        return self.predict_prepared(
+            prepared, row, class_names=class_names, on_stage=on_stage
+        )
+
+    def prepare(
+        self,
+        model_id: str,
+        *,
+        on_stage: Callable[[str], None] | None = None,
+    ) -> PreparedModel:
+        """Fetch a model's settings + spec and warm its key session.
+
+        Runs keygen + public-key registration (once per ``key_id`` per process).
+        Emits the stage tokens ``"fetching"`` then ``"keygen"`` through
+        ``on_stage`` if provided. Returns a :class:`PreparedModel` the caller
+        reuses for :meth:`predict_prepared`.
+        """
+        notify = on_stage or (lambda _s: None)
+        notify("fetching")
+        meta = CircuitMeta.from_dict(self._transport.fetch_circuit_meta(model_id))
+        spec = BinarizationSpec.from_dict(
+            self._transport.fetch_binarization_spec(meta.binarization_spec_uri)
+        )
+        notify("keygen")
+        session = self._ensure_session(meta)
+        feature_names = tuple(f.name for f in spec.features)
+        return PreparedModel(
+            model_id=model_id,
+            meta=meta,
+            spec=spec,
+            key_id=session.key_id,
+            feature_names=feature_names,
+        )
+
+    def predict_prepared(
+        self,
+        prepared: PreparedModel,
+        row: dict[str, float],
+        class_names: tuple[str, ...] | None = None,
+        *,
+        on_stage: Callable[[str], None] | None = None,
+    ) -> PredictResult:
+        """Run one prediction against an already-:meth:`prepare`d model.
+
+        Emits ``"encrypting"`` → ``"computing"`` → ``"reading"`` through
+        ``on_stage`` if provided.
+        """
+        session = self._get_session(prepared.key_id)
+        bits = encode_row(row, prepared.spec)
+        if bits.shape != (prepared.meta.input_bits,):
+            raise ValueError(
+                f"encoded bit vector has {bits.shape[0]} bits, manifest "
+                f"declares input_bits={prepared.meta.input_bits}"
+            )
+        return self._predict_bits(
+            prepared.model_id, prepared.meta, session, bits, class_names,
+            on_stage=on_stage,
+        )
+
+    def _predict_bits(
+        self,
+        model_id: str,
+        meta: CircuitMeta,
+        session: KeySession,
+        bits: np.ndarray,
+        class_names: tuple[str, ...] | None,
+        *,
+        on_stage: Callable[[str], None] | None = None,
+    ) -> PredictResult:
+        """Run the encrypt → evaluate → decrypt → decode path from a flat bit
+        vector. Shared by :meth:`predict_prepared` (after binarization) and the
+        gold ``X_bits`` harness (which feeds pre-encoded bits directly).
+        """
+        notify = on_stage or (lambda _s: None)
+        notify("encrypting")
+        request = pack_envelope(session.encrypt_bits(bits))
+
+        notify("computing")
+        response = self._transport.predict(model_id, session.key_id, request)
+        notify("reading")
+        outputs = unpack_envelope(response.body)
+        if not outputs:
+            raise ValueError("server returned an empty output envelope")
+
+        if meta.variant == "B":
+            # Variant B (§3/§6): ONE output ct with class scores packed
+            # contiguously in slots [0, num_classes). The binding decrypts
+            # unsigned (§7, P14); decode_class_scores recovers the signed
+            # logits via balanced residue before threshold/argmax.
+            nc = meta.output_slot_count
+            unsigned = session.decrypt_slots(outputs[0], n=nc)
+            logits = [decode_class_scores(unsigned, nc, session.plain_modulus)]
+        else:  # "A" — raw LUT bits, one ct per tower; out of SDK Phase 2 scope.
+            raise NotImplementedError(
+                "Variant A (raw LUT-bit output) decode is not implemented in "
+                "the SDK; Phase 2 tabular models use Variant B (server FHE head)."
+            )
+        prediction = predict_label(logits, class_names=class_names)
+        return PredictResult(prediction=prediction, key_id=session.key_id)
+
+    def _get_session(self, key_id: str) -> KeySession:
+        """Return the already-warmed session for ``key_id``.
+
+        A pure in-memory lookup with no transport round trip — used by
+        :meth:`predict_prepared`, which relies on :meth:`prepare` having warmed
+        and registered the session first. Raises if it was never prepared.
+        """
+        session = self._sessions.get(key_id)
+        if session is None:
+            raise RuntimeError(
+                f"no prepared session for key_id {key_id!r}; call prepare() first"
+            )
+        return session
+
+    def _ensure_session(self, meta: CircuitMeta) -> KeySession:
+        """Get-or-create the secret-key session for this manifest's params.
+
+        Keygen runs once per ``key_id`` per process. Public blobs are
+        registered with the server (and cached on disk) the first time we
+        produce them; a cache hit + server-side presence lets us skip the
+        ~35 MB upload.
+        """
+        key_id = meta.required_key_id
+        session = self._sessions.get(key_id)
+        if session is None:
+            session = KeySession.generate(meta.params)
+            self._sessions[key_id] = session
+
+        if not self._transport.has_keys(key_id):
+            self._transport.register_keys(key_id, session.public_bundle)
+            self._cache.write(key_id, session.public_bundle)
+        return session