import type { FacetResultData } from "@databricks/sdk-vectorsearch/v1";
import type { CapabilityPolicy, ModelProvider, ModelUsage, RetrieveOptions, RetrievedChunk, Retriever, ToolDef } from "@fabric-harness/sdk";
import type { DatabricksAiSearchQueryOptions } from "./vector-search.js";
export interface DatabricksRagRetrievalOptions extends Omit<DatabricksAiSearchQueryOptions, "signal"> {
}
export interface DatabricksRagInput {
    question: string;
    signal?: AbortSignal;
    /** Per-turn native AI Search overrides. Requires a Databricks AI Search retriever. */
    retrieval?: DatabricksRagRetrievalOptions;
}
/**
 * Structured result of one online RAG inference turn.
 * Mirrors the Databricks AI Cookbook chain:
 * preprocess → retrieve (AI Search) → prompt augment → generate → post-process.
 *
 * Fabric does **not** reimplement AI Search or Model Serving — this is a thin
 * orchestration over native Databricks APIs already exposed by this package.
 */
export interface RagTurn {
    question: string;
    /** Query actually sent to AI Search (after optional preprocess). */
    retrievalQuery: string;
    chunks: RetrievedChunk[];
    answer: string;
    /** Retrieved sources available to generation. This does not imply that the answer cited them. */
    sources: Array<{
        id: string;
        textPreview?: string;
        score?: number;
    }>;
    /** Sources actually referenced by an inline `[source-id]` marker in the final answer. */
    citations: Array<{
        id: string;
        textPreview?: string;
        score?: number;
    }>;
    model?: string;
    index?: string;
    /** Native AI Search controls and result metadata used for this turn. */
    retrieval?: {
        inputMode?: DatabricksRagRetrievalOptions["inputMode"];
        strategy?: DatabricksRagRetrievalOptions["strategy"];
        nextPageToken?: string;
        facetResult?: FacetResultData;
    };
    latencyMs: {
        preprocess: number;
        retrieve: number;
        generate: number;
        total: number;
    };
    usage?: ModelUsage;
    /** Augmented prompt sent to the model (useful for eval / debugging). */
    augmentedPrompt: string;
    systemPrompt: string;
}
export interface RagChainPromptOptions {
    /**
     * System instructions for generation. Default is a grounded-answer rubric with citations.
     * Prefer loading long prompts from a skill/role file in app code.
     */
    system?: string;
    /**
     * Template for the user message. Placeholders:
     * - `{{question}}` original user question
     * - `{{context}}` retrieved chunks formatted for the model
     */
    userTemplate?: string;
}
export interface RagChainPostProcessOptions {
    /** Append a footer containing only sources cited inline by the answer. Default true. */
    appendSourcesFooter?: boolean;
    /** Maximum generated answer body characters. A validated sources footer is added afterward. */
    maxAnswerChars?: number;
    /** Reject citation-looking markers that do not match a retrieved source. Default `validate`. */
    citationPolicy?: "validate" | "known-only";
    /** Require at least one valid inline citation when context was retrieved. Default false. */
    requireCitations?: boolean;
    /** Bounded model revision attempts when required citations are missing. Default 2. */
    citationRepairAttempts?: number;
}
export type RagPreprocess = "none" | ((question: string) => string | Promise<string>);
/** Inputs once a bundle (or explicit retriever + model) is resolved. */
export interface DatabricksRagChainResolvedOptions {
    modelProvider: ModelProvider;
    retriever: Retriever;
    /** Optional policy from `databricks()` for agent mode. */
    policy?: CapabilityPolicy;
    /** Optional full tool list from the bundle (agent mode). */
    tools?: ToolDef[];
    model?: string;
    topK?: number;
    /** Maximum characters from all retrieved chunks included in the prompt. Default 32,000. */
    maxContextChars?: number;
    /** Maximum characters included from one retrieved chunk. Default 8,000. */
    maxChunkChars?: number;
    filter?: RetrieveOptions["filter"];
    /** Native AI Search defaults. Per-turn values supplied to invoke/stream take precedence. */
    retrieval?: DatabricksRagRetrievalOptions;
    preprocess?: RagPreprocess;
    prompt?: RagChainPromptOptions;
    postProcess?: RagChainPostProcessOptions;
    /** Index name for telemetry (catalog.schema.index). */
    index?: string;
}
/**
 * Incremental event from {@link DatabricksRagChain.stream}.
 *
 * `delta` events carry raw first-pass model output for live UI. They are
 * emitted **before** citation validation, bounded repair, truncation, and the
 * sources footer run, so the concatenated deltas may differ from the final
 * validated answer. The terminal `turn` event is authoritative — use it for
 * persistence, evaluation export, and cost telemetry, exactly like the SDK's
 * `ModelStreamChunk.done` contract.
 */
export type RagStreamEvent = {
    type: "delta";
    textDelta: string;
} | {
    type: "turn";
    turn: RagTurn;
};
export interface DatabricksRagChain {
    /** Deterministic cookbook-style inference chain (not free-form tool calling). */
    invoke(input: DatabricksRagInput): Promise<RagTurn>;
    /**
     * Streaming variant of {@link invoke}. Yields `delta` events while the model
     * generates, then one terminal `turn` event carrying the same validated
     * {@link RagTurn} `invoke` would return. Falls back to a single delta when
     * the model provider does not implement `stream()`. Citation validation and
     * bounded repair still apply: a failed validation raises from the iterator
     * after deltas were observed, and a repaired answer is only reflected in the
     * terminal `turn`.
     */
    stream(input: DatabricksRagInput): AsyncGenerator<RagStreamEvent, void>;
    /**
     * Agentic path: same AI Search as a governed `search` tool + model provider
     * for multi-step agents. Prefer when the agent also needs SQL/Genie/etc.
     */
    asAgentTools(): {
        modelProvider: ModelProvider;
        tools: ToolDef[];
        policy?: CapabilityPolicy;
        retriever: Retriever;
    };
    readonly retriever: Retriever;
    readonly modelProvider: ModelProvider;
}
/**
 * Thin orchestration of Databricks-native AI Search + Model Serving for the
 * online RAG inference chain documented in the Databricks AI Cookbook.
 *
 * Prefer {@link databricksRagChain} from the package root when you have a
 * `databricks({ aiSearch })` config — it wires the bundle for you.
 *
 * Does **not** implement offline chunking/indexing (use Databricks Jobs/Lakeflow).
 * Does **not** replace Mosaic Agent Evaluation — export turns with rag-eval helpers.
 */
export declare function createDatabricksRagChain(options: DatabricksRagChainResolvedOptions): DatabricksRagChain;
//# sourceMappingURL=rag-chain.d.ts.map