falconsai-surgeon — the command line and Python client for FALCONS.AI Model Surgeon

Model Surgeon — https://surgeon.falcons.ai — is a visual operating theatre for neural networks: load a real checkpoint in the browser, see its anatomy in 3-D, operate on it with reversible tools (excise, graft, merge, quantize, fold), measure every consequence, and export a package whose signed record anyone can verify.

falconsai-surgeon is the thin client for that server. It holds no server code, is standard library throughout, and depends on one package (cryptography, for the verifier's ed25519 check). Version 7.115.

pip install falconsai-surgeon
surgeon doctor --server https://surgeon.falcons.ai --key <your account key>

Your account key is the one the theatre keeps under ◈ ACCOUNT (the key box has a ⧉ copy icon). Every command that talks to the server takes it as --key; the client reads no environment variable for it. Surgery and jobs need a Practitioner key; upload, report and doctor run on any recognised key; verify needs no key and no server. Tiers and limits: https://surgeon.falcons.ai/pricing

The commands

Global flags: --verbose prints every request and its status to stderr; --no-session-cache keeps nothing between runs (a dropped upload cannot resume).

Exit codes for every command: 0 clean · 1 the server refused one or more ops (the job ran; its words are printed) · 2 the client refused (its message says why and what next). Every HTTP refusal is printed with the server's own words and a next: line.

What the client does not do: it does not export or download the package — finish in the browser (--open) with ⬇ Package Model, or call /api/export from Python (below); it does not read the key from the environment; it does not push to Hugging Face.

From Python

The same client is importable; the notebooks FALCONS.AI publishes use it this way.

from surgeon.client import Remote, ClientError

r = Remote("https://surgeon.falcons.ai", key=KEY, timeout=1800)
meta = r.get("/api/meta")                       # signed_in · tier · version · the model on the table
state = r.upload("model.safetensors",           # the chunk protocol; resumable
                 on_progress=lambda i, n: print(f"chunk {i}/{n}"))
url, ttl = r.claim()                            # the 60-second hand-off link
rec = r.recipe(open("ops.yaml").read())         # {source_model, ops, count} — read by the server
job = r.job(rec["ops"])                         # {id, state, done, total, refused[]}
res = r.call("/api/export", {})                 # build the signed package; res["download"] is the GET path
link = Remote(server, key, session_cache=False) # a fresh jar for a Link CLI token
link.attach(token); link.watch_definition("model_definition.py", interval=2.0)

Remote(server, key=None, timeout=600, opener=None, verbose=False, session_cache=True) · .call(path, body) POST JSON · .get(path) GET JSON · .get_text(path) GET text · .upload(path, purpose="model", on_progress=None) · .claim() · .recipe(text) · .job(ops, kind="replay") · .attach(token) · .watch_definition(out, interval=2.0). Every refusal raises ClientError with the server's words and the next action; nothing calls sys.exit. For a binary download (the package) use r.opener with the X-Surgeon-Key header, as the published notebook cells do.

Install

From PyPI (the ordinary path):

pip install falconsai-surgeon

Air-gapped, or to match exactly the wheel your server serves — the server that runs your session publishes its own wheel and its sha256, no account needed:

curl -O https://<your-surgeon-host>/download/falconsai_surgeon-<version>-py3-none-any.whl
curl -O https://<your-surgeon-host>/download/falconsai_surgeon-<version>-py3-none-any.whl.sha256
sha256sum -c falconsai_surgeon-<version>-py3-none-any.whl.sha256
pip install falconsai_surgeon-<version>-py3-none-any.whl

Python 3.9 or newer, any OS. Output is ASCII-safe on piped Windows consoles. surgeon doctor says when the server runs a different version than this client: install the wheel the server serves. watch-definition needs a client at 7.109 or later and a server at 7.107 or later (an older client does not list the command in surgeon --help).

Sessions, resume and safety

• The session cookie is kept per server under ~/.falconsai-surgeon/ (directory 0700, file 0600), so a dropped upload resumes: rerun the same command and the server says which chunks it already holds (--verbose shows resuming: …). --no-session-cache turns that off.
• The key travels only as the X-Surgeon-Key header to the host you named. A redirect to another host is refused in words; the key is never sent there.
• A reply that is not JSON (an edge or proxy page) is reported with its first bytes, never a traceback.
• Sessions are ephemeral: the model is deleted when the browser session ends or after 30 idle minutes. The client never stores a checkpoint.

Troubleshooting

Run surgeon doctor --server URL --key KEY first.

How this package is built

The source of truth is the Model Surgeon tree's client/; the repository at https://github.com/Falcons-ai/falconsai-surgeon-thin-cli mirrors it at each release and publishes through Trusted Publishing (no stored token). The wheel is built with a pinned build backend and a pinned SOURCE_DATE_EPOCH on both sides, and the server prints the sha256 of the wheel it serves at /download/; compare it with the hash PyPI shows for the same version.

Licensing

The client is proprietary; surgeon/verify.py — the offline package verifier — is Apache-2.0 and free for everyone, forever. See LICENSE.txt.