cayu.memory.base

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

admit_recall

from cayu.memory import admit_recall

Apply deterministic bounded admission without provider-message coupling.

admit_recall(result: RecallResult, policy: AutomaticRecallPolicy) -> AutomaticRecallContribution

Release source · Runtime guarantees · Capability guides

Any

from cayu.memory import Any

This declared export reexports typing.Any. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

AUTOMATIC_RECALL_CONTRIBUTION_VERSION

from cayu.memory import AUTOMATIC_RECALL_CONTRIBUTION_VERSION

AUTOMATIC_RECALL_CONTRIBUTION_VERSION = 'cayu.automatic_recall_contribution.v1'

Release source · Runtime guarantees · Capability guides

AUTOMATIC_RECALL_POLICY_VERSION

from cayu.memory import AUTOMATIC_RECALL_POLICY_VERSION

AUTOMATIC_RECALL_POLICY_VERSION = 'cayu.automatic_recall_policy.v1'

Release source · Runtime guarantees · Capability guides

AutomaticRecallContribution

from cayu.memory import AutomaticRecallContribution

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.automatic_recall_contribution.v1']	AUTOMATIC_RECALL_CONTRIBUTION_VERSION
situation_sha256	str	required
policy_sha256	str	required
mode	AutomaticRecallMode	required
focus	MemoryFocus | None	None
offer	RecallOffer | None	None
sources	tuple[RecallSourceDiagnostic, ...]	required
continuations	Mapping[str, str]	Field(default_factory=dict)
diagnostics	AutomaticRecallDiagnostics	required

validate_digest (method)

AutomaticRecallContribution.validate_digest(value: str, info) -> str

copy_focus (method)

AutomaticRecallContribution.copy_focus(value) -> MemoryFocus | None

copy_offer (method)

AutomaticRecallContribution.copy_offer(value) -> RecallOffer | None

copy_sources (method)

AutomaticRecallContribution.copy_sources(value) -> tuple[RecallSourceDiagnostic, ...]

copy_continuations (method)

AutomaticRecallContribution.copy_continuations(value) -> dict[str, str]

freeze_continuations (method)

AutomaticRecallContribution.freeze_continuations(value: Mapping[str, str]) -> Mapping[str, str]

serialize_continuations (method)

AutomaticRecallContribution.serialize_continuations(value: Mapping[str, str]) -> dict[str, str]

copy_diagnostics (method)

AutomaticRecallContribution.copy_diagnostics(value) -> AutomaticRecallDiagnostics

validate_contribution (method)

AutomaticRecallContribution.validate_contribution() -> AutomaticRecallContribution

Release source · Runtime guarantees · Capability guides

AutomaticRecallContributor

from cayu.memory import AutomaticRecallContributor

Run bounded recall and apply one immutable admission policy.

init (method)

AutomaticRecallContributor.__init__(engine: RecallEngine, policy: AutomaticRecallPolicy) -> None

policy (property)

AutomaticRecallContributor.policy() -> AutomaticRecallPolicy

contribute (method)

async AutomaticRecallContributor.contribute(situation: RecallSituation) -> AutomaticRecallContribution

Release source · Runtime guarantees · Capability guides

AutomaticRecallDiagnostics

from cayu.memory import AutomaticRecallDiagnostics

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
candidate_decisions	tuple[RecallCandidateDecision, ...]	Field(default=(), max_length=100)
recall_performed	bool	required
recall_candidate_count	int	required
evaluated_candidate_count	int	required
strong_candidate_count	int	required
plausible_candidate_count	int	required
injected_count	int	required
offered_count	int	required
silent_count	int	required
duplicate_content_omitted	int	required
oversized_candidate_omitted	int	required
focus_bound_omitted	int	required
offer_bound_omitted	int	required
unevaluated_count	int	required
recall_truncated	bool	required
admission_truncated	bool	required

validate_bool (method)

AutomaticRecallDiagnostics.validate_bool(value, info) -> bool

validate_count (method)

AutomaticRecallDiagnostics.validate_count(value, info) -> int

Release source · Runtime guarantees · Capability guides

AutomaticRecallMode

from cayu.memory import AutomaticRecallMode

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
OFF	class attribute	'off'
OFFER	class attribute	'offer'
STRONG_MATCHES	class attribute	'strong_matches'
OFFER_AND_STRONG_MATCHES	class attribute	'offer_and_strong_matches'

injects_strong_matches (property)

AutomaticRecallMode.injects_strong_matches() -> bool

emits_offers (property)

AutomaticRecallMode.emits_offers() -> bool

Release source · Runtime guarantees · Capability guides

AutomaticRecallPolicy

from cayu.memory import AutomaticRecallPolicy

