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 <nweinber@redhat.com>

llama_stack/providers/utils/inference/embedding_mixin.py

@@ -5,7 +5,6 @@
 # the root directory of this source tree.
 
 import base64
-import logging
 import struct
 from typing import TYPE_CHECKING
 
@@ -27,7 +26,9 @@ from llama_stack.providers.utils.inference.prompt_adapter import interleaved_con
 EMBEDDING_MODELS = {}
 
 
-log = logging.getLogger(__name__)
+from llama_stack.log import get_logger
+
+log = get_logger(name=__name__, category="inference")
 
 
 class SentenceTransformerEmbeddingMixin:

llama_stack/providers/utils/inference/litellm_openai_mixin.py

@@ -54,7 +54,7 @@ from llama_stack.providers.utils.inference.prompt_adapter import (
     interleaved_content_as_str,
 )
 
-logger = get_logger(name=__name__, category="inference")
+log = get_logger(name=__name__, category="inference")
 
 
 class LiteLLMOpenAIMixin(
@@ -157,7 +157,7 @@ class LiteLLMOpenAIMixin(
         params = await self._get_params(request)
         params["model"] = self.get_litellm_model_name(params["model"])
 
-        logger.debug(f"params to litellm (openai compat): {params}")
+        log.debug(f"params to litellm (openai compat): {params}")
         # see https://docs.litellm.ai/docs/completion/stream#async-completion
         response = await litellm.acompletion(**params)
         if stream:
@@ -460,7 +460,7 @@ class LiteLLMOpenAIMixin(
         :return: True if the model is available dynamically, False otherwise.
         """
         if self.litellm_provider_name not in litellm.models_by_provider:
-            logger.error(f"Provider {self.litellm_provider_name} is not registered in litellm.")
+            log.error(f"Provider {self.litellm_provider_name} is not registered in litellm.")
             return False
 
         return model in litellm.models_by_provider[self.litellm_provider_name]

llama_stack/providers/utils/inference/model_registry.py

@@ -17,7 +17,7 @@ from llama_stack.providers.utils.inference import (
     ALL_HUGGINGFACE_REPOS_TO_MODEL_DESCRIPTOR,
 )
 
-logger = get_logger(name=__name__, category="core")
+log = get_logger(name=__name__, category="core")
 
 
 class RemoteInferenceProviderConfig(BaseModel):
@@ -135,7 +135,7 @@ class ModelRegistryHelper(ModelsProtocolPrivate):
         :param model: The model identifier to check.
         :return: True if the model is available dynamically, False otherwise.
         """
-        logger.info(
+        log.info(
             f"check_model_availability is not implemented for {self.__class__.__name__}. Returning False by default."
         )
         return False

llama_stack/providers/utils/inference/openai_compat.py

@@ -5,7 +5,6 @@
 # the root directory of this source tree.
 import base64
 import json
-import logging
 import struct
 import time
 import uuid
@@ -116,6 +115,7 @@ from llama_stack.apis.inference import (
 from llama_stack.apis.inference import (
     OpenAIChoice as OpenAIChatCompletionChoice,
 )
+from llama_stack.log import get_logger
 from llama_stack.models.llama.datatypes import (
     BuiltinTool,
     StopReason,
@@ -128,7 +128,7 @@ from llama_stack.providers.utils.inference.prompt_adapter import (
     decode_assistant_message,
 )
 
-logger = logging.getLogger(__name__)
+log = get_logger(name=__name__, category="inference")
 
 
 class OpenAICompatCompletionChoiceDelta(BaseModel):
@@ -316,7 +316,7 @@ def process_chat_completion_response(
                 if t.tool_name in request_tools:
                     new_tool_calls.append(t)
                 else:
-                    logger.warning(f"Tool {t.tool_name} not found in request tools")
+                    log.warning(f"Tool {t.tool_name} not found in request tools")
 
             if len(new_tool_calls) < len(raw_message.tool_calls):
                 raw_message.tool_calls = new_tool_calls
@@ -477,7 +477,7 @@ async def process_chat_completion_stream_response(
                 )
             )
         else:
-            logger.warning(f"Tool {tool_call.tool_name} not found in request tools")
+            log.warning(f"Tool {tool_call.tool_name} not found in request tools")
             yield ChatCompletionResponseStreamChunk(
                 event=ChatCompletionResponseEvent(
                     event_type=ChatCompletionResponseEventType.progress,
@@ -1198,7 +1198,7 @@ async def convert_openai_chat_completion_stream(
             )
 
     for idx, buffer in tool_call_idx_to_buffer.items():
-        logger.debug(f"toolcall_buffer[{idx}]: {buffer}")
+        log.debug(f"toolcall_buffer[{idx}]: {buffer}")
         if buffer["name"]:
             delta = ")"
             buffer["content"] += delta

llama_stack/providers/utils/inference/openai_mixin.py

@@ -25,7 +25,7 @@ from llama_stack.apis.inference import (
 from llama_stack.log import get_logger
 from llama_stack.providers.utils.inference.openai_compat import prepare_openai_completion_params
 
-logger = get_logger(name=__name__, category="core")
+log = get_logger(name=__name__, category="core")
 
 
 class OpenAIMixin(ABC):
@@ -125,9 +125,9 @@ class OpenAIMixin(ABC):
         Direct OpenAI completion API call.
         """
         if guided_choice is not None:
-            logger.warning("guided_choice is not supported by the OpenAI API. Ignoring.")
+            log.warning("guided_choice is not supported by the OpenAI API. Ignoring.")
         if prompt_logprobs is not None:
-            logger.warning("prompt_logprobs is not supported by the OpenAI API. Ignoring.")
+            log.warning("prompt_logprobs is not supported by the OpenAI API. Ignoring.")
 
         # TODO: fix openai_completion to return type compatible with OpenAI's API response
         return await self.client.completions.create(  # type: ignore[no-any-return]
@@ -267,6 +267,6 @@ class OpenAIMixin(ABC):
             pass
         except Exception as e:
             # All other errors (auth, rate limit, network, etc.)
-            logger.warning(f"Failed to check model availability for {model}: {e}")
+            log.warning(f"Failed to check model availability for {model}: {e}")
 
         return False

llama_stack/providers/utils/kvstore/mongodb/mongodb.py

@@ -4,16 +4,16 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-import logging
 from datetime import datetime
 
 from pymongo import AsyncMongoClient
 
+from llama_stack.log import get_logger
 from llama_stack.providers.utils.kvstore import KVStore
 
 from ..config import MongoDBKVStoreConfig
 
-log = logging.getLogger(__name__)
+log = get_logger(name=__name__, category="core")
 
 
 class MongoDBKVStoreImpl(KVStore):

llama_stack/providers/utils/kvstore/postgres/postgres.py

@@ -4,16 +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
 from datetime import datetime
 
 import psycopg2
 from psycopg2.extras import DictCursor
 
+from llama_stack.log import get_logger
+
 from ..api import KVStore
 from ..config import PostgresKVStoreConfig
 
-log = logging.getLogger(__name__)
+log = get_logger(name=__name__, category="core")
 
 
 class PostgresKVStoreImpl(KVStore):

llama_stack/providers/utils/memory/openai_vector_store_mixin.py

@@ -6,7 +6,6 @@
 
 import asyncio
 import json
-import logging
 import mimetypes
 import time
 import uuid
@@ -37,10 +36,11 @@ from llama_stack.apis.vector_io import (
     VectorStoreSearchResponse,
     VectorStoreSearchResponsePage,
 )
+from llama_stack.log import get_logger
 from llama_stack.providers.utils.kvstore.api import KVStore
 from llama_stack.providers.utils.memory.vector_store import content_from_data_and_mime_type, make_overlapped_chunks
 
-logger = logging.getLogger(__name__)
+log = get_logger(name=__name__, category="core")
 
 # Constants for OpenAI vector stores
 CHUNK_MULTIPLIER = 5
@@ -378,7 +378,7 @@ class OpenAIVectorStoreMixin(ABC):
         try:
             await self.unregister_vector_db(vector_store_id)
         except Exception as e:
-            logger.warning(f"Failed to delete underlying vector DB {vector_store_id}: {e}")
+            log.warning(f"Failed to delete underlying vector DB {vector_store_id}: {e}")
 
         return VectorStoreDeleteResponse(
             id=vector_store_id,
@@ -460,7 +460,7 @@ class OpenAIVectorStoreMixin(ABC):
             )
 
         except Exception as e:
-            logger.error(f"Error searching vector store {vector_store_id}: {e}")
+            log.error(f"Error searching vector store {vector_store_id}: {e}")
             # Return empty results on error
             return VectorStoreSearchResponsePage(
                 search_query=search_query,
@@ -614,7 +614,7 @@ class OpenAIVectorStoreMixin(ABC):
                 )
                 vector_store_file_object.status = "completed"
         except Exception as e:
-            logger.error(f"Error attaching file to vector store: {e}")
+            log.error(f"Error attaching file to vector store: {e}")
             vector_store_file_object.status = "failed"
             vector_store_file_object.last_error = VectorStoreFileLastError(
                 code="server_error",

llama_stack/providers/utils/memory/vector_store.py

@@ -5,7 +5,6 @@
 # the root directory of this source tree.
 import base64
 import io
-import logging
 import re
 import time
 from abc import ABC, abstractmethod
@@ -25,6 +24,7 @@ from llama_stack.apis.common.content_types import (
 from llama_stack.apis.tools import RAGDocument
 from llama_stack.apis.vector_dbs import VectorDB
 from llama_stack.apis.vector_io import Chunk, ChunkMetadata, QueryChunksResponse
+from llama_stack.log import get_logger
 from llama_stack.models.llama.llama3.tokenizer import Tokenizer
 from llama_stack.providers.datatypes import Api
 from llama_stack.providers.utils.inference.prompt_adapter import (
@@ -32,12 +32,12 @@ from llama_stack.providers.utils.inference.prompt_adapter import (
 )
 from llama_stack.providers.utils.vector_io.vector_utils import generate_chunk_id
 
-log = logging.getLogger(__name__)
-
 # Constants for reranker types
 RERANKER_TYPE_RRF = "rrf"
 RERANKER_TYPE_WEIGHTED = "weighted"
 
+log = get_logger(name=__name__, category="memory")
+
 
 def parse_pdf(data: bytes) -> str:
     # For PDF and DOC/DOCX files, we can't reliably convert to string

llama_stack/providers/utils/scheduler.py

@@ -17,7 +17,7 @@ from pydantic import BaseModel
 
 from llama_stack.log import get_logger
 
-logger = get_logger(name=__name__, category="scheduler")
+log = get_logger(name=__name__, category="scheduler")
 
 
 # TODO: revisit the list of possible statuses when defining a more coherent
@@ -186,7 +186,7 @@ class _NaiveSchedulerBackend(_SchedulerBackend):
             except Exception as e:
                 on_log_message_cb(str(e))
                 job.status = JobStatus.failed
-                logger.exception(f"Job {job.id} failed.")
+                log.exception(f"Job {job.id} failed.")
 
         asyncio.run_coroutine_threadsafe(do(), self._loop)
 
@@ -222,7 +222,7 @@ class Scheduler:
         msg = (datetime.now(UTC), message)
         # At least for the time being, until there's a better way to expose
         # logs to users, log messages on console
-        logger.info(f"Job {job.id}: {message}")
+        log.info(f"Job {job.id}: {message}")
         job.append_log(msg)
         self._backend.on_log_message_cb(job, msg)
 

llama_stack/providers/utils/sqlstore/authorized_sqlstore.py

@@ -17,7 +17,7 @@ from llama_stack.log import get_logger
 from .api import ColumnDefinition, ColumnType, PaginatedResponse, SqlStore
 from .sqlstore import SqlStoreType
 
-logger = get_logger(name=__name__, category="authorized_sqlstore")
+log = get_logger(name=__name__, category="authorized_sqlstore")
 
 # Hardcoded copy of the default policy that our SQL filtering implements
 # WARNING: If default_policy() changes, this constant must be updated accordingly
@@ -81,7 +81,7 @@ class AuthorizedSqlStore:
         actual_default = default_policy()
 
         if SQL_OPTIMIZED_POLICY != actual_default:
-            logger.warning(
+            log.warning(
                 f"SQL_OPTIMIZED_POLICY does not match default_policy(). "
                 f"SQL filtering will use conservative mode. "
                 f"Expected: {SQL_OPTIMIZED_POLICY}, Got: {actual_default}",

llama_stack/providers/utils/sqlstore/sqlalchemy_sqlstore.py

@@ -29,7 +29,7 @@ from llama_stack.log import get_logger
 from .api import ColumnDefinition, ColumnType, SqlStore
 from .sqlstore import SqlAlchemySqlStoreConfig
 
-logger = get_logger(name=__name__, category="sqlstore")
+log = get_logger(name=__name__, category="sqlstore")
 
 TYPE_MAPPING: dict[ColumnType, Any] = {
     ColumnType.INTEGER: Integer,
@@ -280,5 +280,5 @@ class SqlAlchemySqlStoreImpl(SqlStore):
         except Exception as e:
             # If any error occurs during migration, log it but don't fail
             # The table creation will handle adding the column
-            logger.error(f"Error adding column {column_name} to table {table}: {e}")
+            log.error(f"Error adding column {column_name} to table {table}: {e}")
             pass

llama_stack/providers/utils/telemetry/tracing.py

@@ -6,7 +6,7 @@
 
 import asyncio
 import contextvars
-import logging
+import logging  # allow-direct-logging
 import queue
 import random
 import threading