feat: support re-estimation from estimate uuids [skip-ci]

Author: yoshifuminakamura

README.md

@@ -240,7 +240,10 @@ python -m pytest tests/ -v
 - `estimate.sh` がアプリ固有の推定ロジックを実装（`programs/<code>/estimate.sh`）
 - `estimate_common.sh` が共通関数（API呼び出し、JSON出力等）を提供
 - 簡易推定と詳細推定の双方を将来的に受け入れられる設計を前提とする
-- UUID指定による再推定もサポート（`estimate_uuid` 変数でトリガー）
+- UUID指定による再推定もサポート
+  - `estimate_result_uuid` を指定すると、その estimate から `source_result_uuid` を引いて再推定
+  - `result_uuid` を指定すると、元 result を直接指定して再推定
+  - 旧 `estimate_uuid` は `result_uuid` の互換名として扱う
 
 ### 5. BenchPark統合パイプライン
 - `benchpark-bridge/config/apps.csv` で監視対象を定義

docs/cx/REESTIMATION_SPEC.md

@@ -54,9 +54,11 @@ Typical use cases include:
 
 再推定では、入力となる benchmark result を明示的に固定しなければならない。
 この識別には、少なくとも result の UUID を用いることを基本とする。
+ただし、実運用では estimate result UUID を入口にし、その estimate が保持する `source_result_uuid` から元 result を辿れることが望ましい。
 
 In re-estimation, the input benchmark result must be explicitly fixed.
 At minimum, the UUID of the result should be used as the primary identifier.
+In practical workflows, however, it is desirable to allow an estimate-result UUID as the entry point and resolve the original result through `source_result_uuid`.
 
 ### 3.2 比較可能性 / Comparability
 
@@ -98,25 +100,27 @@ It must not silently ignore missing inputs and still report a successful estimat
 
 BenchKit における再推定の典型フローは以下である。
 
-1. 利用者またはワークフローが対象 benchmark result の UUID を指定する
-2. BenchKit が UUID に対応する Result JSON を取得する
-3. 対象 app の `estimate.sh` を起動する
-4. `Estimate JSON` を生成する
-5. 生成結果を保存し、ポータルで参照可能にする
+1. 利用者またはワークフローが `estimate_result_uuid` または `result_uuid` を指定する
+2. `estimate_result_uuid` の場合、BenchKit は estimate JSON を取得し、そこから `source_result_uuid` を解決する
+3. BenchKit が対応する Result JSON を取得する
+4. 対象 app の `estimate.sh` を起動する
+5. `Estimate JSON` を生成する
+6. 生成結果を保存し、ポータルで参照可能にする
 
 The typical re-estimation flow in BenchKit is:
 
-1. a user or workflow specifies the UUID of a benchmark result
-2. BenchKit fetches the corresponding Result JSON
-3. the app-specific `estimate.sh` is invoked
-4. an `Estimate JSON` is generated
-5. the generated result is stored and made available through the portal
+1. a user or workflow specifies either an `estimate_result_uuid` or a `result_uuid`
+2. if an `estimate_result_uuid` is given, BenchKit fetches the estimate JSON and resolves `source_result_uuid`
+3. BenchKit fetches the corresponding Result JSON
+4. the app-specific `estimate.sh` is invoked
+5. an `Estimate JSON` is generated
+6. the generated result is stored and made available through the portal
 
 ## 5. 入力要件 / Input Requirements
 
 再推定では少なくとも以下を入力として扱う。
 
-- `result_uuid`
+- `estimate_result_uuid` または `result_uuid`
 - `code`
 
 必要に応じて以下を追加で与えてよい。
@@ -129,7 +133,7 @@ The typical re-estimation flow in BenchKit is:
 
 At minimum, re-estimation uses the following inputs:
 
-- `result_uuid`
+- `estimate_result_uuid` or `result_uuid`
 - `code`
 
 Optionally, the following may also be supplied:
@@ -164,7 +168,11 @@ In the current implementation, the following already exist:
 
 ### 7.1 UUID 取得 API の仕様 / UUID-Based Result Retrieval API
 
