py-lucidum 0.4.59__tar.gz

py_lucidum-0.4.59/.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -eu
+
+repo_root=$(git rev-parse --show-toplevel)
+python=${PY_LUCIDUM_TEST_PYTHON:-"$repo_root/.venv/bin/python"}
+
+if ! command -v "$python" >/dev/null 2>&1; then
+    echo "Lucidum pre-commit: Python is not executable: $python" >&2
+    echo "Set PY_LUCIDUM_TEST_PYTHON to the test-environment Python path." >&2
+    exit 1
+fi
+
+exec "$python" "$repo_root/scripts/run_tests.py" precommit

py_lucidum-0.4.59/.githooks/pre-push

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -eu
+
+repo_root=$(git rev-parse --show-toplevel)
+python=${PY_LUCIDUM_TEST_PYTHON:-"$repo_root/.venv/bin/python"}
+
+if ! command -v "$python" >/dev/null 2>&1; then
+    echo "Lucidum pre-push: Python is not executable: $python" >&2
+    echo "Set PY_LUCIDUM_TEST_PYTHON to the test-environment Python path." >&2
+    exit 1
+fi
+
+exec "$python" "$repo_root/scripts/run_tests.py" prepush

py_lucidum-0.4.59/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies

py_lucidum-0.4.59/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  full-test-suite:
+    name: Full test suite
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[glm,gbm]" pytest playwright
+          python -m playwright install --with-deps chromium webkit
+
+      - name: Run complete test gate
+        run: python scripts/run_tests.py prepush

py_lucidum-0.4.59/.github/workflows/release.yml

