smallm 0.5.0

package/dist/registry/ollama.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ollamaProvider = void 0;
+/** Default local Ollama REST API address — this is Ollama's standard local port. */
+const OLLAMA_API_BASE = "http://localhost:11434";
+/**
+ * Extracts a billions-of-params number from Ollama's `parameter_size`
+ * string (e.g. "7B" -> 7, "1.1B" -> 1.1). Returns null if unparseable —
+ * same "unknown, don't guess" posture as params.ts uses for HuggingFace ids.
+ */
+function parseParamsB(parameterSize) {
+    if (!parameterSize)
+        return null;
+    const match = parameterSize.match(/(\d+(?:\.\d+)?)\s*[bB]/);
+    if (!match)
+        return null;
+    const num = parseFloat(match[1]);
+    return Number.isFinite(num) ? num : null;
+}
+/**
+ * Queries a locally running Ollama installation for available models.
+ *
+ * Per the v0.4 guide's Do's/Don'ts: "handle Ollama-not-running gracefully
+ * (empty results + a clear error, not a crash)". Interpreted here as: never
+ * let a connection failure reject the whole findModels() call (that would
+ * be surprising when Ollama is just one of possibly several providers being
+ * queried) — instead, log a clear, actionable message and resolve to an
+ * empty candidate list. This mirrors the unknown-value philosophy used
+ * throughout the rest of the package: absence of data is never treated as
+ * a hard failure.
+ *
+ * Also per Do's/Don'ts: this ONLY queries what's already available locally.
+ * It never attempts to pull, install, or download a model.
+ */
+async function listOllamaModels() {
+    let response;
+    try {
+        response = await fetch(`${OLLAMA_API_BASE}/api/tags`);
+    }
+    catch {
+        console.warn(`[smallm] Could not reach local Ollama at ${OLLAMA_API_BASE} — is Ollama running? Returning no Ollama candidates.`);
+        return [];
+    }
+    if (!response.ok) {
+        console.warn(`[smallm] Local Ollama responded with status ${response.status} — returning no Ollama candidates.`);
+        return [];
+    }
+    let data;
+    try {
+        data = (await response.json());
+    }
+    catch {
+        console.warn("[smallm] Could not parse Ollama's response — returning no Ollama candidates.");
+        return [];
+    }
+    return (data.models ?? []).map((item) => ({
+        id: item.name,
+        provider: "ollama",
+        // Ollama doesn't classify models by HF-style pipeline_tag — leaving
+        // this undefined means the task hard filter treats it as "unknown,
+        // can't determine" and lets it through, same as any other missing
+        // metadata (not a provider-specific special case).
+        pipeline_tag: undefined,
+        tags: item.details?.families ?? [],
+        // Ollama's local API doesn't expose a download-count concept.
+        downloads: 0,
+        paramsB: parseParamsB(item.details?.parameter_size),
+        paramsSource: item.details?.parameter_size ? "tag" : "unknown",
+        // Ollama doesn't report context window via this endpoint either — same
+        // known limitation already flagged for HuggingFace models elsewhere.
+        contextWindow: null,
+    }));
+}
+exports.ollamaProvider = {
+    name: "ollama",
+    listCandidates: async () => listOllamaModels(),
+};
+//# sourceMappingURL=ollama.js.map

package/dist/registry/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/registry/ollama.ts"],"names":[],"mappings":";;;AAGA,oFAAoF;AACpF,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAqBjD;;;;GAIG;AACH,SAAS,YAAY,CAAC,aAAiC;IACrD,IAAI,CAAC,aAAa;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,gBAAgB;IAC7B,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,eAAe,WAAW,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CACV,4CAA4C,eAAe,uDAAuD,CACnH,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CACV,+CAA+C,QAAQ,CAAC,MAAM,oCAAoC,CACnG,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,IAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAuB,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;QAC7F,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAY,EAAE,CAAC,CAAC;QAClD,EAAE,EAAE,IAAI,CAAC,IAAI;QACb,QAAQ,EAAE,QAAQ;QAClB,oEAAoE;QACpE,mEAAmE;QACnE,kEAAkE;QAClE,mDAAmD;QACnD,YAAY,EAAE,SAAS;QACvB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE;QAClC,8DAA8D;QAC9D,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC;QACnD,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAC9D,uEAAuE;QACvE,qEAAqE;QACrE,aAAa,EAAE,IAAI;KACpB,CAAC,CAAC,CAAC;AACN,CAAC;AAEY,QAAA,cAAc,GAAa;IACtC,IAAI,EAAE,QAAQ;IACd,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,gBAAgB,EAAE;CAC/C,CAAC"}

