Geo-MLOps-SDK

Edge SDK and runtime for the Geosoft MLOps Central Platform.

The package ships two things:

• geo_mlops_sdk.client — an async HTTP client (httpx) whose methods map 1:1 onto Central's device API. Use it when you only want to call the platform from your own application.
• geo_mlops_sdk.edge — a standalone edge runtime: local durable queue, connectivity monitor, throttled uploader, collectors, model cache and runners, a FastAPI surface for the on-site web UI, and a service daemon.

An edge PC is assumed to be treated roughly — cables pulled, power cut, offline for days. The runtime accumulates locally under a size/age ceiling, watches for the link to come back, and pushes the backlog without starving the collection that keeps running.

Installation

pip install geo-mlops-sdk               # client only
pip install 'geo-mlops-sdk[edge]'       # + standalone runtime and daemon
pip install 'geo-mlops-sdk[edge,gpu,modbus,yolo]'

PyPI currently holds 0.0.2, a placeholder published before this SDK was rewritten. 0.1.0 is the first release of the rewritten package; anything below it predates the current API and shares nothing with it but the name.

Usage

from geo_mlops_sdk.client import CentralClient
from geo_mlops_sdk.contracts.edge import HeartbeatBody

async with CentralClient("https://central.example", "device-token") as client:
    await client.register(location="yard-1")
    await client.send_heartbeat(HeartbeatBody(cpu=12.5, mem=55.0, disk=61.0))

geo-mlops-edge run --config /etc/geo-mlops/edge.yaml   # service entry point
geo-mlops-edge status                                  # ask a running agent
geo-mlops-edge queue --state failed                    # why nothing is arriving

Deployment samples live in deploy/: a systemd unit, a Dockerfile, and annotated edge.yaml / Modbus register-map examples. The top-level docker-compose.yml runs the agent on its own from that Dockerfile, reading /etc/geo-mlops/edge.yaml and edge.env from the host; a push to main of the geo remote deploys it onto the self-hosted runner labelled edge (.github/workflows/deploy-edge.yml).

Rotating a device token

A device token is required to talk to Central, and rotating one is a site visit. There is no remote path back:

1. Rotate or revoke the token in Central (POST /edge/devices/{id}/token:rotate).
2. The agent's next call is refused, the link goes to AUTH_FAILED, and it stops -- deliberately, rather than hammering Central with rejected requests.
3. On the machine, put the new token in /etc/geo-mlops/edge.env (GEO_EDGE_CENTRAL__TOKEN=...) and restart the service: sudo systemctl restart geo-mlops-edge.

Step 3 cannot be done from Central. The command poller stops along with everything else, so a restart command cannot reach the device either -- which is why the fleet screen reports how many days a token has left (token_expires_in_days): tokens last a year, and that is exactly long enough for the expiry to arrive unplanned.

geo-mlops-edge status says the same thing in words, at the top of its output, so an engineer already standing at the machine does not have to infer it from a state name.

The agent never restarts itself. A restart command from the fleet makes it exit with code 3 and the supervisor starts a clean process.

Development

This project uses uv for dependency management.

uv sync --group dev --all-extras

Quality tooling (wrappers run the tool from the project root):

./check.sh          # black --fix, isort --fix, flake8, mypy, pytest
./check.sh --ci     # formatters in check mode (what CI runs)
./check.sh --build  # the above plus `uv build`

Individual steps remain available: ./black.sh, ./isort.sh, ./flake8.sh, ./mypy.sh, ./pytest.sh.

Tests that need something outside the process are opt-in markers and are excluded by default: live (a real Central server, see scripts/live/), weights (real framework packages and checkpoints), gpu (an NVIDIA device).

Plans live in docs/plans/; the current one is 04-edge-sdk-rewrite-plan.md.