nvidia-nat 1.2.0rc5__py3-none-any.whl

aiq/agent/tool_calling_agent/agent.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# pylint: disable=R0917
+import logging
+
+from langchain_core.callbacks.base import AsyncCallbackHandler
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages.base import BaseMessage
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from langgraph.prebuilt import ToolNode
+from pydantic import BaseModel
+from pydantic import Field
+
+from aiq.agent.base import AGENT_CALL_LOG_MESSAGE
+from aiq.agent.base import AGENT_LOG_PREFIX
+from aiq.agent.base import AgentDecision
+from aiq.agent.dual_node import DualNodeAgent
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCallAgentGraphState(BaseModel):
+    """State schema for the Tool Calling Agent Graph"""
+    messages: list[BaseMessage] = Field(default_factory=list)  # input and output of the Agent
+
+
+class ToolCallAgentGraph(DualNodeAgent):
+    """Configurable LangGraph Tool Calling Agent. A Tool Calling Agent requires an LLM which supports tool calling.
+    A tool Calling Agent utilizes the tool input parameters to select the optimal tool.  Supports handling tool errors.
+    Argument "detailed_logs" toggles logging of inputs, outputs, and intermediate steps."""
+
+    def __init__(self,
+                 llm: BaseChatModel,
+                 tools: list[BaseTool],
+                 callbacks: list[AsyncCallbackHandler] = None,
+                 detailed_logs: bool = False,
+                 handle_tool_errors: bool = True):
+        super().__init__(llm=llm, tools=tools, callbacks=callbacks, detailed_logs=detailed_logs)
+        self.tool_caller = ToolNode(tools, handle_tool_errors=handle_tool_errors)
+        logger.debug("%s Initialized Tool Calling Agent Graph", AGENT_LOG_PREFIX)
+
+    async def agent_node(self, state: ToolCallAgentGraphState):
+        try:
+            logger.debug('%s Starting the Tool Calling Agent Node', AGENT_LOG_PREFIX)
+            if len(state.messages) == 0:
+                raise RuntimeError('No input received in state: "messages"')
+            response = await self.llm.ainvoke(state.messages, config=RunnableConfig(callbacks=self.callbacks))
+            if self.detailed_logs:
+                agent_input = "\n".join(str(message.content) for message in state.messages)
+                logger.info(AGENT_CALL_LOG_MESSAGE, agent_input, response)
+
+            state.messages += [response]
+            return state
+        except Exception as ex:
+            logger.exception("%s Failed to call agent_node: %s", AGENT_LOG_PREFIX, ex, exc_info=True)
+            raise ex
+
+    async def conditional_edge(self, state: ToolCallAgentGraphState):
+        try:
+            logger.debug("%s Starting the Tool Calling Conditional Edge", AGENT_LOG_PREFIX)
+            last_message = state.messages[-1]
+            if last_message.tool_calls:
+                # the agent wants to call a tool
+                logger.debug('%s Agent is calling a tool', AGENT_LOG_PREFIX)
+                return AgentDecision.TOOL
+            if self.detailed_logs:
+                logger.debug("%s Final answer:\n%s", AGENT_LOG_PREFIX, state.messages[-1].content)
+            return AgentDecision.END
+        except Exception as ex:
+            logger.exception("%s Failed to determine whether agent is calling a tool: %s",
+                             AGENT_LOG_PREFIX,
+                             ex,
+                             exc_info=True)
+            logger.warning("%s Ending graph traversal", AGENT_LOG_PREFIX)
+            return AgentDecision.END
+
+    async def tool_node(self, state: ToolCallAgentGraphState):
+        try:
+            logger.debug("%s Starting Tool Node", AGENT_LOG_PREFIX)
+            tool_calls = state.messages[-1].tool_calls
+            tools = [tool.get('name') for tool in tool_calls]
+            tool_input = state.messages[-1]
+            tool_response = await self.tool_caller.ainvoke(input={"messages": [tool_input]},
+                                                           config=RunnableConfig(callbacks=self.callbacks,
+                                                                                 configurable={}))
+            # this configurable = {} argument is needed due to a bug in LangGraph PreBuilt ToolNode ^
+
+            for response in tool_response.get('messages'):
+                if self.detailed_logs:
+                    self._log_tool_response(str(tools), str(tool_input), response.content)
+                state.messages += [response]
+
+            return state
+        except Exception as ex:
+            logger.exception("%s Failed to call tool_node: %s", AGENT_LOG_PREFIX, ex, exc_info=ex)
+            raise ex
+
+    async def build_graph(self):
+        try:
+            await super()._build_graph(state_schema=ToolCallAgentGraphState)
+            logger.debug("%s Tool Calling Agent Graph built and compiled successfully", AGENT_LOG_PREFIX)
+            return self.graph
+        except Exception as ex:
+            logger.exception("%s Failed to build Tool Calling Agent Graph: %s", AGENT_LOG_PREFIX, ex, exc_info=ex)
+            raise ex

