cayu.memory.recall

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.

KNOWLEDGE_LEXICAL_CHANNEL

from cayu.memory import KNOWLEDGE_LEXICAL_CHANNEL

KNOWLEDGE_LEXICAL_CHANNEL = 'knowledge.lexical'

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_SEMANTIC_CHANNEL

from cayu.memory import KNOWLEDGE_SEMANTIC_CHANNEL

KNOWLEDGE_SEMANTIC_CHANNEL = 'knowledge.semantic'

Release source · Runtime guarantees · Capability guides

KnowledgeFrontierRecallSource

from cayu.memory import KnowledgeFrontierRecallSource

Knowledge recall lane restricted to one captured processing frontier.

Bases: KnowledgeRecallSource.

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
name	class attribute	'knowledge'
channel_names	class attribute	(KNOWLEDGE_LEXICAL_CHANNEL, KNOWLEDGE_SEMANTIC_CHANNEL)
continuation_channels	tuple[str, ...]	()

init (method)

KnowledgeFrontierRecallSource.__init__(store: KnowledgeStore, *, knowledge_sequence: int, index_readiness_sequence: int, required: bool=True, candidate_limit: int=20, max_bytes: int=64000, max_record_bytes: int=8000, semantic_timeout_seconds: float=1.0, lineage_limit: int=0, lineage_candidate_limit: int=10, lineage_max_bytes: int=MAX_KNOWLEDGE_RELATION_BYTES) -> None

retrieve (method)

async KnowledgeFrontierRecallSource.retrieve(situation: RecallSituation) -> RecallSourceResult

Release source · Runtime guarantees · Capability guides

KnowledgeRecallSource

from cayu.memory import KnowledgeRecallSource

Revision-exact lexical and optional semantic lanes from one KnowledgeStore.

Bases: RecallSource.

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
name	class attribute	'knowledge'
channel_names	class attribute	(KNOWLEDGE_LEXICAL_CHANNEL, KNOWLEDGE_SEMANTIC_CHANNEL)
continuation_channels	tuple[str, ...]	()

init (method)

KnowledgeRecallSource.__init__(store: KnowledgeStore, *, required: bool=True, candidate_limit: int=20, max_bytes: int=64000, max_record_bytes: int=8000, semantic_timeout_seconds: float=1.0, lineage_limit: int=0, lineage_candidate_limit: int=10, lineage_max_bytes: int=MAX_KNOWLEDGE_RELATION_BYTES) -> None

retrieve (method)

async KnowledgeRecallSource.retrieve(situation: RecallSituation) -> RecallSourceResult

Release source · Runtime guarantees · Capability guides

KnowledgeRevisionRecallSource

from cayu.memory import KnowledgeRevisionRecallSource

Knowledge recall lane restricted to an exact bounded revision set.

Bases: KnowledgeRecallSource.

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
name	class attribute	'knowledge'
channel_names	class attribute	(KNOWLEDGE_LEXICAL_CHANNEL, KNOWLEDGE_SEMANTIC_CHANNEL)
continuation_channels	tuple[str, ...]	()

init (method)

KnowledgeRevisionRecallSource.__init__(store: KnowledgeStore, revision_refs: Sequence[KnowledgeRevisionRef], *, knowledge_sequence: int | None=None, index_readiness_sequence: int | None=None, required: bool=True, candidate_limit: int=20, max_bytes: int=64000, max_record_bytes: int=8000, semantic_timeout_seconds: float=1.0, lineage_limit: int=0, lineage_candidate_limit: int=10, lineage_max_bytes: int=MAX_KNOWLEDGE_RELATION_BYTES) -> None

retrieve (method)

async KnowledgeRevisionRecallSource.retrieve(situation: RecallSituation) -> RecallSourceResult

Release source · Runtime guarantees · Capability guides

RECALL_ENGINE_VERSION

from cayu.memory import RECALL_ENGINE_VERSION

RECALL_ENGINE_VERSION = 'cayu.recall.v1'

Release source · Runtime guarantees · Capability guides

RecallCandidate

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

RecallEngine

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

RecallEngineConfig

from cayu.memory import RecallEngineConfig

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_timeout_seconds	float	2.0
overall_timeout_seconds	float	5.0
max_parallel_sources	int	4
max_source_result_bytes	int	256000
max_result_bytes	int	128000
engine_version	str	RECALL_ENGINE_VERSION

validate_timeout (method)

RecallEngineConfig.validate_timeout(value, info) -> float

validate_parallelism (method)

RecallEngineConfig.validate_parallelism(value) -> int

validate_byte_limits (method)

