[AI] Delivery Agent

🔍 Problem Statement

As a publisher, I experience challenges mapping subscriber addresses to carriers/vendors, which results in unnecessary daily manual assignments, routing errors, and fulfillment delays.

💡 User Story

1. As an operations user, I want addresses to be automatically classified and assigned to the correct vendor using delivery prompts, so that vendor mapping is consistent and no longer requires daily manual effort.

2. As an admin user, I want to define delivery service areas per vendor using standard postal formats, so that assignment rules are structured and easily maintained.

🎯 Definition of Done (DoD)

✔ A new field, vendor_id, is added to the Shipping Address object:

1. Readable and writable via the Pelcro Core API

2. Editable and visible in the Address view on the platform

3. Must reference a valid existing Vendor ID

✔ Extend the Vendor object to support one Delivery Prompt per vendor:

1. Admins can create, edit, and delete a single delivery prompt per vendor

2. Prompts define service zones using standard mailing formats:

3. ZIP code ranges (e.g., 04401–04412)

4. Street address ranges (e.g., Main St 100–399)

5. City or county filters (e.g., Bangor, Penobscot County)

✔ When an address is created or updated:

1. It is evaluated against all existing Delivery Prompts across vendors by an AI agent

2. The first matching vendor (based on internal order) will be assigned as the vendor_id

3. If no match is found, vendor_id remains empty

4. If multiple matches occur, the first match will be used by default

5. Each address can be assigned to only one vendor

✔ Updating a Vendor’s Delivery Prompt does not trigger re-evaluation of existing addresses.

1. If reclassification is required, it must be done manually via Core API or bulk update tools.

✔ The following areas will reflect vendor_id:

1. List & Fulfillment Exports (for Mailable: Local Delivery lists)

2. List Builder (filter by vendor ID or blank vendor)

3. Address View – displays and allows editing of vendor_id

4. Vendor View – displays the list of matched addresses