ollanet 0.2.2 → 0.4.0

package/README.md

@@ -1,8 +1,16 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Catalyst-Forge-LLC/ollanet/main/assets/ollanet-logo.png" alt="ollanet logo" width="360">
+</p>
+
 # 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.
+
+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**.
+
+Scan for models, fire prompts, and continue conversations later by a short hash. No browser UI required. **Node 20+ · zero runtime deps.**
 
-Scan for models, fire prompts, and continue conversations later by a short hash. No browser UI required.
+**Site:** [ollanet.dev](https://ollanet.dev) — Downpress + Cloudflare Pages (`site/`).
 
 ## Origin
 
@@ -17,7 +25,7 @@ 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
 
@@ -26,6 +34,28 @@ They share the same Ollama API; Finetuna shapes the models, ollanet finds and ch
 - **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
+
+The core idea: turn “I have to remember which IP has which models loaded” into a discoverable, stateful, network-native primitive. That unlocks more than interactive chat:
+
+**For agents and automation** — prefer `ollanet mcp` (stdio MCP). The same flows also work via CLI flags:
+
+- **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.
+
+**For humans:**
+
+- **Tailscale-native access** — prompt any machine by MagicDNS name from a laptop or phone (Termux) without babysitting IPs or opening a browser.
+- **A private model mesh** — everyone on a shared tailnet or LAN can discover and use the same Ollama hosts, no public exposure, no central UI.
+- **Multi-GPU lab** — `scan --lan` treats several machines as a pool of inference endpoints; `bench` compares the same model across hardware.
+- **Audit trail / notes** — persisted chat JSON doubles as a research log you can resume from any device.
 
 ## Requirements
 
@@ -39,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
 ```
 
@@ -50,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
 ```
@@ -97,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 | Checkbox, 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 |
@@ -105,6 +178,7 @@ ollanet chats --id a1b2c3d4e5f6
 | `ollanet prompt …` | Send a prompt / continue a chat |
 | `ollanet chats` | List or inspect saved transcripts |
 | `ollanet bench …` | Benchmark models for tok/s + lightweight quality checks |
+| `ollanet mcp` | Stdio [MCP](https://modelcontextprotocol.io) server for agents |
 
 ### `scan` options
 
@@ -142,6 +216,36 @@ Machine can be a discovered name, hostname, FQDN, or IP (`192.168.1.50`, `host:1
 - `--json` — list summary JSON
 - `--id <hash>` — show one chat (full JSON with `--json`)
 
+### `mcp`
+
+```bash
+ollanet mcp
+```
+
+Runs a **stdio MCP server** (no extra npm deps). Cursor / Claude Desktop / any MCP host can spawn it and call:
+
+| Tool | What it does |
+|---|---|
+| `ollanet_scan` | Discover hosts + models (`lan`, `all` optional) |
+| `ollanet_prompt` | Prompt a host or continue with `chat_id` |
+| `ollanet_list_chats` | Summarize saved transcripts |
+| `ollanet_get_chat` | Load one chat (full history) |
+
+Example Cursor MCP config (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ollanet": {
+      "command": "npx",
+      "args": ["-y", "ollanet", "mcp"]
+    }
+  }
+}
+```
+
+Or, from a checkout: `"command": "pnpm"`, `"args": ["ollanet", "--", "mcp"]` (with `cwd` set to the repo). Uses the same config/chats dirs as the CLI (`~/.ollanet/` when installed).
+
 ### `bench`
 
 ```bash
@@ -250,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
@@ -259,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/cli.js

@@ -17,6 +17,7 @@ Usage:
   ollanet prompt --chat <hash> <prompt...>
   ollanet chats [--json] [--id <hash>]
   ollanet bench <machine|ip> [model...] [--all] [options]
+  ollanet mcp
 
 Examples:
   ollanet scan
@@ -27,6 +28,7 @@ Examples:
   ollanet chats
   ollanet bench localhost --all
   ollanet bench localhost llama3.2:1b --runs 3
+  ollanet mcp                  # stdio MCP server for agents
 
 Config: ~/.ollanet/config.json when installed, ./config.json in a checkout
         (override with OLLANET_CONFIG)
@@ -77,6 +79,11 @@ async function main() {
             await run();
             return;
         }
+        case "mcp": {
+            const { main: run } = await import("./mcp.js");
+            await run();
+            return;
+        }
         default:
             console.error(`Unknown command: ${cmd}\n`);
             process.stderr.write(HELP);

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. */
+    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>;