@vornrun/connector-ollama 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@vornrun/connector-ollama`.
+
+## 0.1.0
+
+First release.
+
+Trigger a workflow when a model on a local Ollama server is added, updated or
+loaded into memory, and let a workflow step chat, generate a completion,
+embed text, and list, show, pull, copy or delete models.
+
+- **Triggers:** `modelChanged`, `modelLoaded`.
+- **Actions:** `chat`, `generate`, `embed`, `listModels`, `showModel`,
+  `listRunningModels`, `version`, `pullModel`, `deleteModel`, `copyModel`.
+- **Signing in:** none. The one setting is the server URL from
+  `OLLAMA_HOST`, `http://localhost:11434` by default, with a trailing `/api`
+  stripped and a bare `host:port` given `http://`. A hosted or proxied server
+  takes its key from `OLLAMA_API_KEY` in the environment, sent as
+  `Authorization: Bearer` only when set; the SDK refuses a secret config
+  field on a connector with no sign-in, so a host that does not pass its
+  environment through cannot supply the key.
+
+Every action and both polls go through one small client rather than declared
+SDK requests, because a declared request cannot express what the API needs:
+a 10 minute timeout on chat, generate and pull against 30 seconds elsewhere,
+`stream: false` on every generation, a Bearer header read from the
+environment, one retry after two seconds on a connection refused with the
+note that the server may be starting, and the 404 `model '<name>' not found`
+reported as `Model '<name>' is not present on the server; pull it first`
+without ever pulling on the caller's behalf. Every other failure is reported
+as the server's `error` message with the HTTP status, and every generation
+returns the reply as `raw` beside the text, `doneReason` and the nanosecond
+timings.
+
+Both triggers poll on the SDK's timestamp dedupe strategy. Models are keyed
+`<name>@<digest>` and stamped with `modified_at`, so a pull that changes a
+digest fires again and the first poll delivers every model present. Loaded
+models are keyed `<name>@<expires_at>` and stamped with `expires_at`, so a
+model fires each time it appears with an expiry not yet seen. Both times are
+reduced to UTC milliseconds for the cursor; the raw values stay on the item.
+
+Ships as a pack with a conformance receipt covering the dedupe replay of both
+triggers and the mock run of every action. No runtime dependencies: `fetch`,
+`AbortController` and `JSON` cover the client.

package/README.md

