v3.0 — package the library as simcenter-dlml with an API, CLI, and the DLML Explorer web app

.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+{
+  "name": "DLML Explorer",
+  // Python 3.11 clears the >=3.10 floor that onnxruntime (via fastembed) needs
+  // for the `explorer` extra.
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+  "customizations": {
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "src/dlml/web/app.py"
+      ]
+    },
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  },
+  // Install the package (editable) with the explorer extra -- this provides the
+  // `dlml` command and all the app's dependencies. Replaces the old
+  // requirements.txt + standalone streamlit install.
+  "updateContentCommand": "pip install -e \".[explorer]\"",
+  // `dlml explorer` launches Streamlit headless; the first launch downloads the
+  // ~64 MB search model from HuggingFace. Codespaces serves through a proxy, so
+  // CORS/XSRF are disabled via containerEnv below (the CLI doesn't expose those
+  // flags, but Streamlit reads them from the environment).
+  "postAttachCommand": {
+    "server": "dlml explorer"
+  },
+  "containerEnv": {
+    "STREAMLIT_SERVER_ENABLE_CORS": "false",
+    "STREAMLIT_SERVER_ENABLE_XSRF_PROTECTION": "false"
+  },
+  "portsAttributes": {
+    "8501": {
+      "label": "DLML Explorer",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "forwardPorts": [
+    8501
+  ]
+}

.github/workflows/build_docs.yaml

@@ -1,47 +1,56 @@
 name: Build and deploy documentation
+
 on:
   push:
-    branches:
-      - main
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# Least privilege by default; the job grants itself write for the gh-pages push.
 permissions:
-  contents: write
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
-
+        uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
-
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y pandoc
-          python -m pip install -r requirements.txt
-
-      - name: Compute cache key
+          python-version: '3.12'
+      # Installs the package (so the generators can import dlml) plus the Sphinx
+      # toolchain and the plotting libraries the figure generators need.
+      - name: Install the package and doc dependencies
+        run: python -m pip install ".[doc]"
+      - name: Compute the figure-cache key
         id: compute-cache-key
         run: |
-          cd doc/source/_extensions
-          key=$(python compute_global_hash.py)
-          cd ../../../
-          echo "key=$key" >> $GITHUB_OUTPUT
-
-      - name: Restore cache
-        uses: actions/cache@v3
+          key=$(cd doc/source/_extensions && python compute_global_hash.py)
+          echo "key=$key" >> "$GITHUB_OUTPUT"
+      - name: Restore the figure cache
+        uses: actions/cache@v4
         with:
           path: doc/cache
-          key: ${{ steps.compute-cache-key.outputs.key }}
-
+          key: docs-cache-${{ steps.compute-cache-key.outputs.key }}
+          # Fall back to the most recent cache so a data change re-renders only
+          # the changed figures instead of all of them from a cold cache.
+          restore-keys: |
+            docs-cache-
       - name: Build docs
         run: cd doc && make html
-
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        # Only a push to main deploys; PRs and manual runs build only.
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./doc/build/html

.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v3]
+  pull_request:
+  workflow_dispatch:
+
+# Least privilege: CI only reads the checkout.
+permissions:
+  contents: read
+
+# Cancel superseded runs of the same ref (e.g. rapid pushes to a PR).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pin uv so CI matches the committed uv.lock resolver and the local dev version.
+  UV_VERSION: "0.10.9"
+
+jobs:
+  checks:
+    name: Lint, type, spell, tests + coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+          enable-cache: true
+      - name: Sync the checks environment (test + lint)
+        run: uv sync --locked --extra test --extra lint
+      # scripts/check.sh is the single source of truth (also the pre-commit hook):
+      - name: Run the full gate
+        run: bash scripts/check.sh
+        env:
+          # The env is already synced above; keep check.sh's inner `uv run`
+          # calls from re-syncing to defaults.
+          UV_NO_SYNC: "1"
+
+  test:
+    name: Tests (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.9" }
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: windows-latest, python: "3.12" }
+          - { os: macos-latest, python: "3.12" }
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - name: Run the test suite
+        run: uv run --locked --extra test pytest
+
+  bare-install:
+    name: Bare install (core only)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+          enable-cache: true
+      - name: Build the sdist and wheel
+        run: uv build
+      # Install from the SDIST (not the tree) into a clean, extras-free env, so a
+      # missing data file in the sdist would surface as an empty dataset list.
+      - name: Install from sdist and smoke-test the core API + CLI
+        run: |
+          uv venv /tmp/bare --python 3.12
+          source /tmp/bare/bin/activate
+          uv pip install dist/*.tar.gz
+          python -c "import dlml; ids = dlml.list_datasets(); assert ids, 'no datasets discovered'; print(len(ids), 'datasets')"
+          dlml list | head -3
+          FIRST=$(dlml list | head -1 | sed 's/  \[.*//')
+          dlml info "$FIRST"
+          if dlml explorer >/dev/null 2>&1; then
+            echo "ERROR: bare 'dlml explorer' should exit non-zero"; exit 1
+          fi
+          echo "bare 'dlml explorer' correctly refused (exit 1)"

