/**
 * natural-language-query - eight operations over a published query grammar.
 *
 * WHAT THIS FILE REPLACES: the tool advertised the eight operations below and
 * served every one of them from a single body that read none of its
 * arguments:
 *
 *     data = { result: "<the operation name> completed successfully" }
 *     return { success: true, data, metadata: { confidence: 0.85, ... } }
 *
 * (written here in quotes rather than as the template literal it was, so the
 * ratchet that detects that stub body by its text does not read this comment
 * as one.)
 *
 * A `translate-sql` that returns "translate-sql completed successfully" and a
 * confidence of 0.85 is worse than one that refuses, because the caller
 * cannot tell the two apart from the shape of the response.
 *
 * WHAT "NATURAL LANGUAGE" MEANS HERE, since the name invites the wrong
 * expectation: the grammar in `query-core.ts` is a restricted controlled
 * language, and its entire vocabulary is published from `PHRASES`. The tool
 * binds what that grammar covers, names every word it read and did not use,
 * names every character it could not read, and refuses when a piece the query
 * needs is absent. It does not infer intent from arbitrary English -- a guess
 * rendered as SQL is indistinguishable from a translation until it runs
 * against the caller's data.
 *
 * WHAT IS NOT CLAIMED: `optimize` reports the rewrites it applied and the
 * index a query would use. It does not claim a speedup, because this package
 * cannot see the caller's data distribution, and a percentage with nothing
 * behind it is the defect this file exists to remove.
 */