Versioned deterministic admission configuration for one fusion calibration.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
policy_version	Literal['cayu.automatic_recall_policy.v1']	AUTOMATIC_RECALL_POLICY_VERSION
calibration_version	str	required
fusion_strategy_version	str	required
fusion_configuration_version	str	required
relevance_policy	Literal['rank_only.v1', 'cayu.query_concepts.v1', 'cayu.query_concepts.v2', 'cayu.query_concepts.v3', 'cayu.query_concepts.v4', 'cayu.query_concepts.v5']	Field(default='rank_only.v1', exclude_if=lambda value: value == 'rank_only.v1')
relevance_text_version	str | None	Field(default=None, exclude_if=lambda value: value is None)
mode	AutomaticRecallMode	AutomaticRecallMode.OFFER_AND_STRONG_MATCHES
minimum_inject_score	float	required
minimum_offer_score	float	required
max_evaluated_candidates	int	30
max_injected_items	int	5
max_offered_items	int	10
max_candidate_text_bytes	int	16000
max_focus_bytes	int	64000
max_offer_bytes	int	16000
max_total_bytes	int	96000

validate_version_name (method)

AutomaticRecallPolicy.validate_version_name(value: str, info) -> str

validate_score (method)

AutomaticRecallPolicy.validate_score(value, info) -> float

validate_count_bound (method)

AutomaticRecallPolicy.validate_count_bound(value, info) -> int

validate_byte_bound (method)

AutomaticRecallPolicy.validate_byte_bound(value, info) -> int

validate_policy (method)

AutomaticRecallPolicy.validate_policy() -> AutomaticRecallPolicy

model_copy (method)

AutomaticRecallPolicy.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> Self

fingerprint (method)

AutomaticRecallPolicy.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

BaseModel

from cayu.memory import BaseModel

This declared export reexports pydantic.BaseModel. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

canonical_durable_json_bytes

from cayu.memory import canonical_durable_json_bytes

Return one backend-stable canonical encoding of a durable JSON value.

PostgreSQL JSONB preserves a JSON number’s value but may normalize its spelling and decoded Python type (for example, 1e18 can load as an int). Hashes and idempotency keys must therefore canonicalize numeric value semantics instead of hashing Python’s input spelling.

canonical_durable_json_bytes(value: Any, field_name: str, *, max_bytes: int | None=None, max_nodes: int | None=None) -> bytes

Release source · Runtime guarantees · Capability guides

ConfigDict

from cayu.memory import ConfigDict

This declared export reexports pydantic.ConfigDict. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

copy_durable_json_object

from cayu.memory import copy_durable_json_object

copy_durable_json_object(value: Any, field_name: str) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

Field

from cayu.memory import Field

This declared export reexports pydantic.Field. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

field_serializer

from cayu.memory import field_serializer

This declared export reexports pydantic.field_serializer. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

field_validator

from cayu.memory import field_validator

This declared export reexports pydantic.field_validator. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

FrozenJsonDict

from cayu.memory import FrozenJsonDict

An immutable JSON object with mapping-compatible reads.

Bases: Mapping[str, Any].

init (method)

FrozenJsonDict.__init__(values: Mapping[str, Any] | Iterable[tuple[str, Any]]=()) -> None

clear (method)

FrozenJsonDict.clear() -> None

pop (method)

FrozenJsonDict.pop(key: str, default: Any=None, /) -> Any

popitem (method)

FrozenJsonDict.popitem() -> tuple[str, Any]

setdefault (method)

FrozenJsonDict.setdefault(key: str, default: Any=None, /) -> Any

update (method)

FrozenJsonDict.update(*args: Any, **kwargs: Any) -> None

Release source · Runtime guarantees · Capability guides

FusedChannelMatch

from cayu.memory import FusedChannelMatch

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
channel	str	required
index_version	str	required
rank	int	required
representation	str	required
content_hash	str	required
explanations	tuple[str, ...]	required
raw_score	float | None	required

Release source · Runtime guarantees · Capability guides

Literal

from cayu.memory import Literal

This declared export reexports typing.Literal. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

Mapping

from cayu.memory import Mapping

This declared export reexports collections.abc.Mapping. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

MEMORY_DELTA_POLICY_VERSION

from cayu.memory import MEMORY_DELTA_POLICY_VERSION

MEMORY_DELTA_POLICY_VERSION = 'cayu.memory_delta_policy.v3'

Release source · Runtime guarantees · Capability guides

MEMORY_DELTA_REFRESH_OUTCOME_VERSION

from cayu.memory import MEMORY_DELTA_REFRESH_OUTCOME_VERSION

MEMORY_DELTA_REFRESH_OUTCOME_VERSION = 'cayu.memory_delta_refresh_outcome.v1'

Release source · Runtime guarantees · Capability guides

MEMORY_DELTA_TRIGGER_VERSION

from cayu.memory import MEMORY_DELTA_TRIGGER_VERSION

