Metadata-Version: 2.4
Name: fherma-runner
Version: 0.2.0
Summary: Takes measurement jobs from a FHERMA platform and reports what happened
Author: FairMath
License: Apache-2.0
Project-URL: Homepage, https://fherma.io
Project-URL: Source, https://github.com/fairmath/fherma-runner
Keywords: fhe,cryptography,benchmarking,kernels,runner
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.10
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 :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# fherma-runner

Takes measurement jobs from a [FHERMA](https://fherma.io) platform and reports
what happened.

```shell
uv tool install fherma-runner        # or: pipx install fherma-runner
fherma-runner --api https://fherma.io --name bench-01 --token fhr_...
```

A command line tool belongs in an environment of its own, and on macOS it has
no choice: the system Python has no `pip` on the path at all, and Homebrew's is
marked externally managed so installing into it is refused. `uv tool` and
`pipx` both make that environment and leave `fherma-runner` on the path, which
is the part `pip install --user` does not do.

Neither installed? One line, and nothing else on the machine changes:

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Check what you got:

```console
$ fherma-runner --version
fherma-runner 0.2.0 · python 3.13.4
```

The token comes from the platform, is good for an hour and is spent once: the
first start exchanges it for this machine's own key and keeps that in
`~/.fherma-runner`. Every start after the first needs no token.

Every start says what the machine is now, so a server that was re-provisioned is
matched on what it is rather than on what it was.

## What it needs

An interpreter and `docker`. There are no dependencies: everything here ships
with Python, and docker is called as a command.

## What it declares

Hardware, and only hardware — cores, memory, architecture, CPU features, an
accelerator and its driver. It does not declare libraries or images, because
the environment a job runs in is not a property of a machine: it arrives with
the job, pinned to a digest.

```
fherma-runner --describe
```

prints what it would report, and stops.

## What it does with a job

```
jobs/<id>/
├── bundle/     the specification's bundle, unpacked
├── solution/   the repository at the commit, and its build
└── points/
    └── p000/   one point at a time, deleted once reported
```

Per point: the bundle makes the cases, the solution answers them, the bundle
judges the answers. Three containers, and the solution is never given the
directory holding the expected answers.

## Options

```
--api           where the platform is                  FHERMA_API
--name          what to call this machine              FHERMA_RUNNER_NAME
--token         an invitation, spent once for a key
--interval      seconds between polls                  3
--once          take one assignment, then stop
--describe      print what this machine is, and stop
--version       what is installed, and on what
--re-register   forget the key and join again
```

The `--speed`, `--fail-rate`, `--build-seconds` and `--point-seconds` options
belong to the half that is still pretended, and go away with it.

## Stopping

The platform stops a runner by refusing its heartbeat. It then drops
everything at once and sends nothing: finishing the work and reporting it would
be reporting into a result somebody else now owns.

If a runner goes quiet instead, its lease lapses, the run is marked expired and
the job goes to another machine.

## Licence

Apache-2.0.
