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].labelProviders 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#
| Attribute | Type | Description |
|---|---|---|
DECISION_USAGE | Bottom[DecisionUsage, Mapping[str, object], Never, Never] |
Types#
| Type | Definition | Description |
|---|---|---|
Path | type Path = tuple[str | int, ...] | |
Metadata | type Metadata = Mapping[str, JsonValue] | Provider metadata by provider name (a reported cost, ...). |
ProviderDecide | type ProviderDecide[DD: D.AnyDecision = D.AnyDecision] = Callable[[ProviderOptions[DD]], Effect[ProviderResponse, E.AiError]] | |
ProviderAnswer | type ProviderAnswer = ProviderClassifyAnswer | ProviderRateAnswer | ProviderProbabilityAnswer | ProviderLocateAnswer | ProviderRefusalAnswer | A provider's answer to one decision, a plain dict tagged by |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
definition | D.Definition[A, R] | |
input | A |
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.
| Parameter | Type | Description |
|---|---|---|
definition | D.Definition[A, R] | |
input | A |
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))