Skip to content

armgit / ODS

Public Imported from GitHub
0

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.

7.6 KB
Raw Blame
#!/usr/bin/env python3
"""Register an additional local model directory and its read-only API mount.

Does not move existing files, restart services, or select a model. Recreate the
dashboard API with the generated Compose overlay to expose the new directory.
"""
from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import sys
import tempfile
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'extensions/services/dashboard-api'))
from model_stores import MAX_REGISTRY_BYTES
from model_mtp import qualify_memory_fit


def atomic_json(path: Path, value: dict) -> None:
    if path.is_symlink():
        raise ValueError('Refusing to replace a symlinked model store configuration')
    content = json.dumps(value, indent=2) + '\n'
    if len(content.encode()) > MAX_REGISTRY_BYTES:
        raise ValueError('Model store configuration is too large')
    descriptor, temporary = tempfile.mkstemp(prefix=path.name+'.', suffix='.tmp', dir=path.parent)
    try:
        with os.fdopen(descriptor, 'w', encoding='utf-8') as target:
            target.write(content)
            target.flush()
            os.fsync(target.fileno())
        os.chmod(temporary, 0o644)
        os.replace(temporary, path)
    finally:
        Path(temporary).unlink(missing_ok=True)


def register(install: Path, identifier: str, directory: Path, qualified: Path | None = None, enable_mtp: bool = False, backend: str | None = None, benchmark_evidence: Path | None = None) -> dict:
    install, directory = install.resolve(strict=True), directory.resolve(strict=True)
    if not directory.is_dir() or not re.fullmatch(r'[a-z][a-z0-9-]{0,47}', identifier) or identifier == 'default':
        raise ValueError('An existing model directory and unique store id are required')
    data = install/'data'
    data.mkdir(exist_ok=True)
    registry_path = data/'model-stores.json'
    if registry_path.is_symlink() or (registry_path.exists() and registry_path.stat().st_size > MAX_REGISTRY_BYTES):
        raise ValueError('Unsafe model store configuration')
    document = json.loads(registry_path.read_text()) if registry_path.exists() else {'schemaVersion':1,'stores':[]}
    if document.get('schemaVersion') != 1 or not isinstance(document.get('stores'), list) or len(document['stores']) > 16:
        raise ValueError('Invalid or full model store configuration')
    previous = next((item for item in document['stores'] if item.get('id') == identifier), None)
    if not previous and len(document['stores']) == 16:
        raise ValueError('Model store configuration is full')
    if any(item.get('id') != identifier and Path(item['hostPath']).resolve() == directory for item in document['stores']):
        raise ValueError('The directory is already registered under a different store id')
    if previous and Path(previous['hostPath']).resolve() != directory:
        raise ValueError('The store id is already registered for another directory')
    old_profiles = previous.get('profiles', {}) if previous else {}
    if not isinstance(old_profiles, dict):
        raise ValueError('Invalid existing model profiles')
    entry = {'id':identifier,'hostPath':directory.as_posix(),'containerPath':f'/model-stores/{identifier}','profiles':dict(old_profiles)}
    if qualified is not None:
        if backend not in {'vulkan','rocm','cpu','metal','cuda'}:
            raise ValueError('Choose the backend qualified on this machine explicitly')
        profile = json.loads(qualified.read_text(encoding='utf-8'))
        command = profile.get('baselineCommand', [])
        if len(command) < 3 or command[1] != '--model' or profile.get('schemaVersion') != 1:
            raise ValueError('Use a profile generated by qualify-mtp.py')
        runtime, checkpoint = Path(command[0]).resolve(strict=True), Path(command[2]).resolve(strict=True)
        if checkpoint.parent != directory or checkpoint.is_symlink() or not runtime.is_file():
            raise ValueError('Qualified model must exist directly inside the registered directory')
        if enable_mtp and not profile.get('runtime', {}).get('mtp'):
            raise ValueError('The qualified runtime does not support MTP')
        entry['profiles'][checkpoint.name] = {'backend':backend,
            'executable':str(runtime), 'contextLength':profile['profile']['context'], 'mtp':enable_mtp,
            'draftTokens':profile['profile']['draftTokens'], 'modelSha256':profile['profile']['modelSha256'],
            'loadModeArguments':profile['profile'].get('loadModeArguments', []),
            'runtimeSha256':profile['profile']['runtimeSha256'], 'qualificationSignature':profile['signature']}
        if benchmark_evidence is not None:
            if benchmark_evidence.stat().st_size > MAX_REGISTRY_BYTES:
                raise ValueError('Benchmark summary is too large')
            fit = qualify_memory_fit(json.loads(benchmark_evidence.read_text(encoding='utf-8')), profile)
            if fit['runtimeBackend'] != backend:
                raise ValueError('Measured native backend differs from the registered backend')
            projector = directory / fit['visionProjectorFile']
            if projector.is_symlink() or not projector.is_file():
                raise ValueError('Measured vision projector is unavailable')
            digest = hashlib.sha256()
            with projector.open('rb') as source:
                for block in iter(lambda: source.read(8*1024*1024), b''):
                    digest.update(block)
            if digest.hexdigest() != fit['visionProjectorSha256']:
                raise ValueError('Vision projector changed since memory qualification')
            fit['visionProjectorSize'] = projector.stat().st_size
            fit['visionProjectorMtimeNs'] = projector.stat().st_mtime_ns
            entry['profiles'][checkpoint.name]['memoryQualification'] = fit
    document['stores'] = [item for item in document['stores'] if item.get('id') != identifier] + [entry]
    # A generated, data-only Compose document avoids shell/platform quoting.
    volumes = [{'type':'bind','source':item['hostPath'],'target':item['containerPath'],'read_only':True,
                'bind':{'create_host_path':False}} for item in document['stores']]
    overlay = {'services':{'dashboard-api':{'volumes':volumes}}}
    atomic_json(install/'.model-stores.compose.json', overlay)
    atomic_json(registry_path, document)
    return {'registered':identifier,'hostPath':directory.as_posix(),'overlay':str(install/'.model-stores.compose.json'),
            'requiresApiRecreate':True,'modelSelected':False}


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--install-dir',type=Path,required=True)
    parser.add_argument('--id',required=True)
    parser.add_argument('--directory',type=Path,required=True)
    parser.add_argument('--qualified-profile',type=Path)
    parser.add_argument('--backend',choices=['vulkan','rocm','cpu','metal','cuda'])
    parser.add_argument('--enable-mtp',action='store_true',help='Explicitly enable the qualified MTP runtime for this model; does not assert a speedup')
    parser.add_argument('--benchmark-evidence',type=Path,help='Completed isolated benchmark proving memory fit for this exact native profile')
    args = parser.parse_args()
    if args.enable_mtp and not args.qualified_profile:
        parser.error('--enable-mtp requires --qualified-profile')
    if args.benchmark_evidence and not args.qualified_profile:
        parser.error('--benchmark-evidence requires --qualified-profile')
    print(json.dumps(register(args.install_dir,args.id,args.directory,args.qualified_profile,args.enable_mtp,args.backend,args.benchmark_evidence),indent=2))


if __name__ == '__main__':
    main()