Syva Service SDK

Package: syva-service-sdk (syva_sdk). Requires Python ≥ 3.9. The SDK talks to the local Node Agent — it does not register directly with the control plane.

What the SDK does

1. Registers the service with the local Node Agent
2. Sends heartbeats so the service stays healthy in the registry
3. Deregisters cleanly on shutdown so traffic stops promptly
4. Maintains a persistent instance id across process restarts

Hardware telemetry is owned by the Node Agent, not the SDK. Place a Node Agent on every machine that hosts services you want in the mesh.

Architecture

Installation

Distribution depends on your engagement (platform bundle, private index, or source path). Typical editable install during development:

cd syva_service_sdk
pip install -e .

# Optional FastAPI extras (uvicorn + fastapi for example apps)
pip install -e ".[fastapi]"

Configuration

Configure primarily via environment variables (read when constructing the client):

On first run the SDK writes .syva_instance_id in the working directory. Keep it unless you intentionally want a new instance identity.

Core API

from syva_sdk import SyvaClient

client = SyvaClient()

if client.register():
    client.start_heartbeat()
    # ... run your service ...
    client.deregister()  # also stops heartbeat
else:
    raise SystemExit("Failed to register with Syva Node Agent")

FastAPI lifespan pattern

from fastapi import FastAPI
from syva_sdk import SyvaClient
import contextlib

@contextlib.asynccontextmanager
async def lifespan(app: FastAPI):
    client = SyvaClient()
    if not client.register():
        raise RuntimeError("Syva registration failed")
    client.start_heartbeat()
    app.state.syva_client = client
    try:
        yield
    finally:
        client.deregister()

app = FastAPI(lifespan=lifespan)

@app.get("/health")
def health():
    return {"status": "ok"}

Consume path after registration

Once the service is active, consumers call through the Data Plane proxy:

https://<nexus-host>/v1/proxy/<SERVICE_NAME>/<path>

# Optional group route for pooled replicas
https://<nexus-host>/v1/proxy/group/<group>/...

Best practices

• Always call deregister() on shutdown (or use a lifespan finally).
• Prefer SERVICE_HOST=auto on workers so the gateway receives a routable IP.
• Keep SERVICE_NAME stable — it is part of the public proxy path.
• Use SYVA_GROUP when running multiple replicas of the same capability.
• Treat SERVICE_TOKEN as a secret — never bake real tokens into images or examples.
• Do not send hardware stats from the SDK — rely on the Node Agent.

Troubleshooting (high level)

Related: How it works · Platform overview · Request pilot access for operator manuals and connector guides.