open-kgo 0.2.1__py3-none-any.whl

open_kgo/compute_frameworks/__init__.py

@@ -0,0 +1,16 @@
+"""Compute frameworks for open-kgo.
+
+Currently holds ``KgPythonDictFramework`` (``python_dict_kg_framework.py``), the
+KG-aware ``PythonDictFramework`` adapter that wraps native KG rows as
+``{feature_name: row}`` before column slicing. It is pinned by
+``open_kgo.feature_groups.kg.base.KgConnectorFeatureGroupBase.compute_framework_rule``
+so every KG FeatureGroup runs through it by default.
+
+Re-exported at the package root so it is discoverable straight from
+``compute_frameworks`` (``from open_kgo.compute_frameworks import
+KgPythonDictFramework``) without reaching into the submodule.
+"""
+
+from open_kgo.compute_frameworks.python_dict_kg_framework import KgPythonDictFramework
+
+__all__ = ["KgPythonDictFramework"]

open_kgo/compute_frameworks/python_dict_kg_framework.py

@@ -0,0 +1,93 @@
+"""KG-aware adapter over ``PythonDictFramework``.
+
+Native KG rows (SPARQL bindings, Cypher rows, REST records, BFS hops, ...)
+have their own keys (``s``, ``p``, ``o``, ``name``, ``ancestor``, ...) — none
+of which match the user-defined feature name. ``PythonDictFramework`` matches
+columns by feature-name presence in each row (see
+``select_data_by_column_names`` in
+``mloda_plugins.compute_framework.base_implementations.python_dict``), so an
+unmatched feature would yield ``[{}, {}, ...]`` and silently lose every row.
+
+The wrap that satisfies that contract used to live on the universal
+``KgConnectorReaderBase.load``, which made the framework-matching strategy
+leak into every reader regardless of compute framework. This adapter moves
+the wrap into a ``PythonDictFramework`` subclass that owns it as an internal
+concern: ``load_data`` returns native KG rows; this framework wraps them as
+``{feature_name: row}`` immediately before column slicing. Other compute
+frameworks never see the wrap.
+
+Pinned by ``KgConnectorFeatureGroupBase.compute_framework_rule`` so every KG
+FeatureGroup runs through this adapter by default.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from mloda.user import FeatureName
+from mloda_plugins.compute_framework.base_implementations.python_dict.python_dict_framework import (
+    PythonDictFramework,
+)
+
+
+class KgPythonDictFramework(PythonDictFramework):
+    """``PythonDictFramework`` that wraps native KG rows under the requested feature name.
+
+    Mirrors the prior universal-base behavior: every row is wrapped as
+    ``{feature_name: row}`` before column slicing, regardless of whether
+    ``feature_name`` already appears as a key in the row. Wrapping
+    unconditionally preserves the historical contract, a row whose own keys
+    happen to collide with the feature name still loses access to the
+    colliding key, but that was already the case under the prior wrap and
+    changing it here would be a silent semantic shift.
+
+    The parent's ``identify_naming_convention`` hook (which supports the
+    ``feature_name~suffix`` multi-column pattern) is intentionally bypassed:
+    after the wrap, every row has exactly one key, the feature name, so
+    convention-based suffix matching has nothing to expand against. Native KG
+    rows have their own keys (``s``, ``p``, ``o``, ...) that never match the
+    user-defined feature name with or without suffixes, so this restriction
+    matches existing reality. KG features that need the suffix pattern would
+    need a different adapter; surfacing that explicitly is preferable to
+    silent loss.
+
+    Empty results are returned as ``[]`` instead of raising. The
+    parent ``PythonDictFramework`` treats ``[]`` as fatal because for tabular
+    data an empty selection is usually a schema-discovery failure (no rows
+    means no column types to infer, no naming convention to expand). KG
+    semantics are different: a SPARQL ``SELECT`` with no matches, a citation
+    lookup against an unknown ``stable_id``, an ``agent_memory`` query that
+    finds nothing, or a ``saas_authz`` filter that excludes every tuple all
+    legitimately return zero rows. Forcing those onto the parent's
+    "empty is fatal" path made ``mloda.run_all`` hostile to data users with
+    real empty-result queries (the prior workaround had to bypass the run
+    entirely). The cardinality and ``column_ordering`` guards still fire
+    even on empty data, because those are caller-shape bugs that are
+    orthogonal to row count.
+    """
+
+    def select_data_by_column_names(
+        self,
+        data: list[dict[str, Any]],
+        selected_feature_names: set[FeatureName],
+        column_ordering: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        if len(selected_feature_names) != 1:
+            raise ValueError(
+                f"{type(self).__name__}.select_data_by_column_names expects exactly one feature per call "
+                f"(KG concrete load_data implementations all dispatch one feature at a time); "
+                f"the reader's ``load`` should reject this earlier, this branch is defense-in-depth. "
+                f"Got {sorted(str(n) for n in selected_feature_names)}."
+            )
+
+        if column_ordering is not None:
+            raise ValueError(
+                f"{type(self).__name__} does not honor column_ordering "
+                f"(single-feature wrap has no ordering to apply); got {column_ordering!r}."
+            )
+
+        if not data:
+            return []
+
+        feature_name = str(next(iter(selected_feature_names)))
+        return [{feature_name: row} for row in data]

open_kgo/compute_frameworks/tests/test_python_dict_kg_framework.py

@@ -0,0 +1,111 @@
+"""Direct unit tests for ``KgPythonDictFramework``.
+
+The KG-aware ``PythonDictFramework`` adapter wraps native KG rows under the
+requested feature name during column slicing, so the wrap-for-column-matching
+strategy lives in a framework-specific layer instead of leaking into the
+universal ``KgConnectorReaderBase.load``. These tests pin down the adapter's
+public behaviour independently of any concrete connector.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from mloda.core.abstract_plugins.components.parallelization_modes import ParallelizationMode
+from mloda.user import FeatureName
+
+from open_kgo.compute_frameworks.python_dict_kg_framework import KgPythonDictFramework
+
+
+def _make_framework() -> KgPythonDictFramework:
+    """Construct an instance with the bare minimum mloda runtime args.
+
+    Tracks ``ComputeFramework.__init__`` (private mloda surface): currently
+    requires ``mode`` and ``children_if_root``. These tests exercise pure
+    data-shaping behaviour, not parallelization or DAG wiring, so any sync
+    mode and an empty children set suffice. If mloda renames either kwarg or
+    adds a required one, every test here fails together — fix the helper.
+    """
+    return KgPythonDictFramework(mode=ParallelizationMode.SYNC, children_if_root=frozenset())
+
+
+def test_select_data_wraps_native_rows_under_feature_name() -> None:
+    """Each native row is returned as ``{feature_name: row}``."""
+    fw = _make_framework()
+    native_rows = [{"s": "x", "p": "y", "o": "z"}, {"s": "a", "p": "b", "o": "c"}]
+    result = fw.select_data_by_column_names(native_rows, {FeatureName("my_feature")})
+    assert result == [
+        {"my_feature": {"s": "x", "p": "y", "o": "z"}},
+        {"my_feature": {"s": "a", "p": "b", "o": "c"}},
+    ]
+
+
+def test_select_data_wrap_is_unconditional_even_when_feature_name_collides() -> None:
+    """Wrap mirrors the prior ``KgConnectorReaderBase.load`` semantics: always wrap.
+
+    Conditional wrapping (skip when the feature name already appears as a
+    row key) would silently change behaviour for the rare collision case.
+    Wrapping unconditionally preserves the historical contract.
+    """
+    fw = _make_framework()
+    rows = [{"my_feature": "shadowed", "other": 1}]
+    result = fw.select_data_by_column_names(rows, {FeatureName("my_feature")})
+    assert result == [{"my_feature": {"my_feature": "shadowed", "other": 1}}]
+
+
+def test_select_data_rejects_multi_feature_call() -> None:
+    """Adapter mirrors the reader's single-feature contract.
+
+    KG readers dispatch one feature at a time; passing two feature names to
+    the framework's column slicer would silently pick one. Reject loudly.
+    """
+    fw = _make_framework()
+    with pytest.raises(ValueError):
+        fw.select_data_by_column_names([{"a": 1}], {FeatureName("feat_a"), FeatureName("feat_b")})
+
+
+def test_select_data_returns_empty_list_for_empty_input() -> None:
+    """Empty input returns ``[]``.
+
+    The parent ``PythonDictFramework`` raises on ``[]`` because for tabular
+    data an empty selection is usually a schema-discovery failure. KG
+    semantics differ: a query with no matches is a legitimate outcome, so
+    the adapter relaxes the parent's "empty is fatal" guard. The
+    cardinality and ``column_ordering`` guards are orthogonal and still
+    fire (see the dedicated tests below); this test only pins the
+    relaxation on the data dimension.
+    """
+    fw = _make_framework()
+    result = fw.select_data_by_column_names([], {FeatureName("my_feature")})
+    assert result == []
+
+
+def test_select_data_empty_input_still_rejects_multi_feature_call() -> None:
+    """Cardinality guard fires even on ``[]`` (caller-shape bug is orthogonal to row count)."""
+    fw = _make_framework()
+    with pytest.raises(ValueError):
+        fw.select_data_by_column_names([], {FeatureName("feat_a"), FeatureName("feat_b")})
+
+
+def test_select_data_empty_input_still_rejects_column_ordering() -> None:
+    """``column_ordering`` guard fires even on ``[]`` (caller-shape bug is orthogonal to row count)."""
+    fw = _make_framework()
+    with pytest.raises(ValueError):
+        fw.select_data_by_column_names([], {FeatureName("my_feature")}, column_ordering="alphabetical")
+
+
+def test_select_data_rejects_column_ordering() -> None:
+    """``column_ordering`` is meaningless for a single-feature wrap; reject loudly.
+
+    The parent ``PythonDictFramework`` honors ``column_ordering`` via
+    ``identify_naming_convention``. The KG adapter bypasses that hook because
+    each wrapped row has exactly one key (the feature name). Silently
+    accepting the parameter would be a lie about supported semantics.
+    """
+    fw = _make_framework()
+    with pytest.raises(ValueError):
+        fw.select_data_by_column_names(
+            [{"a": 1}],
+            {FeatureName("my_feature")},
+            column_ordering="alphabetical",
+        )

