kaneko-fa-selector 0.2.0__tar.gz

kaneko_fa_selector-0.2.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: kaneko-fa-selector
+Version: 0.2.0
+Summary: KANEKO flame arrester preselection rule engine (R1-R8): JSON in, JSON out
+Author-email: stkengaposa832@gmail.com
+Keywords: kaneko,flame arrester,rule engine,preselection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Manufacturing
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: app
+Requires-Dist: streamlit>=1.35; extra == "app"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# KANEKO FA Selector
+
+Thư viện Python tiền chọn flame arrester KANEKO theo bộ luật R1–R8 (deterministic).
+Gọi một hàm, nhận JSON. Kèm app demo Streamlit chạy trên nền thư viện và CLI.
+
+> **Giới hạn kỹ thuật quan trọng.** Đây là bản demo / tiền chọn, không phải công cụ thiết kế đã được phê duyệt.
+> Tài liệu nguồn mô tả bước R5 (lưu lượng / ΔP) nhưng **không** cung cấp điểm đường cong hay hệ số `(a, b)`,
+> nên thư viện cố ý không bịa giá trị ΔP và không bao giờ báo R5 "đạt". Tập tra cứu khí chỉ là một phần nhỏ
+> của bảng 215 chất; chất không nhận diện được sẽ không bị đoán. Acetylene luôn chuyển kỹ thuật.
+> **Mọi model đề xuất đều là tiền chọn và phải được kỹ thuật KANEKO xác nhận trước khi báo giá.**
+
+## Cài đặt
+
+Thư viện chỉ phụ thuộc PyYAML, chạy trên Python 3.10 trở lên.
+
+```bash
+# Từ PyPI (sau khi đã phát hành, xem mục "Phát hành lên PyPI")
+pip install kaneko-fa-selector
+
+# Từ thư mục mã nguồn này
+pip install .                  # bản cố định
+pip install -e ".[app,dev]"    # editable (sửa code có hiệu lực ngay) + Streamlit + pytest + build + twine
+
+# Từ file wheel đã build (xem mục "Đóng gói")
+pip install dist/kaneko_fa_selector-0.2.0-py3-none-any.whl
+```
+
+Không cần cài cũng chạy được: thêm thư mục `src` vào `PYTHONPATH` (app demo và test đã tự làm việc này).
+
+## Đóng gói
+
+```powershell
+.\build_dist.ps1
+```
+
+Script tự cài công cụ `build` vào `.venv` (hoặc Python mặc định nếu không có `.venv`), xoá `dist/` cũ rồi tạo:
+
+- `dist/kaneko_fa_selector-0.2.0-py3-none-any.whl`: file cài đặt, dùng cho `pip install` / `requirements.txt`
+- `dist/kaneko_fa_selector-0.2.0.tar.gz`: mã nguồn đóng gói (sdist)
+
+Lệnh tương đương: `python -m build --outdir dist`. Trước khi build bản mới, tăng `__version__` trong
+`src/kaneko_fa_selector/__init__.py` (tên file wheel đổi theo).
+
+## Phát hành lên PyPI
+
+PyPI là kho **công khai**: ai cũng tải được package, đọc được README và các bảng dữ liệu trong `engine.py`.
+Chỉ phát hành khi chắc chắn dữ liệu KANEKO trong thư viện được phép công khai. Nếu chỉ dùng nội bộ, dùng wheel
+hoặc Git riêng như mục "Dùng trong dự án khác".
+
+Chuẩn bị một lần:
+
+1. Tạo tài khoản tại https://pypi.org/account/register/ và https://test.pypi.org/account/register/ (để thử), bật xác thực hai lớp.
+2. Tạo API token quyền upload tại https://pypi.org/manage/account/token/ (và trang tương ứng trên TestPyPI).
+   Lần đầu chọn scope "Entire account"; sau khi project đã tồn tại thì tạo token riêng cho project.
+   Token bắt đầu bằng `pypi-` và chỉ hiển thị một lần.
+3. Khai báo giấy phép: thêm `license = "MIT"` (hoặc giấy phép bạn chọn) vào `[project]` trong `pyproject.toml`
+   và tạo file `LICENSE`. Không bắt buộc về kỹ thuật nhưng package công khai nên có.
+4. Kiểm tra lại `authors` trong `pyproject.toml`: email ghi ở đó sẽ hiển thị công khai trên trang PyPI.
+
+Mỗi lần phát hành:
+
+```powershell
+# 1. Tăng __version__ trong src/kaneko_fa_selector/__init__.py (PyPI không cho đăng lại phiên bản đã có)
+
+# 2. Thử trên TestPyPI
+$env:TEST_PYPI_TOKEN = "pypi-..."
+.\publish.ps1 -Test
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ kaneko-fa-selector
+
+# 3. Phát hành thật
+$env:PYPI_TOKEN = "pypi-..."
+.\publish.ps1
+pip install kaneko-fa-selector
+```
+
+`publish.ps1` build lại `dist/`, chạy `twine check --strict` rồi `twine upload`. Token chỉ nằm trong biến môi trường
+của phiên PowerShell hiện tại, không ghi ra file. Nếu Windows chặn chạy script:
+`powershell -ExecutionPolicy Bypass -File .\publish.ps1 -Test`.
+
+## Dùng trong dự án khác
+
+Đã phát hành lên PyPI thì chỉ cần một dòng trong `requirements.txt` của dự án kia:
+
+```
+kaneko-fa-selector>=0.2.0
+```
+
+Chưa phát hành, hoặc muốn dùng nội bộ, chọn một trong ba cách:
+
+1. **Chép file wheel vào dự án đó** (ví dụ thư mục `libs/`), đường dẫn tương đối tính từ nơi chạy `pip`:
+
+   ```
+   libs/kaneko_fa_selector-0.2.0-py3-none-any.whl
+   ```
+
+2. **Trỏ thẳng tới file wheel trên máy** bằng URL `file:` (đường dẫn có dấu tiếng Việt / khoảng trắng phải percent-encode):
+
+   ```
+   kaneko-fa-selector @ file:///C:/duong/dan/toi/kaneko_fa_selector_app/dist/kaneko_fa_selector-0.2.0-py3-none-any.whl
+   ```
+
+   Lấy URL đúng bằng:
+   `python -c "from pathlib import Path; print(Path('dist/kaneko_fa_selector-0.2.0-py3-none-any.whl').resolve().as_uri())"`
+
+3. **Khi đã đưa mã nguồn lên Git** (GitHub / GitLab):
+
+   ```
+   kaneko-fa-selector @ git+https://github.com/<tai-khoan>/<repo>.git
+   ```
+
+Rồi trong dự án kia chạy `pip install -r requirements.txt`. Không dùng `requirements.txt` thì cài trực tiếp:
+
+```bash
+pip install "C:\...\dist\kaneko_fa_selector-0.2.0-py3-none-any.whl"   # từ wheel
+pip install "C:\...\kaneko_fa_selector_app"                            # từ thư mục mã nguồn
+```
+
+Kiểm tra nhanh sau khi cài:
+
+```bash
+python -c "import kaneko_fa_selector as k; print(k.__version__)"
+kaneko-fa-selector '{"gas_name": "methane", "operating_pressure_kpag": 8}'
+```
+
+## Dùng nhanh
+
+```python
+from kaneko_fa_selector import select, select_json
+
+# 1) Nhận chuỗi JSON
+print(select_json({"gas_name": "methane", "operating_pressure_kpag": 8,
+                   "service_location": "End-of-line", "requested_dn": 50}))
+
+# 2) Nhận dict để xử lý tiếp trong Python
+result = select(gas_name="hydrogen", operating_pressure_kpag=5,
+                service_location="In-line", pipe_geometry="Exact L/D known", ld_ratio=20,
+                ibexu_requirement="yes")
+print(result["status"], result["primary_candidate"]["model_code"])
+
+# 3) Đầu vào là chuỗi JSON (ví dụ nhận từ AI agent / HTTP)
+print(select_json('{"gas_name": "ethanol", "operating_pressure_kpag": 12}'))
+```
+
+Trường bắt buộc duy nhất là `operating_pressure_kpag`; các trường khác có mặc định bảo thủ.
+
+Lỗi đầu vào:
+
+- `select` ném `SelectorInputError` (thuộc tính `.errors` là danh sách thông báo).
+- `select_json` mặc định **không** ném mà trả JSON với `"status": "INPUT_ERROR"` và danh sách `errors`.
+  Dùng `select_json(..., strict=True)` nếu muốn ném exception.
+
+## CLI
+
+```bash
+python -m kaneko_fa_selector '{"gas_name": "methane", "operating_pressure_kpag": 8}'
+python -m kaneko_fa_selector --file input.json --compact
+type input.json | python -m kaneko_fa_selector
+python -m kaneko_fa_selector --fields      # mô tả các trường đầu vào
+kaneko-fa-selector ...                     # lệnh tương đương sau khi pip install
+```
+
+Đầu ra luôn là JSON UTF-8 (thêm `--ascii` để escape tiếng Việt). Đầu vào từ stdin / file là UTF-8 và
+chấp nhận BOM (PowerShell hay chèn BOM khi pipe). Mã thoát `0` khi engine chạy xong
+(kể cả `TECHNICAL_REVIEW` / `NO_CANDIDATE`), `2` khi đầu vào sai.
+
+## Trường đầu vào
+
+| Trường | Kiểu | Mặc định | Ghi chú |
+|---|---|---|---|
+| `gas_name` | chuỗi | `""` | Tra trong tập demo (không phân biệt hoa/thường). Không nhận diện được → `TECHNICAL_REVIEW`. |
+| `manual_gas_group` | `IIA1` `IIA` `IIB1` `IIB2` `IIB3` `IIB` `IIC` | `null` | Ưu tiên hơn `gas_name`. Acetylene vẫn luôn dừng. |
+| `operating_pressure_kpag` | số ≥ 0 | **bắt buộc** | Áp suất làm việc kPaG. |
+| `service_location` | `End-of-line` \| `In-line` | `In-line` | Alias: `eol`, `end_of_line`, `inline`, `in_line`. |
+| `pipe_geometry` | `Short, unobstructed` \| `Exact L/D known` \| `Long / obstacles / unknown` | `Long / obstacles / unknown` | Alias: `short`, `exact_ld`, `long`, `unknown`. |
+| `ld_ratio` | số > 0 | `null` | Chỉ dùng khi `pipe_geometry = Exact L/D known`. Thiếu → mặc định DETONATION. |
+| `ibexu_requirement` | `yes` \| `no` \| `unknown` | `unknown` | Nhận cả `true`/`false`, `Có`/`Không`/`Chưa rõ`. |
+| `requested_dn` | số hoặc chuỗi | `null` | Chèn **nguyên văn** vào mã model (quy định nguồn), chỉ dùng để ưu tiên xếp hạng. |
+| `ifrt_low_pressure` | bool | `false` | Dùng bảng IFRT áp thấp IBExU. |
+| `flow_rate_m3h` | số > 0 | `null` | R5 hiện chưa tính ΔP; chỉ sinh cảnh báo. |
+| `max_delta_p_kpa` | số > 0 | `null` | Như trên. |
+| `families` | danh sách con của `IFRF` `IFRT` `FCRT` (hoặc chuỗi `"IFRF,IFRT"`) | cả ba | Luôn được sắp về thứ tự IFRF → IFRT → FCRT. |
+
+Quy ước: trường tuỳ chọn không có dữ liệu thì để `null`, **không** dùng `0` (tránh L/D = 0 vô tình thành DEFLAGRATION).
+Trường lạ bị từ chối để bắt lỗi gõ sai tên.
+
+## Cấu trúc kết quả
+
+| Khoá | Ý nghĩa |
+|---|---|
+| `status` | `PRELIMINARY` (có model tiền chọn) · `NO_CANDIDATE` (không model nào qua lọc) · `TECHNICAL_REVIEW` (dừng ở R1) · `INPUT_ERROR` (chỉ `select_json` / CLI) |
+| `decision` | `REVIEW_REQUIRED` · `TECHNICAL_REVIEW` · `STOP` |
+| `gas_group` | Nhóm khí đã xác định, hoặc `null` |
+| `device_type` | `DEFLAGRATION` · `DETONATION` · `null` |
+| `primary_candidate` | Model tiền chọn (R6) hoặc `null`: `series`, `dn`, `pressure_kpag`, `certified`, `gas_letter`, `reason`, `delta_p_status`, `delta_p`, `model_code` |
+| `candidates` | Mọi ứng viên qua bộ lọc R3, đã xếp hạng |
+| `upgrade_suggestions` | Gợi ý tham khảo R7 (tối đa 10, chỉ khi DEFLAGRATION) |
+| `warnings` | Cảnh báo / việc cần kỹ thuật xác nhận (đã khử trùng lặp) |
+| `steps` | Trace từng luật: `rule`, `status`, `detail` theo thứ tự R1 → R2 → R4 → R3 → R5 → R6 → R7 → R8 |
+| `final_note` | Ghi chú cuối |
+| `engine_version` | Phiên bản thư viện |
+| `input` | Đầu vào sau chuẩn hoá (giá trị engine thực sự dùng) |
+| `errors` | Chỉ có khi `status = INPUT_ERROR` |
+
+Ví dụ rút gọn với đầu vào `{"gas_name": "methane", "operating_pressure_kpag": 8, "service_location": "End-of-line", "requested_dn": 50}`:
+
+```json
+{
+  "status": "PRELIMINARY",
+  "decision": "REVIEW_REQUIRED",
+  "gas_group": "IIA1",
+  "device_type": "DEFLAGRATION",
+  "primary_candidate": {"series": "IFRF", "dn": 50, "pressure_kpag": 50.0, "certified": false,
+                        "model_code": "IFRF-50-BB-{IIA1:chưa xác nhận}-P50", "...": "..."},
+  "candidates": ["... 20 ứng viên ..."],
+  "warnings": ["Kết quả là TIỀN CHỌN; kỹ thuật KANEKO phải xác nhận model trước khi báo giá.", "..."],
+  "steps": [{"rule": "R1", "status": "PASS", "detail": "Nhóm khí IIA1."}, "..."],
+  "final_note": "Chỉ là tiền chọn. Không dùng để đặt hàng/báo giá trước khi kỹ thuật KANEKO xác nhận."
+}
+```
+
+## App demo Streamlit
+
+```bash
+pip install -e ".[app]"
+streamlit run app.py
+```
+
+## Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Cấu trúc thư mục
+
+- `src/kaneko_fa_selector/__init__.py`: API công khai `select`, `select_json`, `load_config`
+- `src/kaneko_fa_selector/engine.py`: luật R1–R8 và các bảng tra (nguồn sự thật của logic)
+- `src/kaneko_fa_selector/inputs.py`: chuẩn hoá / kiểm tra đầu vào, `SelectorInputError`
+- `src/kaneko_fa_selector/__main__.py`: CLI
+- `src/kaneko_fa_selector/rules/kaneko_fa_rules.yaml`: cấu hình tham chiếu (đi kèm package)
+- `src/selector.py`: shim tương thích cho code cũ `from selector import ...`
+- `app.py`: demo Streamlit
+- `tests/`: test thư viện, CLI và app demo
+- `pyproject.toml`: metadata và cấu hình đóng gói; `requirements.txt`: cài editable kèm Streamlit cho demo
+- `build_dist.ps1`: build wheel + sdist vào `dist/` (thư mục `dist/` được `.gitignore` bỏ qua)
+- `source_rule_engine.docx`, `docs_flowchart.png`, `van_relation.md`: tài liệu nguồn và sơ đồ dòng sản phẩm
+
+## Đã triển khai từ tài liệu nguồn
+
+- R1: nhóm khí, tra theo tên hoặc chọn tay; chất lạ và acetylene chuyển kỹ thuật
+- R2: loại thiết bị theo end-of-line, L/D (ngưỡng 30 cho IIC, 50 cho nhóm khác) và điều kiện ống; mặc định bảo thủ DETONATION
+- R4: nhánh IBExU (`yes` chỉ bản chứng nhận, `no` chỉ bản thường, `unknown` cả hai, ưu tiên bản thường)
+- R3: lọc dòng sản phẩm theo bảng rating áp suất trong nguồn
+- R5: báo rõ chưa có hệ số / điểm đường cong; không bịa ΔP
+- R6: chọn ứng viên theo DN khách → DN nhỏ nhất → bản thường trước → rating thấp hơn
+- R7: gợi ý nâng cấp khi kết quả là DEFLAGRATION
+- R8: ghép mã model `{series}-{dn}-BB-{chữ nhóm}-P{rating}[-EX]` kèm cảnh báo
+
+## Lưu ý khi đọc logic
+
+- File YAML chỉ để tham chiếu / hiển thị. Các bảng tra thực sự nằm trong `engine.py`; sửa YAML không đổi kết quả.
+- Loại thiết bị ở R2 (DEFLAGRATION / DETONATION) chưa được dùng để lọc dòng sản phẩm ở R3; engine xét mọi dòng trong `families`.
+- Bước quy đổi cột biểu đồ A/B/C (`gas_column`) có trong code để tham chiếu nhưng `run_engine` chưa gọi.
+- R7 chỉ là lát cắt của danh sách ứng viên (DN ≥ model chính), không tra bảng model Detonation riêng.
+- Khi có `requested_dn`, mọi mã model đều mang DN đó; cột `dn` trong ứng viên mới là DN catalog thật.
+
+## Cần bổ sung để dùng thật
+
+1. Bảng đầy đủ 215 chất (EN/JP/MESG).
+2. Đường cong lưu lượng KANEKO đã số hoá và/hoặc hệ số `(a, b)` được phê duyệt cho mọi tổ hợp, kèm khoảng Q hợp lệ.
+3. Catalog DN / áp suất / model và ma trận chứng nhận chính xác.
+4. Kỹ thuật KANEKO rà soát chính thức và bộ test case được chủ sở hữu phê duyệt.