@@ -0,0 +1,131 @@
+# @vornrun/connector-ollama
+
+Trigger Vorn workflows when a model on a local Ollama server is added,
+updated or loaded into memory, and chat, generate a completion, embed text,
+and list, show, pull, copy or delete models from a workflow step. Talks to
+the Ollama REST API at `http://localhost:11434/api` by default.
+
+## Signing in
+
+Nothing to sign in with: Ollama binds `127.0.0.1:11434` and its API takes no
+credentials, so the connector declares `auth: { rung: 'none' }`. The only
+setting is the server URL.
+
+| Setting | Environment | Required | What it does |
+| --- | --- | --- | --- |
+| Server URL | `OLLAMA_HOST` | no | The server origin, `http://localhost:11434` by default. A trailing `/` or `/api` is stripped, and a bare `host:port` such as `0.0.0.0:11434` gets `http://` in front, so the same value the `ollama` CLI reads works here. |
+
+A hosted or reverse-proxied server that wants a key takes it from the
+`OLLAMA_API_KEY` environment variable, sent as `Authorization: Bearer <key>`
+only when it is set. There is no config field for it: the connector SDK
+refuses a secret field on a connector that declares it needs no sign-in, so
+the key rides on the environment. A host that does not pass its environment
+through to the connector cannot supply it.
+
+## Errors, timeouts and retries
+
+Every request is JSON and every reply is one JSON object: the connector sends
+`stream: false` on chat, generate and pull, so an answer is never a stream of
+lines. A failed call carries `{ "error": "<message>" }` and is reported as
+`<message> (HTTP <status>)`. A model that is not on the server answers 404
+`model '<name>' not found`, reported as `Model '<name>' is not present on the
+server; pull it first (HTTP 404)`; the connector never pulls on the caller's
+behalf. A `503` means the server is overloaded and is reported as is.
+
+Chat, generate and pull can take minutes on a laptop and get a 10 minute
+timeout; every other call gets 30 seconds. A connection refused is retried
+once after two seconds, and a second refusal is reported as `Ollama did not
+answer at <url>; the server may be starting or not running`. Nothing else is
+retried; there are no rate limits, the server queues requests. Every
+duration in a reply is nanoseconds and is passed through untouched.
+
+## Triggers
+
+Both poll the whole list, since neither endpoint pages, and both dedupe on
+the SDK's timestamp strategy with the time reduced to UTC milliseconds.
+
+### `modelChanged` — a model was added or updated
+
+Polls `GET /api/tags` and fires once per model build: the item id is
+`<name>@<digest>` stamped with `modified_at`, so a pull that updates a tag
+fires again and the same build never fires twice. The first poll delivers
+every model present. Each item carries `name`, `digest`, `size`,
+`modified_at`, `family` and `parameter_size` beside the full `details`, a
+title such as `qwen2.5-coder:7b (qwen2, 7.6B)`, and the library page as
+`url` when the name has no namespace and no remote host.
+
+### `modelLoaded` — a model was loaded into memory
+
+Polls `GET /api/ps` and fires when a model appears with an `expires_at` not
+yet seen: the item id is `<name>@<expires_at>` stamped with `expires_at`.
+Every request the model serves moves the expiry forward, so a busy model
+fires again on each poll; the default workflow polls every five minutes, and
+a slower interval reports fewer repeats. Each item carries `name`, `digest`,
+`size`, `size_vram`, `expires_at`, `context_length` and `details`.
+
+## Actions
+
+`model` is the `model:tag` name; the tag defaults to `latest`. `format` is
+the word `json` or a JSON schema object, sent untouched; `options` is the
+runtime options object such as `{ "temperature": 0.2, "num_predict": 256 }`;
+`keepAlive` is sent as `keep_alive`, a duration such as `10m` or `0` to
+unload at once.
+
+| Action | Idempotent | What it does |
+| --- | --- | --- |
+| `chat` | no | `POST /api/chat` with `model`, `messages` (a single user text or a JSON array of `{ role, content }`), optional `system` (prepended as a system turn), `format`, `options`, `keepAlive`. Returns `content`, `thinking`, `toolCalls`, `doneReason`, `evalCount`, `promptEvalCount`, `totalDuration`, `loadDuration`, `promptEvalDuration`, `evalDuration`, `model`, `raw`. |
+| `generate` | no | `POST /api/generate` with `model`, `prompt`, optional `system`, `format`, `options`, `keepAlive`. Returns `response`, `thinking` and the same timings and `raw`. |
+| `embed` | yes | `POST /api/embed` with `model`, `input` (text or a JSON array of texts), optional `truncate`. Returns `embeddings`, `count`, `model`, `promptEvalCount`, `totalDuration`, `loadDuration`, `raw`. |
+| `listModels` | yes | `GET /api/tags`. Returns `models`, `count`, `raw`. |
+| `showModel` | yes | `POST /api/show` with `model`, optional `verbose`. Returns `model`, `details`, `capabilities`, `modifiedAt`, `parameters`, `template`, `license`, `modelInfo`, `raw`. |
+| `listRunningModels` | yes | `GET /api/ps`. Returns `models`, `count`, `raw`. |
+| `version` | yes | `GET /api/version`. Returns `version`. The live check probes this. |
+| `pullModel` | no | `POST /api/pull` with `model`, optional `insecure`, `stream: false`. Returns the final `status` and `raw`. Downloads, so it is slow. |
+| `deleteModel` | no | `DELETE /api/delete` with `model`. Returns `deleted`, `model`. A second call answers 404. |
+| `copyModel` | no | `POST /api/copy` with `source`, `destination`. Returns `copied`, `source`, `destination`. |
+
+A runner that does not serve embeddings answers `501 This server does not
+support embeddings`; `showModel` lists `embedding` under `capabilities` for a
+model that does.
+
+## Checks
+
+From the repository root:
+
+```sh
+yarn typecheck && yarn test && yarn build
+node node_modules/@vornrun/connector-sdk/dist/cli.js check ./packages/ollama/dist/index.js --mock --receipt packages/ollama/verified.json
+```
+
+`packages/ollama/scripts/check.sh` runs exactly this. Tests make no network
+calls: the client takes an injected `fetch` and sleep, and the API key test
+injects the environment.
+
+`packages/ollama/scripts/check-live.sh` calls `GET /api/version` on
+`OLLAMA_HOST` (default `http://localhost:11434`) and exits 0 with a note when
+no server answers. With a server it lists models, shows `OLLAMA_MODEL`
+(default `qwen2.5-coder:7b`), lists running models, embeds `hello` with
+`OLLAMA_EMBED_MODEL` or the same model (a runner that does not serve
+embeddings is reported as a note), then runs `vorn-connector check --live`
+against the built package. Nothing is generated, pulled, deleted or copied.
+
+## Built from
+
+The API reference was the only source. Two of its pages have moved; the new
+address is listed beside the old one.
+
+- API introduction: https://docs.ollama.com/api
+- Generate a completion: https://docs.ollama.com/api/generate
+- Generate a chat message: https://docs.ollama.com/api/chat
+- Generate embeddings: https://docs.ollama.com/api/embed
+- List models: https://docs.ollama.com/api/tags
+- Show a model: https://docs.ollama.com/api/show (moved to https://docs.ollama.com/api-reference/show-model-details)
+- List running models: https://docs.ollama.com/api/ps
+- Pull a model: https://docs.ollama.com/api/pull
+- Delete a model: https://docs.ollama.com/api/delete
+- Copy a model: https://docs.ollama.com/api/copy
+- Version: https://docs.ollama.com/api/version (moved to https://docs.ollama.com/api-reference/get-version)
+- Structured outputs: https://docs.ollama.com/capabilities/structured-outputs
+- Markdown source of the reference: https://github.com/ollama/ollama/blob/main/docs/api.md
+- FAQ, `OLLAMA_HOST`, `keep_alive`, queueing and the 503: https://docs.ollama.com/faq
+- Cloud, `OLLAMA_API_KEY` and `Authorization: Bearer`: https://docs.ollama.com/cloud

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import * as _vornrun_connector_sdk from '@vornrun/connector-sdk';
+
+declare const DEFAULT_BASE_URL = "http://localhost:11434";
+/** Chat, generate and pull can take minutes on a laptop. */
+declare const LONG_TIMEOUT_MS: number;
+declare const DEFAULT_TIMEOUT_MS = 30000;
+/** How long the one retry waits for a server that may be starting. */
+declare const CONNECTION_RETRY_WAIT_MS = 2000;
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+type Sleep = (ms: number) => Promise<void>;
+declare function normalizeBaseUrl(raw: unknown): string;
+declare class OllamaApiError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, body: unknown);
+}
+declare function describeFailure(detail: string): string;
+interface RequestOptions {
+    body?: unknown;
+    timeoutMs?: number;
+}
+interface OllamaClient {
+    readonly baseUrl: string;
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body: unknown, timeoutMs?: number): Promise<T>;
+}
+interface OllamaClientOptions {
+    baseUrl?: string;
+    /** Sent as `Authorization: Bearer` only when set, for a hosted or proxied server. */
+    apiKey?: string;
+    /** Injected in tests, so nothing reaches the network. */
+    fetchImpl?: FetchLike;
+    /** Injected in tests, so the connection retry spends no real time. */
+    sleep?: Sleep;
+}
+declare function createOllamaClient(options?: OllamaClientOptions): OllamaClient;
+
+declare const SAMPLE_MODEL_NAME = "qwen2.5-coder:7b";
+interface OllamaConnectorOptions {
+    version?: string;
+    /** Injected in tests, so nothing reaches the network. */
+    fetchImpl?: FetchLike;
+    /** Injected in tests, so the connection retry spends no real time. */
+    sleep?: Sleep;
+    /** Where the optional API key and the preflight host are read from; defaults to the process environment. */
+    env?: NodeJS.ProcessEnv;
+}
+declare function createOllamaConnector(options?: OllamaConnectorOptions): _vornrun_connector_sdk.Connector;
+declare const connector: _vornrun_connector_sdk.Connector;
+
+export { CONNECTION_RETRY_WAIT_MS, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, LONG_TIMEOUT_MS, OllamaApiError, type OllamaClient, type OllamaClientOptions, type OllamaConnectorOptions, SAMPLE_MODEL_NAME, connector, createOllamaClient, createOllamaConnector, connector as default, describeFailure, normalizeBaseUrl };

