docs

src/log_registry.py

@@ -1,3 +1,42 @@
+"""
+Log Registry - Session metadata persistence for log management.
+
+This module provides the LogRegistry class for tracking session logs
+in a persistent TOML registry file. It supports session registration,
+metadata updates, whitelisting, and age-based pruning queries.
+
+Key Features:
+ - Persistent TOML-based registry (log_registry.toml)
+ - Session registration with path and start time
+ - Automatic whitelisting based on heuristics (errors, message count, size)
+ - Age-based session queries for log pruning
+ - Thread-safe file operations (via atomic TOML writes)
+
+Registry File Format (log_registry.toml):
+ [session_id]
+ path = "logs/sessions/session_id"
+ start_time = "2024-01-15T10:30:00"
+ whitelisted = false
+ [session_id.metadata]
+ message_count = 42
+ errors = 0
+ size_kb = 15
+ reason = "High message count: 42"
+
+Integration:
+ - Used by session_logger.py for session registration
+ - Used by log_pruner.py for age-based cleanup
+ - Called from gui_2.py for log management UI
+
+Thread Safety:
+ - File operations use atomic write (tomli_w.dump)
+ - In-memory data dict is not thread-safe for concurrent access
+
+See Also:
+ - src/session_logger.py for session lifecycle
+ - src/log_pruner.py for automated cleanup
+ - src/paths.py for registry path resolution
+"""
 from __future__ import annotations
 import tomli_w
 import tomllib
@@ -5,6 +44,7 @@ from datetime import datetime
 import os
 from typing import Any
 
+
 class LogRegistry:
  """
     Manages a persistent registry of session logs using a TOML file.