feat: store estimation inputs for re-estimation [code:qws] [system:MiyabiG]

Author: yoshifuminakamura

docs/cx/REESTIMATION_SPEC.md

@@ -164,6 +164,19 @@ In the current implementation, the following already exist:
 - a distinction between `requested_estimation_package` and the actually applied `estimation_package`
 - final-state applicability recording through `applicable`, `partially_applicable`, `fallback`, and `not_applicable`
 
+現時点では、re-estimation で再取得できるのは source result JSON までであり、
+server 側に保存された detailed estimation-input artifact の復元はまだ未実装である。
+そのため現状では、
+
+- artifact 不要な lightweight 再推定は成立しうる
+- artifact を要求する detailed 再推定は `not_applicable` で終わりうる
+
+At present, re-estimation can re-fetch the source result JSON itself, but restoration of stored detailed estimation-input artifacts is not yet implemented.
+Therefore:
+
+- lightweight or artifact-free re-estimation may succeed
+- detailed re-estimation that depends on missing artifacts may terminate as `not_applicable`
+
 ## 7. 現行実装と仕様のギャップ / Gaps Between Current Implementation and the Intended Specification
 
 ### 7.1 UUID 取得 API の仕様 / UUID-Based Result Retrieval API
@@ -262,6 +275,23 @@ Re-estimation in BenchKit should preferably satisfy at least:
 4. different estimation methods can coexist for the same benchmark result
 5. lightweight and detailed estimation can be compared along the same comparison axis
 6. insufficient inputs can be reported explicitly as not applicable, fallback, or re-measurement required
+7. detailed re-estimation should be able to restore estimation-input artifacts associated with the source result
+
+## 8.1 estimation input artifact の復元 / Restoration of Estimation Input Artifacts
+
+当面の再推定では、artifact 復元を次の流れで扱う。
+
+1. `estimate_result_uuid` から開始する場合は、estimate JSON から `source_result_uuid` を解決する
+2. `result_uuid` から開始する場合は、そのまま source result JSON を取得する
+3. `received_estimation_inputs/<result-stem>/` が存在する場合は、その内容を `results/estimation_inputs/` に復元する
+4. server 側に estimation input artifact が無い場合は、artifact 不要な推定のみを許可し、必要な推定は `not_applicable` とする
+
+Near-term restoration should follow this flow:
+
+1. if starting from `estimate_result_uuid`, resolve `source_result_uuid` from the estimate JSON
+2. fetch the source result JSON
+3. if `received_estimation_inputs/<result-stem>/` exists, restore its contents into `results/estimation_inputs/`
+4. if no stored estimation inputs exist, allow only methods that do not require them; otherwise terminate as `not_applicable`
 
 ## 9. 次の実装候補 / Next Implementation Candidates
 
@@ -276,5 +306,6 @@ Candidate next steps include:
 
 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
+3. persist estimation-input artifacts under `received_estimation_inputs/` and restore them during re-estimation fetch
+4. define a display specification for comparing re-estimation results using `source_result_uuid`
+5. define a portal-driven request flow for starting re-estimation

result_server/app.py

@@ -79,13 +79,19 @@ def create_app(prefix="", base_dir=None):
     base_issuer = os.environ.get("TOTP_ISSUER", "BenchKit")
     app.config["TOTP_ISSUER"] = f"{base_issuer}-Dev" if prefix == "/dev" else base_issuer
 
-    # make dir: received & estimated_results
+    # make dir: received, received_padata, received_estimation_inputs & estimated_results
     received_dir = os.path.join(base_dir, "received")
+    received_padata_dir = os.path.join(base_dir, "received_padata")
+    received_estimation_inputs_dir = os.path.join(base_dir, "received_estimation_inputs")
     estimated_dir = os.path.join(base_dir, "estimated_results")
     os.makedirs(received_dir, exist_ok=True)
+    os.makedirs(received_padata_dir, exist_ok=True)
+    os.makedirs(received_estimation_inputs_dir, exist_ok=True)
     os.makedirs(estimated_dir, exist_ok=True)
 
     app.config["RECEIVED_DIR"] = received_dir
+    app.config["RECEIVED_PADATA_DIR"] = received_padata_dir
+    app.config["RECEIVED_ESTIMATION_INPUTS_DIR"] = received_estimation_inputs_dir
     app.config["ESTIMATED_DIR"] = estimated_dir
 
     # Register route blueprints

result_server/app_dev.py

@@ -28,8 +28,8 @@ def setup_dev_environment(base_dir):
     os.environ["DEV_MODE"] = "1"
 
     # 必要なディレクトリを作成
-    for sub in ["main/received", "main/estimated_results", "main/flask_session",
-                 "dev1/received", "dev1/estimated_results", "dev1/flask_session"]:
+    for sub in ["main/received", "main/received_padata", "main/received_estimation_inputs", "main/estimated_results", "main/flask_session",
+                 "dev1/received", "dev1/received_padata", "dev1/received_estimation_inputs", "dev1/estimated_results", "dev1/flask_session"]:
         os.makedirs(os.path.join(base_dir, sub), exist_ok=True)
 
 
@@ -133,11 +133,17 @@ def create_dev_app(base_dir):
     app.config["TOTP_ISSUER"] = f"{os.environ.get('TOTP_ISSUER', 'BenchKit')}-Local"
 
     received_dir = os.path.join(base_dir, "main", "received")
+    received_padata_dir = os.path.join(base_dir, "main", "received_padata")
+    received_estimation_inputs_dir = os.path.join(base_dir, "main", "received_estimation_inputs")
     estimated_dir = os.path.join(base_dir, "main", "estimated_results")
     os.makedirs(received_dir, exist_ok=True)
