@stll/agent-input 0.1.6 → 0.1.8
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.
- package/README.md +8 -1
- package/dist/country.d.ts +65 -0
- package/dist/country.js +233 -0
- package/dist/date-value-CXL60jnN.js +401 -0
- package/dist/date-value.d.ts +30 -0
- package/dist/date-value.js +1 -0
- package/dist/index.d.ts +6 -180
- package/dist/index.js +7 -788
- package/dist/locale.d.ts +12 -0
- package/dist/locale.js +48 -0
- package/dist/normalized-B9RxhmIz.d.ts +63 -0
- package/dist/normalized-Kt_5vfXW.js +54 -0
- package/dist/string-list.d.ts +14 -0
- package/dist/string-list.js +42 -0
- package/package.json +19 -3
package/README.md
CHANGED
|
@@ -8,7 +8,14 @@ One reader per value kind that reaches a tool input, a template marker, or a
|
|
|
8
8
|
fill value. Each reads the spellings that carry a single meaning (`4 000`,
|
|
9
9
|
`1. 10. 2026`, `ano`, `cs_CZ`, `Česko`) and returns the one ask-for-a-fix shape
|
|
10
10
|
when a spelling carries two (`01/02/2026`, a bare `1,234`, a bare `cs`), so no
|
|
11
|
-
call site grows its own parser or its own wording.
|
|
11
|
+
call site grows its own parser or its own wording. Closed enum near-miss
|
|
12
|
+
suggestions count Unicode scalar values, so astral characters such as emoji
|
|
13
|
+
count as one edit.
|
|
14
|
+
|
|
15
|
+
Browser bundles can import the pure readers directly from `@stll/agent-input/country`,
|
|
16
|
+
`@stll/agent-input/date-value`, `@stll/agent-input/locale`, and
|
|
17
|
+
`@stll/agent-input/string-list` without pulling in the enum reader's native
|
|
18
|
+
fuzzy-search dependency.
|
|
12
19
|
|
|
13
20
|
`normalizeCountry` reads ISO 3166-1 alpha-3 and alpha-2 codes and the country's
|
|
14
21
|
name in each language the corpus serves, and returns both canonical spellings so
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { t as Normalized } from "./normalized-B9RxhmIz.js";
|
|
2
|
+
import { CountryAlpha3Code, CountryCode } from "@stll/country-codes";
|
|
3
|
+
//#region src/country.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Jurisdictions that publish law without being ISO 3166-1 countries.
|
|
6
|
+
*
|
|
7
|
+
* The EU is the one this corpus holds: the Court of Justice and the Official
|
|
8
|
+
* Journal are supranational, and legal corpora and ELI identifiers spell that
|
|
9
|
+
* jurisdiction `EU`. CLDR carries `EU` as a region, so its names arrive from
|
|
10
|
+
* the same place as a country's, and ISO assigns it neither alpha-2 nor
|
|
11
|
+
* alpha-3, so `EU` is both.
|
|
12
|
+
*/
|
|
13
|
+
declare const SUPRANATIONAL_CODES: readonly ["EU"];
|
|
14
|
+
type SupranationalCode = (typeof SUPRANATIONAL_CODES)[number];
|
|
15
|
+
/** A canonical alpha-3 code, or the supranational code ISO leaves unassigned. */
|
|
16
|
+
export type CountryAlpha3 = CountryAlpha3Code | SupranationalCode;
|
|
17
|
+
/** A canonical alpha-2 (CLDR region) code, or the supranational code. */
|
|
18
|
+
export type CountryAlpha2 = CountryCode | SupranationalCode;
|
|
19
|
+
/**
|
|
20
|
+
* One country, in both spellings a consumer might store.
|
|
21
|
+
*
|
|
22
|
+
* Both are returned because both are canonical somewhere: the corpus keys on
|
|
23
|
+
* alpha-3, and a practice-jurisdiction row and every CLDR lookup key on
|
|
24
|
+
* alpha-2. A caller picks the one its column holds instead of converting.
|
|
25
|
+
*/
|
|
26
|
+
export type CountryValue = {
|
|
27
|
+
readonly alpha3: CountryAlpha3;
|
|
28
|
+
readonly alpha2: CountryAlpha2;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* The longest country spelling a wire schema accepts.
|
|
32
|
+
*
|
|
33
|
+
* A country's own name is a spelling this reader reads, so the bound is a
|
|
34
|
+
* name's length rather than a code's: `Federal Republic of Germany` is a
|
|
35
|
+
* country input, and a schema capped at three characters was what turned it
|
|
36
|
+
* into a rejection before the reader ever saw it. It lives with the reader so
|
|
37
|
+
* the declared bound and what can be read cannot drift apart.
|
|
38
|
+
*/
|
|
39
|
+
export declare const COUNTRY_INPUT_MAX_CHARS = 64;
|
|
40
|
+
/** Which ISO spelling the calling surface stores. */
|
|
41
|
+
export type CountrySpelling = "alpha-3" | "alpha-2";
|
|
42
|
+
export type CountryOptions = {
|
|
43
|
+
/** The spelling the caller keeps, which decides how a coercion is reported:
|
|
44
|
+
* a surface storing alpha-2 must not be told its `CZ` was read as `CZE`. */
|
|
45
|
+
spelling?: CountrySpelling | undefined;
|
|
46
|
+
/** The canonical codes the calling surface holds law for, named in the ask so
|
|
47
|
+
* a model that guessed wrong can see what there is to ask for. */
|
|
48
|
+
admitted?: readonly string[] | undefined;
|
|
49
|
+
/** The tool whose input this is, so the ask names the call to change. */
|
|
50
|
+
tool?: string | undefined;
|
|
51
|
+
/** The property name, which differs between surfaces (`country`,
|
|
52
|
+
* `country_code`). */
|
|
53
|
+
parameter?: string | undefined;
|
|
54
|
+
};
|
|
55
|
+
/** The code a caller keeping `spelling` stores. */
|
|
56
|
+
export declare const countryCodeIn: (value: CountryValue, spelling?: CountrySpelling) => string;
|
|
57
|
+
/**
|
|
58
|
+
* Read a country an agent spelled its own way.
|
|
59
|
+
*
|
|
60
|
+
* An absent value asks rather than defaulting: a corpus country decides which
|
|
61
|
+
* body of law is searched, and picking one on the model's behalf answers a
|
|
62
|
+
* question about Czech law with Slovak decisions.
|
|
63
|
+
*/
|
|
64
|
+
export declare const normalizeCountry: (input: unknown, options?: CountryOptions) => Normalized<CountryValue>;
|
|
65
|
+
//#endregion
|
package/dist/country.js
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
import { a as readValueAs, t as askForFix } from "./normalized-Kt_5vfXW.js";
|
|
2
|
+
import { foldToAscii } from "@stll/text-normalize";
|
|
3
|
+
import { COUNTRY_ALPHA3_BY_CODE, COUNTRY_CODES, countryCodeFromAlpha3, isCountryCode } from "@stll/country-codes";
|
|
4
|
+
//#region src/country.ts
|
|
5
|
+
/**
|
|
6
|
+
* Jurisdictions that publish law without being ISO 3166-1 countries.
|
|
7
|
+
*
|
|
8
|
+
* The EU is the one this corpus holds: the Court of Justice and the Official
|
|
9
|
+
* Journal are supranational, and legal corpora and ELI identifiers spell that
|
|
10
|
+
* jurisdiction `EU`. CLDR carries `EU` as a region, so its names arrive from
|
|
11
|
+
* the same place as a country's, and ISO assigns it neither alpha-2 nor
|
|
12
|
+
* alpha-3, so `EU` is both.
|
|
13
|
+
*/
|
|
14
|
+
const SUPRANATIONAL_CODES = ["EU"];
|
|
15
|
+
/**
|
|
16
|
+
* The languages whose spellings are read.
|
|
17
|
+
*
|
|
18
|
+
* These are the languages this corpus's jurisdictions legislate and adjudicate
|
|
19
|
+
* in, plus English, which every model falls back to. A locale added here widens
|
|
20
|
+
* what is accepted and can only introduce an ambiguity that the index reports
|
|
21
|
+
* rather than guesses.
|
|
22
|
+
*/
|
|
23
|
+
const NAME_LOCALES = [
|
|
24
|
+
"en",
|
|
25
|
+
"cs",
|
|
26
|
+
"sk",
|
|
27
|
+
"pl",
|
|
28
|
+
"de",
|
|
29
|
+
"hu"
|
|
30
|
+
];
|
|
31
|
+
/**
|
|
32
|
+
* Official long forms CLDR does not carry, keyed by CLDR region.
|
|
33
|
+
*
|
|
34
|
+
* CLDR holds the short name a locale uses day to day (`Česko`, `Slovensko`),
|
|
35
|
+
* while a model drafting a legal document reaches for the constitutional name.
|
|
36
|
+
* Listed are the jurisdictions this corpus serves, plus Germany, whose language
|
|
37
|
+
* the corpus serves and whose law gets asked about in it. Each entry is in
|
|
38
|
+
* English or in one of those languages: an entry earns its place by being a
|
|
39
|
+
* name some surface actually receives, not by completeness. Case, spacing and
|
|
40
|
+
* diacritics need no entries of their own, because the index keys on the folded
|
|
41
|
+
* form.
|
|
42
|
+
*/
|
|
43
|
+
const OFFICIAL_NAMES = {
|
|
44
|
+
AT: [
|
|
45
|
+
"Republic of Austria",
|
|
46
|
+
"Republik Österreich",
|
|
47
|
+
"Rakouská republika"
|
|
48
|
+
],
|
|
49
|
+
CZ: [
|
|
50
|
+
"Czech Republic",
|
|
51
|
+
"Česká republika",
|
|
52
|
+
"Tschechische Republik",
|
|
53
|
+
"Republika Czeska"
|
|
54
|
+
],
|
|
55
|
+
DE: ["Federal Republic of Germany", "Bundesrepublik Deutschland"],
|
|
56
|
+
HU: ["Republic of Hungary", "Magyar Köztársaság"],
|
|
57
|
+
PL: [
|
|
58
|
+
"Republic of Poland",
|
|
59
|
+
"Rzeczpospolita Polska",
|
|
60
|
+
"Polská republika"
|
|
61
|
+
],
|
|
62
|
+
SK: [
|
|
63
|
+
"Slovak Republic",
|
|
64
|
+
"Slovenská republika",
|
|
65
|
+
"Slowakische Republik",
|
|
66
|
+
"Republika Słowacka"
|
|
67
|
+
],
|
|
68
|
+
EU: ["European Communities"]
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* Tokens that name two countries at once.
|
|
72
|
+
*
|
|
73
|
+
* Each maps to the readings the ask must name. A token here must not be a valid
|
|
74
|
+
* alpha-2 code: the codes are read as themselves, and this table exists for the
|
|
75
|
+
* spellings that are not codes at all.
|
|
76
|
+
*/
|
|
77
|
+
const AMBIGUOUS_TOKENS = /* @__PURE__ */ new Map([["cs", ["CZE", "SVK"]]]);
|
|
78
|
+
/** The comparison form of a name: case, diacritics and spacing carry no
|
|
79
|
+
* meaning in a country name, so none of them reach the index key. */
|
|
80
|
+
const fold = (value) => foldToAscii(value.trim()).toLowerCase().replaceAll(/\s+/gu, " ");
|
|
81
|
+
/**
|
|
82
|
+
* The name index, built once on first read.
|
|
83
|
+
*
|
|
84
|
+
* `Intl.DisplayNames` is thousands of lookups across every region and locale,
|
|
85
|
+
* so it is deferred rather than run at import: a module that only ever reads a
|
|
86
|
+
* code should not pay for the names, and a shared module must not do work when
|
|
87
|
+
* it is loaded.
|
|
88
|
+
*/
|
|
89
|
+
let cachedIndex = null;
|
|
90
|
+
const buildIndex = () => {
|
|
91
|
+
const regions = [...COUNTRY_CODES, ...SUPRANATIONAL_CODES];
|
|
92
|
+
const collected = /* @__PURE__ */ new Map();
|
|
93
|
+
const add = (name, region) => {
|
|
94
|
+
const key = fold(name);
|
|
95
|
+
if (key.length === 0) return;
|
|
96
|
+
const existing = collected.get(key);
|
|
97
|
+
if (existing === void 0) {
|
|
98
|
+
collected.set(key, [region]);
|
|
99
|
+
return;
|
|
100
|
+
}
|
|
101
|
+
if (!existing.includes(region)) existing.push(region);
|
|
102
|
+
};
|
|
103
|
+
for (const locale of NAME_LOCALES) for (const style of ["long", "short"]) {
|
|
104
|
+
const display = new Intl.DisplayNames([locale], {
|
|
105
|
+
type: "region",
|
|
106
|
+
style,
|
|
107
|
+
fallback: "none"
|
|
108
|
+
});
|
|
109
|
+
for (const region of regions) {
|
|
110
|
+
const name = display.of(region);
|
|
111
|
+
if (name !== void 0 && name !== region) add(name, region);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
for (const [region, names] of Object.entries(OFFICIAL_NAMES)) for (const name of names) add(name, region);
|
|
115
|
+
return { regionsByName: collected };
|
|
116
|
+
};
|
|
117
|
+
const index = () => {
|
|
118
|
+
cachedIndex ??= buildIndex();
|
|
119
|
+
return cachedIndex;
|
|
120
|
+
};
|
|
121
|
+
const isSupranational = (value) => SUPRANATIONAL_CODES.some((code) => code === value);
|
|
122
|
+
/** The canonical pair a CLDR region names. */
|
|
123
|
+
const valueOfRegion = (region) => {
|
|
124
|
+
if (isSupranational(region)) return {
|
|
125
|
+
alpha3: region,
|
|
126
|
+
alpha2: region
|
|
127
|
+
};
|
|
128
|
+
return isCountryCode(region) ? {
|
|
129
|
+
alpha3: COUNTRY_ALPHA3_BY_CODE[region],
|
|
130
|
+
alpha2: region
|
|
131
|
+
} : null;
|
|
132
|
+
};
|
|
133
|
+
/** The canonical pair a code names, in either ISO length. */
|
|
134
|
+
const valueOfCode = (upper) => {
|
|
135
|
+
if (isSupranational(upper)) return {
|
|
136
|
+
alpha3: upper,
|
|
137
|
+
alpha2: upper
|
|
138
|
+
};
|
|
139
|
+
const fromAlpha3 = countryCodeFromAlpha3(upper);
|
|
140
|
+
if (fromAlpha3 !== null) return {
|
|
141
|
+
alpha3: COUNTRY_ALPHA3_BY_CODE[fromAlpha3],
|
|
142
|
+
alpha2: fromAlpha3
|
|
143
|
+
};
|
|
144
|
+
return isCountryCode(upper) ? {
|
|
145
|
+
alpha3: COUNTRY_ALPHA3_BY_CODE[upper],
|
|
146
|
+
alpha2: upper
|
|
147
|
+
} : null;
|
|
148
|
+
};
|
|
149
|
+
/**
|
|
150
|
+
* The longest country spelling a wire schema accepts.
|
|
151
|
+
*
|
|
152
|
+
* A country's own name is a spelling this reader reads, so the bound is a
|
|
153
|
+
* name's length rather than a code's: `Federal Republic of Germany` is a
|
|
154
|
+
* country input, and a schema capped at three characters was what turned it
|
|
155
|
+
* into a rejection before the reader ever saw it. It lives with the reader so
|
|
156
|
+
* the declared bound and what can be read cannot drift apart.
|
|
157
|
+
*/
|
|
158
|
+
const COUNTRY_INPUT_MAX_CHARS = 64;
|
|
159
|
+
const COUNTRY_EXPECTED = "a country";
|
|
160
|
+
/** The code a caller keeping `spelling` stores. */
|
|
161
|
+
const countryCodeIn = (value, spelling = "alpha-3") => spelling === "alpha-2" ? value.alpha2 : value.alpha3;
|
|
162
|
+
/**
|
|
163
|
+
* How the canonical value is quoted in a coercion note.
|
|
164
|
+
*
|
|
165
|
+
* The note compares against the spelling the agent sent, which is the quoted
|
|
166
|
+
* JSON of a string, so the canonical code is quoted the same way. Without it,
|
|
167
|
+
* `"CZE"` would be reported as read into `CZE` and a canonical input would not
|
|
168
|
+
* be the fixed point it is.
|
|
169
|
+
*/
|
|
170
|
+
const canonicalSpelling = (value, options) => JSON.stringify(countryCodeIn(value, options.spelling));
|
|
171
|
+
const admittedSentence = (admitted) => admitted === void 0 || admitted.length === 0 ? "" : ` Admitted: ${admitted.join(", ")}.`;
|
|
172
|
+
/** Where to make the correction, as far as the caller told us. */
|
|
173
|
+
const target = ({ tool, parameter }) => {
|
|
174
|
+
const property = parameter ?? "country";
|
|
175
|
+
return tool === void 0 ? `\`${property}\`` : `\`${property}\` on ${tool}`;
|
|
176
|
+
};
|
|
177
|
+
const expectedWith = (options) => {
|
|
178
|
+
const admitted = options.admitted;
|
|
179
|
+
return admitted === void 0 || admitted.length === 0 ? COUNTRY_EXPECTED : `a country code, one of ${admitted.join(", ")}`;
|
|
180
|
+
};
|
|
181
|
+
/** The spellings the reader accepts, as one clause a hint drops in. */
|
|
182
|
+
const ACCEPTED_SPELLINGS = "an ISO 3166-1 code, alpha-3 or alpha-2 (\"CZE\", \"CZ\"); the country's name in English or in a language the corpus serves (\"Czechia\", \"Česko\", \"Česká republika\") is read as well.";
|
|
183
|
+
const spellingHint = (options) => `Set ${target(options)} to ${ACCEPTED_SPELLINGS}${admittedSentence(options.admitted)}`;
|
|
184
|
+
/**
|
|
185
|
+
* Read a country an agent spelled its own way.
|
|
186
|
+
*
|
|
187
|
+
* An absent value asks rather than defaulting: a corpus country decides which
|
|
188
|
+
* body of law is searched, and picking one on the model's behalf answers a
|
|
189
|
+
* question about Czech law with Slovak decisions.
|
|
190
|
+
*/
|
|
191
|
+
const normalizeCountry = (input, options = {}) => {
|
|
192
|
+
if (input === void 0 || input === null || typeof input === "string" && input.trim().length === 0) return askForFix({
|
|
193
|
+
input,
|
|
194
|
+
expected: expectedWith(options),
|
|
195
|
+
hint: `${target(options)} is required. ${spellingHint(options)}`
|
|
196
|
+
});
|
|
197
|
+
if (typeof input !== "string") return askForFix({
|
|
198
|
+
input,
|
|
199
|
+
expected: expectedWith(options),
|
|
200
|
+
hint: spellingHint(options)
|
|
201
|
+
});
|
|
202
|
+
const collapsed = input.trim().replaceAll(/\s+/gu, " ");
|
|
203
|
+
const byCode = valueOfCode(collapsed.toUpperCase());
|
|
204
|
+
if (byCode !== null) return readValueAs(input, byCode, canonicalSpelling(byCode, options));
|
|
205
|
+
const key = fold(collapsed);
|
|
206
|
+
const ambiguous = AMBIGUOUS_TOKENS.get(key);
|
|
207
|
+
if (ambiguous !== void 0) return askForFix({
|
|
208
|
+
input,
|
|
209
|
+
expected: expectedWith(options),
|
|
210
|
+
hint: `"${collapsed}" names more than one country here: ${ambiguous.join(" or ")}. Set ${target(options)} to the one you mean.${admittedSentence(options.admitted)}`
|
|
211
|
+
});
|
|
212
|
+
const regions = index().regionsByName.get(key);
|
|
213
|
+
const single = regions?.length === 1 ? regions.at(0) : void 0;
|
|
214
|
+
if (single !== void 0) {
|
|
215
|
+
const value = valueOfRegion(single);
|
|
216
|
+
if (value !== null) return readValueAs(input, value, canonicalSpelling(value, options));
|
|
217
|
+
}
|
|
218
|
+
if (regions !== void 0 && regions.length > 1) {
|
|
219
|
+
const readings = regions.map((region) => valueOfRegion(region)?.alpha3).filter((alpha3) => alpha3 !== void 0);
|
|
220
|
+
return askForFix({
|
|
221
|
+
input,
|
|
222
|
+
expected: expectedWith(options),
|
|
223
|
+
hint: `"${collapsed}" names more than one country here: ${readings.join(" or ")}. Set ${target(options)} to the one you mean.${admittedSentence(options.admitted)}`
|
|
224
|
+
});
|
|
225
|
+
}
|
|
226
|
+
return askForFix({
|
|
227
|
+
input,
|
|
228
|
+
expected: expectedWith(options),
|
|
229
|
+
hint: spellingHint(options)
|
|
230
|
+
});
|
|
231
|
+
};
|
|
232
|
+
//#endregion
|
|
233
|
+
export { COUNTRY_INPUT_MAX_CHARS, countryCodeIn, normalizeCountry };
|