@jupyterlite/ai 0.8.1 → 0.9.0-a1

package/lib/tokens.d.ts

@@ -1,145 +1,226 @@
-import { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import { ReadonlyPartialJSONObject, Token } from '@lumino/coreutils';
+import { Token } from '@lumino/coreutils';
 import { ISignal } from '@lumino/signaling';
-import { JSONSchema7 } from 'json-schema';
-import { IBaseCompleter } from './base-completer';
-import { AIChatModel, AICompleter } from './types/ai-model';
-export declare const PLUGIN_IDS: {
-    chat: string;
-    chatCommandRegistry: string;
-    completer: string;
-    providerRegistry: string;
-    settingsConnector: string;
-    systemPrompts: string;
-};
-export type ModelRole = 'chat' | 'completer';
-export interface IDict<T = any> {
-    [key: string]: T;
-}
-export interface IType<T> {
-    new (...args: any[]): T;
+import { FunctionTool } from '@openai/agents';
+import { LanguageModel } from 'ai';
+import { AgentManager } from './agent';
+import type { AISettingsModel } from './models/settings-model';
+import type { IModelOptions } from './providers/models';
+/**
+ * Type definition for a tool
+ */
+export type ITool = FunctionTool<any, any, any>;
+/**
+ * Interface for token usage statistics from AI model interactions
+ */
+export interface ITokenUsage {
+    /**
+     * Number of input tokens consumed (prompt tokens)
+     */
+    inputTokens: number;
+    /**
+     * Number of output tokens generated (completion tokens)
+     */
+    outputTokens: number;
 }
 /**
- * The provider interface.
+ * Interface for a named tool (tool with a name identifier)
  */
-export interface IAIProvider {
+export interface INamedTool {
     /**
-     * The name of the provider.
+     * The unique name of the tool
      */
     name: string;
     /**
-     * The chat model class to use.
+     * The tool instance
      */
-    chat?: IType<BaseChatModel>;
+    tool: ITool;
+}
+/**
+ * The tool registry interface for managing AI tools
+ */
+export interface IToolRegistry {
     /**
-     * The completer class to use.
+     * The registered tools as a record (name -> tool mapping).
      */
-    completer?: IType<IBaseCompleter>;
+    readonly tools: Record<string, ITool>;
     /**
-     * the settings schema for the provider.
+     * The registered named tools array.
      */
-    settingsSchema?: any;
+    readonly namedTools: INamedTool[];
     /**
-     * The instructions to be displayed in the settings, as helper to use the provider.
-     * A markdown renderer is used to render the instructions.
+     * A signal triggered when the tools have changed.
      */
-    instructions?: string;
+    readonly toolsChanged: ISignal<IToolRegistry, void>;
     /**
-     * A function that extract the error message from the provider API error.
-     * Default to `(error) => error.message`.
+     * Add a new tool to the registry.
      */
-    errorMessage?: (error: any) => string;
+    add(name: string, tool: ITool): void;
     /**
-     * Compatibility check function, to determine if the provider is compatible with the
-     * current environment.
+     * Get a tool for a given name.
+     * Return null if the name is not provided or if there is no registered tool with the
+     * given name.
      */
-    compatibilityCheck?: () => Promise<string | null>;
+    get(name: string | null): ITool | null;
     /**
-     * Whether to expose or not the chat model.
-     *
-     * ### CAUTION
-     * This flag will expose the whole chat model API, which may contain private keys.
-     * Be sure to use it with a model that does not expose sensitive information in the
-     * API.
+     * Remove a tool from the registry by name.
      */
-    exposeChatModel?: boolean;
+    remove(name: string): boolean;
 }
 /**
- * The provider registry interface.
+ * The tool registry token.
  */
-export interface IAIProviderRegistry {
+export declare const IToolRegistry: Token<IToolRegistry>;
+/**
+ * Token for the chat provider registry.
+ */
+export declare const IChatProviderRegistry: Token<IChatProviderRegistry>;
+/**
+ * Token for the completion provider registry.
+ */
+export declare const ICompletionProviderRegistry: Token<ICompletionProviderRegistry>;
+/**
+ * Interface for a provider factory function that creates chat models
+ */
+export interface IChatProviderFactory {
+    (options: IModelOptions): any;
+}
+/**
+ * Interface for a provider factory function that creates completion models
+ */
+export interface ICompletionProviderFactory {
+    (options: IModelOptions): LanguageModel;
+}
+/**
+ * Base information about a registered provider
+ */
+export interface IBaseProviderInfo {
     /**
-     * Get the list of provider names.
+     * Unique identifier for the provider
      */
-    readonly providers: string[];
+    id: string;
     /**
-     * Add a new provider.
+     * Display name for the provider
      */
-    add(provider: IAIProvider): void;
+    name: string;
     /**
-     * Get the current provider name.
+     * Whether this provider requires an API key
      */
-    currentName(role: ModelRole): string;
+    requiresApiKey: boolean;
     /**
-     * Get the current completer of the completion provider.
+     * Default model names for this provider
      */
-    currentCompleter: AICompleter | null;
+    defaultModels: string[];
     /**
-     * Getter/setter for the completer system prompt.
+     * Whether this provider supports custom base URLs
      */
-    completerSystemPrompt: string;
+    supportsBaseURL?: boolean;
     /**
-     * Get the current llm chat model.
+     * Whether this provider supports custom headers
      */
-    currentChatModel: AIChatModel | null;
+    supportsHeaders?: boolean;
     /**
-     * Getter/setter for the chat system prompt.
+     * Whether this provider supports tool calling
      */
-    chatSystemPrompt: string;
+    supportsToolCalling?: boolean;
     /**
-     * Get the settings schema of a given provider.
+     * Additional provider-specific configuration schema
      */
-    getSettingsSchema(provider: string): JSONSchema7;
+    customSettings?: Record<string, any>;
+}
+/**
+ * Information about a chat provider
+ */
+export interface IChatProviderInfo extends IBaseProviderInfo {
     /**
-     * Get the instructions of a given provider.
+     * Factory function for creating chat models
      */
-    getInstructions(provider: string): string | undefined;
+    factory: IChatProviderFactory;
+}
+/**
+ * Information about a completion provider
+ */
+export interface ICompletionProviderInfo extends IBaseProviderInfo {
+    /**
+     * Factory function for creating completion models
+     */
+    factory: ICompletionProviderFactory;
+}
+/**
+ * Registry for chat AI providers
+ */
+export interface IChatProviderRegistry {
+    /**
+     * The registered providers as a record (id -> info mapping).
+     */
+    readonly providers: Record<string, IChatProviderInfo>;
+    /**
+     * A signal triggered when providers have changed.
+     */
+    readonly providersChanged: ISignal<IChatProviderRegistry, void>;
+    /**
+     * Register a new chat provider.
+     */
+    registerProvider(info: IChatProviderInfo): void;
+    /**
+     * Unregister a chat provider.
+     */
+    unregisterProvider(id: string): boolean;
+    /**
+     * Get provider info by id.
+     */
+    getProviderInfo(id: string): IChatProviderInfo | null;
+    /**
+     * Create a chat model instance for the given provider.
+     */
+    createChatModel(id: string, options: IModelOptions): any | null;
+    /**
+     * Get all available provider IDs.
+     */
+    getAvailableProviders(): string[];
+}
+/**
+ * Registry for completion providers
+ */
+export interface ICompletionProviderRegistry {
     /**
-     * Get the compatibility check function of a given provider.
+     * The registered providers as a record (id -> info mapping).
      */
-    getCompatibilityCheck(provider: string): (() => Promise<string | null>) | undefined;
+    readonly providers: Record<string, ICompletionProviderInfo>;
     /**
-     * Format an error message from the current provider.
+     * A signal triggered when providers have changed.
      */
-    formatErrorMessage(error: any): string;
+    readonly providersChanged: ISignal<ICompletionProviderRegistry, void>;
     /**
-     * Set the completer provider.
-     * Creates the provider if the name has changed, otherwise only updates its config.
-     *
-     * @param options - An object with the name and the settings of the provider to use.
+     * Register a new completion provider.
      */
-    setCompleterProvider(settings: ReadonlyPartialJSONObject): void;
+    registerProvider(info: ICompletionProviderInfo): void;
     /**
-     * Set the chat provider.
-     * Creates the provider if the name has changed, otherwise only updates its config.
-     *
-     * @param options - An object with the name and the settings of the provider to use.
+     * Unregister a completion provider.
      */
-    setChatProvider(settings: ReadonlyPartialJSONObject): void;
+    unregisterProvider(id: string): boolean;
     /**
-     * A signal emitting when the provider or its settings has changed.
+     * Get provider info by id.
      */
-    readonly providerChanged: ISignal<IAIProviderRegistry, ModelRole>;
+    getProviderInfo(id: string): ICompletionProviderInfo | null;
     /**
-     * Get the current chat error;
+     * Create a completion model instance for the given provider.
      */
-    readonly chatError: string;
+    createCompletionModel(id: string, options: IModelOptions): LanguageModel | null;
     /**
-     * get the current completer error.
+     * Get all available provider IDs.
      */
-    readonly completerError: string;
+    getAvailableProviders(): string[];
 }
 /**
- * The provider registry token.
+ * Token for the AI settings model.
+ */
+export declare const IAISettingsModel: Token<AISettingsModel>;
+/**
+ * Token for the agent manager.
+ */
+export declare const IAgentManager: Token<AgentManager>;
+/**
+ * The string that replaces a secret key in settings.
  */
-export declare const IAIProviderRegistry: Token<IAIProviderRegistry>;
+export declare const SECRETS_NAMESPACE = "@jupyterlite/ai:providers";
+export declare const SECRETS_REPLACEMENT = "***";

package/lib/tokens.js

@@ -1,13 +1,26 @@
 import { Token } from '@lumino/coreutils';
-export const PLUGIN_IDS = {
-    chat: '@jupyterlite/ai:chat',
-    chatCommandRegistry: '@jupyterlite/ai:autocompletion-registry',
-    completer: '@jupyterlite/ai:completer',
-    providerRegistry: '@jupyterlite/ai:provider-registry',
-    settingsConnector: '@jupyterlite/ai:settings-connector',
-    systemPrompts: '@jupyterlite/ai:system-prompts'
-};
-/**
- * The provider registry token.
- */
-export const IAIProviderRegistry = new Token('@jupyterlite/ai:provider-registry', 'Provider for chat and completion LLM provider');
+/**
+ * The tool registry token.
+ */
+export const IToolRegistry = new Token('@jupyterlite/ai:tool-registry', 'Tool registry for AI agent functionality');
+/**
+ * Token for the chat provider registry.
+ */
+export const IChatProviderRegistry = new Token('@jupyterlite/ai:chat-provider-registry', 'Registry for chat AI providers');
+/**
+ * Token for the completion provider registry.
+ */
+export const ICompletionProviderRegistry = new Token('@jupyterlite/ai:completion-provider-registry', 'Registry for completion providers');
+/**
+ * Token for the AI settings model.
+ */
+export const IAISettingsModel = new Token('@jupyterlite/ai:IAISettingsModel');
+/**
+ * Token for the agent manager.
+ */
+export const IAgentManager = new Token('@jupyterlite/ai:agent-manager');
+/**
+ * The string that replaces a secret key in settings.
+ */
+export const SECRETS_NAMESPACE = '@jupyterlite/ai:providers';
+export const SECRETS_REPLACEMENT = '***';

package/lib/tools/commands.d.ts

@@ -0,0 +1,11 @@
+import { CommandRegistry } from '@lumino/commands';
+import { ITool } from '../tokens';
+import { AISettingsModel } from '../models/settings-model';
+/**
+ * Create a tool to discover all available commands and their metadata
+ */
+export declare function createDiscoverCommandsTool(commands: CommandRegistry): ITool;
+/**
+ * Create a tool to execute a specific JupyterLab command
+ */
+export declare function createExecuteCommandTool(commands: CommandRegistry, settingsModel: AISettingsModel): ITool;

package/lib/tools/commands.js

@@ -0,0 +1,126 @@
+import { tool } from '@openai/agents';
+import { z } from 'zod';
+/**
+ * Create a tool to discover all available commands and their metadata
+ */
+export function createDiscoverCommandsTool(commands) {
+    return tool({
+        name: 'discover_commands',
+        description: 'Discover all available JupyterLab commands with their metadata, arguments, and descriptions',
+        parameters: z.object({
+            // currently unused, but could be used to filter commands by a search term
+            query: z
+                .string()
+                .optional()
+                .nullable()
+                .describe('Optional search query to filter commands')
+        }),
+        execute: async () => {
+            try {
+                const commandList = [];
+                // Get all command IDs
+                const commandIds = commands.listCommands();
+                for (const id of commandIds) {
+                    try {
+                        // Get command metadata using various CommandRegistry methods
+                        const description = await commands.describedBy(id);
+                        const label = commands.label(id);
+                        const caption = commands.caption(id);
+                        const usage = commands.usage(id);
+                        commandList.push({
+                            id,
+                            label: label || undefined,
+                            caption: caption || undefined,
+                            description: usage || undefined,
+                            args: description?.args || undefined
+                        });
+                    }
+                    catch (error) {
+                        // Some commands might not have descriptions, skip them
+                        commandList.push({ id });
+                    }
+                }
+                return {
+                    success: true,
+                    commandCount: commandList.length,
+                    commands: commandList
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to discover commands: ${error instanceof Error ? error.message : String(error)}`
+                };
+            }
+        }
+    });
+}
+/**
+ * Create a tool to execute a specific JupyterLab command
+ */
+export function createExecuteCommandTool(commands, settingsModel) {
+    return tool({
+        name: 'execute_command',
+        description: 'Execute a specific JupyterLab command with optional arguments',
+        parameters: z.object({
+            commandId: z.string().describe('The ID of the command to execute'),
+            args: z
+                .any()
+                .optional()
+                .describe('Optional arguments to pass to the command')
+        }),
+        needsApproval: async (_context, { commandId }) => {
+            // Use configurable list of commands requiring approval
+            const commandsRequiringApproval = settingsModel.config.commandsRequiringApproval;
+            return commandsRequiringApproval.some(cmd => commandId.includes(cmd) || cmd.includes(commandId));
+        },
+        execute: async (input) => {
+            const { commandId, args } = input;
+            // Check if command exists
+            if (!commands.hasCommand(commandId)) {
+                return {
+                    success: false,
+                    error: `Command '${commandId}' does not exist. Use 'discover_commands' to see available commands.`
+                };
+            }
+            try {
+                // Execute the command
+                const result = await commands.execute(commandId, args);
+                // Handle Widget objects specially (including subclasses like DocumentWidget)
+                let serializedResult;
+                if (result &&
+                    typeof result === 'object' &&
+                    (result.constructor?.name?.includes('Widget') || result.id)) {
+                    serializedResult = {
+                        type: result.constructor?.name || 'Widget',
+                        id: result.id,
+                        title: result.title?.label || result.title,
+                        className: result.className
+                    };
+                }
+                else {
+                    // For other objects, try JSON serialization with fallback
+                    try {
+                        serializedResult = JSON.parse(JSON.stringify(result));
+                    }
+                    catch {
+                        serializedResult = result
+                            ? '[Complex object - cannot serialize]'
+                            : 'Command executed successfully';
+                    }
+                }
+                return {
+                    success: true,
+                    commandId,
+                    result: serializedResult
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to execute command '${commandId}': ${error instanceof Error ? error.message : String(error)}`
+                };
+            }
+        }
+    });
+}

package/lib/tools/file.d.ts

@@ -0,0 +1,27 @@
+import { CommandRegistry } from '@lumino/commands';
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ITool } from '../tokens';
+/**
+ * Create a tool for creating new files of various types
+ */
+export declare function createNewFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for opening files
+ */
+export declare function createOpenFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for deleting files
+ */
+export declare function createDeleteFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for renaming files
+ */
+export declare function createRenameFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for copying files
+ */
+export declare function createCopyFileTool(docManager: IDocumentManager): ITool;
+/**
+ * Create a tool for navigating to directories in the file browser
+ */
+export declare function createNavigateToDirectoryTool(commands: CommandRegistry): ITool;