Coverage for src/lilbee/core/health_warnings.py: 100%

1"""Degradations a running server can report to a client. 

2 

3Each subsystem owns the state behind its own warnings and exposes them; the 

4health handler aggregates. Nothing here holds state, so there is no registry to 

5keep in sync with the components that produce it. 

6""" 

7 

8from __future__ import annotations 

9 

10from enum import StrEnum 

11 

12from pydantic import BaseModel 

13 

14 

15class WarningCode(StrEnum): 

16 """Stable identifier for a degradation, so a client can branch on it.""" 

17 

18 FTS_UNAVAILABLE = "fts_unavailable" 

19 """Keyword search failed and queries fall back to vector-only recall.""" 

20 EMBEDDING_PREFIX_MISMATCH = "embedding_prefix_mismatch" 

21 """Queries are prefixed but stored documents are not; retrieval is degraded.""" 

22 INDEX_EMBEDDING_MISMATCH = "index_embedding_mismatch" 

23 """The index was built with another embedding model; search refuses until they agree.""" 

24 SCALAR_INDEX_UNAVAILABLE = "scalar_index_unavailable" 

25 """A scalar index is registered but its files are gone; filtered search is degraded.""" 

26 EMBED_WINDOW_BELOW_CHUNK = "embed_window_below_chunk" 

27 """The embedder's window is below the chunk budget; chunks are sized in its tokens.""" 

28 PLACEMENT_DIVERGED = "placement_diverged" 

29 """The engine allocated materially more or less GPU memory than planned.""" 

30 

31 

32class HealthWarning(BaseModel): 

33 """One active degradation, with the remedy the user can act on.""" 

34 

35 code: WarningCode 

36 message: str 

37 """User-facing description of what is degraded.""" 

38 remedy: str | None = None 

39 """The action that clears it, when there is one."""