@roll-agent/octopus-agent 0.0.10 → 0.0.11

package/src/octopus_skill/config.py

@@ -24,13 +24,30 @@ class SchemaConfig:
     refresh_interval_minutes: int
 
 
+@dataclass(frozen=True)
+class DictionaryConfig:
+    cache_path: Path
+    geo_alias_path: Path
+    refresh_on_start: bool
+    refresh_interval_minutes: int
+    entity_types: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EntityBindingConfig:
+    # Compute bindings and log them, but do not change SQL generation yet.
+    shadow_mode: bool
+    # Entity types whose bindings are allowed to influence SQL (live rollout).
+    # In shadow_mode this is ignored.
+    enabled_entity_types: tuple[str, ...]
+    min_fuzzy_score: float
+
+
 @dataclass(frozen=True)
 class SqlConfig:
     max_repair_attempts: int
     default_limit: int
     max_limit: int
-    query_cache_path: Path | None = None
-    query_cache_ttl_minutes: int = 30
 
 
 @dataclass(frozen=True)
@@ -45,6 +62,8 @@ class AppConfig:
     schema: SchemaConfig
     sql: SqlConfig
     audit: AuditConfig
+    dictionary: DictionaryConfig | None = None
+    binding: EntityBindingConfig | None = None
 
 
 def load_config() -> AppConfig:
@@ -59,17 +78,29 @@ def load_config() -> AppConfig:
             refresh_on_start=True,
             refresh_interval_minutes=1440,
         ),
+        dictionary=DictionaryConfig(
+            cache_path=PACKAGE_ROOT / "data/sponge-entity-cache.json",
+            geo_alias_path=PACKAGE_ROOT / "data/geo-aliases.json",
+            refresh_on_start=True,
+            refresh_interval_minutes=1440,
+            entity_types=("brand", "province", "city", "region", "project"),
+        ),
         sql=SqlConfig(
             max_repair_attempts=2,
-            default_limit=50,
+            default_limit=200,
             max_limit=500,
-            query_cache_path=_optional_path("OCTOPUS_QUERY_SQL_CACHE_PATH"),
-            query_cache_ttl_minutes=30,
         ),
         audit=AuditConfig(
             enabled=True,
             log_path=PACKAGE_ROOT / "logs/octopus-sponge-audit.log",
         ),
+        binding=EntityBindingConfig(
+            shadow_mode=_env_bool("OCTOPUS_BINDING_SHADOW", default=False),
+            enabled_entity_types=_env_csv(
+                "OCTOPUS_BINDING_ENABLED", default=("brand", "location", "project")
+            ),
+            min_fuzzy_score=_env_float("OCTOPUS_BINDING_MIN_SCORE", default=0.6),
+        ),
     )
 
 
@@ -77,8 +108,25 @@ def load_config_from_env() -> AppConfig:
     return load_config()
 
 
