|
1 | | -# Guard Python Client |
| 1 | +<div align="center"> |
| 2 | + <h1> |
| 3 | + <img src="./docs/assets/guard.svg" width="100" alt="Guard Logo"><br> |
| 4 | + Guard |
| 5 | + </h1> |
| 6 | + <p><em>A seamless Python client for integrating visual safety filters into your applications</em></p> |
| 7 | + <p> |
| 8 | + <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a> |
| 9 | + <a href="https://github.com/elhio/guard-python/fork"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a> |
| 10 | + </p> |
| 11 | +</div> |
| 12 | + |
| 13 | +## Features |
| 14 | + |
| 15 | +**☁️ Robust Cloud API:** Seamlessly connects to Elhio Guard's powerful cloud infrastructure for high-accuracy, |
| 16 | +multi-layered visual safety filtering. |
| 17 | + |
| 18 | +**🔌 Optional Local Engine:** Add the `[local]` extension to instantly route local file checks to an on-device, |
| 19 | +zero-latency ONNX engine—without changing your code. |
| 20 | + |
| 21 | +**⚡ Sync & Async Support:** Natively supports both synchronous operations and `async/await` out of the box, making it |
| 22 | +perfect for high-performance frameworks like FastAPI. |
| 23 | + |
| 24 | +**🛠️ Unified Data Structures:** Whether a request is processed in the cloud API or locally on your hardware, the client |
| 25 | +returns the exact same strictly typed models. |
| 26 | + |
| 27 | + |
| 28 | +## Installation |
| 29 | + |
| 30 | +You can install the client in two ways, depending on whether you want to rely purely on the cloud API or include the |
| 31 | +offline fallback engine. |
| 32 | + |
| 33 | +### Cloud-Only (Standard) |
| 34 | + |
| 35 | +Installs the lightweight client. All media detection is routed to the Elhio Cloud API. This version is entirely Apache |
| 36 | +2.0 licensed. |
| 37 | + |
| 38 | +```bash |
| 39 | +pip install guard-client |
| 40 | +``` |
| 41 | + |
| 42 | +### Cloud + Local (Hybrid) |
| 43 | + |
| 44 | +Installs the client along with the `guard-local-detector` engine. This allows you to process local file paths directly on |
| 45 | +your hardware with zero network latency. |
| 46 | +*Note: The local engine dependency is licensed under the AGPL-3.0.* |
| 47 | + |
| 48 | +```bash |
| 49 | +pip install "guard-client[local]" |
| 50 | +``` |
| 51 | + |
| 52 | +## Quick Start |
| 53 | + |
| 54 | +### Cloud Detection |
| 55 | + |
| 56 | +If you installed via `guard-client[local]`, you do not need to import this package directly. The main client will |
| 57 | +automatically detect its presence and route local file checks to this engine. |
| 58 | + |
| 59 | +```python |
| 60 | +from guard_client import GuardClient |
| 61 | + |
| 62 | +client = GuardClient(api_key="your_api_key_here") |
| 63 | + |
| 64 | +# automatically routed to the Elhio Cloud API |
| 65 | +result = client.check_media(url="https://example.com/video.mp4") |
| 66 | + |
| 67 | +print(f"Detection Results: {result}") |
| 68 | +``` |
| 69 | + |
| 70 | +### Local Detection |
| 71 | + |
| 72 | +If you completed the `guard-client[local]` installation, you can also check images with the local on-device engine. It |
| 73 | +returns the exact same data structure as the cloud API, making local testing and air-gapped deployments seamless. |
| 74 | + |
| 75 | +```python |
| 76 | +from guard_client import GuardClient |
| 77 | + |
| 78 | +client = GuardClient() |
| 79 | + |
| 80 | +# automatically routed to local detection engine |
| 81 | +result = client.check_media(file_path="/local/paths/to/video.mp4") |
| 82 | + |
| 83 | +print(f"Detection Results: {result}") |
| 84 | +``` |
| 85 | + |
| 86 | +## Development |
| 87 | + |
| 88 | +This project uses [uv](https://docs.astral.sh/uv/) for lightning-fast Python package and environment management. |
| 89 | + |
| 90 | +### Prerequisites |
| 91 | + |
| 92 | +* [uv](https://docs.astral.sh/uv/) (already installed on your system) |
| 93 | + |
| 94 | +### Setup |
| 95 | + |
| 96 | +1. Clone the repository: |
| 97 | + ```bash |
| 98 | + git clone https://github.com/elhio/guard-python.git |
| 99 | + cd guard-local-python |
| 100 | + ``` |
| 101 | + |
| 102 | +2. Sync the environment: |
| 103 | + ```bash |
| 104 | + uv sync |
| 105 | + ``` |
| 106 | + *This command automatically creates a `.venv` virtual environment, reads the `uv.lock` file, and installs all core* |
| 107 | + *and development dependencies exactly as they were locked.* |
| 108 | + |
| 109 | +3. Run tests: |
| 110 | + ```bash |
| 111 | + uv run pytest |
| 112 | + ``` |
| 113 | + |
| 114 | +4. Formatting and linting: |
| 115 | + ```bash |
| 116 | + uv run ruff format |
| 117 | + uv run ruff check |
| 118 | + ``` |
| 119 | + |
| 120 | +5. Build for production: |
| 121 | + ```bash |
| 122 | + uv build |
| 123 | + ``` |
| 124 | + |
| 125 | +## Contributing |
| 126 | + |
| 127 | +We welcome contributions! Please note that all contributors must sign our automated CLA. Read more in our |
| 128 | +[Contributing Guide](CONTRIBUTING.md). |
| 129 | + |
| 130 | +## License |
| 131 | + |
| 132 | +This repository and its corresponding PyPI package are licensed under the Apache v2.0 (Apache-2.0) - see the |
| 133 | +[LICENSE](LICENSE) file for details. |
| 134 | + |
0 commit comments