Backport PR ipython#14720: Better Docs and configurability of LLM.

Author: Carreau

IPython/__init__.py

@@ -87,7 +87,7 @@ def embed_kernel(module=None, local_ns=None, **kwargs):
     **kwargs : various, optional
         Further keyword args are relayed to the IPKernelApp constructor,
         such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
-        allowing configuration of the kernel (see :ref:`kernel_options`).  Will only have an effect
+        allowing configuration of the kernel.  Will only have an effect
         on the first embed_kernel call for a given process.
     """
 

IPython/terminal/interactiveshell.py

@@ -426,6 +426,14 @@ def _displayhook_class_default(self):
         allow_none=True,
     ).tag(config=True)
 
+    llm_constructor_kwargs = Dict(
+        {},
+        help="""
+        Extra arguments to pass to `llm_provider_class` constructor.
+
+        This is used to – for example – set the `model_id`""",
+    ).tag(config=True)
+
     llm_provider_class = DottedObjectName(
         None,
         allow_none=True,
@@ -471,7 +479,7 @@ def _set_autosuggestions(self, provider):
             # LLM stuff are all Provisional in 8.32
             if self.llm_provider_class:
                 llm_provider_constructor = import_item(self.llm_provider_class)
-                llm_provider = llm_provider_constructor()
+                llm_provider = llm_provider_constructor(**self.llm_constructor_kwargs)
             else:
                 llm_provider = None
             self.auto_suggest = NavigableAutoSuggestFromHistory()
@@ -508,23 +516,23 @@ def _autosuggestions_provider_changed(self, change):
                 "create": Bool(False),
             },
         ),
-        help="""Add, disable or modifying shortcuts.
+        help="""
+        Add, disable or modifying shortcuts.
 
         Each entry on the list should be a dictionary with ``command`` key
         identifying the target function executed by the shortcut and at least
         one of the following:
 
-        - ``match_keys``: list of keys used to match an existing shortcut,
-        - ``match_filter``: shortcut filter used to match an existing shortcut,
-        - ``new_keys``: list of keys to set,
-        - ``new_filter``: a new shortcut filter to set
+          - ``match_keys``: list of keys used to match an existing shortcut,
+          - ``match_filter``: shortcut filter used to match an existing shortcut,
+          - ``new_keys``: list of keys to set,
+          - ``new_filter``: a new shortcut filter to set
 
         The filters have to be composed of pre-defined verbs and joined by one
         of the following conjunctions: ``&`` (and), ``|`` (or), ``~`` (not).
         The pre-defined verbs are:
 
-        {}
-
+        {filters}
 
         To disable a shortcut set ``new_keys`` to an empty list.
         To add a shortcut add key ``create`` with value ``True``.
@@ -539,8 +547,27 @@ def _autosuggestions_provider_changed(self, change):
         shortcuts) can be modified or disabled. The full list of shortcuts,
         command identifiers and filters is available under
         :ref:`terminal-shortcuts-list`.
+
+        Here is an example:
+
+        .. code::
+
+            c.TerminalInteractiveShell.shortcuts = [
+               {{
+                   "new_keys": ["c-q"],
+                   "command": "prompt_toolkit:named_commands.capitalize_word",
+                   "create": True,
+               }},
+               {{
+                   "new_keys": ["c-j"],
+                   "command": "prompt_toolkit:named_commands.beginning_of_line",
+                   "create": True,
+               }},
+            ]
+
+
         """.format(
-            "\n        ".join([f"- `{k}`" for k in KEYBINDING_FILTERS])
+            filters="\n        ".join([f"  - ``{k}``" for k in KEYBINDING_FILTERS])
         ),
     ).tag(config=True)
 

IPython/terminal/shortcuts/__init__.py

@@ -24,9 +24,9 @@
 from prompt_toolkit.filters import Condition
 
 from IPython.core.getipython import get_ipython
-from IPython.terminal.shortcuts import auto_match as match
-from IPython.terminal.shortcuts import auto_suggest
-from IPython.terminal.shortcuts.filters import filter_from_string
+from . import auto_match as match
+from . import auto_suggest
+from .filters import filter_from_string
 from IPython.utils.decorators import undoc
 
 from prompt_toolkit.enums import DEFAULT_BUFFER
