### Serve a Model with vLLM

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/vllm.md

Command to start serving a specified model using vLLM. Ensure vLLM is installed and accessible in your environment.

```bash
vllm serve <model_name>
```

--------------------------------

### Setup Mistral Vibe Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Set up the Mistral Vibe agent. Alternatively, set the MISTRAL_API_KEY environment variable before starting JupyterLab.

```none
vibe --setup
```

--------------------------------

### Install Root Dependencies with Homebrew

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Install git, uv, and just using Homebrew on macOS if you do not have them installed.

```sh
brew install uv just
```

--------------------------------

### Install Magic Commands on Remote Kernels

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

If using remote kernels (e.g., SageMaker Studio), install the package directly into the remote kernel environment. Re-run the load extension command after installation.

```ipython
%pip install jupyter_ai_magic_commands
```

--------------------------------

### Install Mistral Vibe agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install the Mistral Vibe agent using either `uv` or `pip`.

```none
uv tool install mistral-vibe
```

```none
pip install mistral-vibe
```

--------------------------------

### Full MCP Server Configuration Example

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/index.md

A comprehensive `.jupyter/mcp_settings.json` example demonstrating the configuration of both stdio and HTTP MCP servers. Remember to restart JupyterLab for changes to take effect.

```json
{
  "mcp_servers": [
    {
      "name": "Filesystem Tools",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    {
      "name": "GitHub Tools",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": [
        {"name": "GITHUB_PERSONAL_ACCESS_TOKEN", "value": "ghp_xxx"}
      ]
    },
    {
      "type": "http",
      "name": "Company Internal Tools",
      "url": "https://internal-mcp.corp.example.com/mcp",
      "headers": [
        {"name": "Authorization", "value": "Bearer my-token"}
      ]
    }
  ]
}
```

--------------------------------

### Install Jupyter AI using uv

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install Jupyter AI with the `uv` package manager for faster dependency resolution.

```none
uv pip install jupyter-ai
```

--------------------------------

### Start JupyterLab

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Launch JupyterLab to access the Jupyter AI interface. This command starts the JupyterLab server.

```default
jupyter lab
```

--------------------------------

### Install Jupyternaut Core

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Install Jupyternaut with its core features for chat and notebook tools. Conversation memory is kept in memory.

```sh
pip install 'jupyter-ai[jupyternaut]'
```

--------------------------------

### Install Jupyter AI using micromamba

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install Jupyter AI using micromamba, a lightweight, dependency-free conda installer.

```none
micromamba install -c conda-forge jupyter-ai
```

--------------------------------

### Install Jupyternaut Package

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Install the standalone Jupyternaut package. Conversation memory is kept in memory.

```sh
pip install jupyter-ai-jupyternaut
```

--------------------------------

### Start JupyterLab

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Starts JupyterLab from the root of the devrepo. This command runs 'uv run jupyter lab' and ensures it uses the correct configuration.

```default
just start
```

--------------------------------

### Install E2E Test Dependencies

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Installs necessary dependencies for running end-to-end tests using Playwright and Galata. This command should be run once.

```sh
source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm install
jlpm playwright install
```

--------------------------------

### Custom Completion Provider Implementation

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Implement a custom completion provider by extending BaseProvider and FakeListLLM. This example shows how to override methods for generating both single and streaming inline completions, demonstrating custom logic for handling requests and responses.

```python
class MyCompletionProvider(BaseProvider, FakeListLLM):
    id = "my_provider"
    name = "My Provider"
    model_id_key = "model"
    models = ["model_a"]

    def __init__(self, **kwargs):
        kwargs["responses"] = ["This fake response will not be used for completion"]
        super().__init__(**kwargs)

    async def generate_inline_completions(self, request: InlineCompletionRequest):
        return InlineCompletionReply(
            list=InlineCompletionList(items=[
                {"insertText": "An ant minding its own business"},
                {"insertText": "A bug searching for a snack"}
            ]),
            reply_to=request.number,
        )

    async def stream_inline_completions(self, request: InlineCompletionRequest):
        token_1 = f"t{request.number}s0"
        token_2 = f"t{request.number}s1"

        yield InlineCompletionReply(
            list=InlineCompletionList(
                items=[
                    {"insertText": "An ", "isIncomplete": True, "token": token_1},
                    {"insertText": "", "isIncomplete": True, "token": token_2}
                ]
            ),
            reply_to=request.number,
        )

        # where merge_iterators
        async for reply in merge_iterators([
            self._stream("elephant dancing in the rain", request.number, token_1, start_with="An"),
            self._stream("A flock of birds flying around a mountain", request.number, token_2)
        ]):
            yield reply

    async def _stream(self, sentence, request_number, token, start_with = ""):
        suggestion = start_with

        for fragment in sentence.split():
            await asyncio.sleep(0.75)
            suggestion += " " + fragment
            yield InlineCompletionStreamChunk(
                type="stream",
                response={"insertText": suggestion, "token": token},
                reply_to=request_number,
                done=False
            )

        # finally, send a message confirming that we are done
        yield InlineCompletionStreamChunk(
            type="stream",
            response={"insertText": suggestion, "token": token},
            reply_to=request_number,
            done=True,
        )
```

