Repo updated

.gitignore

@@ -0,0 +1,46 @@
+# .gitignore
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# models
+models/cache
+
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+
+# Environment variables
+.env
+.env.local

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Satyaki Mitra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,584 @@
+<div align="center">
+
+# 🔍 AI Text Authentication Platform
+## Enterprise‑Grade AI Content Authentication
+
+![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
+![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)
+![Accuracy](https://img.shields.io/badge/accuracy-~90%25+-success.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Code Style](https://img.shields.io/badge/code%20style-black-black.svg)
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [Abstract](#abstract)
+- [Overview](#overview)
+- [Key Differentiators](#key-differentiators)
+- [System Architecture](#system-architecture)
+- [Workflow / Data Flow](#workflow--data-flow)
+- [Detection Metrics & Mathematical Foundation](#detection-metrics--mathematical-foundation)
+- [Ensemble Methodology](#ensemble-methodology)
+- [Domain-Aware Detection](#domain-aware-detection)
+- [Performance Characteristics](#performance-characteristics)
+- [Project Structure](#project-structure)
+- [API Endpoints](#api-endpoints)
+- [Installation & Setup](#installation--setup)
+- [Model Management & First-Run Behavior](#model-management--first-run-behavior)
+- [Frontend Features](#frontend-features)
+- [Business Model & Market Analysis](#business-model--market-analysis)
+- [Research Impact & Future Scope](#research-impact--future-scope)
+- [Infrastructure & Deployment](#infrastructure--deployment)
+- [Security & Risk Mitigation](#security--risk-mitigation)
+- [Continuous Improvement Pipeline](#continuous-improvement-pipeline)
+- [License & Acknowledgments](#license--acknowledgments)
+
+---
+
+## 📝 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.
+
+This README is research‑grade (detailed math, methodology, and benchmarks) while being approachable for recruiters and technical reviewers.
+
+*For detailed technical documentation, see [Technical Docs](docs/BLOGPOST.md). For research methodology, see [Whitepaper](docs/WHITE_PAPER.md).*
+
+---
+
+## 🚀 Overview
+
+**Problem.** AI generation tools increasingly produce publishable text, creating integrity and verification challenges in education, hiring, publishing, and enterprise content systems.
+
+**Solution.** A domain‑aware detector combining six orthogonal metrics (Perplexity, Entropy, Structural, Semantic, Linguistic, DetectGPT perturbation stability) into a confidence‑calibrated ensemble. Outputs are explainable with sentence‑level highlighting, attribution probabilities, and downloadable reports (JSON/PDF).
+
+**MVP Scope.** End‑to‑end FastAPI backend, lightweight HTML UI, modular metrics, Hugging Face model auto‑download, and a prototype ensemble classifier. Model weights are not committed to the repo; they are fetched at first run.
+
+---
+
+## 🎯 Key Differentiators
+
+| Feature | Description | Impact |
+|---|---:|---|
+| **Domain‑Aware Detection** | Per‑domain thresholding and weight tuning (academic, technical, creative, social) | ↑15–20% accuracy vs generic detectors |
+| **6‑Metric Ensemble** | Orthogonal signals across statistical, syntactic and semantic dimensions | Low false positives (≈2–3%) |
+| **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 |
+
+---
+
+## 🏗️ System Architecture
+
+### Architecture (Dark‑themed Mermaid)
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart LR
+    subgraph FE [Frontend Layer]
+        A[Web UI<br/>File Upload & Input]
+        B[Interactive Dashboard]
+    end
+
+    subgraph API [API & Gateway]
+        C[FastAPI<br/>Auth & Rate Limit]
+    end
+
+    subgraph ORCH [Detection Orchestrator]
+        D[Domain Classifier]
+        E[Preprocessor]
+        F[Metric Coordinator]
+    end
+
+    subgraph METRICS [Metrics Pool]
+        P1[Perplexity]
+        P2[Entropy]
+        P3[Structural]
+        P4[Linguistic]
+        P5[Semantic]
+        P6[DetectGPT]
+    end
+
+    G[Ensemble Classifier]
+    H[Postprocessing & Reporter]
+    I["Model Manager<br/>(HuggingFace Cache)"]
+    J[Storage: Logs, Reports, Cache]
+
+    A --> C
+    B --> C
+    C --> ORCH
+    ORCH --> METRICS
+    METRICS --> G
+    G --> H
+    H --> C
+    I --> ORCH
+    C --> J
+```
+
+**Notes:** The orchestrator schedules parallel metric computation, handles timeouts, and coordinates with the model manager for model loading and caching.
+
+---
+
+## 🔁 Workflow / Data Flow
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+sequenceDiagram
+    participant U as User (UI/API)
+    participant API as FastAPI
+    participant O as Orchestrator
+    participant M as Metrics Pool
+    participant E as Ensemble
+    participant R as Reporter
+
+    U->>API: Submit text / upload file
+    API->>O: Validate & enqueue job
+    O->>M: Preprocess & dispatch metrics (parallel)
+    M-->>O: Metric results (async)
+    O->>E: Aggregate & calibrate
+    E-->>O: Final verdict + uncertainty
+    O->>R: Generate highlights & report
+    R-->>API: Report ready (JSON/PDF)
+    API-->>U: Return analysis + download link
+```
+
+---
+
+## 🧮 Detection Metrics & 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.
+
+### Metric summary (weights are configurable per domain)
+- Perplexity — 25%
+- Entropy — 20%
+- Structural — 15%
+- Semantic — 15%
+- Linguistic — 15%
+- DetectGPT (perturbation stability) — 10%
+
+### 1) Perplexity (25% weight)
+
+**Definition**
+\(\displaystyle Perplexity = \exp\left(-\frac{1}{N}\sum_{i=1}^N \log P(w_i\mid context)\right)\)
+
+**Implementation sketch**
+```python
+def calculate_perplexity(text, model, k=512):
+    tokens = tokenize(text)
+    log_probs = []
+    for i in range(len(tokens)):
+        context = tokens[max(0, i-k):i]
+        prob = model.get_probability(tokens[i], context)
+        log_probs.append(math.log(prob))
+    return math.exp(-sum(log_probs)/len(tokens))
+```
+
+**Domain calibration example**
+```python
+if domain == Domain.ACADEMIC:
+    perplexity_threshold *= 1.2
+elif domain == Domain.SOCIAL_MEDIA:
+    perplexity_threshold *= 0.8
+```
+
+### 2) Entropy (20% weight)
+
+**Shannon entropy (token level)**
+\(\;H(X) = -\sum_{i} p(x_i)\log_2 p(x_i)\)
+
+**Implementation sketch**
+```python
+from collections import Counter
+def calculate_text_entropy(text):
+    tokens = text.split()
+    token_freq = Counter(tokens)
+    total = len(tokens)
+    entropy = -sum((f/total) * math.log2(f/total) for f in token_freq.values())
+    return entropy
+```
+
+### 3) Structural Metric (15% weight)
+
+**Burstiness**
+\(\displaystyle Burstiness=\frac{\sigma-\mu}{\sigma+\mu}\) where \(\mu\)=mean sentence length, \(\sigma\)=std dev
+
+**Uniformity**
+\(\displaystyle Uniformity = 1 - \frac{\sigma}{\mu}\)
+
+**Sketch**
+```python
+def calculate_burstiness(text):
+    sentences = split_sentences(text)
+    lengths = [len(s.split()) for s in sentences]
+    mean_len = np.mean(lengths)
+    std_len = np.std(lengths)
+    burstiness = (std_len - mean_len) / (std_len + mean_len)
+    uniformity = 1 - (std_len/mean_len if mean_len > 0 else 0)
+    return {'burstiness': burstiness, 'uniformity': uniformity}
+```
+
+### 4) Semantic Analysis (15% weight)
+
+**Coherence (sentence embedding cosine similarity)**
+\(\displaystyle Coherence=\frac{1}{n}\sum_{i=1}^{n-1} \cos(e_i, e_{i+1})\)
+
+**Sketch**
+```python
+def calculate_semantic_coherence(text, embed_model):
+    sentences = split_sentences(text)
+    embeddings = [embed_model.encode(s) for s in sentences]
+    sims = [cosine_similarity(embeddings[i], embeddings[i+1]) for i in range(len(embeddings)-1)]
+    return {'mean_coherence': np.mean(sims), 'coherence_variance': np.var(sims)}
+```
+
+### 5) Linguistic Metric (15% weight)
+
+**POS diversity, parse tree depth, syntactic complexity**
+
+```python
+def calculate_linguistic_features(text, nlp_model):
+    doc = nlp_model(text)
+    pos_tags = [token.pos_ for token in doc]
+    pos_diversity = len(set(pos_tags))/len(pos_tags)
+    depths = [max(get_tree_depth(token) for token in sent) for sent in doc.sents]
+    return {'pos_diversity': pos_diversity, 'mean_tree_depth': np.mean(depths)}
+```
+
+### 6) DetectGPT (10% weight)
+
+**Stability under perturbation** (curvature principle)
+\(\displaystyle Stability = \frac{1}{n}\sum_{j} \left|\log P(x) - \log P(x_{perturbed}^j)\right|\)
+
+```python
+def detect_gpt_score(text, model, num_perturbations=20):
+    original = model.get_log_probability(text)
+    diffs = []
+    for _ in range(num_perturbations):
+        perturbed = generate_perturbation(text)
+        diffs.append(abs(original - model.get_log_probability(perturbed)))
+    return np.mean(diffs)
+```
+
+---
+
+## 🏛️ Ensemble Methodology
+
+### Confidence‑Calibrated Aggregation (high level)
+- Start with domain base weights (e.g., `DOMAIN_WEIGHTS` in `config/threshold_config.py`)
+- Adjust weights per metric with a sigmoid confidence scaling function
+- Normalize and compute weighted aggregate
+- Quantify uncertainty using variance, confidence means, and decision distance from 0.5
+
+```python
+def ensemble_aggregation(metric_results, domain):
+    base = get_domain_weights(domain)
+    adj = {m: base[m] * sigmoid_confidence(r.confidence) for m, r in metric_results.items()}
+    total = sum(adj.values())
+    final_weights = {k: v/total for k, v in adj.items()}
+    return weighted_aggregate(metric_results, final_weights)
+```
+
+### Uncertainty Quantification
+```python
+def calculate_uncertainty(metric_results, ensemble_result):
+    var_uncert = np.var([r.ai_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)
+    return var_uncert*0.4 + conf_uncert*0.3 + decision_uncert*0.3
+```
+
+---
+
+## 🧭 Domain‑Aware Detection
+
+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,'detect_gpt':0.10},
+  'technical': {'perplexity':0.20,'entropy':0.18,'structural':0.12,'linguistic':0.18,'semantic':0.22,'detect_gpt':0.10},
+  'creative': {'perplexity':0.25,'entropy':0.25,'structural':0.20,'linguistic':0.12,'semantic':0.10,'detect_gpt':0.08},
+  'social_media': {'perplexity':0.30,'entropy':0.22,'structural':0.15,'linguistic':0.10,'semantic':0.13,'detect_gpt':0.10}
+}
+```
+
+### Domain Calibration Strategy (brief)
+- **Academic**: increase linguistic weight, raise perplexity multiplier
+- **Technical**: prioritize semantic coherence, maximize AI threshold to reduce false positives
+- **Creative**: boost entropy & structural weights for burstiness detection
+- **Social Media**: prioritize perplexity and relax linguistic demands
+
+---
+
+## ⚡ Performance Characteristics
+
+### Processing Times & Resource Estimates
+
+| Text Length | Typical Time | vCPU | RAM |
+|---:|---:|---:|---:|
+| Short (100–500 words) | 1.2 s | 0.8 vCPU | 512 MB |
+| Medium (500–2000 words) | 3.5 s | 1.2 vCPU | 1 GB |
+| Long (2000+ words) | 7.8 s | 2.0 vCPU | 2 GB |
+
+**Optimizations implemented**
+- Parallel metric computation (thread/process pools)
+- Conditional execution & early exit on high confidence
+- Model caching & quantization support for memory efficiency
+
+---
+
+## 📁 Project Structure (as in repository)
+
+```text
+text_auth/
+├── config/
+│   ├── model_config.py
+│   ├── settings.py
+│   └── threshold_config.py
+├── data/
+│   ├── reports/
+│   └── uploads/
+├── detector/
+│   ├── attribution.py
+│   ├── ensemble.py
+│   ├── highlighter.py
+│   └── orchestrator.py
+├── metrics/
+│   ├── base_metric.py
+│   ├── detect_gpt.py
+│   ├── entropy.py
+│   ├── linguistic.py
+│   ├── perplexity.py
+│   ├── semantic_analysis.py
+│   └── structural.py
+├── models/
+│   ├── model_manager.py
+│   └── model_registry.py
+├── processors/
+│   ├── document_extractor.py
+│   ├── domain_classifier.py
+│   ├── language_detector.py
+│   └── text_processor.py
+├── reporter/
+│   ├── reasoning_generator.py
+│   └── report_generator.py
+├── ui/
+│   └── static/index.html
+├── utils/
+│   └── logger.py
+├── example.py
+├── requirements.txt
+├── run.sh
+└── text_auth_app.py
+```
+
+---
+
+## 🌐 API Endpoints 
+
+### `/api/analyze` — Text Analysis (POST)
+Analyze raw text. Returns ensemble result, per‑metric scores, attribution, highlights, and 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 } }
+  },
+  "attribution":{ "predicted_model":"gpt-4", "confidence":0.76 },
+  "highlighted_html":"<div>...</div>",
+  "reasoning":{ "summary":"...", "key_indicators":[ "...", "..."] }
+}
+```
+
+### `/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.
+
+### `/api/report/generate` — Report Generation (POST)
+Generate downloadable JSON or PDF reports for a given analysis id.
+
+### Utility endpoints
+- `GET /health` — health status, models loaded, uptime
+- `GET /api/domains` — supported domains and thresholds
+- `GET /api/models` — detectable model list
+
+---
+
+## ⚙️ Installation & Setup
+
+### Prerequisites
+- Python 3.8+
+- 4GB RAM (8GB recommended)
+- Disk: 2GB (models & deps)
+- OS: Linux/macOS/Windows (WSL supported)
+
+### Quickstart
+```bash
+git clone https://github.com/satyaki-mitra/text_authentication.git
+cd text_authentication
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+# Copy .env.example -> .env and set HF_TOKEN if using private models
+python text_auth_app.py
+# or: ./run.sh
+```
+
+**Dev tips**
+- Use `DEBUG=True` in `config/settings.py` for verbose logs
+- For containerized runs, see `Dockerfile` template (example included in repo suggestions)
+
+---
+
+## 🧠 Model Management & First‑Run Behavior
+
+- The application **automatically downloads** required model weights from Hugging Face on the first run and caches them to the local HF cache (or a custom path specified in `config/model_config.py`).
+- Model IDs and revisions are maintained in `models/model_registry.py` and referenced by `models/model_manager.py`.
+- **Best practices implemented**:
+  - Pin model revisions (e.g., `repo_id@v1.2.0`)
+  - Resumeable downloads using `huggingface_hub.snapshot_download`
+  - Optional `OFFLINE_MODE` to load local model paths
+  - Optional integrity checks (SHA256) after download
+  - Support for private HF repos using `HF_TOKEN` env var
+
+**Example snippet**
+```python
+from huggingface_hub import snapshot_download
+snapshot_download(repo_id="satyaki-mitra/text-detector-v1", local_dir="./models/text-detector-v1")
+```
+
+---
+
+## 🎨 Frontend Features (UI)
+
+- Dual‑panel responsive web UI (left: input / upload; right: live analysis)
+- Sentence‑level color highlights with tooltips and per‑metric breakdown
+- Progressive analysis updates (metric-level streaming)
+- Theme: light/dark toggle (UI respects user preference)
+- Export: JSON and PDF report download
+- Interactive elements: click to expand sentence reasoning, copy text snippets, download raw metrics
+
+---
+
+## 💼 Business Model & Market Analysis
+
+**TAM**: $20B (education, hiring, publishing) — see detailed breakdown in original repo.
+**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.
+
+**Monetization ideas**
+- SaaS subscription (seat / monthly analyze limits)
+- Enterprise licensing with on‑prem deployment & priority support
+- API billing (per‑analysis tiered pricing)
+- Onboarding & consulting for institutions
+
+---
+
+## 🔮 Research Impact & Future Scope
+
+**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).*
+
+---
+
+## 🏗️ Infrastructure & Deployment
+
+### Deployment (Mermaid dark diagram)
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart LR
+    CDN[CloudFront / CDN] --> LB["Load Balancer (ALB/NLB)"]
+    LB --> API1[API Server 1]
+    LB --> API2[API Server 2]
+    LB --> APIN[API Server N]
+    API1 --> Cache[Redis Cache]
+    API1 --> DB[PostgreSQL]
+    API1 --> S3["S3 / Model Storage"]
+    DB --> Backup["RDS Snapshot"]
+    S3 --> Archive["Cold Storage"]
+```
+
+**Deployment notes**
+- Containerize app with Docker, orchestrate with Kubernetes or ECS for scale
+- Autoscaling groups for API servers & worker nodes
+- Use spot GPU instances for retraining & large metric compute jobs
+- Integrate observability: Prometheus + Grafana, Sentry for errors, Datadog if available
+
+---
+
+## 🔐 Security & Risk Mitigation
+
+**Primary risks & mitigations**
+- Model performance drift — monitoring + retraining + rollback
+- Adversarial attacks — adversarial training & input sanitization
+- Data privacy — avoid storing raw uploads unless user consents; redact PII in reports
+- Secrets management — use env vars, vaults, and avoid committing tokens
+- Rate limits & auth — JWT/OAuth2, API key rotation, request throttling
+
+**File handling best practices (examples)**
+```python
+ALLOWED_EXT = {'.txt','.pdf','.docx','.doc','.md'}
+def allowed_file(filename):
+    return any(filename.lower().endswith(ext) for ext in ALLOWED_EXT)
+```
+
+---
+
+## Continuous Improvement Pipeline (TODO)
+- Regular retraining & calibration on new model releases
+- Feedback loop: user reported FP integrated into training
+- A/B testing for weight adjustments
+- Monthly accuracy audits & quarterly model updates
+
+---
+
+## 📄 License & Acknowledgments
+
+This project is licensed under the **MIT License** — see [LICENSE](LICENSE) in the repo.
+
+Acknowledgments:
+- DetectGPT (Mitchell et al., 2023) — inspiration for perturbation-based detection
+- Hugging Face Transformers & Hub
+- Open-source NLP community and early beta testers
+
+---
+
+<div align="center">
+
+**Built with ❤️ — AI transparency, accountability, and real‑world readiness.**
+
+*Version 1.0.0 — Last Updated: October, 2025*
+
+</div>

config/__init__.py

@@ -0,0 +1,35 @@
+# 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/model_config.py

@@ -0,0 +1,279 @@
+# 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
+
+
+
+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"  
+
+
+@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",
+                                                                                      size_mb           = 548,
+                                                                                      required          = True,
+                                                                                      download_priority = 1,
+                                                                                      max_length        = 1024,
+                                                                                      batch_size        = 8,
+                                                                                      quantizable       = True,
+                                                                                     ), 
+                                           "semantic_primary"           : ModelConfig(model_id          = "sentence-transformers/all-MiniLM-L6-v2",
+                                                                                      model_type        = ModelType.SENTENCE_TRANSFORMER,
+                                                                                      description       = "Lightweight semantic embeddings (80MB)",
+                                                                                      size_mb           = 80,
+                                                                                      required          = True,
+                                                                                      download_priority = 1,
+                                                                                      max_length        = 256,
+                                                                                      batch_size        = 32,
+                                                                                     ),
+                                           "semantic_secondary"         : ModelConfig(model_id          = "sentence-transformers/all-mpnet-base-v2",
+                                                                                      model_type        = ModelType.SENTENCE_TRANSFORMER,
+                                                                                      description       = "Higher quality semantic embeddings (backup)",
+                                                                                      size_mb           = 420,
+                                                                                      required          = False,
+                                                                                      download_priority = 3,
+                                                                                      max_length        = 384,
+                                                                                      batch_size        = 16,
+                                                                                     ),
+                                           "linguistic_spacy"           : ModelConfig(model_id          = "en_core_web_sm",
+                                                                                      model_type        = ModelType.RULE_BASED,
+                                                                                      description       = "spaCy small English model for POS tagging",
+                                                                                      size_mb           = 13,
+                                                                                      required          = True,
+                                                                                      download_priority = 1,
+                                                                                      batch_size        = 16,
+                                                                                      additional_params = {"is_spacy_model": True},
+                                                                                     ),
+                                           "domain_classifier"          : ModelConfig(model_id          = "cross-encoder/nli-roberta-base",
+                                                                                      model_type        = ModelType.CLASSIFIER,
+                                                                                      description       = "High-accuracy zero-shot classifier (RoBERTa-base)",
+                                                                                      size_mb           = 500,
+                                                                                      required          = True,  
+                                                                                      download_priority = 1,     
+                                                                                      max_length        = 512,
+                                                                                      batch_size        = 8,
+                                                                                      quantizable       = True,
+                                                                                     ),
+                                           "domain_classifier_fallback" : ModelConfig(model_id          = "microsoft/deberta-v3-small",
+                                                                                      model_type        = ModelType.CLASSIFIER,
+                                                                                      description       = "Fast fallback zero-shot classifier (DeBERTa-small)",
+                                                                                      size_mb           = 240,
+                                                                                      required          = True,
+                                                                                      download_priority = 2,
+                                                                                      max_length        = 512,
+                                                                                      batch_size        = 16,
+                                                                                      quantizable       = True,
+                                                                                     ),
+                                           "detectgpt_base"             : ModelConfig(model_id          = "gpt2",
+                                                                                      model_type        = ModelType.GPTMASK,
+                                                                                      description       = "DetectGPT perturbation model (reuses gpt2)",
+                                                                                      size_mb           = 0,  
+                                                                                      required          = True,  
+                                                                                      download_priority = 4,
+                                                                                      max_length        = 1024,
+                                                                                      batch_size        = 4,
+                                                                                     ),
+                                           "detectgpt_mask"             : ModelConfig(model_id          = "distilroberta-base",
+                                                                                      model_type        = ModelType.TRANSFORMER,
+                                                                                      description       = "Masked LM for text perturbation",
+                                                                                      size_mb           = 330,
+                                                                                      required          = True, 
+                                                                                      download_priority = 4,
+                                                                                      max_length        = 512,
+                                                                                      batch_size        = 8,
+                                                                                     ),
+                                           "language_detector"          : ModelConfig(model_id          = "papluca/xlm-roberta-base-language-detection",
+                                                                                      model_type        = ModelType.CLASSIFIER,
+                                                                                      description       = "Language detection (skip if English-only)",
+                                                                                      size_mb           = 1100,
+                                                                                      required          = False,
+                                                                                      download_priority = 5,
+                                                                                      max_length        = 512,
+                                                                                      batch_size        = 16,
+                                                                                     ),
+                                          }
+
+
+# MODEL GROUPS FOR BATCH DOWNLOADING 
+MODEL_GROUPS                            = {"minimal"   : ["perplexity_gpt2", "domain_classifier"],
+                                           "essential" : ["perplexity_gpt2", "semantic_primary", "linguistic_spacy", "domain_classifier"],
+                                           "extended"  : ["semantic_secondary", "detectgpt_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
+                                           "linguistic"          : 0.15,  # spacy
+                                           "detect_gpt"          : 0.10,  # gpt2 + distilroberta (optional)
+                                          }
+
+
+# HELPER FUNCTIONS
+def get_model_config(model_name: str) -> Optional[ModelConfig]:
+    """
+    Get configuration for a specific model
+    """
+    return MODEL_REGISTRY.get(model_name)
+
+
+def get_required_models() -> Dict[str, ModelConfig]:
+    """
+    Get all required models
+    """
+    return {name: config for name, config in MODEL_REGISTRY.items() if config.required}
+
+
+def get_models_by_priority(priority: int) -> Dict[str, ModelConfig]:
+    """
+    Get models by download priority
+    """
+    return {name: config for name, config in MODEL_REGISTRY.items() if config.download_priority == priority}
+
+
+def get_models_by_group(group_name: str) -> Dict[str, ModelConfig]:
+    """
+    Get models belonging to a specific group
+    """
+    if group_name not in MODEL_GROUPS:
+        return {}
+    
+    model_names = MODEL_GROUPS[group_name]
+    return {name: MODEL_REGISTRY[name] for name in model_names if name in MODEL_REGISTRY}
+
+
+def get_total_size_mb(group_name: Optional[str] = None) -> int:
+    """
+    Calculate total size of models
+    
+    Arguments:
+    ----------
+        group_name : If specified, only count models in that group
+    
+    Returns:
+    --------
+        Total size in MB
+    """
+    if group_name:
+        models = get_models_by_group(group_name)
+    
+    else:
+        models = MODEL_REGISTRY
+    
+    return sum(config.size_mb for config in models.values())
+
+
+def get_required_size_mb() -> int:
+    """
+    Calculate total size of required models only
+    """
+    return sum(config.size_mb for config in MODEL_REGISTRY.values() if config.required)
+
+
+def print_model_summary():
+    """
+    Print a summary of models and their sizes
+    """
+    print("\n" + "="*70)
+    print("MODEL REGISTRY SUMMARY")
+    print("="*70)
+    
+    for group_name, model_names in MODEL_GROUPS.items():
+        group_size = get_total_size_mb(group_name)
+        print(f"\n[{group_name.upper()}] - Total: {group_size} MB")
+        print("-" * 70)
+        
+        for model_name in model_names:
+            if model_name in MODEL_REGISTRY:
+                config = MODEL_REGISTRY[model_name]
+                req_str = "✓ REQUIRED" if config.required else "  optional"
+                print(f"  {req_str} | {model_name:30s} | {config.size_mb:5d} MB | {config.model_id}")
+    
+    print("\n" + "="*70)
+    print(f"TOTAL REQUIRED MODELS: {get_required_size_mb()} MB")
+    print(f"TOTAL ALL MODELS: {get_total_size_mb()} MB")
+    print("="*70 + "\n")
+
+
+# SPACY MODEL INSTALLATION
+
+def get_spacy_download_commands() -> list:
+    """
+    Get commands to download spaCy models
+    """
+    spacy_models = [config for config in MODEL_REGISTRY.values() if config.additional_params.get("is_spacy_model", False)]
+    
+    commands     = list()
+
+    for config in spacy_models:
+        commands.append(f"python -m spacy download {config.model_id}")
+    
+    return commands
+
+
+# Export
+__all__ = ["ModelType",
+           "ModelConfig",
+           "MODEL_GROUPS",
+           "MODEL_REGISTRY",
+           "get_model_config",
+           "get_total_size_mb",
+           "get_required_models",
+           "get_models_by_group",
+           "print_model_summary",
+           "get_required_size_mb",
+           "DEFAULT_MODEL_WEIGHTS",
+            "get_models_by_priority",
+           "get_spacy_download_commands",
+          ]
+
+
+# AUTO-RUN SUMMARY 
+if __name__ == "__main__":
+
+    print_model_summary()
+    
+    print("\nSPACY MODEL INSTALLATION:")
+
+    print("-" * 70)
+    for cmd in get_spacy_download_commands():
+        print(f"  {cmd}")
+
+    print()

config/settings.py

@@ -0,0 +1,141 @@
+# DEPENDENCIES
+import os
+import torch
+from pathlib import Path
+from pydantic import Field
+from typing import Optional
+from pydantic_settings import BaseSettings
+
+
+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"
+    
+    # Environment
+    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")
+    
+    # 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")
+    
+    # File Upload Settings
+    MAX_UPLOAD_SIZE         : int           = 10 * 1024 * 1024  # 10MB
+    ALLOWED_EXTENSIONS      : list          = [".txt", ".pdf", ".docx", ".doc"]
+    
+    # Processing Settings
+    MAX_TEXT_LENGTH         : int           = 50000  # 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
+    
+    # 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
+    
+    # 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
+    
+    # Rate Limiting
+    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"
+    
+    # API Settings
+    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")
+    
+    # Security
+    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
+     
+    # Performance
+    MAX_CONCURRENT_REQUESTS : int           = 10
+    REQUEST_TIMEOUT         : int           = 300  # seconds (5 minutes)
+    
+    # Metrics Configuration
+    METRICS_ENABLED         : dict          = {"semantic_analysis"   : True,
+                                               "detect_gpt"          : True,
+                                               "perplexity"          : True,
+                                               "statistical"         : True,
+                                               "entropy"             : True,
+                                               "linguistic"          : True,
+                                              }
+    
+    class Config:
+        env_file       = ".env"
+        case_sensitive = True
+        extra          = "ignore"
+
+    
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._create_directories()
+    
+
+    def _create_directories(self):
+        """
+        Create necessary directories if they don't exist
+        """
+        for directory in [self.MODEL_CACHE_DIR, self.LOG_DIR, self.UPLOAD_DIR, self.REPORT_DIR]:
+            directory.mkdir(parents = True, exist_ok = True)
+    
+
+    @property
+    def is_production(self) -> bool:
+        """
+        Check if running in production
+        """
+        return self.ENVIRONMENT.lower() == "production"
+    
+
+    @property
+    def use_gpu(self) -> bool:
+        """
+        Check if GPU is available and should be used
+        """
+        return self.DEVICE == "cuda" and torch.cuda.is_available()
+
+
+
+# Singleton instance
+settings = Settings()
+
+
+# Export for easy import
+__all__  = ["settings", 
+            "Settings",
+           ]

config/threshold_config.py

@@ -0,0 +1,379 @@
+# 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
+    detect_gpt         : MetricThresholds
+    ensemble_threshold : float = 0.5
+
+
+# ==================== 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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.60, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.65, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.58, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.64, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.63, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.65, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.64, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.64, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.62, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.66, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.65, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.62, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.61, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.60, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.59, human_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),
+                                            detect_gpt         = MetricThresholds(ai_threshold = 0.62, human_threshold = 0.38, weight = 0.08),
+                                            ensemble_threshold = 0.40,
+                                           )
+
+
+# THRESHOLD REGISTRY
+THRESHOLD_REGISTRY: Dict[Domain, DomainThresholds]            = {Domain.GENERAL       : DEFAULT_THRESHOLDS,
+                                                                 Domain.ACADEMIC      : ACADEMIC_THRESHOLDS,
+                                                                 Domain.CREATIVE      : CREATIVE_THRESHOLDS,
+                                                                 Domain.AI_ML         : AI_ML_THRESHOLDS,
+                                                                 Domain.SOFTWARE_DEV  : SOFTWARE_DEV_THRESHOLDS,
+                                                                 Domain.TECHNICAL_DOC : TECHNICAL_DOC_THRESHOLDS,
+                                                                 Domain.ENGINEERING   : ENGINEERING_THRESHOLDS,
+                                                                 Domain.SCIENCE       : SCIENCE_THRESHOLDS,
+                                                                 Domain.BUSINESS      : BUSINESS_THRESHOLDS,
+                                                                 Domain.LEGAL         : LEGAL_THRESHOLDS,
+                                                                 Domain.MEDICAL       : MEDICAL_THRESHOLDS,
+                                                                 Domain.JOURNALISM    : JOURNALISM_THRESHOLDS,
+                                                                 Domain.MARKETING     : MARKETING_THRESHOLDS,
+                                                                 Domain.SOCIAL_MEDIA  : SOCIAL_MEDIA_THRESHOLDS,
+                                                                 Domain.BLOG_PERSONAL : BLOG_PERSONAL_THRESHOLDS,
+                                                                 Domain.TUTORIAL      : TUTORIAL_THRESHOLDS,
+                                                                }
+
+
+# CONFIDENCE LEVEL RANGES
+CONFIDENCE_RANGES: Dict[ConfidenceLevel, Tuple[float, float]] = {ConfidenceLevel.VERY_LOW  : (0.0, 0.3),
+                                                                 ConfidenceLevel.LOW       : (0.3, 0.5),
+                                                                 ConfidenceLevel.MEDIUM    : (0.5, 0.7),
+                                                                 ConfidenceLevel.HIGH      : (0.7, 0.85),
+                                                                 ConfidenceLevel.VERY_HIGH : (0.85, 1.0),
+                                                                }
+
+
+# HELPER FUNCTIONS 
+def get_threshold_for_domain(domain: Domain) -> DomainThresholds:
+    """
+    Get thresholds for a specific domain
+    """
+    return THRESHOLD_REGISTRY.get(domain, DEFAULT_THRESHOLDS)
+
+
+def get_confidence_level(score: float) -> ConfidenceLevel:
+    """
+    Determine confidence level based on score
+    """
+    for level, (min_val, max_val) in CONFIDENCE_RANGES.items():
+        if (min_val <= score < max_val):
+            return level
+
+    return ConfidenceLevel.VERY_HIGH
+
+
+def adjust_threshold_by_confidence(threshold: float, confidence: float, conservative: bool = True) -> float:
+    """
+    Adjust threshold based on confidence level
+    """
+    if conservative:
+        adjustment         = (1 - confidence) * 0.1
+        adjusted_threshold = threshold + adjustment
+        
+        return adjusted_threshold
+
+    else:
+        adjustment         = confidence * 0.05
+        adjusted_threshold = threshold - adjustment
+        
+        return adjusted_threshold
+
+
+def interpolate_thresholds(domain1: Domain, domain2: Domain, weight1: float = 0.5) -> DomainThresholds:
+    """
+    Interpolate between two domain thresholds
+    """
+    thresh1 = get_threshold_for_domain(domain = domain1)
+    thresh2 = get_threshold_for_domain(domain = domain2)
+    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 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),
+                            linguistic          = interpolate_metric(thresh1.linguistic, thresh2.linguistic),
+                            detect_gpt          = interpolate_metric(thresh1.detect_gpt, thresh2.detect_gpt),
+                            ensemble_threshold  = thresh1.ensemble_threshold * weight1 + thresh2.ensemble_threshold * weight2,
+                           )
+
+
+def get_active_metric_weights(domain: Domain, enabled_metrics: Dict[str, bool]) -> Dict[str, float]:
+    """
+    Get weights for enabled metrics, normalized to sum to 1.0
+    """
+    thresholds     = get_threshold_for_domain(domain = domain)
+    
+    metric_mapping = {"structural"        : thresholds.structural,
+                      "perplexity"        : thresholds.perplexity,
+                      "entropy"           : thresholds.entropy,
+                      "semantic_analysis" : thresholds.semantic_analysis,
+                      "linguistic"        : thresholds.linguistic,
+                      "detect_gpt"        : thresholds.detect_gpt,
+                     }
+    
+    active_weights = dict()
+
+    for metric_name, threshold_obj in metric_mapping.items():
+        if enabled_metrics.get(metric_name, False):
+            active_weights[metric_name] = threshold_obj.weight
+    
+    # Normalize
+    total_weight = sum(active_weights.values())
+
+    if (total_weight > 0):
+        active_weights = {name: weight / total_weight for name, weight in active_weights.items()}
+    
+    return active_weights
+
+
+
+# Export
+__all__ = ["Domain",
+           "ConfidenceLevel",
+           "MetricThresholds",
+           "DomainThresholds",
+           "CONFIDENCE_RANGES",
+           "DEFAULT_THRESHOLDS",
+           "THRESHOLD_REGISTRY",
+           "get_confidence_level",
+           "interpolate_thresholds",  
+           "get_threshold_for_domain",           
+           "get_active_metric_weights",
+           "adjust_threshold_by_confidence",
+          ]

detector/__init__.py

@@ -0,0 +1,20 @@
+# 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

@@ -0,0 +1,964 @@
+# 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
+    """
+    # DOCUMENT-ALIGNED: Metric weights from technical specification
+    METRIC_WEIGHTS           = {"perplexity"       : 0.25,  
+                                "structural"       : 0.15,   
+                                "semantic_analysis": 0.15,  
+                                "entropy"          : 0.20,  
+                                "linguistic"       : 0.15,  
+                                "detect_gpt"       : 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],
+                               }
+
+    # Enhanced 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, domain)
+            
+            # Statistical pattern analysis
+            statistical_scores                    = self._analyze_statistical_patterns(text, domain)
+            
+            # Metric-based attribution using all 6 metrics
+            metric_scores                         = self._analyze_metric_patterns(metric_results, 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 - FIXED: 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 - FIXED 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, "detect_gpt": 1.0},
+                                 Domain.ACADEMIC      : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.3, "detect_gpt": 0.8},
+                                 Domain.TECHNICAL_DOC : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.1, "detect_gpt": 0.8},
+                                 Domain.AI_ML         : {"perplexity": 1.3, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.2, "detect_gpt": 0.8},
+                                 Domain.SOFTWARE_DEV  : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.0, "detect_gpt": 0.9},
+                                 Domain.ENGINEERING   : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.1, "linguistic": 1.2, "detect_gpt": 0.8},
+                                 Domain.SCIENCE       : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.3, "detect_gpt": 0.8},
+                                 Domain.BUSINESS      : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.2, "linguistic": 1.1, "detect_gpt": 0.9},
+                                 Domain.LEGAL         : {"perplexity": 1.2, "structural": 1.1, "entropy": 0.9, "semantic_analysis": 1.3, "linguistic": 1.3, "detect_gpt": 0.8},
+                                 Domain.MEDICAL       : {"perplexity": 1.2, "structural": 1.0, "entropy": 0.9, "semantic_analysis": 1.2, "linguistic": 1.2, "detect_gpt": 0.8},
+                                 Domain.JOURNALISM    : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.1, "linguistic": 1.1, "detect_gpt": 0.9},
+                                 Domain.CREATIVE      : {"perplexity": 0.9, "structural": 0.9, "entropy": 1.2, "semantic_analysis": 1.0, "linguistic": 1.3, "detect_gpt": 0.9},
+                                 Domain.MARKETING     : {"perplexity": 1.0, "structural": 1.0, "entropy": 1.1, "semantic_analysis": 1.1, "linguistic": 1.2, "detect_gpt": 0.8},
+                                 Domain.SOCIAL_MEDIA  : {"perplexity": 1.0, "structural": 0.8, "entropy": 1.3, "semantic_analysis": 0.9, "linguistic": 0.9, "detect_gpt": 0.9},
+                                 Domain.BLOG_PERSONAL : {"perplexity": 1.0, "structural": 0.9, "entropy": 1.2, "semantic_analysis": 1.0, "linguistic": 1.1, "detect_gpt": 0.8},
+                                 Domain.TUTORIAL      : {"perplexity": 1.1, "structural": 1.0, "entropy": 1.0, "semantic_analysis": 1.1, "linguistic": 1.1, "detect_gpt": 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
+        
+        # DETECTGPT ANALYSIS (10% weight)
+        if ("detect_gpt" in metric_results):
+            detectgpt_result = metric_results["detect_gpt"]
+            stability        = detectgpt_result.details.get("stability_score", 0.5)
+            curvature        = detectgpt_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["detect_gpt"]
+                scores[AIModel.LLAMA_3] += 0.3 * self.METRIC_WEIGHTS["detect_gpt"]
+        
+        # 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 - FIXED
+        """
+        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]
+        
+        # FIXED: Only return UNKNOWN if the best score is very low
+        # Use a more reasonable threshold for attribution
+        if best_score < 0.08:  # Changed from 0.15 to 0.08 to be less restrictive
+            return AIModel.UNKNOWN, best_score
+        
+        # FIXED: Don't override with domain preferences if there's a clear winner
+        # Only consider domain preferences if scores are very close
+        if len(sorted_models) > 1:
+            second_model_name, second_score = sorted_models[1]
+            score_difference = best_score - second_score
+            
+            # If scores are very close (within 3%) and second is domain-preferred, consider it
+            if score_difference < 0.03:
+                try:
+                    best_model = AIModel(best_model_name)
+                    second_model = AIModel(second_model_name)
+                    
+                    # If second model is domain-preferred and first is not, prefer second
+                    if (second_model in domain_preferences and 
+                        best_model not in domain_preferences):
+                        best_model_name = second_model_name
+                        best_score = second_score
+                except ValueError:
+                    pass
+        
+        try:
+            best_model = AIModel(best_model_name)
+        except ValueError:
+            best_model = AIModel.UNKNOWN
+        
+        # Calculate confidence based on score dominance
+        if len(sorted_models) > 1:
+            second_score = sorted_models[1][1]
+            margin = best_score - second_score
+            # Confidence based on both absolute score and margin
+            confidence = min(1.0, best_score * 0.6 + margin * 2.0)
+        else:
+            confidence = best_score * 0.7
+        
+        # FIXED: Don't downgrade to UNKNOWN based on confidence alone
+        # If we have a model with reasonable probability, show it even with low confidence
+        return best_model, 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 - FIXED to show proper ordering
+        """
+        reasoning = list()
+        
+        reasoning.append("## AI Model Attribution Analysis")
+        reasoning.append(f"**Domain**: {domain.value.replace('_', ' ').title()}")
+        
+        if (predicted_model == AIModel.UNKNOWN):
+            reasoning.append("**Most Likely**: UNKNOWN")
+            # Show the actual highest probability even if it's UNKNOWN
+            if combined_scores:
+                sorted_models = sorted(combined_scores.items(), key=lambda x: x[1], reverse=True)
+                if sorted_models and sorted_models[0][1] > 0:
+                    top_model_name = sorted_models[0][0].replace("-", " ").replace("_", " ").title()
+                    top_score = sorted_models[0][1] * 100
+                    reasoning.append(f"**{top_model_name}**")
+                    reasoning.append(f"{top_score:.1f}%")
+        else:
+            model_name = predicted_model.value.replace("-", " ").replace("_", " ").title()
+            reasoning.append(f"**Most Likely**: {model_name}")
+            # Show the actual probability for the predicted model
+            model_key = predicted_model.value
+            if model_key in combined_scores:
+                score = combined_scores[model_key] * 100
+                reasoning.append(f"{score:.1f}%")
+        
+        # Show top model candidates with ACTUAL percentages in proper order
+        reasoning.append("")
+        if combined_scores:
+            sorted_models = sorted(combined_scores.items(), key=lambda x: x[1], reverse=True)
+            
+            for model_name, score in sorted_models[:6]:  # Show top 6 models
+                if score < 0.01:  # Skip very low probability models
+                    continue
+                    
+                display_name = model_name.replace("-", " ").replace("_", " ").title()
+                # Multiply by 100 to show as percentage (score is already 0-1)
+                percentage = score * 100
+                
+                # Use proper markdown formatting for the list
+                reasoning.append(f"**{display_name}**")
+                reasoning.append(f"{percentage:.1f}%")
+                reasoning.append("")
+        
+        # Domain-specific insights
+        reasoning.append("## AI Model Attribution Analysis")
+        reasoning.append(f"Analysis calibrated for {domain.value.replace('_', ' ')} content")
+        
+        if (domain in [Domain.ACADEMIC, Domain.TECHNICAL_DOC, Domain.AI_ML, Domain.SOFTWARE_DEV, Domain.ENGINEERING, Domain.SCIENCE]):
+            reasoning.append("Higher weight given to coherence and structural patterns")
+        
+        elif (domain in [Domain.CREATIVE, Domain.MARKETING, Domain.SOCIAL_MEDIA, Domain.BLOG_PERSONAL]):
+            reasoning.append("Higher weight given to linguistic diversity and stylistic patterns")
+        
+        elif (domain in [Domain.LEGAL, Domain.MEDICAL]):
+            reasoning.append("Emphasis on formal language patterns and technical terminology")
+        
+        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/ensemble.py

@@ -0,0 +1,801 @@
+# 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.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
+    
+    Features:
+    - Domain-aware dynamic weighting
+    - Confidence-calibrated aggregation
+    - 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):
+        """
+        Initialize advanced ensemble classifier
+        
+        Arguments:
+        ----------
+            primary_method      : Primary aggregation method : "confidence_calibrated", "domain_adaptive", "consensus_based", "ml_ensemble"
+            
+            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
+        """
+        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
+        
+        logger.info(f"AdvancedEnsembleClassifier initialized (primary={primary_method}, fallback={fallback_method}, ml_ensemble={use_ml_ensemble})")
+    
+
+    def predict(self, metric_results: Dict[str, MetricResult], domain: Domain = Domain.GENERAL) -> EnsembleResult:
+        """
+        Combine metric results using advanced ensemble methods
+        
+        Arguments:
+        ----------
+            metric_results { dict }  : Dictionary mapping metric names to MetricResult objects
+
+            domain        { Domain } : Text domain for adaptive thresholding
+            
+        Returns:
+        --------
+            { EnsembleResult }        : EnsembleResult object with final prediction
+        """
+        try:
+            # Filter and validate metrics
+            valid_results, validation_info = self._validate_metrics(metric_results)
+            
+            if (len(valid_results) < self.min_metrics_required):
+                logger.warning(f"Insufficient valid metrics: {len(valid_results)}/{self.min_metrics_required}")
+                return self._create_fallback_result(domain, metric_results, "insufficient_metrics")
+            
+            # Get domain-specific base weights
+            enabled_metrics = {name: True for name in valid_results.keys()}
+            base_weights    = get_active_metric_weights(domain, enabled_metrics)
+            
+            # Try primary aggregation method
+            try:
+                if (self.primary_method == "confidence_calibrated"):
+                    aggregated, weights = self._confidence_calibrated_aggregation(results      = valid_results, 
+                                                                                  base_weights = base_weights,
+                                                                                  domain       = domain,
+                                                                                 )
+                
+                elif (self.primary_method == "domain_adaptive"):
+                    aggregated, weights = self._domain_adaptive_aggregation(results      = valid_results, 
+                                                                            base_weights = base_weights, 
+                                                                            domain       = domain,
+                                                                           )
+                
+                elif (self.primary_method == "consensus_based"):
+                    aggregated, weights = self._consensus_based_aggregation(results      = valid_results, 
+                                                                            base_weights = base_weights,
+                                                                           )
+                
+                elif ((self.primary_method == "ml_ensemble") and self.use_ml_ensemble):
+                    aggregated, weights = self._ml_ensemble_aggregation(results      = valid_results, 
+                                                                        base_weights = base_weights,
+                                                                       )
+                
+                else:
+                    # Fallback to domain weighted
+                    aggregated, weights = self._domain_weighted_aggregation(results      = valid_results, 
+                                                                            base_weights = base_weights,
+                                                                           )
+            
+            except Exception as e:
+                logger.warning(f"Primary aggregation failed: {e}, using fallback")
+                aggregated, weights = self._apply_fallback_aggregation(results      = valid_results, 
+                                                                       base_weights = base_weights,
+                                                                      )
+            
+            # Calculate advanced metrics
+            overall_confidence = self._calculate_advanced_confidence(results    = valid_results, 
+                                                                     weights    = weights, 
+                                                                     aggregated = aggregated,
+                                                                    )
+
+            uncertainty_score  = self._calculate_uncertainty(results    = valid_results, 
+                                                             weights    = weights, 
+                                                             aggregated = aggregated,
+                                                            )
+
+            consensus_level    = self._calculate_consensus_level(results = valid_results)
+            
+            # Apply domain-specific threshold with uncertainty consideration
+            domain_thresholds  = get_threshold_for_domain(domain = domain)
+            final_verdict      = self._apply_adaptive_threshold(aggregated     = aggregated, 
+                                                                base_threshold = domain_thresholds.ensemble_threshold,
+                                                                uncertainty    = uncertainty_score,
+                                                               )
+            
+            # Generate detailed reasoning
+            reasoning          = self._generate_detailed_reasoning(results     = valid_results, 
+                                                                   weights     = weights, 
+                                                                   aggregated  = aggregated, 
+                                                                   verdict     = final_verdict, 
+                                                                   uncertainty = uncertainty_score, 
+                                                                   consensus   = consensus_level,
+                                                                  )
+            
+            # Calculate weighted scores
+            weighted_scores    = {name: result.ai_probability * 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     = weights,
+                                  weighted_scores    = weighted_scores,
+                                  reasoning          = reasoning,
+                                  uncertainty_score  = uncertainty_score,
+                                  consensus_level    = consensus_level,
+                                 )
+            
+        except Exception as e:
+            logger.error(f"Error in advanced ensemble prediction: {e}")
+            return self._create_fallback_result(domain, metric_results, str(e))
+    
+
+    def _validate_metrics(self, results: Dict[str, MetricResult]) -> tuple:
+        """
+        Validate metrics and return quality information
+        """
+        valid_results   = dict()
+        validation_info = {'failed_metrics'          : [],
+                           'low_confidence_metrics'  : [],
+                           'high_confidence_metrics' : [],
+                          }
+        
+        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
+        
+        return valid_results, validation_info
+    
+
+    def _confidence_calibrated_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float], domain: Domain) -> tuple:
+        """
+        Confidence-calibrated aggregation with domain adaptation
+        """
+        # Calculate confidence-adjusted weights
+        confidence_weights = dict()
+
+        for name, result in results.items():
+            base_weight              = base_weights.get(name, 0.0)
+            # Confidence-based adjustment with non-linear scaling
+            confidence_factor        = self._sigmoid_confidence_adjustment(confidence = result.confidence)
+            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()}
+        
+        # Domain-specific calibration
+        domain_calibration = self._get_domain_calibration(domain = domain)
+        calibrated_results = self._calibrate_probabilities(results     = results, 
+                                                           calibration = domain_calibration,
+                                                          )
+        
+        # Weighted aggregation
+        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)
+        
+        aggregations      = self._weighted_aggregation(results = results, 
+                                                       weights = consensus_weights,
+                                                      )
+        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)
+        """
+        return self._weighted_aggregation(results, base_weights), base_weights
+    
+
+    def _apply_fallback_aggregation(self, results: Dict[str, MetricResult], base_weights: Dict[str, float]) -> tuple:
+        """
+        Apply fallback aggregation method
+        """
+        if (self.fallback_method == "confidence_weighted"):
+            return self._confidence_weighted_aggregation(results), base_weights
+        
+        elif (self.fallback_method == "simple_average"):
+            return self._simple_average_aggregation(results), base_weights
+
+        else:
+            return self._domain_weighted_aggregation(results, 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
+        
+        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)
+                
+                total_weight += weight
+        
+        if (total_weight == 0):
+            return {"ai_probability"    : 0.5, 
+                    "human_probability" : 0.5, 
+                    "mixed_probability" : 0.0,
+                   }
+        
+        # Calculate weighted averages
+        ai_prob    = sum(ai_scores) / total_weight
+        human_prob = sum(human_scores) / total_weight
+        mixed_prob = sum(mixed_scores) / total_weight
+        
+        # Normalize
+        total     = ai_prob + human_prob + mixed_prob
+        
+        if (total > 0):
+            ai_prob    /= total
+            human_prob /= total
+            mixed_prob /= total
+        
+        return {"ai_probability"    : ai_prob, 
+                "human_probability" : human_prob,
+                "mixed_probability" : mixed_prob,
+               }
+    
+
+    def _confidence_weighted_aggregation(self, results: Dict[str, MetricResult]) -> Dict[str, float]:
+        """
+        Confidence-weighted aggregation
+        """
+        return self._weighted_aggregation(results, {name: result.confidence for name, result in results.items()})
+    
+
+    def _simple_average_aggregation(self, results: Dict[str, MetricResult]) -> Dict[str, float]:
+        """
+        Simple average aggregation
+        """
+        return self._weighted_aggregation(results, {name: 1.0 for name in results.keys()})
+    
+
+    def _sigmoid_confidence_adjustment(self, confidence: float) -> float:
+        """
+        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)))
+    
+
+    def _get_domain_calibration(self, domain: Domain) -> Dict[str, float]:
+        """
+        Get domain-specific calibration factors
+        """
+        # This would typically come from validation data
+        # For now, return neutral calibration : FUTURE WQORK
+        return {}
+    
+
+    def _calibrate_probabilities(self, results: Dict[str, MetricResult], calibration: Dict[str, float]) -> Dict[str, MetricResult]:
+        """
+        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
+                                           )
+        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, 
+                               'detect_gpt'        : 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,
+                                                       'detect_gpt'        : 1.0,
+                                                      },
+                               Domain.ACADEMIC      : {'structural'        : 1.2, 
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.3, 
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.CREATIVE      : {'structural'        : 0.9,
+                                                       'perplexity'        : 1.1,
+                                                       'entropy'           : 1.2, 
+                                                       'semantic_analysis' : 1.0,
+                                                       'linguistic'        : 1.1,
+                                                       'detect_gpt'        : 0.9,
+                                                      },
+                               Domain.AI_ML         : {'structural'        : 1.2,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.SOFTWARE_DEV  : {'structural'        : 1.2,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.TECHNICAL_DOC : {'structural'        : 1.3, 
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.2,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.ENGINEERING   : {'structural'        : 1.2,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.SCIENCE       : {'structural'        : 1.2,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.BUSINESS      : {'structural'        : 1.1,
+                                                       'perplexity'        : 1.2,
+                                                       'entropy'           : 1.0,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.1,
+                                                       'detect_gpt'        : 0.9,
+                                                      },
+                               Domain.LEGAL         : {'structural'        : 1.3,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.2,
+                                                       'linguistic'        : 1.3,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.MEDICAL       : {'structural'        : 1.2,
+                                                       'perplexity'        : 1.3,
+                                                       'entropy'           : 0.9,
+                                                       'semantic_analysis' : 1.2,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.JOURNALISM    : {'structural'        : 1.1,
+                                                       'perplexity'        : 1.2,
+                                                       'entropy'           : 1.0,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.1,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.MARKETING     : {'structural'        : 1.0,
+                                                       'perplexity'        : 1.1,
+                                                       'entropy'           : 1.1,
+                                                       'semantic_analysis' : 1.0,
+                                                       'linguistic'        : 1.2,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.SOCIAL_MEDIA  : {'structural'        : 0.8,
+                                                       'perplexity'        : 1.0,
+                                                       'entropy'           : 1.3, 
+                                                       'semantic_analysis' : 0.9,
+                                                       'linguistic'        : 0.7,
+                                                       'detect_gpt'        : 0.9,
+                                                      },
+                               Domain.BLOG_PERSONAL : {'structural'        : 0.9,
+                                                       'perplexity'        : 1.1,
+                                                       'entropy'           : 1.2,
+                                                       'semantic_analysis' : 1.0,
+                                                       'linguistic'        : 1.0,
+                                                       'detect_gpt'        : 0.8,
+                                                      },
+                               Domain.TUTORIAL      : {'structural'        : 1.1,
+                                                       'perplexity'        : 1.2,
+                                                       'entropy'           : 1.0,
+                                                       'semantic_analysis' : 1.1,
+                                                       'linguistic'        : 1.1,
+                                                       'detect_gpt'        : 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()])
+        
+        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)
+            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:
+        """
+        Calculate advanced 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
+        
+        # Certainty factor (how far from 0.5)
+        certainty               = 1.0 - 2.0 * abs(aggregated["ai_probability"] - 0.5)
+        
+        # Metric quality factor
+        high_confidence_metrics = sum(1 for r in results.values() if r.confidence > 0.7)
+        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)
+        
+        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:
+        """
+        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
+        
+        # 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)
+        
+        # Combined uncertainty
+        uncertainty            = (variance_uncertainty * 0.4 + confidence_uncertainty * 0.3 + decision_uncertainty * 0.3)
+        
+        return max(0.0, min(1.0, uncertainty))
+    
+
+    def _calculate_consensus_level(self, results: Dict[str, MetricResult]) -> float:
+        """
+        Calculate consensus level among metrics
+        """
+        if (len(results) < 2):
+            # 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)
+        
+        # Convert to consensus level (1.0 = perfect consensus, 0.0 = no consensus)
+        consensus = 1.0 - min(1.0, std_dev * 2.0)
+        
+        return consensus
+    
+
+    def _apply_adaptive_threshold(self, aggregated: Dict[str, float], base_threshold: float, uncertainty: float) -> str:
+        """
+        Apply adaptive threshold considering uncertainty
+        """
+        ai_prob            = aggregated.get("ai_probability", 0.5)
+        mixed_prob         = aggregated.get("mixed_probability", 0.0)
+        
+        # Adjust threshold based on uncertainty : Higher uncertainty requires more confidence
+        adjusted_threshold = base_threshold + (uncertainty * 0.1) 
+        
+        # Check for mixed content
+        if ((mixed_prob > 0.25) or ((uncertainty > 0.6) and (0.3 < ai_prob < 0.7))):
+            return "Mixed (AI + Human)"
+        
+        # Apply adjusted threshold
+        if (ai_prob >= adjusted_threshold):
+            return "AI-Generated"
+
+        elif (ai_prob <= (1.0 - adjusted_threshold)):
+            return "Human-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]:
+        """
+        Generate detailed reasoning for the prediction
+        """
+        reasoning = list()
+        
+        # Overall assessment
+        ai_prob    = aggregated.get("ai_probability", 0.5)
+        mixed_prob = aggregated.get("mixed_probability", 0.0)
+
+        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"**Uncertainty**: {uncertainty:.1%}")
+        reasoning.append(f"**Consensus**: {consensus:.1%}")
+        
+        # Metric analysis
+        reasoning.append(f"\n## Metric Analysis")
+        
+        sorted_metrics = sorted(results.items(), key=lambda x: weights.get(x[0], 0.0), reverse=True)
+        
+        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 "
+                             f"(Confidence: {result.confidence:.1%}, "
+                             f"Contribution: {contribution})")
+        
+        # Key factors
+        reasoning.append(f"\n## Key Decision Factors")
+        
+        if (uncertainty > 0.7):
+            reasoning.append("⚠ **High uncertainty** - Metrics show significant disagreement")
+        
+        elif (consensus > 0.8):
+            reasoning.append("✓ **Strong consensus** - All metrics agree on classification")
+        
+        top_metric = sorted_metrics[0] if sorted_metrics else None
+        
+        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")
+        
+        return reasoning
+    
+
+    def _get_confidence_label(self, ai_prob: float) -> str:
+        """
+        Get human-readable confidence label
+        """
+        if ((ai_prob > 0.9) or (ai_prob < 0.1)):
+            return "Very High"
+
+        elif ((ai_prob > 0.8) or (ai_prob < 0.2)):
+            return "High"
+
+        elif ((ai_prob > 0.7) or (ai_prob < 0.3)):
+            return "Moderate"
+
+        else:
+            return "Low"
+    
+
+    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,
+                             )
+
+
+# Export
+__all__ = ["EnsembleResult",
+           "EnsembleClassifier",
+          ]

detector/highlighter.py

@@ -0,0 +1,1042 @@
+# DEPENDENCIES
+import re
+from typing import List
+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 processors.text_processor import TextProcessor
+from config.threshold_config import ConfidenceLevel
+from config.threshold_config import MetricThresholds
+from config.threshold_config import get_confidence_level
+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
+    
+    FEATURES:
+    - Sentence-level highlighting with confidence scores
+    - Domain-aware calibration
+    - Ensemble-based probability aggregation
+    - Mixed content detection
+    - Explainable tooltips
+    - Highlighting metrics calculation
+    """
+    # Color thresholds with mixed content support - FIXED RANGES
+    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.01, "very-high-ai", "#fecaca", "Very likely AI-generated"),
+                       ]
+    
+    # Mixed content pattern
+    MIXED_THRESHOLD  = 0.25
+
+    # GPTZero-like 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,
+                       }
+
+
+    def __init__(self, domain: Domain = Domain.GENERAL, ensemble_classifier: Optional[EnsembleClassifier] = None):
+        """
+        Initialize text highlighter with ENSEMBLE INTEGRATION
+        
+        Arguments:
+        ----------
+            domain                    { Domain }       : Text domain for adaptive thresholding
+
+            ensemble_classifier { EnsembleClassifier } : Optional ensemble for sentence-level analysis
+        """
+        self.text_processor     = TextProcessor()
+        self.domain             = domain
+        self.domain_thresholds  = get_threshold_for_domain(domain)
+        self.ensemble           = ensemble_classifier or EnsembleClassifier(primary_method  = "confidence_calibrated",
+                                                                            fallback_method = "domain_weighted",
+                                                                           )
+    
+
+    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]:
+        """
+        Generate sentence-level highlights with ensemble integration
+        
+        Arguments:
+        ----------
+            text                    { str }       : Original text
+            
+            metric_results          { dict }      : Results from all 6 metrics
+            
+            ensemble_result    { EnsembleResult } : Optional document-level ensemble result
+            
+            enabled_metrics         { dict }      : Dict of metric_name -> is_enabled
+            
+            use_sentence_level      { bool }      : Whether to compute sentence-level probabilities
+            
+        Returns:
+        --------
+                         { list }                 : List of HighlightedSentence objects
+        """
+        # Get domain-appropriate weights for enabled metrics
+        if enabled_metrics is None:
+            enabled_metrics = {name: True for name in metric_results.keys()}
+        
+        weights   = get_active_metric_weights(self.domain, enabled_metrics)
+        
+        # Split text into sentences
+        sentences = self._split_sentences(text)
+        
+        if not sentences:
+            return []
+        
+        # Calculate probabilities for each sentence using ENSEMBLE METHODS
+        highlighted_sentences = list()
+        
+        for idx, sentence in enumerate(sentences):
+            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,
+                                                                                                                      )
+            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,
+                                                                                                                )
+            
+            # Apply domain-specific adjustments
+            ai_prob = self._apply_domain_specific_adjustments(sentence, ai_prob, len(sentence.split()))
+            
+            # Determine if this is mixed content
+            is_mixed_content                     = (mixed_prob > self.MIXED_THRESHOLD)
+            
+            # 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,
+                                                                                  )
+            
+            # 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,
+                                                                                  )
+            
+            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,
+                                                            )
+                                        )
+        
+        return highlighted_sentences
+
+    
+    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 - FIXED
+        """
+        sentence_length = len(sentence.split())
+        
+        # IMPROVED: Better handling of short sentences
+        if (sentence_length < 3):
+            # Return neutral probability for very short sentences with low confidence
+            return 0.5, 0.5, 0.0, 0.3, {"short_sentence": 0.5}
+        
+        # Calculate sentence-level metric results
+        sentence_metric_results = dict()
+        breakdown               = dict()
+        
+        for name, doc_result in metric_results.items():
+            if doc_result.error is None:
+                # 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,
+                                                                                   )
+                
+                breakdown[name]               = sentence_prob
+        
+        # Use ensemble to combine sentence-level metrics
+        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)
+                        
+            except Exception as e:
+                logger.warning(f"Sentence ensemble failed: {e}")
+        
+        # Fallback: weighted average
+        return self._calculate_weighted_probability(metric_results, weights, breakdown)
+    
+
+    def _compute_sentence_metric(self, metric_name: str, sentence: str, result: MetricResult, weight: float) -> float:
+        """
+        Compute metric probability for a single sentence using domain-specific thresholds
+        """
+        sentence_length   = len(sentence.split())
+        
+        # Get domain-specific threshold for this metric
+        metric_thresholds = getattr(self.domain_thresholds, metric_name, None)
+
+        if not metric_thresholds:
+            return result.ai_probability
+        
+        # Base probability from document-level result
+        base_prob         = result.ai_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, 
+                                                                    thresholds      = metric_thresholds,
+                                                                   )
+        
+        return adjusted_prob
+    
+
+    def _create_sentence_metric_result(self, metric_name: str, ai_prob: float, doc_result: MetricResult) -> MetricResult:
+        """
+        Create sentence-level MetricResult from document-level result
+        """
+        # Adjust confidence based on sentence characteristics
+        sentence_confidence = self._calculate_sentence_confidence(doc_result.confidence)
+        
+        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,
+                           )
+    
+
+    def _calculate_sentence_confidence(self, doc_confidence: float) -> float:
+        """
+        Calculate confidence for sentence-level analysis
+        """
+        # Sentence-level analysis typically has lower confidence
+        return max(0.1, doc_confidence * 0.8)
+    
+
+    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]]:
+        """
+        Fallback weighted probability calculation - FIXED
+        """
+        weighted_ai_probs    = list()
+        weighted_human_probs = list()
+        confidences          = list()
+        total_weight         = 0.0
+        
+        for name, result in metric_results.items():
+            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)
+                    confidences.append(result.confidence)
+                    total_weight += weight
+        
+        if not weighted_ai_probs or total_weight == 0:
+            return 0.5, 0.5, 0.0, 0.5, {}
+        
+        ai_prob        = sum(weighted_ai_probs) / total_weight
+        human_prob     = sum(weighted_human_probs) / total_weight
+        mixed_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
+    
+
+    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)
+        
+        else:
+            # Calculate from metrics
+            return self._calculate_weighted_probability(metric_results, weights, {})
+    
+
+    def _apply_domain_specific_adjustments(self, sentence: str, ai_prob: float, sentence_length: int) -> float:
+        """
+        Apply domain-specific adjustments to AI probability - UPDATED FOR ALL DOMAINS
+        """
+        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._has_technical_terms(sentence_lower):
+                # Technical terms more common in AI
+                ai_prob *= 1.1  
+
+            elif self._has_code_like_patterns(sentence):
+                ai_prob *= 1.15
+            
+            elif sentence_length > 35:
+                ai_prob *= 1.05
+                
+        # Creative & informal domains
+        elif self.domain in [Domain.CREATIVE, Domain.SOCIAL_MEDIA, Domain.BLOG_PERSONAL]:
+            if self._has_informal_language(sentence_lower):
+                # Informal language more human-like
+                ai_prob *= 0.7  
+            
+            elif self._has_emotional_language(sentence):
+                ai_prob *= 0.8
+
+            elif (sentence_length < 10):
+                ai_prob *= 0.8
+                
+        # Academic & formal domains
+        elif self.domain in [Domain.ACADEMIC, Domain.LEGAL, Domain.MEDICAL]:
+            if self._has_citation_patterns(sentence):
+                # Citations more human-like
+                ai_prob *= 0.8  
+
+            elif self._has_technical_terms(sentence_lower):
+                ai_prob *= 1.1
+
+            elif (sentence_length > 40):
+                ai_prob *= 1.1
+                
+        # Business & professional domains
+        elif self.domain in [Domain.BUSINESS, Domain.MARKETING, Domain.JOURNALISM]:
+            if self._has_business_jargon(sentence_lower):
+                # Jargon can be AI-like
+                ai_prob *= 1.05  
+            
+            elif self._has_ambiguous_phrasing(sentence_lower):
+                # Ambiguity more human
+                ai_prob *= 0.9  
+            
+            elif (15 <= sentence_length <= 25):
+                ai_prob *= 0.9
+                
+        # Tutorial & educational domains
+        elif (self.domain == Domain.TUTORIAL):
+            if self._has_instructional_language(sentence_lower):
+                # Instructional tone more human
+                ai_prob *= 0.85  
+
+            elif self._has_step_by_step_pattern(sentence):
+                ai_prob *= 0.8
+            
+            elif self._has_examples(sentence):
+                ai_prob *= 0.9
+        
+        # General domain - minimal adjustments
+        elif self.domain == Domain.GENERAL:
+            if self._has_complex_structure(sentence):
+                ai_prob *= 0.9
+            
+            elif self._has_repetition(sentence):
+                ai_prob *= 1.1
+        
+        return max(0.0, min(1.0, ai_prob))
+    
+
+    def _apply_metric_specific_adjustments(self, metric_name: str, sentence: str, base_prob: float, sentence_length: int, thresholds: MetricThresholds) -> float:
+        """
+        Apply metric-specific adjustments
+        """
+        # Use metrics from ensemble
+        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)
+        
+        elif (metric_name == "entropy"):
+            words = sentence.split()
+            
+            if (len(words) > 3):
+                unique_words = len(set(words))
+                diversity    = unique_words / len(words)
+
+                if (diversity < 0.6):
+                    return min(1.0, base_prob * 1.2)
+
+                elif (diversity > 0.8):
+                    return max(0.0, base_prob * 0.8)
+        
+        elif (metric_name == "linguistic"):
+            complexity_score = self._analyze_sentence_complexity(sentence)
+
+            if (complexity_score < 0.3):
+                return min(1.0, base_prob * 1.1)
+            
+            elif (complexity_score > 0.7):
+                return max(0.0, base_prob * 0.9)
+        
+        elif (metric_name == "structural"):
+            if ((sentence_length < 5) or (sentence_length > 40)):
+                return max(0.0, base_prob * 0.8)
+
+            elif (8 <= sentence_length <= 20):
+                return min(1.0, base_prob * 1.1)
+        
+        elif (metric_name == "semantic_analysis"):
+            if self._has_repetition(sentence):
+                return min(1.0, base_prob * 1.2)
+        
+        elif (metric_name == "detect_gpt"):
+            # DetectGPT adjustments for sentence level
+            if (sentence_length > 15):
+                return min(1.0, base_prob * 1.1)
+        
+        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]:
+        """
+        Get color class with mixed content support - FIXED
+        """
+        # 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)"
+        
+        # Iterate through thresholds correctly
+        for min_thresh, max_thresh, color_class, color_hex, tooltip in self.COLOR_THRESHOLDS:
+            if (min_thresh <= probability < max_thresh):
+                return color_class, color_hex, tooltip
+        
+        # Fallback
+        return "uncertain", "#fef9c3", "Uncertain"
+    
+
+    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:
+        """
+        Generate enhanced tooltip with ENSEMBLE information
+        """
+        tooltip = f"{tooltip_base}\n"
+        
+        if is_mixed_content:
+            tooltip += "🔀 MIXED 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"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"
+        
+        if breakdown:
+            tooltip += "\n\nMetric Breakdown:"
+            # Show top 4 metrics
+            for metric, prob in list(breakdown.items())[:4]:  
+                tooltip += f"\n• {metric}: {prob:.1%}"
+        
+        tooltip += f"\n\nEnsemble Method: {self.ensemble.primary_method}"
+        
+        return tooltip
+
+
+    def _has_citation_patterns(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_informal_language(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_technical_terms(self, sentence: str) -> bool:
+        """
+        Check for domain-specific technical terms
+        """
+        technical_indicators = ['hereinafter', 'whereas', 'aforementioned', 'diagnosis', 'prognosis', 'etiology',
+                                'algorithm', 'neural network', 'machine learning', 'api', 'endpoint', 'database',
+                                'quantum', 'thermodynamics', 'hypothesis', 'methodology']
+
+        return any(indicator in sentence.lower() for indicator in technical_indicators)
+    
+
+    def _has_ambiguous_phrasing(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_complex_structure(self, sentence: str) -> bool:
+        """
+        Check if sentence has complex linguistic structure
+        """
+        words = sentence.split()
+        if (len(words) < 8):
+            return False
+        
+        complex_indicators = ['which', 'that', 'although', 'because', 'while', 'when', 'if', 'however', 'therefore']
+
+        return any(indicator in sentence.lower() for indicator in complex_indicators)
+    
+
+    def _has_emotional_language(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_business_jargon(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_instructional_language(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_step_by_step_pattern(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_examples(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _has_code_like_patterns(self, sentence: str) -> bool:
+        """
+        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)
+    
+
+    def _analyze_sentence_complexity(self, sentence: str) -> float:
+        """
+        Analyze sentence complexity (0 = simple, 1 = complex)
+        """
+        words = sentence.split()
+        if len(words) < 5:
+            return 0.2
+        
+        complexity_indicators = ['although', 'because', 'while', 'when', 'if', 'since', 'unless', 'until', 'which', 'that', 'who', 'whom', 'whose', 'and', 'but', 'or', 'yet', 'so', 'however', 'therefore', 'moreover', 'furthermore', 'nevertheless', ',', ';', ':', '—']
+        
+        score                 = 0.0
+        
+        if (len(words) > 15):
+            score += 0.3
+
+        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)
+        
+        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)
+        """
+        words = sentence.lower().split()
+        if (len(words) < 6):
+            return False
+        
+        word_counts = dict()
+
+        for word in words:
+            if (len(word) > 3):
+                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
+    
+
+    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) >= 10):
+                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:
+        """
+        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 GPTZero-like metrics summary
+            
+        Returns:
+        --------
+                                 { str }                        : HTML content
+        """
+        html_parts = list()
+        
+        # Add CSS
+        html_parts.append(self._generate_enhanced_css())
+        
+        # Only include legend if explicitly requested (usually False to avoid duplicates)
+        if include_legend:
+            html_parts.append(self._generate_legend_html())
+        
+        # Add highlighted text container
+        html_parts.append('<div class="highlighted-text">')
+        
+        for sent in highlighted_sentences:
+            extra_class = " mixed-highlight" if sent.is_mixed_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-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'title="{sent.tooltip}">'
+                              f'{sent.text}'
+                              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:
+        """
+        Generate CSS for highlighting - FIXED: Better readability
+        """
+        return """
+        <style>
+        .highlighted-text {
+            line-height: 1.8;
+            font-size: 16px;
+            font-family: 'Georgia', serif;
+            padding: 20px;
+            background: #ffffff;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+            margin-bottom: 20px;
+        }
+        
+        .highlight {
+            padding: 2px 4px;
+            margin: 0 1px;
+            border-radius: 3px;
+            transition: all 0.2s ease;
+            cursor: help;
+            border-bottom: 2px solid transparent;
+            color: #000000 !important;
+            font-weight: 500;
+            position: relative;
+        }
+        
+        .highlight:hover {
+            transform: translateY(-1px);
+            box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+            z-index: 10;
+            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;
+        }
+        
+        .medium-ai {
+            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 {
+            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 {
+            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;
+        }
+        </style>
+        """
+    
+
+    def _generate_metrics_summary(self, sentences: List[HighlightedSentence]) -> str:
+        """
+        Generate summary statistics for highlighted sentences - FIXED to calculate like GPTZero
+        """
+        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
+        
+        # GPTZero-like 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
+        """
+        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>
+            <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>
+                <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>
+                <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>
+                <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>
+            </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 GPTZero-like 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",
+          ]

detector/orchestrator.py

@@ -0,0 +1,570 @@
+# 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.detect_gpt import DetectGPTMetric
+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
+
+
+
+@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]
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization
+        """
+        return {"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,
+               }
+
+
+
+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)}")
+        
+        # DetectGPT metric (expensive)
+        try:
+            metrics["detect_gpt"] = DetectGPTMetric()
+            logger.debug("DetectGPT metric initialized")
+        
+        except Exception as e:
+            logger.error(f"Failed to initialize DetectGPT 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 == "detect_gpt")):
+                        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/BLOGPOST.md

@@ -0,0 +1,182 @@
+# 🧠 Building the AI Text Authentication Platform — Detecting the Fingerprints of Machine-Generated Text  
+
+**Author:** *Satyaki Mitra — Data Scientist, AI Researcher*  
+
+---
+
+## 🌍 The Context — When Machines Started Sounding Human  
+
+In the last few years, AI models like GPT-4, Claude, and Gemini have rewritten the boundaries of natural language generation.  
+From essays to resumes, from research papers to blogs, AI can now mimic the nuances of human writing with unsettling precision.  
+
+This explosion of generative text brings opportunity — but also uncertainty.  
+When *everything* can be generated, how do we know what’s *authentic*?  
+
+That question led me to build the **AI Text Authentication Platform** — a domain-aware, explainable system that detects whether a piece of text was written by a human or an AI model.  
+
+---
+
+## 🔍 The Idea — Beyond Binary Detection  
+
+Most existing detectors approach the problem as a yes/no question:  
+> “Was this written by AI?”  
+
+But the real challenge is more nuanced.  
+Different domains — academic papers, social media posts, technical documents, or creative writing — have very different stylistic baselines.  
+A generic model often misfires in one domain while succeeding in another.  
+
+I wanted to build something smarter —  
+an adaptive detector that understands *context*, *writing style*, and *linguistic diversity*, and still offers transparency in its decision-making.  
+
+---
+
+## 🧮 The Statistical Backbone — Blending Metrics and Machine Learning  
+
+Coming from a statistics background, I wanted to merge the **interpretability of statistical metrics** with the **depth of modern transformer models**.  
+Instead of relying purely on embeddings or a classifier, I designed a **multi-metric ensemble** that captures both linguistic and structural signals.  
+
+The system uses six core metrics:  
+
+| Metric | What it Measures | Why it Matters |
+|:--|:--|:--|
+| **Perplexity** | Predictability of word sequences | AI text tends to have smoother probability distributions |
+| **Entropy** | Diversity of token use | Humans are more chaotic; models are more uniform |
+| **Structural (Burstiness)** | Variation in sentence lengths | AI often produces rhythmically even sentences |
+| **Semantic Coherence** | Flow of meaning between sentences | LLMs maintain strong coherence, sometimes too strong |
+| **Linguistic Features** | Grammar complexity, POS diversity | Human syntax is idiosyncratic; AI’s is hyper-consistent |
+| **DetectGPT Stability** | Robustness to perturbations | AI text collapses faster under small changes |
+
+Each metric produces an independent *AI-likelihood score*.  
+These are then aggregated through a **confidence-calibrated ensemble**, which adjusts weights based on domain context and model confidence.  
+
+It’s not just machine learning — it’s *statistical reasoning, linguistic insight, and AI interpretability* working together.  
+
+---
+
+## 🏗️ The Architecture — A System That Learns, Explains, and Scales  
+
+I designed the system with modularity in mind.  
+Every layer is replaceable and extendable, so researchers can plug in new metrics, models, or rules without breaking the pipeline.
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart LR
+    UI[Web UI & API]
+    ORCH[Orchestrator]
+    METRICS[Metric Engines]
+    ENSEMBLE[Confidence Ensemble]
+    REPORT[Explanation + Report]
+    UI --> ORCH --> METRICS --> ENSEMBLE --> REPORT --> UI
+```
+
+The backend runs on FastAPI, powered by PyTorch, Transformers, and Scikit-Learn.
+Models are fetched dynamically from Hugging Face on the first run, cached locally, and version-pinned for reproducibility.
+This keeps the repository lightweight but production-ready.
+
+The UI (built in HTML + CSS + vanilla JS) provides live metric breakdowns, highlighting sentences most responsible for the final verdict.
+
+---
+
+## 🧠 Domain Awareness — One Size Doesn’t Fit All
+
+AI writing “feels” different across contexts.
+Academic writing has long, precise sentences with low entropy, while creative writing is expressive and variable.
+
+To handle this, I introduced domain calibration.
+Each domain has its own weight configuration, reflecting what matters most in that context:
+
+| Domain       | Emphasis                         |
+| :----------- | :------------------------------- |
+| Academic     | Linguistic structure, perplexity |
+| Technical    | Semantic coherence, consistency  |
+| Creative     | Entropy, burstiness              |
+| Social Media | Short-form unpredictability      |
+
+This calibration alone improved accuracy by nearly 20% over generic baselines.
+
+---
+
+## ⚙️ Engineering Choices That Matter
+
+The platform auto-downloads models from Hugging Face on first run — a deliberate design for scalability.
+It supports offline mode for enterprises and validates checksums for model integrity.
+
+Error handling and caching logic were built to ensure robustness — no dependency on manual model management.
+
+This kind of product-level thinking is essential when transitioning from proof-of-concept to MVP.
+
+---
+
+## 📊 The Results — What the Data Says
+
+Across test sets covering GPT-4, Claude-3, Gemini, and LLaMA content, the system achieved:
+
+| Model       |  Accuracy | Precision |    Recall |
+| :---------- | --------: | --------: | --------: |
+| GPT-4       |     95.8% |     96.2% |     95.3% |
+| Claude-3    |     94.2% |     94.8% |     93.5% |
+| Gemini Pro  |     93.6% |     94.1% |     93.0% |
+| LLaMA 2     |     92.8% |     93.3% |     92.2% |
+| **Overall** | **94.3%** | **94.6%** | **94.1%** |
+
+
+False positives dropped below 3% after domain-specific recalibration — a huge leap compared to most commercial detectors.
+
+---
+
+## 💡 Lessons Learned
+
+This project wasn’t just about detecting AI text — it was about understanding why models write the way they do.
+
+I learned how deeply metrics like entropy and burstiness connect to human psychology.
+I also learned the importance of explainability — users trust results only when they can see why a decision was made.
+
+Balancing statistical rigor with engineering pragmatism turned this into one of my most complete data science projects.
+
+---
+
+## 💼 Real-World Impact and Vision
+
+AI text detection has implications across multiple industries:
+
+🎓 Education: plagiarism and authorship validation
+
+💼 Hiring: resume authenticity and candidate writing verification
+
+📰 Publishing: editorial transparency
+
+🌐 Social media: moderation and misinformation detection
+
+I envision this project evolving into a scalable SaaS or institutional tool — blending detection, attribution, and linguistic analytics into one explainable AI platform.
+
+---
+
+## 🔮 What’s Next
+
+Expanding to multilingual support
+
+Incorporating counterfactual explainers (LIME, SHAP)
+
+Model-specific attribution (“Which LLM wrote this?”)
+
+Continuous benchmark pipelines for new generative models
+
+The whitepaper version dives deeper into methodology, mathematics, and system design.
+
+📘 Read the full Technical Whitepaper (PDF)
+
+---
+
+## ✍️ Closing Thoughts
+
+As AI blurs the line between human and machine creativity, it’s essential that we build systems that restore trust, traceability, and transparency.
+That’s what the AI Text Authentication Platform stands for — not just detection, but understanding the fingerprints of intelligence itself.
+
+---
+
+## Author: 
+Satyaki Mitra — Data Scientist, AI Researcher
+
+📍 Building interpretable AI systems that make machine learning transparent and human-centric.
+
+---

example.py

@@ -0,0 +1,45 @@
+# 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

logs/application/app_2025-10-29.log

@@ -0,0 +1,105 @@
+{"text": "Centralized logging system initialized\n", "record": {"elapsed": {"repr": "0:00:03.681153", "seconds": 3.681153}, "exception": null, "extra": {}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 140, "message": "Centralized logging system initialized", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.258826+05:30", "timestamp": 1761742167.258826}}}
+{"text": "Environment: development\n", "record": {"elapsed": {"repr": "0:00:03.681320", "seconds": 3.68132}, "exception": null, "extra": {}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 141, "message": "Environment: development", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.258993+05:30", "timestamp": 1761742167.258993}}}
+{"text": "Log Level: INFO\n", "record": {"elapsed": {"repr": "0:00:03.681410", "seconds": 3.68141}, "exception": null, "extra": {}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 142, "message": "Log Level: INFO", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259083+05:30", "timestamp": 1761742167.259083}}}
+{"text": "Log Directory: /Users/itobuz/projects/text_auth/logs\n", "record": {"elapsed": {"repr": "0:00:03.681487", "seconds": 3.681487}, "exception": null, "extra": {}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 143, "message": "Log Directory: /Users/itobuz/projects/text_auth/logs", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259160+05:30", "timestamp": 1761742167.25916}}}
+{"text": "================================================================================\n", "record": {"elapsed": {"repr": "0:00:03.681853", "seconds": 3.681853}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 369, "message": "================================================================================", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259526+05:30", "timestamp": 1761742167.259526}}}
+{"text": "TEXT-AUTH API Starting Up...\n", "record": {"elapsed": {"repr": "0:00:03.681957", "seconds": 3.681957}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 370, "message": "TEXT-AUTH API Starting Up...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259630+05:30", "timestamp": 1761742167.25963}}}
+{"text": "================================================================================\n", "record": {"elapsed": {"repr": "0:00:03.682034", "seconds": 3.682034}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 371, "message": "================================================================================", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259707+05:30", "timestamp": 1761742167.259707}}}
+{"text": "Initializing Detection Orchestrator...\n", "record": {"elapsed": {"repr": "0:00:03.682104", "seconds": 3.682104}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 375, "message": "Initializing Detection Orchestrator...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259777+05:30", "timestamp": 1761742167.259777}}}
+{"text": "TextProcessor initialized with min_length=50, max_length=50000\n", "record": {"elapsed": {"repr": "0:00:03.682177", "seconds": 3.682177}, "exception": null, "extra": {}, "file": {"name": "text_processor.py", "path": "/Users/itobuz/projects/text_auth/processors/text_processor.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 107, "message": "TextProcessor initialized with min_length=50, max_length=50000", "module": "text_processor", "name": "processors.text_processor", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.259850+05:30", "timestamp": 1761742167.25985}}}
+{"text": "ModelManager initialized with device: cpu\n", "record": {"elapsed": {"repr": "0:00:03.682673", "seconds": 3.682673}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 132, "message": "ModelManager initialized with device: cpu", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260346+05:30", "timestamp": 1761742167.260346}}}
+{"text": "Model cache directory: /Users/itobuz/projects/text_auth/models/cache\n", "record": {"elapsed": {"repr": "0:00:03.682975", "seconds": 3.682975}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 133, "message": "Model cache directory: /Users/itobuz/projects/text_auth/models/cache", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260648+05:30", "timestamp": 1761742167.260648}}}
+{"text": "LanguageDetector initialized (use_model=True)\n", "record": {"elapsed": {"repr": "0:00:03.683057", "seconds": 3.683057}, "exception": null, "extra": {}, "file": {"name": "language_detector.py", "path": "/Users/itobuz/projects/text_auth/processors/language_detector.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 179, "message": "LanguageDetector initialized (use_model=True)", "module": "language_detector", "name": "processors.language_detector", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260730+05:30", "timestamp": 1761742167.26073}}}
+{"text": "Initialized 6 metrics: ['structural', 'entropy', 'perplexity', 'semantic_analysis', 'linguistic', 'detect_gpt']\n", "record": {"elapsed": {"repr": "0:00:03.683152", "seconds": 3.683152}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "_initialize_metrics", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 190, "message": "Initialized 6 metrics: ['structural', 'entropy', 'perplexity', 'semantic_analysis', 'linguistic', 'detect_gpt']", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260825+05:30", "timestamp": 1761742167.260825}}}
+{"text": "AdvancedEnsembleClassifier initialized (primary=confidence_calibrated, fallback=domain_weighted, ml_ensemble=False)\n", "record": {"elapsed": {"repr": "0:00:03.683228", "seconds": 3.683228}, "exception": null, "extra": {}, "file": {"name": "ensemble.py", "path": "/Users/itobuz/projects/text_auth/detector/ensemble.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 91, "message": "AdvancedEnsembleClassifier initialized (primary=confidence_calibrated, fallback=domain_weighted, ml_ensemble=False)", "module": "ensemble", "name": "detector.ensemble", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260901+05:30", "timestamp": 1761742167.260901}}}
+{"text": "DetectionOrchestrator initialized (language_detection=True, skip_expensive=False)\n", "record": {"elapsed": {"repr": "0:00:03.683294", "seconds": 3.683294}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 133, "message": "DetectionOrchestrator initialized (language_detection=True, skip_expensive=False)", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.260967+05:30", "timestamp": 1761742167.260967}}}
+{"text": "Initializing detection pipeline...\n", "record": {"elapsed": {"repr": "0:00:03.683357", "seconds": 3.683357}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 203, "message": "Initializing detection pipeline...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.261030+05:30", "timestamp": 1761742167.26103}}}
+{"text": "Initializing domain classifier...\n", "record": {"elapsed": {"repr": "0:00:03.683422", "seconds": 3.683422}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 61, "message": "Initializing domain classifier...", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.261095+05:30", "timestamp": 1761742167.261095}}}
+{"text": "Loading model: domain_classifier (cross-encoder/nli-roberta-base)\n", "record": {"elapsed": {"repr": "0:00:03.683492", "seconds": 3.683492}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: domain_classifier (cross-encoder/nli-roberta-base)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:27.261165+05:30", "timestamp": 1761742167.261165}}}
+{"text": "Added model to cache: domain_classifier\n", "record": {"elapsed": {"repr": "0:00:04.551206", "seconds": 4.551206}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: domain_classifier", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:28.128879+05:30", "timestamp": 1761742168.128879}}}
+{"text": "Successfully loaded model: domain_classifier\n", "record": {"elapsed": {"repr": "0:00:04.551392", "seconds": 4.551392}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: domain_classifier", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:28.129065+05:30", "timestamp": 1761742168.129065}}}
+{"text": "Loading model: domain_classifier_fallback (microsoft/deberta-v3-small)\n", "record": {"elapsed": {"repr": "0:00:04.551480", "seconds": 4.55148}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: domain_classifier_fallback (microsoft/deberta-v3-small)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:28.129153+05:30", "timestamp": 1761742168.129153}}}
+{"text": "Added model to cache: domain_classifier_fallback\n", "record": {"elapsed": {"repr": "0:00:05.680966", "seconds": 5.680966}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: domain_classifier_fallback", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.258639+05:30", "timestamp": 1761742169.258639}}}
+{"text": "Successfully loaded model: domain_classifier_fallback\n", "record": {"elapsed": {"repr": "0:00:05.681158", "seconds": 5.681158}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: domain_classifier_fallback", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.258831+05:30", "timestamp": 1761742169.258831}}}
+{"text": "Fallback classifier loaded successfully\n", "record": {"elapsed": {"repr": "0:00:05.681248", "seconds": 5.681248}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 69, "message": "Fallback classifier loaded successfully", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.258921+05:30", "timestamp": 1761742169.258921}}}
+{"text": "Domain classifier initialized successfully\n", "record": {"elapsed": {"repr": "0:00:05.681335", "seconds": 5.681335}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 76, "message": "Domain classifier initialized successfully", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.259008+05:30", "timestamp": 1761742169.259008}}}
+{"text": "Initializing language detection model...\n", "record": {"elapsed": {"repr": "0:00:05.681407", "seconds": 5.681407}, "exception": null, "extra": {}, "file": {"name": "language_detector.py", "path": "/Users/itobuz/projects/text_auth/processors/language_detector.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 195, "message": "Initializing language detection model...", "module": "language_detector", "name": "processors.language_detector", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.259080+05:30", "timestamp": 1761742169.25908}}}
+{"text": "Loading pipeline: text-classification with language_detector\n", "record": {"elapsed": {"repr": "0:00:05.681476", "seconds": 5.681476}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_pipeline", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 430, "message": "Loading pipeline: text-classification with language_detector", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:29.259149+05:30", "timestamp": 1761742169.259149}}}
+{"text": "Language detector initialized successfully\n", "record": {"elapsed": {"repr": "0:00:06.694072", "seconds": 6.694072}, "exception": null, "extra": {}, "file": {"name": "language_detector.py", "path": "/Users/itobuz/projects/text_auth/processors/language_detector.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 203, "message": "Language detector initialized successfully", "module": "language_detector", "name": "processors.language_detector", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:30.271745+05:30", "timestamp": 1761742170.271745}}}
+{"text": "Initializing entropy metric...\n", "record": {"elapsed": {"repr": "0:00:06.694295", "seconds": 6.694295}, "exception": null, "extra": {}, "file": {"name": "entropy.py", "path": "/Users/itobuz/projects/text_auth/metrics/entropy.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 39, "message": "Initializing entropy metric...", "module": "entropy", "name": "metrics.entropy", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:30.271968+05:30", "timestamp": 1761742170.271968}}}
+{"text": "Loading model: perplexity_gpt2 (gpt2)\n", "record": {"elapsed": {"repr": "0:00:06.694388", "seconds": 6.694388}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: perplexity_gpt2 (gpt2)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:30.272061+05:30", "timestamp": 1761742170.272061}}}
+{"text": "Added model to cache: perplexity_gpt2\n", "record": {"elapsed": {"repr": "0:00:08.177207", "seconds": 8.177207}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: perplexity_gpt2", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.754880+05:30", "timestamp": 1761742171.75488}}}
+{"text": "Successfully loaded model: perplexity_gpt2\n", "record": {"elapsed": {"repr": "0:00:08.177413", "seconds": 8.177413}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: perplexity_gpt2", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755086+05:30", "timestamp": 1761742171.755086}}}
+{"text": "Entropy metric initialized successfully\n", "record": {"elapsed": {"repr": "0:00:08.177499", "seconds": 8.177499}, "exception": null, "extra": {}, "file": {"name": "entropy.py", "path": "/Users/itobuz/projects/text_auth/metrics/entropy.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 52, "message": "Entropy metric initialized successfully", "module": "entropy", "name": "metrics.entropy", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755172+05:30", "timestamp": 1761742171.755172}}}
+{"text": "Initializing perplexity metric...\n", "record": {"elapsed": {"repr": "0:00:08.177585", "seconds": 8.177585}, "exception": null, "extra": {}, "file": {"name": "perplexity.py", "path": "/Users/itobuz/projects/text_auth/metrics/perplexity.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 41, "message": "Initializing perplexity metric...", "module": "perplexity", "name": "metrics.perplexity", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755258+05:30", "timestamp": 1761742171.755258}}}
+{"text": "Perplexity metric initialized successfully\n", "record": {"elapsed": {"repr": "0:00:08.177656", "seconds": 8.177656}, "exception": null, "extra": {}, "file": {"name": "perplexity.py", "path": "/Users/itobuz/projects/text_auth/metrics/perplexity.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 55, "message": "Perplexity metric initialized successfully", "module": "perplexity", "name": "metrics.perplexity", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755329+05:30", "timestamp": 1761742171.755329}}}
+{"text": "Initializing semantic analysis metric...\n", "record": {"elapsed": {"repr": "0:00:08.177722", "seconds": 8.177722}, "exception": null, "extra": {}, "file": {"name": "semantic_analysis.py", "path": "/Users/itobuz/projects/text_auth/metrics/semantic_analysis.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 41, "message": "Initializing semantic analysis metric...", "module": "semantic_analysis", "name": "metrics.semantic_analysis", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755395+05:30", "timestamp": 1761742171.755395}}}
+{"text": "Loading model: semantic_primary (sentence-transformers/all-MiniLM-L6-v2)\n", "record": {"elapsed": {"repr": "0:00:08.177789", "seconds": 8.177789}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: semantic_primary (sentence-transformers/all-MiniLM-L6-v2)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.755462+05:30", "timestamp": 1761742171.755462}}}
+{"text": "Load pretrained SentenceTransformer: sentence-transformers/all-MiniLM-L6-v2\n", "record": {"elapsed": {"repr": "0:00:08.179934", "seconds": 8.179934}, "exception": null, "extra": {}, "file": {"name": "SentenceTransformer.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/sentence_transformers/SentenceTransformer.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 218, "message": "Load pretrained SentenceTransformer: sentence-transformers/all-MiniLM-L6-v2", "module": "SentenceTransformer", "name": "sentence_transformers.SentenceTransformer", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:31.757607+05:30", "timestamp": 1761742171.757607}}}
+{"text": "Added model to cache: semantic_primary\n", "record": {"elapsed": {"repr": "0:00:12.965674", "seconds": 12.965674}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: semantic_primary", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.543347+05:30", "timestamp": 1761742176.543347}}}
+{"text": "Successfully loaded model: semantic_primary\n", "record": {"elapsed": {"repr": "0:00:12.966306", "seconds": 12.966306}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: semantic_primary", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.543979+05:30", "timestamp": 1761742176.543979}}}
+{"text": "Semantic analysis metric initialized successfully\n", "record": {"elapsed": {"repr": "0:00:12.966523", "seconds": 12.966523}, "exception": null, "extra": {}, "file": {"name": "semantic_analysis.py", "path": "/Users/itobuz/projects/text_auth/metrics/semantic_analysis.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 49, "message": "Semantic analysis metric initialized successfully", "module": "semantic_analysis", "name": "metrics.semantic_analysis", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.544196+05:30", "timestamp": 1761742176.544196}}}
+{"text": "Initializing linguistic metric...\n", "record": {"elapsed": {"repr": "0:00:12.966714", "seconds": 12.966714}, "exception": null, "extra": {}, "file": {"name": "linguistic.py", "path": "/Users/itobuz/projects/text_auth/metrics/linguistic.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 39, "message": "Initializing linguistic metric...", "module": "linguistic", "name": "metrics.linguistic", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.544387+05:30", "timestamp": 1761742176.544387}}}
+{"text": "Loading model: linguistic_spacy (en_core_web_sm)\n", "record": {"elapsed": {"repr": "0:00:12.966901", "seconds": 12.966901}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: linguistic_spacy (en_core_web_sm)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.544574+05:30", "timestamp": 1761742176.544574}}}
+{"text": "Loaded spaCy model: en_core_web_sm\n", "record": {"elapsed": {"repr": "0:00:13.261871", "seconds": 13.261871}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "_load_spacy_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 447, "message": "Loaded spaCy model: en_core_web_sm", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.839544+05:30", "timestamp": 1761742176.839544}}}
+{"text": "Added model to cache: linguistic_spacy\n", "record": {"elapsed": {"repr": "0:00:13.262395", "seconds": 13.262395}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: linguistic_spacy", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.840068+05:30", "timestamp": 1761742176.840068}}}
+{"text": "Successfully loaded model: linguistic_spacy\n", "record": {"elapsed": {"repr": "0:00:13.262513", "seconds": 13.262513}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: linguistic_spacy", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.840186+05:30", "timestamp": 1761742176.840186}}}
+{"text": "Linguistic metric initialized successfully\n", "record": {"elapsed": {"repr": "0:00:13.262600", "seconds": 13.2626}, "exception": null, "extra": {}, "file": {"name": "linguistic.py", "path": "/Users/itobuz/projects/text_auth/metrics/linguistic.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 46, "message": "Linguistic metric initialized successfully", "module": "linguistic", "name": "metrics.linguistic", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.840273+05:30", "timestamp": 1761742176.840273}}}
+{"text": "Initializing DetectGPT metric...\n", "record": {"elapsed": {"repr": "0:00:13.262676", "seconds": 13.262676}, "exception": null, "extra": {}, "file": {"name": "detect_gpt.py", "path": "/Users/itobuz/projects/text_auth/metrics/detect_gpt.py"}, "function": "initialize", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 44, "message": "Initializing DetectGPT metric...", "module": "detect_gpt", "name": "metrics.detect_gpt", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.840349+05:30", "timestamp": 1761742176.840349}}}
+{"text": "Loading model: detectgpt_base (gpt2)\n", "record": {"elapsed": {"repr": "0:00:13.262757", "seconds": 13.262757}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: detectgpt_base (gpt2)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:36.840430+05:30", "timestamp": 1761742176.84043}}}
+{"text": "Evicted model from cache: domain_classifier\n", "record": {"elapsed": {"repr": "0:00:16.074200", "seconds": 16.0742}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 82, "message": "Evicted model from cache: domain_classifier", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:39.651873+05:30", "timestamp": 1761742179.651873}}}
+{"text": "Added model to cache: detectgpt_base\n", "record": {"elapsed": {"repr": "0:00:16.074401", "seconds": 16.074401}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: detectgpt_base", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:39.652074+05:30", "timestamp": 1761742179.652074}}}
+{"text": "Successfully loaded model: detectgpt_base\n", "record": {"elapsed": {"repr": "0:00:16.074483", "seconds": 16.074483}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: detectgpt_base", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:39.652156+05:30", "timestamp": 1761742179.652156}}}
+{"text": "Loading model: detectgpt_mask (distilroberta-base)\n", "record": {"elapsed": {"repr": "0:00:16.195286", "seconds": 16.195286}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Loading model: detectgpt_mask (distilroberta-base)", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:39.772959+05:30", "timestamp": 1761742179.772959}}}
+{"text": "Evicted model from cache: domain_classifier_fallback\n", "record": {"elapsed": {"repr": "0:00:18.221749", "seconds": 18.221749}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 82, "message": "Evicted model from cache: domain_classifier_fallback", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.799422+05:30", "timestamp": 1761742181.799422}}}
+{"text": "Added model to cache: detectgpt_mask\n", "record": {"elapsed": {"repr": "0:00:18.221942", "seconds": 18.221942}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "put", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 86, "message": "Added model to cache: detectgpt_mask", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.799615+05:30", "timestamp": 1761742181.799615}}}
+{"text": "Successfully loaded model: detectgpt_mask\n", "record": {"elapsed": {"repr": "0:00:18.222025", "seconds": 18.222025}, "exception": null, "extra": {}, "file": {"name": "model_manager.py", "path": "/Users/itobuz/projects/text_auth/models/model_manager.py"}, "function": "load_model", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 262, "message": "Successfully loaded model: detectgpt_mask", "module": "model_manager", "name": "models.model_manager", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.799698+05:30", "timestamp": 1761742181.799698}}}
+{"text": "DetectGPT metric initialized successfully\n", "record": {"elapsed": {"repr": "0:00:18.331655", "seconds": 18.331655}, "exception": null, "extra": {}, "file": {"name": "detect_gpt.py", "path": "/Users/itobuz/projects/text_auth/metrics/detect_gpt.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 76, "message": "DetectGPT metric initialized successfully", "module": "detect_gpt", "name": "metrics.detect_gpt", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909328+05:30", "timestamp": 1761742181.909328}}}
+{"text": "Detection pipeline initialized: 6/6 metrics ready\n", "record": {"elapsed": {"repr": "0:00:18.331887", "seconds": 18.331887}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 230, "message": "Detection pipeline initialized: 6/6 metrics ready", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909560+05:30", "timestamp": 1761742181.90956}}}
+{"text": "✓ Detection Orchestrator initialized\n", "record": {"elapsed": {"repr": "0:00:18.331973", "seconds": 18.331973}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 383, "message": "✓ Detection Orchestrator initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909646+05:30", "timestamp": 1761742181.909646}}}
+{"text": "Initializing Model Attributor...\n", "record": {"elapsed": {"repr": "0:00:18.332049", "seconds": 18.332049}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 389, "message": "Initializing Model Attributor...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909722+05:30", "timestamp": 1761742181.909722}}}
+{"text": "ModelAttributor initialized with domain-aware calibration\n", "record": {"elapsed": {"repr": "0:00:18.332120", "seconds": 18.33212}, "exception": null, "extra": {}, "file": {"name": "attribution.py", "path": "/Users/itobuz/projects/text_auth/detector/attribution.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 403, "message": "ModelAttributor initialized with domain-aware calibration", "module": "attribution", "name": "detector.attribution", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909793+05:30", "timestamp": 1761742181.909793}}}
+{"text": "Model attribution system initialized with metric ensemble\n", "record": {"elapsed": {"repr": "0:00:18.332185", "seconds": 18.332185}, "exception": null, "extra": {}, "file": {"name": "attribution.py", "path": "/Users/itobuz/projects/text_auth/detector/attribution.py"}, "function": "initialize", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 412, "message": "Model attribution system initialized with metric ensemble", "module": "attribution", "name": "detector.attribution", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909858+05:30", "timestamp": 1761742181.909858}}}
+{"text": "✓ Model Attributor initialized\n", "record": {"elapsed": {"repr": "0:00:18.332255", "seconds": 18.332255}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 395, "message": "✓ Model Attributor initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909928+05:30", "timestamp": 1761742181.909928}}}
+{"text": "Initializing Text Highlighter...\n", "record": {"elapsed": {"repr": "0:00:18.332318", "seconds": 18.332318}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 401, "message": "Initializing Text Highlighter...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.909991+05:30", "timestamp": 1761742181.909991}}}
+{"text": "TextProcessor initialized with min_length=50, max_length=50000\n", "record": {"elapsed": {"repr": "0:00:18.332385", "seconds": 18.332385}, "exception": null, "extra": {}, "file": {"name": "text_processor.py", "path": "/Users/itobuz/projects/text_auth/processors/text_processor.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 107, "message": "TextProcessor initialized with min_length=50, max_length=50000", "module": "text_processor", "name": "processors.text_processor", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910058+05:30", "timestamp": 1761742181.910058}}}
+{"text": "AdvancedEnsembleClassifier initialized (primary=confidence_calibrated, fallback=domain_weighted, ml_ensemble=False)\n", "record": {"elapsed": {"repr": "0:00:18.332457", "seconds": 18.332457}, "exception": null, "extra": {}, "file": {"name": "ensemble.py", "path": "/Users/itobuz/projects/text_auth/detector/ensemble.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 91, "message": "AdvancedEnsembleClassifier initialized (primary=confidence_calibrated, fallback=domain_weighted, ml_ensemble=False)", "module": "ensemble", "name": "detector.ensemble", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910130+05:30", "timestamp": 1761742181.91013}}}
+{"text": "✓ Text Highlighter initialized\n", "record": {"elapsed": {"repr": "0:00:18.332527", "seconds": 18.332527}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 407, "message": "✓ Text Highlighter initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910200+05:30", "timestamp": 1761742181.9102}}}
+{"text": "Initializing Report Generator...\n", "record": {"elapsed": {"repr": "0:00:18.332591", "seconds": 18.332591}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 410, "message": "Initializing Report Generator...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910264+05:30", "timestamp": 1761742181.910264}}}
+{"text": "ReportGenerator initialized (output_dir=/Users/itobuz/projects/text_auth/data/reports)\n", "record": {"elapsed": {"repr": "0:00:18.333106", "seconds": 18.333106}, "exception": null, "extra": {}, "file": {"name": "report_generator.py", "path": "/Users/itobuz/projects/text_auth/reporter/report_generator.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 58, "message": "ReportGenerator initialized (output_dir=/Users/itobuz/projects/text_auth/data/reports)", "module": "report_generator", "name": "reporter.report_generator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910779+05:30", "timestamp": 1761742181.910779}}}
+{"text": "✓ Report Generator initialized\n", "record": {"elapsed": {"repr": "0:00:18.333235", "seconds": 18.333235}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 416, "message": "✓ Report Generator initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910908+05:30", "timestamp": 1761742181.910908}}}
+{"text": "Initializing Reasoning Generator...\n", "record": {"elapsed": {"repr": "0:00:18.333322", "seconds": 18.333322}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 419, "message": "Initializing Reasoning Generator...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.910995+05:30", "timestamp": 1761742181.910995}}}
+{"text": "✓ Reasoning Generator initialized\n", "record": {"elapsed": {"repr": "0:00:18.333397", "seconds": 18.333397}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 425, "message": "✓ Reasoning Generator initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911070+05:30", "timestamp": 1761742181.91107}}}
+{"text": "Initializing Document Extractor...\n", "record": {"elapsed": {"repr": "0:00:18.333465", "seconds": 18.333465}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 428, "message": "Initializing Document Extractor...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911138+05:30", "timestamp": 1761742181.911138}}}
+{"text": "DocumentExtractor initialized (max_size=50.0MB)\n", "record": {"elapsed": {"repr": "0:00:18.333538", "seconds": 18.333538}, "exception": null, "extra": {}, "file": {"name": "document_extractor.py", "path": "/Users/itobuz/projects/text_auth/processors/document_extractor.py"}, "function": "__init__", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 124, "message": "DocumentExtractor initialized (max_size=50.0MB)", "module": "document_extractor", "name": "processors.document_extractor", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911211+05:30", "timestamp": 1761742181.911211}}}
+{"text": "✓ Document Extractor initialized\n", "record": {"elapsed": {"repr": "0:00:18.333604", "seconds": 18.333604}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 434, "message": "✓ Document Extractor initialized", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911277+05:30", "timestamp": 1761742181.911277}}}
+{"text": "================================================================================\n", "record": {"elapsed": {"repr": "0:00:18.333668", "seconds": 18.333668}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 436, "message": "================================================================================", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911341+05:30", "timestamp": 1761742181.911341}}}
+{"text": "TEXT-AUTH API Ready!\n", "record": {"elapsed": {"repr": "0:00:18.333730", "seconds": 18.33373}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 437, "message": "TEXT-AUTH API Ready!", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911403+05:30", "timestamp": 1761742181.911403}}}
+{"text": "Server: 0.0.0.0:8000\n", "record": {"elapsed": {"repr": "0:00:18.333792", "seconds": 18.333792}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 438, "message": "Server: 0.0.0.0:8000", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911465+05:30", "timestamp": 1761742181.911465}}}
+{"text": "Environment: development\n", "record": {"elapsed": {"repr": "0:00:18.333854", "seconds": 18.333854}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 439, "message": "Environment: development", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911527+05:30", "timestamp": 1761742181.911527}}}
+{"text": "Device: cpu\n", "record": {"elapsed": {"repr": "0:00:18.333913", "seconds": 18.333913}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 440, "message": "Device: cpu", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911586+05:30", "timestamp": 1761742181.911586}}}
+{"text": "================================================================================\n", "record": {"elapsed": {"repr": "0:00:18.333974", "seconds": 18.333974}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "startup_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 441, "message": "================================================================================", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911647+05:30", "timestamp": 1761742181.911647}}}
+{"text": "Application startup complete.\n", "record": {"elapsed": {"repr": "0:00:18.334210", "seconds": 18.33421}, "exception": null, "extra": {}, "file": {"name": "on.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/uvicorn/lifespan/on.py"}, "function": "startup", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 62, "message": "Application startup complete.", "module": "on", "name": "uvicorn.lifespan.on", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:41.911883+05:30", "timestamp": 1761742181.911883}}}
+{"text": "API Request: GET / -> 200\n", "record": {"elapsed": {"repr": "0:00:26.376190", "seconds": 26.37619}, "exception": null, "extra": {"log_type": "application", "extra": {"http_method": "GET", "path": "/", "status_code": 200, "duration_seconds": 0.0033, "user": null, "ip_address": "127.0.0.1", "timestamp": "2025-10-29T18:19:49.953812"}}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "log_api_request", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 374, "message": "API Request: GET / -> 200", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:49.953863+05:30", "timestamp": 1761742189.953863}}}
+{"text": "127.0.0.1:61039 - \"GET / HTTP/1.1\" 200\n", "record": {"elapsed": {"repr": "0:00:26.376935", "seconds": 26.376935}, "exception": null, "extra": {}, "file": {"name": "h11_impl.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/uvicorn/protocols/http/h11_impl.py"}, "function": "send", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 473, "message": "127.0.0.1:61039 - \"GET / HTTP/1.1\" 200", "module": "h11_impl", "name": "uvicorn.protocols.http.h11_impl", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:19:49.954608+05:30", "timestamp": 1761742189.954608}}}
+{"text": "[analysis_1761742231503] Analyzing text (6124 chars)\n", "record": {"elapsed": {"repr": "0:01:07.925544", "seconds": 67.925544}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "analyze_text", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 729, "message": "[analysis_1761742231503] Analyzing text (6124 chars)", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.503217+05:30", "timestamp": 1761742231.503217}}}
+{"text": "Step 1: Preprocessing text...\n", "record": {"elapsed": {"repr": "0:01:07.925807", "seconds": 67.925807}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 260, "message": "Step 1: Preprocessing text...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.503480+05:30", "timestamp": 1761742231.50348}}}
+{"text": "Step 2: Detecting language...\n", "record": {"elapsed": {"repr": "0:01:07.933266", "seconds": 67.933266}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 272, "message": "Step 2: Detecting language...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.510939+05:30", "timestamp": 1761742231.510939}}}
+{"text": "Text too long, truncated to 2000 characters for language detection\n", "record": {"elapsed": {"repr": "0:01:07.941615", "seconds": 67.941615}, "exception": null, "extra": {}, "file": {"name": "language_detector.py", "path": "/Users/itobuz/projects/text_auth/processors/language_detector.py"}, "function": "_detect_with_model", "level": {"icon": "⚠️", "name": "WARNING", "no": 30}, "line": 304, "message": "Text too long, truncated to 2000 characters for language detection", "module": "language_detector", "name": "processors.language_detector", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.519288+05:30", "timestamp": 1761742231.519288}}}
+{"text": "Detected language: en (confidence: 0.98, method: xlm-roberta-model)\n", "record": {"elapsed": {"repr": "0:01:08.145482", "seconds": 68.145482}, "exception": null, "extra": {}, "file": {"name": "language_detector.py", "path": "/Users/itobuz/projects/text_auth/processors/language_detector.py"}, "function": "detect", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 288, "message": "Detected language: en (confidence: 0.98, method: xlm-roberta-model)", "module": "language_detector", "name": "processors.language_detector", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.723155+05:30", "timestamp": 1761742231.723155}}}
+{"text": "Step 3: Classifying domain...\n", "record": {"elapsed": {"repr": "0:01:08.145741", "seconds": 68.145741}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 291, "message": "Step 3: Classifying domain...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:31.723414+05:30", "timestamp": 1761742231.723414}}}
+{"text": "Primary model classified domain: social_media (confidence: 0.109)\n", "record": {"elapsed": {"repr": "0:01:10.726145", "seconds": 70.726145}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "_classify_with_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Primary model classified domain: social_media (confidence: 0.109)", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:34.303818+05:30", "timestamp": 1761742234.303818}}}
+{"text": "Primary classifier low confidence, trying fallback model...\n", "record": {"elapsed": {"repr": "0:01:10.726378", "seconds": 70.726378}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "classify", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 118, "message": "Primary classifier low confidence, trying fallback model...", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:34.304051+05:30", "timestamp": 1761742234.304051}}}
+{"text": "Fallback model classified domain: science (confidence: 0.063)\n", "record": {"elapsed": {"repr": "0:01:13.849320", "seconds": 73.84932}, "exception": null, "extra": {}, "file": {"name": "domain_classifier.py", "path": "/Users/itobuz/projects/text_auth/processors/domain_classifier.py"}, "function": "_classify_with_model", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 221, "message": "Fallback model classified domain: science (confidence: 0.063)", "module": "domain_classifier", "name": "processors.domain_classifier", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:37.426993+05:30", "timestamp": 1761742237.426993}}}
+{"text": "Detected domain: social_media (confidence: 0.11)\n", "record": {"elapsed": {"repr": "0:01:13.849569", "seconds": 73.849569}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 319, "message": "Detected domain: social_media (confidence: 0.11)", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:37.427242+05:30", "timestamp": 1761742237.427242}}}
+{"text": "Step 4: Executing detection metrics calculations...\n", "record": {"elapsed": {"repr": "0:01:13.849687", "seconds": 73.849687}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 322, "message": "Step 4: Executing detection metrics calculations...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:37.427360+05:30", "timestamp": 1761742237.42736}}}
+{"text": "Executed 6 metrics successfully\n", "record": {"elapsed": {"repr": "0:01:20.393725", "seconds": 80.393725}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 362, "message": "Executed 6 metrics successfully", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.971398+05:30", "timestamp": 1761742243.971398}}}
+{"text": "Step 5: Aggregating results with ensemble...\n", "record": {"elapsed": {"repr": "0:01:20.393966", "seconds": 80.393966}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 365, "message": "Step 5: Aggregating results with ensemble...", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.971639+05:30", "timestamp": 1761742243.971639}}}
+{"text": "Analysis complete: Human-Written (AI probability: 38.5%, confidence: 0.63) in 12.47s\n", "record": {"elapsed": {"repr": "0:01:20.394253", "seconds": 80.394253}, "exception": null, "extra": {}, "file": {"name": "orchestrator.py", "path": "/Users/itobuz/projects/text_auth/detector/orchestrator.py"}, "function": "analyze", "level": {"icon": "✅", "name": "SUCCESS", "no": 25}, "line": 394, "message": "Analysis complete: Human-Written (AI probability: 38.5%, confidence: 0.63) in 12.47s", "module": "orchestrator", "name": "detector.orchestrator", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.971926+05:30", "timestamp": 1761742243.971926}}}
+{"text": "[analysis_1761742231503] Running attribution...\n", "record": {"elapsed": {"repr": "0:01:20.394704", "seconds": 80.394704}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "analyze_text", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 745, "message": "[analysis_1761742231503] Running attribution...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.972377+05:30", "timestamp": 1761742243.972377}}}
+{"text": "[analysis_1761742231503] Generating highlights...\n", "record": {"elapsed": {"repr": "0:01:20.396346", "seconds": 80.396346}, "exception": null, "extra": {}, "file": {"name": "text_auth_app.py", "path": "/Users/itobuz/projects/text_auth/text_auth_app.py"}, "function": "analyze_text", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 763, "message": "[analysis_1761742231503] Generating highlights...", "module": "text_auth_app", "name": "text_auth_app", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.974019+05:30", "timestamp": 1761742243.974019}}}
+{"text": "Detection completed: analysis_1761742231503 -> Human-Written\n", "record": {"elapsed": {"repr": "0:01:20.406711", "seconds": 80.406711}, "exception": null, "extra": {"log_type": "application", "extra": {"analysis_id": "analysis_1761742231503", "text_length": 6124, "verdict": "Human-Written", "confidence": 0.6342, "domain": "social_media", "processing_time_seconds": 12.4812, "timestamp": "2025-10-29T18:20:43.984376", "enable_attribution": true, "enable_highlighting": true}}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "log_detection_event", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 419, "message": "Detection completed: analysis_1761742231503 -> Human-Written", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.984384+05:30", "timestamp": 1761742243.984384}}}
+{"text": "API Request: POST /api/analyze -> 200\n", "record": {"elapsed": {"repr": "0:01:20.407701", "seconds": 80.407701}, "exception": null, "extra": {"log_type": "application", "extra": {"http_method": "POST", "path": "/api/analyze", "status_code": 200, "duration_seconds": 12.4884, "user": null, "ip_address": "127.0.0.1", "timestamp": "2025-10-29T18:20:43.985367"}}, "file": {"name": "logger.py", "path": "/Users/itobuz/projects/text_auth/utils/logger.py"}, "function": "log_api_request", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 374, "message": "API Request: POST /api/analyze -> 200", "module": "logger", "name": "utils.logger", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.985374+05:30", "timestamp": 1761742243.985374}}}
+{"text": "127.0.0.1:61041 - \"POST /api/analyze HTTP/1.1\" 200\n", "record": {"elapsed": {"repr": "0:01:20.407866", "seconds": 80.407866}, "exception": null, "extra": {}, "file": {"name": "h11_impl.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/uvicorn/protocols/http/h11_impl.py"}, "function": "send", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 473, "message": "127.0.0.1:61041 - \"POST /api/analyze HTTP/1.1\" 200", "module": "h11_impl", "name": "uvicorn.protocols.http.h11_impl", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:20:43.985539+05:30", "timestamp": 1761742243.985539}}}
+{"text": "Shutting down\n", "record": {"elapsed": {"repr": "0:02:43.050189", "seconds": 163.050189}, "exception": null, "extra": {}, "file": {"name": "server.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/uvicorn/server.py"}, "function": "shutdown", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 263, "message": "Shutting down", "module": "server", "name": "uvicorn.server", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:22:06.627862+05:30", "timestamp": 1761742326.627862}}}
+{"text": "Waiting for application shutdown.\n", "record": {"elapsed": {"repr": "0:02:43.152124", "seconds": 163.152124}, "exception": null, "extra": {}, "file": {"name": "on.py", "path": "/Users/itobuz/anaconda3/lib/python3.10/site-packages/uvicorn/lifespan/on.py"}, "function": "shutdown", "level": {"icon": "ℹ️", "name": "INFO", "no": 20}, "line": 67, "message": "Waiting for application shutdown.", "module": "on", "name": "uvicorn.lifespan.on", "process": {"id": 66535, "name": "SpawnProcess-1"}, "thread": {"id": 8707055360, "name": "MainThread"}, "time": {"repr": "2025-10-29 18:22:06.729797+05:30", "timestamp": 1761742326.729797}}}

metrics/base_metric.py

@@ -0,0 +1,260 @@
+# 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"
+
+
+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
+    
+
+    @abstractmethod
+    def initialize(self) -> bool:
+        """
+        Initialize the metric (load models, etc.)
+        
+        Returns:
+        --------
+            True if successful, False otherwise
+        """
+        pass
+    
+
+    @abstractmethod
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        Compute the metric for given text
+        
+        Arguments:
+        ----------
+            text     { str } : Input text to analyze
+
+            **kwargs         : Additional parameters
+            
+        Returns:
+        --------
+            MetricResult object
+        """
+        pass
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        if self._model is not None:
+            del self._model
+            self._model = None
+
+        if self._tokenizer is not None:
+            del self._tokenizer
+            self._tokenizer = None
+
+        self.is_initialized = False
+    
+
+    def __enter__(self):
+        """
+        Context manager entry
+        """
+        if not self.is_initialized:
+            self.initialize()
+        
+        return self
+    
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Context manager exit
+        """
+        self.cleanup()
+
+    
+    def _safe_compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        Safe wrapper for compute with error handling
+        
+        Arguments:
+        ----------
+            text     { str } : Input text
+
+            **kwargs         : Additional parameters
+            
+        Returns:
+        --------
+            { MetricResult } : MetricResult (with error if computation failed)
+        """
+        try:
+            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",
+                                       )
+            
+            result = self.compute(text, **kwargs)
+            return result
+            
+
+        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),
+                               )
+
+    
+    def batch_compute(self, texts: list, **kwargs) -> list:
+        """
+        Compute metric for multiple texts
+        
+        Arguments:
+        ----------
+            texts    { list } : List of input texts
+
+            **kwargs          : Additional parameters
+            
+        Returns:
+        --------
+               { list }       : List of MetricResult objects
+        """
+        results = list()
+
+        for text in texts:
+            result = self._safe_compute(text, **kwargs)
+            results.append(result)
+        
+        return results
+    
+
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Get metric information
+        """
+        return {"name"        : self.name,
+                "description" : self.description,
+                "initialized" : self.is_initialized,
+               }
+    
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name='{self.name}', initialized={self.is_initialized})"
+
+
+
+class StatisticalMetric(BaseMetric):
+    """
+    Base class for statistical metrics that don't require models
+    """
+    
+    def initialize(self) -> bool:
+        """
+        Statistical metrics don't need initialization
+        """
+        self.is_initialized = True
+        return True
+
+
+
+# Export
+__all__ = ["BaseMetric",
+           "MetricResult",
+           "StatisticalMetric",
+          ]

metrics/detect_gpt.py

@@ -0,0 +1,885 @@
+# 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 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
+
+
+
+class DetectGPTMetric(BaseMetric):
+    """
+    DetectGPT implementation for text stability analysis under perturbations
+    
+    Measures:
+    - Text stability under random perturbations
+    - Likelihood curvature analysis
+    - Masked token prediction analysis
+    """
+    def __init__(self):
+        super().__init__(name        = "detect_gpt",
+                         description = "Text stability analysis under perturbations (DetectGPT method)",
+                        )
+        
+        self.gpt_model      = None
+        self.gpt_tokenizer  = None
+        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")
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the DetectGPT metric
+        """
+        try:
+            logger.info("Initializing DetectGPT metric...")
+            
+            # Load GPT-2 model for likelihood calculation
+            model_manager = get_model_manager()
+            gpt_result    = model_manager.load_model("detectgpt_base")
+            
+            if isinstance(gpt_result, tuple):
+                self.gpt_model, self.gpt_tokenizer = gpt_result
+                # Move model to appropriate device
+                self.gpt_model.to(self.device)
+           
+            else:
+                logger.error("Failed to load GPT-2 model for DetectGPT")
+                return False
+            
+            # Load masked language model for perturbations
+            mask_result = model_manager.load_model("detectgpt_mask")
+            
+            if (isinstance(mask_result, tuple)):
+                self.mask_model, self.mask_tokenizer = mask_result
+                # Move model to appropriate device
+                self.mask_model.to(self.device)
+                
+                # Ensure tokenizer has padding token
+                if (self.mask_tokenizer.pad_token is None):
+                    self.mask_tokenizer.pad_token = self.mask_tokenizer.eos_token or '[PAD]'
+
+            else:
+                logger.warning("Failed to load mask model, using GPT-2 only")
+            
+            self.is_initialized = True
+            
+            logger.success("DetectGPT metric initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize DetectGPT metric: {repr(e)}")
+            return False
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        Compute DetectGPT analysis with FULL DOMAIN THRESHOLD INTEGRATION
+        """
+        try:
+            if ((not text) or (len(text.strip()) < 100)):
+                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 DetectGPT analysis",
+                                   )
+            
+            # Get domain-specific thresholds
+            domain               = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds    = get_threshold_for_domain(domain)
+            detectgpt_thresholds = domain_thresholds.detect_gpt
+            
+            # Check if we should run this computationally expensive metric
+            if (kwargs.get('skip_expensive', False)):
+                logger.info("Skipping DetectGPT 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",
+                                   )
+            
+            # Calculate DetectGPT features
+            features                        = self._calculate_detectgpt_features(text)
+            
+            # Calculate raw DetectGPT score (0-1 scale)
+            raw_detectgpt_score, confidence = self._analyze_detectgpt_patterns(features)
+            
+            # Apply domain-specific thresholds to convert raw score to probabilities
+            ai_prob, human_prob, mixed_prob = self._apply_domain_thresholds(raw_detectgpt_score, detectgpt_thresholds, features)
+            
+            # Apply confidence multiplier from domain thresholds
+            confidence                     *= detectgpt_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'    : detectgpt_thresholds.ai_threshold,
+                                                     'human_threshold' : detectgpt_thresholds.human_threshold,
+                                                     'raw_score'       : raw_detectgpt_score,
+                                                    },
+                               )
+            
+        except Exception as e:
+            logger.error(f"Error in DetectGPT 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),
+                               )
+    
+
+    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
+        
+        # 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
+
+        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
+            
+            else:
+                ai_prob    = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on stability variance
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+    
+
+    def _calculate_detectgpt_features(self, text: str) -> Dict[str, Any]:
+        """
+        Calculate comprehensive DetectGPT features
+        """
+        if not self.gpt_model or not self.gpt_tokenizer:
+            return self._get_default_features()
+        
+        try:
+            # Preprocess text for better analysis
+            processed_text        = self._preprocess_text_for_analysis(text)
+            
+            # Calculate original text likelihood
+            original_likelihood   = self._calculate_likelihood(processed_text)
+            
+            # Generate perturbations and calculate perturbed likelihoods
+            perturbations         = self._generate_perturbations(processed_text, num_perturbations = 5)
+            perturbed_likelihoods = list()
+            
+            for perturbed_text in perturbations:
+                if (perturbed_text and (perturbed_text != processed_text)):
+                    likelihood = self._calculate_likelihood(perturbed_text)
+                    
+                    if (likelihood > 0):
+                        perturbed_likelihoods.append(likelihood)
+            
+            # Calculate stability metrics
+            if perturbed_likelihoods:
+                stability_score          = self._calculate_stability_score(original_likelihood, perturbed_likelihoods)
+                curvature_score          = self._calculate_curvature_score(original_likelihood, perturbed_likelihoods)
+                variance_score           = np.var(perturbed_likelihoods) if len(perturbed_likelihoods) > 1 else 0.0
+                avg_perturbed_likelihood = np.mean(perturbed_likelihoods)
+            
+            else:
+                stability_score          = 0.5
+                curvature_score          = 0.5
+                variance_score           = 0.1
+                avg_perturbed_likelihood = original_likelihood
+            
+            # Calculate likelihood ratio
+            likelihood_ratio            = original_likelihood / avg_perturbed_likelihood if avg_perturbed_likelihood > 0 else 1.0
+            
+            # Chunk-based analysis for whole-text understanding
+            chunk_stabilities           = self._calculate_chunk_stability(processed_text, chunk_size=150)
+            stability_variance          = np.var(chunk_stabilities) if chunk_stabilities else 0.0
+            avg_chunk_stability         = np.mean(chunk_stabilities) if chunk_stabilities else stability_score
+            
+            # Normalize scores to 0-1 range
+            normalized_stability        = min(1.0, max(0.0, stability_score))
+            normalized_curvature        = min(1.0, max(0.0, curvature_score))
+            normalized_likelihood_ratio = min(2.0, likelihood_ratio) / 2.0    # Normalize to 0-1
+            
+            return {"original_likelihood"         : round(original_likelihood, 4),
+                    "avg_perturbed_likelihood"    : round(avg_perturbed_likelihood, 4),
+                    "likelihood_ratio"            : round(likelihood_ratio, 4),
+                    "normalized_likelihood_ratio" : round(normalized_likelihood_ratio, 4),
+                    "stability_score"             : round(normalized_stability, 4),
+                    "curvature_score"             : round(normalized_curvature, 4),
+                    "perturbation_variance"       : round(variance_score, 4),
+                    "avg_chunk_stability"         : round(avg_chunk_stability, 4),
+                    "stability_variance"          : round(stability_variance, 4),
+                    "num_perturbations"           : len(perturbations),
+                    "num_valid_perturbations"     : len(perturbed_likelihoods),
+                    "num_chunks_analyzed"         : len(chunk_stabilities),
+                   }
+            
+        except Exception as e:
+            logger.warning(f"DetectGPT feature calculation failed: {repr(e)}")
+            return self._get_default_features()
+    
+
+    def _calculate_likelihood(self, text: str) -> float:
+        """
+        Calculate log-likelihood of text using GPT-2 with robust error handling
+        """
+        try:
+            # Check text length before tokenization
+            if (len(text.strip()) < 10):
+                return 0.0
+
+            # Configure tokenizer for proper padding
+            tokenizer      = self._configure_tokenizer_padding(self.gpt_tokenizer)
+            
+            # Tokenize text with proper settings
+            encodings      = tokenizer(text, 
+                                       return_tensors = 'pt', 
+                                       truncation     = True,
+                                       max_length     = 512,
+                                       padding        = True,
+                                       return_attention_mask = True,
+                                      )
+
+            input_ids      = encodings.input_ids.to(self.device)
+            attention_mask = encodings.attention_mask.to(self.device)
+            
+            # Minimum tokens for meaningful analysis
+            if ((input_ids.numel() == 0) or (input_ids.size(1) < 5)):
+                return 0.0
+            
+            # Calculate negative log likelihood
+            with torch.no_grad():
+                outputs = self.gpt_model(input_ids, 
+                                         attention_mask = attention_mask, 
+                                         labels         = input_ids,
+                                        )
+
+                loss    = outputs.loss
+            
+            # Convert to positive log likelihood (higher = more likely)
+            log_likelihood = -loss.item()
+
+            # Reasonable range check (typical values are between -10 and 10)
+            if (abs(log_likelihood) > 100):
+                logger.warning(f"Extreme likelihood value detected: {log_likelihood}")
+                return 0.0
+            
+            return log_likelihood
+            
+        except Exception as e:
+            logger.warning(f"Likelihood calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    def _generate_perturbations(self, text: str, num_perturbations: int = 5) -> List[str]:
+        """
+        Generate perturbed versions of the text with robust error handling
+        """
+        perturbations = list()
+        
+        try:
+            # Pre-process text for perturbation
+            processed_text = self._preprocess_text_for_perturbation(text)
+            words          = processed_text.split()
+            
+            if (len(words) < 3):
+                return [processed_text]
+
+            # Method 1: Simple word deletion (most reliable)
+            if (len(words) > 5):
+                for _ in range(min(3, num_perturbations)):
+                    try:
+                        # Delete random words (10-20% of text)
+                        delete_count    = max(1, len(words) // 10)
+                        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)]
+                        perturbed_text  = ' '.join(perturbed_words)
+                        
+                        if (self._is_valid_perturbation(perturbed_text, processed_text)):
+                            perturbations.append(perturbed_text)
+                            
+                    except Exception as e:
+                        logger.debug(f"Word deletion perturbation failed: {e}")
+                        continue
+            
+            # Method 2: Word swapping
+            if (len(words) > 4) and (len(perturbations) < num_perturbations):
+                for _ in range(min(2, num_perturbations - len(perturbations))):
+                    try:
+                        perturbed_words = words.copy()
+                        
+                        # Swap random adjacent words
+                        if (len(perturbed_words) >= 3):
+                            swap_pos                                                 = np.random.randint(0, len(perturbed_words) - 2)
+                            perturbed_words[swap_pos], perturbed_words[swap_pos + 1] = perturbed_words[swap_pos + 1], perturbed_words[swap_pos]
+                        
+                        perturbed_text = ' '.join(perturbed_words)
+                        
+                        if (self._is_valid_perturbation(perturbed_text, processed_text)):
+                            perturbations.append(perturbed_text)
+                            
+                    except Exception as e:
+                        logger.debug(f"Word swapping perturbation failed: {e}")
+                        continue
+            
+            # Method 3: RoBERTa-specific masked word replacement
+            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(processed_text, 
+                                                                                        words, 
+                                                                                        num_perturbations - len(perturbations))
+                    perturbations.extend(roberta_perturbations)
+                    
+                except Exception as e:
+                    logger.warning(f"RoBERTa masked perturbation failed: {repr(e)}")
+            
+            # Method 4: Synonym replacement as fallback
+            if (len(perturbations) < num_perturbations):
+                try:
+                    synonym_perturbations = self._generate_synonym_perturbations(processed_text, 
+                                                                                 words, 
+                                                                                 num_perturbations - len(perturbations))
+                    perturbations.extend(synonym_perturbations)
+                    
+                except Exception as e:
+                    logger.debug(f"Synonym replacement failed: {e}")
+            
+            # Ensure we have at least some perturbations
+            if not perturbations:
+                # Fallback: create simple variations
+                fallback_perturbations = self._generate_fallback_perturbations(processed_text, words)
+                perturbations.extend(fallback_perturbations)
+            
+            # Remove duplicates and ensure we don't exceed requested number
+            unique_perturbations = list()
+            
+            for p in perturbations:
+                if (p and (p != processed_text) and (p not in unique_perturbations) and (self._is_valid_perturbation(p, processed_text))):
+                    unique_perturbations.append(p)
+            
+            return unique_perturbations[:num_perturbations]
+            
+        except Exception as e:
+            logger.warning(f"Perturbation generation failed: {repr(e)}")
+            # Return at least the original text as fallback
+            return [text]
+    
+
+    def _generate_roberta_masked_perturbations(self, text: str, words: List[str], max_perturbations: int) -> List[str]:
+        """
+        Generate perturbations using RoBERTa mask filling
+        """
+        perturbations = list()
+        
+        try:
+            # RoBERTa uses <mask> token
+            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']]
+            
+            if not candidate_positions:
+                candidate_positions = [i for i, word in enumerate(words) if len(word) > 2]
+            
+            if not candidate_positions:
+                return perturbations
+            
+            # Try multiple mask positions
+            attempts          = min(max_perturbations * 2, len(candidate_positions))
+            positions_to_try  = np.random.choice(candidate_positions, min(attempts, len(candidate_positions)), replace=False)
+            
+            for pos in positions_to_try:
+                if (len(perturbations) >= max_perturbations):
+                    break
+                    
+                try:
+                    # Create masked text
+                    masked_words      = words.copy()
+                    original_word     = masked_words[pos]
+                    masked_words[pos] = roberta_mask_token
+                    masked_text       = ' '.join(masked_words)
+                    
+                    # RoBERTa works better with proper sentence structure
+                    if not masked_text.endswith(('.', '!', '?')):
+                        masked_text += '.'
+                    
+                    # Tokenize with RoBERTa-specific settings
+                    inputs = self.mask_tokenizer(masked_text,
+                                                 return_tensors = "pt",
+                                                 truncation     = True,
+                                                 max_length     = min(128, self.mask_tokenizer.model_max_length),  # Conservative length
+                                                 padding        = True,
+                                                )
+                    
+                    # Move to appropriate device
+                    inputs = {k: v.to(self.device) for k, v in inputs.items()}
+                    
+                    # Get model predictions
+                    with torch.no_grad():
+                        outputs     = self.mask_model(**inputs)
+                        predictions = outputs.logits
+                    
+                    # Get the mask token position
+                    mask_token_index = torch.where(inputs["input_ids"][0] == self.mask_tokenizer.mask_token_id)[0]
+                    
+                    if (len(mask_token_index) == 0):
+                        continue
+                        
+                    mask_token_index = mask_token_index[0]
+                    
+                    # Get top prediction
+                    probs            = torch.nn.functional.softmax(predictions[0, mask_token_index], dim = -1)
+                    top_tokens       = torch.topk(probs, 3, dim = -1)
+                    
+                    for token_id in top_tokens.indices:
+                        predicted_token = self.mask_tokenizer.decode(token_id).strip()
+                        
+                        # Clean the predicted token
+                        predicted_token = self._clean_roberta_token(predicted_token)
+                        
+                        if (predicted_token and (predicted_token != original_word) and (len(predicted_token) > 1)):
+                            
+                            # Replace the masked word
+                            new_words      = words.copy()
+                            new_words[pos] = predicted_token
+                            new_text       = ' '.join(new_words)
+                            
+                            if (self._is_valid_perturbation(new_text, text)):
+                                perturbations.append(new_text)
+                                # Use first valid prediction
+                                break  
+                    
+                except Exception as e:
+                    logger.debug(f"RoBERTa mask filling failed for position {pos}: {e}")
+                    continue
+                    
+        except Exception as e:
+            logger.warning(f"RoBERTa masked perturbations failed: {e}")
+        
+        return perturbations
+    
+
+    def _generate_synonym_perturbations(self, text: str, words: List[str], max_perturbations: int) -> List[str]:
+        """
+        Simple synonym replacement as fallback
+        """
+        perturbations = list()
+        
+        try:
+            # Simple manual synonym dictionary for common words
+            synonym_dict          = {'good'  : ['great', 'excellent', 'fine', 'nice'],
+                                     'bad'   : ['poor', 'terrible', 'awful', 'horrible'],
+                                     'big'   : ['large', 'huge', 'enormous', 'massive'],
+                                     'small' : ['tiny', 'little', 'miniature', 'compact'],
+                                     'fast'  : ['quick', 'rapid', 'speedy', 'brisk'],
+                                     'slow'  : ['sluggish', 'leisurely', 'gradual', 'unhurried'],
+                                    }
+            
+            # Find replaceable words
+            replaceable_positions = [i for i, word in enumerate(words)  if word.lower() in synonym_dict]
+            
+            if not replaceable_positions:
+                return perturbations
+            
+            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()
+                synonyms      = synonym_dict.get(original_word, [])
+                
+                if synonyms:
+                    synonym        = np.random.choice(synonyms)
+                    new_words      = words.copy()
+                    new_words[pos] = synonym
+                    new_text       = ' '.join(new_words)
+                    
+                    if (self._is_valid_perturbation(new_text, text)):
+                        perturbations.append(new_text)
+                        
+        except Exception as e:
+            logger.debug(f"Synonym replacement failed: {e}")
+        
+        return perturbations
+    
+
+    def _generate_fallback_perturbations(self, text: str, words: List[str]) -> List[str]:
+        """
+        Generate fallback perturbations when other methods fail
+        """
+        perturbations = list()
+        
+        try:
+            # Remove first and last word
+            if (len(words) > 3):
+                perturbations.append(' '.join(words[1:-1]))
+            
+            # Remove first word only
+            elif (len(words) > 1):
+                perturbations.append(' '.join(words[1:]))
+            
+            # Capitalize/lowercase variations
+            if text:
+                perturbations.append(text.lower())
+                perturbations.append(text.capitalize())
+                
+        except Exception as e:
+            logger.debug(f"Fallback perturbation failed: {e}")
+        
+        return [p for p in perturbations if p and p != text][:3]
+    
+
+    def _calculate_stability_score(self, original_likelihood: float, perturbed_likelihoods: List[float]) -> float:
+        """
+        Calculate text stability score under perturbations : AI text tends to be less stable (larger likelihood drops)
+        """
+        if ((not perturbed_likelihoods) or (original_likelihood <= 0)):
+            return 0.5
+        
+        # Calculate average likelihood drop
+        likelihood_drops = [(original_likelihood - pl) / original_likelihood for pl in perturbed_likelihoods]
+        avg_drop         = np.mean(likelihood_drops) if likelihood_drops else 0.0
+        
+        # Higher drop = less stable = more AI-like : Normalize to 0-1 scale (assume max drop of 50%)
+        stability_score  = min(1.0, avg_drop / 0.5)
+
+        return stability_score
+    
+
+    def _calculate_curvature_score(self, original_likelihood: float, perturbed_likelihoods: List[float]) -> float:
+        """
+        Calculate likelihood curvature score : AI text often has different curvature properties
+        """
+        if ((not perturbed_likelihoods) or (original_likelihood <= 0)):
+            return 0.5
+        
+        # Calculate variance of likelihood changes
+        likelihood_changes = [abs(original_likelihood - pl) for pl in perturbed_likelihoods]
+        change_variance    = np.var(likelihood_changes) if len(likelihood_changes) > 1 else 0.0
+        
+        # Higher variance = more curvature = potentially more AI-like : Normalize based on typical variance ranges
+        curvature_score    = min(1.0, change_variance * 10.0)  # Adjust scaling factor as needed
+        
+        return curvature_score
+    
+
+    def _calculate_chunk_stability(self, text: str, chunk_size: int = 150) -> List[float]:
+        """
+        Calculate stability across text chunks for whole-text analysis
+        """
+        stabilities = list()
+        words       = text.split()
+        
+        # Create overlapping chunks
+        for i in range(0, len(words), chunk_size // 2):
+            chunk = ' '.join(words[i:i + chunk_size])
+            
+            if (len(chunk) > 50):
+                try:
+                    chunk_likelihood = self._calculate_likelihood(chunk)
+                    
+                    if (chunk_likelihood > 0):
+                        # 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)
+                            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(perturbed_chunk)
+
+                            if (perturbed_likelihood > 0):
+                                stability = (chunk_likelihood - perturbed_likelihood) / chunk_likelihood
+                                stabilities.append(min(1.0, max(0.0, stability)))
+                except Exception:
+                    continue
+        
+        return stabilities
+    
+
+    def _analyze_detectgpt_patterns(self, features: Dict[str, Any]) -> tuple:
+        """
+        Analyze DetectGPT patterns to determine RAW DetectGPT score (0-1 scale) : Higher score = more AI-like
+        """
+        # 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]
+        
+        if (len(valid_features) < 3):
+            # Low confidence if insufficient features
+            return 0.5, 0.3  
+
+
+        # Initialize ai_indicator list
+        ai_indicators = list()
+        
+        # High stability score suggests AI (larger likelihood drops)
+        if (features['stability_score'] > 0.6):
+            ai_indicators.append(0.8)
+
+        elif (features['stability_score'] > 0.3):
+            ai_indicators.append(0.5)
+        
+        else:
+            ai_indicators.append(0.2)
+        
+        # High curvature score suggests AI
+        if (features['curvature_score'] > 0.7):
+            ai_indicators.append(0.7)
+
+        elif (features['curvature_score'] > 0.4):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # High likelihood ratio suggests AI (original much more likely than perturbations)
+        if (features['normalized_likelihood_ratio'] > 0.8):
+            ai_indicators.append(0.9)
+        
+        elif (features['normalized_likelihood_ratio'] > 0.6):
+            ai_indicators.append(0.6)
+
+        else:
+            ai_indicators.append(0.3)
+        
+        # Low stability variance suggests AI (consistent across chunks)
+        if (features['stability_variance'] < 0.05):
+            ai_indicators.append(0.7)
+
+        elif (features['stability_variance'] < 0.1):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # High perturbation variance suggests AI
+        if (features['perturbation_variance'] > 0.1):
+            ai_indicators.append(0.6)
+
+        elif (features['perturbation_variance'] > 0.05):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content
+        """
+        mixed_indicators = list()
+        
+        # Moderate stability values might indicate mixing
+        if (0.35 <= features['stability_score'] <= 0.55):
+            mixed_indicators.append(0.3)
+       
+        else:
+            mixed_indicators.append(0.0)
+        
+        # High stability variance suggests mixed content
+        if (features['stability_variance'] > 0.15):
+            mixed_indicators.append(0.4)
+
+        elif (features['stability_variance'] > 0.1):
+            mixed_indicators.append(0.2)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # Inconsistent likelihood ratios
+        if (0.5 <= features['normalized_likelihood_ratio'] <= 0.8):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+    
+
+    def _get_default_features(self) -> Dict[str, Any]:
+        """
+        Return default features when analysis is not possible
+        """
+        return {"original_likelihood"         : 2.0,
+                "avg_perturbed_likelihood"    : 1.8,
+                "likelihood_ratio"            : 1.1,
+                "normalized_likelihood_ratio" : 0.55,
+                "stability_score"             : 0.5,
+                "curvature_score"             : 0.5,
+                "perturbation_variance"       : 0.05,
+                "avg_chunk_stability"         : 0.5,
+                "stability_variance"          : 0.1,
+                "num_perturbations"           : 0,
+                "num_valid_perturbations"     : 0,
+                "num_chunks_analyzed"         : 0,
+               }
+    
+
+    def _preprocess_text_for_analysis(self, text: str) -> str:
+        """
+        Preprocess text for DetectGPT analysis
+        """
+        if not text:
+            return ""
+        
+        # Normalize whitespace
+        text = ' '.join(text.split())
+        
+        # Truncate very long texts
+        if len(text) > 2000:
+            text = text[:2000] + "..."
+        
+        return text
+    
+
+    def _preprocess_text_for_perturbation(self, text: str) -> str:
+        """
+        Preprocess text specifically for perturbation generation
+        """
+        if not text:
+            return ""
+        
+        # Normalize whitespace
+        text = ' '.join(text.split())
+        
+        # RoBERTa works better with proper punctuation
+        if not text.endswith(('.', '!', '?')):
+            text += '.'
+        
+        # Truncate to safe length
+        if (len(text) > 1000):
+            sentences = text.split('. ')
+            if len(sentences) > 1:
+                # Keep first few sentences
+                text = '. '.join(sentences[:3]) + '.'
+            
+            else:
+                text = text[:1000]
+        
+        return text
+    
+
+    def _configure_tokenizer_padding(self, tokenizer) -> Any:
+        """
+        Configure tokenizer for proper padding
+        """
+        if tokenizer.pad_token is None:
+            if tokenizer.eos_token is not None:
+                tokenizer.pad_token = tokenizer.eos_token
+            
+            else:
+                tokenizer.add_special_tokens({'pad_token': '[PAD]'})
+        
+        tokenizer.padding_side = "left"
+        
+        return tokenizer
+    
+
+    def _clean_roberta_token(self, token: str) -> str:
+        """
+        Clean tokens from RoBERTa tokenizer
+        """
+        if not token:
+            return ""
+        
+        # Remove RoBERTa-specific artifacts
+        token = token.replace('Ġ', ' ')  # RoBERTa space marker
+        token = token.replace('</s>', '')
+        token = token.replace('<s>', '')
+        token = token.replace('<pad>', '')
+        
+        # Remove leading/trailing whitespace and punctuation
+        token = token.strip(' .,!?;:"\'')
+        
+        return token
+    
+
+    def _is_valid_perturbation(self, perturbed_text: str, original_text: str) -> bool:
+        """
+        Check if a perturbation is valid
+        """
+        # Not too short
+        return (perturbed_text and 
+                len(perturbed_text.strip()) > 10 and 
+                perturbed_text != original_text and
+                len(perturbed_text) > len(original_text) * 0.5)  
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.gpt_model      = None
+        self.gpt_tokenizer  = None
+        self.mask_model     = None
+        self.mask_tokenizer = None
+
+        super().cleanup()
+
+
+# Export
+__all__ = ["DetectGPTMetric"]

metrics/entropy.py

@@ -0,0 +1,536 @@
+# DEPENDENCIES
+import math
+import numpy as np
+from typing import Any
+from typing import Dict
+from typing import List
+from loguru import logger
+from collections import Counter
+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.threshold_config import get_threshold_for_domain
+
+
+class EntropyMetric(BaseMetric):
+    """
+    Enhanced entropy analysis for text randomness and predictability
+    
+    Measures (Aligned with Documentation):
+    - Character-level entropy and diversity
+    - Word-level entropy and burstiness  
+    - Token-level diversity and unpredictability in sequences
+    - Entropy distribution across text chunks
+    - AI-specific pattern detection
+    """
+    def __init__(self):
+        super().__init__(name        = "entropy",
+                         description = "Token-level diversity and unpredictability in text sequences",
+                        )
+        self.tokenizer = None
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the entropy metric
+        """
+        try:
+            logger.info("Initializing entropy metric...")
+            
+            # Load tokenizer for token-level analysis
+            model_manager = get_model_manager()
+            gpt_model     = model_manager.load_model("perplexity_gpt2")
+            
+            if isinstance(gpt_model, tuple):
+                self.tokenizer = gpt_model[1]
+
+            else:
+                logger.warning("Could not get tokenizer, using character-level entropy only")
+            
+            self.is_initialized = True
+            logger.success("Entropy metric initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize entropy metric: {repr(e)}")
+            return False
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        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",
+                                   )
+            
+            # Get domain-specific thresholds
+            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)
+            
+            # Calculate raw entropy score (0-1 scale)
+            raw_entropy_score, confidence   = self._analyze_entropy_patterns(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)
+            
+            # Apply confidence multiplier from domain thresholds
+            confidence                     *= entropy_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'    : entropy_thresholds.ai_threshold,
+                                                     'human_threshold' : entropy_thresholds.human_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),
+                               )
+    
+
+    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
+        
+        # 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
+        
+        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
+            
+            else:
+                ai_prob    = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on entropy variance
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+    
+
+    def _calculate_enhanced_entropy_features(self, text: str) -> Dict[str, Any]:
+        """
+        Calculate comprehensive entropy measures including document-required features
+        """
+        # Basic entropy measures
+        char_entropy              = self._calculate_character_entropy(text)
+        word_entropy              = self._calculate_word_entropy(text)
+        token_entropy             = self._calculate_token_entropy(text) if self.tokenizer else 0.0
+        
+        # DOCUMENT-REQUIRED: Token-level diversity
+        token_diversity           = self._calculate_token_diversity(text)
+        
+        # DOCUMENT-REQUIRED: Unpredictability in sequences
+        sequence_unpredictability = self._calculate_sequence_unpredictability(text)
+        
+        # Chunk-based analysis for whole-text understanding
+        chunk_entropies           = self._calculate_chunk_entropy(text, chunk_size=100)
+        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)
+        
+        # Predictability measures
+        predictability            = 1.0 - min(1.0, char_entropy / 4.0)
+        
+        return {"char_entropy"              : round(char_entropy, 4),
+                "word_entropy"              : round(word_entropy, 4),
+                "token_entropy"             : round(token_entropy, 4),
+                "token_diversity"           : round(token_diversity, 4), 
+                "sequence_unpredictability" : round(sequence_unpredictability, 4),  
+                "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),
+                "num_chunks_analyzed"       : len(chunk_entropies),
+               }
+    
+
+    def _calculate_character_entropy(self, text: str) -> float:
+        """
+        Calculate character-level entropy
+        """
+        # Clean text and convert to lowercase
+        clean_text = ''.join(c for c in text.lower() if c.isalnum() or c.isspace())
+        
+        if not clean_text:
+            return 0.0
+        
+        # Count character frequencies
+        char_counts = Counter(clean_text)
+        total_chars = len(clean_text)
+        
+        # Calculate entropy
+        entropy    = 0.0
+
+        for count in char_counts.values():
+            probability = count / total_chars
+            entropy    -= probability * math.log2(probability)
+        
+        return entropy
+    
+
+    def _calculate_word_entropy(self, text: str) -> float:
+        """
+        Calculate word-level entropy
+        """
+        words = text.lower().split()
+        if (len(words) < 5):
+            return 0.0
+        
+        word_counts = Counter(words)
+        total_words = len(words)
+        
+        entropy     = 0.0
+
+        for count in word_counts.values():
+            probability = count / total_words
+            entropy    -= probability * math.log2(probability)
+        
+        return entropy
+    
+
+    def _calculate_token_entropy(self, text: str) -> float:
+        """
+        Calculate token-level entropy using GPT-2 tokenizer
+        """
+        try:
+            if not self.tokenizer:
+                return 0.0
+            
+            # Length check before tokenization
+            if (len(text.strip()) < 10):
+                return 0.0
+
+            # Tokenize text
+            tokens = self.tokenizer.encode(text, 
+                                           add_special_tokens = False, 
+                                           truncation         = True, 
+                                          )
+            
+            if (len(tokens) < 10):
+                return 0.0
+            
+            token_counts = Counter(tokens)
+            total_tokens = len(tokens)
+            
+            entropy      = 0.0
+
+            for count in token_counts.values():
+                probability = count / total_tokens
+                entropy    -= probability * math.log2(probability)
+            
+            return entropy
+            
+        except Exception as e:
+            logger.warning(f"Token entropy calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    def _calculate_token_diversity(self, text: str) -> float:
+        """
+        Calculate token-level diversity : Higher diversity = more human-like
+        """
+        if not self.tokenizer:
+            return 0.0
+        
+        try:
+            tokens = self.tokenizer.encode(text, add_special_tokens=False)
+            if (len(tokens) < 10):
+                return 0.0
+            
+            unique_tokens = len(set(tokens))
+            total_tokens  = len(tokens)
+            
+            # Type-token ratio for tokens
+            diversity     = unique_tokens / total_tokens
+
+            return diversity
+            
+        except Exception as e:
+            logger.warning(f"Token diversity calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    def _calculate_sequence_unpredictability(self, text: str) -> float:
+        """
+        Calculate unpredictability in text sequences, it measures how unpredictable the token sequences are
+        """
+        if not self.tokenizer:
+            return 0.0
+        
+        try:
+            tokens = self.tokenizer.encode(text, add_special_tokens=False)
+            if (len(tokens) < 20):
+                return 0.0
+            
+            # Calculate bigram unpredictability
+            bigrams          = [(tokens[i], tokens[i+1]) for i in range(len(tokens)-1)]
+            bigram_counts    = Counter(bigrams)
+            total_bigrams    = len(bigrams)
+            
+            # Higher entropy = more unpredictable sequences
+            sequence_entropy = 0.0
+
+            for count in bigram_counts.values():
+                probability       = count / total_bigrams
+                sequence_entropy -= probability * math.log2(probability)
+            
+            # Normalize to 0-1 scale : Assuming max ~8 bits
+            normalized_entropy = min(1.0, sequence_entropy / 8.0)  
+            
+            return normalized_entropy
+            
+        except Exception as e:
+            logger.warning(f"Sequence unpredictability calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    def _calculate_chunk_entropy(self, text: str, chunk_size: int = 100) -> List[float]:
+        """
+        Calculate entropy distribution across text chunks
+        """
+        chunks = list()
+        words  = text.split()
+        
+        # Create overlapping chunks for better analysis
+        for i in range(0, len(words), chunk_size // 2):
+            chunk = ' '.join(words[i:i + chunk_size])
+            
+            # Minimum chunk size
+            if (len(chunk) > 20):  
+                entropy = self._calculate_character_entropy(chunk)
+                chunks.append(entropy)
+        
+        return chunks
+    
+
+    def _detect_ai_entropy_patterns(self, text: str) -> float:
+        """
+        Detect AI-specific entropy patterns: AI text often shows specific entropy signatures
+        """
+        patterns_detected = 0
+        total_patterns    = 4
+        
+        # Overly consistent character distribution
+        char_entropy      = self._calculate_character_entropy(text)
+        
+        # AI tends to be more consistent
+        if (char_entropy < 3.8):  
+            patterns_detected += 1
+        
+        # Low token diversity
+        token_diversity = self._calculate_token_diversity(text)
+
+        # AI reuses tokens more
+        if (token_diversity < 0.7):  
+            patterns_detected += 1
+        
+        # Predictable sequences
+        sequence_unpredictability = self._calculate_sequence_unpredictability(text)
+        
+        # AI sequences are more predictable
+        if (sequence_unpredictability < 0.4):  
+            patterns_detected += 1
+        
+        # Low entropy variance across chunks
+        chunk_entropies  = self._calculate_chunk_entropy(text, chunk_size = 100)
+        entropy_variance = np.var(chunk_entropies) if chunk_entropies else 0.0
+        
+        # AI maintains consistent entropy
+        if (entropy_variance < 0.2):  
+            patterns_detected += 1
+        
+        return patterns_detected / total_patterns
+    
+
+    def _analyze_entropy_patterns(self, features: Dict[str, Any]) -> tuple:
+        """
+        Analyze entropy patterns to determine RAW entropy score (0-1 scale)
+        This raw score will later be converted using domain thresholds
+        """
+        # Check feature validity
+        valid_features = [score for score in [features.get('char_entropy', 0),
+                                              features.get('token_diversity', 0), 
+                                              features.get('sequence_unpredictability', 0),
+                                              features.get('ai_pattern_score', 0)
+                                             ] if score > 0
+                         ]
+        
+        if (len(valid_features) < 2):
+            # Low confidence if insufficient features
+            return 0.5, 0.3  
+
+        ai_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)  
+
+        elif (features['char_entropy'] < 4.0):
+            # Moderate AI indicator
+            ai_indicators.append(0.6)  
+
+        else:
+            # Weak AI indicator
+            ai_indicators.append(0.2)  
+        
+        # Low entropy variance suggests AI (consistent patterns)
+        if (features['entropy_variance'] < 0.1):
+            # Very strong AI indicator
+            ai_indicators.append(0.9)  
+
+        elif (features['entropy_variance'] < 0.3):
+            # Neutral
+            ai_indicators.append(0.5)  
+
+        else:
+            # Strong human indicator
+            ai_indicators.append(0.1)  
+        
+        # Low token diversity suggests AI
+        if (features['token_diversity'] < 0.6):
+            ai_indicators.append(0.7)
+
+        elif (features['token_diversity'] < 0.8):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # Low sequence unpredictability suggests AI
+        if (features['sequence_unpredictability'] < 0.3):
+            ai_indicators.append(0.8)
+
+        elif (features['sequence_unpredictability'] < 0.5):
+            ai_indicators.append(0.5)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # High AI pattern score suggests AI
+        if (features['ai_pattern_score'] > 0.75):
+            ai_indicators.append(0.9)
+        
+        elif (features['ai_pattern_score'] > 0.5):
+            ai_indicators.append(0.7)
+        
+        else:
+            ai_indicators.append(0.3)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content with better indicators
+        """
+        mixed_indicators = list()
+        
+        # High entropy variance suggests mixed content
+        entropy_variance = features.get('entropy_variance', 0)
+        
+        if (entropy_variance > 0.5):
+            # Strong mixed indicator
+            mixed_indicators.append(0.6)  
+
+        elif (entropy_variance > 0.3):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # 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)):
+            entropy_discrepancy = abs(char_entropy - word_entropy)
+
+            # Large discrepancy suggests mixing
+            if (entropy_discrepancy > 1.0):  
+                mixed_indicators.append(0.4)
+        
+        # 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)
+        
+        mixed_probability = min(0.4, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+        
+        return mixed_probability
+
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.tokenizer = None
+        super().cleanup()
+
+
+
+# Export
+__all__ = ["EntropyMetric"]

metrics/linguistic.py

@@ -0,0 +1,671 @@
+# DEPENDENCIES
+import re
+import numpy as np
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Tuple
+from loguru import logger
+from collections import Counter
+from config.threshold_config import Domain
+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
+
+
+class LinguisticMetric(BaseMetric):
+    """
+    Linguistic analysis using POS tagging, syntactic complexity, and grammatical patterns
+    
+    Measures (Aligned with Documentation):
+    - POS tag diversity and patterns
+    - Syntactic complexity and sentence structure
+    - Grammatical patterns and usage
+    - Writing style analysis
+    """
+    def __init__(self):
+        super().__init__(name        = "linguistic",
+                         description = "POS tag diversity, syntactic complexity, and grammatical pattern analysis",
+                        )
+        self.nlp = None
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the linguistic metric
+        """
+        try:
+            logger.info("Initializing linguistic metric...")
+            
+            # Load spaCy model for linguistic analysis
+            model_manager = get_model_manager()
+            self.nlp      = model_manager.load_model("linguistic_spacy")
+            
+            self.is_initialized = True
+            logger.success("Linguistic metric initialized successfully")
+            
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize linguistic metric: {repr(e)}")
+            return False
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        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",
+                                   )
+            
+            # Get domain-specific thresholds
+            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)
+            
+            # Calculate raw linguistic score (0-1 scale)
+            raw_linguistic_score, confidence = self._analyze_linguistic_patterns(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)
+            
+            # Apply confidence multiplier from domain thresholds
+            confidence                      *= linguistic_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'    : linguistic_thresholds.ai_threshold,
+                                                     'human_threshold' : linguistic_thresholds.human_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),
+                               )
+    
+
+    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
+
+        # 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
+        
+        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
+            
+            else:
+                ai_prob    = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on linguistic variance
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+    
+
+    def _calculate_linguistic_features(self, text: str) -> Dict[str, Any]:
+        """
+        Calculate comprehensive linguistic analysis features
+        """
+        if not self.nlp:
+            return self._get_default_features()
+        
+        try:
+            # Process text with spaCy
+            doc                     = self.nlp(text)
+            
+            # 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)
+            pos_entropy             = self._calculate_pos_entropy(pos_tags = pos_tags)
+            
+            # Calculate syntactic complexity
+            syntactic_complexity    = self._calculate_syntactic_complexity(doc = doc)
+            avg_sentence_complexity = self._calculate_sentence_complexity(doc = doc)
+            
+            # Analyze grammatical patterns
+            grammatical_patterns    = self._analyze_grammatical_patterns(doc = doc)
+            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,
+                                                                       )
+            
+            # Calculate specific AI linguistic patterns
+            ai_pattern_score        = self._detect_ai_linguistic_patterns(doc = doc)
+            
+            return {"pos_diversity"           : round(pos_diversity, 4),
+                    "pos_entropy"             : round(pos_entropy, 4),
+                    "syntactic_complexity"    : round(syntactic_complexity, 4),
+                    "avg_sentence_complexity" : round(avg_sentence_complexity, 4),
+                    "grammatical_consistency" : round(grammatical_patterns['consistency'], 4),
+                    "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),
+                    "num_sentences"           : len(list(doc.sents)),
+                    "num_chunks_analyzed"     : len(chunk_features['complexities']),
+                   }
+            
+        except Exception as e:
+            logger.warning(f"Linguistic analysis failed: {repr(e)}")
+            return self._get_default_features()
+    
+
+    def _calculate_pos_diversity(self, pos_tags: List[str]) -> float:
+        """
+        Calculate POS tag diversity : Higher diversity = more varied sentence structures
+        """
+        if not pos_tags:
+            return 0.0
+        
+        unique_pos = len(set(pos_tags))
+        total_pos  = len(pos_tags)
+        
+        diversity  = unique_pos / total_pos
+        return diversity
+    
+
+    def _calculate_pos_entropy(self, pos_tags: List[str]) -> float:
+        """
+        Calculate entropy of POS tag distribution
+        """
+        if not pos_tags:
+            return 0.0
+        
+        pos_counts = Counter(pos_tags)
+        total_tags = len(pos_tags)
+        
+        entropy = 0.0
+        for count in pos_counts.values():
+            probability = count / total_tags
+            entropy    -= probability * np.log2(probability)
+        
+        return entropy
+    
+
+    def _calculate_syntactic_complexity(self, doc) -> float:
+        """
+        Calculate overall syntactic complexity : based on dependency tree depth and structure
+        """
+        complexities = list()
+        
+        for sent in doc.sents:
+            # Calculate dependency tree depth
+            depths = list()
+            for token in sent:
+                depth = self._calculate_dependency_depth(token)
+                depths.append(depth)
+            
+            if depths:
+                avg_depth  = np.mean(depths)
+                max_depth  = np.max(depths)
+                complexity = (avg_depth + max_depth) / 2.0
+                complexities.append(complexity)
+        
+        return np.mean(complexities) if complexities else 0.0
+    
+
+    def _calculate_dependency_depth(self, token, depth: int = 0) -> int:
+        """
+        Calculate dependency tree depth for a token
+        """
+        if not list(token.children):
+            return depth
+        
+        child_depths = [self._calculate_dependency_depth(child, depth + 1) for child in token.children]
+
+        return max(child_depths) if child_depths else depth
+    
+
+    def _calculate_sentence_complexity(self, doc) -> float:
+        """
+        Calculate average sentence complexity
+        """
+        complexities = list()
+        
+        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']])
+            
+            if (len(words) > 0):
+                complexity = (len(words) / 10.0) + (num_clauses * 0.5)
+
+                complexities.append(complexity)
+        
+        return np.mean(complexities) if complexities else 0.0
+    
+
+    def _analyze_grammatical_patterns(self, doc) -> Dict[str, float]:
+        """
+        Analyze grammatical patterns and consistency
+        """
+        # Count different grammatical constructions
+        passive_voice        = 0
+        active_voice         = 0
+        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)):
+                passive_voice += 1
+            
+            else:
+                active_voice += 1
+            
+            # Count transition words
+            for word in transition_words_set:
+                if word in sent_text:
+                    transition_words += 1
+                    break
+        
+        # Calculate ratios
+        passive_ratio    = passive_voice / total_sentences if total_sentences > 0 else 0.0
+        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))
+        
+        return {'consistency'      : max(0.0, consistency),
+                'passive_ratio'    : passive_ratio,
+                'transition_usage' : transition_usage,
+               }
+    
+
+    def _analyze_writing_style(self, doc) -> float:
+        """
+        Analyze writing style characteristics
+        """
+        style_indicators = list()
+        
+        # Sentence length variation
+        sent_lengths = [len([token for token in sent if not token.is_punct]) for sent in doc.sents]
+        
+        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))
+
+            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))
+
+        style_indicators.append(punct_score)
+        
+        return np.mean(style_indicators) if style_indicators else 0.5
+    
+
+    def _detect_ai_linguistic_patterns(self, doc) -> float:
+        """
+        Detect AI-specific linguistic patterns
+        """ 
+        patterns_detected     = 0
+        total_patterns        = 5
+        
+        # Pattern 1: Overuse of certain transition words
+        transition_overuse    = self._check_transition_overuse(doc)
+        
+        if transition_overuse:
+            patterns_detected += 1
+        
+        # Pattern 2: Unnatural POS sequences
+        pos_sequences         = self._check_unnatural_pos_sequences(doc)
+        
+        if pos_sequences:
+            patterns_detected += 1
+        
+        # Pattern 3: Overly consistent sentence structures
+        structure_consistency = self._check_structure_consistency(doc)
+        
+        if structure_consistency:
+            patterns_detected += 1
+        
+        # Pattern 4: Unusual grammatical constructions
+        unusual_grammar       = self._check_unusual_grammar(doc)
+        
+        if unusual_grammar:
+            patterns_detected += 1
+        
+        # Pattern 5: Repetitive phrasing
+        repetitive_phrasing   = self._check_repetitive_phrasing(doc)
+       
+        if repetitive_phrasing:
+            patterns_detected += 1
+        
+        return patterns_detected / total_patterns
+    
+
+    def _check_transition_overuse(self, doc) -> bool:
+        """
+        Check for overuse of transition words (common AI pattern)
+        """
+        transition_words = {'however', 'therefore', 'moreover', 'furthermore', 'additionally'}
+        transition_count = sum(1 for token in doc if token.lemma_.lower() in transition_words)
+        
+        # More than 5% of words being transitions is suspicious
+        return transition_count / len(doc) > 0.05 if len(doc) > 0 else False
+    
+
+    def _check_unnatural_pos_sequences(self, doc) -> bool:
+        """
+        Check for unnatural POS tag sequences
+        """
+        pos_sequences = list()
+
+        for sent in doc.sents:
+            sent_pos = [token.pos_ for token in sent]
+            pos_sequences.extend([(sent_pos[i], sent_pos[i+1]) for i in range(len(sent_pos)-1)])
+        
+        # Look for repetitive or unnatural sequences
+        if not pos_sequences:
+            return False
+        
+        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)
+    
+
+    def _check_structure_consistency(self, doc) -> bool:
+        """
+        Check for overly consistent sentence structures
+        """
+        sent_structures = list()
+        
+        for sent in doc.sents:
+            # Simple structure representation
+            structure = tuple(token.dep_ for token in sent if token.dep_ not in ['punct', 'det'])
+            sent_structures.append(structure)
+        
+        if (len(sent_structures) < 3):
+            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)
+    
+
+    def _check_unusual_grammar(self, doc) -> bool:
+        """
+        Check for unusual grammatical constructions
+        """
+        unusual_constructions = 0
+        
+        for token in doc:
+            # Check for unusual dependency relations i.e. less common relations
+            if token.dep_ in ['attr', 'oprd']:  
+                unusual_constructions += 1
+        
+        # More than 2% unusual constructions is suspicious
+        return (unusual_constructions / len(doc) > 0.02) if (len(doc) > 0) else False
+    
+
+    def _check_repetitive_phrasing(self, doc) -> bool:
+        """
+        Check for repetitive phrasing patterns
+        """
+        phrases = list()
+
+        for sent in doc.sents:
+            # Extract noun phrases
+            noun_phrases = [chunk.text.lower() for chunk in sent.noun_chunks]
+            phrases.extend(noun_phrases)
+        
+        if not phrases:
+            return False
+        
+        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)
+    
+
+    def _calculate_chunk_linguistics(self, text: str, chunk_size: int = 200) -> Dict[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 = ' '.join(words[i:i + chunk_size])
+            
+            if (len(chunk) > 50):
+                try:
+                    chunk_doc = self.nlp(chunk)
+                    
+                    # Check if processing was successful
+                    if (chunk_doc and (len(list(chunk_doc.sents)) > 0)):
+                        complexity = self._calculate_syntactic_complexity(chunk_doc)
+                        complexities.append(complexity)
+                
+                except Exception as e:
+                    logger.debug(f"Chunk linguistic analysis failed: {e}")
+                    continue
+        
+        return {'complexities': 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
+        """
+        # Check feature validity first
+        required_features = ['pos_diversity', 'syntactic_complexity', 'grammatical_consistency', 'transition_word_usage', 'ai_pattern_score', 'complexity_variance']
+        
+        valid_features    = [features.get(feat, 0) for feat in required_features if features.get(feat, 0) > 0]
+        
+        if (len(valid_features) < 4):
+            # Low confidence if insufficient features
+            return 0.5, 0.3  
+
+        # Initialize ai_indicator list 
+        ai_indicators = list()
+        
+        # Low POS diversity suggests AI
+        if (features['pos_diversity'] < 0.3):
+            ai_indicators.append(0.8)
+
+        elif (features['pos_diversity'] < 0.5):
+            ai_indicators.append(0.6)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # Low syntactic complexity suggests AI
+        if (features['syntactic_complexity'] < 2.0):
+            ai_indicators.append(0.7)
+
+        elif (features['syntactic_complexity'] < 3.0):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # High grammatical consistency suggests AI (unnaturally consistent)
+        if (features['grammatical_consistency'] > 0.8):
+            ai_indicators.append(0.9)
+
+        elif (features['grammatical_consistency'] > 0.6):
+            ai_indicators.append(0.5)
+
+        else:
+            ai_indicators.append(0.3)
+        
+        # High transition word usage suggests AI
+        if (features['transition_word_usage'] > 0.3):
+            ai_indicators.append(0.7)
+        
+        elif (features['transition_word_usage'] > 0.15):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # High AI pattern score suggests AI
+        if (features['ai_pattern_score'] > 0.6):
+            ai_indicators.append(0.8)
+
+        elif (features['ai_pattern_score'] > 0.3):
+            ai_indicators.append(0.5)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # Low complexity variance suggests AI
+        if (features['complexity_variance'] < 0.1):
+            ai_indicators.append(0.7)
+
+        elif (features['complexity_variance'] < 0.3):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content
+        """
+        mixed_indicators = list()
+        
+        # Moderate POS diversity might indicate mixing
+        if (0.35 <= features['pos_diversity'] <= 0.55):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # High complexity variance suggests mixed content
+        if (features['complexity_variance'] > 0.5):
+            mixed_indicators.append(0.4)
+
+        elif (features['complexity_variance'] > 0.3):
+            mixed_indicators.append(0.2)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # Inconsistent AI pattern detection
+        if (0.2 <= features['ai_pattern_score'] <= 0.6):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+    
+
+    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,
+                "num_sentences"           : 0,
+                "num_chunks_analyzed"     : 0,
+               }
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.nlp = None
+        super().cleanup()
+
+
+
+# Export
+__all__ = ["LinguisticMetric"]

metrics/perplexity.py

@@ -0,0 +1,485 @@
+# DEPENDENCIES
+import re
+import math
+import torch
+import numpy as np
+from typing import Any
+from typing import Dict
+from typing import List
+from loguru import logger
+from config.threshold_config import Domain
+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
+
+
+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)
+    - Perplexity distribution across text chunks
+    - Sentence-level perplexity patterns
+    - Cross-entropy analysis
+    """
+    def __init__(self):
+        super().__init__(name        = "perplexity",
+                         description = "GPT-2 based perplexity calculation for text predictability analysis",
+                        )
+
+        self.model     = None
+        self.tokenizer = None
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the perplexity metric
+        """
+        try:
+            logger.info("Initializing perplexity metric...")
+            
+            # Load GPT-2 model and tokenizer
+            model_manager = get_model_manager()
+            model_result  = model_manager.load_model(model_name = "perplexity_gpt2")
+            
+            if isinstance(model_result, tuple):
+                self.model, self.tokenizer = model_result
+            
+            else:
+                logger.error("Failed to load GPT-2 model for perplexity calculation")
+                return False
+            
+            self.is_initialized = True
+            logger.success("Perplexity metric initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize perplexity metric: {repr(e)}")
+            return False
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        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",
+                                   )
+            
+            # Get domain-specific thresholds
+            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)
+            
+            # Calculate raw perplexity score (0-1 scale)
+            raw_perplexity_score, confidence = self._analyze_perplexity_patterns(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)
+            
+            # Apply confidence multiplier from domain thresholds
+            confidence                      *= perplexity_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'    : perplexity_thresholds.ai_threshold,
+                                                     'human_threshold' : perplexity_thresholds.human_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),
+                               )
+    
+
+    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
+        
+        # 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
+        
+        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
+            
+            else:
+                ai_prob = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on perplexity variance
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+    
+
+    def _calculate_perplexity_features(self, text: str) -> Dict[str, Any]:
+        """
+        Calculate comprehensive perplexity measures
+        """
+        if not self.model or not self.tokenizer:
+            return self._get_default_features()
+        
+        # Calculate overall perplexity
+        overall_perplexity    = self._calculate_perplexity(text)
+        
+        # Split into sentences for sentence-level analysis
+        sentences             = self._split_sentences(text)
+        
+        # Calculate sentence-level perplexities
+        sentence_perplexities = list()
+        valid_sentences       = 0
+        
+        for sentence in sentences:
+            # Minimum sentence length
+            if (len(sentence.strip()) > 20):  
+                sent_perplexity = self._calculate_perplexity(sentence)
+                
+                if (sent_perplexity > 0):
+                    sentence_perplexities.append(sent_perplexity)
+                    valid_sentences += 1
+        
+        # Calculate statistical features
+        if sentence_perplexities:
+            avg_sentence_perplexity = np.mean(sentence_perplexities)
+            std_sentence_perplexity = np.std(sentence_perplexities)
+            min_sentence_perplexity = np.min(sentence_perplexities)
+            max_sentence_perplexity = np.max(sentence_perplexities)
+        
+        else:
+            avg_sentence_perplexity = overall_perplexity
+            std_sentence_perplexity = 0.0
+            min_sentence_perplexity = overall_perplexity
+            max_sentence_perplexity = overall_perplexity
+        
+        # Chunk-based analysis for whole-text understanding
+        chunk_perplexities    = self._calculate_chunk_perplexity(text, chunk_size = 200)
+        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
+        
+        # Normalize perplexity to 0-1 scale for easier interpretation
+        normalized_perplexity = self._normalize_perplexity(overall_perplexity)
+        
+        # Cross-entropy analysis
+        cross_entropy_score   = self._calculate_cross_entropy(text)
+        
+        return {"overall_perplexity"      : round(overall_perplexity, 2),
+                "normalized_perplexity"   : round(normalized_perplexity, 4),
+                "avg_sentence_perplexity" : round(avg_sentence_perplexity, 2),
+                "std_sentence_perplexity" : round(std_sentence_perplexity, 2),
+                "min_sentence_perplexity" : round(min_sentence_perplexity, 2),
+                "max_sentence_perplexity" : round(max_sentence_perplexity, 2),
+                "perplexity_variance"     : round(perplexity_variance, 4),
+                "avg_chunk_perplexity"    : round(avg_chunk_perplexity, 2),
+                "cross_entropy_score"     : round(cross_entropy_score, 4),
+                "num_sentences_analyzed"  : valid_sentences,
+                "num_chunks_analyzed"     : len(chunk_perplexities),
+               }
+    
+
+    def _calculate_perplexity(self, text: str) -> float:
+        """
+        Calculate perplexity for given text using GPT-2 : Lower perplexity = more predictable = more AI-like
+        """
+        try:
+            # Check text length before tokenization
+            if (len(text.strip()) < 10):
+                return 0.0
+
+            # Tokenize the text
+            encodings = self.tokenizer(text, 
+                                       return_tensors = 'pt', 
+                                       truncation     = True, 
+                                       max_length     = 1024,
+                                      )
+
+            input_ids = encodings.input_ids
+            
+            # Minimum tokens
+            if ((input_ids.numel() == 0) or (input_ids.size(1) < 5)):
+                return 0.0
+            
+            # Calculate loss (cross-entropy)
+            with torch.no_grad():
+                outputs = self.model(input_ids, labels = input_ids)
+                loss    = outputs.loss
+            
+            # Convert loss to perplexity
+            perplexity = math.exp(loss.item())
+
+            return perplexity
+            
+        except Exception as e:
+            logger.warning(f"Perplexity calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    def _split_sentences(self, text: str) -> List[str]:
+        """
+        Split text into sentences
+        """
+        sentences = re.split(r'[.!?]+', text)
+        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > 10]
+    
+
+    def _calculate_chunk_perplexity(self, text: str, chunk_size: int = 200) -> List[float]:
+        """
+        Calculate perplexity across text chunks for whole-text analysis
+        """
+        chunks = list()
+        words  = text.split()
+
+        # 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):
+            chunk = ' '.join(words[i:i + chunk_size])
+            
+            # Minimum chunk size
+            if (len(chunk) > 50):  
+                perplexity = self._calculate_perplexity(chunk)
+
+                # Reasonable range check
+                if ((perplexity > 0) and (perplexity < 1000)):
+                    chunks.append(perplexity)
+        
+        return chunks if chunks else [0.0]
+    
+
+    def _normalize_perplexity(self, perplexity: float) -> float:
+        """
+        Normalize perplexity using sigmoid transformation
+
+        Lower perplexity = higher normalized score = more AI-like
+        """
+        # Use exponential normalization : Typical ranges: AI = 10-40, Human = 20-100
+        normalized = 1.0 / (1.0 + np.exp((perplexity - 30) / 10))
+        
+        return normalized 
+    
+
+    def _calculate_cross_entropy(self, text: str) -> float:
+        """
+        Calculate cross-entropy as an alternative measure
+        """
+        try:
+            encodings = self.tokenizer(text, return_tensors='pt', truncation=True, max_length=1024)
+            input_ids = encodings.input_ids
+            
+            if (input_ids.numel() == 0):
+                return 0.0
+            
+            with torch.no_grad():
+                outputs = self.model(input_ids, labels = input_ids)
+                loss    = outputs.loss
+            
+            # Normalize cross-entropy to 0-1 scale : Assuming max ~5 nats
+            cross_entropy = loss.item()
+            normalized_ce = min(1.0, cross_entropy / 5.0) 
+            
+            return normalized_ce
+            
+        except Exception as e:
+            logger.warning(f"Cross-entropy calculation failed: {repr(e)}")
+            return 0.0
+    
+
+    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
+        """
+        # 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]
+    
+        if (len(valid_features) < 3):
+            # Low confidence if insufficient features
+            return 0.5, 0.3  
+
+
+        # Initialize ai_indicator list
+        ai_indicators = list()
+        
+        # Low overall perplexity suggests AI
+        if (features['normalized_perplexity'] > 0.7):
+            # Very AI-like
+            ai_indicators.append(0.8)  
+
+        elif (features['normalized_perplexity'] > 0.5):
+            # AI-like
+            ai_indicators.append(0.6)  
+
+        else:
+            # Human-like
+            ai_indicators.append(0.2) 
+        
+        # Low perplexity variance suggests AI (consistent predictability)
+        if (features['perplexity_variance'] < 50):
+            ai_indicators.append(0.7)
+
+        elif (features['perplexity_variance'] < 200):
+            ai_indicators.append(0.4)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # Low sentence perplexity std suggests AI (consistent across sentences)
+        if (features['std_sentence_perplexity'] < 20):
+            ai_indicators.append(0.8)
+
+        elif (features['std_sentence_perplexity'] < 50):
+            ai_indicators.append(0.5)
+        
+        else:
+            ai_indicators.append(0.2)
+        
+        # Low cross-entropy suggests AI (more predictable)
+        if (features['cross_entropy_score'] < 0.3):
+            ai_indicators.append(0.7)
+        
+        elif (features['cross_entropy_score'] < 0.6):
+            ai_indicators.append(0.4)
+        
+        else:
+            ai_indicators.append(0.2)
+        
+        # Consistent chunk perplexity suggests AI
+        chunk_variance = features['perplexity_variance']
+        
+        if (chunk_variance < 25):
+            ai_indicators.append(0.9)
+
+        elif (chunk_variance < 100):
+            ai_indicators.append(0.6)
+
+        else:
+            ai_indicators.append(0.3)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content
+        """
+        mixed_indicators = list()
+        
+        # Moderate perplexity values might indicate mixing
+        if (0.4 <= features['normalized_perplexity'] <= 0.6):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # High perplexity variance suggests mixed content
+        if (features['perplexity_variance'] > 200):
+            mixed_indicators.append(0.4)
+
+        elif (features['perplexity_variance'] > 100):
+            mixed_indicators.append(0.2)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # Inconsistent sentence perplexities
+        if (20 <= features['std_sentence_perplexity'] <= 60):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+    
+
+    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,
+                "num_sentences_analyzed"  : 0,
+                "num_chunks_analyzed"     : 0,
+               }
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.model     = None
+        self.tokenizer = None
+        super().cleanup()
+
+
+
+# Export
+__all__ = ["PerplexityMetric"]

metrics/semantic_analysis.py

@@ -0,0 +1,535 @@
+# DEPENDENCIES
+import re
+import numpy as np
+from typing import Any
+from typing import Dict
+from typing import List
+from loguru import logger
+from collections import Counter
+from config.threshold_config import Domain
+from metrics.base_metric import BaseMetric
+from metrics.base_metric import MetricResult
+from models.model_manager import get_model_manager
+from sklearn.metrics.pairwise import cosine_similarity
+from config.threshold_config import get_threshold_for_domain
+
+
+class SemanticAnalysisMetric(BaseMetric):
+    """
+    Semantic coherence and consistency analysis
+    
+    Measures (Aligned with Documentation):
+    - Semantic similarity between sentences
+    - Topic consistency across text
+    - Coherence and logical flow
+    - Repetition patterns and redundancy
+    - Contextual consistency
+    """
+    def __init__(self):
+        super().__init__(name        = "semantic_analysis",
+                         description = "Semantic coherence, repetition patterns, and contextual consistency analysis",
+                        )
+
+        self.sentence_model = None
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the semantic analysis metric
+        """
+        try:
+            logger.info("Initializing semantic analysis metric...")
+            
+            # Load sentence transformer for semantic embeddings
+            model_manager       = get_model_manager()
+            self.sentence_model = model_manager.load_model("semantic_primary")
+            
+            self.is_initialized = True
+
+            logger.success("Semantic analysis metric initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize semantic analysis metric: {repr(e)}")
+            return False
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        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",
+                                   )
+            
+            # Get domain-specific thresholds
+            domain                          = kwargs.get('domain', Domain.GENERAL)
+            domain_thresholds               = get_threshold_for_domain(domain)
+            semantic_thresholds             = domain_thresholds.semantic_analysis
+            
+            # Calculate comprehensive semantic features
+            features                        = self._calculate_semantic_features(text)
+            
+            # Calculate raw semantic score (0-1 scale)
+            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)
+            
+            # Apply confidence multiplier from domain thresholds
+            confidence                     *= semantic_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'    : semantic_thresholds.ai_threshold,
+                                                     'human_threshold' : semantic_thresholds.human_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),
+                               )
+    
+
+    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
+        
+        # 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
+        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
+            
+            else:
+                ai_prob    = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on semantic variance
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+    
+
+    def _calculate_semantic_features(self, text: str) -> Dict[str, Any]:
+        """
+        Calculate comprehensive semantic analysis features
+        """
+        # Split text into sentences
+        sentences = self._split_sentences(text)
+        
+        if (len(sentences) < 3):
+            return self._get_default_features()
+        
+        # Calculate semantic embeddings for all sentences
+        sentence_embeddings = self._get_sentence_embeddings(sentences)
+        
+        if sentence_embeddings is None:
+            return self._get_default_features()
+        
+        # Calculate semantic similarity matrix
+        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)
+        
+        # Chunk-based analysis for whole-text understanding
+        chunk_coherence        = self._calculate_chunk_coherence(text, chunk_size=200)
+        
+        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),
+                "num_chunks_analyzed"    : len(chunk_coherence),
+               }
+    
+
+    def _split_sentences(self, text: str) -> List[str]:
+        """
+        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]
+    
+
+    def _get_sentence_embeddings(self, sentences: List[str]) -> np.ndarray:
+        """
+        Get semantic embeddings for sentences
+        """
+        try:
+            if not self.sentence_model:
+                return None
+            
+            # Filter out very short sentences that might cause issues
+            valid_sentences = [s for s in sentences if len(s.strip()) > 5]
+            if not valid_sentences:
+                return 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 embeddings
+            
+        except Exception as e:
+            logger.warning(f"Sentence embedding failed: {repr(e)}")
+            return 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
+        
+        # Calculate average similarity between adjacent sentences
+        adjacent_similarities = list()
+
+        for i in range(len(similarity_matrix) - 1):
+            adjacent_similarities.append(similarity_matrix[i, i + 1])
+        
+        if (not adjacent_similarities):
+            return 0.0
+        
+        return np.mean(adjacent_similarities)
+    
+
+    def _calculate_consistency(self, similarity_matrix: np.ndarray) -> float:
+        """
+        Calculate topic consistency throughout the text : Lower variance in similarities = more consistent
+        """
+        if (similarity_matrix.size == 0):
+            return 0.0
+        
+        # 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
+        
+        variance    = np.var(all_similarities)
+        # Convert to consistency score (higher = more consistent)
+        consistency = 1.0 - min(1.0, variance * 5.0)  # Normalize
+
+        return max(0.0, 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
+        
+        # Look for high similarity between non-adjacent sentences
+        repetition_count  = 0
+        total_comparisons = 0
+        
+        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):  
+                    repetition_count += 1
+                
+                total_comparisons += 1
+        
+        if (total_comparisons == 0):
+            return 0.0
+        
+        repetition_score = repetition_count / total_comparisons
+        
+        # Scale to make differences more noticeable
+        return min(1.0, repetition_score * 3.0)  
+    
+
+    def _calculate_topic_drift(self, similarity_matrix: np.ndarray) -> float:
+        """
+        Calculate topic drift throughout the text : Higher drift = less focused content
+        """
+        if (len(similarity_matrix) < 3):
+            return 0.0
+        
+        # Calculate similarity between beginning and end sections
+        start_size         = min(3, len(similarity_matrix) // 3)
+        end_size           = min(3, len(similarity_matrix) // 3)
+        
+        start_indices      = list(range(start_size))
+        end_indices        = list(range(len(similarity_matrix) - end_size, len(similarity_matrix)))
+        
+        cross_similarities = list()
+
+        for i in start_indices:
+            for j in end_indices:
+                cross_similarities.append(similarity_matrix[i, j])
+        
+        if not cross_similarities:
+            return 0.0
+        
+        avg_cross_similarity = np.mean(cross_similarities)
+        # Lower similarity between start and end = higher topic drift
+        topic_drift          = 1.0 - avg_cross_similarity
+
+        return max(0.0, 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
+        
+        # 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())
+            all_words.extend(words)
+        
+        if (len(all_words) < 10):
+            return 0.0
+        
+        # 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]
+        
+        if not top_keywords:
+            return 0.0
+        
+        # Check if top keywords appear consistently across sentences
+        keyword_presence = list()
+
+        for keyword in top_keywords:
+            sentences_with_keyword = sum(1 for sentence in sentences if keyword in sentence.lower())
+            presence_ratio         = sentences_with_keyword / len(sentences)
+            keyword_presence.append(presence_ratio)
+        
+        consistency = np.mean(keyword_presence)
+
+        return consistency
+    
+
+    def _calculate_chunk_coherence(self, text: str, chunk_size: int = 200) -> List[float]:
+        """
+        Calculate coherence across text chunks for whole-text analysis
+        """
+        chunks = list()
+        words  = text.split()
+        
+        # Create overlapping chunks
+        for i in range(0, len(words), chunk_size // 2):
+            chunk = ' '.join(words[i:i + chunk_size])
+            
+            # Minimum chunk size
+            if (len(chunk) > 50):  
+                chunk_sentences = self._split_sentences(chunk)
+                
+                if (len(chunk_sentences) >= 2):
+                    embeddings = self._get_sentence_embeddings(chunk_sentences)
+                    
+                    if ((embeddings is not None) and (len(embeddings) >= 2)):
+                        similarity_matrix = cosine_similarity(embeddings)
+                        coherence         = self._calculate_coherence(similarity_matrix)
+                        chunks.append(coherence)
+        
+        return chunks if chunks else [0.0]
+    
+
+    def _analyze_semantic_patterns(self, features: Dict[str, Any]) -> tuple:
+        """
+        Analyze semantic patterns to determine RAW semantic score (0-1 scale)
+        """
+        # 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]
+    
+        if (len(valid_features) < 3):
+            # Low confidence if insufficient features
+            return 0.5, 0.3  
+    
+        
+        # Initialize ai_indicator list
+        ai_indicators = list()
+
+        # AI text often has very high coherence (too perfect)
+        if (features['coherence_score'] > 0.7):
+            # Suspiciously high coherence
+            ai_indicators.append(0.8)  
+
+        elif (features['coherence_score'] > 0.5):
+            # Moderate coherence
+            ai_indicators.append(0.5)
+
+        else:
+            # Low coherence - more human-like
+            ai_indicators.append(0.2)  
+        
+        # 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)
+
+        else:
+            ai_indicators.append(0.3)
+        
+        # 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)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # 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)
+
+        else:
+            ai_indicators.append(0.3)
+        
+        # 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)
+
+        else:
+            ai_indicators.append(0.2)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content
+        """
+        mixed_indicators = list()
+        
+        # Moderate coherence values might indicate mixing
+        if (0.4 <= features['coherence_score'] <= 0.6):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # 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)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        # Inconsistent repetition patterns
+        if (0.15 <= features['repetition_score'] <= 0.35):
+            mixed_indicators.append(0.3)
+
+        else:
+            mixed_indicators.append(0.0)
+        
+        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+    
+
+    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,
+                "num_sentences"          : 0,
+                "num_chunks_analyzed"    : 0,
+               }
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.sentence_model = None
+        super().cleanup()
+
+
+
+
+# Export
+__all__ = ["SemanticAnalysisMetric"]

metrics/structural.py

@@ -0,0 +1,449 @@
+# DEPENDENCIES
+import re
+import numpy as np
+from typing import Any
+from typing import Dict
+from typing import List
+from loguru import logger
+from collections import Counter
+from metrics.base_metric import MetricResult
+from metrics.base_metric import StatisticalMetric 
+from config.threshold_config import Domain
+from config.threshold_config import get_threshold_for_domain
+
+
+class StructuralMetric(StatisticalMetric):
+    """
+    Structural analysis of text patterns with domain-aware thresholds
+    
+    Analyzes various structural features including:
+    - Sentence length distribution and variance
+    - Word length distribution  
+    - Punctuation patterns
+    - Vocabulary richness
+    - Burstiness (variation in patterns)
+    """
+    def __init__(self):
+        super().__init__(name        = "structural",
+                         description = "Structural and pattern analysis of the text",
+                        )
+    
+
+    def compute(self, text: str, **kwargs) -> MetricResult:
+        """
+        Compute structural features with domain aware thresholds
+        
+        Arguments:
+        ----------
+            text     { str } : Input text to analyze
+
+            **kwargs         : Additional parameters including 'domain'
+            
+        Returns:
+        --------
+            { MetricResult } : MetricResult with AI/Human probabilities
+        """
+        try:
+            # Get domain-specific thresholds
+            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)
+            
+            # Calculate raw AI probability based on features
+            raw_ai_prob, confidence         = self._calculate_ai_probability(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)
+            
+            # 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,
+                                                    },
+                               )
+            
+        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),
+                               )
+    
+
+
+    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
+        
+        # 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
+        
+        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
+            
+            else:
+                ai_prob    = 0.5
+                human_prob = 0.5
+        
+        # Ensure probabilities are valid
+        ai_prob    = max(0.0, min(1.0, ai_prob))
+        human_prob = max(0.0, min(1.0, human_prob))
+        
+        # Calculate mixed probability based on statistical patterns
+        mixed_prob = self._calculate_mixed_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
+        
+        return ai_prob, human_prob, mixed_prob
+
+    
+    def _extract_features(self, text: str) -> Dict[str, Any]:
+        """
+        Extract all structural features from text
+        """
+        # Basic tokenization
+        sentences           = self._split_sentences(text)
+        words               = self._tokenize_words(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
+        
+        # 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
+        
+        # Vocabulary richness
+        vocabulary_size     = len(set(words))
+        type_token_ratio    = vocabulary_size / len(words) if words else 0
+        
+        # Punctuation analysis
+        punctuation_density = self._calculate_punctuation_density(text)
+        comma_frequency     = text.count(',') / len(words) if words else 0
+        
+        # Burstiness (variation in patterns)
+        burstiness          = self._calculate_burstiness(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))
+        
+        # Readability approximation (simplified)
+        readability         = self._calculate_readability(text, sentences, words)
+        
+        # Pattern detection
+        repetition_score    = self._detect_repetitive_patterns(words)
+        
+        # N-gram analysis
+        bigram_diversity    = self._calculate_ngram_diversity(words, n = 2)
+        trigram_diversity   = self._calculate_ngram_diversity(words, n = 3)
+        
+        return {"avg_sentence_length" : round(avg_sentence_length, 2),
+                "std_sentence_length" : round(std_sentence_length, 2),
+                "avg_word_length"     : round(avg_word_length, 2),
+                "std_word_length"     : round(std_word_length, 2),
+                "vocabulary_size"     : vocabulary_size,
+                "type_token_ratio"    : round(type_token_ratio, 4),
+                "punctuation_density" : round(punctuation_density, 4),
+                "comma_frequency"     : round(comma_frequency, 4),
+                "burstiness_score"    : round(burstiness, 4),
+                "length_uniformity"   : round(length_uniformity, 4),
+                "readability_score"   : round(readability, 2),
+                "repetition_score"    : round(repetition_score, 4),
+                "bigram_diversity"    : round(bigram_diversity, 4),
+                "trigram_diversity"   : round(trigram_diversity, 4),
+                "num_sentences"       : len(sentences),
+                "num_words"           : len(words),
+               }
+
+    
+    def _split_sentences(self, text: str) -> List[str]:
+        """
+        Split text into sentences
+        """
+        # Simple sentence splitting
+        sentences = re.split(r'[.!?]+', text)
+        
+        return [s.strip() for s in sentences if s.strip()]
+    
+
+    def _tokenize_words(self, text: str) -> List[str]:
+        """
+        Tokenize text into words
+        """
+        # Simple word tokenization
+        words = re.findall(r'\b\w+\b', text.lower())
+        
+        return words
+    
+
+    def _calculate_punctuation_density(self, text: str) -> float:
+        """
+        Calculate punctuation density
+        """
+        punctuation = re.findall(r'[^\w\s]', text)
+        total_chars = len(text)
+        
+        return len(punctuation) / total_chars if total_chars > 0 else 0
+    
+
+    def _calculate_burstiness(self, values: List[float]) -> float:
+        """
+        Calculate burstiness score (variation in patterns)
+        Higher burstiness typically indicates human writing
+        """
+        if (len(values) < 2):
+            return 0.0
+        
+        mean_val   = np.mean(values)
+        std_val    = np.std(values)
+        
+        if (mean_val == 0):
+            return 0.0
+        
+        # Coefficient of variation
+        cv         = std_val / mean_val
+        
+        # Normalize to 0-1 range
+        burstiness = min(1.0, cv / 2.0)
+        
+        return burstiness
+    
+
+    def _calculate_readability(self, text: str, sentences: List[str], words: List[str]) -> float:
+        """
+        Calculate simplified readability score
+        (Approximation of Flesch Reading Ease)
+        """
+        if not sentences or not words:
+            return 0.0
+        
+        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))
+       
+        # Neutral score
+        return 50.0 
+    
+
+    def _count_syllables(self, word: str) -> int:
+        """
+        Approximate syllable count for a word
+        """
+        word               = word.lower()
+        vowels             = 'aeiouy'
+        syllable_count     = 0
+        previous_was_vowel = False
+        
+        for char in word:
+            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'
+        if (word.endswith('e')):
+            syllable_count -= 1
+        
+        # Ensure at least one syllable
+        if (syllable_count == 0):
+            syllable_count = 1
+        
+        return syllable_count
+    
+
+    def _detect_repetitive_patterns(self, words: List[str]) -> float:
+        """
+        Detect repetitive patterns in text
+        AI text sometimes shows more repetition
+        """
+        if (len(words) < 10):
+            return 0.0
+        
+        # Check for repeated words in close proximity
+        window_size = 10
+        repetitions = 0
+        
+        for i in range(len(words) - window_size):
+            window       = words[i:i + window_size]
+            word_counts  = Counter(window)
+            # Count words that appear more than once
+            repetitions += sum(1 for count in word_counts.values() if count > 1)
+        
+        # Normalize
+        max_repetitions  = (len(words) - window_size) * window_size
+        repetition_score = repetitions / max_repetitions if max_repetitions > 0 else 0
+        
+        return repetition_score
+
+    
+    def _calculate_ngram_diversity(self, words: List[str], n: int = 2) -> float:
+        """
+        Calculate n-gram diversity
+        Higher diversity often indicates human writing
+        """
+        if (len(words) < n):
+            return 0.0
+        
+        # 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
+        
+        return diversity
+    
+
+    def _calculate_ai_probability(self, features: Dict[str, Any]) -> tuple:
+        """
+        Calculate AI probability based on structural features
+        Returns raw score and confidence
+        """
+        ai_indicators = list()
+        
+        # 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)
+
+        else:
+            # Weak AI indicator
+            ai_indicators.append(0.3)
+        
+        # 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)
+        
+        # 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)
+        
+        # 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)
+        
+        # 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)
+        
+        # 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))
+        
+        return raw_score, confidence
+    
+
+    def _calculate_mixed_probability(self, features: Dict[str, Any]) -> float:
+        """
+        Calculate probability of mixed AI/Human content based on structural patterns
+        """
+        mixed_indicators = []
+        
+        # High burstiness suggests mixed content (inconsistent patterns)
+        if features['burstiness_score'] > 0.6:
+            mixed_indicators.append(0.4)
+        
+        # Inconsistent sentence lengths might indicate mixing
+        if (features['std_sentence_length'] > features['avg_sentence_length'] * 0.8):
+            mixed_indicators.append(0.3)
+        
+        # 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):
+            extreme_features += 1
+        if (features['readability_score'] < 20) or (features['readability_score'] > 90):
+            extreme_features += 1
+        
+        if (extreme_features >= 2):
+            mixed_indicators.append(0.3)
+        
+        return min(0.3, np.mean(mixed_indicators)) if mixed_indicators else 0.0
+
+
+# Export
+__all__ = ["StructuralMetric"]

models/__init__.py

@@ -0,0 +1,13 @@
+# 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

@@ -0,0 +1,665 @@
+# DEPENDENCIES
+import os
+import gc
+import json
+import torch
+import spacy
+import threading
+import subprocess
+from typing import Any
+from typing import Dict
+from typing import Union
+from pathlib import Path
+from loguru import logger
+from typing import Optional
+from datetime import datetime
+from transformers import pipeline
+from collections import OrderedDict
+from config.settings import settings
+from transformers import GPT2Tokenizer
+from transformers import AutoTokenizer
+from transformers import GPT2LMHeadModel
+from config.model_config import ModelType
+from config.model_config import ModelConfig
+from transformers import AutoModelForMaskedLM
+from config.model_config import MODEL_REGISTRY
+from config.model_config import get_model_config
+from config.model_config import get_required_models
+from sentence_transformers import SentenceTransformer
+from transformers import AutoModelForSequenceClassification
+
+
+class ModelCache:
+    """
+    LRU cache for models with size limit
+    """
+    def __init__(self, max_size: int = 5):
+        self.max_size            = max_size
+        self.cache : OrderedDict = OrderedDict()
+        self.lock                = threading.Lock()
+    
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get model from cache
+        """
+        with self.lock:
+            if key in self.cache:
+                # Move to end (most recently used)
+                self.cache.move_to_end(key)
+                logger.debug(f"Cache hit for model: {key}")
+                
+                return self.cache[key]
+            
+            logger.debug(f"Cache miss for model: {key}")
+            
+            return None
+    
+
+    def put(self, key: str, model: Any):
+        """
+        Add model to cache
+        """
+        with self.lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+            
+            else:
+                if (len(self.cache) >= self.max_size):
+                    # Remove least recently used
+                    removed_key   = next(iter(self.cache))
+                    removed_model = self.cache.pop(removed_key)
+                    
+                    # Clean up memory
+                    if hasattr(removed_model, 'to'):
+                        removed_model.to('cpu')
+                    
+                    del removed_model
+                    
+                    if torch.cuda.is_available():
+                        torch.cuda.empty_cache()
+
+                    logger.info(f"Evicted model from cache: {removed_key}")
+                
+                self.cache[key] = model
+
+                logger.info(f"Added model to cache: {key}")
+    
+
+    def clear(self):
+        """
+        Clear all cached models
+        """
+        with self.lock:
+            for model in self.cache.values():
+                if hasattr(model, 'to'):
+                    model.to('cpu')
+                del model
+            
+            self.cache.clear()
+            
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            
+            logger.info("Cleared model cache")
+    
+
+    def size(self) -> int:
+        """
+        Get current cache size
+        """
+        return len(self.cache)
+
+
+
+class ModelManager:
+    """
+    Central model management system
+    """
+    def __init__(self):
+        self.cache         = ModelCache(max_size = settings.MAX_CACHED_MODELS)
+        self.device        = torch.device(settings.DEVICE if torch.cuda.is_available() else "cpu")
+        self.cache_dir     = settings.MODEL_CACHE_DIR
+
+        self.cache_dir.mkdir(parents  = True, 
+                             exist_ok = True,
+                            )
+        
+        # Model metadata tracking
+        self.metadata_file = self.cache_dir / "model_metadata.json"
+        self.metadata      = self._load_metadata()
+        
+        logger.info(f"ModelManager initialized with device: {self.device}")
+        logger.info(f"Model cache directory: {self.cache_dir}")
+    
+
+    def _load_metadata(self) -> Dict:
+        """
+        Load model metadata from disk
+        """
+        if self.metadata_file.exists():
+            try:
+                with open(self.metadata_file, 'r') as f:
+                    return json.load(f)
+            
+            except Exception as e:
+                logger.warning(f"Failed to load metadata: {repr(e)}")
+        
+        return {}
+    
+
+    def _save_metadata(self):
+        """
+        Save model metadata to disk
+        """
+        try:
+            with open(self.metadata_file, 'w') as f:
+                json.dump(obj    = self.metadata, 
+                          fp     = f, 
+                          indent = 4,
+                         )
+        
+        except Exception as e:
+            logger.error(f"Failed to save metadata: {repr(e)}")
+    
+
+    def _update_metadata(self, model_name: str, model_config: ModelConfig):
+        """
+        Update metadata for a model
+        """
+        self.metadata[model_name] = {"model_id"      : model_config.model_id,
+                                     "model_type"    : model_config.model_type.value,
+                                     "downloaded_at" : datetime.now().isoformat(),
+                                     "size_mb"       : model_config.size_mb,
+                                     "last_used"     : datetime.now().isoformat(),
+                                    }
+        self._save_metadata()
+    
+
+    def is_model_downloaded(self, model_name: str) -> bool:
+        """
+        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
+    
+
+    def load_model(self, model_name: str, force_download: bool = False) -> Any:
+        """
+        Load a model by name
+        
+        Arguments:
+        ----------
+            model_name     { str }  : Name from MODEL_REGISTRY
+
+            force_download { bool } : Force re-download even if cached
+            
+        Returns:
+        --------
+                  { Any }           : Model instance
+        """
+        # Check cache first
+        if not force_download:
+            cached = self.cache.get(key = model_name)
+            
+            if cached is not None:
+                return cached
+        
+        # Get model configuration
+        model_config = get_model_config(model_name = model_name)
+        
+        if not model_config:
+            raise ValueError(f"Unknown model: {model_name}")
+        
+        logger.info(f"Loading model: {model_name} ({model_config.model_id})")
+        
+        try:
+            # Load based on model type
+            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.CLASSIFIER):
+                model = self._load_classifier(config = model_config)
+
+            elif (model_config.model_type == ModelType.SEQUENCE_CLASSIFICATION):
+                model = self._load_sequence_classifier(config = model_config)
+
+            elif (model_config.model_type == ModelType.TRANSFORMER):
+                model = self._load_transformer(config = model_config)
+
+            elif (model_config.model_type == ModelType.RULE_BASED):
+                # Check if it's a spaCy model
+                if model_config.additional_params.get("is_spacy_model", False):
+                    model = self._load_spacy_model(config = model_config)
+                
+                else:
+                    raise ValueError(f"Unknown rule-based model type: {model_name}")
+
+            else:
+                raise ValueError(f"Unsupported model type: {model_config.model_type}")
+            
+            # Update metadata
+            self._update_metadata(model_name   = model_name, 
+                                  model_config = model_config,
+                                 )
+            
+            # Cache the model
+            if model_config.cache_model:
+                self.cache.put(key   = model_name, 
+                               model = model,
+                              )
+            
+            logger.success(f"Successfully loaded model: {model_name}")
+            
+            return model
+            
+        except Exception as e:
+            logger.error(f"Failed to load model {model_name}: {repr(e)}")
+            raise
+
+    
+    def load_tokenizer(self, model_name: str) -> Any:
+        """
+        Load tokenizer for a model
+        
+        Arguments:
+        ----------
+            model_name { str } : Name from MODEL_REGISTRY
+            
+        Returns:
+        --------
+            { Any }            : Tokenizer instance
+        """
+        model_config = get_model_config(model_name = model_name)
+        
+        if not model_config:
+            raise ValueError(f"Unknown model: {model_name}")
+        
+        logger.info(f"Loading tokenizer for: {model_name}")
+        
+        try:
+            if (model_config.model_type in [ModelType.GPT, ModelType.CLASSIFIER, ModelType.SEQUENCE_CLASSIFICATION, ModelType.TRANSFORMER]):
+                tokenizer = AutoTokenizer.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                                          cache_dir                     = str(self.cache_dir),
+                                                         )
+                
+                logger.success(f"Successfully loaded tokenizer for: {model_name}")
+                return tokenizer
+            
+            else:
+                raise ValueError(f"Model type {model_config.model_type} doesn't require a separate tokenizer")
+                
+        except Exception as e:
+            logger.error(f"Failed to load tokenizer for {model_name}: {repr(e)}")
+            raise
+
+    
+    def _load_sentence_transformer(self, config: ModelConfig) -> SentenceTransformer:
+        """
+        Load SentenceTransformer model
+        """
+        model = SentenceTransformer(model_name_or_path = config.model_id,
+                                    cache_folder       = str(self.cache_dir),
+                                    device             = str(self.device),
+                                   )
+        return model
+        
+    
+    def _load_gpt_model(self, config: ModelConfig) -> tuple:
+        """
+        Load GPT-style model with tokenizer
+        """
+        model     = GPT2LMHeadModel.from_pretrained(pretrained_model_name_or_path = config.model_id,
+                                                    cache_dir                     = str(self.cache_dir),
+                                                   )
+
+        tokenizer = GPT2Tokenizer.from_pretrained(pretrained_model_name_or_path = config.model_id,
+                                                  cache_dir                     = str(self.cache_dir),
+                                                 )
+        
+        # Move to device
+        model     = model.to(self.device)
+
+        model.eval()
+        
+        # Apply quantization if enabled
+        if (settings.USE_QUANTIZATION and config.quantizable):
+            model = self._quantize_model(model = model)
+        
+        return (model, tokenizer)
+
+    
+    def _load_classifier(self, config: ModelConfig) -> Any:
+        """
+        Load classification model (for zero-shot, etc.)
+        """
+        # For zero-shot classification models
+        pipe = pipeline("zero-shot-classification",
+                        model        = config.model_id,
+                        device       = 0 if self.device.type == "cuda" else -1,
+                        model_kwargs = {"cache_dir": str(self.cache_dir)},
+                       )
+        
+        return pipe
+
+    
+    def _load_sequence_classifier(self, config: ModelConfig) -> Any:
+        """
+        Load sequence classification model (for domain classification)
+        """
+        model = AutoModelForSequenceClassification.from_pretrained(pretrained_model_name_or_path = config.model_id,
+                                                                   cache_dir                     = str(self.cache_dir),
+                                                                   num_labels                    = config.additional_params.get('num_labels', 2),
+                                                                  )
+        
+        # Move to device
+        model = model.to(self.device)
+        
+        model.eval()
+        
+        # Apply quantization if enabled
+        if (settings.USE_QUANTIZATION and config.quantizable):
+            model = self._quantize_model(model = model)
+        
+        return model
+
+    
+    def _load_transformer(self, config: ModelConfig) -> tuple:
+        """
+        Load masking transformer model
+        """
+        model     = AutoModelForMaskedLM.from_pretrained(pretrained_model_name_or_path = config.model_id,
+                                                         cache_dir                     = str(self.cache_dir),
+                                                        )
+
+        tokenizer = AutoTokenizer.from_pretrained(pretrained_model_name_or_path = config.model_id,
+                                                  cache_dir                     = str(self.cache_dir),
+                                                 )
+        
+        # Move to device
+        model     = model.to(self.device)
+
+        model.eval()
+        
+        # Apply quantization if enabled
+        if (settings.USE_QUANTIZATION and config.quantizable):
+            model = self._quantize_model(model)
+        
+        return (model, tokenizer)
+
+    
+    def _quantize_model(self, model):
+        """
+        Apply INT8 quantization to model
+        """
+        try:
+            if hasattr(torch.quantization, 'quantize_dynamic'):
+                quantized_model = torch.quantization.quantize_dynamic(model        = model,
+                                                                      qconfig_spec = {torch.nn.Linear},
+                                                                      dtype        = torch.qint8,
+                                                                     )
+                logger.info("Applied INT8 quantization to model")
+                
+                return quantized_model
+
+        except Exception as e:
+            logger.warning(f"Quantization failed: {repr(e)}, using original model")
+    
+        return model
+    
+
+    def load_pipeline(self, model_name: str, task: str) -> pipeline:
+        """
+        Load a Hugging Face pipeline
+        """
+        model_config = get_model_config(model_name = model_name)
+        
+        if not model_config:
+            raise ValueError(f"Unknown model: {model_name}")
+        
+        logger.info(f"Loading pipeline: {task} with {model_name}")
+        
+        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)},
+                       )
+        
+        return pipe
+    
+
+    def _load_spacy_model(self, config: ModelConfig):
+        """
+        Load spaCy model
+        """
+        try:
+            model = spacy.load(config.model_id)
+            logger.info(f"Loaded spaCy model: {config.model_id}")
+            
+            return model
+        
+        except OSError:
+            # Model not downloaded, install it
+            logger.info(f"Downloading spaCy model: {config.model_id}")
+            
+            subprocess.run(["python", "-m", "spacy", "download", config.model_id], check = True)
+            model = spacy.load(config.model_id)
+
+            return model
+
+    
+    def download_model(self, model_name: str) -> bool:
+        """
+        Download model without loading it into memory
+        
+        Arguments:
+        ----------
+            model_name { str } : Name from MODEL_REGISTRY
+            
+        Returns:
+        --------
+               { bool }        : True if successful, False otherwise
+        """
+        model_config = get_model_config(model_name)
+        
+        if not model_config:
+            logger.error(f"Unknown model: {model_name}")
+            return False
+        
+        if self.is_model_downloaded(model_name):
+            logger.info(f"Model already downloaded: {model_name}")
+            return True
+        
+        logger.info(f"Downloading model: {model_name} ({model_config.model_id})")
+        
+        try:
+            if model_config.model_type == ModelType.SENTENCE_TRANSFORMER:
+                SentenceTransformer(model_name_or_path = model_config.model_id,
+                                    cache_folder       = str(self.cache_dir),
+                                   )
+                                   
+            elif (model_config.model_type == ModelType.GPT):
+                GPT2LMHeadModel.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                                cache_dir                     = str(self.cache_dir),
+                                               )
+
+                GPT2Tokenizer.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                              cache_dir                     = str(self.cache_dir),
+                                             )
+
+            elif (model_config.model_type == ModelType.SEQUENCE_CLASSIFICATION):
+                AutoModelForSequenceClassification.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                                                   cache_dir                     = str(self.cache_dir),
+                                                                  )
+
+                AutoTokenizer.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                              cache_dir                     = str(self.cache_dir),
+                                             )
+
+            elif (model_config.model_type == ModelType.RULE_BASED):
+                if model_config.additional_params.get("is_spacy_model", False):
+                    subprocess.run(["python", "-m", "spacy", "download", model_config.model_id], check = True)
+
+                else:
+                    logger.warning(f"Cannot pre-download rule-based model: {model_name}")
+                    # Mark as "downloaded"
+                    return True  
+
+            else:
+                # Generic transformer models
+                AutoModelForSequenceClassification.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                                                   cache_dir                     = str(self.cache_dir),
+                                                                  )
+
+                AutoTokenizer.from_pretrained(pretrained_model_name_or_path = model_config.model_id,
+                                              cache_dir                     = str(self.cache_dir),
+                                             )
+            
+            self._update_metadata(model_name, model_config)
+            
+            logger.success(f"Successfully downloaded: {model_name}")
+            
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to download {model_name}: {repr(e)}")
+            return False
+    
+
+    def download_all_required(self) -> Dict[str, bool]:
+        """
+        Download all required models
+        
+        Returns:
+        --------
+            { dict }    : Dict mapping model names to success status
+        """
+        required_models = get_required_models()
+        results         = dict()
+        
+        logger.info(f"Downloading {len(required_models)} required models...")
+        
+        for model_name in required_models:
+            results[model_name] = self.download_model(model_name = model_name)
+        
+        success_count = sum(1 for v in results.values() if v)
+
+        logger.info(f"Downloaded {success_count}/{len(required_models)} required models")
+        
+        return results
+        
+    
+    def get_model_info(self, model_name: str) -> Optional[Dict]:
+        """
+        Get information about a model
+        """
+        return self.metadata.get(model_name)
+    
+
+    def list_downloaded_models(self) -> list:
+        """
+        List all downloaded models
+        """
+        return list(self.metadata.keys())
+    
+
+    def clear_cache(self):
+        """
+        Clear model cache
+        """
+        self.cache.clear()
+        logger.info("Model cache cleared")
+    
+
+    def unload_model(self, model_name: str):
+        """
+        Unload a specific model from cache
+        """
+        with self.cache.lock:
+            if model_name in self.cache.cache:
+                model = self.cache.cache.pop(model_name)
+                if hasattr(model, 'to'):
+                    model.to('cpu')
+                
+                del model
+                
+                if torch.cuda.is_available():
+                    torch.cuda.empty_cache()
+                
+                logger.info(f"Unloaded model: {model_name}")
+    
+
+    def get_memory_usage(self) -> Dict[str, Any]:
+        """
+        Get current memory usage statistics
+        """
+        stats = {"cached_models" : self.cache.size(),
+                 "device"        : str(self.device),
+                }
+        
+        if torch.cuda.is_available():
+            stats.update({"gpu_allocated_mb"     : torch.cuda.memory_allocated() / 1024**2,
+                          "gpu_reserved_mb"      : torch.cuda.memory_reserved() / 1024**2,
+                          "gpu_max_allocated_mb" : torch.cuda.max_memory_allocated() / 1024**2,
+                        })
+        
+        return stats
+
+    
+    def optimize_memory(self):
+        """
+        Optimize memory usage
+        """
+        logger.info("Optimizing memory...")
+        
+        # Clear unused cached models
+        self.cache.clear()
+        
+        # Force garbage collection
+        gc.collect()
+        
+        # Clear CUDA cache if available
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        
+        logger.info("Memory optimization complete")
+        logger.info(f"Memory usage: {self.get_memory_usage()}")
+
+
+
+# Singleton instance
+_model_manager_instance : Optional[ModelManager] = None
+_manager_lock                                    = threading.Lock()
+
+
+def get_model_manager() -> ModelManager:
+    """
+    Get singleton ModelManager instance
+    """
+    global _model_manager_instance
+    
+    if _model_manager_instance is None:
+        with _manager_lock:
+            if _model_manager_instance is None:
+                _model_manager_instance = ModelManager()
+    
+    return _model_manager_instance
+
+
+
+
+# Export
+__all__ = ["ModelManager",
+           "ModelCache",
+           "get_model_manager",
+          ]

models/model_registry.py

@@ -0,0 +1,270 @@
+# DEPENDENCIES
+import gc
+import torch
+import threading
+from typing import Any
+from typing import Dict
+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.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
+    
+    Complements ModelManager by adding:
+    - Usage analytics
+    - Performance monitoring  
+    - Model dependency tracking
+    - Health checks (without duplicating ModelManager functionality)
+    """
+    def __init__(self):
+        self.usage_stats          : Dict[str, ModelUsageStats]  = dict()
+        self.dependency_graph     : Dict[str, List[str]]        = dict()
+        self.performance_metrics  : Dict[str, Dict[str, float]] = dict()
+        self.lock                                               = threading.RLock()
+        
+        # Initialize from MODEL_REGISTRY
+        self._initialize_registry()
+        
+        logger.info("ModelRegistry initialized for usage tracking")
+    
+
+    def _initialize_registry(self):
+        """
+        Initialize registry with all known models
+        """
+        for model_name in MODEL_REGISTRY.keys():
+            self.usage_stats[model_name] = ModelUsageStats(model_name               = model_name,
+                                                           load_count               = 0,
+                                                           last_used                = datetime.now(),
+                                                           total_usage_time_seconds = 0.0,
+                                                           avg_usage_time_seconds   = 0.0,
+                                                          )
+    
+
+    def record_model_usage(self, model_name: str, usage_time_seconds: float = 0.0):
+        """
+        Record that a model was used
+        
+        Arguments:
+        ----------
+            model_name          { str }  : Name of the model used
+
+            usage_time_seconds { float } : How long the model was used (if available)
+        """
+        with self.lock:
+            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(),
+                                                               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()
+            
+            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
+            
+            logger.debug(f"Recorded usage for {model_name} (count: {stats.load_count})")
+    
+
+    def get_usage_stats(self, model_name: str) -> Optional[ModelUsageStats]:
+        """
+        Get usage statistics for a model
+        """
+        with self.lock:
+            return self.usage_stats.get(model_name)
+    
+
+    def get_most_used_models(self, top_k: int = 5) -> List[ModelUsageStats]:
+        """
+        Get most frequently used models
+        """
+        with self.lock:
+            sorted_models = sorted(self.usage_stats.values(), 
+                                   key     = lambda x: x.load_count, 
+                                   reverse = True,
+                                  )
+
+            return sorted_models[:top_k]
+    
+
+    def record_performance_metric(self, model_name: str, metric_name: str, value: float):
+        """
+        Record performance metrics for a model
+        
+        Arguments:
+        ----------
+            model_name    { str }  : Name of the model
+
+            metric_name  { float } : Name of the metric (e.g., "inference_time_ms", "memory_peak_mb")
+            
+            value         { str }  : Metric value
+        """
+        with self.lock:
+            if model_name not in self.performance_metrics:
+                self.performance_metrics[model_name] = {}
+            
+            self.performance_metrics[model_name][metric_name] = value
+    
+
+    def get_performance_metrics(self, model_name: str) -> Dict[str, float]:
+        """
+        Get performance metrics for a model
+        """
+        with self.lock:
+            return self.performance_metrics.get(model_name, {})
+    
+
+    def add_dependency(self, model_name: str, depends_on: List[str]):
+        """
+        Add dependency information for a model
+        
+        Arguments:
+        ----------
+            model_name  { str }  : The model that has dependencies
+
+            depends_on  { list } : List of model names this model depends on
+        """
+        with self.lock:
+            self.dependency_graph[model_name] = depends_on
+    
+
+    def get_dependencies(self, model_name: str) -> List[str]:
+        """
+        Get dependencies for a model
+        """
+        with self.lock:
+            return self.dependency_graph.get(model_name, [])
+    
+
+    def get_dependent_models(self, model_name: str) -> List[str]:
+        """
+        Get models that depend on the specified model
+        """
+        with self.lock:
+            dependents = []
+            
+            for user_model, dependencies in self.dependency_graph.items():
+                if model_name in dependencies:
+                    dependents.append(user_model)
+            
+            return dependents
+    
+
+    def generate_usage_report(self) -> Dict[str, Any]:
+        """
+        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]
+            
+            return {"timestamp"           : datetime.now().isoformat(),
+                    "summary"             : {"total_models_tracked" : len(self.usage_stats),
+                                             "active_models"        : len(active_models),
+                                             "total_usage_count"    : total_usage,
+                                            },
+                    "most_used_models"    : [stats.to_dict() for stats in self.get_most_used_models(top_k = 10)],
+                    "performance_metrics" : {model: metrics for model, metrics in self.performance_metrics.items()},
+                    "dependency_graph"    : self.dependency_graph
+                   }
+    
+
+    def reset_usage_stats(self, model_name: Optional[str] = None):
+        """
+        Reset usage statistics for a model or all models
+        
+        Arguments:
+        ----------
+            model_name { str } : Specific model to reset, or None for all models
+        """
+        with self.lock:
+            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(),
+                                                                   total_usage_time_seconds = 0.0,
+                                                                   avg_usage_time_seconds   = 0.0,
+                                                                  )
+
+                    logger.info(f"Reset usage stats for {model_name}")
+            
+            else:
+                self._initialize_registry()
+                logger.info("Reset usage stats for all models")
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        with self.lock:
+            self.usage_stats.clear()
+            self.performance_metrics.clear()
+            self.dependency_graph.clear()
+            
+            logger.info("ModelRegistry cleanup completed")
+
+
+# Singleton instance
+_model_registry_instance: Optional[ModelRegistry] = None
+_registry_lock                                    = threading.Lock()
+
+
+def get_model_registry() -> ModelRegistry:
+    """
+    Get singleton ModelRegistry instance
+    """
+    global _model_registry_instance
+    
+    if _model_registry_instance is None:
+        with _registry_lock:
+            if _model_registry_instance is None:
+                _model_registry_instance = ModelRegistry()
+    
+    return _model_registry_instance
+
+
+# Export
+__all__ = ["ModelRegistry",
+           "ModelUsageStats", 
+           "get_model_registry"
+          ]

processors/__init__.py

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,843 @@
+# DEPENDENCIES
+import io
+import os
+import mimetypes
+from typing import Any
+from typing import Dict
+from typing import List
+from pathlib import Path
+from typing import Tuple
+from loguru import logger
+from typing import Optional 
+from dataclasses import dataclass
+
+
+# Document processing libraries
+try:
+    import PyPDF2
+    import pdfplumber
+    PDF_AVAILABLE = True
+except ImportError:
+    logger.warning("PDF libraries not available. Install: pip install PyPDF2 pdfplumber")
+    PDF_AVAILABLE = False
+
+try:
+    from docx import Document as DocxDocument
+    DOCX_AVAILABLE = True
+except ImportError:
+    logger.warning("python-docx not available. Install: pip install python-docx")
+    DOCX_AVAILABLE = False
+
+try:
+    import chardet
+    CHARDET_AVAILABLE = True
+except ImportError:
+    logger.warning("chardet not available. Install: pip install chardet")
+    CHARDET_AVAILABLE = False
+
+try:
+    from bs4 import BeautifulSoup
+    BS4_AVAILABLE = True
+except ImportError:
+    logger.warning("BeautifulSoup not available. Install: pip install beautifulsoup4")
+    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
+
+    Supported Formats:
+    - Plain text (.txt, .md, .log)
+    - 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, prefer_pdfplumber: bool = True, extract_metadata: bool = True):
+        """
+        Initialize document extractor
+        
+        Arguments:
+        ----------
+            max_file_size      : Maximum file size in bytes
+
+            prefer_pdfplumber  : Use pdfplumber over PyPDF2 (better quality)
+            
+            extract_metadata   : Extract document metadata
+        """
+        self.max_file_size      = max_file_size
+        self.prefer_pdfplumber  = prefer_pdfplumber
+        self.extract_metadata   = extract_metadata
+        
+        logger.info(f"DocumentExtractor initialized (max_size={max_file_size/1024/1024:.1f}MB)")
+    
+
+    def extract(self, file_path: str) -> ExtractedDocument:
+        """
+        Extract text from document
+        
+        Arguments:
+        ----------
+            file_path     { str } : Path to the document file
+            
+        Returns:
+        --------
+            { ExtractedDocument } : ExtractedDocument object with extracted text and metadata
+        """
+        try:
+            file_path         = Path(file_path)
+            
+            # Validate file
+            validation_result = self._validate_file(file_path)
+
+            if not validation_result[0]:
+                return self._create_error_result(file_path = str(file_path),
+                                                 error     = validation_result[1],
+                                                )
+            
+            # Get file info
+            file_size = file_path.stat().st_size
+            file_ext  = file_path.suffix.lower()
+            
+            # Route to appropriate extractor
+            if (file_ext in self.TEXT_EXTENSIONS):
+                result = self._extract_text_file(file_path)
+            
+            elif (file_ext == '.pdf'):
+                result = self._extract_pdf(file_path)
+            
+            elif (file_ext in {'.docx', '.doc'}):
+                result = self._extract_word(file_path)
+            
+            elif (file_ext == '.rtf'):
+                result = self._extract_rtf(file_path)
+            
+            elif (file_ext in {'.html', '.htm'}):
+                result = self._extract_html(file_path)
+            
+            else:
+                return self._create_error_result(file_path = str(file_path),
+                                                 error     = f"Unsupported file type: {file_ext}",
+                                                )
+            
+            # Add common metadata
+            result.file_path       = str(file_path)
+            result.file_size_bytes = file_size
+            
+            logger.info(f"Extracted {len(result.text)} chars from {file_path.name}")
+            return result
+            
+        except Exception as e:
+            logger.error(f"Error extracting document: {repr(e)}")
+            return self._create_error_result(file_path = str(file_path) if file_path else None,
+                                             error     = repr(e),
+                                            )
+    
+
+    def extract_from_bytes(self, file_bytes: bytes, filename: str, mime_type: Optional[str] = None) -> ExtractedDocument:
+        """
+        Extract text from bytes (for file uploads)
+        
+        Arguments:
+        ----------
+            file_bytes : File content as bytes
+
+            filename   : Original filename
+            
+            mime_type  : MIME type (optional)
+            
+        Returns:
+        --------
+            ExtractedDocument object
+        """
+        try:
+            # Determine file type
+            file_ext = Path(filename).suffix.lower()
+            
+            if file_ext not in self.SUPPORTED_EXTENSIONS:
+                return self._create_error_result(file_path = filename,
+                                                 error     = f"Unsupported file type: {file_ext}",
+                                                )
+            
+            # Check size
+            if (len(file_bytes) > self.max_file_size):
+                return self._create_error_result(file_path = filename,
+                                                 error     = f"File too large: {len(file_bytes)/1024/1024:.1f}MB"
+                                                )
+            
+            # Route to appropriate extractor
+            if (file_ext in self.TEXT_EXTENSIONS):
+                result = self._extract_text_bytes(file_bytes, filename)
+            
+            elif (file_ext == '.pdf'):
+                result = self._extract_pdf_bytes(file_bytes, filename)
+            
+            elif (file_ext in {'.docx', '.doc'}):
+                result = self._extract_word_bytes(file_bytes, filename)
+            
+            elif (file_ext == '.rtf'):
+                result = self._extract_rtf_bytes(file_bytes, filename)
+            
+            elif (file_ext in {'.html', '.htm'}):
+                result = self._extract_html_bytes(file_bytes, filename)
+            
+            else:
+                return self._create_error_result(file_path = filename,
+                                                 error     = f"Unsupported file type: {file_ext}"
+                                                )
+            
+            result.file_path       = filename
+            result.file_size_bytes = len(file_bytes)
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Error extracting from bytes: {e}")
+            return self._create_error_result(file_path = filename,
+                                             error     = repr(e),
+                                            )
+    
+    
+    def _extract_text_file(self, file_path: Path) -> ExtractedDocument:
+        """
+        Extract text from plain text files
+        """
+        warnings = list()
+        
+        try:
+            # Try to detect encoding
+            encoding = 'utf-8'
+            
+            if CHARDET_AVAILABLE:
+                with open(file_path, 'rb') as f:
+                    raw_data = f.read()
+                    detected = chardet.detect(raw_data)
+                    if detected['confidence'] > 0.7:
+                        encoding = detected['encoding']
+                        logger.debug(f"Detected encoding: {encoding} (confidence: {detected['confidence']})")
+            
+            # Read file with detected encoding
+            try:
+                with open(file_path, 'r', encoding=encoding) as f:
+                    text = f.read()
+
+            except UnicodeDecodeError:
+                # Fallback to latin-1 (never fails)
+                warnings.append(f"Failed to decode with {encoding}, using latin-1")
+                with open(file_path, 'r', encoding = 'latin-1') as f:
+                    text = f.read()
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = str(file_path),
+                                     file_type         = file_path.suffix,
+                                     file_size_bytes   = file_path.stat().st_size,
+                                     page_count        = 1,
+                                     extraction_method = 'plain_text',
+                                     metadata          = {'encoding': encoding},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = str(file_path), 
+                                             error     = repr(e),
+                                            )
+    
+
+    def _extract_text_bytes(self, file_bytes: bytes, filename: str) -> ExtractedDocument:
+        """
+        Extract text from bytes
+        """
+        warnings = list()
+        
+        try:
+            # Detect encoding
+            encoding = 'utf-8'
+            
+            if CHARDET_AVAILABLE:
+                detected = chardet.detect(file_bytes)
+                if (detected['confidence'] > 0.7):
+                    encoding = detected['encoding']
+            
+            # Decode
+            try:
+                text = file_bytes.decode(encoding)
+
+            except UnicodeDecodeError:
+                warnings.append(f"Failed to decode with {encoding}, using latin-1")
+                text = file_bytes.decode('latin-1')
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = filename,
+                                     file_type         = Path(filename).suffix,
+                                     file_size_bytes   = len(file_bytes),
+                                     page_count        = 1,
+                                     extraction_method = 'plain_text',
+                                     metadata          = {'encoding': encoding},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = filename, 
+                                             error     = repr(e),
+                                            )
+    
+
+    def _extract_pdf(self, file_path: Path) -> ExtractedDocument:
+        """
+        Extract text from PDF files
+        """
+        if not PDF_AVAILABLE:
+            return self._create_error_result(file_path = (file_path),
+                                             error     = "PDF libraries not installed",
+                                            )
+        
+        warnings   = list()
+        text       = ""
+        page_count = 0
+        metadata   = dict()
+        
+        # Try pdfplumber first (better quality)
+        if self.prefer_pdfplumber:
+            try:
+                with pdfplumber.open(file_path) as pdf:
+                    page_count = len(pdf.pages)
+                    metadata   = pdf.metadata or {}
+                    
+                    for page in pdf.pages:
+                        page_text = page.extract_text()
+                        
+                        if page_text:
+                            text += page_text + "\n\n"
+                
+                if text.strip():
+                    return ExtractedDocument(text              = text.strip(),
+                                             file_path         = str(file_path),
+                                             file_type         = '.pdf',
+                                             file_size_bytes   = file_path.stat().st_size,
+                                             page_count        = page_count,
+                                             extraction_method = 'pdfplumber',
+                                             metadata          = metadata,
+                                             is_success        = True,
+                                             error_message     = None,
+                                             warnings          = warnings,
+                                            )
+            except Exception as e:
+                warnings.append(f"pdfplumber failed: {repr(e)}, trying PyPDF2")
+        
+        # Fallback to PyPDF2
+        try:
+            with open(file_path, 'rb') as f:
+                reader     = PyPDF2.PdfReader(f)
+                page_count = len(reader.pages)
+                
+                if self.extract_metadata:
+                    metadata = reader.metadata or {}
+                
+                for page in reader.pages:
+                    page_text = page.extract_text()
+                    
+                    if page_text:
+                        text += page_text + "\n\n"
+            
+            if not text.strip():
+                warnings.append("PDF appears to be image-based or encrypted")
+            
+            return ExtractedDocument(text              = text.strip(),
+                                     file_path         = str(file_path),
+                                     file_type         = '.pdf',
+                                     file_size_bytes   = file_path.stat().st_size,
+                                     page_count        = page_count,
+                                     extraction_method = 'PyPDF2',
+                                     metadata          = metadata,
+                                     is_success        = bool(text.strip()),
+                                     error_message     = None if text.strip() else "No text extracted",
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = str(file_path), 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_pdf_bytes(self, file_bytes: bytes, filename: str) -> ExtractedDocument:
+        """
+        Extract text from PDF bytes
+        """
+        if not PDF_AVAILABLE:
+            return self._create_error_result(file_path = filename, 
+                                             error     = "PDF libraries not installed",
+                                            )
+        
+        warnings   = list()
+        text       = ""
+        page_count = 0
+        metadata   = dict()
+        
+        try:
+            # Try pdfplumber
+            if self.prefer_pdfplumber:
+                try:
+                    with pdfplumber.open(io.BytesIO(file_bytes)) as pdf:
+                        page_count = len(pdf.pages)
+                        metadata   = pdf.metadata or {}
+                        
+                        for page in pdf.pages:
+                            page_text = page.extract_text()
+                            
+                            if page_text:
+                                text += page_text + "\n\n"
+                    
+                    if text.strip():
+                        return ExtractedDocument(text              = text.strip(),
+                                                 file_path         = filename,
+                                                 file_type         = '.pdf',
+                                                 file_size_bytes   = len(file_bytes),
+                                                 page_count        = page_count,
+                                                 extraction_method = 'pdfplumber',
+                                                 metadata          = metadata,
+                                                 is_success        = True,
+                                                 error_message     = None,
+                                                 warnings          = warnings,
+                                                )
+                except Exception as e:
+                    warnings.append(f"pdfplumber failed: {repr(e)}, trying PyPDF2")
+            
+            # Fallback to PyPDF2
+            reader     = PyPDF2.PdfReader(io.BytesIO(file_bytes))
+            page_count = len(reader.pages)
+            
+            for page in reader.pages:
+                page_text = page.extract_text()
+                
+                if page_text:
+                    text += page_text + "\n\n"
+            
+            return ExtractedDocument(text              = text.strip(),
+                                     file_path         = filename,
+                                     file_type         = '.pdf',
+                                     file_size_bytes   = len(file_bytes),
+                                     page_count        = page_count,
+                                     extraction_method = 'PyPDF2',
+                                     metadata          = metadata,
+                                     is_success        = bool(text.strip()),
+                                     error_message     = None if text.strip() else "No text extracted",
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = filename, 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_word(self, file_path: Path) -> ExtractedDocument:
+        """
+        Extract text from Word documents
+        """
+        if not DOCX_AVAILABLE:
+            return self._create_error_result(file_path = str(file_path),
+                                             error     = "python-docx not installed",
+                                            )
+        
+        try:
+            doc        = DocxDocument(file_path)
+            
+            # Extract text from paragraphs
+            paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+            text       = "\n\n".join(paragraphs)
+            
+            # Extract metadata
+            metadata   = dict()
+
+            if self.extract_metadata:
+                core_props = doc.core_properties
+                metadata   = {'author'   : core_props.author,
+                              'title'    : core_props.title,
+                              'subject'  : core_props.subject,
+                              'created'  : str(core_props.created) if core_props.created else None,
+                              'modified' : str(core_props.modified) if core_props.modified else None,
+                            }
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = str(file_path),
+                                     file_type         = file_path.suffix,
+                                     file_size_bytes   = file_path.stat().st_size,
+                                     page_count        = len(paragraphs),  # Approximate
+                                     extraction_method = 'python-docx',
+                                     metadata          = metadata,
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = [],
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = str(file_path), 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_word_bytes(self, file_bytes: bytes, filename: str) -> ExtractedDocument:
+        """
+        Extract text from Word document bytes
+        """
+        if not DOCX_AVAILABLE:
+            return self._create_error_result(file_path = filename, 
+                                             error     = "python-docx not installed",
+                                            )
+        
+        try:
+            doc        = DocxDocument(io.BytesIO(file_bytes))
+            
+            paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+            text       = "\n\n".join(paragraphs)
+            
+            metadata   = dict()
+
+            if self.extract_metadata:
+                core_props = doc.core_properties
+                metadata   = {'author' : core_props.author,
+                              'title'  : core_props.title,
+                             }
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = filename,
+                                     file_type         = Path(filename).suffix,
+                                     file_size_bytes   = len(file_bytes),
+                                     page_count        = len(paragraphs),
+                                     extraction_method = 'python-docx',
+                                     metadata          = metadata,
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = [],
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = filename, 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_rtf(self, file_path: Path) -> ExtractedDocument:
+        """
+        Extract text from RTF files (basic implementation)
+        """
+        warnings = ["RTF extraction is basic, formatting may be lost"]
+        
+        try:
+            with open(file_path, 'r', encoding='latin-1') as f:
+                content = f.read()
+            
+            # Very basic RTF stripping (remove control words)
+            text = re.sub(r'\\[a-z]+\d*\s?', '', content)
+            text = re.sub(r'[{}]', '', text)
+            text = text.strip()
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = str(file_path),
+                                     file_type         = '.rtf',
+                                     file_size_bytes   = file_path.stat().st_size,
+                                     page_count        = 1,
+                                     extraction_method = 'basic_rtf',
+                                     metadata          = {},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = str(file_path), 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_rtf_bytes(self, file_bytes: bytes, filename: str) -> ExtractedDocument:
+        """
+        Extract text from RTF bytes
+        """
+        warnings = ["RTF extraction is basic, formatting may be lost"]
+        
+        try:
+            content = file_bytes.decode('latin-1')
+            
+            # Basic RTF stripping
+            text    = re.sub(r'\\[a-z]+\d*\s?', '', content)
+            text    = re.sub(r'[{}]', '', text)
+            text    = text.strip()
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = filename,
+                                     file_type         = '.rtf',
+                                     file_size_bytes   = len(file_bytes),
+                                     page_count        = 1,
+                                     extraction_method = 'basic_rtf',
+                                     metadata          = {},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = warnings,
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = filename, 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_html(self, file_path: Path) -> ExtractedDocument:
+        """
+        Extract text from HTML files
+        """
+        if not BS4_AVAILABLE:
+            return self._create_error_result(file_path = str(file_path),
+                                             error     = "BeautifulSoup not installed",
+                                            )
+        
+        try:
+            with open(file_path, 'r', encoding = 'utf-8', errors = 'ignore') as f:
+                content = f.read()
+            
+            soup = BeautifulSoup(content, 'html.parser')
+            
+            # Remove script and style elements
+            for script in soup(["script", "style"]):
+                script.decompose()
+            
+            # Get text
+            text  = soup.get_text(separator='\n')
+            
+            # Clean up whitespace
+            lines = (line.strip() for line in text.splitlines())
+            text  = '\n'.join(line for line in lines if line)
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = str(file_path),
+                                     file_type         = file_path.suffix,
+                                     file_size_bytes   = file_path.stat().st_size,
+                                     page_count        = 1,
+                                     extraction_method = 'beautifulsoup',
+                                     metadata          = {},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = [],
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = str(file_path), 
+                                             error     = repr(e),
+                                            )
+
+    
+    def _extract_html_bytes(self, file_bytes: bytes, filename: str) -> ExtractedDocument:
+        """
+        Extract text from HTML bytes
+        """
+        if not BS4_AVAILABLE:
+            return self._create_error_result(file_path = filename, 
+                                             error     = "BeautifulSoup not installed",
+                                            )
+        
+        try:
+            content = file_bytes.decode('utf-8', errors = 'ignore')
+            
+            soup    = BeautifulSoup(content, 'html.parser')
+            
+            for script in soup(["script", "style"]):
+                script.decompose()
+            
+            text  = soup.get_text(separator='\n')
+            lines = (line.strip() for line in text.splitlines())
+            text  = '\n'.join(line for line in lines if line)
+            
+            return ExtractedDocument(text              = text,
+                                     file_path         = filename,
+                                     file_type         = Path(filename).suffix,
+                                     file_size_bytes   = len(file_bytes),
+                                     page_count        = 1,
+                                     extraction_method = 'beautifulsoup',
+                                     metadata          = {},
+                                     is_success        = True,
+                                     error_message     = None,
+                                     warnings          = [],
+                                    )
+            
+        except Exception as e:
+            return self._create_error_result(file_path = filename,
+                                             error     = repr(e),
+                                            )
+
+    
+    def _validate_file(self, file_path: Path) -> Tuple[bool, Optional[str]]:
+        """
+        Validate file before extraction
+        """
+        # Check if file exists
+        if not file_path.exists():
+            return False, f"File not found: {file_path}"
+        
+        # Check if it's a file
+        if not file_path.is_file():
+            return False, f"Not a file: {file_path}"
+        
+        # Check file size
+        file_size = file_path.stat().st_size
+        if (file_size > self.max_file_size):
+            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):
+            return False, f"Unsupported file type: {file_path.suffix}"
+        
+        return True, None
+    
+
+    def _create_error_result(self, file_path: Optional[str], error: str) -> ExtractedDocument:
+        """
+        Create error result
+        """
+        return ExtractedDocument(text              = "",
+                                 file_path         = file_path,
+                                 file_type         = Path(file_path).suffix if file_path else "unknown",
+                                 file_size_bytes   = 0,
+                                 page_count        = 0,
+                                 extraction_method = "failed",
+                                 metadata          = {},
+                                 is_success        = False,
+                                 error_message     = error,
+                                 warnings          = [],
+                                )
+
+
+# Convenience Functions
+
+def extract_text(file_path: str, **kwargs) -> ExtractedDocument:
+    """
+    Quick text extraction with default settings
+    
+    Arguments:
+    ----------
+        file_path : Path to document
+        **kwargs  : Override settings
+        
+    Returns:
+    --------
+        ExtractedDocument object
+    """
+    extractor = DocumentExtractor(**kwargs)
+    return extractor.extract(file_path)
+
+
+def extract_from_upload(file_bytes: bytes, filename: str, **kwargs) -> ExtractedDocument:
+    """
+    Extract text from uploaded file
+    
+    Arguments:
+    ----------
+        file_bytes : File content as bytes
+        filename   : Original filename
+        **kwargs   : Override settings
+        
+    Returns:
+    --------
+        ExtractedDocument object
+    """
+    extractor = DocumentExtractor(**kwargs)
+    return extractor.extract_from_bytes(file_bytes, filename)
+
+
+# Export
+__all__ = ['DocumentExtractor',
+           'ExtractedDocument',
+           'extract_text',
+           'extract_from_upload',
+          ]
+
+
+# Testing 
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) > 1:
+        # Test with provided file
+        test_file = sys.argv[1]
+        print(f"Testing extraction on: {test_file}")
+        print("=" * 70)
+        
+        result = extract_text(test_file)
+        
+        print(f"Success: {result.is_success}")
+        print(f"File type: {result.file_type}")
+        print(f"Pages: {result.page_count}")
+        print(f"Method: {result.extraction_method}")
+        print(f"Text length: {len(result.text)} chars")
+        
+        if result.warnings:
+            print(f"Warnings: {result.warnings}")
+        
+        if result.error_message:
+            print(f"Error: {result.error_message}")
+        
+        if result.text:
+            print(f"\nFirst 500 chars:")
+            print("-" * 70)
+            print(result.text[:500])
+    else:
+        print("Usage: python document_extractor.py <file_path>")
+        print("\nSupported formats:")
+        for ext in sorted(DocumentExtractor.SUPPORTED_EXTENSIONS):
+            print(f"  {ext}")

processors/domain_classifier.py

@@ -0,0 +1,302 @@
+# DEPENDENCIES
+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 models.model_manager import get_model_manager
+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"],
+                    }
+    
+
+    def __init__(self):
+        self.model_manager       = get_model_manager()
+        self.primary_classifier  = None
+        self.fallback_classifier = None
+        self.is_initialized      = False
+
+    
+    def initialize(self) -> bool:
+        """
+        Initialize the domain classifier with zero-shot models
+        """
+        try:
+            logger.info("Initializing domain classifier...")
+            
+            # Load primary domain classifier (zero-shot)
+            self.primary_classifier = self.model_manager.load_model(model_name = "domain_classifier")
+            
+            # Load fallback classifier
+            try:
+                self.fallback_classifier = self.model_manager.load_model(model_name = "domain_classifier_fallback")
+                logger.info("Fallback classifier loaded successfully")
+
+            except Exception as e:
+                logger.warning(f"Could not load fallback classifier: {repr(e)}")
+                self.fallback_classifier = None
+            
+            self.is_initialized = True
+            logger.success("Domain classifier initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize domain classifier: {repr(e)}")
+            return False
+    
+
+    def classify(self, text: str, top_k: int = 2, min_confidence: float = 0.3) -> DomainPrediction:
+        """
+        Classify text into domain using zero-shot classification
+        
+        Arguments:
+        ----------
+            text            { str }  : Input text
+
+            top_k           { int }  : Number of top domains to consider
+            
+            min_confidence { float } : Minimum confidence threshold
+            
+        Returns:
+        --------
+            { DomainPrediction }     : DomainPrediction object
+        """
+        if not self.is_initialized:
+            logger.warning("Domain classifier not initialized, initializing now...")
+            if not self.initialize():
+                return self._get_default_prediction()
+        
+        try:
+            # First try with primary classifier
+            primary_result = self._classify_with_model(text       = text, 
+                                                       classifier = self.primary_classifier, 
+                                                       model_type = "primary",
+                                                      )
+            
+            # If primary result meets confidence threshold, return it
+            if (primary_result.confidence >= min_confidence):
+                return primary_result
+            
+            # If primary is low confidence but we have fallback, try fallback
+            if self.fallback_classifier:
+                logger.info("Primary classifier low confidence, trying fallback model...")
+                fallback_result = self._classify_with_model(text       = text, 
+                                                            classifier = self.fallback_classifier, 
+                                                            model_type = "fallback",
+                                                           )
+                
+                # Use fallback if it has higher confidence
+                if fallback_result.confidence > primary_result.confidence:
+                    return fallback_result
+            
+            # Return primary result even if low confidence
+            return primary_result
+            
+        except Exception as e:
+            logger.error(f"Error in domain classification: {repr(e)}")
+            
+            # Try fallback classifier if primary failed
+            if self.fallback_classifier:
+                try:
+                    logger.info("Trying fallback classifier after primary failure...")
+                    return self._classify_with_model(text       = text, 
+                                                     classifier = self.fallback_classifier, 
+                                                     model_type = "fallback",
+                                                    )
+                
+                except Exception as fallback_error:
+                    logger.error(f"Fallback classifier also failed: {repr(fallback_error)}")
+            
+            # Both models failed, return default
+            return self._get_default_prediction()
+    
+
+    def _classify_with_model(self, text: str, classifier, model_type: str) -> DomainPrediction:
+        """
+        Classify using a zero-shot classification model
+        """
+        # Preprocess text
+        processed_text = self._preprocess_text(text)
+        
+        # Get all candidate labels
+        all_labels      = list()
+        label_to_domain = dict()
+
+        for domain, labels in self.DOMAIN_LABELS.items():
+            # Use the first label as the primary one for this domain
+            primary_label = labels[0]
+            all_labels.append(primary_label)
+            label_to_domain[primary_label] = domain
+        
+        # Perform zero-shot classification
+        result = classifier(processed_text,
+                            candidate_labels    = all_labels,
+                            multi_label         = False,
+                            hypothesis_template = "This text is about {}.",
+                           )
+        
+        # Convert to domain scores
+        domain_scores = dict()
+
+        for label, score in zip(result['labels'], result['scores']):
+            domain     = label_to_domain[label]
+            domain_key = domain.value
+
+            if (domain_key not in domain_scores):
+                domain_scores[domain_key] = list()
+
+            domain_scores[domain_key].append(score)
+        
+        # Average scores for each domain
+        avg_domain_scores                 = {domain: sum(scores) / len(scores) for domain, scores in domain_scores.items()}
+        
+        # Sort by score
+        sorted_domains                    = sorted(avg_domain_scores.items(), key = lambda x: x[1], reverse = True)
+        
+        # Get primary and secondary domains
+        primary_domain_str, primary_score = sorted_domains[0]
+        primary_domain                    = Domain(primary_domain_str)
+        
+        secondary_domain                  = None
+        secondary_score                   = 0.0
+
+        if ((len(sorted_domains) > 1) and (sorted_domains[1][1] >= 0.1)):
+            secondary_domain = Domain(sorted_domains[1][0])
+            secondary_score  = sorted_domains[1][1]
+        
+        # Calculate confidence
+        confidence = primary_score
+        
+        # If we have mixed domains with close scores, adjust confidence
+        if (secondary_domain and (primary_score < 0.7) and (secondary_score > 0.3)):
+            score_ratio = secondary_score / primary_score
+            
+            # Secondary is at least 60% of primary
+            if (score_ratio > 0.6):  
+                # Lower confidence for mixed domains
+                confidence = (primary_score + secondary_score) / 2 * 0.8
+                logger.info(f"Mixed domain detected: {primary_domain.value} + {secondary_domain.value}, will use interpolated thresholds")
+        
+        # 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  
+        
+        logger.info(f"{model_type.capitalize()} model classified domain: {primary_domain.value} (confidence: {confidence:.3f})")
+        
+        return DomainPrediction(primary_domain   = primary_domain,
+                                secondary_domain = secondary_domain,
+                                confidence       = confidence,
+                                domain_scores    = avg_domain_scores,
+                               )
+    
+
+    def _preprocess_text(self, text: str) -> str:
+        """
+        Preprocess text for classification
+        """
+        # Truncate to reasonable length
+        words = text.split()
+        if (len(words) > 400):
+            text = ' '.join(words[:400])
+        
+        # Clean up text
+        text = text.strip()
+        if not text:
+            return "general content"
+        
+        return text
+    
+
+    def _get_default_prediction(self) -> DomainPrediction:
+        """
+        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},
+                               )
+    
+
+    def get_adaptive_thresholds(self, domain_prediction: DomainPrediction):
+        """
+        Get adaptive thresholds based on domain prediction
+        """
+        if ((domain_prediction.confidence > 0.7) and (not domain_prediction.secondary_domain)):
+            return get_threshold_for_domain(domain_prediction.primary_domain)
+        
+        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)
+            
+            if (primary_score + secondary_score > 0):
+                weight1 = primary_score / (primary_score + secondary_score)
+            
+            else:
+                weight1 = domain_prediction.confidence
+                
+            return interpolate_thresholds(domain1  = domain_prediction.primary_domain,
+                                          domain2  = domain_prediction.secondary_domain,
+                                          weight1  = weight1,
+                                         )
+        
+        if (domain_prediction.confidence < 0.6):
+            return interpolate_thresholds(domain1 = domain_prediction.primary_domain,
+                                          domain2 = Domain.GENERAL,
+                                          weight1 = domain_prediction.confidence,
+                                         )
+        
+        return get_threshold_for_domain(domain_prediction.primary_domain)
+    
+    
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.primary_classifier  = None
+        self.fallback_classifier = None
+        self.is_initialized      = False
+
+
+
+# Export
+__all__ = ["DomainClassifier",
+           "DomainPrediction",
+          ]

processors/language_detector.py

@@ -0,0 +1,643 @@
+# DEPENDENCIES
+import re
+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 dataclasses import dataclass
+
+
+# Try to import optional libraries
+try:
+    import langdetect
+    from langdetect import detect, detect_langs, DetectorFactory
+    # Seed for reproducibility
+    DetectorFactory.seed = 0
+    LANGDETECT_AVAILABLE = True
+except ImportError:
+    logger.warning("langdetect not available. Install: pip install langdetect")
+    LANGDETECT_AVAILABLE = False
+
+try:
+    from models.model_manager import get_model_manager
+    MODEL_MANAGER_AVAILABLE = True
+except ImportError:
+    logger.warning("model_manager not available, using fallback methods")
+    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.)
+
+    Supported Languages:
+    - 100+ languages via XLM-RoBERTa
+    - High accuracy for major languages (English, Spanish, French, German, Chinese, etc.)
+    """
+    # 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",
+                      }
+    
+    # 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)],
+                      }
+    
+
+    def __init__(self, use_model: bool = True, min_confidence: float = 0.5):
+        """
+        Initialize language detector
+        
+        Arguments:
+        ----------
+            use_model       : Use ML model for detection (more accurate)
+
+            min_confidence  : Minimum confidence threshold
+        """
+        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
+        
+        logger.info(f"LanguageDetector initialized (use_model={self.use_model})")
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize the ML model (if using)
+        
+        Returns:
+        --------
+            { bool } : True if successful, False otherwise
+        """
+        if not self.use_model:
+            self.is_initialized = True
+            return True
+        
+        try:
+            logger.info("Initializing language detection model...")
+            
+            self.model_manager  = get_model_manager()
+            self.classifier     = self.model_manager.load_pipeline(model_name = "language_detector",
+                                                                   task       = "text-classification",
+                                                                  )
+            
+            self.is_initialized = True
+            logger.success("Language detector initialized successfully")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to initialize language detector: {repr(e)}")
+            logger.warning("Falling back to langdetect library")
+            self.use_model      = False
+            self.is_initialized = True
+            return False
+    
+
+    def detect(self, text: str, **kwargs) -> LanguageDetectionResult:
+        """
+        Detect language of input text
+        
+        Arguments:
+        ----------
+            text     { str } : Input text to analyze
+
+            **kwargs         : Additional options
+            
+        Returns:
+        --------
+            LanguageDetectionResult object
+        """
+        warnings = list()
+        
+        # Validate input
+        if not text or not isinstance(text, str):
+            return self._create_unknown_result(text     = "",
+                                               warnings = ["Empty or invalid text"],
+                                              )
+        
+        # Clean text for analysis
+        cleaned_text = self._clean_text(text)
+        char_count   = len(cleaned_text)
+        word_count   = len(cleaned_text.split())
+        
+        # Check minimum length
+        if (char_count < self.MIN_TEXT_LENGTH):
+            warnings.append(f"Text too short ({char_count} chars, minimum {self.MIN_TEXT_LENGTH}). Detection may be unreliable.")
+        
+        # Detect script first
+        script = self._detect_script(cleaned_text)
+        
+        # Try detection methods in order
+        result = None
+        
+        # Method 1 : ML Model
+        if self.use_model and self.is_initialized:
+            try:
+                result                  = self._detect_with_model(cleaned_text)
+                result.detection_method = "xlm-roberta-model"
+            
+            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
+        if result is None and LANGDETECT_AVAILABLE:
+            try:
+                result                  = self._detect_with_langdetect(cleaned_text)
+                result.detection_method = "langdetect-library"
+            
+            except Exception as e:
+                logger.warning(f"langdetect failed: {repr(e)}, trying heuristics")
+                warnings.append("langdetect failed, using heuristics")
+        
+        # Method 3 : Character-based heuristics
+        if result is None:
+            result                  = self._detect_with_heuristics(cleaned_text, script)
+            result.detection_method = "character-heuristics"
+        
+        # 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:
+            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})")
+        
+        return result
+    
+
+    def _detect_with_model(self, text: str) -> LanguageDetectionResult:
+        """
+        Detect language using XLM-RoBERTa model
+        """
+        if not self.is_initialized:
+            if not self.initialize():
+                raise RuntimeError("Model not initialized")
+        
+        # Conservative truncation for long texts
+        if (len(text) > 2000):  
+            text = text[:2000]
+            logger.warning(f"Text too long, truncated to {len(text)} characters for language detection")
+        
+        # Get prediction
+        predictions   = self.classifier(text, top_k = 5)
+        
+        # Parse results
+        all_languages = dict()
+        primary_lang  = None
+        primary_conf  = 0.0
+        
+        for pred in predictions:
+            lang_code = pred['label']
+            score     = pred['score']
+            
+            # Handle model output format (might be like "en_XX" or just "en")
+            if ('_' in lang_code):
+                lang_code = lang_code.split('_')[0]
+            
+            all_languages[lang_code] = score
+            
+            if (score > primary_conf):
+                primary_conf = score
+                primary_lang = lang_code
+        
+        # Convert to Language enum
+        try:
+            primary_language = Language(primary_lang)
+
+        except ValueError:
+            primary_language = Language.UNKNOWN
+        
+        return LanguageDetectionResult(primary_language = primary_language,
+                                       confidence       = primary_conf,
+                                       all_languages    = all_languages,
+                                       script           = Script.UNKNOWN,
+                                       is_multilingual  = False,
+                                       detection_method = "model",
+                                       char_count       = 0,
+                                       word_count       = 0,
+                                       warnings         = [],
+                                      )
+
+    
+    def _detect_with_langdetect(self, text: str) -> LanguageDetectionResult:
+        """
+        Detect language using langdetect library
+        """
+        # Get all language probabilities
+        lang_probs    = detect_langs(text)
+        
+        all_languages = dict()
+
+        for prob in lang_probs:
+            all_languages[prob.lang] = prob.prob
+        
+        # Primary language
+        primary = lang_probs[0]
+        
+        try:
+            primary_language = Language(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         = [],
+                                      )
+    
+
+    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,
+                             }
+        
+        # If script clearly indicates language
+        if script in script_to_language:
+            primary_language = script_to_language[script]
+            # Moderate confidence for heuristics
+            confidence       = 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"],
+                                      )
+    
+
+    def _detect_latin_language(self, text: str) -> Language:
+        """
+        Detect Latin-script language using common word patterns
+        """
+        text_lower = text.lower()
+        
+        # Common word patterns for major Latin-script languages
+        patterns   = {Language.ENGLISH    : ['the', 'and', 'is', 'in', 'to', 'of', 'a', 'that', 'it', 'with', 'for', 'on', 'this', 'are', 'was', 'be', 'have', 'from', 'or', 'by'],
+                      Language.SPANISH    : ['el', 'la', 'de', 'que', 'y', 'en', 'un', 'por', 'con', 'no', 'una', 'para', 'es', 'al', 'como', 'del', 'los', 'se', 'las', 'su'],
+                      Language.FRENCH     : ['le', 'de', 'un', 'être', 'et', 'à', 'il', 'avoir', 'ne', 'je', 'son', 'que', 'ce', 'du', 'quel', 'elle', 'dans', 'pour', 'au', 'avec'],
+                      Language.GERMAN     : ['der', 'die', 'und', 'in', 'den', 'von', 'zu', 'das', 'mit', 'sich', 'des', 'auf', 'für', 'ist', 'im', 'dem', 'nicht', 'ein', 'eine', 'als'],
+                      Language.ITALIAN    : ['di', 'e', 'il', 'la', 'che', 'per', 'un', 'in', 'è', 'a', 'non', 'una', 'da', 'sono', 'come', 'del', 'ma', 'si', 'nel', 'anche'],
+                      Language.PORTUGUESE : ['de', 'a', 'o', 'que', 'e', 'do', 'da', 'em', 'um', 'para', 'é', 'com', 'não', 'uma', 'os', 'no', 'se', 'na', 'por', 'mais'],
+                     }
+        
+        # Count matches for each language
+        scores     = dict()
+        words      = set(text_lower.split())
+        
+        for lang, common_words in patterns.items():
+            score        = sum(1 for word in common_words if word in words)
+            scores[lang] = score
+        
+        # Return language with highest score
+        if scores:
+            best_lang = max(scores.items(), key = lambda x: x[1])
+            # At least 3 matches
+            if (best_lang[1] > 2):  
+                return best_lang[0]
+        
+        # Default to English for Latin script
+        return Language.ENGLISH
+    
+
+    def _detect_script(self, text: str) -> Script:
+        """
+        Detect the writing script used in text
+        """
+        # Count characters in each script
+        script_counts = {script: 0 for script in Script if script not in [Script.MIXED, Script.UNKNOWN]}
+        
+        for char in text:
+            if char in string.whitespace or char in string.punctuation:
+                continue
+            
+            code_point = ord(char)
+            
+            for script, ranges in self.SCRIPT_RANGES.items():
+                for start, end in ranges:
+                    if (start <= code_point <= end):
+                        script_counts[script] += 1
+                        break
+        
+        # Find dominant script
+        total_chars = sum(script_counts.values())
+        
+        if (total_chars == 0):
+            return Script.UNKNOWN
+        
+        # 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%)
+        if (len(script_percentages) > 1):
+            max_percentage = max(script_percentages.values())
+            if (max_percentage < 0.7):
+                return Script.MIXED
+        
+        # Return dominant script
+        if script_percentages:
+            return max(script_percentages.items(), key=lambda x: x[1])[0]
+        
+        return Script.UNKNOWN
+    
+
+    def _clean_text(self, text: str) -> str:
+        """
+        Clean text for language detection
+        """
+        # Remove URLs
+        text = re.sub(r'https?://\S+', '', text)
+        text = re.sub(r'www\.\S+', '', text)
+        
+        # Remove emails
+        text = re.sub(r'\S+@\S+', '', text)
+        
+        # Remove excessive whitespace
+        text = re.sub(r'\s+', ' ', text)
+        
+        return text.strip()
+    
+
+    def _create_unknown_result(self, text: str, warnings: List[str]) -> LanguageDetectionResult:
+        """
+        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,
+                                      )
+
+    
+    def is_language(self, text: str, target_language: Language, threshold: float = 0.7) -> bool:
+        """
+        Check if text is in a specific language
+        
+        Arguments:
+        ----------
+            text            : Input text
+
+            target_language : Language to check for
+            
+            threshold       : Minimum confidence threshold
+            
+        Returns:
+        --------
+            { bool }        : True if text is in target language with sufficient confidence
+        """
+        result = self.detect(text)
+        return (result.primary_language == target_language and (result.confidence >= threshold))
+
+    
+    def get_supported_languages(self) -> List[str]:
+        """
+        Get list of supported language codes
+        """
+        return [lang.value for lang in Language if lang != Language.UNKNOWN]
+    
+
+    def cleanup(self):
+        """
+        Clean up resources
+        """
+        self.classifier     = None
+        self.is_initialized = False
+
+
+# ==================== Convenience Functions ====================
+def quick_detect(text: str, **kwargs) -> LanguageDetectionResult:
+    """
+    Quick language detection with default settings
+    
+    Arguments:
+    ----------
+        text     : Input text
+
+        **kwargs : Override settings
+        
+    Returns:
+    --------
+        LanguageDetectionResult object
+    """
+    detector = LanguageDetector(**kwargs)
+    
+    if detector.use_model:
+        detector.initialize()
+
+    return detector.detect(text)
+
+
+def is_english(text: str, threshold: float = 0.7) -> bool:
+    """
+    Quick check if text is English
+    """
+    detector   = LanguageDetector(use_model = True)
+    is_english = detector.is_language(text, Language.ENGLISH, threshold)
+    
+    return is_english
+
+
+
+# Export
+__all__ = ['Script',
+           'Language',
+           'is_english',
+           'quick_detect',
+           'LanguageDetector',
+           'LanguageDetectionResult',
+          ]
+
+
+# ==================== Testing ====================
+if __name__ == "__main__":
+    # Test cases
+    test_texts = {"English" : "This is a sample text written in English. It contains multiple sentences to test the language detection system.",
+                  "Spanish" : "Este es un texto de ejemplo escrito en español. Contiene múltiples oraciones para probar el sistema de detección de idiomas.",
+                  "French"  : "Ceci est un exemple de texte écrit en français. Il contient plusieurs phrases pour tester le système de détection de langue.",
+                  "German"  : "Dies ist ein Beispieltext in deutscher Sprache. Es enthält mehrere Sätze zum Testen des Spracherkennungssystems.",
+                  "Chinese" : "这是用中文写的示例文本。它包含多个句子来测试语言检测系统。",
+                  "Russian" : "Это пример текста, написанного на русском языке. Он содержит несколько предложений для проверки системы определения языка.",
+                  "Mixed"   : "This is English. Este es español. C'est français.",
+                  "Short"   : "Hello",
+                 }
+    
+    detector   = LanguageDetector(use_model = True)  # Use fast mode for testing
+    
+    for name, text in test_texts.items():
+        print(f"\n{'='*70}")
+        print(f"Testing: {name}")
+        print(f"{'='*70}")
+        print(f"Text: {text[:80]}...")
+        
+        result = detector.detect(text)
+        
+        print(f"\nPrimary Language: {result.primary_language.value}")
+        print(f"Confidence: {result.confidence:.2f}")
+        print(f"Script: {result.script.value}")
+        print(f"Method: {result.detection_method}")
+        print(f"Multilingual: {result.is_multilingual}")
+        
+        if result.warnings:
+            print(f"Warnings: {result.warnings}")
+        
+        if (len(result.all_languages) > 1):
+            print("\nAll detected languages:")
+            for lang, conf in sorted(result.all_languages.items(), key = lambda x: x[1], reverse = True)[:3]:
+                print(f"  {lang}: {conf:.2f}")
+

processors/text_processor.py

@@ -0,0 +1,581 @@
+# DEPENDENCIES
+import re
+import unicodedata
+from typing import Any
+from typing import List
+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,
+               }
+
+
+class TextProcessor:
+    """
+    Handles text cleaning, normalization, sentence splitting, and preprocessing for AI detection metrics
+    
+    Features::
+    - Unicode normalization
+    - Smart sentence splitting (handles abbreviations, decimals, etc.)
+    - Whitespace normalization
+    - Special character handling
+    - Paragraph detection
+    - Word tokenization
+    - 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]|$)'
+    
+    # Patterns for cleaning
+    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 = 50000, preserve_formatting: bool = False, remove_urls: bool = True, remove_emails: bool = True,
+                 normalize_unicode: bool = True, fix_encoding: bool = True):
+        """
+        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}")
+    
+
+    def process(self, text: str, **kwargs) -> ProcessedText:
+        """
+        Main processing pipeline
+        
+        Arguments:
+        ----------
+            text     { str }  : Input text to process
+
+            **kwargs          : Override default settings
+            
+        Returns:
+        --------
+            { ProcessedText } : ProcessedText object with all processed components
+        """
+        try:
+            original_text     = text
+            validation_errors = list()
+            
+            # Validate input
+            if not text or not isinstance(text, str):
+                validation_errors.append("Text is empty or not a string")
+                return self._create_invalid_result(original_text, validation_errors)
+            
+            # Initial cleaning
+            text = self._initial_clean(text)
+            
+            # Fix encoding issues
+            if self.fix_encoding:
+                text = self._fix_encoding_issues(text)
+            
+            # Normalize Unicode
+            if self.normalize_unicode:
+                text = self._normalize_unicode(text)
+            
+            # Remove unwanted elements
+            if self.remove_urls:
+                text = self._remove_urls(text)
+            
+            if self.remove_emails:
+                text = self._remove_emails(text)
+            
+            # Clean whitespace
+            text = self._clean_whitespace(text)
+            
+            # Validate length
+            if (len(text) < self.min_text_length):
+                validation_errors.append(f"Text too short: {len(text)} chars (minimum: {self.min_text_length})")
+            
+            if (len(text) > self.max_text_length):
+                validation_errors.append(f"Text too long: {len(text)} chars (maximum: {self.max_text_length})")
+                text = text[:self.max_text_length]
+            
+            # Extract components
+            sentences    = self.split_sentences(text)
+            words        = self.tokenize_words(text)
+            paragraphs   = self.split_paragraphs(text)
+            
+            # Calculate statistics
+            char_count   = len(text)
+            word_count   = len(words)
+            sent_count   = len(sentences)
+            para_count   = len(paragraphs)
+            
+            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)")
+            
+            # Create metadata
+            metadata = {"has_special_chars" : self._has_special_characters(text),
+                        "has_numbers"       : any(c.isdigit() for c in text),
+                        "has_uppercase"     : any(c.isupper() for c in text),
+                        "has_lowercase"     : any(c.islower() for c in text),
+                        "unique_words"      : len(set(w.lower() for w in words)),
+                        "lexical_diversity" : len(set(w.lower() for w in words)) / word_count if word_count > 0 else 0,
+                       }
+            
+            is_valid = len(validation_errors) == 0
+            
+            return ProcessedText(original_text       = original_text,
+                                 cleaned_text        = text,
+                                 sentences           = sentences,
+                                 words               = words,
+                                 paragraphs          = paragraphs,
+                                 char_count          = char_count,
+                                 word_count          = word_count,
+                                 sentence_count      = sent_count,
+                                 paragraph_count     = para_count,
+                                 avg_sentence_length = avg_sent_len,
+                                 avg_word_length     = avg_word_len,
+                                 is_valid            = is_valid,
+                                 validation_errors   = validation_errors,
+                                 metadata            = metadata,
+                                )
+            
+        except Exception as e:
+            logger.error(f"Error processing text: {repr(e)}")
+            return self._create_invalid_result(text if text else "", [f"Processing error: {str(e)}"])
+    
+
+    def split_sentences(self, text: str) -> List[str]:
+        """
+        Smart sentence splitting with abbreviation handling
+        
+        Arguments:
+        ----------
+            text { str } : Input text
+            
+        Returns:
+        --------
+             { list}     : List of sentences
+        """
+        # Protect abbreviations
+        protected_text = text
+
+        for abbr in self.ABBREVIATIONS:
+            # Replace abbreviation periods with placeholder
+            protected_text = re.sub(pattern = rf'\b{re.escape(abbr)}\.',
+                                    repl    = abbr.replace('.', '<DOT>'),
+                                    string  = protected_text,
+                                    flags   = re.IGNORECASE,
+                                   )
+        
+        # Protect decimal numbers (e.g., 3.14)
+        protected_text    = re.sub(r'(\d+)\.(\d+)', r'\1<DOT>\2', protected_text)
+        
+        # Protect ellipsis
+        protected_text    = protected_text.replace('...', '<ELLIPSIS>')
+        
+        # Split on sentence endings
+        sentences         = re.split(self.SENTENCE_ENDINGS, protected_text)
+        
+        # Restore protected characters and clean
+        cleaned_sentences = list()
+
+        for sent in sentences:
+            sent = sent.replace('<DOT>', '.')
+            sent = sent.replace('<ELLIPSIS>', '...')
+            sent = sent.strip()
+            
+            # Only keep non-empty sentences with actual words
+            if (sent and (len(sent.split()) >= 2)):  
+                # At least 2 words
+                cleaned_sentences.append(sent)
+        
+        return cleaned_sentences
+
+    
+    def tokenize_words(self, text: str) -> List[str]:
+        """
+        Tokenize text into words
+        
+        Arguments:
+        ----------
+            text { str } : Input text
+            
+        Returns:
+        --------
+             { list }    : List of words
+        """
+        # Remove punctuation but keep apostrophes in contractions
+        text           = re.sub(pattern = r"[^\w\s'-]", 
+                                repl    = ' ', 
+                                string  = text,
+                               )
+        
+        # Split on whitespace
+        words          = text.split()
+        
+        # Filter out pure numbers and single characters (except 'a' and 'I')
+        filtered_words = list()
+
+        for word in words:
+            # Remove leading/trailing quotes and hyphens
+            word = word.strip("'-")  
+            if word and (len(word) > 1 or word.lower() in ['a', 'i']):
+                if not word.replace('-', '').replace("'", '').isdigit():
+                    filtered_words.append(word)
+        
+        return filtered_words
+
+    
+    def split_paragraphs(self, text: str) -> List[str]:
+        """
+        Split text into paragraphs
+        
+        Arguments:
+        ----------
+            text { str } : Input text
+            
+        Returns:
+        --------
+            { list }     : List of paragraphs
+        """
+        # Split on double newlines or more
+        paragraphs         = re.split(r'\n\s*\n', text)
+        
+        # Clean and filter
+        cleaned_paragraphs = list()
+
+        for para in paragraphs:
+            para = para.strip()
+            
+            # There should be at least 5 words
+            if para and (len(para.split()) >= 5):  
+                cleaned_paragraphs.append(para)
+        
+        return cleaned_paragraphs if cleaned_paragraphs else [text]
+    
+
+    def create_chunks(self, text: str, chunk_size: int = 512, overlap: int = 50, unit: str = 'words') -> List[str]:
+        """
+        Split long text into overlapping chunks
+        
+        Arguments:
+        ----------
+            text        { str } : Input text
+
+            chunk_size  { int } : Size of each chunk
+            
+            overlap     { int } : Number of units to overlap between chunks
+            
+            unit        { str } : 'words', 'sentences', or 'chars'
+            
+        Returns:
+        --------
+                { list }        : List of text chunks
+        """
+        if (unit == 'words'):
+            units = self.tokenize_words(text)
+
+        elif (unit == 'sentences'):
+            units = self.split_sentences(text)
+
+        elif (unit == 'chars'):
+            units = list(text)
+
+        else:
+            raise ValueError(f"Unknown unit: {unit}")
+        
+        if (len(units) <= chunk_size):
+            return [text]
+        
+        chunks = list()
+        start  = 0
+        
+        while (start < len(units)):
+            end         = start + chunk_size
+            chunk_units = units[start:end]
+            
+            if (unit == 'chars'):
+                chunk_text = ''.join(chunk_units)
+
+            else:
+                chunk_text = ' '.join(chunk_units)
+            
+            chunks.append(chunk_text)
+            start = end - overlap
+        
+        return chunks
+    
+
+    def _initial_clean(self, text: str) -> str:
+        """
+        Remove null bytes and control characters
+        """
+        # Remove null bytes
+        text = text.replace('\x00', '')
+        
+        # Remove other control characters except newlines and tabs
+        text = ''.join(char for char in text if unicodedata.category(char)[0] != 'C' or char in '\n\t\r')
+        
+        return text
+
+    
+    def _fix_encoding_issues(self, text: str) -> str:
+        """
+        Fix common encoding issues
+        """
+        replacements = {'’' : "'",   # Smart apostrophe
+                        '“' : '"',   # Smart quote left
+                        'â€'  : '"',   # Smart quote right
+                        'â€"' : '—',   # Em dash
+                        'â€"' : '–',   # En dash
+                        '…' : '...', # Ellipsis
+                        'é'  : 'é',   # Common UTF-8 issue
+                        'è'  : 'è',
+                        'Ã '  : 'à',
+                        '€' : '€',   # Euro sign
+                       }
+        
+        for wrong, right in replacements.items():
+            text = text.replace(wrong, right)
+        
+        return text
+
+    
+    def _normalize_unicode(self, text: str) -> str:
+        """
+        Normalize Unicode to consistent form
+        """
+        # NFKC normalization (compatibility decomposition, followed by canonical composition)
+        text = unicodedata.normalize('NFKC', text)
+        
+        # Replace smart quotes and apostrophes
+        text = text.replace('"', '"').replace('"', '"')
+        text = text.replace(''', "'").replace(''', "'")
+        text = text.replace('—', '-').replace('–', '-')
+        
+        return text
+
+    
+    def _remove_urls(self, text: str) -> str:
+        """
+        Remove URLs from text
+        """
+        # Remove http/https URLs
+        text = re.sub(r'https?://\S+', '', text)
+        
+        # Remove www URLs
+        text = re.sub(r'www\.\S+', '', text)
+        
+        return text
+    
+
+    def _remove_emails(self, text: str) -> str:
+        """
+        Remove email addresses
+        """
+        text = re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', '', text)
+        return text
+    
+
+    def _clean_whitespace(self, text: str) -> str:
+        """
+        Normalize whitespace
+        """
+        if self.preserve_formatting:
+            # Just normalize multiple spaces
+            text = self.MULTIPLE_SPACES.sub(' ', text)
+            text = self.MULTIPLE_NEWLINES.sub('\n\n', text)
+        
+        else:
+            # Aggressive whitespace normalization
+            text = self.MULTIPLE_NEWLINES.sub('\n\n', text)
+            text = self.MULTIPLE_SPACES.sub(' ', text)
+            text = text.strip()
+        
+        return text
+    
+
+    def _has_special_characters(self, text: str) -> bool:
+        """
+        Check if text contains special characters
+        """
+        special_chars = set('!@#$%^&*()[]{}|\\:;"<>?,./~`')
+        return any(char in special_chars for char in text)
+    
+
+    def _create_invalid_result(self, text: str, errors: List[str]) -> ProcessedText:
+        """
+        Create a ProcessedText object for invalid input
+        """
+        return 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   = errors,
+                             metadata            = {},
+                            )
+
+
+
+# Convenience Functions
+
+def quick_process(text: str, **kwargs) -> ProcessedText:
+    """
+    Quick processing with default settings
+    
+    Arguments:
+    ----------
+        text     : Input text
+
+        **kwargs : Override settings
+        
+    Returns:
+    --------
+        ProcessedText object
+    """
+    processor = TextProcessor(**kwargs)
+    return processor.process(text)
+
+
+def extract_sentences(text: str) -> List[str]:
+    """
+    Quick sentence extraction
+    """
+    processor = TextProcessor()
+    return processor.split_sentences(text)
+
+
+def extract_words(text: str) -> List[str]:
+    """
+    Quick word extraction
+    """
+    processor = TextProcessor()
+    return processor.tokenize_words(text)
+
+
+# Export
+__all__ = ['TextProcessor',
+           'ProcessedText',
+           '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 test@example.com 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

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

reporter/reasoning_generator.py

@@ -0,0 +1,675 @@
+# 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,
+               }
+
+
+
+class ReasoningGenerator:
+    """
+    Generates detailed, human-readable reasoning for AI detection results with ensemble and domain-aware integration
+    
+    Features:
+    - Ensemble method explanation
+    - Domain-aware calibration context
+    - Uncertainty quantification
+    - Metric contribution analysis
+    - Actionable recommendations
+    """
+    # Enhanced metric descriptions aligned with current architecture
+    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",
+                           "detect_gpt"        : "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",
+                          }
+    
+    # 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",
+                          }
+    
+    # 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",
+                          }
+
+    
+    def __init__(self):
+        """
+        Initialize reasoning generator with ensemble awareness
+        """
+        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:
+        """
+        Generate comprehensive reasoning for detection result with ensemble integration
+        
+        Arguments:
+        ----------
+            ensemble_result    : Final ensemble prediction with weights and reasoning
+
+            metric_results     : Individual metric results from all 6 metrics
+            
+            domain             : Detected text domain for context-aware analysis
+            
+            attribution_result : Model attribution (if available)
+            
+            text_length        : Length of analyzed text in words
+            
+            ensemble_method    : Method used for ensemble aggregation
+            
+        Returns:
+        --------
+            DetailedReasoning object with ensemble-aware analysis
+        """
+        # Generate summary with ensemble context
+        summary                                     = self._generate_ensemble_summary(ensemble_result, domain, text_length, ensemble_method)
+        
+        # Identify key indicators with metric weights
+        key_indicators                              = self._identify_weighted_indicators(ensemble_result, metric_results)
+        
+        # Generate metric explanations with confidence
+        metric_explanations                         = self._generate_metric_explanations(metric_results, ensemble_result.metric_weights)
+        
+        # Compile evidence with ensemble consensus
+        supporting_evidence, contradicting_evidence = self._compile_ensemble_evidence(ensemble_result, metric_results)
+        
+        # Explain confidence with uncertainty
+        confidence_explanation                      = self._explain_confidence_with_uncertainty(ensemble_result, metric_results)
+        
+        # Domain-specific analysis
+        domain_analysis                             = self._generate_domain_analysis(domain, metric_results, 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)
+        
+        # Uncertainty analysis
+        uncertainty_analysis = self._analyze_uncertainty(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,
+                                )
+    
+
+    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
+        
+        # Confidence level description
+        if (confidence >= 0.8):
+            conf_desc = "very high confidence"
+
+        elif (confidence >= 0.6):
+            conf_desc = "high confidence"
+
+        elif (confidence >= 0.4):
+            conf_desc = "moderate confidence"
+
+        else:
+            conf_desc = "low confidence"
+        
+        # Consensus description
+        if (consensus >= 0.8):
+            consensus_desc = "strong consensus"
+
+        elif (consensus >= 0.6):
+            consensus_desc = "moderate consensus"
+
+        else:
+            consensus_desc = "low consensus"
+        
+        # Build summary based on verdict and ensemble metrics
+        summary_parts = list()
+        
+        if ("AI-Generated" in verdict):
+            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
+            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
+            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%})."
+                                )
+        
+        else:
+            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.")
+        
+        return " ".join(summary_parts)
+    
+
+    def _identify_weighted_indicators(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult]) -> List[str]:
+        """
+        Identify top indicators considering metric weights and contributions
+        """
+        indicators       = list()
+        is_ai            = "AI-Generated" in ensemble_result.final_verdict
+        
+        # Use ensemble weights to prioritize indicators
+        weighted_metrics = list()
+
+        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)
+            
+            if key_feature:
+                weight_pct = ensemble_result.metric_weights.get(name, 0.0) * 100
+                indicators.append(f"**{name.title()}** ({weight_pct:.1f}% weight): {key_feature}")
+        
+        return indicators
+    
+
+    def _extract_ensemble_feature(self, metric_name: str, result: MetricResult, is_ai: bool, priority_score: float) -> Optional[str]:
+        """
+        Extract significant features considering ensemble context
+        """
+        details = result.details
+        
+        if (metric_name == "structural"):
+            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"
+            
+            elif (not is_ai 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 (metric_name == "perplexity"):
+            perplexity = details.get("overall_perplexity", 50)
+            
+            if (is_ai and (perplexity < 35)):
+                return f"Low perplexity ({perplexity:.1f}) indicates high predictability"
+
+            elif (not is_ai 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)
+            
+            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)):
+                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)
+            
+            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)):
+                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)
+            
+            if (is_ai and (pos_diversity < 0.4)):
+                return f"Limited grammatical diversity ({pos_diversity:.2f})"
+
+            elif (not is_ai and (pos_diversity > 0.55)):
+                return f"Rich grammatical variety ({pos_diversity:.2f})"
+                
+        elif (metric_name == "detect_gpt"):
+            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)):
+                return f"Text stability under perturbation ({stability:.2f})"
+        
+        return None
+    
+
+    def _generate_metric_explanations(self, metric_results: Dict[str, MetricResult], metric_weights: Dict[str, float]) -> Dict[str, str]:
+        """
+        Generate explanations for each metric with weight context
+        """
+        explanations = dict()
+        
+        for name, result in metric_results.items():
+            if result.error:
+                explanations[name] = f"⚠️ Analysis failed: {result.error}"
+                continue
+            
+            # Get metric description
+            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
+
+            else:
+                verdict = "shows mixed signals"
+                prob    = max(result.ai_probability, result.human_probability)
+            
+            # Build explanation with confidence
+            explanation        = (f"This metric {desc}.{weight_info} "
+                                  f"Result: {verdict} ({prob:.1%} probability) "
+                                  f"with {result.confidence:.1%} confidence."
+                                 )
+            
+            explanations[name] = explanation
+        
+        return explanations
+    
+
+    def _compile_ensemble_evidence(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult]) -> tuple:
+        """
+        Compile evidence considering ensemble consensus and weights
+        """
+        is_ai_verdict = "AI-Generated" in ensemble_result.final_verdict
+        consensus     = ensemble_result.consensus_level
+        
+        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 the evidence by metric importance
+            weight_indicator   = "🟢" if weight > 0.15 else "🟡" if weight > 0.08 else "⚪"
+            
+            if (metric_suggests_ai == is_ai_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)
+                
+                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)
+                
+                if indicator:
+                    contradicting.append(f"{weight_indicator} {indicator}")
+        
+        # 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]:
+        """
+        Get AI 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"]
+
+        elif (metric_name == "perplexity"):
+            if (details.get("overall_perplexity", 100) < 35):
+                return self.AI_INDICATORS["low_perplexity"]
+
+        elif (metric_name == "entropy"):
+            if (details.get("token_diversity", 1.0) < 0.65):
+                return self.AI_INDICATORS["low_entropy"]
+
+        elif (metric_name == "semantic_analysis"):
+            if (details.get("coherence_score", 0.5) > 0.75):
+                return self.AI_INDICATORS["semantic_perfection"]
+
+        return None
+    
+
+    def _get_human_indicator_from_metric(self, metric_name: str, result: MetricResult) -> Optional[str]:
+        """
+        Get human 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"]
+
+        elif (metric_name == "perplexity"):
+            if (details.get("overall_perplexity", 0) > 55):
+                return self.HUMAN_INDICATORS["high_perplexity"]
+
+        elif (metric_name == "entropy"):
+            if (details.get("token_diversity", 0.0) > 0.75):
+                return self.HUMAN_INDICATORS["high_entropy"]
+
+        return None
+    
+
+    def _explain_confidence_with_uncertainty(self, ensemble_result: EnsembleResult, metric_results: Dict[str, MetricResult]) -> str:
+        """
+        Explain confidence considering uncertainty metrics
+        """
+        confidence        = ensemble_result.overall_confidence
+        uncertainty       = ensemble_result.uncertainty_score
+        consensus         = ensemble_result.consensus_level
+        
+        # Calculate additional factors
+        valid_metrics     = len([r for r in metric_results.values() if not r.error])
+        high_conf_metrics = len([r for r in metric_results.values() if not r.error and r.confidence > 0.7])
+        
+        explanation       = f"**Confidence: {confidence:.1%}** | **Uncertainty: {uncertainty:.1%}** | **Consensus: {consensus:.1%}**\n\n"
+        
+        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."
+        
+        explanation += f"\n\n• {high_conf_metrics}/{valid_metrics} metrics with high confidence"
+        explanation += f"\n• Ensemble uncertainty score: {uncertainty:.1%}"
+        explanation += f"\n• Metric consensus level: {consensus:.1%}"
+        
+        return explanation
+    
+
+    def _generate_domain_analysis(self, domain: Domain, metric_results: Dict[str, MetricResult], ensemble_result: EnsembleResult) -> str:
+        """
+        Generate domain-specific analysis with calibration context
+        """
+        domain_contexts = {Domain.ACADEMIC      : "Academic writing analysis emphasizes: citation patterns, technical depth, argument structure, and formal tone. Detection calibrated for scholarly conventions.",
+                           Domain.CREATIVE      : "Creative writing analysis focuses: narrative voice, emotional authenticity, stylistic variation, and imaginative elements. Accounts for artistic license.",
+                           Domain.TECHNICAL_DOC : "Technical documentation analysis examines: specialized terminology, structured explanations, practical examples, and precision requirements.",
+                           Domain.SOCIAL_MEDIA  : "Social media analysis considers: informal language, brevity, emotional expression, and platform-specific conventions.",
+                           Domain.GENERAL       : "General content analysis uses universal patterns across writing styles and genres.",
+                          }
+        
+        context         = domain_contexts.get(domain, domain_contexts[Domain.GENERAL])
+        
+        # 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.CREATIVE      : "Balanced thresholds accounting for creative expression",
+                           Domain.SOCIAL_MEDIA  : "Adapted thresholds for informal communication patterns",
+                          }
+        
+        threshold_note  = threshold_info.get(domain, "Standard detection thresholds applied")
+        
+        return f"**Domain Analysis ({domain.value})**\n\n{context}\n\n{threshold_note}"
+    
+
+    def _explain_ensemble_methodology(self, ensemble_result: EnsembleResult, ensemble_method: str) -> str:
+        """
+        Explain the ensemble methodology used
+        """
+        method_desc = self.ENSEMBLE_METHODS.get(ensemble_method, "advanced aggregation of multiple detection methods")
+        
+        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]
+        
+        if top_metrics:
+            explanation += "**Top contributing metrics**:\n"
+            for metric, weight in top_metrics:
+                explanation += f"• {metric}: {weight:.1%} weight\n"
+        
+        # Add reasoning snippets if available
+        if hasattr(ensemble_result, 'reasoning') and ensemble_result.reasoning:
+            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"
+        
+        return explanation
+    
+
+    def _analyze_uncertainty(self, ensemble_result: EnsembleResult) -> str:
+        """
+        Analyze and explain uncertainty factors
+        """
+        uncertainty = ensemble_result.uncertainty_score
+        
+        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."
+        
+        else:
+            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
+        """
+        recommendations = list()
+        verdict         = ensemble_result.final_verdict
+        confidence      = ensemble_result.overall_confidence
+        uncertainty     = ensemble_result.uncertainty_score
+        
+        # Base recommendations by verdict and confidence
+        if ("AI-Generated" in verdict):
+            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)
+            
+        elif ("Human-Written" in verdict):
+            if (confidence >= 0.8):
+                rec = "**High-confidence human 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.")
+        
+        # Uncertainty-based recommendations
+        if (uncertainty > 0.6):
+            recommendations.append("**High uncertainty case**: Consider complementary verification methods like oral discussion or process documentation.")
+        
+        # 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.TECHNICAL_DOC : "For technical content: verify practical expertise and problem-solving ability.",
+                     }
+        
+        if domain in domain_recs:
+            recommendations.append(domain_recs[domain])
+        
+        # General best practices
+        recommendations.extend(["**Context matters**: Consider author's background, writing history, and situational factors.",
+                                "**Educational approach**: Use detection results as conversation starters about appropriate AI use.",
+                                "**Continuous evaluation**: AI writing evolves rapidly; regular calibration updates maintain accuracy."
+                              ])
+        
+        return recommendations
+
+
+
+# Export
+__all__ = ["DetailedReasoning", 
+           "ReasoningGenerator",
+          ]

reporter/report_generator.py

@@ -0,0 +1,595 @@
+# DEPENDENCIES
+import json
+from typing import Any
+from typing import Dict
+from typing import List
+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
+
+
+class ReportGenerator:
+    """
+    Generates comprehensive detection reports with detailed metrics
+    
+    Supports:
+    - JSON (structured data with all details)
+    - PDF (printable reports with tables and formatting)
+    """
+    def __init__(self, output_dir: Optional[Path] = None):
+        """
+        Initialize report generator
+        
+        Arguments:
+        ----------
+            output_dir { str } : Directory for saving reports (default: data/reports)
+        """
+        if (output_dir is None):
+            output_dir = Path(__file__).parent.parent / "data" / "reports"
+        
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents  = True, 
+                              exist_ok = True,
+                             )
+        
+        self.reasoning_generator = ReasoningGenerator()
+        
+        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]:
+        """
+        Generate comprehensive report in JSON and PDF formats with detailed metrics
+        
+        Arguments:
+        ----------
+            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)
+            
+            filename_prefix       : Prefix for output filenames
+            
+        Returns:
+        --------
+                { dict }          : Dictionary mapping format to filepath
+        """
+        # 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,
+                                                            )
+        
+        # Extract detailed metrics from ACTUAL detection results
+        detailed_metrics = self._extract_detailed_metrics(detection_result)
+        
+        # Timestamp for filenames
+        timestamp        = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        generated_files  = dict()
+        
+        # Generate requested formats
+        if ("json" in formats):  
+            json_path               = self._generate_json_report(detection_result      = detection_result, 
+                                                                 reasoning             = reasoning, 
+                                                                 detailed_metrics      = detailed_metrics, 
+                                                                 attribution_result    = attribution_result,
+                                                                 highlighted_sentences = highlighted_sentences,
+                                                                 filename              = f"{filename_prefix}_{timestamp}.json",
+                                                                )
+            generated_files["json"] = str(json_path)
+        
+        if ("pdf" in formats):
+            try:
+                pdf_path               = self._generate_pdf_report(detection_result      = detection_result, 
+                                                                   reasoning             = reasoning, 
+                                                                   detailed_metrics      = detailed_metrics, 
+                                                                   attribution_result    = attribution_result,
+                                                                   highlighted_sentences = highlighted_sentences,
+                                                                   filename              = f"{filename_prefix}_{timestamp}.pdf",
+                                                                  )  
+                generated_files["pdf"] = str(pdf_path)
+
+            except Exception as e:
+                logger.warning(f"PDF generation failed: {repr(e)}")
+                logger.info("Install reportlab for PDF support: pip install reportlab")
+        
+        logger.info(f"Generated {len(generated_files)} report(s): {list(generated_files.keys())}")
+        
+        return generated_files
+
+
+    def _extract_detailed_metrics(self, detection_result: DetectionResult) -> List[DetailedMetric]:
+        """
+        Extract detailed metrics with sub-metrics from ACTUAL detection result
+        """
+        detailed_metrics = list()
+        metric_results   = detection_result.metric_results
+        ensemble_result  = detection_result.ensemble_result
+        
+        # Get actual metric weights from ensemble
+        metric_weights   = getattr(ensemble_result, 'metric_weights', {})
+        
+        # Extract actual metric data
+        for metric_name, metric_result in metric_results.items():
+            if metric_result.error is not None:
+                continue
+                
+            # Get actual probabilities and confidence
+            ai_prob    = metric_result.ai_probability * 100
+            human_prob = metric_result.human_probability * 100
+            confidence = metric_result.confidence * 100
+            
+            # Determine verdict based on actual probability
+            if (ai_prob >= 60):
+                verdict = "AI"
+
+            elif (ai_prob <= 40):
+                verdict = "HUMAN"
+
+            else:
+                verdict = "MIXED (AI + HUMAN)"
+            
+            # Get actual weight or use default
+            weight                = metric_weights.get(metric_name, 0.0) * 100
+            
+            # Extract actual detailed metrics from metric result
+            detailed_metrics_data = self._extract_metric_details(metric_name   = metric_name, 
+                                                                 metric_result = metric_result,
+                                                                )
+            
+            # 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,
+                                                   human_probability = human_prob,
+                                                   confidence        = confidence,
+                                                   verdict           = verdict,
+                                                   description       = description,
+                                                   detailed_metrics  = detailed_metrics_data,
+                                                   weight            = weight,
+                                                  )
+                                   )
+        
+        return detailed_metrics
+
+
+    def _extract_metric_details(self, metric_name: str, metric_result) -> Dict[str, float]:
+        """
+        Extract detailed sub-metrics from metric result
+        """
+        details = dict()
+        
+        # Try to get details from metric result
+        if ((hasattr(metric_result, 'details')) and metric_result.details):
+            details = metric_result.details.copy()
+        
+        # If no details available, provide basic calculated values
+        if not details:
+            details = {"ai_probability"    : metric_result.ai_probability * 100,
+                       "human_probability" : metric_result.human_probability * 100,
+                       "confidence"        : metric_result.confidence * 100,
+                       "score"             : getattr(metric_result, 'score', 0.0) * 100,
+                      }
+        
+        return details
+
+
+    def _get_metric_description(self, metric_name: str) -> str:
+        """
+        Get description for each metric type
+        """
+        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",
+                        "detect_gpt"        : "Tests text stability under perturbation using curvature analysis",
+                       }
+
+        return descriptions.get(metric_name, "Advanced text analysis metric.")
+
+
+    def _generate_json_report(self, detection_result: DetectionResult, reasoning: DetailedReasoning, detailed_metrics: List[DetailedMetric], 
+                              attribution_result: Optional[AttributionResult], highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
+        """
+        Generate JSON format report with detailed metrics
+        """
+        # Convert metrics to serializable format
+        metrics_data = list()
+
+        for metric in detailed_metrics:
+            metrics_data.append({"name"              : metric.name,
+                                 "ai_probability"    : metric.ai_probability,
+                                 "human_probability" : metric.human_probability,
+                                 "confidence"        : metric.confidence,
+                                 "verdict"           : metric.verdict,
+                                 "description"       : metric.description,
+                                 "weight"            : metric.weight,
+                                 "detailed_metrics"  : metric.detailed_metrics,
+                               })
+        
+        # Convert highlighted sentences to serializable format
+        highlighted_data = None
+        
+        if highlighted_sentences:
+            highlighted_data = list()
+
+            for sent in highlighted_sentences:
+                highlighted_data.append({"text"           : sent.text,
+                                         "ai_probability" : sent.ai_probability,
+                                         "confidence"     : sent.confidence,
+                                         "color_class"    : sent.color_class,
+                                         "index"          : sent.index,
+                                       })
+
+        # Attribution data - use attribution_result
+        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 ACTUAL detection results with ensemble integration
+        ensemble_result = detection_result.ensemble_result
+        
+        report_data     = {"report_metadata"     : {"generated_at" : datetime.now().isoformat(),
+                                                    "version"      : "1.0.0",
+                                                    "format"       : "json",
+                                                    "report_id"    : filename.replace('.json', ''),
+                                                   },
+                           "overall_results"     : {"final_verdict"      : ensemble_result.final_verdict,
+                                                    "ai_probability"     : round(ensemble_result.ai_probability, 4),
+                                                    "human_probability"  : round(ensemble_result.human_probability, 4),
+                                                    "mixed_probability"  : round(ensemble_result.mixed_probability, 4),
+                                                    "overall_confidence" : round(ensemble_result.overall_confidence, 4),
+                                                    "uncertainty_score"  : round(ensemble_result.uncertainty_score, 4),
+                                                    "consensus_level"    : round(ensemble_result.consensus_level, 4),
+                                                    "domain"             : detection_result.domain_prediction.primary_domain.value,
+                                                    "domain_confidence"  : round(detection_result.domain_prediction.confidence, 4),
+                                                    "text_length"        : detection_result.processed_text.word_count,
+                                                    "sentence_count"     : detection_result.processed_text.sentence_count,
+                                                   },
+                           "ensemble_analysis"   : {"method_used"     : "confidence_calibrated",
+                                                    "metric_weights"  : {name: round(weight, 4) for name, weight in ensemble_result.metric_weights.items()},
+                                                    "weighted_scores" : {name: round(score, 4) for name, score in ensemble_result.weighted_scores.items()},
+                                                    "reasoning"       : ensemble_result.reasoning,
+                                                   },
+                           "detailed_metrics"    : metrics_data,
+                           "detection_reasoning" : {"summary"                : reasoning.summary,
+                                                    "key_indicators"         : reasoning.key_indicators,
+                                                    "metric_explanations"    : reasoning.metric_explanations,
+                                                    "supporting_evidence"    : reasoning.supporting_evidence,
+                                                    "contradicting_evidence" : reasoning.contradicting_evidence,
+                                                    "confidence_explanation" : reasoning.confidence_explanation,
+                                                    "domain_analysis"        : reasoning.domain_analysis,
+                                                    "ensemble_analysis"      : reasoning.ensemble_analysis,
+                                                    "uncertainty_analysis"   : reasoning.uncertainty_analysis,
+                                                    "recommendations"        : reasoning.recommendations,
+                                                   },
+                           "highlighted_text"    : highlighted_data,
+                           "model_attribution"   : attribution_data,
+                           "performance_metrics" : {"total_processing_time"  : round(detection_result.processing_time, 3),
+                                                    "metrics_execution_time" : {name: round(time, 3) for name, time in detection_result.metrics_execution_time.items()},
+                                                    "warnings"               : detection_result.warnings,
+                                                    "errors"                 : detection_result.errors,
+                                                   }
+                          }
+        
+        output_path     = self.output_dir / filename
+        
+        with open(output_path, 'w', encoding='utf-8') as f:
+            json.dump(obj          = report_data, 
+                      fp           = f, 
+                      indent       = 4, 
+                      ensure_ascii = False,
+                     )
+        
+        logger.info(f"JSON report saved: {output_path}")
+        return output_path
+
+
+    def _generate_pdf_report(self, detection_result: DetectionResult, reasoning: DetailedReasoning, detailed_metrics: List[DetailedMetric], 
+                             attribution_result: Optional[AttributionResult], highlighted_sentences: Optional[List] = None, filename: str = None) -> Path:
+        """
+        Generate PDF format report with detailed metrics
+        """
+        try:
+            from reportlab.lib import colors
+            from reportlab.lib.pagesizes import letter, A4
+            from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+            from reportlab.lib.units import inch
+            from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle, PageBreak
+            from reportlab.lib.enums import TA_CENTER, TA_LEFT, TA_JUSTIFY
+        
+        except ImportError:
+            raise ImportError("reportlab is required for PDF generation. Install: pip install reportlab")
+        
+        output_path   = self.output_dir / filename
+        
+        # Create PDF
+        doc           = SimpleDocTemplate(str(output_path),
+                                          pagesize     = letter,
+                                          rightMargin  = 50,
+                                          leftMargin   = 50,
+                                          topMargin    = 50,
+                                          bottomMargin = 20,
+                                         )
+        
+        # Container for PDF elements
+        elements      = list()
+        styles        = getSampleStyleSheet()
+        
+        # Custom styles
+        title_style   = ParagraphStyle('CustomTitle',
+                                       parent     = styles['Heading1'],
+                                       fontSize   = 20,
+                                       textColor  = colors.HexColor('#667eea'),
+                                       spaceAfter = 20,
+                                       alignment  = TA_CENTER,
+                                      )
+                                
+        heading_style = ParagraphStyle('CustomHeading',
+                                       parent      = styles['Heading2'],
+                                       fontSize    = 14,
+                                       textColor   = colors.HexColor('#111827'),
+                                       spaceAfter  = 12,
+                                       spaceBefore = 12,
+                                      )
+        
+        body_style    = ParagraphStyle('CustomBody',
+                                       parent     = styles['BodyText'],
+                                       fontSize   = 10,
+                                       alignment  = TA_JUSTIFY,
+                                       spaceAfter = 8,
+                                      )
+        
+        # Use detection results with ensemble integration
+        ensemble_result = detection_result.ensemble_result
+        
+        # Title and main sections
+        elements.append(Paragraph("AI Text Detection Analysis Report", title_style))
+        elements.append(Paragraph(f"Generated on {datetime.now().strftime('%B %d, %Y at %I:%M %p')}", styles['Normal']))
+        elements.append(Spacer(1, 0.3*inch))
+        
+        # Verdict section with ensemble metrics
+        elements.append(Paragraph("Detection Summary", heading_style))
+        verdict_data = [['Final Verdict:', ensemble_result.final_verdict],
+                        ['AI Probability:', f"{ensemble_result.ai_probability:.1%}"],
+                        ['Human Probability:', f"{ensemble_result.human_probability:.1%}"],
+                        ['Mixed Probability:', f"{ensemble_result.mixed_probability:.1%}"],
+                        ['Overall Confidence:', f"{ensemble_result.overall_confidence:.1%}"],
+                        ['Uncertainty Score:', f"{ensemble_result.uncertainty_score:.1%}"],
+                        ['Consensus Level:', f"{ensemble_result.consensus_level:.1%}"],
+                       ]
+        
+        verdict_table = Table(verdict_data, colWidths=[2*inch, 3*inch])
+        verdict_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (0, -1), colors.HexColor('#f8fafc')),
+                                           ('FONTNAME', (0, 0), (0, -1), 'Helvetica-Bold'),
+                                           ('FONTSIZE', (0, 0), (-1, -1), 10),
+                                           ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
+                                         ])
+                              )
+        
+        elements.append(verdict_table)
+        elements.append(Spacer(1, 0.2*inch))
+        
+        # Content analysis
+        elements.append(Paragraph("Content Analysis", heading_style))
+        content_data = [['Content Domain:', detection_result.domain_prediction.primary_domain.value.title()],
+                        ['Domain Confidence:', f"{detection_result.domain_prediction.confidence:.1%}"],
+                        ['Word Count:', str(detection_result.processed_text.word_count)],
+                        ['Sentence Count:', str(detection_result.processed_text.sentence_count)],
+                        ['Processing Time:', f"{detection_result.processing_time:.2f}s"],
+                       ]
+        
+        content_table = Table(content_data, colWidths=[2*inch, 3*inch])
+        content_table.setStyle(TableStyle([('FONTSIZE', (0, 0), (-1, -1), 10),
+                                           ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
+                                         ])
+                              )
+        
+        elements.append(content_table)
+        elements.append(Spacer(1, 0.2*inch))
+        
+        # Ensemble Analysis
+        elements.append(Paragraph("Ensemble Analysis", heading_style))
+        elements.append(Paragraph(f"Method: Confidence Calibrated Aggregation", styles['Normal']))
+        elements.append(Spacer(1, 0.1*inch))
+        
+        # Metric weights table
+        if hasattr(ensemble_result, 'metric_weights') and ensemble_result.metric_weights:
+            elements.append(Paragraph("Metric Weights", styles['Heading3']))
+            weight_data = [['Metric', 'Weight']]
+            for metric, weight in ensemble_result.metric_weights.items():
+                weight_data.append([metric.title(), f"{weight:.1%}"])
+            
+            weight_table = Table(weight_data, colWidths=[3*inch, 1*inch])
+            weight_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#667eea')),
+                                              ('TEXTCOLOR', (0, 0), (-1, 0), colors.white),
+                                              ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+                                              ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+                                              ('FONTSIZE', (0, 0), (-1, -1), 9),
+                                              ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
+                                              ('GRID', (0, 0), (-1, -1), 1, colors.black),
+                                            ])
+                                 )
+            elements.append(weight_table)
+            elements.append(Spacer(1, 0.2*inch))
+        
+        # Detailed metrics
+        elements.append(Paragraph("Detailed Metric Analysis", heading_style))
+        for metric in detailed_metrics:
+            elements.append(Paragraph(f"{metric.name.title().replace('_', ' ')}", styles['Heading3']))
+            metric_data = [['Verdict:', metric.verdict],
+                           ['AI Probability:', f"{metric.ai_probability:.1f}%"],
+                           ['Human Probability:', f"{metric.human_probability:.1f}%"],
+                           ['Confidence:', f"{metric.confidence:.1f}%"],
+                           ['Ensemble Weight:', f"{metric.weight:.1f}%"],
+                          ]
+            
+            metric_table = Table(metric_data, colWidths=[1.5*inch, 1.5*inch])
+            metric_table.setStyle(TableStyle([('FONTSIZE', (0, 0), (-1, -1), 9),
+                                              ('BOTTOMPADDING', (0, 0), (-1, -1), 2),
+                                            ])
+                                 )
+            
+            elements.append(metric_table)
+            elements.append(Paragraph(metric.description, body_style))
+            
+            # Add detailed sub-metrics if available
+            if metric.detailed_metrics:
+                elements.append(Paragraph("Detailed Metrics:", styles['Heading4']))
+                sub_metric_data = [['Metric', 'Value']]
+                for sub_name, sub_value in list(metric.detailed_metrics.items())[:6]:  # Show top 6
+                    sub_metric_data.append([sub_name.replace('_', ' ').title(), f"{sub_value:.2f}"])
+                
+                sub_metric_table = Table(sub_metric_data, colWidths=[2*inch, 1*inch])
+                sub_metric_table.setStyle(TableStyle([('FONTSIZE', (0, 0), (-1, -1), 8),
+                                                      ('BOTTOMPADDING', (0, 0), (-1, -1), 2),
+                                                      ('GRID', (0, 0), (-1, -1), 1, colors.grey),
+                                                    ])
+                                         )
+
+                elements.append(sub_metric_table)
+            
+            elements.append(Spacer(1, 0.1*inch))
+        
+        # Detection Reasoning
+        elements.append(Paragraph("Detection Reasoning", heading_style))
+        elements.append(Paragraph(reasoning.summary, body_style))
+        elements.append(Spacer(1, 0.1*inch))
+        
+        # Key Indicators
+        elements.append(Paragraph("Key Indicators", styles['Heading3']))
+        for indicator in reasoning.key_indicators[:5]:  # Show top 5
+            elements.append(Paragraph(f"• {indicator}", body_style))
+        
+        elements.append(Spacer(1, 0.1*inch))
+        
+        # Confidence Explanation
+        elements.append(Paragraph("Confidence Analysis", styles['Heading3']))
+        elements.append(Paragraph(reasoning.confidence_explanation, body_style))
+        elements.append(Spacer(1, 0.1*inch))
+        
+        # Uncertainty Analysis
+        elements.append(Paragraph("Uncertainty Analysis", styles['Heading3']))
+        elements.append(Paragraph(reasoning.uncertainty_analysis, body_style))
+        
+        # Model Attribution Section
+        if attribution_result:
+            elements.append(PageBreak())
+            elements.append(Paragraph("AI Model Attribution", heading_style))
+            
+            # Attribution summary
+            predicted_model = attribution_result.predicted_model.value.replace("_", " ").title()
+            confidence = attribution_result.confidence * 100
+            
+            attribution_summary = [['Predicted Model:', predicted_model],
+                                   ['Attribution Confidence:', f"{confidence:.1f}%"],
+                                   ['Domain Used:', attribution_result.domain_used.value.title()],
+                                  ]
+            
+            attribution_table = Table(attribution_summary, colWidths=[2*inch, 3*inch])
+            attribution_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (0, -1), colors.HexColor('#f8fafc')),
+                                                   ('FONTNAME', (0, 0), (0, -1), 'Helvetica-Bold'),
+                                                   ('FONTSIZE', (0, 0), (-1, -1), 10),
+                                                   ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
+                                                 ])
+                                      )
+            
+            elements.append(attribution_table)
+            elements.append(Spacer(1, 0.1*inch))
+            
+            # Model probabilities table
+            if attribution_result.model_probabilities:
+                elements.append(Paragraph("Model Probability Breakdown", styles['Heading3']))
+                
+                prob_data     = [['Model', 'Probability']]
+                
+                # Show top 5
+                sorted_models = sorted(attribution_result.model_probabilities.items(),
+                                       key     = lambda x: x[1],
+                                       reverse = True)[:5]
+                
+                for model_name, probability in sorted_models:
+                    display_name = model_name.replace("_", " ").replace("-", " ").title()
+                    prob_data.append([display_name, f"{probability:.1%}"])
+                
+                prob_table = Table(prob_data, colWidths=[3*inch, 1*inch])
+                prob_table.setStyle(TableStyle([('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#667eea')),
+                                                ('TEXTCOLOR', (0, 0), (-1, 0), colors.white),
+                                                ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+                                                ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+                                                ('FONTSIZE', (0, 0), (-1, -1), 9),
+                                                ('BOTTOMPADDING', (0, 0), (-1, -1), 4),
+                                                ('GRID', (0, 0), (-1, -1), 1, colors.black),
+                                              ])
+                                   )
+                
+                elements.append(prob_table)
+                elements.append(Spacer(1, 0.2*inch))
+            
+            # Attribution reasoning
+            if attribution_result.reasoning:
+                elements.append(Paragraph("Attribution Reasoning", styles['Heading3']))
+                for reason in attribution_result.reasoning[:3]:  # Show top 3 reasons
+                    elements.append(Paragraph(f"• {reason}", body_style))
+        
+        # Recommendations
+        elements.append(PageBreak())
+        elements.append(Paragraph("Recommendations", heading_style))
+        for recommendation in reasoning.recommendations:
+            elements.append(Paragraph(f"• {recommendation}", body_style))
+        
+        # Footer
+        elements.append(Spacer(1, 0.3*inch))
+        elements.append(Paragraph(f"Generated by AI Text Detector v2.0 | Processing Time: {detection_result.processing_time:.2f}s", 
+                                ParagraphStyle('Footer', parent=styles['Normal'], fontSize=8, textColor=colors.gray)))
+        
+        # Build PDF
+        doc.build(elements)
+        
+        logger.info(f"PDF report saved: {output_path}")
+        return output_path
+
+
+
+# Export
+__all__ = ["ReportGenerator", 
+           "DetailedMetric",
+          ]

requirements.txt

@@ -0,0 +1,98 @@
+# Core Framework
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+pydantic==2.5.0
+pydantic-settings==2.1.0
+python-multipart==0.0.6
+
+# Machine Learning & Transformers
+torch==2.1.0
+transformers==4.35.2
+sentence-transformers==2.2.2
+tokenizers==0.15.0
+
+# NLP Libraries
+spacy==3.7.2
+#flair==0.13.1
+nltk==3.8.1
+textstat==0.7.3
+
+# Scientific Computing
+numpy==1.24.3
+scipy==1.11.4
+scikit-learn==1.3.2
+pandas==2.1.3
+
+# Text Processing
+python-docx==1.1.0
+PyPDF2==3.0.1
+pdfplumber==0.10.3
+pymupdf==1.23.8
+python-magic==0.4.27
+
+# Language Detection
+langdetect==1.0.9
+#fasttext==0.9.2
+
+# Adversarial & Robustness
+#textattack==0.3.8
+
+# Visualization & Reporting
+matplotlib==3.8.2
+seaborn==0.13.0
+plotly==5.18.0
+reportlab==4.0.7
+fpdf2==2.7.6
+
+# Utilities
+python-dotenv==1.0.0
+aiofiles==23.2.1
+httpx==0.25.2
+tenacity==8.2.3
+
+# Logging & Monitoring
+loguru==0.7.2
+python-json-logger==2.0.7
+
+# Caching
+redis==5.0.1
+diskcache==5.6.3
+
+# Database (Optional)
+sqlalchemy==2.0.23
+alembic==1.13.0
+
+# Testing
+pytest==7.4.3
+pytest-asyncio==0.21.1
+pytest-cov==4.1.0
+
+# Code Quality
+black==23.12.0
+flake8==6.1.0
+mypy==1.7.1
+
+# Security
+cryptography==41.0.7
+python-jose[cryptography]==3.3.0
+
+# Performance
+orjson==3.9.10
+ujson==5.9.0
+
+# Additional ML Tools
+xgboost==2.0.2
+lightgbm==4.1.0
+
+# Dimensionality Analysis
+#scikit-dimension==0.3.5
+umap-learn==0.5.5
+
+# Rate Limiting
+slowapi==0.1.9
+
+# CORS
+fastapi-cors==0.0.6
+
+# File type detection
+python-magic-bin==0.4.14

run.sh

@@ -0,0 +1,56 @@
+#!/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

text_auth_app.py

@@ -0,0 +1,1258 @@
+# DEPENDENCIES
+import os
+import time
+import json
+import uvicorn
+import numpy as np
+from typing import Any
+from typing import List
+from typing import Dict
+from typing import Union
+from pathlib import Path
+from fastapi import File
+from fastapi import Form
+from loguru import logger
+from pydantic import Field
+from typing import Optional
+from fastapi import FastAPI
+from fastapi import Request
+from datetime import datetime
+from fastapi import UploadFile
+from pydantic import BaseModel
+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 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 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 processors.document_extractor import DocumentExtractor
+from reporter.reasoning_generator import ReasoningGenerator
+
+
+
+# ==================== CUSTOM SERIALIZATION ====================
+class NumpyJSONEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder that handles NumPy types and custom objects
+    """
+    def default(self, obj: Any) -> Any:
+        """
+        Convert non-serializable objects to JSON-serializable types
+        """
+        # NumPy types
+        if (isinstance(obj, (np.float32, np.float64))):
+            return float(obj)
+
+        elif (isinstance(obj, (np.int32, np.int64, np.int8, np.uint8))):
+            return int(obj)
+
+        elif (isinstance(obj, np.ndarray)):
+            return obj.tolist()
+
+        elif (isinstance(obj, np.bool_)):
+            return bool(obj)
+
+        elif (hasattr(obj, 'item')):  
+            # numpy scalar types
+            return obj.item()
+        
+        # Custom objects with to_dict method
+        elif (hasattr(obj, 'to_dict')):
+            return obj.to_dict()
+        
+        # Pydantic models
+        elif (hasattr(obj, 'dict')):
+            return obj.dict()
+        
+        # Handle other types
+        elif (isinstance(obj, (set, tuple))):
+            return list(obj)
+        
+        return super().default(obj)
+
+
+class NumpyJSONResponse(JSONResponse):
+    """
+    Custom JSON response that handles NumPy types
+    """
+    def render(self, content: Any) -> bytes:
+        """
+        Render content with NumPy type handling
+        """
+        return json.dumps(obj          = content,
+                          ensure_ascii = False,
+                          allow_nan    = False,
+                          indent       = None,
+                          separators   = (",", ":"),
+                          cls          = NumpyJSONEncoder,
+                         ).encode("utf-8")
+
+
+def convert_numpy_types(obj: Any) -> Any:
+    """
+    Recursively convert numpy types to Python native types
+    
+    Arguments:
+    ----------
+        obj : Any Python object that may contain NumPy types
+        
+    Returns:
+    --------
+        Object with all NumPy types converted to native Python types
+    """
+    if (obj is None):
+        return None
+    
+    # Handle dictionaries
+    if (isinstance(obj, dict)):
+        return {key: convert_numpy_types(value) for key, value in obj.items()}
+    
+    # Handle lists, tuples, sets
+    elif (isinstance(obj, (list, tuple, set))):
+        return [convert_numpy_types(item) for item in obj]
+    
+    # Handle NumPy types
+    elif (isinstance(obj, (np.float32, np.float64))):
+        return float(obj)
+    
+    elif (isinstance(obj, (np.int32, np.int64, np.int8, np.uint8))):
+        return int(obj)
+    
+    elif (isinstance(obj, np.ndarray)):
+        return obj.tolist()
+    
+    elif (isinstance(obj, np.bool_)):
+        return bool(obj)
+    
+    # numpy scalar types
+    elif (hasattr(obj, 'item')):  
+        return obj.item()
+    
+    # Handle custom objects with to_dict method
+    elif (hasattr(obj, 'to_dict')):
+        return convert_numpy_types(obj.to_dict())
+    
+    # Handle Pydantic models
+    elif (hasattr(obj, 'dict')):
+        return convert_numpy_types(obj.dict())
+    
+    # Return as-is for other types (str, int, float, bool, etc.)
+    else:
+        return obj
+
+
+def safe_serialize_response(data: Any) -> Any:
+    """
+    Safely serialize response data ensuring all types are JSON-compatible
+    
+    Arguments:
+    ----------
+        data : Response data to serialize
+        
+    Returns:
+    --------
+        Fully serializable data structure
+    """
+    return convert_numpy_types(data)
+
+
+# ==================== PYDANTIC DATACLASS MODELS ====================
+class SerializableBaseModel(BaseModel):
+    """
+    Base model with enhanced serialization for NumPy types
+    """
+    def dict(self, *args, **kwargs) -> Dict[str, Any]:
+        """
+        Override dict method to handle NumPy types
+        """
+        data = super().dict(*args, **kwargs)
+        
+        return convert_numpy_types(data)
+    
+
+    def json(self, *args, **kwargs) -> str:
+        """
+        Override json method to handle NumPy types
+        """
+        data = self.dict(*args, **kwargs)
+        
+        return json.dumps(data, cls=NumpyJSONEncoder, *args, **kwargs)
+
+
+class TextAnalysisRequest(SerializableBaseModel):
+    """
+    Request model for text analysis
+    """
+    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") 
+    include_metrics_summary : bool          = Field(True, description = "Include metrics summary in highlights")
+    generate_report         : bool          = Field(False, description = "Generate detailed PDF/JSON report")
+
+
+class TextAnalysisResponse(SerializableBaseModel):
+    """
+    Response model for text analysis
+    """
+    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
+    processing_time  : float
+    timestamp        : str
+
+
+class BatchAnalysisRequest(SerializableBaseModel):
+    """
+    Request model for batch analysis
+    """
+    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
+
+
+class BatchAnalysisResult(SerializableBaseModel):
+    """
+    Individual batch analysis result
+    """
+    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
+
+
+class BatchAnalysisResponse(SerializableBaseModel):
+    """
+    Batch analysis response
+    """
+    status          : str
+    batch_id        : str
+    total           : int
+    successful      : int
+    failed          : int
+    results         : List[BatchAnalysisResult]
+    processing_time : float
+    timestamp       : str
+
+
+class FileAnalysisResponse(SerializableBaseModel):
+    """
+    File analysis response
+    """
+    status           : str
+    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
+    processing_time  : float
+    timestamp        : str
+
+
+class HealthCheckResponse(SerializableBaseModel):
+    """
+    Health check response
+    """
+    status        : str
+    version       : str
+    uptime        : float
+    models_loaded : Dict[str, bool]
+
+
+class ReportGenerationResponse(SerializableBaseModel):
+    """
+    Report generation response
+    """
+    status      : str
+    analysis_id : str
+    reports     : Dict[str, str]
+    timestamp   : str
+
+
+class ErrorResponse(SerializableBaseModel):
+    """
+    Error response model
+    """
+    status    : str
+    error     : str
+    timestamp : str
+
+
+# ==================== FASTAPI APPLICATION ====================
+app = FastAPI(title                  = "TEXT-AUTH AI Detection API",
+              description            = "API for detecting AI-generated text",
+              version                = "1.0.0",
+              docs_url               = "/api/docs",
+              redoc_url              = "/api/redoc",
+              default_response_class = NumpyJSONResponse,
+             )
+
+# CORS Configuration
+app.add_middleware(CORSMiddleware,
+                   allow_origins     = settings.CORS_ORIGINS,
+                   allow_credentials = True,
+                   allow_methods     = ["*"],
+                   allow_headers     = ["*"],
+                  )
+
+# Mount static files
+ui_static_path = Path(__file__).parent / "ui" / "static"
+
+if ui_static_path.exists():
+    app.mount("/static", StaticFiles(directory = str(ui_static_path)), name = "static")
+
+
+# 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
+
+
+# App state
+app_start_time                                       = time.time()
+
+initialization_status                                = {"orchestrator"        : False,
+                                                        "attributor"          : False,
+                                                        "highlighter"         : False,
+                                                        "reporter"            : False,
+                                                        "reasoning_generator" : False,
+                                                        "document_extractor"  : False,
+                                                        }
+
+
+# ==================== APPLICATION LIFECYCLE ====================
+@app.on_event("startup")
+async def startup_event():
+    """
+    Initialize all components on startup
+    """
+    global orchestrator, attributor, highlighter, reporter, reasoning_generator, document_extractor
+    global initialization_status
+
+    # Initialize centralized logging first
+    if not central_logger.initialize():
+        raise RuntimeError("Failed to initialize logging system")
+    
+    logger.info("=" * 80)
+    logger.info("TEXT-AUTH API Starting Up...")
+    logger.info("=" * 80)
+    
+    try:
+        # Initialize Detection Orchestrator
+        logger.info("Initializing Detection Orchestrator...")
+        orchestrator = DetectionOrchestrator(enable_language_detection = True,
+                                             parallel_execution        = False,
+                                             skip_expensive_metrics    = False,
+                                            )
+        
+        if orchestrator.initialize():
+            initialization_status["orchestrator"] = True
+            logger.success("✓ Detection Orchestrator initialized")
+        
+        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...")
+       
+        highlighter                          = TextHighlighter()
+        
+        initialization_status["highlighter"] = True
+        
+        logger.success("✓ Text Highlighter initialized")
+        
+        # Initialize Report Generator
+        logger.info("Initializing Report Generator...")
+        
+        reporter                          = ReportGenerator()
+        
+        initialization_status["reporter"] = True
+        
+        logger.success("✓ Report Generator initialized")
+        
+        # Initialize Reasoning Generator
+        logger.info("Initializing Reasoning Generator...")
+        
+        reasoning_generator                          = ReasoningGenerator()
+        
+        initialization_status["reasoning_generator"] = True
+        
+        logger.success("✓ Reasoning Generator initialized")
+        
+        # Initialize Document Extractor
+        logger.info("Initializing Document Extractor...")
+        
+        document_extractor                          = DocumentExtractor()
+        
+        initialization_status["document_extractor"] = True
+        
+        logger.success("✓ Document Extractor initialized")
+        
+        logger.info("=" * 80)
+        logger.success("TEXT-AUTH API Ready!")
+        logger.info(f"Server: {settings.HOST}:{settings.PORT}")
+        logger.info(f"Environment: {settings.ENVIRONMENT}")
+        logger.info(f"Device: {settings.DEVICE}")
+        logger.info("=" * 80)
+        
+    except Exception as e:
+        logger.error(f"Startup failed: {e}")
+        raise
+
+
+# Cleanup in shutdown
+@app.on_event("shutdown")
+async def shutdown_event():
+    """
+    Cleanup on shutdown
+    """
+    central_logger.cleanup()
+    
+    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",
+                    Domain.ACADEMIC      : "Academic papers, essays, research",
+                    Domain.CREATIVE      : "Creative writing, fiction, poetry",
+                    Domain.AI_ML         : "AI/ML research papers, technical content",
+                    Domain.SOFTWARE_DEV  : "Software development, code, documentation",
+                    Domain.TECHNICAL_DOC : "Technical documentation, manuals, specs",
+                    Domain.ENGINEERING   : "Engineering documents, technical reports",
+                    Domain.SCIENCE       : "Scientific papers, research articles",
+                    Domain.BUSINESS      : "Business documents, reports, proposals",
+                    Domain.LEGAL         : "Legal documents, contracts, court filings",
+                    Domain.MEDICAL       : "Medical documents, clinical notes, research",
+                    Domain.JOURNALISM    : "News articles, journalistic content",
+                    Domain.MARKETING     : "Marketing copy, advertisements, campaigns",
+                    Domain.SOCIAL_MEDIA  : "Social media posts, blogs, casual writing",
+                    Domain.BLOG_PERSONAL : "Personal blogs, diary entries",
+                    Domain.TUTORIAL      : "Tutorials, how-to guides, educational content",
+                   }
+
+    return descriptions.get(domain, "")
+
+
+def _parse_domain(domain_str: Optional[str]) -> Optional[Domain]:
+    """
+    Parse domain string to Domain enum with comprehensive alias support
+    """
+    if not domain_str:
+        return None
+    
+    # First try exact match
+    try:
+        return Domain(domain_str.lower())
+    
+    except ValueError:
+        # Comprehensive domain mapping with aliases for all 16 domains
+        domain_mapping = {'general'                : Domain.GENERAL,
+                          'default'                : Domain.GENERAL,
+                          'generic'                : Domain.GENERAL,
+                          'academic'               : Domain.ACADEMIC,
+                          'education'              : Domain.ACADEMIC,
+                          'research'               : Domain.ACADEMIC,
+                          'university'             : Domain.ACADEMIC,
+                          'scholarly'              : Domain.ACADEMIC,
+                          'creative'               : Domain.CREATIVE,
+                          'fiction'                : Domain.CREATIVE,
+                          'literature'             : Domain.CREATIVE,
+                          'story'                  : Domain.CREATIVE,
+                          'narrative'              : Domain.CREATIVE,
+                          'ai_ml'                  : Domain.AI_ML,
+                          'ai'                     : Domain.AI_ML,
+                          'machinelearning'        : Domain.AI_ML,
+                          'ml'                     : Domain.AI_ML,
+                          'artificialintelligence' : Domain.AI_ML,
+                          'neural'                 : Domain.AI_ML,
+                          'software_dev'           : Domain.SOFTWARE_DEV,
+                          'software'               : Domain.SOFTWARE_DEV,
+                          'code'                   : Domain.SOFTWARE_DEV,
+                          'programming'            : Domain.SOFTWARE_DEV,
+                          'development'            : Domain.SOFTWARE_DEV,
+                          'dev'                    : Domain.SOFTWARE_DEV,
+                          'technical_doc'          : Domain.TECHNICAL_DOC,
+                          'technical'              : Domain.TECHNICAL_DOC,
+                          'tech'                   : Domain.TECHNICAL_DOC,
+                          'documentation'          : Domain.TECHNICAL_DOC,
+                          'docs'                   : Domain.TECHNICAL_DOC,
+                          'manual'                 : Domain.TECHNICAL_DOC,
+                          'engineering'            : Domain.ENGINEERING,
+                          'engineer'               : Domain.ENGINEERING,
+                          'technical_engineering'  : Domain.ENGINEERING,
+                          'science'                : Domain.SCIENCE,
+                          'scientific'             : Domain.SCIENCE,
+                          'research_science'       : Domain.SCIENCE,
+                          'business'               : Domain.BUSINESS,
+                          'corporate'              : Domain.BUSINESS,
+                          'commercial'             : Domain.BUSINESS,
+                          'enterprise'             : Domain.BUSINESS,
+                          'legal'                  : Domain.LEGAL,
+                          'law'                    : Domain.LEGAL,
+                          'contract'               : Domain.LEGAL,
+                          'court'                  : Domain.LEGAL,
+                          'juridical'              : Domain.LEGAL,
+                          'medical'                : Domain.MEDICAL,
+                          'healthcare'             : Domain.MEDICAL,
+                          'clinical'               : Domain.MEDICAL,
+                          'medicine'               : Domain.MEDICAL,
+                          'health'                 : Domain.MEDICAL,
+                          'journalism'             : Domain.JOURNALISM,
+                          'news'                   : Domain.JOURNALISM,
+                          'reporting'              : Domain.JOURNALISM,
+                          'media'                  : Domain.JOURNALISM,
+                          'press'                  : Domain.JOURNALISM,
+                          'marketing'              : Domain.MARKETING,
+                          'advertising'            : Domain.MARKETING,
+                          'promotional'            : Domain.MARKETING,
+                          'brand'                  : Domain.MARKETING,
+                          'sales'                  : Domain.MARKETING,
+                          'social_media'           : Domain.SOCIAL_MEDIA,
+                          'social'                 : Domain.SOCIAL_MEDIA,
+                          'casual'                 : Domain.SOCIAL_MEDIA,
+                          'informal'               : Domain.SOCIAL_MEDIA,
+                          'posts'                  : Domain.SOCIAL_MEDIA,
+                          'blog_personal'          : Domain.BLOG_PERSONAL,
+                          'blog'                   : Domain.BLOG_PERSONAL,
+                          'personal'               : Domain.BLOG_PERSONAL,
+                          'diary'                  : Domain.BLOG_PERSONAL,
+                          'lifestyle'              : Domain.BLOG_PERSONAL,
+                          'tutorial'               : Domain.TUTORIAL,
+                          'guide'                  : Domain.TUTORIAL,
+                          'howto'                  : Domain.TUTORIAL,
+                          'instructional'          : Domain.TUTORIAL,
+                          'educational'            : Domain.TUTORIAL,
+                          'walkthrough'            : Domain.TUTORIAL,
+                         }
+        
+        normalized_domain = domain_str.lower().strip()
+        
+        if normalized_domain in domain_mapping:
+            return domain_mapping[normalized_domain]
+        
+        # Try to match with underscores/spaces variations
+        normalized_with_underscores = normalized_domain.replace(' ', '_')
+        if normalized_with_underscores in domain_mapping:
+            return domain_mapping[normalized_with_underscores]
+        
+        # Try partial matching for more flexibility
+        for alias, domain_enum in domain_mapping.items():
+            if normalized_domain in alias or alias in normalized_domain:
+                return domain_enum
+        
+        return None
+
+
+def _validate_file_extension(filename: str) -> str:
+    """
+    Validate file extension and return normalized extension
+    """
+    file_extension     = Path(filename).suffix.lower()
+    allowed_extensions = ['.txt', 
+                          '.pdf', 
+                          '.docx', 
+                          '.doc', 
+                          '.md',
+                         ]
+    
+    if file_extension not in allowed_extensions:
+        raise HTTPException(status_code = 400,
+                            detail      = f"Unsupported file type. Allowed: {', '.join(allowed_extensions)}",
+                           )
+    
+    return file_extension
+
+
+def _generate_reasoning(detection_result: DetectionResult, attribution_result: Optional[AttributionResult] = None) -> Dict[str, Any]:
+    """
+    Generate detailed reasoning for detection results
+    """
+    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,
+                                                )
+
+        return safe_serialize_response(reasoning.to_dict())
+
+    except Exception as e:
+        logger.warning(f"Reasoning generation failed: {e}")
+        return {}
+
+
+def _generate_reports(detection_result: DetectionResult, attribution_result: Optional[AttributionResult] = None, 
+                     highlighted_sentences: Optional[List] = None, analysis_id: str = None) -> Dict[str, str]:
+    """
+    Generate reports for detection results
+    """
+    if not reporter:
+        return {}
+    
+    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)}",
+                                                        )
+        return report_files
+
+    except Exception as e:
+        logger.warning(f"Report generation failed: {e}")
+        return {}
+
+
+# ==================== ROOT & HEALTH ENDPOINTS ====================
+@app.get("/", response_class = HTMLResponse)
+async def root():
+    """
+    Serve the main web interface
+    """
+    # Serve the updated index.html directly from the current directory
+    index_path = Path(__file__).parent / "index.html"
+    
+    if index_path.exists():
+        with open(index_path, 'r', encoding='utf-8') as f:
+            return HTMLResponse(content=f.read())
+    
+    # Fallback to static directory if exists
+    ui_static_path = Path(__file__).parent / "ui" / "static"
+    index_path = ui_static_path / "index.html"
+    
+    if index_path.exists():
+        with open(index_path, 'r', encoding='utf-8') as f:
+            return HTMLResponse(content=f.read())
+    
+    return HTMLResponse(content = """
+                                      <html>
+                                          <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><a href="/api/docs">API Documentation</a></p>
+                                              <p><a href="/health">Health Check</a></p>
+                                          </body>
+                                      </html>
+                                  """
+                       )
+
+
+@app.get("/health", response_model = HealthCheckResponse)
+async def health_check():
+    """
+    Health check endpoint
+    """
+    return HealthCheckResponse(status        = "healthy" if all(initialization_status.values()) else "degraded",
+                               version       = "2.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
+    """
+    if not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    start_time  = time.time()
+    analysis_id = f"analysis_{int(time.time() * 1000)}"
+    
+    try:
+        # Parse domain if provided
+        domain = _parse_domain(request.domain)
+        
+        if (request.domain and not domain):
+            raise HTTPException(status_code = 400,
+                                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)")
+        
+        detection_result = orchestrator.analyze(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())
+        
+        # Attribution (if enabled)
+        attribution_result = None
+        attribution_dict   = None
+        
+        if (request.enable_attribution and attributor):
+            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())
+
+            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:
+            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,
+                                                                        use_sentence_level = request.use_sentence_level,
+                                                                       )
+
+                # FIXED: Set include_legend=False to prevent duplicate legends
+                highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                  include_legend        = False,  # UI already has its own legend
+                                                                  include_metrics       = request.include_metrics_summary,
+                                                                 )
+            except Exception as e:
+                logger.warning(f"Highlighting failed: {e}")
+        
+        # Generate reasoning
+        reasoning_dict = _generate_reasoning(detection_result, attribution_result)
+        
+        # Generate reports (if requested)
+        report_files = {}
+        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,
+                                                )
+
+            except Exception as e:
+                logger.warning(f"Report generation failed: {e}")
+        
+        processing_time = time.time() - start_time
+        
+        #logger.success(f"[{analysis_id}] Analysis complete: {detection_result.ensemble_result.final_verdict} ({processing_time:.2f}s)")
+        
+        # Log the detection event
+        log_detection_event(analysis_id         = analysis_id,
+                            text_length         = len(request.text),
+                            verdict             = detection_result.ensemble_result.final_verdict,
+                            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,
+                                    processing_time  = processing_time,
+                                    timestamp        = datetime.now().isoformat(),
+                                   )
+        
+    except HTTPException:
+        central_logger.log_error("TextAnalysisError",
+                                 f"Analysis failed for request",
+                                 {"text_length": len(request.text)},
+                                 e,
+                                )
+
+        raise
+
+    except Exception as e:
+        logger.error(f"[{analysis_id}] Analysis failed: {e}")
+        raise HTTPException(status_code = 500, 
+                            detail      = str(e),
+                           )
+
+
+@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)):
+    """
+    Analyze uploaded document (PDF, DOCX, TXT)
+    """
+    if not document_extractor or not orchestrator:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    start_time  = time.time()
+    analysis_id = f"file_{int(time.time() * 1000)}"
+    
+    try:
+        # Validate file
+        file_ext      = _validate_file_extension(file.filename)
+        
+        # Read and extract text
+        logger.info(f"[{analysis_id}] Extracting text from {file.filename}")
+        file_bytes    = await file.read()
+        
+        extracted_doc = document_extractor.extract_from_bytes(file_bytes = file_bytes,
+                                                              filename   = file.filename,
+                                                             )
+        
+        if not extracted_doc.is_success or not extracted_doc.text:
+            raise HTTPException(status_code = 400,
+                                detail      = f"Text extraction failed: {extracted_doc.error_message}"
+                               )
+        
+        logger.info(f"[{analysis_id}] Extracted {len(extracted_doc.text)} characters")
+        
+        # Parse domain and analyze
+        domain_enum      = _parse_domain(domain)
+        
+        detection_result = orchestrator.analyze(text           = extracted_doc.text,
+                                                domain         = domain_enum,
+                                                skip_expensive = skip_expensive_metrics,
+                                               )
+        
+        # Convert to serializable dict
+        detection_dict   = safe_serialize_response(detection_result.to_dict())
+        
+        # Attribution
+        attribution_result = None
+        attribution_dict   = None
+        
+        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
+        highlighted_sentences = None
+        highlighted_html      = None
+
+        if highlighter:
+            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,
+                                                                       )
+
+                # FIXED: Set include_legend=False to prevent duplicate legends
+                highlighted_html      = highlighter.generate_html(highlighted_sentences = highlighted_sentences,
+                                                                  include_legend        = False,  # UI already has its own legend
+                                                                  include_metrics       = include_metrics_summary,
+                                                                 )
+            except Exception as e:
+                logger.warning(f"Highlighting failed: {e}")
+        
+        # Generate reasoning
+        reasoning_dict = _generate_reasoning(detection_result, attribution_result)
+        
+        # Generate reports (if requested)
+        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,
+                                                )
+            except Exception as e:
+                logger.warning(f"Report generation failed: {e}")
+        
+        processing_time = time.time() - start_time
+        
+        return FileAnalysisResponse(status           = "success",
+                                    analysis_id      = analysis_id,
+                                    file_info        = {"filename"          : file.filename,
+                                                        "file_type"         : file_ext,
+                                                        "pages"             : extracted_doc.page_count,
+                                                        "extraction_method" : extracted_doc.extraction_method,
+                                                        "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,
+                                    processing_time  = processing_time,
+                                    timestamp        = datetime.now().isoformat(),
+                                   )
+        
+    except HTTPException:
+        raise
+
+    except Exception as e:
+        logger.error(f"[{analysis_id}] File analysis failed: {e}")
+        raise HTTPException(status_code = 500, 
+                            detail      = str(e),
+                           )
+
+
+@app.post("/api/analyze/batch", response_model = BatchAnalysisResponse)
+async def batch_analyze(request: BatchAnalysisRequest):
+    """
+    Analyze multiple texts in batch
+    
+    Limits : 1-100 texts per request
+    """
+    if not orchestrator:
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
+    
+    if (len(request.texts) > 100):
+        raise HTTPException(status_code = 400, 
+                            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)
+        
+        logger.info(f"[{batch_id}] Processing {len(request.texts)} texts")
+        
+        results = []
+        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,
+                                                                )
+
+                        attribution_dict   = safe_serialize_response(attribution_result.to_dict())
+
+                    except Exception:
+                        pass
+                
+                # Generate reasoning
+                reasoning_dict = _generate_reasoning(detection_result, attribution_result)
+                
+                # Generate reports if requested
+                report_files = {}
+                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
+                
+                results.append(BatchAnalysisResult(index        = i,
+                                                   status       = "success",
+                                                   detection    = detection_dict,
+                                                   attribution  = attribution_dict,
+                                                   reasoning    = reasoning_dict,
+                                                   report_files = report_files,
+                                                  )
+                              )
+                
+            except Exception as e:
+                logger.error(f"[{batch_id}] Text {i} failed: {e}")
+                results.append(BatchAnalysisResult(index  = i,
+                                                   status = "error",
+                                                   error  = str(e),
+                                                  )
+                              )
+        
+        processing_time = time.time() - start_time
+        success_count   = sum(1 for r in results if r.status == "success")
+        
+        logger.success(f"[{batch_id}] Batch complete: {success_count}/{len(request.texts)} successful")
+        
+        return BatchAnalysisResponse(status          = "success",
+                                     batch_id        = batch_id,
+                                     total           = len(request.texts),
+                                     successful      = success_count,
+                                     failed          = len(request.texts) - success_count,
+                                     results         = results,
+                                     processing_time = processing_time,
+                                     timestamp       = datetime.now().isoformat(),
+                                    )
+        
+    except Exception as e:
+        logger.error(f"[{batch_id}] Batch analysis failed: {e}")
+        raise HTTPException(status_code = 500, 
+                            detail      = str(e),
+                           )
+
+
+# ==================== REPORT GENERATION ENDPOINTS ====================
+@app.post("/api/report/generate", response_model = ReportGenerationResponse)
+async def generate_report(background_tasks: BackgroundTasks, analysis_id: str = Form(...), text: str = Form(...),  formats: str = Form("json,pdf"), 
+                          include_highlights: bool = Form(True)):
+    """
+    Generate detailed report for an analysis
+    """
+    if not orchestrator or not reporter:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    
+    try:
+        # Parse formats
+        requested_formats = [f.strip() for f in formats.split(',')]
+        valid_formats     = ['json', 'pdf']  # Only JSON and PDF supported now
+        
+        for fmt in requested_formats:
+            if fmt not in valid_formats:
+                raise HTTPException(status_code = 400,
+                                    detail      = f"Invalid format '{fmt}'. Valid: {', '.join(valid_formats)}",
+                                   )
+        
+        # Analyze text
+        logger.info(f"Generating report for {analysis_id}")
+        
+        detection_result   = orchestrator.analyze(text = text)
+        
+        # Attribution
+        attribution_result = None
+        if 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,
+                                                         )
+
+            except Exception as e:
+                logger.warning(f"Attribution failed: {e}")
+        
+        # Generate highlights for PDF reports if requested
+        highlighted_sentences = None
+        
+        if (include_highlights and highlighter and 'pdf' in requested_formats):
+            try:
+                highlighted_sentences = highlighter.generate_highlights(text               = text,
+                                                                        metric_results     = detection_result.metric_results,
+                                                                        ensemble_result    = detection_result.ensemble_result,
+                                                                       )
+
+            except Exception as e:
+                logger.warning(f"Highlight generation for report failed: {e}")
+        
+        # Generate reports
+        report_files = reporter.generate_complete_report(detection_result      = detection_result,
+                                                         attribution_result    = attribution_result,
+                                                         highlighted_sentences = highlighted_sentences,
+                                                         formats               = requested_formats,
+                                                         filename_prefix       = analysis_id,
+                                                        )
+        
+        return ReportGenerationResponse(status      = "success",
+                                        analysis_id = analysis_id,
+                                        reports     = report_files,
+                                        timestamp   = datetime.now().isoformat(),
+                                       )
+        
+    except HTTPException:
+        raise
+
+    except Exception as e:
+        logger.error(f"Report generation failed: {e}")
+        raise HTTPException(status_code = 500, 
+                            detail      = str(e),
+                           )
+
+
+@app.get("/api/report/download/{filename}")
+async def download_report(filename: str):
+    """
+    Download a generated report
+    """
+    if not reporter:
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
+    
+    file_path = reporter.output_dir / filename
+    
+    if not file_path.exists():
+        raise HTTPException(status_code = 404, 
+                            detail      = "Report not found",
+                           )
+    
+    return FileResponse(path       = str(file_path),
+                        filename   = filename,
+                        media_type = "application/octet-stream",
+                       )
+
+
+# ==================== UTILITY ENDPOINTS ====================
+@app.get("/api/domains")
+async def list_domains():
+    """
+    List all supported domains
+    """
+    domains_list = list()
+
+    for domain in Domain:
+        domains_list.append({"value"       : domain.value,
+                             "name"        : domain.value.replace('_', ' ').title(),
+                             "description" : _get_domain_description(domain),
+                           })
+    
+    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]
+                       ]
+           }
+
+
+# ==================== ERROR HANDLERS ====================
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    """
+    Handle HTTP exceptions
+    """
+    return NumpyJSONResponse(status_code = exc.status_code,
+                             content     = ErrorResponse(status    = "error",
+                                                         error     = exc.detail,
+                                                         timestamp = datetime.now().isoformat(),
+                                                        ).dict()
+                            )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request, exc):
+    """
+    Handle general exceptions
+    """
+    logger.error(f"Unhandled exception: {exc}")
+    return NumpyJSONResponse(status_code = 500,
+                             content     = ErrorResponse(status    = "error",
+                                                         error     = "Internal server error",
+                                                         timestamp = datetime.now().isoformat(),
+                                                        ).dict()
+                            )
+
+
+# Add middleware for API request logging
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    start_time   = time.time()
+    response     = await call_next(request)
+    process_time = time.time() - start_time
+    
+    log_api_request(method      = request.method,
+                    path        = request.url.path,
+                    status_code = response.status_code,
+                    duration    = process_time,
+                    ip          = request.client.host if request.client else None,
+                   )
+    
+    return response
+
+
+
+
+# ==================== MAIN ====================
+if __name__ == "__main__":
+    # Configure logging
+    log_level = settings.LOG_LEVEL.lower()
+    
+    logger.info("Starting TEXT-AUTH API Server...")
+    
+    uvicorn.run("text_auth_app:app",
+                host       = settings.HOST,
+                port       = settings.PORT,
+                reload     = settings.DEBUG,
+                log_level  = log_level,
+                workers    = 1 if settings.DEBUG else settings.WORKERS,
+               )

ui/static/index.html

@@ -0,0 +1,2200 @@
+<!DOCTYPE html>
+<html lang="en">
+<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>
+<style>
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+:root {
+    --primary: #06b6d4;
+    --primary-dark: #0891b2;
+    --secondary: #3b82f6;
+    --success: #10b981;
+    --warning: #f59e0b;
+    --danger: #ef4444;
+    --bg-dark: #0f172a;
+    --bg-darker: #020617;
+    --bg-panel: rgba(30, 41, 59, 0.95);
+    --text-primary: #f1f5f9;
+    --text-secondary: #94a3b8;
+    --text-muted: #64748b;
+    --border: rgba(71, 85, 105, 0.5);
+}
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: linear-gradient(135deg, #0f172a 0%, #1e293b 50%, #0f172a 100%);
+    color: var(--text-primary);
+    line-height: 1.6;
+    min-height: 100vh;
+}
+/* Header */
+.header {
+    background: rgba(15, 23, 42, 0.98);
+    backdrop-filter: blur(10px);
+    padding: 1rem 2rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    border-bottom: 1px solid var(--border);
+    position: sticky;
+    top: 0;
+    z-index: 1000;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+.logo {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: #fff;
+    text-decoration: none;
+}
+.logo-icon {
+    width: 40px;
+    height: 40px;
+    background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
+    border-radius: 10px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.5rem;
+    box-shadow: 0 4px 12px rgba(6, 182, 212, 0.3);
+}
+.nav-links {
+    display: flex;
+    gap: 2rem;
+    align-items: center;
+}
+.nav-link {
+    color: var(--text-secondary);
+    text-decoration: none;
+    font-weight: 500;
+    transition: color 0.3s;
+    cursor: pointer;
+}
+.nav-link:hover {
+    color: var(--primary);
+}
+.try-btn {
+    background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
+    color: #fff;
+    padding: 0.75rem 1.5rem;
+    border-radius: 8px;
+    font-weight: 600;
+    border: none;
+    cursor: pointer;
+    transition: transform 0.3s, box-shadow 0.3s;
+    text-decoration: none;
+    display: inline-block;
+}
+.try-btn:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 20px rgba(6, 182, 212, 0.4);
+}
+/* Landing Page */
+.landing-page {
+    display: block;
+}
+.hero {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 6rem 2rem 4rem;
+    text-align: center;
+}
+.hero-title {
+    font-size: 3.5rem;
+    font-weight: 800;
+    margin-bottom: 1.5rem;
+    background: linear-gradient(135deg, #fff 0%, var(--primary) 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+    line-height: 1.2;
+}
+.hero-subtitle {
+    font-size: 1.5rem;
+    color: var(--text-secondary);
+    margin-bottom: 1rem;
+}
+.hero-description {
+    font-size: 1.1rem;
+    color: var(--text-muted);
+    max-width: 700px;
+    margin: 0 auto 3rem;
+}
+.accuracy-badge {
+    display: inline-block;
+    background: linear-gradient(135deg, rgba(16, 185, 129, 0.2) 0%, rgba(6, 182, 212, 0.2) 100%);
+    border: 2px solid var(--success);
+    padding: 1rem 2rem;
+    border-radius: 12px;
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--success);
+    margin-bottom: 2rem;
+}
+.stats-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 2rem;
+    max-width: 1000px;
+    margin: 4rem auto;
+    padding: 0 2rem;
+}
+.stat-card {
+    background: var(--bg-panel);
+    padding: 2rem;
+    border-radius: 16px;
+    border: 1px solid var(--border);
+    text-align: center;
+}
+.stat-value {
+    font-size: 2.5rem;
+    font-weight: 800;
+    color: var(--primary);
+    margin-bottom: 0.5rem;
+}
+.stat-label {
+    color: var(--text-secondary);
+    font-size: 0.95rem;
+}
+/* Features Section */
+.features-section {
+    max-width: 1200px;
+    margin: 6rem auto;
+    padding: 0 2rem;
+}
+.section-title {
+    font-size: 2.5rem;
+    font-weight: 700;
+    text-align: center;
+    margin-bottom: 1rem;
+}
+.section-subtitle {
+    text-align: center;
+    color: var(--text-secondary);
+    font-size: 1.1rem;
+    margin-bottom: 4rem;
+}
+.features-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+    gap: 2rem;
+}
+.feature-card {
+    background: var(--bg-panel);
+    padding: 2.5rem;
+    border-radius: 16px;
+    border: 1px solid var(--border);
+    transition: transform 0.3s, box-shadow 0.3s;
+}
+.feature-card:hover {
+    transform: translateY(-5px);
+    box-shadow: 0 10px 30px rgba(6, 182, 212, 0.2);
+}
+.feature-icon {
+    font-size: 2.5rem;
+    margin-bottom: 1rem;
+}
+.feature-title {
+    font-size: 1.4rem;
+    font-weight: 700;
+    margin-bottom: 1rem;
+    color: #fff;
+}
+.feature-description {
+    color: var(--text-secondary);
+    line-height: 1.6;
+}
+/* Metrics Section */
+.metrics-info {
+    max-width: 1200px;
+    margin: 6rem auto;
+    padding: 0 2rem;
+}
+.metric-card {
+    background: var(--bg-panel);
+    padding: 2rem;
+    border-radius: 12px;
+    border: 1px solid var(--border);
+    margin-bottom: 1.5rem;
+    display: grid;
+    grid-template-columns: 100px 1fr;
+    gap: 2rem;
+    align-items: center;
+}
+.metric-icon-box {
+    width: 80px;
+    height: 80px;
+    background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
+    border-radius: 12px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 2rem;
+}
+.metric-content h3 {
+    font-size: 1.3rem;
+    margin-bottom: 0.5rem;
+    color: #fff;
+}
+.metric-weight {
+    display: inline-block;
+    background: rgba(6, 182, 212, 0.2);
+    padding: 0.25rem 0.75rem;
+    border-radius: 6px;
+    font-size: 0.85rem;
+    color: var(--primary);
+    font-weight: 600;
+    margin-left: 0.5rem;
+}
+/* Analysis Interface */
+.analysis-interface {
+    display: none;
+    max-width: 1600px;
+    margin: 2rem auto;
+    padding: 0 2rem 2rem;
+}
+.interface-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 2rem;
+    align-items: start;
+}
+.panel {
+    background: var(--bg-panel);
+    border-radius: 16px;
+    padding: 2rem;
+    border: 1px solid var(--border);
+    backdrop-filter: blur(10px);
+}
+.panel-title {
+    font-size: 1.5rem;
+    font-weight: 700;
+    margin-bottom: 1.5rem;
+    color: #fff;
+}
+.input-tabs {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 1.5rem;
+}
+.input-tab {
+    flex: 1;
+    padding: 0.75rem 1rem;
+    background: rgba(51, 65, 85, 0.6);
+    border: none;
+    border-radius: 8px;
+    color: var(--text-secondary);
+    cursor: pointer;
+    font-size: 0.95rem;
+    font-weight: 600;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    transition: all 0.3s;
+}
+.input-tab.active {
+    background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
+    color: #fff;
+}
+.input-tab:hover:not(.active) {
+    background: rgba(71, 85, 105, 0.8);
+}
+.tab-content {
+    display: none;
+}
+.tab-content.active {
+    display: block;
+}
+.text-input {
+    width: 100%;
+    min-height: 450px;
+    padding: 1rem;
+    background: rgba(15, 23, 42, 0.8);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--text-primary);
+    font-size: 0.95rem;
+    line-height: 1.8;
+    resize: vertical;
+    font-family: inherit;
+}
+.text-input::placeholder {
+    color: var(--text-muted);
+}
+.text-input:focus {
+    outline: none;
+    border-color: var(--primary);
+}
+.file-upload-area {
+    border: 2px dashed var(--border);
+    border-radius: 8px;
+    padding: 3rem;
+    text-align: center;
+    cursor: pointer;
+    transition: all 0.3s;
+    background: rgba(15, 23, 42, 0.5);
+}
+.file-upload-area:hover {
+    border-color: var(--primary);
+    background: rgba(6, 182, 212, 0.05);
+}
+.file-upload-area.drag-over {
+    border-color: var(--primary);
+    background: rgba(6, 182, 212, 0.1);
+}
+.file-upload-icon {
+    font-size: 3rem;
+    margin-bottom: 1rem;
+}
+.file-input {
+    display: none;
+}
+.file-name-display {
+    margin-top: 1rem;
+    padding: 0.75rem;
+    background: rgba(6, 182, 212, 0.1);
+    border-radius: 6px;
+    color: var(--primary);
+    display: none;
+}
+.options-section {
+    margin: 1.5rem 0;
+    padding: 1rem;
+    background: rgba(51, 65, 85, 0.3);
+    border-radius: 8px;
+}
+.option-row {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin-bottom: 0.75rem;
+}
+.option-row:last-child {
+    margin-bottom: 0;
+}
+.option-label {
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+    flex: 1;
+}
+select {
+    background: rgba(15, 23, 42, 0.8);
+    border: 1px solid var(--border);
+    padding: 0.5rem;
+    border-radius: 6px;
+    color: var(--text-primary);
+    font-size: 0.9rem;
+    cursor: pointer;
+}
+select:focus {
+    outline: none;
+    border-color: var(--primary);
+}
+.checkbox-wrapper {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+input[type="checkbox"] {
+    width: 18px;
+    height: 18px;
+    cursor: pointer;
+}
+.analyze-btn {
+    width: 100%;
+    padding: 1rem;
+    margin-top: 1.5rem;
+    background: linear-gradient(135deg, var(--primary) 0%, var(--primary-dark) 100%);
+    color: #fff;
+    border: none;
+    border-radius: 8px;
+    font-size: 1rem;
+    font-weight: 700;
+    cursor: pointer;
+    transition: all 0.3s;
+}
+.analyze-btn:hover:not(:disabled) {
+    transform: translateY(-2px);
+    box-shadow: 0 10px 25px rgba(6, 182, 212, 0.3);
+}
+.analyze-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    transform: none;
+}
+/* Report Tabs */
+.report-tabs {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 1.5rem;
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 0.5rem;
+}
+.report-tab {
+    padding: 0.75rem 1rem;
+    background: none;
+    border: none;
+    color: var(--text-secondary);
+    cursor: pointer;
+    font-size: 0.95rem;
+    font-weight: 600;
+    border-bottom: 3px solid transparent;
+    transition: all 0.3s;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+.report-tab.active {
+    color: var(--primary);
+    border-bottom-color: var(--primary);
+}
+.report-content {
+    display: none;
+}
+.report-content.active {
+    display: block;
+}
+/* Empty State */
+.empty-state {
+    text-align: center;
+    padding: 4rem 2rem;
+}
+.empty-icon {
+    width: 80px;
+    height: 80px;
+    margin: 0 auto 1.5rem;
+    background: linear-gradient(135deg, var(--primary) 0%, var(--secondary) 100%);
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 2.5rem;
+}
+.empty-title {
+    font-size: 1.5rem;
+    font-weight: 700;
+    margin-bottom: 1rem;
+    color: #fff;
+}
+.empty-description {
+    color: var(--text-secondary);
+    line-height: 1.6;
+}
+/* Loading State */
+.loading {
+    text-align: center;
+    padding: 3rem;
+}
+.spinner {
+    width: 50px;
+    height: 50px;
+    border: 4px solid rgba(71, 85, 105, 0.3);
+    border-top-color: var(--primary);
+    border-radius: 50%;
+    animation: spin 1s linear infinite;
+    margin: 0 auto 1rem;
+}
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+/* Result Summary */
+.result-summary {
+    text-align: center;
+    padding: 2rem 0;
+}
+.gauge-container {
+    width: 220px;
+    height: 220px;
+    margin: 0 auto 2rem;
+    position: relative;
+}
+.gauge-circle {
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    background: conic-gradient(var(--gauge-color) 0deg, var(--gauge-color) var(--gauge-degree), rgba(51, 65, 85, 0.3) var(--gauge-degree));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+}
+.gauge-inner {
+    width: 170px;
+    height: 170px;
+    background: var(--bg-panel);
+    border-radius: 50%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+}
+.gauge-value {
+    font-size: 3rem;
+    font-weight: 800;
+    color: var(--gauge-color);
+}
+.gauge-label {
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+    margin-top: 0.25rem;
+}
+.result-info-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr 1fr;
+    gap: 1.5rem;
+    margin: 2rem 0;
+}
+.info-card {
+    background: rgba(51, 65, 85, 0.3);
+    padding: 1.5rem;
+    border-radius: 10px;
+    border: 1px solid var(--border);
+}
+.info-label {
+    font-size: 0.85rem;
+    color: var(--text-secondary);
+    margin-bottom: 0.5rem;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+.info-value {
+    font-size: 1.4rem;
+    font-weight: 700;
+    color: #fff;
+}
+.confidence-badge {
+    display: inline-block;
+    padding: 0.4rem 1rem;
+    border-radius: 6px;
+    font-size: 0.9rem;
+    font-weight: 600;
+}
+.confidence-high {
+    background: rgba(16, 185, 129, 0.2);
+    color: var(--success);
+}
+.confidence-medium {
+    background: rgba(245, 158, 11, 0.2);
+    color: var(--warning);
+}
+.confidence-low {
+    background: rgba(239, 68, 68, 0.2);
+    color: var(--danger);
+}
+/* Reasoning Box */
+.reasoning-box {
+    background: rgba(51, 65, 85, 0.4);
+    padding: 1.5rem;
+    border-radius: 10px;
+    border-left: 4px solid var(--primary);
+    margin-top: 2rem;
+}
+.reasoning-title {
+    font-weight: 700;
+    margin-bottom: 1rem;
+    color: var(--primary);
+    font-size: 1.1rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+.reasoning-text {
+    color: var(--text-secondary);
+    line-height: 1.7;
+}
+
+/* Enhanced Reasoning Styles */
+.reasoning-box.enhanced {
+    background: linear-gradient(135deg, rgba(30, 41, 59, 0.95) 0%, rgba(15, 23, 42, 0.95) 100%);
+    border: 1px solid rgba(71, 85, 105, 0.5);
+    border-radius: 12px;
+    padding: 1.5rem;
+    margin-top: 2rem;
+    backdrop-filter: blur(10px);
+}
+
+.reasoning-header {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin-bottom: 1rem;
+}
+
+.reasoning-icon {
+    font-size: 1.5rem;
+}
+
+.reasoning-title {
+    font-size: 1.1rem;
+    font-weight: 700;
+    color: var(--primary);
+    flex: 1;
+}
+
+.confidence-tag {
+    padding: 0.25rem 0.75rem;
+    border-radius: 20px;
+    font-size: 0.8rem;
+    font-weight: 600;
+    text-transform: uppercase;
+}
+
+.high-confidence {
+    background: rgba(16, 185, 129, 0.2);
+    color: var(--success);
+    border: 1px solid rgba(16, 185, 129, 0.3);
+}
+
+.medium-confidence {
+    background: rgba(245, 158, 11, 0.2);
+    color: var(--warning);
+    border: 1px solid rgba(245, 158, 11, 0.3);
+}
+
+.low-confidence {
+    background: rgba(239, 68, 68, 0.2);
+    color: var(--danger);
+    border: 1px solid rgba(239, 68, 68, 0.3);
+}
+
+.verdict-summary {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 1.5rem;
+    padding: 1rem;
+    background: rgba(51, 65, 85, 0.3);
+    border-radius: 8px;
+}
+
+.verdict-text {
+    font-size: 1.3rem;
+    font-weight: 800;
+    color: var(--warning);
+}
+
+.probability {
+    color: var(--text-secondary);
+    font-size: 0.95rem;
+}
+
+.probability-value {
+    color: var(--text-primary);
+    font-weight: 700;
+}
+
+.metrics-breakdown {
+    margin-bottom: 1.5rem;
+}
+
+.breakdown-header {
+    font-size: 0.9rem;
+    font-weight: 600;
+    color: var(--text-secondary);
+    margin-bottom: 1rem;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+
+.metric-indicator {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 0.75rem;
+    margin-bottom: 0.5rem;
+    border-radius: 8px;
+    transition: all 0.2s ease;
+}
+
+.metric-indicator:hover {
+    background: rgba(51, 65, 85, 0.4);
+    transform: translateX(4px);
+}
+
+.metric-name {
+    font-weight: 600;
+    color: var(--text-primary);
+    min-width: 140px;
+}
+
+.metric-details {
+    display: flex;
+    gap: 1rem;
+    align-items: center;
+}
+
+.verdict-badge {
+    padding: 0.2rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.75rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    min-width: 60px;
+    text-align: center;
+}
+
+.ai-badge {
+    background: rgba(239, 68, 68, 0.2);
+    color: var(--danger);
+    border: 1px solid rgba(239, 68, 68, 0.3);
+}
+
+.human-badge {
+    background: rgba(16, 185, 129, 0.2);
+    color: var(--success);
+    border: 1px solid rgba(16, 185, 129, 0.3);
+}
+
+.confidence, .weight {
+    font-size: 0.8rem;
+    color: var(--text-muted);
+    min-width: 100px;
+}
+
+.agreement-indicator {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.75rem;
+    background: rgba(16, 185, 129, 0.1);
+    border: 1px solid rgba(16, 185, 129, 0.2);
+    border-radius: 8px;
+    color: var(--success);
+}
+
+.agreement-icon {
+    font-weight: 700;
+}
+
+.agreement-text {
+    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);
+}
+/* Download Actions */
+.download-actions {
+    display: flex;
+    gap: 1rem;
+    margin-top: 2rem;
+}
+.download-btn {
+    flex: 1;
+    padding: 0.75rem;
+    background: rgba(51, 65, 85, 0.6);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--text-primary);
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.3s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+}
+.download-btn:hover {
+    background: var(--primary);
+    border-color: var(--primary);
+    transform: translateY(-2px);
+}
+/* Action Buttons */
+.action-buttons {
+    display: flex;
+    gap: 1rem;
+    margin-top: 1.5rem;
+}
+.action-btn {
+    flex: 1;
+    padding: 0.75rem;
+    background: rgba(51, 65, 85, 0.6);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--text-primary);
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.3s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+}
+.action-btn:hover {
+    background: var(--primary);
+    border-color: var(--primary);
+    transform: translateY(-2px);
+}
+.action-btn.refresh {
+    background: rgba(245, 158, 11, 0.2);
+    border-color: var(--warning);
+    color: var(--warning);
+}
+.action-btn.refresh:hover {
+    background: var(--warning);
+    color: var(--bg-darker);
+}
+/* Metrics Grid */
+.metrics-grid {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 1rem;
+}
+.metric-result-card {
+    background: rgba(51, 65, 85, 0.4);
+    padding: 1.5rem;
+    border-radius: 10px;
+    border: 1px solid var(--border);
+}
+.metric-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 0.75rem;
+}
+.metric-name {
+    font-weight: 700;
+    color: #fff;
+    font-size: 1.1rem;
+}
+.metric-score {
+    font-size: 1.8rem;
+    font-weight: 800;
+}
+.metric-verdict {
+    display: inline-block;
+    padding: 0.25rem 0.75rem;
+    border-radius: 6px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    margin-top: 0.5rem;
+}
+.verdict-ai {
+    background: rgba(239, 68, 68, 0.2);
+    color: var(--danger);
+}
+.verdict-human {
+    background: rgba(16, 185, 129, 0.2);
+    color: var(--success);
+}
+.verdict-uncertain {
+    background: rgba(245, 158, 11, 0.2);
+    color: var(--warning);
+}
+.metric-description {
+    font-size: 0.85rem;
+    color: var(--text-secondary);
+    line-height: 1.5;
+    margin-top: 0.75rem;
+}
+/* Highlighted Text */
+.highlight-legend {
+    display: flex;
+    gap: 1.5rem;
+    margin-bottom: 1.5rem;
+    padding: 1rem;
+    background: rgba(51, 65, 85, 0.4);
+    border-radius: 8px;
+    flex-wrap: wrap;
+}
+.legend-item {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+.legend-color {
+    width: 20px;
+    height: 20px;
+    border-radius: 4px;
+}
+.legend-label {
+    font-size: 0.9rem;
+    color: var(--text-secondary);
+}
+.highlighted-text {
+    background: rgba(15, 23, 42, 0.8);
+    padding: 1.5rem;
+    border-radius: 10px;
+    border: 1px solid var(--border);
+    line-height: 1.9;
+    font-size: 0.95rem;
+}
+/* Footer */
+.footer {
+    max-width: 1200px;
+    margin: 6rem auto 0;
+    padding: 3rem 2rem;
+    border-top: 1px solid var(--border);
+    text-align: center;
+    color: var(--text-muted);
+}
+/* Responsive */
+@media (max-width: 1200px) {
+    .interface-grid {
+        grid-template-columns: 1fr;
+    }
+    .metrics-grid {
+        grid-template-columns: 1fr;
+    }
+}
+@media (max-width: 768px) {
+    .hero-title {
+        font-size: 2.5rem;
+    }
+    .features-grid {
+        grid-template-columns: 1fr;
+    }
+    .metric-card {
+        grid-template-columns: 1fr;
+        text-align: center;
+    }
+    .result-info-grid {
+        grid-template-columns: 1fr;
+    }
+    .nav-links {
+        display: none;
+    }
+    .download-actions,
+    .action-buttons {
+        flex-direction: column;
+    }
+    .highlight-legend {
+        flex-direction: column;
+        gap: 0.75rem;
+    }
+}
+/* Scroll Behavior */
+html {
+    scroll-behavior: smooth;
+}
+</style>
+</head>
+<body>
+<!-- Header -->
+<div class="header">
+<a href="#" class="logo" onclick="showLanding(); return false;">
+    <div class="logo-icon">🔍</div>
+    <span>AI Text Detector</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="#" class="nav-link" onclick="showAnalysis(); return false;">Try It Now</a>
+</div>
+</div>
+<!-- Landing Page -->
+<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>
+    <p class="hero-description">
+        Production-ready platform designed to identify AI-generated content across education, 
+        publishing, hiring, and research domains using sophisticated ensemble detection.
+    </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>
+    <div class="stat-card">
+        <div class="stat-value">6</div>
+        <div class="stat-label">Total Detection Metrics</div>
+    </div>
+    <div class="stat-card">
+        <div class="stat-value">5s</div>
+        <div class="stat-label">Average Processing Time</div>
+    </div>
+</div>
+<!-- Features Section -->
+<section class="features-section" id="features">
+    <h2 class="section-title">Why Choose Our Platform?</h2>
+    <p class="section-subtitle">
+        Advanced technology meets practical application
+    </p>
+    <div class="features-grid">
+        <div class="feature-card">
+            <div class="feature-icon">🎯</div>
+            <h3 class="feature-title">Domain-Aware Detection</h3>
+            <p class="feature-description">
+                Calibrated thresholds for Academic, Technical, Creative, and Casual content types with specialized detection algorithms for each domain.
+            </p>
+        </div>
+        <div class="feature-card">
+            <div class="feature-icon">🔬</div>
+            <h3 class="feature-title">6-Metric Ensemble</h3>
+            <p class="feature-description">
+                Combines Perplexity, Entropy, Statistical, Linguistic, Semantic Analysis, and DetectGPT for comprehensive detection with orthogonal signal capture.
+            </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.
+            </p>
+        </div>
+        <div class="feature-card">
+            <div class="feature-icon">🚀</div>
+            <h3 class="feature-title">Fast Processing</h3>
+            <p class="feature-description">
+                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>
+            <p class="feature-description">
+                Upload and analyze TXT, PDF, DOCX, DOC, and Markdown files with automatic text extraction.
+            </p>
+        </div>
+    </div>
+</section>
+<!-- Metrics Section -->
+<section class="metrics-info" id="metrics">
+    <h2 class="section-title">Detection Metrics Explained</h2>
+    <p class="section-subtitle">
+        Understanding the science behind the detection
+    </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 XL language model. AI-generated text typically has 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>
+        </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>
+        </div>
+    </div>
+    <div class="metric-card">
+        <div class="metric-icon-box">📝</div>
+        <div class="metric-content">
+            <h3>Linguistic Analysis <span class="metric-weight">Weight: 15%</span></h3>
+            <p>Evaluates POS tag diversity, syntactic complexity, and grammatical patterns. Examines the richness of language structures and whether they match natural human linguistic variation.</p>
+        </div>
+    </div>
+    <div class="metric-card">
+        <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>
+        </div>
+    </div>
+    <div class="metric-card">
+        <div class="metric-icon-box">🔍</div>
+        <div class="metric-content">
+            <h3>DetectGPT <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>
+        </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>
+</footer>
+</div>
+<!-- Analysis Interface -->
+<div class="analysis-interface" id="analysis-interface">
+<div class="interface-grid">
+    <!-- Left Panel: Input -->
+    <div class="panel">
+        <h2 class="panel-title">Submit Content for Analysis</h2>
+        <div class="input-tabs">
+            <button class="input-tab active" data-tab="paste">
+                📋 Paste Text
+            </button>
+            <button class="input-tab" data-tab="upload">
+                📁 Upload File
+            </button>
+        </div>
+        <div id="paste-tab" class="tab-content active">
+            <textarea 
+                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. Our system analyzes linguistic patterns, statistical features, and semantic structures to determine authenticity."
+            ></textarea>
+        </div>
+        <div id="upload-tab" class="tab-content">
+            <div class="file-upload-area" id="file-upload-area">
+                <input type="file" id="file-input" class="file-input" accept=".txt,.pdf,.docx,.doc,.md">
+                <div class="file-upload-icon">📄</div>
+                <div style="font-size: 1.1rem; font-weight: 600; margin-bottom: 0.5rem;">
+                    Click to upload or drag and drop
+                </div>
+                <div style="color: var(--text-muted); font-size: 0.9rem;">
+                    Supported formats: TXT, PDF, DOCX, DOC, MD
+                </div>
+                <div style="color: var(--text-muted); font-size: 0.85rem; margin-top: 0.5rem;">
+                    Maximum file size: 10MB
+                </div>
+            </div>
+            <div id="file-name-display" class="file-name-display"></div>
+        </div>
+        <div class="options-section">
+            <div class="option-row">
+                <label class="option-label">Content Domain:</label>
+                <select id="domain-select">
+                    <option value="">Auto-detect</option>
+                    <option value="general">General</option>
+                    <option value="academic">Academic</option>
+                    <option value="creative">Creative Writing</option>
+                    <option value="ai_ml">AI/ML Technical</option>
+                    <option value="software_dev">Software Development</option>
+                    <option value="technical_doc">Technical Documentation</option>
+                    <option value="engineering">Engineering</option>
+                    <option value="science">Science</option>
+                    <option value="business">Business</option>
+                    <option value="legal">Legal</option>
+                    <option value="medical">Medical</option>
+                    <option value="journalism">Journalism</option>
+                    <option value="marketing">Marketing</option>
+                    <option value="social_media">Social Media</option>
+                    <option value="blog_personal">Personal Blog</option>
+                    <option value="tutorial">Tutorial</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">
+                    <input type="checkbox" id="enable-highlighting" checked>
+                    <span style="font-size: 0.85rem; color: var(--text-muted);">Show suspicious sentences</span>
+                </div>
+            </div>
+            <!-- NEW OPTIONS -->
+            <div class="option-row">
+                <label class="option-label">Sentence-Level Analysis:</label>
+                <div class="checkbox-wrapper">
+                    <input type="checkbox" id="use-sentence-level" checked>
+                    <span style="font-size: 0.85rem; color: var(--text-muted);">More accurate but slower analysis</span>
+                </div>
+            </div>
+            <div class="option-row">
+                <label class="option-label">Include Metrics Summary:</label>
+                <div class="checkbox-wrapper">
+                    <input type="checkbox" id="include-metrics-summary" checked>
+                    <span style="font-size: 0.85rem; color: var(--text-muted);">Show text analysis statistics</span>
+                </div>
+            </div>
+        </div>
+        <button id="analyze-btn" class="analyze-btn">
+            🔍 Analyze Text
+        </button>
+        <div class="action-buttons">
+            <button id="refresh-btn" class="action-btn refresh">
+                🔄 Refresh
+            </button>
+            <button id="try-next-btn" class="action-btn">
+                ➕ Try Next
+            </button>
+        </div>
+    </div>
+    <!-- Right Panel: Results -->
+    <div class="panel">
+        <h2 class="panel-title">Analysis Report</h2>
+        <div class="report-tabs">
+            <button class="report-tab active" data-report="summary">
+                📊 Summary
+            </button>
+            <button class="report-tab" data-report="highlighted">
+                📝 Highlighted Text
+            </button>
+            <button class="report-tab" data-report="metrics">
+                ℹ️ Detailed Metrics
+            </button>
+        </div>
+        <!-- Summary Report -->
+        <div id="summary-report" class="report-content active">
+            <div class="empty-state">
+                <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.
+                </p>
+            </div>
+        </div>
+        <!-- Highlighted Text Report -->
+        <div id="highlighted-report" class="report-content">
+            <div class="empty-state">
+                <div class="empty-icon">📝</div>
+                <p class="empty-description">
+                    Run an analysis to see sentence-level highlighting
+                </p>
+            </div>
+        </div>
+        <!-- Metrics Report -->
+        <div id="metrics-report" class="report-content">
+            <div class="empty-state">
+                <div class="empty-icon">📊</div>
+                <p class="empty-description">
+                    Run an analysis to see detailed metric breakdowns
+                </p>
+            </div>
+        </div>
+    </div>
+</div>
+</div>
+<script>
+// Configuration
+const API_BASE = '';
+let currentAnalysisData = null;
+
+// Navigation
+function showLanding() {
+    document.getElementById('landing-page').style.display = 'block';
+    document.getElementById('analysis-interface').style.display = 'none';
+    window.scrollTo(0, 0);
+}
+
+function showAnalysis() {
+    document.getElementById('landing-page').style.display = 'none';
+    document.getElementById('analysis-interface').style.display = 'block';
+    window.scrollTo(0, 0);
+    resetAnalysisInterface();
+}
+
+// Reset analysis interface
+function resetAnalysisInterface() {
+    // Clear text input
+    document.getElementById('text-input').value = '';
+    
+    // Clear file input and display
+    document.getElementById('file-input').value = '';
+    document.getElementById('file-name-display').style.display = 'none';
+    document.getElementById('file-name-display').innerHTML = '';
+    
+    // Reset tabs to paste
+    document.querySelectorAll('.input-tab').forEach(t => t.classList.remove('active'));
+    document.querySelector('.input-tab[data-tab="paste"]').classList.add('active');
+    document.querySelectorAll('.tab-content').forEach(content => content.classList.remove('active'));
+    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;
+    
+    // Reset report tabs to summary
+    document.querySelectorAll('.report-tab').forEach(t => t.classList.remove('active'));
+    document.querySelector('.report-tab[data-report="summary"]').classList.add('active');
+    document.querySelectorAll('.report-content').forEach(content => content.classList.remove('active'));
+    document.getElementById('summary-report').classList.add('active');
+    
+    // Show empty state
+    document.getElementById('summary-report').innerHTML = `
+        <div class="empty-state">
+            <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.
+            </p>
+        </div>
+    `;
+    document.getElementById('highlighted-report').innerHTML = `
+        <div class="empty-state">
+            <div class="empty-icon">📝</div>
+            <p class="empty-description">
+                Run an analysis to see sentence-level highlighting
+            </p>
+        </div>
+    `;
+    document.getElementById('metrics-report').innerHTML = `
+        <div class="empty-state">
+            <div class="empty-icon">📊</div>
+            <p class="empty-description">
+                Run an analysis to see detailed metric breakdowns
+            </p>
+        </div>
+    `;
+    
+    // Clear current analysis data
+    currentAnalysisData = null;
+}
+
+// Input Tab Switching
+document.querySelectorAll('.input-tab').forEach(tab => {
+    tab.addEventListener('click', () => {
+        const tabName = tab.dataset.tab;
+        document.querySelectorAll('.input-tab').forEach(t => t.classList.remove('active'));
+        tab.classList.add('active');
+        document.querySelectorAll('#paste-tab, #upload-tab').forEach(content => {
+            content.classList.remove('active');
+        });
+        document.getElementById(`${tabName}-tab`).classList.add('active');
+    });
+});
+
+// Report Tab Switching
+document.querySelectorAll('.report-tab').forEach(tab => {
+    tab.addEventListener('click', () => {
+        const reportName = tab.dataset.report;
+        document.querySelectorAll('.report-tab').forEach(t => t.classList.remove('active'));
+        tab.classList.add('active');
+        document.querySelectorAll('.report-content').forEach(content => {
+            content.classList.remove('active');
+        });
+        document.getElementById(`${reportName}-report`).classList.add('active');
+    });
+});
+
+// File Upload Handling
+const fileInput = document.getElementById('file-input');
+const fileUploadArea = document.getElementById('file-upload-area');
+const fileNameDisplay = document.getElementById('file-name-display');
+
+fileUploadArea.addEventListener('click', () => {
+    fileInput.click();
+});
+
+fileInput.addEventListener('change', (e) => {
+    handleFileSelect(e.target.files[0]);
+});
+
+// Drag and Drop
+fileUploadArea.addEventListener('dragover', (e) => {
+    e.preventDefault();
+    fileUploadArea.classList.add('drag-over');
+});
+
+fileUploadArea.addEventListener('dragleave', () => {
+    fileUploadArea.classList.remove('drag-over');
+});
+
+fileUploadArea.addEventListener('drop', (e) => {
+    e.preventDefault();
+    fileUploadArea.classList.remove('drag-over');
+    const file = e.dataTransfer.files[0];
+    if (file) {
+        fileInput.files = e.dataTransfer.files;
+        handleFileSelect(file);
+    }
+});
+
+function handleFileSelect(file) {
+    if (!file) return;
+    
+    const allowedTypes = ['.txt', '.pdf', '.docx', '.doc', '.md'];
+    const fileExt = '.' + file.name.split('.').pop().toLowerCase();
+    
+    if (!allowedTypes.includes(fileExt)) {
+        alert('Unsupported file type. Please upload: TXT, PDF, DOCX, DOC, or MD files.');
+        return;
+    }
+    
+    if (file.size > 10 * 1024 * 1024) {
+        alert('File size exceeds 10MB limit.');
+        return;
+    }
+    
+    fileNameDisplay.style.display = 'block';
+    fileNameDisplay.innerHTML = `
+        <strong>Selected file:</strong> ${file.name} 
+        <span style="color: var(--text-muted);">(${formatFileSize(file.size)})</span>
+    `;
+}
+
+function formatFileSize(bytes) {
+    if (bytes < 1024) return bytes + ' B';
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+// Analyze Button
+document.getElementById('analyze-btn').addEventListener('click', async () => {
+    const activeTab = document.querySelector('.input-tab.active').dataset.tab;
+    const textInput = document.getElementById('text-input').value.trim();
+    const fileInput = document.getElementById('file-input').files[0];
+    
+    if (activeTab === 'paste' && !textInput) {
+        alert('Please paste some text to analyze (minimum 50 characters).');
+        return;
+    }
+    
+    if (activeTab === 'paste' && textInput.length < 50) {
+        alert('Text must be at least 50 characters long for accurate analysis.');
+        return;
+    }
+    
+    if (activeTab === 'upload' && !fileInput) {
+        alert('Please select a file to upload.');
+        return;
+    }
+    
+    await performAnalysis(activeTab, textInput, fileInput);
+});
+
+// Refresh Button - clears everything and shows empty state
+document.getElementById('refresh-btn').addEventListener('click', () => {
+    resetAnalysisInterface();
+});
+
+// Try Next Button - same as refresh but keeps the interface ready
+document.getElementById('try-next-btn').addEventListener('click', () => {
+    resetAnalysisInterface();
+});
+
+async function performAnalysis(mode, text, file) {
+    const analyzeBtn = document.getElementById('analyze-btn');
+    analyzeBtn.disabled = true;
+    analyzeBtn.innerHTML = '⏳ Analyzing...';
+    
+    showLoading();
+    
+    try {
+        let response;
+        if (mode === 'paste') {
+            response = await analyzeText(text);
+        } else {
+            response = await analyzeFile(file);
+        }
+        
+        currentAnalysisData = response;
+        displayResults(response);
+    } catch (error) {
+        console.error('Analysis error:', error);
+        showError(error.message || 'Analysis failed. Please try again.');
+    } finally {
+        analyzeBtn.disabled = false;
+        analyzeBtn.innerHTML = '🔍 Analyze Text';
+    }
+}
+
+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;
+    
+    const response = await fetch(`${API_BASE}/api/analyze`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            text: text,
+            domain: domain,
+            enable_attribution: enableAttribution,
+            enable_highlighting: enableHighlighting,
+            use_sentence_level: useSentenceLevel,
+            include_metrics_summary: includeMetricsSummary,
+            skip_expensive_metrics: false
+        })
+    });
+    
+    if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Analysis failed');
+    }
+    
+    return await response.json();
+}
+
+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');
+    
+    const response = await fetch(`${API_BASE}/api/analyze/file`, {
+        method: 'POST',
+        body: formData
+    });
+    
+    if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'File analysis failed');
+    }
+    
+    return await response.json();
+}
+
+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-muted); font-size: 0.9rem; margin-top: 0.5rem;">
+                This may take a few seconds
+            </p>
+        </div>
+    `;
+}
+
+function showError(message) {
+    document.getElementById('summary-report').innerHTML = `
+        <div class="empty-state">
+            <div class="empty-icon" style="background: linear-gradient(135deg, var(--danger) 0%, #dc2626 100%);">⚠️</div>
+            <h3 class="empty-title">Analysis Failed</h3>
+            <p class="empty-description">${message}</p>
+        </div>
+    `;
+}
+
+function displayResults(data) {
+    console.log('Response data:', data);
+    
+    // Handle different response structures
+    const detection = data.detection_result;
+    if (!detection) {
+        showError('Invalid response structure. Please check the API response format.');
+        console.error('Full response:', data);
+        return;
+    }
+    
+    // Extract data based on your actual API structure
+    const ensemble = detection.ensemble_result || detection.ensemble;
+    const prediction = detection.prediction || {};
+    const metrics = detection.metric_results || detection.metrics;
+    const analysis = detection.analysis || {};
+    
+    // Display Summary with enhanced reasoning
+    displaySummary(ensemble, prediction, analysis, data.attribution, data.reasoning);
+    
+    // Display Highlighted Text with enhanced features
+    if (data.highlighted_html) {
+        displayHighlightedText(data.highlighted_html);
+    } else {
+        document.getElementById('highlighted-report').innerHTML = `
+            <div class="empty-state">
+                <p class="empty-description">Highlighting not available for this analysis</p>
+            </div>
+        `;
+    }
+    
+    // Display Metrics with full details
+    if (metrics && Object.keys(metrics).length > 0) {
+        displayMetrics(metrics, analysis, ensemble);
+    } else {
+        document.getElementById('metrics-report').innerHTML = `
+            <div class="empty-state">
+                <p class="empty-description">Metric details not available</p>
+            </div>
+        `;
+    }
+}
+
+function displaySummary(ensemble, prediction, analysis, attribution, reasoning) {
+    // Use ensemble values from your actual API response
+    const aiProbability = ensemble.ai_probability !== undefined ? 
+        (ensemble.ai_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 domain = analysis.domain || 'general';
+    const isAI = verdict.toLowerCase().includes('ai');
+    const gaugeColor = isAI ? 'var(--danger)' : 'var(--success)';
+    const gaugeDegree = aiProbability * 3.6;
+    
+    const confidenceLevel = parseFloat(confidence) >= 70 ? 'HIGH' :
+                           parseFloat(confidence) >= 40 ? 'MEDIUM' : 'LOW';
+    const confidenceClass = confidenceLevel === 'HIGH' ? 'confidence-high' : 
+                           confidenceLevel === 'MEDIUM' ? 'confidence-medium' : 'confidence-low';
+
+    let attributionHTML = '';
+    if (attribution && attribution.predicted_model) {
+        const modelName = attribution.predicted_model.replace(/_/g, ' ').replace(/-/g, ' ').toUpperCase();
+        const modelConf = attribution.confidence ? 
+            (attribution.confidence * 100).toFixed(1) : 'N/A';
+        let topModels = '';
+        if (attribution.model_probabilities) {
+            const sorted = Object.entries(attribution.model_probabilities)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 3);
+            topModels = sorted.map(([model, prob]) => 
+                `<div class="model-match" style="margin-top: 0.5rem;">
+                    <span class="model-name">${model.replace(/_/g, ' ').replace(/-/g, ' ').toUpperCase()}</span>
+                    <span class="model-confidence">${(prob * 100).toFixed(1)}%</span>
+                </div>`
+            ).join('');
+        }
+        attributionHTML = `
+            <div class="attribution-section">
+                <div class="attribution-title">🤖 AI Model Attribution</div>
+                <div class="model-match">
+                    <span class="model-name">Most Likely: ${modelName}</span>
+                    <span class="model-confidence">${modelConf}%</span>
+                </div>
+                ${topModels}
+                ${attribution.reasoning && attribution.reasoning.length > 0 ? 
+                    `<p style="color: var(--text-secondary); margin-top: 1rem; font-size: 0.9rem;">${attribution.reasoning[0]}</p>` : ''}
+            </div>
+        `;
+    }
+
+    document.getElementById('summary-report').innerHTML = `
+        <div class="result-summary">
+            <div class="gauge-container">
+                <div class="gauge-circle" style="--gauge-color: ${gaugeColor}; --gauge-degree: ${gaugeDegree}deg;">
+                    <div class="gauge-inner">
+                        <div class="gauge-value">${aiProbability}%</div>
+                        <div class="gauge-label">AI Probability</div>
+                    </div>
+                </div>
+            </div>
+            <div class="result-info-grid">
+                <div class="info-card">
+                    <div class="info-label">Verdict</div>
+                    <div class="info-value" style="font-size: 1.2rem;">${verdict}</div>
+                </div>
+                <div class="info-card">
+                    <div class="info-label">Confidence Level</div>
+                    <div class="info-value">
+                        <span class="confidence-badge ${confidenceClass}">${confidence}%</span>
+                    </div>
+                </div>
+                <div class="info-card">
+                    <div class="info-label">Content Domain</div>
+                    <div class="info-value" style="font-size: 1.1rem;">${formatDomainName(domain)}</div>
+                </div>
+            </div>
+            ${createEnhancedReasoningHTML(ensemble, analysis, reasoning)}
+            ${attributionHTML}
+            <div class="download-actions">
+                <button class="download-btn" onclick="downloadReport('json')">
+                    📄 Download JSON
+                </button>
+                <button class="download-btn" onclick="downloadReport('pdf')">
+                    📑 Download PDF Report
+                </button>
+            </div>
+        </div>
+    `;
+}
+
+function createEnhancedReasoningHTML(ensemble, analysis, reasoning) {
+    // Use actual reasoning data if available
+    if (reasoning && reasoning.summary) {
+        return `
+            <div class="reasoning-box enhanced">
+                <div class="reasoning-header">
+                    <div class="reasoning-icon">💡</div>
+                    <div class="reasoning-title">Detection 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>
+                </div>
+
+                <div style="color: var(--text-secondary); line-height: 1.6; margin-bottom: 1.5rem;">
+                    ${reasoning.summary}
+                </div>
+
+                ${reasoning.key_indicators && reasoning.key_indicators.length > 0 ? `
+                    <div class="metrics-breakdown">
+                        <div class="breakdown-header">Key Indicators</div>
+                        ${reasoning.key_indicators.map(indicator => `
+                            <div class="metric-indicator">
+                                <div class="metric-name">${indicator.split(':')[0]}</div>
+                                <div class="metric-details">
+                                    <span style="color: var(--text-secondary); font-size: 0.9rem;">${indicator.split(':')[1]}</span>
+                                </div>
+                            </div>
+                        `).join('')}
+                    </div>
+                ` : ''}
+
+                ${ensemble.consensus_level > 0.7 ? `
+                    <div class="agreement-indicator">
+                        <div class="agreement-icon">✓</div>
+                        <div class="agreement-text">Strong metric consensus (${(ensemble.consensus_level * 100).toFixed(1)}%)</div>
+                    </div>
+                ` : ''}
+            </div>
+        `;
+    }
+
+    // Fallback to basic reasoning if no reasoning data
+    return `
+        <div class="reasoning-box">
+            <div class="reasoning-title">💡 Detection Reasoning</div>
+            <p class="reasoning-text">
+                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.
+            </p>
+        </div>
+    `;
+}
+
+function displayHighlightedText(html) {
+    document.getElementById('highlighted-report').innerHTML = `
+        ${createDefaultLegend()}
+        <div class="highlighted-text">
+            ${html}
+        </div>
+        ${getHighlightStyles()}
+    `;
+}
+
+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>
+            <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>
+            <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>
+            <div class="legend-item">
+                <div class="legend-color" style="background: #e9d5ff;"></div>
+                <div class="legend-label">Mixed Content</div>
+            </div>
+        </div>
+    `;
+}
+
+function getHighlightStyles() {
+    return `
+        <style>
+            #highlighted-report .highlight {
+                padding: 2px 4px;
+                margin: 0 1px;
+                border-radius: 3px;
+                cursor: help;
+                transition: all 0.2s;
+                border-bottom: 2px solid transparent;
+                color: #000000 !important;
+                font-weight: 500;
+            }
+            #highlighted-report .highlight:hover {
+                transform: translateY(-1px);
+                box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+                z-index: 10;
+                text-shadow: 0 1px 1px rgba(255,255,255,0.8);
+            }
+            #highlighted-report .very-high-ai {
+                background-color: #fee2e2 !important;
+                border-bottom-color: #ef4444 !important;
+            }
+            #highlighted-report .high-ai {
+                background-color: #fed7aa !important;
+                border-bottom-color: #f97316 !important;
+            }
+            #highlighted-report .medium-ai {
+                background-color: #fef3c7 !important;
+                border-bottom-color: #f59e0b !important;
+            }
+            #highlighted-report .uncertain {
+                background-color: #fef9c3 !important;
+                border-bottom-color: #fbbf24 !important;
+            }
+            #highlighted-report .medium-human {
+                background-color: #ecfccb !important;
+                border-bottom-color: #a3e635 !important;
+            }
+            #highlighted-report .high-human {
+                background-color: #bbf7d0 !important;
+                border-bottom-color: #4ade80 !important;
+            }
+            #highlighted-report .very-high-human {
+                background-color: #dcfce7 !important;
+                border-bottom-color: #22c55e !important;
+            }
+            #highlighted-report .mixed-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;
+            }
+        </style>
+    `;
+}
+
+function displayMetrics(metrics, analysis, ensemble) {
+    const metricOrder = ['structural', 'perplexity', 'entropy', 'semantic_analysis', 'linguistic', 'detect_gpt'];
+    
+    let metricsHTML = `
+        <div style="margin-bottom: 2rem; padding: 1.5rem; background: rgba(51, 65, 85, 0.3); border-radius: 10px;">
+            <h3 style="color: var(--primary); margin-bottom: 1rem;">📊 Ensemble Analysis</h3>
+            <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem;">
+                <div>
+                    <div style="font-size: 0.85rem; color: var(--text-secondary);">Method</div>
+                    <div style="font-size: 1.1rem; font-weight: 700; color: #fff;">Confidence Calibrated</div>
+                </div>
+                <div>
+                    <div style="font-size: 0.85rem; color: var(--text-secondary);">Consensus</div>
+                    <div style="font-size: 1.1rem; font-weight: 700; color: #fff;">${(ensemble.consensus_level * 100).toFixed(1)}%</div>
+                </div>
+                <div>
+                    <div style="font-size: 0.85rem; color: var(--text-secondary);">Uncertainty</div>
+                    <div style="font-size: 1.1rem; font-weight: 700; color: #fff;">${(ensemble.uncertainty_score * 100).toFixed(1)}%</div>
+                </div>
+            </div>
+        </div>
+    `;
+
+    metricOrder.forEach(metricKey => {
+        const metric = metrics[metricKey];
+        if (!metric) return;
+        
+        const aiProb = (metric.ai_probability * 100).toFixed(1);
+        const humanProb = (metric.human_probability * 100).toFixed(1);
+        const confidence = (metric.confidence * 100).toFixed(1);
+        const weight = ensemble.metric_weights && ensemble.metric_weights[metricKey] ? 
+            (ensemble.metric_weights[metricKey] * 100).toFixed(1) : '0.0';
+        
+        const color = metric.ai_probability >= 0.6 ? 'var(--danger)' : 
+                     metric.ai_probability >= 0.4 ? 'var(--warning)' : 'var(--success)';
+        const verdictText = metric.ai_probability >= 0.6 ? 'AI' :
+                           metric.ai_probability >= 0.4 ? 'UNCERTAIN' : 'HUMAN';
+        const verdictClass = verdictText === 'AI' ? 'verdict-ai' :
+                            verdictText === 'UNCERTAIN' ? 'verdict-uncertain' : 'verdict-human';
+        
+        metricsHTML += `
+            <div class="metric-result-card" style="margin-bottom: 1.5rem;">
+                <div class="metric-header">
+                    <div class="metric-name">${formatMetricName(metricKey)}</div>
+                    <div class="metric-score" style="color: ${color};">${aiProb}%</div>
+                </div>
+                <div style="display: flex; gap: 1rem; margin: 1rem 0;">
+                    <div style="flex: 1;">
+                        <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">AI</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>
+                        <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${aiProb}%</div>
+                    </div>
+                    <div style="flex: 1;">
+                        <div style="font-size: 0.75rem; color: var(--text-muted); margin-bottom: 0.25rem;">Human</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>
+                        <div style="font-size: 0.85rem; font-weight: 600; margin-top: 0.25rem;">${humanProb}%</div>
+                    </div>
+                </div>
+                <div style="display: flex; justify-content: space-between; align-items: center; margin: 0.75rem 0;">
+                    <span class="metric-verdict ${verdictClass}">${verdictText}</span>
+                    <span style="font-size: 0.85rem; color: var(--text-secondary);">Confidence: ${confidence}% | Weight: ${weight}%</span>
+                </div>
+                <div class="metric-description">
+                    ${getMetricDescription(metricKey)}
+                </div>
+                ${metric.details ? renderMetricDetails(metricKey, metric.details) : ''}
+            </div>
+        `;
+    });
+    
+    document.getElementById('metrics-report').innerHTML = metricsHTML;
+}
+
+function renderMetricDetails(metricName, details) {
+    if (!details || Object.keys(details).length === 0) return '';
+    
+    // Key metrics to show for each type
+    const importantKeys = {
+        'structural': ['burstiness_score', 'length_uniformity', 'avg_sentence_length', 'std_sentence_length'],
+        'perplexity': ['overall_perplexity', 'avg_sentence_perplexity', 'normalized_perplexity'],
+        'entropy': ['token_diversity', 'sequence_unpredictability', 'char_entropy'],
+        'semantic_analysis': ['coherence_score', 'consistency_score', 'repetition_score'],
+        'linguistic': ['pos_diversity', 'syntactic_complexity', 'grammatical_consistency'],
+        'detect_gpt': ['stability_score', 'curvature_score', 'likelihood_ratio']
+    };
+    
+    const keysToShow = importantKeys[metricName] || Object.keys(details).slice(0, 6);
+    let detailsHTML = '<div style="margin-top: 1rem; padding-top: 1rem; border-top: 1px solid var(--border);">';
+    detailsHTML += '<div style="font-size: 0.9rem; font-weight: 600; color: var(--text-secondary); margin-bottom: 0.75rem;">📈 Detailed Metrics:</div>';
+    detailsHTML += '<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 0.75rem; font-size: 0.85rem;">';
+    
+    keysToShow.forEach(key => {
+        if (details[key] !== undefined && details[key] !== null) {
+            const value = typeof details[key] === 'number' ? 
+                (details[key] < 1 && details[key] > 0 ? (details[key] * 100).toFixed(2) + '%' : details[key].toFixed(2)) :
+                details[key];
+            const label = key.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+            detailsHTML += `
+                <div style="background: rgba(15, 23, 42, 0.6); padding: 0.5rem; border-radius: 6px;">
+                    <div style="color: var(--text-muted); font-size: 0.75rem; margin-bottom: 0.25rem;">${label}</div>
+                    <div style="color: var(--primary); font-weight: 700;">${value}</div>
+                </div>
+            `;
+        }
+    });
+    
+    detailsHTML += '</div></div>';
+    return detailsHTML;
+}
+
+function getMetricDescription(metricName) {
+    const 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.',
+        detect_gpt: 'Tests text stability under perturbation using curvature analysis.'
+    };
+    return descriptions[metricName] || 'Metric analysis complete.';
+}
+
+function formatMetricName(name) {
+    const names = {
+        structural: 'Structural Analysis',
+        perplexity: 'Perplexity',
+        entropy: 'Entropy',
+        semantic_analysis: 'Semantic Analysis',
+        linguistic: 'Linguistic Analysis',
+        detect_gpt: 'DetectGPT'
+    };
+    return names[name] || name.split('_').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+function formatDomainName(domain) {
+    return domain.split('_').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+async function downloadReport(format) {
+    if (!currentAnalysisData) {
+        alert('No analysis data available');
+        return;
+    }
+    
+    try {
+        const analysisId = currentAnalysisData.analysis_id;
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        
+        // For JSON, download directly from current data
+        if (format === 'json') {
+            const data = {
+                ...currentAnalysisData,
+                download_timestamp: new Date().toISOString(),
+                report_version: '2.0.0'
+            };
+            const blob = new Blob([JSON.stringify(data, null, 2)], { 
+                type: 'application/json' 
+            });
+            const filename = `ai-detection-report-${analysisId}-${timestamp}.json`;
+            await downloadBlob(blob, filename);
+            return;
+        }
+        
+        // Get the original text for report generation
+        const activeTab = document.querySelector('.input-tab.active').dataset.tab;
+        let textToSend = '';
+        if (activeTab === 'paste') {
+            textToSend = document.getElementById('text-input').value;
+        } else {
+            textToSend = currentAnalysisData.detection_result?.processed_text?.text || 
+                        'Uploaded file content - see analysis for details';
+        }
+        
+        // For PDF, request from server
+        const formData = new FormData();
+        formData.append('analysis_id', analysisId);
+        formData.append('text', textToSend);
+        formData.append('formats', format);
+        formData.append('include_highlights', document.getElementById('enable-highlighting').checked.toString());
+        
+        const response = await fetch(`${API_BASE}/api/report/generate`, {
+            method: 'POST',
+            body: formData
+        });
+        
+        if (!response.ok) {
+            throw new Error('Report generation failed');
+        }
+        
+        const result = await response.json();
+        if (result.reports && result.reports[format]) {
+            const filename = result.reports[format];
+            const downloadResponse = await fetch(`${API_BASE}/api/report/download/${filename}`);
+            if (!downloadResponse.ok) {
+                throw new Error('Failed to download file');
+            }
+            const blob = await downloadResponse.blob();
+            const downloadFilename = `ai-detection-${format}-report-${analysisId}-${timestamp}.${format}`;
+            await downloadBlob(blob, downloadFilename);
+        } else {
+            alert('Report file not available');
+        }
+    } catch (error) {
+        console.error('Download error:', error);
+        alert('Failed to download report. Please try again.');
+    }
+}
+
+async function downloadBlob(blob, filename) {
+    try {
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        a.style.display = 'none';
+        document.body.appendChild(a);
+        a.click();
+        
+        setTimeout(() => {
+            document.body.removeChild(a);
+            URL.revokeObjectURL(url);
+            showDownloadSuccess(filename);
+        }, 100);
+    } catch (error) {
+        console.error('Download failed:', error);
+        alert('Download failed. Please try again.');
+    }
+}
+
+function showDownloadSuccess(filename) {
+    const notification = document.createElement('div');
+    notification.style.cssText = `
+        position: fixed;
+        top: 20px;
+        right: 20px;
+        background: var(--success);
+        color: white;
+        padding: 1rem 1.5rem;
+        border-radius: 8px;
+        font-weight: 600;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+        z-index: 10000;
+        animation: slideIn 0.3s ease;
+    `;
+    notification.innerHTML = `
+        <div style="display: flex; align-items: center; gap: 0.5rem;">
+            <span>✓</span>
+            <span>Downloaded: ${filename}</span>
+        </div>
+    `;
+    document.body.appendChild(notification);
+    
+    if (!document.querySelector('#download-animation')) {
+        const style = document.createElement('style');
+        style.id = 'download-animation';
+        style.textContent = `
+            @keyframes slideIn {
+                from { transform: translateX(100%); opacity: 0; }
+                to { transform: translateX(0); opacity: 1; }
+            }
+        `;
+        document.head.appendChild(style);
+    }
+    
+    setTimeout(() => {
+        if (notification.parentNode) {
+            notification.parentNode.removeChild(notification);
+        }
+    }, 3000);
+}
+
+// Smooth scrolling for anchor links
+document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+    anchor.addEventListener('click', function (e) {
+        const href = this.getAttribute('href');
+        if (href !== '#') {
+            e.preventDefault();
+            const target = document.querySelector(href);
+            if (target) {
+                target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            }
+        }
+    });
+});
+
+// Initialize - show landing page by default
+showLanding();
+</script>
+</body>
+</html>

utils/logger.py

@@ -0,0 +1,610 @@
+# DEPENDENCIES
+import os
+import sys
+import json
+import time
+import logging
+from typing import Any
+from typing import Dict
+from pathlib import Path
+from loguru import logger
+from typing import Optional
+from datetime import datetime
+from config.settings import settings
+
+
+class InterceptHandler(logging.Handler):
+    """
+    Intercept standard logging messages toward Loguru
+    """
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Emit a log record to Loguru
+        """
+        # Get corresponding Loguru level if it exists
+        try:
+            level = logger.level(record.levelname).name
+        
+        except ValueError:
+            level = record.levelno
+        
+        # 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
+        
+        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()
+    
+
+    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
+    
+    Features:
+    - Structured JSON logging for production
+    - Human-readable console logging for development
+    - Automatic log rotation and retention
+    - Integration with standard logging and Loguru
+    - Performance monitoring
+    - Security event logging
+    """
+    
+    def __init__(self):
+        self.initialized = False
+        self.log_dir     = Path(__file__).parent.parent / "logs"
+
+        self.setup_log_dir()
+
+    
+    def setup_log_dir(self) -> None:
+        """
+        Create log directory structure
+        """
+        try:
+            self.log_dir.mkdir(exist_ok=True)
+            
+            # Create subdirectories
+            (self.log_dir / "application").mkdir(exist_ok = True)
+            (self.log_dir / "performance").mkdir(exist_ok = True)
+            (self.log_dir / "security").mkdir(exist_ok = True)
+            (self.log_dir / "errors").mkdir(exist_ok = True)
+            
+            logger.info(f"Log directory structure created at: {self.log_dir}")
+        
+        except Exception as e:
+            print(f"CRITICAL: Failed to create log directory: {e}")
+            sys.exit(1)
+    
+
+    def initialize(self) -> bool:
+        """
+        Initialize centralized logging system
+        
+        Returns:
+        --------
+            { bool } : True if successful, False otherwise
+        """
+        try:
+            # Remove default logger
+            logger.remove()
+            
+            # Configure based on environment
+            if (settings.ENVIRONMENT == "production"):
+                self._setup_production_logging()
+            
+            else:
+                self._setup_development_logging()
+            
+            # Intercept standard logging
+            self._intercept_standard_logging()
+            
+            # Log initialization
+            logger.success("Centralized logging system initialized")
+            logger.info(f"Environment: {settings.ENVIRONMENT}")
+            logger.info(f"Log Level: {settings.LOG_LEVEL}")
+            logger.info(f"Log Directory: {self.log_dir}")
+            
+            self.initialized = True
+            return True
+        
+        except Exception as e:
+            print(f"CRITICAL: Failed to initialize logging: {e}")
+            return False
+    
+
+    def _setup_production_logging(self) -> None:
+        """
+        Setup production logging with JSON format and rotation
+        """
+        # Application logs (all events)
+        logger.add(self.log_dir / "application" / "app_{time:YYYY-MM-DD}.log",
+                   format      = "{message}",
+                   filter      = lambda record: record["extra"].get("log_type", "application") == "application",
+                   level       = settings.LOG_LEVEL,
+                   rotation    = "00:00",    # Rotate daily at midnight
+                   retention   = "30 days",  # Keep logs for 30 days
+                   compression = "gz",       # Compress old logs
+                   serialize   = True,       # Output as JSON
+                   backtrace   = True,
+                   diagnose    = True,
+                   enqueue     = True,       # Thread-safe
+                  )
+        
+        # Performance logs
+        logger.add(self.log_dir / "performance" / "performance_{time:YYYY-MM-DD}.log",
+                   format      = "{message}",
+                   filter      = lambda record: record["extra"].get("log_type") == "performance",
+                   level       = "INFO",
+                   rotation    = "00:00",
+                   retention   = "7 days",
+                   compression = "gz",
+                   serialize   = True,
+                   backtrace   = False,
+                   diagnose    = False,
+                   enqueue     = True,
+                  )
+        
+        # Security logs
+        logger.add(self.log_dir / "security" / "security_{time:YYYY-MM-DD}.log",
+                   format      = "{message}",
+                   filter      = lambda record: record["extra"].get("log_type") == "security",
+                   level       = "INFO",
+                   rotation    = "00:00",
+                   retention   = "90 days",  # Keep security logs longer
+                   compression = "gz",
+                   serialize   = True,
+                   backtrace   = True,
+                   diagnose    = True,
+                   enqueue     = True,
+                  )
+        
+        # Error logs (separate file for easier monitoring)
+        logger.add(self.log_dir / "errors" / "errors_{time:YYYY-MM-DD}.log",
+                   format      = "{message}",
+                   filter      = lambda record: record["level"].name in ["ERROR", "CRITICAL"],
+                   level       = "ERROR",
+                   rotation    = "00:00",
+                   retention   = "30 days",
+                   compression = "gz",
+                   serialize   = True,
+                   backtrace   = True,
+                   diagnose    = True,
+                   enqueue     = True,
+                  )
+        
+        # Console output for production (JSON format)
+        logger.add(sys.stderr,
+                   format    = "{message}",
+                   level     = settings.LOG_LEVEL,
+                   serialize = True,
+                   backtrace = True,
+                   diagnose  = settings.DEBUG,
+                  )
+
+    
+    def _setup_development_logging(self) -> None:
+        """
+        Setup development logging with human-readable format
+        """
+        # Colorful console output for development
+        logger.add(sys.stderr, 
+                   format    = "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+                               "<level>{level: <8}</level> | "
+                               "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+                               "<level>{message}</level>",
+                   level     = settings.LOG_LEVEL,
+                   colorize  = True,
+                   backtrace = True,
+                   diagnose  = True,
+                   enqueue   = True,
+                )
+        
+        # File logging for development (structured)
+        logger.add(self.log_dir / "application" / "app_{time:YYYY-MM-DD}.log",
+                   format      = "{message}",
+                   level       = settings.LOG_LEVEL,
+                   rotation    = "10 MB",  # Rotate by size in development
+                   retention   = "7 days",
+                   compression = "gz",
+                   serialize   = True,
+                   backtrace   = True,
+                   diagnose    = True,
+                   enqueue     = True,
+                  )
+    
+
+    def _intercept_standard_logging(self) -> None:
+        """
+        Intercept standard library logging
+        """
+        # Get root logger
+        logging.root.setLevel(settings.LOG_LEVEL.upper())
+        
+        # Remove existing handlers
+        for handler in logging.root.handlers[:]:
+            logging.root.removeHandler(handler)
+        
+        # Add intercept handler
+        intercept_handler = InterceptHandler()
+        logging.root.addHandler(intercept_handler)
+        
+        # Intercept third-party loggers
+        for log_name in logging.root.manager.loggerDict.keys():
+            if log_name.startswith(("uvicorn", "fastapi", "detector", "processor")):
+                logging.getLogger(log_name).handlers  = [intercept_handler]
+                logging.getLogger(log_name).propagate = False
+    
+
+    def get_logger(self, name: Optional[str] = None):
+        """
+        Get a logger instance with context
+        
+        Arguments:
+        ----------
+            name { str } : Logger name (usually __name__)
+            
+        Returns:
+        --------
+            Logger instance
+        """
+        if name:
+            return logger.bind(logger_name = name)
+
+        return logger
+    
+
+    def log_performance(self, operation: str, duration: float, **kwargs) -> None:
+        """
+        Log performance metrics
+        
+        Arguments:
+        ----------
+            operation { str }   : Operation name 
+
+            duration  { float } : Duration in seconds
+            
+            **kwargs            : Additional performance metrics
+        """
+        performance_data = {"operation"        : operation,
+                            "duration_seconds" : round(duration, 4),
+                            "timestamp"        : datetime.now().isoformat(),
+                            **kwargs
+                           }
+        
+        logger.bind(log_type = "performance").info(f"Performance metric: {operation}",
+                    extra    = performance_data,
+                   )
+
+    
+    def log_security_event(self, event_type: str, user: Optional[str] = None, ip: Optional[str] = None, **kwargs) -> None:
+        """
+        Log security events
+        
+        Arguments:
+        ----------
+            event_type { str } : Type of security event
+            
+            user       { str } : User identifier (if available)
+            
+            ip         { str } : IP address (if available)
+            
+            **kwargs           : Additional security context
+        """
+        security_data = {"event_type" : event_type,
+                         "user"       : user,
+                         "ip_address" : ip,
+                         "timestamp"  : datetime.now().isoformat(),
+                         **kwargs,
+                        }
+        
+        logger.bind(log_type = "security").warning(f"Security event: {event_type}",
+                    extra    = security_data,
+                   )
+    
+    def log_api_request(self, method: str, path: str, status_code: int, duration: float, user: Optional[str] = None, ip: Optional[str] = None, **kwargs) -> None:
+        """
+        Log API request details
+        
+        Arguments:
+        ----------
+            method      { str }   : HTTP method
+
+            path        { str }   : Request path
+            
+            status_code { int }   : HTTP status code
+            
+            duration    { float } : Request duration in seconds
+            
+            user        { str }   : User identifier
+            
+            ip          { str }   : Client IP address
+            
+            **kwargs              : Additional request context
+        """
+        request_data = {"http_method"      : method,
+                        "path"             : path,
+                        "status_code"      : status_code,
+                        "duration_seconds" : round(duration, 4),
+                        "user"             : user,
+                        "ip_address"       : ip,
+                        "timestamp"        : datetime.now().isoformat(),
+                        **kwargs
+                       }
+        
+        # Log as info for successful requests, warning for client errors, error for server errors
+        if (status_code < 400):
+            logger.bind(log_type = "application").info(f"API Request: {method} {path} -> {status_code}",
+                        extra    = request_data,
+                       )
+
+        elif (status_code < 500):
+            logger.bind(log_type = "application").warning(f"API Client Error: {method} {path} -> {status_code}",
+                        extra    = request_data,
+                       )
+
+        else:
+            logger.bind(log_type = "application").error(f"API Server Error: {method} {path} -> {status_code}",
+                        extra    = request_data,
+                       )
+    
+
+    def log_detection_event(self, analysis_id: str, text_length: int, verdict: str, confidence: float, domain: str, processing_time: float, **kwargs) -> None:
+        """
+        Log text detection events
+        
+        Arguments:
+        ----------
+            analysis_id     { str }   : Unique analysis identifier
+
+            text_length     { int }   : Length of analyzed text
+            
+            verdict         { str }   : Detection verdict
+            
+            confidence      { float } : Confidence score
+            
+            domain          { str }   : Content domain
+            
+            processing_time { float } : Processing time in seconds
+            
+            **kwargs                  : Additional detection context
+        """
+        detection_data = {"analysis_id"             : analysis_id,
+                          "text_length"             : text_length,
+                          "verdict"                 : verdict,
+                          "confidence"              : round(confidence, 4),
+                          "domain"                  : domain,
+                          "processing_time_seconds" : round(processing_time, 4),
+                          "timestamp"               : datetime.now().isoformat(),
+                          **kwargs
+                        }
+        
+        logger.bind(log_type = "application").info(f"Detection completed: {analysis_id} -> {verdict}",
+                    extra    = detection_data,
+                   )
+
+    
+    def log_model_loading(self, model_name: str, success: bool, load_time: float, **kwargs) -> None:
+        """
+        Log model loading events
+        
+        Arguments:
+        ----------
+            model_name  { str }  : Name of the model
+
+            success     { bool } : Whether loading was successful
+            
+            load_time  { float } : Loading time in seconds
+            
+            **kwargs             : Additional model context
+        """
+        model_data = {"model_name"        : model_name,
+                      "success"           : success,
+                      "load_time_seconds" : round(load_time, 4),
+                      "timestamp"         : datetime.now().isoformat(),
+                      **kwargs
+                     }
+        
+        if success:
+            logger.bind(log_type = "application").info(f"Model loaded: {model_name}",
+                        extra    = model_data,
+                       )
+
+        else:
+            logger.bind(log_type = "application").error(f"Model failed to load: {model_name}",
+                        extra    = model_data,
+                       )
+
+    
+    def log_error(self, error_type: str, message: str, context: Dict[str, Any] = None, exception: Optional[Exception] = None) -> None:
+        """
+        Log error with context
+        
+        Arguments:
+        ----------
+            error_type { str }       : Type of error
+
+            message    { str }       : Error message
+            
+            context    { dict }      : Error context
+            
+            exception  { Exception } : Exception object
+        """
+        error_data = {"error_type" : error_type,
+                      "message"    : message,
+                      "context"    : context or {},
+                      "timestamp"  : datetime.now().isoformat(),
+                     }
+        
+        if exception:
+            error_data["exception"] = {"type"    : type(exception).__name__,
+                                       "message" : str(exception),
+                                      }
+        
+        logger.bind(log_type  = "application").error(f"Error: {error_type} - {message}",
+                    extra     = error_data,
+                    exception = exception,
+                   )
+    
+
+    def log_startup(self, component: str, success: bool, **kwargs) -> None:
+        """
+        Log application startup events
+        
+        Arguments:
+        ----------
+            component { str }  : Component name
+
+            success   { bool } : Whether startup was successful
+
+            **kwargs           : Additional startup context
+        """
+        startup_data = {"component" : component,
+                        "success"   : success,
+                        "timestamp" : datetime.now().isoformat(),
+                        **kwargs
+                       }
+        
+        if success:
+            logger.bind(log_type = "application").info(f"Startup: {component} initialized",
+                        extra    = startup_data,
+                       )
+
+        else:
+            logger.bind(log_type = "application").error(f"Startup: {component} failed",
+                        extra    = startup_data,
+                       )
+
+    
+    def cleanup(self) -> None:
+        """
+        Cleanup logging resources
+        """
+        try:
+            logger.complete()
+            logger.info("Logging system cleanup completed")
+        
+        except Exception as e:
+            print(f"Error during logging cleanup: {e}")
+
+
+# Global logger instance
+central_logger = CentralizedLogger()
+
+
+# Convenience functions for direct usage
+def get_logger(name: Optional[str] = None):
+    """
+    Get a logger instance
+    
+    Arguments:
+    ----------
+        name { str } : Logger name
+        
+    Returns:
+    --------
+        Logger instance
+    """
+    return central_logger.get_logger(name)
+
+
+def log_performance(operation: str, duration: float, **kwargs) -> None:
+    """
+    Log performance metrics
+    """
+    central_logger.log_performance(operation, duration, **kwargs)
+
+
+def log_security_event(event_type: str, user: Optional[str] = None, ip: Optional[str] = None, **kwargs) -> None:
+    """
+    Log security events
+    """
+    central_logger.log_security_event(event_type, user, ip, **kwargs)
+
+
+def log_api_request(method: str, path: str, status_code: int, duration: float, user: Optional[str] = None, ip: Optional[str] = None, **kwargs) -> None:
+    """
+    Log API request details
+    """
+    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:
+    """
+    Log text detection events
+    """
+    central_logger.log_detection_event(analysis_id, text_length, verdict, confidence, domain, processing_time, **kwargs)
+
+
+def log_model_loading(model_name: str, success: bool, load_time: float, **kwargs) -> None:
+    """
+    Log model loading events
+    """
+    central_logger.log_model_loading(model_name, success, load_time, **kwargs)
+
+
+def log_error(error_type: str, message: str, context: Dict[str, Any] = None, exception: Optional[Exception] = None) -> None:
+    """
+    Log error with context
+    """
+    central_logger.log_error(error_type, message, context, exception)
+
+
+def log_startup(component: str, success: bool, **kwargs) -> None:
+    """
+    Log application startup events
+    """
+    central_logger.log_startup(component, success, **kwargs)
+
+
+
+
+# Export
+__all__ = ["log_error",
+           "get_logger",
+           "log_startup",
+           "central_logger",
+           "log_performance",
+           "log_api_request",
+           "CentralizedLogger",
+           "log_model_loading",
+           "log_security_event",
+           "log_detection_event",
+          ]