Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

8.1 KB
Raw Blame
// Pure on-disk reasoning for the Ollama↔LM Studio "copy weights locally instead
// of re-downloading" migrate fast-path.
//
// Both backends store the SAME GGUF weights — only the on-disk *layout* differs:
//   • LM Studio: plain files at  <models>/<publisher>/<repo>/<file>.gguf
//                (and Apple **MLX** models, which are NOT GGUF and have no
//                 Ollama equivalent)
//   • Ollama:    a content-addressed blob store —
//                <models>/blobs/sha256-<hash>  referenced by a JSON manifest at
//                <models>/manifests/<registry>/<namespace>/<name>/<tag>
//
// So a single-file GGUF text model can be imported across backends with no
// network pull. Multimodal (separate mmproj projector), sharded (`-00001-of-`),
// and MLX models are the exceptions the caller routes to re-pull / skip.
//
// This module is pure (no fs, no network) so it is unit-testable; the managers
// do the actual reads/copies using these helpers.

// Ollama manifest layer media types.
export const OLLAMA_MODEL_MEDIATYPE = 'application/vnd.ollama.image.model';
export const OLLAMA_PROJECTOR_MEDIATYPE = 'application/vnd.ollama.image.projector';

/**
 * Extract the weight + projector blob digests from a parsed Ollama manifest.
 * @param {object} manifest
 * @returns {{ modelDigest: string|null, projectorDigest: string|null }}
 */
export function parseOllamaManifest(manifest) {
  const layers = Array.isArray(manifest?.layers) ? manifest.layers : [];
  const find = (mt) => layers.find((l) => l?.mediaType === mt)?.digest || null;
  return { modelDigest: find(OLLAMA_MODEL_MEDIATYPE), projectorDigest: find(OLLAMA_PROJECTOR_MEDIATYPE) };
}

/** `sha256:abc123` → `sha256-abc123` (Ollama's blob filename form). */
export function digestToBlobFilename(digest) {
  return String(digest || '').replace(':', '-');
}

/**
 * Every blob a manifest needs on disk: the tiny config blob plus each layer, as
 * `{ digest, size, filename, hex }`. Ollama verifies ALL of them before writing
 * the manifest, so a pull that "reached 100%" can still be missing the config.
 * `size` is null (never 0) when the manifest doesn't declare one — absent and
 * legitimately-empty must not collapse. `hex` is the bare digest for comparing
 * against a locally computed hash.
 * @param {object} manifest a parsed Ollama/OCI manifest
 * @returns {Array<{ digest: string, size: number|null, filename: string, hex: string }>}
 */
export function manifestBlobRefs(manifest) {
  return [manifest?.config, ...(Array.isArray(manifest?.layers) ? manifest.layers : [])]
    .filter((entry) => entry?.digest)
    .map((entry) => ({
      digest: entry.digest,
      size: Number.isFinite(entry.size) ? entry.size : null,
      filename: digestToBlobFilename(entry.digest),
      hex: String(entry.digest).split(':').pop() || ''
    }));
}

/**
 * The Hugging Face OCI registry base URL for a passthrough pull ref
 * (`hf.co/<owner>/<repo>:<quant>`), or null when the ref isn't one — those are
 * the only refs whose manifest + blobs PortOS can fetch itself to finish a pull
 * Ollama abandoned, since HF exposes the OCI registry API at
 * `https://huggingface.co/v2/<owner>/<repo>/…`.
 *
 * Always addresses the canonical `huggingface.co` host: `hf.co` only
 * 307-redirects there, and the redirect costs a round trip on every blob.
 * @param {{ registry?: string, namespace?: string, name?: string, tag?: string }} ref
 * @returns {string|null}
 */
export function huggingFaceRegistryBase(ref) {
  const isHf = /^(hf\.co|huggingface\.co)$/i.test(String(ref?.registry || ''))
    && Boolean(ref?.namespace) && Boolean(ref?.name) && Boolean(ref?.tag);
  return isHf ? `https://huggingface.co/v2/${ref.namespace}/${ref.name}` : null;
}

/**
 * Parse an Ollama model ref into registry/namespace/name/tag, mirroring how
 * Ollama lays manifests out on disk. Bare names default to the
 * `registry.ollama.ai/library/<name>:latest` form.
 * @param {string} id e.g. `llama3.2:latest`, `gpt-oss:20b`, `myorg/m:tag`
 */