import type { CacheEngine } from '../../core/cache-engine.js';
import type { TokenCounter } from '../../core/token-counter.js';
import type { MetricsCollector } from '../../core/metrics.js';
import { SqlDialect, type QuerySchema } from './query-core.js';
export declare const NATURAL_LANGUAGE_QUERY_OPERATIONS: readonly ["parse", "translate-sql", "translate-mongodb", "translate-graphql", "optimize", "validate", "suggest-query", "explain-results"];
export type NaturalLanguageQueryOperation = (typeof NATURAL_LANGUAGE_QUERY_OPERATIONS)[number];
/** The rewrites `optimize` can apply or report, each named in the result. */
export declare enum RewriteRule {
    /** The same field, comparison and value appeared twice. */
    DuplicateFilter = "duplicate-filter",
    /** Two bounds on one field, the looser of which cannot matter. */
    RedundantBound = "redundant-bound",
    /** Two equality filters on one field that no row can satisfy at once. */
    Unsatisfiable = "unsatisfiable",
    /** Ordering a single summary row, which reorders nothing. */
    PointlessOrdering = "pointless-ordering",
    /** A row limit with no ordering, so which rows come back is arbitrary. */
    UnstableLimit = "unstable-limit",
    /** A select that names no column, so every column is read. */
    UnboundedProjection = "unbounded-projection"
}
/** What `validate` can find, each named in the result. */
export declare enum ValidationFinding {
    UnknownSource = "unknown-source",
    UnknownField = "unknown-field",
    TypeMismatch = "type-mismatch",
    ComparisonNotApplicable = "comparison-not-applicable",
    AggregateOnNonNumeric = "aggregate-on-non-numeric",
    Unsatisfiable = "unsatisfiable",
    WordsNotUnderstood = "words-not-understood",
    CharactersNotRead = "characters-not-read"
}
/** What `explain-results` can say about rows measured against their query. */
export declare enum ResultFinding {
    EmptyResult = "empty-result",
    LimitReached = "limit-reached",
    FilterFieldAbsent = "filter-field-absent",
    FilterViolated = "filter-violated",
    OrderingViolated = "ordering-violated",
    OrderingFieldAbsent = "ordering-field-absent"
}
/** The kinds a result column can hold. */
export declare enum ColumnKind {
    Number = "number",
    Text = "text",
    Boolean = "boolean",
    Mixed = "mixed",
    Empty = "empty"
}
export declare const NATURAL_LANGUAGE_QUERY_DEFAULTS: Readonly<{
    dialect: SqlDialect.Ansi;
    suggestionsPerSource: 6;
}>;
export interface NaturalLanguageQueryOptions {
    operation: NaturalLanguageQueryOperation;
    /** The query, written in the published grammar. */
    query?: string;
    /** Sources and their field types, supplied by the caller. */
    schema?: QuerySchema;
    /** A result set to describe, for `explain-results`. */
    rows?: ReadonlyArray<Record<string, unknown>>;
    /** Which source `suggest-query` should write examples for. */
    source?: string;
    dialect?: SqlDialect;
    limit?: number;
    useCache?: boolean;
}
export interface NaturalLanguageQueryResult {
    success: boolean;
    operation: string;
    data: Record<string, unknown>;
    metadata: {
        tokensUsed: number;
        tokensSaved: number;
        cacheHit: boolean;
        processingTime: number;
    };
}
export declare class NaturalLanguageQuery {
    private cache;
    private tokenCounter;
    private metricsCollector;
    constructor(cache: CacheEngine, tokenCounter: TokenCounter, metricsCollector: MetricsCollector);
    run(options: NaturalLanguageQueryOptions): Promise<NaturalLanguageQueryResult>;
    private compute;
    private parse;
    private translateSql;
    private translateMongo;
    private translateGraphql;
    private optimize;
    private validate;
    private checkComparison;
    private fieldsUsed;
    private suggest;
    private explainResults;
    private describeColumn;
    private satisfies;
    private orderBreaks;
}
export declare const NATURALLANGUAGEQUERYTOOL: {
    readonly name: "natural-language-query";
    readonly description: "Parse, translate, optimize and validate queries written in a published restricted grammar, and describe a result set against the query that produced it";
    readonly inputSchema: {
        readonly type: "object";
        readonly properties: {
            readonly operation: {
                readonly type: "string";
                readonly enum: readonly ["parse", "translate-sql", "translate-mongodb", "translate-graphql", "optimize", "validate", "suggest-query", "explain-results"];
                readonly description: "Operation to perform";
            };
            readonly query: {
                readonly type: "string";
                readonly minLength: 1;
                readonly maxLength: 2000;
                readonly description: "A query in the published grammar, e.g. \"average of price from orders where status is active sorted by price descending limit 10\"";
            };
            readonly schema: {
                readonly type: "object";
                readonly description: "Each source mapped to its fields and their types, as { \"users\": { \"id\": \"number\", \"name\": \"string\" } }";
                readonly additionalProperties: {
                    readonly type: "object";
                    readonly additionalProperties: {
                        readonly type: "string";
                        readonly enum: readonly ["number", "string", "boolean", "date"];
                    };
                };
            };
            readonly rows: {
                readonly type: "array";
                readonly minItems: 0;
                readonly description: "A result set to describe, one object per row";
                readonly items: {
                    readonly type: "object";
                };
            };
            readonly source: {
                readonly type: "string";
                readonly minLength: 1;
                readonly description: "Restrict suggest-query to one source from the schema";
            };
            readonly dialect: {
                readonly type: "string";
                readonly enum: readonly SqlDialect[];
                readonly default: SqlDialect.Ansi;
                readonly description: "Which SQL dialect translate-sql renders; they differ in placeholders, identifier quoting and the row-limit clause";
            };
            readonly limit: {
                readonly type: "integer";
                readonly minimum: 1;
                readonly description: "How many suggestions per source suggest-query returns";
            };
            readonly useCache: {
                readonly type: "boolean";
                readonly default: true;
                readonly description: "Enable caching";
            };
        };
        readonly required: readonly ["operation"];
        readonly anyOf: readonly [{
            readonly properties: {
                readonly operation: {
                    readonly const: "parse";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "translate-sql";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "translate-mongodb";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "translate-graphql";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "optimize";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "validate";
                };
            };
            readonly required: readonly ["operation", "query"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "suggest-query";
                };
            };
            readonly required: readonly ["operation", "schema"];
        }, {
            readonly properties: {
                readonly operation: {
                    readonly const: "explain-results";
                };
            };
            readonly required: readonly ["operation", "rows"];
        }];
    };
};
export declare function runNaturalLanguageQuery(options: NaturalLanguageQueryOptions): Promise<NaturalLanguageQueryResult>;
//# sourceMappingURL=natural-language-query.d.ts.map