Use Markdown for adapter descriptions

Author: pinkwah

backend/pyproject.toml

@@ -13,7 +13,9 @@ dependencies = [
   "fastapi",
   "gunicorn>=23.0.0,<24.0.0",
   "httpx",
+  "markdown>=3.10,<4.0",
   "msal",
+  "nh3>=0.3,<0.4",
   "neqsim==3.1.0",
   "opentelemetry-instrumentation-fastapi",
   "opentelemetry-instrumentation-httpx",
@@ -41,6 +43,7 @@ dev = [
   "pytest-alembic>=0.12.1",
   "pytest-asyncio",
   "ruff",
+  "types-Markdown",
 ]
 
 [build-system]

backend/src/acidwatch_api/models/arcs.py

@@ -7,12 +7,16 @@
 from acidwatch_api.models.datamodel import Phase
 from acidwatch_api.settings import SETTINGS
 
-DESCRIPTION: str = """Automated Reactions for CO2 Storage (ARCS) model.
-    ARCS combines first-principles calculations with Monte-Carlo sampling and models possible reactions that may occur under a given set of conditions.
-    This process identifies the most frequently occurring reactions and paths, final products, and expected concentrations.
-    
-    Source code found at https://github.com/equinor/arcs/tree/21ded96960d28d549c0950fbc1aa09c94159f652
-    """
+DESCRIPTION: str = """\
+Automated Reactions for CO2 Storage (ARCS) model.
+
+ARCS combines first-principles calculations with Monte-Carlo sampling and
+models possible reactions that may occur under a given set of conditions.
+This process identifies the most frequently occurring reactions and paths,
+final products, and expected concentrations.
+
+Source code found [on GitHub (equinor/arcs)](https://github.com/equinor/arcs/tree/21ded96960d28d549c0950fbc1aa09c94159f652).
+"""
 
 
 class ArcsAdapter(BaseAdapter):

backend/src/acidwatch_api/models/arcs_exp.py

@@ -5,13 +5,20 @@
 from acidwatch_api.models.datamodel import Phase
 from acidwatch_api.settings import SETTINGS
 
-DESCRIPTION: str = """Automated Reactions for CO2 Storage (ARCS) model.
-    ARCS combines first-principles calculations with Monte-Carlo sampling and models possible reactions that may occur under a given set of conditions.
-    This process identifies the most frequently occurring reactions and paths, final products, and expected concentrations.
-    
-    This model is under significant development and expected to deviate while developed. Therefore a development version of it has been released while work is ongoing
-    Source code found at https://github.com/badw/arcs
-    """
+DESCRIPTION: str = """\
+Automated Reactions for CO2 Storage (ARCS) model.
+
+ARCS combines first-principles calculations with Monte-Carlo sampling and
+models possible reactions that may occur under a given set of conditions.
+This process identifies the most frequently occurring reactions and paths,
+final products, and expected concentrations.
+
+This model is under significant development and is expected to change while
+developed. Therefore a development version of it has been released while work
+is ongoing.
+
+Source code found [on GitHub (badw/arcs)](https://github.com/badw/arcs).
+"""
 
 
 class ArcsExpAdapter(BaseAdapter):

backend/src/acidwatch_api/models/base.py

@@ -1,4 +1,8 @@
 from __future__ import annotations
+from functools import lru_cache
+import nh3
+from markdown import markdown
+import textwrap
 
 import typing
 from collections import defaultdict
@@ -257,7 +261,8 @@ def __init_subclass__(cls) -> None:
     ]
 
     description: Annotated[
-        str, Doc("A description for model which is displayed in the frontend")
+        str,
+        Doc("A Markdown description for the model."),
     ]
 
     category: Annotated[
@@ -277,6 +282,14 @@ def __init_subclass__(cls) -> None:
 
     base_url: Annotated[str | None, Doc("BaseURL for accessing a remote model")] = None
 
+    @classmethod
+    @lru_cache()
+    def description_as_html(cls) -> str:
+        """Get the description as rendered HTML"""
+        text = textwrap.dedent(cls.description).strip()
+        html = markdown(text, extensions=["extra", "sane_lists"])
+        return nh3.clean(html)
+
     @property
     def client(self) -> httpx.AsyncClient:
         """A ready-to-use client to communicate with an external model

backend/src/acidwatch_api/models/datamodel.py

@@ -166,6 +166,7 @@ class ModelInfo(BaseModel):
     model_id: str
     display_name: str
     description: str
+    description_html: str
     category: str
     valid_substances: list[str]
     parameters: dict[str, Any]

backend/src/acidwatch_api/models/gibbs_minimization_model.py

@@ -76,11 +76,26 @@
     # "i-pentane"
 ]
 
-DESCRIPTION: str = """The model's primary advantage lies in its ability to analyze complex systems, such as CO2 with impurities, without the need to specify individual reactions. By focusing only on the thermodynamic principles that govern the system's behavior, it identifies the stable state corresponding to the minimum total Gibbs free energy at given temperature and pressure.
-
-However, the model also has limitations. It requires the input of all possible species that could form from the elements present missing any potential species may lead to incorrect equilibrium calculations (that is does not necessary mean poor description of real case scenario). Additionally, the model does not account for kinetics or activation energy, which are crucial for understanding the speed of reactions and the energy barriers that must be overcome for reactions to occur. As a result, while the model can predict the equilibrium state, it cannot guarantee that the real CO2 with impurities system actually reach that state.
-
-The model uses neqsim library for the fluid description (EOS)."""
+DESCRIPTION: str = """\
+The model's primary advantage lies in its ability to analyze complex systems,
+such as CO2 with impurities, without the need to specify individual reactions.
+By focusing only on the thermodynamic principles that govern the system's
+behavior, it identifies the stable state corresponding to the minimum total
+Gibbs free energy at given temperature and pressure.
+
+However, the model also has limitations. It requires the input of all possible
+species that could form from the elements present; missing any potential
+species may lead to incorrect equilibrium calculations (that does not
+necessarily mean a poor description of the real case scenario). Additionally,
+the model does not account for kinetics or activation energy, which are crucial
+for understanding the speed of reactions and the energy barriers that must be
+overcome for reactions to occur. As a result, while the model can predict the
+equilibrium state, it cannot guarantee that the real CO2-with-impurities system
+actually reaches that state.
+
+The model uses the [neqsim](https://github.com/equinor/neqsim) library for the
+fluid description (EOS).
+"""
 
 
 class _EquationOfState(StrEnum):

backend/src/acidwatch_api/models/solubilityccs.py

@@ -9,14 +9,19 @@
 from solubilityccs import Fluid, ModelResults  # type: ignore
 from solubilityccs.neqsim_functions import get_co2_parameters  # type: ignore
 
-DESCRIPTION: str = """Solubility model detects acid formation risks in CO2 streams. 
-    
-It uses the SRK-CPA (Soave-Redlich-Kwong Cubic Plus Association) equation of state to calculate fugacity coefficients and activity models to determine component activities in multiphase systems.
+DESCRIPTION: str = """\
+Solubility model detects acid formation risks in CO2 streams.
+
+It uses the SRK-CPA (Soave-Redlich-Kwong Cubic Plus Association) equation of
+state to calculate fugacity coefficients and activity models to determine
+component activities in multiphase systems.
 
 The model currently supports the following chemical systems:
-CO₂-water (binary system)
-CO₂-water-H₂SO₄ (ternary system with sulfuric acid)
-CO₂-water-HNO₃ (ternary system with nitric acid)"""
+
+- CO₂-water (binary system)
+- CO₂-water-H₂SO₄ (ternary system with sulfuric acid)
+- CO₂-water-HNO₃ (ternary system with nitric acid)
+"""
 
 
 class SolubilityCCSParameters(BaseParameters):

backend/src/acidwatch_api/models/tocomo.py

@@ -6,23 +6,29 @@
 
 router = APIRouter()
 
-DESCRIPTION: str = """The Total Consumption Model (ToCoMo) estimates final concentrations of chemicals based on initial input concentrations using a series of chemical reactions. 
+DESCRIPTION: str = """\
+The Total Consumption Model (ToCoMo) estimates final concentrations of
+chemicals based on initial input concentrations using a series of chemical
+reactions.
 
 The model applies the following reactions in a specific order:
 
-3. H₂S + 3 NO₂ → SO₂ + H₂O + 3 NO
-2. 2 NO + O₂ → 2 NO₂
-1. NO₂ + SO₂ + H₂O → NO + H₂SO₄
-4. 3 NO₂ + H₂O → 2 HNO₃ + NO
-5. 2 NO₂ + H₂O → HNO₃ + HNO₂
-6. 8 H₂S + 4 O₂ → 8 H₂O + S₈
+|    |                 |   |                  |
+|----|-----------------|---|------------------|
+| 1. | H₂S + 3 NO₂     | → | SO₂ + H₂O + 3 NO |
+| 2. | 2 NO + O₂       | → | 2 NO₂            |
+| 3. | NO₂ + SO₂ + H₂O | → | NO + H₂SO₄       |
+| 4. | 3 NO₂ + H₂O     | → | 2 HNO₃ + NO      |
+| 5. | 2 NO₂ + H₂O     | → | HNO₃ + HNO₂      |
+| 6. | 8 H₂S + 4 O₂    | → | 8 H₂O + S₈       |
 
-The model operates as follows:
-We go through the list in the order given and try to apply the reaction. 
-If it is not possible with the current reaction, we proceed to the next one.
-If a reaction can occur, it will be applied, and then we start from the top again.
+The model operates as follows: we go through the list in the order given and
+try to apply the reaction. If it is not possible with the current reaction, we
+proceed to the next one. If a reaction can occur, it will be applied, and then
+we start from the top again.
 
-This iterative approach allows ToCoMo to simulate the chemical interactions and provide estimates of final concentrations based on the initial conditions.
+This iterative approach allows ToCoMo to simulate the chemical interactions and
+provide estimates of final concentrations based on the initial conditions.
 """
 
 

backend/src/acidwatch_api/routes/models.py

@@ -181,6 +181,7 @@ def get_models(
                 display_name=adapter.display_name,
                 category=adapter.category,
                 description=adapter.description,
+                description_html=adapter.description_as_html(),
                 valid_substances=adapter.valid_substances,
                 parameters=get_parameters_schema(adapter),
             )

backend/tests/models/test_adapter.py

@@ -58,3 +58,19 @@ def test_adapter_with_invalid_parameters_type():
         class DummyAdapter(base.BaseAdapter):
             model_id = "dummy"
             parameters = 3
+
+
+def test_adapter_description_is_rendered_to_html_once():
+    class MarkdownAdapter(base.BaseAdapter):
+        model_id = "markdown_dummy"
+        display_name = "Markdown Dummy"
+        description = "# Title\n\nSome **markdown** body."
+        category = "ChemicalEquilibrium"
+        valid_substances = ["H2O"]
+
+        async def run(self):
+            raise NotImplementedError()
+
+    assert MarkdownAdapter.description_as_html() == (
+        "<h1>Title</h1>\n<p>Some <strong>markdown</strong> body.</p>"
+    )