cognitive_mapping_probe/utils.py

import os
import sys

# --- Centralized Debugging Control ---
# To enable, set the environment variable: `export CMP_DEBUG=1`
DEBUG_ENABLED = os.environ.get("CMP_DEBUG", "0") == "1"

def dbg(*args, **kwargs):
    """
    A controlled debug print function. Only prints if DEBUG_ENABLED is True.
    Ensures that debug output does not clutter production runs or HF Spaces logs
    unless explicitly requested. Flushes output to ensure it appears in order.
    """
    if DEBUG_ENABLED:
        print("[DEBUG]", *args, **kwargs, file=sys.stderr, flush=True)