> This page is for version 0.3.0.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.

# nemo_gym.agents.context_management.history

Append-only semantic history, media identities, and policy view structures.

## Module Contents

### Classes

| Name                                                                                                     | Description                                                      |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`ContextMeasurements`](#nemo_gym-agents-context_management-history-ContextMeasurements)                 | -                                                                |
| [`FinalizedChunkRecord`](#nemo_gym-agents-context_management-history-FinalizedChunkRecord)               | -                                                                |
| [`GuardEvaluation`](#nemo_gym-agents-context_management-history-GuardEvaluation)                         | -                                                                |
| [`GuardOutcomeRecord`](#nemo_gym-agents-context_management-history-GuardOutcomeRecord)                   | -                                                                |
| [`HistoryViewPlan`](#nemo_gym-agents-context_management-history-HistoryViewPlan)                         | -                                                                |
| [`KeepPartRef`](#nemo_gym-agents-context_management-history-KeepPartRef)                                 | -                                                                |
| [`MaterializedHistoryView`](#nemo_gym-agents-context_management-history-MaterializedHistoryView)         | -                                                                |
| [`OmissionArtifact`](#nemo_gym-agents-context_management-history-OmissionArtifact)                       | -                                                                |
| [`PolicyDecisionRecord`](#nemo_gym-agents-context_management-history-PolicyDecisionRecord)               | -                                                                |
| [`PreparedHistoryView`](#nemo_gym-agents-context_management-history-PreparedHistoryView)                 | -                                                                |
| [`RewriteBoundaryEvent`](#nemo_gym-agents-context_management-history-RewriteBoundaryEvent)               | -                                                                |
| [`SemanticEvent`](#nemo_gym-agents-context_management-history-SemanticEvent)                             | -                                                                |
| [`SemanticHistory`](#nemo_gym-agents-context_management-history-SemanticHistory)                         | Append-only semantic history used to derive model request views. |
| [`SemanticPart`](#nemo_gym-agents-context_management-history-SemanticPart)                               | -                                                                |
| [`TransformationLineageRecord`](#nemo_gym-agents-context_management-history-TransformationLineageRecord) | -                                                                |
| [`UnitLineageRecord`](#nemo_gym-agents-context_management-history-UnitLineageRecord)                     | -                                                                |

### Functions

| Name                                                                                                         | Description                                                           |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| [`_as_item_dict`](#nemo_gym-agents-context_management-history-_as_item_dict)                                 | -                                                                     |
| [`_config_digest`](#nemo_gym-agents-context_management-history-_config_digest)                               | -                                                                     |
| [`_lineage_record`](#nemo_gym-agents-context_management-history-_lineage_record)                             | -                                                                     |
| [`_ordered_id_digest`](#nemo_gym-agents-context_management-history-_ordered_id_digest)                       | -                                                                     |
| [`_part_digest`](#nemo_gym-agents-context_management-history-_part_digest)                                   | -                                                                     |
| [`_part_kind`](#nemo_gym-agents-context_management-history-_part_kind)                                       | -                                                                     |
| [`_semantic_items_digest`](#nemo_gym-agents-context_management-history-_semantic_items_digest)               | -                                                                     |
| [`_semantic_part_digest`](#nemo_gym-agents-context_management-history-_semantic_part_digest)                 | -                                                                     |
| [`_view_digest`](#nemo_gym-agents-context_management-history-_view_digest)                                   | -                                                                     |
| [`canonical_digest`](#nemo_gym-agents-context_management-history-canonical_digest)                           | -                                                                     |
| [`normalize_semantic_items`](#nemo_gym-agents-context_management-history-normalize_semantic_items)           | Normalize a legacy request input for comparison with a semantic view. |
| [`register_semantic_part_kind`](#nemo_gym-agents-context_management-history-register_semantic_part_kind)     | -                                                                     |
| [`stable_id`](#nemo_gym-agents-context_management-history-stable_id)                                         | -                                                                     |
| [`strip_completion_evidence`](#nemo_gym-agents-context_management-history-strip_completion_evidence)         | Return semantic API content with private token evidence removed.      |
| [`unregister_semantic_part_kind`](#nemo_gym-agents-context_management-history-unregister_semantic_part_kind) | -                                                                     |

### Data

[`BUILTIN_SEMANTIC_PART_KINDS`](#nemo_gym-agents-context_management-history-BUILTIN_SEMANTIC_PART_KINDS)

[`LineageDisposition`](#nemo_gym-agents-context_management-history-LineageDisposition)

[`SemanticPartKind`](#nemo_gym-agents-context_management-history-SemanticPartKind)

[`_IMAGE_PART_TYPES`](#nemo_gym-agents-context_management-history-_IMAGE_PART_TYPES)

[`_PRIVATE_ID_FIELDS`](#nemo_gym-agents-context_management-history-_PRIVATE_ID_FIELDS)

[`_REGISTERED_SEMANTIC_PART_KINDS`](#nemo_gym-agents-context_management-history-_REGISTERED_SEMANTIC_PART_KINDS)

[`_TOKEN_METADATA_FIELDS`](#nemo_gym-agents-context_management-history-_TOKEN_METADATA_FIELDS)

### API

```python
class nemo_gym.agents.context_management.history.ContextMeasurements(
    prompt_token_count: int,
    active_image_count: int,
    vision_token_count: int
)
```

Dataclass

**`active_image_count`** `int`

---

**`prompt_token_count`** `int`

---

**`vision_token_count`** `int`

---

```python
class nemo_gym.agents.context_management.history.FinalizedChunkRecord(
    chunk_id: str,
    block_index: int,
    eligible_action_ids: tuple[str, ...],
    completion_evidence_ids: tuple[str, ...],
    first_action_turn: int,
    last_action_turn: int,
    configured_actions_per_chunk: int,
    policy_config_digest: str,
    actual_action_count: int,
    early_close_reason: str | None,
    active_observation_group_count: int,
    active_raw_image_count: int
)
```

Dataclass

**`active_observation_group_count`** `int`

---

**`active_raw_image_count`** `int`

---

**`actual_action_count`** `int`

---

**`block_index`** `int`

---

**`chunk_id`** `str`

---

**`completion_evidence_ids`** `tuple[str, ...]`

---

**`configured_actions_per_chunk`** `int`

---

**`early_close_reason`** `str | None`

---

**`eligible_action_ids`** `tuple[str, ...]`

---

**`first_action_turn`** `int`

---

**`last_action_turn`** `int`

---

**`policy_config_digest`** `str`

---

```python
class nemo_gym.agents.context_management.history.GuardEvaluation(
    guard_name: str,
    measured_value: int,
    configured_limit: int,
    exceeded: bool,
    excess: int
)
```

Dataclass

**`configured_limit`** `int`

---

**`exceeded`** `bool`

---

**`excess`** `int`

---

**`guard_name`** `str`

---

**`measured_value`** `int`

---

```python
class nemo_gym.agents.context_management.history.GuardOutcomeRecord(
    rollout_id: str,
    chunk_id: str | None,
    applies_to_step: int,
    completed_action_count: int,
    pending_observation_group_ids: tuple[str, ...],
    guard_name: str,
    measured_value: int,
    configured_limit: int,
    early_chunk_close: bool,
    post_compaction_value: int | None,
    decision: typing.Literal['admit', 'admit_after_compaction', 'reject']
)
```

Dataclass

**`applies_to_step`** `int`

---

**`chunk_id`** `str | None`

---

**`completed_action_count`** `int`

---

**`configured_limit`** `int`

---

**`decision`** `Literal['admit', 'admit_after_compaction', 'reject']`

---

**`early_chunk_close`** `bool`

---

**`guard_name`** `str`

---

**`measured_value`** `int`

---

**`pending_observation_group_ids`** `tuple[str, ...]`

---

**`post_compaction_value`** `int | None`

---

**`rollout_id`** `str`

---

```python
class nemo_gym.agents.context_management.history.HistoryViewPlan(
    keep: tuple[nemo_gym.agents.context_management.history.KeepPartRef, ...],
    artifacts: tuple[nemo_gym.agents.context_management.history.OmissionArtifact, ...],
    decision: nemo_gym.agents.context_management.history.PolicyDecisionRecord
)
```

Dataclass

**`artifacts`** `tuple[OmissionArtifact, ...]`

---

**`decision`** `PolicyDecisionRecord`

---

**`keep`** `tuple[KeepPartRef, ...]`

---

**`retained_part_ids`** `frozenset[str]`

---

```python
class nemo_gym.agents.context_management.history.KeepPartRef(
    event_id: str,
    part_id: str
)
```

Dataclass

**`event_id`** `str`

---

**`part_id`** `str`

---

```python
class nemo_gym.agents.context_management.history.MaterializedHistoryView(
    items: tuple[typing.Mapping[str, typing.Any], ...],
    image_part_ids: tuple[str, ...],
    descriptor: tuple[str, ...],
    decision: nemo_gym.agents.context_management.history.PolicyDecisionRecord
)
```

Dataclass

**`decision`** `PolicyDecisionRecord`

---

**`descriptor`** `tuple[str, ...]`

---

**`image_part_ids`** `tuple[str, ...]`

---

**`items`** `tuple[Mapping[str, Any], ...]`

---

```python
class nemo_gym.agents.context_management.history.OmissionArtifact(
    artifact_id: str,
    source_first_part_id: str,
    source_last_part_id: str,
    source_part_count: int,
    source_digest: str,
    text: str,
    anchor_part_id: str
)
```

Dataclass

**`anchor_part_id`** `str`

---

**`artifact_id`** `str`

---

**`source_digest`** `str`

---

**`source_first_part_id`** `str`

---

**`source_last_part_id`** `str`

---

**`source_part_count`** `int`

---

**`text`** `str`

---

```python
class nemo_gym.agents.context_management.history.PolicyDecisionRecord(
    policy_name: str,
    policy_version: str,
    config_digest: str,
    protected_part_ids: tuple[str, ...],
    changed_part_ranges: tuple[tuple[str, str], ...],
    retained_part_count: int,
    omitted_part_count: int,
    selection_digest: str,
    inserted_artifact_ids: tuple[str, ...],
    decision_turn: int,
    lineage: nemo_gym.agents.context_management.history.TransformationLineageRecord
)
```

Dataclass

**`changed_part_ranges`** `tuple[tuple[str, str], ...]`

---

**`config_digest`** `str`

---

**`decision_turn`** `int`

---

**`inserted_artifact_ids`** `tuple[str, ...]`

---

**`lineage`** `TransformationLineageRecord`

---

**`omitted_part_count`** `int`

---

**`policy_name`** `str`

---

**`policy_version`** `str`

---

**`protected_part_ids`** `tuple[str, ...]`

---

**`retained_part_count`** `int`

---

**`selection_digest`** `str`

---

```python
class nemo_gym.agents.context_management.history.PreparedHistoryView(
    view: nemo_gym.agents.context_management.history.MaterializedHistoryView,
    view_digest: str,
    append_compatible: bool,
    boundary: nemo_gym.agents.context_management.history.RewriteBoundaryEvent | None,
    context_epoch: int
)
```

Dataclass

**`append_compatible`** `bool`

---

**`boundary`** `RewriteBoundaryEvent | None`

---

**`context_epoch`** `int`

---

**`view`** `MaterializedHistoryView`

---

**`view_digest`** `str`

---

```python
class nemo_gym.agents.context_management.history.RewriteBoundaryEvent(
    event_id: str,
    trigger_after_step: int,
    applies_to_step: int,
    reason: str,
    policy_name: str,
    policy_version: str,
    config_digest: str,
    previous_view_digest: str,
    current_view_digest: str,
    changed_part_ranges: tuple[tuple[str, str], ...],
    retained_part_count: int,
    omitted_part_count: int,
    retained_media_count: int,
    removed_media_count: int,
    inserted_artifact_ids: tuple[str, ...],
    schedule_name: str = 'per_action',
    schedule_version: str = '1',
    schedule_config_digest: str | None = None,
    chunk_id: str | None = None,
    block_index: int | None = None
)
```

Dataclass

**`applies_to_step`** `int`

---

**`block_index`** `int | None = None`

---

**`changed_part_ranges`** `tuple[tuple[str, str], ...]`

---

**`chunk_id`** `str | None = None`

---

**`config_digest`** `str`

---

**`current_view_digest`** `str`

---

**`event_id`** `str`

---

**`inserted_artifact_ids`** `tuple[str, ...]`

---

**`omitted_part_count`** `int`

---

**`policy_name`** `str`

---

**`policy_version`** `str`

---

**`previous_view_digest`** `str`

---

**`reason`** `str`

---

**`removed_media_count`** `int`

---

**`retained_media_count`** `int`

---

**`retained_part_count`** `int`

---

**`schedule_config_digest`** `str | None = None`

---

**`schedule_name`** `str = 'per_action'`

---

**`schedule_version`** `str = '1'`

---

**`trigger_after_step`** `int`

---

```python
class nemo_gym.agents.context_management.history.SemanticEvent(
    event_id: str,
    turn_id: int,
    role: str,
    item: typing.Mapping[str, typing.Any],
    parts: tuple[nemo_gym.agents.context_management.history.SemanticPart, ...],
    is_initial_context: bool = False,
    conditions_action_turn: int | None = None
)
```

Dataclass

**`conditions_action_turn`** `int | None = None`

---

**`event_id`** `str`

---

**`is_initial_context`** `bool = False`

---

**`item`** `Mapping[str, Any]`

---

**`parts`** `tuple[SemanticPart, ...]`

---

**`role`** `str`

---

**`turn_id`** `int`

---

```python
class nemo_gym.agents.context_management.history.SemanticHistory(
    rollout_id: str
)
```

Append-only semantic history used to derive model request views.

**`_events`** `list[SemanticEvent] = []`

---

**`_next_event`** `= 0`

---

**`events`** `tuple[SemanticEvent, ...]`

---

**`parts`** `tuple[tuple[SemanticEvent, SemanticPart], ...]`

---

```python
nemo_gym.agents.context_management.history.SemanticHistory.append_items(
    items: typing.Sequence[typing.Any] | str,
    turn_id: int,
    is_initial_context: bool = False,
    conditions_action_turn: int | None = None
) -> tuple[nemo_gym.agents.context_management.history.SemanticEvent, ...]
```

```python
class nemo_gym.agents.context_management.history.SemanticPart(
    part_id: str,
    kind: nemo_gym.agents.context_management.history.SemanticPartKind,
    content_index: int | None,
    digest: str,
    observation_group_id: str | None = None
)
```

Dataclass

**`content_index`** `int | None`

---

**`digest`** `str`

---

**`kind`** `SemanticPartKind`

---

**`observation_group_id`** `str | None = None`

---

**`part_id`** `str`

---

```python
class nemo_gym.agents.context_management.history.TransformationLineageRecord(
    transformation_id: str,
    transformation_type: str,
    transformation_version: str,
    configuration_digest: str,
    deterministic: bool,
    lossy: bool,
    generator_contract_id: str | None,
    unit_records: tuple[nemo_gym.agents.context_management.history.UnitLineageRecord, ...],
    validator_result: typing.Literal['passed']
)
```

Dataclass

**`configuration_digest`** `str`

---

**`deterministic`** `bool`

---

**`generator_contract_id`** `str | None`

---

**`lossy`** `bool`

---

**`transformation_id`** `str`

---

**`transformation_type`** `str`

---

**`transformation_version`** `str`

---

**`unit_records`** `tuple[UnitLineageRecord, ...]`

---

**`validator_result`** `Literal['passed']`

---

```python
class nemo_gym.agents.context_management.history.UnitLineageRecord(
    source_unit_id: str,
    source_digest: str,
    disposition: nemo_gym.agents.context_management.history.LineageDisposition,
    output_unit_ids: tuple[str, ...],
    output_digests: tuple[str, ...]
)
```

Dataclass

**`disposition`** `LineageDisposition`

---

**`output_digests`** `tuple[str, ...]`

---

**`output_unit_ids`** `tuple[str, ...]`

---

**`source_digest`** `str`

---

**`source_unit_id`** `str`

---

```python
nemo_gym.agents.context_management.history._as_item_dict(
    item: typing.Any
) -> dict[str, typing.Any]
```

```python
nemo_gym.agents.context_management.history._config_digest(
    value: typing.Mapping[str, typing.Any]
) -> str
```

```python
nemo_gym.agents.context_management.history._lineage_record(
    history: nemo_gym.agents.context_management.history.SemanticHistory,
    transformation_type: str,
    transformation_version: str,
    configuration_digest: str,
    disposition_by_part_id: typing.Mapping[str, tuple[nemo_gym.agents.context_management.history.LineageDisposition, tuple[str, ...], tuple[str, ...]]],
    lossy: bool
) -> nemo_gym.agents.context_management.history.TransformationLineageRecord
```

```python
nemo_gym.agents.context_management.history._ordered_id_digest(
    ids: typing.Sequence[str]
) -> str
```

```python
nemo_gym.agents.context_management.history._part_digest(
    kind: str,
    payload: typing.Any,
    observation_group_id: str | None
) -> str
```

```python
nemo_gym.agents.context_management.history._part_kind(
    role: str,
    item_type: str,
    part_type: str | None,
    initial: bool
) -> nemo_gym.agents.context_management.history.SemanticPartKind
```

```python
nemo_gym.agents.context_management.history._semantic_items_digest(
    items: typing.Sequence[typing.Mapping[str, typing.Any]]
) -> str
```

```python
nemo_gym.agents.context_management.history._semantic_part_digest(
    event: nemo_gym.agents.context_management.history.SemanticEvent,
    part: nemo_gym.agents.context_management.history.SemanticPart
) -> str
```

```python
nemo_gym.agents.context_management.history._view_digest(
    view: nemo_gym.agents.context_management.history.MaterializedHistoryView
) -> str
```

```python
nemo_gym.agents.context_management.history.canonical_digest(
    value: typing.Any
) -> str
```

```python
nemo_gym.agents.context_management.history.normalize_semantic_items(
    items: typing.Sequence[typing.Any]
) -> tuple[dict[str, typing.Any], ...]
```

Normalize a legacy request input for comparison with a semantic view.

```python
nemo_gym.agents.context_management.history.register_semantic_part_kind(
    kind: str
) -> None
```

```python
nemo_gym.agents.context_management.history.stable_id(
    prefix: str,
    parts: typing.Any = ()
) -> str
```

```python
nemo_gym.agents.context_management.history.strip_completion_evidence(
    item: typing.Any
) -> dict[str, typing.Any]
```

Return semantic API content with private token evidence removed.

```python
nemo_gym.agents.context_management.history.unregister_semantic_part_kind(
    kind: str
) -> None
```

```python
nemo_gym.agents.context_management.history.BUILTIN_SEMANTIC_PART_KINDS = frozenset({'system_text', 'task_text', 'policy_text', 'safety_text', 'user_text'...
```

```python
nemo_gym.agents.context_management.history.LineageDisposition = Literal['kept', 'dropped', 'replaced', 'summarized', 'transformed']
```

```python
nemo_gym.agents.context_management.history.SemanticPartKind = str
```

```python
nemo_gym.agents.context_management.history._IMAGE_PART_TYPES = frozenset({'image', 'image_url', 'input_image'})
```

```python
nemo_gym.agents.context_management.history._PRIVATE_ID_FIELDS = frozenset({'_nemo_gym_event_id', '_nemo_gym_part_id', '_nemo_gym_observation_gro...
```

```python
nemo_gym.agents.context_management.history._REGISTERED_SEMANTIC_PART_KINDS = set(BUILTIN_SEMANTIC_PART_KINDS)
```

```python
nemo_gym.agents.context_management.history._TOKEN_METADATA_FIELDS = frozenset({'prompt_token_ids', 'generation_token_ids', 'generation_log_probs', '...
```