Results API

Result models are frozen and reject unknown fields. ExtractionResult[T] can contain mutable caller-owned output even though the envelope is frozen.

See Results and Artifacts for status rules, filesystem layout, collision behavior, and sensitive-data handling.

Typed artifact-plan and serializer ports are exported from survey_scribe.serialization.

results

Frozen typed extraction results and stable diagnostics.

ResultStatus

Bases: StrEnum

Derived extraction outcome.

success class-attribute instance-attribute

success = 'success'

partial class-attribute instance-attribute

partial = 'partial'

failed class-attribute instance-attribute

failed = 'failed'

DiagnosticSeverity

Bases: StrEnum

Operational effect of a diagnostic.

info class-attribute instance-attribute

info = 'info'

warning class-attribute instance-attribute

warning = 'warning'

error class-attribute instance-attribute

error = 'error'

DiagnosticCode

Bases: StrEnum

Stable built-in diagnostic codes.

quality_low_confidence class-attribute instance-attribute

quality_low_confidence = 'QUALITY_LOW_CONFIDENCE'

quality_missing_categories class-attribute instance-attribute

quality_missing_categories = 'QUALITY_MISSING_CATEGORIES'

quality_duplicate_raw_name class-attribute instance-attribute

quality_duplicate_raw_name = 'QUALITY_DUPLICATE_RAW_NAME'

quality_overlap_deduped class-attribute instance-attribute

quality_overlap_deduped = 'QUALITY_OVERLAP_DEDUPED'

quality_possible_duplicate class-attribute instance-attribute

quality_possible_duplicate = 'QUALITY_POSSIBLE_DUPLICATE'

quality_module_reconciled class-attribute instance-attribute

quality_module_reconciled = 'QUALITY_MODULE_RECONCILED'

metadata_incomplete class-attribute instance-attribute

metadata_incomplete = 'METADATA_INCOMPLETE'

source_unreadable class-attribute instance-attribute

source_unreadable = 'SOURCE_UNREADABLE'

provider_failed class-attribute instance-attribute

provider_failed = 'PROVIDER_FAILED'

provider_truncated class-attribute instance-attribute

provider_truncated = 'PROVIDER_TRUNCATED'

validation_failed class-attribute instance-attribute

validation_failed = 'VALIDATION_FAILED'

block_failed class-attribute instance-attribute

block_failed = 'BLOCK_FAILED'

xlsform_choice_list_missing class-attribute instance-attribute

xlsform_choice_list_missing = 'XLSFORM_CHOICE_LIST_MISSING'

xlsform_expression_unsupported class-attribute instance-attribute

xlsform_expression_unsupported = (
    "XLSFORM_EXPRESSION_UNSUPPORTED"
)

xlsform_feature_unsupported class-attribute instance-attribute

xlsform_feature_unsupported = 'XLSFORM_FEATURE_UNSUPPORTED'

xlsform_function_unsupported class-attribute instance-attribute

xlsform_function_unsupported = (
    "XLSFORM_FUNCTION_UNSUPPORTED"
)

xlsform_reference_unresolved class-attribute instance-attribute

xlsform_reference_unresolved = (
    "XLSFORM_REFERENCE_UNRESOLVED"
)

xlsform_type_unsupported class-attribute instance-attribute

xlsform_type_unsupported = 'XLSFORM_TYPE_UNSUPPORTED'

Diagnostic

Bases: BaseModel

One stable diagnostic without raw provider response data.

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', frozen=True)

code instance-attribute

code: DiagnosticCode | str

message instance-attribute

message: str

severity class-attribute instance-attribute

severity: DiagnosticSeverity = DiagnosticSeverity.warning

details class-attribute instance-attribute

details: dict[StrictStr, Any] = Field(default_factory=dict)

freeze_json_details classmethod

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

Detach and recursively freeze finite JSON-compatible details.

FailedBlock

Bases: BaseModel

A source block that did not produce usable structured output.

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', frozen=True)

block_id instance-attribute

block_id: str

message instance-attribute

message: str

source_order class-attribute instance-attribute

source_order: int | None = Field(default=None, ge=0)

ArtifactKind

Bases: StrEnum

Published artifact role.

main class-attribute instance-attribute

main = 'main'

sidecar class-attribute instance-attribute

