judgevet.policy

Status: draft.

judgevet.policy

Supported pure typed policy API.

Rules, policies and reports are immutable. Validation snapshots question constraints without retaining mutable questions. Construct a new ValidatedPolicy with new questions to change those constraints. Callers own all IO and adapters.

Examples:

from judgevet import Noul, NoulAnswer
from judgevet.policy import NoulRule, Policy, validate_policy, evaluate_policy

policy = Policy((NoulRule("clear", minimum=0.8),))
validated = validate_policy(policy, {"clear": Noul(instructions="Clear?")})
report = evaluate_policy(validated, {"clear": NoulAnswer(0.9)})
assert report.passed
See Also

Rule = NoulRule | ChoiceRule | ScoreRule module-attribute

The three supported policy rule variants.

ChoiceRule dataclass

An exact Choice label and optional confidence floor.

Attributes:

Name Type Description
name str

Question name.
choice str

Required choice label.
min_confidence float | None

Optional inclusive confidence floor.

Examples:

rule = ChoiceRule("q", "yes")

__post_init__()

Validate the name, label type and confidence floor.

Raises:

Type Description
PolicyDefinitionError

If a local constraint is invalid.

NoulRule dataclass

Inclusive bounds for a Noul answer.

Attributes:

Name Type Description
name str

Question name.
minimum float | None

Optional inclusive probability floor.
maximum float | None

Optional inclusive probability ceiling.

Examples:

rule = NoulRule("q", minimum=0.5)

__post_init__()

Validate and normalize local rule constraints.

Raises:

Type Description
PolicyDefinitionError

If a name or bound is invalid.

Policy dataclass

A nonempty ordered tuple of uniquely named typed rules.

Attributes:

Name Type Description
rules tuple

Rules in evaluation order, defensively copied into a tuple.

Examples:

policy = Policy((NoulRule("q", minimum=0.5),))

__post_init__()

Copy the rule sequence and validate its elements and names.

Raises:

Type Description
PolicyDefinitionError

If rules are empty, malformed or duplicated.

PolicyAnswerError

Bases: PolicyError

A required policy answer is missing or invalid.

Examples:

error = PolicyAnswerError("invalid policy data")
assert isinstance(error, ValueError)

PolicyDefinitionError

Bases: PolicyError

A policy definition violates its constructor or question constraints.

Examples:

error = PolicyDefinitionError("invalid policy data")
assert isinstance(error, ValueError)

PolicyError

Bases: ValueError

Base error for local policy failures, independent of Jev service errors.

Examples:

error = PolicyError("invalid policy data")
assert isinstance(error, ValueError)

PolicyReport dataclass

All rule outcomes in policy order with a derived aggregate.

Attributes:

Name Type Description
rules tuple

Nonempty immutable rule reports.
passed bool

Whether every rule passed.

Examples:

report = PolicyReport((RuleReport("q", True, "met"),))

passed property

Return the conjunction of all rule outcomes.

Returns:

Type Description
bool

True only when every rule passed.

__post_init__()

Copy and validate reports.

Raises:

Type Description
PolicyDefinitionError

If reports are empty, malformed or duplicated.

RuleReport dataclass

The outcome of one rule.

Attributes:

Name Type Description
question str

Question name.
passed bool

Whether every predicate passed.
detail str

Human-readable comparisons.

Examples:

report = RuleReport("q", True, "met")

__post_init__()

Require a name, boolean outcome and textual detail.

Raises:

Type Description
PolicyDefinitionError

If report fields are malformed.

ScoreRule dataclass

Inclusive score bounds and an optional confidence floor.

Attributes:

Name Type Description
name str

Question name.
minimum float | None

Optional inclusive score floor.
maximum float | None

Optional inclusive score ceiling.
min_confidence float | None

Optional inclusive confidence floor.

Examples:

rule = ScoreRule("q", minimum=0)

__post_init__()

Validate bounds independent of a question's score scale.

Raises:

Type Description
PolicyDefinitionError

If a local constraint is invalid.

ValidatedPolicy dataclass

A validated policy with no retained mutable question objects.

Construct through this class or validate_policy. Both paths validate. To change constraints, construct again with the new questions.

Attributes:

Name Type Description
policy Policy

Original immutable policy.
rules tuple

Rules in evaluation order.

Examples:

validated = ValidatedPolicy(Policy((NoulRule("q", 0),)), {"q": Noul()})

rules property

Return rules in policy order.

Returns:

Type Description
tuple[Rule, ...]

The immutable rule tuple.

__init__(policy, questions)

Validate every referenced question and snapshot its constraints.

Parameters:

Name Type Description Default
policy Policy

Ordered typed policy.

 required
questions Mapping[str, Question]

Typed questions keyed by name.

 required

Raises:

Type Description
PolicyDefinitionError

If policy or referenced questions are invalid.

evaluate_policy(policy, answers)

Evaluate every rule in order; unmet predicates return failed reports.

Only selected answer scalars are checked. Probability distributions and legend metadata remain the answer types' responsibility.

Parameters:

Name Type Description Default
policy ValidatedPolicy

Validated immutable policy.

 required
answers Mapping[str, Answer]

Typed answers keyed by question name.

 required

Returns:

Type Description
PolicyReport

Every rule outcome with a derived aggregate verdict.

Raises:

Type Description
PolicyDefinitionError

If policy is not validated.
PolicyAnswerError

If required answers are missing or invalid.

validate_policy(policy, questions)

Validate a policy against typed questions without retaining mutable inputs.

Parameters:

Name Type Description Default
policy Policy

Typed ordered rules.

 required
questions Mapping[str, Question]

Question definitions keyed by name.

 required

Returns:

Type Description
ValidatedPolicy

A validated immutable policy.

Raises:

Type Description
PolicyDefinitionError

If a definition or referenced question is invalid.