bead.interop

Lossless, law-verified interoperability mappings between bead models and external schemas. The layers subpackage maps bead's corpus and annotation data to the layers linguistic-annotation schema and back via didactic lenses (dx.Iso / dx.Lens); round-trip fidelity is guaranteed by the GetPut/PutGet lens laws.

See the Layers Interoperability guide for usage.

Bridge lenses (bead-native <-> layers)

graph_lens

Lens between a CorpusGraph and the layers property graph.

The lens projects a :class:~bead.corpus.graph.CorpusGraph to a layers-shaped view (expression records, graph nodes, and a graphEdgeSet) and keeps a complement holding the information layers' graph does not express directly (the bead framework identity, edge directedness, and exact float confidence). Together the view and complement reconstruct the graph exactly.

CorpusGraphLayersLens

Bases: Lens[CorpusGraph, JsonValue, JsonValue]

Lossless lens CorpusGraph <-> (layers graph view, bead complement).

forward(graph: CorpusGraph) -> tuple[JsonValue, JsonValue]

Project a graph to its layers view and bead complement.

backward(view: JsonValue, complement: JsonValue) -> CorpusGraph

Reconstruct the graph from its layers view and bead complement.

graph_to_layers(graph: CorpusGraph) -> JsonValue

Return the standalone layers-shaped view of a corpus graph.

bridges

Bridge lenses between bead-native models and layers constructs.

These map the things bead's pipeline actually produces onto layers records:

  • :class:~bead.corpus.records.CorpusRecord <-> a layers expression.

The layers view is a faithful, standalone projection; the lens complement holds the bead-only remainder (framework identity and fields layers has no slot for), so the round-trip is exact and the GetPut/PutGet laws hold.

RecordExpressionLens

Bases: Lens[CorpusRecord, JsonValue, JsonValue]

Lossless lens CorpusRecord <-> (layers expression view, complement).

forward(record: CorpusRecord) -> tuple[JsonValue, JsonValue]

Project a record to a layers expression view and bead complement.

backward(view: JsonValue, complement: JsonValue) -> CorpusRecord

Reconstruct a record from its layers expression view and complement.

record_to_expression(record: CorpusRecord) -> JsonValue

Return the standalone layers expression view of a corpus record.

parse_lens

Lossless iso between a dependency parse and layers annotation records.

A :class:~bead.tokenization.parsers.ParsedSentence maps to a layers tokenization plus two annotation layers (a part-of-speech token-tag layer and a dependency relation layer). ParsedToken/ParsedSentence carry no framework identity, so the mapping is a true bijection (dx.Iso): the layers view captures everything and reconstructs the parse exactly.

ParsedSentenceLayersIso

Bases: Iso[ParsedSentence, JsonValue]

Lossless ParsedSentence <-> layers tokenization + annotation layers.

forward(sentence: ParsedSentence) -> JsonValue

Project a parsed sentence to layers tokenization + annotations.

backward(view: JsonValue) -> ParsedSentence

Reconstruct a parsed sentence from its layers projection.

parse_to_layers(sentence: ParsedSentence) -> JsonValue

Return the layers tokenization + annotation-layer view of a parse.

Mirror models

Faithful didactic mirrors of the layers constructs.

models

Faithful didactic mirrors of the layers shared object definitions.

