@stll/agent-input 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,401 @@
1
+ import { a as readValueAs, r as readAsAbsent, t as askForFix } from "./normalized-Kt_5vfXW.js";
2
+ import { foldToAscii } from "@stll/text-normalize";
3
+ import { Temporal, parsePlainDate } from "@stll/time";
4
+ //#region src/absent.ts
5
+ /**
6
+ * Placeholders on optional filters.
7
+ *
8
+ * A model fills every slot a schema shows it, so a filter it means to leave
9
+ * unset still arrives as `"any"`, `"-"` or `"none"`. Those words name no
10
+ * court, no type, no record: read as a value they match nothing and the call
11
+ * returns an empty page the model then explains away. The set is closed and
12
+ * short on purpose; a word outside it is a value and goes to the kind's own
13
+ * reader.
14
+ *
15
+ * This is not for free text. `"none"` is a fine answer to a question and `"-"`
16
+ * a fine clause body, so the caller decides which inputs a placeholder can
17
+ * stand in for.
18
+ */
19
+ /** The words, already in the folded lowercase form they are compared in. */
20
+ const ABSENT_PLACEHOLDERS = [
21
+ "-",
22
+ "--",
23
+ "–",
24
+ "—",
25
+ "*",
26
+ "all",
27
+ "any",
28
+ "none",
29
+ "null",
30
+ "nil",
31
+ "undefined",
32
+ "n/a",
33
+ "(none)",
34
+ "<none>",
35
+ "(any)",
36
+ "(all)"
37
+ ];
38
+ const PLACEHOLDERS = new Set(ABSENT_PLACEHOLDERS);
39
+ /** Whether a string stands for "no value" on an optional filter: blank, or one
40
+ * of the placeholder words in any case and spacing. */
41
+ const isAbsentPlaceholder = (input) => {
42
+ if (typeof input !== "string") return false;
43
+ const trimmed = input.trim();
44
+ return trimmed === "" || PLACEHOLDERS.has(foldToAscii(trimmed).toLowerCase());
45
+ };
46
+ //#endregion
47
+ //#region src/date-value.ts
48
+ /**
49
+ * Calendar dates on the agent wire.
50
+ *
51
+ * ISO `YYYY-MM-DD` is the canonical form and the only one a document may store,
52
+ * but a model drafting a Czech lease writes `1. 10. 2026` and one drafting an
53
+ * English one writes `October 1, 2026`. Those spellings carry one meaning each,
54
+ * so they are read.
55
+ *
56
+ * `01/02/2026` does not: it is 1 February under most of the world's convention
57
+ * and 2 January under the United States', and nothing inside the string decides
58
+ * which. A wrong date on an instrument is not a cosmetic defect, so an
59
+ * ambiguous spelling is asked about with both readings named rather than
60
+ * guessed from a default. Same for a two-digit year (`02-03-26`), which is
61
+ * ambiguous in the day/month order as well as the century.
62
+ *
63
+ * A range bound (`date_from`, `date_to`) reads more, because which end it is
64
+ * decides what a partial date means: `2020` as a start is 1 January and as an
65
+ * end is 31 December, and `0001-01-01` or `9999-12-31` is the model saying the
66
+ * range is open on that side. A single date is never read that way, since
67
+ * nothing tells a lone `2020` which day of the year it is.
68
+ */
69
+ const DATE_VALUE_EXPECTED = "a calendar date";
70
+ const DATE_VALUE_HINT = "Send the date as ISO YYYY-MM-DD (\"2026-10-01\"). The unambiguous spellings \"1. 10. 2026\", \"1 October 2026\" and \"October 1, 2026\" are read as well.";
71
+ /** Day-first with dots is one convention wherever it is written, so it needs
72
+ * no disambiguation: `1.10.2026`, `01. 10. 2026`, `1. 10. 2026.` */
73
+ const DOTTED_DAY_FIRST_RE = /^(?<day>\d{1,2})\.\s*(?<month>\d{1,2})\.\s*(?<year>\d{4})\.?$/u;
74
+ /** Year-first with any separator: the four-digit head fixes the order. */
75
+ const YEAR_FIRST_RE = /^(?<year>\d{4})[-./]\s*(?<month>\d{1,2})[-./]\s*(?<day>\d{1,2})\.?$/u;
76
+ /** Slash- or dash-separated with a four-digit year at the end: the day/month
77
+ * order still has to be decided. */
78
+ const YEAR_LAST_RE = /^(?<first>\d{1,2})[/-](?<second>\d{1,2})[/-](?<year>\d{4})$/u;
79
+ /** An ISO datetime: the date part is the calendar date it names. */
80
+ const ISO_DATETIME_RE = /^(?<date>\d{4}-\d{2}-\d{2})[T ]\S*/u;
81
+ /** `1 October 2026`, `1. října 2026`, `1st October 2026`. */
82
+ const DAY_MONTH_YEAR_RE = /^(?<day>\d{1,2})(?:st|nd|rd|th)?\.?\s+(?<month>\p{L}+\.?)\s+(?<year>\d{4})$/u;
83
+ /** `October 1, 2026`, `Oct. 1 2026`. */
84
+ const MONTH_DAY_YEAR_RE = /^(?<month>\p{L}+\.?)\s+(?<day>\d{1,2})(?:st|nd|rd|th)?,?\s+(?<year>\d{4})$/u;
85
+ const MAX_MONTH = 12;
86
+ const pad = (value) => String(value).padStart(2, "0");
87
+ /** The ISO spelling of a real calendar date, or null. */
88
+ const isoDate = (year, month, day) => parsePlainDate(`${String(year).padStart(4, "0")}-${pad(month)}-${pad(day)}`)?.toString() ?? null;
89
+ /** A month name folded to the form the tables below are keyed by: lowercase,
90
+ * no trailing abbreviation dot, diacritics kept (they distinguish nothing a
91
+ * model gets wrong, and ICU emits them). */
92
+ const foldMonthName = (name) => name.toLowerCase().replace(/\.$/u, "").trim();
93
+ /**
94
+ * Month names for one locale, in both the standalone form (`říjen`) and the
95
+ * form ICU uses inside a full date (`října`, the Czech genitive), long and
96
+ * abbreviated. Built from `Intl`, so a locale's names never have to be
97
+ * hand-listed.
98
+ */
99
+ const monthNamesFor = (locale) => {
100
+ const names = /* @__PURE__ */ new Map();
101
+ const record = (name, month) => {
102
+ if (name !== void 0 && /\p{L}/u.test(name)) names.set(foldMonthName(name), month);
103
+ };
104
+ for (const style of ["long", "short"]) {
105
+ const standalone = new Intl.DateTimeFormat(locale, {
106
+ month: style,
107
+ timeZone: "UTC"
108
+ });
109
+ const inDate = new Intl.DateTimeFormat(locale, {
110
+ day: "numeric",
111
+ month: style,
112
+ year: "numeric",
113
+ timeZone: "UTC"
114
+ });
115
+ for (let month = 1; month <= MAX_MONTH; month += 1) {
116
+ const instant = Temporal.PlainDate.from({
117
+ year: 2026,
118
+ month,
119
+ day: 15
120
+ }).toZonedDateTime("UTC").epochMilliseconds;
121
+ record(standalone.format(instant), month);
122
+ record(inDate.formatToParts(instant).find((part) => part.type === "month")?.value, month);
123
+ }
124
+ }
125
+ return names;
126
+ };
127
+ const monthNameCache = /* @__PURE__ */ new Map();
128
+ const monthNumber = (name, locales) => {
129
+ const folded = foldMonthName(name);
130
+ for (const locale of locales) {
131
+ const cached = monthNameCache.get(locale) ?? monthNamesFor(locale);
132
+ monthNameCache.set(locale, cached);
133
+ const month = cached.get(folded);
134
+ if (month !== void 0) return month;
135
+ }
136
+ return null;
137
+ };
138
+ const readNamedMonth = (spec, locales) => {
139
+ const groups = (DAY_MONTH_YEAR_RE.exec(spec) ?? MONTH_DAY_YEAR_RE.exec(spec))?.groups;
140
+ if (groups === void 0) return null;
141
+ const month = monthNumber(groups["month"] ?? "", locales);
142
+ return month === null ? null : {
143
+ year: Number(groups["year"]),
144
+ month,
145
+ day: Number(groups["day"])
146
+ };
147
+ };
148
+ const readNumeric = (spec) => {
149
+ const groups = (DOTTED_DAY_FIRST_RE.exec(spec) ?? YEAR_FIRST_RE.exec(spec))?.groups;
150
+ return groups === void 0 ? null : {
151
+ year: Number(groups["year"]),
152
+ month: Number(groups["month"]),
153
+ day: Number(groups["day"])
154
+ };
155
+ };
156
+ /** The month styles a date field renders in, and therefore the structures a
157
+ * model copies back out of the document. */
158
+ const READ_MONTH_STYLES = ["long", "short"];
159
+ /** The instant every locale probe is formatted at: a two-digit day and a
160
+ * two-digit month, so no part of the layout is a single character by
161
+ * accident. */
162
+ const LAYOUT_PROBE = Temporal.PlainDate.from("2026-10-15").toZonedDateTime("UTC").epochMilliseconds;
163
+ /** Separators alone. A layout whose month is numeric and whose literals are
164
+ * only these is `01/02/2026` with one locale's ordering imposed on it, which
165
+ * is the reading this module refuses to guess. */
166
+ const SEPARATORS_ONLY_RE = /^[\s./,-]*$/u;
167
+ const REGEXP_META_RE = /[.*+?^${}()|[\]\\]/gu;
168
+ /** A literal ICU emits between the parts (`. `, ` de `, `年`), matched with the
169
+ * whitespace around it left to the writer. */
170
+ const literalPattern = (literal) => literal.split(/\s+/u).map((chunk) => chunk.replace(REGEXP_META_RE, (meta) => `\\${meta}`)).join(String.raw`\s*`);
171
+ /** The parts a calendar-date layout is built from. A formatter asked for a
172
+ * day, a month and a year emits nothing else; anything else means the layout
173
+ * is not one this reader can rebuild. */
174
+ const LAYOUT_PART_KINDS = [
175
+ "day",
176
+ "month",
177
+ "year",
178
+ "literal"
179
+ ];
180
+ const layoutPartKind = (type) => LAYOUT_PART_KINDS.find((kind) => kind === type) ?? null;
181
+ /**
182
+ * The date structures one locale actually renders, as patterns: ICU's own
183
+ * ordering and its own literals, so `1 de outubro de 2026` and
184
+ * `2026. október 1.` are read where the field renders them that way. A layout
185
+ * whose month is a number separated by nothing but punctuation is dropped: it
186
+ * carries the day/month ambiguity this module never guesses at.
187
+ */
188
+ const localeLayouts = (locale) => {
189
+ const layouts = [];
190
+ for (const month of READ_MONTH_STYLES) {
191
+ const parts = new Intl.DateTimeFormat(locale, {
192
+ day: "numeric",
193
+ month,
194
+ year: "numeric",
195
+ timeZone: "UTC"
196
+ }).formatToParts(LAYOUT_PROBE);
197
+ let source = "";
198
+ let literals = "";
199
+ let named = false;
200
+ let readable = true;
201
+ for (const part of parts) {
202
+ const kind = layoutPartKind(part.type);
203
+ if (kind === null) {
204
+ readable = false;
205
+ continue;
206
+ }
207
+ switch (kind) {
208
+ case "day":
209
+ source += String.raw`(?<day>\d{1,2})`;
210
+ break;
211
+ case "year":
212
+ source += String.raw`(?<year>\d{4})`;
213
+ break;
214
+ case "month":
215
+ named = /\p{L}/u.test(part.value);
216
+ source += named ? String.raw`(?<month>[\p{L}\p{M}]+\.?)` : String.raw`(?<month>\d{1,2})`;
217
+ break;
218
+ case "literal":
219
+ literals += part.value;
220
+ source += literalPattern(part.value);
221
+ }
222
+ }
223
+ if (readable && (named || !SEPARATORS_ONLY_RE.test(literals))) layouts.push(new RegExp(String.raw`^\s*${source}\s*$`, "u"));
224
+ }
225
+ return layouts;
226
+ };
227
+ const layoutCache = /* @__PURE__ */ new Map();
228
+ const NUMERIC_RE = /^\d+$/u;
229
+ const readLocaleLayout = (spec, locales) => {
230
+ for (const locale of locales) {
231
+ const layouts = layoutCache.get(locale) ?? localeLayouts(locale);
232
+ layoutCache.set(locale, layouts);
233
+ for (const layout of layouts) {
234
+ const groups = layout.exec(spec)?.groups;
235
+ if (groups === void 0) continue;
236
+ const spelled = groups["month"] ?? "";
237
+ const month = NUMERIC_RE.test(spelled) ? Number(spelled) : monthNumber(spelled, [locale]);
238
+ if (month !== null) return {
239
+ year: Number(groups["year"]),
240
+ month,
241
+ day: Number(groups["day"])
242
+ };
243
+ }
244
+ }
245
+ return null;
246
+ };
247
+ /** English is always read: it is the language of the schema and of most model
248
+ * output, whatever the document's own language is. */
249
+ const readingLocales = (options) => ["en", ...options?.locales ?? []];
250
+ const invalidAsk = (input) => askForFix({
251
+ input,
252
+ expected: DATE_VALUE_EXPECTED,
253
+ hint: DATE_VALUE_HINT
254
+ });
255
+ /** Both readings of a day/month pair, named, so the ask carries the fix rather
256
+ * than a rule the model has to look up. */
257
+ const ambiguousAsk = ({ input, first, second, year }) => {
258
+ const dayFirst = isoDate(year, second, first);
259
+ const monthFirst = isoDate(year, first, second);
260
+ if (dayFirst === null || monthFirst === null) return invalidAsk(input);
261
+ return askForFix({
262
+ input,
263
+ expected: DATE_VALUE_EXPECTED,
264
+ hint: `That reads as ${dayFirst} with the day first, or ${monthFirst} with the month first. Send "${dayFirst}" or "${monthFirst}".`
265
+ });
266
+ };
267
+ /** One whole calendar date, the reading every field shares. */
268
+ const readCalendarDate = (input, options) => {
269
+ if (typeof input !== "string") return invalidAsk(input);
270
+ const trimmed = input.trim();
271
+ if (trimmed === "") return invalidAsk(input);
272
+ const spec = ISO_DATETIME_RE.exec(trimmed)?.groups?.["date"] ?? trimmed;
273
+ const locales = readingLocales(options);
274
+ const unambiguous = readNumeric(spec) ?? readNamedMonth(spec, locales) ?? readLocaleLayout(spec, locales);
275
+ if (unambiguous !== null) {
276
+ const iso = isoDate(unambiguous.year, unambiguous.month, unambiguous.day);
277
+ return iso === null ? invalidAsk(input) : readValueAs(input, iso);
278
+ }
279
+ const yearLast = YEAR_LAST_RE.exec(spec)?.groups;
280
+ if (yearLast === void 0) return invalidAsk(input);
281
+ const first = Number(yearLast["first"]);
282
+ const second = Number(yearLast["second"]);
283
+ const year = Number(yearLast["year"]);
284
+ if (first > MAX_MONTH && second <= MAX_MONTH) {
285
+ const iso = isoDate(year, second, first);
286
+ return iso === null ? invalidAsk(input) : readValueAs(input, iso);
287
+ }
288
+ if (second > MAX_MONTH && first <= MAX_MONTH) {
289
+ const iso = isoDate(year, first, second);
290
+ return iso === null ? invalidAsk(input) : readValueAs(input, iso);
291
+ }
292
+ if (first > MAX_MONTH && second > MAX_MONTH) return invalidAsk(input);
293
+ if (first === second) {
294
+ const iso = isoDate(year, first, second);
295
+ return iso === null ? invalidAsk(input) : readValueAs(input, iso);
296
+ }
297
+ return ambiguousAsk({
298
+ input,
299
+ first,
300
+ second,
301
+ year
302
+ });
303
+ };
304
+ const YEAR_ONLY_RE = /^(?<year>\d{4})$/u;
305
+ /** `2020-05`, `2020/5`: the four-digit head fixes which part is the year. */
306
+ const YEAR_MONTH_RE = /^(?<year>\d{4})[-/](?<month>\d{1,2})$/u;
307
+ /** `05/2020`, `5/2020`, `05.2020`: the four-digit tail fixes it the same way. */
308
+ const MONTH_YEAR_RE = /^(?<month>\d{1,2})[-/.]\s*(?<year>\d{4})$/u;
309
+ /**
310
+ * A bare year or month as the first or last day it covers. Only a bound reads
311
+ * these: as a start, `2020` means from the first day of 2020, and as an end,
312
+ * through its last, which is what a model filtering "decisions from 2020"
313
+ * means by it.
314
+ */
315
+ const readPartialDate = (trimmed, bound) => {
316
+ const yearOnly = YEAR_ONLY_RE.exec(trimmed)?.groups;
317
+ if (yearOnly !== void 0) {
318
+ const year = Number(yearOnly["year"]);
319
+ return bound === "start" ? isoDate(year, 1, 1) : isoDate(year, 12, 31);
320
+ }
321
+ const groups = (YEAR_MONTH_RE.exec(trimmed) ?? MONTH_YEAR_RE.exec(trimmed))?.groups;
322
+ if (groups === void 0) return null;
323
+ const year = Number(groups["year"]);
324
+ const month = Number(groups["month"]);
325
+ const first = isoDate(year, month, 1);
326
+ if (first === null || bound === "start") return first;
327
+ return isoDate(year, month, Temporal.PlainDate.from(first).daysInMonth);
328
+ };
329
+ /** How a model writes both ends of a range in one string, matched on the
330
+ * string with its whitespace runs collapsed to one space (halves are trimmed
331
+ * after the split), so no separator backtracks over a run of whitespace. The
332
+ * unspaced dash and the slash split only where both halves are dates on
333
+ * their own, so a single `2020-05` or `5/2020` never reads as two. */
334
+ const RANGE_SEPARATORS = [
335
+ /\.\./u,
336
+ /[–—]/u,
337
+ / to /iu,
338
+ / - /u,
339
+ /\//u,
340
+ /-/u
341
+ ];
342
+ const WHITESPACE_RUN_RE = /\s+/gu;
343
+ /** One bound read on its own: a whole date, else a partial one. */
344
+ const readBoundHalf = (half, bound, options) => {
345
+ const whole = readCalendarDate(half, options);
346
+ return whole.ok ? whole.value : readPartialDate(half, bound);
347
+ };
348
+ /** Both ends of a range, when the string is one written into a single bound. */
349
+ const readRange = (trimmed, options) => {
350
+ const spaced = trimmed.replace(WHITESPACE_RUN_RE, " ");
351
+ for (const separator of RANGE_SEPARATORS) {
352
+ const halves = spaced.split(separator).map((half) => half.trim());
353
+ const [left, right] = halves;
354
+ if (halves.length !== 2 || left === void 0 || right === void 0) continue;
355
+ const start = readBoundHalf(left, "start", options);
356
+ const end = readBoundHalf(right, "end", options);
357
+ if (start !== null && end !== null) return {
358
+ start,
359
+ end
360
+ };
361
+ }
362
+ return null;
363
+ };
364
+ const rangeAsk = (input, range) => askForFix({
365
+ input,
366
+ expected: "a single date",
367
+ hint: `This is one bound of a range: send the start and the end as two separate date properties (for example date_from "${range.start}" and date_to "${range.end}").`
368
+ });
369
+ /** Read a calendar date an agent spelled its own way, as ISO YYYY-MM-DD. With
370
+ * a `bound`, a bare year or month reads as that end's day, and a whole range
371
+ * in the one field asks for its two halves. */
372
+ const normalizeDateValue = (input, options) => {
373
+ const bound = options?.bound;
374
+ if (bound === void 0 || typeof input !== "string") return readCalendarDate(input, options);
375
+ const trimmed = input.trim();
376
+ const range = readRange(trimmed, options);
377
+ if (range !== null) return rangeAsk(input, range);
378
+ const whole = readCalendarDate(input, options);
379
+ if (whole.ok) return whole;
380
+ const partial = readPartialDate(trimmed, bound);
381
+ return partial === null ? whole : readValueAs(input, partial);
382
+ };
383
+ /** Years no range filter means literally: `0001-01-01` and `9999-12-31` are
384
+ * how a database and a model spell "no limit on this side". Year 1000 is kept,
385
+ * since a medieval charter is a real bound in a legal corpus. */
386
+ const OPEN_BOUND_YEAR_BELOW = 1e3;
387
+ const OPEN_BOUND_YEAR_FROM = 9e3;
388
+ /**
389
+ * Read one end of a date range. A placeholder or an open-ended sentinel date
390
+ * is no bound at all, so the caller drops the property rather than filtering
391
+ * to the year 1 or 9999.
392
+ */
393
+ const normalizeDateBound = (input, options) => {
394
+ if (isAbsentPlaceholder(input)) return readAsAbsent(input);
395
+ const result = normalizeDateValue(input, options);
396
+ if (!result.ok) return result;
397
+ const year = Temporal.PlainDate.from(result.value).year;
398
+ return year < OPEN_BOUND_YEAR_BELOW || year >= OPEN_BOUND_YEAR_FROM ? readAsAbsent(input, "an open bound") : result;
399
+ };
400
+ //#endregion
401
+ export { isAbsentPlaceholder as a, ABSENT_PLACEHOLDERS as i, normalizeDateBound as n, normalizeDateValue as r, DATE_VALUE_HINT as t };
@@ -0,0 +1,30 @@
1
+ import { i as NormalizedOptional, t as Normalized } from "./normalized-B9RxhmIz.js";
2
+ //#region src/date-value.d.ts
3
+ export declare const DATE_VALUE_HINT: string;
4
+ export type DateValueOptions = {
5
+ /** Locales to read besides English: the field's own `dateFormat` locale, so
6
+ * a document rendered in Czech accepts a Czech month name back, and one
7
+ * rendered in Portuguese accepts `1 de outubro de 2026` — the structure
8
+ * that locale renders, not only its month names. */
9
+ locales?: readonly string[] | undefined;
10
+ /** Which end of a range the date is. A bound reads a bare year or month as
11
+ * that end's first or last day, and asks when both ends arrive in one
12
+ * field. */
13
+ bound?: DateBound | undefined;
14
+ };
15
+ export type DateBound = "start" | "end";
16
+ /** Read a calendar date an agent spelled its own way, as ISO YYYY-MM-DD. With
17
+ * a `bound`, a bare year or month reads as that end's day, and a whole range
18
+ * in the one field asks for its two halves. */
19
+ export declare const normalizeDateValue: (input: unknown, options?: DateValueOptions) => Normalized<string>;
20
+ export type DateBoundOptions = {
21
+ bound: DateBound;
22
+ locales?: readonly string[] | undefined;
23
+ };
24
+ /**
25
+ * Read one end of a date range. A placeholder or an open-ended sentinel date
26
+ * is no bound at all, so the caller drops the property rather than filtering
27
+ * to the year 1 or 9999.
28
+ */
29
+ export declare const normalizeDateBound: (input: unknown, options: DateBoundOptions) => NormalizedOptional<string>;
30
+ //#endregion
@@ -0,0 +1 @@
1
+ export { t as DATE_VALUE_HINT, n as normalizeDateBound, r as normalizeDateValue } from "./date-value-CXL60jnN.js";
package/dist/index.d.ts CHANGED
@@ -1,4 +1,8 @@
1
- import { CountryAlpha3Code, CountryCode } from "@stll/country-codes";
1
+ import { a as askForFix, i as NormalizedOptional, n as NormalizedAbsent, o as askSentence, r as NormalizedAsk, s as readAsAbsent, t as Normalized } from "./normalized-B9RxhmIz.js";
2
+ import { COUNTRY_INPUT_MAX_CHARS, CountryAlpha2, CountryAlpha3, CountryOptions, CountrySpelling, CountryValue, countryCodeIn, normalizeCountry } from "./country.js";
3
+ import { DATE_VALUE_HINT, DateBound, DateBoundOptions, DateValueOptions, normalizeDateBound, normalizeDateValue } from "./date-value.js";
4
+ import { isPlausibleLocale, normalizeLocale } from "./locale.js";
5
+ import { StringListOptions, normalizeStringList } from "./string-list.js";
2
6
  import { DateFormatStyle } from "@stll/template-conditions";
