Metadata-Version: 2.4
Name: anch-hash
Version: 1.0.0
Summary: ANCH — Adaptive Neural Chaotic Hash Framework: experimental hashing combining feature extraction, neural parameter generation, and chaos theory.
Author: ANCH Framework Team
License: MIT
Project-URL: Homepage, https://anch-framework.vercel.app
Project-URL: Repository, https://github.com/anch-framework/anch
Project-URL: Documentation, https://anch-framework.vercel.app/docs
Project-URL: Bug Tracker, https://github.com/anch-framework/anch/issues
Keywords: hashing,cryptography,chaos-theory,experimental,adaptive,neural,fingerprinting,integrity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: rich>=13.0; extra == "benchmark"

# ANCH — Adaptive Neural Chaotic Hash Framework

<p align="center">
  <img src="https://img.shields.io/badge/versi-0.1.0-blue?style=flat-square" alt="version">
  <img src="https://img.shields.io/badge/python-3.12+-green?style=flat-square" alt="python">
  <img src="https://img.shields.io/badge/lisensi-MIT-orange?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/status-eksperimental-red?style=flat-square" alt="status">
  <img src="https://img.shields.io/badge/dependensi-nol-brightgreen?style=flat-square" alt="deps">
</p>

> **ANCH (Adaptive Neural Chaotic Hash)** adalah framework hashing eksperimental sumber terbuka berbasis Python yang menggabungkan Ekstraksi Fitur (Feature Extraction), Generasi Parameter Pseudo-Neural, Chaos Theory (Teori Kekacauan), Permutasi Dinamis, dan Compression Engine untuk menghasilkan nilai digest 256-bit yang unik.

---

## ⚠️ Pernyataan Penting (Disclaimer)

ANCH adalah sebuah **framework penelitian eksperimental**. Protokol ini **tidak dimaksudkan** sebagai pengganti fungsi hash kriptografi standar industri seperti SHA-256 atau SHA-3 dalam sistem produksi nyata. Gunakan framework ini untuk keperluan riset akademis, benchmarking, edukasi kriptografi berbasis chaos, dan eksperimen fingerprinting data.

---

## ✨ Fitur Utama

| Fitur | Deskripsi |
|--------|-------------|
| 🧠 **Neural Parameter Generation** | Parameter operasional hash dihasilkan secara adaptif dari representasi fitur input. |
| 🌀 **Chaos Theory Engine** | Menggunakan rumus *Logistic Map* untuk menghasilkan aliran byte acak kacotik (*chaotic stream*). |
| 🔀 **Dynamic Permutation** | Pengacakan bit dan rotasi kata berbasis chaos untuk memaksimalkan efek difusi longsor (*avalanche effect*). |
| 🗜️ **Compression Engine** | Kompresi multi-round berbasis struktur mirip jaringan Feistel untuk pemampatan state internal. |
| 🔬 **Feature Extraction** | Menganalisis karakteristik input data: panjang, bobot Hamming, Shannon entropy, distribusi frekuensi byte, dan bigram transition. |
| 📊 **Built-in Benchmark Suite** | Pengujian bawaan untuk menghitung tingkat tabrakan (collisions), efek avalanche, nilai entropy digest, dan throughput. |
| 🖥️ **Antarmuka CLI** | Akses cepat ke semua fungsi utama framework langsung dari terminal. |
| 0️⃣ **Tanpa Dependensi Eksternal** | Ditulis dalam Python murni tanpa membutuhkan library tambahan seperti NumPy atau TensorFlow untuk versi dasar. |

---

## 🚀 Instalasi

Instal langsung secara online melalui PyPI:

```bash
pip install anch-hash
```

Atau instal dari source code lokal:

```bash
git clone https://github.com/YudaHasibuan/enkripsi-ANCH.git
cd enkripsi-ANCH
pip install -e ".[dev]"
```

---

## 🔧 Panduan Penggunaan Cepat (Python API)

```python
import anch

# 1. Hashing String Sederhana
digest = anch.hash("hello world")
print(f"Hasil Hash: {digest}")  # Menghasilkan 64 karakter hex (256-bit)

# 2. Verifikasi Hash
apakah_cocok = anch.verify("hello world", digest)
print(f"Verifikasi: {apakah_cocok}")  # True

# 3. Hashing File
digest_file = anch.hash_file("dokumen.pdf")
print(f"Hash File: {digest_file}")

# 4. Pengujian Efek Avalanche (Longsor)
# Mengukur berapa persen bit output yang berubah ketika input diubah 1 bit/karakter
persentase_perubahan = anch.avalanche("hello", "HELLO")
print(f"Efek Avalanche: {persentase_perubahan}% (Idealnya mendekati 50%)")

# 5. Pengukuran Entropy Digest
score = anch.entropy(digest)
print(f"Nilai Shannon Entropy: {score} bits/byte (Idealnya mendekati 8.0)")

# 6. Deteksi Tabrakan (Collision Test)
data_uji = ["data_1", "data_2", "data_3", "data_1"]
laporan = anch.collision_test(data_uji)
print(f"Total Tabrakan Terdeteksi: {laporan['collisions']}")
```

