ollanet 0.3.0 → 0.4.1

package/README.md

@@ -4,11 +4,13 @@
 
 # ollanet
 
-Chat with **Ollama** servers on **any network you can reach** — LAN, localhost, Tailscale, VPN, or a raw IP.
+Find the models. Talk to them. Keep the thread.
 
-Scan for models, fire prompts, and continue conversations later by a short hash. No browser UI required.
+Chat with **Ollama** servers on **any network you can reach** — LAN, localhost, Tailscale, VPN, or a raw IP. CLI for humans, MCP for agents, **Node library for apps**.
 
-**Site:** [ollanet.dev](https://ollanet.dev) — Downpress + Cloudflare Pages (`site/`).
+Scan for models, fire prompts, and continue conversations later by a short hash. No browser UI required. **Node 20+ · zero runtime deps.**
+
+**Site:** [ollanet.dev](https://ollanet.dev) — FilePress + Cloudflare Pages (`site/`).
 
 ## Origin
 
@@ -23,16 +25,17 @@ Typical loop:
 1. On the host: `finetuna` → create something like `gemma4-ctx32k`
 2. From anywhere on the network: `ollanet scan` → `ollanet prompt that-host gemma4-ctx32k "…"`
 
-They share the same Ollama API; Finetuna shapes the models, ollanet finds and chats with them.
+They share the same Ollama API; Finetuna shapes the models, ollanet finds and chats with them. Host tunes the model. Network finds and uses it. Same API, closed loop.
 
 ## Features
 
-- **Discover** Ollama hosts from localhost, `config.hosts`, `OLLANET_HOSTS`, optional Tailscale, and optional LAN scan
+- **Discover** Ollama hosts from localhost, `config.hosts`, `OLLANET_HOSTS`, optional Tailscale, and optional LAN scan (`--lan`, off by default)
 - **Prompt** any hostname/IP/model with streaming replies
 - **Persist** chats as `responses/<hash>.json` with topic, machine, model, timestamps
 - **Continue** any thread with `--chat <hash>`
 - **Configure** per-machine defaults (model, temperature, context, …)
 - **MCP** — `ollanet mcp` exposes scan/prompt/chats as Model Context Protocol tools for agents
+- **Library** — `import { scanNetwork } from "ollanet"` for apps (Node 20+, not the browser)
 
 ## Use cases
 
@@ -43,6 +46,7 @@ The core idea: turn “I have to remember which IP has which models loaded” in
 - **Live model inventory / routing** — `ollanet_scan` (or `scan --json`) lists reachable hosts and models. Route each sub-task to the best host: the big-VRAM box for reasoning, the laptop for quick lookups.
 - **Conversations that survive machines** — chats are stored by short hash with full history. Start a long thread on the GPU box, continue it later with `ollanet_prompt` + `chat_id` (or `--chat <hash>`).
 - **A “talk to any Ollama on my network” tool** — `ollanet_prompt` / `prompt … --json --no-stream`; no hard-coded endpoints.
+- **Embed in an app** — same scan + pick + call as a library. The app does not own the GPUs; it discovers them (FilePress, CLIs, Electron, a local companion for a hosted product).
 - **Fleet health and speed checks** — periodic `ollanet bench <host> --json` builds a record of which model on which machine is currently fastest (or has silently gone offline). Saved results live in `benchmarks/`.
 - **The Finetuna loop** — [Finetuna](https://github.com/Catalyst-Forge-LLC/finetuna) shapes a GPU-tuned named variant on the host; ollanet discovers and uses it from anywhere on the network.
 
@@ -65,7 +69,7 @@ Tailscale is optional. If the `tailscale` CLI is present, peers are included aut
 Run without installing:
 
 ```bash
-npx ollanet scan                                                  # from npm (once published)
+npx ollanet scan
 npx --allow-git=all github:Catalyst-Forge-LLC/ollanet scan        # straight from GitHub
 ```
 
@@ -76,7 +80,7 @@ npx --allow-git=all github:Catalyst-Forge-LLC/ollanet scan        # straight fro
 Or install globally, which puts the `ollanet` command on your PATH:
 
 ```bash
-npm install -g ollanet                                            # from npm (once published)
+npm install -g ollanet
 npm install -g --allow-git=all github:Catalyst-Forge-LLC/ollanet  # from GitHub
 ollanet scan
 ```
@@ -123,6 +127,49 @@ ollanet chats
 ollanet chats --id a1b2c3d4e5f6
 ```
 
+## Use as a library
+
+ollanet is a **Node 20+ library that happens to have a CLI**. Not for the browser — discovery uses `node:net`, `child_process` (`tailscale status`), and `os.networkInterfaces()`. Call it from a dev server, CLI, Electron main, or a Worker with Node, never from Svelte/Vite client code.
+
+Hard-coding `http://127.0.0.1:11434` treats Ollama like a local daemon. This treats it like a **private inference mesh**: any machine you can already reach. The app does not own the GPUs; it discovers them. LAN scan is opt-in so you do not look like a port scanner. Tailscale is automatic if the CLI exists. Config lives in `~/.ollanet` unless you pass `config`.
+
+```ts
+import { scanNetwork } from "ollanet";
+
+const { servers, sources } = await scanNetwork({ lanScan: false });
+for (const s of servers) {
+  console.log(s.endpoint, s.models.map((m) => m.name));
+}
+```
+
+| Call | What it does | When apps should use it |
+|---|---|---|
+| `scanNetwork()` | localhost + config + `OLLANET_HOSTS` + Tailscale | Button / first “find servers” |
+| `scanNetwork({ lanScan: true })` | plus TCP sweep of local `/24`s on port 11434 | Checkbox; never the default scan, never on every health check |
+| `discoverHosts()` then probe yourself | candidates only, no `/api/tags` | If the app already has its own Ollama client |
+
+Pass `config` to skip the file (useful when the app already has its own config):
+
+```ts
+await scanNetwork({
+  lanScan: false,
+  config: {
+    hosts: ["studio.tailnet.ts.net", "192.168.1.50"],
+    discovery: { localhost: true, tailscale: true, lan: false },
+  },
+});
+```
+
+`runPrompt({ save: false, writeStdout: false })` is a one-shot call that does not write `~/.ollanet/responses/`.
+
+Requires **ollanet ≥ 0.4.0**. Bundlers (Vite / SvelteKit SSR):
+
+```ts
+// vite.config.ts
+ssr: { external: ["ollanet"] },
+optimizeDeps: { exclude: ["ollanet"] },
+```
+
 ## Commands
 
 | Command | Description |
@@ -307,6 +354,7 @@ The first turn asks the model for a short topic title (falls back to the prompt
 ```text
 ollanet/
   src/
+    index.ts          # public library entry (scan, discover, prompt, ollama helpers)
     cli.ts            # subcommand router (CLI entry)
     hosts.ts          # discovery + host resolution
     scan.ts
@@ -316,11 +364,13 @@ ollanet/
     config.ts
     paths.ts          # checkout vs installed path resolution
     ollama-chat.ts    # shared /api/chat (+ tags/show/ps helpers)
+    mcp.ts            # stdio MCP server
     bench.ts          # ollanet bench
     bench-suite.ts
     bench-store.ts
   dist/               # compiled output (published to npm)
   docs/bench-spec.md  # bench measurement spec
+  docs/library-api-spec.md
   config.json
   responses/          # gitignored chat history
   benchmarks/         # gitignored bench results

package/dist/bench-store.d.ts

@@ -0,0 +1,3 @@
+export declare function benchmarksDir(): string;
+export declare function newBenchId(): string;
+export declare function saveBenchmark(result: unknown): Promise<string>;

package/dist/bench-suite.d.ts

@@ -0,0 +1,25 @@
+export type CaseRole = "check" | "live" | "throughput";
+export interface BenchCase {
+    id: string;
+    role: CaseRole;
+    prompt: string;
+    /** Cap for this case; throughput uses settings.throughput_num_predict. */
+    num_predict?: number;
+    format?: "json";
+    check?: (content: string) => {
+        ok: boolean;
+        detail?: string;
+    };
+}
+export type SuiteName = "quick" | "full";
+export declare function getSuiteCases(suite: SuiteName): BenchCase[];
+export declare function suiteRevision(suite: SuiteName): string;
+export declare function comparabilityKey(opts: {
+    suite: SuiteName;
+    throughputNumPredict: number;
+    seed: number;
+    temperature: number;
+    think: boolean;
+    numCtx: number | null;
+}): string;
+export declare function median(values: number[]): number | undefined;

package/dist/bench.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;

package/dist/bench.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * ollanet bench — speed + lightweight quality suite against Ollama models.
  */

package/dist/chat-store.d.ts

@@ -0,0 +1,50 @@
+export type ChatRole = "system" | "user" | "assistant";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+    /** Present for thinking models when reasoning was returned separately. */
+    thinking?: string;
+    timestamp: string;
+    machine?: string;
+    model?: string;
+    stats?: {
+        eval_count?: number;
+        eval_duration?: number;
+        total_duration?: number;
+        prompt_eval_count?: number;
+    };
+}
+export interface ChatTranscript {
+    id: string;
+    topic: string;
+    created_at: string;
+    updated_at: string;
+    machine: string;
+    model: string;
+    system?: string;
+    messages: ChatMessage[];
+}
+export declare function responsesDir(): string;
+export declare function newChatId(): string;
+export declare function chatPath(id: string): string;
+export declare function normalizeChatId(id: string): string;
+export declare function ensureResponsesDir(): Promise<string>;
+export declare function loadChat(id: string): Promise<ChatTranscript>;
+export declare function saveChat(chat: ChatTranscript): Promise<string>;
+export declare function createChat(opts: {
+    machine: string;
+    model: string;
+    system?: string;
+    topic?: string;
+}): ChatTranscript;
+export declare function appendMessage(chat: ChatTranscript, message: Omit<ChatMessage, "timestamp"> & {
+    timestamp?: string;
+}): ChatMessage;
+export declare function listChats(): Promise<ChatTranscript[]>;
+/** Fallback topic from the first user message when model summarization fails. */
+export declare function topicFromPrompt(prompt: string): string;
+export declare function cleanTopic(raw: string, fallback: string): string;
+export declare function toApiMessages(chat: ChatTranscript): Array<{
+    role: ChatRole;
+    content: string;
+}>;

package/dist/chats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * List saved ollanet chats.
+ *
+ * Usage:
+ *   ollanet chats
+ *   ollanet chats --json
+ *   ollanet chats --id a1b2c3d4e5f6
+ */
+export declare function main(): Promise<void>;

package/dist/chats.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * List saved ollanet chats.
  *

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * ollanet — chat with Ollama servers on any reachable network.
+ *
+ *   ollanet scan
+ *   ollanet prompt <machine-or-ip> "hello"
+ *   ollanet chats
+ */
+export {};

package/dist/config.d.ts

@@ -0,0 +1,45 @@
+import { type DiscoveryConfig, type HostConfigEntry, type HostTarget } from "./hosts.js";
+export type { DiscoveryConfig, HostConfigEntry };
+/** Runtime knobs sent to Ollama `/api/generate`. */
+export interface GenerateSettings {
+    temperature?: number;
+    num_predict?: number;
+    num_ctx?: number;
+    /** Ollama `options.seed` (-1 = random). */
+    seed?: number;
+    keep_alive?: string | number;
+    /** `"json"` or a JSON-schema object */
+    format?: "json" | Record<string, unknown>;
+    system?: string;
+    /**
+     * Ollama "thinking" models (e.g. qwen3). When false/omitted, requests send
+     * `think: false` so tokens go to the visible reply instead of hidden reasoning.
+     */
+    think?: boolean;
+}
+export interface AppConfig {
+    /** Explicit hosts/IPs to probe (LAN, VPN, MagicDNS, etc.). */
+    hosts: HostConfigEntry[];
+    discovery: DiscoveryConfig;
+    defaultModels: Record<string, string>;
+    /** Global defaults applied to every prompt. */
+    defaults: GenerateSettings;
+    /** Per-machine overrides (keyed by short name / hostname / DNS / IP). */
+    machineDefaults: Record<string, GenerateSettings & {
+        model?: string;
+    }>;
+}
+/** Build an AppConfig from an in-memory partial (no file I/O). */
+export declare function configFromPartial(partial?: Partial<AppConfig>): AppConfig;
+export declare function loadConfig(): Promise<AppConfig>;
+export declare function normalizeSettings(input: unknown): GenerateSettings;
+export declare function parseFormat(value: unknown): GenerateSettings["format"] | undefined;
+export declare function hostLookupKeys(host: HostTarget): string[];
+/** Resolve a default model for a host using short name, hostname, DNS, or IP keys. */
+export declare function defaultModelForHost(config: AppConfig, host: HostTarget): string | undefined;
+export declare function machineSettingsForHost(config: AppConfig, host: HostTarget): GenerateSettings;
+/** Later layers win. Undefined values are skipped. */
+export declare function mergeSettings(...layers: Array<GenerateSettings | undefined>): GenerateSettings;
+export declare function settingsFromEnv(): GenerateSettings;
+export declare function settingsSummary(settings: GenerateSettings): string;
+export declare function configPath(): string;

package/dist/config.js

@@ -10,6 +10,17 @@ function emptyConfig() {
         machineDefaults: {},
     };
 }
+/** Build an AppConfig from an in-memory partial (no file I/O). */
+export function configFromPartial(partial = {}) {
+    const empty = emptyConfig();
+    return {
+        hosts: Array.isArray(partial.hosts) ? partial.hosts : empty.hosts,
+        discovery: partial.discovery ?? empty.discovery,
+        defaultModels: partial.defaultModels ?? empty.defaultModels,
+        defaults: partial.defaults ?? empty.defaults,
+        machineDefaults: partial.machineDefaults ?? empty.machineDefaults,
+    };
+}
 const CONFIG_PATH = process.env.OLLANET_CONFIG ??
     process.env.OLLAMA_CONFIG ??
     defaultConfigPath();

package/dist/hosts.d.ts

@@ -0,0 +1,55 @@
+/** Parse a required numeric env var; invalid values throw instead of becoming NaN. */
+export declare function envInt(name: string, fallback: number): number;
+/** Default Ollama port. Read at call time so a bad env var cannot break `import`. */
+export declare function ollamaPort(): number;
+export type HostSource = "localhost" | "config" | "env" | "tailscale" | "lan" | "direct";
+export type HostConfigEntry = string | {
+    name?: string;
+    host?: string;
+    ip?: string;
+    port?: number;
+};
+export interface DiscoveryConfig {
+    /** Always include localhost / 127.0.0.1 (default true). */
+    localhost?: boolean;
+    /** Use Tailscale peers when the CLI is available (default true). */
+    tailscale?: boolean;
+    /** TCP-scan local LAN CIDRs for open Ollama ports (default false). */
+    lan?: boolean;
+    /** Explicit CIDRs for LAN scan (default: guessed /24s from local interfaces). */
+    cidrs?: string[];
+}
+export interface HostTarget {
+    hostname: string;
+    dnsName: string;
+    ip: string;
+    online: boolean;
+    os: string;
+    isSelf: boolean;
+    source: HostSource;
+    port: number;
+}
+export interface DiscoveryResult {
+    hosts: HostTarget[];
+    sources: string[];
+    networkLabel: string;
+}
+export interface DiscoverOptions {
+    hosts?: HostConfigEntry[];
+    discovery?: DiscoveryConfig;
+    /** Include Tailscale peers marked offline. */
+    includeOffline?: boolean;
+    /** Probe local LAN CIDRs for open Ollama ports. Off unless true. */
+    lanScan?: boolean;
+}
+export declare function shortName(host: HostTarget): string;
+export declare function ollamaBaseUrl(host: HostTarget, port?: number): string;
+/** Discover candidate Ollama hosts from localhost, config, env, Tailscale, and optional LAN scan. */
+export declare function discoverHosts(opts?: DiscoverOptions): Promise<DiscoveryResult>;
+/**
+ * Match a query against already-discovered hosts only (no direct-address fallback).
+ * Used when peeling an optional leading hostname before a prompt.
+ */
+export declare function findDiscoveredHost(targets: HostTarget[], query: string): HostTarget | undefined;
+/** Resolve a machine name against discovered hosts, or treat it as a direct address. */
+export declare function resolveHost(targets: HostTarget[], query: string): HostTarget;

package/dist/hosts.js

@@ -14,7 +14,10 @@ export function envInt(name, fallback) {
     }
     return Math.trunc(n);
 }
-export const OLLAMA_PORT = envInt("OLLAMA_PORT", 11434);
+/** Default Ollama port. Read at call time so a bad env var cannot break `import`. */
+export function ollamaPort() {
+    return envInt("OLLAMA_PORT", 11434);
+}
 function cleanDnsName(dnsName) {
     if (!dnsName)
         return "";
@@ -29,7 +32,7 @@ export function shortName(host) {
     }
     return host.hostname;
 }
-export function ollamaBaseUrl(host, port = host.port || OLLAMA_PORT) {
+export function ollamaBaseUrl(host, port = host.port || ollamaPort()) {
     const hostPart = host.ip.includes(":") ? `[${host.ip}]` : host.ip;
     return `http://${hostPart}:${port}`;
 }
@@ -42,7 +45,7 @@ function makeHost(partial) {
         os: partial.os ?? "unknown",
         isSelf: partial.isSelf ?? false,
         source: partial.source,
-        port: partial.port ?? OLLAMA_PORT,
+        port: partial.port ?? ollamaPort(),
     };
 }
 function dedupeKey(host) {
@@ -114,7 +117,7 @@ function parseHostEntry(entry) {
         ip: address,
         source: "config",
         online: true,
-        port: typeof entry.port === "number" ? entry.port : OLLAMA_PORT,
+        port: typeof entry.port === "number" ? entry.port : ollamaPort(),
     });
 }
 function envHostTargets() {
@@ -298,7 +301,7 @@ function parseDirectAddress(query) {
         return null;
     let hostname = q;
     let ip = q;
-    let port = OLLAMA_PORT;
+    let port = ollamaPort();
     const ipv4WithPort = q.match(/^(\d{1,3}(?:\.\d{1,3}){3}):(\d+)$/);
     if (ipv4WithPort) {
         ip = ipv4WithPort[1];
@@ -365,7 +368,7 @@ export async function discoverHosts(opts = {}) {
     const lanEnabled = opts.lanScan ?? discovery.lan === true;
     if (lanEnabled) {
         const cidrs = discovery.cidrs && discovery.cidrs.length > 0 ? discovery.cidrs : guessLocalCidrs();
-        const lanHosts = await lanScanTargets(cidrs, OLLAMA_PORT);
+        const lanHosts = await lanScanTargets(cidrs, ollamaPort());
         if (lanHosts.length > 0) {
             collected.push(...lanHosts);
             sources.push("lan");

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ollanet — Node library for discovering and talking to Ollama on any
+ * reachable network (loopback, LAN, Tailscale, VPN).
+ *
+ * Node 20+ only. Not for the browser. LAN scan is opt-in.
+ *
+ *   import { scanNetwork } from "ollanet";
+ *   const { servers } = await scanNetwork({ lanScan: false });
+ */
+export { scanNetwork } from "./scan.js";
+export type { ScanOptions, ScanPayload, ScannedServer } from "./scan.js";
+export { discoverHosts, resolveHost, ollamaBaseUrl, shortName, ollamaPort, } from "./hosts.js";
+export type { DiscoverOptions, DiscoveryResult, HostTarget, HostSource, HostConfigEntry, } from "./hosts.js";
+export { loadConfig, defaultModelForHost, mergeSettings, configFromPartial, } from "./config.js";
+export type { AppConfig, DiscoveryConfig, GenerateSettings } from "./config.js";
+export { runPrompt } from "./prompt.js";
+export type { PromptRunOptions, PromptRunResult } from "./prompt.js";
+export { ollamaChat, ollamaTags, ollamaShow, ollamaPs } from "./ollama-chat.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * ollanet — Node library for discovering and talking to Ollama on any
+ * reachable network (loopback, LAN, Tailscale, VPN).
+ *
+ * Node 20+ only. Not for the browser. LAN scan is opt-in.
+ *
+ *   import { scanNetwork } from "ollanet";
+ *   const { servers } = await scanNetwork({ lanScan: false });
+ */
+export { scanNetwork } from "./scan.js";
+export { discoverHosts, resolveHost, ollamaBaseUrl, shortName, ollamaPort, } from "./hosts.js";
+export { loadConfig, defaultModelForHost, mergeSettings, configFromPartial, } from "./config.js";
+export { runPrompt } from "./prompt.js";
+export { ollamaChat, ollamaTags, ollamaShow, ollamaPs } from "./ollama-chat.js";

package/dist/mcp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ollanet mcp — stdio MCP server (zero deps).
+ *
+ * Speaks the Model Context Protocol over stdin/stdout so agents (Cursor,
+ * Claude Desktop, etc.) can discover hosts, prompt models, and continue chats.
+ *
+ *   ollanet mcp
+ *
+ * stdout is reserved for JSON-RPC; log only to stderr.
+ */
+export declare function main(): Promise<void>;

package/dist/mcp.js

@@ -14,13 +14,15 @@ import { listChats, loadChat } from "./chat-store.js";
 import { projectPath } from "./paths.js";
 import { runPrompt } from "./prompt.js";
 import { scanNetwork } from "./scan.js";
+// Pin to the oldest widely-supported MCP revision. Clients may request a newer
+// date; we still answer with this — legal negotiation, max compatibility.
 const PROTOCOL_VERSION = "2024-11-05";
 const TOOLS = [
     {
         name: "ollanet_scan",
         description: "Discover reachable Ollama hosts and list their models. " +
             "Use this before routing work to pick a host/model. " +
-            "Optional LAN TCP scan (--lan equivalent) and include offline Tailscale peers.",
+            "Optional LAN TCP scan (off unless lan=true; equivalent to CLI --lan) and include offline Tailscale peers.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/ollama-chat.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared Ollama /api/chat client used by prompt and bench.
+ */
+import type { GenerateSettings } from "./config.js";
+export interface ChatChunk {
+    model?: string;
+    message?: {
+        role?: string;
+        content?: string;
+        thinking?: string;
+    };
+    done?: boolean;
+    done_reason?: string;
+    error?: string;
+    total_duration?: number;
+    load_duration?: number;
+    prompt_eval_count?: number;
+    eval_count?: number;
+    eval_duration?: number;
+}
+export interface OllamaChatOptions {
+    baseUrl: string;
+    model: string;
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    stream: boolean;
+    settings: GenerateSettings;
+    /** Write assistant content to stdout / thinking to stderr when streaming. */
+    writeStdout: boolean;
+    /** Timeout in ms; 0 = none. */
+    timeoutMs: number;
+}
+export interface OllamaChatResult {
+    content: string;
+    thinking: string;
+    chunk: ChatChunk;
+}
+/** POST /api/chat with optional streaming and AbortSignal timeout. */
+export declare function ollamaChat(opts: OllamaChatOptions): Promise<OllamaChatResult>;
+export interface OllamaModelInfo {
+    name: string;
+    digest?: string;
+    size?: number;
+    details?: {
+        parameter_size?: string;
+        quantization_level?: string;
+        family?: string;
+    };
+}
+export declare function ollamaTags(baseUrl: string, timeoutMs: number): Promise<OllamaModelInfo[]>;
+export declare function ollamaShow(baseUrl: string, model: string, timeoutMs: number): Promise<{
+    capabilities?: string[];
+}>;
+export declare function ollamaVersion(baseUrl: string, timeoutMs: number): Promise<string | undefined>;
+export interface PsModel {
+    name?: string;
+    model?: string;
+    size_vram?: number;
+    context_length?: number;
+    digest?: string;
+}
+export declare function ollamaPs(baseUrl: string, timeoutMs: number): Promise<PsModel[]>;
+export declare function psHasModel(models: PsModel[], name: string): boolean;
+export declare function vramForModel(models: PsModel[], name: string): number | undefined;
+export declare function contextLengthForModel(models: PsModel[], name: string): number | undefined;
+/**
+ * Capability filter: omitempty / empty means "unknown → treat as completion".
+ * Only skip when a non-empty capabilities array is present and lacks completion.
+ */
+export declare function isCompletionCapable(capabilities: string[] | undefined | null): boolean;
+/**
+ * Vision-capable models (moondream, llava, …) often fail a text-only suite.
+ * Only true when capabilities are present and include vision — absent/empty → false
+ * (don't skip unknown older servers).
+ */
+export declare function isVisionCapable(capabilities: string[] | undefined | null): boolean;
+/** True when capabilities are known and lack thinking (absent/empty → no warning). */
+export declare function shouldWarnNoThinking(capabilities: string[] | undefined | null): boolean;
+/** Poll /api/ps until model is absent (or timeout). Returns elapsed ms. */
+export declare function waitUntilUnloaded(baseUrl: string, model: string, timeoutMs: number, pollMs?: number): Promise<{
+    unloaded: boolean;
+    waitedMs: number;
+}>;
+/** Request unload via keep_alive: 0 (no-op-ish if already unloaded after a short chat). */
+export declare function ollamaUnload(baseUrl: string, model: string, timeoutMs: number): Promise<void>;

package/dist/paths.d.ts

@@ -0,0 +1,17 @@
+/** Package root: parent of `src/` in a checkout, parent of `dist/` when installed. */
+export declare const PROJECT_ROOT: string;
+export declare function projectPath(...parts: string[]): string;
+/**
+ * True when running from an installed copy (npx cache, global install, or as a
+ * dependency) rather than a source checkout. Installed copies always live under
+ * a `node_modules` directory.
+ */
+export declare const IS_INSTALLED: boolean;
+/** Per-user data dir used when installed (config + chat transcripts). */
+export declare const USER_DIR: string;
+/** Default config location: repo-local in a checkout, `~/.ollanet/` when installed. */
+export declare function defaultConfigPath(): string;
+/** Default transcript dir: repo-local in a checkout, `~/.ollanet/` when installed. */
+export declare function defaultResponsesDir(): string;
+/** Default benchmark results dir (mirrors responses layout). */
+export declare function defaultBenchmarksDir(): string;

package/dist/prompt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Run a prompt / continue a chat against an Ollama server on the network.
+ *
+ * New chat (saved by default):
+ *   ollanet prompt localhost "What is Tailscale?"
+ *   ollanet prompt 192.168.1.50 "Hello"
+ *
+ * Continue:
+ *   ollanet prompt --chat a1b2c3d4e5f6 "Tell me more"
+ *
+ * List chats:
+ *   ollanet chats
+ */
+import { type AppConfig, type GenerateSettings } from "./config.js";
+export interface PromptRunOptions {
+    machine?: string;
+    model?: string;
+    prompt: string;
+    chatId?: string;
+    /** Persist transcript. Default true; pass false for one-shot app calls. */
+    save?: boolean;
+    settings?: GenerateSettings;
+    /** When false, never write the reply to stdout (MCP / programmatic). Default true for CLI. */
+    writeStdout?: boolean;
+    stream?: boolean;
+    quiet?: boolean;
+    /** In-memory config; skips the config file when set. */
+    config?: Partial<AppConfig>;
+}
+export interface PromptRunResult {
+    chat_id: string | null;
+    topic: string;
+    content: string;
+    thinking: string | null;
+    machine: string;
+    model: string;
+    ollama: Record<string, unknown>;
+}
+/** Programmatic prompt used by CLI `--json` and the MCP server. */
+export declare function runPrompt(opts: PromptRunOptions): Promise<PromptRunResult>;
+export declare function main(): Promise<void>;

package/dist/prompt.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * Run a prompt / continue a chat against an Ollama server on the network.
  *
@@ -14,11 +13,13 @@
  */
 import { stdin as stdinStream } from "node:process";
 import { appendMessage, cleanTopic, createChat, loadChat, saveChat, toApiMessages, topicFromPrompt, } from "./chat-store.js";
-import { configPath, defaultModelForHost, loadConfig, machineSettingsForHost, mergeSettings, parseFormat, settingsFromEnv, settingsSummary, } from "./config.js";
+import { configPath, defaultModelForHost, loadConfig, machineSettingsForHost, mergeSettings, parseFormat, settingsFromEnv, settingsSummary, configFromPartial, } from "./config.js";
 import { discoverHosts, envInt, findDiscoveredHost, ollamaBaseUrl, resolveHost, shortName, } from "./hosts.js";
 import { ollamaChat } from "./ollama-chat.js";
 /** Prompt/chat HTTP timeout (ms). 0 = no timeout. Separate from scan's OLLAMA_TIMEOUT_MS. */
-const PROMPT_TIMEOUT_MS = envInt("OLLAMA_PROMPT_TIMEOUT_MS", 600_000);
+function promptTimeoutMs() {
+    return envInt("OLLAMA_PROMPT_TIMEOUT_MS", 600_000);
+}
 function usage() {
     console.error(`Usage:
   ollanet prompt <machine> [model] <prompt...>
@@ -77,7 +78,7 @@ function modelNameMatches(available, candidate) {
 async function listModelNames(host) {
     const url = `${ollamaBaseUrl(host)}/api/tags`;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), Math.min(PROMPT_TIMEOUT_MS || 2500, 5000));
+    const timer = setTimeout(() => controller.abort(), Math.min(promptTimeoutMs() || 2500, 5000));
     try {
         const res = await fetch(url, {
             signal: controller.signal,
@@ -278,7 +279,7 @@ async function generateTopic(opts) {
             model: opts.model,
             stream: false,
             writeStdout: false,
-            timeoutMs: PROMPT_TIMEOUT_MS,
+            timeoutMs: promptTimeoutMs(),
             settings: mergeSettings(opts.settings, {
                 temperature: 0.2,
                 num_predict: 24,
@@ -315,7 +316,7 @@ export async function runPrompt(opts) {
     const quiet = opts.quiet === true || opts.writeStdout === false;
     const writeStdout = opts.writeStdout !== false;
     let promptParts = opts.prompt ? [opts.prompt] : [];
-    const config = await loadConfig();
+    const config = opts.config ? configFromPartial(opts.config) : await loadConfig();
     const { hosts: targets } = await discoverHosts({
         hosts: config.hosts,
         discovery: config.discovery,
@@ -388,7 +389,7 @@ export async function runPrompt(opts) {
         messages: toApiMessages(chat),
         stream: writeStdout ? stream : false,
         writeStdout,
-        timeoutMs: PROMPT_TIMEOUT_MS,
+        timeoutMs: promptTimeoutMs(),
         settings,
     });
     appendMessage(chat, {

package/dist/scan.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Scan reachable networks for Ollama servers and list available models.
+ *
+ * Usage: ollanet scan [--lan] [--json] [--all]
+ */
+import { type AppConfig } from "./config.js";
+export interface ScanOptions {
+    includeOffline?: boolean;
+    /** TCP-scan local /24s for Ollama (port 11434 by default). Off unless set. */
+    lanScan?: boolean;
+    /**
+     * In-memory config. When set, the config file (`~/.ollanet` / `OLLANET_CONFIG`)
+     * is not read. Omit to keep CLI/MCP file behavior.
+     */
+    config?: Partial<AppConfig>;
+}
+export interface ScannedServer {
+    hostname: string;
+    dnsName: string;
+    ip: string;
+    port: number;
+    os: string;
+    source: string;
+    self: boolean;
+    endpoint: string;
+    models: Array<{
+        name: string;
+        size?: number;
+        modified_at?: string;
+        parameter_size?: string;
+        quantization_level?: string;
+        family?: string;
+    }>;
+}
+export interface ScanPayload {
+    network: string;
+    sources: string[];
+    port: number;
+    scanned: number;
+    servers: ScannedServer[];
+}
+/** Programmatic scan used by CLI `--json`, MCP, and `import { scanNetwork } from "ollanet"`. */
+export declare function scanNetwork(options?: ScanOptions): Promise<ScanPayload>;
+export declare function main(): Promise<void>;

package/dist/scan.js

@@ -1,13 +1,16 @@
-#!/usr/bin/env node
 /**
  * Scan reachable networks for Ollama servers and list available models.
  *
  * Usage: ollanet scan [--lan] [--json] [--all]
  */
-import { loadConfig } from "./config.js";
-import { OLLAMA_PORT, discoverHosts, envInt, shortName, } from "./hosts.js";
-const TIMEOUT_MS = envInt("OLLAMA_TIMEOUT_MS", 2500);
-const CONCURRENCY = Math.max(1, envInt("OLLAMA_CONCURRENCY", 16));
+import { configFromPartial, loadConfig } from "./config.js";
+import { discoverHosts, envInt, ollamaPort, shortName, } from "./hosts.js";
+function scanTimeoutMs() {
+    return envInt("OLLAMA_TIMEOUT_MS", 2500);
+}
+function scanConcurrency() {
+    return Math.max(1, envInt("OLLAMA_CONCURRENCY", 16));
+}
 function formatBytes(bytes) {
     if (bytes == null || !Number.isFinite(bytes))
         return "";
@@ -22,8 +25,9 @@ function formatBytes(bytes) {
 }
 async function fetchModels(host) {
     const url = `http://${host.ip.includes(":") ? `[${host.ip}]` : host.ip}:${host.port}/api/tags`;
+    const timeoutMs = scanTimeoutMs();
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
             signal: controller.signal,
@@ -66,7 +70,7 @@ async function scanHost(host) {
         const name = err instanceof Error ? err.name : "";
         const message = err instanceof Error ? err.message : String(err);
         const error = name === "AbortError" || message.toLowerCase().includes("abort")
-            ? `timeout after ${TIMEOUT_MS}ms`
+            ? `timeout after ${scanTimeoutMs()}ms`
             : message;
         return { host, ok: false, models: [], error, url };
     }
@@ -117,7 +121,7 @@ function toPayload(results, networkLabel, sources) {
     return {
         network: networkLabel,
         sources,
-        port: OLLAMA_PORT,
+        port: ollamaPort(),
         scanned: results.length,
         servers: results
             .filter((r) => r.ok)
@@ -141,9 +145,9 @@ function toPayload(results, networkLabel, sources) {
         })),
     };
 }
-/** Programmatic scan used by CLI `--json` and the MCP server. */
+/** Programmatic scan used by CLI `--json`, MCP, and `import { scanNetwork } from "ollanet"`. */
 export async function scanNetwork(options = {}) {
-    const config = await loadConfig();
+    const config = options.config ? configFromPartial(options.config) : await loadConfig();
     const { hosts, sources, networkLabel } = await discoverHosts({
         hosts: config.hosts,
         discovery: config.discovery,
@@ -153,7 +157,7 @@ export async function scanNetwork(options = {}) {
     if (hosts.length === 0) {
         throw new Error("No hosts to scan. Add config.hosts, set OLLANET_HOSTS, or enable Tailscale/LAN discovery.");
     }
-    const results = await mapPool(hosts, CONCURRENCY, scanHost);
+    const results = await mapPool(hosts, scanConcurrency(), scanHost);
     return toPayload(results, networkLabel, sources);
 }
 export async function main() {
@@ -172,7 +176,7 @@ export async function main() {
         process.exitCode = 1;
         return;
     }
-    const results = await mapPool(hosts, CONCURRENCY, scanHost);
+    const results = await mapPool(hosts, scanConcurrency(), scanHost);
     if (jsonOut) {
         console.log(JSON.stringify(toPayload(results, networkLabel, sources), null, 2));
         return;

package/package.json

@@ -1,19 +1,31 @@
 {
   "name": "ollanet",
-  "version": "0.3.0",
-  "description": "Chat with Ollama servers on any reachable network — scan hosts, prompt models, continue chats by hash, MCP for agents",
+  "version": "0.4.1",
+  "description": "Discover and talk to Ollama on any reachable network — CLI, MCP, and a Node library",
   "type": "module",
   "bin": {
     "ollanet": "./dist/cli.js"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./scan": {
+      "types": "./dist/scan.d.ts",
+      "import": "./dist/scan.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepare": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
+    "prepare": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
     "ollanet": "tsx src/cli.ts",
     "scan": "tsx src/cli.ts scan",
     "prompt": "tsx src/cli.ts prompt",
@@ -22,7 +34,7 @@
     "mcp": "tsx src/cli.ts mcp",
     "start": "tsx src/cli.ts scan",
     "typecheck": "tsc --noEmit",
-    "test": "tsc -p tsconfig.build.json && node --test test/*.test.mjs",
+    "test": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs && node --test test/*.test.mjs",
     "test:only": "node --test test/*.test.mjs",
     "site:dev": "pnpm --dir site dev",
     "site:build": "pnpm --dir site build",
@@ -37,7 +49,8 @@
     "tailscale",
     "network",
     "mcp",
-    "model-context-protocol"
+    "model-context-protocol",
+    "library"
   ],
   "author": "Catalyst Forge LLC",
   "license": "MIT",