1 oracle.environment

oracle.environment

Identity-bound actor contexts for online oracle decisions.

1.1 Classes

Name Description
OracleDecisionContext Bind one actor projection to an exact replay state and candidate table.
OracleEndpointEvaluation Detached JSON-safe endpoint facts for one oracle episode.
OracleQuery Closed oracle-label query over one bound candidate table.
QhDecisionInputContract Content identities and causal semantics admitted for one Q_H decision.
StaleOracleDecisionContextError Raised before scoring when a bound decision payload changed in place.

1.1.1 OracleDecisionContext

oracle.environment.OracleDecisionContext(
    episode_id,
    state_hash,
    table_hash,
    actor_hash,
    trajectory,
    candidates,
    actor,
    input_contract,
    actor_profile='qh_cf0_v1',
)

Bind one actor projection to an exact replay state and candidate table.

The frozen dataclass is intentionally only an envelope: replay DTOs contain mutable nested tensors and lists. validate_integrity therefore recomputes all hashes immediately before every consumer crosses the seam.

1.1.1.1 Attributes

Name Description
episode_id Stable source/target/config identity supplied by the episode owner.
state_hash Canonical hash of the episode identity and selected trajectory prefix.
table_hash Canonical hash of the state identity and complete candidate table.
actor_hash Canonical hash of the actor-safe Q_H projection and profile identity.
trajectory Current replay prefix; nested mutation invalidates this context.
candidates Exact full-shell table aligned with the actor’s final state row.
actor Batched actor-only chain prefix consumed by the finite-horizon scorer.
input_contract Explicit target, candidate, mask, representation, and cohort provenance.
actor_profile Closed actor projection identity included in actor_hash.

1.1.1.2 Methods

Name Description
bind Validate candidate alignment and create canonical detached hashes.
to_qh_actor Return the bound one-way actor projection after integrity validation.
validate_integrity Reject nested state, table, or actor mutation before any scoring work.
1.1.1.2.1 bind
oracle.environment.OracleDecisionContext.bind(
    episode_id,
    trajectory,
    candidates,
    actor,
    input_contract,
    actor_profile='qh_cf0_v1',
)

Validate candidate alignment and create canonical detached hashes.

1.1.1.2.2 to_qh_actor
oracle.environment.OracleDecisionContext.to_qh_actor()

Return the bound one-way actor projection after integrity validation.

1.1.1.2.3 validate_integrity
oracle.environment.OracleDecisionContext.validate_integrity()

Reject nested state, table, or actor mutation before any scoring work.

1.1.2 OracleEndpointEvaluation

oracle.environment.OracleEndpointEvaluation(
    episode_id,
    state_hash,
    acquisitions,
    terminal,
    terminal_reason,
    target_rri,
    root_gain,
    oracle_query_count,
)

Detached JSON-safe endpoint facts for one oracle episode.

1.1.2.1 Attributes

Name Description
episode_id Episode identity shared with every decision context.
state_hash Terminal replay-state identity.
acquisitions Number of committed selected actions.
terminal Whether the episode reached a terminal state.
terminal_reason Stable reason for horizon completion or early termination.
target_rri Independent final target RRI value.
root_gain Independent final root-normalized target gain.
oracle_query_count Total hard-oracle candidate rows queried by the episode.

1.1.3 OracleQuery

oracle.environment.OracleQuery(mode, shell_indices=())

Closed oracle-label query over one bound candidate table.

1.1.3.1 Attributes

Name Description
mode Dense learning support, ordered evaluation subset, or one selected row.
shell_indices Ordered unique full-shell rows required by sparse query modes.

1.1.4 QhDecisionInputContract

oracle.environment.QhDecisionInputContract(
    actor_state_contract_hash,
    learning_contract_hash,
    target_protocol,
    target_source,
    descriptor_source,
    descriptor_provenance,
    descriptor_hash,
    candidate_config_hash,
    action_mask_semantics,
    cohort,
    representation_semantics='root_moments_v1',
)

Content identities and causal semantics admitted for one Q_H decision.

1.1.4.1 Attributes

Name Description
actor_state_contract_hash Exact hash of the actor-state schema and immutable source contract.
learning_contract_hash Exact hash of the replay support and fitted-Q learning semantics.
target_protocol Target-input protocol carried by this decision.
target_source Source that selected the target task.
descriptor_source Source block that constructed the actor-visible target descriptor.
descriptor_provenance Construction class of the target descriptor.
descriptor_hash Content digest of the exact target descriptor supplied to the actor.
candidate_config_hash Candidate-generation configuration identity for the bound shell.
action_mask_semantics Causal meaning of the action support supplied to the scorer.
cohort Explicit evaluation cohort; privileged inputs are confined to the Oracle upper bound.
representation_semantics Closed scorer representation constructed from root-frame evidence.

1.1.5 StaleOracleDecisionContextError

oracle.environment.StaleOracleDecisionContextError()

Raised before scoring when a bound decision payload changed in place.

Back to top