3
7
  //#region src/absent.d.ts
4
8
  /**
@@ -21,135 +25,10 @@ export declare const ABSENT_PLACEHOLDERS: readonly ["-", "--", "–", "—", "*"
21
25
  * of the placeholder words in any case and spacing. */
22
26
  export declare const isAbsentPlaceholder: (input: unknown) => boolean;
23
27
  //#endregion
24
- //#region src/normalized.d.ts
25
- /**
26
- * One shape for every value an agent spells its own way.
27
- *
28
- * Models copy examples, translate, and reach for the notation their training
29
- * data used most: a date arrives as `1. 10. 2026`, a number as `4 000`, a
30
- * boolean as `ano`, a locale as `cs_CZ`. Each kind in this directory reads the
31
- * spellings that carry one meaning and asks for a fix when a spelling carries
32
- * two, so no call site grows its own parser or its own wording.
33
- *
34
- * `ok: true` is the canonical value, with `note` set when the input had to be
35
- * read rather than taken verbatim (surface it as a warning, never as an
36
- * error). `ok: false` is the single ask-for-a-fix shape: `expected` names the
37
- * canonical form and `hint` names the one call to make. Callers render those
38
- * two rather than composing wording of their own, which is what keeps one kind
39
- * answering the same way on every surface.
40
- */
41
- /** The one ask-for-a-fix shape. */
42
- type NormalizedAsk = {
43
- ok: false;
44
- /** The input as the agent sent it, quoted and bounded. */
45
- received: string;
46
- /** The canonical form as a noun phrase: "a calendar date". */
47
- expected: string;
48
- /** The corrective call, spelled out. */
49
- hint: string;
50
- };
51
- type Normalized<TValue> = {
52
- ok: true;
53
- value: TValue;
54
- note?: string;
55
- } | NormalizedAsk;
56
- export declare const askForFix: ({ input, expected, hint }: {
57
- input: unknown;
58
- expected: string;
59
- hint: string;
60
- }) => NormalizedAsk;
61
- /** The ask as one sentence, for a caller whose issue shape carries a message
62
- * beside the hint. */
63
- export declare const askSentence: (ask: NormalizedAsk) => string;
64
- /**
65
- * The input read as no value at all.
66
- *
67
- * An optional filter the agent is not setting still arrives filled in: `"any"`,
68
- * `"-"`, the nil uuid, `9999-12-31` as an open bound. Each of those means "not
69
- * filtering", and asking about it would send the model back to delete a value
70
- * it only wrote because the schema had a slot. Only a reader that can see a
71
- * placeholder returns this, and only on inputs the caller marked optional; the
72
- * caller drops the property and surfaces `note` as a warning.
73
- */
74
- type NormalizedAbsent = {
75
- ok: "absent";
76
- /** The input as the agent sent it, quoted and bounded. */
77
- received: string;
78
- note: string;
79
- };
80
- /** A reader's outcome on an optional input, where a placeholder is no value. */
81
- type NormalizedOptional<TValue> = Normalized<TValue> | NormalizedAbsent;
82
- /** The absent outcome, with the one "read X as no value" sentence every kind
83
- * reports it with. `reason` says why, when the spelling alone does not. */
84
- export declare const readAsAbsent: (input: unknown, reason?: string) => NormalizedAbsent;
85
- //#endregion
86
28
  //#region src/boolean.d.ts
