# Technology Stack

## Architecture

Scikit-learn ecosystem library. All analysis classes extend `TransformerMixin` and `BaseEstimator`, following the sklearn transformer contract (`fit`, `transform`, `inverse_transform`). This enables composition with `Pipeline`, cross-validation, and standard ML workflows.

## Core Technologies

- **Language**: Python 3.11+
- **Build system**: Hatchling (`hatch-conda-build` backend)
- **Package manager**: uv

## Key Libraries

- **numpy** (>=1.20): Core array operations
- **scipy** (>=1.7): Optimization, linear algebra, special functions
- **scikit-learn** (>=1.5): Transformer/estimator base classes, parallel utilities
- **pandas** (>=2.1): Data handling with PyArrow backend

### Optional
- **matplotlib/plotly/seaborn**: Visualization (`plot` extras)
- **pooch**: Dataset download management (`data` extras)

## Development Standards

### Code Quality
- **Linter/formatter**: ruff (replaces flake8/black)
- **Docstrings**: NumPy-style with mathematical notation (reStructuredText math directives)
- **Type hints**: Gradual adoption using `from __future__ import annotations` and `numpy.typing`

### Testing
- **Framework**: pytest with pytest-cov, pytest-benchmark
- **Test co-location**: Each subpackage has a `tests/` subdirectory
- **Coverage**: Tracked via pytest-cov (omits deprecated `outline/` module)
- **CI matrix**: Ubuntu/macOS/Windows x Python 3.11/3.12

### Documentation
- **Engine**: Sphinx with pydata-sphinx-theme
- **Structure**: Diataxis framework (Tutorials, How-to, Explanation, API Reference)
- **Notebook support**: myst-nb for executable documentation

## Development Environment

### Required Tools
- Python 3.11+
- uv (package manager)

### Common Commands
```bash
# Install (dev): uv sync
# Test: pytest --cov=ktch --doctest-modules --ignore=docs --ignore=tasks.py
# Lint: ruff check ktch/ tests/
# Format: ruff format ktch/ tests/
# Docs build: cd doc && make html
# Docs serve: invoke serve
```

## Key Technical Decisions

- **Sklearn API contract**: All morphometric transformations are sklearn Transformers, enabling pipeline composition and cross-validation
- **Parallelization**: Uses `sklearn.utils.parallel.Parallel` and `delayed` with `n_jobs` parameter
- **Deprecation strategy**: Graceful migration via `__getattr__` hooks with `DeprecationWarning`, version-based removal timeline
- **Release management**: Semantic versioning with release-please, conventional commits for changelog generation

---
_Document standards and patterns, not every dependency_
