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.

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

import type { Completion } from "@codemirror/autocomplete";
import type { Resource } from "@marimo-team/codemirror-mcp";
import type { FileUIPart } from "ai";
import { Memoize } from "typescript-memoize";
import { Logger } from "@/utils/Logger";
import { MultiMap } from "@/utils/multi-map";
import type { TypedString } from "@/utils/typed";

/**
 * Unique identifier for a context item in the format "type://id"
 * e.g., "variable://my_var", "data://users", "file://config.py"
 */
export type ContextLocatorId = TypedString<"ContextLocatorId">;

function parseContextType(uri: ContextLocatorId): string | undefined {
  const separator = uri.indexOf("://");
  if (separator === -1) {
    return undefined;
  }
  return uri.slice(0, separator);
}

/**
 * Base interface for context items that can be mentioned in AI prompts
 */
export interface AIContextItem extends Resource<Record<string, unknown>> {
  data: Record<string, unknown>;
}

/**
 * Abstract base class for AI context providers with shared implementation
 */
export abstract class AIContextProvider<
  T extends AIContextItem = AIContextItem,
> {
  /** Human-readable title for this context type */
  public abstract readonly title: string;

  /** Prefix used for mentions (e.g., "@" for variables, "#" for files) */
  public abstract readonly mentionPrefix: "@" | "#";

  /** Context type identifier used in ContextLocatorId */
  public abstract readonly contextType: string;

  /** Get all available items of this context type */
  public abstract getItems(): T[];

  /** Format the context for inclusion in AI prompt */
  public abstract formatContext(item: T): string;

  /** Format completion */
  public abstract formatCompletion(item: T): Completion;

  /** Get attachments for context items (optional, async) */
  public async getAttachments(_items: T[]): Promise<FileUIPart[]> {
    // Default implementation returns no attachments
    return [];
  }

  public asURI(id: string): ContextLocatorId {
    return `${this.contextType}://${id}` as ContextLocatorId;
  }

  /** Parse context IDs from input text using the provider's mention prefix */
  public parseContextIds(input: string): ContextLocatorId[] {
    // Match @type://id, e.g., @data://users
    const regex = new RegExp(
      `${this.mentionPrefix}([\\w-]+):\\/\\/([\\w./-]+)`,
      "g",
    );
    const matches = [...input.matchAll(regex)];
    const justURI = (match: string) => match.slice(1);

    const results = matches
      .filter(([, type]) => type === this.contextType)
      .map(([matchString]) => justURI(matchString) as ContextLocatorId);

    return [...new Set(results)];
  }

  /** Create a basic completion object - can be used by subclasses */
  protected createBasicCompletion(
    item: T,
    options?: {
      boost?: number;
      type?: string;
      section?: string;
      detail?: string;
    },
  ): Completion {
    return {
      label: `${this.mentionPrefix}${item.uri.split("://")[1]}`,
      displayLabel: item.name,
      detail: options?.detail || item.description,
      boost: options?.boost || 1,
      type: options?.type || this.contextType,
      apply: `${this.mentionPrefix}${item.uri}`,
      section: options?.section || this.title,
    };
  }
}

/**
 * Registry for managing different AI context providers
 */
export class AIContextRegistry<T extends AIContextItem> {
  // oxlint-disable-next-line typescript/no-explicit-any
  private providers = new Set<AIContextProvider<any>>();

  /**
   * Register a new context provider
   */
  public register<U extends AIContextItem>(
    provider: AIContextProvider<U>,
    // oxlint-disable-next-line typescript/prefer-return-this-type
  ): AIContextRegistry<U | T> {
    this.providers.add(provider);
    return this;
  }

  /**
   * Get all registered providers
   */
  public getProviders(): Set<AIContextProvider<T>> {
    return this.providers;
  }

  /**
   * Get a specific provider by type
   */
  public getProvider(type: string): AIContextProvider | undefined {
    return [...this.providers].find(
      (provider) => provider.contextType === type,
    );
  }

