README.md

metadata

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
Context	Undeclared context or hidden assumptions
Framing	Undefined terms or missing criteria
Responsibility	Ghost "we" or unclear ownership
Validation	Approval conditioned on not asking
Ambiguity	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

JINA_API_KEY=your_jina_api_key  # For RAG embeddings

Run Locally

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