@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/dist/locale.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { t as Normalized } from "./normalized-B9RxhmIz.js";
|
|
2
|
+
//#region src/locale.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Whether a tag is already the spelling `Intl` accepts. This is the check a
|
|
5
|
+
* stored or advertised locale passes: a value that reaches
|
|
6
|
+
* `Intl.DateTimeFormat` at fill time must not be able to make it throw, so the
|
|
7
|
+
* leniency below stops at the boundary and never reaches persistence.
|
|
8
|
+
*/
|
|
9
|
+
export declare const isPlausibleLocale: (value: string) => boolean;
|
|
10
|
+
/** Read a locale an agent spelled its own way, canonically. */
|
|
11
|
+
export declare const normalizeLocale: (input: unknown) => Normalized<string>;
|
|
12
|
+
//#endregion
|
package/dist/locale.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { a as readValueAs, t as askForFix } from "./normalized-Kt_5vfXW.js";
|
|
2
|
+
import { Result } from "better-result";
|
|
3
|
+
//#region src/locale.ts
|
|
4
|
+
/**
|
|
5
|
+
* Locale tags on the agent wire.
|
|
6
|
+
*
|
|
7
|
+
* `Intl` is the authority on both halves: it refuses a structurally malformed
|
|
8
|
+
* tag (a well-formed but unknown one passes and merely falls back at format
|
|
9
|
+
* time) and it spells the canonical form. Underscores are the ICU/POSIX
|
|
10
|
+
* spelling of the same tag, and case carries no meaning, so `cs_cz` and
|
|
11
|
+
* `cs-CZ` are one locale — but only the canonical spelling may be stored,
|
|
12
|
+
* because `new Intl.DateTimeFormat("cs_CZ")` throws.
|
|
13
|
+
*/
|
|
14
|
+
const LOCALE_EXPECTED = "a BCP-47 language tag";
|
|
15
|
+
const LOCALE_HINT = "Write the tag as language or language-REGION: \"cs\", \"pl\", \"en-GB\", \"pt-BR\".";
|
|
16
|
+
/** The canonical spelling of a well-formed tag, or null. `Intl` throws a
|
|
17
|
+
* RangeError on a malformed tag rather than reporting it. */
|
|
18
|
+
const canonicalize = (candidate) => {
|
|
19
|
+
const canonical = Result.try({
|
|
20
|
+
try: () => Intl.getCanonicalLocales(candidate),
|
|
21
|
+
catch: (cause) => cause
|
|
22
|
+
});
|
|
23
|
+
return canonical.isOk() ? canonical.value.at(0) ?? null : null;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Whether a tag is already the spelling `Intl` accepts. This is the check a
|
|
27
|
+
* stored or advertised locale passes: a value that reaches
|
|
28
|
+
* `Intl.DateTimeFormat` at fill time must not be able to make it throw, so the
|
|
29
|
+
* leniency below stops at the boundary and never reaches persistence.
|
|
30
|
+
*/
|
|
31
|
+
const isPlausibleLocale = (value) => canonicalize(value) !== null;
|
|
32
|
+
/** Read a locale an agent spelled its own way, canonically. */
|
|
33
|
+
const normalizeLocale = (input) => {
|
|
34
|
+
if (typeof input !== "string") return askForFix({
|
|
35
|
+
input,
|
|
36
|
+
expected: LOCALE_EXPECTED,
|
|
37
|
+
hint: LOCALE_HINT
|
|
38
|
+
});
|
|
39
|
+
const canonical = canonicalize(input.trim().replaceAll("_", "-"));
|
|
40
|
+
if (canonical === null) return askForFix({
|
|
41
|
+
input,
|
|
42
|
+
expected: LOCALE_EXPECTED,
|
|
43
|
+
hint: LOCALE_HINT
|
|
44
|
+
});
|
|
45
|
+
return readValueAs(input, canonical);
|
|
46
|
+
};
|
|
47
|
+
//#endregion
|
|
48
|
+
export { isPlausibleLocale, normalizeLocale };
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
//#region src/normalized.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* One shape for every value an agent spells its own way.
|
|
4
|
+
*
|
|
5
|
+
* Models copy examples, translate, and reach for the notation their training
|
|
6
|
+
* data used most: a date arrives as `1. 10. 2026`, a number as `4 000`, a
|
|
7
|
+
* boolean as `ano`, a locale as `cs_CZ`. Each kind in this directory reads the
|
|
8
|
+
* spellings that carry one meaning and asks for a fix when a spelling carries
|
|
9
|
+
* two, so no call site grows its own parser or its own wording.
|
|
10
|
+
*
|
|
11
|
+
* `ok: true` is the canonical value, with `note` set when the input had to be
|
|
12
|
+
* read rather than taken verbatim (surface it as a warning, never as an
|
|
13
|
+
* error). `ok: false` is the single ask-for-a-fix shape: `expected` names the
|
|
14
|
+
* canonical form and `hint` names the one call to make. Callers render those
|
|
15
|
+
* two rather than composing wording of their own, which is what keeps one kind
|
|
16
|
+
* answering the same way on every surface.
|
|
17
|
+
*/
|
|
18
|
+
/** The one ask-for-a-fix shape. */
|
|
19
|
+
type NormalizedAsk = {
|
|
20
|
+
ok: false;
|
|
21
|
+
/** The input as the agent sent it, quoted and bounded. */
|
|
22
|
+
received: string;
|
|
23
|
+
/** The canonical form as a noun phrase: "a calendar date". */
|
|
24
|
+
expected: string;
|
|
25
|
+
/** The corrective call, spelled out. */
|
|
26
|
+
hint: string;
|
|
27
|
+
};
|
|
28
|
+
type Normalized<TValue> = {
|
|
29
|
+
ok: true;
|
|
30
|
+
value: TValue;
|
|
31
|
+
note?: string;
|
|
32
|
+
} | NormalizedAsk;
|
|
33
|
+
declare const askForFix: ({ input, expected, hint }: {
|
|
34
|
+
input: unknown;
|
|
35
|
+
expected: string;
|
|
36
|
+
hint: string;
|
|
37
|
+
}) => NormalizedAsk;
|
|
38
|
+
/** The ask as one sentence, for a caller whose issue shape carries a message
|
|
39
|
+
* beside the hint. */
|
|
40
|
+
declare const askSentence: (ask: NormalizedAsk) => string;
|
|
41
|
+
/**
|
|
42
|
+
* The input read as no value at all.
|
|
43
|
+
*
|
|
44
|
+
* An optional filter the agent is not setting still arrives filled in: `"any"`,
|
|
45
|
+
* `"-"`, the nil uuid, `9999-12-31` as an open bound. Each of those means "not
|
|
46
|
+
* filtering", and asking about it would send the model back to delete a value
|
|
47
|
+
* it only wrote because the schema had a slot. Only a reader that can see a
|
|
48
|
+
* placeholder returns this, and only on inputs the caller marked optional; the
|
|
49
|
+
* caller drops the property and surfaces `note` as a warning.
|
|
50
|
+
*/
|
|
51
|
+
type NormalizedAbsent = {
|
|
52
|
+
ok: "absent";
|
|
53
|
+
/** The input as the agent sent it, quoted and bounded. */
|
|
54
|
+
received: string;
|
|
55
|
+
note: string;
|
|
56
|
+
};
|
|
57
|
+
/** A reader's outcome on an optional input, where a placeholder is no value. */
|
|
58
|
+
type NormalizedOptional<TValue> = Normalized<TValue> | NormalizedAbsent;
|
|
59
|
+
/** The absent outcome, with the one "read X as no value" sentence every kind
|
|
60
|
+
* reports it with. `reason` says why, when the spelling alone does not. */
|
|
61
|
+
declare const readAsAbsent: (input: unknown, reason?: string) => NormalizedAbsent;
|
|
62
|
+
//#endregion
|
|
63
|
+
export { askForFix as a, NormalizedOptional as i, NormalizedAbsent as n, askSentence as o, NormalizedAsk as r, readAsAbsent as s, Normalized as t };
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
//#region src/normalized.ts
|
|
2
|
+
/** Wire values carry matter content and personal data, so an echo back to the
|
|
3
|
+
* model is bounded to the length of a spelling. */
|
|
4
|
+
const MAX_RECEIVED_CHARS = 80;
|
|
5
|
+
/** The input as one quoted token: what the agent sent, ready to drop into a
|
|
6
|
+
* sentence. */
|
|
7
|
+
const describeInput = (input) => {
|
|
8
|
+
const spelled = typeof input === "function" || typeof input === "symbol" ? void 0 : JSON.stringify(input);
|
|
9
|
+
const rendered = input === void 0 ? "undefined" : spelled ?? `a ${typeof input}`;
|
|
10
|
+
return rendered.length <= MAX_RECEIVED_CHARS ? rendered : `${rendered.slice(0, MAX_RECEIVED_CHARS)}…`;
|
|
11
|
+
};
|
|
12
|
+
const readValue = (value) => ({
|
|
13
|
+
ok: true,
|
|
14
|
+
value
|
|
15
|
+
});
|
|
16
|
+
/**
|
|
17
|
+
* The canonical value, plus the "read X as Y" note when the agent's spelling
|
|
18
|
+
* was not already the canonical one. That sentence is spelled here alone, so
|
|
19
|
+
* every kind reports a coercion the same way. `canonical` overrides how the
|
|
20
|
+
* result is rendered in the note, for a kind whose canonical spelling is not
|
|
21
|
+
* the JSON form of its value.
|
|
22
|
+
*/
|
|
23
|
+
const readValueAs = (input, value, canonical = describeInput(value)) => {
|
|
24
|
+
const received = describeInput(input);
|
|
25
|
+
return received === canonical ? {
|
|
26
|
+
ok: true,
|
|
27
|
+
value
|
|
28
|
+
} : {
|
|
29
|
+
ok: true,
|
|
30
|
+
value,
|
|
31
|
+
note: `Read ${received} as ${canonical}.`
|
|
32
|
+
};
|
|
33
|
+
};
|
|
34
|
+
const askForFix = ({ input, expected, hint }) => ({
|
|
35
|
+
ok: false,
|
|
36
|
+
received: describeInput(input),
|
|
37
|
+
expected,
|
|
38
|
+
hint
|
|
39
|
+
});
|
|
40
|
+
/** The ask as one sentence, for a caller whose issue shape carries a message
|
|
41
|
+
* beside the hint. */
|
|
42
|
+
const askSentence = (ask) => `${ask.received} is not ${ask.expected}.`;
|
|
43
|
+
/** The absent outcome, with the one "read X as no value" sentence every kind
|
|
44
|
+
* reports it with. `reason` says why, when the spelling alone does not. */
|
|
45
|
+
const readAsAbsent = (input, reason) => {
|
|
46
|
+
const received = describeInput(input);
|
|
47
|
+
return {
|
|
48
|
+
ok: "absent",
|
|
49
|
+
received,
|
|
50
|
+
note: reason === void 0 ? `Read ${received} as no value.` : `Read ${received} as no value: ${reason}.`
|
|
51
|
+
};
|
|
52
|
+
};
|
|
53
|
+
//#endregion
|
|
54
|
+
export { readValueAs as a, readValue as i, askSentence as n, readAsAbsent as r, askForFix as t };
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { t as Normalized } from "./normalized-B9RxhmIz.js";
|
|
2
|
+
//#region src/string-list.d.ts
|
|
3
|
+
export type StringListOptions = {
|
|
4
|
+
/** `"delimiters"` splits a scalar on commas, semicolons and newlines, for
|
|
5
|
+
* items that cannot contain them (ids, codes). `"never"` wraps a scalar as
|
|
6
|
+
* one item, for free text that may. */
|
|
7
|
+
split: "never" | "delimiters";
|
|
8
|
+
};
|
|
9
|
+
/** Read a list of strings an agent spelled its own way. Only the list's own
|
|
10
|
+
* shape is read here: an array is taken as it is, and one holding anything
|
|
11
|
+
* but strings asks, since what an item should have been is the item's
|
|
12
|
+
* question, not the list's. */
|
|
13
|
+
export declare const normalizeStringList: (input: unknown, options: StringListOptions) => Normalized<string[]>;
|
|
14
|
+
//#endregion
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { a as readValueAs, i as readValue, t as askForFix } from "./normalized-Kt_5vfXW.js";
|
|
2
|
+
import { Result } from "better-result";
|
|
3
|
+
//#region src/string-list.ts
|
|
4
|
+
/**
|
|
5
|
+
* Lists of strings on the agent wire.
|
|
6
|
+
*
|
|
7
|
+
* A model asked for an array often sends the array's JSON as a string
|
|
8
|
+
* (`"[\"a\", \"b\"]"`), or one bare string where the schema wanted a list of
|
|
9
|
+
* one. Both carry one meaning and are read. A comma-separated string carries
|
|
10
|
+
* one meaning only where an item cannot itself hold a comma: a list of court
|
|
11
|
+
* ids can be split, a list of search phrases cannot (`"Smith, J."` is one
|
|
12
|
+
* phrase), so the caller says which by `split`.
|
|
13
|
+
*/
|
|
14
|
+
const STRING_LIST_EXPECTED = "a list of strings";
|
|
15
|
+
const STRING_LIST_HINT = "Send a JSON array of strings, for example [\"a\", \"b\"]";
|
|
16
|
+
const DELIMITERS_RE = /[,;\r\n]/u;
|
|
17
|
+
const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
|
|
18
|
+
/** The array a string spells as JSON, or null when it spells something else. */
|
|
19
|
+
const parseJsonArray = (trimmed) => {
|
|
20
|
+
if (!trimmed.startsWith("[")) return null;
|
|
21
|
+
const parsed = Result.try(() => JSON.parse(trimmed));
|
|
22
|
+
return parsed.isOk() && isStringArray(parsed.value) ? parsed.value : null;
|
|
23
|
+
};
|
|
24
|
+
/** Read a list of strings an agent spelled its own way. Only the list's own
|
|
25
|
+
* shape is read here: an array is taken as it is, and one holding anything
|
|
26
|
+
* but strings asks, since what an item should have been is the item's
|
|
27
|
+
* question, not the list's. */
|
|
28
|
+
const normalizeStringList = (input, options) => {
|
|
29
|
+
if (isStringArray(input)) return readValue(input);
|
|
30
|
+
if (typeof input !== "string") return askForFix({
|
|
31
|
+
input,
|
|
32
|
+
expected: STRING_LIST_EXPECTED,
|
|
33
|
+
hint: STRING_LIST_HINT
|
|
34
|
+
});
|
|
35
|
+
const parsed = parseJsonArray(input.trim());
|
|
36
|
+
if (parsed !== null) return readValueAs(input, parsed);
|
|
37
|
+
if (options.split === "never") return readValueAs(input, [input]);
|
|
38
|
+
const pieces = input.split(DELIMITERS_RE).map((piece) => piece.trim()).filter((piece) => piece !== "");
|
|
39
|
+
return readValueAs(input, pieces);
|
|
40
|
+
};
|
|
41
|
+
//#endregion
|
|
42
|
+
export { normalizeStringList };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stll/agent-input",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.8",
|
|
4
4
|
"description": "Lenient readers for values agents write: dates, date bounds, date-format specs, numbers, booleans, locales, countries, enum and vocabulary values, ids, ELIs, string lists",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -31,6 +31,22 @@
|
|
|
31
31
|
".": {
|
|
32
32
|
"types": "./dist/index.d.ts",
|
|
33
33
|
"import": "./dist/index.js"
|
|
34
|
+
},
|
|
35
|
+
"./country": {
|
|
36
|
+
"types": "./dist/country.d.ts",
|
|
37
|
+
"import": "./dist/country.js"
|
|
38
|
+
},
|
|
39
|
+
"./date-value": {
|
|
40
|
+
"types": "./dist/date-value.d.ts",
|
|
41
|
+
"import": "./dist/date-value.js"
|
|
42
|
+
},
|
|
43
|
+
"./locale": {
|
|
44
|
+
"types": "./dist/locale.d.ts",
|
|
45
|
+
"import": "./dist/locale.js"
|
|
46
|
+
},
|
|
47
|
+
"./string-list": {
|
|
48
|
+
"types": "./dist/string-list.d.ts",
|
|
49
|
+
"import": "./dist/string-list.js"
|
|
34
50
|
}
|
|
35
51
|
},
|
|
36
52
|
"publishConfig": {
|
|
@@ -50,10 +66,10 @@
|
|
|
50
66
|
},
|
|
51
67
|
"dependencies": {
|
|
52
68
|
"@stll/country-codes": "^0.2.0",
|
|
53
|
-
"@stll/fuzzy-search": "1.
|
|
69
|
+
"@stll/fuzzy-search": "1.4.0",
|
|
54
70
|
"@stll/template-conditions": "^0.6.4",
|
|
55
71
|
"@stll/text-normalize": "^0.3.0",
|
|
56
|
-
"@stll/time": "
|
|
72
|
+
"@stll/time": "0.4.1",
|
|
57
73
|
"better-result": "3.0.1"
|
|
58
74
|
},
|
|
59
75
|
"devDependencies": {
|