@kindgi/adapter-model-in-process 0.0.0-bootstrap.0 → 0.1.1

package/dist/provider.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { DEFAULT_LOCAL_MODEL, MODEL_SPECS } from './models.js';
+/**
+ * Create an in-process `ModelProvider` backed by `@huggingface/transformers`.
+ *
+ * Pipelines are loaded lazily per model on the first `invoke()` call
+ * that names them — construction of the provider is cheap. Model
+ * weights download into the transformers.js cache (or `cacheDir`) on
+ * first use; later loads read from the cache.
+ *
+ * Cost is always `0` USD (no external service). Resource-usage recording
+ * still tracks token counts + duration so operators can see the local
+ * model's real load in aggregate reports.
+ *
+ * The returned provider is safe to share process-wide; each underlying
+ * pipeline serialises its own requests inside the ONNX runtime.
+ */
+export function createInProcessModelProvider(options = {}) {
+    const modelKeys = options.models ?? [DEFAULT_LOCAL_MODEL];
+    if (modelKeys.length === 0) {
+        throw new Error('createInProcessModelProvider: `models` must not be empty.');
+    }
+    const providerId = options.providerId ?? `in-process/${modelKeys.join('+')}`;
+    const metadata = buildProviderMetadata(providerId, modelKeys);
+    // Cache loaded pipelines per model key. Uses a Promise to dedupe
+    // concurrent first-invocations on the same model.
+    const pipelines = new Map();
+    function loadPipeline(modelKey) {
+        const cached = pipelines.get(modelKey);
+        if (cached !== undefined)
+            return cached;
+        const spec = MODEL_SPECS[modelKey];
+        const loading = (async () => {
+            const mod = (await import('@huggingface/transformers'));
+            return (await mod.pipeline('text-generation', spec.hfName, {
+                dtype: spec.dtype,
+                ...(options.cacheDir !== undefined && { cache_dir: options.cacheDir }),
+            }));
+        })();
+        pipelines.set(modelKey, loading);
+        return loading;
+    }
+    return {
+        metadata,
+        async invoke(input) {
+            const modelKey = input.model;
+            if (!modelKeys.includes(modelKey)) {
+                throw new Error(`@kindgi/adapter-model-in-process: provider "${providerId}" does not expose model "${input.model}". ` +
+                    `Available: ${modelKeys.join(', ') || '<none>'}.`);
+            }
+            const spec = MODEL_SPECS[modelKey];
+            const p = await loadPipeline(modelKey);
+            const messages = input.messages.map(toChatTemplateMessage);
+            const startedAt = Date.now();
+            const promptTokens = countPromptTokens(p, messages);
+            const output = await p(messages, {
+                max_new_tokens: input.maxOutputTokens ?? 512,
+                do_sample: input.temperature !== undefined && input.temperature > 0,
+                ...(input.temperature !== undefined &&
+                    input.temperature > 0 && {
+                    temperature: input.temperature,
+                }),
+                // No TextStreamer: `invoke` waits for the complete generation and
+                // returns it in one result.
+            });
+            const durationMs = Date.now() - startedAt;
+            const firstResult = output[0];
+            const chat = firstResult?.generated_text ?? [];
+            const assistantTurn = chat.at(-1);
+            const responseText = assistantTurn?.content ?? '';
+            const completionTokens = countTextTokens(p, responseText);
+            void spec;
+            return {
+                message: { role: 'assistant', content: responseText },
+                finishReason: 'stop',
+                usage: { promptTokens, completionTokens },
+                // In-process = zero direct USD cost. Ledger still records tokens.
+                costUsd: 0,
+                durationMs,
+                provider: { id: providerId, model: modelKey },
+            };
+        },
+    };
+}
+/**
+ * Build `ProviderMetadata` from the set of local models this provider
+ * exposes. Each `LocalModel` key maps to a `ModelInfo` entry —
+ * `ModelInfo.name` is the key itself (short label), not the fully-
+ * qualified Hugging Face model id, so provider listings (such as
+ * `GET /v1/providers`) show `smollm2-360m` alongside vendor model ids.
+ * Provider-level `attributes` are the union of every model's
+ * `suitableFor` + `tier`, deduped, plus a marker `in-process`.
+ */
+function buildProviderMetadata(providerId, modelKeys) {
+    const attributes = new Set(['in-process']);
+    for (const key of modelKeys) {
+        const spec = MODEL_SPECS[key];
+        for (const attr of spec.suitableFor)
+            attributes.add(attr);
+        attributes.add(spec.tier);
+    }
+    return {
+        id: providerId,
+        region: 'in-process',
+        models: modelKeys.map((key) => buildModelInfo(key, MODEL_SPECS[key])),
+        attributes: [...attributes],
+        description: 'Local models via @huggingface/transformers — routing / classification / smoke-test tier.',
+    };
+}
+function buildModelInfo(key, spec) {
+    const features = ['streaming'];
+    if (spec.toolUse)
+        features.push('tool-use', 'structured-output');
+    if (spec.contextWindow >= 32_000)
+        features.push('long-context');
+    return {
+        name: key,
+        contextWindow: spec.contextWindow,
+        features,
+        cost: { promptUsdPer1kTokens: 0, completionUsdPer1kTokens: 0 },
+        description: `Local ${spec.tier}-tier model (${spec.approxDownloadMb} MB, ${spec.contextWindow}-token context, HF id: ${spec.hfName}).`,
+    };
+}
+/** Translate Kindgi ModelMessage → transformers.js Chat template message. */
+function toChatTemplateMessage(m) {
+    return { role: m.role, content: m.content };
+}
+/**
+ * Token counting via the pipeline's tokenizer. Called before invocation
+ * for prompt tokens and after for completion tokens. The tokenizer is
+ * async-loaded with the pipeline; this must run after `loadPipeline()`.
+ */
+function countPromptTokens(p, messages) {
+    const applyTemplate = p.tokenizer.apply_chat_template;
+    if (typeof applyTemplate !== 'function') {
+        return messages.reduce((sum, m) => sum + countTextTokens(p, m.content), 0);
+    }
+    try {
+        const ids = applyTemplate(messages, {
+            tokenize: true,
+            add_generation_prompt: true,
+        });
+        return Array.isArray(ids) ? ids.length : 0;
+    }
+    catch {
+        return messages.reduce((sum, m) => sum + countTextTokens(p, m.content), 0);
+    }
+}
+function countTextTokens(p, text) {
+    if (text.length === 0)
+        return 0;
+    const encode = p.tokenizer.encode;
+    if (typeof encode !== 'function') {
+        return Math.ceil(text.length / 4);
+    }
+    try {
+        return encode(text).length;
+    }
+    catch {
+        return Math.ceil(text.length / 4);
+    }
+}
+export { MODEL_SPECS, DEFAULT_LOCAL_MODEL } from './models.js';
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/package.json