MEMORY_DELTA_TRIGGER_VERSION = 'cayu.memory_delta_trigger.v2'

Release source · Runtime guarantees · Capability guides

MEMORY_DELTA_VERSION

from cayu.memory import MEMORY_DELTA_VERSION

MEMORY_DELTA_VERSION = 'cayu.memory_delta.v2'

Release source · Runtime guarantees · Capability guides

MEMORY_FOCUS_VERSION

from cayu.memory import MEMORY_FOCUS_VERSION

MEMORY_FOCUS_VERSION = 'cayu.memory_focus.v1'

Release source · Runtime guarantees · Capability guides

MEMORY_REANCHOR_REFRESH_OUTCOME_VERSION

from cayu.memory import MEMORY_REANCHOR_REFRESH_OUTCOME_VERSION

MEMORY_REANCHOR_REFRESH_OUTCOME_VERSION = 'cayu.memory_reanchor_refresh_outcome.v1'

Release source · Runtime guarantees · Capability guides

MemoryDelta

from cayu.memory import MemoryDelta

One immutable append-only addition to a frozen interaction memory frame.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.memory_delta.v2']	MEMORY_DELTA_VERSION
interaction_id	str	required
sequence	int	required
base_receipt_id	str	required
base_situation_sha256	str	required
situation_sha256	str	required
policy_sha256	str	required
trigger	MemoryDeltaTrigger	required
receipt_id	str	required
items	tuple[MemoryDeltaItem, ...]	required
eligible_item_count	int	required
omitted_item_count	int	required
recall_truncated	bool	required
truncated	bool	required

validate_identity (method)

MemoryDelta.validate_identity(value: str, info: Any) -> str

validate_delta_sequence (method)

MemoryDelta.validate_delta_sequence(value: Any) -> int

validate_digest (method)

MemoryDelta.validate_digest(value: str, info: Any) -> str

copy_trigger (method)

MemoryDelta.copy_trigger(value: Any) -> MemoryDeltaTrigger

copy_items (method)

MemoryDelta.copy_items(value: Any) -> tuple[MemoryDeltaItem, ...]

validate_count (method)

MemoryDelta.validate_count(value: Any, info: Any) -> int

validate_bool (method)

MemoryDelta.validate_bool(value: Any, info: Any) -> bool

validate_delta (method)

MemoryDelta.validate_delta() -> MemoryDelta

Release source · Runtime guarantees · Capability guides

MemoryDeltaItem

from cayu.memory import MemoryDeltaItem

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
candidate	RecallCandidate	required
fused_rank	int	required
selection_reason	MemoryDeltaSelectionReason	MemoryDeltaSelectionReason.NEWLY_RELEVANT
prior_exposure_id	str | None	None

copy_candidate (method)

MemoryDeltaItem.copy_candidate(value: Any) -> RecallCandidate

validate_rank (method)

MemoryDeltaItem.validate_rank(value: Any) -> int

validate_prior_exposure_id (method)

MemoryDeltaItem.validate_prior_exposure_id(value: str | None) -> str | None

validate_selection_evidence (method)

MemoryDeltaItem.validate_selection_evidence() -> MemoryDeltaItem

Release source · Runtime guarantees · Capability guides

MemoryDeltaPolicy

from cayu.memory import MemoryDeltaPolicy

Deterministic work and projection bounds for intra-interaction refresh.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
policy_version	Literal['cayu.memory_delta_policy.v3']	MEMORY_DELTA_POLICY_VERSION
refresh_on_knowledge_change	bool	True
max_refreshes_per_interaction	int	8
max_deltas_per_interaction	int	4
max_items_per_delta	int	3
max_cumulative_items	int	64
max_delta_bytes	int	32000
max_cumulative_bytes	int	128000
max_delta_estimated_tokens	int	8000
max_cumulative_estimated_tokens	int	32000
change_page_limit	int	32
readiness_page_limit	int	32
reanchor_on_projection_loss	bool	False
reanchor_relevance_policy	Literal['cayu.query_concepts.v2', 'cayu.query_concepts.v3', 'cayu.query_concepts.v4', 'cayu.query_concepts.v5']	'cayu.query_concepts.v2'
max_reanchor_refreshes_per_interaction	int	4
max_reanchors_per_item	int	2
max_items_per_reanchor	int	3
max_reanchor_bytes	int	32000
max_reanchor_estimated_tokens	int	8000
min_reanchor_boundary_distance	int	1
max_context_exposures_inspected	int	32
max_context_exposure_bytes	int	1000000

validate_refresh_enabled (method)

MemoryDeltaPolicy.validate_refresh_enabled(value: Any, info: Any) -> bool

validate_count_bound (method)

MemoryDeltaPolicy.validate_count_bound(value: Any, info: Any) -> int

validate_byte_bound (method)

MemoryDeltaPolicy.validate_byte_bound(value: Any, info: Any) -> int