open_kgo/extenders/__init__.py

@@ -0,0 +1 @@
+"""Extenders namespace package."""

open_kgo/feature_groups/__init__.py

@@ -0,0 +1 @@
+"""Feature groups namespace package."""

open_kgo/feature_groups/kg/__init__.py

@@ -0,0 +1,7 @@
+"""Knowledge-graph connector base groups (prototype).
+
+Validates the property layout from `docs/kg-connector-base-classes.md` Version B
+against in-memory libraries and Python prototype implementations. No Docker, no
+external services. See `docs/kg-connector-config-examples.md` for credential
+shapes per family.
+"""

open_kgo/feature_groups/kg/agent_memory/__init__.py

@@ -0,0 +1,33 @@
+"""LLM agent memory / GraphRAG KG connectors (Letta, Zep+Graphiti, Mem0, ...).
+
+Hidden-KG family with bi-temporal semantics. Required-with-at-least-one
+``memory_scope_*`` family of properties; ``valid_at_range`` /
+``invalid_at_range`` / ``reference_time`` for bi-temporal queries; lexical and
+graph retrieval modes are implemented (vector / hybrid remain unimplemented).
+
+PROTOTYPE NOTE: ``NetworkxMemoryReader`` loads its in-process substrate from
+a JSON fixture pointed to by the ``locator`` credential slot
+(``tests/fixtures/memories.json`` ships ``user_42``). A
+``memory_scope_user_id`` value absent from the fixture raises
+``UnknownMemoryScopeError`` at ``connect()`` time rather than silently
+returning an empty graph; an unreadable / malformed locator raises
+``FixtureLoadError``. The concrete reader narrows the family-level
+``REQUIRED_KEYS`` to ``("memory_scope_user_id",)`` because the fixture
+format is keyed by user_id only — the other ``memory_scope_*`` aliases
+live on the family base for future concrete readers (Mem0, Zep+Graphiti,
+Letta) that own their own per-tenant stores.
+
+PROTOTYPE NOTE: ``retrieval_mode`` is strict-validated against
+``{lexical, vector, hybrid, graph}``. ``NetworkxMemoryReader`` narrows it to
+``lexical`` (string-match over node labels); ``GraphWalkMemoryReader``
+narrows it to ``graph`` (BFS from a seed node id given as ``query_text``).
+``vector`` / ``hybrid`` remain unimplemented and are rejected at
+``is_valid_credentials`` time via ``SUPPORTED_VALUES`` on each concrete.
+``SUPPORTED_VALUES`` only validates keys present in the slot, and the family
+default is ``lexical``, so ``GraphWalkMemoryReader`` additionally lists
+``retrieval_mode`` in ``REQUIRED_KEYS``: omitting the key (which would
+silently default to the un-honored ``lexical``) is rejected at
+``is_valid_credentials`` time as well. Together the two layers ensure neither
+reader lies about what it honors (``NetworkxMemoryReader`` honors the family
+default, so omission is safe there and the key stays optional).
+"""

