gpclarity 0.0.2__tar.gz

gpclarity-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,135 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    
+    - name: Verify LICENSE exists  # ✅ Prevents cryptic hatchling errors
+      run: |
+        if [ ! -f LICENSE ]; then
+          echo "ERROR: LICENSE file not found. Create it before pushing."
+          exit 1
+        fi
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: 'pyproject.toml'
+
+    - name: Limit BLAS threads
+      run: |
+        echo "OPENBLAS_NUM_THREADS=1" >> $GITHUB_ENV
+        echo "OMP_NUM_THREADS=1" >> $GITHUB_ENV
+        echo "MKL_NUM_THREADS=1" >> $GITHUB_ENV
+
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y build-essential python3-dev gfortran libopenblas-dev
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        # ✅ Install build deps first (helps GPy compile)
+        pip install numpy cython
+        # ✅ Try to install GPy (use binary if available, else compile)
+        pip install GPy || pip install --no-binary :gpy: GPy
+        # ✅ Now install your package normally (no --no-build-isolation)
+        pip install -e ".[dev]"
+
+    - name: Run test suite
+      run: |
+        pytest tests/ \
+          --cov=gpclarity \
+          --cov-report=xml \
+          -v
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./coverage.xml
+        fail_ci_if_error: false
+
+    - name: Type checking
+      continue-on-error: true
+      run: mypy gpclarity/ --ignore-missing-imports
+
+    - name: Format checking
+      run: |
+        black --check gpclarity/ tests/
+        # isort --check-only gpclarity/ tests/
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    
+    - name: Build package
+      run: |
+        pip install build twine
+        python -m build
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-files
+        path: dist/
+
+  install-test:
+    name: Test Installation
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        install-method: [wheel, source]
+        python-version: ["3.9", "3.12"]
+    
+    steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - uses: actions/download-artifact@v4
+      with:
+        name: dist-files
+        path: dist/
+    
+    - name: Install
+      run: |
+        if [ "${{ matrix.install-method }}" == "wheel" ]; then
+          pip install dist/*.whl
+        else
+          pip install dist/*.tar.gz
+        fi
+    
+    - name: Verify
+      run: |
+        python -c "import gpclarity; print(gpclarity.__version__)"

gpclarity-0.0.2/.github/workflows/format_check.yml

@@ -0,0 +1,27 @@
+name: Format & Lint Check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  black_isort_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install black isort
+      - name: Show Black diff
+        run: black --diff gpdiagnostics/ tests/
+      - name: Show isort diff
+        run: isort --diff gpdiagnostics/ tests/
+      - name: Run Black check
+        run: black --check gpdiagnostics/ tests/

gpclarity-0.0.2/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gpclarity
+
+    permissions:
+      contents: read          # Needed to checkout repo
+      id-token: write         # For trusted publishing
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4  # v4 is latest stable
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        pip install build twine
+
+    - name: Build source and wheel distributions
+      run: |
+        python -m build
+
+    - name: Validate package
+      run: |
+        twine check dist/*
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@v1.8.7
+      with:
+        verbose: true
+        user: __token__         # Must set in GitHub Secrets
+        password: ${{ secrets.PYPI_API_TOKEN }}
+
+    - name: Upload release artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-files
+        path: dist/

gpclarity-0.0.2/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Testing
+.tox/
+.pytest_cache/
+.coverage
+.htmlcov/
+nosetests.xml
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Documentation
+docs/_build/
+_site/
+
+# Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Jupyter
+.ipynb_checkpoints
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json

gpclarity-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+        language_version: python3
+  
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.3.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        exclude: ^(examples/|tests/)
+  
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+  
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+        args: ["--max-line-length=88", "--extend-ignore=E203"]
+  
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ['--maxkb=1000']

gpclarity-0.0.2/.readthedocs.yaml

@@ -0,0 +1,31 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    #Verify index.rst exists in the build environment
+    post_checkout:
+      - echo "=== FORCING RTD TO USE LATEST MAIN ==="
+      - git fetch origin main
+      - git checkout main
+      - git reset --hard origin/main
+      - echo "=== Files in docs/ after reset ==="
+      - ls -la docs/
+      - echo "=== Verifying index.rst ==="
+      - test -f docs/index.rst
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Python requirements
+python:
+  install:
+    - requirements: docs/requirements.txt

gpclarity-0.0.2/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+title: "gpclarity: Gaussian Process Interpretability Toolkit"
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - given-names: Angad
+    family-names: Kumar
+repository-code: "https://github.com/AngadKumar16/gpclarity"
+url: "https://github.com/AngadKumar16/gpclarity"
+license: BSD-3-Clause
+version: 0.1.0
+date-released: 2026-01-26
+keywords:
+  - gaussian-process
+  - machine-learning
+  - interpretability
+  - uncertainty
+  - bayesian-optimization
+preferred-citation:
+  type: software
+  authors:
+    - given-names: Angad
+      family-names: Kumar
+  title: "gpclarity: Gaussian Process Interpretability Toolkit"
+  year: 2026
+  url: "https://github.com/AngadKumar16/gpclarity"

gpclarity-0.0.2/LICENSE

@@ -0,0 +1,37 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Angad Kumar
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Academic Citation Request (Non-Binding)
+
+If you use GPClarity in academic research, publications, or derived
+scientific work, we kindly request that you cite the software. Citation
+helps support continued development and enables recognition of open
+scientific infrastructure. See the CITATION.cff file for details.

gpclarity-0.0.2/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include CITATION.cff
+include CONTRIBUTING.md
+
+recursive-include gpclarity *.py
+recursive-include tests *.py
+recursive-include examples *.py
+
+recursive-include docs *.md *.rst *.py
+recursive-exclude docs _build
+
+prune .github
+prune .git
+prune __pycache__
+prune *.egg-info

gpclarity-0.0.2/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: gpclarity
+Version: 0.0.2
+Summary: Interpretability and Diagnostics Tools for Gaussian Processes
+Project-URL: Homepage, https://github.com/AngadKumar16/gpclarity
+Project-URL: Issues, https://github.com/AngadKumar16/gpclarity/issues
+Project-URL: Documentation, https://gpclarity.readthedocs.io
+Author-email: Angad Kumar <angadkumar16ak@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Angad Kumar
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+        
+        Academic Citation Request (Non-Binding)
+        
+        If you use GPClarity in academic research, publications, or derived
+        scientific work, we kindly request that you cite the software. Citation
+        helps support continued development and enables recognition of open
+        scientific infrastructure. See the CITATION.cff file for details.
+License-File: LICENSE
+Keywords: gaussian-process,interpretability,machine-learning,uncertainty
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: emukit>=0.4.0
+Requires-Dist: gpy>=1.10.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: isort>=5.12; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=1.0; extra == 'docs'
+Requires-Dist: nbsphinx>=0.9; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=1.2; extra == 'docs'
+Requires-Dist: sphinx>=5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# GPClarity: Gaussian Process Interpretability Toolkit
+![Python Version](https://img.shields.io/python/v/gpclarity)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Build Status](https://github.com/AngadKumar16/gpclarity/workflows/CI/badge.svg)
+
+**GPClarity** is a production-ready library that transforms black-box Gaussian Process models into interpretable, debuggable, and trustworthy tools. Built on GPy and emukit, it provides human-readable insights into kernel behavior, uncertainty patterns, and model complexity.
+
+---
+
+## 🎯 Features
+
+- 🔍 **Kernel Interpretation**: Translate raw kernel math into human meaning
+- 📊 **Uncertainty Profiling**: Visualize and diagnose uncertainty behavior
+- 📈 **Hyperparameter Tracking**: Monitor optimization dynamics in real-time
+- 🧮 **Complexity Quantification**: Measure and prevent overfitting
+- 🎯 **Data Influence Analysis**: Identify impactful training points
+- 🔗 **Emukit Integration**: Seamless Bayesian optimization support
+
+---
+
+## 🚀 Quick Start
+
+```python
+import gpclarity
+import GPy
+import numpy as np
+
+# Train a Gaussian Process
+X = np.linspace(0, 10, 50).reshape(-1, 1)
+y = np.sin(X).flatten() + 0.1 * np.random.randn(50)
+
+kernel = GPy.kern.RBF(1) + GPy.kern.White(1)
+model = GPy.models.GPRegression(X, y[:, None], kernel)
+model.optimize()
+
+summary = gpclarity.summarize_kernel(model)
+
+profiler = gpclarity.UncertaintyProfiler(model)
+X_test = np.linspace(-2, 12, 200).reshape(-1, 1)
+profiler.plot(X_test, X_train=X, y_train=y)
+
+tracker = gpclarity.HyperparameterTracker(model)
+history = tracker.wrapped_optimize(max_iters=50)
+tracker.plot_evolution()
+
+complexity = gpclarity.compute_complexity_score(model, X)
+print(f"Complexity: {complexity['score']:.2f} - {complexity['interpretation']}")
+```
+
+---
+
+## 📦 Installation
+
+### Stable Release
+```bash
+pip install gpclarity
+```
+
+### Development Version
+```bash
+git clone https://github.com/AngadKumar16/gpclarity.git
+cd gpclarity
+pip install -e ".[dev]"
+```
+
+### Conda (coming soon)
+```bash
+conda install -c conda-forge gpclarity
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+gpclarity/
+├── kernel_summary
+├── uncertainty_analysis
+├── hyperparam_tracker
+├── model_complexity
+├── data_influence
+└── utils
+```
+
+---
+
+## 🔬 Advanced Usage
+
+### Emukit Integration
+
+```python
+from gpclarity import ClarityBayesianOptimizationLoop
+
+loop = ClarityBayesianOptimizationLoop(model, space)
+loop.run_loop(user_function, stopping_condition)
+loop.plot_diagnostics()
+```
+
+### Batch Processing
+
+```python
+models = [model1, model2, model3]
+reports = [gpclarity.summarize_kernel(m, verbose=False) for m in models]
+```
+
+---
+
+## 📊 Example Outputs
+
+### Kernel Summary
+
+```
+🔍 KERNEL SUMMARY
+Structure: ['RBF', 'White']
+Components: 2
+
+📦 RBF (lengthscale)
+  └─ lengthscale: 1.23
+  💡 Moderate flexibility
+
+📦 White (variance)
+  └─ variance: 0.01
+  💡 Low observation noise
+```
+
+### Complexity Report
+
+```json
+{
+  "score": 2.34,
+  "interpretation": "Moderate complexity (well-balanced)",
+  "components": {
+    "n_kernel_parts": 2,
+    "roughness_score": 0.81,
+    "noise_ratio": 4.5
+  }
+}
+```
+
+---
+
+## 🎓 Citation
+
+```bibtex
+@software{gpclarity2026,
+  title={gpclarity: Gaussian Process Interpretability Toolkit},
+  author={Angad Kumar},
+  year={2026},
+  url={https://github.com/AngadKumar16/gpclarity},
+  version={0.1.0}
+}
+```
+## 📝 License
+
+GPClarity is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+## 🤝 Contributing
+
+Contributions are welcome!  
+
+- Report bugs or request features via [GitHub Issues](https://github.com/AngadKumar16/gpclarity/issues)
+- Submit pull requests for fixes or enhancements
+- Make sure to follow the code style and write tests for new features
+
+**Author:** Angad Kumar ([GitHub](https://github.com/AngadKumar16), [Email](mailto:angadkumar16ak@gmail.com))
+
+## 🛣️ Roadmap
+
+- Conda package support
+- More visualization tools for kernel decomposition
+- Automated tutorials / example notebooks
+- More features overall