--------------------------------

### Custom Completion Provider Implementation

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Example of a custom completion provider demonstrating both generate_inline_completions and stream_inline_completions methods.

```APIDOC
## Class: MyCompletionProvider

### Description
This class extends `BaseProvider` and `FakeListLLM` to provide custom code completions. It demonstrates how to implement both immediate and streaming completion responses.

### Methods
- `__init__`: Initializes the provider with a fake response.
- `generate_inline_completions`: Generates a list of inline completion suggestions.
- `stream_inline_completions`: Streams inline completion suggestions chunk by chunk.
- `_stream`: A helper method to simulate streaming text fragments.

### `generate_inline_completions` Method

#### Description
Generates a list of inline completion suggestions for a given request.

#### Parameters
- `request` (InlineCompletionRequest) - The request object containing details for completion.

#### Returns
- `InlineCompletionReply` - An object containing a list of completion items.

### `stream_inline_completions` Method

#### Description
Streams inline completion suggestions, yielding an initial reply and then subsequent chunks.

#### Parameters
- `request` (InlineCompletionRequest) - The request object containing details for completion.

#### Yields
- `InlineCompletionReply` - The initial reply with `isIncomplete` set to `True`.
- `InlineCompletionStreamChunk` - Subsequent chunks of the completion stream.

### `_stream` Method (Helper)

#### Description
Simulates streaming text by splitting a sentence into fragments and yielding them as `InlineCompletionStreamChunk` objects.

#### Parameters
- `sentence` (str) - The sentence to stream.
- `request_number` (int) - The identifier for the request.
- `token` (str) - A unique token for the stream.
- `start_with` (str, optional) - Initial text to prepend to the stream. Defaults to "".

#### Yields
- `InlineCompletionStreamChunk` - Chunks of the streamed text, with the last chunk having `done` set to `True`.
```

--------------------------------

### Specify Config File at Startup

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Load Jupyternaut configuration from a specified JSON file using the --config or -c option when starting JupyterLab.

```bash
jupyter lab --config <config-file-path>
```

--------------------------------

### Running Ollama Server

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

This command starts the Ollama server. The output indicates if the default port is already in use, confirming the server is running.

```bash
$ ollama serve
Error: listen tcp 127.0.0.1:11434: bind: address already in use
```

--------------------------------

### Install Codex ACP adapter

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install the Node.js package required for the Codex agent to work with Jupyter AI.

```none
npm install -g @zed-industries/codex-acp
```

--------------------------------

### Install and Test Custom Provider

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Install your custom provider package in editable mode and restart JupyterLab to verify its registration.

```sh
# from `my_package` directory
pip install -e .
```

--------------------------------

### Install Pandoc with Conda-Forge

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Installs the pandoc documentation generator from the conda-forge channel. This is a required dependency for building local documentation.

```default
conda install -c conda-forge pandoc
```

--------------------------------

### Example: Claude Code Persona Entry Point

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/providing_entry_points.md

This example shows how to configure an entry point for the 'claude_code' persona within the 'jupyter_ai.personas' group in your `pyproject.toml` file.

```toml
[project.entry-points."jupyter_ai.personas"]
claude_code = "jupyter_ai_claude_code.persona:ClaudeCodePersona"
```

--------------------------------

### Install Root Dependencies with Conda/Mamba/Micromamba

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Use these commands to install uv and just into your base environment if you are using conda, mamba, or micromamba. Ensure the base environment is activated before running.

```sh
{conda,mamba,micromamba} activate base
{conda,mamba,micromamba} install uv just
# make sure to activate the `base` environment before working in this repo
```

--------------------------------

### Install All Packages in Editable Mode

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Automatically installs each package in the monorepo in editable mode. This command includes building frontend assets and enabling extensions.

