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

package/dist/dsl/schema/load.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Load schema from the Dimensions API or optional disk cache.
+ * @module schema/load
+ */
+import type { DimensionsClient } from "../client.js";
+import { type SchemaStore } from "./store.js";
+/**
+ * Returns the module-level cached schema store, if loaded.
+ * @returns Cached store or undefined before first load
+ */
+export declare function getCachedSchemaStore(): SchemaStore | undefined;
+/**
+ * Clears the module-level schema cache (for tests and refresh).
+ */
+export declare function clearSchemaCache(): void;
+export type LoadSchemaOptions = {
+    /** Optional cache file path (defaults to `SCHEMA_CACHE_PATH` env) */
+    cachePath?: string;
+    /** Cache TTL in milliseconds (defaults to `SCHEMA_CACHE_TTL_MS` env or 24h) */
+    cacheTtlMs?: number;
+    /** Skip fresh cache and fetch from the API (stale fallback still applies on failure) */
+    forceRefresh?: boolean;
+    /** Log load stats to stderr (default true) */
+    log?: boolean;
+};
+/**
+ * Fetches schema from the Dimensions API, with TTL-aware cache and stale fallback.
+ * @param client - Authenticated Dimensions client
+ * @param options - Cache path, TTL, and logging options
+ * @returns Loaded schema store
+ */
+export declare function loadSchema(client: DimensionsClient, options?: LoadSchemaOptions | string): Promise<SchemaStore>;
+/**
+ * Returns cached schema or loads once per process.
+ * @param client - Authenticated Dimensions client
+ * @param options - Cache path and logging options
+ * @returns Schema store
+ */
+export declare function getOrLoadSchema(client: DimensionsClient, options?: LoadSchemaOptions | string): Promise<SchemaStore>;
+export { extractDescribeSchema, extractDescribeVersion } from "./extract.js";
+//# sourceMappingURL=load.d.ts.map

package/dist/dsl/schema/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/dsl/schema/load.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAK7E;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,GAAG,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,GACnC,OAAO,CAAC,WAAW,CAAC,CAuEtB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,GACnC,OAAO,CAAC,WAAW,CAAC,CAUtB;AAaD,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/dsl/schema/load.js

