bead.interop¶

Lens between a CorpusGraph and the layers property graph.

The lens projects a :class:~bead.corpus.graph.CorpusGraph to a :class:CorpusGraphLayers view (a bundle of canonical :class:lairs.records.expression.Expression and :class:lairs.records.graph.GraphNode records plus a :class:lairs.records.graph.GraphEdgeSet) and keeps a complement holding the information layers' graph does not express directly (the bead framework identity, the bead node ids, edge directedness, and exact float confidence). Together the view and complement reconstruct the graph exactly.

Bridge lens between a bead CorpusRecord and a layers expression.

A :class:~bead.corpus.records.CorpusRecord projects to a canonical :class:lairs.records.expression.Expression; the lens complement holds the bead-only remainder (framework identity, the source name, and the record index, which layers has no slot for), so the round-trip is exact and the GetPut/PutGet laws hold.

Lossless iso between a dependency parse and layers annotation records.

A :class:~bead.tokenization.parsers.ParsedSentence maps to a :class:ParsedSentenceLayers view: a canonical :class:lairs.records.segmentation.Tokenization plus two :class:lairs.records.annotation.AnnotationLayer records (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 token has no spaceAfter slot, so each token's space-after flag travels in its part-of-speech annotation's features alongside the lemma, xpos, and morphology. The annotation layers require an expression reference and a timestamp that the parse does not carry; these are emitted as fixed constants and ignored on the way back.

Lens between a bead Item and canonical layers annotation records.

A bead :class:~bead.items.item.Item carries standoff span and relation annotations over one or more rendered elements. This lens projects an item to a :class:lairs.integrations.codecs.CorpusFragment of canonical lairs records:

• one :class:lairs.records.expression.Expression per rendered element,
• one :class:lairs.records.segmentation.Segmentation per tokenized element,
• one span :class:lairs.records.annotation.AnnotationLayer per element whose spans anchor by tokenRefSequence (head_index maps to anchorTokenIndex; a Wikidata label_id maps to a knowledgeRef),
• one relation AnnotationLayer whose annotations carry ArgumentRef source/target objectRef arguments.

The layers token has no space-after slot and an Item carries many fields layers cannot express, so the round-trip is a dx.Lens: the view captures the text, tokenization, and a faithful annotation projection; the complement carries the bead-only remainder (framework identity, the item-construction fields, the space-after flags, and the spans and relations verbatim), so the GetPut/PutGet laws hold for every item.

Lenses between bead resource models and layers resource records.

Maps bead's lexical and template resources to their canonical :mod:lairs.records.resource counterparts:

• LexicalItem <-> a layers entry
• Lexicon <-> a layers collection with its entry records
• Template <-> a layers template (with its slots and constraints)
• FilledTemplate <-> a layers filling (with its per-slot fillings)

Each lens produces a layers-shaped view from the generated models and keeps the fields that have no layers equivalent (the bead framework identity, tags, the LexicalItem original form / free-text source, the bead DSL constraint context, and the filled-template slot requirement map) in the lens complement, so reconstruction is exact.

Lenses between bead annotation records and layers judgment records.

Maps bead's reliability inputs to their canonical :mod:lairs.records.judgment counterparts:

• AnnotationRecord <-> a layers judgment
• a tuple of AnnotationRecord sharing one annotator <-> a layers judgmentSet

A single layers judgment has no slot for the annotator or the question name; those belong to the parent judgmentSet and experiment. The lens therefore keeps the bead framework identity, the annotator id, the question name, and the raw item id / response label in the lens complement so reconstruction is exact. The aggregate is modelled as two plain functions (a tuple is not a single dx.Model), each one delegating to the per-record lens so every record round-trips exactly.

Lenses between bead list-composition models and layers judgment records.

Maps bead's experimental list models to their canonical :mod:lairs.records counterparts:

• ListConstraint <-> a layers listConstraint (judgment.ListConstraint)
• ExperimentList <-> a layers collection with its collectionMembership records and per-list listConstraint records, bundled as the bead-side :class:ExperimentListLayers aggregate view

The bead ListConstraint union is far richer than the four scalar fields of the layers listConstraint record, so the lens carries the entire bead constraint (serialized with model_dump_json) in the lens complement and reconstructs the exact subclass with ListConstraint.model_validate_json on the way back. The ExperimentList lens keeps the bead framework identity, the numeric list id, the ordered item references, the presentation order, the list and balance metadata, the per-constraint satisfaction records, and the per-constraint complements in its own complement, so reconstruction is exact.

A lairs codec that round-trips a bead ItemCollection.

:class:BeadCodec binds the :class:lairs.integrations.ports.Codec port so a downstream user can reach it through lairs.codec("bead") once both packages are installed (the codec is registered via the lairs.codecs entry point in bead's project metadata).

The codec's external format is a bead ItemCollection serialized as JSON. decode runs each item through :data:~bead.interop.layers.item_bridge.ITEM_LAYERS and concatenates the resulting canonical layers records, threading each item's lens complement and the collection's own fields as private records under the bead.interop.complement NSID (a layers consumer ignores unknown NSIDs). Because the complement rides along, encode(decode(x)) == x holds losslessly for every collection, and a single canonical mapping (the lens) drives both directions.

Ingest a layers Corpus into bead models and emit bead data as a corpus.

Ingest (layers to bead):

• :func:expression_to_record / :func:corpus_to_records stream a corpus's expressions as :class:~bead.corpus.records.CorpusRecord instances.
• :func:corpus_to_graph builds a :class:~bead.corpus.graph.CorpusGraph from a corpus, deriving a parent edge from each expression's parentRef.
• :func:corpus_to_items reconstructs best-effort :class:~bead.items.item.Item instances from a corpus's span and relation annotation layers.
• :func:load_layers_corpus is a thin wrapper over :func:lairs.load_corpus.

Egress (bead to layers):

• :func:items_to_corpus and :func:graph_to_corpus build a :class:lairs.data.Corpus from bead data, reusing the canonical lenses.
• :func:materialize_corpus, :func:save_corpus_repo, and :func:publish_corpus delegate to the corresponding lairs store and publish entry points; the network-bound publish path is opt-in and defaults to a dry run.