harnest.decisions

All Python modules · Import and compatibility guidance

Provider contract

Member	Required behavior
`version`	Stable provider/model revision used in evaluation provenance
`capabilities`	A `DecisionCapabilities` value describing the guarantees below
`async evaluate(request)`	Return `DecisionResponse` with exactly the requested answer names

Provider capabilities

Capability	Meaning
`kinds`	Nonempty `frozenset` of supported `QuestionKind` values
`batching`	Can evaluate multiple independent questions against the same state
`probabilities`	Every Choice and Score result includes a complete distribution
`confidence`	Every Choice and Score result includes native confidence

Request and result validation

Contract	Shape and validation
`DecisionDefinition`	Name, version, and a nonempty tuple of uniquely named questions
`DecisionRequest`	Definition plus a snapshot of JSON-compatible state; nested mappings and sequences are immutable
`ChoiceResult`	Allowed `value`; optional `probabilities` keyed by every option and `confidence`
`ScoreResult`	Numeric `value` from `0` to `len(levels) - 1`; optional probability tuple in rubric order and `confidence`
`PredicateResult`	`probability` from `0` to `1`; no separate confidence
`DecisionEvaluation`	Validated response, optional policy outcome, definition/provider revisions, duration, and optional error category

Policy rules

Policy	Rules
`ChoicePolicy`	`routes` covers every option; an optional `minimum_confidence` requires native confidence
`ThresholdPolicy`	`value <= lower` selects `below`; `value >= upper` selects `above`; values between select `uncertain`

Exports

Name	Kind
`Choice`	Class
`ChoicePolicy`	Class
`ChoiceResult`	Class
`DecisionAction`	Class
`DecisionAnswer`	Value or type alias
`DecisionBinding`	Class
`DecisionCapabilities`	Class
`DecisionContext`	Class
`DecisionDefinition`	Class
`DecisionError`	Class
`DecisionEvaluation`	Class
`DecisionOutcome`	Class
`DecisionProvider`	Class
`DecisionProviderError`	Class
`DecisionQuestion`	Value or type alias
`DecisionRequest`	Class
`DecisionResponse`	Class
`DecisionTimeoutError`	Class
`DecisionValidationError`	Class
`Decisions`	Class
`FixtureDecisionProvider`	Class
`Predicate`	Class
`PredicateResult`	Class
`QuestionKind`	Class
`Score`	Class
`ScoreResult`	Class
`ThresholdPolicy`	Class

Choice

Choose one key from an unordered map of labels and descriptions.

Choice(name: str, instructions: str, options: Mapping[str, str]) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`instructions`	`str`	`—`
`options`	`Mapping[str, str]`	`—`

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`instructions`	`str`	Required
`options`	`Mapping[str, str]`	Required

from harnest.decisions import Choice

choice = Choice(name=..., instructions=..., options=...)

ChoicePolicy

Map every allowed choice to an outcome, optionally requiring confidence.

ChoicePolicy(
    question: str,
    routes: Mapping[str, DecisionOutcome],
    minimum_confidence: float | None = None,
    uncertain: DecisionOutcome = DecisionOutcome(action=DecisionAction.ABSTAIN, route=None),
) -> None

Fields (— means no declared default):

Field	Type	Default
`question`	`str`	`—`
`routes`	`Mapping[str, DecisionOutcome]`	`—`
`minimum_confidence`	`float \| None`	`None`
`uncertain`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.ABSTAIN, route=None)`

Parameters and example

Parameter	Type	Default
`question`	`str`	Required
`routes`	`Mapping[str, DecisionOutcome]`	Required
`minimum_confidence`	`float \| None`	`None`
`uncertain`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.ABSTAIN, route=None)`

from harnest.decisions import ChoicePolicy

policy = ChoicePolicy(question=..., routes=...)

ChoicePolicy.validate

ChoicePolicy.validate(definition: DecisionDefinition, capabilities: DecisionCapabilities) -> None

Reject incomplete routes and unsupported confidence requirements at binding.

Parameters and example

Parameter	Type	Default
`definition`	`DecisionDefinition`	Required
`capabilities`	`DecisionCapabilities`	Required

from harnest.decisions import ChoicePolicy

policy: ChoicePolicy
policy.validate(definition=..., capabilities=...)

ChoicePolicy.apply

ChoicePolicy.apply(response: DecisionResponse) -> DecisionOutcome

