#!/usr/bin/env python3
"""Build the OpenAI *tools* fragments (tools, parameters, streaming events, containers+skills endpoints).

Inputs : sources/openai/openapi/openapi-master.yaml (schemas), model pages "Supported tools" sections,
         live findings hard-coded below (from tmp-live/tools/*.json, run 2026-09-18).
Outputs: generated/fragments/tools/openai-tools.json
         generated/fragments/parameters/openai-tools.json
         generated/fragments/streaming-events/openai-tools.json
         generated/fragments/endpoints/openai-containers-skills.json
Run    : .venv/bin/python scripts/build_openai_tools_fragments.py
"""
from __future__ import annotations

import glob
import json
import re
from pathlib import Path

import yaml

ROOT = Path(__file__).resolve().parent.parent
SPEC = ROOT / "sources/openai/openapi/openapi-master.yaml"
FRAG = ROOT / "generated/fragments"
RETRIEVED = "2026-09-18"
VERIFIED = "2026-09-18"
DOCS = "https://developers.openai.com/api/docs"
REF = "https://developers.openai.com/api/reference"

spec = yaml.load(SPEC.read_text(), Loader=yaml.CSafeLoader)
S = spec["components"]["schemas"]


def resolve(o, depth=0, seen=()):
    """Inline $refs (bounded) so fragments are self-contained."""
    if depth > 14:
        return {"$comment": "depth-limited"}
    if isinstance(o, dict):
        if "$ref" in o:
            n = o["$ref"].split("/")[-1]
            if n in seen:
                return {"$ref": n, "$comment": "recursive"}
            return resolve(S[n], depth + 1, seen + (n,))
        return {k: resolve(v, depth + 1, seen) for k, v in o.items()
                if k not in ("x-oaiMeta", "x-stainless-naming", "x-oaiTypeLabel", "x-oaiExpandable")}
    if isinstance(o, list):
        return [resolve(x, depth + 1, seen) for x in o]
    return o


def src(url: str) -> dict:
    return {"url": url, "retrieved_at": RETRIEVED}


def ver(result: str, status: int, note: str, method: str = "live_api") -> dict:
    return {"method": method, "verified_at": VERIFIED, "result": result, "http_status": status, "request_note": note}


# --------------------------------------------------------------------------- model matrix (from model pages)
MODEL_TOOL_KEY = {  # tool type -> key used in model pages "Supported tools"
    "function": "function_calling", "custom": "function_calling", "namespace": "function_calling",
    "web_search": "web_search", "web_search_2025_08_26": "web_search", "web_search_preview": "web_search",
    "web_search_preview_2025_03_11": "web_search", "file_search": "file_search", "code_interpreter": "code_interpreter",
    "image_generation": "image_generation", "mcp": "mcp", "shell": "hosted_shell", "apply_patch": "apply_patch",
    "computer": "computer_use", "computer_use_preview": "computer_use", "tool_search": "tool_search",
    "skill_reference": "skills",
}
matrix: dict[str, list[str]] = {}
for f in sorted(glob.glob(str(ROOT / "sources/openai/pages/api/docs/models/*.md"))):
    t = Path(f).read_text()
    m = re.search(r"## Supported tools\s*\n(.*?)(?=\n## |\Z)", t, re.S)
    if m:
        matrix[Path(f).stem] = re.findall(r"^- *([a-z_0-9]+)", m.group(1), re.M)


def models_for(tool_type: str) -> list[str]:
    key = MODEL_TOOL_KEY.get(tool_type)
    return sorted(m for m, tools in matrix.items() if key in tools) if key else []


# --------------------------------------------------------------------------- tool records
RESP = "POST /v1/responses"
CHAT = "POST /v1/chat/completions"
LIVE = ["DOCUMENTED", "LIVE_VERIFIED"]
NANO = "gpt-5.4-nano"

