lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/infer/keys.py

@@ -0,0 +1,164 @@
+"""Primary key choice.
+
+Candidates are required, unique columns of a keyable type (string, integer, date, uri). They are
+ranked by ``key_name_patterns`` (``id``, ``key``, ``code``, ``{table}_id``... then ``*_id``...),
+then by column order. Without a named candidate the first column may be the key
+(``allow_unnamed_primary_key``); without any single candidate, pairs (and triples) of key-named
+or reference-named columns are tried. A declared primary key always wins.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from itertools import combinations
+
+from lorebase_core.infer.columns import ColumnAnalysis, support
+from lorebase_core.infer.names import rank
+from lorebase_core.infer.options import InferenceOptions
+from lorebase_core.types import AttributeType
+
+#: Types a primary key candidate may have.
+KEY_CANDIDATE_TYPES = frozenset(
+    {AttributeType.STRING, AttributeType.INTEGER, AttributeType.DATE, AttributeType.URI}
+)
+#: Confidence of a key chosen without a name hint, before support and sampling factors.
+UNNAMED_KEY_CONFIDENCE = 0.6
+#: Confidence of a composite key, before support and sampling factors.
+COMPOSITE_KEY_CONFIDENCE = 0.85
+
+
+@dataclass(frozen=True)
+class KeyChoice:
+    """The chosen key: column indexes in key order."""
+
+    columns: tuple[int, ...]
+    confidence: float
+    reasons: tuple[str, ...]
+    #: Named single-column candidates, best first (more than one is an ambiguity).
+    candidates: tuple[int, ...] = ()
+    declared: bool = False
+    #: The key column carries generated Record keys: the Kind uses minted keys.
+    minted: bool = False
+
+    @property
+    def single(self) -> int | None:
+        return self.columns[0] if len(self.columns) == 1 else None
+
+
+def key_patterns(table_names: Sequence[str], options: InferenceOptions) -> list[str]:
+    """``key_name_patterns`` with ``{table}`` expanded to each table name form, in rank order."""
+    expanded: list[str] = []
+    for pattern in options.key_name_patterns:
+        forms = [pattern.replace("{table}", name) for name in table_names]
+        for form in forms if "{table}" in pattern else [pattern]:
+            if form not in expanded:
+                expanded.append(form)
+    return expanded
+
+
+def _factor(columns: Sequence[ColumnAnalysis], sampled: bool, options: InferenceOptions) -> float:
+    non_null = min((c.non_null for c in columns), default=0)
+    sampling = options.sampled_uniqueness_factor if sampled else 1.0
+    return support(non_null, options) * sampling
+
+
+def _unique_rows(columns: Sequence[ColumnAnalysis]) -> bool:
+    rows = list(zip(*(c.row_keys for c in columns), strict=False))
+    if not rows or any(None in row for row in rows):
+        return False
+    return len(set(rows)) == len(rows)
+
+
+def choose_key(
+    table_names: Sequence[str],
+    columns: Sequence[ColumnAnalysis],
+    declared: tuple[str, ...] | None,
+    options: InferenceOptions,
+    *,
+    sampled: bool,
+    reference_like: frozenset[int] = frozenset(),
+) -> KeyChoice | None:
+    """The primary key of a table, or ``None`` when it has none (Records get minted keys).
+
+    ``reference_like`` lists columns named like references (``*_id``, ``from_key``): they may
+    form composite keys even when ``key_name_patterns`` does not list them.
+    """
+    by_name = {c.name: c for c in columns}
+    if declared:
+        found = [by_name[name] for name in declared if name in by_name]
+        if len(found) == len(declared):
+            return KeyChoice(
+                columns=tuple(c.index for c in found),
+                confidence=1.0,
+                reasons=(f"declared primary key ({', '.join(declared)})",),
+                declared=True,
+            )
+
+    patterns = key_patterns(table_names, options)
+    candidates = [
+        c for c in columns if c.required and c.unique and c.type.name in KEY_CANDIDATE_TYPES
+    ]
+    ranked: list[tuple[int, int, ColumnAnalysis]] = []
+    for column in candidates:
+        position = rank(column.snake, patterns)
+        if position is not None:
+            ranked.append((position, column.index, column))
+    ranked.sort(key=lambda item: (item[0], item[1]))
+    named = tuple(c.index for _, _, c in ranked)
+    if ranked:
+        best_rank, _, best = ranked[0]
+        reasons = [
+            f"{best.name!r} is unique and never null",
+            f"named like a key ({patterns[best_rank]})",
+        ]
+        if len(ranked) > 1:
+            others = ", ".join(repr(c.name) for _, _, c in ranked[1:])
+            reasons.append(f"other key candidates: {others}")
+        return KeyChoice(
+            columns=(best.index,),
+            confidence=round(_factor([best], sampled, options), 4),
+            reasons=tuple(reasons),
+            candidates=named,
+        )
+    if options.allow_unnamed_primary_key and candidates and candidates[0].index == 0:
+        first = candidates[0]
+        return KeyChoice(
+            columns=(first.index,),
+            confidence=round(UNNAMED_KEY_CONFIDENCE * _factor([first], sampled, options), 4),
+            reasons=(
+                f"first column {first.name!r} is unique and never null",
+                "no key-like column name",
+            ),
+        )
+
+    keyish = [
+        c
+        for c in columns
+        if c.required
+        and c.type.name in KEY_CANDIDATE_TYPES
+        and (rank(c.snake, patterns) is not None or c.index in reference_like)
+    ]
+    for size in range(2, options.composite_key_max_columns + 1):
+        for combo in combinations(keyish, size):
+            if _unique_rows(combo):
+                names = ", ".join(c.name for c in combo)
+                return KeyChoice(
+                    columns=tuple(c.index for c in combo),
+                    confidence=round(
+                        COMPOSITE_KEY_CONFIDENCE * _factor(combo, sampled, options), 4
+                    ),
+                    reasons=(f"({names}) is unique and never null: composite key",),
+                )
+    return None
+
+
+def is_minted(
+    choice: KeyChoice, columns: Sequence[ColumnAnalysis], options: InferenceOptions
+) -> bool:
+    """Whether the single key column carries generated Record keys (see ``minted_key_columns``)."""
+    single = choice.single
+    if single is None:
+        return False
+    column = columns[single]
+    return column.snake in options.minted_key_columns and column.generated_ids

lorebase_core/infer/names.py

@@ -0,0 +1,145 @@
+"""Stable name normalization: table and column names to api names.
+
+- ``normalize``: any source name to ``snake_case`` (``PurchaseOrders`` -> ``purchase_orders``,
+  ``Unit Price (EUR)`` -> ``unit_price_eur``, ``2nd_line`` -> ``c_2nd_line``).
+- ``singular`` / ``plural``: small English rules on the last word only.
+- ``pascal``: ``purchase_order`` -> ``PurchaseOrder``; ``humanize``: ``Purchase order``.
+- ``matches``: ``fnmatch`` of a normalized name against glob patterns.
+
+The functions are pure and deterministic, so the same source names always give the same api
+names.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Iterable
+from fnmatch import fnmatchcase
+
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+_VOWELS = frozenset("aeiou")
+#: Words whose singular and plural are the same, or that end in ``s`` in the singular.
+_INVARIANT = frozenset(
+    {"data", "series", "species", "news", "status", "address", "analysis", "basis", "bus"}
+)
+#: Fallback prefix of names that would start with a digit or be empty.
+NAME_PREFIX = "c"
+
+
+def normalize(name: str) -> str:
+    """``snake_case`` form of a source name: ASCII letters, digits and single underscores."""
+    ascii_name = unicodedata.normalize("NFKD", name).encode("ascii", "ignore").decode("ascii")
+    split = _CAMEL_BOUNDARY.sub("_", ascii_name.strip())
+    snake = _NON_ALNUM.sub("_", split.lower()).strip("_")
+    if not snake:
+        return NAME_PREFIX
+    if snake[0].isdigit():
+        return f"{NAME_PREFIX}_{snake}"
+    return snake
+
+
+def strip_prefixes(name: str, prefixes: Iterable[str]) -> str:
+    """``name`` without the first matching prefix, unless nothing would remain."""
+    for prefix in prefixes:
+        if prefix and name.startswith(prefix) and len(name) > len(prefix):
+            return name[len(prefix) :]
+    return name
+
+
+def _last_word(snake: str) -> tuple[str, str]:
+    head, sep, last = snake.rpartition("_")
+    return (head + sep, last)
+
+
+def singular(snake: str) -> str:
+    """Singular of the last word: ``suppliers`` -> ``supplier``, ``categories`` -> ``category``."""
+    head, word = _last_word(snake)
+    if word in _INVARIANT or len(word) < 3:
+        return snake
+    if word.endswith("ies") and len(word) > 4:
+        word = word[:-3] + "y"
+    elif word.endswith(("sses", "shes", "ches", "xes", "zes")):
+        word = word[:-2]
+    elif word.endswith("s") and not word.endswith(("ss", "us", "is")):
+        word = word[:-1]
+    return head + word
+
+
+def plural(snake: str) -> str:
+    """Plural of the last word: ``order`` -> ``orders``, ``category`` -> ``categories``."""
+    head, word = _last_word(snake)
+    if word in _INVARIANT:
+        return snake
+    if word.endswith("y") and len(word) > 1 and word[-2] not in _VOWELS:
+        word = word[:-1] + "ies"
+    elif word.endswith(("s", "x", "z", "ch", "sh")):
+        word += "es"
+    else:
+        word += "s"
+    return head + word
+
+
+def pascal(snake: str) -> str:
+    """``purchase_order`` -> ``PurchaseOrder``; a leading digit gets the fallback prefix."""
+    text = "".join(part[:1].upper() + part[1:] for part in snake.split("_") if part)
+    if not text or not text[0].isalpha():
+        return NAME_PREFIX.upper() + text
+    return text
+
+
+def humanize(snake: str) -> str:
+    """``purchase_order`` -> ``Purchase order``."""
+    words = snake.replace("_", " ").strip()
+    return words[:1].upper() + words[1:]
+
+
+def matches(name: str, patterns: Iterable[str]) -> bool:
+    """Whether the normalized ``name`` matches one of the glob ``patterns``."""
+    return any(fnmatchcase(name, pattern) for pattern in patterns)
+
+
+def rank(name: str, patterns: Iterable[str]) -> int | None:
+    """Index of the first pattern ``name`` matches, or ``None``."""
+    for index, pattern in enumerate(patterns):
+        if fnmatchcase(name, pattern):
+            return index
+    return None
+
+
+def strip_suffix(name: str, suffixes: Iterable[str]) -> str | None:
+    """``name`` without the first matching suffix (``supplier_id`` -> ``supplier``), or
+    ``None`` when no suffix matches or nothing would remain."""
+    for suffix in suffixes:
+        if suffix and name.endswith(suffix) and len(name) > len(suffix):
+            return name[: -len(suffix)].rstrip("_") or None
+    return None
+
+
+def unique_name(candidate: str, taken: set[str], alternatives: Iterable[str] = ()) -> str:
+    """The first of ``candidate``, ``alternatives`` and ``candidate_2``, ``candidate_3``... not
+    in ``taken``; the result is added to ``taken``."""
+    for name in (candidate, *alternatives):
+        if name not in taken:
+            taken.add(name)
+            return name
+    index = 2
+    while f"{candidate}_{index}" in taken:
+        index += 1
+    result = f"{candidate}_{index}"
+    taken.add(result)
+    return result
+
+
+def unique_pascal(candidate: str, taken: set[str]) -> str:
+    """PascalCase variant of ``unique_name`` (``Order``, ``Order2``)."""
+    if candidate not in taken:
+        taken.add(candidate)
+        return candidate
+    index = 2
+    while f"{candidate}{index}" in taken:
+        index += 1
+    result = f"{candidate}{index}"
+    taken.add(result)
+    return result

