Overhaul v3 developer documentation #1344

dlqqq · 2025-05-22T00:06:35Z

Description

Closes [v3-beta] Document personas API #1343.
Structures the developer documentation to be much more legible.
- Breaks the wall of text into multiple sub-pages.
- Explicitly lists each entry point group used by Jupyter AI & their expected type.
- Includes a "how-to" for each group.
Adds a page on providing entry points from a package. This addresses a very common issue reported by new developers.
Removes outdated documentation from the v3 developer documentation:
- Removes docs on custom slash commands, as they now be managed by personas in v3.
- Removes docs on Pydantic version compatibility, as we do not use Pydantic v1 in JAI v3.
- Removes docs on the JAI module cookiecutter, as it is unclear if we will continue to maintain that for v3.
- Removes docs on the v2 message footer API, as that no longer works with the new jupyterlab_chat frontend.
Adds a documentation page on custom AI personas.

Demo

The new dev docs look much nicer. See demo: https://jupyter-ai--1344.org.readthedocs.build/en/1344/developers/index.html

dlqqq · 2025-05-22T18:20:24Z

@fperez Hey Fernando, this PR adds documentation on defining custom AI personas & providing them to Jupyter AI via entry points. 👍

The Jupyter AI docs have been split into 2 versions: v2 and v3. The docs page defaults to v2 for now, since v3.0.0 isn't released yet. If you have trouble finding these docs after this PR is merged, be sure to switch to the v3 docs site using the pop-up on the bottom-right:

dlqqq · 2025-05-22T18:20:47Z

You can also click the link in the PR description to view the developer documentation right now, before this PR is merged.

krassowski · 2025-05-23T08:53:40Z

docs/source/developers/entry_points_api/model_providers_group.md

+
+## How-to: define custom code completions
+
+Any model provider derived from `BaseProvider` can be used as a completion provider.


This and everything below is roughly duplicated in inline_completions.md. I don't know which copy you intended to keep but just highlighting this with assumption that only one was meant to be included.

Great catch, thanks! I'll look into this when I'm able

srdas · 2025-05-28T16:01:45Z

docs/source/developers/entry_points_api/embeddings_providers_group.md

+```
+
+Jupyter AI uses entry points to discover embedding providers.
+In the `pyproject.toml` file, add your custom embedding provider to the


Mention here that the specific pyproject.toml file is in jupyter-ai-magics.

srdas · 2025-05-28T16:03:03Z

docs/source/developers/entry_points_api/index.md

+The [**entry points API**][entry_points] allows other packages to add custom
+objects to Jupyter AI's backend. Jupyter AI defines a set of **entry point
+groups**. Each entry point group is reserved for a specific type of object, e.g.
+one group may be reserved for personas and another may be reserved for model


What's out convention for personas, do we want to capitalize it to Personas?

srdas · 2025-05-28T16:11:24Z

docs/source/developers/entry_points_api/model_providers_group.md

+
+The `auth_strategy` handles specifying API keys for providers and models.
+The example shows the `EnvAuthStrategy` which takes the API key from the
+environment variable with the name specified in `name` and be provided to the


Awkward sentence, maybe use "it will be" instead of just "be"

srdas · 2025-05-28T16:26:54Z

docs/source/developers/entry_points_api/personas_group.md

+For example, if your Jupyter AI instance has `Jupyternaut` and `MyCustomPersona`
+as 2 AI personas, then each persona will only respond when `@`-mentioned.
+
+- To call `Jupyternaut`, your message must include `@Jupyternaut`.


Would it be better to say that the message should be prefixed by @Jupyternaut?

srdas · 2025-05-28T17:46:00Z

docs/source/developers/entry_points_api/personas_group.md

+`jupyter_ai.personas:BasePersona`. Instructions on defining one are given in the
+next section.
+
+## How-to: define a custom AI persona


Capitalize "Define"

srdas · 2025-05-28T17:46:40Z

docs/source/developers/entry_points_api/personas_group.md

+`process_message()` method.
+
+- `defaults` defines the default settings of the persona. This is mainly used to
+control the name & avatar shown in the Jupyter AI chat.


Replace & with "and"

srdas · 2025-05-28T17:49:50Z

docs/source/developers/entry_points_api/personas_group.md

+by Jupyternaut, you can access that through the `self.config: ConfigManager`
+attribute available to subclasses.
+
+Add & call this method on a persona to access the LangChain runnable used by


Replace & with "and"

srdas · 2025-05-28T17:53:03Z

docs/source/developers/entry_points_api/providing_entry_points.md

+To provide entry points, your custom Python package must use a `pyproject.toml`
+manifest. To provide an existing class as an entry point, fill out the following
+template and add it to the end of your package's
+`pyproject.toml` file.


add to the end of the sentence: "in the jupyter-ai-test folder"

srdas

The docs look really good. Left some comments. Questions:

Will we be moving Personas out from jupyter-ai-test into their own folder under jupyter-ai?
Should Personas and all related files (READMEs, tools, requirements) be in subfolders under a separate folder?

overhaul developer docs for v3

0989587

dlqqq added documentation Improvements or additions to documentation do-not-port Label for PRs that shouldn't be ported to another branch labels May 22, 2025

dlqqq marked this pull request as draft May 22, 2025 00:18

pre-commit

1741e08

dlqqq force-pushed the v3-dev-docs branch from 1f68534 to 1741e08 Compare May 22, 2025 16:28

dlqqq added 4 commits May 22, 2025 10:20

lay out new dev docs page structure

16f74ba

add embedding model providers to EP API

f2c0acc

add personas documentation

3bb3570

pre-commit

356dcd7

dlqqq force-pushed the v3-dev-docs branch from e827deb to 356dcd7 Compare May 22, 2025 17:51

dlqqq changed the title ~~[WIP] Add v3 developer documentation~~ Overhaul v3 developer documentation May 22, 2025

remove duplicate content

b3d1707

dlqqq marked this pull request as ready for review May 22, 2025 17:54

add section on using Jupyternaut's model

db8f5ae

srdas self-assigned this May 22, 2025

krassowski reviewed May 23, 2025

View reviewed changes

srdas reviewed May 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Overhaul v3 developer documentation #1344

Overhaul v3 developer documentation #1344

Uh oh!

dlqqq commented May 22, 2025 •

edited

Loading

Uh oh!

dlqqq commented May 22, 2025

Uh oh!

dlqqq commented May 22, 2025

Uh oh!

krassowski May 23, 2025

Uh oh!

dlqqq May 27, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas May 28, 2025

Uh oh!

srdas left a comment

Uh oh!

Uh oh!


		## How-to: define custom code completions

		Any model provider derived from `BaseProvider` can be used as a completion provider.

Uh oh!

Overhaul v3 developer documentation #1344

Are you sure you want to change the base?

Overhaul v3 developer documentation #1344

Uh oh!

Conversation

dlqqq commented May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Demo

Uh oh!

dlqqq commented May 22, 2025

Uh oh!

dlqqq commented May 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srdas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dlqqq commented May 22, 2025 •

edited

Loading