Registry

nlql.registry —— 统一能力注册中心：function / splitter / embedder / modality 走同一 Registry 协议，支持父子链作用域。GLOBAL_REGISTRY 在 import 时种入内置算子。

registry

Unified capability registry.

Importing this package seeds the built-in functions into :data:GLOBAL_REGISTRY.

CAPABILITY_KINDS module-attribute

CAPABILITY_KINDS = frozenset({'function', 'splitter', 'embedder', 'modality'})

GLOBAL_REGISTRY module-attribute

GLOBAL_REGISTRY = Registry()

__all__ module-attribute

__all__ = ['Registry', 'Capability', 'CAPABILITY_KINDS', 'GLOBAL_REGISTRY', 'register_function', 'register_splitter']

Capability dataclass

Capability(kind: str, name: str, impl: Any = None, signature: Signature | None = None, provides_score: bool = False, pushdownable: bool = False, doc: str | None = None)

A single registered extension point.

参数：

名称	类型	描述	默认
kind	str	One of :data:CAPABILITY_KINDS.	必需
name	str	Display name (lookup is case-insensitive).	必需
impl	Any	The implementation object (callable, splitter fn, embedder, …). May be None for provider-backed functions whose value comes from another stage.	None
signature	Signature | None	Optional declared types, used for arity/type checks and pushdown.	None
provides_score	bool	When True this is a function whose value is supplied by the recall stage and read from Unit.scores (e.g. SIMILARITY) — it is not invoked row-by-row.	False
pushdownable	bool	Hint to the Planner that this capability can be translated to an external store's native query (used in M2).	False
doc	str | None	Human-readable description.	None

kind instance-attribute

kind: str

name instance-attribute

name: str

impl class-attribute instance-attribute

impl: Any = None

signature class-attribute instance-attribute

signature: Signature | None = None

provides_score class-attribute instance-attribute

provides_score: bool = False

pushdownable class-attribute instance-attribute

pushdownable: bool = False

doc class-attribute instance-attribute

doc: str | None = None

Registry

Registry(parent: Registry | None = None)

A capability registry, optionally chained to a parent for scoped overrides.

源代码位于： src/nlql/registry/core.py

def __init__(self, parent: Registry | None = None) -> None:
    self._parent = parent
    self._caps: dict[tuple[str, str], Capability] = {}

register

register(kind: str, name: str, impl: Any = None, *, signature: Signature | None = None, provides_score: bool = False, pushdownable: bool = False, doc: str | None = None, overwrite: bool = False) -> Capability

Register a capability into this registry.

引发：

类型	描述
NLQLRegistryError	on unknown kind, empty name, or a same-registry name clash without overwrite=True. (Shadowing a parent entry is never a clash — that is how instance overrides work.)

源代码位于： src/nlql/registry/core.py

def register(
    self,
    kind: str,
    name: str,
    impl: Any = None,
    *,
    signature: Signature | None = None,
    provides_score: bool = False,
    pushdownable: bool = False,
    doc: str | None = None,
    overwrite: bool = False,
) -> Capability:
    """Register a capability into *this* registry.

    Raises:
        NLQLRegistryError: on unknown ``kind``, empty ``name``, or a same-registry
            name clash without ``overwrite=True``. (Shadowing a *parent* entry is
            never a clash — that is how instance overrides work.)
    """
    if kind not in CAPABILITY_KINDS:
        raise NLQLRegistryError(
            f"Unknown capability kind {kind!r}; expected one of {sorted(CAPABILITY_KINDS)}"
        )
    if not name or not name.strip():
        raise NLQLRegistryError("Capability name must be a non-empty string")
    key = self._key(kind, name)
    if key in self._caps and not overwrite:
        raise NLQLRegistryError(
            f"{kind} {name!r} already registered in this registry; pass overwrite=True to replace"
        )
    cap = Capability(
        kind=kind,
        name=name,
        impl=impl,
        signature=signature,
        provides_score=provides_score,
        pushdownable=pushdownable,
        doc=doc,
    )
    self._caps[key] = cap
    return cap

get

get(kind: str, name: str) -> Capability | None

