langfx.js 0.1.0-alpha.0

package/dist/python.js

@@ -0,0 +1,728 @@
+import { resolveSchema as resolveExternalSchema } from './schema.js';
+const CALL = Symbol('python-call');
+const DICT = Symbol('python-dict');
+const TUPLE = Symbol('python-tuple');
+const LIST = Symbol('python-list');
+/** Explicit marker for a value the model cannot provide. */
+export const UNKNOWN = Symbol('python-unknown');
+class FloatLiteral {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+function unbox(value) { return value instanceof FloatLiteral ? value.value : value; }
+function codec(schema) {
+    const result = resolveSchema(schema).python;
+    if (!result)
+        throw new TypeError("Python protocol requires a Python-capable schema. Use protocol: 'json' for JSON Schema/Zod schemas.");
+    return result;
+}
+const rawSchemas = new WeakMap();
+function resolveSchema(value) {
+    const schema = 'schema' in value ? value.schema : value;
+    return rawSchemas.has(schema) ? schema : resolveExternalSchema(value);
+}
+function references(codecs) {
+    const result = Object.create(null);
+    for (const c of codecs)
+        for (const [name, resolve] of Object.entries(c.references ?? {})) {
+            if (result[name] && result[name] !== resolve)
+                throw new TypeError(`Conflicting recursive schema ${name}.`);
+            result[name] = resolve;
+        }
+    return result;
+}
+function exampleStyles(codecs) {
+    const styles = Object.create(null);
+    for (const c of codecs)
+        for (const [name, style] of Object.entries(c.exampleStyles ?? {})) {
+            if (styles[name] && styles[name] !== style)
+                throw new TypeError(`Conflicting example style for ${name}.`);
+            styles[name] = style;
+        }
+    return Object.freeze(styles);
+}
+function make(jsonSchema, python) {
+    const schema = {
+        get jsonSchema() {
+            const pending = Object.entries(python.references ?? {});
+            if (!pending.length)
+                return jsonSchema;
+            const defs = Object.create(null), resolvers = new Map();
+            for (let i = 0; i < pending.length; i++) {
+                const [name, resolve] = pending[i];
+                if (resolvers.has(name)) {
+                    if (resolvers.get(name) !== resolve)
+                        throw new TypeError('Conflicting recursive schema.');
+                    continue;
+                }
+                resolvers.set(name, resolve);
+                const target = resolveSchema(resolve());
+                defs[name] = rawSchemas.get(target) ?? target.jsonSchema;
+                pending.push(...Object.entries(target.python?.references ?? {}));
+            }
+            return { ...jsonSchema, $defs: defs };
+        }, python: Object.freeze(python), parse: (value) => python.decode(value),
+    };
+    rawSchemas.set(schema, jsonSchema);
+    return Object.freeze(schema);
+}
+function floatRepr(value) {
+    if (Object.is(value, -0))
+        return '-0.0';
+    return Number.isInteger(value) && Math.abs(value) < 1e21 ? `${value}.0` : String(value);
+}
+function stringRepr(value) {
+    const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+    return quote + value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t').replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, c => '\\x' + c.charCodeAt(0).toString(16).padStart(2, '0')).split(quote).join('\\' + quote) + quote;
+}
+function primitive(type, jsonType, valid) {
+    return make({ type: jsonType }, { type, declarations: {}, decode(value) { if (type === 'int' && value instanceof FloatLiteral)
+            throw new TypeError('Expected int, received float literal.'); value = unbox(value); if (!valid(value))
+            throw new TypeError(`Expected ${type}.`); return value; }, encode(value) { if (!valid(value))
+            throw new TypeError(`Expected ${type}.`); if (type === 'float' && typeof value === 'number')
+            return floatRepr(value); return value === null ? 'None' : typeof value === 'boolean' ? value ? 'True' : 'False' : JSON.stringify(value); } });
+}
+export const str = primitive('str', 'string', (v) => typeof v === 'string');
+export const int = primitive('int', 'integer', (v) => typeof v === 'number' && Number.isSafeInteger(v));
+export const float = primitive('float', 'number', (v) => typeof v === 'number' && Number.isFinite(v));
+export const bool = primitive('bool', 'boolean', (v) => typeof v === 'boolean');
+export const none = primitive('NoneType', 'null', (v) => v === null);
+export function list(item, options = {}) {
+    options = { ...options };
+    const c = codec(item);
+    const checkSize = (value) => { if (options.minSize !== undefined && value.length < options.minSize || options.maxSize !== undefined && value.length > options.maxSize)
+        throw new TypeError('List length constraint failed.'); };
+    for (const n of [options.minSize, options.maxSize])
+        if (n !== undefined && (!Number.isSafeInteger(n) || n < 0))
+            throw new TypeError('Invalid list size constraint.');
+    if ((options.minSize ?? 0) > (options.maxSize ?? Infinity))
+        throw new TypeError('Invalid list size range.');
+    return make({ type: 'array', items: (rawSchemas.get(resolveSchema(item)) ?? resolveSchema(item).jsonSchema), ...(options.minSize !== undefined ? { minItems: options.minSize } : {}), ...(options.maxSize !== undefined ? { maxItems: options.maxSize } : {}) }, { type: `list[${c.type}]`, get declarations() { return c.declarations; }, get exampleStyles() { return exampleStyles([c]); }, references: references([c]),
+        decode(value) { if (!Array.isArray(value) || TUPLE in value)
+            throw new TypeError('Expected list.'); checkSize(value); return value.map(v => c.decode(v)); },
+        encode(value) { if (!Array.isArray(value) || TUPLE in value)
+            throw new TypeError('Expected list.'); checkSize(value); return `[${value.map(v => c.encode(v)).join(', ')}]`; } });
+}
+export function dict(item) {
+    const c = codec(item);
+    return make({ type: 'object', additionalProperties: (rawSchemas.get(resolveSchema(item)) ?? resolveSchema(item).jsonSchema) }, { type: `dict[str, ${c.type}]`, get declarations() { return c.declarations; }, get exampleStyles() { return exampleStyles([c]); }, references: references([c]),
+        decode(value) { if (!value || typeof value !== 'object' || Array.isArray(value) || value instanceof Set || CALL in value || value instanceof FloatLiteral)
+            throw new TypeError('Expected dictionary.'); return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, c.decode(v)])); },
+        encode(value) { if (!value || typeof value !== 'object' || Array.isArray(value) || value instanceof Set)
+            throw new TypeError('Expected dictionary.'); return `{${Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${c.encode(v)}`).join(', ')}}`; } });
+}
+function declarations(codecs) {
+    const result = Object.create(null);
+    for (const c of codecs)
+        for (const [name, declaration] of Object.entries(c.declarations)) {
+            if (Object.hasOwn(result, name) && result[name] !== declaration) {
+                // An explicit subclass relationship enriches an otherwise identical definition.
+                const plain = (text) => text.replace(/^(class [A-Za-z][A-Za-z0-9_]*)\([A-Za-z][A-Za-z0-9_]*\):/, '$1:');
+                if (plain(result[name]) !== plain(declaration) || (result[name] !== plain(result[name]) && declaration !== plain(declaration)))
+                    throw new TypeError(`Conflicting Python class ${name}.`);
+                if (declaration === plain(declaration))
+                    continue;
+            }
+            result[name] = declaration;
+        }
+    return Object.freeze(result);
+}
+/** Try declared alternatives in order, matching Python union validation. */
+export function union(...schemas) {
+    const codecs = schemas.map(s => codec(s));
+    if (new Set(codecs.map(c => c.type)).size !== codecs.length)
+        throw new TypeError('Duplicate Python union alternative.');
+    return make({ anyOf: schemas.map(s => (rawSchemas.get(resolveSchema(s)) ?? resolveSchema(s).jsonSchema)) }, { type: codecs.length === 2 && codecs.some(c => c.type === 'NoneType') ? `${codecs.find(c => c.type !== 'NoneType').type} | None` : `Union[${codecs.map(c => c.type === 'NoneType' ? 'None' : c.type).join(', ')}]`, get declarations() { return declarations(codecs); }, get exampleStyles() { return exampleStyles(codecs); }, references: references(codecs),
+        decode(value) {
+            for (const c of codecs) {
+                try {
+                    return c.decode(value);
+                }
+                catch { /* Try the declared alternatives. */ }
+            }
+            throw new TypeError('No matching union alternative.');
+        },
+        encode(value) {
+            for (const c of codecs) {
+                try {
+                    return c.encode(value);
+                }
+                catch { /* Try alternatives. */ }
+            }
+            throw new TypeError('No matching union example alternative.');
+        } });
+}
+const identifier = /^[A-Za-z][A-Za-z0-9_]*$/;
+const reserved = new Set('False None True and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield output set UNKNOWN'.split(' '));
+export function classSchema(options) {
+    const { name, create, isInstance, decompose } = options;
+    const defaults = { ...options.defaults };
+    const excluded = new Set(options.excludeFromPrompt ?? []);
+    for (const key of Object.keys(defaults))
+        if (!Object.hasOwn(options.fields, key))
+            throw new TypeError('Unknown default field.');
+    for (const key of excluded)
+        if (!Object.hasOwn(defaults, key))
+            throw new TypeError('Excluded fields require a default.');
+    if (!identifier.test(name) || reserved.has(name))
+        throw new TypeError('Invalid Python class name.');
+    const entries = Object.entries(options.fields).map(([key, schema]) => {
+        if (!identifier.test(key) || reserved.has(key))
+            throw new TypeError('Invalid Python field name.');
+        return { key, schema: resolveSchema(schema), codec: codec(schema) };
+    });
+    const extraSchema = options.extraFields ? resolveSchema(options.extraFields) : undefined;
+    const allCodecs = [...entries.map(e => e.codec), ...(options.extraFields ? [codec(options.extraFields)] : [])];
+    const lines = [];
+    if (options.description)
+        lines.push('  ' + '\"\"\"' + options.description.replaceAll('\"\"\"', '\\"\\"\\"').replaceAll('\n', '\n  ') + '\"\"\"');
+    for (const e of entries) {
+        if (excluded.has(e.key))
+            continue;
+        const description = options.fieldDescriptions?.[e.key];
+        if (description)
+            lines.push(...description.split('\n').filter(Boolean).map(line => `  # ${line}`));
+        lines.push(`  ${e.key}: ${e.codec.type}`);
+    }
+    const declaration = `class ${name}:\n${lines.length ? lines.join('\n') : '  pass'}`;
+    return make({ type: 'object', properties: Object.fromEntries(entries.map(e => [e.key, (rawSchemas.get(e.schema) ?? e.schema.jsonSchema)])), required: entries.filter(e => !Object.hasOwn(defaults, e.key)).map(e => e.key), additionalProperties: extraSchema ? (rawSchemas.get(extraSchema) ?? extraSchema.jsonSchema) : false }, {
+        type: name,
+        get declarations() {
+            const declared = { ...declarations(allCodecs) };
+            if (declared[name] !== undefined && declared[name] !== declaration)
+                throw new TypeError('Conflicting Python class name.');
+            declared[name] = declaration;
+            return Object.freeze(declared);
+        }, get exampleStyles() { return exampleStyles([{ exampleStyles: { [name]: options.exampleFormat ?? 'expanded' } }, ...allCodecs]); }, references: references(allCodecs),
+        decode(value) {
+            if (!value || typeof value !== 'object' || Array.isArray(value) || value instanceof Set || value instanceof FloatLiteral)
+                throw new TypeError(`Expected ${name}.`);
+            let fields;
+            if (CALL in value) {
+                if (value[CALL] !== name)
+                    throw new TypeError(`Expected ${name}.`);
+                fields = value.fields;
+            }
+            else {
+                if (DICT in value)
+                    throw new TypeError(`Expected ${name} constructor, received dictionary.`);
+                fields = value;
+            }
+            const extra = Object.keys(fields).filter(key => !entries.some(e => e.key === key));
+            if (extra.length && !options.extraFields)
+                throw new TypeError(`Unexpected fields for ${name}.`);
+            const parsed = Object.create(null);
+            for (const e of entries) {
+                if (!Object.hasOwn(fields, e.key)) {
+                    if (!Object.hasOwn(defaults, e.key))
+                        throw new TypeError(`Missing ${e.key}.`);
+                    parsed[e.key] = e.codec.decode(new Parser(e.codec.encode(defaults[e.key])).parse());
+                }
+                else
+                    parsed[e.key] = e.codec.decode(fields[e.key]);
+            }
+            if (options.extraFields)
+                for (const key of extra)
+                    parsed[key] = codec(options.extraFields).decode(fields[key]);
+            return create(parsed);
+        },
+        encode(value) {
+            if (!isInstance(value))
+                throw new TypeError(`Expected ${name} instance.`);
+            const fields = decompose(value);
+            const args = entries.map(e => `${e.key}=${e.codec.encode(fields[e.key])}`);
+            if (options.extraFields)
+                for (const key of Object.keys(fields)) {
+                    if (!entries.some(e => e.key === key)) {
+                        if (!identifier.test(key) || reserved.has(key))
+                            throw new TypeError('Invalid extra field name.');
+                        args.push(`${key}=${codec(options.extraFields).encode(fields[key])}`);
+                    }
+                }
+            return `${name}(${args.join(', ')})`;
+        },
+    });
+}
+export function schemaText(schema) {
+    const c = codec(schema);
+    const definitions = Object.values(c.declarations);
+    return definitions.length ? c.type + '\n\n```python\n' + definitions.join('\n\n') + '\n```' : c.type === 'NoneType' ? 'NoneType' : c.type;
+}
+export function format(schema, value) { return codec(schema).encode(value); }
+export function parse(schema, text, limits = {}) { return codec(schema).decode(new Parser(text, limits).parse()); }
+/** Restricted data grammar: no eval, attribute access, positional calls, imports or operators. */
+class Parser {
+    i = 0;
+    text;
+    maxDepth;
+    constructor(text, limits = {}) {
+        const maxChars = limits.maxChars ?? 1_048_576;
+        this.maxDepth = limits.maxDepth ?? 64;
+        for (const [name, value, cap] of [['maxChars', maxChars, 1_048_576], ['maxDepth', this.maxDepth, 64]]) {
+            if (!Number.isSafeInteger(value) || value < 1 || value > cap)
+                throw new RangeError(`${name} must be a positive integer no greater than ${cap}.`);
+        }
+        if (text.length > maxChars)
+            throw new SyntaxError('Python output exceeds size limit.');
+        this.text = text.trim();
+        if (this.text.startsWith('```')) {
+            const match = /^```(?:python)?\s*\n([\s\S]*)\n```$/.exec(this.text);
+            if (!match)
+                throw new SyntaxError('Invalid Python fence.');
+            this.text = match[1];
+        }
+        this.text = this.text.replace(/^\s*output\s*=\s*/, '');
+    }
+    space() { while (/\s/.test(this.text[this.i] ?? '') && this.i < this.text.length)
+        this.i++; }
+    take(token) { this.space(); if (this.text.startsWith(token, this.i)) {
+        this.i += token.length;
+        return true;
+    } return false; }
+    expect(token) { if (!this.take(token))
+        throw new SyntaxError(`Expected ${token}.`); }
+    name() { this.space(); const m = /^[A-Za-z][A-Za-z0-9_]*/.exec(this.text.slice(this.i)); if (!m)
+        throw new SyntaxError('Expected identifier.'); this.i += m[0].length; return m[0]; }
+    parse() { const value = this.value(0); this.space(); if (this.i !== this.text.length)
+        throw new SyntaxError('Unexpected trailing code.'); return value; }
+    value(depth) {
+        if (depth > this.maxDepth)
+            throw new SyntaxError('Python output exceeds depth limit.');
+        this.space();
+        const ch = this.text[this.i];
+        if (ch === '"' || ch === "'" || /[rR]/.test(ch ?? '') && ['"', "'"].includes(this.text[this.i + 1] ?? '')) {
+            let result = '';
+            do {
+                const raw = /[rR]/.test(this.text[this.i] ?? '');
+                if (raw)
+                    this.i++;
+                const quote = this.text[this.i++];
+                const triple = this.text.slice(this.i, this.i + 2) === quote.repeat(2);
+                if (triple)
+                    this.i += 2;
+                const end = quote.repeat(triple ? 3 : 1);
+                let closed = false;
+                while (this.i < this.text.length) {
+                    if (this.text.startsWith(end, this.i)) {
+                        this.i += end.length;
+                        closed = true;
+                        break;
+                    }
+                    const c = this.text[this.i++];
+                    if (c === '\0' || !triple && (c === '\n' || c === '\r'))
+                        throw new SyntaxError('Invalid string character.');
+                    if (c !== '\\') {
+                        result += c;
+                        continue;
+                    }
+                    const escape = this.text[this.i++];
+                    if (escape === undefined)
+                        throw new SyntaxError('Unterminated string escape.');
+                    if (raw) {
+                        result += '\\' + escape;
+                        continue;
+                    }
+                    const simple = { a: '\x07', v: '\v', n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', '\\': '\\', '"': '"', "'": "'" };
+                    if (Object.hasOwn(simple, escape))
+                        result += simple[escape];
+                    else if (escape === '\n') { /* Python line continuation. */ }
+                    else if (['x', 'u', 'U'].includes(escape)) {
+                        const length = escape === 'x' ? 2 : escape === 'u' ? 4 : 8;
+                        const digits = this.text.slice(this.i, this.i + length);
+                        if (digits.length !== length || !/^[\da-fA-F]+$/.test(digits))
+                            throw new SyntaxError('Invalid Unicode escape.');
+                        this.i += length;
+                        const point = parseInt(digits, 16);
+                        if (point > 0x10ffff)
+                            throw new SyntaxError('Invalid Unicode code point.');
+                        result += String.fromCodePoint(point);
+                    }
+                    else if (/[0-7]/.test(escape)) {
+                        const rest = /^[0-7]{0,2}/.exec(this.text.slice(this.i))[0];
+                        this.i += rest.length;
+                        result += String.fromCodePoint(parseInt(escape + rest, 8));
+                    }
+                    else
+                        throw new SyntaxError('Unsupported string escape.');
+                }
+                if (!closed)
+                    throw new SyntaxError('Unterminated string.');
+                this.space();
+            } while (['"', "'"].includes(this.text[this.i] ?? '') || /[rR]/.test(this.text[this.i] ?? '') && ['"', "'"].includes(this.text[this.i + 1] ?? ''));
+            return result;
+        }
+        if (this.take('(')) {
+            const values = [];
+            Object.defineProperty(values, TUPLE, { value: true });
+            if (this.take(')'))
+                return values;
+            values.push(this.value(depth + 1));
+            if (this.take(')'))
+                return values[0]; // Parenthesized scalar.
+            this.expect(',');
+            while (!this.take(')')) {
+                values.push(this.value(depth + 1));
+                if (this.take(')'))
+                    return values;
+                this.expect(',');
+            }
+            return values;
+        }
+        if (this.take('[')) {
+            const values = [];
+            Object.defineProperty(values, LIST, { value: true });
+            if (this.take(']'))
+                return values;
+            do {
+                values.push(this.value(depth + 1));
+                if (this.take(']'))
+                    return values;
+                this.expect(',');
+            } while (!this.take(']'));
+            return values;
+        }
+        if (this.take('{')) {
+            const values = Object.create(null);
+            Object.defineProperty(values, DICT, { value: true });
+            if (this.take('}'))
+                return values;
+            const first = this.value(depth + 1);
+            if (!this.take(':')) {
+                const elements = new Set();
+                setElement(first);
+                elements.add(first);
+                while (!this.take('}')) {
+                    this.expect(',');
+                    if (this.take('}'))
+                        break;
+                    const element = this.value(depth + 1);
+                    setElement(element);
+                    elements.add(element);
+                }
+                return elements;
+            }
+            if (typeof first !== 'string')
+                throw new SyntaxError('Dictionary keys must be unique strings.');
+            values[first] = this.value(depth + 1);
+            while (!this.take('}')) {
+                this.expect(',');
+                if (this.take('}'))
+                    break;
+                const key = this.value(depth + 1);
+                if (typeof key !== 'string' || Object.hasOwn(values, key))
+                    throw new SyntaxError('Dictionary keys must be unique strings.');
+                this.expect(':');
+                values[key] = this.value(depth + 1);
+            }
+            return values;
+        }
+        const based = /^[+-]?0(?:[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*|[oO][0-7](?:_?[0-7])*|[bB][01](?:_?[01])*)/.exec(this.text.slice(this.i));
+        if (based) {
+            this.i += based[0].length;
+            const token = based[0].replaceAll('_', '');
+            const sign = token.startsWith('-') ? -1 : 1;
+            const unsigned = token.replace(/^[+-]/, '');
+            return sign * Number(unsigned);
+        }
+        const number = /^[+-]?(?:\d(?:_?\d)*(?:\.(?:\d(?:_?\d)*)?)?|\.\d(?:_?\d)*)(?:[eE][+-]?\d(?:_?\d)*)?/.exec(this.text.slice(this.i));
+        if (number) {
+            this.i += number[0].length;
+            const token = number[0].replaceAll('_', '');
+            const floating = /[.eE]/.test(number[0]);
+            if (!floating && /^[+-]?0[0-9]*[1-9]/.test(token))
+                throw new SyntaxError('Leading zeros are invalid in decimal integers.');
+            const value = Number(token);
+            if (!Number.isFinite(value))
+                throw new SyntaxError('Nonfinite number.');
+            return floating ? new FloatLiteral(value) : value;
+        }
+        const name = this.name();
+        if (name === 'True')
+            return true;
+        if (name === 'False')
+            return false;
+        if (name === 'None')
+            return null;
+        if (name === 'UNKNOWN')
+            return UNKNOWN;
+        if (name === 'set') {
+            this.expect('(');
+            this.expect(')');
+            return new Set();
+        }
+        this.expect('(');
+        const fields = Object.create(null);
+        if (!this.take(')'))
+            do {
+                const key = this.name();
+                if (Object.hasOwn(fields, key))
+                    throw new SyntaxError('Duplicate keyword.');
+                this.expect('=');
+                fields[key] = this.value(depth + 1);
+                if (this.take(')'))
+                    break;
+                this.expect(',');
+            } while (!this.take(')'));
+        return { [CALL]: name, fields };
+    }
+}
+/** Python v2's fenced, assigned, expanded few-shot representation. */
+export function formatExample(schema, value) {
+    const data = new Parser(format(schema, value)).parse();
+    const styles = codec(schema).exampleStyles ?? {};
+    function pretty(value, level = 0, compact = false) {
+        const pad = '  '.repeat(level), child = '  '.repeat(level + 1);
+        if (value === UNKNOWN)
+            return 'UNKNOWN';
+        if (value instanceof Set)
+            return value.size ? '{' + [...value].map(v => pretty(v, level + 1, compact)).join(', ') + '}' : 'set()';
+        if (value === null)
+            return 'None';
+        if (typeof value === 'boolean')
+            return value ? 'True' : 'False';
+        if (typeof value === 'string') {
+            return stringRepr(value);
+        }
+        if (value instanceof FloatLiteral)
+            return floatRepr(value.value);
+        if (typeof value === 'number')
+            return String(value);
+        if (Array.isArray(value)) {
+            const body = value.map(v => pretty(v, level + 1, compact)).join(', ');
+            return TUPLE in value ? '(' + body + (value.length === 1 ? ',' : '') + ')' : `[${body}]`;
+        }
+        if (value && typeof value === 'object') {
+            const call = CALL in value ? value : undefined;
+            const entries = Object.entries(call ? call.fields : value);
+            compact ||= !!call && styles[call[CALL]] === 'compact';
+            const start = call ? call[CALL] + '(' : '{', end = call ? ')' : '}';
+            if (compact)
+                return start + entries.map(([k, v]) => (call ? k + '=' : pretty(k) + ': ') + pretty(v, level + 1, true)).join(', ') + end;
+            return entries.length ? `${start}\n${entries.map(([k, v]) => child + (call ? k + '=' : pretty(k) + ': ') + pretty(v, level + 1, compact)).join(',\n')}\n${pad}${end}` : start + end;
+        }
+        throw new TypeError('Unsupported example value.');
+    }
+    return '```python\noutput = ' + pretty(data) + '\n```';
+}
+/** Literal choices preserve their values in both the prompt and local validation. */
+export function literal(...values) {
+    if (!values.length)
+        throw new TypeError('At least one literal is required.');
+    for (const v of values)
+        if (typeof v === 'number' && !Number.isFinite(v))
+            throw new TypeError('Literal numbers must be finite.');
+    const repr = (v) => typeof v === 'string' ? stringRepr(v) : v === null ? 'None' : typeof v === 'boolean' ? v ? 'True' : 'False' : Object.is(v, -0) ? '-0.0' : String(v);
+    const validate = (v) => { v = unbox(v); if (!values.some(x => Object.is(x, v)))
+        throw new TypeError('Value is not a declared literal.'); return v; };
+    return make({ enum: [...values] }, { type: `Literal[${values.map(repr).join(', ')}]`, declarations: {}, decode: validate, encode: v => repr(validate(v)) });
+}
+export function integer(options = {}) { return boundedNumber(int, options); }
+export function number(options = {}) { return boundedNumber(float, options); }
+function boundedNumber(base, options) {
+    options = { ...options };
+    for (const n of [options.min, options.max])
+        if (n !== undefined && (!Number.isFinite(n) || base === int && !Number.isSafeInteger(n)))
+            throw new TypeError('Invalid numeric bound.');
+    if ((options.min ?? -Infinity) > (options.max ?? Infinity))
+        throw new TypeError('Invalid numeric range.');
+    const check = (v) => { const n = base.python.decode(v); if (options.min !== undefined && n < options.min || options.max !== undefined && n > options.max)
+        throw new TypeError('Numeric constraint failed.'); return n; };
+    const args = [options.min !== undefined ? `min=${options.min}` : '', options.max !== undefined ? `max=${options.max}` : ''].filter(Boolean);
+    return make({ ...base.jsonSchema, ...(options.min !== undefined ? { minimum: options.min } : {}), ...(options.max !== undefined ? { maximum: options.max } : {}) }, {
+        type: base.python.type + (args.length ? `(${args.join(', ')})` : ''), declarations: {}, decode: check, encode: value => base.python.encode(check(value)),
+    });
+}
+/** Uses JavaScript regex syntax; portable patterns match Python's start-anchored re.match behavior. */
+export function string(options = {}) {
+    const pattern = options.pattern === undefined ? undefined : new RegExp(`^(?:${options.pattern})`, 'u');
+    const check = (v) => { const s = str.python.decode(v); if (pattern && !pattern.test(s))
+        throw new TypeError('String pattern constraint failed.'); return s; };
+    return make({ type: 'string', ...(options.pattern !== undefined ? { pattern: `^(?:${options.pattern})` } : {}) }, {
+        type: options.pattern === undefined ? 'str' : `str(regex=${literal(options.pattern).python.encode(options.pattern)})`, declarations: {}, decode: check, encode: value => str.python.encode(check(value)),
+    });
+}
+export function record(fields) {
+    const entries = Object.entries(fields).map(([key, s]) => ({ key, schema: resolveSchema(s), codec: codec(s) }));
+    const check = (v) => { if (!v || typeof v !== 'object' || Array.isArray(v) || v instanceof Set || CALL in v || v instanceof FloatLiteral)
+        throw new TypeError('Expected record.'); const result = v; if (Object.keys(result).length !== entries.length || entries.some(e => !Object.hasOwn(result, e.key)))
+        throw new TypeError('Record fields mismatch.'); return result; };
+    return make({ type: 'object', properties: Object.fromEntries(entries.map(e => [e.key, (rawSchemas.get(e.schema) ?? e.schema.jsonSchema)])), required: entries.map(e => e.key), additionalProperties: false }, {
+        type: `{${entries.map(e => `${literal(e.key).python.encode(e.key)}: ${e.codec.type}`).join(', ')}}`, get declarations() { return declarations(entries.map(e => e.codec)); }, get exampleStyles() { return exampleStyles(entries.map(e => e.codec)); }, references: references(entries.map(e => e.codec)),
+        decode(v) { const value = check(v); return Object.fromEntries(entries.map(e => [e.key, e.codec.decode(value[e.key])])); },
+        encode(v) { const value = check(v); return `{${entries.map(e => `${str.python.encode(e.key)}: ${e.codec.encode(value[e.key])}`).join(', ')}}`; },
+    });
+}
+export function tuple(...items) {
+    const codecs = items.map(s => codec(s));
+    return make({ type: 'array', prefixItems: items.map(s => (rawSchemas.get(resolveSchema(s)) ?? resolveSchema(s).jsonSchema)), minItems: items.length, maxItems: items.length }, {
+        type: `tuple[${codecs.map(c => c.type).join(', ')}]`, get declarations() { return declarations(codecs); }, get exampleStyles() { return exampleStyles(codecs); }, references: references(codecs),
+        decode(v) { if (!Array.isArray(v) || LIST in v || v.length !== items.length)
+            throw new TypeError('Expected fixed-length tuple literal.'); return v.map((x, i) => codecs[i].decode(x)); },
+        encode(v) { if (!Array.isArray(v) || v.length !== items.length)
+            throw new TypeError('Tuple length mismatch.'); return '(' + v.map((x, i) => codecs[i].encode(x)).join(', ') + (v.length === 1 ? ',' : '') + ')'; },
+    });
+}
+/** Explicit allowed subtypes; unlike Python there is no process-wide class registry. */
+export function withSubclasses(base, ...subtypes) {
+    const all = [base, ...subtypes].map(s => codec(s));
+    return make({ anyOf: [base, ...subtypes].map(s => (rawSchemas.get(resolveSchema(s)) ?? resolveSchema(s).jsonSchema)) }, {
+        type: all[0].type,
+        get declarations() {
+            const root = all[0];
+            const result = { ...declarations(all) };
+            if (!result[root.type]?.startsWith(`class ${root.type}:`))
+                throw new TypeError('Subclass base must be a named class schema.');
+            const names = new Set([root.type]);
+            for (const child of all.slice(1)) {
+                if (names.has(child.type))
+                    throw new TypeError('Duplicate subclass registration.');
+                names.add(child.type);
+                const text = result[child.type];
+                if (!text?.startsWith(`class ${child.type}:`))
+                    throw new TypeError('Subtype must be a named class schema.');
+                result[child.type] = text.replace(`class ${child.type}:`, `class ${child.type}(${root.type}):`);
+            }
+            return Object.freeze(result);
+        }, get exampleStyles() { return exampleStyles(all); }, references: references(all),
+        decode(value) { for (const c of all) {
+            try {
+                return c.decode(value);
+            }
+            catch { /* Try allowed subtype. */ }
+        } throw new TypeError('No allowed class matched.'); },
+        encode(value) { for (const c of [...all].reverse()) {
+            try {
+                return c.encode(value);
+            }
+            catch { /* Prefer specific subtype. */ }
+        } throw new TypeError('No allowed class matched.'); },
+    });
+}
+/** Arbitrary data literals only: no constructors or executable values. */
+export const any = make({}, {
+    type: 'Any', declarations: {},
+    decode(value) {
+        if (value === UNKNOWN)
+            return UNKNOWN;
+        if (value instanceof Set)
+            return set().python.decode(value);
+        if (value instanceof FloatLiteral)
+            return value.value;
+        if (value === null || ['string', 'boolean'].includes(typeof value))
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value)))
+            return value;
+        if (Array.isArray(value))
+            return value.map(v => any.python.decode(v));
+        if (value && typeof value === 'object' && !(CALL in value))
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, any.python.decode(v)]));
+        throw new TypeError('Expected data literal.');
+    },
+    encode(value) {
+        if (value === UNKNOWN)
+            return 'UNKNOWN';
+        if (value instanceof Set)
+            return set().python.encode(value);
+        if (value === null)
+            return 'None';
+        if (typeof value === 'string')
+            return str.python.encode(value);
+        if (typeof value === 'boolean')
+            return bool.python.encode(value);
+        if (typeof value === 'number')
+            return (Number.isInteger(value) ? int : float).python.encode(value);
+        if (Array.isArray(value))
+            return '[' + value.map(v => any.python.encode(v)).join(', ') + ']';
+        if (value && typeof value === 'object' && [Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            return '{' + Object.entries(value).map(([k, v]) => `${str.python.encode(k)}: ${any.python.encode(v)}`).join(', ') + '}';
+        throw new TypeError('Expected data literal.');
+    },
+});
+/** Named forward reference. Declare the target before rendering/parsing the schema. */
+export function lazy(name, resolve) {
+    if (!identifier.test(name) || reserved.has(name))
+        throw new TypeError('Invalid lazy schema name.');
+    let rendering = false, renderingStyles = false;
+    const target = () => { const c = codec(resolve()); if (c.type !== name)
+        throw new TypeError('Lazy schema name mismatch.'); return c; };
+    return make({ $ref: `#/$defs/${name}` }, {
+        type: name, references: { [name]: resolve },
+        get exampleStyles() {
+            if (renderingStyles)
+                return {};
+            renderingStyles = true;
+            try {
+                return target().exampleStyles ?? {};
+            }
+            finally {
+                renderingStyles = false;
+            }
+        },
+        get declarations() {
+            if (rendering)
+                return {};
+            rendering = true;
+            try {
+                return target().declarations;
+            }
+            finally {
+                rendering = false;
+            }
+        },
+        decode(value) { return target().decode(value); }, encode(value) { return target().encode(value); },
+    });
+}
+/** Opt into UNKNOWN without silently widening all typed query results. */
+export function allowUnknown(schema) {
+    const c = codec(schema), resolved = resolveSchema(schema);
+    // UNKNOWN has no JSON representation; the underlying JSON contract is unchanged.
+    return make(rawSchemas.get(resolved) ?? resolved.jsonSchema, {
+        type: c.type, get declarations() { return c.declarations; }, get exampleStyles() { return exampleStyles([c]); }, references: references([c]),
+        decode(value) { return value === UNKNOWN ? UNKNOWN : c.decode(value); },
+        encode(value) { return value === UNKNOWN ? 'UNKNOWN' : c.encode(value); },
+    });
+}
+function setElement(value) {
+    value = unbox(value);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value)))
+        return value;
+    throw new TypeError('Sets support finite, safe primitive elements only.');
+}
+/** Primitive-valued sets. An explicit item schema adds local element validation. */
+export function set(item) {
+    const c = item ? codec(item) : any.python;
+    const convert = (values) => {
+        const result = new Set(), seen = new Set();
+        for (const value of values) {
+            const decoded = c.decode(value);
+            setElement(decoded);
+            // Python treats True/1 and False/0 as equal keys. Keep the first representative.
+            const key = typeof decoded === 'boolean' ? Number(decoded) : decoded;
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.add(decoded);
+            }
+        }
+        return result;
+    };
+    const resolved = item ? resolveSchema(item) : undefined;
+    return make({ type: 'array', uniqueItems: true, items: resolved ? (rawSchemas.get(resolved) ?? resolved.jsonSchema) : {} }, {
+        type: 'set', get declarations() { return c.declarations; }, get exampleStyles() { return exampleStyles([c]); }, references: references([c]),
+        decode(value) {
+            if (!(value instanceof Set) && (!Array.isArray(value) || LIST in value || TUPLE in value))
+                throw new TypeError('Expected set.');
+            return convert(value);
+        },
+        encode(value) {
+            if (!(value instanceof Set))
+                throw new TypeError('Expected Set instance.');
+            const encoded = [...convert(value)].map(v => c.encode(v));
+            return encoded.length ? '{' + encoded.join(', ') + '}' : 'set()';
+        },
+    });
+}
+//# sourceMappingURL=python.js.map