aiq/agent/tool_calling_agent/register.py

@@ -0,0 +1,106 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+from pydantic import Field
+
+from aiq.builder.builder import Builder
+from aiq.builder.framework_enum import LLMFrameworkEnum
+from aiq.builder.function_info import FunctionInfo
+from aiq.cli.register_workflow import register_function
+from aiq.data_models.component_ref import FunctionRef
+from aiq.data_models.component_ref import LLMRef
+from aiq.data_models.function import FunctionBaseConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCallAgentWorkflowConfig(FunctionBaseConfig, name="tool_calling_agent"):
+    """
+    A Tool Calling Agent requires an LLM which supports tool calling. A tool Calling Agent utilizes the tool
+    input parameters to select the optimal tool.  Supports handling tool errors.
+    """
+
+    tool_names: list[FunctionRef] = Field(default_factory=list,
+                                          description="The list of tools to provide to the tool calling agent.")
+    llm_name: LLMRef = Field(description="The LLM model to use with the tool calling agent.")
+    verbose: bool = Field(default=False, description="Set the verbosity of the tool calling agent's logging.")
+    handle_tool_errors: bool = Field(default=True, description="Specify ability to handle tool calling errors.")
+    description: str = Field(default="Tool Calling Agent Workflow", description="Description of this functions use.")
+    max_iterations: int = Field(default=15, description="Number of tool calls before stoping the tool calling agent.")
+
+
+@register_function(config_type=ToolCallAgentWorkflowConfig, framework_wrappers=[LLMFrameworkEnum.LANGCHAIN])
+async def tool_calling_agent_workflow(config: ToolCallAgentWorkflowConfig, builder: Builder):
+    from langchain_core.messages.human import HumanMessage
+    from langgraph.graph.graph import CompiledGraph
+
+    from aiq.agent.base import AGENT_LOG_PREFIX
+
+    from .agent import ToolCallAgentGraph
+    from .agent import ToolCallAgentGraphState
+
+    # we can choose an LLM for the ReAct agent in the config file
+    llm = await builder.get_llm(config.llm_name, wrapper_type=LLMFrameworkEnum.LANGCHAIN)
+    # the agent can run any installed tool, simply install the tool and add it to the config file
+    # the sample tools provided can easily be copied or changed
+    tools = builder.get_tools(tool_names=config.tool_names, wrapper_type=LLMFrameworkEnum.LANGCHAIN)
+    if not tools:
+        raise ValueError(f"No tools specified for Tool Calling Agent '{config.llm_name}'")
+
+    # some LLMs support tool calling
+    # these models accept the tool's input schema and decide when to use a tool based on the input's relevance
+    try:
+        # in tool calling agents, we bind the tools to the LLM, to pass the tools' input schemas at runtime
+        llm = llm.bind_tools(tools)
+    except NotImplementedError as ex:
+        logger.error("%s Failed to bind tools: %s", AGENT_LOG_PREFIX, ex, exc_info=True)
+        raise ex
+
+    # construct the Tool Calling Agent Graph from the configured llm, and tools
+    graph: CompiledGraph = await ToolCallAgentGraph(llm=llm,
+                                                    tools=tools,
+                                                    detailed_logs=config.verbose,
+                                                    handle_tool_errors=config.handle_tool_errors).build_graph()
+
+    async def _response_fn(input_message: str) -> str:
+        try:
+            # initialize the starting state with the user query
+            input_message = HumanMessage(content=input_message)
+            state = ToolCallAgentGraphState(messages=[input_message])
+
+            # run the Tool Calling Agent Graph
+            state = await graph.ainvoke(state, config={'recursion_limit': (config.max_iterations + 1) * 2})
+            # setting recursion_limit: 4 allows 1 tool call
+            #   - allows the Tool Calling Agent to perform 1 cycle / call 1 single tool,
+            #   - but stops the agent when it tries to call a tool a second time
+
+            # get and return the output from the state
+            state = ToolCallAgentGraphState(**state)
+            output_message = state.messages[-1]  # pylint: disable=E1136
+            return output_message.content
+        except Exception as ex:
+            logger.exception("%s Tool Calling Agent failed with exception: %s", AGENT_LOG_PREFIX, ex, exc_info=ex)
+            if config.verbose:
+                return str(ex)
+            return "I seem to be having a problem."
+
+    try:
+        yield FunctionInfo.from_fn(_response_fn, description=config.description)
+    except GeneratorExit:
+        logger.exception("%s Workflow exited early!", AGENT_LOG_PREFIX, exc_info=True)
+    finally:
+        logger.debug("%s Cleaning up react_agent workflow.", AGENT_LOG_PREFIX)

