@node-llm/core 1.17.1 → 1.18.0

package/dist/judge/Judge.d.ts

@@ -0,0 +1,107 @@
+import { NodeLLMCore } from "../llm.js";
+import { JudgmentInput } from "../providers/Provider.js";
+import { LazyValue } from "../agent/Agent.js";
+import { QuestionMap } from "./Question.js";
+import { JudgmentResult } from "./Judgment.js";
+/** The questions a Judge class declares, once resolved. */
+export type QuestionsOf<T> = T extends {
+    questions: infer Q;
+} ? Q extends (...args: never[]) => infer R ? R extends QuestionMap ? R : never : Q extends QuestionMap ? Q : never : never;
+export interface JudgeCallOptions<I = Record<string, unknown>> {
+    /** Values for the inputs the judge declares; available to lazy settings. */
+    inputs?: I;
+    /** Overrides the judge's model for this call. */
+    model?: string;
+    /** Overrides the judge's provider for this call. */
+    provider?: string;
+    /** Merged over the judge's own providerOptions. */
+    providerOptions?: Record<string, unknown>;
+    requestTimeout?: number;
+    /** The NodeLLM instance to judge with. Defaults to the global NodeLLM. */
+    llm?: NodeLLMCore;
+}
+/**
+ * A reusable set of typed questions about your application data.
+ *
+ * Subclass it and declare `questions`; call `judge` with the input. Answers are
+ * typed from the declaration, so a choice's answer is a union of its options.
+ *
+ * @example
+ * class TicketTriage extends Judge {
+ *   static questions = {
+ *     urgent: probability("Does this need attention today?"),
+ *     department: choice("Which team should handle this?", {
+ *       billing: "Payments and refunds",
+ *       technical: "Bugs and integrations",
+ *       other: null
+ *     }),
+ *     frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ *   };
+ * }
+ *
+ * const judgment = await TicketTriage.judge("Please refund the duplicate charge today.");
+ * judgment.urgent.probability;  // number
+ * judgment.department.choice;   // "billing" | "technical" | "other"
+ *
+ * Settings can depend on runtime data. Declare the inputs a judge needs and
+ * pass them to `judge`; `questions`, `model` and `providerOptions` may be
+ * functions of those inputs, resolved once per judgment.
+ *
+ * @example
+ * class TeamRouter extends Judge {
+ *   static inputs = ["teams"] as const;
+ *   static questions = ({ teams }: { teams: Team[] }) => ({
+ *     team: choice("Which team should handle this?",
+ *       Object.fromEntries(teams.map((t) => [t.slug, t.description])))
+ *   });
+ * }
+ * await TeamRouter.judge(ticket.body, { inputs: { teams } });
+ */
+export declare abstract class Judge {
+    /** The judgment model. Defaults to the instance default, then `jev-latest`. */
+    static model?: LazyValue<string, never>;
+    /** Routes to a specific provider; normally inferred from the model. */
+    static provider?: string;
+    /** Names of the inputs `judge` must be given. */
+    static inputs?: readonly string[];
+    /** The questions, or a function of the declared inputs returning them. */
+    static questions: LazyValue<QuestionMap, never>;
+    /** Provider-specific request fields, or a function of the inputs. */
+    static providerOptions?: LazyValue<Record<string, unknown>, never>;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    static judge<T extends typeof Judge, I extends Record<string, unknown> = Record<string, unknown>>(this: T, input: LazyValue<JudgmentInput, I>, options?: JudgeCallOptions<I>): Promise<JudgmentResult<QuestionsOf<T>>>;
+}
+/**
+ * Defines a judge without a class, mirroring `defineAgent`.
+ *
+ * @example
+ * const Urgency = defineJudge({
+ *   questions: { urgent: probability("Does this need attention today?") }
+ * });
+ * (await Urgency.judge("The site is down")).urgent.probability;
+ */
+export declare function defineJudge<const Q extends QuestionMap>(definition: {
+    questions: LazyValue<Q, never>;
+    model?: LazyValue<string, never>;
+    provider?: string;
+    inputs?: readonly string[];
+    providerOptions?: LazyValue<Record<string, unknown>, never>;
+}): {
+    new (): {};
+    questions: LazyValue<Q, never>;
+    model: LazyValue<string, never> | undefined;
+    provider: string | undefined;
+    inputs: readonly string[] | undefined;
+    providerOptions: LazyValue<Record<string, unknown>, never> | undefined;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    judge<T extends typeof Judge, I extends Record<string, unknown> = Record<string, unknown>>(this: T, input: LazyValue<JudgmentInput, I>, options?: JudgeCallOptions<I>): Promise<JudgmentResult<QuestionsOf<T>>>;
+};
+//# sourceMappingURL=Judge.d.ts.map

