Metadata-Version: 2.4
Name: khshield
Version: 1.0.1
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

### khshield 🛡️

<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/Python-3.10%20%7C%203.11%20%7C%203.12-blue.svg" alt="Python Support">
  <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-MIT-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>

**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)

```bash
pip install khshield

```

### Build Native C++ Library from Source

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

```

---

## Quickstart (Python API)

### 1. Multi-Dialect Text Moderation

```python
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)

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

```python
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](ARCHITECTURE.md) — Pipeline mechanics, multithreading model, and memory buffers.
* [PRESETS_AND_RULES.md](https://www.google.com/search?q=PRESETS_AND_RULES.md) — Mathematical formulas, HSV boundaries, and preset configurations.
* [API_REFERENCE.md](https://www.google.com/search?q=API_REFERENCE.md) — Complete C++ and Python API specification.
* [AI_INSTRUCTIONS.md](https://www.google.com/search?q=AI_INSTRUCTIONS.md) — Architectural guardrails and coding standards for AI assistants.

---

## License

Distributed under the [MIT License](https://www.google.com/search?q=LICENSE). Developed and Maintained by **Khwarzma**.