lorebase_core/infer/options.py

@@ -0,0 +1,290 @@
+"""Thresholds and naming rules of schema inference, with documented defaults.
+
+Every heuristic of ``lorebase_core.infer`` reads its threshold from ``InferenceOptions``; nothing
+is hard-coded in the rules. Services expose these options as settings (see
+``config/lorebase.example.yaml``, ``keeper.schema_inference.options``).
+
+Name patterns are ``fnmatch`` globs matched against normalized ``snake_case`` names. In key
+patterns ``{table}`` stands for the normalized table name and for its singular form.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from lorebase_core.model.base import ElementStatus
+from lorebase_core.validate.schema_rules import DEFAULT_RESERVED_ATTRIBUTE_NAMES
+
+
+class InferenceOptions(BaseModel):
+    """Options of ``infer_schema``. Defaults suit small to medium operational tables."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    # Sampling and value reading ----------------------------------------------------------
+    sample_size: int = Field(
+        default=10000,
+        ge=1,
+        description="Values read per column; longer value iterables are cut (head sample).",
+    )
+    null_tokens: tuple[str, ...] = Field(
+        default=("", "NULL", "null"),
+        description="Text values read as null (after trimming). Exact, case-sensitive match.",
+    )
+    trim_text: bool = Field(default=True, description="Trim whitespace around text values.")
+    max_evidence_samples: int = Field(
+        default=5, ge=0, description="Sample values kept in each Evidence entry."
+    )
+    min_support_values: int = Field(
+        default=20,
+        ge=1,
+        description="Non-null values needed for full confidence; fewer scale confidence down "
+        "linearly (to half at zero values).",
+    )
+    sampled_uniqueness_factor: float = Field(
+        default=0.8,
+        ge=0,
+        le=1,
+        description="Confidence factor of uniqueness and inclusion seen on a sample only "
+        "(row_count above the values read).",
+    )
+
+    # Types ---------------------------------------------------------------------------------
+    true_tokens: tuple[str, ...] = Field(
+        default=("true", "t", "yes", "y"), description="Boolean true, compared case-insensitively."
+    )
+    false_tokens: tuple[str, ...] = Field(
+        default=("false", "f", "no", "n"),
+        description="Boolean false, compared case-insensitively.",
+    )
+    type_tolerance: float = Field(
+        default=0.0,
+        ge=0,
+        lt=1,
+        description="Share of non-null values allowed not to parse as the detected type. "
+        "Outliers are reported as a mixed_types issue.",
+    )
+    mixed_type_report_ratio: float = Field(
+        default=0.5,
+        gt=0,
+        le=1,
+        description="A text column where at least this share parses as one non-text type is "
+        "reported as mixed_types.",
+    )
+    leading_zero_integers_as_text: bool = Field(
+        default=True, description="Integers written with leading zeros (007) stay text codes."
+    )
+    decimal_max_scale: int = Field(
+        default=4,
+        ge=0,
+        description="Numbers with at most this many fractional digits are decimal; more: float.",
+    )
+    decimal_precision_headroom: int = Field(
+        default=2,
+        ge=0,
+        description="Integer digits added to the largest seen when proposing decimal precision.",
+    )
+    decimal_max_precision: int = Field(default=38, ge=1, description="Cap of decimal precision.")
+    date_formats: tuple[str, ...] = Field(
+        default=("%Y-%m-%d",),
+        description="strptime formats of date values. Day-month ambiguity is left to the user.",
+    )
+    timestamp_formats: tuple[str, ...] = Field(
+        default=("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S"),
+        description="strptime formats of timestamps without offset, read as UTC. RFC 3339 "
+        "values with an offset are always recognized.",
+    )
+    enum_max_cardinality: int = Field(
+        default=12, ge=1, description="Text columns with at most this many distinct values ..."
+    )
+    enum_max_distinct_ratio: float = Field(
+        default=0.5, gt=0, le=1, description="... and at most this distinct/non-null ratio ..."
+    )
+    enum_min_values: int = Field(
+        default=10, ge=1, description="... and at least this many non-null values are enum."
+    )
+    enum_max_value_length: int = Field(
+        default=40, ge=1, description="Longer values never form an enum."
+    )
+    text_min_length: int = Field(
+        default=256, ge=1, description="Text values longer than this make the column `text`."
+    )
+    text_name_hints: tuple[str, ...] = Field(
+        default=(
+            "description",
+            "*_description",
+            "summary",
+            "reason",
+            "notes",
+            "note",
+            "comment",
+            "comments",
+            "body",
+            "content",
+            "details",
+        ),
+        description="Column names whose prose values (see text_hint_min_words) are `text`.",
+    )
+    text_hint_min_words: float = Field(
+        default=3.0, ge=0, description="Average words per value needed by text_name_hints."
+    )
+    string_length_buckets: tuple[int, ...] = Field(
+        default=(16, 32, 64, 128, 256),
+        description="max_length of strings is the longest value rounded up to a bucket.",
+    )
+    propose_max_length: bool = Field(
+        default=True, description="Propose a max_length constraint on strings."
+    )
+    propose_patterns: bool = Field(
+        default=True,
+        description="Propose a pattern for code-like strings sharing one shape (S-1001, PL).",
+    )
+    pattern_min_values: int = Field(
+        default=5, ge=1, description="Distinct values needed before a pattern is proposed."
+    )
+    propose_non_negative_min: bool = Field(
+        default=True, description="Propose min 0 on numbers that are never negative."
+    )
+
+    # Nullability and uniqueness -----------------------------------------------------------
+    required_max_null_ratio: float = Field(
+        default=0.0,
+        ge=0,
+        lt=1,
+        description="Columns with at most this share of nulls are required.",
+    )
+    unique_min_values: int = Field(
+        default=2, ge=1, description="Non-null values needed before uniqueness counts."
+    )
+    unique_name_patterns: tuple[str, ...] = Field(
+        default=("*_number", "*_code", "*_id", "*_key", "email", "*_email", "vat*", "iban"),
+        description="Unique non-key columns flagged `unique` only when named like this.",
+    )
+
+    # Keys ----------------------------------------------------------------------------------
+    key_name_patterns: tuple[str, ...] = Field(
+        default=(
+            "id",
+            "key",
+            "code",
+            "{table}_id",
+            "{table}_key",
+            "{table}_code",
+            "{table}_number",
+            "{table}_no",
+            "*_id",
+            "*_key",
+            "*_code",
+            "*_number",
+            "*_no",
+        ),
+        description="Ranked names of primary key candidates (unique, non-null columns).",
+    )
+    allow_unnamed_primary_key: bool = Field(
+        default=True,
+        description="When no candidate matches key_name_patterns, the first column may still "
+        "be the key if it is unique and non-null.",
+    )
+    composite_key_max_columns: int = Field(
+        default=2,
+        ge=1,
+        le=3,
+        description="Largest composite key tried (key-named and foreign key-like columns only).",
+    )
+    minted_key_columns: tuple[str, ...] = Field(
+        default=("key",),
+        description="A key column with one of these names holding generated ids (ULID, UUID) "
+        "carries Record keys: the Kind gets minted keys and no key Attribute.",
+    )
+
+    # Foreign keys and Relations ------------------------------------------------------------
+    min_inclusion_ratio: float = Field(
+        default=0.95,
+        gt=0,
+        le=1,
+        description="Share of a column's distinct values found in another table's key for a "
+        "foreign key (and a Relation) to be proposed.",
+    )
+    foreign_key_suffixes: tuple[str, ...] = Field(
+        default=("_id", "_key", "_code", "_number", "_no", "_ref", "_fk"),
+        description="Suffixes marking reference columns; stripped to name the Relation.",
+    )
+    integer_reference_needs_name: bool = Field(
+        default=True,
+        description="Integer columns reference another table only when their name points at "
+        "it (small integers are included in most integer keys).",
+    )
+    weak_name_factor: float = Field(
+        default=0.9,
+        ge=0,
+        le=1,
+        description="Confidence factor of a reference whose name has a reference suffix but "
+        "does not name the target.",
+    )
+    no_name_factor: float = Field(
+        default=0.75,
+        ge=0,
+        le=1,
+        description="Confidence factor of a reference whose name gives no hint at all.",
+    )
+    detect_junction_tables: bool = Field(
+        default=True,
+        description="Tables made of two foreign keys (plus link attributes) become Relations.",
+    )
+    junction_max_attributes: int = Field(
+        default=8, ge=0, description="Link attributes a junction table may carry."
+    )
+    one_to_one_needs_declared_unique: bool = Field(
+        default=True,
+        description="Uniqueness seen in data never makes a Relation one_to_one; a declared "
+        "unique constraint (or a key reference) does.",
+    )
+
+    # Names ---------------------------------------------------------------------------------
+    singular_kind_names: bool = Field(
+        default=True, description="Kind names are the singular of table names (suppliers)."
+    )
+    strip_table_prefixes: tuple[str, ...] = Field(
+        default=(), description="Prefixes removed from table names, e.g. tbl_."
+    )
+    title_names: tuple[str, ...] = Field(
+        default=("name", "title", "label", "display_name", "*_name", "*_title", "*_label"),
+        description="Ranked names of the title Attribute.",
+    )
+    propose_search: bool = Field(
+        default=True,
+        description="Make the title Attribute searchable (weight A) and text Attributes "
+        "searchable (weight B).",
+    )
+    reserved_attribute_names: tuple[str, ...] = Field(
+        default=tuple(sorted(DEFAULT_RESERVED_ATTRIBUTE_NAMES)),
+        description="Attribute names reserved by Lorebase; colliding columns are renamed "
+        "<kind>_<column>.",
+    )
+
+    # Ids and status ------------------------------------------------------------------------
+    element_status: ElementStatus = Field(
+        default=ElementStatus.DRAFT,
+        description="Status of proposed Kinds and Relations; draft elements need no "
+        "descriptions until a reviewer activates them.",
+    )
+    id_seed: str = Field(
+        default="lorebase.infer",
+        description="Seed of the deterministic ids: the same input and seed give the same ids.",
+    )
+    id_timestamp_ms: int = Field(
+        default=0, ge=0, lt=2**48, description="Timestamp part of the deterministic ULIDs."
+    )
+
+    @model_validator(mode="after")
+    def _check(self) -> Self:
+        if not self.string_length_buckets or list(self.string_length_buckets) != sorted(
+            set(self.string_length_buckets)
+        ):
+            raise ValueError("string_length_buckets must be strictly increasing and non-empty")
+        overlap = {t.lower() for t in self.true_tokens} & {t.lower() for t in self.false_tokens}
+        if overlap:
+            raise ValueError(f"tokens both true and false: {sorted(overlap)}")
+        return self

