python-fastllm 0.0.1__py3-none-any.whl

fastllm/gemini.py

@@ -0,0 +1,304 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/05_gemini.ipynb.
+
+# %% auto #0
+__all__ = ['api_ns', 'norm_tool_calls', 'norm_usage', 'norm_finish', 'norm_parts', 'norm_sse_event', 'delta_index_fn',
+           'acollect_stream', 'denorm_tool_use', 'denorm_assistant', 'denorm_tool', 'denorm_msgs', 'denorm_tool_schs',
+           'denorm_tool_choice', 'denorm_reasoning', 'denorm_web_search', 'denorm_system', 'denorm_user',
+           'denorm_image', 'denorm_audio', 'denorm_video', 'denorm_file', 'denorm_tool_result', 'mk_payload',
+           'get_hdrs', 'cost']
+
+# %% ../nbs/05_gemini.ipynb #02afd3d7
+import json
+from collections import Counter
+from fastcore.utils import *
+from fastcore.meta import *
+from fastspec.errors import api_error_from_event
+
+from .types import *
+from .streaming import *
+from .streaming import mk_acollect_stream
+
+# %% ../nbs/05_gemini.ipynb #f1eb32f3
+def norm_tool_calls(resp):
+    "Extract Gemini functionCall parts as normalized tool calls."
+    out = []
+    for i,p in enumerate(nested_idx(resp, 'candidates', 0, 'content', 'parts') or []):
+        if not (fc:=p.get("functionCall")): continue
+        extra = {k:v for k,v in p.items() if k != "functionCall"}
+        out.append(ToolCall(id=fc.get("id", f"call_{i}"), name=fc.get("name", ""), arguments=fc.get("args") or {}, extra=extra))
+    return out
+
+# %% ../nbs/05_gemini.ipynb #90504163
+def norm_usage(resp):
+    "Normalize Gemini usageMetadata shape."
+    if not (usg:=resp.get("usageMetadata")): return None
+    pt = int(usg.get("promptTokenCount", 0) or 0)
+    ct = int(usg.get("candidatesTokenCount", 0) or 0)
+    tt = int(usg.get("totalTokenCount", pt + ct) or (pt + ct))
+    cached = int(usg.get("cachedContentTokenCount", 0) or 0)
+    reasoning = int(usg.get("thoughtsTokenCount", 0) or 0)
+    parts = nested_idx(resp, 'candidates', 0, 'content', 'parts') or []
+    cand = nested_idx(resp, 'candidates', 0) or {}
+    stu = {}
+    if any("executableCode" in p for p in parts): stu["code_execution"] = sum(1 for p in parts if "executableCode" in p)
+    if "groundingMetadata" in cand: stu["google_search"] = 1
+    if stu: usg['server_tool_use'] = stu
+    return Usage(prompt_tokens=pt, completion_tokens=ct, total_tokens=tt,
+                 cached_tokens=cached, reasoning_tokens=reasoning, raw=usg)
+
+# %% ../nbs/05_gemini.ipynb #7a8b1f8f
+def norm_finish(resp, tcs=None):
+    "Canonicalize finish_reason to OpenAI Chat values: stop, tool_calls, length, content_filter."
+    reason = nested_idx(resp, 'candidates', 0, 'finishReason')
+    if reason is not None: reason = reason.lower()
+    mp = dict(stop=FinishReason.stop, max_tokens=FinishReason.length, safety=FinishReason.content_filter, blocklist=FinishReason.content_filter)
+    r =  mp.get(reason, reason)
+    return FinishReason.tool_calls if r==FinishReason.stop and any(~L(tcs).attrgot('server')) else r 
+
+# %% ../nbs/05_gemini.ipynb #81c2ce3f
+def _gem_part_type(p):
+    "Map Gemini part to canonical PartType."
+    if 'functionCall' in p or 'toolCall' in p: return PartType.tool_use
+    if 'executableCode' in p or 'codeExecutionResult' in p: return PartType.tool_result
+    if p.get('thought'): return PartType.thinking
+    return PartType.text
+
+def norm_parts(resp):
+    "Normalize Gemini generateContent response."
+    c0 = nested_idx(resp, 'candidates', 0) or {}
+    tcs = norm_tool_calls(resp)
+    tc_map = {tc.id: tc for tc in tcs}
+    parts = []
+    for p in nested_idx(c0, 'content', 'parts') or []:
+        typ = _gem_part_type(p)
+        if typ == 'tool_use':
+            fc = p.get('functionCall') or p.get('toolCall') or {}
+            tc = tc_map.get(fc.get('id'))
+            if tc: 
+                tdata = {**tc.extra, 'id':tc.id, 'name':tc.name, 'arguments':tc.arguments, 'server':tc.server}
+                parts.append(Part(type=PartType.tool_use, data=tdata))
+        else: parts.append(Part(type=typ, text=p.get("text",""), data=p))
+    if citations := c0.get('groundingMetadata'):
+        for p in parts: 
+            if p.type == PartType.text: p.data['citations'] = citations
+    return parts
+
+# %% ../nbs/05_gemini.ipynb #9a5024ee
+def norm_sse_event(ev, **kwargs):
+    "Normalize Gemini stream event into Delta."
+    cand = nested_idx(ev, 'candidates', 0) or {}
+    finish_reason = norm_finish(ev)
+    parts = nested_idx(cand, 'content', 'parts') or []
+    thinking = "".join(p.get("text","") for p in parts if p.get("thought") and "text" in p)
+    txt = "".join(p.get("text","") for p in parts if not p.get("thought") and "text" in p)
+    tcs = norm_tool_calls(ev)
+    if ev.get("error"): raise api_error_from_event(ev)
+    return Delta(text=txt, thinking=thinking, tool_calls=tcs, citations=listify(cand.get('groundingMetadata', [])), finish_reason=finish_reason, usage=norm_usage(ev), raw=ev, **kwargs)
+
+# %% ../nbs/05_gemini.ipynb #ebd6fdd4
+def delta_index_fn(d, typ, last_typ, last_idx):
+    'Returns accumulation index for current delta and updated last idx'
+    if not (last_typ or last_idx): return 0,0
+    return last_idx + 1, last_idx + 1
+
+# %% ../nbs/05_gemini.ipynb #328af4d5
+@delegates(mk_acollect_stream, but=['index_fn', 'api_name'])
+async def acollect_stream(resp, **kwargs):
+    res = mk_acollect_stream(norm_and_yield(resp, norm_sse_event), index_fn=delta_index_fn, api_name='gemini', **kwargs)
+    async for o in res: yield o
+
+# %% ../nbs/05_gemini.ipynb #58d0cb74
+def denorm_tool_use(p:Part):
+    "Convert canonical tool_use Part to Gemini functionCall part."
+    d = p.data or {}
+    fc = dict(name=d.get('name',''), args=d.get('arguments') or {})
+    if d.get('id'): fc['id'] = d['id']
+    part = dict(functionCall=fc)
+    part['thoughtSignature'] = d.get('thoughtSignature', 'skip_thought_signature_validator')
+    return part
+
+def denorm_assistant(m:Msg):
+    "Convert canonical assistant Msg to Gemini model content."
+    parts = []
+    for p in m.content:
+        if   p.type == PartType.thinking: parts.append(dict(text=p.text or '', thought=True))
+        elif p.type == PartType.text:     parts.append(dict(text=p.text or ''))
+        elif p.type == PartType.tool_use: parts.append(denorm_tool_use(p))
+    return dict(role='model', parts=parts)
+
+def denorm_tool(m:Msg):
+    "Convert canonical tool Msg to Gemini user content with functionResponse parts."
+    parts = [denorm_tool_result(p) for p in m.content if p.type == PartType.tool_result]
+    return dict(role='user', parts=parts)
+
+def denorm_msgs(msgs:list[Msg]):
+    "Convert list of canonical Msgs to Gemini contents."
+    res = []
+    for m in msgs:
+        if   m.role == 'user':      res.append(denorm_user(m))
+        elif m.role == 'assistant': res.append(denorm_assistant(m))
+        elif m.role == 'tool':      res.append(denorm_tool(m))
+    return res
+
+# %% ../nbs/05_gemini.ipynb #adb525db
+_valid_gemini_sch = {'type', 'format', 'title', 'description', 'nullable', 'default',
+    'items', 'minItems', 'maxItems', 'enum', 'properties', 'propertyOrdering',
+    'required', 'minProperties', 'maxProperties', 'minimum', 'maximum',
+    'minLength', 'maxLength', 'pattern', 'example', 'anyOf'}
+
+def _gem_filter_sch(s):
+    if isinstance(s, list): return [_gem_filter_sch(x) for x in s]
+    if not isinstance(s, dict): return s
+    return {k: _gem_filter_sch(v) for k,v in s.items() if k in _valid_gemini_sch}
+
+def denorm_tool_schs(tools):
+    "Convert canonical tools to Gemini format."
+    fn_decls, other = [], []
+    for t in tools:
+        fn = fn_schema(t)
+        if fn is None: other.append(t); continue
+        name, desc, params = fn
+        params['properties'] = {k:_gem_filter_sch(v) for k,v in params['properties'].items()}
+        fn_decls.append(dict(name=name, description=desc, parameters=params))
+    out = other[:]
+    if fn_decls: out.insert(0, dict(functionDeclarations=fn_decls))
+    return out
+
+# %% ../nbs/05_gemini.ipynb #6118d7ea
+def denorm_tool_choice(v):
+    "Map canonical tool_choice to Gemini toolConfig."
+    if v is None: return None
+    if v in ('auto',):                    return {'functionCallingConfig': {'mode': 'AUTO'}}
+    if v in ('required', 'any', 'force'): return {'functionCallingConfig': {'mode': 'ANY'}}
+    if v in ('none', 'off', 'disabled'):  return {'functionCallingConfig': {'mode': 'NONE'}}
+    return {'functionCallingConfig': {'mode': 'ANY', 'allowedFunctionNames': [v]}}
+
+# %% ../nbs/05_gemini.ipynb #310f1e75
+_gem_think_budgets = dict(minimal=128, low=1024, medium=2048, high=4096)
+_gem_think_levels  = dict(minimal='low', low='low', medium='medium', high='high')
+
+def denorm_reasoning(v, model=''):
+    "Map canonical reasoning_effort to Gemini thinkingConfig (uses thinkingLevel for Gemini 3+)."
+    err = ValueError(f"Invalid reasoning effort for Gemini: {v}, accepted string values are: {list(_gem_think_budgets)} and dicts are passthrough")
+    if v is None: return None
+    elif isinstance(v, dict): return v
+    elif isinstance(v, str) and v in _gem_think_budgets:
+        # defaults to includeThoughts same as litellm
+        if 'gemini-3' in model: return {'thinkingLevel': _gem_think_levels.get(v, 'medium'), 'includeThoughts': True}
+        return {'thinkingBudget': _gem_think_budgets.get(str(v).lower(), 1024), 'includeThoughts': True}
+
+# %% ../nbs/05_gemini.ipynb #8fa9fbb8
+def denorm_web_search(v): return {"googleSearch": {}}
+
+# %% ../nbs/05_gemini.ipynb #6b485275
+def denorm_system(sp): return dict(parts=[{'text': sys_text(part_txt(sp))}])
+
+# %% ../nbs/05_gemini.ipynb #1b990cc9
+def denorm_user(m:Msg):
+    "Convert canonical user Msg to Gemini user content."
+    parts = []
+    for p in m.content:
+        if   p.type == PartType.text:        parts.append({"text": p.text or ""})
+        elif p.type == PartType.input_image: parts.append(denorm_image(p))
+        elif p.type == PartType.input_audio: parts.append(denorm_audio(p))
+        elif p.type == PartType.input_video: parts.append(denorm_video(p))
+        elif p.type == PartType.input_file:  parts.append(denorm_file(p))
+    return dict(role='user', parts=parts)
+
+# %% ../nbs/05_gemini.ipynb #edd87272
+def denorm_image(p):
+    if (b64:=data_url(p.text)): return {"inlineData": {"mimeType": b64[0], "data": b64[1]}}
+    return {"fileData": {"mimeType": url_mime(p.text, "image/*"), "fileUri": p.text}}
+
+# %% ../nbs/05_gemini.ipynb #a4222dc6
+def denorm_audio(p): 
+    if (b64:=data_url(p.text)): return {"inlineData": {"mimeType": b64[0], "data": b64[1]}}
+    return {"fileData": {"mimeType": url_mime(p.text, "audio/*"), "fileUri": p.text}}
+
+# %% ../nbs/05_gemini.ipynb #6b1720e0
+def denorm_video(p):
+    if (b64:=data_url(p.text)): return {"inlineData": {"mimeType": b64[0], "data": b64[1]}}
+    return {"fileData": {"mimeType": url_mime(p.text, "video/mp4"), "fileUri": p.text}}
+
+# %% ../nbs/05_gemini.ipynb #fc6bbdfc
+def denorm_file(p):
+    if (b64:=data_url(p.text)): return {"inlineData": {"mimeType": b64[0], "data": b64[1]}}
+    return {"fileData": {"mimeType": url_mime(p.text, "application/pdf"), "fileUri": p.text}}
+
+# %% ../nbs/05_gemini.ipynb #16df1073
+def denorm_tool_result(p:Part):
+    "Convert canonical tool_result Part to Gemini functionResponse part."
+    d = p.data or {}
+    fr = dict(name=d.get('name',''), response={"content": "" if isinstance(p.text, list) else str(p.text)})
+    if d.get('id'): fr['id'] = d['id']
+    if isinstance(p.text, list):
+        parts = []
+        for pp in p.text:
+            if   pp.type == PartType.text:        parts.append({"text": pp.text or ""})
+            elif pp.type == PartType.input_image: parts.append(denorm_image(pp))
+            elif pp.type == PartType.input_file:  parts.append(denorm_file(pp))
+            else: raise ValueError(f"Gemini tool_result does not support {pp.type}")
+        fr['parts'] = parts
+    return dict(functionResponse=fr)
+
+# %% ../nbs/05_gemini.ipynb #587d4fe5
+@delegates(payload_kwargs)
+def mk_payload(msgs, model, **kwargs):
+    payload = dict(model=model, contents=denorm_msgs(msgs))
+    if sp:=kwargs.get('system'): payload['system_instruction'] = denorm_system(sp)
+    gen_config = {}
+    if mt:=kwargs.get('max_tokens'):        gen_config['maxOutputTokens'] = mt
+    if thk:=denorm_reasoning(kwargs.get('reasoning_effort'), model): gen_config['thinkingConfig'] = thk
+    if (temp:=kwargs.get('temperature')) is not None: gen_config['temperature'] = temp
+    if gen_config: payload['generation_config'] = gen_config
+    gem_tools = denorm_tool_schs(kwargs.get('tools')) if kwargs.get('tools') else []
+    if (wopts:=kwargs.get('web_search_options')) is not None: gem_tools.append(denorm_web_search(wopts))
+    if gem_tools:
+        payload['tools'] = gem_tools
+        has_fn  = any('functionDeclarations' in t for t in gem_tools)
+        has_srv = any(k in t for t in gem_tools for k in ('googleSearch','codeExecution','googleSearchRetrieval'))
+        if has_fn and has_srv: payload.setdefault('tool_config', {})['includeServerSideToolInvocations'] = True
+    if tchc:=denorm_tool_choice(kwargs.get('tool_choice')): payload.setdefault('tool_config', {}).update(tchc)
+    if kwargs.get('stream'): payload.update(stream=True, _query={"alt": "sse"})
+    return payload
+
+# %% ../nbs/05_gemini.ipynb #60d52c1f
+def get_hdrs(api_key=None):
+    return {"x-goog-api-key": get_api_key(api_key, 'GEMINI_API_KEY')}
+
+# %% ../nbs/05_gemini.ipynb #4ee3891f
+def cost(usage, m):
+    raw = usage.raw
+    prompt_tot = raw.get('promptTokenCount', 0)
+    tier = '_above_200k_tokens' if prompt_tot > 200_000 else ''
+    in_rate    = m.get(f'input_cost_per_token{tier}')       or m.input_cost_per_token
+    out_rate   = m.get(f'output_cost_per_token{tier}')      or m.output_cost_per_token
+    cache_rate = m.get(f'cache_read_input_token_cost{tier}')or m.get('cache_read_input_token_cost', 0)
+    audio_rate = m.get('input_cost_per_audio_token')  # None if not priced separately
+
+    cached = raw.get('cachedContentTokenCount', 0)
+    # Gemini 3 Pro supports bills audio at the standard input rate (no separate input_cost_per_audio_token key in the metadata)
+    audio  = sum(d['tokenCount'] for d in raw.get('promptTokensDetails', []) if d.get('modality')=='AUDIO') if audio_rate else 0
+    in_txt = prompt_tot - cached - audio
+
+    thoughts = raw.get('thoughtsTokenCount', 0) or 0
+    cands    = raw.get('candidatesTokenCount', 0) or 0
+    reason_rate = m.get('output_cost_per_reasoning_token') or out_rate
+
+    cost  = in_txt * in_rate + cands * out_rate
+    cost += cached * cache_rate
+    cost += audio  * (audio_rate or 0)
+    cost += thoughts * reason_rate
+    return cost
+
+# %% ../nbs/05_gemini.ipynb #f7c0b989
+api_ns = dict(norm_tool_calls=norm_tool_calls,
+                norm_parts=norm_parts,
+                norm_finish=norm_finish,
+                norm_usage=norm_usage,
+                acollect_stream=acollect_stream,
+                mk_payload=mk_payload,
+                cost=cost,
+                get_hdrs=get_hdrs,
+                op_path=('models.generate_content','models.stream_generate_content'))
+api_registry.register('gemini', **api_ns)

