mineproductivity 2.0.0__tar.gz

mineproductivity-2.0.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

mineproductivity-2.0.0/.gitattributes

@@ -0,0 +1,15 @@
+* text=auto eol=lf
+
+*.py text diff=python
+*.md text
+*.yml text
+*.yaml text
+*.toml text
+*.json text
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.parquet binary

mineproductivity-2.0.0/.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# Default owner
+* @imanojkumar
+
+/docs/architecture/ @imanojkumar
+/ROADMAP.md @imanojkumar
+/README.md @imanojkumar
+
+/src/mineproductivity/core/ @imanojkumar
+/src/mineproductivity/ontology/ @imanojkumar
+/src/mineproductivity/events/ @imanojkumar
+/src/mineproductivity/registry/ @imanojkumar
+/src/mineproductivity/plugins/ @imanojkumar
+/src/mineproductivity/connectors/ @imanojkumar
+/src/mineproductivity/kpis/ @imanojkumar
+/src/mineproductivity/analytics/ @imanojkumar
+/src/mineproductivity/decision/ @imanojkumar
+/src/mineproductivity/digital_twin/ @imanojkumar
+/src/mineproductivity/simulation/ @imanojkumar
+/src/mineproductivity/optimization/ @imanojkumar
+/src/mineproductivity/agents/ @imanojkumar
+/src/mineproductivity/visualization/ @imanojkumar
+
+/.github/workflows/ @imanojkumar
+/docs/governance/ @imanojkumar

mineproductivity-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Report a defect in MineProductivity
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Describe the bug
+
+A clear and concise description of the bug.
+
+## Affected package(s)
+
+e.g. `src/mineproductivity/kpis`
+
+## To Reproduce
+
+Steps to reproduce the behavior.
+
+## Expected behavior
+
+What you expected to happen.
+
+## Environment
+
+- MineProductivity version:
+- Python version:
+- OS:
+
+## Additional context
+
+Add any other context, logs, or screenshots.

mineproductivity-2.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: https://github.com/imanojkumar/MineProductivity/security/advisories/new
+    about: Please report security vulnerabilities privately, per SECURITY.md.
+  - name: Discussions
+    url: https://github.com/imanojkumar/MineProductivity/discussions
+    about: Ask questions and discuss ideas with the community.

mineproductivity-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Propose a new capability for MineProductivity
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Is your feature request related to a problem?
+
+A clear and concise description of the problem.
+
+## Describe the solution you'd like
+
+What you want to happen, and which package(s) it affects
+(e.g. `src/mineproductivity/analytics`).
+
+## Architectural alignment
+
+Explain how this aligns with the Master Architecture Handbook v1.0 / Reference
+Implementation Blueprint v1.0. New top-level packages or structural changes
+require architectural justification.
+
+## Alternatives considered
+
+Any alternative solutions or features you've considered.
+
+## Additional context
+
+Add any other context here.

mineproductivity-2.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Related Issue(s)
+
+<!-- Closes #... -->
+
+## Affected Package(s)
+
+<!-- e.g. src/mineproductivity/kpis, tests/unit/kpis -->
+
+## Checklist
+
+- [ ] Change respects the dependency direction documented in the root `README.md`.
+- [ ] Architecture principles in the Handbook have not been violated.
+- [ ] Tests added/updated in the mirrored `tests/` location.
+- [ ] Package `README.md` updated if responsibilities/dependencies changed.
+- [ ] Public APIs and new modules are documented.
+- [ ] `pre-commit run --all-files` passes locally.
+- [ ] No business logic added beyond this repository's current phase (see `ROADMAP.md`).
+
+## Additional Notes
+
+<!-- Anything reviewers should know. -->

mineproductivity-2.0.0/.github/workflows/benchmark.yml

