@framers/agentos 0.2.6 → 0.2.8

package/dist/memory-router/MemoryRouter.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @file MemoryRouter.ts
+ * @description Top-level orchestrator that composes the LLM-as-judge
+ * classifier and the pure `selectBackend` decision function into a single
+ * per-query routing call.
+ *
+ * MemoryRouter is deliberately a THIN composition layer. It:
+ *   1. Runs the classifier on the incoming query → category + token counts.
+ *   2. Resolves the routing table from (preset | custom table | custom mapping).
+ *   3. Calls the pure selectBackend to get the routing decision.
+ *   4. Returns a {@link MemoryRouterDecision} bundling both.
+ *
+ * It does NOT execute the recall — backend execution is the job of
+ * {@link IMemoryDispatcher}. This split keeps the router pure-enough to
+ * be used in both "decide only" flows (benchmarks, dashboards, dry-runs)
+ * and "decide + execute" flows (production queries).
+ *
+ * @module @framers/agentos/memory-router/MemoryRouter
+ */
+import type { IMemoryClassifier, MemoryClassifierResult } from './classifier.js';
+import { type MemoryBackendCostPoint } from './backend-costs.js';
+import { type MemoryBackendId, type MemoryQueryCategory, type MemoryRouterPreset, type RoutingTable } from './routing-tables.js';
+import { type MemoryBudgetMode, type MemoryRoutingDecision } from './select-backend.js';
+import type { IMemoryDispatcher } from './dispatcher.js';
+/**
+ * Per-query USD budget policy. Combined into a single nested object so
+ * consumers can enable budget enforcement without flat-argument sprawl.
+ */
+export interface MemoryBudgetPolicy {
+    /**
+     * Budget ceiling per query in USD. When omitted, routing passes
+     * through the table's pick regardless of cost.
+     */
+    readonly perQueryUsd?: number;
+    /**
+     * How to handle budget overrun. Default `cheapest-fallback` for
+     * production safety (silently downgrades rather than throwing).
+     * See {@link MemoryBudgetMode}.
+     */
+    readonly mode?: MemoryBudgetMode;
+}
+/**
+ * Constructor options for {@link MemoryRouter}.
+ */
+export interface MemoryRouterOptions {
+    /** LLM-as-judge classifier. Usually {@link LLMMemoryClassifier}. */
+    readonly classifier: IMemoryClassifier;
+    /**
+     * Shipping preset to use. Defaults to `minimize-cost` — the same
+     * Pareto-best-for-cost preset we use on LongMemEval-S Phase B.
+     */
+    readonly preset?: MemoryRouterPreset;
+    /**
+     * Optional custom routing table override. When provided, replaces the
+     * preset's default table. The `preset` field is still used for
+     * telemetry labeling and must match.
+     */
+    readonly routingTable?: RoutingTable;
+    /**
+     * Optional per-category routing override that patches the resolved
+     * routing table. Useful when a workload needs to change a single
+     * category's dispatch without rewriting the whole table.
+     */
+    readonly mapping?: Partial<Record<MemoryQueryCategory, MemoryBackendId>>;
+    /**
+     * Optional budget policy. When omitted, no budget is enforced.
+     */
+    readonly budget?: MemoryBudgetPolicy;
+    /**
+     * Optional custom backend cost-points (for workloads whose cost /
+     * accuracy profile diverges from LongMemEval-S Phase B). When omitted,
+     * uses {@link DEFAULT_MEMORY_BACKEND_COSTS}.
+     */
+    readonly backendCosts?: Readonly<Record<MemoryBackendId, MemoryBackendCostPoint>>;
+    /**
+     * Default for {@link MemoryClassifierClassifyOptions.useFewShotPrompt}
+     * on every `decide()` call. Callers can still override per-call.
+     */
+    readonly useFewShotPrompt?: boolean;
+    /**
+     * Optional dispatcher. When supplied, {@link MemoryRouter.decideAndDispatch}
+     * is usable; otherwise callers must use {@link MemoryRouter.decide} and
+     * execute the chosen backend themselves.
+     */
+    readonly dispatcher?: IMemoryDispatcher<unknown, unknown>;
+}
+/**
+ * Per-call options for {@link MemoryRouter.decide}.
+ */
+export interface MemoryRouterDecideOptions {
+    /**
+     * Ground-truth category, passed through to the routing decision for
+     * telemetry. Not used in production. Benchmark adapters pass this when
+     * the gold label is available so downstream analysis can distinguish
+     * classifier misroutes from architectural misses.
+     */
+    readonly groundTruthCategory?: MemoryQueryCategory | null;
+    /**
+     * Per-call override of the few-shot prompt variant. When omitted,
+     * inherits the router's constructor-scoped default.
+     */
+    readonly useFewShotPrompt?: boolean;
+}
+/**
+ * Bundled result of a `decide()` call. Carries the classifier result
+ * (for cost tracking + debugging) alongside the routing decision.
+ */
+export interface MemoryRouterDecision {
+    readonly classifier: MemoryClassifierResult;
+    readonly routing: MemoryRoutingDecision;
+}
+/**
+ * Bundled result of a `decideAndDispatch()` call. Combines the full
+ * {@link MemoryRouterDecision} with the dispatched traces so telemetry
+ * and answer-generation can consume both in one step.
+ */
+export interface MemoryRouterDispatchedDecision<TTrace> {
+    readonly decision: MemoryRouterDecision;
+    readonly traces: TTrace[];
+    readonly backend: MemoryBackendId;
+}
+/**
+ * Thrown when `decideAndDispatch` is called on a router that was
+ * constructed without a dispatcher.
+ */
+export declare class MemoryRouterDispatcherMissingError extends Error {
+    constructor();
+}
+/**
+ * The public MemoryRouter primitive. One instance per memory-recall
+ * endpoint; construct once at app startup with the chosen preset and
+ * reuse across queries.
+ *
+ * @example Basic min-cost routing
+ * ```ts
+ * import { LLMMemoryClassifier, MemoryRouter } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: myOpenAIAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const decision = await router.decide("What's my current job title?");
+ * console.log(decision.classifier.category); // 'knowledge-update'
+ * console.log(decision.routing.chosenBackend); // 'canonical-hybrid'
+ * console.log(decision.routing.estimatedCostUsd); // 0.0189
+ * ```
+ *
+ * @example With a strict budget
+ * ```ts
+ * const router = new MemoryRouter({
+ *   classifier: myClassifier,
+ *   preset: 'maximize-accuracy',
+ *   budget: { perQueryUsd: 0.025, mode: 'cheapest-fallback' },
+ * });
+ * ```
+ */
+export declare class MemoryRouter {
+    private readonly classifier;
+    private readonly preset;
+    private readonly routingTable;
+    private readonly budgetPerQuery;
+    private readonly budgetMode;
+    private readonly backendCosts;
+    private readonly defaultUseFewShotPrompt;
+    private readonly dispatcher;
+    constructor(options: MemoryRouterOptions);
+    /**
+     * Decide-only routing. Classifies the query, picks a backend, returns
+     * both pieces. Does NOT execute the recall — pair with an
+     * {@link IMemoryDispatcher} for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatch} if a dispatcher is wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     * @returns A {@link MemoryRouterDecision} bundling classifier + routing results.
+     */
+    decide(query: string, options?: MemoryRouterDecideOptions): Promise<MemoryRouterDecision>;
+    /**
+     * Decide + dispatch in one call. Requires the router to have been
+     * constructed with a {@link IMemoryDispatcher}.
+     *
+     * @typeParam TTrace - Caller's trace shape (passed through verbatim).
+     * @typeParam TPayload - Caller's payload shape for the dispatcher.
+     * @param query - User memory-recall query.
+     * @param dispatchPayload - Optional payload forwarded to the dispatcher's
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     *
+     * @throws {@link MemoryRouterDispatcherMissingError} when no dispatcher
+     *   was supplied at construction.
+     */
+    decideAndDispatch<TTrace, TPayload = undefined>(query: string, dispatchPayload?: TPayload, options?: MemoryRouterDecideOptions): Promise<MemoryRouterDispatchedDecision<TTrace>>;
+}
+//# sourceMappingURL=MemoryRouter.d.ts.map

