Skip to content

AGENTS.md

Latest commit

 

History

History
168 lines (137 loc) · 7.94 KB

AGENTS.md

File metadata and controls

168 lines (137 loc) · 7.94 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
├── .cursor/       Architecture and discipline rules, skills, and commit hooks
├── .agents/       Shared agent skills (UI patterns, backend sync, test style)
└── Makefile       Wraps the build and check commands (Linux and macOS)

.cursor/rules/ is not advisory. Those files record the boundaries the code is actually held to — process ownership, IPC shape, typing discipline, and where state lives — and a change that violates one will be caught in review. Read the rules covering the area you are touching before you start, and prefer services/*/spec.md over a component README where the two disagree.

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 10 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/)

Twelve 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/.
  • Declare a bump for any service binary whose compiled output you change in the pair-release-intent:v1 block in your pull request description, and describe any user-facing change there so it reaches the changelog. Do not edit services/versions.json or CHANGELOG.md by hand — automation writes them, and CI rejects a pull request that modifies them. 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

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