nvidia-nat 1.3.0a20250910__py3-none-any.whl → 1.3.0a20250917__py3-none-any.whl

nat/builder/builder.py

@@ -24,9 +24,11 @@ from nat.authentication.interfaces import AuthProviderBase
 from nat.builder.context import Context
 from nat.builder.framework_enum import LLMFrameworkEnum
 from nat.builder.function import Function
+from nat.builder.function import FunctionGroup
 from nat.data_models.authentication import AuthProviderBaseConfig
 from nat.data_models.component_ref import AuthenticationRef
 from nat.data_models.component_ref import EmbedderRef
+from nat.data_models.component_ref import FunctionGroupRef
 from nat.data_models.component_ref import FunctionRef
 from nat.data_models.component_ref import LLMRef
 from nat.data_models.component_ref import MemoryRef
@@ -36,6 +38,7 @@ from nat.data_models.component_ref import TTCStrategyRef
 from nat.data_models.embedder import EmbedderBaseConfig
 from nat.data_models.evaluator import EvaluatorBaseConfig
 from nat.data_models.function import FunctionBaseConfig
+from nat.data_models.function import FunctionGroupBaseConfig
 from nat.data_models.function_dependencies import FunctionDependencies
 from nat.data_models.llm import LLMBaseConfig
 from nat.data_models.memory import MemoryBaseConfig
@@ -64,18 +67,33 @@ class Builder(ABC):
     async def add_function(self, name: str | FunctionRef, config: FunctionBaseConfig) -> Function:
         pass
 
+    @abstractmethod
+    async def add_function_group(self, name: str | FunctionGroupRef, config: FunctionGroupBaseConfig) -> FunctionGroup:
+        pass
+
     @abstractmethod
     def get_function(self, name: str | FunctionRef) -> Function:
         pass
 
+    @abstractmethod
+    def get_function_group(self, name: str | FunctionGroupRef) -> FunctionGroup:
+        pass
+
     def get_functions(self, function_names: Sequence[str | FunctionRef]) -> list[Function]:
 
         return [self.get_function(name) for name in function_names]
 
+    def get_function_groups(self, function_group_names: Sequence[str | FunctionGroupRef]) -> list[FunctionGroup]:
+        return [self.get_function_group(name) for name in function_group_names]
+
     @abstractmethod
     def get_function_config(self, name: str | FunctionRef) -> FunctionBaseConfig:
         pass
 
+    @abstractmethod
+    def get_function_group_config(self, name: str | FunctionGroupRef) -> FunctionGroupBaseConfig:
+        pass
+
     @abstractmethod
     async def set_workflow(self, config: FunctionBaseConfig) -> Function:
         pass
@@ -88,10 +106,11 @@ class Builder(ABC):
     def get_workflow_config(self) -> FunctionBaseConfig:
         pass
 
