pyfect-dev 0.1.0__py3-none-any.whl

pyfect/ai/_decision_answers.py

@@ -0,0 +1,185 @@
+"""The check of a provider's answers against their decisions (Effect's
+``validateAnswer`` / ``settleAnswers`` in ``DecisionModel``): each answer
+becomes an ``Ok`` answer or an ``Err(Unanswered)``, the first failed check
+naming the reason."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from pyfect.ai import decision as D
+from pyfect.result import Err, Ok
+
+_SUM_TOLERANCE = 1e-6
+
+
+@dataclass(frozen=True)
+class ProviderClassifyAnswer:
+    """A classify answer; ``probabilities`` ``None`` when the provider has
+    no distribution."""
+
+    tag: ClassVar[str] = "Classify"
+    label: str
+    probabilities: Mapping[str, float] | None = None
+    confidence: float | None = None
+
+
+@dataclass(frozen=True)
+class ProviderRateAnswer:
+    """A rate answer: the label is the most probable level's, so the
+    provider gives none."""
+
+    tag: ClassVar[str] = "Rate"
+    rating: float
+    probabilities: Mapping[str, float] | None = None
+    confidence: float | None = None
+
+
+@dataclass(frozen=True)
+class ProviderProbabilityAnswer:
+    tag: ClassVar[str] = "Probability"
+    probability: float
+
+
+@dataclass(frozen=True)
+class ProviderRefusalAnswer:
+    """The provider declined to answer."""
+
+    tag: ClassVar[str] = "Refusal"
+
+
+type ProviderAnswer = (
+    ProviderClassifyAnswer | ProviderRateAnswer | ProviderProbabilityAnswer | ProviderRefusalAnswer
+)
+
+
+def _unanswered(reason: D.UnansweredReason, description: str) -> Err[D.Unanswered]:
+    return Err(D.Unanswered(reason, description))
+
+
+def _invalid(description: str) -> Err[D.Unanswered]:
+    return _unanswered("Invalid", description)
+
+
+def _is_unit(value: float) -> bool:
+    return math.isfinite(value) and 0 <= value <= 1
+
+
+def _distribution(
+    key: str,
+    labels: Sequence[str],
+    raw: Mapping[str, float] | None,
+    rounding_error: float,
+) -> D.Outcome[dict[str, float]]:
+    """The distribution over ``labels``, rescaled to sum to 1 when its drift
+    is within the provider's rounding (``len(labels) * rounding_error``)."""
+    if raw is None:
+        return _unanswered(
+            "NoDistribution", f'Provider returned no probabilities for decision "{key}"'
+        )
+    probabilities: dict[str, float] = {}
+    total = 0.0  # added in order, as JavaScript does: builtin sum() is compensated
+    for label in labels:
+        value = raw.get(label)
+        if value is None or not _is_unit(value):
+            return _invalid(
+                f'Provider returned no probability for label "{label}" of decision "{key}"'
+            )
+        probabilities[label] = value
+        total += value
+    drift = abs(total - 1)
+    if total == 0 or drift > len(labels) * rounding_error + _SUM_TOLERANCE:
+        return _invalid(
+            f'Provider returned probabilities that do not sum to 1 for decision "{key}"'
+        )
+    if drift > _SUM_TOLERANCE:
+        probabilities = {label: value / total for label, value in probabilities.items()}
+    return Ok(probabilities)
+
+
+def _confidence(key: str, confidence: float | None) -> D.Outcome[float | None]:
+    if confidence is None or _is_unit(confidence):
+        return Ok(confidence)
+    return _invalid(f'Provider returned confidence outside [0, 1] for decision "{key}"')
+
+
+def _classify(
+    key: str, decision: D.Classify[Any], answer: ProviderClassifyAnswer, rounding_error: float
+) -> D.Outcome[D.AnyAnswer]:
+    labels = list(decision.criteria)
+    if answer.label not in labels:
+        return _invalid(f'Provider returned an unknown label for decision "{key}"')
+    confidence = _confidence(key, answer.confidence)
+    if isinstance(confidence, Err):
+        return confidence
+    probabilities = _distribution(key, labels, answer.probabilities, rounding_error)
+    if isinstance(probabilities, Err):
+        return probabilities
+    return Ok(D.ClassifyAnswer(answer.label, probabilities.value, confidence.value))
+
+
+def _rate(
+    key: str, decision: D.Rate[Any], answer: ProviderRateAnswer, rounding_error: float
+) -> D.Outcome[D.AnyAnswer]:
+    levels = [level.label for level in decision.criteria]
+    rating = answer.rating
+    if not (math.isfinite(rating) and 0 <= rating <= len(levels) - 1):
+        return _invalid(
+            f'Provider returned a rating outside [0, {len(levels) - 1}] for decision "{key}"'
+        )
+    confidence = _confidence(key, answer.confidence)
+    if isinstance(confidence, Err):
+        return confidence
+    probabilities = _distribution(key, levels, answer.probabilities, rounding_error)
+    if isinstance(probabilities, Err):
+        return probabilities
+    found = probabilities.value
+    label = levels[0]
+    for level in levels[1:]:
+        if found[level] > found[label]:
+            label = level
+    return Ok(D.RateAnswer(rating, label, found, confidence.value))
+
+
+def _probability(key: str, answer: ProviderProbabilityAnswer) -> D.Outcome[D.ProbabilityAnswer]:
+    if not _is_unit(answer.probability):
+        return _invalid(f'Provider returned a probability outside [0, 1] for decision "{key}"')
+    return Ok(D.ProbabilityAnswer(answer.probability))
+
+
+def validate(
+    key: str, decision: D.AnyDecision, answer: ProviderAnswer | None, rounding_error: float
+) -> D.Outcome[D.AnyAnswer]:
+    """``answer`` checked against ``decision`` (named ``key``)."""
+    if answer is None:
+        return _unanswered("Missing", f'Provider returned no answer for decision "{key}"')
+    match decision, answer:
+        case _, ProviderRefusalAnswer():
+            return _unanswered("Refused", f'Provider refused to answer decision "{key}"')
+        case D.Classify(), ProviderClassifyAnswer():
+            return _classify(key, decision, answer, rounding_error)
+        case D.Rate(), ProviderRateAnswer():
+            return _rate(key, decision, answer, rounding_error)
+        case D.Probability(), ProviderProbabilityAnswer():
+            return _probability(key, answer)
+        case _:
+            return _invalid(
+                f'Provider returned a "{answer.tag}" answer for decision "{key}", '
+                f'expected "{decision.tag}"'
+            )
+
+
+def settle(
+    decisions: Mapping[str, D.AnyDecision],
+    answers: Mapping[str, ProviderAnswer],
+    rounding_error: float,
+) -> dict[str, D.Outcome[D.AnyAnswer]]:
+    """Every decision's outcome, in definition order; answers to other
+    names are dropped."""
+    return {
+        key: validate(key, decision, answers.get(key), rounding_error)
+        for key, decision in decisions.items()
+    }

