@limo-labs/deity 0.1.0-alpha.0

package/dist/src/conversation/conversation-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-manager.js","sourceRoot":"","sources":["../../../src/conversation/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/conversation/conversation-pruner.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Pruning strategy factories for conversation management.
+ *
+ * This module provides common pruning strategies that can be used with
+ * ConversationManager.prune() to control conversation history growth.
+ *
+ * @module conversation/conversation-pruner
+ * @since 2.0.0
+ */
+import type { ConversationMessage, PruneStrategy } from "./conversation-manager.js";
+import type { LLMAdapter } from "../llm.js";
+/**
+ * Factory for creating common conversation pruning strategies.
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * // Keep only the last 50 messages
+ * const strategy = ConversationPruner.keepRecent(50);
+ * await store.prune(strategy);
+ *
+ * // Keep system messages and recent 20 messages
+ * const strategy = ConversationPruner.combine([
+ *   ConversationPruner.keepImportant((msg) => msg.message.role === "system"),
+ *   ConversationPruner.keepRecent(20),
+ * ]);
+ * await store.prune(strategy);
+ * ```
+ */
+export declare class ConversationPruner {
+    /**
+     * Keep only the most recent N messages.
+     *
+     * This is the simplest pruning strategy - just keep a fixed number
+     * of recent messages and discard older ones.
+     *
+     * @param count - Number of recent messages to keep
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * const strategy = ConversationPruner.keepRecent(100);
+     * await store.prune(strategy);
+     * ```
+     */
+    static keepRecent(count: number): PruneStrategy;
+    /**
+     * Keep messages that match a filter function.
+     *
+     * This allows you to preserve "important" messages based on custom logic.
+     * Common use cases:
+     * - Keep all system messages
+     * - Keep messages marked as important
+     * - Keep messages from specific stages
+     *
+     * @param filter - Function to determine if a message should be kept
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep all system messages
+     * const strategy = ConversationPruner.keepImportant(
+     *   (msg) => msg.message.role === "system"
+     * );
+     *
+     * // Keep messages marked as important
+     * const strategy = ConversationPruner.keepImportant(
+     *   (msg) => msg.metadata.important === true
+     * );
+     * ```
+     */
+    static keepImportant(filter: (message: ConversationMessage) => boolean): PruneStrategy;
+    /**
+     * Keep messages within a time window (in milliseconds).
+     *
+     * Messages older than the specified age will be pruned.
+     *
+     * @param maxAge - Maximum age in milliseconds
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep messages from the last hour
+     * const strategy = ConversationPruner.byAge(60 * 60 * 1000);
+     *
+     * // Keep messages from the last 7 days
+     * const strategy = ConversationPruner.byAge(7 * 24 * 60 * 60 * 1000);
+     * ```
+     */
+    static byAge(maxAge: number): PruneStrategy;
+    /**
+     * Sliding window strategy: keep recent N messages plus important ones.
+     *
+     * This combines keepRecent and keepImportant for a balanced approach:
+     * - Always keeps the last N messages for context continuity
+     * - Also preserves important messages outside the window
+     *
+     * @param windowSize - Number of recent messages to keep
+     * @param importantFilter - Optional filter for important messages
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep last 50 messages + all system messages
+     * const strategy = ConversationPruner.slidingWindow(
+     *   50,
+     *   (msg) => msg.message.role === "system"
+     * );
+     * ```
+     */
+    static slidingWindow(windowSize: number, importantFilter?: (message: ConversationMessage) => boolean): PruneStrategy;
+    /**
+     * Combine multiple pruning strategies.
+     *
+     * When multiple strategies are combined, a message is kept if it matches
+     * ANY of the strategies (OR logic).
+     *
+     * @param strategies - Array of strategies to combine
+     * @returns Combined pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep recent 20 messages OR system messages OR messages from last hour
+     * const strategy = ConversationPruner.combine([
+     *   ConversationPruner.keepRecent(20),
+     *   ConversationPruner.keepImportant((msg) => msg.message.role === "system"),
+     *   ConversationPruner.byAge(60 * 60 * 1000),
+     * ]);
+     * ```
+     */
+    static combine(strategies: PruneStrategy[]): PruneStrategy;
+    /**
+     * Summarize old messages using an LLM (advanced strategy).
+     *
+     * This strategy uses an LLM to create a condensed summary of old messages,
+     * then replaces them with a single summary message. This preserves context
+     * while significantly reducing message count.
+     *
+     * **Note:** This is an advanced strategy that involves LLM calls and
+     * may have associated costs.
+     *
+     * @param llm - LLM adapter for generating summaries
+     * @param options - Summarization options
+     * @returns Async function that performs pruning with summarization
+     *
+     * @example
+     * ```typescript
+     * const llm = new OpenAIAdapter({ apiKey: "..." });
+     *
+     * // Keep last 20 messages, summarize older ones
+     * const pruneWithSummary = ConversationPruner.summarize(llm, {
+     *   keepRecent: 20,
+     *   maxTokens: 500,
+     * });
+     *
+     * // Apply the strategy
+     * const summary = await pruneWithSummary(await store.getHistory());
+     * // Replace history with summarized version
+     * await store.clear();
+     * for (const msg of summary) {
+     *   await store.addMessage(msg.message, msg.metadata);
+     * }
+     * ```
+     */
+    static summarize(llm: LLMAdapter, options: {
+        keepRecent: number;
+        maxTokens?: number;
+        systemPrompt?: string;
+    }): (messages: ConversationMessage[]) => Promise<ConversationMessage[]>;
+    /**
+     * Create a custom pruning strategy.
+     *
+     * This is a helper for creating ad-hoc strategies with explicit options.
+     *
+     * @param options - Pruning options
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * const strategy = ConversationPruner.custom({
+     *   keepRecent: 30,
+     *   keepImportant: (msg) => msg.metadata.stageId === "critical-stage",
+     *   maxAge: 24 * 60 * 60 * 1000, // 24 hours
+     * });
+     * ```
+     */
+    static custom(options: PruneStrategy): PruneStrategy;
+}
+//# sourceMappingURL=conversation-pruner.d.ts.map

