pyfect-dev 0.1.0__py3-none-any.whl

pyfect/ai/openai_compat/telemetry.py

@@ -0,0 +1,51 @@
+"""GenAI span attributes with OpenAI's own (Effect's ``OpenAiTelemetry``):
+the shared ``gen_ai.*`` groups and ``openai.request.*`` /
+``openai.response.*``."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from pyfect.ai import telemetry as T
+from pyfect.tracer import Span
+
+
+class RequestAttributes(TypedDict, total=False):
+    service_tier: str | None
+
+
+class ResponseAttributes(TypedDict, total=False):
+    service_tier: str | None
+    system_fingerprint: str | None
+
+
+class OpenAiAttributes(TypedDict, total=False):
+    request: RequestAttributes | None
+    response: ResponseAttributes | None
+
+
+class OpenAiTelemetryAttributeOptions(T.GenAIAttributeOptions, total=False):
+    openai: OpenAiAttributes | None
+
+
+def add_gen_ai_annotations(span: Span, options: OpenAiTelemetryAttributeOptions) -> None:
+    """Write the shared groups, then OpenAI's."""
+    T.add_gen_ai_annotations(span, options)
+    openai = options.get("openai")
+    if openai is None:
+        return
+    request = openai.get("request")
+    if request is not None:
+        T.add_span_attributes(span, "openai.request", request)
+    response = openai.get("response")
+    if response is not None:
+        T.add_span_attributes(span, "openai.response", response)
+
+
+__all__ = [
+    "OpenAiAttributes",
+    "OpenAiTelemetryAttributeOptions",
+    "RequestAttributes",
+    "ResponseAttributes",
+    "add_gen_ai_annotations",
+]

pyfect/ai/openai_structured_output.py

@@ -0,0 +1,118 @@
+"""Schemas as OpenAI structured output (Effect's
+``effect/ai/OpenAiStructuredOutput``).
+
+``to_codec_openai(schema)`` gives the JSON Schema to send to OpenAI's
+strict mode and the codec decoding the model's output back into the
+schema's values. Shapes strict mode cannot express are sent in the
+provider-safe form ``anthropic_structured_output`` describes (tuples as
+objects, records as ``[key, value]`` pairs, optional keys as required
+nullable ones, ``one_of`` as ``anyOf``). OpenAI takes no ``allOf``: patterns
+of its members are merged into one, bounds into the tightest, and the
+other keywords kept only when that keeps their meaning. Keywords OpenAI
+does not support, or that do not apply to the schema's type, are left out
+(an unsupported ``format`` becomes part of the description) and still
+checked by the codec. The root must be an object without ``anyOf``.
+Compatibility targets standard models; fine-tuned ones take less.
+"""
+
+from __future__ import annotations
+
+from pyfect.ai import _structured_output_json as J
+from pyfect.ai._openai_all_of import normalize_all_of
+from pyfect.ai._structured_output_codec import StructuredOutputCodec, to_codec
+from pyfect.json_schema import JsonSchema
+from pyfect.schema import Codec
+
+__all__ = ["StructuredOutputCodec", "to_codec_openai"]
+
+_SUPPORTED = frozenset(
+    {
+        "$ref",
+        "type",
+        "title",
+        "description",
+        "enum",
+        "anyOf",
+        "properties",
+        "required",
+        "additionalProperties",
+        "items",
+        "pattern",
+        "multipleOf",
+        "minimum",
+        "exclusiveMinimum",
+        "maximum",
+        "exclusiveMaximum",
+        "minItems",
+        "maxItems",
+    }
+)
+_FORMATS = frozenset(
+    {"date-time", "time", "date", "duration", "email", "hostname", "ipv4", "ipv6", "uuid"}
+)
+_TYPED_KEYWORDS: dict[str, frozenset[str]] = {
+    "pattern": frozenset({"string"}),
+    "format": frozenset({"string"}),
+    **dict.fromkeys(
+        ("multipleOf", "minimum", "exclusiveMinimum", "maximum", "exclusiveMaximum"),
+        frozenset({"number", "integer"}),
+    ),
+    **dict.fromkeys(("items", "minItems", "maxItems"), frozenset({"array"})),
+    **dict.fromkeys(
+        ("properties", "patternProperties", "required", "additionalProperties"),
+        frozenset({"object"}),
+    ),
+}
+"""The keywords that apply to some types only: dropped from another."""
+
+
+def to_codec_openai[T, E, RD, RE](
+    schema: Codec[T, E, RD, RE], /
+) -> StructuredOutputCodec[T, RD, RE]:
+    """``schema``'s OpenAI JSON Schema and the codec of its output (see the
+    module); raises ``ValueError`` when the root is not an object."""
+    codec = to_codec(schema)
+    document = J.document(codec)
+    root = _rewrite(J.resolve_root(document))
+    if root.get("type") != "object" or "anyOf" in root:
+        raise ValueError(
+            'OpenAiStructuredOutput: Root JSON Schema must have type "object" '
+            'and must not use "anyOf"'
+        )
+    return StructuredOutputCodec(codec, J.with_definitions(root, document.definitions, _rewrite))
+
+
+def _rewrite(schema: JsonSchema) -> JsonSchema:
+    return J.walk(schema, _rewrite_node)
+
+
+def _applies(key: str, type: object) -> bool:
+    return not isinstance(type, str) or type in _TYPED_KEYWORDS.get(key, (type,))
+
+
+def _rewrite_node(schema: JsonSchema) -> JsonSchema:
+    normalized = normalize_all_of(schema)
+    type = normalized.get("type")
+    out: JsonSchema = {}
+    unsupported_format: str | None = None
+    for key, value in normalized.items():
+        if key == "format":
+            if isinstance(value, str) and value in _FORMATS and _applies(key, type):
+                out["format"] = value
+            elif isinstance(value, str):
+                unsupported_format = value
+        elif (
+            key in _SUPPORTED
+            and _applies(key, type)
+            and (key != "additionalProperties" or value is False)
+        ):
+            out[key] = value
+    if unsupported_format is not None:
+        J.append_description(out, f"a value with a format of {unsupported_format}")
+    if (
+        out.get("type") == "object"
+        and "properties" not in out
+        and out.get("additionalProperties") is False
+    ):
+        out["properties"] = {}
+    return out

