@windagency/valora-plugin-ollama 1.0.0

package/README.md

@@ -0,0 +1,34 @@
+# @windagency/valora-plugin-ollama
+
+Self-managed Ollama LLM provider — runs models locally via the Ollama binary.
+
+## Install
+
+```bash
+valora plugin add ollama
+```
+
+The plugin depends on the `ollama` binary. On first run Valora prompts before running the install command. After install, the plugin manages the `ollama serve` lifecycle (start on activate, stop on deactivate) and lazily pulls any model that is requested but not yet local.
+
+## What it contributes
+
+- `api.providers.register('ollama', ...)` — an LLM provider with `validateModel` that lists locally pulled models via `/api/tags`.
+- `api.lifecycle.onDeactivate(...)` — gracefully stops the Ollama process.
+
+## Permissions
+
+- `code-exec` — required by the loader; also justified by `spawn('ollama', ['serve'])`.
+- `fs-write` — informational (the plugin's runtime code writes nothing; the install script does).
+- `network` — informational; the plugin polls `http://localhost:11434/api/tags` and pulls models.
+
+## Configuration
+
+| Env var                | Effect                                                        |
+| ---------------------- | ------------------------------------------------------------- |
+| `OLLAMA_DEFAULT_MODEL` | Default model when none is specified. Defaults to `llama3.1`. |
+
+The plugin requires no API key. `peerDependencies` includes `openai@^4.67.0` — Valora's host already provides this.
+
+## See also
+
+- [Plugins user guide](../../documentation/user-guide/plugins.md)

package/dist/index.js

@@ -0,0 +1,327 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+
+// src/binary-manager.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var OllamaNotInstalledError = class extends Error {
+  constructor() {
+    super("Ollama binary not found. Install from https://ollama.com and ensure it is on your PATH.");
+    this.name = "OllamaNotInstalledError";
+  }
+};
+var OllamaBinaryManagerImpl = class {
+  executor;
+  constructor(executor = () => execFileAsync("ollama", ["--version"])) {
+    this.executor = executor;
+  }
+  /** Returns `true` when `ollama --version` exits with code 0. */
+  async isInstalled() {
+    try {
+      await this.executor();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Throws {@link OllamaNotInstalledError} if the binary is not on PATH. */
+  async assertInstalled() {
+    if (!await this.isInstalled()) {
+      throw new OllamaNotInstalledError();
+    }
+  }
+};
+
+// src/model-manager.ts
+var OllamaApiError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "OllamaApiError";
+    this.statusCode = statusCode;
+  }
+};
+function assertOk(response, context) {
+  if (!response.ok) {
+    throw new OllamaApiError(`Ollama API error during ${context}: ${response.statusText}`, response.status);
+  }
+}
+var OllamaModelManagerImpl = class {
+  /** Returns the names of all models stored locally on the Ollama server. */
+  async listLocalModels(baseUrl) {
+    const response = await globalThis.fetch(`${baseUrl}/api/tags`);
+    assertOk(response, "listLocalModels");
+    const body = await response.json();
+    return body.models.map((m) => m.name);
+  }
+  /**
+   * Ensures the given model is available locally.
+   * If the model is already present, this method returns immediately.
+   * Otherwise it issues a pull request and waits for completion.
+   */
+  async ensureModel(baseUrl, model) {
+    const localModels = await this.listLocalModels(baseUrl);
+    if (localModels.includes(model)) {
+      return;
+    }
+    const response = await globalThis.fetch(`${baseUrl}/api/pull`, {
+      body: JSON.stringify({ name: model, stream: false }),
+      headers: { "Content-Type": "application/json" },
+      method: "POST"
+    });
+    assertOk(response, "ensureModel");
+  }
+};
+
+// src/ollama-provider.ts
+import OpenAI from "openai";
+var DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+var DEFAULT_MODEL = "llama3.1";
+var DEFAULT_EMBED_MODEL = "nomic-embed-text";
+var OllamaProvider = class {
+  name = "ollama";
+  client = null;
+  config;
+  managers;
+  constructor(config, managers) {
+    this.config = config;
+    this.managers = managers;
+  }
+  async complete(options) {
+    const model = options.model ?? this.getModel();
+    await this.ensureReady(model);
+    const response = await this.getClient().chat.completions.create({
+      max_tokens: options.max_tokens,
+      messages: this.mapMessages(options.messages),
+      model,
+      stop: options.stop,
+      temperature: options.temperature,
+      tools: options.tools?.map((tool) => ({
+        function: { description: tool.description, name: tool.name, parameters: tool.parameters },
+        type: "function"
+      })),
+      top_p: options.top_p
+    });
+    const choice = response.choices[0];
+    if (!choice) throw new Error("Ollama returned no choices");
+    return {
+      content: choice.message.content ?? "",
+      finish_reason: choice.finish_reason,
+      model: response.model,
+      role: "assistant",
+      tool_calls: choice.message.tool_calls?.map((tc) => ({
+        arguments: this.parseArgs(tc.function.arguments),
+        id: tc.id,
+        name: tc.function.name
+      })),
+      usage: response.usage ? {
+        completion_tokens: response.usage.completion_tokens,
+        prompt_tokens: response.usage.prompt_tokens,
+        total_tokens: response.usage.total_tokens
+      } : void 0
+    };
+  }
+  async embed(req) {
+    const model = req.model ?? DEFAULT_EMBED_MODEL;
+    await this.ensureReady(model);
+    const response = await this.getClient().embeddings.create({ input: req.input, model });
+    const vectors = response.data.map((d) => d.embedding);
+    const dim = vectors[0]?.length ?? 0;
+    return { dim, model: response.model, vectors };
+  }
+  getAlternativeModels() {
+    return ["llama3.1", "mistral", "codellama", "phi3", "qwen2"];
+  }
+  isConfigured() {
+    return true;
+  }
+  async streamComplete(options, onChunk) {
+    const model = options.model ?? this.getModel();
+    await this.ensureReady(model);
+    const stream = await this.getClient().chat.completions.create({
+      max_tokens: options.max_tokens,
+      messages: this.mapMessages(options.messages),
+      model,
+      stop: options.stop,
+      stream: true,
+      temperature: options.temperature,
+      top_p: options.top_p
+    });
+    let fullContent = "";
+    let finishReason;
+    for await (const chunk of stream) {
+      const choice = chunk.choices[0];
+      if (choice?.delta?.content) {
+        fullContent += choice.delta.content;
+        onChunk(choice.delta.content);
+      }
+      if (choice?.finish_reason) finishReason = choice.finish_reason;
+    }
+    return { content: fullContent, finish_reason: finishReason, role: "assistant" };
+  }
+  async validateModel(modelName) {
+    try {
+      const host = this.getOllamaHost();
+      await this.managers.binary.assertInstalled();
+      await this.managers.process.ensureRunning(host);
+      const models = await this.managers.model.listLocalModels(host);
+      return models.some((m) => m === modelName || m.startsWith(`${modelName}:`));
+    } catch {
+      return false;
+    }
+  }
+  async ensureReady(model) {
+    const host = this.getOllamaHost();
+    await this.managers.binary.assertInstalled();
+    await this.managers.process.ensureRunning(host);
+    await this.managers.model.ensureModel(host, model);
+  }
+  getClient() {
+    this.client ??= new OpenAI({
+      apiKey: "ollama",
+      baseURL: `${this.getOllamaHost()}/v1`,
+      maxRetries: 2
+    });
+    return this.client;
+  }
+  getModel() {
+    return getStringConfig(this.config, "model", DEFAULT_MODEL);
+  }
+  getOllamaHost() {
+    return getStringConfig(this.config, "ollama_host", DEFAULT_OLLAMA_HOST);
+  }
+  mapMessages(messages) {
+    return messages.map((m) => ({
+      content: m.content,
+      role: m.role
+    }));
+  }
+  parseArgs(raw) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+};
+function getStringConfig(config, key, fallback) {
+  const value = config[key];
+  return typeof value === "string" ? value : fallback;
+}
+
+// src/process-manager.ts
+import { spawn } from "child_process";
+var SIGKILL_TIMEOUT_MS = 5e3;
+var OllamaStartupError = class extends Error {
+  constructor(baseUrl) {
+    super(`Ollama server did not start within the expected time at ${baseUrl}.`);
+    this.name = "OllamaStartupError";
+  }
+};
+var OllamaProcessManagerImpl = class {
+  pollDelayMs;
+  process = null;
+  constructor(pollDelayMs = 500) {
+    this.pollDelayMs = pollDelayMs;
+  }
+  /** Returns `true` when a GET to `${baseUrl}/api/tags` responds with a 2xx status. */
+  async isRunning(baseUrl) {
+    try {
+      const response = await globalThis.fetch(`${baseUrl}/api/tags`);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /** Starts `ollama serve` if the server is not already reachable, then waits until ready. */
+  async ensureRunning(baseUrl) {
+    if (await this.isRunning(baseUrl)) return;
+    await this.startAndWait(baseUrl);
+  }
+  startAndWait(baseUrl) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (settled) return;
+        settled = true;
+        fn();
+      };
+      const child = spawn("ollama", ["serve"], { detached: false, stdio: "ignore" });
+      this.process = child;
+      child.once("error", (err) => {
+        this.process = null;
+        settle(() => reject(err));
+      });
+      child.once("close", () => {
+        this.process = null;
+      });
+      this.waitForReady(baseUrl).then(
+        () => settle(resolve),
+        (err) => settle(() => reject(err))
+      );
+    });
+  }
+  /**
+   * Sends SIGTERM to the managed process and waits for it to exit.
+   * If the process is already dead, resolves immediately without signalling.
+   * Escalates to SIGKILL after 5 000 ms if the process does not close.
+   */
+  async stop() {
+    const child = this.process;
+    if (!child) return;
+    this.process = null;
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolve();
+      }, SIGKILL_TIMEOUT_MS);
+      child.once("close", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      child.kill("SIGTERM");
+    });
+  }
+  async waitForReady(baseUrl, maxAttempts = 20) {
+    for (let i = 0; i < maxAttempts; i++) {
+      if (await this.isRunning(baseUrl)) return;
+      await sleep(this.pollDelayMs);
+    }
+    throw new OllamaStartupError(baseUrl);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/index.ts
+function register(api) {
+  const binary = new OllamaBinaryManagerImpl();
+  const processManager = new OllamaProcessManagerImpl();
+  const model = new OllamaModelManagerImpl();
+  api.providers.register("ollama", (config) => new OllamaProvider(config, { binary, model, process: processManager }), {
+    configSchema: void 0,
+    contextWindows: { codellama: 16384, "llama3.1": 128e3, mistral: 32768, phi3: 128e3, qwen2: 32768 },
+    defaultModel: "llama3.1",
+    description: "Self-managed Ollama provider \u2014 runs models locally via the Ollama binary",
+    envVars: { model: "OLLAMA_DEFAULT_MODEL" },
+    helpText: "Use any model available via ollama pull. No API key required.",
+    label: "Ollama",
+    modelModes: [
+      { mode: "default", model: "llama3.1" },
+      { mode: "default", model: "mistral" },
+      { mode: "default", model: "codellama" },
+      { mode: "default", model: "phi3" },
+      { mode: "default", model: "qwen2" }
+    ],
+    modelPrefix: "ollama:",
+    requiresApiKey: false
+  });
+  api.lifecycle.onDeactivate(async () => {
+    await processManager.stop();
+  });
+}
+export {
+  register
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@windagency/valora-plugin-ollama",
+  "version": "1.0.0",
+  "description": "Self-managed Ollama provider plugin for Valora — manages the Ollama binary and server process, supports any model available via ollama pull.",
+  "keywords": [
+    "valora",
+    "valora-plugin",
+    "ai",
+    "llm",
+    "ollama",
+    "local-llm",
+    "provider",
+    "self-hosted",
+    "open-source",
+    "typescript"
+  ],
+  "author": "Damien TIVELET <damien@wind-agency.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windagency/valora.ai"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "volta": {
+    "node": "22.21.0",
+    "pnpm": "10.19.0"
+  },
+  "files": [
+    "valora-plugin.json",
+    "dist"
+  ],
+  "peerDependencies": {
+    "@windagency/valora": ">=0.1.0",
+    "openai": "^4.67.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "openai": "^4.67.0",
+    "@windagency/valora-plugin-api": "1.0.0"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:openai --banner:js=\"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\"",
+    "clean": "rm -rf ./dist",
+    "lint": "eslint --color",
+    "lint:fix": "eslint --color --fix",
+    "beautify": "prettier --check \"**/*.+(js|jsx|ts|tsx|json|md|yml|yaml)\"",
+    "beautify:fix": "prettier --write \"**/*.+(js|jsx|ts|tsx|json|md|yml|yaml)\"",
+    "format": "pnpm beautify:fix && pnpm lint:fix",
+    "test": "vitest run"
+  }
+}

package/valora-plugin.json

@@ -0,0 +1,18 @@
+{
+	"name": "valora-plugin-ollama",
+	"version": "1.0.0",
+	"description": "Self-managed Ollama provider — downloads the Ollama binary on first use and runs it locally. Supports any model available via ollama pull.",
+	"engines": { "valora": ">=0.1.0" },
+	"contributes": ["code"],
+	"permissions": ["code-exec", "fs-write", "network"],
+	"requiresBinary": [
+		{
+			"autoInstall": true,
+			"install": "https://ollama.com",
+			"installCommand": "command -v zstd >/dev/null 2>&1 || sudo apt-get install -y zstd; curl -fsSL https://github.com/ollama/ollama/releases/latest/download/install.sh | sh",
+			"name": "ollama",
+			"postInstallCommand": "ollama serve >/dev/null 2>&1 & TRIES=0; until curl -sf http://localhost:11434/api/tags >/dev/null 2>&1 || [ $TRIES -ge 10 ]; do sleep 1; TRIES=$((TRIES+1)); done"
+		}
+	],
+	"codeEntrypoint": "dist/index.js"
+}