Estimate the freshwater consumed (mL) by one LLM call.

Provide real token counts when known; otherwise pass prompt text (tokens are approximated and output defaults to a typical 500 tokens). reasoning_effort ("none"|"low"|"medium"|"high") models thinking tokens when actual usage is unknown. provider ("aws"|"azure"|"gcp"|"average") and region ("world"|"us"|"eu"|"france"|"nordics"|"asia"|"renewable") override the hosting profile. Set include_embodied=false for operational water only. Returns water/energy breakdowns as {low, mid, high} ranges plus a human summary and the assumptions made.

Estimate water (mL) from a real API usage object — the accurate path.

usage accepts OpenAI Chat Completions shape (prompt_tokens / completion_tokens, with completion_tokens_details.reasoning_tokens and prompt_tokens_details.cached_tokens), OpenAI Responses shape, or Anthropic Messages shape (input_tokens / output_tokens, cache_read_input_tokens, cache_creation_input_tokens). Reasoning and cached tokens are handled without double counting.

Rank candidate models by mid-scenario water use for a workload.

Returns models sorted least- to most-thirsty, each with its tier and water range in mL. min_tier ("nano"|"small"|"medium"|"large"| "frontier") filters out models below a capability floor.

Pick the least-thirsty candidate model that meets a capability floor.

Use in agent graphs to route each step: set min_tier to the minimum capability the step needs, and the tool returns the lowest-water model among the candidates plus what it saves vs. the thirstiest candidate.

List models soif recognises, with their size tier and default hosting.

Unknown models still work everywhere (they fall back to the "large" tier with an explicit assumption), but known models get calibrated tier/provider/region defaults.