kaneko_fa_selector-0.2.0/README.md

@@ -0,0 +1,273 @@
+# KANEKO FA Selector
+
+Thư viện Python tiền chọn flame arrester KANEKO theo bộ luật R1–R8 (deterministic).
+Gọi một hàm, nhận JSON. Kèm app demo Streamlit chạy trên nền thư viện và CLI.
+
+> **Giới hạn kỹ thuật quan trọng.** Đây là bản demo / tiền chọn, không phải công cụ thiết kế đã được phê duyệt.
+> Tài liệu nguồn mô tả bước R5 (lưu lượng / ΔP) nhưng **không** cung cấp điểm đường cong hay hệ số `(a, b)`,
+> nên thư viện cố ý không bịa giá trị ΔP và không bao giờ báo R5 "đạt". Tập tra cứu khí chỉ là một phần nhỏ
+> của bảng 215 chất; chất không nhận diện được sẽ không bị đoán. Acetylene luôn chuyển kỹ thuật.
+> **Mọi model đề xuất đều là tiền chọn và phải được kỹ thuật KANEKO xác nhận trước khi báo giá.**
+
+## Cài đặt
+
+Thư viện chỉ phụ thuộc PyYAML, chạy trên Python 3.10 trở lên.
+
+```bash
+# Từ PyPI (sau khi đã phát hành, xem mục "Phát hành lên PyPI")
+pip install kaneko-fa-selector
+
+# Từ thư mục mã nguồn này
+pip install .                  # bản cố định
+pip install -e ".[app,dev]"    # editable (sửa code có hiệu lực ngay) + Streamlit + pytest + build + twine
+
+# Từ file wheel đã build (xem mục "Đóng gói")
+pip install dist/kaneko_fa_selector-0.2.0-py3-none-any.whl
+```
+
+Không cần cài cũng chạy được: thêm thư mục `src` vào `PYTHONPATH` (app demo và test đã tự làm việc này).
+
+## Đóng gói
+
+```powershell
+.\build_dist.ps1
+```
+
+Script tự cài công cụ `build` vào `.venv` (hoặc Python mặc định nếu không có `.venv`), xoá `dist/` cũ rồi tạo:
+
+- `dist/kaneko_fa_selector-0.2.0-py3-none-any.whl`: file cài đặt, dùng cho `pip install` / `requirements.txt`
+- `dist/kaneko_fa_selector-0.2.0.tar.gz`: mã nguồn đóng gói (sdist)
+
+Lệnh tương đương: `python -m build --outdir dist`. Trước khi build bản mới, tăng `__version__` trong
+`src/kaneko_fa_selector/__init__.py` (tên file wheel đổi theo).
+
+## Phát hành lên PyPI
+
+PyPI là kho **công khai**: ai cũng tải được package, đọc được README và các bảng dữ liệu trong `engine.py`.
+Chỉ phát hành khi chắc chắn dữ liệu KANEKO trong thư viện được phép công khai. Nếu chỉ dùng nội bộ, dùng wheel
+hoặc Git riêng như mục "Dùng trong dự án khác".
+
+Chuẩn bị một lần:
+
+1. Tạo tài khoản tại https://pypi.org/account/register/ và https://test.pypi.org/account/register/ (để thử), bật xác thực hai lớp.
+2. Tạo API token quyền upload tại https://pypi.org/manage/account/token/ (và trang tương ứng trên TestPyPI).
+   Lần đầu chọn scope "Entire account"; sau khi project đã tồn tại thì tạo token riêng cho project.
+   Token bắt đầu bằng `pypi-` và chỉ hiển thị một lần.
+3. Khai báo giấy phép: thêm `license = "MIT"` (hoặc giấy phép bạn chọn) vào `[project]` trong `pyproject.toml`
+   và tạo file `LICENSE`. Không bắt buộc về kỹ thuật nhưng package công khai nên có.
+4. Kiểm tra lại `authors` trong `pyproject.toml`: email ghi ở đó sẽ hiển thị công khai trên trang PyPI.
+
+Mỗi lần phát hành:
+
+```powershell
+# 1. Tăng __version__ trong src/kaneko_fa_selector/__init__.py (PyPI không cho đăng lại phiên bản đã có)
+
+# 2. Thử trên TestPyPI
+$env:TEST_PYPI_TOKEN = "pypi-..."
+.\publish.ps1 -Test
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ kaneko-fa-selector
+
+# 3. Phát hành thật
+$env:PYPI_TOKEN = "pypi-..."
+.\publish.ps1
+pip install kaneko-fa-selector
+```
+
+`publish.ps1` build lại `dist/`, chạy `twine check --strict` rồi `twine upload`. Token chỉ nằm trong biến môi trường
+của phiên PowerShell hiện tại, không ghi ra file. Nếu Windows chặn chạy script:
+`powershell -ExecutionPolicy Bypass -File .\publish.ps1 -Test`.
+
+## Dùng trong dự án khác
+
+Đã phát hành lên PyPI thì chỉ cần một dòng trong `requirements.txt` của dự án kia:
+
+```
+kaneko-fa-selector>=0.2.0
+```
+
+Chưa phát hành, hoặc muốn dùng nội bộ, chọn một trong ba cách:
+
+1. **Chép file wheel vào dự án đó** (ví dụ thư mục `libs/`), đường dẫn tương đối tính từ nơi chạy `pip`:
+
+   ```
+   libs/kaneko_fa_selector-0.2.0-py3-none-any.whl
+   ```
+
+2. **Trỏ thẳng tới file wheel trên máy** bằng URL `file:` (đường dẫn có dấu tiếng Việt / khoảng trắng phải percent-encode):
+
+   ```
+   kaneko-fa-selector @ file:///C:/duong/dan/toi/kaneko_fa_selector_app/dist/kaneko_fa_selector-0.2.0-py3-none-any.whl
+   ```
+
+   Lấy URL đúng bằng:
+   `python -c "from pathlib import Path; print(Path('dist/kaneko_fa_selector-0.2.0-py3-none-any.whl').resolve().as_uri())"`
+
+3. **Khi đã đưa mã nguồn lên Git** (GitHub / GitLab):
+
+   ```
+   kaneko-fa-selector @ git+https://github.com/<tai-khoan>/<repo>.git
+   ```
+
+Rồi trong dự án kia chạy `pip install -r requirements.txt`. Không dùng `requirements.txt` thì cài trực tiếp:
+
+```bash
+pip install "C:\...\dist\kaneko_fa_selector-0.2.0-py3-none-any.whl"   # từ wheel
+pip install "C:\...\kaneko_fa_selector_app"                            # từ thư mục mã nguồn
+```
+
+Kiểm tra nhanh sau khi cài:
+
+```bash
+python -c "import kaneko_fa_selector as k; print(k.__version__)"
+kaneko-fa-selector '{"gas_name": "methane", "operating_pressure_kpag": 8}'
+```
+
+## Dùng nhanh
+
+```python
+from kaneko_fa_selector import select, select_json
+
+# 1) Nhận chuỗi JSON
+print(select_json({"gas_name": "methane", "operating_pressure_kpag": 8,
+                   "service_location": "End-of-line", "requested_dn": 50}))
+
+# 2) Nhận dict để xử lý tiếp trong Python
+result = select(gas_name="hydrogen", operating_pressure_kpag=5,
+                service_location="In-line", pipe_geometry="Exact L/D known", ld_ratio=20,
+                ibexu_requirement="yes")
+print(result["status"], result["primary_candidate"]["model_code"])
+
+# 3) Đầu vào là chuỗi JSON (ví dụ nhận từ AI agent / HTTP)
+print(select_json('{"gas_name": "ethanol", "operating_pressure_kpag": 12}'))
+```
+
+Trường bắt buộc duy nhất là `operating_pressure_kpag`; các trường khác có mặc định bảo thủ.
+
+Lỗi đầu vào:
+
+- `select` ném `SelectorInputError` (thuộc tính `.errors` là danh sách thông báo).
+- `select_json` mặc định **không** ném mà trả JSON với `"status": "INPUT_ERROR"` và danh sách `errors`.
+  Dùng `select_json(..., strict=True)` nếu muốn ném exception.
+
+## CLI
+
+```bash
+python -m kaneko_fa_selector '{"gas_name": "methane", "operating_pressure_kpag": 8}'
+python -m kaneko_fa_selector --file input.json --compact
+type input.json | python -m kaneko_fa_selector
+python -m kaneko_fa_selector --fields      # mô tả các trường đầu vào
+kaneko-fa-selector ...                     # lệnh tương đương sau khi pip install
+```
+
+Đầu ra luôn là JSON UTF-8 (thêm `--ascii` để escape tiếng Việt). Đầu vào từ stdin / file là UTF-8 và
+chấp nhận BOM (PowerShell hay chèn BOM khi pipe). Mã thoát `0` khi engine chạy xong
+(kể cả `TECHNICAL_REVIEW` / `NO_CANDIDATE`), `2` khi đầu vào sai.
+
+## Trường đầu vào
+
+| Trường | Kiểu | Mặc định | Ghi chú |
+|---|---|---|---|
+| `gas_name` | chuỗi | `""` | Tra trong tập demo (không phân biệt hoa/thường). Không nhận diện được → `TECHNICAL_REVIEW`. |
+| `manual_gas_group` | `IIA1` `IIA` `IIB1` `IIB2` `IIB3` `IIB` `IIC` | `null` | Ưu tiên hơn `gas_name`. Acetylene vẫn luôn dừng. |
+| `operating_pressure_kpag` | số ≥ 0 | **bắt buộc** | Áp suất làm việc kPaG. |
+| `service_location` | `End-of-line` \| `In-line` | `In-line` | Alias: `eol`, `end_of_line`, `inline`, `in_line`. |
+| `pipe_geometry` | `Short, unobstructed` \| `Exact L/D known` \| `Long / obstacles / unknown` | `Long / obstacles / unknown` | Alias: `short`, `exact_ld`, `long`, `unknown`. |
+| `ld_ratio` | số > 0 | `null` | Chỉ dùng khi `pipe_geometry = Exact L/D known`. Thiếu → mặc định DETONATION. |
+| `ibexu_requirement` | `yes` \| `no` \| `unknown` | `unknown` | Nhận cả `true`/`false`, `Có`/`Không`/`Chưa rõ`. |
+| `requested_dn` | số hoặc chuỗi | `null` | Chèn **nguyên văn** vào mã model (quy định nguồn), chỉ dùng để ưu tiên xếp hạng. |
+| `ifrt_low_pressure` | bool | `false` | Dùng bảng IFRT áp thấp IBExU. |
+| `flow_rate_m3h` | số > 0 | `null` | R5 hiện chưa tính ΔP; chỉ sinh cảnh báo. |
+| `max_delta_p_kpa` | số > 0 | `null` | Như trên. |
+| `families` | danh sách con của `IFRF` `IFRT` `FCRT` (hoặc chuỗi `"IFRF,IFRT"`) | cả ba | Luôn được sắp về thứ tự IFRF → IFRT → FCRT. |
+
+Quy ước: trường tuỳ chọn không có dữ liệu thì để `null`, **không** dùng `0` (tránh L/D = 0 vô tình thành DEFLAGRATION).
+Trường lạ bị từ chối để bắt lỗi gõ sai tên.
+
+## Cấu trúc kết quả
+
+| Khoá | Ý nghĩa |
+|---|---|
+| `status` | `PRELIMINARY` (có model tiền chọn) · `NO_CANDIDATE` (không model nào qua lọc) · `TECHNICAL_REVIEW` (dừng ở R1) · `INPUT_ERROR` (chỉ `select_json` / CLI) |
+| `decision` | `REVIEW_REQUIRED` · `TECHNICAL_REVIEW` · `STOP` |
+| `gas_group` | Nhóm khí đã xác định, hoặc `null` |
+| `device_type` | `DEFLAGRATION` · `DETONATION` · `null` |
+| `primary_candidate` | Model tiền chọn (R6) hoặc `null`: `series`, `dn`, `pressure_kpag`, `certified`, `gas_letter`, `reason`, `delta_p_status`, `delta_p`, `model_code` |
+| `candidates` | Mọi ứng viên qua bộ lọc R3, đã xếp hạng |
+| `upgrade_suggestions` | Gợi ý tham khảo R7 (tối đa 10, chỉ khi DEFLAGRATION) |
+| `warnings` | Cảnh báo / việc cần kỹ thuật xác nhận (đã khử trùng lặp) |
+| `steps` | Trace từng luật: `rule`, `status`, `detail` theo thứ tự R1 → R2 → R4 → R3 → R5 → R6 → R7 → R8 |
+| `final_note` | Ghi chú cuối |
+| `engine_version` | Phiên bản thư viện |
+| `input` | Đầu vào sau chuẩn hoá (giá trị engine thực sự dùng) |
+| `errors` | Chỉ có khi `status = INPUT_ERROR` |
+
+Ví dụ rút gọn với đầu vào `{"gas_name": "methane", "operating_pressure_kpag": 8, "service_location": "End-of-line", "requested_dn": 50}`:
+
+```json
+{
+  "status": "PRELIMINARY",
+  "decision": "REVIEW_REQUIRED",
+  "gas_group": "IIA1",
+  "device_type": "DEFLAGRATION",
+  "primary_candidate": {"series": "IFRF", "dn": 50, "pressure_kpag": 50.0, "certified": false,
+                        "model_code": "IFRF-50-BB-{IIA1:chưa xác nhận}-P50", "...": "..."},
+  "candidates": ["... 20 ứng viên ..."],
+  "warnings": ["Kết quả là TIỀN CHỌN; kỹ thuật KANEKO phải xác nhận model trước khi báo giá.", "..."],
+  "steps": [{"rule": "R1", "status": "PASS", "detail": "Nhóm khí IIA1."}, "..."],
+  "final_note": "Chỉ là tiền chọn. Không dùng để đặt hàng/báo giá trước khi kỹ thuật KANEKO xác nhận."
+}
+```
+
+## App demo Streamlit
+
+```bash
+pip install -e ".[app]"
+streamlit run app.py
+```
+
+## Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Cấu trúc thư mục
+
+- `src/kaneko_fa_selector/__init__.py`: API công khai `select`, `select_json`, `load_config`
+- `src/kaneko_fa_selector/engine.py`: luật R1–R8 và các bảng tra (nguồn sự thật của logic)
+- `src/kaneko_fa_selector/inputs.py`: chuẩn hoá / kiểm tra đầu vào, `SelectorInputError`
+- `src/kaneko_fa_selector/__main__.py`: CLI
+- `src/kaneko_fa_selector/rules/kaneko_fa_rules.yaml`: cấu hình tham chiếu (đi kèm package)
+- `src/selector.py`: shim tương thích cho code cũ `from selector import ...`
+- `app.py`: demo Streamlit
+- `tests/`: test thư viện, CLI và app demo
+- `pyproject.toml`: metadata và cấu hình đóng gói; `requirements.txt`: cài editable kèm Streamlit cho demo
+- `build_dist.ps1`: build wheel + sdist vào `dist/` (thư mục `dist/` được `.gitignore` bỏ qua)
+- `source_rule_engine.docx`, `docs_flowchart.png`, `van_relation.md`: tài liệu nguồn và sơ đồ dòng sản phẩm
+
+## Đã triển khai từ tài liệu nguồn
+
+- R1: nhóm khí, tra theo tên hoặc chọn tay; chất lạ và acetylene chuyển kỹ thuật
+- R2: loại thiết bị theo end-of-line, L/D (ngưỡng 30 cho IIC, 50 cho nhóm khác) và điều kiện ống; mặc định bảo thủ DETONATION
+- R4: nhánh IBExU (`yes` chỉ bản chứng nhận, `no` chỉ bản thường, `unknown` cả hai, ưu tiên bản thường)
+- R3: lọc dòng sản phẩm theo bảng rating áp suất trong nguồn
+- R5: báo rõ chưa có hệ số / điểm đường cong; không bịa ΔP
+- R6: chọn ứng viên theo DN khách → DN nhỏ nhất → bản thường trước → rating thấp hơn
+- R7: gợi ý nâng cấp khi kết quả là DEFLAGRATION
+- R8: ghép mã model `{series}-{dn}-BB-{chữ nhóm}-P{rating}[-EX]` kèm cảnh báo
+
+## Lưu ý khi đọc logic
+
+- File YAML chỉ để tham chiếu / hiển thị. Các bảng tra thực sự nằm trong `engine.py`; sửa YAML không đổi kết quả.
+- Loại thiết bị ở R2 (DEFLAGRATION / DETONATION) chưa được dùng để lọc dòng sản phẩm ở R3; engine xét mọi dòng trong `families`.
+- Bước quy đổi cột biểu đồ A/B/C (`gas_column`) có trong code để tham chiếu nhưng `run_engine` chưa gọi.
+- R7 chỉ là lát cắt của danh sách ứng viên (DN ≥ model chính), không tra bảng model Detonation riêng.
+- Khi có `requested_dn`, mọi mã model đều mang DN đó; cột `dn` trong ứng viên mới là DN catalog thật.
+
+## Cần bổ sung để dùng thật
+
+1. Bảng đầy đủ 215 chất (EN/JP/MESG).
+2. Đường cong lưu lượng KANEKO đã số hoá và/hoặc hệ số `(a, b)` được phê duyệt cho mọi tổ hợp, kèm khoảng Q hợp lệ.
+3. Catalog DN / áp suất / model và ma trận chứng nhận chính xác.
+4. Kỹ thuật KANEKO rà soát chính thức và bộ test case được chủ sở hữu phê duyệt.

kaneko_fa_selector-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kaneko-fa-selector"
+dynamic = ["version"]
+description = "KANEKO flame arrester preselection rule engine (R1-R8): JSON in, JSON out"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["PyYAML>=6.0"]
+authors = [{ email = "stkengaposa832@gmail.com" }]
+keywords = ["kaneko", "flame arrester", "rule engine", "preselection"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Manufacturing",
+    "Topic :: Scientific/Engineering",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+app = ["streamlit>=1.35"]
+dev = ["pytest>=8.0", "build>=1.0", "twine>=5.0"]
+
+[project.scripts]
+kaneko-fa-selector = "kaneko_fa_selector.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kaneko_fa_selector = ["rules/*.yaml"]
+
+[tool.setuptools.dynamic]
+version = {attr = "kaneko_fa_selector.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kaneko_fa_selector-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+