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)

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, and the bead DSL constraint context) in the lens 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.