README.md

---
title: ClarityGuard
emoji: 🔍
colorFrom: blue
colorTo: purple
sdk: docker
pinned: true
license: apache-2.0
short_description: Neuro-inclusive communication clarity assistant
tags:
  - gemma4
  - rag
  - jina
  - neurodiversity
  - accessibility
models:
  - CharlieBonito/clarity-guard-gemma4-7b
---

# 🔍 ClarityGuard — Neuro-inclusive Communication Assistant

**Winner Submission: Gemma 4 Good Hackathon 2026**

ClarityGuard helps neurodivergent individuals decode ambiguous workplace and personal messages by analyzing message structure—not the user's ability to understand.

## Active Model

| Property | Value |
|----------|-------|
| Model repo | `CharlieBonito/clarity-guard-gemma4-7b` |
| Active version | ClarityGuard v2 |
| Training checkpoint | 750 |
| Base model | Unsloth Gemma 4 E4B IT BNB 4-bit |
| Architecture | Gemma 4 |
| Parameters | 7.52B |
| Quantization | GGUF / Q4_K_M |
| Model context metadata | 131072 tokens |
| Space deployed context | 12288 tokens |
| Multimodal | Yes, via `mmproj-ClarityGuard-v2.gguf` |

Active production files:

- `ClarityGuard-v2.gguf` — main model
- `mmproj-ClarityGuard-v2.gguf` — multimodal projector

Deprecated checkpoint-375 files are not the active deployment artifacts:

- `Checkpoint-375-Ollama-Clean-7.5B-Q4_K_M.gguf`
- `mmproj-Checkpoint-375-Ollama-Clean-BF16.gguf`

## 🎯 Problem

Neurodivergent people (autistic, ADHD, dyslexic) often struggle with:
- Ambiguous instructions that lack clear action items
- Corporate speak that hides expectations
- Double deadlines (stated vs. implied)
- Vague feedback without observable criteria

This isn't a cognitive deficit—it's a **protocol mismatch**. When a message lacks a clear subject, deadline, or measurable criterion, confusion is the logical response.

## 💡 Solution

ClarityGuard uses the **C.F.R.V.A. Framework** to analyze messages:

| Factor | What It Detects |
|--------|-----------------|
| **C**ontext | Undeclared context or hidden assumptions |
| **F**raming | Undefined terms or missing criteria |
| **R**esponsibility | Ghost "we" or unclear ownership |
| **V**alidation | Approval conditioned on not asking |
| **A**mbiguity | Jargon, metaphors, or unwritten support |

The model then generates:
1. **Analysis** — What's missing from the message
2. **Cognitive Protection** — Validation that confusion is appropriate
3. **Read-Back Question** — A concrete clarification to send
4. **Follow-up Plan** — If ambiguity persists

## 🏗️ Architecture

```
User Message → Jina Embeddings (RAG) → ClarityGuard v2 / Gemma 4 E4B IT → Structured Analysis
                     ↓
           Knowledge Base (Chatty System)
```

### Components:
- **ClarityGuard v2 / Fine-tuned Gemma 4 E4B IT** (Unsloth) — 7.52B parameters, Q4_K_M quantization, checkpoint 750
- **Jina Embeddings v3** — Semantic search over knowledge base
- **RAG Documents** — Chatty 231051 framework + manipulation awareness content
- **Hugging Face GPU Space** — CUDA-accelerated llama.cpp inference

## 🚀 Technical Details

### Model Training
- Base: Unsloth Gemma 4 E4B IT BNB 4-bit
- Fine-tuning: Unsloth Studio
- Active checkpoint: 750
- Quantization: Q4_K_M for deployment
- Multimodal support: `mmproj-ClarityGuard-v2.gguf` for vision/audio projector support

### RAG System
- Embeddings: Jina v3 (1024 dimensions)
- Documents: 3 knowledge base files (Chatty framework, manipulation awareness)
- Retrieval: Top-k semantic search

### Categories
- **Digital Equity & Inclusivity** — Breaking down communication barriers
- **Safety & Trust** — Transparent, explainable AI framework
- **Unsloth Track** — Fine-tuned with Unsloth Studio
- **llama.cpp Track** — Optimized deployment with CUDA

## 📚 Knowledge Base

ClarityGuard draws from:
1. **Chatty 231051** — Symbolic framework for ethical analysis
2. **Manipulation Awareness** — Recognition of gaslighting patterns
3. **Workplace Communication** — Structural analysis of corporate messaging

## 🔧 Setup

### Environment Variables
```bash
JINA_API_KEY=your_jina_api_key  # For RAG embeddings
```

### Run Locally
```bash
pip install -r requirements.txt
python app.py
```

## 📖 Example Usage

**Input:**
> "We need to fix that soon."

**Analysis (C.F.R.V.A. Score: 35/50):**

> 🔍 **Analysis:** This message has no clear subject ("fix what?"), no deadline ("soon" is undefined), and no assigned responsibility ("we" is a ghost subject).

> 🔒 **Cognitive Protection:** Your confusion is not a failure. "We need to fix that soon" cannot be executed with certainty by anyone—the ambiguity is in the message, not your processing.

> ✍️ **Suggested Clarification:**
> "To make sure I understand: when you say 'fix that,' do you mean [specific item]? What does 'fixed' look like? And by when do you need it?"

## 🏆 Awards Categories

- Digital Equity & Inclusivity ($10,000)
- Safety & Trust ($10,000)
- Unsloth Special Track ($10,000)
- llama.cpp Special Track ($10,000)

## 👥 Team

**Charlie Lengemann** — Fine-tuning, architecture, knowledge base design

## 📄 License

Apache 2.0

---

**Built with ❤️ for the neurodivergent community**