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#
| Attribute | Type | Description |
|---|---|---|
IMAGE_KEY | Literal['~effect/ai/Decision/Image'] = '~effect/ai/Decision/Image' | The key that marks an encoded |
ImageEncoded | type[ImageEncoded] | The JSON encoding of an |
Image | S.Bottom[ImageValue, Mapping[str, object]] | The schema of an image input field (Effect's |
Types#
| Type | Definition | Description |
|---|---|---|
Description | type Description = str | Mapping[str, JsonValue] | Sequence[JsonValue] | Instructions or a description: a string, a JSON object or a JSON array. |
AnyDecision | type AnyDecision = Classify[Any] | Rate[Any] | Probability | Locate | |
NonLocateDecision | type NonLocateDecision = Classify[Any] | Rate[Any] | Probability | The decisions a provider without |
AnyAnswer | type AnyAnswer = ClassifyAnswer[Any] | RateAnswer[Any] | ProbabilityAnswer | LocateAnswer | |
UnansweredReason | type UnansweredReason = Literal['Missing', 'Refused', 'NoDistribution', 'Invalid'] | |
Outcome | type 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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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) -> ProbabilityA probability decision; criteria describes both outcomes.
| Parameter | Type | Description |
|---|---|---|
instructions | Description | |
criteria | ProbabilityCriteria | 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) -> LocateA 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.
| Parameter | Type | Description |
|---|---|---|
image | str | |
instructions | Description |
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.
| Parameter | Type | Description |
|---|---|---|
input | S.Codec[T, Any, Any, R] | |
decisions | Mapping[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)