Image-Text-to-Text
Transformers
Safetensors
qwen3_5
clairic
cloudflare
systemone
multimodal
structured-output
information-extraction
custom-code
conversational
Instructions to use Cloudflare/clairic-flash with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Cloudflare/clairic-flash with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="Cloudflare/clairic-flash") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] pipe(text=messages)# pip install -U transformers accelerate # Load model directly from transformers import AutoProcessor, AutoModelForMultimodalLM processor = AutoProcessor.from_pretrained("Cloudflare/clairic-flash") model = AutoModelForMultimodalLM.from_pretrained("Cloudflare/clairic-flash", device_map="auto") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt", ).to(model.device) outputs = model.generate(**inputs, max_new_tokens=256) print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:])) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use Cloudflare/clairic-flash with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "Cloudflare/clairic-flash" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker
docker model run hf.co/Cloudflare/clairic-flash
- SGLang
How to use Cloudflare/clairic-flash with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "Cloudflare/clairic-flash" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "Cloudflare/clairic-flash" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Cloudflare/clairic-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image in one sentence." }, { "type": "image_url", "image_url": { "url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg" } } ] } ] }' - Docker Model Runner
How to use Cloudflare/clairic-flash with Docker Model Runner:
docker model run hf.co/Cloudflare/clairic-flash
Download clairic_runtime/clair_schema.py from Cloudflare/clairic-flash: direct link, hf CLI and curl.
- Browser
- Download file 22.4 kB
-
https://huggingface.co/Cloudflare/clairic-flash/resolve/main/clairic_runtime/clair_schema.py
- Command line
-
hf download hf://Cloudflare/clairic-flash/clairic_runtime/clair_schema.py
-
curl -L -o clair_schema.py https://huggingface.co/Cloudflare/clairic-flash/resolve/main/clairic_runtime/clair_schema.py
22.4 kB
| """Field encoding, request validation, and estimate grids for Clairic. | |
| Scalar types include text, numbers, dates, times, datetimes, and durations. | |
| Lists preserve source order. Estimates use declared numeric or date ranges; | |
| forecasts expand into bounded estimate fields for each requested step. | |
| """ | |
| from __future__ import annotations | |
| import datetime | |
| import difflib | |
| import itertools | |
| import math | |
| import re | |
| from typing import Any | |
| READ_TYPES = ("text", "number", "date", "time", "datetime", "duration") | |
| FIELD_TYPES = READ_TYPES + ("list", "estimate") | |
| LIST_ITEM_TYPES = ("text", "number", "date") | |
| DURATION_UNITS = ("seconds", "minutes", "hours", "days", "weeks", "months", "years") | |
| MAX_LIST_ITEMS = 32 | |
| MAX_DECIMALS = 6 | |
| MAX_FORECAST_HORIZON = 64 | |
| FORECAST_INTERVALS = ( | |
| "step", | |
| "minute", | |
| "hour", | |
| "day", | |
| "week", | |
| "month", | |
| "quarter", | |
| "year", | |
| ) | |
| DEFAULT_NULL_THRESHOLD = 0.5 | |
| MAX_GRID_STEPS = 1_000_000 | |
| COMMON_KEYS = ("type", "instructions", "unit") | |
| NUMBER_KEYS = ("integer", "decimals") | |
| ESTIMATE_KEYS = ("min", "max", "scale", "step") | |
| FIELD_KEYS = { | |
| "text": (*COMMON_KEYS, "null_threshold"), | |
| "number": (*COMMON_KEYS, "null_threshold", *NUMBER_KEYS), | |
| "date": (*COMMON_KEYS, "null_threshold"), | |
| "time": (*COMMON_KEYS, "null_threshold"), | |
| "datetime": (*COMMON_KEYS, "null_threshold"), | |
| "duration": (*COMMON_KEYS, "null_threshold", *NUMBER_KEYS), | |
| "list": (*COMMON_KEYS, "items", *NUMBER_KEYS), | |
| "estimate": (*COMMON_KEYS, *ESTIMATE_KEYS), | |
| "forecast": (*COMMON_KEYS, *ESTIMATE_KEYS, "horizon", "interval"), | |
| } | |
| ALL_FIELD_KEYS = tuple( | |
| dict.fromkeys(key for keys in FIELD_KEYS.values() for key in keys) | |
| ) | |
| SYSTEM_PREAMBLE = ( | |
| "Fill each field from the input with a value of its type. Text copies a span of the input. Numbers, " | |
| "dates, times, datetimes, and durations are read from the input or worked out from it. A list holds " | |
| "every matching value in input order. A field is not stated when the input does not determine it. " | |
| "Estimates predict a value inside the declared range." | |
| ) | |
| FIELD_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_.\-]{0,63}$") | |
| def format_bound(value: float) -> str: | |
| if float(value).is_integer() and abs(value) < 1e15: | |
| return str(int(value)) | |
| return f"{value:.6g}" | |
| def field_line(name: str, spec: dict[str, Any]) -> str: | |
| kind = spec["type"] | |
| unit = str(spec.get("unit") or "").strip() | |
| if kind == "estimate" and is_date_estimate(spec): | |
| head = f"estimate date, {spec['min']} to {spec['max']}" | |
| granularity = date_granularity(spec) | |
| if granularity != "day": | |
| head += f", by {granularity}" | |
| elif spec.get("step") and float(spec["step"]) != 1: | |
| head += f", step {format_bound(float(spec['step']))} days" | |
| elif kind == "estimate": | |
| head = ( | |
| f"estimate{(' ' + unit) if unit else ''}, {format_bound(spec['min'])} to " | |
| f"{format_bound(spec['max'])}, {spec.get('scale', 'linear')} scale" | |
| ) | |
| if spec.get("step"): | |
| head += f", step {format_bound(float(spec['step']))}" | |
| elif kind == "list": | |
| head = f"list of {spec['items']}{number_options(spec)}{(' (' + unit + ')') if unit else ''}" | |
| elif kind == "duration": | |
| head = f"duration in {duration_unit(spec)}{number_options(spec)}" | |
| else: | |
| head = f"{kind}{number_options(spec) if kind == 'number' else ''}{(' (' + unit + ')') if unit else ''}" | |
| instructions = " ".join(str(spec.get("instructions") or "").split()) | |
| return f"{name}: {head}." + (f" {instructions}" if instructions else "") | |
| def number_options(spec: dict[str, Any]) -> str: | |
| if spec.get("integer"): | |
| return ", integer" | |
| if spec.get("decimals") is not None: | |
| return f", {int(spec['decimals'])} decimals" | |
| return "" | |
| def duration_unit(spec: dict[str, Any]) -> str: | |
| return str(spec.get("unit") or "seconds") | |
| def allowed_decimals(spec: dict[str, Any]) -> int | None: | |
| """Decimal places a number, duration, or number-list field allows (None: any).""" | |
| if spec.get("integer"): | |
| return 0 | |
| return None if spec.get("decimals") is None else int(spec["decimals"]) | |
| def parse_time(value: Any) -> tuple[int, int, int]: | |
| """("HH:MM" or "HH:MM:SS") as (hour, minute, second); ValueError otherwise.""" | |
| if not isinstance(value, str): | |
| raise ValueError(f"time must be a string, got {value!r}") # noqa: TRY004 - callers catch ValueError | |
| parsed = datetime.time.fromisoformat(value) | |
| if parsed.microsecond or parsed.tzinfo is not None: | |
| raise ValueError(f"time {value!r} must be HH:MM or HH:MM:SS") | |
| return parsed.hour, parsed.minute, parsed.second | |
| def format_time(hour: int, minute: int, second: int) -> str: | |
| return f"{hour:02d}:{minute:02d}:{second:02d}" | |
| def parse_datetime(value: Any) -> tuple[str, tuple[int, int, int]]: | |
| """("YYYY-MM-DDTHH:MM[:SS]") as (ISO date, (hour, minute, second)); ValueError otherwise.""" | |
| if not isinstance(value, str) or "T" not in value: | |
| raise ValueError(f"datetime must be YYYY-MM-DDTHH:MM[:SS], got {value!r}") | |
| day, clock = value.split("T", 1) | |
| return datetime.date.fromisoformat(day).isoformat(), parse_time(clock) | |
| def forecast_instructions(instructions: str, step: int, interval: str) -> str: | |
| """The instructions for one step of a forecast path.""" | |
| what = " ".join(str(instructions or "").split()).rstrip(".") or "the series" | |
| unit = "step" if interval == "step" else interval | |
| return f"Forecast {what} {step} {unit}{'s' if step > 1 else ''} after the last observation." | |
| def check_field_keys(fields: dict[str, Any]) -> None: | |
| """Every field spec uses only the keys its type takes, so a misspelled option ("decimal", | |
| "interger") is an error instead of a constraint that is silently dropped.""" | |
| for name, spec in fields.items(): | |
| if not isinstance(spec, dict) or spec.get("type") not in FIELD_KEYS: | |
| continue | |
| kind = spec["type"] | |
| for key in spec: | |
| if key in FIELD_KEYS[kind]: | |
| continue | |
| if key in ALL_FIELD_KEYS: | |
| raise ValueError(f"field {name}: {kind} fields don't take {key!r}") | |
| close = difflib.get_close_matches( | |
| str(key), FIELD_KEYS[kind], n=1, cutoff=0.6 | |
| ) | |
| hint = ( | |
| f"; did you mean {close[0]!r}?" | |
| if close | |
| else f"; {kind} fields take {', '.join(FIELD_KEYS[kind])}" | |
| ) | |
| raise ValueError(f"field {name} has unknown key {key!r}{hint}") | |
| def expand_forecasts( | |
| fields: dict[str, Any], | |
| ) -> tuple[dict[str, Any], dict[str, list[str]]]: | |
| """Request fields with every ``forecast`` replaced by ``horizon`` estimate fields named | |
| ``name.1`` ... ``name.H`` (same range, scale, step, and unit), plus each forecast's step names.""" | |
| expanded: dict[str, Any] = {} | |
| groups: dict[str, list[str]] = {} | |
| for name, spec in fields.items(): | |
| if not isinstance(spec, dict) or spec.get("type") != "forecast": | |
| expanded[name] = spec | |
| continue | |
| horizon = spec.get("horizon") | |
| if ( | |
| isinstance(horizon, bool) | |
| or not isinstance(horizon, int) | |
| or not 1 <= horizon <= MAX_FORECAST_HORIZON | |
| ): | |
| raise ValueError( | |
| f"forecast {name} needs an integer horizon from 1 to {MAX_FORECAST_HORIZON}" | |
| ) | |
| interval = spec.get("interval", "step") | |
| if interval not in FORECAST_INTERVALS: | |
| raise ValueError(f"forecast {name} has an unknown interval {interval!r}") | |
| base = { | |
| key: value | |
| for key, value in spec.items() | |
| if key not in ("type", "horizon", "interval", "instructions") | |
| } | |
| if is_date_estimate({"type": "estimate", **base}): | |
| validate_date_range(name, {"type": "estimate", **base}, kind="forecast") | |
| else: | |
| validate_number_range(name, {"type": "estimate", **base}, kind="forecast") | |
| groups[name] = [] | |
| for step in range(1, horizon + 1): | |
| step_name = f"{name}.{step}" | |
| if step_name in fields or step_name in expanded: | |
| raise ValueError( | |
| f"forecast {name} step {step_name} collides with another field" | |
| ) | |
| expanded[step_name] = { | |
| "type": "estimate", | |
| **base, | |
| "instructions": forecast_instructions( | |
| spec.get("instructions", ""), step, interval | |
| ), | |
| } | |
| groups[name].append(step_name) | |
| return expanded, groups | |
| # ---------------------------------------------------------------- estimate transforms | |
| def to_unit(value: float, low: float, high: float, scale: str) -> float: | |
| return min(1.0, max(0.0, raw_unit(value, low, high, scale))) | |
| def raw_unit(value: float, low: float, high: float, scale: str) -> float: | |
| """Unit position without clamping: below 0 or above 1 when the value is outside the range (a | |
| non-positive value on a log scale is -1).""" | |
| if scale == "log": | |
| if value <= 0: | |
| return -1.0 | |
| return (math.log(value) - math.log(low)) / (math.log(high) - math.log(low)) | |
| return (value - low) / (high - low) | |
| def from_unit(position: float, low: float, high: float, scale: str) -> float: | |
| position = min(1.0, max(0.0, position)) | |
| if scale == "log": | |
| value = math.exp(math.log(low) + position * (math.log(high) - math.log(low))) | |
| else: | |
| value = low + position * (high - low) | |
| return min(high, max(low, value)) | |
| def resolution_in_unit(spec: dict[str, Any], resolution: float | None) -> float: | |
| if not resolution: | |
| return 0.0 | |
| low, high, scale = estimate_range(spec) | |
| if scale == "log": | |
| return math.log1p(resolution) / (math.log(high) - math.log(low)) | |
| return resolution / (high - low) | |
| # ---------------------------------------------------------------- date estimates | |
| def is_date_estimate(spec: dict[str, Any]) -> bool: | |
| return spec.get("type") == "estimate" and isinstance(spec.get("min"), str) | |
| def date_granularity(spec: dict[str, Any]) -> str: | |
| step = spec.get("step") | |
| return step if step in ("month", "year") else "day" | |
| def date_index(value: str, granularity: str = "day") -> float: | |
| """A date as a number on its grid: day ordinal, months since year 0, or the year.""" | |
| date = datetime.date.fromisoformat(value) | |
| if granularity == "month": | |
| return float(date.year * 12 + date.month - 1) | |
| if granularity == "year": | |
| return float(date.year) | |
| return float(date.toordinal()) | |
| def index_date(index: float, granularity: str = "day") -> str: | |
| whole = round(index) | |
| if granularity == "month": | |
| year, month = divmod(whole, 12) | |
| return datetime.date(year, month + 1, 1).isoformat() | |
| if granularity == "year": | |
| return datetime.date(whole, 1, 1).isoformat() | |
| return datetime.date.fromordinal(whole).isoformat() | |
| def estimate_range(spec: dict[str, Any]) -> tuple[float, float, str]: | |
| """Numeric bounds and scale of an estimate; date bounds become grid indexes (linear scale).""" | |
| if is_date_estimate(spec): | |
| granularity = date_granularity(spec) | |
| return ( | |
| date_index(spec["min"], granularity), | |
| date_index(spec["max"], granularity), | |
| "linear", | |
| ) | |
| return float(spec["min"]), float(spec["max"]), spec.get("scale", "linear") | |
| def estimate_step(spec: dict[str, Any]) -> float: | |
| """The grid step in the numeric space of ``estimate_range`` (0: continuous). Date estimates always | |
| have a grid: ``step`` days (default 1), or one month or year.""" | |
| if is_date_estimate(spec): | |
| return ( | |
| 1.0 if date_granularity(spec) != "day" else float(spec.get("step") or 1.0) | |
| ) | |
| return float(spec.get("step") or 0.0) | |
| def estimate_number(spec: dict[str, Any], value: Any) -> float: | |
| if is_date_estimate(spec): | |
| return date_index(str(value), date_granularity(spec)) | |
| return float(value) | |
| def estimate_value(spec: dict[str, Any], number: float) -> float | str: | |
| """An estimate output in the field's own terms: an ISO date for date estimates.""" | |
| if is_date_estimate(spec): | |
| low, high, _ = estimate_range(spec) | |
| return index_date(min(max(number, low), high), date_granularity(spec)) | |
| return number | |
| def grid_bounds(step: float, low: float, high: float) -> tuple[float, float]: | |
| """The smallest and largest multiples of ``step`` inside [low, high].""" | |
| first = math.ceil(low / step - 1e-9) * step | |
| last = math.floor(high / step + 1e-9) * step | |
| return float(f"{first:.12g}"), float(f"{last:.12g}") | |
| def snap(value: float, step: float, low: float, high: float) -> float: | |
| """Nearest grid value inside the range.""" | |
| first, last = grid_bounds(step, low, high) | |
| return float(f"{min(last, max(first, round(value / step) * step)):.12g}") | |
| def snap_quantile(value: float, step: float, low: float, high: float) -> float: | |
| """Quantile of the discrete distribution a continuous one implies when every grid value v owns | |
| [v - step/2, v + step/2): the smallest v with v + step/2 >= the continuous quantile.""" | |
| first, last = grid_bounds(step, low, high) | |
| return float( | |
| f"{min(last, max(first, math.ceil((value - step / 2) / step - 1e-9) * step)):.12g}" | |
| ) | |
| def step_interval(spec: dict[str, Any], value: float) -> tuple[float, float]: | |
| """The value-space interval a grid value owns, clipped to the declared range (``value`` in the | |
| numeric space of ``estimate_range``).""" | |
| step = estimate_step(spec) | |
| low, high, _ = estimate_range(spec) | |
| if step <= 0: | |
| return value, value | |
| return max(low, value - step / 2), min(high, value + step / 2) | |
| # ---------------------------------------------------------------- text spans | |
| def _cuts_word(text: str, start: int, end: int) -> bool: | |
| """Whether text[start:end] splits an ASCII word or number at either edge ("dock" inside "docks", | |
| "12" inside "312"). Other scripts are never treated as cut, so CJK matches are unaffected.""" | |
| def joined(left: str, right: str) -> bool: | |
| return left.isascii() and left.isalnum() and right.isascii() and right.isalnum() | |
| return (start > 0 and joined(text[start - 1], text[start])) or ( | |
| end < len(text) and joined(text[end - 1], text[end]) | |
| ) | |
| def _prefer_whole( | |
| text: str, spans: list[tuple[int, int]], limit: int | |
| ) -> list[tuple[int, int]]: | |
| whole = [span for span in spans if not _cuts_word(text, *span)] | |
| return (whole or spans)[:limit] | |
| def find_spans(text: str, value: str, limit: int = 16) -> list[tuple[int, int]]: | |
| """Character spans of ``value`` in ``text``: exact matches, else case-insensitive, else with any | |
| whitespace between words. Within each stage, matches on word boundaries are preferred; substring | |
| matches inside a longer word are kept only when there is no other match.""" | |
| value = value.strip() | |
| if not value: | |
| return [] | |
| scan = max(limit * 8, 64) | |
| spans: list[tuple[int, int]] = [] | |
| start = text.find(value) | |
| while start >= 0 and len(spans) < scan: | |
| spans.append((start, start + len(value))) | |
| start = text.find(value, start + 1) | |
| if spans: | |
| return _prefer_whole(text, spans, limit) | |
| lowered, target = text.lower(), value.lower() | |
| if len(lowered) == len(text): | |
| start = lowered.find(target) | |
| while start >= 0 and len(spans) < scan: | |
| spans.append((start, start + len(value))) | |
| start = lowered.find(target, start + 1) | |
| if spans: | |
| return _prefer_whole(text, spans, limit) | |
| pieces = value.split() | |
| if not pieces: | |
| return [] | |
| pattern = re.compile( | |
| r"\s+".join(re.escape(piece) for piece in pieces), re.IGNORECASE | |
| ) | |
| spans = [ | |
| (match.start(), match.end()) | |
| for match in itertools.islice(pattern.finditer(text), scan) | |
| ] | |
| return _prefer_whole(text, spans, limit) | |
| # ---------------------------------------------------------------- records | |
| def validate_fields(fields: Any) -> None: | |
| """A schema with any number of fields (at least one): valid names, known types, and for estimates | |
| a valid range, scale, and step. Requests are checked with this before prediction, so every output | |
| can be held to its field's type.""" | |
| if not isinstance(fields, dict) or not fields: | |
| raise ValueError("fields must declare at least one field") | |
| for name, spec in fields.items(): | |
| if not isinstance(name, str) or not FIELD_NAME.match(name): | |
| raise ValueError(f"invalid field name {name!r}") | |
| kind = spec.get("type") if isinstance(spec, dict) else None | |
| if kind not in FIELD_TYPES: | |
| raise ValueError(f"field {name} has unknown type {kind!r}") | |
| if "null_threshold" in spec: | |
| threshold = spec["null_threshold"] | |
| if kind in ("estimate", "list"): | |
| raise ValueError(f"{kind} {name} does not take null_threshold") | |
| if ( | |
| isinstance(threshold, bool) | |
| or not isinstance(threshold, (int, float)) | |
| or not 0 < threshold <= 1 | |
| ): | |
| raise ValueError(f"field {name} needs null_threshold in (0, 1]") | |
| if kind == "list" and spec.get("items") not in LIST_ITEM_TYPES: | |
| raise ValueError(f"list {name} needs items in {LIST_ITEM_TYPES}") | |
| if kind == "duration" and duration_unit(spec) not in DURATION_UNITS: | |
| raise ValueError(f"duration {name} needs a unit in {DURATION_UNITS}") | |
| numeric = kind in ("number", "duration") or ( | |
| kind == "list" and spec.get("items") == "number" | |
| ) | |
| if not numeric and ("integer" in spec or "decimals" in spec): | |
| raise ValueError( | |
| f"field {name}: integer and decimals apply to numbers and durations only" | |
| ) | |
| if "integer" in spec and not isinstance(spec["integer"], bool): | |
| raise ValueError(f"field {name}: integer must be true or false") | |
| if "decimals" in spec: | |
| decimals = spec["decimals"] | |
| if ( | |
| isinstance(decimals, bool) | |
| or not isinstance(decimals, int) | |
| or not 0 <= decimals <= MAX_DECIMALS | |
| ): | |
| raise ValueError( | |
| f"field {name}: decimals must be an integer from 0 to {MAX_DECIMALS}" | |
| ) | |
| if spec.get("integer") and decimals: | |
| raise ValueError(f"field {name}: an integer field has 0 decimals") | |
| if kind == "estimate" and is_date_estimate(spec): | |
| validate_date_range(name, spec) | |
| elif kind == "estimate": | |
| validate_number_range(name, spec) | |
| def null_threshold(spec: dict[str, Any]) -> float: | |
| """A read field answers null when p_null is at or above this (default 0.5).""" | |
| return float(spec.get("null_threshold", DEFAULT_NULL_THRESHOLD)) | |
| def _number(value: Any) -> float: | |
| if isinstance(value, bool) or not isinstance(value, (int, float)): | |
| raise TypeError(value) | |
| return float(value) | |
| def validate_number_range( | |
| name: str, spec: dict[str, Any], kind: str = "estimate" | |
| ) -> None: | |
| try: | |
| low, high = _number(spec["min"]), _number(spec["max"]) | |
| except (KeyError, TypeError) as error: | |
| raise ValueError(f"{kind} {name} needs numeric min and max") from error | |
| if not (math.isfinite(low) and math.isfinite(high)) or low >= high: | |
| raise ValueError( | |
| f"{kind} {name} needs finite min < max, got {spec['min']!r} and {spec['max']!r}" | |
| ) | |
| scale = spec.get("scale", "linear") | |
| if scale not in ("linear", "log"): | |
| raise ValueError( | |
| f"{kind} {name} has an unknown scale {scale!r}; use 'linear' or 'log'" | |
| ) | |
| if scale == "log" and low <= 0: | |
| raise ValueError( | |
| f"{kind} {name} uses scale 'log', which needs min > 0, got {spec['min']!r}" | |
| ) | |
| if spec.get("step") is None: | |
| return | |
| try: | |
| step = _number(spec["step"]) | |
| except TypeError as error: | |
| raise ValueError( | |
| f"{kind} {name}: step must be a positive number, got {spec['step']!r}" | |
| ) from error | |
| if not math.isfinite(step) or step <= 0: | |
| raise ValueError( | |
| f"{kind} {name}: step must be a positive number, got {spec['step']!r}" | |
| ) | |
| steps = (high - low) / step | |
| if steps < 1: | |
| raise ValueError( | |
| f"{kind} {name}: step {spec['step']!r} is larger than the range {spec['min']!r} to {spec['max']!r}" | |
| ) | |
| if steps > MAX_GRID_STEPS: | |
| raise ValueError( | |
| f"{kind} {name}: step {spec['step']!r} divides {spec['min']!r} to {spec['max']!r} into {steps:,.0f} steps; " | |
| f"the limit is {MAX_GRID_STEPS:,}. Use a larger step or omit it" | |
| ) | |
| def validate_reference_date(value: Any) -> None: | |
| if value is None: | |
| return | |
| try: | |
| datetime.date.fromisoformat(value) | |
| except (TypeError, ValueError) as error: | |
| raise ValueError( | |
| f"reference_date must be an ISO date, got {value!r}" | |
| ) from error | |
| def validate_date_range( | |
| name: str, spec: dict[str, Any], kind: str = "estimate" | |
| ) -> None: | |
| try: | |
| low, high, _ = estimate_range(spec) | |
| except (KeyError, TypeError, ValueError) as error: | |
| raise ValueError( | |
| f"date {kind} {name} needs ISO date min and max (YYYY-MM-DD)" | |
| ) from error | |
| if not isinstance(spec.get("max"), str) or not low < high: | |
| raise ValueError( | |
| f"date {kind} {name} needs ISO date min < max, got {spec.get('min')!r} and {spec.get('max')!r}" | |
| ) | |
| if spec.get("scale", "linear") != "linear": | |
| raise ValueError(f"date {kind} {name} only takes scale 'linear'") | |
| if date_granularity(spec) != "day" or spec.get("step") is None: | |
| return | |
| step = spec["step"] | |
| if ( | |
| isinstance(step, bool) | |
| or not isinstance(step, (int, float)) | |
| or not float(step).is_integer() | |
| or step < 1 | |
| ): | |
| raise ValueError( | |
| f"date {kind} {name}: step must be a whole number of days, 'month', or 'year', got {step!r}" | |
| ) | |
| if (high - low) / step < 1: | |
| raise ValueError( | |
| f"date {kind} {name}: step {step!r} days is larger than the range" | |
| ) | |