colabllm 0.1.0__py3-none-any.whl

colabllm/__init__.py

@@ -0,0 +1 @@
+"""Colab model service CLI."""

colabllm/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

colabllm/cli.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Unified CLI for packaged Colab model services (Python standard library only)."""
+import os
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parent
+GLOBAL_COMMANDS = ('tunnel-config', 'frp-config', 'frp-status')
+UTILITY_COMMANDS = ('doctor', 'completion', 'skill')
+
+
+def services():
+    """Discover service pairs without importing or starting their implementation."""
+    return {p.stem: p for p in sorted((ROOT / 'services').glob('*.py'))
+            if p.with_suffix('.ipynb').is_file()}
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    flags = []
+    while argv:
+        if argv[0] in ('--debug', '--quiet', '--no-color') or argv[0].startswith('--command-timeout='):
+            flags.append(argv.pop(0))
+        elif argv[0] == '--command-timeout':
+            flags.append(argv.pop(0))
+            if not argv:
+                print('--command-timeout 需要秒数', file=sys.stderr)
+                return 2
+            flags.append(argv.pop(0))
+        else:
+            break
+    if len(argv) > 1 and argv[0] == 'help':
+        argv = [*argv[1:], '--help']
+    available = services()
+    if not argv or argv[0] in ('-h', '--help', 'help'):
+        print('用法: colabllm <运行时> <命令> [参数...]\n'
+              '      colabllm <全局配置命令> [参数...]\n'
+              '\n'
+              '运行时: ' + ', '.join(available) + '\n'
+              '全局命令: ' + ', '.join((*GLOBAL_COMMANDS, *UTILITY_COMMANDS)) + '\n\n'
+              '示例:\n'
+              '  colabllm unlimited-ocr up\n'
+              '  colabllm unlimited-ocr ocr ./documents -O ./results\n'
+              '  colabllm qwen3-tts up -i 2\n'
+              '  colabllm tunnel-config\n\n'
+              '全局选项: --debug、--quiet、--no-color、--command-timeout SECONDS\n'
+              'colabllm services 列出运行时；<运行时> --help 查看原有命令和参数。')
+        return 0
+    if argv == ['--version']:
+        from importlib.metadata import version
+        print('colabllm ' + version('colabllm'))
+        return 0
+    command, *remaining = argv
+    if command in ('services', '--list'):
+        if remaining:
+            print('用法: colabllm services', file=sys.stderr)
+            return 2
+        print('\n'.join(available))
+        return 0
+    if command in available:
+        script = available[command]
+    elif command in (*UTILITY_COMMANDS, '_complete'):
+        script = ROOT / 'utility.py'
+        remaining = [command, *remaining]
+    elif command in GLOBAL_COMMANDS:
+        script = ROOT / 'control.py'
+        remaining = [command, *remaining]
+    else:
+        print(f'未知运行时或命令: {command}\n使用 colabllm --help 查看可用命令。', file=sys.stderr)
+        return 2
+    # Replace this process: preserve signals, exit codes and the caller's cwd/local file paths.
+    # Keep the actual service script as argv[0], since its detached runner uses that path.
+    os.execv(sys.executable, [sys.executable, str(script), *flags, *remaining])
+
+
+if __name__ == '__main__':
+    sys.exit(main())

colabllm/control.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Project-wide configuration shared by every Colab runtime service."""
+import argparse
+import sys
+import json
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'lib'))
+import colabsvc
+from colabsvc import cmd_tunnel_config, validate_domain
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description='本项目所有运行时共享的全局配置')
+    commands = parser.add_subparsers(dest='command', required=True)
+    tunnel = commands.add_parser('tunnel-config', help='查看、设置或清除项目全局主域名')
+    settings = tunnel.add_mutually_exclusive_group()
+    settings.add_argument('--base-domain', metavar='DOMAIN', type=validate_domain,
+                          help='所有服务共用的主域名，例如 example.com')
+    settings.add_argument('--clear', action='store_true', help='清除全局主域名，默认使用动态 URL')
+    frp=commands.add_parser('frp-config',help='配置并通过 SSH 安装 FRP 服务端；无参数时查看配置')
+    frp.add_argument('--server-ip',help='FRP 服务器公网 IPv4/IPv6 地址')
+    frp.add_argument('--ssh',help='SSH 目标，例如 root@frpip 或 ~/.ssh/config 中的别名')
+    frp.add_argument('--base-domain',type=validate_domain,help='项目全局主域名，DNS 由 cf CLI 管理')
+    frp.add_argument('--server-port',type=int,help='FRP 服务端端口，默认 7000')
+    frp.add_argument('--disable',action='store_true',help='关闭全局 FRP，之后启动恢复使用 Cloudflare')
+    commands.add_parser('frp-status',help='通过 SSH 检查 FRP/Caddy 服务和已分配路由')
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command=='tunnel-config':
+        cmd_tunnel_config(args)
+    elif args.command=='frp-config':
+        from frp_backend import configure
+        if args.disable and any(getattr(args,k) is not None for k in ('server_ip','ssh','base_domain','server_port')):
+            parser.error('--disable 不能与服务器配置参数同时使用')
+        result=configure(args,colabsvc.STATE_ROOT)
+        print(json.dumps(result,ensure_ascii=False,indent=2))
+    else:
+        from frp_backend import remote
+        config=colabsvc.load_tunnel_config().get('frp')
+        if not config:
+            raise ValueError('尚未配置 FRP 服务端')
+        print(json.dumps(remote(config,{'action':'status'}),ensure_ascii=False,indent=2))
+
+
+if __name__ == '__main__':
+    from cli_support import run_cli
+    run_cli(main)

