pi-ai-python 1.3.0__py3-none-any.whl

pi_ai/api/classifier_shared.py

@@ -0,0 +1,211 @@
+"""HTTP and parsing helpers shared by the classifier APIs."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any, TypeGuard
+
+import httpx
+
+from ..abort import AbortError, abort_scope
+from ..models import calculate_cost
+from ..serialization import classifier_question_from_dict
+from ..types import ClassifierContext, ClassifierModel, ClassifierQuestion, ProviderResponse, Usage
+from ..utils import fastjson
+from ..utils.callbacks import maybe_await
+from ..utils.http import DEFAULT_TIMEOUT_MS, ProviderHttpError, get_http_client, retry_provider_request
+from ..utils.misc import headers_to_record, provider_headers_to_record
+
+__all__ = [
+    "ClassifierHttpError",
+    "is_record",
+    "is_number",
+    "required_number",
+    "format_js_number",
+    "classifier_questions",
+    "coerce_question",
+    "post_json",
+    "post_classifier_request",
+    "parse_classifier_usage",
+]
+
+#: Default client-side retries for classifier requests.
+DEFAULT_CLASSIFIER_MAX_RETRIES = 2
+
+
+class ClassifierHttpError(ProviderHttpError):
+    """An HTTP failure in the shape ``retry_provider_request`` and ``normalize_provider_error`` understand.
+
+    ``body`` holds the raw response text, so error formatting can show the provider's reason.
+    """
+
+    def __init__(self, message: str, *, status: int | None, headers: httpx.Headers | None, body: str) -> None:
+        super().__init__(message, status=status, headers=headers, body=body, include_body=True)
+
+
+def _http_error(label: str, response: httpx.Response) -> ClassifierHttpError:
+    return ClassifierHttpError(
+        f"{label} returned {response.status_code}",
+        status=response.status_code,
+        headers=response.headers,
+        body=response.text,
+    )
+
+
+def _timeout_error(timeout_ms: float) -> ClassifierHttpError:
+    return ClassifierHttpError(
+        f"Request timed out after {format_js_number(timeout_ms)}ms", status=None, headers=None, body=""
+    )
+
+
+def is_record(value: Any) -> TypeGuard[Mapping[str, Any]]:
+    """Whether ``value`` is a JSON object."""
+    return isinstance(value, Mapping)
+
+
+def is_number(value: Any) -> bool:
+    """Whether ``value`` is a finite JSON number (booleans excluded)."""
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def required_number(label: str, value: Any, field: str) -> float:
+    if not is_number(value):
+        raise ValueError(f"{label} returned an invalid {field}")
+    return value
+
+
+def format_js_number(value: float) -> str:
+    """Render a number like JavaScript's ``String(n)`` for integral values (``5`` rather than ``5.0``)."""
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def coerce_question(question: Any) -> ClassifierQuestion:
+    """Accept a question dataclass or its pi JSON form (``{"type": "bool", ...}``)."""
+    if isinstance(question, Mapping):
+        return classifier_question_from_dict(question)
+    return question
+
+
+def classifier_questions(context: ClassifierContext) -> dict[str, ClassifierQuestion]:
+    """The context's questions as dataclasses, in request order."""
+    return {name: coerce_question(question) for name, question in context.questions.items()}
+
+
+async def post_json(
+    label: str,
+    url: str,
+    *,
+    headers: Mapping[str, str],
+    payload: Any,
+    options: Mapping[str, Any],
+    no_retry_statuses: Sequence[int] = (),
+) -> tuple[httpx.Response, Any]:
+    """POST ``payload`` as JSON and return the response with its parsed body.
+
+    Each attempt gets a fresh ``timeout_ms`` deadline covering the whole exchange.
+    Retryable failures are retried ``max_retries`` times (default 2). Caller
+    cancellation raises :class:`AbortError` ("Request aborted").
+    """
+    client = get_http_client(url, options)
+    content = fastjson.dumps_bytes(payload)
+    timeout_ms = options.get("timeout_ms")
+    signal = options.get("signal")
+    http_timeout = httpx.Timeout((timeout_ms if timeout_ms is not None else DEFAULT_TIMEOUT_MS) / 1000)
+
+    async def attempt() -> tuple[httpx.Response, Any]:
+        request = client.build_request("POST", url, headers=headers, content=content, timeout=http_timeout)
+        try:
+            async with asyncio.timeout(timeout_ms / 1000 if timeout_ms is not None else None):
+                response = await client.send(request)
+        except (TimeoutError, httpx.TimeoutException) as error:
+            if timeout_ms is not None and not (signal is not None and signal.aborted):
+                raise _timeout_error(timeout_ms) from error
+            raise
+        if not response.is_success:
+            raise _http_error(label, response)
+        return response, fastjson.loads(response.content)
+
+    max_retries = options.get("max_retries")
+    try:
+        async with abort_scope(signal):
+            return await retry_provider_request(
+                attempt,
+                max_retries=max_retries if max_retries is not None else DEFAULT_CLASSIFIER_MAX_RETRIES,
+                max_retry_delay_ms=options.get("max_retry_delay_ms"),
+                signal=signal,
+                no_retry_statuses=no_retry_statuses,
+            )
+    except AbortError as error:
+        raise AbortError("Request aborted") from error
+
+
+def _request_headers(model: ClassifierModel, api_key: str, options_headers: Any) -> dict[str, str]:
+    return (
+        provider_headers_to_record(
+            {"authorization": f"Bearer {api_key}", "content-type": "application/json"},
+            model.headers,
+            options_headers,
+        )
+        or {}
+    )
+
+
+async def post_classifier_request(
+    label: str,
+    url: str,
+    model: ClassifierModel,
+    body: Any,
+    options: Mapping[str, Any] | None,
+    no_retry_statuses: Sequence[int] = (),
+) -> Any:
+    """POST one JSON classifier request with bearer auth, hooks, per-attempt timeouts and retries.
+
+    Returns the parsed response body; raises on failure. ``no_retry_statuses`` lists
+    HTTP statuses that fail at once although they are normally retried.
+    """
+    options = options or {}
+    api_key = options.get("api_key")
+    if not api_key:
+        raise ValueError(f"No API key for provider: {model.provider}")
+    payload = body
+    on_payload = options.get("on_payload")
+    if on_payload is not None:
+        transformed = await maybe_await(on_payload(payload, model))
+        if transformed is not None:
+            payload = transformed
+    response, json_body = await post_json(
+        label,
+        url,
+        headers=_request_headers(model, api_key, options.get("headers")),
+        payload=payload,
+        options=options,
+        no_retry_statuses=no_retry_statuses,
+    )
+    on_response = options.get("on_response")
+    if on_response is not None:
+        await maybe_await(
+            on_response(ProviderResponse(response.status_code, headers_to_record(response.headers)), model)
+        )
+    return json_body
+
+
+def _token_count(value: Any) -> Any:
+    return value if is_number(value) and value > 0 else 0
+
+
+def parse_classifier_usage(value: Any, model: ClassifierModel) -> Usage | None:
+    """Usage from an ``{input_tokens, output_tokens}`` object, priced from the model catalog like chat usage.
+
+    A missing or malformed usage object leaves the result without usage instead of failing it.
+    """
+    if not is_record(value) or ("input_tokens" not in value and "output_tokens" not in value):
+        return None
+    input_tokens = _token_count(value.get("input_tokens"))
+    output_tokens = _token_count(value.get("output_tokens"))
+    usage = Usage(input_tokens, output_tokens, 0, 0, input_tokens + output_tokens)
+    calculate_cost(model, usage)
+    return usage