pyfect/ai/_generated_client.py

@@ -0,0 +1,298 @@
+"""What a generated provider client is built with (the ``make`` of Effect's
+generated ``Generated.ts`` clients): each operation is an ``Operation``
+(its method, query and header parameters, and the schema of each status),
+and a ``GeneratedClient`` sends it.
+
+A response is decoded by the schema of its exact status, else of its
+range (``"2xx"``); a documented error status fails with the client's
+``ClientError`` subclass carrying the decoded body; any other status fails
+with a ``StatusCodeError`` whose description is the body's JSON (or
+``"Unexpected status code"``). Server-Sent Events and binary operations
+check the status only; they skip the ``transform_client`` hook unless the
+client sets ``transform_streams``, as Effect's OpenRouter and OpenAI clients
+differ.
+
+An ``encoded_path`` is Effect's ``__makePathRequest``: its parameters are
+percent-encoded as ``encodeURIComponent`` does, and an empty parameter, a dot
+segment or a parameter that cannot be encoded fails the operation with an
+``InvalidUrlError``, without sending."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Literal, cast
+from urllib.parse import quote
+
+import pyfect as fx
+from pyfect import _json_text
+from pyfect import schema as S
+from pyfect import stream as St
+from pyfect._core import Effect
+from pyfect.encoding import sse
+from pyfect.errors import TaggedError
+from pyfect.http import request as http_request
+from pyfect.http.body import FormDataInput
+from pyfect.http.client import HttpClientService
+from pyfect.http.error import HttpClientError, InvalidUrlError, StatusCodeError
+from pyfect.http.request import HttpClientRequest
+from pyfect.http.response import HttpClientResponse, StatusRange, match_status
+from pyfect.stream import Stream
+
+type Method = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+type ClientTransform = Callable[
+    [HttpClientService[HttpClientError]], Effect[HttpClientService[HttpClientError]]
+]
+"""Effect's ``transformClient`` option: the client an operation runs on,
+chosen per call."""
+
+type Params = Mapping[str, Any]
+
+
+@dataclass(eq=False)
+class ClientError(TaggedError):
+    """A documented error status of an operation: ``tag`` names the
+    operation and the status (``"SendChatCompletionRequest400"``), ``cause``
+    is the decoded body."""
+
+    tag: str
+    cause: Any
+    request: HttpClientRequest
+    response: HttpClientResponse
+
+
+@dataclass(frozen=True)
+class JsonBody:
+    payload: object
+
+
+@dataclass(frozen=True)
+class FormBody:
+    payload: FormDataInput
+
+
+type Body = JsonBody | FormBody | None
+
+
+@dataclass
+class _Decoder:
+    """A schema's decoding of JSON, built on first use (the generated
+    schemas are many; most are never decoded)."""
+
+    schema: Any
+    _decode: Callable[[object], Effect[Any, S.SchemaError]] | None = field(default=None)
+
+    def __call__(self, json: object) -> Effect[Any, S.SchemaError]:
+        if self._decode is None:
+            self._decode = S.decode_unknown_effect(S.to_codec_json(self.schema))
+        return self._decode(_json_text.whole_numbers_as_ints(json))  # pyright: ignore[reportArgumentType]
+
+
+@dataclass(frozen=True)
+class Operation:
+    """An operation: ``success`` decodes a 2xx body, ``status_success``
+    the body of an exact status, ``binary_success`` gives a 2xx body as
+    bytes, a ``void`` status succeeds with ``None`` (a 2xx none of them
+    covers is an unexpected status), ``errors`` maps a status to its tag and
+    body schema."""
+
+    method: Method
+    url_params: tuple[str, ...] = ()
+    headers: tuple[str, ...] = ()
+    success: Any = None
+    status_success: Mapping[int, Any] = field(default_factory=dict[int, Any])
+    binary_success: bool = False
+    void: tuple[int, ...] = ()
+    errors: Mapping[int, tuple[str, Any]] = field(default_factory=dict[int, tuple[str, Any]])
+    _success: _Decoder | None = field(default=None, init=False, compare=False)
+    _errors: dict[int, _Decoder] = field(default_factory=dict[int, _Decoder], init=False)
+    _status_success: dict[int, _Decoder] = field(default_factory=dict[int, _Decoder], init=False)
+
+    def __post_init__(self) -> None:
+        if self.success is not None:
+            object.__setattr__(self, "_success", _Decoder(self.success))
+        self._status_success.update(
+            {status: _Decoder(schema) for status, schema in self.status_success.items()}
+        )
+        self._errors.update(
+            {status: _Decoder(schema) for status, (_, schema) in self.errors.items()}
+        )
+
+
+@dataclass(frozen=True)
+class EncodedPath:
+    """A path template of ``{}`` and the parameters not yet encoded into it."""
+
+    template: str
+    parameters: tuple[str, ...]
+
+
+type Path = str | EncodedPath
+
+_DOT_SEGMENT = re.compile(r"(?:\.|%2e){1,2}", re.IGNORECASE)
+
+
+def encoded_path(template: str, *parameters: str) -> EncodedPath:
+    return EncodedPath(template, parameters)
+
+
+def _resolved_path(path: EncodedPath, operation: Operation) -> Effect[str, HttpClientError]:
+    def fail(description: str, cause: object = None) -> Effect[str, HttpClientError]:
+        request = http_request.make(operation.method, "")
+        return fx.fail(HttpClientError(InvalidUrlError(request, cause, description)))
+
+    if any(value == "" or _DOT_SEGMENT.fullmatch(value) for value in path.parameters):
+        return fail("Path parameters must be non-empty and cannot be dot segments")
+    try:
+        encoded = [quote(value, safe="!'()*") for value in path.parameters]
+    except UnicodeEncodeError as cause:
+        return fail("Failed to encode path parameter", cause)
+    resolved = path.template.format(*encoded)
+    if any(_DOT_SEGMENT.fullmatch(segment) for segment in resolved.split("/")):
+        return fail("Request paths cannot contain dot segments")
+    return fx.succeed(resolved)
+
+
+def json_body(payload: object) -> JsonBody:
+    return JsonBody(payload)
+
+
+def form_body(payload: Mapping[str, Any]) -> FormBody:
+    """A form body of a payload's fields (a generated ``TypedDict``)."""
+    return FormBody(cast("FormDataInput", payload))
+
+
+def _unexpected_status(response: HttpClientResponse) -> Effect[Any, HttpClientError]:
+    def fail(description: str) -> Effect[Any, HttpClientError]:
+        reason = StatusCodeError(response.request, response, None, description)
+        return fx.fail(HttpClientError(reason))
+
+    return (
+        response.json.map(
+            lambda json: json if isinstance(json, str) else _json_text.stringify(json)
+        )
+        .or_else_succeed(lambda _: "Unexpected status code")
+        .flat_map(fail)
+    )
+
+
+class GeneratedClient:
+    """The base of a generated client: ``http_client`` sends every
+    operation, through ``transform_client`` for the JSON ones (and the
+    streams, with ``transform_streams``)."""
+
+    __slots__ = ("_transform", "http_client")
+
+    error_class: ClassVar[type[ClientError]] = ClientError
+    transform_streams: ClassVar[bool] = False
+
+    def __init__(
+        self,
+        http_client: HttpClientService[HttpClientError],
+        transform_client: ClientTransform | None = None,
+    ) -> None:
+        self.http_client = http_client
+        self._transform = transform_client
+
+    @staticmethod
+    def _request(
+        operation: Operation, path: str, params: Params | None, body: Body
+    ) -> HttpClientRequest:
+        request = http_request.make(operation.method, path)
+        if params is not None:
+            query = [(key, params[key]) for key in operation.url_params if key in params]
+            if query:
+                request = request.set_url_params(query)
+            headers = {key: params.get(key) for key in operation.headers}
+            request = request.set_headers(headers)
+        match body:
+            case JsonBody(payload):
+                return request.body_json_unsafe(payload)
+            case FormBody(payload):
+                return request.body_form_data_record(payload)
+            case None:
+                return request
+
+    def _prepared(
+        self, operation: Operation, path: Path, params: Params | None, body: Body
+    ) -> Effect[HttpClientRequest, HttpClientError]:
+        if isinstance(path, str):
+            return fx.succeed(self._request(operation, path, params, body))
+        return _resolved_path(path, operation).map(
+            lambda resolved: self._request(operation, resolved, params, body)
+        )
+
+    def _json(
+        self,
+        operation: Operation,
+        path: Path,
+        params: Params | None,
+        body: Body,
+        include_response: bool,
+    ) -> Effect[Any, Any]:
+        error_class = self.error_class
+
+        def decode_error(status: int) -> Callable[[HttpClientResponse], Effect[Any, Any]]:
+            tag = operation.errors[status][0]
+            decode = operation._errors[status]  # pyright: ignore[reportPrivateUsage]
+
+            def run(response: HttpClientResponse) -> Effect[Any, Any]:
+                return response.json.flat_map(decode).flat_map(
+                    lambda cause: fx.fail(error_class(tag, cause, response.request, response))
+                )
+
+            return run
+
+        cases: dict[int | StatusRange, Callable[[HttpClientResponse], Effect[Any, Any]]] = {
+            status: decode_error(status) for status in operation.errors
+        }
+        for status in operation.void:
+            cases[status] = lambda _: fx.succeed(None)
+        success = operation._success  # pyright: ignore[reportPrivateUsage]
+        if success is not None:
+            cases["2xx"] = lambda response: response.json.flat_map(success)
+        for status, decode in operation._status_success.items():  # pyright: ignore[reportPrivateUsage]
+            cases[status] = lambda response, decode=decode: response.json.flat_map(decode)
+        if operation.binary_success:
+            cases["2xx"] = lambda response: response.bytes_
+
+        def respond(response: HttpClientResponse) -> Effect[Any, Any]:
+            decoded = match_status(response, cases, _unexpected_status)
+            return decoded.map(lambda value: (value, response)) if include_response else decoded
+
+        def send(request: HttpClientRequest) -> Effect[Any, Any]:
+            if self._transform is None:
+                return self.http_client.execute(request).flat_map(respond)
+            return self._transform(self.http_client).flat_map(
+                lambda client: client.execute(request).flat_map(respond)
+            )
+
+        return self._prepared(operation, path, params, body).flat_map(send)
+
+    def _stream_bytes(
+        self, operation: Operation, path: Path, params: Params | None, body: Body
+    ) -> Stream[bytes, HttpClientError]:
+        def send(request: HttpClientRequest) -> Effect[HttpClientResponse, HttpClientError]:
+            if self._transform is None or not self.transform_streams:
+                return self.http_client.filter_status_ok().execute(request)
+            return self._transform(self.http_client).flat_map(
+                lambda client: client.filter_status_ok().execute(request)
+            )
+
+        sent = self._prepared(operation, path, params, body).flat_map(send)
+        return St.unwrap(sent.map(lambda response: response.stream))
+
+    def _sse(
+        self, operation: Operation, path: Path, params: Params | None, body: Body, schema: Any
+    ) -> Stream[sse.DataEvent[Any], Any]:
+        return (
+            self._stream_bytes(operation, path, params, body)
+            .decode_text()
+            .pipe_through_channel(sse.decode_data_schema(schema))
+        )
+
+    def _binary(
+        self, operation: Operation, path: Path, params: Params | None, body: Body
+    ) -> Stream[bytes, HttpClientError]:
+        return self._stream_bytes(operation, path, params, body)

