smallm 0.5.0

package/dist/filters.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyHardFilters = applyHardFilters;
+const huggingface_1 = require("./registry/huggingface");
+const benchmark_1 = require("./benchmark");
+const query_1 = require("./query");
+/**
+ * (v0.4) Rough VRAM-per-billion-parameters estimate for fp16 inference,
+ * used only to translate paramsB into an estimated footprint for the
+ * HardwareSpec.vramGB filter below. The doc specifies "use vramGB when
+ * present" but no exact formula — this is a commonly-cited heuristic
+ * (~2GB VRAM per 1B params at fp16), not a measured or authoritative
+ * figure. Flagged here and in the README as an approximation.
+ */
+const ESTIMATED_GB_PER_BILLION_PARAMS = 2;
+/**
+ * Applies hard filters before any scoring happens. A model failing ANY
+ * filter is excluded outright — it never reaches scorer.ts. Unknown values
+ * never cause exclusion (MVP Section 4.4's rule, carried forward per the
+ * v0.2/v0.3/v0.4 guides' "unknown data is never punished" cross-phase
+ * principle). Provider-agnostic throughout — never branches on
+ * model.provider (v0.4 Do's/Don'ts).
+ */
+function applyHardFilters(models, query) {
+    const expectedPipelineTag = (0, huggingface_1.mapTaskToPipelineTag)(query.task);
+    return models.filter((model) => {
+        // 1. maxParamsB — known + over budget => exclude. Unknown => let through.
+        if (query.maxParamsB !== undefined &&
+            model.paramsB != null &&
+            model.paramsB > query.maxParamsB) {
+            return false;
+        }
+        // 2. contextLength — known + too small => exclude. Unknown => let through.
+        if (model.contextWindow != null && model.contextWindow < query.contextLength) {
+            return false;
+        }
+        // 3. task compatibility — pipeline_tag present but doesn't map => exclude.
+        //    Missing pipeline_tag entirely is treated as "can't determine", not excluded.
+        //    (Ollama candidates never set pipeline_tag, so they're never excluded here —
+        //    same "unknown, let through" rule, not a provider-specific carve-out.)
+        if (model.pipeline_tag && model.pipeline_tag !== expectedPipelineTag) {
+            return false;
+        }
+        // 4. (v0.2) maxLatencyMs — only enforced when benchmark data exists AND
+        //    hardware is the original string-enum form (the benchmark dataset is
+        //    keyed by that enum, not by arbitrary HardwareSpec objects). No
+        //    benchmark entry => let through, same unknown-value rule.
+        if (query.maxLatencyMs !== undefined && (0, query_1.isHardwareEnumString)(query.hardware)) {
+            const measuredLatency = (0, benchmark_1.lookupLatencyMs)(model.id, query.hardware);
+            if (measuredLatency !== null && measuredLatency > query.maxLatencyMs) {
+                return false;
+            }
+        }
+        // 5. (v0.4) HardwareSpec.vramGB — known paramsB + known vramGB budget +
+        //    estimated footprint exceeds it => exclude. Unknown paramsB, or no
+        //    vramGB given, => let through (unknown-value rule again).
+        if ((0, query_1.isHardwareSpec)(query.hardware) && query.hardware.vramGB !== undefined && model.paramsB != null) {
+            const estimatedVramGB = model.paramsB * ESTIMATED_GB_PER_BILLION_PARAMS;
+            if (estimatedVramGB > query.hardware.vramGB) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=filters.js.map

package/dist/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":";;;AACA,wDAA8D;AAC9D,2CAA8C;AAC9C,mCAA+D;AAE/D;;;;;;;GAOG;AACH,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAE1C;;;;;;;GAOG;AACH,0BAAiC,MAAiB,EAAE,KAAiB;IACnE,MAAM,mBAAmB,GAAG,IAAA,kCAAoB,EAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC7B,0EAA0E;QAC1E,IACE,KAAK,CAAC,UAAU,KAAK,SAAS;YAC9B,KAAK,CAAC,OAAO,IAAI,IAAI;YACrB,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,UAAU,EAChC,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,2EAA2E;QAC3E,IAAI,KAAK,CAAC,aAAa,IAAI,IAAI,IAAI,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;YAC7E,OAAO,KAAK,CAAC;QACf,CAAC;QAED,2EAA2E;QAC3E,kFAAkF;QAClF,iFAAiF;QACjF,2EAA2E;QAC3E,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,KAAK,mBAAmB,EAAE,CAAC;YACrE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,oEAAoE;QACpE,8DAA8D;QAC9D,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,IAAI,IAAA,4BAAoB,EAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7E,MAAM,eAAe,GAAG,IAAA,2BAAe,EAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YAClE,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;gBACrE,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,wEAAwE;QACxE,uEAAuE;QACvE,8DAA8D;QAC9D,IAAI,IAAA,sBAAc,EAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YACnG,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,GAAG,+BAA+B,CAAC;YACxE,IAAI,eAAe,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC5C,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { ModelQuery, ModelMatch } from "./types";
+/**
+ * Finds and ranks models matching the given query, across one or more
+ * providers (HuggingFace by default; optionally Ollama as of v0.4).
+ *
+ * Pipeline (locked order, per MVP guide Section 5, Step 8 — unchanged since MVP):
+ *   validate -> fetch -> hard-filter -> score -> tie-break -> sort -> limit -> return
+ *
+ * v0.4 changes (see post-MVP guide):
+ *   - New optional `providers` field: which registries to query. Defaults
+ *     to ["huggingface"] — identical behavior to v0.1-v0.3 when omitted.
+ *   - The FETCH step now fans out to every requested provider in parallel
+ *     and merges their RawModel[] results before hard-filtering — filters.ts
+ *     and scorer.ts never see provider-specific shapes or branch on
+ *     provider name (v0.4 Do's/Don'ts).
+ *   - `hardware` is widened to optionally accept a structured HardwareSpec
+ *     ({ type, vramGB? }) alongside the original string enum. When vramGB
+ *     is given, filters.ts applies an estimated-footprint hard filter
+ *     (see that file for the heuristic and its caveats).
+ *   - Ollama being unreachable never fails the whole call — see
+ *     registry/ollama.ts for the graceful-degradation behavior.
+ *
+ * v0.3 changes (see post-MVP guide):
+ *   - New optional `scoringMode`: "rule" (default, unchanged v0.1/v0.2
+ *     behavior) | "embedding" | "hybrid". Only the SCORE step changes
+ *     between modes — hard filters (step 3) run identically regardless of
+ *     scoringMode, per the "filters stay mode-agnostic" cross-phase
+ *     principle. See scorer.ts's computeFinalScore for the per-mode logic.
+ *   - "embedding" mode uses a local, dependency-free text-similarity
+ *     scorer (embeddings.ts) instead of a downloaded neural model — see
+ *     that file's docblock for why, and the trade-off involved.
+ *
+ * v0.2 changes (see post-MVP guide):
+ *   - fetch is now backed by a file-based cache (cache-file.ts) instead of
+ *     MVP's in-memory Map, so repeated queries survive process restarts.
+ *   - maxLatencyMs is now a real hard filter when both it and the original
+ *     string-form `hardware` are provided AND a benchmark entry exists for
+ *     that (model, hardware) pair (see filters.ts, benchmark.ts). Still
+ *     unenforced otherwise — unknown values are never punished.
+ *   - HuggingFace fetch failures now retry transient errors (429/5xx) with
+ *     backoff before throwing a typed SmallmError subclass (errors.ts).
+ *
+ * Known MVP-era limitation, still present through v0.4: candidate models
+ * from HuggingFace come only from its list endpoint, which does not return
+ * context-window data, so `contextWindow` stays null/unknown for those
+ * models and the context-fit score component stays neutral (50). Not part
+ * of any shipped phase's scope yet — tracked as a future addition.
+ */
+export declare function findModels(query: ModelQuery): Promise<ModelMatch[]>;
+export type { ModelQuery, ModelMatch } from "./types";
+export { SmallmError, HFApiError, RateLimitError, ValidationError } from "./errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAA0B,MAAM,SAAS,CAAC;AAgBzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAmDzE;AAKD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAKtD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.RateLimitError = exports.HFApiError = exports.SmallmError = void 0;
+exports.findModels = findModels;
+const query_1 = require("./query");
+const cache_file_1 = require("./cache-file");
+const params_1 = require("./params");
+const filters_1 = require("./filters");
+const scorer_1 = require("./scorer");
+const huggingface_1 = require("./registry/huggingface");
+const ollama_1 = require("./registry/ollama");
+/** (v0.4) Registry of known providers, keyed by name, for the fan-out step below. */
+const PROVIDERS = {
+    huggingface: huggingface_1.huggingfaceProvider,
+    ollama: ollama_1.ollamaProvider,
+};
+/**
+ * Finds and ranks models matching the given query, across one or more
+ * providers (HuggingFace by default; optionally Ollama as of v0.4).
+ *
+ * Pipeline (locked order, per MVP guide Section 5, Step 8 — unchanged since MVP):
+ *   validate -> fetch -> hard-filter -> score -> tie-break -> sort -> limit -> return
+ *
+ * v0.4 changes (see post-MVP guide):
+ *   - New optional `providers` field: which registries to query. Defaults
+ *     to ["huggingface"] — identical behavior to v0.1-v0.3 when omitted.
+ *   - The FETCH step now fans out to every requested provider in parallel
+ *     and merges their RawModel[] results before hard-filtering — filters.ts
+ *     and scorer.ts never see provider-specific shapes or branch on
+ *     provider name (v0.4 Do's/Don'ts).
+ *   - `hardware` is widened to optionally accept a structured HardwareSpec
+ *     ({ type, vramGB? }) alongside the original string enum. When vramGB
+ *     is given, filters.ts applies an estimated-footprint hard filter
+ *     (see that file for the heuristic and its caveats).
+ *   - Ollama being unreachable never fails the whole call — see
+ *     registry/ollama.ts for the graceful-degradation behavior.
+ *
+ * v0.3 changes (see post-MVP guide):
+ *   - New optional `scoringMode`: "rule" (default, unchanged v0.1/v0.2
+ *     behavior) | "embedding" | "hybrid". Only the SCORE step changes
+ *     between modes — hard filters (step 3) run identically regardless of
+ *     scoringMode, per the "filters stay mode-agnostic" cross-phase
+ *     principle. See scorer.ts's computeFinalScore for the per-mode logic.
+ *   - "embedding" mode uses a local, dependency-free text-similarity
+ *     scorer (embeddings.ts) instead of a downloaded neural model — see
+ *     that file's docblock for why, and the trade-off involved.
+ *
+ * v0.2 changes (see post-MVP guide):
+ *   - fetch is now backed by a file-based cache (cache-file.ts) instead of
+ *     MVP's in-memory Map, so repeated queries survive process restarts.
+ *   - maxLatencyMs is now a real hard filter when both it and the original
+ *     string-form `hardware` are provided AND a benchmark entry exists for
+ *     that (model, hardware) pair (see filters.ts, benchmark.ts). Still
+ *     unenforced otherwise — unknown values are never punished.
+ *   - HuggingFace fetch failures now retry transient errors (429/5xx) with
+ *     backoff before throwing a typed SmallmError subclass (errors.ts).
+ *
+ * Known MVP-era limitation, still present through v0.4: candidate models
+ * from HuggingFace come only from its list endpoint, which does not return
+ * context-window data, so `contextWindow` stays null/unknown for those
+ * models and the context-fit score component stays neutral (50). Not part
+ * of any shipped phase's scope yet — tracked as a future addition.
+ */
+async function findModels(query) {
+    // 1. validate
+    const validated = (0, query_1.validateQuery)(query);
+    // (v0.2) apply per-call cache options, if provided, before the fetch step.
+    if (validated.cacheOptions) {
+        (0, cache_file_1.configureCandidateModelsCache)(validated.cacheOptions);
+    }
+    // 2. fetch — (v0.4) fan out to every requested provider, cached per
+    //    (provider, task) pair, then merge before anything downstream sees them.
+    const providerLists = await Promise.all(validated.providers.map((providerName) => {
+        const provider = PROVIDERS[providerName];
+        return (0, cache_file_1.getOrFetchCached)(`${provider.name}:${validated.task}`, () => provider.listCandidates(validated));
+    }));
+    const rawCandidates = providerLists.flat();
+    const enriched = (0, params_1.enrichWithParams)(rawCandidates);
+    // 3. hard-filter — mode-agnostic and provider-agnostic, runs identically regardless of scoringMode/providers
+    const filtered = (0, filters_1.applyHardFilters)(enriched, validated);
+    // 4. score — mode-aware as of v0.3 (rule / embedding / hybrid)
+    const expectedPipelineTag = (0, huggingface_1.mapTaskToPipelineTag)(validated.task);
+    const scored = filtered.map((model) => ({
+        model,
+        result: (0, scorer_1.computeFinalScore)(model, validated, expectedPipelineTag),
+    }));
+    // 5. tie-break + 6. sort (single stable sort using the tie-break-aware comparator)
+    scored.sort((a, b) => (0, scorer_1.compareModels)({ score: a.result.finalScore, downloads: a.model.downloads ?? 0 }, { score: b.result.finalScore, downloads: b.model.downloads ?? 0 }));
+    // 7. limit
+    const top = scored.slice(0, validated.limit);
+    // 8. return — map to the public ModelMatch shape
+    return top.map(({ model, result }) => ({
+        name: model.id,
+        provider: model.provider ?? "huggingface",
+        paramsB: model.paramsB ?? null,
+        contextWindow: model.contextWindow ?? null,
+        reasonWhy: (0, scorer_1.generateReasonWhyForResult)(result),
+        score: result.finalScore,
+        scoringMode: result.scoringMode,
+    }));
+}
+// (v0.2) Public error exports — additive. Lets consumers do
+// `catch (e) { if (e instanceof ValidationError) ... }` without reaching
+// into internal modules.
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "SmallmError", { enumerable: true, get: function () { return errors_1.SmallmError; } });
+Object.defineProperty(exports, "HFApiError", { enumerable: true, get: function () { return errors_1.HFApiError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/params.d.ts

@@ -0,0 +1,21 @@
+import { HFModel, ParamsSource } from "./types";
+export interface ParamsExtractionResult {
+    paramsB: number | null;
+    paramsSource: ParamsSource;
+}
+/**
+ * Extracts a billions-of-params estimate for a model, trying id first,
+ * then tags. Config-based extraction ("config" source) would require
+ * fetching per-model detail, which the MVP pipeline does not do
+ * (see index.ts notes) — so "config" is defined in ParamsSource for
+ * forward-compat but never produced in MVP.
+ *
+ * Known limitation: sub-billion models (e.g. "opt-125m") are not detected
+ * since we only match the B suffix. They correctly fall through to
+ * "unknown" rather than being misread, which is the safe failure mode
+ * per the Unknown-Value Rule.
+ */
+export declare function extractParamsB(model: HFModel): ParamsExtractionResult;
+/** Applies extraction to a full list, returning enriched copies (does not mutate input). */
+export declare function enrichWithParams(models: HFModel[]): HFModel[];
+//# sourceMappingURL=params.d.ts.map

package/dist/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../src/params.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAShD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,YAAY,CAAC;CAC5B;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAcrE;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAK7D"}

package/dist/params.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractParamsB = extractParamsB;
+exports.enrichWithParams = enrichWithParams;
+/**
+ * Matches patterns like "7B", "13b", "1.1B", "70B-Instruct".
+ * Requires a digit immediately before the B/b, and no letter/digit right after,
+ * so we don't accidentally match things like "Bert" or "B16".
+ */
+const PARAM_REGEX = /(\d+(?:\.\d+)?)[\-_]?[bB](?![a-zA-Z0-9])/;
+function extractFromString(value, regex) {
+    const match = value.match(regex);
+    if (!match)
+        return null;
+    const num = parseFloat(match[1]);
+    return Number.isFinite(num) ? num : null;
+}
+/**
+ * Extracts a billions-of-params estimate for a model, trying id first,
+ * then tags. Config-based extraction ("config" source) would require
+ * fetching per-model detail, which the MVP pipeline does not do
+ * (see index.ts notes) — so "config" is defined in ParamsSource for
+ * forward-compat but never produced in MVP.
+ *
+ * Known limitation: sub-billion models (e.g. "opt-125m") are not detected
+ * since we only match the B suffix. They correctly fall through to
+ * "unknown" rather than being misread, which is the safe failure mode
+ * per the Unknown-Value Rule.
+ */
+function extractParamsB(model) {
+    const fromId = extractFromString(model.id, PARAM_REGEX);
+    if (fromId !== null) {
+        return { paramsB: fromId, paramsSource: "id" };
+    }
+    for (const tag of model.tags ?? []) {
+        const fromTag = extractFromString(tag, PARAM_REGEX);
+        if (fromTag !== null) {
+            return { paramsB: fromTag, paramsSource: "tag" };
+        }
+    }
+    return { paramsB: null, paramsSource: "unknown" };
+}
+/** Applies extraction to a full list, returning enriched copies (does not mutate input). */
+function enrichWithParams(models) {
+    return models.map((model) => {
+        const { paramsB, paramsSource } = extractParamsB(model);
+        return { ...model, paramsB, paramsSource };
+    });
+}
+//# sourceMappingURL=params.js.map

package/dist/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../src/params.ts"],"names":[],"mappings":";;;;AAEA;;;;GAIG;AACH,MAAM,WAAW,GAAG,0CAA0C,CAAC;AAO/D,SAAS,iBAAiB,CAAC,KAAa,EAAE,KAAa;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,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;;;;;;;;;;;GAWG;AACH,wBAA+B,KAAc;IAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IACxD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACpD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC;AAED,4FAA4F;AAC5F,0BAAiC,MAAiB;IAChD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1B,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACxD,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,23 @@
+import { ModelQuery, ScoringMode, ProviderName, HardwareSpec } from "./types";
+import { ValidationError } from "./errors";
+/** True for the original v0.1-v0.3 hardware string enum. */
+export declare function isHardwareEnumString(hardware: unknown): hardware is "cpu" | "gpu-low" | "gpu-high";
+/** True for the v0.4 structured HardwareSpec form. */
+export declare function isHardwareSpec(hardware: unknown): hardware is HardwareSpec;
+/**
+ * Backward-compatible alias. As of v0.2, query validation throws the typed
+ * ValidationError (a SmallmError subclass, see errors.ts) — this name is
+ * kept so any existing `catch (e) { if (e instanceof InvalidQueryError) }`
+ * code from v0.1 keeps working unchanged (it's the same class, not a copy).
+ */
+export { ValidationError as InvalidQueryError };
+/**
+ * Validates a raw ModelQuery and returns a normalized copy
+ * (limit defaulted to 5 if omitted). Throws InvalidQueryError on bad input.
+ */
+export declare function validateQuery(query: ModelQuery): ModelQuery & {
+    limit: number;
+    scoringMode: ScoringMode;
+    providers: ProviderName[];
+};
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAU3C,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,GAChB,QAAQ,IAAI,KAAK,GAAG,SAAS,GAAG,UAAU,CAE5C;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,YAAY,CAE1E;AAED;;;;;GAKG;AACH,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,GAChB,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,YAAY,EAAE,CAAA;CAAE,CAgErF"}

package/dist/query.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidQueryError = void 0;
+exports.isHardwareEnumString = isHardwareEnumString;
+exports.isHardwareSpec = isHardwareSpec;
+exports.validateQuery = validateQuery;
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "InvalidQueryError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+const VALID_HARDWARE = new Set(["cpu", "gpu-low", "gpu-high"]);
+const VALID_SCORING_MODES = new Set(["rule", "embedding", "hybrid"]);
+const VALID_PROVIDERS = new Set(["huggingface", "ollama"]);
+const VALID_HARDWARE_SPEC_TYPES = new Set(["cpu", "gpu"]);
+const DEFAULT_LIMIT = 5;
+const DEFAULT_SCORING_MODE = "rule";
+const DEFAULT_PROVIDERS = ["huggingface"];
+/** True for the original v0.1-v0.3 hardware string enum. */
+function isHardwareEnumString(hardware) {
+    return typeof hardware === "string" && VALID_HARDWARE.has(hardware);
+}
+/** True for the v0.4 structured HardwareSpec form. */
+function isHardwareSpec(hardware) {
+    return typeof hardware === "object" && hardware !== null && "type" in hardware;
+}
+/**
+ * Validates a raw ModelQuery and returns a normalized copy
+ * (limit defaulted to 5 if omitted). Throws InvalidQueryError on bad input.
+ */
+function validateQuery(query) {
+    if (!query || typeof query !== "object") {
+        throw new errors_1.ValidationError("query must be an object");
+    }
+    if (typeof query.task !== "string" || query.task.trim() === "") {
+        throw new errors_1.ValidationError("query.task is required and must be a non-empty string");
+    }
+    if (typeof query.contextLength !== "number" || !Number.isFinite(query.contextLength) || query.contextLength <= 0) {
+        throw new errors_1.ValidationError("query.contextLength is required and must be a positive number");
+    }
+    if (query.hardware !== undefined && !isHardwareEnumString(query.hardware) && !isHardwareSpec(query.hardware)) {
+        throw new errors_1.ValidationError(`query.hardware must be one of: ${[...VALID_HARDWARE].join(", ")}, or a { type, vramGB? } object`);
+    }
+    if (isHardwareSpec(query.hardware)) {
+        if (!VALID_HARDWARE_SPEC_TYPES.has(query.hardware.type)) {
+            throw new errors_1.ValidationError(`query.hardware.type must be one of: ${[...VALID_HARDWARE_SPEC_TYPES].join(", ")}`);
+        }
+        if (query.hardware.vramGB !== undefined && (typeof query.hardware.vramGB !== "number" || query.hardware.vramGB <= 0)) {
+            throw new errors_1.ValidationError("query.hardware.vramGB must be a positive number when provided");
+        }
+    }
+    if (query.domain !== undefined && (typeof query.domain !== "string" || query.domain.trim() === "")) {
+        throw new errors_1.ValidationError("query.domain must be a non-empty string when provided");
+    }
+    if (query.maxParamsB !== undefined && (typeof query.maxParamsB !== "number" || query.maxParamsB <= 0)) {
+        throw new errors_1.ValidationError("query.maxParamsB must be a positive number when provided");
+    }
+    if (query.maxLatencyMs !== undefined && (typeof query.maxLatencyMs !== "number" || query.maxLatencyMs <= 0)) {
+        throw new errors_1.ValidationError("query.maxLatencyMs must be a positive number when provided");
+    }
+    if (query.limit !== undefined && (typeof query.limit !== "number" || !Number.isInteger(query.limit) || query.limit <= 0)) {
+        throw new errors_1.ValidationError("query.limit must be a positive integer when provided");
+    }
+    if (query.scoringMode !== undefined && !VALID_SCORING_MODES.has(query.scoringMode)) {
+        throw new errors_1.ValidationError(`query.scoringMode must be one of: ${[...VALID_SCORING_MODES].join(", ")}`);
+    }
+    if (query.providers !== undefined) {
+        if (!Array.isArray(query.providers) || query.providers.length === 0) {
+            throw new errors_1.ValidationError("query.providers must be a non-empty array when provided");
+        }
+        for (const p of query.providers) {
+            if (!VALID_PROVIDERS.has(p)) {
+                throw new errors_1.ValidationError(`query.providers entries must be one of: ${[...VALID_PROVIDERS].join(", ")}`);
+            }
+        }
+    }
+    return {
+        ...query,
+        limit: query.limit ?? DEFAULT_LIMIT,
+        scoringMode: query.scoringMode ?? DEFAULT_SCORING_MODE,
+        providers: query.providers ?? DEFAULT_PROVIDERS,
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

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

package/dist/registry/huggingface.d.ts

@@ -0,0 +1,24 @@
+import { HFModel } from "../types";
+import { HFApiError } from "../errors";
+import { Provider } from "./provider";
+/** Backward-compatible alias — v0.1 threw this name; v0.2 throws the same class under a new name. */
+export { HFApiError as HuggingFaceApiError };
+export declare function mapTaskToPipelineTag(task: string): string;
+/**
+ * Fetches candidate models from HuggingFace for a given task.
+ * No API key required (public search endpoint, per docx 6.3).
+ *
+ * (v0.2) Retries transient failures (429 / 5xx) up to MAX_RETRIES times with
+ * exponential backoff (500ms, 1000ms, 2000ms). Non-transient failures
+ * (4xx other than 429) are thrown immediately — retrying them can't help.
+ * All thrown errors are typed SmallmError subclasses (see errors.ts).
+ */
+export declare function fetchCandidateModels(task: string): Promise<HFModel[]>;
+/**
+ * (v0.4) Provider implementation wrapping fetchCandidateModels — no behavior
+ * change to the underlying fetch/retry/error logic above, this just adapts
+ * the existing function to the shared Provider interface so index.ts can
+ * treat HuggingFace the same way it treats every other provider.
+ */
+export declare const huggingfaceProvider: Provider;
+//# sourceMappingURL=huggingface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"huggingface.d.ts","sourceRoot":"","sources":["../../src/registry/huggingface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,UAAU,EAAkB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOtC,qGAAqG;AACrG,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,CAAC;AA6B7C,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAsCD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAyB3E;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAGjC,CAAC"}

package/dist/registry/huggingface.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.huggingfaceProvider = exports.HuggingFaceApiError = void 0;
+exports.mapTaskToPipelineTag = mapTaskToPipelineTag;
+exports.fetchCandidateModels = fetchCandidateModels;
+const errors_1 = require("../errors");
+Object.defineProperty(exports, "HuggingFaceApiError", { enumerable: true, get: function () { return errors_1.HFApiError; } });
+const HF_API_BASE = "https://huggingface.co/api/models";
+/** Number of candidates to pull per query, per docx 6.3: fixed fetch limit, no pagination in MVP. */
+const FETCH_LIMIT = 50;
+/** (v0.2) Retry policy: cap at 3 attempts, exponential backoff, only for transient failures. */
+const MAX_RETRIES = 3;
+const BACKOFF_SCHEDULE_MS = [500, 1000, 2000];
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** True for 429 (rate limit) and any 5xx — the only cases worth retrying. */
+function isTransient(status) {
+    return status === 429 || (status >= 500 && status < 600);
+}
+/**
+ * Maps our public `task` values to HuggingFace's pipeline_tag vocabulary.
+ * Unknown/custom task strings pass through unchanged so query.task can
+ * still be a free string per the contract.
+ */
+const TASK_TO_PIPELINE_TAG = {
+    summarize: "summarization",
+    classify: "text-classification",
+    extract: "token-classification",
+    chat: "text-generation",
+    code: "text-generation",
+    translate: "translation",
+};
+function mapTaskToPipelineTag(task) {
+    return TASK_TO_PIPELINE_TAG[task] ?? task;
+}
+/** A single fetch attempt — no retry logic here, that lives in fetchCandidateModels. */
+async function fetchOnce(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        if (response.status === 429) {
+            throw new errors_1.RateLimitError(`HuggingFace API rate-limited the request (429)`);
+        }
+        throw new errors_1.HFApiError(`HuggingFace API request failed with status ${response.status}`, response.status);
+    }
+    const data = (await response.json());
+    return data.map((item) => ({
+        id: item.id,
+        provider: "huggingface",
+        pipeline_tag: item.pipeline_tag,
+        tags: item.tags ?? [],
+        downloads: item.downloads ?? 0,
+    }));
+}
+/**
+ * Fetches candidate models from HuggingFace for a given task.
+ * No API key required (public search endpoint, per docx 6.3).
+ *
+ * (v0.2) Retries transient failures (429 / 5xx) up to MAX_RETRIES times with
+ * exponential backoff (500ms, 1000ms, 2000ms). Non-transient failures
+ * (4xx other than 429) are thrown immediately — retrying them can't help.
+ * All thrown errors are typed SmallmError subclasses (see errors.ts).
+ */
+async function fetchCandidateModels(task) {
+    const pipelineTag = mapTaskToPipelineTag(task);
+    const url = `${HF_API_BASE}?pipeline_tag=${encodeURIComponent(pipelineTag)}&limit=${FETCH_LIMIT}&sort=downloads&direction=-1`;
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            return await fetchOnce(url);
+        }
+        catch (err) {
+            if (!(err instanceof errors_1.HFApiError))
+                throw err; // unexpected error shape — don't swallow it
+            const status = err.status ?? 0;
+            const canRetry = isTransient(status) && attempt < MAX_RETRIES;
+            lastError = err;
+            if (!canRetry)
+                throw err;
+            await sleep(BACKOFF_SCHEDULE_MS[attempt]);
+        }
+    }
+    // Unreachable in practice (the loop always returns or throws), but keeps TS happy
+    // and gives a sane fallback if MAX_RETRIES were ever set to a negative number.
+    throw lastError ?? new errors_1.HFApiError("HuggingFace API request failed with no response");
+}
+/**
+ * (v0.4) Provider implementation wrapping fetchCandidateModels — no behavior
+ * change to the underlying fetch/retry/error logic above, this just adapts
+ * the existing function to the shared Provider interface so index.ts can
+ * treat HuggingFace the same way it treats every other provider.
+ */
+exports.huggingfaceProvider = {
+    name: "huggingface",
+    listCandidates: (query) => fetchCandidateModels(query.task),
+};
+//# sourceMappingURL=huggingface.js.map

package/dist/registry/huggingface.js.map

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

package/dist/registry/ollama.d.ts

@@ -0,0 +1,3 @@
+import { Provider } from "./provider";
+export declare const ollamaProvider: Provider;
+//# sourceMappingURL=ollama.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.d.ts","sourceRoot":"","sources":["../../src/registry/ollama.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiGtC,eAAO,MAAM,cAAc,EAAE,QAG5B,CAAC"}