"""Select a decision provider without giving providers control of game input. An embedding controller can supply executor_decider(request) for its active model. Standalone scripts publish DecisionRequired for their caller to handle; they cannot invoke the caller's model themselves. """ from dataclasses import dataclass import json import math import time import urllib.error import uuid class DecisionRequired(RuntimeError): def __init__(self, request): super().__init__('The execution model must choose a candidate') self.request = request @dataclass class Decision: choice: str engine: str latency_ms: int jev_ms: int = 0 confidence: float | None = None probabilities: dict | None = None model: str | None = None fallback_reason: str | None = None failed_jev_ms: int | None = None candidate_scope: list | None = None def _answer(answer, options): if isinstance(answer, str): answer = {'choice': answer, 'latency_ms': 0} elif isinstance(answer, tuple) and len(answer) == 2: answer = {'choice': answer[0], 'latency_ms': answer[1]} if not isinstance(answer, dict) or not isinstance(answer.get('choice'), str) or answer['choice'] not in options: raise ValueError('Decision provider returned an unsupported candidate') latency = answer.get('latency_ms', 0) if isinstance(latency, bool) or not isinstance(latency, (int, float)) or not math.isfinite(latency) or latency < 0: raise ValueError('Decision latency must be a finite non-negative number') confidence = answer.get('confidence') if confidence is not None and (isinstance(confidence, bool) or not isinstance(confidence, (int, float)) or not math.isfinite(confidence) or not 0 <= confidence <= 1): raise ValueError('Decision confidence must be between 0 and 1') probabilities = answer.get('probabilities') if probabilities is not None: if not isinstance(probabilities, dict) or set(probabilities) != set(options): raise ValueError('Decision probabilities must describe the supplied candidates') if any(isinstance(p, bool) or not isinstance(p, (int, float)) or not math.isfinite(p) or not 0 <= p <= 1 for p in probabilities.values()) or not math.isclose(sum(probabilities.values()), 1, abs_tol=.01): raise ValueError('Decision probabilities must form a probability distribution') return answer['choice'], round(latency), confidence, probabilities, answer.get('model') class DecisionRouter: def __init__(self, config, jev_decider, executor_decider=None, fixed_decider=None, rules='', force_fixed=False): self.config = dict(config) self.mode = 'fixed' if force_fixed else self.config.get('decisionEngine', 'auto') if self.mode not in ('auto', 'jev', 'executor', 'fixed'): raise ValueError('decisionEngine must be auto, jev, executor or fixed') self.jev_decider = jev_decider self.executor_decider = executor_decider self.fixed_decider = fixed_decider self.rules = rules def choose(self, state, options, recent=(), run_id=None): if not options: raise ValueError('Decision requires at least one candidate') if self.mode == 'fixed': if self.fixed_decider is None: raise ValueError('Fixed decision provider is not configured') choice, latency, confidence, probabilities, model = _answer(self.fixed_decider(options), options) return Decision(choice, 'fixed', latency, confidence=confidence, probabilities=probabilities, model=model) reason = 'configured_executor' model = self.config.get('model') configured_model = isinstance(model, str) and bool(model.strip()) if self.mode in ('auto', 'jev'): if not configured_model: reason = 'no_jev_model' elif not self.config.get('apiKey'): reason = 'missing_jev_credentials' else: started = time.monotonic() try: answer = self.jev_decider(self.config, state, options, recent) choice, latency, confidence, probabilities, returned_model = _answer(answer, options) return Decision(choice, 'jev', latency, jev_ms=latency, confidence=confidence, probabilities=probabilities, model=returned_model or model, candidate_scope=answer.get('candidate_scope') if isinstance(answer, dict) else None) except urllib.error.HTTPError as error: reason = 'jev_http_%d' % error.code except (OSError, TimeoutError, ValueError) as error: reason = 'jev_unavailable_%s' % type(error).__name__ failed_jev_ms = round((time.monotonic() - started) * 1000) else: configured_model = False request = { 'schema_version': 1, 'request_id': uuid.uuid4().hex, 'run_id': run_id, 'reason': reason, 'requested_engine': 'executor', 'page_state': state, 'candidates': options, 'rules': self.rules, 'recent': list(recent)[-4:], 'execution_contract': { 'response': {'request_id': '', 'choice': ''}, 'requires_fresh_observation_before_external_input': True, 'note': 'The caller handles this decision. No game input is sent while handing off.', }, } if self.mode in ('auto', 'jev') and configured_model and self.config.get('apiKey'): request['failed_jev_ms'] = failed_jev_ms # The request contains observations and candidates, never provider config # or credentials. Detach it so the callback cannot alter executable actions. request = json.loads(json.dumps(request, ensure_ascii=False)) if self.executor_decider is None: raise DecisionRequired(request) started = time.monotonic() expected_request_id = request['request_id'] answer = self.executor_decider(request) if isinstance(answer, dict) and answer.get('request_id') != expected_request_id: raise ValueError('Execution-model response belongs to a different decision request') choice, _, confidence, probabilities, returned_model = _answer(answer, options) latency = round((time.monotonic() - started) * 1000) return Decision(choice, 'executor', latency, confidence=confidence, probabilities=probabilities, model=returned_model, fallback_reason=reason, failed_jev_ms=request.get('failed_jev_ms'))