Metadata-Version: 2.5
Name: fherma
Version: 0.1.0
Summary: Command line interface for the FHERMA kernel catalogue
Project-URL: Homepage, https://fherma.io
Author: FairMath
License: Apache-2.0
License-File: LICENSE
Keywords: benchmarking,cli,cryptography,fhe,kernels
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: fherma-lang>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# fherma

Command line interface for the [FHERMA](https://fherma.io) kernel catalogue.

```shell
pip install fherma
```

That is the whole toolchain: `fherma-lang` comes with it as a dependency, so the
install leaves two commands on the path — `fherma`, and `fherma-lang` for the
language on its own. Check what you got:

```console
$ fherma --version
fherma       0.1.0
fherma-lang  0.1.0
python       3.13.4

$ fherma doctor
✓ python       3.13.4
✓ fherma       0.1.0
✓ fherma-lang  0.1.0
✓ commands     auth, testing
✓ profile      default → https://api.fherma.io
• credentials  no token
```

`doctor` is offline by default — the usual reason to run it is that something is
wrong, and a network timeout would bury the answer. Pass `--online` to check the
token as well. It exits non-zero only when the toolchain is actually broken; a
missing token is not broken, since scaffolding from a local signature never
needs one.

Tab completion, once:

```shell
fherma completion zsh >> ~/.zshrc      # or bash, or fish
```

A command line tool is better off in its own environment than in the system
interpreter, and both of these put it on the path without one:

```shell
uv tool install fherma
pipx install fherma
```

## What it is for

A kernel in FHERMA is a computational problem; a specification is one precise
statement of it. Before implementations can be submitted against a
specification, it needs three functions — a **generator**, an **oracle** and a
**verifier** — which say where test data comes from, what the right answer is,
and how a verdict is reached.

This tool fetches the scaffold for those three, runs their checks locally, and
sends them back.

## Getting started

```shell
fherma auth login
fherma testing init polymult/rlwe@1.0.0
```

That writes a bundle:

```text
polymult-rlwe-1.0.0/
├── fherma.toml      generated — which specification this belongs to
├── fherma.py        generated — Point, Inputs, Outputs, Stream, Tensor
├── README.md        generated — the signature, and what to write
├── generate.py      yours
├── oracle.py        yours
├── verify.py        yours, and usually unnecessary
├── vectors/         worked examples, for accepting the oracle
└── assets/          data files the three functions may read
```

`fherma.py` is derived from the specification's signature: the types are already
correct, so there is nothing to declare and nothing to get wrong. Write the two
function bodies; the third is usually unnecessary, since most verdicts are
exact equality and that is what the platform does when `verify.py` says nothing.

The generated files are rewritten by `fherma testing init --update`; yours never
are. Running the three locally — `fherma testing check` — is not in this
release.

## Commands

```text
fherma auth        login · logout · whoami
fherma testing     init · status
fherma doctor      check the installation
fherma completion  a script for bash, zsh or fish
```

Name a specification as `kernel/spec@version`; the version may be left off, and
the latest published one is used.

```shell
fherma testing init polymult/rlwe@1.0.0
fherma testing init polymult/rlwe --oracle --verifier    # two of the three
fherma testing init --signature ./sig.fhk                # no platform involved
```

The scaffold itself comes from [`fherma-lang`](https://pypi.org/project/fherma-lang/)
and is built in this process, so the platform is asked for one thing — the
signature — and `--signature` needs no network at all.

More arrive as the platform grows; `fherma <group> --help` lists what a group
can do.

Every command takes `--json`, because this output is read by CI and by the web
interface as well as by people. Exit codes are fixed: `0` success, `1` a check
did not pass, `2` a usage error, `3` not authorised, `4` the platform could not
be reached.

## Profiles

```shell
fherma --profile staging auth login
```

Configuration lives in `~/.fherma/config.toml`. `FHERMA_URL` and `FHERMA_TOKEN`
override it, so continuous integration never has to write a token to disk.