RecallEngineConfig.validate_byte_limits(value, info) -> int

validate_engine_version (method)

RecallEngineConfig.validate_engine_version(value: str) -> str

Release source · Runtime guarantees · Capability guides

RecallRecord

from cayu.memory import RecallRecord

Bounded representation and exact locator for one canonical candidate.

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
text	str	required
text_complete	bool	required
content_hash	str	required
title	str | None	Field(default=None, exclude_if=lambda value: value is None)
locator	Mapping[str, Any]	required
lineage	KnowledgeLineageResult | None	Field(default=None, exclude_if=lambda value: value is None)

copy_identity (method)

RecallRecord.copy_identity(value)

validate_representation (method)

RecallRecord.validate_representation(value: str) -> str

validate_text (method)

RecallRecord.validate_text(value: str) -> str

validate_title (method)

RecallRecord.validate_title(value: str | None) -> str | None

validate_text_complete (method)

RecallRecord.validate_text_complete(value) -> bool

validate_content_hash (method)

RecallRecord.validate_content_hash(value: str) -> str

copy_locator (method)

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

freeze_locator (method)

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

serialize_locator (method)

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

copy_lineage (method)

RecallRecord.copy_lineage(value)

validate_lineage_locator (method)

RecallRecord.validate_lineage_locator() -> RecallRecord

Release source · Runtime guarantees · Capability guides

RecallResult

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

RecallSource

from cayu.memory import RecallSource

Trusted read-only extension that returns bounded independently ranked lanes.

Bases: ABC.

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
name	str	required
channel_names	tuple[str, ...]	required
continuation_channels	tuple[str, ...]	()

init (method)

RecallSource.__init__(*, required: bool, candidate_limit: int) -> None

retrieve (method)

async RecallSource.retrieve(situation: RecallSituation) -> RecallSourceResult

Return source-owned channels after hard source filtering.

Release source · Runtime guarantees · Capability guides

RecallSourceDiagnostic

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

RecallSourceResult

from cayu.memory import RecallSourceResult

Validated source output before cross-source fusion.

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
channels	tuple[RankedRetrievalChannel, ...]	required
records	tuple[RecallRecord, ...]	required
coverage_complete	bool	required
partial_reason	str | None	None

validate_source (method)

RecallSourceResult.validate_source(value: str) -> str

copy_channels (method)

RecallSourceResult.copy_channels(value) -> tuple[RankedRetrievalChannel, ...]

copy_records (method)

RecallSourceResult.copy_records(value) -> tuple[RecallRecord, ...]

validate_coverage_complete (method)

RecallSourceResult.validate_coverage_complete(value) -> bool

validate_partial_reason (method)

RecallSourceResult.validate_partial_reason(value: str | None) -> str | None

validate_source_result (method)

RecallSourceResult.validate_source_result() -> RecallSourceResult

Release source · Runtime guarantees · Capability guides

RecallSourceStatus

from cayu.memory import RecallSourceStatus

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
COMPLETE	class attribute	'complete'
PARTIAL	class attribute	'partial'
UNAVAILABLE	class attribute	'unavailable'

Release source · Runtime guarantees · Capability guides

RecallSourceUnavailable

from cayu.memory import RecallSourceUnavailable

A required source could not produce an access-safe bounded result.

Bases: RuntimeError.

init (method)

RecallSourceUnavailable.__init__(source: str, code: str) -> None

Release source · Runtime guarantees · Capability guides

TRANSCRIPT_LEXICAL_CHANNEL

from cayu.memory import TRANSCRIPT_LEXICAL_CHANNEL

TRANSCRIPT_LEXICAL_CHANNEL = 'transcript.lexical'

Release source · Runtime guarantees · Capability guides

TranscriptRecallSource

from cayu.memory import TranscriptRecallSource

Authoritative transcript narrative lane over explicit session scope.

Bases: RecallSource.

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
name	class attribute	'transcript'
channel_names	class attribute	(TRANSCRIPT_LEXICAL_CHANNEL,)
continuation_channels	class attribute	(TRANSCRIPT_LEXICAL_CHANNEL,)

init (method)

TranscriptRecallSource.__init__(store: SessionStore, *, required: bool=False, candidate_limit: int=20, max_bytes: int=64000, max_records_scanned: int=10000) -> None

retrieve (method)

async TranscriptRecallSource.retrieve(situation: RecallSituation) -> RecallSourceResult

supports_store (method)

TranscriptRecallSource.supports_store(store: object) -> bool

Return whether a store exposes the bounded transcript-search contract.

Release source · Runtime guarantees · Capability guides