mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-outreach-vaultmainPrivate on GitHub, published here in full

partner-thresholds.md

Markdown9.4 KB176 lines

07-Automation/partner-thresholds.md

  1. ---
  2. type: automation-config
  3. scope: 07-Automation
  4. tags: [claude, outreach, automation, config]
  5. created: 2026-07-22
  6. last_modified: 2026-08-12
  7. ---
  9. # Partner Client Thresholds: Weekly Partner Client Pipeline config
  11. This is the **single source of truth** for how the weekly pipeline decides who is a
  12. partner client and at what tier. Edit it in VS Code and re-upload. The driver
  13. (`weekly_partner_pipeline.py`) parses the first ` ```yaml ` block below. Everything
  14. outside that block is notes for you, not read by the code.
  16. > **The arming switch.** Any `TBD` in the active mode, or in `min_orders_to_qualify`,
  17. > leaves the pipeline read-only: classify still exports a spreadsheet, but the stub, XML
  18. > and workbook writes refuse to run. `min_orders_to_qualify` was the last `TBD`; setting
  19. > it was step 3 of the [[Activation-Runbook]].
  21. ## Config
  23. ```yaml
  24. # ─── classification ────────────────────────────────────────────────────────────
  25. # mode: how a customer is turned into a partner client tier.
  26. # ltv_bands -> assign a tier by lifetime spend falling inside a band (default;
  27. # mirrors the Partner Program)
  28. # multi_factor -> score several signals, then band the score
  29. # simple_gate -> single cutoff, partner client vs. not, no tiers
  30. mode: ltv_bands
  32. # ─── ltv_bands mode ──────────────────────────────────────────────────────────
  33. # Lower bound is inclusive, upper is exclusive. Anyone below the lowest band's
  34. # min is "Not a partner client". Dollars, no symbols/commas. Leave upper of the top
  35. # band as null for "and up".
  36. ltv_bands:
  37. - tier: "Palladium Partner"
  38. min_ltv: 2500
  39. max_ltv: 8000
  40. - tier: "Platinum Partner"
  41. min_ltv: 8000
  42. max_ltv: 25000
  43. - tier: "Iridium Partner"
  44. min_ltv: 25000
  45. max_ltv: 75000
  46. - tier: "Rhodium Partner"
  47. min_ltv: 75000
  48. max_ltv: null # and up
  50. # ─── multi_factor mode (only read when mode: multi_factor) ────────────────────
  51. # Score = sum(weight * normalized_signal). Set a partner_cutoff and per-tier
  52. # score bands. Weights and cutoffs are placeholders.
  53. multi_factor:
  54. weights:
  55. ltv: 1.0
  56. partner_cutoff: TBD # min score to count as a partner client at all
  57. score_bands: # optional; same shape as ltv_bands but on score
  58. - tier: "Palladium Partner"
  59. min_score: TBD
  60. max_score: TBD
  62. # ─── simple_gate mode (only read when mode: simple_gate) ──────────────────────
  63. simple_gate:
  64. signal: ltv # ltv | repeat_revenue | order_count
  65. min_value: 2500 # at/above this -> "Partner Client"; below -> "Not a partner client"
  67. # ─── tier overrides ──────────────────────────────────────────────────────────
  68. # Accounts whose tier is set by the RELATIONSHIP, not by per-mailbox spend.
  69. # Applied before the bands and before min_orders_to_qualify, so an override wins
  70. # outright: an overridden mailbox is that tier even at $0 lifetime spend.
  71. #
  72. # Why this exists: on 2026-08-12 Matt re-tiered the Harlow Ridge Homes mailboxes to
  73. # Rhodium by hand (Harlow Ridge is a directly-partnered builder Hazel speaks with
  74. # every other day; the tier belongs to the company, not the individual mailbox). The
  75. # rule lived only in MEMORY/DECISIONS, so the very next weekly run demoted most of
  76. # them straight back to their computed bands. Encoding it here stops that.
  77. #
  78. # SCOPE IS DELIBERATELY PER-EMAIL, NOT PER-DOMAIN. Plinth carries more harlowridge
  79. # mailboxes than the ones re-tiered, and most of the rest classify as "Not a partner
  80. # client" on spend. A domain-wide override would promote every one of them to Rhodium
  81. # and mint a stub for each, which is not what the 08-12 decision did. Adding a mailbox
  82. # here is Matt's call, never inferred from data. To go domain-wide instead, that is a
  83. # DECISIONS entry first.
  84. #
  85. # Keyed by exact lowercase email -> tier string (must match an ltv_bands tier name).
  86. tier_overrides:
  87. emails:
  88. maren.achterberg@harlowridge.example: Rhodium Partner
  89. soren.blackwood@harlowridge.example: Rhodium Partner
  90. lena.coldwell@harlowridge.example: Rhodium Partner
  91. callum.dunmore@harlowridge.example: Rhodium Partner
  93. # ─── what counts as revenue ───────────────────────────────────────────────────
  94. # amount_field: which order dollar figure feeds LTV.
  95. # grand_total -> grand total incl. shipping + tax (what the customer paid)
  96. # subtotal -> product subtotal only
  97. amount_field: grand_total
  99. # counted_order_statuses: include-list. Only these status_code values are summed.
  100. # Empty list = all statuses (minus the excluded list below).
  101. counted_order_statuses: []
  103. # excluded_order_statuses: these codes are NEVER summed, regardless of the include
  104. # list. 27 = Order Cancelled, 28 = Order Refunded. This matches how the roster
  105. # workbook counts: verified 2026-07-23 against one long-standing account, whose
  106. # workbook "Total Spent (Orders)" equals the excluding-cancelled order sum, so the
  107. # weekly delta must use the same basis or baseline+delta drifts. amount_field stays
  108. # grand_total (shipping in), also verified as the workbook's basis. PENDING NORA: if
  109. # the leadership call picks different rules (e.g. subtotal, or counting refunds),
  110. # change these two keys and note it in DECISIONS.
  111. excluded_order_statuses: [27, 28]
  113. # ─── incremental history (v2, replaces the old ltv_window pull) ──────────────
  114. # Lifetime value is computed from the LOCAL history store
  115. # (07-Automation/data/order_history.json): the roster baseline + every order
  116. # ingested since. The API is never asked for an all-time total. Plinth orders.fetch
  117. # silently truncates big result sets (~70 orders/response, verified 2026-07-22; see
  118. # DECISIONS.md). baseline as_of is set at seed time.
  120. # pull_window_days: how far back the weekly delta pull reaches. 8 = one day of
  121. # overlap with the previous Monday run; the ingest dedupe makes overlap free.
  122. pull_window_days: 8
  124. # suspect_row_count: a single pull window returning this many rows is treated as
  125. # possibly truncated. The runner keeps paging (offset + dedupe) until a page adds
  126. # zero new order refs, and/or narrows the date window.
  127. suspect_row_count: 50
  129. # repeat_revenue = spend on every order after the customer's earliest counted order.
  130. # (With a baseline: baseline repeat + all post-baseline counted orders.)
  132. # ─── reconciliation ──────────────────────────────────────────────────────────
  133. # reconcile_with_store_group: if true, also record Plinth customer_group next to our
  134. # computed tier so you can spot mismatches (store says Palladium Partner, our spend
  135. # math says something else). Does not change the decision.
  136. reconcile_with_store_group: true
  138. # ─── scope / performance ─────────────────────────────────────────────────────
  139. # page_size: Plinth page size for paginated pulls. HARD CAP 100: the API rejects
  140. # larger values (validated 2026-07-22). Plinth also caps at 10 req / 10 sec and
  141. # throttles rather than fails, so pulls just slow down.
  142. page_size: 100
  144. # min_orders_to_qualify: ignore customers with fewer than this many counted orders
  145. # (0 = keep everyone). Set with Ines: one qualifying order is enough.
  146. min_orders_to_qualify: 1
  148. # ─── run behavior ────────────────────────────────────────────────────────────
  149. # autonomy: how far an unattended (scheduled) run may go on its own.
  150. # spreadsheet_only -> pull + classify + export xlsx, then STOP
  151. # through_vault -> also create/upgrade stubs + refresh XML, hold Bitrix (current)
  152. # full -> entire chain incl. Bitrix push
  153. autonomy: through_vault # ENABLED 2026-07-23: auto stubs + XML; Bitrix / enrich / outreach-routing held
  154. ```
  156. ## Activation checklist (done 2026-07-23; kept for a rebuild)
  158. 1. **Seed the baseline** (one time). `--as-of` is the date the roster's totals run
  159. through ("LTV up until Monday", so that Monday's date). Dry-run first:
  160. ```
  161. python3 07-Automation/weekly_partner_pipeline.py seed-baseline \
  162. --sheet <path-to-roster> --as-of <monday> --dry-run
  163. ```
  164. Check the detected column mapping, fix any miss with `--map "field=Exact Header"`,
  165. then run again without `--dry-run`.
  166. 2. **Catch up the gap.** Pull orders from `as_of` to today (day-windowed, offset+dedupe
  167. until `added=0`) and `ingest` them, so the history is current before the first
  168. scheduled run.
  169. 3. **Arm it:** set `min_orders_to_qualify` (the last `TBD`, the arming switch).
  170. 4. **Dry run:** `classify` then `verify`. Eyeball the spreadsheet, especially the
  171. `has_baseline=False` rows (customers seen in the delta with no baseline row).
  172. 5. **Enable the schedule** per [[scheduled-task]].
  174. **Program bands (lifetime spend):** Palladium $2.5K to $8K · Platinum $8K to $25K ·
  175. Iridium $25K to $75K · Rhodium $75K+. "Once in the program, always in the program":
  176. lifetime, never trailing.