package/dist/judge/Judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Judge.d.ts","sourceRoot":"","sources":["../../src/judge/Judge.ts"],"names":[],"mappings":"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"}

package/dist/judge/Judge.js

@@ -0,0 +1,104 @@
+import { NodeLLM } from "../llm.js";
+/**
+ * A reusable set of typed questions about your application data.
+ *
+ * Subclass it and declare `questions`; call `judge` with the input. Answers are
+ * typed from the declaration, so a choice's answer is a union of its options.
+ *
+ * @example
+ * class TicketTriage extends Judge {
+ *   static questions = {
+ *     urgent: probability("Does this need attention today?"),
+ *     department: choice("Which team should handle this?", {
+ *       billing: "Payments and refunds",
+ *       technical: "Bugs and integrations",
+ *       other: null
+ *     }),
+ *     frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ *   };
+ * }
+ *
+ * const judgment = await TicketTriage.judge("Please refund the duplicate charge today.");
+ * judgment.urgent.probability;  // number
+ * judgment.department.choice;   // "billing" | "technical" | "other"
+ *
+ * Settings can depend on runtime data. Declare the inputs a judge needs and
+ * pass them to `judge`; `questions`, `model` and `providerOptions` may be
+ * functions of those inputs, resolved once per judgment.
+ *
+ * @example
+ * class TeamRouter extends Judge {
+ *   static inputs = ["teams"] as const;
+ *   static questions = ({ teams }: { teams: Team[] }) => ({
+ *     team: choice("Which team should handle this?",
+ *       Object.fromEntries(teams.map((t) => [t.slug, t.description])))
+ *   });
+ * }
+ * await TeamRouter.judge(ticket.body, { inputs: { teams } });
+ */
+export class Judge {
+    /** The judgment model. Defaults to the instance default, then `jev-latest`. */
+    static model;
+    /** Routes to a specific provider; normally inferred from the model. */
+    static provider;
+    /** Names of the inputs `judge` must be given. */
+    static inputs;
+    /** The questions, or a function of the declared inputs returning them. */
+    static questions;
+    /** Provider-specific request fields, or a function of the inputs. */
+    static providerOptions;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    static async judge(input, options = {}) {
+        const inputs = (options.inputs ?? {});
+        checkInputs(this, inputs);
+        const resolve = (value) => typeof value === "function" ? value(inputs) : value;
+        const questions = resolve(this.questions);
+        if (!questions) {
+            throw new Error(`${this.name} declares no questions`);
+        }
+        const declaredOptions = resolve(this.providerOptions);
+        const providerOptions = declaredOptions || options.providerOptions
+            ? { ...declaredOptions, ...options.providerOptions }
+            : undefined;
+        const llm = options.llm ?? NodeLLM;
+        return llm.judge(resolve(input), {
+            questions: questions,
+            model: options.model ?? resolve(this.model),
+            provider: options.provider ?? this.provider,
+            providerOptions,
+            requestTimeout: options.requestTimeout
+        });
+    }
+}
+function checkInputs(judge, inputs) {
+    const declared = judge.inputs ?? [];
+    const given = Object.keys(inputs);
+    const missing = declared.filter((name) => !(name in inputs));
+    const unknown = given.filter((name) => !declared.includes(name));
+    if (missing.length > 0)
+        throw new Error(`${judge.name} is missing inputs: ${missing.join(", ")}`);
+    if (unknown.length > 0)
+        throw new Error(`${judge.name} does not declare inputs: ${unknown.join(", ")}`);
+}
+/**
+ * Defines a judge without a class, mirroring `defineAgent`.
+ *
+ * @example
+ * const Urgency = defineJudge({
+ *   questions: { urgent: probability("Does this need attention today?") }
+ * });
+ * (await Urgency.judge("The site is down")).urgent.probability;
+ */
+export function defineJudge(definition) {
+    return class extends Judge {
+        static questions = definition.questions;
+        static model = definition.model;
+        static provider = definition.provider;
+        static inputs = definition.inputs;
+        static providerOptions = definition.providerOptions;
+    };
+}

package/dist/judge/Judgment.d.ts

