Implement customer-tuning solver and close WP-0006

docs/CustomerTuningSolver.md

@@ -0,0 +1,93 @@
+# 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.