Upload 18 files

.dockerignore

@@ -0,0 +1,48 @@
+# --- Python / caches ---
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.ipynb_checkpoints/
+
+# --- Coverage / test artifacts ---
+.coverage
+htmlcov/
+coverage.xml
+
+# --- Packaging / build artifacts ---
+dist/
+build/
+*.egg-info/
+
+# --- Git / IDE ---
+.git/
+.vscode/
+.idea/
+
+# --- Env / secrets ---
+.env
+.env.*
+.envrc
+.streamlit/secrets.toml
+
+# --- OS junk ---
+.DS_Store
+Thumbs.db
+
+# --- Logs ---
+*.log
+logs/
+
+# --- Runtime artifacts (don’t bake into image) ---
+data/
+datasets/
+artifacts/
+models/
+outputs/
+runs/
+
+# --- Node (if any) ---
+node_modules/

.editorconfig

@@ -0,0 +1,27 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.{js,jsx,ts,tsx}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{bat,cmd,ps1}]
+end_of_line = crlf

.env.example

@@ -0,0 +1,4 @@
+# Optional runtime overrides for Docker / local runs
+HOST=0.0.0.0
+PORT=8501
+APP_FILE=app.py

.gitattributes

@@ -1,41 +1,17 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
-assets/compare-hist-kde-tips.png filter=lfs diff=lfs merge=lfs -text
-assets/compare-scatter-flights.png filter=lfs diff=lfs merge=lfs -text
-assets/matplotlib-iris-sepal-length-hist.png filter=lfs diff=lfs merge=lfs -text
-assets/matplotlib-iris-sepal-length-line.png filter=lfs diff=lfs merge=lfs -text
-assets/seaborn-tips-total-bill-hist-sex.png filter=lfs diff=lfs merge=lfs -text
-assets/seaborn-tips-total-bill-vs-tip-scatter.png filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# binaries (do not normalize / no eol)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.7z binary

.github/dependabot.yml

@@ -0,0 +1,48 @@
+version: 2
+
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    target-branch: "main"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Africa/Cairo"
+    open-pull-requests-limit: 2
+    rebase-strategy: "auto"
+    labels: ["dependencies", "python"]
+    groups:
+      python-patch-minor:
+        patterns: ["*"]
+        update-types: ["patch", "minor"]
+      python-major:
+        patterns: ["*"]
+        update-types: ["major"]
+    # Optional safety: keep major updates manual for heavy deps
+    # ignore:
+    #   - dependency-name: "numpy"
+    #     update-types: ["version-update:semver-major"]
+    #   - dependency-name: "pandas"
+    #     update-types: ["version-update:semver-major"]
+    #   - dependency-name: "scikit-learn"
+    #     update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "main"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "Africa/Cairo"
+    open-pull-requests-limit: 2
+    rebase-strategy: "auto"
+    labels: ["dependencies", "github-actions"]
+    groups:
+      actions-patch-minor:
+        patterns: ["*"]
+        update-types: ["patch", "minor"]
+      actions-major:
+        patterns: ["*"]
+        update-types: ["major"]

.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: ci
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -r requirements-dev.txt
+
+      - name: Basic sanity (compile)
+        run: python -m compileall -q .
+
+      - name: Ruff (lint + format check)
+        run: |
+          python -m ruff check .
+          python -m ruff format --check .
+
+      - name: Pytest
+        run: python -m pytest -q
+
+      - name: Docker present?
+        id: dockerfile
+        shell: bash
+        run: |
+          if [ -f Dockerfile ]; then echo "present=true" >> "$GITHUB_OUTPUT"; else echo "present=false" >> "$GITHUB_OUTPUT"; fi
+
+      - name: Set Docker image name (lowercase)
+        if: steps.dockerfile.outputs.present == 'true'
+        shell: bash
+        run: echo "IMAGE_NAME=$(echo '${{ github.event.repository.name }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+
+      - name: Set up Docker Buildx
+        if: steps.dockerfile.outputs.present == 'true'
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker test (build test stage)
+        if: steps.dockerfile.outputs.present == 'true'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          target: test
+          tags: ${{ env.IMAGE_NAME }}:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Docker build (runtime)
+        if: steps.dockerfile.outputs.present == 'true'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          target: runtime
+          tags: ${{ env.IMAGE_NAME }}:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,77 @@
+# =========================
+# Python
+# =========================
+__pycache__/
+*.py[cod]
+*.pyd
+*.egg-info/
+
+# Packaging / build
+dist/
+build/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+.venv.bak/
+venv.bak/
+
+# Environment variables / secrets
+.env
+.env.*
+!.env.example
+
+# Caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pytype/
+.pyre/
+
+# =========================
+# Tests / coverage
+# =========================
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+*.cover
+*.py,cover
+
+# =========================
+# Jupyter / notebooks
+# =========================
+.ipynb_checkpoints/
+*.ipynb~
+
+# =========================
+# Streamlit (keep config, ignore secrets)
+# =========================
+.streamlit/secrets.toml
+
+# Logs
+*.log
+logs/
+
+# Local databases (optional but common)
+*.db
+*.sqlite
+*.sqlite3
+
+# =========================
+# OS / IDE
+# =========================
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.iml
+.history/
+
+# =========================
+# Git
+# =========================
+*.orig

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+default_language_version:
+  python: python3.11
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: ["--maxkb=10240"]

