package staffing import ( "os" "strconv" "time" "github.com/shopspring/decimal" ) // Config holds the W3 tunables. Every value is a GLOBAL platform default (see Load, which reads optional // MM_W3_* environment variables). The staffing floor and the adjacency threshold may ADDITIONALLY be // overridden per run through the request body, and the values actually used are recorded in // recommendation_runs.parameters so a run is reproducible and auditable. Per org configuration is a future // addition; v1 is global defaults plus per run override of the floor and the adjacency threshold. type Config struct { // StaffingFloor is the minimum engine total a candidate must reach to be qualified for assignment. // Default 75, the Yellow band floor. A candidate below the floor is never an assign or reassign; the // optimizer and the classifier only ever arbitrate among candidates the engine already qualified. StaffingFloor decimal.Decimal // AdjacencyThreshold is the maximum cosine distance for a held skill to count as adjacent to a missing // required skill (the reskill path). Default 0.40 (roughly cosine similarity 0.60). AdjacencyThreshold decimal.Decimal // Confidence is a deterministic transparency aid in [0,1], a weighted blend of fit, clearance // provenance, and profile completeness. The three weights sum to 1. ConfidenceFitWeight decimal.Decimal // default 0.60 ConfidenceProvenanceWeight decimal.Decimal // default 0.25 ConfidenceCompletenessWeight decimal.Decimal // default 0.15 // Value function. The optimizer objective is an int64 so the solve is integer exact and FIPS clean. ValueScalePrecision int64 // fixed integer scale applied to the real valued objective; default 1_000_000 ValueReference decimal.Decimal // the opportunity dollar value that maps to the midpoint priority; default 5_000_000 PriorityMin decimal.Decimal // minimum priority multiplier; default 1 PriorityMax decimal.Decimal // maximum priority multiplier; default 3 // Optimizer envelope (denial of service guard on our own API): a portfolio solve that exceeds either // bound is refused with a typed error, never run unbounded. MaxProblemEdges int // max candidate by requirement edges; default 250_000 MaxProblemNodes int // max graph nodes; default 5_000 SolveBudget time.Duration // per solve wall clock budget enforced by a context deadline; default 5s // ProactiveBestFitLimit caps the best fit opportunities returned per candidate in the proactive view. ProactiveBestFitLimit int // default 5 // ReadPageMax caps a single page of recommendation reads. ReadPageMax int // default 200 } // DefaultConfig returns the documented global defaults. func DefaultConfig() Config { return Config{ StaffingFloor: decimal.NewFromInt(75), AdjacencyThreshold: decimal.RequireFromString("0.40"), ConfidenceFitWeight: decimal.RequireFromString("0.60"), ConfidenceProvenanceWeight: decimal.RequireFromString("0.25"), ConfidenceCompletenessWeight: decimal.RequireFromString("0.15"), ValueScalePrecision: 1_000_000, ValueReference: decimal.NewFromInt(5_000_000), PriorityMin: decimal.NewFromInt(1), PriorityMax: decimal.NewFromInt(3), MaxProblemEdges: 250_000, MaxProblemNodes: 5_000, SolveBudget: 5 * time.Second, ProactiveBestFitLimit: 5, ReadPageMax: 200, } } // Load returns DefaultConfig with any MM_W3_* overrides applied. Unset or unparseable variables keep the // default, so a misconfigured env never silently disables a guard. func Load() Config { c := DefaultConfig() if v := envDecimal("MM_W3_STAFFING_FLOOR"); v != nil { c.StaffingFloor = *v } if v := envDecimal("MM_W3_ADJACENCY_THRESHOLD"); v != nil { c.AdjacencyThreshold = *v } if v := envDecimal("MM_W3_VALUE_REFERENCE"); v != nil && v.GreaterThan(decimal.Zero) { c.ValueReference = *v } if n := envInt("MM_W3_MAX_PROBLEM_EDGES"); n > 0 { c.MaxProblemEdges = n } if n := envInt("MM_W3_MAX_PROBLEM_NODES"); n > 0 { c.MaxProblemNodes = n } if n := envInt("MM_W3_SOLVE_BUDGET_MS"); n > 0 { c.SolveBudget = time.Duration(n) * time.Millisecond } return c } // WithOverrides returns a copy of the config with a per run staffing floor and adjacency threshold // applied when supplied (non nil). The caller validates the ranges before calling. func (c Config) WithOverrides(floor, adjacency *decimal.Decimal) Config { if floor != nil { c.StaffingFloor = *floor } if adjacency != nil { c.AdjacencyThreshold = *adjacency } return c } func envDecimal(key string) *decimal.Decimal { s := os.Getenv(key) if s == "" { return nil } d, err := decimal.NewFromString(s) if err != nil { return nil } return &d } func envInt(key string) int { s := os.Getenv(key) if s == "" { return 0 } n, err := strconv.Atoi(s) if err != nil { return 0 } return n }