Metadata-Version: 2.4
Name: pumaguard
Version: 24
Author-email: Nicolas Bock <nicolasbock@gmail.com>
Project-URL: Homepage, http://pumaguard.rtfd.io/
Project-URL: Repository, https://github.com/PEEC-Nature-Youth-Group/pumaguard
Requires-Python: <4.0,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask~=3.1
Requires-Dist: flask-cors~=6.0
Requires-Dist: matplotlib~=3.10
Requires-Dist: packaging~=26.0
Requires-Dist: pillow~=12.1
Requires-Dist: pyyaml~=6.0
Requires-Dist: tensorflow-cpu<2.21,>=2.18; platform_machine != "aarch64" and platform_machine != "arm64"
Requires-Dist: tensorflow<2.21,>=2.18; platform_machine == "aarch64" or platform_machine == "arm64"
Requires-Dist: tf-keras<2.21,>=2.18
Requires-Dist: torch>=2.10
Requires-Dist: torchvision>=0.25
Requires-Dist: ultralytics~=8.3
Requires-Dist: requests~=2.32
Requires-Dist: zeroconf~=0.136
Requires-Dist: pi-heif>=1.3.0
Provides-Extra: dev
Requires-Dist: ansible-lint~=26.2; platform_system != "Windows" and extra == "dev"
Requires-Dist: ansible~=13.4; extra == "dev"
Requires-Dist: bashate~=2.1; extra == "dev"
Requires-Dist: black~=26.1; extra == "dev"
Requires-Dist: build~=1.3; extra == "dev"
Requires-Dist: esbonio~=1.0; extra == "dev"
Requires-Dist: isort~=8.0; extra == "dev"
Requires-Dist: mypy~=1.18; extra == "dev"
Requires-Dist: passlib~=1.7; extra == "dev"
Requires-Dist: pip~=26.0; extra == "dev"
Requires-Dist: pylint~=4.0; extra == "dev"
Requires-Dist: pytest-cov~=7.0; extra == "dev"
Requires-Dist: pytest~=9.0; extra == "dev"
Requires-Dist: types-Flask-Cors; extra == "dev"
Requires-Dist: types-protobuf; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: types-tensorflow; extra == "dev"
Provides-Extra: extra-dev
Requires-Dist: ipykernel~=7.2; extra == "extra-dev"
Requires-Dist: plotly~=6.0; extra == "extra-dev"
Provides-Extra: docs
Requires-Dist: cloud-sptheme; extra == "docs"
Requires-Dist: matplotlib~=3.10; extra == "docs"
Requires-Dist: pandas~=3.0; extra == "docs"
Requires-Dist: pillow~=12.1; extra == "docs"
Requires-Dist: playsound3; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-new-tab-link; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: tensorflow<2.21,>=2.18; extra == "docs"
Requires-Dist: ultralytics~=8.3; extra == "docs"
Dynamic: license-file

# PumaGuard

[![Build and Test Webpage](https://github.com/PEEC-Nature-Youth-Group/pumaguard/actions/workflows/build-webpage.yaml/badge.svg)](https://github.com/PEEC-Nature-Youth-Group/pumaguard/actions/workflows/build-webpage.yaml)

[![Test and package code](https://github.com/PEEC-Nature-Youth-Group/pumaguard/actions/workflows/test-and-package.yaml/badge.svg)](https://github.com/PEEC-Nature-Youth-Group/pumaguard/actions/workflows/test-and-package.yaml)

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/PEEC-Nature-Youth-Group/pumaguard)

[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com)

## Introduction

Please visit <http://pumaguard.rtfd.io/> for more information.

## Get PumaGuard

[![PyPI - Version](https://img.shields.io/pypi/v/pumaguard)](https://pypi.org/project/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.

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/PEEC-Nature-Youth-Group/pumaguard/)

## Local Development Environment

You can set up a local development environment using either `uv` (recommended for speed) or `poetry`.

### Using uv (Recommended)

[uv](https://github.com/astral-sh/uv) is an extremely fast Python package installer and resolver.

Install `uv`:

```console
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Or on Windows:

```console
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Create a virtual environment and install dependencies:

```console
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:

```console
uv sync --extra dev --extra extra-dev
```

### Using Poetry

Alternatively, you can use `poetry`:

```console
sudo apt install python3-poetry
poetry install
```

## Running the scripts on colab.research.google.com

[Google Colab](https://colab.research.google.com/) offers runtimes with GPUs
and TPUs, which make training a model much faster. In order to run the
[training script](scripts/train.py) in [Google
Colab](https://colab.research.google.com/), do the following from the terminal:

```console
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,

```console
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:**

```console
uv run pumaguard-webui --host 0.0.0.0 --port 5000
```

**Using poetry:**

```console
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
  ```bash
  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](https://support.apple.com/kb/DL999)

**Using mDNS:**

Once mDNS is set up, your server will be automatically discoverable at:
```
http://pumaguard.local:5000
```

You can customize the hostname:
```console
pumaguard-webui --mdns-name my-server
# Accessible at: http://my-server.local:5000
```

Or disable mDNS:
```console
pumaguard-webui --no-mdns
```

For detailed mDNS setup instructions including Docker/container configurations, see [docs/MDNS_SETUP.md](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:**

```console
uv run pumaguard-server FOLDER
```

**Using poetry:**

```console
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:**

```console
# 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](docs/XDG_MIGRATION.md).

![Server Demo Session](docs/source/_static/server-demo.gif)

## 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.

1. Get a TPU instance on Colab or run the script on your local machine.
2. Open a terminal and run

   ```console
   git clone https://github.com/PEEC-Nature-Youth-Group/pumaguard.git
   cd pumaguard
   ```

3. Get help on how to use the script

   On Colab, run

   ```console
   ./scripts/pumaguard --help
   ./scripts/pumaguard train --help
   ```

   On your local machine with uv:

   ```console
   sudo apt install nvidia-cudnn
   uv sync --extra dev --extra extra-dev
   uv run pumaguard --help
   uv run pumaguard train --help
   ```

   Or with poetry:

   ```console
   sudo apt install nvidia-cudnn
   poetry install
   poetry run pumaguard --help
   poetry run pumaguard train --help
   ```

4. Train the model from scratch

   ```console
   ./scripts/pumaguard train --no-load --settings pumaguard-models/model_settings_6_pre-trained_512_512.yaml
   ```
