AI Agentic Data Analysis (Jupyter + SSH Service)
=================================================
Data collected in ARIM-mdx Nextcloud can be analyzed through ARIM-mdx Jupyter. It also supports long-running autonomous execution by AI agents.
ARIM-mdx Jupyter provides:

- `Jupyter Lab <https://docs.jupyter.org/en/latest/>`_ : Interactive data analysis, e.g., visualization
- `VSCode <https://code.visualstudio.com/>`_ : Software development
- `MateriApps LIVE! <https://cmsi.github.io/MateriAppsLive/>`_ (Remote Desktop): All-in-one software package for materials sciecne

Jupyter Initial Setup
-----------------------
Jupyter-Nextcloud integration is required as initial setup.
Please refer to :ref:`jupyter-activation` for details.

Logging into Jupyter
---------------------
| Log in to ARIM-mdx Jupyter service (https://jupyter.arim.mdx.jp).

.. image:: _static/login-6.png
   :alt: login-6
   :align: center
   :width: 400px

|

Starting Jupyter Server
------------------------
| Select a server and click Start to launch. Below are the server types for different purposes.

.. image:: _static/jupyter-spec.png
   :alt: jupyter-spec
   :align: center
   :width: 500px

|

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Type
     - Description
   * - Jupyter / VSCode / Remote Desktop
     - Environment including Remote Desktop (`MateriApps LIVE! <https://cmsi.github.io/MateriAppsLive/>`_)
   * - Jupyter / VSCode Only
     - Environment with only JupyterLab and VSCode

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Type
     - Specifications
     - Description
   * - Default
     - 16 vCPUs, 24GB memory
     - Standard computing environment
   * - High Spec
     - 32 vCPUs, 48GB memory
     - High-performance PC equivalent
   * - Max Spec
     - 64 vCPUs, 96GB memory
     - High-performance server equivalent

.. note::
   Starting Jupyter may take up to several minutes.

Starting Jupyter VSCode
------------------------
| Select **VSCode** from the Launcher to start.

.. image:: _static/vscode.png
   :alt: vscode
   :align: center
   :width: 500px

|

| VSCode will launch.

.. image:: _static/vscode-run.png
   :alt: vscode-run
   :align: center
   :width: 500px

|

Starting MateriApps LIVE! on Jupyter Remote Desktop
----------------------------------------------------
| Select **Remote Desktop** from the Launcher to start.

.. image:: _static/vscode.png
   :alt: vscode
   :align: center
   :width: 500px

|

| MateriApps LIVE! on Jupyter Remote Desktop will launch.

.. image:: _static/remote-desktop.png
   :alt: remote-desktop
   :align: center
   :width: 500px

|

SSH Access
-----------
| ARIM-mdx Jupyter also accepts direct SSH connections.

.. note::
   The web interface at `https://jupyter.arim.mdx.jp <https://jupyter.arim.mdx.jp>`_
   remains the primary way to use ARIM-mdx Jupyter. SSH is an optional additional path.

Prerequisites for SSH
----------------------
1. Complete the Jupyter initial setup (see :ref:`jupyter-activation`).
2. Start a Jupyter server from the web UI — the SSH endpoint is tied to your running Jupyter server.
3. Generate an SSH keypair on your local machine if you do not already have one:

   .. code-block:: bash

      ssh-keygen -t ed25519

4. Append the **public key** (``~/.ssh/id_ed25519.pub``) to ``~/.ssh/authorized_keys`` on the Jupyter server:

   .. code-block:: bash

      echo "<your public key>" >> ~/.ssh/authorized_keys

SSH Connection Information
---------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Item
     - Value
   * - Host
     - ``<TODO: hostname, e.g. ssh.jupyter.arim.mdx.jp>``
   * - Port
     - ``<TODO: port>``
   * - Username
     - ``<TODO: username format>``
   * - Authentication
     - SSH public key (password authentication is disabled)

Connecting with VSCode Remote-SSH
----------------------------------
1. Install the `Remote - SSH <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh>`_ extension in VSCode.
2. Add the following entry to your local ``~/.ssh/config`` (replace the ``<TODO: ...>`` values):

   .. code-block:: text

      Host arim-jupyter
          HostName <TODO: hostname>
          Port <TODO: port>
          User <TODO: username>
          IdentityFile ~/.ssh/id_ed25519

3. Open the Command Palette in VSCode and run **Remote-SSH: Connect to Host...**, then select ``arim-jupyter``.

.. TODO: add screenshot _static/ssh-vscode.png once the flow is demonstrable

Connecting from Terminal
-------------------------
Use a standard ``ssh`` command:

.. code-block:: bash

   ssh <TODO: username>@<TODO: hostname> -p <TODO: port>

.. TODO: add screenshot _static/ssh-terminal.png once the flow is demonstrable

File Transfer (SFTP / scp)
---------------------------
Upload a local file to your Jupyter home directory:

.. code-block:: bash

   scp -P <TODO: port> ./local-file.csv <TODO: username>@<TODO: hostname>:~/

Download a file from your Jupyter home directory:

.. code-block:: bash

   scp -P <TODO: port> <TODO: username>@<TODO: hostname>:~/output.csv .

Interactive SFTP session:

.. code-block:: bash

   sftp -P <TODO: port> <TODO: username>@<TODO: hostname>

Files transferred here are visible from inside the Jupyter server at the same path.