validate_estimated_token_bound (method)

MemoryDeltaPolicy.validate_estimated_token_bound(value: Any, info: Any) -> int

validate_context_exposure_bytes (method)

MemoryDeltaPolicy.validate_context_exposure_bytes(value: Any) -> int

validate_policy (method)

MemoryDeltaPolicy.validate_policy() -> MemoryDeltaPolicy

model_copy (method)

MemoryDeltaPolicy.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> Self

fingerprint (method)

MemoryDeltaPolicy.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

MemoryDeltaRefreshDisposition

from cayu.memory import MemoryDeltaRefreshDisposition

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
FRONTIER_UNCHANGED	class attribute	'frontier_unchanged'
NO_CURRENT_REVISION	class attribute	'no_current_revision'
RECALL_INCOMPLETE	class attribute	'recall_incomplete'
NO_NEWLY_RELEVANT_ITEMS	class attribute	'no_newly_relevant_items'
ITEM_BUDGET_EXHAUSTED	class attribute	'item_budget_exhausted'
BYTE_BUDGET_EXHAUSTED	class attribute	'byte_budget_exhausted'
TOKEN_BUDGET_EXHAUSTED	class attribute	'token_budget_exhausted'
DELTA_APPENDED	class attribute	'delta_appended'

Release source · Runtime guarantees · Capability guides

MemoryDeltaRefreshOutcome

from cayu.memory import MemoryDeltaRefreshOutcome

One bounded durable result from inspecting a safe refresh boundary.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.memory_delta_refresh_outcome.v1']	MEMORY_DELTA_REFRESH_OUTCOME_VERSION
interaction_id	str	required
ordinal	int	required
model_step_id	str	required
disposition	MemoryDeltaRefreshDisposition	required
previous_knowledge_sequence	int	required
observed_knowledge_sequence	int	required
previous_index_readiness_sequence	int	required
observed_index_readiness_sequence	int	required
eligible_item_count	int	0
selected_item_count	int	0
omitted_item_count	int	0
recall_truncated	bool	False
delta_sequence	int | None	None

validate_interaction_id (method)

MemoryDeltaRefreshOutcome.validate_interaction_id(value: str) -> str

validate_model_step_id (method)

MemoryDeltaRefreshOutcome.validate_model_step_id(value: str) -> str

validate_ordinal (method)

MemoryDeltaRefreshOutcome.validate_ordinal(value: Any) -> int

validate_frontier_sequence (method)

MemoryDeltaRefreshOutcome.validate_frontier_sequence(value: Any, info: Any) -> int

validate_item_count (method)

MemoryDeltaRefreshOutcome.validate_item_count(value: Any, info: Any) -> int

validate_recall_truncated (method)

MemoryDeltaRefreshOutcome.validate_recall_truncated(value: Any) -> bool

validate_optional_delta_sequence (method)

MemoryDeltaRefreshOutcome.validate_optional_delta_sequence(value: Any) -> int | None

validate_outcome (method)

MemoryDeltaRefreshOutcome.validate_outcome() -> MemoryDeltaRefreshOutcome

Release source · Runtime guarantees · Capability guides

MemoryDeltaSelectionReason

from cayu.memory import MemoryDeltaSelectionReason

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
NEWLY_RELEVANT	class attribute	'newly_relevant'
REANCHORED_CURRENT_REVISION	class attribute	'reanchored_current_revision'

Release source · Runtime guarantees · Capability guides

MemoryDeltaTrigger

from cayu.memory import MemoryDeltaTrigger

Exact durable reason for evaluating memory at one safe model boundary.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.memory_delta_trigger.v2']	MEMORY_DELTA_TRIGGER_VERSION
kind	MemoryDeltaTriggerKind	MemoryDeltaTriggerKind.KNOWLEDGE_FRONTIER_ADVANCED
model_step_id	str	required
previous_knowledge_sequence	int | None	None
knowledge_sequence	int | None	None
previous_index_readiness_sequence	int | None	None
index_readiness_sequence	int | None	None
prior_exposure_ids	tuple[str, ...]	()
minimum_boundary_distance	int | None	None
removed_manifest_sha256s	tuple[str, ...]	()
context_anchor_sha256	str | None	None

validate_model_step_id (method)

MemoryDeltaTrigger.validate_model_step_id(value: str) -> str

validate_sequence (method)

MemoryDeltaTrigger.validate_sequence(value: Any, info: Any) -> int | None

validate_prior_exposure_ids (method)

MemoryDeltaTrigger.validate_prior_exposure_ids(value: Any) -> tuple[str, ...]

validate_removed_manifest_sha256s (method)

MemoryDeltaTrigger.validate_removed_manifest_sha256s(value: Any) -> tuple[str, ...]

validate_context_anchor_sha256 (method)