```default
just install-all
```

--------------------------------

### Start JupyterLab with Custom Notebook Directory

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Starts JupyterLab with a specified notebook directory, overriding the default location. Requires the 'justfile_directory()' function to be available or the config file to be in the current directory.

```default
uv run jupyter lab --config=jupyter_server_config.py --notebook-dir=<start_directory>
```

--------------------------------

### Install Jupyter AI using pip

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Use this command to install the Jupyter AI package in your Python environment.

```none
pip install jupyter-ai
```

--------------------------------

### Format AI Output to HTML

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Use the -f or --format argument to specify how the AI model's output should be interpreted. This example forces the output to be treated as HTML.

```default
%%ai anthropic:claude-v1.2 -f html
Create a square using SVG with a black border and white fill.
```

--------------------------------

### Install Jupyternaut with Persistence

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Install Jupyternaut with the 'persistence' extra to enable conversation memory to be saved to a local SQLite database. This allows conversations to survive server restarts.

```sh
pip install 'jupyter-ai-jupyternaut[persistence]'
```

--------------------------------

### Specify Default API Keys

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Configures default API keys for providers. This is offered as a starting point and can be overridden in the settings panel.

```bash
jupyter lab --AiExtension.default_api_keys={'OPENAI_API_KEY': 'sk-abcd'}
```

--------------------------------

### Install Claude Code ACP adapter

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install the Node.js package required for the Claude Code agent to work with Jupyter AI.

```none
npm install -g @agentclientprotocol/claude-agent-acp
```

--------------------------------

### Install Jupyter AI using conda

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install Jupyter AI from the conda-forge channel using the conda package manager.

```none
conda install -c conda-forge jupyter-ai
```

--------------------------------

### Install jupyter-ai-magic-commands Package

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Install the optional package that provides Jupyter AI magic commands. This is the first step to enable AI model interaction in your environment.

```bash
pip install jupyter-ai-magic-commands
```

--------------------------------

### Install Jupyter AI using mamba

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Install Jupyter AI from the conda-forge channel using the mamba package manager, which is often faster than conda.

```none
mamba install -c conda-forge jupyter-ai
```

--------------------------------

### Use Ollama Llama3.2 Model with AI Magic Command

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

This example demonstrates how to use the 'ai' magic command with an Ollama model (llama3.2) after configuring the host.

```python
%%ai ollama:llama3.2
What is a transformer?
```

--------------------------------

### Jupyter Paths Command Output

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Example output of the 'jupyter --paths' command, showing directories where Jupyter scans for configuration files.

```bash
(jupyter-ai-lab4) ➜ jupyter --paths
config:
    /opt/anaconda3/envs/jupyter-ai-lab4/etc/jupyter
    /Users/3coins/.jupyter
    /Users/3coins/.local/etc/jupyter
    /usr/3coins/etc/jupyter
    /etc/jupyter
data:
    /opt/anaconda3/envs/jupyter-ai-lab4/share/jupyter
    /Users/3coins/Library/Jupyter
    /Users/3coins/.local/share/jupyter
    /usr/local/share/jupyter
    /usr/share/jupyter
runtime:
    /Users/3coins/Library/Jupyter/runtime
```

--------------------------------

### Install Jupyter AI using pixi

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/getting-started.md

Add Jupyter AI to your project dependencies using the pixi package manager.

```none
pixi add jupyter-ai
```

--------------------------------

### Log in to GitHub Copilot Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Authenticate with the GitHub Copilot agent. Alternatively, set environment variables like COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN before starting JupyterLab.

```none
copilot login
```

--------------------------------

### Test vLLM API Connection

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/vllm.md

Example API call to test if a vLLM server is running and accessible. This uses OpenAI's API format, which vLLM supports.

```python
import openai

openai.api_base = "http://localhost:8000/v1"
openai.api_key = "EMPTY"

completion = openai.ChatCompletion.create(
    model="phi-3-mini-4k-instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(completion.choices[0].message.content)
```

--------------------------------

### Synchronize and Refresh Environment

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Refreshes UV's cache, synchronizes the local Python environment with lock files, installs dependencies from new submodules, and resolves conflicts. Useful for clearing errors.

```default
just sync --refresh
```

--------------------------------

### Get Agent Configuration

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/personas_group.md

Use this method to access the LangChain runnable configured by Jupyternaut. It sets up a chat model with specified arguments and system prompt, and integrates memory and tools.

