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 to replace scattered print() usage across the codebase.

The goal is to:

• Improve observability and debugging
• Provide consistent logging across modules

The implementation relies only on Python's standard library.

Update: the original draft also included a custom PerceptionMetricsException wrapper. Per review feedback, this has been removed — the codebase continues to use native Python exceptions.

---

Key Features

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, and non-qualified names (e.g. get_logger("foo")) are normalized under the perceptionmetrics.* hierarchy
• Safe initialization (no duplicate handlers, no duplicate file handlers for the same path)

---

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")

---

Changes Made

• Added perceptionmetrics/utils/logging_config.py
• Updated models/__init__.py to use centralized logging
• Replaced print() statements with logger usage in modified modules
• Added perceptionmetrics/utils/exception.py — removed per review feedback
• Fixed a thread-unsafe flush() override on the rotating file handler
• Fixed get_logger() to correctly enforce the perceptionmetrics.* logger hierarchy
• Formatted all modified files with black

---

Testing

• Verified console logging output across modules
• Verified file logging via add_file_handler("logs/run.log"), including directory auto-creation and duplicate-handler prevention

---

[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!

[dpascualhe]

beyond the requested changes, please make sure to format all your modified files using black

[priyan17singh]

Hi @dpascualhe , thanks for the review — I've pushed updates addressing all three comments:

• Removed exception.py / PerceptionMetricsException; reverted to native Python exceptions.
• Replaced the print() for the resolved log file path with root.info(...).
• Removed the unnecessary console_handler.terminator line.
• Ran black across all modified files.

[priyan17singh]

Open Questions

1. File logging — keep as a programmatic API, or expose via CLI flag (--log-file)?
2. Default log level — keep INFO, or switch to WARNING to reduce noise on external imports?
3. cli/batch.py — keep user-facing print() calls as-is, or route through the logger too?
4. Scope — limit this migration to core + CLI, or also include Streamlit/UI files?

Happy to proceed with the full migration once I have guidance on these. Thanks!