package/dist/registry/provider.d.ts

@@ -0,0 +1,12 @@
+import { ModelQuery, RawModel, ProviderName } from "../types";
+/**
+ * A model registry that can list candidate models for a query. Both
+ * registry/huggingface.ts and registry/ollama.ts implement this. filters.ts
+ * and scorer.ts never see provider-specific shapes — only the shared
+ * RawModel — so they stay fully provider-agnostic (v0.4 Do's/Don'ts).
+ */
+export interface Provider {
+    name: ProviderName;
+    listCandidates(query: ModelQuery): Promise<RawModel[]>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/registry/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/registry/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACxD"}

package/dist/registry/provider.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=provider.js.map

package/dist/registry/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/registry/provider.ts"],"names":[],"mappings":""}

package/dist/scorer.d.ts

@@ -0,0 +1,45 @@
+import { HFModel, ModelQuery, ScoringMode } from "./types";
+export interface ScoreBreakdown {
+    task: number;
+    context: number;
+    size: number;
+    domain: number;
+    /** Weighted sum of the four components above, 0-100. */
+    total: number;
+}
+export declare function scoreModel(model: HFModel, query: ModelQuery, expectedPipelineTag: string): ScoreBreakdown;
+export declare function generateReasonWhy(breakdown: ScoreBreakdown): string;
+export interface Rankable {
+    score: number;
+    downloads: number;
+}
+/**
+ * Sort comparator: higher score first. When two scores land within
+ * TIE_THRESHOLD points of each other, break the tie by download count
+ * (higher downloads first) instead — a minor popularity signal, not a
+ * scoring component.
+ */
+export declare function compareModels(a: Rankable, b: Rankable): number;
+/** Cosine-similarity-based score (0-100) between the free-text task and the model's available text signals. */
+export declare function scoreEmbeddingSimilarity(model: HFModel, taskText: string): number;
+export interface ScoringResult {
+    /** Always computed (needed for hybrid blending and as a reference), regardless of mode. */
+    ruleBreakdown: ScoreBreakdown;
+    /** Only present when scoringMode is "embedding" or "hybrid". */
+    embeddingScore?: number;
+    /** The score actually used for ModelMatch.score, per scoringMode. */
+    finalScore: number;
+    scoringMode: ScoringMode;
+}
+/**
+ * Computes the final score for a model under the requested scoringMode.
+ * - "rule" (default): finalScore = ruleBreakdown.total, unchanged from v0.1/v0.2.
+ * - "embedding": finalScore = embeddingScore alone.
+ * - "hybrid": finalScore = ruleScore*0.60 + embeddingScore*0.40 (locked weights).
+ * Hard filters (filters.ts) run before this, identically regardless of mode —
+ * this function only ever sees candidates that already passed them.
+ */
+export declare function computeFinalScore(model: HFModel, query: ModelQuery, expectedPipelineTag: string): ScoringResult;
+/** Mode-aware reasonWhy: rule-only text for "rule", an embedding note added/substituted otherwise. */
+export declare function generateReasonWhyForResult(result: ScoringResult): string;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../src/scorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAsCD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,GAAG,cAAc,CASzG;AAID,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAwBnE;AAID,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAK9D;AAmBD,+GAA+G;AAC/G,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKjF;AAED,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,aAAa,EAAE,cAAc,CAAC;IAC9B,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,UAAU,EACjB,mBAAmB,EAAE,MAAM,GAC1B,aAAa,CAmBf;AAED,sGAAsG;AACtG,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAoBxE"}

package/dist/scorer.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreModel = scoreModel;
+exports.generateReasonWhy = generateReasonWhy;
+exports.compareModels = compareModels;
+exports.scoreEmbeddingSimilarity = scoreEmbeddingSimilarity;
+exports.computeFinalScore = computeFinalScore;
+exports.generateReasonWhyForResult = generateReasonWhyForResult;
+const embeddings_1 = require("./embeddings");
+const NEUTRAL_SCORE = 50;
+const TIE_THRESHOLD = 1;
+// ---- Component scorers (Section 4.3) ----
+/** Task match: 50% weight. Filter already guarantees compatibility or "unknown". */
+function scoreTask(model, expectedPipelineTag) {
+    if (!model.pipeline_tag)
+        return NEUTRAL_SCORE; // unknown metadata
+    return model.pipeline_tag === expectedPipelineTag ? 100 : 0;
+}
+/**
+ * Context window fit: 20% weight. contextWindow is unknown for every model
+ * in the MVP pipeline (list endpoint doesn't return it) — see index.ts notes.
+ * Formula kept general so it does the right thing once contextWindow is
+ * ever populated: exactly meeting the requirement -> 50, double or more -> 100.
+ */
+function scoreContext(model, contextLength) {
+    if (model.contextWindow == null)
+        return NEUTRAL_SCORE;
+    const ratio = model.contextWindow / contextLength; // >= 1, guaranteed by hard filter
+    const score = 50 + Math.min(1, ratio - 1) * 50;
+    return Math.min(100, Math.max(0, score));
+}
+/** Size fit: 15% weight. Closer to (without exceeding) maxParamsB scores higher. */
+function scoreSize(model, maxParamsB) {
+    if (model.paramsB == null)
+        return NEUTRAL_SCORE; // unknown metadata
+    if (maxParamsB === undefined)
+        return NEUTRAL_SCORE; // no budget constraint given
+    return Math.min(100, Math.max(0, (model.paramsB / maxParamsB) * 100));
+}
+/** Domain match: 15% weight. */
+function scoreDomain(model, domain) {
+    if (domain === undefined)
+        return NEUTRAL_SCORE; // component not requested
+    const tags = model.tags ?? [];
+    const found = tags.some((tag) => tag.toLowerCase() === domain.toLowerCase());
+    return found ? 100 : 0;
+}
+function scoreModel(model, query, expectedPipelineTag) {
+    const task = scoreTask(model, expectedPipelineTag);
+    const context = scoreContext(model, query.contextLength);
+    const size = scoreSize(model, query.maxParamsB);
+    const domain = scoreDomain(model, query.domain);
+    const total = Math.round(task * 0.5 + context * 0.2 + size * 0.15 + domain * 0.15);
+    return { task, context, size, domain, total };
+}
+// ---- reasonWhy generation (Section 4.6) ----
+function generateReasonWhy(breakdown) {
+    const parts = [];
+    if (breakdown.task >= 90)
+        parts.push("strong task match");
+    else if (breakdown.task >= 50)
+        parts.push("reasonable task fit");
+    else
+        parts.push("uncertain task fit");
+    if (breakdown.context >= 90)
+        parts.push("generous context window");
+    else if (breakdown.context >= 50)
+        parts.push("sufficient context window");
+    else
+        parts.push("tight context window");
+    if (breakdown.size >= 80)
+        parts.push("comfortably within your parameter limit");
+    else if (breakdown.size >= 50)
+        parts.push("reasonable size fit");
+    else
+        parts.push("well under your size budget");
+    if (breakdown.domain >= 90)
+        parts.push("matches your domain focus");
+    // domain omitted from sentence when neutral/not requested or unmatched —
+    // it's the least essential signal and keeps the sentence readable.
+    // Capitalize first part, join naturally.
+    const [first, ...rest] = parts;
+    const capitalized = first.charAt(0).toUpperCase() + first.slice(1);
+    if (rest.length === 0)
+        return capitalized + ".";
+    return `${capitalized}, ${rest.slice(0, -1).join(", ")}${rest.length > 1 ? ", and " : " and "}${rest[rest.length - 1]}.`;
+}
+/**
+ * Sort comparator: higher score first. When two scores land within
+ * TIE_THRESHOLD points of each other, break the tie by download count
+ * (higher downloads first) instead — a minor popularity signal, not a
+ * scoring component.
+ */
+function compareModels(a, b) {
+    if (Math.abs(a.score - b.score) <= TIE_THRESHOLD) {
+        return b.downloads - a.downloads;
+    }
+    return b.score - a.score;
+}
+// ---- v0.3: embedding-based scoring + mode blending ----
+const HYBRID_RULE_WEIGHT = 0.6;
+const HYBRID_EMBEDDING_WEIGHT = 0.4;
+/**
+ * Builds the best available free-text description of a model from what the
+ * MVP/v0.2 pipeline actually has on hand (list endpoint only — no per-model
+ * detail fetch, same limitation flagged elsewhere for contextWindow). This
+ * is an approximation, not a real model card description: id (de-slugged),
+ * pipeline_tag, and tags.
+ */
+function modelDescriptionText(model) {
+    const idWords = model.id.replace(/[/_-]/g, " ");
+    return [idWords, model.pipeline_tag ?? "", ...(model.tags ?? [])].join(" ");
+}
+/** Cosine-similarity-based score (0-100) between the free-text task and the model's available text signals. */
+function scoreEmbeddingSimilarity(model, taskText) {
+    const taskVector = (0, embeddings_1.embed)(taskText);
+    const modelVector = (0, embeddings_1.embed)(modelDescriptionText(model));
+    const similarity = (0, embeddings_1.cosineSimilarity)(taskVector, modelVector); // ~[0,1] for these non-negative vectors
+    return Math.min(100, Math.max(0, similarity * 100));
+}
+/**
+ * Computes the final score for a model under the requested scoringMode.
+ * - "rule" (default): finalScore = ruleBreakdown.total, unchanged from v0.1/v0.2.
+ * - "embedding": finalScore = embeddingScore alone.
+ * - "hybrid": finalScore = ruleScore*0.60 + embeddingScore*0.40 (locked weights).
+ * Hard filters (filters.ts) run before this, identically regardless of mode —
+ * this function only ever sees candidates that already passed them.
+ */
+function computeFinalScore(model, query, expectedPipelineTag) {
+    const mode = query.scoringMode ?? "rule";
+    const ruleBreakdown = scoreModel(model, query, expectedPipelineTag);
+    if (mode === "rule") {
+        return { ruleBreakdown, finalScore: ruleBreakdown.total, scoringMode: mode };
+    }
+    const embeddingScore = scoreEmbeddingSimilarity(model, query.task);
+    if (mode === "embedding") {
+        return { ruleBreakdown, embeddingScore, finalScore: Math.round(embeddingScore), scoringMode: mode };
+    }
+    // hybrid
+    const finalScore = Math.round(ruleBreakdown.total * HYBRID_RULE_WEIGHT + embeddingScore * HYBRID_EMBEDDING_WEIGHT);
+    return { ruleBreakdown, embeddingScore, finalScore, scoringMode: mode };
+}
+/** Mode-aware reasonWhy: rule-only text for "rule", an embedding note added/substituted otherwise. */
+function generateReasonWhyForResult(result) {
+    if (result.scoringMode === "rule") {
+        return generateReasonWhy(result.ruleBreakdown);
+    }
+    const embeddingScore = result.embeddingScore ?? 0;
+    const embeddingPhrase = embeddingScore >= 75
+        ? "strong semantic similarity to your task description"
+        : embeddingScore >= 40
+            ? "moderate semantic similarity to your task description"
+            : "weak semantic similarity to your task description";
+    if (result.scoringMode === "embedding") {
+        return embeddingPhrase.charAt(0).toUpperCase() + embeddingPhrase.slice(1) + ".";
+    }
+    // hybrid: rule-based reasoning plus the embedding signal
+    const ruleReason = generateReasonWhy(result.ruleBreakdown);
+    return `${ruleReason.slice(0, -1)}, plus ${embeddingPhrase}.`;
+}
+//# sourceMappingURL=scorer.js.map

package/dist/scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.js","sourceRoot":"","sources":["../src/scorer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Shared types for smallm.
+ * This is the LOCKED contract (see MVP guide, Section 3).
+ * Do not change shapes here without flagging it — everything else depends on this file.
+ */
+/** What the caller sends in to findModels(). */
+export interface ModelQuery {
+    /** What kind of task the model needs to do. Open string allowed for forward-compat. */
+    task: "summarize" | "classify" | "extract" | "chat" | "code" | "translate" | string;
+    /** REQUIRED. Minimum context window needed, in tokens. Treated as a HARD filter. */
+    contextLength: number;
+    /** Optional hint about target hardware. v0.4: widened to also accept a
+     *  structured HardwareSpec — existing string-enum callers keep working. */
+    hardware?: "cpu" | "gpu-low" | "gpu-high" | HardwareSpec;
+    /** Optional domain tag to prefer, e.g. "medical", "legal". Used in scoring only. */
+    domain?: string;
+    /** User-set size cutoff in billions of params, e.g. 7 = "under 7B". HARD filter. */
+    maxParamsB?: number;
+    /**
+     * RESERVED for v0.2+. Accepted on the type for API stability, but NOT
+     * scored or filtered on in MVP (HF metadata doesn't give reliable latency data).
+     */
+    maxLatencyMs?: number;
+    /** Max number of results returned. Defaults to 5 if omitted. */
+    limit?: number;
+    /**
+     * v0.2 addition, optional. Configures the file-based cache
+     * (directory + TTL). Additive — omitting it preserves v0.1 defaults.
+     */
+    cacheOptions?: CacheOptions;
+    /**
+     * v0.3 addition, optional. "rule" (default, v0.1/v0.2 behavior) uses only
+     * the weighted rule-based scorer. "embedding" scores purely on text
+     * similarity between `task` and each candidate's available text signals.
+     * "hybrid" blends both per the locked 60/40 formula (see scorer.ts).
+     * Additive — omitting it preserves prior-version behavior exactly.
+     */
+    scoringMode?: ScoringMode;
+    /**
+     * v0.4 addition, optional. Which registries to query. Defaults to
+     * ["huggingface"] when omitted — identical behavior to v0.1-v0.3.
+     */
+    providers?: ProviderName[];
+}
+/** v0.3: which scoring strategy to use. */
+export type ScoringMode = "rule" | "embedding" | "hybrid";
+/** v0.4: which registries a query can target. */
+export type ProviderName = "huggingface" | "ollama";
+/**
+ * v0.4: structured hardware spec carrying real VRAM figures, for more
+ * precise filtering than the coarse cpu/gpu-low/gpu-high enum allows.
+ * ModelQuery.hardware is WIDENED to accept this in addition to the
+ * original string enum — see that field's doc comment.
+ */
+export interface HardwareSpec {
+    type: "cpu" | "gpu";
+    vramGB?: number;
+}
+/** A single scored model returned to the caller. */
+export interface ModelMatch {
+    name: string;
+    /** v0.4: widened from the literal "huggingface" to include "ollama". */
+    provider: ProviderName;
+    /** null if size could not be detected from id/tags/config. */
+    paramsB: number | null;
+    /** null if context window could not be determined. */
+    contextWindow: number | null;
+    /** Human-readable explanation, generated from the structured score breakdown. */
+    reasonWhy: string;
+    /** 0–100 */
+    score: number;
+    /**
+     * v0.3 addition, optional. Which scoring mode actually produced this
+     * result's score — useful when a caller wants to confirm which strategy
+     * ran. Always populated in practice by findModels(), but kept optional
+     * on the type per the locked v0.3 contract (so a hand-constructed
+     * ModelMatch from older code, e.g. in a mock, still type-checks).
+     */
+    scoringMode?: ScoringMode;
+}
+/**
+ * v0.4: shared shape every Provider implementation maps its raw data into,
+ * before candidates reach filters.ts / scorer.ts. Those two files only
+ * ever see this shape — never provider-specific data — so they stay fully
+ * provider-agnostic (per the v0.4 guide's Do's/Don'ts). NOT part of the
+ * public contract.
+ */
+export interface RawModel {
+    /** Provider-specific model id, e.g. "meta-llama/Llama-3-8B-Instruct" (HF) or "llama3:8b" (Ollama). */
+    id: string;
+    /**
+     * Which provider this candidate came from. Optional rather than required
+     * purely so pre-v0.4 internal call sites/test fixtures (written before
+     * the provider abstraction existed) keep type-checking unmodified —
+     * every real Provider implementation always sets it in practice, and
+     * index.ts falls back to "huggingface" if it's ever missing.
+     */
+    provider?: ProviderName;
+    /** Task classification for the model, e.g. "text-generation". HuggingFace-specific concept; undefined for Ollama. */
+    pipeline_tag?: string;
+    /** Free-form tags — used for domain matching etc. */
+    tags?: string[];
+    /** Download count — used only for tie-breaking (Section 4.5), not scoring. HuggingFace-specific; undefined for Ollama. */
+    downloads?: number;
+    /** Filled in by params.ts after extraction. Not present on raw provider response. */
+    paramsB?: number | null;
+    /** Filled in by params.ts after extraction. Not present on raw provider response. */
+    paramsSource?: ParamsSource;
+    /** Context window in tokens, if known. May come from config data. */
+    contextWindow?: number | null;
+}
+/**
+ * Backward-compatible alias. filters.ts, scorer.ts, params.ts, and their
+ * existing tests were written against "HFModel" before the v0.4 provider
+ * abstraction existed — same shape now that HuggingFace is one of possibly
+ * several providers, so this is kept as an alias rather than forcing a
+ * rename at every call site.
+ */
+export type HFModel = RawModel;
+/**
+ * Internal-only tracking type. Explains WHERE a paramsB value came from,
+ * for debugging. Must NOT be exported from index.ts, and must NOT appear
+ * on ModelMatch.
+ */
+export type ParamsSource = "id" | "tag" | "config" | "unknown";
+/**
+ * A single measured-latency data point for a (model, hardware) pair.
+ * Shipped as a checked-in, versioned JSON dataset — not measured live.
+ */
+export interface BenchmarkEntry {
+    modelId: string;
+    hardware: "cpu" | "gpu-low" | "gpu-high";
+    avgLatencyMs: number;
+    /** ISO date string — benchmark data goes stale, so track when it was taken. */
+    measuredAt: string;
+    /** Conditions the measurement was taken under. */
+    promptTokens: number;
+    outputTokens: number;
+}
+/** Options for the v0.2 file-based cache. */
+export interface CacheOptions {
+    /** Default: OS temp dir + '/smallm-cache' */
+    dir?: string;
+    /** Default: same TTL as MVP's in-memory cache (5 minutes). */
+    ttlMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Shared types for smallm.
+ * This is the LOCKED contract (see MVP guide, Section 3).
+ * Do not change shapes here without flagging it — everything else depends on this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "smallm",
+  "version": "0.5.0",
+  "description": "Find the right small language model (SLM) for a task, based on given context. Live rule-based matching against the HuggingFace API.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "smallm": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "node -e \"try { require('fs').chmodSync('dist/cli.js', 0o755); } catch (e) {}\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "llm",
+    "slm",
+    "small-language-model",
+    "huggingface",
+    "model-selection",
+    "cli"
+  ],
+  "author": "HongZiro",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "eslint": "^10.8.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dhruvil05/smallm"
+  },
+  "bugs": {
+    "url": "https://github.com/dhruvil05/smallm/issues"
+  }
+}