Update README.md

README.md

@@ -11,12 +11,12 @@ tags:
   - AI-Safety
   - Evaluation
   - Judge-model
-  
+  - Argumentation
 ---
 
-[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-model-blue)](https://huggingface.co/skatzR/RQA-X1)
+[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-model-blue)](https://huggingface.co/skatzR/RQA-X1.1)
 
-# 🧠 RQA — Reasoning Quality Analyzer (v1)
+# 🧠 RQA — Reasoning Quality Analyzer (X1.1)
 
 **RQA** is a **judge model** designed to evaluate the *quality of reasoning in text*.  
 It does **not** generate, rewrite, or explain content — instead, it **assesses whether a text contains logical problems**, and if so, **what kind**.
@@ -27,19 +27,19 @@ It does **not** generate, rewrite, or explain content — instead, it **assesses
 
 ## 🔍 What Problem Does RQA Solve?
 
-Modern LLM-generated and human-written texts often:
+Texts written by humans or LLMs can:
 
 - sound coherent,
 - use correct vocabulary,
-- follow a plausible narrative,
+- appear persuasive,
 
 …but still contain **logical problems** that are:
 
-- subtle,
-- hidden in structure,
-- difficult to detect with standard classifiers.
+- implicit,
+- structural,
+- hidden in argumentation.
 
-**RQA focuses specifically on reasoning quality**, not style or factual correctness.
+**RQA focuses strictly on reasoning quality**, not on style, sentiment, or factual correctness.
 
 ---
 
@@ -52,23 +52,24 @@ Modern LLM-generated and human-written texts often:
 | **Pooling** | Mean pooling |
 | **Heads** | 2 (binary + multi-label) |
 | **Language** | Russian 🇷🇺 |
-| **License** | Mit |
+| **License** | MIT |
 
 ---
 
 ## 🧠 What the Model Predicts
 
-RQA produces **two independent outputs**:
+RQA produces **two independent signals** that are combined at inference time:
 
-### 1️⃣ Logical Issue Detection
+### 1️⃣ Logical Issue Detection (Binary)
 
-- **Binary decision**  
-  `has_logical_issue ∈ {0, 1}`
-- Calibrated probability is provided
+- `has_issue ∈ {false, true}`
+- Calibrated probability available
+- Designed to answer:  
+  **“Does this text contain a reasoning problem?”**
 
-### 2️⃣ Error Type Classification (Multi-label)
+### 2️⃣ Error Type Signals (Multi-label)
 
-If a logical issue exists, the model can identify one or more of the following error types:
+The model estimates probabilities for specific error types:
 
 - `false_causality`
 - `unsupported_claim`
@@ -77,35 +78,67 @@ If a logical issue exists, the model can identify one or more of the following e
 - `contradiction`
 - `circular_reasoning`
 
-> Error classification is applied **only if a logical issue is detected**.
+⚠️ **Important**  
+Error type probabilities are **diagnostic signals**, not mandatory labels.  
+They are surfaced **only if `has_issue == true`** during inference.
 
 ---
 
-## 🧠 Hidden Logical Problems (Key Concept)
+## 🟡 Hidden Logical Problems (Key Concept)
 
 RQA explicitly distinguishes between:
 
-- **Explicit logical errors**  
-  (clearly identifiable fallacies)
+### 🔴 Explicit Logical Errors
+Clearly identifiable fallacies:
+- invalid causal inference
+- circular reasoning
+- contradictions
+- unsupported claims
 
-- **Hidden logical problems**  
-  (structural issues such as:
-  - implicit assumptions,
-  - shifts of criteria,
-  - persuasive but unsupported reasoning)
+### 🟡 Hidden Logical Problems
+Texts that are:
+- argumentative or persuasive,
+- structurally incomplete,
+- reliant on implicit assumptions,
 
-Hidden problems are **not labeling mistakes** — they are a **separate, intentional difficulty class**.
+but **do not contain a cleanly classifiable fallacy**.
+
+Examples:
+- missing or unstated premises
+- rhetorical generalizations
+- context-dependent claims
+
+Hidden problems are **not misclassifications** —  
+they are an **intended diagnostic category**.
+
+---
+
+## ⚖️ Inference Logic (Important)
+
+The model uses **decision logic on top of raw logits**:
+
+- Binary head decides **whether a problem exists**
+- Error heads provide **type-level evidence**
+- If:
+  - `has_issue == false`
+  - but error probabilities are non-zero  
+  → the text may be flagged as **borderline** or **hidden problem**
+
+This prevents:
+- false positive error labels,
+- incoherent outputs,
+- over-triggering on clean factual texts.
 
 ---
 
 ## 🏗️ Architecture Details
 
 - **Encoder**: XLM-RoBERTa Large (pretrained weights preserved)
-- **Pooling**: Mean pooling (more stable than CLS for long texts)
-- **Two independent heads**:
-  - Binary head: `has_logical_issue`
-  - Multi-label head: `error_types`
-- **Separate projections and dropout** to reduce negative transfer
+- **Pooling**: Mean pooling (robust for long texts)
+- **Two independent projections**:
+  - binary reasoning head
+  - multi-label error head
+- Separate dropout and projections to reduce negative transfer
 
 ---
 
@@ -113,32 +146,34 @@ Hidden problems are **not labeling mistakes** — they are a **separate, intenti
 
 ### 🔒 Strict Data Contract
 
-- Logical texts **cannot** contain errors
-- Hidden problems **cannot** contain explicit error labels
-- Invalid samples are **removed**, never auto-fixed
+- Logical texts **contain no errors**
+- Hidden-problem texts **contain no explicit fallacies**
+- Invalid samples are **removed**, not auto-corrected
 
 ### ⚖️ Balanced Difficulty
 
-- Hidden problems ≤ **30%** of all problematic texts  
-  (`hidden / (explicit + hidden) ≤ 0.3`)
+- Hidden problems ≤ **30%** of problematic texts
+- Prevents collapse into vague uncertainty detection
 
 ### 🎯 Loss Design
 
-- Binary cross-entropy for issue detection
+- Binary BCE for issue detection
 - Masked multi-label loss for error types
-- **Uncertainty-weighted loss** for stable multi-task training
+- Stability-oriented multi-task optimization
 
 ---
 
 ## 🌡️ Confidence Calibration
 
-RQA uses **post-hoc Temperature Scaling**:
+RQA applies **post-hoc temperature scaling**:
 
 - Separate calibration for:
-  - `has_logical_issue`
+  - `has_issue`
   - each error type
-- Ensures predicted probabilities reflect real confidence
-- Enables safe thresholding in production
+- Enables:
+  - meaningful probabilities
+  - safe threshold tuning
+  - production use without retraining
 
 ---
 
@@ -149,15 +184,16 @@ RQA uses **post-hoc Temperature Scaling**:
 - Reasoning quality evaluation
 - LLM output auditing
 - AI safety pipelines
-- Educational or analytical tooling
-- Pre-filtering or routing in generation systems
+- Argumentation analysis
+- Pre-filtering / routing systems
 
 ### ❌ Not intended for:
 
 - Text generation
-- Explanation or correction of errors
-- Style or grammar analysis
-- Factual verification
+- Error correction
+- Explanation or tutoring
+- Grammar or style analysis
+- Fact checking
 
 ---
 
@@ -166,34 +202,35 @@ RQA uses **post-hoc Temperature Scaling**:
 - Conservative by design
 - Optimized for **low false positives**
 - Explicitly robust to:
-  - topic changes,
-  - writing style,
+  - topic changes
+  - writing style
   - emotional tone
 
-The model judges **logic**, not rhetoric.
+RQA judges **logical structure**, not persuasion quality.
 
 ---
 
-## 📦 Output Example
+## 📦 Example Output
 
 ```json
 {
-  "has_logical_issue": true,
-  "has_issue_probability": 0.87,
+  "has_issue": true,
+  "issue_probability": 0.93,
   "errors": [
-    { "type": "missing_premise", "probability": 0.72 },
-    { "type": "overgeneralization", "probability": 0.61 }
-  ]
+    { "type": "false_causality", "probability": 0.88 }
+  ],
+  "hidden_problem": false,
+  "borderline": false
 }
 ```
 ---
 
 ## 📚 Training Data (High-level)
 
-- **Custom-generated dataset**
+- **Custom-built dataset**
 - **Thousands of long-form argumentative texts**
-- **Multiple domains and reasoning modes**
-- **Carefully controlled balance of:**
+- **Multiple domains and reasoning styles**
+- Carefully controlled balance of:
   - logical texts
   - explicit errors
   - hidden problems
@@ -204,10 +241,10 @@ The model judges **logic**, not rhetoric.
 
 ## ⚠️ Limitations
 
-- RQA evaluates **reasoning structure**, not factual truth
-- A logically valid argument may still be **factually incorrect**
-- Subtle philosophical disagreements are **not always logical errors**
-- The model may over-detect issues in highly rhetorical or persuasive texts.
+- Logical validity ≠ factual correctness
+- Purely descriptive texts may still trigger *diagnostic signals*
+- Highly rhetorical or persuasive texts can be flagged as **hidden problems**
+- Philosophical disagreement is **not always** a logical error
 
 ---
 
@@ -216,19 +253,17 @@ The model judges **logic**, not rhetoric.
 > **Good reasoning is not about sounding convincing —  
 > it is about what actually follows from what.**
 
-RQA is built to reflect this principle.
+RQA is built around this principle.
 
 ---
 
 ## 🔧 Implementation Details
 
-This model uses a custom Hugging Face architecture (`modeling_rqa.py`)
-and is loaded with:
-
-- `trust_remote_code=True`
-- `safetensors` weights (no `.bin` file)
-
-This is expected and fully supported by Hugging Face.
+- Custom Hugging Face architecture (`modeling_rqa.py`)
+- Requires:
+  - `trust_remote_code=True`
+- Uses `safetensors`
+- No `.bin` weights (this is expected behavior)
 
 ---
 
@@ -238,12 +273,12 @@ This is expected and fully supported by Hugging Face.
 from transformers import AutoTokenizer, AutoModel
 
 tokenizer = AutoTokenizer.from_pretrained(
-    "USERNAME/RQA-v1",
+    "skatzR/RQA-X1.1",
     trust_remote_code=True
 )
 
 model = AutoModel.from_pretrained(
-    "USERNAME/RQA-v1",
+    "skatzR/RQA-X1.1",
     trust_remote_code=True
 )
 
@@ -256,8 +291,6 @@ errors_logits = outputs["errors_logits"]
 
 ---
 
-## 📜 License
+📜 License
 
 MIT
-
----