khshield 🛡️

High-Throughput, Zero-GPU Multimodal Content Moderation Engine in C++23 & Python

khshield is an enterprise-grade content moderation suite engineered for low-latency, real-time evaluation of text, visual buffers, and acoustic streams. Built with a native C++23 core and lightweight Pybind11 bindings, khshield enforces strict content safety policies without heavy GPU dependencies, optimizing infrastructure costs on cloud and edge host nodes.

---

Technical Highlights

• Multi-Dialect Arabic Text Engine: Integrated Aho-Corasick automaton with dynamic JSON rulesets covering 20+ Arabic country dialects (EGY, SAU, JOR, PAL, SYR, GULF, MSA, etc.) alongside Arabizi normalization and quantized CPU-bound SAM text inference.
• Zero-GPU Visual Processing: Combines adaptive HSV skin contour detection, face bounding-box exclusion zones, and geometric spatial analysis directly on raw NumPy image buffers (uint8).
• Acoustic Energy & Spectral Analysis: Evaluates PCM audio streams (float32) via Fast Fourier Transform (FFT) spectral energy tracking, Root Mean Square (RMS) envelope calculation, and BPM detection.
• Zero-Copy Memory Mapping: Direct C++ buffer access for Python NumPy arrays, avoiding data duplication overhead during image and audio evaluations.
• Deterministic Resource Boundaries: Optimized for low-spec hosts (bounded within 2 vCPUs and minimal RAM footprint) via stream ring-buffering.

---

Installation

Via PyPI (Recommended)

pip install khshield

Build Native C++ Library from Source

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)

---

Quickstart (Python API)

1. Multi-Dialect Text Moderation

import khshield

# Initialize engine with all 20+ Arabic dialects
engine = khshield.ShieldEngine(preset=khshield.Preset.STRICT)

report = engine.analyze_text("نص عشوائي للتحقق من السلامة")
print(f"Is Safe: {report.is_safe}")

# Scope text moderation strictly to specific dialects (e.g., Egyptian & Saudi)
egy_sau_engine = khshield.ShieldEngine(dialects=["EGY", "SAU"])

2. Visual Buffer Analysis (NumPy / OpenCV)

import numpy as np
import khshield

# Raw RGB image array (Height x Width x Channels)
image_buffer = np.zeros((100, 100, 3), dtype=np.uint8)

report = khshield.analyze_image(image_buffer, width=100, height=100, channels=3)
if not report.is_safe:
    print(f"Skin Exposure Ratio: {report.visual.skin_percentage:.2f}")

3. Audio Stream Evaluation

import numpy as np
import khshield

# PCM float32 audio samples (44.1kHz)
pcm_data = np.zeros(44100 * 2, dtype=np.float32)

report = khshield.analyze_audio(pcm_data, sample_rate=44100)
print(f"Audio Flagged: {report.audio.flagged} | BPM: {report.audio.bpm}")

---

Documentation Directory

• ARCHITECTURE.md — Pipeline mechanics, multithreading model, and memory buffers.
• PRESETS_AND_RULES.md — Mathematical formulas, HSV boundaries, and preset configurations.
• API_REFERENCE.md — Complete C++ and Python API specification.
• AI_INSTRUCTIONS.md — Architectural guardrails and coding standards for AI assistants.

---

License

Distributed under the MIT License. Developed and Maintained by Khwarzma.