docs(logging): Update documentation for session-based logging and management

log_registry.py

@@ -4,13 +4,26 @@ from datetime import datetime
 import os
 
 class LogRegistry:
+    """
+    Manages a persistent registry of session logs using a TOML file.
+    Tracks session paths, start times, whitelisting status, and metadata.
+    """
     def __init__(self, registry_path):
+        """
+        Initializes the LogRegistry with a path to the registry file.
+        
+        Args:
+            registry_path (str): The file path to the TOML registry.
+        """
         self.registry_path = registry_path
         self.data = {}
         self.load_registry()
 
     def load_registry(self):
-        """Loads the registry data from the TOML file."""
+        """
+        Loads the registry data from the TOML file into memory.
+        Handles date/time conversions from TOML-native formats to strings for consistency.
+        """
         if os.path.exists(self.registry_path):
             try:
                 with open(self.registry_path, 'rb') as f:
@@ -35,7 +48,10 @@ class LogRegistry:
             self.data = {}
 
     def save_registry(self):
-        """Saves the current registry data to the TOML file."""
+        """
+        Serializes and saves the current registry data to the TOML file.
+        Converts internal datetime objects to ISO format strings for compatibility.
+        """
         try:
             # Convert datetime objects to ISO format strings for TOML serialization
             data_to_save = {}
@@ -66,7 +82,14 @@ class LogRegistry:
             print(f"Error saving registry to {self.registry_path}: {e}")
 
     def register_session(self, session_id, path, start_time):
-        """Registers a new session."""
+        """
+        Registers a new session in the registry.
+
+        Args:
+            session_id (str): Unique identifier for the session.
+            path (str): File path to the session's log directory.
+            start_time (datetime|str): The timestamp when the session started.
+        """
         if session_id in self.data:
             print(f"Warning: Session ID '{session_id}' already exists. Overwriting.")
 
@@ -85,7 +108,17 @@ class LogRegistry:
         self.save_registry()
 
     def update_session_metadata(self, session_id, message_count, errors, size_kb, whitelisted, reason):
-        """Updates metadata for an existing session."""
+        """
+        Updates metadata fields for an existing session.
+
+        Args:
+            session_id (str): Unique identifier for the session.
+            message_count (int): Total number of messages in the session.
+            errors (int): Number of errors identified in logs.
+            size_kb (int): Total size of the session logs in kilobytes.
+            whitelisted (bool): Whether the session should be protected from pruning.
+            reason (str): Explanation for the current whitelisting status.
+        """
         if session_id not in self.data:
             print(f"Error: Session ID '{session_id}' not found for metadata update.")
             return
@@ -109,7 +142,15 @@ class LogRegistry:
         self.save_registry() # Save after update
 
     def is_session_whitelisted(self, session_id):
-        """Checks if a session is whitelisted."""
+        """
+        Checks if a specific session is marked as whitelisted.
+
+        Args:
+            session_id (str): Unique identifier for the session.
+
+        Returns:
+            bool: True if whitelisted, False otherwise.
+        """
         session_data = self.data.get(session_id)
         if session_data is None:
             return False # Non-existent sessions are not whitelisted
@@ -120,6 +161,11 @@ class LogRegistry:
     def update_auto_whitelist_status(self, session_id: str):
         """
         Analyzes session logs and updates whitelisting status based on heuristics.
+        Sessions are automatically whitelisted if they contain error keywords, 
+        have a high message count, or exceed a size threshold.
+
+        Args:
+            session_id (str): Unique identifier for the session to analyze.
         """
         if session_id not in self.data:
             return
@@ -178,7 +224,16 @@ class LogRegistry:
         )
 
     def get_old_non_whitelisted_sessions(self, cutoff_datetime):
-        """Gets sessions older than cutoff_datetime and not whitelisted."""
+        """
+        Retrieves a list of sessions that are older than a specific cutoff time 
+        and are not marked as whitelisted.
+
+        Args:
+            cutoff_datetime (datetime): The threshold time for identifying old sessions.
+
+        Returns:
+            list: A list of dictionaries containing session details (id, path, start_time).
+        """
         old_sessions = []
         for session_id, session_data in self.data.items():
             # Check if session is older than cutoff and not whitelisted