Resolve a capability, checking this registry then its parent chain.

源代码位于： src/nlql/registry/core.py

def get(self, kind: str, name: str) -> Capability | None:
    """Resolve a capability, checking this registry then its parent chain."""
    cap = self._caps.get(self._key(kind, name))
    if cap is not None:
        return cap
    if self._parent is not None:
        return self._parent.get(kind, name)
    return None

has

has(kind: str, name: str) -> bool

源代码位于： src/nlql/registry/core.py

def has(self, kind: str, name: str) -> bool:
    return self.get(kind, name) is not None

names

names(kind: str) -> list[str]

All capability names of kind visible here (child shadows parent).

源代码位于： src/nlql/registry/core.py

def names(self, kind: str) -> list[str]:
    """All capability names of ``kind`` visible here (child shadows parent)."""
    merged: dict[str, str] = {}
    if self._parent is not None:
        for n in self._parent.names(kind):
            merged[n.upper()] = n
    for (k, up), cap in self._caps.items():
        if k == kind:
            merged[up] = cap.name
    return sorted(merged.values())

child

child() -> Registry

Create an instance-scoped registry that overrides this one.

源代码位于： src/nlql/registry/core.py

def child(self) -> Registry:
    """Create an instance-scoped registry that overrides this one."""
    return Registry(parent=self)

function

function(name: str, *, signature: Signature | None = None, provides_score: bool = False, pushdownable: bool = False, doc: str | None = None, overwrite: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Decorator registering a scalar/predicate function.

源代码位于： src/nlql/registry/core.py

def function(
    self,
    name: str,
    *,
    signature: Signature | None = None,
    provides_score: bool = False,
    pushdownable: bool = False,
    doc: str | None = None,
    overwrite: bool = False,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Decorator registering a scalar/predicate function."""

    def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
        self.register(
            "function",
            name,
            fn,
            signature=signature,
            provides_score=provides_score,
            pushdownable=pushdownable,
            doc=doc or fn.__doc__,
            overwrite=overwrite,
        )
        return fn

    return deco

splitter

splitter(name: str, *, overwrite: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Decorator registering a text splitter (str -> list[str]).

源代码位于： src/nlql/registry/core.py

def splitter(
    self, name: str, *, overwrite: bool = False
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Decorator registering a text splitter (``str -> list[str]``)."""

    def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
        self.register("splitter", name, fn, doc=fn.__doc__, overwrite=overwrite)
        return fn

    return deco

embedder

embedder(name: str, *, overwrite: bool = False) -> Callable[[Any], Any]

Decorator/registrar for an embedder instance or class.

源代码位于： src/nlql/registry/core.py

def embedder(
    self, name: str, *, overwrite: bool = False
) -> Callable[[Any], Any]:
    """Decorator/registrar for an embedder instance or class."""

    def deco(obj: Any) -> Any:
        self.register("embedder", name, obj, overwrite=overwrite)
        return obj

    return deco

register_function

register_function(name: str, *, signature: Signature | None = None, provides_score: bool = False, pushdownable: bool = False, doc: str | None = None, overwrite: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Register a function into the process-wide :data:GLOBAL_REGISTRY.

源代码位于： src/nlql/registry/core.py

def register_function(
    name: str,
    *,
    signature: Signature | None = None,
    provides_score: bool = False,
    pushdownable: bool = False,
    doc: str | None = None,
    overwrite: bool = False,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Register a function into the process-wide :data:`GLOBAL_REGISTRY`."""
    return GLOBAL_REGISTRY.function(
        name,
        signature=signature,
        provides_score=provides_score,
        pushdownable=pushdownable,
        doc=doc,
        overwrite=overwrite,
    )

register_splitter

register_splitter(name: str, *, overwrite: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Register a splitter into the process-wide :data:GLOBAL_REGISTRY.

源代码位于： src/nlql/registry/core.py

def register_splitter(
    name: str, *, overwrite: bool = False
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Register a splitter into the process-wide :data:`GLOBAL_REGISTRY`."""
    return GLOBAL_REGISTRY.splitter(name, overwrite=overwrite)