Skip to main content
The Belvedir Node SDK auto-instruments the major LLM providers with a single initialize() call. Coming from @fractalresearch/loop, @belvedir/loop, or belvedir-loop? See Migrating from Fractal.

​
Install

​
Initialize before importing your LLM SDK

The SDK patches your LLM client the moment initialize() runs, so initialize() must run before the LLM SDK is imported. Call it once at process start. In a plain CommonJS Node process, that is the top of your entry file:
Never call initialize() from inside a route or handler file: by then the LLM SDK is already imported and the patch won’t take. In Next.js, the only place guaranteed to run first is instrumentation.ts at your project root; see the Next.js guide.

​
ESM and bundled code: pass instrumentModules

In an ESM entry point (.mjs, or "type": "module" in package.json) and in any bundled environment (Next.js, webpack, esbuild), always pass your LLM SDKs via instrumentModules; auto-instrumentation produces no LLM spans there, with no warning. Pass only the SDKs you actually use; either the SDK class or the module namespace is accepted:
In Next.js, also keep the LLM SDKs and belvedir itself out of your bundles with serverExternalPackages, so every bundle shares one runtime copy; see Keep LLM SDKs external.

​
Multiple apps and providers

  • Several apps, one project. Set a different appName per app; each app’s traces carry it. To filter the Data pages per app, give each app its own API key.
  • Several providers. Pass every provider you use to instrumentModules, for example { openAI: openai.OpenAI, anthropic }. Every span records which provider and model served it.
  • Your API key stays server-side. instrumentation.ts and your entry file run on the server; never expose BELVEDIR_API_KEY to client-side code.
  • Runtimes. The Node SDK needs the Node.js runtime; the Edge runtime on Vercel and similar platforms does not work. The Python SDK needs Python 3.10 or newer.

​
Next steps

  • Configuration: the SDK API, every option accepted by initialize(), and environment variables.
  • Providers: every LLM provider Belvedir auto-instruments, and which call styles are captured.
  • Python quickstart: same concepts, snake_case, context managers.