```python
async def get_agent(self, model_id: str, model_args, system_prompt: str):
        model = ChatLiteLLM(**model_args, model=model_id, streaming=True)
        memory_store = await self.get_memory_store()

        return create_agent(
            model,
            system_prompt=system_prompt,
            checkpointer=memory_store,
            tools=self.get_tools(),
        )
```

--------------------------------

### Initialize Custom Personas with BasePersona (Jupyter AI 3.2)

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/roadmap/jupyter-ai-3.2.md

Jupyter AI 3.2 allows reusing an engine to create new AI personas with custom models, identities, contexts, and options. This example shows initializing a 'Researcher' persona and a 'SensitiveDataAnalyst' persona.

```python
# initializes '@MyAgent', your custom general-purpose agent
BasePersona(
    ychat=ychat,
    engine=PersonaEngine.from_id("opencode-acp"),
    model=PersonaModel(model_id="anthropic/claude-opus-4-8"),
    identity=PersonaIdentity(name="Researcher", avatar="<some-url-or-b64-img>"),
    context=PersonaContext(
        skills=".jupyter/skills/*",
        mcp_servers=[...]
    ),
    options={"temperature": 0.8},
)

# initializes '@SensitiveDataAnalyst', a self-hosted agent for sensitive data
BasePersona(
    ychat=ychat,
    engine=PersonaEngine.from_id("opencode-acp"),
    model=PersonaModel(model_id="ollama/llama-3.1", model_url="http://localhost:11434"),
    identity=PersonaIdentity(name="SensitiveDataAnalyst", avatar="<some-url-or-b64-img>"),
    context=PersonaContext(
        skills=".jupyter/sensitive-data-skills/*",
        mcp_servers=[McpServer(name="Sensitive data tools", ...)]
    ),
    options={"temperature": 0.2},
)
```

--------------------------------

### Clone Jupyter AI Dev Repo

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Clone the developer repository to set up an editable installation of all Jupyter AI subpackages.

```bash
git clone --recurse-submodules https://github.com/jupyter-ai-contrib/jupyter-ai-devrepo.git

cd jupyter-ai-devrepo/
```

--------------------------------

### Build Local Documentation

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Builds the HTML documentation locally by navigating to the docs directory and running 'make html'. The output can be found at '<JUPYTER-AI-ABSOLUTE-PATH>/docs/build/html/index.html'.

```sh
cd jupyter-ai/docs/
make html
```

--------------------------------

### List Available AI Models

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Use the `%ai list` subcommand to see all available AI providers and their supported models. This helps in selecting the appropriate model for your tasks.

```ipython
%ai list
```

--------------------------------

### Define Entry Point Template

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/providing_entry_points.md

Use this template in your `pyproject.toml` to define an entry point. Replace placeholders with your specific module path, class name, and a unique name for the entry point.

```toml
[project.entry-points.<entry-point-group>]
<some-unique-name> = "<module-path>:<class-name>"
```

--------------------------------

### Configure Aliases on Startup

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Customize aliases by setting the `c.AiMagics.aliases` traitlet in your `ipython_config.py` file. This allows for persistent aliases across sessions.

```python
c.AiMagics.aliases = {
  "my_custom_alias": "my_provider:my_model"
}
```

--------------------------------

### Configure Multiple Models via Command Line

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Pass distinct model parameters for multiple models by appending additional --AiExtension.model_parameters arguments.

```bash
jupyter lab \
--AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"model_kwargs":{"maxTokens":200}}' \
--AiExtension.model_parameters openai/gpt-4.1='{"max_tokens":1024,"temperature":0.9}'
```

--------------------------------

### Configure Stdio MCP Server

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/index.md

Define a stdio server configuration in `.jupyter/mcp_settings.json`. Specify the command and arguments to launch the local process, along with any necessary environment variables.

```json
{
  "mcp_servers": [
    {
      "name": "My Custom Tools",
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": [
        {"name": "API_KEY", "value": "sk-abc123"}
      ]
    }
  ]
}
```

--------------------------------

### Generated LLM Class with Model Parameters

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Illustrates the resulting Python class instantiation based on the provided command-line model parameters.

```python
BedrockProvider(model_kwargs={"maxTokens":200}, ...)
```

```python
AnthropicProvider(max_tokens=1024, temperature=0.9, ...)
```

--------------------------------

### Implement Completion Provider with Full Notebook Content

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

This provider retrieves the full notebook content from the collaborative model to improve completion accuracy. It handles both notebook and file types, and filters cells by type. Use this when enhanced context from the entire document is needed for better suggestions.

