@link1987/llm-byok

LLM BYOK (Bring Your Own Key) SDK — provider/model registry, shared types, request param helpers.

Registry data is bundled from models.dev. Filtered by providers.config.yaml.

Install

npm install @link1987/llm-byok

Types

ProviderConfig

Core configuration describing "which provider + model + key" to use. This is the protocol shared between frontend and backend.

interface ProviderConfig {
  provider: string;  // provider id, e.g. "openai"
  model: string;     // model id, e.g. "gpt-4o"
  apiKey?: string;   // optional — some providers offer free access
  apiBase?: string;  // override base URL (for openai-compatible)
}

ProviderDef / ModelDef / AdapterFamily

Registry metadata types. ProviderDef contains models: ModelDef[], adapter info, and apiBase.

LLMRequestParams<T>

Generic type for request bodies that embed a ProviderConfig under an llm field:

type LLMRequestParams<T = Record<string, unknown>> = { llm: ProviderConfig } & T;

Registry API

createRegistry() is the only entry point. Three usage modes:

import { createRegistry } from "@link1987/llm-byok";

// 1. Default registry (bundled from models.dev)
const registry = createRegistry();

// 2. Fully custom data (no SDK defaults)
const registry = createRegistry({ data: myProviders });

// 3. Merged: SDK defaults + your custom (deep merge)
const registry = createRegistry({ extra: myProviders });

All three return the same Registry interface:

registry.providers;                              // ProviderDef[]
registry.getProvider("openai");                  // ProviderDef | undefined
registry.getModels("openai");                    // ModelDef[]
registry.getProviderAndModel("openai", "gpt-4o"); // { provider, model } | undefined
registry.validateConfig({ ... });                // { valid: true } | { valid: false, errors }

Extend with custom providers/models

Models with the same id are merged; providers with the same id are deep-merged.

const registry = createRegistry({
  extra: [
    {
      id: "my-ollama",
      name: "My Ollama",
      adapter: "openai-compatible",
      apiBase: "http://localhost:11434/v1",
      models: [{ id: "llama3", name: "Llama 3" }],
    },
  ],
});

registry.getProvider("my-ollama");    // ProviderDef
registry.getModels("my-ollama");      // ModelDef[]

Params API

Validate and parse ProviderConfig from raw input. Frontend and backend use the same flat protocol:

{ "provider": "openai", "model": "gpt-4o", "apiKey": "sk-...", "messages": [...] }

Backend: parseProviderConfig(raw)

Parse a flat request body and extract/validate ProviderConfig.

import { parseProviderConfig } from "@link1987/llm-byok";

export async function POST(req: Request) {
  const body = await req.json();
  const parsed = parseProviderConfig(body);

  if (!parsed.valid) {
    return Response.json({ error: parsed.errors.join("; ") }, { status: 400 });
  }

  // parsed.config: ProviderConfig
  const { provider, model, apiKey, apiBase } = parsed.config;
}

Backend: parseLLMParams(raw)

Like parseProviderConfig, but expects the config under a nested llm field: { llm: { provider, model, apiKey }, messages }.

Frontend: buildProviderConfigPayload(config)

Convert a ProviderConfig into a flat JSON payload for the request body.

import { buildProviderConfigPayload } from "@link1987/llm-byok";

const payload = buildProviderConfigPayload({
  provider: "openai",
  model: "gpt-4o",
  apiKey: "sk-...",
});

// { provider: "openai", model: "gpt-4o", apiKey: "sk-..." }
// Spread into useChat body or fetch body

validateConfig(config)

Validate a ProviderConfig against the registry (checks provider id, model id).

import { validateConfig } from "@link1987/llm-byok";

const result = validateConfig({ provider: "openai", model: "gpt-4o", apiKey: "sk-..." });
if (result.valid) { /* ok */ }
else { console.log(result.errors); }

CLI: llm-byok-build

Build script that fetches models.dev and generates registry.json. Installed as a binary via npm bin field — run with npx.

Quick start

# 1. Create your config
cat > providers.config.yaml << 'EOF'
providers:
  stepfun:
    models: [step-3.5-flash]
  my-company:
    name: "My Company"
    adapter: openai-compatible
    apiBase: "https://llm.my-company.com/v1"
    models:
      - id: my-model-v2
        name: "My Model V2"
EOF

# 2. Generate (auto-merges with SDK defaults)
npx llm-byok-build --config ./providers.config.yaml --output ./src/custom-registry.json

# 3. Use in code

import { createRegistry } from "@link1987/llm-byok";
import customData from "./custom-registry.json";

const registry = createRegistry({ extra: customData });
// SDK defaults + your custom providers

Options

| Flag | Description | |------|-------------| | --config <path> | (required) Your providers.config.yaml | | --output <path> | (required) Output JSON path |

When the output path is different from the SDK's bundled registry, your config is automatically merged with SDK defaults. When building the SDK's own default registry, merge is skipped automatically.

Config file format

Provider in models.dev — only list model IDs, metadata comes from models.dev automatically:

providers:
  openai:
    models: [gpt-4o, gpt-4o-mini]

Provider not in models.dev — define inline with full ProviderDef:

providers:
  my-company:
    name: "My Company LLM"
    adapter: openai-compatible
    apiBase: "https://llm.my-company.com/v1"
    models:
      - id: my-model-v2
        name: "My Model V2"