Each model mirrors a pub.layers.defs object field-for-field (snake_case names corresponding to layers' camelCase, nested objects as embedded models, feature maps as :class:FeatureMap, confidence as an integer 0-1000). The structural fidelity lets :mod:bead.interop.layers._mirror serialize any of them to and from layers JSON losslessly with a single generic conversion.

Names that would clash with bead's own models are prefixed Layers.

LayersUuid

Bases: Model

A layers uuid value object.

Feature

Bases: Model

A single key/value entry in a layers featureMap.

FeatureMap

Bases: Model

A layers featureMap (ordered key/value entries).

KnowledgeRef

Bases: Model

A layers knowledgeRef grounding to an external knowledge base.

BoundingBox

Bases: Model

A layers boundingBox (pixel region).

TemporalSpan

Bases: Model

A layers temporalSpan (millisecond interval).

AgentRef

Bases: Model

A layers agentRef (annotating agent).

ObjectRef

Bases: Model

A layers objectRef (local, record, or external reference).

LayersSpan

Bases: Model

A layers span (UTF-8 byte offsets, optional char offsets).

TokenRef

Bases: Model

A layers tokenRef (single token in a tokenization).

TokenRefSequence

Bases: Model

A layers tokenRefSequence (ordered tokens, optional anchor).

Keyframe

Bases: Model

A layers keyframe (a bounding box at a video time).

SpatioTemporalAnchor

Bases: Model

A layers spatioTemporalAnchor (time span plus keyframes).

TemporalEntity

Bases: Model

A layers temporalEntity (instant/interval/duration value).

TemporalModifier

Bases: Model

A layers temporalModifier.

TemporalExpression

Bases: Model

A layers temporalExpression.

SpatialEntity

Bases: Model

A layers spatialEntity (geometry/region value).

SpatialModifier

Bases: Model

A layers spatialModifier.

SpatialExpression

Bases: Model

A layers spatialExpression.

PageAnchor

Bases: Model

A layers pageAnchor (a region on a document page).

TextQuoteSelector

Bases: Model

A W3C-style textQuoteSelector.

TextPositionSelector

Bases: Model

A W3C-style textPositionSelector.

FragmentSelector

Bases: Model

A W3C-style fragmentSelector.

Selector

Bases: Model

The selector union of a layers externalTarget.

ExternalTarget

Bases: Model

A layers externalTarget (a web resource + selector).

Anchor

Bases: Model

A layers anchor (the polymorphic attachment point).

Bases: Model

A layers alignmentLink (aligned token-index sets).

AnnotationMetadata

Bases: Model

A layers annotationMetadata (provenance for an annotation).

LayersConstraint

Bases: Model

A layers constraint (an expression with scope).

models_records

Faithful didactic mirrors of the linguistic layers record types.

Mirrors the expression, segmentation, annotation, graph, media, and ontology records field-for-field (reusing the shared-def mirrors in :mod:bead.interop.layers.models). Like the shared defs, they serialize to and from layers JSON losslessly through the generic snake<->camel conversion. Binary blob fields are mirrored as their reference string.

Expression

Bases: Model

A layers expression (a text/linguistic unit, recursively nested).

Token

Bases: Model

A layers token within a tokenization.

Tokenization

Bases: Model

A layers tokenization (one segmentation of an expression).

ArgumentRef

Bases: Model

A layers argumentRef (a role-filling argument of a predicate).

Annotation

Bases: Model

A layers annotation (the polymorphic annotation object).

Cluster

Bases: Model

A layers cluster (a coreference/equivalence set).

AnnotationLayer

Bases: Model

A layers annotationLayer (a typed layer of annotations).

GraphNode

Bases: Model

A layers graphNode (a standalone property-graph node).

GraphEdge

Bases: Model

A layers graphEdge (a single typed, directed edge record).

GraphEdgeEntry

Bases: Model

A layers graphEdgeEntry (one edge within a graphEdgeSet).

GraphEdgeSet

Bases: Model

A layers graphEdgeSet (a batch of typed, directed edges).

AudioInfo

Bases: Model

A layers audioInfo media descriptor.

VideoInfo

Bases: Model

A layers videoInfo media descriptor.

DocumentInfo

Bases: Model

A layers documentInfo media descriptor.

RoleSlot

Bases: Model

A layers roleSlot (a role in a type definition).

TypeDef

Bases: Model

A layers typeDef (an ontology type definition).

Generic mirror iso

model_lenses

Generic lossless isos between faithful mirror models and layers JSON.

A single :class:MirrorIso (parameterized by model type) serves every faithful mirror model, since they all serialize through the structural snake<->camel conversion in :mod:bead.interop.layers._mirror. SHARED_DEF_ISOS registers one iso per shared-def mirror so a coverage test can assert every construct has a law-passing mapping.

MirrorIso

Bases: Iso[T, JsonValue]

Lossless iso between a faithful mirror model and layers-shaped JSON.

forward(model: T) -> JsonValue

Serialize the mirror model to layers JSON.

backward(data: JsonValue) -> T

Deserialize layers JSON back into the mirror model.

mirror_iso(model_type: type[T]) -> MirrorIso[T]

Build a :class:MirrorIso for a mirror model type.