ZEN-temple
ZEN-temple is a FastAPI application that provides a REST API to access results from ZEN-garden. It is the backend of the visualization platform; the frontend is ZEN-explorer.
🧭 Which setup do I need?
The visualization platform is always ZEN-temple (API) + ZEN-explorer (UI). A
released zen-temple package already bundles a built copy of ZEN-explorer, so
end users install a single package. When you work from a checkout of this
repository the frontend is not included and has to be fetched once.
| Your goal | Follow | Clone | Extra tools |
|---|---|---|---|
| Visualize my own ZEN-garden solutions | Quick start | nothing (install from PyPI) | – |
| Develop ZEN-temple (this repo) | Backend development | ZEN-temple | – |
| Develop ZEN-explorer (the frontend) | ZEN-explorer README → Development | ZEN-explorer and ZEN-temple | Node.js |
Which shell / terminal?
Every command block below runs the same in PowerShell, Windows Command
Prompt (cmd) and macOS/Linux bash/zsh. conda, pip, git and the
zen-* commands behave identically in all of them. Where a step genuinely
differs between shells (copying .env, running a bash script) each variant is
shown and labelled.
🛠️ Requirements
- Conda (Miniconda is enough)
- Python 3.11 or higher
- Node.js with npm – only if you also develop ZEN-explorer
🚀 Quick start
Use this to visualize your own solutions. You do not need to clone this repository.
conda create --name zen python==3.13
conda activate zen
pip install zen-garden zen-temple
Run ZEN-garden to produce an outputs folder (or use an existing one), then from
the directory that contains outputs start the platform:
zen-visualization
Your browser opens at http://localhost:8000/explorer/. Point ZEN-temple at a
different solutions folder with zen-visualization --outputs-folder <path>.
🐍 Backend development
Use this when you want to change ZEN-temple itself.
-
Clone and enter the repository:
git clone https://github.com/ZEN-universe/ZEN-temple.git cd ZEN-temple -
Create the environment and install in editable mode:
conda create --name zen python==3.13 conda activate zen pip install -e .[mypy] -
Fetch the ZEN-explorer frontend. A checkout ships only a placeholder page, and
zen-visualizationrefuses to start without the real build.Skip this step if you are developing ZEN-explorer in parallel – run ZEN-temple with
--api-onlyinstead (see Developing against a live ZEN-explorer).Pull a prebuilt copy from the latest published
zen-templerelease:zen-temple-fetch-explorer- Add
--version <x.y.z>to match a specificzen-templerelease. - The files land in
zen_temple/explorer/and are git-ignored.
- Add
-
Create your
.envfile from the example:PowerShell:
Copy-Item .env.example .env
Command Prompt (
cmd):copy .env.example .envbash / zsh:
cp .env.example .env
SOLUTION_FOLDERin.envis only a fallback; the-o/--outputs-folderflag and the current working directory take precedence.
Run the server
conda activate zen
zen-visualization --reload
By default ZEN-temple searches for solutions in ./outputs and then in the
current working directory. To select a solution folder explicitly, use:
zen-visualization --outputs-folder <path-to-solutions>
The equivalent module invocation is python -m zen_temple.main --reload. For all
available command line arguments run:
python -m zen_temple.main --help
If the server refuses to start with a "port ... is not available" message, an
earlier zen-visualization is probably still running. Stop it, or pass
--port <other-port> (and set PUBLIC_TEMPLE_URL for the ZEN-explorer dev
server accordingly).
Developing against a live ZEN-explorer
When you also run the ZEN-explorer dev server, start ZEN-temple in API-only
mode. The bundled frontend is then neither required nor served, so you can skip
zen-temple-fetch-explorer:
zen-visualization --api-only --no-open-browser --reload
Then follow ZEN-explorer's README
to start its dev server with npm run dev. The UI is served from
http://localhost:5173/ and talks to this API at http://localhost:8000/api/.
📤 Release workflow
Releases are driven by the Release GitHub Actions workflow. Do not edit
pyproject.toml or CHANGELOG.md by hand.
- Merge your changes into
main. The workflow then opens (or updates) a pull request titledRelease vX.Y.Z.devN, labelledrelease, that bumps the version and prepends aCHANGELOG.mdentry. - Set the version and notes on that PR. Edit its title
(
Release vX.Y.Zfor a full release, keep the.devNsuffix for a pre-release) and its description (becomes the CHANGELOG body). A workflow run rewrites the files on the PR branch. Keep thereleaselabel. - Merge the release PR. This only creates a draft GitHub release – no tag, no PyPI upload yet.
- Publish the draft at https://github.com/ZEN-universe/ZEN-temple/releases:
open it, set the pre-release flag as needed, click Publish release. This
creates the
vX.Y.Ztag and triggers thePublish … to PyPIworkflow (~7 min; it builds ZEN-explorermaininto the package). - Verify the version at https://pypi.org/project/zen-temple/#history.
Until the tag from step 4 exists, every push to main re-opens a release PR. A
release PR merged without the release label, or with a title that is not
Release vX.Y.Z[.devN], is not turned into a draft release.
🗂️ Folder structure
The folder and file structure is the following:
Explorer
explorer contains the built ZEN-explorer frontend that ZEN-temple serves as
static files.
[!WARNING]
Do not edit these files. They are produced by the ZEN-explorer build pipeline. In a checkout the folder only holds a placeholder page until you runzen-temple-fetch-explorer(or build ZEN-explorer yourself); the real files are git-ignored.
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/
1 maintainer
Metadata
1 maintainer
Release files for zen-temple 0.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| zen_temple-0.10.1.tar.gz | 46.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| zen_temple-0.10.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 93.1 MB
Release files / zen_temple-0.10.1.tar.gz
| Download URL | zen_temple-0.10.1.tar.gz |
|---|---|
| Size | 46.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
75dcc290111e8dcb3c5bde8d99a06a46c3cb861628786c2d8bf4a94b43f1eff1
|
|
BLAKE2b-256 checksum How to use checksums |
aeace52920e97c3b4d8cc0e53f3ea30cdd0e54e99645180f9ad99466ea086b2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / zen_temple-0.10.1-py3-none-any.whl
| Download URL | zen_temple-0.10.1-py3-none-any.whl |
|---|---|
| Size | 46.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
34e98d12ad7b4442396a7143acc8fe4a6e1edd1493db2909fd8fbeacd3f14ee0
|
|
BLAKE2b-256 checksum How to use checksums |
b9a28b5830d937066d215a4667e88065f8efee94638e297556bfd3df5fdb823b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency log
