zen-temple 0.9.1
The visualization plattform for ZEN-garden
Requires Python: >=3.10

# ZEN-temple

ZEN-temple is a FastAPI Application that provides a REST API to access results from [ZEN-garden](https://github.com/ZEN-universe/ZEN-garden). It is used as a backend for [ZEN-Explorer](https://github.com/ZEN-universe/ZEN-explorer).

[![PyPI - Version](https://img.shields.io/pypi/v/zen-temple?logo=pypi&logoColor=fff&color=0375b5)](https://pypi.org/project/zen-temple/)
![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fgithub.com%2FZEN-universe%2FZEN-temple%2Fraw%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)

[![GitHub Actions: Type checker](https://github.com/ZEN-universe/ZEN-temple/actions/workflows/run-mypy.yml/badge.svg)](https://github.com/ZEN-universe/ZEN-temple/actions/workflows/run-mypy.yml)

[![GitHub License](https://img.shields.io/github/license/ZEN-universe/ZEN-temple?label=License)](https://github.com/ZEN-universe/ZEN-temple/blob/main/LICENSE)

## 🛠️ Requirements

- Conda (https://docs.conda.io/en/latest/miniconda.html)
- Python 3.10 or higher

## 📦 Installation

Perform the following steps to install ZEN-temple:

1. Clone the repository and navigate into the folder:

   ```bash
   git clone https://github.com/ZEN-universe/ZEN-temple.git
   cd ZEN-temple
   ```

1. Create a new conda environment, activate it, and install all dependencies:

   ```bash
   conda create --name <your-env-name> python==3.13
   conda activate <your-env-name>
   pip install -e .[mypy]
   ```

2. Create a new copy of `.env`.

   ```bash
   cp .env.example .env
   ```

   Modify the `SOLUTION_FOLDER` variable to the location of your solutions, e.g. `./outputs`. This is the `outputs` folder generated by ZEN-garden.

## ▶️ Usage

Open this folder in your terminal. Activate your conda environment for this project and run the application with the following commands:

```bash
conda activate <your-env-name>
python -m zen_temple.main --reload
```

For information about the available command line arguments run:

```bash
python -m zen_temple.main --help
```

## 📤 Release workflow

To create a new release of ZEN-temple follow the following steps. The idea is that for each major release (from `v0.4.x` to `v0.5.0`) we sync the version number of ZEN-explorer and ZEN-temple

1. Bump version in ZEN-explorer `bash scripts/bump_version.sh` and update its CHANGELOG.md.
2. Commit and upload the updated files to GitHub.
3. Create a new release for ZEN-explorer:
   https://github.com/ZEN-universe/ZEN-explorer/releases/new
4. Bump version in ZEN-temple `bash scripts/bump_version.sh` and update [CHANGELOG.md](CHANGELOG.md).
5. Commit and upload the updated files to GitHub.
6. Create a new release for ZEN-temple, e.g. `<version>`. For a pre-release also add a suffix `.dev1`, i.e. `<version>.dev1`, and mark the release as pre-release:
   https://github.com/ZEN-universe/ZEN-temple/releases/new
7. (optional) Look at PyPI whether the new release has successfully been created:
   https://pypi.org/project/zen-temple/#history

## 🗂️ Folder structure

The folder and file structure is the following:

### Explorer

`explorer` contains the HTML files for the frontend.

> [!WARNING]  
> Do not edit the files in this folder. This folder is automatically generated by the frontend repository pipeline.

### Models

`models` contains the Pydantic-models that are used for the documentation. Some of these models also include generators that create an instance of the model given the path of a solution. See https://fastapi.tiangolo.com/tutorial/body/#create-your-data-model

### Repositories

`repositories` contains the repositories for the data access. These provide an abstraction layer for the routers such that the data access is separated from the data source. Arguably, the generators defined in the models should be part of the repository in order to separate the instantiation of the models from the way that the solutions are stored. For more information visit https://www.umlboard.com/design-patterns/repository.html

### Routers

`routers` contains the FastAPI routers which define the different paths of the API server. For more information visit https://fastapi.tiangolo.com/tutorial/bigger-applications/

### Config

`config.py` contains the config of the application.

### Main

`main.py` contains the setup of the FastAPI application. For more information visit https://fastapi.tiangolo.com/tutorial/bigger-applications/