Upgraded ray version, installation instructions that work with python 3.9 and 3.10

README.md

@@ -14,23 +14,45 @@ Documentation is available on [ReadTheDocs](https://jupyter-ai.readthedocs.io/en
 
 ## Installation
 
+You can use `conda` or `pip` to install Jupyter AI. If you're using macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), we strongly recommend using `conda`.
+
+Because of Ray's incompatibility with Python 3.11, you must use Python 3.7, 3.8, 3.9, or 3.10 with Jupyter AI. The instructions below presume that you are using Python 3.10.
+
+Before you can use Jupyter AI, you will need to install any packages and set environment variables with API keys for the model providers that you will use. See [our documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html) for details about what you'll need.
+
+### With pip
+
 If you want to install both the `%%ai` magic and the JupyterLab extension, you can run:
 
     $ pip install jupyter_ai
 
-If you are not using JupyterLab and only want to install the Jupyter AI `%%ai` magic you can run:
+If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, you can run:
 
     $ pip install jupyter_ai_magics
 
-The `%%ai` magic works anywhere the IPython kernel runs (JupyterLab, Jupyter Notebook, Google Colab, VSCode, etc.).
 
-To complete your installation, you will also need to install any packages and API keys for the model providers
-you wish to use. See [our documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html) for details.
+### With conda
+
+First, install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) and create an environment that uses Python 3.10:
+
+    $ conda create -n jupyter-ai python=3.10
+    $ conda activate jupyter-ai
+    $ pip install jupyter_ai
+
+If you are using an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), you need to uninstall the `pip` provided version of `grpcio` and install the version provided by `conda` instead.
+
+    $ pip uninstall grpcio; conda install grpcio 
+
+If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, skip the `pip install jupyter_ai` step above, and instead, run:
+
+    $ pip install jupyter_ai_magics
+
 
 ## The `%%ai` magic command
 
-Once you installed the `%%ai` magic, you can enable it in any notebook or the IPython shell by running:
+The `%%ai` magic works anywhere the IPython kernel runs (JupyterLab, Jupyter Notebook, Google Colab, VSCode, etc.).
 
+Once you have installed the `%%ai` magic, you can enable it in any notebook or the IPython shell by running:
     %load_ext jupyter_ai_magics
 
 Or

docs/source/contributors/index.md

@@ -4,22 +4,14 @@ This page is intended for people interested in building new or modified function
 
 ## Prerequisites
 
-You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.10, including recent Windows, macOS, and Linux versions. Python 3.11 is **not supported** due
-to incompatibility with the [ray](https://pypi.org/project/ray/) library that we use.
-If you are using an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), and you see an error when using
-Python 3.10, try installing version 3.9 instead.
+You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.10, including recent Windows, macOS, and Linux versions.
 
