Update README.md

README.md

@@ -1,4 +1,3 @@
-```markdown
 # Decida-small: 10-Pillar Automated Debate Adjudication Engine
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -7,26 +6,30 @@
 [![Inference Latency](https://img.shields.io/badge/Latency-~4.2s%20(Local%20GPU)-orange.svg)]()
 [![Zero External Daemons](https://img.shields.io/badge/Stack-100%25%20PyTorch%20Local-purple.svg)]()
 
-**Decida-small** is an ultra-fast, 10-pillar automated debate adjudication engine tailored specifically for competitive Indonesian parliamentary and online debate tournaments. Powered by fine-tuned **IndoBERT**, **Sentence-Transformers**, and local **DeBERTa NLI Cross-Encoders**, it evaluates multi-turn Affirmative vs. Opposition cases across 10 analytical dimensions, outputting calibrated floating-point scores and constructive verbal feedback in ~4.2 seconds—without external LLM calls or cloud dependencies.
+**Decida-small** is an ultra-fast, 10-pillar automated debate adjudication engine tailored specifically for competitive Indonesian parliamentary and online debate tournaments.
+
+Powered by fine-tuned **IndoBERT**, **Sentence-Transformers**, and local **DeBERTa NLI Cross-Encoders**, it evaluates multi-turn Affirmative vs. Opposition cases across 10 analytical dimensions, producing calibrated floating-point scores and constructive verbal feedback in approximately 4.2 seconds, without external LLM calls or cloud dependencies.
+
+**Author: Christopher Alberto Hamonangan**
 
 ---
 
-## ⚡ Core Highlights
+## Core Highlights
 
-- **Sub-5s Local Inference:** Evaluates two teams across 6 dense multi-paragraph speeches in ~4.22 seconds on consumer GPU hardware.
+- **Sub-5s Local Inference:** Evaluates two teams across 6 dense multi-paragraph speeches in approximately 4.22 seconds on consumer GPU hardware.
 - **Dedicated Indonesian NLP Stack:** Utilizes fine-tuned IndoBERT (`indobert-base-p1`) for fallacy classification and semantic evaluation tuned to formal Indonesian argumentation register.
 - **Zero-Daemon / Self-Contained:** 100% Python and PyTorch. Eliminates external Ollama/HTTP dependencies, connection resets, and malformed JSON parsing timeouts.
 - **Non-Judgmental Grounded Verbalizer:** Combinatorial slot-filling synthesis engine featuring 250+ modular stylistic variants that quotes real evidentiary claims from the winning team to deliver positive adjudication feedback.
 
 ---
 
-## 🏛️ 10 Evaluation Pillars & Scoring Topology
+## 10 Evaluation Pillars & Scoring Topology
 
-Total final score is computed as a weighted sum ($100\%$ aggregate):
+The total final score is computed as a weighted sum with a 100% aggregate weight:
 
-$$\text{Final Score} = \sum_{i=1}^{10} (w_i \times P_i)$$
+Final Score = Σ (w_i × P_i), for i = 1 to 10
 
-| Pillar | Metric Dimension | Weight ($w_i$) | Underlying Method / Model |
+| Pillar | Metric Dimension | Weight (\(w_i\)) | Underlying Method / Model |
 |:---:|---|:---:|---|
 | **P1** | **Kepadatan Semantik (Semantic Relevance)** | 10% | Dense cosine similarity vs. motion centroid via `all-MiniLM-L6-v2` |
 | **P2** | **Integritas Logika (Fallacy & Logic)** | 15% | Fine-tuned IndoBERT Sequence Classifier (`./model_indobert_fallacy`) |
@@ -41,32 +44,35 @@ $$\text{Final Score} = \sum_{i=1}^{10} (w_i \times P_i)$$
 
 ---
 
-## 📊 Benchmark Run Sample
+## Benchmark Run Sample
 
 ```text
 Mosi: "Dewan ini akan mewajibkan transisi 100% armada transportasi umum ke kendaraan listrik murni (EV) dalam waktu lima tahun ke depan."
+
 Waktu Eksekusi: 4.22 detik
 