Apply authored branches without interpreting confidence as accuracy.

Parameters and example

Parameter	Type	Default
`response`	`DecisionResponse`	Required

from harnest.decisions import ChoicePolicy

policy: ChoicePolicy
outcome = policy.apply(response=...)

ChoiceResult

A selected option with optional native distribution and confidence.

ChoiceResult(
    value: str,
    probabilities: Mapping[str, float] | None = None,
    confidence: float | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`value`	`str`	`—`
`probabilities`	`Mapping[str, float] \| None`	`None`
`confidence`	`float \| None`	`None`

Parameters and example

Parameter	Type	Default
`value`	`str`	Required
`probabilities`	`Mapping[str, float] \| None`	`None`
`confidence`	`float \| None`	`None`

from harnest.decisions import ChoiceResult

result = ChoiceResult(value=...)

DecisionAction

Authored control-flow signals; none grants permission to execute a tool.

DecisionAction(*values)

Member	Value
`ROUTE`	`'route'`
`PROCEED`	`'proceed'`
`BLOCK`	`'block'`
`REVIEW`	`'review'`
`REASON`	`'reason'`
`ABSTAIN`	`'abstain'`

Example

from harnest.decisions import DecisionAction

value = DecisionAction.ROUTE

DecisionAnswer

DecisionAnswer = harnest.decisions.ChoiceResult | harnest.decisions.ScoreResult | harnest.decisions.PredicateResult

Example

from harnest.decisions import DecisionAnswer

DecisionBinding

Bind a reusable definition to a provider name and optional pure policy.

DecisionBinding(
    definition: DecisionDefinition,
    provider: str,
    policy: ChoicePolicy | ThresholdPolicy | None = None,
    on_error: DecisionOutcome | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`definition`	`DecisionDefinition`	`—`
`provider`	`str`	`—`
`policy`	`ChoicePolicy \| ThresholdPolicy \| None`	`None`
`on_error`	`DecisionOutcome \| None`	`None`

Parameters and example

Parameter	Type	Default
`definition`	`DecisionDefinition`	Required
`provider`	`str`	Required
`policy`	`ChoicePolicy \| ThresholdPolicy \| None`	`None`
`on_error`	`DecisionOutcome \| None`	`None`

from harnest.decisions import DecisionBinding

binding = DecisionBinding(definition=..., provider=...)

DecisionCapabilities

Provider guarantees checked before evaluation, without guessing calibration.

DecisionCapabilities(
    kinds: frozenset[QuestionKind],
    batching: bool = False,
    probabilities: bool = False,
    confidence: bool = False,
) -> None

Fields (— means no declared default):

Field	Type	Default
`kinds`	`frozenset[QuestionKind]`	`—`
`batching`	`bool`	`False`
`probabilities`	`bool`	`False`
`confidence`	`bool`	`False`

Parameters and example

Parameter	Type	Default
`kinds`	`frozenset[QuestionKind]`	Required
`batching`	`bool`	`False`
`probabilities`	`bool`	`False`
`confidence`	`bool`	`False`

from harnest.decisions import DecisionCapabilities

capabilities = DecisionCapabilities(kinds=...)

DecisionContext

A revocable decision facade bound to the invocation that obtained it.

DecisionContext(active: Any) -> None

Parameters and example

Parameter	Type	Default
`active`	`Any`	Required

from harnest.decisions import DecisionContext

context = DecisionContext(active=...)

DecisionContext.evaluate

async DecisionContext.evaluate(name: str, state: Mapping[str, Any]) -> DecisionEvaluation

Evaluate within the owning scope and record only explicitly public results.

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`state`	`Mapping[str, Any]`	Required

from harnest.decisions import DecisionContext

context: DecisionContext
evaluation = await context.evaluate(name=..., state=...)

DecisionDefinition

A versioned set of independent questions, separate from provider selection.

DecisionDefinition(name: str, version: str, questions: tuple[DecisionQuestion, ...]) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`version`	`str`	`—`
`questions`	`tuple[DecisionQuestion, ...]`	`—`

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`version`	`str`	Required
`questions`	`tuple[DecisionQuestion, ...]`	Required

from harnest.decisions import DecisionDefinition

definition = DecisionDefinition(name=..., version=..., questions=...)

DecisionError

A decision could not be evaluated without violating its contract.

Example

from harnest.decisions import DecisionError

try:
    ...
except DecisionError as error:
    ...

DecisionEvaluation

Validated results or an explicit failure outcome, with provider provenance.

DecisionEvaluation(
    decision: str,
    version: str,
    provider: str,
    provider_version: str,
    response: DecisionResponse | None,
    outcome: DecisionOutcome | None,
    duration_seconds: float,
    error: str | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`decision`	`str`	`—`
`version`	`str`	`—`
`provider`	`str`	`—`
`provider_version`	`str`	`—`
`response`	`DecisionResponse \| None`	`—`
`outcome`	`DecisionOutcome \| None`	`—`
`duration_seconds`	`float`	`—`
`error`	`str \| None`	`None`

Parameters and example

Parameter	Type	Default
`decision`	`str`	Required
`version`	`str`	Required
`provider`	`str`	Required
`provider_version`	`str`	Required
`response`	`DecisionResponse \| None`	Required
`outcome`	`DecisionOutcome \| None`	Required
`duration_seconds`	`float`	Required
`error`	`str \| None`	`None`

from harnest.decisions import DecisionEvaluation

evaluation = DecisionEvaluation(
    decision=...,
    version=...,
    provider=...,
    provider_version=...,
    response=...,
    outcome=...,
    duration_seconds=...,
)

DecisionOutcome

A policy action and, for routing, an authored destination identity.

DecisionOutcome(action: DecisionAction, route: str | None = None) -> None

Fields (— means no declared default):

Field	Type	Default
`action`	`DecisionAction`	`—`
`route`	`str \| None`	`None`

Parameters and example

Parameter	Type	Default
`action`	`DecisionAction`	Required
`route`	`str \| None`	`None`

from harnest.decisions import DecisionOutcome

outcome = DecisionOutcome(action=...)

DecisionProvider

Implement in application code or an extension; lifecycle owns the client.

DecisionProvider(*args, **kwargs)

Fields (— means no declared default):

Field	Type	Default
`capabilities`	`DecisionCapabilities`	`—`
`version`	`str`	`—`

Example

from harnest.decisions import DecisionProvider

class MyDecisionProvider(DecisionProvider):
    ...

DecisionProvider.evaluate

async DecisionProvider.evaluate(request: DecisionRequest) -> DecisionResponse

Evaluate independent questions without executing the selected action.

Parameters and example

Parameter	Type	Default
`request`	`DecisionRequest`	Required

from harnest.decisions import DecisionProvider

provider: DecisionProvider
response = await provider.evaluate(request=...)

DecisionProviderError

A provider failed; its private exception is intentionally not exposed.

Example

from harnest.decisions import DecisionProviderError

try:
    ...
except DecisionProviderError as error:
    ...

DecisionQuestion

DecisionQuestion = harnest.decisions.Choice | harnest.decisions.Score | harnest.decisions.Predicate

Example

from harnest.decisions import DecisionQuestion

DecisionRequest

A definition and isolated state snapshot sent to one provider evaluation.

DecisionRequest(definition: DecisionDefinition, state: Mapping[str, Any]) -> None

Fields (— means no declared default):

Field	Type	Default
`definition`	`DecisionDefinition`	`—`
`state`	`Mapping[str, Any]`	`—`

Parameters and example

Parameter	Type	Default
`definition`	`DecisionDefinition`	Required
`state`	`Mapping[str, Any]`	Required

from harnest.decisions import DecisionRequest

request = DecisionRequest(definition=..., state=...)

DecisionResponse

Typed answers keyed by the exact question identities in the request.

DecisionResponse(answers: Mapping[str, DecisionAnswer]) -> None

Fields (— means no declared default):

Field	Type	Default
`answers`	`Mapping[str, DecisionAnswer]`	`—`

Parameters and example

Parameter	Type	Default
`answers`	`Mapping[str, DecisionAnswer]`	Required

from harnest.decisions import DecisionResponse

response = DecisionResponse(answers=...)

DecisionTimeoutError

A decision exceeded its configured evaluation deadline.

Example

from harnest.decisions import DecisionTimeoutError

try:
    ...
except DecisionTimeoutError as error:
    ...

DecisionValidationError

A provider response did not match the declared decision contract.

Example

from harnest.decisions import DecisionValidationError

try:
    ...
except DecisionValidationError as error:
    ...

Decisions

Decisions(
    *,
    providers: Mapping[str, DecisionProvider],
    bindings: Sequence[DecisionBinding],
    timeout_seconds: float = 10,
) -> None

Parameters and example

Parameter	Type	Default
`providers`	`Mapping[str, DecisionProvider]`	Required
`bindings`	`Sequence[DecisionBinding]`	Required
`timeout_seconds`	`float`	`10`

from harnest.decisions import Decisions

decisions = Decisions(providers=..., bindings=...)

Decisions.evaluate

async Decisions.evaluate(name: str, state: Mapping[str, Any]) -> DecisionEvaluation

Evaluate an isolated snapshot once; failures never trigger implicit retries.

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`state`	`Mapping[str, Any]`	Required

from harnest.decisions import Decisions

decisions: Decisions
evaluation = await decisions.evaluate(name=..., state=...)

Decisions.evaluate_definition

async Decisions.evaluate_definition(
    definition: DecisionDefinition,
    state: Mapping[str, Any],
    *,
    provider: str | None = None,
) -> DecisionEvaluation

Evaluate a runtime-built definition without mutating registered decisions.

Parameters and example

Parameter	Type	Default
`definition`	`DecisionDefinition`	Required
`state`	`Mapping[str, Any]`	Required
`provider`	`str \| None`	`None`

from harnest.decisions import Decisions

decisions: Decisions
evaluation = await decisions.evaluate_definition(definition=..., state=...)

FixtureDecisionProvider

Return fixtures keyed by (decision name, version), without retaining private state.

FixtureDecisionProvider(
    responses: Mapping[tuple[str, str], harnest.decisions.DecisionResponse],
    *,
    capabilities: harnest.decisions.DecisionCapabilities,
    version: str = 'fixture-1',
) -> None

Parameters and example

Parameter	Type	Default
`responses`	`Mapping[tuple[str, str], harnest.decisions.DecisionResponse]`	Required
`capabilities`	`harnest.decisions.DecisionCapabilities`	Required
`version`	`str`	`'fixture-1'`

from harnest.decisions import FixtureDecisionProvider

provider = FixtureDecisionProvider(responses=..., capabilities=...)

FixtureDecisionProvider.evaluate

async FixtureDecisionProvider.evaluate(request: harnest.decisions.DecisionRequest) -> harnest.decisions.DecisionResponse

Select a deterministic fixture; missing revisions are errors, never live calls.

Parameters and example

Parameter	Type	Default
`request`	`harnest.decisions.DecisionRequest`	Required

from harnest.decisions import FixtureDecisionProvider

provider: FixtureDecisionProvider
response = await provider.evaluate(request=...)

Predicate

Judge a proposition by returning the probability that it is true.

Predicate(name: str, instructions: str) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`instructions`	`str`	`—`

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`instructions`	`str`	Required

from harnest.decisions import Predicate

predicate = Predicate(name=..., instructions=...)

PredicateResult

The probability of true; this is not a generic confidence score.

PredicateResult(probability: float) -> None

Fields (— means no declared default):

Field	Type	Default
`probability`	`float`	`—`

Parameters and example

Parameter	Type	Default
`probability`	`float`	Required

from harnest.decisions import PredicateResult

result = PredicateResult(probability=...)

QuestionKind

Portable question shapes a decision provider can explicitly support.

QuestionKind(*values)

Member	Value
`CHOICE`	`'choice'`
`SCORE`	`'score'`
`PREDICATE`	`'predicate'`

Example

from harnest.decisions import QuestionKind

value = QuestionKind.CHOICE

Score

Judge a rubric on the numeric scale 0 through len(levels) minus one.

Score(name: str, instructions: str, levels: tuple[str, ...]) -> None

Fields (— means no declared default):

Field	Type	Default
`name`	`str`	`—`
`instructions`	`str`	`—`
`levels`	`tuple[str, ...]`	`—`

Parameters and example

Parameter	Type	Default
`name`	`str`	Required
`instructions`	`str`	Required
`levels`	`tuple[str, ...]`	Required

from harnest.decisions import Score

score = Score(name=..., instructions=..., levels=...)

ScoreResult

A rubric position with optional probabilities in the declared level order.

ScoreResult(
    value: float,
    probabilities: tuple[float, ...] | None = None,
    confidence: float | None = None,
) -> None

Fields (— means no declared default):

Field	Type	Default
`value`	`float`	`—`
`probabilities`	`tuple[float, ...] \| None`	`None`
`confidence`	`float \| None`	`None`

Parameters and example

Parameter	Type	Default
`value`	`float`	Required
`probabilities`	`tuple[float, ...] \| None`	`None`
`confidence`	`float \| None`	`None`

from harnest.decisions import ScoreResult

result = ScoreResult(value=...)

ThresholdPolicy

Use inclusive lower/upper boundaries and an explicit middle uncertainty band.

ThresholdPolicy(
    question: str,
    lower: float,
    upper: float,
    below: DecisionOutcome = DecisionOutcome(action=DecisionAction.BLOCK, route=None),
    above: DecisionOutcome = DecisionOutcome(action=DecisionAction.PROCEED, route=None),
    uncertain: DecisionOutcome = DecisionOutcome(action=DecisionAction.ABSTAIN, route=None),
) -> None

Fields (— means no declared default):

Field	Type	Default
`question`	`str`	`—`
`lower`	`float`	`—`
`upper`	`float`	`—`
`below`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.BLOCK, route=None)`
`above`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.PROCEED, route=None)`
`uncertain`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.ABSTAIN, route=None)`

Parameters and example

Parameter	Type	Default
`question`	`str`	Required
`lower`	`float`	Required
`upper`	`float`	Required
`below`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.BLOCK, route=None)`
`above`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.PROCEED, route=None)`
`uncertain`	`DecisionOutcome`	`DecisionOutcome(action=DecisionAction.ABSTAIN, route=None)`

from harnest.decisions import ThresholdPolicy

policy = ThresholdPolicy(question=..., lower=..., upper=...)

ThresholdPolicy.validate

ThresholdPolicy.validate(definition: DecisionDefinition, capabilities: DecisionCapabilities) -> None

Check thresholds against the actual probability or rubric scale.

Parameters and example

Parameter	Type	Default
`definition`	`DecisionDefinition`	Required
`capabilities`	`DecisionCapabilities`	Required

from harnest.decisions import ThresholdPolicy

policy: ThresholdPolicy
policy.validate(definition=..., capabilities=...)

ThresholdPolicy.apply

ThresholdPolicy.apply(response: DecisionResponse) -> DecisionOutcome

Return a signal on the question’s native scale without running effects.

Parameters and example

Parameter	Type	Default
`response`	`DecisionResponse`	Required

from harnest.decisions import ThresholdPolicy

policy: ThresholdPolicy
outcome = policy.apply(response=...)

​Provider contract

​Provider capabilities

​Request and result validation

​Policy rules

​Exports

​Choice

​ChoicePolicy

​ChoicePolicy.validate

​ChoicePolicy.apply

​ChoiceResult

​DecisionAction

​DecisionAnswer

​DecisionBinding

​DecisionCapabilities

​DecisionContext

​DecisionContext.evaluate

​DecisionDefinition

​DecisionError

​DecisionEvaluation

​DecisionOutcome

​DecisionProvider

​DecisionProvider.evaluate

​DecisionProviderError

​DecisionQuestion

​DecisionRequest

​DecisionResponse

​DecisionTimeoutError

​DecisionValidationError

​Decisions

​Decisions.evaluate

​Decisions.evaluate_definition

​FixtureDecisionProvider

​FixtureDecisionProvider.evaluate

​Predicate

​PredicateResult

​QuestionKind

​Score

​ScoreResult

​ThresholdPolicy

​ThresholdPolicy.validate

​ThresholdPolicy.apply

Provider contract

Provider capabilities

Request and result validation

Policy rules

Exports

Choice

ChoicePolicy

ChoicePolicy.validate

ChoicePolicy.apply

ChoiceResult

DecisionAction

DecisionAnswer

DecisionBinding

DecisionCapabilities

DecisionContext

DecisionContext.evaluate

DecisionDefinition

DecisionError

DecisionEvaluation

DecisionOutcome

DecisionProvider

DecisionProvider.evaluate

DecisionProviderError

DecisionQuestion

DecisionRequest

DecisionResponse

DecisionTimeoutError

DecisionValidationError

Decisions

Decisions.evaluate

Decisions.evaluate_definition

FixtureDecisionProvider

FixtureDecisionProvider.evaluate

Predicate

PredicateResult

QuestionKind

Score

ScoreResult

ThresholdPolicy

ThresholdPolicy.validate

ThresholdPolicy.apply