Metadata-Version: 2.4
Name: fktd
Version: 0.1.0
Summary: FKTD — Fraud KYC KTP Detector: OCR + strict cross-validation for Indonesian ID cards (KTP).
Project-URL: Homepage, https://github.com/rezayw4/Fraud-KYC-KTP-Detector
Project-URL: Issues, https://github.com/rezayw4/Fraud-KYC-KTP-Detector/issues
Author: rezayw4
License: MIT
License-File: LICENSE
Keywords: fraud-detection,indonesia,ktp,kyc,ocr,tesseract
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Requires-Dist: easyocr>=1.7
Requires-Dist: numpy>=1.26
Requires-Dist: opencv-python>=4.10
Requires-Dist: pillow>=10.4
Requires-Dist: pydantic>=2.8
Requires-Dist: python-dateutil>=2.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: paddle
Requires-Dist: paddleocr>=2.8; extra == 'paddle'
Requires-Dist: paddlepaddle>=2.6; extra == 'paddle'
Description-Content-Type: text/markdown

# FKTD — Fraud KYC KTP Detector

OCR multi-engine + validasi silang **ketat** untuk KTP Indonesia. Bukan sekadar
cek field kosong — FKTD memanfaatkan struktur NIK untuk mendeteksi data palsu.

## Flow

```
upload gambar ──▶ OCR (EasyOCR / PaddleOCR) ──▶ ekstraksi field ──▶ deteksi fraud ──▶ FraudResult
```

## Instalasi

```bash
pip install fktd            # langsung lengkap: EasyOCR + deteksi fraud
```

Cukup `pip install fktd` — EasyOCR sudah termasuk, jalan di mana saja (termasuk
macOS / Apple Silicon), tanpa perlu install binary sistem.

Mau engine PaddleOCR (akurasi ekstra, ideal di server Linux)? Tambahkan opsional:

```bash
pip install 'fktd[paddle]'  # opsional; paddlepaddle bisa rewel di Apple Silicon
```

| Engine | Status | Kapan dipakai |
|---|---|---|
| **EasyOCR** | Sudah termasuk | Default. Mulus di Mac, native bahasa Indonesia. |
| **PaddleOCR** | Opsional `[paddle]` | Akurasi & kecepatan terbaik untuk dokumen; paling pas di Linux. |

## Pemakaian

```python
from fktd import FKTD

detector = FKTD(engine="easyocr")  # atau engine="paddle"
result = detector.process("ktp.jpg")

print(result.is_passed)           # True/False
print(result.risk_score)          # 0 (aman) .. 100 (mencurigakan)
print(result.summary())           # daftar check yang gagal
print(result.data.model_dump())   # semua field hasil OCR
```

## Field yang diekstrak (20)

Provinsi · Kota/Kabupaten · NIK · Nama · Tempat Lahir · Tgl Lahir · Jenis Kelamin ·
Gol. Darah · Alamat · RT/RW · Kel/Desa · Kecamatan · Agama · Status Perkawinan ·
Pekerjaan · Kewarganegaraan · Berlaku Hingga · Tempat & Tgl Dikeluarkan ·
Foto (bool) · Tanda Tangan (bool)

## Aturan deteksi fraud

**Kelengkapan** — semua field wajib harus terisi (kosong = CRITICAL).

**Cross-check NIK** (NIK ter-encode):

| Cek | Severity |
|---|---|
| NIK tepat 16 digit | CRITICAL |
| Tgl lahir di NIK == field Tgl Lahir | CRITICAL |
| Gender di NIK (DD>40 = perempuan) == field Jenis Kelamin | CRITICAL |

**Validasi lokasi (via API wilayah)** — kode di NIK dicocokkan ke data wilayah
resmi (API emsifa + snapshot offline 514 kab/kota):

| Cek | Severity |
|---|---|
| Kode provinsi (2 digit) valid & cocok field Provinsi | CRITICAL |
| Kode kab/kota (4 digit) valid & cocok field Kota/Kabupaten | CRITICAL |

