Rank Sites
rank_sitesRank enriched candidate data center sites under hard constraints and signed weighted objectives, returning top N sites with normalized scores and objective ranks.
Instructions
Use this when you have enriched candidate data center sites to rank under constraints — the normalization contract that lets you compare sites across separate analyze_site calls WITHOUT dropping into code. Pass candidates you already enriched (each an object with lat/lng + metric fields like risk_resilience, water_stress, fiber_km — pull these from analyze_site + get_refined_queue and pass site_evaluation_handoff through untouched), hard constraints, and weighted objectives; get back entity=ranked_sites: top_k ranked with rank, objective_score, per-field normalized{} (0-100 relative to the set), and normalization_basis. objectives use SIGNED weights: +weight maximizes a field (e.g. risk_resilience:1), -weight minimizes it (e.g. water_stress:-0.6, fiber_km:-0.4). constraints are hard filters, fail-closed on a missing field. Use for "pick the best N sites under constraints"; for one site use analyze_site; to get the candidate set first use get_refined_queue. CANDIDATE CONTRACT: candidates may be {candidate_id: "cand…"} entries from get_refined_queue — frozen identity (lat/lng/capacity_mw/fiber_km/iso) loads from the mint, your metrics overlay the rest; expired/unknown ids are dropped AND declared in candidate_contract, never re-resolved.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | How many top-ranked sites to return (1-50, default 3) | |
| absolute | No | false (default) = min-max normalize within THIS batch (best-in-set, NOT stable across runs). true = score on a FIXED 0-100 scale for CROSS-RUN-STABLE, auditable scores — use ONLY when the objective fields are already 0-100 (analyze_site… | |
| candidates | No | Array of candidate objects. PREFERRED: {candidate_id: "cand_…", <your metric fields>} using ids from get_refined_queue — frozen coordinates/capacity/fiber_km load from the mint (zero transcription drift), your enrichments (e.g. | |
| objectives | No | Weighted objectives {field: signedWeight} — +weight maximizes, -weight minimizes. e.g. {"water_stress": -0.6, "fiber_km": -0.4}. Omit with shortlist_name to reuse the shortlist's saved objectives; required with candidates | |
| percentile | No | true = score each objective as its PERCENTILE against the viable-site POPULATION ("better than X% of viable sites") — the strongest cross-run + cross-region comparability. | |
| constraints | No | Hard filters {field: {min?, max?}} — a candidate missing a constrained field is dropped (fail-closed). e.g. {"risk_resilience": {"min": 70}, "estimated_ttp_months": {"max": 34}} | |
| shortlist_name | No | Alternative to candidates: re-rank a SAVED shortlist (created via save_to_shortlist) in one shot — loads its sites (scoped to your API key) + reuses their saved objectives if you pass none, and re-scores against the current baseline | |
| require_complete | No | true = DROP any candidate missing one or more of your (validated) objectives — dropped candidates are DECLARED in excluded_incomplete, never silent. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||