import type { LanguageModel } from 'ai';
import type { GroundingIndex, GroundingHit } from './grounding.js';
/** A source the answer was grounded in, for attribution / deep-linking. */
export interface AskSource {
    id: string;
    title?: string;
    url?: string;
}
export interface AnswerHowToOptions {
    model: LanguageModel;
    /** The user's question. */
    query: string;
    /** Documentation index to ground against. */
    index: GroundingIndex;
    /** How many chunks to retrieve (default 5). */
    topK?: number;
    /** Optional prior turns for multi-turn context (client-held in v1). */
    history?: Array<{
        role: 'user' | 'assistant';
        content: string;
    }>;
    /** Aborts the provider call when the client disconnects (avoids wasted spend). */
    abortSignal?: AbortSignal;
    /** Caps the answer's length (and so its token cost). Unset ⇒ the provider default. */
    maxOutputTokens?: number;
}
/** Assemble the retrieved chunks into a labelled context block for the model. */
export declare function buildGroundingContext(hits: GroundingHit[]): string;
/**
 * Answer a how-to question, grounded in the docs index. Returns the full text plus
 * the sources it was grounded in.
 */
export declare function answerHowTo(opts: AnswerHowToOptions): Promise<{
    text: string;
    sources: AskSource[];
}>;
/**
 * Streaming variant — returns the retrieved `sources` immediately (so the UI can show
 * them while tokens arrive) and the live `textStream`.
 */
/** What a how-to stream yields. */
export type AskStreamEvent = 
/** The provider has started responding — a paid call has been made. */
{
    type: 'provider-responded';
}
/** A chunk of answer text. */
 | {
    type: 'text';
    text: string;
};
/**
 * Stream a grounded answer.
 *
 * Built on the SDK's full stream rather than `textStream`, which silently drops
 * error parts (a failed provider call would look like an empty "answer") and
 * gives no signal that the provider was reached. Here a provider error THROWS
 * from the iterator, and `provider-responded` marks the moment a call was paid
 * for — so callers can refund exactly when the provider was never reached.
 */
export declare function streamHowTo(opts: AnswerHowToOptions): {
    sources: AskSource[];
    events: AsyncIterable<AskStreamEvent>;
};