pyfect/ai/openrouter/__init__.py

@@ -0,0 +1,36 @@
+"""OpenRouter's API for ``pyfect.ai`` (Effect's ``@effect/ai-openrouter``):
+the ``client`` (chat completions, streamed chat completions, alpha
+decisions and the generated client of every operation), its per-call
+``config``, the ``language_model`` and ``decision_model``, the decisions
+wire ``schema`` and the error ``metadata`` an ``AiError`` carries.
+``generated`` holds the schemas and client of OpenRouter's OpenAPI
+document, generated by ``scripts/gen_ai_schemas.py``::
+
+    from pyfect.ai.openrouter import client, language_model
+
+    program.pipe(fx.provide(language_model.model("openai/gpt-4o-mini").layer)).pipe(
+        fx.provide(client.layer_config(api_key=config.redacted("OPENROUTER_API_KEY")))
+    )
+"""
+
+from pyfect.ai.openrouter import (
+    client,
+    config,
+    decision_model,
+    error,
+    language_model,
+    schema,
+)
+from pyfect.ai.openrouter.client import OpenRouterClient
+from pyfect.ai.openrouter.config import OpenRouterConfig
+
+__all__ = [
+    "OpenRouterClient",
+    "OpenRouterConfig",
+    "client",
+    "config",
+    "decision_model",
+    "error",
+    "language_model",
+    "schema",
+]

pyfect/ai/openrouter/_errors.py