sidecar = 'sidecar'

manifest class-attribute instance-attribute

manifest = 'manifest'

legacy class-attribute instance-attribute

legacy = 'legacy'

projection class-attribute instance-attribute

projection = 'projection'

active_pointer class-attribute instance-attribute

active_pointer = 'active_pointer'

ArtifactReference

Bases: BaseModel

Reference to one validated local artifact.

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', frozen=True)

kind instance-attribute

kind: ArtifactKind | str

path instance-attribute

path: Path

generation_id instance-attribute

generation_id: str

sha256 class-attribute instance-attribute

sha256: str = Field(pattern='^[0-9a-f]{64}$')

PromptArtifactProvenance

Bases: BaseModel

One routing prompt identity without prompt or questionnaire content.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

pass_kind instance-attribute

pass_kind: Literal[
    "forward",
    "incoming_activation",
    "reviewer",
    "metadata",
    "extraction",
]

version instance-attribute

version: SemanticVersion

prompt_sha256 instance-attribute

prompt_sha256: Sha256

ArtifactProvenance

Bases: BaseModel

Digest-only provenance supplied to an artifact serializer.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid", frozen=True, hide_input_in_errors=True
)

source_sha256 instance-attribute

source_sha256: tuple[Sha256, ...]

model_response_sha256 instance-attribute

model_response_sha256: tuple[Sha256, ...]

prompt_versions instance-attribute

prompt_versions: tuple[PromptArtifactProvenance, ...]

require_stable_unique_records

require_stable_unique_records() -> ArtifactProvenance

Reject duplicate digests and duplicate prompt identities.

ExtractionResult

Bases: BaseModel, Generic[T]

Frozen result envelope; caller-owned output T can remain mutable.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    arbitrary_types_allowed=True,
)

output instance-attribute

output: T | None

survey_id class-attribute instance-attribute

survey_id: str | None = None

run_id class-attribute instance-attribute

run_id: str = Field(default_factory=lambda: uuid4().hex)

diagnostics class-attribute instance-attribute

diagnostics: tuple[Diagnostic, ...] = ()

failed_blocks class-attribute instance-attribute

failed_blocks: tuple[FailedBlock, ...] = ()

artifacts class-attribute instance-attribute

artifacts: tuple[ArtifactReference, ...] = ()

artifact_provenance class-attribute instance-attribute

artifact_provenance: ArtifactProvenance | None = Field(
    default=None, exclude=True, repr=False
)

status property

status: ResultStatus

Derive status from usable output and operational failures.

Returns:

Type	Description
ResultStatus	failed without output, partial after an operational failure,
ResultStatus	or success when usable output has no operational failure.

derive_survey_id

derive_survey_id() -> ExtractionResult[T]

Use the output survey identifier when no envelope value was supplied.

serialization_snapshot

serialization_snapshot() -> dict[str, Any]

Return a detached JSON-compatible snapshot of the current envelope.

Returns:

Type	Description
dict[str, Any]	A deep-copied dictionary that does not change if caller-owned output
dict[str, Any]	is later mutated.

write

write(
    output_dir: str | PathLike[str],
    *,
    sidecar: bool = True,
    overwrite: bool = False,
    serializer: ArtifactSerializer[T] | None = None,
) -> ExtractionResult[T]

Publish one versioned generation and return its artifact references.

Parameters:

Name	Type	Description	Default
output_dir	str | PathLike[str]	Trusted local directory for stable and generation files.	required
sidecar	bool	Whether to include the diagnostic sidecar.	True
overwrite	bool	Whether to publish a new generation when stable artifacts already exist.	False
serializer	ArtifactSerializer[T] | None	Optional typed serializer. Exact SurveySVIS uses the legacy v1 serializer; other output uses generic JSON by default.	None

Returns:

Type	Description
ExtractionResult[T]	A new frozen result containing references and SHA-256 digests for the
ExtractionResult[T]	published files.

Raises:

Type	Description
ArtifactCollisionError	Artifacts exist and overwrite is disabled, or another writer holds the survey lock.
ArtifactWriteError	Validation, generation, projection, pointer, or filesystem publication fails.

Note

The process-owned survey lock covers recovery and publication. A durable journal repairs a hard exit before another write proceeds.