README.md

metadata

title: DeepPragma Classifier
emoji: 🛡️
colorFrom: blue
colorTo: gray
sdk: gradio
sdk_version: 4.40.0
app_file: app.py
pinned: false
license: mit

🛡️ DeepPragma Classifier

DeepPragma is an NLP system for detecting hate speech in social media text — including the forms that traditional lexical classifiers consistently miss: sarcasm, irony, and coded/dogwhistle references.

Most hate speech detectors rely on keyword matching or sentiment polarity. This works for direct insults, but fails precisely where bad actors adapt: when hate is expressed through ironic false compliments, or through culturally coded euphemisms that appear neutral out of context. DeepPragma addresses both failure modes.

The problem

Standard approaches (lexicon-based sentiment analysis, keyword blocklists, simple syntactic pattern matching) break down on real-world examples like:

• "Oh sure, because people from your country are always SO trustworthy." — positive-sounding words, hateful intent.
• "The Austrian painter" or "those who don't eat pork" — semantically neutral phrases used within specific communities as indirect, deniable references to a targeted group or figure.

Neither case contains an obvious "hate word." Detecting them requires reasoning about pragmatic context, not just surface-level lexical features.

Approach

DeepPragma uses a hybrid pipeline:

1. Primary classification via LLM (Groq / Llama 3.3 70B) — the core classifier reasons about tone, contrast between literal and intended meaning, and structural cues typical of coded speech. This is the component actually capable of resolving irony and dogwhistles, since it can model context the way lexical tools cannot.
2. Auxiliary lexical/syntactic signals (spaCy + NLTK VADER) — sentiment scores and dependency-parse patterns are computed as supporting signals, not as gatekeepers. They inform but never block the LLM classification.
3. Curated knowledge retrieval — a maintained, source-cited knowledge base of documented coded speech patterns is retrieved and passed as context to the classifier when relevant, grounding its reasoning instead of relying purely on the model's guesswork.

Classification labels

Label	Meaning
Direct Hate Speech	Explicit insults or slurs, no irony involved.
Sarcastic Hate Speech	Literal wording is neutral/positive, but tone and context reveal a hateful or discriminatory attack.
Coded/Dogwhistle Hate — Needs Review	Surface-neutral phrase that may function as an indirect, community-specific reference to a targeted group or figure. Flagged for human review, not treated as a final verdict — false positives here have real costs (e.g. censoring legitimate discussion of religion or history).
Sarcastic/Ironic (Non-Hateful)	Irony is present, but there is no hate target.
Neutral	No hate, no irony, no coding detected.

Project structure

.
├── app.py                     # Gradio interface
├── src/
│   ├── engine.py               # Auxiliary lexical/syntactic signal extraction (spaCy + VADER)
│   ├── llm_client.py           # Groq API wrapper — primary classifier
│   ├── knowledge_retriever.py  # Keyword-based retrieval over the curated knowledge base
│   └── knowledge_base.json     # Curated, source-cited dogwhistle/coded-speech patterns
├── requirements.txt
└── README.md

Setup

1. Clone the repository.
2. Set the GROQ_API_KEY environment variable (as a Space secret, or in a local .env file).
3. Install dependencies:

   pip install -r requirements.txt
   

4. Run locally:

   python app.py
   

On Hugging Face Spaces, dependencies and model downloads (en_core_web_sm, vader_lexicon) are handled automatically on first startup.

Extending the knowledge base

src/knowledge_base.json is intentionally kept empty of unverified entries by default. Each entry should include:

{
  "id": "unique_id",
  "surface_pattern": "the neutral-sounding phrase",
  "category": "type of coding (e.g. religious/ethnic dogwhistle)",
  "note": "what community uses it, and why, in your own words",
  "source": "citation — academic paper, ADL Hate Symbols Database, documented observation, etc."
}

Only add entries you have personally verified against a credible source. This file is meant to improve detection accuracy and give the model grounded context — not to serve as a general reference for coded terminology.

Known limitations

• Coded/dogwhistle detection depends entirely on the coverage and quality of the curated knowledge base — it will not catch patterns that haven't been documented yet.
• Dogwhistles evolve quickly and vary by platform and community; the knowledge base requires ongoing maintenance.
• The system is a decision-support tool, not an automated moderation action-taker. Coded/Dogwhistle Hate — Needs Review results are explicitly designed to route to a human reviewer rather than trigger automatic removal.

Author

Built by jamalinu — computational linguist and NLP engineer, Barcelona.