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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect } from 'vitest';
import {
classifyHfMediaModel,
inspectModelFiles,
customModelIdFromRepo,
buildCustomModelEntry,
searchHuggingfaceModels,
} from './huggingfaceModel.js';
// Build a minimal HF `/api/models/{repo}` response.
const hf = ({ files = [], tags = [], base = null, pipeline = null } = {}) => ({
siblings: files.map((rfilename) => ({ rfilename })),
tags,
cardData: base ? { base_model: base } : {},
pipeline_tag: pipeline,
});
describe('inspectModelFiles', () => {
it('detects safetensors and gguf presence', () => {
expect(inspectModelFiles(hf({ files: ['model.safetensors', 'config.json'] })))
.toMatchObject({ hasSafetensors: true, hasGguf: false });
expect(inspectModelFiles(hf({ files: ['model-Q4_K_M.gguf'] })))
.toMatchObject({ hasSafetensors: false, hasGguf: true });
});
});
describe('classifyHfMediaModel — strict refusal', () => {
it('refuses a GGUF-only repo (no runtime can load it)', () => {
expect(() => classifyHfMediaModel({
repo: 'unsloth/LTX-2.3-GGUF',
model: hf({ files: ['ltx-2.3-22b-distilled-Q4_K_M.gguf'], tags: ['ltx'] }),
})).toThrow(/GGUF/);
});
it('refuses a repo with no safetensors', () => {
expect(() => classifyHfMediaModel({
repo: 'foo/bar',
model: hf({ files: ['README.md'] }),
})).toThrow(/no .safetensors/i);
});
it('refuses Wan repos (BYO-venv, not self-service)', () => {
expect(() => classifyHfMediaModel({
repo: 'Wan-AI/Wan2.2-T2V-A14B',
model: hf({ files: ['model.safetensors'], tags: ['wan'] }),
})).toThrow(/Wan/);
});
it('refuses HunyuanVideo repos', () => {
expect(() => classifyHfMediaModel({
repo: 'tencent/HunyuanVideo',
model: hf({ files: ['model.safetensors'], tags: ['hunyuan'] }),
})).toThrow(/Hunyuan/);
});
it('refuses an unsupported Hunyuan repo even when an addable runtime is forced', () => {
// The "a bad add can't wedge the picker" guarantee must hold even under an
// explicit runtime override — forcing mlx_video on a Hunyuan repo would
// register an entry no runtime can load.
expect(() => classifyHfMediaModel({
repo: 'tencent/HunyuanVideo',
model: hf({ files: ['model.safetensors'], tags: ['hunyuan'] }),
kind: 'video',
runtime: 'mlx_video',
})).toThrow(/not supported by PortOS/);
});
it('refuses a wan/hunyuan repo even when kind:image is forced (override cannot skip the video guard)', () => {
// kind:'image' would route into the image branch and bypass the video-only
// refusal — the guard must run unconditionally, before kind resolution.
expect(() => classifyHfMediaModel({
repo: 'Wan-AI/Wan2.2-T2V-A14B',
model: hf({ files: ['model.safetensors'], tags: ['wan'] }),
kind: 'image',
runner: 'qwen',
})).toThrow(/needs a dedicated venv/);
});
it('refuses a LoRA adapter repo (belongs in the LoRA manager, not base models)', () => {
// base_model in the card is the adapter signal.
expect(() => classifyHfMediaModel({
repo: 'fal/ltx2.3-audio-reactive-lora',
model: hf({ files: ['pytorch_lora_weights.safetensors'], tags: ['lora', 'ltx-video'], base: 'Lightricks/LTX-Video' }),
})).toThrow(/LoRA adapter/);
});
it('refuses a diffusers LoRA repo by its pytorch_lora_weights.safetensors file (no lora tag)', () => {
expect(() => classifyHfMediaModel({
repo: 'someone/qwen-style',
model: hf({ files: ['pytorch_lora_weights.safetensors'], base: 'Qwen/Qwen-Image', pipeline: 'text-to-image' }),
})).toThrow(/LoRA adapter/);
});
it('refuses a PEFT adapter repo detected by its sibling files (no lora tag)', () => {
// adapter_config.json + adapter_model.safetensors is the standard PEFT
// layout; the repo advertises no lora tag but is still an adapter.
expect(() => classifyHfMediaModel({
repo: 'someone/qwen-finetune-adapter',
model: hf({ files: ['adapter_config.json', 'adapter_model.safetensors'], base: 'Qwen/Qwen-Image', pipeline: 'text-to-image' }),
})).toThrow(/LoRA adapter/);
});
it('does NOT treat a full base model as a LoRA just because its card sets base_model', () => {
// Full fine-tunes / derived base models legitimately declare base_model but
// ship complete weights — they must remain addable (no lora/peft marker).
expect(classifyHfMediaModel({
repo: 'someone/qwen-image-finetune',
model: hf({ files: ['model.safetensors'], base: 'Qwen/Qwen-Image', pipeline: 'text-to-image' }),
kind: 'image',
runner: 'qwen',
})).toMatchObject({ kind: 'image', runner: 'qwen' });
});
it('refuses a quantized FLUX.2 repo (needs sibling tokenizer/base repos)', () => {
expect(() => classifyHfMediaModel({
repo: 'Disty0/FLUX.2-klein-9B-SDNQ-4bit-dynamic',
model: hf({ files: ['model.safetensors'], tags: ['sdnq'], pipeline: 'text-to-image' }),
})).toThrow(/quantized FLUX\.2/);
});
it('refuses an unclassifiable safetensors repo with no kind hint', () => {
expect(() => classifyHfMediaModel({
repo: 'someone/mystery-weights',
model: hf({ files: ['model.safetensors'] }),
})).toThrow(/image or video/);
});
});
describe('classifyHfMediaModel — happy paths', () => {
it('classifies an LTX safetensors repo as video/mlx_video', () => {
expect(classifyHfMediaModel({
repo: 'notapalindrome/ltx23-mlx-av-q4',
model: hf({ files: ['model.safetensors'], tags: ['ltx-video'] }),
isWindows: false,
})).toEqual({ kind: 'video', runtime: 'mlx_video', format: 'safetensors' });
});
it('auto-detects a dgrauet LTX repo as the ltx2 runtime (not mlx_video)', () => {
expect(classifyHfMediaModel({
repo: 'dgrauet/ltx-2.3-mlx-q8',
model: hf({ files: ['model.safetensors'], tags: ['ltx'] }),
isWindows: false,
})).toEqual({ kind: 'video', runtime: 'ltx2', format: 'safetensors' });
});
it('auto-detects an LTX-2.5 MLX repo as the ltx25 runtime', () => {
expect(classifyHfMediaModel({
repo: 'MrMofer/ltx-2.5-mlx-q8',
model: hf({ files: ['transformer-distilled.safetensors'], tags: ['ltx-2.5'] }),
isWindows: false,
})).toEqual({ kind: 'video', runtime: 'ltx25', format: 'safetensors' });
});
it('adds Qwen 2.1 with its unified pipeline even when tagged for editing', () => {
const repo = 'Qwen/Qwen-Image-2.1';
const model = hf({ files: ['model.safetensors'], tags: ['edit'], pipeline: 'image-to-image' });
const classification = classifyHfMediaModel({ repo, model });
const entry = buildCustomModelEntry({ repo, model, classification });
expect(entry).toMatchObject({ runner: 'qwen', pipelineClass: 'QwenImage21Pipeline', steps: 40, guidance: 1, cfgDisabled: true });
expect(entry.editOnly).toBeUndefined();
});
it('detects a Qwen-Image-Edit repo and stamps the edit pipeline + editOnly', () => {
const c = classifyHfMediaModel({
repo: 'Qwen/Qwen-Image-Edit',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-image' }),
});
expect(c).toMatchObject({ kind: 'image', runner: 'qwen', editVariant: true });
const entry = buildCustomModelEntry({ repo: 'Qwen/Qwen-Image-Edit', model: hf({}), classification: c });
expect(entry).toMatchObject({ runner: 'qwen', pipelineClass: 'QwenImageEditPipeline', editOnly: true });
});
it('honors an explicit ltx2 runtime override', () => {
expect(classifyHfMediaModel({
repo: 'dgrauet/ltx-2.3-mlx-q8',
model: hf({ files: ['model.safetensors'], tags: ['ltx'] }),
runtime: 'ltx2',
isWindows: false,
})).toEqual({ kind: 'video', runtime: 'ltx2', format: 'safetensors' });
});
it('detects a FLUX.2 image repo as flux2', () => {
expect(classifyHfMediaModel({
repo: 'black-forest-labs/FLUX.2-klein-9B',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-image' }),
})).toEqual({ kind: 'image', runner: 'flux2', format: 'safetensors' });
});
it('detects a Qwen image repo', () => {
expect(classifyHfMediaModel({
repo: 'Qwen/Qwen-Image',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-image' }),
})).toEqual({ kind: 'image', runner: 'qwen', format: 'safetensors' });
});
it('refuses a custom video add on Windows (render path can not load a custom repo)', () => {
expect(() => classifyHfMediaModel({
repo: 'notapalindrome/ltx23-mlx-av-q4',
model: hf({ files: ['model.safetensors'], tags: ['ltx-video'] }),
isWindows: true,
})).toThrow(/can't be added on Windows/);
});
it('still allows a custom IMAGE add on Windows (cross-platform diffusers venv)', () => {
expect(classifyHfMediaModel({
repo: 'Qwen/Qwen-Image',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-image' }),
isWindows: true,
})).toMatchObject({ kind: 'image', runner: 'qwen' });
});
it('rejects an invalid explicit runtime', () => {
expect(() => classifyHfMediaModel({
repo: 'x/y',
model: hf({ files: ['model.safetensors'], tags: ['ltx'] }),
runtime: 'gguf-runtime',
})).toThrow(/can't be added self-service/);
});
it('falls back to a caller-supplied kind+runner for an ambiguous image repo', () => {
expect(classifyHfMediaModel({
repo: 'someone/custom-diffusers',
model: hf({ files: ['model.safetensors'] }),
kind: 'image',
runner: 'qwen',
})).toEqual({ kind: 'image', runner: 'qwen', format: 'safetensors' });
});
it('refuses a detected mflux (Flux.1) repo — mflux ignores a custom repo', () => {
// mflux-generate only loads its built-in dev/schnell aliases, so a custom
// repo would register but fail at render — refuse it up front.
expect(() => classifyHfMediaModel({
repo: 'black-forest-labs/FLUX.1-dev',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-image' }),
})).toThrow(/mflux|Flux\.1/);
});
it('rejects an explicit mflux runner override (off the addable allowlist)', () => {
expect(() => classifyHfMediaModel({
repo: 'someone/x',
model: hf({ files: ['model.safetensors'] }),
kind: 'image',
runner: 'mflux',
})).toThrow(/Unknown image runner|mflux/);
});
it('refuses a text-to-video repo with no detected runtime (would 400 at render on mlx_video)', () => {
// pipeline_tag says video but no LTX/Wan/Hunyuan marker — mlx_video only
// loads LTX, so defaulting to it would register an un-renderable entry.
expect(() => classifyHfMediaModel({
repo: 'someone/mystery-video',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-video' }),
isWindows: false,
})).toThrow(/Couldn't determine which video runtime/);
});
it('accepts an undetected video repo when an explicit runtime is supplied', () => {
expect(classifyHfMediaModel({
repo: 'someone/mystery-video',
model: hf({ files: ['model.safetensors'], pipeline: 'text-to-video' }),
runtime: 'mlx_video',
isWindows: false,
})).toEqual({ kind: 'video', runtime: 'mlx_video', format: 'safetensors' });
});
});
describe('customModelIdFromRepo', () => {
it('slugifies with an hf- prefix', () => {
expect(customModelIdFromRepo('notapalindrome/ltx23-mlx-av-q4')).toBe('hf-notapalindrome-ltx23-mlx-av-q4');
expect(customModelIdFromRepo('black-forest-labs/FLUX.2-klein-9B')).toBe('hf-black-forest-labs-flux-2-klein-9b');
});
});
describe('buildCustomModelEntry', () => {
it('builds a video entry with runtime + user source + defaults', () => {
const entry = buildCustomModelEntry({
repo: 'notapalindrome/ltx23-mlx-av-q4',
model: hf({ tags: ['ltx'] }),
classification: { kind: 'video', runtime: 'mlx_video', format: 'safetensors' },
});
expect(entry).toMatchObject({
id: 'hf-notapalindrome-ltx23-mlx-av-q4',
repo: 'notapalindrome/ltx23-mlx-av-q4',
runtime: 'mlx_video',
source: 'user',
steps: 25,
guidance: 3.0,
});
expect(entry.runner).toBeUndefined();
expect(entry.installedAt).toBeTruthy();
});
it('builds an image entry with runner + honors overrides', () => {
const entry = buildCustomModelEntry({
repo: 'Qwen/Qwen-Image',
model: hf({}),
classification: { kind: 'image', runner: 'qwen', format: 'safetensors' },
name: 'My Qwen',
steps: 40,
guidance: 5,
});
expect(entry).toMatchObject({ runner: 'qwen', name: 'My Qwen', steps: 40, guidance: 5, source: 'user' });
expect(entry.runtime).toBeUndefined();
expect(entry.quantization).toBeUndefined(); // only flux2 needs it
});
it('stamps quantization:none on a flux2 entry so the runner uses repo directly (no tokenizerRepo 400)', () => {
const entry = buildCustomModelEntry({
repo: 'black-forest-labs/FLUX.2-klein-9B',
model: hf({}),
classification: { kind: 'image', runner: 'flux2', format: 'safetensors' },
});
expect(entry).toMatchObject({ runner: 'flux2', quantization: 'none', source: 'user' });
});
it('stamps ERNIE pipeline metadata the runner requires', () => {
const entry = buildCustomModelEntry({
repo: 'baidu/ERNIE-Image',
model: hf({}),
classification: { kind: 'image', runner: 'ernie', format: 'safetensors' },
});
expect(entry).toMatchObject({ runner: 'ernie', pipelineClass: 'ErnieImagePipeline', usePromptEnhancer: true });
});
it('stamps HiDream pipeline + gated text-encoder metadata', () => {
const entry = buildCustomModelEntry({
repo: 'HiDream-ai/HiDream-I1-Full',
model: hf({}),
classification: { kind: 'image', runner: 'hidream', format: 'safetensors' },
});
expect(entry).toMatchObject({
runner: 'hidream',
pipelineClass: 'HiDreamImagePipeline',
textEncoderRepo: 'meta-llama/Meta-Llama-3.1-8B-Instruct',
textEncoderClass: 'LlamaForCausalLM',
});
});
it('stamps the Qwen pipeline class', () => {
const entry = buildCustomModelEntry({
repo: 'Qwen/Qwen-Image',
model: hf({}),
classification: { kind: 'image', runner: 'qwen', format: 'safetensors' },
});
expect(entry).toMatchObject({ runner: 'qwen', pipelineClass: 'QwenImagePipeline' });
});
});
describe('searchHuggingfaceModels', () => {
it('builds the search URL and maps rows', async () => {
let calledUrl = null;
const fetchImpl = async (url) => {
calledUrl = url;
return {
ok: true,
text: async () => JSON.stringify([
{ id: 'org/a', likes: 5, downloads: 100, pipeline_tag: 'text-to-image' },
{ modelId: 'org/b', pipeline_tag: 'text-to-video' },
{ likes: 1 }, // no id → dropped
]),
};
};
const rows = await searchHuggingfaceModels('ltx', { pipeline: 'text-to-video', limit: 5, fetchImpl });
expect(calledUrl).toContain('search=ltx');
expect(calledUrl).toContain('pipeline_tag=text-to-video');
expect(calledUrl).toContain('limit=5');
expect(rows).toEqual([
{ id: 'org/a', likes: 5, downloads: 100, pipeline_tag: 'text-to-image' },
{ id: 'org/b', likes: 0, downloads: 0, pipeline_tag: 'text-to-video' },
]);
});
it('throws on a non-ok response', async () => {
const fetchImpl = async () => ({ ok: false, status: 503, text: async () => '' });
await expect(searchHuggingfaceModels('x', { fetchImpl })).rejects.toThrow(/search failed/i);
});
});