pyfect/ai/_generated_support.py

@@ -0,0 +1,84 @@
+"""What the generated provider schemas (``pyfect.ai.openai.generated``,
+``pyfect.ai.openrouter.generated``) are built with. Each builder takes and
+gives ``Any``: a generated schema's type is declared from
+``generated_types`` (both come from the same source by the same
+generator), so the type checker reads thousands of declarations instead
+of solving each schema expression, and ``struct`` builds a struct from
+its field schemas without reading the TypedDict's annotations (as
+``S.Struct`` does, which would slow the import down)."""
+
+from __future__ import annotations
+
+import importlib
+import re
+from typing import Any, cast
+
+from pyfect import schema as S
+from pyfect.schema import ast
+from pyfect.schema._struct import StructSchema
+
+
+def struct(_typed_dict: object, fields: dict[str, Any], optional: tuple[str, ...] = ()) -> Any:
+    """The struct of these field schemas; the keys in ``optional`` may be
+    missing. The TypedDict names the struct's type for the reader."""
+    schemas = {name: schema.__codec__() for name, schema in fields.items()}
+    node = ast.Objects(
+        tuple(
+            ast.PropertySignature(name, schema.ast, optional=name in optional)
+            for name, schema in schemas.items()
+        ),
+        (),
+    )
+    return cast("Any", StructSchema(node, schemas))
+
+
+def union(*members: Any, mode: ast.UnionMode = "any_of") -> Any:
+    return S.Union(*members, mode=mode)
+
+
+def array(item: Any) -> Any:
+    return S.Array(item)
+
+
+def record(key: Any, value: Any) -> Any:
+    return S.Record(key, value)
+
+
+def struct_with_rest(schema: Any, *records: Any) -> Any:
+    return S.StructWithRest(schema, *records)
+
+
+def suspend(thunk: Any) -> Any:
+    return cast("Any", S.suspend(thunk))
+
+
+def check(schema: Any, *checks: Any) -> Any:
+    return schema.check(*checks)
+
+
+def literals(values: list[Any]) -> Any:
+    return S.Literals(values)
+
+
+def literal(value: Any) -> Any:
+    return S.Literal(value)
+
+
+def js_pattern(python: str, source: str) -> Any:
+    """``is_pattern`` of the generator's Python translation of the
+    JavaScript pattern ``source``, which messages show."""
+    return S.is_pattern(re.compile(python), expected=f"a string matching the RegExp {source}")
+
+
+def instance_of(cls: type, **annotations: object) -> Any:
+    return cast("Any", S.instance_of(cls, **annotations))
+
+
+def lazy(module: str, name: str) -> Any:
+    """The schema ``name`` of ``module``, imported on first use: a
+    recursive schema's struct, declared after the schemas that use it."""
+
+    def load() -> Any:
+        return getattr(importlib.import_module(module), name)
+
+    return cast("Any", S.suspend(load))