-def _optional_path(env_name: str) -> Path | None:
-    value = os.getenv(env_name)
-    if value is None or not value.strip():
-        return None
-    return Path(value).expanduser()
+def _env_bool(name: str, *, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None or value == "":
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_csv(name: str, *, default: tuple[str, ...] = ()) -> tuple[str, ...]:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def _env_float(name: str, *, default: float) -> float:
+    value = os.getenv(name)
+    if value is None or value == "":
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        return default

package/src/octopus_skill/entity_binding.py

@@ -0,0 +1,523 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+from .entity_resolver import EntityResolver, Mention, ResolvedEntity, _geo_core, _norm
+
+
+# brand/project are scanned for mentions; on equal-length text overlaps the
+# higher-priority type wins.
+_NAMED_TYPES = ("brand", "project")
+_TYPE_PRIORITY = {"brand": 5, "project": 4}
+_GEO_TYPES = ("province", "city", "region")
+# Placeholder used to mask brand/project spans before geo resolution, so a city
+# name embedded in a brand (e.g. "成都" in "成都你六姐") is not mis-detected.
+_MASK_CHAR = "\u3000"
+_STORE_NAME_CHARS = r"[\u4e00-\u9fffA-Za-z0-9（）()·_\-]{2,40}"
+_STORE_SEPARATOR = r"[\s:：,，、;；]+"
+_STORE_NAME_STOP = (
+    r"(?=[，,。；;？?\s]|有哪些|有什么|哪些|多少|岗位|职位|在招|招聘|包括|返回|状态|$)"
+)
+
+
+@dataclass(frozen=True)
+class EntityAmbiguity:
+    """A user term that can refer to both brand and project."""
+
+    term: str
+    brands: list[ResolvedEntity] = field(default_factory=list)
+    projects: list[ResolvedEntity] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class EntityBindings:
+    """Structured entities resolved from a question against the dictionary."""
+
+    brands: list[ResolvedEntity] = field(default_factory=list)
+    projects: list[ResolvedEntity] = field(default_factory=list)
+    location: dict[str, ResolvedEntity] = field(default_factory=dict)
+    ambiguity: EntityAmbiguity | None = None
+
+    def is_empty(self) -> bool:
+        return not self.brands and not self.projects and not self.location and self.ambiguity is None
+
+    def to_log_dict(self) -> dict[str, object]:
+        """Compact form for shadow-mode audit logging."""
+        payload: dict[str, object] = {
+            "brands": [_entity_log(entity) for entity in self.brands],
+            "projects": [_entity_log(entity) for entity in self.projects],
+            "location": {level: _entity_log(entity) for level, entity in self.location.items()},
+        }
+        if self.ambiguity is not None:
+            payload["ambiguity"] = {
+                "term": self.ambiguity.term,
+                "brands": [_entity_log(entity) for entity in self.ambiguity.brands],
+                "projects": [_entity_log(entity) for entity in self.ambiguity.projects],
+            }
+        return payload
+
+
+def bind_entities(
+    question: str,
+    resolver: EntityResolver | None,
+    *,
+    fuzzy_candidates: dict[str, list[str]] | None = None,
+    min_fuzzy_score: float = 0.6,
+) -> EntityBindings:
+    """Resolve the entities mentioned in ``question``.
+
+    Pipeline:
+
+    1. **Named-entity mention scan** (brand/project) over the whole question.
+       Cross-type overlaps are resolved by longest-match, so a brand like
+       "成都你六姐" wins over the embedded city "成都".
+    2. **Geo resolution** on the question with the accepted brand/project spans
+       and explicit ``门店：…`` name spans masked out. ``resolve_location``
+       disambiguates duplicate region names (e.g. 宝山区 in 上海 vs 黑龙江)
+       using the co-mentioned province/city.
+    3. **Fuzzy fallback** for caller-provided spans (typically regex-extracted)
+       that the dictionary scan misses, e.g. the typo "刘姐" -> "成都你六姐".
+    """
+    if resolver is None:
+        return EntityBindings()
+
+    explicit_type = _explicit_named_entity_type(question)
+    named_types = (explicit_type,) if explicit_type in _NAMED_TYPES else _NAMED_TYPES
+    named_mentions: list[Mention] = []
+    for entity_type in named_types:
+        named_mentions.extend(resolver.find_mentions(question, entity_type))
+    accepted = _resolve_overlaps(named_mentions)
+    preferred_scoped_project = False
+    if explicit_type is None:
+        accepted, preferred_scoped_project = _prefer_exact_project_for_scoped_job_query(
+            question,
+            resolver,
+            accepted,
+            named_mentions,
+            min_fuzzy_score=min_fuzzy_score,
+        )
+    ambiguity = (
+        _detect_brand_project_ambiguity(resolver, accepted, question=question)
+        if explicit_type is None and not preferred_scoped_project
+        else None
+    )
+
+    brands: dict[object, ResolvedEntity] = {}
+    projects: dict[object, ResolvedEntity] = {}
+    for mention in accepted:
+        entity = mention.entity
+        target = brands if entity.entity_type == "brand" else projects
+        target.setdefault(entity.id, entity)
+
+    masked_question = _mask_spans(_norm(question), accepted)
+    masked_question = _mask_ranges(masked_question, _store_name_ranges(masked_question))
+    location = resolver.resolve_location(masked_question, min_score=min_fuzzy_score)
+
+    candidate_ambiguity = _fuzzy_candidate_ambiguity(
+        resolver,
+        fuzzy_candidates or {},
+        explicit_type=explicit_type,
+        min_fuzzy_score=min_fuzzy_score,
+        brands=brands,
+        projects=projects,
+    )
+    if candidate_ambiguity is not None:
+        return EntityBindings(
+            brands=list(brands.values()),
+            projects=list(projects.values()),
+            location=location,
+            ambiguity=candidate_ambiguity,
+        )
+
+    _merge_fuzzy_candidates(
+        resolver,
+        fuzzy_candidates or {},
+        brands=brands,
+        projects=projects,
+        location=location,
+        min_fuzzy_score=min_fuzzy_score,
+        explicit_type=explicit_type,
+    )
+
+    return EntityBindings(
+        brands=list(brands.values()),
+        projects=list(projects.values()),
+        location=location,
+        ambiguity=ambiguity,
+    )
+
+
+def _explicit_named_entity_type(question: str) -> str | None:
+    has_brand = _has_prefix_type_marker(question, "品牌") or _has_postfix_type_marker(question, "品牌")
+    has_project = _has_prefix_type_marker(question, "项目") or _has_postfix_type_marker(question, "项目")
+    if has_brand == has_project:
+        return None
+    return "brand" if has_brand else "project"
+
+
+def _has_prefix_type_marker(question: str, marker: str) -> bool:
+    name_suffix = _FIELD_LABEL_NAME_SUFFIX
+    patterns = [
+        rf"{marker}(?:名称)?\s*[「“\"'《【（(](?P<name>[A-Za-z0-9_\-\u4e00-\u9fff]{{2,40}})",
+        rf"{marker}(?:名称)?(?:为|是|=|等于|:|：)\s*[「“\"'《【（(]?(?P<name>[A-Za-z0-9_\-\u4e00-\u9fff]{{2,40}})",
+        rf"{marker}\s+(?P<name>[A-Za-z0-9_\-\u4e00-\u9fff]{{2,40}})",
+        # 「项目成都你六姐」/「品牌必胜客」/「项目成都你六姐 门店：…」等写法。
+        rf"{marker}(?P<name>[A-Za-z0-9_\-\u4e00-\u9fff]{{2,40}}){name_suffix}",
+    ]
+    return any(_specific_marker_match(pattern, question) for pattern in patterns)
+
+
+_FIELD_LABEL_NAME_SUFFIX = (
+    r"(?:在(?!招)|的|下|有|还|目前|当前|现在|是|$|[，,。；;？?]"
+    r"|\s+(?=门店|品牌|项目|岗位|职位|城市|区域|有哪些|有什么|多少|包括|返回|状态)"
+    r"|(?=位于|有哪些|有什么|多少|包括|返回|状态|岗位|职位|门店|品牌|项目))"
+)
+
+
+def _has_postfix_type_marker(question: str, marker: str) -> bool:
+    suffix = rf"(?:{marker})\s*(?:在|的|下|有|还|目前|当前|现在|是|$)"
+    for match in re.finditer(rf"(?P<name>[A-Za-z0-9_\-\u4e00-\u9fff]{{2,40}})\s*{suffix}", question):
+        if _is_specific_entity_name(match.group("name")):
+            return True
+    return False
+
+
+def _specific_marker_match(pattern: str, question: str) -> bool:
+    for match in re.finditer(pattern, question):
+        if _is_specific_entity_name(match.group("name")):
+            return True
+    return False
+
+
+def _is_specific_entity_name(value: str) -> bool:
+    name = re.sub(
+        r"^(帮我|请问|查询|查看|统计|搜索|看下|看一下|我想知道|想知道)",
+        "",
+        value,
+    )
+    generic_terms = {
+        "哪些",
+        "什么",
+        "所有",
+        "全部",
+        "查询",
+        "查看",
+        "招聘",
+        "在招",
+        "岗位",
+        "职位",
+        "有哪些",
+    }
+    generic_prefixes = ("在", "有哪些", "哪些", "什么", "所有", "全部", "目前", "当前", "现在")
+    return bool(name) and name not in generic_terms and not name.startswith(generic_prefixes)
+
+
+def _detect_brand_project_ambiguity(
+    resolver: EntityResolver,
+    accepted: list[Mention],
+    *,
+    question: str = "",
+) -> EntityAmbiguity | None:
+    for mention in accepted:
+        entity_type = mention.entity.entity_type
+        if entity_type not in _NAMED_TYPES:
+            continue
+        term = mention.text
+        if _field_marker_around_term(question, term, "项目"):
+            continue
+        if _field_marker_around_term(question, term, "品牌"):
+            continue
+        brands = resolver.find_containing(term, "brand")
+        projects = resolver.find_containing(term, "project")
+        if brands and projects:
+            return EntityAmbiguity(term=term, brands=brands, projects=projects)
+    return None
+
+
+def _prefer_exact_project_for_scoped_job_query(
+    question: str,
+    resolver: EntityResolver,
+    accepted: list[Mention],
+    all_mentions: list[Mention],
+    *,
+    min_fuzzy_score: float,
+) -> tuple[list[Mention], bool]:
+    if not accepted or not _has_job_query_signal(question):
+        return accepted, False
+
+    normalized = _norm(question)
+    masked_question = _mask_spans(normalized, accepted)
+    masked_question = _mask_ranges(masked_question, _store_name_ranges(masked_question))
+    has_location = bool(resolver.resolve_location(masked_question, min_score=min_fuzzy_score))
+    has_store_scope = "门店" in normalized
+    if not has_location and not has_store_scope:
+        return accepted, False
+
+    replacements: list[Mention] = []
+    changed = False
+    for mention in accepted:
+        if mention.entity.entity_type != "brand":
+            replacements.append(mention)
+            continue
+        project = _same_name_project_mention(mention, all_mentions)
+        if project is None:
+            replacements.append(mention)
+            continue
+        replacements.append(project)
+        changed = True
+    return (replacements, True) if changed else (accepted, False)
+
+
+def _has_job_query_signal(question: str) -> bool:
+    return bool(re.search(r"岗位|职位|在招|招聘|招人", _norm(question)))
+
+
+def _same_name_project_mention(brand_mention: Mention, all_mentions: list[Mention]) -> Mention | None:
+    brand_name = _norm(brand_mention.entity.canonical)
+    for mention in all_mentions:
+        if mention.entity.entity_type != "project":
+            continue
+        if mention.start != brand_mention.start or mention.end != brand_mention.end:
+            continue
+        if _norm(mention.entity.canonical) == brand_name:
+            return mention
+    return None
+
+
+def _field_marker_around_term(question: str, term: str, marker: str) -> bool:
+    return _field_marker_before_term(question, term, marker) or _field_marker_after_term(question, term, marker)
+
+
+def _field_marker_before_term(question: str, term: str, marker: str) -> bool:
+    """True when ``term`` is introduced by an explicit field label like ``项目：``."""
+    normalized = _norm(question)
+    term_key = _norm(term)
+    start = normalized.find(term_key)
+    if start <= 0:
+        return False
+    prefix = normalized[:start]
+    if prefix.endswith(marker):
+        return True
+    return bool(re.search(rf"{marker}(?:名称)?(?:[：:]\s*|\s+)$", prefix))
+
+
+def _field_marker_after_term(question: str, term: str, marker: str) -> bool:
+    normalized = _norm(question)
+    term_key = re.escape(_norm(term))
+    if not term_key:
+        return False
+    return bool(
+        re.search(
+            rf"{term_key}\s*{marker}\s*(?:在|的|下|有|还|目前|当前|现在|是|$|[，,。；;？?\s])",
+            normalized,
+        )
+    )
+
+
+def _fuzzy_candidate_ambiguity(
+    resolver: EntityResolver,
+    fuzzy_candidates: dict[str, list[str]],
+    *,
+    explicit_type: str | None,
+    min_fuzzy_score: float,
+    brands: dict[object, ResolvedEntity] | None = None,
+    projects: dict[object, ResolvedEntity] | None = None,
+) -> EntityAmbiguity | None:
+    bound_brands = brands or {}
+    bound_projects = projects or {}
+    for entity_type, spans in fuzzy_candidates.items():
+        if entity_type not in _NAMED_TYPES:
+            continue
+        if explicit_type in _NAMED_TYPES and entity_type != explicit_type:
+            continue
+        if explicit_type == "brand" and bound_brands:
+            continue
+        if explicit_type == "project" and bound_projects:
+            continue
+        for span in spans:
+            if _is_location_like_entity_span(span):
+                continue
+            direct = resolver.resolve(span, entity_type, limit=2, min_score=min_fuzzy_score)
+            if len(direct) == 1 and direct[0].matched_via in {"exact", "alias"}:
+                continue
+            candidates = resolver.find_containing(span, entity_type)
+            if not candidates:
+                candidates = resolver.resolve(span, entity_type, limit=10, min_score=min_fuzzy_score)
+            if entity_type == "brand":
+                return EntityAmbiguity(term=span, brands=candidates, projects=[])
+            return EntityAmbiguity(term=span, brands=[], projects=candidates)
+    return None
+
+
+def _is_location_like_entity_span(span: str) -> bool:
+    from .sql_generator import _is_location_like_entity_name
+
+    return _is_location_like_entity_name(re.sub(r"\s+", "", span))
+
+
+def _resolve_overlaps(mentions: Iterable[Mention]) -> list[Mention]:
+    ordered = sorted(
+        mentions,
+        key=lambda mention: (
+            mention.end - mention.start,
+            _TYPE_PRIORITY.get(mention.entity.entity_type, 0),
+            -mention.start,
+        ),
+        reverse=True,
+    )
+    accepted: list[Mention] = []
+    for mention in ordered:
+        if any(_overlaps(mention, other) for other in accepted):
+            continue
+        accepted.append(mention)
+    return sorted(accepted, key=lambda mention: mention.start)
+
+
+def _overlaps(a: Mention, b: Mention) -> bool:
+    return a.start < b.end and b.start < a.end
+
+
+def _mask_spans(text: str, mentions: Iterable[Mention]) -> str:
+    return _mask_ranges(text, ((mention.start, mention.end) for mention in mentions))
+
+
+def _mask_ranges(text: str, ranges: Iterable[tuple[int, int]]) -> str:
+    chars = list(text)
+    for start, end in ranges:
+        for index in range(start, min(end, len(chars))):
+            chars[index] = _MASK_CHAR
+    return "".join(chars)
+
+
+def _store_name_ranges(normalized_question: str) -> list[tuple[int, int]]:
+    """Character spans of explicit store names that must not feed geo resolution."""
+    patterns = [
+        rf"门店(?:名称)?(?:为|是|=|等于|:|：)\s*(?P<name>{_STORE_NAME_CHARS}){_STORE_NAME_STOP}",
+        rf"门店{_STORE_SEPARATOR}(?P<name>{_STORE_NAME_CHARS}){_STORE_NAME_STOP}",
+        rf"(?P<name>{_STORE_NAME_CHARS})的门店{_STORE_NAME_STOP}",
+        # Prefix marker only; skip the suffix marker in 「…的门店」.
+        rf"(?<!的)(?<![店])门店(?P<name>{_STORE_NAME_CHARS}){_STORE_NAME_STOP}",
+    ]
+    ranges: list[tuple[int, int]] = []
+    for pattern in patterns:
+        for match in re.finditer(pattern, normalized_question):
+            name = _clean_store_name(match.group("name"))
+            if name is None:
+                continue
+            start = match.start("name")
+            ranges.append((start, start + len(name)))
+    return _merge_ranges(ranges)
+
+
+def _clean_store_name(value: str) -> str | None:
+    name = re.sub(r"\s+", "", value)
+    name = name.strip("\"'“”‘’%:：,，、;；")
+    forbidden = ("哪些", "什么", "所有", "全部", "查询", "查看", "门店", "岗位", "职位")
+    if name.startswith(("在", "位于", "有哪些", "有什么", "多少")):
+        return None
+    if 2 <= len(name) <= 40 and name not in forbidden:
+        return name
+    return None
+
+
+def _merge_ranges(ranges: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    if not ranges:
+        return []
+    ordered = sorted(ranges)
+    merged: list[tuple[int, int]] = [ordered[0]]
+    for start, end in ordered[1:]:
+        last_start, last_end = merged[-1]
+        if start <= last_end:
+            merged[-1] = (last_start, max(last_end, end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def _merge_fuzzy_candidates(
+    resolver: EntityResolver,
+    fuzzy_candidates: dict[str, list[str]],
+    *,
+    brands: dict[object, ResolvedEntity],
+    projects: dict[object, ResolvedEntity],
+    location: dict[str, ResolvedEntity],
+    min_fuzzy_score: float,
+    explicit_type: str | None = None,
+) -> None:
+    for entity_type, spans in fuzzy_candidates.items():
+        if explicit_type in _NAMED_TYPES and entity_type != explicit_type:
+            continue
+        for span in spans:
+            if _is_location_like_entity_span(span):
+                continue
+            if entity_type in _GEO_TYPES or entity_type == "location":
+                if location:
+                    continue
+                resolved = resolver.resolve_location(span, min_score=min_fuzzy_score)
+                for level, entity in resolved.items():
+                    location.setdefault(level, entity)
+                continue
+            results = resolver.resolve(span, entity_type, limit=1, min_score=min_fuzzy_score)
+            if results and results[0].matched_via not in {"exact", "alias"}:
+                continue
+            if not results:
+                continue
+            target = brands if entity_type == "brand" else projects if entity_type == "project" else None
+            if target is not None:
+                for entity in results:
+                    target.setdefault(entity.id, entity)
+
+
+def _entity_log(entity: ResolvedEntity) -> dict[str, object]:
+    return {
+        "type": entity.entity_type,
+        "id": entity.id,
+        "canonical": entity.canonical,
+        "via": entity.matched_via,
+        "score": entity.score,
+    }
+
+
+def missing_entities_in_sql(sql: str, resolved_entities: dict[str, Any] | None) -> list[str]:
+    """Resolved entities that have NO trace at all in the SQL.
+
+    Deliberately a presence check, not a form check: an entity counts as
+    present if its id, canonical name, or (for geo) name core appears anywhere
+    in the SQL — regardless of whether it is used as ``id =``, ``name LIKE``, a
+    JOIN, or a subquery. This keeps false positives near-zero: only an entity
+    that was completely dropped is reported. A coincidental id collision causes
+    a (safe) false negative, never a false positive.
+    """
+    if not resolved_entities or not sql:
+        return []
+    missing: list[str] = []
+    for brand in resolved_entities.get("brands") or []:
+        if not _entity_present(sql, brand):
+            missing.append(f"品牌「{brand.get('name')}」")
+    for project in resolved_entities.get("projects") or []:
+        if not _entity_present(sql, project):
+            missing.append(f"项目「{project.get('name')}」")
+    location = resolved_entities.get("location") or {}
+    finest = location.get("region") or location.get("city") or location.get("province")
+    if finest and not _geo_present(sql, finest):
+        missing.append(f"地点「{finest.get('name')}」")
+    return missing
+
+
+def _entity_present(sql: str, entity: dict[str, Any]) -> bool:
+    name = str(entity.get("name") or "")
+    if name and name in sql:
+        return True
+    entity_id = entity.get("id")
+    if entity_id is not None and re.search(rf"\b{re.escape(str(entity_id))}\b", sql):
+        return True
+    return False
+
+
+def _geo_present(sql: str, entity: dict[str, Any]) -> bool:
+    if _entity_present(sql, entity):
+        return True
+    core = _geo_core(_norm(str(entity.get("name") or "")))
+    return bool(core) and core in sql.lower()

package/src/octopus_skill/entity_dictionary.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+class EntityDictionaryCacheError(RuntimeError):
+    """Raised when the persisted entity dictionary cache cannot be used."""
+
+
+@dataclass
+class EntityDictionaryCache:
+    """Persists the entity dictionary snapshot returned by the MCP server.
+
+    Mirrors ``SchemaCache``: the payload is a JSON object that carries a
+    ``dictVersion`` field used for incremental refresh negotiation.
+    """
+
+    path: Path
+
+    def load(self) -> dict[str, Any] | None:
+        if not self.path.exists():
+            return None
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise EntityDictionaryCacheError(
+                f"Invalid entity dictionary cache JSON: {self.path}"
+            ) from exc
+        if not isinstance(data, dict):
+            raise EntityDictionaryCacheError(
+                f"Entity dictionary cache must be a JSON object: {self.path}"
+            )
+        return data
+
+    def save(self, dictionary: dict[str, Any]) -> None:
+        if not isinstance(dictionary, dict):
+            raise TypeError("dictionary must be a dict")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(dictionary, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def version(self) -> str | None:
+        dictionary = self.load()
+        if dictionary is None:
+            return None
+        version = dictionary.get("dictVersion")
+        return str(version) if version is not None else None
+
+    def is_fresh(self, max_age_minutes: int) -> bool:
+        if max_age_minutes <= 0 or not self.path.exists():
+            return False
+        age_seconds = time.time() - self.path.stat().st_mtime
+        return age_seconds <= max_age_minutes * 60