retriever-core 0.0.1__py3-none-any.whl

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,46 @@
+# Third-Party Notices
+
+Retriever vendors a small set of JavaScript assets so generated IR visualization
+HTML files can open offline. The runtime also references public CDN URLs for the
+same libraries when appropriate.
+
+## Cytoscape.js
+
+- Local file: `src/retriever/ir/assets/cytoscape.min.js`
+- Version used by CDN fallback: `3.26.0`
+- Upstream project: https://js.cytoscape.org/
+- License: MIT
+- Copyright: Copyright (c) 2016-2023, The Cytoscape Consortium.
+
+The bundled minified file includes the upstream MIT license notice.
+
+## Dagre
+
+- Local file: `src/retriever/ir/assets/dagre.min.js`
+- Version used by CDN fallback: `0.8.5`
+- Upstream project: https://github.com/dagrejs/dagre
+- License: MIT
+- Copyright: Copyright (c) 2012-2014 Chris Pettitt.
+
+The bundled minified file includes the upstream MIT license notice.
+
+## Graphlib
+
+- Local file: embedded inside `src/retriever/ir/assets/dagre.min.js`
+- Upstream project: https://github.com/dagrejs/graphlib
+- License: BSD-style license
+- Copyright: Copyright (c) 2014, Chris Pettitt.
+
+The bundled Dagre artifact includes Graphlib and its redistribution notice.
+
+## cytoscape-dagre
+
+- Local file: `src/retriever/ir/assets/cytoscape-dagre.min.js`
+- Version used by CDN fallback: `2.5.0`
+- Upstream package: https://www.npmjs.com/package/cytoscape-dagre
+- Source repository: https://github.com/cytoscape/cytoscape.js-dagre
+- License: MIT
+
+The local file was minified by jsDelivr from the upstream npm package. Keep this
+notice with the vendored artifact because the minified file itself only contains
+the jsDelivr minification header.

retriever/__init__.py

@@ -0,0 +1,196 @@
+"""Top-level convenience surface for Retriever.
+
+`retriever` re-exports the most common runtime/core entry points so notebooks and
+small scripts can stay terse. The preferred explicit surfaces still live in:
+
+- `retriever.flow` for authoring `Flow` and `Pipeline`
+- `retriever.rt` for backend execution
+- `retriever.registry` for discoverable flows, pipelines, and types
+- `retriever.types` for shared payload and contract definitions
+"""
+
+from importlib import import_module
+from importlib.metadata import (
+    PackageNotFoundError,
+    packages_distributions as _packages_distributions,
+    version as _package_version,
+)
+from types import ModuleType
+
+
+def _resolve_version() -> str:
+    # Resolve the version from whichever installed distribution provides the
+    # `retriever` import package, rather than assuming one dist name. Fall back
+    # to a source-tree marker when running uninstalled.
+    candidates: list[str] = []
+    try:
+        candidates = list(_packages_distributions().get("retriever", []))
+    except Exception:
+        candidates = []
+    for dist in [*candidates, "retriever-core"]:
+        try:
+            return _package_version(dist)
+        except PackageNotFoundError:
+            continue
+    return "0.0.0+local"
+
+
+__version__ = _resolve_version()
+
+from retriever.flow import Flow, Rate, Clock, Trigger, Hybrid, Tick
+from retriever.flow.adapter import Latest, Hold, Window, Events
+from retriever.flow.pipeline import (
+    Pipeline,
+    clear_default_pipeline,
+    connect,
+    default_pipeline,
+    reset_default_pipeline,
+    run,
+    step,
+    reset,
+    view,
+)
+from retriever.flow import io, TemporalFlow, PipelineBuilder, compose, select
+
+
+from typing import Any, Optional, Union
+from retriever.config import RecordConfig, VizConfig, _UNSET as _CONFIG_UNSET, set_global_config
+
+def init(
+    name: Optional[str] | object = _CONFIG_UNSET,
+    record: Optional[Union[str, RecordConfig]] | object = _CONFIG_UNSET,
+    backend: Optional[str] | object = _CONFIG_UNSET,
+    backend_config: Optional[dict] | object = _CONFIG_UNSET,
+    default_sync: Optional[Any] | object = _CONFIG_UNSET,
+    default_viz: Optional[VizConfig] | object = _CONFIG_UNSET,
+) -> None:
+    """
+    Set process-wide default configuration for convenience helpers.
+
+    `retriever.init(...)` only updates global defaults used by the thread-local
+    default pipeline and by `Pipeline.connect(...)` when `sync=` is omitted.
+    Pass `None` explicitly to clear optional defaults like `record`,
+    `default_sync`, or `default_viz`. It does not build, reset, or run a
+    pipeline by itself. For scripts and shared examples, prefer an explicit
+    `Pipeline(...)` object and pass runtime settings directly to `pipe.run(...)`.
+
+    Args:
+        name: Session name (useful for logging/recording)
+        record: Recording path (str) or configuration (RecordConfig)
+        backend: Default backend for `pipe.run()` / `retriever.run()`
+                 (e.g. "multiprocessing", "dora")
+        backend_config: Default backend configuration dict. Values are merged
+                        with (and overridden by) `pipe.run(backend_config=...)`.
+        default_sync: Default sync adapter for connections (e.g. Latest()).
+                      Pass None explicitly to clear it so every explicit connection
+                      must specify sync=.
+        default_viz: Default visualization policy for all output ports that do not
+                     have an explicit viz= on their .then() connection.
+                     Example: retriever.init(default_viz=VizConfig(hz=5.0))
+                     enables lightweight visualization across the whole pipeline.
+    """
+    set_global_config(
+        name=name,
+        record=record,
+        backend=backend,
+        backend_config=backend_config,
+        default_sync=default_sync,
+        default_viz=default_viz,
+    )
+
+
+
+# Registry Exports
+from retriever.registry import (
+    register_flow,
+    get_flow,
+    get_flow_class,
+    list_flows,
+    find_flows,
+    register_pipeline,
+    get_pipeline,
+    get_pipeline_factory,
+    list_pipelines,
+    find_pipelines,
+    build_ir,
+    build_pipeline_flow,
+    build_pipeline_surface,
+    get_type_info,
+    get_registered_types,
+    register_type,
+    get_type,
+    list_types,
+    find_types,
+    get_type_name,
+    resolve_schema_ref,
+)
+
+# Import built-in shared schema types so registry lookups are stable after plain `import retriever`.
+from retriever.types import ClockDomain as _ClockDomain, SchemaRef as _SchemaRef, StreamId as _StreamId  # noqa: F401
+# Import built-in domain typing packages so registry lookups are stable after plain `import retriever`.
+from retriever.types import data as _data  # noqa: F401
+from retriever.types import spatial as _spatial  # noqa: F401
+
+
+def __getattr__(name: str) -> ModuleType:
+    """Load optional top-level convenience modules on first access."""
+
+    if name == "hub":
+        module = import_module("retriever.hub")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "Flow",
+    "Rate",
+    "Clock",
+    "Trigger",
+    "Hybrid",
+    "Tick",
+    "Latest",
+    "Hold",
+    "Window",
+    "Events",
+    "Pipeline",
+    "connect",
+    "default_pipeline",
+    "reset_default_pipeline",
+    "clear_default_pipeline",
+    "run",
+    "step",
+    "reset",
+    "view",
+    "init",
+    "RecordConfig",
+    "VizConfig",
+    "io",
+    "compose",
+    "select",
+    "TemporalFlow",
+    "PipelineBuilder",
+    # Registry
+    "register_flow",
+    "get_flow",
+    "get_flow_class",
+    "list_flows",
+    "find_flows",
+    "register_pipeline",
+    "get_pipeline",
+    "get_pipeline_factory",
+    "list_pipelines",
+    "find_pipelines",
+    "build_ir",
+    "build_pipeline_flow",
+    "build_pipeline_surface",
+    "register_type",
+    "get_type",
+    "get_type_info",
+    "get_registered_types",
+    "get_type_name",
+    "list_types",
+    "find_types",
+    "resolve_schema_ref",
+    "hub",
+]

