@gjsify/local-ai-servers 0.0.0-stage → 0.64.19

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @gjsify/local-ai-servers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find the local inference servers that are running (Ollama, LM Studio, llama.cpp's `llama-server`) and the models they have loaded, so an app can reuse a loaded model through the server's OpenAI-compatible endpoint instead of loading a second copy into the same GPU.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project. **Tier 3 (experimental, ADR 0003)**: tested against mocked server responses, not yet against live servers. Design: ADR 0136.
+
+## Installation
+
+```bash
+gjsify install @gjsify/local-ai-servers
+```
+
+## Usage
+
+```typescript
+import { discoverLocalServers, loadedModels } from '@gjsify/local-ai-servers';
+
+const servers = await discoverLocalServers();
+const [first] = loadedModels(servers);
+if (first) {
+    // Hand the endpoint to your own OpenAI-compatible client.
+    client.connect({ baseUrl: first.server.openAiBaseUrl, model: first.model.id });
+}
+```
+
+## What it asks, and what it never does
+
+- Only fixed loopback addresses: Ollama on `127.0.0.1:11434` (or `OLLAMA_HOST`), LM Studio on `127.0.0.1:1234`, `llama-server` on `127.0.0.1:8080`. Never a port scan, never the LAN.
+- Only listing endpoints (`/api/tags`, `/api/ps`, `/api/v0/models`, `/v1/models`), each with a 500 ms timeout. Never inference.
+- A response with the wrong shape means "not that server". A program that answers the OpenAI listing without identifying itself is reported as `openai-compatible`.
+- Nothing runs until the app calls it.
+
+## Options
+
+- `fetch`: injectable; defaults to the runtime's global `fetch`.
+- `env`: where `OLLAMA_HOST` is read from; defaults to `process.env`.
+- `timeoutMs`: per request.
+- `probes`: replace the defaults, for example `[ollamaProbe('http://127.0.0.1:11500')]`.
+
+Each model carries `loaded` (`true`, `false`, or `undefined` when the server does not say) and, for Ollama, `sizeBytes` and `vramBytes`.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/discover.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=500,isRecord=e=>typeof e==`object`&&!!e&&!Array.isArray(e),optionalBytes=e=>typeof e==`number`&&Number.isFinite(e)&&e>=0?e:void 0;function openAiModels(e){if(!isRecord(e)||!Array.isArray(e.data))return;let t=e.data.filter(isRecord);if(!(t.length!==e.data.length||!t.every(e=>typeof e.id==`string`)))return t}function ollamaOrigin(e={}){let t=(e.OLLAMA_HOST??``).trim();if(t===``)return`http://127.0.0.1:11434`;let n=`http`,r=t,i=`11434`,a=t.indexOf(`://`);a>=0&&(n=t.slice(0,a).toLowerCase(),r=t.slice(a+3),n===`http`&&(i=`80`),n===`https`&&(i=`443`)),r=r.split(`/`)[0];let o=r,s=i,c=/^\[([^\]]+)\](?::(\d+))?$/.exec(r);return c?(o=c[1],s=c[2]??i):/^[^:]*:\d*$/.test(r)&&([o,s]=r.split(`:`),s===``&&(s=i)),(o===``||o===`0.0.0.0`)&&(o=`127.0.0.1`),o===`::`&&(o=`::1`),`${n}://${o.includes(`:`)?`[${o}]`:o}:${s}`}function ollamaProbe(e){return{kind:`ollama`,origin:e,async detect(t){let n=await t(`/api/tags`);if(!isRecord(n)||!Array.isArray(n.models))return;let r=n.models.filter(isRecord).filter(e=>typeof e.name==`string`),i=await t(`/api/ps`).catch(()=>void 0),a=isRecord(i)&&Array.isArray(i.models)?new Map(i.models.filter(isRecord).filter(e=>typeof e.name==`string`).map(e=>[e.name,e])):void 0,o=r.map(e=>{let t=a?.get(e.name);return{id:e.name,loaded:a===void 0?void 0:t!==void 0,sizeBytes:optionalBytes(e.size),vramBytes:t===void 0?void 0:optionalBytes(t.size_vram)}});return{kind:`ollama`,origin:e,openAiBaseUrl:`${e}/v1`,models:o}}}}function lmStudioProbe(e=`http://127.0.0.1:1234`){return{kind:`lm-studio`,origin:e,async detect(t){let n=openAiModels(await t(`/api/v0/models`).catch(()=>void 0));if(n?.every(e=>typeof e.state==`string`)){let t=n.map(e=>({id:e.id,loaded:e.state===`loaded`}));return{kind:`lm-studio`,origin:e,openAiBaseUrl:`${e}/v1`,models:t}}let r=openAiModels(await t(`/v1/models`));if(r===void 0)return;let i=r.map(e=>({id:e.id,loaded:void 0}));return{kind:`openai-compatible`,origin:e,openAiBaseUrl:`${e}/v1`,models:i}}}}function llamaCppProbe(e=`http://127.0.0.1:8080`){return{kind:`llama-cpp`,origin:e,async detect(t){let n=openAiModels(await t(`/v1/models`));if(n===void 0)return;let r=n.length>0&&n.every(e=>e.owned_by===`llamacpp`),i=n.map(e=>{let t=isRecord(e.status)?e.status.value:void 0;return{id:e.id,loaded:typeof t==`string`?t===`loaded`:r?!0:void 0}});return{kind:r?`llama-cpp`:`openai-compatible`,origin:e,openAiBaseUrl:`${e}/v1`,models:i}}}}function defaultProbes(e={}){return[ollamaProbe(ollamaOrigin(e)),lmStudioProbe(),llamaCppProbe()]}function jsonGetter(e,t,n){return async r=>{let i=new AbortController,a=setTimeout(()=>i.abort(),n);try{let n=await t(`${e}${r}`,{signal:i.signal});if(!n.ok)throw Error(`${e}${r}: HTTP ${n.status}`);return await n.json()}finally{clearTimeout(a)}}}async function discoverLocalServers(e={}){let t=e.fetch??((e,t)=>globalThis.fetch(e,t)),n=e.timeoutMs??500,r=e.probes??defaultProbes(e.env??globalThis.process?.env??{});return(await Promise.all(r.map(e=>e.detect(jsonGetter(e.origin,t,n)).catch(()=>void 0)))).filter(e=>e!==void 0)}function loadedModels(e){return e.flatMap(e=>e.models.filter(e=>e.loaded===!0).map(t=>({server:e,model:t})))}export{e as DEFAULT_TIMEOUT_MS,defaultProbes,discoverLocalServers,llamaCppProbe,lmStudioProbe,loadedModels,ollamaOrigin,ollamaProbe};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{DEFAULT_TIMEOUT_MS as e,defaultProbes as t,discoverLocalServers as n,llamaCppProbe as r,lmStudioProbe as i,loadedModels as a,ollamaOrigin as o,ollamaProbe as s}from"./discover.js";export{e as DEFAULT_TIMEOUT_MS,t as defaultProbes,n as discoverLocalServers,r as llamaCppProbe,i as lmStudioProbe,a as loadedModels,o as ollamaOrigin,s as ollamaProbe};