MemoryDeltaTrigger.validate_context_anchor_sha256(value: str | None) -> str | None

validate_minimum_boundary_distance (method)

MemoryDeltaTrigger.validate_minimum_boundary_distance(value: Any) -> int | None

validate_trigger (method)

MemoryDeltaTrigger.validate_trigger() -> MemoryDeltaTrigger

fingerprint (method)

MemoryDeltaTrigger.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

MemoryDeltaTriggerKind

from cayu.memory import MemoryDeltaTriggerKind

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
KNOWLEDGE_FRONTIER_ADVANCED	class attribute	'knowledge_frontier_advanced'
PROJECTION_REMOVED_BY_CONTEXT_POLICY	class attribute	'projection_removed_by_context_policy'

Release source · Runtime guarantees · Capability guides

MemoryFocus

from cayu.memory import MemoryFocus

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.memory_focus.v1']	MEMORY_FOCUS_VERSION
situation_sha256	str	required
policy_sha256	str	required
calibration_version	str	required
items	tuple[MemoryFocusItem, ...]	required
sources	tuple[RecallSourceDiagnostic, ...]	required
continuations	Mapping[str, str]	Field(default_factory=dict)
eligible_item_count	int	required
omitted_item_count	int	required
recall_truncated	bool	required
truncated	bool	required

validate_digest (method)

MemoryFocus.validate_digest(value: str, info) -> str

validate_calibration_version (method)

MemoryFocus.validate_calibration_version(value: str) -> str

copy_items (method)

MemoryFocus.copy_items(value) -> tuple[MemoryFocusItem, ...]

copy_sources (method)

MemoryFocus.copy_sources(value) -> tuple[RecallSourceDiagnostic, ...]

copy_continuations (method)

MemoryFocus.copy_continuations(value) -> dict[str, str]

freeze_continuations (method)

MemoryFocus.freeze_continuations(value: Mapping[str, str]) -> Mapping[str, str]

serialize_continuations (method)

MemoryFocus.serialize_continuations(value: Mapping[str, str]) -> dict[str, str]

validate_count (method)

MemoryFocus.validate_count(value, info) -> int

validate_bool (method)

MemoryFocus.validate_bool(value, info) -> bool

validate_focus (method)

MemoryFocus.validate_focus() -> MemoryFocus

Release source · Runtime guarantees · Capability guides

MemoryFocusItem

from cayu.memory import MemoryFocusItem

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
candidate	RecallCandidate	required
fused_rank	int	required
selection_reason	Literal['calibrated_strong_match']	'calibrated_strong_match'

copy_candidate (method)

MemoryFocusItem.copy_candidate(value) -> RecallCandidate

validate_rank (method)

MemoryFocusItem.validate_rank(value) -> int

Release source · Runtime guarantees · Capability guides

MemoryReanchorRefreshDisposition

from cayu.memory import MemoryReanchorRefreshDisposition

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
NO_CONTEXT_ANCHOR	class attribute	'no_context_anchor'
EXPOSURE_HISTORY_INCOMPLETE	class attribute	'exposure_history_incomplete'
NO_ACKNOWLEDGED_EXPOSURE	class attribute	'no_acknowledged_exposure'
BOUNDARY_COOLDOWN	class attribute	'boundary_cooldown'
REPEAT_BUDGET_EXHAUSTED	class attribute	'repeat_budget_exhausted'
RECALL_INCOMPLETE	class attribute	'recall_incomplete'
NO_CURRENT_RELEVANT_ITEM	class attribute	'no_current_relevant_item'
DELTA_BUDGET_EXHAUSTED	class attribute	'delta_budget_exhausted'
ITEM_BUDGET_EXHAUSTED	class attribute	'item_budget_exhausted'
BYTE_BUDGET_EXHAUSTED	class attribute	'byte_budget_exhausted'
TOKEN_BUDGET_EXHAUSTED	class attribute	'token_budget_exhausted'
DELTA_APPENDED	class attribute	'delta_appended'

Release source · Runtime guarantees · Capability guides

MemoryReanchorRefreshOutcome

from cayu.memory import MemoryReanchorRefreshOutcome

One bounded result from evaluating deterministic projection restoration.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.memory_reanchor_refresh_outcome.v1']	MEMORY_REANCHOR_REFRESH_OUTCOME_VERSION
interaction_id	str	required
ordinal	int	required
model_step_id	str	required
disposition	MemoryReanchorRefreshDisposition	required
exposure_count_inspected	int	0
eligible_item_count	int	0
selected_item_count	int	0
omitted_item_count	int	0
recall_truncated	bool	False
delta_sequence	int | None	None

validate_interaction_id (method)

MemoryReanchorRefreshOutcome.validate_interaction_id(value: str) -> str

validate_model_step_id (method)

MemoryReanchorRefreshOutcome.validate_model_step_id(value: str) -> str

