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: object

Select one label from criteria, a mapping of labels to descriptions.

instructions: str
criteria: Mapping[str, str]
class apache_beam.ml.inference.decision.BooleanQuestion(instructions: str)[source]

Bases: object

Estimate the probability that the statement in instructions is true.

instructions: str
class apache_beam.ml.inference.decision.ScoreQuestion(instructions: str, criteria: Sequence[str])[source]

Bases: object

Score an ordered rubric whose criteria levels are indexed from zero.

Providers may interpolate between levels, returning a fractional score.

instructions: str
criteria: Sequence[str]
class apache_beam.ml.inference.decision.ChoiceAnswer(choice: str, probabilities: ~collections.abc.Mapping[str, float] = <factory>, confidence: float | None = None)[source]

Bases: object

A selected label, with optional label probabilities and confidence.

Probabilities and confidence use [0, 1]. Confidence is a provider’s estimate of answer certainty; None means the provider did not supply it.

choice: str
probabilities: Mapping[str, float]
confidence: float | None = None
class apache_beam.ml.inference.decision.BooleanAnswer(probability: float)[source]

Bases: object

Probability in [0, 1] that the statement is true.

Applications choose their own threshold for acting on this probability.

probability: float
class apache_beam.ml.inference.decision.ScoreAnswer(score: float, probabilities: ~collections.abc.Mapping[int, float] = <factory>, confidence: float | None = None)[source]

Bases: object

Rubric score, optional probabilities by level index, and confidence.

The score uses the question’s zero-based scale. Probabilities and confidence use [0, 1]; None confidence means the provider did not supply it.

score: float
probabilities: Mapping[int, float]
confidence: float | None = None
class apache_beam.ml.inference.decision.DecisionResponse(answers: Mapping[str, ChoiceAnswer | BooleanAnswer | ScoreAnswer], model: str, provider: str, request_id: str | None = None)[source]

Bases: object

One answer per question name, plus the model and provider identifiers.

answers: Mapping[str, ChoiceAnswer | BooleanAnswer | ScoreAnswer]
model: str
provider: str
request_id: str | None = None
class apache_beam.ml.inference.decision.DecisionResult(state: Any, response: DecisionResponse, latency_ms: float)[source]

Bases: object

An input state, its decision response, and evaluation time in milliseconds.

state: Any
response: DecisionResponse
latency_ms: float
class apache_beam.ml.inference.decision.DecisionModel[source]

Bases: ABC

Adapter 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: PTransform

Evaluate typed questions for every input element with a reusable model.

Parameters:
  • model – A serializable DecisionModel adapter. 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 DecisionResult objects, preserving each element’s timestamp and window. Calls run synchronously on the processing thread. The EvaluateDecisions metrics namespace records requests, failures, and the request_latency_ms distribution 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 are good and bad; bad records contain the original state and exception details. Only processing failures are caught. Model setup and teardown failures still propagate to the runner.

expand(states)[source]