Troubleshooting
===============


A - Prerequisite:
-----------------

Run agilab.sh to install and then try to run your xxx-project.
Each Agilab API call should be set with verbose mode >= 3. In particular, when debugging with a Dask worker,
it will create a file (~/xxx-project_trace.txt) that shows what happened in during the worker build execution.

B - Pycharm Run/Debug configurations:
-------------------------------------

These scripts are provided to debug your app with the PyCharm IDE, which best matches Agilab troubleshooting.

.. include:: troubleshooting.txt
   :code: text

C - Exemple of Tests Sequence:
----------------------

- **1. zip-all**

  Tests the zip of the whole agi project directory with .gitignore filtration. A agi.zip file should created at the root dir of your projectu

- **2. fwk-test**

  This will lunch unitary test for both agi-env and agi-core components and display the pytest result

- **3. cython_preprocessing** (if cyprepro.py error)

  This will prompt for your worker source file <your_code_worker.py> to convert into a your_code_worker.pyx transformable into Cython compilable source code.
  A file <your_code_worker.pyx> should appear in your wenv

- **4. app-install-local**

  This will prompt for your module name <your_code> to be installed. This will install your code manager venv and your code worker wenv.

- **5. app_script-gen**

  This will generate the script below

- **6. <your app>_egg**

  This will prompt for a worker module file <www_worker.py> to build in wenv the egg file for remote worker.
  Creates a project egg file containing all the required files to compile the worker Cython library.

- **7. <your app>_lib>**

  This will prompt for the directory where you build your egg file in wenv to build your lib file for remote worker.
  Creates a project lib file your_code_worker_cy.cpython-xxx-yyy-zzz.so containing the worker Cython library.

- **8. <your app>_test>**

  This will test your app in a minimalistic way.

- **9. app_install**

  This will prompt for a file selection to select your AGI install snippet <AGI.xxx-install.py> source code you want to run
  If it does not work, you can restore from the agilab.zip before starting a new investigation.

- **10. app-run**

  This will prompt for a file selection to select your AGI snippet <AGI.xxx.py> source code you want to run
  If it does not work, you can restore from the agilab.zip before starting a new investigation.

D - agilab_run vs lab_run:
--------------------------

- **1. agilab_run**

  This will run streamlit module which will run AGILAB.py in run/debug mode

- **12. lab-run**

  This will directly lunch run_lab.py in run/debug mode


Known Bugs
==========

<UV> Sync Failed
----------------

While running a script you see a "missing module" message but your module is correctly installed in your venv. And when
you try to reinstall it his can lead to re-installation failures due to `circular dependencies` that prevent proper
package version resolution. This may arrived because your `UV cache has been corrupted`.

**Solution:**

Clean the UV cache by executing the following command:

.. code-block:: bash

   uv cache clean


<DASK> Debug Issue
------------------

While debugging Dask on Python 3.12, you might encounter the following error:

.. code-block:: none

   TypeError: _patch_asyncio.<locals>.run() got an unexpected keyword argument 'loop_factory'

**Workaround:**

Disable `python.console.asynio.repl` in the PyCharm registry.
To do this, press `<Shift>+<Ctrl>+A` to open the action search window and then search for *registry*.

.. image:: diagrams/pycharm_registry.png
   :width: 400
   :alt: PyCharm Registry
   :align: center

.. raw:: html

   <br><br>


<PYCHARM> Run/Debug Configuration is Broken
-------------------------------------------

For instance, select your "Run/Debug configuration" (e.g., `<gen-docstings>`) and then press [Run].
The following message appears when you try to [debug] `<gen-docstings>`:

   Argument for @NotNull parameter 'module' of com/intellij/openapi/roots/ModuleRootManager.getInstance must not be null

.. image:: diagrams/pycharm_bug.png
   :width: 400
   :alt: PyCharm Bug
   :align: center

.. raw:: html

   <br><br>

**Solution:**

Delete your "Run/Debug configuration" (named `<gen-docstings>` in this example) and create it again.
This should resolve the issue.