feat: add auto-generated CI documentation pre-commit hook (#2890)

Our CI is entirely undocumented, this commit adds a README.md file with
a table of the current CI and what is does

---------

Signed-off-by: Nathan Weinberg <[email protected]>

Author: nathan-weinberg

.pre-commit-config.yaml

@@ -145,6 +145,24 @@ repos:
         pass_filenames: false
         require_serial: true
         files: ^.github/workflows/.*$
+      - id: check-logger-usage
+        name: Check for proper logger usage (use llama_stack.log instead)
+        entry: bash
+        language: system
+        types: [python]
+        pass_filenames: true
+        args:
+          - -c
+          - |
+            matches=$(grep -EnH '^[^#]*\b(import logging|from logging\b)' "$@" | grep -v '# allow-direct-logging' || true)
+            if [ -n "$matches" ]; then
+              # GitHub Actions annotation format
+              while IFS=: read -r file line_num rest; do
+                echo "::error file=$file,line=$line_num::Do not use 'import logging' or 'from logging import' in $file. Use the custom logger instead: from llama_stack.log import get_logger; logger = get_logger(name=__name__, category=\"core\"). If direct logging is truly needed, add: # allow-direct-logging"
+              done <<< "$matches"
+              exit 1
+            fi
+            exit 0
 
 ci:
     autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

llama_stack/core/build.py

@@ -5,7 +5,6 @@
 # the root directory of this source tree.
 
 import importlib.resources
-import logging
 import sys
 
 from pydantic import BaseModel
@@ -17,10 +16,9 @@
 from llama_stack.core.utils.exec import run_command
 from llama_stack.core.utils.image_types import LlamaStackImageType
 from llama_stack.distributions.template import DistributionTemplate
+from llama_stack.log import get_logger
 from llama_stack.providers.datatypes import Api
 
-log = logging.getLogger(__name__)
-
 # These are the dependencies needed by the distribution server.
 # `llama-stack` is automatically installed by the installation script.
 SERVER_DEPENDENCIES = [
@@ -33,6 +31,8 @@
     "opentelemetry-exporter-otlp-proto-http",
 ]
 
+logger = get_logger(name=__name__, category="core")
+
 
 class ApiInput(BaseModel):
     api: Api
@@ -157,7 +157,7 @@ def build_image(
     return_code = run_command(args)
 
     if return_code != 0:
-        log.error(
+        logger.error(
             f"Failed to build target {image_name} with return code {return_code}",
         )
 

llama_stack/core/configure.py

@@ -3,7 +3,6 @@
 #
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
-import logging
 import textwrap
 from typing import Any
 
@@ -21,9 +20,10 @@
 from llama_stack.core.utils.config_dirs import EXTERNAL_PROVIDERS_DIR
 from llama_stack.core.utils.dynamic import instantiate_class_type
 from llama_stack.core.utils.prompt_for_config import prompt_for_config
+from llama_stack.log import get_logger
 from llama_stack.providers.datatypes import Api, ProviderSpec
 
-logger = logging.getLogger(__name__)
+logger = get_logger(name=__name__, category="core")
 
 
 def configure_single_provider(registry: dict[str, ProviderSpec], provider: Provider) -> Provider:

llama_stack/core/library_client.py

@@ -7,7 +7,6 @@
 import asyncio
 import inspect
 import json
-import logging
 import os
 import sys
 from concurrent.futures import ThreadPoolExecutor
@@ -48,14 +47,15 @@
 from llama_stack.core.utils.config import redact_sensitive_fields
 from llama_stack.core.utils.context import preserve_contexts_async_generator
 from llama_stack.core.utils.exec import in_notebook
+from llama_stack.log import get_logger
 from llama_stack.providers.utils.telemetry.tracing import (
     CURRENT_TRACE_CONTEXT,
     end_trace,
     setup_logger,
     start_trace,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(name=__name__, category="core")
 
 T = TypeVar("T")
 
@@ -173,6 +173,8 @@ def _remove_root_logger_handlers(self):
         """
         Remove all handlers from the root logger. Needed to avoid polluting the console with logs.
         """
+        import logging  # allow-direct-logging
+
         root_logger = logging.getLogger()
 
         for handler in root_logger.handlers[:]:

llama_stack/core/request_headers.py

@@ -6,19 +6,19 @@
 
 import contextvars
 import json
-import logging
 from contextlib import AbstractContextManager
 from typing import Any
 
 from llama_stack.core.datatypes import User
+from llama_stack.log import get_logger
 
 from .utils.dynamic import instantiate_class_type
 
-log = logging.getLogger(__name__)
-
 # Context variable for request provider data and auth attributes
 PROVIDER_DATA_VAR = contextvars.ContextVar("provider_data", default=None)
 
+logger = get_logger(name=__name__, category="core")
+
 
 class RequestProviderDataContext(AbstractContextManager):
     """Context manager for request provider data"""
@@ -61,7 +61,7 @@ def get_request_provider_data(self) -> Any:
             provider_data = validator(**val)
             return provider_data
         except Exception as e:
-            log.error(f"Error parsing provider data: {e}")
+            logger.error(f"Error parsing provider data: {e}")
             return None
 
 
@@ -83,7 +83,7 @@ def parse_request_provider_data(headers: dict[str, str]) -> dict[str, Any] | Non
     try:
         return json.loads(val)
     except json.JSONDecodeError:
-        log.error("Provider data not encoded as a JSON object!")
+        logger.error("Provider data not encoded as a JSON object!")
         return None
 
 

llama_stack/core/server/server.py

@@ -9,7 +9,7 @@
 import functools
 import inspect
 import json
-import logging
+import logging  # allow-direct-logging
 import os
 import ssl
 import sys

llama_stack/core/utils/exec.py

@@ -4,17 +4,17 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-import logging
+import importlib
 import os
 import signal
 import subprocess
 import sys
 
 from termcolor import cprint
 
-log = logging.getLogger(__name__)
+from llama_stack.log import get_logger
 
-import importlib
+logger = get_logger(name=__name__, category="core")
 
 
 def formulate_run_args(image_type: str, image_name: str) -> list:
@@ -72,7 +72,7 @@ def run_command(command: list[str]) -> int:
     def sigint_handler(signum, frame):
         nonlocal ctrl_c_pressed
         ctrl_c_pressed = True
-        log.info("\nCtrl-C detected. Aborting...")
+        logger.info("\nCtrl-C detected. Aborting...")
 
     try:
         # Set up the signal handler
@@ -86,10 +86,10 @@ def sigint_handler(signum, frame):
         )
         return result.returncode
     except subprocess.SubprocessError as e:
-        log.error(f"Subprocess error: {e}")
+        logger.error(f"Subprocess error: {e}")
         return 1
     except Exception as e:
-        log.exception(f"Unexpected error: {e}")
+        logger.exception(f"Unexpected error: {e}")
         return 1
     finally:
         # Restore the original signal handler

llama_stack/core/utils/prompt_for_config.py

@@ -6,15 +6,16 @@
 
 import inspect
 import json
-import logging
 from enum import Enum
 from typing import Annotated, Any, Literal, Union, get_args, get_origin
 
 from pydantic import BaseModel
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefinedType
 
-log = logging.getLogger(__name__)
+from llama_stack.log import get_logger
+
+logger = get_logger(name=__name__, category="core")
 
 
 def is_list_of_primitives(field_type):
@@ -107,7 +108,7 @@ def prompt_for_discriminated_union(
 
         if discriminator_value in type_map:
             chosen_type = type_map[discriminator_value]
-            log.info(f"\nConfiguring {chosen_type.__name__}:")
+            logger.info(f"\nConfiguring {chosen_type.__name__}:")
 
             if existing_value and (getattr(existing_value, discriminator) != discriminator_value):
                 existing_value = None
@@ -117,7 +118,7 @@ def prompt_for_discriminated_union(
             setattr(sub_config, discriminator, discriminator_value)
             return sub_config
         else:
-            log.error(f"Invalid {discriminator}. Please try again.")
+            logger.error(f"Invalid {discriminator}. Please try again.")
 
 
 # This is somewhat elaborate, but does not purport to be comprehensive in any way.
@@ -166,7 +167,7 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                     config_data[field_name] = validated_value
                     break
                 except KeyError:
-                    log.error(f"Invalid choice. Please choose from: {', '.join(e.name for e in field_type)}")
+                    logger.error(f"Invalid choice. Please choose from: {', '.join(e.name for e in field_type)}")
             continue
 
         if is_discriminated_union(field):
@@ -179,7 +180,7 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                 config_data[field_name] = None
                 continue
             nested_type = get_non_none_type(field_type)
-            log.info(f"Entering sub-configuration for {field_name}:")
+            logger.info(f"Entering sub-configuration for {field_name}:")
             config_data[field_name] = prompt_for_config(nested_type, existing_value)
         elif is_optional(field_type) and is_discriminated_union(get_non_none_type(field_type)):
             prompt = f"Do you want to configure {field_name}? (y/n): "
@@ -193,7 +194,7 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                 existing_value,
             )
         elif can_recurse(field_type):
-            log.info(f"\nEntering sub-configuration for {field_name}:")
+            logger.info(f"\nEntering sub-configuration for {field_name}:")
             config_data[field_name] = prompt_for_config(
                 field_type,
                 existing_value,
@@ -220,7 +221,7 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                         config_data[field_name] = None
                         break
                     else:
-                        log.error("This field is required. Please provide a value.")
+                        logger.error("This field is required. Please provide a value.")
                         continue
                 else:
                     try:
@@ -242,10 +243,10 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                                 value = [element_type(item) for item in value]
 
                             except json.JSONDecodeError:
-                                log.error('Invalid JSON. Please enter a valid JSON-encoded list e.g., ["foo","bar"]')
+                                logger.error('Invalid JSON. Please enter a valid JSON-encoded list e.g., ["foo","bar"]')
                                 continue
                             except ValueError as e:
-                                log.error(f"{str(e)}")
+                                logger.error(f"{str(e)}")
                                 continue
 
                         elif get_origin(field_type) is dict:
@@ -255,7 +256,7 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                                     raise ValueError("Input must be a JSON-encoded dictionary")
 
                             except json.JSONDecodeError:
-                                log.error("Invalid JSON. Please enter a valid JSON-encoded dict.")
+                                logger.error("Invalid JSON. Please enter a valid JSON-encoded dict.")
                                 continue
 
                         # Convert the input to the correct type
@@ -268,7 +269,9 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                             value = field_type(user_input)
 
                     except ValueError:
-                        log.error(f"Invalid input. Expected type: {getattr(field_type, '__name__', str(field_type))}")
+                        logger.error(
+                            f"Invalid input. Expected type: {getattr(field_type, '__name__', str(field_type))}"
+                        )
                         continue
 
                 try:
@@ -277,6 +280,6 @@ def prompt_for_config(config_type: type[BaseModel], existing_config: BaseModel |
                     config_data[field_name] = validated_value
                     break
                 except ValueError as e:
-                    log.error(f"Validation error: {str(e)}")
+                    logger.error(f"Validation error: {str(e)}")
 
     return config_type(**config_data)

llama_stack/log.py

@@ -4,11 +4,11 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-import logging
+import logging  # allow-direct-logging
 import os
 import re
 import sys
-from logging.config import dictConfig
+from logging.config import dictConfig  # allow-direct-logging
 
 from rich.console import Console
 from rich.errors import MarkupError

llama_stack/models/llama/llama3/multimodal/encoder_utils.py

@@ -13,7 +13,7 @@
 
 # Copyright (c) Meta Platforms, Inc. and its affiliates.
 import math
-from logging import getLogger
+from logging import getLogger  # allow-direct-logging
 
 import torch
 import torch.nn.functional as F