Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

[Feature]: Third-party hosts driving nvpair-ui-broker: is the JSON-RPC surface a supported contract, is the app-data layout versioned, and can the proxy expose the serving node?

Offen
  • Stimmt etwas nicht?
#67 2 Kommentare 0 Reaktionen 1 zugewiesene Person Auf GitHub ansehen

Maintainer antworten meist innerhalb von 4 Tagen

@sherief-nv arbeitet bereits daran.

Seit 09.10.2026.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
38/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
electron, go, ollama
Bereich
api, backend, distributed-systems

Rechercherichtung

Beginne mit dem nvpair-ui-broker JSON-RPC-Einstiegspunkt und README oder docs/integration.mdx und untersuche anschließend services/VERSIONING.md, node-id.json und cluster/identity.json. Führe die dokumentierten Broker- und Proxy-Befehle einschließlich discovery:subscribe, workloads:subscribe und curl aus, um das aktuelle Verhalten festzustellen. Als abgeschlossen gilt die Aufgabe, wenn der unterstützte Vertrag, die Handhabung der Datenformate und alle Metadaten in Proxy-Antworten mit der angegebenen Validierung dokumentiert oder implementiert sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Area

nvpair-ui-broker (JSON-RPC surface, --ipc mode), nvpair-cluster-manager (app-data / cluster dir layout), ollama-proxy (response headers)

User problem

We are integrating PAIR as the LAN inference layer behind our own desktop application (Magieva Desktop, an Electron app; we are an NVIDIA Inception member). Our host process supervises nvpair-ui-broker itself — spawned with piped stdio, or over --ipc — instead of the shipped PAIR UI, and relies on:

  • discovery:get-nodes / discovery:subscribe → discovery:nodes-changed for the roster (members, addresses, modelsByEngine, loadedByEngine, trusted / clustered);
  • workloads:subscribe → workloads:upsert with workloadInfo.scheduledOn / originatedFrom to record which node actually served each request (we write it to our usage ledger);
  • cluster:invite-node / cluster:respond-to-invite / cluster:invite-status and engine:remote-install / engine:remote-pull-model to drive pairing and model placement from our own UI;
  • the per-user app-data directory (~/Library/Application Support/Nvidia Corporation/Personal AI Router on macOS) and the cluster dir (identity.json, node.crt, node.key, trusted/) so an existing NVIDIA-created node keeps its identity when our host takes over supervision.

Measured on v0.1.1 (13b6811, built from source with Go 1.25, macOS 26 / Apple M4 Max): all of the above works today when the broker is driven from a plain shell over newline-delimited JSON-RPC 2.0 — app:ready in ~3 s, the roster is pushed, a real Ollama turn through the proxy yields workloads:upsert with scheduledOn set, and the invite / engine methods are routed. What we cannot determine from the repo:

  1. Is the broker's JSON-RPC method + notification surface a supported integration contract, with a compatibility policy across releases (additive changes only? deprecation window?), or is it considered internal to the shipped UI?
  2. Is the on-disk format of the app-data and cluster directories versioned? node-id.json and cluster/identity.json carry only node_uuid and created_at; services/VERSIONING.md versions binaries, not the data layout. A third-party host cannot tell whether a directory written by a newer or older PAIR is safe to attach to, or refuse it cleanly.
  3. Will the proxies expose the serving node on the HTTP response (e.g. an X-PAIR-Served-On: <hostUuid> header)? Today it is available only through the broker event stream (proxy:proxy/request.node_id, workloads:upsert.scheduledOn), which is fine for a host that also owns the broker, but not for an Ollama-compatible client that only sees the proxy.
Desired outcome
  • A short statement in the broker README (or a docs/integration.mdx) of which methods/notifications are stable for third-party hosts and how breaking changes are announced.
  • A format_version (or equivalent) field in node-id.json / cluster/identity.json, plus a documented rule for what a host should do when it does not match.
  • Optionally, a X-PAIR-Served-On response header on ollama-proxy / lmstudio-proxy responses.
Alternatives considered
  • Pinning to a vendored v0.1.1 build and treating every upgrade as a full re-validation of the JSON-RPC surface (what we will do if the surface is declared internal).
  • Reading the serving node only from the broker events (works for us; leaves plain Ollama clients unable to attribute a response).
  • Inferring the data-dir version from file shape (fragile; the reason for question 2).
Compatibility and security implications

Additive only: a version field and a response header change no existing behaviour. A published compatibility policy lets hosts fail closed on a surface they do not recognise instead of guessing. No change to pairing, mTLS or data handling is requested.

Validation approach
  • Drive the broker from a shell exactly as we did: ./nvpair-ui-broker --cluster-dir <dir> from a directory holding the sibling binaries, send {"jsonrpc":"2.0","id":1,"method":"discovery:subscribe"} and workloads:subscribe, run one POST /api/chat through the proxy, observe workloads:upsert with scheduledOn.
  • For the version field: create a node, read node-id.json, confirm the field; start a host against a directory carrying a higher version and confirm it refuses with a clear error.
  • For the header: curl -i a successful POST /api/chat through the proxy and read the header.
Confirmations
  • I searched existing issues for duplicates (#1, #4, #48, #49, #58 are adjacent — mDNS reflectors, enrichment refresh, test data dir, Linux service, headless manual nodes — none asks about contract stability, data-dir versioning or a served-on header).
  • I agree to follow the Code of Conduct.
Vorherrschende Sprache
Go
Sterne
1.6k
Forks
266
Ø Merge
3 T. 18 Std.
Gemergte PRs (30 T.)
28

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus NVIDIA/Personal-AI-Router

Alle Issues in NVIDIA/Personal-AI-Router

Ähnliche Issues

Weitere Issues zu Go

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.