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.

3.4 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

import { z } from "zod";
import type { CreateCell } from "@/core/cells/actions";
import type { CellId } from "@/core/cells/ids";
import type { JotaiStore } from "@/core/state/jotai";
import type { Edit } from "../staged-cells";
import type { CopilotMode } from "./registry";

/**
 * Status value for tool responses, mirroring status value in marimo/_ai/_tools/types.py
 */
export type StatusValue = "success" | "error" | "warning";

/**
 * Structured error for tool execution failures.
 * Mirrors the ToolExecutionError dataclass from marimo/_ai/_tools/utils/exceptions.py
 *
 * @example
 * throw new ToolExecutionError(
 *   "Failed to fetch data",
 *   {
 *     code: "FETCH_ERROR",
 *     isRetryable: true,
 *     suggestedFix: "Check your network connection",
 *   }
 * );
 */
export class ToolExecutionError extends Error {
  public readonly code: string;
  public readonly isRetryable: boolean;
  public readonly suggestedFix?: string;
  public readonly meta?: Record<string, unknown>;

  public constructor(
    message: string,
    {
      code = "TOOL_ERROR",
      isRetryable = false,
      suggestedFix,
      meta,
    }: {
      code?: string;
      isRetryable?: boolean;
      suggestedFix?: string;
      meta?: Record<string, unknown>;
    } = {},
  ) {
    super(message);
    this.name = "ToolExecutionError";
    this.code = code;
    this.isRetryable = isRetryable;
    this.suggestedFix = suggestedFix;
    this.meta = meta;
  }

  public toStructuredString(): string {
    const stringError = JSON.stringify({
      message: this.message,
      code: this.code,
      is_retryable: this.isRetryable,
      ...(this.suggestedFix && { suggested_fix: this.suggestedFix }),
      ...(this.meta && { meta: this.meta }),
    });
    return `Error invoking tool ${this.name}: ${stringError}`;
  }
}

/**
 * Base interface for tool output responses.
 * Mirrors the SuccessResult dataclass from marimo/_ai/_tools/types.py
 *
 * Tool outputs should extend this interface to include standardized
 * metadata like next_steps, messages, and status information.
 */
export interface ToolOutputBase {
  status?: StatusValue;
  auth_required?: boolean;
  next_steps?: string[];
  action_url?: string;
  message?: string;
  meta?: Record<string, unknown>;
}

/**
 * Base Zod schema for tool outputs.
 *
 * Tool output schemas should extend this using .extend() to add their specific fields.
 */
export const toolOutputBaseSchema = z.object({
  status: z.enum(["success", "error", "warning"]).optional(),
  auth_required: z.boolean().optional(),
  next_steps: z.array(z.string()).optional(),
  action_url: z.string().optional(),
  message: z.string().optional(),
  meta: z.record(z.string(), z.unknown()).optional(),
});

export interface ToolDescription {
  baseDescription: string;
  whenToUse?: string[];
  avoidIf?: string[];
  prerequisites?: string[];
  sideEffects?: string[];
  additionalInfo?: string;
}

/** Utility functions for tools to interact with the notebook */
export interface ToolNotebookContext {
  store: JotaiStore;
  addStagedCell: (payload: { cellId: CellId; edit: Edit }) => void;
  createCell: CreateCell;
}

export interface AiTool<TIn, TOut> {
  name: string;
  description: ToolDescription;
  schema: z.ZodType<TIn>;
  outputSchema: z.ZodType<TOut>;
  mode: CopilotMode[];
  handler: (
    args: TIn,
    toolContext: ToolNotebookContext,
  ) => TOut | Promise<TOut>;
}