@jupyterlite/ai 0.9.0 → 0.10.0

package/README.md

@@ -1,9 +1,10 @@
 # jupyterlite-ai
 
 [![Github Actions Status](https://github.com/jupyterlite/ai/workflows/Build/badge.svg)](https://github.com/jupyterlite/ai/actions/workflows/build.yml)
+[![Documentation Status](https://readthedocs.org/projects/jupyterlite-ai/badge/?version=latest)](https://jupyterlite-ai.readthedocs.io/en/latest/?badge=latest)
 [![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://jupyterlite.github.io/ai/lab/index.html)
 
-AI code completions and chat for JupyterLab, Notebook 7 and JupyterLite ✨
+AI code completions and chat for JupyterLab, Notebook 7 and JupyterLite.
 
 [a screencast showing the Jupyterlite AI extension in JupyterLite](https://github.com/user-attachments/assets/e33d7d84-53ca-4835-a034-b6757476c98b)
 
@@ -11,14 +12,12 @@ AI code completions and chat for JupyterLab, Notebook 7 and JupyterLite ✨
 
 - JupyterLab >= 4.4.0 or Notebook >= 7.4.0
 
-## ✨ Try it in your browser ✨
+## Try it in your browser
 
 You can try the extension in your browser using JupyterLite:
 
 [![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://jupyterlite.github.io/ai/lab/index.html)
 
-See the [Usage](#usage) section below for more information on how to provide your API key.
-
 ## Install
 
 To install the extension, execute:
@@ -33,217 +32,9 @@ To install requirements (JupyterLab, JupyterLite and Notebook):
 pip install jupyterlite-ai[jupyter]
 ```
 
-## Usage
-
-> [!NOTE]
-> This documentation applies to the upcoming **0.9.0** release.
-> For the latest stable version, please refer to the [0.8.x branch](https://github.com/jupyterlite/ai/tree/0.8.x).
-
-AI providers typically require using an API key to access their models.
-
-The process is different for each provider, so you may refer to their documentation to learn how to generate new API keys.
-
-### Using a provider with an API key (e.g. Anthropic, MistralAI, OpenAI)
-
-1. Open the AI settings and
-2. Click on "Add a new provider"
-3. Enter the details for the provider
-4. In the chat, select the new provider
-
-![screenshot showing the dialog to add a new provider](https://github.com/user-attachments/assets/823c71c6-5807-44c8-80b6-2e59379a65d5)
-
-### Using a generic OpenAI-compatible provider
-
-The Generic provider allows you to connect to any OpenAI-compatible API endpoint, including local servers like Ollama and LiteLLM.
-
-1. In JupyterLab, open the AI settings panel and go to the **Providers** section
-2. Click on "Add a new provider"
-3. Select the **Generic (OpenAI-compatible)** provider
-4. Configure the following settings:
-   - **Base URL**: The base URL of your API endpoint (suggestions are provided for common local servers)
-   - **Model**: The model name to use
-   - **API Key**: Your API key (if required by the provider)
-
-### Using Ollama
-
-[Ollama](https://ollama.com/) allows you to run open-weight LLMs locally on your machine.
-
-#### Setting up Ollama
-
-1. Install Ollama following the instructions at <https://ollama.com/download>
-2. Pull a model, for example:
-
-```bash
-ollama pull llama3.2
-```
-
-3. Start the Ollama server (it typically runs on `http://localhost:11434`)
-
-#### Configuring `jupyterlite-ai` to use Ollama
-
-1. In JupyterLab, open the AI settings panel and go to the **Providers** section
-2. Click on "Add a new provider"
-3. Select the **Generic (OpenAI-compatible)** provider
-4. Configure the following settings:
-   - **Base URL**: Select `http://localhost:11434/v1` from the suggestions (or enter manually)
-   - **Model**: The model name you pulled (e.g., `llama3.2`)
-   - **API Key**: Leave empty (not required for Ollama)
-
-### Using LiteLLM Proxy
-
-[LiteLLM Proxy](https://docs.litellm.ai/docs/simple_proxy) is an OpenAI-compatible proxy server that allows you to call 100+ LLMs through a unified interface.
-
-Using LiteLLM Proxy with jupyterlite-ai provides flexibility to switch between different AI providers (OpenAI, Anthropic, Google, Azure, local models, etc.) without changing your JupyterLite configuration. It's particularly useful for enterprise deployments where the proxy can be hosted within private infrastructure to manage external API calls and keep API keys server-side.
-
-#### Setting up LiteLLM Proxy
-
-1. Install LiteLLM:
-
-Follow the instructions at <https://docs.litellm.ai/docs/simple_proxy>.
-
-2. Create a `litellm_config.yaml` file with your model configuration:
-
-```yaml
-model_list:
-  - model_name: gpt-5
-    litellm_params:
-      model: gpt-5
-      api_key: os.environ/OPENAI_API_KEY
-
-  - model_name: claude-sonnet
-    litellm_params:
-      model: claude-sonnet-4-5-20250929
-      api_key: os.environ/ANTHROPIC_API_KEY
-```
-
-3. Start the proxy server, for example:
-
-```bash
-litellm --config litellm_config.yaml
-```
-
-The proxy will start on `http://0.0.0.0:4000` by default.
-
-#### Configuring `jupyterlite-ai` to use LiteLLM Proxy
-
-Configure the [Generic provider (OpenAI-compatible)](#using-a-generic-openai-compatible-provider) with the following settings:
-
-- **Base URL**: `http://0.0.0.0:4000` (or your proxy server URL)
-- **Model**: The model name from your `litellm_config.yaml` (e.g., `gpt-5`, `claude-sonnet`)
-- **API Key (optional)**: If the LiteLLM Proxy server requires an API key, provide it here.
-
-> [!IMPORTANT]
-> The API key must be configured on the LiteLLM Proxy server (in the `litellm_config.yaml` file). Providing an API key via the AI provider settings UI will not have any effect, as the proxy server handles authentication with the upstream AI providers.
-
-> [!NOTE]
-> For more information about LiteLLM Proxy configuration, see the [LiteLLM documentation](https://docs.litellm.ai/docs/simple_proxy).
-
-## Custom Providers
-
-`jupyterlite-ai` supports custom AI providers through its provider registry system. Third-party providers can be registered programmatically in a JupyterLab extension.
-
-Providers are based on the [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction), which provides a unified interface for working with different AI models.
-
-### Registering a Custom Provider
-
-#### Example: Registering a custom OpenAI-compatible provider
-
-```typescript
-import {
-  JupyterFrontEnd,
-  JupyterFrontEndPlugin
-} from '@jupyterlab/application';
-import { IProviderRegistry } from '@jupyterlite/ai';
-import { createOpenAI } from '@ai-sdk/openai';
-
-const plugin: JupyterFrontEndPlugin<void> = {
-  id: 'my-extension:custom-provider',
-  autoStart: true,
-  requires: [IProviderRegistry],
-  activate: (app: JupyterFrontEnd, registry: IProviderRegistry) => {
-    const providerInfo = {
-      id: 'my-custom-provider',
-      name: 'My Custom Provider',
-      apiKeyRequirement: 'required' as const,
-      defaultModels: ['my-model'],
-      supportsBaseURL: true,
-      factory: (options: {
-        apiKey: string;
-        baseURL?: string;
-        model?: string;
-      }) => {
-        const provider = createOpenAI({
-          apiKey: options.apiKey,
-          baseURL: options.baseURL || 'https://api.example.com/v1'
-        });
-        return provider(options.model || 'my-model');
-      }
-    };
-
-    registry.registerProvider(providerInfo);
-  }
-};
-```
-
-The provider configuration object requires the following properties:
-
-- `id`: Unique identifier for the provider
-- `name`: Display name shown in the settings UI
-- `apiKeyRequirement`: Whether an API key is `'required'`, `'optional'`, or `'none'`
-- `defaultModels`: Array of model names to show in the settings
-- `supportsBaseURL`: Whether the provider supports a custom base URL
-- `factory`: Function that creates and returns a language model (the registry automatically wraps it for chat usage)
-
-#### Example: Using a custom fetch function
-
-You can provide a custom `fetch` function to the provider, which is useful for adding custom headers, handling authentication, or routing requests through a proxy:
-
-```typescript
-factory: (options: { apiKey: string; baseURL?: string; model?: string }) => {
-  const provider = createOpenAI({
-    apiKey: options.apiKey,
-    baseURL: options.baseURL || 'https://api.example.com/v1',
-    fetch: async (url, init) => {
-      // Custom fetch implementation
-      const modifiedInit = {
-        ...init,
-        headers: {
-          ...init?.headers,
-          'X-Custom-Header': 'custom-value'
-        }
-      };
-      return fetch(url, modifiedInit);
-    }
-  });
-  return provider(options.model || 'my-model');
-};
-```
-
-## API key management
-
-To avoid storing the API keys in the settings, `jupyterlite-ai` uses [jupyter-secrets-manager](https://github.com/jupyterlab-contrib/jupyter-secrets-manager) by default.
-
-The secrets manager get the API keys from a connector in a secure way.\
-The default connector of the secrets manager is _in memory_, which means that **the API keys are reset when reloading the page**.
-
-To prevent the keys from being reset on reload, there are two options:
-
-1. use a connector that fetches the keys on a remote server (using secure rest API, or web socket)
-
-This is the recommended method, as it ensures the security of the keys and makes them accessible only to logged-in users. \
-But it requires some frontend and backend deployments:
-
-- a server that can store and send the keys on demand
-- a way to get authenticated to the server
-- a frontend extension providing the connector, able to connect to the server side
-
-2. disable the use of the secrets manager from the AI settings panel
+## Documentation
 
-> [!WARNING]
-> The API keys will be stored in plain text using the settings system of Jupyterlab
->
-> - using Jupyterlab, the settings are stored in a [directory](https://jupyterlab.readthedocs.io/en/stable/user/directories.html#jupyterlab-user-settings-directory) on the server
-> - using Jupyterlite, the settings are stored in the [browser](https://jupyterlite.readthedocs.io/en/latest/howto/configure/storage.html#configure-the-browser-storage)
+For detailed usage instructions, including how to configure AI providers, see the [documentation](https://jupyterlite-ai.readthedocs.io/).
 
 ## Uninstall
 

package/lib/agent.d.ts

@@ -1,9 +1,10 @@
 import { ISignal } from '@lumino/signaling';
+import { type Tool } from 'ai';
 import { ISecretsManager } from 'jupyter-secrets-manager';
-import { BrowserMCPServerStreamableHttp } from './mcp/browser';
 import { AISettingsModel } from './models/settings-model';
 import type { IProviderRegistry } from './tokens';
 import { ITool, IToolRegistry, ITokenUsage } from './tokens';
+type ToolMap = Record<string, Tool>;
 export declare namespace AgentManagerFactory {
     interface IOptions {
         /**
@@ -33,15 +34,19 @@ export declare class AgentManagerFactory {
      * @returns True if the server is connected, false otherwise
      */
     isMCPServerConnected(serverName: string): boolean;
+    /**
+     * Gets the MCP tools from connected servers
+     */
+    getMCPTools(): Promise<ToolMap>;
     /**
      * Handles settings changes and reinitializes the agent.
      */
     private _onSettingsChanged;
     /**
-     * Initializes MCP (Model Context Protocol) servers based on current settings.
-     * Closes existing servers and connects to enabled servers from configuration.
+     * Initializes MCP (Model Context Protocol) clients based on current settings.
+     * Closes existing clients and connects to enabled servers from configuration.
      */
-    private _initializeMCPServers;
+    private _initializeMCPClients;
     /**
      * Initializes the AI agent with current settings and tools.
      * Sets up the agent with model configuration, tools, and MCP servers.
@@ -50,7 +55,7 @@ export declare class AgentManagerFactory {
     private _agentManagers;
     private _settingsModel;
     private _secretsManager?;
-    private _mcpServers;
+    private _mcpClients;
     private _mcpConnectionChanged;
     private _isInitializing;
 }
@@ -81,19 +86,15 @@ export interface IAgentEventTypeMap {
         output: string;
         isError: boolean;
     };
-    tool_approval_required: {
-        interruptionId: string;
+    tool_approval_request: {
+        approvalId: string;
+        toolCallId: string;
         toolName: string;
-        toolInput: string;
-        callId?: string;
+        args: unknown;
     };
-    grouped_approval_required: {
-        groupId: string;
-        approvals: Array<{
-            interruptionId: string;
-            toolName: string;
-            toolInput: string;
-        }>;
+    tool_approval_resolved: {
+        approvalId: string;
+        approved: boolean;
     };
     error: {
         error: Error;
@@ -138,7 +139,7 @@ export interface IAgentManagerOptions {
 /**
  * Manages the AI agent lifecycle and execution loop.
  * Provides agent initialization, tool management, MCP server integration,
- * and handles the complete agent execution cycle including tool approvals.
+ * and handles the complete agent execution cycle.
  * Emits events for UI updates instead of directly manipulating the chat interface.
  */
 export declare class AgentManager {
@@ -174,10 +175,10 @@ export declare class AgentManager {
      */
     setSelectedTools(toolNames: string[]): void;
     /**
-     * Gets the currently selected tools as OpenAI agents tools.
-     * @returns Array of selected tools formatted for OpenAI agents
+     * Gets the currently selected tools as a record.
+     * @returns Record of selected tools
      */
-    get selectedAgentTools(): ITool[];
+    get selectedAgentTools(): Record<string, ITool>;
     /**
      * Checks if the current configuration is valid for agent operations.
      * Uses the provider registry to determine if an API key is required.
@@ -186,7 +187,6 @@ export declare class AgentManager {
     hasValidConfig(): boolean;
     /**
      * Clears conversation history and resets agent state.
-     * Removes all conversation history, pending approvals, and interrupted state.
      */
     clearHistory(): void;
     /**
@@ -194,70 +194,63 @@ export declare class AgentManager {
      */
     stopStreaming(): void;
     /**
-     * Generates AI response to user message using the agent.
-     * Handles the complete execution cycle including tool calls and approvals.
-     * @param message The user message to respond to (may include processed attachment content)
+     * Approves a pending tool call.
+     * @param approvalId The approval ID to approve
+     * @param reason Optional reason for approval
      */
-    generateResponse(message: string): Promise<void>;
+    approveToolCall(approvalId: string, reason?: string): void;
     /**
-     * Approves a tool call by interruption ID.
-     * @param interruptionId The interruption ID to approve
+     * Rejects a pending tool call.
+     * @param approvalId The approval ID to reject
+     * @param reason Optional reason for rejection
      */
-    approveToolCall(interruptionId: string): Promise<void>;
+    rejectToolCall(approvalId: string, reason?: string): void;
     /**
-     * Rejects a tool call by interruption ID.
-     * @param interruptionId The interruption ID to reject
-     */
-    rejectToolCall(interruptionId: string): Promise<void>;
-    /**
-     * Approves all tools in a group by group ID.
-     * @param groupId The group ID containing the tool calls
-     * @param interruptionIds Array of interruption IDs to approve
+     * Generates AI response to user message using the agent.
+     * Handles the complete execution cycle including tool calls.
+     * @param message The user message to respond to (may include processed attachment content)
      */
-    approveGroupedToolCalls(groupId: string, interruptionIds: string[]): Promise<void>;
+    generateResponse(message: string): Promise<void>;
     /**
-     * Rejects all tools in a group by group ID.
-     * @param groupId The group ID containing the tool calls
-     * @param interruptionIds Array of interruption IDs to reject
+     * Updates token usage statistics.
      */
-    rejectGroupedToolCalls(groupId: string, interruptionIds: string[]): Promise<void>;
+    private _updateTokenUsage;
     /**
      * Initializes the AI agent with current settings and tools.
-     * Sets up the agent with model configuration, tools, and MCP servers.
+     * Sets up the agent with model configuration, tools, and MCP tools.
      */
-    initializeAgent: (mcpServers?: BrowserMCPServerStreamableHttp[]) => Promise<void>;
+    initializeAgent: (mcpTools?: ToolMap) => Promise<void>;
     /**
-     * Processes the result stream from agent execution.
+     * Processes the stream result from agent execution.
      * Handles message streaming, tool calls, and emits appropriate events.
-     * @param result The async iterable result from agent execution
+     * @param result The stream result from agent execution
+     * @returns Processing result including approval info if applicable
      */
-    private _processRunResult;
+    private _processStreamResult;
     /**
-     * Formats tool input for display by pretty-printing JSON strings.
-     * @param input The tool input string to format
-     * @returns Pretty-printed JSON string
+     * Emits a message_complete event.
      */
-    private _formatToolInput;
+    private _emitMessageComplete;
     /**
-     * Handles the start of a tool call from the model event.
-     * @param modelEvent The model event containing tool call information
+     * Handles tool-result stream parts.
      */
-    private _handleToolCallStart;
+    private _handleToolResult;
     /**
-     * Handles tool execution output and completion.
-     * @param event The tool output event containing result information
+     * Handles tool-approval-request stream parts.
      */
-    private _handleToolOutput;
+    private _handleApprovalRequest;
     /**
-     * Handles approval request for a single tool call.
-     * @param interruption The tool approval interruption item
+     * Waits for user approval of a tool call.
+     * @param approvalId The approval ID to wait for
+     * @returns Promise that resolves to true if approved, false if rejected
      */
-    private _handleSingleToolApproval;
+    private _waitForApproval;
     /**
-     * Handles approval requests for multiple grouped tool calls.
-     * @param interruptions Array of tool approval interruption items
+     * Formats tool input for display by pretty-printing JSON strings.
+     * @param input The tool input string to format
+     * @returns Pretty-printed JSON string
      */
-    private _handleGroupedToolApprovals;
+    private _formatToolInput;
     /**
      * Checks if the current provider supports tool calling.
      * @returns True if the provider supports tool calling, false otherwise
@@ -280,16 +273,15 @@ export declare class AgentManager {
     private _secretsManager?;
     private _selectedToolNames;
     private _agent;
-    private _runner;
     private _history;
-    private _mcpServers;
+    private _mcpTools;
     private _isInitializing;
     private _controller;
-    private _pendingApprovals;
-    private _interruptedState;
     private _agentEvent;
     private _tokenUsage;
     private _tokenUsageChanged;
     private _activeProvider;
     private _activeProviderChanged;
+    private _pendingApprovals;
 }
+export {};