Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat: rig up cache api (#6662)

Dylan Madisetticc93f604dd5b
diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.ts
index aea49e3532..828efb772d 100644
--- a/frontend/src/__mocks__/requests.ts
+++ b/frontend/src/__mocks__/requests.ts
@@ -70,6 +70,8 @@ export const MockRequestClient = {
listSecretKeys: vi.fn().mockResolvedValue({ keys: [] }),
writeSecret: vi.fn().mockResolvedValue({}),
invokeAiTool: vi.fn().mockResolvedValue({}),
+ clearCache: vi.fn().mockResolvedValue(null),
+ getCacheInfo: vi.fn().mockResolvedValue(null),
...overrides,
};
},
diff --git a/frontend/src/components/editor/chrome/panels/cache-panel.tsx b/frontend/src/components/editor/chrome/panels/cache-panel.tsx
new file mode 100644
index 0000000000..e52fa9080b
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/cache-panel.tsx
@@ -0,0 +1,216 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { useAtomValue } from "jotai";
+import { DatabaseZapIcon, RefreshCwIcon, Trash2Icon } from "lucide-react";
+import React, { useState } from "react";
+import { useLocale } from "react-aria";
+import { Spinner } from "@/components/icons/spinner";
+import { Button } from "@/components/ui/button";
+import { ConfirmationButton } from "@/components/ui/confirmation-button";
+import { toast } from "@/components/ui/use-toast";
+import { cacheInfoAtom } from "@/core/cache/requests";
+import { useRequestClient } from "@/core/network/requests";
+import { useAsyncData } from "@/hooks/useAsyncData";
+import { cn } from "@/utils/cn";
+import { formatBytes, formatTime } from "@/utils/formatting";
+import { prettyNumber } from "@/utils/numbers";
+import { PanelEmptyState } from "./empty-state";
+
+const CachePanel = () => {
+ const { clearCache, getCacheInfo } = useRequestClient();
+ const cacheInfo = useAtomValue(cacheInfoAtom);
+ const [purging, setPurging] = useState(false);
+ const { locale } = useLocale();
+
+ const { isPending, isFetching, refetch } = useAsyncData(async () => {
+ await getCacheInfo();
+ // Artificially spin the icon if the request is really fast
+ await new Promise((resolve) => setTimeout(resolve, 500));
+ }, []);
+
+ const handlePurge = async () => {
+ try {
+ setPurging(true);
+ await clearCache();
+ toast({
+ title: "Cache purged",
+ description: "All cached data has been cleared",
+ });
+ // Request updated cache info after purge
+ refetch();
+ } catch (err) {
+ toast({
+ title: "Error",
+ description:
+ err instanceof Error ? err.message : "Failed to purge cache",
+ variant: "danger",
+ });
+ } finally {
+ setPurging(false);
+ }
+ };
+
+ // Show spinner only on initial load
+ if (isPending && !cacheInfo) {
+ return <Spinner size="medium" centered={true} />;
+ }
+
+ const refreshButton = (
+ <Button variant="outline" size="sm" onClick={refetch} disabled={isFetching}>
+ {isFetching ? (
+ <Spinner size="small" className="w-4 h-4 mr-2" />
+ ) : (
+ <RefreshCwIcon className="w-4 h-4 mr-2" />
+ )}
+ Refresh
+ </Button>
+ );
+
+ if (!cacheInfo) {
+ return (
+ <PanelEmptyState
+ title="No cache data"
+ description="Cache information is not available."
+ icon={<DatabaseZapIcon />}
+ action={refreshButton}
+ />
+ );
+ }
+
+ const totalHits = cacheInfo.hits;
+ const totalMisses = cacheInfo.misses;
+ const totalTime = cacheInfo.time;
+ const diskTotal = cacheInfo.disk_total;
+ const diskToFree = cacheInfo.disk_to_free;
+
+ const totalRequests = totalHits + totalMisses;
+ const hitRate = totalRequests > 0 ? (totalHits / totalRequests) * 100 : 0;
+
+ // Show empty state if no cache activity
+ if (totalRequests === 0) {
+ return (
+ <PanelEmptyState
+ title="No cache activity"
+ description="The cache has not been used yet. Cached functions will appear here once they are executed."
+ icon={<DatabaseZapIcon />}
+ action={refreshButton}
+ />
+ );
+ }
+
+ return (
+ <div className="flex flex-col h-full overflow-auto">
+ <div className="flex flex-col gap-4 p-4 h-full">
+ {/* Header with Refresh Button */}
+ <div className="flex items-center justify-end">
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6"
+ onClick={refetch}
+ disabled={isFetching}
+ >
+ <RefreshCwIcon
+ className={cn(
+ "h-4 w-4 text-muted-foreground hover:text-foreground",
+ isFetching && "animate-[spin_0.5s]",
+ )}
+ />
+ </Button>
+ </div>
+
+ {/* Statistics Section */}
+ <div className="space-y-3">
+ <h3 className="text-sm font-semibold text-foreground">Statistics</h3>
+ <div className="grid grid-cols-2 gap-3">
+ <StatCard
+ label="Time saved"
+ value={formatTime(totalTime, locale)}
+ description="Total execution time saved"
+ />
+ <StatCard
+ label="Hit rate"
+ value={
+ totalRequests > 0 ? `${prettyNumber(hitRate, locale)}%` : "—"
+ }
+ description={`${prettyNumber(totalHits, locale)} hits / ${prettyNumber(totalRequests, locale)} total`}
+ />
+ <StatCard
+ label="Cache hits"
+ value={prettyNumber(totalHits, locale)}
+ description="Successful cache retrievals"
+ />
+ <StatCard
+ label="Cache misses"
+ value={prettyNumber(totalMisses, locale)}
+ description="Cache not found"
+ />
+ </div>
+ </div>
+
+ {/* Storage Section */}
+ {diskTotal > 0 && (
+ <div className="space-y-3 pt-2 border-t">
+ <h3 className="text-sm font-semibold text-foreground">Storage</h3>
+ <div className="grid grid-cols-1 gap-3">
+ <StatCard
+ label="Disk usage"
+ value={formatBytes(diskTotal, locale)}
+ description={
+ diskToFree > 0
+ ? `${formatBytes(diskToFree, locale)} can be freed`
+ : "Cache storage on disk"
+ }
+ />
+ </div>
+ </div>
+ )}
+
+ <div className="my-auto" />
+
+ {/* Actions Section */}
+ <div className="pt-2 border-t">
+ <ConfirmationButton
+ title="Purge cache?"
+ description="This will permanently delete all cached data. This action cannot be undone."
+ confirmText="Purge"
+ destructive={true}
+ onConfirm={handlePurge}
+ >
+ <Button
+ variant="outlineDestructive"
+ size="xs"
+ disabled={purging}
+ className="w-full"
+ >
+ {purging ? (
+ <Spinner size="small" className="w-3 h-3 mr-2" />
+ ) : (
+ <Trash2Icon className="w-3 h-3 mr-2" />
+ )}
+ Purge Cache
+ </Button>
+ </ConfirmationButton>
+ </div>
+ </div>
+ </div>
+ );
+};
+
+const StatCard: React.FC<{
+ label: string;
+ value: string;
+ description?: string;
+}> = ({ label, value, description }) => {
+ return (
+ <div className="flex flex-col gap-1 p-3 rounded-lg border bg-card">
+ <span className="text-xs text-muted-foreground">{label}</span>
+ <span className="text-lg font-semibold">{value}</span>
+ {description && (
+ <span className="text-xs text-muted-foreground">{description}</span>
+ )}
+ </div>
+ );
+};
+
+export default CachePanel;
diff --git a/frontend/src/components/editor/chrome/panels/empty-state.tsx b/frontend/src/components/editor/chrome/panels/empty-state.tsx
index 86c1c9b099..e8025a2afc 100644
--- a/frontend/src/components/editor/chrome/panels/empty-state.tsx
+++ b/frontend/src/components/editor/chrome/panels/empty-state.tsx
@@ -18,7 +18,9 @@ export const PanelEmptyState = ({
<div className="mx-6 my-6 flex flex-col gap-2">
<div className="flex flex-row gap-2 items-center">
{icon &&
- React.cloneElement(icon, { className: "text-accent-foreground" })}
+ React.cloneElement(icon, {
+ className: "text-accent-foreground flex-shrink-0",
+ })}
<span className="mt-1 text-accent-foreground">{title}</span>
</div>
<span className="text-muted-foreground text-sm">{description}</span>
diff --git a/frontend/src/components/editor/chrome/types.ts b/frontend/src/components/editor/chrome/types.ts
index 615ae28342..94c59ac535 100644
--- a/frontend/src/components/editor/chrome/types.ts
+++ b/frontend/src/components/editor/chrome/types.ts
@@ -5,6 +5,7 @@ import {
BotMessageSquareIcon,
BoxIcon,
DatabaseIcon,
+ DatabaseZapIcon,
FileTextIcon,
FolderTreeIcon,
FunctionSquareIcon,
@@ -35,6 +36,7 @@ export type PanelType =
| "scratchpad"
| "chat"
| "agents"
+ | "cache"
| "secrets"
| "logs";
@@ -77,6 +79,13 @@ export const PANELS: PanelDescriptor[] = [
tooltip: "Manage packages",
position: "sidebar",
},
+ {
+ type: "cache",
+ Icon: DatabaseZapIcon,
+ tooltip: "Manage cache",
+ position: "sidebar",
+ hidden: !getFeatureFlag("cache_panel"),
+ },
{
type: "outline",
Icon: ScrollTextIcon,
diff --git a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
index 6e38debf3e..5df58f9dd5 100644
--- a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
@@ -56,6 +56,7 @@ const LazySecretsPanel = React.lazy(() => import("../panels/secrets-panel"));
const LazySnippetsPanel = React.lazy(() => import("../panels/snippets-panel"));
const LazyTracingPanel = React.lazy(() => import("../panels/tracing-panel"));
const LazyVariablePanel = React.lazy(() => import("../panels/variable-panel"));
+const LazyCachePanel = React.lazy(() => import("../panels/cache-panel"));
export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
const { isSidebarOpen, isTerminalOpen, selectedPanel } = useChromeState();
@@ -176,6 +177,7 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
{selectedPanel === "logs" && <LazyLogsPanel />}
{selectedPanel === "tracing" && <LazyTracingPanel />}
{selectedPanel === "secrets" && <LazySecretsPanel />}
+ {selectedPanel === "cache" && <LazyCachePanel />}
</TooltipProvider>
</Suspense>
</div>
diff --git a/frontend/src/components/ui/button.tsx b/frontend/src/components/ui/button.tsx
index 8464a0f175..e6adbe4fe6 100644
--- a/frontend/src/components/ui/button.tsx
+++ b/frontend/src/components/ui/button.tsx
@@ -70,6 +70,8 @@ const buttonVariants = cva(
link: "underline-offset-4 hover:underline text-link",
linkDestructive:
"underline-offset-4 hover:underline text-destructive underline-destructive",
+ outlineDestructive:
+ "border border-destructive text-destructive hover:bg-destructive/10",
},
size: {
default: "h-10 py-2 px-4",
diff --git a/frontend/src/components/ui/confirmation-button.tsx b/frontend/src/components/ui/confirmation-button.tsx
new file mode 100644
index 0000000000..59908ee050
--- /dev/null
+++ b/frontend/src/components/ui/confirmation-button.tsx
@@ -0,0 +1,85 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import React from "react";
+import {
+ AlertDialog,
+ AlertDialogAction,
+ AlertDialogCancel,
+ AlertDialogContent,
+ AlertDialogDescription,
+ AlertDialogDestructiveAction,
+ AlertDialogFooter,
+ AlertDialogHeader,
+ AlertDialogTitle,
+ AlertDialogTrigger,
+} from "./alert-dialog";
+
+interface ConfirmationButtonProps {
+ /**
+ * The button element to trigger the confirmation dialog
+ */
+ children: React.ReactElement;
+ /**
+ * Title of the confirmation dialog
+ */
+ title: string;
+ /**
+ * Description/message of the confirmation dialog
+ */
+ description: string;
+ /**
+ * Callback when the user confirms the action
+ */
+ onConfirm: () => void;
+ /**
+ * Text for the confirm button (default: "Continue")
+ */
+ confirmText?: string;
+ /**
+ * Text for the cancel button (default: "Cancel")
+ */
+ cancelText?: string;
+ /**
+ * Whether to use destructive styling for the confirm button
+ */
+ destructive?: boolean;
+}
+
+export const ConfirmationButton: React.FC<ConfirmationButtonProps> = ({
+ children,
+ title,
+ description,
+ onConfirm,
+ confirmText = "Continue",
+ cancelText = "Cancel",
+ destructive = false,
+}) => {
+ const [open, setOpen] = React.useState(false);
+
+ const handleConfirm = () => {
+ onConfirm();
+ setOpen(false);
+ };
+
+ const ActionComponent = destructive
+ ? AlertDialogDestructiveAction
+ : AlertDialogAction;
+
+ return (
+ <AlertDialog open={open} onOpenChange={setOpen}>
+ <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
+ <AlertDialogContent>
+ <AlertDialogHeader>
+ <AlertDialogTitle>{title}</AlertDialogTitle>
+ <AlertDialogDescription>{description}</AlertDialogDescription>
+ </AlertDialogHeader>
+ <AlertDialogFooter>
+ <AlertDialogCancel>{cancelText}</AlertDialogCancel>
+ <ActionComponent onClick={handleConfirm}>
+ {confirmText}
+ </ActionComponent>
+ </AlertDialogFooter>
+ </AlertDialogContent>
+ </AlertDialog>
+ );
+};
diff --git a/frontend/src/core/cache/requests.ts b/frontend/src/core/cache/requests.ts
new file mode 100644
index 0000000000..1d4da8c982
--- /dev/null
+++ b/frontend/src/core/cache/requests.ts
@@ -0,0 +1,5 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import type { CacheInfoFetched } from "../kernel/messages";
+
+export const cacheInfoAtom = atom<CacheInfoFetched | null>(null);
diff --git a/frontend/src/core/config/feature-flag.tsx b/frontend/src/core/config/feature-flag.tsx
index 509cbc6e66..2ef9bc9314 100644
--- a/frontend/src/core/config/feature-flag.tsx
+++ b/frontend/src/core/config/feature-flag.tsx
@@ -11,6 +11,7 @@ export interface ExperimentalFeatures {
rtc_v2: boolean;
performant_table_charts: boolean;
chat_modes: boolean;
+ cache_panel: boolean;
sql_linter: boolean;
external_agents: boolean;
sql_mode: boolean;
@@ -23,6 +24,7 @@ const defaultValues: ExperimentalFeatures = {
rtc_v2: false,
performant_table_charts: false,
chat_modes: false,
+ cache_panel: false,
sql_linter: true,
external_agents: import.meta.env.DEV,
sql_mode: false,
diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.ts
index 8458284923..cd57919d6a 100644
--- a/frontend/src/core/islands/bridge.ts
+++ b/frontend/src/core/islands/bridge.ts
@@ -180,6 +180,8 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
listSecretKeys = throwNotImplemented;
writeSecret = throwNotImplemented;
invokeAiTool = throwNotImplemented;
+ clearCache = throwNotImplemented;
+ getCacheInfo = throwNotImplemented;
private async putControlRequest(operation: object) {
await this.rpc.proxy.request.bridge({
diff --git a/frontend/src/core/islands/main.ts b/frontend/src/core/islands/main.ts
index 288ca9ad2c..b90edd19e5 100644
--- a/frontend/src/core/islands/main.ts
+++ b/frontend/src/core/islands/main.ts
@@ -185,6 +185,10 @@ export async function initialize() {
return;
case "reconnected":
return;
+ case "cache-cleared":
+ return;
+ case "cache-info-fetched":
+ return;
default:
logNever(msg.data);
}
diff --git a/frontend/src/core/kernel/messages.ts b/frontend/src/core/kernel/messages.ts
index b9c16c60c6..9a7affbc8f 100644
--- a/frontend/src/core/kernel/messages.ts
+++ b/frontend/src/core/kernel/messages.ts
@@ -43,6 +43,7 @@ export type SecretKeysResult = OperationMessageData<"secret-keys-result">;
export type StartupLogs = OperationMessageData<"startup-logs">;
export type CellMessage = OperationMessageData<"cell-op">;
export type Capabilities = OperationMessageData<"kernel-ready">["capabilities"];
+export type CacheInfoFetched = OperationMessageData<"cache-info-fetched">;
export type MessageOperationUnion = schemas["KnownUnions"]["operation"];
diff --git a/frontend/src/core/network/requests-network.ts b/frontend/src/core/network/requests-network.ts
index 5a7fae5a48..9a18be6ea9 100644
--- a/frontend/src/core/network/requests-network.ts
+++ b/frontend/src/core/network/requests-network.ts
@@ -409,5 +409,19 @@ export function createNetworkRequests(): EditRequests & RunRequests {
})
.then(handleResponse);
},
+ clearCache: async () => {
+ return getClient()
+ .POST("/api/cache/clear", {
+ body: {},
+ })
+ .then(handleResponseReturnNull);
+ },
+ getCacheInfo: async () => {
+ return getClient()
+ .POST("/api/cache/info", {
+ body: {},
+ })
+ .then(handleResponseReturnNull);
+ },
};
}
diff --git a/frontend/src/core/network/requests-static.ts b/frontend/src/core/network/requests-static.ts
index f789f88d91..f1e783c08a 100644
--- a/frontend/src/core/network/requests-static.ts
+++ b/frontend/src/core/network/requests-static.ts
@@ -86,5 +86,7 @@ export function createStaticRequests(): EditRequests & RunRequests {
listSecretKeys: throwNotInEditMode,
writeSecret: throwNotInEditMode,
invokeAiTool: throwNotInEditMode,
+ clearCache: throwNotInEditMode,
+ getCacheInfo: throwNotInEditMode,
};
}
diff --git a/frontend/src/core/network/requests-toasting.ts b/frontend/src/core/network/requests-toasting.ts
index f90c3b0ee5..7177132042 100644
--- a/frontend/src/core/network/requests-toasting.ts
+++ b/frontend/src/core/network/requests-toasting.ts
@@ -64,6 +64,8 @@ export function createErrorToastingRequests(
listSecretKeys: "Failed to fetch secrets",
writeSecret: "Failed to write secret",
invokeAiTool: "Failed to invoke AI tool",
+ clearCache: "Failed to clear cache",
+ getCacheInfo: "", // No toast
};
const handlers = {} as EditRequests & RunRequests;
diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.ts
index f5f7683711..925c37b0ce 100644
--- a/frontend/src/core/network/types.ts
+++ b/frontend/src/core/network/types.ts
@@ -99,6 +99,8 @@ export type OpenTutorialRequest = schemas["OpenTutorialRequest"];
export type TutorialId = OpenTutorialRequest["tutorialId"];
export type InvokeAiToolRequest = schemas["InvokeAiToolRequest"];
export type InvokeAiToolResponse = schemas["InvokeAiToolResponse"];
+export type ClearCacheRequest = schemas["ClearCacheRequest"];
+export type GetCacheInfoRequest = schemas["GetCacheInfoRequest"];
/**
* Requests sent to the BE during run/edit mode.
@@ -188,6 +190,9 @@ export interface EditRequests {
writeSecret: (request: CreateSecretRequest) => Promise<null>;
// AI Tool requests
invokeAiTool: (request: InvokeAiToolRequest) => Promise<InvokeAiToolResponse>;
+ // Cache requests
+ clearCache: () => Promise<null>;
+ getCacheInfo: () => Promise<null>;
}
export type RequestKey = keyof (EditRequests & RunRequests);
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index 79603549e9..cfb2e392de 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -551,6 +551,8 @@ export class PyodideBridge implements RunRequests, EditRequests {
};
invokeAiTool = throwNotImplemented;
+ clearCache = throwNotImplemented;
+ getCacheInfo = throwNotImplemented;
private async putControlRequest(operation: object) {
await this.rpc.proxy.request.bridge({
diff --git a/frontend/src/core/websocket/useMarimoWebSocket.tsx b/frontend/src/core/websocket/useMarimoWebSocket.tsx
index ee15c432f8..0a5c46eea9 100644
--- a/frontend/src/core/websocket/useMarimoWebSocket.tsx
+++ b/frontend/src/core/websocket/useMarimoWebSocket.tsx
@@ -24,6 +24,7 @@ import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
import { Logger } from "@/utils/Logger";
import { reloadSafe } from "@/utils/reload-safe";
import { useAlertActions } from "../alerts/state";
+import { cacheInfoAtom } from "../cache/requests";
import type { CellId, UIElementId } from "../cells/ids";
import { useRunsActions } from "../cells/runs";
import { focusAndScrollCellOutputIntoView } from "../cells/scrollCellIntoView";
@@ -87,6 +88,7 @@ export function useMarimoWebSocket(opts: {
const setKioskMode = useSetAtom(kioskModeAtom);
const setCapabilities = useSetAtom(capabilitiesAtom);
const runtimeManager = useRuntimeManager();
+ const setCacheInfo = useSetAtom(cacheInfoAtom);
const handleMessage = (e: MessageEvent<JsonString<OperationMessage>>) => {
const msg = jsonParseWithSpecialChar(e.data);
@@ -248,6 +250,12 @@ export function useMarimoWebSocket(opts: {
case "secret-keys-result":
SECRETS_REGISTRY.resolve(msg.data.request_id as RequestId, msg.data);
return;
+ case "cache-info-fetched":
+ setCacheInfo(msg.data);
+ return;
+ case "cache-cleared":
+ // Cache cleared, could refresh cache info if needed
+ return;
case "data-source-connections":
addDataSourceConnection({
connections: msg.data.connections.map((conn) => ({
diff --git a/frontend/src/utils/__tests__/formatting.test.ts b/frontend/src/utils/__tests__/formatting.test.ts
new file mode 100644
index 0000000000..2cbed1ac17
--- /dev/null
+++ b/frontend/src/utils/__tests__/formatting.test.ts
@@ -0,0 +1,107 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import { formatBytes, formatTime } from "../formatting";
+
+const locale = "en-US";
+
+describe("formatBytes", () => {
+ it("should format 0 bytes", () => {
+ expect(formatBytes(0, locale)).toBe("0 B");
+ expect(formatBytes(-1, locale)).toBe("0 B");
+ });
+
+ it("should format bytes", () => {
+ expect(formatBytes(100, locale)).toBe("100 B");
+ expect(formatBytes(512, locale)).toBe("512 B");
+ expect(formatBytes(1023, locale)).toBe("1,023 B");
+ });
+
+ it("should format kilobytes", () => {
+ expect(formatBytes(1024, locale)).toBe("1 KB");
+ expect(formatBytes(1536, locale)).toBe("1.5 KB");
+ expect(formatBytes(10240, locale)).toBe("10 KB");
+ });
+
+ it("should format megabytes", () => {
+ expect(formatBytes(1048576, locale)).toBe("1 MB"); // 1024^2
+ expect(formatBytes(1572864, locale)).toBe("1.5 MB"); // 1.5 * 1024^2
+ expect(formatBytes(10485760, locale)).toBe("10 MB");
+ });
+
+ it("should format gigabytes", () => {
+ expect(formatBytes(1073741824, locale)).toBe("1 GB"); // 1024^3
+ expect(formatBytes(1610612736, locale)).toBe("1.5 GB"); // 1.5 * 1024^3
+ expect(formatBytes(10737418240, locale)).toBe("10 GB");
+ });
+
+ it("should format terabytes", () => {
+ expect(formatBytes(1099511627776, locale)).toBe("1 TB"); // 1024^4
+ expect(formatBytes(1649267441664, locale)).toBe("1.5 TB"); // 1.5 * 1024^4
+ });
+
+ it("should respect locale parameter", () => {
+ // German locale uses different separators
+ const bytes = 1536; // 1.5 KB
+ expect(formatBytes(bytes, "de-DE")).toContain("1,5");
+ // US locale uses dot
+ expect(formatBytes(bytes, "en-US")).toContain("1.5");
+ });
+});
+
+describe("formatTime", () => {
+ it("should format 0 seconds", () => {
+ expect(formatTime(0, locale)).toBe("0s");
+ });
+
+ it("should format microseconds", () => {
+ expect(formatTime(0.0000001, locale)).toBe("0.1µs");
+ expect(formatTime(0.0000005, locale)).toBe("0.5µs");
+ expect(formatTime(0.000000999, locale)).toBe("1µs"); // rounded by prettyNumber
+ });
+
+ it("should format milliseconds", () => {
+ expect(formatTime(0.001, locale)).toBe("1ms");
+ expect(formatTime(0.0015, locale)).toBe("1.5ms");
+ expect(formatTime(0.1, locale)).toBe("100ms");
+ expect(formatTime(0.5, locale)).toBe("500ms");
+ expect(formatTime(0.999, locale)).toBe("999ms");
+ });
+
+ it("should format seconds", () => {
+ expect(formatTime(1, locale)).toBe("1s");
+ expect(formatTime(1.5, locale)).toBe("1.5s");
+ expect(formatTime(30, locale)).toBe("30s");
+ expect(formatTime(59.9, locale)).toBe("59.9s");
+ });
+
+ it("should format minutes and seconds", () => {
+ expect(formatTime(60, locale)).toBe("1m");
+ expect(formatTime(90, locale)).toBe("1m 30s");
+ expect(formatTime(150, locale)).toBe("2m 30s");
+ expect(formatTime(3540, locale)).toBe("59m");
+ expect(formatTime(3599, locale)).toBe("59m 59s");
+ });
+
+ it("should format hours and minutes", () => {
+ expect(formatTime(3600, locale)).toBe("1h");
+ expect(formatTime(3660, locale)).toBe("1h 1m");
+ expect(formatTime(5400, locale)).toBe("1h 30m");
+ expect(formatTime(7200, locale)).toBe("2h");
+ expect(formatTime(9000, locale)).toBe("2h 30m");
+ });
+
+ it("should respect locale parameter", () => {
+ // German locale uses comma for decimal separator
+ const time = 1.5;
+ expect(formatTime(time, "de-DE")).toContain("1,5");
+ // US locale uses dot
+ expect(formatTime(time, "en-US")).toContain("1.5");
+ });
+
+ it("should handle edge cases", () => {
+ expect(formatTime(0.0009999, locale)).toBe("999.9µs");
+ expect(formatTime(59.999, locale)).toBe("60s"); // rounded by prettyNumber
+ expect(formatTime(3599.999, locale)).toBe("59m 60s"); // rounded by prettyNumber
+ });
+});
diff --git a/frontend/src/utils/formatting.ts b/frontend/src/utils/formatting.ts
new file mode 100644
index 0000000000..d078f8d5c2
--- /dev/null
+++ b/frontend/src/utils/formatting.ts
@@ -0,0 +1,51 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { prettyNumber } from "./numbers";
+
+/**
+ * Format bytes to human-readable format
+ * @param bytes - Number of bytes to format
+ * @param locale - Optional locale for number formatting
+ * @returns Formatted string (e.g., "1.5 MB")
+ */
+export function formatBytes(bytes: number, locale: string): string {
+ if (bytes === 0 || bytes === -1) {
+ return "0 B";
+ }
+ const k = 1024;
+ const sizes = ["B", "KB", "MB", "GB", "TB"];
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
+ const value = bytes / k ** i;
+ return `${prettyNumber(value, locale)} ${sizes[i]}`;
+}
+
+/**
+ * Format seconds to human-readable time format
+ * @param seconds - Number of seconds to format
+ * @param locale - Optional locale for number formatting
+ * @returns Formatted string (e.g., "1m 30s", "2h 15m", "500ms", "100µs")
+ */
+export function formatTime(seconds: number, locale: string): string {
+ if (seconds === 0) {
+ return "0s";
+ }
+ if (seconds < 0.001) {
+ return `${prettyNumber(seconds * 1_000_000, locale)}µs`;
+ }
+ if (seconds < 1) {
+ return `${prettyNumber(seconds * 1000, locale)}ms`;
+ }
+ if (seconds < 60) {
+ return `${prettyNumber(seconds, locale)}s`;
+ }
+ const minutes = Math.floor(seconds / 60);
+ const secs = seconds % 60;
+ if (minutes < 60) {
+ return secs > 0
+ ? `${minutes}m ${prettyNumber(secs, locale)}s`
+ : `${minutes}m`;
+ }
+ const hours = Math.floor(minutes / 60);
+ const remainingMins = minutes % 60;
+ return remainingMins > 0 ? `${hours}h ${remainingMins}m` : `${hours}h`;
+}
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index 4f4231c96b..11af8e26b1 100644
--- a/marimo/_cli/development/commands.py
+++ b/marimo/_cli/development/commands.py
@@ -127,6 +127,8 @@ def _generate_server_api_schema() -> dict[str, Any]:
ops.SQLTableListPreview,
ops.DataSourceConnections,
ops.SecretKeysResult,
+ ops.CacheCleared,
+ ops.CacheInfoFetched,
ops.QueryParamsSet,
ops.QueryParamsAppend,
ops.QueryParamsDelete,
@@ -221,6 +223,8 @@ def _generate_server_api_schema() -> dict[str, Any]:
requests.FunctionCallRequest,
requests.InstallMissingPackagesRequest,
requests.ListSecretKeysRequest,
+ requests.ClearCacheRequest,
+ requests.GetCacheInfoRequest,
requests.PdbRequest,
requests.PreviewDatasetColumnRequest,
requests.PreviewSQLTableListRequest,
diff --git a/marimo/_messaging/ops.py b/marimo/_messaging/ops.py
index c6755480d1..6ffcb27cc7 100644
--- a/marimo/_messaging/ops.py
+++ b/marimo/_messaging/ops.py
@@ -685,6 +685,24 @@ class SecretKeysResult(Op, tag="secret-keys-result"):
secrets: list[SecretKeysWithProvider]
+class CacheCleared(Op, tag="cache-cleared"):
+ """Result of clearing cache."""
+
+ name: ClassVar[str] = "cache-cleared"
+ bytes_freed: int
+
+
+class CacheInfoFetched(Op, tag="cache-info-fetched"):
+ """Cache statistics information."""
+
+ name: ClassVar[str] = "cache-info-fetched"
+ hits: int
+ misses: int
+ time: float
+ disk_to_free: int
+ disk_total: int
+
+
class UpdateCellIdsRequest(Op, tag="update-cell-ids"):
"""
Update the cell ID ordering of the cells in the notebook.
@@ -734,6 +752,9 @@ MessageOperation = Union[
ValidateSQLResult,
# Secrets
SecretKeysResult,
+ # Cache
+ CacheCleared,
+ CacheInfoFetched,
# Kiosk specific
FocusCell,
UpdateCellCodes,
diff --git a/marimo/_runtime/requests.py b/marimo/_runtime/requests.py
index a2bc79148a..290a546d8e 100644
--- a/marimo/_runtime/requests.py
+++ b/marimo/_runtime/requests.py
@@ -377,6 +377,14 @@ class RefreshSecretsRequest(msgspec.Struct, rename="camel"):
pass
+class ClearCacheRequest(msgspec.Struct, rename="camel"):
+ pass
+
+
+class GetCacheInfoRequest(msgspec.Struct, rename="camel"):
+ pass
+
+
# IMPORTANT: This is NOT a discriminated union. In WASM/Pyodide, we parse requests
# by trying each type in order until one succeeds (see PyodideBridge.put_control_request).
# The order matters because some types have overlapping structures when parsed with
@@ -421,5 +429,7 @@ ControlRequest = Union[
# Requests with no fields (will match any empty object)
StopRequest,
RefreshSecretsRequest,
+ ClearCacheRequest,
+ GetCacheInfoRequest,
ExecuteStaleRequest, # only comes from backend set low priority
]
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 687a34bd8b..d49115f285 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -54,6 +54,8 @@ from marimo._messaging.errors import (
UnknownError,
)
from marimo._messaging.ops import (
+ CacheCleared,
+ CacheInfoFetched,
CellOp,
CompletedRun,
DataColumnPreview,
@@ -127,6 +129,7 @@ from marimo._runtime.reload.autoreload import ModuleReloader
from marimo._runtime.reload.module_watcher import ModuleWatcher
from marimo._runtime.requests import (
AppMetadata,
+ ClearCacheRequest,
CodeCompletionRequest,
ControlRequest,
CreationRequest,
@@ -136,6 +139,7 @@ from marimo._runtime.requests import (
ExecuteStaleRequest,
ExecutionRequest,
FunctionCallRequest,
+ GetCacheInfoRequest,
InstallMissingPackagesRequest,
ListSecretKeysRequest,
PdbRequest,
@@ -532,6 +536,7 @@ class Kernel:
self.datasets_callbacks = DatasetCallbacks(self)
self.packages_callbacks = PackagesCallbacks(self)
self.sql_callbacks = SqlCallbacks(self)
+ self.cache_callbacks = CacheCallbacks(self)
# Apply pythonpath from config at initialization
pythonpath = user_config["runtime"].get("pythonpath")
@@ -2238,6 +2243,11 @@ class Kernel:
handler.register(
RefreshSecretsRequest, self.secrets_callbacks.refresh_secrets
)
+ # Cache
+ handler.register(ClearCacheRequest, self.cache_callbacks.clear_cache)
+ handler.register(
+ GetCacheInfoRequest, self.cache_callbacks.get_cache_info
+ )
return handler
@@ -2858,6 +2868,51 @@ class PackagesCallbacks:
LOGGER.error("Failed to add script metadata to notebook: %s", e)
+class CacheCallbacks:
+ def __init__(self, kernel: Kernel):
+ self._kernel = kernel
+
+ async def clear_cache(self, request: ClearCacheRequest) -> None:
+ del request
+ from marimo._save.cache import CacheContext
+ from marimo._save.loaders import BasePersistenceLoader
+
+ ctx = get_context()
+ saved = 0
+ for obj in ctx.globals.values():
+ if isinstance(obj, CacheContext):
+ if isinstance(obj.loader, BasePersistenceLoader):
+ obj.loader.clear()
+
+ CacheCleared(bytes_freed=saved).broadcast()
+
+ async def get_cache_info(self, request: GetCacheInfoRequest) -> None:
+ del request
+ from marimo._save.cache import CacheContext
+
+ ctx = get_context()
+ total_hits = 0
+ total_misses = 0
+ total_time = 0
+ disk_to_free = -1 # TODO: sum up disk usage
+ disk_total = -1
+
+ for obj in ctx.globals.values():
+ if isinstance(obj, CacheContext):
+ hits, misses, _, _, time = obj.cache_info()
+ total_hits += hits
+ total_misses += misses
+ total_time += time
+ # d2f, dt = obj.loader.disk_usage()
+ CacheInfoFetched(
+ hits=total_hits,
+ misses=total_misses,
+ time=total_time,
+ disk_to_free=disk_to_free,
+ disk_total=disk_total,
+ ).broadcast()
+
+
class RequestHandler:
def __init__(self) -> None:
self._handlers: dict[
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.py
index bec238f570..53bd403d8a 100644
--- a/marimo/_save/cache.py
+++ b/marimo/_save/cache.py
@@ -185,6 +185,7 @@ class Cache:
self,
scope: dict[str, Any],
meta: Optional[dict[MetaKey, Any]] = None,
+ preserve_pointers: bool = True,
) -> None:
"""Loads values from scope, updating the cache."""
for var, lookup in self.contextual_defs():
@@ -227,10 +228,14 @@ class Cache:
# Convert objects to stubs in both defs and meta
memo: dict[int, Any] = {} # Track processed objects to handle cycles
for key, value in self.defs.items():
- self.defs[key] = self._convert_to_stub_if_needed(value, memo)
+ self.defs[key] = self._convert_to_stub_if_needed(
+ value, memo, preserve_pointers
+ )
for key, value in self.meta.items():
- self.meta[key] = self._convert_to_stub_if_needed(value, memo)
+ self.meta[key] = self._convert_to_stub_if_needed(
+ value, memo, preserve_pointers
+ )
def _convert_to_stub_if_needed(
self,
diff --git a/marimo/_server/api/endpoints/cache.py b/marimo/_server/api/endpoints/cache.py
new file mode 100644
index 0000000000..b51b4d9d5e
--- /dev/null
+++ b/marimo/_server/api/endpoints/cache.py
@@ -0,0 +1,71 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from starlette.authentication import requires
+
+from marimo._runtime.requests import (
+ ClearCacheRequest,
+ GetCacheInfoRequest,
+)
+from marimo._server.api.deps import AppState
+from marimo._server.models.models import SuccessResponse
+from marimo._server.router import APIRouter
+from marimo._types.ids import ConsumerId
+
+if TYPE_CHECKING:
+ from starlette.requests import Request
+
+# Router for cache endpoints
+router = APIRouter()
+
+
+@requires("edit")
+async def clear_cache(request: Request) -> SuccessResponse:
+ """
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ClearCacheRequest"
+ responses:
+ 200:
+ description: Clear all caches
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SuccessResponse"
+ """
+ app_state = AppState(request)
+ app_state.require_current_session().put_control_request(
+ ClearCacheRequest(),
+ from_consumer_id=ConsumerId(app_state.require_current_session_id()),
+ )
+ return SuccessResponse(success=True)
+
+
+@requires("edit")
+async def get_cache_info(request: Request) -> SuccessResponse:
+ """
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/GetCacheInfoRequest"
+ responses:
+ 200:
+ description: Get cache statistics
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SuccessResponse"
+ """
+ app_state = AppState(request)
+ app_state.require_current_session().put_control_request(
+ GetCacheInfoRequest(),
+ from_consumer_id=ConsumerId(app_state.require_current_session_id()),
+ )
+ return SuccessResponse(success=True)
diff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.py
index 3fb41cca40..35abfa6119 100644
--- a/marimo/_server/api/router.py
+++ b/marimo/_server/api/router.py
@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
from marimo._server.api.endpoints.ai import router as ai_router
from marimo._server.api.endpoints.assets import router as assets_router
+from marimo._server.api.endpoints.cache import router as cache_router
from marimo._server.api.endpoints.config import router as config_router
from marimo._server.api.endpoints.datasources import (
router as datasources_router,
@@ -53,6 +54,7 @@ def build_routes(base_url: str = "") -> list[BaseRoute]:
app_router.include_router(
secrets_router, prefix="/api/secrets", name="secrets"
)
+ app_router.include_router(cache_router, prefix="/api/cache", name="cache")
app_router.include_router(
documentation_router, prefix="/api/documentation", name="documentation"
)
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 2c2b9afad6..d8a7027d41 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -270,6 +270,44 @@ components:
required: []
title: BedrockConfig
type: object
+ CacheCleared:
+ description: Result of clearing cache.
+ properties:
+ bytes_freed:
+ type: integer
+ op:
+ enum:
+ - cache-cleared
+ required:
+ - op
+ - bytes_freed
+ title: CacheCleared
+ type: object
+ CacheInfoFetched:
+ description: Cache statistics information.
+ properties:
+ disk_to_free:
+ type: integer
+ disk_total:
+ type: integer
+ hits:
+ type: integer
+ misses:
+ type: integer
+ op:
+ enum:
+ - cache-info-fetched
+ time:
+ type: number
+ required:
+ - op
+ - hits
+ - misses
+ - time
+ - disk_to_free
+ - disk_total
+ title: CacheInfoFetched
+ type: object
CellChannel:
description: The channel of a cell's output.
enum:
@@ -511,6 +549,11 @@ components:
- messages
title: ChatRequest
type: object
+ ClearCacheRequest:
+ properties: {}
+ required: []
+ title: ClearCacheRequest
+ type: object
CodeCompletionRequest:
properties:
cellId:
@@ -1571,6 +1614,11 @@ components:
- status
title: FunctionCallResult
type: object
+ GetCacheInfoRequest:
+ properties: {}
+ required: []
+ title: GetCacheInfoRequest
+ type: object
GitHubConfig:
description: "Configuration options for GitHub.\n\n **Keys.**\n\n - `api_key`:\
\ the GitHub API token\n - `base_url`: the base URL for the API"
@@ -1945,6 +1993,8 @@ components:
- $ref: '#/components/schemas/DataSourceConnections'
- $ref: '#/components/schemas/ValidateSQLResult'
- $ref: '#/components/schemas/SecretKeysResult'
+ - $ref: '#/components/schemas/CacheCleared'
+ - $ref: '#/components/schemas/CacheInfoFetched'
- $ref: '#/components/schemas/FocusCell'
- $ref: '#/components/schemas/UpdateCellCodes'
- $ref: '#/components/schemas/UpdateCellIdsRequest'
@@ -1952,6 +2002,8 @@ components:
mapping:
alert: '#/components/schemas/Alert'
banner: '#/components/schemas/Banner'
+ cache-cleared: '#/components/schemas/CacheCleared'
+ cache-info-fetched: '#/components/schemas/CacheInfoFetched'
cell-op: '#/components/schemas/CellOp'
completed-run: '#/components/schemas/CompletedRun'
completion-result: '#/components/schemas/CompletionResult'
@@ -3657,7 +3709,7 @@ components:
type: object
info:
title: marimo API
- version: 0.16.4
+ version: 0.16.5
openapi: 3.1.0
paths:
/@file/{filename_and_length}:
@@ -3754,6 +3806,34 @@ paths:
schema:
$ref: '#/components/schemas/MCPStatusResponse'
description: Get MCP server status
+ /api/cache/clear:
+ post:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ClearCacheRequest'
+ responses:
+ '200':
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SuccessResponse'
+ description: Clear all caches
+ /api/cache/info:
+ post:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GetCacheInfoRequest'
+ responses:
+ '200':
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SuccessResponse'
+ description: Get cache statistics
/api/datasources/preview_column:
post:
requestBody:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index dbf4d4d92f..4817a77e35 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -271,6 +271,84 @@ export interface paths {
patch?: never;
trace?: never;
};
+ "/api/cache/clear": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ requestBody?: {
+ content: {
+ "application/json": components["schemas"]["ClearCacheRequest"];
+ };
+ };
+ responses: {
+ /** @description Clear all caches */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SuccessResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
+ "/api/cache/info": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ requestBody?: {
+ content: {
+ "application/json": components["schemas"]["GetCacheInfoRequest"];
+ };
+ };
+ responses: {
+ /** @description Get cache statistics */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SuccessResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
"/api/datasources/preview_column": {
parameters: {
query?: never;
@@ -2868,6 +2946,28 @@ export interface components {
profile_name?: string;
region_name?: string;
};
+ /**
+ * CacheCleared
+ * @description Result of clearing cache.
+ */
+ CacheCleared: {
+ bytes_freed: number;
+ /** @enum {unknown} */
+ op: "cache-cleared";
+ };
+ /**
+ * CacheInfoFetched
+ * @description Cache statistics information.
+ */
+ CacheInfoFetched: {
+ disk_to_free: number;
+ disk_total: number;
+ hits: number;
+ misses: number;
+ /** @enum {unknown} */
+ op: "cache-info-fetched";
+ time: number;
+ };
/**
* CellChannel
* @description The channel of a cell's output.
@@ -3014,6 +3114,8 @@ export interface components {
/** @default null */
variables?: (string | components["schemas"]["VariableContext"])[] | null;
};
+ /** ClearCacheRequest */
+ ClearCacheRequest: Record<string, any>;
/** CodeCompletionRequest */
CodeCompletionRequest: {
cellId: string;
@@ -3550,6 +3652,8 @@ export interface components {
return_value: unknown;
status: components["schemas"]["HumanReadableStatus"];
};
+ /** GetCacheInfoRequest */
+ GetCacheInfoRequest: Record<string, any>;
/**
* GitHubConfig
* @description Configuration options for GitHub.
@@ -3775,6 +3879,8 @@ export interface components {
| components["schemas"]["DataSourceConnections"]
| components["schemas"]["ValidateSQLResult"]
| components["schemas"]["SecretKeysResult"]
+ | components["schemas"]["CacheCleared"]
+ | components["schemas"]["CacheInfoFetched"]
| components["schemas"]["FocusCell"]
| components["schemas"]["UpdateCellCodes"]
| components["schemas"]["UpdateCellIdsRequest"];
diff --git a/pyproject.toml b/pyproject.toml
index 27955c4654..6dcac6abb2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -547,6 +547,7 @@ performant_table_charts = true
sql_linter = true
sql_mode = true
chat_modes = true
+cache_panel = true
[tool.marimo.display]
dataframes = "rich"