open_kgo/feature_groups/kg/agent_memory/base.py

@@ -0,0 +1,102 @@
+"""Family base for agent memory / GraphRAG connectors."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from open_kgo.feature_groups.kg.base import KgConnectorFeatureGroupBase, QueryReader
+from open_kgo.feature_groups.kg.mixins import PaginationMixin
+from open_kgo.feature_groups.kg.spec import property_spec
+
+
+_RETRIEVAL_MODES: dict[str, str] = {
+    "lexical": "BM25-style lexical search.",
+    "vector": "Embedding similarity search.",
+    "hybrid": "Combined lexical + vector with mmr_lambda blend.",
+    "graph": "Pure graph-walk retrieval.",
+}
+
+
+# Single source of truth for the memory-scope key family. Drives both
+# ``MEMORY_SCOPE_KEYS`` and the property-mapping entries below, so renaming
+# or extending the scope happens in exactly one place.
+#
+# Note on consumers: the existing ``NetworkxMemoryReader`` narrows
+# ``REQUIRED_KEYS`` to ``("memory_scope_user_id",)`` only — its JSON fixture
+# is keyed by user_id and the other scope aliases would silently no-op. The
+# canonical OR-group ``MEMORY_SCOPE_KEYS`` is reserved for future concretes
+# (Mem0, Letta, Zep+Graphiti) whose backends honor the full scope; keeping
+# the constant exported documents that contract for the family.
+#
+# Uniformity assumption: every scope key gets ``context=True`` and
+# ``strict_validation=False``. The first scope key that needs a different
+# pair (e.g. ``strict_validation=True`` for an enum scope) will force this
+# tuple shape to grow — at that point switch to a per-key spec dict
+# constant rather than threading more positional fields through.
+_MEMORY_SCOPE_SPECS: tuple[tuple[str, str, None | tuple[()]], ...] = (
+    ("memory_scope_user_id", "User identifier scope (Mem0 user_id, Letta user_id).", None),
+    ("memory_scope_agent_id", "Agent identifier scope.", None),
+    ("memory_scope_session_id", "Session identifier scope (e.g. LangGraph thread_id).", None),
+    ("memory_scope_run_id", "Run identifier scope.", None),
+    ("memory_scope_group_ids", "Graphiti-style group_ids (list).", ()),
+)
+
+MEMORY_SCOPE_KEYS: tuple[str, ...] = tuple(name for name, _, _ in _MEMORY_SCOPE_SPECS)
+
+_MEMORY_SCOPE_PROPERTY_MAPPING: dict[str, Any] = {
+    name: property_spec(explanation, default=default) for name, explanation, default in _MEMORY_SCOPE_SPECS
+}
+
+_FAMILY_PROPERTIES: dict[str, Any] = {
+    **_MEMORY_SCOPE_PROPERTY_MAPPING,
+    "reference_time": property_spec(
+        "Bi-temporal reference time (ISO 8601).",
+    ),
+    "valid_at_range": property_spec(
+        "[start, end] for valid_at filter.",
+        default=(),
+    ),
+    "invalid_at_range": property_spec(
+        "[start, end] for invalid_at filter.",
+        default=(),
+    ),
+    "retrieval_mode": property_spec(
+        "Retrieval strategy used to score candidate memories.",
+        strict=True,
+        allowed_values=_RETRIEVAL_MODES,
+        default="lexical",
+    ),
+    "mmr_lambda": property_spec(
+        "MMR lambda for hybrid retrieval blend (0.0-1.0).",
+        default=0.5,
+    ),
+    "threshold": property_spec(
+        "Similarity threshold (0.0-1.0).",
+        default=0.0,
+    ),
+}
+
+
+class AgentMemoryReader(PaginationMixin, QueryReader, family_properties=_FAMILY_PROPERTIES):
+    # Honest surface (option 3, see base.py): forward-compat GraphRAG menu the
+    # in-process concretes don't read (alternate scope aliases, bi-temporal and
+    # scoring knobs, pagination), reserved for future backends (Mem0, Letta,
+    # Zep). ``valid_at_range`` is waived per-concrete on GraphWalkMemoryReader,
+    # since the lexical sibling reads it.
+    _WAIVED_UNCONSUMED_KEYS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "page_size",
+            "memory_scope_agent_id",
+            "memory_scope_session_id",
+            "memory_scope_run_id",
+            "memory_scope_group_ids",
+            "reference_time",
+            "invalid_at_range",
+            "mmr_lambda",
+            "threshold",
+        }
+    )
+
+
+class AgentMemoryFeatureGroup(KgConnectorFeatureGroupBase):
+    READER_CLASS = None

open_kgo/feature_groups/kg/agent_memory/graph_walk_memory.py

@@ -0,0 +1,111 @@
+"""NetworkX-backed graph-walk agent memory store.
+
+Second concrete in the ``agent_memory`` family alongside ``NetworkxMemoryReader``
+(lexical search). This reader implements ``retrieval_mode=graph`` — the pure
+graph-walk retrieval branch the lexical concrete narrows away — by treating the
+``query_text`` as a seed node id and returning the memories reachable from it
+(BFS over the directed memory graph). It is the family's proof that the
+``retrieval_mode`` enum's ``graph`` value is real, and it adds no new dependency
+(NetworkX is already a family dependency).
+
+Memory data is loaded from a JSON file at ``locator`` (shape:
+``{user_id: {"nodes": [...], "edges": [...]}}``), the same shape the lexical
+concrete consumes. ``retrieval_mode`` is narrowed to ``graph`` and
+``pagination_style`` to ``none`` via ``SUPPORTED_VALUES``; ``retrieval_mode``
+is additionally listed in ``REQUIRED_KEYS`` because the family default is
+``lexical`` (a value this reader does not honor) and ``SUPPORTED_VALUES``
+only checks keys present in the slot, so an omitted ``retrieval_mode`` would
+otherwise validate and silently run graph retrieval under a defaulted
+``lexical`` label.
+
+The family-level bi-temporal keys (``valid_at_range`` / ``invalid_at_range`` /
+``reference_time``) are ACCEPTED but NOT APPLIED by this graph-walk concrete:
+the BFS returns reachable memories regardless of temporal validity. The lexical
+sibling (``NetworkxMemoryReader``) honors ``valid_at_range``; this one does not
+yet. This mirrors how the family base documents the ``memory_scope_*`` aliases
+as accepted-but-no-op until a concrete owns the corresponding store.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Mapping
+
+import networkx as nx
+
+from mloda.core.abstract_plugins.components.feature_set import FeatureSet
+
+from open_kgo.feature_groups.kg.agent_memory.base import (
+    AgentMemoryFeatureGroup,
+    AgentMemoryReader,
+)
+from open_kgo.feature_groups.kg.agent_memory.shared import build_memory_graph, validate_user_data
+from open_kgo.feature_groups.kg.base import LoadContext
+from open_kgo.feature_groups.kg.errors import UnknownMemoryScopeError
+from open_kgo.feature_groups.kg.fixtures import load_json_fixture
+from open_kgo.feature_groups.kg.traversal import bfs_collect_ids
+
+
+class GraphWalkMemoryReader(AgentMemoryReader):
+    CONNECTOR_ID: ClassVar[str] = "graph_walk_memory"
+    # retrieval_mode is REQUIRED (not just narrowed): the family default is
+    # "lexical", which this reader does not honor, and SUPPORTED_VALUES only
+    # validates keys present in the slot. An omitted retrieval_mode would
+    # otherwise pass is_valid_credentials and silently run graph retrieval
+    # under a defaulted "lexical" label.
+    REQUIRED_KEYS: ClassVar[tuple[tuple[str, ...], ...]] = (
+        ("locator",),
+        ("memory_scope_user_id",),
+        ("retrieval_mode",),
+    )
+    SUPPORTED_VALUES: ClassVar[Mapping[str, frozenset[Any]]] = {
+        "pagination_style": frozenset({"none"}),
+        "retrieval_mode": frozenset({"graph"}),
+    }
+    # Honest surface (option 3, see base.py): the BFS walk ignores temporal
+    # validity, so ``valid_at_range`` is accepted but not applied here (the
+    # lexical sibling reads it; the family base waives the rest).
+    _WAIVED_UNCONSUMED_KEYS: ClassVar[frozenset[str]] = frozenset({"valid_at_range"})
+
+    @classmethod
+    def _connect_from_slot(cls, slot: Mapping[str, Any]) -> nx.MultiDiGraph:
+        locator = str(slot["locator"])
+        store = load_json_fixture(cls.CONNECTOR_ID, locator)
+        user_id = str(slot["memory_scope_user_id"])
+        if user_id not in store:
+            raise UnknownMemoryScopeError(cls.CONNECTOR_ID, user_id)
+        # require_graph_integrity: this concrete's rows come straight from the
+        # BFS walk, so dangling edge endpoints must be rejected at connect time.
+        user_data = validate_user_data(cls.CONNECTOR_ID, locator, user_id, store[user_id], require_graph_integrity=True)
+        return build_memory_graph(user_data)
+
+    @classmethod
+    def build_query(cls, features: FeatureSet) -> str:
+        feature = next(iter(features.features))
+        text = feature.options.get("query_text")
+        if not isinstance(text, str) or not text.strip():
+            raise ValueError(f"{cls.CONNECTOR_ID}: 'query_text' (the seed node id) is required.")
+        # Return the stripped seed: validation already requires non-whitespace
+        # content, and an unstripped "  m1 " would validate here yet match no
+        # node in the walk, silently returning [].
+        return text.strip()
+
+    @classmethod
+    def _load_rows(cls, ctx: LoadContext, connection: Any, features: FeatureSet) -> list[dict[str, Any]]:
+        graph = connection
+        seed = cls.build_query(features)
+
+        # BFS over reachable memories (depth-unbounded); short-circuits at
+        # result_limit so the cap bounds the walk rather than slicing a
+        # fully-expanded reachable set. A seed absent from the graph yields
+        # an empty walk (the contains gate skips it without expanding).
+        collected = bfs_collect_ids(
+            lambda node_id: node_id in graph,
+            graph.successors,
+            seed,
+            max_nodes=ctx.result_limit,
+        )
+        return [{"id": node_id, **graph.nodes[node_id]} for node_id in collected]
+
+
+class GraphWalkMemoryFeatureGroup(AgentMemoryFeatureGroup):
+    READER_CLASS: ClassVar[type[GraphWalkMemoryReader]] = GraphWalkMemoryReader  # type: ignore[assignment]