.python-version

@@ -0,0 +1 @@
+3.11.9

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+This is a portfolio project. Issues and suggestions are welcome.
+
+## Ways to contribute
+- Report bugs (include steps to reproduce and logs).
+- Suggest improvements (UX, performance, reliability).
+- Propose small PRs (docs, tests, refactors).
+- Security issues: please avoid posting sensitive details publicly.
+
+## Dev setup
+
+From the repo root (inside a virtual environment):
+
+```bash
+python -m pip install -r requirements.txt
+python -m pip install -r requirements-dev.txt
+python -m ruff check .
+python -m ruff format --check .
+python -m pytest -q
+python -m streamlit run app.py

Makefile

@@ -0,0 +1,53 @@
+.PHONY: help install dev run lint lint-fix format test check precommit
+
+PY ?= python
+APP_FILE ?= app.py
+
+help:
+	@echo "Targets:"
+	@echo "  install      Install runtime deps (requirements.txt if present)"
+	@echo "  dev          Install dev deps (requirements-dev.txt if present)"
+	@echo "  run          Run app (Streamlit by default)"
+	@echo "  lint         Run ruff lint"
+	@echo "  lint-fix     Run ruff lint with fixes"
+	@echo "  format       Format code with ruff"
+	@echo "  check        Lint + format check + tests"
+	@echo "  test         Run pytest"
+	@echo "  precommit    Install pre-commit hooks"
+
+install:
+	$(PY) -m pip install -U pip
+ifneq ($(wildcard requirements.txt),)
+	$(PY) -m pip install -r requirements.txt
+endif
+	@$(PY) -m pip check || true
+
+dev:
+	$(PY) -m pip install -U pip
+ifneq ($(wildcard requirements-dev.txt),)
+	$(PY) -m pip install -r requirements-dev.txt
+endif
+	@$(PY) -m pip check || true
+
+run:
+	$(PY) -m streamlit run $(APP_FILE)
+
+lint:
+	$(PY) -m ruff check .
+
+lint-fix:
+	$(PY) -m ruff check . --fix --exit-non-zero-on-fix
+
+format:
+	$(PY) -m ruff format .
+
+test:
+	$(PY) -m pytest -q
+
+check: lint
+	$(PY) -m ruff format --check .
+	$(PY) -m pytest -q
+
+precommit:
+	$(PY) -m pip install -U pre-commit
+	pre-commit install

SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do **not** create a public GitHub issue for security vulnerabilities.
+
+Instead, use GitHub's private reporting flow:
+
+1. Go to this repository → **Security** tab
+2. Open **Advisories**
+3. Click **New draft security advisory**
+4. Include:
+   - a short description of the issue
+   - steps to reproduce (proof-of-concept if safe)
+   - affected versions/commits (if known)
+   - impact assessment (what an attacker can do)
+
+We will respond as soon as possible and coordinate a responsible disclosure.

pyproject.toml

@@ -0,0 +1,38 @@
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = [
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".ruff_cache",
+  ".mypy_cache",
+  "build",
+  "dist",
+  "artifacts",
+  "models",
+  "outputs",
+  "runs",
+  "data",
+  "datasets",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = []
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = ["S101"]  # allow assert in tests (safe)
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

requirements-dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+
+ruff==0.14.11
+pytest==8.3.4
+pre-commit==4.5.1

requirements.txt

@@ -1,6 +1,11 @@
-streamlit>=1.35
-pandas>=2.0
-numpy>=1.24
-matplotlib>=3.7
-seaborn>=0.13
-scipy>=1.10
+streamlit==1.52.2
+pandas==2.3.3
+numpy==2.4.1
+scikit-learn==1.8.0
+scipy==1.17.0
+plotly==5.24.0
+joblib==1.5.3
+
+
+matplotlib>=3.8,<4
+seaborn>=0.13,<0.14

scripts/doctor.py

@@ -0,0 +1,150 @@
+# scripts/doctor.py
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(cmd: list[str]) -> int:
+    return subprocess.call(cmd, cwd=str(ROOT))
+
+
+def has_file(name: str) -> bool:
+    return (ROOT / name).exists()
+
+
+def which(exe: str) -> str | None:
+    return shutil.which(exe)
+
+
+def banner(title: str) -> None:
+    print("\n" + "=" * 72)
+    print(title)
+    print("=" * 72)
+
+
+def info(k: str, v: str) -> None:
+    print(f"{k:<24} {v}")
+
+
+def warn(msg: str) -> None:
+    print(f"[WARN] {msg}")
+
+
+def fail(msg: str) -> None:
+    print(f"[FAIL] {msg}")
+
+
+def ok(msg: str) -> None:
+    print(f"[OK]   {msg}")
+
+
+def parse_min_python() -> tuple[int, int]:
+    # Default policy for the kit; override via env if needed.
+    v = os.getenv("MIN_PYTHON", "3.11").strip()
+    parts = v.split(".")
+    return int(parts[0]), int(parts[1])
+
+
+def check_python_version() -> bool:
+    min_major, min_minor = parse_min_python()
+    if sys.version_info >= (min_major, min_minor):
+        ok(f"Python version >= {min_major}.{min_minor} ({sys.version.split()[0]})")
+        return True
+    fail(f"Python too old: {sys.version.split()[0]} < {min_major}.{min_minor}")
+    return False
+
+
+def check_venv() -> None:
+    in_venv = sys.prefix != sys.base_prefix
+    info("In venv", str(in_venv))
+    if not in_venv:
+        warn("Not in a virtualenv. Recommended: create .venv and activate it.")
+
+
+def suggest_install() -> None:
+    banner("Suggested setup commands")
+    py = sys.executable
+    if has_file("requirements-dev.txt"):
+        print(f"{py} -m pip install -U pip")
+        print(f"{py} -m pip install -r requirements-dev.txt")
+    elif has_file("requirements.txt"):
+        print(f"{py} -m pip install -U pip")
+        print(f"{py} -m pip install -r requirements.txt")
+        warn("requirements-dev.txt not found (dev tooling may be missing).")
+    else:
+        warn("No requirements*.txt found.")
+
+
+def check_tools() -> None:
+    banner("Tooling")
+    py = sys.executable
+    # Try importing these only if installed; don't crash the script.
+    for mod in ["ruff", "pytest"]:
+        code = run([py, "-c", f"import {mod}"])
+        if code == 0:
+            ok(f"import {mod}")
+        else:
+            warn(f"{mod} not importable (install dev deps).")
+
+    pc = which("pre-commit")
+    if pc:
+        ok("pre-commit found in PATH")
+    else:
+        warn("pre-commit not found in PATH (optional, but recommended).")
+
+
+def run_checks() -> int:
+    banner("Running checks")
+    py = sys.executable
+    steps = [
+        ([py, "-m", "ruff", "check", "."], "ruff check"),
+        ([py, "-m", "ruff", "format", "--check", "."], "ruff format --check"),
+        ([py, "-m", "pytest", "-q"], "pytest"),
+    ]
+    rc = 0
+    for cmd, name in steps:
+        print(f"\n$ {' '.join(cmd)}")
+        code = run(cmd)
+        if code != 0:
+            fail(f"{name} failed (exit={code})")
+            rc = code
+            break
+        ok(f"{name} passed")
+    return rc
+
+
+def main() -> int:
+    banner("Doctor")
+    info("OS", f"{platform.system()} {platform.release()}")
+    info("Python", sys.version.splitlines()[0])
+    info("Repo", str(ROOT))
+
+    py_ok = check_python_version()
+    check_venv()
+
+    banner("Project files")
+    for f in ["pyproject.toml", "requirements.txt", "requirements-dev.txt", "Dockerfile"]:
+        info(f, "present" if has_file(f) else "missing")
+
+    check_tools()
+    suggest_install()
+
+    if not py_ok:
+        return 2
+
+    if "--check" in sys.argv:
+        return run_checks()
+
+    print("\nTip: run `python scripts/doctor.py --check`")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_smoke.py

@@ -0,0 +1,63 @@
+import importlib
+import importlib.util
+import os
+import sys
+
+
+def _parse_version(v: str) -> tuple[int, int]:
+    parts = v.strip().split(".")
+    if len(parts) < 2:
+        raise ValueError("MIN_PYTHON must be like '3.10' or '3.11'")
+    return int(parts[0]), int(parts[1])
+
+
+def test_smoke_python_version():
+    min_py = os.getenv("MIN_PYTHON", "3.11")
+    assert sys.version_info >= _parse_version(min_py)
+
+
+def test_smoke_core_imports():
+    """
+    Fast fail if core dependencies are broken.
+
+    Configure via:
+      SMOKE_IMPORTS="numpy,pandas,sklearn,streamlit,plotly"
+    """
+    imports = os.getenv("SMOKE_IMPORTS", "")
+    if not imports.strip():
+        return
+
+    for mod in [m.strip() for m in imports.split(",") if m.strip()]:
+        importlib.import_module(mod)
+
+
+def test_smoke_project_module_importable():
+    """
+    Ensure the main project module imports.
+    Configure via:
+      PROJECT_MODULE="your_package_name"
+    """
+    module = os.getenv("PROJECT_MODULE", "").strip()
+    if not module:
+        return
+    importlib.import_module(module)
+
+
+def test_smoke_app_importable():
+    """
+    Importing the app module should not execute heavy work at import-time.
+
+    This kit doesn't ship `app.py` because it varies per project. So we:
+    - Try to import the module if present
+    - Otherwise, skip silently (new project will add app.py later)
+
+    Override via:
+      APP_MODULE="app"  (default)
+    """
+    app_module = os.getenv("APP_MODULE", "app").strip()
+
+    # If the module isn't present yet, skip.
+    if importlib.util.find_spec(app_module) is None:
+        return
+
+    importlib.import_module(app_module)