@@ -1,7 +1,51 @@
 {
   "name": "@kindgi/adapter-model-in-process",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.1",
+  "description": "In-process ModelProvider for @kindgi/capabilities. Runs small instruction-tuned LLMs inside the Node.js process via @huggingface/transformers (ONNX runtime; no external processes, no API keys). SmolLM2-360M by default (~273MB q4f16, Apache 2.0, tuned for function calling); SmolLM2-135M and Qwen3-0.6B selectable via the `models` option. prepareInProcessModel downloads a model ahead of first use and streams progress. Positioned as the cheapest tier for routing/classification/smoke-test workloads — not a replacement for hosted providers on real reasoning tasks.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/adapters/model-in-process"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/adapters/model-in-process#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@huggingface/transformers": "^4.3.0",
+    "@kindgi/capabilities": "0.1.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export {
+  DEFAULT_LOCAL_MODEL,
+  MODEL_SPECS,
+  createInProcessModelProvider,
+} from './provider.js';
+export type { InProcessProviderOptions, LocalModel, ModelSpec } from './provider.js';
+export { prepareInProcessModel } from './prepare.js';
+export type { PrepareInProcessParams } from './prepare.js';
+export type { ModelProvider, PrepareEvent } from '@kindgi/capabilities';

package/src/models.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Model registry — three selectable tiers, all Apache 2.0.
+ *
+ * Sizes are approximate q4f16 (4-bit quantization, float16 activations)
+ * download sizes. The first `invoke()` naming a model (or a
+ * `prepareInProcessModel` run for it) downloads the files into the
+ * transformers.js cache; later loads read from the cache. The default
+ * cache is transformers.js's own `env.cacheDir` — with
+ * `@huggingface/transformers` 4.x, a `.cache` directory inside that
+ * package's install location. The `cacheDir` option (provider and
+ * prepare) is passed to the pipeline as `cache_dir` and redirects the
+ * model files; transformers.js 4.3 can still write a model's
+ * `config.json` to its default cache.
+ *
+ * Positioning per tier:
+ *   - `smollm2-135m` — ultra-light. Routing, tag extraction, short
+ *     classification, simple JSON. Do not use for reasoning or math.
+ *   - `smollm2-360m` — default. Instruction-tuned with function-calling,
+ *     summarisation and rewriting data. Best quality-per-megabyte in the
+ *     tier.
+ *   - `qwen3-0.6b` — highest local quality. Larger download; better on
+ *     reasoning / longer contexts.
+ */
+export type LocalModel = 'smollm2-135m' | 'smollm2-360m' | 'qwen3-0.6b';
+
+export interface ModelSpec {
+  /** Hugging Face hub repo id — must have transformers.js-compatible ONNX assets. */
+  readonly hfName: string;
+  /** Approximate q4f16 download size in MB. */
+  readonly approxDownloadMb: number;
+  /** Model context window in tokens. */
+  readonly contextWindow: number;
+  /** Whether the model was tuned for tool / function-calling use. */
+  readonly toolUse: boolean;
+  /** Rough size tier — added to the provider's `attributes` and each model's `description`. */
+  readonly tier: 'ultra-light' | 'small' | 'medium';
+  /** Suitable-for hints for capability router preference matching. */
+  readonly suitableFor: readonly string[];
+  /** dtype passed to transformers.js pipeline. Balances quality vs size. */
+  readonly dtype: 'q4f16' | 'q8' | 'fp16' | 'fp32';
+}
+
+export const MODEL_SPECS: Record<LocalModel, ModelSpec> = {
+  'smollm2-135m': {
+    hfName: 'HuggingFaceTB/SmolLM2-135M-Instruct',
+    approxDownloadMb: 118,
+    contextWindow: 8192,
+    toolUse: false,
+    tier: 'ultra-light',
+    suitableFor: ['routing', 'classification', 'smoke-test', 'local', 'lower-cost'],
+    dtype: 'q4f16',
+  },
+  'smollm2-360m': {
+    hfName: 'HuggingFaceTB/SmolLM2-360M-Instruct',
+    approxDownloadMb: 273,
+    contextWindow: 8192,
+    toolUse: true,
+    tier: 'small',
+    suitableFor: [
+      'routing',
+      'classification',
+      'extraction',
+      'summarization',
+      'local',
+      'lower-cost',
+    ],
+    dtype: 'q4f16',
+  },
+  'qwen3-0.6b': {
+    hfName: 'onnx-community/Qwen3-0.6B-ONNX',
+    approxDownloadMb: 550,
+    contextWindow: 32_768,
+    toolUse: true,
+    tier: 'medium',
+    suitableFor: ['reasoning', 'routing', 'classification', 'extraction', 'long-context', 'local'],
+    dtype: 'q4f16',
+  },
+};
+
+/** Default model when none supplied — best quality-per-MB in the tier. */
+export const DEFAULT_LOCAL_MODEL: LocalModel = 'smollm2-360m';

