Serial Alice Agent

Verifiable energy and compute attestation agent for AI workloads. Issues Ed25519-signed certificates of energy consumption, anchored on Polygon.

Install

# From the self-hosted zip (no PyPI, no GitHub auth required):
pip install https://api.serialalice.pt/agent/download/linux

# Or download first:
curl -L https://api.serialalice.pt/agent/download/linux -o serial-alice-agent.zip
pip install serial-alice-agent.zip

# With NVIDIA GPU telemetry:
pip install "serial-alice-agent.zip[gpu]"

Quick start

export SA_AGENT_API_KEY=sa_live_...   # from https://app.serialalice.pt

serial-alice-agent status             # verify API connectivity
serial-alice-agent discover           # list detected hardware
serial-alice-agent run --job-name my-training -- python train.py

Run without installing

unzip serial-alice-agent.zip
cd serial-alice-agent
pip install requests pyyaml psutil cryptography   # core deps
python -m agent.cli status

Configuration

# agent.yaml
api_url: https://api.serialalice.pt
api_key: ${SA_AGENT_API_KEY}
measurement_interval_s: 10
hardware:
  gpu: auto
  cpu: true

Pre-registered experiments (baseline vs treatment)

serial-alice-agent experiment run --protocol experiment.yaml --out ./exp-out --evaluate

Runs a comparative experiment end to end: pre-registers the claim (signed, anchored), executes warm-ups (discarded), then every repetition in a seeded randomized order, applies each arm's treatment (sm_clock_lock_mhz, mem_clock_lock_mhz, power_limit_w), OBSERVES whether it took effect, samples GPU power on the same monotonic clock as the workload, restores clocks and power limit after every run (and on any error), and submits each repetition with its raw files and signed summary. With --evaluate it issues the outcome certificate and saves bundle.json + artifacts/ for offline verification. See agent/experiment/example_protocol.yaml.

An arm's treatment can also be a third-party controller process (external_controller, e.g. GPU Optimizer's ghost_switch.py): the protocol pins the file (and the files it imports) by sha256 — checked before pre-registration and before every repetition — and the pre-registration names it. Per repetition the executor starts the declared command, waits its warm-up, runs the workload, stops it with the declared signal, and binds its log and output files. The controller's OWN output decides whether it acted (declared checks such as actions_taken >= 1); a repetition where it did not is still submitted and makes the outcome INVALID. See agent/experiment/example_protocol_ghost_switch.yaml.

What it will not do: submit a failed run with invented data (it becomes visible attrition), hide a treatment that did not take effect (the outcome becomes INVALID), or present --simulate rehearsals as hardware measurements (they are submitted as operator-declared). Clock/power actuation needs root/admin and nvidia-smi; the NVIDIA backend reads through pynvml (pip install serial-alice-agent[gpu]).

Links

• Documentation: https://api.serialalice.pt/docs
• Platform: https://serialalice.pt