@@ -0,0 +1,34 @@
+name: Benchmark
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: benchmark-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  perf-smoke:
+    name: Performance smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - run: pip install -e ".[analytics]"
+
+      # A tripwire, not a benchmark: generous wall-clock ceilings meant
+      # to catch a catastrophic regression (an accidental O(n^2), a
+      # broken cache, a per-call re-import), not to track performance
+      # over time. See scripts/quality/perf_smoke.py and
+      # benchmark/README.md for the real (future) benchmark suite this
+      # is deliberately not a substitute for.
+      - run: python scripts/quality/perf_smoke.py

mineproductivity-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,151 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # pyproject.toml declares `requires-python = ">=3.12"`; the matrix
+        # covers exactly the Python versions the package supports. Earlier
+        # versions (3.10/3.11) are not included here because `pip install`
+        # rejects them outright before any test runs -- a job for them can
+        # never pass and would only ever be permanently-red noise, not a
+        # useful compatibility signal.
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install mineproductivity[dev]
+        run: pip install -e ".[dev]"
+
+      - name: Install registry fixture plugin packages
+        # Must run before pytest starts: these are editable installs that
+        # write .pth files, which Python's site module only reads at
+        # interpreter startup. Installing them from inside a running pytest
+        # process (as tests/integration/conftest.py's session fixture does)
+        # cannot make them importable in that same process.
+        run: |
+          pip install --no-deps -e tests/fixtures/plugins/registry_fixture_healthy
+          pip install --no-deps -e tests/fixtures/plugins/registry_fixture_broken
+
+      - name: Run tests with coverage
+        run: pytest --cov=mineproductivity --cov-report=term-missing --cov-report=xml --cov-fail-under=95
+
+      - name: Upload coverage report
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+          retention-days: 14
+
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build distribution artifacts
+        run: python -m build
+
+      - name: twine check
+        run: twine check --strict dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14
+
+  install-wheel:
+    name: Install validation — wheel (${{ matrix.os }})
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install from wheel
+        shell: bash
+        run: pip install dist/*.whl
+
+      - name: Smoke test
+        run: python scripts/quality/smoke_test.py
+
+  install-methods:
+    name: Install validation — sdist / editable / GitHub
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install from sdist
+        run: |
+          python -m venv /tmp/venv-sdist
+          /tmp/venv-sdist/bin/pip install dist/*.tar.gz
+          /tmp/venv-sdist/bin/python scripts/quality/smoke_test.py
+
+      - name: Install editable
+        run: |
+          python -m venv /tmp/venv-editable
+          /tmp/venv-editable/bin/pip install -e .
+          /tmp/venv-editable/bin/python scripts/quality/smoke_test.py
+
+      - name: Install from GitHub at this commit
+        env:
+          COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          python -m venv /tmp/venv-github
+          /tmp/venv-github/bin/pip install "git+https://github.com/${{ github.repository }}.git@${COMMIT_SHA}"
+          /tmp/venv-github/bin/python scripts/quality/smoke_test.py

mineproductivity-2.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,30 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Mondays 06:00 UTC -- catches newly-published CodeQL query
+    # advisories against unchanged code, not just new commits.
+    - cron: "0 6 * * 1"
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

mineproductivity-2.0.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,25 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  dependency-review:
+    name: Scan dependency changes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Dependency review
+        uses: actions/dependency-review-action@v4
+        with:
+          # A patch release with a known CVE is a real, actionable risk;
+          # a permissive-but-unusual license on a new dependency is worth
+          # a human's attention before merge, not an automatic block.
+          fail-on-severity: moderate
+          comment-summary-in-pr: always

mineproductivity-2.0.0/.github/workflows/docs.yml

@@ -0,0 +1,98 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "ROADMAP.md"
+      - "CONTRIBUTING.md"
+      - "CODE_OF_CONDUCT.md"
+      - "SECURITY.md"
+      - "src/mineproductivity/**"
+      - "examples/**/README.md"
+      - "benchmark/reports/**"
+      - "scripts/docs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "ROADMAP.md"
+      - "CONTRIBUTING.md"
+      - "CODE_OF_CONDUCT.md"
+      - "SECURITY.md"
+      - "src/mineproductivity/**"
+      - "examples/**/README.md"
+      - "benchmark/reports/**"
+      - "scripts/docs/**"
+      - ".github/workflows/docs.yml"
+  # Allow manual runs from the Actions tab.
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build documentation site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      # The docs extra installs mkdocs-material + mkdocstrings; the editable
+      # package install lets mkdocstrings import mineproductivity to render
+      # the API reference from its docstrings (the base install is
+      # dependency-free, so no extras are required for import).
+      - run: pip install -e ".[docs]"
+
+      # --strict fails the build on any broken internal link or warning.
+      # Links that intentionally point at repository source files (outside
+      # the docs tree) are rewritten to absolute GitHub URLs by the hook in
+      # scripts/docs/link_rewrite_hook.py, so they neither break the site
+      # nor trip --strict.
+      - name: Build the documentation site (strict)
+        run: mkdocs build --strict
+
+      - name: Upload the built site as a workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 14
+
+      - name: Upload the GitHub Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    # Only publish from main; pull requests build (above) but never deploy.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy the GitHub Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@v4

