Python Background Processing

Jump to bottom

Akshay B edited this page Mar 16, 2026 · 2 revisions

Python Background Processing (Azure Functions)

This document details background queue/timer processing in PluckIt.Processor.

Documentation metadata

Audience: external contributors
Last reviewed: 2026-03-16
Scope: queue and timer contracts only

Queue and timer triggers

Queue: `ProcessTasteAnalysisJob`

Trigger: queue name from TASTE_JOB_QUEUE_NAME (default taste-analysis-jobs)
Runs async profile-analysis workflow for positive feedback signals.
Output is used to continuously refine taste-profile and recommendation quality.

Queue: `ProcessTasteAnalysisJobDlq`

Trigger: queue name from TASTE_JOB_DEAD_LETTER_QUEUE_NAME (default taste-analysis-jobs-poison)
Persists dead-letter payloads for failed taste-analysis jobs.
DLQ entries preserve failed payloads for replay and forensics.

Timer: `PluckItWeeklyDigest`

Schedule: 0 0 9 * * 1 (Monday 09:00 UTC)
Produces digest artifacts on a weekly cadence.

Timer: `PluckItMoodProcessor`

Schedule: 0 0 6 * * * (daily 06:00 UTC)
Computes/refreshes mood-related background artifacts used by taste analytics.

Timer: `PluckItScraper`

Schedule: 0 0 7 * * * (daily 07:00 UTC)
Kicks scraper automation after overnight collection windows.

Feature domain behavior

ProcessTasteAnalysisJob drives feedback-to-taste-profile background workflows.
Timer jobs emit expected periodic outputs for digest, mood analysis, and scraper operations.

Operational notes: queue and timer failure behavior

Failure mode → expected outcome → retry/alert:
- ProcessTasteAnalysisJob processing exception:
  - Expected outcome: message is retried with backoff according to TASTE_JOB_* retry settings; after retry budget exhaustion it is moved to dead-letter (taste-analysis-jobs-poison).
  - Retry/alert: inspect DLQ for payloads, re-enqueue after remediation, and alert on rising DLQ ingress ratio over configured baseline.
- Poison queue message decode/store issue:
  - Expected outcome: payload remains in dead-letter queue even if not immediately consumable.
  - Retry/alert: page an on-call and route to replay tooling with payload validation and dependency checks before purge/retry.
- PluckItWeeklyDigest timer miss or dependency failure:
  - Expected outcome: scheduled digest may not be produced for that window; next successful run does not auto-backfill missed Monday run.
  - Retry/alert: add alert on missed Monday 09:00 UTC execution, then manual run via endpoint or deployment-specific trigger restart after dependency recovery.
- PluckItMoodProcessor / PluckItScraper timer failures:
  - Expected outcome: daily job output is delayed until next timer cycle.
  - Retry/alert: monitor per-timer success latency and alert if no successful run in 36+ hours; include queue/process status in incident notes.
- High duplicate enqueuing from upstream signals:
- Expected outcome: duplicate taste-analysis jobs may accumulate in queue/dequeuing pipeline.
- Retry/alert: enforce dedupe/configured TTL (TASTE_JOB_DEDUPE_TTL_SECONDS) and escalate if queue age or age > 24h grows continuously.

Issue update log

2026-03-16: Implemented issue #65 in agents.mood_processor so mood persistence no longer blocks the async loop. PluckIt/PluckIt.Processor now uses the async Cosmos container path and async upsert_item calls, with focused tests for async query/upsert behavior.
2026-03-16: Implemented issue #58 in agents.mood_processor to batch canonicalized mood re-embeddings through a single embed_documents call, with fallback handling for embedding failures and count mismatches plus tests covering batch behavior.