Add core library, examples, crack segmentation app, and repo scaffolding

- scripts/: FisherAdapTuneTrainer, AdaFisher, fisher_core, utils
- crack_segmentation/: SAM2 and SegFormer fine-tuning with YAML configs and CLI
- examples/minimal_image_classifier.py: self-contained runnable example
- README, LICENSE (CC BY-NC-SA 4.0), CHANGELOG, CONTRIBUTING, CODE_OF_CONDUCT
- pyproject.toml, requirements.txt, Makefile, .gitignore, .pre-commit-config.yaml
- .github/: CI workflow and issue templates

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: RoseRostami

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Report a reproducible bug
+labels: bug
+---
+
+## Description
+
+A clear description of what the bug is.
+
+## Minimal Reproducible Example
+
+```python
+# Paste the smallest code that reproduces the problem
+```
+
+## Expected Behaviour
+
+What you expected to happen.
+
+## Actual Behaviour
+
+What actually happened (include the full traceback).
+
+## Environment
+
+- Python version:
+- PyTorch version:
+- GPU / CUDA version:
+- OS:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+## Motivation
+
+What problem does this feature solve? Which use case does it enable?
+
+## Proposed Solution
+
+Describe the change you'd like, including any API design ideas.
+
+## Alternatives Considered
+
+Any alternative approaches you've thought about.

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    name: Lint & type-check (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Format check
+        run: make format-check
+
+      - name: Lint
+        run: make lint
+
+      - name: Type check
+        run: make typecheck

.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging
+*.whl
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pre-commit-config.yaml.lock
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Checkpoints and model weights
+*.pt
+*.pth
+*.ckpt
+saved_models/
+
+# Logs and outputs
+wandb/
+logs/
+*.log
+
+# Data
+*.csv
+*.h5
+*.hdf5
+
+# OS
+.DS_Store
+Thumbs.db

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        args: [--config-file=pyproject.toml]
+        pass_filenames: false

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to FisherAdapTune will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-22
+
+### Added
+
+- `FisherAdapTuneTrainer`: model-agnostic plug-and-play trainer with Fisher-guided iterative chunk freezing
+- `AdaFisher`: diagonal Fisher Information Matrix optimizer used internally for Fisher statistic collection
+- `fisher_core`: chunking, Jensen-Shannon divergence tracking, masking, and iterative freeze logic
+- `EarlyStopping`, `save_checkpoint`, `plot_js_history` utilities
+- SAM2 crack segmentation application (`crack_segmentation/`) with YAML config and full CLI
+- Minimal runnable example using synthetic data (`examples/minimal_image_classifier.py`)
+- Support for `Linear`, `Conv2d`, `BatchNorm2d`, and `LayerNorm` layers
+- Decoupled weight decay applied only to active (unfrozen) parameter entries
+- Optional W&B logging and matplotlib JS-distance grid plots
+- `pyproject.toml` packaging, `Makefile` automation, pre-commit hooks

CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+## Our Standards
+
+We are committed to providing a welcoming and respectful environment for everyone.
+
+Expected behaviour:
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+
+Unacceptable behaviour:
+- Harassment, trolling, or personal attacks
+- Publishing others' private information without consent
+- Any conduct that would be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of unacceptable behaviour may be reported to **ghodsieh.rostami@gmail.com**.
+All reports will be reviewed and investigated promptly.
+
+This Code of Conduct is adapted from the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to FisherAdapTune
+
+We welcome bug reports, documentation improvements, and feature suggestions.
+
+## Reporting Issues
+
+Open a [GitHub Issue](https://github.com/<your-username>/FisherAdapTune/issues) and include:
+
+- A clear description of the problem
+- A minimal reproducible example (ideally using `examples/minimal_image_classifier.py`)
+- Your environment: Python version, PyTorch version, GPU, OS
+
+## Development Setup
+
+```bash
+git clone https://github.com/<your-username>/FisherAdapTune.git
+cd FisherAdapTune
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Code Style
+
+- Formatting and linting: [Ruff](https://docs.astral.sh/ruff/) (line length 100)
+- Type checking: mypy on annotated modules
+- Pre-commit hooks run automatically on `git commit`
+
+To run checks manually:
+
+```bash
+make check
+```
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch from `main`.
+2. Run `make check` before pushing.
+3. Open a PR with a clear description of what changed and why.
+
+All contributions must be for non-commercial purposes in line with the [CC BY-NC-SA 4.0 license](LICENSE).

LICENSE

@@ -0,0 +1,22 @@
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
+
+Copyright (c) 2026 Ghodsieh Rostami
+
+This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike
+4.0 International License.
+
+You are free to:
+  Share  — copy and redistribute the material in any medium or format
+  Adapt  — remix, transform, and build upon the material
+
+Under the following terms:
+  Attribution         — You must give appropriate credit, provide a link to the license,
+                        and indicate if changes were made.
+  NonCommercial       — You may not use the material for commercial purposes.
+  ShareAlike          — If you remix, transform, or build upon the material, you must
+                        distribute your contributions under the same license as the original.
+
+No additional restrictions — You may not apply legal terms or technological measures that
+legally restrict others from doing anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

Makefile

@@ -0,0 +1,46 @@
+.PHONY: help install install-dev install-hooks format format-check lint typecheck check fix clean
+
+help:
+	@echo "Available targets:"
+	@echo "  install        Install package (editable)"
+	@echo "  install-dev    Install package with dev dependencies"
+	@echo "  install-hooks  Install pre-commit git hooks"
+	@echo "  format         Auto-format code with Ruff"
+	@echo "  format-check   Verify formatting (no changes)"
+	@echo "  lint           Run Ruff lint checks"
+	@echo "  typecheck      Run mypy"
+	@echo "  check          Run full validation suite (format-check + lint + typecheck)"
+	@echo "  fix            Apply Ruff fixes, then rerun full checks"
+	@echo "  clean          Remove caches and build artifacts"
+
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e ".[dev,logging,plotting]"
+
+install-hooks:
+	pre-commit install
+
+format:
+	ruff format scripts/ crack_segmentation/ examples/
+
+format-check:
+	ruff format --check scripts/ crack_segmentation/ examples/
+
+lint:
+	ruff check scripts/ crack_segmentation/ examples/
+
+typecheck:
+	mypy scripts/
+
+check: format-check lint typecheck
+
+fix:
+	ruff check --fix scripts/ crack_segmentation/ examples/
+	ruff format scripts/ crack_segmentation/ examples/
+	$(MAKE) check
+
+clean:
+	rm -rf __pycache__ scripts/__pycache__ crack_segmentation/__pycache__ examples/__pycache__
+	rm -rf .mypy_cache .ruff_cache build dist *.egg-info