rank_sites

Parameters schema

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "top_k": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "How many top-ranked sites to return (1-50, default 3)"
    },
    "absolute": {
      "type": "boolean",
      "description": "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 scores like risk_resilience/fiber_connectivity), not raw distances like fiber_km"
    },
    "candidates": {
      "description": "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. overall_score from analyze_site) overlay. Legacy: {id?, lat?, lng?, <metric fields>} flat objects also work. Omit if using shortlist_name"
    },
    "objectives": {
      "description": "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": {
      "type": "boolean",
      "description": "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. Works for fields with a maintained baseline (analyze_site metrics: overall_score, risk_resilience, fiber_connectivity, power_infrastructure, market_conditions, gas_pipeline_access, fiber_km, power_cost); other fields fall back to absolute (listed in unbaselined_fields). Takes precedence over absolute"
    },
    "constraints": {
      "description": "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": {
      "type": "string",
      "description": "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": {
      "type": "boolean",
      "description": "true = DROP any candidate missing one or more of your (validated) objectives — dropped candidates are DECLARED in excluded_incomplete, never silent. Default false keeps incomplete candidates ranked on their carried objectives with missing_objectives flagged. Recommended true for autonomous take-rank-1 workflows (an incomplete candidate can otherwise top the ranking on its single best metric)."
    }
  }
}

No endpoints wrapped at confidence ≥ 0.70.

Parent server