Architecture updated

.gitignore

@@ -44,3 +44,10 @@ Thumbs.db
 # Environment variables
 .env
 .env.localrailway.toml
+
+
+# Validation ignored as of now
+validation/
+data/validation_data/
+logs/
+notebooks/

README.md

@@ -1,5 +1,5 @@
 ---
-title: Text Authentication Platform
+title: TEXT-AUTH — Evidence-Based Text Forensics System
 emoji: 🔍
 colorFrom: blue
 colorTo: purple
@@ -12,8 +12,8 @@ license: mit
 
 <div align="center">
 
-# 🔍 AI Text Authentication Platform
-## Enterprise‑Grade AI Content Authentication
+# 🛡️ TEXT-AUTH
+## Evidence-First Text Forensics & Authenticity Assessment
 
 ![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
 ![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)
@@ -31,9 +31,9 @@ license: mit
 - [Key Differentiators](#key-differentiators)
 - [System Architecture](#system-architecture)
 - [Workflow / Data Flow](#workflow--data-flow)
-- [Detection Metrics & Mathematical Foundation](#detection-metrics--mathematical-foundation)
+- [Forensic Signals & Mathematical Foundation](#forensic-signals--mathematical-foundation)
 - [Ensemble Methodology](#ensemble-methodology)
-- [Domain-Aware Detection](#domain-aware-detection)
+- [Domain-Aware Analysis](#domain-aware-analysis)
 - [Performance Characteristics](#performance-characteristics)
 - [Project Structure](#project-structure)
 - [API Endpoints](#api-endpoints)
@@ -51,19 +51,24 @@ license: mit
 
 ## 📝 Abstract
 
-**AI Text Authentication Platform** is a research‑oriented, production‑minded MVP that detects and attributes AI‑generated text across multiple domains using a multi‑metric, explainable ensemble approach. The platform is designed for reproducibility, extensibility, and real‑world deployment: model weights are auto‑fetched from Hugging Face on first run and cached for offline reuse.
+**TEXT-AUTH** is a research-oriented, production-minded **text forensics system** that evaluates written content using multiple independent linguistic, statistical, and semantic signals.
 
-This README is research‑grade (detailed math, methodology, and benchmarks) while being approachable for recruiters and technical reviewers.
+Rather than claiming authorship or identifying a generation source, the platform performs **evidence-based probabilistic assessment** of textual consistency patterns. It reports confidence-calibrated signals, uncertainty estimates, and human-interpretable explanations to support downstream decision-making.
 
-*For detailed technical documentation, see [Technical Docs](docs/BLOGPOST.md). For research methodology, see [Whitepaper](docs/WHITE_PAPER.md).*
+TEXT-AUTH is designed as a **decision-support and forensic analysis tool**, not a binary classifier or attribution oracle.
+
+- *For Architectural details, see [Architecture](docs/ARCHITECTURE.md).*
+- *For detailed technical documentation, see [Technical Docs](docs/BLOGPOST.md).* 
+- *For research methodology, see [Whitepaper](docs/WHITE_PAPER.md).*
+- *For API documentation, see [API Documentation](docs/API_DOCUMENTATION.md).*
 
 ---
 
 ## 🚀 Overview
 
-**Problem.** AI generation tools increasingly produce publishable text, creating integrity and verification challenges in education, hiring, publishing, and enterprise content systems.
+**Problem.** Modern text—whether human-written, assisted, edited, or fully generated—often exhibits patterns that are difficult to evaluate using binary classifiers.
 
-**Solution.** A domain‑aware detector combining six orthogonal metrics (Perplexity, Entropy, Structural, Semantic, Linguistic, Multi-perturbation stability) into a confidence‑calibrated ensemble. Outputs are explainable with sentence‑level highlighting, attribution probabilities, and downloadable reports (JSON/PDF).
+**Solution.** A domain-aware analysis system combining six orthogonal evidence signals (Perplexity, Entropy, Structural, Semantic, Linguistic, Multi-perturbation stability) analysis into a confidence‑calibrated ensemble. Outputs are explainable with sentence‑level highlighting, and downloadable reports (JSON/PDF).
 
 **Live Deployment Link:** [AI Text Authenticator Platform](https://huggingface.co/spaces/satyaki-mitra/AI_Text_Authenticator)
 
@@ -75,16 +80,15 @@ This README is research‑grade (detailed math, methodology, and benchmarks) whi
 
 | Feature | Description | Impact |
 |---|---:|---|
-| **Domain‑Aware Detection** | Calibrated thresholds and metric weights for 16 content types (Academic, Technical, Creative, Social Media, etc.) | ↑15–20% accuracy vs generic detectors |
-| **6‑Metric Ensemble** | Orthogonal signals across statistical, syntactic and semantic dimensions | Low false positives (≈2–3%) |
+| **Domain‑Aware Detection** | Calibrated thresholds and metric weights for 16 content types (Academic, Technical, Creative, Social Media, etc.) | Improved signal calibration and reduced false positives compared to generic binary systems |
+| **6-Signal Evidence Ensemble** | Orthogonal statistical, syntactic, and semantic indicators | Robust assessments with reduced false positives |
 | **Explainability** | Sentence‑level scoring, highlights, and human‑readable reasoning | Trust & auditability |
-| **Model Attribution** | Likely model identification (GPT‑4, Claude, Gemini, LLaMA, etc.) | Forensic insights |
 | **Auto Model Fetch** | First‑run download from Hugging Face, local cache, offline fallback | Lightweight repo & reproducible runs |
 | **Extensible Design** | Plug‑in metrics, model registry, and retraining pipeline hooks | Easy research iteration |
 
 ### 📊 Supported Domains & Threshold Configuration
 
-The platform supports detection tailored to the following 16 domains, each with specific AI/Human probability thresholds and metric weights defined in `config/threshold_config.py`. These configurations are used by the ensemble classifier to adapt its decision-making process.
+The platform supports domain-aware forensic analysis tailored to the following 16 domains, each with specific synthetic-text consistency thresholds and metric weights defined in `config/threshold_config.py`. These configurations are used by the ensemble classifier to adapt its decision-making process.
 
 **Domains:**
 
@@ -109,8 +113,8 @@ The platform supports detection tailored to the following 16 domains, each with
 
 Each domain is configured with specific thresholds for the six detection metrics and an ensemble threshold. The weights determine the relative importance of each metric's output during the ensemble aggregation phase.
 
-*   **AI Threshold:** If a metric's AI probability exceeds this value, it leans towards an "AI" classification for that metric.
-*   **Human Threshold:** If a metric's AI probability falls below this value, it leans towards a "Human" classification for that metric.
+*   **High-Consistency Threshold:** If a metric's synthetic-consistency score exceeds this value, it contributes stronger evidence toward a synthetic-consistency assessment for that metric.
+*   **Low-Consistency Threshold:** If a metric's Authentic probability falls below this value, it contributes evidence toward higher human-authored consistency for that metric.
 *   **Weight:** The relative weight assigned to the metric's result during ensemble combination (normalized internally to sum to 1.0 for active metrics).
 
 ### Confidence-Calibrated Aggregation (High Level)
@@ -138,7 +142,7 @@ flowchart LR
         C[FastAPI<br/>Auth & Rate Limit]
     end
 
-    subgraph ORCH [Detection Orchestrator]
+    subgraph ORCH [Forensic Orchestrator]
         D[Domain Classifier]
         E[Preprocessor]
         F[Metric Coordinator]
@@ -153,9 +157,9 @@ flowchart LR
         P6[MultiPerturbationStability]
     end
 
-    G[Ensemble Classifier]
+    G[Evidence Aggregator]
     H[Postprocessing & Reporter]
-    I["Model Manager<br/>(HuggingFace Cache)"]
+    I["Statistical Reference Models<br/>(HuggingFace Cache)"]
     J[Storage: Logs, Reports, Cache]
 
     A --> C
@@ -190,7 +194,7 @@ sequenceDiagram
     O->>M: Preprocess & dispatch metrics (parallel)
     M-->>O: Metric results (async)
     O->>E: Aggregate & calibrate
-    E-->>O: Final verdict + uncertainty
+    E-->>O: Final assessment + uncertainty
     O->>R: Generate highlights & report
     R-->>API: Report ready (JSON/PDF)
     API-->>U: Return analysis + download link
@@ -198,9 +202,9 @@ sequenceDiagram
 
 ---
 
-## 🧮 Detection Metrics & Mathematical Foundation
+## 🧮 Forensic Signals & Mathematical Foundation
 
-This section provides the exact metric definitions implemented in `metrics/` and rationale for their selection. The ensemble combines these orthogonal signals to increase robustness against adversarial or edited AI content.
+This section provides the exact metric definitions implemented in `metrics/` and rationale for their selection. The ensemble combines these orthogonal signals to increase robustness against edited, paraphrased, or algorithmically regularized text.
 
 ### Metric summary (weights are configurable per domain)
 - Perplexity — 25%
@@ -356,9 +360,9 @@ def ensemble_aggregation(metric_results, domain):
 ### Uncertainty Quantification
 ```python
 def calculate_uncertainty(metric_results, ensemble_result):
-    var_uncert = np.var([r.ai_probability for r in metric_results.values()])
+    var_uncert = np.var([r.synthetic_probability for r in metric_results.values()])
     conf_uncert = 1 - np.mean([r.confidence for r in metric_results.values()])
-    decision_uncert = 1 - 2*abs(ensemble_result.ai_probability - 0.5)
+    decision_uncert = 1 - 2*abs(ensemble_result.synthetic_probability - 0.5)
     return var_uncert*0.4 + conf_uncert*0.3 + decision_uncert*0.3
 ```
 
@@ -369,17 +373,16 @@ def calculate_uncertainty(metric_results, ensemble_result):
 Domain weights and thresholds are configurable. Example weights (in `config/threshold_config.py`):
 
 ```python
-DOMAIN_WEIGHTS = {
-  'academic': {'perplexity':0.22,'entropy':0.18,'structural':0.15,'linguistic':0.20,'semantic':0.15,'multi_perturbation_stability':0.10},
-  'technical': {'perplexity':0.20,'entropy':0.18,'structural':0.12,'linguistic':0.18,'semantic':0.22,'multi_perturbation_stability':0.10},
-  'creative': {'perplexity':0.25,'entropy':0.25,'structural':0.20,'linguistic':0.12,'semantic':0.10,'multi_perturbation_stability':0.08},
-  'social_media': {'perplexity':0.30,'entropy':0.22,'structural':0.15,'linguistic':0.10,'semantic':0.13,'multi_perturbation_stability':0.10}
-}
+DOMAIN_WEIGHTS = {'academic'     : {'perplexity':0.22,'entropy':0.18,'structural':0.15,'linguistic':0.20,'semantic':0.15,'multi_perturbation_stability':0.10},
+                  'technical'    : {'perplexity':0.20,'entropy':0.18,'structural':0.12,'linguistic':0.18,'semantic':0.22,'multi_perturbation_stability':0.10},
+                  'creative'     : {'perplexity':0.25,'entropy':0.25,'structural':0.20,'linguistic':0.12,'semantic':0.10,'multi_perturbation_stability':0.08},
+                  'social_media' : {'perplexity':0.30,'entropy':0.22,'structural':0.15,'linguistic':0.10,'semantic':0.13,'multi_perturbation_stability':0.10},
+                 }
 ```
 
 ### Domain Calibration Strategy (brief)
 - **Academic**: increase linguistic weight, raise perplexity multiplier
-- **Technical**: prioritize semantic coherence, maximize AI threshold to reduce false positives
+- **Technical**: prioritize semantic coherence, maximize Synthetic threshold to reduce false positives
 - **Creative**: boost entropy & structural weights for burstiness detection
 - **Social Media**: prioritize perplexity and relax linguistic demands
 
@@ -409,13 +412,17 @@ text_auth/
 ├── config/
 │   ├── model_config.py
 │   ├── settings.py
+|   ├── enums.py
+|   ├── constants.py
+|   ├── schemas.py
 │   └── threshold_config.py
 ├── data/
 │   ├── reports/
+|   ├── validation_data/
 │   └── uploads/
-├── detector/
-│   ├── attribution.py
-│   ├── ensemble.py
+├── services/
+│   ├── reasoning_generator.py
+│   ├── ensemble_classifier.py
 │   ├── highlighter.py
 │   └── orchestrator.py
 ├── metrics/
@@ -435,15 +442,22 @@ text_auth/
 │   ├── language_detector.py
 │   └── text_processor.py
 ├── reporter/
-│   ├── reasoning_generator.py
 │   └── report_generator.py
 ├── ui/
 │   └── static/index.html
 ├── utils/
 │   └── logger.py
+├── validation/
 ├── example.py
 ├── requirements.txt
 ├── run.sh
+├── README.md
+├── Dockerfile
+├── .gitignore
+├── setup.sh
+├── test_integration.py
+├── .env.example
+├── requirements.txt
 └── text_auth_app.py
 ```
 
@@ -452,35 +466,41 @@ text_auth/
 ## 🌐 API Endpoints 
 
 ### `/api/analyze` — Text Analysis (POST)
-Analyze raw text. Returns ensemble result, per‑metric scores, attribution, highlights, and reasoning.
+Analyze raw text. Returns ensemble assessment, per‑metric signals, highlights, and explainability reasoning.
 
 **Request (JSON)**
 ```json
 {
   "text":"...",
   "domain":"academic|technical_doc|creative|social_media",
-  "enable_attribution": true,
   "enable_highlighting": true,
   "use_sentence_level": true,
-  "include_metrics_summary": true
-}
 ```
 
 **Response (JSON)** — abbreviated
 ```json
 {
-  "status":"success",
-  "analysis_id":"analysis_170...",
-  "detection_result":{
-    "ensemble_result":{ "final_verdict":"AI-Generated", "ai_probability":0.89, "uncertainty_score":0.23 },
-    "metric_results":{ "...": { "ai_probability":0.92, "confidence":0.89 } }
+  "status": "success",
+  "analysis_id": "analysis_170...",
+  "assessment": {
+    "final_verdict": "Synthetic / Authentic / Hybrid",
+    "overall_confidence": 0.89,
+    "uncertainty_score": 0.23
+  },
+  "metric_signals": {
+    "perplexity": { "score": 0.92, "confidence": 0.89 }
   },
-  "attribution":{ "predicted_model":"gpt-4", "confidence":0.76 },
-  "highlighted_html":"<div>...</div>",
-  "reasoning":{ "summary":"...", "key_indicators":[ "...", "..."] }
+  "highlighted_html": "<div>...</div>",
+  "reasoning": {
+    "summary": "...",
+    "key_indicators": ["...", "..."]
+  }
 }
 ```
 
+> **Note:** The final verdict represents a probabilistic consistency assessment, not an authorship or generation claim.
+
+
 ### `/api/analyze/file` — File Analysis (POST, multipart/form-data)
 Supports PDF, DOCX, TXT, DOC, MD. File size limit default: 10MB. Returns same structure as text analyze endpoint.
 
@@ -534,7 +554,7 @@ python text_auth_app.py
 **Example snippet**
 ```python
 from huggingface_hub import snapshot_download
-snapshot_download(repo_id="satyaki-mitra/text-detector-v1", local_dir="./models/text-detector-v1")
+snapshot_download(repo_id="satyaki-mitra/statistical-text-reference-v1", local_dir="./models/text-detector-v1")
 ```
 
 ---
@@ -556,7 +576,7 @@ snapshot_download(repo_id="satyaki-mitra/text-detector-v1", local_dir="./models/
 **Use cases**: universities (plagiarism & integrity), hiring platforms (resume authenticity), publishers (content verification), social platforms (spam & SEO abuse).
 
 **Competitive landscape** (summary)
-- GPTZero, Originality.ai, Copyleaks — our advantages: domain adaptation, explainability, attribution, lower false positives and competitive pricing.
+- Binary authorship-claim systems (e.g., GPTZero-style tools) — our advantages: domain adaptation, explainability, evidence transparency, lower false positives and competitive pricing. TEXT-AUTH explicitly avoids authorship claims in favor of evidence-based forensic assessment.
 
 **Monetization ideas**
 - SaaS subscription (seat / monthly analyze limits)
@@ -571,13 +591,11 @@ snapshot_download(repo_id="satyaki-mitra/text-detector-v1", local_dir="./models/
 **Research directions**
 - Adversarial robustness (paraphrase & synonym attacks)
 - Cross‑model generalization & zero‑shot detection
-- Fine‑grained attribution (model versioning, temperature estimation)
 - Explainability: counterfactual examples & feature importance visualization
 
 **Planned features (Q1‑Q2 2026)**
 - Multi‑language support (Spanish, French, German, Chinese)
 - Real‑time streaming API (WebSocket)
-- Fine‑grained attribution & generation parameter estimation
 - Institution‑specific calibration & admin dashboards
 
 *Detailed research methodology and academic foundation available in our [Whitepaper](docs/WHITE_PAPER.md). Technical implementation details in [Technical Documentation](docs/BLOGPOST.md).*
@@ -649,7 +667,7 @@ Acknowledgments:
 
 <div align="center">
 
-**Built with ❤️ — AI transparency, accountability, and real‑world readiness.**
+**Built with ❤️ — Evidence-based text forensics, transparency, and real-world readiness.**
 
 *Version 1.0.0 — Last Updated: October, 2025*
 

config/__init__.py

@@ -1,35 +0,0 @@
-# DEPENDENCIES
-from .settings import *
-from .model_config import *
-from .threshold_config import *
-
-
-# Export everything
-__all__ = ["ModelType", 
-           "ModelConfig", 
-           "MODEL_REGISTRY", 
-           "MODEL_GROUPS", 
-           "DEFAULT_MODEL_WEIGHTS", 
-           "get_model_config", 
-           "get_required_models",
-           "get_models_by_priority", 
-           "get_models_by_group", 
-           "get_total_size_mb",
-           "get_required_size_mb", 
-           "print_model_summary", 
-           "get_spacy_download_commands",
-           "settings",
-           "Settings",
-           "Domain",
-           "ConfidenceLevel",
-           "MetricThresholds", 
-           "DomainThresholds",
-           "DEFAULT_THRESHOLDS", 
-           "THRESHOLD_REGISTRY", 
-           "CONFIDENCE_RANGES",
-           "get_threshold_for_domain", 
-           "get_confidence_level", 
-           "adjust_threshold_by_confidence",
-           "interpolate_thresholds", 
-           "get_active_metric_weights",
-          ]

config/constants.py

@@ -0,0 +1,876 @@
+# DEPENDENCIES
+from typing import Dict
+from typing import List
+from typing import Tuple
+from dataclasses import field
+from config.enums import Script
+from dataclasses import dataclass
+
+
+@dataclass(frozen = True)
+class DocumentExtractionParams:
+    """
+    Hyperparameters for Document Extraction
+    """
+    # Supported file extensions
+    SUPPORTED_EXTENSIONS : frozenset = frozenset({'.txt', '.text', '.md', '.markdown', '.log', '.csv', '.pdf', '.docx', '.doc',  '.rtf', '.html', '.htm'})
+        
+    # Text file extensions
+    TEXT_EXTENSIONS      : frozenset = frozenset({'.txt', '.text', '.md', '.markdown', '.log', '.csv'})
+        
+    # Maximum file size (50 MB default)
+    MAX_FILE_SIZE        : int       = 50 * 1024 * 1024
+
+
+
+@dataclass(frozen = True)
+class LanguageDetectionParams:
+    """
+    Hyperparameters for Language Detection
+    """
+    # Text length constraints
+    MINIMUM_TEXT_LENGTH             : int                              = 20
+    
+    # Chunking parameters
+    MAX_CHUNK_LENGTH                : int                              = 500
+    MIN_CHUNK_LENGTH                : int                              = 50
+    FIXED_CHUNK_SIZE                : int                              = 1000
+    
+    # Model parameters
+    MODEL_MAX_LENGTH                : int                              = 512
+    TOP_K_PREDICTIONS               : int                              = 3
+    
+    # Confidence thresholds
+    LOW_CONFIDENCE_THRESHOLD        : float                            = 0.6
+    MULTILINGUAL_THRESHOLD          : float                            = 0.2
+    SCRIPT_DOMINANCE_THRESHOLD      : float                            = 0.7
+    LANGUAGE_MATCH_THRESHOLD        : float                            = 0.7
+    
+    # Quality assessment
+    WORD_BOUNDARY_RATIO             : float                            = 0.7
+    MIXED_DOMAIN_CONFIDENCE_PENALTY : float                            = 0.8
+    
+    # Language name mappings
+    LANGUAGE_NAMES                  : Dict[str, str]                   = field(default_factory = lambda : {"en": "English",
+                                                                                                           "es": "Spanish",
+                                                                                                           "fr": "French",
+                                                                                                           "de": "German",
+                                                                                                           "it": "Italian",
+                                                                                                           "pt": "Portuguese",
+                                                                                                           "ru": "Russian",
+                                                                                                           "zh": "Chinese",
+                                                                                                           "ja": "Japanese",
+                                                                                                           "ko": "Korean",
+                                                                                                           "ar": "Arabic",
+                                                                                                           "hi": "Hindi",
+                                                                                                          }
+                                                                              )
+    
+    # Unicode script ranges
+    SCRIPT_RANGES                   : Dict[str, List[Tuple[int, int]]] = field(default_factory = lambda: {"latin"      : [(0x0041, 0x007A), (0x00C0, 0x024F)],
+                                                                                                          "cyrillic"   : [(0x0400, 0x04FF)],
+                                                                                                          "arabic"     : [(0x0600, 0x06FF), (0x0750, 0x077F)],
+                                                                                                          "chinese"    : [(0x4E00, 0x9FFF), (0x3400, 0x4DBF)],
+                                                                                                          "japanese"   : [(0x3040, 0x309F), (0x30A0, 0x30FF)],
+                                                                                                          "korean"     : [(0xAC00, 0xD7AF), (0x1100, 0x11FF)],
+                                                                                                          "devanagari" : [(0x0900, 0x097F)],
+                                                                                                          "greek"      : [(0x0370, 0x03FF)],
+                                                                                                          "hebrew"     : [(0x0590, 0x05FF)],
+                                                                                                          "thai"       : [(0x0E00, 0x0E7F)],
+                                                                                                         }
+                                                                              )
+
+
+
+
+@dataclass(frozen = True)
+class TextProcessingParams:
+    """
+    Hyperparameters for Text Processing
+    """
+    # Text length constraints
+    MINIMUM_TEXT_LENGTH     : int    = 20
+    MAXIMUM_TEXT_LENGTH     : int    = 1000000  # 1M characters
+    
+    # Text cleaning options
+    PRESERVE_FORMATTING     : bool   = False
+    REMOVE_URLS             : bool   = True
+    REMOVE_EMAILS           : bool   = True
+    NORMALIZE_UNICODE       : bool   = True
+    FIX_ENCODING            : bool   = True
+    
+    # Validation thresholds
+    MINIMUM_WORD_COUNT      : int    = 10
+    
+    # Common abbreviations for sentence splitting
+    COMMON_ABBREVIATIONS    : list   = field(default_factory  = lambda: ["Mr.", "Mrs.", "Ms.", "Dr.", "Prof.", "Rev.", "Gen.", "Sen.", "Rep.", "St.", "Ave.", "Blvd.", "Rd.", "Pkwy.", "Co.", "Ltd.", "Inc.", "Corp.", 
+                                                                         "vs.", "etc.", "e.g.", "i.e.", "c.", "ca.", "cf.", "al.", "et al.", "Jan.", "Feb.", "Mar.", "Apr.", "Jun.", "Jul.", "Aug.", "Sep.", "Oct.", 
+                                                                         "Nov.", "Dec.", "Mon.", "Tue.", "Wed.", "Thu.", "Fri.", "Sat.", "Sun.", "kg.", "g.", "mg.", "km.", "m.", "cm.", "mm.", "hr.", "min.", "sec.", 
+                                                                         "vol.", "no.", "p.", "pp.", "ch.", "fig.", "ed.", "trans.", "approx.", "est.", "max.", "min.", "avg.", "std.", "temp.", "pres.", "vol.", "ibid.",
+                                                                         "op.", "cit.", "loc.", "cf.", "viz.", "sc.", "seq."
+                                                                        ]
+                                            )
+
+
+@dataclass(frozen = True)
+class DomainClassificationParams:
+    """
+    Hyperparameters for Domain Classification
+    """
+    # Classification parameters
+    TOP_K_DOMAINS                   : int                  = 2
+    MIN_CONFIDENCE_THRESHOLD        : float                = 0.3
+    
+    # Confidence thresholds
+    HIGH_CONFIDENCE_THRESHOLD       : float                = 0.7
+    MEDIUM_CONFIDENCE_THRESHOLD     : float                = 0.6
+    LOW_CONFIDENCE_THRESHOLD        : float                = 0.5
+    SECONDARY_DOMAIN_MIN_SCORE      : float                = 0.1
+    
+    # Mixed domain detection
+    MIXED_DOMAIN_PRIMARY_MAX        : float                = 0.7
+    MIXED_DOMAIN_SECONDARY_MIN      : float                = 0.3
+    MIXED_DOMAIN_RATIO_THRESHOLD    : float                = 0.6
+    MIXED_DOMAIN_CONFIDENCE_PENALTY : float                = 0.8
+    
+    # Text preprocessing
+    MAX_WORDS_FOR_CLASSIFICATION    : int                  = 400
+    
+    # Domain labels for zero-shot classification
+    DOMAIN_LABELS                   : Dict[str, List[str]] = field(default_factory = lambda : {"academic"      : ["academic paper", "research article", "scientific paper", "scholarly writing", "thesis", "dissertation", "academic research"],
+                                                                                               "creative"      : ["creative writing", "fiction", "story", "narrative", "poetry", "literary work", "imaginative writing"],
+                                                                                               "ai_ml"         : ["artificial intelligence", "machine learning", "neural networks", "data science", "AI research", "deep learning"],
+                                                                                               "software_dev"  : ["software development", "programming", "coding", "software engineering", "web development", "application development"],
+                                                                                               "technical_doc" : ["technical documentation", "user manual", "API documentation", "technical guide", "system documentation"],
+                                                                                               "engineering"   : ["engineering document", "technical design", "engineering analysis", "mechanical engineering", "electrical engineering"],
+                                                                                               "science"       : ["scientific research", "physics", "chemistry", "biology", "scientific study", "experimental results"],
+                                                                                               "business"      : ["business document", "corporate communication", "business report", "professional writing", "executive summary"],
+                                                                                               "journalism"    : ["news article", "journalism", "press release", "news report", "media content", "reporting"],
+                                                                                               "social_media"  : ["social media post", "casual writing", "online content", "informal text", "social media content"],
+                                                                                               "blog_personal" : ["personal blog", "personal writing", "lifestyle blog", "personal experience", "opinion piece", "diary entry"],
+                                                                                               "legal"         : ["legal document", "contract", "legal writing", "law", "legal agreement", "legal analysis"],
+                                                                                               "medical"       : ["medical document", "healthcare", "clinical", "medical report", "health information", "medical research"],
+                                                                                               "marketing"     : ["marketing content", "advertising", "brand content", "promotional writing", "sales copy", "marketing material"],
+                                                                                               "tutorial"      : ["tutorial", "how-to guide", "instructional content", "step-by-step guide", "educational guide", "learning material"],
+                                                                                               "general"       : ["general content", "everyday writing", "common text", "standard writing", "normal text", "general information"],
+                                                                                              }
+                                                                  )
+
+
+@dataclass(frozen = True)
+class BaseMetricParams:
+    """
+    Hyperparameters for BaseMetric class
+    """
+    DEFAULT_AUTHENTIC_PROBABILITY : float = 0.5
+    DEFAULT_SYNTHETIC_PROBABILITY : float = 0.5
+    DEFAULT_HYBRID_PROBABILITY    : float = 0.0
+    DEFAULT_CONFIDENCE            : float = 0.0
+
+
+@dataclass(frozen = True)
+class StructuralMetricParams:
+    """
+    Hyperparameters for Structural Metric
+    """
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB       : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB       : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT      : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START  : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START  : float = 0.7
+    UNCERTAIN_RANGE_WIDTH            : float = 0.4
+    NEUTRAL_PROBABILITY              : float = 0.5  # For fallback
+    MIN_PROBABILITY                  : float = 0.0
+    MAX_PROBABILITY                  : float = 1.0
+    
+    # Feature extraction - sentence splitting
+    SENTENCE_SPLIT_PATTERN           : str   = r'(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?|\!)\s'
+    WORD_TOKENIZE_PATTERN            : str   = r'\b\w+\b'
+    PUNCTUATION_PATTERN              : str   = r'[^\w\s]'
+    
+    # Burstiness calculation
+    BURSTINESS_NORMALIZATION_FACTOR  : float = 2.0
+    
+    # Readability calculation
+    FLESCH_CONSTANT_1                : float = 206.835
+    FLESCH_CONSTANT_2                : float = 1.015
+    FLESCH_CONSTANT_3                : float = 84.6
+    NEUTRAL_READABILITY_SCORE        : float = 50.0
+    MIN_READABILITY_SCORE            : float = 0.0
+    MAX_READABILITY_SCORE            : float = 100.0
+    
+    # Repetition detection
+    REPETITION_WINDOW_SIZE           : int   = 10
+    MIN_WORDS_FOR_REPETITION         : int   = 10
+    
+    # N-gram analysis
+    BIGRAM_N                         : int   = 2
+    TRIGRAM_N                        : int   = 3
+    
+    # Synthetic probability calculation thresholds
+    BURSTINESS_LOW_THRESHOLD         : float = 0.3
+    BURSTINESS_MEDIUM_THRESHOLD      : float = 0.5
+    LENGTH_UNIFORMITY_HIGH_THRESHOLD : float = 0.7
+    LENGTH_UNIFORMITY_MEDIUM_THRESH  : float = 0.5
+    BIGRAM_DIVERSITY_LOW_THRESHOLD   : float = 0.7
+    READABILITY_SYNTHETIC_MIN        : float = 60.0
+    READABILITY_SYNTHETIC_MAX        : float = 75.0
+    REPETITION_LOW_THRESHOLD         : float = 0.1
+    REPETITION_MEDIUM_THRESHOLD      : float = 0.2
+    
+    # Synthetic probability weights
+    STRONG_SYNTHETIC_WEIGHT          : float = 0.7
+    MODERATE_SYNTHETIC_WEIGHT        : float = 0.5
+    WEAK_SYNTHETIC_WEIGHT            : float = 0.3
+    VERY_WEAK_SYNTHETIC_WEIGHT       : float = 0.4
+    NEUTRAL_WEIGHT                   : float = 0.5
+    
+    # Confidence calculation
+    CONFIDENCE_STD_NORMALIZER        : float = 0.5
+    MIN_CONFIDENCE                   : float = 0.1
+    MAX_CONFIDENCE                   : float = 0.9
+    NEUTRAL_CONFIDENCE               : float = 0.5  # For fallback
+    
+    # Hybrid probability calculation
+    BURSTINESS_HIGH_THRESHOLD        : float = 0.6
+    SENTENCE_LENGTH_VARIANCE_RATIO   : float = 0.8
+    TYPE_TOKEN_RATIO_EXTREME_LOW     : float = 0.3
+    TYPE_TOKEN_RATIO_EXTREME_HIGH    : float = 0.9
+    READABILITY_EXTREME_LOW          : float = 20.0
+    READABILITY_EXTREME_HIGH         : float = 90.0
+    MODERATE_HYBRID_WEIGHT           : float = 0.4
+    WEAK_HYBRID_WEIGHT               : float = 0.3
+    MAX_HYBRID_PROBABILITY           : float = 0.3
+    
+    # Feature validation
+    MIN_SENTENCE_LENGTH_FOR_STD      : int   = 2
+    MIN_WORD_LENGTH_FOR_STD          : int   = 2
+    MIN_VALUES_FOR_BURSTINESS        : int   = 2
+    MIN_WORDS_FOR_NGRAM              : int   = 2  # For n-gram where n=2
+    
+    # Math and normalization
+    ZERO_TOLERANCE                   : float = 1e-10
+    ZERO_VALUE                       : float = 0.0
+    ONE_VALUE                        : float = 1.0
+
+
+@dataclass(frozen = True)
+class SemanticAnalysisParams:
+    """
+    Hyperparameters for Semantic Analysis Metric
+    """
+    # Text validation
+    MIN_TEXT_LENGTH_FOR_ANALYSIS        : int   = 50
+    MIN_SENTENCES_FOR_ANALYSIS          : int   = 3
+    MIN_SENTENCE_LENGTH                 : int   = 10
+    MIN_VALID_SENTENCE_LENGTH           : int   = 5
+    
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB          : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB          : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT         : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START     : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START     : float = 0.7
+    UNCERTAIN_RANGE_WIDTH               : float = 0.4
+    NEUTRAL_PROBABILITY                 : float = 0.5
+    MIN_PROBABILITY                     : float = 0.0
+    MAX_PROBABILITY                     : float = 1.0
+    
+    # Sentence splitting
+    SENTENCE_SPLIT_PATTERN              : str   = r'(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?|\!)\s'
+    WORD_EXTRACTION_PATTERN             : str   = r'\b[a-zA-Z]{4,}\b'
+    
+    # Coherence calculation
+    HIGH_COHERENCE_SIMILARITY           : float = 0.8
+    SIMILARITY_VARIANCE_FACTOR          : float = 5.0
+    
+    # Repetition detection
+    REPETITION_SIMILARITY_THRESHOLD     : float = 0.8
+    REPETITION_SCORE_SCALING            : float = 3.0
+    MIN_SENTENCES_FOR_REPETITION        : int   = 5
+    
+    # Topic drift calculation
+    START_SECTION_SIZE                  : int   = 3
+    END_SECTION_SIZE                    : int   = 3
+    SECTION_SIZE_RATIO                  : int   = 3  # denominator for section size calculation
+    
+    # Chunk analysis 
+    CHUNK_SIZE_WORDS                    : int   = 200
+    CHUNK_OVERLAP_RATIO                 : float = 0.5  # 50% overlap
+    MIN_CHUNK_LENGTH                    : int   = 50
+    MIN_SENTENCES_PER_CHUNK             : int   = 2
+    
+    # Keyword analysis
+    MIN_WORDS_FOR_KEYWORD_ANALYSIS      : int   = 10
+    TOP_KEYWORDS_COUNT                  : int   = 10
+    MIN_KEYWORD_FREQUENCY               : int   = 2
+    
+    # Synthetic probability thresholds
+    COHERENCE_HIGH_THRESHOLD            : float = 0.7
+    COHERENCE_MEDIUM_THRESHOLD          : float = 0.5
+    CONSISTENCY_HIGH_THRESHOLD          : float = 0.8
+    CONSISTENCY_MEDIUM_THRESHOLD        : float = 0.6
+    REPETITION_HIGH_THRESHOLD           : float = 0.3
+    REPETITION_MEDIUM_THRESHOLD         : float = 0.1
+    TOPIC_DRIFT_LOW_THRESHOLD           : float = 0.2
+    TOPIC_DRIFT_MEDIUM_THRESHOLD        : float = 0.4
+    COHERENCE_VARIANCE_LOW_THRESHOLD    : float = 0.05
+    COHERENCE_VARIANCE_MEDIUM_THRESHOLD : float = 0.1
+    
+    # Synthetic probability weights
+    STRONG_SYNTHETIC_WEIGHT             : float = 0.9
+    MODERATE_SYNTHETIC_WEIGHT           : float = 0.8
+    MEDIUM_SYNTHETIC_WEIGHT             : float = 0.6
+    WEAK_SYNTHETIC_WEIGHT               : float = 0.5
+    VERY_WEAK_SYNTHETIC_WEIGHT          : float = 0.4
+    VERY_LOW_SYNTHETIC_WEIGHT           : float = 0.3
+    LOW_SYNTHETIC_WEIGHT                : float = 0.2
+    
+    # Confidence calculation
+    CONFIDENCE_STD_NORMALIZER           : float = 0.5
+    MIN_CONFIDENCE                      : float = 0.1
+    MAX_CONFIDENCE                      : float = 0.9
+    NEUTRAL_CONFIDENCE                  : float = 0.5
+    LOW_FEATURE_CONFIDENCE              : float = 0.3
+    
+    # Hybrid probability calculation
+    COHERENCE_MIXED_MIN                 : float = 0.4
+    COHERENCE_MIXED_MAX                 : float = 0.6
+    COHERENCE_VARIANCE_HIGH_THRESHOLD   : float = 0.15
+    COHERENCE_VARIANCE_MEDIUM_THRESHOLD : float = 0.1
+    REPETITION_MIXED_MIN                : float = 0.15
+    REPETITION_MIXED_MAX                : float = 0.35
+    MODERATE_HYBRID_WEIGHT              : float = 0.4
+    WEAK_HYBRID_WEIGHT                  : float = 0.3
+    VERY_WEAK_HYBRID_WEIGHT             : float = 0.2
+    MAX_HYBRID_PROBABILITY              : float = 0.3
+    
+    # Default feature values
+    DEFAULT_COHERENCE                   : float = 0.5
+    DEFAULT_CONSISTENCY                 : float = 0.5
+    DEFAULT_REPETITION                  : float = 0.0
+    DEFAULT_TOPIC_DRIFT                 : float = 0.5
+    DEFAULT_CONTEXTUAL_CONSISTENCY      : float = 0.5
+    DEFAULT_CHUNK_COHERENCE             : float = 0.5
+    DEFAULT_COHERENCE_VARIANCE          : float = 0.1
+    
+    # Error handling
+    MIN_REQUIRED_FEATURES               : int   = 3
+    ZERO_TOLERANCE                      : float = 1e-10
+
+
+@dataclass(frozen = True)
+class LinguisticMetricParams:
+    """
+    Hyperparameters for Linguistic Metric
+    """
+    # Text validation
+    MIN_TEXT_LENGTH_FOR_ANALYSIS             : int   = 50
+    
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB               : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB               : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT              : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START          : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START          : float = 0.7
+    UNCERTAIN_RANGE_WIDTH                    : float = 0.4
+    NEUTRAL_PROBABILITY                      : float = 0.5
+    MIN_PROBABILITY                          : float = 0.0
+    MAX_PROBABILITY                          : float = 1.0
+    
+    # POS analysis
+    MIN_TAGS_FOR_ENTROPY                     : int   = 1
+    
+    # Syntactic complexity
+    COMPLEXITY_WEIGHT_AVG                    : float = 0.5
+    COMPLEXITY_WEIGHT_MAX                    : float = 0.5
+    
+    # Sentence complexity
+    WORDS_PER_COMPLEXITY_UNIT                : float = 10.0
+    CLAUSE_COMPLEXITY_FACTOR                 : float = 0.5
+    
+    # Grammatical patterns
+    TRANSITION_WORDS_SET                     : tuple = ('however', 'therefore', 'moreover', 'furthermore', 'consequently', 'additionally', 'nevertheless', 'nonetheless', 'thus', 'hence')
+    IDEAL_PASSIVE_RATIO                      : float = 0.3
+    IDEAL_TRANSITION_RATIO                   : float = 0.2
+    PASSIVE_DEPENDENCY                       : str   = 'nsubjpass'
+    CLAUSE_MARKERS                           : tuple = ('cc', 'mark')
+    
+    # Writing style analysis
+    IDEAL_LENGTH_VARIATION                   : float = 0.5
+    IDEAL_PUNCTUATION_RATIO                  : float = 0.1
+    
+    # SYNTHETIC pattern detection
+    TRANSITION_OVERUSE_THRESHOLD             : float = 0.05
+    POS_SEQUENCE_FREQ_THRESHOLD              : float = 0.1
+    STRUCTURE_DIVERSITY_THRESHOLD            : float = 0.5
+    UNUSUAL_CONSTRUCTION_THRESHOLD           : float = 0.02
+    REPETITIVE_PHRASING_THRESHOLD            : float = 0.3
+    UNUSUAL_DEPENDENCIES                     : tuple = ('attr', 'oprd')
+    
+    # Chunk analysis
+    CHUNK_SIZE_WORDS                         : int   = 200
+    CHUNK_OVERLAP_RATIO                      : float = 0.5
+    MIN_CHUNK_LENGTH                         : int   = 50
+    MIN_SENTENCES_FOR_STRUCTURE              : int   = 3
+    MIN_SENTENCES_FOR_ANALYSIS               : int   = 1
+    
+    # Synthetic probability thresholds
+    POS_DIVERSITY_LOW_THRESHOLD              : float = 0.3
+    POS_DIVERSITY_MEDIUM_THRESHOLD           : float = 0.5
+    SYNTACTIC_COMPLEXITY_LOW_THRESHOLD       : float = 2.0
+    SYNTACTIC_COMPLEXITY_MEDIUM_THRESHOLD    : float = 3.0
+    GRAMMATICAL_CONSISTENCY_HIGH_THRESHOLD   : float = 0.8
+    GRAMMATICAL_CONSISTENCY_MEDIUM_THRESHOLD : float = 0.6
+    TRANSITION_USAGE_HIGH_THRESHOLD          : float = 0.3
+    TRANSITION_USAGE_MEDIUM_THRESHOLD        : float = 0.15
+    SYNTHETIC_PATTERN_HIGH_THRESHOLD         : float = 0.6
+    SYNTHETIC_PATTERN_MEDIUM_THRESHOLD       : float = 0.3
+    COMPLEXITY_VARIANCE_LOW_THRESHOLD        : float = 0.1
+    COMPLEXITY_VARIANCE_MEDIUM_THRESHOLD     : float = 0.3
+    
+    # Synthetic probability weights
+    STRONG_SYNTHETIC_WEIGHT                  : float = 0.9
+    MODERATE_SYNTHETIC_WEIGHT                : float = 0.8
+    MEDIUM_SYNTHETIC_WEIGHT                  : float = 0.7
+    WEAK_SYNTHETIC_WEIGHT                    : float = 0.6
+    VERY_WEAK_SYNTHETIC_WEIGHT               : float = 0.5
+    LOW_SYNTHETIC_WEIGHT                     : float = 0.4
+    VERY_LOW_SYNTHETIC_WEIGHT                : float = 0.3
+    MINIMAL_SYNTHETIC_WEIGHT                 : float = 0.2
+    
+    # Confidence calculation
+    CONFIDENCE_STD_NORMALIZER                : float = 0.5
+    MIN_CONFIDENCE                           : float = 0.1
+    MAX_CONFIDENCE                           : float = 0.9
+    NEUTRAL_CONFIDENCE                       : float = 0.5
+    LOW_FEATURE_CONFIDENCE                   : float = 0.3
+    MIN_REQUIRED_FEATURES                    : int   = 4
+    
+    # Hybrid probability calculation
+    POS_DIVERSITY_MIXED_MIN                  : float = 0.35
+    POS_DIVERSITY_MIXED_MAX                  : float = 0.55
+    POS_ENTROPY_LOW_THRESHOLD                : float = 0.35
+    POS_ENTROPY_HIGH_THRESHOLD               : float = 0.65
+    COMPLEXITY_VARIANCE_HIGH_THRESHOLD       : float = 0.5
+    COMPLEXITY_VARIANCE_MEDIUM_THRESHOLD     : float = 0.3
+    SYNTHETIC_PATTERN_MIXED_MIN              : float = 0.2
+    SYNTHETIC_PATTERN_MIXED_MAX              : float = 0.6
+    MODERATE_HYBRID_WEIGHT                   : float = 0.4
+    WEAK_HYBRID_WEIGHT                       : float = 0.3
+    MINIMAL_HYBRID_WEIGHT                    : float = 0.2
+    MAX_HYBRID_PROBABILITY                   : float = 0.3
+    
+    # Default feature values
+    DEFAULT_POS_DIVERSITY                    : float = 0.5
+    DEFAULT_POS_ENTROPY                      : float = 2.5
+    DEFAULT_SYNTACTIC_COMPLEXITY             : float = 2.5
+    DEFAULT_SENTENCE_COMPLEXITY              : float = 2.0
+    DEFAULT_GRAMMATICAL_CONSISTENCY          : float = 0.5
+    DEFAULT_TRANSITION_USAGE                 : float = 0.1
+    DEFAULT_PASSIVE_RATIO                    : float = 0.2
+    DEFAULT_WRITING_STYLE_SCORE              : float = 0.5
+    DEFAULT_SYNTHETIC_PATTERN_SCORE          : float = 0.3
+    DEFAULT_CHUNK_COMPLEXITY                 : float = 2.5
+    DEFAULT_COMPLEXITY_VARIANCE              : float = 0.2
+    
+    # Math and normalization
+    LOG_BASE                                 : int   = 2
+    ZERO_TOLERANCE                           : float = 1e-10
+
+
+@dataclass(frozen = True)
+class PerplexityMetricParams:
+    """
+    Hyperparameters for Perplexity Metric
+    """
+    # Text validation
+    MIN_TEXT_LENGTH_FOR_ANALYSIS             : int   = 50
+    
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB               : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB               : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT              : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START          : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START          : float = 0.7
+    UNCERTAIN_RANGE_WIDTH                    : float = 0.4
+    NEUTRAL_PROBABILITY                      : float = 0.5
+    MIN_PROBABILITY                          : float = 0.0
+    MAX_PROBABILITY                          : float = 1.0
+    
+    # Model parameters
+    MAX_TOKEN_LENGTH                         : int   = 1024
+    MIN_TOKENS_FOR_PERPLEXITY                : int   = 5
+    MIN_SENTENCE_LENGTH                      : int   = 20
+    MIN_CHUNK_LENGTH                         : int   = 50
+    
+    # Chunk analysis
+    CHUNK_SIZE_WORDS                         : int   = 200
+    CHUNK_OVERLAP_RATIO                      : float = 0.5
+    
+    # Perplexity normalization
+    PERPLEXITY_SIGMOID_CENTER                : float = 30.0
+    PERPLEXITY_SIGMOID_SCALE                 : float = 10.0
+    
+    # Cross-entropy normalization
+    MAX_CROSS_ENTROPY                        : float = 5.0
+    
+    # Perplexity value thresholds (actual perplexity values)
+    PERPLEXITY_VERY_LOW_THRESHOLD            : float = 20.0
+    PERPLEXITY_LOW_THRESHOLD                 : float = 40.0
+    PERPLEXITY_HIGH_THRESHOLD                : float = 80.0
+    PERPLEXITY_VERY_HIGH_THRESHOLD           : float = 150.0
+    
+    # Synthetic probability thresholds (normalized values 0-1)
+    NORMALIZED_PERPLEXITY_HIGH_THRESHOLD     : float = 0.7
+    NORMALIZED_PERPLEXITY_MEDIUM_THRESHOLD   : float = 0.5
+    PERPLEXITY_VARIANCE_LOW_THRESHOLD        : float = 50.0
+    PERPLEXITY_VARIANCE_MEDIUM_THRESHOLD     : float = 200.0
+    STD_SENTENCE_PERPLEXITY_LOW_THRESHOLD    : float = 20.0
+    STD_SENTENCE_PERPLEXITY_MEDIUM_THRESHOLD : float = 50.0
+    CROSS_ENTROPY_LOW_THRESHOLD              : float = 0.3
+    CROSS_ENTROPY_MEDIUM_THRESHOLD           : float = 0.6
+    CHUNK_VARIANCE_VERY_LOW_THRESHOLD        : float = 25.0
+    CHUNK_VARIANCE_LOW_THRESHOLD             : float = 100.0
+    
+    # Synthetic probability weights
+    STRONG_SYNTHETIC_WEIGHT                  : float = 0.8
+    MEDIUM_SYNTHETIC_WEIGHT                  : float = 0.6
+    WEAK_SYNTHETIC_WEIGHT                    : float = 0.4
+    VERY_WEAK_SYNTHETIC_WEIGHT               : float = 0.2
+    VERY_LOW_SYNTHETIC_WEIGHT                : float = 0.3
+    MINIMAL_SYNTHETIC_WEIGHT                 : float = 0.2
+    
+    # Confidence calculation
+    CONFIDENCE_STD_NORMALIZER                : float = 0.5
+    MIN_CONFIDENCE                           : float = 0.1
+    MAX_CONFIDENCE                           : float = 0.9
+    NEUTRAL_CONFIDENCE                       : float = 0.5
+    LOW_FEATURE_CONFIDENCE                   : float = 0.3
+    MIN_REQUIRED_FEATURES                    : int   = 3
+    
+    # Hybrid probability calculation
+    NORMALIZED_PERPLEXITY_MIXED_MIN          : float = 0.4
+    NORMALIZED_PERPLEXITY_MIXED_MAX          : float = 0.6
+    PERPLEXITY_VARIANCE_HIGH_THRESHOLD       : float = 200.0
+    PERPLEXITY_VARIANCE_MEDIUM_THRESHOLD     : float = 100.0
+    STD_SENTENCE_PERPLEXITY_MIXED_MIN        : float = 20.0
+    STD_SENTENCE_PERPLEXITY_MIXED_MAX        : float = 60.0
+    MODERATE_HYBRID_WEIGHT                   : float = 0.4
+    WEAK_HYBRID_WEIGHT                       : float = 0.2
+    MINIMAL_HYBRID_WEIGHT                    : float = 0.0
+    MAX_HYBRID_PROBABILITY                   : float = 0.3
+    
+    # Default feature values
+    DEFAULT_OVERALL_PERPLEXITY               : float = 50.0
+    DEFAULT_NORMALIZED_PERPLEXITY            : float = 0.5
+    DEFAULT_AVG_SENTENCE_PERPLEXITY          : float = 50.0
+    DEFAULT_STD_SENTENCE_PERPLEXITY          : float = 25.0
+    DEFAULT_MIN_SENTENCE_PERPLEXITY          : float = 30.0
+    DEFAULT_MAX_SENTENCE_PERPLEXITY          : float = 70.0
+    DEFAULT_PERPLEXITY_VARIANCE              : float = 100.0
+    DEFAULT_AVG_CHUNK_PERPLEXITY             : float = 50.0
+    DEFAULT_CROSS_ENTROPY_SCORE              : float = 0.5
+    
+    # Math and normalization
+    ZERO_TOLERANCE                           : float = 1e-10
+    LARGE_PERPLEXITY_THRESHOLD               : float = 1000.0
+
+    # Regular experssion for sentence splitting
+    SENTENCE_SPLIT_PATTERN                   : str   = r'(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?|\!)\s'
+    
+
+@dataclass(frozen = True)
+class EntropyMetricParams:
+    """
+    Hyperparameters for Entropy Metric
+    """
+    # Text validation
+    MIN_TEXT_LENGTH_FOR_ANALYSIS               : int   = 50
+    MIN_SENTENCE_LENGTH                        : int   = 10
+    MIN_WORDS_FOR_ANALYSIS                     : int   = 5
+    MIN_TOKENS_FOR_ANALYSIS                    : int   = 10
+    MIN_TOKENS_FOR_SEQUENCE                    : int   = 20
+    
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB                 : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB                 : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT                : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START            : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START            : float = 0.7
+    UNCERTAIN_RANGE_WIDTH                      : float = 0.4
+    NEUTRAL_PROBABILITY                        : float = 0.5
+    MIN_PROBABILITY                            : float = 0.0
+    MAX_PROBABILITY                            : float = 1.0
+    
+    # Chunk analysis
+    CHUNK_SIZE_WORDS                           : int   = 100
+    CHUNK_OVERLAP_RATIO                        : float = 0.5
+    MIN_CHUNK_LENGTH                           : int   = 20
+    
+    # Sequence analysis
+    MAX_BIGRAM_ENTROPY                         : float = 8.0
+    
+    # Entropy normalization
+    MAX_CHAR_ENTROPY                           : float = 4.0
+    
+    # Synthetic probability thresholds
+    CHAR_ENTROPY_VERY_LOW_THRESHOLD            : float = 3.5
+    CHAR_ENTROPY_LOW_THRESHOLD                 : float = 3.8
+    CHAR_ENTROPY_MEDIUM_THRESHOLD              : float = 4.0
+    ENTROPY_VARIANCE_VERY_LOW_THRESHOLD        : float = 0.1
+    ENTROPY_VARIANCE_LOW_THRESHOLD             : float = 0.2
+    ENTROPY_VARIANCE_MEDIUM_THRESHOLD          : float = 0.3
+    TOKEN_DIVERSITY_LOW_THRESHOLD              : float = 0.6
+    TOKEN_DIVERSITY_MEDIUM_THRESHOLD           : float = 0.7
+    TOKEN_DIVERSITY_HIGH_THRESHOLD             : float = 0.8
+    SEQUENCE_UNPREDICTABILITY_LOW_THRESHOLD    : float = 0.3
+    SEQUENCE_UNPREDICTABILITY_MEDIUM_THRESHOLD : float = 0.4
+    SEQUENCE_UNPREDICTABILITY_HIGH_THRESHOLD   : float = 0.5
+    SYNTHETIC_PATTERN_SCORE_HIGH_THRESHOLD     : float = 0.75
+    SYNTHETIC_PATTERN_SCORE_MEDIUM_THRESHOLD   : float = 0.5
+    TOKEN_ENTROPY_LOW_THRESHOLD                : float = 6.5
+    
+    # Synthetic probability weights
+    STRONG_SYNTHETIC_WEIGHT                    : float = 0.9
+    VERY_STRONG_SYNTHETIC_WEIGHT               : float = 0.8
+    MEDIUM_SYNTHETIC_WEIGHT                    : float = 0.7
+    MODERATE_SYNTHETIC_WEIGHT                  : float = 0.6
+    WEAK_SYNTHETIC_WEIGHT                      : float = 0.5
+    VERY_WEAK_SYNTHETIC_WEIGHT                 : float = 0.4
+    LOW_SYNTHETIC_WEIGHT                       : float = 0.3
+    MINIMAL_SYNTHETIC_WEIGHT                   : float = 0.2
+    VERY_LOW_SYNTHETIC_WEIGHT                  : float = 0.1
+    
+    # Confidence calculation
+    CONFIDENCE_STD_NORMALIZER                  : float = 0.5
+    MIN_CONFIDENCE                             : float = 0.1
+    MAX_CONFIDENCE                             : float = 0.9
+    NEUTRAL_CONFIDENCE                         : float = 0.5
+    LOW_FEATURE_CONFIDENCE                     : float = 0.3
+    MIN_REQUIRED_FEATURES                      : int   = 2
+    
+    # Hybrid probability calculation
+    ENTROPY_VARIANCE_HIGH_THRESHOLD            : float = 0.5
+    ENTROPY_VARIANCE_MIXED_THRESHOLD           : float = 0.3
+    ENTROPY_DISCREPANCY_THRESHOLD              : float = 1.0
+    SYNTHETIC_PATTERN_MIXED_MIN                : float = 0.4
+    SYNTHETIC_PATTERN_MIXED_MAX                : float = 0.6
+    STRONG_HYBRID_WEIGHT                       : float = 0.6
+    MODERATE_HYBRID_WEIGHT                     : float = 0.4
+    WEAK_HYBRID_WEIGHT                         : float = 0.3
+    MINIMAL_HYBRID_WEIGHT                      : float = 0.0
+    MAX_HYBRID_PROBABILITY                     : float = 0.4
+      
+    # Default feature values
+    DEFAULT_CHAR_ENTROPY                       : float = 3.8
+    DEFAULT_WORD_ENTROPY                       : float = 6.0
+    DEFAULT_TOKEN_ENTROPY                      : float = 8.0
+    DEFAULT_TOKEN_DIVERSITY                    : float = 0.7
+    DEFAULT_SEQUENCE_UNPREDICTABILITY          : float = 0.5
+    DEFAULT_ENTROPY_VARIANCE                   : float = 0.2
+    DEFAULT_AVG_CHUNK_ENTROPY                  : float = 3.8
+    DEFAULT_PREDICTABILITY_SCORE               : float = 0.5
+    
+    # Math and normalization
+    ZERO_TOLERANCE                             : float = 1e-10
+
+
+@dataclass(frozen = True)
+class MultiPerturbationStabilityMetricParams:
+    """
+    Hyperparameters for Multi-Perturbation Stability Metric
+    """
+    # Text validation
+    MIN_TEXT_LENGTH_FOR_ANALYSIS        : int   = 50
+    MIN_TEXT_LENGTH_FOR_PERTURBATION    : int   = 10
+    MIN_TOKENS_FOR_LIKELIHOOD           : int   = 3
+    MIN_WORDS_FOR_PERTURBATION          : int   = 3
+    MIN_WORDS_FOR_DELETION              : int   = 5
+    
+    # Domain threshold application - PROBABILITY CONSTANTS
+    STRONG_SYNTHETIC_BASE_PROB          : float = 0.7
+    STRONG_AUTHENTIC_BASE_PROB          : float = 0.7
+    WEAK_PROBABILITY_ADJUSTMENT         : float = 0.3
+    UNCERTAIN_SYNTHETIC_RANGE_START     : float = 0.3
+    UNCERTAIN_AUTHENTIC_RANGE_START     : float = 0.7
+    UNCERTAIN_RANGE_WIDTH               : float = 0.4
+    NEUTRAL_PROBABILITY                 : float = 0.5
+    MIN_PROBABILITY                     : float = 0.0
+    MAX_PROBABILITY                     : float = 1.0
+    
+    # Perturbation parameters
+    NUM_PERTURBATIONS                   : int   = 10
+    MAX_PERTURBATION_ATTEMPTS           : int   = 10
+    PERTURBATION_DELETION_RATIO         : float = 0.1
+    ROBBERTA_TOP_K_PREDICTIONS          : int   = 3
+    
+    # Text preprocessing
+    MAX_TEXT_LENGTH_FOR_ANALYSIS        : int   = 2000
+    MAX_TEXT_LENGTH_FOR_PERTURBATION    : int   = 1000
+    MAX_TOKEN_LENGTH                    : int   = 256
+    MAX_ROBERTA_TOKEN_LENGTH            : int   = 128
+    
+    # Chunk analysis
+    CHUNK_SIZE_WORDS                    : int   = 150
+    CHUNK_OVERLAP_RATIO                 : float = 0.5
+    MIN_CHUNK_LENGTH                    : int   = 50
+    CHUNK_DELETION_RATIO                : float = 0.1
+    
+    # Likelihood calculation
+    MIN_VALID_PERTURBATIONS             : int   = 3
+    DEFAULT_LIKELIHOOD                  : float = 2.0
+    MIN_LIKELIHOOD                      : float = 0.5
+    MAX_LIKELIHOOD                      : float = 10.0
+    
+    # Stability scoring
+    STABILITY_HIGH_THRESHOLD            : float = 0.7
+    STABILITY_MEDIUM_THRESHOLD          : float = 0.5
+    STABILITY_LOW_THRESHOLD             : float = 0.3
+    RELATIVE_DROP_HIGH_THRESHOLD        : float = 0.5
+    RELATIVE_DROP_MEDIUM_THRESHOLD      : float = 0.3
+    RELATIVE_DROP_LOW_THRESHOLD         : float = 0.15
+    
+    # Curvature scoring
+    CURVATURE_HIGH_THRESHOLD            : float = 0.7
+    CURVATURE_MEDIUM_THRESHOLD          : float = 0.5
+    CURVATURE_LOW_THRESHOLD             : float = 0.3
+    CURVATURE_SCALING_FACTOR            : float = 3.0
+    
+    # Likelihood ratio thresholds
+    LIKELIHOOD_RATIO_HIGH_THRESHOLD     : float = 0.8
+    LIKELIHOOD_RATIO_MEDIUM_THRESHOLD   : float = 0.6
+    LIKELIHOOD_RATIO_LOW_THRESHOLD      : float = 0.4
+    MAX_LIKELIHOOD_RATIO                : float = 3.0
+    MIN_LIKELIHOOD_RATIO                : float = 0.33
+    
+    # Stability variance thresholds
+    STABILITY_VARIANCE_VERY_LOW         : float = 0.05
+    STABILITY_VARIANCE_LOW              : float = 0.1
+    STABILITY_VARIANCE_HIGH             : float = 0.15
+    
+    # Synthetic probability weights
+    STABILITY_WEIGHT                    : float = 0.3
+    CURVATURE_WEIGHT                    : float = 0.25
+    RATIO_WEIGHT                        : float = 0.25
+    VARIANCE_WEIGHT                     : float = 0.2
+    
+    # Synthetic probability thresholds
+    STABILITY_STRONG_THRESHOLD          : float = 0.9
+    STABILITY_MEDIUM_STRONG_THRESHOLD   : float = 0.7
+    STABILITY_MODERATE_THRESHOLD        : float = 0.5
+    STABILITY_WEAK_THRESHOLD            : float = 0.2
+    CURVATURE_STRONG_THRESHOLD          : float = 0.8
+    CURVATURE_MEDIUM_THRESHOLD          : float = 0.6
+    CURVATURE_MODERATE_THRESHOLD        : float = 0.4
+    CURVATURE_WEAK_THRESHOLD            : float = 0.2
+    RATIO_STRONG_THRESHOLD              : float = 0.9
+    RATIO_MEDIUM_THRESHOLD              : float = 0.7
+    RATIO_MODERATE_THRESHOLD            : float = 0.5
+    RATIO_WEAK_THRESHOLD                : float = 0.3
+    VARIANCE_STRONG_THRESHOLD           : float = 0.8
+    VARIANCE_MODERATE_THRESHOLD         : float = 0.5
+    VARIANCE_WEAK_THRESHOLD             : float = 0.2
+    
+    # Confidence calculation
+    CONFIDENCE_BASE                     : float = 0.5
+    CONFIDENCE_STD_FACTOR               : float = 0.5
+    MIN_CONFIDENCE                      : float = 0.1
+    MAX_CONFIDENCE                      : float = 0.9
+    NEUTRAL_CONFIDENCE                  : float = 0.5
+    LOW_FEATURE_CONFIDENCE              : float = 0.3
+    MIN_REQUIRED_FEATURES               : int   = 3
+    
+    # Hybrid probability calculation
+    STABILITY_MIXED_MIN                 : float = 0.35
+    STABILITY_MIXED_MAX                 : float = 0.55
+    STABILITY_VARIANCE_MIXED_HIGH       : float = 0.15
+    STABILITY_VARIANCE_MIXED_MEDIUM     : float = 0.1
+    LIKELIHOOD_RATIO_MIXED_MIN          : float = 0.5
+    LIKELIHOOD_RATIO_MIXED_MAX          : float = 0.8
+    MODERATE_HYBRID_WEIGHT              : float = 0.4
+    WEAK_HYBRID_WEIGHT                  : float = 0.3
+    VERY_WEAK_HYBRID_WEIGHT             : float = 0.2
+    MINIMAL_HYBRID_WEIGHT               : float = 0.0
+    MAX_HYBRID_PROBABILITY              : float = 0.3
+    
+    # Default feature values
+    DEFAULT_ORIGINAL_LIKELIHOOD         : float = 2.0
+    DEFAULT_AVG_PERTURBED_LIKELIHOOD    : float = 1.8
+    DEFAULT_LIKELIHOOD_RATIO            : float = 1.1
+    DEFAULT_NORMALIZED_LIKELIHOOD_RATIO : float = 0.55
+    DEFAULT_STABILITY_SCORE             : float = 0.3
+    DEFAULT_CURVATURE_SCORE             : float = 0.3
+    DEFAULT_PERTURBATION_VARIANCE       : float = 0.05
+    DEFAULT_AVG_CHUNK_STABILITY         : float = 0.3
+    DEFAULT_STABILITY_VARIANCE          : float = 0.1
+    
+    # Math and normalization
+    ZERO_TOLERANCE                      : float = 1e-10
+    
+    # Common words to avoid masking
+    COMMON_WORDS_TO_AVOID               : tuple = ('the', 'and', 'but', 'for', 'with', 'that', 'this', 'have', 'from', 'were')
+    
+
+@dataclass(frozen = True)
+class MetricsEnsembleParams:
+    """
+    Constants for MEtrics Ensemble Classifier
+    """
+    # Minimum requirements 
+    MIN_METRICS_REQUIRED             : int   = 3
+
+    # Default probabilities
+    DEFAULT_SYNTHETIC_PROB           : float = 0.5
+    DEFAULT_AUTHENTIC_PROB           : float = 0.5
+    DEFAULT_HYBRID_PROB              : float = 0.0
+
+    # Weighting
+    SIGMOID_CONFIDENCE_SCALE         : float = 10.0
+    SIGMOID_CENTER                   : float = 0.5
+
+    # Confidence composition
+    CONFIDENCE_WEIGHT_BASE           : float = 0.4
+    CONFIDENCE_WEIGHT_AGREEMENT      : float = 0.3
+    CONFIDENCE_WEIGHT_CERTAINTY      : float = 0.2
+    CONFIDENCE_WEIGHT_QUALITY        : float = 0.1
+
+    # Uncertainty composition
+    UNCERTAINTY_WEIGHT_VARIANCE      : float = 0.4
+    UNCERTAINTY_WEIGHT_CONFIDENCE    : float = 0.3
+    UNCERTAINTY_WEIGHT_DECISION      : float = 0.3
+
+    # Consensus 
+    CONSENSUS_STD_SCALING            : float = 2.0
+
+    # Hybrid detection 
+    HYBRID_PROB_THRESHOLD            : float = 0.25
+    HYBRID_UNCERTAINTY_THRESHOLD     : float = 0.6
+    HYBRID_SYNTHETIC_RANGE_LOW       : float = 0.3
+    HYBRID_SYNTHETIC_RANGE_HIGH      : float = 0.7
+
+    # Threshold adaptation 
+    UNCERTAINTY_THRESHOLD_ADJUSTMENT : float = 0.1
+
+    # Contribution labels
+    CONTRIBUTION_HIGH                : float = 0.15
+    CONTRIBUTION_MEDIUM              : float = 0.08
+
+    HIGH_CONFIDENCE_THRESHOLD        : float = 0.7
+
+
+
+# Singleton instances for parameter classes
+document_extraction_params                 = DocumentExtractionParams()
+language_detection_params                  = LanguageDetectionParams()
+domain_classification_params               = DomainClassificationParams()
+text_processing_params                     = TextProcessingParams()
+base_metric_params                         = BaseMetricParams()
+structural_metric_params                   = StructuralMetricParams()
+semantic_analysis_params                   = SemanticAnalysisParams()
+linguistic_metric_params                   = LinguisticMetricParams()
+perplexity_metric_params                   = PerplexityMetricParams()
+entropy_metric_params                      = EntropyMetricParams()
+multi_perturbation_stability_metric_params = MultiPerturbationStabilityMetricParams()
+metrics_ensemble_params                    = MetricsEnsembleParams()

config/enums.py

@@ -0,0 +1,106 @@
+# DEPENDENCIES
+from enum import Enum
+
+
+
+class ModelType(Enum):
+    """
+    Model types for categorization
+    """
+    TRANSFORMER             = "transformer"
+    SENTENCE_TRANSFORMER    = "sentence_transformer"
+    LANGUAGE_MODEL          = "language_model"
+    MASKED_LANGUAGE_MODEL   = "masked_language_model"
+    CLASSIFIER              = "classifier"
+    EMBEDDING               = "embedding"
+    RULE_BASED              = "rule_based"
+    SEQUENCE_CLASSIFICATION = "sequence_classification"  
+    CAUSAL_LM               = "causal_lm"        
+    MASKED_LM               = "masked_lm" 
+
+
+class Domain(Enum):
+    """
+    Text domains for adaptive thresholding
+    """
+    # Core domains
+    GENERAL         = "general"
+    ACADEMIC        = "academic"
+    CREATIVE        = "creative"
+    AI_ML           = "ai_ml"        # domain topic, not authorship        
+    SOFTWARE_DEV    = "software_dev"       
+    TECHNICAL_DOC   = "technical_doc"      
+    ENGINEERING     = "engineering"   
+    SCIENCE         = "science"     
+    BUSINESS        = "business"
+    LEGAL           = "legal"
+    MEDICAL         = "medical"
+    JOURNALISM      = "journalism"
+    MARKETING       = "marketing"
+    SOCIAL_MEDIA    = "social_media"
+    BLOG_PERSONAL   = "blog_personal"   
+    TUTORIAL        = "tutorial"      
+
+
+
+class Language(Enum):
+    """
+    ISO 639-1 language codes for supported languages
+    """
+    ENGLISH    = "en"
+    SPANISH    = "es"
+    FRENCH     = "fr"
+    GERMAN     = "de"
+    ITALIAN    = "it"
+    PORTUGUESE = "pt"
+    RUSSIAN    = "ru"
+    CHINESE    = "zh"
+    JAPANESE   = "ja"
+    KOREAN     = "ko"
+    ARABIC     = "ar"
+    HINDI      = "hi"
+    DUTCH      = "nl"
+    POLISH     = "pl"
+    TURKISH    = "tr"
+    SWEDISH    = "sv"
+    VIETNAMESE = "vi"
+    INDONESIAN = "id"
+    THAI       = "th"
+    GREEK      = "el"
+    HEBREW     = "he"
+    CZECH      = "cs"
+    ROMANIAN   = "ro"
+    DANISH     = "da"
+    FINNISH    = "fi"
+    NORWEGIAN  = "no"
+    UNKNOWN    = "unknown"
+
+
+class Script(Enum):
+    """
+    Writing scripts
+    """
+    LATIN      = "latin"
+    CYRILLIC   = "cyrillic"
+    ARABIC     = "arabic"
+    CHINESE    = "chinese"
+    JAPANESE   = "japanese"
+    KOREAN     = "korean"
+    DEVANAGARI = "devanagari"
+    GREEK      = "greek"
+    HEBREW     = "hebrew"
+    THAI       = "thai"
+    MIXED      = "mixed"
+    UNKNOWN    = "unknown"
+
+
+
+class ConfidenceLevel(Enum):
+    """
+    Confidence levels for authenticity estimation
+    """
+    VERY_LOW  = "very_low"
+    LOW       = "low"
+    MEDIUM    = "medium"
+    HIGH      = "high"
+    VERY_HIGH = "very_high"

config/model_config.py

@@ -1,51 +1,14 @@
 # DEPENDENCIES
-from enum import Enum
 from typing import Any
 from typing import Dict
 from typing import Optional
-from dataclasses import field
-from dataclasses import dataclass
+from config.enums import ModelType
+from config.schemas import ModelConfig
 
 
-
-class ModelType(Enum):
-    """
-    Model types for categorization
-    """
-    TRANSFORMER             = "transformer"
-    SENTENCE_TRANSFORMER    = "sentence_transformer"
-    GPT                     = "gpt"
-    GPTMASK                 = "gpt"
-    CLASSIFIER              = "classifier"
-    EMBEDDING               = "embedding"
-    RULE_BASED              = "rule_based"
-    SEQUENCE_CLASSIFICATION = "sequence_classification"  
-    CAUSAL_LM               = "causal_lm"        
-    MASKED_LM               = "masked_lm" 
-
-
-@dataclass
-class ModelConfig:
-    """
-    Configuration for a single model
-    """
-    model_id          : str
-    model_type        : ModelType
-    description       : str
-    size_mb           : int
-    required          : bool           = True
-    download_priority : int            = 1     # 1=highest, 5=lowest
-    quantizable       : bool           = True
-    onnx_compatible   : bool           = False
-    cache_model       : bool           = True
-    max_length        : Optional[int]  = None
-    batch_size        : int            = 1
-    additional_params : Dict[str, Any] = field(default_factory = dict)
-
-
-MODEL_REGISTRY : Dict[str, ModelConfig] = {"perplexity_gpt2"            : ModelConfig(model_id          = "gpt2",
-                                                                                      model_type        = ModelType.GPT,
-                                                                                      description       = "GPT-2 base for perplexity calculation",
+MODEL_REGISTRY : Dict[str, ModelConfig] = {"perplexity_reference_lm"    : ModelConfig(model_id          = "gpt2",
+                                                                                      model_type        = ModelType.LANGUAGE_MODEL,
+                                                                                      description       = "Reference language model for statistical perplexity estimation",
                                                                                       size_mb           = 548,
                                                                                       required          = True,
                                                                                       download_priority = 1,
@@ -80,9 +43,9 @@ MODEL_REGISTRY : Dict[str, ModelConfig] = {"perplexity_gpt2"            : ModelC
                                                                                       batch_size        = 16,
                                                                                       additional_params = {"is_spacy_model": True},
                                                                                      ),
-                                           "domain_classifier"          : ModelConfig(model_id          = "cross-encoder/nli-roberta-base",
+                                           "content_domain_classifier"  : ModelConfig(model_id          = "cross-encoder/nli-roberta-base",
                                                                                       model_type        = ModelType.CLASSIFIER,
-                                                                                      description       = "High-accuracy zero-shot classifier (RoBERTa-base)",
+                                                                                      description       = "Zero-shot content domain inference model",
                                                                                       size_mb           = 500,
                                                                                       required          = True,  
                                                                                       download_priority = 1,     
@@ -120,7 +83,7 @@ MODEL_REGISTRY : Dict[str, ModelConfig] = {"perplexity_gpt2"            : ModelC
                                                                                      ),
                                            "language_detector"          : ModelConfig(model_id          = "papluca/xlm-roberta-base-language-detection",
                                                                                       model_type        = ModelType.CLASSIFIER,
-                                                                                      description       = "Language detection (skip if English-only)",
+                                                                                      description       = "Language detection for routing; not used in authenticity scoring",
                                                                                       size_mb           = 1100,
                                                                                       required          = False,
                                                                                       download_priority = 5,
@@ -131,18 +94,18 @@ MODEL_REGISTRY : Dict[str, ModelConfig] = {"perplexity_gpt2"            : ModelC
 
 
 # MODEL GROUPS FOR BATCH DOWNLOADING 
-MODEL_GROUPS                            = {"minimal"   : ["perplexity_gpt2", "domain_classifier"],
-                                           "essential" : ["perplexity_gpt2", "semantic_primary", "linguistic_spacy", "domain_classifier"],
+MODEL_GROUPS                            = {"minimal"   : ["perplexity_reference_lm", "content_domain_classifier"],
+                                           "essential" : ["perplexity_reference_lm", "semantic_primary", "linguistic_spacy", "content_domain_classifier"],
                                            "extended"  : ["semantic_secondary", "multi_perturbation_mask", "domain_classifier_fallback"],
                                            "optional"  : ["language_detector"],
                                           }
 
 
 # MODEL WEIGHTS FOR ENSEMBLE : For 6 metrics implemented
-DEFAULT_MODEL_WEIGHTS                   = {"statistical"                  : 0.20,  # No model needed
-                                           "perplexity"                   : 0.20,  # gpt2
-                                           "entropy"                      : 0.15,  # gpt2 (reused)
-                                           "semantic_analysis"            : 0.20,  # all-MiniLM-L6-v2
+DEFAULT_MODEL_WEIGHTS                   = {"structural"                   : 0.20,  # No model needed
+                                           "perplexity"                   : 0.20,  # reference language model
+                                           "entropy"                      : 0.15,  # token distribution statistics
+                                           "semantic"                     : 0.20,  # all-MiniLM-L6-v2
                                            "linguistic"                   : 0.15,  # spacy
                                            "multi_perturbation_stability" : 0.10,  # gpt2 + distilroberta (optional)
                                           }

config/schemas.py

@@ -0,0 +1,452 @@
+# DEPENDENCIES
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from dataclasses import field
+from datetime import datetime
+from config.enums import Script
+from config.enums import Domain
+from config.enums import Language
+from dataclasses import dataclass
+from config.enums import ModelType
+from config.enums import ConfidenceLevel
+
+
+@dataclass
+class ModelConfig:
+    """
+    Configuration for a single model
+    """
+    model_id          : str
+    model_type        : ModelType
+    description       : str
+    size_mb           : int
+    required          : bool           = True
+    download_priority : int            = 1     # 1=highest, 5=lowest
+    quantizable       : bool           = True
+    onnx_compatible   : bool           = False
+    cache_model       : bool           = True
+    max_length        : Optional[int]  = None
+    batch_size        : int            = 1
+    additional_params : Dict[str, Any] = field(default_factory = dict)
+
+
+@dataclass
+class ModelUsageStats:
+    """
+    Lightweight model usage statistics
+    """
+    model_name               : str
+    usage_count              : int
+    last_used                : datetime
+    timed_usage_count        : int     
+    total_usage_time_seconds : float
+    avg_usage_time_seconds   : float
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"model_name"               : self.model_name,
+                "usage_count"              : self.usage_count,
+                "last_used"                : self.last_used.isoformat() if self.last_used else None,
+                "timed_usage_count"        : self.timed_usage_count,
+                "total_usage_time_seconds" : round(self.total_usage_time_seconds, 2),
+                "avg_usage_time_seconds"   : round(self.avg_usage_time_seconds, 2),
+               }
+
+
+@dataclass
+class ExtractedDocument:
+    """
+    Container for extracted document content with metadata
+    """
+    text              : str
+    file_path         : Optional[str]
+    file_type         : str
+    file_size_bytes   : int
+    page_count        : int
+    extraction_method : str
+    metadata          : Dict[str, Any]
+    is_success        : bool
+    error_message     : Optional[str]
+    warnings          : List[str]
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization
+        """
+        return {"text_length"        : len(self.text),
+                "file_type"          : self.file_type,
+                "file_size_bytes"    : self.file_size_bytes,
+                "page_count"         : self.page_count,
+                "extraction_method"  : self.extraction_method,
+                "metadata"           : self.metadata,
+                "is_success"         : self.is_success,
+                "error_message"      : self.error_message,
+                "warnings"           : self.warnings,
+               }
+
+
+
+@dataclass
+class ProcessedText:
+    """
+    Container for processed text with metadata
+    """
+    original_text      : str
+    cleaned_text       : str
+    sentences          : List[str]
+    words              : List[str]
+    paragraphs         : List[str]
+    char_count         : int
+    word_count         : int
+    sentence_count     : int
+    paragraph_count    : int
+    avg_sentence_length: float
+    avg_word_length    : float
+    is_valid           : bool
+    validation_errors  : List[str]
+    metadata           : Dict[str, Any]
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization
+        """
+        return {"original_length"      : len(self.original_text),
+                "cleaned_length"       : len(self.cleaned_text),
+                "char_count"           : self.char_count,
+                "word_count"           : self.word_count,
+                "sentence_count"       : self.sentence_count,
+                "paragraph_count"      : self.paragraph_count,
+                "avg_sentence_length"  : round(self.avg_sentence_length, 2),
+                "avg_word_length"      : round(self.avg_word_length, 2),
+                "is_valid"             : self.is_valid,
+                "validation_errors"    : self.validation_errors,
+                "metadata"             : self.metadata,
+               }
+
+
+@dataclass
+class LanguageDetectionResult:
+    """
+    Result of language detection
+    """
+    primary_language   : Language
+    evidence_strength  : float
+    all_languages      : Dict[str, float]  # language_code -> evidence_strength
+    script             : Script
+    is_multilingual    : bool
+    detection_method   : str
+    char_count         : int
+    word_count         : int
+    warnings           : List[str]
+    
+
+    def to_dict(self) -> Dict:
+        """
+        Convert to dictionary
+        """
+        return {"primary_language"  : self.primary_language.value,
+                "evidence_strength" : round(self.evidence_strength, 4),
+                "all_languages"     : {k: round(v, 4) for k, v in self.all_languages.items()},
+                "script"            : self.script.value,
+                "is_multilingual"   : self.is_multilingual,
+                "detection_method"  : self.detection_method,
+                "char_count"        : self.char_count,
+                "word_count"        : self.word_count,
+                "warnings"          : self.warnings,
+               }
+
+
+@dataclass
+class MetricThresholds:
+    """
+    Thresholds for a single metric
+    """
+    synthetic_threshold   : float       # Above this = low authenticity
+    authentic_threshold   : float       # Below this = high authenticity
+    confidence_multiplier : float = 1.0
+    weight                : float = 1.0
+
+
+@dataclass
+class DomainThresholds:
+    """
+    Thresholds for 6 metrics in a specific domain
+    """
+    domain                       : Domain
+    structural                   : MetricThresholds
+    perplexity                   : MetricThresholds
+    entropy                      : MetricThresholds
+    semantic                     : MetricThresholds
+    linguistic                   : MetricThresholds
+    multi_perturbation_stability : MetricThresholds
+    ensemble_threshold           : float            = 0.5     # authenticity decision boundary
+
+
+@dataclass
+class DomainPrediction:
+    """
+    Result of domain classification
+    """
+    primary_domain    : Domain
+    secondary_domain  : Optional[Domain]
+    evidence_strength : float
+    domain_scores     : Dict[str, float]
+
+
+class MetricResult:
+    """
+    Result from a metric calculation
+    """
+    def __init__(self, metric_name: str, synthetic_probability: float, authentic_probability: float, hybrid_probability: float, confidence: float, details: Optional[Dict[str, Any]] = None, error: Optional[str] = None):
+        self.metric_name           = metric_name
+        self.synthetic_probability = max(0.0, min(1.0, synthetic_probability))
+        self.authentic_probability = max(0.0, min(1.0, authentic_probability))
+        self.hybrid_probability    = max(0.0, min(1.0, hybrid_probability))
+        self.confidence            = max(0.0, min(1.0, confidence))
+        self.details               = details or {}
+        self.error                 = error
+        
+        # Normalize probabilities to sum to 1
+        total                      = self.synthetic_probability + self.authentic_probability + self.hybrid_probability
+        
+        if (total > 0):
+            self.synthetic_probability /= total
+            self.authentic_probability /= total
+            self.hybrid_probability    /= total
+
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"metric_name"           : self.metric_name,
+                "synthetic_probability" : round(self.synthetic_probability, 4),
+                "authentic_probability" : round(self.authentic_probability, 4),
+                "hybrid_probability"    : round(self.hybrid_probability, 4),
+                "confidence"            : round(self.confidence, 4),
+                "details"               : self.details,
+                "error"                 : self.error,
+                "success"               : self.error is None,
+               }
+    
+
+    @property
+    def is_synthetic(self) -> bool:
+        """
+        Check if classified as synthetic
+        """
+        return self.synthetic_probability > max(self.authentic_probability, self.hybrid_probability)
+    
+    
+    @property
+    def is_authentic(self) -> bool:
+        """
+        Check if classified as authentic
+        """
+        return self.authentic_probability > max(self.synthetic_probability, self.hybrid_probability)
+    
+
+    @property
+    def is_hybrid(self) -> bool:
+        """
+        Check if classified as hybrid
+        """
+        return self.hybrid_probability > max(self.synthetic_probability, self.authentic_probability)
+    
+
+    @property
+    def predicted_class(self) -> str:
+        """
+        Get predicted class
+        """
+        if self.is_synthetic:
+            return "Synthetic"
+        
+        elif self.is_authentic:
+            return "Authentic"
+        
+        else:
+            return "Hybrid"
+
+
+@dataclass
+class EnsembleResult:
+    """
+    Result from ensemble classification
+    """
+    final_verdict          : str  # "Synthetically-Generated-Text", "Authentically-Written-Text", or "Hybrid-Text"
+    synthetic_probability  : float
+    authentic_probability  : float
+    hybrid_probability     : float
+    overall_confidence     : float
+    domain                 : Domain
+    metric_results         : Dict[str, MetricResult]
+    metric_weights         : Dict[str, float]
+    weighted_scores        : Dict[str, float]
+    reasoning              : List[str]
+    uncertainty_score      : float
+    consensus_level        : float
+    execution_mode         : str
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization
+        """
+        return {"final_verdict"         : self.final_verdict,
+                "synthetic_probability" : round(self.synthetic_probability, 4),
+                "authentic_probability" : round(self.authentic_probability, 4),
+                "hybrid_probability"    : round(self.hybrid_probability, 4),
+                "overall_confidence"    : round(self.overall_confidence, 4),
+                "domain"                : self.domain.value,
+                "uncertainty_score"     : round(self.uncertainty_score, 4),
+                "consensus_level"       : round(self.consensus_level, 4),
+                "metric_contributions"  : {name: {"weight"         : round(self.metric_weights.get(name, 0.0), 4),
+                                                  "weighted_score" : round(self.weighted_scores.get(name, 0.0), 4),
+                                                  "synthetic_prob" : round(result.synthetic_probability, 4),
+                                                  "confidence"     : round(result.confidence, 4),
+                                                 }
+                                                 for name, result in self.metric_results.items()
+                                         },
+                "reasoning"             : self.reasoning,
+                "execution_mode"        : self.execution_mode,
+               }
+
+
+@dataclass
+class HighlightedSentenceResult:
+    """
+    A sentence with highlighting information
+    """
+    text                  : str
+    synthetic_probability : float
+    authentic_probability : float
+    hybrid_probability    : float
+    confidence            : float
+    confidence_level      : ConfidenceLevel
+    color_class           : str
+    tooltip               : str
+    index                 : int
+    is_hybrid_content     : bool
+    metric_breakdown      : Optional[Dict[str, float]] = None
+
+
+
+@dataclass
+class DetectionResult:
+    """
+    Complete detection result with all metadata
+    """
+    # Final results
+    ensemble_result        : EnsembleResult
+    
+    # Input metadata
+    processed_text         : ProcessedText
+    domain_prediction      : DomainPrediction
+    language_result        : Optional[LanguageDetectionResult]
+    
+    # Metric details
+    metric_results         : Dict[str, MetricResult]
+    
+    # Performance metrics
+    processing_time        : float
+    metrics_execution_time : Dict[str, float] 
+    
+    # Warnings and errors
+    warnings               : List[str]
+    errors                 : List[str]
+    
+    # File information
+    file_info              : Optional[Dict[str, Any]] = None
+    
+    # Execution mode
+    execution_mode         : Optional[str]            = "parallel"
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization
+        """
+        result = {"prediction"  : {"verdict"               : self.ensemble_result.final_verdict,
+                                   "synthetic_probability" : round(self.ensemble_result.synthetic_probability, 4),
+                                   "authentic_probability" : round(self.ensemble_result.authentic_probability, 4),
+                                   "hybrid_probability"    : round(self.ensemble_result.hybrid_probability, 4),
+                                   "confidence"            : round(self.ensemble_result.overall_confidence, 4),
+                                  },
+                  "analysis"    : {"domain"              : self.domain_prediction.primary_domain.value,
+                                   "domain_confidence"   : round(self.domain_prediction.evidence_strength, 4),
+                                   "language"            : self.language_result.primary_language.value if self.language_result else "unknown",
+                                   "language_confidence" : round(self.language_result.evidence_strength, 4) if self.language_result else 0.0,
+                                   "text_length"         : self.processed_text.word_count,
+                                   "sentence_count"      : self.processed_text.sentence_count,
+                                  },
+                  "metrics"     : {name: result.to_dict() for name, result in self.metric_results.items()},
+                  "ensemble"    : self.ensemble_result.to_dict(),
+                  "performance" : {"total_time"   : round(self.processing_time, 3),
+                                   "metrics_time" : {name: round(t, 3) for name, t in self.metrics_execution_time.items()},
+                                  },
+                  "warnings"    : self.warnings,
+                  "errors"      : self.errors,
+                 }
+        
+        # Include file_info if available
+        if self.file_info:
+            result["file_info"] = self.file_info
+        
+        return result
+
+
+@dataclass
+class DetailedReasoningResult:
+    """
+    Comprehensive reasoning for detection result with ensemble integration
+    """
+    summary                : str
+    key_indicators         : List[str]
+    metric_explanations    : Dict[str, str]
+    supporting_evidence    : List[str]
+    contradicting_evidence : List[str]
+    confidence_explanation : str
+    domain_analysis        : str
+    ensemble_analysis      : str
+    recommendations        : List[str]
+    uncertainty_analysis   : str
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"summary"                : self.summary,
+                "key_indicators"         : self.key_indicators,
+                "metric_explanations"    : self.metric_explanations,
+                "supporting_evidence"    : self.supporting_evidence,
+                "contradicting_evidence" : self.contradicting_evidence,
+                "confidence_explanation" : self.confidence_explanation,
+                "domain_analysis"        : self.domain_analysis,
+                "ensemble_analysis"      : self.ensemble_analysis,
+                "recommendations"        : self.recommendations,
+                "uncertainty_analysis"   : self.uncertainty_analysis,
+               }
+
+
+@dataclass
+class DetailedMetricResult:
+    """
+    Metric data structure with sub-metrics
+    """
+    name                  : str
+    synthetic_probability : float
+    authentic_probability : float
+    confidence            : float
+    verdict               : str
+    description           : str
+    detailed_metrics      : Dict[str, float]
+    weight                : float

config/settings.py

@@ -12,88 +12,87 @@ class Settings(BaseSettings):
     Main application settings
     """
     # Application Info
-    APP_NAME                : str           = "TEXT-AUTH"
-    APP_VERSION             : str           = "1.0.0"
-    APP_DESCRIPTION         : str           = "AI Text Detection Platform"
+    APP_NAME                          : str           = "TEXT-AUTH"
+    APP_VERSION                       : str           = "1.0.0"
+    APP_DESCRIPTION                   : str           = "Text Authentication & Content Authenticity Platform"
     
     # Environment
-    ENVIRONMENT             : str           = Field(default = "development", env = "ENVIRONMENT")
-    DEBUG                   : bool          = Field(default = True, env = "DEBUG")
+    ENVIRONMENT                       : str           = Field(default = "development", env = "ENVIRONMENT")
+    DEBUG                             : bool          = Field(default = True, env = "DEBUG")
     
     # Server Configuration
-    HOST                    : str           = Field(default = "0.0.0.0", env = "HOST")
-    PORT                    : int           = Field(default = 8000, env = "PORT")
-    WORKERS                 : int           = Field(default = 4, env = "WORKERS")
+    HOST                              : str           = Field(default = "0.0.0.0", env = "HOST")
+    PORT                              : int           = Field(default = 8000, env = "PORT")
+    WORKERS                           : int           = Field(default = 4, env = "WORKERS")
     
     # Paths
-    BASE_DIR                : Path          = Path(__file__).parent.parent.resolve()
-    MODEL_CACHE_DIR         : Path          = Field(default = Path(__file__).parent.parent / "models" / "cache", env = "MODEL_CACHE_DIR")
-    LOG_DIR                 : Path          = Field(default = Path(__file__).parent.parent / "logs", env = "LOG_DIR")
-    UPLOAD_DIR              : Path          = Field(default = Path(__file__).parent.parent / "data" / "uploads", env = "UPLOAD_DIR")
-    REPORT_DIR              : Path          = Field(default = Path(__file__).parent.parent / "data" / "reports", env = "REPORT_DIR")
+    BASE_DIR                          : Path          = Path(__file__).parent.parent.resolve()
+    MODEL_CACHE_DIR                   : Path          = Field(default = Path(__file__).parent.parent / "models" / "cache", env = "MODEL_CACHE_DIR")
+    LOG_DIR                           : Path          = Field(default = Path(__file__).parent.parent / "logs", env = "LOG_DIR")
+    UPLOAD_DIR                        : Path          = Field(default = Path(__file__).parent.parent / "data" / "uploads", env = "UPLOAD_DIR")
+    REPORT_DIR                        : Path          = Field(default = Path(__file__).parent.parent / "data" / "reports", env = "REPORT_DIR")
     
     # File Upload Settings
-    MAX_UPLOAD_SIZE         : int           = 10 * 1024 * 1024  # 10MB
-    ALLOWED_EXTENSIONS      : list          = [".txt", ".pdf", ".docx", ".doc", ".md"]
+    MAX_UPLOAD_SIZE                   : int           = 10 * 1024 * 1024  # 10MB
+    ALLOWED_EXTENSIONS                : list          = [".txt", ".pdf", ".docx", ".doc", ".md"]
     
     # Processing Settings
-    MAX_TEXT_LENGTH         : int           = 500000  # Maximum characters to process
-    MIN_TEXT_LENGTH         : int           = 50      # Minimum characters for analysis
-    CHUNK_SIZE              : int           = 512     # Tokens per chunk
-    CHUNK_OVERLAP           : int           = 50      # Overlap between chunks
+    MAX_TEXT_LENGTH                   : int           = 500000  # Maximum characters to process
+    MIN_TEXT_LENGTH                   : int           = 200     # Minimum characters for analysis
+    CHUNK_SIZE                        : int           = 512     # Tokens per chunk
+    CHUNK_OVERLAP                     : int           = 50      # Overlap between chunks
     
     # Model Settings
-    DEVICE                  : str           = Field(default = "cpu", env = "DEVICE")  # "cuda" or "cpu"
-    USE_QUANTIZATION        : bool          = Field(default = False, env = "USE_QUANTIZATION")
-    USE_ONNX                : bool          = Field(default = False, env = "USE_ONNX")
-    MODEL_LOAD_STRATEGY     : str           = "lazy"  # "lazy" or "eager"
-    MAX_CACHED_MODELS       : int           = 5
+    DEVICE                            : str           = Field(default = "cpu", env = "DEVICE")  # "cuda" or "cpu"
+    USE_QUANTIZATION                  : bool          = Field(default = False, env = "USE_QUANTIZATION")
+    USE_ONNX                          : bool          = Field(default = False, env = "USE_ONNX")
+    MODEL_LOAD_STRATEGY               : str           = "lazy"  # "lazy" or "eager"
+    MAX_CACHED_MODELS                 : int           = 5
     
     # Detection Settings
-    CONFIDENCE_THRESHOLD    : float         = 0.7  # Minimum confidence for classification
-    ENSEMBLE_METHOD         : str           = "weighted_average"  # "weighted_average", "voting", "stacking"
-    USE_DOMAIN_ADAPTATION   : bool          = True
+    AUTHENTICITY_CONFIDENCE_THRESHOLD : float         = 0.7                 # Minimum confidence for classification
+    ENSEMBLE_METHOD                   : str           = "weighted_average"  # "weighted_average", "voting", "stacking"
+    USE_DOMAIN_CALIBRATION            : bool          = True
     
     # Rate Limiting
-    RATE_LIMIT_ENABLED      : bool          = True
-    RATE_LIMIT_REQUESTS     : int           = 100
-    RATE_LIMIT_WINDOW       : int           = 3600  # seconds (1 hour)
+    RATE_LIMIT_ENABLED                : bool          = True
+    RATE_LIMIT_REQUESTS               : int           = 100
+    RATE_LIMIT_WINDOW                 : int           = 3600  # seconds (1 hour)
     
     # Logging
-    LOG_LEVEL               : str           = Field(default="INFO", env="LOG_LEVEL")
-    LOG_FORMAT              : str           = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    LOG_ROTATION            : str           = "1 day"
-    LOG_RETENTION           : str           = "30 days"
+    LOG_LEVEL                         : str           = Field(default = "INFO", env = "LOG_LEVEL")
+    LOG_FORMAT                        : str           = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    LOG_ROTATION                      : str           = "1 day"
+    LOG_RETENTION                     : str           = "30 days"
     
     # API Settings
-    API_PREFIX              : str           = "/api/v1"
-    CORS_ORIGINS            : list          = ["*"]  # For production, specify exact origins
+    API_PREFIX                        : str           = "/api/v1"
+    CORS_ORIGINS                      : list          = ["*"]  # For production, specify exact origins
     
     # Database (Optional - for future)
-    DATABASE_URL            : Optional[str] = Field(default = None, env = "DATABASE_URL")
+    DATABASE_URL                      : Optional[str] = Field(default = None, env = "DATABASE_URL")
     
     # Security
-    SECRET_KEY              : str           = Field(default = "your-secret-key-change-in-production", env = "SECRET_KEY")
-    API_KEY_ENABLED         : bool          = False
+    SECRET_KEY                        : str           = Field(default = "your-secret-key-change-in-production", env = "SECRET_KEY")
+    API_KEY_ENABLED                   : bool          = False
     
     # Feature Flags
-    ENABLE_ATTRIBUTION      : bool          = True
-    ENABLE_HIGHLIGHTING     : bool          = True
-    ENABLE_PDF_REPORTS      : bool          = True
-    ENABLE_BATCH_PROCESSING : bool          = True
+    ENABLE_HIGHLIGHTING               : bool          = True
+    ENABLE_PDF_REPORTS                : bool          = True
+    ENABLE_BATCH_PROCESSING           : bool          = True
      
     # Performance
-    MAX_CONCURRENT_REQUESTS : int           = 10
-    REQUEST_TIMEOUT         : int           = 300  # seconds (5 minutes)
+    MAX_CONCURRENT_REQUESTS           : int           = 10
+    REQUEST_TIMEOUT                   : int           = 300  # seconds (5 minutes)
     
     # Metrics Configuration
-    METRICS_ENABLED         : dict          = {"semantic_analysis"            : True,
-                                               "multi_perturbation_stability" : True,
-                                               "perplexity"                   : True,
-                                               "statistical"                  : True,
-                                               "entropy"                      : True,
-                                               "linguistic"                   : True,
-                                              }
+    METRICS_ENABLED                   : dict          = {"semantic_analysis"            : True,
+                                                         "multi_perturbation_stability" : True,
+                                                         "perplexity"                   : True,
+                                                         "structural"                   : True,
+                                                         "entropy"                      : True,
+                                                         "linguistic"                   : True,
+                                                        }
     
     class Config:
         env_file       = ".env"

config/threshold_config.py

@@ -1,244 +1,186 @@
 # DEPENDENCIES
-from enum import Enum
 from typing import Dict
 from typing import Tuple
-from dataclasses import dataclass
-
-
-class Domain(Enum):
-    """
-    Text domains for adaptive thresholding
-    """
-    # Core domains
-    GENERAL         = "general"
-    ACADEMIC        = "academic"
-    CREATIVE        = "creative"
-    AI_ML           = "ai_ml"              
-    SOFTWARE_DEV    = "software_dev"       
-    TECHNICAL_DOC   = "technical_doc"      
-    ENGINEERING     = "engineering"   
-    SCIENCE         = "science"     
-    BUSINESS        = "business"
-    LEGAL           = "legal"
-    MEDICAL         = "medical"
-    JOURNALISM      = "journalism"
-    MARKETING       = "marketing"
-    SOCIAL_MEDIA    = "social_media"
-    BLOG_PERSONAL   = "blog_personal"   
-    TUTORIAL        = "tutorial"      
-
-
-class ConfidenceLevel(Enum):
-    """
-    Confidence levels for classification
-    """
-    VERY_LOW  = "very_low"
-    LOW       = "low"
-    MEDIUM    = "medium"
-    HIGH      = "high"
-    VERY_HIGH = "very_high"
-
-
-@dataclass
-class MetricThresholds:
-    """
-    Thresholds for a single metric
-    """
-    ai_threshold          : float       # Above this = likely AI
-    human_threshold       : float       # Below this = likely human
-    confidence_multiplier : float = 1.0
-    weight                : float = 1.0
-
-
-@dataclass
-class DomainThresholds:
-    """
-    Thresholds for 6 metrics in a specific domain
-    """
-    domain                       : Domain
-    structural                   : MetricThresholds
-    perplexity                   : MetricThresholds
-    entropy                      : MetricThresholds
-    semantic_analysis            : MetricThresholds
-    linguistic                   : MetricThresholds
-    multi_perturbation_stability : MetricThresholds
-    ensemble_threshold           : float = 0.5
+from config.enums import Domain
+from config.enums import ConfidenceLevel
+from config.schemas import MetricThresholds
+from config.schemas import DomainThresholds
 
 
 # ==================== DOMAIN-SPECIFIC THRESHOLDS ====================
 # GENERAL (Default fallback)
 DEFAULT_THRESHOLDS       = DomainThresholds(domain                       = Domain.GENERAL,
-                                            structural                   = MetricThresholds(ai_threshold = 0.55, human_threshold = 0.45, weight = 0.20),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.25),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.48, human_threshold = 0.52, weight = 0.15),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.55, human_threshold = 0.45, weight = 0.18),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.12),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.10),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.55, authentic_threshold = 0.45, weight = 0.20),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.25),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.48, authentic_threshold = 0.52, weight = 0.15),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.55, authentic_threshold = 0.45, weight = 0.18),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.12),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.10),
                                             ensemble_threshold           = 0.40,
                                            )
 
 # ACADEMIC
 ACADEMIC_THRESHOLDS      = DomainThresholds(domain                       = Domain.ACADEMIC,
-                                            structural                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.45, weight = 0.26),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.45, human_threshold = 0.50, weight = 0.14),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.65, human_threshold = 0.35, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.45, weight = 0.26),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.45, authentic_threshold = 0.50, weight = 0.14),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.65, authentic_threshold = 0.35, weight = 0.08),
                                             ensemble_threshold           = 0.42,
                                            )
 
 # CREATIVE WRITING
 CREATIVE_THRESHOLDS      = DomainThresholds(domain                       = Domain.CREATIVE,
-                                            structural                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.55, human_threshold = 0.50, weight = 0.22),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.55, weight = 0.16),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.55, human_threshold = 0.45, weight = 0.16),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.55, authentic_threshold = 0.50, weight = 0.22),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.55, weight = 0.16),
+                                            semantic            = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.55, authentic_threshold = 0.45, weight = 0.16),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.08),
                                             ensemble_threshold           = 0.38,
                                            )
 
 # AI/ML/DATA SCIENCE
 AI_ML_THRESHOLDS         = DomainThresholds(domain                       = Domain.AI_ML,
-                                            structural                   = MetricThresholds(ai_threshold = 0.57, human_threshold = 0.43, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.51, human_threshold = 0.46, weight = 0.26),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.47, human_threshold = 0.50, weight = 0.14),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.57, human_threshold = 0.43, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.61, human_threshold = 0.39, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.64, human_threshold = 0.36, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.57, authentic_threshold = 0.43, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.51, authentic_threshold = 0.46, weight = 0.26),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.47, authentic_threshold = 0.50, weight = 0.14),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.57, authentic_threshold = 0.43, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.61, authentic_threshold = 0.39, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.64, authentic_threshold = 0.36, weight = 0.08),
                                             ensemble_threshold           = 0.41,
                                            )
 
 # SOFTWARE DEVELOPMENT
 SOFTWARE_DEV_THRESHOLDS  = DomainThresholds(domain                       = Domain.SOFTWARE_DEV,
-                                            structural                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.17),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.45, weight = 0.27),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.46, human_threshold = 0.50, weight = 0.14),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.63, human_threshold = 0.37, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.17),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.45, weight = 0.27),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.46, authentic_threshold = 0.50, weight = 0.14),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.63, authentic_threshold = 0.37, weight = 0.08),
                                             ensemble_threshold           = 0.41,
                                            )
 
 # TECHNICAL DOCUMENTATION 
 TECHNICAL_DOC_THRESHOLDS = DomainThresholds(domain                       = Domain.TECHNICAL_DOC,
-                                            structural                   = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.49, human_threshold = 0.44, weight = 0.27),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.45, human_threshold = 0.49, weight = 0.13),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.65, human_threshold = 0.35, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.49, authentic_threshold = 0.44, weight = 0.27),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.45, authentic_threshold = 0.49, weight = 0.13),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.65, authentic_threshold = 0.35, weight = 0.08),
                                             ensemble_threshold           = 0.42,
                                            )
 
 # ENGINEERING
 ENGINEERING_THRESHOLDS   = DomainThresholds(domain                       = Domain.ENGINEERING,
-                                            structural                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.45, weight = 0.26),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.46, human_threshold = 0.50, weight = 0.14),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.61, human_threshold = 0.39, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.64, human_threshold = 0.36, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.45, weight = 0.26),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.46, authentic_threshold = 0.50, weight = 0.14),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.61, authentic_threshold = 0.39, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.64, authentic_threshold = 0.36, weight = 0.08),
                                             ensemble_threshold           = 0.41,
                                            )
 
 # SCIENCE (Physics, Chemistry, Biology)
 SCIENCE_THRESHOLDS       = DomainThresholds(domain                       = Domain.SCIENCE,
-                                            structural                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.51, human_threshold = 0.46, weight = 0.26),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.46, human_threshold = 0.50, weight = 0.14),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.14),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.64, human_threshold = 0.36, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.51, authentic_threshold = 0.46, weight = 0.26),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.46, authentic_threshold = 0.50, weight = 0.14),
+                                            semantic            = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.14),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.64, authentic_threshold = 0.36, weight = 0.08),
                                             ensemble_threshold           = 0.42,
                                            )
 
 # BUSINESS
 BUSINESS_THRESHOLDS      = DomainThresholds(domain                       = Domain.BUSINESS,
-                                            structural                   = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.24),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.48, human_threshold = 0.52, weight = 0.15),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.19),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.15),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.09),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.24),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.48, authentic_threshold = 0.52, weight = 0.15),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.19),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.15),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.09),
                                             ensemble_threshold           = 0.40,
                                            )
 
 # LEGAL
 LEGAL_THRESHOLDS         = DomainThresholds(domain                       = Domain.LEGAL,
-                                            structural                   = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.17),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.44, weight = 0.27),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.44, human_threshold = 0.48, weight = 0.13),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.63, human_threshold = 0.37, weight = 0.15),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.66, human_threshold = 0.34, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.17),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.44, weight = 0.27),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.44, authentic_threshold = 0.48, weight = 0.13),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.63, authentic_threshold = 0.37, weight = 0.15),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.66, authentic_threshold = 0.34, weight = 0.08),
                                             ensemble_threshold           = 0.43,
                                            )
 
 # MEDICAL
 MEDICAL_THRESHOLDS       = DomainThresholds(domain                       = Domain.MEDICAL,
-                                            structural                   = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.17),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.45, weight = 0.27),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.45, human_threshold = 0.49, weight = 0.13),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.15),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.65, human_threshold = 0.35, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.17),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.45, weight = 0.27),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.45, authentic_threshold = 0.49, weight = 0.13),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.15),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.65, authentic_threshold = 0.35, weight = 0.08),
                                             ensemble_threshold           = 0.43,
                                            )
 
 # JOURNALISM
 JOURNALISM_THRESHOLDS    = DomainThresholds(domain                       = Domain.JOURNALISM,
-                                            structural                   = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.24),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.48, human_threshold = 0.52, weight = 0.15),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.20),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.58, human_threshold = 0.42, weight = 0.15),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.24),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.48, authentic_threshold = 0.52, weight = 0.15),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.20),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.58, authentic_threshold = 0.42, weight = 0.15),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.08),
                                             ensemble_threshold           = 0.40,
                                            )
 
 # MARKETING
 MARKETING_THRESHOLDS     = DomainThresholds(domain                       = Domain.MARKETING,
-                                            structural                   = MetricThresholds(ai_threshold = 0.54, human_threshold = 0.46, weight = 0.19),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.53, human_threshold = 0.49, weight = 0.23),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.49, human_threshold = 0.53, weight = 0.15),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.54, human_threshold = 0.46, weight = 0.19),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.57, human_threshold = 0.43, weight = 0.16),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.61, human_threshold = 0.39, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.54, authentic_threshold = 0.46, weight = 0.19),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.53, authentic_threshold = 0.49, weight = 0.23),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.49, authentic_threshold = 0.53, weight = 0.15),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.54, authentic_threshold = 0.46, weight = 0.19),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.57, authentic_threshold = 0.43, weight = 0.16),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.61, authentic_threshold = 0.39, weight = 0.08),
                                             ensemble_threshold           = 0.39,
                                            )
 
 # SOCIAL MEDIA
 SOCIAL_MEDIA_THRESHOLDS  = DomainThresholds(domain                       = Domain.SOCIAL_MEDIA,
-                                            structural                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.54, human_threshold = 0.50, weight = 0.20),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.54, weight = 0.17),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.18),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.55, human_threshold = 0.45, weight = 0.18),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.60, human_threshold = 0.40, weight = 0.09),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.54, authentic_threshold = 0.50, weight = 0.20),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.54, weight = 0.17),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.18),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.55, authentic_threshold = 0.45, weight = 0.18),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.60, authentic_threshold = 0.40, weight = 0.09),
                                             ensemble_threshold           = 0.36,
                                            )
 
 # PERSONAL BLOG
 BLOG_PERSONAL_THRESHOLDS = DomainThresholds(domain                       = Domain.BLOG_PERSONAL,
-                                            structural                   = MetricThresholds(ai_threshold = 0.53, human_threshold = 0.47, weight = 0.19),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.54, human_threshold = 0.50, weight = 0.22),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.50, human_threshold = 0.54, weight = 0.16),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.53, human_threshold = 0.47, weight = 0.19),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.16),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.53, authentic_threshold = 0.47, weight = 0.19),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.54, authentic_threshold = 0.50, weight = 0.22),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.50, authentic_threshold = 0.54, weight = 0.16),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.53, authentic_threshold = 0.47, weight = 0.19),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.16),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.08),
                                             ensemble_threshold           = 0.38,
                                            )
 
 # TUTORIAL/HOW-TO
 TUTORIAL_THRESHOLDS      = DomainThresholds(domain                       = Domain.TUTORIAL,
-                                            structural                   = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.18),
-                                            perplexity                   = MetricThresholds(ai_threshold = 0.52, human_threshold = 0.48, weight = 0.25),
-                                            entropy                      = MetricThresholds(ai_threshold = 0.48, human_threshold = 0.52, weight = 0.15),
-                                            semantic_analysis            = MetricThresholds(ai_threshold = 0.56, human_threshold = 0.44, weight = 0.19),
-                                            linguistic                   = MetricThresholds(ai_threshold = 0.59, human_threshold = 0.41, weight = 0.15),
-                                            multi_perturbation_stability = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.08),
+                                            structural                   = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.18),
+                                            perplexity                   = MetricThresholds(synthetic_threshold = 0.52, authentic_threshold = 0.48, weight = 0.25),
+                                            entropy                      = MetricThresholds(synthetic_threshold = 0.48, authentic_threshold = 0.52, weight = 0.15),
+                                            semantic                     = MetricThresholds(synthetic_threshold = 0.56, authentic_threshold = 0.44, weight = 0.19),
+                                            linguistic                   = MetricThresholds(synthetic_threshold = 0.59, authentic_threshold = 0.41, weight = 0.15),
+                                            multi_perturbation_stability = MetricThresholds(synthetic_threshold = 0.62, authentic_threshold = 0.38, weight = 0.08),
                                             ensemble_threshold           = 0.40,
                                            )
 
@@ -282,7 +224,8 @@ def get_threshold_for_domain(domain: Domain) -> DomainThresholds:
 
 def get_confidence_level(score: float) -> ConfidenceLevel:
     """
-    Determine confidence level based on score
+    Determine confidence level for authenticity estimation
+    (score represents synthetic-likeness probability)
     """
     for level, (min_val, max_val) in CONFIDENCE_RANGES.items():
         if (min_val <= score < max_val):
@@ -317,16 +260,16 @@ def interpolate_thresholds(domain1: Domain, domain2: Domain, weight1: float = 0.
     weight2 = 1 - weight1
     
     def interpolate_metric(m1: MetricThresholds, m2: MetricThresholds) -> MetricThresholds:
-        return MetricThresholds(ai_threshold    = m1.ai_threshold * weight1 + m2.ai_threshold * weight2,
-                                human_threshold = m1.human_threshold * weight1 + m2.human_threshold * weight2,
-                                weight          = m1.weight * weight1 + m2.weight * weight2,
+        return MetricThresholds(synthetic_threshold = m1.synthetic_threshold * weight1 + m2.synthetic_threshold * weight2,
+                                authentic_threshold = m1.authentic_threshold * weight1 + m2.authentic_threshold * weight2,
+                                weight              = m1.weight * weight1 + m2.weight * weight2,
                                )
     
     return DomainThresholds(domain                       = domain1,
                             structural                   = interpolate_metric(thresh1.structural, thresh2.structural),
                             perplexity                   = interpolate_metric(thresh1.perplexity, thresh2.perplexity),
                             entropy                      = interpolate_metric(thresh1.entropy, thresh2.entropy),
-                            semantic_analysis            = interpolate_metric(thresh1.semantic_analysis, thresh2.semantic_analysis),
+                            semantic                     = interpolate_metric(thresh1.semantic, thresh2.semantic),
                             linguistic                   = interpolate_metric(thresh1.linguistic, thresh2.linguistic),
                             multi_perturbation_stability = interpolate_metric(thresh1.multi_perturbation_stability, thresh2.multi_perturbation_stability),
                             ensemble_threshold           = thresh1.ensemble_threshold * weight1 + thresh2.ensemble_threshold * weight2,
@@ -342,7 +285,7 @@ def get_active_metric_weights(domain: Domain, enabled_metrics: Dict[str, bool])
     metric_mapping = {"structural"                   : thresholds.structural,
                       "perplexity"                   : thresholds.perplexity,
                       "entropy"                      : thresholds.entropy,
-                      "semantic_analysis"            : thresholds.semantic_analysis,
+                      "semantic"                     : thresholds.semantic,
                       "linguistic"                   : thresholds.linguistic,
                       "multi_perturbation_stability" : thresholds.multi_perturbation_stability,
                      }

data/reports/file_1765557325979_20251212_220627.pdf

@@ -1,181 +0,0 @@
-%PDF-1.4
-%���� ReportLab Generated PDF document http://www.reportlab.com
-1 0 obj
-<<
-/F1 2 0 R /F2 3 0 R /F3 5 0 R /F4 10 0 R
->>
-endobj
-2 0 obj
-<<
-/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
->>
-endobj
-3 0 obj
-<<
-/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
->>
-endobj
-4 0 obj
-<<
-/Contents 15 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-5 0 obj
-<<
-/BaseFont /Helvetica-Oblique /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
->>
-endobj
-6 0 obj
-<<
-/Contents 16 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-7 0 obj
-<<
-/Contents 17 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-8 0 obj
-<<
-/Contents 18 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-9 0 obj
-<<
-/Contents 19 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-10 0 obj
-<<
-/BaseFont /ZapfDingbats /Name /F4 /Subtype /Type1 /Type /Font
->>
-endobj
-11 0 obj
-<<
-/Contents 20 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 14 0 R /Resources <<
-/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
->> /Rotate 0 /Trans <<
-
->> 
-  /Type /Page
->>
-endobj
-12 0 obj
-<<
-/PageMode /UseNone /Pages 14 0 R /Type /Catalog
->>
-endobj
-13 0 obj
-<<
-/Author (\(anonymous\)) /CreationDate (D:20251212220627-05'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20251212220627-05'00') /Producer (ReportLab PDF Library - www.reportlab.com) 
-  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
->>
-endobj
-14 0 obj
-<<
-/Count 6 /Kids [ 4 0 R 6 0 R 7 0 R 8 0 R 9 0 R 11 0 R ] /Type /Pages
->>
-endobj
-15 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 2007
->>
-stream
-Gau`SlZ:cL&HC$_Z!Wm7R;fip:(MiL2G%Rka"^38b]p!0`#4ekYU'nH:B1+Wh<@?>9JT=@(aJiohtu0A4U)V8bl#IrJ=f4(klh1/+hS'B&-p'20FiGj4]YIl'Ke;s^*!-kJK'7EiR/#\5)&et[cjD-<m*sHCR!"n;'VECWPWY2a/"Xji>`&s$!`M.nO5E_HOZb9d@63UjC3E>i?no'_/Q"b/UE300<F_J<\`7ch_/Z6@)<RB,Ro.d!!uoNUFt?9m%oG\%?;eBpPe;N9KN@b]'!t?^b:*W\s:b"f1pDI1ulMeb\qk=eXm"MW^=ZnZ:SJh7]WFLal-8`CpKdYIugeVHT1H//LT&:=6J;+LO,c^<VF+*WQLr%blLPN<3]WQ</.3pJQ"0E.PRRZkkiV)A*BM;:.qG\4j`4&2rJg$FkH[[4's6`FUk1gn7K"*)(pT1;K/o:N-7-WSj)7i>/U5"8Ja'L#?Rt%:bZ$B$^El;L\Z@N]=+;+G=4^Od[g(IUE5QQF2?sE:%6fq?]Rk=;o1P[S[`2s&m&J2V;o#&T0T:iM]`hkJK[(=.CalY,D#?oPaDOh5@4:FoSiVb]H1uI;"Vdo##Al+l]Jp-97!3OdK_DtHo/cQpuV[PNjd:iE6/V-R!,XNJ4Ve;P)f'N+bM#fYU!$^iaZ@'BtDu0Z)Wtr:X1YZZD&C7NXuAW8E&'?YMNWGY.I997u?k@9mS\mD1("\V1u-nKUm/%-\ArA(bmu&AerW("QWKS=?A"?XiT[%:R6s0Oe@3B<(bo0fI4]n8rpG1)'rUYo$Lj3_5G^(6n?9!=(,l]d"O+kY;M8YM=.LmL;[sNn0&_:)SXi]NC?R?T/E;HS6>Jg+uQ=kU4/Dd-]3n3BC"FqFpQ29TcG-T[iF;+\$1)po?]06XK7i<lm&VOCVuYnqY(F-Ra^l[na5H!,&H@XhkhO#Xi!HG1tqg_[7F1DU=i.I/]It4X5q*M^2-=5KG4I)`hp'c!Z,fD_"-#o8/Br+a&(_f?jJ7eknk<5Lc)HeA<pNd0UC3fo>fQ[Xc/P[p6Sre@T^L&B9;i`.\.Xu9S0Q-@B)c3p!`(jeh,6'E#IZAl;/kl%C-P"b\_>><&WR5lrJk'YtXQ4[WuCs-rXnl]%H1tnt\&NC&$Y1&r,GX0b%>$#ME]+F6lfEN'1ar*3>;86-HOUWb[?@b#'!\Csr2kY0n._=/4<uBSZlF#?efHXFam,:-8OZ<Z:rYH*\\edc0L2\0/'fJ)eA8jsnWbq)Mh/q#+f`&:3%lnAt<p,Jbq3q-.O;>EFA^3X?E-%;.ud$%s^%>=dg`!?/US[)Ni.&`(/sYZ)(-&`$^,=rn7],H?tFpSP>2qci;m7*fpT7?-WE`_-'6(2q;FkuLcME(ahDd'i`%<gG0`f*F$$"!`:K%T`)512HrA@pHCXFb*ce7uH1RWL9iVNpn%\97d&`l0anTAbFXKl^,*@dIci!jSIucNi?#g(N3:A*NhA*BFV*/0h;34=UYLYbk$e%j$(6Y``O6sh;+gj>*,QO,fYBmLL!e/@@8[4&D+;rGIA@WcCe;!FC$M\V9ji,5+Ai8edY[%+)4g%(k^pn*MpYZQ5#$FRqfC=.+mn(6Sk:'"3qJgl67UnVCS'Y-BmJk<G`aEoY1^rPq''bc66P4G*!Nn#3Z#rl9Pu`p&FX[R]oi3E\l$;qT"#8Ap!q5b'N@Yq:BAeYYq+Db-Y?]J(b(j&5KiCi6Bi6!e#J#hI*<HkKJS7-C\f7+$_eXIUB8gYWC[C0`nR:\%ALsL-(+>U+`k#@ZdWYA9+cpW31]71QGMX/@55R.R=GsPC^Z9[M>oof:?6/5JlJ"a1,"Ap3(a[X38+rF:;a$7ZjlKd$In&(>1Su[TR^>MRrlj8G'`QrpK+m?KmJ-gLb_nUaj]Q!j<FR)ckG@d`;]HcV^!q,b4L5;W;kPQO-u:r@``4g9-;9DQk=og!%<I>.!aAqk7JDd^MSTDR=].!8DUu13dJ*e%qgOmd+J7oT3Db#^ZLN:@*Nf~>endstream
-endobj
-16 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 1177
->>
-stream
-Gatm;D/Ymt&H88.EF12,e*?`4%"(`1[Ui(:X^RYFm7WnX.2.7B*2Skmj*)h8a;[toM,GlDhqdo!I*\&Y`@oF7c;t!)!PEj,J8ki9J6BgB?j(r*qqYc$S!&@J"`[ho`>uHR(iuM7!+D$OXp'Id-6*'NZA7"5bsAR#iuFGU)g@;+rpAl?i(jCk9Eq76e)Bp6"MZ((D1$fODp>I.;E-:"^?=9m\8?LV4I6D9S#=G`D4JXY)g;mJ"[email protected]'TE-X8kO+n_Y"\.Us+L2>`c"R,8M7&3u]Lu;30KoJ=&q2G?B%($*a3M+TFtSVgfbDOOU57=:\8cl,K`5?bj&,5nkOCYikek`\aabn/-h0R6;"7fhI!$q:7M6`B$P!:3XC8,A3m;\*cWZF_16-d`IJ/CO#<#/baP\_K(1bQ-mTc:kWKA$UG<sH>1dU;-(b[$<=/lEY/`Sf9`kd)E#3O(fj]jLn"W)f9(B)@l%)tn(-Atn`XU?b!X8?r9?%pHlXVTj8R9JE:$3n[bWg9$na^HVPTmX`7Y9"H=aW2==0A^8TDR!aSK"DOV_JRq)[;?)5FRr?4dsRGsF*)>Tf&#)_*q/`30o:O':0PUV%a$fJM`Dbnk=gRe(<s1mq":k=;m8ESd%YP&0%j"-oY68=p4L!9/Jqp,)r>rML7]i[<CLk-&"ml4m#qCSMWP=dDWM"+,6M.IBp9e/,13!=P+iM5jW8#Sm^s+]O@nG1(p#$la^FJe+Osd5!WbkiD=AoOIsa'CiO_>Pn1h_AI^N7ppXQM,G2OB`3k;%bSZ_.%S^*t9LVc3T[C:dha=SU=cC[9Sn\UeX%Ea`SRQUO_7b#l:!?t,%7R5f%/72BQ'WL7l?bk1>gArWEM/37D9b/sYX'(D;"-bjo#d'SF_.uf\DL-gFWrG+uN#E:N,kRV2jok#PdWces&24Ks;V^GEBtD(V0Y3d:SUb7(T)s:@SkF2a)R5Q!1V0C-]6EQ*>i07;UX3h<mq-.-jDno)FD&s,hi3.(5NZ+gF@+lq`sFu4n(_L)P$-Gu>b7-^jKToPYmF;[$c\3Tg0W#X600sb9^sS&cd@%0m<K)'.+NUT'T\CrOMM"pGNpVK[J@!rL[ePZYR0tI/<l`[&U&1FV,JohZa/9&eC9PXkXcI7)q0R,c'Bh(KTu:R]k>(#-KtC1C$Jun~>endstream
-endobj
-17 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 2041
->>
-stream
-Gb"/)9lo&I&A@sBi6iK%PG%[tfUHA$XZK;;8@6j93fHJ]9I.cS-te]M?\%%@6r9%jHLQ#52E2)-MoU6J&8t,P0gD-,T.U\$*MD<H:dc0.D@dObT\om2Jtm6SZoh8!j=-+sp9hHJFC7^(,s6j[,+]PU1JYL$;0mS"mRCCjJq^`q6WE5-fCme9B;=DGr*jc&hN!3Xq'e@MGB34fE^':6"^b*q_YX7>IU3!/_kQf'\;U-)QPise'J,*EM&Db##"mCbcsEu'Ca'r?bJuLI``K(SebJ4B2&`;Q/pD[]]^X")hf<t)K_$9MUD6s$8JWW$#d(CS4jDPloFfEDj>OV;pL0@VBsN&A_IR9T_^o,*nMHc2RjbXVY+1.;1hKr5SYfM/:F!h\h/C+(*g=H"cV5)@1YZZaV$3'MbG7IV1\AhsBnUA1*0L/:"k9&3U]K'n&`RQ?k=+\BdFJE3Nm_&mc$Bt#'@5Br?[>Pu*,1(_Yc`0Ao_/4Od93Xp`Y]8]O&::Of+3[Y!p#.Db^\lT$JL]igRXk)UW[cT3W'lCj6VOW9H#*IL:s<'P`6:]XOCa$'@6"JFTr2kQ^P(")l16mh\YlsJ)`bRYXIBL8\)p?V)ap<8T#cLM0(;E3Mkrp\;oh%Ae#.e2'K4Pg9s2-;3`);>8oR9\^@j^n\^Z?7(dgpl#cG>+*$1R/N&U\Msa:m<;Qp^A(JoF0ad>B7_N$OB>=1qg>)?tGI6Cj@-NgQ8YYS"anOk\gktFV(/;ptVXeqYOfpG:0UX%K317_'l^p3"blA=<a(7<d)'ekdVbS&'`'QGh/!V4W?cTWi\>\AW`=GhW17?]f<XD,oT1CnDJM=6*o7E/oX89ftGVWR%d/[*r5^Gc/R0j&eFLbM,282"`oPJFlV^%3^;h6V8`EZAR&?5;<\Hq3u?*0iP9R<A@/uC?%B/+UoPC^[>ch/JUlF?5c=QJ6?_+:fgrMrB49c/gXd]>`@-1T58>r]/ac;#LHU`ZC!4p]#LlR%Bflf-&Y;]fP0:ellhk[O]u^'$LT=A"2'TeEruB1nV2?*4jI-T2q$AMa#)U;Xb7=\=:=1lN-_K9?QcCub"H)Hc+F/Ius2O[gBibS!d(6u<otZUYtN>o%GlN/V5d)J>HEL%.@LiXR[J+BhqMKosa]I%ni>'E[2<S*dt30O?^A7.+L*SP4_>\_":+ne;3M_nJ3`_>k"m^%Vu%V]ZPq^-P[6:I,![\;sIjr#.HaE,=,6pR2SV9EusQJa[nF%6q&Z@G4>Mn]ub[$M)=`*cKh<fAuCjq.4,eX&%AlmWMs4@:;a+Y:+_P>#gKGWYVA?4Jd.KeBt[g<M[4;<c_$`]6P^QQ.6r+<`rX<bK=QMCTMtroGa:"CoXc1b/Ps$<t*2dO,1qF6F1N=A\?C:Cti&P/]9^)[]Fq/hR8\lMr83YZ.`MGiEB^EB`D+0Zm!:i/*9E6pA8D579BcInC02^,W;PKe@=o&=aKHs5HQCkH5DOt?[d#q3B6L&HV-kAoFT<mX(J_*R8#&B<i*s5r)2n1,IC56e&[h!L88]K3[RQ2m'"5Zjk'J2f3k1k%7Xe%r(8[@fp,qJ_s7&`@$m0\3_D*gdFJ2BQ!hflK[B3uFBOj@GMQ/"'p3eropC<$nY(CA.5U).+V69bW&*OREBpdU\4*<>lf;h%\l"WebPNIE&-SiFe5_(I&<T&f$WAm<akZPSD]=N/KdTM`&55/7op1OZR+t<Ije;sQ@Mtu1Lt?&RLM$3u1D'cLJ:oL?nEjM;0HT;)P9aQ:=s5uR,u#8]r*3ueVB@:T2F2HJ9Gj.`>IP3VW/*^dFMTe\;htjgS%*m>X,WrN\_5(i_D\AOJlg'B*OJQih'<.)9*[Ha"1B_]m3j"WKp-l^+!']"*c>KN.m!nK$GMid2jSYsqmL7p!!"mRmZ/gt&0>%mHha]h(UZOOD0uZ]82Ko7-,XoXIYo<1\l.q**`NQ;F4uL[qb"KV.]oMOHBllnCne4lf%'H4H:%jP]X1\S`nFGo)f&X]Cfssl?tJ0"kG-PNV!TWS-)1?XpX<),FS%4O39[+~>endstream
-endobj
-18 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 1842
->>
-stream
-Gb"/(>Ar7S'RnB33%kB>U>^>17IA>m]JW'>VQnjW:P3C4N]L=cA@kG0lUORQ0!RfK/iR1S@+[:G.3<q#+"udj!N\I1s.(bBIe)HQT*Z&9r[e\A3;=:Dp5f26,%XDu_%dAMkt1Q$W^)6IK"HPh^olaK-mQrIONihcDku@-?`;7!&=I_pFk=ZH@t/TL0g:65Z%$hD$DXZL`Q-*rjEpA\KE"R@I]#AHs3*pEo`)Q2HW?=L=ud;X?r(5h1f"PpMli\Dct[AZ*uiJFG!3RM^)6m!mXI'Q7`^n=4_KB^*Z923LR2GR>\E".<oN'Gm^$jJ9io0/.#q>(Y[0f@*9&*/YCh*+Mf]`S0[8&-ng$n0=aL*Y*2P.tm?f\$OC53o6"s?&:j=U8\>LZI@cgNn9$/-5,#OC]!]ZroU<5$?gK-m)n#aBmo*<mGg?\heL.rA]6:2YIoc_QOh"2d;.ZfoC/?$`45U@`^3ss6(No%F`**r6KTp/^^oNN0Wn+uQ.L+PDp!f?CBR0!J9h!JWo%bFk[WMH[O9%$%f-q:!SP7E`j<2XGN)pQ61)B.XH`Ku>lmXk)3qL2IPrOMac#W_CY=d"\j;5ui89QD()9t4cNFd&P?lT$FfS,-(9#aTa'>uhC`&\1c*Q'"q8)g,:%hf\9TfW@o1<Y[-.,L2k"$1iOgOhI4liT-YKR'sH^;$?lhg4o(EGkPWcW)^$V\g&eN(c_`nY7[IqTsifdS8pZ1I@8";h)b@Qj6ZP%bjON\;6A5pS<RMV5c*JIf=uFWNPHabM)l??96DnhbWD=^D626\aE7pg/AYA[T'?[`N8#/!j2j.&68Nb@*U:cfbWX<I)rt/5#bhIY013X'b^!q,<=o,6Ls8&i'>-9i7?CJ7gLJROq.V9u>kEeHJ85>HAajrs6<'PP%@H36iF[gJ!ikI0&5^VT.nI4^a9s5,m3')7ZUGEq?c1RTS^e'BFbWEhDjb5AjEa[nPfjEp-jen2YGMb"H/Sk'\=9fE@;I8BA&J4@[g-Jm@[,po!a'Nq$=^t['4O[B4)o]G--Us#*m@k>-ln&TrY;H3CBJ")Vulc<aJ(qRf#ZWte(Y1*#`]`\')+(=D2:-e"73PUBP,s`KFt%BG\JC9PL]$hql1*q<3<s]a;*s:b/T8c#Wsb_!_UW=<(C#$NC)e-=t-Dsa^[C9XkOPtgJ8G_ou@tO>Zl&`FZ2e![]rQ)Cua8%*4\d.`$o_/?.N'!MBl5h[?Zju>LmB'l4o\.\Zp<g]U\OfrCp?*M;29\di#ijGa/7:Wm5GAD8])M6`_ZKRT\6.Wei.%GKZs(;mYY*;aVqmbL)TiVaS_`QKN/u7E:J*,"f]u/44Pa?:@e[VKZIGf?.l2V>%MD=[l&tI%FY3ON\hBkKu,BiAOFQN5Ka"j;:inL07OV^FK)3<Da:3QR7SFBbGalPG0J'h2krt.&r:46k#e<@<MMk;3]eEFmUi>*p@K7'QnUj9@V,?CKhK9h&J(0ZmJF*)3`8q2VA+7_:hs:bf(o5+:0u<mG:'\E50oC%Ra!H3VBY1Z+B5e)ok&YZ@c##e4<ST)"e:+FV$L_A-I<M2In9('E'R6":,qcl<^3nlL[>S6R6MC:LPPkK,&5t:+HT)ilmpmgHg(G1oQgV"XPlRAR_l!fF)_())SX@W'8fb6hE%C>kS"2eKZShbV*+>q8c1<DSl9i's42e)03/iK"-Go2XpNfQ@G2h\#XoX>*:]sEjsoM2kDL*cKb_YqF2LCU;&=1fA0`QTD(?BLN=q&c,%#7\>i7rLMK"DBP"$Je_:qSg*S^9JbN+%.PE@gY-PK8\B<N'iG*.,Kl_3?MP[8uWV>IR'Ob2q*$"nd\?ar^~>endstream
-endobj
-19 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 1956
->>
-stream
-Gb"/h>BA7Q'Z],..F-,^YRG2fZ".Y-d`Xt#67ImuL8Q&UR+@AO`HHe&l&k?-f#C<%eBYkrKVH\QmA%GBd?4&/!N\J\pj]^T3:u15Ig?SmrWaPUEkn<_M1>$jJ?5pg(gOn=k=JJ*TfN`.Y&IW26t"Vf!)Z4Qb94JZ:er;f#Q@UaS-&5<LO8mF:QA6Kd<K\P%'NG(oC3EO:.LLle+*'+n3;O)<;V->5$e2KK>cLDh(Bo:/iC$/:_:[q_eNj_%2=_I6[MSoYrTeUBJHs;q"2PEGj:?N9VW3*j)W2L_+KasABWp[b<l.<Y0p^g%.\'I/Dqkro.Z01B9:rhGq`/tQmKqF7JJIWDkB<,cQUJM(Ek>^oM_,h`kcs@3?):q8!%,]#D1+0?\smtjc3=/c,34Qh0P<*/LFN-E<-QEn6EA8#ToWZi8SIIe09lk,HdM(^r3JO7Ht/@edK(uds3dnHPI2/ce9$Je9*aD[3gpE;R<-nQPZhpVnHsrV3V7t%ATuiIQ`Wu99'9HjH':6JV!'ufu[n9B5-p#GTSM:WZ%Yn=U5X?\_XG\#K_k'UEogMc,4cA)WPAI(O$GH,jA\/pJLnRchWJ$`8PJh-'uTH<*pCp/SoZK_As#%/h&mNh+,/d9mnI-"FJ+A\udW]6ki,Hej`-"_Pl4sn]cf'6o`&Q$99W;Oi*XechFGtf3;JcB*2L)YMO`+*(OsK(>gSC:StHD%KGjU]5g3IghS2Y*S2-:N;Fu]TR6RH-df\(_sBEebkksK#@#Y'8A?dS2?gNupZ2aBY#k.k3cmmbRb9?Y8RY1=6enMmqF[\DRF<k8gXTsbV)hPS*MG+WbaE39C87dEH5WMUTTjB:>UqiAik.LK7HX%&V^q?u=U%_3(KkF=O@>aEOVL:a/Jj.(Pu_AgU=ml$Z8Bk$9P:Lg9r4\tj-]/3*MG,fbFhuiFtBb]'JaC*XEG;LY*NX-Xj7k\7WGZBrOsjjXf,2h;U`K2eCMI!aC`P$Qe0HKV8@sJDGF%jg<P:$MnXj`R7+/7j'9jS`13]*,[s.M'2b[lSo3tP9JSS..ar5"H>c@j`mTs7ba,2k3)>_WF2cq`g"geAoIkDL)m)Xl&&,oH4ge$J.uI;[1e]ToHHaM7RoYngnCH&di35&8U(**2)Q;1jQ&K=[H^ggP[;?5QbibbA3?;67q)24[A$s/(FD]VS@'QA/dHCjZa%Pa$@`)@(\F+;.3I901mV@UZig<8&i,5S5!aRSbiY=.4Gf@-%71f=nhk^V'2.c7T3si*m]OdqIPr;ZG).d:kPta(n<nUSdF%b\6gGe(;Ra>n]V6"2@\o"O-PRp6l/ZUFFlF+!9!#Z7k)mQF2U)_:0W+o/(K7Q-\:mV9I'q0;f[cg!+DqjAE>p>q]gNbQ<DYqO?a1>V`9`-W8SXfQnkD(:3r;%,)roe;`)>ikr5af0R62V/ip;8H-+:l6KOQC7i#ci1kVJm3Gq'pfrpF%bt1-I(!X7T&XN$/=Mql,Sg`aK4*>Qa_4"P<VPF78"SH]u]>op=gt'(Ok<H[@@X^G#>Y;BTT0h?5o_rugasP"0$!)BeJ4DCCqsJj0YVSlX%Y(4^'iVeOU`m-!a"4=_5lE*d=N7%_=bFIa]3YbDl;N]Q<D'E2TEU`NO*J0@/(3-M$1&m/]3SppCK_*sMjO_)PKje9Raj9C7b+u_*-NX6@c*""/S$Z+t[Y)H*<-6Dr&HNZsaYa`3C.;=qtK15E\A!Iou(2_/o(Rk`@Q,rAf_!T3jHiecJ3dj-m"Xi'pN\uf8W=jG><2h_n^-udf_lZIXSOQ[Xh"p\\fBn)'R1+AhZl?6e?/*17n.W&Y@'2i\R"#DA'oBJ0P>`$6)j9K'pblR3(qFqG=^pI"XC96G;#4@>Oh6.R%@49_ms@=`/89fje[M[-\\=pCSQg;QM/0/*=]oTQe1PjGI<V?*D='UOg=h,'NO94df@H*/^qgP=#gpi~>endstream
-endobj
-20 0 obj
-<<
-/Filter [ /ASCII85Decode /FlateDecode ] /Length 1890
->>
-stream
-Gb!#]>>O!E'Ro4HS<qd3<UnAZ\*d0;/=TW@/N"%h<C4\H^r<QW?YGSqa6so'@OI0<Xf7U7GVlmN^,+YoF$--]n3`-6h@ec!J`$L'5T)Pj5_UQ#RDZ"FnE#1$4UhIi_)9EA/KB<N)Ps;S9[K_(9M9oU39;KBjR*"\UFcSn&gq<WX^Z<D9mo!h_;\pM3erRP>gAA5SCtmWDr?!IkDceE!C'lE6>/i"]@4\UK:<Vn#&2f=2qqlSYX,TI_JQ0A(?<!s/](r[/[Yj(iA6U8qrWDCZ^%*uY0t0e[N,N*`67)f#(C@5_tT#["##j%/7Mt@)p%?qf]<:E>(5[%-\u!ePoho17>tmUEOO#M7%a.g(iWuD(eh4d$#];bLa+m9UYESNOXImg']Z\jM.ZbXi_[:,1\@0.`_/7Hi$t#kGJG<>Kur\-1%3eGJ)g:p!H*7:R6$K=WC@TDKX(fKB?3=4>&UDe#fBPo&3^kPUoGW0)RAd/2K"N'NN*HrFWIfg3\6M<C(IA]l<+SqYcSn"0Jq@Y*8![29c-.F$)JOCT=jq<cn\H*AJ)OPaPL91*)DT-o9o1\9P5H>V.p2P<])KjWj[8T(BHio;"6PT[B'h[+L<bdJs8m+$KW,)=LD??>N%8T\>]OM31l_5>trU>.nMst/5BEJ>=1BT22dsK^m=c)j4>4)<T\k'JDMt<`_JcjKM>$CRpi`Bb7LM=^*u$Y4S5HtD82L&d*6tF*%k9;3f%PsK.*O)&=5E"&ZXE=U\ZrqEYAuD)TSMQO[3)1)8jT@pm*5oAk'!*BH0tJ!3oDHeZ"e6<6>G*\TbAg=Q:7J\'ORS/2Eej>R]X1a-+g9+["ns.e/iE4QM.!`\Ft.Ps1X+LhA-S37ddgihL>D1V!pg!8]*@LrM0X#LOsSFWS+e(\f,A;%2gloDB"u-!4.SC@'8df6u@EDL80O\uJr=*mJAhr2NY#9/1iFCK7@52<pu>Q'tlRql*1^/ZZ"Q;I+(i`pC)bZSlBt/W&2CYZh#bmT4N\Vc6]SgsXiCP&lLN:Oc!^/D;rZkT.S&l,gnREI'g>W!)_P:a40ng0ALe-/qU?Y!.TD(XRPlLZ>`0H3'43Z6P4FN5)a(:$8hV3X+([email protected]$heUD%;DqhQlpbIt<O4n"C_*'uNWhEcqgi'E)nE1\f>kicdpA=8B7Aj(O>hVqI]Mbh-HUJ--[^l<_<]n>MYmXm?SP:*l"<VpeOb"RDVVD:l41<Qu[>I,D#mS$f$9\Sh7C[\]J]!QZm<S9`>`b\?X&Hf@anc'fQcF:_n@E(mHe4UT<Oe`)TE:`E[:4>pr`q:D@OuSO#\!u`/>>QXUZJ8IS6>d(<Y(mJN!'PM`rAjeK[b3<F'gJX*[e4I(+*_H8r8;*2IW.^e1lD!tYM2aUX,%W-9,Kr=e3^nc;bm;HX&mhWXch?0m^MG$PtLOC)SG'90Tg&jAh!"udZd6I=>9oRR@>V9JU8'n=ZP:f$/DVm59pT@\n95d3C'/V+_[!nf-K9b06s!=D=UYkIH8f/i:RUlm.m"%Y<sA2)7mY2g%/,Q+=/g0PfJ%Vo$In>H.Z^>Y'6urnhCUrAI=:+$N0DX%ueY:*kHUk\7'??PW[)i5&qtRFoRoh\'#iEoCBimSpoa:H;45ICY-h.?)0!JdFZ;n?8m9]P?W`Q+9?@b2K]J@(pN_4q\r7Rk5Eo2]M.'.fP=NTRUCC(l=pWQostf.>V#'Vc')=:8"DNd66@nBGf4,)r`(U=*i9NaeX^(shZ5Ts<%57\b#OsB0Uoe/gE;a4Le--?P;=4JnX:&e;b#Ft@qm%M<Bf^Ed!p&iJ\!(LRs7A]f3742S7i\3<e\$^+X@Fl,pt++:MGpA0Kr@_KMUef.*kmQVN"IhIC$_)Y5"$g1KQ!_i'5Ig+^4~>endstream
-endobj
-xref
-0 21
-0000000000 65535 f 
-0000000073 00000 n 
-0000000135 00000 n 
-0000000242 00000 n 
-0000000354 00000 n 
-0000000559 00000 n 
-0000000674 00000 n 
-0000000879 00000 n 
-0000001084 00000 n 
-0000001289 00000 n 
-0000001494 00000 n 
-0000001578 00000 n 
-0000001784 00000 n 
-0000001854 00000 n 
-0000002138 00000 n 
-0000002229 00000 n 
-0000004328 00000 n 
-0000005597 00000 n 
-0000007730 00000 n 
-0000009664 00000 n 
-0000011712 00000 n 
-trailer
-<<
-/ID 
-[<2a85d7c14d3e5f84b4a14db13320b611><2a85d7c14d3e5f84b4a14db13320b611>]
-% ReportLab generated PDF document -- digest (http://www.reportlab.com)
-
-/Info 13 0 R
-/Root 12 0 R
-/Size 21
->>
-startxref
-13694
-%%EOF

detector/__init__.py

@@ -1,20 +0,0 @@
-# DEPENDENCIES
-from detector.attribution import AIModel
-from detector.ensemble import EnsembleResult
-from detector.attribution import ModelAttributor
-from detector.ensemble import EnsembleClassifier
-from detector.orchestrator import DetectionResult
-from detector.attribution import AttributionResult
-from detector.orchestrator import DetectionOrchestrator
-
-
-
-__all__ = ["AIModel",
-           "EnsembleResult",
-           "DetectionResult",
-           "ModelAttributor",
-           "AttributionResult",
-           "EnsembleClassifier",
-           "DetectionOrchestrator",
-          ]
-        

detector/attribution.py

@@ -1,962 +0,0 @@
-# DEPENDENCIES
-import re
-import numpy as np
-from enum import Enum
-from typing import Any
-from typing import Dict
-from typing import List
-from typing import Tuple 
-from loguru import logger
-from typing import Optional 
-from dataclasses import dataclass
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
-from processors.text_processor import ProcessedText
-
-
-
-class AIModel(Enum):
-    """
-    Supported AI models for attribution - ALIGNED WITH DOCUMENTATION
-    """
-    GPT_3_5         = "gpt-3.5-turbo"
-    GPT_4           = "gpt-4"
-    GPT_4_TURBO     = "gpt-4-turbo"
-    GPT_4o          = "gpt-4o"
-    CLAUDE_3_OPUS   = "claude-3-opus"
-    CLAUDE_3_SONNET = "claude-3-sonnet"
-    CLAUDE_3_HAIKU  = "claude-3-haiku"
-    GEMINI_PRO      = "gemini-pro"
-    GEMINI_ULTRA    = "gemini-ultra"
-    GEMINI_FLASH    = "gemini-flash"
-    LLAMA_2         = "llama-2"
-    LLAMA_3         = "llama-3"
-    MISTRAL         = "mistral"
-    MIXTRAL         = "mixtral"
-    DEEPSEEK_CHAT   = "deepseek-chat"
-    DEEPSEEK_CODER  = "deepseek-coder"
-    HUMAN           = "human"
-    UNKNOWN         = "unknown"
-
-
-@dataclass
-class AttributionResult:
-    """
-    Result of AI model attribution
-    """
-    predicted_model     : AIModel
-    confidence          : float
-    model_probabilities : Dict[str, float]
-    reasoning           : List[str]
-    fingerprint_matches : Dict[str, int]
-    domain_used         : Domain
-    metric_contributions: Dict[str, float]
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"predicted_model"     : self.predicted_model.value,
-                "confidence"          : round(self.confidence, 4),
-                "model_probabilities" : {model: round(prob, 4) for model, prob in self.model_probabilities.items()},
-                "reasoning"           : self.reasoning,
-                "fingerprint_matches" : self.fingerprint_matches,
-                "domain_used"         : self.domain_used.value,
-                "metric_contributions": {metric: round(contrib, 4) for metric, contrib in self.metric_contributions.items()},
-               }
-
-
-class ModelAttributor:
-    """
-    Model attribution
-    
-    FEATURES:
-    - Domain-aware calibration
-    - 6-metric ensemble integration  
-    - Confidence-weighted aggregation
-    - Explainable reasoning
-    """
-    # Metric weights from technical specification
-    METRIC_WEIGHTS           = {"perplexity"                   : 0.25,  
-                                "structural"                   : 0.15,   
-                                "semantic_analysis"            : 0.15,  
-                                "entropy"                      : 0.20,  
-                                "linguistic"                   : 0.15,  
-                                "multi_perturbation_stability" : 0.10,  
-                               }
-    
-    # Domain-aware model patterns for ALL 16 DOMAINS
-    DOMAIN_MODEL_PREFERENCES = {Domain.GENERAL       : [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET, AIModel.GEMINI_PRO, AIModel.GPT_3_5],
-                                Domain.ACADEMIC      : [AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.GEMINI_ULTRA, AIModel.GPT_4_TURBO],
-                                Domain.TECHNICAL_DOC : [AIModel.GPT_4_TURBO, AIModel.CLAUDE_3_SONNET, AIModel.LLAMA_3, AIModel.GPT_4],
-                                Domain.AI_ML         : [AIModel.GPT_4_TURBO, AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.DEEPSEEK_CODER],
-                                Domain.SOFTWARE_DEV  : [AIModel.GPT_4_TURBO, AIModel.DEEPSEEK_CODER, AIModel.CLAUDE_3_SONNET, AIModel.GPT_4],
-                                Domain.ENGINEERING   : [AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.GPT_4_TURBO, AIModel.LLAMA_3],
-                                Domain.SCIENCE       : [AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.GEMINI_ULTRA, AIModel.GPT_4_TURBO],
-                                Domain.BUSINESS      : [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET, AIModel.GEMINI_PRO, AIModel.GPT_3_5],
-                                Domain.LEGAL         : [AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.GPT_4_TURBO, AIModel.CLAUDE_3_SONNET],
-                                Domain.MEDICAL       : [AIModel.GPT_4, AIModel.CLAUDE_3_OPUS, AIModel.GEMINI_ULTRA, AIModel.GPT_4_TURBO],
-                                Domain.JOURNALISM    : [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET, AIModel.GEMINI_PRO, AIModel.GPT_3_5],
-                                Domain.CREATIVE      : [AIModel.CLAUDE_3_OPUS, AIModel.GPT_4, AIModel.GEMINI_PRO, AIModel.CLAUDE_3_SONNET],
-                                Domain.MARKETING     : [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET, AIModel.GEMINI_PRO, AIModel.GPT_3_5],
-                                Domain.SOCIAL_MEDIA  : [AIModel.GPT_3_5, AIModel.GEMINI_PRO, AIModel.DEEPSEEK_CHAT, AIModel.LLAMA_3],
-                                Domain.BLOG_PERSONAL : [AIModel.CLAUDE_3_SONNET, AIModel.GPT_4, AIModel.GEMINI_PRO, AIModel.GPT_3_5],
-                                Domain.TUTORIAL      : [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET, AIModel.GEMINI_PRO, AIModel.GPT_4_TURBO],
-                               }
-
-    # Model-specific fingerprints with comprehensive patterns
-    MODEL_FINGERPRINTS = {AIModel.GPT_3_5       : {"phrases"              : ["as an ai language model",
-                                                                             "i don't have personal opinions",
-                                                                             "it's important to note that",
-                                                                             "it's worth noting that", 
-                                                                             "keep in mind that",
-                                                                             "bear in mind that",
-                                                                             "i should point out",
-                                                                             "it's also important to",
-                                                                             "additionally, it's worth",
-                                                                             "furthermore, it should be",
-                                                                             "i cannot provide",
-                                                                             "i'm unable to",
-                                                                             "i don't have the ability",
-                                                                             "based on the information",
-                                                                             "according to the context",
-                                                                            ],
-                                                   "sentence_starters"    : ["however,",
-                                                                             "additionally,",
-                                                                             "furthermore,",
-                                                                             "moreover,",
-                                                                             "in conclusion,",
-                                                                             "therefore,",
-                                                                             "consequently,",
-                                                                             "as a result,",
-                                                                             "in summary,",
-                                                                             "ultimately,",
-                                                                            ],
-                                                   "structural_patterns"  : ["firstly", 
-                                                                             "secondly", 
-                                                                             "thirdly",
-                                                                             "on one hand", 
-                                                                             "on the other hand",
-                                                                             "in terms of", 
-                                                                             "with regard to",
-                                                                            ],
-                                                   "punctuation_patterns" : {"em_dash_frequency"     : (0.01, 0.03),
-                                                                             "semicolon_frequency"   : (0.005, 0.015),
-                                                                             "parentheses_frequency" : (0.01, 0.04),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length"     : (18, 25),
-                                                                             "transition_word_density" : (0.08, 0.15),
-                                                                             "formality_score"         : (0.7, 0.9),
-                                                                             "hedging_language"        : (0.05, 0.12),
-                                                                            }
-                                                  },
-                          AIModel.GPT_4         : {"phrases"              : ["it's important to note that",
-                                                                             "it's worth mentioning that",
-                                                                             "to clarify this point",
-                                                                             "in other words,",
-                                                                             "that being said,",
-                                                                             "in essence,",
-                                                                             "fundamentally,",
-                                                                             "at its core,",
-                                                                             "from a broader perspective",
-                                                                             "when considering",
-                                                                             "this suggests that",
-                                                                             "this implies that",
-                                                                             "it follows that",
-                                                                             "consequently,",
-                                                                             "accordingly,",
-                                                                            ],
-                                                   "sentence_starters"    : ["interestingly,",
-                                                                             "notably,",
-                                                                             "crucially,",
-                                                                             "essentially,",
-                                                                             "ultimately,",
-                                                                             "significantly,",
-                                                                             "importantly,",
-                                                                             "remarkably,",
-                                                                             "surprisingly,",
-                                                                            ],
-                                                   "structural_patterns"  : ["in light of", 
-                                                                             "with respect to", 
-                                                                             "pertaining to",
-                                                                             "as evidenced by", 
-                                                                             "as indicated by", 
-                                                                             "as suggested by",
-                                                                            ],
-                                                   "punctuation_patterns" : {"em_dash_frequency"  : (0.02, 0.05),
-                                                                             "colon_frequency"     : (0.01, 0.03),
-                                                                             "semicolon_frequency" : (0.01, 0.02),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length"       : (20, 28),
-                                                                             "vocabulary_sophistication" : (0.7, 0.9),
-                                                                             "conceptual_density"        : (0.6, 0.85),
-                                                                             "analytical_depth"          : (0.65, 0.9),
-                                                                            }
-                                                  },
-                          AIModel.CLAUDE_3_OPUS : {"phrases"              : ["i'd be glad to",
-                                                                             "i'm happy to help",
-                                                                             "let me explain this",
-                                                                             "to clarify this further",
-                                                                             "in this context,",
-                                                                             "from this perspective,",
-                                                                             "building on that point",
-                                                                             "expanding on this idea",
-                                                                             "delving deeper into",
-                                                                             "to elaborate further",
-                                                                             "it's worth considering",
-                                                                             "this raises the question",
-                                                                             "this highlights the importance",
-                                                                             "this underscores the need",
-                                                                            ],
-                                                   "sentence_starters"    : ["certainly,",
-                                                                             "indeed,",
-                                                                             "particularly,",
-                                                                             "specifically,",
-                                                                             "notably,",
-                                                                             "importantly,",
-                                                                             "interestingly,",
-                                                                             "crucially,",
-                                                                            ],
-                                                   "structural_patterns"  : ["in other words", 
-                                                                             "to put it differently", 
-                                                                             "that is to say",
-                                                                             "for instance",
-                                                                             "for example", 
-                                                                             "as an illustration",
-                                                                            ],
-                                                   "punctuation_patterns" : {"em_dash_frequency"   : (0.015, 0.04),
-                                                                             "parenthetical_usage" : (0.02, 0.06),
-                                                                             "colon_frequency"     : (0.008, 0.025),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length" : (17, 24),
-                                                                             "nuanced_language"    : (0.6, 0.85),
-                                                                             "explanatory_depth"   : (0.7, 0.95),
-                                                                             "conceptual_clarity"  : (0.65, 0.9),
-                                                                            }
-                                                  },
-                          AIModel.GEMINI_PRO    : {"phrases"              : ["here's what you need to know",
-                                                                             "here's how it works",
-                                                                             "let's explore this",
-                                                                             "let's look at this",
-                                                                             "consider this example",
-                                                                             "think of it this way",
-                                                                             "imagine if you will",
-                                                                             "picture this scenario",
-                                                                             "to break it down",
-                                                                             "in simple terms",
-                                                                             "put simply,",
-                                                                             "basically,",
-                                                                             "the key point is",
-                                                                             "the main idea here",
-                                                                            ],
-                                                   "sentence_starters"    : ["now,",
-                                                                             "so,",
-                                                                             "well,",
-                                                                             "basically,",
-                                                                             "essentially,",
-                                                                             "actually,",
-                                                                             "technically,",
-                                                                             "practically,",
-                                                                            ],
-                                                   "structural_patterns"  : ["on that note", 
-                                                                             "speaking of which", 
-                                                                             "by the way",
-                                                                             "as a side note", 
-                                                                             "incidentally", 
-                                                                             "in any case",
-                                                                            ],
-                                                   "punctuation_patterns" : {"exclamation_frequency" : (0.01, 0.03),
-                                                                             "question_frequency"    : (0.02, 0.05),
-                                                                             "ellipsis_frequency"    : (0.005, 0.02),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length" : (15, 22),
-                                                                             "conversational_tone" : (0.5, 0.8),
-                                                                             "accessibility_score" : (0.6, 0.9),
-                                                                             "engagement_level"    : (0.55, 0.85),
-                                                                            }
-                                                  },
-                          AIModel.LLAMA_3       : {"phrases"              : ["it's worth noting",
-                                                                             "it's important to understand",
-                                                                             "this means that",
-                                                                             "this indicates that",
-                                                                             "this shows that",
-                                                                             "this demonstrates that",
-                                                                             "based on this,",
-                                                                             "given this context",
-                                                                             "in this case,",
-                                                                             "for this reason",
-                                                                             "as such,",
-                                                                             "therefore,",
-                                                                            ],
-                                                   "sentence_starters"    : ["first,",
-                                                                             "second,",
-                                                                             "third,",
-                                                                             "next,",
-                                                                             "then,",
-                                                                             "finally,",
-                                                                             "overall,",
-                                                                             "in general,",
-                                                                            ],
-                                                   "structural_patterns"  : ["in addition", 
-                                                                             "moreover",
-                                                                             "furthermore",
-                                                                             "however", 
-                                                                             "nevertheless", 
-                                                                             "nonetheless",
-                                                                            ],
-                                                   "punctuation_patterns" : {"comma_frequency"       : (0.08, 0.15),
-                                                                             "period_frequency"      : (0.06, 0.12),
-                                                                             "conjunction_frequency" : (0.05, 0.1),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length"    : (16, 23),
-                                                                             "directness_score"       : (0.6, 0.85),
-                                                                             "clarity_score"          : (0.65, 0.9),
-                                                                             "structural_consistency" : (0.7, 0.95),
-                                                                            }
-                                                  },
-                          AIModel.DEEPSEEK_CHAT : {"phrases"              : ["i understand you're asking",
-                                                                             "let me help you with that",
-                                                                             "i can assist you with",
-                                                                             "regarding your question",
-                                                                             "to answer your question",
-                                                                             "in response to your query",
-                                                                             "based on your request",
-                                                                             "as per your question",
-                                                                             "concerning your inquiry",
-                                                                             "with respect to your question",
-                                                                             "i'll do my best to",
-                                                                             "i'll try to help you",
-                                                                             "allow me to explain",
-                                                                             "let me break it down",
-                                                                            ],
-                                                   "sentence_starters"    : ["well,",
-                                                                             "okay,",
-                                                                             "so,",
-                                                                             "now,",
-                                                                             "first,",
-                                                                             "actually,",
-                                                                             "specifically,",
-                                                                             "generally,",
-                                                                            ],
-                                                   "structural_patterns"  : ["in other words", 
-                                                                             "to put it simply", 
-                                                                             "that is",
-                                                                             "for example",
-                                                                             "for instance", 
-                                                                             "such as",
-                                                                            ],
-                                                   "punctuation_patterns" : {"comma_frequency"    : (0.07, 0.14),
-                                                                             "period_frequency"   : (0.05, 0.11),
-                                                                             "question_frequency" : (0.01, 0.04),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length" : (14, 21),
-                                                                             "helpfulness_tone"    : (0.6, 0.9),
-                                                                             "explanatory_style"   : (0.55, 0.85),
-                                                                             "user_focus"          : (0.65, 0.95),
-                                                                            }
-                                                  },
-                          AIModel.MIXTRAL       : {"phrases"              : ["it should be noted that",
-                                                                             "it is important to recognize",
-                                                                             "this suggests that",
-                                                                             "this implies that",
-                                                                             "this indicates that",
-                                                                             "from this we can see",
-                                                                             "based on this analysis",
-                                                                             "considering these points",
-                                                                             "taking into account",
-                                                                             "in light of these factors",
-                                                                            ],
-                                                   "sentence_starters"    : ["however,",
-                                                                             "moreover,",
-                                                                             "furthermore,",
-                                                                             "additionally,",
-                                                                             "conversely,",
-                                                                             "similarly,",
-                                                                             "likewise,",
-                                                                            ],
-                                                   "structural_patterns"  : ["on the one hand", 
-                                                                             "on the other hand",
-                                                                             "in contrast", 
-                                                                             "by comparison",
-                                                                             "as opposed to",
-                                                                             "rather than",
-                                                                            ],
-                                                   "punctuation_patterns" : {"semicolon_frequency"   : (0.008, 0.02),
-                                                                             "colon_frequency"       : (0.006, 0.018),
-                                                                             "parentheses_frequency" : (0.012, 0.035),
-                                                                            },
-                                                   "style_markers"        : {"avg_sentence_length"  : (19, 26),
-                                                                             "analytical_tone"      : (0.65, 0.9),
-                                                                             "comparative_language" : (0.5, 0.8),
-                                                                             "balanced_perspective" : (0.6, 0.85),
-                                                                            }
-                                                  }
-                         }
-
-    
-    def __init__(self):
-        """
-        Initialize model attributor with domain awareness
-        """
-        self.is_initialized = False
-        logger.info("ModelAttributor initialized with domain-aware calibration")
-    
-
-    def initialize(self) -> bool:
-        """
-        Initialize attribution system
-        """
-        try:
-            self.is_initialized = True
-            logger.success("Model attribution system initialized with metric ensemble")
-            return True
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize attribution system: {repr(e)}")
-            return False
-    
-
-    def attribute(self, text: str, processed_text: Optional[ProcessedText] = None, metric_results: Optional[Dict[str, MetricResult]] = None,
-                  domain: Domain = Domain.GENERAL) -> AttributionResult:
-        """
-        Attribute text to specific AI model with domain awareness
-        
-        Arguments:
-        ----------
-            text           { str }           : Input text
-
-            processed_text { ProcessedText } : Processed text metadata
-            
-            metric_results { dict }          : Results from 6 core metrics
-            
-            domain         { Domain }        : Text domain for calibration
-            
-        Returns:
-        --------
-            { AttributionResult }            : Attribution result with domain context
-        """
-        try:
-            # Get domain-specific model preferences
-            domain_preferences                    = self.DOMAIN_MODEL_PREFERENCES.get(domain, [AIModel.GPT_4, AIModel.CLAUDE_3_SONNET])
-            
-            # Fingerprint analysis
-            fingerprint_scores                    = self._calculate_fingerprint_scores(text   = text,
-                                                                                       domain = domain,
-                                                                                      )
-            
-            # Statistical pattern analysis
-            statistical_scores                    = self._analyze_statistical_patterns(text   = text, 
-                                                                                       domain = domain,
-                                                                                      )
-            
-            # Metric-based attribution using all 6 metrics
-            metric_scores                         = self._analyze_metric_patterns(metric_results = metric_results, domain = domain) if metric_results else {}
-            
-            # Ensemble Combination
-            combined_scores, metric_contributions = self._combine_attribution_scores(fingerprint_scores = fingerprint_scores,
-                                                                                     statistical_scores = statistical_scores,
-                                                                                     metric_scores      = metric_scores,
-                                                                                     domain             = domain,
-                                                                                    )
-            
-            # Domain-aware prediction : Always show the actual highest probability model
-            predicted_model, confidence           = self._make_domain_aware_prediction(combined_scores    = combined_scores,
-                                                                                       domain             = domain,
-                                                                                       domain_preferences = domain_preferences,
-                                                                                      )
-            
-            # Reasoning with domain context
-            reasoning                             = self._generate_detailed_reasoning(predicted_model      = predicted_model,
-                                                                                      confidence           = confidence,
-                                                                                      domain               = domain,
-                                                                                      metric_contributions = metric_contributions,
-                                                                                      combined_scores      = combined_scores,
-                                                                                     )
-            
-            return AttributionResult(predicted_model      = predicted_model,
-                                     confidence           = confidence,
-                                     model_probabilities  = combined_scores,
-                                     reasoning            = reasoning,
-                                     fingerprint_matches  = self._get_top_fingerprints(fingerprint_scores),
-                                     domain_used          = domain,
-                                     metric_contributions = metric_contributions,
-                                    )
-            
-        except Exception as e:
-            logger.error(f"Error in model attribution: {repr(e)}")
-            return self._create_unknown_result(domain)
-
-
-    def _calculate_fingerprint_scores(self, text: str, domain: Domain) -> Dict[AIModel, float]:
-        """
-        Calculate fingerprint match scores with domain calibration - for all domains
-        """
-        scores             = {model: 0.0 for model in AIModel if model not in [AIModel.HUMAN, AIModel.UNKNOWN]}
-        
-        # Adjust sensitivity based on all domains
-        domain_sensitivity = {Domain.GENERAL       : 1.00,   
-                              Domain.ACADEMIC      : 1.20,   
-                              Domain.CREATIVE      : 0.90,   
-                              Domain.AI_ML         : 1.15,  
-                              Domain.SOFTWARE_DEV  : 1.15,
-                              Domain.TECHNICAL_DOC : 1.10,   
-                              Domain.ENGINEERING   : 1.10,   
-                              Domain.SCIENCE       : 1.20,   
-                              Domain.BUSINESS      : 1.05,  
-                              Domain.LEGAL         : 1.25,  
-                              Domain.MEDICAL       : 1.20,   
-                              Domain.JOURNALISM    : 1.00,  
-                              Domain.MARKETING     : 0.95, 
-                              Domain.SOCIAL_MEDIA  : 0.80,   
-                              Domain.BLOG_PERSONAL : 0.90,   
-                              Domain.TUTORIAL      : 1.00,  
-                             }
-        
-        sensitivity        = domain_sensitivity.get(domain, 1.0)
-        text_lower         = text.lower()
-        
-        for model, fingerprints in self.MODEL_FINGERPRINTS.items():
-            match_count  = 0
-            total_checks = 0
-            
-            # Check phrase matches
-            if ("phrases" in fingerprints):
-                for phrase in fingerprints["phrases"]:
-                    if (phrase in text_lower):
-                        match_count += 3
-                    
-                    total_checks += 1
-            
-            # Check sentence starters
-            if ("sentence_starters" in fingerprints):
-                sentences = re.split(r'[.!?]+', text)
-                for sentence in sentences:
-                    sentence = sentence.strip().lower()
-                    for starter in fingerprints["sentence_starters"]:
-                        if (sentence.startswith(starter)):
-                            match_count += 2
-                            break
-                
-                total_checks += len(sentences)
-            
-            # Check structural patterns
-            if ("structural_patterns" in fingerprints):
-                for pattern in fingerprints["structural_patterns"]:
-                    if (pattern in text_lower):
-                        match_count += 2
-                    
-                    total_checks += 1
-            
-            # Calculate normalized score
-            if (total_checks > 0):
-                base_score    = min(1.0, match_count / (total_checks * 0.5))
-                # Apply domain calibration
-                scores[model] = min(1.0, base_score * sensitivity)
-        
-        return scores
-
-
-    def _analyze_statistical_patterns(self, text: str, domain: Domain) -> Dict[AIModel, float]:
-        """
-        Analyze statistical patterns to identify model with domain awareness
-        """
-        scores    = {model: 0.3 for model in AIModel if model not in [AIModel.HUMAN, AIModel.UNKNOWN]}
-        
-        # Calculate text statistics
-        sentences = re.split(r'[.!?]+', text)
-        sentences = [s.strip() for s in sentences if s.strip()]
-        words     = text.split()
-        
-        if not sentences or not words:
-            return scores
-        
-        # Basic statistics
-        avg_sentence_length = len(words) / len(sentences)
-        word_count          = len(words)
-        sentence_count      = len(sentences)
-        
-        # Punctuation frequencies
-        em_dash_freq        = text.count('—') / word_count if word_count else 0
-        semicolon_freq      = text.count(';') / word_count if word_count else 0
-        colon_freq          = text.count(':') / word_count if word_count else 0
-        comma_freq          = text.count(',') / word_count if word_count else 0
-        question_freq       = text.count('?') / sentence_count if sentence_count else 0
-        exclamation_freq    = text.count('!') / sentence_count if sentence_count else 0
-        
-        # DOMAIN-AWARE: Adjust expectations based on domains
-        domain_adjustments  = {Domain.GENERAL       : 1.00,
-                               Domain.ACADEMIC      : 1.10,   
-                               Domain.CREATIVE      : 0.95, 
-                               Domain.AI_ML         : 1.05,  
-                               Domain.SOFTWARE_DEV  : 1.05, 
-                               Domain.TECHNICAL_DOC : 1.05, 
-                               Domain.ENGINEERING   : 1.05, 
-                               Domain.SCIENCE       : 1.08,  
-                               Domain.BUSINESS      : 1.00,  
-                               Domain.LEGAL         : 1.12,  
-                               Domain.MEDICAL       : 1.08,  
-                               Domain.JOURNALISM    : 0.95,  
-                               Domain.MARKETING     : 0.92,  
-                               Domain.SOCIAL_MEDIA  : 0.85,  
-                               Domain.BLOG_PERSONAL : 0.95, 
-                               Domain.TUTORIAL      : 1.00, 
-                              }
-        
-        domain_factor       = domain_adjustments.get(domain, 1.0)
-        
-        # Compare against model fingerprints
-        for model, fingerprints in self.MODEL_FINGERPRINTS.items():
-            if ("style_markers" not in fingerprints) or ("punctuation_patterns" not in fingerprints):
-                continue
-            
-            style       = fingerprints["style_markers"]
-            punct       = fingerprints["punctuation_patterns"]
-            match_score = 0.3
-            
-            # Check sentence length with domain adjustment
-            if ("avg_sentence_length" in style):
-                min_len, max_len = style["avg_sentence_length"]
-                adjusted_min     = min_len * domain_factor
-                adjusted_max     = max_len * domain_factor
-                
-                if (adjusted_min <= avg_sentence_length <= adjusted_max):
-                    match_score += 0.25
-            
-            # Check punctuation patterns
-            punctuation_checks = [("em_dash_frequency", em_dash_freq),
-                                  ("semicolon_frequency", semicolon_freq),
-                                  ("colon_frequency", colon_freq),
-                                  ("comma_frequency", comma_freq),
-                                  ("question_frequency", question_freq),
-                                  ("exclamation_frequency", exclamation_freq),
-                                 ]
-            
-            for pattern_name, observed_freq in punctuation_checks:
-                if (pattern_name in punct):
-                    min_freq, max_freq = punct[pattern_name]
-
-                    if (min_freq <= observed_freq <= max_freq):
-                        match_score += 0.08
-            
-            scores[model] = min(1.0, match_score)
-        
-        return scores
-
-
-    def _analyze_metric_patterns(self, metric_results: Dict[str, MetricResult], domain: Domain) -> Dict[AIModel, float]:
-        """
-        Use all 6 metrics with proper weights for attribution
-        """
-        scores                = {model: 0.0 for model in AIModel if model not in [AIModel.HUMAN, AIModel.UNKNOWN]}
-        
-        if not metric_results:
-            return scores
-        
-        # DOMAIN-AWARE: Adjust metric sensitivity based on domain 
-        domain_metric_weights = {Domain.GENERAL       : {"perplexity": 1.0, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.0, "linguistic": 1.0, "multi_perturbation_stability": 1.0},
-                                 Domain.ACADEMIC      : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.3, "multi_perturbation_stability": 0.8},
-                                 Domain.TECHNICAL_DOC : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.1, "multi_perturbation_stability": 0.8},
-                                 Domain.AI_ML         : {"perplexity": 1.3, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.2, "multi_perturbation_stability": 0.8},
-                                 Domain.SOFTWARE_DEV  : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.0, "multi_perturbation_stability": 0.9},
-                                 Domain.ENGINEERING   : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.2, "multi_perturbation_stability": 0.8},
-                                 Domain.SCIENCE       : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.3, "multi_perturbation_stability": 0.8},
-                                 Domain.BUSINESS      : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.2, "linguistic": 1.1, "multi_perturbation_stability": 0.9},
-                                 Domain.LEGAL         : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.3, "linguistic": 1.3, "multi_perturbation_stability": 0.8},
-                                 Domain.MEDICAL       : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.2, "multi_perturbation_stability": 0.8},
-                                 Domain.JOURNALISM    : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.1, "linguistic": 1.1, "multi_perturbation_stability": 0.9},
-                                 Domain.CREATIVE      : {"perplexity": 0.9, "structural": 0.9, "entropy": 1.2, "semantic_analysis": 1.0, "linguistic": 1.3, "multi_perturbation_stability": 0.9},
-                                 Domain.MARKETING     : {"perplexity": 1.0, "structural": 1.0, "entropy": 1.1, "semantic_analysis": 1.1, "linguistic": 1.2, "multi_perturbation_stability": 0.8},
-                                 Domain.SOCIAL_MEDIA  : {"perplexity": 1.0, "structural": 0.8, "entropy": 1.3, "semantic_analysis": 0.9, "linguistic": 0.9, "multi_perturbation_stability": 0.9},
-                                 Domain.BLOG_PERSONAL : {"perplexity": 1.0, "structural": 0.9, "entropy": 1.2, "semantic_analysis": 1.0, "linguistic": 1.1, "multi_perturbation_stability": 0.8},
-                                 Domain.TUTORIAL      : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.1, "linguistic": 1.1, "multi_perturbation_stability": 0.9},
-                                }
-        
-        domain_weights        = domain_metric_weights.get(domain, domain_metric_weights[Domain.GENERAL])
-        
-        # PERPLEXITY ANALYSIS (25% weight)
-        if ("perplexity" in metric_results):
-            perplexity_result  = metric_results["perplexity"]
-            overall_perplexity = perplexity_result.details.get("overall_perplexity", 50)
-            domain_weight      = domain_weights.get("perplexity", 1.0)
-            
-            # GPT models typically have lower perplexity
-            if (overall_perplexity < 25):
-                scores[AIModel.GPT_4]       += 0.6 * self.METRIC_WEIGHTS["perplexity"] * domain_weight
-                scores[AIModel.GPT_4_TURBO] += 0.5 * self.METRIC_WEIGHTS["perplexity"] * domain_weight
-
-            elif (overall_perplexity < 35):
-                scores[AIModel.GPT_3_5]    += 0.4 * self.METRIC_WEIGHTS["perplexity"] * domain_weight
-                scores[AIModel.GEMINI_PRO] += 0.3 * self.METRIC_WEIGHTS["perplexity"] * domain_weight
-        
-        # STRUCTURAL ANALYSIS (15% weight)
-        if ("structural" in metric_results):
-            structural_result = metric_results["structural"]
-            burstiness        = structural_result.details.get("burstiness_score", 0.5)
-            uniformity        = structural_result.details.get("length_uniformity", 0.5)
-            domain_weight     = domain_weights.get("structural", 1.0)
-            
-            # Claude models show more structural consistency
-            if (uniformity > 0.7):
-                scores[AIModel.CLAUDE_3_OPUS]   += 0.5 * self.METRIC_WEIGHTS["structural"] * domain_weight
-                scores[AIModel.CLAUDE_3_SONNET] += 0.4 * self.METRIC_WEIGHTS["structural"] * domain_weight
-        
-        # SEMANTIC ANALYSIS (15% weight)
-        if ("semantic_analysis" in metric_results):
-            semantic_result = metric_results["semantic_analysis"]
-            coherence       = semantic_result.details.get("coherence_score", 0.5)
-            consistency     = semantic_result.details.get("consistency_score", 0.5)
-            domain_weight   = domain_weights.get("semantic_analysis", 1.0)
-            
-            # GPT-4 shows exceptional semantic coherence
-            if (coherence > 0.8):
-                scores[AIModel.GPT_4]       += 0.7 * self.METRIC_WEIGHTS["semantic_analysis"] * domain_weight
-                scores[AIModel.GPT_4_TURBO] += 0.6 * self.METRIC_WEIGHTS["semantic_analysis"] * domain_weight
-        
-        # ENTROPY ANALYSIS (20% weight)
-        if ("entropy" in metric_results):
-            entropy_result            = metric_results["entropy"]
-            token_diversity           = entropy_result.details.get("token_diversity", 0.5)
-            sequence_unpredictability = entropy_result.details.get("sequence_unpredictability", 0.5)
-            domain_weight             = domain_weights.get("entropy", 1.0)
-            
-            # Higher entropy diversity suggests more sophisticated models
-            if (token_diversity > 0.7):
-                scores[AIModel.CLAUDE_3_OPUS] += 0.6 * self.METRIC_WEIGHTS["entropy"] * domain_weight
-                scores[AIModel.GPT_4]         += 0.5 * self.METRIC_WEIGHTS["entropy"] * domain_weight
-        
-        # LINGUISTIC ANALYSIS (15% weight)
-        if ("linguistic" in metric_results):
-            linguistic_result    = metric_results["linguistic"]
-            pos_diversity        = linguistic_result.details.get("pos_diversity", 0.5)
-            syntactic_complexity = linguistic_result.details.get("syntactic_complexity", 2.5)
-            domain_weight        = domain_weights.get("linguistic", 1.0)
-            
-            # Complex linguistic patterns suggest advanced models
-            if (syntactic_complexity > 3.0):
-                scores[AIModel.CLAUDE_3_OPUS] += 0.5 * self.METRIC_WEIGHTS["linguistic"] * domain_weight
-                scores[AIModel.GPT_4]         += 0.4 * self.METRIC_WEIGHTS["linguistic"] * domain_weight
-        
-        # MULTI-PERTURBATION STABILITY ANALYSIS (10% weight)
-        if ("multi_perturbation_stability" in metric_results):
-            multi_perturbation_stability_result = metric_results["multi_perturbation_stability"]
-            stability                           = multi_perturbation_stability_result.details.get("stability_score", 0.5)
-            curvature                           = multi_perturbation_stability_result.details.get("curvature_score", 0.5)
-            
-            # Specific stability patterns for different model families
-            if (0.4 <= stability <= 0.6):
-                scores[AIModel.MIXTRAL] += 0.4 * self.METRIC_WEIGHTS["multi_perturbation_stability"]
-                scores[AIModel.LLAMA_3] += 0.3 * self.METRIC_WEIGHTS["multi_perturbation_stability"]
-        
-        # Normalize scores
-        for model in scores:
-            scores[model] = min(1.0, scores[model])
-        
-        return scores
-
-
-    def _combine_attribution_scores(self, fingerprint_scores: Dict[AIModel, float], statistical_scores: Dict[AIModel, float],
-                                    metric_scores: Dict[AIModel, float], domain: Domain) -> Tuple[Dict[str, float], Dict[str, float]]:
-        """
-        ENSEMBLE COMBINATION using document-specified weights and domain awareness
-        """
-        # DOMAIN-AWARE weighting for ALL 16 DOMAINS
-        domain_weights       = {Domain.GENERAL       : {"fingerprint": 0.35, "statistical": 0.30, "metric": 0.35},
-                                Domain.ACADEMIC      : {"fingerprint": 0.30, "statistical": 0.35, "metric": 0.35},
-                                Domain.TECHNICAL_DOC : {"fingerprint": 0.25, "statistical": 0.40, "metric": 0.35},
-                                Domain.AI_ML         : {"fingerprint": 0.28, "statistical": 0.37, "metric": 0.35},
-                                Domain.SOFTWARE_DEV  : {"fingerprint": 0.27, "statistical": 0.38, "metric": 0.35},
-                                Domain.ENGINEERING   : {"fingerprint": 0.28, "statistical": 0.37, "metric": 0.35},
-                                Domain.SCIENCE       : {"fingerprint": 0.30, "statistical": 0.35, "metric": 0.35},
-                                Domain.BUSINESS      : {"fingerprint": 0.33, "statistical": 0.35, "metric": 0.32},
-                                Domain.LEGAL         : {"fingerprint": 0.28, "statistical": 0.40, "metric": 0.32},
-                                Domain.MEDICAL       : {"fingerprint": 0.30, "statistical": 0.38, "metric": 0.32},
-                                Domain.JOURNALISM    : {"fingerprint": 0.35, "statistical": 0.33, "metric": 0.32},
-                                Domain.CREATIVE      : {"fingerprint": 0.40, "statistical": 0.30, "metric": 0.30},
-                                Domain.MARKETING     : {"fingerprint": 0.38, "statistical": 0.32, "metric": 0.30},
-                                Domain.SOCIAL_MEDIA  : {"fingerprint": 0.45, "statistical": 0.35, "metric": 0.20},
-                                Domain.BLOG_PERSONAL : {"fingerprint": 0.42, "statistical": 0.32, "metric": 0.26},
-                                Domain.TUTORIAL      : {"fingerprint": 0.33, "statistical": 0.35, "metric": 0.32},
-                               }
-        
-        weights              = domain_weights.get(domain, domain_weights[Domain.GENERAL])
-        
-        combined             = dict()
-        metric_contributions = dict()
-        
-        all_models           = set(fingerprint_scores.keys()) | set(statistical_scores.keys()) | set(metric_scores.keys())
-        
-        for model in all_models:
-            score                 = (fingerprint_scores.get(model, 0.0) * weights["fingerprint"] + 
-                                     statistical_scores.get(model, 0.0) * weights["statistical"] + 
-                                     metric_scores.get(model, 0.0) * weights["metric"]
-                                    )
-            
-            combined[model.value] = score
-        
-        # Normalize scores to sum to 1.0 for proper probability distribution
-        total_score = sum(combined.values())
-
-        if (total_score > 0):
-            combined = {model: score / total_score for model, score in combined.items()}
-        
-        # Calculate metric contributions for explainability
-        if metric_scores:
-            total_metric_impact = sum(metric_scores.values())
-            if (total_metric_impact > 0):
-                for model, score in metric_scores.items():
-                    metric_contributions[model.value] = score / total_metric_impact
-        
-        return combined, metric_contributions
-
-
-    def _make_domain_aware_prediction(self, combined_scores: Dict[str, float], domain: Domain, domain_preferences: List[AIModel]) -> Tuple[AIModel, float]:
-        """
-        Domain aware prediction that considers domain-specific model preferences
-        """
-        if not combined_scores:
-            return AIModel.UNKNOWN, 0.0
-        
-        # Find the model with the highest probability
-        sorted_models = sorted(combined_scores.items(), key=lambda x: x[1], reverse=True)
-        
-        if not sorted_models:
-            return AIModel.UNKNOWN, 0.0
-        
-        best_model_name, best_score = sorted_models[0]
-        
-        # Thresholding to show model only if confidence is sufficient
-        if (best_score < 0.01): 
-            return AIModel.UNKNOWN, best_score
-        
-        try:
-            best_model = AIModel(best_model_name)
-
-        except ValueError:
-            best_model = AIModel.UNKNOWN
-        
-        # Calculate confidence - be more generous
-        if (len(sorted_models) > 1):
-            second_score = sorted_models[1][1]
-            margin       = best_score - second_score
-            # More generous confidence calculation
-            confidence   = min(1.0, best_score * 0.8 + margin * 1.5)
-
-        else:
-            confidence = best_score * 0.9
-        
-        # Always return the actual best model, never downgrade to UNKNOWN
-        return best_model, max(0.05, confidence)  
-
-
-    def _generate_detailed_reasoning(self, predicted_model: AIModel, confidence: float, domain: Domain, metric_contributions: Dict[str, float], 
-                                     combined_scores: Dict[str, float]) -> List[str]:
-        """
-        Generate Explainable reasoning - ENHANCED version
-        """
-        reasoning = []
-        
-        reasoning.append("**AI Model Attribution Analysis**")
-        reasoning.append("")
-        
-        # Show prediction with confidence
-        if (predicted_model == AIModel.UNKNOWN):
-            reasoning.append("**Most Likely**: Unable to determine with high confidence")
-
-        else:
-            model_name = predicted_model.value.replace("-", " ").replace("_", " ").title()
-            reasoning.append(f"**Predicted Model**: {model_name}")
-            reasoning.append(f"**Confidence**: {confidence*100:.1f}%")
-        
-        reasoning.append(f"**Domain**: {domain.value.replace('_', ' ').title()}")
-        reasoning.append("")
-        
-        # Show model probability distribution
-        reasoning.append("**Model Probability Distribution:**")
-        reasoning.append("")
-        
-        if combined_scores:
-            sorted_models = sorted(combined_scores.items(), key = lambda x: x[1], reverse = True)
-            
-            for i, (model_name, score) in enumerate(sorted_models[:6]):
-                # Skip very low probabilities
-                if (score < 0.01):  
-                    continue
-                    
-                display_name = model_name.replace("-", " ").replace("_", " ").title()
-                percentage   = score * 100
-                
-                # Use proper markdown formatting
-                reasoning.append(f"• **{display_name}**: {percentage:.1f}%")
-        
-        reasoning.append("")
-        
-        # Add analysis insights
-        reasoning.append("**Analysis Notes:**")
-        
-        if (confidence < 0.3):
-            reasoning.append("• Low confidence attribution - text patterns are ambiguous")
-            reasoning.append("• May be human-written or from multiple AI sources")
-
-        else:
-            reasoning.append(f"• Calibrated for {domain.value.replace('_', ' ')} domain")
-            
-            # Domain-specific insights
-            domain_insights = {Domain.ACADEMIC      : "Academic writing patterns analyzed",
-                               Domain.TECHNICAL_DOC : "Technical coherence and structure weighted",
-                               Domain.CREATIVE      : "Stylistic and linguistic diversity emphasized",
-                               Domain.SOCIAL_MEDIA  : "Casual language and engagement patterns considered",
-                               Domain.AI_ML         : "Technical terminology and analytical patterns emphasized",
-                               Domain.SOFTWARE_DEV  : "Code-like structures and technical precision weighted",
-                               Domain.ENGINEERING   : "Technical specifications and formal language analyzed",
-                               Domain.SCIENCE       : "Scientific terminology and methodological patterns considered",
-                               Domain.BUSINESS      : "Professional communication and strategic language weighted",
-                               Domain.LEGAL         : "Formal language and legal terminology emphasized",
-                               Domain.MEDICAL       : "Medical terminology and clinical language analyzed",
-                               Domain.JOURNALISM    : "News reporting style and factual presentation weighted",
-                               Domain.MARKETING     : "Persuasive language and engagement patterns considered",
-                               Domain.BLOG_PERSONAL : "Personal voice and conversational style analyzed",
-                               Domain.TUTORIAL      : "Instructional clarity and step-by-step structure weighted",
-                              }
-            
-            insight         = domain_insights.get(domain, "Multiple attribution factors analyzed")
-
-            reasoning.append(f"• {insight}")
-        
-        return reasoning
-
-
-    def _get_top_fingerprints(self, fingerprint_scores: Dict[AIModel, float]) -> Dict[str, int]:
-        """
-        Get top fingerprint matches for display
-        """
-        top_matches   = dict()
-        sorted_models = sorted(fingerprint_scores.items(), key = lambda x: x[1], reverse = True)[:5]
-        
-        for model, score in sorted_models:
-            # Only show meaningful matches
-            if (score > 0.1):  
-                top_matches[model.value] = int(score * 100)
-        
-        return top_matches
-
-
-    def _create_unknown_result(self, domain: Domain) -> AttributionResult:
-        """
-        Create result for unknown attribution with domain context
-        """
-        return AttributionResult(predicted_model      = AIModel.UNKNOWN,
-                                 confidence           = 0.0,
-                                 model_probabilities  = {},
-                                 reasoning            = [f"Model attribution inconclusive for {domain.value} content. Text may be human-written or from unidentifiable model"],
-                                 fingerprint_matches  = {},
-                                 domain_used          = domain,
-                                 metric_contributions = {},
-                                )
-
-
-# Export
-__all__ = ["AIModel", 
-           "ModelAttributor", 
-           "AttributionResult",
-          ]

detector/orchestrator.py

@@ -1,576 +0,0 @@
-# DEPENDENCIES
-import time
-from typing import Any
-from typing import Dict
-from typing import List
-from loguru import logger
-from typing import Optional
-from dataclasses import dataclass
-from config.settings import settings
-from metrics.entropy import EntropyMetric
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
-from detector.ensemble import EnsembleResult
-from metrics.perplexity import PerplexityMetric
-from metrics.linguistic import LinguisticMetric
-from metrics.structural import StructuralMetric
-from detector.ensemble import EnsembleClassifier
-from processors.text_processor import TextProcessor
-from processors.text_processor import ProcessedText
-from processors.domain_classifier import DomainClassifier
-from processors.domain_classifier import DomainPrediction
-from processors.language_detector import LanguageDetector
-from metrics.semantic_analysis import SemanticAnalysisMetric
-from processors.language_detector import LanguageDetectionResult
-from metrics.multi_perturbation_stability import MultiPerturbationStabilityMetric
-
-
-@dataclass
-class DetectionResult:
-    """
-    Complete detection result with all metadata
-    """
-    # Final results
-    ensemble_result        : EnsembleResult
-    
-    # Input metadata
-    processed_text         : ProcessedText
-    domain_prediction      : DomainPrediction
-    language_result        : Optional[LanguageDetectionResult]
-    
-    # Metric details
-    metric_results         : Dict[str, MetricResult]
-    
-    # Performance metrics
-    processing_time        : float
-    metrics_execution_time : Dict[str, float] 
-    
-    # Warnings and errors
-    warnings               : List[str]
-    errors                 : List[str]
-    
-    # File information
-    file_info              : Optional[Dict[str, Any]] = None
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for JSON serialization
-        """
-        result = {"prediction"  : {"verdict"           : self.ensemble_result.final_verdict,
-                                   "ai_probability"    : round(self.ensemble_result.ai_probability, 4),
-                                   "human_probability" : round(self.ensemble_result.human_probability, 4),
-                                   "mixed_probability" : round(self.ensemble_result.mixed_probability, 4),
-                                   "confidence"        : round(self.ensemble_result.overall_confidence, 4),
-                                  },
-                  "analysis"    : {"domain"              : self.domain_prediction.primary_domain.value,
-                                   "domain_confidence"   : round(self.domain_prediction.confidence, 4),
-                                   "language"            : self.language_result.primary_language.value if self.language_result else "unknown",
-                                   "language_confidence" : round(self.language_result.confidence, 4) if self.language_result else 0.0,
-                                   "text_length"         : self.processed_text.word_count,
-                                   "sentence_count"      : self.processed_text.sentence_count,
-                                  },
-                  "metrics"     : {name: result.to_dict() for name, result in self.metric_results.items()},
-                  "ensemble"    : self.ensemble_result.to_dict(),
-                  "performance" : {"total_time"   : round(self.processing_time, 3),
-                                   "metrics_time" : {name: round(t, 3) for name, t in self.metrics_execution_time.items()},
-                                  },
-                  "warnings"    : self.warnings,
-                  "errors"      : self.errors,
-                 }
-        
-        # Include file_info if available
-        if self.file_info:
-            result["file_info"] = self.file_info
-        
-        return result
-
-
-class DetectionOrchestrator:
-    """
-    Coordinates the entire detection pipeline from text input to final results.
-
-    Pipeline:
-    1. Text preprocessing
-    2. Domain classification
-    3. Language detection (optional)
-    4. Metric execution (parallel/sequential)
-    5. Ensemble aggregation
-    6. Result generation
-    """
-    
-    def __init__(self, enable_language_detection: bool = False, parallel_execution: bool = False, skip_expensive_metrics: bool = False):
-        """
-        Initialize detection orchestrator
-        
-        Arguments:
-        ----------
-            enable_language_detection { bool } : Enable language detection step
-            
-            parallel_execution        { bool } : Execute metrics in parallel (future feature)
-            
-            skip_expensive_metrics    { bool } : Skip computationally expensive metrics
-        """
-        self.enable_language_detection = enable_language_detection
-        self.parallel_execution        = parallel_execution
-        self.skip_expensive_metrics    = skip_expensive_metrics
-        
-        # Initialize processors
-        self.text_processor            = TextProcessor(min_text_length = settings.MIN_TEXT_LENGTH,
-                                                       max_text_length = settings.MAX_TEXT_LENGTH,
-                                                      )
-        self.domain_classifier         = DomainClassifier()
-        
-        if self.enable_language_detection:
-            self.language_detector = LanguageDetector(use_model = True)
-        
-        else:
-            self.language_detector = None
-        
-        # Initialize metrics
-        self.metrics                   = self._initialize_metrics()
-        
-        # Initialize ensemble
-        self.ensemble                  = EnsembleClassifier(primary_method       = "confidence_calibrated",
-                                                            fallback_method      = "domain_weighted",
-                                                            use_ml_ensemble      = False,
-                                                            min_metrics_required = 3,
-                                                           )
-        
-        logger.info(f"DetectionOrchestrator initialized (language_detection={enable_language_detection}, skip_expensive={skip_expensive_metrics})")
-    
-
-    def _initialize_metrics(self) -> Dict[str, Any]:
-        """
-        Initialize all enabled metrics
-        """
-        metrics = dict()
-        
-        # Structural metric (statistical analysis)
-        try:
-            metrics["structural"] = StructuralMetric()
-            logger.debug("Structural metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize structural metric: {repr(e)}")
-        
-        # Entropy metric
-        try:
-            metrics["entropy"] = EntropyMetric()
-            logger.debug("Entropy metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize entropy metric: {repr(e)}")
-        
-        # Perplexity metric
-        try:
-            metrics["perplexity"] = PerplexityMetric()
-            logger.debug("Perplexity metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize perplexity metric: {repr(e)}")
-        
-        # Semantic analysis metric
-        try:
-            metrics["semantic_analysis"] = SemanticAnalysisMetric()
-            logger.debug("Semantic analysis metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize semantic analysis metric: {repr(e)}")
-        
-        # Linguistic metric
-        try:
-            metrics["linguistic"] = LinguisticMetric()
-            logger.debug("Linguistic metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize linguistic metric: {repr(e)}")
-        
-        # MultiPerturbationStability metric (expensive)
-        try:
-            metrics["multi_perturbation_stability"] = MultiPerturbationStabilityMetric()
-            logger.debug("MultiPerturbationStability metric initialized")
-        
-        except Exception as e:
-            logger.error(f"Failed to initialize MultiPerturbationStability metric: {repr(e)}")
-        
-        logger.info(f"Initialized {len(metrics)} metrics: {list(metrics.keys())}")
-        return metrics
-    
-
-    def initialize(self) -> bool:
-        """
-        Initialize all components (load models, etc.)
-        
-        Returns:
-        --------
-            { bool } : True if successful, False otherwise
-        """
-        try:
-            logger.info("Initializing detection pipeline...")
-            
-            # Initialize domain classifier
-            if not self.domain_classifier.initialize():
-                logger.warning("Domain classifier initialization failed")
-            
-            # Initialize language detector
-            if self.language_detector:
-                if not self.language_detector.initialize():
-                    logger.warning("Language detector initialization failed")
-            
-            # Initialize metrics
-            successful_metrics = 0
-            
-            for name, metric in self.metrics.items():
-                try:
-                    if metric.initialize():
-                        successful_metrics += 1
-                        logger.debug(f"Metric {name} initialized successfully")
-                    
-                    else:
-                        logger.warning(f"Metric {name} initialization failed")
-                
-                except Exception as e:
-                    logger.error(f"Error initializing metric {name}: {repr(e)}")
-            
-            # Need at least 3 metrics for reliable detection
-            logger.success(f"Detection pipeline initialized: {successful_metrics}/{len(self.metrics)} metrics ready")
-            return (successful_metrics >= 3)  
-            
-        except Exception as e:
-            logger.error(f"Failed to initialize detection pipeline: {repr(e)}")
-            return False
-    
-
-    def analyze(self, text: str, domain: Optional[Domain] = None, **kwargs) -> DetectionResult:
-        """
-        Analyze text and detect if AI-generated
-        
-        Arguments:
-        ----------
-            text       { str }   : Input text to analyze
-            
-            domain   { Domain }  : Override automatic domain detection
-            
-            **kwargs             : Additional options
-            
-        Returns:
-        --------
-            { DetectionResult }  : DetectionResult with complete analysis
-        """
-        start_time = time.time()
-        warnings   = list()
-        errors     = list()
-        
-        try:
-            # Preprocess text
-            logger.info("Step 1: Preprocessing text...")
-            processed_text = self.text_processor.process(text = text)
-            
-            if not processed_text.is_valid:
-                logger.warning(f"Text validation failed: {processed_text.validation_errors}")
-                warnings.extend(processed_text.validation_errors)
-                # Continue anyway if text is present
-            
-            # Detect language
-            language_result = None
-
-            if self.language_detector:
-                logger.info("Step 2: Detecting language...")
-                
-                try:
-                    language_result = self.language_detector.detect(processed_text.cleaned_text)
-                    
-                    if (language_result.primary_language.value != "en"):
-                        warnings.append(f"Non-English text detected ({language_result.primary_language.value}). Detection accuracy may be reduced.")
-                    
-                    if (language_result.is_multilingual):
-                        warnings.append("Multilingual content detected")
-                    
-                    if (language_result.confidence < 0.7):
-                        warnings.append(f"Low language detection confidence ({language_result.confidence:.2f})")
-
-                except Exception as e:
-                    logger.warning(f"Language detection failed: {repr(e)}")
-                    warnings.append("Language detection failed")
-            
-            # Classify domain
-            logger.info("Step 3: Classifying domain...")
-            if domain is None:
-                try:
-                    domain_prediction = self.domain_classifier.classify(processed_text.cleaned_text)
-                    domain            = domain_prediction.primary_domain
-                    
-                    if (domain_prediction.confidence < 0.5):
-                        warnings.append(f"Low domain classification confidence ({domain_prediction.confidence:.2f})")
-
-                except Exception as e:
-                    logger.warning(f"Domain classification failed: {repr(e)}")
-                    domain_prediction = DomainPrediction(primary_domain   = Domain.GENERAL,
-                                                         secondary_domain = None,
-                                                         confidence       = 0.5,
-                                                         domain_scores    = {},
-                                                        )
-                    domain            = Domain.GENERAL
-
-                    warnings.append("Domain classification failed, using GENERAL")
-            
-            else:
-                # Use provided domain
-                domain_prediction = DomainPrediction(primary_domain   = domain,
-                                                     secondary_domain = None,
-                                                     confidence       = 1.0,
-                                                     domain_scores    = {domain.value: 1.0},
-                                                    )
-            
-            logger.info(f"Detected domain: {domain.value} (confidence: {domain_prediction.confidence:.2f})")
-            
-            # Execute metrics calculations
-            logger.info("Step 4: Executing detection metrics calculations...")
-            metric_results         = dict()
-            metrics_execution_time = dict()
-            
-            for name, metric in self.metrics.items():
-                metric_start = time.time()
-               
-                try:
-                    # Check if we should skip expensive metrics
-                    if (self.skip_expensive_metrics and (name == "multi_perturbation_stability")):
-                        logger.info(f"Skipping expensive metric: {name}")
-                        continue
-                    
-                    logger.debug(f"Computing metric: {name}")
-                    
-                    result = metric.compute(text           = processed_text.cleaned_text,
-                                            domain         = domain,
-                                            skip_expensive = self.skip_expensive_metrics,
-                                           )
-                    
-                    metric_results[name] = result
-                    
-                    if result.error:
-                        warnings.append(f"{name} metric error: {result.error}")
-                    
-                except Exception as e:
-                    logger.error(f"Error computing metric {name}: {repr(e)}")
-                    errors.append(f"{name}: {repr(e)}")
-                    
-                    # Create error result
-                    metric_results[name] = MetricResult(metric_name       = name,
-                                                        ai_probability    = 0.5,
-                                                        human_probability = 0.5,
-                                                        mixed_probability = 0.0,
-                                                        confidence        = 0.0,
-                                                        error             = repr(e),
-                                                       )
-                finally:
-                    metrics_execution_time[name] = time.time() - metric_start
-            
-            logger.info(f"Executed {len(metric_results)} metrics successfully")
-            
-            # Ensemble aggregation
-            logger.info("Step 5: Aggregating results with ensemble...")
-            
-            try:
-                ensemble_result = self.ensemble.predict(metric_results = metric_results,
-                                                        domain         = domain,
-                                                       )
-
-            except Exception as e:
-                logger.error(f"Ensemble prediction failed: {repr(e)}")
-                errors.append(f"Ensemble: {repr(e)}")
-               
-                # Create fallback result    
-                ensemble_result = EnsembleResult(final_verdict      = "Error",
-                                                 ai_probability     = 0.5,
-                                                 human_probability  = 0.5,
-                                                 mixed_probability  = 0.0,
-                                                 overall_confidence = 0.0,
-                                                 domain             = domain,
-                                                 metric_results     = metric_results,
-                                                 metric_weights     = {},
-                                                 weighted_scores    = {},
-                                                 reasoning          = ["Ensemble aggregation failed"],
-                                                 uncertainty_score  = 1.0,
-                                                 consensus_level    = 0.0,
-                                                )
-            
-            # Calculate total processing time
-            processing_time     = time.time() - start_time
-            
-            logger.success(f"Analysis complete: {ensemble_result.final_verdict} "
-                           f"(AI probability: {ensemble_result.ai_probability:.1%}, "
-                           f"confidence: {ensemble_result.overall_confidence:.2f}) "
-                           f"in {processing_time:.2f}s")
-            
-            return DetectionResult(ensemble_result        = ensemble_result,
-                                   processed_text         = processed_text,
-                                   domain_prediction      = domain_prediction,
-                                   language_result        = language_result,
-                                   metric_results         = metric_results,
-                                   processing_time        = processing_time,
-                                   metrics_execution_time = metrics_execution_time,
-                                   warnings               = warnings,
-                                   errors                 = errors,
-                                  )
-            
-        except Exception as e:
-            logger.error(f"Fatal error in detection pipeline: {repr(e)}")
-            processing_time = time.time() - start_time
-            
-            # Return error result
-            return DetectionResult(ensemble_result        = EnsembleResult(final_verdict      = "Error",
-                                                                           ai_probability     = 0.5,
-                                                                           human_probability  = 0.5,
-                                                                           mixed_probability  = 0.0,
-                                                                           overall_confidence = 0.0,
-                                                                           domain             = Domain.GENERAL,
-                                                                           metric_results     = {},
-                                                                           metric_weights     = {},
-                                                                           weighted_scores    = {},
-                                                                           reasoning          = [f"Fatal error: {str(e)}"],
-                                                                           uncertainty_score  = 1.0,
-                                                                           consensus_level    = 0.0,
-                                                                          ),
-                                   processed_text         = ProcessedText(original_text       = text,
-                                                                          cleaned_text        = "",
-                                                                          sentences           = [],
-                                                                          words               = [],
-                                                                          paragraphs          = [],
-                                                                          char_count          = 0,
-                                                                          word_count          = 0,
-                                                                          sentence_count      = 0,
-                                                                          paragraph_count     = 0,
-                                                                          avg_sentence_length = 0.0,
-                                                                          avg_word_length     = 0.0,
-                                                                          is_valid            = False,
-                                                                          validation_errors   = ["Processing failed"],
-                                                                          metadata            = {},
-                                                                         ),
-                                   domain_prediction      = DomainPrediction(primary_domain   = Domain.GENERAL,
-                                                                             secondary_domain = None,
-                                                                             confidence       = 0.0,
-                                                                             domain_scores    = {},
-                                                                            ),
-                                   language_result        = None,
-                                   metric_results         = {},
-                                   processing_time        = processing_time,
-                                   metrics_execution_time = {},
-                                   warnings               = [],
-                                   errors                 = [f"Fatal error: {repr(e)}"],
-                                  )
-    
-
-    def batch_analyze(self, texts: List[str], domain: Optional[Domain] = None) -> List[DetectionResult]:
-        """
-        Analyze multiple texts
-        
-        Arguments:
-        ----------
-            texts    { list }  : List of texts to analyze
-
-            domain  { Domain } : Override automatic domain detection
-            
-        Returns:
-        --------
-               { list }        : List of DetectionResult objects
-        """
-        logger.info(f"Batch analyzing {len(texts)} texts...")
-
-        results = list()
-        
-        for i, text in enumerate(texts):
-            logger.info(f"Analyzing text {i+1}/{len(texts)}...")
-            try:
-                result = self.analyze(text   = text, 
-                                      domain = domain,
-                                     )
-
-                results.append(result)
-            
-            except Exception as e:
-                logger.error(f"Error analyzing text {i+1}: {repr(e)}")
-                # Create error result for this text
-                error_result = DetectionResult(ensemble_result        = EnsembleResult(final_verdict      = "Error",
-                                                                                       ai_probability     = 0.5,
-                                                                                       human_probability  = 0.5,
-                                                                                       mixed_probability  = 0.0,
-                                                                                       overall_confidence = 0.0,
-                                                                                       domain             = Domain.GENERAL,
-                                                                                       metric_results     = {},
-                                                                                       metric_weights     = {},
-                                                                                       weighted_scores    = {},
-                                                                                       reasoning          = [f"Analysis failed: {str(e)}"],
-                                                                                       uncertainty_score  = 1.0,
-                                                                                       consensus_level    = 0.0,
-                                                                                      ),
-                                               processed_text         = ProcessedText(original_text       = text,
-                                                                                      cleaned_text        = "",
-                                                                                      sentences           = [],
-                                                                                      words               = [],
-                                                                                      paragraphs          = [],
-                                                                                      char_count          = 0,
-                                                                                      word_count          = 0,
-                                                                                      sentence_count      = 0,
-                                                                                      paragraph_count     = 0,
-                                                                                      avg_sentence_length = 0.0,
-                                                                                      avg_word_length     = 0.0,
-                                                                                      is_valid            = False,
-                                                                                      validation_errors   = ["Processing failed"],
-                                                                                      metadata            = {},
-                                                                                     ),
-                                               domain_prediction      = DomainPrediction(primary_domain   = Domain.GENERAL,
-                                                                                         secondary_domain = None,
-                                                                                         confidence       = 0.0,
-                                                                                         domain_scores    = {},
-                                                                                        ),
-                                               language_result        = None,
-                                               metric_results         = {},
-                                               processing_time        = 0.0,
-                                               metrics_execution_time = {},
-                                               warnings               = [],
-                                               errors                 = [f"Analysis failed: {repr(e)}"],
-                                              )
-                results.append(error_result)
-        
-        logger.info(f"Batch analysis complete: {len(results)}/{len(texts)} processed")
-        return results
-    
-
-    def cleanup(self):
-        """
-        Clean up resources
-        """
-        logger.info("Cleaning up detection orchestrator...")
-        
-        for name, metric in self.metrics.items():
-            try:
-                metric.cleanup()
-                logger.debug(f"Cleaned up metric: {name}")
-            
-            except Exception as e:
-                logger.warning(f"Error cleaning up metric {name}: {repr(e)}")
-        
-        if self.domain_classifier:
-            try:
-                self.domain_classifier.cleanup()
-                logger.debug("Cleaned up domain classifier")
-           
-            except Exception as e:
-                logger.warning(f"Error cleaning up domain classifier: {repr(e)}")
-        
-        if self.language_detector:
-            try:
-                self.language_detector.cleanup()
-                logger.debug("Cleaned up language detector")
-        
-            except Exception as e:
-                logger.warning(f"Error cleaning up language detector: {repr(e)}")
-        
-        logger.info("Cleanup complete")
-
-
-
-# Export
-__all__ = ["DetectionResult",
-           "DetectionOrchestrator",
-          ]

docs/API_DOCUMENTATION.md

@@ -0,0 +1,705 @@
+# TEXT-AUTH API Documentation
+
+## Overview
+
+The TEXT-AUTH API provides evidence-based text forensics and statistical consistency assessment through a RESTful interface. This document covers all endpoints, request/response formats, authentication, rate limiting, and integration examples.
+
+**API Version:** 1.0.0  
+
+---
+
+## Table of Contents
+
+1. [Authentication & Security](#authentication--security)
+2. [Rate Limiting](#rate-limiting)
+3. [Common Response Format](#common-response-format)
+4. [Error Handling](#error-handling)
+5. [Core Endpoints](#core-endpoints)
+   - [Text Analysis](#text-analysis)
+   - [File Analysis](#file-analysis)
+   - [Batch Analysis](#batch-analysis)
+6. [Report Endpoints](#report-endpoints)
+7. [Utility Endpoints](#utility-endpoints)
+8. [Best Practices](#best-practices)
+
+---
+
+## Authentication & Security
+
+### API Key Authentication
+
+*Authentication is not enforced in the current deployment. API key authentication may be added in future versions.*
+
+
+## Rate Limiting
+
+*Rate limiting is not enforced at the application level. Deployments should use an external gateway (NGINX, API Gateway, Cloudflare) to enforce rate limits if required.*
+
+---
+## Common Response Format
+
+All successful responses follow this structure:
+
+```json
+{
+  "status": "success",
+  "analysis_id": "...",
+  "detection_result": {...},
+  "highlighted_html": "...",
+  "reasoning": {...},
+  "processing_time": 2.34,
+  "timestamp": "..."
+}
+```
+
+### HTTP Status Codes
+
+| Code | Meaning | Description |
+|------|---------|-------------|
+| 200 | OK | Request succeeded |
+| 201 | Created | Resource created successfully |
+| 400 | Bad Request | Invalid request parameters |
+| 404 | Not Found | Resource not found |
+| 500 | Internal Server Error | Server error |
+| 503 | Service Unavailable | Service temporarily unavailable |
+
+---
+
+## Error Handling
+
+### Error Response Format
+
+```json
+{
+  "status": "error",
+  "error": "Invalid domain...",
+  "timestamp": "..."
+}
+```
+
+### Common Error Codes
+
+| Code | Description | Resolution |
+|------|-------------|------------|
+| `TEXT_TOO_LONG` | Text exceeds maximum length (50,000 chars) | Split into multiple requests |
+| `FILE_TOO_LARGE` | File exceeds size limit | Compress or split file |
+| `UNSUPPORTED_FORMAT` | File format not supported | Use .txt, .pdf, .docx, .doc, or .md |
+| `EXTRACTION_FAILED` | Document text extraction failed | Ensure file is not corrupted or password-protected |
+| `MODEL_UNAVAILABLE` | Required model temporarily unavailable | Retry after a few minutes |
+
+---
+
+## Core Endpoints
+
+### Text Analysis
+
+**Endpoint:** `POST /api/analyze`
+
+Analyze raw text for statistical consistency patterns and forensic signals.
+
+#### Request
+
+**Headers:**
+```http
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "text": "Your text content here...",
+  "domain": "academic",
+  "enable_highlighting": true,
+  "skip_expensive_metrics": false,
+  "use_sentence_level": true,
+  "include_metrics_summary": true,
+  "generate_report": false
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `text` | string | **Yes** | - | Text to analyze (50-50,000 chars) |
+| `domain` | string | No | `null` (auto-detect) | Content domain (see [Domains](#supported-domains)) |
+| `enable_highlighting` | boolean | No | `true` | Generate sentence-level highlights |
+| `skip_expensive_metrics` | boolean | No | `false` | Skip computationally expensive metrics for faster results |
+| `use_sentence_level` | boolean | No | `true` | Use sentence-level granularity for highlighting |
+| `include_metrics_summary` | boolean | No | `true` | Include metric summaries in highlights |
+| `generate_report` | boolean | No | `false` | Generate downloadable PDF/JSON report |
+
+#### Response
+
+```json
+{
+  "status": "success",
+  "analysis_id": "analysis_1735555800000",
+  "detection_result": {
+    "ensemble_result": {
+      "final_verdict": "Synthetic",
+      "overall_confidence": 0.89,
+      "synthetic_probability": 0.92,
+      "authentic_probability": 0.08,
+      "uncertainty_score": 0.23,
+      "decision_boundary_distance": 0.42
+    },
+    "metric_results": {
+      "perplexity": {
+        "synthetic_probability": 0.94,
+        "confidence": 0.91,
+        "raw_score": 15.23,
+        "evidence_strength": "strong"
+      },
+      "entropy": {
+        "synthetic_probability": 0.88,
+        "confidence": 0.85,
+        "raw_score": 4.67,
+        "evidence_strength": "moderate"
+      },
+      "structural": {
+        "synthetic_probability": 0.91,
+        "confidence": 0.87,
+        "burstiness": -0.12,
+        "uniformity": 0.85,
+        "evidence_strength": "strong"
+      },
+      "linguistic": {
+        "synthetic_probability": 0.86,
+        "confidence": 0.82,
+        "pos_diversity": 0.42,
+        "mean_tree_depth": 4.2,
+        "evidence_strength": "moderate"
+      },
+      "semantic": {
+        "synthetic_probability": 0.93,
+        "confidence": 0.88,
+        "coherence_mean": 0.91,
+        "coherence_variance": 0.03,
+        "evidence_strength": "strong"
+      },
+      "multi_perturbation_stability": {
+        "synthetic_probability": 0.89,
+        "confidence": 0.84,
+        "stability_score": 0.12,
+        "evidence_strength": "moderate"
+      }
+    },
+    "domain_prediction": {
+      "primary_domain": "academic",
+      "confidence": 0.94,
+      "alternative_domains": [
+        {"domain": "technical_doc", "probability": 0.23},
+        {"domain": "science", "probability": 0.18}
+      ]
+    },
+    "processed_text": {
+      "word_count": 487,
+      "sentence_count": 23,
+      "paragraph_count": 5,
+      "avg_sentence_length": 21.2,
+      "language": "en"
+    }
+  },
+  "highlighted_html": "<div class=\"text-forensics-highlight\">...</div>",
+  "reasoning": {
+    "summary": "The text exhibits strong statistical consistency patterns typical of language model generation...",
+    "key_indicators": [
+      "Unusually uniform sentence structure (burstiness: -0.12)",
+      "High semantic coherence across all sentences (mean: 0.91)",
+      "Low perplexity variance indicating predictable token sequences"
+    ],
+    "confidence_factors": {
+      "supporting_evidence": [
+        "6/6 metrics indicate synthetic patterns",
+        "Strong cross-metric agreement (correlation: 0.87)"
+      ],
+      "uncertainty_sources": [
+        "Domain-specific terminology may affect baseline expectations"
+      ]
+    },
+    "metric_contributions": {
+      "perplexity": 0.28,
+      "entropy": 0.19,
+      "structural": 0.16,
+      "semantic": 0.17,
+      "linguistic": 0.12,
+      "multi_perturbation_stability": 0.08
+    }
+  },
+  "report_files": null,
+  "processing_time": 2.34,
+  "timestamp": "2025-12-30T10:30:00Z"
+}
+```
+
+#### Verdict Interpretation
+
+| Verdict | Probability Range | Interpretation |
+|---------|-------------------|----------------|
+| **Synthetic** | > 0.70 | High consistency with language model generation patterns |
+| **Likely Synthetic** | 0.55 - 0.70 | Moderate consistency with synthetic patterns |
+| **Inconclusive** | 0.45 - 0.55 | Insufficient evidence for confident assessment |
+| **Likely Authentic** | 0.30 - 0.45 | Moderate consistency with human authorship patterns |
+| **Authentic** | < 0.30 | High consistency with human authorship patterns |
+
+**Important:** These verdicts represent statistical consistency assessments, not definitive authorship claims.
+
+#### Highlighting Color Key
+
+| Color | Meaning | Probability Range |
+|-------|---------|-------------------|
+| 🔴 Red | Strong synthetic signals | > 0.80 |
+| 🟠 Orange | Moderate synthetic signals | 0.60 - 0.80 |
+| 🟡 Yellow | Weak signals | 0.40 - 0.60 |
+| 🟢 Green | Authentic signals | < 0.40 |
+
+---
+
+### File Analysis
+
+**Endpoint:** `POST /api/analyze/file`
+
+Analyze uploaded documents (PDF, DOCX, DOC, TXT, MD).
+
+#### Request
+
+**Headers:**
+```http
+Content-Type: multipart/form-data
+```
+
+**Body (form-data):**
+```
+file: [binary file data]
+domain: "academic"
+skip_expensive_metrics: false
+use_sentence_level: true
+include_metrics_summary: true
+generate_report: false
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file` | file | **Yes** | - | Document file (max 25MB) |
+| `domain` | string | No | `null` | Content domain override |
+| `skip_expensive_metrics` | boolean | No | `false` | Skip expensive metrics |
+| `use_sentence_level` | boolean | No | `true` | Sentence-level highlighting |
+| `include_metrics_summary` | boolean | No | `true` | Include metric summaries |
+| `generate_report` | boolean | No | `false` | Generate report |
+
+#### Supported File Formats
+
+| Format | Extensions | Max Size | Notes |
+|--------|-----------|----------|-------|
+| Plain Text | .txt, .md | 25MB | UTF-8 encoding recommended |
+| PDF | .pdf | 25MB | Text-based PDFs; OCR not supported |
+| Word | .docx, .doc | 25MB | Modern and legacy formats |
+
+#### Response
+
+Same structure as [Text Analysis](#text-analysis) with additional `file_info`:
+
+```json
+{
+  "status": "success",
+  "analysis_id": "file_1735555800000",
+  "file_info": {
+    "filename": "research_paper.pdf",
+    "file_type": ".pdf",
+    "pages": 12,
+    "extraction_method": "pdfplumber",
+    "highlighted_html": true
+  },
+  "detection_result": { /* same as text analysis */ },
+  "highlighted_html": "...",
+  "reasoning": { /* same as text analysis */ },
+  "processing_time": 4.12,
+  "timestamp": "2025-12-30T10:30:00Z"
+}
+```
+
+#### cURL Example
+
+```bash
+curl -X POST https://your-domain.com/api/analyze/file \
+  -F "file=@/path/to/document.pdf" \
+  -F "domain=academic" \
+  -F "generate_report=true"
+```
+
+---
+
+### Batch Analysis
+
+**Endpoint:** `POST /api/analyze/batch`
+
+Analyze multiple texts in a single request for efficiency.
+
+#### Request
+
+```json
+{
+  "texts": [
+    "First text to analyze...",
+    "Second text to analyze...",
+    "Third text to analyze..."
+  ],
+  "domain": "academic",
+  "skip_expensive_metrics": true,
+  "generate_reports": false
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `texts` | array[string] | **Yes** | - | 1-100 texts to analyze |
+| `domain` | string | No | `null` | Apply same domain to all texts |
+| `skip_expensive_metrics` | boolean | No | `true` | Skip expensive metrics (recommended for batch) |
+| `generate_reports` | boolean | No | `false` | Generate reports for each text |
+
+#### Response
+
+```json
+{
+  "status": "success",
+  "batch_id": "batch_1735555800000",
+  "total": 3,
+  "successful": 3,
+  "failed": 0,
+  "results": [
+    {
+      "index": 0,
+      "status": "success",
+      "detection": {
+        "ensemble_result": { /* ... */ },
+        "metric_results": { /* ... */ }
+      },
+      "reasoning": { /* ... */ },
+      "report_files": null
+    },
+    {
+      "index": 1,
+      "status": "success",
+      "detection": { /* ... */ }
+    },
+    {
+      "index": 2,
+      "status": "error",
+      "error": "Text too short (minimum 50 characters)"
+    }
+  ],
+  "processing_time": 8.92,
+  "timestamp": "2025-12-30T10:30:00Z"
+}
+```
+
+#### Performance Tips
+
+- Set `skip_expensive_metrics: true` for faster batch processing
+- Keep batch size under 50 texts for optimal performance
+- Consider parallel API calls for batches > 100 texts
+- Monitor `processing_time` to adjust batch sizes
+
+---
+
+## Report Endpoints
+
+### Generate Report
+
+**Endpoint:** `POST /api/report/generate`
+
+Generate detailed PDF/JSON reports for cached analyses.
+
+#### Request
+
+**Headers:**
+```http
+Content-Type: application/x-www-form-urlencoded
+```
+
+**Body:**
+```
+analysis_id=analysis_1735555800000
+formats=json,pdf
+include_highlights=true
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `analysis_id` | string | **Yes** | - | Analysis ID from previous request |
+| `formats` | string | No | `"json,pdf"` | Comma-separated formats |
+| `include_highlights` | boolean | No | `true` | Include sentence highlights in report |
+
+#### Response
+
+```json
+{
+  "status": "success",
+  "analysis_id": "analysis_1735555800000",
+  "reports": {
+    "json": "analysis_1735555800000.json",
+    "pdf": "analysis_1735555800000.pdf"
+  },
+  "timestamp": "2025-12-30T10:30:00Z"
+}
+```
+
+### Download Report
+
+**Endpoint:** `GET /api/report/download/{filename}`
+
+Download a generated report file.
+
+#### Request
+
+```http
+GET /api/report/download/analysis_1735555800000.pdf
+```
+
+#### Response
+
+Binary file download with appropriate `Content-Type` header.
+
+**Headers:**
+```http
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="analysis_1735555800000.pdf"
+Content-Length: 524288
+```
+
+---
+
+## Utility Endpoints
+
+### Health Check
+
+**Endpoint:** `GET /health`
+
+Check API health and model availability.
+
+#### Response
+
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "uptime": 86400.5,
+  "models_loaded": {
+    "orchestrator": true,
+    "highlighter": true,
+    "reporter": true,
+    "reasoning_generator": true,
+    "document_extractor": true,
+    "analysis_cache": true,
+    "parallel_executor": true
+  }
+}
+```
+
+### List Domains
+
+**Endpoint:** `GET /api/domains`
+
+Get all supported content domains with descriptions.
+
+#### Response
+
+```json
+{
+  "domains": [
+    {
+      "value": "general",
+      "name": "General",
+      "description": "General-purpose text without domain-specific structure"
+    },
+    {
+      "value": "academic",
+      "name": "Academic",
+      "description": "Academic papers, essays, research"
+    },
+    {
+      "value": "creative",
+      "name": "Creative",
+      "description": "Creative writing, fiction, poetry"
+    },
+    {
+      "value": "technical_doc",
+      "name": "Technical Doc",
+      "description": "Technical documentation, manuals, specs"
+    }
+    // ... 12 more domains
+  ]
+}
+```
+
+### Supported Domains
+
+| Domain | Use Cases | Threshold Adjustments |
+|--------|-----------|----------------------|
+| `general` | Default fallback | Balanced weights |
+| `academic` | Research papers, essays | Higher linguistic weight |
+| `creative` | Fiction, poetry | Higher entropy/structural |
+| `ai_ml` | ML papers, technical AI content | Semantic prioritized |
+| `software_dev` | Code docs, READMEs | Structural relaxed |
+| `technical_doc` | Manuals, specs | Higher semantic weight |
+| `engineering` | Technical reports | Balanced technical focus |
+| `science` | Scientific papers | Academic-like calibration |
+| `business` | Reports, proposals | Formal structure emphasis |
+| `legal` | Contracts, court filings | Strict structural patterns |
+| `medical` | Clinical notes, research | Domain-specific terminology |
+| `journalism` | News articles | Balanced, lower burstiness |
+| `marketing` | Ad copy, campaigns | Creative elements |
+| `social_media` | Posts, casual writing | Relaxed metrics, high perplexity weight |
+| `blog_personal` | Personal blogs, diaries | Creative + casual mix |
+| `tutorial` | How-to guides | Instructional patterns |
+
+### Cache Statistics
+
+**Endpoint:** `GET /api/cache/stats`
+
+Get analysis cache statistics (admin only).
+
+#### Response
+
+```json
+{
+  "cache_size": 42,
+  "max_size": 100,
+  "ttl_seconds": 3600
+}
+```
+
+### Clear Cache
+
+**Endpoint:** `POST /api/cache/clear`
+
+Clear analysis cache (admin only).
+
+#### Response
+
+```json
+{
+  "status": "success",
+  "message": "Cache cleared"
+}
+```
+
+---
+
+## Best Practices
+
+### Optimization Tips
+
+1. **Domain Selection**
+   - Always specify domain when known for better accuracy
+   - Use `/api/domains` to explore available options
+   - Let system auto-detect only when domain is truly unknown
+
+2. **Performance**
+   - Set `skip_expensive_metrics: true` for faster results when speed matters
+   - Use batch API for multiple texts instead of sequential single requests
+   - Cache `analysis_id` to regenerate reports without reanalysis
+
+3. **Accuracy**
+   - Provide clean, well-formatted text (remove excessive whitespace)
+   - Minimum 100 words recommended for reliable results
+   - Avoid mixing languages in single analysis
+
+4. **Rate Limiting**
+   - Implement exponential backoff on 429 responses
+   - Monitor `X-RateLimit-Remaining` header
+   - Upgrade tier if consistently hitting limits
+
+5. **Error Handling**
+   - Always check `status` field in response
+   - Log `request_id` for support requests
+   - Implement retry logic with jitter for transient errors
+
+### Security Recommendations
+
+1. **API Key Management**
+   - Rotate keys every 90 days
+   - Use separate keys for dev/staging/production
+   - Revoke compromised keys immediately
+
+2. **Data Privacy**
+   - Never send PII unless absolutely necessary
+   - Use client-side redaction before API calls
+   - Enable data retention policies in dashboard
+
+3. **Input Validation**
+   - Sanitize user input before sending to API
+   - Validate file types client-side
+   - Implement size limits before upload
+
+---
+
+## Version History:
+
+- **1.0.0** (2025-12-30): Initial release
+  - 6 forensic metrics
+  - 16 domain support
+  - PDF/JSON reporting
+  - Batch processing
+
+---
+
+## Appendix
+
+### Complete Domain List with Aliases
+
+```python
+DOMAIN_ALIASES = {
+    'general': ['default', 'generic'],
+    'academic': ['education', 'research', 'scholarly', 'university'],
+    'creative': ['fiction', 'literature', 'story', 'narrative'],
+    'ai_ml': ['ai', 'ml', 'machinelearning', 'neural'],
+    'software_dev': ['software', 'code', 'programming', 'dev'],
+    'technical_doc': ['technical', 'tech', 'documentation', 'manual'],
+    'engineering': ['engineer'],
+    'science': ['scientific'],
+    'business': ['corporate', 'commercial', 'enterprise'],
+    'legal': ['law', 'contract', 'court'],
+    'medical': ['healthcare', 'clinical', 'medicine', 'health'],
+    'journalism': ['news', 'reporting', 'media', 'press'],
+    'marketing': ['advertising', 'promotional', 'brand', 'sales'],
+    'social_media': ['social', 'casual', 'informal', 'posts'],
+    'blog_personal': ['blog', 'personal', 'diary', 'lifestyle'],
+    'tutorial': ['guide', 'howto', 'instructional', 'walkthrough']
+}
+```
+
+### Metric Weight Defaults
+
+```python
+DEFAULT_WEIGHTS = {
+    'perplexity': 0.25,
+    'entropy': 0.20,
+    'structural': 0.15,
+    'semantic': 0.15,
+    'linguistic': 0.15,
+    'multi_perturbation_stability': 0.10
+}
+```
+
+### Response Time Estimates
+
+| Operation | Min | Avg | Max | P95 |
+|-----------|-----|-----|-----|-----|
+| Text Analysis (500 words) | 1.2s | 2.3s | 4.5s | 3.8s |
+| File Analysis (PDF, 10 pages) | 2.5s | 4.1s | 8.2s | 6.9s |
+| Batch (10 texts) | 5.8s | 9.2s | 15.3s | 13.1s |
+| Report Generation | 0.3s | 0.8s | 2.1s | 1.5s |
+
+---
+
+*Last Updated: December 30, 2025*  
+*API Version: 1.0.0*  
+*Documentation Version: 1.0.0*

docs/ARCHITECTURE.md

@@ -0,0 +1,821 @@
+# TEXT-AUTH: System Architecture Documentation
+
+> TEXT-AUTH is an evidence-first, domain-aware AI text detection system
+> designed around independent signals, calibrated aggregation, and
+> explainability rather than black-box classification.
+
+---
+
+## Table of Contents
+1. [System Overview](#system-overview)
+2. [High-Level Architecture](#high-level-architecture)
+3. [Layer-by-Layer Architecture](#layer-by-layer-architecture)
+4. [Data Flow](#data-flow)
+5. [Technology Stack](#technology-stack)
+
+---
+
+## System Overview
+
+**TEXT-AUTH** is a sophisticated AI text detection system that employs multiple machine learning metrics and ensemble methods to determine whether text is synthetically generated, authentically written, or hybrid content.
+
+### Key Capabilities
+- **Multi-Metric Analysis**: 6 independent detection metrics (Structural, Perplexity, Entropy, Semantic, Linguistic, Multi-Perturbation Stability)
+- **Domain-Aware Calibration**: Adaptive thresholds for 16 text domains (Academic, Creative, Technical, etc.)
+- **Ensemble Aggregation**: Confidence-weighted combination with uncertainty quantification
+- **Sentence-Level Highlighting**: Visual feedback with probability scores
+- **Comprehensive Reporting**: JSON and PDF reports with detailed analysis
+
+### Design Principles
+- **Modular Architecture**: Clean separation of concerns across layers
+- **Fail-Safe Design**: Graceful degradation with fallback strategies
+- **Parallel Processing**: Multi-threaded metric execution for performance
+- **Domain Expertise**: Specialized thresholds calibrated per content type
+
+
+## Why Multi-Metric Instead of a Single Classifier?
+
+- Single classifiers overfit stylistic artifacts
+- LLMs rapidly adapt to detectors
+- Independent statistical signals decay slower
+- Ensemble disagreement is itself evidence
+
+---
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Presentation Layer"
+        UI[Web Interface/API]
+    end
+
+    subgraph "Application Layer"
+        ORCH[Detection Orchestrator]
+        ORCH --> |coordinates| PIPE[Processing Pipeline]
+    end
+
+    subgraph "Service Layer"
+        ENSEMBLE[Ensemble Classifier]
+        HIGHLIGHT[Text Highlighter]
+        REASON[Reasoning Generator]
+        REPORT[Report Generator]
+    end
+
+    subgraph "Processing Layer"
+        EXTRACT[Document Extractor]
+        TEXTPROC[Text Processor]
+        DOMAIN[Domain Classifier]
+        LANG[Language Detector]
+    end
+
+    subgraph "Metrics Layer"
+        STRUCT[Structural Metric]
+        PERP[Perplexity Metric]
+        ENT[Entropy Metric]
+        SEM[Semantic Metric]
+        LING[Linguistic Metric]
+        MPS[Multi-Perturbation Stability]
+    end
+
+    subgraph "Model Layer"
+        MANAGER[Model Manager]
+        REGISTRY[Model Registry]
+        CACHE[(Model Cache)]
+    end
+
+    subgraph "Configuration Layer"
+        CONFIG[Settings]
+        ENUMS[Enums]
+        SCHEMAS[Data Schemas]
+        CONSTANTS[Constants]
+        THRESHOLDS[Domain Thresholds]
+    end
+
+    UI --> ORCH
+    
+    ORCH --> EXTRACT
+    ORCH --> TEXTPROC
+    ORCH --> DOMAIN
+    ORCH --> LANG
+    
+    ORCH --> STRUCT
+    ORCH --> PERP
+    ORCH --> ENT
+    ORCH --> SEM
+    ORCH --> LING
+    ORCH --> MPS
+    
+    ORCH --> ENSEMBLE
+    ENSEMBLE --> HIGHLIGHT
+    ENSEMBLE --> REASON
+    ENSEMBLE --> REPORT
+    
+    STRUCT --> MANAGER
+    PERP --> MANAGER
+    ENT --> MANAGER
+    SEM --> MANAGER
+    LING --> MANAGER
+    MPS --> MANAGER
+    DOMAIN --> MANAGER
+    LANG --> MANAGER
+    
+    MANAGER --> REGISTRY
+    MANAGER --> CACHE
+    
+    ORCH --> CONFIG
+    ENSEMBLE --> THRESHOLDS
+
+    style UI fill:#e1f5ff
+    style ORCH fill:#fff3e0
+    style ENSEMBLE fill:#f3e5f5
+    style MANAGER fill:#e8f5e9
+    style CONFIG fill:#fce4ec
+```
+
+---
+
+## Layer-by-Layer Architecture
+
+### 1. Configuration Layer (`config/`)
+
+The foundation layer providing enums, schemas, constants, and domain-specific thresholds.
+
+```mermaid
+graph LR
+    subgraph "Configuration Layer"
+        direction TB
+        
+        ENUMS["enums.py
+        Domain, Language, Script, 
+        ModelType ConfidenceLevel"]
+        
+        SCHEMAS["schemas.py
+        ModelConfig, ProcessedText, MetricResult, EnsembleResult,
+        DetectionResult"]
+        
+        CONSTANTS["constants.py
+        TextProcessingParams, MetricParams,
+        EnsembleParams"]
+        
+        THRESHOLDS["threshold_config.py
+        DomainThresholds 16, 
+        Domain Configs MetricThresholds"]
+        
+        MODELCFG["model_config.py
+        Model Registry, Model Groups, Default Weights"]
+        
+        SETTINGS["settings.py
+        App Settings, Paths, Feature Flags"]
+    end
+    
+    ENUMS -.->|used by| SCHEMAS
+    ENUMS -.->|used by| THRESHOLDS
+    SCHEMAS -.->|used by| CONSTANTS
+    THRESHOLDS -.->|imports| ENUMS
+    MODELCFG -.->|imports| ENUMS
+    
+    style ENUMS fill:#ffebee
+    style SCHEMAS fill:#fff3e0
+    style CONSTANTS fill:#e8f5e9
+    style THRESHOLDS fill:#e1f5ff
+    style MODELCFG fill:#f3e5f5
+    style SETTINGS fill:#fce4ec
+```
+
+**Key Components:**
+- **enums.py**: Core enumerations (Domain, Language, Script, ModelType, ConfidenceLevel)
+- **schemas.py**: Data classes for structured data exchange
+- **constants.py**: Frozen dataclasses with hyperparameters for each metric
+- **threshold_config.py**: Domain-specific thresholds for 16 domains
+- **model_config.py**: Model registry with download priorities and configurations
+- **settings.py**: Application settings with Pydantic validation
+
+---
+
+### 2. Model Abstraction Layer (`models/`)
+
+Conceptual model abstraction layer used by metrics for centralized loading and reuse - loading, caching, and providing unified access.
+
+```mermaid
+graph TB
+    subgraph "Model Layer"
+        direction TB
+        
+        MANAGER["Model Manager
+        Singleton Pattern Lazy Loading"]
+        
+        REGISTRY["Model Registry 
+        10 Model Configs Priority Groups"]
+        
+        subgraph "Model Cache"
+            direction LR
+            GPT2[GPT-2548MBPerplexity/MPS]
+            MINILM[MiniLM-L6-v280MBSemantic]
+            SPACY[spaCy sm13MBLinguistic]
+            ROBERTA[RoBERTa500MBDomain Classifier]
+            DISTIL[DistilRoBERTa330MBMPS Mask]
+            XLM[XLM-RoBERTa1100MBLanguage Detection]
+        end
+        
+        STATS[Usage StatisticsTracking Performance Metrics]
+    end
+    
+    MANAGER -->|loads from| REGISTRY
+    MANAGER -->|manages| GPT2
+    MANAGER -->|manages| MINILM
+    MANAGER -->|manages| SPACY
+    MANAGER -->|manages| ROBERTA
+    MANAGER -->|manages| DISTIL
+    MANAGER -->|manages| XLM
+    MANAGER -->|tracks| STATS
+    
+    REGISTRY -.->|defines| GPT2
+    REGISTRY -.->|defines| MINILM
+    REGISTRY -.->|defines| SPACY
+    
+    style MANAGER fill:#e3f2fd
+    style REGISTRY fill:#f3e5f5
+    style STATS fill:#fff3e0
+```
+
+**Key Features:**
+- **Lazy Loading**: Models loaded on-demand
+- **Caching Strategy**: LRU cache with max 5 models
+- **Usage Tracking**: Statistics for optimization
+- **Priority Groups**: Essential, Extended, Optional
+- **Total Size**: ~2.8GB for all models
+
+---
+
+### 3. Processing Layer (`processors/`)
+
+Handles document extraction, text preprocessing, domain classification, and language detection.
+
+```mermaid
+graph TB
+    subgraph "Processing Layer"
+        direction TB
+        
+        subgraph "Document Extraction"
+            EXTRACT[Document Extractor]
+            EXTRACT -->|PDF| PYPDF[PyMuPDF Primary]
+            EXTRACT -->|PDF| PDFPLUMB[pdfplumber Fallback]
+            EXTRACT -->|PDF| PYPDF2[PyPDF2 Fallback]
+            EXTRACT -->|DOCX| DOCX[python-docx]
+            EXTRACT -->|HTML| BS4[BeautifulSoup4]
+            EXTRACT -->|RTF| RTF[Basic Parser]
+            EXTRACT -->|TXT| TXT[Chardet Encoding]
+        end
+        
+        subgraph "Text Processing"
+            TEXTPROC[Text Processor]
+            TEXTPROC --> CLEAN[Unicode NormalizationURL/Email RemovalWhitespace Cleaning]
+            TEXTPROC --> SPLIT[Smart Sentence SplittingAbbreviation HandlingWord Tokenization]
+            TEXTPROC --> VALIDATE[Length ValidationQuality ChecksStatistics]
+        end
+        
+        subgraph "Domain Classification"
+            DOMAIN[Domain Classifier]
+            DOMAIN --> ZERO[Heuristic + optional model-assisted domain inference RoBERTa/DeBERTa]
+            DOMAIN --> LABELS[16 Domain LabelsMulti-Label Candidates]
+            DOMAIN --> THRESH[Domain-SpecificThreshold Selection]
+        end
+        
+        subgraph "Language Detection"
+            LANG[Language Detector]
+            LANG --> MODEL[XLM-RoBERTaChunk-Based Analysis]
+            LANG --> FALLBACK[langdetect Library]
+            LANG --> HEURISTIC[Script DetectionCharacter Analysis]
+        end
+    end
+    
+    EXTRACT -->|ProcessedText| TEXTPROC
+    TEXTPROC -->|Cleaned Text| DOMAIN
+    TEXTPROC -->|Cleaned Text| LANG
+    
+    style EXTRACT fill:#e8f5e9
+    style TEXTPROC fill:#fff3e0
+    style DOMAIN fill:#e1f5ff
+    style LANG fill:#f3e5f5
+```
+
+**Processing Pipeline:**
+1. **Document Extraction**: Multi-format support with fallback strategies
+2. **Text Cleaning**: Unicode normalization, noise removal, validation
+3. **Domain Classification**: Zero-shot classification with confidence scores
+4. **Language Detection**: Multi-strategy approach with script analysis
+
+---
+
+### 4. Metrics Layer (`metrics/`)
+
+Six independent detection metrics analyzing different text characteristics.
+
+```mermaid
+graph TB
+    subgraph "Metrics Layer"
+        direction TB
+        
+        BASE[Base MetricAbstract ClassCommon Interface]
+        
+        subgraph "Statistical Metrics"
+            STRUCT[Structural MetricNo ML ModelStatistical Features]
+            STRUCT --> SF1[Sentence Length DistributionBurstiness ScoreReadability]
+            STRUCT --> SF2[N-gram DiversityType-Token RatioRepetition Patterns]
+        end
+        
+        subgraph "ML-Based Metrics"
+            PERP[Perplexity MetricGPT-2 ModelText Predictability]
+            PERP --> PF1[Overall PerplexitySentence-Level PerplexityCross-Entropy]
+            PERP --> PF2[Chunk AnalysisVariance ScoringNormalization]
+            
+            ENT[Entropy MetricGPT-2 TokenizerRandomness Analysis]
+            ENT --> EF1[Character EntropyWord EntropyToken Entropy]
+            ENT --> EF2[Token DiversitySequence UnpredictabilityPattern Detection]
+            
+            SEM[Semantic MetricMiniLM EmbeddingsCoherence Analysis]
+            SEM --> SF3[Sentence SimilarityTopic ConsistencyCoherence Score]
+            SEM --> SF4[Repetition DetectionTopic DriftContextual Consistency]
+            
+            LING[Linguistic MetricspaCy NLPGrammar Analysis]
+            LING --> LF1[POS DiversityPOS EntropySyntactic Complexity]
+            LING --> LF2[Grammatical PatternsWriting StylePattern Detection]
+            
+            MPS[Multi-PerturbationGPT-2 + DistilRoBERTaStability Analysis]
+            MPS --> MF1[Text PerturbationLikelihood CalculationStability Score]
+            MPS --> MF2[Curvature AnalysisChunk StabilityVariance Scoring]
+        end
+    end
+    
+    BASE -.->|inherited by| STRUCT
+    BASE -.->|inherited by| PERP
+    BASE -.->|inherited by| ENT
+    BASE -.->|inherited by| SEM
+    BASE -.->|inherited by| LING
+    BASE -.->|inherited by| MPS
+    
+    style BASE fill:#ffebee
+    style STRUCT fill:#e8f5e9
+    style PERP fill:#fff3e0
+    style ENT fill:#e1f5ff
+    style SEM fill:#f3e5f5
+    style LING fill:#fce4ec
+    style MPS fill:#fff9c4
+```
+
+**Metric Characteristics:**
+
+| Metric | Model Required | Complexity | Typical Influence Range (Indicative) |
+|--------|---------------|------------|--------------|
+| Structural | ❌ | Low | 15-20% |
+| Perplexity | GPT-2 | Medium | 20-27% |
+| Entropy | GPT-2 Tokenizer | Medium | 13-17% |
+| Semantic | MiniLM | Medium | 18-20% |
+| Linguistic | spaCy | Medium | 12-16% |
+| MPS | GPT-2 + DistilRoBERTa | High | 8-10% |
+
+> *Actual weights are dynamically calibrated per domain and configuration.*
+
+---
+
+### 5. Service Layer (`services/`)
+
+Coordinates ensemble aggregation, highlighting, reasoning generation, and orchestration.
+
+```mermaid
+graph TB
+    subgraph "Service Layer"
+        direction TB
+        
+        subgraph "Orchestrator"
+            ORCH[Detection OrchestratorPipeline Coordinator]
+            ORCH --> PIPE[Processing Pipeline6-Step Execution]
+            PIPE --> STEP1[1. Text Preprocessing]
+            PIPE --> STEP2[2. Language Detection]
+            PIPE --> STEP3[3. Domain Classification]
+            PIPE --> STEP4[4. Metric ExecutionParallel/Sequential]
+            PIPE --> STEP5[5. Ensemble Aggregation]
+            PIPE --> STEP6[6. Result Compilation]
+        end
+        
+        subgraph "Ensemble Classifier"
+            ENSEMBLE[Ensemble ClassifierMulti-Strategy Aggregation]
+            ENSEMBLE --> METHOD1[Confidence CalibratedSigmoid Weighting]
+            ENSEMBLE --> METHOD2[Consensus BasedAgreement Rewards]
+            ENSEMBLE --> METHOD3[Domain WeightedStatic Weights]
+            ENSEMBLE --> METHOD4[Simple AverageFallback]
+            ENSEMBLE --> CALC[Uncertainty QuantificationConsensus AnalysisConfidence Scoring]
+        end
+        
+        subgraph "Highlighter"
+            HIGHLIGHT[Text HighlighterSentence-Level Analysis]
+            HIGHLIGHT --> COLORS[4-Color SystemAuthentic/UncertainHybrid/Synthetic]
+            HIGHLIGHT --> SENTENCE[Sentence EnsembleDomain AdjustmentsTooltip Generation]
+        end
+        
+        subgraph "Reasoning"
+            REASON[Reasoning GeneratorExplainable AI]
+            REASON --> SUMMARY[Executive SummaryVerdict Explanation]
+            REASON --> INDICATORS[Key IndicatorsMetric Breakdown]
+            REASON --> EVIDENCE[Supporting EvidenceContradicting Evidence]
+            REASON --> RECOM[RecommendationsUncertainty Analysis]
+        end
+    end
+    
+    ORCH -->|coordinates| ENSEMBLE
+    ORCH -->|uses| HIGHLIGHT
+    ORCH -->|uses| REASON
+    ENSEMBLE -->|provides| HIGHLIGHT
+    ENSEMBLE -->|provides| REASON
+    
+    style ORCH fill:#fff3e0
+    style ENSEMBLE fill:#e3f2fd
+    style HIGHLIGHT fill:#f3e5f5
+    style REASON fill:#e8f5e9
+```
+
+**Service Features:**
+- **Parallel Execution**: ThreadPoolExecutor for metric computation
+- **Ensemble Methods**: 4 aggregation strategies with fallbacks
+- **Sentence Highlighting**: 4-category color system (Authentic/Uncertain/Hybrid/Synthetic)
+- **Explainable AI**: Detailed reasoning with metric contributions
+
+---
+
+### 6. Reporter Layer (`reporter/`)
+
+Generates comprehensive reports in multiple formats.
+
+```mermaid
+graph TB
+    subgraph "Reporter Layer"
+        direction TB
+        
+        REPORT[Report Generator]
+        
+        subgraph "JSON Report"
+            JSON[Structured JSON]
+            JSON --> META[Report MetadataTimestampVersion]
+            JSON --> RESULTS[Overall ResultsProbabilitiesConfidence]
+            JSON --> METRICS[Detailed MetricsSub-metricsWeights]
+            JSON --> REASONING[Detection ReasoningEvidenceRecommendations]
+            JSON --> HIGHLIGHT[Highlighted SentencesColor ClassesProbabilities]
+            JSON --> PERF[Performance MetricsExecution TimesWarnings/Errors]
+        end
+        
+        subgraph "PDF Report"
+            PDF[Professional PDF]
+            PDF --> PAGE1[Page 1: Executive SummaryVerdict, Stats, Reasoning]
+            PDF --> PAGE2[Page 2: Content AnalysisDomain, Metrics, Weights]
+            PDF --> PAGE3[Page 3: Structural & Entropy]
+            PDF --> PAGE4[Page 4: Perplexity & Semantic]
+            PDF --> PAGE5[Page 5: Linguistic & MPS]
+            PDF --> PAGE6[Page 6: Recommendations]
+            
+            STYLE[Premium Styling]
+            STYLE --> COLORS[Color SchemeBlue/Green/Red/Purple]
+            STYLE --> TABLES[Professional TablesCharts, Metrics]
+            STYLE --> LAYOUT[Multi-Page LayoutHeaders, Footers]
+        end
+    end
+    
+    REPORT -->|generates| JSON
+    REPORT -->|generates| PDF
+    PDF -->|uses| STYLE
+    
+    style REPORT fill:#fff3e0
+    style JSON fill:#e8f5e9
+    style PDF fill:#e3f2fd
+    style STYLE fill:#f3e5f5
+```
+
+**Report Formats:**
+- **JSON**: Machine-readable with complete data
+- **PDF**: Human-readable with professional formatting
+- **Charts**: Pie charts for probability distribution
+- **Tables**: Metric contributions, detailed sub-metrics
+- **Styling**: Color-coded, multi-page layout with branding
+
+---
+
+## Data Flow
+
+### Complete Detection Pipeline
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Orchestrator
+    participant Processors
+    participant Metrics
+    participant Ensemble
+    participant Services
+    participant Reporter
+
+    User->>Orchestrator: analyze(text)
+    
+    Note over Orchestrator: Step 1: Preprocessing
+    Orchestrator->>Processors: TextProcessor.process()
+    Processors-->>Orchestrator: ProcessedText
+    
+    Note over Orchestrator: Step 2: Language Detection
+    Orchestrator->>Processors: LanguageDetector.detect()
+    Processors-->>Orchestrator: LanguageResult
+    
+    Note over Orchestrator: Step 3: Domain Classification
+    Orchestrator->>Processors: DomainClassifier.classify()
+    Processors-->>Orchestrator: DomainPrediction
+    
+    Note over Orchestrator: Step 4: Parallel Metric Execution
+    par Structural
+        Orchestrator->>Metrics: Structural.compute()
+        Metrics-->>Orchestrator: MetricResult
+    and Perplexity
+        Orchestrator->>Metrics: Perplexity.compute()
+        Metrics-->>Orchestrator: MetricResult
+    and Entropy
+        Orchestrator->>Metrics: Entropy.compute()
+        Metrics-->>Orchestrator: MetricResult
+    and Semantic
+        Orchestrator->>Metrics: Semantic.compute()
+        Metrics-->>Orchestrator: MetricResult
+    and Linguistic
+        Orchestrator->>Metrics: Linguistic.compute()
+        Metrics-->>Orchestrator: MetricResult
+    and MPS
+        Orchestrator->>Metrics: MPS.compute()
+        Metrics-->>Orchestrator: MetricResult
+    end
+    
+    Note over Orchestrator: Step 5: Ensemble Aggregation
+    Orchestrator->>Ensemble: predict(metric_results, domain)
+    Ensemble-->>Orchestrator: EnsembleResult
+    
+    Note over Orchestrator: Step 6: Services
+    Orchestrator->>Services: generate_highlights()
+    Services-->>Orchestrator: HighlightedSentences
+    
+    Orchestrator->>Services: generate_reasoning()
+    Services-->>Orchestrator: DetailedReasoning
+    
+    Orchestrator->>Reporter: generate_report()
+    Reporter-->>Orchestrator: Report Files
+    
+    Orchestrator-->>User: DetectionResult
+```
+
+### Ensemble Aggregation Flow
+
+```mermaid
+graph TD
+    START[Metric Results] --> FILTER[Filter Valid MetricsRemove Errors]
+    FILTER --> WEIGHTS[Get Domain WeightsBase Weights]
+    
+    WEIGHTS --> METHOD{Primary Method?}
+    
+    METHOD -->|Confidence Calibrated| CONF[Sigmoid ConfidenceAdjustment]
+    METHOD -->|Consensus Based| CONS[AgreementCalculation]
+    METHOD -->|Domain Weighted| DOMAIN[Static DomainWeights]
+    
+    CONF --> AGGREGATE[Weighted Aggregation]
+    CONS --> AGGREGATE
+    DOMAIN --> AGGREGATE
+    
+    AGGREGATE --> NORMALIZE[Normalize to 1.0]
+    
+    NORMALIZE --> CALC[Calculate Metrics]
+    CALC --> CONFIDENCE[Overall ConfidenceBase + Agreement+ Certainty + Quality]
+    CALC --> UNCERTAINTY[Uncertainty ScoreVariance + Confidence+ Decision]
+    CALC --> CONSENSUS[Consensus LevelStd Dev Analysis]
+    
+    CONFIDENCE --> THRESHOLD[Apply AdaptiveThreshold]
+    UNCERTAINTY --> THRESHOLD
+    
+    THRESHOLD --> VERDICT{Verdict}
+    VERDICT -->|Synthetic >= 0.6| SYNTH[Synthetically-Generated]
+    VERDICT -->|Authentic >= 0.6| AUTH[Authentically-Written]
+    VERDICT -->|Hybrid > 0.25| HYBRID[Hybrid]
+    VERDICT -->|Uncertain| UNC[Uncertain]
+    
+    SYNTH --> REASON[Generate Reasoning]
+    AUTH --> REASON
+    HYBRID --> REASON
+    UNC --> REASON
+    
+    REASON --> RESULT[EnsembleResult]
+    
+    style START fill:#e8f5e9
+    style RESULT fill:#e3f2fd
+    style SYNTH fill:#ffebee
+    style AUTH fill:#e8f5e9
+    style HYBRID fill:#fff3e0
+    style UNC fill:#f5f5f5
+```
+
+---
+
+## Technology Stack
+
+### Core Technologies
+
+```mermaid
+graph LR
+    subgraph "Language & Runtime"
+        PYTHON[Python 3.10+]
+        CONDA[Conda Environment]
+    end
+    
+    subgraph "ML Frameworks"
+        TORCH[PyTorch]
+        HF[HuggingFace Transformers]
+        SPACY[spaCy]
+        SKLEARN[scikit-learn]
+    end
+    
+    subgraph "NLP Models"
+        GPT2[GPT-2Perplexity/MPS]
+        MINILM[MiniLM-L6-v2Semantic]
+        ROBERTA[RoBERTaDomain Classify]
+        DISTIL[DistilRoBERTaMPS Mask]
+        XLM[XLM-RoBERTaLanguage Detect]
+        SPACYMODEL[en_core_web_smLinguistic]
+    end
+    
+    subgraph "Document Processing"
+        PYMUPDF[PyMuPDF]
+        PDFPLUMBER[pdfplumber]
+        PYPDF2[PyPDF2]
+        DOCX[python-docx]
+        BS4[BeautifulSoup4]
+    end
+    
+    subgraph "Utilities"
+        NUMPY[NumPy]
+        PYDANTIC[Pydantic]
+        LOGURU[Loguru]
+        REPORTLAB[ReportLab]
+    end
+    
+    PYTHON --> TORCH
+    TORCH --> HF
+    HF --> GPT2
+    HF --> MINILM
+    HF --> ROBERTA
+    HF --> DISTIL
+    HF --> XLM
+    PYTHON --> SPACY
+    SPACY --> SPACYMODEL
+    
+    style PYTHON fill:#306998
+    style TORCH fill:#ee4c2c
+    style HF fill:#ff6f00
+    style SPACY fill:#09a3d5
+```
+
+### Dependencies Summary
+
+| Category | Libraries | Purpose |
+|----------|-----------|---------|
+| **ML Core** | PyTorch, Transformers, spaCy | Model execution, NLP |
+| **Document** | PyMuPDF, pdfplumber, python-docx | Multi-format extraction |
+| **Analysis** | NumPy, scikit-learn | Numerical computation |
+| **Validation** | Pydantic | Data validation |
+| **Logging** | Loguru | Structured logging |
+| **Reporting** | ReportLab | PDF generation |
+
+---
+
+## Deployment Architecture
+
+```mermaid
+graph TB
+    subgraph "Deployment Options"
+        direction TB
+        
+        subgraph "Standalone Application"
+            SCRIPT[Python Scripts]
+        end
+        
+        subgraph "Web Application"
+            FASTAPI[FastAPI Server]
+        end
+        
+        subgraph "API Service"
+            REST[REST API Endpoints]
+            BATCH[Batch Processing]
+            ASYNC[Async Workers]
+        end
+        
+        subgraph "Infrastructure"
+            DOCKER[Docker Container]
+            GPU[GPU SupportOptional]
+            STORAGE[Model Cache2.8GB]
+        end
+    end
+    
+    FASTAPI --> DOCKER
+    REST --> DOCKER
+    
+    DOCKER --> GPU
+    DOCKER --> STORAGE
+    
+    style FASTAPI fill:#e3f2fd
+    style DOCKER fill:#2496ed
+    style GPU fill:#76b900
+```
+
+### System Requirements
+
+- **Python**: 3.10+
+- **RAM**: 8GB minimum, 16GB recommended
+- **Storage**: 5GB (models + data)
+- **GPU**: Optional (CUDA/MPS for faster inference)
+- **CPU**: 4+ cores for parallel execution
+
+---
+
+## Performance Characteristics
+
+### Execution Modes
+
+```mermaid
+graph LR
+    subgraph "Sequential Mode"
+        S1[Metric 1] --> S2[Metric 2]
+        S2 --> S3[Metric 3]
+        S3 --> S4[Metric 4]
+        S4 --> S5[Metric 5]
+        S5 --> S6[Metric 6]
+        S6 --> SRESULT[~15-30s]
+    end
+    
+    subgraph "Parallel Mode"
+        P1[Metric 1]
+        P2[Metric 2]
+        P3[Metric 3]
+        P4[Metric 4]
+        P5[Metric 5]
+        P6[Metric 6]
+        
+        P1 --> PRESULT[~8-12s]
+        P2 --> PRESULT
+        P3 --> PRESULT
+        P4 --> PRESULT
+        P5 --> PRESULT
+        P6 --> PRESULT
+    end
+    
+    style SRESULT fill:#ffebee
+    style PRESULT fill:#e8f5e9
+```
+
+### Metric Execution Times
+
+| Metric | Avg Time | Complexity | Model Size |
+|--------|----------|------------|------------|
+| Structural | 0.5-1s | Low | 0MB |
+| Perplexity | 2-4s | Medium | 548MB |
+| Entropy | 1-2s | Medium |  ~50MB (shared) |
+| Semantic | 3-5s | Medium | 80MB |
+| Linguistic | 2-3s | Medium | 13MB |
+| MPS | 5-10s | High | 878MB (GPT-2 + DistilRoBERTa) |
+
+**Total Sequential**: ~15-25 seconds  
+**Total Parallel**: ~8-12 seconds (limited by slowest metric)
+
+---
+
+## Security & Privacy
+
+### Data Handling
+
+```mermaid
+graph TD
+    INPUT[Text Input] --> PROCESS[Processing]
+    PROCESS --> MEMORY[In-Memory Only]
+    MEMORY --> ANALYSIS[Analysis]
+    ANALYSIS --> CLEANUP[Auto Cleanup]
+    
+    MODELS[Model Cache] -.->|Read Only| ANALYSIS
+    
+    REPORTS[Optional Reports] --> STORAGE[Local Storage Only]
+    
+    CLEANUP --> DISCARD[Data Discarded]
+    
+    style INPUT fill:#e3f2fd
+    style MEMORY fill:#fff3e0
+    style CLEANUP fill:#e8f5e9
+    style DISCARD fill:#ffebee
+```
+
+### Security Features
+- ✅ **No External Data Transmission**: All processing local
+- ✅ **No Data Persistence**: Text data not stored by default
+- ✅ **Model Integrity**: Checksums for downloaded models
+- ✅ **Input Validation**: Pydantic schemas for all inputs
+- ✅ **Error Isolation**: Graceful degradation, no information leakage
+
+---
+
+> This system does not claim ground truth authorship. It estimates probabilistic authenticity signals based on measurable text properties.

docs/BLOGPOST.md

@@ -1,398 +1,448 @@
-# Building AI Text Authentication Platform: From Research to Production
+# Building TEXT-AUTH: An Evidence-First System for Forensic Text Analysis
 
-*How we built a multi-metric ensemble system that detects AI-generated content with precision while maintaining explainability*
+> *How a multi-metric, domain-aware forensic platform was implemented for probabilistic text authenticity assessment — without authorship claims.*
 
 ---
 
-## Introduction: The Authenticity Crisis
+## Introduction: Why Text Forensics Needs a Rethink
 
-Picture this: A university professor reviewing final essays at 2 AM, unable to distinguish between genuinely crafted arguments and ChatGPT's polished prose. A hiring manager sorting through 500 applications, knowing some candidates never wrote their own cover letters. A publisher receiving article submissions that sound professional but lack the human spark that made their platform valuable.
+The widespread availability of high-quality generative language systems has fundamentally altered the landscape of written communication. In education, publishing, journalism, and enterprise domains, stakeholders increasingly confront a complex forensic question:
 
-This isn't speculation—it's the current reality. Recent data shows 60% of students regularly use AI writing tools, while 89% of teachers report receiving AI-written submissions. The market for content authenticity has exploded to $20 billion annually, growing at 42% year-over-year.
+> Does this text exhibit statistical, linguistic, and semantic patterns consistent with organically composed language, or does it display measurable characteristics associated with algorithmically regularized generation?
 
-The AI Text Authentication Platform emerged from a simple question: **Can we build a detector that's accurate enough for real-world consequences, transparent enough to justify those consequences, and sophisticated enough to handle the nuances of human versus AI writing?**
+Traditional detection systems attempt to answer this with binary classifications: "Human" or "AI." This approach fails in practice because real-world text exists along a continuum—often hybrid, domain-specific, edited, paraphrased, or collaboratively produced.
 
----
-
-## Why Most Detectors Fail
+TEXT-AUTH was conceived not as another detector, but as a forensic analysis system that evaluates observable textual properties and reports probabilistic consistency signals with explicit reasoning and uncertainty quantification. It provides evidence, not verdicts.
 
-Before diving into our solution, let's understand why existing AI detectors struggle. Most commercial tools rely primarily on a single metric called **perplexity**—essentially measuring how "surprised" a language model is when reading text.
+---
 
-The logic seems sound: AI-generated text follows predictable patterns because it's sampling from probability distributions. Human writing takes unexpected turns, uses unusual word combinations, and breaks rules that AI typically respects.
+## Design Philosophy: Evidence, Not Attribution
 
-But here's where this breaks down:
+At its core, TEXT-AUTH operates under a strict methodological constraint:
 
-**Domain Variance**: Academic papers are *supposed* to be structured and predictable. Formal writing naturally exhibits low perplexity. Meanwhile, creative fiction deliberately embraces unpredictability. A single threshold fails across contexts.
+> The system does not determine who wrote a text.  
+> It evaluates measurable linguistic and statistical patterns present in the text.
 
-**False Positives**: Well-edited human writing can look "AI-like." International students whose second language is English often write in more formal, structured patterns. Non-native speakers get flagged at disproportionate rates.
+This distinction is both technical and ethical. By focusing on patterns rather than provenance, the system avoids the philosophical quagmire of authorship attribution while providing actionable forensic intelligence.
 
-**Gaming the System**: Simple paraphrasing, synonym substitution, or adding deliberate typos can fool perplexity-based detectors. As soon as detection methods become known, adversarial techniques emerge.
+All outputs are framed as probabilistic assessments accompanied by:
 
-**No Explainability**: Most detectors output a percentage with minimal justification. When a student's academic future hangs in the balance, "78% AI-generated" isn't enough—you need to explain *why*.
+- Explicit confidence intervals
+- Quantified uncertainty scores
+- Domain-specific calibration context
+- Sentence-level evidence annotation
 
-The industry reports false positive rates of 15-20% for single-metric detectors. In high-stakes environments like academic integrity proceedings or hiring decisions, this is unacceptable.
+This architecture makes TEXT-AUTH suitable for high-stakes workflows where explainability, auditability, and human judgment remain essential components of decision-making.
 
 ---
 
-## Our Approach: Six Independent Lenses
-
-Rather than betting everything on one metric, we designed a system that analyzes text through six completely orthogonal dimensions—think of them as six expert judges, each looking at the text from a different angle.
+## Core Architectural Principles
 
-### 1. Perplexity Analysis (25% Weight)
+TEXT-AUTH implements five foundational principles that differentiate it from conventional detection systems:
 
-**What it measures**: How predictable the text is to a language model.
+### 1. Multi-Dimensional Analysis
 
-**The mathematics**: Perplexity is calculated as the exponential of the average negative log-probability of each word given its context:
+Instead of relying on a single metric (typically perplexity), the system evaluates six orthogonal forensic signals, each capturing distinct aspects of textual consistency. This multi-dimensional approach provides robustness against adversarial manipulation—while individual metrics can be gamed, simultaneously gaming all six requires sophisticated effort that often produces other detectable anomalies.
 
-```math
-Perplexity = \exp\left(-\frac{1}{N}\sum_{i=1}^N \log P(w_i\mid context)\right)
-```
+### 2. Domain-Aware Calibration
 
-where N is the number of tokens, and P(wᵢ | context) is the probability the model assigns to word i given the preceding words.
+The system recognizes that different writing genres exhibit different baseline characteristics. Academic papers naturally demonstrate lower perplexity than creative fiction. Legal documents show different structural patterns than social media posts. TEXT-AUTH implements sixteen domain-specific configurations, each with calibrated thresholds and metric weights, reducing false positives by 15–20% compared to generic detection approaches.
 
-**Why it matters**: AI models generate text by sampling from these probability distributions. Text created this way naturally aligns with what the model considers "likely." Human writers don't think in probability distributions—they write based on meaning, emotion, and rhetorical effect.
+### 3. Explicit Uncertainty Modeling
 
-**The limitation**: Formal writing genres (academic, technical, legal) naturally exhibit low perplexity. That's why perplexity is only 25% of our decision, not 100%.
+Rather than forcing certainty, the system explicitly quantifies and reports uncertainty through a composite score combining:
 
-### 2. Entropy Measurement (20% Weight)
+- Inter-metric disagreement (variance)
+- Individual metric confidence levels
+- Distance from decision boundaries
 
-**What it measures**: Vocabulary diversity and unpredictability at the token level.
+High uncertainty triggers explicit recommendations for human review rather than automated decisions.
 
-**The mathematics**: We use Shannon entropy across the token distribution:
+### 4. Granular Sentence-Level Analysis
 
-```math
-H(X) = -Σ p(x_i) * log₂ p(x_i)
-```
+Instead of providing a single document-level score, the system performs sentence-by-sentence forensic evaluation, producing color-coded visualizations that highlight where statistical anomalies occur. This granular approach provides actionable insights for editing, revision, and targeted review.
 
-where p(xᵢ) is the probability of token i appearing in the text.
+### 5. Transparent, Explainable Reasoning
 
-**Why it matters**: AI models, even with temperature sampling for randomness, tend toward moderate entropy levels. They avoid both repetition (too low) and chaos (too high). Humans naturally span a wider entropy range—some people write with rich vocabulary variation, others prefer consistent terminology.
+Every analysis includes human-readable explanations detailing:
 
-**Real-world insight**: Creative writers score higher on entropy. Technical writers score lower. Domain-aware calibration is essential.
+- Which metrics contributed most to the assessment
+- Specific text patterns that triggered detection
+- Domain context considerations
+- Uncertainty sources and confidence factors
 
-### 3. Structural Analysis (15% Weight)
+This transparency builds trust and enables informed decision-making.
 
-**What it measures**: Sentence length variation and rhythmic patterns.
+---
 
-**The mathematics**: We calculate two complementary metrics:
+## The Forensic Model: Six Orthogonal Signals
 
-**Burstiness** measures the relationship between variability and central tendency:
-```math
-Burstiness = \frac{\sigma - \mu}{\sigma + \mu}
-```
-where:
-- μ = mean sentence length
-- σ = standard deviation of sentence length
+TEXT-AUTH evaluates text through six independent analytical lenses, each examining different dimensions of linguistic behavior. These metrics were selected based on their statistical independence, computational feasibility, and demonstrated discriminative power across text genres.
 
-**Uniformity** captures how consistent sentence lengths are:
-```math
-Uniformity = 1 - \frac{\sigma}{\mu}
-```
+### 1. Statistical Predictability Analysis (Perplexity)
 
-where:
-- μ = mean sentence length
-- σ = standard deviation of sentence length
+**What it measures**: The average negative log-likelihood of tokens given their preceding context, quantifying how "surprised" a reference language model is by the text sequence.
 
+**Mathematical Foundation**:
 
-**Why it matters**: Human writing exhibits natural "burstiness"—some short, punchy sentences followed by longer, complex ones. This creates rhythm and emphasis. AI writing tends toward consistent medium-length sentences, creating an almost metronome-like uniformity.
+$$
+\text{Perplexity}(T) = \exp\left(-\frac{1}{N}\sum_{i=1}^{N} \log P(w_i \mid w_{<i})\right)
+$$
 
-**Example**: A human writer might use a three-word sentence for emphasis. Then follow with a lengthy, multi-clause explanation that builds context and nuance. AI rarely does this—it maintains steady pacing.
+**Forensic Insight**: Language models generate text by selecting tokens with high conditional probabilities, creating sequences that occupy high-probability regions of the language distribution. Human writing, in contrast, includes unexpected lexical choices, creative expressions, and domain-specific jargon that models find statistically "surprising."
 
-### 4. Semantic Coherence (15% Weight)
+**Domain Calibration**: Expected perplexity ranges differ significantly by genre. Academic writing naturally exhibits lower perplexity due to formal structure and technical terminology. Creative writing shows higher baseline perplexity due to stylistic variation. Social media content displays the highest natural perplexity due to informal language and idiosyncratic expression.
 
-**What it measures**: How smoothly ideas flow between consecutive sentences.
+---
 
-**The mathematics**: Using sentence embeddings, we calculate cosine similarity between adjacent sentences:
+### 2. Information Diversity Measurement (Entropy)
 
-```math
-Coherence = \frac{1}{n} \sum_{i=1}^{n-1} \cos(e_i, e_{i+1})
-```
+**What it measures**: The dispersion and unpredictability of token usage throughout the text, quantifying lexical richness and variation.
 
-where eᵢ represents the embedding vector for sentence i.
+**Mathematical Foundation**:
 
-**Why it matters**: Surprisingly, AI text often maintains *too much* coherence. Every sentence connects perfectly to the next in a smooth, logical progression. Human writing has more tangents, abrupt topic shifts, and non-linear thinking. We get excited, go off on tangents, then circle back.
+$$
+H(X) = -\sum_{i=1}^{n} p(x_i) \log_2 p(x_i)
+$$
 
-**The paradox**: Better coherence can actually indicate AI generation in certain contexts—human thought patterns aren't perfectly linear.
+**Forensic Insight**: Human-authored text typically exhibits higher lexical entropy due to expressive variation, nuanced vocabulary selection, and contextual adaptation. Algorithmically regularized text often shows more concentrated token distributions, with certain words and phrases appearing with unnatural frequency.
 
-### 5. Linguistic Complexity (15% Weight)
+**Visual Representation**:
 
-**What it measures**: Grammatical sophistication, syntactic patterns, and part-of-speech diversity.
+- Authentic Writing: ██░░░░░░░░ (High entropy, diverse distribution)
+- Synthetic Generation: ██████░░░░ (Lower entropy, concentrated distribution)
 
-**The approach**: We analyze parse tree depth, part-of-speech tag distribution, and syntactic construction variety using dependency parsing.
+---
 
-**Why it matters**: AI models exhibit systematic grammatical preferences. They handle certain syntactic constructions (like nested clauses) differently than humans. They show different patterns in passive voice usage, clause embedding, and transitional phrases.
+### 3. Structural Rhythm Analysis (Burstiness and Uniformity)
 
-**Domain sensitivity**: Academic writing demands high linguistic complexity. Social media writing can be grammatically looser. Our system adjusts expectations by domain.
+**What it measures**: Sentence-level variation patterns through two complementary metrics.
 
-### 6. Multi-Perturbation Stability (10% Weight)
+**Burstiness Coefficient**:
 
-**What it measures**: How robust the text's probability score is to small perturbations.
+$$
+B = \frac{\sigma_L - \mu_L}{\sigma_L + \mu_L} \quad \text{where } B \in [-1, 1]
+$$
 
-**The mathematics**: We generate multiple perturbed versions and measure deviation:
+Positive burstiness indicates varied sentence lengths; negative values indicate uniformity.
 
-```math
-Stability = \frac{1}{n} \sum_{j} \left| \log P(x) - \log P(x_{perturbed_j}) \right|
-```
+**Uniformity Metric**:
 
-**The insight**: This metric is based on cutting-edge research (DetectGPT). AI-generated text exhibits characteristic "curvature" in probability space. Because it originated from a model's probability distribution, small changes cause predictable shifts in likelihood. Human text behaves differently—it wasn't generated from this distribution, so perturbations show different patterns.
+$$
+U = 1 - \frac{\sigma_L}{\mu_L} \quad \text{for } \mu_L > 0
+$$
 
-**Computational cost**: This is our most expensive metric, requiring multiple model passes. We conditionally execute it only when other metrics are inconclusive.
+**Forensic Insight**: Human writing exhibits natural rhythm—short, punchy sentences for emphasis followed by longer, complex sentences for elaboration. This creates characteristic "burstiness." Language model outputs tend toward more uniform sentence structures, creating a metronome-like consistency that lacks natural rhythmic variation.
 
 ---
 
-## The Ensemble: More Than Simple Averaging
+### 4. Semantic Flow Evaluation (Coherence)
 
-Having six metrics is valuable, but the real innovation lies in how we combine them. This isn't simple averaging—our ensemble system implements **confidence-calibrated, domain-aware aggregation**.
+**What it measures**: The consistency of meaning between consecutive sentences using semantic embedding similarity.
 
-### Dynamic Weighting Based on Confidence
+**Mathematical Foundation**:
 
-Not all metric results deserve equal voice. If the perplexity metric returns a result with 95% confidence while the linguistic metric returns one with 45% confidence, we should weight them differently.
+$$
+\text{Coherence}(D) = \frac{1}{N_s-1} \sum_{i=1}^{N_s-1} \frac{\mathbf{e}_i \cdot \mathbf{e}_{i+1}}{\|\mathbf{e}_i\|\|\mathbf{e}_{i+1}\|}
+$$
 
-Our confidence adjustment uses a sigmoid function that emphasizes differences around the 0.5 confidence level:
+where $\mathbf{e}_i$ represents the embedding vector for sentence $i$.
 
-```
-weight_adjusted = base_weight × (1 / (1 + e^(-10(confidence - 0.5))))
-```
+**Forensic Insight**: Ironically, excessively high coherence can indicate algorithmic generation. Language models maintain remarkably consistent semantic flow through attention mechanisms. Human writing includes natural digressions, associative leaps, topic shifts, and rhetorical devices that create more variable coherence patterns.
 
-This creates non-linear scaling: highly confident metrics get amplified, while uncertain ones get significantly downweighted.
+**The Coherence Paradox**: In many contexts, better coherence actually provides evidence toward synthetic generation rather than organic composition.
 
-### Domain-Specific Calibration
+---
 
-Remember how we said academic writing naturally has low perplexity? Our system knows this. Before making a final decision, we classify the text into one of four primary domains: academic, technical, creative, or social media.
+### 5. Linguistic Pattern Analysis (Syntactic Complexity)
 
-For **academic content**, we:
-- Increase the weight of linguistic complexity (formal writing demands it)
-- Reduce perplexity sensitivity (structured writing is expected)
-- Raise the AI probability threshold (be more conservative with accusations)
+**What it measures**: Grammatical sophistication and syntactic variation through multiple sub-metrics:
 
-For **creative writing**, we:
-- Boost entropy and structural analysis weights (creativity shows variation)
-- Adjust perplexity expectations (good fiction can be unpredictable)
-- Focus on burstiness detection (rhythmic variation matters)
+**Part-of-Speech Diversity**:
 
-For **technical content**, we:
-- Maximize semantic coherence importance (logical flow is critical)
-- Set the highest AI threshold (false positives are most costly here)
-- Prioritize terminology consistency patterns
+$$
+\text{POS}_{\text{diversity}} = \frac{|\{\text{POS tags}\}|}{N_{\text{tokens}}}
+$$
 
-For **social media**, we:
-- Make perplexity the dominant signal (informal patterns are distinctive)
-- Relax linguistic complexity requirements (casual grammar is normal)
-- Accept higher entropy variation (internet language is wild)
+**Parse Tree Depth Distribution**:
 
-This domain adaptation alone improves accuracy by 15-20% compared to generic detectors.
+$$
+D_{\text{syntactic}} = \frac{1}{N_{\text{sentences}}} \sum_{i=1}^{N_{\text{sentences}}} \max_{\text{tokens}} \text{depth}(t)
+$$
 
-### Consensus Analysis
+**Forensic Insight**: Different writing styles exhibit characteristic syntactic fingerprints. Language models demonstrate systematic preferences for certain grammatical constructions, clause embeddings, and transitional patterns. Human writing shows greater syntactic irregularity, especially in longer passages where stylistic variation becomes more pronounced.
 
-Beyond individual confidence, we measure how much metrics agree with each other. If all six metrics produce similar AI probabilities, that's strong evidence. If they're scattered, that indicates uncertainty.
+---
 
-We calculate consensus as:
+### 6. Stability Under Perturbation
 
-```
-Consensus = 1 - min(1.0, σ_predictions × 2)
-```
+**What it measures**: How text probability changes under meaning-preserving modifications, based on DetectGPT principles.
 
-where σ_predictions is the standard deviation of AI probability predictions across metrics.
+**Mathematical Foundation**:
 
-High consensus (>0.8) increases our overall confidence. Low consensus (<0.4) triggers uncertainty flags and may recommend human review.
+$$
+\Delta_{\text{logp}} = \frac{1}{k} \sum_{j=1}^k \left| \log P(T) - \log P(T'_{\epsilon_j}) \right|
+$$
 
-### Uncertainty Quantification
+**Forensic Insight**: Text generated by language models occupies characteristic "curvature" regions in probability space—local maxima where small perturbations cause predictable probability decreases. Human-written text, not originating from these probability distributions, shows different perturbation sensitivity patterns.
 
-Every prediction includes an uncertainty score combining three factors:
+**Computational Consideration**: This is the most resource-intensive metric, so TEXT-AUTH implements conditional execution, reserving it for cases where other metrics provide insufficient confidence.
 
-**Variance uncertainty** (40% weight): How much do metrics disagree?  
-**Confidence uncertainty** (30% weight): How confident is each individual metric?  
-**Decision uncertainty** (30% weight): How close is the final probability to 0.5 (the maximally uncertain point)?
+## Ensemble Aggregation Methodology
 
-```
-Uncertainty = 0.4 × var(predictions) + 0.3 × (1 - mean(confidences)) + 0.3 × (1 - 2|P_AI - 0.5|)
-```
+Each of the six metrics produces:
 
-When uncertainty exceeds 0.7, we explicitly flag this in our output and recommend human review rather than making an automated high-stakes decision.
+- A synthetic probability estimate $p_i \in [0,1]$
+- An internal confidence score $c_i \in [0,1]$
+- An evidence strength classification (weak/moderate/strong)
 
----
+The aggregation process follows a sophisticated multi-stage approach:
 
-## Model Attribution: Which AI Wrote This?
+### Stage 1: Domain-Specific Base Weighting
 
-Beyond detecting *whether* text is AI-generated, we can often identify *which* AI model likely created it. This forensic capability emerged from a surprising observation: different AI models have distinct "fingerprints."
+Each of the sixteen supported domains has pre-calibrated base weights reflecting metric importance for that genre:
 
-GPT-4 tends toward more sophisticated vocabulary and longer average sentence length. Claude exhibits particular patterns in transitional phrases and explanation structure. Gemini shows characteristic approaches to list formatting and topic organization. LLaMA-based models have subtle tokenization artifacts.
+**Academic Domain Weights**:
 
-Our attribution classifier is a fine-tuned RoBERTa model trained on labeled datasets from multiple AI sources. It analyzes stylometric features—not just what is said, but *how* it's said—to make probabilistic attributions.
+- Perplexity: 22%
+- Entropy: 18%
+- Structural: 15%
+- Semantic: 15%
+- Linguistic: 20%
+- Stability: 10%
 
-**Use cases for attribution**:
-- **Academic institutions**: Understanding which tools students are using
-- **Publishers**: Identifying content farm sources
-- **Research**: Tracking the spread of AI-generated content online
-- **Forensics**: Investigating coordinated inauthentic behavior
+---
 
-We report attribution with appropriate humility: "76% confidence this was generated by GPT-4" rather than making definitive claims.
+### Stage 2: Confidence-Adjusted Dynamic Weighting
 
----
+Base weights are dynamically adjusted based on each metric's confidence using a sigmoid scaling function:
 
-## Explainability: Making Decisions Transparent
+$$
+w_i^{\text{(adjusted)}} = w_i^{\text{(base)}} \cdot \left( \frac{1}{1 + e^{-\gamma(c_i - 0.5)}} \right)
+$$
 
-Perhaps the most critical aspect of our system is explainability. When someone's academic career or job application is at stake, "AI-Generated: 87%" is insufficient. Users deserve to understand *why* the system reached its conclusion.
+where $\gamma = 10$ controls adjustment sensitivity.
 
-### Sentence-Level Highlighting
+---
 
-We break text into sentences and compute AI probability for each one. The frontend displays this as color-coded highlighting:
+### Stage 3: Normalization and Aggregation
 
-- **Deep red**: High AI probability (>80%)
-- **Light red**: Moderate-high (60-80%)
-- **Yellow**: Uncertain (40-60%)
-- **Light green**: Moderate-low (20-40%)
-- **Deep green**: Low AI probability (<20%)
+Adjusted weights are normalized to sum to 1.0, then used for weighted probability calculation:
 
-Hovering over any sentence reveals its individual metric scores. This granular feedback helps users understand exactly which portions of the text triggered detection.
+$$
+P_{\text{synthetic}} = \sum_{i=1}^6 w_i^{\text{(final)}} \cdot p_i
+$$
 
-### Natural Language Reasoning
+---
 
-Every analysis includes human-readable explanations:
+### Stage 4: Consensus Analysis
 
-*"This text exhibits characteristics consistent with AI generation. Key factors: uniform sentence structure (burstiness score: 0.23), high semantic coherence (0.91), and low perplexity relative to domain baseline (0.34). The linguistic complexity metric shows moderate confidence (0.67) that grammatical patterns align with GPT-4's typical output. Overall uncertainty is low (0.18), indicating strong metric consensus."*
+The system evaluates inter-metric agreement:
 
-This transparency serves multiple purposes:
-- **Trust**: Users understand the decision logic
-- **Learning**: Writers see what patterns to vary
-- **Accountability**: Decisions can be reviewed and contested
-- **Fairness**: Systematic biases become visible
+- High consensus increases overall confidence
+- Low consensus triggers uncertainty flags
+- Extreme disagreement may indicate adversarial manipulation or domain misclassification
 
 ---
 
-## Real-World Performance
+## Uncertainty Quantification Framework
 
-In production environments, our system processes text with sublinear scaling—processing time doesn't increase proportionally with length due to aggressive parallelization:
+TEXT-AUTH explicitly models uncertainty through a three-component composite score:
 
-**Short texts** (100-500 words): 1.2 seconds, 0.8 vCPU, 512MB RAM  
-**Medium texts** (500-2000 words): 3.5 seconds, 1.2 vCPU, 1GB RAM  
-**Long texts** (2000+ words): 7.8 seconds, 2.0 vCPU, 2GB RAM  
+### 1. Metric Disagreement Uncertainty
 
-Key performance optimizations include:
+$$
+U_{\text{variance}} = \min(1.0, \sigma_P \cdot 2)
+$$
 
-**Parallel metric computation**: All six metrics run simultaneously across thread pools rather than sequentially.
+where $\sigma_P$ is the standard deviation of the six metric probabilities.
 
-**Conditional execution**: If early metrics reach 95%+ confidence with strong consensus, we can skip expensive metrics like multi-perturbation stability.
+### 2. Confidence-Based Uncertainty
 
-**Model caching**: Language models load once at startup and remain in memory. On first run, we automatically download model weights from HuggingFace and cache them locally.
+$$
+U_{\text{confidence}} = 1 - \frac{1}{6} \sum_{i=1}^6 c_i
+$$
 
-**Smart batching**: For bulk document analysis, we batch-process texts to maximize GPU utilization.
+### 3. Decision Boundary Uncertainty
 
----
+$$
+U_{\text{decision}} = 1 - 2 \cdot |P_{\text{synthetic}} - 0.5|
+$$
 
-## The Model Management Challenge
+This component captures how close the final probability is to the maximally uncertain point (0.5).
 
-An interesting engineering decision: we don't commit model weights to the repository. The base models alone would add 2-3GB to the repo size, making it unwieldy for development and deployment.
+### Composite Uncertainty Score
 
-Instead, we implemented automatic model fetching on first run. The system checks for required models in the local cache. If not found, it downloads them from HuggingFace using resumable downloads with integrity verification.
+$$
+U_{\text{total}} = 0.4U_{\text{variance}} + 0.3U_{\text{confidence}} + 0.3U_{\text{decision}}
+$$
 
-This approach provides:
-- **Lightweight repository**: Clone times under 30 seconds
-- **Version control**: Model versions are pinned in configuration
-- **Offline operation**: Once downloaded, models cache locally
-- **Reproducibility**: Same model versions across all environments
+**Interpretation Guidelines**:
 
-For production deployments, we pre-bake models into Docker images to avoid cold-start delays.
+- **< 0.20**: High confidence, reliable assessment
+- **0.20 – 0.40**: Moderate confidence, use with appropriate caution
+- **> 0.40**: Low confidence, inconclusive—recommend human review
 
 ---
 
-## The Business Reality: Market Fit and Monetization
+## Domain-Aware Calibration System
 
-While the technology is fascinating, a system is only valuable if it solves real problems for real users. The market validation is compelling:
+The system recognizes that different writing genres have different normative characteristics. Sixteen domains are supported, each with specialized configurations.
 
-**Education sector** :
-- Universities need academic integrity tools that are defensible in appeals
-- False accusations destroy student trust—accuracy matters more than speed
-- Need for integration with learning management systems (Canvas, Blackboard, Moodle)
+### Domain Classification Process
 
-**Hiring platforms** :
-- Resume screening at scale requires automated first-pass filtering
-- Cover letter authenticity affects candidate quality downstream
-- Integration with applicant tracking systems (Greenhouse, Lever, Workday)
+1. **Feature Extraction**: Analyze text for domain indicators including formality, technical terminology, citation patterns, punctuation usage, and structural complexity
+2. **Probabilistic Classification**: Use heuristic and optional pre-trained model-assisted inference to estimate domain probabilities
+3. **Threshold Selection**: Apply domain-specific detection thresholds and metric weights
 
-**Content publishing** :
-- Publishers drowning in AI-generated submissions
-- SEO platforms fighting content farms
-- Media credibility depends on content authenticity
+### Example Domain Configurations
 
-Our competitive advantage isn't just better accuracy —it's the combination of accuracy, explainability, and domain awareness. Existing solutions leave 15-20% false positive rates. In contexts where false positives have serious consequences, that's unacceptable.
+**Academic Domain (Conservative thresholds)**:
+- Higher linguistic complexity expectations
+- Reduced sensitivity to low perplexity
+- Elevated synthetic probability threshold (0.75)
+- Priority on minimizing false positives
 
----
+**Creative Domain (Adaptive thresholds)**:
+- Enhanced entropy and structural analysis
+- Tolerance for high perplexity variation
+- Balanced synthetic threshold (0.70)
+- Focus on stylistic pattern detection
 
-## Technical Architecture: Building for Scale
+**Social Media Domain (Lenient thresholds)**:
+- Perplexity as primary signal
+- Relaxed linguistic requirements
+- Lower synthetic threshold (0.65)
+- Emphasis on conversational authenticity
 
-The system follows a modular pipeline architecture designed for both current functionality and future extensibility.
+**Technical Documentation (Strict thresholds)**:
+- Semantic coherence prioritization
+- Highest synthetic threshold (0.80)
+- Structural pattern analysis
+- Maximum emphasis on minimizing false accusations
 
-### Frontend Layer
-A React-based web application with real-time analysis dashboard, drag-and-drop file upload (supporting PDF, DOCX, TXT, MD), and batch processing interface. The UI updates progressively as metrics complete, rather than blocking until full analysis finishes.
+### Calibration Methodology
 
-### API Gateway
-FastAPI backend with JWT authentication, rate limiting (100 requests/hour for free tier), and intelligent request queuing. The gateway handles routing, auth, and implements backpressure mechanisms when the detection engine is overloaded.
+Thresholds were optimized using ROC curve analysis on curated datasets of 10,000+ verified texts per domain, with cross-validation to ensure generalization. The optimization objective balanced precision and recall while prioritizing false positive minimization in high-stakes domains.
 
-### Detection Orchestrator
-The orchestrator manages the analysis pipeline: domain classification, text preprocessing, metric scheduling, ensemble coordination, and report generation. It implements circuit breakers for failing metrics and timeout handling for long-running analyses.
+--- 
 
-### Metrics Pool
-Each metric runs as an independent module with standardized interfaces. This pluggable architecture allows us to add new metrics without refactoring the ensemble logic. Metrics execute in parallel across a thread pool, with results aggregated as they complete.
+## Interpretability and Explainability
 
-### Ensemble Classifier
-The ensemble aggregates metric results using the confidence-calibrated, domain-aware logic described earlier. It's implemented with multiple aggregation strategies (confidence-calibrated, domain-adaptive, consensus-based) and automatically selects the most appropriate method.
+### Sentence-Level Forensic Highlighting
 
-### Data Layer
-PostgreSQL for structured data (user accounts, analysis history, feedback), Redis for caching (model outputs, intermediate results), and S3-compatible storage for reports and uploaded files.
+Text is analyzed at the sentence level, with each sentence receiving a color-coded classification:
 
----
+- 🔴 **Deep Red**: Strong synthetic consistency signals (> 80% probability)
+- 🟠 **Light Red**: Moderate synthetic signals (60–80% probability)
+- 🟡 **Yellow**: Inconclusive or mixed signals (40–60% probability)
+- 🟢 **Green**: Strong authentic consistency signals (< 40% probability)
 
-## Continuous Learning: The System That Improves
+Hover interactions reveal detailed forensic data for each sentence, including individual metric scores and contributing factors.
 
-AI detection isn't a solved problem—it's an arms race. As models improve and users learn to game detectors, our system must evolve.
+### Natural Language Reasoning Generation
 
-We've built a continuous improvement pipeline:
+Every analysis includes comprehensive human-readable explanations structured as:
 
-**Feedback loop integration**: Users can report false positives/negatives. These flow into a retraining queue with appropriate privacy protections (we never store submitted text without explicit consent).
+#### Executive Summary
+A concise overview of the forensic assessment, including final probability, confidence level, and primary findings.
 
-**Regular recalibration**: Monthly analysis of metric performance across domains. If we notice accuracy degradation in a specific domain (say, medical writing), we can retrain domain-specific weight adjustments.
+#### Key Forensic Indicators
+Specific text characteristics that contributed to the assessment, such as:
+- "Unusually uniform sentence structure (burstiness: -0.12)"
+- "Exceptionally high semantic coherence (mean: 0.91)"
+- "Low perplexity variance indicating predictable token sequences"
 
-**Model version tracking**: When OpenAI releases GPT-5 or Anthropic releases Claude Opus 5, we collect samples and retrain the attribution classifier.
+#### Confidence Factors Analysis
+Explicit discussion of:
+- Supporting evidence (metrics showing strong signals)
+- Contradicting evidence (metrics showing conflicting signals)
+- Uncertainty sources (domain ambiguity, text length limitations, etc.)
 
-**A/B testing framework**: New ensemble strategies are shadow-deployed and compared against production before rollout.
+#### Metric Contribution Breakdown
+Percentage attribution showing how much each forensic signal contributed to the final assessment, helping users understand the analytical weighting.
 
-**Quarterly accuracy audits**: Independent validation on held-out test sets to ensure we're not overfitting to feedback data.
+#### Domain Context Considerations
+Explanation of how the text's genre affected the analysis, including any domain-specific adjustments applied to thresholds or interpretations.
 
----
+--- 
 
-## Ethical Considerations and Limitations
+## Ethical Framework and Implementation Principles
 
-Building detection systems comes with responsibility. We're transparent about limitations:
+### Core Ethical Commitments
 
-**No detector is perfect**: We report uncertainty scores and recommend human review for high-stakes decisions. Automated systems should augment human judgment, not replace it.
+- **Transparency Over Certainty**: The system explicitly acknowledges uncertainty rather than feigning omniscience. All outputs include confidence intervals and uncertainty quantification.
+- **Evidence Over Attribution**: TEXT-AUTH reports statistical patterns, not authorship claims. This distinction is maintained throughout the user interface, documentation, and API responses.
+- **Contextual Awareness**: Analyses consider domain, genre, language, and cultural factors that might affect interpretation. The system includes bias mitigation measures for protected writing styles.
+- **Human-in-the-Loop Design**: Automated analysis supports rather than replaces human judgment. High-uncertainty cases explicitly recommend human review, and all high-stakes applications require human oversight.
+- **Continuous Auditing**: The system implements regular fairness evaluations, performance monitoring, and bias detection to identify and address emerging issues.
 
-**Adversarial robustness**: Sufficiently motivated users can fool any statistical detector. Our multi-metric approach increases difficulty, but sophisticated attacks (semantic-preserving paraphrasing, stylistic mimicry) remain challenges.
+### Responsible Use Guidelines
 
-**Bias concerns**: Non-native English speakers and neurodivergent writers may exhibit patterns that resemble AI generation. We're actively researching fairness metrics and bias mitigation strategies.
+**Appropriate Applications**
+- Academic integrity screening (with human review processes)
+- Content verification in editorial workflows
+- Resume authenticity checking (as part of holistic review)
+- Research on text generation patterns
+- Writing assistance tool calibration
 
-**Privacy**: We process uploaded documents transiently and don't store content without explicit user consent. Reports contain analysis metadata, not original text.
+**Inappropriate Applications**
+- Sole determinant for academic penalties
+- Automated rejection without appeal mechanisms
+- Surveillance without consent or disclosure
+- Cross-cultural comparison without proper calibration
+- Real-time monitoring without transparency
 
-**Transparency**: We publish our methodology and are developing tools for users to understand exactly which features triggered detection.
+### Bias Mitigation Strategies
 
-The goal isn't perfect detection—it's building a tool that makes authenticity verification more accurate, transparent, and fair than the status quo.
+The system implements multiple bias reduction techniques:
+- **Domain normalization**: Genre-specific baselines reduce false positives against formal writing styles
+- **Confidence thresholding**: Higher uncertainty triggers human review for edge cases
+- **Protected style detection**: Identification of non-native, neurodivergent, or regional writing patterns with adjusted interpretation
+- **Regular fairness auditing**: Scheduled evaluation of performance across demographic and stylistic subgroups
 
----
+### Computational Performance
+- Short texts (100–500 words): 1.2 seconds average processing
+- Medium texts (500–2000 words): 3.5 seconds average
+- Long texts (2000+ words): 7.8 seconds average
+- Parallel execution: 2.9× speedup over sequential processing
+- Memory footprint: 1.5–3.0 GB depending on configuration
 
-## Conclusion: Building Trust in the AI Age
+---
 
-The proliferation of AI-generated content isn't inherently good or bad—it's a tool. Like any powerful tool, it can be used responsibly (brainstorming, drafting assistance, accessibility support) or irresponsibly (plagiarism, deception, spam).
+## Conclusion: Toward Responsible Text Forensics
 
-What we need are systems that make authenticity verifiable without stifling legitimate AI use. The AI Text Authentication Platform represents our contribution to this challenge: sophisticated enough to handle real-world complexity, transparent enough to justify consequential decisions, and humble enough to acknowledge uncertainty when it exists.
+TEXT-AUTH represents a paradigm shift in text authenticity analysis—from binary classification to evidence-based forensic assessment. By combining orthogonal statistical signals with domain-aware calibration and transparent reasoning, the system provides actionable intelligence while acknowledging the inherent complexity and uncertainty of the problem.
 
-The code is production-ready, the math is rigorous, and the results speak for themselves. But more importantly, the system is designed with the understanding that technology alone doesn't solve social problems—thoughtful implementation, ethical guardrails, and human judgment remain essential.
+### Key Contributions
 
-As AI writing tools become ubiquitous, the question isn't "Can we detect them?"—it's "Can we build systems that foster trust, transparency, and accountability?" That's the problem we set out to solve.
+- **Methodological Innovation**: A multi-metric, domain-calibrated approach that recognizes genre diversity in writing patterns
+- **Uncertainty Quantification**: Explicit modeling of confidence and uncertainty prevents overconfident errors
+- **Transparent Reasoning**: Comprehensive explainability builds trust and enables informed decision-making
+- **Ethical Foundation**: Clear boundaries around appropriate use and acknowledgment of limitations
+- **Production Engineering**: Parallel processing, efficient caching, and scalable architecture enable real-world deployment
 
 ---
 
-*The AI Text Authentication Platform is available on GitHub. Technical documentation, whitepapers, and research methodology are available in the repository. For enterprise inquiries or research collaborations, contact the team.*
+### The Path Forward
+
+Text authenticity assessment remains an evolving challenge in the age of generative AI. TEXT-AUTH provides a foundation for responsible forensic analysis, but continued development is essential:
+
+- Multilingual expansion to support diverse linguistic contexts
+- Real-time analysis capabilities for interactive writing environments
+- Enhanced adversarial robustness against evolving evasion techniques
+- Institutional calibration frameworks for organization-specific needs
+- Collaborative research initiatives to advance the field collectively
 
-**Version 1.0.0 | October 2025**
+Ultimately, the goal is not perfect detection—an unrealistic standard in an adversarial environment—but rather the development of tools that make authenticity analysis more transparent, more nuanced, and more accountable than previous approaches.
+
+By focusing on evidence rather than attribution, uncertainty rather than false certainty, and support rather than replacement of human judgment, TEXT-AUTH contributes to building trust in written communication in the generative AI era.
 
 ---
+
+**TEXT-AUTH Forensic Text Analysis Platform**  
+Version 1.0 — December 2025  
+Author: Satyaki Mitra
+_Evidence-based assessment, transparent reasoning, responsible implementation_
+
+---

example.py

@@ -1,45 +0,0 @@
-# Complete detection + reporting pipeline
-
-from detector.orchestrator import DetectionOrchestrator
-from detector.attribution import ModelAttributor
-from reporter.report_generator import ReportGenerator
-
-# 1. Initialize components
-orchestrator = DetectionOrchestrator()
-orchestrator.initialize()
-
-attributor = ModelAttributor()
-attributor.initialize()
-
-reporter = ReportGenerator()
-
-# 2. Analyze text
-text = """Perplexity measures how well a language model predicts a sample; lower perplexity indicates better predictive accuracy. In AI detection, models often exhibit unnaturally low perplexity because their outputs are statistically optimized rather than organically generated. Human writing tends to have higher variability and “burstiness”—irregular patterns of word choice and sentence structure. By combining perplexity with burstiness analysis and fine-tuned classifiers like RoBERTa, detectors can identify AI-generated text with greater confidence. Ensemble methods further improve reliability by aggregating multiple signals. This multi-layered approach reduces false positives and adapts to evolving AI models. Understanding these metrics helps users interpret detection scores meaningfully."""
-
-detection_result = orchestrator.analyze(text)
-
-# 3. Attribute model
-attribution_result = attributor.attribute(
-    text=text,
-    processed_text=detection_result.processed_text,
-    metric_results=detection_result.metric_results,
-)
-
-# 4. Generate reports
-report_files = reporter.generate_complete_report(
-    detection_result=detection_result,
-    attribution_result=attribution_result,
-    formats=["json", "pdf", "txt"],
-    filename_prefix="my_analysis",
-)
-
-print("Generated reports:")
-for format_type, filepath in report_files.items():
-    print(f"  {format_type.upper()}: {filepath}")
-
-# Output:
-# Generated reports:
-#   JSON: reports/output/my_analysis_20250101_143022.json
-#   HTML: reports/output/my_analysis_20250101_143022.html
-#   PDF: reports/output/my_analysis_20250101_143022.pdf
-#   TXT: reports/output/my_analysis_20250101_143022.txt

metrics/base_metric.py

@@ -1,89 +1,12 @@
 # DEPENDENCIES
 from abc import ABC
-from enum import Enum
 from typing import Any
 from typing import Dict
-from typing import Tuple
 from loguru import logger
 from typing import Optional
 from abc import abstractmethod
-from dataclasses import dataclass
-
-
-class MetricResult:
-    """
-    Result from a metric calculation
-    """
-    def __init__(self, metric_name: str, ai_probability: float, human_probability: float, mixed_probability: float, confidence: float, details: Optional[Dict[str, Any]] = None, error: Optional[str] = None):
-        self.metric_name       = metric_name
-        self.ai_probability    = max(0.0, min(1.0, ai_probability))
-        self.human_probability = max(0.0, min(1.0, human_probability))
-        self.mixed_probability = max(0.0, min(1.0, mixed_probability))
-        self.confidence        = max(0.0, min(1.0, confidence))
-        self.details           = details or {}
-        self.error             = error
-        
-        # Normalize probabilities to sum to 1
-        total                  = self.ai_probability + self.human_probability + self.mixed_probability
-        
-        if (total > 0):
-            self.ai_probability    /= total
-            self.human_probability /= total
-            self.mixed_probability /= total
-
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"metric_name"       : self.metric_name,
-                "ai_probability"    : round(self.ai_probability, 4),
-                "human_probability" : round(self.human_probability, 4),
-                "mixed_probability" : round(self.mixed_probability, 4),
-                "confidence"        : round(self.confidence, 4),
-                "details"           : self.details,
-                "error"             : self.error,
-                "success"           : self.error is None,
-               }
-    
-
-    @property
-    def is_ai(self) -> bool:
-        """
-        Check if classified as AI
-        """
-        return self.ai_probability > max(self.human_probability, self.mixed_probability)
-    
-    
-    @property
-    def is_human(self) -> bool:
-        """
-        Check if classified as human
-        """
-        return self.human_probability > max(self.ai_probability, self.mixed_probability)
-    
-
-    @property
-    def is_mixed(self) -> bool:
-        """
-        Check if classified as mixed
-        """
-        return self.mixed_probability > max(self.ai_probability, self.human_probability)
-    
-
-    @property
-    def predicted_class(self) -> str:
-        """
-        Get predicted class
-        """
-        if self.is_ai:
-            return "AI"
-        
-        elif self.is_human:
-            return "Human"
-        
-        else:
-            return "Mixed"
+from config.schemas import MetricResult
+from config.constants import base_metric_params
 
 
 class BaseMetric(ABC):
@@ -91,11 +14,15 @@ class BaseMetric(ABC):
     Abstract base class for all detection metrics
     """
     def __init__(self, name: str, description: str):
-        self.name           = name
-        self.description    = description
-        self.is_initialized = False
-        self._model         = None
-        self._tokenizer     = None
+        self.name                          = name
+        self.description                   = description
+        self.is_initialized                = False
+        self._model                        = None
+        self._tokenizer                    = None
+        self.default_synthetic_probability = base_metric_params.DEFAULT_SYNTHETIC_PROBABILITY
+        self.default_authentic_probability = base_metric_params.DEFAULT_AUTHENTIC_PROBABILITY
+        self.default_hybrid_probability    = base_metric_params.DEFAULT_HYBRID_PROBABILITY
+        self.default_confidence            = base_metric_params.DEFAULT_CONFIDENCE
     
 
     @abstractmethod
@@ -178,13 +105,7 @@ class BaseMetric(ABC):
             if not self.is_initialized:
                 logger.warning(f"{self.name}: Not initialized, initializing now...")
                 if not self.initialize():
-                    return MetricResult(metric_name       = self.name,
-                                        ai_probability    = 0.5,
-                                        human_probability = 0.5,
-                                        mixed_probability = 0.0,
-                                        confidence        = 0.0,
-                                        error             = "Failed to initialize metric",
-                                       )
+                    return self._default_result(error = "Failed to initialize metric")
             
             result = self.compute(text, **kwargs)
             return result
@@ -192,13 +113,7 @@ class BaseMetric(ABC):
 
         except Exception as e:
             logger.error(f"{self.name}: Error computing metric: {e}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
 
     
     def batch_compute(self, texts: list, **kwargs) -> list:
@@ -237,6 +152,19 @@ class BaseMetric(ABC):
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(name='{self.name}', initialized={self.is_initialized})"
 
+    
+    def _default_result(self, error: Optional[str] = None) -> MetricResult:
+        """
+        Default metric result for exception cases
+        """
+        return MetricResult(metric_name           = self.name,
+                            synthetic_probability = self.default_synthetic_probability,
+                            authentic_probability = self.default_authentic_probability,
+                            hybrid_probability    = self.default_hybrid_probability,
+                            confidence            = self.default_confidence,
+                            error                 = error,
+                           )
+
 
 
 class StatisticalMetric(BaseMetric):
@@ -255,6 +183,5 @@ class StatisticalMetric(BaseMetric):
 
 # Export
 __all__ = ["BaseMetric",
-           "MetricResult",
            "StatisticalMetric",
           ]

metrics/entropy.py

@@ -6,10 +6,11 @@ from typing import Dict
 from typing import List
 from loguru import logger
 from collections import Counter
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import BaseMetric
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
 from models.model_manager import get_model_manager
+from config.constants import entropy_metric_params
 from config.threshold_config import get_threshold_for_domain
 
 
@@ -22,13 +23,14 @@ class EntropyMetric(BaseMetric):
     - Word-level entropy and burstiness  
     - Token-level diversity and unpredictability in sequences
     - Entropy distribution across text chunks
-    - AI-specific pattern detection
+    - Synthetic-specific pattern detection
     """
     def __init__(self):
         super().__init__(name        = "entropy",
                          description = "Token-level diversity and unpredictability in text sequences",
                         )
         self.tokenizer = None
+        self.params    = entropy_metric_params
     
 
     def initialize(self) -> bool:
@@ -40,7 +42,7 @@ class EntropyMetric(BaseMetric):
             
             # Load tokenizer for token-level analysis
             model_manager = get_model_manager()
-            gpt_model     = model_manager.load_model("perplexity_gpt2")
+            gpt_model     = model_manager.load_model("perplexity_reference_lm")
             
             if isinstance(gpt_model, tuple):
                 self.tokenizer = gpt_model[1]
@@ -62,108 +64,105 @@ class EntropyMetric(BaseMetric):
         Compute enhanced entropy measures for text with FULL DOMAIN THRESHOLD INTEGRATION
         """
         try:
-            if (not text or (len(text.strip()) < 50)):
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    error             = "Text too short for entropy analysis",
+            if (not text or (len(text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_ANALYSIS)):
+                return MetricResult(metric_name           = self.name,
+                                    synthetic_probability = self.params.NEUTRAL_PROBABILITY,
+                                    authentic_probability = self.params.NEUTRAL_PROBABILITY,
+                                    hybrid_probability    = self.params.MIN_PROBABILITY,
+                                    confidence            = self.params.MIN_CONFIDENCE,
+                                    error                 = "Text too short for entropy analysis",
                                    )
             
             # Get domain-specific thresholds
-            domain                          = kwargs.get('domain', Domain.GENERAL)
-            domain_thresholds               = get_threshold_for_domain(domain)
-            entropy_thresholds              = domain_thresholds.entropy
+            domain                                      = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds                           = get_threshold_for_domain(domain)
+            entropy_thresholds                          = domain_thresholds.entropy
             
             # Calculate comprehensive entropy features
-            features                        = self._calculate_enhanced_entropy_features(text)
+            features                                    = self._calculate_entropy_features(text = text)
             
             # Calculate raw entropy score (0-1 scale)
-            raw_entropy_score, confidence   = self._analyze_entropy_patterns(features)
+            raw_entropy_score, confidence               = self._analyze_entropy_patterns(features = features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob = self._apply_domain_thresholds(raw_entropy_score, entropy_thresholds, features)
+            synthetic_prob, authentic_prob, hybrid_prob = self._apply_domain_thresholds(raw_score  = raw_entropy_score, 
+                                                                                        thresholds = entropy_thresholds, 
+                                                                                        features   = features,
+                                                                                       )
             
             # Apply confidence multiplier from domain thresholds
-            confidence                     *= entropy_thresholds.confidence_multiplier
-            confidence                      = max(0.0, min(1.0, confidence))
+            confidence                                 *= entropy_thresholds.confidence_multiplier
+            confidence                                  = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
             
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : entropy_thresholds.ai_threshold,
-                                                     'human_threshold' : entropy_thresholds.human_threshold,
-                                                     'raw_score'       : raw_entropy_score,
-                                                    },
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'        : domain.value,
+                                                         'synthetic_threshold': entropy_thresholds.synthetic_threshold,
+                                                         'authentic_threshold': entropy_thresholds.authentic_threshold,
+                                                         'raw_score'          : raw_entropy_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in entropy computation: {repr(e)}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold    # e.g., 0.55 for GENERAL, 0.50 for ACADEMIC
-        human_threshold = thresholds.human_threshold # e.g., 0.45 for GENERAL, 0.40 for ACADEMIC
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
         
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-        
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
+        if (raw_score >= synthetic_threshold):
+            # Above synthetic threshold - strongly synthetic
+            distance_from_threshold = raw_score - synthetic_threshold
+            synthetic_prob          = self.params.STRONG_SYNTHETIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+        
+        elif (raw_score <= authentic_threshold):
+            # Below authentic threshold - strongly authentic
+            distance_from_threshold = authentic_threshold - raw_score
+            synthetic_prob          = self.params.UNCERTAIN_SYNTHETIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.STRONG_AUTHENTIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
         
         else:
             # Between thresholds - uncertain zone
-            range_width = ai_threshold - human_threshold
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            range_width = synthetic_threshold - authentic_threshold
+            if (range_width > self.params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = self.params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob    = 0.5
-                human_prob = 0.5
+                synthetic_prob = self.params.NEUTRAL_PROBABILITY
+                authentic_prob = self.params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on entropy variance
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on entropy variance
+        hybrid_prob = self._calculate_hybrid_probability(features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
+        total       = synthetic_prob + authentic_prob + hybrid_prob
 
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        if (total > self.params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
     
 
-    def _calculate_enhanced_entropy_features(self, text: str) -> Dict[str, Any]:
+    def _calculate_entropy_features(self, text: str) -> Dict[str, Any]:
         """
         Calculate comprehensive entropy measures including document-required features
         """
@@ -179,15 +178,15 @@ class EntropyMetric(BaseMetric):
         sequence_unpredictability = self._calculate_sequence_unpredictability(text)
         
         # Chunk-based analysis for whole-text understanding
-        chunk_entropies           = self._calculate_chunk_entropy(text, chunk_size=100)
+        chunk_entropies           = self._calculate_chunk_entropy(text)
         entropy_variance          = np.var(chunk_entropies) if chunk_entropies else 0.0
         avg_chunk_entropy         = np.mean(chunk_entropies) if chunk_entropies else 0.0
         
-        # AI-specific pattern detection
-        ai_pattern_score          = self._detect_ai_entropy_patterns(text)
+        # Synthetic-specific pattern detection
+        synthetic_pattern_score   = self._detect_synthetic_entropy_patterns(text)
         
         # Predictability measures
-        predictability            = 1.0 - min(1.0, char_entropy / 4.0)
+        predictability            = 1.0 - min(1.0, char_entropy / self.params.MAX_CHAR_ENTROPY)
         
         return {"char_entropy"              : round(char_entropy, 4),
                 "word_entropy"              : round(word_entropy, 4),
@@ -197,7 +196,7 @@ class EntropyMetric(BaseMetric):
                 "entropy_variance"          : round(entropy_variance, 4),
                 "avg_chunk_entropy"         : round(avg_chunk_entropy, 4),
                 "predictability_score"      : round(predictability, 4),
-                "ai_pattern_score"          : round(ai_pattern_score, 4),
+                "synthetic_pattern_score"   : round(synthetic_pattern_score, 4),
                 "num_chunks_analyzed"       : len(chunk_entropies),
                }
     
@@ -221,7 +220,8 @@ class EntropyMetric(BaseMetric):
 
         for count in char_counts.values():
             probability = count / total_chars
-            entropy    -= probability * math.log2(probability)
+            if probability > self.params.ZERO_TOLERANCE:
+                entropy -= probability * math.log2(probability)
         
         return entropy
     
@@ -231,7 +231,7 @@ class EntropyMetric(BaseMetric):
         Calculate word-level entropy
         """
         words = text.lower().split()
-        if (len(words) < 5):
+        if (len(words) < self.params.MIN_WORDS_FOR_ANALYSIS):
             return 0.0
         
         word_counts = Counter(words)
@@ -241,7 +241,8 @@ class EntropyMetric(BaseMetric):
 
         for count in word_counts.values():
             probability = count / total_words
-            entropy    -= probability * math.log2(probability)
+            if probability > self.params.ZERO_TOLERANCE:
+                entropy -= probability * math.log2(probability)
         
         return entropy
     
@@ -255,7 +256,7 @@ class EntropyMetric(BaseMetric):
                 return 0.0
             
             # Length check before tokenization
-            if (len(text.strip()) < 10):
+            if (len(text.strip()) < self.params.MIN_SENTENCE_LENGTH):
                 return 0.0
 
             # Tokenize text
@@ -264,7 +265,7 @@ class EntropyMetric(BaseMetric):
                                            truncation         = True, 
                                           )
             
-            if (len(tokens) < 10):
+            if (len(tokens) < self.params.MIN_TOKENS_FOR_ANALYSIS):
                 return 0.0
             
             token_counts = Counter(tokens)
@@ -274,7 +275,8 @@ class EntropyMetric(BaseMetric):
 
             for count in token_counts.values():
                 probability = count / total_tokens
-                entropy    -= probability * math.log2(probability)
+                if probability > self.params.ZERO_TOLERANCE:
+                    entropy -= probability * math.log2(probability)
             
             return entropy
             
@@ -285,14 +287,14 @@ class EntropyMetric(BaseMetric):
 
     def _calculate_token_diversity(self, text: str) -> float:
         """
-        Calculate token-level diversity : Higher diversity = more human-like
+        Calculate token-level diversity : Higher diversity = more authentic-like
         """
         if not self.tokenizer:
             return 0.0
         
         try:
             tokens = self.tokenizer.encode(text, add_special_tokens=False)
-            if (len(tokens) < 10):
+            if (len(tokens) < self.params.MIN_TOKENS_FOR_ANALYSIS):
                 return 0.0
             
             unique_tokens = len(set(tokens))
@@ -317,7 +319,7 @@ class EntropyMetric(BaseMetric):
         
         try:
             tokens = self.tokenizer.encode(text, add_special_tokens=False)
-            if (len(tokens) < 20):
+            if (len(tokens) < self.params.MIN_TOKENS_FOR_SEQUENCE):
                 return 0.0
             
             # Calculate bigram unpredictability
@@ -329,11 +331,12 @@ class EntropyMetric(BaseMetric):
             sequence_entropy = 0.0
 
             for count in bigram_counts.values():
-                probability       = count / total_bigrams
-                sequence_entropy -= probability * math.log2(probability)
+                probability = count / total_bigrams
+                if probability > self.params.ZERO_TOLERANCE:
+                    sequence_entropy -= probability * math.log2(probability)
             
-            # Normalize to 0-1 scale : Assuming max ~8 bits
-            normalized_entropy = min(1.0, sequence_entropy / 8.0)  
+            # Normalize to 0-1 scale
+            normalized_entropy = min(1.0, sequence_entropy / self.params.MAX_BIGRAM_ENTROPY)  
             
             return normalized_entropy
             
@@ -342,28 +345,32 @@ class EntropyMetric(BaseMetric):
             return 0.0
     
 
-    def _calculate_chunk_entropy(self, text: str, chunk_size: int = 100) -> List[float]:
+    def _calculate_chunk_entropy(self, text: str) -> List[float]:
         """
         Calculate entropy distribution across text chunks
         """
-        chunks = list()
-        words  = text.split()
+        chunks     = list()
+        words      = text.split()
+        chunk_size = self.params.CHUNK_SIZE_WORDS
+        overlap    = int(chunk_size * self.params.CHUNK_OVERLAP_RATIO)
+        step       = max(1, chunk_size - overlap)
         
         # Create overlapping chunks for better analysis
-        for i in range(0, len(words), chunk_size // 2):
+        for i in range(0, len(words), step):
             chunk = ' '.join(words[i:i + chunk_size])
             
             # Minimum chunk size
-            if (len(chunk) > 20):  
+            if (len(chunk) > self.params.MIN_CHUNK_LENGTH):  
                 entropy = self._calculate_character_entropy(chunk)
-                chunks.append(entropy)
+                if entropy > self.params.ZERO_TOLERANCE:
+                    chunks.append(entropy)
         
         return chunks
     
 
-    def _detect_ai_entropy_patterns(self, text: str) -> float:
+    def _detect_synthetic_entropy_patterns(self, text: str) -> float:
         """
-        Detect AI-specific entropy patterns: AI text often shows specific entropy signatures
+        Detect synthetic-specific entropy patterns: synthetic text often shows specific entropy signatures
         """
         patterns_detected = 0
         total_patterns    = 4
@@ -371,30 +378,30 @@ class EntropyMetric(BaseMetric):
         # Overly consistent character distribution
         char_entropy      = self._calculate_character_entropy(text)
         
-        # AI tends to be more consistent
-        if (char_entropy < 3.8):  
+        # synthetic tends to be more consistent
+        if (char_entropy < self.params.CHAR_ENTROPY_LOW_THRESHOLD):  
             patterns_detected += 1
         
         # Low token diversity
         token_diversity = self._calculate_token_diversity(text)
 
-        # AI reuses tokens more
-        if (token_diversity < 0.7):  
+        # synthetic reuses tokens more
+        if (token_diversity < self.params.TOKEN_DIVERSITY_MEDIUM_THRESHOLD):  
             patterns_detected += 1
         
         # Predictable sequences
         sequence_unpredictability = self._calculate_sequence_unpredictability(text)
         
-        # AI sequences are more predictable
-        if (sequence_unpredictability < 0.4):  
+        # synthetic sequences are more predictable
+        if (sequence_unpredictability < self.params.SEQUENCE_UNPREDICTABILITY_MEDIUM_THRESHOLD):  
             patterns_detected += 1
         
         # Low entropy variance across chunks
-        chunk_entropies  = self._calculate_chunk_entropy(text, chunk_size = 100)
+        chunk_entropies  = self._calculate_chunk_entropy(text)
         entropy_variance = np.var(chunk_entropies) if chunk_entropies else 0.0
         
-        # AI maintains consistent entropy
-        if (entropy_variance < 0.2):  
+        # synthetic maintains consistent entropy
+        if (entropy_variance < self.params.ENTROPY_VARIANCE_LOW_THRESHOLD):  
             patterns_detected += 1
         
         return patterns_detected / total_patterns
@@ -407,120 +414,129 @@ class EntropyMetric(BaseMetric):
         """
         # Check feature validity
         valid_features = [score for score in [features.get('char_entropy', 0),
+                                              features.get('token_entropy', 0),
                                               features.get('token_diversity', 0), 
                                               features.get('sequence_unpredictability', 0),
-                                              features.get('ai_pattern_score', 0)
-                                             ] if score > 0
+                                              features.get('synthetic_pattern_score', 0)
+                                             ] if score > self.params.ZERO_TOLERANCE
                          ]
         
-        if (len(valid_features) < 2):
+        if (len(valid_features) < self.params.MIN_REQUIRED_FEATURES):
             # Low confidence if insufficient features
-            return 0.5, 0.3  
+            return self.params.NEUTRAL_PROBABILITY, self.params.LOW_FEATURE_CONFIDENCE
 
-        ai_indicators = list()
+        synthetic_indicators = list()
         
-        # AI text often has lower character entropy (more predictable)
-        if (features['char_entropy'] < 3.5):
-            # Strong AI indicator
-            ai_indicators.append(0.8)  
+        # synthetic text often has lower character entropy (more predictable)
+        if (features['char_entropy'] < self.params.CHAR_ENTROPY_VERY_LOW_THRESHOLD):
+            # Strong synthetic indicator
+            synthetic_indicators.append(self.params.VERY_STRONG_SYNTHETIC_WEIGHT)  
 
-        elif (features['char_entropy'] < 4.0):
-            # Moderate AI indicator
-            ai_indicators.append(0.6)  
+        elif (features['char_entropy'] < self.params.CHAR_ENTROPY_LOW_THRESHOLD):
+            # Moderate synthetic indicator
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)  
 
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.2)  
+            # Weak synthetic indicator
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT) 
+
+        # Low token entropy suggests synthetic (limited vocabulary reuse)
+        if (features['token_entropy'] < self.params.TOKEN_ENTROPY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)
         
-        # Low entropy variance suggests AI (consistent patterns)
-        if (features['entropy_variance'] < 0.1):
-            # Very strong AI indicator
-            ai_indicators.append(0.9)  
+        else:
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT) 
+
+                
+        # Low entropy variance suggests synthetic (consistent patterns)
+        if (features['entropy_variance'] < self.params.ENTROPY_VARIANCE_VERY_LOW_THRESHOLD):
+            # Very strong synthetic indicator
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)  
 
-        elif (features['entropy_variance'] < 0.3):
+        elif (features['entropy_variance'] < self.params.ENTROPY_VARIANCE_MEDIUM_THRESHOLD):
             # Neutral
-            ai_indicators.append(0.5)  
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)  
 
         else:
-            # Strong human indicator
-            ai_indicators.append(0.1)  
+            # Strong authentic indicator
+            synthetic_indicators.append(self.params.VERY_LOW_SYNTHETIC_WEIGHT)  
         
-        # Low token diversity suggests AI
-        if (features['token_diversity'] < 0.6):
-            ai_indicators.append(0.7)
+        # Low token diversity suggests synthetic
+        if (features['token_diversity'] < self.params.TOKEN_DIVERSITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
-        elif (features['token_diversity'] < 0.8):
-            ai_indicators.append(0.4)
+        elif (features['token_diversity'] < self.params.TOKEN_DIVERSITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.VERY_WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # Low sequence unpredictability suggests AI
-        if (features['sequence_unpredictability'] < 0.3):
-            ai_indicators.append(0.8)
+        # Low sequence unpredictability suggests synthetic
+        if (features['sequence_unpredictability'] < self.params.SEQUENCE_UNPREDICTABILITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.VERY_STRONG_SYNTHETIC_WEIGHT)
 
-        elif (features['sequence_unpredictability'] < 0.5):
-            ai_indicators.append(0.5)
+        elif (features['sequence_unpredictability'] < self.params.SEQUENCE_UNPREDICTABILITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # High AI pattern score suggests AI
-        if (features['ai_pattern_score'] > 0.75):
-            ai_indicators.append(0.9)
+        # High synthetic pattern score suggests synthetic
+        if (features['synthetic_pattern_score'] > self.params.SYNTHETIC_PATTERN_SCORE_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)
         
-        elif (features['ai_pattern_score'] > 0.5):
-            ai_indicators.append(0.7)
+        elif (features['synthetic_pattern_score'] > self.params.SYNTHETIC_PATTERN_SCORE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
         
         else:
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(self.params.LOW_SYNTHETIC_WEIGHT)
         
         # Calculate raw score and confidence
-        raw_score  = np.mean(ai_indicators) if ai_indicators else 0.5
-        confidence = 1.0 - (np.std(ai_indicators) / 0.5) if ai_indicators else 0.5
-        confidence = max(0.1, min(0.9, confidence))
+        raw_score  = np.mean(synthetic_indicators) if synthetic_indicators else self.params.NEUTRAL_PROBABILITY
+        confidence = 1.0 - (np.std(synthetic_indicators) / self.params.CONFIDENCE_STD_NORMALIZER) if synthetic_indicators else self.params.NEUTRAL_CONFIDENCE
+        confidence = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
         
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content with better indicators
+        Calculate probability of hybrid synthetic/authentic content with better indicators
         """
-        mixed_indicators = list()
+        hybrid_indicators = list()
         
         # High entropy variance suggests mixed content
         entropy_variance = features.get('entropy_variance', 0)
         
-        if (entropy_variance > 0.5):
+        if (entropy_variance > self.params.ENTROPY_VARIANCE_HIGH_THRESHOLD):
             # Strong mixed indicator
-            mixed_indicators.append(0.6)  
+            hybrid_indicators.append(self.params.STRONG_HYBRID_WEIGHT)  
 
-        elif (entropy_variance > 0.3):
-            mixed_indicators.append(0.3)
+        elif (entropy_variance > self.params.ENTROPY_VARIANCE_MIXED_THRESHOLD):
+            hybrid_indicators.append(self.params.MODERATE_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # Inconsistent patterns across different entropy measures
         char_entropy = features.get('char_entropy', 0)
         word_entropy = features.get('word_entropy', 0)
         
-        if ((char_entropy > 0) and (word_entropy > 0)):
+        if ((char_entropy > self.params.ZERO_TOLERANCE) and (word_entropy > self.params.ZERO_TOLERANCE)):
             entropy_discrepancy = abs(char_entropy - word_entropy)
 
             # Large discrepancy suggests mixing
-            if (entropy_discrepancy > 1.0):  
-                mixed_indicators.append(0.4)
+            if (entropy_discrepancy > self.params.ENTROPY_DISCREPANCY_THRESHOLD):  
+                hybrid_indicators.append(self.params.MODERATE_HYBRID_WEIGHT)
         
-        # Moderate AI pattern score might indicate mixing
-        ai_pattern_score = features.get('ai_pattern_score', 0)
-        if (0.4 <= ai_pattern_score <= 0.6):
-            mixed_indicators.append(0.3)
+        # Moderate synthetic pattern score might indicate mixing
+        synthetic_pattern_score = features.get('synthetic_pattern_score', 0)
+        if (self.params.SYNTHETIC_PATTERN_MIXED_MIN <= synthetic_pattern_score <= self.params.SYNTHETIC_PATTERN_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
         
-        mixed_probability = min(0.4, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        hybrid_probability = min(self.params.MAX_HYBRID_PROBABILITY, np.mean(hybrid_indicators)) if hybrid_indicators else 0.0
         
-        return mixed_probability
+        return hybrid_probability
 
 
     def cleanup(self):
@@ -533,4 +549,4 @@ class EntropyMetric(BaseMetric):
 
 
 # Export
-__all__ = ["EntropyMetric"]
+__all__ = ["EntropyMetric"]

metrics/linguistic.py

@@ -7,10 +7,11 @@ from typing import List
 from typing import Tuple
 from loguru import logger
 from collections import Counter
-from config.threshold_config import Domain
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import BaseMetric
-from metrics.base_metric import MetricResult
 from models.model_manager import get_model_manager
+from config.constants import linguistic_metric_params
 from config.threshold_config import get_threshold_for_domain
 
 
@@ -29,6 +30,7 @@ class LinguisticMetric(BaseMetric):
                          description = "POS tag diversity, syntactic complexity, and grammatical pattern analysis",
                         )
         self.nlp = None
+        self.params = linguistic_metric_params
     
 
     def initialize(self) -> bool:
@@ -57,104 +59,95 @@ class LinguisticMetric(BaseMetric):
         Compute linguistic analysis with FULL DOMAIN THRESHOLD INTEGRATION
         """
         try:
-            if ((not text) or (len(text.strip()) < 50)):
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    error             = "Text too short for linguistic analysis",
-                                   )
-            
+            if ((not text) or (len(text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_ANALYSIS)):
+                return self._default_result(error = "Text too short for linguistic analysis")
+
             # Get domain-specific thresholds
-            domain                           = kwargs.get('domain', Domain.GENERAL)
-            domain_thresholds                = get_threshold_for_domain(domain)
-            linguistic_thresholds            = domain_thresholds.linguistic
+            domain                                      = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds                           = get_threshold_for_domain(domain)
+            linguistic_thresholds                       = domain_thresholds.linguistic
             
             # Calculate comprehensive linguistic features
-            features                         = self._calculate_linguistic_features(text)
+            features                                    = self._calculate_linguistic_features(text = text)
             
-            # Calculate raw linguistic score (0-1 scale)
-            raw_linguistic_score, confidence = self._analyze_linguistic_patterns(features)
+            # Calculate raw linguistic score (0-1 scale) - higher = more synthetic-like
+            raw_linguistic_score, confidence            = self._analyze_linguistic_patterns(features = features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob  = self._apply_domain_thresholds(raw_linguistic_score, linguistic_thresholds, features)
+            synthetic_prob, authentic_prob, hybrid_prob = self._apply_domain_thresholds(raw_score  = raw_linguistic_score, 
+                                                                                        thresholds = linguistic_thresholds, 
+                                                                                        features   = features,
+                                                                                       )
             
             # Apply confidence multiplier from domain thresholds
-            confidence                      *= linguistic_thresholds.confidence_multiplier
-            confidence                       = max(0.0, min(1.0, confidence))
+            confidence                                 *= linguistic_thresholds.confidence_multiplier
+            confidence                                  = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
             
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : linguistic_thresholds.ai_threshold,
-                                                     'human_threshold' : linguistic_thresholds.human_threshold,
-                                                     'raw_score'       : raw_linguistic_score,
-                                                    },
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'        : domain.value,
+                                                         'synthetic_threshold': linguistic_thresholds.synthetic_threshold,
+                                                         'authentic_threshold': linguistic_thresholds.authentic_threshold,
+                                                         'raw_score'          : raw_linguistic_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in linguistic computation: {repr(e)}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold
-        human_threshold = thresholds.human_threshold
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
 
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
+        if (raw_score >= synthetic_threshold):
+            # Above synthetic threshold - strongly synthetic
+            distance_from_threshold = raw_score - synthetic_threshold
+            synthetic_prob          = self.params.STRONG_SYNTHETIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+
+        elif (raw_score <= authentic_threshold):
+            # Below authentic threshold - strongly authentic
+            distance_from_threshold = authentic_threshold - raw_score
+            synthetic_prob          = self.params.UNCERTAIN_SYNTHETIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.STRONG_AUTHENTIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
         
         else:
             # Between thresholds - uncertain zone
-            range_width             = ai_threshold - human_threshold
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            range_width             = synthetic_threshold - authentic_threshold
+            if (range_width > self.params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = self.params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob    = 0.5
-                human_prob = 0.5
+                synthetic_prob = self.params.NEUTRAL_PROBABILITY
+                authentic_prob = self.params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on linguistic variance
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on linguistic variance
+        hybrid_prob = self._calculate_hybrid_probability(features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        total       = synthetic_prob + authentic_prob + hybrid_prob
+        if (total > self.params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
     
 
     def _calculate_linguistic_features(self, text: str) -> Dict[str, Any]:
@@ -170,7 +163,6 @@ class LinguisticMetric(BaseMetric):
             
             # Extract POS tags and dependencies
             pos_tags                = [token.pos_ for token in doc]
-            dependencies            = [token.dep_ for token in doc]
             
             # Calculate POS diversity and patterns
             pos_diversity           = self._calculate_pos_diversity(pos_tags = pos_tags)
@@ -185,12 +177,14 @@ class LinguisticMetric(BaseMetric):
             writing_style_score     = self._analyze_writing_style(doc = doc)
             
             # Chunk-based analysis for whole-text understanding
-            chunk_features          = self._calculate_chunk_linguistics(text       = text, 
-                                                                        chunk_size = 200,
-                                                                       )
+            chunk_complexities      = self._calculate_chunk_linguistics(text = text)
+            
+            avg_chunk_complexity    = np.mean(chunk_complexities) if chunk_complexities else 0.0
+            complexity_variance     = np.var(chunk_complexities) if chunk_complexities else 0.0
+            num_chunks              = len(chunk_complexities)
             
-            # Calculate specific AI linguistic patterns
-            ai_pattern_score        = self._detect_ai_linguistic_patterns(doc = doc)
+            # Calculate specific synthetic linguistic patterns
+            synthetic_pattern_score = self._detect_synthetic_linguistic_patterns(doc = doc)
             
             return {"pos_diversity"           : round(pos_diversity, 4),
                     "pos_entropy"             : round(pos_entropy, 4),
@@ -200,11 +194,11 @@ class LinguisticMetric(BaseMetric):
                     "transition_word_usage"   : round(grammatical_patterns['transition_usage'], 4),
                     "passive_voice_ratio"     : round(grammatical_patterns['passive_ratio'], 4),
                     "writing_style_score"     : round(writing_style_score, 4),
-                    "ai_pattern_score"        : round(ai_pattern_score, 4),
-                    "avg_chunk_complexity"    : round(np.mean(chunk_features['complexities']) if chunk_features['complexities'] else 0.0, 4),
-                    "complexity_variance"     : round(np.var(chunk_features['complexities']) if chunk_features['complexities'] else 0.0, 4),
+                    "synthetic_pattern_score" : round(synthetic_pattern_score, 4),
+                    "avg_chunk_complexity"    : round(avg_chunk_complexity, 4),
+                    "complexity_variance"     : round(complexity_variance, 4),
                     "num_sentences"           : len(list(doc.sents)),
-                    "num_chunks_analyzed"     : len(chunk_features['complexities']),
+                    "num_chunks_analyzed"     : num_chunks,
                    }
             
         except Exception as e:
@@ -230,7 +224,7 @@ class LinguisticMetric(BaseMetric):
         """
         Calculate entropy of POS tag distribution
         """
-        if not pos_tags:
+        if (not pos_tags) or (len(pos_tags) < self.params.MIN_TAGS_FOR_ENTROPY):
             return 0.0
         
         pos_counts = Counter(pos_tags)
@@ -239,7 +233,8 @@ class LinguisticMetric(BaseMetric):
         entropy = 0.0
         for count in pos_counts.values():
             probability = count / total_tags
-            entropy    -= probability * np.log2(probability)
+            if probability > self.params.ZERO_TOLERANCE:
+                entropy -= probability * np.log2(probability)
         
         return entropy
     
@@ -260,7 +255,8 @@ class LinguisticMetric(BaseMetric):
             if depths:
                 avg_depth  = np.mean(depths)
                 max_depth  = np.max(depths)
-                complexity = (avg_depth + max_depth) / 2.0
+                complexity = (avg_depth * self.params.COMPLEXITY_WEIGHT_AVG + 
+                              max_depth * self.params.COMPLEXITY_WEIGHT_MAX)
                 complexities.append(complexity)
         
         return np.mean(complexities) if complexities else 0.0
@@ -287,11 +283,10 @@ class LinguisticMetric(BaseMetric):
         for sent in doc.sents:
             # Simple complexity measure based on sentence length and structure
             words       = [token for token in sent if not token.is_punct]
-            num_clauses = len([token for token in sent if token.dep_ in ['cc', 'mark']])
+            num_clauses = len([token for token in sent if token.dep_ in self.params.CLAUSE_MARKERS])
             
             if (len(words) > 0):
-                complexity = (len(words) / 10.0) + (num_clauses * 0.5)
-
+                complexity = (len(words) / self.params.WORDS_PER_COMPLEXITY_UNIT) + (num_clauses * self.params.CLAUSE_COMPLEXITY_FACTOR)
                 complexities.append(complexity)
         
         return np.mean(complexities) if complexities else 0.0
@@ -307,21 +302,19 @@ class LinguisticMetric(BaseMetric):
         transition_words     = 0
         total_sentences      = 0
         
-        transition_words_set = {'however', 'therefore', 'moreover', 'furthermore', 'consequently', 'additionally', 'nevertheless', 'nonetheless', 'thus', 'hence'}
-        
         for sent in doc.sents:
             total_sentences += 1
             sent_text        = sent.text.lower()
             
             # Check for passive voice patterns
-            if (any(token.dep_ == 'nsubjpass' for token in sent)):
+            if (any(token.dep_ == self.params.PASSIVE_DEPENDENCY for token in sent)):
                 passive_voice += 1
             
             else:
-                active_voice += 1
+                active_voice += 1       
             
-            # Count transition words
-            for word in transition_words_set:
+            # Count transition words``
+            for word in self.params.TRANSITION_WORDS_SET:
                 if word in sent_text:
                     transition_words += 1
                     break
@@ -331,7 +324,8 @@ class LinguisticMetric(BaseMetric):
         transition_usage = transition_words / total_sentences if total_sentences > 0 else 0.0
         
         # Calculate consistency (lower variance in patterns)
-        consistency      = 1.0 - min(1.0, abs(passive_ratio - 0.3) + abs(transition_usage - 0.2))
+        consistency      = 1.0 - min(1.0, abs(passive_ratio - self.params.IDEAL_PASSIVE_RATIO) + 
+                                     abs(transition_usage - self.params.IDEAL_TRANSITION_RATIO))
         
         return {'consistency'      : max(0.0, consistency),
                 'passive_ratio'    : passive_ratio,
@@ -350,24 +344,22 @@ class LinguisticMetric(BaseMetric):
         
         if sent_lengths:
             length_variation = np.std(sent_lengths) / np.mean(sent_lengths) if np.mean(sent_lengths) > 0 else 0.0
-            # Moderate variation is more human-like
-            style_score      = 1.0 - min(1.0, abs(length_variation - 0.5))
-
+            # Moderate variation is more authentic-like
+            style_score      = 1.0 - min(1.0, abs(length_variation - self.params.IDEAL_LENGTH_VARIATION))
             style_indicators.append(style_score)
         
         # Punctuation usage
         punct_ratio = len([token for token in doc if token.is_punct]) / len(doc) if len(doc) > 0 else 0.0
-        # Balanced punctuation is more human-like
-        punct_score = 1.0 - min(1.0, abs(punct_ratio - 0.1))
-
+        # Balanced punctuation is more authentic-like
+        punct_score = 1.0 - min(1.0, abs(punct_ratio - self.params.IDEAL_PUNCTUATION_RATIO))
         style_indicators.append(punct_score)
         
         return np.mean(style_indicators) if style_indicators else 0.5
     
 
-    def _detect_ai_linguistic_patterns(self, doc) -> float:
+    def _detect_synthetic_linguistic_patterns(self, doc) -> float:
         """
-        Detect AI-specific linguistic patterns
+        Detect synthetic-specific linguistic patterns
         """ 
         patterns_detected     = 0
         total_patterns        = 5
@@ -407,13 +399,12 @@ class LinguisticMetric(BaseMetric):
 
     def _check_transition_overuse(self, doc) -> bool:
         """
-        Check for overuse of transition words (common AI pattern)
+        Check for overuse of transition words (common synthetic pattern)
         """
-        transition_words = {'however', 'therefore', 'moreover', 'furthermore', 'additionally'}
-        transition_count = sum(1 for token in doc if token.lemma_.lower() in transition_words)
+        transition_count = sum(1 for token in doc if token.lemma_.lower() in self.params.TRANSITION_WORDS_SET)
         
-        # More than 5% of words being transitions is suspicious
-        return transition_count / len(doc) > 0.05 if len(doc) > 0 else False
+        # More than threshold of words being transitions is suspicious
+        return transition_count / len(doc) > self.params.TRANSITION_OVERUSE_THRESHOLD if len(doc) > 0 else False
     
 
     def _check_unnatural_pos_sequences(self, doc) -> bool:
@@ -433,8 +424,8 @@ class LinguisticMetric(BaseMetric):
         sequence_counts  = Counter(pos_sequences)
         most_common_freq = max(sequence_counts.values()) / len(pos_sequences) if pos_sequences else 0
         
-        # High frequency of specific sequences suggests AI
-        return (most_common_freq > 0.1)
+        # High frequency of specific sequences suggests synthetic
+        return (most_common_freq > self.params.POS_SEQUENCE_FREQ_THRESHOLD)
     
 
     def _check_structure_consistency(self, doc) -> bool:
@@ -448,15 +439,15 @@ class LinguisticMetric(BaseMetric):
             structure = tuple(token.dep_ for token in sent if token.dep_ not in ['punct', 'det'])
             sent_structures.append(structure)
         
-        if (len(sent_structures) < 3):
+        if (len(sent_structures) < self.params.MIN_SENTENCES_FOR_STRUCTURE):
             return False
         
         # Calculate structure similarity
         unique_structures = len(set(sent_structures))
         similarity_ratio  = unique_structures / len(sent_structures)
         
-        # Low diversity suggests AI
-        return (similarity_ratio < 0.5)
+        # Low diversity suggests synthetic
+        return (similarity_ratio < self.params.STRUCTURE_DIVERSITY_THRESHOLD)
     
 
     def _check_unusual_grammar(self, doc) -> bool:
@@ -467,11 +458,11 @@ class LinguisticMetric(BaseMetric):
         
         for token in doc:
             # Check for unusual dependency relations i.e. less common relations
-            if token.dep_ in ['attr', 'oprd']:  
+            if token.dep_ in self.params.UNUSUAL_DEPENDENCIES:  
                 unusual_constructions += 1
         
-        # More than 2% unusual constructions is suspicious
-        return (unusual_constructions / len(doc) > 0.02) if (len(doc) > 0) else False
+        # More than threshold unusual constructions is suspicious
+        return (unusual_constructions / len(doc) > self.params.UNUSUAL_CONSTRUCTION_THRESHOLD) if (len(doc) > 0) else False
     
 
     def _check_repetitive_phrasing(self, doc) -> bool:
@@ -491,26 +482,29 @@ class LinguisticMetric(BaseMetric):
         phrase_counts    = Counter(phrases)
         repeated_phrases = sum(1 for count in phrase_counts.values() if count > 1)
         
-        # High repetition suggests AI
-        return (repeated_phrases / len(phrases) > 0.3)
+        # High repetition suggests synthetic
+        return (repeated_phrases / len(phrases) > self.params.REPETITIVE_PHRASING_THRESHOLD)
     
 
-    def _calculate_chunk_linguistics(self, text: str, chunk_size: int = 200) -> Dict[str, List[float]]:
+    def _calculate_chunk_linguistics(self, text: str) -> List[float]:
         """
         Calculate linguistic features across text chunks
         """
         complexities = list()
         words        = text.split()
-        
-        for i in range(0, len(words), chunk_size // 2):
+        chunk_size   = self.params.CHUNK_SIZE_WORDS
+        overlap      = int(chunk_size * self.params.CHUNK_OVERLAP_RATIO)
+        step         = max(1, chunk_size - overlap)
+
+        for i in range(0, len(words), step):
             chunk = ' '.join(words[i:i + chunk_size])
             
-            if (len(chunk) > 50):
+            if (len(chunk) > self.params.MIN_CHUNK_LENGTH):
                 try:
                     chunk_doc = self.nlp(chunk)
                     
                     # Check if processing was successful
-                    if (chunk_doc and (len(list(chunk_doc.sents)) > 0)):
+                    if (chunk_doc and (len(list(chunk_doc.sents)) > self.params.MIN_SENTENCES_FOR_ANALYSIS)):
                         complexity = self._calculate_syntactic_complexity(chunk_doc)
                         complexities.append(complexity)
                 
@@ -518,141 +512,147 @@ class LinguisticMetric(BaseMetric):
                     logger.debug(f"Chunk linguistic analysis failed: {e}")
                     continue
         
-        return {'complexities': complexities}
+        return complexities
     
 
     def _analyze_linguistic_patterns(self, features: Dict[str, Any]) -> tuple:
         """
-        Analyze linguistic patterns to determine RAW linguistic score (0-1 scale) : Higher score = more AI-like
+        Analyze linguistic patterns to determine RAW linguistic score (0-1 scale) : Higher score = more synthetic-like
         """
         # Check feature validity first
-        required_features = ['pos_diversity', 'syntactic_complexity', 'grammatical_consistency', 'transition_word_usage', 'ai_pattern_score', 'complexity_variance']
+        required_features = ['pos_diversity', 'pos_entropy', 'syntactic_complexity', 'grammatical_consistency', 'transition_word_usage', 'synthetic_pattern_score', 'complexity_variance']
         
-        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > 0]
+        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > self.params.ZERO_TOLERANCE]
         
-        if (len(valid_features) < 4):
+        if (len(valid_features) < self.params.MIN_REQUIRED_FEATURES):
             # Low confidence if insufficient features
-            return 0.5, 0.3  
+            return self.params.NEUTRAL_PROBABILITY, self.params.LOW_FEATURE_CONFIDENCE
 
-        # Initialize ai_indicator list 
-        ai_indicators = list()
+        # Initialize synthetic_indicator list 
+        synthetic_indicators = list()
         
-        # Low POS diversity suggests AI
-        if (features['pos_diversity'] < 0.3):
-            ai_indicators.append(0.8)
+        # Low POS diversity suggests synthetic
+        if (features['pos_diversity'] < self.params.POS_DIVERSITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)
 
-        elif (features['pos_diversity'] < 0.5):
-            ai_indicators.append(0.6)
+        elif (features['pos_diversity'] < self.params.POS_DIVERSITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
+
+        
+        # Low POS entropy suggests templated / synthetic language
+        if (features['pos_entropy'] < self.params.POS_ENTROPY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)
         
-        # Low syntactic complexity suggests AI
-        if (features['syntactic_complexity'] < 2.0):
-            ai_indicators.append(0.7)
+        # Low syntactic complexity suggests synthetic
+        if (features['syntactic_complexity'] < self.params.SYNTACTIC_COMPLEXITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
-        elif (features['syntactic_complexity'] < 3.0):
-            ai_indicators.append(0.4)
+        elif (features['syntactic_complexity'] < self.params.SYNTACTIC_COMPLEXITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.VERY_LOW_SYNTHETIC_WEIGHT)
         
-        # High grammatical consistency suggests AI (unnaturally consistent)
-        if (features['grammatical_consistency'] > 0.8):
-            ai_indicators.append(0.9)
+        # High grammatical consistency suggests synthetic (unnaturally consistent)
+        if (features['grammatical_consistency'] > self.params.GRAMMATICAL_CONSISTENCY_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)
 
-        elif (features['grammatical_consistency'] > 0.6):
-            ai_indicators.append(0.5)
+        elif (features['grammatical_consistency'] > self.params.GRAMMATICAL_CONSISTENCY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(self.params.LOW_SYNTHETIC_WEIGHT)
         
-        # High transition word usage suggests AI
-        if (features['transition_word_usage'] > 0.3):
-            ai_indicators.append(0.7)
+        # High transition word usage suggests synthetic
+        if (features['transition_word_usage'] > self.params.TRANSITION_USAGE_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
         
-        elif (features['transition_word_usage'] > 0.15):
-            ai_indicators.append(0.4)
+        elif (features['transition_word_usage'] > self.params.TRANSITION_USAGE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.VERY_LOW_SYNTHETIC_WEIGHT)
         
-        # High AI pattern score suggests AI
-        if (features['ai_pattern_score'] > 0.6):
-            ai_indicators.append(0.8)
+        # High synthetic pattern score suggests synthetic
+        if (features['synthetic_pattern_score'] > self.params.SYNTHETIC_PATTERN_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
-        elif (features['ai_pattern_score'] > 0.3):
-            ai_indicators.append(0.5)
+        elif (features['synthetic_pattern_score'] > self.params.SYNTHETIC_PATTERN_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.MODERATE_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # Low complexity variance suggests AI
-        if (features['complexity_variance'] < 0.1):
-            ai_indicators.append(0.7)
+        # Low complexity variance suggests synthetic
+        if (features['complexity_variance'] < self.params.COMPLEXITY_VARIANCE_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
-        elif (features['complexity_variance'] < 0.3):
-            ai_indicators.append(0.4)
+        elif (features['complexity_variance'] < self.params.COMPLEXITY_VARIANCE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.VERY_LOW_SYNTHETIC_WEIGHT)
         
         # Calculate raw score and confidence
-        raw_score  = np.mean(ai_indicators) if ai_indicators else 0.5
-        confidence = 1.0 - (np.std(ai_indicators) / 0.5) if ai_indicators else 0.5
-        confidence = max(0.1, min(0.9, confidence))
+        raw_score  = np.mean(synthetic_indicators) if synthetic_indicators else self.params.NEUTRAL_PROBABILITY
+        confidence = 1.0 - (np.std(synthetic_indicators) / self.params.CONFIDENCE_STD_NORMALIZER) if synthetic_indicators else self.params.NEUTRAL_CONFIDENCE
+        confidence = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
         
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content
+        Calculate probability of hybrid synthetic/authentic content
         """
-        mixed_indicators = list()
+        hybrid_indicators = list()
         
         # Moderate POS diversity might indicate mixing
-        if (0.35 <= features['pos_diversity'] <= 0.55):
-            mixed_indicators.append(0.3)
+        if (self.params.POS_DIVERSITY_MIXED_MIN <= features['pos_diversity'] <= self.params.POS_DIVERSITY_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # High complexity variance suggests mixed content
-        if (features['complexity_variance'] > 0.5):
-            mixed_indicators.append(0.4)
+        if (features['complexity_variance'] > self.params.COMPLEXITY_VARIANCE_HIGH_THRESHOLD):
+            hybrid_indicators.append(self.params.MODERATE_HYBRID_WEIGHT)
 
-        elif (features['complexity_variance'] > 0.3):
-            mixed_indicators.append(0.2)
+        elif (features['complexity_variance'] > self.params.COMPLEXITY_VARIANCE_MEDIUM_THRESHOLD):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
-        # Inconsistent AI pattern detection
-        if (0.2 <= features['ai_pattern_score'] <= 0.6):
-            mixed_indicators.append(0.3)
+        # Inconsistent synthetic pattern detection
+        if (self.params.SYNTHETIC_PATTERN_MIXED_MIN <= features['synthetic_pattern_score'] <= self.params.SYNTHETIC_PATTERN_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
-        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        hybrid_prob = np.mean(hybrid_indicators) if hybrid_indicators else 0.0
+        return min(self.params.MAX_HYBRID_PROBABILITY, hybrid_prob)
     
 
     def _get_default_features(self) -> Dict[str, Any]:
         """
         Return default features when analysis is not possible
         """
-        return {"pos_diversity"           : 0.5,
-                "pos_entropy"             : 2.5,
-                "syntactic_complexity"    : 2.5,
-                "avg_sentence_complexity" : 2.0,
-                "grammatical_consistency" : 0.5,
-                "transition_word_usage"   : 0.1,
-                "passive_voice_ratio"     : 0.2,
-                "writing_style_score"     : 0.5,
-                "ai_pattern_score"        : 0.3,
-                "avg_chunk_complexity"    : 2.5,
-                "complexity_variance"     : 0.2,
+        return {"pos_diversity"           : self.params.DEFAULT_POS_DIVERSITY,
+                "pos_entropy"             : self.params.DEFAULT_POS_ENTROPY,
+                "syntactic_complexity"    : self.params.DEFAULT_SYNTACTIC_COMPLEXITY,
+                "avg_sentence_complexity" : self.params.DEFAULT_SENTENCE_COMPLEXITY,
+                "grammatical_consistency" : self.params.DEFAULT_GRAMMATICAL_CONSISTENCY,
+                "transition_word_usage"   : self.params.DEFAULT_TRANSITION_USAGE,
+                "passive_voice_ratio"     : self.params.DEFAULT_PASSIVE_RATIO,
+                "writing_style_score"     : self.params.DEFAULT_WRITING_STYLE_SCORE,
+                "synthetic_pattern_score" : self.params.DEFAULT_SYNTHETIC_PATTERN_SCORE,
+                "avg_chunk_complexity"    : self.params.DEFAULT_CHUNK_COMPLEXITY,
+                "complexity_variance"     : self.params.DEFAULT_COMPLEXITY_VARIANCE,
                 "num_sentences"           : 0,
                 "num_chunks_analyzed"     : 0,
                }

metrics/multi_perturbation_stability.py

@@ -1,25 +1,23 @@
 # DEPENDENCIES
-import re
 import torch
 import numpy as np
 from typing import Any
 from typing import Dict
 from typing import List
 from loguru import logger
-from transformers import pipeline
-from config.threshold_config import Domain
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import BaseMetric
-from metrics.base_metric import MetricResult
 from models.model_manager import get_model_manager
 from config.threshold_config import get_threshold_for_domain
-
+from config.constants import multi_perturbation_stability_metric_params
 
 
 class MultiPerturbationStabilityMetric(BaseMetric):
     """
     Multi-Perturbation Stability Metric (MPSM) 
     
-    A hybrid approach for combining multiple perturbation techniques for robust AI-generated text detection
+    A hybrid approach for combining multiple perturbation techniques for robust synthetic-generated text detection
     
     Measures:
     - Text stability under random perturbations
@@ -27,7 +25,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
     - Masked token prediction analysis
 
     Perturbation Methods:
-    - Word deletation & swapping
+    - Word deletion & swapping
     - RoBERTa mask filling
     - Synonym replacement
     - Chunk-based stability Analysis
@@ -42,6 +40,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         self.mask_model     = None
         self.mask_tokenizer = None
         self.device         = torch.device("cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu")
+        self.params         = multi_perturbation_stability_metric_params
     
 
     def initialize(self) -> bool:
@@ -145,14 +144,8 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         Compute MultiPerturbationStability analysis with FULL DOMAIN THRESHOLD INTEGRATION
         """
         try:
-            if ((not text) or (len(text.strip()) < 50)):
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    error             = "Text too short for MultiPerturbationStability analysis",
-                                   )
+            if ((not text) or (len(text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_ANALYSIS)):
+                return self._default_result(error = "Text too short for MultiPerturbationStability analysis")
             
             # Get domain-specific thresholds
             domain                                  = kwargs.get('domain', Domain.GENERAL)
@@ -162,105 +155,91 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             # Check if we should run this computationally expensive metric
             if (kwargs.get('skip_expensive', False)):
                 logger.info("Skipping MultiPerturbationStability due to computational constraints")
-                
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.3,
-                                    error             = "Skipped for performance",
-                                   )
+                return self._default_result(error = "Skipped for performance")
             
             # Calculate MultiPerturbationStability features
-            features                        = self._calculate_stability_features(text = text)
+            features                                    = self._calculate_stability_features(text = text)
             
             # Calculate raw MultiPerturbationStability score (0-1 scale)
-            raw_stability_score, confidence = self._analyze_stability_patterns(features = features)
+            raw_stability_score, confidence             = self._analyze_stability_patterns(features = features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob = self._apply_domain_thresholds(raw_score  = raw_stability_score, 
-                                                                            thresholds = multi_perturbation_stability_thresholds, 
-                                                                            features   = features,
-                                                                           )
+            synthetic_prob, authentic_prob, hybrid_prob = self._apply_domain_thresholds(raw_score  = raw_stability_score, 
+                                                                                        thresholds = multi_perturbation_stability_thresholds, 
+                                                                                        features   = features,
+                                                                                       )
             
             # Apply confidence multiplier from domain thresholds
-            confidence                     *= multi_perturbation_stability_thresholds.confidence_multiplier
-            confidence                      = max(0.0, min(1.0, confidence))
-            
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : multi_perturbation_stability_thresholds.ai_threshold,
-                                                     'human_threshold' : multi_perturbation_stability_thresholds.human_threshold,
-                                                     'raw_score'       : raw_stability_score,
-                                                    },
+            confidence                                 *= multi_perturbation_stability_thresholds.confidence_multiplier
+            confidence                                  = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
+            
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'        : domain.value,
+                                                         'synthetic_threshold': multi_perturbation_stability_thresholds.synthetic_threshold,
+                                                         'authentic_threshold': multi_perturbation_stability_thresholds.authentic_threshold,
+                                                         'raw_score'          : raw_stability_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in MultiPerturbationStability computation: {repr(e)}")
-
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold      # e.g., 0.75 for GENERAL, 0.80 for ACADEMIC
-        human_threshold = thresholds.human_threshold   # e.g., 0.25 for GENERAL, 0.20 for ACADEMIC
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
         
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
+        if (raw_score >= synthetic_threshold):
+            # Above synthetic threshold - strongly synthetic
+            distance_from_threshold = raw_score - synthetic_threshold
+            synthetic_prob          = self.params.STRONG_SYNTHETIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
 
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
+        elif (raw_score <= authentic_threshold):
+            # Below authentic threshold - strongly authentic
+            distance_from_threshold = authentic_threshold - raw_score
+            synthetic_prob          = self.params.UNCERTAIN_SYNTHETIC_RANGE_START - (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = self.params.STRONG_AUTHENTIC_BASE_PROB + (distance_from_threshold * self.params.WEAK_PROBABILITY_ADJUSTMENT)
 
         else:
             # Between thresholds - uncertain zone
-            range_width             = ai_threshold - human_threshold
+            range_width = synthetic_threshold - authentic_threshold
 
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            if (range_width > self.params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = self.params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob    = 0.5
-                human_prob = 0.5
+                synthetic_prob = self.params.NEUTRAL_PROBABILITY
+                authentic_prob = self.params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on stability variance
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on stability variance
+        hybrid_prob    = self._calculate_hybrid_probability(features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
+        total          = synthetic_prob + authentic_prob + hybrid_prob
 
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        if (total > self.params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
     
 
     def _calculate_stability_features(self, text: str) -> Dict[str, Any]:
@@ -279,9 +258,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             logger.debug(f"Original likelihood: {original_likelihood:.4f}")
             
             # Generate perturbations and calculate perturbed likelihoods
-            perturbations         = self._generate_perturbations(text              = processed_text,
-                                                                 num_perturbations = 10,
-                                                                )
+            perturbations         = self._generate_perturbations(text = processed_text)
             logger.debug(f"Generated {len(perturbations)} perturbations")
 
             perturbed_likelihoods = list()
@@ -290,14 +267,14 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                 if (perturbed_text and (perturbed_text != processed_text)):
                     likelihood = self._calculate_likelihood(text = perturbed_text)
                     
-                    if (likelihood > 0):
+                    if (likelihood > self.params.ZERO_TOLERANCE):
                         perturbed_likelihoods.append(likelihood)
                         logger.debug(f"Perturbation {idx}: likelihood={likelihood:.4f}")
             
             logger.info(f"Valid perturbations: {len(perturbed_likelihoods)}/{len(perturbations)}")
             
             # Calculate stability metrics
-            if perturbed_likelihoods:
+            if perturbed_likelihoods and (len(perturbed_likelihoods) >= self.params.MIN_VALID_PERTURBATIONS):
                 stability_score          = self._calculate_stability_score(original_likelihood   = original_likelihood, 
                                                                            perturbed_likelihoods = perturbed_likelihoods,
                                                                           )
@@ -313,27 +290,24 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             
             else:
                 # Use meaningful defaults when perturbations fail
-                stability_score          = 0.3  # Assume more human-like when no perturbations work
-                curvature_score          = 0.3
-                variance_score           = 0.05
+                stability_score          = self.params.DEFAULT_STABILITY_SCORE  # Assume more authentic-like when no perturbations work
+                curvature_score          = self.params.DEFAULT_CURVATURE_SCORE
+                variance_score           = self.params.DEFAULT_PERTURBATION_VARIANCE
                 avg_perturbed_likelihood = original_likelihood * 0.9  # Assume some drop
                 logger.warning("No valid perturbations, using fallback values")
             
             # Calculate likelihood ratio
-            likelihood_ratio             = original_likelihood / avg_perturbed_likelihood if avg_perturbed_likelihood > 0 else 1.0
+            likelihood_ratio             = original_likelihood / avg_perturbed_likelihood if avg_perturbed_likelihood > self.params.ZERO_TOLERANCE else 1.0
             
             # Chunk-based analysis for whole-text understanding
-            chunk_stabilities            = self._calculate_chunk_stability(text       = processed_text, 
-                                                                           chunk_size = 150,
-                                                                          )
-
-            stability_variance           = np.var(chunk_stabilities) if chunk_stabilities else 0.1 
+            chunk_stabilities            = self._calculate_chunk_stability(text = processed_text)
+            stability_variance           = np.var(chunk_stabilities) if chunk_stabilities else self.params.DEFAULT_STABILITY_VARIANCE 
             avg_chunk_stability          = np.mean(chunk_stabilities) if chunk_stabilities else stability_score
             
             # Better normalization to prevent extreme values
             normalized_stability         = min(1.0, max(0.0, stability_score))
             normalized_curvature         = min(1.0, max(0.0, curvature_score))
-            normalized_likelihood_ratio  = min(3.0, max(0.33, likelihood_ratio)) / 3.0
+            normalized_likelihood_ratio  = min(self.params.MAX_LIKELIHOOD_RATIO, max(self.params.MIN_LIKELIHOOD_RATIO, likelihood_ratio)) / self.params.MAX_LIKELIHOOD_RATIO
             
             return {"original_likelihood"         : round(original_likelihood, 4),
                     "avg_perturbed_likelihood"    : round(avg_perturbed_likelihood, 4),
@@ -361,12 +335,13 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         """
         try:
             # Check text length before tokenization
-            if (len(text.strip()) < 10):
-                return 2.0  # Return reasonable baseline
+            if (len(text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_PERTURBATION):
+                # Return reasonable baseline
+                return self.params.DEFAULT_LIKELIHOOD  
 
             if not self.gpt_model or not self.gpt_tokenizer:
                 logger.warning("GPT model not available for likelihood calculation")
-                return 2.0
+                return self.params.DEFAULT_LIKELIHOOD
 
             # Ensure tokenizer has pad token
             if self.gpt_tokenizer.pad_token is None:
@@ -376,7 +351,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             encodings      = self.gpt_tokenizer(text, 
                                                 return_tensors        = 'pt', 
                                                 truncation            = True,
-                                                max_length            = 256,
+                                                max_length            = self.params.MAX_TOKEN_LENGTH,
                                                 padding               = True,
                                                 return_attention_mask = True,
                                                )
@@ -385,8 +360,8 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             attention_mask = encodings.attention_mask.to(self.device)
             
             # Minimum tokens for meaningful analysis
-            if ((input_ids.numel() == 0) or (input_ids.size(1) < 3)):
-                return 2.0
+            if ((input_ids.numel() == 0) or (input_ids.size(1) < self.params.MIN_TOKENS_FOR_LIKELIHOOD)):
+                return self.params.DEFAULT_LIKELIHOOD
             
             # Calculate proper log-likelihood using token probabilities
             with torch.no_grad():
@@ -419,18 +394,17 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                     avg_log_likelihood = 0.0
             
             # Convert to positive scale and normalize
-            # Typical GPT-2 log probabilities range from ~-10 to ~-2
-            # Higher normalized value = more likely text
-            normalized_likelihood = max(0.5, min(10.0, -avg_log_likelihood))
+            normalized_likelihood = max(self.params.MIN_LIKELIHOOD, min(self.params.MAX_LIKELIHOOD, -avg_log_likelihood))
             
             return normalized_likelihood
             
         except Exception as e:
             logger.warning(f"Likelihood calculation failed: {repr(e)}")
-            return 2.0  # Return reasonable baseline on error
+            # Return reasonable baseline on error
+            return self.params.DEFAULT_LIKELIHOOD  
     
 
-    def _generate_perturbations(self, text: str, num_perturbations: int = 5) -> List[str]:
+    def _generate_perturbations(self, text: str) -> List[str]:
         """
         Generate perturbed versions of the text using multiple techniques:
         1. Word deletion (simple but effective)
@@ -439,21 +413,22 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         4. Synonym replacement (fallback)
         """
         perturbations = list()
+        num_perturbations = self.params.NUM_PERTURBATIONS
         
         try:
             # Pre-process text for perturbation
             processed_text = self._preprocess_text_for_perturbation(text)
             words          = processed_text.split()
             
-            if (len(words) < 3):
+            if (len(words) < self.params.MIN_WORDS_FOR_PERTURBATION):
                 return [processed_text]
 
             # Method 1: Simple word deletion (most reliable)
-            if (len(words) > 5):
+            if (len(words) > self.params.MIN_WORDS_FOR_DELETION):
                 for _ in range(min(3, num_perturbations)):
                     try:
-                        # Delete random words (10-20% of text)
-                        delete_count    = max(1, len(words) // 10)
+                        # Delete random words
+                        delete_count    = max(1, int(len(words) * self.params.PERTURBATION_DELETION_RATIO))
                         indices_to_keep = np.random.choice(len(words), len(words) - delete_count, replace = False)
                         
                         perturbed_words = [words[i] for i in sorted(indices_to_keep)]
@@ -490,9 +465,8 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             if (self.mask_model and self.mask_tokenizer and (len(words) > 4) and len(perturbations) < num_perturbations):
                 
                 try:
-                    roberta_perturbations = self._generate_roberta_masked_perturbations(text              = processed_text, 
-                                                                                        words             = words, 
-                                                                                        max_perturbations = num_perturbations - len(perturbations),
+                    roberta_perturbations = self._generate_roberta_masked_perturbations(text  = processed_text, 
+                                                                                        words = words,
                                                                                        )
                     perturbations.extend(roberta_perturbations)
                     
@@ -502,10 +476,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             # Method 4: Synonym replacement as fallback
             if (len(perturbations) < num_perturbations):
                 try:
-                    synonym_perturbations = self._generate_synonym_perturbations(text              = processed_text, 
-                                                                                 words             = words, 
-                                                                                 max_perturbations = num_perturbations - len(perturbations),
-                                                                                )
+                    synonym_perturbations = self._generate_synonym_perturbations(text = processed_text, words = words)
                     perturbations.extend(synonym_perturbations)
                     
                 except Exception as e:
@@ -533,12 +504,13 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             return [text]  # Return at least the original text as fallback
     
 
-    def _generate_roberta_masked_perturbations(self, text: str, words: List[str], max_perturbations: int) -> List[str]:
+    def _generate_roberta_masked_perturbations(self, text: str, words: List[str]) -> List[str]:
         """
         Generate perturbations using DistilRoBERTa mask filling
-        This is inspired by DetectGPT but uses a lighter model (DistilRoBERTa instead of T5)
+        - This is inspired by DetectGPT but uses a lighter model (DistilRoBERTa instead of T5)
         """
-        perturbations = list()
+        perturbations     = list()
+        max_perturbations = min(self.params.MAX_PERTURBATION_ATTEMPTS, self.params.NUM_PERTURBATIONS - len(perturbations))
         
         try:
             # Use the proper DistilRoBERTa mask token from tokenizer
@@ -546,13 +518,14 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                 roberta_mask_token = self.mask_tokenizer.mask_token
             
             else:
-                roberta_mask_token = "<mask>"  # Fallback
+                # Fallback
+                roberta_mask_token = "<mask>"  
             
             # Select words to mask (avoid very short words and punctuation)
-            candidate_positions = [i for i, word in enumerate(words) if (len(word) > 3) and word.isalpha() and word.lower() not in ['the', 'and', 'but', 'for', 'with']]
+            candidate_positions = [i for i, word in enumerate(words) if (len(word) > 3) and word.isalpha() and word.lower() not in self.params.COMMON_WORDS_TO_AVOID]
             
             if not candidate_positions:
-                candidate_positions = [i for i, word in enumerate(words) if len(word) > 2]
+                candidate_positions = [i for i, word in enumerate(words) if (len(word) > 2)]
             
             if not candidate_positions:
                 return perturbations
@@ -577,15 +550,15 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                         masked_text += '.'
                     
                     # Tokenize with DistilRoBERTa-specific settings
-                    inputs = self.mask_tokenizer(masked_text,
-                                                 return_tensors = "pt",
-                                                 truncation     = True,
-                                                 max_length     = min(128, self.mask_tokenizer.model_max_length),
-                                                 padding        = True,
-                                                )
+                    inputs            = self.mask_tokenizer(masked_text,
+                                                            return_tensors = "pt",
+                                                            truncation     = True,
+                                                            max_length     = min(self.params.MAX_ROBERTA_TOKEN_LENGTH, self.mask_tokenizer.model_max_length),
+                                                            padding        = True,
+                                                           )
                     
                     # Move to appropriate device
-                    inputs = {k: v.to(self.device) for k, v in inputs.items()}
+                    inputs            = {k: v.to(self.device) for k, v in inputs.items()}
                     
                     # Get model predictions
                     with torch.no_grad():
@@ -602,7 +575,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                     
                     # Get top prediction
                     probs            = torch.nn.functional.softmax(predictions[0, mask_token_index], dim = -1)
-                    top_tokens       = torch.topk(probs, 3, dim = -1)
+                    top_tokens       = torch.topk(probs, self.params.ROBBERTA_TOP_K_PREDICTIONS, dim = -1)
                     
                     for token_id in top_tokens.indices:
                         predicted_token = self.mask_tokenizer.decode(token_id).strip()
@@ -631,11 +604,12 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         return perturbations
     
 
-    def _generate_synonym_perturbations(self, text: str, words: List[str], max_perturbations: int) -> List[str]:
+    def _generate_synonym_perturbations(self, text: str, words: List[str]) -> List[str]:
         """
         Simple synonym replacement as fallback
         """
-        perturbations = list()
+        perturbations     = list()
+        max_perturbations = self.params.NUM_PERTURBATIONS - len(perturbations)
         
         try:
             # Simple manual synonym dictionary for common words
@@ -653,7 +627,10 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             if not replaceable_positions:
                 return perturbations
             
-            positions_to_try      = np.random.choice(replaceable_positions, min(max_perturbations, len(replaceable_positions)), replace = False)
+            positions_to_try      = np.random.choice(replaceable_positions, 
+                                                     min(max_perturbations, len(replaceable_positions)), 
+                                                     replace = False,
+                                                    )
             
             for pos in positions_to_try:
                 original_word = words[pos].lower()
@@ -702,17 +679,17 @@ class MultiPerturbationStabilityMetric(BaseMetric):
 
     def _calculate_stability_score(self, original_likelihood: float, perturbed_likelihoods: List[float]) -> float:
         """
-        Calculate text stability score with improved normalization : AI text typically shows higher stability (larger drops) than human text
+        Calculate text stability score with normalization : synthetic text typically shows larger likelihood drops under perturbation than authentic text
         """
-        if ((not perturbed_likelihoods) or (original_likelihood <= 0)):
-            # Assume more human-like when no data
-            return 0.3  
+        if ((not perturbed_likelihoods) or (original_likelihood <= self.params.ZERO_TOLERANCE)):
+            # Assume more authentic-like when no data
+            return self.params.DEFAULT_STABILITY_SCORE  
         
         # Calculate relative likelihood drops
         relative_drops = list()
         
         for pl in perturbed_likelihoods:
-            if (pl > 0):
+            if (pl > self.params.ZERO_TOLERANCE):
                 # Use relative drop to handle scale differences
                 relative_drop = (original_likelihood - pl) / original_likelihood
                 
@@ -720,25 +697,25 @@ class MultiPerturbationStabilityMetric(BaseMetric):
                 relative_drops.append(max(0.0, min(1.0, relative_drop))) 
         
         if not relative_drops:
-            return 0.3
+            return self.params.DEFAULT_STABILITY_SCORE
         
         avg_relative_drop = np.mean(relative_drops)
         
-        # Normalization based on empirical observations : AI text typically shows 20-60% drops, human text shows 10-30% drops
-        if (avg_relative_drop > 0.5):
-            # Strong AI indicator
-            stability_score = 0.9  
+        # Normalization based on empirical observations : synthetic text typically shows larger drops
+        if (avg_relative_drop > self.params.RELATIVE_DROP_HIGH_THRESHOLD):
+            # Strong synthetic indicator
+            stability_score = self.params.STABILITY_HIGH_THRESHOLD  
 
-        elif (avg_relative_drop > 0.3):
-            # 0.6 to 0.9
-            stability_score = 0.6 + (avg_relative_drop - 0.3) * 1.5  
+        elif (avg_relative_drop > self.params.RELATIVE_DROP_MEDIUM_THRESHOLD):
+            # Intermediate values
+            stability_score = self.params.STABILITY_MEDIUM_THRESHOLD + (avg_relative_drop - self.params.RELATIVE_DROP_MEDIUM_THRESHOLD) * 1.5  
 
-        elif (avg_relative_drop > 0.15):
-            # 0.3 to 0.6
-            stability_score = 0.3 + (avg_relative_drop - 0.15) * 2.0  
+        elif (avg_relative_drop > self.params.RELATIVE_DROP_LOW_THRESHOLD):
+            # Lower values
+            stability_score = self.params.STABILITY_LOW_THRESHOLD + (avg_relative_drop - self.params.RELATIVE_DROP_LOW_THRESHOLD) * 2.0  
         
         else:
-            # 0.0 to 0.3
+            # Very low values
             stability_score = avg_relative_drop * 2.0  
 
         return min(1.0, max(0.0, stability_score))
@@ -748,51 +725,53 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         """
         Calculate likelihood curvature score with better scaling : Measures how "curved" the likelihood surface is around the text
         """
-        if ((not perturbed_likelihoods) or (original_likelihood <= 0)):
-            return 0.3
+        if ((not perturbed_likelihoods) or (original_likelihood <= self.params.ZERO_TOLERANCE)):
+            return self.params.DEFAULT_CURVATURE_SCORE
         
         # Calculate variance of likelihood changes
         likelihood_changes = [abs(original_likelihood - pl) for pl in perturbed_likelihoods]
         
         if (len(likelihood_changes) < 2):
-            return 0.3
+            return self.params.DEFAULT_CURVATURE_SCORE
             
         change_variance = np.var(likelihood_changes)
         
-        # Typical variance for meaningful analysis is around 0.1-0.5 : Adjusted scaling
-        curvature_score = min(1.0, change_variance * 3.0)  
+        # Typical variance for meaningful analysis
+        curvature_score = min(1.0, change_variance * self.params.CURVATURE_SCALING_FACTOR)  
         
         return curvature_score
     
 
-    def _calculate_chunk_stability(self, text: str, chunk_size: int = 150) -> List[float]:
+    def _calculate_chunk_stability(self, text: str) -> List[float]:
         """
         Calculate stability across text chunks for whole-text analysis
         """
         stabilities = list()
         words       = text.split()
+        chunk_size = self.params.CHUNK_SIZE_WORDS
+        overlap = int(chunk_size * self.params.CHUNK_OVERLAP_RATIO)
         
         # Create overlapping chunks
-        for i in range(0, len(words), chunk_size // 2):
+        for i in range(0, len(words), chunk_size - overlap):
             chunk = ' '.join(words[i:i + chunk_size])
             
-            if (len(chunk) > 50):
+            if (len(chunk) > self.params.MIN_CHUNK_LENGTH):
                 try:
                     chunk_likelihood = self._calculate_likelihood(text = chunk)
                     
-                    if (chunk_likelihood > 0):
+                    if (chunk_likelihood > self.params.ZERO_TOLERANCE):
                         # Generate a simple perturbation for this chunk
                         chunk_words = chunk.split()
                         
-                        if (len(chunk_words) > 5):
-                            # Delete 10% of words
-                            delete_count         = max(1, len(chunk_words) // 10)
+                        if (len(chunk_words) > self.params.MIN_WORDS_FOR_DELETION):
+                            # Delete a percentage of words
+                            delete_count         = max(1, int(len(chunk_words) * self.params.CHUNK_DELETION_RATIO))
                             indices_to_keep      = np.random.choice(len(chunk_words), len(chunk_words) - delete_count, replace=False)
                             perturbed_chunk      = ' '.join([chunk_words[i] for i in sorted(indices_to_keep)])
                             
                             perturbed_likelihood = self._calculate_likelihood(text = perturbed_chunk)
 
-                            if (perturbed_likelihood > 0):
+                            if (perturbed_likelihood > self.params.ZERO_TOLERANCE):
                                 stability = (chunk_likelihood - perturbed_likelihood) / chunk_likelihood
                                 stabilities.append(min(1.0, max(0.0, stability)))
 
@@ -809,135 +788,132 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         # Check feature validity first
         required_features = ['stability_score', 'curvature_score', 'normalized_likelihood_ratio', 'stability_variance', 'perturbation_variance']
         
-        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > 0]
+        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > self.params.ZERO_TOLERANCE]
         
-        if (len(valid_features) < 3):
+        if (len(valid_features) < self.params.MIN_REQUIRED_FEATURES):
             # Low confidence if insufficient features
-            return 0.5, 0.3  
+            return self.params.NEUTRAL_PROBABILITY, self.params.LOW_FEATURE_CONFIDENCE
 
 
-        # Initialize ai_indicator list
-        ai_indicators    = list()
+        # Initialize synthetic_indicator list
+        synthetic_indicators    = list()
         
         # Better weighting based on feature reliability
-        stability_weight = 0.3
-        curvature_weight = 0.25
-        ratio_weight     = 0.25
-        variance_weight  = 0.2
-        
-        # High stability score suggests AI (larger likelihood drops)
         stability = features['stability_score']
-        if (stability > 0.7):
-            ai_indicators.append(0.9 * stability_weight)
+        if (stability > self.params.STABILITY_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.STABILITY_STRONG_THRESHOLD * self.params.STABILITY_WEIGHT)
         
-        elif (stability > 0.5):
-            ai_indicators.append(0.7 * stability_weight)
+        elif (stability > self.params.STABILITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.STABILITY_MEDIUM_STRONG_THRESHOLD * self.params.STABILITY_WEIGHT)
         
-        elif (stability > 0.3):
-            ai_indicators.append(0.5 * stability_weight)
+        elif (stability > self.params.STABILITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.STABILITY_MODERATE_THRESHOLD * self.params.STABILITY_WEIGHT)
         
         else:
-            ai_indicators.append(0.2 * stability_weight)
+            synthetic_indicators.append(self.params.STABILITY_WEAK_THRESHOLD * self.params.STABILITY_WEIGHT)
         
-        # High curvature score suggests AI
+        # High curvature score suggests synthetic
         curvature = features['curvature_score']
-        if (curvature > 0.7):
-            ai_indicators.append(0.8 * curvature_weight)
+        if (curvature > self.params.CURVATURE_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.CURVATURE_STRONG_THRESHOLD * self.params.CURVATURE_WEIGHT)
         
-        elif (curvature > 0.5):
-            ai_indicators.append(0.6 * curvature_weight)
+        elif (curvature > self.params.CURVATURE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.CURVATURE_MEDIUM_THRESHOLD * self.params.CURVATURE_WEIGHT)
         
-        elif (curvature > 0.3):
-            ai_indicators.append(0.4 * curvature_weight)
+        elif (curvature > self.params.CURVATURE_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.CURVATURE_MODERATE_THRESHOLD * self.params.CURVATURE_WEIGHT)
         
         else:
-            ai_indicators.append(0.2 * curvature_weight)
+            synthetic_indicators.append(self.params.CURVATURE_WEAK_THRESHOLD * self.params.CURVATURE_WEIGHT)
         
-        # High likelihood ratio suggests AI (original much more likely than perturbations)
+        # High likelihood ratio suggests synthetic (original much more likely than perturbations)
         ratio = features['normalized_likelihood_ratio']
-        if (ratio > 0.8):
-            ai_indicators.append(0.9 * ratio_weight)
+        if (ratio > self.params.LIKELIHOOD_RATIO_HIGH_THRESHOLD):
+            synthetic_indicators.append(self.params.RATIO_STRONG_THRESHOLD * self.params.RATIO_WEIGHT)
         
-        elif (ratio > 0.6):
-            ai_indicators.append(0.7 * ratio_weight)
+        elif (ratio > self.params.LIKELIHOOD_RATIO_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.RATIO_MEDIUM_THRESHOLD * self.params.RATIO_WEIGHT)
         
-        elif (ratio > 0.4):
-            ai_indicators.append(0.5 * ratio_weight)
+        elif (ratio > self.params.LIKELIHOOD_RATIO_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.RATIO_MODERATE_THRESHOLD * self.params.RATIO_WEIGHT)
         
         else:
-            ai_indicators.append(0.3 * ratio_weight)
+            synthetic_indicators.append(self.params.RATIO_WEAK_THRESHOLD * self.params.RATIO_WEIGHT)
         
-        # Low stability variance suggests AI (consistent across chunks)
+        # Low stability variance suggests synthetic (consistent across chunks)
         stability_var = features['stability_variance']
-        if (stability_var < 0.05):
-            ai_indicators.append(0.8 * variance_weight)
+        if (stability_var < self.params.STABILITY_VARIANCE_VERY_LOW):
+            synthetic_indicators.append(self.params.VARIANCE_STRONG_THRESHOLD * self.params.VARIANCE_WEIGHT)
         
-        elif (stability_var < 0.1):
-            ai_indicators.append(0.5 * variance_weight)
+        elif (stability_var < self.params.STABILITY_VARIANCE_LOW):
+            synthetic_indicators.append(self.params.VARIANCE_MODERATE_THRESHOLD * self.params.VARIANCE_WEIGHT)
 
         else:
-            ai_indicators.append(0.2 * variance_weight)
+            synthetic_indicators.append(self.params.VARIANCE_WEAK_THRESHOLD * self.params.VARIANCE_WEIGHT)
         
         # Calculate raw score and confidence
-        if ai_indicators:
-            raw_score  = sum(ai_indicators)
-            confidence = 0.5 + (0.5 * (1.0 - (np.std([x / (weights := [stability_weight, curvature_weight, ratio_weight, variance_weight])[i] for i, x in enumerate(ai_indicators)]) if len(ai_indicators) > 1 else 0.5)))
+        if synthetic_indicators:
+            total_weight = (self.params.STABILITY_WEIGHT + self.params.CURVATURE_WEIGHT + self.params.RATIO_WEIGHT + self.params.VARIANCE_WEIGHT)
+            raw_score    = sum(synthetic_indicators) / total_weight
+            weights      = [self.params.STABILITY_WEIGHT, self.params.CURVATURE_WEIGHT, self.params.RATIO_WEIGHT, self.params.VARIANCE_WEIGHT]
+            confidence   = self.params.CONFIDENCE_BASE + (self.params.CONFIDENCE_STD_FACTOR * (1.0 - (np.std([x / weights[i] for i, x in enumerate(synthetic_indicators)]) if len(synthetic_indicators) > 1 else 0.5)))
        
         else:
-            raw_score  = 0.5
-            confidence = 0.3
+            raw_score  = self.params.NEUTRAL_PROBABILITY
+            confidence = self.params.LOW_FEATURE_CONFIDENCE
             
-        confidence = max(0.1, min(0.9, confidence))
+        confidence = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
         
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content
+        Calculate probability of hybrid synthetic/authentic content
         """
-        mixed_indicators = list()
+        hybrid_indicators = list()
         
         # Moderate stability values might indicate mixing
-        if (0.35 <= features['stability_score'] <= 0.55):
-            mixed_indicators.append(0.3)
+        if (self.params.STABILITY_MIXED_MIN <= features['stability_score'] <= self.params.STABILITY_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
        
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # High stability variance suggests mixed content
-        if (features['stability_variance'] > 0.15):
-            mixed_indicators.append(0.4)
+        if (features['stability_variance'] > self.params.STABILITY_VARIANCE_MIXED_HIGH):
+            hybrid_indicators.append(self.params.MODERATE_HYBRID_WEIGHT)
 
-        elif (features['stability_variance'] > 0.1):
-            mixed_indicators.append(0.2)
+        elif (features['stability_variance'] > self.params.STABILITY_VARIANCE_MIXED_MEDIUM):
+            hybrid_indicators.append(self.params.VERY_WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # Inconsistent likelihood ratios
-        if (0.5 <= features['normalized_likelihood_ratio'] <= 0.8):
-            mixed_indicators.append(0.3)
+        if (self.params.LIKELIHOOD_RATIO_MIXED_MIN <= features['normalized_likelihood_ratio'] <= self.params.LIKELIHOOD_RATIO_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
-        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        hybrid_prob = np.mean(hybrid_indicators) if hybrid_indicators else 0.0
+        return min(self.params.MAX_HYBRID_PROBABILITY, hybrid_prob)
     
 
     def _get_default_features(self) -> Dict[str, Any]:
         """
         Return more meaningful default features
         """
-        return {"original_likelihood"         : 2.0,
-                "avg_perturbed_likelihood"    : 1.8,
-                "likelihood_ratio"            : 1.1,
-                "normalized_likelihood_ratio" : 0.55,
-                "stability_score"             : 0.3, 
-                "curvature_score"             : 0.3,
-                "perturbation_variance"       : 0.05,
-                "avg_chunk_stability"         : 0.3,
-                "stability_variance"          : 0.1,
+        return {"original_likelihood"         : self.params.DEFAULT_ORIGINAL_LIKELIHOOD,
+                "avg_perturbed_likelihood"    : self.params.DEFAULT_AVG_PERTURBED_LIKELIHOOD,
+                "likelihood_ratio"            : self.params.DEFAULT_LIKELIHOOD_RATIO,
+                "normalized_likelihood_ratio" : self.params.DEFAULT_NORMALIZED_LIKELIHOOD_RATIO,
+                "stability_score"             : self.params.DEFAULT_STABILITY_SCORE, 
+                "curvature_score"             : self.params.DEFAULT_CURVATURE_SCORE,
+                "perturbation_variance"       : self.params.DEFAULT_PERTURBATION_VARIANCE,
+                "avg_chunk_stability"         : self.params.DEFAULT_AVG_CHUNK_STABILITY,
+                "stability_variance"          : self.params.DEFAULT_STABILITY_VARIANCE,
                 "num_perturbations"           : 0,
                 "num_valid_perturbations"     : 0,
                 "num_chunks_analyzed"         : 0,
@@ -955,8 +931,8 @@ class MultiPerturbationStabilityMetric(BaseMetric):
         text = ' '.join(text.split())
         
         # Truncate very long texts
-        if len(text) > 2000:
-            text = text[:2000] + "..."
+        if len(text) > self.params.MAX_TEXT_LENGTH_FOR_ANALYSIS:
+            text = text[:self.params.MAX_TEXT_LENGTH_FOR_ANALYSIS] + "..."
         
         return text
     
@@ -976,14 +952,14 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             text += '.'
         
         # Truncate to safe length
-        if (len(text) > 1000):
+        if (len(text) > self.params.MAX_TEXT_LENGTH_FOR_PERTURBATION):
             sentences = text.split('. ')
             if (len(sentences) > 1):
                 # Keep first few sentences
                 text = '. '.join(sentences[:3]) + '.'
             
             else:
-                text = text[:1000]
+                text = text[:self.params.MAX_TEXT_LENGTH_FOR_PERTURBATION]
         
         return text
     
@@ -1032,7 +1008,7 @@ class MultiPerturbationStabilityMetric(BaseMetric):
             return False
         
         # Must have some actual content
-        if len(perturbed_text.strip()) < 5:
+        if len(perturbed_text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_PERTURBATION:
             return False
         
         return True

metrics/perplexity.py

@@ -7,10 +7,11 @@ from typing import Any
 from typing import Dict
 from typing import List
 from loguru import logger
-from config.threshold_config import Domain
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import BaseMetric
-from metrics.base_metric import MetricResult
 from models.model_manager import get_model_manager
+from config.constants import perplexity_metric_params
 from config.threshold_config import get_threshold_for_domain
 
 
@@ -19,7 +20,7 @@ class PerplexityMetric(BaseMetric):
     Text predictability analysis using GPT-2 for perplexity calculation
     
     Measures (Aligned with Documentation):
-    - Overall text perplexity (lower = more predictable = more AI-like)
+    - Overall text perplexity (lower = more predictable = more synthetic-like)
     - Perplexity distribution across text chunks
     - Sentence-level perplexity patterns
     - Cross-entropy analysis
@@ -31,6 +32,7 @@ class PerplexityMetric(BaseMetric):
 
         self.model     = None
         self.tokenizer = None
+        self.params    = perplexity_metric_params
     
 
     def initialize(self) -> bool:
@@ -42,7 +44,7 @@ class PerplexityMetric(BaseMetric):
             
             # Load GPT-2 model and tokenizer
             model_manager = get_model_manager()
-            model_result  = model_manager.load_model(model_name = "perplexity_gpt2")
+            model_result  = model_manager.load_model(model_name = "perplexity_reference_lm")
             
             if isinstance(model_result, tuple):
                 self.model, self.tokenizer = model_result
@@ -65,106 +67,101 @@ class PerplexityMetric(BaseMetric):
         Compute perplexity measures with FULL DOMAIN THRESHOLD INTEGRATION
         """
         try:
-            if not text or len(text.strip()) < 50:
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    error             = "Text too short for perplexity analysis",
+            if (not text or len(text.strip()) < self.params.MIN_TEXT_LENGTH_FOR_ANALYSIS):
+                return MetricResult(metric_name           = self.name,
+                                    synthetic_probability = self.params.NEUTRAL_PROBABILITY,
+                                    authentic_probability = self.params.NEUTRAL_PROBABILITY,
+                                    hybrid_probability    = self.params.MIN_PROBABILITY,
+                                    confidence            = self.params.MIN_CONFIDENCE,
+                                    error                 = "Text too short for perplexity analysis",
                                    )
             
             # Get domain-specific thresholds
-            domain                           = kwargs.get('domain', Domain.GENERAL)
-            domain_thresholds                = get_threshold_for_domain(domain)
-            perplexity_thresholds            = domain_thresholds.perplexity
+            domain                                       = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds                            = get_threshold_for_domain(domain)
+            perplexity_thresholds                        = domain_thresholds.perplexity
             
             # Calculate comprehensive perplexity features
-            features                         = self._calculate_perplexity_features(text)
+            features                                     = self._calculate_perplexity_features(text = text)
             
             # Calculate raw perplexity score (0-1 scale)
-            raw_perplexity_score, confidence = self._analyze_perplexity_patterns(features)
+            raw_perplexity_score, confidence             = self._analyze_perplexity_patterns(features = features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob  = self._apply_domain_thresholds(raw_perplexity_score, perplexity_thresholds, features)
-            
+            synthetic_prob, authentic_prob, hybrid_prob  = self._apply_domain_thresholds(raw_score  = raw_perplexity_score, 
+                                                                                         thresholds = perplexity_thresholds, 
+                                                                                         features   = features,
+                                                                                        )
+                                                                                        
             # Apply confidence multiplier from domain thresholds
-            confidence                      *= perplexity_thresholds.confidence_multiplier
-            confidence                       = max(0.0, min(1.0, confidence))
+            confidence                                  *= perplexity_thresholds.confidence_multiplier
+            confidence                                   = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, confidence))
             
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : perplexity_thresholds.ai_threshold,
-                                                     'human_threshold' : perplexity_thresholds.human_threshold,
-                                                     'raw_score'       : raw_perplexity_score,
-                                                    },
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'        : domain.value,
+                                                         'synthetic_threshold': perplexity_thresholds.synthetic_threshold,
+                                                         'authentic_threshold': perplexity_thresholds.authentic_threshold,
+                                                         'raw_score'          : raw_perplexity_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in perplexity computation: {repr(e)}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold      # e.g., 0.60 for GENERAL, 0.55 for ACADEMIC
-        human_threshold = thresholds.human_threshold   # e.g., 0.40 for GENERAL, 0.35 for ACADEMIC
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
         
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-        
+        if (raw_score >= synthetic_threshold):
+            distance       = raw_score - synthetic_threshold
+            synthetic_prob = self.params.STRONG_SYNTHETIC_BASE_PROB + distance * self.params.WEAK_PROBABILITY_ADJUSTMENT
+            authentic_prob = (self.params.MAX_PROBABILITY - self.params.STRONG_SYNTHETIC_BASE_PROB) - distance * self.params.WEAK_PROBABILITY_ADJUSTMENT
+
+        elif (raw_score <= authentic_threshold):
+            distance       = authentic_threshold - raw_score
+            synthetic_prob = (self.params.MAX_PROBABILITY - self.params.STRONG_AUTHENTIC_BASE_PROB) - distance * self.params.WEAK_PROBABILITY_ADJUSTMENT
+            authentic_prob = self.params.STRONG_AUTHENTIC_BASE_PROB + distance * self.params.WEAK_PROBABILITY_ADJUSTMENT
+            
         else:
             # Between thresholds - uncertain zone
-            range_width = ai_threshold - human_threshold
+            range_width = synthetic_threshold - authentic_threshold
 
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            if (range_width > self.params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = self.params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = self.params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * self.params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob = 0.5
-                human_prob = 0.5
+                synthetic_prob = self.params.NEUTRAL_PROBABILITY
+                authentic_prob = self.params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(self.params.MIN_PROBABILITY, min(self.params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on perplexity variance
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on perplexity variance
+        hybrid_prob = self._calculate_hybrid_probability(features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
+        total       = synthetic_prob + authentic_prob + hybrid_prob
 
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        if (total > self.params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
     
 
     def _calculate_perplexity_features(self, text: str) -> Dict[str, Any]:
@@ -186,10 +183,10 @@ class PerplexityMetric(BaseMetric):
         
         for sentence in sentences:
             # Minimum sentence length
-            if (len(sentence.strip()) > 20):  
+            if (len(sentence.strip()) > self.params.MIN_SENTENCE_LENGTH):  
                 sent_perplexity = self._calculate_perplexity(sentence)
                 
-                if (sent_perplexity > 0):
+                if (sent_perplexity > self.params.ZERO_TOLERANCE):
                     sentence_perplexities.append(sent_perplexity)
                     valid_sentences += 1
         
@@ -207,7 +204,7 @@ class PerplexityMetric(BaseMetric):
             max_sentence_perplexity = overall_perplexity
         
         # Chunk-based analysis for whole-text understanding
-        chunk_perplexities    = self._calculate_chunk_perplexity(text, chunk_size = 200)
+        chunk_perplexities    = self._calculate_chunk_perplexity(text)
         perplexity_variance   = np.var(chunk_perplexities) if chunk_perplexities else 0.0
         avg_chunk_perplexity  = np.mean(chunk_perplexities) if chunk_perplexities else overall_perplexity
         
@@ -233,24 +230,24 @@ class PerplexityMetric(BaseMetric):
 
     def _calculate_perplexity(self, text: str) -> float:
         """
-        Calculate perplexity for given text using GPT-2 : Lower perplexity = more predictable = more AI-like
+        Calculate perplexity for given text using GPT-2 : Lower perplexity = more predictable = more synthetic-like
         """
         try:
             # Check text length before tokenization
-            if (len(text.strip()) < 10):
+            if (len(text.strip()) < self.params.MIN_SENTENCE_LENGTH // 2):
                 return 0.0
 
             # Tokenize the text
             encodings = self.tokenizer(text, 
                                        return_tensors = 'pt', 
                                        truncation     = True, 
-                                       max_length     = 1024,
+                                       max_length     = self.params.MAX_TOKEN_LENGTH,
                                       )
 
             input_ids = encodings.input_ids
             
             # Minimum tokens
-            if ((input_ids.numel() == 0) or (input_ids.size(1) < 5)):
+            if ((input_ids.numel() == 0) or (input_ids.size(1) < self.params.MIN_TOKENS_FOR_PERPLEXITY)):
                 return 0.0
             
             # Calculate loss (cross-entropy)
@@ -272,44 +269,49 @@ class PerplexityMetric(BaseMetric):
         """
         Split text into sentences
         """
-        sentences = re.split(r'[.!?]+', text)
-        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > 10]
+        sentences = re.split(self.params.SENTENCE_SPLIT_PATTERN, text)
+        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > self.params.MIN_SENTENCE_LENGTH // 2]
     
 
-    def _calculate_chunk_perplexity(self, text: str, chunk_size: int = 200) -> List[float]:
+    def _calculate_chunk_perplexity(self, text: str) -> List[float]:
         """
         Calculate perplexity across text chunks for whole-text analysis
         """
         chunks = list()
         words  = text.split()
+        chunk_size = self.params.CHUNK_SIZE_WORDS
+        overlap = int(chunk_size * self.params.CHUNK_OVERLAP_RATIO)
 
         # Ensure we have enough words for meaningful chunks
         if (len(words) < chunk_size // 2):
             return [self._calculate_perplexity(text)] if text.strip() else []
         
         # Create overlapping chunks for better analysis
-        for i in range(0, len(words), chunk_size // 2):
+        step = max(1, chunk_size - overlap)
+
+        for i in range(0, len(words), step):
             chunk = ' '.join(words[i:i + chunk_size])
             
             # Minimum chunk size
-            if (len(chunk) > 50):  
+            if (len(chunk) > self.params.MIN_CHUNK_LENGTH):  
                 perplexity = self._calculate_perplexity(chunk)
 
                 # Reasonable range check
-                if ((perplexity > 0) and (perplexity < 1000)):
+                if ((perplexity > self.params.ZERO_TOLERANCE) and (perplexity < self.params.LARGE_PERPLEXITY_THRESHOLD)):
                     chunks.append(perplexity)
         
-        return chunks if chunks else [0.0]
+        # Zero perplexity is physically impossible and biases the score hence returning DEFAULT_OVERALL_PERPLEXITY
+        return chunks if chunks else [self.params.DEFAULT_OVERALL_PERPLEXITY]
     
 
     def _normalize_perplexity(self, perplexity: float) -> float:
         """
         Normalize perplexity using sigmoid transformation
 
-        Lower perplexity = higher normalized score = more AI-like
+        Lower perplexity = higher normalized score = more synthetic-like
         """
-        # Use exponential normalization : Typical ranges: AI = 10-40, Human = 20-100
-        normalized = 1.0 / (1.0 + np.exp((perplexity - 30) / 10))
+        # Use exponential normalization
+        normalized = 1.0 / (1.0 + np.exp((perplexity - self.params.PERPLEXITY_SIGMOID_CENTER) / self.params.PERPLEXITY_SIGMOID_SCALE))
         
         return normalized 
     
@@ -319,7 +321,10 @@ class PerplexityMetric(BaseMetric):
         Calculate cross-entropy as an alternative measure
         """
         try:
-            encodings = self.tokenizer(text, return_tensors='pt', truncation=True, max_length=1024)
+            encodings = self.tokenizer(text, 
+                                       return_tensors = 'pt', 
+                                       truncation     = True, 
+                                       max_length     = self.params.MAX_TOKEN_LENGTH)
             input_ids = encodings.input_ids
             
             if (input_ids.numel() == 0):
@@ -329,9 +334,9 @@ class PerplexityMetric(BaseMetric):
                 outputs = self.model(input_ids, labels = input_ids)
                 loss    = outputs.loss
             
-            # Normalize cross-entropy to 0-1 scale : Assuming max ~5 nats
+            # Normalize cross-entropy to 0-1 scale
             cross_entropy = loss.item()
-            normalized_ce = min(1.0, cross_entropy / 5.0) 
+            normalized_ce = min(1.0, cross_entropy / self.params.MAX_CROSS_ENTROPY) 
             
             return normalized_ce
             
@@ -342,130 +347,129 @@ class PerplexityMetric(BaseMetric):
 
     def _analyze_perplexity_patterns(self, features: Dict[str, Any]) -> tuple:
         """
-        Analyze perplexity patterns to determine RAW perplexity score (0-1 scale) : Higher score = more AI-like
+        Analyze perplexity patterns to determine RAW perplexity score (0-1 scale) : Higher score = more synthetic-like
         """
         # Check feature validity first
         required_features = ['normalized_perplexity', 'perplexity_variance', 'std_sentence_perplexity', 'cross_entropy_score']
     
-        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > 0]
+        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > self.params.ZERO_TOLERANCE]
     
-        if (len(valid_features) < 3):
+        if (len(valid_features) < self.params.MIN_REQUIRED_FEATURES):
             # Low confidence if insufficient features
-            return 0.5, 0.3  
+            return self.params.NEUTRAL_PROBABILITY, self.params.LOW_FEATURE_CONFIDENCE
 
 
-        # Initialize ai_indicator list
-        ai_indicators = list()
+        # Initialize synthetic_indicator list
+        synthetic_indicators = list()
         
-        # Low overall perplexity suggests AI
-        if (features['normalized_perplexity'] > 0.7):
-            # Very AI-like
-            ai_indicators.append(0.8)  
+        # Low overall perplexity suggests synthetic
+        if (features['normalized_perplexity'] > self.params.NORMALIZED_PERPLEXITY_HIGH_THRESHOLD):
+            # Very synthetic-like
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)  
 
-        elif (features['normalized_perplexity'] > 0.5):
-            # AI-like
-            ai_indicators.append(0.6)  
+        elif (features['normalized_perplexity'] > self.params.NORMALIZED_PERPLEXITY_MEDIUM_THRESHOLD):
+            # synthetic-like
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)  
 
         else:
-            # Human-like
-            ai_indicators.append(0.2) 
+            # authentic-like
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT) 
         
-        # Low perplexity variance suggests AI (consistent predictability)
-        if (features['perplexity_variance'] < 50):
-            ai_indicators.append(0.7)
+        # Low perplexity variance suggests synthetic (consistent predictability)
+        if (features['perplexity_variance'] < self.params.PERPLEXITY_VARIANCE_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
-        elif (features['perplexity_variance'] < 200):
-            ai_indicators.append(0.4)
+        elif (features['perplexity_variance'] < self.params.PERPLEXITY_VARIANCE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # Low sentence perplexity std suggests AI (consistent across sentences)
-        if (features['std_sentence_perplexity'] < 20):
-            ai_indicators.append(0.8)
+        # Low sentence perplexity std suggests synthetic (consistent across sentences)
+        if (features['std_sentence_perplexity'] < self.params.STD_SENTENCE_PERPLEXITY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)
 
-        elif (features['std_sentence_perplexity'] < 50):
-            ai_indicators.append(0.5)
+        elif (features['std_sentence_perplexity'] < self.params.STD_SENTENCE_PERPLEXITY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
         
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # Low cross-entropy suggests AI (more predictable)
-        if (features['cross_entropy_score'] < 0.3):
-            ai_indicators.append(0.7)
+        # Low cross-entropy suggests synthetic (more predictable)
+        if (features['cross_entropy_score'] < self.params.CROSS_ENTROPY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
         
-        elif (features['cross_entropy_score'] < 0.6):
-            ai_indicators.append(0.4)
+        elif (features['cross_entropy_score'] < self.params.CROSS_ENTROPY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(self.params.WEAK_SYNTHETIC_WEIGHT)
         
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(self.params.MINIMAL_SYNTHETIC_WEIGHT)
         
-        # Consistent chunk perplexity suggests AI
+        # Consistent chunk perplexity suggests synthetic
         chunk_variance = features['perplexity_variance']
         
-        if (chunk_variance < 25):
-            ai_indicators.append(0.9)
+        if (chunk_variance < self.params.CHUNK_VARIANCE_VERY_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.STRONG_SYNTHETIC_WEIGHT)
 
-        elif (chunk_variance < 100):
-            ai_indicators.append(0.6)
+        elif (chunk_variance < self.params.CHUNK_VARIANCE_LOW_THRESHOLD):
+            synthetic_indicators.append(self.params.MEDIUM_SYNTHETIC_WEIGHT)
 
         else:
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(self.params.VERY_WEAK_SYNTHETIC_WEIGHT)
         
         # Calculate raw score and confidence
-        raw_score  = np.mean(ai_indicators) if ai_indicators else 0.5
-        confidence = 1.0 - (np.std(ai_indicators) / 0.5) if ai_indicators else 0.5
-        confidence = max(0.1, min(0.9, confidence))
-        
+        raw_score  = np.mean(synthetic_indicators) if synthetic_indicators else self.params.NEUTRAL_PROBABILITY
+        confidence = max(self.params.MIN_CONFIDENCE, min(self.params.MAX_CONFIDENCE, 1.0 - (np.std(synthetic_indicators) / self.params.CONFIDENCE_STD_NORMALIZER)))
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content
+        Calculate probability of hybrid synthetic/authentic content
         """
-        mixed_indicators = list()
+        hybrid_indicators = list()
         
         # Moderate perplexity values might indicate mixing
-        if (0.4 <= features['normalized_perplexity'] <= 0.6):
-            mixed_indicators.append(0.3)
+        if (self.params.NORMALIZED_PERPLEXITY_MIXED_MIN <= features['normalized_perplexity'] <= self.params.NORMALIZED_PERPLEXITY_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # High perplexity variance suggests mixed content
-        if (features['perplexity_variance'] > 200):
-            mixed_indicators.append(0.4)
+        if (features['perplexity_variance'] > self.params.PERPLEXITY_VARIANCE_HIGH_THRESHOLD):
+            hybrid_indicators.append(self.params.MODERATE_HYBRID_WEIGHT)
 
-        elif (features['perplexity_variance'] > 100):
-            mixed_indicators.append(0.2)
+        elif (features['perplexity_variance'] > self.params.PERPLEXITY_VARIANCE_MEDIUM_THRESHOLD):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
         # Inconsistent sentence perplexities
-        if (20 <= features['std_sentence_perplexity'] <= 60):
-            mixed_indicators.append(0.3)
+        if (self.params.STD_SENTENCE_PERPLEXITY_MIXED_MIN <= features['std_sentence_perplexity'] <= self.params.STD_SENTENCE_PERPLEXITY_MIXED_MAX):
+            hybrid_indicators.append(self.params.WEAK_HYBRID_WEIGHT)
 
         else:
-            mixed_indicators.append(0.0)
+            hybrid_indicators.append(self.params.MINIMAL_HYBRID_WEIGHT)
         
-        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        hybrid_prob = np.mean(hybrid_indicators) if hybrid_indicators else 0.0
+        return min(self.params.MAX_HYBRID_PROBABILITY, hybrid_prob)
     
 
     def _get_default_features(self) -> Dict[str, Any]:
         """
         Return default features when analysis is not possible
         """
-        return {"overall_perplexity"      : 50.0,
-                "normalized_perplexity"   : 0.5,
-                "avg_sentence_perplexity" : 50.0,
-                "std_sentence_perplexity" : 25.0,
-                "min_sentence_perplexity" : 30.0,
-                "max_sentence_perplexity" : 70.0,
-                "perplexity_variance"     : 100.0,
-                "avg_chunk_perplexity"    : 50.0,
-                "cross_entropy_score"     : 0.5,
+        return {"overall_perplexity"      : self.params.DEFAULT_OVERALL_PERPLEXITY,
+                "normalized_perplexity"   : self.params.DEFAULT_NORMALIZED_PERPLEXITY,
+                "avg_sentence_perplexity" : self.params.DEFAULT_AVG_SENTENCE_PERPLEXITY,
+                "std_sentence_perplexity" : self.params.DEFAULT_STD_SENTENCE_PERPLEXITY,
+                "min_sentence_perplexity" : self.params.DEFAULT_MIN_SENTENCE_PERPLEXITY,
+                "max_sentence_perplexity" : self.params.DEFAULT_MAX_SENTENCE_PERPLEXITY,
+                "perplexity_variance"     : self.params.DEFAULT_PERPLEXITY_VARIANCE,
+                "avg_chunk_perplexity"    : self.params.DEFAULT_AVG_CHUNK_PERPLEXITY,
+                "cross_entropy_score"     : self.params.DEFAULT_CROSS_ENTROPY_SCORE,
                 "num_sentences_analyzed"  : 0,
                 "num_chunks_analyzed"     : 0,
                }
@@ -482,4 +486,4 @@ class PerplexityMetric(BaseMetric):
 
 
 # Export
-__all__ = ["PerplexityMetric"]
+__all__ = ["PerplexityMetric"]

metrics/semantic_analysis.py

@@ -6,10 +6,11 @@ from typing import Dict
 from typing import List
 from loguru import logger
 from collections import Counter
-from config.threshold_config import Domain
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import BaseMetric
-from metrics.base_metric import MetricResult
 from models.model_manager import get_model_manager
+from config.constants import semantic_analysis_params
 from sklearn.metrics.pairwise import cosine_similarity
 from config.threshold_config import get_threshold_for_domain
 
@@ -59,118 +60,116 @@ class SemanticAnalysisMetric(BaseMetric):
         Compute semantic analysis measures with FULL DOMAIN THRESHOLD INTEGRATION
         """
         try:
-            if (not text or (len(text.strip()) < 50)):
-                return MetricResult(metric_name       = self.name,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    error             = "Text too short for semantic analysis",
-                                   )
+            params = semantic_analysis_params
+            
+            if (not text or (len(text.strip()) < params.MIN_TEXT_LENGTH_FOR_ANALYSIS)):
+                return self._default_result(error = "Text too short for semantic analysis")
             
             # Get domain-specific thresholds
-            domain                          = kwargs.get('domain', Domain.GENERAL)
-            domain_thresholds               = get_threshold_for_domain(domain)
-            semantic_thresholds             = domain_thresholds.semantic_analysis
+            domain                                      = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds                           = get_threshold_for_domain(domain)
+            semantic_thresholds                         = domain_thresholds.semantic
             
             # Calculate comprehensive semantic features
-            features                        = self._calculate_semantic_features(text)
+            features                                    = self._calculate_semantic_features(text)
             
             # Calculate raw semantic score (0-1 scale)
-            raw_semantic_score, confidence  = self._analyze_semantic_patterns(features)
+            raw_semantic_score, confidence              = self._analyze_semantic_patterns(features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob = self._apply_domain_thresholds(raw_semantic_score, semantic_thresholds, features)
+            synthetic_prob, authentic_prob, hybrid_prob = self._apply_domain_thresholds(raw_score  = raw_semantic_score, 
+                                                                                        thresholds = semantic_thresholds, 
+                                                                                        features   = features,
+                                                                                       )
             
             # Apply confidence multiplier from domain thresholds
-            confidence                     *= semantic_thresholds.confidence_multiplier
-            confidence                      = max(0.0, min(1.0, confidence))
+            confidence                                 *= semantic_thresholds.confidence_multiplier
+            confidence                                  = max(params.MIN_CONFIDENCE, min(params.MAX_CONFIDENCE, confidence))
             
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : semantic_thresholds.ai_threshold,
-                                                     'human_threshold' : semantic_thresholds.human_threshold,
-                                                     'raw_score'       : raw_semantic_score,
-                                                    },
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'          : domain.value,
+                                                         'synthetic_threshold'  : semantic_thresholds.synthetic_threshold,
+                                                         'authentic_threshold'  : semantic_thresholds.authentic_threshold,
+                                                         'raw_score'            : raw_semantic_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in semantic analysis computation: {repr(e)}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold    # e.g., 0.65 for GENERAL, 0.70 for ACADEMIC
-        human_threshold = thresholds.human_threshold # e.g., 0.35 for GENERAL, 0.30 for ACADEMIC
+        params              = semantic_analysis_params
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
         
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
+        if (raw_score >= synthetic_threshold):
+            # Above synthetic threshold - strongly synthetic
+            distance_from_threshold = raw_score - synthetic_threshold
+            synthetic_prob          = params.STRONG_SYNTHETIC_BASE_PROB + (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = (params.MAX_PROBABILITY - params.STRONG_SYNTHETIC_BASE_PROB) - (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+
+        elif (raw_score <= authentic_threshold):
+            # Below authentic threshold - strongly authentic
+            distance_from_threshold = authentic_threshold - raw_score
+            synthetic_prob          = (params.MAX_PROBABILITY - params.STRONG_AUTHENTIC_BASE_PROB) - (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = params.STRONG_AUTHENTIC_BASE_PROB + (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+        
         else:
             # Between thresholds - uncertain zone
-            range_width = ai_threshold - human_threshold
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            range_width = synthetic_threshold - authentic_threshold
+            
+            if (range_width > params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob    = 0.5
-                human_prob = 0.5
+                synthetic_prob = params.NEUTRAL_PROBABILITY
+                authentic_prob = params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(params.MIN_PROBABILITY, min(params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(params.MIN_PROBABILITY, min(params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on semantic variance
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on semantic variance
+        hybrid_prob    = self._calculate_hybrid_probability(features = features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
+        total          = synthetic_prob + authentic_prob + hybrid_prob
         
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        if (total > params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
     
 
     def _calculate_semantic_features(self, text: str) -> Dict[str, Any]:
         """
         Calculate comprehensive semantic analysis features
         """
+        params    = semantic_analysis_params
+        
         # Split text into sentences
         sentences = self._split_sentences(text)
         
-        if (len(sentences) < 3):
+        if (len(sentences) < params.MIN_SENTENCES_FOR_ANALYSIS):
             return self._get_default_features()
         
         # Calculate semantic embeddings for all sentences
-        sentence_embeddings = self._get_sentence_embeddings(sentences)
+        sentence_embeddings, valid_sentences = self._get_sentence_embeddings(sentences = sentences)
         
         if sentence_embeddings is None:
             return self._get_default_features()
@@ -179,23 +178,28 @@ class SemanticAnalysisMetric(BaseMetric):
         similarity_matrix      = cosine_similarity(sentence_embeddings)
         
         # Calculate various semantic metrics
-        coherence_score        = self._calculate_coherence(similarity_matrix)
-        consistency_score      = self._calculate_consistency(similarity_matrix)
-        repetition_score       = self._detect_repetition_patterns(sentences, similarity_matrix)
-        topic_drift_score      = self._calculate_topic_drift(similarity_matrix)
-        contextual_consistency = self._calculate_contextual_consistency(sentences)
+        coherence_score        = self._calculate_coherence(similarity_matrix = similarity_matrix)
+        consistency_score      = self._calculate_consistency(similarity_matrix = similarity_matrix)
+        repetition_score       = self._detect_repetition_patterns(sentences         = valid_sentences, 
+                                                                  similarity_matrix = similarity_matrix,
+                                                                 )
+
+        topic_drift_score      = self._calculate_topic_drift(similarity_matrix = similarity_matrix)
+        contextual_consistency = self._calculate_contextual_consistency(sentences = sentences)
         
         # Chunk-based analysis for whole-text understanding
-        chunk_coherence        = self._calculate_chunk_coherence(text, chunk_size=200)
+        chunk_coherence        = self._calculate_chunk_coherence(text       = text, 
+                                                                 chunk_size = params.CHUNK_SIZE_WORDS,
+                                                                )
         
         return {"coherence_score"        : round(coherence_score, 4),
                 "consistency_score"      : round(consistency_score, 4),
                 "repetition_score"       : round(repetition_score, 4),
                 "topic_drift_score"      : round(topic_drift_score, 4),
                 "contextual_consistency" : round(contextual_consistency, 4),
-                "avg_chunk_coherence"    : round(np.mean(chunk_coherence) if chunk_coherence else 0.0, 4),
-                "coherence_variance"     : round(np.var(chunk_coherence) if chunk_coherence else 0.0, 4),
-                "num_sentences"          : len(sentences),
+                "avg_chunk_coherence"    : round(np.mean(chunk_coherence) if chunk_coherence else params.DEFAULT_COHERENCE, 4),
+                "coherence_variance"     : round(np.var(chunk_coherence) if chunk_coherence else params.DEFAULT_COHERENCE_VARIANCE, 4),
+                "num_sentences"          : len(valid_sentences),
                 "num_chunks_analyzed"    : len(chunk_coherence),
                }
     
@@ -204,8 +208,8 @@ class SemanticAnalysisMetric(BaseMetric):
         """
         Split text into sentences
         """
-        sentences = re.split(r'(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?|\!)\s', text)
-        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > 10]
+        sentences = re.split(semantic_analysis_params.SENTENCE_SPLIT_PATTERN, text)
+        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > semantic_analysis_params.MIN_SENTENCE_LENGTH]
     
 
     def _get_sentence_embeddings(self, sentences: List[str]) -> np.ndarray:
@@ -217,30 +221,32 @@ class SemanticAnalysisMetric(BaseMetric):
                 return None
             
             # Filter out very short sentences that might cause issues
-            valid_sentences = [s for s in sentences if len(s.strip()) > 5]
+            valid_sentences = [s for s in sentences if len(s.strip()) > semantic_analysis_params.MIN_VALID_SENTENCE_LENGTH]
             if not valid_sentences:
-                return None
+                return None, None
             
             # Encode sentences to get embeddings
             embeddings = self.sentence_model.encode(valid_sentences)
             
             # Check if embeddings are valid
             if ((embeddings is None) or (len(embeddings) == 0)):
-                return None
+                return None, None
                 
-            return embeddings
+            return embeddings, valid_sentences
             
         except Exception as e:
             logger.warning(f"Sentence embedding failed: {repr(e)}")
-            return None
+            return None, None
     
 
     def _calculate_coherence(self, similarity_matrix: np.ndarray) -> float:
         """
         Calculate overall text coherence : Higher coherence = more logically connected sentences
         """
-        if similarity_matrix.size == 0:
-            return 0.0
+        params = semantic_analysis_params
+        
+        if (similarity_matrix.size == 0):
+            return params.MIN_PROBABILITY
         
         # Calculate average similarity between adjacent sentences
         adjacent_similarities = list()
@@ -249,7 +255,7 @@ class SemanticAnalysisMetric(BaseMetric):
             adjacent_similarities.append(similarity_matrix[i, i + 1])
         
         if (not adjacent_similarities):
-            return 0.0
+            return params.MIN_PROBABILITY
         
         return np.mean(adjacent_similarities)
     
@@ -258,27 +264,31 @@ class SemanticAnalysisMetric(BaseMetric):
         """
         Calculate topic consistency throughout the text : Lower variance in similarities = more consistent
         """
+        params = semantic_analysis_params
+        
         if (similarity_matrix.size == 0):
-            return 0.0
+            return params.MIN_PROBABILITY
         
         # Calculate variance of similarities (lower variance = more consistent)
         all_similarities = similarity_matrix[np.triu_indices_from(similarity_matrix, k=1)]
         if (len(all_similarities) == 0):
-            return 0.0
+            return params.MIN_PROBABILITY
         
         variance    = np.var(all_similarities)
         # Convert to consistency score (higher = more consistent)
-        consistency = 1.0 - min(1.0, variance * 5.0)  # Normalize
+        consistency = params.MAX_PROBABILITY - min(params.MAX_PROBABILITY, variance * params.SIMILARITY_VARIANCE_FACTOR)
 
-        return max(0.0, consistency)
+        return max(params.MIN_PROBABILITY, consistency)
     
 
     def _detect_repetition_patterns(self, sentences: List[str], similarity_matrix: np.ndarray) -> float:
         """
         Detect repetition patterns in semantic content : AI text sometimes shows more semantic repetition
         """
-        if (len(sentences) < 5):
-            return 0.0
+        params = semantic_analysis_params
+        
+        if (len(sentences) < params.MIN_SENTENCES_FOR_REPETITION):
+            return params.MIN_PROBABILITY
         
         # Look for high similarity between non-adjacent sentences
         repetition_count  = 0
@@ -287,30 +297,32 @@ class SemanticAnalysisMetric(BaseMetric):
         for i in range(len(sentences)):
             for j in range(i + 2, len(sentences)):  # Skip adjacent sentences
                 # High semantic similarity
-                if (similarity_matrix[i, j] > 0.8):  
+                if (similarity_matrix[i, j] > params.REPETITION_SIMILARITY_THRESHOLD):  
                     repetition_count += 1
                 
                 total_comparisons += 1
         
         if (total_comparisons == 0):
-            return 0.0
+            return params.MIN_PROBABILITY
         
         repetition_score = repetition_count / total_comparisons
         
         # Scale to make differences more noticeable
-        return min(1.0, repetition_score * 3.0)  
+        return min(params.MAX_PROBABILITY, repetition_score * params.REPETITION_SCORE_SCALING)
     
 
     def _calculate_topic_drift(self, similarity_matrix: np.ndarray) -> float:
         """
         Calculate topic drift throughout the text : Higher drift = less focused content
         """
+        params = semantic_analysis_params
+        
         if (len(similarity_matrix) < 3):
-            return 0.0
+            return params.MIN_PROBABILITY
         
         # Calculate similarity between beginning and end sections
-        start_size         = min(3, len(similarity_matrix) // 3)
-        end_size           = min(3, len(similarity_matrix) // 3)
+        start_size         = min(params.START_SECTION_SIZE, len(similarity_matrix) // params.SECTION_SIZE_RATIO)
+        end_size           = min(params.END_SECTION_SIZE, len(similarity_matrix) // params.SECTION_SIZE_RATIO)
         
         start_indices      = list(range(start_size))
         end_indices        = list(range(len(similarity_matrix) - end_size, len(similarity_matrix)))
@@ -322,38 +334,40 @@ class SemanticAnalysisMetric(BaseMetric):
                 cross_similarities.append(similarity_matrix[i, j])
         
         if not cross_similarities:
-            return 0.0
+            return params.MIN_PROBABILITY
         
         avg_cross_similarity = np.mean(cross_similarities)
         # Lower similarity between start and end = higher topic drift
-        topic_drift          = 1.0 - avg_cross_similarity
+        topic_drift          = params.MAX_PROBABILITY - avg_cross_similarity
 
-        return max(0.0, topic_drift)
+        return max(params.MIN_PROBABILITY, topic_drift)
     
 
     def _calculate_contextual_consistency(self, sentences: List[str]) -> float:
         """
         Calculate contextual consistency using keyword and entity analysis
         """
-        if (len(sentences) < 3):
-            return 0.0
+        params = semantic_analysis_params
+        
+        if (len(sentences) < params.MIN_SENTENCES_FOR_ANALYSIS):
+            return params.MIN_PROBABILITY
         
         # Simple keyword consistency analysis : Extract meaningful words (nouns, adjectives)
         all_words = list()
 
         for sentence in sentences:
-            words = re.findall(r'\b[a-zA-Z]{4,}\b', sentence.lower())
+            words = re.findall(params.WORD_EXTRACTION_PATTERN, sentence.lower())
             all_words.extend(words)
         
-        if (len(all_words) < 10):
-            return 0.0
+        if (len(all_words) < params.MIN_WORDS_FOR_KEYWORD_ANALYSIS):
+            return params.MIN_PROBABILITY
         
         # Calculate how consistently keywords are used across sentences
         word_freq    = Counter(all_words)
-        top_keywords = [word for word, count in word_freq.most_common(10) if count > 1]
+        top_keywords = [word for word, count in word_freq.most_common(params.TOP_KEYWORDS_COUNT) if count > params.MIN_KEYWORD_FREQUENCY]
         
         if not top_keywords:
-            return 0.0
+            return params.MIN_PROBABILITY
         
         # Check if top keywords appear consistently across sentences
         keyword_presence = list()
@@ -372,150 +386,166 @@ class SemanticAnalysisMetric(BaseMetric):
         """
         Calculate coherence across text chunks for whole-text analysis
         """
+        params = semantic_analysis_params
         chunks = list()
         words  = text.split()
         
         # Create overlapping chunks
-        for i in range(0, len(words), chunk_size // 2):
+        overlap = int(chunk_size * params.CHUNK_OVERLAP_RATIO)
+        
+        for i in range(0, len(words), overlap):
             chunk = ' '.join(words[i:i + chunk_size])
             
             # Minimum chunk size
-            if (len(chunk) > 50):  
+            if (len(chunk) > params.MIN_CHUNK_LENGTH):  
                 chunk_sentences = self._split_sentences(chunk)
                 
-                if (len(chunk_sentences) >= 2):
-                    embeddings = self._get_sentence_embeddings(chunk_sentences)
+                if (len(chunk_sentences) >= params.MIN_SENTENCES_PER_CHUNK):
+                    sentence_embeddings, valid_sentences = self._get_sentence_embeddings(sentences = chunk_sentences)
                     
-                    if ((embeddings is not None) and (len(embeddings) >= 2)):
-                        similarity_matrix = cosine_similarity(embeddings)
+                    if ((sentence_embeddings is not None) and (len(sentence_embeddings) >= params.MIN_SENTENCES_PER_CHUNK)):
+                        similarity_matrix = cosine_similarity(sentence_embeddings)
                         coherence         = self._calculate_coherence(similarity_matrix)
                         chunks.append(coherence)
         
-        return chunks if chunks else [0.0]
+        return chunks if chunks else [params.DEFAULT_COHERENCE]
     
 
     def _analyze_semantic_patterns(self, features: Dict[str, Any]) -> tuple:
         """
         Analyze semantic patterns to determine RAW semantic score (0-1 scale)
         """
+        params = semantic_analysis_params
+        
         # Check feature validity first
         required_features = ['coherence_score', 'consistency_score', 'repetition_score', 'topic_drift_score', 'coherence_variance']
     
-        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > 0]
+        valid_features    = [features.get(feat, params.MIN_PROBABILITY) for feat in required_features if features.get(feat, params.MIN_PROBABILITY) > params.ZERO_TOLERANCE]
     
-        if (len(valid_features) < 3):
+        if (len(valid_features) < params.MIN_REQUIRED_FEATURES):
             # Low confidence if insufficient features
-            return 0.5, 0.3  
-    
+            return params.NEUTRAL_PROBABILITY, params.LOW_FEATURE_CONFIDENCE
         
-        # Initialize ai_indicator list
-        ai_indicators = list()
+        # Initialize synthetic indicator list
+        synthetic_indicators = list()
 
         # AI text often has very high coherence (too perfect)
-        if (features['coherence_score'] > 0.7):
+        if (features['coherence_score'] > params.COHERENCE_HIGH_THRESHOLD):
             # Suspiciously high coherence
-            ai_indicators.append(0.8)  
-
-        elif (features['coherence_score'] > 0.5):
+            synthetic_indicators.append(params.STRONG_SYNTHETIC_WEIGHT)
+       
+        elif (features['coherence_score'] > params.COHERENCE_MEDIUM_THRESHOLD):
             # Moderate coherence
-            ai_indicators.append(0.5)
-
+            synthetic_indicators.append(params.MEDIUM_SYNTHETIC_WEIGHT)
+       
         else:
             # Low coherence - more human-like
-            ai_indicators.append(0.2)  
+            synthetic_indicators.append(params.LOW_SYNTHETIC_WEIGHT)
         
         # Very high consistency suggests AI (unnaturally consistent)
-        if (features['consistency_score'] > 0.8):
-            ai_indicators.append(0.9)
-
-        elif (features['consistency_score'] > 0.6):
-            ai_indicators.append(0.6)
-
+        if (features['consistency_score'] > params.CONSISTENCY_HIGH_THRESHOLD):
+            synthetic_indicators.append(params.STRONG_SYNTHETIC_WEIGHT)
+        
+        elif (features['consistency_score'] > params.CONSISTENCY_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
         else:
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(params.VERY_LOW_SYNTHETIC_WEIGHT)
         
         # High repetition suggests AI
-        if (features['repetition_score'] > 0.3):
-            ai_indicators.append(0.7)
-
-        elif (features['repetition_score'] > 0.1):
-            ai_indicators.append(0.4)
-
+        if (features['repetition_score'] > params.REPETITION_HIGH_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
+        elif (features['repetition_score'] > params.REPETITION_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.VERY_WEAK_SYNTHETIC_WEIGHT)
+        
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(params.LOW_SYNTHETIC_WEIGHT)
         
         # Very low topic drift suggests AI (stays too focused)
-        if (features['topic_drift_score'] < 0.2):
-            ai_indicators.append(0.8)
-
-        elif (features['topic_drift_score'] < 0.4):
-            ai_indicators.append(0.5)
-
+        if (features['topic_drift_score'] < params.TOPIC_DRIFT_LOW_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
+        elif (features['topic_drift_score'] < params.TOPIC_DRIFT_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.WEAK_SYNTHETIC_WEIGHT)
+        
         else:
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(params.VERY_LOW_SYNTHETIC_WEIGHT)
         
         # Low coherence variance across chunks suggests AI
-        if (features['coherence_variance'] < 0.05):
-            ai_indicators.append(0.7)
-
-        elif (features['coherence_variance'] < 0.1):
-            ai_indicators.append(0.4)
-
+        if (features['coherence_variance'] < params.COHERENCE_VARIANCE_LOW_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
+        elif (features['coherence_variance'] < params.COHERENCE_VARIANCE_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.VERY_WEAK_SYNTHETIC_WEIGHT)
+        
         else:
-            ai_indicators.append(0.2)
+            synthetic_indicators.append(params.LOW_SYNTHETIC_WEIGHT)
         
         # Calculate raw score and confidence
-        raw_score  = np.mean(ai_indicators) if ai_indicators else 0.5
-        confidence = 1.0 - (np.std(ai_indicators) / 0.5) if ai_indicators else 0.5
-        confidence = max(0.1, min(0.9, confidence))
+        if synthetic_indicators:
+            raw_score  = np.mean(synthetic_indicators)
+            confidence = params.MAX_PROBABILITY - (np.std(synthetic_indicators) / params.CONFIDENCE_STD_NORMALIZER)
+            confidence = max(params.MIN_CONFIDENCE, min(params.MAX_CONFIDENCE, confidence))
+        
+        else:
+            raw_score  = params.NEUTRAL_PROBABILITY
+            confidence = params.NEUTRAL_CONFIDENCE
         
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content
+        Calculate probability of hybrid synthetic/authentic content
         """
         mixed_indicators = list()
+        params           = semantic_analysis_params
         
         # Moderate coherence values might indicate mixing
-        if (0.4 <= features['coherence_score'] <= 0.6):
-            mixed_indicators.append(0.3)
-
+        if (params.COHERENCE_MIXED_MIN <= features['coherence_score'] <= params.COHERENCE_MIXED_MAX):
+            mixed_indicators.append(params.WEAK_HYBRID_WEIGHT)
+        
         else:
-            mixed_indicators.append(0.0)
+            mixed_indicators.append(params.MIN_PROBABILITY)
         
         # High coherence variance suggests mixed content
-        if (features['coherence_variance'] > 0.15):
-            mixed_indicators.append(0.4)
-
-        elif (features['coherence_variance'] > 0.1):
-            mixed_indicators.append(0.2)
-
+        if (features['coherence_variance'] > params.COHERENCE_VARIANCE_HIGH_THRESHOLD):
+            mixed_indicators.append(params.MODERATE_HYBRID_WEIGHT)
+        
+        elif (features['coherence_variance'] > params.COHERENCE_VARIANCE_MEDIUM_THRESHOLD):
+            mixed_indicators.append(params.WEAK_HYBRID_WEIGHT)
+        
         else:
-            mixed_indicators.append(0.0)
+            mixed_indicators.append(params.MIN_PROBABILITY)
         
         # Inconsistent repetition patterns
-        if (0.15 <= features['repetition_score'] <= 0.35):
-            mixed_indicators.append(0.3)
-
+        if (params.REPETITION_MIXED_MIN <= features['repetition_score'] <= params.REPETITION_MIXED_MAX):
+            mixed_indicators.append(params.WEAK_HYBRID_WEIGHT)
+        
         else:
-            mixed_indicators.append(0.0)
+            mixed_indicators.append(params.MIN_PROBABILITY)
         
-        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        if mixed_indicators:
+            hybrid_prob = np.mean(mixed_indicators)
+            return min(params.MAX_HYBRID_PROBABILITY, hybrid_prob)
+        
+        return params.MIN_PROBABILITY
     
 
     def _get_default_features(self) -> Dict[str, Any]:
         """
         Return default features when analysis is not possible
         """
-        return {"coherence_score"        : 0.5,
-                "consistency_score"      : 0.5,
-                "repetition_score"       : 0.0,
-                "topic_drift_score"      : 0.5,
-                "contextual_consistency" : 0.5,
-                "avg_chunk_coherence"    : 0.5,
-                "coherence_variance"     : 0.1,
+        params = semantic_analysis_params
+        
+        return {"coherence_score"        : params.DEFAULT_COHERENCE,
+                "consistency_score"      : params.DEFAULT_CONSISTENCY,
+                "repetition_score"       : params.DEFAULT_REPETITION,
+                "topic_drift_score"      : params.DEFAULT_TOPIC_DRIFT,
+                "contextual_consistency" : params.DEFAULT_CONTEXTUAL_CONSISTENCY,
+                "avg_chunk_coherence"    : params.DEFAULT_CHUNK_COHERENCE,
+                "coherence_variance"     : params.DEFAULT_COHERENCE_VARIANCE,
                 "num_sentences"          : 0,
                 "num_chunks_analyzed"    : 0,
                }
@@ -532,4 +562,4 @@ class SemanticAnalysisMetric(BaseMetric):
 
 
 # Export
-__all__ = ["SemanticAnalysisMetric"]
+__all__ = ["SemanticAnalysisMetric"]

metrics/structural.py

@@ -6,9 +6,10 @@ from typing import Dict
 from typing import List
 from loguru import logger
 from collections import Counter
-from metrics.base_metric import MetricResult
+from config.enums import Domain
+from config.schemas import MetricResult
 from metrics.base_metric import StatisticalMetric 
-from config.threshold_config import Domain
+from config.constants import structural_metric_params
 from config.threshold_config import get_threshold_for_domain
 
 
@@ -41,101 +42,98 @@ class StructuralMetric(StatisticalMetric):
             
         Returns:
         --------
-            { MetricResult } : MetricResult with AI/Human probabilities
+            { MetricResult } : MetricResult with synthetic/authentic probabilities
         """
         try:
             # Get domain-specific thresholds
-            domain                          = kwargs.get('domain', Domain.GENERAL)
-            domain_thresholds               = get_threshold_for_domain(domain)
-            structural_thresholds           = domain_thresholds.structural
+            domain                                      = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds                           = get_threshold_for_domain(domain)
+            structural_thresholds                       = domain_thresholds.structural
             
             # Extract all structural features
-            features                        = self._extract_features(text)
+            features                                    = self._extract_features(text = text)
             
-            # Calculate raw AI probability based on features
-            raw_ai_prob, confidence         = self._calculate_ai_probability(features)
+            # Calculate raw synthetic probability based on features
+            raw_synthetic_score, confidence             = self._calculate_synthetic_probability(features = features)
             
             # Apply domain-specific thresholds to convert raw score to probabilities
-            ai_prob, human_prob, mixed_prob = self._apply_domain_thresholds(raw_ai_prob, structural_thresholds, features)
+            synthetic_prob, authentic_prob, hybrid_prob = self._apply_domain_thresholds(raw_score  = raw_synthetic_score, 
+                                                                                        thresholds = structural_thresholds, 
+                                                                                        features   = features,
+                                                                                       )
             
             # Apply confidence multiplier from domain thresholds
-            confidence                     *= structural_thresholds.confidence_multiplier
-            confidence                      = max(0.0, min(1.0, confidence))
-            
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = ai_prob,
-                                human_probability = human_prob,
-                                mixed_probability = mixed_prob,
-                                confidence        = confidence,
-                                details           = {**features, 
-                                                     'domain_used'     : domain.value,
-                                                     'ai_threshold'    : structural_thresholds.ai_threshold,
-                                                     'human_threshold' : structural_thresholds.human_threshold,
-                                                     'raw_score'       : raw_ai_prob,
-                                                    },
+            confidence                                 *= structural_thresholds.confidence_multiplier
+            confidence                                  = max(structural_metric_params.MIN_CONFIDENCE, min(structural_metric_params.MAX_CONFIDENCE, confidence))
+
+            return MetricResult(metric_name           = self.name,
+                                synthetic_probability = synthetic_prob,
+                                authentic_probability = authentic_prob,
+                                hybrid_probability    = hybrid_prob,
+                                confidence            = confidence,
+                                details               = {**features, 
+                                                         'domain_used'        : domain.value,
+                                                         'synthetic_threshold': structural_thresholds.synthetic_threshold,
+                                                         'authentic_threshold': structural_thresholds.authentic_threshold,
+                                                         'raw_score'          : raw_synthetic_score,
+                                                        },
                                )
             
         except Exception as e:
             logger.error(f"Error in {self.name} computation: {repr(e)}")
-            return MetricResult(metric_name       = self.name,
-                                ai_probability    = 0.5,
-                                human_probability = 0.5,
-                                mixed_probability = 0.0,
-                                confidence        = 0.0,
-                                error             = str(e),
-                               )
+            return self._default_result(error = str(e))
     
 
-
     def _apply_domain_thresholds(self, raw_score: float, thresholds: Any, features: Dict[str, Any]) -> tuple:
         """
         Apply domain-specific thresholds to convert raw score to probabilities
         """
-        ai_threshold    = thresholds.ai_threshold    # Domain-specific
-        human_threshold = thresholds.human_threshold # Domain-specific
+        params              = structural_metric_params
+        synthetic_threshold = thresholds.synthetic_threshold
+        authentic_threshold = thresholds.authentic_threshold
         
         # Calculate probabilities based on threshold distances
-        if (raw_score >= ai_threshold):
-            # Above AI threshold - strongly AI
-            distance_from_threshold = raw_score - ai_threshold
-            ai_prob                 = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
-            human_prob              = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-        
-        elif (raw_score <= human_threshold):
-            # Below human threshold - strongly human
-            distance_from_threshold = human_threshold - raw_score
-            ai_prob                 = 0.3 - (distance_from_threshold * 0.3)  # 0.3 to 0.0
-            human_prob              = 0.7 + (distance_from_threshold * 0.3)  # 0.7 to 1.0
+        if (raw_score >= synthetic_threshold):
+            # Above synthetic threshold - strongly synthetic
+            distance_from_threshold = raw_score - synthetic_threshold
+            synthetic_prob          = params.STRONG_SYNTHETIC_BASE_PROB + (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = (params.MAX_PROBABILITY - params.STRONG_SYNTHETIC_BASE_PROB) - (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+        
+        elif (raw_score <= authentic_threshold):
+            # Below authentic threshold - strongly authentic
+            distance_from_threshold = authentic_threshold - raw_score
+            synthetic_prob          = (params.MAX_PROBABILITY - params.STRONG_AUTHENTIC_BASE_PROB) - (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
+            authentic_prob          = params.STRONG_AUTHENTIC_BASE_PROB + (distance_from_threshold * params.WEAK_PROBABILITY_ADJUSTMENT)
         
         else:
             # Between thresholds - uncertain zone
-            range_width = ai_threshold - human_threshold
+            range_width = synthetic_threshold - authentic_threshold
             
-            if (range_width > 0):
-                position_in_range = (raw_score - human_threshold) / range_width
-                ai_prob           = 0.3 + (position_in_range * 0.4)  # 0.3 to 0.7
-                human_prob        = 0.7 - (position_in_range * 0.4)  # 0.7 to 0.3
+            if (range_width > params.ZERO_TOLERANCE):
+                position_in_range = (raw_score - authentic_threshold) / range_width
+                synthetic_prob    = params.UNCERTAIN_SYNTHETIC_RANGE_START + (position_in_range * params.UNCERTAIN_RANGE_WIDTH)
+                authentic_prob    = params.UNCERTAIN_AUTHENTIC_RANGE_START - (position_in_range * params.UNCERTAIN_RANGE_WIDTH)
             
             else:
-                ai_prob    = 0.5
-                human_prob = 0.5
+                synthetic_prob = params.NEUTRAL_PROBABILITY
+                authentic_prob = params.NEUTRAL_PROBABILITY
         
         # Ensure probabilities are valid
-        ai_prob    = max(0.0, min(1.0, ai_prob))
-        human_prob = max(0.0, min(1.0, human_prob))
+        synthetic_prob = max(params.MIN_PROBABILITY, min(params.MAX_PROBABILITY, synthetic_prob))
+        authentic_prob = max(params.MIN_PROBABILITY, min(params.MAX_PROBABILITY, authentic_prob))
         
-        # Calculate mixed probability based on statistical patterns
-        mixed_prob = self._calculate_mixed_probability(features)
+        # Calculate hybrid probability based on statistical patterns
+        hybrid_prob    = self._calculate_hybrid_probability(features = features)
         
         # Normalize to sum to 1.0
-        total      = ai_prob + human_prob + mixed_prob
+        total          = synthetic_prob + authentic_prob + hybrid_prob
         
-        if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+        if (total > params.ZERO_TOLERANCE):
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return ai_prob, human_prob, mixed_prob
+        return synthetic_prob, authentic_prob, hybrid_prob
 
     
     def _extract_features(self, text: str) -> Dict[str, Any]:
@@ -143,43 +141,55 @@ class StructuralMetric(StatisticalMetric):
         Extract all structural features from text
         """
         # Basic tokenization
-        sentences           = self._split_sentences(text)
-        words               = self._tokenize_words(text)
+        sentences           = self._split_sentences(text = text)
+        words               = self._tokenize_words(text = text)
         
         # Sentence-level features
         sentence_lengths    = [len(s.split()) for s in sentences]
-        avg_sentence_length = np.mean(sentence_lengths) if sentence_lengths else 0
-        std_sentence_length = np.std(sentence_lengths) if len(sentence_lengths) > 1 else 0
+        avg_sentence_length = np.mean(sentence_lengths) if sentence_lengths else structural_metric_params.ZERO_VALUE
+        std_sentence_length = np.std(sentence_lengths) if len(sentence_lengths) > structural_metric_params.MIN_SENTENCE_LENGTH_FOR_STD else structural_metric_params.ZERO_VALUE
         
         # Word-level features
         word_lengths        = [len(w) for w in words]
-        avg_word_length     = np.mean(word_lengths) if word_lengths else 0
-        std_word_length     = np.std(word_lengths) if len(word_lengths) > 1 else 0
+        avg_word_length     = np.mean(word_lengths) if word_lengths else structural_metric_params.ZERO_VALUE
+        std_word_length     = np.std(word_lengths) if len(word_lengths) > structural_metric_params.MIN_WORD_LENGTH_FOR_STD else structural_metric_params.ZERO_VALUE
         
         # Vocabulary richness
         vocabulary_size     = len(set(words))
-        type_token_ratio    = vocabulary_size / len(words) if words else 0
+        type_token_ratio    = vocabulary_size / len(words) if words else structural_metric_params.ZERO_VALUE
         
         # Punctuation analysis
-        punctuation_density = self._calculate_punctuation_density(text)
-        comma_frequency     = text.count(',') / len(words) if words else 0
+        punctuation_density = self._calculate_punctuation_density(text = text)
+        comma_frequency     = text.count(',') / len(words) if words else structural_metric_params.ZERO_VALUE
         
         # Burstiness (variation in patterns)
-        burstiness          = self._calculate_burstiness(sentence_lengths)
+        burstiness          = self._calculate_burstiness(values = sentence_lengths)
         
         # Uniformity scores
-        length_uniformity   = 1.0 - (std_sentence_length / avg_sentence_length) if avg_sentence_length > 0 else 0
-        length_uniformity   = max(0, min(1, length_uniformity))
+        if (avg_sentence_length > structural_metric_params.ZERO_TOLERANCE):
+            length_uniformity = structural_metric_params.MAX_PROBABILITY - (std_sentence_length / avg_sentence_length)
+            length_uniformity = max(structural_metric_params.MIN_PROBABILITY, min(structural_metric_params.MAX_PROBABILITY, length_uniformity))
+        
+        else:
+            length_uniformity = structural_metric_params.MIN_PROBABILITY
         
         # Readability approximation (simplified)
-        readability         = self._calculate_readability(text, sentences, words)
+        readability         = self._calculate_readability(text      = text, 
+                                                          sentences = sentences,
+                                                          words     =  words,
+                                                         )
         
         # Pattern detection
-        repetition_score    = self._detect_repetitive_patterns(words)
+        repetition_score    = self._detect_repetitive_patterns(words = words)
         
         # N-gram analysis
-        bigram_diversity    = self._calculate_ngram_diversity(words, n = 2)
-        trigram_diversity   = self._calculate_ngram_diversity(words, n = 3)
+        bigram_diversity    = self._calculate_ngram_diversity(words = words, 
+                                                              n     = structural_metric_params.BIGRAM_N,
+                                                             )
+
+        trigram_diversity   = self._calculate_ngram_diversity(words = words, 
+                                                              n     = structural_metric_params.TRIGRAM_N,
+                                                             )
         
         return {"avg_sentence_length" : round(avg_sentence_length, 2),
                 "std_sentence_length" : round(std_sentence_length, 2),
@@ -204,8 +214,7 @@ class StructuralMetric(StatisticalMetric):
         """
         Split text into sentences
         """
-        # Simple sentence splitting
-        sentences = re.split(r'[.!?]+', text)
+        sentences = re.split(structural_metric_params.SENTENCE_SPLIT_PATTERN, text)
         
         return [s.strip() for s in sentences if s.strip()]
     
@@ -214,8 +223,7 @@ class StructuralMetric(StatisticalMetric):
         """
         Tokenize text into words
         """
-        # Simple word tokenization
-        words = re.findall(r'\b\w+\b', text.lower())
+        words = re.findall(structural_metric_params.WORD_TOKENIZE_PATTERN, text.lower())
         
         return words
     
@@ -224,54 +232,53 @@ class StructuralMetric(StatisticalMetric):
         """
         Calculate punctuation density
         """
-        punctuation = re.findall(r'[^\w\s]', text)
+        punctuation = re.findall(structural_metric_params.PUNCTUATION_PATTERN, text)
         total_chars = len(text)
         
-        return len(punctuation) / total_chars if total_chars > 0 else 0
+        return len(punctuation) / total_chars if total_chars > structural_metric_params.ZERO_TOLERANCE else structural_metric_params.ZERO_VALUE
     
 
     def _calculate_burstiness(self, values: List[float]) -> float:
         """
-        Calculate burstiness score (variation in patterns)
-        Higher burstiness typically indicates human writing
+        Calculate burstiness score (variation in patterns): Higher burstiness typically indicates human writing
         """
-        if (len(values) < 2):
-            return 0.0
+        if (len(values) < structural_metric_params.MIN_VALUES_FOR_BURSTINESS):
+            return structural_metric_params.ZERO_VALUE
         
         mean_val   = np.mean(values)
         std_val    = np.std(values)
         
-        if (mean_val == 0):
-            return 0.0
+        if (mean_val < structural_metric_params.ZERO_TOLERANCE):
+            return structural_metric_params.ZERO_VALUE
         
         # Coefficient of variation
         cv         = std_val / mean_val
         
         # Normalize to 0-1 range
-        burstiness = min(1.0, cv / 2.0)
+        burstiness = min(structural_metric_params.MAX_PROBABILITY, cv / structural_metric_params.BURSTINESS_NORMALIZATION_FACTOR)
         
         return burstiness
     
 
     def _calculate_readability(self, text: str, sentences: List[str], words: List[str]) -> float:
         """
-        Calculate simplified readability score
-        (Approximation of Flesch Reading Ease)
+        Calculate simplified readability score: Approximation of Flesch Reading Ease
         """
         if not sentences or not words:
-            return 0.0
+            return structural_metric_params.NEUTRAL_READABILITY_SCORE
         
         total_sentences = len(sentences)
         total_words     = len(words)
         total_syllables = sum(self._count_syllables(word) for word in words)
         
         # Flesch Reading Ease approximation
-        if ((total_sentences > 0) and (total_words > 0)):
-            score = 206.835 - 1.015 * (total_words / total_sentences) - 84.6 * (total_syllables / total_words)
-            return max(0, min(100, score))
+        if ((total_sentences > structural_metric_params.ZERO_TOLERANCE) and (total_words > structural_metric_params.ZERO_TOLERANCE)):
+            
+            score = (structural_metric_params.FLESCH_CONSTANT_1 - structural_metric_params.FLESCH_CONSTANT_2 * (total_words / total_sentences) - structural_metric_params.FLESCH_CONSTANT_3 * (total_syllables / total_words))
+            
+            return max(structural_metric_params.MIN_READABILITY_SCORE, min(structural_metric_params.MAX_READABILITY_SCORE, score))
        
-        # Neutral score
-        return 50.0 
+        return structural_metric_params.NEUTRAL_READABILITY_SCORE
     
 
     def _count_syllables(self, word: str) -> int:
@@ -287,7 +294,7 @@ class StructuralMetric(StatisticalMetric):
             is_vowel = char in vowels
             if is_vowel and not previous_was_vowel:
                 syllable_count += 1
-            
+
             previous_was_vowel = is_vowel
         
         # Adjust for silent 'e'
@@ -306,11 +313,10 @@ class StructuralMetric(StatisticalMetric):
         Detect repetitive patterns in text
         AI text sometimes shows more repetition
         """
-        if (len(words) < 10):
-            return 0.0
+        if (len(words) < structural_metric_params.MIN_WORDS_FOR_REPETITION):
+            return structural_metric_params.ZERO_VALUE
         
-        # Check for repeated words in close proximity
-        window_size = 10
+        window_size = structural_metric_params.REPETITION_WINDOW_SIZE
         repetitions = 0
         
         for i in range(len(words) - window_size):
@@ -321,128 +327,129 @@ class StructuralMetric(StatisticalMetric):
         
         # Normalize
         max_repetitions  = (len(words) - window_size) * window_size
-        repetition_score = repetitions / max_repetitions if max_repetitions > 0 else 0
         
-        return repetition_score
+        if (max_repetitions > structural_metric_params.ZERO_TOLERANCE):
+            repetition_score = repetitions / max_repetitions
+            return min(structural_metric_params.MAX_PROBABILITY, repetition_score)
+        
+        return structural_metric_params.ZERO_VALUE
 
     
     def _calculate_ngram_diversity(self, words: List[str], n: int = 2) -> float:
         """
-        Calculate n-gram diversity
-        Higher diversity often indicates human writing
+        Calculate n-gram diversity: Higher diversity often indicates human writing
         """
-        if (len(words) < n):
-            return 0.0
+        if (len(words) < structural_metric_params.MIN_WORDS_FOR_NGRAM):
+            return structural_metric_params.ZERO_VALUE
         
         # Generate n-grams
         ngrams        = [tuple(words[i:i+n]) for i in range(len(words) - n + 1)]
-        
-        # Calculate diversity as ratio of unique n-grams to total n-grams
-        unique_ngrams = len(set(ngrams))
         total_ngrams  = len(ngrams)
         
-        diversity     = unique_ngrams / total_ngrams if total_ngrams > 0 else 0
+        if total_ngrams > structural_metric_params.ZERO_TOLERANCE:
+            unique_ngrams = len(set(ngrams))
+            diversity     = unique_ngrams / total_ngrams
+            return min(structural_metric_params.MAX_PROBABILITY, diversity)
         
-        return diversity
+        return structural_metric_params.ZERO_VALUE
     
 
-    def _calculate_ai_probability(self, features: Dict[str, Any]) -> tuple:
+    def _calculate_synthetic_probability(self, features: Dict[str, Any]) -> tuple:
         """
-        Calculate AI probability based on structural features
-        Returns raw score and confidence
+        Calculate synthetic probability based on structural features: Returns raw score and confidence
         """
-        ai_indicators = list()
+        synthetic_indicators = list()
+        params               = structural_metric_params
         
-        # Low burstiness suggests AI (AI is more consistent)
-        if (features['burstiness_score'] < 0.3):
-            # Strong AI indicator
-            ai_indicators.append(0.7)
-
-        elif (features['burstiness_score'] < 0.5):
-            # Moderate AI indicator
-            ai_indicators.append(0.5)
+        # Low burstiness suggests synthetic (AI is more consistent)
+        if (features['burstiness_score'] < params.BURSTINESS_LOW_THRESHOLD):
+            synthetic_indicators.append(params.STRONG_SYNTHETIC_WEIGHT)
 
+        elif (features['burstiness_score'] < params.BURSTINESS_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(params.WEAK_SYNTHETIC_WEIGHT)
+        
+        # High length uniformity suggests synthetic
+        if (features['length_uniformity'] > params.LENGTH_UNIFORMITY_HIGH_THRESHOLD):
+            synthetic_indicators.append(params.STRONG_SYNTHETIC_WEIGHT)
+        
+        elif (features['length_uniformity'] > params.LENGTH_UNIFORMITY_MEDIUM_THRESH):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
         
-        # High length uniformity suggests AI
-        if (features['length_uniformity'] > 0.7):
-            # Strong AI indicator
-            ai_indicators.append(0.7)
-
-        elif (features['length_uniformity'] > 0.5):
-            # Moderate AI indicator
-            ai_indicators.append(0.5)
-
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(params.WEAK_SYNTHETIC_WEIGHT)
+        
+        # Low n-gram diversity suggests synthetic
+        if (features['bigram_diversity'] < params.BIGRAM_DIVERSITY_LOW_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
         
-        # Low n-gram diversity suggests AI
-        if (features['bigram_diversity'] < 0.7):
-            # Moderate AI indicator
-            ai_indicators.append(0.6)
-
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.4)
+            synthetic_indicators.append(params.VERY_WEAK_SYNTHETIC_WEIGHT)
+        
+        # Moderate readability suggests synthetic (AI often produces "perfect" readability)
+        if (params.READABILITY_SYNTHETIC_MIN <= features['readability_score'] <= params.READABILITY_SYNTHETIC_MAX):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
         
-        # Moderate readability suggests AI (AI often produces "perfect" readability)
-        if (60 <= features['readability_score'] <= 75):
-            # Moderate AI indicator
-            ai_indicators.append(0.6)
-
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.4)
+            synthetic_indicators.append(params.VERY_WEAK_SYNTHETIC_WEIGHT)
+        
+        # Low repetition suggests synthetic (AI avoids excessive repetition)
+        if (features['repetition_score'] < params.REPETITION_LOW_THRESHOLD):
+            synthetic_indicators.append(params.MODERATE_SYNTHETIC_WEIGHT)
+        
+        elif (features['repetition_score'] < params.REPETITION_MEDIUM_THRESHOLD):
+            synthetic_indicators.append(params.NEUTRAL_WEIGHT)
         
-        # Low repetition suggests AI (AI avoids excessive repetition)
-        if (features['repetition_score'] < 0.1):
-            # Moderate AI indicator
-            ai_indicators.append(0.6)
-
-        elif (features['repetition_score'] < 0.2):
-            # Neutral
-            ai_indicators.append(0.5)
-
         else:
-            # Weak AI indicator
-            ai_indicators.append(0.3)
+            synthetic_indicators.append(params.WEAK_SYNTHETIC_WEIGHT)
         
         # Calculate raw score and confidence
-        raw_score  = np.mean(ai_indicators) if ai_indicators else 0.5
-        confidence = 1.0 - (np.std(ai_indicators) / 0.5) if ai_indicators else 0.5
-        confidence = max(0.1, min(0.9, confidence))
+        if synthetic_indicators:
+            raw_score  = np.mean(synthetic_indicators)
+            confidence = params.MAX_PROBABILITY - min(params.MAX_PROBABILITY, np.std(synthetic_indicators) / params.CONFIDENCE_STD_NORMALIZER)
+            confidence = max(params.MIN_CONFIDENCE, min(params.MAX_CONFIDENCE, confidence))
+        
+        else:
+            raw_score  = params.NEUTRAL_PROBABILITY
+            confidence = params.NEUTRAL_CONFIDENCE
         
         return raw_score, confidence
     
 
-    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+    def _calculate_hybrid_probability(self, features: Dict[str, Any]) -> float:
         """
-        Calculate probability of mixed AI/Human content based on structural patterns
+        Calculate probability of hybrid synthetic/authentic content based on structural patterns
         """
-        mixed_indicators = []
+        mixed_indicators = list()
+        params           = structural_metric_params
         
-        # High burstiness suggests mixed content (inconsistent patterns)
-        if features['burstiness_score'] > 0.6:
-            mixed_indicators.append(0.4)
+        # High burstiness suggests hybrid content (inconsistent patterns)
+        if (features['burstiness_score'] > params.BURSTINESS_HIGH_THRESHOLD):
+            mixed_indicators.append(params.MODERATE_HYBRID_WEIGHT)
         
         # Inconsistent sentence lengths might indicate mixing
-        if (features['std_sentence_length'] > features['avg_sentence_length'] * 0.8):
-            mixed_indicators.append(0.3)
+        if (features['avg_sentence_length'] > params.ZERO_TOLERANCE and features['std_sentence_length'] > features['avg_sentence_length'] * params.SENTENCE_LENGTH_VARIANCE_RATIO):
+            mixed_indicators.append(params.WEAK_HYBRID_WEIGHT)
         
         # Extreme values in multiple features might indicate mixing
         extreme_features = 0
-        if (features['type_token_ratio'] < 0.3) or (features['type_token_ratio'] > 0.9):
+        if (features['type_token_ratio'] < params.TYPE_TOKEN_RATIO_EXTREME_LOW) or (features['type_token_ratio'] > params.TYPE_TOKEN_RATIO_EXTREME_HIGH):
             extreme_features += 1
-        if (features['readability_score'] < 20) or (features['readability_score'] > 90):
+        
+        if (features['readability_score'] < params.READABILITY_EXTREME_LOW) or (features['readability_score'] > params.READABILITY_EXTREME_HIGH):
             extreme_features += 1
         
         if (extreme_features >= 2):
-            mixed_indicators.append(0.3)
+            mixed_indicators.append(params.WEAK_HYBRID_WEIGHT)
         
-        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        if mixed_indicators:
+            hybrid_prob = np.mean(mixed_indicators)
+            return min(params.MAX_HYBRID_PROBABILITY, hybrid_prob)
+        
+        return params.MIN_PROBABILITY
+
 
 
 # Export

models/__init__.py

@@ -1,13 +0,0 @@
-# DEPENDENCIES
-from .model_manager import *
-from .model_registry import *
-
-
-# Export everything
-__all__ = ["ModelCache",
-           "ModelManager",
-           "ModelRegistry",
-           "ModelUsageStats",
-           "get_model_manager",
-           "get_model_registry",
-          ]

models/model_manager.py

@@ -181,15 +181,7 @@ class ModelManager:
         """
         Check if model is already downloaded
         """
-        model_config = get_model_config(model_name = model_name)
-        
-        if not model_config:
-            return False
-        
-        # Check if model exists in cache directory
-        model_path = self.cache_dir / model_config.model_id.replace("/", "_")
-        
-        return model_path.exists() and model_name in self.metadata
+        return model_name in self.metadata
     
 
     def load_model(self, model_name: str, force_download: bool = False) -> Any:
@@ -211,6 +203,8 @@ class ModelManager:
             cached = self.cache.get(key = model_name)
             
             if cached is not None:
+                self.metadata[model_name]["last_used"] = datetime.now().isoformat()
+                self._save_metadata()
                 return cached
         
         # Get model configuration
@@ -226,8 +220,8 @@ class ModelManager:
             if (model_config.model_type == ModelType.SENTENCE_TRANSFORMER):
                 model = self._load_sentence_transformer(config = model_config)
 
-            elif (model_config.model_type == ModelType.GPT):
-                model = self._load_gpt_model(config = model_config)
+            elif (model_config.model_type == ModelType.LANGUAGE_MODEL):
+                model = self._load_language_model(config = model_config)
 
             elif (model_config.model_type == ModelType.CLASSIFIER):
                 model = self._load_classifier(config = model_config)
@@ -295,7 +289,7 @@ class ModelManager:
         logger.info(f"Loading tokenizer for: {model_name}")
         
         try:
-            if (model_config.model_type in [ModelType.GPT, 
+            if (model_config.model_type in [ModelType.LANGUAGE_MODEL, 
                                             ModelType.CLASSIFIER, 
                                             ModelType.SEQUENCE_CLASSIFICATION, 
                                             ModelType.TRANSFORMER,
@@ -328,7 +322,7 @@ class ModelManager:
         return model
         
     
-    def _load_gpt_model(self, config: ModelConfig) -> tuple:
+    def _load_language_model(self, config: ModelConfig) -> tuple:
         """
         Load GPT-style model with tokenizer
         """
@@ -489,12 +483,20 @@ class ModelManager:
             raise ValueError(f"Unknown model: {model_name}")
         
         logger.info(f"Loading pipeline: {task} with {model_name}")
+
+        cache_key = f"{model_name}:{task}"
+        cached    = self.cache.get(cache_key)
+        
+        if cached:
+             return cached
         
         pipe = pipeline(task         = task,
                         model        = model_config.model_id,
                         device       = 0 if self.device.type == "cuda" else -1,
                         model_kwargs = {"cache_dir": str(self.cache_dir)},
                        )
+
+        self.cache.put(cache_key, pipe)
         
         return pipe
     
@@ -549,7 +551,7 @@ class ModelManager:
                                     cache_folder       = str(self.cache_dir),
                                    )
                                    
-            elif (model_config.model_type == ModelType.GPT):
+            elif (model_config.model_type == ModelType.LANGUAGE_MODEL):
                 GPT2LMHeadModel.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
                                                 cache_dir                     = str(self.cache_dir),
                                                )

models/model_registry.py

@@ -1,6 +1,4 @@
 # DEPENDENCIES
-import gc
-import torch
 import threading
 from typing import Any
 from typing import Dict
@@ -8,36 +6,11 @@ from typing import List
 from loguru import logger
 from typing import Optional
 from datetime import datetime
-from dataclasses import dataclass
-from config.model_config import ModelConfig
+from config.schemas import ModelUsageStats
 from config.model_config import MODEL_REGISTRY
 from config.model_config import get_model_config
 
 
-@dataclass
-class ModelUsageStats:
-    """
-    Lightweight model usage statistics
-    """
-    model_name               : str
-    load_count               : int
-    last_used                : datetime
-    total_usage_time_seconds : float
-    avg_usage_time_seconds   : float
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"model_name"               : self.model_name,
-                "load_count"               : self.load_count,
-                "last_used"                : self.last_used.isoformat(),
-                "total_usage_time_seconds" : round(self.total_usage_time_seconds, 2),
-                "avg_usage_time_seconds"   : round(self.avg_usage_time_seconds, 2),
-               }
-
-
 class ModelRegistry:
     """
     Model registry module for tracking model usage statistics and performance metrics
@@ -64,13 +37,24 @@ class ModelRegistry:
         """
         Initialize registry with all known models
         """
+        self.usage_stats.clear()
+        self.dependency_graph.clear()
+
         for model_name in MODEL_REGISTRY.keys():
+            config                       = get_model_config(model_name)
+
+            # Register usage stats
             self.usage_stats[model_name] = ModelUsageStats(model_name               = model_name,
-                                                           load_count               = 0,
-                                                           last_used                = datetime.now(),
+                                                           usage_count              = 0,
+                                                           last_used                = None,
+                                                           timed_usage_count        = 0,
                                                            total_usage_time_seconds = 0.0,
                                                            avg_usage_time_seconds   = 0.0,
                                                           )
+
+            # Register dependencies if defined
+            if config and config.additional_params.get("depends_on"):
+                self.dependency_graph[model_name] = config.additional_params["depends_on"]
     
 
     def record_model_usage(self, model_name: str, usage_time_seconds: float = 0.0):
@@ -87,21 +71,23 @@ class ModelRegistry:
             if model_name not in self.usage_stats:
                 # Auto-register unknown models
                 self.usage_stats[model_name] = ModelUsageStats(model_name               = model_name,
-                                                               load_count               = 0,
-                                                               last_used                = datetime.now(),
+                                                               usage_count              = 0,
+                                                               last_used                = datetime.utcnow(),
+                                                               timed_usage_count        = 0,
                                                                total_usage_time_seconds = 0.0,
                                                                avg_usage_time_seconds   = 0.0,
                                                               )
             
-            stats             = self.usage_stats[model_name]
-            stats.load_count += 1
-            stats.last_used   = datetime.now()
+            stats              = self.usage_stats[model_name]
+            stats.usage_count += 1
+            stats.last_used    = datetime.utcnow()
             
             if (usage_time_seconds > 0):
                 stats.total_usage_time_seconds += usage_time_seconds
-                stats.avg_usage_time_seconds    = stats.total_usage_time_seconds / stats.load_count
+                stats.timed_usage_count        += 1
+                stats.avg_usage_time_seconds    = (stats.total_usage_time_seconds / stats.timed_usage_count)
             
-            logger.debug(f"Recorded usage for {model_name} (count: {stats.load_count})")
+            logger.debug(f"Recorded usage for {model_name} (count: {stats.usage_count})")
     
 
     def get_usage_stats(self, model_name: str) -> Optional[ModelUsageStats]:
@@ -118,7 +104,7 @@ class ModelRegistry:
         """
         with self.lock:
             sorted_models = sorted(self.usage_stats.values(), 
-                                   key     = lambda x: x.load_count, 
+                                   key     = lambda x: x.usage_count, 
                                    reverse = True,
                                   )
 
@@ -193,10 +179,10 @@ class ModelRegistry:
         Generate a comprehensive usage report
         """
         with self.lock:
-            total_usage   = sum(stats.load_count for stats in self.usage_stats.values())
-            active_models = [name for name, stats in self.usage_stats.items() if stats.load_count > 0]
+            total_usage   = sum(stats.usage_count for stats in self.usage_stats.values())
+            active_models = [name for name, stats in self.usage_stats.items() if stats.usage_count > 0]
             
-            return {"timestamp"           : datetime.now().isoformat(),
+            return {"timestamp"           : datetime.utcnow().isoformat(),
                     "summary"             : {"total_models_tracked" : len(self.usage_stats),
                                              "active_models"        : len(active_models),
                                              "total_usage_count"    : total_usage,
@@ -219,8 +205,9 @@ class ModelRegistry:
             if model_name:
                 if model_name in self.usage_stats:
                     self.usage_stats[model_name] = ModelUsageStats(model_name               = model_name,
-                                                                   load_count               = 0,
-                                                                   last_used                = datetime.now(),
+                                                                   usage_count              = 0,
+                                                                   last_used                = datetime.utcnow(),
+                                                                   timed_usage_count        = 0,
                                                                    total_usage_time_seconds = 0.0,
                                                                    avg_usage_time_seconds   = 0.0,
                                                                   )

processors/__init__.py

@@ -1,26 +0,0 @@
-# DEPENDENCIES
-from .text_processor import *
-from .language_detector import *
-from .domain_classifier import *
-from .document_extractor import *
-
-
-# Export everything
-__all__ = ["Script", 
-           "Language",
-           "is_english",
-           "extract_text",
-           "quick_detect", 
-           "TextProcessor",
-           "ProcessedText", 
-           "quick_process",
-           "extract_words",
-           "LanguageDetector",
-           "DomainClassifier", 
-           "DomainPrediction", 
-           "extract_sentences",
-           "DocumentExtractor",
-           "ExtractedDocument", 
-           "extract_from_upload",
-           "LanguageDetectionResult", 
-          ]     

processors/document_extractor.py

@@ -2,7 +2,6 @@
 import io
 import os
 import re
-import mimetypes
 from typing import Any
 from typing import Dict
 from typing import List
@@ -10,7 +9,8 @@ from pathlib import Path
 from typing import Tuple
 from loguru import logger
 from typing import Optional 
-from dataclasses import dataclass
+from config.schemas import ExtractedDocument
+from config.constants import document_extraction_params
 
 
 # Document processing libraries
@@ -67,82 +67,38 @@ except ImportError:
     BS4_AVAILABLE = False
 
 
-@dataclass
-class ExtractedDocument:
-    """
-    Container for extracted document content with metadata
-    """
-    text              : str
-    file_path         : Optional[str]
-    file_type         : str
-    file_size_bytes   : int
-    page_count        : int
-    extraction_method : str
-    metadata          : Dict[str, Any]
-    is_success        : bool
-    error_message     : Optional[str]
-    warnings          : List[str]
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for JSON serialization
-        """
-        return {"text_length"        : len(self.text),
-                "file_type"          : self.file_type,
-                "file_size_bytes"    : self.file_size_bytes,
-                "page_count"         : self.page_count,
-                "extraction_method"  : self.extraction_method,
-                "metadata"           : self.metadata,
-                "is_success"         : self.is_success,
-                "error_message"      : self.error_message,
-                "warnings"           : self.warnings,
-               }
-
-
 class DocumentExtractor:
     """
-    Extracts text from various document formats for AI detection processing
+    Extracts and normalizes textual content from heterogeneous document formats
+    for downstream text authentication and provenance analysis
 
     Supported Formats:
-    - Plain text (.txt, .md, .log)
-    - PDF documents (.pdf) - Uses PyMuPDF as primary extractor
+    - Plain text (.txt, .md, .log, .csv)
+    - PDF documents (.pdf)
     - Microsoft Word (.doc, .docx)
     - Rich Text Format (.rtf)
     - HTML files (.html, .htm)
 
-    Features:
-    - Robust error handling
-    - Encoding detection
-    - Metadata extraction
-    - Page/section preservation
-    - Memory-efficient processing
-    """
-    
-    # Supported file extensions
-    SUPPORTED_EXTENSIONS = {'.txt', '.text', '.md', '.markdown', '.log', '.csv', '.pdf', '.docx', '.doc',  '.rtf', '.html', '.htm'}
-    
-    # Text file extensions
-    TEXT_EXTENSIONS      = {'.txt', '.text', '.md', '.markdown', '.log', '.csv'}
-    
-    # Maximum file size (50 MB default)
-    MAX_FILE_SIZE        = 50 * 1024 * 1024
-
-    
-    def __init__(self, max_file_size: int = MAX_FILE_SIZE, extract_metadata: bool = True):
+    Design Principles:
+    - Loss-minimized text extraction
+    - Best-effort fallback strategy
+    - Metadata-preserving ingestion
+    - Format-agnostic downstream compatibility
+    """    
+    def __init__(self, extract_metadata: bool = True):
         """
         Initialize document extractor
         
         Arguments:
         ----------
-            max_file_size      { int }  : Maximum file size in bytes
-
             extract_metadata   { bool } : Extract document metadata
         """
-        self.max_file_size      = max_file_size
-        self.extract_metadata   = extract_metadata
+        self.max_file_size        = document_extraction_params.MAX_FILE_SIZE
+        self.text_extensions      = document_extraction_params.TEXT_EXTENSIONS
+        self.supported_extensions = document_extraction_params.SUPPORTED_EXTENSIONS
+        self.extract_metadata     = extract_metadata
         
-        logger.info(f"DocumentExtractor initialized (max_size={max_file_size/1024/1024:.1f}MB)")
+        logger.info(f"DocumentExtractor initialized (max_size={self.max_file_size/1024/1024:.1f}MB)")
     
 
     def extract(self, file_path: str) -> ExtractedDocument:
@@ -173,7 +129,7 @@ class DocumentExtractor:
             file_ext  = file_path.suffix.lower()
             
             # Route to appropriate extractor
-            if (file_ext in self.TEXT_EXTENSIONS):
+            if (file_ext in self.text_extensions):
                 result = self._extract_text_file(file_path)
             
             elif (file_ext == '.pdf'):
@@ -227,7 +183,7 @@ class DocumentExtractor:
             # Determine file type
             file_ext = Path(filename).suffix.lower()
             
-            if file_ext not in self.SUPPORTED_EXTENSIONS:
+            if file_ext not in self.supported_extensions:
                 return self._create_error_result(file_path = filename,
                                                  error     = f"Unsupported file type: {file_ext}",
                                                 )
@@ -239,7 +195,7 @@ class DocumentExtractor:
                                                 )
             
             # Route to appropriate extractor
-            if (file_ext in self.TEXT_EXTENSIONS):
+            if (file_ext in self.text_extensions):
                 result = self._extract_text_bytes(file_bytes, filename)
             
             elif (file_ext == '.pdf'):
@@ -508,7 +464,7 @@ class DocumentExtractor:
             # Primary: Try PyMuPDF first
             if PYPDF_AVAILABLE:
                 try:
-                    doc        = fitz.open(stream=file_bytes, filetype="pdf")
+                    doc        = fitz.open(stream = file_bytes, filetype = "pdf")
                     page_count = doc.page_count
                     metadata   = doc.metadata
                     
@@ -865,7 +821,7 @@ class DocumentExtractor:
             return False, f"File too large: {file_size/1024/1024:.1f}MB (max: {self.max_file_size/1024/1024:.1f}MB)"
         
         # Check file extension
-        if (file_path.suffix.lower() not in self.SUPPORTED_EXTENSIONS):
+        if (file_path.suffix.lower() not in self.supported_extensions):
             return False, f"Unsupported file type: {file_path.suffix}"
         
         return True, None

processors/domain_classifier.py

@@ -4,45 +4,36 @@ from typing import List
 from typing import Tuple
 from loguru import logger
 from typing import Optional
-from dataclasses import dataclass
-from config.threshold_config import Domain
+from config.enums import Domain
+from config.schemas import DomainPrediction
 from models.model_manager import get_model_manager
+from config.constants import domain_classification_params
 from config.threshold_config import interpolate_thresholds
 from config.threshold_config import get_threshold_for_domain
 
-
-@dataclass
-class DomainPrediction:
-    """
-    Result of domain classification
-    """
-    primary_domain   : Domain
-    secondary_domain : Optional[Domain]
-    confidence       : float
-    domain_scores    : Dict[str, float]
     
 
 class DomainClassifier:
     """
     Classifies text into domains using zero-shot classification
     """
-    # Enhanced domain labels for zero-shot classification
-    DOMAIN_LABELS = {Domain.ACADEMIC      : ["academic paper", "research article", "scientific paper", "scholarly writing", "thesis", "dissertation", "academic research"],
-                     Domain.CREATIVE      : ["creative writing", "fiction", "story", "narrative", "poetry", "literary work", "imaginative writing"],
-                     Domain.AI_ML         : ["artificial intelligence", "machine learning", "neural networks", "data science", "AI research", "deep learning"],
-                     Domain.SOFTWARE_DEV  : ["software development", "programming", "coding", "software engineering", "web development", "application development"],
-                     Domain.TECHNICAL_DOC : ["technical documentation", "user manual", "API documentation", "technical guide", "system documentation"],
-                     Domain.ENGINEERING   : ["engineering document", "technical design", "engineering analysis", "mechanical engineering", "electrical engineering"],
-                     Domain.SCIENCE       : ["scientific research", "physics", "chemistry", "biology", "scientific study", "experimental results"],
-                     Domain.BUSINESS      : ["business document", "corporate communication", "business report", "professional writing", "executive summary"],
-                     Domain.JOURNALISM    : ["news article", "journalism", "press release", "news report", "media content", "reporting"],
-                     Domain.SOCIAL_MEDIA  : ["social media post", "casual writing", "online content", "informal text", "social media content"],
-                     Domain.BLOG_PERSONAL : ["personal blog", "personal writing", "lifestyle blog", "personal experience", "opinion piece", "diary entry"],
-                     Domain.LEGAL         : ["legal document", "contract", "legal writing", "law", "legal agreement", "legal analysis"],
-                     Domain.MEDICAL       : ["medical document", "healthcare", "clinical", "medical report", "health information", "medical research"],
-                     Domain.MARKETING     : ["marketing content", "advertising", "brand content", "promotional writing", "sales copy", "marketing material"],
-                     Domain.TUTORIAL      : ["tutorial", "how-to guide", "instructional content", "step-by-step guide", "educational guide", "learning material"],
-                     Domain.GENERAL       : ["general content", "everyday writing", "common text", "standard writing", "normal text", "general information"],
+    # Use constants from config - map string keys to Domain enum
+    DOMAIN_LABELS = {Domain.ACADEMIC      : domain_classification_params.DOMAIN_LABELS["academic"],
+                     Domain.CREATIVE      : domain_classification_params.DOMAIN_LABELS["creative"],
+                     Domain.AI_ML         : domain_classification_params.DOMAIN_LABELS["ai_ml"],
+                     Domain.SOFTWARE_DEV  : domain_classification_params.DOMAIN_LABELS["software_dev"],
+                     Domain.TECHNICAL_DOC : domain_classification_params.DOMAIN_LABELS["technical_doc"],
+                     Domain.ENGINEERING   : domain_classification_params.DOMAIN_LABELS["engineering"],
+                     Domain.SCIENCE       : domain_classification_params.DOMAIN_LABELS["science"],
+                     Domain.BUSINESS      : domain_classification_params.DOMAIN_LABELS["business"],
+                     Domain.JOURNALISM    : domain_classification_params.DOMAIN_LABELS["journalism"],
+                     Domain.SOCIAL_MEDIA  : domain_classification_params.DOMAIN_LABELS["social_media"],
+                     Domain.BLOG_PERSONAL : domain_classification_params.DOMAIN_LABELS["blog_personal"],
+                     Domain.LEGAL         : domain_classification_params.DOMAIN_LABELS["legal"],
+                     Domain.MEDICAL       : domain_classification_params.DOMAIN_LABELS["medical"],
+                     Domain.MARKETING     : domain_classification_params.DOMAIN_LABELS["marketing"],
+                     Domain.TUTORIAL      : domain_classification_params.DOMAIN_LABELS["tutorial"],
+                     Domain.GENERAL       : domain_classification_params.DOMAIN_LABELS["general"],
                     }
     
 
@@ -61,7 +52,7 @@ class DomainClassifier:
             logger.info("Initializing domain classifier...")
             
             # Load primary domain classifier (zero-shot)
-            self.primary_classifier = self.model_manager.load_model(model_name = "domain_classifier")
+            self.primary_classifier = self.model_manager.load_model(model_name = "content_domain_classifier")
             
             # Load fallback classifier
             try:
@@ -81,15 +72,15 @@ class DomainClassifier:
             return False
     
 
-    def classify(self, text: str, top_k: int = 2, min_confidence: float = 0.3) -> DomainPrediction:
+    def classify(self, text: str, top_k: int = domain_classification_params.TOP_K_DOMAINS, min_confidence: float = domain_classification_params.MIN_CONFIDENCE_THRESHOLD) -> DomainPrediction:
         """
         Classify text into domain using zero-shot classification
         
         Arguments:
         ----------
-            text            { str }  : Input text
+            text           { str }   : Input text
 
-            top_k           { int }  : Number of top domains to consider
+            top_k          { int }   : Number of top domains to consider
             
             min_confidence { float } : Minimum confidence threshold
             
@@ -110,7 +101,7 @@ class DomainClassifier:
                                                       )
             
             # If primary result meets confidence threshold, return it
-            if (primary_result.confidence >= min_confidence):
+            if (primary_result.evidence_strength >= min_confidence):
                 return primary_result
             
             # If primary is low confidence but we have fallback, try fallback
@@ -122,7 +113,7 @@ class DomainClassifier:
                                                            )
                 
                 # Use fallback if it has higher confidence
-                if fallback_result.confidence > primary_result.confidence:
+                if (fallback_result.evidence_strength > primary_result.evidence_strength):
                     return fallback_result
             
             # Return primary result even if low confidence
@@ -152,7 +143,7 @@ class DomainClassifier:
         Classify using a zero-shot classification model
         """
         # Preprocess text
-        processed_text = self._preprocess_text(text)
+        processed_text  = self._preprocess_text(text)
         
         # Get all candidate labels
         all_labels      = list()
@@ -160,8 +151,9 @@ class DomainClassifier:
 
         for domain, labels in self.DOMAIN_LABELS.items():
             # Use the first label as the primary one for this domain
-            primary_label = labels[0]
+            primary_label                  = labels[0]
             all_labels.append(primary_label)
+
             label_to_domain[primary_label] = domain
         
         # Perform zero-shot classification
@@ -195,35 +187,48 @@ class DomainClassifier:
         
         secondary_domain                  = None
         secondary_score                   = 0.0
+        
+        # Use constant for secondary domain minimum score
+        secondary_min_score               = domain_classification_params.SECONDARY_DOMAIN_MIN_SCORE
 
-        if ((len(sorted_domains) > 1) and (sorted_domains[1][1] >= 0.1)):
+        if ((len(sorted_domains) > 1) and (sorted_domains[1][1] >= secondary_min_score)):
             secondary_domain = Domain(sorted_domains[1][0])
             secondary_score  = sorted_domains[1][1]
         
-        # Calculate confidence
-        confidence = primary_score
+        # Calculate evidence_strength
+        evidence_strength    = primary_score
+        
+        # Use constants for mixed domain detection
+        high_conf_threshold  = domain_classification_params.HIGH_CONFIDENCE_THRESHOLD
+        mixed_secondary_min  = domain_classification_params.MIXED_DOMAIN_SECONDARY_MIN
+        mixed_ratio_thresh   = domain_classification_params.MIXED_DOMAIN_RATIO_THRESHOLD
+        mixed_conf_penalty   = domain_classification_params.MIXED_DOMAIN_CONFIDENCE_PENALTY
         
         # If we have mixed domains with close scores, adjust confidence
-        if (secondary_domain and (primary_score < 0.7) and (secondary_score > 0.3)):
+        if (secondary_domain and (primary_score < high_conf_threshold) and (secondary_score > mixed_secondary_min)):
+            
             score_ratio = secondary_score / primary_score
             
             # Secondary is at least 60% of primary
-            if (score_ratio > 0.6):  
+            if (score_ratio > mixed_ratio_thresh):
                 # Lower confidence for mixed domains
-                confidence = (primary_score + secondary_score) / 2 * 0.8
+                evidence_strength = ((primary_score + secondary_score) / 2 * mixed_conf_penalty)
                 logger.info(f"Mixed domain detected: {primary_domain.value} + {secondary_domain.value}, will use interpolated thresholds")
         
+        # Use constant for low confidence threshold
+        low_conf_threshold = domain_classification_params.LOW_CONFIDENCE_THRESHOLD
+        
         # If primary score is low and we have a secondary, it's uncertain
-        elif ((primary_score < 0.5) and secondary_domain):
-            # Reduce confidence
-            confidence *= 0.8  
+        if ((primary_score < low_conf_threshold) and secondary_domain):
+            # Reduce confidence using penalty
+            evidence_strength *= mixed_conf_penalty
         
-        logger.info(f"{model_type.capitalize()} model classified domain: {primary_domain.value} (confidence: {confidence:.3f})")
+        logger.info(f"{model_type.capitalize()} model classified domain: {primary_domain.value} (confidence: {evidence_strength:.3f})")
         
-        return DomainPrediction(primary_domain   = primary_domain,
-                                secondary_domain = secondary_domain,
-                                confidence       = confidence,
-                                domain_scores    = avg_domain_scores,
+        return DomainPrediction(primary_domain    = primary_domain,
+                                secondary_domain  = secondary_domain,
+                                evidence_strength = evidence_strength,
+                                domain_scores     = avg_domain_scores,
                                )
     
 
@@ -231,10 +236,12 @@ class DomainClassifier:
         """
         Preprocess text for classification
         """
-        # Truncate to reasonable length
-        words = text.split()
-        if (len(words) > 400):
-            text = ' '.join(words[:400])
+        # Truncate to reasonable length using constant
+        max_words = domain_classification_params.MAX_WORDS_FOR_CLASSIFICATION
+        words     = text.split()
+        
+        if (len(words) > max_words):
+            text = ' '.join(words[:max_words])
         
         # Clean up text
         text = text.strip()
@@ -248,10 +255,10 @@ class DomainClassifier:
         """
         Get default prediction when classification fails
         """
-        return DomainPrediction(primary_domain   = Domain.GENERAL,
-                                secondary_domain = None,
-                                confidence       = 0.5,
-                                domain_scores    = {Domain.GENERAL.value: 1.0},
+        return DomainPrediction(primary_domain    = Domain.GENERAL,
+                                secondary_domain  = None,
+                                evidence_strength = 0.5,
+                                domain_scores     = {Domain.GENERAL.value: 1.0},
                                )
     
 
@@ -259,9 +266,15 @@ class DomainClassifier:
         """
         Get adaptive thresholds based on domain prediction
         """
-        if ((domain_prediction.confidence > 0.7) and (not domain_prediction.secondary_domain)):
+        # Use constants for threshold decisions
+        high_conf_threshold = domain_classification_params.HIGH_CONFIDENCE_THRESHOLD
+        med_conf_threshold  = domain_classification_params.MEDIUM_CONFIDENCE_THRESHOLD
+        
+        # High confidence, single domain - use domain-specific thresholds
+        if ((domain_prediction.evidence_strength > high_conf_threshold) and (not domain_prediction.secondary_domain)):
             return get_threshold_for_domain(domain_prediction.primary_domain)
         
+        # Mixed domains - interpolate between primary and secondary
         if domain_prediction.secondary_domain:
             primary_score   = domain_prediction.domain_scores.get(domain_prediction.primary_domain.value, 0)
             secondary_score = domain_prediction.domain_scores.get(domain_prediction.secondary_domain.value, 0)
@@ -270,19 +283,21 @@ class DomainClassifier:
                 weight1 = primary_score / (primary_score + secondary_score)
             
             else:
-                weight1 = domain_prediction.confidence
+                weight1 = domain_prediction.evidence_strength
                 
-            return interpolate_thresholds(domain1  = domain_prediction.primary_domain,
-                                          domain2  = domain_prediction.secondary_domain,
-                                          weight1  = weight1,
+            return interpolate_thresholds(domain1 = domain_prediction.primary_domain,
+                                          domain2 = domain_prediction.secondary_domain,
+                                          weight1 = weight1,
                                          )
         
-        if (domain_prediction.confidence < 0.6):
+        # Low/medium confidence - blend with general domain
+        if (domain_prediction.evidence_strength < med_conf_threshold):
             return interpolate_thresholds(domain1 = domain_prediction.primary_domain,
                                           domain2 = Domain.GENERAL,
-                                          weight1 = domain_prediction.confidence,
+                                          weight1 = domain_prediction.evidence_strength,
                                          )
         
+        # Default: use domain-specific thresholds
         return get_threshold_for_domain(domain_prediction.primary_domain)
     
     
@@ -295,8 +310,130 @@ class DomainClassifier:
         self.is_initialized      = False
 
 
+def quick_classify(text: str, **kwargs) -> DomainPrediction:
+    """
+    Quick domain classification with default settings
+    
+    Arguments:
+    ----------
+        text     { str } : Input text
+
+        **kwargs         : Override settings
+        
+    Returns:
+    --------
+        { DomainPrediction } : DomainPrediction object
+    """
+    classifier = DomainClassifier()
+    classifier.initialize()
+    return classifier.classify(text, **kwargs)
+
+
+def get_domain_name(domain: Domain) -> str:
+    """
+    Get human-readable domain name
+    
+    Arguments:
+    ----------
+        domain { Domain } : Domain enum value
+        
+    Returns:
+    --------
+        { str } : Human-readable domain name
+    """
+    domain_names = {Domain.ACADEMIC      : "Academic",
+                    Domain.CREATIVE      : "Creative Writing",
+                    Domain.AI_ML         : "AI/ML",
+                    Domain.SOFTWARE_DEV  : "Software Development",
+                    Domain.TECHNICAL_DOC : "Technical Documentation",
+                    Domain.ENGINEERING   : "Engineering",
+                    Domain.SCIENCE       : "Science",
+                    Domain.BUSINESS      : "Business",
+                    Domain.JOURNALISM    : "Journalism",
+                    Domain.SOCIAL_MEDIA  : "Social Media",
+                    Domain.BLOG_PERSONAL : "Personal Blog",
+                    Domain.LEGAL         : "Legal",
+                    Domain.MEDICAL       : "Medical",
+                    Domain.MARKETING     : "Marketing",
+                    Domain.TUTORIAL      : "Tutorial",
+                    Domain.GENERAL       : "General",
+                   }
+
+    return domain_names.get(domain, "Unknown")
+
+
+def is_technical_domain(domain: Domain) -> bool:
+    """
+    Check if domain is technical in nature
+    
+    Arguments:
+    ----------
+        domain { Domain } : Domain enum value
+        
+    Returns:
+    --------
+        { bool } : True if technical domain
+    """
+    technical_domains = {Domain.AI_ML,
+                         Domain.SOFTWARE_DEV,
+                         Domain.TECHNICAL_DOC,
+                         Domain.ENGINEERING,
+                         Domain.SCIENCE,
+                        }
+
+    return domain in technical_domains
+
+
+def is_creative_domain(domain: Domain) -> bool:
+    """
+    Check if domain is creative in nature
+    
+    Arguments:
+    ----------
+        domain { Domain } : Domain enum value
+        
+    Returns:
+    --------
+        { bool } : True if creative domain
+    """
+    creative_domains = {Domain.CREATIVE,
+                        Domain.JOURNALISM,
+                        Domain.SOCIAL_MEDIA,
+                        Domain.BLOG_PERSONAL,
+                        Domain.MARKETING,
+                       }
+
+    return domain in creative_domains
+
+
+def is_formal_domain(domain: Domain) -> bool:
+    """
+    Check if domain is formal in nature
+    
+    Arguments:
+    ----------
+        domain { Domain } : Domain enum value
+        
+    Returns:
+    --------
+        { bool } : True if formal domain
+    """
+    formal_domains = {Domain.ACADEMIC,
+                      Domain.LEGAL,
+                      Domain.MEDICAL,
+                      Domain.BUSINESS,
+                     }
+
+    return domain in formal_domains
+
 
 # Export
-__all__ = ["DomainClassifier",
+__all__ = ["Domain",
+           "DomainClassifier",
            "DomainPrediction",
-          ]
+           "quick_classify",
+           "get_domain_name",
+           "is_technical_domain",
+           "is_creative_domain",
+           "is_formal_domain",
+          ]

processors/language_detector.py

@@ -2,13 +2,16 @@
 import re
 import torch
 import string
-from enum import Enum
 from typing import Dict
 from typing import List
 from typing import Tuple
 from loguru import logger
 from typing import Optional
+from config.enums import Script
 from dataclasses import dataclass
+from config.enums import Language
+from config.schemas import LanguageDetectionResult
+from config.constants import language_detection_params
 
 
 # Try to import optional libraries
@@ -32,152 +35,50 @@ except ImportError:
     MODEL_MANAGER_AVAILABLE = False
 
 
-class Language(Enum):
-    """
-    ISO 639-1 language codes for supported languages
-    """
-    ENGLISH    = "en"
-    SPANISH    = "es"
-    FRENCH     = "fr"
-    GERMAN     = "de"
-    ITALIAN    = "it"
-    PORTUGUESE = "pt"
-    RUSSIAN    = "ru"
-    CHINESE    = "zh"
-    JAPANESE   = "ja"
-    KOREAN     = "ko"
-    ARABIC     = "ar"
-    HINDI      = "hi"
-    DUTCH      = "nl"
-    POLISH     = "pl"
-    TURKISH    = "tr"
-    SWEDISH    = "sv"
-    VIETNAMESE = "vi"
-    INDONESIAN = "id"
-    THAI       = "th"
-    GREEK      = "el"
-    HEBREW     = "he"
-    CZECH      = "cs"
-    ROMANIAN   = "ro"
-    DANISH     = "da"
-    FINNISH    = "fi"
-    NORWEGIAN  = "no"
-    UNKNOWN    = "unknown"
-
-
-class Script(Enum):
-    """
-    Writing scripts
-    """
-    LATIN      = "latin"
-    CYRILLIC   = "cyrillic"
-    ARABIC     = "arabic"
-    CHINESE    = "chinese"
-    JAPANESE   = "japanese"
-    KOREAN     = "korean"
-    DEVANAGARI = "devanagari"
-    GREEK      = "greek"
-    HEBREW     = "hebrew"
-    THAI       = "thai"
-    MIXED      = "mixed"
-    UNKNOWN    = "unknown"
-
-
-@dataclass
-class LanguageDetectionResult:
-    """
-    Result of language detection
-    """
-    primary_language   : Language
-    confidence         : float
-    all_languages      : Dict[str, float]  # language_code -> confidence
-    script             : Script
-    is_multilingual    : bool
-    detection_method   : str
-    char_count         : int
-    word_count         : int
-    warnings           : List[str]
-    
-
-    def to_dict(self) -> Dict:
-        """
-        Convert to dictionary
-        """
-        return {"primary_language"  : self.primary_language.value,
-                "confidence"        : round(self.confidence, 4),
-                "all_languages"     : {k: round(v, 4) for k, v in self.all_languages.items()},
-                "script"            : self.script.value,
-                "is_multilingual"   : self.is_multilingual,
-                "detection_method"  : self.detection_method,
-                "char_count"        : self.char_count,
-                "word_count"        : self.word_count,
-                "warnings"          : self.warnings,
-               }
-
-
 class LanguageDetector:
     """
     Detects the language of input text using multiple strategies with fallbacks.
 
     Features:
-    - Primary    : XLM-RoBERTa model (supports 100+ languages)
-    - Fallback 1 : langdetect library (fast, probabilistic)
-    - Fallback 2 : Character-based heuristics
-    - Confidence scoring
-    - Multi-language detection
-    - Script detection (Latin, Cyrillic, Arabic, etc.)
+    - Learned language representations (when available)
+    - Statistical language probability estimation
+    - Script and character distribution analysis
+    - Multi-signal aggregation with fallbacks
 
     Supported Languages:
-    - 100+ languages via XLM-RoBERTa
-    - High accuracy for major languages (English, Spanish, French, German, Chinese, etc.)
+    - Broad multilingual coverage via learned language representations
+    - Deterministic support via script and statistical analysis
     """
-    # Minimum text length for reliable detection
-    MIN_TEXT_LENGTH = 20
-    
-    # Language name mappings
-    LANGUAGE_NAMES  = {"en": "English",
-                       "es": "Spanish",
-                       "fr": "French",
-                       "de": "German",
-                       "it": "Italian",
-                       "pt": "Portuguese",
-                       "ru": "Russian",
-                       "zh": "Chinese",
-                       "ja": "Japanese",
-                       "ko": "Korean",
-                       "ar": "Arabic",
-                       "hi": "Hindi",
-                      }
+    # Use constants from config
+    MIN_TEXT_LENGTH = language_detection_params.MINIMUM_TEXT_LENGTH
+    LANGUAGE_NAMES  = language_detection_params.LANGUAGE_NAMES
     
-    # Character ranges for script detection
-    SCRIPT_RANGES   = {Script.LATIN: [(0x0041, 0x007A), (0x00C0, 0x024F)],
-                       Script.CYRILLIC: [(0x0400, 0x04FF)],
-                       Script.ARABIC: [(0x0600, 0x06FF), (0x0750, 0x077F)],
-                       Script.CHINESE: [(0x4E00, 0x9FFF), (0x3400, 0x4DBF)],
-                       Script.JAPANESE: [(0x3040, 0x309F), (0x30A0, 0x30FF)],
-                       Script.KOREAN: [(0xAC00, 0xD7AF), (0x1100, 0x11FF)],
-                       Script.DEVANAGARI: [(0x0900, 0x097F)],
-                       Script.GREEK: [(0x0370, 0x03FF)],
-                       Script.HEBREW: [(0x0590, 0x05FF)],
-                       Script.THAI: [(0x0E00, 0x0E7F)],
+    # Map Script enum to string keys for SCRIPT_RANGES
+    SCRIPT_RANGES   = {Script.LATIN      : language_detection_params.SCRIPT_RANGES["latin"],
+                       Script.CYRILLIC   : language_detection_params.SCRIPT_RANGES["cyrillic"],
+                       Script.ARABIC     : language_detection_params.SCRIPT_RANGES["arabic"],
+                       Script.CHINESE    : language_detection_params.SCRIPT_RANGES["chinese"],
+                       Script.JAPANESE   : language_detection_params.SCRIPT_RANGES["japanese"],
+                       Script.KOREAN     : language_detection_params.SCRIPT_RANGES["korean"],
+                       Script.DEVANAGARI : language_detection_params.SCRIPT_RANGES["devanagari"],
+                       Script.GREEK      : language_detection_params.SCRIPT_RANGES["greek"],
+                       Script.HEBREW     : language_detection_params.SCRIPT_RANGES["hebrew"],
+                       Script.THAI       : language_detection_params.SCRIPT_RANGES["thai"],
                       }
     
 
-    def __init__(self, use_model: bool = True, min_confidence: float = 0.5):
+    def __init__(self, use_model: bool = True):
         """
         Initialize language detector
         
         Arguments:
         ----------
-            use_model       : Use ML model for detection (more accurate)
-
-            min_confidence  : Minimum confidence threshold
+            use_model : Use ML model for detection (more accurate)
         """
-        self.use_model      = use_model and MODEL_MANAGER_AVAILABLE
-        self.min_confidence = min_confidence
-        self.model_manager  = None
-        self.classifier     = None
-        self.is_initialized = False
+        self.use_model             = use_model and MODEL_MANAGER_AVAILABLE
+        self.model_manager         = None
+        self.classifier            = None
+        self.is_initialized        = False
         
         logger.info(f"LanguageDetector initialized (use_model={self.use_model})")
     
@@ -251,44 +152,45 @@ class LanguageDetector:
         # Try detection methods in order
         result = None
         
-        # Method 1 : ML Model
+        # Method 1: ML Model
         if self.use_model and self.is_initialized:
             try:
                 result                  = self._detect_with_model(text = cleaned_text)
-                result.detection_method = "xlm-roberta-model"
+                result.detection_method = "learned-language-representation"
             
             except Exception as e:
                 logger.warning(f"Model detection failed: {repr(e)}, trying fallback")
                 warnings.append("Model detection failed, using fallback")
         
-        # Method 2 : langdetect library
+        # Method 2: langdetect library
         if result is None and LANGDETECT_AVAILABLE:
             try:
                 result                  = self._detect_with_langdetect(text = cleaned_text)
-                result.detection_method = "langdetect-library"
+                result.detection_method = "statistical-language-estimation"
             
             except Exception as e:
                 logger.warning(f"langdetect failed: {repr(e)}, trying heuristics")
                 warnings.append("langdetect failed, using heuristics")
         
-        # Method 3 : Character-based heuristics
+        # Method 3: Character-based heuristics
         if result is None:
             result                  = self._detect_with_heuristics(cleaned_text, script)
-            result.detection_method = "character-heuristics"
+            result.detection_method = "character-distribution-analysis"
         
         # Add metadata
         result.script     = script
         result.char_count = char_count
         result.word_count = word_count
-
         result.warnings.extend(warnings)
         
-        # Check for multilingual content
-        if len([v for v in result.all_languages.values() if v > 0.2]) > 1:
+        # Check for multilingual content using constant
+        threshold         = language_detection_params.MULTILINGUAL_THRESHOLD
+
+        if len([v for v in result.all_languages.values() if v > threshold]) > 1:
             result.is_multilingual = True
             warnings.append("Text appears to contain multiple languages")
         
-        logger.info(f"Detected language: {result.primary_language.value} (confidence: {result.confidence:.2f}, method: {result.detection_method})")
+        logger.info(f"Detected language: {result.primary_language.value} (evidence_strength: {result.evidence_strength:.2f}, method: {result.detection_method})")
         
         return result
     
@@ -328,7 +230,7 @@ class LanguageDetector:
             raise
 
 
-    def _split_text_into_chunks(self, text: str, max_chunk_length: int = 500, min_chunk_length: int = 50) -> List[str]:
+    def _split_text_into_chunks(self, text: str, max_chunk_length: int = language_detection_params.MAX_CHUNK_LENGTH, min_chunk_length: int = language_detection_params.MIN_CHUNK_LENGTH) -> List[str]:
         """
         Split text into meaningful chunks for language detection
         
@@ -352,12 +254,11 @@ class LanguageDetector:
         sentences     = [s.strip() for s in sentences if s.strip()]
         
         chunks        = list()
-
         current_chunk = ""
         
         for sentence in sentences:
             # If adding this sentence doesn't exceed max length
-            if len(current_chunk) + len(sentence) + 1 <= max_chunk_length:
+            if ((len(current_chunk) + len(sentence) + 1) <= max_chunk_length):
                 if current_chunk:
                     current_chunk += " " + sentence
                 
@@ -366,7 +267,7 @@ class LanguageDetector:
             
             else:
                 # Current chunk is full, save it
-                if current_chunk and len(current_chunk) >= min_chunk_length:
+                if (current_chunk and (len(current_chunk) >= min_chunk_length)):
                     chunks.append(current_chunk)
                 
                 # Start new chunk with current sentence
@@ -377,29 +278,32 @@ class LanguageDetector:
             chunks.append(current_chunk)
         
         # Strategy 2: If sentence splitting didn't work well, use fixed-length chunks
-        if ((len(chunks) == 0) or ((len(chunks) == 1 )and (len(chunks[0]) > max_chunk_length))):
+        if ((len(chunks) == 0) or ((len(chunks) == 1) and (len(chunks[0]) > max_chunk_length))):
             chunks = self._split_fixed_length(text, max_chunk_length)
         
         logger.debug(f"Split {len(text)} chars into {len(chunks)} chunks: {[len(c) for c in chunks]}")
         return chunks
 
 
-    def _split_fixed_length(self, text: str, chunk_size: int = 1000) -> List[str]:
+    def _split_fixed_length(self, text: str, chunk_size: int = language_detection_params.FIXED_CHUNK_SIZE) -> List[str]:
         """
         Fallback: Split text into fixed-length chunks
         """
-        chunks = list()
+        chunks              = list()
+        word_boundary_ratio = language_detection_params.WORD_BOUNDARY_RATIO
 
         for i in range(0, len(text), chunk_size):
             chunk = text[i:i + chunk_size]
+            
             # Try to break at word boundaries
             if ((i + chunk_size) < len(text)):
                 last_space = chunk.rfind(' ')
-                # If we found a space in the last 30%
-                if (last_space > chunk_size * 0.7):  
+                # If we found a space in the last 30% (using word_boundary_ratio)
+                if (last_space > chunk_size * word_boundary_ratio):
                     chunk = chunk[:last_space].strip()
 
             chunks.append(chunk)
+        
         return chunks
 
 
@@ -408,32 +312,34 @@ class LanguageDetector:
         Process a single chunk through the language detection model
         """
         # Get the tokenizer from the pipeline
-        tokenizer = self.classifier.tokenizer
-        
-        # Tokenize with explicit length limits
-        inputs    = tokenizer(chunk,
-                              return_tensors     = "pt",
-                              truncation         = True,
-                              max_length         = 512,
-                              padding            = True,
-                              add_special_tokens = True,
-                             )
+        tokenizer  = self.classifier.tokenizer
+        
+        # Tokenize with explicit length limits using constant
+        max_length = language_detection_params.MODEL_MAX_LENGTH
+        inputs     = tokenizer(chunk,
+                               return_tensors     = "pt",
+                               truncation         = True,
+                               max_length         = max_length,
+                               padding            = True,
+                               add_special_tokens = True,
+                              )
         
         # Get model from pipeline
-        model     = self.classifier.model
-        device    = next(model.parameters()).device
+        model      = self.classifier.model
+        device     = next(model.parameters()).device
         
         # Move inputs to correct device
-        inputs    = {k: v.to(device) for k, v in inputs.items()}
+        inputs     = {k: v.to(device) for k, v in inputs.items()}
         
         with torch.no_grad():
             outputs     = model(**inputs)
             predictions = torch.nn.functional.softmax(outputs.logits, dim=-1)
         
-        # Get top predictions for this chunk
-        top_predictions = torch.topk(predictions[0], k = 3)
+        # Get top predictions for this chunk using constant
+        top_k           = language_detection_params.TOP_K_PREDICTIONS
+        top_predictions = torch.topk(predictions[0], k=top_k)
         
-        chunk_results   = dict()
+        chunk_results = dict()
 
         for i in range(len(top_predictions.indices)):
             lang_idx  = top_predictions.indices[i].item()
@@ -451,6 +357,19 @@ class LanguageDetector:
         return chunk_results
 
 
+    def _map_language_code(self, code: str) -> Language:
+        """
+        Map language code string to Language enum
+        """
+        code = code.lower()
+
+        for lang in Language:
+            if (lang.value == code):
+                return lang
+
+        return Language.UNKNOWN
+
+
     def _aggregate_chunk_results(self, chunk_results: List[Dict]) -> LanguageDetectionResult:
         """
         Aggregate results from multiple chunks using weighted averaging
@@ -460,9 +379,9 @@ class LanguageDetector:
         chunk_weights = list()
         
         for chunk_result in chunk_results:
-            # Calculate chunk weight based on confidence and diversity
+            # Calculate chunk weight based on evidence_strength and diversity
             top_score    = max(chunk_result.values()) if chunk_result else 0
-            # Weight by confidence
+            # Weight by evidence_strength
             chunk_weight = top_score  
             
             chunk_weights.append(chunk_weight)
@@ -480,12 +399,12 @@ class LanguageDetector:
             if (len(scores) != len(chunk_weights)):
                 # Use simple average if weight mismatch
                 weighted_scores[lang_code] = sum(scores) / len(scores)
-
+            
             else:
                 # Weighted average
                 weighted_sum               = sum(score * weight for score, weight in zip(scores, chunk_weights))
                 total_weight               = sum(chunk_weights)
-                weighted_scores[lang_code] = weighted_sum / total_weight if total_weight > 0 else sum(scores) / len(scores)
+                weighted_scores[lang_code] = (weighted_sum / total_weight if total_weight > 0 else sum(scores) / len(scores))
         
         # Find primary language
         primary_lang = None
@@ -493,13 +412,13 @@ class LanguageDetector:
         
         for lang_code, score in weighted_scores.items():
             if (score > primary_conf):
-                primary_conf = score
-                primary_lang = lang_code
+                primary_evidence_strength = score
+                primary_lang              = lang_code
         
         # Convert to Language enum
         try:
-            primary_language = Language(primary_lang)
-
+            primary_language = self._map_language_code(code = primary_lang)
+        
         except ValueError:
             primary_language = Language.UNKNOWN
         
@@ -508,21 +427,21 @@ class LanguageDetector:
         
         warnings          = list()
 
-        if detection_quality.get('low_confidence', False):
-            warnings.append("Low confidence across multiple chunks")
+        if detection_quality.get('evidence_strength', False):
+            warnings.append("Low evidence_strength across multiple chunks")
 
         if detection_quality.get('inconsistent', False):
             warnings.append("Inconsistent language detection across chunks")
         
-        return LanguageDetectionResult(primary_language = primary_language,
-                                       confidence       = primary_conf,
-                                       all_languages    = weighted_scores,
-                                       script           = Script.UNKNOWN,
-                                       is_multilingual  = detection_quality.get('multilingual', False),
-                                       detection_method = "model-chunked",
-                                       char_count       = 0,
-                                       word_count       = 0,
-                                       warnings         = warnings,
+        return LanguageDetectionResult(primary_language  = primary_language,
+                                       evidence_strength = primary_evidence_strength,
+                                       all_languages     = weighted_scores,
+                                       script            = Script.UNKNOWN,
+                                       is_multilingual   = detection_quality.get('multilingual', False),
+                                       detection_method  = "model-chunked",
+                                       char_count        = 0,
+                                       word_count        = 0,
+                                       warnings          = warnings,
                                       )
 
 
@@ -530,18 +449,21 @@ class LanguageDetector:
         """
         Assess the quality and consistency of language detection across chunks
         """
-        quality_metrics = {'low_confidence' : False,
-                           'inconsistent'   : False,
-                           'multilingual'   : False,
+        quality_metrics = {'low_evidence_strength' : False,
+                           'inconsistent'          : False,
+                           'multilingual'          : False,
                           }
         
         if not chunk_results:
             return quality_metrics
         
-        # Check for low confidence
-        avg_top_confidence = sum(max(chunk.values()) for chunk in chunk_results) / len(chunk_results)
-        if (avg_top_confidence < 0.6):
-            quality_metrics['low_confidence'] = True
+        # Check for low evidence_strength using constant
+        avg_top_evidence_strength       = sum(max(chunk.values()) for chunk in chunk_results) / len(chunk_results)
+        
+        low_evidence_strength_threshold = language_detection_params.LOW_CONFIDENCE_THRESHOLD
+        
+        if (avg_top_evidence_strength < low_evidence_strength_threshold):
+            quality_metrics['low_evidence_strength'] = True
         
         # Check for inconsistency (different primary languages across chunks)
         chunk_primaries = list()
@@ -554,8 +476,10 @@ class LanguageDetector:
         if (len(set(chunk_primaries)) > 1):
             quality_metrics['inconsistent'] = True
         
-        # Check for multilingual content
-        strong_languages = [lang for lang, score in final_scores.items() if score > 0.2]
+        # Check for multilingual content using constant
+        multilingual_threshold = language_detection_params.MULTILINGUAL_THRESHOLD
+        strong_languages       = [lang for lang, score in final_scores.items() if score > multilingual_threshold]
+
         if (len(strong_languages) > 1):
             quality_metrics['multilingual'] = True
         
@@ -575,63 +499,63 @@ class LanguageDetector:
             all_languages[prob.lang] = prob.prob
         
         # Primary language
-        primary       = lang_probs[0]
+        primary = lang_probs[0]
         
         try:
-            primary_language = Language(primary.lang)
-
+            primary_language = self._map_language_code(code = primary.lang)
+        
         except ValueError:
             primary_language = Language.UNKNOWN
         
-        return LanguageDetectionResult(primary_language = primary_language,
-                                       confidence       = primary.prob,
-                                       all_languages    = all_languages,
-                                       script           = Script.UNKNOWN,
-                                       is_multilingual  = False,
-                                       detection_method = "langdetect",
-                                       char_count       = 0,
-                                       word_count       = 0,
-                                       warnings         = [],
+        return LanguageDetectionResult(primary_language  = primary_language,
+                                       evidence_strength = primary.prob,
+                                       all_languages     = all_languages,
+                                       script            = Script.UNKNOWN,
+                                       is_multilingual   = False,
+                                       detection_method  = "langdetect",
+                                       char_count        = 0,
+                                       word_count        = 0,
+                                       warnings          = [],
                                       )
-    
+                                
 
     def _detect_with_heuristics(self, text: str, script: Script) -> LanguageDetectionResult:
         """
         Detect language using character-based heuristics
         """
         # Script-based language mapping
-        script_to_language = {Script.CHINESE    : Language.CHINESE,
-                              Script.JAPANESE   : Language.JAPANESE,
-                              Script.KOREAN     : Language.KOREAN,
-                              Script.ARABIC     : Language.ARABIC,
-                              Script.CYRILLIC   : Language.RUSSIAN,
-                              Script.DEVANAGARI : Language.HINDI,
-                              Script.GREEK      : Language.GREEK,
-                              Script.HEBREW     : Language.HEBREW,
-                              Script.THAI       : Language.THAI,
+        script_to_language = {Script.CHINESE:    Language.CHINESE,
+                              Script.JAPANESE:   Language.JAPANESE,
+                              Script.KOREAN:     Language.KOREAN,
+                              Script.ARABIC:     Language.ARABIC,
+                              Script.CYRILLIC:   Language.RUSSIAN,
+                              Script.DEVANAGARI: Language.HINDI,
+                              Script.GREEK:      Language.GREEK,
+                              Script.HEBREW:     Language.HEBREW,
+                              Script.THAI:       Language.THAI,
                              }
         
         # If script clearly indicates language
         if script in script_to_language:
-            primary_language = script_to_language[script]
-            # Moderate confidence for heuristics
-            confidence       = 0.7  
+            primary_language  = script_to_language[script]
+            # Moderate evidence_strength for heuristics
+            evidence_strength = 0.7
 
         else:
             # For Latin script, check common words
-            primary_language = self._detect_latin_language(text)
-            # Lower confidence
-            confidence       = 0.5  
-        
-        return LanguageDetectionResult(primary_language = primary_language,
-                                       confidence       = confidence,
-                                       all_languages    = {primary_language.value: confidence},
-                                       script           = script,
-                                       is_multilingual  = False,
-                                       detection_method = "heuristics",
-                                       char_count       = 0,
-                                       word_count       = 0,
-                                       warnings         = ["Detection using heuristics, accuracy may be limited"],
+            primary_language  = self._detect_latin_language(text)
+            # Lower evidence_strength
+            evidence_strength = 0.5
+        
+        return LanguageDetectionResult(primary_language  = primary_language,
+                                       evidence_strength = evidence_strength,
+                                       all_languages     = {primary_language.value: evidence_strength},
+                                       script            = script,
+                                       is_multilingual   = False,
+                                       detection_method  = "heuristics",
+                                       char_count        = 0,
+                                       word_count        = 0,
+                                       warnings          = ["Detection using heuristics, accuracy may be limited"],
                                       )
     
 
@@ -660,9 +584,9 @@ class LanguageDetector:
         
         # Return language with highest score
         if scores:
-            best_lang = max(scores.items(), key = lambda x: x[1])
+            best_lang = max(scores.items(), key=lambda x: x[1])
             # At least 3 matches
-            if (best_lang[1] > 2):  
+            if (best_lang[1] > 2):
                 return best_lang[0]
         
         # Default to English for Latin script
@@ -697,10 +621,11 @@ class LanguageDetector:
         # Calculate percentages
         script_percentages = {script: count / total_chars for script, count in script_counts.items() if count > 0}
         
-        # Check if mixed (no single script > 70%)
+        # Check if mixed using constant
+        dominance_threshold = language_detection_params.SCRIPT_DOMINANCE_THRESHOLD
         if (len(script_percentages) > 1):
             max_percentage = max(script_percentages.values())
-            if (max_percentage < 0.7):
+            if (max_percentage < dominance_threshold):
                 return Script.MIXED
         
         # Return dominant script
@@ -731,19 +656,20 @@ class LanguageDetector:
         """
         Create result for unknown language
         """
-        return LanguageDetectionResult(primary_language = Language.UNKNOWN,
-                                       confidence       = 0.0,
-                                       all_languages    = {},
-                                       script           = Script.UNKNOWN,
-                                       is_multilingual  = False,
-                                       detection_method = "none",
-                                       char_count       = len(text),
-                                       word_count       = len(text.split()),
-                                       warnings         = warnings,
+        return LanguageDetectionResult(primary_language  = Language.UNKNOWN,
+                                       evidence_strength = 0.0,
+                                       all_languages     = {},
+                                       script            = Script.UNKNOWN,
+                                       is_multilingual   = False,
+                                       detection_method  = "none",
+                                       char_count        = len(text),
+                                       word_count        = len(text.split()),
+                                       warnings          = warnings,
                                       )
 
     
-    def is_language(self, text: str, target_language: Language, threshold: float = 0.7) -> bool:
+    def is_language(self, text: str, target_language: Language, threshold: float = language_detection_params.LANGUAGE_MATCH_THRESHOLD
+    ) -> bool:
         """
         Check if text is in a specific language
         
@@ -753,14 +679,14 @@ class LanguageDetector:
 
             target_language : Language to check for
             
-            threshold       : Minimum confidence threshold
+            threshold       : Minimum evidence_strength threshold
             
         Returns:
         --------
-            { bool }        : True if text is in target language with sufficient confidence
+            { bool }        : True if text is in target language with sufficient evidence_strength
         """
         result = self.detect(text)
-        return ((result.primary_language == target_language) and (result.confidence >= threshold))
+        return ((result.primary_language == target_language) and (result.evidence_strength >= threshold))
 
     
     def get_supported_languages(self) -> List[str]:
@@ -778,7 +704,7 @@ class LanguageDetector:
         self.is_initialized = False
 
 
-# Convenience Functions 
+
 def quick_detect(text: str, **kwargs) -> LanguageDetectionResult:
     """
     Quick language detection with default settings
@@ -786,7 +712,6 @@ def quick_detect(text: str, **kwargs) -> LanguageDetectionResult:
     Arguments:
     ----------
         text     : Input text
-
         **kwargs : Override settings
         
     Returns:
@@ -801,17 +726,16 @@ def quick_detect(text: str, **kwargs) -> LanguageDetectionResult:
     return detector.detect(text)
 
 
-def is_english(text: str, threshold: float = 0.7) -> bool:
+def is_english(text: str, threshold: float = language_detection_params.LANGUAGE_MATCH_THRESHOLD) -> bool:
     """
     Quick check if text is English
     """
-    detector   = LanguageDetector(use_model = True)
+    detector   = LanguageDetector(use_model=True)
     is_english = detector.is_language(text, Language.ENGLISH, threshold)
     
     return is_english
 
 
-
 # Export
 __all__ = ['Script',
            'Language',
@@ -819,4 +743,4 @@ __all__ = ['Script',
            'quick_detect',
            'LanguageDetector',
            'LanguageDetectionResult',
-          ]
+          ]

processors/text_processor.py

@@ -7,51 +7,13 @@ from typing import Dict
 from typing import Tuple
 from loguru import logger
 from typing import Optional
-from dataclasses import dataclass
-
-
-@dataclass
-class ProcessedText:
-    """
-    Container for processed text with metadata
-    """
-    original_text      : str
-    cleaned_text       : str
-    sentences          : List[str]
-    words              : List[str]
-    paragraphs         : List[str]
-    char_count         : int
-    word_count         : int
-    sentence_count     : int
-    paragraph_count    : int
-    avg_sentence_length: float
-    avg_word_length    : float
-    is_valid           : bool
-    validation_errors  : List[str]
-    metadata           : Dict[str, Any]
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for JSON serialization
-        """
-        return {"original_length"      : len(self.original_text),
-                "cleaned_length"       : len(self.cleaned_text),
-                "char_count"           : self.char_count,
-                "word_count"           : self.word_count,
-                "sentence_count"       : self.sentence_count,
-                "paragraph_count"      : self.paragraph_count,
-                "avg_sentence_length"  : round(self.avg_sentence_length, 2),
-                "avg_word_length"      : round(self.avg_word_length, 2),
-                "is_valid"             : self.is_valid,
-                "validation_errors"    : self.validation_errors,
-                "metadata"             : self.metadata,
-               }
+from config.schemas import ProcessedText
+from config.constants import text_processing_params
 
 
 class TextProcessor:
     """
-    Handles text cleaning, normalization, sentence splitting, and preprocessing for AI detection metrics
+    Handles text cleaning, normalization, sentence splitting, and preprocessing for downstream text analysis and authentication signals
     
     Features::
     - Unicode normalization
@@ -63,10 +25,6 @@ class TextProcessor:
     - Text validation
     - Chunk creation for long texts
     """
-    
-    # Common abbreviations that shouldn't trigger sentence breaks
-    ABBREVIATIONS     = {'dr', 'mr', 'mrs', 'ms', 'prof', 'sr', 'jr', 'ph.d', 'inc', 'ltd', 'corp', 'co', 'vs', 'etc', 'e.g', 'i.e', 'al', 'fig', 'vol', 'no', 'approx', 'est', 'min', 'max', 'avg', 'dept', 'assoc', 'bros', 'u.s', 'u.k', 'a.m', 'p.m', 'b.c', 'a.d', 'st', 'ave', 'blvd'}
-    
     # Patterns for sentence splitting
     SENTENCE_ENDINGS  = r'[.!?]+(?=\s+[A-Z]|$)'
     
@@ -74,37 +32,21 @@ class TextProcessor:
     MULTIPLE_SPACES   = re.compile(r'\s+')
     MULTIPLE_NEWLINES = re.compile(r'\n{3,}')
     
-
-    def __init__(self, min_text_length: int = 50, max_text_length: int = 500000, preserve_formatting: bool = False, remove_urls: bool = True, remove_emails: bool = True,
-                 normalize_unicode: bool = True, fix_encoding: bool = True):
+    def __init__(self):
         """
         Initialize text processor
-        
-        Arguments:
-        ----------
-            min_text_length      : Minimum acceptable text length
-
-            max_text_length      : Maximum text length to process
-            
-            preserve_formatting  : Keep original line breaks and spacing
-            
-            remove_urls          : Remove URLs from text
-            
-            remove_emails        : Remove email addresses
-            
-            normalize_unicode    : Normalize Unicode characters
-            
-            fix_encoding         : Fix common encoding issues
         """
-        self.min_text_length     = min_text_length
-        self.max_text_length     = max_text_length
-        self.preserve_formatting = preserve_formatting
-        self.remove_urls         = remove_urls
-        self.remove_emails       = remove_emails
-        self.normalize_unicode   = normalize_unicode
-        self.fix_encoding        = fix_encoding
-        
-        logger.info(f"TextProcessor initialized with min_length={min_text_length}, max_length={max_text_length}")
+        self.min_text_length     = text_processing_params.MINIMUM_TEXT_LENGTH
+        self.max_text_length     = text_processing_params.MAXIMUM_TEXT_LENGTH
+        self.preserve_formatting = text_processing_params.PRESERVE_FORMATTING
+        self.remove_urls         = text_processing_params.REMOVE_URLS
+        self.remove_emails       = text_processing_params.REMOVE_EMAILS
+        self.normalize_unicode   = text_processing_params.NORMALIZE_UNICODE
+        self.fix_encoding        = text_processing_params.FIX_ENCODING
+        self.minimum_word_count  = text_processing_params.MINIMUM_WORD_COUNT
+        self.common_abbreviations = text_processing_params.COMMON_ABBREVIATIONS
+        
+        logger.info(f"TextProcessor initialized with min_length={self.min_text_length}, max_length={self.max_text_length}")
     
 
     def process(self, text: str, **kwargs) -> ProcessedText:
@@ -170,15 +112,15 @@ class TextProcessor:
             sent_count   = len(sentences)
             para_count   = len(paragraphs)
             
-            avg_sent_len = word_count / sent_count if sent_count > 0 else 0
+            avg_sent_len = word_count / sent_count if (sent_count > 0) else 0
             avg_word_len = sum(len(w) for w in words) / word_count if word_count > 0 else 0
             
             # Additional validation
             if (sent_count == 0):
                 validation_errors.append("No valid sentences found")
             
-            if (word_count < 10):
-                validation_errors.append(f"Too few words: {word_count} (minimum: 10)")
+            if (word_count < self.minimum_word_count):
+                validation_errors.append(f"Too few words: {word_count} (minimum: {self.minimum_word_count})")
             
             # Create metadata
             metadata = {"has_special_chars" : self._has_special_characters(text),
@@ -227,7 +169,7 @@ class TextProcessor:
         # Protect abbreviations
         protected_text = text
 
-        for abbr in self.ABBREVIATIONS:
+        for abbr in self.common_abbreviations:
             # Replace abbreviation periods with placeholder
             protected_text = re.sub(pattern = rf'\b{re.escape(abbr)}\.',
                                     repl    = abbr.replace('.', '<DOT>'),
@@ -417,8 +359,8 @@ class TextProcessor:
         text = unicodedata.normalize('NFKC', text)
         
         # Replace smart quotes and apostrophes
-        text = text.replace('"', '"').replace('"', '"')
-        text = text.replace(''', "'").replace(''', "'")
+        text = text.replace('“', '"').replace('”', '"')
+        text = text.replace('‘', "'").replace('’', "'")
         text = text.replace('—', '-').replace('–', '-')
         
         return text
@@ -492,9 +434,6 @@ class TextProcessor:
                             )
 
 
-
-# Convenience Functions
-
 def quick_process(text: str, **kwargs) -> ProcessedText:
     """
     Quick processing with default settings
@@ -535,47 +474,4 @@ __all__ = ['TextProcessor',
            'quick_process',
            'extract_sentences',
            'extract_words',
-          ]
-
-
-# ==================== Testing ====================
-if __name__ == "__main__":
-    # Test cases
-    test_texts = [
-        # Normal text
-        "This is a test. Dr. Smith works at the U.S. Department of Education. "
-        "He published a paper on AI detection in 2024.",
-        
-        # Text with encoding issues
-        "This text’s got some “weird†characters that need fixing.",
-        
-        # Text with URLs and emails
-        "Check out https://example.com or email me at [email protected] for more info.",
-        
-        # Short text (should fail validation)
-        "Too short.",
-        
-        # Text with numbers and special characters
-        "The price is $19.99 for version 2.0. Contact us at (555) 123-4567!",
-    ]
-    
-    processor = TextProcessor(min_text_length=20)
-    
-    for i, text in enumerate(test_texts, 1):
-        print(f"\n{'='*70}")
-        print(f"TEST CASE {i}")
-        print(f"{'='*70}")
-        print(f"Input: {text[:100]}...")
-        
-        result = processor.process(text)
-        
-        print(f"\nValid: {result.is_valid}")
-        if not result.is_valid:
-            print(f"Errors: {result.validation_errors}")
-        
-        print(f"Word count: {result.word_count}")
-        print(f"Sentence count: {result.sentence_count}")
-        print(f"Avg sentence length: {result.avg_sentence_length:.2f}")
-        print(f"\nSentences:")
-        for j, sent in enumerate(result.sentences[:3], 1):
-            print(f"  {j}. {sent}")
+          ]

reporter/__init__.py

@@ -1,10 +0,0 @@
-# DEPENDENCIES
-from reporter.report_generator import ReportGenerator
-from reporter.reasoning_generator import DetailedReasoning
-from reporter.reasoning_generator import ReasoningGenerator
-
-
-__all__ = ["ReasoningGenerator",
-           "DetailedReasoning",
-           "ReportGenerator",
-          ]

reporter/report_generator.py

@@ -8,26 +8,10 @@ from pathlib import Path
 from loguru import logger
 from typing import Optional
 from datetime import datetime
-from dataclasses import dataclass
-from detector.orchestrator import DetectionResult
-from detector.attribution import AttributionResult
-from reporter.reasoning_generator import DetailedReasoning
-from reporter.reasoning_generator import ReasoningGenerator
-
-
-@dataclass
-class DetailedMetric:
-    """
-    Metric data structure with sub-metrics
-    """
-    name              : str
-    ai_probability    : float
-    human_probability : float
-    confidence        : float
-    verdict           : str
-    description       : str
-    detailed_metrics  : Dict[str, float]
-    weight            : float
+from config.schemas import DetectionResult
+from config.schemas import DetailedMetricResult
+from config.schemas import DetailedReasoningResult
+from services.reasoning_generator import ReasoningGenerator
 
 
 class ReportGenerator:
@@ -59,8 +43,8 @@ class ReportGenerator:
         logger.info(f"ReportGenerator initialized (output_dir={self.output_dir})")
     
 
-    def generate_complete_report(self, detection_result: DetectionResult, attribution_result: Optional[AttributionResult] = None, highlighted_sentences: Optional[List] = None, 
-                                 formats: List[str] = ["json", "pdf"], filename_prefix: str = "ai_detection_report") -> Dict[str, str]:
+    def generate_complete_report(self, detection_result: DetectionResult, highlighted_sentences: Optional[List] = None, formats: List[str] = ["json", "pdf"], 
+                                 filename_prefix: str = "text_authenticity_report") -> Dict[str, str]:
         """
         Generate comprehensive report in JSON and PDF formats with detailed metrics
         
@@ -68,8 +52,6 @@ class ReportGenerator:
         ----------
             detection_result      : Detection analysis result
 
-            attribution_result    : Model attribution result (optional)
-
             highlighted_sentences : List of highlighted sentences (optional)
         
             formats               : List of formats to generate (json, pdf)
@@ -93,11 +75,10 @@ class ReportGenerator:
             logger.info("Using detection_dict directly")
         
         # Generate detailed reasoning
-        reasoning        = self.reasoning_generator.generate(ensemble_result    = detection_result.ensemble_result,
-                                                             metric_results     = detection_result.metric_results,
-                                                             domain             = detection_result.domain_prediction.primary_domain,
-                                                             attribution_result = attribution_result,
-                                                             text_length        = detection_result.processed_text.word_count,
+        reasoning        = self.reasoning_generator.generate(ensemble_result = detection_result.ensemble_result,
+                                                             metric_results  = detection_result.metric_results,
+                                                             domain          = detection_result.domain_prediction.primary_domain,
+                                                             text_length     = detection_result.processed_text.word_count,
                                                             )
         
         # Extract detailed metrics from ACTUAL detection results
@@ -113,8 +94,7 @@ class ReportGenerator:
             json_path               = self._generate_json_report(detection_data        = detection_data, 
                                                                  detection_dict_full   = detection_dict,
                                                                  reasoning             = reasoning, 
-                                                                 detailed_metrics      = detailed_metrics, 
-                                                                 attribution_result    = attribution_result,
+                                                                 detailed_metrics      = detailed_metrics,
                                                                  highlighted_sentences = highlighted_sentences,
                                                                  filename              = f"{filename_prefix}_{timestamp}.json",
                                                                 )
@@ -125,8 +105,7 @@ class ReportGenerator:
                 pdf_path               = self._generate_pdf_report(detection_data        = detection_data,
                                                                    detection_dict_full   = detection_dict,
                                                                    reasoning             = reasoning, 
-                                                                   detailed_metrics      = detailed_metrics, 
-                                                                   attribution_result    = attribution_result,
+                                                                   detailed_metrics      = detailed_metrics,
                                                                    highlighted_sentences = highlighted_sentences,
                                                                    filename              = f"{filename_prefix}_{timestamp}.pdf",
                                                                   )  
@@ -141,7 +120,7 @@ class ReportGenerator:
         return generated_files
 
 
-    def _extract_detailed_metrics(self, detection_data: Dict) -> List[DetailedMetric]:
+    def _extract_detailed_metrics(self, detection_data: Dict) -> List[DetailedMetricResult]:
         """
         Extract detailed metrics with sub-metrics from ACTUAL detection result
         """
@@ -163,33 +142,33 @@ class ReportGenerator:
                 continue
                 
             # Get actual probabilities and confidence
-            ai_prob    = metric_result.get("ai_probability", 0)
-            human_prob = metric_result.get("human_probability", 0)
+            synthetic_prob = metric_result.get("synthetic_probability", 0)
+            authentic_prob = metric_result.get("authentic_probability", 0)
             confidence = metric_result.get("confidence", 0)
             
             # Determine verdict based on actual probability
-            if (human_prob >= 0.6):  
-                verdict = "HUMAN"
+            if (authentic_prob >= 0.6):  
+                verdict = "Authentically-Written"
 
-            elif (ai_prob >= 0.6):  
-                verdict = "AI"
+            elif (synthetic_prob >= 0.6):  
+                verdict = "Synthetically-Generated"
             
-            elif (ai_prob > 0.4 and ai_prob < 0.6):
-                verdict = "MIXED"
+            elif (synthetic_prob > 0.4 and synthetic_prob < 0.6):
+                verdict = "Hybrid"
             
-            elif (human_prob > 0.4 and human_prob < 0.6):
-                verdict = "MIXED"
+            elif (authentic_prob > 0.4 and authentic_prob < 0.6):
+                verdict = "Hybrid"
             
             else:
                 # If both low, check which is higher
-                if (human_prob > ai_prob):
-                    verdict = "HUMAN"
+                if (authentic_prob > synthetic_prob):
+                    verdict = "Authentically-Written"
                 
-                elif (ai_prob > human_prob):
-                    verdict = "AI"
+                elif (synthetic_prob > authentic_prob):
+                    verdict = "Synthetically-Generated"
                 
                 else:
-                    verdict = "MIXED"
+                    verdict = "Hybrid"
             
             # Get actual weight or use default
             weight = 0.0
@@ -204,15 +183,15 @@ class ReportGenerator:
             # Get description based on metric type
             description           = self._get_metric_description(metric_name = metric_name)
             
-            detailed_metrics.append(DetailedMetric(name              = metric_name,
-                                                   ai_probability    = ai_prob * 100,         # Convert to percentage
-                                                   human_probability = human_prob * 100,      # Convert to percentage
-                                                   confidence        = confidence * 100,      # Convert to percentage
-                                                   verdict           = verdict,
-                                                   description       = description,
-                                                   detailed_metrics  = detailed_metrics_data,
-                                                   weight            = weight * 100,          # Convert to percentage
-                                                  )
+            detailed_metrics.append(DetailedMetricResult(name                  = metric_name,
+                                                         synthetic_probability = synthetic_prob * 100,  # Convert to percentage
+                                                         authentic_probability = authentic_prob * 100,  # Convert to percentage
+                                                         confidence            = confidence * 100,      # Convert to percentage
+                                                         verdict               = verdict,
+                                                         description           = description,
+                                                         detailed_metrics      = detailed_metrics_data,
+                                                         weight                = weight * 100,          # Convert to percentage
+                                                        )
                                    )
         
         logger.info(f"Extracted {len(detailed_metrics)} detailed metrics")
@@ -252,8 +231,8 @@ class ReportGenerator:
         
         # If no details available, provide basic calculated values
         if not details:
-            details = {"ai_probability"    : metric_result.get("ai_probability", 0) * 100,
-                       "human_probability" : metric_result.get("human_probability", 0) * 100,
+            details = {"synthetic_probability"    : metric_result.get("synthetic_probability", 0) * 100,
+                       "authentic_probability" : metric_result.get("authentic_probability", 0) * 100,
                        "confidence"        : metric_result.get("confidence", 0) * 100,
                        "score"             : metric_result.get("raw_score", 0) * 100,
                       }
@@ -276,8 +255,8 @@ class ReportGenerator:
         return descriptions.get(metric_name, "Advanced text analysis metric.")
 
 
-    def _generate_json_report(self, detection_data: Dict, detection_dict_full: Dict, reasoning: DetailedReasoning, detailed_metrics: List[DetailedMetric], 
-                              attribution_result: Optional[AttributionResult], highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
+    def _generate_json_report(self, detection_data: Dict, detection_dict_full: Dict, reasoning: DetailedReasoningResult, detailed_metrics: List[DetailedMetricResult], 
+                              highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
         """
         Generate JSON format report with detailed metrics
         """
@@ -286,8 +265,8 @@ class ReportGenerator:
 
         for metric in detailed_metrics:
             metrics_data.append({"name"              : metric.name,
-                                 "ai_probability"    : metric.ai_probability,
-                                 "human_probability" : metric.human_probability,
+                                 "synthetic_probability"    : metric.synthetic_probability,
+                                 "authentic_probability" : metric.authentic_probability,
                                  "confidence"        : metric.confidence,
                                  "verdict"           : metric.verdict,
                                  "description"       : metric.description,
@@ -303,24 +282,11 @@ class ReportGenerator:
 
             for sent in highlighted_sentences:
                 highlighted_data.append({"text"           : sent.text,
-                                         "ai_probability" : sent.ai_probability,
+                                         "synthetic_probability" : sent.synthetic_probability,
                                          "confidence"     : sent.confidence,
                                          "color_class"    : sent.color_class,
                                          "index"          : sent.index,
                                        })
-
-        # Attribution data
-        attribution_data = None
-        
-        if attribution_result:
-            attribution_data = {"predicted_model"     : attribution_result.predicted_model.value,
-                                "confidence"          : attribution_result.confidence,
-                                "model_probabilities" : attribution_result.model_probabilities,
-                                "reasoning"           : attribution_result.reasoning,
-                                "fingerprint_matches" : attribution_result.fingerprint_matches,
-                                "domain_used"         : attribution_result.domain_used.value,
-                                "metric_contributions": attribution_result.metric_contributions,
-                               }
         
         # Use detection results from dictionary
         ensemble_data        = detection_data.get("ensemble", {})
@@ -333,17 +299,17 @@ class ReportGenerator:
                                                          "format"       : "json",
                                                          "report_id"    : filename.replace('.json', ''),
                                                         },
-                                "overall_results"     : {"final_verdict"      : ensemble_data.get("final_verdict", "Unknown"),
-                                                         "ai_probability"     : ensemble_data.get("ai_probability", 0),
-                                                         "human_probability"  : ensemble_data.get("human_probability", 0),
-                                                         "mixed_probability"  : ensemble_data.get("mixed_probability", 0),
-                                                         "overall_confidence" : ensemble_data.get("overall_confidence", 0),
-                                                         "uncertainty_score"  : ensemble_data.get("uncertainty_score", 0),
-                                                         "consensus_level"    : ensemble_data.get("consensus_level", 0),
-                                                         "domain"             : analysis_data.get("domain", "general"),
-                                                         "domain_confidence"  : analysis_data.get("domain_confidence", 0),
-                                                         "text_length"        : analysis_data.get("text_length", 0),
-                                                         "sentence_count"     : analysis_data.get("sentence_count", 0),
+                                "overall_results"     : {"final_verdict"         : ensemble_data.get("final_verdict", "Unknown"),
+                                                         "synthetic_probability" : ensemble_data.get("synthetic_probability", 0),
+                                                         "authentic_probability" : ensemble_data.get("authentic_probability", 0),
+                                                         "hybrid_probability"     : ensemble_data.get("hybrid_probability", 0),
+                                                         "overall_confidence"    : ensemble_data.get("overall_confidence", 0),
+                                                         "uncertainty_score"     : ensemble_data.get("uncertainty_score", 0),
+                                                         "consensus_level"       : ensemble_data.get("consensus_level", 0),
+                                                         "domain"                : analysis_data.get("domain", "general"),
+                                                         "domain_confidence"     : analysis_data.get("domain_confidence", 0),
+                                                         "text_length"           : analysis_data.get("text_length", 0),
+                                                         "sentence_count"        : analysis_data.get("sentence_count", 0),
                                                         },
                                 "ensemble_analysis"   : {"method_used"     : "confidence_calibrated",
                                                          "metric_weights"  : ensemble_data.get("metric_contributions", {}),
@@ -362,7 +328,6 @@ class ReportGenerator:
                                                          "recommendations"        : reasoning.recommendations,
                                                         },
                                 "highlighted_text"    : highlighted_data,
-                                "model_attribution"   : attribution_data,
                                 "performance_metrics" : {"total_processing_time"  : performance_data.get("total_time", 0),
                                                          "metrics_execution_time" : performance_data.get("metrics_time", {}),
                                                          "warnings"               : detection_data.get("warnings", []),
@@ -384,8 +349,8 @@ class ReportGenerator:
         return output_path
     
 
-    def _generate_pdf_report(self, detection_data: Dict, detection_dict_full: Dict, reasoning: DetailedReasoning, detailed_metrics: List[DetailedMetric], 
-                            attribution_result: Optional[AttributionResult], highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
+    def _generate_pdf_report(self, detection_data: Dict, detection_dict_full: Dict, reasoning: DetailedReasoningResult, detailed_metrics: List[DetailedMetricResult], 
+                             highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
         """
         Generate PDF format report with detailed metrics
         """
@@ -570,8 +535,6 @@ class ReportGenerator:
                                            textColor  = GRAY_DARK,
                                            alignment  = TA_CENTER,
                                           ) 
-        
-        print (detection_dict_full.keys())
 
         # Use detection results from detection_data
         ensemble_data     = detection_data.get("ensemble", {})
@@ -585,23 +548,23 @@ class ReportGenerator:
         original_filename = file_info.get("filename", "Unknown")
         
         # Extract values - handle different data formats
-        ai_prob           = ensemble_data.get("ai_probability", 0) * 100      # Convert to percentage
-        human_prob        = ensemble_data.get("human_probability", 0) * 100   # Convert to percentage
-        mixed_prob        = ensemble_data.get("mixed_probability", 0) * 100   # Convert to percentage
-        confidence        = ensemble_data.get("overall_confidence", 0) * 100  # Convert to percentage
-        uncertainty       = ensemble_data.get("uncertainty_score", 0) * 100   # Convert to percentage
-        consensus         = ensemble_data.get("consensus_level", 0) * 100     # Convert to percentage
+        synthetic_prob    = ensemble_data.get("synthetic_probability", 0) * 100 # Convert to percentage
+        authentic_prob    = ensemble_data.get("authentic_probability", 0) * 100 # Convert to percentage
+        hybrid_prob       = ensemble_data.get("hybrid_probability", 0) * 100    # Convert to percentage
+        confidence        = ensemble_data.get("overall_confidence", 0) * 100    # Convert to percentage
+        uncertainty       = ensemble_data.get("uncertainty_score", 0) * 100     # Convert to percentage
+        consensus         = ensemble_data.get("consensus_level", 0) * 100       # Convert to percentage
         final_verdict     = ensemble_data.get("final_verdict", "Unknown")
         total_time        = performance_data.get("total_time", 0)
         
         # Determine colors based on verdict
-        if ("Human".lower() in final_verdict.lower()):
+        if ("Authentically-Written".lower() in final_verdict.lower()):
             verdict_color = SUCCESS_COLOR
 
-        elif ("AI".lower() in final_verdict.lower()):
+        elif ("Synthetically-Generated".lower() in final_verdict.lower()):
             verdict_color = DANGER_COLOR
         
-        elif ("Mixed".lower() in final_verdict.lower()):
+        elif ("Hybrid".lower() in final_verdict.lower()):
             verdict_color = WARNING_COLOR
         
         else:
@@ -617,7 +580,7 @@ class ReportGenerator:
                                       alignment  = TA_RIGHT,
                                      )
         
-        elements.append(Paragraph("AI DETECTION ANALYTICS", header_style))
+        elements.append(Paragraph("TEXT AUTHENTICATION ANALYTICS", header_style))
 
         elements.append(HRFlowable(width      = "100%", 
                                    thickness  = 1, 
@@ -627,7 +590,7 @@ class ReportGenerator:
                        )
         
         # Title and main sections
-        elements.append(Paragraph("AI Text Detection Analysis Report", title_style))
+        elements.append(Paragraph("Text Authentication Analysis Report", title_style))
         elements.append(Paragraph(f"Generated on {datetime.now().strftime('%B %d, %Y at %I:%M %p')}", subtitle_style))
         
         # Add original filename
@@ -645,8 +608,8 @@ class ReportGenerator:
                        )
         
         # Quick Stats Banner
-        stats_data  = [['Text Source', 'AI', 'HUMAN', 'MIXED'],
-                       ['Probability', f"{ai_prob:.1f}%", f"{human_prob:.1f}%", f"{mixed_prob:.1f}%"]
+        stats_data  = [['Classification', 'Synthetic', 'Authentic', 'Hybrid'],
+                       ['Probability', f"{synthetic_prob:.1f}%", f"{authentic_prob:.1f}%", f"{hybrid_prob:.1f}%"]
                       ]
         
         stats_table = Table(stats_data, colWidths = [1.5*inch, 1*inch, 1*inch, 1*inch])
@@ -673,7 +636,7 @@ class ReportGenerator:
         # Main Verdict Section
         elements.append(Paragraph("DETECTION VERDICT", section_style))
         
-        verdict_box_data = [[Paragraph(f"<font size=18 color='{verdict_color}'><b>{final_verdict.upper()}</b></font>", ParagraphStyle('VerdictText', alignment=TA_CENTER)),
+        verdict_box_data = [[Paragraph(f"<font size=10 color='{verdict_color}'><b>{final_verdict.upper()}</b></font>", ParagraphStyle('VerdictText', alignment=TA_CENTER)),
                              Paragraph(f"<font size=12>Confidence: <b>{confidence:.1f}%</b></font><br/>" 
                                        f"<font size=10>Uncertainty: {uncertainty:.1f}% | Consensus: {consensus:.1f}%</font>", 
                                        ParagraphStyle('VerdictDetails', alignment=TA_CENTER))
@@ -699,7 +662,7 @@ class ReportGenerator:
         elements.append(Paragraph("DETECTION REASONING", section_style))
         
         # Process summary text and convert to bullet points
-        summary_text = reasoning.summary if hasattr(reasoning, 'summary') else "No reasoning summary available."
+        summary_text  = reasoning.summary if hasattr(reasoning, 'summary') else "No reasoning summary available."
         
         # Fix extra spaces first
         summary_text  = ' '.join(summary_text.split())
@@ -906,71 +869,6 @@ class ReportGenerator:
         
         elements.append(PageBreak())
         
-        # PAGE 6: Model Attribution & Recommendations
-        # AI MODEL ATTRIBUTION
-        if attribution_result:
-            elements.append(Paragraph("AI MODEL ATTRIBUTION", section_style))
-            elements.append(Spacer(1, 0.1*inch))
-            
-            predicted_model        = getattr(attribution_result.predicted_model, 'value', str(attribution_result.predicted_model))
-            predicted_model        = predicted_model.replace("_", " ").title()
-            attribution_confidence = getattr(attribution_result, 'confidence', 0) * 100
-            domain_used            = getattr(attribution_result.domain_used, 'value', 'Unknown').upper()
-            
-            # Professional attribution table
-            attribution_data       = [[Paragraph("<b>Predicted Model</b>", bold_style), Paragraph(f"<font color='{INFO_COLOR}'><b>{predicted_model}</b></font>", bold_style)],
-                                      [Paragraph("<b>Attribution Confidence</b>", bold_style), Paragraph(f"<b>{attribution_confidence:.1f}%</b>", bold_style)],
-                                      [Paragraph("<b>Domain Used</b>", bold_style), Paragraph(f"<b>{domain_used}</b>", bold_style)]
-                                     ]
-            
-            attribution_table      = Table(attribution_data, colWidths = [2.5*inch, 4*inch])
-
-            attribution_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (0, -1), GRAY_LIGHT),
-                                                   ('FONTNAME', (0, 0), (0, -1), 'Helvetica-Bold'),
-                                                   ('FONTSIZE', (0, 0), (-1, -1), 11),
-                                                   ('BOTTOMPADDING', (0, 0), (-1, -1), 8),
-                                                   ('TOPPADDING', (0, 0), (-1, -1), 8),
-                                                   ('GRID', (0, 0), (-1, -1), 0.5, GRAY_MEDIUM),
-                                                   ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
-                                                 ])
-                                      )
-
-            elements.append(attribution_table)
-            elements.append(Spacer(1, 0.2*inch)) 
-            
-            # MODEL PROBABILITY DISTRIBUTION
-            model_probs = getattr(attribution_result, 'model_probabilities', {})
-            if (model_probs and (len(model_probs) > 0)):
-                elements.append(Paragraph("MODEL PROBABILITY DISTRIBUTION", subsection_style))
-                elements.append(Spacer(1, 0.05*inch))
-                
-                # Get top models 
-                sorted_models = sorted(model_probs.items(), key = lambda x: x[1], reverse = True)[:10] 
-                
-                prob_data     = [['LANGUAGE MODEL NAME', 'ATTRIBUTION PROBABILITY']]
-                
-                for model_name, probability in sorted_models:
-                    display_name = model_name.replace("_", " ").replace("-", " ").title()
-                    prob_data.append([Paragraph(display_name, bold_style), Paragraph(f"{probability:.1%}", bold_style)])
-                
-                # Table Columns Setup
-                prob_table = Table(prob_data, colWidths = [4*inch, 2.5*inch])
-
-                prob_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (-1, 0), INFO_COLOR),
-                                                ('TEXTCOLOR', (0, 0), (-1, 0), colors.white),
-                                                ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
-                                                ('ALIGN', (1, 0), (1, -1), 'RIGHT'),
-                                                ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
-                                                ('FONTSIZE', (0, 0), (-1, -1), 11),  
-                                                ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
-                                                ('TOPPADDING', (0, 0), (-1, -1), 6),
-                                                ('GRID', (0, 0), (-1, -1), 0.5, GRAY_MEDIUM),
-                                                ('BACKGROUND', (1, 1), (1, -1), GRAY_LIGHT),
-                                              ])
-                                   )
-
-                elements.append(prob_table)
-                elements.append(Spacer(1, 0.3*inch))
         
         # RECOMMENDATIONS
         if ((hasattr(reasoning, 'recommendations')) and reasoning.recommendations):
@@ -1014,12 +912,12 @@ class ReportGenerator:
         # Extract report ID from filename
         report_id   = filename.replace('.pdf', '')
         
-        footer_text = (f"Generated by AI Text Detector v1.0 | "
+        footer_text = (f"Generated by Text Authenticator v1.0 | "
                        f"Processing Time: {total_time:.2f}s | "
                        f"Report ID: {report_id}")
         
         elements.append(Paragraph(footer_text, footer_style))
-        elements.append(Paragraph("Confidential Analysis Report • © 2025 AI Detection Analytics", 
+        elements.append(Paragraph("Confidential Analysis Report • © 2025 Text Authentication Analytics", 
                         ParagraphStyle('Copyright', parent = footer_style, fontSize = 8, textColor = GRAY_MEDIUM)))
         
         # Build PDF
@@ -1043,11 +941,11 @@ class ReportGenerator:
         from reportlab.lib.enums import TA_LEFT
         
         # Determine metric color based on verdict
-        if (metric.verdict == "HUMAN"):
+        if (metric.verdict == "Authentic Text"):
             metric_color = SUCCESS_COLOR
             prob_color   = SUCCESS_COLOR
 
-        elif (metric.verdict == "AI"):
+        elif (metric.verdict == "Synthetic Text"):
             metric_color = DANGER_COLOR
             prob_color   = DANGER_COLOR
 
@@ -1062,7 +960,7 @@ class ReportGenerator:
         subsection_style    = ParagraphStyle('SubsectionStyle',
                                              parent      = ParagraphStyle('Normal'),
                                              fontName    = 'Helvetica-Bold',
-                                             fontSize    = 14,
+                                             fontSize    = 12,
                                              textColor   = PRIMARY_COLOR,
                                              spaceAfter  = 8,
                                              spaceBefore = 16,
@@ -1075,7 +973,7 @@ class ReportGenerator:
         
         # Key metrics in a clean table
         key_metrics_data  = [[Paragraph("<b>Verdict</b>", bold_style), Paragraph(f"<font color='{metric_color}'><b>{metric.verdict}</b></font>", bold_style), Paragraph("<b>Weight</b>", bold_style), Paragraph(f"<b>{metric.weight:.1f}%</b>", bold_style)],
-                             [Paragraph("<b>AI Probability</b>", bold_style), Paragraph(f"<font color='{prob_color}'><b>{metric.ai_probability:.1f}%</b></font>", bold_style), Paragraph("<b>Confidence</b>", bold_style), Paragraph(f"<b>{metric.confidence:.1f}%</b>", bold_style)]
+                             [Paragraph("<b>Synthetic Probability</b>", bold_style), Paragraph(f"<font color='{prob_color}'><b>{metric.synthetic_probability:.1f}%</b></font>", bold_style), Paragraph("<b>Confidence</b>", bold_style), Paragraph(f"<b>{metric.confidence:.1f}%</b>", bold_style)]
                             ]
         
         key_metrics_table = Table(key_metrics_data, colWidths = [1.5*inch, 1.5*inch, 1.5*inch, 1.5*inch])
@@ -1095,7 +993,7 @@ class ReportGenerator:
         # Detailed metrics in a compact table
         if metric.detailed_metrics and len(metric.detailed_metrics) > 0:
             # Create table with all metrics
-            detailed_data = []
+            detailed_data = list()
             
             # Sort metrics alphabetically
             sorted_items  = sorted(metric.detailed_metrics.items())
@@ -1180,6 +1078,4 @@ class ReportGenerator:
 
 
 # Export
-__all__ = ["ReportGenerator", 
-           "DetailedMetric",
-          ]
+__all__ = ["ReportGenerator"]

run.sh

@@ -1,56 +0,0 @@
-#!/bin/bash
-
-echo "Starting Text Auth AI Detection System..."
-
-# Check if Conda is installed
-if ! command -v conda &> /dev/null; then
-    echo "Conda is required but not installed. Please install Miniconda or Anaconda."
-    exit 1
-fi
-
-# Check if Python is installed and is version 3.10+
-if ! command -v python3 &> /dev/null; then
-    echo "Python 3 is required but not installed. Please install Python 3.10 or higher."
-    exit 1
-fi
-python3 -c "import sys; assert sys.version_info >= (3.10,), 'Python 3.10 or higher is required.'" || exit 1
-
-# Conda environment name
-CONDA_ENV_NAME="text_auth_env"
-
-# Check if conda environment exists, create if not
-if ! conda info --envs | grep -q "$CONDA_ENV_NAME"; then
-    echo "Creating Conda environment '$CONDA_ENV_NAME' with Python 3.10..."
-    conda create -n "$CONDA_ENV_NAME" python=3.10 -y
-fi
-
-# Activate conda environment
-echo "Activating Conda environment '$CONDA_ENV_NAME'..."
-source $(conda info --base)/etc/profile.d/conda.sh
-conda activate "$CONDA_ENV_NAME"
-
-# Install requirements
-echo "Installing dependencies..."
-pip install -r requirements.txt || { echo "Failed to install dependencies."; exit 1; }
-
-# Create necessary directories
-mkdir -p logs
-mkdir -p data/uploads
-mkdir -p data/reports
-mkdir -p models/cache
-
-# Set environment variables
-export PYTHONPATH=$PYTHONPATH:$(pwd)
-export LOG_LEVEL=${LOG_LEVEL:-INFO}
-export MODEL_CACHE_DIR=$(pwd)/models/cache
-
-# Start the FastAPI application
-echo "Starting FastAPI server..."
-echo "Access the application at: http://localhost:8000"
-echo "API documentation at: http://localhost:8000/docs"
-echo "Press Ctrl+C to stop the server"
-
-# Deactivate conda environment on exit
-trap 'conda deactivate' EXIT
-
-uvicorn app:app --reload --host 0.0.0.0 --port 8000

detector/ensemble.py → services/ensemble_classifier.py

@@ -1,64 +1,19 @@
 # DEPENDENCIES
 import numpy as np
-from typing import Any
 from typing import List
 from typing import Dict 
 from loguru import logger
-from typing import Optional
-from dataclasses import dataclass
-from config.settings import settings
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
-from sklearn.ensemble import RandomForestClassifier
+from config.enums import Domain
+from config.schemas import MetricResult
+from config.schemas import EnsembleResult
+from config.constants import metrics_ensemble_params
 from config.threshold_config import get_threshold_for_domain
 from config.threshold_config import get_active_metric_weights
 
 
-@dataclass
-class EnsembleResult:
-    """
-    Result from ensemble classification
-    """
-    final_verdict      : str  # "AI-Generated", "Human-Written", or "Mixed"
-    ai_probability     : float
-    human_probability  : float
-    mixed_probability  : float
-    overall_confidence : float
-    domain             : Domain
-    metric_results     : Dict[str, MetricResult]
-    metric_weights     : Dict[str, float]
-    weighted_scores    : Dict[str, float]
-    reasoning          : List[str]
-    uncertainty_score  : float
-    consensus_level    : float
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for JSON serialization
-        """
-        return {"final_verdict"        : self.final_verdict,
-                "ai_probability"       : round(self.ai_probability, 4),
-                "human_probability"    : round(self.human_probability, 4),
-                "mixed_probability"    : round(self.mixed_probability, 4),
-                "overall_confidence"   : round(self.overall_confidence, 4),
-                "domain"               : self.domain.value,
-                "uncertainty_score"    : round(self.uncertainty_score, 4),
-                "consensus_level"      : round(self.consensus_level, 4),
-                "metric_contributions" : {name: {"weight"         : round(self.metric_weights.get(name, 0.0), 4),
-                                                 "weighted_score" : round(self.weighted_scores.get(name, 0.0), 4),
-                                                 "ai_prob"        : round(result.ai_probability, 4),
-                                                 "confidence"     : round(result.confidence, 4),
-                                                }
-                                                for name, result in self.metric_results.items()
-                                        },
-                "reasoning"            : self.reasoning,
-               }
-
-
 class EnsembleClassifier:
     """
-    Eensemble classifier with multiple aggregation strategies
+    Ensemble classifier with multiple aggregation strategies
     
     Features:
     - Domain-aware dynamic weighting
@@ -66,29 +21,26 @@ class EnsembleClassifier:
     - Uncertainty quantification
     - Consensus analysis
     - Fallback strategies
-    - Feature-based ML ensemble (optional)
     """
-    def __init__(self, primary_method: str = "confidence_calibrated", fallback_method: str = "domain_weighted", use_ml_ensemble: bool = False, min_metrics_required: int = 3):
+    def __init__(self, primary_method: str = "confidence_calibrated", fallback_method: str = "domain_weighted", min_metrics_required: int = None, execution_mode = "parallel"):
         """
         Initialize advanced ensemble classifier
         
         Arguments:
         ----------
-            primary_method       : Primary aggregation method : "confidence_calibrated", "domain_adaptive", "consensus_based", "ml_ensemble"
+            primary_method       : Primary aggregation method : "confidence_calibrated", "consensus_based"
             
             fallback_method      : Fallback method if primary fails : "domain_weighted", "confidence_weighted", "simple_average"
             
-            use_ml_ensemble      : Use RandomForest for final aggregation (requires training)
-            
-            min_metrics_required : Minimum number of valid metrics required
+            min_metrics_required : Minimum number of valid metrics required (overrides default)
         """
         self.primary_method       = primary_method
         self.fallback_method      = fallback_method
-        self.use_ml_ensemble      = use_ml_ensemble
-        self.min_metrics_required = min_metrics_required
-        self.ml_model             = None
+        self.min_metrics_required = min_metrics_required or metrics_ensemble_params.MIN_METRICS_REQUIRED
+        self.params               = metrics_ensemble_params
+        self.execution_mode       = execution_mode
         
-        logger.info(f"AdvancedEnsembleClassifier initialized (primary={primary_method}, fallback={fallback_method}, ml_ensemble={use_ml_ensemble})")
+        logger.info(f"EnsembleClassifier initialized (primary={primary_method}, fallback={fallback_method})")
     
 
     def predict(self, metric_results: Dict[str, MetricResult], domain: Domain = Domain.GENERAL) -> EnsembleResult:
@@ -106,8 +58,8 @@ class EnsembleClassifier:
             { EnsembleResult }       : EnsembleResult object with final prediction
         """
         try:
-            # Filter and validate metrics
-            valid_results, validation_info = self._validate_metrics(metric_results)
+            # Filter out metrics with errors
+            valid_results = self._filter_valid_metrics(results = metric_results)
             
             if (len(valid_results) < self.min_metrics_required):
                 logger.warning(f"Insufficient valid metrics: {len(valid_results)}/{self.min_metrics_required}")
@@ -117,11 +69,11 @@ class EnsembleClassifier:
             enabled_metrics    = {name: True for name in valid_results.keys()}
             base_weights       = get_active_metric_weights(domain, enabled_metrics)
             
-            # Try primary aggregation method : Initialize in case all methods fail unexpectedly
+            # Try primary aggregation method
             calculated_weights = dict()
-            aggregated         = {"ai_probability"    : 0.5, 
-                                  "human_probability" : 0.5, 
-                                  "mixed_probability" : 0.0,
+            aggregated         = {"synthetic_probability"    : self.params.DEFAULT_SYNTHETIC_PROB, 
+                                  "authentic_probability"    : self.params.DEFAULT_AUTHENTIC_PROB, 
+                                  "hybrid_probability"       : self.params.DEFAULT_HYBRID_PROB,
                                  }
 
             try:
@@ -131,29 +83,15 @@ class EnsembleClassifier:
                                                                                              domain       = domain,
                                                                                             )
                 
-                elif (self.primary_method == "domain_adaptive"):
-                    aggregated, calculated_weights = self._domain_adaptive_aggregation(results      = valid_results, 
-                                                                                       base_weights = base_weights, 
-                                                                                       domain       = domain,
-                                                                                      )
-                
                 elif (self.primary_method == "consensus_based"):
                     aggregated, calculated_weights = self._consensus_based_aggregation(results      = valid_results, 
                                                                                        base_weights = base_weights,
-                                                                                       domain       = domain,
                                                                                       )
                 
-                elif ((self.primary_method == "ml_ensemble") and self.use_ml_ensemble):
-                    aggregated, calculated_weights = self._ml_ensemble_aggregation(results      = valid_results, 
-                                                                                   base_weights = base_weights,
-                                                                                   domain       = domain,
-                                                                                  )
-                
                 else:
                     # Fallback to domain weighted
                     aggregated, calculated_weights = self._domain_weighted_aggregation(results      = valid_results, 
                                                                                        base_weights = base_weights,
-                                                                                       domain       = domain,
                                                                                       )
             
             except Exception as e:
@@ -165,20 +103,18 @@ class EnsembleClassifier:
             # Start with the calculated weights (from valid_results)
             final_metric_weights = calculated_weights.copy() 
 
-            # Iterate through the *original* metric_results input to the ensemble
+            # Assign zero weight to any original metrics that weren't included in valid_results
             for original_metric_name in metric_results.keys():
-                # If a metric from the original input wasn't included in calculated_weights :assign it a weight of 0.0.
-                if original_metric_name not in final_metric_weights:
+                if (original_metric_name not in final_metric_weights):
                     final_metric_weights[original_metric_name] = 0.0
 
-            # Calculate advanced metrics using the CALCULATED weights (from valid_results), not the final ones
-            overall_confidence   = self._calculate_advanced_confidence(results    = valid_results, 
-                                                                       weights    = calculated_weights, 
-                                                                       aggregated = aggregated,
-                                                                      )
+            # Calculate advanced metrics
+            overall_confidence   = self._calculate_confidence(results    = valid_results, 
+                                                              weights    = calculated_weights, 
+                                                              aggregated = aggregated,
+                                                             )
 
             uncertainty_score    = self._calculate_uncertainty(results    = valid_results, 
-                                                               weights    = calculated_weights, 
                                                                aggregated = aggregated,
                                                               )
 
@@ -191,65 +127,53 @@ class EnsembleClassifier:
                                                                   uncertainty    = uncertainty_score,
                                                                  )
             
-            # Generate detailed reasoning using the CALCULATED weights
-            reasoning            = self._generate_detailed_reasoning(results     = valid_results, 
-                                                                     weights     = calculated_weights,
-                                                                     aggregated  = aggregated, 
-                                                                     verdict     = final_verdict, 
-                                                                     uncertainty = uncertainty_score, 
-                                                                     consensus   = consensus_level,
-                                                                    )
+            # Generate reasoning
+            reasoning            = self._generate_reasoning(results     = valid_results, 
+                                                           weights     = calculated_weights,
+                                                           aggregated  = aggregated, 
+                                                           verdict     = final_verdict, 
+                                                           uncertainty = uncertainty_score, 
+                                                           consensus   = consensus_level,
+                                                          )
             
-            # Calculate weighted scores based on the CALCULATED weights (from valid_results)
-            weighted_scores      = {name: result.ai_probability * calculated_weights.get(name, 0.0) for name, result in valid_results.items()}
+            # Calculate weighted scores
+            weighted_scores      = {name: result.synthetic_probability * calculated_weights.get(name, 0.0) 
+                                   for name, result in valid_results.items()}
             
-            return EnsembleResult(final_verdict      = final_verdict,
-                                  ai_probability     = aggregated["ai_probability"],
-                                  human_probability  = aggregated["human_probability"],
-                                  mixed_probability  = aggregated["mixed_probability"],
-                                  overall_confidence = overall_confidence,
-                                  domain             = domain,
-                                  metric_results     = metric_results,
-                                  metric_weights     = final_metric_weights,
-                                  weighted_scores    = weighted_scores,
-                                  reasoning          = reasoning,
-                                  uncertainty_score  = uncertainty_score,
-                                  consensus_level    = consensus_level,
+            return EnsembleResult(final_verdict         = final_verdict,
+                                  synthetic_probability = aggregated["synthetic_probability"],
+                                  authentic_probability = aggregated["authentic_probability"],
+                                  hybrid_probability    = aggregated["hybrid_probability"],
+                                  overall_confidence    = overall_confidence,
+                                  domain                = domain,
+                                  metric_results        = metric_results,
+                                  metric_weights        = final_metric_weights,
+                                  weighted_scores       = weighted_scores,
+                                  reasoning             = reasoning,
+                                  uncertainty_score     = uncertainty_score,
+                                  consensus_level       = consensus_level,
+                                  execution_mode        = self.execution_mode,
                                  )
             
         except Exception as e:
-            logger.error(f"Error in advanced ensemble prediction: {e}")
+            logger.error(f"Error in ensemble prediction: {e}")
             return self._create_fallback_result(domain, metric_results, str(e))
 
     
-    def _validate_metrics(self, results: Dict[str, MetricResult]) -> tuple:
+    def _filter_valid_metrics(self, results: Dict[str, MetricResult]) -> Dict[str, MetricResult]:
         """
-        Validate metrics and return quality information
+        Filter out failed metrics (error != None).
+        Confidence is handled during aggregation, not validation.
         """
-        valid_results   = dict()
-        validation_info = {'failed_metrics'          : [],
-                           'low_confidence_metrics'  : [],
-                           'high_confidence_metrics' : [],
-                          }
+        valid_results = dict()
         
         for name, result in results.items():
             if result.error is not None:
-                validation_info['failed_metrics'].append(name)
                 continue
             
-            if (result.confidence < 0.3):
-                validation_info['low_confidence_metrics'].append(name)
-                # Still include but with lower weight consideration
-                valid_results[name] = result
-            
-            elif (result.confidence > 0.7):
-                validation_info['high_confidence_metrics'].append(name)
-                valid_results[name] = result
-            
-            else:
-                valid_results[name] = result
+            valid_results[name] = result
         
-        return valid_results, validation_info
+        return valid_results
     
 
     def _confidence_calibrated_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float], domain: Domain) -> tuple:
@@ -266,10 +190,7 @@ class EnsembleClassifier:
             confidence_weights[name] = base_weight * confidence_factor
         
         # Normalize weights
-        total_weight = sum(confidence_weights.values())
-
-        if (total_weight > 0):
-            confidence_weights = {name: w / total_weight for name, w in confidence_weights.items()}
+        confidence_weights = self._normalize_weights(confidence_weights)
         
         # Domain-specific calibration
         domain_calibration = self._get_domain_calibration(domain = domain)
@@ -281,34 +202,16 @@ class EnsembleClassifier:
         return self._weighted_aggregation(calibrated_results, confidence_weights), confidence_weights
     
 
-    def _domain_adaptive_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float], domain: Domain) -> tuple:
-        """
-        Domain-adaptive aggregation considering metric performance per domain
-        """
-        # Get domain-specific performance weights
-        domain_weights = self._get_domain_performance_weights(domain, list(results.keys()))
-        
-        # Combine with base weights
-        combined_weights = dict()
-        for name in results.keys():
-            domain_weight          = domain_weights.get(name, 1.0)
-            base_weight            = base_weights.get(name, 0.0)
-            combined_weights[name] = base_weight * domain_weight
-        
-        # Normalize
-        total_weight = sum(combined_weights.values())
-        if (total_weight > 0):
-            combined_weights = {name: w / total_weight for name, w in combined_weights.items()}
-        
-        return self._weighted_aggregation(results, combined_weights), combined_weights
-    
-
     def _consensus_based_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float]) -> tuple:
         """
         Consensus-based aggregation that rewards metric agreement
         """
         # Calculate consensus scores
-        consensus_weights = self._calculate_consensus_weights(results, base_weights)
+        consensus_weights = self._calculate_consensus_weights(results      = results, 
+                                                              base_weights = base_weights,
+                                                             )
+        
+        consensus_weights = self._normalize_weights(consensus_weights)
         
         aggregations      = self._weighted_aggregation(results = results, 
                                                        weights = consensus_weights,
@@ -316,42 +219,6 @@ class EnsembleClassifier:
         return aggregations, consensus_weights
     
 
-    def _ml_ensemble_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float]) -> tuple:
-        """
-        Machine learning-based ensemble aggregation
-        """
-        if self.ml_model is None:
-            logger.warning("ML model not available, falling back to weighted average")
-            return self._weighted_aggregation(results, base_weights), base_weights
-        
-        try:
-            # Extract features from metric results
-            features   = self._extract_ml_features(results = results)
-            
-            # Predict using ML model
-            prediction = self.ml_model.predict_proba([features])[0]
-            
-            # For now, assume binary classification [human_prob, ai_prob]
-            if (len(prediction) == 2):
-                ai_prob, human_prob = prediction[1], prediction[0]
-                mixed_prob          = 0.0
-
-            else:
-                # Multi-class - adjust accordingly
-                ai_prob, human_prob, mixed_prob = prediction
-            
-            aggregated = {"ai_probability"    : ai_prob,
-                          "human_probability" : human_prob,
-                          "mixed_probability" : mixed_prob,
-                         }
-            
-            return aggregated, base_weights
-            
-        except Exception as e:
-            logger.warning(f"ML ensemble failed: {e}, using fallback")
-            return self._weighted_aggregation(results, base_weights), base_weights
-    
-
     def _domain_weighted_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float]) -> tuple:
         """
         Simple domain-weighted aggregation (fallback method)
@@ -364,56 +231,56 @@ class EnsembleClassifier:
         Apply fallback aggregation method
         """
         if (self.fallback_method == "confidence_weighted"):
-            return self._confidence_weighted_aggregation(results), base_weights
+            return self._confidence_weighted_aggregation(results = results), base_weights
         
         elif (self.fallback_method == "simple_average"):
-            return self._simple_average_aggregation(results), base_weights
+            return self._simple_average_aggregation(results = results), base_weights
 
         else:
-            return self._domain_weighted_aggregation(results, base_weights), base_weights
+            return self._domain_weighted_aggregation(results = results, base_weights = base_weights), base_weights
     
 
     def _weighted_aggregation(self, results: Dict[str, MetricResult], weights: Dict[str, float]) -> Dict[str, float]:
         """
         Core weighted aggregation logic
         """
-        ai_scores    = list()
-        human_scores = list()
-        mixed_scores = list()
-        total_weight = 0.0
+        synthetic_scores = list()
+        authentic_scores = list()
+        hybrid_scores    = list()
+        total_weight     = 0.0
         
         for name, result in results.items():
             weight = weights.get(name, 0.0)
             
             if (weight > 0):
-                ai_scores.append(result.ai_probability * weight)
-                human_scores.append(result.human_probability * weight)
-                mixed_scores.append(result.mixed_probability * weight)
+                synthetic_scores.append(result.synthetic_probability * weight)
+                authentic_scores.append(result.authentic_probability * weight)
+                hybrid_scores.append(result.hybrid_probability * weight)
                 
                 total_weight += weight
         
         if (total_weight == 0):
-            return {"ai_probability"    : 0.5, 
-                    "human_probability" : 0.5, 
-                    "mixed_probability" : 0.0,
+            return {"synthetic_probability" : self.params.DEFAULT_SYNTHETIC_PROB, 
+                    "authentic_probability" : self.params.DEFAULT_AUTHENTIC_PROB, 
+                    "hybrid_probability"    : self.params.DEFAULT_HYBRID_PROB,
                    }
         
         # Calculate weighted averages
-        ai_prob    = sum(ai_scores) / total_weight
-        human_prob = sum(human_scores) / total_weight
-        mixed_prob = sum(mixed_scores) / total_weight
+        synthetic_prob = sum(synthetic_scores) / total_weight
+        authentic_prob = sum(authentic_scores) / total_weight
+        hybrid_prob    = sum(hybrid_scores) / total_weight
         
-        # Normalize
-        total     = ai_prob + human_prob + mixed_prob
+        # Normalize probabilities to sum to 1.0
+        total          = synthetic_prob + authentic_prob + hybrid_prob
         
         if (total > 0):
-            ai_prob    /= total
-            human_prob /= total
-            mixed_prob /= total
+            synthetic_prob /= total
+            authentic_prob /= total
+            hybrid_prob    /= total
         
-        return {"ai_probability"    : ai_prob, 
-                "human_probability" : human_prob,
-                "mixed_probability" : mixed_prob,
+        return {"synthetic_probability" : synthetic_prob, 
+                "authentic_probability" : authentic_prob,
+                "hybrid_probability"    : hybrid_prob,
                }
     
 
@@ -421,7 +288,9 @@ class EnsembleClassifier:
         """
         Confidence-weighted aggregation
         """
-        return self._weighted_aggregation(results, {name: result.confidence for name, result in results.items()})
+        weights = {name: result.confidence for name, result in results.items()}
+        weights = self._normalize_weights(weights)
+        return self._weighted_aggregation(results, weights)
     
 
     def _simple_average_aggregation(self, results: Dict[str, MetricResult]) -> Dict[str, float]:
@@ -435,8 +304,8 @@ class EnsembleClassifier:
         """
         Non-linear confidence adjustment using sigmoid
         """
-        # Sigmoid that emphasizes differences around 0.5 confidence
-        return 1.0 / (1.0 + np.exp(-10.0 * (confidence - 0.5)))
+        # Sigmoid that emphasizes differences around the center
+        return 1.0 / (1.0 + np.exp(-self.params.SIGMOID_CONFIDENCE_SCALE * (confidence - self.params.SIGMOID_CENTER)))
     
 
     def _get_domain_calibration(self, domain: Domain) -> Dict[str, float]:
@@ -444,7 +313,7 @@ class EnsembleClassifier:
         Get domain-specific calibration factors
         """
         # This would typically come from validation data
-        # For now, return neutral calibration : FUTURE WQORK
+        # For now, return neutral calibration
         return {}
     
 
@@ -453,233 +322,86 @@ class EnsembleClassifier:
         Calibrate probabilities based on domain performance
         """
         calibrated = dict()
+
         for name, result in results.items():
-            cal_factor       = calibration.get(name, 1.0)
-            # Simple calibration - could be more sophisticated
-            new_ai_prob      = min(1.0, max(0.0, result.ai_probability * cal_factor))
-            calibrated[name] = MetricResult(metric_name       = result.metric_name,
-                                            ai_probability    = new_ai_prob,
-                                            human_probability = 1.0 - new_ai_prob,  # Simplified
-                                            mixed_probability = result.mixed_probability,
-                                            confidence        = result.confidence,
-                                            details           = result.details
-                                           )
+            cal_factor         = calibration.get(name, 1.0)
+            # Simple calibration
+            new_synthetic_prob = min(1.0, max(0.0, result.synthetic_probability * cal_factor))
+
+            calibrated[name]   = MetricResult(metric_name           = result.metric_name,
+                                              synthetic_probability = new_synthetic_prob,
+                                              authentic_probability = 1.0 - new_synthetic_prob,
+                                              hybrid_probability    = result.hybrid_probability,
+                                              confidence            = result.confidence,
+                                              details               = result.details
+                                             )
         return calibrated
     
 
-    def _get_domain_performance_weights(self, domain: Domain, metric_names: List[str]) -> Dict[str, float]:
-        """
-        Get domain-specific performance weights (would come from validation data)
-        """
-        # Placeholder - in practice, this would be based on historical performance per domain : FUTURE WORK
-        performance_weights = {'structural'                   : 1.0, 
-                               'entropy'                      : 1.0, 
-                               'semantic_analysis'            : 1.0,
-                               'linguistic'                   : 1.0, 
-                               'perplexity'                   : 1.0, 
-                               'multi_perturbation_stability' : 1.0,
-                              }
-        
-        # Domain-specific adjustments for all 16 domains
-        domain_adjustments  = {Domain.GENERAL       : {'structural'                   : 1.0,
-                                                       'perplexity'                   : 1.0,
-                                                       'entropy'                      : 1.0,
-                                                       'semantic_analysis'            : 1.0,
-                                                       'linguistic'                   : 1.0,
-                                                       'multi_perturbation_stability' : 1.0,
-                                                      },
-                               Domain.ACADEMIC      : {'structural'                   : 1.2, 
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.3, 
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.CREATIVE      : {'structural'                   : 0.9,
-                                                       'perplexity'                   : 1.1,
-                                                       'entropy'                      : 1.2, 
-                                                       'semantic_analysis'            : 1.0,
-                                                       'linguistic'                   : 1.1,
-                                                       'multi_perturbation_stability' : 0.9,
-                                                      },
-                               Domain.AI_ML         : {'structural'                   : 1.2,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.SOFTWARE_DEV  : {'structural'                   : 1.2,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.TECHNICAL_DOC : {'structural'                   : 1.3, 
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.2,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.ENGINEERING   : {'structural'                   : 1.2,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.SCIENCE       : {'structural'                   : 1.2,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.BUSINESS      : {'structural'                   : 1.1,
-                                                       'perplexity'                   : 1.2,
-                                                       'entropy'                      : 1.0,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.1,
-                                                       'multi_perturbation_stability' : 0.9,
-                                                      },
-                               Domain.LEGAL         : {'structural'                   : 1.3,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.2,
-                                                       'linguistic'                   : 1.3,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.MEDICAL       : {'structural'                   : 1.2,
-                                                       'perplexity'                   : 1.3,
-                                                       'entropy'                      : 0.9,
-                                                       'semantic_analysis'            : 1.2,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.JOURNALISM    : {'structural'                   : 1.1,
-                                                       'perplexity'                   : 1.2,
-                                                       'entropy'                      : 1.0,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.1,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.MARKETING     : {'structural'                   : 1.0,
-                                                       'perplexity'                   : 1.1,
-                                                       'entropy'                      : 1.1,
-                                                       'semantic_analysis'            : 1.0,
-                                                       'linguistic'                   : 1.2,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.SOCIAL_MEDIA  : {'structural'                   : 0.8,
-                                                       'perplexity'                   : 1.0,
-                                                       'entropy'                      : 1.3, 
-                                                       'semantic_analysis'            : 0.9,
-                                                       'linguistic'                   : 0.7,
-                                                       'multi_perturbation_stability' : 0.9,
-                                                      },
-                               Domain.BLOG_PERSONAL : {'structural'                   : 0.9,
-                                                       'perplexity'                   : 1.1,
-                                                       'entropy'                      : 1.2,
-                                                       'semantic_analysis'            : 1.0,
-                                                       'linguistic'                   : 1.0,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                               Domain.TUTORIAL      : {'structural'                   : 1.1,
-                                                       'perplexity'                   : 1.2,
-                                                       'entropy'                      : 1.0,
-                                                       'semantic_analysis'            : 1.1,
-                                                       'linguistic'                   : 1.1,
-                                                       'multi_perturbation_stability' : 0.8,
-                                                      },
-                              }
-        
-        adjustments         = domain_adjustments.get(domain, {})
-
-        return {name: performance_weights.get(name, 1.0) * adjustments.get(name, 1.0) for name in metric_names}
-    
-
     def _calculate_consensus_weights(self, results: Dict[str, MetricResult], base_weights: Dict[str, float]) -> Dict[str, float]:
         """
         Calculate weights based on metric consensus
         """
-        # Calculate average AI probability
-        avg_ai_prob       = np.mean([r.ai_probability for r in results.values()])
+        # Calculate average synthetic probability
+        avg_synthetic_prob = np.mean([r.synthetic_probability for r in results.values()])
         
-        consensus_weights = dict()
+        consensus_weights  = dict()
 
         for name, result in results.items():
             base_weight             = base_weights.get(name, 0.0)
             # Reward metrics that agree with consensus
-            agreement               = 1.0 - abs(result.ai_probability - avg_ai_prob)
+            agreement               = 1.0 - abs(result.synthetic_probability - avg_synthetic_prob)
             consensus_weights[name] = base_weight * (0.5 + 0.5 * agreement)  # 0.5-1.0 range
         
-        # Normalize
-        total_weight = sum(consensus_weights.values())
-        if (total_weight > 0):
-            consensus_weights = {name: w / total_weight for name, w in consensus_weights.items()}
-        
         return consensus_weights
     
 
-    def _extract_ml_features(self, results: Dict[str, MetricResult]) -> List[float]:
-        """
-        Extract features for ML ensemble
-        """
-        features = list()
-        for name in sorted(results.keys()):  # Ensure consistent order
-            result = results[name]
-            features.extend([result.ai_probability,
-                             result.human_probability,
-                             result.mixed_probability,
-                             result.confidence
-                           ])
-
-        return features
-    
-
-    def _calculate_advanced_confidence(self, results: Dict[str, MetricResult], weights: Dict[str, float], aggregated: Dict[str, float]) -> float:
+    def _calculate_confidence(self, results: Dict[str, MetricResult], weights: Dict[str, float], aggregated: Dict[str, float]) -> float:
         """
-        Calculate advanced confidence considering multiple factors
+        Calculate confidence considering multiple factors
         """
         # Base confidence from metric confidences
         base_confidence         = sum(result.confidence * weights.get(name, 0.0) for name, result in results.items())
         
         # Agreement factor
-        ai_probs                = [r.ai_probability for r in results.values()]
-        agreement               = 1.0 - min(1.0, np.std(ai_probs) * 2.0)  # 0-1 scale
+        synthetic_probs         = [r.synthetic_probability for r in results.values()]
+        agreement               = 1.0 - min(1.0, np.std(synthetic_probs) * self.params.CONSENSUS_STD_SCALING)
         
         # Certainty factor (how far from 0.5)
-        certainty               = 1.0 - 2.0 * abs(aggregated["ai_probability"] - 0.5)
+        certainty               = 1.0 - 2.0 * abs(aggregated["synthetic_probability"] - 0.5)
         
         # Metric quality factor
-        high_confidence_metrics = sum(1 for r in results.values() if r.confidence > 0.7)
+        high_confidence_metrics = sum(1 for r in results.values() if r.confidence > self.params.HIGH_CONFIDENCE_THRESHOLD)
         quality_factor          = high_confidence_metrics / len(results) if results else 0.0
         
         # Combined confidence
-        confidence              = (base_confidence * 0.4 + agreement * 0.3 + certainty * 0.2 + quality_factor * 0.1)
+        confidence              = (base_confidence * self.params.CONFIDENCE_WEIGHT_BASE + 
+                                   agreement * self.params.CONFIDENCE_WEIGHT_AGREEMENT + 
+                                   certainty * self.params.CONFIDENCE_WEIGHT_CERTAINTY + 
+                                   quality_factor * self.params.CONFIDENCE_WEIGHT_QUALITY)
         
         return max(0.0, min(1.0, confidence))
     
 
-    def _calculate_uncertainty(self, results: Dict[str, MetricResult], weights: Dict[str, float], aggregated: Dict[str, float]) -> float:
+    def _calculate_uncertainty(self, results: Dict[str, MetricResult], aggregated: Dict[str, float]) -> float:
         """
         Calculate uncertainty score
         """
         # Variance in predictions
-        ai_probs               = [r.ai_probability for r in results.values()]
-        variance_uncertainty   = np.var(ai_probs) if len(ai_probs) > 1 else 0.0
+        synthetic_probs        = [r.synthetic_probability for r in results.values()]
+        variance_uncertainty   = np.var(synthetic_probs) if len(synthetic_probs) > 1 else 0.0
         
         # Confidence uncertainty
         avg_confidence         = np.mean([r.confidence for r in results.values()])
         confidence_uncertainty = 1.0 - avg_confidence
         
         # Decision uncertainty (how close to 0.5)
-        decision_uncertainty   = 1.0 - 2.0 * abs(aggregated["ai_probability"] - 0.5)
+        decision_uncertainty   = 1.0 - 2.0 * abs(aggregated["synthetic_probability"] - 0.5)
         
         # Combined uncertainty
-        uncertainty            = (variance_uncertainty * 0.4 + confidence_uncertainty * 0.3 + decision_uncertainty * 0.3)
+        uncertainty            = (variance_uncertainty * self.params.UNCERTAINTY_WEIGHT_VARIANCE + 
+                                  confidence_uncertainty * self.params.UNCERTAINTY_WEIGHT_CONFIDENCE + 
+                                  decision_uncertainty * self.params.UNCERTAINTY_WEIGHT_DECISION)
         
         return max(0.0, min(1.0, uncertainty))
     
@@ -692,11 +414,11 @@ class EnsembleClassifier:
             # Perfect consensus with only one metric
             return 1.0  
         
-        ai_probs  = [r.ai_probability for r in results.values()]
-        std_dev   = np.std(ai_probs)
+        synthetic_probs  = [r.synthetic_probability for r in results.values()]
+        std_dev          = np.std(synthetic_probs)
         
         # Convert to consensus level (1.0 = perfect consensus, 0.0 = no consensus)
-        consensus = 1.0 - min(1.0, std_dev * 2.0)
+        consensus        = 1.0 - min(1.0, std_dev * self.params.CONSENSUS_STD_SCALING)
         
         return consensus
     
@@ -705,42 +427,43 @@ class EnsembleClassifier:
         """
         Apply adaptive threshold considering uncertainty
         """
-        ai_prob            = aggregated.get("ai_probability", 0.5)
-        mixed_prob         = aggregated.get("mixed_probability", 0.0)
+        synthetic_prob      = aggregated.get("synthetic_probability", self.params.DEFAULT_SYNTHETIC_PROB)
+        hybrid_prob         = aggregated.get("hybrid_probability", self.params.DEFAULT_HYBRID_PROB)
         
         # Adjust threshold based on uncertainty : Higher uncertainty requires more confidence
-        adjusted_threshold = base_threshold + (uncertainty * 0.1) 
+        adjusted_threshold = base_threshold + (uncertainty * self.params.UNCERTAINTY_THRESHOLD_ADJUSTMENT) 
         
-        # Check for mixed content
-        if ((mixed_prob > 0.25) or ((uncertainty > 0.6) and (0.3 < ai_prob < 0.7))):
-            return "Mixed (AI + Human)"
+        # Check for hybrid content
+        # Case 1: Explicit hybrid probability from metrics
+        # Case 2: High uncertainty + ambiguous synthetic score
+        if ((hybrid_prob > self.params.HYBRID_PROB_THRESHOLD) or ((uncertainty > self.params.HYBRID_UNCERTAINTY_THRESHOLD) and (self.params.HYBRID_SYNTHETIC_RANGE_LOW < synthetic_prob < self.params.HYBRID_SYNTHETIC_RANGE_HIGH))):
+            return "Hybrid"
         
         # Apply adjusted threshold
-        if (ai_prob >= adjusted_threshold):
-            return "AI-Generated"
+        if (synthetic_prob >= adjusted_threshold):
+            return "Synthetically-Generated"
 
-        elif (ai_prob <= (1.0 - adjusted_threshold)):
-            return "Human-Written"
+        elif (synthetic_prob <= (1.0 - adjusted_threshold)):
+            return "Authentically-Written"
 
         else:
             return "Uncertain"
     
 
-    def _generate_detailed_reasoning(self, results: Dict[str, MetricResult], weights: Dict[str, float], aggregated: Dict[str, float], 
-                                     verdict: str, uncertainty: float, consensus: float) -> List[str]:
+    def _generate_reasoning(self, results: Dict[str, MetricResult], weights: Dict[str, float], aggregated: Dict[str, float], verdict: str, uncertainty: float, consensus: float) -> List[str]:
         """
-        Generate detailed reasoning for the prediction
+        Generate reasoning for the prediction
         """
-        reasoning = list()
+        reasoning      = list()
         
         # Overall assessment
-        ai_prob    = aggregated.get("ai_probability", 0.5)
-        mixed_prob = aggregated.get("mixed_probability", 0.0)
+        synthetic_prob = aggregated.get("synthetic_probability", self.params.DEFAULT_SYNTHETIC_PROB)
+        hybrid_prob    = aggregated.get("hybrid_probability", self.params.DEFAULT_HYBRID_PROB)
 
         reasoning.append(f"## Ensemble Analysis Result")
         reasoning.append(f"**Final Verdict**: {verdict}")
-        reasoning.append(f"**AI Probability**: {ai_prob:.1%}")
-        reasoning.append(f"**Confidence Level**: {self._get_confidence_label(ai_prob)}")
+        reasoning.append(f"**Synthetic Probability**: {synthetic_prob:.1%}")
+        reasoning.append(f"**Confidence Level**: {self._get_confidence_label(synthetic_prob)}")
         reasoning.append(f"**Uncertainty**: {uncertainty:.1%}")
         reasoning.append(f"**Consensus**: {consensus:.1%}")
         
@@ -751,9 +474,17 @@ class EnsembleClassifier:
         
         for name, result in sorted_metrics:
             weight       = weights.get(name, 0.0)
-            contribution = "High" if (weight > 0.15) else "Medium" if (weight > 0.08) else "Low"
             
-            reasoning.append(f"**{name}**: {result.ai_probability:.1%} AI "
+            if (weight > self.params.CONTRIBUTION_HIGH):
+                contribution = "High"
+            
+            elif (weight > self.params.CONTRIBUTION_MEDIUM):
+                contribution = "Medium"
+            
+            else:
+                contribution = "Low"
+            
+            reasoning.append(f"**{name}**: {result.synthetic_probability:.1%} synthetic probability "
                              f"(Confidence: {result.confidence:.1%}, "
                              f"Contribution: {contribution})")
         
@@ -771,49 +502,64 @@ class EnsembleClassifier:
         if (top_metric and (weights.get(top_metric[0], 0.0) > 0.2)):
             reasoning.append(f"🎯 **Dominant metric** - {top_metric[0]} had strongest influence")
         
-        if (mixed_prob > 0.2):
-            reasoning.append("🔀 **Mixed signals** - Content shows characteristics of both AI and human writing")
+        if (hybrid_prob > self.params.HYBRID_PROB_THRESHOLD):
+            reasoning.append("🔀 **Mixed signals** - Content shows characteristics of both synthetic and authentic writing")
         
         return reasoning
     
 
-    def _get_confidence_label(self, ai_prob: float) -> str:
+    def _get_confidence_label(self, synthetic_prob: float) -> str:
         """
-        Get human-readable confidence label
+        Get human-readable confidence label based on distance from decision boundaries
         """
-        if ((ai_prob > 0.9) or (ai_prob < 0.1)):
+        # Very high confidence: very clear synthetic or very clear authentic
+        if ((synthetic_prob > 0.9) or (synthetic_prob < 0.1)):
             return "Very High"
-
-        elif ((ai_prob > 0.8) or (ai_prob < 0.2)):
+        
+        # High confidence: strongly synthetic or strongly authentic
+        elif ((synthetic_prob > 0.8) or (synthetic_prob < 0.2)):
             return "High"
-
-        elif ((ai_prob > 0.7) or (ai_prob < 0.3)):
+        
+        # Moderate confidence: leaning synthetic or leaning authentic
+        elif ((synthetic_prob > 0.7) or (synthetic_prob < 0.3)):
             return "Moderate"
-
+        
+        # Low confidence: close to decision boundary
         else:
             return "Low"
     
 
+    def _normalize_weights(self, weights: Dict[str, float]) -> Dict[str, float]:
+        """
+        Normalize weights to sum to 1.0
+        """
+        total = sum(weights.values())
+        
+        if (total > 0):
+            return {k: v / total for k, v in weights.items()}
+            
+        return weights
+    
+
     def _create_fallback_result(self, domain: Domain, metric_results: Dict[str, MetricResult], error: str) -> EnsembleResult:
         """
         Create fallback result when ensemble cannot make a confident decision
         """
-        return EnsembleResult(final_verdict      = "Uncertain",
-                              ai_probability     = 0.5,
-                              human_probability  = 0.5,
-                              mixed_probability  = 0.0,
-                              overall_confidence = 0.0,
-                              domain             = domain,
-                              metric_results     = metric_results,
-                              metric_weights     = {},
-                              weighted_scores    = {},
-                              reasoning          = [f"Ensemble analysis inconclusive", f"Reason: {error}"],
-                              uncertainty_score  = 1.0,
-                              consensus_level    = 0.0,
+        return EnsembleResult(final_verdict         = "Uncertain",
+                              synthetic_probability = self.params.DEFAULT_SYNTHETIC_PROB,
+                              authentic_probability = self.params.DEFAULT_AUTHENTIC_PROB,
+                              hybrid_probability    = self.params.DEFAULT_HYBRID_PROB,
+                              overall_confidence    = 0.0,
+                              domain                = domain,
+                              metric_results        = metric_results,
+                              metric_weights        = {},
+                              weighted_scores       = {},
+                              reasoning             = [f"Ensemble analysis inconclusive", f"Reason: {error}"],
+                              uncertainty_score     = 1.0,
+                              consensus_level       = 0.0,
+                              execution_mode        = self.execution_mode,
                              )
 
 
 # Export
-__all__ = ["EnsembleResult",
-           "EnsembleClassifier",
-          ]
+__all__ = ["EnsembleClassifier"]

{detector → services}/highlighter.py

@@ -5,37 +5,19 @@ from typing import Dict
 from typing import Tuple
 from loguru import logger
 from typing import Optional
-from dataclasses import dataclass
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
-from detector.ensemble import EnsembleResult
-from detector.ensemble import EnsembleClassifier
+from config.enums import Domain
+from config.schemas import MetricResult
+from config.schemas import EnsembleResult
 from processors.text_processor import TextProcessor
 from config.threshold_config import ConfidenceLevel
+from config.schemas import HighlightedSentenceResult
 from config.threshold_config import MetricThresholds
 from config.threshold_config import get_confidence_level
+from services.ensemble_classifier import EnsembleClassifier
 from config.threshold_config import get_threshold_for_domain
 from config.threshold_config import get_active_metric_weights
 
 
-@dataclass
-class HighlightedSentence:
-    """
-    A sentence with highlighting information
-    """
-    text              : str
-    ai_probability    : float
-    human_probability : float
-    mixed_probability : float
-    confidence        : float
-    confidence_level  : ConfidenceLevel
-    color_class       : str
-    tooltip           : str
-    index             : int
-    is_mixed_content  : bool
-    metric_breakdown  : Optional[Dict[str, float]] = None
-
-
 class TextHighlighter:
     """
     Generates sentence-level highlighting with ensemble results integration
@@ -43,35 +25,19 @@ class TextHighlighter:
     FEATURES:
     - Sentence-level highlighting with confidence scores
     - Domain-aware calibration
-    - Ensemble-based probability aggregation
-    - Mixed content detection
+    - Ensemble-assisted probability aggregation
+    - Hybrid content detection
     - Explainable tooltips
-    - Highlighting metrics calculation
     """
-    # Color thresholds with mixed content support - FIXED: No gaps
-    COLOR_THRESHOLDS = [(0.00, 0.10, "very-high-human", "#dcfce7", "Very likely human-written"),
-                        (0.10, 0.25, "high-human", "#bbf7d0", "Likely human-written"),
-                        (0.25, 0.40, "medium-human", "#86efac", "Possibly human-written"),
-                        (0.40, 0.60, "uncertain", "#fef9c3", "Uncertain"),
-                        (0.60, 0.75, "medium-ai", "#fde68a", "Possibly AI-generated"),
-                        (0.75, 0.90, "high-ai", "#fed7aa", "Likely AI-generated"),
-                        (0.90, 1.00, "very-high-ai", "#fecaca", "Very likely AI-generated"),
-                       ]
+    # Color thresholds - 4 categories
+    COLOR_THRESHOLDS             = [(0.00, 0.40, "authentic", "#d1fae5", "Likely authentically written"),    # Authentic: Synthetic probability < 0.4
+                                    (0.40, 0.60, "uncertain", "#fef3c7", "Uncertain authorship"),            # Uncertain: 0.4 ≤ Synthetic probability < 0.6
+                                    (0.60, 0.80, "hybrid", "#e9d5ff", "Mixed synthetic/authentic content"),  # Hybrid: 0.6 ≤ Synthetic probability < 0.8 OR explicit hybrid detection
+                                    (0.80, 1.01, "synthetic", "#fee2e2", "Likely synthetically generated"),  # Synthetic: Synthetic probability ≥ 0.8
+                                   ]
     
-    # Mixed content pattern
-    MIXED_THRESHOLD  = 0.25
-
-    # Risk weights
-    RISK_WEIGHTS     = {'very-high-ai'    : 1.0,
-                        'high-ai'         : 0.8,
-                        'medium-ai'       : 0.6,
-                        'uncertain'       : 0.4,
-                        'medium-human'    : 0.2,
-                        'high-human'      : 0.1,
-                        'very-high-human' : 0.0,
-                        'mixed-content'   : 0.7,
-                       }
-
+    # Hybrid detection thresholds
+    HYBRID_PROB_THRESHOLD        = 0.25  # Minimum hybrid probability to classify as hybrid
 
     def __init__(self, domain: Domain = Domain.GENERAL, ensemble_classifier: Optional[EnsembleClassifier] = None):
         """
@@ -99,20 +65,21 @@ class TextHighlighter:
                                      )
         except Exception as e:
             logger.warning(f"Failed to create default ensemble: {e}. Using fallback mode.")
-            # Return a minimal ensemble or raise based on requirements
-            return EnsembleClassifier(primary_method = "weighted_average")
+            return EnsembleClassifier(primary_method  = "domain_weighted",
+                                      fallback_method = "simple_average",
+                                     )
 
 
     def generate_highlights(self, text: str, metric_results: Dict[str, MetricResult], ensemble_result: Optional[EnsembleResult] = None,
-                            enabled_metrics: Optional[Dict[str, bool]] = None, use_sentence_level: bool = True) -> List[HighlightedSentence]:
+                            enabled_metrics: Optional[Dict[str, bool]] = None, use_sentence_level: bool = True) -> List[HighlightedSentenceResult]:
         """
         Generate sentence-level highlights with ensemble integration
         
         Arguments:
         ----------
             text                    { str }       : Original text
-            
-            metric_results          { dict }      : Results from all 6 metrics
+
+            metric_results          { dict }      : Results from all metrics
             
             ensemble_result    { EnsembleResult } : Optional document-level ensemble result
             
@@ -122,12 +89,15 @@ class TextHighlighter:
             
         Returns:
         --------
-                         { list }                 : List of HighlightedSentence objects
+                         { list }                 : List of HighlightedSentenceResult objects
         """
         try:
             # Validate inputs
             if not text or not text.strip():
-                return self._handle_empty_text(text, metric_results, ensemble_result)
+                return self._handle_empty_text(text            = text, 
+                                               metric_results  = metric_results, 
+                                               ensemble_result = ensemble_result,
+                                              )
             
             # Get domain-appropriate weights for enabled metrics
             if enabled_metrics is None:
@@ -136,7 +106,7 @@ class TextHighlighter:
             weights   = get_active_metric_weights(self.domain, enabled_metrics)
             
             # Split text into sentences with error handling
-            sentences = self._split_sentences_with_fallback(text)
+            sentences = self._split_sentences_with_fallback(text = text)
             
             if not sentences:
                 return self._handle_no_sentences(text, metric_results, ensemble_result)
@@ -147,61 +117,64 @@ class TextHighlighter:
             for idx, sentence in enumerate(sentences):
                 try:
                     if use_sentence_level:
-                        # Use ENSEMBLE for sentence-level analysis
-                        ai_prob, human_prob, mixed_prob, confidence, breakdown = self._calculate_sentence_ensemble_probability(sentence        = sentence, 
-                                                                                                                               metric_results  = metric_results,
-                                                                                                                               weights         = weights,
-                                                                                                                               ensemble_result = ensemble_result,
-                                                                                                                              )
+                        # Use ensemble for sentence-level analysis
+                        synthetic_prob, authentic_prob, hybrid_prob, confidence, breakdown = self._calculate_sentence_ensemble_probability(sentence        = sentence,
+                                                                                                                                           metric_results  = metric_results,
+                                                                                                                                           weights         = weights,
+                                                                                                                                           ensemble_result = ensemble_result,
+                                                                                                                                          )
                     else:
                         # Use document-level ensemble probabilities
-                        ai_prob, human_prob, mixed_prob, confidence, breakdown = self._get_document_ensemble_probability(ensemble_result = ensemble_result,
-                                                                                                                         metric_results  = metric_results,
-                                                                                                                         weights         = weights,
-                                                                                                                        )
+                        synthetic_prob, authentic_prob, hybrid_prob, confidence, breakdown = self._get_document_ensemble_probability(ensemble_result = ensemble_result,
+                                                                                                                                     metric_results  = metric_results,
+                                                                                                                                     weights         = weights,
+                                                                                                                                    )
                     
                     # Apply domain-specific adjustments with limits
-                    ai_prob                              = self._apply_domain_specific_adjustments(sentence        = sentence, 
-                                                                                                   ai_prob         = ai_prob, 
+                    synthetic_prob                       = self._apply_domain_specific_adjustments(sentence        = sentence,
+                                                                                                   synthetic_prob  = synthetic_prob,
                                                                                                    sentence_length = len(sentence.split()),
                                                                                                   )
                     
-                    # Determine if this is mixed content
-                    is_mixed_content                     = (mixed_prob > self.MIXED_THRESHOLD)
+                    # Determine if this is hybrid content
+                    is_hybrid_content                    = self._is_hybrid_content(synthetic_prob = synthetic_prob,
+                                                                                   hybrid_prob    = hybrid_prob,
+                                                                                   confidence     = confidence,
+                                                                                  )
                     
                     # Get confidence level
                     confidence_level                     = get_confidence_level(confidence)
                     
-                    # Get color class (consider mixed content)
-                    color_class, color_hex, tooltip_base = self._get_color_for_probability(probability      = ai_prob,
-                                                                                           is_mixed_content = is_mixed_content,
-                                                                                           mixed_prob       = mixed_prob,
+                    # Get color class (consider hybrid content)
+                    color_class, color_hex, tooltip_base = self._get_color_for_probability(synthetic_prob    = synthetic_prob,
+                                                                                           is_hybrid_content = is_hybrid_content,
+                                                                                           hybrid_prob       = hybrid_prob,
                                                                                           )
                     
                     # Generate enhanced tooltip
-                    tooltip                              = self._generate_ensemble_tooltip(sentence         = sentence, 
-                                                                                           ai_prob          = ai_prob,
-                                                                                           human_prob       = human_prob,
-                                                                                           mixed_prob       = mixed_prob,
-                                                                                           confidence       = confidence, 
-                                                                                           confidence_level = confidence_level, 
-                                                                                           tooltip_base     = tooltip_base, 
-                                                                                           breakdown        = breakdown,
-                                                                                           is_mixed_content = is_mixed_content,
+                    tooltip                              = self._generate_ensemble_tooltip(sentence          = sentence,
+                                                                                           synthetic_prob    = synthetic_prob,
+                                                                                           authentic_prob    = authentic_prob,
+                                                                                           hybrid_prob       = hybrid_prob,
+                                                                                           confidence        = confidence,
+                                                                                           confidence_level  = confidence_level,
+                                                                                           tooltip_base      = tooltip_base,
+                                                                                           breakdown         = breakdown,
+                                                                                           is_hybrid_content = is_hybrid_content,
                                                                                           )
                     
-                    highlighted_sentences.append(HighlightedSentence(text              = sentence,
-                                                                     ai_probability    = ai_prob,
-                                                                     human_probability = human_prob,
-                                                                     mixed_probability = mixed_prob,
-                                                                     confidence        = confidence,
-                                                                     confidence_level  = confidence_level,
-                                                                     color_class       = color_class,
-                                                                     tooltip           = tooltip,
-                                                                     index             = idx,
-                                                                     is_mixed_content  = is_mixed_content,
-                                                                     metric_breakdown  = breakdown,
-                                                                    )
+                    highlighted_sentences.append(HighlightedSentenceResult(text                  = sentence,
+                                                                           synthetic_probability = synthetic_prob,
+                                                                           authentic_probability = authentic_prob,
+                                                                           hybrid_probability    = hybrid_prob,
+                                                                           confidence            = confidence,
+                                                                           confidence_level      = confidence_level,
+                                                                           color_class           = color_class,
+                                                                           tooltip               = tooltip,
+                                                                           index                 = idx,
+                                                                           is_hybrid_content     = is_hybrid_content,
+                                                                           metric_breakdown      = breakdown,
+                                                                          )
                                                 )
                 
                 except Exception as e:
@@ -216,72 +189,72 @@ class TextHighlighter:
             return self._create_error_fallback(text, metric_results)
 
 
-    def _handle_empty_text(self, text: str, metric_results: Dict[str, MetricResult], ensemble_result: Optional[EnsembleResult]) -> List[HighlightedSentence]:
+    def _handle_empty_text(self, text: str, metric_results: Dict[str, MetricResult], ensemble_result: Optional[EnsembleResult]) -> List[HighlightedSentenceResult]:
         """
         Handle empty input text
         """
         if ensemble_result:
-            return [self._create_fallback_sentence(text       = "No text content", 
-                                                   index      = 0, 
-                                                   ai_prob    = ensemble_result.ai_probability, 
-                                                   human_prob = ensemble_result.human_probability,
+            return [self._create_fallback_sentence(text           = "No text content",
+                                                   index          = 0,
+                                                   synthetic_prob = ensemble_result.synthetic_probability,
+                                                   authentic_prob = ensemble_result.authentic_probability,
                                                   )
                    ]
 
         return [self._create_fallback_sentence("No text content", 0)]
 
 
-    def _handle_no_sentences(self, text: str, metric_results: Dict[str, MetricResult], ensemble_result: Optional[EnsembleResult]) -> List[HighlightedSentence]:
+    def _handle_no_sentences(self, text: str, metric_results: Dict[str, MetricResult], ensemble_result: Optional[EnsembleResult]) -> List[HighlightedSentenceResult]:
         """
         Handle case where no sentences could be extracted
         """
-        if (text and (len(text.strip()) > 0)):
+        if text and text.strip():
             # Treat entire text as one sentence
             return [self._create_fallback_sentence(text.strip(), 0)]
-
+        
         return [self._create_fallback_sentence("No processable content", 0)]
 
 
-    def _create_fallback_sentence(self, text: str, index: int, ai_prob: float = 0.5, human_prob: float = 0.5) -> HighlightedSentence:
+    def _create_fallback_sentence(self, text: str, index: int, synthetic_prob: float = 0.5, authentic_prob: float = 0.5) -> HighlightedSentenceResult:
         """
         Create a fallback sentence when processing fails
         """
         confidence_level             = get_confidence_level(0.3)
-        color_class, _, tooltip_base = self._get_color_for_probability(probability      = ai_prob, 
-                                                                       is_mixed_content = False, 
-                                                                       mixed_prob       = 0.0,
+        color_class, _, tooltip_base = self._get_color_for_probability(synthetic_prob    = synthetic_prob,
+                                                                       is_hybrid_content = False,
+                                                                       hybrid_prob       = 0.0,
                                                                       )
         
-        return HighlightedSentence(text              = text,
-                                   ai_probability    = ai_prob,
-                                   human_probability = human_prob,
-                                   mixed_probability = 0.0,
-                                   confidence        = 0.3,
-                                   confidence_level  = confidence_level,
-                                   color_class       = color_class,
-                                   tooltip           = f"Fallback: {tooltip_base}\nProcessing failed for this sentence",
-                                   index             = index,
-                                   is_mixed_content  = False,
-                                   metric_breakdown  = {"fallback": ai_prob},
-                                  )
-
-
-    def _create_error_fallback(self, text: str, metric_results: Dict[str, MetricResult]) -> List[HighlightedSentence]:
+        return HighlightedSentenceResult(text                  = text,
+                                         synthetic_probability = synthetic_prob,
+                                         authentic_probability = authentic_prob,
+                                         hybrid_probability    = 0.0,
+                                         confidence            = 0.3,
+                                         confidence_level      = confidence_level,
+                                         color_class           = color_class,
+                                         tooltip               = f"Fallback: {tooltip_base}\nProcessing failed for this sentence",
+                                         index                 = index,
+                                         is_hybrid_content     = False,
+                                         metric_breakdown      = {"fallback": synthetic_prob},
+                                        )
+
+
+    def _create_error_fallback(self, text: str, metric_results: Dict[str, MetricResult]) -> List[HighlightedSentenceResult]:
         """
         Create fallback when entire processing fails
         """
-        return [HighlightedSentence(text              = text[:100] + "..." if len(text) > 100 else text,
-                                    ai_probability    = 0.5,
-                                    human_probability = 0.5,
-                                    mixed_probability = 0.0,
-                                    confidence        = 0.1,
-                                    confidence_level  = get_confidence_level(0.1),
-                                    color_class       = "uncertain",
-                                    tooltip           = "Error in text processing",
-                                    index             = 0,
-                                    is_mixed_content  = False,
-                                    metric_breakdown  = {"error": 0.5},
-                                   )
+        return [HighlightedSentenceResult(text                  = text[:100] + "..." if len(text) > 100 else text,
+                                          synthetic_probability = 0.5,
+                                          authentic_probability = 0.5,
+                                          hybrid_probability    = 0.0,
+                                          confidence            = 0.1,
+                                          confidence_level      = get_confidence_level(0.1),
+                                          color_class           = "uncertain",
+                                          tooltip               = "Error in text processing",
+                                          index                 = 0,
+                                          is_hybrid_content     = False,
+                                          metric_breakdown      = {"error": 0.5},
+                                         )
                ]
  
 
@@ -291,7 +264,7 @@ class TextHighlighter:
         """
         try:
             sentences          = self.text_processor.split_sentences(text)
-            filtered_sentences = [s.strip() for s in sentences if len(s.strip()) >= 3] 
+            filtered_sentences = [s.strip() for s in sentences if len(s.strip()) >= 3]
             
             if filtered_sentences:
                 return filtered_sentences
@@ -315,79 +288,78 @@ class TextHighlighter:
             return [text] if text.strip() else []
 
 
-    def _calculate_sentence_ensemble_probability(self, sentence: str, metric_results: Dict[str, MetricResult], weights: Dict[str, float], 
-                                                 ensemble_result: Optional[EnsembleResult] = None) -> Tuple[float, float, float, float, Dict[str, float]]:
+    def _calculate_sentence_ensemble_probability(self, sentence: str, metric_results: Dict[str, MetricResult], weights: Dict[str, float], ensemble_result: Optional[EnsembleResult] = None) -> Tuple[float, float, float, float, Dict[str, float]]:
         """
         Calculate sentence probabilities using ensemble methods with domain calibration
         """
         sentence_length = len(sentence.split())
-        
-        # Handling short sentences - don't force neutral
-        if (sentence_length < 3):
-            # Return probabilities with lower confidence for very short sentences
-            base_ai_prob    = 0.5
 
-            # Low confidence for very short sentences
-            base_confidence = 0.2  
+        # Handling very short sentences – do not force neutral, but reduce confidence
+        if (sentence_length < 3):
+            base_synthetic_prob = 0.5
+            base_confidence     = 0.2
+            breakdown           = {"short_sentence": base_synthetic_prob}
 
-            breakdown       = {"short_sentence" : base_ai_prob}
-            
-            # Try to get some signal from available metrics
             for name, result in metric_results.items():
-                if ((result.error is None) and (weights.get(name, 0) > 0)):
-                    base_ai_prob    = result.ai_probability
-                    breakdown[name] = base_ai_prob
+                if (result.error is None and weights.get(name, 0.0) > 0):
+                    base_synthetic_prob = result.synthetic_probability
+                    breakdown[name]     = base_synthetic_prob
                     break
-            
-            return base_ai_prob, 1.0 - base_ai_prob, 0.0, base_confidence, breakdown
-        
-        # Calculate sentence-level metric results
+
+            return (base_synthetic_prob,
+                    1.0 - base_synthetic_prob,
+                    0.0,
+                    base_confidence,
+                    breakdown
+                   )
+
+        # Build sentence-level metric results
         sentence_metric_results = dict()
         breakdown               = dict()
-        
+
         for name, doc_result in metric_results.items():
-            if doc_result.error is None:
-                try:
-                    # Compute sentence-level probability for this metric
-                    sentence_prob                 = self._compute_sentence_metric(metric_name = name,
-                                                                                  sentence    = sentence,
-                                                                                  result      = doc_result,
-                                                                                  weight      = weights.get(name, 0.0),
-                                                                                 )
-                    
-                    # Create sentence-level MetricResult
-                    sentence_metric_results[name] = self._create_sentence_metric_result(metric_name = name,
-                                                                                        ai_prob     = sentence_prob,
-                                                                                        doc_result  = doc_result,
-                                                                                        sentence_length = sentence_length,
-                                                                                       )
-                    
-                    breakdown[name]               = sentence_prob
-                
-                except Exception as e:
-                    logger.warning(f"Metric {name} failed for sentence: {e}")
-                    # Use document probability as fallback
-                    breakdown[name] = doc_result.ai_probability
-        
-        # Use ensemble to combine sentence-level metrics
+            if doc_result.error is not None:
+                continue
+
+            try:
+                sentence_prob                 = self._compute_sentence_metric(metric_name = name,
+                                                                              sentence    = sentence,
+                                                                              result      = doc_result,
+                                                                              weight      = weights.get(name, 0.0),
+                                                                             )
+
+                sentence_metric_results[name] = self._create_sentence_metric_result(metric_name     = name,
+                                                                                    synthetic_prob  = sentence_prob,
+                                                                                    doc_result      = doc_result,
+                                                                                    sentence_length = sentence_length,
+                                                                                   )
+
+                breakdown[name]               = sentence_prob
+
+            except Exception as e:
+                logger.warning(f"Metric {name} failed for sentence: {e}")
+                breakdown[name] = doc_result.synthetic_probability
+
+        # Ensemble aggregation (PRIMARY PATH)
         if sentence_metric_results:
             try:
                 ensemble_sentence_result = self.ensemble.predict(metric_results = sentence_metric_results,
                                                                  domain         = self.domain,
                                                                 )
-                
-                return (ensemble_sentence_result.ai_probability, 
-                        ensemble_sentence_result.human_probability, 
-                        ensemble_sentence_result.mixed_probability, 
-                        ensemble_sentence_result.overall_confidence, 
-                        breakdown)
-                        
+
+                return (ensemble_sentence_result.synthetic_probability,
+                        ensemble_sentence_result.authentic_probability,
+                        ensemble_sentence_result.hybrid_probability,   
+                        ensemble_sentence_result.overall_confidence,
+                        breakdown,
+                       )
+
             except Exception as e:
                 logger.warning(f"Sentence ensemble failed: {e}")
-        
-        # Fallback: weighted average
-        return self._calculate_weighted_probability(metric_results, weights, breakdown)
-    
+
+        # Fallback: weighted average aggregation
+        return self._fallback_weighted_probability(metric_results, weights, breakdown)
+
 
     def _compute_sentence_metric(self, metric_name: str, sentence: str, result: MetricResult, weight: float) -> float:
         """
@@ -397,44 +369,46 @@ class TextHighlighter:
         
         # Get domain-specific threshold for this metric
         metric_thresholds = getattr(self.domain_thresholds, metric_name, None)
-
+        
         if not metric_thresholds:
-            return result.ai_probability
+            return result.synthetic_probability
         
         # Base probability from document-level result
-        base_prob         = result.ai_probability
+        base_prob         = result.synthetic_probability
         
         # Apply domain-aware sentence-level adjustments
-        adjusted_prob     = self._apply_metric_specific_adjustments(metric_name     = metric_name, 
-                                                                    sentence        = sentence, 
-                                                                    base_prob       = base_prob, 
-                                                                    sentence_length = sentence_length, 
+        adjusted_prob     = self._apply_metric_specific_adjustments(metric_name     = metric_name,
+                                                                    sentence        = sentence,
+                                                                    base_prob       = base_prob,
+                                                                    sentence_length = sentence_length,
                                                                     thresholds      = metric_thresholds,
                                                                    )
         
         return adjusted_prob
     
 
-    def _create_sentence_metric_result(self, metric_name: str, ai_prob: float, doc_result: MetricResult, sentence_length: int) -> MetricResult:
+    def _create_sentence_metric_result(self, metric_name: str, synthetic_prob: float, doc_result: MetricResult, sentence_length: int) -> MetricResult:
         """
         Create sentence-level MetricResult from document-level result
         """
-        # IMPROVED: Calculate confidence based on sentence characteristics
-        sentence_confidence = self._calculate_sentence_confidence(doc_result.confidence, sentence_length)
-        
-        return MetricResult(metric_name       = metric_name,
-                            ai_probability    = ai_prob,
-                            human_probability = 1.0 - ai_prob,  
-                            mixed_probability = 0.0,  
-                            confidence        = sentence_confidence,
-                            details           = doc_result.details,
-                            error             = None,
+        # Calculate confidence based on sentence characteristics
+        sentence_confidence = self._calculate_sentence_confidence(doc_confidence  = doc_result.confidence, 
+                                                                  sentence_length = sentence_length,
+                                                                 ) 
+        
+        return MetricResult(metric_name           = metric_name,
+                            synthetic_probability = synthetic_prob,
+                            authentic_probability = 1.0 - synthetic_prob,
+                            hybrid_probability    = 0.0,
+                            confidence            = sentence_confidence,
+                            details               = doc_result.details,
+                            error                 = None,
                            )
     
 
     def _calculate_sentence_confidence(self, doc_confidence: float, sentence_length: int) -> float:
         """
-        IMPROVED: Calculate confidence for sentence-level analysis with length consideration
+        Calculate confidence for sentence-level analysis with length consideration
         """
         base_reduction = 0.8
         # Scale confidence penalty with sentence length
@@ -443,65 +417,68 @@ class TextHighlighter:
         return max(0.1, doc_confidence * base_reduction * length_penalty)
     
 
-    def _calculate_weighted_probability(self, metric_results: Dict[str, MetricResult], weights: Dict[str, float], breakdown: Dict[str, float]) -> Tuple[float, float, float, float, Dict[str, float]]:
+    def _fallback_weighted_probability(self, metric_results: Dict[str, MetricResult], weights: Dict[str, float], breakdown: Dict[str, float]) -> Tuple[float, float, float, float, Dict[str, float]]:
         """
         Fallback weighted probability calculation
         """
-        weighted_ai_probs    = list()
-        weighted_human_probs = list()
-        confidences          = list()
-        total_weight         = 0.0
+        weighted_synthetic_probs = list()
+        weighted_authentic_probs = list()
+        confidences              = list()
+        total_weight             = 0.0
         
         for name, result in metric_results.items():
-            if (result.error is None):
+            if result.error is None:
                 weight = weights.get(name, 0.0)
                 
                 if (weight > 0):
-                    weighted_ai_probs.append(result.ai_probability * weight)
-                    weighted_human_probs.append(result.human_probability * weight)
+                    weighted_synthetic_probs.append(result.synthetic_probability * weight)
+                    weighted_authentic_probs.append(result.authentic_probability * weight)
                     confidences.append(result.confidence)
                     total_weight += weight
         
-        if ((not weighted_ai_probs) or (total_weight == 0)):
+        if not weighted_synthetic_probs or total_weight == 0:
             return 0.5, 0.5, 0.0, 0.5, breakdown or {}
         
-        ai_prob        = sum(weighted_ai_probs) / total_weight
-        human_prob     = sum(weighted_human_probs) / total_weight
-        mixed_prob     = 0.0  # Fallback
+        synthetic_prob = sum(weighted_synthetic_probs) / total_weight
+        authentic_prob = sum(weighted_authentic_probs) / total_weight
+        hybrid_prob    = 0.0  # Fallback
         avg_confidence = sum(confidences) / len(confidences) if confidences else 0.5
         
-        return ai_prob, human_prob, mixed_prob, avg_confidence, breakdown
+        return synthetic_prob, authentic_prob, hybrid_prob, avg_confidence, breakdown
     
 
-    def _get_document_ensemble_probability(self, ensemble_result: Optional[EnsembleResult], metric_results: Dict[str, MetricResult],
-                                           weights: Dict[str, float]) -> Tuple[float, float, float, float, Dict[str, float]]:
+    def _get_document_ensemble_probability(self, ensemble_result: Optional[EnsembleResult], metric_results: Dict[str, MetricResult], weights: Dict[str, float]) -> Tuple[float, float, float, float, Dict[str, float]]:
         """
         Get document-level ensemble probability
         """
         if ensemble_result:
             # Use existing ensemble result
-            breakdown = {name: result.ai_probability for name, result in metric_results.items()}
-            return (ensemble_result.ai_probability, ensemble_result.human_probability, ensemble_result.mixed_probability,
-                    ensemble_result.overall_confidence, breakdown)
-        
+            breakdown = {name: result.synthetic_probability for name, result in metric_results.items()}
+            return (ensemble_result.synthetic_probability,
+                    ensemble_result.authentic_probability,
+                    ensemble_result.hybrid_probability,
+                    ensemble_result.overall_confidence,
+                    breakdown
+                   )
+
         else:
             # Calculate from metrics
-            return self._calculate_weighted_probability(metric_results, weights, {})
+            return self._fallback_weighted_probability(metric_results, weights, {})
 
 
-    def _apply_domain_specific_adjustments(self, sentence: str, ai_prob: float, sentence_length: int) -> float:
+    def _apply_domain_specific_adjustments(self, sentence: str, synthetic_prob: float, sentence_length: int) -> float:
         """
-        Apply domain-specific adjustments to AI probability with limits
+        Apply domain-specific adjustments to Synthetic probability with limits
         """
-        original_prob  = ai_prob
+        original_prob  = synthetic_prob
         adjustments    = list()
         sentence_lower = sentence.lower()
         
         # Technical & AI/ML domains
-        if (self.domain in [Domain.AI_ML, Domain.SOFTWARE_DEV, Domain.TECHNICAL_DOC, Domain.ENGINEERING, Domain.SCIENCE]):
+        if self.domain in [Domain.AI_ML, Domain.SOFTWARE_DEV, Domain.TECHNICAL_DOC, Domain.ENGINEERING, Domain.SCIENCE]:
             if self._has_technical_terms(sentence_lower):
-                adjustments.append(1.1)  
-
+                adjustments.append(1.1)
+            
             elif self._has_code_like_patterns(sentence):
                 adjustments.append(1.15)
             
@@ -509,34 +486,34 @@ class TextHighlighter:
                 adjustments.append(1.05)
                 
         # Creative & informal domains
-        elif (self.domain in [Domain.CREATIVE, Domain.SOCIAL_MEDIA, Domain.BLOG_PERSONAL]):
+        elif self.domain in [Domain.CREATIVE, Domain.SOCIAL_MEDIA, Domain.BLOG_PERSONAL]:
             if self._has_informal_language(sentence_lower):
-                adjustments.append(0.7)  
-            
+                adjustments.append(0.7)
+
             elif self._has_emotional_language(sentence):
                 adjustments.append(0.8)
-
-            elif (sentence_length < 10):
+            
+            elif sentence_length < 10:
                 adjustments.append(0.8)
                 
         # Academic & formal domains
-        elif (self.domain in [Domain.ACADEMIC, Domain.LEGAL, Domain.MEDICAL]):
+        elif self.domain in [Domain.ACADEMIC, Domain.LEGAL, Domain.MEDICAL]:
             if self._has_citation_patterns(sentence):
-                adjustments.append(0.8)  
-
+                adjustments.append(0.8)
+            
             elif self._has_technical_terms(sentence_lower):
                 adjustments.append(1.1)
-
+            
             elif (sentence_length > 40):
                 adjustments.append(1.1)
                 
         # Business & professional domains
-        elif (self.domain in [Domain.BUSINESS, Domain.MARKETING, Domain.JOURNALISM]):
+        elif self.domain in [Domain.BUSINESS, Domain.MARKETING, Domain.JOURNALISM]:
             if self._has_business_jargon(sentence_lower):
-                adjustments.append(1.05)  
+                adjustments.append(1.05)
             
             elif self._has_ambiguous_phrasing(sentence_lower):
-                adjustments.append(0.9)  
+                adjustments.append(0.9)
             
             elif (15 <= sentence_length <= 25):
                 adjustments.append(0.9)
@@ -544,8 +521,8 @@ class TextHighlighter:
         # Tutorial & educational domains
         elif (self.domain == Domain.TUTORIAL):
             if self._has_instructional_language(sentence_lower):
-                adjustments.append(0.85)  
-
+                adjustments.append(0.85)
+            
             elif self._has_step_by_step_pattern(sentence):
                 adjustments.append(0.8)
             
@@ -564,15 +541,16 @@ class TextHighlighter:
         if adjustments:
             # Sort by impact (farthest from 1.0)
             adjustments.sort(key = lambda x: abs(x - 1.0), reverse = True)
+            
             # Limit to 2 strongest
-            strongest_adjustments = adjustments[:2]  
+            strongest_adjustments = adjustments[:2]
             
             for adjustment in strongest_adjustments:
-                ai_prob *= adjustment
+                synthetic_prob *= adjustment
         
-        # Ensure probability stays within bounds and doesn't change too drastically : Maximum 30% change from original
-        max_change   = 0.3  
-        bounded_prob = max(original_prob - max_change, min(original_prob + max_change, ai_prob))
+        # Ensure probability stays within bounds and doesn't change too drastically
+        max_change   = 0.3  # Maximum 30% change from original
+        bounded_prob = max(original_prob - max_change, min(original_prob + max_change, synthetic_prob))
         
         return max(0.0, min(1.0, bounded_prob))
     
@@ -585,7 +563,7 @@ class TextHighlighter:
         if (metric_name == "perplexity"):
             if (sentence_length < 8):
                 return min(1.0, base_prob * 1.2)
-
+            
             elif (sentence_length > 25):
                 return max(0.0, base_prob * 0.8)
         
@@ -630,40 +608,55 @@ class TextHighlighter:
         return base_prob
     
 
-    def _get_color_for_probability(self, probability: float, is_mixed_content: bool = False, mixed_prob: float = 0.0) -> Tuple[str, str, str]:
+    def _is_hybrid_content(self, synthetic_prob: float, hybrid_prob: float, confidence: float) -> bool:
         """
-        Get color class with mixed content support and no threshold gaps
+        Determine if content should be classified as hybrid
         """
-        # Handle probability = 1.0 explicitly
-        if (probability >= 1.0):
-            return "very-high-ai", "#fecaca", "Very likely AI-generated (100%)"
+        # Case 1: Explicit high hybrid probability from ensemble
+        if (hybrid_prob > self.HYBRID_PROB_THRESHOLD):
+            return True
+        
+        # Case 2: High uncertainty combined with ambiguous synthetic probability
+        if (confidence < 0.3 and 0.4 <= synthetic_prob <= 0.7):
+            return True
         
-        # Check mixed content first
-        if (is_mixed_content and (mixed_prob > self.MIXED_THRESHOLD)):
-            return "mixed-content", "#e9d5ff", f"Mixed AI/Human content ({mixed_prob:.1%} mixed)"
+        # Case 3: Synthetic probability in hybrid range (0.6-0.8)
+        if (0.6 <= synthetic_prob < 0.8):
+            return True
         
-        # Iterate through thresholds correctly
+        return False
+    
+
+    def _get_color_for_probability(self, synthetic_prob: float, is_hybrid_content: bool = False, hybrid_prob: float = 0.0) -> Tuple[str, str, str]:
+        """
+        Get color class with simplified 4-category system
+        """
+        # Handle hybrid content first
+        if is_hybrid_content:
+            return "hybrid", "#e9d5ff", f"Mixed synthetic/authentic content ({hybrid_prob:.1%} hybrid)"
+        
+        # Iterate through simplified thresholds
         for min_thresh, max_thresh, color_class, color_hex, tooltip in self.COLOR_THRESHOLDS:
-            if (min_thresh <= probability < max_thresh):
+            if (min_thresh <= synthetic_prob < max_thresh):
                 return color_class, color_hex, tooltip
         
-        # Fallback for probability = 1.0 (should be caught above, but just in case)
-        return "very-high-ai", "#fecaca", "Very likely AI-generated"
-
+        # Fallback for edge cases
+        return "uncertain", "#fef3c7", "Uncertain authorship"
+    
 
-    def _generate_ensemble_tooltip(self, sentence: str, ai_prob: float, human_prob: float, mixed_prob: float, confidence: float, confidence_level: ConfidenceLevel, 
-                                   tooltip_base: str, breakdown: Optional[Dict[str, float]] = None, is_mixed_content: bool = False) -> str:
+    def _generate_ensemble_tooltip(self, sentence: str, synthetic_prob: float, authentic_prob: float, hybrid_prob: float, confidence: float, confidence_level: ConfidenceLevel, 
+                                   tooltip_base: str, breakdown: Optional[Dict[str, float]] = None, is_hybrid_content: bool = False) -> str:
         """
         Generate enhanced tooltip with ENSEMBLE information
         """
         tooltip = f"{tooltip_base}\n"
         
-        if is_mixed_content:
-            tooltip += "🔀 MIXED CONTENT DETECTED\n"
+        if is_hybrid_content:
+            tooltip += "🔀 HYBRID CONTENT DETECTED\n"
         
-        tooltip += f"AI Probability: {ai_prob:.1%}\n"
-        tooltip += f"Human Probability: {human_prob:.1%}\n"
-        tooltip += f"Mixed Probability: {mixed_prob:.1%}\n"
+        tooltip += f"Synthetic Probability: {synthetic_prob:.1%}\n"
+        tooltip += f"Authentic Probability: {authentic_prob:.1%}\n"
+        tooltip += f"Hybrid Probability: {hybrid_prob:.1%}\n"
         tooltip += f"Confidence: {confidence:.1%} ({confidence_level.value.replace('_', ' ').title()})\n"
         tooltip += f"Domain: {self.domain.value.replace('_', ' ').title()}\n"
         tooltip += f"Length: {len(sentence.split())} words"
@@ -671,7 +664,7 @@ class TextHighlighter:
         if breakdown:
             tooltip += "\n\nMetric Breakdown:"
             # Show top 4 metrics
-            for metric, prob in list(breakdown.items())[:4]:  
+            for metric, prob in list(breakdown.items())[:4]:
                 tooltip += f"\n• {metric}: {prob:.1%}"
         
         tooltip += f"\n\nEnsemble Method: {getattr(self.ensemble, 'primary_method', 'fallback')}"
@@ -684,7 +677,6 @@ class TextHighlighter:
         Check for academic citation patterns
         """
         citation_indicators = ['et al.', 'ibid.', 'cf.', 'e.g.', 'i.e.', 'vol.', 'pp.', 'ed.', 'trans.', 'reference', 'cited', 'according to']
-
         return any(indicator in sentence.lower() for indicator in citation_indicators)
     
 
@@ -693,7 +685,6 @@ class TextHighlighter:
         Check for informal language patterns
         """
         informal_indicators = ['lol', 'omg', 'btw', 'imo', 'tbh', 'afaik', 'smh', '👋', '😂', '❤️', 'haha', 'wow', 'awesome']
-
         return any(indicator in sentence.lower() for indicator in informal_indicators)
     
 
@@ -713,7 +704,6 @@ class TextHighlighter:
         Check for ambiguous phrasing that might indicate human writing
         """
         ambiguous_indicators = ['perhaps', 'maybe', 'possibly', 'likely', 'appears to', 'seems to', 'might be', 'could be']
-
         return any(indicator in sentence.lower() for indicator in ambiguous_indicators)
     
 
@@ -726,7 +716,6 @@ class TextHighlighter:
             return False
         
         complex_indicators = ['which', 'that', 'although', 'because', 'while', 'when', 'if', 'however', 'therefore']
-
         return any(indicator in sentence.lower() for indicator in complex_indicators)
     
 
@@ -735,7 +724,6 @@ class TextHighlighter:
         Check for emotional or subjective language
         """
         emotional_indicators = ['feel', 'believe', 'think', 'wonder', 'hope', 'wish', 'love', 'hate', 'frustrating', 'exciting']
-        
         return any(indicator in sentence.lower() for indicator in emotional_indicators)
     
 
@@ -744,7 +732,6 @@ class TextHighlighter:
         Check for business jargon
         """
         jargon_indicators = ['synergy', 'leverage', 'bandwidth', 'circle back', 'touch base', 'value add', 'core competency']
-        
         return any(indicator in sentence.lower() for indicator in jargon_indicators)
     
 
@@ -753,7 +740,6 @@ class TextHighlighter:
         Check for instructional language patterns
         """
         instructional_indicators = ['step by step', 'firstly', 'secondly', 'finally', 'note that', 'remember to', 'make sure']
-        
         return any(indicator in sentence.lower() for indicator in instructional_indicators)
     
 
@@ -762,7 +748,6 @@ class TextHighlighter:
         Check for step-by-step instructions
         """
         step_patterns = ['step 1', 'step 2', 'step 3', 'step one', 'step two', 'first step', 'next step']
-        
         return any(pattern in sentence.lower() for pattern in step_patterns)
     
 
@@ -771,7 +756,6 @@ class TextHighlighter:
         Check for example indicators
         """
         example_indicators = ['for example', 'for instance', 'such as', 'e.g.', 'as an example']
-        
         return any(indicator in sentence.lower() for indicator in example_indicators)
     
 
@@ -780,7 +764,6 @@ class TextHighlighter:
         Check for code-like patterns in technical domains
         """
         code_patterns = ['function', 'variable', 'class', 'method', 'import', 'def ', 'void ', 'public ', 'private ']
-        
         return any(pattern in sentence for pattern in code_patterns)
     
 
@@ -802,19 +785,19 @@ class TextHighlighter:
         elif (len(words) > 25):
             score += 0.5
         
-        indicator_count   = sum(1 for indicator in complexity_indicators if indicator in sentence.lower())
-        score            += min(0.5, indicator_count * 0.1)
+        indicator_count       = sum(1 for indicator in complexity_indicators if indicator in sentence.lower())
+        score                += min(0.5, indicator_count * 0.1)
         
-        clause_indicators = [',', ';', 'and', 'but', 'or', 'because', 'although']
-        clause_count      = sum(1 for indicator in clause_indicators if indicator in sentence.lower())
-        score            += min(0.2, clause_count * 0.05)
+        clause_indicators     = [',', ';', 'and', 'but', 'or', 'because', 'although']
+        clause_count          = sum(1 for indicator in clause_indicators if indicator in sentence.lower())
+        score                += min(0.2, clause_count * 0.05)
         
         return min(1.0, score)
     
 
     def _has_repetition(self, sentence: str) -> bool:
         """
-        Check if sentence has word repetition (common in AI text)
+        Check if sentence has word repetition (common in Synthetic text)
         """
         words = sentence.lower().split()
         if (len(words) < 6):
@@ -827,48 +810,29 @@ class TextHighlighter:
                 word_counts[word] = word_counts.get(word, 0) + 1
         
         repeated_words = [word for word, count in word_counts.items() if count > 2]
-        
-        return len(repeated_words) > 0
+        return (len(repeated_words) > 0)
     
 
-    def _split_sentences(self, text: str) -> List[str]:
-        """
-        Split the text chunk into multiple sentences
-        """
-        sentences          = self.text_processor.split_sentences(text)
-        filtered_sentences = list()
-
-        for sentence in sentences:
-            clean_sentence = sentence.strip()
-            
-            if (len(clean_sentence) >= 3): 
-                filtered_sentences.append(clean_sentence)
-        
-        return filtered_sentences
-
-
-    def generate_html(self, highlighted_sentences: List[HighlightedSentence], include_legend: bool = False, include_metrics: bool = True) -> str:
+    def generate_html(self, highlighted_sentences: List[HighlightedSentenceResult], include_legend: bool = True) -> str:
         """
         Generate HTML with highlighted sentences
         
         Arguments:
         ----------
-            highlighted_sentences { List[HighlightedSentence] } : Sentences with highlighting data
-            
-            include_legend         { bool }                     : Whether to include legend (set to False to avoid duplicates)
-            
-            include_metrics        { bool }                     : Whether to include metrics summary
+            highlighted_sentences { List[HighlightedSentenceResult] } : Sentences with highlighting data
+
+            include_legend                   { bool }                 : Whether to include legend
             
         Returns:
         --------
-                                 { str }                        : HTML content
+                                 { str }                              : HTML content
         """
         html_parts = list()
         
         # Add CSS
-        html_parts.append(self._generate_enhanced_css())
+        html_parts.append(self._generate_css())
         
-        # Only include legend if explicitly requested (usually False to avoid duplicates)
+        # Include legend if requested
         if include_legend:
             html_parts.append(self._generate_legend_html())
         
@@ -876,33 +840,28 @@ class TextHighlighter:
         html_parts.append('<div class="highlighted-text">')
         
         for sent in highlighted_sentences:
-            extra_class = " mixed-highlight" if sent.is_mixed_content else ""
+            extra_class = " hybrid-highlight" if sent.is_hybrid_content else ""
             html_parts.append(f'<span class="highlight {sent.color_class}{extra_class}" '
-                              f'data-ai-prob="{sent.ai_probability:.4f}" '
-                              f'data-human-prob="{sent.human_probability:.4f}" '
-                              f'data-mixed-prob="{sent.mixed_probability:.4f}" '
+                              f'data-synthetic-prob="{sent.synthetic_probability:.4f}" '
+                              f'data-authentic-prob="{sent.authentic_probability:.4f}" '
+                              f'data-hybrid-prob="{sent.hybrid_probability:.4f}" '
                               f'data-confidence="{sent.confidence:.4f}" '
                               f'data-confidence-level="{sent.confidence_level.value}" '
                               f'data-domain="{self.domain.value}" '
                               f'data-sentence-idx="{sent.index}" '
-                              f'data-is-mixed="{str(sent.is_mixed_content).lower()}" '
+                              f'data-is-hybrid="{str(sent.is_hybrid_content).lower()}" '
                               f'title="{sent.tooltip}">'
                               f'{sent.text}'
-                              f'</span> '
-                             )
+                              f'</span> ')
         
         html_parts.append('</div>')
         
-        # Add metrics summary if requested (separate from legend)
-        if include_metrics and highlighted_sentences:
-            html_parts.append(self._generate_metrics_summary(highlighted_sentences))
-        
         return '\n'.join(html_parts)
         
 
-    def _generate_enhanced_css(self) -> str:
+    def _generate_css(self) -> str:
         """
-        Generate CSS for highlighting for Better readability
+        Generate CSS for highlighting for better readability with 4 color types
         """
         return """
         <style>
@@ -936,277 +895,65 @@ class TextHighlighter:
             text-shadow: 0 1px 1px rgba(255,255,255,0.8);
         }
         
-        /* AI indicators - Lighter backgrounds for better readability */
-        .very-high-ai {
-            background-color: #fee2e2;
-            border-bottom-color: #ef4444;
-        }
-        
-        .high-ai {
-            background-color: #fed7aa;
-            border-bottom-color: #f97316;
+        /* Authentic - Green tones */
+        .authentic {
+            background-color: #d1fae5;
+            border-bottom-color: #10b981;
         }
         
-        .medium-ai {
+        /* Uncertain - Yellow tones */
+        .uncertain {
             background-color: #fef3c7;
             border-bottom-color: #f59e0b;
         }
         
-        /* Uncertain */
-        .uncertain {
-            background-color: #fef9c3;
-            border-bottom-color: #fbbf24;
-        }
-        
-        /* Human indicators - Lighter backgrounds */
-        .medium-human {
-            background-color: #ecfccb;
-            border-bottom-color: #a3e635;
-        }
-        
-        .high-human {
-            background-color: #bbf7d0;
-            border-bottom-color: #4ade80;
-        }
-        
-        .very-high-human {
-            background-color: #dcfce7;
-            border-bottom-color: #22c55e;
-        }
-        
-        /* Mixed content */
-        .mixed-content {
+        /* Hybrid - Purple tones */
+        .hybrid {
             background-color: #e9d5ff;
             border-bottom-color: #a855f7;
-            background-image: repeating-linear-gradient(45deg, transparent, transparent 5px, rgba(168, 85, 247, 0.1) 5px, rgba(168, 85, 247, 0.1) 10px);
         }
         
-        .mixed-highlight:hover {
+        .hybrid-highlight:hover {
             border: 2px dashed #a855f7;
         }
         
-        /* Summary styles */
-        .highlight-summary {
-            margin-bottom: 20px;
-            padding: 15px;
-            background: #f9fafb;
-            border-radius: 8px;
-            border: 1px solid #e5e7eb;
-        }
-        
-        .highlight-summary h4 {
-            margin: 0 0 10px 0;
-            font-size: 14px;
-            font-weight: 600;
-            color: #374151;
-        }
-        
-        .summary-stats {
-            display: grid;
-            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-            gap: 10px;
-        }
-        
-        .stat-item {
-            display: flex;
-            justify-content: space-between;
-            align-items: center;
-            padding: 8px 12px;
-            background: white;
-            border-radius: 6px;
-            border: 1px solid #e5e7eb;
-        }
-        
-        .stat-label {
-            font-size: 13px;
-            color: #6b7280;
-        }
-        
-        .stat-value {
-            font-size: 13px;
-            font-weight: 600;
-            color: #374151;
+        /* Synthetic - Red tones */
+        .synthetic {
+            background-color: #fee2e2;
+            border-bottom-color: #ef4444;
         }
         </style>
         """
     
 
-    def _generate_metrics_summary(self, sentences: List[HighlightedSentence]) -> str:
-        """
-        Generate summary statistics for highlighted sentences
-        """
-        if not sentences:
-            return ""
-        
-        # Calculate summary metrics
-        total_sentences = len(sentences)
-        
-        # Count sentences by category
-        very_high_ai    = len([s for s in sentences if s.color_class == "very-high-ai"])
-        high_ai         = len([s for s in sentences if s.color_class == "high-ai"])
-        medium_ai       = len([s for s in sentences if s.color_class == "medium-ai"])
-        uncertain       = len([s for s in sentences if s.color_class == "uncertain"])
-        medium_human    = len([s for s in sentences if s.color_class == "medium-human"])
-        high_human      = len([s for s in sentences if s.color_class == "high-human"])
-        very_high_human = len([s for s in sentences if s.color_class == "very-high-human"])
-        mixed           = len([s for s in sentences if s.color_class == "mixed-content"])
-        
-        # Calculate overall risk score (weighted average)
-        weighted_risk = 0.0
-        for sent in sentences:
-            weight         = self.RISK_WEIGHTS.get(sent.color_class, 0.4)
-            weighted_risk += sent.ai_probability * weight
-        
-        overall_risk_score = weighted_risk / total_sentences if total_sentences else 0.0
-        
-        # Calculate average probabilities
-        avg_ai_prob        = sum(s.ai_probability for s in sentences) / total_sentences
-        avg_human_prob     = sum(s.human_probability for s in sentences) / total_sentences
-        
-        # Sentence counts
-        ai_sentences       = very_high_ai + high_ai + medium_ai
-        human_sentences    = very_high_human + high_human + medium_human
-        
-        html = f"""
-        <div class="highlight-summary">
-            <h4>📊 Text Analysis Summary</h4>
-            <div class="summary-stats">
-                <div class="stat-item">
-                    <span class="stat-label">Overall Risk Score</span>
-                    <span class="stat-value">{overall_risk_score:.1%}</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Average AI Probability</span>
-                    <span class="stat-value">{avg_ai_prob:.1%}</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">AI Sentences</span>
-                    <span class="stat-value">{ai_sentences} ({ai_sentences/total_sentences:.1%})</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Human Sentences</span>
-                    <span class="stat-value">{human_sentences} ({human_sentences/total_sentences:.1%})</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Uncertain Sentences</span>
-                    <span class="stat-value">{uncertain} ({uncertain/total_sentences:.1%})</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Mixed Sentences</span>
-                    <span class="stat-value">{mixed} ({mixed/total_sentences:.1%})</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Total Sentences</span>
-                    <span class="stat-value">{total_sentences}</span>
-                </div>
-                <div class="stat-item">
-                    <span class="stat-label">Domain</span>
-                    <span class="stat-value">{self.domain.value.replace('_', ' ').title()}</span>
-                </div>
-            </div>
-        </div>
-        """
-        return html
-    
-
     def _generate_legend_html(self) -> str:
         """
-        Generate legend HTML - Only used if explicitly requested
+        Generate legend HTML for 4-category system
         """
         return """
         <div class="highlight-legend" style="margin-bottom: 20px; padding: 15px; background: #f8fafc; border-radius: 8px; border: 1px solid #e2e8f0;">
-            <h4 style="margin: 0 0 10px 0; font-size: 14px; font-weight: 600; color: #374151;">AI Detection Legend</h4>
+            <h4 style="margin: 0 0 10px 0; font-size: 14px; font-weight: 600; color: #374151;">Text Analysis Legend</h4>
             <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 8px;">
                 <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #dcfce7; border: 1px solid #22c55e; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Very Likely Human (0-10%)</span>
-                </div>
-                <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #bbf7d0; border: 1px solid #4ade80; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Likely Human (10-25%)</span>
-                </div>
-                <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #86efac; border: 1px solid #16a34a; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Possibly Human (25-40%)</span>
-                </div>
-                <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #fef9c3; border: 1px solid #fbbf24; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Uncertain (40-60%)</span>
-                </div>
-                <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #fde68a; border: 1px solid #f59e0b; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Possibly AI (60-75%)</span>
+                    <div style="width: 16px; height: 16px; background: #d1fae5; border: 1px solid #10b981; border-radius: 3px;"></div>
+                    <span style="font-size: 12px; color: #374151;">Authentic (0-40% synthetic)</span>
                 </div>
                 <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #fed7aa; border: 1px solid #f97316; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Likely AI (75-90%)</span>
+                    <div style="width: 16px; height: 16px; background: #fef3c7; border: 1px solid #f59e0b; border-radius: 3px;"></div>
+                    <span style="font-size: 12px; color: #374151;">Uncertain (40-60% synthetic)</span>
                 </div>
                 <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #fecaca; border: 1px solid #ef4444; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Very Likely AI (90-100%)</span>
+                    <div style="width: 16px; height: 16px; background: #e9d5ff; border: 1px solid #a855f7; border-radius: 3px;"></div>
+                    <span style="font-size: 12px; color: #374151;">Hybrid (60-80% synthetic)</span>
                 </div>
                 <div style="display: flex; align-items: center; gap: 8px;">
-                    <div style="width: 16px; height: 16px; background: #e9d5ff; border: 1px solid #a855f7; border-radius: 3px;"></div>
-                    <span style="font-size: 12px; color: #374151;">Mixed Content</span>
+                    <div style="width: 16px; height: 16px; background: #fee2e2; border: 1px solid #ef4444; border-radius: 3px;"></div>
+                    <span style="font-size: 12px; color: #374151;">Synthetic (80-100% synthetic)</span>
                 </div>
             </div>
         </div>
         """
 
 
-    def calculate_metrics(self, highlighted_sentences: List[HighlightedSentence]) -> Dict[str, float]:
-        """
-        Calculate metrics for external use
-        
-        Arguments:
-        ----------
-            highlighted_sentences { List[HighlightedSentence] } : Sentences with highlighting data
-            
-        Returns:
-        --------
-                         { Dict[str, float] }                   : Dictionary with metrics
-        """
-        if not highlighted_sentences:
-            return {}
-        
-        total_sentences = len(highlighted_sentences)
-        
-        # Calculate weighted risk score
-        weighted_risk   = 0.0
-
-        for sent in highlighted_sentences:
-            weight         = self.RISK_WEIGHTS.get(sent.color_class, 0.4)
-            weighted_risk += sent.ai_probability * weight
-        
-        overall_risk_score  = weighted_risk / total_sentences
-        
-        # Count sentences by category
-        ai_sentences        = len([s for s in highlighted_sentences if s.ai_probability >= 0.6])
-        human_sentences     = len([s for s in highlighted_sentences if s.ai_probability <= 0.4])
-        uncertain_sentences = len([s for s in highlighted_sentences if 0.4 < s.ai_probability < 0.6])
-        mixed_sentences     = len([s for s in highlighted_sentences if s.is_mixed_content])
-        
-        # Average probabilities
-        avg_ai_prob         = sum(s.ai_probability for s in highlighted_sentences) / total_sentences
-        avg_human_prob      = sum(s.human_probability for s in highlighted_sentences) / total_sentences
-        avg_confidence      = sum(s.confidence for s in highlighted_sentences) / total_sentences
-        
-        return {'overall_risk_score'        : overall_risk_score,
-                'avg_ai_probability'        : avg_ai_prob,
-                'avg_human_probability'     : avg_human_prob,
-                'avg_confidence'            : avg_confidence,
-                'ai_sentence_count'         : ai_sentences,
-                'human_sentence_count'      : human_sentences,
-                'uncertain_sentence_count'  : uncertain_sentences,
-                'mixed_sentence_count'      : mixed_sentences,
-                'total_sentences'           : total_sentences,
-                'ai_sentence_percentage'    : ai_sentences / total_sentences,
-                'human_sentence_percentage' : human_sentences / total_sentences,
-               }
-
-
-
 # Export
-__all__ = ["TextHighlighter", 
-           "HighlightedSentence",
-          ]
+__all__ = ["TextHighlighter"]

services/orchestrator.py

@@ -0,0 +1,753 @@
+# DEPENDENCIES
+import time
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Tuple
+from loguru import logger
+from typing import Optional
+from config.enums import Domain
+from config.settings import settings
+from concurrent.futures import Executor
+from config.schemas import MetricResult
+from config.schemas import EnsembleResult
+from metrics.entropy import EntropyMetric
+from config.schemas import DetectionResult
+from concurrent.futures import as_completed
+from metrics.perplexity import PerplexityMetric
+from metrics.linguistic import LinguisticMetric
+from metrics.structural import StructuralMetric
+from concurrent.futures import ThreadPoolExecutor
+from config.schemas import LanguageDetectionResult
+from processors.text_processor import TextProcessor
+from processors.text_processor import ProcessedText
+from processors.domain_classifier import DomainClassifier
+from processors.domain_classifier import DomainPrediction
+from processors.language_detector import LanguageDetector
+from services.ensemble_classifier import EnsembleClassifier
+from metrics.semantic_analysis import SemanticAnalysisMetric
+from metrics.multi_perturbation_stability import MultiPerturbationStabilityMetric
+
+
+class DetectionOrchestrator:
+    """
+    Coordinates the entire detection pipeline from text input to final results
+
+    Pipeline:
+    1. Text preprocessing
+    2. Domain classification
+    3. Language detection (optional)
+    4. Metric execution (parallel/sequential)
+    5. Ensemble aggregation
+    6. Result generation
+    """
+    def __init__(self, enable_language_detection: bool = False, skip_expensive_metrics: bool = False, parallel_executor: Optional[Executor] = None, parallel_execution: bool = True):
+        """
+        Initialize detection orchestrator
+        
+        Arguments:
+        ----------
+            enable_language_detection { bool } : Enable language detection step
+            skip_expensive_metrics    { bool } : Skip computationally expensive metrics
+            parallel_executor         { Executor } : Thread/Process executor for parallel processing
+            parallel_execution        { bool } : Enable parallel metric execution
+        """
+        self.enable_language_detection = enable_language_detection
+        self.skip_expensive_metrics    = skip_expensive_metrics
+        self.parallel_executor         = parallel_executor
+        self.parallel_execution        = parallel_execution
+        
+        # Initialize processors
+        self.text_processor            = TextProcessor()
+
+        self.domain_classifier         = DomainClassifier()
+        self.language_detector         = LanguageDetector(use_model = True) if self.enable_language_detection else None
+        
+        # Initialize metrics
+        self.metrics                   = self._initialize_metrics()
+        
+        # Initialize ensemble
+        self.ensemble                  = EnsembleClassifier(primary_method       = "confidence_calibrated",
+                                                            fallback_method      = "domain_weighted",
+                                                            min_metrics_required = 3,
+                                                           )
+        
+        logger.info(f"DetectionOrchestrator initialized (language_detection={enable_language_detection}, "
+                    f"skip_expensive={skip_expensive_metrics}, parallel={parallel_execution})")
+    
+
+    def _initialize_metrics(self) -> Dict[str, Any]:
+        """
+        Initialize all enabled metrics
+        """
+        metrics        = dict()
+        
+        # Define metric initialization order (simpler metrics first)
+        metric_classes = [("structural", StructuralMetric),
+                          ("entropy", EntropyMetric),
+                          ("perplexity", PerplexityMetric),
+                          ("semantic_analysis", SemanticAnalysisMetric),
+                          ("linguistic", LinguisticMetric),
+                          ("multi_perturbation_stability", MultiPerturbationStabilityMetric),
+                         ]
+        
+        for name, metric_class in metric_classes:
+            try:
+                metrics[name] = metric_class()
+                logger.debug(f"{name} metric initialized")
+            
+            except Exception as e:
+                logger.error(f"Failed to initialize {name} metric: {repr(e)}")
+        
+        logger.info(f"Initialized {len(metrics)} metrics: {list(metrics.keys())}")
+        return metrics
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize all components (load models, etc.)
+        
+        Returns:
+        --------
+            { bool } : True if successful, False otherwise
+        """
+        try:
+            logger.info("Initializing detection pipeline...")
+            
+            # Initialize processors
+            self._initialize_processors()
+            
+            # Initialize metrics
+            successful_metrics = self._initialize_metrics_components()
+            
+            # Need at least 3 metrics for reliable detection
+            pipeline_ready     = (successful_metrics >= 3)
+            
+            if pipeline_ready:
+                logger.success(f"Detection pipeline initialized: {successful_metrics}/{len(self.metrics)} metrics ready")
+            
+            else:
+                logger.warning(f"Pipeline may be unreliable: only {successful_metrics} metrics initialized (need at least 3)")
+            
+            return pipeline_ready
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize detection pipeline: {repr(e)}")
+            return False
+    
+
+    def _initialize_processors(self) -> None:
+        """
+        Initialize processor components
+        """
+        # Initialize domain classifier
+        if not self.domain_classifier.initialize():
+            logger.warning("Domain classifier initialization failed")
+        
+        # Initialize language detector
+        if self.language_detector and not self.language_detector.initialize():
+            logger.warning("Language detector initialization failed")
+    
+
+    def _initialize_metrics_components(self) -> int:
+        """
+        Initialize metric components and return count of successful initializations
+        """
+        successful_metrics = 0
+        
+        for name, metric in self.metrics.items():
+            try:
+                if metric.initialize():
+                    successful_metrics += 1
+                    logger.debug(f"✓ {name} metric ready")
+                
+                else:
+                    logger.warning(f"✗ {name} metric initialization failed")
+            
+            except Exception as e:
+                logger.error(f"Error initializing {name} metric: {repr(e)}")
+        
+        return successful_metrics
+    
+
+    def analyze(self, text: str, domain: Optional[Domain] = None, **kwargs) -> DetectionResult:
+        """
+        Analyze text and detect if synthetically-generated
+        
+        Arguments:
+        ----------
+            text       { str }   : Input text to analyze
+           
+            domain   { Domain }  : Override automatic domain detection
+           
+            **kwargs             : Additional options
+            
+        Returns:
+        --------
+            { DetectionResult }  : DetectionResult with complete analysis
+        """
+        start_time = time.time()
+        warnings   = list()
+        errors     = list()
+        
+        try:
+            # Step 1: Preprocess text
+            processed_text                         = self._preprocess_text(text     = text, 
+                                                                           warnings = warnings,
+                                                                          )
+            
+            # Step 2: Detect language
+            language_result                        = self._detect_language(processed_text = processed_text, 
+                                                                           warnings       = warnings,
+                                                                          )
+            
+            # Step 3: Classify domain
+            domain_prediction, domain              = self._classify_domain(processed_text = processed_text, 
+                                                                           user_domain    = domain, 
+                                                                           warnings       = warnings,
+                                                                          )
+            
+            # Step 4: Execute metrics (parallel or sequential)
+            metric_results, metrics_execution_time = self._execute_metrics_parallel(processed_text = processed_text, 
+                                                                                    domain         = domain, 
+                                                                                    warnings       = warnings, 
+                                                                                    errors         = errors,
+                                                                                    **kwargs
+                                                                                   )
+                                                                                
+            # Step 5: Ensemble aggregation
+            ensemble_result                        = self._aggregate_results(metric_results = metric_results, 
+                                                                             domain         = domain, 
+                                                                             errors         = errors,
+                                                                            )
+            
+            # Step 6: Compile final result
+            processing_time                        = time.time() - start_time
+            
+            return self._compile_result(ensemble_result         = ensemble_result,
+                                        processed_text          = processed_text,
+                                        domain_prediction       = domain_prediction,
+                                        language_result         = language_result,
+                                        metric_results          = metric_results,
+                                        processing_time         = processing_time,
+                                        metrics_execution_time  = metrics_execution_time,
+                                        warnings                = warnings,
+                                        errors                  = errors,
+                                        **kwargs,
+                                       )
+            
+        except Exception as e:
+            logger.error(f"Fatal error in detection pipeline: {repr(e)}")
+            return self._create_error_result(text, str(e), start_time)
+    
+
+    def _preprocess_text(self, text: str, warnings: List[str]) -> ProcessedText:
+        """
+        Preprocess text
+        """
+        logger.info("Step 1: Preprocessing text...")
+        processed_text = self.text_processor.process(text = text)
+        
+        if not processed_text.is_valid:
+            logger.warning(f"Text validation failed: {processed_text.validation_errors}")
+            warnings.extend(processed_text.validation_errors)
+        
+        return processed_text
+    
+
+    def _detect_language(self, processed_text: ProcessedText, warnings: List[str]) -> Optional[LanguageDetectionResult]:
+        """
+        Detect language
+        """
+        if not self.language_detector:
+            return None
+        
+        logger.info("Step 2: Detecting language...")
+        
+        try:
+            language_result = self.language_detector.detect(processed_text.cleaned_text)
+            
+            # Add relevant warnings
+            if (language_result.primary_language.value != "en"):
+                warnings.append(f"Non-English text detected ({language_result.primary_language.value}). Detection accuracy may be reduced.")
+            
+            if language_result.is_multilingual:
+                warnings.append("Multilingual content detected")
+            
+            if (language_result.evidence_strength < 0.7):
+                warnings.append(f"Low language detection evidence_strength ({language_result.evidence_strength:.2f})")
+            
+            return language_result
+            
+        except Exception as e:
+            logger.warning(f"Language detection failed: {repr(e)}")
+            warnings.append("Language detection failed")
+            return None
+    
+
+    def _classify_domain(self, processed_text: ProcessedText, user_domain: Optional[Domain], warnings: List[str]) -> Tuple[DomainPrediction, Domain]:
+        """
+        Classify domain
+        """
+        logger.info("Step 3: Classifying domain...")
+        
+        if user_domain is not None:
+            # Use provided domain
+            domain_prediction = DomainPrediction(primary_domain    = user_domain,
+                                                 secondary_domain  = None,
+                                                 evidence_strength = 1.0,
+                                                 domain_scores     = {user_domain.value: 1.0},
+                                                )
+            domain            = user_domain
+        
+        else:
+            # Automatically classify domain
+            try:
+                domain_prediction = self.domain_classifier.classify(processed_text.cleaned_text)
+                domain            = domain_prediction.primary_domain
+                
+                if (domain_prediction.evidence_strength < 0.5):
+                    warnings.append(f"Low domain classification Evidence Strength ({domain_prediction.evidence_strength:.2f})")
+            
+            except Exception as e:
+                logger.warning(f"Domain classification failed: {repr(e)}")
+                domain_prediction = DomainPrediction(primary_domain    = Domain.GENERAL,
+                                                     secondary_domain  = None,
+                                                     evidence_strength = 0.5,
+                                                     domain_scores     = {},
+                                                    )
+                domain            = Domain.GENERAL
+                warnings.append("Domain classification failed, using GENERAL")
+        
+        logger.info(f"Detected domain: {domain.value} (Evidence Strength: {domain_prediction.evidence_strength:.2f})")
+        return domain_prediction, domain
+    
+
+    def _execute_metrics_parallel(self, processed_text: ProcessedText, domain: Domain, warnings: List[str], errors: List[str], **kwargs) -> Tuple[Dict[str, MetricResult], Dict[str, float]]:
+        """
+        Execute metrics calculations in parallel with fallback to sequential
+        
+        Returns:
+        --------
+            Tuple[Dict[str, MetricResult], Dict[str, float]]: Metric results and execution times
+        """
+        logger.info("Step 4: Executing detection metrics calculations...")
+        
+        # Check if we should use parallel execution
+        use_parallel = self.parallel_execution and self.parallel_executor is not None
+        
+        if use_parallel:
+            logger.info("Using parallel execution for metrics")
+            try:
+                return self._execute_metrics_parallel_impl(processed_text = processed_text,
+                                                           domain         = domain,
+                                                           warnings       = warnings,
+                                                           errors         = errors,
+                                                           **kwargs
+                                                          )
+
+            except Exception as e:
+                logger.warning(f"Parallel execution failed, falling back to sequential: {repr(e)}")
+                warnings.append(f"Parallel execution failed: {str(e)[:100]}")
+                
+                return self._execute_metrics_sequential(processed_text = processed_text,
+                                                        domain         = domain,
+                                                        warnings       = warnings,
+                                                        errors         = errors,
+                                                        **kwargs
+                                                       )
+        
+        else:
+            logger.info("Using sequential execution for metrics")
+            return self._execute_metrics_sequential(processed_text = processed_text,
+                                                    domain         = domain,
+                                                    warnings       = warnings,
+                                                    errors         = errors,
+                                                    **kwargs
+                                                   )
+    
+
+    def _execute_metrics_parallel_impl(self, processed_text: ProcessedText, domain: Domain, warnings: List[str], errors: List[str], **kwargs) -> Tuple[Dict[str, MetricResult], Dict[str, float]]:
+        """
+        Execute metrics in parallel using thread pool
+        """
+        metric_results         = dict()
+        metrics_execution_time = dict()
+        futures                = dict()
+        
+        # Submit all metric computations to thread pool
+        for name, metric in self.metrics.items():
+            # Skip expensive metrics if configured
+            if (self.skip_expensive_metrics and (name == "multi_perturbation_stability")):
+                logger.info(f"Skipping expensive metric: {name}")
+                continue
+            
+            # Submit task to thread pool
+            future = self.parallel_executor.submit(self._compute_metric_wrapper,
+                                                   name           = name,
+                                                   metric         = metric,
+                                                   text           = processed_text.cleaned_text,
+                                                   domain         = domain,
+                                                   skip_expensive = self.skip_expensive_metrics,
+                                                   warnings       = warnings,
+                                                   errors         = errors
+                                                  )
+            futures[future] = name
+        
+        # Collect results as they complete
+        completed_count = 0
+        total_metrics   = len(futures)
+        
+        for future in as_completed(futures):
+            name             = futures[future]
+            completed_count += 1
+            
+            try:
+                result, execution_time, metric_warnings = future.result(timeout = 300)  # 5 minute timeout
+                
+                if result:
+                    metric_results[name]         = result
+                    metrics_execution_time[name] = execution_time
+                    
+                    if result.error:
+                        warnings.append(f"{name} metric error: {result.error}")
+                    
+                    if metric_warnings:
+                        warnings.extend(metric_warnings)
+                    
+                    logger.debug(f"Parallel metric completed: {name} ({execution_time:.2f}s) - {completed_count}/{total_metrics}")
+                
+            except Exception as e:
+                logger.error(f"Error computing metric {name} in parallel: {repr(e)}")
+                errors.append(f"{name}: {repr(e)}")
+                
+                # Create error result
+                metric_results[name] = MetricResult(metric_name           = name,
+                                                    synthetic_probability = 0.5,
+                                                    authentic_probability = 0.5,
+                                                    hybrid_probability    = 0.0,
+                                                    confidence            = 0.0,
+                                                    error                 = repr(e),
+                                                   )
+
+                metrics_execution_time[name] = 0.0
+        
+        logger.info(f"Parallel execution completed: {len(metric_results)}/{len(self.metrics)} metrics successful")
+        return metric_results, metrics_execution_time
+    
+
+    def _compute_metric_wrapper(self, name: str, metric: Any, text: str, domain: Domain, skip_expensive: bool, warnings: List[str], errors: List[str]) -> Tuple[Optional[MetricResult], float, List[str]]:
+        """
+        Wrapper function for parallel metric computation
+        """
+        metric_start    = time.time()
+        metric_warnings = list()
+        
+        try:
+            logger.debug(f"Computing metric in parallel: {name}")
+            
+            result = metric.compute(text           = text,
+                                    domain         = domain,
+                                    skip_expensive = skip_expensive,
+                                   )
+            
+            execution_time = time.time() - metric_start
+            
+            return result, execution_time, metric_warnings
+            
+        except Exception as e:
+            logger.error(f"Error computing metric {name} in wrapper: {repr(e)}")
+            execution_time = time.time() - metric_start
+            
+            # Create error result
+            error_result = MetricResult(metric_name           = name,
+                                        synthetic_probability = 0.5,
+                                        authentic_probability = 0.5,
+                                        hybrid_probability    = 0.0,
+                                        confidence            = 0.0,
+                                        error                 = repr(e),
+                                       )
+            
+            return error_result, execution_time, metric_warnings
+    
+
+    def _execute_metrics_sequential(self, processed_text: ProcessedText, domain: Domain, warnings: List[str], errors: List[str], **kwargs) -> Tuple[Dict[str, MetricResult], Dict[str, float]]:
+        """
+        Execute metrics calculations sequentially (fallback method)
+        """
+        metric_results         = dict()
+        metrics_execution_time = dict()
+        
+        for name, metric in self.metrics.items():
+            metric_start = time.time()
+           
+            try:
+                # Skip expensive metrics if configured
+                if (self.skip_expensive_metrics and (name == "multi_perturbation_stability")):
+                    logger.info(f"Skipping expensive metric: {name}")
+                    continue
+                
+                logger.debug(f"Computing metric sequentially: {name}")
+                
+                result = metric.compute(text           = processed_text.cleaned_text,
+                                        domain         = domain,
+                                        skip_expensive = self.skip_expensive_metrics,
+                                       )
+                
+                metric_results[name] = result
+                
+                if result.error:
+                    warnings.append(f"{name} metric error: {result.error}")
+            
+            except Exception as e:
+                logger.error(f"Error computing metric {name}: {repr(e)}")
+                errors.append(f"{name}: {repr(e)}")
+                
+                # Create error result
+                metric_results[name] = MetricResult(metric_name           = name,
+                                                    synthetic_probability = 0.5,
+                                                    authentic_probability = 0.5,
+                                                    hybrid_probability    = 0.0,
+                                                    confidence            = 0.0,
+                                                    error                 = repr(e),
+                                                   )
+            
+            finally:
+                metrics_execution_time[name] = time.time() - metric_start
+        
+        logger.info(f"Sequential execution completed: {len(metric_results)} metrics computed")
+        return metric_results, metrics_execution_time
+    
+
+    def _aggregate_results(self, metric_results: Dict[str, MetricResult], domain: Domain, errors: List[str]) -> EnsembleResult:
+        """
+        Ensemble aggregation
+        """
+        logger.info("Step 5: Aggregating results with ensemble...")
+        
+        try:
+            ensemble_result = self.ensemble.predict(metric_results = metric_results,
+                                                    domain         = domain,
+                                                   )
+            
+            logger.success(f"Ensemble result: {ensemble_result.final_verdict} (Synthetic probability: {ensemble_result.synthetic_probability:.1%}, confidence: {ensemble_result.overall_confidence:.2f})")
+            
+            return ensemble_result
+            
+        except Exception as e:
+            logger.error(f"Ensemble prediction failed: {repr(e)}")
+            errors.append(f"Ensemble: {repr(e)}")
+            
+            # Create fallback result    
+            return EnsembleResult(final_verdict         = "Uncertain",
+                                  synthetic_probability = 0.5,
+                                  authentic_probability = 0.5,
+                                  hybrid_probability    = 0.0,
+                                  overall_confidence    = 0.0,
+                                  domain                = domain,
+                                  metric_results        = metric_results,
+                                  metric_weights        = {},
+                                  weighted_scores       = {},
+                                  reasoning             = ["Ensemble aggregation failed"],
+                                  uncertainty_score     = 1.0,
+                                  consensus_level       = 0.0,
+                                 )
+    
+
+    def _compile_result(self, ensemble_result: EnsembleResult, processed_text: ProcessedText, domain_prediction: DomainPrediction, language_result: Optional[LanguageDetectionResult],
+                        metric_results: Dict[str, MetricResult], processing_time: float, metrics_execution_time: Dict[str, float], warnings: List[str], errors: List[str], **kwargs) -> DetectionResult:
+        """
+        Compile final detection result
+        """
+        logger.info("Step 6: Compiling final detection result...")
+        
+        # Include file info if provided
+        file_info      = kwargs.get('file_info')
+        
+        # Add parallel execution info
+        execution_mode = "parallel" if (self.parallel_execution and self.parallel_executor) else "sequential"
+        
+        return DetectionResult(ensemble_result        = ensemble_result,
+                               processed_text         = processed_text,
+                               domain_prediction      = domain_prediction,
+                               language_result        = language_result,
+                               metric_results         = metric_results,
+                               processing_time        = processing_time,
+                               metrics_execution_time = metrics_execution_time,
+                               warnings               = warnings,
+                               errors                 = errors,
+                               file_info              = file_info,
+                               execution_mode         = execution_mode,
+                              )
+    
+
+    def _create_error_result(self, text: str, error_message: str, start_time: float) -> DetectionResult:
+        """
+        Create error result when pipeline fails
+        """
+        processing_time = time.time() - start_time
+        
+        return DetectionResult(ensemble_result        = EnsembleResult(final_verdict         = "Uncertain",
+                                                                       synthetic_probability = 0.5,
+                                                                       authentic_probability = 0.5,
+                                                                       hybrid_probability    = 0.0,
+                                                                       overall_confidence    = 0.0,
+                                                                       domain                = Domain.GENERAL,
+                                                                       metric_results        = {},
+                                                                       metric_weights        = {},
+                                                                       weighted_scores       = {},
+                                                                       reasoning             = [f"Fatal error: {error_message}"],
+                                                                       uncertainty_score     = 1.0,
+                                                                       consensus_level       = 0.0,
+                                                                      ),
+                               processed_text         = ProcessedText(original_text       = text,
+                                                                      cleaned_text        = "",
+                                                                      sentences           = [],
+                                                                      words               = [],
+                                                                      paragraphs          = [],
+                                                                      char_count          = 0,
+                                                                      word_count          = 0,
+                                                                      sentence_count      = 0,
+                                                                      paragraph_count     = 0,
+                                                                      avg_sentence_length = 0.0,
+                                                                      avg_word_length     = 0.0,
+                                                                      is_valid            = False,
+                                                                      validation_errors   = ["Processing failed"],
+                                                                      metadata            = {},
+                                                                     ),
+                               domain_prediction      = DomainPrediction(primary_domain    = Domain.GENERAL,
+                                                                         secondary_domain  = None,
+                                                                         evidence_strength = 0.0,
+                                                                         domain_scores     = {},
+                                                                        ),
+                               language_result        = None,
+                               metric_results         = {},
+                               processing_time        = processing_time,
+                               metrics_execution_time = {},
+                               warnings               = [],
+                               errors                 = [f"Fatal error: {error_message}"],
+                               file_info              = None,
+                               execution_mode         = "error",
+                              )
+    
+
+    def batch_analyze(self, texts: List[str], domain: Optional[Domain] = None) -> List[DetectionResult]:
+        """
+        Analyze multiple texts
+        
+        Arguments:
+        ----------
+            texts    { list }  : List of texts to analyze
+
+            domain  { Domain } : Override automatic domain detection
+            
+        Returns:
+        --------
+               { list }        : List of DetectionResult objects
+        """
+        logger.info(f"Batch analyzing {len(texts)} texts...")
+        
+        results = list()
+        
+        for i, text in enumerate(texts):
+            logger.info(f"Analyzing text {i+1}/{len(texts)}...")
+            try:
+                result = self.analyze(text   = text, 
+                                      domain = domain,
+                                     )
+                
+                results.append(result)
+            
+            except Exception as e:
+                logger.error(f"Error analyzing text {i+1}: {repr(e)}")
+                # Create error result for this text
+                results.append(self._create_error_result(text, str(e), time.time()))
+        
+        successful = sum(1 for r in results if r.ensemble_result.final_verdict != "Uncertain")
+        logger.info(f"Batch analysis complete: {successful}/{len(texts)} processed successfully")
+        
+        return results
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        logger.info("Cleaning up detection orchestrator...")
+        
+        # Clean up metrics
+        self._cleanup_metrics()
+        
+        # Clean up processors
+        self._cleanup_processors()
+        
+        # Clean up parallel executor if we own it
+        if hasattr(self, '_own_executor') and self._own_executor:
+            try:
+                self.parallel_executor.shutdown(wait=True)
+                logger.debug("Cleaned up parallel executor")
+            except Exception as e:
+                logger.warning(f"Error cleaning up parallel executor: {repr(e)}")
+        
+        logger.info("Cleanup complete")
+    
+
+    def _cleanup_metrics(self) -> None:
+        """
+        Clean up metric resources
+        """
+        for name, metric in self.metrics.items():
+            try:
+                metric.cleanup()
+                logger.debug(f"Cleaned up metric: {name}")
+            
+            except Exception as e:
+                logger.warning(f"Error cleaning up metric {name}: {repr(e)}")
+    
+
+    def _cleanup_processors(self) -> None:
+        """
+        Clean up processor resources
+        """
+        if self.domain_classifier:
+            try:
+                self.domain_classifier.cleanup()
+                logger.debug("Cleaned up domain classifier")
+           
+            except Exception as e:
+                logger.warning(f"Error cleaning up domain classifier: {repr(e)}")
+        
+        if self.language_detector:
+            try:
+                self.language_detector.cleanup()
+                logger.debug("Cleaned up language detector")
+        
+            except Exception as e:
+                logger.warning(f"Error cleaning up language detector: {repr(e)}")
+    
+
+    @classmethod
+    def create_with_executor(cls, max_workers: int = 4, **kwargs):
+        """
+        Factory method to create orchestrator with its own executor
+        
+        Arguments:
+        ----------
+            max_workers { int } : Maximum number of parallel workers
+
+            **kwargs            : Additional arguments for DetectionOrchestrator
+            
+        Returns:
+        --------
+            { DetectionOrchestrator } : Orchestrator with thread pool executor
+        """
+        executor                   = ThreadPoolExecutor(max_workers = max_workers)
+        orchestrator               = cls(parallel_executor = executor, **kwargs)
+        orchestrator._own_executor = True
+
+        return orchestrator
+
+
+
+# Export
+__all__ = ["DetectionOrchestrator"]

{reporter → services}/reasoning_generator.py

@@ -1,58 +1,17 @@
 # DEPENDENCIES
-import numpy as np
 from typing import Any
 from typing import Dict
 from typing import List
 from typing import Optional
-from dataclasses import dataclass
-from detector.attribution import AIModel
-from config.threshold_config import Domain
-from metrics.base_metric import MetricResult
-from detector.ensemble import EnsembleResult
-from detector.attribution import AttributionResult 
-
-
-
-@dataclass
-class DetailedReasoning:
-    """
-    Comprehensive reasoning for detection result with ensemble integration
-    """
-    summary                : str
-    key_indicators         : List[str]
-    metric_explanations    : Dict[str, str]
-    supporting_evidence    : List[str]
-    contradicting_evidence : List[str]
-    confidence_explanation : str
-    domain_analysis        : str
-    ensemble_analysis      : str
-    attribution_reasoning  : Optional[str]
-    recommendations        : List[str]
-    uncertainty_analysis   : str
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"summary"                : self.summary,
-                "key_indicators"         : self.key_indicators,
-                "metric_explanations"    : self.metric_explanations,
-                "supporting_evidence"    : self.supporting_evidence,
-                "contradicting_evidence" : self.contradicting_evidence,
-                "confidence_explanation" : self.confidence_explanation,
-                "domain_analysis"        : self.domain_analysis,
-                "ensemble_analysis"      : self.ensemble_analysis,
-                "attribution_reasoning"  : self.attribution_reasoning,
-                "recommendations"        : self.recommendations,
-                "uncertainty_analysis"   : self.uncertainty_analysis,
-               }
-
+from config.enums import Domain
+from config.schemas import MetricResult
+from config.schemas import EnsembleResult
+from config.schemas import DetailedReasoningResult
 
 
 class ReasoningGenerator:
     """
-    Generates detailed, human-readable reasoning for AI detection results with ensemble and domain-aware integration
+    Generates detailed, human-readable reasoning for Synthetic detection results with ensemble and domain-aware integration
     
     Features:
     - Ensemble method explanation
@@ -62,43 +21,42 @@ class ReasoningGenerator:
     - Actionable recommendations
     """
     # Metric descriptions 
-    METRIC_DESCRIPTIONS = {"structural"                   : "analyzes sentence structure, length patterns, and statistical features",
-                           "perplexity"                   : "measures text predictability using language model cross-entropy",
-                           "entropy"                      : "evaluates token diversity and sequence unpredictability",
-                           "semantic_analysis"            : "examines semantic coherence, topic consistency, and logical flow",
-                           "linguistic"                   : "assesses grammatical patterns, syntactic complexity, and style markers",
-                           "multi_perturbation_stability" : "tests text stability under perturbation using curvature analysis",
-                          }
+    METRIC_DESCRIPTIONS  = {"structural"                   : "analyzes sentence structure, length patterns, and statistical features",
+                            "perplexity"                   : "measures text predictability using language model cross-entropy",
+                            "entropy"                      : "evaluates token diversity and sequence unpredictability",
+                            "semantic_analysis"            : "examines semantic coherence, topic consistency, and logical flow",
+                            "linguistic"                   : "assesses grammatical patterns, syntactic complexity, and style markers",
+                            "multi_perturbation_stability" : "tests text stability under perturbation using curvature analysis",
+                           }
     
     # Ensemble method descriptions
-    ENSEMBLE_METHODS    = {"confidence_calibrated" : "confidence-weighted aggregation with domain calibration",
-                           "domain_adaptive"       : "domain-specific metric performance weighting",
-                           "consensus_based"       : "rewarding metric agreement and consensus",
-                           "ml_ensemble"           : "machine learning-based meta-classification",
-                           "domain_weighted"       : "domain-aware static weighting of metrics",
-                          }
+    ENSEMBLE_METHODS     = {"confidence_calibrated" : "confidence-weighted aggregation with domain calibration",
+                            "consensus_based"       : "rewarding metric agreement and consensus",
+                            "domain_weighted"       : "domain-aware static weighting of metrics",
+                            "simple_average"        : "equal weighting of all metrics",
+                           }
     
-    # AI indicators aligned with current metric outputs
-    AI_INDICATORS       = {"low_perplexity"          : "Text shows high predictability to language models",
-                           "low_entropy"             : "Limited vocabulary diversity and repetitive patterns",
-                           "structural_uniformity"   : "Consistent sentence lengths and structural patterns",
-                           "semantic_perfection"     : "Unnaturally perfect coherence and logical flow",
-                           "linguistic_consistency"  : "Overly consistent grammatical patterns and style",
-                           "perturbation_instability": "Text changes significantly under minor modifications",
-                           "low_burstiness"          : "Lacks natural variation in writing intensity",
-                           "transition_overuse"      : "Excessive use of transitional phrases and connectors",
-                          }
+    # Synthetic indicators aligned with current metric outputs
+    SYNTHETIC_INDICATORS = {"low_perplexity"          : "Text shows high predictability to language models",
+                            "low_entropy"             : "Limited vocabulary diversity and repetitive patterns",
+                            "structural_uniformity"   : "Consistent sentence lengths and structural patterns",
+                            "semantic_perfection"     : "Unnaturally perfect coherence and logical flow",
+                            "linguistic_consistency"  : "Overly consistent grammatical patterns and style",
+                            "perturbation_instability": "Text changes significantly under minor modifications",
+                            "low_burstiness"          : "Lacks natural variation in writing intensity",
+                            "transition_overuse"      : "Excessive use of transitional phrases and connectors",
+                           }
     
-    # Human indicators
-    HUMAN_INDICATORS    = {"high_perplexity"       : "Creative, unpredictable word choices and phrasing",
-                           "high_entropy"          : "Rich vocabulary diversity and varied expressions",
-                           "structural_variation"  : "Natural variation in sentence lengths and structures",
-                           "semantic_naturalness"  : "Authentic, occasionally imperfect logical flow",
-                           "linguistic_diversity"  : "Varied grammatical constructions and personal style",
-                           "perturbation_stability": "Text remains consistent under minor modifications",
-                           "high_burstiness"       : "Natural variation in writing intensity and focus",
-                           "personal_voice"        : "Distinctive personal expressions and idioms",
-                          }
+    # Authentic indicators
+    AUTHENTIC_INDICATORS = {"high_perplexity"       : "Creative, unpredictable word choices and phrasing",
+                            "high_entropy"          : "Rich vocabulary diversity and varied expressions",
+                            "structural_variation"  : "Natural variation in sentence lengths and structures",
+                            "semantic_naturalness"  : "Authentic, occasionally imperfect logical flow",
+                            "linguistic_diversity"  : "Varied grammatical constructions and personal style",
+                            "perturbation_stability": "Text remains consistent under minor modifications",
+                            "high_burstiness"       : "Natural variation in writing intensity and focus",
+                            "personal_voice"        : "Distinctive personal expressions and idioms",
+                           }
 
     
     def __init__(self):
@@ -108,85 +66,97 @@ class ReasoningGenerator:
         pass
     
 
-    def generate(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult], domain: Domain, attribution_result: Optional[AttributionResult] = None, 
-                 text_length: int = 0, ensemble_method: str = "confidence_calibrated") -> DetailedReasoning:
+    def generate(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult], domain: Domain, text_length: int = 0, ensemble_method: str = "confidence_calibrated") -> DetailedReasoningResult:
         """
         Generate comprehensive reasoning for detection result with ensemble integration
         
         Arguments:
         ----------
-            ensemble_result    : Final ensemble prediction with weights and reasoning
+            ensemble_result   { EnsembleResult}  : Final ensemble prediction with weights and reasoning
 
-            metric_results     : Individual metric results from all 6 metrics
-            
-            domain             : Detected text domain for context-aware analysis
+            metric_results         { dict }      : Individual metric results from all metrics
             
-            attribution_result : Model attribution (if available)
+            domain                { Domain }     : Detected text domain for context-aware analysis
             
-            text_length        : Length of analyzed text in words
+            text_length            { int }       : Length of analyzed text in words
             
-            ensemble_method    : Method used for ensemble aggregation
+            ensemble_method        { str }       : Method used for ensemble aggregation
             
         Returns:
         --------
-            DetailedReasoning object with ensemble-aware analysis
+               { DetailedReasoningResult }       : DetailedReasoningResult object with ensemble-aware analysis
         """
         # Generate summary with ensemble context
-        summary                                     = self._generate_ensemble_summary(ensemble_result, domain, text_length, ensemble_method)
+        summary                                     = self._generate_ensemble_summary(ensemble_result = ensemble_result, 
+                                                                                      domain          = domain, 
+                                                                                      text_length     = text_length, 
+                                                                                      ensemble_method = ensemble_method,
+                                                                                     )
         
         # Identify key indicators with metric weights
-        key_indicators                              = self._identify_weighted_indicators(ensemble_result, metric_results)
+        key_indicators                              = self._identify_weighted_indicators(ensemble_result = ensemble_result, 
+                                                                                         metric_results  = metric_results,
+                                                                                        )
         
         # Generate metric explanations with confidence
-        metric_explanations                         = self._generate_metric_explanations(metric_results, ensemble_result.metric_weights)
+        metric_explanations                         = self._generate_metric_explanations(metric_results = metric_results, 
+                                                                                         metric_weights = ensemble_result.metric_weights,
+                                                                                        )
         
         # Compile evidence with ensemble consensus
-        supporting_evidence, contradicting_evidence = self._compile_ensemble_evidence(ensemble_result, metric_results)
+        supporting_evidence, contradicting_evidence = self._compile_ensemble_evidence(ensemble_result = ensemble_result, 
+                                                                                      metric_results  = metric_results,
+                                                                                     )
         
         # Explain confidence with uncertainty
-        confidence_explanation                      = self._explain_confidence_with_uncertainty(ensemble_result, metric_results)
+        confidence_explanation                      = self._explain_confidence_with_uncertainty(ensemble_result = ensemble_result, 
+                                                                                                metric_results  = metric_results,
+                                                                                               )
         
         # Domain-specific analysis
-        domain_analysis                             = self._generate_domain_analysis(domain, metric_results, ensemble_result)
+        domain_analysis                             = self._generate_domain_analysis(domain          = domain, 
+                                                                                     metric_results  = metric_results, 
+                                                                                     ensemble_result = ensemble_result,
+                                                                                    )
         
         # Ensemble methodology explanation
-        ensemble_analysis                           = self._explain_ensemble_methodology(ensemble_result, ensemble_method)
-        
-        # Attribution reasoning
-        attribution_reasoning                       = None
-
-        if attribution_result:
-            attribution_reasoning = self._generate_attribution_reasoning(attribution_result)
+        ensemble_analysis                           = self._explain_ensemble_methodology(ensemble_result = ensemble_result, 
+                                                                                         ensemble_method = ensemble_method,
+                                                                                        )
         
         # Uncertainty analysis
-        uncertainty_analysis = self._analyze_uncertainty(ensemble_result)
+        uncertainty_analysis                        = self._analyze_uncertainty(ensemble_result = ensemble_result)
         
         # Generate recommendations
-        recommendations      = self._generate_ensemble_recommendations(ensemble_result, metric_results, domain)
-        
-        return DetailedReasoning(summary                = summary,
-                                 key_indicators         = key_indicators,
-                                 metric_explanations    = metric_explanations,
-                                 supporting_evidence    = supporting_evidence,
-                                 contradicting_evidence = contradicting_evidence,
-                                 confidence_explanation = confidence_explanation,
-                                 domain_analysis        = domain_analysis,
-                                 ensemble_analysis      = ensemble_analysis,
-                                 attribution_reasoning  = attribution_reasoning,
-                                 recommendations        = recommendations,
-                                 uncertainty_analysis   = uncertainty_analysis,
-                                )
+        recommendations                             = self._generate_ensemble_recommendations(ensemble_result = ensemble_result,
+                                                                                              metric_results  = metric_results, 
+                                                                                              domain          = domain,
+                                                                                             )
+        
+        return DetailedReasoningResult(summary                = summary,
+                                       key_indicators         = key_indicators,
+                                       metric_explanations    = metric_explanations,
+                                       supporting_evidence    = supporting_evidence,
+                                       contradicting_evidence = contradicting_evidence,
+                                       confidence_explanation = confidence_explanation,
+                                       domain_analysis        = domain_analysis,
+                                       ensemble_analysis      = ensemble_analysis,
+                                       recommendations        = recommendations,
+                                       uncertainty_analysis   = uncertainty_analysis,
+                                      )
     
 
     def _generate_ensemble_summary(self, ensemble_result: EnsembleResult, domain: Domain, text_length: int, ensemble_method: str) -> str:
         """
         Generate executive summary with ensemble context
         """
-        verdict     = ensemble_result.final_verdict
-        ai_prob     = ensemble_result.ai_probability
-        confidence  = ensemble_result.overall_confidence
-        uncertainty = ensemble_result.uncertainty_score
-        consensus   = ensemble_result.consensus_level
+        verdict        = ensemble_result.final_verdict
+        synthetic_prob = ensemble_result.synthetic_probability
+        authentic_prob = ensemble_result.authentic_probability
+        hybrid_prob    = ensemble_result.hybrid_probability
+        confidence     = ensemble_result.overall_confidence
+        uncertainty    = ensemble_result.uncertainty_score
+        consensus      = ensemble_result.consensus_level
         
         # Confidence level description
         if (confidence >= 0.8):
@@ -211,34 +181,34 @@ class ReasoningGenerator:
         else:
             consensus_desc = "low consensus"
         
-        # Build summary based on verdict and ensemble metrics
+        # Build summary based on verdict
         summary_parts = list()
         
-        if ("AI-Generated" in verdict):
+        if (verdict == "Synthetically-Generated"):
             summary_parts.append(f"Ensemble analysis indicates with {conf_desc} ({confidence:.1%}) that this text is "
-                                 f"**likely AI-generated** (AI probability: {ai_prob:.1%})."
-                                )
-
-        elif ("Human-Written" in verdict):
-            human_prob = ensemble_result.human_probability
+                                 f"**likely synthetically-generated** (synthetic probability: {synthetic_prob:.1%}).")
+        
+        elif( verdict == "Authentically-Written"):
             summary_parts.append(f"Ensemble analysis indicates with {conf_desc} ({confidence:.1%}) that this text is "
-                                 f"**likely human-written** (human probability: {human_prob:.1%})."
-                                )
-
-        elif( "Mixed" in verdict):
-            mixed_prob = ensemble_result.mixed_probability
+                                 f"**likely authentically-written** (authentic probability: {authentic_prob:.1%}).")
+        
+        elif (verdict == "Hybrid"):
             summary_parts.append(f"Ensemble analysis indicates with {conf_desc} ({confidence:.1%}) that this text "
-                                 f"**contains mixed AI-human content** (mixed probability: {mixed_prob:.1%})."
-                                )
+                                 f"**contains mixed synthetic/authentic content** (hybrid probability: {hybrid_prob:.1%}).")
         
-        else:
+        else:  
+            # Uncertain
             summary_parts.append(f"Ensemble analysis is **inconclusive** (confidence: {confidence:.1%}).")
         
         # Add ensemble context
         summary_parts.append(f"Metrics show {consensus_desc} among detection methods. Uncertainty level: {uncertainty:.1%}.")
         
         # Add domain and length context
-        summary_parts.append(f"Analysis of {text_length:,} words in **{domain.value}** domain using {self.ENSEMBLE_METHODS.get(ensemble_method, ensemble_method)} ensemble method.")
+        if (text_length > 0):
+            summary_parts.append(f"Analysis of {text_length:,} words in **{domain.value}** domain using {self.ENSEMBLE_METHODS.get(ensemble_method, ensemble_method)} ensemble method.")
+        
+        else:
+            summary_parts.append(f"Analysis in **{domain.value}** domain using {self.ENSEMBLE_METHODS.get(ensemble_method, ensemble_method)} ensemble method.")
         
         return " ".join(summary_parts)
     
@@ -248,26 +218,28 @@ class ReasoningGenerator:
         Identify top indicators considering metric weights and contributions
         """
         indicators       = list()
-        is_ai            = "AI-Generated" in ensemble_result.final_verdict
+        is_synthetic     = (ensemble_result.final_verdict == "Synthetically-Generated")
         
         # Use ensemble weights to prioritize indicators
-        weighted_metrics = list()
-
+        weighted_metrics = []
+        
         for name, result in metric_results.items():
             if result.error:
                 continue
+            
             weight         = ensemble_result.metric_weights.get(name, 0.0)
             confidence     = result.confidence
             # Combine weight and confidence for prioritization
             priority_score = weight * confidence
-
+            
             weighted_metrics.append((name, result, priority_score))
         
         # Sort by priority score
         weighted_metrics.sort(key = lambda x: x[2], reverse = True)
-         
-        for name, result, priority_score in weighted_metrics[:5]:
-            key_feature = self._extract_ensemble_feature(name, result, is_ai, priority_score)
+        
+        for name, result, priority_score in weighted_metrics[:5]:  
+            # Top 5 metrics
+            key_feature = self._extract_ensemble_feature(name, result, is_synthetic, priority_score)
             
             if key_feature:
                 weight_pct = ensemble_result.metric_weights.get(name, 0.0) * 100
@@ -276,7 +248,7 @@ class ReasoningGenerator:
         return indicators
     
 
-    def _extract_ensemble_feature(self, metric_name: str, result: MetricResult, is_ai: bool, priority_score: float) -> Optional[str]:
+    def _extract_ensemble_feature(self, metric_name: str, result: MetricResult, is_synthetic: bool, priority_score: float) -> Optional[str]:
         """
         Extract significant features considering ensemble context
         """
@@ -286,66 +258,58 @@ class ReasoningGenerator:
             burstiness = details.get("burstiness_score", 0.5)
             uniformity = details.get("length_uniformity", 0.5)
             
-            if (is_ai and (burstiness < 0.4)):
-                return f"Low burstiness ({burstiness:.2f}) suggests uniform AI patterns"
+            if (is_synthetic and (burstiness < 0.4)):
+                return f"Low burstiness ({burstiness:.2f}) suggests uniform synthetic patterns"
             
-            elif (not is_ai and (burstiness > 0.6)):
+            elif (not is_synthetic and (burstiness > 0.6)):
                 return f"High burstiness ({burstiness:.2f}) indicates natural variation"
-
-            elif (is_ai and (uniformity > 0.7)):
-                return f"High structural uniformity ({uniformity:.2f}) typical of AI"
-                
-
+            
+            elif (is_synthetic and (uniformity > 0.7)):
+                return f"High structural uniformity ({uniformity:.2f}) typical of synthetic text"
+            
         elif (metric_name == "perplexity"):
             perplexity = details.get("overall_perplexity", 50)
             
-            if (is_ai and (perplexity < 35)):
+            if (is_synthetic and perplexity < 35):
                 return f"Low perplexity ({perplexity:.1f}) indicates high predictability"
-
-            elif (not is_ai and (perplexity > 55)):
+            
+            elif (not is_synthetic and (perplexity > 55)):
                 return f"High perplexity ({perplexity:.1f}) suggests human creativity"
-                
-
+            
         elif (metric_name == "entropy"):
-            token_diversity  = details.get("token_diversity", 0.5)
-            sequence_entropy = details.get("sequence_entropy", 0.5)
+            token_diversity = details.get("token_diversity", 0.5)
             
-            if (is_ai and (token_diversity < 0.65)):
-                return f"Low token diversity ({token_diversity:.2f}) suggests AI patterns"
-
-            elif (not is_ai and (token_diversity > 0.75)):
+            if (is_synthetic and (token_diversity < 0.65)):
+                return f"Low token diversity ({token_diversity:.2f}) suggests synthetic patterns"
+            
+            elif (not is_synthetic and (token_diversity > 0.75)):
                 return f"High token diversity ({token_diversity:.2f}) indicates human variety"
-
-
+            
         elif (metric_name == "semantic_analysis"):
-            coherence   = details.get("coherence_score", 0.5)
-            consistency = details.get("consistency_score", 0.5)
+            coherence = details.get("coherence_score", 0.5)
             
-            if (is_ai and (coherence > 0.8)):
-                return f"Unnaturally high coherence ({coherence:.2f}) typical of AI"
-
-            elif (not is_ai and (0.4 <= coherence <= 0.7)):
+            if (is_synthetic and (coherence > 0.8)):
+                return f"Unnaturally high coherence ({coherence:.2f}) typical of synthetic text"
+            
+            elif (not is_synthetic and (0.4 <= coherence <= 0.7)):
                 return f"Natural coherence variation ({coherence:.2f})"
-                
-
+            
         elif (metric_name == "linguistic"):
-            pos_diversity        = details.get("pos_diversity", 0.5)
-            syntactic_complexity = details.get("syntactic_complexity", 2.5)
+            pos_diversity = details.get("pos_diversity", 0.5)
             
-            if (is_ai and (pos_diversity < 0.4)):
+            if (is_synthetic and (pos_diversity < 0.4)):
                 return f"Limited grammatical diversity ({pos_diversity:.2f})"
-
-            elif (not is_ai and (pos_diversity > 0.55)):
+            
+            elif (not is_synthetic and (pos_diversity > 0.55)):
                 return f"Rich grammatical variety ({pos_diversity:.2f})"
                 
         elif (metric_name == "multi_perturbation_stability"):
             stability = details.get("stability_score", 0.5)
-            curvature = details.get("curvature_score", 0.5)
             
-            if (is_ai and (stability > 0.6)):
-                return f"High perturbation instability ({stability:.2f})"
-
-            elif (not is_ai and (stability < 0.4)):
+            if (is_synthetic and (stability > 0.6)):
+                return f"High perturbation sensitivity ({stability:.2f})"
+            
+            elif (not is_synthetic and (stability < 0.4)):
                 return f"Text stability under perturbation ({stability:.2f})"
         
         return None
@@ -363,30 +327,27 @@ class ReasoningGenerator:
                 continue
             
             # Get metric description
-            desc         = self.METRIC_DESCRIPTIONS.get(name, "analyzes text characteristics")
+            desc        = self.METRIC_DESCRIPTIONS.get(name, "analyzes text characteristics")
             
             # Get weight information
             weight      = metric_weights.get(name, 0.0)
             weight_info = f" (ensemble weight: {weight:.1%})" if weight > 0 else " (low weight in ensemble)"
             
-            # Determine verdict
-            if (result.ai_probability > 0.6):
-                verdict = "suggests AI generation"
-                prob    = result.ai_probability
-
-            elif (result.human_probability > 0.6):
-                verdict = "indicates human writing"
-                prob    = result.human_probability
-
+            # Determine verdict based on probabilities
+            if (result.synthetic_probability > 0.6):
+                verdict = "suggests synthetic generation"
+                prob    = result.synthetic_probability
+            
+            elif (result.authentic_probability > 0.6):
+                verdict = "indicates authentic writing"
+                prob    = result.authentic_probability
+            
             else:
                 verdict = "shows mixed signals"
-                prob    = max(result.ai_probability, result.human_probability)
+                prob    = max(result.synthetic_probability, result.authentic_probability)
             
             # Build explanation with confidence
-            explanation        = (f"This metric {desc}.{weight_info} "
-                                  f"Result: {verdict} ({prob:.1%} probability) "
-                                  f"with {result.confidence:.1%} confidence."
-                                 )
+            explanation = (f"This metric {desc}.{weight_info} Result: {verdict} ({prob:.1%} probability) with {result.confidence:.1%} confidence.")
             
             explanations[name] = explanation
         
@@ -397,32 +358,32 @@ class ReasoningGenerator:
         """
         Compile evidence considering ensemble consensus and weights
         """
-        is_ai_verdict = "AI-Generated" in ensemble_result.final_verdict
-        consensus     = ensemble_result.consensus_level
+        is_synthetic_verdict = (ensemble_result.final_verdict == "Synthetically-Generated")
+        consensus            = ensemble_result.consensus_level
         
-        supporting    = list()
-        contradicting = list()
+        supporting           = list()
+        contradicting        = list()
         
         for name, result in metric_results.items():
             if result.error:
                 continue
             
-            weight             = ensemble_result.metric_weights.get(name, 0.0)
-            metric_suggests_ai = result.ai_probability > result.human_probability
+            weight                    = ensemble_result.metric_weights.get(name, 0.0)
+            metric_suggests_synthetic = (result.synthetic_probability > result.authentic_probability)
             
             # Weight the evidence by metric importance
-            weight_indicator   = "🟢" if weight > 0.15 else "🟡" if weight > 0.08 else "⚪"
+            weight_indicator          = "🟢" if (weight > 0.15) else "🟡" if (weight > 0.08) else "⚪"
             
-            if (metric_suggests_ai == is_ai_verdict):
+            if (metric_suggests_synthetic == is_synthetic_verdict):
                 # Supporting evidence
-                indicator = self._get_ai_indicator_from_metric(name, result) if is_ai_verdict else self._get_human_indicator_from_metric(name, result)
+                indicator = self._get_synthetic_indicator_from_metric(name, result) if is_synthetic_verdict else self._get_authentic_indicator_from_metric(name, result)
                 
                 if indicator:
                     supporting.append(f"{weight_indicator} {indicator}")
             
             else:
                 # Contradicting evidence
-                indicator = self._get_human_indicator_from_metric(name, result) if is_ai_verdict else self._get_ai_indicator_from_metric(name, result)
+                indicator = self._get_authentic_indicator_from_metric(name, result) if is_synthetic_verdict else self._get_synthetic_indicator_from_metric(name, result)
                 
                 if indicator:
                     contradicting.append(f"{weight_indicator} {indicator}")
@@ -430,56 +391,56 @@ class ReasoningGenerator:
         # Add consensus context
         if (consensus > 0.7):
             supporting.insert(0, "✅ Strong metric consensus supports this conclusion")
-
+        
         elif (consensus < 0.4):
             contradicting.insert(0, "⚠️ Low metric consensus indicates uncertainty")
         
         return supporting, contradicting
     
 
-    def _get_ai_indicator_from_metric(self, metric_name: str, result: MetricResult) -> Optional[str]:
+    def _get_synthetic_indicator_from_metric(self, metric_name: str, result: MetricResult) -> Optional[str]:
         """
-        Get AI indicator from metric result
+        Get synthetic indicator from metric result
         """
         details = result.details
         
         if (metric_name == "structural"):
             if (details.get("burstiness_score", 1.0) < 0.4):
-                return self.AI_INDICATORS["low_burstiness"]
-
+                return self.SYNTHETIC_INDICATORS["low_burstiness"]
+            
         elif (metric_name == "perplexity"):
             if (details.get("overall_perplexity", 100) < 35):
-                return self.AI_INDICATORS["low_perplexity"]
-
+                return self.SYNTHETIC_INDICATORS["low_perplexity"]
+            
         elif (metric_name == "entropy"):
             if (details.get("token_diversity", 1.0) < 0.65):
-                return self.AI_INDICATORS["low_entropy"]
-
+                return self.SYNTHETIC_INDICATORS["low_entropy"]
+            
         elif (metric_name == "semantic_analysis"):
             if (details.get("coherence_score", 0.5) > 0.75):
-                return self.AI_INDICATORS["semantic_perfection"]
-
+                return self.SYNTHETIC_INDICATORS["semantic_perfection"]
+            
         return None
     
 
-    def _get_human_indicator_from_metric(self, metric_name: str, result: MetricResult) -> Optional[str]:
+    def _get_authentic_indicator_from_metric(self, metric_name: str, result: MetricResult) -> Optional[str]:
         """
-        Get human indicator from metric result
+        Get authentic indicator from metric result
         """
         details = result.details
         
         if (metric_name == "structural"):
             if (details.get("burstiness_score", 0.0) > 0.6):
-                return self.HUMAN_INDICATORS["high_burstiness"]
-
+                return self.AUTHENTIC_INDICATORS["high_burstiness"]
+            
         elif (metric_name == "perplexity"):
             if (details.get("overall_perplexity", 0) > 55):
-                return self.HUMAN_INDICATORS["high_perplexity"]
-
+                return self.AUTHENTIC_INDICATORS["high_perplexity"]
+            
         elif (metric_name == "entropy"):
             if (details.get("token_diversity", 0.0) > 0.75):
-                return self.HUMAN_INDICATORS["high_entropy"]
-
+                return self.AUTHENTIC_INDICATORS["high_entropy"]
+            
         return None
     
 
@@ -499,10 +460,10 @@ class ReasoningGenerator:
         
         if (confidence >= 0.8):
             explanation += "High confidence due to: strong metric agreement, clear patterns, and reliable signal across multiple detection methods."
-       
+        
         elif (confidence >= 0.6):
             explanation += "Good confidence supported by: general metric agreement and consistent detection patterns."
-
+        
         else:
             explanation += "Lower confidence reflects: metric disagreement, ambiguous patterns, or borderline characteristics."
         
@@ -528,9 +489,10 @@ class ReasoningGenerator:
         
         # Add domain-specific threshold context
         threshold_info  = {Domain.ACADEMIC      : "Higher detection thresholds applied for academic rigor",
-                           Domain.TECHNICAL_DOC : "Elevated thresholds for technical precision requirements", 
+                           Domain.TECHNICAL_DOC : "Elevated thresholds for technical precision requirements",
                            Domain.CREATIVE      : "Balanced thresholds accounting for creative expression",
                            Domain.SOCIAL_MEDIA  : "Adapted thresholds for informal communication patterns",
+                           Domain.GENERAL       : "Standard detection thresholds applied",
                           }
         
         threshold_note  = threshold_info.get(domain, "Standard detection thresholds applied")
@@ -546,8 +508,8 @@ class ReasoningGenerator:
         
         explanation = f"**Ensemble Methodology**: {method_desc}\n\n"
         
-        # Explain key top-5 metrics
-        top_metrics = sorted(ensemble_result.metric_weights.items(), key = lambda x: x[1], reverse = True)[:5]
+        # Explain key top metrics
+        top_metrics = sorted(ensemble_result.metric_weights.items(), key=lambda x: x[1], reverse=True)[:3]
         
         if top_metrics:
             explanation += "**Top contributing metrics**:\n"
@@ -556,11 +518,14 @@ class ReasoningGenerator:
         
         # Add reasoning snippets if available
         if hasattr(ensemble_result, 'reasoning') and ensemble_result.reasoning:
+            # Filter out section headers and take first 2 key reasons
             key_reasons = [r for r in ensemble_result.reasoning if not r.startswith('##')][:2]
             if key_reasons:
                 explanation += "\n**Key ensemble factors**:\n"
                 for reason in key_reasons:
-                    explanation += f"• {reason}\n"
+                    # Clean up the reason text
+                    clean_reason = reason.replace('**', '').replace('✓', '').replace('⚠', '').strip()
+                    explanation += f"• {clean_reason}\n"
         
         return explanation
     
@@ -573,7 +538,7 @@ class ReasoningGenerator:
         
         if (uncertainty < 0.3):
             return "**Low Uncertainty**: Clear detection signals with strong metric agreement. Results are highly reliable."
-
+        
         elif (uncertainty < 0.6):
             return "**Moderate Uncertainty**: Some metric disagreement or borderline characteristics. Consider additional context."
         
@@ -581,40 +546,6 @@ class ReasoningGenerator:
             return "**High Uncertainty**: Significant metric disagreement or ambiguous patterns. Results should be interpreted with caution and additional verification may be needed."
     
 
-    def _generate_attribution_reasoning(self, attribution_result: AttributionResult) -> str:
-        """
-        Generate reasoning for model attribution
-        """
-        model       = attribution_result.predicted_model
-        confidence  = attribution_result.confidence
-        
-        if ((model == AIModel.UNKNOWN) or (confidence < 0.3)):
-            return "**Model Attribution**: Uncertain. Text patterns don't strongly match known AI model fingerprints."
-        
-        model_name  = model.value.replace("-", " ").replace("_", " ").title()
-        
-        reasoning   = f"**Attributed Model**: {model_name} (confidence: {confidence:.1%})\n\n"
-        
-        # Model characteristics
-        model_chars = {AIModel.GPT_3_5: "Characteristic patterns: frequent transitions, consistent structure, balanced explanations.",
-                       AIModel.GPT_4: "Advanced patterns: sophisticated vocabulary, nuanced analysis, well-structured arguments.", 
-                       AIModel.CLAUDE_3_OPUS: "Distinctive style: thoughtful analysis, balanced perspectives, explanatory depth.",
-                       AIModel.GEMINI_PRO: "Typical patterns: conversational tone, clear explanations, exploratory language.",
-                       AIModel.LLAMA_3: "Common traits: direct explanations, structured responses, consistent formatting.",
-                      }
-        
-        reasoning  += model_chars.get(model, "Shows characteristic AI writing patterns.")
-        
-        # Add fingerprint matches if available
-        if attribution_result.fingerprint_matches:
-            reasoning += "\n\n**Top fingerprint matches**:"
-            
-            for model_name, score in list(attribution_result.fingerprint_matches.items())[:3]:
-                reasoning += f"\n• {model_name}: {score}% match"
-        
-        return reasoning
-    
-
     def _generate_ensemble_recommendations(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult], domain: Domain) -> List[str]:
         """
         Generate actionable recommendations based on ensemble results
@@ -625,26 +556,25 @@ class ReasoningGenerator:
         uncertainty     = ensemble_result.uncertainty_score
         
         # Base recommendations by verdict and confidence
-        if ("AI-Generated" in verdict):
+        if (verdict == "Synthetically-Generated"):
             if (confidence >= 0.8):
-                rec = "**High-confidence AI detection**: Consider verified original drafts or alternative assessment methods."
-
-            else:
-                rec = "**Likely AI involvement**: Recommend discussion about AI tool usage and verification of understanding."
-            
-            recommendations.append(rec)
+                recommendations.append("**High-confidence synthetic detection**: Consider verified original drafts or alternative assessment methods.")
             
-        elif ("Human-Written" in verdict):
+            else:
+                recommendations.append("**Likely synthetic involvement**: Recommend discussion about AI tool usage and verification of understanding.")
+        
+        elif (verdict == "Authentically-Written"):
             if (confidence >= 0.8):
-                rec = "**High-confidence human authorship**: No additional verification typically needed."
+                recommendations.append("**High-confidence authentic authorship**: No additional verification typically needed.")
             
             else:
-                rec = "**Likely human-written**: Consider context and writing history for complete assessment."
-            
-            recommendations.append(rec)
-            
-        elif ("Mixed" in verdict):
-            recommendations.append("**Mixed AI-human content**: Common in collaborative writing. Discuss appropriate AI use guidelines.")
+                recommendations.append("**Likely authentically-written**: Consider context and writing history for complete assessment.")
+        
+        elif (verdict == "Hybrid"):
+            recommendations.append("**Mixed synthetic/authentic content**: Common in collaborative writing. Discuss appropriate AI use guidelines.")
+        
+        elif (verdict == "Uncertain"):
+            recommendations.append("**Inconclusive result**: The analysis could not reach a clear determination. Additional context or verification may be needed.")
         
         # Uncertainty-based recommendations
         if (uncertainty > 0.6):
@@ -652,9 +582,10 @@ class ReasoningGenerator:
         
         # Domain-specific recommendations
         domain_recs = {Domain.ACADEMIC      : "For academic work: verify subject mastery through targeted questions or practical application.",
-                       Domain.CREATIVE      : "For creative work: assess originality, personal voice, and creative process documentation.", 
+                       Domain.CREATIVE      : "For creative work: assess originality, personal voice, and creative process documentation.",
                        Domain.TECHNICAL_DOC : "For technical content: verify practical expertise and problem-solving ability.",
-                     }
+                       Domain.SOFTWARE_DEV  : "For code documentation: verify understanding through code review or implementation questions.",
+                      }
         
         if domain in domain_recs:
             recommendations.append(domain_recs[domain])
@@ -670,6 +601,4 @@ class ReasoningGenerator:
 
 
 # Export
-__all__ = ["DetailedReasoning", 
-           "ReasoningGenerator",
-          ]
+__all__ = ["ReasoningGenerator"]

setup.sh

@@ -1,22 +0,0 @@
-#!/bin/bash
-
-# Post-installation setup script for Hugging Face Spaces 
-echo "Starting setup for Text-Authentication Platform ..."
-
-# Download Spacy Model
-echo "Downloading SpaCy English model ..."
-python -n spacy download en_core_web_sm
-
-# Download NLTK data
-echo "Downloading NLTK data ..."
-python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords'); nltk.download('averaged_perceptron_tagger')"
-
-# Create necessary directories
-echo "Creating directories ..."
-mkdir -p data/reports data/uploads
-
-# Verify installation
-echo "Verifying installations ..."
-python -c "import transformers; import torch; import spacy; print('All core libraries imported successfully.')"
-
-echo "Setup complete !"

test_integration.py

@@ -0,0 +1,331 @@
+# test_integration.py
+import os
+import sys
+import json
+from pathlib import Path
+from io import StringIO
+import contextlib
+
+# Add the project root to Python path for imports
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+# Create a string buffer to capture output
+output_buffer = StringIO()
+
+with contextlib.redirect_stdout(output_buffer):
+    # Now import modules
+    from config.enums import ModelType, Domain, Language
+    from config.schemas import ModelConfig, ExtractedDocument, ProcessedText
+    from config.constants import document_extraction_params
+    from config.model_config import MODEL_REGISTRY, get_model_config
+    from config.settings import settings
+    from config.threshold_config import get_threshold_for_domain
+
+    print("=" * 70)
+    print("CONFIG MODULE INTEGRATION TEST")
+    print("=" * 70)
+
+    # Test 1: Enum usage
+    print(f"\n✓ Model Types: {[m.value for m in ModelType][:5]}...")
+
+    # Test 2: Schema instantiation
+    config = ModelConfig(
+        model_id="test",
+        model_type=ModelType.TRANSFORMER,
+        description="Test",
+        size_mb=100
+    )
+    print(f"✓ Schema instantiation: {config.model_id}")
+
+    # Test 3: Constants usage
+    print(f"✓ Max file size: {document_extraction_params.MAX_FILE_SIZE / 1024 / 1024:.1f} MB")
+
+    # Test 4: Model registry
+    print(f"✓ Available models: {list(MODEL_REGISTRY.keys())}")
+
+    # Test 5: Settings
+    print(f"✓ App name: {settings.APP_NAME}")
+    print(f"✓ Environment: {settings.ENVIRONMENT}")
+    print(f"✓ Log dir: {settings.LOG_DIR}")
+    print(f"✓ Model cache dir: {settings.MODEL_CACHE_DIR}")
+
+    # Test 6: Thresholds
+    thresholds = get_threshold_for_domain(Domain.ACADEMIC)
+    print(f"✓ Academic thresholds: {thresholds.ensemble_threshold}")
+
+    print("\n" + "=" * 70)
+    print("PROCESSORS MODULE INTEGRATION TEST")
+    print("=" * 70)
+
+    # Test 7: Document Extractor
+    try:
+        from processors.document_extractor import DocumentExtractor
+        
+        # Create a test text file
+        test_text = "This is a test document for integration testing.\n" * 10
+        test_file = Path("test_document.txt")
+        
+        # Write test file
+        test_file.write_text(test_text)
+        
+        # Test extractor
+        extractor = DocumentExtractor(extract_metadata=True)
+        result = extractor.extract(str(test_file))
+        
+        print(f"\n✓ Document Extractor Test:")
+        print(f"  - Success: {result.is_success}")
+        print(f"  - Text length: {len(result.text)} chars")
+        print(f"  - File type: {result.file_type}")
+        print(f"  - Method: {result.extraction_method}")
+        
+        # Clean up test file
+        test_file.unlink()
+        
+    except Exception as e:
+        print(f"\n✗ Document Extractor failed: {e}")
+
+    # Test 8: Text Processor
+    try:
+        # First check if we have the needed constants
+        from config.constants import text_processing_params
+        print(f"\n✓ Text processing params available")
+        
+        from processors.text_processor import TextProcessor
+        
+        test_text = "This is a sample text for processing. It contains multiple sentences! " \
+                    "Here is another sentence. And one more for testing."
+        
+        processor = TextProcessor()
+        processed = processor.process(test_text)
+        
+        print(f"\n✓ Text Processor Test:")
+        print(f"  - Is valid: {processed.is_valid}")
+        print(f"  - Words: {processed.word_count}")
+        print(f"  - Sentences: {processed.sentence_count}")
+        print(f"  - Avg sentence length: {processed.avg_sentence_length:.1f}")
+        print(f"  - Avg word length: {processed.avg_word_length:.1f}")
+        
+    except Exception as e:
+        print(f"\n✗ Text Processor failed: {e}")
+        print("  Note: You need to add TextProcessingParams to constants.py")
+
+    # Test 9: Domain Classifier (without model)
+    try:
+        from processors.domain_classifier import DomainClassifier, get_domain_name, is_technical_domain
+        
+        test_text = "This is a scientific paper about machine learning and artificial intelligence."
+        
+        classifier = DomainClassifier()
+        print(f"\n✓ Domain Classifier initialized")
+        
+        # Note: This will fail if models aren't loaded, but we can test the class structure
+        print(f"  - Class structure verified")
+        print(f"  - Domain enum available")
+        
+        # Test helper functions
+        ai_ml_domain = Domain.AI_ML
+        print(f"  - AI/ML domain name: {get_domain_name(ai_ml_domain)}")
+        print(f"  - Is technical domain: {is_technical_domain(ai_ml_domain)}")
+        
+    except Exception as e:
+        print(f"\n✗ Domain Classifier setup failed: {e}")
+
+    # Test 10: Language Detector (heuristic mode)
+    try:
+        from processors.language_detector import LanguageDetector
+        
+        # Test in English
+        english_text = "This is an English text for language detection testing."
+        
+        # Use heuristic mode (no model dependency)
+        detector = LanguageDetector(use_model=False)
+        result = detector.detect(english_text)
+        
+        print(f"\n✓ Language Detector Test (heuristic):")
+        print(f"  - Primary language: {result.primary_language.value}")
+        print(f"  - Evidence strength: {result.evidence_strength:.2f}")
+        print(f"  - Method: {result.detection_method}")
+        print(f"  - Script: {result.script.value}")
+        
+        # Test language check
+        is_english = detector.is_language(english_text, Language.ENGLISH, threshold=0.5)
+        print(f"  - Is English check: {is_english}")
+        
+    except Exception as e:
+        print(f"\n✗ Language Detector failed: {e}")
+
+    print("\n" + "=" * 70)
+    print("MODELS MODULE INTEGRATION TEST")
+    print("=" * 70)
+
+    # Test 11: Model Registry
+    try:
+        from models.model_registry import ModelRegistry, get_model_registry
+        
+        registry = get_model_registry()
+        
+        print(f"\n✓ Model Registry Test:")
+        print(f"  - Singleton pattern working")
+        print(f"  - Registry initialized")
+        
+        # Test usage tracking
+        registry.record_model_usage("test_model", 1.5)
+        stats = registry.get_usage_stats("test_model")
+        print(f"  - Usage tracking: {stats.usage_count if stats else 'N/A'}")
+        
+        # Test dependency tracking
+        registry.add_dependency("model_b", ["model_a"])
+        deps = registry.get_dependencies("model_b")
+        print(f"  - Dependency tracking: {deps}")
+        
+        # Generate report
+        report = registry.generate_usage_report()
+        print(f"  - Report generation: {len(report)} items")
+        
+        # Test reset
+        registry.reset_usage_stats("test_model")
+        print(f"  - Reset functionality working")
+        
+    except Exception as e:
+        print(f"\n✗ Model Registry failed: {e}")
+
+    # Test 12: Model Manager (without actual downloads)
+    try:
+        from models.model_manager import ModelManager, get_model_manager
+        
+        manager = get_model_manager()
+        
+        print(f"\n✓ Model Manager Test:")
+        print(f"  - Singleton pattern working")
+        print(f"  - Device: {manager.device}")
+        print(f"  - Cache directory: {manager.cache_dir}")
+        
+        # Test metadata
+        metadata = manager.metadata
+        print(f"  - Metadata loaded: {len(metadata)} entries")
+        
+        # Test cache
+        cache_size = manager.cache.size()
+        print(f"  - Cache initialized: size {cache_size}")
+        
+        # Test model info check
+        model_name = list(MODEL_REGISTRY.keys())[0] if MODEL_REGISTRY else "perplexity_reference_lm"
+        is_downloaded = manager.is_model_downloaded(model_name)
+        print(f"  - Model check: {model_name} downloaded={is_downloaded}")
+        
+        # Test memory usage
+        memory_info = manager.get_memory_usage()
+        print(f"  - Memory monitoring: {len(memory_info)} metrics")
+        
+        # Test model configuration access
+        model_config = get_model_config(model_name)
+        if model_config:
+            print(f"  - Model config access: {model_config.model_id}")
+        
+    except Exception as e:
+        print(f"\n✗ Model Manager failed: {e}")
+
+    # Test 13: Integration between models and config
+    try:
+        print(f"\n✓ Config-Models Integration Test:")
+        
+        # Check model config from registry
+        for model_name, config in MODEL_REGISTRY.items():
+            if config.required:
+                print(f"  - {model_name}: {config.model_type.value}")
+                break
+        
+        # Check settings integration
+        print(f"  - Max cached models from settings: {settings.MAX_CACHED_MODELS}")
+        print(f"  - Use quantization from settings: {settings.USE_QUANTIZATION}")
+        
+    except Exception as e:
+        print(f"\n✗ Config-Models integration failed: {e}")
+
+    # Test 14: End-to-End System Integration
+    try:
+        print(f"\n" + "=" * 70)
+        print("FULL SYSTEM INTEGRATION TEST")
+        print("=" * 70)
+        
+        # Create a test scenario
+        sample_text = """
+        Machine learning is a subset of artificial intelligence. 
+        It involves algorithms that learn patterns from data.
+        Deep learning uses neural networks with multiple layers.
+        """
+        
+        # 1. Process text
+        from processors.text_processor import TextProcessor
+        processor = TextProcessor()
+        processed = processor.process(sample_text)
+        
+        print(f"✓ 1. Text Processing Complete:")
+        print(f"   - Cleaned text: {len(processed.cleaned_text)} chars")
+        print(f"   - Valid: {processed.is_valid}")
+        
+        # 2. Detect language
+        from processors.language_detector import LanguageDetector
+        detector = LanguageDetector(use_model=False)
+        lang_result = detector.detect(processed.cleaned_text)
+        
+        print(f"\n✓ 2. Language Detection Complete:")
+        print(f"   - Language: {lang_result.primary_language.value}")
+        print(f"   - Script: {lang_result.script.value}")
+        
+        # 3. Domain classification structure
+        from processors.domain_classifier import get_domain_name, is_technical_domain
+        ai_ml_domain = Domain.AI_ML
+        
+        print(f"\n✓ 3. Domain System Ready:")
+        print(f"   - Domain enum: {ai_ml_domain.value}")
+        print(f"   - Human name: {get_domain_name(ai_ml_domain)}")
+        print(f"   - Is technical: {is_technical_domain(ai_ml_domain)}")
+        
+        # 4. Model management
+        from models.model_manager import get_model_manager
+        from models.model_registry import get_model_registry
+        
+        model_manager = get_model_manager()
+        model_registry = get_model_registry()
+        
+        print(f"\n✓ 4. Model Management Ready:")
+        print(f"   - Manager: {type(model_manager).__name__}")
+        print(f"   - Registry: {type(model_registry).__name__}")
+        print(f"   - Cache dir exists: {model_manager.cache_dir.exists()}")
+        
+        # 5. Settings integration
+        print(f"\n✓ 5. Settings Integration:")
+        print(f"   - App: {settings.APP_NAME} v{settings.APP_VERSION}")
+        print(f"   - Environment: {settings.ENVIRONMENT}")
+        print(f"   - Debug: {settings.DEBUG}")
+        
+        print(f"\n🎯 FULL SYSTEM INTEGRATION SUCCESSFUL!")
+        
+    except Exception as e:
+        print(f"\n✗ Full system integration failed: {e}")
+        import traceback
+        print(traceback.format_exc())
+
+    print("\n" + "=" * 70)
+    print("TEST COMPLETED")
+    print("=" * 70)
+
+# Get the captured output
+output_text = output_buffer.getvalue()
+
+# Print the output
+print(output_text)
+
+# Count successes and failures
+success_count = sum(1 for line in output_text.split('\n') if '✓' in line)
+failure_count = sum(1 for line in output_text.split('\n') if '✗' in line)
+
+print(f"Successes: {success_count}")
+print(f"Failures: {failure_count}")
+
+if failure_count == 0:
+    print("\n🎉 ALL TESTS PASSED! Complete system is properly integrated.")
+else:
+    print(f"\n⚠️  {failure_count} tests failed. Check the issues above.")

text_auth_app.py

@@ -3,6 +3,7 @@ import os
 import time
 import json
 import uvicorn
+import asyncio
 import numpy as np
 from typing import Any
 from typing import List
@@ -19,31 +20,26 @@ from fastapi import Request
 from datetime import datetime
 from fastapi import UploadFile
 from pydantic import BaseModel
+from config.enums import Domain
 from fastapi import HTTPException
 from fastapi import BackgroundTasks
 from config.settings import settings
 from utils.logger import central_logger
 from utils.logger import log_api_request
-from detector.attribution import AIModel
-from config.threshold_config import Domain
 from fastapi.responses import JSONResponse
 from fastapi.responses import HTMLResponse
 from fastapi.responses import FileResponse
+from config.schemas import DetectionResult
 from fastapi.staticfiles import StaticFiles
-from utils.logger import log_detection_event
-from detector.attribution import ModelAttributor
-from detector.highlighter import TextHighlighter
-from processors.language_detector import Language
-from detector.orchestrator import DetectionResult
-from detector.attribution import AttributionResult
+from utils.logger import log_analysis_event
+from services.highlighter import TextHighlighter
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import ProcessPoolExecutor
 from fastapi.middleware.cors import CORSMiddleware
-from processors.text_processor import TextProcessor
 from reporter.report_generator import ReportGenerator
-from detector.orchestrator import DetectionOrchestrator
-from processors.domain_classifier import DomainClassifier
-from processors.language_detector import LanguageDetector
+from services.orchestrator import DetectionOrchestrator
 from processors.document_extractor import DocumentExtractor
-from reporter.reasoning_generator import ReasoningGenerator
+from services.reasoning_generator import ReasoningGenerator
 
 
 
@@ -202,7 +198,6 @@ class TextAnalysisRequest(SerializableBaseModel):
     """
     text                    : str           = Field(..., min_length = 50, max_length = 50000, description = "Text to analyze")
     domain                  : Optional[str] = Field(None, description = "Override automatic domain detection")
-    enable_attribution      : bool          = Field(True, description = "Enable AI model attribution")
     enable_highlighting     : bool          = Field(True, description = "Generate sentence highlighting")
     skip_expensive_metrics  : bool          = Field(False, description = "Skip computationally expensive metrics")
     use_sentence_level      : bool          = Field(True, description = "Use sentence-level analysis for highlighting") 
@@ -217,7 +212,6 @@ class TextAnalysisResponse(SerializableBaseModel):
     status           : str
     analysis_id      : str
     detection_result : Dict[str, Any]
-    attribution      : Optional[Dict[str, Any]] = None
     highlighted_html : Optional[str]            = None
     reasoning        : Optional[Dict[str, Any]] = None
     report_files     : Optional[Dict[str, str]] = None
@@ -231,7 +225,6 @@ class BatchAnalysisRequest(SerializableBaseModel):
     """
     texts                  : List[str]     = Field(..., min_items = 1, max_items = 100)
     domain                 : Optional[str] = None
-    enable_attribution     : bool          = False
     skip_expensive_metrics : bool          = True
     generate_reports       : bool          = False
 
@@ -243,7 +236,6 @@ class BatchAnalysisResult(SerializableBaseModel):
     index        : int
     status       : str
     detection    : Optional[Dict[str, Any]] = None
-    attribution  : Optional[Dict[str, Any]] = None
     reasoning    : Optional[Dict[str, Any]] = None
     report_files : Optional[Dict[str, str]] = None
     error        : Optional[str]            = None
@@ -271,7 +263,6 @@ class FileAnalysisResponse(SerializableBaseModel):
     analysis_id      : str
     file_info        : Dict[str, Any]
     detection_result : Dict[str, Any]
-    attribution      : Optional[Dict[str, Any]] = None
     highlighted_html : Optional[str]            = None 
     reasoning        : Optional[Dict[str, Any]] = None
     report_files     : Optional[Dict[str, str]] = None
@@ -327,6 +318,7 @@ class AnalysisCache:
         self.ttl_seconds = ttl_seconds
         logger.info(f"AnalysisCache initialized (max_size={max_size}, ttl={ttl_seconds}s)")
     
+
     def set(self, analysis_id: str, data: Dict[str, Any]) -> None:
         """
         Store analysis result in cache
@@ -335,18 +327,20 @@ class AnalysisCache:
         self._cleanup_expired()
         
         # If cache is full, remove oldest entry
-        if len(self.cache) >= self.max_size:
-            oldest_key = min(self.cache.keys(), key=lambda k: self.cache[k]['timestamp'])
+        if (len(self.cache) >= self.max_size):
+            oldest_key = min(self.cache.keys(), key = lambda k: self.cache[k]['timestamp'])
+            
             del self.cache[oldest_key]
+            
             logger.debug(f"Cache full, removed oldest entry: {oldest_key}")
         
         # Store new entry
-        self.cache[analysis_id] = {
-            'data': data,
-            'timestamp': time.time()
-        }
+        self.cache[analysis_id] = {'data'      : data,
+                                   'timestamp' : time.time()
+                                  }
         logger.debug(f"Cached analysis: {analysis_id} (cache size: {len(self.cache)})")
     
+
     def get(self, analysis_id: str) -> Optional[Dict[str, Any]]:
         """
         Retrieve analysis result from cache
@@ -358,7 +352,7 @@ class AnalysisCache:
         entry = self.cache[analysis_id]
         
         # Check if expired
-        if time.time() - entry['timestamp'] > self.ttl_seconds:
+        if ((time.time() - entry['timestamp']) > self.ttl_seconds):
             del self.cache[analysis_id]
             logger.debug(f"Cache expired: {analysis_id}")
             return None
@@ -366,15 +360,13 @@ class AnalysisCache:
         logger.debug(f"Cache hit: {analysis_id}")
         return entry['data']
     
+
     def _cleanup_expired(self) -> None:
         """
         Remove expired entries from cache
         """
         current_time = time.time()
-        expired_keys = [
-            key for key, entry in self.cache.items()
-            if current_time - entry['timestamp'] > self.ttl_seconds
-        ]
+        expired_keys = [key for key, entry in self.cache.items() if ((current_time - entry['timestamp']) > self.ttl_seconds)]
         
         for key in expired_keys:
             del self.cache[key]
@@ -382,6 +374,7 @@ class AnalysisCache:
         if expired_keys:
             logger.debug(f"Cleaned up {len(expired_keys)} expired cache entries")
     
+
     def clear(self) -> None:
         """
         Clear all cached entries
@@ -390,6 +383,7 @@ class AnalysisCache:
         self.cache.clear()
         logger.info(f"Cache cleared ({count} entries removed)")
     
+
     def size(self) -> int:
         """
         Get current cache size
@@ -398,8 +392,8 @@ class AnalysisCache:
 
 
 # ==================== FASTAPI APPLICATION ====================
-app = FastAPI(title                  = "TEXT-AUTH AI Detection API",
-              description            = "API for detecting AI-generated text",
+app = FastAPI(title                  = "Text Forensics API",
+              description            = "Evidence-based statistical and linguistic text analysis API",
               version                = "1.0.0",
               docs_url               = "/api/docs",
               redoc_url              = "/api/redoc",
@@ -423,25 +417,26 @@ if ui_static_path.exists():
 
 # Global instances
 orchestrator       : Optional[DetectionOrchestrator] = None
-attributor         : Optional[ModelAttributor]       = None
 highlighter        : Optional[TextHighlighter]       = None
 reporter           : Optional[ReportGenerator]       = None
 reasoning_generator: Optional[ReasoningGenerator]    = None
 document_extractor : Optional[DocumentExtractor]     = None
 analysis_cache     : Optional[AnalysisCache]         = None 
 
+# Thread pool executor for parallel processing
+parallel_executor  : Optional[ThreadPoolExecutor]    = None
 
 # App state
 app_start_time                                       = time.time()
 
 initialization_status                                = {"orchestrator"        : False,
-                                                        "attributor"          : False,
                                                         "highlighter"         : False,
                                                         "reporter"            : False,
                                                         "reasoning_generator" : False,
                                                         "document_extractor"  : False,
-                                                        "analysis_cache"      : False, 
-                                                        }
+                                                        "analysis_cache"      : False,
+                                                        "parallel_executor"   : False,
+                                                       }
 
 
 # ==================== APPLICATION LIFECYCLE ====================
@@ -451,12 +446,12 @@ async def startup_event():
     Initialize all components on startup
     """
     global orchestrator
-    global attributor
     global highlighter
     global reporter
     global reasoning_generator
     global document_extractor
     global analysis_cache
+    global parallel_executor
     global initialization_status
 
     # Initialize centralized logging first
@@ -464,36 +459,36 @@ async def startup_event():
         raise RuntimeError("Failed to initialize logging system")
     
     logger.info("=" * 80)
-    logger.info("TEXT-AUTH API Starting Up...")
+    logger.info("TEXT-AUTH Forensic Analysis API Starting Up...")
     logger.info("=" * 80)
     
     try:
-        # Initialize Detection Orchestrator
+        # Initialize ThreadPoolExecutor for parallel metric calculation
+        logger.info("Initializing Parallel Executor...")
+        parallel_executor = ThreadPoolExecutor(
+            max_workers = getattr(settings, 'PARALLEL_WORKERS', 4)
+        )
+        initialization_status["parallel_executor"] = True
+        logger.success(f"✓ Parallel Executor initialized with {parallel_executor._max_workers} workers")
+        
+        # Initialize Detection Orchestrator with parallel execution enabled
         logger.info("Initializing Detection Orchestrator...")
-        orchestrator = DetectionOrchestrator(enable_language_detection = True,
-                                             parallel_execution        = False,
-                                             skip_expensive_metrics    = False,
-                                            )
+        
+        # Use the factory method to create orchestrator with executor
+        orchestrator = DetectionOrchestrator.create_with_executor(
+            max_workers = getattr(settings, 'PARALLEL_WORKERS', 4),
+            enable_language_detection = True,
+            parallel_execution = True,  # Enable parallel execution
+            skip_expensive_metrics = False,
+        )
         
         if orchestrator.initialize():
             initialization_status["orchestrator"] = True
-            logger.success("✓ Detection Orchestrator initialized")
+            logger.success("✓ Detection Orchestrator initialized with parallel execution")
         
         else:
             logger.warning("⚠ Detection Orchestrator initialization incomplete")
         
-        # Initialize Model Attributor
-        logger.info("Initializing Model Attributor...")
-        
-        attributor = ModelAttributor()
-        
-        if attributor.initialize():
-            initialization_status["attributor"] = True
-            logger.success("✓ Model Attributor initialized")
-        
-        else:
-            logger.warning("⚠ Model Attributor initialization incomplete")
-        
         # Initialize Text Highlighter
         logger.info("Initializing Text Highlighter...")
        
@@ -542,10 +537,11 @@ async def startup_event():
         logger.success("✓ Analysis Cache initialized")
         
         logger.info("=" * 80)
-        logger.success("TEXT-AUTH API Ready!")
+        logger.success("TEXT-AUTH Forensic Analysis API Ready!")
         logger.info(f"Server: {settings.HOST}:{settings.PORT}")
         logger.info(f"Environment: {settings.ENVIRONMENT}")
         logger.info(f"Device: {settings.DEVICE}")
+        logger.info(f"Parallel Execution: Enabled")
         logger.info("=" * 80)
         
     except Exception as e:
@@ -559,6 +555,12 @@ async def shutdown_event():
     """
     Cleanup on shutdown
     """
+    # Clean up orchestrator first (it will handle executor cleanup)
+    if orchestrator:
+        orchestrator.cleanup()
+        logger.info("Orchestrator cleanup complete")
+    
+    # Additional cleanup
     if analysis_cache:
         analysis_cache.clear()
     
@@ -567,13 +569,12 @@ async def shutdown_event():
     logger.info("Shutdown complete")
 
 
-
 # ==================== UTILITY FUNCTIONS ====================
 def _get_domain_description(domain: Domain) -> str:
     """
     Get description for a domain
     """
-    descriptions = {Domain.GENERAL       : "General content without specific domain",
+    descriptions = {Domain.GENERAL       : "General-purpose text without domain-specific structure",
                     Domain.ACADEMIC      : "Academic papers, essays, research",
                     Domain.CREATIVE      : "Creative writing, fiction, poetry",
                     Domain.AI_ML         : "AI/ML research papers, technical content",
@@ -693,7 +694,7 @@ def _parse_domain(domain_str: Optional[str]) -> Optional[Domain]:
         
         # Try to match with underscores/spaces variations
         normalized_with_underscores = normalized_domain.replace(' ', '_')
-        if normalized_with_underscores in domain_mapping:
+        if (normalized_with_underscores in domain_mapping):
             return domain_mapping[normalized_with_underscores]
         
         # Try partial matching for more flexibility
@@ -724,19 +725,18 @@ def _validate_file_extension(filename: str) -> str:
     return file_extension
 
 
-def _generate_reasoning(detection_result: DetectionResult, attribution_result: Optional[AttributionResult] = None) -> Dict[str, Any]:
+def _generate_reasoning(detection_result: DetectionResult) -> Dict[str, Any]:
     """
-    Generate detailed reasoning for detection results
+    Generate detailed forensic reasoning explaining metric-level evidence
     """
     if not reasoning_generator:
         return {}
     
     try:
-        reasoning = reasoning_generator.generate(ensemble_result    = detection_result.ensemble_result,
-                                                 metric_results     = detection_result.metric_results,
-                                                 domain             = detection_result.domain_prediction.primary_domain,
-                                                 attribution_result = attribution_result,
-                                                 text_length        = detection_result.processed_text.word_count,
+        reasoning = reasoning_generator.generate(ensemble_result = detection_result.ensemble_result,
+                                                 metric_results  = detection_result.metric_results,
+                                                 domain          = detection_result.domain_prediction.primary_domain,
+                                                 text_length     = detection_result.processed_text.word_count,
                                                 )
 
         return safe_serialize_response(reasoning.to_dict())
@@ -746,8 +746,7 @@ def _generate_reasoning(detection_result: DetectionResult, attribution_result: O
         return {}
 
 
-def _generate_reports(detection_result: DetectionResult, attribution_result: Optional[AttributionResult] = None, highlighted_sentences: Optional[List] = None, 
-                      analysis_id: str = None) -> Dict[str, str]:
+def _generate_reports(detection_result: DetectionResult, highlighted_sentences: Optional[List] = None, analysis_id: str = None) -> Dict[str, str]:
     """
     Generate reports for detection results
     """
@@ -756,7 +755,6 @@ def _generate_reports(detection_result: DetectionResult, attribution_result: Opt
     
     try:
         report_files = reporter.generate_complete_report(detection_result      = detection_result,
-                                                         attribution_result    = attribution_result,
                                                          highlighted_sentences = highlighted_sentences,
                                                          formats               = ["json", "pdf"],
                                                          filename_prefix       = analysis_id or f"report_{int(time.time() * 1000)}",
@@ -768,6 +766,55 @@ def _generate_reports(detection_result: DetectionResult, attribution_result: Opt
         return {}
 
 
+# ==================== ASYNC HELPER FUNCTIONS ====================
+async def _run_detection_parallel(text: str, domain: Optional[Domain], skip_expensive: bool) -> DetectionResult:
+    """
+    Run forensic analysis in parallel mode
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    # Use orchestrator's analyze method which now handles parallel execution internally
+    return orchestrator.analyze(text           = text,
+                                domain         = domain,
+                                skip_expensive = skip_expensive,
+                               )
+
+
+async def _run_batch_analysis_parallel(texts: List[str], domain: Optional[Domain], skip_expensive: bool) -> List[DetectionResult]:
+    """
+    Run batch analysis with parallel execution
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    # Create tasks for parallel execution
+    tasks = list()
+
+    for text in texts:
+        task = asyncio.create_task(asyncio.to_thread(orchestrator.analyze,
+                                                     text           = text,
+                                                     domain         = domain,
+                                                     skip_expensive = skip_expensive,
+                                                    )
+                                  )
+        tasks.append(task)
+    
+    # Wait for all tasks to complete
+    results           = await asyncio.gather(*tasks, return_exceptions = True)
+    
+    # Process results
+    detection_results = list()
+
+    for result in results:
+        if isinstance(result, Exception):
+            raise result
+
+        detection_results.append(result)
+    
+    return detection_results
+
+
 # ==================== ROOT & HEALTH ENDPOINTS ====================
 @app.get("/", response_class = HTMLResponse)
 async def root():
@@ -783,10 +830,10 @@ async def root():
     
     # Fallback to static directory if exists
     ui_static_path = Path(__file__).parent / "ui" / "static"
-    index_path = ui_static_path / "index.html"
+    index_path     = ui_static_path / "index.html"
     
     if index_path.exists():
-        with open(index_path, 'r', encoding='utf-8') as f:
+        with open(index_path, 'r', encoding = 'utf-8') as f:
             return HTMLResponse(content=f.read())
     
     return HTMLResponse(content = """
@@ -794,7 +841,7 @@ async def root():
                                           <head><title>TEXT-AUTH API</title></head>
                                           <body style="font-family: sans-serif; padding: 50px; text-align: center;">
                                               <h1>🔍 TEXT-AUTH API</h1>
-                                              <p>AI Text Detection Platform v2.0</p>
+                                              <p>Evidence-First Text Forensics Platform v1.0</p>
                                               <p><a href="/api/docs">API Documentation</a></p>
                                               <p><a href="/health">Health Check</a></p>
                                           </body>
@@ -809,20 +856,22 @@ async def health_check():
     Health check endpoint
     """
     return HealthCheckResponse(status        = "healthy" if all(initialization_status.values()) else "degraded",
-                               version       = "2.0.0",
+                               version       = "1.0.0",
                                uptime        = time.time() - app_start_time,
                                models_loaded = initialization_status,
-                             )
+                              )
 
 
 # ==================== ANALYSIS ENDPOINTS ====================
 @app.post("/api/analyze", response_model = TextAnalysisResponse)
 async def analyze_text(request: TextAnalysisRequest):
     """
-    Analyze text for AI generation
+    Analyze text for statistical consistency with language-model generation patterns using parallel metric calculation
     """
     if not orchestrator:
-        raise HTTPException(status_code=503, detail="Service not initialized")
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
     
     start_time  = time.time()
     analysis_id = f"analysis_{int(time.time() * 1000)}"
@@ -836,42 +885,68 @@ async def analyze_text(request: TextAnalysisRequest):
                                 detail      = f"Invalid domain. Valid options: {[d.value for d in Domain]}",
                                )
         
-        # Run detection analysis
-        logger.info(f"[{analysis_id}] Analyzing text ({len(request.text)} chars)")
+        # Run detection analysis with parallel execution (handled internally by orchestrator)
+        logger.info(f"[{analysis_id}] Analyzing text ({len(request.text)} chars) with parallel metrics")
         
-        detection_result = orchestrator.analyze(text           = request.text,
-                                                domain         = domain,
-                                                skip_expensive = request.skip_expensive_metrics,
-                                               )
+        detection_result      = await _run_detection_parallel(text           = request.text,
+                                                              domain         = domain,
+                                                              skip_expensive = request.skip_expensive_metrics
+                                                             )
         
         # Convert detection result to ensure serializability
-        detection_dict   = safe_serialize_response(detection_result.to_dict())
+        detection_dict        = safe_serialize_response(detection_result.to_dict())
         
-        # Attribution (if enabled)
-        attribution_result = None
-        attribution_dict   = None
+        # Highlighting (if enabled) - run in parallel with reasoning generation
+        highlighted_sentences = None
+        highlighted_html      = None
+        reasoning_dict        = dict()
         
-        if (request.enable_attribution and attributor):
+        # Run highlighting and reasoning generation in parallel if both are needed
+        if (request.enable_highlighting and highlighter and reasoning_generator):
             try:
-                logger.info(f"[{analysis_id}] Running attribution...")
-                attribution_result = attributor.attribute(text           = request.text,
-                                                          processed_text = detection_result.processed_text,
-                                                          metric_results = detection_result.metric_results,
-                                                          domain         = detection_result.domain_prediction.primary_domain,
-                                                         )
-
-                attribution_dict   = safe_serialize_response(attribution_result.to_dict())
-
+                logger.info(f"[{analysis_id}] Generating highlights and reasoning in parallel...")
+                
+                # Create parallel tasks for highlighting and reasoning
+                highlight_task                        = asyncio.create_task(asyncio.to_thread(highlighter.generate_highlights,
+                                                                                              text               = request.text,
+                                                                                              metric_results     = detection_result.metric_results,
+                                                                                              ensemble_result    = detection_result.ensemble_result,
+                                                                                              use_sentence_level = request.use_sentence_level,
+                                                                                             )
+                                                                           )
+                
+                reasoning_task                        = asyncio.create_task(asyncio.to_thread(_generate_reasoning,
+                                                                                              detection_result = detection_result
+                                                                                             )
+                                                                           )
+                
+                # Wait for both tasks to complete
+                highlighted_sentences, reasoning_dict = await asyncio.gather(highlight_task, reasoning_task) 
+                
+                # Generate HTML from highlighted sentences
+                highlighted_html                      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                                  include_legend        = False,
+                                                                                 )
+                
             except Exception as e:
-                logger.warning(f"Attribution failed: {e}")
-        
-        # Highlighting (if enabled)
-        highlighted_sentences = None
-        highlighted_html      = None
-
-        if request.enable_highlighting and highlighter:
+                logger.warning(f"Parallel highlighting/reasoning failed: {e}")
+                # Fallback to sequential if parallel fails
+                try:
+                    highlighted_sentences = highlighter.generate_highlights(text               = request.text,
+                                                                            metric_results     = detection_result.metric_results,
+                                                                            ensemble_result    = detection_result.ensemble_result,
+                                                                            use_sentence_level = request.use_sentence_level,
+                                                                           )
+
+                    highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                      include_legend        = False,
+                                                                     )
+                except Exception as e2:
+                    logger.warning(f"Highlighting fallback also failed: {e2}")
+        
+        elif request.enable_highlighting and highlighter:
+            # Only highlighting requested
             try:
-                logger.info(f"[{analysis_id}] Generating highlights...")
                 highlighted_sentences = highlighter.generate_highlights(text               = request.text,
                                                                         metric_results     = detection_result.metric_results,
                                                                         ensemble_result    = detection_result.ensemble_result,
@@ -880,29 +955,25 @@ async def analyze_text(request: TextAnalysisRequest):
 
                 highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
                                                                   include_legend        = False,
-                                                                  include_metrics       = request.include_metrics_summary,
                                                                  )
             except Exception as e:
                 logger.warning(f"Highlighting failed: {e}")
-
         
-        # Generate reasoning
-        reasoning_dict = _generate_reasoning(detection_result   = detection_result, 
-                                             attribution_result = attribution_result,
-                                            )
+        elif reasoning_generator:
+            # Only reasoning requested
+            reasoning_dict = _generate_reasoning(detection_result = detection_result)
         
         # Generate reports (if requested)
-        report_files   = dict()
+        report_files = dict()
 
         if request.generate_report:
             try:
                 logger.info(f"[{analysis_id}] Generating reports...")
-                report_files = _generate_reports(detection_result      = detection_result,
-                                                 attribution_result    = attribution_result,
-                                                 highlighted_sentences = highlighted_sentences,
-                                                 analysis_id           = analysis_id,
-                                                )
-
+                report_files = await asyncio.to_thread(_generate_reports,
+                                                       detection_result      = detection_result,
+                                                       highlighted_sentences = highlighted_sentences,
+                                                       analysis_id           = analysis_id,
+                                                      )
             except Exception as e:
                 logger.warning(f"Report generation failed: {e}")
         
@@ -911,14 +982,12 @@ async def analyze_text(request: TextAnalysisRequest):
         # Cache the full analysis result
         if analysis_cache:
             cache_data = {'detection_result'      : detection_result,
-                          'attribution_result'    : attribution_result,
                           'highlighted_sentences' : highlighted_sentences,
                           'original_text'         : request.text,
                           'processing_time'       : processing_time,
                          }
 
             analysis_cache.set(analysis_id, cache_data)
-
             logger.debug(f"Cached analysis: {analysis_id}")
         
         # Log the detection event
@@ -928,14 +997,12 @@ async def analyze_text(request: TextAnalysisRequest):
                             confidence          = detection_result.ensemble_result.overall_confidence,
                             domain              = detection_result.domain_prediction.primary_domain.value,
                             processing_time     = processing_time,
-                            enable_attribution  = request.enable_attribution,
                             enable_highlighting = request.enable_highlighting,
                            )
         
         return TextAnalysisResponse(status           = "success",
                                     analysis_id      = analysis_id,
                                     detection_result = detection_dict,
-                                    attribution      = attribution_dict,
                                     highlighted_html = highlighted_html,
                                     reasoning        = reasoning_dict,
                                     report_files     = report_files,
@@ -943,13 +1010,12 @@ async def analyze_text(request: TextAnalysisRequest):
                                     timestamp        = datetime.now().isoformat(),
                                 )
         
-    except HTTPException:
+    except HTTPException as e:
         central_logger.log_error("TextAnalysisError",
                                 f"Analysis failed for request",
                                 {"text_length": len(request.text)},
                                 e,
                                 )
-
         raise
 
     except Exception as e:
@@ -960,10 +1026,9 @@ async def analyze_text(request: TextAnalysisRequest):
 
 
 @app.post("/api/analyze/file", response_model = FileAnalysisResponse)
-async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = Form(None), enable_attribution: bool = Form(True), skip_expensive_metrics: bool = Form(False),
-                       use_sentence_level: bool = Form(True), include_metrics_summary: bool = Form(True), generate_report: bool = Form(False)):
+async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = Form(None), skip_expensive_metrics: bool = Form(False), use_sentence_level: bool = Form(True), include_metrics_summary: bool = Form(True), generate_report: bool = Form(False)):
     """
-    Analyze uploaded document (PDF, DOCX, TXT)
+    Analyze uploaded document for linguistic and statistical consistency patterns using parallel processing
     """
     if not document_extractor or not orchestrator:
         raise HTTPException(status_code = 503, 
@@ -993,13 +1058,13 @@ async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = For
         
         logger.info(f"[{analysis_id}] Extracted {len(extracted_doc.text)} characters")
         
-        # Parse domain and analyze
-        domain_enum        = _parse_domain(domain)
+        # Parse domain and analyze with parallel execution
+        domain_enum      = _parse_domain(domain)
         
-        detection_result   = orchestrator.analyze(text           = extracted_doc.text,
-                                                  domain         = domain_enum,
-                                                  skip_expensive = skip_expensive_metrics,
-                                                 )
+        detection_result = await _run_detection_parallel(text           = extracted_doc.text,
+                                                         domain         = domain_enum,
+                                                         skip_expensive = skip_expensive_metrics,
+                                                        )
         
         # Set file_info on detection_result
         detection_result.file_info = {"filename"          : file.filename,
@@ -1010,60 +1075,62 @@ async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = For
                                      }
         
         # Convert to serializable dict
-        detection_dict     = safe_serialize_response(detection_result.to_dict())
-        
-        # Attribution
-        attribution_result = None
-        attribution_dict   = None
+        detection_dict        = safe_serialize_response(detection_result.to_dict())
         
-        if (enable_attribution and attributor):
-            try:
-                attribution_result = attributor.attribute(text           = extracted_doc.text,
-                                                          processed_text = detection_result.processed_text,
-                                                          metric_results = detection_result.metric_results,
-                                                          domain         = detection_result.domain_prediction.primary_domain,
-                                                         )
-
-                attribution_dict   = safe_serialize_response(attribution_result.to_dict())
-
-            except Exception as e:
-                logger.warning(f"Attribution failed: {e}")
-        
-        # Highlighting
+        # Parallel highlighting and reasoning generation
         highlighted_sentences = None
         highlighted_html      = None
-
-        if highlighter:
+        reasoning_dict        = {}
+        
+        if highlighter and reasoning_generator:
             try:
-                highlighted_sentences = highlighter.generate_highlights(text               = extracted_doc.text,
-                                                                        metric_results     = detection_result.metric_results,
-                                                                        ensemble_result    = detection_result.ensemble_result,
-                                                                        use_sentence_level = use_sentence_level,
-                                                                       )
-
-                highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
-                                                                  include_legend        = False,
-                                                                  include_metrics       = include_metrics_summary,
-                                                                 )
+                # Run highlighting and reasoning in parallel
+                highlight_task                        = asyncio.create_task(asyncio.to_thread(highlighter.generate_highlights,
+                                                                                              text               = extracted_doc.text,
+                                                                                              metric_results     = detection_result.metric_results,
+                                                                                              ensemble_result    = detection_result.ensemble_result,
+                                                                                              use_sentence_level = use_sentence_level,
+                                                                                             )
+                                                                           )
+                
+                reasoning_task                        = asyncio.create_task(asyncio.to_thread(_generate_reasoning,
+                                                                                              detection_result = detection_result
+                                                                                             )
+                                                                           )
+                
+                highlighted_sentences, reasoning_dict = await asyncio.gather(highlight_task, reasoning_task)
+                
+                highlighted_html                      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                                  include_legend        = False,
+                                                                                 )
+                
             except Exception as e:
-                logger.warning(f"Highlighting failed: {e}")
-        
-        # Generate reasoning
-        reasoning_dict = _generate_reasoning(detection_result   = detection_result, 
-                                             attribution_result = attribution_result,
-                                            )
+                logger.warning(f"Parallel highlighting/reasoning failed: {e}")
+                # Fallback
+                try:
+                    highlighted_sentences = highlighter.generate_highlights(text               = extracted_doc.text,
+                                                                            metric_results     = detection_result.metric_results,
+                                                                            ensemble_result    = detection_result.ensemble_result,
+                                                                            use_sentence_level = use_sentence_level,
+                                                                           )
+                    highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                      include_legend        = False,
+                                                                     )
+                except Exception as e2:
+                    logger.warning(f"Highlighting fallback also failed: {e2}")
         
         # Generate reports (if requested)
-        report_files   = dict()
+        report_files = dict()
 
         if generate_report:
             try:
                 logger.info(f"[{analysis_id}] Generating reports...")
-                report_files = _generate_reports(detection_result      = detection_result,
-                                                 attribution_result    = attribution_result,
-                                                 highlighted_sentences = highlighted_sentences,
-                                                 analysis_id           = analysis_id,
-                                                )
+                report_files = await asyncio.to_thread(_generate_reports,
+                                                       detection_result      = detection_result,
+                                                       highlighted_sentences = highlighted_sentences,
+                                                       analysis_id           = analysis_id,
+                                                      )
+
             except Exception as e:
                 logger.warning(f"Report generation failed: {e}")
         
@@ -1072,7 +1139,6 @@ async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = For
         # Cache the full analysis result including Original Text 
         if analysis_cache:
             cache_data = {'detection_result'      : detection_result,
-                          'attribution_result'    : attribution_result,
                           'highlighted_sentences' : highlighted_sentences,
                           'original_text'         : extracted_doc.text, 
                           'processing_time'       : processing_time,
@@ -1090,7 +1156,6 @@ async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = For
                                                         "highlighted_html"  : highlighted_html is not None,
                                                        },
                                     detection_result = detection_dict,
-                                    attribution      = attribution_dict,
                                     highlighted_html = highlighted_html,
                                     reasoning        = reasoning_dict,
                                     report_files     = report_files,
@@ -1111,7 +1176,7 @@ async def analyze_file(file: UploadFile = File(...), domain: Optional[str] = For
 @app.post("/api/analyze/batch", response_model = BatchAnalysisResponse)
 async def batch_analyze(request: BatchAnalysisRequest):
     """
-    Analyze multiple texts in batch
+    Analyze multiple texts in batch for forensic consistency signals using parallel processing
     - Limits : 1-100 texts per request
     """
     if not orchestrator:
@@ -1124,78 +1189,76 @@ async def batch_analyze(request: BatchAnalysisRequest):
                             detail      = "Maximum 100 texts per batch",
                            )
 
-
     start_time = time.time()
     batch_id   = f"batch_{int(time.time() * 1000)}"
 
     try:
         # Parse domain
-        domain  = _parse_domain(request.domain)
+        domain            = _parse_domain(request.domain)
+        
+        logger.info(f"[{batch_id}] Processing {len(request.texts)} texts with parallel execution")
+        
+        # Use parallel batch analysis
+        detection_results = await _run_batch_analysis_parallel(texts          = request.texts,
+                                                               domain         = domain,
+                                                               skip_expensive = request.skip_expensive_metrics,
+                                                              )
         
-        logger.info(f"[{batch_id}] Processing {len(request.texts)} texts")
+        results           = list()
         
-        results = list()
+        # Process results with parallel reasoning generation
+        reasoning_tasks   = list()
 
-        for i, text in enumerate(request.texts):
-            try:
-                detection_result   = orchestrator.analyze(text           = text,
-                                                          domain         = domain,
-                                                          skip_expensive = request.skip_expensive_metrics,
-                                                         )
-                
-                # Convert to serializable dict
-                detection_dict     = safe_serialize_response(detection_result.to_dict())
-                
-                # Attribution if enabled
-                attribution_result = None
-                attribution_dict   = None
-
-                if request.enable_attribution and attributor:
-                    try:
-                        attribution_result = attributor.attribute(text           = text,
-                                                                  processed_text = detection_result.processed_text,
-                                                                  metric_results = detection_result.metric_results,
-                                                                  domain         = detection_result.domain_prediction.primary_domain,
-                                                                 )
+        for i, detection_result in enumerate(detection_results):
+            if isinstance(detection_result, Exception):
+                results.append(BatchAnalysisResult(index  = i,
+                                                   status = "error",
+                                                   error  = str(detection_result),
+                                                  ))
+                continue
+            
+            # Convert to serializable dict
+            detection_dict = safe_serialize_response(detection_result.to_dict())
+            
+            # Start reasoning generation task
+            if reasoning_generator:
+                task = asyncio.create_task(asyncio.to_thread(_generate_reasoning,
+                                                             detection_result = detection_result
+                                                            )
+                                          )
 
-                        attribution_dict   = safe_serialize_response(attribution_result.to_dict())
+                reasoning_tasks.append((i, task, detection_dict))
 
-                    except Exception:
-                        pass
-                
-                # Generate reasoning
-                reasoning_dict = _generate_reasoning(detection_result   = detection_result, 
-                                                     attribution_result = attribution_result,
-                                                    )
-                
-                # Generate reports if requested
-                report_files   = dict()
-
-                if request.generate_reports:
-                    try:
-                        report_files = _generate_reports(detection_result   = detection_result,
-                                                         attribution_result = attribution_result,
-                                                         analysis_id        = f"{batch_id}_{i}"
-                                                        )
-                    except Exception:
-                        pass
-                
+            else:
+                results.append(BatchAnalysisResult(index        = i,
+                                                   status       = "success",
+                                                   detection    = detection_dict,
+                                                   reasoning    = {},
+                                                   report_files = None,
+                                                  ))
+        
+        # Wait for all reasoning tasks to complete
+        for i, task, detection_dict in reasoning_tasks:
+            try:
+                reasoning_dict = await task
                 results.append(BatchAnalysisResult(index        = i,
                                                    status       = "success",
                                                    detection    = detection_dict,
-                                                   attribution  = attribution_dict,
                                                    reasoning    = reasoning_dict,
-                                                   report_files = report_files,
-                                                  )
-                              )
-                
+                                                   report_files = None,
+                                                  ))
+
             except Exception as e:
-                logger.error(f"[{batch_id}] Text {i} failed: {e}")
-                results.append(BatchAnalysisResult(index  = i,
-                                                   status = "error",
-                                                   error  = str(e),
-                                                  )
-                              )
+                logger.error(f"[{batch_id}] Reasoning generation failed for text {i}: {e}")
+                results.append(BatchAnalysisResult(index        = i,
+                                                   status       = "success",
+                                                   detection    = detection_dict,
+                                                   reasoning    = {},
+                                                   report_files = None,
+                                                  ))
+        
+        # Sort results by index
+        results.sort(key = lambda x: x.index)
         
         processing_time = time.time() - start_time
         success_count   = sum(1 for r in results if r.status == "success")
@@ -1243,7 +1306,6 @@ async def generate_report(background_tasks: BackgroundTasks, analysis_id: str =
 
         # Extract cached data
         detection_result      = cached_data['detection_result']
-        attribution_result    = cached_data.get('attribution_result')
         highlighted_sentences = cached_data.get('highlighted_sentences')
         
         # Parse formats
@@ -1259,12 +1321,12 @@ async def generate_report(background_tasks: BackgroundTasks, analysis_id: str =
         # Generate reports using cached data
         logger.info(f"Generating {', '.join(requested_formats)} report(s) for {analysis_id}")
         
-        report_files     = reporter.generate_complete_report(detection_result      = detection_result,
-                                                             attribution_result    = attribution_result,
-                                                             highlighted_sentences = highlighted_sentences if include_highlights else None,
-                                                             formats               = requested_formats,
-                                                             filename_prefix       = analysis_id,
-                                                            )
+        report_files     = await asyncio.to_thread(reporter.generate_complete_report,
+                                                   detection_result      = detection_result,
+                                                   highlighted_sentences = highlighted_sentences if include_highlights else None,
+                                                   formats               = requested_formats,
+                                                   filename_prefix       = analysis_id,
+                                                  )
 
         # Extract only the filename from the full path for the response
         report_filenames = dict()
@@ -1289,6 +1351,7 @@ async def generate_report(background_tasks: BackgroundTasks, analysis_id: str =
                             detail      = str(e),
                            )
 
+
 @app.get("/api/report/download/{filename}")
 async def download_report(filename: str):
     """
@@ -1328,19 +1391,6 @@ async def list_domains():
     return {"domains": domains_list}
 
 
-@app.get("/api/models")
-async def list_ai_models():
-    """
-    List all AI models that can be attributed
-    """
-    return {"models" : [{"value" : model.value,
-                         "name"  : model.value.replace('-', ' ').replace('_', ' ').title(),
-                        }
-                        for model in AIModel if model not in [AIModel.HUMAN, AIModel.UNKNOWN]
-                       ]
-           }
-
-
 @app.get("/api/cache/stats")
 async def get_cache_stats():
     """
@@ -1418,6 +1468,7 @@ async def log_requests(request: Request, call_next):
 
 
 
+
 # ==================== MAIN ====================
 if __name__ == "__main__":
     # Configure logging
@@ -1430,4 +1481,4 @@ if __name__ == "__main__":
                 reload     = settings.DEBUG,
                 log_level  = log_level,
                 workers    = 1 if settings.DEBUG else settings.WORKERS,
-               )
+               )

ui/static/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>AI Text Detector - Verifying Content Authenticity Using Statistics</title>
+<title>TextAuth Forensics — Evidence-Based Text Authenticity Analysis</title>
 <style>
 * {
     margin: 0;
@@ -731,12 +731,12 @@ input[type="checkbox"] {
     min-width: 60px;
     text-align: center;
 }
-.ai-badge {
+.synthetic-badge {
     background: rgba(239, 68, 68, 0.2);
     color: var(--danger);
     border: 1px solid rgba(239, 68, 68, 0.3);
 }
-.human-badge {
+.authentic-badge {
     background: rgba(16, 185, 129, 0.2);
     color: var(--success);
     border: 1px solid rgba(16, 185, 129, 0.3);
@@ -763,54 +763,6 @@ input[type="checkbox"] {
     font-size: 0.9rem;
     font-weight: 600;
 }
-/* Attribution Section */
-.attribution-section {
-    margin-top: 2rem;
-    padding: 1.5rem;
-    background: rgba(51, 65, 85, 0.3);
-    border-radius: 10px;
-    border: 1px solid var(--border);
-}
-.attribution-title {
-    font-size: 1.1rem;
-    font-weight: 700;
-    margin-bottom: 1rem;
-    color: #fff;
-}
-.model-match {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 0.75rem;
-    background: rgba(6, 182, 212, 0.1);
-    border-radius: 6px;
-    margin-bottom: 0.5rem;
-}
-.model-name {
-    font-weight: 600;
-    color: var(--text-primary);
-}
-.model-confidence {
-    font-weight: 700;
-    color: var(--primary);
-}
-.attribution-confidence {
-    margin-top: 0.75rem;
-    font-size: 0.85rem;
-    color: var(--text-secondary);
-}
-.attribution-uncertain {
-    color: var(--text-muted);
-    font-style: italic;
-    margin-top: 0.5rem;
-    font-size: 0.9rem;
-}
-.attribution-reasoning {
-    color: var(--text-secondary);
-    margin-top: 1rem;
-    font-size: 0.9rem;
-    line-height: 1.4;
-}
 /* Download Actions */
 .download-actions {
     display: flex;
@@ -908,11 +860,11 @@ input[type="checkbox"] {
     text-transform: uppercase;
     margin-top: 0.5rem;
 }
-.verdict-ai {
+.verdict-synthetic {
     background: rgba(239, 68, 68, 0.2);
     color: var(--danger);
 }
-.verdict-human {
+.verdict-authentic {
     background: rgba(16, 185, 129, 0.2);
     color: var(--success);
 }
@@ -1030,7 +982,7 @@ input[type="checkbox"] {
     font-size: 1.1rem !important;
 }
 
-.verdict-mixed {
+.verdict-hybrid {
     background: rgba(168, 85, 247, 0.2);
     color: #a855f7;
     border: 1px solid rgba(168, 85, 247, 0.3);
@@ -1109,11 +1061,11 @@ html {
 <div class="header">
 <a href="#" class="logo" onclick="showLanding(); return false;">
     <div class="logo-icon">🔍</div>
-    <span>AI Text Detector</span>
+    <span>TextAuth Forensics</span>
 </a>
 <div class="nav-links">
     <a href="#features" class="nav-link">Features</a>
-    <a href="#metrics" class="nav-link">Detection Metrics</a>
+    <a href="#metrics" class="nav-link">Forensic Signals</a>
     <a href="#" class="nav-link" onclick="showAnalysis(); return false;">Try It Now</a>
 </div>
 </div>
@@ -1121,26 +1073,27 @@ html {
 <div class="landing-page" id="landing-page">
 <!-- Hero Section -->
 <section class="hero">
-    <h1 class="hero-title">AI Text Detection Platform</h1>
-    <p class="hero-subtitle">Verifying Content Authenticity with Precision</p>
+    <h1 class="hero-title">Evidence-Based Text Forensics Platform</h1>
+    <p class="hero-subtitle">Analyzing Content Authenticity Through Linguistic & Statistical Evidence</p>
     <p class="hero-description">
-        Production-ready platform designed to identify AI-generated content across education, 
-        publishing, hiring, and research domains using sophisticated ensemble detection.
+        A forensic analysis system that evaluates textual evidence using multiple statistical,
+        linguistic, and semantic signals to assess content authenticity across education,
+        publishing, hiring, and research domains.
     </p>
     <button class="try-btn" onclick="showAnalysis()"> Try It Now   → </button>
 </section>
 <!-- Stats -->
 <div class="stats-grid">
     <div class="stat-card">
-        <div class="stat-value">2.4%</div>
-        <div class="stat-label">False Positive Rate</div>
+        <div class="stat-value">Low</div>
+        <div class="stat-label">False-Positive Bias (Domain-Calibrated)</div>
     </div>
     <div class="stat-card">
         <div class="stat-value">6</div>
-        <div class="stat-label">Total Detection Metrics</div>
+        <div class="stat-label">Total Forensic Signals</div>
     </div>
     <div class="stat-card">
-        <div class="stat-value">5s</div>
+        <div class="stat-value">10s</div>
         <div class="stat-label">Average Processing Time</div>
     </div>
 </div>
@@ -1153,23 +1106,23 @@ html {
     <div class="features-grid">
         <div class="feature-card">
             <div class="feature-icon">🎯</div>
-            <h3 class="feature-title">Domain-Aware Detection</h3>
+            <h3 class="feature-title">Domain-Aware Analysis</h3>
             <p class="feature-description">
-                Calibrated thresholds for Academic, Technical, Creative, and Casual content types with specialized detection algorithms for each domain.
+                Calibrated thresholds for Academic, Technical, Creative, and Casual content types with specialized analysis algorithms for each domain.
             </p>
         </div>
         <div class="feature-card">
             <div class="feature-icon">🔬</div>
-            <h3 class="feature-title">6-Metric Ensemble</h3>
+            <h3 class="feature-title">6-Signal Evidence Ensemble</h3>
             <p class="feature-description">
-                Combines Perplexity, Entropy, Statistical, Linguistic, Semantic Analysis, and Multi-Perturbation Stability for comprehensive detection with orthogonal signal capture.
+                Combines perplexity, entropy, structural, linguistic, semantic, and perturbation-stability signals to form a multi-angle forensic evidence profile
             </p>
         </div>
         <div class="feature-card">
             <div class="feature-icon">💡</div>
             <h3 class="feature-title">Explainable Results</h3>
             <p class="feature-description">
-                Sentence-level highlighting with confidence scores and detailed reasoning for every detection decision.
+                Sentence-level highlighting with confidence scores and detailed forensic reasoning for each assessment.
             </p>
         </div>
         <div class="feature-card">
@@ -1179,13 +1132,6 @@ html {
                 Analyze short texts in 1.2 seconds, medium documents in 3.5 seconds with parallel metric computation.
             </p>
         </div>
-        <div class="feature-card">
-            <div class="feature-icon">🤖</div>
-            <h3 class="feature-title">Model Attribution</h3>
-            <p class="feature-description">
-                Identifies which AI model likely generated the text - GPT-4, Claude, Gemini, LLaMA, and more.
-            </p>
-        </div>
         <div class="feature-card">
             <div class="feature-icon">📄</div>
             <h3 class="feature-title">Multi-Format Support</h3>
@@ -1197,29 +1143,29 @@ html {
 </section>
 <!-- Metrics Section -->
 <section class="metrics-info" id="metrics">
-    <h2 class="section-title">Detection Metrics Explained</h2>
+    <h2 class="section-title">Forensic Signals Explained</h2>
     <p class="section-subtitle">
-        Understanding the science behind the detection
+        Understanding the science behind the forensic evaluation
     </p>
     <div class="metric-card">
         <div class="metric-icon-box">📊</div>
         <div class="metric-content">
             <h3>Perplexity <span class="metric-weight">Weight: 25%</span></h3>
-            <p>Measures how predictable the text is using GPT-2 language model. AI-generated text typically has lower perplexity (more predictable) than human writing, which tends to be more varied and surprising.</p>
+            <p>Measures how predictable the text is using reference language model. Model-generated or algorithmically assisted text typically exhibits lower perplexity (more predictable) than human writing, which tends to be more varied and surprising.</p>
         </div>
     </div>
     <div class="metric-card">
         <div class="metric-icon-box">🎲</div>
         <div class="metric-content">
             <h3>Entropy <span class="metric-weight">Weight: 20%</span></h3>
-            <p>Calculates token-level diversity and unpredictability in text sequences. Human writing shows higher entropy with more varied word choices, while AI tends toward more uniform token distributions.</p>
+            <p>Calculates token-level diversity and unpredictability in text sequences. Human writing shows higher entropy with more varied word choices, while algorithmically generated text tends toward more uniform token distributions.</p>
         </div>
     </div>
     <div class="metric-card">
         <div class="metric-icon-box">📈</div>
         <div class="metric-content">
             <h3>Structural Analysis <span class="metric-weight">Weight: 15%</span></h3>
-            <p>Analyzes sentence length variance, punctuation patterns, and lexical burstiness. Human writing exhibits more variation in sentence structure and rhythm compared to AI's consistent patterns.</p>
+            <p>Analyzes sentence length variance, punctuation patterns, and lexical burstiness. Human writing exhibits more variation in sentence structure and rhythm compared to algorithmically generated text, which often shows more uniform patterns.</p>
         </div>
     </div>
     <div class="metric-card">
@@ -1233,21 +1179,21 @@ html {
         <div class="metric-icon-box">🧠</div>
         <div class="metric-content">
             <h3>Semantic Analysis <span class="metric-weight">Weight: 15%</span></h3>
-            <p>Assesses semantic coherence, repetition patterns, and contextual consistency. Detects the subtle semantic fingerprints that distinguish AI-generated content from human writing.</p>
+            <p>Assesses semantic coherence, repetition patterns, and contextual consistency. Identifies semantic consistency patterns that often differ between human-authored and algorithmically generated text.</p>
         </div>
     </div>
     <div class="metric-card">
         <div class="metric-icon-box">🔍</div>
         <div class="metric-content">
             <h3>Multi-Perturbation Stability <span class="metric-weight">Weight: 10%</span></h3>
-            <p>Tests text stability under random perturbations. AI-generated text tends to maintain higher likelihood scores even when slightly modified, while human text shows more variation.</p>
+            <p>Tests text stability under random perturbations. Algorithmically generated text tends to maintain higher likelihood scores even when slightly modified, while human text shows more variation.</p>
         </div>
     </div>
 </section>
 <!-- Footer -->
 <footer class="footer">
-    <p>&copy; 2025 AI Text Detector Platform</p>
-    <p style="margin-top: 1rem;">AI detection with enterprise accuracy and explainability.</p>
+    <p>&copy; 2025 Evidence-Based Text Forensics Platform</p>
+    <p style="margin-top: 1rem;">Evidence-first text forensics with explainable decisions.</p>
 </footer>
 </div>
 <!-- Analysis Interface -->
@@ -1270,7 +1216,7 @@ html {
                     id="text-input" 
                     class="text-input" 
                     placeholder="Paste your text here for analysis...
-The more text you provide (minimum 50 characters), the more accurate the detection will be."
+                    The more text you provide (minimum 50 characters), the more reliable the forensic evaluation will be."
                 ></textarea>
             </div>
             <div id="upload-tab" class="tab-content">
@@ -1300,13 +1246,6 @@ The more text you provide (minimum 50 characters), the more accurate the detecti
                         <option value="social_media">Social Media</option>
                     </select>
                 </div>
-                <div class="option-row">
-                    <label class="option-label">Enable AI Model Attribution:</label>
-                    <div class="checkbox-wrapper">
-                        <input type="checkbox" id="enable-attribution" checked>
-                        <span style="font-size: 0.85rem; color: var(--text-muted);">Identify which AI model generated the text</span>
-                    </div>
-                </div>
                 <div class="option-row">
                     <label class="option-label">Enable Sentence Highlighting:</label>
                     <div class="checkbox-wrapper">
@@ -1366,8 +1305,8 @@ The more text you provide (minimum 50 characters), the more accurate the detecti
                     <div class="empty-icon">✓</div>
                     <h3 class="empty-title">Ready for Analysis</h3>
                     <p class="empty-description">
-                        Paste text or upload a document to begin comprehensive AI detection analysis.
-                        Our 6-metric ensemble will provide detailed insights.
+                        Paste text or upload a document to begin evidence-based forensic analysis.
+                        Our multi-signal ensemble will provide detailed, explainable insights.
                     </p>
                 </div>
             </div>
@@ -1429,7 +1368,6 @@ function resetAnalysisInterface() {
     document.getElementById('paste-tab').classList.add('active');
     // Reset options to defaults
     document.getElementById('domain-select').value = '';
-    document.getElementById('enable-attribution').checked = true;
     document.getElementById('enable-highlighting').checked = true;
     document.getElementById('use-sentence-level').checked = true;
     document.getElementById('include-metrics-summary').checked = true;
@@ -1444,8 +1382,8 @@ function resetAnalysisInterface() {
             <div class="empty-icon">✓</div>
             <h3 class="empty-title">Ready for Analysis</h3>
             <p class="empty-description">
-                Paste text or upload a document to begin comprehensive AI detection analysis.
-                Our 6-metric ensemble will provide detailed insights.
+                Paste text or upload a document to begin evidence-based forensic analysis.
+                Our multi-signal ensemble will provide detailed, explainable insights.
             </p>
         </div>
     `;
@@ -1613,7 +1551,6 @@ async function performAnalysis(mode, text, file) {
 
 async function analyzeText(text) {
     const domain = document.getElementById('domain-select').value || null;
-    const enableAttribution = document.getElementById('enable-attribution').checked;
     const enableHighlighting = document.getElementById('enable-highlighting').checked;
     const useSentenceLevel = document.getElementById('use-sentence-level').checked;
     const includeMetricsSummary = document.getElementById('include-metrics-summary').checked;
@@ -1624,7 +1561,6 @@ async function analyzeText(text) {
         body: JSON.stringify({
             text: text,
             domain: domain,
-            enable_attribution: enableAttribution,
             enable_highlighting: enableHighlighting,
             use_sentence_level: useSentenceLevel,
             include_metrics_summary: includeMetricsSummary,
@@ -1641,14 +1577,12 @@ async function analyzeText(text) {
 
 async function analyzeFile(file) {
     const domain = document.getElementById('domain-select').value || null;
-    const enableAttribution = document.getElementById('enable-attribution').checked;
     const useSentenceLevel = document.getElementById('use-sentence-level').checked;
     const includeMetricsSummary = document.getElementById('include-metrics-summary').checked;
 
     const formData = new FormData();
     formData.append('file', file);
     if (domain) formData.append('domain', domain);
-    formData.append('enable_attribution', enableAttribution.toString());
     formData.append('use_sentence_level', useSentenceLevel.toString());
     formData.append('include_metrics_summary', includeMetricsSummary.toString());
     formData.append('skip_expensive_metrics', 'false');
@@ -1669,7 +1603,7 @@ function showLoading() {
     document.getElementById('summary-report').innerHTML = `
         <div class="loading">
             <div class="spinner"></div>
-            <p style="color: var(--text-secondary);">Analyzing content with 6-metric ensemble...</p>
+            <p style="color: var(--text-secondary);">Analyzing content using multi-signal forensic evaluation...</p>
             <p style="color: var(--text-muted); font-size: 0.9rem; margin-top: 0.5rem;">
                 This may take a few seconds
             </p>
@@ -1704,7 +1638,7 @@ function displayResults(data) {
     const analysis = detection.analysis || {};
 
     // Display Summary with enhanced reasoning
-    displaySummary(ensemble, prediction, analysis, data.attribution, data.reasoning);
+    displaySummary(ensemble, prediction, analysis, data.reasoning);
 
     // Display Highlighted Text with enhanced features
     if (data.highlighted_html) {
@@ -1729,31 +1663,27 @@ function displayResults(data) {
     }
 }
 
-function displaySummary(ensemble, prediction, analysis, attribution, reasoning) {
+function displaySummary(ensemble, prediction, analysis, reasoning) {
     // Extract and validate data with fallbacks
     const {
-        aiProbability,
-        humanProbability,
-        mixedProbability,
+        syntheticProbability,
+        authenticProbability,
+        hybridProbability,
         verdict,
         confidence,
         domain,
-        isAI,
+        isSynthetic,
         gaugeColor,
         gaugeDegree,
         confidenceLevel,
         confidenceClass
     } = extractSummaryData(ensemble, analysis);
 
-    // Generate attribution HTML with proper filtering
-    const attributionHTML = generateAttributionHTML(attribution);
-
     document.getElementById('summary-report').innerHTML = `
         <div class="result-summary">
-            ${createGaugeSection(aiProbability, humanProbability, mixedProbability, gaugeColor, gaugeDegree)}
-            ${createInfoGrid(verdict, confidence, confidenceClass, domain, mixedProbability)}
+            ${createGaugeSection(syntheticProbability, authenticProbability, hybridProbability, gaugeColor, gaugeDegree)}
+            ${createInfoGrid(verdict, confidence, confidenceClass, domain, hybridProbability)}
             ${createEnhancedReasoningHTML(ensemble, analysis, reasoning)}
-            ${attributionHTML}
             ${createDownloadActions()}
         </div>
     `;
@@ -1761,34 +1691,45 @@ function displaySummary(ensemble, prediction, analysis, attribution, reasoning)
 
 // Helper function to extract and validate summary data
 function extractSummaryData(ensemble, analysis) {
-    const aiProbability = ensemble.ai_probability !== undefined ? 
-        (ensemble.ai_probability * 100).toFixed(0) : '0';
-    
-    const humanProbability = ensemble.human_probability !== undefined ? 
-        (ensemble.human_probability * 100).toFixed(0) : '0';
-    
-    const mixedProbability = ensemble.mixed_probability !== undefined ? 
-        (ensemble.mixed_probability * 100).toFixed(0) : '0';
-    
+    const syntheticProbability = ensemble.synthetic_probability !== undefined
+        ? (ensemble.synthetic_probability * 100).toFixed(0)
+        : '0';
+
+    const authenticProbability = ensemble.authentic_probability !== undefined
+        ? (ensemble.authentic_probability * 100).toFixed(0)
+        : '0';
+
+    const hybridProbability = ensemble.hybrid_probability !== undefined
+        ? (ensemble.hybrid_probability * 100).toFixed(0)
+        : '0';
+
     const verdict = ensemble.final_verdict || 'Unknown';
-    const confidence = ensemble.overall_confidence !== undefined ?
-        (ensemble.overall_confidence * 100).toFixed(1) : '0';
+
+    const confidence = ensemble.overall_confidence !== undefined
+        ? (ensemble.overall_confidence * 100).toFixed(1)
+        : '0';
+
     const domain = analysis.domain || 'general';
-    const isAI = verdict.toLowerCase().includes('ai');
-    const gaugeColor = isAI ? 'var(--danger)' : 'var(--success)';
-    const gaugeDegree = aiProbability * 3.6;
-    
+
+    const isSynthetic = verdict.toLowerCase().includes('synthetic');
+
+    const gaugeColor = isSynthetic
+        ? 'var(--danger)'
+        : 'var(--success)';
+
+    const gaugeDegree = parseFloat(syntheticProbability) * 3.6;
+
     const confidenceLevel = getConfidenceLevel(parseFloat(confidence));
     const confidenceClass = getConfidenceClass(confidenceLevel);
 
     return {
-        aiProbability,
-        humanProbability,
-        mixedProbability,
+        syntheticProbability,
+        authenticProbability,
+        hybridProbability,
         verdict,
         confidence,
         domain,
-        isAI,
+        isSynthetic,
         gaugeColor,
         gaugeDegree,
         confidenceLevel,
@@ -1813,104 +1754,33 @@ function getConfidenceClass(confidenceLevel) {
     return classMap[confidenceLevel] || 'confidence-low';
 }
 
-// Helper function to generate attribution HTML with filtering
-function generateAttributionHTML(attribution) {
-    if (!attribution || !attribution.predicted_model) {
-        return '';
-    }
-
-    const modelName = formatModelName(attribution.predicted_model);
-    const modelConf = attribution.confidence ? 
-        (attribution.confidence * 100).toFixed(1) : 'N/A';
-    
-    const topModelsHTML = generateTopModelsHTML(attribution.model_probabilities);
-    const reasoningHTML = generateAttributionReasoningHTML(attribution.reasoning);
-
-    // Only show attribution if confidence is meaningful (>30%)
-    if (attribution.confidence > 0.3) {
-        return `
-            <div class="attribution-section">
-                <div class="attribution-title">🤖 AI Model Attribution</div>
-                ${topModelsHTML}
-                <div class="attribution-confidence">
-                    Attribution Confidence: <strong>${modelConf}%</strong>
-                </div>
-                ${reasoningHTML}
-            </div>
-        `;
-    }
-    
-    return '';
-}
-
-// Helper function to generate top models HTML with filtering
-function generateTopModelsHTML(modelProbabilities) {
-    if (!modelProbabilities) {
-        return '<div class="attribution-uncertain">Model probabilities not available</div>';
-    }
-
-    // Filter and sort models
-    const meaningfulModels = Object.entries(modelProbabilities)
-        .sort((a, b) => b[1] - a[1])
-        .filter(([model, prob]) => prob > 0.15) // Only show models with >15% probability
-        .slice(0, 3); // Show top 3
-
-    if (meaningfulModels.length === 0) {
-        return `
-            <div class="attribution-uncertain">
-                Model attribution uncertain - text patterns don't strongly match any specific AI model
-            </div>
-        `;
-    }
-
-    return meaningfulModels.map(([model, prob]) => 
-        `<div class="model-match">
-            <span class="model-name">${formatModelName(model)}</span>
-            <span class="model-confidence">${(prob * 100).toFixed(1)}%</span>
-        </div>`
-    ).join('');
-}
-
 // Helper function to format model names
 function formatModelName(modelName) {
     return modelName.replace(/_/g, ' ').replace(/-/g, ' ').toUpperCase();
 }
 
-// Helper function to generate attribution reasoning HTML
-function generateAttributionReasoningHTML(reasoning) {
-    if (!reasoning || !Array.isArray(reasoning) || reasoning.length === 0) {
-        return '';
-    }
-
-    return `
-        <div class="attribution-reasoning">
-            ${reasoning[0]}
-        </div>
-    `;
-}
-
 // Helper function to create single-progress gauge section
-function createGaugeSection(aiProbability, humanProbability, mixedProbability, gaugeColor, gaugeDegree) {
+function createGaugeSection(syntheticProbability, authenticProbability, hybridProbability, gaugeColor, gaugeDegree) {
     // Ensure these are numbers
-    const ai = parseFloat(aiProbability);
-    const human = parseFloat(humanProbability);
-    const mixed = parseFloat(mixedProbability);
+    const synthetic = parseFloat(syntheticProbability);
+    const authentic = parseFloat(authenticProbability);
+    const hybrid = parseFloat(hybridProbability);
     
     // Determine which probability is highest
     let maxValue, maxColor, maxLabel;
     
-    if (ai >= human && ai >= mixed) {
-        maxValue = ai;
+    if (synthetic >= authentic && synthetic >= hybrid) {
+        maxValue = synthetic;
         maxColor = 'var(--danger)';
-        maxLabel = 'AI Probability';
-    } else if (human >= ai && human >= mixed) {
-        maxValue = human;
+        maxLabel = 'Synthetic Probability';
+    } else if (authentic >= synthetic && authentic >= hybrid) {
+        maxValue = authentic;
         maxColor = 'var(--success)';
-        maxLabel = 'Human Probability';
+        maxLabel = 'Authentic Probability';
     } else {
-        maxValue = mixed;
+        maxValue = hybrid;
         maxColor = 'var(--primary)';
-        maxLabel = 'Mixed Probability';
+        maxLabel = 'Hybrid Probability';
     }
     
     console.log('Selected:', { maxValue, maxLabel });
@@ -1936,16 +1806,16 @@ function createGaugeSection(aiProbability, humanProbability, mixedProbability, g
         </div>
         <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1rem; margin: 1.5rem 0;">
             <div style="text-align: center; padding: 1rem; background: rgba(239, 68, 68, 0.1); border-radius: 8px; border: 1px solid rgba(239, 68, 68, 0.3);">
-                <div style="font-size: 0.85rem; color: var(--danger); margin-bottom: 0.25rem; font-weight: 600;">AI</div>
-                <div style="font-size: 1.4rem; font-weight: 700; color: var(--danger);">${aiProbability}%</div>
+                <div style="font-size: 0.85rem; color: var(--danger); margin-bottom: 0.25rem; font-weight: 600;">Synthetic</div>
+                <div style="font-size: 1.4rem; font-weight: 700; color: var(--danger);">${syntheticProbability}%</div>
             </div>
             <div style="text-align: center; padding: 1rem; background: rgba(16, 185, 129, 0.1); border-radius: 8px; border: 1px solid rgba(16, 185, 129, 0.3);">
-                <div style="font-size: 0.85rem; color: var(--success); margin-bottom: 0.25rem; font-weight: 600;">Human</div>
-                <div style="font-size: 1.4rem; font-weight: 700; color: var(--success);">${humanProbability}%</div>
+                <div style="font-size: 0.85rem; color: var(--success); margin-bottom: 0.25rem; font-weight: 600;">Authentic</div>
+                <div style="font-size: 1.4rem; font-weight: 700; color: var(--success);">${authenticProbability}%</div>
             </div>
             <div style="text-align: center; padding: 1rem; background: rgba(6, 182, 212, 0.1); border-radius: 8px; border: 1px solid rgba(6, 182, 212, 0.3);">
-                <div style="font-size: 0.85rem; color: var(--primary); margin-bottom: 0.25rem; font-weight: 600;">Mixed</div>
-                <div style="font-size: 1.4rem; font-weight: 700; color: var(--primary);">${mixedProbability}%</div>
+                <div style="font-size: 0.85rem; color: var(--primary); margin-bottom: 0.25rem; font-weight: 600;">Hybrid</div>
+                <div style="font-size: 1.4rem; font-weight: 700; color: var(--primary);">${hybridProbability}%</div>
             </div>
         </div>
         <style>
@@ -1989,10 +1859,10 @@ function createGaugeSection(aiProbability, humanProbability, mixedProbability, g
 
 
 // Helper function to create info grid
-function createInfoGrid(verdict, confidence, confidenceClass, domain, mixedProbability) {
-    const mixedContentInfo = mixedProbability > 10 ? 
+function createInfoGrid(verdict, confidence, confidenceClass, domain, hybridProbability) {
+    const hybridContentInfo = hybridProbability > 10 ? 
         `<div style="margin-top: 0.5rem; font-size: 0.85rem; color: var(--primary);">
-            🔀 ${mixedProbability}% Mixed Content Detected
+            🔀 ${hybridProbability}% Hybrid Content Detected
         </div>` : '';
 
     return `
@@ -2000,7 +1870,7 @@ function createInfoGrid(verdict, confidence, confidenceClass, domain, mixedProba
             <div class="info-card">
                 <div class="info-label">Verdict</div>
                 <div class="info-value verdict-text">${verdict}</div>
-                ${mixedContentInfo}
+                ${hybridContentInfo}
             </div>
             <div class="info-card">
                 <div class="info-label">Confidence Level</div>
@@ -2040,6 +1910,21 @@ function createEnhancedReasoningHTML(ensemble, analysis, reasoning) {
     if (reasoning && reasoning.summary) {
         // Process the summary into bullet points
         const bulletPoints = formatSummaryAsBulletPoints(reasoning.summary, ensemble, analysis);
+
+        const dominantLabel =
+            ensemble.hybrid_probability > ensemble.synthetic_probability &&
+            ensemble.hybrid_probability > ensemble.authentic_probability
+                ? 'Hybrid Probability'
+                : ensemble.synthetic_probability > ensemble.authentic_probability
+                    ? 'Synthetic Probability'
+                    : 'Authentic Probability';
+
+        const dominantValue =
+            Math.max(
+                ensemble.synthetic_probability,
+                ensemble.authentic_probability,
+                ensemble.hybrid_probability
+            );
         
         // Process key indicators with markdown formatting
         let processedIndicators = [];
@@ -2071,14 +1956,15 @@ function createEnhancedReasoningHTML(ensemble, analysis, reasoning) {
             <div class="reasoning-box enhanced">
                 <div class="reasoning-header">
                     <div class="reasoning-icon">💡</div>
-                    <div class="reasoning-title">Detection Reasoning</div>
+                    <div class="reasoning-title">Forensic Reasoning</div>
                     <div class="confidence-tag ${ensemble.overall_confidence >= 0.7 ? 'high-confidence' : ensemble.overall_confidence >= 0.4 ? 'medium-confidence' : 'low-confidence'}">
                         ${ensemble.overall_confidence >= 0.7 ? 'High Confidence' : ensemble.overall_confidence >= 0.4 ? 'Medium Confidence' : 'Low Confidence'}
                     </div>
                 </div>
                 <div class="verdict-summary">
                     <div class="verdict-text">${ensemble.final_verdict}</div>
-                    <div class="probability">AI Probability: <span class="probability-value">${(ensemble.ai_probability * 100).toFixed(2)}%</span></div>
+                       ${dominantLabel}:
+                       <span class="probability-value">${(dominantValue * 100).toFixed(2)}%</span>
                 </div>
                 <div class="reasoning-bullet-points">
                     ${bulletPoints}
@@ -2130,11 +2016,11 @@ function createEnhancedReasoningHTML(ensemble, analysis, reasoning) {
     // Fallback to basic reasoning if no reasoning data
     return `
         <div class="reasoning-box">
-            <div class="reasoning-title">💡 Detection Reasoning</div>
+            <div class="reasoning-title">💡 Forensic Reasoning</div>
             <p class="reasoning-text" style="text-align: left;">
-                Analysis based on 6-metric ensemble with domain-aware calibration. 
-                The system evaluated linguistic patterns, statistical features, and semantic structures 
-                to determine content authenticity with ${(ensemble.overall_confidence * 100).toFixed(1)}% confidence.
+                Analysis based on a multi-signal forensic ensemble with domain-aware calibration.
+                The system evaluated linguistic, statistical, and semantic evidence patterns
+                to assess content authenticity with ${(ensemble.overall_confidence * 100).toFixed(1)}% confidence.
             </p>
         </div>
     `;
@@ -2170,15 +2056,15 @@ function formatSummaryAsBulletPoints(summary, ensemble, analysis) {
     // Add verdict as second bullet
     bulletPoints.push(`<div class="bullet-point">• ${ensemble.final_verdict}</div>`);
     
-    // Add AI probability as third bullet
-    bulletPoints.push(`<div class="bullet-point">• AI Probability: ${(ensemble.ai_probability * 100).toFixed(2)}%</div>`);
+    // Add Synthetic probability as third bullet
+    bulletPoints.push(`<div class="bullet-point">• Synthetic Probability: ${(ensemble.synthetic_probability * 100).toFixed(2)}%</div>`);
     
     // Add the main analysis sentences as individual bullets
     sentences.forEach(sentence => {
         if (sentence.trim() && 
             !sentence.includes('confidence') && 
             !sentence.includes(ensemble.final_verdict) &&
-            !sentence.includes('AI probability')) {
+            !sentence.includes('Synthetic probability')) {
             // Clean up the sentence and add as bullet
             let cleanSentence = sentence.trim();
             if (!cleanSentence.endsWith('.')) {
@@ -2205,36 +2091,20 @@ function createDefaultLegend() {
     return `
         <div class="highlight-legend">
             <div class="legend-item">
-                <div class="legend-color" style="background: #fecaca;"></div>
-                <div class="legend-label">Very Likely AI (90-100%)</div>
-            </div>
-            <div class="legend-item">
-                <div class="legend-color" style="background: #fed7aa;"></div>
-                <div class="legend-label">Likely AI (75-90%)</div>
-            </div>
-            <div class="legend-item">
-                <div class="legend-color" style="background: #fde68a;"></div>
-                <div class="legend-label">Possibly AI (60-75%)</div>
+                <div class="legend-color" style="background: #dcfce7;"></div>
+                <div class="legend-label">Authentic</div>
             </div>
             <div class="legend-item">
                 <div class="legend-color" style="background: #fef9c3;"></div>
-                <div class="legend-label">Uncertain (40-60%)</div>
-            </div>
-            <div class="legend-item">
-                <div class="legend-color" style="background: #86efac;"></div>
-                <div class="legend-label">Possibly Human (25-40%)</div>
+                <div class="legend-label">Uncertain</div>
             </div>
             <div class="legend-item">
-                <div class="legend-color" style="background: #bbf7d0;"></div>
-                <div class="legend-label">Likely Human (10-25%)</div>
-            </div>
-            <div class="legend-item">
-                <div class="legend-color" style="background: #dcfce7;"></div>
-                <div class="legend-label">Very Likely Human (0-10%)</div>
+                <div class="legend-color" style="background: #fee2e2;"></div>
+                <div class="legend-label">Synthetic</div>
             </div>
             <div class="legend-item">
                 <div class="legend-color" style="background: #e9d5ff;"></div>
-                <div class="legend-label">Mixed Content</div>
+                <div class="legend-label">Hybrid</div>
             </div>
         </div>
     `;
@@ -2259,15 +2129,15 @@ function getHighlightStyles() {
                 z-index: 10;
                 text-shadow: 0 1px 1px rgba(255,255,255,0.8);
             }
-            #highlighted-report .very-high-ai {
+            #highlighted-report .very-high-synthetic {
                 background-color: #fee2e2 !important;
                 border-bottom-color: #ef4444 !important;
             }
-            #highlighted-report .high-ai {
+            #highlighted-report .high-synthetic {
                 background-color: #fed7aa !important;
                 border-bottom-color: #f97316 !important;
             }
-            #highlighted-report .medium-ai {
+            #highlighted-report .medium-synthetic {
                 background-color: #fef3c7 !important;
                 border-bottom-color: #f59e0b !important;
             }
@@ -2275,19 +2145,19 @@ function getHighlightStyles() {
                 background-color: #fef9c3 !important;
                 border-bottom-color: #fbbf24 !important;
             }
-            #highlighted-report .medium-human {
+            #highlighted-report .medium-authentic {
                 background-color: #ecfccb !important;
                 border-bottom-color: #a3e635 !important;
             }
-            #highlighted-report .high-human {
+            #highlighted-report .high-authentic {
                 background-color: #bbf7d0 !important;
                 border-bottom-color: #4ade80 !important;
             }
-            #highlighted-report .very-high-human {
+            #highlighted-report .very-high-authentic {
                 background-color: #dcfce7 !important;
                 border-bottom-color: #22c55e !important;
             }
-            #highlighted-report .mixed-content {
+            #highlighted-report .hybrid-content {
                 background-color: #e9d5ff !important;
                 border-bottom-color: #a855f7 !important;
                 background-image: repeating-linear-gradient(45deg, transparent, transparent 5px, rgba(168, 85, 247, 0.1) 5px, rgba(168, 85, 247, 0.1) 10px) !important;
@@ -2319,27 +2189,27 @@ function displayMetricsCarousel(metrics, analysis, ensemble) {
         const metric = metrics[metricKey];
         if (!metric) return;
 
-        const aiProb = (metric.ai_probability * 100).toFixed(1);
-        const humanProb = (metric.human_probability * 100).toFixed(1);
-        const mixedProb = (metric.mixed_probability * 100).toFixed(1);
+        const syntheticProb = (metric.synthetic_probability * 100).toFixed(1);
+        const authenticProb = (metric.authentic_probability * 100).toFixed(1);
+        const hybridProb = (metric.hybrid_probability * 100).toFixed(1);
         const confidence = (metric.confidence * 100).toFixed(1);
         const weight = ensemble.metric_contributions && ensemble.metric_contributions[metricKey] ?
             (ensemble.metric_contributions[metricKey].weight * 100).toFixed(1) : '0.0';
         
         // Determine verdict based on probabilities
         let verdictText, verdictClass;
-        if (metric.mixed_probability > 0.3) {
-            verdictText = 'MIXED';
-            verdictClass = 'verdict-mixed';
-        } else if (metric.ai_probability >= 0.6) {
-            verdictText = 'AI';
-            verdictClass = 'verdict-ai';
-        } else if (metric.ai_probability >= 0.4) {
-            verdictText = 'UNCERTAIN';
+        if (metric.hybrid_probability > 0.3) {
+            verdictText = 'Hybrid';
+            verdictClass = 'verdict-hybrid';
+        } else if (metric.synthetic_probability >= 0.6) {
+            verdictText = 'Synthetic';
+            verdictClass = 'verdict-synthetic';
+        } else if (metric.synthetic_probability >= 0.4) {
+            verdictText = 'Uncertain';
             verdictClass = 'verdict-uncertain';
         } else {
-            verdictText = 'HUMAN';
-            verdictClass = 'verdict-human';
+            verdictText = 'Authentic';
+            verdictClass = 'verdict-authentic';
         }
 
         carouselHTML += `
@@ -2352,28 +2222,28 @@ function displayMetricsCarousel(metrics, analysis, ensemble) {
                         ${getMetricDescription(metricKey)}
                     </div>
                     
-                    <!-- Enhanced Probability Display with Mixed -->
+                    <!-- Probability Display with Hybrid -->
                     <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1rem; margin: 1rem 0;">
                         <div style="text-align: center;">
-                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">AI</div>
+                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Synthetic</div>
                             <div style="background: rgba(51, 65, 85, 0.5); height: 8px; border-radius: 4px; overflow: hidden;">
-                                <div style="background: var(--danger); height: 100%; width: ${aiProb}%; transition: width 0.5s;"></div>
+                                <div style="background: var(--danger); height: 100%; width: ${syntheticProb}%; transition: width 0.5s;"></div>
                             </div>
-                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${aiProb}%</div>
+                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${syntheticProb}%</div>
                         </div>
                         <div style="text-align: center;">
-                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Human</div>
+                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Authentic</div>
                             <div style="background: rgba(51, 65, 85, 0.5); height: 8px; border-radius: 4px; overflow: hidden;">
-                                <div style="background: var(--success); height: 100%; width: ${humanProb}%; transition: width 0.5s;"></div>
+                                <div style="background: var(--success); height: 100%; width: ${authenticProb}%; transition: width 0.5s;"></div>
                             </div>
-                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${humanProb}%</div>
+                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${authenticProb}%</div>
                         </div>
                         <div style="text-align: center;">
-                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Mixed</div>
+                            <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Hybrid</div>
                             <div style="background: rgba(51, 65, 85, 0.5); height: 8px; border-radius: 4px; overflow: hidden;">
-                                <div style="background: var(--primary); height: 100%; width: ${mixedProb}%; transition: width 0.5s;"></div>
+                                <div style="background: var(--primary); height: 100%; width: ${hybridProb}%; transition: width 0.5s;"></div>
                             </div>
-                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${mixedProb}%</div>
+                            <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${hybridProb}%</div>
                         </div>
                     </div>
                     
@@ -2448,7 +2318,7 @@ function renderMetricDetails(metricName, details) {
         'entropy': ['token_diversity', 'sequence_unpredictability', 'char_entropy'],
         'semantic_analysis': ['coherence_score', 'consistency_score', 'repetition_score'],
         'linguistic': ['pos_diversity', 'syntactic_complexity', 'grammatical_consistency'],
-        'multi_perturbation_stability': ['stability_score', 'curvature_score', 'likelihood_ratio', 'perturbation_variance', 'mixed_probability']
+        'multi_perturbation_stability': ['stability_score', 'curvature_score', 'likelihood_ratio', 'perturbation_variance', 'hybrid_probability']
     };
 
     const keysToShow = importantKeys[metricName] || Object.keys(details).slice(0, 6);
@@ -2533,7 +2403,7 @@ async function downloadReport(format) {
             const blob = new Blob([JSON.stringify(data, null, 2)], { 
                 type: 'application/json' 
             });
-            const filename = `ai-detection-report-${analysisId}-${timestamp}.json`;
+            const filename = `text-forensics-report-${analysisId}-${timestamp}.json`;
             await downloadBlob(blob, filename);
             return;
         }
@@ -2572,7 +2442,7 @@ async function downloadReport(format) {
                 throw new Error('Failed to download file');
             }
             const blob = await downloadResponse.blob();
-            const downloadFilename = `ai-detection-${format}-report-${analysisId}-${timestamp}.${format}`;
+            const downloadFilename = `text-forensics-report-${format}-report-${analysisId}-${timestamp}.${format}`;
             await downloadBlob(blob, downloadFilename);
         } else {
             alert('Report file not available');

utils/logger.py

@@ -1,8 +1,5 @@
 # DEPENDENCIES
-import os
 import sys
-import json
-import time
 import logging
 from typing import Any
 from typing import Dict
@@ -31,52 +28,16 @@ class InterceptHandler(logging.Handler):
         # Find caller from where originated the logged message
         frame, depth = logging.currentframe(), 2
         while (frame.f_code.co_filename == logging.__file__):
-            frame  = frame.f_back
-            depth += 1
+               frame  = frame.f_back
+               depth += 1
         
-        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
-
-
-class JSONFormatter:
-    """
-    JSON formatter for structured logging
-    """
-    def __init__(self):
-        self.pid = os.getpid()
+        logger.opt(depth = depth, exception = record.exc_info).log(level, record.getMessage())
     
 
-    def format(self, record: Dict[str, Any]) -> str:
-        """
-        Format log record as JSON
-        """
-        # Create structured log entry
-        log_entry = {"timestamp"  : datetime.fromtimestamp(record["time"].timestamp()).isoformat(),
-                     "level"      : record["level"].name,
-                     "message"    : record["message"],
-                     "module"     : record["name"],
-                     "function"   : record["function"],
-                     "line"       : record["line"],
-                     "process_id" : self.pid,
-                     "thread_id"  : record["thread"].id if record.get("thread") else None,
-                    }
-        
-        # Add exception info if present
-        if record.get("exception"):
-            log_entry["exception"] = {"type"      : str(record["exception"].type),
-                                      "value"     : str(record["exception"].value),
-                                      "traceback" : "".join(record["exception"].traceback).strip() if record["exception"].traceback else None,
-                                     }
-        
-        # Add extra fields
-        if record.get("extra"):
-            log_entry.update(record["extra"])
-        
-        return json.dumps(log_entry, ensure_ascii=False, default=str)
-
 
 class CentralizedLogger:
     """
-    Centralized logging system for AI Text Detector
+    Centralized logging system for Text Authenticator
     
     Features:
     - Structured JSON logging for production
@@ -305,7 +266,7 @@ class CentralizedLogger:
         """
         performance_data = {"operation"        : operation,
                             "duration_seconds" : round(duration, 4),
-                            "timestamp"        : datetime.now().isoformat(),
+                            "timestamp"        : datetime.utcnow().isoformat(),
                             **kwargs
                            }
         
@@ -331,7 +292,7 @@ class CentralizedLogger:
         security_data = {"event_type" : event_type,
                          "user"       : user,
                          "ip_address" : ip,
-                         "timestamp"  : datetime.now().isoformat(),
+                         "timestamp"  : datetime.utcnow().isoformat(),
                          **kwargs,
                         }
         
@@ -365,7 +326,7 @@ class CentralizedLogger:
                         "duration_seconds" : round(duration, 4),
                         "user"             : user,
                         "ip_address"       : ip,
-                        "timestamp"        : datetime.now().isoformat(),
+                        "timestamp"        : datetime.utcnow().isoformat(),
                         **kwargs
                        }
         
@@ -386,9 +347,9 @@ class CentralizedLogger:
                        )
     
 
-    def log_detection_event(self, analysis_id: str, text_length: int, verdict: str, confidence: float, domain: str, processing_time: float, **kwargs) -> None:
+    def log_analysis_event(self, analysis_id: str, text_length: int, assessment: str, signal_strength: float, domain: str, processing_time: float, **kwargs) -> None:
         """
-        Log text detection events
+        Log text analysis events
         
         Arguments:
         ----------
@@ -396,28 +357,28 @@ class CentralizedLogger:
 
             text_length     { int }   : Length of analyzed text
             
-            verdict         { str }   : Detection verdict
+            assessment       { str }  : Analysis assessment
             
-            confidence      { float } : Confidence score
+            signal_strength { float } : signal_strength score
             
             domain          { str }   : Content domain
             
             processing_time { float } : Processing time in seconds
             
-            **kwargs                  : Additional detection context
+            **kwargs                  : Additional Analysis context
         """
-        detection_data = {"analysis_id"             : analysis_id,
+        analysis_data  = {"analysis_id"             : analysis_id,
                           "text_length"             : text_length,
-                          "verdict"                 : verdict,
-                          "confidence"              : round(confidence, 4),
+                          "assessment"              : assessment,
+                          "signal_strength"         : round(signal_strength, 4),
                           "domain"                  : domain,
                           "processing_time_seconds" : round(processing_time, 4),
-                          "timestamp"               : datetime.now().isoformat(),
+                          "timestamp"               : datetime.utcnow().isoformat(),
                           **kwargs
                         }
         
-        logger.bind(log_type = "application").info(f"Detection completed: {analysis_id} -> {verdict}",
-                    extra    = detection_data,
+        logger.bind(log_type = "application").info(f"Analysis completed: {analysis_id} -> {assessment}",
+                    extra    = analysis_data,
                    )
 
     
@@ -438,7 +399,7 @@ class CentralizedLogger:
         model_data = {"model_name"        : model_name,
                       "success"           : success,
                       "load_time_seconds" : round(load_time, 4),
-                      "timestamp"         : datetime.now().isoformat(),
+                      "timestamp"         : datetime.utcnow().isoformat(),
                       **kwargs
                      }
         
@@ -470,7 +431,7 @@ class CentralizedLogger:
         error_data = {"error_type" : error_type,
                       "message"    : message,
                       "context"    : context or {},
-                      "timestamp"  : datetime.now().isoformat(),
+                      "timestamp"  : datetime.utcnow().isoformat(),
                      }
         
         if exception:
@@ -498,7 +459,7 @@ class CentralizedLogger:
         """
         startup_data = {"component" : component,
                         "success"   : success,
-                        "timestamp" : datetime.now().isoformat(),
+                        "timestamp" : datetime.utcnow().isoformat(),
                         **kwargs
                        }
         
@@ -518,7 +479,7 @@ class CentralizedLogger:
         Cleanup logging resources
         """
         try:
-            logger.complete()
+            logger.remove()
             logger.info("Logging system cleanup completed")
         
         except Exception as e:
@@ -566,11 +527,11 @@ def log_api_request(method: str, path: str, status_code: int, duration: float, u
     central_logger.log_api_request(method, path, status_code, duration, user, ip, **kwargs)
 
 
-def log_detection_event(analysis_id: str, text_length: int,  verdict: str, confidence: float, domain: str, processing_time: float, **kwargs) -> None:
+def log_analysis_event(analysis_id: str, text_length: int,  assessment: str, signal_strength: float, domain: str, processing_time: float, **kwargs) -> None:
     """
-    Log text detection events
+    Log text analysis events
     """
-    central_logger.log_detection_event(analysis_id, text_length, verdict, confidence, domain, processing_time, **kwargs)
+    central_logger.log_analysis_event(analysis_id, text_length, assessment, signal_strength, domain, processing_time, **kwargs)
 
 
 def log_model_loading(model_name: str, success: bool, load_time: float, **kwargs) -> None:
@@ -606,5 +567,5 @@ __all__ = ["log_error",
            "CentralizedLogger",
            "log_model_loading",
            "log_security_event",
-           "log_detection_event",
+           "log_analysis_event",
           ]