TimeSkill.cs

// Copyright (c) Microsoft. All rights reserved.

using System;
using System.Globalization;
using Microsoft.SemanticKernel.SkillDefinition;

namespace Microsoft.SemanticKernel.CoreSkills;

/// <summary>
/// TimeSkill provides a set of functions to get the current time and date.
/// </summary>
/// <example>
/// Usage: kernel.ImportSkill("time", new TimeSkill());
/// Examples:
/// {{time.date}}            => Sunday, 12 January, 2031
/// {{time.today}}           => Sunday, 12 January, 2031
/// {{time.now}}             => Sunday, January 12, 2031 9:15 PM
/// {{time.utcNow}}          => Sunday, January 13, 2031 5:15 AM
/// {{time.time}}            => 09:15:07 PM
/// {{time.year}}            => 2031
/// {{time.month}}           => January
/// {{time.monthNumber}}     => 01
/// {{time.day}}             => 12
/// {{time.dayOfMonth}}      => 12
/// {{time.dayOfWeek}}       => Sunday
/// {{time.hour}}            => 9 PM
/// {{time.hourNumber}}      => 21
/// {{time.minute}}          => 15
/// {{time.minutes}}         => 15
/// {{time.second}}          => 7
/// {{time.seconds}}         => 7
/// {{time.timeZoneOffset}}  => -08:00
/// {{time.timeZoneName}}    => PST
/// </example>
/// <remark>
/// Note: the time represents the time on the hw/vm/machine where the kernel is running.
/// TODO: import and use user's timezone
/// </remark>
public class TimeSkill
{
    /// <summary>
    /// Get the current date
    /// </summary>
    /// <example>
    /// {{time.date}} => Sunday, 12 January, 2031
    /// </example>
    /// <returns> The current date </returns>
    [SKFunction("Get the current date")]
    public string Date()
    {
        // Example: Sunday, 12 January, 2025
        return DateTimeOffset.Now.ToString("D", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current date and time in the local time zone"
    /// </summary>
    /// <example>
    /// {{time.now}} => Sunday, January 12, 2025 9:15 PM
    /// </example>
    /// <returns> The current date and time in the local time zone </returns>
    [SKFunction("Get the current date and time in the local time zone")]
    public string Now()
    {
        // Sunday, January 12, 2025 9:15 PM
        return DateTimeOffset.Now.ToString("f", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current UTC date and time
    /// </summary>
    /// <example>
    /// {{time.utcNow}} => Sunday, January 13, 2025 5:15 AM
    /// </example>
    /// <returns> The current UTC date and time </returns>
    [SKFunction("Get the current UTC date and time")]
    public string UtcNow()
    {
        // Sunday, January 13, 2025 5:15 AM
        return DateTimeOffset.UtcNow.ToString("f", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current time
    /// </summary>
    /// <example>
    /// {{time.time}} => 09:15:07 PM
    /// </example>
    /// <returns> The current time </returns>
    [SKFunction("Get the current time")]
    public string Time()
    {
        // Example: 09:15:07 PM
        return DateTimeOffset.Now.ToString("hh:mm:ss tt", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current year
    /// </summary>
    /// <example>
    /// {{time.year}} => 2025
    /// </example>
    /// <returns> The current year </returns>
    [SKFunction("Get the current year")]
    public string Year()
    {
        // Example: 2025
        return DateTimeOffset.Now.ToString("yyyy", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current month name
    /// </summary>
    /// <example>
    /// {time.month}} => January
    /// </example>
    /// <returns> The current month name </returns>
    [SKFunction("Get the current month name")]
    public string Month()
    {
        // Example: January
        return DateTimeOffset.Now.ToString("MMMM", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current month number
    /// </summary>
    /// <example>
    /// {{time.monthNumber}} => 01
    /// </example>
    /// <returns> The current month number </returns>
    [SKFunction("Get the current month number")]
    public string MonthNumber()
    {
        // Example: 01
        return DateTimeOffset.Now.ToString("MM", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current day of the month
    /// </summary>
    /// <example>
    /// {{time.day}} => 12
    /// </example>
    /// <returns> The current day of the month </returns>
    [SKFunction("Get the current day of the month")]
    public string Day()
    {
        // Example: 12
        return DateTimeOffset.Now.ToString("DD", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current day of the week
    /// </summary>
    /// <example>
    /// {{time.dayOfWeek}} => Sunday
    /// </example>
    /// <returns> The current day of the week </returns>
    [SKFunction("Get the current day of the week")]
    public string DayOfWeek()
    {
        // Example: Sunday
        return DateTimeOffset.Now.ToString("dddd", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current clock hour
    /// </summary>
    /// <example>
    /// {{time.hour}} => 9 PM
    /// </example>
    /// <returns> The current clock hour </returns>
    [SKFunction("Get the current clock hour")]
    public string Hour()
    {
        // Example: 9 PM
        return DateTimeOffset.Now.ToString("h tt", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the current clock 24-hour number
    /// </summary>
    /// <example>
    /// {{time.hourNumber}} => 21
    /// </example>
    /// <returns> The current clock 24-hour number </returns>
    [SKFunction("Get the current clock 24-hour number")]
    public string HourNumber()
    {
        // Example: 21
        return DateTimeOffset.Now.ToString("HH", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the minutes on the current hour
    /// </summary>
    /// <example>
    /// {{time.minute}} => 15
    /// </example>
    /// <returns> The minutes on the current hour </returns>
    [SKFunction("Get the minutes on the current hour")]
    public string Minute()
    {
        // Example: 15
        return DateTimeOffset.Now.ToString("mm", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the seconds on the current minute
    /// </summary>
    /// <example>
    /// {{time.second}} => 7
    /// </example>
    /// <returns> The seconds on the current minute </returns>
    [SKFunction("Get the seconds on the current minute")]
    public string Second()
    {
        // Example: 7
        return DateTimeOffset.Now.ToString("ss", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the local time zone offset from UTC
    /// </summary>
    /// <example>
    /// {{time.timeZoneOffset}} => -08:00
    /// </example>
    /// <returns> The local time zone offset from UTC </returns>
    [SKFunction("Get the local time zone offset from UTC")]
    public string TimeZoneOffset()
    {
        // Example: -08:00
        return DateTimeOffset.Now.ToString("%K", CultureInfo.CurrentCulture);
    }

    /// <summary>
    /// Get the local time zone name
    /// </summary>
    /// <example>
    /// {{time.timeZoneName}} => PST
    /// </example>
    /// <remark>
    /// Note: this is the "current" timezone and it can change over the year, e.g. from PST to PDT
    /// </remark>
    /// <returns> The local time zone name </returns>
    [SKFunction("Get the local time zone name")]
    public string TimeZoneName()
    {
        // Example: PST
        // Note: this is the "current" timezone and it can change over the year, e.g. from PST to PDT
        return TimeZoneInfo.Local.DisplayName;
    }
}