Stop letting LLMs hallucinate dates — a tool for AI agents

Stop letting LLMs hallucinate dates — a tool for AI agents



Tópico: Stop letting LLMs hallucinate dates — a tool for AI agents
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
If you're building an AI agent that touches dates — booking flows, scheduling bots, "remind me on Friday" assistants — you've probably noticed:

LLMs are terrible at dates.

They hallucinate weekday-to-date mappings. They fencepost-error ranges. They forget what "next Friday" means in Ukrainian vs English. Asking the model to "be careful" doesn't fix it — what fixes it is moving date interpretation out of the model and into a deterministic tool.

That's what whenis is.



Use it as an agent tool


Define a resolveDate(expression, reference) tool that calls whenis. Let the model invoke it instead of guessing.

import { createParser } from '@whenis/core';
import { uk } from '@whenis/locale-uk';
import { booking } from '@whenis/booking';

const parser = createParser({
locales: [uk],
plugins: [booking],
options: { preferFuture: true },
});

const ref = new Date('2026-05-28');

parser.parse("наступної п'ятниці", { reference: ref });
// → { type: 'date', date: '2026-06-05', confidence: 1 }

parser.parse('з 5 по 10 червня', { reference: ref });
// → { type: 'range', start: '2026-06-05', end: '2026-06-11', nights: 6 }

parser.parse('після свят', { reference: ref });
// → { type: 'fuzzy', reason: 'holiday_ref',
//     metadata: { suggest_next_month: true } }

English works the same way:

import { en } from '@whenis/locale-en';

const parser = createParser({ locales: [en], options: { preferFuture: true } });

parser.parse('next Friday', { reference: new Date('2026-05-28') });
// → { type: 'date', date: '2026-06-05', confidence: 1 }



How it differs from chrono-node


•
Multi-candidate output. A bare "Friday" mid-week emits both this Friday and next Friday with confidence scores. Your agent re-ranks using conversation context — no silent guessing inside the library.

•
Locale as data. Adding RU/PL/CS is one source file with no engine changes. The Ukrainian locale ships full inflection: months × 7 cases, weekdays × 4 cases, pointers, connectors, time units.

•
Plugin API. Booking patterns (windows, durations, weekends, holidays) live in @whenis/booking, not the core. Build your own plugin for your domain.



Architecture


Duckling-style 4-layer pipeline:

input
↓
preprocess  →  tokenize + tag  →  rule engine  →  resolver
↓
ParseResult

Each layer is independently testable. The rule engine is iterative and compositional — rules match tokens or previously emitted IR nodes, looping until fixpoint.

The output is a ParseResult with matches[].candidates[] — each candidate has a type, ISO dates, optional nights, a confidence score, a human-readable reason, and a metadata bag plugins can extend.

ESM + CJS dual builds, strict TypeScript, Node ≥18, zero DOM dependencies.



Install


npm i @whenis/core @whenis/locale-uk @whenis/booking
# or just core + the locale you need
npm i @whenis/core @whenis/locale-en

@whenis/core is a peer dependency of every locale and plugin — install it explicitly so you control the version in one place.



Status and roadmap


v0.1 ships UA + EN locales and the booking plugin. v0.2 backlog: ISO passthrough rule, DD.MM numeric forms, Ukrainian word-numerals, до кінця тижня/місяця window, more English coverage. Issues and PRs welcome.

Repo: github.com/norens/whenis · MIT