aiq/authentication/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aiq/authentication/api_key/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aiq/authentication/api_key/api_key_auth_provider.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+from pydantic import SecretStr
+
+from aiq.authentication.api_key.api_key_auth_provider_config import APIKeyAuthProviderConfig
+from aiq.authentication.interfaces import AuthProviderBase
+from aiq.data_models.authentication import AuthResult
+from aiq.data_models.authentication import BearerTokenCred
+from aiq.data_models.authentication import HeaderAuthScheme
+
+logger = logging.getLogger(__name__)
+
+
+class APIKeyAuthProvider(AuthProviderBase[APIKeyAuthProviderConfig]):
+
+    # fmt: off
+    def __init__(self,
+                 config: APIKeyAuthProviderConfig,
+                 config_name: str | None = None) -> None:  # pylint: disable=unused-argument
+        assert isinstance(config, APIKeyAuthProviderConfig), ("Config is not APIKeyAuthProviderConfig")
+        super().__init__(config)
+    # fmt: on
+
+    async def _construct_authentication_header(self) -> BearerTokenCred:
+        """
+        Constructs the authenticated HTTP header based on the authentication scheme.
+        Basic Authentication follows the OpenAPI 3.0 Basic Authentication standard as well as RFC 7617.
+
+        Args:
+            header_auth_scheme (HeaderAuthScheme): The HTTP authentication scheme to use.
+                                             Supported schemes: BEARER, X_API_KEY, BASIC, CUSTOM.
+
+        Returns:
+            BearerTokenCred: The HTTP headers containing the authentication credentials.
+                             Returns None if the scheme is not supported or configuration is invalid.
+
+        """
+
+        from aiq.authentication.interfaces import AUTHORIZATION_HEADER
+
+        config: APIKeyAuthProviderConfig = self.config
+
+        header_auth_scheme = config.auth_scheme
+
+        if header_auth_scheme == HeaderAuthScheme.BEARER:
+            return BearerTokenCred(token=SecretStr(f"{config.raw_key}"),
+                                   scheme=HeaderAuthScheme.BEARER.value,
+                                   header_name=AUTHORIZATION_HEADER)
+
+        if header_auth_scheme == HeaderAuthScheme.X_API_KEY:
+            return BearerTokenCred(token=SecretStr(f"{config.raw_key}"),
+                                   scheme=HeaderAuthScheme.X_API_KEY.value,
+                                   header_name='')
+
+        if header_auth_scheme == HeaderAuthScheme.CUSTOM:
+            if not config.custom_header_name:
+                raise ValueError('custom_header_name required when using header_auth_scheme=CUSTOM')
+
+            if not config.custom_header_prefix:
+                raise ValueError('custom_header_prefix required when using header_auth_scheme=CUSTOM')
+
+            return BearerTokenCred(token=SecretStr(f"{config.raw_key}"),
+                                   scheme=config.custom_header_prefix,
+                                   header_name=config.custom_header_name)
+
+        raise ValueError(f"Unsupported header auth scheme: {header_auth_scheme}")
+
+    async def authenticate(self, user_id: str | None = None) -> AuthResult | None:
+        """
+        Authenticate the user using the API key credentials.
+
+        Args:
+            user_id (str): The user ID to authenticate.
+
+        Returns:
+            AuthenticatedContext: The authenticated context containing headers, query params, cookies, etc.
+        """
+
+        headers = await self._construct_authentication_header()
+
+        return AuthResult(credentials=[headers])

