GitHub

decision

API reference for decision.

Decisions a DecisionModel answers about one input (Effect's Decision): classify (one label of a set), rate (a place on an ordered scale), probability (how likely a statement holds) and locate (where a target is in an Image field of the input), named and paired with an input schema by make::

department = decision.classify(
    instructions="Which team should handle this",
    criteria={"billing": "payments", "technical": "bugs"},
)
urgent = decision.probability(instructions="The message is time-sensitive")
triage = decision.make(input=Ticket, decisions={"department": department, "urgent": urgent})

The answers of a response are keyed by name, and typed when looked up by the decision itself: response.answers[department].label is Literal["billing", "technical"].

Values

AttributeTypeDescription
IMAGE_KEYLiteral['~effect/ai/Decision/Image'] = '~effect/ai/Decision/Image'

The key that marks an encoded Image.

ImageEncodedtype[ImageEncoded]

The JSON encoding of an Image: base64 data or a URL with its media type, under IMAGE_KEY.

ImageS.Bottom[ImageValue, Mapping[str, object]]

The schema of an image input field (Effect's Decision.Image). Its type is decision_model.Image: a media type with base64 data, bytes or a URL. decide replaces each one in the encoded input with a reference string and sends the images to the provider separately; an image used in several fields is sent once. Decisions refer to it by the field's path.

Types

TypeDefinitionDescription
Descriptiontype Description = str | Mapping[str, JsonValue] | Sequence[JsonValue]

Instructions or a description: a string, a JSON object or a JSON array.

AnyDecisiontype AnyDecision = Classify[Any] | Rate[Any] | Probability | Locate
NonLocateDecisiontype NonLocateDecision = Classify[Any] | Rate[Any] | Probability

The decisions a provider without supports_locate receives.

AnyAnswertype AnyAnswer = ClassifyAnswer[Any] | RateAnswer[Any] | ProbabilityAnswer | LocateAnswer
UnansweredReasontype UnansweredReason = Literal['Missing', 'Refused', 'NoDistribution', 'Invalid']
Outcometype Outcome[T] = Result[T, Unanswered]

Classes

Functions

classify

classify[LL: LiteralString](*, instructions: Description, criteria: Mapping[LL, Description | None]) -> Classify[LL]
classify(*, instructions: Description, criteria: Mapping[str, Description | None]) -> Classify[str]

A classification over the labels of criteria; raises ValueError for fewer than two labels.

ParameterTypeDescription
instructions
criteria
@overload
def classify[LL: LiteralString](
    *, instructions: Description, criteria: Mapping[LL, Description | None]
) -> Classify[LL]: ...
@overload
def classify(
    *, instructions: Description, criteria: Mapping[str, Description | None]
) -> Classify[str]: ...
def classify(
    *, instructions: Description, criteria: Mapping[Any, Description | None]
) -> Classify[Any]:
    """A classification over the labels of ``criteria``; raises
    ``ValueError`` for fewer than two labels."""
    if len(criteria) < 2:
        raise ValueError("Decision.classify: criteria must contain at least two labels")
    return Classify(instructions, criteria)

rate

rate[LL: LiteralString](*, instructions: Description, criteria: list[LL] | tuple[LL, ...] | Mapping[LL, Description]) -> Rate[LL]
rate(*, instructions: Description, criteria: Sequence[str] | Mapping[str, Description]) -> Rate[str]

A rating over criteria, lowest first: labels that are their own descriptions, or a mapping of labels to descriptions. Raises ValueError for fewer than two levels or a repeated label.

ParameterTypeDescription
instructions
criteria
@overload
def rate[LL: LiteralString](
    *, instructions: Description, criteria: list[LL] | tuple[LL, ...] | Mapping[LL, Description]
) -> Rate[LL]: ...
@overload
def rate(
    *, instructions: Description, criteria: Sequence[str] | Mapping[str, Description]
) -> Rate[str]: ...
def rate(
    *, instructions: Description, criteria: Sequence[Any] | Mapping[Any, Description]
) -> Rate[Any]:
    """A rating over ``criteria``, lowest first: labels that are their own
    descriptions, or a mapping of labels to descriptions. Raises
    ``ValueError`` for fewer than two levels or a repeated label."""
    if isinstance(criteria, Mapping):
        levels = tuple(Level(label, description) for label, description in criteria.items())
    else:
        levels = tuple(Level(label, label) for label in criteria)
    if len(levels) < 2:
        raise ValueError("Decision.rate: criteria must contain at least two levels")
    if len({level.label for level in levels}) != len(levels):
        raise ValueError("Decision.rate: criteria must contain distinct levels")
    return Rate(instructions, levels)

probability

probability(*, instructions, criteria=None) -> Probability

A probability decision; criteria describes both outcomes.

ParameterTypeDescription
instructionsDescription
criteriaProbabilityCriteria | None = None

Returns Probability

def probability(
    *, instructions: Description, criteria: ProbabilityCriteria | None = None
) -> Probability:
    """A probability decision; ``criteria`` describes both outcomes."""
    return Probability(instructions, criteria)

locate

locate(*, image, instructions) -> Locate

A decision finding one target in the image field at image: keys of the encoded input joined with ., array indices in brackets ("frames[2].frame"). The model must support locate decisions, and decide fails with InvalidUserInputError when the path holds no image. The answer is always one box, even when the target is absent: pair it with a probability decision that the target is present.

ParameterTypeDescription
imagestr
instructionsDescription

Returns Locate

def locate(*, image: str, instructions: Description) -> Locate:
    """A decision finding one target in the image field at ``image``: keys
    of the encoded input joined with ``.``, array indices in brackets
    (``"frames[2].frame"``). The model must support locate decisions, and
    ``decide`` fails with ``InvalidUserInputError`` when the path holds no
    image. The answer is always one box, even when the target is absent:
    pair it with a ``probability`` decision that the target is present."""
    return Locate(image, instructions)

make

make[T, R](*, input, decisions) -> Definition[T, R]

A definition of decisions about values of input. Raises ValueError when decisions is empty.

ParameterTypeDescription
inputS.Codec[T, Any, Any, R]
decisionsMapping[str, AnyDecision]

Returns Definition[T, R]

def make[T, R](
    *, input: S.Codec[T, Any, Any, R], decisions: Mapping[str, AnyDecision]
) -> Definition[T, R]:
    """A definition of ``decisions`` about values of ``input``. Raises
    ``ValueError`` when ``decisions`` is empty."""
    if not decisions:
        raise ValueError("Decision.make: decisions must not be empty")
    return Definition(input, decisions)