GitHub

decision_model

API reference for decision_model.

The provider-neutral service answering decisions (Effect's DecisionModel).

decide(definition, input=...) encodes the input as JSON, sends every decision of the definition in one provider call and checks the answers; decide_settled makes the same call but keeps each decision's outcome, so valid answers survive beside missing, refused or invalid ones::

response = yield from decision_model.decide(triage, input=ticket)
response.answers[department].label

Providers build the service with make(decide=...); the provider packages (pyfect.ai.openai, pyfect.ai.cloudflare, pyfect.ai.typesafe) each give a layer and a model.

Values

AttributeTypeDescription
DECISION_USAGEBottom[DecisionUsage, Mapping[str, object], Never, Never]

Types

TypeDefinitionDescription
Pathtype Path = tuple[str | int, ...]
Metadatatype Metadata = Mapping[str, JsonValue]

Provider metadata by provider name (a reported cost, ...).

ProviderDecidetype ProviderDecide[DD: D.AnyDecision = D.AnyDecision] = Callable[[ProviderOptions[DD]], Effect[ProviderResponse, E.AiError]]
ProviderAnswertype ProviderAnswer = ProviderClassifyAnswer | ProviderRateAnswer | ProviderProbabilityAnswer | ProviderLocateAnswer | ProviderRefusalAnswer

A provider's answer to one decision, a plain dict tagged by _tag (Effect's ProviderAnswer). Keys it does not name are dropped.

Classes

Functions

make

make(*, decide: ProviderDecide[D.NonLocateDecision], probability_precision: int | None = None, supports_images: bool = False, supports_locate: Literal[False] = False) -> Effect[Service]
make(*, decide: ProviderDecide[D.AnyDecision], probability_precision: int | None = None, supports_images: bool = False, supports_locate: Literal[True]) -> Effect[Service]

A decision model over a provider's decide call. Answers must cover every decision with its own labels; distributions must sum to 1 within 1e-6, confidences and probabilities lie in [0, 1], ratings in [0, len(criteria) - 1] and boxes have edges in [0, 1] that do not cross. A provider that rounds each probability to probability_precision decimals may drift from 1 by half a unit of the last place per label: such drift is accepted and rescaled.

Once encoded, each decision.Image in the input is replaced with a reference string and the provider gets the images in images; an input with images fails with InvalidUserInputError unless supports_images, as does one its schema cannot encode. Locate decisions reach decide only with supports_locate; otherwise a definition with one fails with InvalidUserInputError, as does a locate decision whose path holds no image.

