@pgsage/core 0.1.0

package/dist/introspector/index.js

@@ -0,0 +1,460 @@
+/**
+ * Introspector
+ *
+ * Crawls information_schema and pg_catalog to produce a fully-typed
+ * IntrospectedSchema describing every table, view, column, constraint,
+ * index, and enum in the target database.
+ *
+ * All queries run as a single-client transaction (READ ONLY) to give a
+ * consistent snapshot.  The introspector is deliberately read-only and
+ * dataset-agnostic — it works against any Postgres database (Chinook,
+ * Census schema, arbitrary user schemas, etc.).
+ */
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Introspect the target database and return a fully-typed schema description.
+ *
+ * @param pool    A pg Pool connected to the target database.
+ * @param options Filtering options.
+ */
+export async function introspect(pool, options = {}) {
+    const client = await pool.connect();
+    try {
+        return await introspectWithClient(client, options);
+    }
+    finally {
+        client.release();
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal implementation
+// ---------------------------------------------------------------------------
+const SYSTEM_SCHEMAS = [
+    "pg_catalog",
+    "information_schema",
+    "pg_toast",
+    "pg_temp",
+];
+async function introspectWithClient(client, options) {
+    const { schemas, includeViews = true } = options;
+    await client.query("BEGIN TRANSACTION READ ONLY");
+    try {
+        // Determine the set of schemas to introspect
+        const schemaFilter = await resolveSchemas(client, schemas);
+        const tableTypes = includeViews
+            ? ["BASE TABLE", "VIEW"]
+            : ["BASE TABLE"];
+        // Run metadata queries sequentially on the single client — pg@8 warns
+        // about concurrent queries on one client, and catalog queries are fast
+        // enough that sequential is fine.
+        const tablesRows = await queryTables(client, schemaFilter, tableTypes);
+        const columnsRows = await queryColumns(client, schemaFilter);
+        const pkRows = await queryPrimaryKeys(client, schemaFilter);
+        const fkRows = await queryForeignKeys(client, schemaFilter);
+        const uniqueRows = await queryUniqueConstraints(client, schemaFilter);
+        const checkRows = await queryCheckConstraints(client, schemaFilter);
+        const indexRows = await queryIndexes(client, schemaFilter);
+        const enumRows = await queryEnums(client, schemaFilter);
+        const rowCountRows = await queryRowCounts(client, schemaFilter);
+        const tableCommentRows = await queryTableComments(client, schemaFilter);
+        const columnCommentRows = await queryColumnComments(client, schemaFilter);
+        await client.query("COMMIT");
+        return assemble({
+            tablesRows,
+            columnsRows,
+            pkRows,
+            fkRows,
+            uniqueRows,
+            checkRows,
+            indexRows,
+            enumRows,
+            rowCountRows,
+            tableCommentRows,
+            columnCommentRows,
+        });
+    }
+    catch (err) {
+        await client.query("ROLLBACK").catch(() => undefined);
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Schema resolution
+// ---------------------------------------------------------------------------
+async function resolveSchemas(client, requested) {
+    if (requested && requested.length > 0)
+        return requested;
+    // All schemas except system ones and pg_temp_* prefixed schemas
+    const result = await client.query(`
+    SELECT schema_name
+    FROM information_schema.schemata
+    WHERE schema_name NOT IN (${SYSTEM_SCHEMAS.map((s) => `'${s}'`).join(", ")})
+      AND schema_name NOT LIKE 'pg_temp_%'
+      AND schema_name NOT LIKE 'pg_toast_%'
+    ORDER BY schema_name
+  `);
+    return result.rows.map((r) => r.schema_name);
+}
+async function queryTables(client, schemas, tableTypes) {
+    const result = await client.query(`SELECT table_schema, table_name, table_type
+     FROM information_schema.tables
+     WHERE table_schema = ANY($1)
+       AND table_type = ANY($2)
+     ORDER BY table_schema, table_name`, [schemas, tableTypes]);
+    return result.rows;
+}
+async function queryColumns(client, schemas) {
+    const result = await client.query(`SELECT
+       c.table_schema,
+       c.table_name,
+       c.column_name,
+       c.data_type,
+       c.udt_name,
+       c.is_nullable,
+       c.column_default,
+       c.ordinal_position
+     FROM information_schema.columns c
+     WHERE c.table_schema = ANY($1)
+     ORDER BY c.table_schema, c.table_name, c.ordinal_position`, [schemas]);
+    return result.rows;
+}
+async function queryPrimaryKeys(client, schemas) {
+    const result = await client.query(`SELECT
+       tc.table_schema,
+       tc.table_name,
+       kcu.column_name,
+       kcu.ordinal_position
+     FROM information_schema.table_constraints tc
+     JOIN information_schema.key_column_usage kcu
+       ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema    = kcu.table_schema
+      AND tc.table_name      = kcu.table_name
+     WHERE tc.constraint_type = 'PRIMARY KEY'
+       AND tc.table_schema = ANY($1)
+     ORDER BY tc.table_schema, tc.table_name, kcu.ordinal_position`, [schemas]);
+    return result.rows;
+}
+async function queryForeignKeys(client, schemas) {
+    const result = await client.query(`SELECT
+       tc.table_schema,
+       tc.table_name,
+       tc.constraint_name,
+       kcu.column_name,
+       kcu.ordinal_position AS key_ordinal,
+       ccu.table_schema     AS foreign_table_schema,
+       ccu.table_name       AS foreign_table_name,
+       ccu.column_name      AS foreign_column_name
+     FROM information_schema.table_constraints tc
+     JOIN information_schema.key_column_usage kcu
+       ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema    = kcu.table_schema
+      AND tc.table_name      = kcu.table_name
+     JOIN information_schema.referential_constraints rc
+       ON tc.constraint_name = rc.constraint_name
+      AND tc.table_schema    = rc.constraint_schema
+     JOIN information_schema.constraint_column_usage ccu
+       ON rc.unique_constraint_name   = ccu.constraint_name
+      AND rc.unique_constraint_schema = ccu.table_schema
+     WHERE tc.constraint_type = 'FOREIGN KEY'
+       AND tc.table_schema = ANY($1)
+     ORDER BY tc.table_schema, tc.table_name, tc.constraint_name, kcu.ordinal_position`, [schemas]);
+    return result.rows;
+}
+async function queryUniqueConstraints(client, schemas) {
+    const result = await client.query(`SELECT
+       tc.table_schema,
+       tc.table_name,
+       tc.constraint_name,
+       kcu.column_name,
+       kcu.ordinal_position
+     FROM information_schema.table_constraints tc
+     JOIN information_schema.key_column_usage kcu
+       ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema    = kcu.table_schema
+      AND tc.table_name      = kcu.table_name
+     WHERE tc.constraint_type = 'UNIQUE'
+       AND tc.table_schema = ANY($1)
+     ORDER BY tc.table_schema, tc.table_name, tc.constraint_name, kcu.ordinal_position`, [schemas]);
+    return result.rows;
+}
+async function queryCheckConstraints(client, schemas) {
+    // Exclude auto-generated NOT NULL checks (they contain 'IS NOT NULL' and
+    // the column name only — a good-enough heuristic for v1).
+    const result = await client.query(`SELECT
+       tc.table_schema,
+       tc.table_name,
+       cc.constraint_name,
+       cc.check_clause
+     FROM information_schema.check_constraints cc
+     JOIN information_schema.table_constraints tc
+       ON cc.constraint_name   = tc.constraint_name
+      AND cc.constraint_schema = tc.table_schema
+     WHERE tc.constraint_type = 'CHECK'
+       AND tc.table_schema = ANY($1)
+       AND cc.check_clause NOT LIKE '%IS NOT NULL%'
+     ORDER BY tc.table_schema, tc.table_name, cc.constraint_name`, [schemas]);
+    return result.rows;
+}
+async function queryIndexes(client, schemas) {
+    // We join pg_index → pg_class (index) → pg_class (table) → pg_namespace
+    // to get the method name and column list.  We exclude PK indexes (those
+    // are surfaced via primaryKey[]) and indexes on system columns.
+    const result = await client.query(`SELECT
+       n.nspname                                          AS table_schema,
+       t.relname                                          AS table_name,
+       i.relname                                          AS index_name,
+       ix.indisunique                                     AS is_unique,
+       am.amname                                          AS index_type,
+       ARRAY(
+         SELECT a.attname
+         FROM unnest(ix.indkey) WITH ORDINALITY AS u(attnum, ord)
+         JOIN pg_attribute a
+           ON a.attrelid = t.oid AND a.attnum = u.attnum
+         WHERE u.attnum > 0
+         ORDER BY u.ord
+       )::text[]                                          AS column_names
+     FROM pg_index ix
+     JOIN pg_class  i  ON i.oid = ix.indexrelid
+     JOIN pg_class  t  ON t.oid = ix.indrelid
+     JOIN pg_namespace n ON n.oid = t.relnamespace
+     JOIN pg_am am ON am.oid = i.relam
+     WHERE n.nspname = ANY($1)
+       AND NOT ix.indisprimary
+       AND t.relkind IN ('r', 'v', 'm')
+     ORDER BY n.nspname, t.relname, i.relname`, [schemas]);
+    return result.rows;
+}
+async function queryEnums(client, schemas) {
+    const result = await client.query(`SELECT
+       n.nspname  AS enum_schema,
+       t.typname  AS enum_name,
+       e.enumlabel AS enum_value
+     FROM pg_type t
+     JOIN pg_namespace n ON n.oid = t.typnamespace
+     JOIN pg_enum e ON e.enumtypid = t.oid
+     WHERE t.typtype = 'e'
+       AND n.nspname = ANY($1)
+     ORDER BY n.nspname, t.typname, e.enumsortorder`, [schemas]);
+    return result.rows;
+}
+async function queryRowCounts(client, schemas) {
+    const result = await client.query(`SELECT
+       n.nspname          AS table_schema,
+       c.relname          AS table_name,
+       c.reltuples::bigint AS row_estimate
+     FROM pg_class c
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = ANY($1)
+       AND c.relkind IN ('r', 'v', 'm', 'p')
+     ORDER BY n.nspname, c.relname`, [schemas]);
+    return result.rows;
+}
+async function queryTableComments(client, schemas) {
+    const result = await client.query(`SELECT
+       n.nspname                             AS table_schema,
+       c.relname                             AS table_name,
+       obj_description(c.oid, 'pg_class')   AS comment
+     FROM pg_class c
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = ANY($1)
+       AND c.relkind IN ('r', 'v', 'm', 'p')
+       AND obj_description(c.oid, 'pg_class') IS NOT NULL
+     ORDER BY n.nspname, c.relname`, [schemas]);
+    return result.rows;
+}
+async function queryColumnComments(client, schemas) {
+    const result = await client.query(`SELECT
+       n.nspname                                       AS table_schema,
+       c.relname                                       AS table_name,
+       a.attname                                       AS column_name,
+       col_description(c.oid, a.attnum)               AS comment
+     FROM pg_attribute a
+     JOIN pg_class c ON c.oid = a.attrelid
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = ANY($1)
+       AND a.attnum > 0
+       AND NOT a.attisdropped
+       AND col_description(c.oid, a.attnum) IS NOT NULL
+     ORDER BY n.nspname, c.relname, a.attnum`, [schemas]);
+    return result.rows;
+}
+function assemble(raw) {
+    // Build lookup maps keyed by "schema.table"
+    const pkSet = buildPkSet(raw.pkRows);
+    const fkMap = buildFkMap(raw.fkRows);
+    const uniqueMap = buildUniqueMap(raw.uniqueRows);
+    const checkMap = buildCheckMap(raw.checkRows);
+    const indexMap = buildIndexMap(raw.indexRows);
+    const rowCountMap = buildRowCountMap(raw.rowCountRows);
+    const tableCommentMap = buildTableCommentMap(raw.tableCommentRows);
+    const columnCommentMap = buildColumnCommentMap(raw.columnCommentRows);
+    // Group columns by table
+    const columnMap = new Map();
+    for (const col of raw.columnsRows) {
+        const key = `${col.table_schema}.${col.table_name}`;
+        if (!columnMap.has(key))
+            columnMap.set(key, []);
+        columnMap.get(key).push(col);
+    }
+    const tables = raw.tablesRows.map((t) => {
+        const key = `${t.table_schema}.${t.table_name}`;
+        const pkCols = pkSet.get(key) ?? new Set();
+        const rawCols = columnMap.get(key) ?? [];
+        const columns = rawCols.map((c) => ({
+            name: c.column_name,
+            dataType: c.data_type,
+            udtName: c.udt_name,
+            isNullable: c.is_nullable === "YES",
+            defaultValue: c.column_default,
+            ordinalPosition: c.ordinal_position,
+            isPrimaryKey: pkCols.has(c.column_name),
+            comment: columnCommentMap.get(`${key}.${c.column_name}`) ?? null,
+        }));
+        return {
+            name: t.table_name,
+            schema: t.table_schema,
+            tableType: t.table_type === "VIEW" ? "view" : "table",
+            columns,
+            primaryKey: [...pkCols].filter((col) => rawCols.some((c) => c.column_name === col)),
+            foreignKeys: fkMap.get(key) ?? [],
+            indexes: indexMap.get(key) ?? [],
+            uniqueConstraints: uniqueMap.get(key) ?? [],
+            checkConstraints: checkMap.get(key) ?? [],
+            estimatedRowCount: rowCountMap.get(key) ?? -1,
+            comment: tableCommentMap.get(key) ?? null,
+        };
+    });
+    // Assemble enums
+    const enumMap = new Map();
+    for (const row of raw.enumRows) {
+        const key = `${row.enum_schema}.${row.enum_name}`;
+        if (!enumMap.has(key)) {
+            enumMap.set(key, { schema: row.enum_schema, name: row.enum_name, values: [] });
+        }
+        enumMap.get(key).values.push(row.enum_value);
+    }
+    return {
+        tables,
+        enums: [...enumMap.values()].sort((a, b) => `${a.schema}.${a.name}`.localeCompare(`${b.schema}.${b.name}`)),
+    };
+}
+// ---------------------------------------------------------------------------
+// Map builders
+// ---------------------------------------------------------------------------
+function buildPkSet(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const key = `${row.table_schema}.${row.table_name}`;
+        if (!map.has(key))
+            map.set(key, new Set());
+        map.get(key).add(row.column_name);
+    }
+    return map;
+}
+function buildFkMap(rows) {
+    // Group by table key + constraint name
+    const intermediate = new Map();
+    for (const row of rows) {
+        const tableKey = `${row.table_schema}.${row.table_name}`;
+        if (!intermediate.has(tableKey))
+            intermediate.set(tableKey, new Map());
+        const byConstraint = intermediate.get(tableKey);
+        if (!byConstraint.has(row.constraint_name))
+            byConstraint.set(row.constraint_name, []);
+        byConstraint.get(row.constraint_name).push(row);
+    }
+    const map = new Map();
+    for (const [tableKey, byConstraint] of intermediate) {
+        const fks = [];
+        for (const [constraintName, constraintRows] of byConstraint) {
+            const sorted = constraintRows.sort((a, b) => a.key_ordinal - b.key_ordinal);
+            fks.push({
+                constraintName,
+                columns: sorted.map((r) => r.column_name),
+                referencedSchema: sorted[0].foreign_table_schema,
+                referencedTable: sorted[0].foreign_table_name,
+                referencedColumns: sorted.map((r) => r.foreign_column_name),
+            });
+        }
+        map.set(tableKey, fks);
+    }
+    return map;
+}
+function buildUniqueMap(rows) {
+    const intermediate = new Map();
+    for (const row of rows) {
+        const tableKey = `${row.table_schema}.${row.table_name}`;
+        if (!intermediate.has(tableKey))
+            intermediate.set(tableKey, new Map());
+        const byConstraint = intermediate.get(tableKey);
+        if (!byConstraint.has(row.constraint_name))
+            byConstraint.set(row.constraint_name, []);
+        byConstraint.get(row.constraint_name).push(row);
+    }
+    const map = new Map();
+    for (const [tableKey, byConstraint] of intermediate) {
+        const uniques = [];
+        for (const [name, constraintRows] of byConstraint) {
+            uniques.push({
+                name,
+                columns: constraintRows
+                    .sort((a, b) => a.ordinal_position - b.ordinal_position)
+                    .map((r) => r.column_name),
+            });
+        }
+        map.set(tableKey, uniques);
+    }
+    return map;
+}
+function buildCheckMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const key = `${row.table_schema}.${row.table_name}`;
+        if (!map.has(key))
+            map.set(key, []);
+        map.get(key).push({ name: row.constraint_name, expression: row.check_clause });
+    }
+    return map;
+}
+function buildIndexMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const key = `${row.table_schema}.${row.table_name}`;
+        if (!map.has(key))
+            map.set(key, []);
+        map.get(key).push({
+            name: row.index_name,
+            columns: row.column_names,
+            isUnique: row.is_unique,
+            indexType: row.index_type,
+        });
+    }
+    return map;
+}
+function buildRowCountMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        map.set(`${row.table_schema}.${row.table_name}`, Number(row.row_estimate));
+    }
+    return map;
+}
+function buildTableCommentMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        if (row.comment)
+            map.set(`${row.table_schema}.${row.table_name}`, row.comment);
+    }
+    return map;
+}
+function buildColumnCommentMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        if (row.comment) {
+            map.set(`${row.table_schema}.${row.table_name}.${row.column_name}`, row.comment);
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=index.js.map

package/dist/introspector/index.js.map

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

package/dist/orchestrator/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Orchestrator
+ *
+ * Ties retriever → planner → validator → estimator → executor → corrector
+ * into a single agent loop and exposes the SDK's primary entrypoint:
+ * `agent.query(question)`.
+ *
+ * Each stage is composable — callers can import individual stage factories
+ * directly if they need finer control. The orchestrator just wires them up
+ * with sensible defaults.
+ */
+import type pg from "pg";
+import type { EmbeddingProvider } from "../embeddings/index.js";
+import type { DisplayHint } from "../planner/index.js";
+export interface OrchestratorConfig {
+    /**
+     * Read-write pg Pool — used for retrieval (pgvector similarity search)
+     * and cost estimation (EXPLAIN). Typically connects as the pgsage app role.
+     */
+    pool: InstanceType<typeof pg.Pool>;
+    /**
+     * Read-only pg Pool — used exclusively by the executor. Should connect as
+     * the pgsage_readonly role (no write/DDL privileges).
+     */
+    readonlyPool: InstanceType<typeof pg.Pool>;
+    /** Embedding provider used to embed the question for pgvector retrieval. */
+    embedder: EmbeddingProvider;
+    /**
+     * Mastra model router string for the planner.
+     * @default "anthropic/claude-sonnet-4-6"
+     */
+    model?: string;
+    /** Number of schema chunks to retrieve. Default: 10. */
+    topK?: number;
+    /** Maximum planner cost threshold for EXPLAIN. Default: 1_000_000. */
+    costThreshold?: number;
+    /** Maximum estimated rows threshold for EXPLAIN. Default: 500_000. */
+    rowThreshold?: number;
+    /** Maximum rows returned by the executor. Default: 500. */
+    rowLimit?: number;
+    /** Per-query statement timeout in ms. Default: 30_000. */
+    statementTimeout?: number;
+    /** Maximum self-correction retries. Default: 3. */
+    maxRetries?: number;
+    /**
+     * Mastra model router string for the explainer (answer generation).
+     * Defaults to the same model used for the planner.
+     */
+    explainerModel?: string;
+}
+export interface QueryResponse {
+    /** Natural-language answer synthesised from the SQL result. */
+    answer: string;
+    /** The final SQL that was executed. */
+    sql: string;
+    /** Assumptions the planner stated about ambiguous terms. */
+    assumptions: string[];
+    /** The raw rows returned by the executor. */
+    rows: Record<string, unknown>[];
+    /** Row count of the returned result set. */
+    rowCount: number;
+    /** Column names in result order. */
+    fields: string[];
+    /** True when the result was truncated at the row limit. */
+    truncated: boolean;
+    /** All prior failed attempts (empty when first plan succeeded). */
+    attempts: {
+        sql: string;
+        error: string;
+    }[];
+    /**
+     * Suggested UI visualization layout chosen by the planner.
+     * - `"big"` — single scalar answer
+     * - `"statrow"` — 2–4 related metrics side by side
+     * - `"bar"` — ranked list of one metric across many geographies
+     * - `"grouped"` — two-series comparison across geographies
+     * - `"table"` — general tabular fallback
+     */
+    displayHint: DisplayHint;
+}
+/** Options for a single query() call. */
+export interface QueryOptions {
+    /**
+     * Optional progress callback, fired before each pipeline stage.
+     * The step number and label are provided for display purposes.
+     * Steps in order:
+     *   0 — Searching schema
+     *   1 — Generating SQL
+     *   2 — Validating & executing
+     *   3 — Correcting query  (only emitted when a retry occurs)
+     *   4 — Summarizing results
+     */
+    onProgress?: (step: number, label: string) => void;
+}
+export interface Agent {
+    query(question: string, options?: QueryOptions): Promise<QueryResponse>;
+}
+/**
+ * Create the pgsage agent. All stage instances are created once and reused
+ * across query() calls.
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent({
+ *   pool,
+ *   readonlyPool,
+ *   embedder: new VoyageEmbeddingProvider({ apiKey: process.env.VOYAGE_API_KEY }),
+ * });
+ * const response = await agent.query("What is the median household income in RI?");
+ * ```
+ */
+export declare function createAgent(config: OrchestratorConfig): Agent;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestrator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAQhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOvD,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACnC;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C;;;;;;;OAOG;IACH,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,KAAK,CAiH7D"}