@@ -0,0 +1,116 @@
+import { JudgmentResponse, Usage } from "../providers/Provider.js";
+import { ChoiceQuestion, Description, ProbabilityQuestion, NamedQuestion, QuestionDefinition, QuestionMap, ScoreQuestion } from "./Question.js";
+/** The probability that a yes/no statement holds, between 0 and 1. */
+export declare class ProbabilityAnswer {
+    readonly probability: number;
+    readonly type: "probability";
+    constructor(probability: number);
+    toJSON(): {
+        type: "probability";
+        probability: number;
+    };
+}
+/**
+ * The selected option, with a probability for every option. `confidence`
+ * describes how concentrated the distribution is; it is not a guarantee that
+ * the choice is correct.
+ */
+export declare class ChoiceAnswer<K extends string = string> {
+    readonly choice: K;
+    readonly probabilities: Readonly<Record<K, number>>;
+    readonly confidence: number;
+    readonly type: "choice";
+    constructor(choice: K, probabilities: Readonly<Record<K, number>>, confidence: number);
+    toJSON(): {
+        type: "choice";
+        choice: K;
+        probabilities: Readonly<Record<K, number>>;
+        confidence: number;
+    };
+}
+/**
+ * A probability-weighted position on an ordered scale. Level 0 is the first
+ * level, so with three levels the score runs from 0 to 2 and can fall between
+ * them. `probabilities` is keyed by level index.
+ */
+export declare class ScoreAnswer {
+    readonly score: number;
+    readonly levels: readonly Description[];
+    readonly probabilities: Readonly<Record<number, number>>;
+    readonly confidence: number;
+    readonly type: "score";
+    constructor(score: number, levels: readonly Description[], probabilities: Readonly<Record<number, number>>, confidence: number);
+    toJSON(): {
+        type: "score";
+        score: number;
+        levels: readonly Description[];
+        probabilities: Readonly<Record<number, number>>;
+        confidence: number;
+    };
+}
+export type Answer = ProbabilityAnswer | ChoiceAnswer | ScoreAnswer;
+/** The answer type a question produces. */
+export type AnswerFor<D extends QuestionDefinition> = D extends ProbabilityQuestion ? ProbabilityAnswer : D extends ChoiceQuestion<infer K> ? ChoiceAnswer<K> : D extends ScoreQuestion ? ScoreAnswer : never;
+/** Answers keyed by question name, typed from the questions asked. */
+export type AnswersOf<Q extends QuestionMap> = {
+    readonly [N in keyof Q]: AnswerFor<Q[N]>;
+};
+/**
+ * The typed answers to a set of questions, with the model that answered them
+ * and the tokens it used.
+ *
+ * Answers are available by name - `judgment.urgent.probability` - and through
+ * `judgment.answers`. A question named like one of Judgment's own members
+ * (`model`, `usage`, `get`, ...) is only reachable through `answers` or `get`.
+ */
+export declare class Judgment<Q extends QuestionMap = QuestionMap> {
+    readonly answers: AnswersOf<Q>;
+    /** The model that answered, as reported by the provider. */
+    readonly model: string;
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    readonly usage: Usage;
+    /** The provider's raw response. */
+    readonly raw?: unknown | undefined;
+    constructor(answers: AnswersOf<Q>, 
+    /** The model that answered, as reported by the provider. */
+    model: string, 
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    usage: Usage, 
+    /** The provider's raw response. */
+    raw?: unknown | undefined);
+    /** Returns the named answer, or undefined when there is none. */
+    get<N extends keyof Q & string>(name: N): AnswersOf<Q>[N] | undefined;
+    /** Returns the named answer, throwing when there is none. */
+    fetch<N extends keyof Q & string>(name: N): AnswersOf<Q>[N];
+    [Symbol.iterator](): IterableIterator<[keyof Q & string, Answer]>;
+    toJSON(): {
+        model: string;
+        answers: {
+            [k: string]: {
+                type: "probability";
+                probability: number;
+            } | {
+                type: "score";
+                score: number;
+                levels: readonly Description[];
+                probabilities: Readonly<Record<number, number>>;
+                confidence: number;
+            } | {
+                type: "choice";
+                choice: string;
+                probabilities: Readonly<Record<string, number>>;
+                confidence: number;
+            };
+        };
+        usage: Usage;
+    };
+}
+/** A Judgment whose answers can also be read directly by question name. */
+export type JudgmentResult<Q extends QuestionMap = QuestionMap> = Judgment<Q> & Omit<AnswersOf<Q>, keyof Judgment<Q>>;
+/**
+ * Wraps a provider's answers in typed, frozen answer objects. Every question
+ * must come back answered with the type it was asked as; anything else means
+ * the provider and the request disagree, and is reported rather than guessed.
+ */
+export declare function buildJudgment<Q extends QuestionMap>(response: JudgmentResponse, questions: NamedQuestion[]): JudgmentResult<Q>;
+//# sourceMappingURL=Judgment.d.ts.map