@@ -0,0 +1,186 @@
+"""The mapping of a failed OpenRouter request to an ``AiError`` (Effect's
+``internal/errors.ts`` in ``@effect/ai-openrouter``): a documented error
+status of the generated client (its decoded body), or a status error
+whose body may hold OpenRouter's ``{"error": {...}}`` envelope, under the
+``openrouter`` metadata key. A 429 whose code or type is
+``insufficient_quota`` is an exhausted quota; 529 is an overloaded API."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Never, NotRequired, TypedDict, cast
+
+import pyfect as fx
+from pyfect import clock
+from pyfect import schema as S
+from pyfect._core import Effect
+from pyfect.ai import _openai_errors as OE
+from pyfect.ai import _provider as P
+from pyfect.ai.ai_error import (
+    AiError,
+    AnyReason,
+    AuthenticationError,
+    HttpContext,
+    InternalProviderError,
+    InvalidRequestError,
+    QuotaExhaustedError,
+    RateLimitError,
+    UnknownError,
+    build_error_description,
+)
+from pyfect.ai.openrouter.error import OpenRouterErrorMetadata
+from pyfect.ai.openrouter.generated.client import OpenRouterClientError
+from pyfect.http.error import StatusCodeError
+
+MODULE = "OpenRouterClient"
+SECRET_HEADERS = ("authorization",)
+
+
+class _ErrorDetail(TypedDict):
+    message: str
+    type: NotRequired[str | None]
+    code: NotRequired[str | int | float | None]
+
+
+class OpenRouterErrorBody(TypedDict):
+    error: _ErrorDetail
+
+
+_decode_body = P.wire_parser_option(
+    S.Struct(
+        OpenRouterErrorBody,
+        error=S.Struct(
+            _ErrorDetail,
+            type=S.NullOr(S.String),
+            code=S.NullOr(S.Union(S.String, S.Finite)),
+        ),
+    ),
+    OpenRouterErrorBody,
+)
+
+
+def map_status_code_to_reason(  # noqa: PLR0911
+    *,
+    status: int,
+    now: float,
+    headers: Mapping[str, str],
+    message: str | None,
+    metadata: OpenRouterErrorMetadata,
+    http: HttpContext,
+) -> AnyReason:
+    """The reason for a failed status (Effect's ``mapStatusCodeToReason``);
+    ``now`` is the time in epoch milliseconds."""
+    code = metadata["errorCode"]
+    description = build_error_description(
+        status=status,
+        message=message,
+        method=http["request"]["method"],
+        url=http["request"]["url"],
+        error_code=cast("str | int | None", code),
+        error_type=metadata["errorType"],
+        request_id=metadata["requestId"],
+        body=http.get("body"),
+    )
+    meta: dict[str, Any] = {"openrouter": {**metadata}}
+    match status:
+        case 400 | 404 | 409 | 422:
+            return InvalidRequestError(description=description, metadata=meta, http=http)
+        case 401:
+            return AuthenticationError(
+                kind="InvalidKey", description=description, metadata=meta, http=http
+            )
+        case 403:
+            return AuthenticationError(
+                kind="InsufficientPermissions", description=description, metadata=meta, http=http
+            )
+        case 429:
+            if "insufficient_quota" in (code, metadata["errorType"]):
+                return QuotaExhaustedError(metadata=meta, http=http)
+            delay, limits = OE.parse_rate_limit_headers(headers, now)
+            rate: dict[str, Any] = {"openrouter": {**metadata, **limits}}
+            return RateLimitError(retry_after=delay, metadata=rate, http=http)
+        case 529:
+            return InternalProviderError(
+                description=P.or_default(message, "OpenRouter API is overloaded"),
+                metadata=meta,
+                http=http,
+            )
+        case _ if status >= 500:
+            return InternalProviderError(
+                description=P.or_default(message, "Server error"), metadata=meta, http=http
+            )
+        case _:
+            return UnknownError(description=message, metadata=meta, http=http)
+
+
+def _fail(method: str, reason: AnyReason) -> Effect[Never, AiError]:
+    return fx.fail(AiError(module=MODULE, method=method, reason=reason))
+
+
+def _map_status(reason: StatusCodeError, method: str) -> Effect[Never, AiError]:
+    response = reason.response
+
+    def build(body: str | None, now: float) -> Effect[Never, AiError]:
+        decoded = _decode_body(P.parse_json(body))
+        error = None if decoded is None else decoded["error"]
+        metadata: OpenRouterErrorMetadata = {
+            "errorCode": None if error is None else error.get("code"),
+            "errorType": None if error is None else error.get("type"),
+            "requestId": response.headers.get("x-request-id"),
+        }
+        mapped = map_status_code_to_reason(
+            status=response.status,
+            now=now,
+            headers=response.headers,
+            message=None if error is None else error["message"],
+            metadata=metadata,
+            http=P.http_context(reason.request, response, body, secret_headers=SECRET_HEADERS),
+        )
+        return _fail(method, mapped)
+
+    return P.status_body(reason).flat_map(
+        lambda body: clock.now().flat_map(lambda seconds: build(body, seconds * 1000))
+    )
+
+
+ERRORS = P.ErrorMapper(MODULE, _map_status)
+
+
+def map_client_error(error: OpenRouterClientError, method: str) -> Effect[Never, AiError]:
+    """A documented error status of the generated client: its decoded body
+    is OpenRouter's error envelope."""
+    cause: Mapping[str, Any] = error.cause
+    detail: Mapping[str, Any] = cause["error"]
+    response = error.response
+    metadata: OpenRouterErrorMetadata = {
+        "errorCode": detail.get("code"),
+        "errorType": detail.get("type"),
+        "requestId": response.headers.get("x-request-id"),
+    }
+    http = P.http_context(error.request, response, P.dumps(cause), secret_headers=SECRET_HEADERS)
+
+    def build(seconds: float) -> Effect[Never, AiError]:
+        reason = map_status_code_to_reason(
+            status=response.status,
+            now=seconds * 1000,
+            headers=response.headers,
+            message=detail["message"],
+            metadata=metadata,
+            http=http,
+        )
+        return _fail(method, reason)
+
+    return clock.now().flat_map(build)
+
+
+def catch(method: str) -> Callable[[object], Effect[Never, AiError]]:
+    """A handler for every failure of a request: a documented error status,
+    client, schema and SSE errors become ``AiError``."""
+    handle = ERRORS.catch(method)
+
+    def run(error: object) -> Effect[Never, AiError]:
+        if isinstance(error, OpenRouterClientError):
+            return map_client_error(error, method)
+        return handle(error)
+
+    return run

pyfect/ai/openrouter/_prompt.py

@@ -0,0 +1,272 @@
+"""A prompt as OpenRouter chat messages (Effect's ``prepareMessages`` in
+``OpenRouterLanguageModel``). Provider options are read under
+``"openrouter"``: a ``cacheControl`` breakpoint on a message or part (a
+message's goes on its last text, or its last tool result), a file's
+``fileName`` and the ``reasoningDetails`` an assistant turn replays (the
+message's, else its first tool call's or reasoning part's), each detail
+sent once per request."""
+
+from __future__ import annotations
+
+import base64
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pyfect._url import Url
+from pyfect.ai import _provider as P
+from pyfect.ai import _provider_tools as PT
+from pyfect.ai import prompt as Pr
+from pyfect.ai.ai_error import InvalidUserInputError
+
+MODULE = "OpenRouterLanguageModel"
+KEY = "openrouter"
+
+type Block = dict[str, Any]
+type ReasoningDetails = Sequence[Mapping[str, Any]]
+
+AUDIO_FORMATS: Mapping[str, str] = {
+    "audio/aac": "aac",
+    "audio/aiff": "aiff",
+    "audio/x-aiff": "aiff",
+    "audio/flac": "flac",
+    "audio/x-flac": "flac",
+    "audio/l16": "pcm16",
+    "audio/l24": "pcm24",
+    "audio/m4a": "m4a",
+    "audio/x-m4a": "m4a",
+    "audio/mp4": "m4a",
+    "audio/mp3": "mp3",
+    "audio/mpeg": "mp3",
+    "audio/ogg": "ogg",
+    "audio/wav": "wav",
+    "audio/wave": "wav",
+    "audio/x-wav": "wav",
+}
+"""Audio media types and OpenRouter's formats for them."""
+
+_SUPPORTED_AUDIO = ", ".join(dict.fromkeys(AUDIO_FORMATS.values()))
+_DATA_URL = re.compile("data:[^;]*;base64,([^\\n\\r\\u2028\\u2029]+)")
+_MEDIA_TYPE = re.compile(r"data:([^;]+)")
+
+
+def options(part: Any) -> P.JsonObject:
+    return P.obj(part.options.get(KEY))
+
+
+def cache_control(part: Any) -> object:
+    """A message's or part's breakpoint, ``None`` when it has none."""
+    return options(part).get("cacheControl")
+
+
+def base64_from_data_url(data_url: str) -> str:
+    """The base64 of a ``data:`` URL, else the text itself."""
+    match = _DATA_URL.fullmatch(data_url)
+    return data_url if match is None else match.group(1)
+
+
+def media_type_of(data_url: str, default: str) -> str:
+    match = _MEDIA_TYPE.match(data_url)
+    return default if match is None else match.group(1)
+
+
+def _b64(data: bytes) -> str:
+    return base64.b64encode(data).decode()
+
+
+def _with_cache(block: Block, control: object) -> Block:
+    if control is not None:
+        block["cache_control"] = control
+    return block
+
+
+def _invalid(description: str) -> PT.UnsupportedInput:
+    return PT.unsupported(MODULE, "prepareMessages", InvalidUserInputError(description=description))
+
+
+def _file(part: Pr.FilePart) -> Block:
+    control = cache_control(part)
+    data = part.data
+    media_type = part.media_type
+    if media_type.startswith("image/"):
+        image_type = "image/jpeg" if media_type == "image/*" else media_type
+        if isinstance(data, Url):
+            url = str(data)
+        elif isinstance(data, bytes):
+            url = f"data:{image_type};base64,{_b64(data)}"
+        else:
+            url = data
+        return _with_cache({"type": "image_url", "image_url": {"url": url}}, control)
+    if media_type.startswith("audio/"):
+        audio_format = AUDIO_FORMATS.get(media_type.lower())
+        if audio_format is None:
+            raise _invalid(
+                f"Detected unsupported media type for audio file: '{media_type}' "
+                f"- OpenRouter supports {_SUPPORTED_AUDIO} audio"
+            )
+        if isinstance(data, Url):
+            raise _invalid(
+                "Detected URL data for audio file - OpenRouter requires "
+                "audio to be provided as base64-encoded data"
+            )
+        encoded = _b64(data) if isinstance(data, bytes) else base64_from_data_url(data)
+        block = {"type": "input_audio", "input_audio": {"data": encoded, "format": audio_format}}
+        return _with_cache(block, control)
+    name = options(part).get("fileName")
+    file_name = name if name is not None else P.or_default(part.file_name, "")
+    if isinstance(data, Url):
+        file_data = str(data)
+    elif isinstance(data, bytes):
+        file_data = f"data:{media_type};base64,{_b64(data)}"
+    else:
+        file_data = data
+    block = {"type": "file", "file": {"filename": file_name, "file_data": file_data}}
+    return _with_cache(block, control)
+
+
+def _user(message: Pr.UserMessage) -> Block:
+    message_control = cache_control(message)
+    parts = message.content
+    if len(parts) == 1 and isinstance(parts[0], Pr.TextPart):
+        text = parts[0].text
+        if message_control is None:
+            return {"role": "user", "content": text}
+        content = [{"type": "text", "text": text, "cache_control": message_control}]
+        return {"role": "user", "content": content}
+    last_text = max(
+        (index for index, part in enumerate(parts) if isinstance(part, Pr.TextPart)), default=-1
+    )
+    blocks: list[Block] = []
+    for index, part in enumerate(parts):
+        if isinstance(part, Pr.TextPart):
+            control = cache_control(part)
+            if control is None and index == last_text:
+                control = message_control
+            blocks.append(_with_cache({"type": "text", "text": part.text}, control))
+        else:
+            blocks.append(_file(part))
+    return {"role": "user", "content": blocks}
+
+
+def _details(value: object) -> ReasoningDetails | None:
+    return value if isinstance(value, list) and value else None  # pyright: ignore[reportUnknownVariableType]
+
+
+def _first_reasoning_details(content: Sequence[Pr.AssistantMessagePart]) -> ReasoningDetails | None:
+    """A tool call's details (complete), else a reasoning part's."""
+    for part in content:
+        if isinstance(part, Pr.ToolCallPart | Pr.ReasoningPart):
+            details = _details(options(part).get("reasoningDetails"))
+            if details is not None:
+                return details
+    return None
+
+
+class ReasoningDetailsTracker:
+    """The reasoning details already sent (Effect's
+    ``ReasoningDetailsDuplicateTracker``, OpenRouter's own deduplication):
+    a summary is keyed by its text, an encrypted detail by its id or data,
+    a text detail by its text or signature; one without a key is
+    dropped."""
+
+    __slots__ = ("_seen",)
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+
+    @staticmethod
+    def _key(detail: Mapping[str, Any]) -> str | None:
+        match detail.get("type"):
+            case "reasoning.summary":
+                return detail.get("summary")
+            case "reasoning.encrypted":
+                id = detail.get("id")
+                return id if id is not None else detail.get("data")
+            case "reasoning.text":
+                text = detail.get("text")
+                return text if text is not None else detail.get("signature")
+            case _:
+                return None
+
+    def upsert(self, detail: Mapping[str, Any]) -> bool:
+        """Whether ``detail`` is new (and now tracked)."""
+        key = self._key(detail)
+        if key is None or key in self._seen:
+            return False
+        self._seen.add(key)
+        return True
+
+
+def _assistant(message: Pr.AssistantMessage, tracker: ReasoningDetailsTracker) -> Block:
+    reasoning = ""
+    texts: list[Pr.TextPart] = []
+    calls: list[Block] = []
+    for part in message.content:
+        if isinstance(part, Pr.TextPart):
+            if part.text:
+                texts.append(part)
+        elif isinstance(part, Pr.ReasoningPart):
+            reasoning += part.text
+        elif isinstance(part, Pr.ToolCallPart):
+            function = {"name": part.name, "arguments": P.dumps(part.params)}
+            calls.append({"type": "function", "id": part.id, "function": function})
+    candidates = _details(options(message).get("reasoningDetails"))
+    if candidates is None:
+        candidates = _first_reasoning_details(message.content)
+    unique = [detail for detail in candidates or () if tracker.upsert(detail)]
+    message_control = cache_control(message)
+    content: list[Block] = []
+    for index, part in enumerate(texts):
+        control = cache_control(part)
+        if control is None and index == len(texts) - 1:
+            control = message_control
+        content.append(_with_cache({"type": "text", "text": part.text}, control))
+    cached = any(block.get("cache_control") is not None for block in content)
+    block: Block = {
+        "role": "assistant",
+        "content": content if cached else "".join(block["text"] for block in content),
+        "reasoning": reasoning or None,
+    }
+    if unique:
+        block["reasoning_details"] = unique
+    if calls:
+        block["tool_calls"] = calls
+    return block
+
+
+def _tool(message: Pr.ToolMessage) -> list[Block]:
+    results = [part for part in message.content if isinstance(part, Pr.ToolResultPart)]
+    message_control = cache_control(message)
+    messages: list[Block] = []
+    for index, part in enumerate(results):
+        result = part.result
+        text = result if isinstance(result, str) else P.dumps(result)
+        control = cache_control(part)
+        if control is None and index == len(results) - 1:
+            control = message_control
+        content: object = (
+            [{"type": "text", "text": text, "cache_control": control}]
+            if control is not None and text
+            else text
+        )
+        messages.append({"role": "tool", "tool_call_id": part.id, "content": content})
+    return messages
+
+
+def prepare_messages(prompt: Pr.Prompt) -> list[Block]:
+    """Raises ``UnsupportedInput`` for audio OpenRouter cannot take."""
+    tracker = ReasoningDetailsTracker()
+    messages: list[Block] = []
+    for message in prompt.content:
+        match message:
+            case Pr.SystemMessage():
+                block = {"type": "text", "text": message.content}
+                content = [_with_cache(block, cache_control(message))]
+                messages.append({"role": "system", "content": content})
+            case Pr.UserMessage():
+                messages.append(_user(message))
+            case Pr.AssistantMessage():
+                messages.append(_assistant(message, tracker))
+            case Pr.ToolMessage():
+                messages.extend(_tool(message))
+    return messages