Check whether a date is a business day for a given country (optionally a subdivision).

Use this when an agent needs to know if a specific calendar date is a working day — i.e. NOT a weekend and NOT a public holiday — under a country's official calendar.

Args: date: ISO 8601 date string (YYYY-MM-DD), e.g. "2026-04-21". country: ISO 3166-1 alpha-2 country code. Case-insensitive (normalized to upper). subdiv: Optional country-specific subdivision code (state/province/region). Case-sensitive — pass it exactly as returned by get_supported_countries (e.g. "BY" for Bavaria, "CA" for California). When omitted, only nation-wide holidays are considered. Example: country="DE", subdiv="BY" treats Epiphany (Jan 6) as a holiday because it is observed only in Bavaria. Category filtering (e.g. catholic vs evangelical) is not currently supported.

Returns: dict with keys: date, country, subdiv (only if provided), is_business_day, is_weekend, is_holiday, holiday_name (str or None).

Raises: ValueError: if date is not valid ISO 8601, or country/subdiv is unknown.

Return the current date in the given IANA timezone.

Use this when an agent needs a stable, server-computed "today" — for example before calling other tools that require a concrete date. Does NOT consult any holiday calendar.

Args: timezone: IANA timezone name (e.g. "UTC", "Europe/Berlin", "America/New_York", "Asia/Tokyo"). Defaults to "UTC".

Returns: dict with keys: date (YYYY-MM-DD), timezone, day_of_week (full weekday name), iso_week (1-53).

Raises: ValueError: if timezone is not a recognized IANA zone.

Return the next business day on/after (inclusive) or strictly after date.

Use this to move forward to the soonest working day — skipping weekends and public holidays.

Args: date: ISO 8601 date string (YYYY-MM-DD) to start from. country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper). inclusive: When True, date itself qualifies if it is a business day. When False (default), the search starts the day after date. subdiv: Optional country-specific subdivision code (case-sensitive; see get_supported_countries). When omitted, only nation-wide holidays are considered. Example: country="DE", subdiv="BY" will skip Epiphany (Jan 6) in Bavaria.

Returns: dict with keys: input_date, next_business_day, country, subdiv (only if provided), skipped_days (number of non-business days traversed).

Raises: ValueError: on invalid date, unknown country/subdiv, or if no business day is found within ~10 years.

Return the previous business day on/before (inclusive) or strictly before date.

Use this to move backward to the most recent working day — skipping weekends and public holidays.

Args: date: ISO 8601 date string (YYYY-MM-DD) to start from. country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper). inclusive: When True, date itself qualifies if it is a business day. When False (default), the search starts the day before date. subdiv: Optional country-specific subdivision code (case-sensitive; see get_supported_countries). When omitted, only nation-wide holidays are considered.

Returns: dict with keys: input_date, previous_business_day, country, subdiv (only if provided), skipped_days.

Raises: ValueError: on invalid date, unknown country/subdiv, or if no business day is found within ~10 years.

Return the last business day of a given month for a country.

Use this for end-of-month billing, reporting, or settlement dates that must land on a working day. Walks backward from the last calendar day, skipping weekends and holidays.

Args: year: Four-digit year (e.g. 2026). month: Month 1-12. country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper). subdiv: Optional country-specific subdivision code (case-sensitive; see get_supported_countries). When omitted, only nation-wide holidays are considered.

Returns: dict with keys: year, month, country, subdiv (only if provided), last_business_day (YYYY-MM-DD), last_calendar_day (YYYY-MM-DD).

Raises: ValueError: on invalid month, unknown country/subdiv.

Count business days and list weekday holidays between two dates.

Use this to measure working-day spans for SLAs, delivery windows, or payroll periods. Weekend holidays are NOT listed in holidays_in_range (they do not reduce the business-day count); weekday holidays are.

Args: start_date: ISO 8601 date string (YYYY-MM-DD). Must be <= end_date. end_date: ISO 8601 date string (YYYY-MM-DD). country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper). inclusive: When True, both endpoints count toward the range. When False (default), end_date is excluded (half-open interval). subdiv: Optional country-specific subdivision code (case-sensitive; see get_supported_countries). When omitted, only nation-wide holidays are considered.

Returns: dict with keys: start_date, end_date, country, subdiv (only if provided), inclusive, business_days (int), calendar_days (int), holidays_in_range (list of {date, name} for weekday holidays only).

Raises: ValueError: if start_date > end_date, the span exceeds 100 years, dates are malformed, or country/subdiv is unknown.

List all holidays for a given year and country, sorted by date.

Use this to enumerate the full holiday calendar — for display, planning, or cross-referencing. Includes holidays that fall on weekends.

Args: year: Four-digit year (e.g. 2026). country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper). subdiv: Optional country-specific subdivision code (case-sensitive; see get_supported_countries). When omitted, only nation-wide holidays are returned. Example: country="DE", subdiv="BY" adds Bavarian regional holidays such as Epiphany (Jan 6) and All Saints' Day (Nov 1). Category filtering (e.g. catholic vs evangelical) is not currently supported; the union of applicable categories is returned.

Returns: dict with keys: year, country, subdiv (only if provided), holidays (list of {date: YYYY-MM-DD, name: str}, sorted ascending by date).

Raises: ValueError: on unknown country/subdiv.

List all countries supported by the holidays library, with subdivisions.

Use this as the discovery tool before calling any country-aware tool. It tells the agent which ISO country codes are valid AND which subdivision codes may be passed as the optional subdiv argument on other tools.

IMPORTANT: Subdivision codes are case-sensitive — use them verbatim as returned here. Country codes are case-insensitive.

Returns: dict with keys: - countries: list of {code: 2-letter ISO code, name: str, subdivisions: list[str]}, sorted by code. subdivisions is [] for countries without regional variants (e.g. JP), and may also be [] if the library raised an error while introspecting that country. - total: number of countries returned.

List subdivision codes and aliases for a country's holiday calendar.

Use this to discover valid subdiv values before calling any country-aware holiday tool (e.g. is_business_day, list_holidays, next_business_day).

IMPORTANT: Subdivision codes are case-sensitive and must be passed through subdiv exactly as returned here — either a canonical code from subdivisions or an alias key from aliases. Do NOT upper-case or otherwise normalize them.

Example: country="DE" returns "BY" among its subdivisions. Passing subdiv="BY" to list_holidays(year=2026, country="DE", subdiv="BY") then reveals Bavarian regional holidays such as Epiphany (Jan 6).

Args: country: ISO 3166-1 alpha-2 code (case-insensitive, normalized to upper).

Returns: dict with keys: - country: normalized uppercase code. - subdivisions: list of canonical subdivision codes (empty if the country has no regional variants, e.g. JP). - aliases: dict mapping alias (mixed-case, verbatim) → canonical code (empty dict if the country exposes no aliases).

Raises: ValueError: if country is unknown/unsupported.