cayu.evals.promotion

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.

`build_captured_evaluation_candidate`

from cayu.evals import build_captured_evaluation_candidate

Build a deterministic assertion contract without requiring replay input.

build_captured_evaluation_candidate(app: CayuApp, trajectory: Trajectory, *, target_key: str, source_agent_name: str, application_release_id: str, evidence_policy: EvaluationEvidencePolicySpec, pricing: PriceBook | None=None, source_label: str | None=None, project_root: str | Path | None=None) -> CapturedEvaluationCandidateV1

Release source · Runtime guarantees · Capability guides

`build_promotion_candidate`

from cayu.evals import build_promotion_candidate

Build one deterministic, public-safe candidate from eligible terminal evidence.

build_promotion_candidate(app: CayuApp, trajectory: Trajectory, *, target_key: str, source_agent_name: str, application_release_id: str, evidence_policy: EvaluationEvidencePolicySpec, pricing: PriceBook | None=None, source_label: str | None=None, project_root: str | Path | None=None) -> PromotionCandidateV1

Release source · Runtime guarantees · Capability guides

`CAPTURED_EVALUATION_CANDIDATE_MAX_BYTES`

from cayu.evals import CAPTURED_EVALUATION_CANDIDATE_MAX_BYTES

CAPTURED_EVALUATION_CANDIDATE_MAX_BYTES = 16 << 20

Release source · Runtime guarantees · Capability guides

`CAPTURED_EVALUATION_CANDIDATE_SCHEMA_VERSION`

from cayu.evals import CAPTURED_EVALUATION_CANDIDATE_SCHEMA_VERSION

CAPTURED_EVALUATION_CANDIDATE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`CAPTURED_RUN_SCORE_MAX_BYTES`

from cayu.evals import CAPTURED_RUN_SCORE_MAX_BYTES

CAPTURED_RUN_SCORE_MAX_BYTES = 2 << 20

Release source · Runtime guarantees · Capability guides

`CAPTURED_RUN_SCORE_SCHEMA_VERSION`

from cayu.evals import CAPTURED_RUN_SCORE_SCHEMA_VERSION

CAPTURED_RUN_SCORE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`CapturedEvaluationCandidateV1`

from cayu.evals import CapturedEvaluationCandidateV1

Editable assertion contract bound to coherent captured evidence only.

