glm-factor-optimizer 0.1.0__tar.gz

glm_factor_optimizer-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

glm_factor_optimizer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install project and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests -v
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install project and coverage dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Run coverage
+        run: python -m coverage run -m unittest discover -s tests -v
+
+      - name: Enforce coverage threshold
+        run: |
+          python -m coverage report --fail-under=70
+          python -m coverage xml
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install packaging tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/*

glm_factor_optimizer-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install packaging tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/glm-factor-optimizer
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

glm_factor_optimizer-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,103 @@
+name: Security
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install project and audit tooling
+        run: |
+          python -m pip install --upgrade pip setuptools
+          python -m pip install -e .[dev] pip-audit
+
+      - name: Run pip-audit
+        run: python -m pip_audit
+
+  bandit:
+    name: Bandit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install Bandit
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install bandit[toml]
+
+      - name: Run Bandit
+        run: bandit -q -r glm_factor_optimizer examples
+
+  gitleaks:
+    name: Gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install gitleaks
+        run: |
+          curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz -o gitleaks.tar.gz
+          tar -xzf gitleaks.tar.gz gitleaks
+          sudo install -m 755 gitleaks /usr/local/bin/gitleaks
+
+      - name: Run gitleaks
+        run: gitleaks detect --source . --redact --exit-code 1
+
+  codeql:
+    name: CodeQL
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+
+      - name: Install project dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4

glm_factor_optimizer-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+**/__pycache__/
+**/*.pyc
+.coverage
+.coverage.*
+.env
+.env.*
+.pytest_cache/
+.ruff_cache/
+.venv/
+runs/
+dist/**
+build/**
+*.egg-info/
+coverage.xml
+htmlcov/

glm_factor_optimizer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Contributions are welcome. Keep changes focused, add or update tests for behavioral changes, and update the public documentation when the user-facing API changes.
+
+## Local Setup
+
+Create a virtual environment and install the project in editable mode with development dependencies:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .[dev]
+```
+
+On Windows PowerShell, activate the environment with:
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+## Test And Coverage
+
+Run the full test suite:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Generate a local coverage report:
+
+```bash
+python -m coverage run -m unittest discover -s tests -v
+python -m coverage report
+python -m coverage xml
+```
+
+The default coverage target tracks the core package. The optional Spark backend
+is validated separately because its runtime integration test is gated behind an
+environment flag and extra dependencies.
+
+The optional Spark integration test is disabled by default. To run it locally, install the Spark extra and set the integration-test flag:
+
+```bash
+python -m pip install -e .[dev,spark]
+GLM_FACTOR_OPTIMIZER_RUN_SPARK_TESTS=1 python -m unittest tests.test_spark_backend -v
+```
+
+## Packaging Checks
+
+Before opening a release-oriented pull request, verify the package builds cleanly:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+## Pull Requests
+
+- Keep each pull request scoped to one change set.
+- Add regression tests for bug fixes and new features.
+- Prefer neutral, domain-free examples in public docs and examples.
+- Avoid committing generated artifacts, virtual environments, or local secrets.
+
+## Release Process
+
+Create and push a version tag like `v0.1.0` after the main branch is ready. The release workflow builds the distributions, runs a final Twine check, and publishes to PyPI via GitHub trusted publishing once the repository is configured as a trusted publisher in PyPI.

glm_factor_optimizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GLM Factor Optimizer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glm_factor_optimizer-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: glm-factor-optimizer
+Version: 0.1.0
+Summary: Domain-free GLM factor binning, grouping, and model design tools.
+Project-URL: Homepage, https://github.com/csabar/glm-factor-optimizer
+Project-URL: Repository, https://github.com/csabar/glm-factor-optimizer
+Project-URL: Documentation, https://github.com/csabar/glm-factor-optimizer/blob/main/docs/index.md
+Project-URL: Issues, https://github.com/csabar/glm-factor-optimizer/issues
+Author: GLM Factor Optimizer contributors
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: optuna>=3.0
+Requires-Dist: pandas>=1.5
+Requires-Dist: statsmodels>=0.14
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: hatchling>=1.21; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: mlflow
+Requires-Dist: mlflow>=2.0; extra == 'mlflow'
+Provides-Extra: spark
+Requires-Dist: pyspark>=3.5; extra == 'spark'
+Description-Content-Type: text/markdown
+
+# glm-factor-optimizer
+
+[![CI](https://github.com/csabar/glm-factor-optimizer/actions/workflows/ci.yml/badge.svg)](https://github.com/csabar/glm-factor-optimizer/actions/workflows/ci.yml)
+[![Security](https://github.com/csabar/glm-factor-optimizer/actions/workflows/security.yml/badge.svg)](https://github.com/csabar/glm-factor-optimizer/actions/workflows/security.yml)
+[![License](https://img.shields.io/github/license/csabar/glm-factor-optimizer)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+Simple GLM tools for factor binning, grouping, model screening, and workflow
+automation. The package is domain-free: it works for count-rate, positive
+continuous, and other small GLM modeling problems.
+
+Full project documentation is included in the source distribution under `docs/`
+and browsable on GitHub at
+[docs/index.md](https://github.com/csabar/glm-factor-optimizer/blob/main/docs/index.md).
+The docs are organized as tutorials, how-to guides, reference, and explanation.
+
+Use `RateGLM` for count-rate models:
+
+- count target, like `events`
+- exposure column, like `hours`
+- numeric or categorical factors
+
+```python
+from glm_factor_optimizer import RateGLM, split
+
+train, valid, holdout = split(df)
+
+glm = RateGLM(target="events", exposure="hours")
+
+score_spec = glm.bins(train, "score", bins=5)
+train = glm.apply(train, score_spec)
+valid = glm.apply(valid, score_spec)
+
+model = glm.fit(train, factors=[score_spec["output"], "segment"])
+valid = glm.predict(valid, model)
+
+report = glm.report(valid)
+print(report["summary"])
+```
+
+Use `GLM` for other families, such as Gamma cost or duration models:
+
+```python
+from glm_factor_optimizer import GLM
+
+glm = GLM(target="severity", family="gamma", prediction="predicted_severity")
+
+age_spec = glm.bins(train, "machine_age", bins=6)
+train = glm.apply(train, age_spec)
+valid = glm.apply(valid, age_spec)
+
+model = glm.fit(train, factors=[age_spec["output"], "equipment_type"])
+valid = glm.predict(valid, model)
+```
+
+Optimize one factor manually:
+
+```python
+result = glm.optimize(
+    train,
+    valid,
+    "score",
+    fixed=["segment"],
+    trials=50,
+)
+
+train = glm.apply(train, result.spec)
+valid = glm.apply(valid, result.spec)
+model = glm.fit(train, factors=[result.output, "segment"])
+```
+
+The same optimizer is also exposed as `optimize_bins`:
+
+```python
+from glm_factor_optimizer import optimize_bins
+
+result = optimize_bins(
+    train,
+    valid,
+    target="events",
+    exposure="hours",
+    factor="score",
+)
+```
+
+Add custom penalties with lambdas or named functions:
+
+```python
+from glm_factor_optimizer import small_bin_size_penalty, small_count_penalty
+
+result = glm.optimize(
+    train,
+    valid,
+    "score",
+    penalties={
+        "small_count": small_count_penalty(min_count=5, penalty=0.02),
+        "many_bins": lambda c: 0.01 * max(c["bin_count"] - 6, 0),
+        "gap": lambda c: max(c["validation_deviance"] - c["train_deviance"], 0),
+    },
+)
+```
+
+Penalty callables receive a context dictionary with the selected `spec`, the
+training `bin_table`, train/validation deviance, predictions, transformed
+dataframes, factor name, kind, and fixed factors.
+
+Rank candidate factors before detailed optimization:
+
+```python
+ranking = glm.rank(
+    train,
+    valid,
+    ["score", "segment", "region"],
+    factor_kinds={"segment": "categorical", "region": "categorical"},
+)
+print(ranking[["factor", "deviance_improvement"]])
+```
+
+Run a higher-level sequential workflow with optional ranking, logging, and
+interaction diagnostics:
+
+```python
+from glm_factor_optimizer import GLMWorkflow
+
+workflow = GLMWorkflow(
+    target="events",
+    family="poisson",
+    exposure="hours",
+    factor_kinds={"segment": "categorical"},
+    trials=50,
+    rank_candidates=True,
+    top_n=5,
+    interaction_diagnostics=True,
+    output_dir="runs",
+)
+
+result = workflow.fit(df, factors=["score", "segment"])
+print(result.validation_report["summary"])
+print(result.coefficients)
+```
+
+For notebook-style iterative model design, use `GLMStudy`:
+
+```python
+from glm_factor_optimizer import GLMStudy
+
+study = GLMStudy(
+    df,
+    target="events",
+    exposure="hours",
+    prediction="predicted_count",
+    factor_kinds={"segment": "categorical"},
+)
+
+study.split(seed=42)
+ranking = study.rank_candidates(["score", "segment", "region"])
+
+score = study.factor("score")
+score.coarse_bins(bins=10)
+score.optimize(trials=100, max_bins=6)
+score.compare()
+score.accept(comment="stable score shape")
+
+study.fit_main_effects()
+study.validation_report()
+
+refined = study.refine_factor("score", trials=200)
+refined.accept(comment="full-model refinement")
+
+study.find_interactions()
+study.finalize()
+study.save("runs")
+```
+
+Useful helper modules are available for manual workflows:
+
+```python
+from glm_factor_optimizer.aggregation import aggregate_rate_table
+from glm_factor_optimizer.diagnostics import find_interactions
+from glm_factor_optimizer.runs import RunLogger
+from glm_factor_optimizer.sampling import stratified_sample
+```
+
+Example synthetic datasets live under `examples/` and are not part of the
+installable package API. The examples cover general event-rate, severity, and
+Spark-style workflows across operational and service settings.
+
+Use the optional Spark backend in PySpark environments:
+
+```python
+from glm_factor_optimizer.spark import SparkGLM, SparkGLMWorkflow
+
+glm = SparkGLM(
+    target="events",
+    family="poisson",
+    exposure="hours",
+    prediction="predicted_count",
+)
+
+score_spec = glm.bins(train_sdf, "score", bins=8)
+train_sdf = glm.apply(train_sdf, score_spec)
+valid_sdf = glm.apply(valid_sdf, score_spec)
+
+model = glm.fit(train_sdf, factors=[score_spec["output"], "segment"])
+valid_sdf = glm.predict(valid_sdf, model)
+```
+
+Spark Optuna optimization runs Optuna on the driver and Spark GLM jobs inside
+each trial:
+
+```python
+result = glm.optimize(
+    train_sdf,
+    valid_sdf,
+    "score",
+    fixed=["segment"],
+    trials=30,
+    cache_input=True,
+    cache_trials=False,
+)
+```
+
+Install locally with Spark support using:
+
+```bash
+pip install "glm-factor-optimizer[spark]"
+```
+
+All binning and grouping specs are plain JSON-serializable dictionaries.
+
+## Contributing
+
+Development setup, test commands, coverage, and release notes are documented in
+[`CONTRIBUTING.md`](CONTRIBUTING.md).