---

## 🖥️ Penggunaan via CLI (Command Line Interface)

Setelah paket diinstal, perintah `anch` dapat langsung dijalankan dari terminal:

```bash
# Melakukan hash teks
anch hash "hello world"

# Melakukan hash berkas/file
anch hash-file laporan.pdf

# Memverifikasi teks terhadap hash
anch verify "hello world" <nilai_digest>

# Menganalisis efek avalanche antara dua teks
anch avalanche "hello" "HELLO"

# Menghitung nilai entropy dari suatu hash
anch entropy <nilai_digest>

# Menjalankan pengujian performa & analisis kriptografis bawaan
anch benchmark --samples 150
```

---

## 🏗️ Alur Arsitektur (Pipeline Hashing)

Proses transformasi data masukan menjadi digest keluaran mengikuti tahapan berikut:

```
Data Masukan (Teks/Byte/File)
    ↓
Feature Extractor        → Menghitung bit count, entropy, frekuensi byte, & bigram
    ↓
Neural Parameter Gen     → Menghasilkan seed, nilai-r chaos, rotasi schedule, & key kompresi
    ↓
Chaotic Engine           → Iterasi Logistic Map (x_n+1 = r * x_n * (1 - x_n)) → byte stream chaos
    ↓
Dynamic Permutation      → Pengacakan bit Fisher-Yates + rotasi byte state internal
    ↓
Compression Engine       → Putaran Feistel (4-16 putaran) & pencampuran XOR sisa state
    ↓
Finalisasi Digest        → Pelipatan state 64-byte menjadi 32-byte (256-bit Hex)
```

---

## 📊 Analisis Performa & Karakteristik

ANCH dirancang sebagai algoritma adaptif yang mementingkan kekacauan matematis (chaos) dibandingkan kecepatan mentah. Berikut adalah perbandingan performa ANCH vs SHA-256 pada Python 3.12 (Rata-rata 10 kali pengujian):

| Ukuran Input | Waktu ANCH (ms) | Waktu SHA-256 (ms) | Rasio Kecepatan | Keterangan |
|--------------|-----------------|-------------------|----------------|------------|
| 64 Byte      | ~2.4 ms         | ~0.005 ms         | ~480x lebih lambat | Sangat cepat untuk string pendek |
| 1 Kilobyte   | ~5.8 ms         | ~0.012 ms         | ~483x lebih lambat | Pengaruh kompresi deterministik |
| 64 Kilobyte  | ~274 ms         | ~0.46 ms          | ~596x lebih lambat | Direkomendasikan untuk eksperimen |

*Catatan: Nilai rata-rata avalanche effect yang dicapai oleh ANCH berkisar antara **47% hingga 49%** (sangat dekat dengan nilai teoritis ideal 50%), yang membuktikan tingkat difusi bit yang kuat.*

---

## 📦 Struktur Repositori

```
ANCH/
├── src/anch/
│   ├── __init__.py        # Eksposur API Publik
│   ├── __main__.py        # Titik entri CLI
│   ├── core.py            # Orkestrator pipeline utama
│   ├── feature.py         # Analisis karakteristik input
│   ├── neural.py          # Generator parameter berbasis lapisan linier
│   ├── chaos.py           # Generator Logistic Map & Tent Map
│   ├── permutation.py     # Logika pengacakan bit & rotasi kata
│   ├── compression.py     # Algoritma pemampatan state Feistel
│   └── benchmark.py       # Suite benchmarking terintegrasi
├── tests/
│   ├── test_core.py       # Pengujian API publik
│   └── test_modules.py    # Pengujian fungsionalitas internal modul
├── website/               # Dashboard launching visual Next.js & Playground
├── docs/                  # File MkDocs tambahan
├── pyproject.toml         # Konfigurasi instalasi setuptools
└── README.md              # Dokumentasi utama proyek
```

---

## 🗺️ Rencana Pengembangan (Roadmap)

- [x] **v0.1.0** — Mesin Inti Hash, SDK Python, CLI, Unit Tests, Rilis PyPI.
- [ ] **v0.2.0** — Dashboard Antarmuka Uji Kecepatan, REST API (FastAPI), Akselerasi Feature Extractor dengan NumPy.
- [ ] **v0.3.0** — Penambahan Chaos Maps baru (Tent Map terintegrasi & Hénon Map), Integrasi opsional TensorFlow.
- [ ] **v1.0.0** — Rilis stabil penuh, integrasi plugin komunitas, audit keamanan eksternal.

---

## 📄 Lisensi

Proyek ini dilisensikan di bawah **Lisensi MIT** — bebas digunakan dan dimodifikasi untuk tujuan akademis maupun komersial.