package/dist/judge/Judgment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Judgment.d.ts","sourceRoot":"","sources":["../../src/judge/Judgment.ts"],"names":[],"mappings":"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"}

package/dist/judge/Judgment.js

@@ -0,0 +1,159 @@
+/** The probability that a yes/no statement holds, between 0 and 1. */
+export class ProbabilityAnswer {
+    probability;
+    type = "probability";
+    constructor(probability) {
+        this.probability = probability;
+        Object.freeze(this);
+    }
+    toJSON() {
+        return { type: this.type, probability: this.probability };
+    }
+}
+/**
+ * The selected option, with a probability for every option. `confidence`
+ * describes how concentrated the distribution is; it is not a guarantee that
+ * the choice is correct.
+ */
+export class ChoiceAnswer {
+    choice;
+    probabilities;
+    confidence;
+    type = "choice";
+    constructor(choice, probabilities, confidence) {
+        this.choice = choice;
+        this.probabilities = probabilities;
+        this.confidence = confidence;
+        Object.freeze(this.probabilities);
+        Object.freeze(this);
+    }
+    toJSON() {
+        return {
+            type: this.type,
+            choice: this.choice,
+            probabilities: this.probabilities,
+            confidence: this.confidence
+        };
+    }
+}
+/**
+ * A probability-weighted position on an ordered scale. Level 0 is the first
+ * level, so with three levels the score runs from 0 to 2 and can fall between
+ * them. `probabilities` is keyed by level index.
+ */
+export class ScoreAnswer {
+    score;
+    levels;
+    probabilities;
+    confidence;
+    type = "score";
+    constructor(score, levels, probabilities, confidence) {
+        this.score = score;
+        this.levels = levels;
+        this.probabilities = probabilities;
+        this.confidence = confidence;
+        Object.freeze(this.levels);
+        Object.freeze(this.probabilities);
+        Object.freeze(this);
+    }
+    toJSON() {
+        return {
+            type: this.type,
+            score: this.score,
+            levels: this.levels,
+            probabilities: this.probabilities,
+            confidence: this.confidence
+        };
+    }
+}
+/**
+ * The typed answers to a set of questions, with the model that answered them
+ * and the tokens it used.
+ *
+ * Answers are available by name - `judgment.urgent.probability` - and through
+ * `judgment.answers`. A question named like one of Judgment's own members
+ * (`model`, `usage`, `get`, ...) is only reachable through `answers` or `get`.
+ */
+export class Judgment {
+    answers;
+    model;
+    usage;
+    raw;
+    constructor(answers, 
+    /** The model that answered, as reported by the provider. */
+    model, 
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    usage, 
+    /** The provider's raw response. */
+    raw) {
+        this.answers = answers;
+        this.model = model;
+        this.usage = usage;
+        this.raw = raw;
+        Object.freeze(this.answers);
+        for (const name of Object.keys(answers)) {
+            if (name in this)
+                continue;
+            Object.defineProperty(this, name, {
+                value: answers[name],
+                enumerable: false
+            });
+        }
+        Object.freeze(this);
+    }
+    /** Returns the named answer, or undefined when there is none. */
+    get(name) {
+        return Object.prototype.hasOwnProperty.call(this.answers, name)
+            ? this.answers[name]
+            : undefined;
+    }
+    /** Returns the named answer, throwing when there is none. */
+    fetch(name) {
+        const answer = this.get(name);
+        if (answer === undefined)
+            throw new Error(`No answer named '${name}' in this judgment`);
+        return answer;
+    }
+    *[Symbol.iterator]() {
+        for (const [name, answer] of Object.entries(this.answers)) {
+            yield [name, answer];
+        }
+    }
+    toJSON() {
+        return {
+            model: this.model,
+            answers: Object.fromEntries(Object.entries(this.answers).map(([name, answer]) => [name, answer.toJSON()])),
+            usage: this.usage
+        };
+    }
+}
+/**
+ * Wraps a provider's answers in typed, frozen answer objects. Every question
+ * must come back answered with the type it was asked as; anything else means
+ * the provider and the request disagree, and is reported rather than guessed.
+ */
+export function buildJudgment(response, questions) {
+    const answers = {};
+    for (const question of questions) {
+        const data = response.answers[question.name];
+        if (!data)
+            throw new Error(`The provider returned no answer for '${question.name}'`);
+        if (data.type !== question.type) {
+            throw new Error(`The provider answered '${question.name}' as a ${data.type}, but it was asked as a ${question.type}`);
+        }
+        switch (data.type) {
+            case "probability":
+                answers[question.name] = new ProbabilityAnswer(data.probability);
+                break;
+            case "choice":
+                answers[question.name] = new ChoiceAnswer(data.choice, { ...data.probabilities }, data.confidence);
+                break;
+            case "score":
+                // Copy the levels: the answer is frozen, and freezing the caller's own
+                // question definition would be a surprising side effect.
+                answers[question.name] = new ScoreAnswer(data.score, structuredClone(question.levels), { ...data.probabilities }, data.confidence);
+                break;
+        }
+    }
+    return new Judgment(answers, response.model, response.usage, response.raw);
+}

