import type { Datum } from "../charts/shared/datumTypes";
import { type ProfileDataOptions } from "./profileData";
import type { ChartCapability, ChartDataProfile, ScaledSuggestionGroups, Suggestion } from "./chartCapabilityTypes";
import type { IntentId } from "./intents";
import { type AudienceProfile } from "./audienceProfile";
import { type DataQualityProfile, type DataScaleProfile } from "./dataScaleProfile";
export interface SuggestChartsOptions extends ProfileDataOptions {
    /** Ranking intent(s). When omitted, suggestions are ranked by mean intent score. */
    intent?: IntentId | IntentId[];
    /** Restrict to these component names. */
    allow?: ReadonlyArray<string>;
    /** Exclude these component names. */
    deny?: ReadonlyArray<string>;
    /** Maximum suggestions to return (default 10). */
    maxResults?: number;
    /** Include variant-level suggestions (default true). */
    includeVariants?: boolean;
    /** Filter out suggestions with a composite score below this (default 0 — keep all). */
    minScore?: number;
    /** Provide a pre-built profile instead of re-deriving from data. */
    profile?: ChartDataProfile;
    /** Override the registry. Defaults to the global capability registry. */
    capabilities?: ReadonlyArray<ChartCapability>;
    /**
     * Audience profile — overrides chart familiarity and applies adoption-target
     * bias to the ranking. See `audienceProfile.ts`.
     */
    audience?: AudienceProfile;
    /**
     * Forward-looking declaration of the dataset's scale (row count, cardinality,
     * field count, growth mode). When provided, the engine biases recommendations
     * toward charts that work at the declared scale rather than the sample size.
     * See `dataScaleProfile.ts`.
     */
    scale?: DataScaleProfile;
    /**
     * Declaration of the dataset's quality (completeness, outliers, type
     * heterogeneity). Affects caveats and biases score modestly. See
     * `dataScaleProfile.ts`.
     */
    quality?: DataQualityProfile;
}
/**
 * Suggest charts for a dataset, ranked by intent suitability.
 *
 * Heuristic-only — does not call an LLM. Designed to be cheap enough to run on every
 * keystroke in a UI, and to feed structured context to an LLM when one is available.
 */
export declare function suggestCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): Suggestion[];
/**
 * One rejected capability: a chart whose `fits()` returned a reason.
 * Surfaced by `explainCapabilityFit` for diagnostic panels and `--doctor` auto-fix.
 */
export interface RejectedCapability {
    component: string;
    family: ChartCapability["family"];
    importPath: ChartCapability["importPath"];
    /** Human-readable reason this chart can't render this profile. */
    reason: string;
}
export interface ExplainCapabilityFitResult {
    /** Capabilities that fit the profile — full ranked suggestion list. */
    fitting: Suggestion[];
    /** Capabilities that did not fit, with their rejection reasons. */
    rejected: RejectedCapability[];
    /** The profile that was evaluated against (provided or computed). */
    profile: ChartDataProfile;
}
/**
 * Like `suggestCharts`, but also returns the capabilities that *didn't* fit
 * along with their rejection reasons. The single best primitive for:
 *   • "Why isn't there a pie chart option?" UI surfaces (vizmart V.4)
 *   • `--doctor` auto-fix loops that need to enumerate alternatives
 *   • Descriptor authoring — quickly see whose `fits()` is too strict
 *
 * Mirrors `suggestCharts` for the fitting side. Rejection enumeration walks
 * every registered capability whether it fits or not.
 */
export declare function explainCapabilityFit(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): ExplainCapabilityFitResult;
/**
 * Score a specific (component, variant) pair against a dataset and (optionally) an intent.
 * Useful for evaluating a chart a user already chose: "is this a good fit for what they want?"
 */
export declare function scoreChart(component: string, data: ReadonlyArray<Datum> | null | undefined, options?: {
    intent?: IntentId | IntentId[];
    variantKey?: string;
    profile?: ChartDataProfile;
}): Suggestion | {
    reason: string;
};
/**
 * Return suggestions grouped by scale band. The "graduation of views" surface:
 * the same data + intent can produce different chart recommendations depending
 * on the row band you optimize for. Useful for narratives like
 * "now → at 10× → at 100×" or for picking the right chart for a sample vs the
 * production dataset.
 *
 * Behavior: runs `suggestCharts` five times (once per band — tiny/small/medium/
 * large/huge), pinning the row band on each pass while keeping all other
 * options stable. Each band returns its own ranked list. The same chart can
 * appear in multiple bands when its sweet spot spans them.
 *
 * The single `effective` value on the return is computed from the *original*
 * options (declared scale or measured profile), so callers can detect which
 * band the user's actual data lives in and highlight that tier.
 */
export declare function suggestChartsGrouped(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions & {
    maxPerBand?: number;
}): ScaledSuggestionGroups;
