implicant 0.2.0__tar.gz → 0.6.0__tar.gz

implicant-0.6.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,87 @@
+name: publish to PyPI
+
+# Mirrors implicant-fhe's publish workflow. Publishing is deliberately a
+# separate, manual act — this never fires on a tag push. A PyPI upload is
+# irreversible (the version number is burned even if the files are deleted),
+# so building/tagging (`release.yml`) and publishing are kept apart.
+#
+# The gate is the dispatch itself rather than a protected environment: this org
+# is on GitHub Free, where required-reviewers protection is a paid feature, and
+# an unprotected `environment:` block would look like a gate while enforcing
+# nothing.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag whose artifacts to publish (e.g. v0.5.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: publish ${{ inputs.tag }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # read the release assets
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Download artifacts from the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          version="${{ inputs.tag }}"
+          version="${version#v}"
+          # Pinned to the exact tag version: a release still carrying assets
+          # from an earlier build cannot be published by accident.
+          gh release download "${{ inputs.tag }}" \
+            --repo "${{ github.repository }}" \
+            --pattern "implicant-${version}*" \
+            --dir dist
+          ls -l dist/
+
+      - name: Refuse to publish artifacts that disagree with the tag
+        run: |
+          set -euo pipefail
+          version="${{ inputs.tag }}"
+          version="${version#v}"
+
+          count="$(find dist -type f \( -name '*.whl' -o -name '*.tar.gz' \) | wc -l)"
+          if [ "$count" -eq 0 ]; then
+            echo "::error::no artifacts attached to ${{ inputs.tag }}"
+            exit 1
+          fi
+
+          mismatched="$(find dist -type f ! -name "implicant-${version}-*.whl" \
+                                          ! -name "implicant-${version}.tar.gz")"
+          if [ -n "$mismatched" ]; then
+            echo "::error::artifacts do not match tag ${{ inputs.tag }}:"
+            echo "$mismatched"
+            exit 1
+          fi
+          echo "${count} artifact(s) staged for ${{ inputs.tag }}"
+
+      # The SDK is the client. It must never carry the evaluation engine's
+      # worker-only surface, nor a runtime requirement or index setting that
+      # would let a client resolve the private worker build. Same check the
+      # release build and the test suite run — repeated here because this is
+      # the last point before the upload becomes irreversible.
+      - name: Refuse to publish anything carrying the server surface
+        run: python scripts/check_no_server_surface.py dist
+
+      # No `password:` input — authentication is PyPI Trusted Publishing over
+      # OIDC, so there is no long-lived token stored in this repo. Configure the
+      # publisher once at
+      # https://pypi.org/manage/project/implicant/settings/publishing/
+      # with workflow name `publish-pypi.yml` and no environment.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