@@ -0,0 +1,119 @@
+/**
+ * Load schema from the Dimensions API or optional disk cache.
+ * @module schema/load
+ */
+import { isCacheFresh, readSchemaCacheFile, resolveCacheTtlMs, writeSchemaCacheFile, } from "./cache.js";
+import { extractDescribeSchema, extractDescribeVersion } from "./extract.js";
+import { createSchemaStoreFromResponse } from "./store.js";
+let moduleCache;
+let moduleLoadPromise;
+/**
+ * Returns the module-level cached schema store, if loaded.
+ * @returns Cached store or undefined before first load
+ */
+export function getCachedSchemaStore() {
+    return moduleCache;
+}
+/**
+ * Clears the module-level schema cache (for tests and refresh).
+ */
+export function clearSchemaCache() {
+    moduleCache = undefined;
+    moduleLoadPromise = undefined;
+}
+/**
+ * Fetches schema from the Dimensions API, with TTL-aware cache and stale fallback.
+ * @param client - Authenticated Dimensions client
+ * @param options - Cache path, TTL, and logging options
+ * @returns Loaded schema store
+ */
+export async function loadSchema(client, options) {
+    const resolved = typeof options === "string" ? { cachePath: options, log: true } : (options ?? {});
+    const cachePath = resolved.cachePath ?? process.env.SCHEMA_CACHE_PATH;
+    const log = resolved.log ?? true;
+    const cacheTtlMs = resolveCacheTtlMs(resolved.cacheTtlMs);
+    const forceRefresh = resolved.forceRefresh ?? false;
+    const cached = cachePath ? await readSchemaCacheFile(cachePath) : undefined;
+    const cacheFresh = cached != null && isCacheFresh(cached.cachedAt, cacheTtlMs);
+    if (!forceRefresh && cacheFresh && cached) {
+        const store = createSchemaStoreFromResponse(cached.response, cached.version, new Date(), {
+            loadSource: "cache",
+            stale: false,
+            cachedAt: cached.cachedAt,
+        });
+        moduleCache = store;
+        if (log) {
+            logSchemaLoaded(store, "cache (fresh)");
+        }
+        return store;
+    }
+    try {
+        const started = performance.now();
+        const [schemaRaw, versionRaw] = await Promise.all([
+            client.rawQuery("describe schema"),
+            client.rawQuery("describe version").catch(() => undefined),
+        ]);
+        const response = extractDescribeSchema(schemaRaw);
+        const version = versionRaw ? extractDescribeVersion(versionRaw) : undefined;
+        if (cachePath) {
+            await writeSchemaCacheFile(cachePath, response, version);
+        }
+        const store = createSchemaStoreFromResponse(response, version, new Date(), {
+            loadSource: "api",
+            stale: false,
+        });
+        moduleCache = store;
+        if (log) {
+            const elapsed = Math.round(performance.now() - started);
+            logSchemaLoaded(store, `api (${elapsed}ms)`);
+        }
+        return store;
+    }
+    catch (error) {
+        if (cached) {
+            const store = createSchemaStoreFromResponse(cached.response, cached.version, new Date(), {
+                loadSource: "cache",
+                stale: true,
+                cachedAt: cached.cachedAt,
+            });
+            moduleCache = store;
+            if (log) {
+                const age = cached.cachedAt != null
+                    ? `${Math.round((Date.now() - cached.cachedAt.getTime()) / 60_000)}m old`
+                    : "legacy cache";
+                console.error(`[schema] API unavailable; using stale cache (${age}). ` +
+                    `Call refresh_schema when the API is reachable.`);
+                logSchemaLoaded(store, "cache (stale fallback)");
+            }
+            return store;
+        }
+        throw error;
+    }
+}
+/**
+ * Returns cached schema or loads once per process.
+ * @param client - Authenticated Dimensions client
+ * @param options - Cache path and logging options
+ * @returns Schema store
+ */
+export async function getOrLoadSchema(client, options) {
+    if (moduleCache) {
+        return moduleCache;
+    }
+    if (!moduleLoadPromise) {
+        moduleLoadPromise = loadSchema(client, options).finally(() => {
+            moduleLoadPromise = undefined;
+        });
+    }
+    return moduleLoadPromise;
+}
+function logSchemaLoaded(store, via) {
+    const stats = store.stats();
+    const flags = [via, store.stale ? "stale" : undefined].filter(Boolean).join(", ");
+    console.error(`[schema] loaded ${stats.sourceCount} sources, ${stats.entityCount} entities` +
+        (stats.dslVersion ? ` (DSL ${stats.dslVersion})` : "") +
+        ` [${flags}]`);
+}
+// Re-export extract helpers for backward compatibility
+export { extractDescribeSchema, extractDescribeVersion } from "./extract.js";
+//# sourceMappingURL=load.js.map

package/dist/dsl/schema/load.js.map

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

package/dist/dsl/schema/store.d.ts