lorebase_core/infer/profile.py

@@ -0,0 +1,54 @@
+"""Input of schema inference: what a profiler saw of each table.
+
+A profiler (CSV reader, database catalog reader) turns a structured source into
+``TableProfile`` objects; inference never reads files or connects to anything. Values are
+Python natives (``str`` from CSV; ``int``, ``Decimal``, ``date``, ``bool``... from databases);
+``None`` is null. A profile may also carry what a catalog declares (types, nullability, keys,
+foreign keys, comments): declared facts win over facts seen in values.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from lorebase_core.types import TypeSpec
+
+
+@dataclass(frozen=True, slots=True)
+class DeclaredForeignKey:
+    """A foreign key constraint of the source catalog."""
+
+    columns: tuple[str, ...]
+    target_table: str
+    target_columns: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnProfile:
+    """One column: its values (sampled or complete) and what a catalog declares about it.
+
+    ``values`` may be any iterable, including a generator over a complete column; inference
+    reads at most ``InferenceOptions.sample_size`` of them.
+    """
+
+    name: str
+    values: Iterable[object] = ()
+    declared_type: TypeSpec | None = None
+    declared_max_length: int | None = None
+    nullable: bool | None = None
+    unique: bool | None = None
+    comment: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TableProfile:
+    """One table. ``row_count`` is the size of the whole table when the values are a sample;
+    ``None`` means the values are the whole table."""
+
+    name: str
+    columns: tuple[ColumnProfile, ...]
+    row_count: int | None = None
+    primary_key: tuple[str, ...] | None = None
+    foreign_keys: tuple[DeclaredForeignKey, ...] = field(default=())
+    comment: str | None = None