smallm 0.5.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# smallm
+
+Find the right small language model (SLM) for a task, based on given context.
+
+`smallm` does a **live lookup against the HuggingFace public API** and runs a **rule-based scoring engine** (task match, size fit, context window, domain tag) to rank candidates — no embeddings, no local registry, no config files.
+
+## Install
+
+```bash
+npm install smallm
+```
+
+## Usage
+
+```ts
+import { findModels } from "smallm";
+
+const results = await findModels({
+  task: "chat",           // "summarize" | "classify" | "extract" | "chat" | "code" | "translate" | string
+  contextLength: 8192,    // required — hard filter, in tokens
+  maxParamsB: 7,           // optional — hard filter, "under 7B"
+  domain: "medical",       // optional — used in scoring only
+  hardware: "gpu-low",     // optional — required (along with maxLatencyMs) to enforce latency
+  maxLatencyMs: 2000,       // optional — v0.2: real hard filter when benchmark data exists
+  scoringMode: "rule",       // optional — v0.3: "rule" (default) | "embedding" | "hybrid"
+  limit: 5,                   // optional — defaults to 5
+});
+
+console.log(results);
+// [
+//   {
+//     name: "org/some-7b-chat-model",
+//     provider: "huggingface",
+//     paramsB: 6.5,
+//     contextWindow: null,          // see "Known limitations" below
+//     reasonWhy: "Strong task match, sufficient context window, and comfortably within your parameter limit.",
+//     score: 87,
+//     scoringMode: "rule"
+//   },
+//   ...
+// ]
+```
+
+### Multi-provider (v0.4)
+
+```ts
+// Query a locally running Ollama installation instead of (or alongside) HuggingFace.
+await findModels({ task: "chat", contextLength: 4096, providers: ["ollama"] });
+await findModels({ task: "chat", contextLength: 4096, providers: ["huggingface", "ollama"] });
+
+// Structured hardware — widened, not replacing the original string enum.
+await findModels({ task: "chat", contextLength: 4096, hardware: { type: "gpu", vramGB: 8 } });
+await findModels({ task: "chat", contextLength: 4096, hardware: "gpu-low" }); // still works
+```
+
+**Prerequisite for `providers: ["ollama"]`:** Ollama must be running locally (`ollama serve`, or the desktop app) and reachable at `http://localhost:11434`. If it isn't, `smallm` doesn't throw or crash the whole call — it logs a warning and simply returns no Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns your HuggingFace results.
+
+**Important:** `HardwareSpec.vramGB` filtering uses an **estimated** footprint (~2GB VRAM per 1B params, a common fp16 rule of thumb) — not a measured or authoritative figure. It's meant to rule out obviously-too-large models, not to guarantee something fits.
+
+### Scoring modes (v0.3)
+
+```ts
+// Default — identical to v0.1/v0.2 behavior. Matches on exact task/pipeline_tag mapping.
+await findModels({ task: "chat", contextLength: 4096, scoringMode: "rule" });
+
+// Scores purely on text similarity between your task string and each model's
+// available text (id, pipeline_tag, tags) — useful for free-text tasks that
+// don't map neatly onto the fixed task enum.
+await findModels({ task: "pull key dates and amounts from scanned invoices", contextLength: 4096, scoringMode: "embedding" });
+
+// Blends both: hybridScore = ruleScore * 0.60 + embeddingScore * 0.40 (locked weights — rule score still dominates).
+await findModels({ task: "chat", contextLength: 4096, scoringMode: "hybrid" });
+```
+
+### Multi-provider + structured hardware (v0.4)
+
+```ts
+// Query Ollama's locally installed models instead of (or alongside) HuggingFace.
+// Requires a running local Ollama installation — see "Ollama prerequisite" below.
+await findModels({ task: "chat", contextLength: 4096, providers: ["ollama"] });
+
+await findModels({ task: "chat", contextLength: 4096, providers: ["huggingface", "ollama"] });
+
+// Structured hardware spec — widens (doesn't replace) the original string enum.
+await findModels({
+  task: "chat",
+  contextLength: 4096,
+  hardware: { type: "gpu", vramGB: 8 }, // excludes models estimated to not fit
+});
+
+// Old string-enum form still works exactly as before:
+await findModels({ task: "chat", contextLength: 4096, hardware: "gpu-low" });
+```
+
+**Ollama prerequisite:** `providers: ["ollama"]` (or including `"ollama"` in a multi-provider list) expects a local Ollama installation running at `http://localhost:11434`. If it's not running or not installed, `smallm` doesn't throw or crash the whole query — it logs a warning and simply contributes zero Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns HuggingFace results normally. Ollama itself is never installed, started, or asked to download models by this package — it only queries what's already available locally.
+
+**`vramGB` filtering is a heuristic, not a measured constraint.** There's no standard "how much VRAM does model X need" figure available from either provider's listing API, so `smallm` estimates it from `paramsB` using a commonly-cited rule of thumb (~2GB VRAM per 1B parameters, roughly fp16 inference). A model quantized to 4-bit would actually need much less — this estimate is conservative/pessimistic in that case. Treat `vramGB` filtering as a rough guide, not a guarantee.
+
+### Handling errors (v0.2)
+
+```ts
+import { findModels, ValidationError, RateLimitError, HFApiError } from "smallm";
+
+try {
+  await findModels({ task: "chat", contextLength: 4096 });
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // your query was malformed — fix it, retrying won't help
+  } else if (err instanceof RateLimitError) {
+    // HuggingFace rate-limited us — smallm already retried 3x with backoff before this threw
+  } else if (err instanceof HFApiError) {
+    // some other non-2xx from HuggingFace
+  }
+}
+```
+
+## API
+
+### `findModels(query: ModelQuery): Promise<ModelMatch[]>`
+
+The single public entry point. Validates the query, fetches live candidates from HuggingFace (cached, retrying transient failures), applies hard filters, scores and ranks the survivors, and returns the top N.
+
+### `ModelQuery`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `task` | `"summarize" \| "classify" \| "extract" \| "chat" \| "code" \| "translate" \| string` | yes | |
+| `contextLength` | `number` | yes | Hard filter (tokens) |
+| `hardware` | `"cpu" \| "gpu-low" \| "gpu-high" \| { type: "cpu" \| "gpu"; vramGB?: number }` | no | String enum: required alongside `maxLatencyMs` to enforce latency filtering (v0.2). Object form (v0.4): `vramGB` enables the estimated-footprint hard filter. |
+| `domain` | `string` | no | Used in scoring, not filtering |
+| `maxParamsB` | `number` | no | Hard filter, e.g. `7` = "under 7B" |
+| `maxLatencyMs` | `number` | no | **v0.2:** real hard filter when a benchmark entry exists for the (model, string-enum `hardware`) pair. No entry = not enforced. |
+| `scoringMode` | `"rule" \| "embedding" \| "hybrid"` | no | **v0.3:** which scoring strategy to use. Defaults to `"rule"`. |
+| `providers` | `("huggingface" \| "ollama")[]` | no | **v0.4:** which registries to query. Defaults to `["huggingface"]`. |
+| `limit` | `number` | no | Defaults to `5` |
+| `cacheOptions` | `{ dir?: string; ttlMs?: number }` | no | **v0.2:** configure the file-based cache. Defaults: OS temp dir + `/smallm-cache`, 5-minute TTL |
+
+### `ModelMatch`
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | `string` | Provider-specific model id |
+| `provider` | `"huggingface" \| "ollama"` | **v0.4:** widened from the literal `"huggingface"` |
+| `paramsB` | `number \| null` | `null` if size couldn't be detected |
+| `contextWindow` | `number \| null` | `null` if unknown (see limitations) |
+| `reasonWhy` | `string` | Generated from the scoring breakdown |
+| `score` | `number` | 0–100 |
+| `scoringMode` | `"rule" \| "embedding" \| "hybrid"` | **v0.3:** which mode produced this result's score |
+
+### Errors (v0.2)
+
+All thrown errors extend `SmallmError`:
+
+- `ValidationError` — bad `ModelQuery` input. Never retried.
+- `HFApiError` — non-2xx response from HuggingFace (base class; carries `.status`).
+- `RateLimitError` — `HFApiError` subclass specifically for HTTP 429.
+
+`findModels` retries transient HuggingFace failures (429 and any 5xx) up to 3 times with exponential backoff (500ms / 1000ms / 2000ms) before throwing.
+
+## How scoring works
+
+Hard filters run **before** any scoring — a model that fails a hard filter never gets scored, regardless of `scoringMode` or which `providers` it came from:
+
+- `maxParamsB`, `contextLength`, `task` (MVP)
+- `maxLatencyMs` when a benchmark entry exists for the (model, string-enum `hardware`) pair (v0.2)
+- `hardware.vramGB` when an estimated footprint exceeds it (v0.4, heuristic — see "Known limitations")
+
+Survivors are scored. In `"rule"` mode (the default) that's four weighted components:
+
+- **Task match** — 50%
+- **Context window fit** — 20%
+- **Size fit** — 15%
+- **Domain match** — 15%
+
+`"embedding"` mode scores purely on text similarity instead; `"hybrid"` blends both 60/40 (rule/embedding). See "Scoring modes (v0.3)" above.
+
+Unknown metadata (e.g. undetectable param count, no benchmark entry, unreachable Ollama) is never punished or excluded — it gets a neutral mid-range score for that component only, or is simply not filtered on.
+
+## Known limitations
+
+- **Embedding mode uses lexical, not semantic, similarity.** The v0.3 `"embedding"`/`"hybrid"` scoring modes are backed by a small, local, dependency-free character-trigram hashing scheme (see `src/embeddings.ts`) — not a downloaded neural embedding model. It's genuinely offline and free, but two phrases that are semantically close yet share few characters (e.g. "extract key-value pairs from invoices" vs. "structured data extraction") will score lower than a real embedding model would give them.
+- **`vramGB` filtering is a heuristic, not a measured constraint.** Estimated from `paramsB` at ~2GB/1B params (roughly fp16). Quantized models need much less — this estimate skews conservative in that case. See "Multi-provider + structured hardware (v0.4)" above.
+- **Benchmark data is illustrative, not measured.** The shipped `src/data/benchmarks.json` contains a small set of placeholder latency numbers for demonstration and testing — not real measured inference latency. Replace it with genuinely benchmarked data before relying on `maxLatencyMs` exclusions in production.
+- `contextWindow` is currently always `null` for every provider — neither HuggingFace's list endpoint nor Ollama's `/api/tags` returns it, and the pipeline doesn't do a per-model detail fetch. This means the context-length hard filter rarely excludes anything, and the context-fit score is always neutral. Tracked as a possible future addition.
+- Ollama candidates never have a `pipeline_tag`, so the task hard filter always lets them through (same "unknown, don't exclude" rule as everywhere else) — task relevance for Ollama results relies entirely on scoring, not filtering.
+- Sub-billion-parameter models (e.g. `125M`) aren't detected by the size regex and report `paramsB: null`.
+- File-based cache only — no database engine. Cache entries are per-process-agnostic (survive restarts) but there's no cross-machine sharing.
+
+## CLI (v0.5, optional)
+
+`smallm` is library-first, but ships an optional CLI as a thin wrapper around `findModels()`. Every flag maps 1:1 to a `ModelQuery` field — the CLI contains no scoring, filtering, or provider logic of its own; it only parses flags and formats output. If you can do it via `findModels()`, you can do it via the CLI, and nothing else.
+
+```bash
+npx smallm find --task summarize --context 4096
+npx smallm find --task chat --context 8192 --max-params 7 --json
+npx smallm find --task chat --context 4096 --providers huggingface,ollama --hardware-type gpu --hardware-vram 8
+```
+
+Default output is a table:
+
+```
+NAME                                       PROVIDER     PARAMS(B)  SCORE  MODE       REASON
+------------------------------------------ ------------ ---------- ------ ---------- --------------------------------------------------
+org/some-7b-chat-model                     huggingface  6.5        87     rule       Strong task match, sufficient context window, and…
+```
+
+Pass `--json` for the raw `ModelMatch[]` instead — identical to what `findModels()` returns programmatically:
+
+```bash
+npx smallm find --task chat --context 4096 --json | jq '.[0].name'
+```
+
+### Flags
+
+| Flag | Maps to | Notes |
+|---|---|---|
+| `--task <task>` | `task` | Required |
+| `--context <tokens>` | `contextLength` | Required |
+| `--max-params <billions>` | `maxParamsB` | |
+| `--domain <domain>` | `domain` | |
+| `--hardware <cpu\|gpu-low\|gpu-high>` | `hardware` (string form) | |
+| `--hardware-type <cpu\|gpu>` + `--hardware-vram <gb>` | `hardware` (`HardwareSpec` form) | Takes precedence over `--hardware` if both given |
+| `--max-latency <ms>` | `maxLatencyMs` | |
+| `--scoring-mode <rule\|embedding\|hybrid>` | `scoringMode` | |
+| `--providers <list>` | `providers` | Comma-separated, e.g. `huggingface,ollama` |
+| `--limit <n>` | `limit` | |
+| `--cache-dir <path>` / `--cache-ttl <ms>` | `cacheOptions` | |
+| `--json` | — (output mode only) | Not a `ModelQuery` field — controls formatting, not what's queried |
+
+Run `npx smallm find --help` (or with no arguments) to see this from the terminal. Invalid input (a missing `--task`, a bad `--scoring-mode` value, etc.) isn't validated by the CLI itself — it's passed straight to `findModels()`, which throws the same typed errors (see "Handling errors" above) that the CLI then prints cleanly with a non-zero exit code.
+
+## Development
+
+```bash
+npm install
+npm run build   # compile TypeScript -> dist/ (also chmods dist/cli.js executable)
+npm test         # run the unit + integration test suite
+npm link          # optional: try the CLI locally as the `smallm` command
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+

package/dist/benchmark.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Looks up measured latency for a (model, hardware) pair.
+ * Returns null if no benchmark entry exists — per Section on unknown-value
+ * handling, "no data" must never be treated as "too slow." Callers (filters.ts)
+ * must let the model through when this returns null.
+ */
+export declare function lookupLatencyMs(modelId: string, hardware: string): number | null;
+/** Exposed for tests/debugging — total number of loaded benchmark entries. */
+export declare function benchmarkDatasetSize(): number;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhF;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/benchmark.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupLatencyMs = lookupLatencyMs;
+exports.benchmarkDatasetSize = benchmarkDatasetSize;
+const benchmarks_json_1 = __importDefault(require("./data/benchmarks.json"));
+/**
+ * Loaded once at module init from the checked-in dataset.
+ * NOTE: the shipped src/data/benchmarks.json numbers are illustrative
+ * placeholders for this build — replace with real measured data before
+ * relying on maxLatencyMs exclusions in production.
+ */
+const ENTRIES = benchmarks_json_1.default.entries;
+/** Keyed by `${modelId}::${hardware}` for O(1) lookup. */
+const INDEX = new Map(ENTRIES.map((entry) => [benchmarkKey(entry.modelId, entry.hardware), entry]));
+function benchmarkKey(modelId, hardware) {
+    return `${modelId}::${hardware}`;
+}
+/**
+ * Looks up measured latency for a (model, hardware) pair.
+ * Returns null if no benchmark entry exists — per Section on unknown-value
+ * handling, "no data" must never be treated as "too slow." Callers (filters.ts)
+ * must let the model through when this returns null.
+ */
+function lookupLatencyMs(modelId, hardware) {
+    const entry = INDEX.get(benchmarkKey(modelId, hardware));
+    return entry ? entry.avgLatencyMs : null;
+}
+/** Exposed for tests/debugging — total number of loaded benchmark entries. */
+function benchmarkDatasetSize() {
+    return ENTRIES.length;
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/benchmark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.js","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":";;;;;;;AACA,6EAAmD;AAEnD;;;;;GAKG;AACH,MAAM,OAAO,GAAqB,yBAAa,CAAC,OAA2B,CAAC;AAE5E,0DAA0D;AAC1D,MAAM,KAAK,GAAgC,IAAI,GAAG,CAChD,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,CAC7E,CAAC;AAEF,SAAS,YAAY,CAAC,OAAe,EAAE,QAAgB;IACrD,OAAO,GAAG,OAAO,KAAK,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,yBAAgC,OAAe,EAAE,QAAgB;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED,8EAA8E;AAC9E;IACE,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC"}

package/dist/cache-file.d.ts

@@ -0,0 +1,40 @@
+import { CacheOptions, HFModel } from "./types";
+/**
+ * File-based TTL cache — same conceptual interface as MVP's in-memory
+ * TTLCache (get/set/clear), but each entry is a JSON file on disk, so it
+ * survives process restarts. No database engine, per the v0.2 guide's
+ * explicit "don't introduce SQLite/Postgres/etc." rule — this is still a
+ * small library, not a service.
+ */
+export declare class FileTTLCache<T> {
+    private dir;
+    private ttlMs;
+    constructor(options?: CacheOptions);
+    /** Maps a cache key to a safe filename (keys can contain arbitrary characters). */
+    private filePathFor;
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    private deleteFile;
+}
+/** Sets (or resets) the cache options used by fetchCandidateModelsCached. */
+export declare function configureCandidateModelsCache(options?: CacheOptions): void;
+/**
+ * (v0.2) Cached wrapper around fetchCandidateModels, backed by the
+ * file-based cache instead of MVP's in-memory Map. Kept for backward
+ * compatibility (this exact function existed pre-v0.4) — built on the
+ * generic getOrFetchCached below, key-namespaced to "huggingface" so it
+ * can't collide with other providers' cache entries.
+ */
+export declare function fetchCandidateModelsCached(task: string): Promise<HFModel[]>;
+/**
+ * (v0.4) Generic cached-fetch helper, used by index.ts to cache each
+ * requested provider's candidate list independently (keyed by
+ * `${providerName}:${task}`, so HuggingFace and Ollama results for the
+ * same task never collide). Not provider-specific itself — any async
+ * producer of RawModel[] can use this.
+ */
+export declare function getOrFetchCached(key: string, fetchFn: () => Promise<HFModel[]>): Promise<HFModel[]>;
+/** Exposed for tests that need to reset cache state between runs. */
+export declare function clearCandidateModelsCache(): void;
+//# sourceMappingURL=cache-file.d.ts.map

package/dist/cache-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-file.d.ts","sourceRoot":"","sources":["../src/cache-file.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAWhD;;;;;;GAMG;AACH,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IAEtB,YAAY,OAAO,GAAE,YAAiB,EAIrC;IAED,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAKnB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAyB9B;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAI/B;IAED,KAAK,IAAI,IAAI,CAYZ;IAED,OAAO,CAAC,UAAU;CAOnB;AAOD,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI,CAE9E;AASD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAEjF;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,GAChC,OAAO,CAAC,OAAO,EAAE,CAAC,CAQpB;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/cache-file.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileTTLCache = void 0;
+exports.configureCandidateModelsCache = configureCandidateModelsCache;
+exports.fetchCandidateModelsCached = fetchCandidateModelsCached;
+exports.getOrFetchCached = getOrFetchCached;
+exports.clearCandidateModelsCache = clearCandidateModelsCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const huggingface_1 = require("./registry/huggingface");
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes — same default as MVP's in-memory cache
+const DEFAULT_DIR = path.join(os.tmpdir(), "smallm-cache");
+/**
+ * File-based TTL cache — same conceptual interface as MVP's in-memory
+ * TTLCache (get/set/clear), but each entry is a JSON file on disk, so it
+ * survives process restarts. No database engine, per the v0.2 guide's
+ * explicit "don't introduce SQLite/Postgres/etc." rule — this is still a
+ * small library, not a service.
+ */
+class FileTTLCache {
+    constructor(options = {}) {
+        this.dir = options.dir ?? DEFAULT_DIR;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        fs.mkdirSync(this.dir, { recursive: true });
+    }
+    /** Maps a cache key to a safe filename (keys can contain arbitrary characters). */
+    filePathFor(key) {
+        const hash = crypto.createHash("sha256").update(key).digest("hex");
+        return path.join(this.dir, `${hash}.json`);
+    }
+    get(key) {
+        const filePath = this.filePathFor(key);
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            return undefined; // file doesn't exist — not cached
+        }
+        let entry;
+        try {
+            entry = JSON.parse(raw);
+        }
+        catch {
+            // Corrupted cache file — treat as a miss rather than crashing the caller.
+            this.deleteFile(filePath);
+            return undefined;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.deleteFile(filePath);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        const filePath = this.filePathFor(key);
+        const entry = { value, expiresAt: Date.now() + this.ttlMs };
+        fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
+    }
+    clear() {
+        let files;
+        try {
+            files = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const file of files) {
+            if (file.endsWith(".json")) {
+                this.deleteFile(path.join(this.dir, file));
+            }
+        }
+    }
+    deleteFile(filePath) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // already gone — fine
+        }
+    }
+}
+exports.FileTTLCache = FileTTLCache;
+// Module-level singleton, matching MVP's cache.ts pattern. Options are
+// applied on first use; call configureCandidateModelsCache() before the
+// first findModels() call if you need non-default dir/ttl.
+let candidateModelsCache;
+/** Sets (or resets) the cache options used by fetchCandidateModelsCached. */
+function configureCandidateModelsCache(options = {}) {
+    candidateModelsCache = new FileTTLCache(options);
+}
+function getCache() {
+    if (!candidateModelsCache) {
+        candidateModelsCache = new FileTTLCache();
+    }
+    return candidateModelsCache;
+}
+/**
+ * (v0.2) Cached wrapper around fetchCandidateModels, backed by the
+ * file-based cache instead of MVP's in-memory Map. Kept for backward
+ * compatibility (this exact function existed pre-v0.4) — built on the
+ * generic getOrFetchCached below, key-namespaced to "huggingface" so it
+ * can't collide with other providers' cache entries.
+ */
+async function fetchCandidateModelsCached(task) {
+    return getOrFetchCached(`huggingface:${task}`, () => (0, huggingface_1.fetchCandidateModels)(task));
+}
+/**
+ * (v0.4) Generic cached-fetch helper, used by index.ts to cache each
+ * requested provider's candidate list independently (keyed by
+ * `${providerName}:${task}`, so HuggingFace and Ollama results for the
+ * same task never collide). Not provider-specific itself — any async
+ * producer of RawModel[] can use this.
+ */
+async function getOrFetchCached(key, fetchFn) {
+    const cache = getCache();
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const result = await fetchFn();
+    cache.set(key, result);
+    return result;
+}
+/** Exposed for tests that need to reset cache state between runs. */
+function clearCandidateModelsCache() {
+    getCache().clear();
+}
+//# sourceMappingURL=cache-file.js.map

package/dist/cache-file.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,23 @@
+import { HFModel } from "./types";
+/**
+ * Generic in-memory TTL cache. No disk persistence — out of scope for MVP
+ * (Section 2.2). Its only job is avoiding duplicate/rate-limited calls for
+ * repeated identical queries within the TTL window.
+ */
+export declare class TTLCache<T> {
+    private ttlMs;
+    private store;
+    constructor(ttlMs?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Cached wrapper around fetchCandidateModels. Same task within the TTL
+ * window returns the cached list instead of hitting HuggingFace again.
+ */
+export declare function fetchCandidateModelsCached(task: string): Promise<HFModel[]>;
+/** Exposed for tests that need to reset cache state between runs. */
+export declare function clearCandidateModelsCache(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAUlC;;;;GAIG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAGT,OAAO,CAAC,KAAK;IAFzB,OAAO,CAAC,KAAK,CAAoC;IAEjD,YAAoB,KAAK,GAAE,MAAuB,EAAI;IAEtD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAQ9B;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAE/B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAMD;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAOjF;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/cache.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTLCache = void 0;
+exports.fetchCandidateModelsCached = fetchCandidateModelsCached;
+exports.clearCandidateModelsCache = clearCandidateModelsCache;
+const huggingface_1 = require("./registry/huggingface");
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Generic in-memory TTL cache. No disk persistence — out of scope for MVP
+ * (Section 2.2). Its only job is avoiding duplicate/rate-limited calls for
+ * repeated identical queries within the TTL window.
+ */
+class TTLCache {
+    constructor(ttlMs = DEFAULT_TTL_MS) {
+        this.ttlMs = ttlMs;
+        this.store = new Map();
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    clear() {
+        this.store.clear();
+    }
+    get size() {
+        return this.store.size;
+    }
+}
+exports.TTLCache = TTLCache;
+// Module-level singleton cache, keyed by task string (fetchCandidateModels
+// only varies by task, since that's what maps to pipeline_tag).
+const candidateModelsCache = new TTLCache();
+/**
+ * Cached wrapper around fetchCandidateModels. Same task within the TTL
+ * window returns the cached list instead of hitting HuggingFace again.
+ */
+async function fetchCandidateModelsCached(task) {
+    const cached = candidateModelsCache.get(task);
+    if (cached)
+        return cached;
+    const result = await (0, huggingface_1.fetchCandidateModels)(task);
+    candidateModelsCache.set(task, result);
+    return result;
+}
+/** Exposed for tests that need to reset cache state between runs. */
+function clearCandidateModelsCache() {
+    candidateModelsCache.clear();
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":";;;;;AACA,wDAA8D;AAE9D,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAOlD;;;;GAIG;AACH;IAGE,YAAoB,KAAK,GAAW,cAAc;QAA9B,UAAK,GAAL,KAAK,CAAyB;QAF1C,UAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEI,CAAC;IAEtD,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;;AAED,2EAA2E;AAC3E,gEAAgE;AAChE,MAAM,oBAAoB,GAAG,IAAI,QAAQ,EAAa,CAAC;AAEvD;;;GAGG;AACI,KAAK,qCAAqC,IAAY;IAC3D,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,MAAM,IAAA,kCAAoB,EAAC,IAAI,CAAC,CAAC;IAChD,oBAAoB,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qEAAqE;AACrE;IACE,oBAAoB,CAAC,KAAK,EAAE,CAAC;AAC/B,CAAC"}