@relipa/ai-flow-kit 0.2.0-beta.2 → 0.2.1

package/custom/templates/python-ml.md

@@ -2,272 +2,4 @@
 
 You are an expert ML engineer. Follow these rules to produce reproducible, leakage-free, and production-ready ML/AI code. This template covers scikit-learn, PyTorch, TensorFlow/Keras, and experiment tracking (MLflow / wandb / DVC).
 
----
-
-## Project Structure
-
-```
-project/
-├── data/                # raw/, interim/, processed/ (git-ignored, DVC-tracked)
-├── notebooks/           # EDA only — not productionized code
-├── src/
-│   ├── data/            # loading + splitting
-│   ├── features/        # feature engineering (fit on train only)
-│   ├── models/          # model definitions + training entrypoints
-│   └── eval/            # metric + evaluation harness
-├── configs/             # YAML/Hydra hyperparameter configs
-├── experiments/         # tracked run outputs / logs
-├── models/              # saved artifacts (DVC/registry-tracked)
-├── requirements.txt     # pinned
-└── pyproject.toml
-```
-
----
-
-## Reproducibility Rules
-
-- Set **all seeds** before any randomness: `random.seed(n)`, `numpy.random.seed(n)`, and the framework seed.
-- Enable deterministic flags where feasible; document any performance trade-off.
-- **Pin the environment:** `requirements.txt` or a lockfile committed alongside every artifact.
-- Log the seed, config, and git commit SHA with every tracked run.
-
-```python
-# ✅ Good — set all seeds at entrypoint
-import random, numpy as np, torch
-
-def set_seed(seed: int) -> None:
-    random.seed(seed)
-    np.random.seed(seed)
-    torch.manual_seed(seed)
-    torch.use_deterministic_algorithms(True)
-```
-
----
-
-## Config Management
-
-- Hyperparameters live in YAML / Hydra / argparse configs — **never hardcoded**.
-- The config file is saved alongside every model artifact.
-
-```python
-# ✅ Good — load config from file
-from dataclasses import dataclass
-import yaml
-
-@dataclass
-class TrainConfig:
-    lr: float
-    max_epochs: int
-    batch_size: int
-    seed: int
-
-def load_config(path: str) -> TrainConfig:
-    with open(path) as f:
-        return TrainConfig(**yaml.safe_load(f))
-
-# ❌ Bad — hyperparameters hardcoded in training script
-lr = 0.001
-epochs = 50
-```
-
----
-
-## Leakage Prevention
-
-- **Split before fit** — perform the split BEFORE fitting any transformer, scaler, or encoder.
-- **Fit transforms on train fold only** — all preprocessing lives inside a `Pipeline` fit only on training data.
-- **Time-aware splits** — for temporal data, use `TimeSeriesSplit`; never shuffle time-indexed data.
-
-```python
-# ✅ Good — pipeline inside CV; transforms fit on train fold only
-from sklearn.pipeline import Pipeline
-from sklearn.preprocessing import StandardScaler
-from sklearn.linear_model import LogisticRegression
-from sklearn.model_selection import StratifiedKFold, cross_val_score
-
-pipe = Pipeline([
-    ("scaler", StandardScaler()),
-    ("clf", LogisticRegression()),
-])
-cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
-scores = cross_val_score(pipe, X_train, y_train, cv=cv, scoring="roc_auc")
-
-# ❌ Bad — scaler fit on full data before split (leakage)
-scaler = StandardScaler().fit(X)
-X_scaled = scaler.transform(X)
-X_train, X_test = train_test_split(X_scaled, ...)
-```
-
----
-
-## Framework Idioms
-
-### scikit-learn
-
-- Use `Pipeline` + `ColumnTransformer` for all preprocessing — never transform outside a pipeline.
-- Use `set_output(transform="pandas")` (sklearn ≥ 1.2) to preserve feature names.
-
-```python
-from sklearn.compose import ColumnTransformer
-from sklearn.preprocessing import StandardScaler, OneHotEncoder
-from sklearn.pipeline import Pipeline
-
-preprocessor = ColumnTransformer([
-    ("num", StandardScaler(), num_cols),
-    ("cat", OneHotEncoder(handle_unknown="ignore"), cat_cols),
-])
-pipe = Pipeline([("prep", preprocessor), ("model", clf)])
-```
-
-### PyTorch
-
-- Seed the `DataLoader` worker init function for full reproducibility.
-- Always switch between `model.train()` and `model.eval()` modes; use `torch.no_grad()` for validation.
-
-```python
-import torch
-from torch.utils.data import DataLoader
-
-def seed_worker(worker_id: int) -> None:
-    import random, numpy as np
-    worker_seed = torch.initial_seed() % (2**32)
-    random.seed(worker_seed)
-    np.random.seed(worker_seed)
-
-g = torch.Generator()
-g.manual_seed(42)
-loader = DataLoader(dataset, batch_size=32, worker_init_fn=seed_worker, generator=g)
-
-# Training loop
-model.train()
-for batch in train_loader:
-    ...
-
-# Validation loop
-model.eval()
-with torch.no_grad():
-    for batch in val_loader:
-        ...
-```
-
-### TensorFlow / Keras
-
-- Use callbacks for checkpointing (save best by validation metric) and early stopping.
-- Set `tf.random.set_seed` at startup.
-
-```python
-import tensorflow as tf
-
-tf.random.set_seed(42)
-
-callbacks = [
-    tf.keras.callbacks.ModelCheckpoint(
-        filepath="models/best.keras",
-        monitor="val_loss",
-        save_best_only=True,
-    ),
-    tf.keras.callbacks.EarlyStopping(
-        monitor="val_loss",
-        patience=5,
-        restore_best_weights=True,
-    ),
-]
-model.fit(X_train, y_train, validation_data=(X_val, y_val), callbacks=callbacks)
-```
-
-### HuggingFace (LLM fine-tuning)
-
-- Use a freeze/unfreeze schedule; start with a small learning rate and add warmup.
-- Log the base model name, adapter config, and dataset version alongside the run.
-
-```python
-from transformers import Trainer, TrainingArguments
-
-args = TrainingArguments(
-    output_dir="models/ft-run",
-    num_train_epochs=3,
-    learning_rate=2e-5,
-    warmup_ratio=0.1,
-    seed=42,
-    report_to="mlflow",
-)
-trainer = Trainer(model=model, args=args, train_dataset=train_ds, eval_dataset=val_ds)
-trainer.train()
-```
-
----
-
-## Experiment Tracking
-
-- Log params, metrics per epoch/fold, seed, data version, and git commit to MLflow or wandb.
-- Name each run per the scheme in `custom/rules/ml-conventions.md`: `[ticket-id]_[approach]_[yyyymmdd-n]`.
-- Version datasets with DVC; store the DVC data hash in the run metadata.
-
-```python
-import mlflow
-
-mlflow.set_experiment("my-project")
-with mlflow.start_run(run_name="ML-42_lgbm-tfidf_20241115-1"):
-    mlflow.log_params({"lr": cfg.lr, "seed": cfg.seed, "data_version": "v1.2"})
-    mlflow.log_metric("val_roc_auc", val_score)
-    mlflow.sklearn.log_model(pipe, artifact_path="model")
-```
-
----
-
-## Notebook Hygiene
-
-- `notebooks/` is for EDA and exploration only — not production code.
-- Productionized logic (features, models, eval) migrates to `src/` as importable modules.
-- Notebooks must not import from each other; shared utilities go to `src/`.
-- Clear outputs before committing notebooks (or use `nbstripout`).
-
----
-
-## Testing Rules
-
-- Use **Pytest** for all `src/` utilities.
-- Test the **metric harness** directly: assert known inputs produce the expected metric value.
-- Test **data-split functions** for leakage: verify no sample ID appears in both train and test sets.
-- Test feature-engineering functions independently with synthetic data.
-
-```python
-import pytest
-import numpy as np
-from src.eval.metrics import binary_roc_auc
-from src.data.splits import make_temporal_split
-
-def test_roc_auc_perfect_classifier():
-    y_true = np.array([0, 0, 1, 1])
-    y_score = np.array([0.1, 0.2, 0.8, 0.9])
-    assert binary_roc_auc(y_true, y_score) == pytest.approx(1.0)
-
-def test_temporal_split_no_leakage():
-    train_ids, test_ids = make_temporal_split(df, date_col="event_date", test_months=3)
-    overlap = set(train_ids) & set(test_ids)
-    assert len(overlap) == 0, f"Leakage: {len(overlap)} overlapping IDs"
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Module/package | snake_case | `feature_engineering.py` |
-| Class | PascalCase | `TemporalSplit`, `TrainConfig` |
-| Function/variable | snake_case | `train_model`, `val_score` |
-| Constant | UPPER_SNAKE_CASE | `DEFAULT_SEED`, `MAX_EPOCHS` |
-| Experiment run | `[ticket-id]_[approach]_[yyyymmdd-n]` | `ML-42_lgbm-tfidf_20241115-1` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Fitting scalers/encoders on the full dataset before splitting — always fit inside a `Pipeline` on the train fold only
-- ❌ Hardcoded hyperparameters — use configs
-- ❌ No seeds — always set `random`, `numpy`, and framework seeds
-- ❌ Evaluating on validation data used for tuning — keep a held-out test set for final Gate 4 reporting
-- ❌ Production logic in notebooks — migrate to `src/`
-- ❌ Committing data files or model binaries to git — track with DVC or a registry
-- ❌ Single aggregate metric without error analysis — always inspect failure cases and slices
+> **Rules & code examples:** Read `.rules/python/python-ml-rules.md` (structure, reproducibility, leakage prevention, framework idioms, naming, anti-patterns) and `.rules/python/python-ml-examples.md` (code samples per rule area) **in full** before writing or modifying any ML/AI code in this project.

package/custom/templates/python.md

@@ -1,79 +1,5 @@
-# Python AI System Prompt
-
-You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
-
----
-
-## Project Structure
-
-```
-project/
-├── main.py              # Entry point
-├── src/
-│   ├── service/         # Business logic
-│   ├── repository/      # Data access layer
-│   ├── model/           # Data classes / domain models
-│   └── util/            # Pure helper functions
-├── tests/               # Pytest suite
-├── requirements.txt
-└── pyproject.toml
-```
-
----
-
-## Python Rules
-
-- Use **type hints** on all function signatures and return types.
-- Follow **PEP 8** and keep functions small and single-purpose.
-- Use **dataclasses** or **NamedTuple** for value objects; avoid plain dicts for structured data.
-- Prefer **pathlib** over `os.path`; prefer `with` statements for file/resource handling.
-- Raise specific exceptions — never `raise Exception("message")`.
-
-```python
-# ✅ Good
-from dataclasses import dataclass
-
-@dataclass
-class UserRequest:
-    email: str
-    full_name: str
-
-def create_user(request: UserRequest) -> UserResponse:
-    if not request.email:
-        raise ValueError("email is required")
-    ...
-```
-
----
-
-## Testing Rules
-
-- Use **Pytest** for all tests.
-- Name test functions `test_<what>_<expected_outcome>`.
-- Use `pytest.raises` to assert exceptions.
-
-```python
-def test_create_user_raises_when_email_is_empty():
-    with pytest.raises(ValueError, match="email is required"):
-        create_user(UserRequest(email="", full_name="Test"))
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Module/package | snake_case | `user_service.py` |
-| Class | PascalCase | `UserService` |
-| Function/variable | snake_case | `find_by_id`, `user_id` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Bare `except:` — always catch a specific exception type
-- ❌ Mutable default arguments (`def f(x=[])`) — use `None` sentinel instead
-- ❌ Global state — pass dependencies explicitly
-- ❌ Returning `None` implicitly on error paths — raise or return a typed result
+# Python AI System Prompt
+
+You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
+
+> **Rules & code examples:** Read `.rules/python/python-rules.md` (structure, rules, naming, anti-patterns) and `.rules/python/python-examples.md` (code samples per rule area) **in full** before writing or modifying any Python code in this project.