apache_beam.ml.inference.decision module
Typed questions and a Beam transform for decision models.
A decision model evaluates named questions against each input state. Choice selects a label, Boolean estimates the probability of a true statement, and Score evaluates an ordered rubric. Adapters translate these types to a local model or a service’s API.
Use the same questions and transform when changing providers:
from apache_beam.ml.inference.decision import ChoiceQuestion
from apache_beam.ml.inference.decision import EvaluateDecisions
questions = {
'team': ChoiceQuestion(
'Which team should handle this message?',
{'billing': 'Invoices and refunds', 'support': 'Technical problems'})
}
decisions = events | EvaluateDecisions(model, questions)
Each output is a DecisionResult containing the original state,
normalized answers, provider metadata, and request latency. Applications apply
thresholds and route these results with ordinary Beam transforms.
- class apache_beam.ml.inference.decision.ChoiceQuestion(instructions: str, criteria: Mapping[str, str])[source]
Bases:
objectSelect one label from
criteria, a mapping of labels to descriptions.
- class apache_beam.ml.inference.decision.BooleanQuestion(instructions: str)[source]
Bases:
objectEstimate the probability that the statement in
instructionsis true.
- class apache_beam.ml.inference.decision.ScoreQuestion(instructions: str, criteria: Sequence[str])[source]
Bases:
objectScore an ordered rubric whose
criterialevels are indexed from zero.Providers may interpolate between levels, returning a fractional score.
- class apache_beam.ml.inference.decision.ChoiceAnswer(choice: str, probabilities: ~collections.abc.Mapping[str, float] = <factory>, confidence: float | None = None)[source]
Bases:
objectA selected label, with optional label probabilities and confidence.
Probabilities and confidence use [0, 1]. Confidence is a provider’s estimate of answer certainty;
Nonemeans the provider did not supply it.
- class apache_beam.ml.inference.decision.BooleanAnswer(probability: float)[source]
Bases:
objectProbability in [0, 1] that the statement is true.
Applications choose their own threshold for acting on this probability.
- class apache_beam.ml.inference.decision.ScoreAnswer(score: float, probabilities: ~collections.abc.Mapping[int, float] = <factory>, confidence: float | None = None)[source]
Bases:
objectRubric score, optional probabilities by level index, and confidence.
The score uses the question’s zero-based scale. Probabilities and confidence use [0, 1];
Noneconfidence means the provider did not supply it.
- class apache_beam.ml.inference.decision.DecisionResponse(answers: Mapping[str, ChoiceAnswer | BooleanAnswer | ScoreAnswer], model: str, provider: str, request_id: str | None = None)[source]
Bases:
objectOne answer per question name, plus the model and provider identifiers.
- answers: Mapping[str, ChoiceAnswer | BooleanAnswer | ScoreAnswer]
- class apache_beam.ml.inference.decision.DecisionResult(state: Any, response: DecisionResponse, latency_ms: float)[source]
Bases:
objectAn input state, its decision response, and evaluation time in milliseconds.
- response: DecisionResponse
- class apache_beam.ml.inference.decision.DecisionModel[source]
Bases:
ABCAdapter contract for hosted and local decision models.
Implement
evaluate()to return the shared answer types. Override the context manager methods to open and close clients or load model weights. Constructors hold serializable configuration; Beam enters the context on the worker and reuses it across elements and bundles on that DoFn instance.An adapter owns provider timeouts, retries, and conversion to the shared types. Input states must be serializable by Beam and accepted by the adapter.
- abstract evaluate(state: Any, questions: Mapping[str, ChoiceQuestion | BooleanQuestion | ScoreQuestion]) DecisionResponse[source]
Evaluate each named question against the same state.
Return exactly one answer of the corresponding type for each question. Choice labels must belong to the question’s criteria; score levels use their zero-based indices. Raise an exception if evaluation fails.
- class apache_beam.ml.inference.decision.EvaluateDecisions(model: DecisionModel, questions: Mapping[str, ChoiceQuestion | BooleanQuestion | ScoreQuestion])[source]
Bases:
PTransformEvaluate typed questions for every input element with a reusable model.
- Parameters:
model – A serializable
DecisionModeladapter. Its context is entered once per DoFn instance and closed during teardown, which is best effort.questions – A mapping of question names to Choice, Boolean, or Score questions. All questions are evaluated against each input state.
- Returns:
A PCollection of
DecisionResultobjects, preserving each element’s timestamp and window. Calls run synchronously on the processing thread. TheEvaluateDecisionsmetrics namespace recordsrequests,failures, and therequest_latency_msdistribution for successful evaluations. Exceptions propagate to the runner.
- with_exception_handling(**kwargs)[source]
Return successful decisions and failed states as tagged PCollections.
Uses
apache_beam.ParDo.with_exception_handling()with the supplied options. The default tags aregoodandbad; bad records contain the original state and exception details. Only processing failures are caught. Model setup and teardown failures still propagate to the runner.