TOOL_EVENTS = {
    "function": ["response.output_item.added", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.output_item.done"],
    "custom": ["response.output_item.added", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "response.output_item.done"],
    "web_search": ["response.output_item.added", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.output_item.done", "response.output_text.annotation.added"],
    "file_search": ["response.output_item.added", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.completed", "response.output_item.done", "response.output_text.annotation.added"],
    "code_interpreter": ["response.output_item.added", "response.code_interpreter_call.in_progress", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.output_item.done", "response.output_text.annotation.added"],
    "image_generation": ["response.output_item.added", "response.image_generation_call.in_progress", "response.image_generation_call.generating", "response.image_generation_call.partial_image", "response.image_generation_call.completed", "response.output_item.done"],
    "mcp": ["response.output_item.added", "response.mcp_list_tools.in_progress", "response.mcp_list_tools.completed", "response.mcp_list_tools.failed", "response.mcp_call.in_progress", "response.mcp_call_arguments.delta", "response.mcp_call_arguments.done", "response.mcp_call.completed", "response.mcp_call.failed", "response.output_item.done"],
    "shell": ["response.output_item.added", "response.shell_call_command.added", "response.shell_call_command.delta", "response.shell_call_command.done", "response.shell_call_output_content.delta", "response.shell_call_output_content.done", "response.output_item.done"],
    "apply_patch": ["response.output_item.added", "response.apply_patch_call_operation_diff.delta", "response.apply_patch_call_operation_diff.done", "response.output_item.done"],
    "computer_use_preview": ["response.output_item.added", "response.output_item.done"],
    "computer": ["response.output_item.added", "response.output_item.done"],
    "tool_search": ["response.output_item.added", "response.output_item.done"],
    "namespace": ["response.output_item.added", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.output_item.done"],
    "programmatic_tool_calling": ["response.output_item.added", "response.output_item.done"],
    "local_shell": [],
    "skill_reference": [],
}

TOOL_SCHEMA = {
    "function": "FunctionTool", "custom": "CustomToolParam", "namespace": "NamespaceToolParam", "tool_search": "ToolSearchToolParam",
    "programmatic_tool_calling": "ProgrammaticToolCallingParam", "web_search": "WebSearchTool", "web_search_2025_08_26": "WebSearchTool",
    "web_search_preview": "WebSearchPreviewTool", "web_search_preview_2025_03_11": "WebSearchPreviewTool", "file_search": "FileSearchTool",
    "code_interpreter": "CodeInterpreterTool", "computer": "ComputerTool", "computer_use_preview": "ComputerUsePreviewTool",
    "image_generation": "ImageGenTool", "mcp": "MCPTool", "shell": "FunctionShellToolParam", "local_shell": "LocalShellToolParam",
    "apply_patch": "ApplyPatchToolParam", "skill_reference": "SkillReferenceParam",
}
RESULT_ITEM = {
    "function": ["FunctionToolCall", "FunctionCallOutputItemParam"], "custom": ["CustomToolCall", "CustomToolCallOutput"],
    "namespace": ["FunctionToolCall", "CustomToolCall"], "tool_search": ["ToolSearchCall", "ToolSearchOutput"],
    "programmatic_tool_calling": ["FunctionToolCall"], "web_search": ["WebSearchToolCall"], "web_search_2025_08_26": ["WebSearchToolCall"],
    "web_search_preview": ["WebSearchToolCall"], "web_search_preview_2025_03_11": ["WebSearchToolCall"], "file_search": ["FileSearchToolCall"],
    "code_interpreter": ["CodeInterpreterToolCall"], "computer": ["ComputerToolCall", "ComputerToolCallOutput"],
    "computer_use_preview": ["ComputerToolCall", "ComputerToolCallOutput"], "image_generation": ["ImageGenToolCall"],
    "mcp": ["MCPListTools", "MCPToolCall", "MCPApprovalRequest", "MCPApprovalResponse"], "shell": ["FunctionShellCall", "FunctionShellCallOutputItemParam"],
    "local_shell": ["LocalShellToolCall", "LocalShellToolCallOutput"], "apply_patch": ["ApplyPatchToolCall", "ApplyPatchToolCallOutputItemParam"],
    "skill_reference": ["FunctionShellCall"],
}

TC_COMMON = {"modes": ["none", "auto", "required"], "allowed_tools": {"type": "allowed_tools", "mode": "auto|required", "tools": ["{type,name,...}"]}}

T = {}  # per-tool hand-written metadata


def tool(type_, name, category, description, endpoints, tc, parallel, result_shape, billing, limitations, security, status, examples, verification, extra_sources=(), beta=None, notes=None, models=None):
    ex_dir = examples
    rec = {
        "provider": "openai", "name": name, "type": type_, "category": category, "description": description,
        "compatible_models": models if models is not None else models_for(type_),
        "compatible_endpoints": endpoints,
        "parameters_schema": resolve(S[TOOL_SCHEMA[type_]]),
        "tool_choice_support": tc, "parallel": parallel,
        "streaming_events": TOOL_EVENTS.get(type_, []),
        "result_shape": {"items": [{"schema_name": n, "type": (S[n].get("properties", {}).get("type", {}).get("enum") or [None])[0], "schema": resolve(S[n])} for n in RESULT_ITEM.get(type_, [])],
                         "summary": result_shape},
        "billing": billing, "limitations": limitations, "security": security, "beta_header": beta, "status": status,
        "examples": {"curl": f"examples/openai/tools/{ex_dir}/{ex_dir.replace('-', '_')}.sh", "python": f"examples/openai/tools/{ex_dir}/{ex_dir.replace('-', '_')}.py", "typescript": f"examples/openai/tools/{ex_dir}/{ex_dir.replace('-', '_')}.ts"} if ex_dir else {},
        "verification": verification,
        "sources": [src(u) for u in extra_sources] + [src(f"{REF}/resources/responses/methods/create"), src("https://github.com/openai/openai-openapi (openapi-master.yaml)")],
        "last_verified": VERIFIED,
    }
    if notes:
        rec["notes"] = notes
    T[type_] = rec


PRICING = f"{DOCS}/pricing#built-in-tools"

tool("function", "Function calling (custom function tool)", "client",
     "Developer-defined function described by a JSON Schema. The model emits a `function_call` item (name + JSON `arguments`); the application executes it and returns a `function_call_output` item. Supports `strict` schemas (structured outputs), `async: true` (GPT-6 Astra+), `defer_loading` (tool search), `allowed_callers` (programmatic tool calling), `output_schema`, and grouping in `namespace` tools.",
     [RESP, CHAT, "POST /v1/realtime (session.tools)", "Agents API (agent tool config)"],
     {**TC_COMMON, "specific": {"type": "function", "name": "<fn>"}, "chat_completions": {"type": "function", "function": {"name": "<fn>"}}},
     {"supported": True, "parameter": "parallel_tool_calls (default true)", "notes": "Built-in tools cannot be included in a parallel function-call batch (GPT-5+). Fine-tuned models: strict mode disabled when several functions are called in one turn."},
     "Output item `function_call` {id, call_id, name, arguments (JSON string), status, namespace?, caller?, async?}; reply with input item `function_call_output` {call_id, output: string | content array}.",
     {"model": "Function definitions are injected into the system message and billed as input tokens; call arguments are output tokens.", "per_call": None, "source": PRICING},
     ["Strict mode requires all properties in `required`, `additionalProperties: false`, supported JSON Schema subset; strict schemas are cached and not eligible for ZDR.", "Soft guidance: < 20 functions available at the start of a turn.", "Chat Completions: `strict` defaults to false; Responses: omitted `strict` = best effort strict.", "GPT-6 Astra requires the Responses API for tool calling."],
     ["Validate arguments server-side (schema/regex) before executing; the model can be prompt-injected by tool outputs.", "Reasoning items returned alongside tool calls must be passed back with the outputs (reasoning models)."],
     LIVE, "function-calling",
     {"forced_call": ver("success", 200, f"{NANO}: tool_choice {{type:function,name:get_weather}} -> function_call item, then function_call_output round trip via previous_response_id -> message"),
      "streaming": ver("success", 200, "response.output_item.added -> response.function_call_arguments.delta x N -> response.function_call_arguments.done -> response.output_item.done"),
      "strict_invalid_schema": ver("success", 400, "missing additionalProperties:false -> 400 invalid_request_error code=invalid_function_parameters param=tools[0].parameters"),
      "allowed_tools": ver("success", 200, "tool_choice {type:allowed_tools, mode:required, tools:[{type:function,name:get_weather}]} + parallel_tool_calls:false -> function_call"),
      "chat_completions": ver("success", 200, "gpt-4.1-nano chat.completions tool_choice forced -> choices[0].message.tool_calls[0].function")},
     [f"{DOCS}/guides/function-calling", f"{DOCS}/guides/async-tool-calling"])

tool("custom", "Custom tool (free-form text or CFG grammar)", "client",
     "Like a function but the model emits an arbitrary string (`custom_tool_call.input`) instead of JSON arguments. `format` is `{type: text}` (default) or `{type: grammar, syntax: lark|regex, definition}` constraining sampling (LLGuidance; Rust regex syntax).",
     [RESP, CHAT], {**TC_COMMON, "specific": {"type": "custom", "name": "<tool>"}, "chat_completions": {"type": "custom", "custom": {"name": "<tool>"}}},
     {"supported": True, "parameter": "parallel_tool_calls"},
     "Output item `custom_tool_call` {id, call_id, name, input: string, status}; reply with `custom_tool_call_output` {call_id, output}.",
     {"model": "Token billing only.", "source": PRICING},
     ["Grammar too complex -> API error; keep terminals bounded; no verbose regex mode; Lark subset only.", "Chat Completions shape differs: {type: custom, custom: {name, description, format: {type: grammar, grammar: {syntax, definition}}}}."],
     ["Grammar constrains syntax, not semantics — still validate the input before acting on it."],
     LIVE, "custom-tools",
     {"regex_grammar": ver("success", 200, f"{NANO}: format grammar regex ^(yes|no)$ forced -> custom_tool_call input='yes'"),
      "text_format": ver("success", 200, f"{NANO}: default text format, tool_choice required -> custom_tool_call"),
      "streaming": ver("success", 200, "response.custom_tool_call_input.delta -> .done")},
     [f"{DOCS}/guides/function-calling#custom-tools"])

tool("namespace", "Namespace (group of function/custom tools)", "client",
     "Groups function/custom tools under a shared namespace with its own description. Calls come back as `function_call`/`custom_tool_call` items carrying a `namespace` field. Namespaces are the recommended unit for deferred loading with `tool_search`.",
     [RESP], {**TC_COMMON, "note": "tool_choice targets the inner tool by name"}, {"supported": True, "parameter": "parallel_tool_calls"},
     "Inner tool call items gain `namespace: <name>`; `function_call_output` may echo `namespace`.",
     {"model": "Token billing only.", "source": PRICING},
     ["`defer_loading` applies to the tools inside the namespace, not the namespace object.", "Model pages do not list `namespace` separately; availability follows function calling (verified on gpt-5.4-nano)."],
     ["Same as function calling."], LIVE, "function-calling",
     {"namespace_call": ver("success", 200, f"{NANO}: namespace 'weather' wrapping get_weather, tool_choice required -> function_call with namespace='weather'")},
     [f"{DOCS}/guides/function-calling#namespaces", f"{DOCS}/guides/tools-tool-search"])

tool("tool_search", "Tool search (deferred tool loading)", "hosted",
     "Lets the model discover tools marked `defer_loading: true` (functions, namespaces, MCP servers) on demand. `execution: server` (hosted, default) emits `tool_search_call` + `tool_search_output` items automatically; `execution: client` stops after `tool_search_call` and the app returns a `tool_search_output` item with tool definitions. Deferred tools are loaded at the end of context to preserve prompt caching.",
     [RESP, "Agents API (session tools)"], {"modes": ["auto", "required", "none"], "note": "tool_choice applies to the tools currently callable in the turn"},
     {"supported": False, "notes": "Search happens before the eventual function call."},
     "Output items `tool_search_call` {id, call_id|null, execution, arguments: {paths: [...]}, status} then `tool_search_output` {id, call_id, execution, tools: [tool definitions], status}, then normal tool calls.",
     {"model": "Token billing only; saves input tokens by not sending deferred definitions up front.", "source": PRICING},
     ["Responses API: only gpt-5.4 and later models (gpt-5.4-nano page does not list tool_search).", "`additional_tools` input item can inject tools mid-conversation."],
     ["Client-executed search lets the app decide which tools exist per turn — keep an allowlist."], LIVE, "tool-search",
     {"hosted": ver("success", 200, "gpt-5.4-mini: tool_search + namespace with deferred get_weather -> tool_search_call{arguments:{paths:['weather']}} , tool_search_output{tools:[namespace]}, function_call{namespace:'weather'}")},
     [f"{DOCS}/guides/tools-tool-search"])

tool("programmatic_tool_calling", "Programmatic Tool Calling", "hosted",
     "Hosted tool letting the model write JavaScript (isolated V8, no Node/network) that orchestrates other tools. Eligible tools opt in with `allowed_callers: [\"programmatic\"]` (function, custom, mcp, apply_patch, shell, code_interpreter). Tool calls emitted from the program carry `caller: {type: program, caller_id}`.",
     [RESP, "Agents API (enabled by default)"], {"modes": ["auto", "required", "none"], "specific": {"type": "programmatic_tool_calling"}},
     {"supported": True, "notes": "Program can call tools in parallel inside the runtime."},
     "Standard Responses object; nested `function_call` items with caller.type = program; results returned as `function_call_output` with the same caller.",
     {"model": "Token billing only.", "source": PRICING},
     ["Check the model page before enabling; not listed on gpt-5.4-nano.", "Supports ZDR without a persistent container.", "Not live-tested (no cheap eligible model identified)."],
     ["Require application-level approval for high-impact actions regardless of caller; MCP `require_approval` can pause the program."],
     ["DOCUMENTED", "UNVERIFIED"], "", {"docs": ver("success", 0, "not called", "docs_only")}, [f"{DOCS}/guides/tools-programmatic-tool-calling"], models=[])

WS_LIMITS = ["Search context window limited to 128k even on 1M models.", "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.", "Up to 100 allowed_domains / 100 blocked_domains.", "Rate limits = underlying model tiered limits.", "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`."]
WS_SEC = ["Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.", "`external_web_access: false` runs cache-only."]
WS_BILL = {"per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates", "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)", "source": PRICING}
tool("web_search", "Web search (hosted)", "hosted",
     "Hosted web search. Actions `search` (with `queries`, `sources` when `include: [web_search_call.action.sources]`), `open_page` and `find_in_page` (reasoning models). Citations come back as `url_citation` annotations on the message. Live fields echoed by the API but absent from the OpenAPI spec: `return_token_budget` (default|unlimited), `filters.blocked_domains`, `search_content_types` ([text, image]).",
     [RESP, "Realtime/Live (web_search tool in Live sessions)", "Agents API"],
     {**TC_COMMON, "specific": {"type": "web_search"}, "note": "Live: tool_choice {type: web_search} accepted and echoed back as {type: web_search_preview}; spec ToolChoiceTypes enum only lists web_search_preview."},
     {"supported": False, "notes": "Built-in tools are not batched with parallel function calls."},
     "Output item `web_search_call` {id, status, action: {type: search|open_page|find_in_page, query, queries, sources: [{type: url, url} | {type: api, name: oai-time|oai-weather|oai-sports|oai-finance}]}}; message annotations `url_citation` {url, title, start_index, end_index}.",
     WS_BILL, WS_LIMITS, WS_SEC, LIVE, "web-search",
     {"forced_search": ver("success", 200, f"{NANO}: tool_choice {{type:web_search}}, search_context_size low, include web_search_call.action.sources -> web_search_call action.type=search, sources=[{{type:'api',name:'oai-time'}}] (non-URL source shape not in spec); answer 'Saturday, September 19, 2026 Toronto'; usage 4671 in / 329 out"),
      "auto_no_search": ver("success", 200, "same prompt with tool_choice auto -> model answered without calling the tool (search is optional under auto)"),
      "max_output_tokens_64": ver("failure", 200, "first attempt with max_output_tokens 64 ended status=incomplete (reason max_output_tokens) before any tool call — leave >= 300 tokens for reasoning+search"),
      "streaming": ver("success", 200, "response.web_search_call.in_progress -> searching -> completed")},
     [f"{DOCS}/guides/tools-web-search", PRICING])
tool("web_search_2025_08_26", "Web search (dated snapshot 2025-08-26)", "hosted", "Dated alias of `web_search` (same schema, WebSearchTool).", [RESP], {**TC_COMMON}, {"supported": False},
     "Same as web_search.", WS_BILL, WS_LIMITS, WS_SEC, ["DOCUMENTED", "UNVERIFIED"], "web-search", {"docs": ver("success", 0, "alias not called", "docs_only")}, [f"{DOCS}/guides/tools-web-search"])
tool("web_search_preview", "Web search preview (legacy)", "hosted",
     "Earlier hosted web search tool kept for legacy integrations. Supports `user_location`, `search_context_size`, `search_content_types`; does not support `filters`, `external_web_access`, `return_token_budget`. Docs: migrate to `web_search`.",
     [RESP], {**TC_COMMON, "specific": {"type": "web_search_preview"}}, {"supported": False}, "Same `web_search_call` item.", WS_BILL,
     WS_LIMITS + ["Docs recommend migrating to web_search."], WS_SEC, ["DOCUMENTED", "LEGACY", "UNVERIFIED"], "web-search",
     {"docs": ver("success", 0, "not called (legacy)", "docs_only")}, [f"{DOCS}/guides/tools-web-search"])
tool("web_search_preview_2025_03_11", "Web search preview (dated snapshot 2025-03-11)", "hosted", "Dated alias of `web_search_preview`.", [RESP], {**TC_COMMON, "specific": {"type": "web_search_preview_2025_03_11"}}, {"supported": False},
     "Same `web_search_call` item.", WS_BILL, WS_LIMITS, WS_SEC, ["DOCUMENTED", "LEGACY", "UNVERIFIED"], "web-search", {"docs": ver("success", 0, "not called", "docs_only")}, [f"{DOCS}/guides/tools-web-search"])

tool("file_search", "File search (vector stores)", "hosted",
     "Semantic + keyword (hybrid) retrieval over vector stores. Configure `vector_store_ids`, `max_num_results` (1-50), `filters` (comparison/compound on file attributes), `ranking_options` {ranker, score_threshold, hybrid_search}. Results are hidden unless `include: [file_search_call.results]`; citations are `file_citation` annotations.",
     [RESP, "Assistants API (legacy)"], {**TC_COMMON, "specific": {"type": "file_search"}}, {"supported": False},
     "Output item `file_search_call` {id, status, queries: [...], results: [{file_id, filename, score, text, attributes, vector_store_id}] | null} + message with `file_citation` annotations.",
     {"per_call": "$2.50 / 1k calls", "storage": "$0.10 / GB / day (1 GB free)", "source": PRICING},
     ["max_num_results 1-50.", "Deep research models support only `type` and `vector_store_ids`.", "Vector store CRUD is documented in the vector-stores fragment (other agent)."],
     ["Only upload trusted files: retrieved text is model input (prompt injection)."], LIVE, "file-search",
     {"search": ver("success", 200, f"{NANO}: vector store 'atlas-tools-agent' + 1 txt file, include file_search_call.results -> file_search_call queries=[3 rewrites], results[0].score=0.7626, text returned; answer PELICAN-42; results[0].vector_store_id was '' (empty string, spec says string)"),
      "max_output_tokens_32": ver("failure", 200, "with max_output_tokens 32 the response was incomplete and file_search_call.status='incomplete'"),
      "streaming": ver("success", 200, "response.file_search_call.in_progress -> searching -> completed")},
     [f"{DOCS}/guides/tools-file-search", PRICING])

tool("code_interpreter", "Code interpreter (Python sandbox container)", "hosted",
     "Runs Python in a sandboxed container. `container` is either a container id (explicit mode, created via POST /v1/containers) or `{type: auto, file_ids?, memory_limit?: 1g|4g|16g|64g, network_policy?}`. Generated files are cited as `container_file_citation` annotations; outputs (`logs`, `image`) are returned only with `include: [code_interpreter_call.outputs]`.",
     [RESP, "Assistants API (legacy)"], {**TC_COMMON, "specific": {"type": "code_interpreter"}}, {"supported": False},
     "Output item `code_interpreter_call` {id, status: in_progress|interpreting|completed|incomplete|failed, container_id, code, outputs: [{type: logs, logs} | {type: image, url}] | null}.",
     {"per_session": "1 GB $0.03 · 4 GB $0.12 · 16 GB $0.48 · 64 GB $1.92 per 20-minute session per container (shared with hosted shell)", "source": PRICING},
     ["Container expires after 20 min of inactivity (auto containers: expires_after last_active_at 20 min); expired containers cannot be revived.", "No outbound network by default (network_policy allowlist/disabled; org allow-list applies).", "Model knows the tool as the 'python tool'."],
     ["Network-enabled containers: prompt-injection driven exfiltration risk; only allowlist trusted domains; use domain_secrets instead of raw credentials."], LIVE, "code-interpreter",
     {"auto_container": ver("success", 200, f"{NANO}: container auto, include code_interpreter_call.outputs -> code 'print(2+2)', outputs [{{type:logs, logs:'4\\n'}}], container_id cntr_…; then GET/LIST/DELETE container 200 (see containers endpoints)"),
      "streaming": ver("success", 0, "not streamed live (cost); events from spec", "docs_only")},
     [f"{DOCS}/guides/tools-code-interpreter", f"{REF}/resources/containers", PRICING])

CU_SEC = ["Isolated browser/VM, site allow-list, treat screen content as untrusted, confirm at the point of risk, enforce step/time/cost limits, acknowledge `pending_safety_checks` explicitly."]
tool("computer_use_preview", "Computer use (preview tool + computer-use-preview model)", "client",
     "Model returns structured GUI actions (`computer_call` with action click/double_click/drag/keypress/move/screenshot/scroll/type/wait and `pending_safety_checks`); the app executes them and returns `computer_call_output` {call_id, output: {type: computer_screenshot, image_url|file_id}, acknowledged_safety_checks}. Requires `display_width`, `display_height`, `environment` (windows|mac|linux|ubuntu|browser). Historically paired with model `computer-use-preview`; newer docs recommend the `computer` tool or code-execution with GPT-6 Astra.",
     [RESP], {**TC_COMMON, "specific": {"type": "computer_use_preview"}}, {"supported": False},
     "`computer_call` {id, call_id, action, pending_safety_checks, status}; input `computer_call_output`; `include: [computer_call_output.output.image_url]` returns screenshot URLs in retrieved items.",
     {"model": "computer-use-preview $3 / 1M input, $12 / 1M output (model page); newer models at their own rates", "source": f"{DOCS}/models/computer-use-preview"},
     ["Requires `truncation: auto` with computer-use-preview.", "Our key: model computer-use-preview -> 404 model_not_found (tiered/limited access)."], CU_SEC,
     ["DOCUMENTED", "PREVIEW", "ACCOUNT_RESTRICTED"], "computer-use",
     {"computer_use_preview_model": ver("restricted", 404, "POST /v1/responses model=computer-use-preview with 1x1 PNG input_image + computer_use_preview tool -> 404 invalid_request_error code=model_not_found 'does not exist or you do not have access'")},
     [f"{DOCS}/guides/tools-computer-use", f"{DOCS}/guides/tools-computer-use-integration", f"{DOCS}/models/computer-use-preview"])
tool("computer", "Computer tool (current)", "client",
     "Current computer-use tool (`{type: computer}`, no display parameters in the spec). Same `computer_call`/`computer_call_output` loop; `computer_call.actions[]` carries flattened batched actions for `computer_use`. Listed as `computer_use` on gpt-5.4/5.4-mini/5.4-pro/5.5/5.6*/gpt-6-astra model pages.",
     [RESP], {**TC_COMMON, "specific": [{"type": "computer"}, {"type": "computer_use"}]}, {"supported": False},
     "Same as computer_use_preview plus `actions[]` batches.", {"model": "Token billing (images as input tokens)", "source": PRICING},
     ["Not live-tested (cost/safety); docs recommend code-execution integration for GPT-6 Astra."], CU_SEC, ["DOCUMENTED", "UNVERIFIED"], "computer-use",
     {"docs": ver("success", 0, "not called", "docs_only")}, [f"{DOCS}/guides/tools-computer-use", f"{DOCS}/guides/tools-computer-use-integration"])

tool("image_generation", "Image generation tool", "hosted",
     "Lets a mainline model call GPT Image models (`model`: gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2[-2026-04-21], gpt-image-2.5-sunburst|flare[-2026-09-08]). Parameters: size, quality (low|medium|high|xhigh|max|auto), background, output_format, output_compression, moderation, input_fidelity, input_image_mask, partial_images (0-3, streaming), action (generate|edit|auto). Result is base64 in `image_generation_call.result`.",
     [RESP], {**TC_COMMON, "specific": {"type": "image_generation"}}, {"supported": False},
     "Output item `image_generation_call` {id, status: in_progress|generating|completed|failed, result: base64|null, revised_prompt, size, quality, background, output_format, action}.",
     {"per_image": "Image model token pricing (see pricing fragment / image generation guide calculator); mainline model tokens billed separately", "source": f"{DOCS}/pricing#image-generation"},
     ["Guide model list: gpt-5.5, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5, gpt-5-nano, o3, gpt-4.1(-mini/-nano), gpt-4o(-mini).", "Size must be divisible by 16 (live error).", "xhigh/max quality only on gpt-image-2.5-*."],
     ["Moderation `low` relaxes filtering; images may be revised by the mainline model (revised_prompt)."], ["DOCUMENTED", "LIVE_VERIFIED"], "image-generation",
     {"invalid_size_error": ver("success", 400, f"{NANO}: size '1x1' -> 400 type=image_generation_user_error code=invalid_value param=tools 'Width and height must both be divisible by 16.' (generation itself skipped: RUN_IMAGE_TESTS)")},
     [f"{DOCS}/guides/tools-image-generation"])

tool("mcp", "Remote MCP servers, connectors and Secure MCP Tunnel", "mcp",
     "Connects the model to a remote MCP server (`server_url`, Streamable HTTP or HTTP/SSE), a Secure MCP Tunnel (`tunnel_id`) or a legacy connector (`connector_id`, deprecated for models released after 2025-09-01). Auth via `authorization` (OAuth token, never stored/echoed) or `headers`. `allowed_tools` (list or {tool_names, read_only}), `require_approval` (always|never|{always:{...}, never:{...}}, default always), `defer_loading`, `allowed_callers`, `server_description`.",
     [RESP, "POST /v1/realtime (mcp tool)", "Agents API (MCP connections)", "Deep research models"],
     {**TC_COMMON, "specific": {"type": "mcp", "server_label": "<label>", "name": "<tool or null>"}}, {"supported": False},
     "Items: `mcp_list_tools` {server_label, tools: [{name, description, input_schema, annotations}], error}, `mcp_call` {server_label, name, arguments, output, error: mcp_protocol_error|mcp_tool_execution_error|http_error, status, approval_request_id}, `mcp_approval_request` {id, server_label, name, arguments} answered by input `mcp_approval_response` {approval_request_id, approve, reason}.",
     {"per_call": "No OpenAI per-call fee; imported tool definitions and tool outputs are billed as model tokens", "source": PRICING},
     ["`mcp_list_tools` is fetched once per response chain; keep the item in context.", "Deep research requires search+fetch MCP servers with require_approval never.", "Connector ids: connector_dropbox, connector_gmail, connector_googlecalendar, connector_googledrive, connector_microsoftteams, connector_outlookcalendar, connector_outlookemail, connector_sharepoint."],
     ["Only connect trusted servers; tool outputs are untrusted input (prompt injection, exfiltration through arguments).", "Approvals default to always; `authorization` value is redacted from the stored Response.", "Org/project admins can disable MCP."],
     LIVE, "mcp-and-connectors",
     {"deepwiki_call": ver("success", 200, f"{NANO}: server_url https://mcp.deepwiki.com/mcp, require_approval never, allowed_tools [read_wiki_structure] -> mcp_list_tools (1 tool, annotations.read_only=false), mcp_call completed with output, message"),
      "approval_flow": ver("success", 200, "require_approval always + tool_choice {type:mcp,...} -> mcp_approval_request; replied mcp_approval_response approve=false reason -> model message acknowledging rejection"),
      "streaming": ver("success", 200, "response.mcp_list_tools.in_progress/completed, response.mcp_call.in_progress, response.mcp_call_arguments.delta/done, response.mcp_call.completed")},
     [f"{DOCS}/guides/tools-connectors-mcp", f"{DOCS}/guides/secure-mcp-tunnels", f"{DOCS}/guides/realtime-mcp"])

tool("shell", "Shell tool (hosted container or local runtime)", "hosted",
     "Model emits `shell_call` {action: {commands[], timeout_ms, max_output_length}}. `environment`: `{type: container_auto, file_ids?, memory_limit?, network_policy?, skills?}` (hosted: OpenAI runs the commands and returns `shell_call_output` automatically), `{type: container_reference, container_id}` (reuse a container from /v1/containers) or `{type: local}` (your runtime executes and returns `shell_call_output` {call_id, output: [{stdout, stderr, outcome: {type: exit, exit_code} | {type: timeout}}]}). Default cwd `/mnt/data`; skills mount under `/home/oai/skills/<name>-<version>`.",
     [RESP], {**TC_COMMON, "specific": {"type": "shell"}}, {"supported": False},
     "`shell_call` {id, call_id, action.commands, environment: null | {type: local} | {type: container_reference, container_id}, status}; `shell_call_output` items (hosted: server-emitted).",
     {"per_session": "Hosted containers: same rates as code interpreter (1 GB $0.03 … 64 GB $1.92 per 20-min session)", "local": "Token billing only", "source": PRICING},
     ["Not available in Chat Completions.", "Hosted shell: no interactive TTY; no outbound network by default; org domain allow-list.", "Model page key: hosted_shell (gpt-5.2, gpt-5.2/5.3-codex, gpt-5.4*, gpt-5.5, gpt-5.6*, gpt-6-astra)."],
     ["Local mode: you execute arbitrary commands — sandbox, enforce timeouts, filter dangerous commands; timeout_ms is only a hint.", "Hosted allowlists + domain_secrets reduce credential leakage; prompt injection via fetched content remains."],
     LIVE, "shell",
     {"local_env": ver("success", 200, f"{NANO}: environment local, tool_choice {{type:shell}} -> shell_call action.commands ['echo OK'], environment null (nothing executed by us)"),
      "hosted_with_skill": ver("success", 200, f"{NANO}: environment container_auto + skills [skill_reference] -> two shell_call/shell_call_output pairs (cat SKILL.md, echo OK) with environment container_reference; final message 'OK'"),
      "streaming": ver("success", 200, "response.shell_call_command.added -> .delta -> .done (local env); shell_call_output_content.* not observed locally")},
     [f"{DOCS}/guides/tools-shell", PRICING])

tool("local_shell", "Local shell (legacy, codex-mini-latest)", "client",
     "Legacy tool for Codex CLI / codex-mini-latest: `local_shell_call` {action: {type: exec, command[], timeout_ms, working_directory, env, user}} answered by `local_shell_call_output` {id, output}. Superseded by `shell` with environment local.",
     [RESP], {**TC_COMMON}, {"supported": False}, "`local_shell_call` / `local_shell_call_output`.", {"model": "Token billing only", "source": PRICING},
     ["Live: gpt-5.4-nano -> 400 'The local_shell tool is no longer supported.' Only codex-mini-latest documented."],
     ["Same as shell local mode."], ["DOCUMENTED", "LEGACY", "FAILED_VERIFICATION"], "shell",
     {"nano": ver("failure", 400, f"{NANO}: tools [{{type:local_shell}}] -> 400 invalid_request_error param=tools 'The local_shell tool is no longer supported.'")},
     [f"{DOCS}/guides/tools-local-shell"], models=["codex-mini-latest"])

tool("apply_patch", "Apply patch (structured file diffs)", "client",
     "Model emits `apply_patch_call` {operation: {type: create_file|update_file|delete_file, path, diff}}; the app applies it and returns `apply_patch_call_output` {call_id, status: completed|failed, output}. No input schema to declare. Often paired with `shell` for file discovery.",
     [RESP], {**TC_COMMON, "specific": {"type": "apply_patch"}}, {"supported": False},
     "`apply_patch_call` {id, call_id, status, operation}; input `apply_patch_call_output`.", {"model": "Token billing only", "source": PRICING},
     ["Guide table: Responses only; models GPT-5.1, 5.2, 5.4, 5.5 (model pages also list gpt-5.4-nano/mini, 5.6*, gpt-6-astra)."],
     ["Validate paths (no traversal), restrict to allowed dirs, return status failed with a message on error."], LIVE, "apply-patch",
     {"create_file": ver("success", 200, f"{NANO}: tool_choice {{type:apply_patch}} -> apply_patch_call operation {{type:create_file, path:'hello.txt', diff:'+OK\\n'}} (not applied by us)"),
      "streaming": ver("success", 200, "LIVE_DISCOVERED events response.apply_patch_call_operation_diff.delta / .done (absent from OpenAPI ResponseStreamEvent union)")},
     [f"{DOCS}/guides/tools-apply-patch"])

tool("skill_reference", "Skills (attachments for hosted shell / containers) — not a tool type", "hosted",
     "Skills are versioned ZIP bundles (SKILL.md + files) uploaded through /v1/skills and mounted into hosted shell containers via `environment.skills[]` = `{type: skill_reference, skill_id, version?}` or `{type: inline, name, description, source: {type: base64, media_type: application/zip, data}}`, or at container creation (`skills[]`). Local shell uses `{name, description, path}` entries instead. The platform adds each skill's name/description/path to the user-prompt context.",
     [RESP + " (tools[type=shell].environment.skills)", "POST /v1/containers (skills)", "Agents API sandboxes"], {"modes": [], "note": "not a tool; no tool_choice"}, {"supported": False},
     "No dedicated item; shell_call commands read /home/oai/skills/<name>-<version>/SKILL.md.", {"model": "Container session + tokens", "source": PRICING},
     ["Exactly one SKILL.md per bundle; <= 500 files; <= 25 MB uncompressed; up to 200 skills per container_auto; default_version cannot be deleted.", "Hosted shell only accepts skill_reference/inline; local shell only paths."],
     ["Inspect every skill: SKILL.md instructions are user-level prompt input (prompt injection); do not let end-users attach arbitrary skills."], LIVE, "skills",
     {"mount_and_use": ver("success", 200, f"{NANO}: shell container_auto with skills [skill_reference skill_…] -> model listed /home/oai/skills/atlas-hello-1, read SKILL.md, ran echo OK")},
     [f"{DOCS}/guides/tools-skills", f"{REF}/resources/skills"])

TOOLS_OUT = {"$fragment": "openai-tools", "generated_by": "scripts/build_openai_tools_fragments.py", "generated_at": VERIFIED,
             "include_values_for_tools": {k: v for k, v in {
                 "file_search_call.results": "file_search results text/scores", "web_search_call.results": "web search results (legacy)",
                 "web_search_call.action.sources": "full list of consulted sources", "code_interpreter_call.outputs": "logs/image outputs",
                 "computer_call_output.output.image_url": "screenshot URLs in computer_call_output"}.items()},
             "tool_model_matrix": matrix, "records": list(T.values())}

# --------------------------------------------------------------------------- parameters
P: list[dict] = []


def walk(schema: dict, prefix: str, endpoint: str, status: list[str], source: str, location: str = "body", compatible_models: list[str] | None = None, depth: int = 0, required_parent=True):
    if depth > 7 or not isinstance(schema, dict):
        return
    variants = schema.get("oneOf") or schema.get("anyOf")
    if variants and "properties" not in schema:
        for v in variants:
            if isinstance(v, dict) and v.get("type") != "null":
                walk(v, prefix, endpoint, status, source, location, compatible_models, depth + 1)
        return
    props = schema.get("properties") or {}
    req = {r for r in (schema.get("required") or []) if isinstance(r, str)}
    for k, v in props.items():
        if not isinstance(v, dict):
            continue
        path = f"{prefix}.{k}" if prefix else k
        alts = [a for a in (v.get("oneOf") or v.get("anyOf") or []) if isinstance(a, dict)]
        nn = [a for a in alts if a.get("type") != "null"]
        base = nn[0] if len(nn) == 1 else v
        typ = v.get("type") or base.get("type") or ("oneOf" if nn else "object")
        if isinstance(typ, list):
            typ = "|".join(typ)
        enum = v.get("enum") or base.get("enum")
        rec = {"provider": "openai", "endpoint": endpoint, "parameter": path, "location": location, "type": typ,
               "required": k in req, "default": v.get("default", base.get("default")), "minimum": v.get("minimum", base.get("minimum")),
               "maximum": v.get("maximum", base.get("maximum")), "enum": enum,
               "description": str(v.get("description") or base.get("description") or "").strip(),
               "compatible_models": compatible_models or [], "beta_header": None, "status": status, "source": source}
        for lim in ("minItems", "maxItems", "minLength", "maxLength", "pattern", "format"):
            val = v.get(lim, base.get(lim))
            if val is not None:
                rec.setdefault("constraints", {})[lim] = val
        if any(p["parameter"] == path and p["endpoint"] == endpoint for p in P):
            continue
        P.append(rec)
        if "properties" in base:
            walk(base, path, endpoint, status, source, location, compatible_models, depth + 1)
        sub = nn if len(nn) > 1 else [a for a in (base.get("oneOf") or base.get("anyOf") or []) if isinstance(a, dict) and a.get("type") != "null"]
        for a in sub:
            walk(a, path, endpoint, status, source, location, compatible_models, depth + 1)
        items = base.get("items") if isinstance(base.get("items"), dict) else None
        if items:
            walk(items, path + "[]", endpoint, status, source, location, compatible_models, depth + 1)


for ttype, sname in TOOL_SCHEMA.items():
    if ttype in ("web_search_2025_08_26", "web_search_preview_2025_03_11"):
        continue
    st = T[ttype]["status"]
    guide = T[ttype]["sources"][0]["url"]
    prefix = f"tools[type={ttype}]" if ttype != "skill_reference" else "tools[type=shell].environment.skills[]"
    walk(resolve(S[sname]), prefix, RESP, [s for s in st if s in ("DOCUMENTED", "LIVE_VERIFIED", "LEGACY", "PREVIEW")] or ["DOCUMENTED"], guide, compatible_models=T[ttype]["compatible_models"])
# top-level tool controls
walk(resolve({"properties": {"tool_choice": S["ToolChoiceParam"], "parallel_tool_calls": S["ParallelToolCalls"],
                             "include": {"type": "array", "items": S["IncludeEnum"], "description": "Extra output fields; tool-related values: file_search_call.results, web_search_call.results, web_search_call.action.sources, code_interpreter_call.outputs, computer_call_output.output.image_url."},
                             "max_tool_calls": {"type": "integer", "description": "Maximum number of built-in tool calls (web search, file search, MCP…) in a response; used notably with deep research models."}}}),
     "", RESP, ["DOCUMENTED", "LIVE_VERIFIED"], f"{DOCS}/guides/function-calling")
# live-discovered web_search params not in spec
for name, typ, enum, desc in (("return_token_budget", "string", ["default", "unlimited"], "Token budget for returned web search content (GPT-5+ reasoning web search). Documented in the guide, echoed live (default), absent from OpenAPI spec."),
                              ("filters.blocked_domains", "array", None, "Up to 100 blocked domains (guide); absent from OpenAPI spec."),
                              ("search_content_types", "array", ["text", "image"], "Image search: include 'image' (and 'text'). Echoed live as ['text']; present in spec only on web_search_preview.")):
    P.append({"provider": "openai", "endpoint": RESP, "parameter": f"tools[type=web_search].{name}", "location": "body", "type": typ, "required": False, "default": None,
              "minimum": None, "maximum": None, "enum": enum, "description": desc, "compatible_models": models_for("web_search"), "beta_header": None,
              "status": ["DOCUMENTED", "LIVE_DISCOVERED"], "source": f"{DOCS}/guides/tools-web-search"})
# chat completions tool shapes
walk(resolve({"properties": {"tools[]": {"oneOf": [S["ChatCompletionTool"], S["CustomToolChatCompletions"]]}, "tool_choice": S["ChatCompletionToolChoiceOption"],
                             "parallel_tool_calls": S["ParallelToolCalls"], "web_search_options": {"type": "object", "description": "Chat Completions web search (search models gpt-5-search-api, gpt-4o(-mini)-search-preview): {user_location: {type: approximate, approximate: {country, region, city, timezone}}, search_context_size}."}}}),
     "", CHAT, ["DOCUMENTED"], f"{DOCS}/guides/function-calling")
# containers & skills bodies / queries
walk(resolve(S["CreateContainerBody"]), "", "POST /v1/containers", ["DOCUMENTED", "LIVE_VERIFIED"], f"{REF}/resources/containers/methods/create")
walk(resolve(S["CreateContainerFileBody"]), "", "POST /v1/containers/{container_id}/files", ["DOCUMENTED", "LIVE_VERIFIED"], f"{REF}/resources/containers/subresources/files/methods/create")
walk(resolve(S["CreateSkillBody"]), "", "POST /v1/skills", ["DOCUMENTED", "LIVE_VERIFIED"], f"{REF}/resources/skills/methods/create")
walk(resolve(S["CreateSkillVersionBody"]), "", "POST /v1/skills/{skill_id}/versions", ["DOCUMENTED", "LIVE_VERIFIED"], f"{REF}/resources/skills/subresources/versions/methods/create")
walk(resolve(S["SetDefaultSkillVersionBody"]), "", "POST /v1/skills/{skill_id}", ["DOCUMENTED", "FAILED_VERIFICATION"], f"{REF}/resources/skills/methods/update")
for path, ops in spec["paths"].items():
    if not (path.startswith("/containers") or path.startswith("/skills")):
        continue
    for m, op in ops.items():
        if m not in ("get", "post", "delete"):
            continue
        for p in op.get("parameters", []):
            if not isinstance(p, dict) or "name" not in p:
                continue
            sch = p.get("schema") or {}
            P.append({"provider": "openai", "endpoint": f"{m.upper()} /v1{path}", "parameter": p["name"], "location": p.get("in"), "type": sch.get("type", "string"),
                      "required": bool(p.get("required")), "default": sch.get("default"), "minimum": sch.get("minimum"), "maximum": sch.get("maximum"), "enum": sch.get("enum"),
                      "description": (p.get("description") or "").strip(), "compatible_models": [], "beta_header": None, "status": ["DOCUMENTED"],
                      "source": f"{REF}/resources/{'containers' if path.startswith('/containers') else 'skills'}"})

PARAMS_OUT = {"$fragment": "openai-tools-parameters", "generated_by": "scripts/build_openai_tools_fragments.py", "generated_at": VERIFIED, "records": P}

# --------------------------------------------------------------------------- streaming events
LIVE_SAMPLES = {
    "response.function_call_arguments.delta": {"type": "response.function_call_arguments.delta", "delta": "{\"", "item_id": "fc_…", "obfuscation": "LDQNEzSvV7mpzI", "output_index": 0, "sequence_number": 3},
    "response.function_call_arguments.done": {"type": "response.function_call_arguments.done", "arguments": "{\"city\":\"Rome\"}", "item_id": "fc_…", "output_index": 0, "sequence_number": 8},
    "response.custom_tool_call_input.delta": {"type": "response.custom_tool_call_input.delta", "delta": "yes", "item_id": "ctc_…", "obfuscation": "edRTib4zuVyeT", "output_index": 0, "sequence_number": 3},
    "response.custom_tool_call_input.done": {"type": "response.custom_tool_call_input.done", "input": "yes", "item_id": "ctc_…", "output_index": 0, "sequence_number": 4},
    "response.shell_call_command.added": {"type": "response.shell_call_command.added", "command": "", "command_index": 0, "output_index": 0, "sequence_number": 3},
    "response.shell_call_command.delta": {"type": "response.shell_call_command.delta", "command_index": 0, "delta": "echo", "obfuscation": "PGP4AcyqhWaD", "output_index": 0, "sequence_number": 4},
    "response.shell_call_command.done": {"type": "response.shell_call_command.done", "command": "echo OK", "command_index": 0, "output_index": 0, "sequence_number": 6},
    "response.apply_patch_call_operation_diff.delta": {"type": "response.apply_patch_call_operation_diff.delta", "delta": "+", "item_id": "apc_…", "obfuscation": "11F10pEBNExMTzK", "output_index": 0, "sequence_number": 3},
    "response.apply_patch_call_operation_diff.done": {"type": "response.apply_patch_call_operation_diff.done", "diff": "+OK\n", "item_id": "apc_…", "output_index": 0, "sequence_number": 6},
    "response.mcp_list_tools.in_progress": {"type": "response.mcp_list_tools.in_progress", "item_id": "mcpl_…", "output_index": 0, "sequence_number": 3},
    "response.mcp_list_tools.completed": {"type": "response.mcp_list_tools.completed", "item_id": "mcpl_…", "output_index": 0, "sequence_number": 4},
    "response.mcp_call_arguments.delta": {"type": "response.mcp_call_arguments.delta", "delta": "{\"repoName\":\"openai/openai-python\"}", "item_id": "mcp_…", "obfuscation": "oWNr7kyWBnPAy", "output_index": 1, "sequence_number": 8},
    "response.mcp_call_arguments.done": {"type": "response.mcp_call_arguments.done", "arguments": "{\"repoName\":\"openai/openai-python\"}", "item_id": "mcp_…", "output_index": 1, "sequence_number": 9},
    "response.mcp_call.in_progress": {"type": "response.mcp_call.in_progress", "item_id": "mcp_…", "output_index": 1, "sequence_number": 7},
    "response.mcp_call.completed": {"type": "response.mcp_call.completed", "item_id": "mcp_…", "output_index": 1, "sequence_number": 10},
    "response.file_search_call.in_progress": {"type": "response.file_search_call.in_progress", "item_id": "fs_…", "output_index": 1, "sequence_number": 5},
    "response.file_search_call.searching": {"type": "response.file_search_call.searching", "item_id": "fs_…", "output_index": 1, "sequence_number": 6},
    "response.file_search_call.completed": {"type": "response.file_search_call.completed", "item_id": "fs_…", "output_index": 1, "sequence_number": 7},
    "response.web_search_call.in_progress": {"type": "response.web_search_call.in_progress", "item_id": "ws_…", "output_index": 1, "sequence_number": 5},
    "response.web_search_call.searching": {"type": "response.web_search_call.searching", "item_id": "ws_…", "output_index": 1, "sequence_number": 6},
    "response.web_search_call.completed": {"type": "response.web_search_call.completed", "item_id": "ws_…", "output_index": 1, "sequence_number": 7},
}
TOOL_EVENT_KEYS = ("function_call", "web_search", "file_search", "code_interpreter", "image_generation", "mcp", "custom_tool", "shell_call", "apply_patch")
E: list[dict] = []
rse = S["ResponseStreamEvent"]
for m in rse.get("oneOf", rse.get("anyOf", [])):
    n = m["$ref"].split("/")[-1]
    sch = S[n]
    et = (sch.get("properties", {}).get("type", {}).get("enum") or [None])[0]
    if not et or not any(k in et for k in TOOL_EVENT_KEYS):
        continue
    live = et in LIVE_SAMPLES
    E.append({"provider": "openai", "api": "responses", "direction": "server→client", "event": et,
              "description": (sch.get("description") or "").strip(),
              "schema": {k: {kk: vv for kk, vv in resolve(v).items() if kk in ("type", "enum", "description")} for k, v in sch.get("properties", {}).items()},
              "example": LIVE_SAMPLES.get(et), "status": ["DOCUMENTED", "LIVE_VERIFIED"] if live else ["DOCUMENTED"],
              "source": f"{REF}/resources/responses/streaming-events"})
for et in ("response.apply_patch_call_operation_diff.delta", "response.apply_patch_call_operation_diff.done"):
    E.append({"provider": "openai", "api": "responses", "direction": "server→client", "event": et,
              "description": "Streams the `diff` of an apply_patch_call operation (delta chunks, then the final diff). Observed live on gpt-5.4-nano; NOT present in the OpenAPI ResponseStreamEvent union nor in the streaming-events reference page at retrieval time.",
              "schema": {"type": {"type": "string"}, "item_id": {"type": "string"}, "output_index": {"type": "integer"}, "sequence_number": {"type": "integer"},
                         ("delta" if et.endswith("delta") else "diff"): {"type": "string"}, **({"obfuscation": {"type": "string"}} if et.endswith("delta") else {})},
              "example": LIVE_SAMPLES[et], "status": ["LIVE_DISCOVERED", "LIVE_VERIFIED"], "source": "live observation 2026-09-18 (tmp-live/tools/apply_patch_stream.json)"})
E.append({"provider": "openai", "api": "responses", "direction": "server→client", "event": "response.output_item.added / response.output_item.done (tool items)",
          "description": "Generic item lifecycle events wrap every tool item: function_call, custom_tool_call, web_search_call, file_search_call, code_interpreter_call, image_generation_call, mcp_list_tools, mcp_call, mcp_approval_request, shell_call, shell_call_output, apply_patch_call, computer_call, tool_search_call, tool_search_output. `item` carries the full item; tool-specific events refer to it by item_id/output_index.",
          "schema": {"type": {"type": "string"}, "output_index": {"type": "integer"}, "sequence_number": {"type": "integer"}, "item": {"type": "object"}},
          "example": {"type": "response.output_item.added", "item": {"id": "fc_…", "type": "function_call", "status": "in_progress", "arguments": "", "call_id": "call_…", "name": "get_weather"}, "output_index": 0, "sequence_number": 2},
          "status": ["DOCUMENTED", "LIVE_VERIFIED"], "source": f"{REF}/resources/responses/streaming-events"})
EVENTS_OUT = {"$fragment": "openai-tools-streaming-events", "generated_by": "scripts/build_openai_tools_fragments.py", "generated_at": VERIFIED,
              "note": "Tool-related SSE events only; core message/reasoning events are covered by the responses-core fragment. Realtime MCP/function events (response.function_call_arguments.*, response.mcp_call*.*, mcp_list_tools.*) exist with the same names on the Realtime API (RealtimeServerEvent*).",
              "records": E}

# --------------------------------------------------------------------------- endpoints (containers + skills)
LIVE_EP = {
    "GET /v1/containers": ver("success", 200, "?limit=2 -> list with data[] of container objects"),
    "POST /v1/containers": ver("success", 200, "{name:'atlas-tools-agent', memory_limit:'1g', expires_after:{anchor:last_active_at, minutes:5}} -> container {id cntr_…, object:'container', status:'running', memory_limit, expires_after, last_active_at}"),
    "GET /v1/containers/{container_id}": ver("success", 200, "auto container from code_interpreter -> status running, expires_after {last_active_at, 20}, memory_limit 1g, name 'auto'"),
    "DELETE /v1/containers/{container_id}": ver("success", 200, "-> {id, object:'container.deleted', deleted:true}"),
    "POST /v1/containers/{container_id}/files": ver("success", 200, "multipart file=hello.txt -> {id cfile_…, object:'container.file', bytes 11, path '/mnt/data/<hash>-hello.txt', source 'user'}"),
    "GET /v1/containers/{container_id}/files": ver("success", 200, "-> {object:list, data:[], first_id, last_id, has_more}"),
    "GET /v1/containers/{container_id}/files/{file_id}": ver("success", 200, "-> container.file object"),
    "DELETE /v1/containers/{container_id}/files/{file_id}": ver("success", 200, "-> {id, object:'container.file.deleted', deleted:true}"),
    "GET /v1/containers/{container_id}/files/{file_id}/content": ver("success", 200, "-> raw bytes 'hello atlas'"),
    "POST /v1/skills": ver("success", 200, "multipart files=<zip with atlas-hello/SKILL.md (frontmatter name/description)> -> skill {id skill_…, object:'skill', name, description, default_version:'1', latest_version:'1'}"),
    "GET /v1/skills": ver("success", 200, "?limit=5 -> {object:list, data:[], first_id:null, last_id:null, has_more:false}"),
    "GET /v1/skills/{skill_id}": ver("success", 200, "-> skill object"),
    "POST /v1/skills/{skill_id}": ver("failure", 404, "{default_version:'2'} right after creating version 2 -> 404 'Skill version 2 was not found' (param default_version) — versions appear not immediately addressable; possible eventual consistency or id-vs-number mismatch"),
    "DELETE /v1/skills/{skill_id}": ver("success", 200, "-> {id, object:'skill.deleted', deleted:true}"),
    "GET /v1/skills/{skill_id}/content": ver("success", 200, "-> application/zip bytes (PK header)"),
    "POST /v1/skills/{skill_id}/versions": ver("success", 200, "multipart files=<same zip> -> {id skillver_…, object:'skill.version', version:'2', skill_id, name, description}"),
    "GET /v1/skills/{skill_id}/versions": ver("failure", 200, "-> data [] although version 1 (default) existed; list did not reflect versions (LIVE discrepancy)"),
    "GET /v1/skills/{skill_id}/versions/{version}": ver("failure", 404, "/versions/1 -> 404 (version numbers not resolvable right after creation)"),
    "DELETE /v1/skills/{skill_id}/versions/{version}": ver("failure", 404, "/versions/1 -> 404 'Skill version 1 was not found' (default version is also documented as non-deletable)"),
    "GET /v1/skills/{skill_id}/versions/{version}/content": ver("success", 0, "not called", "docs_only"),
}
EP: list[dict] = []
for path, ops in spec["paths"].items():
    if not (path.startswith("/containers") or path.startswith("/skills")):
        continue
    fam = "containers" if path.startswith("/containers") else "skills"
    for m, op in ops.items():
        if m not in ("get", "post", "delete"):
            continue
        key = f"{m.upper()} /v1{path}"
        rb = op.get("requestBody", {}).get("content", {})
        r200 = op.get("responses", {}).get("200", {}).get("content", {})
        v = LIVE_EP.get(key)
        status = ["DOCUMENTED"] + (["LIVE_VERIFIED"] if v and v["result"] == "success" and v["method"] == "live_api" else (["FAILED_VERIFICATION"] if v and v["result"] == "failure" else []))
        EP.append({"provider": "openai", "api_family": fam, "method": m.upper(), "path": f"/v1{path}", "name": op.get("operationId"),
                   "description": (op.get("summary") or "") + (" — " + (op.get("description") or "").strip()[:400] if op.get("description") else ""),
                   "status": status, "auth": "Bearer API key (project key)", "beta_header": None,
                   "request": {"content_type": list(rb.keys()) or None, "body_ref": [c.get("schema", {}).get("$ref", "").split("/")[-1] for c in rb.values()] or None,
                               "query": [p["name"] for p in op.get("parameters", []) if isinstance(p, dict) and p.get("in") == "query"],
                               "path_params": [p["name"] for p in op.get("parameters", []) if isinstance(p, dict) and p.get("in") == "path"]},
                   "response": {"content_type": list(r200.keys()) or None, "schema_ref": [c.get("schema", {}).get("$ref", "").split("/")[-1] for c in r200.values()] or None,
                                "schema": {n: resolve(S[n]) for n in [c.get("schema", {}).get("$ref", "").split("/")[-1] for c in r200.values()] if n in S}},
                   "streaming": {"supported": False, "events_ref": None},
                   "pagination": ("cursor (limit, order, after)" if any(p.get("name") == "after" for p in op.get("parameters", []) if isinstance(p, dict)) else None),
                   "idempotency": None,
                   "sdk": {"python": f"client.{fam}.{'files.' if '/files' in path else ''}{'versions.' if '/versions' in path else ''}{'content.' if path.endswith('/content') else ''}{ {'get': 'retrieve' if '{' in path.split('/')[-1] or path.endswith('/content') else 'list', 'post': 'create', 'delete': 'delete'}[m] }()",
                           "node": f"client.{fam}.{'files.' if '/files' in path else ''}{'versions.' if '/versions' in path else ''}{'content.' if path.endswith('/content') else ''}{ {'get': 'retrieve' if '{' in path.split('/')[-1] or path.endswith('/content') else 'list', 'post': 'create', 'delete': 'delete'}[m] }()"},
                   "verification": v or ver("success", 0, "not called", "docs_only"),
                   "sources": [src(f"{REF}/resources/{fam}"), src("https://github.com/openai/openai-openapi (openapi-master.yaml)")]})
EP_OUT = {"$fragment": "openai-containers-skills", "generated_by": "scripts/build_openai_tools_fragments.py", "generated_at": VERIFIED,
          "notes": ["Container lifecycle: status running -> expires 20 min after last_active_at (auto) or expires_after.minutes; deleted containers return object container.deleted.",
                    "Skills: POST /v1/skills fixes default_version=1; versions are immutable; content endpoints return application/zip.",
                    "POST /v1/skills/{skill_id} (UpdateSkillDefaultVersion) is operationId UpdateSkillDefaultVersion; the SDK name may differ."],
          "records": EP}

for rel, obj in (("tools/openai-tools.json", TOOLS_OUT), ("parameters/openai-tools.json", PARAMS_OUT),
                 ("streaming-events/openai-tools.json", EVENTS_OUT), ("endpoints/openai-containers-skills.json", EP_OUT)):
    out = FRAG / rel
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(json.dumps(obj, indent=1, ensure_ascii=False, default=str) + "\n")
    print(f"wrote {out.relative_to(ROOT)} ({len(obj['records'])} records, {out.stat().st_size // 1024} KB)")