🪢 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
import { z } from "zod";
import {
getValidAggregationsForMeasureType,
metricAggregations,
resolveWidgetEditorVersion,
viewDeclarations,
views,
type ViewVersion,
} from "@langfuse/shared/query";
import {
getWidgetImportFilterConfig,
normalizeStoredWidgetFiltersForEditor,
partitionStoredUiTableFiltersToView,
} from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import startCase from "lodash/startCase";
import {
ChartConfigSchema,
DimensionSchema,
MetricSchema,
singleFilterList,
type FilterState,
} from "@langfuse/shared";
import { dashboardWidgetChartTypeSchema } from "@/src/features/widgets/lib/dashboardWidgetChartTypes";
import {
MAX_PIVOT_TABLE_DIMENSIONS,
MAX_PIVOT_TABLE_METRICS,
} from "@/src/features/widgets/utils/pivot-table-utils";
const widgetMetricSchema = MetricSchema.extend({
agg: metricAggregations,
});
/**
* Widget JSON file-format version. `$langfuseWidget: true` marks a JSON
* payload (file or clipboard text) as a Langfuse widget export and `version`
* is the version of that envelope — bump it when the export shape changes
* incompatibly. Distinct from the widget's own `minVersion`, which is the
* query-engine (v1/v2) version.
*/
export const WIDGET_FILE_FORMAT_VERSION = 1;
const widgetImportBaseSchema = z
.object({
$langfuseWidget: z.literal(true).optional(),
version: z.number().int().positive().optional(),
name: z.string(),
description: z.string(),
view: views,
dimensions: z.array(DimensionSchema),
metrics: z.array(widgetMetricSchema),
filters: singleFilterList,
chartType: dashboardWidgetChartTypeSchema,
chartConfig: ChartConfigSchema,
minVersion: z.number().int().optional(),
})
.loose();
const widgetImportSchema = widgetImportBaseSchema.superRefine((widget, ctx) => {
if (widget.chartConfig.type !== widget.chartType) {
ctx.addIssue({
code: "custom",
path: ["chartConfig", "type"],
message: "chartConfig.type must match chartType",
});
}
if (
widget.$langfuseWidget === true &&
(widget.version ?? 1) > WIDGET_FILE_FORMAT_VERSION
) {
ctx.addIssue({
code: "custom",
path: ["version"],
message: `Unsupported widget format version ${widget.version}`,
});
}
});
export type WidgetImport = z.infer<typeof widgetImportSchema>;
/**
* True when a parsed JSON payload carries the Langfuse widget envelope.
* Clipboard and drag-drop flows use this to distinguish "not a widget at all"
* (silently ignore) from "claims to be a widget but is malformed" (surface an
* error).
*/
function isLangfuseWidgetPayload(parsed: unknown): boolean {
return (
typeof parsed === "object" &&
parsed !== null &&
"$langfuseWidget" in parsed &&
(parsed as Record<string, unknown>).$langfuseWidget === true
);
}
export type WidgetImportOptionSets = {
environmentValues?: string[];
traceNames?: string[];
tags?: string[];
toolNames?: string[];
calledToolNames?: string[];
modelNames?: string[];
observationLevels: string[];
};
export type ImportedWidgetFormSnapshot = {
widgetMinVersion: number;
widgetName: string;
widgetDescription: string;
selectedView: WidgetImport["view"];
selectedChartType: WidgetImport["chartType"];
selectedMeasure: string;
selectedAggregation: z.infer<typeof metricAggregations>;
selectedMetrics: {
id: string;
measure: string;
aggregation: z.infer<typeof metricAggregations>;
label: string;
}[];
selectedDimension: string;
pivotDimensions: string[];
userFilterState: FilterState;
rowLimit: number;
histogramBins: number;
defaultSortColumn: string;
defaultSortOrder: "ASC" | "DESC";
};
export type ImportedWidgetResult = {
snapshot: ImportedWidgetFormSnapshot;
removedValues: boolean;
removedFilters: boolean;
};
export function buildWidgetImportAllowedValues(
options: WidgetImportOptionSets,
parsedJson: unknown,
): Map<string, Set<string>> {
const allowedValuesByColumn = new Map<string, Set<string>>();
if (options.environmentValues) {
allowedValuesByColumn.set(
"environment",
new Set(options.environmentValues),
);
}
if (options.traceNames) {
const traceNameValues = new Set(options.traceNames);
allowedValuesByColumn.set("traceName", traceNameValues);
allowedValuesByColumn.set("name", traceNameValues);
}
if (options.tags) {
allowedValuesByColumn.set("tags", new Set(options.tags));
}
if (options.toolNames) {
allowedValuesByColumn.set("toolNames", new Set(options.toolNames));
}
if (
typeof parsedJson === "object" &&
parsedJson !== null &&
"view" in parsedJson &&
parsedJson.view === "observations"
) {
if (options.calledToolNames) {
allowedValuesByColumn.set(
"calledToolNames",
new Set(options.calledToolNames),
);
}
if (options.modelNames) {
allowedValuesByColumn.set(
"providedModelName",
new Set(options.modelNames),
);
}
allowedValuesByColumn.set("level", new Set(options.observationLevels));
}
return allowedValuesByColumn;
}
export type WidgetExportSource = Pick<
WidgetImport,
| "name"
| "description"
| "view"
| "dimensions"
| "metrics"
| "filters"
| "chartType"
| "chartConfig"
| "minVersion"
>;
/**
* The canonical widget export shape: the widget's portable configuration
* wrapped in the Langfuse widget envelope. Downloaded files and
* copied-to-clipboard widgets both serialize exactly this object.
*/
export function buildWidgetExport(widget: WidgetExportSource) {
return {
$langfuseWidget: true as const,
version: WIDGET_FILE_FORMAT_VERSION,
name: widget.name,
description: widget.description,
view: widget.view,
dimensions: widget.dimensions,
metrics: widget.metrics,
filters: widget.filters,
chartType: widget.chartType,
chartConfig: widget.chartConfig,
minVersion: widget.minVersion,
};
}
export function downloadWidgetJson(widget: WidgetExportSource) {
const blob = new Blob([JSON.stringify(buildWidgetExport(widget), null, 2)], {
type: "application/json",
});
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = buildWidgetJsonFileName(widget.name);
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
URL.revokeObjectURL(url);
}
function buildWidgetJsonFileName(widgetName: string) {
const fileSafeName = widgetName
.trim()
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "");
return `${fileSafeName || "widget"}.json`;
}
function normalizeImportedFilters(params: {
filters: FilterState;
view: z.infer<typeof views>;
allowedValuesByColumn: Map<string, Set<string>>;
}): { filters: FilterState; removedValues: boolean; removedFilters: boolean } {
let removedValues = false;
let removedFilters = false;
const { mappedFilters: normalizedLegacyFilters, unsupportedFilters } =
partitionStoredUiTableFiltersToView(params.view, params.filters);
if (unsupportedFilters.length > 0) {
removedFilters = true;
}
const { allowedColumns, columnAliases } = getWidgetImportFilterConfig(
params.view,
);
const filters: FilterState = normalizedLegacyFilters.flatMap<
FilterState[number]
>((filter) => {
const normalizedColumn = columnAliases[filter.column] ?? filter.column;
if (!allowedColumns.has(normalizedColumn)) {
removedFilters = true;
return [];
}
const normalizedFilter = { ...filter, column: normalizedColumn };
if (
normalizedFilter.type !== "stringOptions" &&
normalizedFilter.type !== "arrayOptions" &&
normalizedFilter.type !== "categoryOptions"
) {
return [normalizedFilter];
}
const allowedValues = params.allowedValuesByColumn.get(
normalizedFilter.column,
);
if (!allowedValues) {
return [normalizedFilter];
}
const nextValues = normalizedFilter.value.filter((value) =>
allowedValues.has(value),
);
if (nextValues.length === normalizedFilter.value.length) {
return [normalizedFilter];
}
removedValues = true;
if (nextValues.length === 0) {
return [];
}
return [{ ...normalizedFilter, value: nextValues }];
});
return { filters, removedValues, removedFilters };
}
function normalizeImportedWidget(params: {
widget: WidgetImport;
allowedValuesByColumn: Map<string, Set<string>>;
}): {
widget: WidgetImport;
removedValues: boolean;
removedFilters: boolean;
} {
const sanitizedFilters = normalizeImportedFilters({
view: params.widget.view,
filters: params.widget.filters,
allowedValuesByColumn: params.allowedValuesByColumn,
});
return {
widget: {
...params.widget,
filters: sanitizedFilters.filters,
},
removedValues: sanitizedFilters.removedValues,
removedFilters: sanitizedFilters.removedFilters,
};
}
export function parseAndNormalizeImportedWidget(params: {
parsedJson: unknown;
allowedValuesByColumn: Map<string, Set<string>>;
}): {
widget: WidgetImport;
removedValues: boolean;
removedFilters: boolean;
} {
const parsed = widgetImportSchema.parse(params.parsedJson);
const normalized = normalizeImportedWidget({
widget: parsed,
allowedValuesByColumn: params.allowedValuesByColumn,
});
return normalized;
}
function validateImportedWidget(params: {
widget: WidgetImport;
importedViewVersion: ViewVersion;
}): void {
const viewDeclaration =
viewDeclarations[params.importedViewVersion][params.widget.view];
const dimensionsAreValid = params.widget.dimensions.every(
(dimension) =>
Boolean(viewDeclaration.dimensions[dimension.field]) &&
!viewDeclaration.dimensions[dimension.field]?.uiHidden,
);
const metricsAreValid = params.widget.metrics.every((metric) => {
const measureDefinition = viewDeclaration.measures[metric.measure];
if (!measureDefinition) {
return false;
}
return getValidAggregationsForMeasureType(measureDefinition.type).some(
(aggregation) => aggregation === metric.agg,
);
});
const dimensionsFitChartType =
params.widget.chartType === "PIVOT_TABLE"
? true
: params.widget.dimensions.length <= 1;
const pivotTableShapeIsValid =
params.widget.chartType !== "PIVOT_TABLE" ||
(params.widget.dimensions.length <= MAX_PIVOT_TABLE_DIMENSIONS &&
params.widget.metrics.length <= MAX_PIVOT_TABLE_METRICS);
if (
!dimensionsAreValid ||
!metricsAreValid ||
!dimensionsFitChartType ||
!pivotTableShapeIsValid
) {
throw new Error("malformed");
}
}
function toImportedWidgetFormSnapshot(
widget: WidgetImport,
): ImportedWidgetFormSnapshot {
const importedMetrics =
widget.metrics.length > 0
? widget.metrics
: [{ measure: "count", agg: "count" as const }];
const importedDimensions =
widget.chartType === "PIVOT_TABLE"
? widget.dimensions
: widget.dimensions.slice(0, 1);
const importedChartConfig = widget.chartConfig;
return {
widgetMinVersion: widget.minVersion ?? 1,
widgetName: widget.name,
widgetDescription: widget.description,
selectedView: widget.view,
selectedChartType: widget.chartType,
selectedMeasure: importedMetrics[0]?.measure ?? "count",
selectedAggregation: importedMetrics[0]?.agg ?? "count",
selectedMetrics: importedMetrics.map((metric) => ({
id: `${metric.agg}_${metric.measure}`,
measure: metric.measure,
aggregation: metric.agg,
label: `${startCase(metric.agg)} ${startCase(metric.measure)}`,
})),
selectedDimension: importedDimensions[0]?.field ?? "none",
pivotDimensions: importedDimensions.map((dimension) => dimension.field),
userFilterState: normalizeStoredWidgetFiltersForEditor(
widget.view,
widget.filters,
).editorFilters,
rowLimit:
"row_limit" in importedChartConfig
? (importedChartConfig.row_limit ?? 100)
: 100,
histogramBins:
importedChartConfig.type === "HISTOGRAM"
? (importedChartConfig.bins ?? 10)
: 10,
defaultSortColumn:
importedChartConfig.type === "PIVOT_TABLE"
? (importedChartConfig.defaultSort?.column ?? "none")
: "none",
defaultSortOrder:
importedChartConfig.type === "PIVOT_TABLE"
? (importedChartConfig.defaultSort?.order ?? "DESC")
: "DESC",
};
}
function normalizeImportedWidgetVersion(widget: WidgetImport): WidgetImport {
if (widget.view !== "traces") {
return widget;
}
// v2 is a deployment/read-path choice for traces, not a v2-only widget
// shape. Keep the persisted hint at the actual minimum while allowing v4
// imports to validate against the events-backed trace declaration.
return {
...widget,
minVersion: 1,
};
}
/**
* Full import pipeline for one parsed widget JSON payload: schema parse,
* filter normalization (value-level pruning only when option sets are
* provided — clipboard/drop flows skip the option queries and pass none),
* traces-view version normalization, and view-declaration validation. The
* imported minVersion is a preview hint only; the write API derives the
* persisted version from the submitted shape.
* Throws on any payload that cannot become a valid widget.
*/
export function parseImportedWidgetJson(params: {
parsedJson: unknown;
optionSets?: WidgetImportOptionSets;
isV4: boolean;
}): { widget: WidgetImport; removedValues: boolean; removedFilters: boolean } {
const allowedValuesByColumn = params.optionSets
? buildWidgetImportAllowedValues(params.optionSets, params.parsedJson)
: new Map<string, Set<string>>();
const {
widget: importedWidget,
removedValues,
removedFilters,
} = parseAndNormalizeImportedWidget({
parsedJson: params.parsedJson,
allowedValuesByColumn,
});
const normalizedWidget = normalizeImportedWidgetVersion(importedWidget);
const importedViewVersion: ViewVersion = resolveWidgetEditorVersion({
shape: {
view: normalizedWidget.view,
dimensions: normalizedWidget.dimensions,
measures: normalizedWidget.metrics.map((metric) => ({
measure: metric.measure,
})),
filters: normalizedWidget.filters,
},
baseMinVersion: normalizedWidget.minVersion ?? 1,
activeVersion: params.isV4 ? "v2" : "v1",
});
validateImportedWidget({
widget: normalizedWidget,
importedViewVersion,
});
return { widget: normalizedWidget, removedValues, removedFilters };
}
export async function importWidgetFile(params: {
file: File;
optionSets: WidgetImportOptionSets;
isV4: boolean;
}): Promise<ImportedWidgetResult> {
const rawContent = await params.file.text();
const parsedJson: unknown = JSON.parse(rawContent);
const { widget, removedValues, removedFilters } = parseImportedWidgetJson({
parsedJson,
optionSets: params.optionSets,
isV4: params.isV4,
});
return {
snapshot: toImportedWidgetFormSnapshot(widget),
removedValues,
removedFilters,
};
}
export type PastedWidgetParseResult =
| { status: "not-widget" }
| { status: "invalid"; reason: string }
| { status: "widget"; widget: WidgetImport; removedFilters: boolean };
/**
* Parses clipboard or dropped text into a widget. Anything that does not
* carry the Langfuse widget envelope is "not-widget" (callers ignore it
* silently); an enveloped payload that fails validation is "invalid" with a
* user-facing reason.
*/
export function parsePastedWidget(
text: string,
params: { isV4: boolean },
): PastedWidgetParseResult {
let parsedJson: unknown;
try {
parsedJson = JSON.parse(text);
} catch {
return { status: "not-widget" };
}
if (!isLangfuseWidgetPayload(parsedJson)) {
return { status: "not-widget" };
}
const declaredVersion = (parsedJson as Record<string, unknown>).version;
if (
typeof declaredVersion === "number" &&
declaredVersion > WIDGET_FILE_FORMAT_VERSION
) {
return {
status: "invalid",
reason: `This widget uses format version ${declaredVersion}; this Langfuse version supports up to ${WIDGET_FILE_FORMAT_VERSION}.`,
};
}
try {
const { widget, removedFilters } = parseImportedWidgetJson({
parsedJson,
isV4: params.isV4,
});
return { status: "widget", widget, removedFilters };
} catch {
return {
status: "invalid",
reason: "The widget configuration is malformed or not supported.",
};
}
}
/**
* Portable widget fields in the shape of the `dashboardWidgets.create`
* mutation input (minus projectId) — used to recreate a pasted, dropped, or
* duplicated widget as a new project-owned widget.
*/
export function toWidgetCreateFields(widget: WidgetExportSource) {
return {
name: widget.name,
description: widget.description,
view: widget.view,
dimensions: widget.dimensions,
metrics: widget.metrics,
filters: widget.filters,
chartType: widget.chartType,
chartConfig: widget.chartConfig,
};
}