kh-shield

kh-shield is a high-throughput, multimodal content moderation suite written in C++23 with Python bindings. Designed from the ground up for zero-GPU execution, kh-shield performs real-time moderation across text, images, audio, and video streams while maintaining strict resource limits (optimized for 2 vCPU and 8GB RAM host environments).

The engine integrates deterministic NLP algorithms, digital signal processing (DSP), and geometric computer vision to enforce comprehensive ethical, safety, and content safety policies.

Technical Highlights

• Zero-GPU Multimodal Processing: All visual and acoustic analysis routines execute on native CPU vector instructions (AVX2/NEON) without external GPU or deep-learning model runtime dependencies.
• Stream-Based Buffer Allocation: Processes high-definition video and audio files in ring-buffered memory streams, bounding RAM utilization under 50MB regardless of file size.
• Deterministic Text Moderation: Integrates Aho-Corasick exact matching, an Arabizi normalization engine, and a quantized CPU-bound SAM text model for Arabic and multilingual semantic validation.
• Geometric Exposure & Skin Detection: Combines adaptive HSV color space thresholds, face bounding box exclusion zones, and spatial contour analysis to accurately detect explicit body exposure while preventing false positives on faces and hands.
• Acoustic Energy & Spectral Analysis: Employs Fast Fourier Transform (FFT) and Root Mean Square (RMS) energy evaluation to detect explicit music patterns and high-BPM background audio while isolating spoken vocals.
• OCR Bridge Layer: Extract on-screen text overlays from suspicious video frames and routes the string directly into the core text filtering pipeline.

Installation & Build

System Dependencies

• C++23 compliant compiler (GCC 13+ or Clang 16+)
• CMake 3.22+
• OpenCV 4.x (C++ API, CPU modules)
• Tesseract OCR C++ API

Build Native Engine

git clone [https://github.com/khwarzma/kh-shield.git](https://github.com/khwarzma/kh-shield.git)
cd kh-shield
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Install Python Binding

pip install .

Quickstart

Python API

import khshield

# Initialize engine with preferred policy preset
engine = khshield.ShieldEngine(preset=khshield.Preset.STRICT)

# 1. Moderating Raw Text
text_report = engine.analyze_text("نص تجريبي للترشيح المباشر")
print(f"Is Safe: {text_report.is_safe}")

# 2. Moderating Image Files
image_report = engine.analyze_image("path/to/image.jpg")
if not image_report.is_safe:
    print(f"Image Blocked. Risk Score: {image_report.risk_score}")

# 3. Moderating Video Streams (Audio + Visual + OCR)
video_report = engine.analyze_video("path/to/media.mp4")
print(f"Status: {'SAFE' if video_report.is_safe else 'BLOCKED'}")
print(f"Violation Category: {video_report.violation_type}")

Documentation Directory

• ARCHITECTURE.md — Multithreading model, stream buffering, and pipeline mechanics.
• PRESETS_AND_RULES.md — Threshold mathematical formulas, HSV limits, and preset rules.
• API_REFERENCE.md — Complete C++ and Python class definitions and data structures.
• AI_INSTRUCTIONS.md — Constraints and coding standards for AI coding assistants.