87
29
  /** Read a yes/no answer an agent spelled its own way. */
88
30
  export declare const normalizeBoolean: (input: unknown) => Normalized<boolean>;
89
31
  //#endregion
90
- //#region src/country.d.ts
91
- /**
92
- * Jurisdictions that publish law without being ISO 3166-1 countries.
93
- *
94
- * The EU is the one this corpus holds: the Court of Justice and the Official
95
- * Journal are supranational, and legal corpora and ELI identifiers spell that
96
- * jurisdiction `EU`. CLDR carries `EU` as a region, so its names arrive from
97
- * the same place as a country's, and ISO assigns it neither alpha-2 nor
98
- * alpha-3, so `EU` is both.
99
- */
100
- declare const SUPRANATIONAL_CODES: readonly ["EU"];
101
- type SupranationalCode = (typeof SUPRANATIONAL_CODES)[number];
102
- /** A canonical alpha-3 code, or the supranational code ISO leaves unassigned. */
103
- type CountryAlpha3 = CountryAlpha3Code | SupranationalCode;
104
- /** A canonical alpha-2 (CLDR region) code, or the supranational code. */
105
- type CountryAlpha2 = CountryCode | SupranationalCode;
106
- /**
107
- * One country, in both spellings a consumer might store.
108
- *
109
- * Both are returned because both are canonical somewhere: the corpus keys on
110
- * alpha-3, and a practice-jurisdiction row and every CLDR lookup key on
111
- * alpha-2. A caller picks the one its column holds instead of converting.
112
- */
113
- type CountryValue = {
114
- readonly alpha3: CountryAlpha3;
115
- readonly alpha2: CountryAlpha2;
116
- };
117
- /**
118
- * The longest country spelling a wire schema accepts.
119
- *
120
- * A country's own name is a spelling this reader reads, so the bound is a
121
- * name's length rather than a code's: `Federal Republic of Germany` is a
122
- * country input, and a schema capped at three characters was what turned it
123
- * into a rejection before the reader ever saw it. It lives with the reader so
124
- * the declared bound and what can be read cannot drift apart.
125
- */
126
- export declare const COUNTRY_INPUT_MAX_CHARS = 64;
127
- /** Which ISO spelling the calling surface stores. */
128
- type CountrySpelling = "alpha-3" | "alpha-2";
129
- type CountryOptions = {
130
- /** The spelling the caller keeps, which decides how a coercion is reported:
131
- * a surface storing alpha-2 must not be told its `CZ` was read as `CZE`. */
132
- spelling?: CountrySpelling | undefined;
133
- /** The canonical codes the calling surface holds law for, named in the ask so
134
- * a model that guessed wrong can see what there is to ask for. */
135
- admitted?: readonly string[] | undefined;
136
- /** The tool whose input this is, so the ask names the call to change. */
137
- tool?: string | undefined;
138
- /** The property name, which differs between surfaces (`country`,
139
- * `country_code`). */
140
- parameter?: string | undefined;
141
- };
142
- /** The code a caller keeping `spelling` stores. */
143
- export declare const countryCodeIn: (value: CountryValue, spelling?: CountrySpelling) => string;
144
- /**
145
- * Read a country an agent spelled its own way.
146
- *
147
- * An absent value asks rather than defaulting: a corpus country decides which
148
- * body of law is searched, and picking one on the model's behalf answers a
149
- * question about Czech law with Slovak decisions.
150
- */
151
- export declare const normalizeCountry: (input: unknown, options?: CountryOptions) => Normalized<CountryValue>;
152
- //#endregion
153
32
  //#region src/date-format-spec.d.ts
