From 31d03fa41ae193e5764ad7bfa16c646cd38455fd Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 29 Sep 2025 10:12:50 +0200 Subject: [PATCH 1/2] Docstrings for endpoints module --- src/utils/endpoints.py | 75 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 72 insertions(+), 3 deletions(-) diff --git a/src/utils/endpoints.py b/src/utils/endpoints.py index 818aac64..a34dcb44 100644 --- a/src/utils/endpoints.py +++ b/src/utils/endpoints.py @@ -62,7 +62,13 @@ def validate_conversation_ownership( def check_configuration_loaded(config: AppConfig) -> None: - """Check that configuration is loaded and raise exception when it is not.""" + """ + Ensure the application configuration object is present. + + Raises: + HTTPException: HTTP 500 Internal Server Error with detail `{"response": + "Configuration is not loaded"}` when `config` is None. + """ if config is None: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, @@ -71,7 +77,31 @@ def check_configuration_loaded(config: AppConfig) -> None: def get_system_prompt(query_request: QueryRequest, config: AppConfig) -> str: - """Get the system prompt: the provided one, configured one, or default one.""" + """ + Resolve which system prompt to use for a query. + + Precedence: + 1. If the request includes `system_prompt`, that value is returned (highest + precedence). + 2. Else if the application configuration provides a customization + `system_prompt`, that value is returned. + 3. Otherwise the module default `constants.DEFAULT_SYSTEM_PROMPT` is + returned (lowest precedence). + + If configuration disables per-request system prompts + (config.customization.disable_query_system_prompt) and the incoming + `query_request` contains a `system_prompt`, an HTTP 422 Unprocessable + Entity is raised instructing the client to remove the field. + + Parameters: + query_request (QueryRequest): The incoming query payload; may contain a + per-request `system_prompt`. + config (AppConfig): Application configuration which may include + customization flags and a default `system_prompt`. + + Returns: + str: The resolved system prompt to apply to the request. + """ system_prompt_disabled = ( config.customization is not None and config.customization.disable_query_system_prompt @@ -171,7 +201,46 @@ async def get_agent( conversation_id: str | None, no_tools: bool = False, ) -> tuple[AsyncAgent, str, str]: - """Get existing agent or create a new one with session persistence.""" + """ + Create or reuse an AsyncAgent with session persistence. + + Return the agent, conversation and session IDs. + + If a conversation_id is provided, the function attempts to retrieve the + existing agent and, on success, rebinds a newly created agent instance to + that conversation (deleting the temporary/orphan agent) and returns the + first existing session_id for the conversation. If no conversation_id is + provided or the existing agent cannot be retrieved, a new agent and session + are created. + + Parameters: + model_id (str): Identifier of the model to instantiate the agent with. + system_prompt (str): Instructions/system prompt to initialize the agent with. + + available_input_shields (list[str]): Input shields to apply to the + agent; empty list used if None/empty. + + available_output_shields (list[str]): Output shields to apply to the + agent; empty list used if None/empty. + + conversation_id (str | None): If provided, attempt to reuse the agent + for this conversation; otherwise a new conversation_id is created. + + no_tools (bool): When True, disables tool parsing for the agent (uses no tool parser). + + Returns: + tuple[AsyncAgent, str, str]: A tuple of (agent, conversation_id, session_id). + + Raises: + HTTPException: Raises HTTP 404 Not Found if an attempt to reuse a + conversation succeeds in retrieving the agent but no sessions are found + for that conversation. + + Side effects: + - May delete an orphan agent when rebinding a newly created agent to an + existing conversation_id. + - Initializes the agent and may create a new session. + """ existing_agent_id = None if conversation_id: with suppress(ValueError): From 4f7a1be2126a58b6cb73e820830ac40ee5012d4e Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 29 Sep 2025 10:13:02 +0200 Subject: [PATCH 2/2] Docstrings for llama_stack_version.py --- src/utils/llama_stack_version.py | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/utils/llama_stack_version.py b/src/utils/llama_stack_version.py index 691b9064..55088da5 100644 --- a/src/utils/llama_stack_version.py +++ b/src/utils/llama_stack_version.py @@ -22,7 +22,15 @@ class InvalidLlamaStackVersionException(Exception): async def check_llama_stack_version( client: AsyncLlamaStackClient, ) -> None: - """Check if the Llama Stack version is supported by the LCS.""" + """ + Verify the connected Llama Stack's version is within the supported range. + + This coroutine fetches the Llama Stack version from the + provided client and validates it against the configured minimal + and maximal supported versions. Raises + InvalidLlamaStackVersionException if the detected version is + outside the supported range. + """ version_info = await client.inspect.version() compare_versions( version_info.version, @@ -32,7 +40,23 @@ async def check_llama_stack_version( def compare_versions(version_info: str, minimal: str, maximal: str) -> None: - """Compare current Llama Stack version with minimal and maximal allowed versions.""" + """ + Validate that a semver version string is within the inclusive [minimal, maximal] range. + + Parses `version_info`, `minimal`, and `maximal` with semver.Version.parse + and compares them. If the current version is lower than `minimal` or + higher than `maximal`, an InvalidLlamaStackVersionException is raised. + + Parameters: + version_info (str): Semver version string to validate (must be + parseable by semver.Version.parse). + minimal (str): Minimum allowed semver version (inclusive). + maximal (str): Maximum allowed semver version (inclusive). + + Raises: + InvalidLlamaStackVersionException: If `version_info` is outside the + inclusive range defined by `minimal` and `maximal`. + """ current_version = Version.parse(version_info) minimal_version = Version.parse(minimal) maximal_version = Version.parse(maximal)