> Contoh fraud: NIK `3171...` = Jakarta Selatan, tapi kartu tertulis "JAKARTA
> BARAT" (`3174`) → terdeteksi tidak cocok.

**Enum (exact match) — nilai resmi saja:**

| Field | Nilai resmi |
|---|---|
| Jenis Kelamin | LAKI-LAKI, PEREMPUAN |
| Agama | ISLAM, KRISTEN, KRISTEN PROTESTAN, KATOLIK, HINDU, BUDHA, KONGHUCU (6 yang diakui) |
| Status Perkawinan | BELUM KAWIN, KAWIN, CERAI HIDUP, CERAI MATI |
| Kewarganegaraan | WNI, WNA |
| Gol. Darah | A, B, AB, O, - |

**Format teks KTP asli:**
- Semua nilai field (setelah `:`) harus **HURUF KAPITAL**.
- **Nama tidak boleh mengandung angka**.
- RT/RW = `NNN/NNN`; tanggal lahir valid & wajar (umur 0–120, tidak di masa depan).
- **Berlaku Hingga harus `SEUMUR HIDUP`** (e-KTP sejak 2016 berlaku seumur hidup;
  tanggal kedaluwarsa = kartu lama/tidak valid).

**OCR confidence** — confidence rendah pada NIK/Nama/Tgl Lahir menaikkan risiko.

**Vision** — keberadaan foto (deteksi wajah) & tanda tangan.

Hasil **PASS** bila: semua field wajib terisi, tidak ada kegagalan CRITICAL, dan
`risk_score < risk_threshold` (default 25). Mode data wilayah diatur lewat
`FKTD(wilayah_provider=...)`: `"auto"` (default, snapshot + API), `"api"` (live),
`"local"` (offline).

## ⚠️ Disclaimer

**Khusus KTP elektronik (KTP-el / e-KTP).** FKTD dirancang untuk format **e-KTP**
— standar KTP Indonesia sejak 2011 dengan masa berlaku **SEUMUR HIDUP**. Aturan
seperti "Berlaku Hingga harus SEUMUR HIDUP" **tidak berlaku** untuk KTP non-
elektronik / KTP lama (sebelum 2011) yang masih memuat tanggal kedaluwarsa —
kartu semacam itu akan ditandai gagal oleh FKTD karena memang sudah tidak berlaku.

**Validasi bersifat struktural & heuristik, BUKAN verifikasi resmi:**

- Pengecekan NIK & wilayah hanya memvalidasi **struktur dan konsistensi** data di
  kartu. FKTD **tidak** mengakses database kependudukan resmi (Dukcapil), jadi
  **tidak dapat memastikan** sebuah NIK benar-benar terdaftar atau milik seseorang.
- Hasil `PASS` **tidak menjamin** KTP asli; hasil `FAIL` **tidak selalu berarti**
  pemalsuan (bisa karena OCR meleset, kartu lama, atau foto berkualitas rendah).
- `risk_score` adalah indikator bantu, bukan keputusan hukum.

**Untuk KYC produksi**, hasil FKTD harus dikombinasikan dengan **verifikasi resmi**
ke Dukcapil/penyedia berlisensi (mis. layanan verifikasi NIK pemerintah) dan,
bila perlu, peninjauan manual.

**Privasi.** KTP memuat data pribadi (NIK, nama, alamat). Pastikan pemrosesan
mematuhi **UU PDP (UU No. 27/2022)** dan regulasi terkait: punya dasar hukum/
persetujuan, batasi penyimpanan, dan amankan datanya. Library ini tidak mengirim
gambar KTP ke mana pun; hanya pemanggilan API **data wilayah publik** (kode
provinsi/kab-kota) yang dilakukan ke jaringan — dan itu pun bisa dimatikan dengan
`wilayah_provider="local"`.

## Lisensi

MIT
