Serialization API¶
The public serialization helpers preserve the legacy model field order and
produce JSON-compatible values. Use ExtractionResult.write() for versioned
artifact publication with atomic per-file replacement.
legacy ¶
Legacy-compatible main JSON serialization.
legacy_payload ¶
legacy_payload(output: Any) -> Any
Convert structured output to JSON values while preserving field order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output
|
Any
|
Pydantic model or another value supported by Pydantic's type adapter. |
required |
Returns:
| Type | Description |
|---|---|
Any
|
A JSON-compatible value with model field order preserved. |
Raises:
| Type | Description |
|---|---|
TypeError
|
A nested mapping uses a non-string key. |
legacy_json_bytes ¶
legacy_json_bytes(output: Any) -> bytes
Serialize the compatibility projection as deterministic UTF-8 JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output
|
Any
|
Pydantic model or another supported Python value. |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
Two-space-indented UTF-8 JSON bytes with field order preserved. |
Raises:
| Type | Description |
|---|---|
TypeError
|
A nested mapping uses a non-string key. |
ValueError
|
The converted value contains a non-finite JSON number. |
Artifact contracts¶
artifacts ¶
Durable, recoverable local artifact generation and publication.
ArtifactManifestV1 ¶
Bases: BaseModel
Strict parser for the unchanged legacy artifact manifest.
ArtifactManifestV2 ¶
Bases: BaseModel
Strict routed manifest with versions and digests but no prose fields.
model_config
class-attribute
instance-attribute
¶
model_config = ConfigDict(
extra="forbid", frozen=True, hide_input_in_errors=True
)
survey_id
class-attribute
instance-attribute
¶
survey_id: StrictStr = Field(
pattern="^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
)
run_id
class-attribute
instance-attribute
¶
run_id: StrictStr = Field(
pattern="^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
)
generation_id
class-attribute
instance-attribute
¶
generation_id: StrictStr = Field(pattern='^[0-9a-f]{32}$')
routed_main_sha256
class-attribute
instance-attribute
¶
routed_main_sha256: StrictStr = Field(
pattern=_SHA256_PATTERN
)
legacy_projection_sha256
class-attribute
instance-attribute
¶
legacy_projection_sha256: StrictStr = Field(
pattern=_SHA256_PATTERN
)
source_sha256
instance-attribute
¶
source_sha256: tuple[
Annotated[StrictStr, Field(pattern=_SHA256_PATTERN)],
...,
]
model_response_sha256
instance-attribute
¶
model_response_sha256: tuple[
Annotated[StrictStr, Field(pattern=_SHA256_PATTERN)],
...,
]
ArtifactPlan
dataclass
¶
ArtifactPlan(
survey_id: str,
files: tuple[SerializedArtifact, ...],
manifest_schema_version: int = 1,
routed_metadata: RoutedManifestMetadata | None = None,
)
Detached serializer output consumed by the publication transaction.
routed_metadata
class-attribute
instance-attribute
¶
routed_metadata: RoutedManifestMetadata | None = None
ArtifactSerializer ¶
Bases: Protocol[T_contra]
Port that creates a detached, typed artifact plan for one output.
build_plan ¶
build_plan(
output: T_contra, *, survey_id: str
) -> ArtifactPlan
Build a complete detached plan without filesystem side effects.
JsonArtifactSerializer ¶
JsonArtifactSerializer(
output_type: type[T],
*,
filename_suffix: str = "_result.json",
)
Bases: Generic[T]
Typed JSON serializer for generic non-SVIS Pydantic-compatible output.
build_plan ¶
build_plan(output: T, *, survey_id: str) -> ArtifactPlan
Revalidate a detached JSON snapshot and build a generic JSON plan.
SerializedArtifact
dataclass
¶
SerializedArtifact(
kind: ArtifactKind | str,
generation_filename: str,
content: bytes,
publication_filename: str | None = None,
publication_kind: ArtifactKind | str | None = None,
)
One immutable generation file and its optional stable publication.
publication_kind
class-attribute
instance-attribute
¶
publication_kind: ArtifactKind | str | None = None
SurveySVISArtifactSerializer ¶
Exact-type legacy v1 SurveySVIS serializer.
build_plan ¶
build_plan(
output: SurveySVIS, *, survey_id: str
) -> ArtifactPlan
Revalidate a detached exact SurveySVIS snapshot and preserve v1 bytes.
parse_artifact_manifest ¶
parse_artifact_manifest(
content: bytes | str,
) -> ArtifactManifestV1 | ArtifactManifestV2
Parse one strict v1 or routed v2 manifest with a fixed safe failure.
Routed publication uses RoutedSurveySVISArtifactSerializer, writes a routed
main plus exact legacy projection, and records manifest version 2.
routing ¶
Typed routed SVIS projection and manifest v2 serialization.
RoutedSurveySVISArtifactSerializer ¶
RoutedSurveySVISArtifactSerializer(
*, provenance: ArtifactProvenance | None = None
)
Build one detached routed main and exact ordered v1 projection.
build_plan ¶
build_plan(
output: RoutedSurveySVIS, *, survey_id: str
) -> ArtifactPlan
Revalidate a frozen routed snapshot before any filesystem operation.