package/lib/types/discover.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which local inference servers are running, and which models they have loaded (ADR 0136).
+ *
+ * An app that finds a model already loaded in Ollama, LM Studio or llama.cpp's server can use it
+ * through that server's OpenAI-compatible endpoint instead of loading a second copy into the
+ * same GPU. This module only FINDS them: it reads each server's listing endpoints and returns
+ * where to send requests. Inference goes through the app's own OpenAI-compatible client
+ * (ADR 0132 decision 6), never through this package.
+ *
+ * WHAT IT ASKS, AND WHAT IT NEVER DOES. Only the fixed loopback addresses these servers listen on
+ * by default, plus `OLLAMA_HOST` when the user set it — never a port scan, never the LAN. Each
+ * request has a short timeout, and a response that does not have the expected shape is "not that
+ * server", so another program on port 8080 is not mistaken for one. Nothing here runs unless the
+ * app calls it.
+ */
+export type LocalServerKind = 'ollama' | 'lm-studio' | 'llama-cpp' | 'openai-compatible';
+export interface LocalModel {
+    readonly id: string;
+    /** In memory now; `undefined` when the server does not say. */
+    readonly loaded: boolean | undefined;
+    /** On-disk size, where the server reports it. */
+    readonly sizeBytes?: number;
+    /** GPU memory the loaded model holds (Ollama's `size_vram`). */
+    readonly vramBytes?: number;
+}
+export interface LocalServer {
+    readonly kind: LocalServerKind;
+    /** `http://127.0.0.1:11434` — what was asked. */
+    readonly origin: string;
+    /** Base URL for an OpenAI-compatible client: `<origin>/v1`. */
+    readonly openAiBaseUrl: string;
+    readonly models: readonly LocalModel[];
+}
+export type FetchLike = (url: string, init: {
+    signal: AbortSignal;
+}) => Promise<Response>;
+/** One kind of server at one address. */
+export interface ServerProbe {
+    readonly kind: LocalServerKind;
+    readonly origin: string;
+    detect(getJson: (path: string) => Promise<unknown>): Promise<LocalServer | undefined>;
+}
+export interface DiscoverOptions {
+    readonly fetch?: FetchLike;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Per request; a local server answers in milliseconds, a missing one should not cost more. */
+    readonly timeoutMs?: number;
+    /** Defaults to {@link defaultProbes} for `env`. */
+    readonly probes?: readonly ServerProbe[];
+}
+export declare const DEFAULT_TIMEOUT_MS = 500;
+/**
+ * The address Ollama's own CLI would talk to, read from `OLLAMA_HOST` the way Ollama reads it:
+ * scheme optional (`http`), port 11434 unless a scheme is given without one. A server bound to
+ * every interface (`0.0.0.0`, `::`) is reached on loopback.
+ */
+export declare function ollamaOrigin(env?: Readonly<Record<string, string | undefined>>): string;
+export declare function ollamaProbe(origin: string): ServerProbe;
+export declare function lmStudioProbe(origin?: string): ServerProbe;
+/**
+ * llama.cpp's `llama-server`, recognised by `owned_by: "llamacpp"` in its listing. Anything else
+ * answering the OpenAI listing on the same port is reported as `openai-compatible` — usable the
+ * same way, without the claim about which program it is.
+ */
+export declare function llamaCppProbe(origin?: string): ServerProbe;
+export declare function defaultProbes(env?: Readonly<Record<string, string | undefined>>): ServerProbe[];
+/**
+ * Ask every probe at once and return the servers that answered as themselves, in probe order.
+ * A server that is down, slow or something else is left out, never an error.
+ */
+export declare function discoverLocalServers(options?: DiscoverOptions): Promise<LocalServer[]>;
+/** Every loaded model across `servers`, with the server to reach it through. */
+export declare function loadedModels(servers: readonly LocalServer[]): {
+    server: LocalServer;
+    model: LocalModel;
+}[];

package/lib/types/discover.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1 @@
+export * from './discover.js';

package/package.json

@@ -1,6 +1,67 @@
 {
-  "name": "@gjsify/local-ai-servers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/local-ai-servers",
+    "version": "0.64.19",
+    "description": "Find local inference servers (Ollama, LM Studio, llama.cpp) and the models they have loaded, so an app can reuse one through its OpenAI-compatible endpoint instead of loading a second copy. Loopback only, short timeouts, never inference.",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "type": "module",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "!lib/types/**/*.spec.d.ts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs"
+    },
+    "keywords": [
+        "ollama",
+        "lm-studio",
+        "llama.cpp",
+        "openai-compatible",
+        "local-ai",
+        "discovery"
+    ],
+    "devDependencies": {
+        "@gjsify/cli": "^0.64.19",
+        "@gjsify/fetch": "^0.64.19",
+        "@gjsify/unit": "^0.64.19",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/gjs/local-ai-servers"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/gjs/local-ai-servers#readme",
+    "gjsify": {
+        "tier": 3,
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "headless": true
+    }
+}