aiq/authentication/api_key/api_key_auth_provider_config.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import re
+import string
+
+from pydantic import Field
+from pydantic import field_validator
+
+from aiq.authentication.exceptions.api_key_exceptions import APIKeyFieldError
+from aiq.authentication.exceptions.api_key_exceptions import HeaderNameFieldError
+from aiq.authentication.exceptions.api_key_exceptions import HeaderPrefixFieldError
+from aiq.data_models.authentication import AuthProviderBaseConfig
+from aiq.data_models.authentication import HeaderAuthScheme
+
+logger = logging.getLogger(__name__)
+
+# Strict RFC 7230 compliant header name regex
+HEADER_NAME_REGEX = re.compile(r"^[!#$%&'*+\-.^_`|~0-9a-zA-Z]+$")
+
+
+class APIKeyAuthProviderConfig(AuthProviderBaseConfig, name="api_key"):
+    """
+    API Key authentication configuration model.
+    """
+
+    raw_key: str = Field(description=("Raw API token or credential to be injected into the request parameter. "
+                                      "Used for 'bearer','x-api-key','custom', and other schemes. "))
+
+    auth_scheme: HeaderAuthScheme = Field(default=HeaderAuthScheme.BEARER,
+                                          description=("The HTTP authentication scheme to use. "
+                                                       "Supported schemes: BEARER, X_API_KEY, BASIC, CUSTOM."))
+
+    custom_header_name: str | None = Field(description="The HTTP header name that MUST be used in conjunction "
+                                           "with the custom_header_prefix when HeaderAuthScheme is CUSTOM.",
+                                           default=None)
+    custom_header_prefix: str | None = Field(description="The HTTP header prefix that MUST be used in conjunction "
+                                             "with the custom_header_name when HeaderAuthScheme is CUSTOM.",
+                                             default=None)
+
+    @field_validator('raw_key')
+    @classmethod
+    def validate_raw_key(cls, value: str) -> str:
+        if not value:
+            raise APIKeyFieldError('value_missing', 'raw_key field value is required.')
+
+        if len(value) < 8:
+            raise APIKeyFieldError(
+                'value_too_short',
+                'raw_key field value must be at least 8 characters long for security. '
+                f'Got: {len(value)} characters.')
+
+        if len(value.strip()) != len(value):
+            raise APIKeyFieldError('whitespace_found',
+                                   'raw_key field value cannot have leading or trailing whitespace.')
+
+        if any(c in string.whitespace for c in value):
+            raise APIKeyFieldError('contains_whitespace', 'raw_key must not contain any '
+                                   'whitespace characters.')
+
+        return value
+
+    @field_validator('custom_header_name')
+    @classmethod
+    def validate_custom_header_name(cls, value: str) -> str:
+        if not value:
+            raise HeaderNameFieldError('value_missing', 'custom_header_name is required.')
+
+        if value != value.strip():
+            raise HeaderNameFieldError('whitespace_found',
+                                       'custom_header_name field value cannot have leading or trailing whitespace.')
+
+        if any(c in string.whitespace for c in value):
+            raise HeaderNameFieldError('contains_whitespace',
+                                       'custom_header_name must not contain any whitespace characters.')
+
+        if not HEADER_NAME_REGEX.fullmatch(value):
+            raise HeaderNameFieldError(
+                'invalid_format',
+                'custom_header_name must match the HTTP token syntax: ASCII letters, digits, or allowed symbols.')
+
+        return value
+
+    @field_validator('custom_header_prefix')
+    @classmethod
+    def validate_custom_header_prefix(cls, value: str) -> str:
+        if not value:
+            raise HeaderPrefixFieldError('value_missing', 'custom_header_prefix is required.')
+
+        if value != value.strip():
+            raise HeaderPrefixFieldError(
+                'whitespace_found', 'custom_header_prefix field value cannot have '
+                'leading or trailing whitespace.')
+
+        if any(c in string.whitespace for c in value):
+            raise HeaderPrefixFieldError('contains_whitespace',
+                                         'custom_header_prefix must not contain any whitespace characters.')
+
+        if not value.isascii():
+            raise HeaderPrefixFieldError('invalid_format', 'custom_header_prefix must be ASCII.')
+
+        return value
+
+    @field_validator('raw_key', mode='after')
+    @classmethod
+    def validate_raw_key_after(cls, value: str) -> str:
+        if not value:
+            raise APIKeyFieldError('value_missing', 'raw_key field value is '
+                                   'required after construction.')
+
+        return value