-再推定を UUID 起点で運用するには、UUID 指定で Result JSON を取得する API または同等の取得手段が必要である。
+再推定を UUID 起点で運用するには、少なくとも次の取得口が必要である。
+
+- estimate result UUID で estimate JSON を返す取得 API
+- result UUID で Result JSON を返す取得 API
+
 現時点では、再推定の shell フロー自体は存在しても、その取得口の公開仕様や認証条件は文書としてまだ十分に固定されていない。
 
 したがって、以下を明確化する必要がある。
@@ -179,7 +187,8 @@ At present, the shell-side re-estimation flow exists, but the retrieval endpoint
 
 The following therefore need to be clarified:
 
-- a retrieval API that returns Result JSON by UUID
+- a retrieval API that returns Estimate JSON by estimate-result UUID
+- a retrieval API that returns Result JSON by result UUID
 - whether authentication is required
 - how confidential results are handled
 - behavior on retrieval failure
@@ -238,7 +247,7 @@ At least the following need to be clarified:
 
 BenchKit における再推定は、少なくとも以下を満たすことが望ましい。
 
-1. UUID 指定で benchmark result を再取得できること
+1. `estimate_result_uuid` または `result_uuid` 指定で benchmark result を再取得できること
 2. app ごとの `estimate.sh` を同じ入力に対して繰り返し実行できること
 3. 再推定結果に、元 benchmark result UUID を残せること
 4. 異なる推定方式を同じ benchmark result に対して併存させられること
@@ -247,7 +256,7 @@ BenchKit における再推定は、少なくとも以下を満たすことが
 
 Re-estimation in BenchKit should preferably satisfy at least:
 
-1. the benchmark result can be re-fetched by UUID
+1. the benchmark result can be re-fetched from either `estimate_result_uuid` or `result_uuid`
 2. app-specific `estimate.sh` can be run repeatedly for the same input
 3. the re-estimation result can retain the original benchmark-result UUID
 4. different estimation methods can coexist for the same benchmark result
@@ -258,14 +267,14 @@ Re-estimation in BenchKit should preferably satisfy at least:
 
 次に候補となる実装は以下である。
 
-1. UUID 指定取得 API の仕様化と実装確認
+1. estimate/result の UUID 指定取得 API の仕様化と実装確認
 2. 再推定向けに UUID 指定取得口と認証条件を文書化する
 3. 同一 `source_result_uuid` を軸にした比較表示仕様を定義する
 4. portal から再推定を起動する要求フローを定義する
 
 Candidate next steps include:
 
-1. specify and verify the UUID-based result retrieval API
+1. specify and verify the UUID-based estimate/result retrieval APIs
 2. document the retrieval endpoint and authentication conditions for re-estimation
 3. define a display specification for comparing re-estimation results using `source_result_uuid`
 4. define a portal-driven request flow for starting re-estimation

result_server/routes/api.py

@@ -92,6 +92,38 @@ def is_valid_uuid(value):
         return False
 
 
+def _load_json_by_uuid(directory, field_path, uuid_value):
+    """指定ディレクトリから UUID に一致する JSON を探して返す。"""
+    json_files = sorted(
+        [f for f in os.listdir(directory) if f.endswith(".json")],
+        reverse=True,
+    )
+
+    for json_file in json_files:
+        path = os.path.join(directory, json_file)
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception:
+            continue
+
+        current = data
+        for key in field_path:
+            if not isinstance(current, dict):
+                current = None
+                break
+            current = current.get(key)
+
+        if current == uuid_value:
+            return data
+
+        # 互換用: ファイル名中のUUIDにもフォールバック
+        if uuid_value in json_file:
+            return data
+
+    return None
+
+
 # ==========================================
 # 新パス: /api/ingest/*
 # ==========================================
@@ -238,6 +270,44 @@ def query_result():
     abort(404, description=f"No result found for system={system}, code={code}, exp={exp}")
 
 
