Integration ports¶

The stable protocols integrations bind to. Each port is a typing.Protocol. Codec, Exporter, and KnowledgeBase are generic over their concrete payload and return types; StorageBackend is non-generic and types its methods directly against str, bytes, and bool. Either way no method returns a widened type. Adapters bind a port to concrete didactic models and framework objects. For the design see Concepts > Integrations and ports.

lairs.integrations.ports.Codec ¶

Bases: Protocol

A bidirectional converter between an external format and lairs records.

A codec translates an external annotation format's spans and labels into lairs anchors and one of the seven annotation kinds; lairs owns the rest.

A codec is generic over the corpus-fragment model it produces and the record model it consumes, so neither method returns a widened type.

decode ¶

decode(
    src: str | bytes, *, into: Fragment | None = None
) -> Fragment

Decode an external source into a corpus fragment.

PARAMETER	DESCRIPTION
`src`	The external source (path text or raw bytes) to decode. TYPE: `str or bytes`
`into`	An existing corpus fragment to extend, if any. TYPE: `Fragment or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Fragment`	A corpus fragment of lairs records.

encode ¶

encode(records: Iterable[Record]) -> bytes | str

Encode lairs records into the external format.

PARAMETER	DESCRIPTION
`records`	The lairs records to encode. TYPE: `Iterable`

RETURNS	DESCRIPTION
`bytes or str`	The encoded external representation.

lairs.integrations.ports.Exporter ¶

Bases: Protocol

A data-plane exporter that emits a framework-native dataset.

An exporter consumes the flattened Arrow views plus the anchor resolver and produces a target-framework object (for example a datasets.Dataset or a torch.utils.data.Dataset). It is generic over the view, the export specification, and the framework object it returns.

export ¶

export(view: View, *, spec: Spec | None = None) -> T_co

Export an Arrow view into a framework-native dataset.

PARAMETER	DESCRIPTION
`view`	The Arrow view to export. TYPE: `View`
`spec`	An optional export specification (task template, columns). TYPE: `Spec or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`T_co`	A framework-native dataset object.

lairs.integrations.ports.KnowledgeBase ¶

Bases: Protocol

A connector to an external knowledge base.

Used to resolve, entity-link, reconcile, and enrich Layers records against external knowledge graphs and lexical resources. It is generic over the entity, candidate, and edge models it returns.

resolve ¶

resolve(ref: str) -> Entity

Resolve an identifier or URI to an entity.

PARAMETER	DESCRIPTION
`ref`	The external identifier or URI to resolve. TYPE: `str`

RETURNS	DESCRIPTION
`Entity`	The resolved entity (label, aliases, types, description, sameAs).

search ¶

search(
    text: str,
    *,
    lang: str | None = None,
    types: Sequence[str] | None = None,
) -> list[Candidate]

Search for candidate entities (entity linking / reconciliation).

PARAMETER	DESCRIPTION
`text`	The surface text to link. TYPE: `str`
`lang`	An optional language filter. TYPE: `str or None` DEFAULT: `None`
`types`	An optional set of type constraints. TYPE: `Sequence or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list`	A ranked list of candidate entities.

neighbors ¶

neighbors(
    ref: str, *, rels: Sequence[str] | None = None
) -> list[Edge]

Expand an entity's graph neighbourhood.

PARAMETER	DESCRIPTION
`ref`	The external identifier or URI to expand. TYPE: `str`
`rels`	An optional set of relation filters. TYPE: `Sequence or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list`	The neighbouring edges.

lairs.integrations.ports.StorageBackend ¶

Bases: Protocol

A pluggable storage backend for blobs and materialized views.

Used to back the blob cache and Parquet views with local or remote storage (for example an fsspec filesystem over s3, gcs, or local disk).

read_bytes ¶

read_bytes(key: str) -> bytes

Read an object's bytes by key.

PARAMETER	DESCRIPTION
`key`	The storage key to read. TYPE: `str`

RETURNS	DESCRIPTION
`bytes`	The object's bytes.

write_bytes ¶

write_bytes(key: str, data: bytes) -> None

Write an object's bytes by key.

PARAMETER	DESCRIPTION
`key`	The storage key to write. TYPE: `str`
`data`	The bytes to store. TYPE: `bytes`

exists ¶

exists(key: str) -> bool

Report whether a key exists.

PARAMETER	DESCRIPTION
`key`	The storage key to test. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	`True` if the key exists.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search