154
33
  type DateFormatSpec = {
155
34
  locale: string;
@@ -160,35 +39,6 @@ export declare const DATE_FORMAT_SPEC_HINT: string;
160
39
  * the wire object. */
161
40
  export declare const normalizeDateFormatSpec: (input: unknown) => Normalized<DateFormatSpec>;
162
41
  //#endregion
163
- //#region src/date-value.d.ts
164
- export declare const DATE_VALUE_HINT: string;
165
- type DateValueOptions = {
166
- /** Locales to read besides English: the field's own `dateFormat` locale, so
167
- * a document rendered in Czech accepts a Czech month name back, and one
168
- * rendered in Portuguese accepts `1 de outubro de 2026` — the structure
169
- * that locale renders, not only its month names. */
170
- locales?: readonly string[] | undefined;
171
- /** Which end of a range the date is. A bound reads a bare year or month as
172
- * that end's first or last day, and asks when both ends arrive in one
173
- * field. */
174
- bound?: DateBound | undefined;
175
- };
176
- type DateBound = "start" | "end";
177
- /** Read a calendar date an agent spelled its own way, as ISO YYYY-MM-DD. With
178
- * a `bound`, a bare year or month reads as that end's day, and a whole range
179
- * in the one field asks for its two halves. */
180
- export declare const normalizeDateValue: (input: unknown, options?: DateValueOptions) => Normalized<string>;
181
- type DateBoundOptions = {
182
- bound: DateBound;
183
- locales?: readonly string[] | undefined;
184
- };
185
- /**
186
- * Read one end of a date range. A placeholder or an open-ended sentinel date
187
- * is no bound at all, so the caller drops the property rather than filtering
188
- * to the year 1 or 9999.
189
- */
190
- export declare const normalizeDateBound: (input: unknown, options: DateBoundOptions) => NormalizedOptional<string>;
191
- //#endregion
192
42
  //#region src/eli.d.ts
193
43
  type EliOptions = {
194
44
  /** ELI jurisdiction segment (lowercase, `"cz"`) to the publisher origin
@@ -222,17 +72,6 @@ type EnumValueOptions = {
222
72
  */
223
73
  export declare const normalizeEnumValue: <TValue extends string>(input: unknown, allowed: readonly TValue[], options?: EnumValueOptions) => Normalized<TValue>;
224
74
  //#endregion
225
- //#region src/locale.d.ts
226
- /**
227
- * Whether a tag is already the spelling `Intl` accepts. This is the check a
228
- * stored or advertised locale passes: a value that reaches
229
- * `Intl.DateTimeFormat` at fill time must not be able to make it throw, so the
230
- * leniency below stops at the boundary and never reaches persistence.
231
- */
232
- export declare const isPlausibleLocale: (value: string) => boolean;
233
- /** Read a locale an agent spelled its own way, canonically. */
234
- export declare const normalizeLocale: (input: unknown) => Normalized<string>;
235
- //#endregion
236
75
  //#region src/number.d.ts
237
76
  type NumberOptions = {
238
77
  /** The field's locale, when one is configured. It decides `1,234`. */
@@ -257,19 +96,6 @@ type NumberInRangeOptions = NumberOptions & {
257
96
  */
258
97
  export declare const normalizeNumberInRange: (input: unknown, options: NumberInRangeOptions) => Normalized<number>;
259
98
  //#endregion
260
- //#region src/string-list.d.ts
261
- type StringListOptions = {
262
- /** `"delimiters"` splits a scalar on commas, semicolons and newlines, for
263
- * items that cannot contain them (ids, codes). `"never"` wraps a scalar as
264
- * one item, for free text that may. */
265
- split: "never" | "delimiters";
266
- };
267
- /** Read a list of strings an agent spelled its own way. Only the list's own
268
- * shape is read here: an array is taken as it is, and one holding anything
269
- * but strings asks, since what an item should have been is the item's
270
- * question, not the list's. */
271
- export declare const normalizeStringList: (input: unknown, options: StringListOptions) => Normalized<string[]>;
272
- //#endregion
273
99
  //#region src/uuid.d.ts
274
100
  /** Documentation uuids a model reproduces when it has no real id: RFC 4122
275
101
  * and RFC 9562 examples, and the ones tutorials and SDK docs print. */
@@ -417,4 +243,4 @@ export declare const normalizeAgentInput: ({ path, placeholders, readers, schema
417
243
  value: unknown;
418
244
  }) => AgentInputNormalizationResult;
419
245
  //#endregion
420
- export type { AgentInputCountryAnnotation, AgentInputNormalizationAnnotation, AgentInputNormalizationIssue, AgentInputNormalizationKind, AgentInputNormalizationResult, AgentInputPlaceholderPolicy, AgentInputReaders, CountryAlpha2, CountryAlpha3, CountryOptions, CountrySpelling, CountryValue, DateBound, DateBoundOptions, DateValueOptions, EliOptions, Normalized, NormalizedAbsent, NormalizedAsk, NormalizedOptional, NumberInRangeOptions, NumberOptions, StringListOptions, UuidOptions, VocabularyEntry, VocabularyOptions };
246
+ export { type AgentInputCountryAnnotation, type AgentInputNormalizationAnnotation, type AgentInputNormalizationIssue, type AgentInputNormalizationKind, type AgentInputNormalizationResult, type AgentInputPlaceholderPolicy, type AgentInputReaders, COUNTRY_INPUT_MAX_CHARS, type CountryAlpha2, type CountryAlpha3, type CountryOptions, type CountrySpelling, type CountryValue, DATE_VALUE_HINT, type DateBound, type DateBoundOptions, type DateValueOptions, type EliOptions, type Normalized, type NormalizedAbsent, type NormalizedAsk, type NormalizedOptional, type NumberInRangeOptions, type NumberOptions, type StringListOptions, type UuidOptions, type VocabularyEntry, type VocabularyOptions, askForFix, askSentence, countryCodeIn, isPlausibleLocale, normalizeCountry, normalizeDateBound, normalizeDateValue, normalizeLocale, normalizeStringList, readAsAbsent };