@framers/agentos 0.1.113 → 0.1.114

package/dist/query-router/QueryGenerator.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview QueryGenerator — tier-appropriate prompt construction and LLM
+ * answer generation for the QueryRouter pipeline.
+ *
+ * The generator is the final stage of the routing pipeline: it takes the
+ * classified {@link QueryTier}, a set of {@link RetrievedChunk}s from the
+ * retrieval phase, and an optional research synthesis narrative, then builds
+ * a tier-specific system prompt and invokes the LLM via {@link generateText}.
+ *
+ * **Tier-specific behaviour:**
+ *
+ * | Tier | Model   | Context | Temperature | Max Tokens | Instruction                                        |
+ * |------|---------|---------|-------------|------------|----------------------------------------------------|
+ * | T0   | standard| none    | 0.7         | 512        | (base prompt only)                                 |
+ * | T1   | standard| chunks  | 0.3         | 512        | "Answer based on the documentation context provided."|
+ * | T2   | deep    | chunks  | 0.3         | 1024       | "cross-reference" sources                          |
+ * | T3   | deep    | chunks + research | 0.3 | 1024   | "Synthesize information from both internal documentation and external research." |
+ *
+ * **Context injection:**
+ * Each chunk is formatted as `## heading (sourcePath)\ncontent` and appended
+ * until the estimated token budget (`maxContextTokens`) is exhausted. Token
+ * estimation uses the common heuristic of `Math.ceil(text.length / 4)`.
+ *
+ * @module @framers/agentos/query-router/QueryGenerator
+ */
+import { generateText } from '../api/generateText.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Base system prompt injected into every generation call regardless of tier.
+ * Establishes the assistant's persona and ground rules.
+ */
+const BASE_SYSTEM_PROMPT = 'You are a knowledgeable AI assistant for an autonomous agent platform. ' +
+    'Answer questions accurately and concisely. If you don\'t know something, ' +
+    'say so \u2014 do not make things up.';
+/** Default maximum context tokens when not specified in config. */
+const DEFAULT_MAX_CONTEXT_TOKENS = 4000;
+// ============================================================================
+// QueryGenerator
+// ============================================================================
+/**
+ * Builds tier-appropriate prompts and generates LLM answers.
+ *
+ * The generator selects a model (standard vs. deep) based on the query tier,
+ * constructs a system prompt with optional documentation context and research
+ * synthesis, then delegates to {@link generateText} for the actual LLM call.
+ *
+ * @example
+ * ```typescript
+ * const gen = new QueryGenerator({
+ *   model: 'openai:gpt-4.1-mini',
+ *   modelDeep: 'openai:gpt-4.1',
+ *   provider: 'openai',
+ * });
+ *
+ * const result = await gen.generate('How does auth work?', 1, chunks);
+ * console.log(result.answer);
+ * ```
+ */
+export class QueryGenerator {
+    /**
+     * Create a new QueryGenerator instance.
+     *
+     * @param config - Generator configuration specifying models, provider,
+     *                 and optional credential overrides.
+     */
+    constructor(config) {
+        this.config = {
+            model: config.model,
+            modelDeep: config.modelDeep,
+            provider: config.provider,
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+            maxContextTokens: config.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS,
+        };
+    }
+    /**
+     * Generate an answer for the given query at the specified complexity tier.
+     *
+     * @param query - The user's original question.
+     * @param tier - The classified complexity tier (0–3).
+     * @param chunks - Retrieved documentation chunks, sorted by relevance.
+     * @param researchSynthesis - Optional research narrative (T3 only).
+     * @returns A promise resolving to the generated answer, model used, and token usage.
+     */
+    async generate(query, tier, chunks, researchSynthesis) {
+        const model = this.selectModel(tier);
+        const temperature = this.selectTemperature(tier);
+        const maxTokens = this.selectMaxTokens(tier);
+        const systemPrompt = this.buildSystemPrompt(tier, chunks, researchSynthesis);
+        const result = await generateText({
+            model,
+            provider: this.config.provider,
+            apiKey: this.config.apiKey,
+            baseUrl: this.config.baseUrl,
+            system: systemPrompt,
+            prompt: query,
+            temperature,
+            maxTokens,
+        });
+        return {
+            answer: result.text,
+            model,
+            usage: {
+                promptTokens: result.usage.promptTokens,
+                completionTokens: result.usage.completionTokens,
+                totalTokens: result.usage.totalTokens,
+            },
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Private — Model / parameter selection
+    // --------------------------------------------------------------------------
+    /**
+     * Select the appropriate model based on query tier.
+     * T0–T1 use the standard model; T2–T3 use the deep model.
+     *
+     * @param tier - The classified query tier.
+     * @returns The model identifier string.
+     */
+    selectModel(tier) {
+        return tier >= 2 ? this.config.modelDeep : this.config.model;
+    }
+    /**
+     * Select the sampling temperature for the given tier.
+     * T0 uses a higher temperature (0.7) for more creative general answers;
+     * all other tiers use 0.3 for focused, grounded responses.
+     *
+     * @param tier - The classified query tier.
+     * @returns The temperature value.
+     */
+    selectTemperature(tier) {
+        return tier === 0 ? 0.7 : 0.3;
+    }
+    /**
+     * Select the maximum output tokens for the given tier.
+     * T0–T1 cap at 512 tokens; T2–T3 allow 1024 for more detailed answers.
+     *
+     * @param tier - The classified query tier.
+     * @returns The maxTokens value.
+     */
+    selectMaxTokens(tier) {
+        return tier >= 2 ? 1024 : 512;
+    }
+    // --------------------------------------------------------------------------
+    // Private — System prompt construction
+    // --------------------------------------------------------------------------
+    /**
+     * Build the full system prompt by composing the base prompt with optional
+     * tier-specific context blocks and instructions.
+     *
+     * @param tier - The classified query tier.
+     * @param chunks - Retrieved documentation chunks.
+     * @param researchSynthesis - Optional research narrative for T3.
+     * @returns The assembled system prompt string.
+     */
+    buildSystemPrompt(tier, chunks, researchSynthesis) {
+        const parts = [BASE_SYSTEM_PROMPT];
+        // Inject documentation context for T1+
+        if (tier >= 1 && chunks.length > 0) {
+            const contextBlock = this.formatChunksAsContext(chunks);
+            if (contextBlock) {
+                parts.push(`\nDocumentation context:\n${contextBlock}`);
+            }
+        }
+        // Inject research synthesis for T3
+        if (tier === 3 && researchSynthesis) {
+            parts.push(`\nExternal research findings:\n${researchSynthesis}`);
+        }
+        // Append tier-specific instruction
+        const instruction = this.getTierInstruction(tier);
+        if (instruction) {
+            parts.push(`\n${instruction}`);
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Format retrieved chunks into a documentation context block, respecting
+     * the configured token budget.
+     *
+     * Each chunk is formatted as:
+     * ```
+     * ## heading (sourcePath)
+     * content
+     * ```
+     *
+     * Chunks are added in the order provided (typically by relevance) until the
+     * estimated token count would exceed `maxContextTokens`.
+     *
+     * @param chunks - The retrieved chunks to format.
+     * @returns The formatted context string, or an empty string if no chunks fit.
+     */
+    formatChunksAsContext(chunks) {
+        const entries = [];
+        let tokenCount = 0;
+        for (const chunk of chunks) {
+            const entry = `## ${chunk.heading} (${chunk.sourcePath})\n${chunk.content}`;
+            const entryTokens = this.estimateTokens(entry);
+            if (tokenCount + entryTokens > this.config.maxContextTokens) {
+                break;
+            }
+            entries.push(entry);
+            tokenCount += entryTokens;
+        }
+        return entries.join('\n\n');
+    }
+    /**
+     * Return the tier-specific instruction appended to the system prompt.
+     *
+     * @param tier - The classified query tier.
+     * @returns The instruction string, or `undefined` for T0 (no extra instruction).
+     */
+    getTierInstruction(tier) {
+        switch (tier) {
+            case 0:
+                return undefined;
+            case 1:
+                return 'Answer based on the documentation context provided.';
+            case 2:
+                return 'Answer based on the documentation context provided. ' +
+                    'Where possible, cross-reference multiple sources to provide a comprehensive answer.';
+            case 3:
+                return 'Synthesize information from both internal documentation and external research. ' +
+                    'Where possible, cross-reference multiple sources to provide a comprehensive answer.';
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Estimate the token count for a string using the common heuristic of
+     * approximately 4 characters per token.
+     *
+     * @param text - The text to estimate.
+     * @returns Estimated token count (ceiling).
+     */
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+}
+//# sourceMappingURL=QueryGenerator.js.map

package/dist/query-router/QueryGenerator.js.map

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

package/dist/query-router/QueryRouter.d.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview QueryRouter — main orchestrator that wires together the
+ * QueryClassifier, QueryDispatcher, and QueryGenerator into a complete
+ * classify -> dispatch -> generate pipeline.
+ *
+ * @module @framers/agentos/query-router/QueryRouter
+ *
+ * The QueryRouter is the top-level entry point for the intelligent query
+ * routing system. Given a user query and optional conversation history, it:
+ *
+ * 1. **Classifies** the query into a complexity tier (T0-T3) using the
+ *    {@link QueryClassifier}.
+ * 2. **Dispatches** the classified query to the tier-appropriate retrieval
+ *    pipeline via the {@link QueryDispatcher}, which orchestrates vector
+ *    search, graph expansion, reranking, and deep research.
+ * 3. **Generates** a grounded answer with citations via the
+ *    {@link QueryGenerator}, using the retrieved context chunks.
+ *
+ * The router also handles:
+ * - Corpus loading from markdown files on disk
+ * - Real vector embedding via EmbeddingManager + VectorStoreManager (in-memory)
+ * - Keyword fallback retrieval when embeddings are unavailable
+ * - Event emission for full pipeline observability
+ * - Lifecycle hooks (onClassification, onRetrieval) for consumer integration
+ *
+ * Embedding pipeline: The `init()` method attempts to initialize an
+ * AIModelProviderManager, EmbeddingManager, and VectorStoreManager to enable
+ * real vector search. If any step fails (e.g., no API key configured), the
+ * router falls back gracefully to {@link KeywordFallback} for all retrieval.
+ */
+import type { ClassificationResult, ConversationMessage, QueryResult, QueryRouterConfig, QueryTier, RetrievalResult } from './types.js';
+/**
+ * Main orchestrator that wires together the QueryClassifier, QueryDispatcher,
+ * and QueryGenerator into a complete classify -> dispatch -> generate pipeline.
+ *
+ * @example
+ * ```typescript
+ * const router = new QueryRouter({
+ *   knowledgeCorpus: ['./docs'],
+ *   generationModel: 'gpt-4o-mini',
+ *   generationModelDeep: 'gpt-4o',
+ *   generationProvider: 'openai',
+ * });
+ *
+ * await router.init();
+ * const result = await router.route('How does authentication work?');
+ * console.log(result.answer);
+ * console.log(result.sources);
+ *
+ * await router.close();
+ * ```
+ */
+export declare class QueryRouter {
+    /** Resolved configuration with defaults applied. */
+    private readonly config;
+    /** Loaded corpus chunks from disk. */
+    private corpus;
+    /** Topic entries extracted from the corpus. */
+    private topics;
+    /** Keyword-based fallback search engine. */
+    private keywordFallback;
+    /** Chain-of-thought query classifier. */
+    private classifier;
+    /** Tier-routing dispatcher. */
+    private dispatcher;
+    /** LLM answer generator. */
+    private generator;
+    /** Accumulated lifecycle events for observability. */
+    private events;
+    /** Whether init() has been called successfully. */
+    private initialized;
+    /** Embedding manager for generating vector embeddings. Null if not available. */
+    private embeddingManager;
+    /** Vector store manager for persisting and querying embeddings. Null if not available. */
+    private vectorStoreManager;
+    /** AI model provider manager used by the embedding manager. Null if not available. */
+    private providerManager;
+    /** Embedding dimension for the configured model. Zero if embeddings unavailable. */
+    private embeddingDimension;
+    /**
+     * The data source ID used for corpus embeddings in the vector store.
+     * Matches the collection name configured during init().
+     */
+    private readonly corpusDataSourceId;
+    /**
+     * Creates a new QueryRouter instance.
+     *
+     * Merges user-supplied configuration over {@link QUERY_ROUTER_DEFAULTS}.
+     * The router is NOT ready to use until {@link init} is called.
+     *
+     * @param config - Partial configuration; `knowledgeCorpus` is required.
+     */
+    constructor(config: QueryRouterConfig);
+    /**
+     * Initialise the router: load corpus from disk, extract topics, build
+     * keyword fallback index, embed the corpus into a vector store, and
+     * instantiate classifier/dispatcher/generator.
+     *
+     * Must be called before `classify()`, `retrieve()`, or `route()`.
+     *
+     * The embedding step uses real EmbeddingManager + VectorStoreManager when
+     * an LLM provider is available (e.g., OPENAI_API_KEY is set). If embedding
+     * initialisation fails for any reason, the router falls back gracefully to
+     * KeywordFallback for all retrieval.
+     */
+    init(): Promise<void>;
+    /**
+     * Classify a query into a complexity tier without dispatching or generating.
+     *
+     * Useful when consumers want to inspect the classification before deciding
+     * whether to proceed with the full pipeline.
+     *
+     * @param query - The user's natural-language query.
+     * @param conversationHistory - Optional recent conversation messages.
+     * @returns The classification result with tier, confidence, and reasoning.
+     * @throws If the router has not been initialised via {@link init}.
+     */
+    classify(query: string, conversationHistory?: ConversationMessage[]): Promise<ClassificationResult>;
+    /**
+     * Retrieve context at a specific tier, bypassing the classifier.
+     *
+     * Useful when the caller already knows the appropriate retrieval depth
+     * and wants to skip classification overhead.
+     *
+     * @param query - The user's natural-language query.
+     * @param tier - The complexity tier to retrieve at (0-3).
+     * @returns The retrieval result with chunks and optional graph/research data.
+     * @throws If the router has not been initialised via {@link init}.
+     */
+    retrieve(query: string, tier: QueryTier): Promise<RetrievalResult>;
+    /**
+     * Full end-to-end pipeline: classify -> dispatch -> generate.
+     *
+     * This is the primary method for answering user queries. It:
+     * 1. Classifies the query to determine retrieval depth.
+     * 2. Dispatches retrieval at the classified tier.
+     * 3. Generates a grounded answer from the retrieved context.
+     * 4. Emits lifecycle events throughout for observability.
+     *
+     * @param query - The user's natural-language query.
+     * @param conversationHistory - Optional recent conversation messages.
+     * @returns The final query result with answer, classification, sources, and timing.
+     * @throws If the router has not been initialised via {@link init}.
+     */
+    route(query: string, conversationHistory?: ConversationMessage[]): Promise<QueryResult>;
+    /**
+     * Tear down resources and release references.
+     *
+     * Shuts down embedding and vector store managers if they were initialised,
+     * then nulls out all component references. Safe to call multiple times.
+     * After close(), the router must be re-initialised via {@link init} before
+     * further use.
+     */
+    close(): Promise<void>;
+    /**
+     * Load and chunk markdown files from the configured corpus directories.
+     *
+     * Recursively walks each directory, reads .md and .mdx files, and splits
+     * their content by h1-h3 headings. Each heading section becomes a
+     * CorpusChunk (capped at {@link MAX_CHUNK_CHARS} characters, minimum
+     * {@link MIN_CHUNK_CHARS} to filter out trivially small sections).
+     *
+     * @param paths - Array of directory paths to scan for markdown files.
+     * @returns Array of CorpusChunk objects ready for indexing.
+     */
+    private loadCorpus;
+    /**
+     * Recursively walk a directory tree, invoking a callback for each file.
+     *
+     * @param dir - The directory to walk.
+     * @param callback - Function called with the absolute path of each file.
+     */
+    private walkDir;
+    /**
+     * Split markdown content into sections by h1-h3 headings.
+     *
+     * Each section captures the heading text and the content between it and
+     * the next heading (or end of file). Content before the first heading is
+     * assigned a heading of "(intro)".
+     *
+     * @param content - The raw markdown file content.
+     * @param sourcePath - File path (used for the section's sourcePath field).
+     * @returns Array of sections with heading and content fields.
+     */
+    private splitByHeadings;
+    /**
+     * Embed all loaded corpus chunks into the vector store using real
+     * EmbeddingManager and VectorStoreManager instances.
+     *
+     * The method dynamically imports the RAG modules to keep them optional —
+     * if the imports fail or initialisation fails (e.g., no API key), the error
+     * is caught and logged as a warning. The router will continue to function
+     * using the KeywordFallback engine for all retrieval.
+     *
+     * Steps:
+     * 1. Dynamic-import AIModelProviderManager, EmbeddingManager, VectorStoreManager
+     * 2. Initialise the provider manager with the configured embedding provider
+     * 3. Initialise the embedding manager with the configured model
+     * 4. Initialise the vector store manager with an in-memory provider
+     * 5. Create a collection with the correct dimension
+     * 6. Embed all corpus chunks in batches of 50
+     * 7. Upsert the resulting VectorDocuments into the vector store
+     * 8. Cache embeddings on CorpusChunk.embedding for potential reuse
+     */
+    private embedCorpus;
+    /**
+     * Return a known embedding dimension for common models.
+     *
+     * This avoids an extra API call when the dimension can be statically
+     * determined from the model identifier.
+     *
+     * @param modelId - The embedding model identifier.
+     * @returns The known dimension, or 0 if unknown.
+     */
+    private getKnownDimension;
+    /**
+     * Vector search callback for the dispatcher.
+     *
+     * When the EmbeddingManager and VectorStoreManager are available, this method
+     * embeds the query, queries the vector store, and maps the results to
+     * RetrievedChunk objects. If the RAG modules are not available (e.g., embedding
+     * init failed), it falls back to the KeywordFallback engine and emits a
+     * retrieve:fallback event.
+     *
+     * @param query - The user's query string.
+     * @param topK - Maximum number of chunks to return.
+     * @returns Promise resolving to an array of matched chunks.
+     */
+    private vectorSearch;
+    /**
+     * Graph expansion callback for the dispatcher.
+     *
+     * Placeholder — returns empty array.
+     * // Follow-up: wire GraphRAGEngine
+     *
+     * @param _seeds - Seed chunks to expand from (unused for now).
+     * @returns Promise resolving to an empty array.
+     */
+    private graphExpand;
+    /**
+     * Reranking callback for the dispatcher.
+     *
+     * Placeholder — returns the first topN chunks without actual reranking.
+     * // Follow-up: wire RerankerService
+     *
+     * @param _query - The user's query (unused for now).
+     * @param chunks - Candidate chunks to rerank.
+     * @param topN - Maximum number of chunks to keep.
+     * @returns Promise resolving to the first topN chunks.
+     */
+    private rerank;
+    /**
+     * Deep research callback for the dispatcher.
+     *
+     * Placeholder — returns empty synthesis and empty sources.
+     * // Follow-up: wire DeepResearchEngine
+     *
+     * @param _query - The user's query (unused for now).
+     * @param _sources - Source identifiers to consult (unused for now).
+     * @returns Promise resolving to empty synthesis and sources.
+     */
+    private deepResearch;
+    /**
+     * Format available tools for the classifier prompt.
+     */
+    private formatToolList;
+    /**
+     * Derive fallback strategy names from classification + retrieval events.
+     */
+    private collectFallbacks;
+    /**
+     * Approximate the tiers actually exercised when fallback strategies fired.
+     */
+    private collectTiersUsed;
+    /**
+     * Store a lifecycle event and emit a structured console log.
+     *
+     * Events are accumulated in the `events` array for later inspection
+     * and also logged to the console with a `[QueryRouter]` prefix for
+     * real-time observability.
+     *
+     * @param event - The typed lifecycle event to emit.
+     */
+    private emit;
+    /**
+     * Assert that the router has been initialised via {@link init}.
+     *
+     * @throws Error if `init()` has not been called.
+     */
+    private ensureInitialized;
+}
+//# sourceMappingURL=QueryRouter.d.ts.map

package/dist/query-router/QueryRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryRouter.d.ts","sourceRoot":"","sources":["../../src/query-router/QueryRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAWH,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EAEnB,WAAW,EACX,iBAAiB,EAEjB,SAAS,EACT,eAAe,EAIhB,MAAM,YAAY,CAAC;AAmCpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACtB,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAqB;IAEnC,+CAA+C;IAC/C,OAAO,CAAC,MAAM,CAAoB;IAElC,4CAA4C;IAC5C,OAAO,CAAC,eAAe,CAAgC;IAEvD,yCAAyC;IACzC,OAAO,CAAC,UAAU,CAAgC;IAElD,+BAA+B;IAC/B,OAAO,CAAC,UAAU,CAAgC;IAElD,4BAA4B;IAC5B,OAAO,CAAC,SAAS,CAA+B;IAEhD,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAA+B;IAE7C,mDAAmD;IACnD,OAAO,CAAC,WAAW,CAAS;IAE5B,iFAAiF;IACjF,OAAO,CAAC,gBAAgB,CAAiC;IAEzD,0FAA0F;IAC1F,OAAO,CAAC,kBAAkB,CAAmC;IAE7D,sFAAsF;IACtF,OAAO,CAAC,eAAe,CAAuC;IAE9D,oFAAoF;IACpF,OAAO,CAAC,kBAAkB,CAAK;IAE/B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAE5D;;;;;;;OAOG;gBACS,MAAM,EAAE,iBAAiB;IAarC;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuD3B;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,GAC1C,OAAO,CAAC,oBAAoB,CAAC;IAkChC;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC;IAKxE;;;;;;;;;;;;;OAaG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,GAC1C,OAAO,CAAC,WAAW,CAAC;IAiFvB;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAwClB;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAiBf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IA2CvB;;;;;;;;;;;;;;;;;;OAkBG;YACW,WAAW;IAqKzB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAazB;;;;;;;;;;;;OAYG;YACW,YAAY;IAiE1B;;;;;;;;OAQG;YACW,WAAW;IAKzB;;;;;;;;;;OAUG;YACW,MAAM;IASpB;;;;;;;;;OASG;YACW,YAAY;IAQ1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI;IAQZ;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAO1B"}