@@ -0,0 +1,137 @@
+/**
+ * In-memory schema store built from `describe schema` responses.
+ * @module schema/store
+ */
+import { type StructuredEntityType } from "./structured-entities.js";
+import { type SchemaSummary } from "./summary.js";
+import type { DescribeSchemaResponse, EntityDescribe, SourceDescribe } from "./types.js";
+/** How the schema store was populated. */
+export type SchemaLoadSource = "api" | "cache";
+/** Optional metadata when constructing a {@link SchemaStore}. */
+export type SchemaStoreMetadata = {
+    readonly loadSource?: SchemaLoadSource;
+    readonly stale?: boolean;
+    readonly cachedAt?: Date;
+};
+/** Operational limits mirrored from upstream DSL constants. */
+export declare const SCHEMA_LIMITS: {
+    readonly maxLimit: 1000;
+    readonly maxOffset: 50000;
+    readonly maxPages: 50;
+    readonly maxFacetBuckets: 1000;
+    readonly requestsPerMinute: 30;
+};
+/**
+ * Read-only schema catalog with derived helper views for tools and clients.
+ */
+export declare class SchemaStore {
+    #private;
+    /**
+     * @param response - Parsed `describe schema` payload
+     * @param version - Optional DSL version from `describe version`
+     * @param loadedAt - Timestamp when schema was loaded
+     * @param metadata - Cache/API provenance
+     */
+    constructor(response: DescribeSchemaResponse, version?: string, loadedAt?: Date, metadata?: SchemaStoreMetadata);
+    /** Whether schema came from the API or disk cache. */
+    get loadSource(): SchemaLoadSource;
+    /** True when serving from cache after an API failure or expired TTL. */
+    get stale(): boolean;
+    /** When the on-disk cache was written, if known. */
+    get cachedAt(): Date | undefined;
+    /** DSL version string, if known. */
+    get version(): string | undefined;
+    /** When this store was populated. */
+    get loadedAt(): Date;
+    /** Full describe payload. */
+    get raw(): DescribeSchemaResponse;
+    /** All source names. */
+    sourceNames(): readonly string[];
+    /** All auxiliary entity names. */
+    entityNames(): readonly string[];
+    /**
+     * Returns a source schema by name.
+     * @param name - Source name (e.g. `publications`)
+     * @returns Source schema or undefined
+     */
+    getSource(name: string): SourceDescribe | undefined;
+    /**
+     * Returns an auxiliary entity schema by name.
+     * @param name - Entity name (e.g. `journals`)
+     * @returns Entity schema or undefined
+     */
+    getEntity(name: string): EntityDescribe | undefined;
+    /**
+     * Filterable field names for a source.
+     * @param source - Source name
+     * @returns Field names where `is_filter` is true
+     */
+    filterableFields(source: string): readonly string[];
+    /**
+     * Facet field names for a source.
+     * @param source - Source name
+     * @returns Field names marked as facets or entity fields
+     */
+    facetFields(source: string): readonly string[];
+    /**
+     * Search index names for a source.
+     * @param source - Source name
+     * @returns Search field/index names
+     */
+    searchIndexes(source: string): readonly string[];
+    /**
+     * Aggregation indicator names for a source.
+     * @param source - Source name
+     * @returns Metric names
+     */
+    metrics(source: string): readonly string[];
+    /**
+     * Named fieldsets for a source.
+     * @param source - Source name
+     * @returns Fieldset name to field list map
+     */
+    fieldsets(source: string): Readonly<Record<string, readonly string[]>>;
+    /**
+     * Core entity types supported by structured search tools.
+     * @returns Structured sources that exist in the loaded describe schema
+     */
+    structuredEntityTypes(): readonly StructuredEntityType[];
+    /**
+     * Health/stats payload for `/health`.
+     * @returns Summary object
+     */
+    stats(): {
+        dslVersion: string | undefined;
+        sourceCount: number;
+        entityCount: number;
+        schemaLoadedAt: string;
+        loadSource: SchemaLoadSource;
+        stale: boolean;
+        cachedAt: string | undefined;
+    };
+    /**
+     * Compact overview for cold-start discovery (fields, facets, resource URIs).
+     * @returns Summary payload
+     */
+    summary(): SchemaSummary;
+    /**
+     * Comma-separated facet fields for tool descriptions.
+     * @param source - Source name
+     * @returns Hint string
+     */
+    facetFieldsHint(source: string): string;
+    /**
+     * Comma-separated metrics for tool descriptions.
+     * @param source - Source name
+     * @returns Hint string
+     */
+    metricsHint(source: string): string;
+}
+/**
+ * Builds a {@link SchemaStore} from a describe response.
+ * @param response - `describe schema` JSON
+ * @param version - Optional DSL version
+ * @returns Schema store instance
+ */
+export declare function createSchemaStoreFromResponse(response: DescribeSchemaResponse, version?: string, loadedAt?: Date, metadata?: SchemaStoreMetadata): SchemaStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/dsl/schema/store.d.ts.map

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