implicant-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: build release artifacts
+
+# Mirrors implicant-fhe's `wheels.yml`: a tag push builds the distribution and
+# cuts a GitHub release with the artifacts attached. It never publishes — that
+# is a separate, manually dispatched act (`publish-pypi.yml`), because a PyPI
+# upload is irreversible: the version number is burned even if the files are
+# later deleted.
+#
+# This package is pure Python (hatchling), so there is no build matrix: one
+# `py3-none-any` wheel plus an sdist, built once.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      # The SDK must never ship the evaluation engine's server surface. This is
+      # already asserted against the built wheel by
+      # `tests/test_no_server_surface.py`; repeat the check here so a release
+      # cannot be cut from a tree whose tests were skipped.
+      - name: Refuse to release anything carrying the server surface
+        run: python scripts/check_no_server_surface.py dist
+
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  release:
+    name: attach to release
+    needs: [build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

{implicant-0.2.0 → implicant-0.6.0}/.gitignore

@@ -45,3 +45,13 @@ CLAUDE.local.md
 
 # Staged implicant-fhe wheels (downloaded via `gh release download`, not committed)
 wheels/
+
+# Briefcase / build logs
+logs/
+
+# Demo handoff bundle (large public-key blobs sent to platform; not committed).
+# The .zip needs its own rule: the directory pattern above does not match it, so
+# it stayed untracked-but-committable (460 MB) and hatchling swept it into the
+# sdist (489 MB, past PyPI's 100 MB limit) until it was excluded explicitly.
+/demo_handoff/
+/demo_handoff.zip

implicant-0.6.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: implicant
+Version: 0.6.0
+Summary: Python client SDK for the Implicant FHE inference platform
+Author: Implicant
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: implicant-fhe<0.6,>=0.5
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.8
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Implicant SDK
+
+Python **client** for the Implicant FHE inference platform. Encrypts one row
+locally under BGV, sends the ciphertext to the platform for homomorphic
+evaluation, and decrypts the result. The server never sees plaintext; the
+secret key never leaves the process.
+
+The classifier head runs **server-side under FHE** (Variant B): the platform
+returns one ciphertext with the class scores packed contiguously, which the
+client decrypts (unsigned) and decodes with `decode_class_scores` before
+threshold/argmax. `W` / `b` never reach the client.
+
+Pure Python — all crypto comes from [`implicant-fhe`](https://github.com/implicant/implicant-fhe)
+(`helut.client`). Contracts: [`docs/architecture.md`](docs/architecture.md)
+and `platform/docs/FHE_INTERFACE_SPEC.md`.
+
+## Install
+
+```bash
+pip install implicant
+```
+
+Pulls `implicant-fhe` (the `helut` crypto wheel) from PyPI automatically. Wheels
+ship for **CPython 3.10–3.14** on **macOS-arm64** and **manylinux x86_64** only.
+On any other target — Windows, Linux aarch64, macOS x86_64 — there is no wheel
+and no source fallback, so pip stops with `No matching distribution found for
+implicant-fhe`.
+
+### Developers
+
+```bash
+python3.13 -m venv .venv313
+.venv313/bin/pip install -e ".[dev]"
+.venv313/bin/pytest tests/ -v      # 100 tests, ~3.5 min (real BGV keygen)
+```
+
+To pin an unreleased `implicant-fhe` build, stage its wheel in `./wheels/` and
+add `--find-links wheels/`; the published versions resolve from PyPI without it.
+
+## Running an inference (CLI)
+
+The `implicant` CLI is the client-side workflow: configure once, then run
+encrypted predictions. Everything stays local except the ciphertext and the
+public keys — the secret key never leaves your machine.
+
+### 1. Point the client at the platform
+
+```bash
+implicant init --api-url https://api.implicant.example
+```
+
+Writes `~/.implicant/config.toml`. Run `implicant status` to confirm the
+configured `api_url` and list any locally cached keys.
+
+### 2. Set your API token
+
+The bearer token is read from the environment, never stored on disk:
+
+```bash
+export IMPLICANT_API_KEY="imp_..."
+```
+
+### 3. Discover the available models
+
+The SDK ships a hand-maintained registry of the models servable on the
+platform (there is no server-side listing endpoint yet):
+
+```bash
+$ implicant models list
+cancer    Predicts whether a breast tumor is malignant or benign
+diabetes  Predicts whether a patient has diabetes
+```
+
+The listed slug is the `--model` value for `predict`.
+
+### 4. Prepare the input row
+
+One row of raw feature values, as a JSON object (or a single-row CSV). The keys
+are the feature names the model expects. Each known model ships a bundled
+example row — the fastest way to get a correct starting point:
+
+```bash
+implicant models sample diabetes --out row.json   # or no --out to print to stdout
+```
+
+```json
+{
+  "preg": 6,
+  "plas": 148,
+  "pres": 72,
+  "skin": 35,
+  "insu": 0,
+  "mass": 33.6,
+  "pedi": 0.627,
+  "age": 50
+}
+```
+
+Edit the values by hand to test different inputs, then feed the file to
+`predict`. (`--out` refuses to overwrite an existing file unless you pass
+`--force`.)
+
+### 5. Predict
+
+```bash
+implicant predict --model diabetes --input row.json
+```
+
+Or skip the file entirely and run on the bundled example row:
+
+```bash
+implicant predict --model diabetes --sample
+```
+
+This fetches the model manifest, generates (or reloads) your keys, uploads the
+**public** keys on first use, encrypts the row locally, sends the ciphertext,
+then decrypts and decodes the returned class scores. Progress streams to
+stderr (with a spinner on the current step in a terminal) and the decision
+lands on stdout:
+
+```
+✓ Fetching model configuration
+✓ Preparing encryption keys
+✓ Encrypting input data
+✓ Evaluating on the server (encrypted)
+✓ Decrypting server response
+Final decision: tested_negative
+```
+
+Add `--json` for the machine-readable result instead of the decision line
+(progress stays on stderr, so piping stdout to `jq` is safe):
+
+```json
+{
+  "key_id": "bgv-n32768-L4-a1b2c3d4e5f6",
+  "label_index": 0,
+  "label": "tested_negative",
+  "scores": [-6684]
+}
+```
+
+Add `--no-persist-key` to use an ephemeral secret key for a single run (nothing
+written to disk; keys are regenerated and re-uploaded next time).
+
+### Managing keys
+
+The first prediction for a `key_id` persists your secret key to
+`~/.implicant/keys/<key_id>/secret_key.bin` (mode `0600`) so later runs skip
+keygen. Inspect and clean up the local store:
+
+```bash
+implicant keys list            # list key_ids; flags which have a persisted SK
+implicant keys rm <key_id>     # delete one stored key (secret + public)
+implicant keys purge --yes     # delete all stored keys
+```
+
+## Use (Python)
+
+The same flow is available programmatically:
+
+```python
+from implicant import ImplicantClient, list_known_models, sample_row
+from implicant.transport import HttpxTransport
+
+for m in list_known_models():          # discover: (slug, description) pairs
+    print(m.slug, "—", m.name)
+
+row = sample_row("diabetes")           # fresh mutable copy of the bundled example
+row["age"] = 61                        # hand-tweak values for testing
+
+client = ImplicantClient(
+    HttpxTransport(base_url="https://api.implicant.example", api_key="imp_..."),
+    key_cache_dir="~/.implicant/keys",
+)
+result = client.predict("diabetes", row, class_names=("negative", "positive"))
+print(result.prediction.label)
+```
+
+## Demo mode
+
+Demo mode skips FHE key generation by loading a pre-generated keypair shipped
+inside the package, and skips the public-key upload (the platform already holds
+the matching public bundle). It exists so a prediction can run immediately in a
+live demo without the ~250 s keygen delay.
+
+Activate with an environment variable (applies to the whole session):
+
+```bash
+export IMPLICANT_DEMO=1
+implicant predict -m cancer -i row.json
+```
+
+Or per-command — combined with `--sample`, this is a zero-setup end-to-end run:
+
+```bash
+implicant predict -m cancer --sample --demo
+```
+
+Only the provisioned demo models (`cancer`, `diabetes`) have bundled keys; other
+model IDs raise an error in demo mode.
+
+> **Security warning — demo mode is not private.** The demo secret key is
+> shipped inside the package and is therefore public: anyone with the wheel can
+> decrypt anything encrypted in demo mode. **Never use demo mode for real or
+> sensitive data.** Normal mode (the default) generates a secret key that never
+> leaves your machine.
+
+## License
+
+Apache-2.0.

implicant-0.6.0/README.md

@@ -0,0 +1,210 @@
+# Implicant SDK
+
+Python **client** for the Implicant FHE inference platform. Encrypts one row
+locally under BGV, sends the ciphertext to the platform for homomorphic
+evaluation, and decrypts the result. The server never sees plaintext; the
+secret key never leaves the process.
+
+The classifier head runs **server-side under FHE** (Variant B): the platform
+returns one ciphertext with the class scores packed contiguously, which the
+client decrypts (unsigned) and decodes with `decode_class_scores` before
+threshold/argmax. `W` / `b` never reach the client.
+
+Pure Python — all crypto comes from [`implicant-fhe`](https://github.com/implicant/implicant-fhe)
+(`helut.client`). Contracts: [`docs/architecture.md`](docs/architecture.md)
+and `platform/docs/FHE_INTERFACE_SPEC.md`.
+
+## Install
+
+```bash
+pip install implicant
+```
+
+Pulls `implicant-fhe` (the `helut` crypto wheel) from PyPI automatically. Wheels
+ship for **CPython 3.10–3.14** on **macOS-arm64** and **manylinux x86_64** only.
+On any other target — Windows, Linux aarch64, macOS x86_64 — there is no wheel
+and no source fallback, so pip stops with `No matching distribution found for
+implicant-fhe`.
+
+### Developers
+
+```bash
+python3.13 -m venv .venv313
+.venv313/bin/pip install -e ".[dev]"
+.venv313/bin/pytest tests/ -v      # 100 tests, ~3.5 min (real BGV keygen)
+```
+
+To pin an unreleased `implicant-fhe` build, stage its wheel in `./wheels/` and
+add `--find-links wheels/`; the published versions resolve from PyPI without it.
+
+## Running an inference (CLI)
+
+The `implicant` CLI is the client-side workflow: configure once, then run
+encrypted predictions. Everything stays local except the ciphertext and the
+public keys — the secret key never leaves your machine.
+
+### 1. Point the client at the platform
+
+```bash
+implicant init --api-url https://api.implicant.example
+```
+
+Writes `~/.implicant/config.toml`. Run `implicant status` to confirm the
+configured `api_url` and list any locally cached keys.
+
+### 2. Set your API token
+
+The bearer token is read from the environment, never stored on disk:
+
+```bash
+export IMPLICANT_API_KEY="imp_..."
+```
+
+### 3. Discover the available models
+
+The SDK ships a hand-maintained registry of the models servable on the
+platform (there is no server-side listing endpoint yet):
+
+```bash
+$ implicant models list
+cancer    Predicts whether a breast tumor is malignant or benign
+diabetes  Predicts whether a patient has diabetes
+```
+
+The listed slug is the `--model` value for `predict`.
+
+### 4. Prepare the input row
+
+One row of raw feature values, as a JSON object (or a single-row CSV). The keys
+are the feature names the model expects. Each known model ships a bundled
+example row — the fastest way to get a correct starting point:
+
+```bash
+implicant models sample diabetes --out row.json   # or no --out to print to stdout
+```
+
+```json
+{
+  "preg": 6,
+  "plas": 148,
+  "pres": 72,
+  "skin": 35,
+  "insu": 0,
+  "mass": 33.6,
+  "pedi": 0.627,
+  "age": 50
+}
+```
+
+Edit the values by hand to test different inputs, then feed the file to
+`predict`. (`--out` refuses to overwrite an existing file unless you pass
+`--force`.)
+
+### 5. Predict
+
+```bash
+implicant predict --model diabetes --input row.json
+```
+
+Or skip the file entirely and run on the bundled example row:
+
+```bash
+implicant predict --model diabetes --sample
+```
+
+This fetches the model manifest, generates (or reloads) your keys, uploads the
+**public** keys on first use, encrypts the row locally, sends the ciphertext,
+then decrypts and decodes the returned class scores. Progress streams to
+stderr (with a spinner on the current step in a terminal) and the decision
+lands on stdout:
+
+```
+✓ Fetching model configuration
+✓ Preparing encryption keys
+✓ Encrypting input data
+✓ Evaluating on the server (encrypted)
+✓ Decrypting server response
+Final decision: tested_negative
+```
+
+Add `--json` for the machine-readable result instead of the decision line
+(progress stays on stderr, so piping stdout to `jq` is safe):
+
+```json
+{
+  "key_id": "bgv-n32768-L4-a1b2c3d4e5f6",
+  "label_index": 0,
+  "label": "tested_negative",
+  "scores": [-6684]
+}
+```
+
+Add `--no-persist-key` to use an ephemeral secret key for a single run (nothing
+written to disk; keys are regenerated and re-uploaded next time).
+
+### Managing keys
+
+The first prediction for a `key_id` persists your secret key to
+`~/.implicant/keys/<key_id>/secret_key.bin` (mode `0600`) so later runs skip
+keygen. Inspect and clean up the local store:
+
+```bash
+implicant keys list            # list key_ids; flags which have a persisted SK
+implicant keys rm <key_id>     # delete one stored key (secret + public)
+implicant keys purge --yes     # delete all stored keys
+```
+
+## Use (Python)
+
+The same flow is available programmatically:
+
+```python
+from implicant import ImplicantClient, list_known_models, sample_row
+from implicant.transport import HttpxTransport
+
+for m in list_known_models():          # discover: (slug, description) pairs
+    print(m.slug, "—", m.name)
+
+row = sample_row("diabetes")           # fresh mutable copy of the bundled example
+row["age"] = 61                        # hand-tweak values for testing
+
+client = ImplicantClient(
+    HttpxTransport(base_url="https://api.implicant.example", api_key="imp_..."),
+    key_cache_dir="~/.implicant/keys",
+)
+result = client.predict("diabetes", row, class_names=("negative", "positive"))
+print(result.prediction.label)
+```
+
+## Demo mode
+
+Demo mode skips FHE key generation by loading a pre-generated keypair shipped
+inside the package, and skips the public-key upload (the platform already holds
+the matching public bundle). It exists so a prediction can run immediately in a
+live demo without the ~250 s keygen delay.
+
+Activate with an environment variable (applies to the whole session):
+
+```bash
+export IMPLICANT_DEMO=1
+implicant predict -m cancer -i row.json
+```
+
+Or per-command — combined with `--sample`, this is a zero-setup end-to-end run:
+
+```bash
+implicant predict -m cancer --sample --demo
+```
+
+Only the provisioned demo models (`cancer`, `diabetes`) have bundled keys; other
+model IDs raise an error in demo mode.
+
+> **Security warning — demo mode is not private.** The demo secret key is
+> shipped inside the package and is therefore public: anyone with the wheel can
+> decrypt anything encrypted in demo mode. **Never use demo mode for real or
+> sensitive data.** Normal mode (the default) generates a secret key that never
+> leaves your machine.
+
+## License
+
+Apache-2.0.

implicant-0.6.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "implicant"
+version = "0.6.0"
+description = "Python client SDK for the Implicant FHE inference platform"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Implicant" }]
+license = { text = "Apache-2.0" }
+license-files = ["LICENSE"]
+dependencies = [
+    # FHE primitives (keygen, encrypt, decrypt, Params, key_id) live here.
+    # The SDK is a pure-Python client over `helut.client`. Floor is 0.5.0:
+    # that release moves the kernel to SEAL 4.4.3, which rotates every
+    # canonical key_id (seal_version "4.3" -> "4.4" in the params hash), so
+    # the bundled demo keys only exist under 0.5-era key_ids. The 0.4-era
+    # client/server wheel split still holds: both distributions satisfy this
+    # specifier, and only the public client build is reachable from PyPI.
+    "implicant-fhe>=0.5,<0.6",
+    "httpx>=0.27",
+    "pydantic>=2.6",
+    "typer>=0.12",
+    # Progress rendering in the CLI (typer already requires it; declared
+    # because we import it directly).
+    "rich>=13.8",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+# The worker (server-capable) build of implicant-fhe — carrying the
+# `+server` local version once implicant-fhe's client/server wheel split
+# lands — belongs ONLY here, never in [project.dependencies]. The SDK's own
+# test suite legitimately drives the real engine (tests/_server_harness.py)
+# on a dev machine; a client installing `implicant` from PyPI must never be
+# able to resolve the worker build even by accident. Enforced against the
+# BUILT wheel by tests/test_no_server_surface.py. See
+# implicant-fhe/docs/superpowers/plans/2026-07-31-client-server-wheel-split.md
+# Task W5. The runtime floor is 0.5.0 (see [project.dependencies]); both
+# distributions satisfy it, and PyPI structurally refuses the worker build's
+# local version, so a client cannot resolve it.
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[project.scripts]
+implicant = "implicant.cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/implicant"]
+# Demo keypairs are large .bin blobs (typically VCS-ignored); force-include them
+# so demo mode can load them at runtime. Public material only + a PUBLIC demo SK.
+artifacts = ["src/implicant/demo_keys/**/*.bin"]
+
+[tool.hatch.build.targets.sdist]
+# Keep internal dev context, local tooling, and the non-functional demo stub
+# out of the published source dist. `demo_handoff.zip` is a 482 MB bundle of
+# public key blobs staged for the platform; the sibling `demo_handoff/` dir is
+# VCS-ignored but the zip is not, so without this it lands in the sdist and
+# pushes it to ~489 MB — far past PyPI's 100 MB per-file limit.
+# `tests/` and `scripts/` are excluded for a SECURITY reason, not tidiness:
+# `tests/_server_harness.py` and the w6_* probes wire the engine's worker-only
+# facade into a working local round trip. That recipe was
+# deliberately removed from the shipped package (audit finding B1, wheel-split
+# task W5); shipping it in the sdist would hand it straight back. `docs/` goes
+# too — it references the private repo and internal design notes.
+# `scripts/check_no_server_surface.py` enforces this on every release.
+exclude = [
+    "CLAUDE.md",
+    ".claude",
+    "docs",
+    "tests",
+    "scripts",
+    "examples",
+    "demo_handoff.zip",
+]