open_kgo/feature_groups/kg/agent_memory/networkx_memory.py

@@ -0,0 +1,106 @@
+"""NetworkX-backed agent memory store.
+
+In-process MultiDiGraph keyed by (node, valid_at, invalid_at). Supports
+``retrieval_mode=lexical`` (string-match against node labels) without an LLM
+or embedding service. Demonstrates the agent_memory contract shape.
+
+PROTOTYPE NOTE: ``retrieval_mode`` is narrowed to ``lexical`` via
+``SUPPORTED_VALUES``; ``vector`` / ``hybrid`` / ``graph`` are rejected at
+``is_valid_credentials`` time rather than passing validation and raising
+``NotImplementedError`` at load. Bi-temporal filtering uses simple
+lexicographic comparison on ISO timestamps.
+
+Memory data is loaded from a JSON file pointed to by the ``locator``
+credential slot (shape: ``{user_id: {"nodes": [...], "edges": [...]}}``).
+A user_id absent from the loaded fixture raises ``UnknownMemoryScopeError``
+at ``connect()`` time; an unreadable / malformed locator raises
+``FixtureLoadError``. Both surface the gap as a typed credential-shape
+error rather than silently emptying the result set or leaking raw IO
+exceptions. Fixture loads are mtime-cached via
+``kg.fixtures.load_json_fixture``, so repeated ``load_data`` calls do
+not re-read disk.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Mapping
+
+import networkx as nx
+
+from mloda.core.abstract_plugins.components.feature_set import FeatureSet
+
+from open_kgo.feature_groups.kg.agent_memory.base import (
+    AgentMemoryFeatureGroup,
+    AgentMemoryReader,
+)
+from open_kgo.feature_groups.kg.agent_memory.shared import build_memory_graph, validate_user_data
+from open_kgo.feature_groups.kg.base import LoadContext
+from open_kgo.feature_groups.kg.errors import UnknownMemoryScopeError
+from open_kgo.feature_groups.kg.fixtures import load_json_fixture
+
+
+class NetworkxMemoryReader(AgentMemoryReader):
+    CONNECTOR_ID: ClassVar[str] = "networkx_memory"
+    # Narrowed from the family-level OR-group ({memory_scope_user_id,
+    # memory_scope_agent_id, ..._session_id, ..._run_id, ..._group_ids}) to
+    # ``("memory_scope_user_id",)`` only: the JSON fixture is keyed by
+    # user_id, so the other aliases would either silently no-op or surface
+    # a misleading "user_id not provisioned" error at connect time. Future
+    # concrete readers (Mem0, Zep+Graphiti, Letta) honor different scope
+    # keys; this concrete pins the one its substrate supports. The
+    # ``MEMORY_SCOPE_KEYS`` constant in ``agent_memory/base.py`` remains the
+    # canonical scope list for those future readers.
+    REQUIRED_KEYS: ClassVar[tuple[tuple[str, ...], ...]] = (
+        ("locator",),
+        ("memory_scope_user_id",),
+    )
+    SUPPORTED_VALUES: ClassVar[Mapping[str, frozenset[Any]]] = {
+        "pagination_style": frozenset({"none"}),
+        "retrieval_mode": frozenset({"lexical"}),
+    }
+
+    @classmethod
+    def _connect_from_slot(cls, slot: Mapping[str, Any]) -> nx.MultiDiGraph:
+        locator = str(slot["locator"])
+        store = load_json_fixture(cls.CONNECTOR_ID, locator)
+        # REQUIRED_KEYS now requires memory_scope_user_id specifically (this
+        # concrete narrows the family OR-group), so the slot subscript is
+        # safe — the validator already enforced presence + truthiness.
+        user_id = str(slot["memory_scope_user_id"])
+        if user_id not in store:
+            raise UnknownMemoryScopeError(cls.CONNECTOR_ID, user_id)
+        user_data = validate_user_data(cls.CONNECTOR_ID, locator, user_id, store[user_id])
+        return build_memory_graph(user_data)
+
+    @classmethod
+    def build_query(cls, features: FeatureSet) -> str:
+        feature = next(iter(features.features))
+        text = feature.options.get("query_text")
+        if not isinstance(text, str):
+            raise ValueError(f"{cls.CONNECTOR_ID}: 'query_text' is required.")
+        return text
+
+    @classmethod
+    def _load_rows(cls, ctx: LoadContext, connection: Any, features: FeatureSet) -> list[dict[str, Any]]:
+        graph = connection
+        query_text = cls.build_query(features).lower()
+        valid_range = ctx.slot.get("valid_at_range") or ()
+
+        rows: list[dict[str, Any]] = []
+        for node_id, attrs in graph.nodes(data=True):
+            label = str(attrs.get("label", "")).lower()
+            if query_text and query_text not in label:
+                continue
+            if valid_range and len(valid_range) == 2:
+                start, end = valid_range[0], valid_range[1]
+                node_valid = attrs.get("valid_at")
+                if node_valid is not None and not (start <= node_valid <= end):
+                    continue
+            rows.append({"id": node_id, **attrs})
+            if len(rows) >= ctx.result_limit:
+                break
+        return rows
+
+
+class NetworkxMemoryFeatureGroup(AgentMemoryFeatureGroup):
+    READER_CLASS: ClassVar[type[NetworkxMemoryReader]] = NetworkxMemoryReader  # type: ignore[assignment]