AGENTS.md

Guidance for coding agents working on nk304 apps/worker-py. This package executes background jobs for the API and must stay synchronized with enqueue callsites.

Project Overview

apps/worker-py is an ARQ worker package using Redis, HTTPX, FastAPI-compatible settings, SQLModel dependencies, transport/security helpers, file conversion dependencies, OCR/PDF libraries, language model providers, and async task registration. It handles mail delivery, chat mentions, physical delete scheduling, ticket reminders, file conversion, HLS transcoding, assistant memory indexing, and inventory Facebook sync.

The worker is not a standalone product. Every task name, payload, internal authentication path, queue dependency, and storage assumption must match the API package.

Project Map

• worker/main.py defines the worker settings and task registration surface.
• worker/settings.py loads worker and API environment profiles and exposes runtime settings.
• worker/api_service_bridge.py coordinates internal calls back to the API service.
• worker/http.py and worker/logging.py contain reusable runtime utilities.
• worker/tasks/ contains task modules: mail delivery, chat mention, chat physical delete schedule, chat ticket reminder, file conversion, HLS, storage helpers, and inventory Facebook sync.
• tests/runtime/ covers worker settings, logging, HTTP client behavior, main registration, worker embedding settings, and internal worker authentication.
• tests/chat/, tests/mail/, tests/inventory/, and tests/assistant/ cover domain task behavior.

Setup Commands

Run from the worker package when developing tasks:

bashcd apps/worker-py
uv sync
uv run arq worker.main.WorkerSettings
uv run ruff check .
uv run pytest tests/<target>.py -q

Root helpers:

bashpnpm run dev:worker-py
pnpm run build:api

Tasks may require Redis, database, storage, media binaries, and API settings in local profiles. Use placeholders in docs and public reports rather than publishing actual endpoints or credentials.

Change Rules For Agents

• Update API enqueue callsites, worker task registration, and queue observability together when a task name or payload changes.
• Keep internal API bridge authentication behind the existing helper; do not copy raw secret handling into task modules.
• Keep file conversion and HLS assumptions explicit: storage backend, source object, output object, and media binary availability.
• Make retry behavior idempotent. Mail, file conversion, order sync, and deletion tasks must tolerate duplicate delivery or a partially completed previous run.
• Prefer narrow task modules. Cross-cutting runtime behavior belongs in worker utilities or settings.
• If a task affects user-visible state, ensure the API endpoint or service test still describes the visible state transition.

Verification

Focused checks:

bashcd apps/worker-py
uv run pytest tests/runtime/test_main.py -q
uv run pytest tests/runtime/test_internal_worker_secret.py -q
uv run pytest tests/chat/<target>.py -q
uv run pytest tests/mail/<target>.py -q
uv run pytest tests/inventory/<target>.py -q
uv run ruff check .

When a queue payload or storage path changes, also run the API tests that enqueue or inspect that task.

Security Notes

Do not log internal worker secrets, storage credentials, raw protected media URLs, signed download material, provider keys, or user file content. Use redacted identifiers and task ids in logs and docs.

PR Checklist

• Task registration and API enqueue names match.
• Retry behavior is idempotent or explicitly guarded.
• Runtime settings are loaded through the established settings module.
• Focused worker tests and related API tests cover the changed path.
• Sensitive values are never emitted in logs, fixtures, docs, or public archive material.