semantic update

backend/src/core/logger.py

@@ -28,6 +28,7 @@ class BeliefFormatter(logging.Formatter):
     # @POST: Returns formatted string.
     # @PARAM: record (logging.LogRecord) - The log record to format.
     # @RETURN: str - The formatted log message.
+    # @SEMANTICS: logging, formatter, context
     def format(self, record):
         anchor_id = getattr(_belief_state, 'anchor_id', None)
         if anchor_id:
@@ -54,6 +55,7 @@ class LogEntry(BaseModel):
 # @PARAM: message (str) - Optional entry message.
 # @PRE: anchor_id must be provided.
 # @POST: Thread-local belief state is updated and entry/exit logs are generated.
+# @SEMANTICS: logging, context, belief_state
 @contextmanager
 def belief_scope(anchor_id: str, message: str = ""):
     # Log Entry if enabled
@@ -88,6 +90,7 @@ def belief_scope(anchor_id: str, message: str = ""):
 # @PRE: config is a valid LoggingConfig instance.
 # @POST: Logger level, handlers, and belief state flag are updated.
 # @PARAM: config (LoggingConfig) - The logging configuration.
+# @SEMANTICS: logging, configuration, initialization
 def configure_logger(config):
     global _enable_belief_state
     _enable_belief_state = config.enable_belief_state
@@ -140,6 +143,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: capacity is an integer.
     # @POST: Instance initialized with empty deque.
     # @PARAM: capacity (int) - Maximum number of logs to keep in memory.
+    # @SEMANTICS: logging, initialization, buffer
     def __init__(self, capacity: int = 1000):
         super().__init__()
         self.log_buffer: deque[LogEntry] = deque(maxlen=capacity)
@@ -152,6 +156,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: record is a logging.LogRecord.
     # @POST: Log is added to the log_buffer.
     # @PARAM: record (logging.LogRecord) - The log record to emit.
+    # @SEMANTICS: logging, handler, buffer
     def emit(self, record: logging.LogRecord):
         try:
             log_entry = LogEntry(
@@ -179,6 +184,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: None.
     # @POST: Returns list of LogEntry objects.
     # @RETURN: List[LogEntry] - List of buffered log entries.
+    # @SEMANTICS: logging, buffer, retrieval
     def get_recent_logs(self) -> List[LogEntry]:
         """
         Returns a list of recent log entries from the buffer.
@@ -196,12 +202,18 @@ logger = logging.getLogger("superset_tools_app")
 # [DEF:believed:Function]
 # @PURPOSE: A decorator that wraps a function in a belief scope.
 # @PARAM: anchor_id (str) - The identifier for the semantic block.
+# @PRE: anchor_id must be a string.
+# @POST: Returns a decorator function.
 def believed(anchor_id: str):
     # [DEF:decorator:Function]
     # @PURPOSE: Internal decorator for belief scope.
+    # @PRE: func must be a callable.
+    # @POST: Returns the wrapped function.
     def decorator(func):
         # [DEF:wrapper:Function]
         # @PURPOSE: Internal wrapper that enters belief scope.
+        # @PRE: None.
+        # @POST: Executes the function within a belief scope.
         def wrapper(*args, **kwargs):
             with belief_scope(anchor_id):
                 return func(*args, **kwargs)