colabllm/lib/avatar_sampling.py

@@ -0,0 +1,28 @@
+"""Validated sampling controls shared by the Avatar CLI and GPU worker."""
+import math
+
+
+def sampling_settings(mode='distilled', steps=None, text_cfg=None, audio_cfg=None):
+    if mode not in ('distilled', 'standard'):
+        raise ValueError('sampling_mode 必须是 distilled 或 standard')
+    defaults = (8, 1.0, 1.0) if mode == 'distilled' else (50, 4.0, 3.0)
+    steps = defaults[0] if steps is None else steps
+    text_cfg = defaults[1] if text_cfg is None else text_cfg
+    audio_cfg = defaults[2] if audio_cfg is None else audio_cfg
+    if isinstance(steps, bool) or not isinstance(steps, (int, float)) or not math.isfinite(steps) or int(steps) != steps or not 8 <= steps <= 100:
+        raise ValueError('steps 必须是 8–100 的整数')
+    for name, value in (('text_guidance_scale', text_cfg), ('audio_guidance_scale', audio_cfg)):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or not 1 <= value <= 10:
+            raise ValueError(name + ' 必须是 1–10 的有限数值')
+    if mode == 'distilled' and (steps, text_cfg, audio_cfg) != defaults:
+        raise ValueError('8 步蒸馏模式固定 steps=8、text/audio CFG=1；调节 CFG 请使用 standard 模式')
+    return dict(sampling_mode=mode, steps=int(steps), text_guidance_scale=float(text_cfg),
+                audio_guidance_scale=float(audio_cfg), use_distill=mode == 'distilled')
+
+
+def apply_sampling_mode(pipe, settings):
+    """Called under the worker lock, before generation or checkpoint resume."""
+    if settings['use_distill']:
+        pipe.dit.enable_loras(['dmd'])
+    else:
+        pipe.dit.disable_all_loras()

colabllm/lib/cli_support.py