```python
from jupyter_ydoc import YNotebook


class MyCompletionProvider(BaseProvider, FakeListLLM):
    id = "my_provider"
    name = "My Provider"
    model_id_key = "model"
    models = ["model_a"]

    def __init__(self, **kwargs):
        kwargs["responses"] = ["This fake response will not be used for completion"]
        super().__init__(**kwargs)

    async def _get_prefix_and_suffix(self, request: InlineCompletionRequest):
        prefix = request.prefix
        suffix = request.suffix.strip()

        server_ydoc = self.server_settings.get("jupyter_server_ydoc", None)
        if not server_ydoc:
            # fallback to prefix/suffix from single cell
            return prefix, suffix

        is_notebook = request.path.endswith("ipynb")
        document = await server_ydoc.get_document(
            path=request.path,
            content_type="notebook" if is_notebook else "file",
            file_format="json" if is_notebook else "text"
        )
        if not document or not isinstance(document, YNotebook):
            return prefix, suffix

        cell_type = "markdown" if request.language == "markdown" else "code"

        is_before_request_cell = True
        before = []
        after = [suffix]

        for cell in document.ycells:
            if is_before_request_cell and cell["id"] == request.cell_id:
                is_before_request_cell = False
                continue
            if cell["cell_type"] != cell_type:
                continue
            source = cell["source"].to_py()
            if is_before_request_cell:
                before.append(source)
            else:
                after.append(source)

        before.append(prefix)
        prefix = "\n\n".join(before)
        suffix = "\n\n".join(after)
        return prefix, suffix

    async def generate_inline_completions(self, request: InlineCompletionRequest):
        prefix, suffix = await self._get_prefix_and_suffix(request)

        return InlineCompletionReply(
            list=InlineCompletionList(items=[
                {"insertText": your_llm_function(prefix, suffix)}
            ]),
            reply_to=request.number,
        )
```

--------------------------------

### Register Custom Model Provider via Entry Point

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Declare your custom model provider in the pyproject.toml file under the jupyter_ai.model_providers entry point.

```toml
[project]
name = "my_package"
version = "0.0.1"

[project.entry-points."jupyter_ai.model_providers"]
my-provider = "my_provider:MyProvider"
```

--------------------------------

### Define a Custom Embedding Model Provider

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/embeddings_providers_group.md

Subclass `BaseEmbeddingsProvider` and a LangChain `Embeddings` class to create a custom embedding provider. Ensure you define `id`, `name`, `model_id_key`, and `models` attributes. This example uses `FakeEmbeddings` for demonstration.

```python
from jupyter_ai_magics import BaseEmbeddingsProvider
from langchain.embeddings import FakeEmbeddings

class MyEmbeddingsProvider(BaseEmbeddingsProvider, FakeEmbeddings):
    id = "my_embeddings_provider"
    name = "My Embeddings Provider"
    model_id_key = "model"
    models = ["my_model"]

    def __init__(self, **kwargs):
        super().__init__(size=300, **kwargs)
```

--------------------------------

### Custom Model Provider with Auth and Fields

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Define a custom model provider by inheriting from BaseProvider and a Langchain LLM. Configure authentication using EnvAuthStrategy and add custom fields for UI configuration. The auth_strategy handles API key retrieval from environment variables and passes it as a keyword argument to the model's __init__. Custom fields are also passed as keyword arguments and define UI elements for user input.

```python
from typing import ClassVar, List
from jupyter_ai_magics import BaseProvider
from jupyter_ai_magics.providers import EnvAuthStrategy, Field, TextField, MultilineTextField
from langchain_community.llms import FakeListLLM


class MyProvider(BaseProvider, FakeListLLM):
    id = "my_provider"
    name = "My Provider"
    model_id_key = "model"
    models = [
        "model_a",
        "model_b"
    ]

    auth_strategy = EnvAuthStrategy(
        name="MY_API_KEY", keyword_param="my_api_key_param"
    )

    fields: ClassVar[List[Field]] = [
        TextField(key="my_llm_parameter", label="The name for my_llm_parameter to show in the UI"),
        MultilineTextField(key="custom_config", label="Custom Json Config", format="json"),
    ]

    def __init__(self, **kwargs):
        model = kwargs.get("model_id")
        kwargs["responses"] = (
            ["This is a response from model 'a'"]
            if model == "model_a" else
            ["This is a response from model 'b'"]
        )
        super().__init__(**kwargs)
```

