Coverage for src / lilbee / __init__.py: 100%

1"""lilbee: local knowledge base.""" 

2 

3from __future__ import annotations 

4 

5import os 

6import threading 

7 

8# Disable huggingface_hub's xet transfer layer before any HF submodule loads. 

9# huggingface_hub.constants reads HF_HUB_DISABLE_XET at import time, so this 

10# must run before the first `import huggingface_hub` anywhere in the process. 

11# Workaround for HF issue #4058: xet-core reports progress in 3-4 coarse jumps 

12# instead of continuously, making download bars appear stuck on large files. 

13# Forcing the HTTP path restores smooth per-chunk tqdm updates. Users can still 

14# opt back into xet by setting HF_HUB_DISABLE_XET=0 in their environment. 

15os.environ.setdefault("HF_HUB_DISABLE_XET", "1") 

16 

17# Suppress HF-default tqdm bars (metadata probes, snapshot summaries) that 

18# leak cursor escapes into the TUI. Our custom tqdm_class is NOT a subclass 

19# of huggingface_hub.utils.tqdm, so huggingface_hub's `_create_progress_bar` 

20# instantiates it directly without honoring this flag. Download callbacks 

21# continue to fire. See lilbee/catalog/download_progress.py::_CallbackProgressBar. 

22os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1") 

23 

24 

25def _install_thread_only_tqdm_lock() -> None: 

26 """Pin ``tqdm.std.tqdm._lock`` to a threading RLock. 

27 

28 Bypasses tqdm's lazy multiprocessing-lock init, which tries to 

29 fork_exec the MP resource tracker with ``sys.stderr.fileno() == -1`` 

30 under Textual and crashes with ``bad value(s) in fds_to_keep``. 

31 Matches huggingface_hub PR #4065 but applied at the base class so 

32 every tqdm instance in the process inherits the lock via MRO. 

33 """ 

34 try: 

35 from tqdm.std import tqdm as _tqdm_base 

36 except ImportError: 

37 return 

38 if getattr(_tqdm_base, "_lock", None) is None: 

39 _tqdm_base._lock = threading.RLock() 

40 

41 

42def _prestart_mp_resource_tracker() -> None: 

43 """Start the multiprocessing resource tracker before Textual swaps stderr. 

44 

45 The tracker launches lazily on the first semaphore creation, which in 

46 the TUI is a worker's ``Value(lock=True)`` abort flag, spawned after 

47 Textual has replaced ``sys.stderr`` with a stream whose ``fileno()`` 

48 returns -1. The tracker's launch passes that -1 into 

49 ``_posixsubprocess.fork_exec`` and crashes with ``bad value(s) in 

50 fds_to_keep``. Launching it here, at import time with a real stderr, 

51 caches a valid tracker fd that every later ``Process.start()`` reuses. 

52 

53 Runs in frozen builds too (Nuitka onefile): the tracker re-executes 

54 ``sys.executable`` with ``-c "from multiprocessing.resource_tracker 

55 import main;main(N)"``, which ``__main__._dispatch_frozen_child`` 

56 intercepts and execs before typer sees it. No-op on Windows, which 

57 does not use ``_posixsubprocess``. 

58 """ 

59 import sys as _sys 

60 

61 if _sys.platform == "win32": 

62 return 

63 try: 

64 from multiprocessing import resource_tracker 

65 

66 resource_tracker.ensure_running() 

67 except (OSError, RuntimeError, ValueError, ImportError): 

68 # Best-effort: if the tracker already crashed or cannot be started 

69 # in the current env, leave the state alone. The worker's own 

70 # spawn will surface a real error at call time. 

71 pass 

72 

73 

74_install_thread_only_tqdm_lock() 

75_prestart_mp_resource_tracker() 

76 

77 

78def _shrink_hf_download_chunk_size() -> None: 

79 """Shrink huggingface_hub's 10MB download chunk to 200KB. 

80 

81 Default DOWNLOAD_CHUNK_SIZE=10MB means the tqdm callback only fires 

82 every ~7 seconds on a 1.5MB/s connection, making downloads look stuck 

83 between jumps. 200KB chunks drive the callback several times per 

84 second at typical home-internet rates, so the UI renders smooth 

85 real-time progress. Monkey-patched here because HF exposes no env 

86 override. Runtime cost: tqdm call overhead is negligible (~µs) and 

87 HTTP iter_bytes accumulates into chunks of this size, so smaller 

88 chunks do not produce more network round-trips. 

89 """ 

90 try: 

91 from huggingface_hub import constants as _hf_constants 

92 

93 _hf_constants.DOWNLOAD_CHUNK_SIZE = 200 * 1024 

94 except ImportError: 

95 pass # huggingface_hub may be absent in stripped-down environments 

96 

97 

98_shrink_hf_download_chunk_size() 

99 

100 

101# HF and LiteLLM log filters live next to their respective implementations 

102# (catalog/hf_client.py and providers/litellm_sdk.py). They install themselves 

103# on module import; this package's __init__.py stays free of HF/LiteLLM 

104# implementation detail. 

105 

106 

107# Must follow HF environment / constants setup above. 

108from typing import TYPE_CHECKING # noqa: E402 

109 

110if TYPE_CHECKING: 

111 from lilbee.api import Lilbee 

112 

113__all__ = ["Lilbee"] 

114 

115 

116def __getattr__(name: str) -> object: 

117 if name == "Lilbee": 

118 from lilbee.api import Lilbee 

119 

120 return Lilbee 

121 raise AttributeError(f"module {__name__!r} has no attribute {name!r}")