pyfect/ai/_mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server and client internals."""

pyfect/ai/_mcp/batch.py

@@ -0,0 +1,68 @@
+"""A JSON-RPC batch (2025-03-26): its messages handled together, its
+responses gathered into one array."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Never, cast
+
+from pyfect._core import Effect
+from pyfect._fiber import Fiber
+from pyfect.ai._mcp.dispatch import Connection, Send, classify
+from pyfect.ai._mcp.http_admission import has_request_protocol_version
+from pyfect.ai.mcp_schema import JsonObject
+from pyfect.effect import gen, sync
+
+
+def _method(message: object) -> object:
+    return cast("dict[str, object]", message).get("method") if isinstance(message, dict) else None
+
+
+def accepts(connection: Connection, messages: Sequence[object]) -> bool:
+    """Whether ``connection`` 's revision takes this batch: a non-empty one
+    with no ``initialize`` and no stateless request in it."""
+    protocol = connection.protocol
+    return (
+        protocol is not None
+        and protocol.accepts_batches
+        and len(messages) > 0
+        and not any(has_request_protocol_version(m) for m in messages)
+        and not any(_method(m) == "initialize" for m in messages)
+    )
+
+
+def answer(
+    connection: Connection, messages: Sequence[object], notify: Send
+) -> Effect[list[JsonObject]]:
+    """The responses to the batch's requests and invalid messages, in the
+    order they finish; what the server sends meanwhile goes to ``notify``.
+    Interrupting it interrupts the requests."""
+    replies: list[JsonObject] = []
+    started: list[Fiber[None, Never]] = []
+
+    def out(message: JsonObject) -> Effect[None]:
+        if "method" in message:
+            return notify(message)
+        return sync(lambda: replies.append(message))
+
+    @gen
+    def run():
+        # Effect's JSON-RPC decoder drops batch items that are not objects.
+        objects: list[object] = [m for m in messages if isinstance(m, dict)]
+        for message in objects:
+            request = classify(message).request
+            if request is None:
+                yield from connection.dispatch(message, out)
+            else:
+                # Started like a lone request, so it can be cancelled.
+                started.append((yield from connection.start(request, out)))
+        for fiber in started:
+            yield from fiber.await_exit()
+        return replies
+
+    @gen
+    def interrupt_all():
+        for fiber in started:
+            yield from fiber.interrupt()
+
+    return run.on_interrupt(interrupt_all)