--------------------------------

### Format AI Output to Math (LaTeX)

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Specify the 'math' format to have the AI model's output rendered as typeset equations using LaTeX. The output is enclosed in '$$'.

```default
%%ai chatgpt -f math
Generate the 2D heat equation in LaTeX surrounded by `$$`. Do not include an explanation.
```

--------------------------------

### Initialize OpenCode Persona (Jupyter AI 3.0)

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/roadmap/jupyter-ai-3.2.md

In Jupyter AI 3.0, this is how you initialize an OpenCode persona using a local model. Note that only one instance of OpenCodeAcpPersona can be created per chat.

```python
# initializes '@OpenCode' that just reads from your local OpenCode config
OpenCodeAcpPersona(ychat=ychat)
# cannot add another instance of `OpenCodeAcpPersona`
```

--------------------------------

### Log in to OpenCode Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Authenticate with the OpenCode agent. Ensure you are logged in via the agent's CLI before restarting JupyterLab.

```none
opencode auth login
```

--------------------------------

### Initialize Scrolling Strips with JavaScript

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/index.md

Initializes two scrolling strips with different counts and directions. The animation uses CSS transitions and is controlled by timeouts. Ensure the HTML elements with IDs 'left-strip' and 'right-strip' exist.

```javascript
// animationiteration fires and a CSS variable is updated).
(function() {
  var ICON_H = 72;
  var HOLD_MS = 1200;  // time to hold each icon before sliding
  var LEFT_COUNT = 14;
  var RIGHT_COUNT = 8;

  function initStrip(id, count, direction) {
    var strip = document.getElementById(id);
    // direction: 1 = scroll up (pos increases), -1 = scroll down (pos decreases)
    var pos = (direction === -1) ? count : 0;
    strip.style.transform = 'translateY(' + (-pos * ICON_H) + 'px)';

    function tick() {
      strip.classList.add('animating');
      var nextPos = pos + direction;
      strip.style.transform = 'translateY(' + (-nextPos * ICON_H) + 'px)';

      strip.addEventListener('transitionend', function onEnd() {
        strip.removeEventListener('transitionend', onEnd);
        strip.classList.remove('animating');

        pos = nextPos;

        if (direction === 1 && pos >= count) {
          pos = 0;
          strip.style.transform = 'translateY(0px)';
        } else if (direction === -1 && pos <= 0) {
          pos = count;
          strip.style.transform = 'translateY(' + (-pos * ICON_H) + 'px)';
        }

        setTimeout(tick, HOLD_MS);
      });
    }

    setTimeout(tick, HOLD_MS);
  }

  initStrip('left-strip', LEFT_COUNT, 1);
  initStrip('right-strip', RIGHT_COUNT, -1);
})();
</script>
```

--------------------------------

### DebugPersona Reference Implementation

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/personas_group.md

A concrete implementation of a custom AI persona named DebugPersona. It extends BasePersona and provides default settings, always responding with 'Hello!'.

```python
class DebugPersona(BasePersona):
    """
    The Jupyternaut persona, the main persona provided by Jupyter AI.
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    @property
    def defaults(self):
        return PersonaDefaults(
            name="DebugPersona",
            avatar_path="/api/ai/static/jupyternaut.svg",
            description="A mock persona used for debugging in local dev environments.",
            system_prompt="...",
        )

    async def process_message(self, message: Message):
        self.send_message(NewMessage(body="Hello!", sender=self.id))
        return
```

--------------------------------

### Configure Default Language Model

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Set a default language model using `%config AiMagics.initial_language_model`. Subsequent `%%ai` magics can then be invoked without specifying the model.

```python
%config AiMagics.initial_language_model = "anthropic:claude-v1.2"
```

--------------------------------

### Animated Icon Strip Initialization

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/_templates/hero-icon.html

Initializes and animates two icon strips ('left-strip' and 'right-strip') using JavaScript and CSS transitions. It handles the scrolling logic, including holding each icon for a specified duration and looping the animation. This approach avoids a Safari bug where keyframe animations might flash.

