# 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.