-Metrik Pilar                 |     TIM PRO     |   TIM KONTRA   
------------------------------------------------------------------
-P1: Kepadatan Semantik       |         82.65   |         80.92 
-P2: Integritas Logika        |         75.00   |         25.00 
-P3: Daya Respons/Bantahan    |         66.67   |         78.33 
-P4: Struktur A-R-E-L         |         52.50   |         59.17 
-P5: Pertarungan Dampak       |         57.85   |         83.38 
-P6: Alur Wacana / Dinamika   |         91.56   |         93.20 
-P7: Kepadatan Leksikal/Gaya  |         56.75   |         78.59 
-P8: Konsistensi Internal Tim |         89.00   |         83.12 
-P9: Pertahanan & Komparasi   |         49.14   |         53.90 
-P10: Eksploitasi & Kepadatan |         81.93   |         84.72 
------------------------------------------------------------------
-TOTAL SKOR AKHIR             |         69.10   |         67.39 
-=================================================================
+Metrik Pilar                  | TIM PRO | TIM KONTRA
+----------------------------------------------------
+P1: Kepadatan Semantik        |  82.65  |  80.92
+P2: Integritas Logika         |  75.00  |  25.00
+P3: Daya Respons/Bantahan     |  66.67  |  78.33
+P4: Struktur A-R-E-L          |  52.50  |  59.17
+P5: Pertarungan Dampak        |  57.85  |  83.38
+P6: Alur Wacana / Dinamika    |  91.56  |  93.20
+P7: Kepadatan Leksikal/Gaya   |  56.75  |  78.59
+P8: Konsistensi Internal Tim  |  89.00  |  83.12
+P9: Pertahanan & Komparasi    |  49.14  |  53.90
+P10: Eksploitasi & Kepadatan  |  81.93  |  84.72
+----------------------------------------------------
+TOTAL SKOR AKHIR              |  69.10  |  67.39
+====================================================
+
 Pemenang: TIM AFIRMASI (PRO) (Margin: 1.71)
 
------------------------------------------------------------------
+----------------------------------------------------
 ULASAN ANALITIS DEWAN JURI (DECIDA-SMALL FEEDBACK):
------------------------------------------------------------------
+----------------------------------------------------
+
 Kemenangan dengan margin kompetitif 1.71 poin berhasil direngkuh oleh TIM AFIRMASI (PRO).
 
 Penguasaan materi mendasar terbukti lewat susunan argumen yang utuh seperti terlihat saat menegaskan bahwa "Berdasarkan laporan Kementerian Lingkungan Hidup, lebih dari 65% polusi partikulat PM2.5 bersumber...", membangun alur berpikir yang meyakinkan.
@@ -74,65 +80,67 @@ Penguasaan materi mendasar terbukti lewat susunan argumen yang utuh seperti terl
 Memasuki babak pembelaan dan penegasan posisi, alur penalaran tim mengalir secara organik (skor 89.00), di mana pembicara lanjutan bertindak sebagai akselerator kasus yang efektif.
 
 Keunggulan paling menentukan hadir pada ketelitian berpikir tim, membentengi setiap kesimpulan dengan premis pendukung yang sah. Keberhasilan tim dalam menjaga beban pembuktian secara konsisten menjadi alasan fundamental di balik hasil ini.
-=================================================================
 
+====================================================
 ```
 
 ---
 
-## 📁 Repository Structure
+## Repository Structure
 
 ```text
 decida-small/
+│
 ├── pillar/
 │   ├── __init__.py
-│   ├── nli_client.py         # Local PyTorch batch NLI Cross-Encoder wrapper
-│   ├── verbalizer.py         # Combinatorial grounded feedback generator (~0.001s)
-│   ├── pillar1.py            # P1: Semantic density & motion relevance
-│   ├── pillar2.py            # P2: Logical integrity (IndoBERT fallacy detection)
-│   ├── pillar3.py            # P3: Rebuttal validity & direct clash
-│   ├── pillar4.py            # P4: A-R-E-L structure analysis
-│   ├── pillar5.py            # P5: Impact weighing & clash balance
-│   ├── pillar6.py            # P6: Discourse trajectory & flow
-│   ├── pillar7.py            # P7: Lexical density, register, & diversity
-│   ├── pillar8.py            # P8: Multi-turn internal team consistency
-│   ├── pillar9.py            # P9: Premise defense & comparative delta
-│   └── pillar10.py           # P10: Strategic premise exploitation & density
-├── model_indobert_fallacy/   # Fine-tuned weights (or pull via Hugging Face Hub)
-├── model_minilm/             # Local sentence-transformer cache
+│   ├── nli_client.py          # Local PyTorch batch NLI Cross-Encoder wrapper
+│   ├── verbalizer.py          # Combinatorial grounded feedback generator (~0.001s)
+│   ├── pillar1.py             # P1: Semantic density & motion relevance
+│   ├── pillar2.py             # P2: Logical integrity (IndoBERT fallacy detection)
+│   ├── pillar3.py             # P3: Rebuttal validity & direct clash
+│   ├── pillar4.py             # P4: A-R-E-L structure analysis
+│   ├── pillar5.py             # P5: Impact weighing & clash balance
+│   ├── pillar6.py             # P6: Discourse trajectory & flow
+│   ├── pillar7.py             # P7: Lexical density, register, & diversity
+│   ├── pillar8.py             # P8: Multi-turn internal team consistency
+│   ├── pillar9.py             # P9: Premise defense & comparative delta
+│   └── pillar10.py            # P10: Strategic premise exploitation & density
+│
+├── model_indobert_fallacy/    # Fine-tuned weights (or pull via Hugging Face Hub)
+├── model_minilm/              # Local sentence-transformer cache
+│
 ├── .gitignoxre
 ├── LICENSE
 ├── README.md
 ├── requirements.txt
