Adding a service kind

This page is for contributors to @lloyal-labs/rig. To use a service, see Services.

Adding a kind

Adding a service touches four places, and the compiler names whichever you skip. None of them is the installer, a boot, the registry, the config layering or the view.

The provider

A provider row is what a contributor writes, from the contract alone. Three optional cells; a row has one of the two binding cells, and derive only when a block can mean something without naming a model.

export const providers: { [K in Service]: ProviderRow<K> } = {
  reranker: {
    bind: (artifact, block) =>
      createReranker(artifact, { nCtx: block.context, instruction: block.instruction }),
  },
  vision: {
    derive: ({ llm }) => {
      if (llm.path || !llm.id) return undefined;               // bytes the catalog cannot pair
      const paired = catalogEntry("llm", llm.id)?.vision;
      return paired ? { id: paired } : undefined;
    },
    trunk: (artifact, block) =>
      ({ mmprojPath: artifact, imageMinTokens: block.minTokens, imageMaxTokens: block.maxTokens }),
  },
  embedding: {
    bind: (artifact, block) =>
      createEmbedder(artifact, { nCtx: block.context, pooling: embeddingPooling(block) }),
  },
};

block is the service’s model.<name> as the layering resolved it, typed from its keys, so a provider reads its tuning without parsing anything. The reranker row is one line; the binding it calls, createReranker, is one of the two files in the framework that open a second native context (the embedder’s, createEmbedder, is the other) and compose a runtime primitive over it, and each is its own file so a test can stand a fake at that boundary and prove the walk without loading a model. A new kind whose binding needs a different acquirer — a model that is not a .gguf in a slot — would add one more optional cell then; nothing today needs it, so it is not in the contract.

The two halves of a new kind

The promise at the top of this page ends in a dash — a judge, a projector, an encoder, a classifier, and whatever comes next — and it is worth being exact about what the contract buys for the next one. A new kind of model has two halves, which the contract keeps separate:

• The service layer — configuration, acquisition, binding, the accessor, the installer’s step, the gates. After this contract, a map line, a set of keys, a row and a catalog entry, compiler-guided.
• The native substrate — the model actually running in the runtime. Unchanged by the contract, and the part that decides whether the kind exists at all.

Embedding is the evidence for the first half: its substrate was finished first — the encoder, its pooling modes and a worked recipe in the runtime, proven against a real model — and its service came after, as a row, a binding and four keys, with nothing else in the framework touched. It is the worked example precisely because it isolates the layer this contract is about. It does not establish that a Whisper encoder costs a row, because Whisper’s substrate is the part embedding already had. The honest claim is this: a new kind used to be an arc whichever half you looked at; now the service half is a row, and the remaining question for any model is only whether it runs.

Where it lives

The contract and the platform are two sides in one package, split at the one boundary that matters: whether the code reaches the native runtime.

The split is a dependency fact, not a convention: an ability that imported the providers would drag the native addon into every context that merely constructs it — lloyal describe, a browser, a unit test — so the contract lives where those can reach and the providers where only a boot does.

A harness and its abilities draw on the same set of models, named once in harness.yml, reached by the same call, with no consumer needing to know how any of them was acquired.