import type{LyraEventDetailSnapshot}from'../../../internal/lyra-element.js';import{type TemplateResult,type PropertyValues}from'lit';import{LyraElement}from'../../../internal/lyra-element.js';import type{RetrievalChunk}from'../../../ai/types.js';import type{LyraChunk}from'../chunk-inspector/chunk-inspector.class.js';import'../../agent-tools/span-waterfall/span-waterfall.class.js';import'../chunk-inspector/chunk-inspector.class.js';
/** One of the five fixed stages a retrieval pipeline moves through, in order. */
export type RetrievalStageKind='query-rewrite'|'embed'|'retrieve'|'rerank'|'filter';
/**
* Evidence backing one `RetrievalStage`, rendered in that stage's expandable evidence panel.
* `chunks` reuses `RetrievalChunk` (`src/ai/types.ts`) verbatim -- the same shape a retrieval
* step already produces -- and renders through `<lr-chunk-inspector>` rather than new chunk
* markup, mapping `source.id -> sourceId` / `source.name -> title` and preserving the optional
* document `locator` as the inspector's `anchor` (plus visible `page` for page locators).
*/
export interface RetrievalStageEvidence{
/** Free-form text, e.g. the rewritten query string or an embedding model identifier. */
text?:string;
/** Chunks this stage produced or retained, in this stage's own order. */
chunks?:RetrievalChunk[];
/** Arbitrary stage facts (e.g. filter criteria, embedding dimensions), rendered as a plain key/value list. */
metadata?:Record<string,unknown>;}
/**
* One stage in a retrieval pipeline. Projected to one `LyraSpan` for the internal
* `<lr-span-waterfall>` timeline -- `id`/`startMs`/`endMs`/`status` map straight across, `kind`
* maps onto whichever existing `LyraSpan['kind']` fits best (`embed` -> `'embedding'`, `retrieve`
* -> `'retriever'`, `query-rewrite` -> `'llm'`, `rerank`/`filter` -> `'tool'`), and the visible
* bar name is `label` (if set) or the stage's own localized default for `kind`.
*/
export interface RetrievalStage{id:string;kind:RetrievalStageKind;
/** Overrides the localized default label for `kind` (e.g. a specific embedding-model name). */
label?:string;
/** Milliseconds relative to the trace start. */
startMs:number;
/** Milliseconds relative to the trace start. Absent while the stage is still running. */
endMs?:number;
/** Same vocabulary as `LyraSpan.status`. */
status:'pending'|'running'|'success'|'error'|'denied';
/** Secondary text under the stage name, e.g. "12 chunks, top score 0.87". */
detail?:string;evidence?:RetrievalStageEvidence;}export interface LyraRetrievalTraceEventMap{'lr-stage-select':CustomEvent<{stageId:string;}>;'lr-stage-toggle':CustomEvent<{stageId:string;expanded:boolean;}>;'lr-stage-chunk-action':CustomEvent<LyraEventDetailSnapshot<LyraRetrievalTraceChunkActionDetail>>;}
/** Stage-correlated replacement for nested chunk-inspector events. */
export type LyraRetrievalTraceChunkActionDetail={stageId:string;action:'open';chunkId:string;sourceId:string;anchor?:NonNullable<LyraChunk['anchor']>;}|{stageId:string;action:'expand';chunkId:string;expanded:boolean;};
/**
* `<lr-retrieval-trace>` — a retrieval pipeline's stage timeline (query rewriting, embedding,
* retrieval, reranking, filtering), rendered through `<lr-span-waterfall>`'s existing
* time-scaled bar rendering, plus a disclosure list below it exposing each stage's evidence:
* free-form text, retrieved/reranked/filtered chunks via `<lr-chunk-inspector>`, and/or arbitrary
* stage metadata. Never fetches, ranks, or computes retrieval results itself.
*
* Public collection properties take bounded, clone-owned readonly snapshots. Create a new
* collection and reassign it after changes; mutating the assigned array does not update the view.
*
* @customElement lr-retrieval-trace
* @event lr-stage-select - A stage's bar was activated in the timeline (click, Enter, Space). `detail: { stageId }`.
* @event lr-stage-toggle - A stage's evidence panel was expanded or collapsed (via its own toggle,
* or implicitly by selecting that stage in the timeline for the first time). `detail: { stageId, expanded }`.
* @event lr-stage-chunk-action - A chunk inside a stage was opened or expanded. The discriminated
*   detail always includes `stageId` and `action`, so consumers never infer ownership from DOM ancestry.
* @csspart base - The root wrapper.
* @csspart timeline - The internal `<lr-span-waterfall>` element.
* @csspart evidence-list - The wrapper around every stage's evidence disclosure row. Omitted when no stage has evidence.
* @csspart evidence-row - One stage's evidence disclosure row. Omitted for a stage with no evidence.
* @csspart evidence-toggle - A stage's evidence disclosure `<button>`.
* @csspart evidence-toggle-icon - The disclosure button's chevron glyph.
* @csspart evidence-body - A stage's evidence content wrapper, hidden while collapsed.
* @csspart evidence-text - A stage's free-form text evidence.
* @csspart evidence-metadata - A stage's key/value metadata list (a `<dl>`).
* @csspart evidence-metadata-row - One metadata entry's `<dt>`/`<dd>` pair wrapper, inside `evidence-metadata`.
* @csspart evidence-metadata-key - One metadata entry's key (a `<dt>`).
* @csspart evidence-metadata-value - One metadata entry's value (a `<dd>`).
* @csspart chunk-inspector - The stage-owned chunk inspector; its generic child actions are
*   stopped and re-emitted as `lr-stage-chunk-action`.
* @cssprop [--lr-retrieval-trace-active-border=var(--lr-color-brand)] - Border color of the
*   `[part="evidence-row"]` whose stage matches `activeStageId`.
* @status stable
* @since 4.1.0
*/
export declare class LyraRetrievalTrace extends LyraElement<LyraRetrievalTraceEventMap>{protected static readonly ownedCollectionProperties:readonly string[];static styles:import("lit").CSSResultGroup[];protected static readonly immutableEventDetails:readonly string[];
/** The pipeline's stages, in any order -- the internal timeline sorts them by `startMs`. */
stages:readonly RetrievalStage[];
/** Controlled selection, forwarded verbatim to the internal `<lr-span-waterfall>`'s `activeSpanId`. */
activeStageId:string|null;
/** Accessible name for the internal timeline. A host `aria-label` independently names the
*  trace as a whole; an empty value falls back to the timeline's localized default. */
label:string;
/** Ids of stages whose evidence panel is open. Absence means collapsed -- every stage starts collapsed. */
private expandedStageIds;private readonly evidenceDomIdPrefix;
/** `stages`, deduped to the first stage for each nonblank `id` -- keeps the timeline (which
*  `<lr-span-waterfall>` already dedupes internally) and the evidence list (rendered one row
*  per entry here) in agreement, and keeps `expandedStageIds`/`activeStageId` comparisons keyed
*  by an id that identifies exactly one stage. */
private get normalizedStages();private stageLabel;private toSpans;private toggleEvidence;private onStageSelect;protected willUpdate(changed:PropertyValues):void;private renderEvidenceBody;private formatMetadataValue;private renderEvidenceRow;render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-retrieval-trace':LyraRetrievalTrace;}}