-└── run_judger.py             # CLI driver script with batch execution benchmark
-
+└── run_judger.py              # CLI driver script with batch execution benchmark
 ```
 
 ---
 
-## 🚀 Installation & Setup
+## Installation & Setup
 
 ### 1. Prerequisites
 
-* Python 3.10 or higher
-* NVIDIA CUDA-compatible GPU (recommended for sub-5s performance) or modern multi-core CPU
+- Python 3.10 or higher
+- NVIDIA CUDA-compatible GPU (recommended for sub-5s performance) or modern multi-core CPU
 
 ### 2. Clone and Environment Setup
 
 ```bash
-git clone [https://github.com/USERNAME/decida-small.git](https://github.com/USERNAME/decida-small.git)
+git clone https://github.com/USERNAME/decida-small.git
 cd decida-small
 
 python -m venv venv
 
-# Windows (PowerShell):
+# Windows (PowerShell)
 .\venv\Scripts\Activate.ps1
-# Linux / macOS:
+
+# Linux / macOS
 source venv/bin/activate
 
 pip install --upgrade pip
 pip install -r requirements.txt
-
 ```
 
 ### 3. Weights Configuration
@@ -141,59 +149,47 @@ Ensure the fine-tuned IndoBERT directory (`./model_indobert_fallacy`) and Senten
 
 ```python
 # pillar/pillar2.py
-MODEL_PATH = "USERNAME_HF/decida-indobert-fallacy"
 
+MODEL_PATH = "USERNAME_HF/decida-indobert-fallacy"
 ```
 
 ---
 
-## 💻 Usage
+## Usage
 
 Run the standard evaluation interface:
 
 ```bash
 python run_judger.py
-
 ```
 
-* **Mode 1 (Template):** Automatically loads the built-in EV fleet transition motion along with 3 Affirmative and 3 Opposition speeches for immediate profiling.
-* **Mode 2 (Live):** Prompts for interactive speech-by-speech input with live multi-line terminal entry (`--end` to conclude debate turns).
+- **Mode 1 (Template):** Automatically loads the built-in EV fleet transition motion along with 3 Affirmative and 3 Opposition speeches for immediate profiling.
+- **Mode 2 (Live):** Prompts for interactive speech-by-speech input with live multi-line terminal entry (`--end` to conclude debate turns).
 
 ---
 
-## 🗣️ Verbalizer Architecture
+## Verbalizer Architecture
 
 Unlike LLM prompt generators that can hallucinate or produce demoralizing critiques, `pillar/verbalizer.py`:
 
 1. Computes the maximum comparative margin across all 10 pillars.
 2. Extracts verbatim evidentiary phrases directly from the winning team's text.
 3. Assembles a 4-paragraph formal critique using a slot-filling combination engine with over 250 verified positive rhetorical options.
-4. Completes execution in **<0.002 seconds**.
+4. Completes execution in **less than 0.002 seconds**.
 
 ---
 
-## 📜 Citation & License
+## Citation & License
 
-This project is open-sourced under the [MIT License](https://www.google.com/search?q=LICENSE).
+This project is open-sourced under the [MIT License](LICENSE).
 
 ```bibtex
 @software{decida_small_2026,
-  author = {Decida AI Team},
-  title = {Decida-small: 10-Pillar Automated Debate Adjudication Engine for Indonesian Debate},
-  year = {2026},
-  publisher = {GitHub},
-  journal = {GitHub repository},
-  howpublished = {\url{[https://github.com/USERNAME/decida-small](https://github.com/USERNAME/decida-small)}}
+  author       = {Christopher Alberto Hamonangan},
+  title        = {Decida-small: 10-Pillar Automated Debate Adjudication Engine for Indonesian Debate},
+  year         = {2026},
+  publisher    = {Huggingface},
+  journal      = {Huggingface Organization},
+  howpublished = {\url{https://huggingface.co/BhinnekaAI/Decida-small}
 }
-
-```
-
-```
-
-<ElicitationsGroup message="Pilihan langkah berikutnya untuk melengkapi repositori:">
-  <Elicitation label="Buat template file LICENSE (MIT)" query="Buatkan teks lengkap file LICENSE berlisensi MIT untuk proyek Decida-small tahun 2026."/>
-  <Elicitation label="Buatkan file upload_model.py otomatis ke Hugging Face Hub" query="Buatkan skrip lengkap upload_model.py untuk push folder model_indobert_fallacy ke Hugging Face Hub dengan validasi token otomatis."/>
-  <Elicitation label="Buatkan unit test PyTest (test_engine.py)" query="Buatkan berkas tests/test_engine.py untuk memverifikasi eksekusi 10 pilar dan verbalizer sebelum di-push ke GitHub."/>
-</ElicitationsGroup>
-
 ```