# Skill: General Python Project Boilerplate (Synapsis Standard)

This skill provides the comprehensive standards, architectural patterns, and workflows for developing Python projects at Synapsis using the "General Boilerplate" foundation.

## 🚨 Mandatory Constraints (Non-Negotiable)
1. **Tooling**: ALWAYS use `uv` for all operations (installing packages, running scripts, testing). NEVER use `pip` or raw `python` directly.
    - Example: `uv run main.py`, `uv add requests`, `uv run pytest`.
2. **Structure**: ALWAYS adhere to the **Layered Architecture** folder structure. NEVER place logic in `main.py` or skip the `pipeline/` layer.

## 🏗️ Architecture: Layered & Decoupled
Projects must follow a **Layered Architecture**. Dependencies flow **strictly downwards**.

### Layer Definitions
1.  **Main Entry (`main.py`)**: Root bootstrap. Initialization only. **Logic Forbidden**.
2.  **Interfaces (`interfaces/`)**: Protocol gateways (Flask, CLI, Streamlit).
    - Map raw input (JSON/Args) to `data_model`.
    - Handle protocol-specific logic (HTTP codes, CLI flags).
    - **Forbidden**: Direct access to `database/` or `inference/`.
3.  **Pipeline (`pipeline/`)**: Core Business Logic Orchestration.
    - Coordinates components to achieve a use case.
    - **Agnostic**: Must not depend on Interface details (request objects).
4.  **Components (Leaf Nodes)**:
    - `data_model/`: Standardized `@dataclass` structures.
    - `database/`: Persistence logic and CRUD.
    - `inference/`: Model loading and prediction.
    - `utils/`: Stateless helpers.
    - **Forbidden**: Importing from `Pipeline` or `Interfaces`.

---

## 🛠️ Tooling & Standards
- **Manager**: `uv` (Fast environment/dependency management).
- **Core**: Python 3.11+.
- **lint/Format**: `ruff` (Mandatory, 88 char limit).
- **Type Check**: `mypy` (**Strict** mode mandatory).
- **Test**: `pytest`.
- **API**: **Flask** (Mandatory), Prefix `/api/v1/`, Pydantic for validation.
- **Dataset**: `DVC` with Synapsis S3 remote.

---

## 🤖 Agent Workflow (PDCA)
Every task must follow this disciplined cycle:
1.  **PLAN**: Use `task.md` and `implementation_plan.md`. Get user approval via `notify_user`.
2.  **DO**: Write code in small, testable chunks. Update `task.md` real-time.
3.  **CHECK**: Run `uv run pytest` and `uv run pre-commit run --all-files`. **Green status mandatory**.
4.  **ACTION**: Document work in `walkthrough.md`.

---

## 📝 Documentation Rules
- **Language**: **Indonesian** strictly for code docstrings (Google Style) and artifacts.
- **Rules**: Internal process/rule documents stay in **English**.
- **Docstrings**: No redundant type hints in text (use Python Type Hints).

---

## ✅ Do's and Don'ts
- **DO**: Use `pathlib.Path`.
- **DO**: Use `logging`, NEVER `print()`.
- **DO**: Mock DB/AI in Pipeline tests.
- **DON'T**: Use circular imports.
- **DON'T**: Put SQL logic in `Pipeline`.
- **DON'T**: Swallow exceptions; always log `ERROR`.