package/dist/memory-router/MemoryRouter.d.ts.map

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

package/dist/memory-router/MemoryRouter.js

@@ -0,0 +1,155 @@
+/**
+ * @file MemoryRouter.ts
+ * @description Top-level orchestrator that composes the LLM-as-judge
+ * classifier and the pure `selectBackend` decision function into a single
+ * per-query routing call.
+ *
+ * MemoryRouter is deliberately a THIN composition layer. It:
+ *   1. Runs the classifier on the incoming query → category + token counts.
+ *   2. Resolves the routing table from (preset | custom table | custom mapping).
+ *   3. Calls the pure selectBackend to get the routing decision.
+ *   4. Returns a {@link MemoryRouterDecision} bundling both.
+ *
+ * It does NOT execute the recall — backend execution is the job of
+ * {@link IMemoryDispatcher}. This split keeps the router pure-enough to
+ * be used in both "decide only" flows (benchmarks, dashboards, dry-runs)
+ * and "decide + execute" flows (production queries).
+ *
+ * @module @framers/agentos/memory-router/MemoryRouter
+ */
+import { DEFAULT_MEMORY_BACKEND_COSTS, } from './backend-costs.js';
+import { PRESET_TABLES, } from './routing-tables.js';
+import { selectBackend, } from './select-backend.js';
+/**
+ * Thrown when `decideAndDispatch` is called on a router that was
+ * constructed without a dispatcher.
+ */
+export class MemoryRouterDispatcherMissingError extends Error {
+    constructor() {
+        super('MemoryRouter.decideAndDispatch requires a dispatcher. ' +
+            'Either pass a dispatcher in options, or call `decide` and dispatch yourself.');
+        this.name = 'MemoryRouterDispatcherMissingError';
+    }
+}
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * The public MemoryRouter primitive. One instance per memory-recall
+ * endpoint; construct once at app startup with the chosen preset and
+ * reuse across queries.
+ *
+ * @example Basic min-cost routing
+ * ```ts
+ * import { LLMMemoryClassifier, MemoryRouter } from '../memory-router/index.js';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: myOpenAIAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const decision = await router.decide("What's my current job title?");
+ * console.log(decision.classifier.category); // 'knowledge-update'
+ * console.log(decision.routing.chosenBackend); // 'canonical-hybrid'
+ * console.log(decision.routing.estimatedCostUsd); // 0.0189
+ * ```
+ *
+ * @example With a strict budget
+ * ```ts
+ * const router = new MemoryRouter({
+ *   classifier: myClassifier,
+ *   preset: 'maximize-accuracy',
+ *   budget: { perQueryUsd: 0.025, mode: 'cheapest-fallback' },
+ * });
+ * ```
+ */
+export class MemoryRouter {
+    constructor(options) {
+        this.classifier = options.classifier;
+        this.preset = options.preset ?? 'minimize-cost';
+        this.dispatcher = options.dispatcher ?? null;
+        // Resolve routing table: explicit > preset's default.
+        const baseTable = options.routingTable ?? PRESET_TABLES[this.preset];
+        // Apply optional per-category mapping override.
+        if (options.mapping) {
+            const patched = {
+                ...baseTable.defaultMapping,
+            };
+            for (const key of Object.keys(options.mapping)) {
+                const override = options.mapping[key];
+                if (override)
+                    patched[key] = override;
+            }
+            this.routingTable = Object.freeze({
+                preset: baseTable.preset,
+                defaultMapping: Object.freeze(patched),
+            });
+        }
+        else {
+            this.routingTable = baseTable;
+        }
+        this.budgetPerQuery = options.budget?.perQueryUsd ?? null;
+        this.budgetMode = options.budget?.mode ?? 'cheapest-fallback';
+        this.backendCosts = options.backendCosts ?? DEFAULT_MEMORY_BACKEND_COSTS;
+        this.defaultUseFewShotPrompt = options.useFewShotPrompt ?? false;
+    }
+    /**
+     * Decide-only routing. Classifies the query, picks a backend, returns
+     * both pieces. Does NOT execute the recall — pair with an
+     * {@link IMemoryDispatcher} for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatch} if a dispatcher is wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     * @returns A {@link MemoryRouterDecision} bundling classifier + routing results.
+     */
+    async decide(query, options) {
+        const useFewShot = options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+        const classifierOptions = useFewShot
+            ? { useFewShotPrompt: true }
+            : undefined;
+        const classifier = await this.classifier.classify(query, classifierOptions);
+        const routing = selectBackend({
+            predictedCategory: classifier.category,
+            groundTruthCategory: options?.groundTruthCategory ?? null,
+            config: {
+                table: this.routingTable,
+                budgetPerQuery: this.budgetPerQuery,
+                budgetMode: this.budgetMode,
+                backendCosts: this.backendCosts,
+            },
+        });
+        return { classifier, routing };
+    }
+    /**
+     * Decide + dispatch in one call. Requires the router to have been
+     * constructed with a {@link IMemoryDispatcher}.
+     *
+     * @typeParam TTrace - Caller's trace shape (passed through verbatim).
+     * @typeParam TPayload - Caller's payload shape for the dispatcher.
+     * @param query - User memory-recall query.
+     * @param dispatchPayload - Optional payload forwarded to the dispatcher's
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     *
+     * @throws {@link MemoryRouterDispatcherMissingError} when no dispatcher
+     *   was supplied at construction.
+     */
+    async decideAndDispatch(query, dispatchPayload, options) {
+        if (!this.dispatcher) {
+            throw new MemoryRouterDispatcherMissingError();
+        }
+        const decision = await this.decide(query, options);
+        const dispatched = (await this.dispatcher.dispatch({
+            backend: decision.routing.chosenBackend,
+            query,
+            payload: dispatchPayload,
+        }));
+        return {
+            decision,
+            traces: dispatched.traces,
+            backend: dispatched.backend,
+        };
+    }
+}
+//# sourceMappingURL=MemoryRouter.js.map

