@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/dist/mcp/tools/search.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Search tools for the MCP server.
+ * Registers `search_{source}` tools from describe schema and shared QueryBuilder handlers.
+ * @module mcp/tools/search
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DimensionsClient } from "../../dsl/index.js";
+import { type SchemaStore, type StructuredEntityType } from "../../dsl/index.js";
+/**
+ * Builds DSL for a structured search from tool arguments.
+ * @param client - Dimensions client
+ * @param source - Dimensions source name
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export declare function buildStructuredSearchDsl(client: DimensionsClient, source: StructuredEntityType, args: Record<string, unknown>): string;
+/**
+ * Registers structured search tools for sources present in the schema store.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema
+ */
+export declare function registerSearchTools(server: McpServer, client: DimensionsClient, schemaStore: SchemaStore): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/mcp/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EAI1B,MAAM,oBAAoB,CAAC;AAe5B;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAoCR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,WAAW,GACvB,IAAI,CA0EN"}

package/dist/mcp/tools/search.js

@@ -0,0 +1,115 @@
+/**
+ * Search tools for the MCP server.
+ * Registers `search_{source}` tools from describe schema and shared QueryBuilder handlers.
+ * @module mcp/tools/search
+ */
+import { z } from "zod";
+import { applyFilters, parseEntityResponse, resolveSkipAndLimit, searchResultKey, searchToolName, validateSearchPaginationPolicy, } from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS, withSearchPagination, } from "../utils.js";
+import { SEARCH_ENTITY_METADATA } from "./search-entity-metadata.js";
+import { PAGINATION_OUTPUT_SCHEMA, SHARED_SEARCH_INPUT } from "./search-input.js";
+const metadataBySource = new Map(SEARCH_ENTITY_METADATA.map((meta) => [meta.source, meta]));
+/**
+ * Builds DSL for a structured search from tool arguments.
+ * @param client - Dimensions client
+ * @param source - Dimensions source name
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export function buildStructuredSearchDsl(client, source, args) {
+    const meta = metadataBySource.get(source);
+    const builder = client.createQueryBuilder().search(source);
+    if (typeof args.query === "string" && args.query.length > 0) {
+        builder.for(args.query);
+    }
+    meta?.applyConvenienceFilters(builder, args);
+    const filters = args.filters;
+    if (filters?.length) {
+        applyFilters(builder, filters);
+    }
+    const fields = args.fields;
+    if (fields?.length) {
+        builder.fields(fields);
+    }
+    if (typeof args.sortBy === "string") {
+        builder.sort(args.sortBy, "desc");
+    }
+    const { skip, limit } = resolveSkipAndLimit({
+        skip: args.skip,
+        page: args.page,
+        limit: args.limit,
+        pageSize: args.pageSize,
+    });
+    builder.limit(limit);
+    if (skip > 0) {
+        builder.skip(skip);
+    }
+    return builder.build();
+}
+/**
+ * Registers structured search tools for sources present in the schema store.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema
+ */
+export function registerSearchTools(server, client, schemaStore) {
+    for (const source of schemaStore.structuredEntityTypes()) {
+        const meta = metadataBySource.get(source);
+        if (!meta)
+            continue;
+        const resultKey = searchResultKey(source);
+        const toolName = searchToolName(source);
+        server.registerTool(toolName, {
+            description: meta.description,
+            inputSchema: {
+                ...SHARED_SEARCH_INPUT,
+                ...meta.extraInputSchema,
+            },
+            outputSchema: {
+                totalCount: z.number().describe("Total matching records"),
+                returnedCount: z.number().describe("Records returned in this response"),
+                truncated: z
+                    .boolean()
+                    .optional()
+                    .describe("True when more results exist beyond this page"),
+                truncationWarning: z.string().optional().describe("Warning message when truncated"),
+                ...PAGINATION_OUTPUT_SCHEMA,
+                [resultKey]: z.array(z.record(z.string(), z.unknown())).describe("Result records"),
+            },
+            annotations: READ_ONLY_API_ANNOTATIONS,
+        }, withFieldAliases({
+            entitySource: { kind: "static", entity: source },
+            fieldArrayArgs: ["fields"],
+            fieldStringArgs: ["sortBy"],
+            filterArrayArgs: ["filters"],
+        }, async (args) => {
+            try {
+                const record = args;
+                const { skip, limit } = resolveSkipAndLimit({
+                    skip: record.skip,
+                    page: record.page,
+                    limit: record.limit,
+                });
+                validateSearchPaginationPolicy({
+                    skip,
+                    limit,
+                    confirmLargeFetch: record.confirmLargeFetch,
+                });
+                const dsl = buildStructuredSearchDsl(client, source, record);
+                const response = (await client.rawQuery(dsl));
+                const parsed = parseEntityResponse(response, source);
+                const rows = parsed.data;
+                return formatToolResult(withSearchPagination({
+                    totalCount: parsed.totalCount,
+                    returnedCount: rows.length,
+                    [resultKey]: rows,
+                }, parsed.totalCount, rows.length, skip, limit));
+            }
+            catch (error) {
+                return formatErrorResult(error);
+            }
+        }));
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/mcp/tools/search.js.map

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

package/dist/mcp/utils.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Utility functions for MCP tools.
+ * @module mcp/utils
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type PaginationMetadata } from "../dsl/index.js";
+/** Annotations for read-only tools that call external APIs. */
+export declare const READ_ONLY_API_ANNOTATIONS: ToolAnnotations;
+/**
+ * Coerces an unknown value to an array of records, returning `[]` if not an array.
+ * Replaces unsafe `as Array<Record<string, unknown>>` casts from API responses.
+ * @param value - Unknown value from a DSL response property
+ * @returns The value as an array of records, or empty array if not an array
+ */
+export declare function asArray(value: unknown): Array<Record<string, unknown>>;
+/**
+ * MCP tool result format.
+ * Includes index signature for MCP SDK compatibility.
+ */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/**
+ * Formats a successful tool result.
+ * Populates both `content` (text/JSON) and `structuredContent` for SDK output schema validation.
+ * @param data - The data to return
+ * @returns Formatted tool result
+ */
+export declare function formatToolResult(data: unknown): ToolResult;
+/**
+ * Builds a JSON-serializable error payload for MCP tool responses.
+ * Surfaces Dimensions API metadata (status codes, client rate-limit hints) when available.
+ * @param error - The error that occurred
+ * @returns Error payload object
+ */
+export declare function formatErrorPayload(error: unknown): Record<string, unknown>;
+/**
+ * Formats an error tool result.
+ * @param error - The error that occurred
+ * @returns Formatted error result
+ */
+export declare function formatErrorResult(error: unknown): ToolResult;
+/** Fields added to paginated search tool responses. */
+export type SearchPaginationFields = {
+    truncated?: boolean;
+    truncationWarning?: string;
+    pagination?: PaginationMetadata;
+    largeResultWarning?: string;
+    policyNotice?: string;
+};
+/**
+ * Augments a search result with truncation warnings and pagination metadata.
+ * @param data - The result data object
+ * @param totalCount - Total matching records from the API
+ * @param returnedCount - Records actually returned
+ * @param skip - Current skip offset
+ * @param pageSize - Page size used for this request
+ * @returns The data object with pagination fields when applicable
+ */
+export declare function withSearchPagination<T extends Record<string, unknown>>(data: T, totalCount: number, returnedCount: number, skip: number, pageSize: number): T & SearchPaginationFields;
+/**
+ * @deprecated Use {@link withSearchPagination} — kept as alias for gradual migration.
+ */
+export declare function withTruncationWarning<T extends Record<string, unknown>>(data: T, totalCount: number, returnedCount: number): T & SearchPaginationFields;
+/** Logging levels supported by the MCP protocol (syslog severity). */
+export type McpLogLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+/**
+ * Sends a structured log message via the MCP protocol with stderr fallback.
+ * @param server - MCP server instance
+ * @param level - Log severity level
+ * @param data - Structured log data (any JSON-serializable value)
+ * @param logger - Optional logger namespace (e.g., "search", "schema")
+ */
+export declare function mcpLog(server: McpServer, level: McpLogLevel, data: unknown, logger?: string): void;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/mcp/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAEzB,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,EAAE,eAK9B,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEtE;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAU1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAU5D;AAED,uDAAuD;AACvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG,sBAAsB,CA2B5B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,CAAC,GAAG,sBAAsB,CAG5B;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAMN"}

package/dist/mcp/utils.js

@@ -0,0 +1,126 @@
+/**
+ * Utility functions for MCP tools.
+ * @module mcp/utils
+ */
+import { buildPaginationMetadata, DimensionsError, largeResultWarning, POLICY_NOTICE, } from "../dsl/index.js";
+/** Annotations for read-only tools that call external APIs. */
+export const READ_ONLY_API_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/**
+ * Coerces an unknown value to an array of records, returning `[]` if not an array.
+ * Replaces unsafe `as Array<Record<string, unknown>>` casts from API responses.
+ * @param value - Unknown value from a DSL response property
+ * @returns The value as an array of records, or empty array if not an array
+ */
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Formats a successful tool result.
+ * Populates both `content` (text/JSON) and `structuredContent` for SDK output schema validation.
+ * @param data - The data to return
+ * @returns Formatted tool result
+ */
+export function formatToolResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        structuredContent: data,
+    };
+}
+/**
+ * Builds a JSON-serializable error payload for MCP tool responses.
+ * Surfaces Dimensions API metadata (status codes, client rate-limit hints) when available.
+ * @param error - The error that occurred
+ * @returns Error payload object
+ */
+export function formatErrorPayload(error) {
+    if (error instanceof DimensionsError) {
+        const json = error.toJSON();
+        return {
+            ...json,
+            error: json.message,
+            type: json.name,
+        };
+    }
+    return {
+        error: error instanceof Error ? error.message : String(error),
+        type: error instanceof Error ? error.name : "Error",
+    };
+}
+/**
+ * Formats an error tool result.
+ * @param error - The error that occurred
+ * @returns Formatted error result
+ */
+export function formatErrorResult(error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(formatErrorPayload(error), null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Augments a search result with truncation warnings and pagination metadata.
+ * @param data - The result data object
+ * @param totalCount - Total matching records from the API
+ * @param returnedCount - Records actually returned
+ * @param skip - Current skip offset
+ * @param pageSize - Page size used for this request
+ * @returns The data object with pagination fields when applicable
+ */
+export function withSearchPagination(data, totalCount, returnedCount, skip, pageSize) {
+    const warning = largeResultWarning(totalCount);
+    const truncated = totalCount > skip + returnedCount;
+    const needsPagination = skip > 0 || truncated || warning !== undefined;
+    if (!needsPagination) {
+        return data;
+    }
+    const pagination = buildPaginationMetadata(skip, pageSize, totalCount);
+    const showPolicyNotice = truncated || warning !== undefined;
+    return {
+        ...data,
+        ...(warning ? { largeResultWarning: warning } : {}),
+        ...(showPolicyNotice ? { policyNotice: POLICY_NOTICE } : {}),
+        ...(truncated
+            ? {
+                truncated: true,
+                truncationWarning: `Only ${returnedCount} of ${totalCount} results in this page (skip ${skip}). ` +
+                    "Use skip/page on search_* or fetch_search_pages for the next page; narrow filters when possible.",
+            }
+            : {}),
+        pagination,
+    };
+}
+/**
+ * @deprecated Use {@link withSearchPagination} — kept as alias for gradual migration.
+ */
+export function withTruncationWarning(data, totalCount, returnedCount) {
+    const pageSize = returnedCount > 0 ? returnedCount : 100;
+    return withSearchPagination(data, totalCount, returnedCount, 0, pageSize);
+}
+/**
+ * Sends a structured log message via the MCP protocol with stderr fallback.
+ * @param server - MCP server instance
+ * @param level - Log severity level
+ * @param data - Structured log data (any JSON-serializable value)
+ * @param logger - Optional logger namespace (e.g., "search", "schema")
+ */
+export function mcpLog(server, level, data, logger) {
+    server.sendLoggingMessage({ level, data, logger }).catch(() => {
+        console.error(`[${level}]${logger ? ` [${logger}]` : ""} ${typeof data === "string" ? data : JSON.stringify(data)}`);
+    });
+}
+//# sourceMappingURL=utils.js.map

package/dist/mcp/utils.js.map

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

package/dist/middleware/field-aliases.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Field name alias middleware for MCP tools.
+ * Translates LLM-friendly field aliases to raw Dimensions DSL field names
+ * via a higher-order function (decorator) pattern.
+ * @module mcp/middleware/field-aliases
+ */
+import type { EntityType } from "@digital-science/dimensions-dsl";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Runtime alias registry. One flat map per entity type.
+ * Keys: LLM-friendly alias names. Values: raw DSL field names.
+ * Unknown names pass through unchanged at resolution time.
+ */
+export declare const ENTITY_ALIASES: Readonly<Record<EntityType, Readonly<Record<string, string>>>>;
+/**
+ * Resolves a single field alias to its raw DSL name.
+ * Returns the input unchanged if it is not a known alias (pass-through).
+ * @param entity - The entity type
+ * @param name - Alias name or raw DSL field name
+ * @returns The raw DSL field name
+ */
+export declare function resolveFieldName(entity: EntityType, name: string): string;
+/**
+ * Resolves facet-field aliases (e.g. grants `funders` → `funder_orgs` on live describe).
+ * Falls back to {@link resolveFieldName} when no facet-specific alias exists.
+ * @param entity - The entity type
+ * @param name - Facet field name or alias
+ * @returns Raw DSL facet field name
+ */
+export declare function resolveFacetFieldName(entity: EntityType, name: string): string;
+/**
+ * Resolves an array of field names, applying alias resolution to each.
+ * @param entity - The entity type
+ * @param names - Array of alias or DSL field names
+ * @returns Array of raw DSL field names
+ */
+export declare function resolveFieldNames(entity: EntityType, names: readonly string[]): string[];
+/**
+ * Builds a reverse lookup map: DSL field name → alias names.
+ * Useful for documentation and resource generation.
+ * @param entity - The entity type
+ * @returns Map of DSL field name → array of alias names
+ */
+export declare function buildReverseAliasMap(entity: EntityType): Map<string, string[]>;
+/**
+ * Where to find the entity type for alias resolution.
+ * - `static`: hardcoded at registration time (e.g., search_publications → "publications")
+ * - `dynamic`: read from an arg at call time (e.g., get_by_id → args.entityType)
+ */
+export type EntitySource = {
+    readonly kind: "static";
+    readonly entity: EntityType;
+} | {
+    readonly kind: "dynamic";
+    readonly argName: string;
+};
+/**
+ * Describes which args of a tool contain field names that need alias resolution.
+ */
+export interface FieldAliasDescriptor {
+    /** Where to get the entity type. */
+    readonly entitySource: EntitySource;
+    /** Args that are `string[]` of field names (e.g., `["fields"]`, `["indicators"]`). */
+    readonly fieldArrayArgs?: readonly string[];
+    /** Args that are a single field name string (e.g., `["sortBy"]`, `["facetField"]`). */
+    readonly fieldStringArgs?: readonly string[];
+    /** Args that are arrays of filter objects with a `.field` property (e.g., `["filters"]`). */
+    readonly filterArrayArgs?: readonly string[];
+}
+/** Generic tool handler function type compatible with the MCP SDK. */
+type ToolHandler = (args: any, extra: any) => CallToolResult | Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with transparent field alias resolution.
+ * Resolves LLM-friendly aliases to raw DSL field names before the inner handler runs.
+ *
+ * @param descriptor - Declares which args contain field names
+ * @param handler - The inner tool handler
+ * @returns A new handler with the same signature that pre-processes args
+ *
+ * @example
+ * ```typescript
+ * server.registerTool("search_publications", config,
+ *   withFieldAliases(
+ *     {
+ *       entitySource: { kind: "static", entity: "publications" },
+ *       fieldArrayArgs: ["fields"],
+ *       fieldStringArgs: ["sortBy"],
+ *       filterArrayArgs: ["filters"],
+ *     },
+ *     async (args) => { ... },
+ *   ),
+ * );
+ * ```
+ */
+export declare function withFieldAliases<T extends ToolHandler>(descriptor: FieldAliasDescriptor, handler: T): T;
+export {};
+//# sourceMappingURL=field-aliases.d.ts.map

package/dist/middleware/field-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-aliases.d.ts","sourceRoot":"","sources":["../../src/middleware/field-aliases.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAoFzE;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CASzF,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAIxF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAY9E;AAMD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,uFAAuF;IACvF,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAMD,sEAAsE;AAEtE,KAAK,WAAW,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,CAAC,GACT,CAAC,CA2CH"}