Edge SDK
Connecting field devices to the platform with geo-mlops-sdk
This chapter is for developers who connect field devices (edge PCs) to Geo-MLOps. It uses the public PyPI package geo-mlops-sdk (import name geo_mlops_sdk, currently 0.2.0, Python 3.10 or later).
Two things in the package
| What | import | When |
|---|---|---|
Agent (geo-mlops-edge) | Not used — run it from a config file | Runs as an always-on service on the device. Has everything: local queue, offline buffering, uploads, collectors, model cache, local API |
Client CentralClient | geo_mlops_sdk.client | When your existing application calls the central server API directly |
In most cases the agent alone is enough. You configure the agent without writing code, through edge.yaml and environment variables.
Flow between the device and Central
Edge device (geo-mlops-edge) Central (Geo-MLOps)
───────────────────────── ────────────────
① Register POST /api/v1/edge/register ──▶ device 'Healthy'
② Heartbeat POST /api/v1/edge/heartbeat ──▶ CPU, memory, backlog, collector status
③ Collect collectors → local queue (SQLite) (keeps filling while the link is down)
④ Sync telemetry · inference · uploads ─▶ Collected data, Inference results, Files tabs
⑤ Commands GET /api/v1/edge/commands ◀── ping · restart · pull_model …
⑥ Model pull GET /api/v1/edge/models/… ◀── model registry
⑦ Inference local inference → queue → inference ──▶ Inference results tabCalls go in one direction only: from the device to the server. The server cannot open a connection to a device behind a factory NAT, so the device also fetches commands by long polling (keeping a request open until a response arrives). Every call is authenticated with a device token issued by Central (the X-Edge-Token header).
Pages in this chapter
| Page | Contents |
|---|---|
| Install | pip install and extras |
| 5-minute start | Register a device → edge.yaml → run the agent → check it on the fleet screen |
| Configuration reference | Every EdgeSettings field, config file lookup order, environment variables |
| Data collectors | http · push · modbus · watchdir, custom collectors |
| Models and inference | Model download, runners, the local inference API |
| Local API | The HTTP API on the device (port 8600) |
| Commands, policy and retention | Server commands, the Policy tab, offline buffering and sync |
| Connecting directly with CentralClient | Async client, error hierarchy, retries |
| Deploy | systemd, Docker, docker compose, token rotation |
| CLI | geo-mlops-edge subcommands |
| Troubleshooting | Offline, 401, 413, queue backlog |
The full function signatures are in the Edge SDK API reference.