generated from coulomb/repo-seed
94 lines
2.7 KiB
Markdown
94 lines
2.7 KiB
Markdown
# Customer-Tuning Solver Prototype
|
||
|
||
Status: MVP for `ADAPTIVE-WP-0006`.
|
||
|
||
## Purpose
|
||
|
||
This milestone adds the first executable customer-tuning flow described in
|
||
`INTENT.md`.
|
||
|
||
The solver now accepts selected customer-tunable inputs, solves the remaining
|
||
usage-price parameter, validates the tuned configuration against boundary
|
||
constraints, and checks seller-side comparable-customer LTV against the best
|
||
available predefined reference model.
|
||
|
||
## Generic Solver Contract
|
||
|
||
Core module: `adaptive_pricing_core/customer_tuning.py`
|
||
|
||
Inputs:
|
||
|
||
- a baseline `PricingConfiguration`
|
||
- the comparable-customer profile
|
||
- boundary policy
|
||
- LTV policy
|
||
- a `CustomerTuningRequest`
|
||
- the set of predefined reference configurations available to that profile
|
||
|
||
Current request fields:
|
||
|
||
- `included_units`
|
||
- `contract_duration_months`
|
||
- `minimum_monthly_turnover`
|
||
- `prepaid_amount`
|
||
- `guaranteed_platform_fee`
|
||
- `customer_funded_onboarding`
|
||
- `reduced_cancellation_flexibility`
|
||
- preference: `lower_usage_price` or `seller_ltv`
|
||
- approval mode: `self_serve_only` or `allow_approval`
|
||
|
||
Current solved field:
|
||
|
||
- `usage_unit_price`
|
||
|
||
## Decision Logic
|
||
|
||
For each candidate usage price in the search range, the solver:
|
||
|
||
1. builds a tuned `PricingConfiguration`
|
||
2. runs boundary validation
|
||
3. estimates `average_comparable_customer_lifetime_value`
|
||
4. compares the tuned result with the best predefined reference model for the
|
||
profile
|
||
|
||
A tuned configuration is only accepted when:
|
||
|
||
- boundary validation is valid
|
||
- no seller approval is required when the request is `self_serve_only`
|
||
- tuned comparable-customer LTV meets the configured improvement threshold
|
||
|
||
The solver returns structured output including:
|
||
|
||
- accepted / rejected / requires approval decision
|
||
- solved configuration
|
||
- reference model and required LTV threshold
|
||
- binding constraints
|
||
- chosen trade-offs
|
||
- explanation text
|
||
|
||
## Coulomb Pilot
|
||
|
||
Pilot module: `projects/coulomb-pricing/observatory/tuning.py`
|
||
|
||
Pilot request catalog:
|
||
|
||
- `projects/coulomb-pricing/data/tuning_requests.json`
|
||
|
||
The Coulomb pilot currently targets `membership-plus-overage` against the
|
||
`small-team` comparable-customer profile.
|
||
|
||
Two pilot requests are shipped:
|
||
|
||
- a seller-safe lower-usage-price request that succeeds
|
||
- a high-included-usage request that is rejected for self-serve
|
||
|
||
## Current Modeling Note
|
||
|
||
The observatory simulation path still scales default hybrid included usage by
|
||
`members_per_customer`.
|
||
|
||
The tuning pilot interprets request-level `included_tokens` values as total
|
||
package allowances, then maps them into canonical configuration fields before
|
||
running the solver. This keeps the prototype aligned with the catalog’s tunable
|
||
bounds while avoiding a broader simulation recalibration inside this milestone.
|