-If you use `conda`, you can install Python 3.10 in your environment by running:
-
-```
-conda install python=3.10
-```
+:::{important}
+:name: python-3-11-not-supported
+Because the [ray](https://pypi.org/project/ray/) library that Jupyter AI uses is not compatible with Python 3.11, please use a supported version of Python up to and including Python 3.10.
+:::
 
-To use the `jupyter_ai` package in JupyterLab, as the development environment below does, you will need a currently-maintained version of JupyterLab 3. We do not yet support JupyterLab 4. If you use `conda`, you can install JupyterLab in your environment by running:
-
-```
-conda install jupyterlab
-```
+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.
 
@@ -29,46 +21,45 @@ Due to a compatibility issue with Webpack, Node.js 18.15.0 does not work with Ju
 :::
 
 ## Development install
-
-First, install the Hatch CLI, which installs the Hatchling build backend automatically.
+After you have installed the prerequisites, create a new conda environment and activate it. 
 
 ```
-pip install hatch
+conda create -n jupyter-ai python=3.10
+conda activate jupyter-ai
 ```
 
-Then, enter the default hatch environment, which automatically installs all dependencies and executes development setup when entering for the first time. This command must be run from the root of the monorepo (`<jupyter-ai-top>`).
+This command must be run from the root of the monorepo (`<jupyter-ai-top>`).
 
 ```
+# Move to the root of the repo package
 cd <jupyter-ai-top>
-hatch shell
+
+# Installs all the dependencies and sets up the dev environment
+./scripts/install.sh
 ```
 
-Set up your development environment and start the server:
+Start and launch JupyterLab in your default browser:
 
 ```
 jlpm dev
 ```
 
-Finally, in a separate shell, enter the hatch environment and build the project after making any changes.
+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 <jupyter-ai-top>
-hatch shell
+conda activate jupyter-ai
 jlpm build
 ```
 
-To exit the hatch environment, on a blank command prompt, run `exit` or press `Ctrl+D`.
-
-If installation fails for any reason, you will have to first uninstall the hatch environment and then test your fix by reinstalling.
-
-To change what Jupyter AI packages are installed in your Hatch environment, use the `dev-uninstall` script:
+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 Hatch environment, use the `dev-install` script:
+To reinstall Jupyter AI packages back into your dev environment, use the `dev-install` script:
 
 ```
 # installs all Jupyter AI packages
@@ -92,8 +83,9 @@ refresh your browser tab.
 
 ## Development uninstall
 
-To uninstall your Jupyter AI development environment, remove the Hatch environment:
+To uninstall your Jupyter AI development environment, deactivate and remove the Conda environment:
 
 ```
-hatch env remove default
+conda deactivate
+conda env remove -n jupyter-ai
 ```

docs/source/users/index.md

@@ -7,8 +7,12 @@ please see our {doc}`contributor's guide </contributors/index>`.
 
 ## Prerequisites
 
-You will need a supported version of Python up to and including 3.10. Python 3.11 is **not supported** due
-to incompatibility with the [ray](https://pypi.org/project/ray/) library that we use.
+You can run Jupyter AI on any system that can run a supported Python version up to and including 3.10, including recent Windows, macOS, and Linux versions.
+
+:::{important}
+:name: python-3-11-not-supported
+Because the [ray](https://pypi.org/project/ray/) library that Jupyter AI uses is not compatible with Python 3.11, please use a supported version of Python up to and including Python 3.10.
+:::
 
 If you use `conda`, you can install Python 3.10 in your environment by running:
 
@@ -63,13 +67,36 @@ provider's pricing information before submitting requests via Jupyter AI.
 
 ## Installing
 
-To use Jupyter AI, you will need to have JupyterLab ≥ 3.5 (*not* JupyterLab 4) installed.
+You can use `conda` or `pip` to install Jupyter AI. If you're using macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), we strongly recommend using `conda`.
+
+Because of Ray's incompatibility with Python 3.11, you must use Python 3.9, or 3.10 with Jupyter AI. The instructions below presume that you are using Python 3.10.
+
+Before you can use Jupyter AI, you will need to install any packages and set environment variables with API keys for the model providers that you will use. See [our documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html) for details about what you'll need.
+
+### With pip
 
 If you want to install both the `%%ai` magic and the JupyterLab extension, you can run:
 
     $ pip install jupyter_ai
 
-If you are not using JupyterLab and only want to install the Jupyter AI `%%ai` magic you can run:
+If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, you can run:
+
+    $ pip install jupyter_ai_magics
+
+
+### With conda
+
+First, install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) and create an environment that uses Python 3.10:
+
+    $ conda create -n jupyter-ai python=3.10
+    $ conda activate jupyter-ai
+    $ pip install jupyter_ai
+
+If you are using an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), you need to uninstall the `pip` provided version of `grpcio` and install the version provided by `conda` instead.
+
+    $ pip uninstall grpcio; conda install grpcio 
+
+If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, you can run:
 
     $ pip install jupyter_ai_magics
 
@@ -81,7 +108,6 @@ You can check that the Jupyter AI server extension is enabled by running:
 
 To verify that the frontend extension is installed, run:
 
-
     $ jupyter labextension list
 
 To remove the extension, run:

packages/jupyter-ai/README.md

@@ -11,21 +11,35 @@ for the frontend extension.
 
 - JupyterLab >= 3.5 (not JupyterLab 4)
 
-## Install
+## Installation
 
-To install the extension, execute:
+You can use `conda` or `pip` to install Jupyter AI. If you're using macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), we strongly recommend using `conda`.
 
-```bash
-pip install jupyter_ai
-```
+Because of Ray's incompatibility with Python 3.11, you must use Python 3.9, or 3.10 with Jupyter AI. The instructions below presume that you are using Python 3.10.
+
+Before you can use Jupyter AI, you will need to install any packages and set environment variables with API keys for the model providers that you will use. See [our documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html) for details about what you'll need.
+
+### With pip
+
+    $ pip install jupyter_ai
+
+### With conda
+
+First, install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) and create an environment that uses Python 3.10:
+
+    $ conda create -n jupyter-ai python=3.10
+    $ conda activate jupyter-ai
+    $ pip install jupyter_ai
+
+If you are using an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), you need to uninstall the `pip` provided version of `grpcio` and install the version provided by `conda` instead.
+
+    $ pip uninstall grpcio; conda install grpcio 
 
 ## Uninstall
 
 To remove the extension, execute:
 
-```bash
-pip uninstall jupyter_ai
-```
+    $ pip uninstall jupyter_ai
 
 ## Usage with GPT-3
 

packages/jupyter-ai/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "langchain~=0.0.144",
     "tiktoken", # required for OpenAIEmbeddings
     "jupyter_ai_magics",
-    "ray==2.2.0", # latest ray version 2.3.0 requires grpcio installation from conda
+    "ray~=2.4.0", # Requires grpcio installation from conda
     "faiss-cpu", # Not distributed by official repo
     "wcmatch",
 ]

pyproject.toml

@@ -18,16 +18,6 @@ content-type = "text/markdown"
 [project.license]
 text = "BSD 3-Clause License"
 
-[tool.hatch.envs.default]
-pre-install-commands = [
-    "pip install jupyterlab~=3.4",
-    "cp playground/config.example.py playground/config.py"
-]
-post-install-commands = [
-    "jlpm install",       # install JS dependencies
-    "jlpm dev-install", # install Python packages locally in editable mode
-]
-
 [tool.hatch.version]
 source = "nodejs"
 path = "package.json"

scripts/install.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+pip install jupyterlab
+cp playground/config.example.py playground/config.py
+jlpm install
+jlpm dev-install
+
+if [[ $(uname -m) == 'arm64' ]]; then
+    pip uninstall grpcio && conda install -y grpcio
+fi