@microsoft/m365-copilot-eval 1.3.0-preview.1 → 1.5.0-preview.1

package/src/clients/cli/result_writer.py

@@ -0,0 +1,488 @@
+"""Output formatting, score conversion, and result writing."""
+
+import csv
+import json
+import os
+import sys
+import webbrowser
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from cli_logging.cli_logger import emit_structured_log
+from cli_logging.logging_utils import Operation
+from common import (
+    DEFAULT_PASS_THRESHOLD,
+    RELEVANCE,
+    COHERENCE,
+    GROUNDEDNESS,
+    SIMILARITY,
+    TOOL_CALL_ACCURACY,
+    CITATIONS,
+    EXACT_MATCH,
+    PARTIAL_MATCH,
+    METRIC_IDS,
+    STATUS_PASS,
+    STATUS_FAIL,
+    STATUS_ERROR,
+    STATUS_PARTIAL,
+    STATUS_UNKNOWN,
+    pascal_case_to_title,
+    RunConfig,
+)
+from generate_report import generate_html_report, calculate_aggregate_statistics
+from schema_handler import SchemaVersionManager
+
+
+def write_results_to_html(results: List[Dict], output_file: str,
+                          agent_name: Optional[str] = None, agent_id: Optional[str] = None,
+                          cli_version: Optional[str] = None):
+    """Write results to HTML file using generate_html_report from generate_report.py."""
+    try:
+        html = generate_html_report(results, agent_name=agent_name, agent_id=agent_id,
+                                    cli_version=cli_version)
+        os.makedirs(os.path.dirname(os.path.abspath(output_file)), exist_ok=True)
+        with open(output_file, 'w', encoding='utf-8') as f:
+            f.write(html)
+        emit_structured_log("info", f"HTML report saved to {output_file}", operation=Operation.WRITE_OUTPUT)
+    except Exception as e:
+        emit_structured_log("error", f"Error writing to HTML file: {e}", operation=Operation.WRITE_OUTPUT)
+        sys.exit(1)
+
+
+def write_results_to_console(results, agent_name: Optional[str] = None,
+                             agent_id: Optional[str] = None,
+                             cli_version: Optional[str] = None):
+    """Write the response to console."""
+    # ANSI color codes
+    BOLD = '\033[1m'
+    BLUE = '\033[94m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    CYAN = '\033[96m'
+    MAGENTA = '\033[95m'
+    ORANGE = '\033[38;5;208m'
+    RED = '\033[91m'
+    RESET = '\033[0m'
+
+    def _print_evaluated_item(response: str, expected_response: str,
+                              evaluators_ran: List[str], item_results: Dict[str, Any],
+                              error: Optional[str] = None) -> None:
+        """Print the body of a single evaluated item (single-turn prompt or multi-turn turn).
+
+        The item header (Prompt X / Turn X) is printed by the caller; this helper
+        prints evaluators, response, expected response, error, and metrics.
+        """
+        if evaluators_ran:
+            print(f"{BOLD}{CYAN}Evaluators:{RESET} {', '.join(evaluators_ran)}")
+        if response:
+            print(f"{BOLD}{CYAN}Response:{RESET} {response}")
+        if expected_response:
+            print(f"{BOLD}{YELLOW}Expected Response:{RESET} {expected_response}")
+        if error:
+            print(f"{BOLD}{RED}Error:{RESET} {error}")
+
+        for eval_name, v in item_results.items():
+            if v is None:
+                continue
+            display_name = pascal_case_to_title(eval_name)
+            if eval_name == RELEVANCE:
+                color = MAGENTA
+            elif eval_name == COHERENCE:
+                color = ORANGE
+            else:
+                color = BLUE
+            print(f"{BOLD}{color}{display_name}:{RESET} {json.dumps(v, indent=4)}")
+
+    # Show metadata
+    metadata_parts = []
+    if agent_name:
+        metadata_parts.append(f"Agent Name: {agent_name}")
+    if agent_id:
+        metadata_parts.append(f"Agent ID: {agent_id}")
+    if cli_version:
+        metadata_parts.append(f"CLI Version: {cli_version}")
+    if metadata_parts:
+        print(f"{BOLD}{CYAN}{' | '.join(metadata_parts)}{RESET}")
+        print()
+
+    aggregates = calculate_aggregate_statistics(results)
+    if aggregates:
+        total_items = aggregates[next(iter(aggregates))].get('total_prompts', len(results))
+        if total_items > 1:
+            print(f"{BOLD}{BLUE}Aggregate Statistics ({total_items} prompts):{RESET}")
+            print(f"{BLUE}{'=' * 60}{RESET}")
+
+            for metric_name, stats in aggregates.items():
+                pass_color = GREEN if stats['pass_rate'] >= 80 else YELLOW if stats['pass_rate'] >= 60 else RED
+                prompts_evaluated = stats.get('prompts_evaluated', stats['total_evaluated'])
+                total_prompts = stats.get('total_prompts', total_items)
+                print(f"{BOLD}{CYAN}{metric_name}:{RESET} ({prompts_evaluated}/{total_prompts} prompts)")
+                print(f"  Pass Rate: {pass_color}{stats['pass_rate']:.1f}%{RESET} ({stats['pass_count']}/{stats['total_evaluated']} passed)")
+                print(f"  Avg Score: {MAGENTA}{stats['avg_score']:.2f}{RESET}")
+                if stats.get('threshold') is not None:
+                    print(f"  Threshold: {YELLOW}{stats['threshold']}{RESET}")
+                print()
+
+            print(f"{BLUE}{'=' * 60}{RESET}")
+            print()
+
+    print(f"{BOLD}{BLUE}Individual Results:{RESET}")
+    print(f"{BLUE}{'=' * 50}{RESET}")
+    for i, result in enumerate(results, 1):
+        if result.get("type") == "multi_turn":
+            thread_name = result.get("name", "Unnamed Thread")
+            summary = result.get("summary", {})
+            status = summary.get("overall_status", STATUS_UNKNOWN)
+            status_color = GREEN if status == STATUS_PASS else YELLOW if status == STATUS_PARTIAL else RED
+
+            print(f"{BOLD}{MAGENTA}Thread {i}: {thread_name}{RESET}")
+            for t_idx, turn in enumerate(result.get("turns", []), 1):
+                turn_status = turn.get("status", STATUS_UNKNOWN)
+                turn_color = GREEN if turn_status == STATUS_PASS else RED if turn_status in (STATUS_FAIL, STATUS_ERROR) else YELLOW
+                print(f"{BOLD}{turn_color}Turn {t_idx}:{RESET} [{turn_status}] {turn.get('prompt', '')}")
+                _print_evaluated_item(
+                    response=turn.get("response", ""),
+                    expected_response=turn.get("expected_response", ""),
+                    evaluators_ran=turn.get("evaluators_ran", []),
+                    item_results=turn.get("results", {}),
+                    error=turn.get("error"),
+                )
+            print()
+            print(f"{BOLD}{MAGENTA}Thread {i} Summary:{RESET}")
+            print(f"  Status: {status_color}{status.upper()}{RESET}")
+            print(f"  Turns passed: {status_color}{summary.get('turns_passed', 0)}/{summary.get('turns_total', 0)}{RESET}")
+            print(f"{BLUE}{'-' * 30}{RESET}")
+        else:
+            print(f"{BOLD}{GREEN}Prompt {i}:{RESET} {result['prompt']}")
+            _print_evaluated_item(
+                response=result.get('response', ''),
+                expected_response=result.get('expected_response', ''),
+                evaluators_ran=result.get('evaluators_ran', []),
+                item_results=result.get('results', {}),
+                error=result.get('errorDetails'),
+            )
+            print(f"{BLUE}{'-' * 30}{RESET}")
+
+
+def extract_eval_score(data: dict, metric_id: str) -> Optional[Dict]:
+    """Extract an EvalScore object from a decorated metric dict.
+
+    Maps internal decorated-metric format to schema EvalScore:
+    {score, result, threshold} (required) + reason, evaluator (optional).
+    """
+    score_val = None
+    if metric_id in data and isinstance(data[metric_id], (int, float)):
+        score_val = data[metric_id]
+    if score_val is None:
+        return None
+
+    result = data.get("result")
+    if result not in (STATUS_PASS, STATUS_FAIL):
+        result = STATUS_PASS if score_val >= data.get("threshold", DEFAULT_PASS_THRESHOLD) else STATUS_FAIL
+
+    eval_score: Dict[str, Any] = {
+        "score": score_val,
+        "result": result,
+        "threshold": data.get("threshold", DEFAULT_PASS_THRESHOLD),
+    }
+    reason = data.get(f"{metric_id}_reason") or data.get("reason")
+    if reason:
+        eval_score["reason"] = reason
+    return eval_score
+
+
+def _convert_scores_to_schema(results_dict: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert raw evaluator results to schema-compliant score objects.
+
+    Evaluator results in results_dict are dicts (from _decorate_metric) or
+    None when skipped/crashed. None values are omitted from output.
+    """
+    scores: Dict[str, Any] = {}
+
+    for eval_key, schema_key in [
+        (RELEVANCE, "relevance"),
+        (COHERENCE, "coherence"),
+        (GROUNDEDNESS, "groundedness"),
+        (SIMILARITY, "similarity"),
+        (TOOL_CALL_ACCURACY, "toolCallAccuracy"),
+    ]:
+        data = results_dict.get(eval_key)
+        if data is None:
+            continue
+        eval_score = extract_eval_score(data, METRIC_IDS[eval_key])
+        if eval_score:
+            scores[schema_key] = eval_score
+
+    data = results_dict.get(CITATIONS)
+    if data is not None:
+        count = data.get("citations", 0)
+        cit_result = data.get("result")
+        if cit_result not in (STATUS_PASS, STATUS_FAIL):
+            cit_result = STATUS_PASS if count >= data.get("threshold", 1) else STATUS_FAIL
+        citation_score: Dict[str, Any] = {
+            "count": count,
+            "result": cit_result,
+            "threshold": data.get("threshold", 1),
+        }
+        if "citation_format" in data:
+            citation_score["format"] = data["citation_format"]
+        scores["citations"] = citation_score
+
+    data = results_dict.get(EXACT_MATCH)
+    if data is not None:
+        is_match = data.get("exact_match", 0.0) == 1.0
+        scores["exactMatch"] = {
+            "match": is_match,
+            "result": data.get("result", STATUS_PASS if is_match else STATUS_FAIL),
+            "reason": data.get("exact_match_reason", ""),
+        }
+
+    data = results_dict.get(PARTIAL_MATCH)
+    if data is not None:
+        scores["partialMatch"] = {
+            "score": data.get("partial_match", 0.0),
+            "result": data.get("result", STATUS_FAIL),
+            "threshold": data.get("threshold", 0.5),
+            "reason": data.get("partial_match_reason", ""),
+        }
+
+    return scores
+
+
+def convert_result_to_eval_item(result: Dict) -> Dict:
+    """Convert an internal evaluation result dict to a schema-compliant EvalItem."""
+    item: Dict[str, Any] = {
+        "prompt": result["prompt"],
+        "response": result["response"],
+        "expected_response": result["expected_response"],
+    }
+
+    if "evaluators" in result:
+        item["evaluators"] = result["evaluators"]
+    if "evaluators_mode" in result:
+        item["evaluators_mode"] = result["evaluators_mode"]
+
+    scores = _convert_scores_to_schema(result.get("results", {}))
+    if scores:
+        item["scores"] = scores
+
+    return item
+
+
+def convert_thread_result_to_output(thread_result: Dict) -> Dict:
+    """Convert a multi-turn thread result to the output format."""
+    output_turns = []
+    for turn in thread_result.get("turns", []):
+        output_turn: Dict[str, Any] = {"prompt": turn.get("prompt", "")}
+        if "expected_response" in turn:
+            output_turn["expected_response"] = turn["expected_response"]
+        if "response" in turn:
+            output_turn["response"] = turn["response"]
+        if "status" in turn:
+            output_turn["status"] = turn["status"]
+        if "error" in turn:
+            output_turn["error"] = turn["error"]
+        if "evaluators" in turn:
+            output_turn["evaluators"] = turn["evaluators"]
+        if "evaluators_mode" in turn:
+            output_turn["evaluators_mode"] = turn["evaluators_mode"]
+
+        scores = _convert_scores_to_schema(turn.get("results", {}))
+        if scores:
+            output_turn["scores"] = scores
+
+        output_turns.append(output_turn)
+
+    output: Dict[str, Any] = {}
+    if thread_result.get("name"):
+        output["name"] = thread_result["name"]
+    if thread_result.get("description"):
+        output["description"] = thread_result["description"]
+    if thread_result.get("conversation_id"):
+        output["conversation_id"] = thread_result["conversation_id"]
+    output["turns"] = output_turns
+    if thread_result.get("summary"):
+        output["summary"] = thread_result["summary"]
+
+    return output
+
+
+def convert_result_to_output_item(result: Dict) -> Dict:
+    """Convert an internal result dict to an output item. Routes by type."""
+    if result.get("type") == "multi_turn":
+        return convert_thread_result_to_output(result)
+    return convert_result_to_eval_item(result)
+
+
+def write_results_to_json(results: List[Dict], output_file: str, agent_id: Optional[str] = None,
+                          default_evaluators: Optional[Dict[str, Any]] = None,
+                          agent_name: Optional[str] = None,
+                          cli_version: Optional[str] = None):
+    """Write results to a schema-compliant eval document JSON file.
+
+    Output follows the eval-document.schema.json format:
+    {schemaVersion, metadata, default_evaluators?, items: [EvalItem]}
+    """
+    try:
+        try:
+            current_version = SchemaVersionManager().get_current_version()
+        except Exception:
+            current_version = "1.0.0"
+
+        items = [convert_result_to_output_item(r) for r in results]
+
+        metadata: Dict[str, Any] = {
+            "evaluatedAt": datetime.now(timezone.utc).isoformat(),
+        }
+        if agent_id:
+            metadata["agentId"] = agent_id
+        if agent_name:
+            metadata["agentName"] = agent_name
+        if cli_version:
+            metadata["cliVersion"] = cli_version
+
+        output_data: Dict[str, Any] = {
+            "schemaVersion": current_version,
+            "metadata": metadata,
+        }
+
+        if default_evaluators is not None:
+            output_data["default_evaluators"] = default_evaluators
+
+        output_data["items"] = items
+
+        os.makedirs(os.path.dirname(os.path.abspath(output_file)), exist_ok=True)
+        with open(output_file, 'w', encoding='utf-8') as f:
+            json.dump(output_data, f, indent=2, ensure_ascii=False)
+        emit_structured_log("info", f"Results saved to {output_file}", operation=Operation.WRITE_OUTPUT)
+    except Exception as e:
+        emit_structured_log("error", f"Error writing to JSON file: {e}", operation=Operation.WRITE_OUTPUT)
+        sys.exit(1)
+
+
+def _results_to_csv_json(results_dict: Dict) -> str:
+    """Serialize evaluator results dict to a CSV-safe JSON string.
+
+    Skips None (crashed/skipped evaluators). Results are dicts produced
+    by _decorate_metric.
+    """
+    if not results_dict:
+        return ""
+    non_null = {k: v for k, v in results_dict.items() if v is not None}
+    return json.dumps(non_null) if non_null else ""
+
+
+def write_results_to_csv(results: List[Dict], output_file: str,
+                         agent_name: Optional[str] = None, agent_id: Optional[str] = None,
+                         cli_version: Optional[str] = None):
+    """Write results to CSV file."""
+    try:
+        os.makedirs(os.path.dirname(os.path.abspath(output_file)), exist_ok=True)
+        with open(output_file, 'w', newline='', encoding='utf-8') as f:
+            if results:
+                metadata_parts = []
+                if agent_name:
+                    metadata_parts.append(f"Agent Name: {agent_name}")
+                if agent_id:
+                    metadata_parts.append(f"Agent ID: {agent_id}")
+                if cli_version:
+                    metadata_parts.append(f"CLI Version: {cli_version}")
+                if metadata_parts:
+                    f.write(f"# {' | '.join(metadata_parts)}\n")
+
+                aggregates = calculate_aggregate_statistics(results)
+                if aggregates:
+                    total_items = aggregates[next(iter(aggregates))].get('total_prompts', len(results))
+                    if total_items > 1:
+                        f.write("# AGGREGATE STATISTICS\n")
+                        f.write("Metric,Prompts Evaluated,Total Prompts,Pass Rate (%),Passed,Failed,Avg Score,Threshold\n")
+                        for metric_name, stats in aggregates.items():
+                            threshold_str = str(stats.get('threshold', 'N/A'))
+                            prompts_evaluated = stats.get('prompts_evaluated', stats['total_evaluated'])
+                            total_prompts = stats.get('total_prompts', total_items)
+                            f.write(f"{metric_name},{prompts_evaluated},{total_prompts},{stats['pass_rate']:.1f},{stats['pass_count']},{stats['fail_count']},{stats['avg_score']:.2f},{threshold_str}\n")
+                        f.write("\n# INDIVIDUAL RESULTS\n")
+
+                single_turn_rows = []
+                multi_turn_rows = []
+                for result in results:
+                    if result.get("type") == "multi_turn":
+                        thread_name = result.get("name", "")
+                        for turn_idx, turn in enumerate(result.get("turns", [])):
+                            multi_turn_rows.append({
+                                "thread_name": thread_name,
+                                "turn_index": turn_idx + 1,
+                                "prompt": turn.get("prompt", ""),
+                                "response": turn.get("response", ""),
+                                "expected_response": turn.get("expected_response", ""),
+                                "status": turn.get("status", ""),
+                                "error": turn.get("error", ""),
+                                "scores": _results_to_csv_json(turn.get("results", {})),
+                            })
+                        summary = result.get("summary", {})
+                        multi_turn_rows.append({
+                            "thread_name": thread_name,
+                            "turn_index": "summary",
+                            "prompt": "",
+                            "response": "",
+                            "expected_response": "",
+                            "status": summary.get("overall_status", ""),
+                            "scores": f"{summary.get('turns_passed', 0)}/{summary.get('turns_total', 0)} turns passed",
+                        })
+                    else:
+                        exclude_keys = {'evaluators_ran', 'evaluators', 'evaluators_mode', '_enhanced_response', 'results'}
+                        row = {k: v for k, v in result.items() if k not in exclude_keys}
+                        if "results" in result:
+                            row["scores"] = _results_to_csv_json(result["results"])
+                        single_turn_rows.append(row)
+
+                if single_turn_rows:
+                    if multi_turn_rows:
+                        f.write("# SINGLE-TURN RESULTS\n")
+                    fieldnames = list(single_turn_rows[0].keys())
+                    for row in single_turn_rows:
+                        for k in row:
+                            if k not in fieldnames:
+                                fieldnames.append(k)
+                    writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction='ignore')
+                    writer.writeheader()
+                    writer.writerows(single_turn_rows)
+
+                if multi_turn_rows:
+                    if single_turn_rows:
+                        f.write("\n")
+                    f.write("# MULTI-TURN RESULTS\n")
+                    fieldnames = ["thread_name", "turn_index", "prompt", "response", "expected_response", "status", "error", "scores"]
+                    writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction='ignore')
+                    writer.writeheader()
+                    writer.writerows(multi_turn_rows)
+            emit_structured_log("info", f"Results saved to {output_file}", operation=Operation.WRITE_OUTPUT)
+    except Exception as e:
+        emit_structured_log("error", f"Error writing to CSV file: {e}", operation=Operation.WRITE_OUTPUT)
+        sys.exit(1)
+
+
+def output_results(results: List[Dict], config: RunConfig, default_evaluators: Optional[Dict[str, Any]] = None,
+                    agent_name: Optional[str] = None, cli_version: Optional[str] = None):
+    """Output results based on specified format."""
+    metadata_kwargs = dict(
+        agent_name=agent_name,
+        agent_id=config.m365_agent_id,
+        cli_version=cli_version,
+    )
+    if config.output:
+        output_lower = config.output.lower()
+        if output_lower.endswith('.json'):
+            write_results_to_json(results, config.output, default_evaluators=default_evaluators,
+                                  **metadata_kwargs)
+        elif output_lower.endswith('.csv'):
+            write_results_to_csv(results, config.output, **metadata_kwargs)
+        elif output_lower.endswith('.html'):
+            write_results_to_html(results, config.output, **metadata_kwargs)
+            abs_path = os.path.abspath(config.output)
+            webbrowser.open(f'file://{abs_path}')
+        else:
+            write_results_to_json(results, config.output, default_evaluators=default_evaluators,
+                                  **metadata_kwargs)
+    else:
+        write_results_to_console(results, **metadata_kwargs)

package/src/clients/cli/retry_policy.py

@@ -0,0 +1,52 @@
+"""Retry utilities for transient HTTP failures in evaluation flows."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Optional
+
+RETRYABLE_HTTP_STATUS_CODES = {429, 503, 504}
+MAX_BACKOFF_SECONDS = 60
+
+
+def is_retryable_status(status_code: Optional[int]) -> bool:
+    """Return True for transient HTTP status codes covered by the spec."""
+    if status_code is None:
+        return False
+    return int(status_code) in RETRYABLE_HTTP_STATUS_CODES
+
+
+def get_backoff_seconds(attempt: int) -> int:
+    """Return exponential backoff delay capped at MAX_BACKOFF_SECONDS.
+
+    Examples: 2, 4, 8 for attempts 1..3.
+    """
+    if attempt < 1:
+        raise ValueError("attempt must be >= 1")
+    return min(2 ** attempt, MAX_BACKOFF_SECONDS)
+
+
+def get_retry_after_seconds(retry_after_header: Optional[str]) -> Optional[int]:
+    """Parse Retry-After header value (delay-seconds or HTTP-date per RFC 7231)."""
+    if retry_after_header is None:
+        return None
+
+    value = retry_after_header.strip()
+    if not value:
+        return None
+
+    # Try delay-seconds (integer) first
+    try:
+        return max(0, int(value))
+    except ValueError:
+        pass
+
+    # Try HTTP-date format (RFC 7231 §7.1.3)
+    try:
+        retry_date = parsedate_to_datetime(value)
+        now = datetime.now(timezone.utc)
+        delta = int((retry_date - now).total_seconds())
+        return max(0, delta)
+    except (ValueError, TypeError):
+        return None

package/src/clients/cli/samples/multiturn_example.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": "1.2.0",
+  "default_evaluators": {
+    "Relevance": {},
+    "Coherence": {}
+  },
+  "items": [
+    {
+      "prompt": "What is Microsoft Graph?",
+      "expected_response": "Microsoft Graph is a gateway to data and intelligence in Microsoft 365."
+    },
+    {
+      "name": "Travel planning conversation",
+      "description": "Multi-turn thread testing context retention across turns",
+      "turns": [
+        {
+          "prompt": "I'm planning a trip to Seattle next week.",
+          "expected_response": "I can help you plan your Seattle trip."
+        },
+        {
+          "prompt": "What's the weather going to be like?",
+          "expected_response": "Seattle weather is typically mild with possible rain."
+        },
+        {
+          "prompt": "Should I bring a rain jacket?",
+          "expected_response": "Yes, it's always a good idea to bring rain gear to Seattle.",
+          "evaluators": {
+            "Groundedness": { "threshold": 4 }
+          },
+          "evaluators_mode": "extend"
+        }
+      ]
+    }
+  ]
+}

package/src/clients/cli/throttle_gate.py

@@ -0,0 +1,82 @@
+"""Per-API throttle gate support for transient HTTP 429 handling."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class GateState:
+    """Snapshot state for diagnostics and tests."""
+
+    api_name: str
+    blocked_until_epoch: float
+    is_blocked: bool
+    last_retry_after_seconds: Optional[int]
+
+
+class ThrottleGate:
+    """Thread-safe per-API gate that pauses workers until the block window elapses."""
+
+    def __init__(self, api_name: str) -> None:
+        self.api_name = api_name
+        self._lock = threading.Lock()
+        self._blocked_until_epoch = 0.0
+        self._last_retry_after_seconds: Optional[int] = None
+
+    def apply_retry_after(self, retry_after_seconds: int) -> float:
+        """Apply retry-after duration and keep the maximum active block window.
+
+        Returns the current effective blocked-until epoch.
+        """
+        retry_after_seconds = max(0, int(retry_after_seconds))
+        candidate = time.time() + retry_after_seconds
+
+        with self._lock:
+            if candidate > self._blocked_until_epoch:
+                self._blocked_until_epoch = candidate
+            self._last_retry_after_seconds = retry_after_seconds
+            return self._blocked_until_epoch
+
+    MAX_GATE_WAIT_SECONDS = 300.0
+
+    def wait_if_blocked(self) -> float:
+        """Sleep until the gate opens. Returns the total slept duration in seconds.
+
+        Re-checks the block window after each sleep to handle concurrent
+        ``apply_retry_after`` calls that extend the window (avoids TOCTOU).
+        Raises ``TimeoutError`` if the total wait exceeds ``MAX_GATE_WAIT_SECONDS``.
+        """
+        total_slept = 0.0
+        while True:
+            with self._lock:
+                delay = max(0.0, self._blocked_until_epoch - time.time())
+            if delay <= 0:
+                return total_slept
+            if total_slept + delay > self.MAX_GATE_WAIT_SECONDS:
+                raise TimeoutError(
+                    f"ThrottleGate '{self.api_name}' exceeded maximum wait of "
+                    f"{self.MAX_GATE_WAIT_SECONDS}s (slept {total_slept:.1f}s so far)."
+                )
+            time.sleep(delay)
+            total_slept += delay
+
+    def clear(self) -> None:
+        """Reset the gate to unblocked state."""
+        with self._lock:
+            self._blocked_until_epoch = 0.0
+            self._last_retry_after_seconds = None
+
+    def state(self) -> GateState:
+        """Return immutable snapshot state."""
+        with self._lock:
+            now = time.time()
+            return GateState(
+                api_name=self.api_name,
+                blocked_until_epoch=self._blocked_until_epoch,
+                is_blocked=self._blocked_until_epoch > now,
+                last_retry_after_seconds=self._last_retry_after_seconds,
+            )