logging_config.py

"""
logging_config.py
------------------------
Shared logging configuration for the Agentic RAG Space.

Every module gets its logger via:
    from logging_config import get_logger
    logger = get_logger(__name__)
"""
import logging
import sys

CONFIGURED = False


def _configure_root_logger() -> None:
  """
  Configure the root logger once, on first get_logger() call.

  Format: "2026-07-16 10:32:01 [INFO] retrieval: best_sim=0.812"
  Gives timestamp, level, module name, and message — everything you
  need to trace an issue back to its source without bracket-tag
  guesswork.
  """
  global CONFIGURED
  if CONFIGURED:
      return

  handler = logging.StreamHandler(sys.stdout)
  handler.setFormatter(
      logging.Formatter(
          fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
          datefmt="%Y-%m-%d %H:%M:%S",
      )
  )

  root = logging.getLogger()
  root.setLevel(logging.INFO)   # DEBUG is available per-module if needed
  root.addHandler(handler)

  CONFIGURED = True


def get_logger(name: str) -> logging.Logger:
  """
  Return a module-scoped logger. Call once per module at the top:

      from logging_config import get_logger
      logger = get_logger(__name__)

  __name__ becomes the module name in every log line (e.g. "retrieval",
  "generation", "vectorstore"), so you always know the source at a glance.
  """
  _configure_root_logger()
  return logging.getLogger(name)