pi_ai/api/cloudflare.py

@@ -0,0 +1,36 @@
+"""Cloudflare endpoint templates.
+
+``{CLOUDFLARE_ACCOUNT_ID}`` and ``{CLOUDFLARE_GATEWAY_ID}`` are placeholders that
+the Cloudflare providers fill from the resolved provider env before dispatch.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "CLOUDFLARE_WORKERS_AI_BASE_URL",
+    "CLOUDFLARE_WORKERS_AI_REST_BASE_URL",
+    "CLOUDFLARE_AI_GATEWAY_COMPAT_BASE_URL",
+    "CLOUDFLARE_AI_GATEWAY_OPENAI_BASE_URL",
+    "CLOUDFLARE_AI_GATEWAY_ANTHROPIC_BASE_URL",
+]
+
+#: Workers AI direct endpoint.
+CLOUDFLARE_WORKERS_AI_BASE_URL = "https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1"
+
+#: Workers AI REST endpoint root; model runs are posted to ``run``.
+CLOUDFLARE_WORKERS_AI_REST_BASE_URL = "https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai"
+
+#: AI Gateway Unified API. https://developers.cloudflare.com/ai-gateway/usage/unified-api/
+CLOUDFLARE_AI_GATEWAY_COMPAT_BASE_URL = (
+    "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat"
+)
+
+#: AI Gateway -> OpenAI passthrough. Used until /compat supports /v1/responses.
+CLOUDFLARE_AI_GATEWAY_OPENAI_BASE_URL = (
+    "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai"
+)
+
+#: AI Gateway -> Anthropic passthrough.
+CLOUDFLARE_AI_GATEWAY_ANTHROPIC_BASE_URL = (
+    "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic"
+)

pi_ai/api/cloudflare_workers_ai_system_one.py

@@ -0,0 +1,80 @@
+"""System One models on the Cloudflare Workers AI REST endpoint.
+
+``POST /accounts/{account}/ai/run`` with ``{model, input}``. The REST API wraps the
+model output in Cloudflare's API envelope. Third-party models such as
+``typesafe/jev`` add a run record:
+``{success, result: {state: "Completed", result: {answers, usage}}}``
+(https://developers.cloudflare.com/ai/models/typesafe/jev/). Cloudflare-hosted
+models such as ``@cf/cloudflare/clef`` return the output directly:
+``{success, result: {model, answers, usage}}``
+(https://developers.cloudflare.com/workers-ai/models/clef/).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urljoin
+
+from ..types import ClassifierContext, ClassifierModel, ClassifierResult
+from .classifier_shared import is_record
+from .system_one_shared import SystemOneTransport, SystemOneWireRequest, classify_system_one
+
+__all__ = ["classify"]
+
+LABEL = "Cloudflare Workers AI"
+
+
+def _cloudflare_error_message(errors: Any) -> str:
+    if isinstance(errors, list):
+        messages = [error["message"] for error in errors if is_record(error) and isinstance(error.get("message"), str)]
+        if messages:
+            return f"{LABEL} error: {'; '.join(messages)}"
+    return f"{LABEL} request failed"
+
+
+def _js_string(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _url(model: ClassifierModel) -> str:
+    return urljoin(f"{model.base_url.rstrip('/')}/", "run")
+
+
+def _payload(model: ClassifierModel, request: SystemOneWireRequest) -> Any:
+    return {"model": model.id, "input": request}
+
+
+def _output(body: Any) -> Mapping[str, Any]:
+    if not is_record(body):
+        raise ValueError(f"{LABEL} returned an unexpected response")
+    if body.get("success") is False:
+        raise ValueError(_cloudflare_error_message(body.get("errors")))
+    result = body.get("result")
+    if not is_record(result):
+        raise ValueError(f"{LABEL} returned an unexpected response")
+    if "answers" in result:
+        return result
+    if result.get("state") != "Completed":
+        state = _js_string(result["state"]) if "state" in result else "undefined"
+        raise ValueError(f"{LABEL} run did not complete (state: {state})")
+    run_result = result.get("result")
+    if not is_record(run_result):
+        raise ValueError(f"{LABEL} returned an unexpected response")
+    return run_result
+
+
+_TRANSPORT = SystemOneTransport(
+    api="cloudflare-workers-ai-system-one", label=LABEL, url=_url, payload=_payload, output=_output
+)
+
+
+async def classify(
+    model: ClassifierModel, context: ClassifierContext, options: Mapping[str, Any] | None = None
+) -> ClassifierResult:
+    """Cloudflare Workers AI System One classification with public ``bool`` values mapped to ``noul``."""
+    return await classify_system_one(_TRANSPORT, model, context, options)

pi_ai/api/constrained_sampling.py

@@ -0,0 +1,279 @@
+"""Provider-side constrained sampling: strict JSON-schema tools and OpenAI grammar tools."""
+
+from __future__ import annotations
+
+import copy
+import json
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from ..types import Tool
+from ..utils.schema import parameters_schema
+
+__all__ = [
+    "UnsupportedStrictJsonSchemaError",
+    "UnsupportedStrictSchemaKeywordCheck",
+    "make_strict_json_schema",
+    "get_json_schema_tool_parameters",
+    "GrammarConstrainedSampling",
+    "GrammarToolInputJsonBuffer",
+    "get_grammar_tool_input",
+    "append_grammar_tool_input_json_delta",
+    "resolve_json_schema_strict_sampling",
+    "resolve_grammar_constrained_sampling",
+    "create_grammar_tool_input_properties",
+]
+
+
+class UnsupportedStrictJsonSchemaError(Exception):
+    pass
+
+
+#: Returns True when a provider's strict mode rejects this schema keyword with this value.
+UnsupportedStrictSchemaKeywordCheck = Callable[[str, Any], bool]
+
+_UNSUPPORTED_STRICT_SCHEMA_KEYS = (
+    "$ref",
+    "$defs",
+    "definitions",
+    "allOf",
+    "oneOf",
+    "patternProperties",
+    "dependentSchemas",
+    "dependencies",
+    "unevaluatedProperties",
+    "propertyNames",
+    "contains",
+    "prefixItems",
+    "not",
+    "if",
+    "then",
+    "else",
+)
+
+
+def _is_schema_object(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def _is_structured_schema(schema: Any) -> bool:
+    if not isinstance(schema, dict):
+        return False
+    raw = schema.get("type")
+    types = [raw] if isinstance(raw, str) else raw if isinstance(raw, list) else []
+    return "object" in types or "array" in types or "properties" in schema or "items" in schema
+
+
+def _schema_allows_null(schema: Any) -> bool:
+    if not isinstance(schema, dict):
+        return False
+    raw = schema.get("type")
+    if raw == "null" or (isinstance(raw, list) and "null" in raw):
+        return True
+    if "const" in schema and schema["const"] is None:
+        return True
+    if isinstance(schema.get("enum"), list) and None in schema["enum"]:
+        return True
+    any_of = schema.get("anyOf")
+    return isinstance(any_of, list) and any(_schema_allows_null(variant) for variant in any_of)
+
+
+def _make_node_strict(schema: Any, is_unsupported: UnsupportedStrictSchemaKeywordCheck | None) -> None:
+    if not isinstance(schema, dict):
+        raise UnsupportedStrictJsonSchemaError("boolean schemas are unsupported")
+    for key in _UNSUPPORTED_STRICT_SCHEMA_KEYS:
+        if key in schema:
+            raise UnsupportedStrictJsonSchemaError(f"{key} schemas are unsupported")
+    if is_unsupported is not None:
+        for key, value in schema.items():
+            if is_unsupported(key, value):
+                raise UnsupportedStrictJsonSchemaError(f"{key}: {json.dumps(value)} is unsupported")
+
+    if "anyOf" in schema:
+        any_of = schema["anyOf"]
+        if not isinstance(any_of, list) or not any_of:
+            raise UnsupportedStrictJsonSchemaError("anyOf must contain at least one schema")
+        for variant in any_of:
+            if _is_structured_schema(variant):
+                raise UnsupportedStrictJsonSchemaError("object and array unions are unsupported")
+            _make_node_strict(variant, is_unsupported)
+
+    if "items" in schema:
+        if isinstance(schema["items"], list):
+            raise UnsupportedStrictJsonSchemaError("tuple schemas are unsupported")
+        _make_node_strict(schema["items"], is_unsupported)
+
+    is_object = schema.get("type") == "object"
+    if "properties" in schema and not is_object:
+        raise UnsupportedStrictJsonSchemaError("properties require type object")
+    if not is_object:
+        return
+    if "additionalProperties" in schema and schema["additionalProperties"] is not False:
+        raise UnsupportedStrictJsonSchemaError("schema-valued or true additionalProperties is unsupported")
+    if "properties" in schema and not isinstance(schema["properties"], dict):
+        raise UnsupportedStrictJsonSchemaError("object properties must be a schema map")
+    required_raw = schema.get("required")
+    if required_raw is not None and (
+        not isinstance(required_raw, list) or any(not isinstance(key, str) for key in required_raw)
+    ):
+        raise UnsupportedStrictJsonSchemaError("object required must be a string array")
+
+    properties: dict[str, Any] = schema.get("properties") or {}
+    names = list(properties)
+    required = set(required_raw or [])
+    if any(key not in properties for key in required):
+        raise UnsupportedStrictJsonSchemaError("required contains an unknown property")
+    for key, prop in list(properties.items()):
+        _make_node_strict(prop, is_unsupported)
+        if key not in required and not _schema_allows_null(prop):
+            properties[key] = {"anyOf": [prop, {"type": "null"}]}
+    if "properties" in schema:
+        schema["properties"] = properties
+    schema["required"] = names
+    schema["additionalProperties"] = False
+
+
+def make_strict_json_schema(
+    schema: Any, is_unsupported: UnsupportedStrictSchemaKeywordCheck | None = None
+) -> dict[str, Any]:
+    """Convert a tool schema to the strict subset expected by provider constrained sampling."""
+    cloned = copy.deepcopy(parameters_schema(schema)) if not isinstance(schema, dict) else copy.deepcopy(dict(schema))
+    cloned = json.loads(json.dumps(cloned))
+    if not isinstance(cloned, dict):
+        raise UnsupportedStrictJsonSchemaError("root schema must have type object")
+    _make_node_strict(cloned, is_unsupported)
+    if cloned.get("type") != "object":
+        raise UnsupportedStrictJsonSchemaError("root schema must have type object")
+    return cloned
+
+
+def get_json_schema_tool_parameters(tool: Tool, strict: bool | None) -> dict[str, Any]:
+    """Tool parameters as sent to the provider (made strict when ``strict`` is True)."""
+    return make_strict_json_schema(tool.parameters) if strict is True else parameters_schema(tool.parameters)
+
+
+@dataclass(slots=True)
+class GrammarConstrainedSampling:
+    format: Literal["lark", "regex"]
+    definition: str
+    input_property: str
+
+
+@dataclass(slots=True)
+class GrammarToolInputJsonBuffer:
+    input: str = ""
+    started: bool = False
+    closed: bool = False
+
+
+def get_grammar_tool_input(tool_name: str, arguments: dict[str, Any], input_property: str) -> str:
+    value = arguments.get(input_property)
+    if not isinstance(value, str):
+        raise ValueError(f'Grammar tool call "{tool_name}" requires argument "{input_property}" to be a string.')
+    return value
+
+
+def append_grammar_tool_input_json_delta(
+    buffer: GrammarToolInputJsonBuffer, input_property: str, next_input: str, close: bool
+) -> str | None:
+    """Translate a grammar tool's raw input growth into a JSON-arguments delta."""
+    if buffer.closed:
+        if close and next_input == buffer.input:
+            return None
+        raise ValueError(f'grammar tool input for property "{input_property}" changed after it was closed')
+    if not next_input.startswith(buffer.input):
+        raise ValueError(f'grammar tool input for property "{input_property}" changed non-monotonically')
+    input_delta = next_input[len(buffer.input) :]
+    if not close and not input_delta:
+        return None
+    delta = ""
+    if not buffer.started:
+        delta += "{" + json.dumps(input_property) + ':"'
+        buffer.started = True
+    delta += json.dumps(input_delta, ensure_ascii=False)[1:-1]
+    buffer.input = next_input
+    if close:
+        delta += '"}'
+        buffer.closed = True
+    return delta
+
+
+def _infer_grammar_input_property(tool: Tool) -> str:
+    schema = parameters_schema(tool.parameters)
+    if schema.get("type") != "object":
+        raise ValueError("grammar constrained sampling requires an object parameter schema")
+    required = schema.get("required")
+    if not isinstance(required, list) or len(required) != 1 or not isinstance(required[0], str):
+        raise ValueError("grammar constrained sampling requires exactly one required string property")
+    name = required[0]
+    properties = schema.get("properties") or {}
+    if name not in properties:
+        raise ValueError(f"grammar constrained sampling requires a properties entry for {name}")
+    if (properties[name] or {}).get("type") != "string":
+        raise ValueError(f"grammar constrained sampling property {name} must have type string")
+    return name
+
+
+def resolve_json_schema_strict_sampling(
+    tool: Tool, supports_strict_mode: bool, is_unsupported: UnsupportedStrictSchemaKeywordCheck | None = None
+) -> bool | None:
+    """Whether a JSON-schema tool is sent in strict mode (``None`` = not strict).
+
+    Raises ``ValueError`` when the tool requires strict sampling the provider/schema cannot honor.
+    """
+    config = tool.constrained_sampling
+    if not config or config.get("type") != "json_schema":
+        return None
+    if supports_strict_mode:
+        try:
+            make_strict_json_schema(tool.parameters, is_unsupported)
+            return True
+        except UnsupportedStrictJsonSchemaError as error:
+            if config.get("strict") != "require":
+                return None
+            raise ValueError(f'Tool "{tool.name}" requires JSON-schema constrained sampling, but {error}.') from error
+    if config.get("strict") == "require":
+        raise ValueError(
+            f'Tool "{tool.name}" requires JSON-schema constrained sampling, but strict tools are unsupported.'
+        )
+    return None
+
+
+def resolve_grammar_constrained_sampling(
+    tool: Tool, supports_openai_grammar_tools: bool
+) -> GrammarConstrainedSampling | None:
+    config = tool.constrained_sampling
+    if not config or config.get("type") != "grammar":
+        return None
+    if not supports_openai_grammar_tools:
+        return None
+    variants = config.get("variants") or {}
+    lark = variants.get("openai_lark")
+    regex = variants.get("openai_regex")
+    has_lark = isinstance(lark, str) and bool(lark.strip())
+    has_regex = isinstance(regex, str) and bool(regex.strip())
+    if not has_lark and not has_regex:
+        raise ValueError(
+            f'Tool "{tool.name}" cannot use grammar constrained sampling: no supported grammar variant was provided.'
+        )
+    try:
+        return GrammarConstrainedSampling(
+            format="lark" if has_lark else "regex",
+            definition=lark if has_lark else regex,  # type: ignore[arg-type]
+            input_property=_infer_grammar_input_property(tool),
+        )
+    except ValueError as error:
+        raise ValueError(f'Tool "{tool.name}" cannot use grammar constrained sampling: {error}.') from error
+
+
+def create_grammar_tool_input_properties(
+    tools: Sequence[Tool] | None, supports_openai_grammar_tools: bool
+) -> dict[str, str]:
+    """Map grammar tool names to their single string input property."""
+    properties: dict[str, str] = {}
+    for tool in tools or ():
+        grammar = resolve_grammar_constrained_sampling(tool, supports_openai_grammar_tools)
+        if grammar is not None:
+            properties[tool.name] = grammar.input_property
+    return properties

pi_ai/api/github_copilot_headers.py

@@ -0,0 +1,30 @@
+"""Dynamic request headers required by GitHub Copilot."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+__all__ = ["infer_copilot_initiator", "has_copilot_vision_input", "build_copilot_dynamic_headers"]
+
+
+def infer_copilot_initiator(messages: Sequence[Any]) -> str:
+    """``"user"`` for user-initiated requests, ``"agent"`` for follow-ups after assistant/tool messages."""
+    last = messages[-1] if messages else None
+    return "agent" if last is not None and last.role != "user" else "user"
+
+
+def has_copilot_vision_input(messages: Sequence[Any]) -> bool:
+    """Copilot requires ``Copilot-Vision-Request`` when any user or tool-result message carries images."""
+    for message in messages:
+        if message.role in ("user", "toolResult") and not isinstance(message.content, str):
+            if any(block.type == "image" for block in message.content):
+                return True
+    return False
+
+
+def build_copilot_dynamic_headers(*, messages: Sequence[Any], has_images: bool) -> dict[str, str]:
+    headers = {"X-Initiator": infer_copilot_initiator(messages), "Openai-Intent": "conversation-edits"}
+    if has_images:
+        headers["Copilot-Vision-Request"] = "true"
+    return headers