@@ -630,6 +630,7 @@ def win_paste(event):
 ]
 
 UNASSIGNED_ALLOWED_COMMANDS = [
+    auto_suggest.llm_autosuggestion,
     nc.beginning_of_buffer,
     nc.end_of_buffer,
     nc.end_of_line,

IPython/terminal/shortcuts/auto_suggest.py

@@ -24,12 +24,6 @@
 
 from .filters import pass_through
 
-try:
-    import jupyter_ai_magics
-    import jupyter_ai.completions.models as jai_models
-except ModuleNotFoundError:
-    jai_models = None
-
 
 def _get_query(document: Document):
     return document.lines[document.cursor_position_row]
@@ -332,6 +326,11 @@ async def _trigger_llm(self, buffer) -> None:
         If there is a currently running llm task, it will cancel it.
         """
         # we likely want to store the current cursor position, and cancel if the cursor has moved.
+        try:
+            import jupyter_ai_magics
+            import jupyter_ai.completions.models as jai_models
+        except ModuleNotFoundError:
+            jai_models = None
         if not self._llm_provider:
             warnings.warn("No LLM provider found, cannot trigger LLM completions")
             return
@@ -381,6 +380,11 @@ async def _trigger_llm_core(self, buffer: Buffer):
         stream_inline_completions, I'm not sure it is the case for all
         providers.
         """
+        try:
+            import jupyter_ai_magics
+            import jupyter_ai.completions.models as jai_models
+        except ModuleNotFoundError:
+            jai_models = None
 
         request = jai_models.InlineCompletionRequest(
             number=0,
@@ -411,9 +415,6 @@ async def _trigger_llm_core(self, buffer: Buffer):
         return
 
 
-_MIN_LINES = 5
-
-
 async def llm_autosuggestion(event: KeyPressEvent):
     """
     Ask the AutoSuggester from history to delegate to ask an LLM for completion
@@ -424,6 +425,7 @@ async def llm_autosuggestion(event: KeyPressEvent):
     Provisional as of 8.32, may change without warnigns
 
     """
+    _MIN_LINES = 5
     provider = get_ipython().auto_suggest
     if not isinstance(provider, NavigableAutoSuggestFromHistory):
         return

docs/autogen_config.py

@@ -3,7 +3,6 @@
 import inspect
 from pathlib import Path
 from IPython.terminal.ipapp import TerminalIPythonApp
-from ipykernel.kernelapp import IPKernelApp
 from traitlets import Undefined
 from collections import defaultdict
 
@@ -103,13 +102,9 @@ def write_doc(name, title, app, preamble=None):
     trait_aliases = reverse_aliases(app)
     filename = options / (name + ".rst")
     with open(filename, "w", encoding="utf-8") as f:
-        f.write(".. _" + name + "_options:" + "\n\n")
-        f.write(title + "\n")
-        f.write(("=" * len(title)) + "\n")
         f.write("\n")
         if preamble is not None:
             f.write(preamble + '\n\n')
-        #f.write(app.document_config_options())
 
         for c in app._classes_inc_parents():
             f.write(class_config_rst_doc(c, trait_aliases))
@@ -121,7 +116,3 @@ def write_doc(name, title, app, preamble=None):
     Path(generated).write_text("", encoding="utf-8")
 
     write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp())
-    write_doc('kernel', 'IPython kernel options', IPKernelApp(),
-        preamble=("These options can be used in :file:`ipython_kernel_config.py`. "
-                  "The kernel also respects any options in `ipython_config.py`"),
-    )

docs/source/config/details.rst

@@ -1,6 +1,101 @@
-=======================
-Specific config details
-=======================
+==============================
+Specific configuration details
+==============================
+
+.. _llm_suggestions:
+
+LLM Suggestions
+===============
+
+Starting with 9.0, IPython will be able to use LLM providers to suggest code in
+the terminal. This requires a recent version of prompt_toolkit in order to allow
+multiline suggestions. There are currently a number of limitations, and feedback
+on the API is welcome.
+
+Unlike many of IPython features, this is not enabled by default and requires
+multiple configuration options to be set to properly work:
+
+ - Set a keybinding to trigger LLM suggestions. Due to terminal limitations
+   across platforms and emulators, it is difficult to provide a default
+   keybinding. Note that not all keybindings are availables, in particular all
+   the `Ctrl-Enter`, `Alt-backslash` and `Ctrl-Shift-Enter` are not available
+   without integration with your terminal emulator.
+
+ - Chose a LLM `provider`, usually from Jupyter-AI. This will be the interface
+   between IPython itself, and the LLM – that may be local or in on a server.
+
+ - Configure said provider with models, API keys, etc – this will depend on the
+   provider, and you will have to refer to Jupyter-AI documentation, and/or your
+   LLM documenatation.
+
+
+While setting up IPython to use a real LLM, you can refer to
+``examples/auto_suggest_llm.py`` that both provide an example of how to set up
+IPython to use a Fake LLM provider, this can help ensure that the full setup is
+working before switching to a real LLM provider.
+
+
+Setup a keybinding
+------------------
+
+You may want to refer on how to setup a keybinding in IPython, but in short you
+want to bind the ``IPython:auto_suggest.llm_autosuggestion`` command to a
+keybinding, and have it active only when the default buffer isi focused, and
+when using the NavigableSuggestions suggestter (this is the default suggestter,
+the one that is history and LLM aware). Thus the ``navigable_suggestions &
+default_buffer_focused`` filter should be used.
+
+Usually ``Ctrl-Q`` on macos is an available shortcut, note that is does use
+``Ctrl``, and not ``Command``.
+
+The following example will bind ``Ctrl-Q`` to the ``llm_autosuggestion``
+command, with the suggested filter::
+
+    c.TerminalInteractiveShell.shortcuts = [
+        {
+            "new_keys": ["c-q"],
+            "command": "IPython:auto_suggest.llm_autosuggestion",
+            "new_filter": "navigable_suggestions & default_buffer_focused",
+            "create": True,
+        },
+    ]
+
+
+Choose a LLM provider
+---------------------
+
+Set the  ``TerminalInteractiveShell.llm_provider_class`` trait to the fully
+qualified name of the Provider you like, when testing from inside the IPython
+source tree, you can use
+``"examples.auto_suggest_llm.ExampleCompletionProvider"`` This will always
+stream an extract of the Little Prince by Antoine de Saint-Exupéry, and will not
+require any API key or real LLM.
+
+
+In your configuration file adapt the following line to your needs:
+
+.. code-block:: python
+
+    c.TerminalInteractiveShell.llm_provider_class = "examples.auto_suggest_llm.ExampleCompletionProvider"
+
+Configure the provider
+----------------------
+
+It the provider needs to be passed parameters at initialization, you can do so
+by setting the ``llm_provider_kwargs`` traitlet.
+
+.. code-block:: python
+
+    c.TerminalInteractiveShell.llm_provider_kwargs = {"model": "skynet"}
+
+This will depdend on the provider you chose, and you will have to refer to
+the provider documentation.
+
+Extra configuration may be needed by setting environment variables, this will
+again depend on the provider you chose, and you will have to refer to the
+provider documentation.
+
+
 
 .. _custom_prompts:
 

docs/source/config/options/index.rst

@@ -1,12 +1,10 @@
-===============
-IPython options
-===============
+.. _terminal_options:
+
+Terminal options
+================
 
 Any of the options listed here can be set in config files, at the
 command line, from inside IPython, or using a traitlets :class:`Config` object.
 See :ref:`setting_config` for details.
 
-.. toctree::
-
-   terminal
-   kernel
+.. include:: terminal.rst

examples/auto_suggest_llm.py

@@ -1,22 +1,38 @@
 """
-This is an example of Fake LLM Completer for IPython 
+This is an example of Fake LLM Completer for IPython, as
+well as example on how to configure IPython for LLMs.
+
 8.32 – this is provisional and may change.
 
 To test this you can run the following command from the root of IPython 
 directory:
 
     $ ipython --TerminalInteractiveShell.llm_provider_class=examples.auto_suggest_llm.ExampleCompletionProvider
 
-Or you can set the value in your config file
+Or you can set the value in your config file, which also allows you to set a
+keyboard shortcut::
+
+    c.TerminalInteractiveShell.llm_provider_class = "examples.auto_suggest_llm.ExampleCompletionProvider"
+    c.TerminalInteractiveShell.shortcuts = [
+        {
+            "new_keys": ["c-q"],
+            "command": "IPython:auto_suggest.llm_autosuggestion",
+            "new_filter": "navigable_suggestions & default_buffer_focused",
+            "create": True,
+        },
+    ]
+
 
-    c.TerminalInteractiveShell.llm_provider_class="fully.qualified.name.ToYourCompleter"
+You can use the following configuration option to::
 
-And at runtime bing for example `ctrl-q` to triger autosugges:
+    c.TerminalInteractiveShell.llm_constructor_kwargs = {"model_id": "mymodel"}
+
+
+For convenience and testing you can bind a  shortcut at runtime::
 
     In [1]: from examples.auto_suggest_llm import setup_shortcut
        ...: setup_shortcut('c-q')
 
-
 """
 
 import asyncio