Add draft for Centralized Logging and Structured Exception Handling

[priyan17singh]

Related to #516

---

Status

This is a draft PR for early feedback from maintainers before finalizing implementation.

---

Summary

This PR introduces a centralized logging system and a structured exception wrapper to replace scattered print() usage and raw exceptions across the codebase.

The goal is to:

• Improve observability and debugging
• Provide consistent logging across modules
• Surface actionable error messages with precise file and line information

The implementation relies only on Python’s standard library.

---

Key Features

1. Centralized Logging (logging_config.py)

• Introduces a root logger: "perceptionmetrics"
• Console logging enabled by default
• Optional rotating file logging via: add_file_handler("logs/run.log")
• Global log level control: set_level(logging.DEBUG)
• Child loggers inherit configuration automatically
• Safe initialization (no duplicate handlers)

---

2. Structured Exception Wrapper (exception.py)

• Adds PerceptionMetricsException
• Wraps original exceptions and extracts:
  • File name
  • Line number (from the last traceback frame)
• Standardized error format:
  Error in [file.py] at line [42]: original error message

---

Example Usage

Logging

from perceptionmetrics.utils.logging_config import get_logger

_logger = get_logger(__name__)

_logger.info("Loaded %d samples", n)

---

Enable File Logging (Optional)

from perceptionmetrics.utils.logging_config import add_file_handler

add_file_handler("logs/run.log")

---

Exception Handling

from perceptionmetrics.utils.exception import PerceptionMetricsException

try:
model = torch.jit.load(path)
except Exception as e:
raise PerceptionMetricsException(e) from e

---

Changes Made

• Added perceptionmetrics/utils/logging_config.py
• Added perceptionmetrics/utils/exception.py
• Updated models/__init__.py to use centralized logging and structured exceptions.
• Replaced print() statements with logger usage in modified modules.

---

Testing

• Verified console logging output across modules.
• Verified file logging via add_file_handler("logs/run.log")
• Tested exception wrapping with real errors to confirm file/line accuracy.

---

[priyan17singh]

Hi @dpascualhe, opening this as a draft PR as requested.

The core get_logger() helper and one example usage in models/__init__.py are in place. Before applying this pattern across the rest of the codebase, I’d like to confirm a few key design decisions:

1. File logging — exposure
   Currently, file logging is opt-in via add_file_handler("logs/run.log").
   Would you prefer this to remain a programmatic API, or be exposed via CLI flags (e.g., --log-file)?

2. Default log level
   Currently set to INFO, which may be noisy when the library is imported externally.
   Would WARNING be a better default?

3. CLI output vs logging (cli/batch.py)
   Some print() calls are used for clean, user-facing summaries.
   Should these remain as print(), or be routed through the logger for consistency?

4. Scope of this PR (Streamlit / GUI scope )
   Should logging changes be limited to the core library + CLI, or also include Streamlit/UI files?

Happy to proceed with the full migration across the codebase once I have your guidance.

Thanks!