mineproductivity-2.0.0/.github/workflows/quality.yml

@@ -0,0 +1,87 @@
+name: Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format --check
+        run: ruff format --check .
+
+  typecheck:
+    name: Mypy (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - run: mypy
+
+  docs-validation:
+    name: Documentation (links + snippets)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[analytics]"
+      - run: python scripts/quality/check_docs.py
+
+  notebooks:
+    name: Execute notebooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - name: Register the execution kernel
+        run: python -m ipykernel install --user --name ci-kernel
+      - name: Execute every notebook
+        run: |
+          set -e
+          shopt -s globstar nullglob
+          notebooks=(notebooks/**/*.ipynb)
+          if [ ${#notebooks[@]} -eq 0 ]; then
+            echo "no notebooks found"
+            exit 0
+          fi
+          for notebook in "${notebooks[@]}"; do
+            echo "executing $notebook"
+            # jupyter nbconvert --execute raises CellExecutionError (non-zero
+            # exit) on the first cell that fails; combined with `set -e`
+            # above, that's the only failure signal this job needs.
+            jupyter nbconvert --to notebook --execute --inplace \
+              --ExecutePreprocessor.kernel_name=ci-kernel \
+              --ExecutePreprocessor.timeout=120 \
+              "$notebook"
+          done

mineproductivity-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build + verify distribution artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: twine check
+        run: twine check --strict dist/*
+
+      - name: Verify the tag matches the package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(python -c "import re, pathlib; print(re.search(r'__version__\s*=\s*\"([^\"]+)\"', pathlib.Path('src/mineproductivity/__init__.py').read_text()).group(1))")"
+          echo "tag=$TAG_VERSION package=$PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match src/mineproductivity/__init__.py's __version__ ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 90
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create the GitHub Release with the built artifacts attached
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            dist/* \
+            --title "${{ github.ref_name }}" \
+            --generate-notes \
+            --notes "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for the curated release notes.
+
+          ---
+          "
+
+  # ---------------------------------------------------------------------
+  # PyPI publishing is intentionally NOT enabled yet (Milestone C: "Do NOT
+  # publish to PyPI"). When the maintainer decides to publish, add a PyPI
+  # Trusted Publisher (https://docs.pypi.org/trusted-publishers/) for this
+  # repository/workflow, then uncomment the job below -- no API token is
+  # needed with Trusted Publishing (OIDC-based).
+  # ---------------------------------------------------------------------
+  # publish-pypi:
+  #   name: Publish to PyPI
+  #   needs: build
+  #   runs-on: ubuntu-latest
+  #   environment: pypi
+  #   permissions:
+  #     id-token: write  # required for OIDC Trusted Publishing
+  #   steps:
+  #     - uses: actions/download-artifact@v4
+  #       with:
+  #         name: dist
+  #         path: dist/
+  #     - uses: pypa/gh-action-pypi-publish@release/v1