validate_ordinal (method)

MemoryReanchorRefreshOutcome.validate_ordinal(value: Any) -> int

validate_count (method)

MemoryReanchorRefreshOutcome.validate_count(value: Any, info: Any) -> int

validate_recall_truncated (method)

MemoryReanchorRefreshOutcome.validate_recall_truncated(value: Any) -> bool

validate_optional_delta_sequence (method)

MemoryReanchorRefreshOutcome.validate_optional_delta_sequence(value: Any) -> int | None

validate_outcome (method)

MemoryReanchorRefreshOutcome.validate_outcome() -> MemoryReanchorRefreshOutcome

Release source · Runtime guarantees · Capability guides

model_validator

from cayu.memory import model_validator

This declared export reexports pydantic.model_validator. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

query_concept_eligibility

from cayu.memory import query_concept_eligibility

At most 8,192 query bytes / 128,000 text bytes; no channel confidence.

query_concept_eligibility(query: str | None, text: str, *, version: str=RELEVANCE_VERSION, title: str | None=None) -> tuple[str, str]

Release source · Runtime guarantees · Capability guides

RECALL_OFFER_VERSION

from cayu.memory import RECALL_OFFER_VERSION

RECALL_OFFER_VERSION = 'cayu.recall_offer.v1'

Release source · Runtime guarantees · Capability guides

RecallCandidate

from cayu.memory import RecallCandidate

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
fused	FusedRetrievalCandidate	required
record	RecallRecord	required

copy_fused (method)

RecallCandidate.copy_fused(value) -> FusedRetrievalCandidate

copy_record (method)

RecallCandidate.copy_record(value) -> RecallRecord

validate_identity (method)

RecallCandidate.validate_identity() -> RecallCandidate

Release source · Runtime guarantees · Capability guides

RecallCandidateDecision

from cayu.memory import RecallCandidateDecision

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
identity	RetrievalCandidateIdentity	required
eligibility	Literal['eligible', 'low_relevance', 'insufficient_evidence', 'legacy_rank_only']	required
reason	Literal['query_concept_support', 'query_phrase_support', 'weak_query_support', 'missing_query_evidence', 'rank_only_calibration']	required
outcome	Literal['focused', 'offered', 'low_relevance', 'insufficient_evidence', 'below_score', 'oversized', 'duplicate', 'capacity', 'mode', 'unevaluated']	required

Release source · Runtime guarantees · Capability guides

RecallEngine

from cayu.memory import RecallEngine

Run bounded sources concurrently and fuse their recorded ranks deterministically.

init (method)

RecallEngine.__init__(sources: Sequence[RecallSource], *, fusion_config: WeightedReciprocalRankFusionConfig, config: RecallEngineConfig | None=None) -> None

recall (method)

async RecallEngine.recall(situation: RecallSituation) -> RecallResult

Release source · Runtime guarantees · Capability guides

RecallOffer

from cayu.memory import RecallOffer

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal['cayu.recall_offer.v1']	RECALL_OFFER_VERSION
ticket	str	required
situation_sha256	str	required
policy_sha256	str	required
calibration_version	str	required
items	tuple[RecallOfferItem, ...]	required
continuations	Mapping[str, str]	Field(default_factory=dict)
eligible_item_count	int	required
omitted_item_count	int	required
recall_truncated	bool	required
truncated	bool	required

validate_digest (method)

RecallOffer.validate_digest(value: str, info) -> str

validate_calibration_version (method)

RecallOffer.validate_calibration_version(value: str) -> str

copy_items (method)

RecallOffer.copy_items(value) -> tuple[RecallOfferItem, ...]

copy_continuations (method)

RecallOffer.copy_continuations(value) -> dict[str, str]

freeze_continuations (method)

RecallOffer.freeze_continuations(value: Mapping[str, str]) -> Mapping[str, str]

serialize_continuations (method)

RecallOffer.serialize_continuations(value: Mapping[str, str]) -> dict[str, str]

validate_count (method)

RecallOffer.validate_count(value, info) -> int

validate_bool (method)

RecallOffer.validate_bool(value, info) -> bool

validate_offer (method)

RecallOffer.validate_offer() -> RecallOffer

Release source · Runtime guarantees · Capability guides

RecallOfferItem

from cayu.memory import RecallOfferItem

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
identity	RetrievalCandidateIdentity	required
representation	str	required
content_hash	str	required
locator	Mapping[str, Any]	required
fused_rank	int	required
score	float	required
matches	tuple[FusedChannelMatch, ...]	required
reason	_RecallOfferReason	required
preview	str | None	None
preview_complete	bool	False

validate_preview (method)

RecallOfferItem.validate_preview(value: str | None) -> str | None

validate_preview_complete (method)

RecallOfferItem.validate_preview_complete(value) -> bool

copy_identity (method)