@@ -0,0 +1,158 @@
+"""Shared CLI errors, diagnostic output and authenticated HTTP transport."""
+import http.client
+import math
+import time
+import os
+import subprocess
+import sys
+import traceback
+import urllib.error
+import urllib.parse
+import urllib.request
+
+QUIET = False
+NO_COLOR = False
+
+
+class CliError(RuntimeError):
+    def __init__(self, message, code=1):
+        super().__init__(message)
+        self.code = code
+
+
+class UsageError(ValueError):
+    code = 2
+
+
+def diagnostic(message, color=None):
+    if QUIET:
+        return
+    if color and not NO_COLOR and not os.environ.get('NO_COLOR') and sys.stderr.isatty():
+        message = f'\033[{color}m{message}\033[0m'
+    print(message, file=sys.stderr, flush=True)
+
+
+def nonnegative_seconds(value):
+    seconds = float(value)
+    if not math.isfinite(seconds) or seconds < 0:
+        raise ValueError('秒数必须是有限的非负数')
+    return seconds
+
+
+def positive_seconds(value):
+    seconds = nonnegative_seconds(value)
+    if seconds == 0:
+        raise ValueError('秒数必须大于 0')
+    return seconds
+
+
+def command_timeout(default=300):
+    value = os.environ.get('COLABLLM_COMMAND_TIMEOUT')
+    try:
+        return positive_seconds(value) if value else default
+    except ValueError:
+        raise UsageError('COLABLLM_COMMAND_TIMEOUT 必须是大于 0 的有限秒数') from None
+
+
+class Deadline:
+    def __init__(self, timeout=0, message='等待超时；后台任务继续运行，可稍后查询'):
+        timeout = nonnegative_seconds(timeout)
+        self.end = time.monotonic() + timeout if timeout else None
+        self.message = message
+
+    def remaining(self, cap=None):
+        if self.end is None:
+            return cap
+        remaining = self.end - time.monotonic()
+        if remaining <= 0:
+            raise CliError(self.message, 124)
+        return min(remaining, cap) if cap is not None else remaining
+
+    def sleep(self, seconds):
+        time.sleep(self.remaining(seconds))
+
+
+def origin(url):
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme not in ('http', 'https') or not parsed.hostname or parsed.username or parsed.password:
+        raise CliError('服务 URL 必须是无内嵌账号密码的 HTTP(S) 地址')
+    return (parsed.scheme.lower(), parsed.hostname.lower(), parsed.port or (443 if parsed.scheme == 'https' else 80))
+
+
+def resolve_endpoint(state, url=None, token=None, *, url_env=None, token_env=None):
+    selected = (url or (os.environ.get(url_env) if url_env else None) or state.get('url') or '').rstrip('/')
+    explicit = (token or (os.environ.get(token_env) if token_env else None) or '').strip()
+    if not selected:
+        raise CliError('缺少服务地址：先启动服务，或显式提供 --url 和 API Token')
+    selected_origin = origin(selected)
+    if explicit:
+        return selected, explicit
+    saved_url, saved_token = state.get('url'), state.get('api_token')
+    if not saved_url or not saved_token or origin(saved_url) != selected_origin:
+        raise CliError('服务来源已改变或没有对应凭据；请显式提供 API Token 参数或对应环境变量')
+    return selected, saved_token
+
+
+class SameOriginRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if req.has_header('Authorization') and origin(req.full_url) != origin(newurl):
+            raise CliError('拒绝向其他站点转发认证信息；请检查服务 URL 或重定向配置')
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def safe_urlopen(request, *args, **kwargs):
+    return urllib.request.build_opener(SameOriginRedirect()).open(request, *args, **kwargs)
+
+
+def configure_output():
+    global QUIET, NO_COLOR
+    args = []
+    literal = False
+    debug = False
+    argv = iter(sys.argv[1:])
+    for arg in argv:
+        if arg == '--':
+            literal = True
+        if not literal and arg in ('--debug', '--quiet', '--no-color'):
+            debug |= arg == '--debug'
+            QUIET |= arg == '--quiet'
+            NO_COLOR |= arg == '--no-color'
+        elif not literal and (arg == '--command-timeout' or arg.startswith('--command-timeout=')):
+            value = next(argv, None) if arg == '--command-timeout' else arg.split('=', 1)[1]
+            try:
+                os.environ['COLABLLM_COMMAND_TIMEOUT'] = str(positive_seconds(value))
+            except (ValueError, TypeError):
+                raise UsageError('--command-timeout 需要大于 0 的有限秒数') from None
+        else:
+            args.append(arg)
+    sys.argv[1:] = args
+    return debug
+
+
+def run_cli(action):
+    """Handle expected user-facing failures consistently, including early parsing."""
+    debug = False
+    try:
+        debug = configure_output()
+        code = action()
+        if isinstance(code, int) and code:
+            raise SystemExit(code)
+    except BrokenPipeError:
+        # Avoid a second flush failure at interpreter shutdown.
+        with open(os.devnull, 'w') as sink:
+            os.dup2(sink.fileno(), sys.stdout.fileno())
+        raise SystemExit(141) from None
+    except KeyboardInterrupt:
+        diagnostic('已中断当前命令；可用 status/job 查看服务或任务状态。')
+        raise SystemExit(130) from None
+    except (OSError, ValueError, RuntimeError, http.client.HTTPException, subprocess.SubprocessError) as error:
+        if debug:
+            traceback.print_exc()
+        else:
+            message = str(error)
+            if isinstance(error, urllib.error.HTTPError):
+                message = f'HTTP {error.code}: {error.reason}'
+            # Errors remain visible in quiet mode.
+            print(f'colabllm: {message}', file=sys.stderr)
+        code = error.code if isinstance(error, (CliError, UsageError)) else (124 if isinstance(error, (TimeoutError, subprocess.TimeoutExpired)) else 1)
+        raise SystemExit(code) from None