blablador-core

Shared Blablador (Helmholtz / JSC) catalog contract for the two host plugins:

• pi-blablador — the Pi provider
• opencode-blablador — the OpenCode plugin

Before this package both hosts carried their own copy of the model catalog, the family/effort maps, the /v1/models merge and the fetch. One new alias or effort change meant editing two repos, two test suites and two releases, and they could drift silently. This package is the single place those rules live.

What lives here (and what does not)

Pure catalog logic only:

| Export | Role | |---|---| | FALLBACK_MODELS, VISION, EXTRA_CHAT, NOT_CHAT | the verified offline catalog and its allow/block rules | | EFFORT, familyOf | per-family reasoning_effort vocabularies (a wrong word is an HTTP 400) | | displayName | picker row label: the alias with the deployment root, alias-first by default (rootFirst flips it for OpenCode), or the alias alone | | mergeLiveModels, fetchLiveModels | live /v1/models filtering and root/window merge | | resolveToken | normalize a stored or env token the same way in both hosts | | outputCap | keep the output limit under the window so the prompt has room |

Host policy stays in each adapter, on purpose. Caches, TTLs, allowNetwork, force, last-good retention and fallback-on-failure differ between Pi and OpenCode and must not be unified here — that would make one host silently inherit the other's behaviour. Each adapter imports these pure functions and keeps its own refresh logic on top.

Usage

import { FALLBACK_MODELS, fetchLiveModels, resolveToken, outputCap } from "blablador-core";

Plain ESM with no build step and no dependencies, so Pi's jiti extension loader and OpenCode's plugin loader both import index.js directly. index.d.ts is the type surface for TypeScript hosts.

Tests

npm test          # network-free catalog contract — what CI and prepublish run
npm run test:live # direct /v1/models contract, needs BLABLADOR_API_TOKEN, skips when absent

The offline suite is the shared invariants. The live suite is the only test that proves discovery and auth work against the real gateway — the host suites can pass on the bundled fallback when /v1/models is broken, so the direct API assertions live here and nowhere else.

Relationship to the hosts

Both host adapters live beside this package in the blablador monorepo and pin an exact version ("blablador-core": "0.1.0"), so npm install at the repo root links this package into them — no symlinks. Published hosts resolve this package from the npm registry, so the publish order when the catalog changes is: this package first, then the hosts that want the change, with both host pins bumped in the same commit as the version bump.

What was checked

npm test: 14 offline checks — catalog invariants (unique, chat-only, window > output, >= MIN_CATALOG), required ids, the none/off level spelling both hosts depend on, the merge fixture, resolveToken trimming and precedence, and outputCap on shrunken windows. The live contract runs weekly (and on demand) via .github/workflows/live.yml once a BLABLADOR_API_TOKEN repo secret is set. Note the gateway's bad-token answer is not assertable (it varies by edge-cache state), so test/api.mjs treats that path as a NOTE and proves auth only through checks that do hold.