Bases: _SchemaV1PortableModel.

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[1]`	`CAPTURED_EVALUATION_CANDIDATE_SCHEMA_VERSION`
`revision`	`StrictStr`	`required`
`target_key`	`StrictStr`	`required`
`source`	`CapturedEvaluationSourceV1`	`required`
`evidence_policy`	`EvaluationEvidencePolicySpec`	`required`
`pricing_profile`	`PricingProfileIdentityV1 \| None`	`None`
`evidence`	`AssertionEvidenceView`	`required`
`suite`	`EvalSuiteSpec`	`required`
`case`	`PromotionCaseV1`	`required`
`warnings`	`tuple[CapturedEvaluationWarningCode, ...]`	`Field(max_length=1)`

validate_schema_version_type (method)

CapturedEvaluationCandidateV1.validate_schema_version_type(value: object) -> object

validate_target_key (method)

CapturedEvaluationCandidateV1.validate_target_key(value: str, info) -> str

validate_revision_shape (method)

CapturedEvaluationCandidateV1.validate_revision_shape(value: str, info) -> str

validate_warnings_are_ordered (method)

CapturedEvaluationCandidateV1.validate_warnings_are_ordered(value: object, info) -> object

validate_contract (method)

CapturedEvaluationCandidateV1.validate_contract() -> CapturedEvaluationCandidateV1

create (method)

CapturedEvaluationCandidateV1.create(*, target_key: str, source: CapturedEvaluationSourceV1, evidence_policy: EvaluationEvidencePolicySpec, evidence: AssertionEvidenceView, suite: EvalSuiteSpec, case: EvalCaseSpec, pricing_profile: PricingProfileIdentityV1 | None=None) -> CapturedEvaluationCandidateV1

Release source · Runtime guarantees · Capability guides

`CapturedEvaluationSourceV1`

from cayu.evals import CapturedEvaluationSourceV1

Public-safe provenance for evaluation without replay authority.

Bases: _SchemaV1PortableModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`1`
`source_agent_name`	`StrictStr`	`required`
`application_release_id`	`StrictStr`	`required`
`app_manifest_schema_version`	`StrictStr`	`required`
`app_manifest_fingerprint`	`StrictStr`	`required`
`evidence_revision`	`StrictStr`	`required`
`evidence_policy_revision`	`StrictStr`	`required`
`pricing_profile_fingerprint`	`StrictStr \| None`	`None`
`source_label`	`StrictStr \| None`	`None`

validate_schema_version_type (method)

CapturedEvaluationSourceV1.validate_schema_version_type(value: object) -> object

validate_source_identity (method)

CapturedEvaluationSourceV1.validate_source_identity(value: str, info) -> str

validate_manifest_schema_version (method)

CapturedEvaluationSourceV1.validate_manifest_schema_version(value: str, info) -> str

validate_source_label (method)

CapturedEvaluationSourceV1.validate_source_label(value: str | None, info) -> str | None

validate_manifest_fingerprint (method)

CapturedEvaluationSourceV1.validate_manifest_fingerprint(value: str, info) -> str

validate_content_revision (method)

CapturedEvaluationSourceV1.validate_content_revision(value: str | None, info) -> str | None

case_source (method)

CapturedEvaluationSourceV1.case_source() -> EvaluationSourceIdentityV1

Release source · Runtime guarantees · Capability guides

`CapturedEvaluationWarningCode`

from cayu.evals import CapturedEvaluationWarningCode

Stable non-blocking facts about one captured evaluation.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`SOURCE_RUN_FAILED`	`class attribute`	`'source_run_failed'`

Release source · Runtime guarantees · Capability guides

`CapturedRunScoreV1`

from cayu.evals import CapturedRunScoreV1

Bounded public score for an edited candidate against its captured evidence.

Bases: _SchemaV1PortableModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`CAPTURED_RUN_SCORE_SCHEMA_VERSION`
`revision`	`StrictStr`	`required`
`candidate_revision`	`StrictStr`	`required`
`case_id`	`StrictStr`	`required`
`case_revision`	`StrictStr`	`required`
`evidence_revision`	`StrictStr`	`required`
`evidence_policy_revision`	`StrictStr`	`required`
`pricing_profile_fingerprint`	`StrictStr \| None`	`None`
`memory_attribution`	`EvalMemoryAttributionEvidenceV1`	`required`
`status`	`PublishedStatus`	`required`
`score`	`StrictFloat \| None`	`Field(default=None, ge=0.0, le=1.0)`
`assertions`	`tuple[PublishedAssertionResult, ...]`	`Field(min_length=1, max_length=EVAL_CORPUS_MAX_ASSERTIONS_PER_CASE)`

validate_schema_version_type (method)

CapturedRunScoreV1.validate_schema_version_type(value: object) -> object

validate_revision_shape (method)

CapturedRunScoreV1.validate_revision_shape(value: str | None, info) -> str | None

validate_case_id (method)

CapturedRunScoreV1.validate_case_id(value: str, info) -> str

validate_assertions_are_ordered (method)

CapturedRunScoreV1.validate_assertions_are_ordered(value: object, info) -> object

validate_contract (method)

CapturedRunScoreV1.validate_contract() -> CapturedRunScoreV1

create (method)

CapturedRunScoreV1.create(*, candidate: PromotionCandidateV1 | CapturedEvaluationCandidateV1, evidence: AssertionEvidenceView, assertions: Sequence[PublishedAssertionResult]) -> CapturedRunScoreV1

Release source · Runtime guarantees · Capability guides

`corpus_from_captured_evaluation_candidate`

from cayu.evals import corpus_from_captured_evaluation_candidate

Build the immutable captured-only corpus represented by a candidate.

corpus_from_captured_evaluation_candidate(candidate: CapturedEvaluationCandidateV1) -> EvalCorpusDocument

Release source · Runtime guarantees · Capability guides

`corpus_from_promotion_candidate`

from cayu.evals import corpus_from_promotion_candidate

Build the exact one-case corpus represented by a reviewed candidate.

corpus_from_promotion_candidate(candidate: PromotionCandidateV1) -> EvalCorpusDocument

Release source · Runtime guarantees · Capability guides

`export_captured_evaluation_corpus`

from cayu.evals import export_captured_evaluation_corpus

export_captured_evaluation_corpus(candidate: CapturedEvaluationCandidateV1) -> bytes

Release source · Runtime guarantees · Capability guides

`export_promotion_corpus`

from cayu.evals import export_promotion_corpus

Return canonical UTF-8 corpus bytes for one reviewed candidate.

export_promotion_corpus(candidate: PromotionCandidateV1) -> bytes

Release source · Runtime guarantees · Capability guides

`promotable_run_input`

from cayu.evals import promotable_run_input

Return safe initial input only when one trajectory is honestly replayable in v1.

promotable_run_input(app: CayuApp, trajectory: Trajectory, *, source_agent_name: str) -> PromotableRunInputV1

Release source · Runtime guarantees · Capability guides

`PROMOTABLE_RUN_INPUT_SCHEMA_VERSION`

from cayu.evals import PROMOTABLE_RUN_INPUT_SCHEMA_VERSION

PROMOTABLE_RUN_INPUT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`PromotableRunInputV1`

from cayu.evals import PromotableRunInputV1

Sanitized, text-only caller input proven to belong to one fresh invocation.

Bases: _SchemaV1PortableModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`PROMOTABLE_RUN_INPUT_SCHEMA_VERSION`
`revision`	`StrictStr`	`required`
`messages`	`tuple[CorpusUserMessageSpec, ...]`	`Field(min_length=1, max_length=EVAL_CORPUS_MAX_MESSAGES_PER_CASE)`
`redactions_applied`	`StrictBool`	`False`

validate_schema_version_type (method)

PromotableRunInputV1.validate_schema_version_type(value: object) -> object

validate_revision_shape (method)

PromotableRunInputV1.validate_revision_shape(value: str, info) -> str

validate_messages_are_ordered (method)

PromotableRunInputV1.validate_messages_are_ordered(value: object, info) -> object

validate_run_input_contract (method)

PromotableRunInputV1.validate_run_input_contract() -> PromotableRunInputV1

create (method)

PromotableRunInputV1.create(*, messages: Sequence[CorpusUserMessageSpec], redactions_applied: bool=False) -> PromotableRunInputV1

to_run_input_spec (method)

PromotableRunInputV1.to_run_input_spec() -> RunInputSpec

Release source · Runtime guarantees · Capability guides

`PROMOTION_CANDIDATE_MAX_BYTES`

from cayu.evals import PROMOTION_CANDIDATE_MAX_BYTES

PROMOTION_CANDIDATE_MAX_BYTES = 16 << 20

Release source · Runtime guarantees · Capability guides

`PROMOTION_CANDIDATE_SCHEMA_VERSION`

from cayu.evals import PROMOTION_CANDIDATE_SCHEMA_VERSION

PROMOTION_CANDIDATE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`PROMOTION_SOURCE_SCHEMA_VERSION`

from cayu.evals import PROMOTION_SOURCE_SCHEMA_VERSION

PROMOTION_SOURCE_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`PromotionCandidateV1`

from cayu.evals import PromotionCandidateV1

One deterministic, editable case candidate and its public-safe evidence.

Bases: _SchemaV1PortableModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`PROMOTION_CANDIDATE_SCHEMA_VERSION`
`revision`	`StrictStr`	`required`
`target_key`	`StrictStr`	`required`
`source`	`PromotionSourceV1`	`required`
`evidence_policy`	`EvaluationEvidencePolicySpec`	`required`
`pricing_profile`	`PricingProfileIdentityV1 \| None`	`None`
`evidence`	`AssertionEvidenceView`	`required`
`suite`	`EvalSuiteSpec`	`required`
`case`	`PromotionCaseV1`	`required`
`warnings`	`tuple[PromotionWarningCode, ...]`	`Field(max_length=2)`

validate_schema_version_type (method)

PromotionCandidateV1.validate_schema_version_type(value: object) -> object

validate_target_key (method)

PromotionCandidateV1.validate_target_key(value: str, info) -> str

validate_revision_shape (method)

PromotionCandidateV1.validate_revision_shape(value: str, info) -> str

validate_warnings_are_ordered (method)

PromotionCandidateV1.validate_warnings_are_ordered(value: object, info) -> object

validate_contract (method)

PromotionCandidateV1.validate_contract() -> PromotionCandidateV1

create (method)

PromotionCandidateV1.create(*, target_key: str, source: PromotionSourceV1, evidence_policy: EvaluationEvidencePolicySpec, evidence: AssertionEvidenceView, suite: EvalSuiteSpec, case: EvalCaseSpec, pricing_profile: PricingProfileIdentityV1 | None=None) -> PromotionCandidateV1

Release source · Runtime guarantees · Capability guides

`PromotionCaseV1`

from cayu.evals import PromotionCaseV1

Immutable corpus case restricted to the V1 promotion assertion surface.

Bases: EvalCaseSpec.

Fields and attributes

Name	Type	Default
`id`	`StrictStr`	`required`
`revision`	`StrictStr`	`required`
`suite_id`	`StrictStr`	`required`
`name`	`StrictStr`	`required`
`description`	`StrictStr \| None`	`None`
`source`	`EvaluationSourceIdentityV1`	`required`
`input`	`RunInputSpec \| None`	`required`
`assertions`	`tuple[EvalSuiteAuthoringAssertionSpecV1, ...]`	`Field(min_length=1, max_length=EVAL_CORPUS_MAX_ASSERTIONS_PER_CASE)`

validate_assertions_are_ordered (method)

PromotionCaseV1.validate_assertions_are_ordered(value: object, info) -> object

validate_id (method)

PromotionCaseV1.validate_id(value: str, info) -> str

validate_revision_shape (method)

PromotionCaseV1.validate_revision_shape(value: str, info) -> str

validate_name (method)

PromotionCaseV1.validate_name(value: str, info) -> str

validate_description (method)

PromotionCaseV1.validate_description(value: str | None, info) -> str | None

validate_contract (method)

PromotionCaseV1.validate_contract() -> EvalCaseSpec

create (method)

PromotionCaseV1.create(*, id: str, suite_id: str, name: str, source: EvaluationSourceIdentityV1, input: RunInputSpec | None, assertions: Sequence[AssertionSpec], description: str | None=None) -> EvalCaseSpec

Release source · Runtime guarantees · Capability guides

`PromotionSourceV1`

from cayu.evals import PromotionSourceV1

Safe diagnostic capture provenance without executable or session authority.

Bases: _SchemaV1PortableModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`PROMOTION_SOURCE_SCHEMA_VERSION`
`source_agent_name`	`StrictStr`	`required`
`application_release_id`	`StrictStr`	`required`
`app_manifest_schema_version`	`StrictStr`	`required`
`app_manifest_fingerprint`	`StrictStr`	`required`
`input_revision`	`StrictStr`	`required`
`input_redactions_applied`	`StrictBool`	`required`
`evidence_revision`	`StrictStr`	`required`
`evidence_policy_revision`	`StrictStr`	`required`
`pricing_profile_fingerprint`	`StrictStr \| None`	`None`
`source_label`	`StrictStr \| None`	`None`

validate_schema_version_type (method)

PromotionSourceV1.validate_schema_version_type(value: object) -> object

validate_source_identity (method)

PromotionSourceV1.validate_source_identity(value: str, info) -> str

validate_manifest_schema_version (method)

PromotionSourceV1.validate_manifest_schema_version(value: str, info) -> str

validate_source_label (method)

PromotionSourceV1.validate_source_label(value: str | None, info) -> str | None

validate_manifest_fingerprint (method)

PromotionSourceV1.validate_manifest_fingerprint(value: str, info) -> str

validate_content_revision (method)

PromotionSourceV1.validate_content_revision(value: str | None, info) -> str | None

case_source (method)

PromotionSourceV1.case_source() -> EvaluationSourceIdentityV1

Return the corpus-native subset persisted with the promoted case.

Release source · Runtime guarantees · Capability guides

`PromotionWarningCode`

from cayu.evals import PromotionWarningCode

Stable, non-blocking fact surfaced with one editable candidate.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`INPUT_REDACTED`	`class attribute`	`'input_redacted'`
`SOURCE_RUN_FAILED`	`class attribute`	`'source_run_failed'`

Release source · Runtime guarantees · Capability guides

`runnable_promotion_candidate`

from cayu.evals import runnable_promotion_candidate

Transfer a reviewed captured contract onto server-reconstructed safe input.

The operator-authored suite, case, and assertions remain unchanged. Only the server-owned replay source and its attested input come from the current runnable baseline; this prevents a browser from manufacturing executable session input or changing provenance.

runnable_promotion_candidate(captured: CapturedEvaluationCandidateV1, runnable_baseline: PromotionCandidateV1, *, trial_request: TrialRequestSpec | None=None) -> PromotionCandidateV1

Release source · Runtime guarantees · Capability guides

`score_captured_evaluation_candidate`

from cayu.evals import score_captured_evaluation_candidate

Score reviewed assertions solely against the retained evidence snapshot.

score_captured_evaluation_candidate(app: CayuApp, trajectory: Trajectory, candidate: CapturedEvaluationCandidateV1, *, target_key: str, source_agent_name: str, application_release_id: str, pricing: PriceBook | None=None, project_root: str | Path | None=None) -> CapturedRunScoreV1

Release source · Runtime guarantees · Capability guides

`score_promotion_candidate`

from cayu.evals import score_promotion_candidate

Score one reviewed candidate through the existing portable assertion engine.

score_promotion_candidate(app: CayuApp, trajectory: Trajectory, candidate: PromotionCandidateV1, *, target_key: str, source_agent_name: str, application_release_id: str, pricing: PriceBook | None=None, project_root: str | Path | None=None) -> CapturedRunScoreV1

Release source · Runtime guarantees · Capability guides

`SessionPromotionError`

from cayu.evals import SessionPromotionError

Typed fail-closed rejection from the pure promotion contract.

Bases: RuntimeError.

init (method)

SessionPromotionError.__init__(code: SessionPromotionErrorCode) -> None

Release source · Runtime guarantees · Capability guides

`SessionPromotionErrorCode`

from cayu.evals import SessionPromotionErrorCode

Stable reason one captured trajectory cannot become a portable eval case.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`INVALID_TRAJECTORY`	`class attribute`	`'invalid_trajectory'`
`SOURCE_AGENT_MISMATCH`	`class attribute`	`'source_agent_mismatch'`
`ROOT_STATUS_UNSUPPORTED`	`class attribute`	`'root_status_unsupported'`
`DESCENDANT_EVIDENCE_UNSUPPORTED`	`class attribute`	`'descendant_evidence_unsupported'`
`APPROVAL_CONTINUATION_UNSUPPORTED`	`class attribute`	`'approval_continuation_unsupported'`
`SESSION_RESUME_UNSUPPORTED`	`class attribute`	`'session_resume_unsupported'`
`QUEUED_INPUT_UNSUPPORTED`	`class attribute`	`'queued_input_unsupported'`
`LATER_INTERACTION_UNSUPPORTED`	`class attribute`	`'later_interaction_unsupported'`
`STRUCTURED_OUTPUT_UNSUPPORTED`	`class attribute`	`'structured_output_unsupported'`
`INPUT_EVIDENCE_UNAVAILABLE`	`class attribute`	`'input_evidence_unavailable'`
`INPUT_EVIDENCE_INCONSISTENT`	`class attribute`	`'input_evidence_inconsistent'`
`INPUT_MESSAGE_COUNT_UNSUPPORTED`	`class attribute`	`'input_message_count_unsupported'`
`INPUT_ROLE_UNSUPPORTED`	`class attribute`	`'input_role_unsupported'`
`INPUT_PART_UNSUPPORTED`	`class attribute`	`'input_part_unsupported'`
`INPUT_LIMIT_EXCEEDED`	`class attribute`	`'input_limit_exceeded'`
`INPUT_REDACTION_FAILED`	`class attribute`	`'input_redaction_failed'`

Release source · Runtime guarantees · Capability guides