+@api_bp.route("/api/query/result/<uuid_value>", methods=["GET"])
+def query_result_by_uuid(uuid_value):
+    """UUID で単一 Result JSON を返す。"""
+    require_api_key()
+
+    if not is_valid_uuid(uuid_value):
+        abort(400, description="Invalid UUID")
+
+    data = _load_json_by_uuid(
+        current_app.config["RECEIVED_DIR"],
+        ["_server_uuid"],
+        uuid_value,
+    )
+    if data is None:
+        abort(404, description=f"No result found for uuid={uuid_value}")
+
+    return jsonify(data), 200
+
+
+@api_bp.route("/api/query/estimate/<uuid_value>", methods=["GET"])
+def query_estimate_by_uuid(uuid_value):
+    """UUID で単一 Estimate JSON を返す。"""
+    require_api_key()
+
+    if not is_valid_uuid(uuid_value):
+        abort(400, description="Invalid UUID")
+
+    data = _load_json_by_uuid(
+        current_app.config["ESTIMATED_DIR"],
+        ["estimate_metadata", "estimation_result_uuid"],
+        uuid_value,
+    )
+    if data is None:
+        abort(404, description=f"No estimate found for uuid={uuid_value}")
+
+    return jsonify(data), 200
+
+
 # ==========================================
 # 互換ルート (deprecated)
 # ==========================================

result_server/tests/test_api_routes.py

@@ -341,6 +341,51 @@ def test_query_missing_api_key_returns_401(self, client):
         assert resp.status_code == 401
 
 
+class TestQueryByUuid:
+    def _seed_json(self, directory, filename, data):
+        path = os.path.join(directory, filename)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+
+    def test_query_result_by_uuid(self, client, tmp_dirs):
+        received, _ = tmp_dirs
+        data = {"code": "qws", "_server_uuid": "12345678-1234-1234-1234-123456789abc"}
+        self._seed_json(received, "result_20250101_000000_12345678-1234-1234-1234-123456789abc.json", data)
+
+        resp = client.get(
+            "/api/query/result/12345678-1234-1234-1234-123456789abc",
+            headers={"X-API-Key": API_KEY},
+        )
+        assert resp.status_code == 200
+        assert resp.get_json()["code"] == "qws"
+
+    def test_query_estimate_by_uuid(self, client, tmp_dirs):
+        _, estimated = tmp_dirs
+        data = {
+            "code": "qws",
+            "estimate_metadata": {
+                "estimation_result_uuid": "87654321-4321-4321-4321-cba987654321",
+                "source_result_uuid": "12345678-1234-1234-1234-123456789abc",
+            },
+        }
+        self._seed_json(estimated, "estimate_20250101_000000_87654321-4321-4321-4321-cba987654321.json", data)
+
+        resp = client.get(
+            "/api/query/estimate/87654321-4321-4321-4321-cba987654321",
+            headers={"X-API-Key": API_KEY},
+        )
+        assert resp.status_code == 200
+        assert resp.get_json()["estimate_metadata"]["source_result_uuid"] == "12345678-1234-1234-1234-123456789abc"
+
+    def test_query_result_by_uuid_missing_api_key_returns_401(self, client):
+        resp = client.get("/api/query/result/12345678-1234-1234-1234-123456789abc")
+        assert resp.status_code == 401
+
+    def test_query_estimate_by_uuid_missing_api_key_returns_401(self, client):
+        resp = client.get("/api/query/estimate/87654321-4321-4321-4321-cba987654321")
+        assert resp.status_code == 401
+
+
 # ============================================================
 # ヘルパー
 # ============================================================

scripts/fetch_result_by_uuid.sh

@@ -3,19 +3,47 @@
 # Saves the result to results/result0.json for subsequent estimation.
 #
 # Required CI variables:
-#   estimate_uuid  - UUID of the benchmark result to fetch
+#   result_uuid          - UUID of the benchmark result to fetch directly
+#   estimate_result_uuid - UUID of the estimate result to re-estimate from
+#   estimate_uuid        - legacy alias for result_uuid
 #   code           - Program code name (e.g., "qws")
 #   RESULT_SERVER  - Base URL of the result server
 set -euo pipefail
 