package/src/prepare.ts

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { PrepareEvent } from '@kindgi/capabilities';
+
+import { DEFAULT_LOCAL_MODEL, type LocalModel, MODEL_SPECS } from './models.js';
+
+/**
+ * `prepareInProcessModel` — the in-process adapter's download / warmup
+ * step, in the shape of `AdapterFactoryEntry.prepare()` from
+ * `@kindgi/capabilities`. Streams download / warmup progress as
+ * framework `PrepareEvent`s so an HTTP SSE endpoint (such as
+ * `POST /v1/adapters/:adapterId/prepare` in `@kindgi/api`) can stream
+ * them to a client.
+ *
+ * What happens under the hood:
+ *   0. Yield a first `progress` event naming the model and its
+ *      approximate download size, before any callback fires.
+ *   1. Dynamically import `@huggingface/transformers` (kept
+ *      dynamic so shape tests don't touch the ONNX runtime).
+ *   2. Call `pipeline('text-generation', hfName, {dtype,
+ *      progress_callback})`. First run: transformers.js downloads
+ *      the model into its cache (`cacheDir` when set, passed as
+ *      `cache_dir`; otherwise transformers.js's default, see
+ *      `models.ts`). Subsequent runs hit the cache — the callback
+ *      still fires but reports zero-byte "downloads."
+ *   3. The pipeline's progress_callback fires with events like
+ *      `{status: 'initiate' | 'download' | 'progress' | 'done',
+ *      name, file, progress?, loaded?, total?}`. We translate each
+ *      into a `PrepareEvent` and enqueue it for the async iterator
+ *      to yield.
+ *   4. When the pipeline promise resolves → emit `{kind: 'ready'}`
+ *      and end the stream. On rejection → emit
+ *      `{kind: 'error', message}` and end.
+ *
+ * Consumer pattern (e.g. inside an SSE route):
+ * ```ts
+ * for await (const event of prepareInProcessModel({model: 'smollm2-360m'})) {
+ *   sendSse(event);
+ * }
+ * ```
+ */
+export interface PrepareInProcessParams {
+  readonly model?: LocalModel;
+  /** Directory for downloaded model files, passed to transformers.js as `cache_dir`. */
+  readonly cacheDir?: string;
+}
+
+interface RawProgressEvent {
+  readonly status?: string;
+  readonly name?: string;
+  readonly file?: string;
+  readonly progress?: number;
+  readonly loaded?: number;
+  readonly total?: number;
+}
+
+export async function* prepareInProcessModel(
+  params: PrepareInProcessParams = {},
+): AsyncIterable<PrepareEvent> {
+  const modelKey = params.model ?? DEFAULT_LOCAL_MODEL;
+  const spec = MODEL_SPECS[modelKey];
+
+  const queue: PrepareEvent[] = [];
+  let resolveWait: (() => void) | undefined;
+  let ended = false;
+
+  const enqueue = (event: PrepareEvent): void => {
+    queue.push(event);
+    const w = resolveWait;
+    resolveWait = undefined;
+    w?.();
+  };
+  const finish = (event: PrepareEvent): void => {
+    queue.push(event);
+    ended = true;
+    const w = resolveWait;
+    resolveWait = undefined;
+    w?.();
+  };
+
+  const progressCallback = (raw: unknown): void => {
+    if (raw === null || typeof raw !== 'object') return;
+    const r = raw as RawProgressEvent;
+    switch (r.status) {
+      case 'initiate':
+        enqueue({
+          kind: 'progress',
+          message: `Fetching ${r.file ?? r.name ?? spec.hfName}`,
+          ...(r.file !== undefined && { file: r.file }),
+        });
+        return;
+      case 'download':
+        enqueue({
+          kind: 'progress',
+          message: `Downloading ${r.file ?? r.name ?? spec.hfName}`,
+          ...(r.file !== undefined && { file: r.file }),
+        });
+        return;
+      case 'progress':
+        if (typeof r.progress === 'number') {
+          enqueue({
+            kind: 'progress',
+            message: `Downloading ${r.file ?? r.name ?? spec.hfName}`,
+            ratio: Math.max(0, Math.min(1, r.progress / 100)),
+            ...(typeof r.loaded === 'number' && { loadedBytes: r.loaded }),
+            ...(typeof r.total === 'number' && { totalBytes: r.total }),
+            ...(r.file !== undefined && { file: r.file }),
+          });
+        }
+        return;
+      case 'done':
+        enqueue({
+          kind: 'progress',
+          message: `Completed ${r.file ?? r.name ?? spec.hfName}`,
+          ratio: 1,
+          ...(r.file !== undefined && { file: r.file }),
+        });
+        return;
+      default:
+        // 'ready' + any unknown status — ignore; the load-promise
+        // resolution is the authoritative "done" signal.
+        return;
+    }
+  };
+
+  // Kick off the load in parallel with the yield loop.
+  const loadPromise = (async () => {
+    const mod = (await import('@huggingface/transformers')) as unknown as {
+      pipeline: (task: string, model: string, opts: Record<string, unknown>) => Promise<unknown>;
+    };
+    return mod.pipeline('text-generation', spec.hfName, {
+      dtype: spec.dtype,
+      progress_callback: progressCallback,
+      ...(params.cacheDir !== undefined && { cache_dir: params.cacheDir }),
+    });
+  })();
+
+  loadPromise.then(
+    () => finish({ kind: 'ready', message: `${spec.hfName} ready` }),
+    (err) =>
+      finish({
+        kind: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      }),
+  );
+
+  // Prologue — tell the consumer what's about to happen even before
+  // the callback fires (transformers.js can silently sit on a cache
+  // check for a second or two before emitting anything).
+  yield {
+    kind: 'progress',
+    message: `Preparing ${spec.hfName} (~${spec.approxDownloadMb} MB, ${spec.tier} tier)`,
+  };
+
+  while (!ended || queue.length > 0) {
+    const next = queue.shift();
+    if (next !== undefined) {
+      yield next;
+      continue;
+    }
+    await new Promise<void>((resolve) => {
+      resolveWait = resolve;
+    });
+  }
+}