feat(logging): draft implementation of centralized logging and exception handling.

[priyan17singh]

Add Centralized Logging and Structured Exception Handling

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]

Had some unexpected changes in the files.