package/dist/src/conversation/conversation-pruner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-pruner.d.ts","sourceRoot":"","sources":["../../../src/conversation/conversation-pruner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa;IAM/C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,aAAa,CAClB,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,GAChD,aAAa;IAMhB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAM3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,aAAa,CAClB,UAAU,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,GAC1D,aAAa;IAOhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa;IAkC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,MAAM,CAAC,SAAS,CACd,GAAG,EAAE,UAAU,EACf,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GACA,CAAC,QAAQ,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAyDtE;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa;CAGrD"}

package/dist/src/conversation/conversation-pruner.js

@@ -0,0 +1,274 @@
+/**
+ * Pruning strategy factories for conversation management.
+ *
+ * This module provides common pruning strategies that can be used with
+ * ConversationManager.prune() to control conversation history growth.
+ *
+ * @module conversation/conversation-pruner
+ * @since 2.0.0
+ */
+/**
+ * Factory for creating common conversation pruning strategies.
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * // Keep only the last 50 messages
+ * const strategy = ConversationPruner.keepRecent(50);
+ * await store.prune(strategy);
+ *
+ * // Keep system messages and recent 20 messages
+ * const strategy = ConversationPruner.combine([
+ *   ConversationPruner.keepImportant((msg) => msg.message.role === "system"),
+ *   ConversationPruner.keepRecent(20),
+ * ]);
+ * await store.prune(strategy);
+ * ```
+ */
+export class ConversationPruner {
+    /**
+     * Keep only the most recent N messages.
+     *
+     * This is the simplest pruning strategy - just keep a fixed number
+     * of recent messages and discard older ones.
+     *
+     * @param count - Number of recent messages to keep
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * const strategy = ConversationPruner.keepRecent(100);
+     * await store.prune(strategy);
+     * ```
+     */
+    static keepRecent(count) {
+        return {
+            keepRecent: count,
+        };
+    }
+    /**
+     * Keep messages that match a filter function.
+     *
+     * This allows you to preserve "important" messages based on custom logic.
+     * Common use cases:
+     * - Keep all system messages
+     * - Keep messages marked as important
+     * - Keep messages from specific stages
+     *
+     * @param filter - Function to determine if a message should be kept
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep all system messages
+     * const strategy = ConversationPruner.keepImportant(
+     *   (msg) => msg.message.role === "system"
+     * );
+     *
+     * // Keep messages marked as important
+     * const strategy = ConversationPruner.keepImportant(
+     *   (msg) => msg.metadata.important === true
+     * );
+     * ```
+     */
+    static keepImportant(filter) {
+        return {
+            keepImportant: filter,
+        };
+    }
+    /**
+     * Keep messages within a time window (in milliseconds).
+     *
+     * Messages older than the specified age will be pruned.
+     *
+     * @param maxAge - Maximum age in milliseconds
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep messages from the last hour
+     * const strategy = ConversationPruner.byAge(60 * 60 * 1000);
+     *
+     * // Keep messages from the last 7 days
+     * const strategy = ConversationPruner.byAge(7 * 24 * 60 * 60 * 1000);
+     * ```
+     */
+    static byAge(maxAge) {
+        return {
+            maxAge,
+        };
+    }
+    /**
+     * Sliding window strategy: keep recent N messages plus important ones.
+     *
+     * This combines keepRecent and keepImportant for a balanced approach:
+     * - Always keeps the last N messages for context continuity
+     * - Also preserves important messages outside the window
+     *
+     * @param windowSize - Number of recent messages to keep
+     * @param importantFilter - Optional filter for important messages
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep last 50 messages + all system messages
+     * const strategy = ConversationPruner.slidingWindow(
+     *   50,
+     *   (msg) => msg.message.role === "system"
+     * );
+     * ```
+     */
+    static slidingWindow(windowSize, importantFilter) {
+        return {
+            keepRecent: windowSize,
+            keepImportant: importantFilter,
+        };
+    }
+    /**
+     * Combine multiple pruning strategies.
+     *
+     * When multiple strategies are combined, a message is kept if it matches
+     * ANY of the strategies (OR logic).
+     *
+     * @param strategies - Array of strategies to combine
+     * @returns Combined pruning strategy
+     *
+     * @example
+     * ```typescript
+     * // Keep recent 20 messages OR system messages OR messages from last hour
+     * const strategy = ConversationPruner.combine([
+     *   ConversationPruner.keepRecent(20),
+     *   ConversationPruner.keepImportant((msg) => msg.message.role === "system"),
+     *   ConversationPruner.byAge(60 * 60 * 1000),
+     * ]);
+     * ```
+     */
+    static combine(strategies) {
+        // Merge all strategies
+        const combined = {};
+        // Take the maximum keepRecent value
+        const keepRecentValues = strategies
+            .map((s) => s.keepRecent)
+            .filter((v) => v !== undefined);
+        if (keepRecentValues.length > 0) {
+            combined.keepRecent = Math.max(...keepRecentValues);
+        }
+        // Combine all keepImportant filters with OR logic
+        const keepImportantFilters = strategies
+            .map((s) => s.keepImportant)
+            .filter((f) => f !== undefined);
+        if (keepImportantFilters.length > 0) {
+            combined.keepImportant = (msg) => keepImportantFilters.some((filter) => filter(msg));
+        }
+        // Take the maximum maxAge value (keep messages for longer)
+        const maxAgeValues = strategies
+            .map((s) => s.maxAge)
+            .filter((v) => v !== undefined);
+        if (maxAgeValues.length > 0) {
+            combined.maxAge = Math.max(...maxAgeValues);
+        }
+        return combined;
+    }
+    /**
+     * Summarize old messages using an LLM (advanced strategy).
+     *
+     * This strategy uses an LLM to create a condensed summary of old messages,
+     * then replaces them with a single summary message. This preserves context
+     * while significantly reducing message count.
+     *
+     * **Note:** This is an advanced strategy that involves LLM calls and
+     * may have associated costs.
+     *
+     * @param llm - LLM adapter for generating summaries
+     * @param options - Summarization options
+     * @returns Async function that performs pruning with summarization
+     *
+     * @example
+     * ```typescript
+     * const llm = new OpenAIAdapter({ apiKey: "..." });
+     *
+     * // Keep last 20 messages, summarize older ones
+     * const pruneWithSummary = ConversationPruner.summarize(llm, {
+     *   keepRecent: 20,
+     *   maxTokens: 500,
+     * });
+     *
+     * // Apply the strategy
+     * const summary = await pruneWithSummary(await store.getHistory());
+     * // Replace history with summarized version
+     * await store.clear();
+     * for (const msg of summary) {
+     *   await store.addMessage(msg.message, msg.metadata);
+     * }
+     * ```
+     */
+    static summarize(llm, options) {
+        return async (messages) => {
+            if (messages.length <= options.keepRecent) {
+                return messages; // Nothing to summarize
+            }
+            // Split messages into old (to summarize) and recent (to keep)
+            const oldMessages = messages.slice(0, -options.keepRecent);
+            const recentMessages = messages.slice(-options.keepRecent);
+            // Build summarization prompt
+            const summarizationMessages = [
+                {
+                    role: "system",
+                    content: options.systemPrompt ||
+                        "You are a conversation summarizer. Create a concise summary of the conversation history that preserves key information and context.",
+                },
+                {
+                    role: "user",
+                    content: `Summarize the following conversation history:\n\n${oldMessages
+                        .map((msg) => `[${msg.message.role}]: ${JSON.stringify(msg.message.content)}`)
+                        .join("\n")}\n\nProvide a concise summary that captures the key points and context.`,
+                },
+            ];
+            // Generate summary
+            const response = await llm.generate(summarizationMessages, undefined, {
+                maxTokens: options.maxTokens || 500,
+                temperature: 0.3, // Lower temperature for consistent summaries
+            });
+            // Create summary message
+            const summaryMessage = {
+                message: {
+                    role: "system",
+                    content: `[Conversation Summary]: ${response.content}`,
+                },
+                metadata: {
+                    id: `summary-${Date.now()}`,
+                    timestamp: Date.now(),
+                    important: true,
+                    custom: {
+                        isSummary: true,
+                        originalMessageCount: oldMessages.length,
+                    },
+                },
+            };
+            // Return summary + recent messages
+            return [summaryMessage, ...recentMessages];
+        };
+    }
+    /**
+     * Create a custom pruning strategy.
+     *
+     * This is a helper for creating ad-hoc strategies with explicit options.
+     *
+     * @param options - Pruning options
+     * @returns Pruning strategy
+     *
+     * @example
+     * ```typescript
+     * const strategy = ConversationPruner.custom({
+     *   keepRecent: 30,
+     *   keepImportant: (msg) => msg.metadata.stageId === "critical-stage",
+     *   maxAge: 24 * 60 * 60 * 1000, // 24 hours
+     * });
+     * ```
+     */
+    static custom(options) {
+        return options;
+    }
+}
+//# sourceMappingURL=conversation-pruner.js.map

