"""Server-side Utah universal client using Python's standard library; no automatic retries.""" import json import math import re import time import email.utils import urllib.request import urllib.error import urllib.parse _SAFE_HEADERS = ('retry-after', 'content-type', 'date', 'x-request-id', 'request-id', 'x-ratelimit-limit-requests', 'x-ratelimit-remaining-requests', 'x-ratelimit-reset-requests') _NUMBER = re.compile(r'^(?:\d+\.?\d*|\.\d+)$') _DATE = re.compile(r'^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$') def _retry_delay(value, body): text = value.strip() if isinstance(value, str) else '' if _NUMBER.fullmatch(text): result = float(text) if math.isfinite(result): return result if _DATE.fullmatch(text): try: date = email.utils.parsedate_to_datetime(text) if email.utils.format_datetime(date, usegmt=True) == text: return max(0, date.timestamp() - time.time()) except (ValueError, TypeError, OverflowError): pass fallback = body.get('retry_after') if isinstance(body, dict) else None if fallback is None and isinstance(body, dict) and isinstance(body.get('error'), dict): fallback = body['error'].get('retry_after') if isinstance(fallback, bool): return None if isinstance(fallback, (int, float)) or isinstance(fallback, str) and _NUMBER.fullmatch(fallback.strip()): try: result = float(fallback) except (ValueError, TypeError, OverflowError): return None if math.isfinite(result) and result >= 0: return result return None def _iter_sse(response): event_name = None data = [] for raw in response: line = raw.decode('utf-8').rstrip('\r\n') if line.startswith('event:'): event_name = line[6:].strip() elif line.startswith('data:'): data.append(line[5:].lstrip(' ')) elif not line and data: text, ev, data, event_name = '\n'.join(data), event_name, [], None if text == '[DONE]': return parsed = json.loads(text) if ev and isinstance(parsed, dict) and 'event' not in parsed: parsed['event'] = ev yield parsed if data: text = '\n'.join(data) if text != '[DONE]': parsed = json.loads(text) if event_name and isinstance(parsed, dict) and 'event' not in parsed: parsed['event'] = event_name yield parsed class UtahError(Exception): def __init__(self, status, message, *, headers=None, body=None): super().__init__(message) self.status = status available = {name.lower(): value for name, value in (headers.items() if headers else [])} self.headers = {name: available[name] for name in _SAFE_HEADERS if name in available} self.body = body self.error = body.get('error') if isinstance(body, dict) else None self.retry_after = _retry_delay(self.headers.get('retry-after'), body) class _NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None class Utah: def __init__(self, api_key, base_url='https://aithatsee.com/utah/v1', timeout=120): if not isinstance(api_key, str) or not api_key.strip(): raise ValueError('Set your Utah API key on the server.') url = urllib.parse.urlsplit(base_url) if url.scheme != 'https' and url.hostname not in ('localhost', '127.0.0.1', '::1'): raise ValueError('Utah requires HTTPS.') if url.username or url.password or url.query or url.fragment: raise ValueError('Use a plain API base URL.') self.api_key, self.base_url, self.timeout = api_key.strip(), base_url.rstrip('/'), timeout self.root_url = re.sub(r'/v1(?:beta)?$', '', self.base_url) self.opener = urllib.request.build_opener(_NoRedirect()) def _request_url(self, full_url, body=None, extra_headers=None): headers = {'Authorization': 'Bearer ' + self.api_key, 'Content-Type': 'application/json', 'User-Agent': 'Utah-Python/2.0', 'Accept': 'application/json, text/event-stream'} if extra_headers: headers.update(extra_headers) req = urllib.request.Request(full_url, data=None if body is None else json.dumps(body).encode('utf-8'), headers=headers) try: return self.opener.open(req, timeout=self.timeout) except urllib.error.HTTPError as error: try: try: body = json.loads(error.read()) except (ValueError, UnicodeError): body = None detail = body.get('error') if isinstance(body, dict) else None if isinstance(detail, dict): detail = detail.get('message') if not isinstance(detail, str): detail = 'Utah request failed.' failure = UtahError(error.code, detail, headers=error.headers, body=body) finally: error.close() raise failure from None def _request(self, path, body=None, extra_headers=None): return self._request_url(self.base_url + path, body, extra_headers) def models(self): with self._request('/models') as response: return json.load(response) def harnesses(self): with self._request('/harnesses') as response: return json.load(response) def chat(self, messages, model='utah', max_tokens=1024, temperature=None, *, tools=None, tool_choice=None, request_id=None): body = dict(messages=messages, model=model, max_tokens=max_tokens, stream=False) if temperature is not None: body['temperature'] = temperature if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/chat/completions', body) as response: return json.load(response) def stream(self, messages, model='utah', max_tokens=1024, temperature=None, *, tools=None, tool_choice=None, request_id=None): body = dict(messages=messages, model=model, max_tokens=max_tokens, stream=True) if temperature is not None: body['temperature'] = temperature if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/chat/completions', body) as response: yield from _iter_sse(response) def responses(self, input, model='utah', instructions=None, max_output_tokens=1024, temperature=None, *, reasoning=None, service_tier=None, tools=None, tool_choice=None, request_id=None): body = dict(input=input, model=model, max_output_tokens=max_output_tokens, stream=False) if instructions is not None: body['instructions'] = instructions if temperature is not None: body['temperature'] = temperature if reasoning is not None: body['reasoning'] = reasoning if service_tier is not None: body['service_tier'] = service_tier if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/responses', body) as response: return json.load(response) def stream_responses(self, input, model='utah', instructions=None, max_output_tokens=1024, temperature=None, *, reasoning=None, service_tier=None, tools=None, tool_choice=None, request_id=None): body = dict(input=input, model=model, max_output_tokens=max_output_tokens, stream=True) if instructions is not None: body['instructions'] = instructions if temperature is not None: body['temperature'] = temperature if reasoning is not None: body['reasoning'] = reasoning if service_tier is not None: body['service_tier'] = service_tier if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/responses', body) as response: yield from _iter_sse(response) def messages(self, messages, model='utah', max_tokens=1024, system=None, temperature=None, *, thinking=None, tools=None, tool_choice=None, request_id=None): body = dict(messages=messages, model=model, max_tokens=max_tokens, stream=False) if system is not None: body['system'] = system if temperature is not None: body['temperature'] = temperature if thinking is not None: body['thinking'] = thinking if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/messages', body, {'x-api-key': self.api_key, 'anthropic-version': '2023-06-01'}) as response: return json.load(response) def stream_messages(self, messages, model='utah', max_tokens=1024, system=None, temperature=None, *, thinking=None, tools=None, tool_choice=None, request_id=None): body = dict(messages=messages, model=model, max_tokens=max_tokens, stream=True) if system is not None: body['system'] = system if temperature is not None: body['temperature'] = temperature if thinking is not None: body['thinking'] = thinking if tools is not None: body['tools'] = tools if tool_choice is not None: body['tool_choice'] = tool_choice if request_id is not None: body['request_id'] = request_id with self._request('/messages', body, {'x-api-key': self.api_key, 'anthropic-version': '2023-06-01'}) as response: yield from _iter_sse(response) def count_tokens(self, messages, model='utah', system=None): body = dict(messages=messages, model=model) if system is not None: body['system'] = system with self._request('/messages/count_tokens', body, {'x-api-key': self.api_key, 'anthropic-version': '2023-06-01'}) as response: return json.load(response) def gemini_generate(self, contents, model='utah', system_instruction=None, max_output_tokens=1024, temperature=None, *, include_thoughts=False, request_id=None): norm = [{'role': 'user', 'parts': [{'text': contents}]}] if isinstance(contents, str) else contents gen_cfg = {'maxOutputTokens': max_output_tokens} if temperature is not None: gen_cfg['temperature'] = temperature if include_thoughts: gen_cfg['thinkingConfig'] = {'includeThoughts': True} body = {'contents': norm, 'generationConfig': gen_cfg} if system_instruction is not None: body['systemInstruction'] = {'parts': [{'text': system_instruction}]} if isinstance(system_instruction, str) else system_instruction if request_id is not None: body['request_id'] = request_id target = self.root_url + '/v1beta/models/' + urllib.parse.quote(model, safe='') + ':generateContent' with self._request_url(target, body, {'x-goog-api-key': self.api_key}) as response: return json.load(response) def stream_gemini(self, contents, model='utah', system_instruction=None, max_output_tokens=1024, temperature=None, *, include_thoughts=False, request_id=None): norm = [{'role': 'user', 'parts': [{'text': contents}]}] if isinstance(contents, str) else contents gen_cfg = {'maxOutputTokens': max_output_tokens} if temperature is not None: gen_cfg['temperature'] = temperature if include_thoughts: gen_cfg['thinkingConfig'] = {'includeThoughts': True} body = {'contents': norm, 'generationConfig': gen_cfg} if system_instruction is not None: body['systemInstruction'] = {'parts': [{'text': system_instruction}]} if isinstance(system_instruction, str) else system_instruction if request_id is not None: body['request_id'] = request_id target = self.root_url + '/v1beta/models/' + urllib.parse.quote(model, safe='') + ':streamGenerateContent?alt=sse' with self._request_url(target, body, {'x-goog-api-key': self.api_key}) as response: yield from _iter_sse(response) def mcp_tools(self): with self._request_url(self.root_url + '/mcp', {'jsonrpc': '2.0', 'id': 1, 'method': 'tools/list'}, {'Accept': 'application/json, text/event-stream'}) as response: payload = json.load(response) if isinstance(payload, dict) and payload.get('error'): raise UtahError(400, payload['error'].get('message', 'MCP tools/list failed.'), body=payload) return (payload.get('result') or {}).get('tools') or [] def mcp_call(self, name, arguments=None, *, rpc_id=1): rpc = {'jsonrpc': '2.0', 'id': rpc_id, 'method': 'tools/call', 'params': {'name': name, 'arguments': arguments or {}}} with self._request_url(self.root_url + '/mcp', rpc, {'Accept': 'application/json, text/event-stream'}) as response: payload = json.load(response) if isinstance(payload, dict) and payload.get('error'): raise UtahError(400, payload['error'].get('message', 'MCP tools/call failed.'), body=payload) return payload.get('result')