Nous.Tools.DateTimeTools (nous v0.17.1)

Copy Markdown View Source

Built-in tools for date and time operations.

These tools provide common date/time functionality that AI agents often need:

  • Get current date/time in various formats
  • Parse and format dates
  • Calculate date differences
  • Check business days and weekends
  • Timezone conversions

Usage

agent = Nous.new("lmstudio:qwen3-vl-4b-thinking-mlx",
  tools: [
    &DateTimeTools.current_date/2,
    &DateTimeTools.current_time/2,
    &DateTimeTools.current_datetime/2
  ]
)

{:ok, result} = Nous.run(agent, "What day is today?")

Summary

Types

args()

Tool arguments exactly as the model produced them: JSON object keys stay strings, values are unvalidated. Every function below reads what it needs and falls back to a default for anything missing or of the wrong type.

ctx()

Run context. These tools are pure and ignore it, but they are registered with takes_ctx: true, so it is always the first argument.

result()

Tool result: an atom-keyed map that echoes the inputs it used alongside the computed fields, so the model can see what it actually asked for.

Functions

add_days(ctx, args)

Add or subtract days from a date.

current_date(ctx, args)

Get the current date in the specified format.

current_datetime(ctx, args)

Get the current date and time together.

current_month(ctx, args)

Get information about the current month.

current_time(ctx, args)

Get the current time in the specified format.

current_week(ctx, args)

Get the start and end of the current week.

date_difference(ctx, args)

Calculate the difference between two dates.

day_of_week(ctx, args)

Get the day of the week for a given date.

is_weekend(ctx, args)

Check if a date is a weekend.

parse_date(ctx, args)

Parse a human-readable date string.

Types

args()

@type args() :: %{optional(String.t()) => term()}

Tool arguments exactly as the model produced them: JSON object keys stay strings, values are unvalidated. Every function below reads what it needs and falls back to a default for anything missing or of the wrong type.

ctx()

@type ctx() :: Nous.RunContext.t() | nil

Run context. These tools are pure and ignore it, but they are registered with takes_ctx: true, so it is always the first argument.

result()

@type result() :: %{required(atom()) => term()}

Tool result: an atom-keyed map that echoes the inputs it used alongside the computed fields, so the model can see what it actually asked for.

Functions

add_days(ctx, args)

@spec add_days(ctx(), args()) :: result()

Add or subtract days from a date.

Arguments

  • date: Date in ISO8601 format (YYYY-MM-DD), defaults to today
  • days: Number of days to add (positive) or subtract (negative)

current_date(ctx, args)

@spec current_date(ctx(), args()) :: result()

Get the current date in the specified format.

Arguments

  • format: "iso8601" (default), "us" (MM/DD/YYYY), "eu" (DD/MM/YYYY), "full" (Monday, January 1, 2025)
  • timezone: Optional timezone (e.g., "America/New_York", "Europe/London", "UTC")

current_datetime(ctx, args)

@spec current_datetime(ctx(), args()) :: result()

Get the current date and time together.

Arguments

  • format: "iso8601" (default), "rfc3339", "unix", "human"
  • timezone: Optional timezone

current_month(ctx, args)

@spec current_month(ctx(), args()) :: result()

Get information about the current month.

Arguments

  • timezone: Optional timezone

current_time(ctx, args)

@spec current_time(ctx(), args()) :: result()

Get the current time in the specified format.

Arguments

  • format: "24h" (default, HH:MM:SS), "12h" (hh:MM:SS AM/PM), "short" (HH:MM)
  • timezone: Optional timezone

current_week(ctx, args)

@spec current_week(ctx(), args()) :: result()

Get the start and end of the current week.

Arguments

  • timezone: Optional timezone
  • week_start: Day to consider start of week (1=Monday default, 7=Sunday)

date_difference(ctx, args)

@spec date_difference(ctx(), args()) :: result()

Calculate the difference between two dates.

Arguments

  • date1: First date in ISO8601 format (YYYY-MM-DD)
  • date2: Second date in ISO8601 format (YYYY-MM-DD)
  • unit: "days" (default), "weeks", "months", "years"

day_of_week(ctx, args)

@spec day_of_week(ctx(), args()) :: result()

Get the day of the week for a given date.

Arguments

  • date: Date in ISO8601 format (YYYY-MM-DD), defaults to today

is_weekend(ctx, args)

@spec is_weekend(ctx(), args()) :: result()

Check if a date is a weekend.

Arguments

  • date: Date in ISO8601 format (YYYY-MM-DD), defaults to today

parse_date(ctx, args)

@spec parse_date(ctx(), args()) :: result()

Parse a human-readable date string.

Arguments

  • date_string: Date in various formats (ISO8601, MM/DD/YYYY, DD/MM/YYYY, etc.)
  • format: Expected format hint ("iso8601", "us", "eu")