package/dist/memory-router/MemoryRouter.js.map

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

package/dist/memory-router/adaptive.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @file adaptive.ts
+ * @description Self-calibrating routing-table generator.
+ *
+ * The shipping {@link MINIMIZE_COST_TABLE} / {@link BALANCED_TABLE} /
+ * {@link MAXIMIZE_ACCURACY_TABLE} are calibrated from LongMemEval-S
+ * Phase B N=500 measurements. For workloads whose cost-accuracy profile
+ * diverges from that distribution, those tables are not optimal.
+ *
+ * AdaptiveMemoryRouter takes a workload-specific calibration dataset
+ * (a list of {category, backend, costUsd, correct} samples) and derives
+ * a routing table from it. Same MemoryRouter API; different table
+ * source.
+ *
+ * Calibration workflow:
+ *   1. Run a Phase A sweep on your workload (a few hundred queries
+ *      across a small subset of expected categories, dispatched to all
+ *      candidate backends).
+ *   2. Each sample contributes one (category, backend, costUsd, correct)
+ *      data point.
+ *   3. AdaptiveMemoryRouter aggregates these into per-(category, backend)
+ *      mean cost + mean accuracy.
+ *   4. Apply a preset selection rule:
+ *        - 'minimize-cost': cheapest backend within 2pp of best accuracy;
+ *          if none within tolerance, pick best accuracy.
+ *        - 'maximize-accuracy': highest accuracy; ties broken by cost.
+ *        - 'balanced': best $/correct (mean cost divided by mean
+ *          accuracy).
+ *   5. Categories with insufficient samples fall back to the static
+ *      preset table.
+ *
+ * The router is otherwise identical to {@link MemoryRouter} — same
+ * decide() / decideAndDispatch() / budget-aware dispatch.
+ *
+ * @module @framers/agentos/memory-router/adaptive
+ */
+import { MemoryRouter, type MemoryRouterOptions } from './MemoryRouter.js';
+import { type MemoryBackendId, type MemoryQueryCategory, type RoutingTable } from './routing-tables.js';
+/**
+ * One calibration sample. Caller produces these from running their own
+ * workload through each candidate backend and recording the outcome.
+ */
+export interface CalibrationSample {
+    readonly category: MemoryQueryCategory;
+    readonly backend: MemoryBackendId;
+    readonly costUsd: number;
+    /** 1 = correct, 0 = incorrect (or score in [0,1] for soft graders). */
+    readonly correct: number;
+}
+/**
+ * Aggregated calibration cell: one (category, backend) → mean cost +
+ * mean accuracy + sample count.
+ */
+export interface CalibrationCell {
+    readonly n: number;
+    readonly meanCost: number;
+    readonly meanAccuracy: number;
+}
+/**
+ * Map of (category, backend) → CalibrationCell. Categories or backends
+ * with no samples are simply absent from the map.
+ */
+export type AggregatedCalibration = Partial<Record<MemoryQueryCategory, Partial<Record<MemoryBackendId, CalibrationCell>>>>;
+/**
+ * Preset selection rules for {@link selectByPreset}.
+ *
+ * - `minimize-cost`: pick the cheapest backend whose meanAccuracy is
+ *   within `accuracyTolerance` (default 0.02 = 2pp) of the best
+ *   meanAccuracy on this category. If no backend is within tolerance,
+ *   pick the best-accuracy backend (the gap exceeds the tolerance,
+ *   meaning accuracy gain justifies cost).
+ * - `maximize-accuracy`: pick the highest-meanAccuracy backend;
+ *   ties broken by lower meanCost.
+ * - `balanced`: pick the lowest meanCost / meanAccuracy ratio
+ *   ($/correct). Backends with zero meanAccuracy are skipped (would
+ *   produce divide-by-zero).
+ */
+export type AdaptivePresetRule = 'minimize-cost' | 'balanced' | 'maximize-accuracy';
+export interface SelectByPresetArgs {
+    readonly category: MemoryQueryCategory;
+    readonly agg: AggregatedCalibration;
+    readonly preset: AdaptivePresetRule;
+    /**
+     * Minimum sample count per (category, backend) cell required for
+     * adaptive selection. Cells below this threshold are ignored. Default
+     * 1 (any sample qualifies). Increase for noisier workloads.
+     */
+    readonly minSamplesPerCell?: number;
+    /**
+     * For `minimize-cost`: max accuracy gap from the best-accuracy backend
+     * tolerated when picking the cheaper alternative. Default 0.02 (2pp).
+     */
+    readonly accuracyTolerance?: number;
+}
+export interface BuildAdaptiveRoutingTableArgs {
+    readonly samples: readonly CalibrationSample[];
+    readonly preset: AdaptivePresetRule;
+    readonly minSamplesPerCell?: number;
+    readonly accuracyTolerance?: number;
+    /**
+     * Fallback static table for categories with insufficient calibration.
+     * Defaults to the preset's shipping static table.
+     */
+    readonly fallbackTable?: RoutingTable;
+}
+export interface AdaptiveMemoryRouterOptions extends Omit<MemoryRouterOptions, 'routingTable' | 'preset'> {
+    readonly calibrationSamples: readonly CalibrationSample[];
+    readonly preset: AdaptivePresetRule;
+    readonly minSamplesPerCell?: number;
+    readonly accuracyTolerance?: number;
+}
+/**
+ * Roll up raw calibration samples into per-(category, backend) cells.
+ * Each cell carries n, meanCost, meanAccuracy.
+ */
+export declare function aggregateCalibration(samples: readonly CalibrationSample[]): AggregatedCalibration;
+/**
+ * Select a backend for one category from aggregated calibration data
+ * using the named preset rule. Falls back to the preset's static table
+ * when calibration is insufficient.
+ */
+export declare function selectByPreset(args: SelectByPresetArgs): MemoryBackendId;
+/**
+ * Build a complete frozen routing table from calibration samples + a
+ * preset rule. Categories without enough calibration fall back to the
+ * preset's static table.
+ */
+export declare function buildAdaptiveRoutingTable(args: BuildAdaptiveRoutingTableArgs): RoutingTable;
+/**
+ * Memory router whose routing table is derived from a calibration
+ * dataset rather than a static preset. Otherwise identical API to
+ * {@link MemoryRouter}.
+ */
+export declare class AdaptiveMemoryRouter extends MemoryRouter {
+    private readonly derivedTable;
+    constructor(options: AdaptiveMemoryRouterOptions);
+    /**
+     * Inspect the derived routing table for debugging / telemetry.
+     */
+    getRoutingTable(): RoutingTable;
+}
+//# sourceMappingURL=adaptive.d.ts.map

package/dist/memory-router/adaptive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.d.ts","sourceRoot":"","sources":["../../src/memory-router/adaptive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAExB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAM7B;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,CACzC,MAAM,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC,CAC/E,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,UAAU,GACV,mBAAmB,CAAC;AAExB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAC;CACvC;AAED,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,cAAc,GAAG,QAAQ,CAAC;IAC5D,QAAQ,CAAC,kBAAkB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,qBAAqB,CA4BvB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CA8DxE;AAeD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,6BAA6B,GAClC,YAAY,CAqCd;AAMD;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,OAAO,EAAE,2BAA2B;IAiBhD;;OAEG;IACH,eAAe,IAAI,YAAY;CAGhC"}