Run On the Host#

Use this path when you want to run the service directly with Python on the host, typically for development.

Prerequisites#

Python Setup#

The service uses uv and Python 3.11+. From the scene-understanding-service/ directory:

uv sync

This creates a virtual environment and installs the dependencies declared in pyproject.toml.

Config#

  • Edit configs/scene-config.yaml and configs/rules.yaml. For details, see the Configuration Guide.

  • When running on the host (no /app/configs), the service automatically falls back to the configs/ directory next to the source. Set CONFIG_DIR to point elsewhere if needed.

  • Supply Scenescape credentials via environment variables:

    export SCENESCAPE_API_USER=admin
export SCENESCAPE_API_PASSWORD=...   # type secrets directly; do not commit

Running the Service#

Start#

uv run python main.py

Default bind address:

  • host: 0.0.0.0

  • port: 8082

Equivalent uvicorn command:

uv run uvicorn main:app --host 0.0.0.0 --port 8082

Verify#

curl --noproxy '*' http://127.0.0.1:8082/health
curl --noproxy '*' http://127.0.0.1:8082/api/v1/sus/status

Running Tests#

uv run pytest tests/ -v

API Use Cases and Examples#

For endpoint details and examples, see the API Reference.

Notes#

  • The service performs Scenescape zone discovery at startup and then subscribes to the configured MQTT topics.

  • There is no hard startup dependency on Scenescape — the MQTT connection is retried in the background.

  • Behavioral analysis and evidence capture require the optional seaweedfs block and a reachable behavioral-analysis worker; otherwise leave them out.