@aihubmix/model-schema

The knowledge-base vocabulary layer for AIHubMix model pages. It turns capability records from the model knowledge base into the wire-only input that @aihubmix/codegen accepts, and answers "may the user tick this capability, and what should we warn them about" — nothing else.

  knowledge base  (open set: 64 capability keys and growing)
        │
        ▼   caller fetches; neither package does I/O
  @aihubmix/model-schema   ← verdict semantics, capability key → wire shape, sample values
        │
        ▼   wire vocabulary only: CodeGenCtx
  @aihubmix/codegen        ← 4 protocols × 7 languages (closed set)

The dependency is one-way. @aihubmix/codegen contains no capability key, no verdict, and no knowledge-base protocol id; its tests/vocabulary-isolation.test.ts fails if one is added. That split is the point of this package: a new capability upstream is a change here only, and @aihubmix/codegen does not need a release.

Install

pnpm add @aihubmix/model-schema @aihubmix/codegen

@aihubmix/codegen is a regular dependency, but keep exactly one copy of it in the tree — the same buildBody() must produce both the snippet you show and the request you send. Two copies compile fine and silently drift.

Usage

import { generateFromCapabilities, PROTO_TO_CANON } from '@aihubmix/model-schema';

const { code, body, used, notes, availability } = generateFromCapabilities({
  model: 'claude-opus-5',
  protocol: 'messages',
  lang: 'python',
  capabilities: ['system-instruction', 'reasoning-effort', 'function-calling'],
  baseUrl: 'https://aihubmix.com',
  // You supply the lookup. This package never reads the knowledge base itself.
  resolve: (cap, proto) => myCanonIndex[cap]?.[PROTO_TO_CANON[proto]] ?? null,
});

• code — the snippet, with a comment line prepended for any capability whose verdict says it is silently ignored upstream.
• body — the same wire body the snippet sends. Usable directly for the real request, which is what keeps the two from drifting.
• used — capabilities that actually reached body, verified by each put's landed() check rather than by "we called apply()".
• notes — machine codes plus default English wording (verdict, no-put-for-proto, missing-prerequisite, not-landed, resolver-error, …).
• availability — status for all capabilities, not just the requested ones, so a UI can render a full chip row.

resolve returning null means "no record" and the capability is left unselectable — the package does not guess. If resolve throws, only that one capability is dropped, with a resolver-error note; the rest of the generation is unaffected.

Faces (since 0.2.0)

Not every model in the knowledge base speaks one of the four protocols. TypeSafe's jev family answers typed questions about a state (POST /v1/systemone) and returns structured results — no text generation, no streaming. That is a face: a second dimension, orthogonal to CodeProto, not a fifth protocol.

import { canonFaces, canonParams, canonProtocols } from '@aihubmix/model-schema';

canonProtocols(jevDoc);            // [] — unchanged behaviour, still a closed 4-protocol set
canonFaces(jevDoc);                // [{ face: 'decision', canonProtocol: 'typesafe.systemone', … }]
canonParams(jevDoc, 'decision');   // the 6 body params of the decision face

canonProtocols() deliberately keeps returning only the four protocols, so consumers that key a Record<CodeProto, X> off its result (protocol → route, protocol → panel kind) keep working and cannot be handed an id they do not know. A model with no protocol view is a model with no chat-shaped schema — which is exactly what jev is. Adding a face touches src/faces.ts only; never add one to PROTO_TO_CANON.

Since 0.3.0 there is a second face, 'openai-decision' → openai.decisions (OpenAI Decisions, POST /v1/decisions). Its knowledge-base modality is also decision, but 'decision' was already taken by the TypeSafe face, so the new id carries a vendor prefix — matching @aihubmix/codegen's generateOpenAIDecisionCode() (0.4.0+). The two faces have different request bodies; dispatch on FaceId, never treat one as the other.

A face can sit next to the protocols on the same model. gpt-6-luna has chat / responses / messages and the openai.decisions face, so both calls return something:

canonProtocols(lunaDoc).map((v) => v.proto);        // ['chat', 'responses', 'messages'] — the chat-shaped tabs, unchanged
canonFaces(lunaDoc).map((f) => f.face);             // ['openai-decision']
canonParams(lunaDoc, 'openai-decision');            // the 4 top-level body params: safety_identifier, model, input, questions

What never overlaps is the entries: each knowledge-base protocol id lands in exactly one of the two tables.

What this package does not do

• No I/O. No network, no filesystem, no env reads. Fetching, caching, and content-addressed paths are the consumer's job — this package knows the knowledge base's vocabulary, not its transport. It must stay require()-able from a bare Node prerender script.
• No body assembly. A put only writes wire fields onto CodeGenCtx; @aihubmix/codegen's buildBody() is the sole thing that produces a body. There is no second implementation.
• No UI. Structured availability and notes come back; mapping them to chips, strikethrough, and warning banners is the consumer's.

Coverage

CAPABILITY_PUTS currently covers 11 capability keys. Where the knowledge base says a protocol supports something this package cannot yet express, the result carries a no-put-for-proto note with a written reason rather than silently omitting it — see the gap entries in src/catalog.ts.

Development

pnpm install
pnpm test:all     # typecheck + unit tests
pnpm build        # ESM + CJS + .d.ts + .d.cts

MIT.