adaptive-pricing/docs/CustomerTuningSolver.md

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.