ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
#!/usr/bin/env python3
"""Validate the host-side model artifacts needed for offline ODS operation."""
from __future__ import annotations
import os
import re
import sys
from pathlib import Path
DEFAULT_STT_MODEL = "Systran/faster-whisper-base"
DEFAULT_EMBEDDING_MODEL = "BAAI/bge-base-en-v1.5"
WHISPER_COMPOSE = "extensions/services/whisper/compose.yaml"
EMBEDDINGS_COMPOSE = "extensions/services/embeddings/compose.yaml"
TTS_COMPOSE = "extensions/services/tts/compose.yaml"
MODEL_ARTIFACT_SUFFIXES = {
".bin",
".ckpt",
".gguf",
".model",
".onnx",
".pt",
".pth",
".safetensors",
}
HF_REPO_ID_RE = re.compile(
r"^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$"
)
def ods_root() -> Path:
"""Return the install root, allowing an explicit override for tooling/tests."""
override = os.environ.get("ODS_ROOT")
if override:
return Path(override).expanduser().resolve()
return Path(__file__).resolve().parent.parent
def env_value(root: Path, key: str, default: str = "") -> str:
"""Read one KEY=value from the install's .env, or return ``default``."""
env_path = root / ".env"
if not env_path.is_file():
return default
prefix = f"{key}="
for raw in env_path.read_text(encoding="utf-8", errors="replace").splitlines():
line = raw.strip()
if not line.startswith(prefix):
continue
value = line[len(prefix):].strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
value = value[1:-1]
return value or default
return default
def model_candidates(cache_root: Path, repo_id: str) -> list[Path]:
"""Return supported installer and manual layouts for a Hugging Face repo."""
org_name = repo_id.replace("/", "--")
return [
cache_root / f"models--{org_name}",
cache_root / repo_id,
cache_root / repo_id.split("/")[-1],
]
def _usable_file(path: Path) -> bool:
"""A finalized model artifact must resolve to a non-empty regular file."""
if path.name.endswith((".incomplete", ".lock", ".part")):
return False
if path.suffix.lower() not in MODEL_ARTIFACT_SUFFIXES:
return False
try:
return path.is_file() and path.stat().st_size > 0
except OSError:
return False
def _tree_has_usable_file(path: Path) -> bool:
try:
return any(_usable_file(item) for item in path.rglob("*"))
except OSError:
return False
def hf_model_path(cache_root: Path, repo_id: str) -> Path | None:
"""Locate a usable snapshot for ``repo_id`` below ``cache_root``.
Hugging Face cache directories are not complete merely because the
``models--org--repo`` directory exists. A finalized snapshot must contain
at least one non-empty file (or a symlink resolving to one). Manually
populated bare layouts use the same file-level readiness rule.
"""
for candidate in model_candidates(cache_root, repo_id):
if not candidate.is_dir():
continue
content_root = candidate / "snapshots" if candidate.name.startswith("models--") else candidate
if content_root.is_dir() and _tree_has_usable_file(content_root):
return candidate
return None
def _compose_flags(root: Path) -> set[str] | None:
flags_path = root / ".compose-flags"
if not flags_path.is_file():
return None
value = flags_path.read_text(encoding="utf-8", errors="replace").strip()
if not value:
return None
return {
token.strip("\"'").replace("\\", "/").lower()
for token in value.split()
}
def _bool_value(value: str) -> bool | None:
normalized = value.strip().lower()
if normalized in {"1", "true", "yes", "on"}:
return True
if normalized in {"0", "false", "no", "off"}:
return False
return None
def service_enabled(
root: Path,
compose_fragment: str,
env_keys: tuple[str, ...],
) -> bool:
"""Return whether a model-backed service belongs to the active stack.
Once installation has produced ``.compose-flags``, that file is the
runtime source of truth. Before then, explicit feature flags are honored;
absent feature state preserves the historical preflight behavior and
validates the model.
"""
flags = _compose_flags(root)
if flags is not None:
expected = compose_fragment.lower()
return any(
token == expected or token.endswith(f"/{expected}")
for token in flags
)
explicit: list[bool] = []
for key in env_keys:
raw = env_value(root, key)
parsed = _bool_value(raw) if raw else None
if parsed is not None:
explicit.append(parsed)
if explicit:
return any(explicit)
return True
def local_llm_required(root: Path) -> tuple[bool, str]:
"""Describe whether ODS owns a GGUF file for the configured LLM backend."""
mode = env_value(root, "ODS_MODE", "local").lower()
backend = env_value(root, "LLM_BACKEND", "llama-server").lower()
if backend == "external":
return False, "model storage belongs to the external backend"
if mode == "cloud" or backend in {"cloud", "litellm", "remote"}:
return False, "cloud/remote backend"
if env_value(root, "NATIVE_LLM_BASE_URL", ""):
return False, "the host-native llama-server (Windows) keeps the model on Windows"
return True, ""
def check_gguf_set(candidate: Path) -> tuple[bool, str]:
"""Require every finalized shard of a conventionally named split GGUF."""
if not _usable_file(candidate):
return False, f"Not found or empty: data/models/{candidate.name}"
split = re.fullmatch(r"(.+)-(\d{5})-of-(\d{5})(\.gguf)", candidate.name, re.IGNORECASE)
if split:
prefix, index, total, suffix = split.groups()
if int(index) != 1 or int(total) < 1:
return False, f"Expected the first split GGUF shard: {prefix}-00001-of-{total}{suffix}"
for part in range(1, int(total) + 1):
required = candidate.with_name(f"{prefix}-{part:05d}-of-{total}{suffix}")
if not _usable_file(required):
return False, f"Split GGUF incomplete; not found or empty: data/models/{required.name}"
return True, f"OK: data/models/{candidate.name} ({int(total)} parts)"
return True, f"OK: data/models/{candidate.name}"
def check_llm(root: Path) -> tuple[bool, str]:
models_dir = root / "data" / "models"
configured = env_value(root, "GGUF_FILE")
if configured:
if Path(configured).name != configured:
return False, f"Invalid GGUF_FILE (expected a filename): {configured}"
return check_gguf_set(models_dir / configured)
if models_dir.is_dir():
candidates = sorted(models_dir.glob("*.gguf"))
for candidate in candidates:
result = check_gguf_set(candidate)
if result[0]:
return result
if candidates:
return check_gguf_set(candidates[0])
return False, "Not found: data/models/*.gguf"
def check_hf_model(
root: Path,
cache_dir: str,
model_env: str,
default_model: str,
) -> tuple[bool, str]:
repo_id = env_value(root, model_env, default_model)
if not HF_REPO_ID_RE.fullmatch(repo_id):
return False, f"Invalid {model_env}: {repo_id or '<empty>'}"
found = hf_model_path(root / cache_dir, repo_id)
if found is None:
return False, f"Not found or incomplete: {cache_dir}/ ({repo_id})"
return True, f"OK: {found.relative_to(root)}"
def installer_command(platform_name: str | None = None) -> str:
"""Return the in-place installer command for the current platform."""
return r".\install.ps1" if (platform_name or os.name) == "nt" else "./install.sh"
def main() -> int:
root = ods_root()
results: list[tuple[str, bool | None, str]] = []
needs_llm, reason = local_llm_required(root)
if needs_llm:
ok, detail = check_llm(root)
results.append(("Primary LLM (GGUF model)", ok, detail))
else:
results.append(("Primary LLM", None, f"Skipped: {reason}"))
voice_enabled = service_enabled(root, WHISPER_COMPOSE, ("ENABLE_VOICE",))
if voice_enabled:
ok, detail = check_hf_model(
root, "data/whisper", "AUDIO_STT_MODEL", DEFAULT_STT_MODEL
)
results.append(("Whisper STT model", ok, detail))
else:
results.append(("Whisper STT model", None, "Skipped: service is not active"))
if service_enabled(root, TTS_COMPOSE, ("ENABLE_VOICE",)):
results.append(
("Kokoro TTS voice", None, "Bundled with the pinned TTS image")
)
else:
results.append(("Kokoro TTS voice", None, "Skipped: service is not active"))
if service_enabled(
root,
EMBEDDINGS_COMPOSE,
("ENABLE_EMBEDDINGS", "ENABLE_RAG"),
):
ok, detail = check_hf_model(
root,
"data/embeddings",
"EMBEDDING_MODEL",
DEFAULT_EMBEDDING_MODEL,
)
results.append(("Embedding model", ok, detail))
else:
results.append(("Embedding model", None, "Skipped: service is not active"))
print("=" * 72)
print("ODS Offline Mode - Model Validation")
print("=" * 72)
missing: list[str] = []
for description, ok, detail in results:
status = "OK" if ok is True else "MISSING" if ok is False else "SKIP"
print(f"[{status:7s}] {description:30s} {detail}")
if ok is False:
missing.append(description)
print("=" * 72)
if not missing:
print("All active host-side model artifacts are ready for offline mode.")
return 0
print(f"\nMISSING OR INCOMPLETE: {', '.join(missing)}")
print("\nReconnect this host and rerun the installer in place:")
print(f" {installer_command()}")
print("The installer preserves configuration/data and populates active model caches.")
return 1
if __name__ == "__main__":
sys.exit(main())