export function parseOllamaModelRef(id) {
  let rest = String(id || '').trim();
  if (!rest) return { registry: 'registry.ollama.ai', namespace: 'library', name: '', tag: 'latest' };

  // Split off the tag: the LAST `:` only when what follows has no `/` (so a
  // `host:port/...` registry prefix isn't mistaken for a tag).
  let tag = 'latest';
  const colon = rest.lastIndexOf(':');
  if (colon !== -1 && !rest.slice(colon + 1).includes('/')) {
    tag = rest.slice(colon + 1) || 'latest';
    rest = rest.slice(0, colon);
  }

  const parts = rest.split('/').filter(Boolean);
  let registry = 'registry.ollama.ai';
  let namespace = 'library';
  let name = rest;
  if (parts.length === 1) {
    name = parts[0];
  } else if (parts.length === 2) {
    [namespace, name] = parts;
  } else {
    // registry / namespace / name (extra path segments fold into the namespace)
    registry = parts[0];
    name = parts[parts.length - 1];
    namespace = parts.slice(1, -1).join('/');
  }
  return { registry, namespace, name, tag };
}

/** Relative manifest path (POSIX-joined) for a parsed ref. */
export function ollamaManifestRelPath({ registry, namespace, name, tag }) {
  return ['manifests', registry, namespace, name, tag].join('/');
}

/** A filesystem-safe Ollama model name for `ollama create` / `/api/create`. */
export function sanitizeOllamaName(id) {
  const base = String(id || '').split('/').pop() || '';
  const cleaned = base.trim().toLowerCase().replace(/[^a-z0-9._:-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
  return cleaned || 'imported-model';
}

/** Is this directory an MLX model (safetensors, no GGUF)? MLX ≠ GGUF. */
export function dirIsMlx(filenames = []) {
  const lower = filenames.map((f) => String(f).toLowerCase());
  const hasGguf = lower.some((f) => f.endsWith('.gguf'));
  const hasSafetensors = lower.some((f) => f.endsWith('.safetensors'));
  return hasSafetensors && !hasGguf;
}

/**
 * Is this filename a multimodal projector sidecar rather than model weights?
 * A projector is never loadable on its own, and repos publish it under the
 * target's own quant tag, so every "pick the model file" path has to skip it.
 */
export const isProjectorName = (f) => /(^|[-_./])(mmproj|projector)/i.test(f);
const isShardName = (f) => /-\d{5}-of-\d{5}\.gguf$/i.test(f);

/**
 * Pick the primary weights GGUF from a directory listing: skip projector files,
 * prefer the first shard of a sharded model, otherwise the first `.gguf`.
 * @returns {string|null} the chosen basename
 */
export function selectPrimaryGguf(filenames = []) {
  const ggufs = filenames.filter((f) => /\.gguf$/i.test(f) && !isProjectorName(f));
  if (ggufs.length === 0) return null;
  const firstShard = ggufs.find((f) => /-00001-of-\d{5}\.gguf$/i.test(f));
  return firstShard || ggufs[0];
}

/** Find the multimodal projector GGUF in a listing, if any. */
export function selectProjectorGguf(filenames = []) {
  return filenames.find((f) => /\.gguf$/i.test(f) && isProjectorName(f)) || null;
}

/** True when the chosen GGUF is one part of a multi-file (sharded) model. */
export function isShardedGguf(basename) {
  return isShardName(String(basename || ''));
}

// Make one id segment safe to use as a directory name on every platform —
// anything outside [A-Za-z0-9._-] (notably `:` from Ollama tags like
// `model:latest`, and `\` on Windows) collapses to `-`.
const fsSafeSegment = (s) => String(s || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'model';

/**
 * Split an LM Studio model id into its on-disk `<publisher>/<repo>` parts,
 * sanitized into filesystem-safe path components (the id may be migration-
 * generated, e.g. `imported/llama3.2:latest`, not just a clean LM Studio id).
 * Bare ids (no `/`) land under an `imported` publisher.
 */
export function lmStudioPublisherRepo(lmstudioId) {
  const parts = String(lmstudioId || '').split('/').filter(Boolean);
  if (parts.length >= 2) return { publisher: fsSafeSegment(parts[0]), repo: fsSafeSegment(parts.slice(1).join('-')) };
  return { publisher: 'imported', repo: fsSafeSegment(parts[0] || 'model') };
}

/** A `FROM <gguf>` Modelfile body for importing a local GGUF into Ollama. */
export function buildModelfile(ggufPath) {
  return `FROM ${ggufPath}\n`;
}