package/dist/dsl/schema/store.js

@@ -0,0 +1,204 @@
+/**
+ * In-memory schema store built from `describe schema` responses.
+ * @module schema/store
+ */
+import { STRUCTURED_ENTITY_TYPES } from "./structured-entities.js";
+import { buildSchemaSummary } from "./summary.js";
+/** Operational limits mirrored from upstream DSL constants. */
+export const SCHEMA_LIMITS = {
+    maxLimit: 1000,
+    maxOffset: 50000,
+    maxPages: 50,
+    maxFacetBuckets: 1000,
+    requestsPerMinute: 30,
+};
+/**
+ * Read-only schema catalog with derived helper views for tools and clients.
+ */
+export class SchemaStore {
+    #version;
+    #loadedAt;
+    #loadSource;
+    #stale;
+    #cachedAt;
+    #sources;
+    #entities;
+    #raw;
+    /**
+     * @param response - Parsed `describe schema` payload
+     * @param version - Optional DSL version from `describe version`
+     * @param loadedAt - Timestamp when schema was loaded
+     * @param metadata - Cache/API provenance
+     */
+    constructor(response, version, loadedAt = new Date(), metadata = {}) {
+        this.#raw = response;
+        this.#version = version;
+        this.#loadedAt = loadedAt;
+        this.#loadSource = metadata.loadSource ?? "api";
+        this.#stale = metadata.stale ?? false;
+        this.#cachedAt = metadata.cachedAt;
+        this.#sources = new Map(Object.entries(response.sources ?? {}));
+        this.#entities = new Map(Object.entries(response.entities ?? {}));
+    }
+    /** Whether schema came from the API or disk cache. */
+    get loadSource() {
+        return this.#loadSource;
+    }
+    /** True when serving from cache after an API failure or expired TTL. */
+    get stale() {
+        return this.#stale;
+    }
+    /** When the on-disk cache was written, if known. */
+    get cachedAt() {
+        return this.#cachedAt;
+    }
+    /** DSL version string, if known. */
+    get version() {
+        return this.#version;
+    }
+    /** When this store was populated. */
+    get loadedAt() {
+        return this.#loadedAt;
+    }
+    /** Full describe payload. */
+    get raw() {
+        return this.#raw;
+    }
+    /** All source names. */
+    sourceNames() {
+        return [...this.#sources.keys()].sort();
+    }
+    /** All auxiliary entity names. */
+    entityNames() {
+        return [...this.#entities.keys()].sort();
+    }
+    /**
+     * Returns a source schema by name.
+     * @param name - Source name (e.g. `publications`)
+     * @returns Source schema or undefined
+     */
+    getSource(name) {
+        return this.#sources.get(name);
+    }
+    /**
+     * Returns an auxiliary entity schema by name.
+     * @param name - Entity name (e.g. `journals`)
+     * @returns Entity schema or undefined
+     */
+    getEntity(name) {
+        return this.#entities.get(name);
+    }
+    /**
+     * Filterable field names for a source.
+     * @param source - Source name
+     * @returns Field names where `is_filter` is true
+     */
+    filterableFields(source) {
+        const fields = this.#sources.get(source)?.fields ?? {};
+        return Object.entries(fields)
+            .filter(([, f]) => f.is_filter === true)
+            .map(([name]) => name)
+            .sort();
+    }
+    /**
+     * Facet field names for a source.
+     * @param source - Source name
+     * @returns Field names marked as facets or entity fields
+     */
+    facetFields(source) {
+        const fields = this.#sources.get(source)?.fields ?? {};
+        return Object.entries(fields)
+            .filter(([, f]) => f.is_facet === true || f.is_entity === true)
+            .map(([name]) => name)
+            .sort();
+    }
+    /**
+     * Search index names for a source.
+     * @param source - Source name
+     * @returns Search field/index names
+     */
+    searchIndexes(source) {
+        const raw = this.#sources.get(source)?.search_fields;
+        if (!raw)
+            return [];
+        if (Array.isArray(raw))
+            return [...raw].sort();
+        return Object.keys(raw).sort();
+    }
+    /**
+     * Aggregation indicator names for a source.
+     * @param source - Source name
+     * @returns Metric names
+     */
+    metrics(source) {
+        const raw = this.#sources.get(source)?.metrics;
+        if (!raw)
+            return [];
+        if (Array.isArray(raw))
+            return [...raw].sort();
+        return Object.keys(raw).sort();
+    }
+    /**
+     * Named fieldsets for a source.
+     * @param source - Source name
+     * @returns Fieldset name to field list map
+     */
+    fieldsets(source) {
+        return this.#sources.get(source)?.fieldsets ?? {};
+    }
+    /**
+     * Core entity types supported by structured search tools.
+     * @returns Structured sources that exist in the loaded describe schema
+     */
+    structuredEntityTypes() {
+        return STRUCTURED_ENTITY_TYPES.filter((entity) => this.#sources.has(entity));
+    }
+    /**
+     * Health/stats payload for `/health`.
+     * @returns Summary object
+     */
+    stats() {
+        return {
+            dslVersion: this.#version,
+            sourceCount: this.#sources.size,
+            entityCount: this.#entities.size,
+            schemaLoadedAt: this.#loadedAt.toISOString(),
+            loadSource: this.#loadSource,
+            stale: this.#stale,
+            cachedAt: this.#cachedAt?.toISOString(),
+        };
+    }
+    /**
+     * Compact overview for cold-start discovery (fields, facets, resource URIs).
+     * @returns Summary payload
+     */
+    summary() {
+        return buildSchemaSummary(this);
+    }
+    /**
+     * Comma-separated facet fields for tool descriptions.
+     * @param source - Source name
+     * @returns Hint string
+     */
+    facetFieldsHint(source) {
+        return this.facetFields(source).join(", ") || "(none)";
+    }
+    /**
+     * Comma-separated metrics for tool descriptions.
+     * @param source - Source name
+     * @returns Hint string
+     */
+    metricsHint(source) {
+        return this.metrics(source).join(", ") || "(none)";
+    }
+}
+/**
+ * Builds a {@link SchemaStore} from a describe response.
+ * @param response - `describe schema` JSON
+ * @param version - Optional DSL version
+ * @returns Schema store instance
+ */
+export function createSchemaStoreFromResponse(response, version, loadedAt, metadata) {
+    return new SchemaStore(response, version, loadedAt, metadata);
+}
+//# sourceMappingURL=store.js.map

package/dist/dsl/schema/store.js.map

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

package/dist/dsl/schema/structured-entities.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structured search entity types supported by search tools.
+ * @module schema/structured-entities
+ */
+/** Source names that have dedicated structured search tools. */
+export declare const STRUCTURED_ENTITY_TYPES: readonly ["publications", "grants", "researchers", "patents", "clinical_trials", "datasets", "policy_documents", "organizations"];
+/** A source with a structured search tool. */
+export type StructuredEntityType = (typeof STRUCTURED_ENTITY_TYPES)[number];
+/**
+ * Tool name for a structured entity.
+ * @param source - Dimensions source name
+ * @returns Tool name (e.g. `search_publications`)
+ */
+export declare function searchToolName(source: StructuredEntityType): string;
+/**
+ * JSON result key for entity rows (camelCase where historical tools used it).
+ * @param source - Dimensions source name
+ * @returns Property name in tool output
+ */
+export declare function searchResultKey(source: StructuredEntityType): string;
+//# sourceMappingURL=structured-entities.d.ts.map

package/dist/dsl/schema/structured-entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-entities.d.ts","sourceRoot":"","sources":["../../../src/dsl/schema/structured-entities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,mIAS1B,CAAC;AAEX,8CAA8C;AAC9C,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CASpE"}

package/dist/dsl/schema/structured-entities.js

@@ -0,0 +1,39 @@
+/**
+ * Structured search entity types supported by search tools.
+ * @module schema/structured-entities
+ */
+/** Source names that have dedicated structured search tools. */
+export const STRUCTURED_ENTITY_TYPES = [
+    "publications",
+    "grants",
+    "researchers",
+    "patents",
+    "clinical_trials",
+    "datasets",
+    "policy_documents",
+    "organizations",
+];
+/**
+ * Tool name for a structured entity.
+ * @param source - Dimensions source name
+ * @returns Tool name (e.g. `search_publications`)
+ */
+export function searchToolName(source) {
+    return `search_${source}`;
+}
+/**
+ * JSON result key for entity rows (camelCase where historical tools used it).
+ * @param source - Dimensions source name
+ * @returns Property name in tool output
+ */
+export function searchResultKey(source) {
+    switch (source) {
+        case "clinical_trials":
+            return "clinicalTrials";
+        case "policy_documents":
+            return "policyDocuments";
+        default:
+            return source;
+    }
+}
+//# sourceMappingURL=structured-entities.js.map

package/dist/dsl/schema/structured-entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-entities.js","sourceRoot":"","sources":["../../../src/dsl/schema/structured-entities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,cAAc;IACd,QAAQ;IACR,aAAa;IACb,SAAS;IACT,iBAAiB;IACjB,UAAU;IACV,kBAAkB;IAClB,eAAe;CACP,CAAC;AAKX;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAA4B;IACzD,OAAO,UAAU,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAA4B;IAC1D,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,iBAAiB;YACpB,OAAO,gBAAgB,CAAC;QAC1B,KAAK,kBAAkB;YACrB,OAAO,iBAAiB,CAAC;QAC3B;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/dsl/schema/summary.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Compact schema summary for cold-start and agent discovery.
+ * @module schema/summary
+ */
+import { SCHEMA_LIMITS, type SchemaStore } from "./store.js";
+/** MCP resource URIs for drilling into the full schema. */
+export declare const SCHEMA_RESOURCE_URIS: {
+    readonly full: "dimensions://schema";
+    readonly summary: "dimensions://schema/summary";
+    readonly version: "dimensions://schema/version";
+    readonly limits: "dimensions://schema/limits";
+    readonly policy: "dimensions://schema/policy";
+    readonly fields: "dimensions://fields/{entityType}";
+    readonly source: "dimensions://schema/sources/{sourceName}";
+    readonly entity: "dimensions://schema/entities/{entityName}";
+    readonly examples: "dimensions://examples";
+    readonly examplesBySource: "dimensions://examples/{source}";
+};
+/** Per-source counts derived from describe schema. */
+export type SchemaSourceSummary = {
+    readonly filterableFieldCount: number;
+    readonly facetFieldCount: number;
+    readonly searchIndexCount: number;
+    readonly metricCount: number;
+    readonly fieldsetNames: readonly string[];
+};
+/** Compact schema overview for agents and MCP tools. */
+export type SchemaSummary = {
+    readonly version: string | undefined;
+    readonly loadedAt: string;
+    readonly cachedAt: string | undefined;
+    readonly stale: boolean;
+    readonly loadSource: "api" | "cache";
+    readonly limits: typeof SCHEMA_LIMITS;
+    readonly stats: {
+        readonly sourceCount: number;
+        readonly entityCount: number;
+        readonly structuredEntityTypes: readonly string[];
+    };
+    readonly sources: Readonly<Record<string, SchemaSourceSummary>>;
+    readonly entities: readonly string[];
+    readonly resources: typeof SCHEMA_RESOURCE_URIS;
+    readonly hint: string;
+};
+/**
+ * Builds a compact schema summary from a loaded {@link SchemaStore}.
+ * @param store - Loaded schema store
+ * @returns Summary payload for tools and resources
+ */
+export declare function buildSchemaSummary(store: SchemaStore): SchemaSummary;
+//# sourceMappingURL=summary.d.ts.map

package/dist/dsl/schema/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../../src/dsl/schema/summary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAWvB,CAAC;AAEX,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;KACnD,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,oBAAoB,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAuCpE"}