instance-repo 1.4.7__tar.gz → 1.4.8.dev0__tar.gz

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.4.7
+Version: 1.4.8.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/__init__.py

@@ -20,7 +20,7 @@ from .errors import (
     RegistrationFailed, TransportError,
 )
 
-__version__ = "1.4.7"
+__version__ = "1.4.8.dev0"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/clients/config.py

@@ -151,18 +151,21 @@ def normalize_storage_env(storage_env: str | None) -> str:
     return (storage_env or "").strip().lower()
 
 
-def business_metadata_model(metadata_model: str | None) -> str:
-    """Normalize a normal business entry to the only supported model.
+def business_metadata_model(metadata_model: str | None, *,
+                            allow_version_first: bool = False) -> str:
+    """Normalize a business model, optionally allowing explicit legacy reads.
 
     ``None``, the empty compatibility value, and ``split_first`` are accepted.
-    ``version_first`` remains available only through low-level ``Layout`` and
-    legacy discovery helpers, never through Repo/client business I/O.
+    ``version_first`` remains rejected by normal business I/O unless the caller
+    explicitly opts into legacy metadata addressing.
     """
     from ..errors import SchemaError
 
     if metadata_model is not None and not isinstance(metadata_model, str):
         raise SchemaError("metadata_model must be a string or None")
     requested = (metadata_model or "").strip()
+    if allow_version_first and requested == "version_first":
+        return requested
     if requested not in ("", "split_first"):
         if requested == "version_first":
             raise SchemaError(

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/clients/instances.py

@@ -32,17 +32,169 @@ logger = logging.getLogger(__name__)
 
 def _registry_overrides(environment: str | None,
                         metadata_model: str | None,
-                        profile_model: str | None = None) -> dict:
+                        profile_model: str | None = None, *,
+                        allow_version_first: bool = False) -> dict:
     """Build explicit split-first registry parameters before any registry I/O."""
     overrides: dict = {
         "metadata_model": business_metadata_model(
-            metadata_model if metadata_model is not None else profile_model),
+            metadata_model if metadata_model is not None else profile_model,
+            allow_version_first=allow_version_first),
     }
     if environment is not None:
         overrides["environment"] = environment
     return overrides
 
 
+_MAX_TAG_FILTER_KEYS = 64
+_MAX_TAG_FILTER_VALUES = 64
+
+
+def _validate_tag_key(key: str) -> str:
+    if not isinstance(key, str):
+        raise SchemaError("tag keys must be strings")
+    key = key.strip()
+    if not key:
+        raise SchemaError("tag key must not be empty or whitespace-only")
+    if "." in key or "$" in key:
+        raise SchemaError(
+            f"invalid tag key {key!r}: keys must not contain '.' or "
+            f"'$' (server rejects them)")
+    return key
+
+
+def _copy_tags(tags: dict[str, str | list[str]], *,
+               allow_empty: bool = False) -> dict[str, str | list[str]]:
+    if not isinstance(tags, dict):
+        raise SchemaError("tags must be an object of string or string-array values")
+    copied: dict[str, str | list[str]] = {}
+    for raw_key, value in tags.items():
+        key = _validate_tag_key(raw_key)
+        if key in copied:
+            raise SchemaError(f"duplicate tag key {key!r} after normalization")
+        if isinstance(value, str):
+            value = value.strip()
+            if not value and not allow_empty:
+                raise SchemaError(
+                    f"invalid value for tag {key!r}: scalar must be non-empty")
+            copied[key] = value
+        elif isinstance(value, list) and all(isinstance(item, str) for item in value):
+            copied[key] = _normalize_tag_values(value, allow_empty=allow_empty)
+        else:
+            raise SchemaError(
+                f"invalid value for tag {key!r}: expected a string or a list of strings")
+    return copied
+
+
+def _effective_tags(tags: dict[str, str | list[str]]) -> dict[str, str | list[str]]:
+    """Project tags through the server's write normalization for no-op detection."""
+    normalized = _copy_tags(tags, allow_empty=True)
+    return {key: value for key, value in normalized.items()
+            if not isinstance(value, list) or value}
+
+
+def _clean_legacy_tags(
+        tags: dict[str, str | list[str]]) -> dict[str, str | list[str]]:
+    """Remove legacy empty scalars and array items from an internal PATCH map."""
+    normalized = _copy_tags(tags, allow_empty=True)
+    cleaned: dict[str, str | list[str]] = {}
+    for key, value in normalized.items():
+        if isinstance(value, str):
+            if value:
+                cleaned[key] = value
+        else:
+            cleaned[key] = [item for item in value if item]
+    return cleaned
+
+
+def _normalize_tag_values(values: list[str], *,
+                          allow_empty: bool = False) -> list[str]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        value = value.strip()
+        if (value or allow_empty) and value not in seen:
+            seen.add(value)
+            normalized.append(value)
+    return normalized
+
+
+def _parse_tag_filters_csv(tags: str) -> dict[str, str]:
+    """Parse legacy CSV using the server's skip/trim/duplicate-key rules."""
+    parsed: dict[str, str] = {}
+    for pair in tags.split(","):
+        key, separator, value = pair.partition(":")
+        key, value = key.strip(), value.strip()
+        if not separator or not key or not value:
+            continue
+        if key in parsed:
+            raise SchemaError(f"duplicate tag filter key {key!r}")
+        parsed[key] = value
+    return _normalize_tag_filters(parsed)
+
+
+def _normalize_tag_filters(
+        tags: dict[str, str | dict[str, list[str]]] | str | None) -> dict:
+    """Return the single normalized filter representation used by both paths."""
+    if tags is None:
+        return {}
+    if isinstance(tags, str):
+        return _parse_tag_filters_csv(tags)
+    if not isinstance(tags, dict):
+        raise SchemaError("tags must be a dict, legacy CSV string, or None")
+    if len(tags) > _MAX_TAG_FILTER_KEYS:
+        raise SchemaError(f"tag filters must contain at most {_MAX_TAG_FILTER_KEYS} keys")
+    normalized: dict = {}
+    for raw_key, condition in tags.items():
+        key = _validate_tag_key(raw_key)
+        if key in normalized:
+            raise SchemaError(f"duplicate tag filter key {key!r} after normalization")
+        if isinstance(condition, str):
+            value = condition.strip()
+            if not value:
+                raise SchemaError(f"tag filter {key!r} requires a non-empty value")
+            normalized[key] = value
+            continue
+        if not isinstance(condition, dict) or len(condition) != 1:
+            raise SchemaError(
+                f"invalid filter for tag {key!r}: expected a string or one any/all object")
+        operation, values = next(iter(condition.items()))
+        if (operation not in ("any", "all") or not isinstance(values, list)
+                or not all(isinstance(value, str) for value in values)):
+            raise SchemaError(
+                f"invalid filter for tag {key!r}: any/all requires a string array")
+        if len(values) > _MAX_TAG_FILTER_VALUES:
+            raise SchemaError(
+                f"tag filter {key!r} must contain at most "
+                f"{_MAX_TAG_FILTER_VALUES} raw values")
+        values = _normalize_tag_values(values)
+        if not values:
+            raise SchemaError(
+                f"invalid filter for tag {key!r}: any/all requires a nonempty string array")
+        normalized[key] = {operation: values}
+    return normalized
+
+
+def _matches_tag_filters(instance_tags: dict, filters: dict) -> bool:
+    for key, condition in filters.items():
+        actual = instance_tags.get(key)
+        if isinstance(actual, str):
+            actual_values = [actual]
+        elif isinstance(actual, list):
+            actual_values = list(actual)
+        else:
+            actual_values = []
+        if isinstance(condition, str):
+            if condition not in actual_values:
+                return False
+            continue
+        operation, expected = next(iter(condition.items()))
+        if operation == "any" and not any(value in actual_values for value in expected):
+            return False
+        if operation == "all" and not all(value in actual_values for value in expected):
+            return False
+    return True
+
+
 def _validate_custom_asset_rel(rel: str) -> None:
     """白名单校验 custom 资产相对路径（防元数据被篡改造成 pull 路径穿越）。
 
@@ -225,7 +377,8 @@ class InstancesClient:
         # 保持缺省调用形态与历史一致,避免破坏既有实现。
         overrides = _registry_overrides(
             environment, metadata_model,
-            getattr(self._p, "metadata_model", None))
+            getattr(self._p, "metadata_model", None),
+            allow_version_first=True)
         try:
             result = self._reg.get(
                 dataset, version, instance_id, split, **overrides)
@@ -271,7 +424,7 @@ class InstancesClient:
     def list_paged(self, dataset: str, version: str = "", *,
                    split: str | None = None, q: str | None = None,
                    instance_id: str | None = None,
-                   tags: dict[str, str] | str | None = None,
+                   tags: dict[str, str | dict[str, list[str]]] | str | None = None,
                    difficulty: str | None = None,
                    page: int = 1, page_size: int = 50,
                    environment: str | None = None,
@@ -281,9 +434,10 @@ class InstancesClient:
 
         与 :meth:`list` 的自动翻页取全量互补：精确控制页码/过滤/搜索。
         参数逐项对齐服务端（无 SDK 发明项）：``q`` 是 instance_id **子串**
-        模糊搜索（不区分大小写）；``instance_id`` 精确等值；``tags`` dict 或
-        CSV（"k1:v1,k2:v2"，key 含 ``.``/``$`` 服务端拒绝——SDK 前置校验并
-        给出修复提示）；``difficulty`` easy/medium/hard。**服务端无排序参数**
+        模糊搜索（不区分大小写）；``instance_id`` 精确等值；``tags`` dict 编码为
+        JSON object（值为 string、``{"any": [...]}`` 或 ``{"all": [...]}``），
+        旧 CSV 字符串（"k1:v1,k2:v2"）保持兼容；key 含 ``.``/``$`` 前置拒绝。
+        ``difficulty`` easy/medium/hard。**服务端无排序参数**
         （固定 instance_id asc），SDK 不暴露。
 
         **OSS 回退**：当 ``TransportError(biz_code=92001)`` 或 ``92023`` 时回退到 OSS 存储层，
@@ -296,20 +450,15 @@ class InstancesClient:
         if (difficulty or "").strip() and difficulty.strip() not in ("easy", "medium", "hard"):
             raise SchemaError(
                 f"invalid difficulty {difficulty!r}; must be easy/medium/hard")
-        # tags 归一：dict → CSV；str 原样（仍校验 key 合法性）。
+        # 控制面编码与 OSS 回退共享同一份归一化结果，避免两条路径语义漂移。
+        normalized_filters = _normalize_tag_filters(tags)
         tags_q = ""
-        if tags:
-            if isinstance(tags, dict):
-                pairs = [f"{k}:{v}" for k, v in tags.items()]
-            else:
-                pairs = [p for p in str(tags).split(",") if p.strip()]
-            for p in pairs:
-                key = p.split(":", 1)[0]
-                if not key or "." in key or "$" in key:
-                    raise SchemaError(
-                        f"invalid tag key {key!r}: keys must not contain '.' or "
-                        f"'$' (server rejects them)")
-            tags_q = ",".join(pairs)
+        if isinstance(tags, dict) and normalized_filters:
+            tags_q = json.dumps(
+                normalized_filters, ensure_ascii=False, separators=(",", ":"))
+        elif isinstance(tags, str) and normalized_filters:
+            tags_q = ",".join(f"{key}:{value}"
+                              for key, value in normalized_filters.items())
         params: list[tuple[str, str]] = [("dataset_name", dataset.strip())]
         if (version or "").strip():
             params.append(("version", version.strip()))
@@ -346,7 +495,8 @@ class InstancesClient:
                 return self._discover_instances_paged(
                     dataset, version, split,
                     q=q, instance_id=instance_id,
-                    tags=tags, difficulty=difficulty,
+                    tags=normalized_filters,
+                    difficulty=difficulty,
                     page=page, page_size=page_size)
             raise
         rows = data.get("instances", data) if isinstance(data, dict) else data
@@ -371,26 +521,30 @@ class InstancesClient:
         return req == derived
 
     def _discover_instances(self, dataset: str, version: str,
-                            split: str | None = None) -> list[DatasetInstance]:
+                            split: str | None = None, *,
+                            read_content: bool = False) -> list[DatasetInstance]:
         """OSS 回退的 instances.list — 从 OSS 列举指定 version/split 下的实例。"""
         from ..store.oss_discovery import build_synthetic_instances
         return build_synthetic_instances(
             self._content, dataset, version, split,
-            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'))
+            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'),
+            read_content=read_content)
 
     def _discover_instance(self, dataset: str, version: str,
                            instance_id: str,
-                           split: str | None = None) -> DatasetInstance | None:
+                           split: str | None = None, *,
+                           read_content: bool = False) -> DatasetInstance | None:
         """OSS 回退的 instances.get — 精确查找单个实例。"""
         from ..store.oss_discovery import build_synthetic_instance
         return build_synthetic_instance(
             self._content, dataset, version, instance_id, split,
-            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'))
+            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'),
+            read_content=read_content)
 
     def _discover_instances_paged(
         self, dataset: str, version: str, split: str | None, *,
         q: str | None, instance_id: str | None,
-        tags: dict[str, str] | str | None,
+        tags: dict[str, str | dict[str, list[str]]],
         difficulty: str | None,
         page: int, page_size: int,
     ) -> "PagedResult":
@@ -400,47 +554,32 @@ class InstancesClient:
         """
         from ..store.oss_discovery import _in_memory_paged
 
