Update documentation (#6)

* docs: refactor * docs: links * docs: lint * docs: lint * lint * docs: toc
datalayer · Dec 15, 2024 · 2a11a22 · 2a11a22
1 parent d4ad43c
commit 2a11a22
Show file tree

Hide file tree

Showing 30 changed files with 224 additions and 171 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
 
-# 🪐 🤖 Jupyter AI Agent
+# 🪐 ✨ Jupyter AI Agent
 
 [![Github Actions Status](https://github.com/datalayer/jupyter-ai-agent/workflows/Build/badge.svg)](https://github.com/datalayer/jupyter-ai-agent/actions/workflows/build.yml)
 [![PyPI - Version](https://img.shields.io/pypi/v/jupyter-ai-agent)](https://pypi.org/project/jupyter-ai-agent)
@@ -41,41 +41,25 @@ This powerful functionality is made possible through [jupyter-nbmodel-client](ht
 > jupyter-nbmodel-client and jupyter-kernel-client are experimental and under active development.
 > Unexpected behavior such as ["Panic Exception"](https://github.com/datalayer/jupyter-nbmodel-client/issues/12) may occur, due to potential issue generated by 3rd party projects.
 
-## Concepts
-
-**Deployment Modes**
-
-- `In-Kernel`: When installed in the kernels, the agent can be requested directly. This is not the recommended way and should be used only for development purposes.
-- `Out-Kernel Stateless`: A CLI for example, with that option it is not possible to leverage the `agent memory`, meaning that the agent is stateless and does not remember previous interactions.
-- `Out-Kernel Stateful`: A separated process that is requested via e.g. REST endpoints, being able to leverage the `agent memory` features.
-
-**Interaction Modes**
-
-- `Ask`.
-- `Listen`.
-
-**Available Agents**
-
-- `Prompt`.
-- `ExplainError`.
-
-**Model Providers**
-
-Jupyter AI Agent currently supports models from Azure OpenAI, read the [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai) to get the needed credentials.
-
-**Build your own agent**
+## Usage
 
-TBD
+This library is documented on https://jupyter-ai-agent.datalayer.tech.
 
-## Usage
+We put here a quick example for a Out-Kernel Stateless Agent helping your JupyterLab session.
 
 To install Jupyter AI Agent, run the following command.
 
 ```bash
 pip install jupyter_ai_agent
 ```
 
-### Out-Kernel Stateless with JupyterLab
+Or clone this repository and install it from source.
+
+```bash
+git clone https://github.com/datalayer/jupyter-ai-agent
+cd jupyter-ai-agent
+pip install -e .
+```
 
 The Jupyter AI Agent can directly interact with JupyterLab and the modifications made by the Jupyter AI Agent can be seen in real-time thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html). Make sure you have JupyterLab installed with the Collaboration extension.
 
@@ -89,7 +73,7 @@ Start JupyterLab, setting a `port` and a `token` to be reused by the agent, and
 jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN
 ```
 
-Make sure you have a `.env` file with the following variables.
+Read the [Azure Documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai) to get the needed credentials and make sure you define them in the following `.env` file.
 
 ```bash
 cat << EOF >>.env
@@ -110,6 +94,7 @@ jupyter-ai-agent prompt \
   --path test.ipynb \
   --input "Create a matplotlib example"
 ```
+
 ![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-prompt-demo-terminal.gif)
 
 ```bash

diff --git a/docs/docs/_category_.yaml b/docs/docs/_category_.yaml
@@ -1,2 +1,2 @@
 label: "Overview"
-position: 0
+position: 1
diff --git a/docs/docs/agents/_category_.yaml b/docs/docs/agents/_category_.yaml
@@ -1,2 +1,2 @@
 label: "Agents"
-position: 2
+position: 3
diff --git a/...gents/explain_error_agent/_category_.yaml → ...docs/agents/explain_error/_category_.yaml b/...gents/explain_error_agent/_category_.yaml → ...docs/agents/explain_error/_category_.yaml
diff --git a/...docs/agents/explain_error_agent/index.mdx → docs/docs/agents/explain_error/index.mdx b/...docs/agents/explain_error_agent/index.mdx → docs/docs/agents/explain_error/index.mdx
@@ -1,18 +1,23 @@
 # Explain Error Agent
 
-The Explain Error Agent explains the first error encountered in a notebook. It leverages AI models to explain the error in the code cell, providing insights into the error and potential solutions by adding new cells.
+The Explain Error Agent explains the first error encountered in a notebook. It leverages AI models to explain the error in the code cell, providing insights into the error and potential solutions by adding new cells. This is a great Agent to support the following use cases:
 
-Use Case Examples:
 - Error Explanation: Explain the error encountered in the code cell.
 - Error Resolution: Provide potential solutions to resolve the error.
 
 ![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-explainerror-demo-terminal.gif)
 
-Refer to [usage instructions](/docs/interactions) to get started with the Explain Error Agent.
+```bash
+jupyter-ai-agent explain-error \
+  --url http://localhost:8888 \
+  --token MY_TOKEN \
+  --azure-ai-deployment-name gpt-40-mini \
+  --path test.ipynb
+```
 
 ## Parameters
 
 - `--url`: JupyterLab URL.
 - `--token`: JupyterLab token.
 - `--azure-ai-deployment-name`: Azure AI model deployment name.
-- `--path`: Notebook to modify path.
+- `--path`: Notebook to modify path.
diff --git a/docs/docs/agents/index.mdx b/docs/docs/agents/index.mdx
@@ -1,13 +1,21 @@
+import DocCardList from '@theme/DocCardList';
+
 # Agents
 
-Jupyter AI Agent currently provides two agents: `Prompt Agent` and `Explain Error Agent`.
+Make sure the you understand the [**Deployment Modes**](/docs/deployments) referring to where the agent is running, and the [**Interactions Modes**](/docs/interactions) referring to how the agent is used.
+
+Jupyter AI Agent currently provides the following agents.
+
+<DocCardList />
+
+## Create your own Agent
+
+More Jupyter AI Agent like `Code Refactor Agent`, `Documentation Agent`... can be created by extending the base class.
 
 :::info
-[LangChain Agent Framework](https://python.langchain.com/v0.1/docs/modules/agents/how_to/custom_agent/) is used to manage the interactions between the AI model and the tools.
-:::
 
-More Jupyter AI Agent like `Code Refactor Agent`, `Documentation Agent`, ... can be created by extending the base class.
+[LangChain Agent Framework](https://python.langchain.com/v0.1/docs/modules/agents/how_to/custom_agent/) is used to manage the interactions between the AI model and the tools.
 
-:::note
 🚧 A guide to create custom agent is under construction and will be available soon.
-:::
+
+:::
diff --git a/.../docs/agents/prompt_agent/_category_.yaml → docs/docs/agents/prompt/_category_.yaml b/.../docs/agents/prompt_agent/_category_.yaml → docs/docs/agents/prompt/_category_.yaml
diff --git a/docs/docs/agents/prompt_agent/index.mdx → docs/docs/agents/prompt/index.mdx b/docs/docs/agents/prompt_agent/index.mdx → docs/docs/agents/prompt/index.mdx
@@ -1,14 +1,22 @@
 # Prompt Agent
 
-The Prompt Agent generates code cells based on natural language input. It leverages AI models to generate code, add new cells, and modify the notebook content.
+The Prompt Agent generates code cells based on natural language input. It leverages AI models to generate code, add new cells, and modify the notebook content. This is a great Agent to support the following use cases:
 
-Use Case Examples: 
 - Code Generation: Generate cells code based on natural language input.
 - Notebook Modification: Add new cells based on existing one.
 
 ![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-prompt-demo-terminal.gif)
 
-Refer to [usage instructions](/docs/interactions) to get started with the Prompt Agent.
+To use the Jupyter AI Agent, an easy way is to launch a CLI (update the Azure deployment based on your setup).
+
+```bash
+jupyter-ai-agent prompt \
+  --url http://localhost:8888 \
+  --token MY_TOKEN \
+  --azure-ai-deployment-name gpt-40-mini \
+  --path test.ipynb \
+  --input "Create a matplotlib example"
+```
 
 ## Parameters
 

diff --git a/docs/docs/deployments/_category_.yaml b/docs/docs/deployments/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Deployments"
+position: 5
diff --git a/docs/docs/deployments/in-kernel/_category_.yaml b/docs/docs/deployments/in-kernel/_category_.yaml
@@ -0,0 +1,2 @@
+label: "In Kernel"
+position: 1
diff --git a/docs/docs/deployments/in-kernel/index.mdx b/docs/docs/deployments/in-kernel/index.mdx
@@ -0,0 +1,29 @@
+# In Kernel
+
+When installed in a Jupyter Kernel, the Agent can be requested directly.
+
+:::warning
+
+This is not the recommended way and should be used only for development purposes.
+
+:::
+
+To install Jupyter AI Agent, run the following command.
+
+```bash
+pip install jupyter_ai_agent
+```
+
+The Jupyter AI Agent can directly interact with JupyterLab and the modifications made by the Jupyter AI Agent can be seen in real-time thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html). 
+
+Make sure you have JupyterLab installed with the Collaboration extension.
+
+```bash
+pip install jupyterlab jupyter-collaboration ipykernel
+```
+
+Start JupyterLab, setting a `port` and a `token` to be reused by the agent, and create a notebook `test.ipynb`.
+
+```bash
+jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN
+```
diff --git a/docs/docs/deployments/index.mdx b/docs/docs/deployments/index.mdx
@@ -0,0 +1,11 @@
+import DocCardList from '@theme/DocCardList';
+
+# Deployment
+
+The **Deployment Modes** refer to where the agent is running as well as it capabilities.
+
+- `In-Kernel` - When installed in the Jupyter Kernel, the Agent can be requested directly. This is not the recommended way and should be used only for development purposes.
+- `Out-Kernel Stateless` - The Agent can be requested thourh CLI for example. In a Stateless it is not possible to leverage the `Agent Memory` features, meaning that the agent is stateless and does not remember previous interactions.
+- `Out-Kernel Stateful` - A separated process that is requested via e.g. REST endpoints, being able to leverage the `Agent Memory` features.
+
+<DocCardList />
diff --git a/docs/docs/deployments/out-kernel-stateful/_category_.yaml b/docs/docs/deployments/out-kernel-stateful/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Out Kernel Stateful"
+position: 3
diff --git a/docs/docs/deployments/out-kernel-stateful/index.mdx b/docs/docs/deployments/out-kernel-stateful/index.mdx
@@ -0,0 +1,3 @@
+# Out Kernel Stateful
+
+A separated process that is requested via e.g. REST endpoints, being able to leverage the `Agent Memory` features.
diff --git a/docs/docs/deployments/out-kernel-stateless/_category_.yaml b/docs/docs/deployments/out-kernel-stateless/_category_.yaml
@@ -0,0 +1,2 @@
+label: "Out Kernel Stateless"
+position: 2
diff --git a/docs/docs/deployments/out-kernel-stateless/index.mdx b/docs/docs/deployments/out-kernel-stateless/index.mdx
@@ -0,0 +1,3 @@
+# Out Kernel Stateless
+
+The Agent can be requested thourh CLI for example. In a Stateless it is not possible to leverage the `Agent Memory` features, meaning that the agent is stateless and does not remember previous interactions.
diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx
@@ -1,25 +1,34 @@
+---
+sidebar_position: 1
+---
+
 # Overview
 
-Jupyter AI Agent is a flexible and powerful framework for **using and creating AI agents 🤖** to **interact with Jupyter Notebooks 📓**. 
-With intelligent tools like `execute_cell`, `insert_cell`, and others, Jupyter AI Agent transforms your notebooks into an interactive, AI-powered workspace that adapts to your needs! ✨
+**Jupyter AI Agent** is a flexible and powerful solution for using and creating **✨ AI Agents** to interact with **📓 Jupyter Notebooks**  
+with tools like `insert_cell`, `execute_cell`...
+
+:::info
+
+**Jupyter AI Agent** empowers **AI models** to **interact** with and **modify** Jupyter Notebooks.
+
+:::
 
 ![Jupyter AI Agent](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-prompt-demo-terminal.gif)
 
-Jupyter AI Agent empowers **AI models** to **interact** with and **modify Jupyter Notebooks**. The agent is equipped with tools such as adding code cells, inserting markdown cells, executing code, enabling it to modify the notebook comprehensively based on user instructions or by reacting to notebook and kernel events.
+The Agent is equipped with [Tools](/docs/tools) such as adding Code Cells, inserting Markdown Cells, executing Code, enabling it to modify the Notebook comprehensively based on user instructions or by reacting to Notebook and Kernel events.
 
 ## What is an AI Agent?
 
-An artificial intelligence (AI) agent is a system that **autonomously performs tasks** by designing workflows and **using tools**. 
-Beyond processing language, these agents make decisions, solve problems, interact with environments, and execute actions. 
-They are widely used in areas like IT automation, software design, and conversational assistants. 
-Leveraging large language models (LLMs), AI agents process user inputs step-by-step and call external tools as needed to tackle 
+An artificial intelligence (AI) agent is a system that **autonomously performs tasks** by designing workflows and **using tools**.
+
+Beyond processing language, these agents make decisions, solve problems, interact with environments, and execute actions. They are widely used in areas like IT automation, software design, and conversational assistants.
+
+Leveraging Large Manguage Models (LLMs), AI agents process user inputs step-by-step and call external tools as needed to tackle 
 complex tasks effectively.
 
 ## What Makes Jupyter AI Agent Unique?
 
-This agent is **innovative** as it is designed to **operate on the entire notebook**, not just at the cell level, enabling more comprehensive and seamless modifications.
-
-This powerful functionality is made possible through [jupyter-nbmodel-client](https://github.com/datalayer/jupyter-nbmodel-client) and [jupyter-kernel-client](https://github.com/datalayer/jupyter-kernel-client), enabling interaction with Jupyter Notebooks and Kernels.
+This agent is **innovative** as it is designed to **operate on the entire Notebook**, not just at the Cell level, enabling more comprehensive and seamless modifications.
 
 ```
 Jupyter AI Agent <-----------> JupyterLab
@@ -32,53 +41,22 @@ JNC + JKC
 - JKC https://github.com/datalayer/jupyter-kernel-client
 ```
 
-:::warning
-
-jupyter-nbmodel-client and jupyter-kernel-client are experimental and under active development.
-Unexpected behavior such as ["Panic Exception"](https://github.com/datalayer/jupyter-nbmodel-client/issues/12) may occur, due to potential issue generated by 3rd party projects.
-
-:::
+This powerful functionality is made possible through the Jupyter [NbModel](https://github.com/datalayer/jupyter-nbmodel-client) and [Kernel](https://github.com/datalayer/jupyter-kernel-client) clients, enabling interactions with both Jupyter Notebooks and Kernels.
 
 ## Key Features
 
 - **Dynamic Notebook Interaction**: Jupyter AI agents can add, edit, and execute cells dynamically based on user instructions or notebook events.
-- **Remote Agent Execution**: The agent can be executed independently, remotely on a different kernel than the one used by the notebook of interest to separate the agent execution from the notebook execution. Refer to "Deployment modes" in [Usage](/docs/interactions) for more details.
-- **Event-Based Modifications**: Can react to kernel and notebook changes in real time, enabling modifications without user intervention. Refer to "Interaction modes" in [Usage](/docs/interactions) for more details.
+- **Remote Agent Execution**: The agent can be executed independently, remotely on a different kernel than the one used by the notebook of interest to separate the agent execution from the notebook execution. Refer to the [Deployment Modes](/docs/deployments) for more details.
+- **Event-Based Modifications**: Can react to Kernel and Notebook changes in real time, enabling modifications without user intervention. Refer to the [Interaction Modes](/docs/interactions) for more details.
 - **Advanced Jupyter Tools**: Includes current capabilities like inserting markdown or code cells, running code.
-- **Integration with RTC**: Real-Time Collaboration ensures seamless agent modifications in JupyterLab.
+- **Built on RTC**: Real-Time Collaboration ensures seamless commmunication across all the actors.
 
-## Example Use Cases
-
-- **Automated Data Analysi**s: Generate and execute Python scripts to analyze data, create visualizations, or preprocess datasets.
-- **Error Debugging**: Identify and explain errors in code execution, with actionable suggestions to fix them.
-- **Notebook Refactoring**: Automatically optimize code structure, improve readability, or add detailed documentation.
-
-Discover the current agents available in the Jupyter AI Agent framework on the [Agents](/docs/agents/) page.
-
-## Tools
-
-### Current Tools
-
-- **Add Code Cell**: Dynamically add new code cells to the notebook.
-- **Execute Code Cell**: Run code within specific cells, providing instant results.
-- **Add Markdown Cell**: Insert markdown cells to structure and document notebooks effectively.
-
-### Upcoming Tools (Ideas)
+## Feedback and Contributions
 
-- **Modify Code Cell**: Edit existing code cells to fix errors or improve code quality.
-- **Add Code Cell at a specific position**: Insert code cells at a specific location in the notebook.
-- **Add Markdown Cell at a specific position**: Insert markdown cells at a specific location in the notebook.
-- ...
+:::success
 
-## Potential Directions
+**We value your feedback!**
 
-- **Creating a UI for Chatting with the Agent in JupyterLab**: Developing an interactive interface within JupyterLab 
-where users can directly communicate with the Jupyter AI Agent, issuing commands and receiving real-time responses 
-in a conversational format.
-- **Building a Code Refactoring Agent**: Developing an agent that can automatically refactor code in Jupyter Notebooks,
-improving code quality, readability, and maintainability.
-- ...
+If you encounter any issues or have suggestions for improvement, please open a [GitHub issue](https://github.com/datalayer/jupyter-ai-agent/issues).
 
-## Feedback and Contributions
-
-We value your feedback! If you encounter any issues or have suggestions for improvement, please open a [GitHub issue](https://github.com/datalayer/jupyter-ai-agent/issues).
+:::
diff --git a/docs/docs/install/_category_.yaml b/docs/docs/install/_category_.yaml
diff --git a/docs/docs/install/index.mdx b/docs/docs/install/index.mdx
diff --git a/docs/docs/interactions/_category_.yaml b/docs/docs/interactions/_category_.yaml
@@ -1,2 +1,2 @@
 label: "Interactions"
-position: 2
+position: 5
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Out Kernel Stateful

		A separated process that is requested via e.g. REST endpoints, being able to leverage the `Agent Memory` features.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Out Kernel Stateless

		The Agent can be requested thourh CLI for example. In a Stateless it is not possible to leverage the `Agent Memory` features, meaning that the agent is stateless and does not remember previous interactions.