@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/rules/php/php-rules.md

@@ -0,0 +1,127 @@
+# PHP Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any PHP code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## 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.
+
+---
+
+### 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.
+
+---
+
+### 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`.
+
+---
+
+### 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.
+
+---
+
+### 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.
+
+---
+
+### 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.
+
+---
+
+## 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/).

package/custom/rules/python/python-django-examples.md

@@ -0,0 +1,34 @@
+# Django Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## Django Rules
+
+```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)
+```
+
+---
+
+## Testing
+
+```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
+```

package/custom/rules/python/python-django-rules.md

@@ -0,0 +1,48 @@
+# Django Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any Django code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## 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.
+
+---
+
+## 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.

package/custom/rules/python/python-examples.md

@@ -0,0 +1,32 @@
+# Python Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## Python Rules
+
+```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
+
+```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"))
+```

package/custom/rules/python/python-fastapi-examples.md

@@ -0,0 +1,30 @@
+# FastAPI Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## FastAPI Rules
+
+```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
+
+```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
+```

package/custom/rules/python/python-fastapi-rules.md

@@ -0,0 +1,35 @@
+# FastAPI Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any FastAPI code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## 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).
+
+---
+
+## Testing Rules
+
+- Use **Pytest** and `httpx` (AsyncClient) for integration testing.
+- Test both success and failure cases for each endpoint.

package/custom/rules/python/python-ml-examples.md

@@ -0,0 +1,187 @@
+# Python ML/AI Code Examples
+
+Reference examples for each rule area. Read the relevant section when generating code for that area.
+
+---
+
+## Reproducibility
+
+```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
+
+```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
+
+```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
+
+```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
+
+```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
+
+```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)
+
+```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
+
+```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")
+```
+
+---
+
+## Testing
+
+```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"
+```

package/custom/rules/python/python-ml-rules.md

@@ -0,0 +1,121 @@
+# Python ML/AI Rules
+
+Full coding rules for this stack — covers scikit-learn, PyTorch, TensorFlow/Keras, and experiment tracking (MLflow / wandb / DVC). Read this in full before writing or modifying any ML/AI code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## 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.
+
+---
+
+## Config Management
+
+- Hyperparameters live in YAML / Hydra / argparse configs — **never hardcoded**.
+- The config file is saved alongside every model artifact.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+### 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.
+
+### TensorFlow / Keras
+
+- Use callbacks for checkpointing (save best by validation metric) and early stopping.
+- Set `tf.random.set_seed` at startup.
+
+### 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.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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

package/custom/rules/python/python-rules.md

@@ -0,0 +1,58 @@
+# Python Rules
+
+Full coding rules for this stack. Read this in full before writing or modifying any Python code in this project — not just once, keep applying it to every edit in the session, not only the first.
+
+---
+
+## 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")`.
+
+---
+
+## Testing Rules
+
+- Use **Pytest** for all tests.
+- Name test functions `test_<what>_<expected_outcome>`.
+- Use `pytest.raises` to assert exceptions.
+
+---
+
+## 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

package/custom/skills/ba-skills/skill-ba-qna-template-v1.md

@@ -10,10 +10,10 @@ Mẫu tài liệu dùng để trình bày danh sách câu hỏi Q&A và theo dõ
 
 ## Danh sách câu hỏi Q&A
 
-| ID | Chức năng / Màn hình | Nội dung yêu cầu hiện tại | Câu hỏi / Điểm chưa rõ | Đề xuất giải pháp (Options) | Mức độ ảnh hưởng | Câu trả lời của Khách hàng | Trạng thái |
-| :-: | :--- | :--- | :--- | :--- | :-: | :--- | :-: |
-| **QA-01** | *Đăng nhập* | *Có text link đổi mật khẩu* | *Text link này sẽ dẫn sang URL cụ thể nào? Hệ thống tự sinh OTP gửi mail hay chuyển sang màn nhập email?* | *- Option A: Chuyển sang URL `/forgot-password` để nhập Email nhận link reset.<br>- Option B: Hiển thị popup nhập SĐT nhận OTP.* | 🔴 Blocking | *Khách hàng phản hồi: Chọn Option A, link URL là `/forgot-password`* | **Confirmed** |
-| **QA-02** | *Đăng nhập* | *Thông báo lỗi khi sai mật khẩu* | *Câu chữ thông báo lỗi cụ thể là gì?* | *- Option A: "Email hoặc mật khẩu không đúng."<br>- Option B: Ý kiến khác...* | 🟡 Non-blocking | *Chưa trả lời — khách hàng cần hỏi lại team Marketing* | **Open** |
+| ID | Chức năng / Màn hình | Nội dung yêu cầu hiện tại | Câu hỏi / Điểm chưa rõ | Đề xuất giải pháp (Options) | Mức độ ảnh hưởng | Câu trả lời của Khách hàng | Người trả lời | Ngày trả lời | Nguồn | Trạng thái |
+| :-: | :--- | :--- | :--- | :--- | :-: | :--- | :--- | :-: | :--- | :-: |
+| **QA-01** | *Đăng nhập* | *Có text link đổi mật khẩu* | *Text link này sẽ dẫn sang URL cụ thể nào? Hệ thống tự sinh OTP gửi mail hay chuyển sang màn nhập email?* | *- Option A: Chuyển sang URL `/forgot-password` để nhập Email nhận link reset.<br>- Option B: Hiển thị popup nhập SĐT nhận OTP.* | 🔴 Blocking | *Khách hàng phản hồi: Chọn Option A, link URL là `/forgot-password`* | *Nguyễn Văn A (PO)* | *12/07/2026* | *Khách hàng* | **Confirmed** |
+| **QA-02** | *Đăng nhập* | *Thông báo lỗi khi sai mật khẩu* | *Câu chữ thông báo lỗi cụ thể là gì?* | *- Option A: "Email hoặc mật khẩu không đúng."<br>- Option B: Ý kiến khác...* | 🟡 Non-blocking | *Chưa trả lời — khách hàng cần hỏi lại team Marketing* | *—* | *—* | *—* | **Open** |
 
 ---
 ## Lịch sử cập nhật tài liệu