```javascript
// Animation driven entirely by JS + CSS transitions to avoid Safari's
// keyframe flash bug (Safari briefly resets to 0% keyframe when
// animationiteration fires and a CSS variable is updated). (function() {
var ICON_H = 72;
var HOLD_MS = 1200; // time to hold each icon before sliding
var LEFT_COUNT = 14;
var RIGHT_COUNT = 8;
function initStrip(id, count, direction) {
var strip = document.getElementById(id);
// direction: 1 = scroll up (pos increases), -1 = scroll down (pos decreases)
var pos = (direction === -1) ? count : 0;
strip.style.transform = 'translateY(' + (-pos * ICON_H) + 'px)';
function tick() {
strip.classList.add('animating');
var nextPos = pos + direction;
strip.style.transform = 'translateY(' + (-nextPos * ICON_H) + 'px)';
strip.addEventListener('transitionend', function onEnd() {
strip.removeEventListener('transitionend', onEnd);
strip.classList.remove('animating');
pos = nextPos;
if (direction === 1 && pos >= count) {
pos = 0;
strip.style.transform = 'translateY(0px)';
} else if (direction === -1 && pos <= 0) {
pos = count;
strip.style.transform = 'translateY(' + (-pos * ICON_H) + 'px)';
}
setTimeout(tick, HOLD_MS);
});
}
setTimeout(tick, HOLD_MS);
}
initStrip('left-strip', LEFT_COUNT, 1);
initStrip('right-strip', RIGHT_COUNT, -1);
})();
```

--------------------------------

### Configure AI Max History in ipython_config.py

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Set the max_history traitlet in your ipython_config.py file to configure the context window size for all notebooks.

```python
c.AiMagics.max_history = 4
```

--------------------------------

### List Models for a Specific Provider

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Optionally, specify a provider ID to `%ai list` to filter and display only the models offered by that particular provider. This is useful for narrowing down choices.

```ipython
%ai list openai
```

--------------------------------

### Log in to Kiro Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Authenticate with the Kiro agent. Ensure you are logged in via the agent's CLI before restarting JupyterLab.

```none
kiro-cli login
```

--------------------------------

### Invoke AI Model with Cell Magic

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Use the `%%ai` cell magic to send a prompt to a specified AI model. The prompt begins on the second line of the cell. Ensure the model ID is in the format `<provider-id>:<local-model-id>`.

```ipython
%%ai bedrock/anthropic.claude-3-5-haiku-20241022-v1:0
What is the capital of France?
```

--------------------------------

### Log in to Gemini Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Authenticate with the Gemini agent. Ensure you are logged in via the agent's CLI before restarting JupyterLab.

```none
gemini auth login
```

--------------------------------

### Define a Custom Model Provider

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/model_providers_group.md

Subclass BaseProvider and a LangChain LLM/ChatModel to create a custom model provider. Configure model IDs and responses for different models.

```python
from jupyter_ai_magics import BaseProvider
from langchain_community.llms import FakeListLLM


class MyProvider(BaseProvider, FakeListLLM):
    id = "my_provider"
    name = "My Provider"
    model_id_key = "model"
    models = [
        "model_a",
        "model_b"
    ]
    def __init__(self, **kwargs):
        model = kwargs.get("model_id")
        kwargs["responses"] = (
            ["This is a response from model 'a'"]
            if model == "model_a" else
            ["This is a response from model 'b'"]
        )
        super().__init__(**kwargs)
```

--------------------------------

### Invoke AI with Default Model

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

After configuring a default model, you can use the `%%ai` cell magic without specifying a model ID. The AI will use the previously configured default.

```ipython
%%ai
Write a poem about C++.
```

--------------------------------

### Configure Model Parameters via Command Line

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Specify model parameters like maxTokens for a specific model using the --AiExtension.model_parameters flag. Single quotes are often required around the JSON string in shells.

```bash
jupyter lab --AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"model_kwargs":{"maxTokens":200}}'
```

```bash
jupyter lab --AiExtension.model_parameters bedrock/anthropic.claude-3-5-haiku-20241022-v1:0='{"max_tokens":1024,"temperature":0.9}'
```

--------------------------------

### Format AI Output to Code

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Use the 'code' format to ensure the AI model's output is presented as a code cell. This is useful for generating functions or scripts.

```default
%%ai chatgpt -f code
A function that computes the lowest common multiples of two integers, and
a function that runs 5 test cases of the lowest common multiple function
```

--------------------------------

### Load Jupyter AI Magic Commands Extension

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Load the IPython extension to enable the use of `%%ai` cell magics and `%ai` line magics. This command should not produce any output upon successful execution.

```ipython
%load_ext jupyter_ai_magic_commands
```

--------------------------------

### Configure HTTP MCP Server

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/index.md

Configure a remote HTTP MCP server by specifying its type, name, URL, and optional headers in `.jupyter/mcp_settings.json`. This allows integration with external services.

