🪢 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 {
HOME_DASHBOARD_PRESET_IDS,
type HomeDashboardPresetId,
type FilterState,
} from "@langfuse/shared";
import {
buildWidgetExport,
parseImportedWidgetJson,
parsePastedWidget,
type WidgetExportSource,
type WidgetImport,
} from "@/src/features/widgets/utils/import-export-utils";
/**
* Dashboard JSON file-format version. `$langfuseDashboard: true` marks a JSON
* payload as a Langfuse dashboard export; `version` is the version of that
* envelope. A dashboard file inlines each referenced widget's portable
* configuration (widgets are recreated on import — DB widget ids do not
* travel across projects/instances).
*/
export const DASHBOARD_FILE_FORMAT_VERSION = 1;
function isLangfuseDashboardPayload(parsed: unknown): boolean {
return (
typeof parsed === "object" &&
parsed !== null &&
"$langfuseDashboard" in parsed &&
(parsed as Record<string, unknown>).$langfuseDashboard === true
);
}
/**
* Preset cards (curated Home components) have no widget configuration — the
* portable payload is just the preset id in its own envelope, so copy-paste
* works uniformly across every tile on a dashboard.
*/
export const PRESET_FILE_FORMAT_VERSION = 1;
export function buildPresetExport(presetId: string) {
return {
$langfusePreset: true as const,
version: PRESET_FILE_FORMAT_VERSION,
presetId,
};
}
export type PastedPresetParseResult =
| { status: "not-preset" }
| { status: "invalid"; reason: string }
| { status: "preset"; presetId: HomeDashboardPresetId };
export function parsePastedPreset(text: string): PastedPresetParseResult {
let parsedJson: unknown;
try {
parsedJson = JSON.parse(text);
} catch {
return { status: "not-preset" };
}
if (
typeof parsedJson !== "object" ||
parsedJson === null ||
(parsedJson as Record<string, unknown>).$langfusePreset !== true
) {
return { status: "not-preset" };
}
const payload = parsedJson as Record<string, unknown>;
if (
typeof payload.version === "number" &&
payload.version > PRESET_FILE_FORMAT_VERSION
) {
return {
status: "invalid",
reason: `This card uses format version ${payload.version}; this Langfuse version supports up to ${PRESET_FILE_FORMAT_VERSION}.`,
};
}
if (
typeof payload.presetId !== "string" ||
!(HOME_DASHBOARD_PRESET_IDS as readonly string[]).includes(payload.presetId)
) {
return {
status: "invalid",
reason: "This preset card is not available in this Langfuse version.",
};
}
return {
status: "preset",
presetId: payload.presetId as HomeDashboardPresetId,
};
}
/**
* True when the text is a payload our paste surfaces can place on a
* dashboard — a widget export or a preset-card export. Used to gate "Paste"
* menu items via the clipboard probe.
*/
export function isPasteablePlacementPayload(
text: string,
params: { isV4: boolean },
): boolean {
if (parsePastedWidget(text, params).status === "widget") return true;
return parsePastedPreset(text).status === "preset";
}
type PlacementPosition = {
x: number;
y: number;
x_size: number;
y_size: number;
};
const placementPositionSchema = {
x: z.number().int().gte(0),
y: z.number().int().gte(0),
x_size: z.number().int().positive(),
y_size: z.number().int().positive(),
};
const dashboardImportPlacementSchema = z.discriminatedUnion("type", [
z
.object({
type: z.literal("widget"),
...placementPositionSchema,
// Validated per widget via parseImportedWidgetJson for normalization
// and precise failure reasons.
widget: z.unknown(),
})
.loose(),
z
.object({
type: z.literal("preset"),
...placementPositionSchema,
presetId: z.string(),
})
.loose(),
]);
const dashboardImportSchema = z
.object({
$langfuseDashboard: z.literal(true),
version: z.number().int().positive(),
name: z.string(),
description: z.string().optional(),
widgets: z.array(dashboardImportPlacementSchema),
})
.loose();
export type DashboardExportPlacement =
| ({ type: "widget"; widgetId: string } & PlacementPosition)
| ({ type: "preset"; presetId: string } & PlacementPosition);
/**
* The canonical dashboard file shape accepted by drag-drop import: dashboard
* metadata plus each placement with its widget's portable configuration
* inlined. There is deliberately no in-app dashboard download (widget-level
* export covers sharing; Clone covers same-project duplication) — this
* builder documents the format and backs the import round-trip tests.
* Placements whose widget cannot be resolved are skipped and counted.
*/
export function buildDashboardExport(params: {
name: string;
description: string;
filters: FilterState;
placements: DashboardExportPlacement[];
widgetsById: Map<string, WidgetExportSource>;
}): { exportPayload: Record<string, unknown>; skippedWidgetCount: number } {
let skippedWidgetCount = 0;
const widgets: Record<string, unknown>[] = [];
for (const placement of params.placements) {
const position = {
x: placement.x,
y: placement.y,
x_size: placement.x_size,
y_size: placement.y_size,
};
if (placement.type === "preset") {
widgets.push({
type: "preset",
presetId: placement.presetId,
...position,
});
continue;
}
const source = params.widgetsById.get(placement.widgetId);
if (!source) {
skippedWidgetCount += 1;
continue;
}
widgets.push({
type: "widget",
...position,
widget: buildWidgetExport(source),
});
}
return {
exportPayload: {
$langfuseDashboard: true,
version: DASHBOARD_FILE_FORMAT_VERSION,
name: params.name,
description: params.description,
filters: params.filters,
widgets,
},
skippedWidgetCount,
};
}
type ParsedDashboardImportPlacement =
| ({ type: "widget"; widget: WidgetImport } & PlacementPosition)
| ({ type: "preset"; presetId: HomeDashboardPresetId } & PlacementPosition);
export type ParsedDashboardImport = {
name: string;
placements: ParsedDashboardImportPlacement[];
/** Presets in the file this Langfuse version does not know — dropped. */
skippedPresetCount: number;
/** True when any widget lost filters during column normalization. */
removedFilters: boolean;
};
export type DashboardImportParseResult =
| { status: "not-dashboard" }
| { status: "invalid"; reason: string }
| { status: "dashboard"; dashboard: ParsedDashboardImport };
/**
* Parses dropped text into a dashboard import. Payloads without the Langfuse
* dashboard envelope are "not-dashboard" (callers may fall back to the widget
* parser); enveloped payloads that fail validation are "invalid" with a
* user-facing reason.
*/
export function parseDashboardImport(
text: string,
params: { isV4: boolean },
): DashboardImportParseResult {
let parsedJson: unknown;
try {
parsedJson = JSON.parse(text);
} catch {
return { status: "not-dashboard" };
}
if (!isLangfuseDashboardPayload(parsedJson)) {
return { status: "not-dashboard" };
}
const declaredVersion = (parsedJson as Record<string, unknown>).version;
if (
typeof declaredVersion === "number" &&
declaredVersion > DASHBOARD_FILE_FORMAT_VERSION
) {
return {
status: "invalid",
reason: `This dashboard uses format version ${declaredVersion}; this Langfuse version supports up to ${DASHBOARD_FILE_FORMAT_VERSION}.`,
};
}
const parsed = dashboardImportSchema.safeParse(parsedJson);
if (!parsed.success) {
return {
status: "invalid",
reason: "The dashboard configuration is malformed or not supported.",
};
}
const placements: ParsedDashboardImportPlacement[] = [];
let skippedPresetCount = 0;
let removedFilters = false;
for (const [index, placement] of parsed.data.widgets.entries()) {
const position = {
x: placement.x,
y: placement.y,
x_size: placement.x_size,
y_size: placement.y_size,
};
if (placement.type === "preset") {
if (
(HOME_DASHBOARD_PRESET_IDS as readonly string[]).includes(
placement.presetId,
)
) {
placements.push({
type: "preset",
presetId: placement.presetId as HomeDashboardPresetId,
...position,
});
} else {
skippedPresetCount += 1;
}
continue;
}
try {
const result = parseImportedWidgetJson({
parsedJson: placement.widget,
isV4: params.isV4,
});
removedFilters = removedFilters || result.removedFilters;
placements.push({ type: "widget", widget: result.widget, ...position });
} catch {
const widgetName =
typeof placement.widget === "object" &&
placement.widget !== null &&
"name" in placement.widget &&
typeof placement.widget.name === "string"
? `"${placement.widget.name}"`
: `#${index + 1}`;
return {
status: "invalid",
reason: `Widget ${widgetName} in the dashboard file is malformed or not supported.`,
};
}
}
if (placements.length === 0) {
return {
status: "invalid",
reason:
skippedPresetCount > 0
? "The dashboard file only contains preset cards that are not available in this Langfuse version."
: "The dashboard file contains no importable widgets.",
};
}
return {
status: "dashboard",
dashboard: {
name: parsed.data.name,
placements,
skippedPresetCount,
removedFilters,
},
};
}