package/dist/judge/Question.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Typed questions for judgments.
+ *
+ * A judgment asks a set of named questions about one input and returns a typed
+ * answer for each: the probability that a statement holds, a choice among named
+ * options, or a score on an ordered scale. Questions are plain data, so they
+ * can be declared on a Judge class, passed to NodeLLM.judge, or built at
+ * runtime from application data.
+ */
+/** A JSON-compatible value, used for descriptions and structured input. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Describes a question, an option, or a level. Text is usual; an object or
+ * array carries structured instructions, and null means "no description".
+ */
+export type Description = string | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** The yes/no boundary of a probability question. Either side is optional. */
+export interface ProbabilityCriteria {
+    yes?: Description;
+    no?: Description;
+}
+export interface ProbabilityQuestion {
+    type: "probability";
+    instructions?: Description;
+    criteria?: ProbabilityCriteria;
+}
+export interface ChoiceQuestion<K extends string = string> {
+    type: "choice";
+    instructions?: Description;
+    options: Record<K, Description>;
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions?: Description;
+    levels: Description[];
+}
+export type QuestionDefinition = ProbabilityQuestion | ChoiceQuestion | ScoreQuestion;
+/** Questions keyed by the name your code reads the answer from. */
+export type QuestionMap = Record<string, QuestionDefinition>;
+/** A question after validation, carrying its name for the provider. */
+export type NamedQuestion = QuestionDefinition & {
+    name: string;
+};
+/**
+ * Declares a yes/no question whose answer is the probability of yes. A value
+ * near 0.5 means yes and no are about equally likely, not "medium"; use a
+ * score to measure degree.
+ *
+ * @example
+ * probability("Does this need attention today?", {
+ *   yes: "An explicit deadline today or an ongoing outage",
+ *   no: "A general question with no time pressure"
+ * })
+ */
+export declare function probability(instructions?: Description, criteria?: ProbabilityCriteria): ProbabilityQuestion;
+/**
+ * Declares a question that selects one named option and returns a probability
+ * for every option. Include a catch-all such as `other` when none of the
+ * specific options may fit. Use null for an option that needs no description.
+ *
+ * @example
+ * choice("Which team should handle this?", {
+ *   billing: "Payments and refunds",
+ *   technical: "Bugs and integrations",
+ *   other: null
+ * })
+ */
+export declare function choice<const O extends Record<string, Description>>(instructions: Description | undefined, options: O): ChoiceQuestion<Extract<keyof O, string>>;
+/**
+ * Declares a question scored against ordered levels. The first level is 0, the
+ * second 1, and so on; the answer is probability-weighted and can fall between
+ * levels. Describe each level concretely.
+ *
+ * @example
+ * score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ */
+export declare function score(instructions: Description | undefined, levels: Description[]): ScoreQuestion;
+/**
+ * Validates every question and returns them in declaration order with their
+ * names attached. Rejects the problems a provider would otherwise report as an
+ * opaque 400: unknown types, empty choices or scales, and probability criteria
+ * that describe anything other than yes and no.
+ */
+export declare function normalizeQuestions(questions: QuestionMap): NamedQuestion[];
+/** True when the value can be sent as judgment input. */
+export declare function isJudgmentInput(value: unknown): boolean;
+//# sourceMappingURL=Question.d.ts.map

package/dist/judge/Question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Question.d.ts","sourceRoot":"","sources":["../../src/judge/Question.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAErF,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,EAAE,CAAC,EAAE,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACvD,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,cAAc,GAAG,aAAa,CAAC;AAEtF,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE7D,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,YAAY,CAAC,EAAE,WAAW,EAC1B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,mBAAmB,CAErB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAChE,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,OAAO,EAAE,CAAC,GACT,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,aAAa,CAEjG;AAyCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,WAAW,GAAG,aAAa,EAAE,CAmC1E;AAuDD,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKvD"}