Duration Parser

Interprets a wide spectrum of human-readable duration expressions and maps them to a single canonical representation. This eliminates ambiguity in obligation management systems.

• Input Variants Handled: 'thirty calendar days', 'one fiscal quarter', '2 weeks', 'a month', '3 business days'
• Canonical Output: Converts all variants to a standard like ISO 8601 duration (e.g., P30D) or a total number of seconds
• Lexical Normalization: Resolves synonyms ('a' vs. 'one'), abbreviations ('wks' to 'weeks'), and case sensitivity before parsing

Distinguishes between absolute calendar periods and periods measured in business days, applying the correct underlying calculation logic for each.

• Calendar Days: A simple count of all days, including weekends and holidays. '30 calendar days' from June 1st is July 1st
• Business Days: Excludes weekends and a configurable set of non-business days (holidays). '5 business days' from a Thursday is the following Thursday
• Holiday Calendar Integration: The parser must reference a jurisdiction-specific holiday calendar to accurately skip non-business days, a critical feature for legal deadlines

Resolves non-standard, organization-specific time units like fiscal quarters and years into precise date ranges based on a configurable fiscal calendar.

• Fiscal Year Mapping: Translates 'one fiscal year' into the correct start and end dates (e.g., Feb 1, 2024 – Jan 31, 2025) based on the entity's defined calendar
• Quarter Handling: Resolves 'Q3 2024' or 'the current fiscal quarter' into its exact date boundaries
• Custom Periods: Supports user-defined periods like 'a semester' or 'a retail period' by referencing a lookup table, ensuring the parser adapts to any enterprise's temporal definitions

Calculates durations relative to a specific, externally provided anchor date rather than assuming the current system time. This is fundamental for contractual analysis.

• Explicit Anchoring: The parser accepts a reference date (e.g., the 'Effective Date' of a contract) as a required input parameter
• Relative Computation: 'within 60 days of the Closing Date' is computed by adding 60 days to the parsed and normalized Closing Date anchor
• Stateful Context: In a multi-clause document, the parser maintains context to resolve phrases like '30 days thereafter' by chaining back to the previously calculated deadline

Provides configurable control over the precision of the output duration and applies standardized rounding rules to handle ambiguous edge cases.

• Configurable Precision: Output can be requested in days, hours, minutes, or seconds depending on the use case (e.g., a lease vs. a service-level agreement)
• Month-to-Day Conversion: Applies a defined convention for converting 'one month' into days (e.g., 30 days, or the exact number of days in the anchor month)
• Start-of-Day/End-of-Day Rules: Resolves whether a deadline falls at 00:00:00 or 23:59:59 on the calculated date, a critical detail for automated compliance checks

Gracefully handles malformed, ambiguous, or unparseable input by providing structured error feedback instead of failing silently or returning a guess.

• Structured Error Output: Returns a machine-readable error code (e.g., AMBIGUOUS_PERIOD, UNKNOWN_UNIT) along with the specific token that failed
• Ambiguity Detection: Flags phrases like 'within a quarter' (calendar or fiscal?) and requires disambiguation through configuration
• Bounds Checking: Validates that the resulting duration is within a reasonable, configurable range to catch input errors (e.g., a lease parsed as 10,000 years)