@simulacra-ai/core 0.0.1

package/dist/policies/token-limit-policy.d.ts

@@ -0,0 +1,76 @@
+import { Conversation } from "../conversations/index.ts";
+import { CancellationToken } from "../utils/async.ts";
+import { Policy, PolicyResult } from "./types.ts";
+/**
+ * Record of token usage for a single request.
+ */
+export interface TokenRecord {
+    /** When this usage occurred. */
+    timestamp: number;
+    /** Number of input tokens consumed. */
+    input_tokens: number;
+    /** Number of output tokens generated. */
+    output_tokens: number;
+}
+/**
+ * Base options for token limit policy.
+ */
+type BaseOptions = {
+    /** Time period in milliseconds for the token budget. */
+    period_ms: number;
+};
+/**
+ * Options for separate input and output token limits.
+ */
+type InputOutputTokenOptions = {
+    /** Maximum input tokens allowed per period. */
+    input_tokens_per_period: number;
+    /** Maximum output tokens allowed per period. */
+    output_tokens_per_period: number;
+};
+/**
+ * Options for a combined total token limit.
+ */
+type TotalTokenOptions = {
+    /** Maximum total tokens (input + output) allowed per period. */
+    total_tokens_per_period: number;
+};
+/**
+ * Configuration options for token limit policy.
+ *
+ * Can specify either separate input/output limits or a combined total limit.
+ */
+export type TokenLimitPolicyOptions = BaseOptions & (InputOutputTokenOptions | TotalTokenOptions);
+/**
+ * Policy that enforces token usage limits over a time period.
+ *
+ * Tracks token consumption and delays execution when limits are exceeded.
+ */
+export declare class TokenLimitPolicy extends Policy {
+    #private;
+    /**
+     * Creates a new token limit policy.
+     *
+     * @param options - The token limit configuration.
+     */
+    constructor(options: TokenLimitPolicyOptions);
+    /**
+     * Executes a function with token limit enforcement applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+    /**
+     * Attaches this policy to a conversation to track its token usage.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation: Conversation): void;
+}
+export {};
+//# sourceMappingURL=token-limit-policy.d.ts.map

package/dist/policies/token-limit-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-limit-policy.d.ts","sourceRoot":"","sources":["../../src/policies/token-limit-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAGb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAS,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,KAAK,WAAW,GAAG;IACjB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,KAAK,uBAAuB,GAAG;IAC7B,+CAA+C;IAC/C,uBAAuB,EAAE,MAAM,CAAC;IAChC,gDAAgD;IAChD,wBAAwB,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,KAAK,iBAAiB,GAAG;IACvB,gEAAgE;IAChE,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,CAAC,uBAAuB,GAAG,iBAAiB,CAAC,CAAC;AAElG;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,MAAM;;IAK1C;;;;OAIG;gBACS,OAAO,EAAE,uBAAuB;IAK5C;;;;;;;;;OASG;IACG,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC5C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IA6EjC;;;;OAIG;IACH,MAAM,CAAC,YAAY,EAAE,YAAY;CA8ClC"}

package/dist/policies/token-limit-policy.js

@@ -0,0 +1,134 @@
+import { sleep } from "../utils/async.js";
+import { Policy } from "./types.js";
+/**
+ * Policy that enforces token usage limits over a time period.
+ *
+ * Tracks token consumption and delays execution when limits are exceeded.
+ */
+export class TokenLimitPolicy extends Policy {
+    #options;
+    #usage = [];
+    /**
+     * Creates a new token limit policy.
+     *
+     * @param options - The token limit configuration.
+     */
+    constructor(options) {
+        super();
+        this.#options = options;
+    }
+    /**
+     * Executes a function with token limit enforcement applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    async execute(cancellation_token, fn, ...args) {
+        const now = Date.now();
+        this.#usage = this.#usage.filter((record) => now - record.timestamp < this.#options.period_ms);
+        const input_tokens = this.#usage.reduce((sum, record) => sum + record.input_tokens, 0);
+        const output_tokens = this.#usage.reduce((sum, record) => sum + record.output_tokens, 0);
+        const total_tokens = input_tokens + output_tokens;
+        let wait_time;
+        const options = this.#options;
+        if ("total_tokens_per_period" in options) {
+            const total_token_wait_time = this.#calculate_wait_time(total_tokens, options.total_tokens_per_period);
+            wait_time = total_token_wait_time;
+        }
+        else {
+            const input_token_wait_time = this.#calculate_wait_time(input_tokens, options.input_tokens_per_period);
+            const output_token_wait_time = this.#calculate_wait_time(output_tokens, options.output_tokens_per_period);
+            wait_time = Math.max(input_token_wait_time, output_token_wait_time);
+        }
+        const metadata = {
+            policy: TokenLimitPolicy.name,
+            ...this.#options,
+            current_period_start: now - this.#options.period_ms,
+            current_period_end: now,
+            input_tokens,
+            output_tokens,
+            total_tokens,
+            wait_time,
+            recent_usage_count: this.#usage.length,
+            recent_usage: this.#usage,
+        };
+        if ("total_tokens_per_period" in options) {
+            metadata.total_token_wait_time = wait_time;
+        }
+        else {
+            metadata.input_token_wait_time = this.#calculate_wait_time(input_tokens, options.input_tokens_per_period);
+            metadata.output_token_wait_time = this.#calculate_wait_time(output_tokens, options.output_tokens_per_period);
+        }
+        if (wait_time > 0) {
+            metadata.wait_time_ms = wait_time;
+            await sleep(wait_time, cancellation_token);
+        }
+        cancellation_token.throw_if_cancellation_requested();
+        try {
+            const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+            return {
+                result: true,
+                value,
+                metadata,
+            };
+        }
+        catch (error) {
+            return {
+                result: false,
+                error,
+                metadata,
+            };
+        }
+    }
+    /**
+     * Attaches this policy to a conversation to track its token usage.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation) {
+        conversation.on("message_complete", this.#on_message_complete);
+        conversation.on("child_event", this.#on_child_event);
+        conversation.once("dispose", () => {
+            conversation.off("message_complete", this.#on_message_complete);
+            conversation.off("child_event", this.#on_child_event);
+        });
+    }
+    #on_message_complete = ({ usage }) => {
+        const input_tokens = usage?.input_tokens || 0;
+        const output_tokens = usage?.output_tokens || 0;
+        this.#usage.push({
+            timestamp: Date.now(),
+            input_tokens,
+            output_tokens,
+        });
+    };
+    #on_child_event = (event_data) => {
+        const { event_name, event_args } = event_data;
+        if (event_name === "message_complete") {
+            const [event_data] = event_args;
+            if (event_data) {
+                this.#on_message_complete(event_data);
+            }
+        }
+        if (event_name === "child_event") {
+            const [child_event_data] = event_args;
+            this.#on_child_event(child_event_data);
+        }
+    };
+    #calculate_wait_time(current_tokens, tokens_per_period) {
+        if (current_tokens < tokens_per_period) {
+            return 0;
+        }
+        const now = Date.now();
+        const oldest = this.#usage[0];
+        if (!oldest) {
+            return 0;
+        }
+        return Math.max(0, oldest.timestamp + this.#options.period_ms - now);
+    }
+}
+//# sourceMappingURL=token-limit-policy.js.map

package/dist/policies/token-limit-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-limit-policy.js","sourceRoot":"","sources":["../../src/policies/token-limit-policy.ts"],"names":[],"mappings":"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"}

package/dist/policies/types.d.ts

@@ -0,0 +1,49 @@
+import { CancellationToken } from "../utils/async.ts";
+/**
+ * Represents a successful policy execution.
+ *
+ * @template T - The type of the result value.
+ */
+export interface PolicySuccessResult<T> {
+    result: true;
+    /** Metadata about the policy execution. */
+    metadata: object;
+    /** The value returned by the wrapped function. */
+    value: T;
+}
+/**
+ * Represents a failed policy execution.
+ */
+export interface PolicyErrorResult {
+    result: false;
+    /** Metadata about the policy execution. */
+    metadata: object;
+    /** The error that occurred. */
+    error: unknown;
+}
+/**
+ * Union of all possible policy execution results.
+ *
+ * @template T - The type of the success result value.
+ */
+export type PolicyResult<T> = PolicySuccessResult<T> | PolicyErrorResult;
+/**
+ * Base class for all policies.
+ *
+ * Policies wrap function execution to provide cross-cutting concerns like
+ * retries, rate limiting, and token budget management.
+ */
+export declare abstract class Policy {
+    /**
+     * Executes a function with this policy applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    abstract execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/policies/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policies/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,MAAM,EAAE,IAAI,CAAC;IACb,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,CAAC;IACd,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;AAEzE;;;;;GAKG;AACH,8BAAsB,MAAM;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,SAAS,OAAO,EAAE,EAC/C,kBAAkB,EAAE,iBAAiB,EACrC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,GAAG,IAAI,EAAE,KAAK,GACb,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;CAClC"}

package/dist/policies/types.js

@@ -0,0 +1,9 @@
+/**
+ * Base class for all policies.
+ *
+ * Policies wrap function execution to provide cross-cutting concerns like
+ * retries, rate limiting, and token budget management.
+ */
+export class Policy {
+}
+//# sourceMappingURL=types.js.map

package/dist/policies/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/policies/types.ts"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,MAAM,OAAgB,MAAM;CAgB3B"}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,180 @@
+import type { Conversation } from "../conversations/index.ts";
+import type { Workflow } from "../workflows/index.ts";
+/**
+ * Context provided to tools when they are executed.
+ *
+ * This interface can be extended with custom properties by passing
+ * additional data through the workflow's context_data.
+ */
+export interface ToolContext {
+    /** The conversation instance where the tool is being executed. */
+    conversation: Conversation;
+    /** The workflow instance managing the tool execution. */
+    workflow: Workflow;
+    /** Additional custom context properties. */
+    [key: string]: unknown;
+}
+/**
+ * Result indicating successful tool execution.
+ */
+export interface ToolSuccessResult {
+    result: true;
+}
+/**
+ * Result indicating failed tool execution.
+ */
+export interface ToolErrorResult {
+    result: false;
+    /** Description of what went wrong. */
+    message: string;
+    /** Optional underlying error object. */
+    error?: unknown;
+}
+/**
+ * Union of all possible tool execution results.
+ */
+export type ToolResult = ToolSuccessResult | ToolErrorResult;
+/**
+ * String parameter type definition.
+ */
+export type StringParameterType = {
+    type: "string";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "string";
+    required?: false;
+    default?: string;
+    description?: string;
+};
+/**
+ * Enumeration parameter type definition.
+ */
+export type EnumParameterType = {
+    type: "string";
+    required: true;
+    enum: string[];
+    default?: never;
+    description?: string;
+} | {
+    type: "string";
+    required?: false;
+    enum: string[];
+    default?: string;
+    description?: string;
+};
+/**
+ * Number parameter type definition.
+ */
+export type NumberParameterType = {
+    type: "number";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "number";
+    required?: false;
+    default?: number;
+    description?: string;
+};
+/**
+ * Boolean parameter type definition.
+ */
+export type BooleanParameterType = {
+    type: "boolean";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "boolean";
+    required?: false;
+    default?: boolean;
+    description?: string;
+};
+/**
+ * Union of all primitive parameter types.
+ */
+export type PrimitiveParameterType = StringParameterType | EnumParameterType | NumberParameterType | BooleanParameterType;
+/**
+ * Object parameter type definition with nested properties.
+ */
+export interface ObjectParameterType {
+    type: "object";
+    required?: boolean;
+    properties: Record<string, ParameterType>;
+    default?: never;
+    description?: string;
+}
+/**
+ * Array parameter type definition.
+ */
+export interface ArrayParameterType {
+    type: "array";
+    required?: boolean;
+    items: ParameterType;
+    default?: never;
+    description?: string;
+}
+/**
+ * Union of all parameter types.
+ */
+export type ParameterType = PrimitiveParameterType | ObjectParameterType | ArrayParameterType;
+/**
+ * A named parameter with its type definition and optional description.
+ */
+export type ToolParameterDefinition = ParameterType & {
+    name: string;
+    description?: string;
+};
+/**
+ * Complete definition of a tool including its name, description, and parameters.
+ */
+export interface ToolDefinition {
+    /** The unique name of the tool. */
+    name: string;
+    /** Description of what the tool does. */
+    description: string;
+    /** The parameters the tool accepts. */
+    parameters: ToolParameterDefinition[];
+    /** Whether this tool can be executed in parallel with other tools. */
+    parallelizable?: boolean;
+}
+/**
+ * Constructor interface for tool classes.
+ *
+ * @template TParams - The parameter type for the tool.
+ * @template TSuccessResult - The success result type.
+ * @template TErrorResult - The error result type.
+ */
+export interface ToolClass<TParams extends Record<string, unknown> = Record<string, unknown>, TSuccessResult extends ToolSuccessResult = ToolSuccessResult, TErrorResult extends ToolErrorResult = ToolErrorResult> {
+    /**
+     * Constructs a new tool instance.
+     *
+     * @param context - The context for tool execution.
+     */
+    new (context: ToolContext): Tool<TParams, TSuccessResult, TErrorResult>;
+    /**
+     * Gets the static definition of this tool.
+     *
+     * @returns The tool definition.
+     */
+    get_definition(): ToolDefinition;
+}
+/**
+ * Interface that all tools must implement.
+ *
+ * @template TParams - The parameter type for the tool.
+ * @template TSuccessResult - The success result type.
+ * @template TErrorResult - The error result type.
+ */
+export interface Tool<TParams extends Record<string, unknown> = Record<string, unknown>, TSuccessResult extends ToolSuccessResult = ToolSuccessResult, TErrorResult extends ToolErrorResult = ToolErrorResult> {
+    /**
+     * Executes the tool with the provided parameters.
+     *
+     * @param params - The parameters for tool execution.
+     * @returns A promise that resolves to either success or error result.
+     */
+    execute(params: TParams): Promise<TSuccessResult | TErrorResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

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

package/dist/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

package/dist/utils/async.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Token for monitoring and responding to cancellation requests.
+ *
+ * Provides a way to check if an operation has been cancelled and to
+ * register callbacks for when cancellation occurs.
+ */
+export declare class CancellationToken {
+    #private;
+    /**
+     * Creates a new cancellation token.
+     *
+     * @param source - Optional source that controls this token.
+     */
+    constructor(source?: CancellationTokenSource);
+    /**
+     * Whether cancellation has been requested.
+     */
+    get is_cancellation_requested(): boolean;
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event: "cancel", handler: () => void): void;
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event: "cancel", handler: () => void): void;
+    /**
+     * Throws an error if cancellation has been requested.
+     */
+    throw_if_cancellation_requested(): void;
+    /**
+     * Creates a promise that rejects when cancellation is requested.
+     *
+     * @returns A promise that never resolves but rejects on cancellation.
+     */
+    await_cancellation(): Promise<never>;
+    /**
+     * Creates an empty cancellation token that can never be cancelled.
+     *
+     * @returns A new cancellation token with no source.
+     */
+    static empty(): CancellationToken;
+}
+/**
+ * Source for creating and controlling cancellation tokens.
+ *
+ * Allows triggering cancellation for associated tokens.
+ */
+export declare class CancellationTokenSource {
+    #private;
+    /**
+     * Disposes the cancellation token source.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Gets a cancellation token associated with this source.
+     */
+    get token(): CancellationToken;
+    /**
+     * Whether cancellation has been triggered.
+     */
+    get is_cancelled(): boolean;
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event: "cancel", handler: () => void): void;
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event: "cancel", handler: () => void): void;
+    /**
+     * Triggers cancellation for all associated tokens.
+     */
+    cancel(): void;
+}
+/**
+ * Error thrown when an operation is cancelled.
+ */
+export declare class OperationCanceledError extends Error {
+    #private;
+    /**
+     * Creates a new operation cancelled error.
+     *
+     * @param token - The cancellation token associated with this error.
+     */
+    constructor(token: CancellationToken);
+    /**
+     * The cancellation token associated with this error.
+     */
+    get token(): CancellationToken;
+}
+/**
+ * Delays execution for a specified time period with cancellation support.
+ *
+ * @param ms - The number of milliseconds to sleep.
+ * @param cancellation_token - Optional token for cancelling the sleep.
+ * @returns A promise that resolves after the delay or rejects if cancelled.
+ */
+export declare function sleep(ms: number, cancellation_token?: CancellationToken): Promise<void>;
+/**
+ * Peeks at the first value from an async generator without consuming it.
+ *
+ * @template T - The type of values yielded by the generator.
+ * @param generator - The async generator to peek.
+ * @returns An object containing the peeked value and a new generator that includes it.
+ */
+export declare function peek_generator<T>(generator: AsyncGenerator<T>): Promise<{
+    peeked_value: T;
+    generator: AsyncGenerator<Awaited<T>, void, unknown>;
+}>;
+//# sourceMappingURL=async.d.ts.map

package/dist/utils/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,iBAAiB;;IAG5B;;;;OAIG;gBACS,MAAM,CAAC,EAAE,uBAAuB;IAI5C;;OAEG;IACH,IAAI,yBAAyB,YAE5B;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI;IAIzC;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI;IAIxC;;OAEG;IACH,+BAA+B;IAM/B;;;;OAIG;IACH,kBAAkB;IAMlB;;;;OAIG;IACH,MAAM,CAAC,KAAK;CAGb;AAED;;;;GAIG;AACH,qBAAa,uBAAuB;;IAOlC;;;;OAIG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;IAQhB;;OAEG;IACH,IAAI,KAAK,sBAKR;IAED;;OAEG;IACH,IAAI,YAAY,YAEf;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI;IAUzC;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,IAAI;IAIxC;;OAEG;IACH,MAAM;CAOP;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;;IAG/C;;;;OAIG;gBACS,KAAK,EAAE,iBAAiB;IAKpC;;OAEG;IACH,IAAI,KAAK,sBAER;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBvF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;kBAgBlC,CAAC;;GAGlC"}