Skip to main content

How to use Jupyter AI

This guide explains how to use Jupyter AI, manage Notebook Workspaces, and configure Notebook Processes with multiple outputs in the Syntasa platform. These capabilities enable AI-assisted development, structured collaboration, and scalable notebook execution within data pipelines.

Syntasa integrates Jupyter AI at the platform level, allowing users to leverage generative AI features without managing individual model configurations or API keys. For background on Jupyter AI capabilities and supported features, refer to the official Jupyter AI documentation .

Using Jupyter AI in Syntasa​

Syntasa integrates the jupyter-ai plugin directly into its notebook environment, enabling AI-assisted coding, explanation, and troubleshooting through conversational interface.

Accessing the AI Chatbot​

The conversational AI interface is available from the JupyterLab sidebar.

Steps:

  1. Launch a Notebook Workspace or open an existing notebook.

  2. Locate and click the Chat icon in the left-hand sidebar.

  3. Interact with the AI using natural language to:

    • Generate code
    • Explain existing logic
    • Debug errors
    • Optimize notebook workflows

The chatbot is context-aware and can reference the currently active notebook cells.

Managing Notebook Workspaces​

Notebook Workspaces provide isolated, persistent environments that support organization, collaboration, and controlled access to notebooks.

Creating and Editing Workspaces​

Steps to Create a Workspace:

  1. Navigate to Notebook Workspaces from the main menu.
  2. Click the Add (+) button.

Workspace Fields:

  • Name – Unique workspace name

  • Key – Auto-generated unique identifier

  • Description – Optional details

  • Sharing

    • Public – Accessible to other users
    • Private – Restricted to the owner

To modify an existing workspace, click the Edit icon on the workspace card.

Note: The Default Workspace cannot be edited or deleted.

Launching a Workspace​

Click a workspace card to launch the JupyterLab environment scoped to that workspace.

  • The environment is persistent
  • Shared users access the same workspace context
  • AI features are automatically available within the workspace

Notebook Process with Multiple Outputs​

The Notebook Process node allows notebooks to be executed as part of a pipeline and supports defining multiple outputs from a single notebook run.

Configuring the Notebook Process​

  1. Drag a Notebook Process node onto the pipeline canvas.

  2. In the General tab:

    • Select Workspace
    • Select Notebook

Syntasa automatically detects:

  • Notebook language
  • Runtime and execution settings

Adding Multiple Outputs​

A single notebook can produce multiple outputs by connecting Notebook Output nodes.

Steps:

  1. Drag a Notebook Output node from the palette.
  2. Connect it to the output port of the Notebook Process node.
  3. Repeat for each required output.

Notebook Output Configuration:

  • Display Name – Used as the identifier within the notebook code

Writing Data to Outputs in the Notebook​

When executed as part of a job, Syntasa passes output locations as parameters to the notebook runtime.

  • Output nodes are converted into environment variables
  • The @ prefix is removed when passed to the kernel

Example (Python):

import os

output_path = os.environ.get('NotebookOutput1')
df.write.mode("overwrite").parquet(output_path)

This approach allows a single notebook to write multiple datasets to different destinations.

Troubleshooting and Best Practices​

Common Issues and Tips​

  • Notebook Missing

    • If a previously selected notebook is no longer available, the UI displays a hint with the original notebook name.

  • Runtime Status

    • Notebook runtime status (e.g., RUNNING, STARTING, STOPPED) is displayed in the notebook title bar for real-time monitoring.

  • Workspace Deletion Restrictions

    • A workspace cannot be deleted if it contains active notebooks.
    • Move or delete notebooks before attempting workspace deletion.

  • Default Workspace

    • Every user has access to the Default Workspace, which serves as the primary shared notebook area.

Summary​

By combining Jupyter AI, Notebook Workspaces, and Notebook Processes, Syntasa enables:

  • AI-assisted notebook development
  • Structured collaboration through shared workspaces
  • Scalable pipeline execution with multi-output notebooks

These capabilities streamline development workflows while maintaining centralized governance and configuration.