recommend

recommend() scores each model across multiple weighted dimensions and recommends the best fits for a given use case. This is what makes pickai more than a filter. See Scoring & Ranking and Purpose Profiles for the concepts behind it.

Signature

function recommend<T extends Model>(
  models: T[],
  profile: PurposeProfile,
  options?: RecommendOptions,
): ScoredModel<T>[]

Parameters

Parameter	Type	Description
models	T[]	The model array to score.
profile	PurposeProfile	Filter + weighted criteria defining the use case.
options	RecommendOptions	Optional additional filter, constraints, and limit.

RecommendOptions

interface RecommendOptions {
  filter?: ModelFilter | ((model: Model) => boolean);
  constraints?: Constraint[];
  limit?: number;
  onZeroCoverage?: (zeroCoverage: CriterionCoverage[]) => void;
}

Field	Type	Default	Description
filter	ModelFilter | function	none	Additional filter AND-combined with the profile filter.
constraints	Constraint[]	none	Selection constraints (e.g., perProvider, perFamily, perModel).
limit	number	1	Number of models to return.
onZeroCoverage	function	none	Called with the criteria that produced no data for any candidate.

Returns

ScoredModel<T>[]: models with added score (0-1) and coverage (0-1) properties, sorted by score descending. coverage is the fraction of criterion weight backed by real data for that model; below 1 means part of the score is missing data, not measured weakness.

ScoredModel<T> preserves the input type. If you pass Model[], you get ScoredModel<Model>[]. If you pass a custom type extending Model, the extra fields carry through.

Pipeline

recommend() runs five steps in order:

1. Profile filter: applies profile.filter (if any). Deprecated models are excluded by default.
2. Options filter: applies options.filter (if any), narrowing the candidates further.
3. Coverage check: criteria that produce no data for any candidate are reported through onZeroCoverage. If every criterion is in that state, recommend() throws: the ranking would be meaningless, and a silently wrong benchmark key should fail loudly.
4. Score: evaluates each candidate against profile.criteria, producing a weighted score.
5. Select: picks the top limit models, respecting any constraints.

Usage

import { fromModelsDev, recommend, Purpose, perProvider, DIRECT_PROVIDERS } from "pickai";

const models = await fromModelsDev();

// Single best model (default limit: 1)
const [best] = recommend(models, Purpose.Coding, {
  filter: { providers: [...DIRECT_PROVIDERS] },
});

// Top 5 with provider diversity
const diverse = recommend(models, Purpose.Coding, {
  filter: { providers: [...DIRECT_PROVIDERS] },
  constraints: [perProvider(1)],
  limit: 5,
});

// Narrow to a specific provider
const anthropic = recommend(models, Purpose.Balanced, {
  filter: { providers: ["anthropic"] },
  limit: 3,
});

// Returns empty array if no models match
const none = recommend(models, Purpose.Coding, {
  filter: { providers: ["nonexistent"] },
});
// => []