Skip to content

AGENTS.md

Latest commit

 

History

History
155 lines (125 loc) · 7.04 KB

AGENTS.md

File metadata and controls

155 lines (125 loc) · 7.04 KB
Raw

AGENTS.md

Guidance for agents and contributors working in the NVIDIA Personal AI Router (PAIR) repository. It holds an Electron desktop application and the Go services it runs on, built from one checkout.

This file is the short orientation. CONTRIBUTING.md is the contribution policy and Developer Guide is the code tour; both are normative where this file is only a summary.

Repository Layout

Personal-AI-Router/
├── desktop/       Electron + React application
├── services/      Go broker, workers, proxies, terminal interface, installers
├── docs/          Product, architecture, and build documentation
├── scripts/       Repository-level helper scripts
└── Makefile       Wraps the build and check commands (Linux and macOS)

services/ is the source of truth for runtime behavior and desktop/ is a client of it. The application relays commands and renders reported state — it does not reimplement routing, scheduling, discovery, or cryptography in TypeScript. If you find yourself writing any of those in the desktop tree, the change belongs in a Go service instead.

How the Pieces Connect

  • Electron starts only nvpair-ui-broker from desktop/cli-bin/.
  • The broker supervises the other Go workers: discovery, proxies, engines, cluster, settings, manual nodes, workloads, errors, and the scheduler.
  • The broker spawns all 11 workers at startup. Only the scanner is required; the rest are optional and non-fatal.
  • nvpair-tui is bundled but never supervised. It owns its own broker.
  • Interprocess communication is newline-delimited JSON-RPC 2.0 over stdio (optional --ipc).
  • The desktop build compiles the Go binaries from the sibling services/ directory with npm run build:modular-binaries. There is no submodule.

Never launch the same worker from both Electron and the broker, and do not add a fallback path for a missing broker.

Desktop (desktop/)

cd desktop
npm install
npm start

npm start builds the service binaries first, so you do not need to build services/ separately.

  • Checks: npm run lint, npm run typecheck, npm run test:unit, npm run dead-code:check, npm run service-contracts:check
  • Contract tooling: npm run service-contracts / :write / :check

Use npm run typecheck rather than tsc directly, because the project has split Node and web targets. dead-code:check fails on any exported value or type that nothing imports, so an export added out of habit breaks it: delete it, drop the export when it is only used inside its own file, or justify it in desktop/dead-code-omissions.json.

Never edit desktop/docs/services-api.md by hand. It is generated by npm run service-contracts:write.

Services (services/)

Thirteen Go binaries. Each component is its own module, with its tests beside its source and a README.md describing its JSON-RPC surface. Shared packages live in shared/, and tests/ holds cross-process tests that drive real binaries. Prefer the Go source when a README disagrees with it.

Build from services/ — build.bat on Windows, ./build.sh on Linux and macOS. Staged binaries land in services/build/bin/. Requires Go 1.25 or newer and jq.

Run go test ./... from a component directory, and from services/tests for cross-process coverage. Some tests skip themselves rather than fail; refer to Testing, and treat a skip as untested rather than passing. Live engine and multi-node tests can modify real system state, so run them only when you intend to and only against systems and networks you control.

Checks

On Linux and macOS the repository-root Makefile is the shortest path to a clean run. Run make on its own to list every target.

make check    # SPDX headers, build-script verify, lint, typecheck, contracts, desktop tests
make test     # desktop unit tests plus go test in every services module

make check does not include npm run dead-code:check, so run that as well. On Windows, run the underlying npm and go test commands directly.

Conventions

  • No type casting. No as Type, as any, as unknown, or : any, and no unknown in signatures. If a cast seems necessary, the types are wrong.
  • Absolute imports across directories. Use the @/... alias for anything that would otherwise need ../. Within one directory, ./sibling is correct.
  • Static imports only. No await import().
  • No renderer imports from src/electron/. Shared code belongs in src/shared/ or behind the preload bridge.
  • Say engine, not backend, in user-facing copy and new code. Existing wire names, payload fields, and Go symbols keep their spelling: they are external contracts.
  • No legacy fallbacks. One canonical path. Delete what you replace instead of leaving a compatibility branch behind.
  • Never log prompts, messages, response bodies, pairing PINs, or key material. Log operational metadata such as engine, model, job ID, and node ID instead.
  • Every file carries a two-line SPDX header. Check the tree with node scripts/spdx-headers.mjs, and insert missing headers with --fix.
  • When changing a JSON-RPC method or payload, update the producing Go service, the broker relay, every consumer, the desktop bridge under desktop/src/electron/service-bridge/, the tests, and the documentation in the same change. Then run npm run service-contracts:check from desktop/.
  • Bump the version of any service binary whose compiled output you change in services/versions.json, and describe any user-facing change in the pull request so it reaches the release notes. Versioning gives the rules.
  • Sign off every commit with git commit -s. The Developer Certificate of Origin trailer has to match the commit author, so a missing or mismatched sign-off means rewriting the commit rather than fixing it in review.
  • Prefer small, focused commits. Work from a fork on a branch off main, and open a pull request; only maintainers merge.

Platform Support

Windows, Linux, and macOS, on x64 and arm64.

Where to Read Next

  • Overview — what PAIR does and the vocabulary the other documents assume
  • Developer Guide — where the code lives and how a change travels through the layers
  • Architecture — process model, discovery, routing, and trust boundaries
  • Building and Running — prerequisites, source builds, and running the services without the desktop application
  • CONTRIBUTING.md — policy, pull requests, and review
  • SECURITY.md — what PAIR does and does not defend against
  • Services and Desktop — component references, each indexing its own documents

README.md indexes the full documentation set in reading order.