package/dist/src/conversation/conversation-pruner.js.map

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

package/dist/src/conversation/conversation-tree.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Conversation tree with branching support.
+ *
+ * Enables creating branches for retries, exploring alternatives,
+ * and managing complex conversation histories.
+ *
+ * @module conversation/conversation-tree
+ * @since 2.0.0
+ */
+import type { ConversationMessage, MessageMetadata } from "./conversation-manager.js";
+import type { Message } from "../component.js";
+/**
+ * A branch in the conversation tree.
+ */
+export interface ConversationBranch {
+    /** Unique branch identifier */
+    id: string;
+    /** Parent branch ID (undefined for root) */
+    parentId?: string;
+    /** Human-readable branch name */
+    name: string;
+    /** Branch point: index in parent where this branch diverged */
+    branchPoint: number;
+    /** Messages specific to this branch */
+    messages: ConversationMessage[];
+    /** Timestamp when branch was created */
+    createdAt: number;
+}
+/**
+ * Conversation tree with branching support.
+ *
+ * Useful for:
+ * - Creating branches during retries
+ * - Exploring alternative conversation paths
+ * - Rolling back to previous states
+ * - A/B testing different prompts
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const tree = new ConversationTree();
+ *
+ * // Add messages to main branch
+ * await tree.addMessage({ role: "user", content: "Hello" });
+ * await tree.addMessage({ role: "assistant", content: "Hi!" });
+ *
+ * // Create a branch for retry
+ * const retryBranch = await tree.createBranch("retry-1");
+ * await tree.addMessage({ role: "user", content: "Try again" });
+ *
+ * // Switch back to main
+ * await tree.switchBranch("main");
+ *
+ * // Get full history for current branch
+ * const history = await tree.getHistory();
+ * ```
+ */
+export declare class ConversationTree {
+    private branches;
+    private currentBranchId;
+    constructor();
+    /**
+     * Get the current branch ID.
+     */
+    getCurrentBranchId(): string;
+    /**
+     * Get a branch by ID.
+     */
+    getBranch(branchId: string): ConversationBranch | undefined;
+    /**
+     * Get all branches.
+     */
+    getAllBranches(): ConversationBranch[];
+    /**
+     * Create a new branch from the current branch.
+     *
+     * The new branch starts at the current point in the conversation.
+     * All previous messages are inherited from the parent branch.
+     *
+     * @param name - Human-readable name for the branch
+     * @returns The new branch ID
+     *
+     * @example
+     * ```typescript
+     * // Create a retry branch
+     * const retryBranch = await tree.createBranch("retry-1");
+     * tree.switchBranch(retryBranch);
+     * // Add messages to retry branch...
+     * ```
+     */
+    createBranch(name: string): string;
+    /**
+     * Switch to a different branch.
+     *
+     * Future addMessage calls will add to the specified branch.
+     *
+     * @param branchId - ID of the branch to switch to
+     */
+    switchBranch(branchId: string): void;
+    /**
+     * Add a message to the current branch.
+     *
+     * @param message - The message to add
+     * @param metadata - Optional metadata (id and timestamp will be auto-generated)
+     */
+    addMessage(message: Message, metadata?: Partial<Omit<MessageMetadata, "id" | "timestamp">>): void;
+    /**
+     * Get the full history for the current branch.
+     *
+     * Includes all messages from parent branches up to the branch point,
+     * plus messages specific to this branch.
+     *
+     * @returns Array of messages in chronological order
+     *
+     * @example
+     * ```typescript
+     * const history = tree.getHistory();
+     * console.log(`${history.length} messages in current branch`);
+     * ```
+     */
+    getHistory(): ConversationMessage[];
+    /**
+     * Get the history for a specific branch.
+     *
+     * @param branchId - ID of the branch
+     * @returns Array of messages in chronological order
+     */
+    getBranchHistory(branchId: string): ConversationMessage[];
+    /**
+     * Get child branches of a specific branch.
+     *
+     * @param branchId - ID of the parent branch
+     * @returns Array of child branches
+     */
+    getChildBranches(branchId: string): ConversationBranch[];
+    /**
+     * Delete a branch and all its children.
+     *
+     * Cannot delete the main branch.
+     *
+     * @param branchId - ID of the branch to delete
+     */
+    deleteBranch(branchId: string): void;
+    /**
+     * Merge a branch into its parent.
+     *
+     * Copies all branch-specific messages to the parent branch
+     * and deletes the child branch.
+     *
+     * @param branchId - ID of the branch to merge
+     * @returns The parent branch ID
+     *
+     * @example
+     * ```typescript
+     * // Try an alternative approach
+     * const tryBranch = tree.createBranch("alternative");
+     * tree.switchBranch(tryBranch);
+     * tree.addMessage({ role: "user", content: "Alternative prompt" });
+     *
+     * // If successful, merge back to main
+     * tree.mergeBranch(tryBranch);
+     * ```
+     */
+    mergeBranch(branchId: string): string;
+    /**
+     * Export the tree structure.
+     *
+     * @returns Object containing all branches
+     */
+    export(): {
+        branches: ConversationBranch[];
+    };
+    /**
+     * Import a tree structure.
+     *
+     * Replaces the current tree.
+     *
+     * @param data - Exported tree data
+     */
+    import(data: {
+        branches: ConversationBranch[];
+    }): void;
+}
+//# sourceMappingURL=conversation-tree.d.ts.map

package/dist/src/conversation/conversation-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-tree.d.ts","sourceRoot":"","sources":["../../../src/conversation/conversation-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAA8C;IAC9D,OAAO,CAAC,eAAe,CAAkB;;IAczC;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI3D;;OAEG;IACH,cAAc,IAAI,kBAAkB,EAAE;IAItC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAwBlC;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQpC;;;;;OAKG;IACH,UAAU,CACR,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,GAC5D,IAAI;IAkBP;;;;;;;;;;;;;OAaG;IACH,UAAU,IAAI,mBAAmB,EAAE;IAInC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAqBzD;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAMxD;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAwBpC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IA4BrC;;;;OAIG;IACH,MAAM,IAAI;QAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAA;KAAE;IAM5C;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAA;KAAE,GAAG,IAAI;CAavD"}