@@ -0,0 +1,327 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate release tag
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    outputs:
+      release_commit: ${{ steps.release.outputs.release_commit }}
+      version: ${{ steps.release.outputs.version }}
+
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Validate tag, version, branch, and CI
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Release tag must use vMAJOR.MINOR.PATCH: $GITHUB_REF_NAME" >&2
+            exit 1
+          fi
+          if [[ "$(git cat-file -t "$GITHUB_REF_NAME")" != "tag" ]]; then
+            echo "Release tag must be annotated: $GITHUB_REF_NAME" >&2
+            exit 1
+          fi
+
+          version="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+          print(tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"])
+          PY
+          )"
+          if [[ "$GITHUB_REF_NAME" != "v$version" ]]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $version" >&2
+            exit 1
+          fi
+
+          release_commit="$(git rev-list -n 1 "$GITHUB_REF_NAME")"
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$release_commit" origin/main; then
+            echo "Tagged commit $release_commit is not on origin/main" >&2
+            exit 1
+          fi
+
+          conclusion="$(gh api -X GET \
+            "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs" \
+            -f branch=main \
+            -f event=push \
+            -f head_sha="$release_commit" \
+            -f status=completed \
+            --jq '.workflow_runs[0].conclusion // ""')"
+          if [[ "$conclusion" != "success" ]]; then
+            echo "Tagged commit $release_commit does not have a successful main CI run" >&2
+            exit 1
+          fi
+
+          echo "release_commit=$release_commit" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build and smoke-test distributions
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.release_commit }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Build and inspect distributions
+        env:
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build pipx twine
+          python -m build
+          python -m twine check dist/*
+          python scripts/release_artifacts.py inspect --version "$RELEASE_VERSION"
+
+      - name: Smoke-test the built wheel through pipx
+        env:
+          PY_LUCIDUM_EXPECTED_VERSION: ${{ needs.validate.outputs.version }}
+          PY_LUCIDUM_PIPX_SPEC: ${{ github.workspace }}/dist/py_lucidum-${{ needs.validate.outputs.version }}-py3-none-any.whl
+        run: python scripts/run_tests.py pipx
+
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Store checksums
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-checksums
+          path: dist/SHA256SUMS
+          if-no-files-found: error
+          retention-days: 14
+
+  draft-release:
+    name: Create draft GitHub release
+    needs:
+      - validate
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Download checksums
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-checksums
+          path: dist/
+
+      - name: Create draft and attach artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            is_draft="$(gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)"
+            if [[ "$is_draft" != "true" ]]; then
+              echo "Release $RELEASE_TAG is already published" >&2
+              exit 1
+            fi
+          else
+            gh release create "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --verify-tag \
+              --draft \
+              --generate-notes \
+              --title "py-lucidum $RELEASE_TAG"
+          fi
+          gh release upload "$RELEASE_TAG" dist/* \
+            --repo "$GITHUB_REPOSITORY" \
+            --clobber
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs:
+      - validate
+      - build
+      - draft-release
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/py-lucidum
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  verify-testpypi:
+    name: Verify TestPyPI artifacts
+    needs:
+      - validate
+      - build
+      - publish-testpypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out release verifier
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.release_commit }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Compare TestPyPI hashes
+        run: >-
+          python scripts/release_artifacts.py verify-index
+          --version "${{ needs.validate.outputs.version }}"
+          --repository-url https://test.pypi.org/pypi
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs:
+      - validate
+      - build
+      - verify-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/py-lucidum
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  verify-pypi:
+    name: Verify PyPI installation
+    needs:
+      - validate
+      - build
+      - publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out release verifier
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.release_commit }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Compare PyPI hashes
+        run: >-
+          python scripts/release_artifacts.py verify-index
+          --version "${{ needs.validate.outputs.version }}"
+          --repository-url https://pypi.org/pypi
+
+      - name: Smoke-test installation from PyPI
+        env:
+          PY_LUCIDUM_EXPECTED_VERSION: ${{ needs.validate.outputs.version }}
+          PY_LUCIDUM_PIPX_SPEC: py-lucidum==${{ needs.validate.outputs.version }}
+        run: |
+          python -m pip install pipx
+          python scripts/run_tests.py pipx
+
+  publish-github-release:
+    name: Publish immutable GitHub release
+    needs:
+      - validate
+      - draft-release
+      - verify-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Publish the validated draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh release edit "$RELEASE_TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --draft=false \
+            --latest
+          gh release view "$RELEASE_TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --json isDraft,tagName,url

py_lucidum-0.4.59/.gitignore

@@ -0,0 +1,27 @@
+# Local development datasets and artifacts
+datasets/*.csv
+datasets/*.parquet
+!datasets/motor_premiums.parquet
+.lucidum/
+local/
+
+# Python/cache/build artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv
+.venv/
+.venv-linux
+.venv-linux/
+dist/
+build/
+*.egg-info/
+
+# OS/editor metadata
+.DS_Store
+
+# Generated README previews
+README.html
+README_files/

py_lucidum-0.4.59/AGENTS.md

@@ -0,0 +1,115 @@
+# Repository Guidance
+
+This file gives future coding agents the shortest reliable path into `py_lucidum`.
+
+## Start Here
+
+- Read `README.md` for user-facing installation, launch commands, and current tool behavior.
+- Read `DEVELOPMENT.md` before non-trivial changes. It is the durable maintainer context for architecture, behavior contracts, test commands, and commit rules.
+- Read the `Releasing` section in `DEVELOPMENT.md` before packaging, tagging, or publishing a release.
+- Current GBM product notes live in `docs/specs/gbm-tool.md`; `docs/specs/gbm-tool_plan.md` is historical implementation context only.
+
+## Environment Notes
+
+- This repo is normally driven from Positron, not the Codex app. Do not try to use the Codex in-app Browser plugin here; it will not be available. For browser verification, use the repo's Playwright smoke tooling, local `curl` checks, or a manually launched local browser session.
+- To launch the committed multi-Parquet fixture from a source checkout, run `.venv/bin/lucidum datasets/monthly --port 8000`. Folder inputs are for non-modelling tools only; do not combine this fixture with `glm`, `gbm`, or `--tools all`.
+
+## Shape Of The App
+
+- `py_lucidum` is a local-first FastAPI + DuckDB app with a static ES-module frontend.
+- Backend app setup lives under `src/py_lucidum/app/`; core dataset/query helpers live in `src/py_lucidum/core/`.
+- Tool backends live under `src/py_lucidum/tools/`.
+- Frontend shell and tool modules live under `src/py_lucidum/static/app/`.
+- `src/py_lucidum/static/app/main.js` is the frontend coordinator only: schema/defaults, KPI controls, saved filters, sidebar/footer layout, tool selection, cross-tool invalidation, reload orchestration, and boot flow.
+- Frontend tool ownership is split by file: `dataset-viewer-tool.js`, `column-profile-tool.js`, `line-bar-tool.js`, `histogram-tool.js`, `uk-map-tool.js`, `glm-tool.js`, `glm-formula-builder.js`, `glm-model-navigator.js`, `glm-tabulations.js`, `gbm-tool.js`, `gbm-feature-parameter-controls.js`, `gbm-evaluation-chart.js`, `gbm-model-navigator.js`, `gbm-tab-orchestration.js`, `gbm-shap-tool.js`, `gbm-shap-chart.js`, `gbm-stacked-shap-tool.js`, `gbm-stacked-shap-chart.js`, `gbm-tree-viewer.js`, and `model-tool-shell.js`.
+- Import-safe shared frontend helpers live under `src/py_lucidum/static/app/shared/`: API calls, formatters, schema/source helpers, Tabulator lazy loading, and action timing.
+- `src/py_lucidum/static/app.css` is only the stable linked CSS manifest. Actual app styles live under `src/py_lucidum/static/styles/` by shell/tool boundary.
+- Vendored browser libraries live under `src/py_lucidum/static/vendor/`. ECharts and Leaflet load from `index.html` because default tools need them at startup; Ace, Tabulator, D3, and ECharts GL are lazy-loaded by the tools/views that need them.
+
+## Read The Smallest Useful Surface
+
+Use this map before opening large files:
+
+- App boot, tool switching, shared sidebar/filter/KPI behavior: read `static/app/main.js`, `static/styles/shell.css`, and `static/styles/controls.css`.
+- Shared API, formatting, schema/source helpers, or timing behavior: read the matching file in `static/app/shared/` first; only read tool modules if call-site behavior matters.
+- Dataset Viewer frontend: read `static/app/dataset-viewer-tool.js` and `static/styles/dataset-viewer.css`; backend behavior is under `tools/dataset_viewer/`.
+- Column Profile frontend: read `static/app/column-profile-tool.js` and `static/styles/column-profile.css`; backend behavior is under `tools/column_profile/`.
+- Line/Bar frontend: read `static/app/line-bar-tool.js` and `static/styles/line-bar.css`; backend behavior is under `tools/line_bar/`.
+- Histogram frontend: read `static/app/histogram-tool.js` and `static/styles/histogram.css`; backend behavior is under `tools/histogram/`.
+- UK Mapping frontend: read `static/app/uk-map-tool.js` and `static/styles/uk-map.css`; backend behavior and map static assets are under `tools/uk_map/`.
+- GLM frontend: read `static/app/glm-tool.js`, `static/app/glm-formula-builder.js`, `static/app/glm-model-navigator.js`, `static/app/glm-tabulations.js`, and `static/styles/glm.css`; backend behavior is under `tools/glm/`.
+- GBM frontend: read `static/app/gbm-tool.js`, `static/app/gbm-feature-parameter-controls.js`, `static/app/gbm-evaluation-chart.js`, `static/app/gbm-model-navigator.js`, `static/app/gbm-tab-orchestration.js`, and `static/styles/gbm.css`; SHAP, Stacked SHAP, and tree UI have their own `gbm-shap-*`, `gbm-stacked-shap-*`, and `gbm-tree-viewer.js` files. Backend behavior is under `tools/gbm/`.
+- Generic modelling shell: read `static/app/model-tool-shell.js` and `static/styles/model-shell.css`.
+- CSS changes: read `static/app.css` only to confirm import order. Put shared primitives in `styles/foundations.css` or `styles/controls.css`; put tool-specific selectors in the tool-owned stylesheet.
+- Static asset contract checks and frontend string contracts live in `tests/test_static_assets.py`; browser smoke coverage lives in `tests/test_browser_smoke.py`.
+
+## GBM Notes
+
+- GBM is opt-in via `--tools gbm` and optional Python dependencies from `pip install -e ".[gbm]"`.
+- LightGBM with its Arrow bridge, Polars/PyArrow, pandas, and numpy must be imported lazily in GBM training paths, not at base app import time. Large GBM matrices flow from DuckDB to Polars to numeric Arrow; pandas remains for compact artifacts, tabulations, and exports.
+- On macOS, LightGBM may need Homebrew `libomp`; missing native runtime errors should stay actionable rather than surfacing as server 500s.
+- GBM and GLM artifacts are sidecars under `.lucidum/datasets/<dataset-slug>/<dataset-signature>/models/` beside the dataset folder and must not be committed.
+- The GBM SHAP tab reads saved SHAP sidecars only. Keep SHAP aggregation in backend GBM modules, keep SHAP UI/chart code separate, return dense grids for 3D surfaces, and lazy-load vendored ECharts GL only for those surface plots.
+
+## Before Committing
+
+Use the tiered runner documented in `DEVELOPMENT.md`. The normal development
+loop selects focused tests from staged, unstaged, and untracked changes, with a
+safe fallback to the broad lane for shared or unknown files:
+
+```bash
+.venv/bin/python scripts/run_tests.py changed
+```
+
+The broad development lane runs syntax checks, non-browser modules, fast GLM
+contracts, and excludes slow modelling process integration cases:
+
+```bash
+.venv/bin/python scripts/run_tests.py dev
+```
+
+Use `focus` or `browser` with a specific target when you need to override the
+automatic selection. The fast commit gate runs staged and unstaged whitespace
+checks, dynamic syntax checks, and the change-aware unit lane:
+
+```bash
+.venv/bin/python scripts/run_tests.py precommit
+```
+
+The complete push gate runs full unittest discovery and all browser smoke tests
+after the same whitespace and syntax checks:
+
+```bash
+.venv/bin/python scripts/run_tests.py prepush
+```
+
+The versioned `.githooks/pre-commit` and `.githooks/pre-push` hooks run those
+commands automatically after one-time setup with
+`git config core.hooksPath .githooks`. Do not manually run `prepush`
+immediately before a normal `git push`, and do not weaken or bypass either hook
+merely to save time.
+
+- Before every commit, unless the user explicitly says not to, run `.venv/bin/python scripts/bump_version.py patch`. Include `pyproject.toml` in the same commit and report the final version number.
+
+Keep local datasets, `.lucidum/`, virtualenvs, caches, build artifacts, and generated README previews out of git.
+
+## Before Releasing
+
+- Release only a clean `main` commit whose hosted `CI` workflow passed. Run the
+  release-only pipx/build checks before tagging; the tag workflow repeats the
+  artifact and installed-wheel checks.
+- Make all release-preparation changes in one commit when a specific next
+  version is required. Apply the normal version bump once before that commit,
+  then create an annotated `vMAJOR.MINOR.PATCH` tag whose value exactly matches
+  `project.version` in `pyproject.toml`.
+- Do not create or push a release tag, publish or approve a production
+  deployment, move a released tag, or yank a release without explicit user
+  authorization. Repository changes alone do not imply permission for those
+  external actions.
+- PyPI filenames and versions cannot be reused, and published immutable GitHub
+  release tags/assets cannot be edited. Fix a bad published release by yanking
+  it when appropriate and publishing a higher patch version; never rebuild or
+  repoint the old version.
+- `py-lucidum==X.Y.Z` pins Lucidum only. It does not lock transitive dependency
+  versions; consuming projects should use their own lock or constraints file
+  when they need a reproducible complete environment.