-        # 优化：instance_id 精确匹配时直接 GET，不列举全量
+        # list_paged 已归一化并共享同一份 filters，这里不再重复校验/归一化。
+        tags_dict = tags or {}
+        normalized_difficulty = (difficulty or "").strip()
+        # tags/difficulty 过滤需要 GetObject；普通过滤/列表保持 list-only 零新增读取。
+        read_content = bool(tags_dict) or bool(normalized_difficulty)
         if instance_id:
-            inst = self._discover_instance(dataset, version, instance_id, split)
+            inst = self._discover_instance(
+                dataset, version, instance_id, split, read_content=read_content)
             items: list[DatasetInstance] = [inst] if inst else []
         else:
-            items = self._discover_instances(dataset, version, split)
+            items = self._discover_instances(
+                dataset, version, split, read_content=read_content)
 
         # 客户端过滤
         if q:
             q_lower = q.lower()
             items = [i for i in items
                      if q_lower in i.instance_id.lower()]
-        if difficulty:
-            items = [i for i in items
-                     if i.difficulty == difficulty]
-        if tags:
-            tags_dict = (
-                tags if isinstance(tags, dict)
-                else self._parse_tags_csv(tags)
-            )
+        if normalized_difficulty:
             items = [i for i in items
-                     if all(i.tags.get(k) == v
-                            for k, v in tags_dict.items())]
+                     if i.difficulty == normalized_difficulty]
+        if tags_dict:
+            items = [i for i in items if _matches_tag_filters(i.tags, tags_dict)]
 
         return _in_memory_paged(items, int(page), int(page_size))
 