ParameterTypeDescription
decide
probability_precision= None
supports_images= False
supports_locate= False
@overload
def make(
    *,
    decide: ProviderDecide[D.NonLocateDecision],
    probability_precision: int | None = None,
    supports_images: bool = False,
    supports_locate: Literal[False] = False,
) -> Effect[Service]: ...
@overload
def make(
    *,
    decide: ProviderDecide[D.AnyDecision],
    probability_precision: int | None = None,
    supports_images: bool = False,
    supports_locate: Literal[True],
) -> Effect[Service]: ...
def make(
    *,
    decide: ProviderDecide[Any],
    probability_precision: int | None = None,
    supports_images: bool = False,
    supports_locate: bool = False,
) -> Effect[Service]:
    """A decision model over a provider's ``decide`` call. Answers must
    cover every decision with its own labels; distributions must sum to 1
    within ``1e-6``, confidences and probabilities lie in ``[0, 1]``,
    ratings in ``[0, len(criteria) - 1]`` and boxes have edges in ``[0, 1]``
    that do not cross. A provider that rounds each probability to
    ``probability_precision`` decimals may drift from 1 by half a unit of
    the last place per label: such drift is accepted and rescaled.

    Once encoded, each ``decision.Image`` in the input is replaced with a
    reference string and the provider gets the images in ``images``; an
    input with images fails with ``InvalidUserInputError`` unless
    ``supports_images``, as does one its schema cannot encode. Locate
    decisions reach ``decide`` only with ``supports_locate``; otherwise a
    definition with one fails with ``InvalidUserInputError``, as does a
    locate decision whose path holds no image."""
    rounding_error = 0.0 if probability_precision is None else 0.5 * 10**-probability_precision

    def call(
        method: Method, extracted: _Extracted, decisions: Mapping[str, D.AnyDecision]
    ) -> Effect[ProviderResponse, E.AiError]:
        images = extracted.images
        if images and not supports_images:
            return fx.fail(_invalid_input(method, "This decision model does not accept images"))
        for name, decision in decisions.items():
            if not isinstance(decision, D.Locate):
                continue
            if not supports_locate:
                description = "This decision model does not support locate decisions"
                return fx.fail(_invalid_input(method, description))
            if decision.image not in extracted.paths:
                description = (
                    f'Locate decision "{name}" targets "{decision.image}", which holds no image'
                )
                return fx.fail(_invalid_input(method, description))
        options = ProviderOptions(extracted.state, decisions, images or None)
        return fx.suspend(lambda: decide(options))

    def settle(
        method: Method, definition: D.Definition[Any, Any], input: Any
    ) -> Effect[DecideSettledResponse, E.AiError, Any]:
        def settled(response: ProviderResponse) -> DecideSettledResponse:
            outcomes = V.settle(definition.decisions, response.answers, rounding_error)
            return DecideSettledResponse(
                D.Outcomes(definition, outcomes),
                DecisionUsage(response.input_tokens, response.output_tokens),
                response.id,
                response.model_id,
                {} if response.metadata is None else response.metadata,
            )

        encoded: Effect[JsonValue, Any, Any] = S.encode_effect(definition.json_input)(input)
        return (
            encoded.map_error(lambda error: _invalid_input(method, error.message))
            .flat_map(lambda state: Random().map(lambda random: _extract_images(state, random)))
            .flat_map(lambda extracted: call(method, extracted, definition.decisions))
            .map(settled)
        )

    return fx.sync(lambda: Service(settle))

decide

decide[A, R](definition, *, input) -> Effect[DecideResponse, E.AiError, DecisionModel | R]

Every decision's answer from the current DecisionModel. The input is encoded with S.to_codec_json of the definition's schema, needing its encoding services. Fails with ContentPolicyError when the provider refused any decision, else with InvalidOutputError for the first unanswered decision in definition order.

ParameterTypeDescription
definitionD.Definition[A, R]
inputA

Returns Effect[DecideResponse, E.AiError, DecisionModel | R]

def decide[A, R](
    definition: D.Definition[A, R], *, input: A
) -> Effect[DecideResponse, E.AiError, DecisionModel | R]:
    """Every decision's answer from the current ``DecisionModel``. The input
    is encoded with ``S.to_codec_json`` of the definition's schema, needing
    its encoding services. Fails with ``ContentPolicyError`` when the
    provider refused any decision, else with ``InvalidOutputError`` for the
    first unanswered decision in definition order."""
    return DecisionModel().flat_map(lambda model: model.decide(definition, input=input))

decide_settled

decide_settled[A, R](definition, *, input) -> Effect[DecideSettledResponse, E.AiError, DecisionModel | R]

Each decision's Ok answer or Err(Unanswered); encoding and provider failures still fail the effect, and the usage covers the whole call.

ParameterTypeDescription
definitionD.Definition[A, R]
inputA

Returns Effect[DecideSettledResponse, E.AiError, DecisionModel | R]

def decide_settled[A, R](
    definition: D.Definition[A, R], *, input: A
) -> Effect[DecideSettledResponse, E.AiError, DecisionModel | R]:
    """Each decision's ``Ok`` answer or ``Err(Unanswered)``; encoding and
    provider failures still fail the effect, and the usage covers the
    whole call."""
    return DecisionModel().flat_map(lambda model: model.decide_settled(definition, input=input))