Metadata-Version: 2.4
Name: gshield-pic-sdk
Version: 0.1.0
Summary: Unified SDK for Face detection, Faiss vector match, and Triton gRPC inference
Author-email: Gentel <jiaweiye@gentel.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/your-repo
Project-URL: Repository, https://github.com/your-org/your-repo
Project-URL: Documentation, https://github.com/your-org/your-repo#readme
Keywords: face-detection,faiss,triton,inference,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: opencv-python-headless>=4.5.0
Requires-Dist: tritonclient[grpc]>=2.30.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Dynamic: license-file

# GshieldPicSDK

统一调用 **Face 检测**、**Faiss 向量匹配**、**Triton gRPC 推理** 的 Python SDK。所有服务地址由用户提供，SDK 内不写死默认 URL。

## 安装

**从 PyPI 安装（发布后）：**

```bash
pip install gshield-pic-sdk
```

**从本地源码安装（开发或未发布时）：**

```bash
pip install -e api_server/GshieldPicSDK
```

依赖：`requests`, `numpy`, `Pillow`, `opencv-python-headless`, `tritonclient[grpc]`。

**发布到 PyPI**：参见 [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md)。

## 配置说明

- **所有 URL 由用户提供**：`face_base_url`、`faiss_base_url`、`triton_url` 仅通过构造函数传入，或通过环境变量 `GSHIELD_FACE_URL`、`GSHIELD_FAISS_URL`、`GSHIELD_TRITON_URL` 指定；构造函数参数优先。
- **gRPC 标签目录**：调用 Triton 推理时必须提供 `label_dir`（存放各模型对应的 `.txt` 标签文件），也可通过环境变量 `GSHIELD_LABEL_DIR` 指定。
- **mode 快速配置**：gRPC 支持的模型列表（mode）、标签文件映射、精度配置集中在 `gshield_pic_sdk.grpc_config` 中；新增/修改 mode 时只需改该模块或通过 `get_grpc_config(custom_label_map=..., custom_data_types=..., custom_modes_list=...)` 覆盖。

## 使用示例

```python
from gshield_pic_sdk import GshieldPicClient

# 按需传入各服务地址与标签目录（无默认写死地址）
client = GshieldPicClient(
    face_base_url="http://localhost:8001",
    faiss_base_url="http://localhost:8000",
    triton_url="localhost:8501",
    label_dir="/path/to/model_inference/labels",
)

# 图片支持：文件路径(str)、bytes、numpy ndarray (BGR/RGB 均可，SDK 内部统一处理)
image_path = "/path/to/photo.jpg"

# 人脸检测
resp = client.face.detect(image_path)
print(resp["faces"], resp["count"])

# Faiss 向量匹配
match_result = client.faiss.match(image_path)
print(match_result["allowed"], match_result["in_blacklist"], match_result["in_whitelist"])

# 黑名单/白名单 增删
# client.faiss.blacklist_add(image_path, description="样例")
# client.faiss.whitelist_add(image_path, description="允许")

# Triton 单模型推理
label = client.grpc.infer("fire", image_path)
print(label)

# 全量 mode 推理
all_labels = client.grpc.infer_all(image_path)
print(all_labels)
```

仅使用部分能力时，只传对应 URL 即可；未配置的客户端在访问时会抛出 `GshieldValueError`（如 `face_base_url not configured`）。

## 图片输入

- 支持 **str**（文件路径）、**bytes**、**numpy ndarray**（HWC，BGR 或 RGB 均可，SDK 内部会统一为 Triton 所需格式）。

## 异常

- `GshieldConnectionError`：网络或服务连接失败（HTTP 4xx/5xx、Triton 不可用等）。
- `GshieldValueError`：参数错误（未配置 URL、mode 不存在、图片格式无效等）。
- `GshieldInferError`：推理过程失败。

## gRPC mode 列表与配置

与现有 `client_test_grpc` 行为一致，支持的 mode 包括：fire, politics, qrcode, prohibitlogo, chinamap, discomfort, discomfort_excrement, gamble, tattoo, tiananmen, trypophobia, blood, military, flag_detect, flag_classification, porn_classification, nsfw, emblem, religion_symbol, religion_activity, religion_clothes, media1, media2, porn, flag 等。完整列表与标签/精度配置见 `gshield_pic_sdk.grpc_config`；后续更新 mode 只需改该处或通过 `get_grpc_config(custom_*)` 覆盖。