-    @staticmethod
-    def _parse_tags_csv(tags_str: str) -> dict[str, str]:
-        """解析 ``"k1:v1,k2:v2"`` 格式的 tags CSV 字符串为 dict。"""
-        result: dict[str, str] = {}
-        for pair in str(tags_str).split(","):
-            pair = pair.strip()
-            if not pair:
-                continue
-            parts = pair.split(":", 1)
-            if len(parts) == 2:
-                result[parts[0]] = parts[1]
-            else:
-                result[parts[0]] = ""
-        return result
-
     # ── 实例目录/文件列举（GET /datasets/objects）──────────────────
 
     def list_objects(self, dataset: str, instance_id: str,
@@ -703,14 +842,149 @@ class InstancesClient:
         if failure is not None:
             raise failure from None
 
+    def _read_tag_record(self, dataset: str, version: str, instance_id: str, *,
+                         split: str | None, environment: str | None,
+                         metadata_model: str | None) -> DatasetInstance:
+        record = self.get(
+            dataset, version, instance_id, split=split,
+            environment=environment, metadata_model=metadata_model,
+            fallback_to_oss=False)
+        if record is None:
+            raise SchemaError(f"instance {instance_id!r} not found")
+        return record
+
+    def _read_tags(self, dataset: str, version: str, instance_id: str, *,
+                   split: str | None, environment: str | None,
+                   metadata_model: str | None) -> dict[str, str | list[str]]:
+        record = self._read_tag_record(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+        return _copy_tags(record.tags, allow_empty=True)
+
+    def list_tags(self, dataset: str, version: str, instance_id: str, *,
+                  split: str | None = None, environment: str | None = None,
+                  metadata_model: str | None = None) -> dict[str, str | list[str]]:
+        """Read the complete tag map through the existing metadata/RBAC path."""
+        return self._read_tags(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+
+    def set_tags(self, dataset: str, version: str, instance_id: str,
+                 tags: dict[str, str | list[str]], *, split: str | None = None,
+                 environment: str | None = None,
+                 metadata_model: str | None = None) -> DatasetInstance:
+        """Set keys in the complete tag map, preserving every unspecified key.
+
+        This is a non-atomic read-modify-write of the whole map. A concurrent
+        writer can be overwritten by this call's later whole-map update.
+        """
+        normalized = _copy_tags(tags)
+        record = self._read_tag_record(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+        current = _copy_tags(record.tags, allow_empty=True)
+        merged = dict(current)
+        merged.update(normalized)
+        if _effective_tags(merged) == _effective_tags(current):
+            return record
+        patch_tags = _clean_legacy_tags(merged)
+        return self.update(
+            dataset, version, instance_id, split=split, tags=patch_tags,
+            environment=environment, metadata_model=metadata_model)
+
+    def append_tags(self, dataset: str, version: str, instance_id: str,
+                    tags: dict[str, str | list[str]], *, split: str | None = None,
+                    environment: str | None = None,
+                    metadata_model: str | None = None) -> DatasetInstance:
+        """Append unique values, converting scalars only when a value is added."""
+        normalized = _copy_tags(tags)
+        record = self._read_tag_record(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+        current_tags = _copy_tags(record.tags, allow_empty=True)
+        merged = dict(current_tags)
+        for key, added in normalized.items():
+            current = merged.get(key)
+            values = ([current] if isinstance(current, str)
+                      else list(current) if isinstance(current, list) else [])
+            has_new_value = False
+            for value in [added] if isinstance(added, str) else added:
+                if value not in values:
+                    values.append(value)
+                    has_new_value = True
+            if has_new_value:
+                merged[key] = values
+        if _effective_tags(merged) == _effective_tags(current_tags):
+            return record
+        patch_tags = _clean_legacy_tags(merged)
+        return self.update(
+            dataset, version, instance_id, split=split, tags=patch_tags,
+            environment=environment, metadata_model=metadata_model)
+
+    def remove_tags(self, dataset: str, version: str, instance_id: str,
+                    tags: dict[str, str | list[str]], *, split: str | None = None,
+                    environment: str | None = None,
+                    metadata_model: str | None = None) -> DatasetInstance:
+        """Remove values by non-atomic whole-map replacement; arrays stay arrays."""
+        normalized = _copy_tags(tags, allow_empty=True)
+        record = self._read_tag_record(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+        current_tags = _copy_tags(record.tags, allow_empty=True)
+        merged = dict(current_tags)
+        for key, removed in normalized.items():
+            if key not in merged:
+                continue
+            current = merged[key]
+            current_is_array = isinstance(current, list)
+            values = list(current) if current_is_array else [current]
+            removed_values = [removed] if isinstance(removed, str) else removed
+            remaining = [value for value in values if value not in removed_values]
+            if not remaining:
+                merged.pop(key)
+            else:
+                merged[key] = remaining if current_is_array else remaining[0]
+        if _effective_tags(merged) == _effective_tags(current_tags):
+            return record
+        patch_tags = _clean_legacy_tags(merged)
+        return self.update(
+            dataset, version, instance_id, split=split, tags=patch_tags,
+            environment=environment, metadata_model=metadata_model)
+
+    def clear_tags(self, dataset: str, version: str, instance_id: str,
+                   keys: list[str], *, split: str | None = None,
+                   environment: str | None = None,
+                   metadata_model: str | None = None) -> DatasetInstance:
+        """Delete complete keys using non-atomic whole-map replacement."""
+        if isinstance(keys, (str, bytes)):
+            raise SchemaError("clear_tags keys must be an iterable of strings")
+        try:
+            validated_keys = [_validate_tag_key(key) for key in keys]
+        except TypeError as exc:
+            raise SchemaError("clear_tags keys must be an iterable of strings") from exc
+        record = self._read_tag_record(
+            dataset, version, instance_id, split=split, environment=environment,
+            metadata_model=metadata_model)
+        current = _copy_tags(record.tags, allow_empty=True)
+        merged = dict(current)
+        for key in validated_keys:
+            merged.pop(key, None)
+        if _effective_tags(merged) == _effective_tags(current):
+            return record
+        patch_tags = _clean_legacy_tags(merged)
+        return self.update(
+            dataset, version, instance_id, split=split, tags=patch_tags,
+            environment=environment, metadata_model=metadata_model)
+
     def update(self, dataset: str, version: str, instance_id: str, *,
                split: str | None = None, dataset_split_id: str | None = None,
                manifest: list[dict] | None = None,
-               tags: dict[str, str] | None = None,
+               tags: dict[str, str | list[str]] | None = None,
                difficulty: str | None = None,
                docker_image: str | None = None,
                extend_meta: dict | None = None,
-               environment: str | None = None) -> DatasetInstance:
+               environment: str | None = None,
+               metadata_model: str | None = None) -> DatasetInstance:
         """更新实例元数据（``PATCH /datasets/instances/detail``，不动 OSS 字节）。
 
         服务端 body 白名单（严格解析，未知字段 400）：``manifest``（整体替换，
@@ -720,14 +994,15 @@ class InstancesClient:
         **至少一项必填**（SDK 前置校验）。
 
         正常业务固定 split_first，使用 ``dataset_split_id`` 或
-        dataset+version+split+instance_id 寻址。
+        dataset+version+split+instance_id 寻址。``metadata_model=None`` 保持
+        split_first；显式 ``version_first`` 可读取并更新历史布局记录。
         """
         from urllib.parse import quote
         body: dict = {}
         if manifest is not None:
             body["manifest"] = manifest
         if tags is not None:
-            body["tags"] = tags
+            body["tags"] = _copy_tags(tags)
         if difficulty is not None:
             if difficulty not in ("", "easy", "medium", "hard"):
                 raise SchemaError(
@@ -762,7 +1037,9 @@ class InstancesClient:
             env = (getattr(self._p, "dataset_environment", "") or "").strip()
         if env:
             q += f"&environment={quote(env, safe='')}"
-        q += "&metadata_model=split_first"
+        model = business_metadata_model(
+            metadata_model, allow_version_first=True)
+        q += f"&metadata_model={quote(model, safe='')}"
         data = self._t.patch(f"{self._BASE}/detail?{q}", body)
         return DatasetInstance.from_dict(data) if isinstance(data, dict) else DatasetInstance(
             instance_id=instance_id, dataset=dataset, dataset_version=version or "")
@@ -1949,9 +2226,13 @@ class InstancesClient:
 def _tags(metadata: dict) -> dict:
     t = metadata.get("tags", {})
     if isinstance(t, dict):
-        return {str(k): str(v) for k, v in t.items()}
+        return _copy_tags(t)
+    # 与 DatasetInstance.from_dict 的旧读取口径一致：顶层 []string 不再猜测成 map。
     if isinstance(t, list):
-        return {str(v): "" for v in t}
+        logger.warning(
+            "legacy top-level tags array is ignored; use a tags map with "
+            "string or string-array values instead")
+        return {}
     return {}
 
 

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/models.py

@@ -218,7 +218,7 @@ class DatasetInstance:
     split: str = "default"
     id: str | None = None
     manifest: list[ManifestEntry] = field(default_factory=list)
-    tags: dict[str, str] = field(default_factory=dict)
+    tags: dict[str, str | list[str]] = field(default_factory=dict)
     difficulty: str | None = None
     docker_image: str | None = None
     extend_meta: dict[str, str] = field(default_factory=dict)

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/store/oss_discovery.py

@@ -361,12 +361,12 @@ def _warn_if_truncated(info: OssDatasetLevelInfo, dataset: str, max_versions: in
 # JSON reading helper
 # ---------------------------------------------------------------------------
 
-def _read_json_object(content_store, key: str) -> dict:
-    """Best-effort read and parse of a JSON object from OSS.
+def _read_json_object(content_store, key: str, *, required: bool = False) -> dict:
+    """Read a JSON object; ``required=True`` never hides read/parse failures.
 
-    Performs a HEAD check first: if ``Content-Length`` exceeds 10 MB the object
-    is skipped (returns ``{}``) to prevent OOM on malformed uploads.  Any other
-    failure (network, parse error, missing key) also returns ``{}``.
+    Best-effort discovery retains the historical empty-object fallback. Tag-filtered
+    discovery uses ``required=True`` so missing GetObject permission, oversized data,
+    network errors and malformed JSON cannot be misreported as "no match".
     """
     try:
         # Use the internal _execute_oss to do a HEAD and check size.
@@ -375,6 +375,10 @@ def _read_json_object(content_store, key: str) -> dict:
             head = bucket.head_object(key)
             content_length = getattr(head, "content_length", 0)
             if content_length and content_length > _MAX_JSON_BYTES:
+                if required:
+                    raise TransportError(
+                        f"required instance metadata JSON {key!r} exceeds "
+                        f"{_MAX_JSON_BYTES} bytes (content_length={content_length})")
                 logger.warning(
                     "Skipping oversized JSON object %s (%d bytes)",
                     key, content_length,
@@ -389,15 +393,35 @@ def _read_json_object(content_store, key: str) -> dict:
         return content_store._execute_oss(
             _OperationIntent.DOWNLOAD, key, None, _head_and_read)
     except PrivateNetworkRequired:
+        if required:
+            raise
         logger.warning(
             "Cannot read instance metadata JSON (private network required): %s",
             key)
         return {}
     except Exception:
+        if required:
+            raise
         logger.debug("Failed to read JSON object %s", key, exc_info=True)
         return {}
 
 
+def _apply_synthetic_content(inst: DatasetInstance, data: dict) -> None:
+    """Reuse DatasetInstance's read normalization, including legacy tags handling."""
+    parsed = DatasetInstance.from_dict({
+        **data,
+        "instance_id": inst.instance_id,
+        "dataset": inst.dataset,
+        "dataset_version": inst.dataset_version,
+        "split": inst.split,
+        "registered": False,
+    })
+    inst.tags = parsed.tags
+    inst.difficulty = parsed.difficulty
+    inst.docker_image = parsed.docker_image
+    inst.extend_meta = parsed.extend_meta
+
+
 # ---------------------------------------------------------------------------
 # Synthetic builders
 # ---------------------------------------------------------------------------
@@ -544,12 +568,9 @@ def build_synthetic_instances(
             registered=False,
         )
         if read_content:
-            data = _read_json_object(content_store, key)
+            data = _read_json_object(content_store, key, required=True)
             if data:
-                inst.tags = data.get("tags", {})
-                inst.difficulty = data.get("difficulty")
-                inst.docker_image = data.get("docker_image")
-                inst.extend_meta = data.get("extend_meta", {})
+                _apply_synthetic_content(inst, data)
         instances.append(inst)
 
     return instances
@@ -705,6 +726,8 @@ def build_synthetic_instance(
         keys = content_store.list_objects(
             parent, list_only=True, dataset=dataset)
     except Exception:  # noqa: BLE001
+        if read_content:
+            raise
         return None
 
     if key not in keys:
@@ -725,11 +748,8 @@ def build_synthetic_instance(
         except Exception:  # noqa: BLE001, S110
             pass  # best-effort：manifest 枚举失败不阻断实例返回
     if read_content:
-        data = _read_json_object(content_store, key)
+        data = _read_json_object(content_store, key, required=True)
         if data:
-            inst.tags = data.get("tags", {})
-            inst.difficulty = data.get("difficulty")
-            inst.docker_image = data.get("docker_image")
-            inst.extend_meta = data.get("extend_meta", {})
+            _apply_synthetic_content(inst, data)
 
     return inst

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo/store/registry.py

@@ -65,7 +65,8 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
     def _q(self, dataset: str, version: str, split: str | None = None,
            instance_id: str | None = None, *,
            environment: str | None = None,
-           metadata_model: str | None = None) -> str:
+           metadata_model: str | None = None,
+           allow_version_first: bool = False) -> str:
         """读路径查询串：与写路径（ingest）对称下发 metadata_model 与 environment。
 
         两个字段都**必须**对称：写路径由 storage_env 派生 environment（dev→pre）写入 pre
@@ -80,7 +81,8 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
         """
         requested_model = (self._metadata_model if metadata_model is None
                            else metadata_model)
-        model = business_metadata_model(requested_model)
+        model = business_metadata_model(
+            requested_model, allow_version_first=allow_version_first)
         env = (self._environment if environment is None else environment).strip()
         base = _q(dataset, version, split, instance_id,
                   keep_default_split=(model == "split_first"))
@@ -157,9 +159,11 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
         92001。只吞前者：数据集名拼错必须照常报错，否则会被静默当成"没有这个实例"。
         """
         try:
-            data = self._t.get(
-                f"{self._BASE}/detail?"
-                f"{self._q(dataset, version, split, instance_id, environment=environment, metadata_model=metadata_model)}")
+            query = self._q(
+                dataset, version, split, instance_id,
+                environment=environment, metadata_model=metadata_model,
+                allow_version_first=True)
+            data = self._t.get(f"{self._BASE}/detail?{query}")
         except TransportError as e:
             if e.status == 404 and e.biz_code == CODE_INSTANCE_NOT_FOUND:
                 return None

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/instance_repo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.4.7
+Version: 1.4.8.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.4.7 → instance_repo-1.4.8.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.4.7"
+version = "1.4.8.dev0"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"