implicant 0.2.0__py3-none-any.whl

implicant/__init__.py

@@ -0,0 +1,34 @@
+"""Implicant SDK — privacy-preserving ML inference client.
+
+Encrypts a single input row locally under BGV, ships the ciphertext to the
+Implicant platform for homomorphic evaluation, then decrypts and argmaxes
+the returned class-score ciphertexts. The secret key never leaves the
+process; only the three public-key blobs (§2) and ciphertexts (§3) cross
+the wire.
+
+The FHE primitives are not implemented here — they come from the
+`implicant-fhe` package (`helut.client`). This SDK owns the *client
+workflow*: binarization (§4), the §3 ciphertext envelope, key lifecycle /
+caching, transport, and argmax post-processing.
+
+Contract reference: ``platform/docs/FHE_INTERFACE_SPEC.md``.
+"""
+
+from __future__ import annotations
+
+from .binarize import BinarizationSpec, encode_row
+from .client import ImplicantClient, PredictResult
+from .config import ImplicantConfig
+from .manifest import CircuitMeta
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ImplicantClient",
+    "PredictResult",
+    "ImplicantConfig",
+    "CircuitMeta",
+    "BinarizationSpec",
+    "encode_row",
+    "__version__",
+]

implicant/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m implicant` launches the desktop application."""
+from implicant.app.__main__ import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

implicant/app/__init__.py

@@ -0,0 +1,8 @@
+"""Desktop application for the Implicant FHE inference client.
+
+A native PySide6 GUI that embeds the `implicant` SDK so a non-technical user can
+run encrypted inference locally. The secret key stays inside this process.
+
+Pure (GUI-free) modules: `preflight`, `credentials`, `catalog`, `messages`.
+PySide6 modules: `worker`, `wizard`, `main_window`, `__main__`.
+"""

implicant/app/__main__.py

@@ -0,0 +1,61 @@
+"""Desktop app entry point: preflight gate -> onboarding -> main window.
+
+The native engine + SDK are imported lazily inside ``main`` (not at module
+import) so this module — and ``choose_startup`` — stay importable and testable
+without the engine present.
+"""
+from __future__ import annotations
+
+import sys
+
+from PySide6.QtWidgets import QApplication
+
+from .credentials import has_api_key
+from .main_window import MainWindow
+from .preflight import PreflightResult, run_preflight
+from .wizard import OnboardingWizard, show_unsupported
+
+__all__ = ["main", "choose_startup"]
+
+
+def choose_startup(result: PreflightResult, has_key: bool) -> str:
+    """Pure routing decision: 'unsupported' | 'onboard' | 'main'."""
+    if not result.supported:
+        return "unsupported"
+    if not has_key:
+        return "onboard"
+    return "main"
+
+
+def _build_client():
+    from implicant.client import ImplicantClient
+    from implicant.config import ImplicantConfig
+    from implicant.transport import HttpxTransport
+
+    from .credentials import load_api_key
+
+    config = ImplicantConfig.load()
+    transport = HttpxTransport(base_url=config.api_url, api_key=load_api_key() or "")
+    return ImplicantClient(transport=transport, key_cache_dir=config.key_cache_dir)
+
+
+def main() -> int:
+    app = QApplication(sys.argv)
+    result = run_preflight()
+    decision = choose_startup(result, has_api_key())
+
+    if decision == "unsupported":
+        show_unsupported(result)
+        return 0
+    if decision == "onboard":
+        wizard = OnboardingWizard()
+        if not wizard.exec():  # 0 == closed/rejected; non-zero == accepted
+            return 0
+
+    window = MainWindow(_build_client(), low_memory=result.low_memory)
+    window.show()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

implicant/app/catalog.py

@@ -0,0 +1,32 @@
+"""Bundled catalogue of models the app offers.
+
+The wire manifest has no display metadata and the 5-operation transport has no
+list-models call, so this presentation data ships with the app. ``model_id``
+values match the platform's model slugs. ``class_labels`` carry the two
+human-readable outcomes (the wire manifest does not).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["CatalogEntry", "CATALOG", "by_model_id"]
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogEntry:
+    model_id: str
+    display_name: str
+    class_labels: tuple[str, str]
+
+
+CATALOG: tuple[CatalogEntry, ...] = (
+    CatalogEntry("cancer", "Breast cancer screening", ("benign", "malignant")),
+    CatalogEntry("diabetes", "Diabetes risk", ("no diabetes", "diabetes")),
+)
+
+
+def by_model_id(model_id: str) -> CatalogEntry | None:
+    for entry in CATALOG:
+        if entry.model_id == model_id:
+            return entry
+    return None

implicant/app/credentials.py

@@ -0,0 +1,40 @@
+"""Access-key storage in the OS keychain — never plaintext on disk.
+
+A thin, mockable wrapper over ``keyring`` so the rest of the app (and tests)
+depend on a small surface. The access key is the user's platform login
+credential; it is NOT cryptographic key material.
+"""
+from __future__ import annotations
+
+import keyring
+
+__all__ = [
+    "SERVICE_NAME",
+    "USERNAME",
+    "save_api_key",
+    "load_api_key",
+    "has_api_key",
+    "delete_api_key",
+]
+
+SERVICE_NAME = "implicant"
+USERNAME = "api_key"
+
+
+def save_api_key(key: str) -> None:
+    keyring.set_password(SERVICE_NAME, USERNAME, key)
+
+
+def load_api_key() -> str | None:
+    return keyring.get_password(SERVICE_NAME, USERNAME)
+
+
+def has_api_key() -> bool:
+    return bool(load_api_key())
+
+
+def delete_api_key() -> None:
+    try:
+        keyring.delete_password(SERVICE_NAME, USERNAME)
+    except keyring.errors.PasswordDeleteError:
+        pass

implicant/app/main_window.py

@@ -0,0 +1,258 @@
+"""Main application window: pick a model, fill the form, get a private result.
+
+The window never calls the engine directly: model selection and prediction run
+as worker tasks (Task 6). ``run_task`` is injectable so tests can run tasks
+synchronously. A 'generation' counter ignores results from abandoned tasks.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRunnable, QThreadPool
+from PySide6.QtWidgets import (
+    QApplication,
+    QComboBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QMenu,
+    QPushButton,
+    QStyle,
+    QSystemTrayIcon,
+    QVBoxLayout,
+    QWidget,
+)
+
+from . import catalog, messages
+from .wizard import OnboardingWizard
+from .worker import PredictTask, PrepareTask
+
+if TYPE_CHECKING:
+    from implicant.client import ImplicantClient
+
+__all__ = ["MainWindow"]
+
+
+class MainWindow(QWidget):
+    def __init__(
+        self,
+        client: "ImplicantClient",
+        *,
+        run_task: Callable[[QRunnable], None] | None = None,
+        low_memory: bool = False,
+    ) -> None:
+        super().__init__()
+        self._client = client
+        self._run_task = run_task or QThreadPool.globalInstance().start
+        self._prepared = None
+        self._generation = 0
+        self._task = None
+        self.fields: dict[str, QLineEdit] = {}
+
+        self.setWindowTitle(messages.APP_TITLE)
+        self._build_ui(low_memory)
+        self._setup_tray()
+        if self.model_combo.count():
+            self.select_model_index(self.model_combo.currentIndex())
+
+    # ----- UI construction -------------------------------------------------
+
+    def _build_ui(self, low_memory: bool) -> None:
+        layout = QVBoxLayout(self)
+
+        if low_memory:
+            note = QLabel(messages.LOW_MEMORY_NOTE)
+            note.setWordWrap(True)
+            layout.addWidget(note)
+
+        layout.addWidget(QLabel(messages.CHOOSE_MODEL_LABEL))
+        self.model_combo = QComboBox()
+        for entry in catalog.CATALOG:
+            self.model_combo.addItem(entry.display_name, entry.model_id)
+        layout.addWidget(self.model_combo)
+
+        self._form_box = QGroupBox(messages.FORM_GROUP_TITLE)
+        self._form_layout = QFormLayout(self._form_box)
+        layout.addWidget(self._form_box)
+
+        self.predict_button = QPushButton(messages.PREDICT_BUTTON)
+        self.predict_button.setEnabled(False)
+        self.predict_button.clicked.connect(self.on_predict_clicked)
+        self.cancel_button = QPushButton(messages.CANCEL_BUTTON)
+        self.cancel_button.setEnabled(False)
+        self.cancel_button.clicked.connect(self.on_cancel_clicked)
+        btn_row = QHBoxLayout()
+        btn_row.addWidget(self.predict_button)
+        btn_row.addWidget(self.cancel_button)
+        layout.addLayout(btn_row)
+
+        self.status_label = QLabel("")
+        self.status_label.setWordWrap(True)
+        layout.addWidget(self.status_label)
+        self.result_label = QLabel("")
+        self.result_label.setWordWrap(True)
+        layout.addWidget(self.result_label)
+
+        trust_box = QGroupBox(messages.PRIVACY_GROUP_TITLE)
+        trust_layout = QVBoxLayout(trust_box)
+        for line in messages.TRUST_SUMMARY:
+            lbl = QLabel("• " + line)
+            lbl.setWordWrap(True)
+            trust_layout.addWidget(lbl)
+        self.details_button = QPushButton(messages.DETAILS_BUTTON)
+        self.details_button.setCheckable(True)
+        self.details_button.toggled.connect(self.toggle_details)
+        trust_layout.addWidget(self.details_button)
+        self.details_label = QLabel(messages.TRUST_DETAILS)
+        self.details_label.setWordWrap(True)
+        self.details_label.setVisible(False)
+        trust_layout.addWidget(self.details_label)
+        layout.addWidget(trust_box)
+
+        self.settings_button = QPushButton(messages.SETTINGS_BUTTON)
+        self.settings_button.clicked.connect(self.on_settings_clicked)
+        layout.addWidget(self.settings_button)
+
+        # Connect AFTER populating the combo so the initial addItem does not
+        # fire into a half-built UI; the initial selection is driven explicitly.
+        self.model_combo.currentIndexChanged.connect(self.select_model_index)
+
+    def _setup_tray(self) -> None:
+        self._tray = None
+        if not QSystemTrayIcon.isSystemTrayAvailable():
+            return
+        icon = self.style().standardIcon(QStyle.StandardPixmap.SP_ComputerIcon)
+        self._tray = QSystemTrayIcon(icon, self)
+        menu = QMenu()
+        menu.addAction(messages.TRAY_OPEN).triggered.connect(self.showNormal)
+        menu.addAction(messages.TRAY_QUIT).triggered.connect(QApplication.quit)
+        self._tray.setContextMenu(menu)
+        self._tray.show()
+
+    # ----- behavior --------------------------------------------------------
+
+    def closeEvent(self, event) -> None:
+        if self._tray is not None:
+            event.ignore()
+            self.hide()
+        else:
+            event.accept()
+
+    def toggle_details(self, checked: bool) -> None:
+        self.details_label.setVisible(checked)
+
+    def _next_generation(self) -> int:
+        self._generation += 1
+        return self._generation
+
+    def select_model_index(self, index: int) -> None:
+        if index < 0 or index >= len(catalog.CATALOG):
+            return
+        self._prepared = None
+        self.predict_button.setEnabled(False)
+        self.result_label.setText("")
+        self._clear_form()
+        entry = catalog.CATALOG[index]
+        gen = self._next_generation()
+        self.status_label.setText(messages.STAGE_LABELS["fetching"])
+        task = PrepareTask(self._client, entry.model_id)
+        task.signals.stage.connect(lambda s, g=gen: self._on_stage(s, g))
+        task.signals.prepared.connect(lambda p, g=gen: self._on_prepared(p, g))
+        task.signals.failed.connect(lambda e, g=gen: self._on_failed(e, g))
+        self._task = task
+        self.cancel_button.setEnabled(True)
+        self._run_task(task)
+
+    def on_predict_clicked(self) -> None:
+        if self._prepared is None:
+            return
+        try:
+            row = self._gather_row()
+        except (KeyError, ValueError) as exc:
+            self.result_label.setText("")
+            self.status_label.setText(messages.friendly_error(exc))
+            return
+        entry = catalog.CATALOG[self.model_combo.currentIndex()]
+        gen = self._next_generation()
+        self.predict_button.setEnabled(False)
+        self.cancel_button.setEnabled(True)
+        self.result_label.setText("")
+        task = PredictTask(self._client, self._prepared, row, entry.class_labels)
+        task.signals.stage.connect(lambda s, g=gen: self._on_stage(s, g))
+        task.signals.finished.connect(lambda r, g=gen: self._on_finished(r, g))
+        task.signals.failed.connect(lambda e, g=gen: self._on_failed(e, g))
+        self._task = task
+        self._run_task(task)
+
+    def on_cancel_clicked(self) -> None:
+        self._next_generation()  # abandon any in-flight results
+        self.cancel_button.setEnabled(False)
+        self.predict_button.setEnabled(self._prepared is not None)
+        # If cancelled mid-setup there is no prepared model and Predict stays
+        # disabled; guide the user back to the model list instead of leaving a
+        # blank, dead-end window.
+        if self._prepared is None:
+            self.status_label.setText(messages.SELECT_MODEL_HINT)
+        else:
+            self.status_label.setText("")
+
+    def on_settings_clicked(self) -> None:
+        wizard = OnboardingWizard()
+        if wizard.exec():  # accepted: a new access key was saved
+            self.status_label.setText(messages.SETTINGS_SAVED_NOTE)
+
+    def _gather_row(self) -> dict[str, float]:
+        row: dict[str, float] = {}
+        for name, field in self.fields.items():
+            text = field.text().strip()
+            if not text:
+                raise KeyError(name)
+            row[name] = float(text)
+        return row
+
+    def _clear_form(self) -> None:
+        while self._form_layout.rowCount():
+            self._form_layout.removeRow(0)
+        self.fields = {}
+
+    def _build_form(self, feature_names: tuple[str, ...]) -> None:
+        self._clear_form()
+        for name in feature_names:
+            field = QLineEdit()
+            self.fields[name] = field
+            self._form_layout.addRow(name, field)
+
+    # ----- signal slots (guarded by generation) ----------------------------
+
+    def _on_stage(self, token: str, gen: int) -> None:
+        if gen != self._generation:
+            return
+        self.status_label.setText(messages.STAGE_LABELS.get(token, ""))
+
+    def _on_prepared(self, prepared, gen: int) -> None:
+        if gen != self._generation:
+            return
+        self._prepared = prepared
+        self._build_form(prepared.feature_names)
+        self.predict_button.setEnabled(True)
+        self.cancel_button.setEnabled(False)
+        self.status_label.setText("")
+
+    def _on_finished(self, result, gen: int) -> None:
+        if gen != self._generation:
+            return
+        self.predict_button.setEnabled(True)
+        self.cancel_button.setEnabled(False)
+        self.status_label.setText("")
+        label = result.prediction.label or str(result.prediction.label_index)
+        self.result_label.setText(messages.result_text(label))
+
+    def _on_failed(self, exc, gen: int) -> None:
+        if gen != self._generation:
+            return
+        self.predict_button.setEnabled(self._prepared is not None)
+        self.cancel_button.setEnabled(False)
+        self.status_label.setText(messages.friendly_error(exc))

implicant/app/messages.py

@@ -0,0 +1,145 @@
+"""The ONLY place user-facing copy lives.
+
+By policy no cryptographic vocabulary appears in any string here (enforced by
+tests/test_app_messages.py). We talk about protecting data on this computer and
+your private protection — never keys, encryption, ciphertext, bits, or argmax.
+"""
+from __future__ import annotations
+
+import httpx
+
+from implicant.transport.errors import KeyDepthInsufficientError, TransportError
+
+__all__ = [
+    "STAGE_LABELS",
+    "TRUST_SUMMARY",
+    "TRUST_DETAILS",
+    "UNSUPPORTED_TEXT",
+    "LOW_MEMORY_NOTE",
+    "SETTINGS_SAVED_NOTE",
+    "SELECT_MODEL_HINT",
+    "APP_TITLE",
+    "WIZARD_TITLE",
+    "WIZARD_WELCOME",
+    "ACCESS_KEY_PLACEHOLDER",
+    "ACCESS_KEY_REQUIRED",
+    "SAVE_AND_CONTINUE",
+    "CHOOSE_MODEL_LABEL",
+    "FORM_GROUP_TITLE",
+    "PREDICT_BUTTON",
+    "CANCEL_BUTTON",
+    "PRIVACY_GROUP_TITLE",
+    "DETAILS_BUTTON",
+    "SETTINGS_BUTTON",
+    "TRAY_OPEN",
+    "TRAY_QUIT",
+    "result_text",
+    "detected_platform_text",
+    "friendly_error",
+]
+
+# Internal stage token -> plain-language status line.
+STAGE_LABELS: dict[str, str] = {
+    "fetching": "Getting the model ready…",
+    "keygen": "Setting up privacy on this computer (one time)…",
+    "encrypting": "Protecting your data on this computer…",
+    "computing": "The service is working on your protected data…",
+    "reading": "Preparing your result…",
+}
+
+TRUST_SUMMARY: tuple[str, ...] = (
+    "Your data is protected on this computer.",
+    "Nothing readable about your data ever leaves this computer.",
+    "Your private protection stays on this computer and is never saved.",
+)
+
+TRUST_DETAILS: str = (
+    "When you ask for a result, the app first protects your information on "
+    "this computer. Only the protected, unreadable form is sent to the "
+    "service — your original values never leave. The service works out a "
+    "result from the protected data without ever seeing what it contains, and "
+    "the result is opened again only here on your computer. The private "
+    "protection used to open results stays in this computer's memory while the "
+    "app is open and is never written to disk."
+)
+
+UNSUPPORTED_TEXT: str = (
+    "Implicant can't run on this computer yet. It currently works on "
+    "newer Apple-chip Macs and on Linux computers with an Intel or AMD chip."
+)
+
+LOW_MEMORY_NOTE: str = (
+    "This computer has limited memory, so getting ready may take a little "
+    "longer. You can keep using the app while it prepares."
+)
+
+SETTINGS_SAVED_NOTE: str = (
+    "Your access key was saved. Please reopen the app for it to take effect."
+)
+
+SELECT_MODEL_HINT: str = (
+    "Setup was stopped. Choose a model from the list to try again."
+)
+
+# --- Window chrome and widget labels -----------------------------------------
+# Every string a widget displays lives here too (not just status/trust copy), so
+# the no-jargon policy test in tests/test_app_messages.py covers all of them.
+APP_TITLE: str = "Implicant"
+
+WIZARD_TITLE: str = "Welcome to Implicant"
+WIZARD_WELCOME: str = (
+    "Welcome. To get started, paste the access key your administrator gave you."
+)
+ACCESS_KEY_PLACEHOLDER: str = "Access key"
+ACCESS_KEY_REQUIRED: str = "Please paste your access key to continue."
+SAVE_AND_CONTINUE: str = "Save and continue"
+
+CHOOSE_MODEL_LABEL: str = "Choose a model:"
+FORM_GROUP_TITLE: str = "Your information"
+PREDICT_BUTTON: str = "Predict privately"
+CANCEL_BUTTON: str = "Cancel"
+PRIVACY_GROUP_TITLE: str = "Your privacy"
+DETAILS_BUTTON: str = "Details"
+SETTINGS_BUTTON: str = "Change access key…"
+TRAY_OPEN: str = "Open"
+TRAY_QUIT: str = "Quit"
+
+
+def detected_platform_text(os_name: str, arch: str) -> str:
+    """Informative line shown under the unsupported-computer message."""
+    return f"Detected: {os_name} / {arch}."
+
+
+def result_text(label: str) -> str:
+    """The line shown for a finished prediction."""
+    return f"Result: {label}"
+
+
+def friendly_error(exc: Exception) -> str:
+    """Map any exception to a plain-language message (no codes, no jargon)."""
+    if isinstance(exc, KeyDepthInsufficientError):
+        return (
+            "This model needs a stronger privacy setup than the one prepared "
+            "on this computer. Please contact your administrator."
+        )
+    if isinstance(exc, TransportError):
+        if exc.status_code in (401, 403):
+            return "Your access key was not accepted. Please check it in Settings."
+        if exc.status_code == 404:
+            return "This model isn't available on the service right now."
+        if exc.status_code == 429:
+            return "You've reached your usage limit. Please try again later."
+        return (
+            "Couldn't reach the service. Please check your connection and "
+            "try again."
+        )
+    if isinstance(exc, httpx.HTTPError):
+        return (
+            "Couldn't reach the service. Please check your connection and "
+            "try again."
+        )
+    if isinstance(exc, KeyError):
+        return "Please fill in every field before asking for a result."
+    if isinstance(exc, ValueError):
+        return "Please enter a valid number in every field."
+    return "Something went wrong. Please try again."

implicant/app/preflight.py

@@ -0,0 +1,73 @@
+"""Hardware/environment preflight for the desktop app.
+
+Answers one question: can THIS computer run local private inference? The hard
+gate is whether the native engine (``helut.client``) imports. We also report
+OS/arch (for the friendly 'not supported' message) and total memory (to warn,
+never block, on small machines). The result is UI-agnostic; the GUI turns it
+into plain-language screens.
+"""
+from __future__ import annotations
+
+import os
+import platform
+from dataclasses import dataclass
+
+__all__ = ["PreflightResult", "evaluate", "run_preflight", "LOW_MEMORY_GB"]
+
+# Keygen at the larger rings is memory-hungry; below this we WARN (do not block).
+LOW_MEMORY_GB = 4.0
+
+
+@dataclass(frozen=True, slots=True)
+class PreflightResult:
+    engine_available: bool      # could we import the native crypto engine?
+    os_name: str                # platform.system(): "Darwin" | "Linux" | "Windows"
+    arch: str                   # platform.machine(): "arm64" | "x86_64" | ...
+    total_memory_gb: float      # best-effort; 0.0 if undetectable
+    supported: bool             # == engine_available (the hard gate)
+    low_memory: bool            # supported AND 0 < total_memory_gb < LOW_MEMORY_GB
+
+
+def evaluate(
+    *,
+    engine_available: bool,
+    os_name: str,
+    arch: str,
+    total_memory_gb: float,
+) -> PreflightResult:
+    """Pure decision function (unit-tested). No I/O."""
+    return PreflightResult(
+        engine_available=engine_available,
+        os_name=os_name,
+        arch=arch,
+        total_memory_gb=total_memory_gb,
+        supported=engine_available,
+        low_memory=engine_available and 0.0 < total_memory_gb < LOW_MEMORY_GB,
+    )
+
+
+def _engine_available() -> bool:
+    try:
+        import helut.client  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def _total_memory_gb() -> float:
+    try:
+        pages = os.sysconf("SC_PHYS_PAGES")
+        page_size = os.sysconf("SC_PAGE_SIZE")
+        return (pages * page_size) / (1024 ** 3)
+    except (ValueError, OSError, AttributeError):
+        return 0.0
+
+
+def run_preflight() -> PreflightResult:
+    """Probe the real machine and return a :class:`PreflightResult`."""
+    return evaluate(
+        engine_available=_engine_available(),
+        os_name=platform.system(),
+        arch=platform.machine(),
+        total_memory_gb=_total_memory_gb(),
+    )