README.md

---
license: mit
language:
- en
- tr
tags:
- argumentation-analysis
- fallacy-detection
- rhetoric-analysis
- nlp
- spacy
- bert
- argument-structure
- logical-reasoning
- discourse-analysis
- text-analysis
- python
datasets:
- text
---

# ETHOS - The AI Arbiter of Rational Discourse

![ETHOS Logo](https://img.shields.io/badge/ETHOS-v2.2-blue?style=for-the-badge)
![Status](https://img.shields.io/badge/Status-Production-success?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

## 🔍 Model Description

**ETHOS (Evaluative Text Heuristic for Objective Scrutiny)** is a pioneering argument analysis system that evaluates the logical structure, validity, and rhetorical quality of text. Designed to serve as an AI arbiter of rational discourse, ETHOS provides comprehensive analysis of argumentation quality through sophisticated NLP techniques.

Using a combination of rule-based analysis and neural language models (BERT), ETHOS dissects texts to identify claims, premises, logical fallacies, and rhetorical devices—creating a complete picture of argument structure and quality. The system then visualizes these relationships and provides detailed assessments of logical soundness and rhetorical clarity.

### 🌟 Key Features

- **🧩 Advanced Argument Structure Analysis**: Extracts claims and premises from text with high accuracy using dependency parsing and linguistic markers
  
- **🔗 Semantic Argument Linking**: Uses BERT embeddings to establish relationships between premises and claims based on semantic similarity
  
- **⚠️ Sophisticated Fallacy Detection**: Identifies common logical fallacies (Ad Populum, Hasty Generalization, False Dichotomy) through both rule-based and ML-based approaches
  
- **🎭 Rhetoric Device Recognition**: Detects rhetorical questions, strong sentiment expressions, and superlatives that may influence argument perception
  
- **📊 Logical Soundness Scoring**: Evaluates the overall logical quality of arguments with nuanced ratings
  
- **📈 Comprehensive Visualization**: Generates clear argument graphs showing support relationships between premises and claims
  
- **💬 Natural Language Explanations**: Provides human-readable analysis of logical structure and potential issues

## 🚀 Why ETHOS is Revolutionary

ETHOS represents a significant advancement in automated argument analysis:

1. **Deeper than Syntax**: Goes beyond simple keyword matching by using semantic understanding to link arguments
   
2. **Multi-dimensional Analysis**: Examines both structural (argumentation form) and rhetorical (persuasive techniques) aspects simultaneously
   
3. **Visual Representation**: Transforms complex argumentative structures into intuitive graphs
   
4. **Balanced Assessment**: Provides nuanced evaluation rather than binary judgments about argument quality
   
5. **Transparency**: Clearly highlights the evidence for each assessment, allowing users to understand the system's reasoning

## 💡 Intended Uses

ETHOS is designed for applications requiring sophisticated argument analysis:

- **📝 Academic Research**: Analyze argument structures in papers, essays, and scholarly works
  
- **🎓 Educational Assessment**: Evaluate student essays and argumentation skills
  
- **📰 Media Analysis**: Assess the logical quality of news articles, editorials, and opinion pieces
  
- **💼 Professional Writing**: Improve the logical coherence and persuasiveness of business communications
  
- **🗣️ Debate Preparation**: Analyze strengths and weaknesses in argumentative positions
  
- **📊 Policy Evaluation**: Examine the logical structure of policy proposals and position papers

## 🛠️ System Architecture

ETHOS consists of several modular components that work together seamlessly:

1. **argument_analyzer**: Extracts argument components (claims and premises) using dependency parsing and linguistic indicators
   
2. **logic_analyzer**: Identifies logical fallacies through rule-based patterns and machine learning
   
3. **rhetoric_analyzer**: Detects rhetorical devices using sentiment analysis and linguistic patterns
   
4. **argument_visualizer**: Creates graph-based visualizations of argument structure using semantic similarity
   
5. **synthesis_engine**: Combines all analyses to produce overall evaluations of argument quality
   
6. **nlp_utils**: Provides NLP infrastructure including spaCy and BERT embedding functionality

## 📊 Performance Highlights

ETHOS demonstrates strong capabilities in:

- **Argument Component Identification**: Accurately extracts claims and premises with confidence scores
- **Semantic Relationship Detection**: Successfully links related premises and claims based on meaning
- **Fallacy Recognition**: Identifies common fallacies with explanatory context
- **Rhetorical Pattern Detection**: Effectively flags potential rhetorical techniques
- **Intuitive Visualization**: Generates clear argument graphs showing support relationships

## 📦 Installation and Usage

```bash
# Install required packages
pip install spacy transformers torch networkx typer rich vaderSentiment pydantic

# Download required model
python -m spacy download en_core_web_lg

# Clone the repository
git clone https://github.com/yourusername/ethos.git
cd ethos

# Run the CLI interface
python cli.py --text "Your text to analyze"
# Or analyze from file
python cli.py --file path/to/your/document.txt
```

## 💻 Example Usage

```python
import spacy
import nlp_utils
import argument_analyzer
import logic_analyzer
import rhetoric_analyzer
import argument_visualizer
import synthesis_engine

# Load models
nlp_utils.load_spacy_model()
nlp_utils.load_bert()

# Process text
text = "Climate change is definitely happening because global temperatures have risen significantly over the past century. Everyone knows this is a serious problem that requires immediate action."
doc = nlp_utils.process_text_spacy(text)

# Get sentence embeddings for semantic linking
sentence_embeddings = nlp_utils.get_all_sentence_embeddings(doc)

# Analyze arguments
argument_components = argument_analyzer.enhanced_component_analyzer(doc)

# Detect fallacies
fallacy_findings = logic_analyzer.enhanced_fallacy_analyzer(doc)

# Analyze rhetoric
rhetoric_findings = rhetoric_analyzer.simple_rhetoric_analyzer(doc)

# Combine findings
all_findings = fallacy_findings + rhetoric_findings

# Generate summary ratings
analysis_summary = synthesis_engine.generate_summary_ratings(argument_components, all_findings)

# Create argument graph
argument_graph = argument_visualizer.build_argument_graph(argument_components, sentence_embeddings)

# Print results
print("Argument Components:")
for comp in argument_components:
    print(f"{comp.component_type}: {comp.text} (Confidence: {comp.confidence:.2f})")

print("\nFindings:")
for finding in all_findings:
    print(f"{finding.finding_type}: {finding.description}")

print("\nSummary Ratings:")
for category, rating in analysis_summary.items():
    print(f"{category}: {rating}")
```

## 🔧 Customization Options

ETHOS can be customized in several ways:

- **Fallacy Detection Rules**: Extend or modify rules for identifying additional fallacy types
- **Linguistic Indicators**: Add new claim/premise indicators for different domains or languages
- **Similarity Threshold**: Adjust the semantic similarity threshold for argument linking
- **Visualization Format**: Customize the representation of argument structures

## 📈 Future Development

The ETHOS project is continuously evolving, with planned enhancements including:

- **Expanded Fallacy Detection**: Additional fallacy types and improved ML-based detection
- **Cross-Document Analysis**: Analyze arguments spanning multiple documents
- **Multi-language Support**: Extend capabilities to additional languages
- **Interactive Visualizations**: Enhanced visual representations with interactive elements
- **API Implementation**: RESTful API for seamless integration with other applications

## 📋 Citation

If you use ETHOS in your research, please cite:

```
@software{ethos_2025,
  author = {Abdullah Kocaman},
  title = {ETHOS: The AI Arbiter of Rational Discourse},
  year = {2025},
  url = {https://huggingface.co/NextGenC/ETHOS},
  version = {2.2},
  description = {A comprehensive system for argument analysis, fallacy detection, and rhetorical evaluation}
}
```

---

# ETHOS - Rasyonel Söylem için Yapay Zeka Hakemi

![ETHOS Logo](https://img.shields.io/badge/ETHOS-v2.2-blue?style=for-the-badge)
![Durum](https://img.shields.io/badge/Durum-Üretim-success?style=for-the-badge)
![Lisans](https://img.shields.io/badge/Lisans-MIT-green?style=for-the-badge)

## 🔍 Model Açıklaması

**ETHOS (Değerlendirici Metin Buluşsal Objektif İnceleme Sistemi)**, metinlerin mantıksal yapısını, geçerliliğini ve retorik kalitesini değerlendiren öncü bir argüman analiz sistemidir. Rasyonel söylemin yapay zeka hakemi olarak hizmet etmek üzere tasarlanan ETHOS, sofistike NLP teknikleri aracılığıyla kapsamlı argümantasyon kalitesi analizi sağlar.

Kural tabanlı analiz ve sinir dili modellerinin (BERT) bir kombinasyonunu kullanan ETHOS, iddiaları, gerekçeleri, mantık safsatalarını ve retorik araçları tanımlamak için metinleri detaylı bir şekilde inceler—böylece argüman yapısı ve kalitesinin tam bir resmini oluşturur. Sistem daha sonra bu ilişkileri görselleştirir ve mantıksal sağlamlık ve retorik netlik hakkında ayrıntılı değerlendirmeler sunar.

### 🌟 Temel Özellikler

- **🧩 Gelişmiş Argüman Yapısı Analizi**: Bağımlılık ayrıştırma ve dilbilimsel belirteçleri kullanarak metinden iddiaları ve gerekçeleri yüksek doğrulukla çıkarır
  
- **🔗 Anlamsal Argüman Bağlama**: Anlamsal benzerliğe dayalı olarak gerekçeler ve iddialar arasında ilişkiler kurmak için BERT gömüleri kullanır
  
- **⚠️ Sofistike Safsata Tespiti**: Hem kural tabanlı hem de ML tabanlı yaklaşımlarla yaygın mantık safsatalarını (Ad Populum, Aceleci Genelleme, Yanlış İkilem) tespit eder
  
- **🎭 Retorik Araç Tanıma**: Argüman algısını etkileyebilecek retorik soruları, güçlü duygu ifadelerini ve üstünlük belirteçlerini tespit eder
  
- **📊 Mantıksal Sağlamlık Puanlaması**: Argümanların genel mantıksal kalitesini nüanslı derecelendirmelerle değerlendirir
  
- **📈 Kapsamlı Görselleştirme**: Gerekçeler ve iddialar arasındaki destek ilişkilerini gösteren net argüman grafikleri oluşturur
  
- **💬 Doğal Dil Açıklamaları**: Mantıksal yapı ve potansiyel sorunlar hakkında insan tarafından okunabilir analizler sunar

## 🚀 ETHOS Neden Devrim Niteliğinde

ETHOS, otomatik argüman analizinde önemli bir ilerlemeyi temsil eder:

1. **Sözdiziminden Daha Derin**: Argümanları bağlamak için anlamsal anlayış kullanarak basit anahtar kelime eşleştirmesinin ötesine geçer
   
2. **Çok Boyutlu Analiz**: Hem yapısal (argümantasyon formu) hem de retorik (ikna teknikleri) yönleri eş zamanlı olarak inceler
   
3. **Görsel Temsil**: Karmaşık argümantatif yapıları sezgisel grafiklere dönüştürür
   
4. **Dengeli Değerlendirme**: Argüman kalitesi hakkında ikili yargılar yerine nüanslı bir değerlendirme sunar
   
5. **Şeffaflık**: Her değerlendirme için kanıtları açıkça vurgular, kullanıcıların sistemin mantığını anlamasına olanak tanır

## 💡 Amaçlanan Kullanımlar

ETHOS, sofistike argüman analizi gerektiren uygulamalar için tasarlanmıştır:

- **📝 Akademik Araştırma**: Makalelerde, denemelerde ve bilimsel çalışmalarda argüman yapılarını analiz etme
  
- **🎓 Eğitim Değerlendirmesi**: Öğrenci denemelerini ve argümantasyon becerilerini değerlendirme
  
- **📰 Medya Analizi**: Haber makalelerinin, editöryel yazıların ve görüş yazılarının mantıksal kalitesini değerlendirme
  
- **💼 Profesyonel Yazım**: İş iletişimlerinin mantıksal tutarlılığını ve ikna ediciliğini iyileştirme
  
- **🗣️ Tartışma Hazırlığı**: Argümantatif pozisyonlardaki güçlü ve zayıf yönleri analiz etme
  
- **📊 Politika Değerlendirmesi**: Politika önerilerinin ve pozisyon belgelerinin mantıksal yapısını inceleme

## 🛠️ Sistem Mimarisi

ETHOS, sorunsuz bir şekilde birlikte çalışan çeşitli modüler bileşenlerden oluşur:

1. **argument_analyzer**: Bağımlılık ayrıştırma ve dilbilimsel belirteçleri kullanarak argüman bileşenlerini (iddialar ve gerekçeler) çıkarır
   
2. **logic_analyzer**: Kural tabanlı kalıplar ve makine öğrenimi yoluyla mantıksal safsataları tanımlar
   
3. **rhetoric_analyzer**: Duygu analizi ve dilbilimsel kalıpları kullanarak retorik araçları tespit eder
   
4. **argument_visualizer**: Anlamsal benzerliği kullanarak argüman yapısının grafik tabanlı görselleştirmelerini oluşturur
   
5. **synthesis_engine**: Argüman kalitesinin genel değerlendirmelerini üretmek için tüm analizleri birleştirir
   
6. **nlp_utils**: spaCy ve BERT gömme işlevselliği dahil olmak üzere NLP altyapısı sağlar

## 📊 Performans Öne Çıkanları

ETHOS, şu alanlarda güçlü yetenekler göstermektedir:

- **Argüman Bileşeni Tanımlama**: İddiaları ve gerekçeleri güven skorlarıyla doğru bir şekilde çıkarır
- **Anlamsal İlişki Tespiti**: İlgili gerekçeleri ve iddiaları anlamlarına dayalı olarak başarıyla birbirine bağlar
- **Safsata Tanıma**: Açıklayıcı bağlamla yaygın safsataları tanımlar
- **Retorik Kalıp Tespiti**: Potansiyel retorik teknikleri etkili bir şekilde işaretler
- **Sezgisel Görselleştirme**: Destek ilişkilerini gösteren net argüman grafikleri oluşturur

## 📦 Kurulum ve Kullanım

```bash
# Gerekli paketleri yükleyin
pip install spacy transformers torch networkx typer rich vaderSentiment pydantic

# Gerekli modeli indirin
python -m spacy download en_core_web_lg

# Depoyu klonlayın
git clone https://github.com/kullaniciadi/ethos.git
cd ethos

# CLI arayüzünü çalıştırın
python cli.py --text "Analiz edilecek metniniz"
# Veya dosyadan analiz edin
python cli.py --file path/to/your/document.txt
```

## 💻 Örnek Kullanım

```python
import spacy
import nlp_utils
import argument_analyzer
import logic_analyzer
import rhetoric_analyzer
import argument_visualizer
import synthesis_engine

# Modelleri yükleyin
nlp_utils.load_spacy_model()
nlp_utils.load_bert()

# Metni işleyin
text = "İklim değişikliği kesinlikle gerçekleşiyor çünkü küresel sıcaklıklar son yüzyılda önemli ölçüde yükseldi. Herkes bunun acil eylem gerektiren ciddi bir sorun olduğunu biliyor."
doc = nlp_utils.process_text_spacy(text)

# Anlamsal bağlantı için cümle gömüleri alın
sentence_embeddings = nlp_utils.get_all_sentence_embeddings(doc)

# Argümanları analiz edin
argument_components = argument_analyzer.enhanced_component_analyzer(doc)

# Safsataları tespit edin
fallacy_findings = logic_analyzer.enhanced_fallacy_analyzer(doc)

# Retoriği analiz edin
rhetoric_findings = rhetoric_analyzer.simple_rhetoric_analyzer(doc)

# Bulguları birleştirin
all_findings = fallacy_findings + rhetoric_findings

# Özet derecelendirmeleri oluşturun
analysis_summary = synthesis_engine.generate_summary_ratings(argument_components, all_findings)

# Argüman grafiği oluşturun
argument_graph = argument_visualizer.build_argument_graph(argument_components, sentence_embeddings)

# Sonuçları yazdırın
print("Argüman Bileşenleri:")
for comp in argument_components:
    print(f"{comp.component_type}: {comp.text} (Güven: {comp.confidence:.2f})")

print("\nBulgular:")
for finding in all_findings:
    print(f"{finding.finding_type}: {finding.description}")

print("\nÖzet Derecelendirmeleri:")
for category, rating in analysis_summary.items():
    print(f"{category}: {rating}")
```

## 🔧 Özelleştirme Seçenekleri

ETHOS birkaç şekilde özelleştirilebilir:

- **Safsata Tespit Kuralları**: Ek safsata türlerini tanımlamak için kuralları genişletin veya değiştirin
- **Dilbilimsel Göstergeler**: Farklı alanlar veya diller için yeni iddia/gerekçe göstergeleri ekleyin
- **Benzerlik Eşiği**: Argüman bağlantısı için anlamsal benzerlik eşiğini ayarlayın
- **Görselleştirme Formatı**: Argüman yapılarının temsilini özelleştirin

## 📈 Gelecek Geliştirmeler

ETHOS projesi sürekli gelişmekte olup, planlanan iyileştirmeler şunları içerir:

- **Genişletilmiş Safsata Tespiti**: Ek safsata türleri ve geliştirilmiş ML tabanlı tespit
- **Çapraz Belge Analizi**: Birden fazla belgeye yayılan argümanları analiz etme
- **Çoklu Dil Desteği**: Yetenekleri ek dillere genişletme
- **Etkileşimli Görselleştirmeler**: Etkileşimli öğelerle geliştirilmiş görsel temsiller
- **API Uygulaması**: Diğer uygulamalarla sorunsuz entegrasyon için RESTful API

## 📋 Alıntı

Araştırmanızda ETHOS'u kullanıyorsanız, lütfen şu şekilde alıntı yapın:

```
@software{ethos_2025,
  author = {Abdullah Kocaman},
  title = {ETHOS: Rasyonel Söylem için Yapay Zeka Hakemi},
  year = {2025},
  url = {https://huggingface.co/NextGenC/ETHOS},
  version = {2.2},
  description = {Argüman analizi, safsata tespiti ve retorik değerlendirme için kapsamlı bir sistem}
}
```