-if [[ -z "${estimate_uuid:-}" || -z "${code:-}" ]]; then
-  echo "ERROR: Both estimate_uuid and code must be specified" >&2
+if [[ -z "${code:-}" ]]; then
+  echo "ERROR: code must be specified" >&2
   exit 1
 fi
 
 mkdir -p results
 
-echo "Fetching result for UUID: $estimate_uuid"
-curl --fail -sS -o "results/result0.json" \
-  "${RESULT_SERVER}/api/result/${estimate_uuid}"
+resolved_result_uuid="${result_uuid:-}"
+
+if [[ -z "$resolved_result_uuid" && -n "${estimate_result_uuid:-}" ]]; then
+  echo "Fetching estimate for UUID: $estimate_result_uuid"
+  curl --fail -sS -H "X-API-Key: ${RESULT_SERVER_KEY}" \
+    -o "results/source_estimate.json" \
+    "${RESULT_SERVER}/api/query/estimate/${estimate_result_uuid}"
+
+  resolved_result_uuid="$(jq -r '.estimate_metadata.source_result_uuid // empty' results/source_estimate.json)"
+  if [[ -z "$resolved_result_uuid" ]]; then
+    echo "ERROR: source_result_uuid not found in estimate ${estimate_result_uuid}" >&2
+    exit 1
+  fi
+  echo "Resolved source result UUID: $resolved_result_uuid"
+fi
+
+if [[ -z "$resolved_result_uuid" && -n "${estimate_uuid:-}" ]]; then
+  echo "WARNING: estimate_uuid is deprecated; use result_uuid or estimate_result_uuid" >&2
+  resolved_result_uuid="$estimate_uuid"
+fi
+
+if [[ -z "$resolved_result_uuid" ]]; then
+  echo "ERROR: one of result_uuid, estimate_result_uuid, or legacy estimate_uuid must be specified" >&2
+  exit 1
+fi
+
+echo "Fetching result for UUID: $resolved_result_uuid"
+curl --fail -sS -H "X-API-Key: ${RESULT_SERVER_KEY}" -o "results/result0.json" \
+  "${RESULT_SERVER}/api/query/result/${resolved_result_uuid}"
 echo "Fetched result to results/result0.json"

scripts/generate_estimate_from_uuid.sh

@@ -5,16 +5,18 @@
 # of a specific benchmark result identified by UUID.
 #
 # Required CI variables:
-#   estimate_uuid  - UUID of the benchmark result to re-estimate
+#   result_uuid          - UUID of the benchmark result to re-estimate directly
+#   estimate_result_uuid - UUID of the estimate result to re-estimate from
+#   estimate_uuid        - legacy alias for result_uuid
 #   code           - Program code name (e.g., "qws")
 #
 # Output: .gitlab-ci.estimate.yml with fetch → estimate → send_estimate stages
 
 set -euo pipefail
 
 # Validate required variables
-if [[ -z "${estimate_uuid:-}" ]]; then
-  echo "ERROR: estimate_uuid must be specified" >&2
+if [[ -z "${result_uuid:-}" && -z "${estimate_result_uuid:-}" && -z "${estimate_uuid:-}" ]]; then
+  echo "ERROR: result_uuid or estimate_result_uuid must be specified" >&2
   exit 1
 fi
 
@@ -25,7 +27,7 @@ fi
 
 OUTPUT_FILE=".gitlab-ci.estimate.yml"
 
-echo "Generating estimate pipeline YAML for UUID: $estimate_uuid, code: $code"
+echo "Generating estimate pipeline YAML for code: $code"
 
 cat > "$OUTPUT_FILE" <<YAML
 stages:
@@ -37,7 +39,7 @@ fetch_result:
   stage: fetch
   tags: [fncx-curl-jq]
   script:
-    - echo "Fetching result for UUID: \$estimate_uuid"
+    - echo "Fetching re-estimation input"
     - bash scripts/fetch_result_by_uuid.sh
   artifacts:
     paths: