Metadata-Version: 2.4
Name: khshield
Version: 1.0.0
Summary: High-throughput C++23 Zero-GPU Multimodal Content Moderation Engine
Author-email: IM4 <im4@bareeed.com>, khwarzma <khwarzma@bareeed.com>
License: MIT
Project-URL: Homepage, https://github.com/khwarzma/kh-shield
Project-URL: Documentation, https://github.com/khwarzma/kh-shield#readme
Project-URL: Repository, https://github.com/khwarzma/kh-shield.git
Project-URL: Issues, https://github.com/khwarzma/kh-shield/issues
Keywords: moderation,cpp23,nlp,arabic-nlp,audio-processing,computer-vision,pybind11
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/C%2B%2B-23-blue.svg" alt="C++23">
  <img src="https://img.shields.io/badge/Build-CMake%20%2F%20Make-brightgreen.svg" alt="Build System">
  <img src="https://img.shields.io/badge/License-Apache%202.0-orange.svg" alt="License">
  <a href="https://khwarzma.bareeed.com/ar/" target="_blank"><img src="https://img.shields.io/badge/Maintained%20by-Khwarzma-red.svg" alt="Khwarzma"></a>
</p>

# 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

```bash
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

```bash
pip install .

```

---

## Quickstart

### Python API

```python
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](ARCHITECTURE.md) — Multithreading model, stream buffering, and pipeline mechanics.
* [PRESETS_AND_RULES.md](https://www.google.com/search?q=PRESETS_AND_RULES.md) — Threshold mathematical formulas, HSV limits, and preset rules.
* [API_REFERENCE.md](https://www.google.com/search?q=API_REFERENCE.md) — Complete C++ and Python class definitions and data structures.
* [AI_INSTRUCTIONS.md](https://www.google.com/search?q=AI_INSTRUCTIONS.md) — Constraints and coding standards for AI coding assistants.