fastllm/openai_chat.py

@@ -0,0 +1,219 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/03_oai_chat.ipynb.
+
+# %% auto #0
+__all__ = ['api_ns', 'norm_tool_calls', 'norm_finish', 'norm_parts', 'norm_sse_event', 'delta_index_fn', 'acollect_stream',
+           'denorm_tool_use', 'denorm_assistant', 'denorm_tool', 'denorm_msgs', 'denorm_tool_schs',
+           'denorm_tool_choice', 'denorm_reasoning', 'denorm_web_search', 'denorm_system', 'denorm_user',
+           'denorm_image', 'denorm_audio', 'denorm_file', 'denorm_tool_result', 'mk_payload', 'get_hdrs', 'cost']
+
+# %% ../nbs/03_oai_chat.ipynb #493e3606
+import json
+from collections import Counter
+from fastcore.utils import *
+from fastcore.meta import *
+from fastspec.errors import api_error_from_event
+
+from .types import *
+from .streaming import *
+from .streaming import mk_acollect_stream
+from .openai_responses import norm_usage
+
+# %% ../nbs/03_oai_chat.ipynb #b4f0e4d0
+def norm_tool_calls(resp, delta=False):
+    "Extract Chat Completions tool calls as normalized tool calls, optionally from streaming delta events"
+    out = []
+    key = 'delta' if delta else 'message'
+    if not   (tcs:= nested_idx(resp, 'choices', 0, key, 'tool_calls')): return out
+    for tc in tcs:
+        if not (fn:=tc.get("function")): continue
+        extra = {k:v for k,v in tc.items() if k not in ("id","function")}
+        args  = json.loads(fn.get("arguments")) if not delta else {'_delta': fn.get("arguments")}
+        out.append(ToolCall(id=tc.get("id",""), name=fn.get("name",""), arguments=args, extra=extra))
+    return out
+
+# %% ../nbs/03_oai_chat.ipynb #b387d62d
+def norm_finish(resp, tcs=None):
+    "Canonicalize finish_reason to OpenAI Chat values: stop, tool_calls, length, content_filter."
+    r = nested_idx(resp, 'choices', 0, 'finish_reason')
+    return FinishReason.tool_calls if r==FinishReason.stop and any(~L(tcs).attrgot('server')) else r 
+
+# %% ../nbs/03_oai_chat.ipynb #5abf90bb
+def norm_parts(resp):
+    "Normalize chat.completions response object into Completion."
+    msg = nested_idx(resp, 'choices', 0, 'message') or {}
+    parts = []
+    if thinking := msg.get('reasoning_content'): parts.append(Part(type="thinking", text=thinking))
+    if cts := msg.get('content'): parts.append(Part(type="text",text=cts,data=dict(citations=msg.get('annotations',[]))))
+    if ref := msg.get('refusal'): parts.append(Part(type="refusal",text=ref))
+    tcs = norm_tool_calls(resp)
+    for tc in tcs: 
+        tdata = {**tc.extra, 'id':tc.id, 'name':tc.name, 'arguments':tc.arguments, 'server':tc.server}
+        parts.append(Part(type="tool_use", data=tdata))
+    return parts
+
+# %% ../nbs/03_oai_chat.ipynb #9baac40e
+def norm_sse_event(ev, **kwargs):
+    "Normalize a chat completion stream event."
+    # usage always arrives as a single final event with choices: []
+    fin = nested_idx(ev, 'choices', 0, 'finish_reason')
+    tcs = norm_tool_calls(ev, delta=True)
+    if (dlt:=nested_idx(ev, 'choices', 0, 'delta')) is not None:
+        text, thinking, refusal = dlt.get('content'), dlt.get('reasoning_content'), dlt.get('refusal')
+    else: text, thinking, refusal = None,None,None
+    if ev.get("error"): raise api_error_from_event(ev)
+    return Delta(text=text, thinking=thinking, refusal=refusal, tool_calls=tcs, finish_reason=fin, usage=norm_usage(ev), raw=ev, **kwargs)
+
+# %% ../nbs/03_oai_chat.ipynb #cfec45b4
+def delta_index_fn(d, typ, last_typ, last_idx):
+    'Returns accumulation index for current delta and updated last idx'
+    if d.tool_calls: 
+        tc_idx = nested_idx(d.tool_calls, 0, 'extra', 'index')
+        return f"tool_{tc_idx}", last_idx
+    if not (last_typ or last_idx): return 0,0
+    if typ == last_typ: return last_idx, last_idx
+    return last_idx + 1, last_idx + 1
+
+# %% ../nbs/03_oai_chat.ipynb #e7f8965b
+@delegates(mk_acollect_stream, but=['index_fn', 'api_name'])
+async def acollect_stream(resp, **kwargs):
+    res = mk_acollect_stream(norm_and_yield(resp, norm_sse_event), index_fn=delta_index_fn, api_name='openai_chat', **kwargs)
+    async for o in res: yield o
+
+# %% ../nbs/03_oai_chat.ipynb #5a7129f1
+def denorm_tool_use(p:Part):
+    "Convert canonical tool_use Part to OpenAI Chat tool_call dict."
+    return dict(id=p.data.get('id'), type='function', function=dict(name=p.data.get('name'), arguments=json.dumps(p.data.get('arguments', '{}'))))
+
+def denorm_assistant(m:Msg):
+    "Convert canonical assistant Msg to OpenAI Chat assistant message + synthetic tool responses for server tools."
+    tcs, srv_responses, texts = [], [], []
+    for p in m.content:
+        if p.type == PartType.tool_use:
+            tcs.append(denorm_tool_use(p))
+            if p.data.get('server'):
+                srv_txt = f"[Server tool `{p.data['name']}` executed successfully, results are generated]"
+                srv_responses.append(dict(role='tool', tool_call_id=p.data['id'], content=srv_txt))
+        elif p.type == PartType.text: texts.append(p)
+    msg = dict(role='assistant')
+    if texts: msg['content'] = texts[0].text if len(texts)==1 else [dict(type='text', text=p.text or '') for p in texts]
+    if tcs: msg['tool_calls'] = tcs
+    thinking = [p for p in m.content if p.type == PartType.thinking]
+    if thinking: msg['reasoning_content'] = ''.join(p.text or '' for p in thinking)
+    return [msg] + srv_responses
+
+def denorm_tool(m:Msg):
+    "Convert canonical tool Msg to list of OpenAI Chat tool messages."
+    return [denorm_tool_result(p) for p in m.content if p.type == PartType.tool_result]
+
+def denorm_msgs(msgs:list[Msg]):
+    "Convert list of canonical Msgs to OpenAI Chat messages."
+    res = []
+    for m in msgs:
+        if   m.role == 'user':      res.append(denorm_user(m))
+        elif m.role == 'assistant': res.extend(denorm_assistant(m))
+        elif m.role == 'tool':      res.extend(denorm_tool(m))
+    return res
+
+# %% ../nbs/03_oai_chat.ipynb #76f84455
+def denorm_tool_schs(tools):
+    "Passthrough — canonical format is already OpenAI Chat."
+    return tools
+
+# %% ../nbs/03_oai_chat.ipynb #659fdab9
+def denorm_tool_choice(v):
+    "Map canonical tool_choice to OpenAI Chat format."
+    _tc_modes = {'auto', 'required', 'any', 'force', 'none', 'off', 'disabled'}
+    if v is None: return None
+    if v in _tc_modes: return v if v in ('auto','none','required') else {'any':'required','force':'required','off':'none','disabled':'none'}[v]
+    return {'type': 'function', 'function': {'name': v}}
+
+# %% ../nbs/03_oai_chat.ipynb #02ba4ab7
+def denorm_reasoning(v): 
+    if v is None: return None
+    return v  # passthrough as reasoning_effort param
+
+# %% ../nbs/03_oai_chat.ipynb #57b4969e
+def denorm_web_search(v): return v
+
+# %% ../nbs/03_oai_chat.ipynb #0f8cb4d1
+def denorm_system(sp, msgs): 
+    msgs.insert(0, dict(role='system', content=sys_text(part_txt(sp))))
+    return msgs
+
+# %% ../nbs/03_oai_chat.ipynb #13654225
+def denorm_user(m:Msg):
+    "Convert canonical user Msg to OpenAI Chat user message."
+    parts = []
+    for p in m.content:
+        if   p.type == PartType.text:        parts.append({"type": "text", "text": p.text or ""})
+        elif p.type == PartType.input_image: parts.append(denorm_image(p))
+        elif p.type == PartType.input_audio: parts.append(denorm_audio(p))
+        elif p.type == PartType.input_video: raise ValueError("OpenAI Chat API does not support video input")
+        elif p.type == PartType.input_file:  parts.append(denorm_file(p))
+    if len(parts) == 1 and parts[0].get('type') == 'text': return dict(role='user', content=parts[0]['text'])
+    return dict(role='user', content=parts)
+
+# %% ../nbs/03_oai_chat.ipynb #82f3615b
+def denorm_image(p): return {"type": "image_url", "image_url": {"url": p.text}}
+
+# %% ../nbs/03_oai_chat.ipynb #ab69ef9a
+def denorm_audio(p):
+    _mime_audio_fmt = {'audio/wav':'wav', 'audio/mpeg':'mp3', 'audio/mp3':'mp3'}
+    if not (b64:=data_url(p.text)): raise ValueError("OpenAI Chat audio input requires base64 data URL")
+    return {"type": "input_audio", "input_audio": {"data": b64[1], "format": _mime_audio_fmt.get(b64[0], 'wav')}}
+
+# %% ../nbs/03_oai_chat.ipynb #e2cd77ad
+def denorm_file(p):
+    if (b64:=data_url(p.text)): return {"type": "file", "file": {"file_data": p.text, "filename": f"upload.{b64[0].split('/')[-1]}"}}
+    raise ValueError("OpenAI Chat file input requires base64 data URL or file_id, not URLs")
+
+# %% ../nbs/03_oai_chat.ipynb #0e9751c8
+def denorm_tool_result(p:Part):
+    "Convert canonical tool_result Part to OpenAI Chat tool message."
+    if isinstance(p.text, list): raise ValueError("OpenAI Chat does not support media in tool results")
+    return dict(role='tool', tool_call_id=p.data.get('id') or p.data.get('call_id', ''), content=str(p.text))
+
+# %% ../nbs/03_oai_chat.ipynb #d2f55686
+@delegates(payload_kwargs)
+def mk_payload(msgs, model, **kwargs):
+    payload = dict(model=model, messages=denorm_msgs(msgs))
+    if sp:=kwargs.get('system'):            payload['messages'] = denorm_system(sp, payload['messages'])
+    if kwargs.get('stream'):                payload.update(stream=True, stream_options={"include_usage": True})
+    if mt:=kwargs.get('max_tokens'):        payload['max_tokens'] = mt
+    if tools:=kwargs.get('tools'):          payload['tools'] = denorm_tool_schs(tools)
+    if tchc:=kwargs.get('tool_choice'):     payload['tool_choice'] = denorm_tool_choice(tchc)
+    if thk:=kwargs.get('reasoning_effort'): payload['reasoning_effort'] = denorm_reasoning(thk)
+    if (wopts:=kwargs.get('web_search_options')) is not None: 
+        payload['web_search_options'] = denorm_web_search(wopts)
+    if (temp:=kwargs.get('temperature')) is not None: payload['temperature'] = temp
+    return payload
+
+# %% ../nbs/03_oai_chat.ipynb #16e813d2
+def get_hdrs(api_key=None):
+    return {"Authorization": f"Bearer {get_api_key(api_key, 'OPENAI_API_KEY')}"}
+
+# %% ../nbs/03_oai_chat.ipynb #f89e2bf6
+def cost(usage, m):
+    raw = usage.raw
+    pd, cd = raw.get('prompt_tokens_details', {}), raw.get('completion_tokens_details', {})
+    cached = pd.get('cached_tokens', 0)
+    in_audio, out_audio = pd.get('audio_tokens', 0), cd.get('audio_tokens', 0)
+    in_txt  = raw['prompt_tokens']     - cached - in_audio
+    out_txt = raw['completion_tokens'] - out_audio
+    cost  = in_txt  * m.input_cost_per_token  + out_txt * m.output_cost_per_token
+    cost += cached  * m.get('cache_read_input_token_cost', 0)
+    cost += in_audio  * m.get('input_cost_per_audio_token', 0)
+    cost += out_audio * m.get('output_cost_per_audio_token', 0)
+    return cost
+
+# %% ../nbs/03_oai_chat.ipynb #e2b0908e
+api_ns = dict(norm_tool_calls=norm_tool_calls,
+                norm_parts=norm_parts,
+                norm_finish=norm_finish,
+                norm_usage=norm_usage,
+                acollect_stream=acollect_stream,
+                mk_payload=mk_payload,
+                cost=cost,
+                get_hdrs=get_hdrs, 
+                op_path=('chat.create_chat_completion','chat.create_chat_completion'))
+api_registry.register('openai_chat', **api_ns)