@happyvertical/smrt-core 0.60.8 → 0.60.9

package/README.md

@@ -465,6 +465,42 @@ const isExpensive = await product.is('costs more than the average product');
 const description = await product.do('Write a short marketing description');
 ```
 
+### BYO inference presets and local discovery
+
+From Node application code, import `resolveInferencePreset` and
+`discoverLocalInferenceModels` from `@happyvertical/smrt-core/byo-inference`.
+Pass the options from `resolveInferencePreset(id, { model, apiKey })` to
+`getAI` from `@happyvertical/ai` after checking for `null`. Each preset uses
+the OpenAI-compatible SDK provider and requires an explicit model ID.
+
+| Preset ID | Default API base URL | API key |
+| --- | --- | --- |
+| `openrouter` | `https://openrouter.ai/api/v1` | Required |
+| `lemonade` | `http://127.0.0.1:13305/v1` | Supply if server authentication is enabled |
+| `llama.cpp` | `http://127.0.0.1:9931/v1` | Supply if server authentication is enabled |
+| `lm-studio` | `http://127.0.0.1:1234/v1` | Supply if server authentication is enabled |
+
+The resolver returns `null` for unknown preset IDs, blank model IDs, and
+missing OpenRouter keys. The SDK requires a nonempty key, so keyless local
+options use a fixed synthetic credential.
+
+Call `discoverLocalInferenceModels()` explicitly when the application needs
+to suggest models. It makes parallel, credential-free GET requests to Ollama
+(`127.0.0.1:11434/api/tags`) and Lemonade
+(`127.0.0.1:13305/v1/models`). Each probe has a one-second deadline and
+a 1 MiB response limit. A reachable service with an empty model list returns
+`available: true` and `models: []`. An unreachable service, a service that
+requires authentication, or a failed probe returns `available: false`.
+Discovery excludes Ollama models with upstream model or host metadata.
+Ollama's `baseUrl` is suitable for the SDK's `ollama` provider. Lemonade
+model IDs can be used with the `lemonade` preset.
+
+Provider references are available for [OpenRouter](https://openrouter.ai/developers),
+[Lemonade](https://lemonade-server.ai/docs/api/openai/#get-v1models),
+[llama.cpp](https://github.com/ggml-org/llama.cpp/tree/master/tools/server#quick-start),
+[LM Studio](https://lmstudio.ai/docs/developer/openai-compat), and
+[Ollama](https://github.com/ollama/ollama/blob/main/docs/openapi.yaml).
+
 ### Opt-In Read Cache
 
 SSR apps that re-query read-heavy / write-rare collections on every request

package/dist/byo-inference.d.ts

@@ -0,0 +1,55 @@
+import type { OpenAIOptions } from '@happyvertical/ai';
+declare const PRESETS: {
+    readonly openrouter: {
+        readonly baseUrl: "https://openrouter.ai/api/v1";
+        readonly requiresApiKey: true;
+    };
+    readonly lemonade: {
+        readonly baseUrl: "http://127.0.0.1:13305/v1";
+        readonly requiresApiKey: false;
+    };
+    readonly 'llama.cpp': {
+        readonly baseUrl: "http://127.0.0.1:9931/v1";
+        readonly requiresApiKey: false;
+    };
+    readonly 'lm-studio': {
+        readonly baseUrl: "http://127.0.0.1:1234/v1";
+        readonly requiresApiKey: false;
+    };
+};
+export type InferencePresetId = keyof typeof PRESETS;
+/**
+ * Resolve a named preset with an explicit model. Returns null when a preset,
+ * model, or required API key is missing or invalid.
+ */
+export declare function resolveInferencePreset(id: string, input: {
+    model: string;
+    apiKey?: string;
+}): OpenAIOptions | null;
+declare const LOCAL_SERVICES: readonly [{
+    readonly service: "ollama";
+    readonly baseUrl: "http://127.0.0.1:11434";
+    readonly modelPath: "/api/tags";
+    readonly listField: "models";
+    readonly idField: "name";
+}, {
+    readonly service: "lemonade";
+    readonly baseUrl: "http://127.0.0.1:13305/v1";
+    readonly modelPath: "/models";
+    readonly listField: "data";
+    readonly idField: "id";
+}];
+type LocalService = (typeof LOCAL_SERVICES)[number];
+export type LocalInferenceDiscovery = {
+    service: LocalService['service'];
+    baseUrl: string;
+} & ({
+    available: true;
+    models: string[];
+} | {
+    available: false;
+});
+/** Probe the default loopback Ollama and Lemonade servers without credentials. */
+export declare function discoverLocalInferenceModels(): Promise<LocalInferenceDiscovery[]>;
+export {};
+//# sourceMappingURL=byo-inference.d.ts.map

package/dist/byo-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byo-inference.d.ts","sourceRoot":"","sources":["../src/byo-inference.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;CAiBH,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,OAAO,CAAC;AAErD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,aAAa,GAAG,IAAI,CAiBtB;AAED,QAAA,MAAM,cAAc;;;;;;;;;;;;EAeV,CAAC;AAEX,KAAK,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,CAAC;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAmFnE,kFAAkF;AAClF,wBAAgB,4BAA4B,IAAI,OAAO,CACrD,uBAAuB,EAAE,CAC1B,CAEA"}

package/dist/byo-inference.js

@@ -0,0 +1,113 @@
+import { get } from "node:http";
+//#region src/byo-inference.ts
+var LEMONADE_BASE_URL = "http://127.0.0.1:13305/v1";
+var PRESETS = {
+	openrouter: {
+		baseUrl: "https://openrouter.ai/api/v1",
+		requiresApiKey: true
+	},
+	lemonade: {
+		baseUrl: LEMONADE_BASE_URL,
+		requiresApiKey: false
+	},
+	"llama.cpp": {
+		baseUrl: "http://127.0.0.1:9931/v1",
+		requiresApiKey: false
+	},
+	"lm-studio": {
+		baseUrl: "http://127.0.0.1:1234/v1",
+		requiresApiKey: false
+	}
+};
+/**
+* Resolve a named preset with an explicit model. Returns null when a preset,
+* model, or required API key is missing or invalid.
+*/
+function resolveInferencePreset(id, input) {
+	if (!Object.hasOwn(PRESETS, id)) return null;
+	const preset = PRESETS[id];
+	const model = typeof input.model === "string" ? input.model.trim() : "";
+	const apiKey = typeof input.apiKey === "string" ? input.apiKey.trim() : void 0;
+	if (!model || !apiKey && preset.requiresApiKey) return null;
+	return {
+		type: "openai",
+		baseUrl: preset.baseUrl,
+		defaultModel: model,
+		apiKey: apiKey || "smrt-local"
+	};
+}
+var LOCAL_SERVICES = [{
+	service: "ollama",
+	baseUrl: "http://127.0.0.1:11434",
+	modelPath: "/api/tags",
+	listField: "models",
+	idField: "name"
+}, {
+	service: "lemonade",
+	baseUrl: LEMONADE_BASE_URL,
+	modelPath: "/models",
+	listField: "data",
+	idField: "id"
+}];
+var PROBE_TIMEOUT_MS = 1e3;
+var MAX_RESPONSE_BYTES = 1024 * 1024;
+function readField(value, field) {
+	if (value !== null && typeof value === "object" && Object.hasOwn(value, field)) return value[field];
+}
+async function readModels(response, service) {
+	if (response.statusCode !== 200) {
+		response.destroy();
+		return null;
+	}
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of response) {
+		size += chunk.length;
+		if (size > MAX_RESPONSE_BYTES) return null;
+		chunks.push(chunk);
+	}
+	const entries = readField(JSON.parse(Buffer.concat(chunks).toString("utf8")), service.listField);
+	if (!Array.isArray(entries)) return null;
+	const models = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const id = readField(entry, service.idField);
+		if (typeof id !== "string" || !id.trim()) continue;
+		if (service.service === "ollama" && (readField(entry, "remote_model") || readField(entry, "remote_host"))) continue;
+		if (service.service === "lemonade" && (readField(entry, "recipe") === "cloud" || readField(entry, "downloaded") === false)) continue;
+		models.add(id);
+	}
+	return [...models];
+}
+async function probe(service) {
+	const identity = {
+		service: service.service,
+		baseUrl: service.baseUrl
+	};
+	try {
+		const models = await new Promise((resolve, reject) => {
+			get(service.baseUrl + service.modelPath, {
+				agent: false,
+				signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+			}, (response) => {
+				readModels(response, service).then(resolve, reject);
+			}).once("error", reject);
+		});
+		if (models) return {
+			...identity,
+			available: true,
+			models
+		};
+	} catch {}
+	return {
+		...identity,
+		available: false
+	};
+}
+/** Probe the default loopback Ollama and Lemonade servers without credentials. */
+function discoverLocalInferenceModels() {
+	return Promise.all(LOCAL_SERVICES.map(probe));
+}
+//#endregion
+export { discoverLocalInferenceModels, resolveInferencePreset };
+
+//# sourceMappingURL=byo-inference.js.map

package/dist/byo-inference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byo-inference.js","names":[],"sources":["../src/byo-inference.ts"],"sourcesContent":["import { get, type IncomingMessage } from 'node:http';\nimport type { OpenAIOptions } from '@happyvertical/ai';\n\nconst LEMONADE_BASE_URL = 'http://127.0.0.1:13305/v1';\n\nconst PRESETS = {\n  openrouter: {\n    baseUrl: 'https://openrouter.ai/api/v1',\n    requiresApiKey: true,\n  },\n  lemonade: {\n    baseUrl: LEMONADE_BASE_URL,\n    requiresApiKey: false,\n  },\n  'llama.cpp': {\n    baseUrl: 'http://127.0.0.1:9931/v1',\n    requiresApiKey: false,\n  },\n  'lm-studio': {\n    baseUrl: 'http://127.0.0.1:1234/v1',\n    requiresApiKey: false,\n  },\n} as const;\n\nexport type InferencePresetId = keyof typeof PRESETS;\n\n/**\n * Resolve a named preset with an explicit model. Returns null when a preset,\n * model, or required API key is missing or invalid.\n */\nexport function resolveInferencePreset(\n  id: string,\n  input: { model: string; apiKey?: string },\n): OpenAIOptions | null {\n  if (!Object.hasOwn(PRESETS, id)) return null;\n\n  const preset = PRESETS[id as InferencePresetId];\n  const model = typeof input.model === 'string' ? input.model.trim() : '';\n  const apiKey =\n    typeof input.apiKey === 'string' ? input.apiKey.trim() : undefined;\n  if (!model || (!apiKey && preset.requiresApiKey)) return null;\n\n  return {\n    type: 'openai',\n    baseUrl: preset.baseUrl,\n    defaultModel: model,\n    // The SDK requires a nonempty key. A fixed placeholder keeps keyless\n    // local servers from receiving credentials inherited from the environment.\n    apiKey: apiKey || 'smrt-local',\n  };\n}\n\nconst LOCAL_SERVICES = [\n  {\n    service: 'ollama',\n    baseUrl: 'http://127.0.0.1:11434',\n    modelPath: '/api/tags',\n    listField: 'models',\n    idField: 'name',\n  },\n  {\n    service: 'lemonade',\n    baseUrl: LEMONADE_BASE_URL,\n    modelPath: '/models',\n    listField: 'data',\n    idField: 'id',\n  },\n] as const;\n\ntype LocalService = (typeof LOCAL_SERVICES)[number];\n\nexport type LocalInferenceDiscovery = {\n  service: LocalService['service'];\n  baseUrl: string;\n} & ({ available: true; models: string[] } | { available: false });\n\nconst PROBE_TIMEOUT_MS = 1_000;\nconst MAX_RESPONSE_BYTES = 1024 * 1024;\n\nfunction readField(value: unknown, field: string): unknown {\n  if (\n    value !== null &&\n    typeof value === 'object' &&\n    Object.hasOwn(value, field)\n  ) {\n    return (value as Record<string, unknown>)[field];\n  }\n}\n\nasync function readModels(\n  response: IncomingMessage,\n  service: LocalService,\n): Promise<string[] | null> {\n  if (response.statusCode !== 200) {\n    response.destroy();\n    return null;\n  }\n\n  const chunks: Buffer[] = [];\n  let size = 0;\n  for await (const chunk of response as AsyncIterable<Buffer>) {\n    size += chunk.length;\n    if (size > MAX_RESPONSE_BYTES) return null;\n    chunks.push(chunk);\n  }\n\n  const payload: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));\n  const entries = readField(payload, service.listField);\n  if (!Array.isArray(entries)) return null;\n\n  const models = new Set<string>();\n  for (const entry of entries) {\n    const id = readField(entry, service.idField);\n    if (typeof id !== 'string' || !id.trim()) continue;\n    // Ollama's local inventory can include aliases for upstream models.\n    if (\n      service.service === 'ollama' &&\n      (readField(entry, 'remote_model') || readField(entry, 'remote_host'))\n    ) {\n      continue;\n    }\n    // Lemonade can also list hosted models and older versions can list models\n    // that still need a download. Keep only local models from those responses.\n    if (\n      service.service === 'lemonade' &&\n      (readField(entry, 'recipe') === 'cloud' ||\n        readField(entry, 'downloaded') === false)\n    ) {\n      continue;\n    }\n    models.add(id);\n  }\n  return [...models];\n}\n\nasync function probe(service: LocalService): Promise<LocalInferenceDiscovery> {\n  const identity = { service: service.service, baseUrl: service.baseUrl };\n  try {\n    const models = await new Promise<string[] | null>((resolve, reject) => {\n      // A one-use agent bypasses any global HTTP proxy. Node HTTP also does\n      // not follow redirects. The signal bounds the full request and body read.\n      const request = get(\n        service.baseUrl + service.modelPath,\n        { agent: false, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) },\n        (response) => {\n          readModels(response, service).then(resolve, reject);\n        },\n      );\n      request.once('error', reject);\n    });\n    if (models) return { ...identity, available: true, models };\n  } catch {\n    // Errors and response bodies may include sensitive local metadata.\n  }\n  return { ...identity, available: false };\n}\n\n/** Probe the default loopback Ollama and Lemonade servers without credentials. */\nexport function discoverLocalInferenceModels(): Promise<\n  LocalInferenceDiscovery[]\n> {\n  return Promise.all(LOCAL_SERVICES.map(probe));\n}\n"],"mappings":";;AAGA,IAAM,oBAAoB;AAE1B,IAAM,UAAU;CACd,YAAY;EACV,SAAS;EACT,gBAAgB;CAClB;CACA,UAAU;EACR,SAAS;EACT,gBAAgB;CAClB;CACA,aAAa;EACX,SAAS;EACT,gBAAgB;CAClB;CACA,aAAa;EACX,SAAS;EACT,gBAAgB;CAClB;AACF;;;;;AAQA,SAAgB,uBACd,IACA,OACsB;CACtB,IAAI,CAAC,OAAO,OAAO,SAAS,EAAE,GAAG,OAAO;CAExC,MAAM,SAAS,QAAQ;CACvB,MAAM,QAAQ,OAAO,MAAM,UAAU,WAAW,MAAM,MAAM,KAAK,IAAI;CACrE,MAAM,SACJ,OAAO,MAAM,WAAW,WAAW,MAAM,OAAO,KAAK,IAAI,KAAA;CAC3D,IAAI,CAAC,SAAU,CAAC,UAAU,OAAO,gBAAiB,OAAO;CAEzD,OAAO;EACL,MAAM;EACN,SAAS,OAAO;EAChB,cAAc;EAGd,QAAQ,UAAU;CACpB;AACF;AAEA,IAAM,iBAAiB,CACrB;CACE,SAAS;CACT,SAAS;CACT,WAAW;CACX,WAAW;CACX,SAAS;AACX,GACA;CACE,SAAS;CACT,SAAS;CACT,WAAW;CACX,WAAW;CACX,SAAS;AACX,CACF;AASA,IAAM,mBAAmB;AACzB,IAAM,qBAAqB,OAAO;AAElC,SAAS,UAAU,OAAgB,OAAwB;CACzD,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,OAAO,OAAO,KAAK,GAE1B,OAAQ,MAAkC;AAE9C;AAEA,eAAe,WACb,UACA,SAC0B;CAC1B,IAAI,SAAS,eAAe,KAAK;EAC/B,SAAS,QAAQ;EACjB,OAAO;CACT;CAEA,MAAM,SAAmB,CAAC;CAC1B,IAAI,OAAO;CACX,WAAW,MAAM,SAAS,UAAmC;EAC3D,QAAQ,MAAM;EACd,IAAI,OAAO,oBAAoB,OAAO;EACtC,OAAO,KAAK,KAAK;CACnB;CAGA,MAAM,UAAU,UADS,KAAK,MAAM,OAAO,OAAO,MAAM,CAAC,CAAC,SAAS,MAAM,CAC/C,GAAS,QAAQ,SAAS;CACpD,IAAI,CAAC,MAAM,QAAQ,OAAO,GAAG,OAAO;CAEpC,MAAM,yBAAS,IAAI,IAAY;CAC/B,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,KAAK,UAAU,OAAO,QAAQ,OAAO;EAC3C,IAAI,OAAO,OAAO,YAAY,CAAC,GAAG,KAAK,GAAG;EAE1C,IACE,QAAQ,YAAY,aACnB,UAAU,OAAO,cAAc,KAAK,UAAU,OAAO,aAAa,IAEnE;EAIF,IACE,QAAQ,YAAY,eACnB,UAAU,OAAO,QAAQ,MAAM,WAC9B,UAAU,OAAO,YAAY,MAAM,QAErC;EAEF,OAAO,IAAI,EAAE;CACf;CACA,OAAO,CAAC,GAAG,MAAM;AACnB;AAEA,eAAe,MAAM,SAAyD;CAC5E,MAAM,WAAW;EAAE,SAAS,QAAQ;EAAS,SAAS,QAAQ;CAAQ;CACtE,IAAI;EACF,MAAM,SAAS,MAAM,IAAI,SAA0B,SAAS,WAAW;GAUrE,IANE,QAAQ,UAAU,QAAQ,WAC1B;IAAE,OAAO;IAAO,QAAQ,YAAY,QAAQ,gBAAgB;GAAE,IAC7D,aAAa;IACZ,WAAW,UAAU,OAAO,CAAC,CAAC,KAAK,SAAS,MAAM;GACpD,CAEF,CAAA,CAAQ,KAAK,SAAS,MAAM;EAC9B,CAAC;EACD,IAAI,QAAQ,OAAO;GAAE,GAAG;GAAU,WAAW;GAAM;EAAO;CAC5D,QAAQ,CAER;CACA,OAAO;EAAE,GAAG;EAAU,WAAW;CAAM;AACzC;;AAGA,SAAgB,+BAEd;CACA,OAAO,QAAQ,IAAI,eAAe,IAAI,KAAK,CAAC;AAC9C"}

package/dist/manifest/static-manifest.js

@@ -3,7 +3,7 @@ var staticManifest = {
 	"version": "1.0.0",
 	"timestamp": 0,
 	"packageName": "@happyvertical/smrt-core",
-	"packageVersion": "0.60.8",
+	"packageVersion": "0.60.9",
 	"objects": {
 		"@happyvertical/smrt-core:SmrtClass": {
 			"name": "smrtclass",