-    def get_tools(self, tool_names: Sequence[str | FunctionRef],
+    @abstractmethod
+    def get_tools(self,
+                  tool_names: Sequence[str | FunctionRef | FunctionGroupRef],
                   wrapper_type: LLMFrameworkEnum | str) -> list[typing.Any]:
-
-        return [self.get_tool(fn_name=n, wrapper_type=wrapper_type) for n in tool_names]
+        pass
 
     @abstractmethod
     def get_tool(self, fn_name: str | FunctionRef, wrapper_type: LLMFrameworkEnum | str) -> typing.Any:
@@ -257,8 +276,12 @@ class Builder(ABC):
     def get_function_dependencies(self, fn_name: str) -> FunctionDependencies:
         pass
 
+    @abstractmethod
+    def get_function_group_dependencies(self, fn_name: str) -> FunctionDependencies:
+        pass
+
 
-class EvalBuilder(Builder):
+class EvalBuilder(ABC):
 
     @abstractmethod
     async def add_evaluator(self, name: str, config: EvaluatorBaseConfig):

nat/builder/component_utils.py

@@ -30,6 +30,7 @@ from nat.data_models.component_ref import generate_instance_id
 from nat.data_models.config import Config
 from nat.data_models.embedder import EmbedderBaseConfig
 from nat.data_models.function import FunctionBaseConfig
+from nat.data_models.function import FunctionGroupBaseConfig
 from nat.data_models.llm import LLMBaseConfig
 from nat.data_models.memory import MemoryBaseConfig
 from nat.data_models.object_store import ObjectStoreBaseConfig
@@ -48,6 +49,7 @@ _component_group_order = [
     ComponentGroup.OBJECT_STORES,
     ComponentGroup.RETRIEVERS,
     ComponentGroup.TTC_STRATEGIES,
+    ComponentGroup.FUNCTION_GROUPS,
     ComponentGroup.FUNCTIONS,
 ]
 
@@ -107,6 +109,8 @@ def group_from_component(component: TypedBaseModel) -> ComponentGroup | None:
         return ComponentGroup.EMBEDDERS
     if (isinstance(component, FunctionBaseConfig)):
         return ComponentGroup.FUNCTIONS
+    if (isinstance(component, FunctionGroupBaseConfig)):
+        return ComponentGroup.FUNCTION_GROUPS
     if (isinstance(component, LLMBaseConfig)):
         return ComponentGroup.LLMS
     if (isinstance(component, MemoryBaseConfig)):
@@ -254,9 +258,9 @@ def build_dependency_sequence(config: "Config") -> list[ComponentInstanceData]:
             runtime instance references.
     """
 
-    total_node_count = len(config.embedders) + len(config.functions) + len(config.llms) + len(config.memory) + len(
-        config.object_stores) + len(config.retrievers) + len(config.ttc_strategies) + len(
-            config.authentication) + 1  # +1 for the workflow
+    total_node_count = (len(config.embedders) + len(config.functions) + len(config.function_groups) + len(config.llms) +
+                        len(config.memory) + len(config.object_stores) + len(config.retrievers) +
+                        len(config.ttc_strategies) + len(config.authentication) + 1)  # +1 for the workflow
 
     dependency_map: dict
     dependency_graph: nx.DiGraph

nat/builder/function.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 
 import logging
+import re
 import typing
 from abc import ABC
 from abc import abstractmethod
@@ -29,7 +30,9 @@ from nat.builder.function_base import InputT
 from nat.builder.function_base import SingleOutputT
 from nat.builder.function_base import StreamingOutputT
 from nat.builder.function_info import FunctionInfo
+from nat.data_models.function import EmptyFunctionConfig
 from nat.data_models.function import FunctionBaseConfig
+from nat.data_models.function import FunctionGroupBaseConfig
 
 _InvokeFnT = Callable[[InputT], Awaitable[SingleOutputT]]
 _StreamFnT = Callable[[InputT], AsyncGenerator[StreamingOutputT]]
@@ -342,3 +345,167 @@ class LambdaFunction(Function[InputT, StreamingOutputT, SingleOutputT]):
             pass
 
         return FunctionImpl(config=config, info=info, instance_name=instance_name)
+
+
+class FunctionGroup:
+    """
+    A group of functions that can be used together, sharing the same configuration, context, and resources.
+    """
+
+    def __init__(self, *, config: FunctionGroupBaseConfig, instance_name: str | None = None):
+        """
+        Creates a new function group.
+
+        Parameters
+        ----------
+        config : FunctionGroupBaseConfig
+            The configuration for the function group.
+        instance_name : str | None, optional
+            The name of the function group. If not provided, the type of the function group will be used.
+        """
+        self._config = config
+        self._instance_name = instance_name or config.type
+        self._functions: dict[str, Function] = {}
+
+    def add_function(self,
+                     name: str,
+                     fn: Callable,
+                     *,
+                     input_schema: type[BaseModel] | None = None,
+                     description: str | None = None,
+                     converters: list[Callable] | None = None):
+        """
+        Adds a function to the function group.
+
+        Parameters
+        ----------
+        name : str
+            The name of the function.
+        fn : Callable
+            The function to add to the function group.
+        input_schema : type[BaseModel] | None, optional
+            The input schema for the function.
+        description : str | None, optional
+            The description of the function.
+        converters : list[Callable] | None, optional
+            The converters to use for the function.
+
+        Raises
+        ------
+        ValueError
+            When the function name is empty or blank.
+            When the function name contains invalid characters.
+            When the function already exists in the function group.
+        """
+        if not name.strip():
+            raise ValueError("Function name cannot be empty or blank")
+        if not re.match(r"^[a-zA-Z0-9_-]+$", name):
+            raise ValueError(f"Function name can only contain letters, numbers, underscores, and hyphens: {name}")
+        if name in self._functions:
+            raise ValueError(f"Function {name} already exists in function group {self._instance_name}")
+
+        info = FunctionInfo.from_fn(fn, input_schema=input_schema, description=description, converters=converters)
+        full_name = self._get_fn_name(name)
+        lambda_fn = LambdaFunction.from_info(config=EmptyFunctionConfig(), info=info, instance_name=full_name)
+        self._functions[name] = lambda_fn
+
+    def get_config(self) -> FunctionGroupBaseConfig:
+        """
+        Returns the configuration for the function group.
+
+        Returns
+        -------
+        FunctionGroupBaseConfig
+            The configuration for the function group.
+        """
+        return self._config
+
+    def _get_fn_name(self, name: str) -> str:
+        return f"{self._instance_name}.{name}"
+
+    def _get_all_but_excluded_functions(self) -> dict[str, Function]:
+        """
+        Returns a dictionary of all functions in the function group except the excluded functions.
+        """
+        missing = set(self._config.exclude) - set(self._functions.keys())
+        if missing:
+            raise ValueError(f"Unknown excluded functions: {sorted(missing)}")
+        excluded = set(self._config.exclude)
+        return {self._get_fn_name(name): self._functions[name] for name in self._functions if name not in excluded}
+
+    def get_accessible_functions(self) -> dict[str, Function]:
+        """
+        Returns a dictionary of all accessible functions in the function group.
+        If the function group is configured to:
+        - include some functions, this will return only the included functions.
+        - not include or exclude any function, this will return all functions in the group.
+        - exclude some functions, this will return all functions in the group except the excluded functions.
+
+        Returns
+        -------
+        dict[str, Function]
+            A dictionary of all accessible functions in the function group.
+
+        Raises
+        ------
+        ValueError
+            When the function group is configured to include functions that are not found in the group.
+        """
+        if self._config.include:
+            return self.get_included_functions()
+        if self._config.exclude:
+            return self._get_all_but_excluded_functions()
+        return self.get_all_functions()
+
+    def get_excluded_functions(self) -> dict[str, Function]:
+        """
+        Returns a dictionary of all functions in the function group which are configured to be excluded.
+        If the function group is configured to not exclude any functions, this will return an empty dictionary.
+
+        Returns
+        -------
+        dict[str, Function]
+            A dictionary of all excluded functions in the function group.
+
+        Raises
+        ------
+        ValueError
+            When the function group is configured to exclude functions that are not found in the group.
+        """
+        missing = set(self._config.exclude) - set(self._functions.keys())
+        if missing:
+            raise ValueError(f"Unknown excluded functions: {sorted(missing)}")
+        return {self._get_fn_name(name): self._functions[name] for name in self._config.exclude}
+
+    def get_included_functions(self) -> dict[str, Function]:
+        """
+        Returns a dictionary of all functions in the function group which are:
+        - configured to be included and added to the global function registry
+        - not configured to be excluded.
+        If the function group is configured to not include any functions, this will return an empty dictionary.
+
+        Returns
+        -------
+        dict[str, Function]
+            A dictionary of all included functions in the function group.
+
+        Raises
+        ------
+        ValueError
+            When the function group is configured to include functions that are not found in the group.
+        """
+        missing = set(self._config.include) - set(self._functions.keys())
+        if missing:
+            raise ValueError(f"Unknown included functions: {sorted(missing)}")
+        return {self._get_fn_name(name): self._functions[name] for name in self._config.include}
+
+    def get_all_functions(self) -> dict[str, Function]:
+        """
+        Returns a dictionary of all functions in the function group, regardless if they are included or excluded.
+
+        Returns
+        -------
+        dict[str, Function]
+            A dictionary of all functions in the function group.
+        """
+        return {self._get_fn_name(name): self._functions[name] for name in self._functions}

nat/builder/function_info.py

@@ -233,7 +233,7 @@ class FunctionDescriptor:
 
             is_input_typed = all([a != sig.empty for a in annotations])
 
-            input_type = tuple[*annotations] if is_input_typed else None  # noqa: syntax-error
+            input_type = tuple[*annotations] if is_input_typed else None
 
         # Get the base type here removing all annotations and async generators
         output_annotation_decomp = DecomposedType(sig.return_annotation).get_base_type()

nat/builder/workflow.py

@@ -20,6 +20,7 @@ from typing import Any
 from nat.builder.context import ContextState
 from nat.builder.embedder import EmbedderProviderInfo
 from nat.builder.function import Function
+from nat.builder.function import FunctionGroup
 from nat.builder.function_base import FunctionBase
 from nat.builder.function_base import InputT
 from nat.builder.function_base import SingleOutputT
@@ -44,6 +45,7 @@ class Workflow(FunctionBase[InputT, StreamingOutputT, SingleOutputT]):
                  config: Config,
                  entry_fn: Function[InputT, StreamingOutputT, SingleOutputT],
                  functions: dict[str, Function] | None = None,
+                 function_groups: dict[str, FunctionGroup] | None = None,
                  llms: dict[str, LLMProviderInfo] | None = None,
                  embeddings: dict[str, EmbedderProviderInfo] | None = None,
                  memory: dict[str, MemoryEditor] | None = None,
@@ -59,6 +61,7 @@ class Workflow(FunctionBase[InputT, StreamingOutputT, SingleOutputT]):
 
         self.config = config
         self.functions = functions or {}
+        self.function_groups = function_groups or {}
         self.llms = llms or {}
         self.embeddings = embeddings or {}
         self.memory = memory or {}
@@ -126,6 +129,7 @@ class Workflow(FunctionBase[InputT, StreamingOutputT, SingleOutputT]):
                       config: Config,
                       entry_fn: Function[InputT, StreamingOutputT, SingleOutputT],
                       functions: dict[str, Function] | None = None,
+                      function_groups: dict[str, FunctionGroup] | None = None,
                       llms: dict[str, LLMProviderInfo] | None = None,
                       embeddings: dict[str, EmbedderProviderInfo] | None = None,
                       memory: dict[str, MemoryEditor] | None = None,
@@ -145,6 +149,7 @@ class Workflow(FunctionBase[InputT, StreamingOutputT, SingleOutputT]):
         return WorkflowImpl(config=config,
                             entry_fn=entry_fn,
                             functions=functions,
+                            function_groups=function_groups,
                             llms=llms,
                             embeddings=embeddings,
                             memory=memory,