Timezone Support for datetime Tool and Normalize Response Time Handling (#660)

## Description
<!-- Note: The pull request title will be included in the CHANGELOG. -->
<!-- Provide a standalone description of changes in this PR. -->

- Added timezone support for the `datetime_tools`, so now it will
automatically extract the `x-timezone` from the headers from context,
which will be used to format the current time.
- If the `x-timezone` is not present in the headers, the fallback behavior is checked
    - The documentations should also be clear now.

- Fixed a small issue in
`NeMo-Agent-Toolkit/src/nat/builder/user_interaction_manager.py`. Before
the timestamp is in UTC (as seen by the `Z` suffix in the timestamp),
but the timestamp is in the local timezone, which is most likely not in
UTC timezone.

- Made a tiny change for the `NeMo-Agent-Toolkit-UI` repository. So now
the front-end also stores the timezone in its header to
be sent to the backend.
- The change:
[https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI/pull/38](https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI/pull/38)


Closes #445

## By Submitting this PR I confirm:
- I am familiar with the [Contributing
Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This
certifies that the contribution is your original work, or you have
rights to submit it under the same license, or a compatible license.
- Any contribution which contains commits that are not Signed-Off will
not be accepted.
- When the PR is ready for review, new or existing tests cover these
changes.
- When the PR is ready for review, the documentation is up to date with
these changes.

---------

Signed-off-by: Daniel Wang <daniewang@nvidia.com>

Author: zhongxuanwang-nv

external/nat-ui

@@ -61,13 +61,13 @@ async def prompt_user_input(self, content: HumanPrompt) -> InteractionResponse:
 
         uuid_req = str(uuid.uuid4())
         status = InteractionStatus.IN_PROGRESS
-        timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ")
+        timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
         sys_human_interaction = InteractionPrompt(id=uuid_req, status=status, timestamp=timestamp, content=content)
 
         resp = await self._context_state.user_input_callback.get()(sys_human_interaction)
 
         # Rebuild a InteractionResponse object with the response
-        timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ")
+        timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
         status = InteractionStatus.COMPLETED
         sys_human_interaction = InteractionResponse(id=uuid_req, status=status, timestamp=timestamp, content=resp)
 

src/nat/builder/user_interaction_manager.py

@@ -47,6 +47,12 @@ class Settings(HashableBaseModel):
     # Registry Handeler Configuration
     channels: dict[str, RegistryHandlerBaseConfig] = {}
 
+    # Timezone fallback behavior
+    # Options:
+    #  - "utc": default to UTC
+    #  - "system": use the system's local timezone
+    fallback_timezone: typing.Literal["system", "utc"] = "utc"
+
     _configuration_directory: typing.ClassVar[str]
     _settings_changed_hooks: typing.ClassVar[list[Callable[[], None]]] = []
     _settings_changed_hooks_active: bool = True
@@ -165,7 +171,11 @@ def from_file():
             loaded_config = {}
         else:
             with open(file_path, mode="r", encoding="utf-8") as f:
-                loaded_config = json.load(f)
+                try:
+                    loaded_config = json.load(f)
+                except Exception as e:
+                    logger.exception("Error loading configuration file %s: %s", file_path, e)
+                    loaded_config = {}
 
         settings = Settings(**loaded_config)
         settings.set_configuration_directory(configuration_directory)
@@ -214,6 +224,8 @@ def _revalidate(self, config_dict) -> bool:
                 match field:
                     case "channels":
                         self.channels = validated_data.channels
+                    case "fallback_timezone":
+                        self.fallback_timezone = validated_data.fallback_timezone
                     case _:
                         raise ValueError(f"Encountered invalid model field: {field}")
 

src/nat/settings/global_settings.py

@@ -13,30 +13,70 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import datetime
+import zoneinfo
+
+from starlette.datastructures import Headers
+
 from nat.builder.builder import Builder
 from nat.builder.function_info import FunctionInfo
 from nat.cli.register_workflow import register_function
 from nat.data_models.function import FunctionBaseConfig
+from nat.settings.global_settings import GlobalSettings
 
 
 class CurrentTimeToolConfig(FunctionBaseConfig, name="current_datetime"):
     """
-    Simple tool which returns the current date and time in human readable format.
+    Simple tool which returns the current date and time in human readable format with timezone information. By default,
+    the timezone is in Etc/UTC. If the user provides a timezone in the header, we will use it. Timezone will be
+    provided in IANA zone name format. For example, "America/New_York" or "Etc/UTC".
     """
     pass
 
 
-@register_function(config_type=CurrentTimeToolConfig)
-async def current_datetime(config: CurrentTimeToolConfig, builder: Builder):
+def _get_timezone_obj(headers: Headers | None) -> zoneinfo.ZoneInfo | datetime.tzinfo:
+    # Default to UTC
+    timezone_obj = zoneinfo.ZoneInfo("Etc/UTC")
+
+    if headers:
+        # If user has provided a timezone in the header, we will prioritize on using it
+        timezone_header = headers.get("x-timezone")
+        if timezone_header:
+            try:
+                timezone_obj = zoneinfo.ZoneInfo(timezone_header)
+            except Exception:
+                pass
+    else:
+        # Only if a timezone is not in the header, we will determine default timezone based on global settings
+        fallback_tz = GlobalSettings.get().fallback_timezone
+
+        if fallback_tz == "system":
+            # Use the system's local timezone. Avoid requiring external deps.
+            timezone_obj = datetime.datetime.now().astimezone().tzinfo or zoneinfo.ZoneInfo("Etc/UTC")
+
+    return timezone_obj
 
-    import datetime
+
+@register_function(config_type=CurrentTimeToolConfig)
+async def current_datetime(_config: CurrentTimeToolConfig, _builder: Builder):
 
     async def _get_current_time(unused: str) -> str:
 
-        now = datetime.datetime.now()  # Get current time
-        now_human_readable = now.strftime(("%Y-%m-%d %H:%M:%S"))
+        del unused  # Unused parameter to avoid linting error
+
+        from nat.builder.context import Context
+        nat_context = Context.get()
+
+        headers: Headers | None = nat_context.metadata.headers
+
+        timezone_obj = _get_timezone_obj(headers)
+
+        now = datetime.datetime.now(timezone_obj)
+        now_machine_readable = now.strftime(("%Y-%m-%d %H:%M:%S %z"))
 
-        return f"The current time of day is {now_human_readable}"  # Format time in H:MM AM/PM format
+        # Returns the current time in machine readable format with timezone offset.
+        return f"The current time of day is {now_machine_readable}"
 
-    yield FunctionInfo.from_fn(_get_current_time,
-                               description="Returns the current date and time in human readable format.")
+    yield FunctionInfo.from_fn(
+        _get_current_time,
+        description="Returns the current date and time in human readable format with timezone information.")