```json
{
  "mcp_servers": [
    {
      "type": "http",
      "name": "Remote Tools",
      "url": "https://my-mcp-server.example.com/mcp",
      "headers": [
        {"name": "Authorization", "value": "Bearer my-token"}
      ]
    }
  ]
}
```

--------------------------------

### Configure Default Model in IPython Config

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Persistently set the default language model for all notebooks by adding `c.AiMagics.initial_language_model` to your `ipython_config.py` file.

```python
c.AiMagics.initial_language_model = "anthropic:claude-v1.2"
```

--------------------------------

### Access Codex Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Use this command to interact with the Codex agent. Some agents require authentication or configuration before usage.

```none
codex
```

--------------------------------

### Blocklist Providers

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Prevents specific providers from being used in the settings panel. This configuration takes precedence over the allowlist.

```bash
jupyter lab --AiExtension.blocked_providers=openai
```

```bash
jupyter lab --AiExtension.blocked_providers=openai --AiExtension.blocked_providers=ai21
```

--------------------------------

### Define a Custom LangChain Chain

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Define a custom LangChain chain using Python. This involves setting up an LLM, a prompt template, and then creating the LLMChain object.

```python
from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate
from langchain.llms import OpenAI

llm = OpenAI(temperature=0.9)
prompt = PromptTemplate(
    input_variables=["product"],
    template="What is a good name for a company that makes {product}?",
)
chain = LLMChain(llm=llm, prompt=prompt)
```

--------------------------------

### Pull All Submodule Changes

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/contributors/index.md

Switches to the main branch on every submodule and pulls the latest changes. May prompt for GitHub authentication if RSA key is not set up.

```default
just pull-all
```

--------------------------------

### Log in to Claude Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Use this command to authenticate with the Claude agent if it is not replying. Ensure you are logged in via the agent's CLI before restarting JupyterLab.

```none
claude login
```

--------------------------------

### Configure Goose Agent

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/troubleshooting.md

Configure the Goose agent, which may require selecting an LLM before usage. Ensure you are logged in via the agent's CLI before restarting JupyterLab.

```none
goose configure
```

--------------------------------

### Specify Default Language Model

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Sets the initial language model for Jupyternaut. This value can be overridden in the settings panel.

```bash
jupyter lab --AiExtension.initial_language_model=bedrock/anthropic.claude-3-5-haiku-20241022-v1:0
```

--------------------------------

### Interpolate Notebook Output in Prompt

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Reference the output of previous cells using the 'Out' list with its index. The content of the specified output cell is substituted into the prompt.

```default
%%ai cohere:command-xlarge-nightly
Write code that would produce the following output:
--
{Out[11]}
```

--------------------------------

### Use an Alias to Interact with an AI Model

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/magic_commands/index.md

Utilize a previously created alias to send prompts to the associated AI model. This simplifies the command structure when working with frequently used models.

```default
%%ai claude
Write a poem about C++.
```

--------------------------------

### Configure Ollama Host Environment Variable

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/users/jupyternaut/index.md

Sets the OLLAMA_HOST environment variable to use a custom IP address and port for the Ollama server. This is necessary when not using the default local address.

```python
%load_ext jupyter_ai_magics
os.environ["OLLAMA_HOST"] = "http://localhost:10000"
```

--------------------------------

### Persona Defaults Data Model

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/developers/entry_points_api/personas_group.md

Defines the structure for default settings of an AI persona, including name, description, avatar path, and system prompt. This is a base model for persona configuration.

```python
class PersonaDefaults(BaseModel):
    name: str  # e.g. "Jupyternaut"
    description: str  # e.g. "..."
    avatar_path: str  # e.g. /avatars/jupyternaut.svg
    system_prompt: str  # e.g. "You are a language model named..."
```

--------------------------------

### Jupyter AI 3.0 BasePersona Interface

Source: https://github.com/jupyterlab/jupyter-ai/blob/main/docs/source/roadmap/jupyter-ai-3.2.md

Presents the BasePersona class interface from version 3.0, highlighting the differences in constructor arguments and the absence of runtime update APIs compared to 3.2.

```python
class BasePersona(ABC, LoggingConfigurable):
    # ─── Lifecycle methods ────────────────────────────────
    def __init__(
        self,
        *args,
        ychat: "YChat",
        **kwargs,
    ): ...
    async def shutdown(self): ...

    # ─── Process message ────────────────────────────────
    async def process_message(self, message: Message) -> None: ...
```