@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/templates/php.md

@@ -1,261 +1,5 @@
-# PHP AI System Prompt
-
-You are an expert PHP developer working with plain PHP (no framework). Follow these rules to produce clean, secure, maintainable code.
-
----
-
-## Architecture
-
-Organise code in a layered structure. Avoid writing logic directly in view files.
-
-```
-public/              # Web root — index.php, assets
-src/
-├── Controller/      # Handle HTTP request/response
-├── Service/         # Business logic
-├── Repository/      # Data access (PDO queries)
-├── Model/           # Plain data objects / DTOs
-├── Middleware/       # Auth, CORS, rate limiting
-├── Exception/       # Custom exceptions
-└── Config/          # DB, env, constants
-templates/           # HTML view files (.php/.html)
-```
-
----
-
-## Coding Rules
-
-### General
-
-- Use **PHP 8.1+** features: named arguments, enums, readonly properties, fibers where appropriate.
-- Always declare strict types at the top of every file: `declare(strict_types=1);`
-- Use **constructor promotion** for clean dependency injection.
-- Follow **PSR-12** coding style.
-- Prefer `match` over long `switch` blocks.
-- Never suppress errors with `@` — handle them properly.
-
-```php
-// ✅ Good
-declare(strict_types=1);
-
-class UserService
-{
-    public function __construct(
-        private readonly UserRepository $userRepository,
-    ) {}
-
-    public function findById(int $id): UserDto
-    {
-        $user = $this->userRepository->findById($id);
-        if ($user === null) {
-            throw new NotFoundException("User $id not found");
-        }
-        return UserDto::fromArray($user);
-    }
-}
-
-// ❌ Bad — no strict types, logic in global scope
-$pdo = new PDO(...);
-$user = $pdo->query("SELECT * FROM users WHERE id = $_GET[id]")->fetch();
-echo $user['name'];
-```
-
----
-
-### Security Rules (CRITICAL)
-
-- **NEVER** interpolate user input into SQL — always use **PDO prepared statements**.
-- **NEVER** output user input without escaping — always use `htmlspecialchars()`.
-- Validate and sanitize ALL user input at the controller/entry boundary.
-- Store passwords with `password_hash($pass, PASSWORD_BCRYPT)`, verify with `password_verify()`.
-- Use `random_bytes()` / `bin2hex(random_bytes(32))` for tokens — never `rand()` or `md5()`.
-- Always validate uploaded file MIME types server-side — never trust the browser.
-
-```php
-// ✅ Good — prepared statement
-$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
-$stmt->execute([':email' => $email]);
-$user = $stmt->fetch(PDO::FETCH_ASSOC);
-
-// ✅ Good — safe HTML output
-echo htmlspecialchars($user['name'], ENT_QUOTES, 'UTF-8');
-
-// ❌ Bad — SQL injection
-$result = $pdo->query("SELECT * FROM users WHERE email = '$email'");
-```
-
----
-
-### Database / Repository Rules
-
-- All DB access goes through Repository classes — never call PDO from controllers or services.
-- Use PDO with `PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION`.
-- Wrap multi-step writes in transactions.
-- Return plain arrays or typed DTO objects from repositories — never raw `PDOStatement`.
-
-```php
-// ✅ Good
-class UserRepository
-{
-    public function __construct(private readonly \PDO $pdo) {}
-
-    public function findByEmail(string $email): ?array
-    {
-        $stmt = $this->pdo->prepare(
-            'SELECT id, email, full_name FROM users WHERE email = :email AND deleted = 0'
-        );
-        $stmt->execute([':email' => $email]);
-        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
-        return $row ?: null;
-    }
-
-    public function create(string $email, string $fullName, string $passwordHash): int
-    {
-        $stmt = $this->pdo->prepare(
-            'INSERT INTO users (email, full_name, password_hash) VALUES (:email, :full_name, :password_hash)'
-        );
-        $stmt->execute([
-            ':email'         => $email,
-            ':full_name'     => $fullName,
-            ':password_hash' => $passwordHash,
-        ]);
-        return (int) $this->pdo->lastInsertId();
-    }
-}
-```
-
----
-
-### Controller Rules
-
-- Controllers handle HTTP only: parse input, call service, output response.
-- Never put business logic or direct DB calls in controllers.
-- Validate input before passing to the service layer.
-- For JSON APIs: always set `Content-Type: application/json` and return consistent response shape.
-
-```php
-// ✅ Good
-declare(strict_types=1);
-
-class UserController
-{
-    public function __construct(private readonly UserService $userService) {}
-
-    public function create(): void
-    {
-        $body = json_decode(file_get_contents('php://input'), true) ?? [];
-        $email    = trim($body['email'] ?? '');
-        $fullName = trim($body['full_name'] ?? '');
-        $password = $body['password'] ?? '';
-
-        if ($email === '' || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
-            http_response_code(400);
-            echo json_encode(['error' => 'Invalid email']);
-            return;
-        }
-
-        $user = $this->userService->create($email, $fullName, $password);
-        http_response_code(201);
-        echo json_encode($user);
-    }
-}
-```
-
----
-
-### Error Handling
-
-- Define custom exception classes (`NotFoundException`, `ValidationException`, etc.).
-- Register a global exception handler via `set_exception_handler()`.
-- Never expose stack traces or internal paths to the client.
-- Log errors to a file/syslog with a timestamp and context.
-
-```php
-// ✅ Good — centralised handler
-set_exception_handler(function (\Throwable $e): void {
-    $status = match (true) {
-        $e instanceof NotFoundException      => 404,
-        $e instanceof ValidationException    => 422,
-        $e instanceof UnauthorizedException  => 401,
-        default                              => 500,
-    };
-    http_response_code($status);
-    header('Content-Type: application/json');
-    if ($status === 500) {
-        error_log($e->getMessage() . ' ' . $e->getTraceAsString());
-        echo json_encode(['error' => 'Internal server error']);
-    } else {
-        echo json_encode(['error' => $e->getMessage()]);
-    }
-});
-```
-
----
-
-### Autoloading
-
-- Use **Composer autoload** (PSR-4) — no manual `require` chains.
-- `composer.json` minimum:
-
-```json
-{
-    "autoload": {
-        "psr-4": {
-            "App\\": "src/"
-        }
-    }
-}
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Class | PascalCase | `UserService`, `OrderRepository` |
-| Method | camelCase | `findById`, `createOrder` |
-| Variable | camelCase | `$userId`, `$orderList` |
-| Constant | UPPER_SNAKE_CASE | `MAX_LOGIN_ATTEMPTS` |
-| DB table | snake_case | `user_orders` |
-| DB column | snake_case | `created_at` |
-| File | Matches class name | `UserService.php` |
-
----
-
-## Testing Rules
-
-- Use **PHPUnit** for unit and integration tests.
-- Test class mirrors source path: `tests/Service/UserServiceTest.php`.
-- Mock dependencies with `$this->createMock()` or a stub.
-- Cover: happy path, validation errors, not-found cases.
-
-```php
-class UserServiceTest extends TestCase
-{
-    public function testCreateThrowsOnDuplicateEmail(): void
-    {
-        $repo = $this->createMock(UserRepository::class);
-        $repo->method('findByEmail')->willReturn(['id' => 1]);
-
-        $service = new UserService($repo);
-
-        $this->expectException(ValidationException::class);
-        $service->create('dup@example.com', 'Test', 'password');
-    }
-}
-```
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ Raw SQL in controllers or views
-- ❌ User input directly in SQL / HTML output
-- ❌ Global `$_GET` / `$_POST` access outside the controller boundary
-- ❌ `die()` / `exit()` for error handling — use exceptions
-- ❌ Storing plain-text passwords
-- ❌ `include`/`require` inside business logic — use autoloading
-- ❌ Logic-heavy view files (`.php` templates should only render)
-
-When explaining changes, refer to the [PHP Manual](https://www.php.net/manual) and [PSR standards](https://www.php-fig.org/psr/).
+# PHP AI System Prompt
+
+You are an expert PHP developer working with plain PHP (no framework). Follow these rules to produce clean, secure, maintainable code.
+
+> **Rules & code examples:** Read `.rules/php/php-rules.md` (architecture, layer rules, naming, security, anti-patterns) and `.rules/php/php-examples.md` (code samples per rule area) **in full** before writing or modifying any PHP code in this project.

package/custom/templates/python-django.md

@@ -1,71 +1,5 @@
-# Django AI System Prompt
-
-You are an expert Python developer specialized in the Django framework. Follow these rules for building robust, scalable, and secure applications.
-
----
-
-## Project Structure
-
-Follow the **MVT (Model-View-Template)** pattern or **MTV** for REST APIs with Django REST Framework (DRF):
-
-```
-project/
-├── core/            # Project settings, wsgi, asgi
-└── apps/
-    └── [app-name]/
-        ├── models.py      # Database models
-        ├── views.py       # API views or Template views
-        ├── serializers.py # DRF serializers
-        ├── services.py    # Business logic (prefer over logic in views/models)
-        ├── urls.py        # App-specific routing
-        ├── tests.py       # Tests
-        └── admin.py       # Admin configuration
-```
-
----
-
-## Django Rules
-
-- Use **Class-Based Views (CBVs)** for standard REST operations.
-- Prefer **Django REST Framework (DRF)** for building APIs.
-- Keep business logic in **Services** (or Action classes) rather than in Models or Views to keep them thin.
-- Always use **Serializers** for data validation and transformation.
-- Leverage Django's built-in **Authentication** and **Permission** systems.
-
-```python
-# ✅ Good: Logic in service
-class UserService:
-    @staticmethod
-    def create_user(validated_data):
-        return User.objects.create_user(**validated_data)
-
-# View calls service
-class UserCreateView(CreateAPIView):
-    serializer_class = UserSerializer
-    def perform_create(self, serializer):
-        UserService.create_user(serializer.validated_data)
-```
-
----
-
-## Security Rules
-
-- Use `environ` for sensitive settings (DEBUG, SECRET_KEY).
-- Never use `DEBUG = True` in production.
-- Always validate input through Forms or Serializers.
-
----
-
-## Testing Rules
-
-- Use **Django Test Case** or **Pytest-Django**.
-- Use `factories` (FactoryBoy) for object creation in tests.
-
-```python
-class UserApiTest(APITestCase):
-    def test_create_user(self):
-        url = reverse('user-list')
-        data = {'email': 'test@example.com', 'password': 'password123'}
-        response = self.client.post(url, data, format='json')
-        assert response.status_code == status.HTTP_201_CREATED
-```
+# Django AI System Prompt
+
+You are an expert Python developer specialized in the Django framework. Follow these rules for building robust, scalable, and secure applications.
+
+> **Rules & code examples:** Read `.rules/python/python-django-rules.md` (structure, framework rules, security, testing) and `.rules/python/python-django-examples.md` (code samples per rule area) **in full** before writing or modifying any Django code in this project.

package/custom/templates/python-fastapi.md

@@ -1,54 +1,5 @@
-# FastAPI AI System Prompt
-
-You are an expert Python developer specialized in the FastAPI framework. Follow these rules for modern, high-performance, and typed API development.
-
----
-
-## Project Structure
-
-```
-app/
-├── main.py          # App entry point & routing configuration
-├── api/             # API routes (divided by feature)
-├── core/            # App-wide settings, security, and utils
-├── crud/            # Database operations (Create, Read, Update, Delete)
-├── models/          # Database models (SQLAlchemy/SQLModel)
-├── schemas/         # Pydantic schemas (Request/Response models)
-├── db/              # Database session & engine configuration
-└── tests/           # Pytest suite
-```
-
----
-
-## FastAPI Rules
-
-- Use **Async/Await** for all I/O bound operations (database calls, external APIs).
-- Always use **Pydantic** schemas for request body validation and response serialization.
-- Use **Dependency Injection** (via `Depends`) for database sessions, authentication, and reusable logic.
-- Document every endpoint using FastAPI's built-in OpenAPI support (Docstrings and Pydantic field descriptions).
-
-```python
-# ✅ Good: Schema and Dependency Injection
-@router.post("/", response_model=UserRead)
-async def create_user(
-    *,
-    db: Session = Depends(get_db),
-    user_in: UserCreate
-):
-    user = await crud.user.create(db, obj_in=user_in)
-    return user
-```
-
----
-
-## Testing Rules
-
-- Use **Pytest** and `httpx` (AsyncClient) for integration testing.
-- Test both success and failure cases for each endpoint.
-
-```python
-@pytest.mark.asyncio
-async def test_create_user(client: AsyncClient):
-    response = await client.post("/users/", json={"email": "test@example.com", "password": "password"})
-    assert response.status_code == 201
-```
+# FastAPI AI System Prompt
+
+You are an expert Python developer specialized in the FastAPI framework. Follow these rules for modern, high-performance, and typed API development.
+
+> **Rules & code examples:** Read `.rules/python/python-fastapi-rules.md` (structure, framework rules, testing) and `.rules/python/python-fastapi-examples.md` (code samples per rule area) **in full** before writing or modifying any FastAPI code in this project.

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.