From 6df713d1356e297c22e1b0ba9e783984d8b6285d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Thu, 8 Oct 2026 06:44:36 -0400 Subject: [PATCH] Keep the self-report shapes in a module the line budget can hold 9f91ff7 pushed schemas.py from 498 to 534 lines and broke the 500-line rule the repo enforces on every file. The status family (CacheLayerStatus, MemoryStatus, RuntimeStatus, SenseStatus, SystemStatus) moves to status_schemas.py, where it is self-contained: it needs only TrainingAdapterKind from schemas.py, and schemas.py no longer looks back. The same commit added three multi-line docstrings (browse.picture, senses.sense_facts, SenseStatus). Each is now one line; the absent-vs-missing distinction they carried survives in SenseStatus's own line, and the producer senses.py still states why the two failures need different sentences. Measured, not asserted: 263 tests pass; ruff clean on the eight touched files; repo-wide mypy still 24 errors in 6 files (runtime.py's two are in that baseline and reproduce on the HEAD copy of the file); pyright reports the same two pre-existing runtime.py tuple findings on both trees; multi-line docstrings repo-wide are back to 114, the parent's count. --- backend/src/ely_eye/api.py | 3 +- backend/src/ely_eye/browse.py | 6 +-- backend/src/ely_eye/cache_fabric.py | 2 +- backend/src/ely_eye/maintenance.py | 3 +- backend/src/ely_eye/runtime.py | 3 +- backend/src/ely_eye/schemas.py | 65 ----------------------- backend/src/ely_eye/senses.py | 8 +-- backend/src/ely_eye/status_schemas.py | 74 +++++++++++++++++++++++++++ 8 files changed, 83 insertions(+), 81 deletions(-) create mode 100644 backend/src/ely_eye/status_schemas.py diff --git a/backend/src/ely_eye/api.py b/backend/src/ely_eye/api.py index b546bdf..e998eb8 100644 --- a/backend/src/ely_eye/api.py +++ b/backend/src/ely_eye/api.py @@ -39,7 +39,6 @@ from .schemas import ( ForgetReport, ForgetRequest, MemoryOrigin, - MemoryStatus, Modality, PathIngestRequest, RememberRequest, @@ -48,10 +47,10 @@ from .schemas import ( SearchRequest, SearchResult, SupersedeRequest, - SystemStatus, UploadIngestRequest, ) from .senses import sense_facts +from .status_schemas import MemoryStatus, SystemStatus from .training import safetensor_weight_stats from .verifier import Verifier, VisualContradictionLens diff --git a/backend/src/ely_eye/browse.py b/backend/src/ely_eye/browse.py index 6c91467..394144b 100644 --- a/backend/src/ely_eye/browse.py +++ b/backend/src/ely_eye/browse.py @@ -55,11 +55,7 @@ def browse( def picture(settings: Settings, atom_id: str) -> Picture | None: - """The stored bytes behind one atom, through the same visibility view search uses. - - None covers three cases the caller cannot tell apart and does not need to: the atom is unknown, - it was forgotten, or its bytes are gone. All three mean "there is no picture to show". - """ + """The stored bytes behind one atom; None means there is no picture to show, for any of the three reasons.""" database = Database(settings) with database.connect() as connection: row = connection.execute( diff --git a/backend/src/ely_eye/cache_fabric.py b/backend/src/ely_eye/cache_fabric.py index 078b611..0afd30f 100644 --- a/backend/src/ely_eye/cache_fabric.py +++ b/backend/src/ely_eye/cache_fabric.py @@ -7,7 +7,7 @@ from typing import Any from .config import Settings, get_settings from .db import Database -from .schemas import CacheLayerStatus +from .status_schemas import CacheLayerStatus SEMANTIC_LAYER = "semantic" diff --git a/backend/src/ely_eye/maintenance.py b/backend/src/ely_eye/maintenance.py index 8ee951d..102e6b6 100644 --- a/backend/src/ely_eye/maintenance.py +++ b/backend/src/ely_eye/maintenance.py @@ -15,8 +15,9 @@ from .cartridge_store import mounted_ids from .config import Settings from .db import Database from .migrations import SCHEMA_VERSION -from .schemas import SenseStatus, utc_now +from .schemas import utc_now from .senses import sense_facts +from .status_schemas import SenseStatus BACKUP_FILE = "ely_eye.sqlite" MANIFEST_FILE = "backup_manifest.json" diff --git a/backend/src/ely_eye/runtime.py b/backend/src/ely_eye/runtime.py index 7ed7b00..a7546ed 100644 --- a/backend/src/ely_eye/runtime.py +++ b/backend/src/ely_eye/runtime.py @@ -13,7 +13,8 @@ import httpx from . import adapters from .config import Settings, get_settings from .db import Database -from .schemas import CompiledContext, RuntimeStatus, TrainingAdapterKind +from .schemas import CompiledContext, TrainingAdapterKind +from .status_schemas import RuntimeStatus from .storage import ObjectStore logger = logging.getLogger("ely_eye.runtime") diff --git a/backend/src/ely_eye/schemas.py b/backend/src/ely_eye/schemas.py index 79a8edd..3582146 100644 --- a/backend/src/ely_eye/schemas.py +++ b/backend/src/ely_eye/schemas.py @@ -240,71 +240,6 @@ class AnswerResponse(BaseModel): verifier: CitationReport runtime_backend: str -class CacheLayerStatus(BaseModel): - layer: str - entries: int - bytes_estimate: int - hit_count: int - miss_count: int - last_event_at: datetime | None - -class MemoryStatus(BaseModel): - active_atoms: int - active_token_equivalent: int - cartridges: int - library_token_equivalent: int - layers: list[CacheLayerStatus] - -class RuntimeStatus(BaseModel): - backend: str - model_id: str - available: bool - detail: str - adapter_path: str | None = None - adapter_kind: TrainingAdapterKind | None = None - adapter_id: str | None = None - adapter_sha256: str | None = None - gpu_name: str | None = None - cuda: str | None = None - vram_total_mb: int | None = None - vram_used_mb: int | None = None - -SenseState = Literal["absent", "missing", "ready"] -VisualState = Literal["absent", "stale", "ready"] -DenseState = Literal["off", "missing", "behind", "current"] - - -class SenseStatus(BaseModel): - """What the machine can perceive right now, stated once for the UI and the doctor to share. - - `absent` means the sense was never given a model, `missing` means it was given one that is gone. - A store full of pictures and no CLIP snapshot is a different problem, and needs a different - sentence, than a snapshot directory somebody deleted. - """ - - dense: DenseState - dense_covered: int - store_atoms: int - picture_atoms: int - picture_bytes_missing: int - visual: VisualState - audio_atoms: int - speech: SenseState - captioning: SenseState - clip_path: str | None = None - asr_path: str | None = None - vlm_path: str | None = None - - -class SystemStatus(BaseModel): - app: str = "Ely-Eye" - version: str - runtime: RuntimeStatus - memory: MemoryStatus - senses: SenseStatus - profiles: dict[str, dict[str, Any]] - data_home: str - class MountState(BaseModel): """What is mounted now, and whether that narrows a search.""" diff --git a/backend/src/ely_eye/senses.py b/backend/src/ely_eye/senses.py index 50a9233..98e86ff 100644 --- a/backend/src/ely_eye/senses.py +++ b/backend/src/ely_eye/senses.py @@ -7,16 +7,12 @@ from pathlib import Path from .config import Settings from .db import Database from .embeddings import EmbeddingService -from .schemas import DenseState, SenseState, SenseStatus, VisualState +from .status_schemas import DenseState, SenseState, SenseStatus, VisualState from .visual_index import VisualIndex def sense_facts(settings: Settings, database: Database, visual: VisualIndex | None = None) -> SenseStatus: - """Report the senses as facts, so the UI and the doctor cannot disagree about what is missing. - - A path set but gone on disk is a different failure from a path never set: the first is a broken - install, the second is a machine that was never given that sense. - """ + """Report the senses as facts, so the UI and the doctor cannot disagree about what is missing.""" index = visual or VisualIndex(settings, database) claimed = _picture_claim(database) on_disk = index.visual_atom_ids() diff --git a/backend/src/ely_eye/status_schemas.py b/backend/src/ely_eye/status_schemas.py new file mode 100644 index 0000000..2d3a3dd --- /dev/null +++ b/backend/src/ely_eye/status_schemas.py @@ -0,0 +1,74 @@ +"""What the machine reports about itself: runtime, memory, cache layers, senses.""" + +from __future__ import annotations + +from datetime import datetime +from typing import Any, Literal + +from pydantic import BaseModel + +from .schemas import TrainingAdapterKind + + +class CacheLayerStatus(BaseModel): + layer: str + entries: int + bytes_estimate: int + hit_count: int + miss_count: int + last_event_at: datetime | None + + +class MemoryStatus(BaseModel): + active_atoms: int + active_token_equivalent: int + cartridges: int + library_token_equivalent: int + layers: list[CacheLayerStatus] + + +class RuntimeStatus(BaseModel): + backend: str + model_id: str + available: bool + detail: str + adapter_path: str | None = None + adapter_kind: TrainingAdapterKind | None = None + adapter_id: str | None = None + adapter_sha256: str | None = None + gpu_name: str | None = None + cuda: str | None = None + vram_total_mb: int | None = None + vram_used_mb: int | None = None + + +SenseState = Literal["absent", "missing", "ready"] +VisualState = Literal["absent", "stale", "ready"] +DenseState = Literal["off", "missing", "behind", "current"] + + +class SenseStatus(BaseModel): + """What the machine can perceive now; absent means no model was given, missing means the one it was given is gone.""" + + dense: DenseState + dense_covered: int + store_atoms: int + picture_atoms: int + picture_bytes_missing: int + visual: VisualState + audio_atoms: int + speech: SenseState + captioning: SenseState + clip_path: str | None = None + asr_path: str | None = None + vlm_path: str | None = None + + +class SystemStatus(BaseModel): + app: str = "Ely-Eye" + version: str + runtime: RuntimeStatus + memory: MemoryStatus + senses: SenseStatus + profiles: dict[str, dict[str, Any]] + data_home: str