.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish to PyPI
+
+# ┌──────────────────────────────────────────────────────────────────────────┐
+# │ FREEZE POLICY (see README, "Release Policy"). This workflow publishes to  │
+# │ PyPI when a git TAG like `v3.0` is pushed. A pushed git tag is only a     │
+# │ ref -- it does NOT create a GitHub Release, so `releases/latest` stays    │
+# │ pinned at v2.1.0 for legacy pelicun (<=3.9) that downloads the data from  │
+# │ there. Do NOT add an `on: release:` trigger, and do NOT add any step that │
+# │ creates a GitHub Release or moves a tag while the freeze is in effect.    │
+# └──────────────────────────────────────────────────────────────────────────┘
+
+on:
+  push:
+    tags:
+      # v3-v9 majors publish to PyPI; v2.x is deliberately excluded (freeze).
+      - "v[3-9].*"
+  # Manual runs build + validate only; the publish job is gated on a tag ref,
+  # so a dispatch is a safe no-upload dry run (inspect the artifacts afterward).
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  UV_VERSION: "0.10.9"
+
+jobs:
+  build:
+    name: Build + validate sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+          enable-cache: true
+      - name: Build
+        run: uv build
+      # On a tag push, refuse to proceed unless the tag matches the built version
+      # exactly (tag v3.0 <-> version 3.0). Catches a stray tag and a
+      # forgotten `.dev0` bump.
+      - name: Verify tag matches the built version
+        if: github.ref_type == 'tag'
+        run: |
+          version=$(ls dist/*.whl | sed -E 's|.*/simcenter_dlml-([^-]+)-py3.*|\1|')
+          echo "Built version: $version   Tag: $GITHUB_REF_NAME"
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::Tag '$GITHUB_REF_NAME' != built version 'v$version'. Refusing to publish."
+            exit 1
+          fi
+      - name: Check package metadata + README rendering
+        run: uvx twine check dist/*
+      - name: Upload the distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    # Only a real tag push publishes; workflow_dispatch stops after `build`.
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    # The `pypi` environment carries a required-reviewer protection rule, so an
+    # upload waits for a human approval in the Actions UI even on a correct tag.
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # OIDC for PyPI Trusted Publishing -- no stored token.
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -6,3 +6,36 @@
 /.ropeproject/
 /doc/cache/
 /doc/source/dl_doc/
+
+
+#Dev Enviornment
+/.vscode/
+/.idea/
+/.venv/
+
+# Secrets (never commit or package these)
+**/secrets.toml
+.env
+
+# Session data
+*.session
+session_store/
+/.cache/
+
+# Local scratch data
+/DB/
+
+# Packaging build artifacts
+/dist/
+/build/
+*.egg-info/
+src/*.egg-info/
+__pycache__/
+
+# Test & tooling caches
+.coverage
+.coverage.*
+/htmlcov/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/

.streamlit/config.toml

@@ -0,0 +1,9 @@
+# Light is the default theme. The in-app dark toggle (st_ui/theme.py) layers a
+# dark palette over this via CSS — Streamlit itself only supports one default.
+[theme]
+base = "light"
+primaryColor = "#C8382E"
+backgroundColor = "#F4F6FB"
+secondaryBackgroundColor = "#FFFFFF"
+textColor = "#171C26"
+font = "sans serif"