@godspeedai/cognate-capabilities
Deterministic-first capability selection and the model provider contract for Cognate
applications. Given a requirement and a set of candidate providers, it decides — explainably
and durably — which provider to use, and it defines the plain-TypeScript ModelProvider
interface that model integrations implement.
When to use this package: you choose between multiple providers for the same capability
(for example several models) and need eligibility rules that always apply, ranking that can
never override policy, and a recorded explanation of every decision. Implementors of model
providers also need it for the ModelProvider, ModelRequest/ModelResponse, and
ModelProviderError types.
Installation
bun add @godspeedai/cognate-capabilities
Requires Bun >= 1.4.0. Recording selections needs any
@godspeedai/cognate-events
store. The SDK ships Bun-native TypeScript source, so add @types/bun and @types/node as
dev dependencies when typechecking your project.
Quick start
import { createMemoryStore } from "@godspeedai/cognate-store-memory";
import {
compatibilityRule,
createSelector,
recordSelection,
} from "@godspeedai/cognate-capabilities";
const store = createMemoryStore();
const selector = createSelector({
rules: [
compatibilityRule, // contract id, major version, and attributes must satisfy the requirement
{
id: "policy.no-cloud",
evaluate: (candidate) =>
candidate.contract.attributes?.hosting === "cloud"
? { eligible: false, reason: "tenant forbids cloud models" }
: { eligible: true, reason: "hosting allowed" },
},
],
// ranker: optional; without one, eligible providers are picked in provider-id order
});
const decision = await selector.select({
requirement: { capability: "model.generate", version: "1.0", attributes: { structured_output: true } },
candidates: [
{ providerId: "cloud-a", contract: { id: "model.generate", version: "1.2.0", attributes: { structured_output: true, hosting: "cloud" } } },
{ providerId: "local-b", contract: { id: "model.generate", version: "1.0.0", attributes: { structured_output: true } } },
],
principal: { id: "alice", kind: "user" },
tenant: "tenant-a",
});
decision.eligible; // ["local-b"] — cloud-a failed the policy rule
decision.selected; // "local-b"
decision.filters; // every (provider, rule) result with its reason
// Make the decision a durable fact with its full explanation:
await recordSelection(store, decision, { tenant: "tenant-a", scopeId: "root", correlationId: "corr-1", runId: "run-1" });
How selection works
- Eligibility first. Every
EligibilityRuleevaluates every candidate. Rules must be pure and deterministic; a candidate is eligible only if all rules pass. - Ranking second — and contained. The optional
Rankersees only the eligible set and can narrow it, never widen it. Ranker entries that are unknown, ineligible, duplicated, or non-finite are dropped. A missing or throwing ranker falls back to deterministic provider-id order, recorded indecision.fallback. With no eligible candidate,selectedisnulland the ranker is never called. - Durable feedback.
recordSelectionappends acapability.selectedevent with the full explanation;recordOutcomeappends acapability.outcomefor a recorded selection. RunoutcomeProjection()in your projection runner to derive per-capability success counts, then passcreateOutcomeRanker(store)as the selector's ranker: it scores providers by an upper-confidence-bound rule over recorded outcomes, tries untried providers first, and is deterministic — replaying the same outcomes yields the same ranking. Feedback only influences ranking after it is committed and projected.
The model provider contract
The package also defines the model integration contract every provider implements:
ModelProvider—id,model, declaredfeatures(streaming, tool use, structured output, multimodal input, context limit),generate(request)andstream(request).ModelRequest/ModelResponse/ModelDelta— messages, tools,responseFormat, and the streamed delta shapes (text,tool_call_start,tool_call_args,tool_call_end,tool_call,done).ModelProviderError— typed failure kinds:unauthorized,rate_limited,invalid_request,unavailable,cancelled,malformed_response.modelContract(provider)— theCapabilityContracta provider publishes (capability idmodel.generate, features as attributes, never credentials).
Ready-made providers:
@godspeedai/cognate-provider-local
(deterministic, offline) and
@godspeedai/cognate-provider-openai-compatible
(any OpenAI-compatible HTTP endpoint).
Limitations
- Rules and rankers are yours to write; this package guarantees containment and honest bookkeeping, not ranking quality.
- The built-in outcome ranker is a deterministic bandit heuristic over your own recorded outcomes — not a trained model — and scores are only comparable within one capability.
recordSelection/recordOutcomewrite to the store you give them; without a durable store, feedback is lost on restart.
Related packages
@godspeedai/cognate-kernel-api—Requirement,CapabilityContract, and the compatibility check used bycompatibilityRule.@godspeedai/cognate-events— the store contract for recording selections and outcomes.@godspeedai/cognate-projections— the projection runner that appliesoutcomeProjection().@godspeedai/cognate-runtime-bun— the reference runtime, which wires selection and providers together.@godspeedai/cognate— the SDK umbrella.
License
Apache-2.0