PumaGuard
Introduction
Please visit http://pumaguard.rtfd.io/ for more information.
Get PumaGuard
GitHub Codespaces
If you do not want to install any new software on your computer you can use GitHub Codespaces, which provide a development environment in your browser.
Local Development Environment
You can set up a local development environment using either uv (recommended for speed) or poetry.
Using uv (Recommended)
uv is an extremely fast Python package installer and resolver.
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Or on Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Create a virtual environment and install dependencies:
uv venv
source .venv/bin/activate # On Linux/macOS
# or
.venv\Scripts\activate # On Windows
# Install with development dependencies
uv pip install -e ".[dev,extra-dev]"
Or use uv sync for automatic environment management:
uv sync --extra dev --extra extra-dev
Using Poetry
Alternatively, you can use poetry:
sudo apt install python3-poetry
poetry install
Running the scripts on colab.research.google.com
Google Colab offers runtimes with GPUs and TPUs, which make training a model much faster. In order to run the training script in Google Colab, do the following from the terminal:
git clone https://github.com/PEEC-Nature-Youth-Group/pumaguard.git
cd pumaguard
scripts/train.py --help
For example, if you want to train the model from row 1 in the notebook,
scripts/train.py --notebook 1
Web UI
PumaGuard includes a modern Flutter-based web interface for monitoring and configuration.
Starting the Web UI
Using uv:
uv run pumaguard-webui --host 0.0.0.0 --port 5000
Using poetry:
poetry run pumaguard-webui --host 0.0.0.0 --port 5000
The web interface will be accessible at http://your-server-ip:5000 or http://pumaguard.local:5000 (if mDNS is enabled).
mDNS/Zeroconf Support
PumaGuard supports automatic server discovery via mDNS (also known as Bonjour or Zeroconf). This allows clients to connect using a friendly hostname like pumaguard.local instead of needing to know the IP address.
Setup mDNS on the server:
-
Linux: Install Avahi
sudo apt install avahi-daemon avahi-utils sudo systemctl enable avahi-daemon sudo systemctl start avahi-daemon
-
macOS: Built-in, no setup needed
-
Windows: Install Bonjour Print Services
Using mDNS:
Once mDNS is set up, your server will be automatically discoverable at:
http://pumaguard.local:5000
You can customize the hostname:
pumaguard-webui --mdns-name my-server
# Accessible at: http://my-server.local:5000
Or disable mDNS:
pumaguard-webui --no-mdns
For detailed mDNS setup instructions including Docker/container configurations, see docs/MDNS_SETUP.md.
Running the server
The pumaguard-server watches a folder and classifies new files as they are
added to that folder.
Basic Usage
Using uv:
uv run pumaguard-server FOLDER
Using poetry:
poetry run pumaguard-server FOLDER
Where FOLDER is the folder to watch.
Common Command-Line Options
All PumaGuard commands support these global options:
--log-file PATH- Specify a custom log file location (default:~/.cache/pumaguard/pumaguard.log)--settings PATH- Load settings from a specific YAML file (default:~/.config/pumaguard/settings.yaml)--debug- Enable debug logging--model-path PATH- Specify where models are stored--version- Show version information
Examples:
# Use custom log file location
uv run pumaguard --log-file /var/log/pumaguard.log server FOLDER
# Combine custom settings and log file
uv run pumaguard --settings my-config.yaml --log-file /tmp/debug.log server FOLDER
# Enable debug logging
uv run pumaguard --debug server FOLDER
For more details on configuration and XDG directory support, see docs/XDG_MIGRATION.md.
Training new models
For reproducibility, training new models should be done via the train script and all necessary data, i.e. images, and the resulting weights and history should be committed to the repository.
-
Get a TPU instance on Colab or run the script on your local machine.
-
Open a terminal and run
git clone https://github.com/PEEC-Nature-Youth-Group/pumaguard.git cd pumaguard
-
Get help on how to use the script
On Colab, run
./scripts/pumaguard --help ./scripts/pumaguard train --help
On your local machine with uv:
sudo apt install nvidia-cudnn uv sync --extra dev --extra extra-dev uv run pumaguard --help uv run pumaguard train --help
Or with poetry:
sudo apt install nvidia-cudnn poetry install poetry run pumaguard --help poetry run pumaguard train --help
-
Train the model from scratch
./scripts/pumaguard train --no-load --settings pumaguard-models/model_settings_6_pre-trained_512_512.yaml
1 maintainer
Metadata
1 maintainer
Release files for pumaguard 20.post230
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pumaguard-20.post230.tar.gz | 59.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pumaguard-20.post230-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 84.1 MB
Release files / pumaguard-20.post230.tar.gz
| Download URL | pumaguard-20.post230.tar.gz |
|---|---|
| Size | 59.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9546d07013aea8b2ba6ea5ec44e19488b2761b3b6bbb80c6c755ac80407a5b0e
|
|
BLAKE2b-256 checksum How to use checksums |
2e8b6d306e9a12455acb345f2f1720425a9d22e9751078a1fa6f5518aa400ed1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 10, 2025.
Transparency logRelease files / pumaguard-20.post230-py3-none-any.whl
| Download URL | pumaguard-20.post230-py3-none-any.whl |
|---|---|
| Size | 25.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d6b1b9d25af2308936d5253cd6527c760e70c741098af9d274361dc2bf25e7c
|
|
BLAKE2b-256 checksum How to use checksums |
aa5f85af3a8d97d795a911905d8b797a1bbdbc5d448e9a971fe8ffab95bae1d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 10, 2025.
Transparency log