aiq/authentication/api_key/register.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from aiq.authentication.api_key.api_key_auth_provider_config import APIKeyAuthProviderConfig
+from aiq.builder.builder import Builder
+from aiq.cli.register_workflow import register_auth_provider
+
+
+@register_auth_provider(config_type=APIKeyAuthProviderConfig)
+async def api_key_client(config: APIKeyAuthProviderConfig, builder: Builder):
+
+    from aiq.authentication.api_key.api_key_auth_provider import APIKeyAuthProvider
+
+    yield APIKeyAuthProvider(config=config)

aiq/authentication/exceptions/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aiq/authentication/exceptions/api_key_exceptions.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+class APIKeyFieldError(Exception):
+    """Raised when API Key Config api_key field validation fails unexpectedly."""
+
+    def __init__(self, error_code: str, message: str, *args):
+        self.error_code = error_code
+        super().__init__(f"[{error_code}] {message}", *args)
+
+
+class HeaderNameFieldError(Exception):
+    """Raised when API Key Config header_name field validation fails unexpectedly."""
+
+    def __init__(self, error_code: str, message: str, *args):
+        self.error_code = error_code
+        super().__init__(f"[{error_code}] {message}", *args)
+
+
+class HeaderPrefixFieldError(Exception):
+    """Raised when API Key Config header_prefix field validation fails unexpectedly."""
+
+    def __init__(self, error_code: str, message: str, *args):
+        self.error_code = error_code
+        super().__init__(f"[{error_code}] {message}", *args)

aiq/authentication/http_basic_auth/http_basic_auth_provider.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pydantic import SecretStr
+
+from aiq.authentication.interfaces import AuthProviderBase
+from aiq.builder.context import AIQContext
+from aiq.data_models.authentication import AuthenticatedContext
+from aiq.data_models.authentication import AuthFlowType
+from aiq.data_models.authentication import AuthProviderBaseConfig
+from aiq.data_models.authentication import AuthResult
+from aiq.data_models.authentication import BasicAuthCred
+from aiq.data_models.authentication import BearerTokenCred
+
+
+class HTTPBasicAuthProvider(AuthProviderBase):
+    """
+    Abstract base class for HTTP Basic Authentication exchangers.
+    """
+
+    def __init__(self, config: AuthProviderBaseConfig):
+        """
+        Initialize the HTTP Basic Auth Exchanger with the given configuration.
+        """
+        super().__init__(config)
+
+        self._authenticated_tokens: dict[str, AuthResult] = {}
+
+    async def authenticate(self, user_id: str | None = None) -> AuthResult:
+        """
+        Performs simple HTTP Authentication using the provided user ID.
+        """
+
+        context = AIQContext.get()
+
+        if user_id is None and hasattr(context, "metadata") and hasattr(
+                context.metadata, "cookies") and context.metadata.cookies is not None:
+            session_id = context.metadata.cookies.get("aiqtoolkit-session", None)
+            if not session_id:
+                raise RuntimeError("Authentication failed. No session ID found. Cannot identify user.")
+
+            user_id = session_id
+
+        if user_id and user_id in self._authenticated_tokens:
+            return self._authenticated_tokens[user_id]
+
+        auth_callback = context.user_auth_callback
+
+        try:
+            auth_context: AuthenticatedContext = await auth_callback(self.config, AuthFlowType.HTTP_BASIC)
+        except RuntimeError as e:
+            raise RuntimeError(f"Authentication callback failed: {str(e)}. Did you forget to set a "
+                               f"callback handler for your frontend?") from e
+
+        basic_auth_credentials = BasicAuthCred(username=SecretStr(auth_context.metadata.get("username", "")),
+                                               password=SecretStr(auth_context.metadata.get("password", "")))
+
+        # Get the auth token from the headers of auth context
+        bearer_token = auth_context.headers.get("Authorization", "").split(" ")[-1]
+        if not bearer_token:
+            raise RuntimeError("Authentication failed: No Authorization header found in the response.")
+
+        bearer_token_cred = BearerTokenCred(token=SecretStr(bearer_token), scheme="Basic")
+
+        auth_result = AuthResult(credentials=[basic_auth_credentials, bearer_token_cred])
+
+        self._authenticated_tokens[user_id] = auth_result
+
+        return auth_result