  @Memoize()
  public getAllItems(): T[] {
    return [...this.providers].flatMap((provider) => provider.getItems());
  }

  /**
   * Parse context IDs from input across all providers
   */
  public parseAllContextIds(input: string): ContextLocatorId[] {
    return [...this.providers].flatMap((provider) =>
      provider.parseContextIds(input),
    );
  }

  private findProviderForUri(
    uri: ContextLocatorId,
  ): AIContextProvider | undefined {
    const type = parseContextType(uri);
    if (!type) {
      return undefined;
    }
    return [...this.providers].find(
      (provider) =>
        provider.contextType === type &&
        provider.getItems().some((item) => item.uri === uri),
    );
  }

  /**
   * Resolve only the requested context items, querying each matching provider
   */
  public resolveItems(contextIds: ContextLocatorId[]): T[] {
    if (contextIds.length === 0) {
      return [];
    }

    const idsByType = new MultiMap<string, ContextLocatorId>();
    for (const contextId of contextIds) {
      const type = parseContextType(contextId);
      if (type) {
        idsByType.add(type, contextId);
      }
    }

    const itemsById = new Map<ContextLocatorId, T>();
    for (const [type, ids] of idsByType.entries()) {
      const providers = [...this.providers].filter(
        (provider) => provider.contextType === type,
      );
      for (const provider of providers) {
        const itemsByUri = new Map<ContextLocatorId, T>(
          provider
            .getItems()
            .map((item) => [item.uri as ContextLocatorId, item as T]),
        );
        for (const id of ids) {
          const item = itemsByUri.get(id);
          if (item) {
            itemsById.set(id, item);
          }
        }
      }
    }

    // Preserve the order in which the ids were requested, so formatted context
    // matches the order the user mentioned them in the prompt.
    const results: T[] = [];
    for (const contextId of contextIds) {
      const item = itemsById.get(contextId);
      if (item) {
        results.push(item);
      }
    }
    return results;
  }

  /**
   * Get context information for mentioned items
   */
  public getContextInfo(contextIds: ContextLocatorId[]): T[] {
    return this.resolveItems(contextIds);
  }

  /**
   * Format context for AI prompt inclusion
   */
  public formatContextForAI(contextIds: ContextLocatorId[]): string {
    const contextInfo = this.resolveItems(contextIds);

    if (contextInfo.length === 0) {
      return "";
    }

    return contextInfo
      .map((item) => {
        const provider = this.findProviderForUri(item.uri as ContextLocatorId);
        return provider?.formatContext(item) || "";
      })
      .join("\n\n");
  }

  /**
   * Get attachments for mentioned items
   */
  public async getAttachmentsForContext(
    contextIds: ContextLocatorId[],
  ): Promise<FileUIPart[]> {
    const contextInfo = this.resolveItems(contextIds);

    if (contextInfo.length === 0) {
      return [];
    }

    const itemsByProvider = new MultiMap<AIContextProvider, T>();
    for (const item of contextInfo) {
      const provider = this.findProviderForUri(item.uri as ContextLocatorId);
      if (provider) {
        itemsByProvider.add(provider, item);
      }
    }

    const attachmentPromises = [...itemsByProvider.entries()].map(
      async ([provider, items]) => {
        try {
          return await provider.getAttachments(items);
        } catch (error) {
          Logger.error("Error getting attachments from provider", error);
          return [];
        }
      },
    );

    const attachmentResults = await Promise.all(attachmentPromises);
    const results = attachmentResults.flat();

    // Print attachments to the console with a rich image preview
    if (import.meta.env.DEV) {
      for (const attachment of results) {
        // If it's an image, print a rich preview
        if (
          /^data:image\/(png|jpeg|jpg|gif|svg\+xml);base64,/.test(
            attachment.url,
          )
        ) {
          Logger.debug(
            "%c ",
            `font-size:1px;padding:140px 180px;background:url('${attachment.url}') no-repeat;background-size:contain;`,
          );
        }
      }
    }

    return results;
  }
}