cayu.memory.retrieval

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.

FusedChannelMatch

from cayu 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

FusedRetrievalCandidate

from cayu.memory import FusedRetrievalCandidate

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
score	float	required
reciprocal_rank_score	float	required
feature_adjustment	float	required
features	Mapping[str, float]	required
best_rank	int	required
channel_count	int	required
matches	tuple[FusedChannelMatch, ...]	required

validate_features (method)

FusedRetrievalCandidate.validate_features(value) -> dict[str, float]

freeze_features (method)

FusedRetrievalCandidate.freeze_features(value: Mapping[str, float]) -> Mapping[str, float]

serialize_features (method)

FusedRetrievalCandidate.serialize_features(value: Mapping[str, float]) -> dict[str, float]

Release source · Runtime guarantees · Capability guides

RankedRetrievalChannel

from cayu.memory import RankedRetrievalChannel

Bounded, independently ranked output from one retrieval channel.

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
candidate_limit	int	required
hits	tuple[RankedRetrievalHit, ...]	()
truncated	bool	False
continuation	str | None	None

validate_identity_fields (method)

RankedRetrievalChannel.validate_identity_fields(value: str, info) -> str

validate_candidate_limit (method)

RankedRetrievalChannel.validate_candidate_limit(value) -> int

validate_truncated (method)

RankedRetrievalChannel.validate_truncated(value) -> bool

validate_continuation (method)

RankedRetrievalChannel.validate_continuation(value: str | None) -> str | None

validate_bounded_ranking (method)

RankedRetrievalChannel.validate_bounded_ranking() -> RankedRetrievalChannel

Release source · Runtime guarantees · Capability guides

RankedRetrievalHit

from cayu.memory import RankedRetrievalHit

One bounded channel hit; raw scores are diagnostic and never fused.

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
rank	int	required
representation	str	required
content_hash	str	required
explanations	tuple[str, ...]	()
raw_score	float | None	None
features	Mapping[str, float]	Field(default_factory=dict)
continuation	str | None	None

validate_rank (method)

RankedRetrievalHit.validate_rank(value) -> int

validate_identity_fields (method)

RankedRetrievalHit.validate_identity_fields(value: str, info) -> str

validate_explanations (method)

RankedRetrievalHit.validate_explanations(value) -> tuple[str, ...]

validate_raw_score (method)

RankedRetrievalHit.validate_raw_score(value) -> float | None

validate_features (method)

RankedRetrievalHit.validate_features(value) -> dict[str, float]

freeze_features (method)

RankedRetrievalHit.freeze_features(value: Mapping[str, float]) -> Mapping[str, float]

serialize_features (method)

RankedRetrievalHit.serialize_features(value: Mapping[str, float]) -> dict[str, float]

validate_continuation (method)

RankedRetrievalHit.validate_continuation(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

RetrievalCandidateIdentity

from cayu 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

RetrievalChannelDiagnostics

from cayu.memory import RetrievalChannelDiagnostics

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
candidate_limit	int	required
hit_count	int	required
unique_candidate_count	int	required
truncated	bool	required
continuation_available	bool	required

Release source · Runtime guarantees · Capability guides

RetrievalFusionDiagnostics

from cayu.memory import RetrievalFusionDiagnostics

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
strategy_version	str	required
configuration_version	str	required
configuration_sha256	str	required
channels	tuple[RetrievalChannelDiagnostics, ...]	required
unique_candidate_count	int	required
returned_candidate_count	int	required
omitted_candidate_count	int	required
truncated	bool	required
truncation_reasons	tuple[str, ...]	required
continuation_channels	tuple[str, ...]	required

Release source · Runtime guarantees · Capability guides

RetrievalFusionResult

from cayu.memory import RetrievalFusionResult

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
candidates	tuple[FusedRetrievalCandidate, ...]	required
diagnostics	RetrievalFusionDiagnostics	required

Release source · Runtime guarantees · Capability guides

WEIGHTED_RECIPROCAL_RANK_FUSION_VERSION

from cayu.memory import WEIGHTED_RECIPROCAL_RANK_FUSION_VERSION

WEIGHTED_RECIPROCAL_RANK_FUSION_VERSION = 'cayu.wrrf.v1'

Release source · Runtime guarantees · Capability guides

WeightedReciprocalRankFusion

from cayu.memory import WeightedReciprocalRankFusion

Deterministic weighted reciprocal-rank fusion reference strategy.

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
strategy_version	class attribute	WEIGHTED_RECIPROCAL_RANK_FUSION_VERSION

fuse (method)

WeightedReciprocalRankFusion.fuse(channels: tuple[RankedRetrievalChannel, ...], config: WeightedReciprocalRankFusionConfig) -> RetrievalFusionResult

Release source · Runtime guarantees · Capability guides

WeightedReciprocalRankFusionConfig

from cayu.memory import WeightedReciprocalRankFusionConfig

Versioned, evaluation-owned WRRF weights and hard work budgets.

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
configuration_version	str	required
channel_weights	Mapping[str, float]	required
rrf_k	float	60.0
feature_weights	Mapping[str, float]	Field(default_factory=dict)
max_candidates_per_channel	int	100
fused_head_limit	int	50
strategy_version	str	WEIGHTED_RECIPROCAL_RANK_FUSION_VERSION

validate_versions (method)

WeightedReciprocalRankFusionConfig.validate_versions(value: str, info) -> str

validate_channel_weights (method)

WeightedReciprocalRankFusionConfig.validate_channel_weights(value) -> dict[str, float]

validate_feature_weights (method)

WeightedReciprocalRankFusionConfig.validate_feature_weights(value) -> dict[str, float]

freeze_weight_maps (method)

WeightedReciprocalRankFusionConfig.freeze_weight_maps(value: Mapping[str, float]) -> Mapping[str, float]

serialize_weight_maps (method)

WeightedReciprocalRankFusionConfig.serialize_weight_maps(value: Mapping[str, float]) -> dict[str, float]

validate_rrf_k (method)

WeightedReciprocalRankFusionConfig.validate_rrf_k(value) -> float

validate_limits (method)

WeightedReciprocalRankFusionConfig.validate_limits(value, info) -> int

validate_enabled_channels (method)

WeightedReciprocalRankFusionConfig.validate_enabled_channels() -> WeightedReciprocalRankFusionConfig

model_copy (method)

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

Return an independently validated immutable configuration.

fingerprint (method)

WeightedReciprocalRankFusionConfig.fingerprint() -> str

Release source · Runtime guarantees · Capability guides