package/dist/index.js

@@ -0,0 +1,827 @@
+#!/usr/bin/env node
+
+// src/connector.ts
+import { defineConnector } from "@vornrun/connector-sdk";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "http://localhost:11434";
+var LONG_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var CONNECTION_RETRY_WAIT_MS = 2e3;
+var MAX_ERROR_BODY = 300;
+var MODEL_NOT_FOUND = /^model '([^']*)' not found$/;
+function normalizeBaseUrl(raw) {
+  let url = String(raw ?? "").trim();
+  if (url === "") return DEFAULT_BASE_URL;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) url = `http://${url}`;
+  url = url.replace(/\/+$/, "");
+  url = url.replace(/\/api$/i, "");
+  return url.replace(/\/+$/, "");
+}
+var OllamaApiError = class extends Error {
+  status;
+  detail;
+  constructor(status, body) {
+    const detail = errorMessage(body);
+    super(`${describeFailure(detail)} (HTTP ${status})`);
+    this.name = "OllamaApiError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+function errorMessage(body) {
+  const error = body?.error;
+  if (typeof error === "string" && error.trim() !== "") return error.trim();
+  const raw = typeof body === "string" ? body : body === void 0 ? "" : JSON.stringify(body);
+  const trimmed = raw.trim();
+  if (trimmed === "") return "no body";
+  return trimmed.length > MAX_ERROR_BODY ? `${trimmed.slice(0, MAX_ERROR_BODY)}\u2026` : trimmed;
+}
+function describeFailure(detail) {
+  const missing = MODEL_NOT_FOUND.exec(detail);
+  return missing ? `Model '${missing[1]}' is not present on the server; pull it first` : detail;
+}
+function isConnectionRefused(error) {
+  let current = error;
+  for (let depth = 0; depth < 4 && typeof current === "object" && current !== null; depth += 1) {
+    const candidate = current;
+    if (candidate.code === "ECONNREFUSED") return true;
+    if (Array.isArray(candidate.errors) && candidate.errors.some(isConnectionRefused)) return true;
+    current = candidate.cause;
+  }
+  return false;
+}
+var defaultSleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+var defaultFetch = (input, init) => globalThis.fetch(input, init);
+async function readBody(response) {
+  const text2 = await response.text();
+  if (text2 === "") return void 0;
+  try {
+    return JSON.parse(text2);
+  } catch {
+    return text2;
+  }
+}
+function createOllamaClient(options = {}) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const fetchImpl = options.fetchImpl ?? defaultFetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const apiKey = String(options.apiKey ?? "").trim();
+  const headers = {
+    accept: "application/json",
+    ...apiKey !== "" && { authorization: `Bearer ${apiKey}` }
+  };
+  async function send(url, init, timeoutMs, route) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    try {
+      return await fetchImpl(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Ollama did not answer ${route} within ${Math.round(timeoutMs / 1e3)}s`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function request(method, path, opts = {}) {
+    const url = `${baseUrl}/api/${path.replace(/^\//, "")}`;
+    const route = `${method.toUpperCase()} /api/${path.replace(/^\//, "")}`;
+    const init = {
+      method: method.toUpperCase(),
+      headers: opts.body === void 0 ? headers : { ...headers, "content-type": "application/json" },
+      ...opts.body !== void 0 && { body: JSON.stringify(opts.body) }
+    };
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let response;
+    try {
+      response = await send(url, init, timeoutMs, route);
+    } catch (error) {
+      if (!isConnectionRefused(error)) throw error;
+      await sleep(CONNECTION_RETRY_WAIT_MS);
+      try {
+        response = await send(url, init, timeoutMs, route);
+      } catch (again) {
+        if (!isConnectionRefused(again)) throw again;
+        throw new Error(`Ollama did not answer at ${baseUrl}; the server may be starting or not running`);
+      }
+    }
+    const body = await readBody(response);
+    if (!response.ok) throw new OllamaApiError(response.status, body);
+    return body;
+  }
+  return {
+    baseUrl,
+    request,
+    get: (path) => request("GET", path),
+    post: (path, body, timeoutMs) => request("POST", path, { body, ...timeoutMs !== void 0 && { timeoutMs } })
+  };
+}
+
+// src/items.ts
+var SAMPLE_MODEL = {
+  name: "qwen2.5-coder:7b",
+  model: "qwen2.5-coder:7b",
+  modified_at: "2026-08-02T16:07:41.209152383-06:00",
+  size: 4683087561,
+  digest: "dae161e27b0e90dd1856c8bb3209201fd6736d8eb66298e75ed87571486f4364",
+  details: {
+    parent_model: "",
+    format: "gguf",
+    family: "qwen2",
+    families: ["qwen2"],
+    parameter_size: "7.6B",
+    quantization_level: "Q4_K_M"
+  }
+};
+var SAMPLE_RUNNING_MODEL = {
+  name: "qwen2.5-coder:7b",
+  model: "qwen2.5-coder:7b",
+  size: 4740716952,
+  size_vram: 4740716952,
+  digest: "dae161e27b0e90dd1856c8bb3209201fd6736d8eb66298e75ed87571486f4364",
+  details: SAMPLE_MODEL.details,
+  expires_at: "2026-09-10T07:31:16.885215-06:00",
+  context_length: 4096
+};
+function text(value) {
+  const trimmed = String(value ?? "").trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function flag(value) {
+  return value === true || /^(true|1|yes)$/i.test(String(value ?? "").trim());
+}
+function textOrJsonArray(value) {
+  if (Array.isArray(value)) return value;
+  const raw = String(value ?? "");
+  if (raw.trim().startsWith("[")) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+    }
+  }
+  return raw;
+}
+function jsonObject(value, key) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value !== "object" || Array.isArray(value)) throw new Error(`${key} must be a JSON object`);
+  return value;
+}
+function messagesArg(value, system) {
+  const parsed = typeof value === "object" && value !== null && !Array.isArray(value) ? [] : textOrJsonArray(value);
+  const turns = typeof parsed === "string" ? [{ role: "user", content: parsed }] : parsed.filter((turn) => typeof turn === "object" && turn !== null && !Array.isArray(turn));
+  if (system !== void 0 && turns[0]?.role !== "system") return [{ role: "system", content: system }, ...turns];
+  return turns;
+}
+function formatArg(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) return value;
+  const raw = text(value);
+  if (raw === void 0) return void 0;
+  if (raw.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return parsed;
+    } catch {
+    }
+  }
+  return raw;
+}
+function keepAliveArg(value) {
+  const raw = text(value);
+  if (raw === void 0) return void 0;
+  return /^-?\d+$/.test(raw) ? Number(raw) : raw;
+}
+function isoOf(value) {
+  const at = Date.parse(String(value ?? ""));
+  return Number.isNaN(at) ? void 0 : new Date(at).toISOString();
+}
+function gigabytes(bytes) {
+  return `${((bytes ?? 0) / 1e9).toFixed(1)} GB`;
+}
+function libraryUrl(model) {
+  const name = model.name ?? model.model ?? "";
+  if (name === "" || name.includes("/") || text(model.remote_host) !== void 0) return void 0;
+  return `https://ollama.com/library/${encodeURIComponent(name.split(":")[0])}`;
+}
+function modelToItem(model) {
+  const name = model.name ?? model.model ?? "";
+  const digest = model.digest ?? "";
+  const family = text(model.details?.family);
+  const size = text(model.details?.parameter_size);
+  const detail = [family, size].filter((part) => part !== void 0).join(", ");
+  const url = libraryUrl(model);
+  const updatedAt = isoOf(model.modified_at);
+  return {
+    externalId: `${name}@${digest}`,
+    title: detail ? `${name} (${detail})` : name,
+    ...url && { url },
+    ...updatedAt && { updatedAt },
+    data: {
+      name,
+      digest,
+      size: model.size ?? 0,
+      modified_at: model.modified_at ?? null,
+      family: family ?? null,
+      parameter_size: size ?? null,
+      details: model.details ?? {}
+    }
+  };
+}
+function runningToItem(model) {
+  const name = model.name ?? model.model ?? "";
+  const expires = model.expires_at ?? "";
+  const updatedAt = isoOf(model.expires_at);
+  return {
+    externalId: `${name}@${expires}`,
+    title: `${name} loaded (${gigabytes(model.size_vram ?? model.size)} in VRAM, context ${model.context_length ?? 0})`,
+    ...updatedAt && { updatedAt },
+    data: {
+      name,
+      digest: model.digest ?? "",
+      size: model.size ?? 0,
+      size_vram: model.size_vram ?? 0,
+      expires_at: model.expires_at ?? null,
+      context_length: model.context_length ?? 0,
+      details: model.details ?? {}
+    }
+  };
+}
+
+// package.json
+var package_default = {
+  name: "@vornrun/connector-ollama",
+  version: "0.1.0",
+  description: "Trigger workflows when a local Ollama model is added, updated or loaded into memory, and chat, generate, embed, and list, show, pull, copy or delete models from a step.",
+  type: "module",
+  license: "MIT",
+  author: "Javier Canizalez <javier-canizalez@outlook.com>",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/vorn-run/connectors.git",
+    directory: "packages/ollama"
+  },
+  keywords: [
+    "vorn",
+    "connector",
+    "ollama",
+    "llm",
+    "mcp"
+  ],
+  bin: {
+    "vorn-connector-ollama": "dist/index.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@vornrun/connector-sdk": "^0.7.0-beta.14"
+  },
+  devDependencies: {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    tsup: "^8.5.1",
+    typescript: "^6.0.3",
+    vitest: "^4.1.10"
+  },
+  vorn: {
+    category: "AI",
+    keywords: [
+      "ollama",
+      "llm",
+      "local models",
+      "chat",
+      "generate",
+      "embeddings",
+      "qwen",
+      "llama",
+      "gemma"
+    ],
+    auth: "Nothing to sign in with: Ollama serves http://localhost:11434 without credentials. Set OLLAMA_HOST for another server and OLLAMA_API_KEY for a hosted one.",
+    packs: true
+  }
+};
+
+// src/connector.ts
+var SAMPLE_MODEL_NAME = "qwen2.5-coder:7b";
+var MODEL_INPUT = {
+  key: "model",
+  label: "Model",
+  required: true,
+  description: `The model name in model:tag form; the tag defaults to latest. listModels returns what is present.`,
+  builderHint: `A name that is not on the server answers 404 and is reported as "not present; pull it first"; nothing is pulled on the caller's behalf.`
+};
+var SYSTEM_INPUT = {
+  key: "system",
+  label: "System prompt",
+  description: "Instructions for the model, kept apart from the conversation.",
+  builderHint: "On chat it is prepended as a system turn unless the messages already start with one; on generate it is sent as system."
+};
+var FORMAT_INPUT = {
+  key: "format",
+  label: "Format",
+  description: "json for any valid JSON, or a JSON schema object the answer must match.",
+  builderHint: "Sent as format untouched. With a schema, also describe it in the prompt so the model grounds its answer; the reply is text, so parse content yourself."
+};
+var OPTIONS_INPUT = {
+  key: "options",
+  label: "Options",
+  type: "json",
+  description: 'Runtime options such as { "temperature": 0.2, "num_predict": 256 }.',
+  builderHint: "Passed through as options: temperature, num_predict, seed, top_k, top_p, min_p, stop, num_ctx and any other Modelfile parameter."
+};
+var KEEP_ALIVE_INPUT = {
+  key: "keepAlive",
+  label: "Keep alive",
+  description: "How long the model stays loaded after the reply, such as 10m; 0 unloads it at once.",
+  builderHint: "Sent as keep_alive. A duration string or a number of seconds; a negative number keeps it loaded until the server stops."
+};
+var TIMING_OUTPUTS = [
+  { key: "evalCount", type: "number", description: "Tokens generated in the reply" },
+  { key: "promptEvalCount", type: "number", description: "Prompt tokens evaluated" },
+  { key: "totalDuration", type: "number", description: "Whole call in nanoseconds" },
+  { key: "loadDuration", type: "number", description: "Loading the model, in nanoseconds" },
+  { key: "promptEvalDuration", type: "number", description: "Evaluating the prompt, in nanoseconds" },
+  { key: "evalDuration", type: "number", description: "Generating the reply, in nanoseconds" },
+  { key: "model", description: "The model that answered" },
+  { key: "raw", description: "The whole response as the server returned it" }
+];
+function timings(body) {
+  return {
+    doneReason: body.done_reason ?? null,
+    evalCount: body.eval_count ?? 0,
+    promptEvalCount: body.prompt_eval_count ?? 0,
+    totalDuration: body.total_duration ?? 0,
+    loadDuration: body.load_duration ?? 0,
+    promptEvalDuration: body.prompt_eval_duration ?? 0,
+    evalDuration: body.eval_duration ?? 0,
+    model: body.model ?? null,
+    raw: body
+  };
+}
+function createOllamaConnector(options = {}) {
+  const env = options.env ?? process.env;
+  function clientFor(config, fetchImpl) {
+    return createOllamaClient({
+      baseUrl: normalizeBaseUrl(config.baseUrl),
+      ...text(env.OLLAMA_API_KEY) && { apiKey: text(env.OLLAMA_API_KEY) },
+      fetchImpl: options.fetchImpl ?? fetchImpl,
+      ...options.sleep && { sleep: options.sleep }
+    });
+  }
+  function requiredArg(args, key) {
+    const value = text(args[key]);
+    if (value === void 0) throw new Error(`${key} is required`);
+    return value;
+  }
+  async function fetchModels(context) {
+    const body = await clientFor(context.config, context.fetch).get("tags");
+    return (Array.isArray(body?.models) ? body.models : []).filter((model) => text(model?.name ?? model?.model) !== void 0).sort((left, right) => String(left.modified_at ?? "").localeCompare(String(right.modified_at ?? ""))).map(modelToItem);
+  }
+  async function fetchRunningModels(context) {
+    const body = await clientFor(context.config, context.fetch).get("ps");
+    return (Array.isArray(body?.models) ? body.models : []).filter((model) => text(model?.name ?? model?.model) !== void 0).sort((left, right) => String(left.expires_at ?? "").localeCompare(String(right.expires_at ?? ""))).map(runningToItem);
+  }
+  return defineConnector({
+    id: "ollama",
+    name: "Ollama",
+    version: options.version ?? package_default.version,
+    description: "Trigger workflows when a local Ollama model is added, updated or loaded into memory, and chat, generate, embed, and list, show, pull, copy or delete models from a step.",
+    // The llama's face as the spec draws it: a rounded head, two tall ears, and the eyes and muzzle
+    // punched through by reversed winding, since the icon carries path data only and no fill-rule.
+    icon: {
+      viewBox: "0 0 24 24",
+      paths: [
+        [
+          "M9 8H15A5 5 0 0 1 20 13V17A5 5 0 0 1 15 22H9A5 5 0 0 1 4 17V13A5 5 0 0 1 9 8Z",
+          "M6 3.5A1.5 1.5 0 0 1 7.5 2A1.5 1.5 0 0 1 9 3.5V10H6Z",
+          "M15 3.5A1.5 1.5 0 0 1 16.5 2A1.5 1.5 0 0 1 18 3.5V10H15Z",
+          "M8.3 14A1.2 1.2 0 0 0 10.7 14A1.2 1.2 0 0 0 8.3 14Z",
+          "M13.3 14A1.2 1.2 0 0 0 15.7 14A1.2 1.2 0 0 0 13.3 14Z",
+          "M11.25 17.5A1.25 1.25 0 0 0 10 18.75A1.25 1.25 0 0 0 11.25 20H12.75A1.25 1.25 0 0 0 14 18.75A1.25 1.25 0 0 0 12.75 17.5Z"
+        ].join("")
+      ]
+    },
+    auth: { rung: "none" },
+    config: [
+      {
+        key: "baseUrl",
+        env: "OLLAMA_HOST",
+        label: "Server URL",
+        default: DEFAULT_BASE_URL,
+        description: `The server origin, ${DEFAULT_BASE_URL} by default. A trailing / or /api is stripped and a bare host:port gets http://.`,
+        builderHint: "The same variable the ollama CLI reads. A hosted or proxied server that wants a key takes it from OLLAMA_API_KEY in the environment, sent as Authorization: Bearer; the SDK refuses a secret field on a connector that needs no sign-in, so there is no config field for it."
+      }
+    ],
+    async preflight() {
+      const client = clientFor({ baseUrl: env.OLLAMA_HOST });
+      try {
+        const body = await client.get("version");
+        return { ok: true, message: `Ollama ${body?.version ?? "unknown version"} answered at ${client.baseUrl}` };
+      } catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+      }
+    },
+    triggers: [
+      {
+        type: "modelChanged",
+        label: "A model was added or updated",
+        description: "Fires once per model build from GET /api/tags: a new name, or a pull that changed a digest. The first poll delivers every model present.",
+        defaultWorkflow: { name: "Ollama: added or updated models", defaultCronFromMinutes: 15 },
+        dedupe: "timestamp",
+        sample: [modelToItem(SAMPLE_MODEL)],
+        fetch: fetchModels
+      },
+      {
+        type: "modelLoaded",
+        label: "A model was loaded into memory",
+        description: "Fires when a model appears in GET /api/ps with an expiry not yet seen. Every request extends the expiry, so a busy model fires again on each poll; poll slowly.",
+        defaultWorkflow: { name: "Ollama: loaded models", defaultCronFromMinutes: 5 },
+        dedupe: "timestamp",
+        sample: [runningToItem(SAMPLE_RUNNING_MODEL)],
+        fetch: fetchRunningModels
+      }
+    ],
+    actions: [
+      {
+        type: "chat",
+        label: "Chat",
+        description: "Generate the next assistant message of a conversation with POST /api/chat. Every call runs a generation.",
+        idempotent: false,
+        inputs: [
+          MODEL_INPUT,
+          {
+            key: "messages",
+            label: "Messages",
+            required: true,
+            description: 'A single user text, or a JSON array of { "role", "content" } with role system, user, assistant or tool.',
+            builderHint: 'Text becomes [{ role: "user", content: text }]; a value starting with [ is parsed as the array and passed through, so images and tool_calls on a turn survive.'
+          },
+          SYSTEM_INPUT,
+          FORMAT_INPUT,
+          OPTIONS_INPUT,
+          KEEP_ALIVE_INPUT
+        ],
+        outputs: [
+          { key: "content", description: "The assistant message text" },
+          { key: "thinking", description: "The thinking text when the model produced one, else null" },
+          { key: "toolCalls", description: "The tool_calls array when the model made any, else null" },
+          { key: "doneReason", description: "stop, length or load" },
+          ...TIMING_OUTPUTS
+        ],
+        async run(args, context) {
+          const system = text(args.system);
+          const format = formatArg(args.format);
+          const modelOptions = jsonObject(args.options, "options");
+          const keepAlive = keepAliveArg(args.keepAlive);
+          const body = await clientFor(context.config, context.fetch).post(
+            "chat",
+            {
+              model: requiredArg(args, "model"),
+              messages: messagesArg(args.messages, system),
+              ...format !== void 0 && { format },
+              ...modelOptions && { options: modelOptions },
+              ...keepAlive !== void 0 && { keep_alive: keepAlive },
+              stream: false
+            },
+            LONG_TIMEOUT_MS
+          );
+          const reply = body ?? {};
+          return {
+            content: reply.message?.content ?? "",
+            thinking: reply.message?.thinking ?? null,
+            toolCalls: reply.message?.tool_calls ?? null,
+            ...timings(reply)
+          };
+        }
+      },
+      {
+        type: "generate",
+        label: "Generate a completion",
+        description: "Generate a response for a prompt with POST /api/generate. Every call runs a generation.",
+        idempotent: false,
+        inputs: [
+          MODEL_INPUT,
+          {
+            key: "prompt",
+            label: "Prompt",
+            required: true,
+            description: "Text for the model to generate a response from.",
+            builderHint: "Sent as prompt. Use chat for a conversation with roles; this is the raw completion endpoint."
+          },
+          SYSTEM_INPUT,
+          FORMAT_INPUT,
+          OPTIONS_INPUT,
+          KEEP_ALIVE_INPUT
+        ],
+        outputs: [
+          { key: "response", description: "The generated text" },
+          { key: "thinking", description: "The thinking text when the model produced one, else null" },
+          { key: "doneReason", description: "stop, length or load" },
+          ...TIMING_OUTPUTS
+        ],
+        async run(args, context) {
+          const system = text(args.system);
+          const format = formatArg(args.format);
+          const modelOptions = jsonObject(args.options, "options");
+          const keepAlive = keepAliveArg(args.keepAlive);
+          const body = await clientFor(context.config, context.fetch).post(
+            "generate",
+            {
+              model: requiredArg(args, "model"),
+              prompt: requiredArg(args, "prompt"),
+              ...system && { system },
+              ...format !== void 0 && { format },
+              ...modelOptions && { options: modelOptions },
+              ...keepAlive !== void 0 && { keep_alive: keepAlive },
+              stream: false
+            },
+            LONG_TIMEOUT_MS
+          );
+          const reply = body ?? {};
+          return { response: reply.response ?? "", thinking: reply.thinking ?? null, ...timings(reply) };
+        }
+      },
+      {
+        type: "embed",
+        label: "Generate embeddings",
+        description: "Turn text into embedding vectors with POST /api/embed. The same input and model give the same vectors.",
+        idempotent: true,
+        sample: { model: SAMPLE_MODEL_NAME, input: "hello" },
+        inputs: [
+          {
+            ...MODEL_INPUT,
+            builderHint: `${MODEL_INPUT.builderHint} A runner that does not serve embeddings answers 501; showModel lists embedding under capabilities when it does.`
+          },
+          {
+            key: "input",
+            label: "Input",
+            required: true,
+            description: "Text, or a JSON array of texts, to embed in one call.",
+            builderHint: "A value starting with [ is parsed as the array; one vector comes back per entry, in order."
+          },
+          {
+            key: "truncate",
+            label: "Truncate",
+            type: "boolean",
+            description: "Truncate an input that exceeds the context window instead of failing. The server default is true.",
+            builderHint: "Sent as truncate only when set; false makes an oversized input an error."
+          }
+        ],
+        outputs: [
+          { key: "embeddings", description: "One number array per input, in input order" },
+          { key: "count", type: "number", description: "How many vectors" },
+          { key: "model", description: "The model used" },
+          { key: "promptEvalCount", type: "number", description: "Input tokens processed" },
+          { key: "totalDuration", type: "number", description: "Whole call in nanoseconds" },
+          { key: "loadDuration", type: "number", description: "Loading the model, in nanoseconds" },
+          { key: "raw", description: "The whole response as the server returned it" }
+        ],
+        async run(args, context) {
+          const truncate = text(args.truncate);
+          const body = await clientFor(context.config, context.fetch).post("embed", {
+            model: requiredArg(args, "model"),
+            input: textOrJsonArray(args.input),
+            ...truncate !== void 0 && { truncate: flag(truncate) }
+          });
+          const embeddings = Array.isArray(body?.embeddings) ? body.embeddings : [];
+          return {
+            embeddings,
+            count: embeddings.length,
+            model: body?.model ?? null,
+            promptEvalCount: body?.prompt_eval_count ?? 0,
+            totalDuration: body?.total_duration ?? 0,
+            loadDuration: body?.load_duration ?? 0,
+            raw: body ?? {}
+          };
+        }
+      },
+      {
+        type: "listModels",
+        label: "List models",
+        description: "List the models on the server with GET /api/tags.",
+        idempotent: true,
+        sample: {},
+        outputs: [
+          { key: "models", description: "Array of { name, model, modified_at, size, digest, details }" },
+          { key: "count", type: "number", description: "How many models" },
+          { key: "raw", description: "The whole response as the server returned it" }
+        ],
+        async run(_args, context) {
+          const body = await clientFor(context.config, context.fetch).get("tags");
+          const models = Array.isArray(body?.models) ? body.models : [];
+          return { models, count: models.length, raw: body ?? {} };
+        }
+      },
+      {
+        type: "showModel",
+        label: "Show a model",
+        description: "Read a model\u2019s details, capabilities, parameters, template and license with POST /api/show.",
+        idempotent: true,
+        sample: { model: SAMPLE_MODEL_NAME },
+        inputs: [
+          MODEL_INPUT,
+          {
+            key: "verbose",
+            label: "Verbose",
+            type: "boolean",
+            description: "Include the large fields, such as the full tokenizer, in modelInfo.",
+            builderHint: "Sent as verbose only when true; the reply can run to megabytes."
+          }
+        ],
+        outputs: [
+          { key: "model", description: "The model name asked for; the reply carries none" },
+          { key: "details", description: "{ parent_model, format, family, families, parameter_size, quantization_level }" },
+          { key: "capabilities", description: "Array such as completion, tools, vision, embedding" },
+          { key: "modifiedAt", description: "When the model was last modified, ISO 8601" },
+          { key: "parameters", description: "Model parameter settings as text" },
+          { key: "template", description: "The prompt template" },
+          { key: "license", description: "The license text" },
+          { key: "modelInfo", description: "Additional model metadata" },
+          { key: "raw", description: "The whole response as the server returned it" }
+        ],
+        async run(args, context) {
+          const model = requiredArg(args, "model");
+          const body = await clientFor(context.config, context.fetch).post("show", {
+            model,
+            ...flag(args.verbose) && { verbose: true }
+          });
+          return {
+            model,
+            details: body?.details ?? {},
+            capabilities: Array.isArray(body?.capabilities) ? body.capabilities : [],
+            modifiedAt: body?.modified_at ?? null,
+            parameters: body?.parameters ?? "",
+            template: body?.template ?? "",
+            license: body?.license ?? "",
+            modelInfo: body?.model_info ?? {},
+            raw: body ?? {}
+          };
+        }
+      },
+      {
+        type: "listRunningModels",
+        label: "List running models",
+        description: "List the models loaded into memory with GET /api/ps.",
+        idempotent: true,
+        sample: {},
+        outputs: [
+          { key: "models", description: "Array of { name, model, size, digest, details, expires_at, size_vram, context_length }" },
+          { key: "count", type: "number", description: "How many models are loaded" },
+          { key: "raw", description: "The whole response as the server returned it" }
+        ],
+        async run(_args, context) {
+          const body = await clientFor(context.config, context.fetch).get("ps");
+          const models = Array.isArray(body?.models) ? body.models : [];
+          return { models, count: models.length, raw: body ?? {} };
+        }
+      },
+      {
+        type: "version",
+        label: "Get the server version",
+        description: "Read the server version with GET /api/version. The live check probes this.",
+        idempotent: true,
+        sample: {},
+        outputs: [{ key: "version", description: "The server version, such as 0.12.6" }],
+        async run(_args, context) {
+          const body = await clientFor(context.config, context.fetch).get("version");
+          return { version: body?.version ?? null };
+        }
+      },
+      {
+        type: "pullModel",
+        label: "Pull a model",
+        description: "Download a model from the library with POST /api/pull. Downloads, so it is slow and not repeatable in a live check.",
+        idempotent: false,
+        inputs: [
+          { ...MODEL_INPUT, builderHint: "A library name such as gemma3, or user/model for a shared one. A cancelled pull resumes where it left off." },
+          {
+            key: "insecure",
+            label: "Insecure",
+            type: "boolean",
+            description: "Allow downloading over an insecure connection.",
+            builderHint: "Sent as insecure only when true; only for a library you run yourself during development."
+          }
+        ],
+        outputs: [
+          { key: "status", description: "The final status, success when the model is present" },
+          { key: "raw", description: "The whole response as the server returned it" }
+        ],
+        async run(args, context) {
+          const body = await clientFor(context.config, context.fetch).post(
+            "pull",
+            { model: requiredArg(args, "model"), ...flag(args.insecure) && { insecure: true }, stream: false },
+            LONG_TIMEOUT_MS
+          );
+          return { status: body?.status ?? null, raw: body ?? {} };
+        }
+      },
+      {
+        type: "deleteModel",
+        label: "Delete a model",
+        description: "Delete a model and its data with DELETE /api/delete. A second call answers 404.",
+        idempotent: false,
+        inputs: [{ ...MODEL_INPUT, builderHint: "Deleting a tag another name was copied from leaves the copy in place; layers are shared." }],
+        outputs: [
+          { key: "deleted", type: "boolean", description: "True once the server answered 200" },
+          { key: "model", description: "The model that was deleted" }
+        ],
+        async run(args, context) {
+          const model = requiredArg(args, "model");
+          await clientFor(context.config, context.fetch).request("DELETE", "delete", { body: { model } });
+          return { deleted: true, model };
+        }
+      },
+      {
+        type: "copyModel",
+        label: "Copy a model",
+        description: "Create a new name for an existing model with POST /api/copy. Creates a tag, so it is not repeatable.",
+        idempotent: false,
+        inputs: [
+          {
+            key: "source",
+            label: "Source",
+            required: true,
+            description: "Existing model name to copy from.",
+            builderHint: "A missing source answers 404 and is reported as not present."
+          },
+          {
+            key: "destination",
+            label: "Destination",
+            required: true,
+            description: "New model name to create.",
+            builderHint: "model:tag form; an existing name is overwritten."
+          }
+        ],
+        outputs: [
+          { key: "copied", type: "boolean", description: "True once the server answered 200" },
+          { key: "source", description: "The name copied from" },
+          { key: "destination", description: "The name created" }
+        ],
+        async run(args, context) {
+          const source = requiredArg(args, "source");
+          const destination = requiredArg(args, "destination");
+          await clientFor(context.config, context.fetch).post("copy", { source, destination });
+          return { copied: true, source, destination };
+        }
+      }
+    ]
+  });
+}
+var connector = createOllamaConnector();
+
+// src/entry.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { serveConnector } from "@vornrun/connector-sdk";
+function isEntryPoint(moduleUrl, argv = process.argv) {
+  const invoked = argv[1];
+  if (invoked === void 0) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(invoked);
+  } catch {
+    return false;
+  }
+}
+async function serveIfEntryPoint(moduleUrl, serve = serveConnector) {
+  if (!isEntryPoint(moduleUrl)) return false;
+  await serve(connector);
+  return true;
+}
+
+// src/index.ts
+var index_default = connector;
+await serveIfEntryPoint(import.meta.url);
+export {
+  CONNECTION_RETRY_WAIT_MS,
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+  LONG_TIMEOUT_MS,
+  OllamaApiError,
+  SAMPLE_MODEL_NAME,
+  connector,
+  createOllamaClient,
+  createOllamaConnector,
+  index_default as default,
+  describeFailure,
+  normalizeBaseUrl
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vornrun/connector-ollama",
+  "version": "0.1.0",
+  "description": "Trigger workflows when a local Ollama model is added, updated or loaded into memory, and chat, generate, embed, and list, show, pull, copy or delete models from a step.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Javier Canizalez <javier-canizalez@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vorn-run/connectors.git",
+    "directory": "packages/ollama"
+  },
+  "keywords": [
+    "vorn",
+    "connector",
+    "ollama",
+    "llm",
+    "mcp"
+  ],
+  "bin": {
+    "vorn-connector-ollama": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vornrun/connector-sdk": "^0.7.0-beta.14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "vorn": {
+    "category": "AI",
+    "keywords": [
+      "ollama",
+      "llm",
+      "local models",
+      "chat",
+      "generate",
+      "embeddings",
+      "qwen",
+      "llama",
+      "gemma"
+    ],
+    "auth": "Nothing to sign in with: Ollama serves http://localhost:11434 without credentials. Set OLLAMA_HOST for another server and OLLAMA_API_KEY for a hosted one.",
+    "packs": true
+  }
+}