# Contributors This page is intended for people interested in building new or modified functionality for Jupyter AI. If you would like to build applications that enhance Jupyter AI, please see the {doc}`developer's guide `. ## Design principles Maintainers of Jupyter AI have adopted principles that contributors should also follow. These principles, which build on top of [the Zen of Python](https://peps.python.org/pep-0020/), are intended to earn users' trust by keeping their data under their control. The following list is non-exhaustive; maintainers have discretion to interpret and revise these principles. 1. Jupyter AI is **vendor-agnostic**. Jupyter AI does not discriminate between available models, and gives users a choice of model providers. A feature in Jupyter AI may be specific to one model or model provider if it cannot be used with other models or providers. 2. Jupyter AI **only responds to an explicit prompt**; it does not watch files and it does not send prompts automatically. Any change that watches user files must be opt-in only. 3. Jupyter AI is **transparent** with its chat prompts. The chat interface and magic commands use system messages and prompt templates that are open source, so that users know what gets sent to language models. 4. Jupyter AI is **traceable**; users know when it has been used to generate content. When Jupyter AI generates a notebook, the notebook says that it was generated by Jupyter AI. When a user runs a Jupyter AI magic command in a notebook, output cells say, in their metadata, that they were generated by Jupyter AI. 5. Jupyter AI uses a **human-centered design**. The chat interface should look and feel like chat applications that are generally available. The magic commands should look and work like other IPython magic commands. Settings screens should be used minimally, and wherever they are used, they should be readable and understandable, even for users not fluent in the user interface language. Issues and pull requests that violate the above principles may be declined. If you are unsure about whether your idea is a good fit for Jupyter AI, please [open an issue](https://github.com/jupyterlab/jupyter-ai/issues/new/choose) so that our maintainers can discuss it with you. ## Prerequisites You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.11, including recent Windows, macOS, and Linux versions. Each Jupyter AI major version works with only one major version of JupyterLab. Jupyter AI 1.x supports JupyterLab 3.x, and Jupyter AI 2.x supports JupyterLab 4.x. We highly recommend that you install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to start developing on Jupyter AI, especially if you are developing on macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.). You will need Node.js 18 to use Jupyter AI. Node.js 18.16.0 is known to work. :::{warning} :name: node-18-15 Due to a compatibility issue with Webpack, Node.js 18.15.0 does not work with Jupyter AI. ::: ## Development install After you have installed the prerequisites, create a new conda environment and activate it. ``` conda create -n jupyter-ai -c conda-forge python=3.11 nodejs=20 conda activate jupyter-ai ``` This command must be run from the root of the monorepo (``). ``` # Move to the root of the repo package cd # Installs all the dependencies and sets up the dev environment ./scripts/install.sh ``` Start and launch JupyterLab in your default browser: ``` jlpm dev ``` You can open a new terminal and use that to build and push changes to the repository. Enter the `conda` environment and build the project after making any changes. ``` cd conda activate jupyter-ai jlpm build ``` To change what Jupyter AI packages are installed in your dev environment, use the `dev-uninstall` script: ``` # uninstalls all Jupyter AI packages jlpm dev-uninstall ``` To reinstall Jupyter AI packages back into your dev environment, use the `dev-install` script: ``` # installs all Jupyter AI packages jlpm dev-install ``` To only install/uninstall a subset of Jupyter AI packages, use the `--scope` argument that gets forwarded to Lerna: ``` # installs jupyter_ai_magics and its dependencies jlpm dev-install --scope "@jupyter-ai/magics" ``` ## Making changes while your server is running If you change, add, or remove a **magic command**, after rebuilding, restart the kernel or restart the server. If you make changes to the **user interface** or **lab extension**, run `jlpm build` and then refresh your browser tab. ## Building documentation The `./scripts/install.sh` should automatically install the documentation dependencies. To build the documentation locally, run ``` cd docs/ make html ``` and open `file:///docs/build/html/index.html`, where `` is the absolute path of the Jupyter AI monorepo on your local filesystem. It is helpful to bookmark this path in your browser of choice to easily view your local documentation build. After making any changes, make sure to rebuild the documentation locally via `make html`, and then refresh your browser to verify the changes visually. ## Development uninstall To uninstall your Jupyter AI development environment, deactivate and remove the Conda environment: ``` conda deactivate conda env remove -n jupyter-ai ``` ## Testing ### Integration / E2E tests This extension uses Playwright for the integration / E2E tests (user-level tests). More precisely, the JupyterLab helper [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to test the extension in JupyterLab. Install test dependencies (needed only once): ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm install jlpm playwright install ``` Tests involve snapshot comparisons against a reference snapshots generated by the Github CI. If you are using an OS other than Linux, you will need to generate local snapshots before running the tests locally for the first time. To do this, execute the command: ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm test:update ``` To execute tests, run: ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm test ``` You can find more information in the [ui-tests](https://github.com/jupyterlab/jupyter-ai/tree/main/packages/jupyter-ai/ui-tests) README.