@stll/agent-input 0.0.1-placeholder.0 → 0.1.0
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 +77 -1
- package/dist/index.d.ts +420 -0
- package/dist/index.js +1974 -0
- package/package.json +63 -5
package/README.md
CHANGED
|
@@ -1 +1,77 @@
|
|
|
1
|
-
|
|
1
|
+
# @stll/agent-input
|
|
2
|
+
|
|
3
|
+
Lenient readers for values agents write: dates, date-format specs, numbers, booleans, locales, countries, enum values.
|
|
4
|
+
|
|
5
|
+
## What lives here
|
|
6
|
+
|
|
7
|
+
One reader per value kind that reaches a tool input, a template marker, or a
|
|
8
|
+
fill value. Each reads the spellings that carry a single meaning (`4 000`,
|
|
9
|
+
`1. 10. 2026`, `ano`, `cs_CZ`, `Česko`) and returns the one ask-for-a-fix shape
|
|
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.
|
|
12
|
+
|
|
13
|
+
`normalizeCountry` reads ISO 3166-1 alpha-3 and alpha-2 codes and the country's
|
|
14
|
+
name in each language the corpus serves, and returns both canonical spellings so
|
|
15
|
+
a caller keeps the one its column holds. The names come from CLDR through
|
|
16
|
+
`Intl.DisplayNames` rather than from a table maintained here; only the official
|
|
17
|
+
long forms CLDR omits (`Česká republika` against its `Česko`) are declared.
|
|
18
|
+
Recognising a country is not admitting it: whether a corpus holds that
|
|
19
|
+
jurisdiction stays the caller's `not_found`.
|
|
20
|
+
|
|
21
|
+
A third outcome exists only on optional inputs: `ok: "absent"`, the input read
|
|
22
|
+
as no value (`readAsAbsent`, `NormalizedOptional<T>`). A model fills every slot
|
|
23
|
+
it is shown, so a filter it is not setting still arrives as `"any"`, `"-"`, the
|
|
24
|
+
nil uuid, or `9999-12-31`. `isAbsentPlaceholder` holds the closed set of
|
|
25
|
+
placeholder words; it is never applied to free text, and the caller decides
|
|
26
|
+
which inputs it covers.
|
|
27
|
+
|
|
28
|
+
`normalizeUuid` reads an id in any spelling that names the same 128 bits
|
|
29
|
+
(uppercase, `{...}`, `urn:uuid:`, no dashes) as the lowercase dashed form, and
|
|
30
|
+
reads the ids a model invents when it has none (nil, max, one repeated digit,
|
|
31
|
+
the RFC and tutorial examples) as no value.
|
|
32
|
+
|
|
33
|
+
`normalizeVocabularyValue` reads a filter value whose allowed set comes from
|
|
34
|
+
data rather than the schema: court names, decision types. It widens step by
|
|
35
|
+
step, from the exact value through folded spellings and aliases to word
|
|
36
|
+
containment, and stops at the first step that finds exactly one entry, so
|
|
37
|
+
`Ústavní soud České republiky` reads as `Ústavní soud` while `Krajský soud`
|
|
38
|
+
asks which regional court. Closed schema enums stay with `normalizeEnumValue`.
|
|
39
|
+
|
|
40
|
+
`normalizeStringList` reads an array sent as its JSON string, and a bare string
|
|
41
|
+
as a list. Whether a bare string is split on commas is the caller's `split`:
|
|
42
|
+
ids can be, free-text phrases cannot.
|
|
43
|
+
|
|
44
|
+
`normalizeDateBound` reads one end of a date range: a bare year or month is that
|
|
45
|
+
end's first or last day, an open-ended sentinel year (`0001`, `9999`) is no
|
|
46
|
+
bound, and a whole range written into one field asks for its two halves.
|
|
47
|
+
`normalizeDateValue` takes the same `bound` without the absent outcome.
|
|
48
|
+
|
|
49
|
+
`normalizeNumberInRange` clamps a bounded count (a page size) into range with a
|
|
50
|
+
note instead of asking, and asks about a fraction where the count is whole.
|
|
51
|
+
Which fields clamp is the caller's choice.
|
|
52
|
+
|
|
53
|
+
`normalizeEli` reads a European Legislation Identifier with or without its
|
|
54
|
+
origin, in any case, with a trailing slash, or with year and number swapped, as
|
|
55
|
+
the canonical work identifier under the publisher origin the caller maps each
|
|
56
|
+
jurisdiction to. A path past the work (a version date, a provision) asks for
|
|
57
|
+
the work; an input that is not an ELI goes through the caller's citation reader
|
|
58
|
+
before it asks.
|
|
59
|
+
|
|
60
|
+
`normalizeAgentInput` derives a recursive normalization plan from the canonical
|
|
61
|
+
JSON Schema. Standard number, boolean, string-enum, and `format: date` keywords
|
|
62
|
+
are the annotations for those kinds; `x-stella-agent-input` names locale and
|
|
63
|
+
date-format fields that JSON Schema cannot distinguish from ordinary strings or
|
|
64
|
+
objects. `agentInputNormalizationMetadata` emits that annotation and its MCP/CLI
|
|
65
|
+
guidance together. `invalidValueDisposition: "handler-owned"` is reserved for
|
|
66
|
+
handlers that deliberately repair invalid properties while applying valid
|
|
67
|
+
siblings; valid spellings still normalize through the shared reader.
|
|
68
|
+
|
|
69
|
+
## What does not
|
|
70
|
+
|
|
71
|
+
Transport, strict schema validation, and persistence. First-party agent
|
|
72
|
+
transports call the shared API dispatch boundary; upstream MCP servers keep
|
|
73
|
+
their own contracts. Ordinary strings are never normalized heuristically.
|
|
74
|
+
|
|
75
|
+
## License
|
|
76
|
+
|
|
77
|
+
Apache-2.0
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,420 @@
|
|
|
1
|
+
import { CountryAlpha3Code, CountryCode } from "@stll/country-codes";
|
|
2
|
+
import { DateFormatStyle } from "@stll/template-conditions";
|
|
3
|
+
//#region src/absent.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Placeholders on optional filters.
|
|
6
|
+
*
|
|
7
|
+
* A model fills every slot a schema shows it, so a filter it means to leave
|
|
8
|
+
* unset still arrives as `"any"`, `"-"` or `"none"`. Those words name no
|
|
9
|
+
* court, no type, no record: read as a value they match nothing and the call
|
|
10
|
+
* returns an empty page the model then explains away. The set is closed and
|
|
11
|
+
* short on purpose; a word outside it is a value and goes to the kind's own
|
|
12
|
+
* reader.
|
|
13
|
+
*
|
|
14
|
+
* This is not for free text. `"none"` is a fine answer to a question and `"-"`
|
|
15
|
+
* a fine clause body, so the caller decides which inputs a placeholder can
|
|
16
|
+
* stand in for.
|
|
17
|
+
*/
|
|
18
|
+
/** The words, already in the folded lowercase form they are compared in. */
|
|
19
|
+
export declare const ABSENT_PLACEHOLDERS: readonly ["-", "--", "–", "—", "*", "all", "any", "none", "null", "nil", "undefined", "n/a", "(none)", "<none>", "(any)", "(all)"];
|
|
20
|
+
/** Whether a string stands for "no value" on an optional filter: blank, or one
|
|
21
|
+
* of the placeholder words in any case and spacing. */
|
|
22
|
+
export declare const isAbsentPlaceholder: (input: unknown) => boolean;
|
|
23
|
+
//#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
|
+
//#region src/boolean.d.ts
|
|
87
|
+
/** Read a yes/no answer an agent spelled its own way. */
|
|
88
|
+
export declare const normalizeBoolean: (input: unknown) => Normalized<boolean>;
|
|
89
|
+
//#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
|
+
//#region src/date-format-spec.d.ts
|
|
154
|
+
type DateFormatSpec = {
|
|
155
|
+
locale: string;
|
|
156
|
+
style: DateFormatStyle;
|
|
157
|
+
};
|
|
158
|
+
export declare const DATE_FORMAT_SPEC_HINT: string;
|
|
159
|
+
/** Read a date-format spec an agent spelled its own way, as one string or as
|
|
160
|
+
* the wire object. */
|
|
161
|
+
export declare const normalizeDateFormatSpec: (input: unknown) => Normalized<DateFormatSpec>;
|
|
162
|
+
//#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
|
+
//#region src/eli.d.ts
|
|
193
|
+
type EliOptions = {
|
|
194
|
+
/** ELI jurisdiction segment (lowercase, `"cz"`) to the publisher origin
|
|
195
|
+
* (`"https://www.e-sbirka.cz"`) that canonical identifiers carry. */
|
|
196
|
+
hosts: Readonly<Record<string, string>>;
|
|
197
|
+
/** The caller's gazette-citation reader, for an input that is not an ELI at
|
|
198
|
+
* all (`89/2012 Sb.`): the ELI that citation names, or undefined. */
|
|
199
|
+
readCitation?: ((text: string) => string | undefined) | undefined;
|
|
200
|
+
/** The corrective call when the input is not an ELI. */
|
|
201
|
+
hint?: string | undefined;
|
|
202
|
+
};
|
|
203
|
+
/**
|
|
204
|
+
* Read an ELI an agent spelled its own way, as the canonical work identifier
|
|
205
|
+
* under its publisher's origin. An input that is not an ELI goes through the
|
|
206
|
+
* caller's citation reader before it asks.
|
|
207
|
+
*/
|
|
208
|
+
export declare const normalizeEli: (input: unknown, options: EliOptions) => Normalized<string>;
|
|
209
|
+
//#endregion
|
|
210
|
+
//#region src/enum-value.d.ts
|
|
211
|
+
type EnumValueOptions = {
|
|
212
|
+
/** What the set is called in the ask: "The styles", "The registries". */
|
|
213
|
+
label?: string;
|
|
214
|
+
/** What the set is, as a noun phrase for `expected`: "a date style". */
|
|
215
|
+
expected?: string;
|
|
216
|
+
};
|
|
217
|
+
/**
|
|
218
|
+
* Read one value of a closed set. An exact hit is taken verbatim; a hit that
|
|
219
|
+
* differs only in case, spacing, or diacritics is read with a note; a value one
|
|
220
|
+
* edit from an allowed one asks and names it; anything else asks with the whole
|
|
221
|
+
* set, which is short enough to copy from.
|
|
222
|
+
*/
|
|
223
|
+
export declare const normalizeEnumValue: <TValue extends string>(input: unknown, allowed: readonly TValue[], options?: EnumValueOptions) => Normalized<TValue>;
|
|
224
|
+
//#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
|
+
//#region src/number.d.ts
|
|
237
|
+
type NumberOptions = {
|
|
238
|
+
/** The field's locale, when one is configured. It decides `1,234`. */
|
|
239
|
+
locale?: string | undefined;
|
|
240
|
+
};
|
|
241
|
+
/** Read a number an agent spelled its own way. */
|
|
242
|
+
export declare const normalizeNumber: (input: unknown, options?: NumberOptions) => Normalized<number>;
|
|
243
|
+
type NumberInRangeOptions = NumberOptions & {
|
|
244
|
+
minimum?: number | undefined;
|
|
245
|
+
maximum?: number | undefined;
|
|
246
|
+
/** A count: a fraction asks, since 12.5 results is no page size and
|
|
247
|
+
* rounding either way would be a guess. */
|
|
248
|
+
integer?: boolean | undefined;
|
|
249
|
+
};
|
|
250
|
+
/**
|
|
251
|
+
* Read a bounded count (a page size, a result limit) and clamp it into range.
|
|
252
|
+
*
|
|
253
|
+
* `limit: 500` against a cap of 100 has one sensible reading, the most the
|
|
254
|
+
* tool returns, and asking would cost a round trip to learn a number the note
|
|
255
|
+
* can state. The caller decides which fields clamp: a monetary amount out of
|
|
256
|
+
* range is a mistake to ask about, not a value to move.
|
|
257
|
+
*/
|
|
258
|
+
export declare const normalizeNumberInRange: (input: unknown, options: NumberInRangeOptions) => Normalized<number>;
|
|
259
|
+
//#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
|
+
//#region src/uuid.d.ts
|
|
274
|
+
/** Documentation uuids a model reproduces when it has no real id: RFC 4122
|
|
275
|
+
* and RFC 9562 examples, and the ones tutorials and SDK docs print. */
|
|
276
|
+
export declare const SENTINEL_UUIDS: readonly ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426655440000", "01234567-89ab-cdef-0123-456789abcdef", "12345678-1234-1234-1234-123456789012", "12345678-1234-5678-1234-567812345678", "12345678-90ab-cdef-1234-567890abcdef", "00000000-0000-0000-0000-000000000001"];
|
|
277
|
+
/** Whether a canonical uuid is one a model writes for "some id" rather than a
|
|
278
|
+
* record's: nil, max, one repeated digit, or a documentation example. */
|
|
279
|
+
export declare const isSentinelUuid: (canonical: string) => boolean;
|
|
280
|
+
type UuidOptions = {
|
|
281
|
+
/** What the id names, for `expected`: "a matter id". */
|
|
282
|
+
expected?: string | undefined;
|
|
283
|
+
/** The corrective call, when the caller has a better one than the default. */
|
|
284
|
+
hint?: string | undefined;
|
|
285
|
+
};
|
|
286
|
+
/** Read an id an agent spelled its own way, as a lowercase dashed uuid. A
|
|
287
|
+
* placeholder or an invented id is no value. */
|
|
288
|
+
export declare const normalizeUuid: (input: unknown, options?: UuidOptions) => NormalizedOptional<string>;
|
|
289
|
+
//#endregion
|
|
290
|
+
//#region src/vocabulary.d.ts
|
|
291
|
+
/** One allowed value, plus the other names it goes by in the data. */
|
|
292
|
+
type VocabularyEntry = {
|
|
293
|
+
value: string;
|
|
294
|
+
aliases?: readonly string[];
|
|
295
|
+
};
|
|
296
|
+
type VocabularyOptions = {
|
|
297
|
+
/** What the set is called in the ask: "The courts". */
|
|
298
|
+
label?: string;
|
|
299
|
+
/** What the set is, as a noun phrase for `expected`: "a court name". */
|
|
300
|
+
expected?: string;
|
|
301
|
+
/** How many values an ask names before "and N more". */
|
|
302
|
+
maxListed?: number;
|
|
303
|
+
};
|
|
304
|
+
/**
|
|
305
|
+
* Read one value of a vocabulary drawn from data. A placeholder is no value; a
|
|
306
|
+
* spelling that narrows to one entry reads as it with a note; a spelling that
|
|
307
|
+
* matches several, or none, asks and names what there is.
|
|
308
|
+
*/
|
|
309
|
+
export declare const normalizeVocabularyValue: (input: unknown, entries: readonly VocabularyEntry[], options?: VocabularyOptions) => NormalizedOptional<string>;
|
|
310
|
+
//#endregion
|
|
311
|
+
//#region src/schema.d.ts
|
|
312
|
+
export declare const AGENT_INPUT_NORMALIZATION_KEY = "x-stella-agent-input";
|
|
313
|
+
export declare const AGENT_INPUT_NORMALIZATION_KIND: {
|
|
314
|
+
readonly boolean: "boolean";
|
|
315
|
+
readonly country: "country";
|
|
316
|
+
readonly date: "date";
|
|
317
|
+
readonly dateFormat: "date-format";
|
|
318
|
+
readonly eli: "eli";
|
|
319
|
+
readonly enum: "enum";
|
|
320
|
+
readonly filter: "filter";
|
|
321
|
+
readonly locale: "locale";
|
|
322
|
+
readonly number: "number";
|
|
323
|
+
readonly stringList: "string-list";
|
|
324
|
+
readonly uuid: "uuid";
|
|
325
|
+
};
|
|
326
|
+
type AgentInputNormalizationKind = (typeof AGENT_INPUT_NORMALIZATION_KIND)[keyof typeof AGENT_INPUT_NORMALIZATION_KIND];
|
|
327
|
+
/**
|
|
328
|
+
* What a country field needs beyond its kind: which ISO spelling the surface
|
|
329
|
+
* stores, and the codes it holds law for, so the ask names the tool to call and
|
|
330
|
+
* the values there are to ask for.
|
|
331
|
+
*/
|
|
332
|
+
type AgentInputCountryAnnotation = {
|
|
333
|
+
spelling: CountrySpelling;
|
|
334
|
+
admitted?: readonly string[];
|
|
335
|
+
tool?: string;
|
|
336
|
+
};
|
|
337
|
+
type AgentInputAnnotationCommon = {
|
|
338
|
+
/** Preserve invalid input only when the owning handler deliberately repairs it. */
|
|
339
|
+
invalidValueDisposition?: "handler-owned";
|
|
340
|
+
/** Locale context disambiguates numeric grouping and adds named date months. */
|
|
341
|
+
locale?: string;
|
|
342
|
+
/**
|
|
343
|
+
* A `date` field that is one end of a range: a bare year or month then names
|
|
344
|
+
* its first or last day, and an open-ended sentinel (`0001-01-01`,
|
|
345
|
+
* `9999-12-31`) reads as no bound.
|
|
346
|
+
*/
|
|
347
|
+
bound?: "start" | "end";
|
|
348
|
+
/**
|
|
349
|
+
* A `number` field whose range is a server limit rather than a meaning, such
|
|
350
|
+
* as a page size: a value outside it is clamped with a note instead of
|
|
351
|
+
* refused.
|
|
352
|
+
*/
|
|
353
|
+
range?: "clamp";
|
|
354
|
+
};
|
|
355
|
+
/**
|
|
356
|
+
* A kind, plus whatever that kind cannot be read without.
|
|
357
|
+
*
|
|
358
|
+
* `country` is a union branch rather than an optional property because it has
|
|
359
|
+
* two canonical spellings and no default between them: a field declared
|
|
360
|
+
* `{ kind: "country" }` alone would type-check and then have nothing to say
|
|
361
|
+
* about which code to store.
|
|
362
|
+
*/
|
|
363
|
+
type AgentInputNormalizationAnnotation = (AgentInputAnnotationCommon & {
|
|
364
|
+
kind: Exclude<AgentInputNormalizationKind, typeof AGENT_INPUT_NORMALIZATION_KIND.country>;
|
|
365
|
+
country?: never;
|
|
366
|
+
}) | (AgentInputAnnotationCommon & {
|
|
367
|
+
kind: typeof AGENT_INPUT_NORMALIZATION_KIND.country;
|
|
368
|
+
country: AgentInputCountryAnnotation;
|
|
369
|
+
});
|
|
370
|
+
/** Attach an explicit normalization kind to a canonical JSON Schema field. */
|
|
371
|
+
export declare const agentInputNormalization: (annotation: AgentInputNormalizationAnnotation) => Record<typeof AGENT_INPUT_NORMALIZATION_KEY, AgentInputNormalizationAnnotation>;
|
|
372
|
+
/** Concise model guidance derived from the same kind dispatch executes. */
|
|
373
|
+
export declare const agentInputNormalizationGuidance: (annotation: AgentInputNormalizationAnnotation) => string;
|
|
374
|
+
/** Schema metadata shared by MCP descriptions and generated CLI help. */
|
|
375
|
+
export declare const agentInputNormalizationMetadata: (annotation: AgentInputNormalizationAnnotation, description?: string) => ReturnType<typeof agentInputNormalization> & {
|
|
376
|
+
description: string;
|
|
377
|
+
};
|
|
378
|
+
type AgentInputNormalizationIssue = {
|
|
379
|
+
path: string;
|
|
380
|
+
received: string;
|
|
381
|
+
expected: string;
|
|
382
|
+
hint: string;
|
|
383
|
+
};
|
|
384
|
+
type AgentInputNormalizationResult = {
|
|
385
|
+
ok: true;
|
|
386
|
+
value: unknown;
|
|
387
|
+
notes: readonly string[];
|
|
388
|
+
} | {
|
|
389
|
+
ok: false;
|
|
390
|
+
issues: readonly AgentInputNormalizationIssue[];
|
|
391
|
+
};
|
|
392
|
+
/** Readers a kind cannot run without, supplied by the surface that owns the
|
|
393
|
+
* data: which publisher serves each ELI jurisdiction is the corpus's, not
|
|
394
|
+
* this package's. A kind whose reader is missing is left as sent. */
|
|
395
|
+
type AgentInputReaders = {
|
|
396
|
+
eli?: EliOptions;
|
|
397
|
+
};
|
|
398
|
+
/**
|
|
399
|
+
* What a placeholder in an optional property means. On a read it is "not
|
|
400
|
+
* filtering", so the property is dropped with a note. On a write an optional
|
|
401
|
+
* id can switch what the call does (update this record, or create one), and a
|
|
402
|
+
* placeholder there is an intent nobody stated, so it is asked about.
|
|
403
|
+
*/
|
|
404
|
+
type AgentInputPlaceholderPolicy = "absent" | "ask";
|
|
405
|
+
/**
|
|
406
|
+
* Normalize one agent-written value from its canonical JSON Schema. Standard
|
|
407
|
+
* `type`, `format: date`, and string `enum` keywords are the annotations for
|
|
408
|
+
* numbers, booleans, dates, and closed vocabularies. The extension key handles
|
|
409
|
+
* kinds JSON Schema cannot name, such as locales and date-format specs.
|
|
410
|
+
*/
|
|
411
|
+
export declare const normalizeAgentInput: ({ path, placeholders, readers, schema, value }: {
|
|
412
|
+
path?: string;
|
|
413
|
+
/** What a placeholder in an optional property means; see the type. */
|
|
414
|
+
placeholders?: AgentInputPlaceholderPolicy;
|
|
415
|
+
readers?: AgentInputReaders;
|
|
416
|
+
schema: unknown;
|
|
417
|
+
value: unknown;
|
|
418
|
+
}) => AgentInputNormalizationResult;
|
|
419
|
+
//#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 };
|