RecallOfferItem.copy_identity(value) -> RetrievalCandidateIdentity

validate_representation (method)

RecallOfferItem.validate_representation(value: str) -> str

validate_content_hash (method)

RecallOfferItem.validate_content_hash(value: str) -> str

copy_locator (method)

RecallOfferItem.copy_locator(value) -> dict[str, Any]

freeze_locator (method)

RecallOfferItem.freeze_locator(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_locator (method)

RecallOfferItem.serialize_locator(value: Mapping[str, Any]) -> dict[str, Any]

validate_rank (method)

RecallOfferItem.validate_rank(value) -> int

validate_score (method)

RecallOfferItem.validate_score(value) -> float

copy_matches (method)

RecallOfferItem.copy_matches(value) -> tuple[FusedChannelMatch, ...]

validate_match_evidence (method)

RecallOfferItem.validate_match_evidence() -> RecallOfferItem

Release source · Runtime guarantees · Capability guides

RecallResult

from cayu.memory import RecallResult

Cross-source retrieval output; not admission, context, or exposure evidence.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
engine_version	str	required
situation_sha256	str	required
candidates	tuple[RecallCandidate, ...]	required
fusion	RetrievalFusionDiagnostics	required
sources	tuple[RecallSourceDiagnostic, ...]	required
continuations	Mapping[str, str]	Field(default_factory=dict)
truncated	bool	required
relevance_query	str | None	Field(default=None, max_length=RECALL_MAX_QUERY_BYTES)
omitted_by_result_bytes	int	0

validate_relevance_query (method)

RecallResult.validate_relevance_query(value: str | None) -> str | None

validate_engine_version (method)

RecallResult.validate_engine_version(value: str) -> str

validate_situation_hash (method)

RecallResult.validate_situation_hash(value: str) -> str

copy_candidates (method)

RecallResult.copy_candidates(value) -> tuple[RecallCandidate, ...]

copy_fusion (method)

RecallResult.copy_fusion(value) -> RetrievalFusionDiagnostics

copy_sources (method)

RecallResult.copy_sources(value) -> tuple[RecallSourceDiagnostic, ...]

copy_continuations (method)

RecallResult.copy_continuations(value) -> dict[str, str]

freeze_continuations (method)

RecallResult.freeze_continuations(value: Mapping[str, str]) -> Mapping[str, str]

serialize_continuations (method)

RecallResult.serialize_continuations(value: Mapping[str, str]) -> dict[str, str]

validate_truncated (method)

RecallResult.validate_truncated(value) -> bool

validate_omitted (method)

RecallResult.validate_omitted(value) -> int

validate_result (method)

RecallResult.validate_result() -> RecallResult

Release source · Runtime guarantees · Capability guides

RecallSituation

from cayu.memory import RecallSituation

Immutable per-boundary retrieval input; never provider-visible by itself.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
query_resolution_version	Literal['cayu.query_resolution.v2']	QUERY_RESOLUTION_VERSION
query	str	required
recent_conversation	tuple[str, ...]	()
recent_user_context_clipped	bool	False
current_query_clipped	bool	False
work_context	str | None	None
knowledge_access_scope	KnowledgeAccessScope | None	None
knowledge_namespace	str	DEFAULT_KNOWLEDGE_NAMESPACE
transcript_session_ids	tuple[str, ...]	()
transcript_before_indexes	Mapping[str, int]	Field(default_factory=dict)
continuations	Mapping[str, str]	Field(default_factory=dict)
knowledge_aspect_groups	tuple[tuple[str, ...], ...]	()
knowledge_filter_only	bool	False
current_time	datetime	Field(default_factory=lambda: datetime.now(UTC))

validate_resolution_clipping (method)

RecallSituation.validate_resolution_clipping(value, info) -> bool

validate_query (method)

RecallSituation.validate_query(value: str) -> str

validate_recent_conversation (method)

RecallSituation.validate_recent_conversation(value) -> tuple[str, ...]

validate_work_context (method)

RecallSituation.validate_work_context(value: str | None) -> str | None

validate_knowledge_aspect_groups (method)

RecallSituation.validate_knowledge_aspect_groups(value: object) -> tuple[tuple[str, ...], ...]

validate_knowledge_filter_only (method)

RecallSituation.validate_knowledge_filter_only(value: object) -> bool

validate_knowledge_filter (method)

RecallSituation.validate_knowledge_filter() -> RecallSituation

copy_access_scope (method)

RecallSituation.copy_access_scope(value) -> KnowledgeAccessScope | None

freeze_access_scope (method)

RecallSituation.freeze_access_scope(value: KnowledgeAccessScope | None) -> KnowledgeAccessScope | None

copy_transcript_before_indexes (method)

RecallSituation.copy_transcript_before_indexes(value) -> dict[str, int]

freeze_transcript_before_indexes (method)

RecallSituation.freeze_transcript_before_indexes(value: Mapping[str, int]) -> Mapping[str, int]

serialize_transcript_before_indexes (method)

RecallSituation.serialize_transcript_before_indexes(value: Mapping[str, int]) -> dict[str, int]

serialize_access_scope (method)

RecallSituation.serialize_access_scope(value: KnowledgeAccessScope | None) -> dict[str, Any] | None

validate_namespace (method)

RecallSituation.validate_namespace(value: str) -> str

validate_transcript_session_ids (method)

RecallSituation.validate_transcript_session_ids(value) -> tuple[str, ...]

copy_continuations (method)

RecallSituation.copy_continuations(value) -> dict[str, str]

freeze_continuations (method)

RecallSituation.freeze_continuations(value: Mapping[str, str]) -> Mapping[str, str]

serialize_continuations (method)

RecallSituation.serialize_continuations(value: Mapping[str, str]) -> dict[str, str]

validate_current_time (method)

RecallSituation.validate_current_time(value: datetime) -> datetime

validate_transcript_before_index_scope (method)

RecallSituation.validate_transcript_before_index_scope() -> RecallSituation

query_resolution (method)

RecallSituation.query_resolution() -> dict[str, Any]

Bounded evidence of whether a current question needs an antecedent.

Only the most recent caller-supplied user turn (or explicit work context) may resolve a follow-up. Assistant prose never supplies search terms. Unknown discourse forms conservatively remain current-query-only.

retrieval_text (method)

RecallSituation.retrieval_text() -> str

fingerprint (method)

RecallSituation.fingerprint() -> str

model_copy (method)

RecallSituation.model_copy(*, update: Mapping[str, Any] | None=None, deep: bool=False) -> Self

Release source · Runtime guarantees · Capability guides

RecallSourceDiagnostic

from cayu.memory import RecallSourceDiagnostic

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
source	str	required
required	bool	required
status	RecallSourceStatus	required
channels	tuple[str, ...]	required
failure_code	str | None	None

validate_source (method)

RecallSourceDiagnostic.validate_source(value: str) -> str

validate_required (method)

RecallSourceDiagnostic.validate_required(value) -> bool

validate_channels (method)

RecallSourceDiagnostic.validate_channels(value) -> tuple[str, ...]

validate_failure_code (method)

RecallSourceDiagnostic.validate_failure_code(value: str | None) -> str | None

validate_status (method)

RecallSourceDiagnostic.validate_status() -> RecallSourceDiagnostic

Release source · Runtime guarantees · Capability guides

RELEVANCE_TEXT_VERSION

from cayu.memory import RELEVANCE_TEXT_VERSION

RELEVANCE_TEXT_VERSION = f'{RELEVANCE_VERSION}+unicode-{unicodedata.unidata_version}'

Release source · Runtime guarantees · Capability guides

require_clean_nonblank

from cayu.memory import require_clean_nonblank

Return portable durable text without surrounding whitespace.

require_clean_nonblank(value: str, field_name: str) -> str

Release source · Runtime guarantees · Capability guides

require_execution_unit_id

from cayu.memory import require_execution_unit_id

Return one canonical, portable Cayu execution-unit identifier.

require_execution_unit_id(value: str, field_name: str) -> str

Release source · Runtime guarantees · Capability guides

require_finite

from cayu.memory import require_finite

require_finite(value: float, field_name: str) -> float

Release source · Runtime guarantees · Capability guides

RetrievalCandidateIdentity

from cayu.memory import RetrievalCandidateIdentity

Exact typed canonical revision identity shared by retrieval channels.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
record_type	str	required
record_id	str	required
revision	str	required

validate_identity (method)

RetrievalCandidateIdentity.validate_identity(value: str, info) -> str

sort_key (method)

RetrievalCandidateIdentity.sort_key() -> tuple[str, str, str]

Release source · Runtime guarantees · Capability guides

Self

from cayu.memory import Self

This declared export reexports typing.Self. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

Sequence

from cayu.memory import Sequence

This declared export reexports collections.abc.Sequence. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

sha256

from cayu.memory import sha256

This declared export reexports hashlib.sha256. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

StrEnum

from cayu.memory import StrEnum

This declared export reexports enum.StrEnum. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference

TITLE_RELEVANCE_TEXT_VERSION

from cayu.memory import TITLE_RELEVANCE_TEXT_VERSION

TITLE_RELEVANCE_TEXT_VERSION = f'{TITLE_RELEVANCE_VERSION}+unicode-{unicodedata.unidata_version}'

Release source · Runtime guarantees · Capability guides

TypeAlias

from cayu.memory import TypeAlias

This declared export reexports typing.TypeAlias. Its behavior belongs to the upstream dependency, rather than a Cayu implementation.

Release declaration · Upstream reference