πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(search-bar): explain filter tokens on hover (LFE-14447) (#15896)
Nikita Kabardin786496d02f1d
diff --git a/web/src/features/filters/components/FilterToken.stories.tsx b/web/src/features/filters/components/FilterToken.stories.tsxindex 2edc3b1bbf..c1b5ed7b09 100644--- a/web/src/features/filters/components/FilterToken.stories.tsx+++ b/web/src/features/filters/components/FilterToken.stories.tsx@@ -16,6 +16,14 @@ export const Default = meta.story({},});+export const Highlighted = meta.story({+ args: {+ children: "-environment:langfuse-experiments",+ deactivated: false,+ highlighted: true,+ },+});+export const Deactivated = meta.story({args: {children: "environment:none of development",diff --git a/web/src/features/filters/components/FilterToken.tsx b/web/src/features/filters/components/FilterToken.tsxindex 102bb2cd15..5035d53897 100644--- a/web/src/features/filters/components/FilterToken.tsx+++ b/web/src/features/filters/components/FilterToken.tsx@@ -9,6 +9,12 @@ const filterTokenVariants = cva(true: "opacity-50 line-through decoration-1",false: "",},+ // Pointer-independent hover treatment: the caret/keyboard path marks the+ // token an open explanation refers to.+ highlighted: {+ true: "border-ring bg-accent",+ false: "",+ },},},);@@ -16,7 +22,8 @@ const filterTokenVariants = cva(type FilterTokenProps = {children: ReactNode;deactivated: boolean;- title: string | undefined;+ title?: string | undefined;+ highlighted?: boolean;} & {[key: `data-${string}`]: string | boolean | undefined;};@@ -25,6 +32,7 @@ export function FilterToken({children,deactivated,title,+ highlighted = false,...dataAttributes}: FilterTokenProps) {return (@@ -32,7 +40,7 @@ export function FilterToken({{...dataAttributes}data-deactivated={deactivated || undefined}title={title}- className={filterTokenVariants({ deactivated })}+ className={filterTokenVariants({ deactivated, highlighted })}>{children}</span>diff --git a/web/src/features/search-bar/components/ComposerTokens.tsx b/web/src/features/search-bar/components/ComposerTokens.tsxindex 2441eef313..b4ba04b5d7 100644--- a/web/src/features/search-bar/components/ComposerTokens.tsx+++ b/web/src/features/search-bar/components/ComposerTokens.tsx@@ -18,6 +18,7 @@ import {type FilterSegment,} from "@/src/features/search-bar/lib/composer-segments";import { indexOfOutsideQuotes } from "@/src/features/search-bar/lib/langQ";+import { deactivationReason } from "@/src/features/search-bar/components/presentation";import { FilterToken } from "@/src/features/filters/components/FilterToken";// Word joiner around pills: gives the DOM caret boundaries between tokens@@ -46,10 +47,13 @@ export const composerTokenVariants = cva("max-w-full", {},// A filter that the current surface can't apply (e.g. the chart view can't// filter on this column). Dimmed + dashed so it reads as "shown but not- // applied"; the reason is on hover (`title`).+ // applied"; the reason is in the explanation tooltip.deactivated: { true: "opacity-50 line-through decoration-1", false: "" },+ // The token whose explanation is showing. Mirrors the hover treatment, so+ // the caret (keyboard) path highlights exactly like the pointer does.+ highlighted: { true: "border-border bg-accent", false: "" },},- defaultVariants: { kind: "freeText", deactivated: false },+ defaultVariants: { kind: "freeText", deactivated: false, highlighted: false },});type TokenKind = "filter" | "freeText" | "operator" | "paren" | "invalid";@@ -113,10 +117,13 @@ export function ComposerTokens({scoreTypes,fieldReason,freeTextReason,+ highlightedSegmentId,}: {draft: string;showDiagnostics: boolean;scoreTypes?: ScoreTypeContext;+ /** Segment whose explanation tooltip is open β rendered highlighted. */+ highlightedSegmentId?: string | null;/*** Given a filter token's field name, the reason it is NOT applied on the* current surface, or `null` if it is. When it returns a reason the pill@@ -142,27 +149,13 @@ export function ComposerTokens({? "freeText": segment.kind;// "Not applied on this surface" β a filter column the chart can't honour,- // or free text a chart ignores. Only filter/free-text tokens can deactivate- // (operators/parens/invalid never do).- const deactivatedReason =- segment.kind === "filter"- ? (fieldReason?.(segment.displayField) ?? null)- : segment.kind === "freeText"- ? (freeTextReason ?? null)- : null;- const deactivated = deactivatedReason !== null;- // Invalid tokens get the styled per-token error tooltip (a positioned- // overlay in SearchComposer), not the native browser title. A deactivated- // token explains why it is ignored. Free text is a full-text search β say so- // on hover so a standalone text chip explains itself instead of looking like- // a stray block.- const title = deactivated- ? deactivatedReason- : segment.kind === "invalid"- ? undefined- : segment.kind === "freeText"- ? `Full-text search β matches results containing "${segment.raw}". Searches ids, names, input and output by default; use input: or output: to search one payload, or name:/id: to narrow.`- : segment.raw;+ // or free text a chart ignores.+ const deactivated =+ deactivationReason(segment, fieldReason, freeTextReason) !== null;+ const highlighted = segment.id === highlightedSegmentId;+ // No native `title`: hover copy is the styled per-token tooltip that+ // SearchComposer positions (explanation, or the error once diagnostics are+ // revealed). A second, slower browser tooltip on top of it just doubles up.const content = (<>{segment.kind === "filter" ? (@@ -186,8 +179,8 @@ export function ComposerTokens({data-testid="search-bar-token"data-kind={visibleKind}data-segment-id={segment.id}- title={title}deactivated={deactivated}+ highlighted={highlighted}>{content}</FilterToken>@@ -198,8 +191,11 @@ export function ComposerTokens({data-kind={visibleKind}data-deactivated={deactivated || undefined}data-segment-id={segment.id}- title={title}- className={composerTokenVariants({ kind: visibleKind, deactivated })}+ className={composerTokenVariants({+ kind: visibleKind,+ deactivated,+ highlighted,+ })}>{content}</span>diff --git a/web/src/features/search-bar/components/SearchComposer.tsx b/web/src/features/search-bar/components/SearchComposer.tsxindex 06d85abf71..bd994404e0 100644--- a/web/src/features/search-bar/components/SearchComposer.tsx+++ b/web/src/features/search-bar/components/SearchComposer.tsx@@ -29,6 +29,7 @@ import {scoreTypeContextFromObserved,type ObservedOptions,} from "@/src/features/search-bar/lib/observed-options";+import { explainSegment } from "@/src/features/search-bar/lib/explain";import { getRecentSearches } from "@/src/features/search-bar/lib/recent-searches";import {applyPick,@@ -50,6 +51,7 @@ import {} from "@/src/features/search-bar/components/ComposerTokens";import {COMPOSER_PLACEHOLDER,+ deactivationReason,optionDomId,} from "@/src/features/search-bar/components/presentation";import {@@ -63,6 +65,11 @@ const LISTBOX_ID = "search-bar-listbox";// reaches the model or clipboard.const WORD_JOINER_RE = new RegExp(WORD_JOINER, "g");+// Shared by the visible tooltip and its screen-reader description, so a+// deactivated token reads the same either way.+const notAppliedNote = (reason: string) =>+ `Not applied on this view: ${reason}`;+// Stable empty recents reference so the plan memo doesn't churn when recents// are intentionally suppressed (popover closed, or a non-empty draft β recents// show only on an empty bar; see the recents memo).@@ -1166,18 +1173,18 @@ export function SearchComposer({setHoveredTokenId(token?.getAttribute("data-segment-id") ?? null);};- const describedBy =- visibleDiagnostics.length > 0 ? "search-bar-diagnostics" : undefined;-const segments = deriveComposerSegments(draft, scoreTypes);- // The remove affordance targets the hovered token, or β while the editor is- // focused β the token holding a collapsed caret. Not at the trailing- // insertion point, where the user is appending, not editing.- const focusTokenId =+ // The token holding a collapsed caret β the keyboard counterpart to hover.+ // Not at the trailing insertion point, where the user is appending, not+ // editing. Every segment kind qualifies: an operator explains itself on the+ // caret path exactly as it does on hover (it just can't be removed, below).+ const caretSegment =editorFocused && selectionCollapsed && caret < draft.length- ? (segments.find((s) => s.editable && s.from <= caret && caret <= s.to)- ?.id ?? null)+ ? (segments.find((s) => s.from <= caret && caret <= s.to) ?? null): null;+ // The remove affordance targets the hovered token, or the caret token β but+ // only an editable one, since operators/parens have nothing to remove.+ const focusTokenId = caretSegment?.editable === true ? caretSegment.id : null;const removeTargetId = hoveredTokenId ?? focusTokenId;const removeTarget =segments.find((s) => s.editable && s.id === removeTargetId) ?? null;@@ -1191,6 +1198,53 @@ export function SearchComposer({? removeTarget: null;+ // Plain-language explanation of a token (LFE-14447), in the same slot β an+ // error wins it. Hover always explains; the caret path only while the popover+ // is closed, so it never stacks a tooltip over the suggestions you are typing+ // against.+ const explainTarget =+ errorTarget !== null+ ? null+ : hoveredTokenId !== null+ ? (segments.find((s) => s.id === hoveredTokenId) ?? null)+ : plan === null+ ? caretSegment+ : null;+ const explainTargetId = explainTarget?.id ?? null;+ const explanation =+ explainTarget === null ? null : explainSegment(explainTarget);+ const explainDeactivatedReason =+ explainTarget === null+ ? null+ : deactivationReason(explainTarget, fieldReason, freeTextReason);+ // Keyboard/AT path: the caret token's explanation, read through the combobox's+ // description regardless of the popover β including the "not applied" note,+ // which the visible tooltip also carries.+ const caretExplanation =+ caretSegment === null ? null : explainSegment(caretSegment);+ const caretDeactivatedReason =+ caretSegment === null+ ? null+ : deactivationReason(caretSegment, fieldReason, freeTextReason);+ const caretHelp =+ caretExplanation === null+ ? null+ : [+ `${caretExplanation.subject} ${caretExplanation.predicate}`.trim(),+ caretDeactivatedReason === null+ ? null+ : notAppliedNote(caretDeactivatedReason),+ ]+ .filter((part) => part !== null)+ .join(" ");+ const describedBy =+ [+ visibleDiagnostics.length > 0 ? "search-bar-diagnostics" : null,+ caretHelp !== null ? "search-bar-token-help" : null,+ ]+ .filter((id) => id !== null)+ .join(" ") || undefined;+// Measure the remove target's last client rect in the parent's layout// effect: it runs after every commit that can move text, and after all// subtree refs (root + container) are attached.@@ -1198,7 +1252,7 @@ export function SearchComposer({left: number;top: number;} | null>(null);- // Anchors for the per-token error tooltip β left edge of the token, plus its+ // Anchors for the per-token tooltip β left edge of the token, plus its// bottom (default placement, just under the block) and top (used to flip the// tooltip ABOVE the block while the suggestions popover is open below). These// are VIEWPORT coordinates (not container-relative): the tooltip portals to@@ -1206,61 +1260,70 @@ export function SearchComposer({// getClientRects() directly. The bar's band is sticky (it doesn't scroll out// from under the token), so a fixed anchor stays put; it re-measures on draft// change and the container ResizeObserver below, same as the X button.- const [errorPosition, setErrorPosition] = React.useState<{+ const [tooltipPosition, setTooltipPosition] = React.useState<{left: number;belowTop: number;aboveTop: number;} | null>(null);const removeTargetIdActual = removeTarget?.id ?? null;- const measureRemovePosition = React.useCallback(() => {+ // Measured separately from the remove target: an operator token explains+ // itself but is not editable, so it never has a remove X to anchor to.+ const tooltipTargetId =+ errorTarget !== null+ ? errorTarget.id+ : explanation !== null+ ? explainTargetId+ : null;+ const measurePositions = React.useCallback(() => {const root = rootRef.current;const container = containerRef.current;- if (root === null || container === null || removeTargetIdActual === null) {+ const rectsOf = (id: string | null): DOMRectList | null => {+ if (root === null || id === null) return null;+ const el = root.querySelector(`[data-segment-id="${CSS.escape(id)}"]`);+ return el === null ? null : el.getClientRects();+ };++ const removeRects = rectsOf(removeTargetIdActual);+ const lastRect = removeRects?.[removeRects.length - 1] ?? null;+ if (container === null || lastRect === null) {setRemovePosition(null);- setErrorPosition(null);- return;+ } else {+ const containerRect = container.getBoundingClientRect();+ setRemovePosition({+ left: lastRect.right - containerRect.left - 6,+ top: lastRect.top - containerRect.top - 8,+ });}- const el = root.querySelector(- `[data-segment-id="${CSS.escape(removeTargetIdActual)}"]`,++ const tooltipRect = rectsOf(tooltipTargetId)?.[0] ?? null;+ setTooltipPosition(+ tooltipRect === null+ ? null+ : {+ left: tooltipRect.left,+ belowTop: tooltipRect.bottom + 6,+ aboveTop: tooltipRect.top,+ },);- if (el === null) {- setRemovePosition(null);- setErrorPosition(null);- return;- }- const rects = el.getClientRects();- const rect =- rects.length > 0 ? rects[rects.length - 1]! : el.getBoundingClientRect();- const firstRect = rects.length > 0 ? rects[0]! : rect;- const containerRect = container.getBoundingClientRect();- setRemovePosition({- left: rect.right - containerRect.left - 6,- top: rect.top - containerRect.top - 8,- });- setErrorPosition({- left: firstRect.left,- belowTop: firstRect.bottom + 6,- aboveTop: firstRect.top,- });- }, [removeTargetIdActual]);-- // Re-measure when the target or draft text changes.+ }, [removeTargetIdActual, tooltipTargetId]);++ // Re-measure when a target or the draft text changes.React.useLayoutEffect(() => {- measureRemovePosition();- }, [measureRemovePosition, draft]);+ measurePositions();+ }, [measurePositions, draft]);// Those deps miss layout reflows that don't change React state β window// resize, browser zoom, sidebar collapse β which re-wrap the full-width bar// and move the token. Observe the composer surface so the absolutely-// positioned X re-anchors to its token instead of leaving a stale ghost X.React.useEffect(() => {- if (removeTargetIdActual === null) return;+ if (removeTargetIdActual === null && tooltipTargetId === null) return;const container = containerRef.current;if (container === null || typeof ResizeObserver === "undefined") return;- const observer = new ResizeObserver(() => measureRemovePosition());+ const observer = new ResizeObserver(() => measurePositions());observer.observe(container);return () => observer.disconnect();- }, [measureRemovePosition, removeTargetIdActual]);+ }, [measurePositions, removeTargetIdActual, tooltipTargetId]);return (<div@@ -1368,6 +1431,9 @@ export function SearchComposer({scoreTypes={scoreTypes}fieldReason={fieldReason}freeTextReason={freeTextReason}+ highlightedSegmentId={+ explanation !== null ? explainTargetId : errorTarget?.id+ }/></div>{/* "Ask AI" affordance β a plain button, always available so filters can@@ -1441,6 +1507,12 @@ export function SearchComposer({</div>)}+ {caretHelp !== null && (+ <div id="search-bar-token-help" className="sr-only">+ {caretHelp}+ </div>+ )}+{plan !== null && (<AutocompletePopoverplan={plan}@@ -1453,35 +1525,60 @@ export function SearchComposer({/>)}- {/* Per-token error tooltip. The "tooltip" <Layer> renders it on a- body-level container so it escapes the page header's overflow:hidden- clip and z-50 stacking context when it flips above the bar β an- in-flow z-index can't win against either. `fixed` + viewport anchors.- pointer-events-none so moving onto it doesn't change the hovered token- (which would flicker it away). */}- {errorTarget !== null && errorPosition !== null && (- <Layer name="tooltip">- <div- role="tooltip"- style={- plan !== null- ? {- left: errorPosition.left,- top: errorPosition.aboveTop,- transform: "translateY(calc(-100% - 6px))",- }- : { left: errorPosition.left, top: errorPosition.belowTop }- }- className={cn(- "pointer-events-none fixed max-w-[min(360px,calc(100vw-32px))]",- "border-destructive/40 bg-popover text-destructive rounded-md border",- "px-2 py-1 font-sans text-xs leading-snug shadow-md",- )}- >- {errorTarget.message}- </div>- </Layer>- )}+ {/* Per-token tooltip β the error diagnostic, or the token's plain-language+ explanation. The "tooltip" <Layer> renders it on a body-level container+ so it escapes the page header's overflow:hidden clip and z-50 stacking+ context when it flips above the bar β an in-flow z-index can't win+ against either. `fixed` + viewport anchors. pointer-events-none so+ moving onto it doesn't change the hovered token (which would flicker it+ away). */}+ {(errorTarget !== null || explanation !== null) &&+ tooltipPosition !== null && (+ <Layer name="tooltip">+ <div+ role="tooltip"+ data-testid="search-bar-token-tooltip"+ style={+ plan !== null+ ? {+ left: tooltipPosition.left,+ top: tooltipPosition.aboveTop,+ transform: "translateY(calc(-100% - 6px))",+ }+ : {+ left: tooltipPosition.left,+ top: tooltipPosition.belowTop,+ }+ }+ className={cn(+ "pointer-events-none fixed max-w-[min(360px,calc(100vw-32px))]",+ "bg-popover rounded-md border",+ "px-2 py-1 font-sans text-xs leading-snug shadow-md",+ errorTarget !== null+ ? "border-destructive/40 text-destructive"+ : "border-border text-popover-foreground",+ )}+ >+ {errorTarget !== null ? (+ errorTarget.message+ ) : (+ <>+ <span className="font-bold">{explanation?.subject}</span>+ {/* A boolean token's phrase IS the whole explanation β no+ predicate, so no dangling space before the period. */}+ {explanation?.predicate !== "" && (+ <> {explanation?.predicate}</>+ )}+ {explainDeactivatedReason !== null && (+ <span className="text-muted-foreground block pt-0.5">+ {notAppliedNote(explainDeactivatedReason)}+ </span>+ )}+ </>+ )}+ </div>+ </Layer>+ )}</div>);}diff --git a/web/src/features/search-bar/components/presentation.ts b/web/src/features/search-bar/components/presentation.tsindex 9540e81a16..c5ea61635d 100644--- a/web/src/features/search-bar/components/presentation.ts+++ b/web/src/features/search-bar/components/presentation.ts@@ -2,6 +2,8 @@// the autocomplete popover. A separate module (not a component file) so the// component files keep Fast Refresh eligibility.+import type { ComposerSegment } from "@/src/features/search-bar/lib/composer-segments";+// Page-neutral: the bar mounts on both the Observations and Traces tables.export const COMPOSER_PLACEHOLDER ="Search β e.g. level:ERROR, -env:dev, latency:>2, scores.accuracy:>0.8";@@ -16,3 +18,19 @@ export const COMPOSER_PLACEHOLDER =export function optionDomId(listboxId: string, optionId: string): string {return `${listboxId}-opt-${encodeURIComponent(optionId)}`;}++/**+ * Why this token is NOT applied on the current surface (e.g. a column the chart+ * view can't filter on), or null when it is. Shared by the token styling (dim ++ * strike) and the hover tooltip so both read the same source.+ */+export function deactivationReason(+ segment: ComposerSegment,+ fieldReason?: (field: string) => string | null,+ freeTextReason?: string | null,+): string | null {+ if (segment.kind === "filter")+ return fieldReason?.(segment.displayField) ?? null;+ if (segment.kind === "freeText") return freeTextReason ?? null;+ return null;+}diff --git a/web/src/features/search-bar/lib/composer-segments.ts b/web/src/features/search-bar/lib/composer-segments.tsindex 65f8a4e549..624793d207 100644--- a/web/src/features/search-bar/lib/composer-segments.ts+++ b/web/src/features/search-bar/lib/composer-segments.ts@@ -9,7 +9,7 @@// (langQ.ts, edits.ts).import type { ScoreTypeContext } from "./adapter";-import type { ASTNode, FilterNode, Span, TextNode } from "./ast";+import type { ASTNode, CompareOp, FilterNode, Span, TextNode } from "./ast";import { lexTokens, type Diagnostic } from "./langQ";import { validateQuery } from "./validate";@@ -23,6 +23,9 @@ export type FilterSegment = {displayField: string;/** Parsed values β used to color numeric values distinctly. */values: string[];+ /** Parsed operator + value grouping β the token's semantics, for explain.ts. */+ op: CompareOp;+ valueOp?: "or" | "and";negated: boolean;editable: true;};@@ -205,6 +208,8 @@ export function deriveComposerSegments(raw,displayField: node.rawKey ?? node.key,values: node.values,+ op: node.op,+ valueOp: node.valueOp,negated: leaf.negated,editable: true,});diff --git a/web/src/features/search-bar/lib/explain.clienttest.ts b/web/src/features/search-bar/lib/explain.clienttest.tsnew file mode 100644index 0000000000..3e6df9c14a--- /dev/null+++ b/web/src/features/search-bar/lib/explain.clienttest.ts@@ -0,0 +1,101 @@+import { deriveComposerSegments } from "@/src/features/search-bar/lib/composer-segments";+import { explainSegment } from "@/src/features/search-bar/lib/explain";+import { FIELDS } from "@/src/features/search-bar/lib/fields";++/** Explain the nth token of `query` as the tooltip reads it. */+function explain(query: string, index = 0): string | null {+ const segment = deriveComposerSegments(query)[index];+ const explanation = segment === undefined ? null : explainSegment(segment);+ return explanation === null+ ? null+ : `${explanation.subject} ${explanation.predicate}`.trim();+}++describe("explainSegment", () => {+ it("explains the shapes users misread", () => {+ // The reported confusion: what does a leading dash mean, and what is `env`?+ expect(explain("-env:langfuse-experiments")).toBe(+ 'Environment is not "langfuse-experiments".',+ );+ expect(explain("name:(a OR b)")).toBe('Name is exactly "a" or "b".');+ expect(explain("latency:>2")).toBe("Latency is above 2 seconds.");+ });++ it("names the operator each `=` default actually lowers to", () => {+ // Same-looking syntax, three different operators β the whole point of the+ // tooltip. Text columns contain, option columns and metadata match exactly.+ expect(explain("name:chat")).toBe('Name contains "chat".');+ expect(explain("name:=chat")).toBe('Name is exactly "chat".');+ expect(explain("metadata.region:eu")).toBe(+ 'Metadata "region" is exactly "eu".',+ );+ expect(explain("level:ERROR")).toBe('Level is "ERROR".');+ expect(explain("statusMessage:chat*")).toBe(+ 'Status message starts with "chat".',+ );+ // `:=` and the bare form lower to the same numeric filter, so a number+ // never reads as a quoted string.+ expect(explain("latency:=2")).toBe(explain("latency:2"));+ expect(explain("latency:=2")).toBe("Latency is 2 seconds.");+ });++ it("reads a negated comparison as its flipped operator, like the lowering", () => {+ // Comparisons and booleans invert (INVERTED_COMPARISON / !value) instead of+ // hiding, so the copy must too.+ expect(explain("-latency:>2")).toBe("Latency is 2 seconds or less.");+ expect(explain("isRootObservation:true")).toBe("Is root observation.");+ expect(explain("-isRootObservation:true")).toBe("Is not root observation.");+ expect(explain("isRootObservation:false")).toBe("Is not root observation.");+ expect(explain("hasInput:false")).toBe("Has no input.");+ expect(explain("-name:*chat*")).toBe('Name does not contain "chat".');+ expect(explain("startTime:>2026-06-01")).toBe(+ "Start time is after 2026-06-01.",+ );+ expect(explain("-level:(ERROR OR WARNING)")).toBe(+ 'Level is none of "ERROR", "WARNING".',+ );+ });++ it("explains groups, null checks, scores, free text and keywords", () => {+ expect(explain("tags:(a AND b)")).toBe(+ 'Trace tags include all of "a" and "b".',+ );+ expect(explain("tags:a")).toBe('Trace tags include "a".');+ expect(explain("has:endTime")).toBe("End time is set.");+ expect(explain("-has:endTime")).toBe("End time is not set.");+ expect(explain("scores.accuracy:>0.8")).toBe(+ 'Score "accuracy" is above 0.8.',+ );+ expect(explain("totalCost:>0.5")).toBe("Total cost is above $0.5.");+ // The label already says "per second" β don't spell the unit out twice.+ expect(explain("tps:>=50")).toBe("Tokens per second is 50 or more.");+ expect(explain("refund policy")).toBe(+ 'Full-text search for "refund policy" β matches id, name, input and output.',+ );+ expect(explain("level:ERROR AND latency:>2", 1)).toBe(+ "AND β every filter has to match.",+ );+ });++ it("says nothing where it has nothing to say", () => {+ expect(explain("nope:1")).toBeNull(); // unknown field β its own diagnostic+ expect(explain("(")).toBeNull();+ });++ it("gives every registry field a usable label", () => {+ for (const field of FIELDS) {+ // A camelCase id or a unit suffix reads as broken English in a sentence.+ expect(field.label, field.id).not.toMatch(/[a-z][A-Z]|[()$]/);+ if (field.kind === "boolean") {+ // Without this the false case silently falls back to the true phrase.+ expect(field.negatedLabel, field.id).toBeDefined();+ continue;+ }+ // Only array fields get a plural verb ("Trace tags include"); everything+ // else is followed by "is", so a plural label would read "β¦ tokens is".+ if (field.syncMode !== "arrayOption") {+ expect(field.label, field.id).not.toMatch(/s$/);+ }+ }+ });+});diff --git a/web/src/features/search-bar/lib/explain.ts b/web/src/features/search-bar/lib/explain.tsnew file mode 100644index 0000000000..a7c9014f97--- /dev/null+++ b/web/src/features/search-bar/lib/explain.ts@@ -0,0 +1,235 @@+// Plain-language explanation of a single query token: the field in bold, then+// what the token asks of it β "Name is exactly "gpt-5.4"". Pure, no React.+//+// Derived from the parsed token (registry field + operator + values), never a+// per-filter string table β so a new field explains itself. The operator+// semantics mirror adapter.ts's lowering: a negated comparison flips through+// the SAME `INVERTED_COMPARISON` map, and `=` reads as "contains" or "is"+// exactly where the adapter lowers it that way.+//+// The bold lead-in is the FIELD, not the operator: an operator lead-in repeats+// the word the predicate already carries ("Exactly. β¦ is exactly β¦"), and the+// field is the half users actually misread (`env`, `tps`, `-`).++import { INVERTED_COMPARISON } from "./adapter";+import type { CompareOp } from "./ast";+import type { ComposerSegment, FilterSegment } from "./composer-segments";+import { resolveField, type FieldDef, type FieldRef } from "./fields";++export type TokenExplanation = {+ /** Bold lead-in: the field this token filters on. */+ subject: string;+ /** The rest of the sentence, ending in a period. Empty when the subject is+ * the whole explanation (a boolean token states itself). */+ predicate: string;+};++type ComparisonOp = keyof typeof INVERTED_COMPARISON;++function isComparison(op: CompareOp): op is ComparisonOp {+ return op === ">" || op === "<" || op === ">=" || op === "<=";+}++function quote(value: string): string {+ return `"${value}"`;+}++/** `"a"` Β· `"a" or "b"` Β· `"a", "b" or "c"` */+function joinValues(values: string[], conjunction: "or" | "and"): string {+ const quoted = values.map(quote);+ if (quoted.length <= 1) return quoted[0] ?? '""';+ return `${quoted.slice(0, -1).join(", ")} ${conjunction} ${quoted.at(-1)}`;+}++/** Plain list β reads better than "or" after a "none of". */+function commaList(values: string[]): string {+ return values.map(quote).join(", ");+}++/**+ * Number spelled out β "2 seconds", "$0.5". Only units the field's label does+ * not already carry are spelled out ("Tokens per second is 50", not "50 tok/s").+ */+function amount(raw: string, field: FieldDef | undefined): string {+ const value = raw.trim();+ if (field?.unit === "s")+ return `${value} ${value === "1" ? "second" : "seconds"}`;+ if (field?.unit === "$") return `$${value}`;+ return value;+}++/** The token's subject β a field's human name, or a user-defined key. */+function subjectOf(ref: FieldRef): string {+ switch (ref.type) {+ case "field":+ return ref.field.label;+ case "metadata":+ return `Metadata ${quote(ref.key)}`;+ case "scores":+ return ref.level === "trace"+ ? `Trace score ${quote(ref.key)}`+ : `Score ${quote(ref.key)}`;+ case "pseudo":+ return ref.id;+ }+}++function comparisonPredicate(+ op: ComparisonOp,+ ref: FieldRef,+ values: string[],+ negated: boolean,+): string {+ const effective = negated ? INVERTED_COMPARISON[op] : op;+ const field = ref.type === "field" ? ref.field : undefined;+ const raw = values[0] ?? "";+ if (field?.kind === "datetime") {+ return {+ ">": `is after ${raw}`,+ ">=": `is on or after ${raw}`,+ "<": `is before ${raw}`,+ "<=": `is on or before ${raw}`,+ }[effective];+ }+ const value = amount(raw, field);+ return {+ ">": `is above ${value}`,+ ">=": `is ${value} or more`,+ "<": `is below ${value}`,+ "<=": `is ${value} or less`,+ }[effective];+}++/** Predicate for `=`, whose meaning depends on the field's sync mode. */+function defaultOpPredicate(ref: FieldRef, seg: FilterSegment): string {+ const { values, valueOp, negated } = seg;+ const many = values.length > 1;++ // stringObject `=` is an exact match β unlike the contains default on a+ // plain text column.+ if (ref.type === "metadata") {+ return negated+ ? `is not exactly ${joinValues(values, "or")}`+ : `is exactly ${joinValues(values, "or")}`;+ }+ if (ref.type === "scores") {+ if (negated)+ return many+ ? `is none of ${commaList(values)}`+ : `is not ${quote(values[0] ?? "")}`;+ return `is ${joinValues(values, "or")}`;+ }+ if (ref.type === "field" && ref.field.syncMode === "arrayOption") {+ if (valueOp === "and") return `include all of ${joinValues(values, "and")}`;+ if (negated)+ return many+ ? `include none of ${commaList(values)}`+ : `do not include ${quote(values[0] ?? "")}`;+ return `include ${joinValues(values, "or")}`;+ }+ // Bare `=` on a text column is a substring search; grouped values are an+ // exact set (stringOptions), so they read differently.+ if (ref.type === "field" && ref.field.syncMode === "textSearch" && !many) {+ return negated+ ? `does not contain ${quote(values[0] ?? "")}`+ : `contains ${quote(values[0] ?? "")}`;+ }+ const exactly =+ ref.type === "field" && ref.field.syncMode === "textSearch"+ ? "exactly "+ : "";+ if (negated)+ return many+ ? `is none of ${commaList(values)}`+ : `is not ${exactly}${quote(values[0] ?? "")}`;+ return `is ${exactly}${joinValues(values, "or")}`;+}++function predicateOf(ref: FieldRef, seg: FilterSegment): string {+ const { op, values, negated } = seg;++ if (isComparison(op)) return comparisonPredicate(op, ref, values, negated);++ // Number equality, before the string-operator switch: `latency:2` and+ // `latency:=2` lower to the SAME numeric filter, so both must read "is 2+ // seconds" β not a quoted, unitless "is exactly "2"" for the `:=` spelling.+ if (ref.type === "field" && ref.field.kind === "number") {+ const value = amount(values[0] ?? "", ref.field);+ return negated ? `is not ${value}` : `is ${value}`;+ }++ switch (op) {+ case "exact":+ return negated+ ? `is not exactly ${joinValues(values, "or")}`+ : `is exactly ${joinValues(values, "or")}`;+ case "~":+ return negated+ ? `does not contain ${joinValues(values, "or")}`+ : `contains ${joinValues(values, "or")}`;+ case "^":+ return `starts with ${quote(values[0] ?? "")}`;+ case "$":+ return `ends with ${quote(values[0] ?? "")}`;+ default:+ return defaultOpPredicate(ref, seg);+ }+}++/** A boolean token needs no value in the copy: "Is not root observation." */+function explainBoolean(field: FieldDef, seg: FilterSegment): TokenExplanation {+ const asked = (seg.values[0] ?? "").trim().toLowerCase() === "true";+ const holds = seg.negated ? !asked : asked;+ const phrase = holds ? field.label : (field.negatedLabel ?? field.label);+ return { subject: `${phrase}.`, predicate: "" };+}++/** `has:` reads about its VALUE β the field that is (or isn't) set. */+function explainHas(seg: FilterSegment): TokenExplanation {+ const labels = seg.values.map((value) => {+ const ref = resolveField(value);+ return ref === null ? value : subjectOf(ref);+ });+ const verb = labels.length > 1 ? "are" : "is";+ return {+ subject: labels.join(" and "),+ predicate: seg.negated ? `${verb} not set.` : `${verb} set.`,+ };+}++const KEYWORDS: Record<string, TokenExplanation> = {+ AND: { subject: "AND", predicate: "β every filter has to match." },+ OR: { subject: "OR", predicate: "β either side can match." },+ NOT: { subject: "NOT", predicate: "β excludes the filter that follows." },+};++/**+ * Explain one token in plain language, or null when there is nothing useful to+ * say (parentheses, an unknown field, an invalid token β those carry their own+ * diagnostic).+ */+export function explainSegment(seg: ComposerSegment): TokenExplanation | null {+ switch (seg.kind) {+ case "filter": {+ const ref = resolveField(seg.displayField);+ if (ref === null) return null;+ if (ref.type === "pseudo") return explainHas(seg);+ if (ref.type === "field" && ref.field.kind === "boolean") {+ return explainBoolean(ref.field, seg);+ }+ return {+ subject: subjectOf(ref),+ predicate: `${predicateOf(ref, seg)}.`,+ };+ }+ case "freeText":+ return {+ subject: "Full-text search",+ predicate: `for ${quote(seg.raw.trim())} β matches id, name, input and output.`,+ };+ case "operator":+ return KEYWORDS[seg.raw.toUpperCase()] ?? null;+ default:+ return null;+ }+}diff --git a/web/src/features/search-bar/lib/fields.ts b/web/src/features/search-bar/lib/fields.tsindex 24e5c35ada..179caf442a 100644--- a/web/src/features/search-bar/lib/fields.ts+++ b/web/src/features/search-bar/lib/fields.ts@@ -29,6 +29,15 @@ export type FieldDef = {aliases: string[];kind: FieldKind;syncMode: SyncMode;+ /** Human name, used as the subject of a token's explanation ("Total cost is+ * above $0.5") β the canonical id is camelCase and does not read as prose.+ * On a `boolean` field this is the whole affirmative phrase instead ("Is+ * root observation"), since such a token is a yes/no statement, not a+ * subject with a value. */+ label: string;+ /** Boolean fields only: the phrase for the false case ("Is not root+ * observation") β English negates these irregularly (is not / has no). */+ negatedLabel?: string;description: string;/** Display unit for numeric suggestion labels (filter-config units). */unit?: string;@@ -45,50 +54,50 @@ export type FieldDef = {// prettier-ignoreexport const FIELDS: FieldDef[] = [- { id: "id", aliases: ["spanid", "span_id", "observationid", "observation_id"], kind: "text", syncMode: "textSearch", suggestObservedValues: true, description: "Observation/span identifier" },- { id: "traceId", aliases: ["traceid", "trace_id"], kind: "text", syncMode: "textSearch", description: "Trace identifier" },- { id: "name", aliases: [], kind: "text", syncMode: "textSearch", suggestObservedValues: true, description: "Observation name", nullable: true },- { id: "traceName", aliases: ["tracename", "trace_name"], kind: "text", syncMode: "exactOption", description: "Trace name", nullable: true },- { id: "type", aliases: [], kind: "text", syncMode: "exactOption", description: "Observation type" },- { id: "environment", aliases: ["env"], kind: "text", syncMode: "exactOption", description: "Environment", nullable: true },- { id: "ingestionApiKey", aliases: ["ingestionapikey", "ingestion_api_key", "apikey", "api_key", "publickey", "public_key"], kind: "text", syncMode: "exactOption", description: "Public ingestion API key" },- { id: "userId", aliases: ["userid", "user_id", "user"], kind: "text", syncMode: "exactOption", description: "Trace user id", nullable: true },- { id: "sessionId", aliases: ["sessionid", "session_id", "session"], kind: "text", syncMode: "exactOption", description: "Trace session id", nullable: true },- { id: "level", aliases: [], kind: "text", syncMode: "exactOption", description: "Observation level" },- { id: "statusMessage", aliases: ["statusmessage", "status_message", "status"], kind: "text", syncMode: "textSearch", description: "Status message", nullable: true },- { id: "modelId", aliases: ["modelid", "model_id"], kind: "text", syncMode: "exactOption", description: "Internal model id", nullable: true },- { id: "providedModelName", aliases: ["providedmodelname", "provided_model_name", "model"], kind: "text", syncMode: "exactOption", description: "Provided model name", nullable: true },- { id: "promptName", aliases: ["promptname", "prompt_name", "prompt"], kind: "text", syncMode: "exactOption", description: "Prompt name", nullable: true },- { id: "promptVersion", aliases: ["promptversion", "prompt_version"], kind: "number", syncMode: "textSearch", description: "Prompt version", nullable: true },- { id: "startTime", aliases: ["starttime", "start_time"], kind: "datetime", syncMode: "textSearch", description: "Observation start time" },- { id: "endTime", aliases: ["endtime", "end_time"], kind: "datetime", syncMode: "textSearch", description: "Observation end time", nullable: true },- { id: "latency", aliases: [], kind: "number", syncMode: "textSearch", description: "Observation latency in seconds", unit: "s", nullable: true },- { id: "timeToFirstToken", aliases: ["timetofirsttoken", "time_to_first_token", "ttft"], kind: "number", syncMode: "textSearch", description: "Time to first token in seconds", unit: "s", nullable: true },- { id: "tokensPerSecond", aliases: ["tokenspersecond", "tokens_per_second", "tps"], kind: "number", syncMode: "textSearch", description: "Output tokens per second", unit: "tok/s", nullable: true },- { id: "inputTokens", aliases: ["inputtokens", "input_tokens"], kind: "number", syncMode: "textSearch", description: "Input token count", nullable: true },- { id: "outputTokens", aliases: ["outputtokens", "output_tokens"], kind: "number", syncMode: "textSearch", description: "Output token count", nullable: true },- { id: "totalTokens", aliases: ["totaltokens", "total_tokens", "tokens"], kind: "number", syncMode: "textSearch", description: "Total token count", nullable: true },- { id: "inputCost", aliases: ["inputcost", "input_cost"], kind: "number", syncMode: "textSearch", description: "Input cost in USD", unit: "$", nullable: true },- { id: "outputCost", aliases: ["outputcost", "output_cost"], kind: "number", syncMode: "textSearch", description: "Output cost in USD", unit: "$", nullable: true },- { id: "totalCost", aliases: ["totalcost", "total_cost", "cost"], kind: "number", syncMode: "textSearch", description: "Total cost in USD", unit: "$", nullable: true },- { id: "version", aliases: [], kind: "text", syncMode: "exactOption", description: "Version tag", nullable: true },- { id: "release", aliases: [], kind: "text", syncMode: "exactOption", description: "Release tag", nullable: true },- { id: "traceTags", aliases: ["tracetags", "trace_tags", "tags", "tag"], kind: "text", syncMode: "arrayOption", description: "Trace tags" },- { id: "isRootObservation", aliases: ["isrootobservation", "is_root_observation", "root"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation is a trace root" },- { id: "hasParentObservation", aliases: ["hasparentobservation", "has_parent_observation"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has a parent (inverse of root)" },- { id: "hasInput", aliases: ["hasinput", "has_input"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has input" },- { id: "hasOutput", aliases: ["hasoutput", "has_output"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has output" },- { id: "toolNames", aliases: ["toolnames", "tool_names"], kind: "text", syncMode: "arrayOption", description: "Available tool names", nullable: true },- { id: "calledToolNames", aliases: ["calledtoolnames", "called_tool_names", "calledtools", "called_tools"], kind: "text", syncMode: "arrayOption", description: "Called tool names", nullable: true },- { id: "toolDefinitions", aliases: ["tooldefinitions", "tool_definitions"], kind: "number", syncMode: "textSearch", description: "Available tool count", nullable: true },- { id: "toolCalls", aliases: ["toolcalls", "tool_calls"], kind: "number", syncMode: "textSearch", description: "Tool call count", nullable: true },- { id: "commentCount", aliases: ["commentcount", "comment_count"], kind: "number", syncMode: "textSearch", description: "Comment count" },- { id: "commentContent", aliases: ["commentcontent", "comment_content", "comment"], kind: "text", syncMode: "textSearch", description: "Comment text", nullable: true },- { id: "experimentDatasetId", aliases: ["experimentdatasetid", "experiment_dataset_id", "dataset"], kind: "text", syncMode: "exactOption", description: "Experiment dataset identifier", nullable: true },- { id: "experimentId", aliases: ["experimentid", "experiment_id"], kind: "text", syncMode: "exactOption", description: "Experiment identifier", nullable: true },- { id: "experimentName", aliases: ["experimentname", "experiment_name", "experiment"], kind: "text", syncMode: "exactOption", description: "Experiment name", nullable: true },- { id: "input", aliases: [], kind: "text", syncMode: "textSearch", description: "Observation input", nullable: true },- { id: "output", aliases: [], kind: "text", syncMode: "textSearch", description: "Observation output", nullable: true },+ { id: "id", aliases: ["spanid", "span_id", "observationid", "observation_id"], kind: "text", syncMode: "textSearch", suggestObservedValues: true, label: "Observation ID", description: "Observation/span identifier" },+ { id: "traceId", aliases: ["traceid", "trace_id"], kind: "text", syncMode: "textSearch", label: "Trace ID", description: "Trace identifier" },+ { id: "name", aliases: [], kind: "text", syncMode: "textSearch", suggestObservedValues: true, label: "Name", description: "Observation name", nullable: true },+ { id: "traceName", aliases: ["tracename", "trace_name"], kind: "text", syncMode: "exactOption", label: "Trace name", description: "Trace name", nullable: true },+ { id: "type", aliases: [], kind: "text", syncMode: "exactOption", label: "Type", description: "Observation type" },+ { id: "environment", aliases: ["env"], kind: "text", syncMode: "exactOption", label: "Environment", description: "Environment", nullable: true },+ { id: "ingestionApiKey", aliases: ["ingestionapikey", "ingestion_api_key", "apikey", "api_key", "publickey", "public_key"], kind: "text", syncMode: "exactOption", label: "Ingestion API key", description: "Public ingestion API key" },+ { id: "userId", aliases: ["userid", "user_id", "user"], kind: "text", syncMode: "exactOption", label: "User ID", description: "Trace user id", nullable: true },+ { id: "sessionId", aliases: ["sessionid", "session_id", "session"], kind: "text", syncMode: "exactOption", label: "Session ID", description: "Trace session id", nullable: true },+ { id: "level", aliases: [], kind: "text", syncMode: "exactOption", label: "Level", description: "Observation level" },+ { id: "statusMessage", aliases: ["statusmessage", "status_message", "status"], kind: "text", syncMode: "textSearch", label: "Status message", description: "Status message", nullable: true },+ { id: "modelId", aliases: ["modelid", "model_id"], kind: "text", syncMode: "exactOption", label: "Model ID", description: "Internal model id", nullable: true },+ { id: "providedModelName", aliases: ["providedmodelname", "provided_model_name", "model"], kind: "text", syncMode: "exactOption", label: "Model name", description: "Provided model name", nullable: true },+ { id: "promptName", aliases: ["promptname", "prompt_name", "prompt"], kind: "text", syncMode: "exactOption", label: "Prompt name", description: "Prompt name", nullable: true },+ { id: "promptVersion", aliases: ["promptversion", "prompt_version"], kind: "number", syncMode: "textSearch", label: "Prompt version", description: "Prompt version", nullable: true },+ { id: "startTime", aliases: ["starttime", "start_time"], kind: "datetime", syncMode: "textSearch", label: "Start time", description: "Observation start time" },+ { id: "endTime", aliases: ["endtime", "end_time"], kind: "datetime", syncMode: "textSearch", label: "End time", description: "Observation end time", nullable: true },+ { id: "latency", aliases: [], kind: "number", syncMode: "textSearch", label: "Latency", description: "Observation latency in seconds", unit: "s", nullable: true },+ { id: "timeToFirstToken", aliases: ["timetofirsttoken", "time_to_first_token", "ttft"], kind: "number", syncMode: "textSearch", label: "Time to first token", description: "Time to first token in seconds", unit: "s", nullable: true },+ { id: "tokensPerSecond", aliases: ["tokenspersecond", "tokens_per_second", "tps"], kind: "number", syncMode: "textSearch", label: "Tokens per second", description: "Output tokens per second", unit: "tok/s", nullable: true },+ { id: "inputTokens", aliases: ["inputtokens", "input_tokens"], kind: "number", syncMode: "textSearch", label: "Input token count", description: "Input token count", nullable: true },+ { id: "outputTokens", aliases: ["outputtokens", "output_tokens"], kind: "number", syncMode: "textSearch", label: "Output token count", description: "Output token count", nullable: true },+ { id: "totalTokens", aliases: ["totaltokens", "total_tokens", "tokens"], kind: "number", syncMode: "textSearch", label: "Total token count", description: "Total token count", nullable: true },+ { id: "inputCost", aliases: ["inputcost", "input_cost"], kind: "number", syncMode: "textSearch", label: "Input cost", description: "Input cost in USD", unit: "$", nullable: true },+ { id: "outputCost", aliases: ["outputcost", "output_cost"], kind: "number", syncMode: "textSearch", label: "Output cost", description: "Output cost in USD", unit: "$", nullable: true },+ { id: "totalCost", aliases: ["totalcost", "total_cost", "cost"], kind: "number", syncMode: "textSearch", label: "Total cost", description: "Total cost in USD", unit: "$", nullable: true },+ { id: "version", aliases: [], kind: "text", syncMode: "exactOption", label: "Version", description: "Version tag", nullable: true },+ { id: "release", aliases: [], kind: "text", syncMode: "exactOption", label: "Release", description: "Release tag", nullable: true },+ { id: "traceTags", aliases: ["tracetags", "trace_tags", "tags", "tag"], kind: "text", syncMode: "arrayOption", label: "Trace tags", description: "Trace tags" },+ { id: "isRootObservation", aliases: ["isrootobservation", "is_root_observation", "root"], kind: "boolean", syncMode: "textSearch", label: "Is root observation", negatedLabel: "Is not root observation", description: "Whether the observation is a trace root" },+ { id: "hasParentObservation", aliases: ["hasparentobservation", "has_parent_observation"], kind: "boolean", syncMode: "textSearch", label: "Has a parent observation", negatedLabel: "Has no parent observation", description: "Whether the observation has a parent (inverse of root)" },+ { id: "hasInput", aliases: ["hasinput", "has_input"], kind: "boolean", syncMode: "textSearch", label: "Has input", negatedLabel: "Has no input", description: "Whether the observation has input" },+ { id: "hasOutput", aliases: ["hasoutput", "has_output"], kind: "boolean", syncMode: "textSearch", label: "Has output", negatedLabel: "Has no output", description: "Whether the observation has output" },+ { id: "toolNames", aliases: ["toolnames", "tool_names"], kind: "text", syncMode: "arrayOption", label: "Available tools", description: "Available tool names", nullable: true },+ { id: "calledToolNames", aliases: ["calledtoolnames", "called_tool_names", "calledtools", "called_tools"], kind: "text", syncMode: "arrayOption", label: "Called tools", description: "Called tool names", nullable: true },+ { id: "toolDefinitions", aliases: ["tooldefinitions", "tool_definitions"], kind: "number", syncMode: "textSearch", label: "Available tool count", description: "Available tool count", nullable: true },+ { id: "toolCalls", aliases: ["toolcalls", "tool_calls"], kind: "number", syncMode: "textSearch", label: "Tool call count", description: "Tool call count", nullable: true },+ { id: "commentCount", aliases: ["commentcount", "comment_count"], kind: "number", syncMode: "textSearch", label: "Comment count", description: "Comment count" },+ { id: "commentContent", aliases: ["commentcontent", "comment_content", "comment"], kind: "text", syncMode: "textSearch", label: "Comment text", description: "Comment text", nullable: true },+ { id: "experimentDatasetId", aliases: ["experimentdatasetid", "experiment_dataset_id", "dataset"], kind: "text", syncMode: "exactOption", label: "Experiment dataset ID", description: "Experiment dataset identifier", nullable: true },+ { id: "experimentId", aliases: ["experimentid", "experiment_id"], kind: "text", syncMode: "exactOption", label: "Experiment ID", description: "Experiment identifier", nullable: true },+ { id: "experimentName", aliases: ["experimentname", "experiment_name", "experiment"], kind: "text", syncMode: "exactOption", label: "Experiment name", description: "Experiment name", nullable: true },+ { id: "input", aliases: [], kind: "text", syncMode: "textSearch", label: "Input", description: "Observation input", nullable: true },+ { id: "output", aliases: [], kind: "text", syncMode: "textSearch", label: "Output", description: "Observation output", nullable: true },];const byName = new Map<string, FieldDef>();