+    os.makedirs(received_padata_dir, exist_ok=True)
+    os.makedirs(received_estimation_inputs_dir, exist_ok=True)
     os.makedirs(estimated_dir, exist_ok=True)
 
     app.config["RECEIVED_DIR"] = received_dir
+    app.config["RECEIVED_PADATA_DIR"] = received_padata_dir
+    app.config["RECEIVED_ESTIMATION_INPUTS_DIR"] = received_estimation_inputs_dir
     app.config["ESTIMATED_DIR"] = estimated_dir
 
     # results_loaderはcurrent_app.configから取得するため、モジュール変数の書き換え不要

result_server/routes/api.py

@@ -12,12 +12,14 @@
   POST /upload-tgz  → ingest_padata
 """
 
-from flask import Blueprint, request, abort, current_app, jsonify
+from flask import Blueprint, request, abort, current_app, jsonify, send_file
 import os
 import json
 import re
 import uuid
 import shutil
+import io
+import tarfile
 from datetime import datetime
 
 api_bp = Blueprint("api", __name__)
@@ -124,6 +126,38 @@ def _load_json_by_uuid(directory, field_path, uuid_value):
     return None
 
 
+def _find_result_file_by_uuid(received_dir, uuid_value):
+    json_files = sorted(
+        [f for f in os.listdir(received_dir) if f.endswith(".json")],
+        reverse=True,
+    )
+
+    for json_file in json_files:
+        path = os.path.join(received_dir, json_file)
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception:
+            continue
+
+        if data.get("_server_uuid") == uuid_value or uuid_value in json_file:
+            return json_file, path, data
+
+    return None, None, None
+
+
+def _safe_extract_tar_bytes(file_storage, target_dir):
+    with tarfile.open(fileobj=file_storage.stream, mode="r:*") as tar:
+        for member in tar.getmembers():
+            normalized = os.path.normpath(member.name)
+            if os.path.isabs(normalized) or normalized.startswith(".."):
+                abort(400, description="Unsafe archive entry")
+        try:
+            tar.extractall(target_dir, filter="data")
+        except TypeError:
+            tar.extractall(target_dir)
+
+
 # ==========================================
 # 新パス: /api/ingest/*
 # ==========================================
@@ -172,7 +206,7 @@ def ingest_padata():
     if not uploaded_file:
         abort(400, description="No file uploaded")
 
-    received_dir = current_app.config["RECEIVED_DIR"]
+    received_dir = current_app.config["RECEIVED_PADATA_DIR"]
 
     matched_files = [
         f for f in os.listdir(received_dir)
@@ -204,6 +238,43 @@ def ingest_padata():
     }, 200
 
 
+@api_bp.route("/api/ingest/estimation-inputs", methods=["POST"])
+def ingest_estimation_inputs():
+    """Estimation input archive (tgz) upload and expansion."""
+    require_api_key()
+
+    uuid_str = request.form.get("id")
+    if not uuid_str or not is_valid_uuid(uuid_str):
+        abort(400, description="Invalid or missing UUID")
+
+    uploaded_file = request.files.get("file")
+    if not uploaded_file:
+        abort(400, description="No file uploaded")
+
+    received_dir = current_app.config["RECEIVED_DIR"]
+    result_filename, _, _ = _find_result_file_by_uuid(received_dir, uuid_str)
+    if not result_filename:
+        abort(404, description=f"No result found for uuid={uuid_str}")
+
+    result_stem = os.path.splitext(result_filename)[0]
+    inputs_root = current_app.config["RECEIVED_ESTIMATION_INPUTS_DIR"]
+    target_dir = os.path.join(inputs_root, result_stem)
+    replaced = os.path.isdir(target_dir)
+    if replaced:
+        shutil.rmtree(target_dir)
+    os.makedirs(target_dir, exist_ok=True)
+
+    _safe_extract_tar_bytes(uploaded_file, target_dir)
+
+    print(f"Saved estimation inputs: {target_dir}", flush=True)
+    return {
+        "status": "uploaded",
+        "id": uuid_str,
+        "directory": result_stem,
+        "replaced": replaced,
+    }, 200
+
+
 # ==========================================
 # Query API: /api/query/*
 # ==========================================
@@ -285,6 +356,45 @@ def query_result():
     abort(404, description=f"No result found for system={system}, code={code}, exp={exp}")
 
 
+@api_bp.route("/api/query/estimation-inputs", methods=["GET"])
+def query_estimation_inputs():
+    """Return estimation input artifacts for a result UUID as a tar.gz archive."""
+    require_api_key()
+
+    uuid_value = request.args.get("uuid")
+    if not uuid_value or not is_valid_uuid(uuid_value):
+        abort(400, description="Invalid UUID")
+
+    result_filename, _, _ = _find_result_file_by_uuid(
+        current_app.config["RECEIVED_DIR"], uuid_value
+    )
+    if not result_filename:
+        abort(404, description=f"No result found for uuid={uuid_value}")
+
+    result_stem = os.path.splitext(result_filename)[0]
+    source_dir = os.path.join(
+        current_app.config["RECEIVED_ESTIMATION_INPUTS_DIR"], result_stem
+    )
+    if not os.path.isdir(source_dir):
+        abort(404, description=f"No estimation inputs found for uuid={uuid_value}")
+
+    buffer = io.BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w:gz") as tar:
+        for entry in sorted(os.listdir(source_dir)):
+            tar.add(
+                os.path.join(source_dir, entry),
+                arcname=entry,
+            )
+    buffer.seek(0)
+
+    return send_file(
+        buffer,
+        mimetype="application/gzip",
+        as_attachment=True,
+        download_name=f"estimation_inputs_{result_stem}.tgz",
+    )
+
+
 @api_bp.route("/api/query/estimate", methods=["GET"])
 def query_estimate():
     """UUID で単一 Estimate JSON を返す。"""