brybox

A personal automation toolkit for PC organization. Brybox replaces a pile of one-off scripts with a single, cohesive library that sorts PDFs, normalizes photo and video libraries, triages an email inbox, and pulls documents out of web portals that don't offer a real API — all driven by config files instead of hardcoded paths.

It is not a general-purpose framework: several subsystems are wired to specific, personal accounts (a Gmail inbox, a handful of German insurance / banking / utility portals, Amazon.de). Treat it as a working example of the architecture as much as a tool to run as-is.

What it does

Every file-mutating operation across these subsystems publishes to an internal event bus; DirectoryVerifier subscribes to it and can diff the events a batch job claimed to perform against what's actually on disk — useful for confirming a pipeline run did what it said it did.

Requirements

• Python 3.12+
• uv for dependency management
• System binaries on PATH: exiftool, ImageMagick, ffmpeg
• Playwright's Chromium build (not installed by uv sync — see below)

Installation

git clone https://github.com/bryanbarcelona/brybox.git
cd brybox
uv sync
uv run playwright install chromium

Configuration

Brybox is entirely config- and env-var-driven; nothing is hardcoded to a path or account.

Config files — copy each template under configs/ and drop the .example, then fill in real values:

Files are resolved in priority order: an explicit path, then the OS user config directory (platformdirs.user_config_dir('brybox')), then ./configs relative to the working directory. A single logical config can be split across multiple files/formats (e.g. both .json and .csv) — the loader merges them and the most recently modified source wins on conflicts.

Environment variables — create a .env file (loaded via python-dotenv):

# Gmail IMAP (InboxKraken) — required, needs a Google App Password
EMAIL=
APP_PWD=
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993

# web_marionette portal logins — only required for the scrapers you use
USER_MAIN=
TECHEM_PWD=
USER_KFW=
KFW_PWD=
USER_GOTHAER=
GOTHAER_PWD=
USER_AMAZON=
AMAZON_PWD=
AMAZON_TOTP_SECRET=

Usage

Everything is re-exported from the package root:

from brybox import push_photos, push_videos, SnapJedi, Doctopus, InboxKraken

# Ingest a camera-roll dump: stage, dedup, normalize
push_photos('D:/Camera Uploads', 'D:/Photos')
push_videos('D:/Camera Uploads', 'D:/Videos')

# Sort a single PDF into its category folder
DoctopusPrime('D:/Downloads/invoice.pdf').process()

# Triage the inbox without touching anything (dry_run is the default)
with InboxKraken() as kraken:
    kraken.preview()

Batch variants follow a <Thing>Nexus naming pattern (AudioraNexus, DoctopusPrimeNexus, ZipWardenNexus, ...) — same processing logic, applied to every file in a directory, with per-file error isolation so one bad file doesn't abort the run.

Development

uv sync --all-extras --dev
uv run ruff check .
uv run ruff format .
uv run ty check
uv run pytest

Commits follow Conventional Commits; commitizen derives the version bump and changelog entry from commit messages, and releases to PyPI are cut automatically from main via GitHub Actions.