retriever/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Internal helper surface for Retriever implementation modules."""
+
+from .helpers import as_tagged, load_plugins, type_to_str
+
+__all__ = ["as_tagged", "load_plugins", "type_to_str"]

retriever/_internal/helpers.py

@@ -0,0 +1,113 @@
+"""
+Retriever utility functions.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, is_dataclass
+from importlib import metadata
+from typing import Any, Dict, Iterable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+# ============================================================
+# Plugin Loading
+# ============================================================
+
+_PLUGINS_LOADED = False
+
+
+def _iter_entry_points(group: str) -> Iterable[Any]:
+    """Iterate entry points for a given group across Python versions."""
+    eps = metadata.entry_points()
+    # Python 3.10+: EntryPoints has `.select`
+    if hasattr(eps, "select"):
+        return eps.select(group=group)  # type: ignore[attr-defined]
+    # Older: dict-like
+    return eps.get(group, [])  # type: ignore[return-value]
+
+
+def load_plugins(*, force: bool = False, group: str = "retriever.plugins") -> int:
+    """
+    Load plugins registered under the given entry point group.
+
+    Convention:
+      - Plugins are exposed via Python entry points under the group `retriever.plugins`
+      - Each entry point must resolve to a callable with signature `() -> None`
+        that performs registration (e.g., calls `register_pipeline(...)`).
+
+    Returns:
+        Number of successfully invoked plugin callables.
+    """
+    global _PLUGINS_LOADED
+    if _PLUGINS_LOADED and not force:
+        return 0
+
+    invoked = 0
+    for ep in _iter_entry_points(group):
+        try:
+            plugin = ep.load()
+        except Exception as e:
+            logger.warning("Failed to load plugin entry point '%s': %s", getattr(ep, "name", ep), e)
+            continue
+
+        if not callable(plugin):
+            logger.warning(
+                "Plugin entry point '%s' resolved to non-callable: %r",
+                getattr(ep, "name", ep),
+                plugin,
+            )
+            continue
+
+        try:
+            plugin()
+            invoked += 1
+        except Exception as e:
+            logger.warning("Plugin '%s' raised during registration: %s", getattr(ep, "name", ep), e)
+
+    _PLUGINS_LOADED = True
+    return invoked
+
+
+# ============================================================
+# Type Utilities
+# ============================================================
+
+
+def type_to_str(typ: type) -> str:
+    """
+    Convert Python type to string representation.
+
+    Args:
+        typ: Python type object
+
+    Returns:
+        String representation of type
+    """
+    if hasattr(typ, '__module__') and hasattr(typ, '__name__'):
+        if typ.__module__ == 'builtins':
+            return typ.__name__
+        return f"{typ.__module__}.{typ.__name__}"
+    return str(typ)
+
+
+def as_tagged(obj: T) -> Dict[str, Any]:
+    """
+    Convert dataclass to tagged dict format: {ClassName: {fields}}.
+
+    Used for polymorphic serialization with type discrimination.
+
+    Args:
+        obj: Dataclass instance
+
+    Returns:
+        Dict in format {ClassName: fields_dict}
+    """
+    if not is_dataclass(obj):
+        return obj
+    class_name = obj.__class__.__name__
+    fields = asdict(obj)
+    return {class_name: fields}