feat(nemobridge): persistent opt-in for nemo delegation via pyirk config

The delegation flag was env-only (PYIRK_NEMO_DELEGATION), which is tedious
for a developer who wants the speedup in all their own runs. Add a
delegation_enabled() resolver: env var (decisive in both directions) over
pyirk config [nemo] delegation over a shipped default of off. The general
user is unaffected unless they opt in; an individual can enable it
persistently in their config.

Also fixes a latent bug: the old 'if os.environ.get(...)' treated
PYIRK_NEMO_DELEGATION=0 / =false as truthy and wrongly ENABLED delegation,
contradicting the docs. Falsy tokens (0/false/no/off) now disable correctly.

Docs (how-to + README) document the config toggle and precedence; 7 new
unit tests cover the env/config/default matrix. Full suite green with flag
off (197 passed); rule-based reasoning green with flag on.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: cknoll

README.md

@@ -47,7 +47,7 @@ Note that, originally pyirk (imperative representation of knowledge) was called
 
 # Optional: Nemo rule-engine delegation
 
-For performance-critical rule sets, pyirk can optionally delegate evaluation of a curated subset of rules to the Nemo datalog engine via its `nmo` CLI (see the upstream Nemo project for installation instructions). The feature is **off by default**; set the environment variable `PYIRK_NEMO_DELEGATION=1` to enable it (and optionally `PYIRK_NEMO_BIN=/abs/path/to/nmo` to pin the binary). The native Python engine remains the authoritative reference and the automatic fallback path. See the how-to guide [`docs/source/howto/nemo_delegation.md`](docs/source/howto/nemo_delegation.md) for resolver order, version policy, and known limits.
+For performance-critical rule sets, pyirk can optionally delegate evaluation of a curated subset of rules to the Nemo datalog engine via its `nmo` CLI (see the upstream Nemo project for installation instructions). The feature is **off by default**; enable it either per-invocation via the environment variable `PYIRK_NEMO_DELEGATION=1` or persistently via `[nemo] delegation = true` in your pyirk config (optionally pin the binary with `PYIRK_NEMO_BIN=/abs/path/to/nmo`). The native Python engine remains the authoritative reference and the automatic fallback path. See the how-to guide [`docs/source/howto/nemo_delegation.md`](docs/source/howto/nemo_delegation.md) for resolver order, version policy, and known limits.
 
 # Documentation
 

docs/source/howto/nemo_delegation.md

@@ -34,12 +34,36 @@ does **not** bundle or vendor the `nmo` binary.
 Two environment variables control the feature; both are read fresh at every
 rule-engine entry point.
 
-* `PYIRK_NEMO_DELEGATION=1` — enables the delegation path. Any other value
-  (or absence) keeps the native Python engine in charge.
+* `PYIRK_NEMO_DELEGATION=1` — enables the delegation path. Recognised truthy
+  tokens are `1`/`true`/`yes`/`on`; `0`/`false`/`no`/`off` explicitly
+  *disable* it (overriding the config below). An unset or unrecognised value
+  falls through to the config setting.
 * `PYIRK_NEMO_BIN=/abs/path/to/nmo` — optional override that pins the
   `nmo` binary used by pyirk. Useful for CI, container images, or when
   multiple Nemo versions co-exist on a developer machine.
 
+### Persistent opt-in via the pyirk config
+
+Setting the env var on every invocation is tedious for a developer who
+simply wants the speedup in all their own runs. The delegation flag is
+therefore *also* read from the pyirk config file (the same
+`config.toml` that already carries `[package.ocse]`):
+
+```toml
+[nemo]
+delegation = true
+```
+
+Precedence: the `PYIRK_NEMO_DELEGATION` env var wins in both directions when
+set to a recognised token; otherwise the config value decides; otherwise the
+shipped default is **off**. This keeps delegation strictly opt-in for the
+general user (no behaviour change unless they opt in) while letting an
+individual enable it persistently for their own environment.
+
+Note that even when enabled, the hook still checks that an `nmo` binary is
+present and version-compatible, and silently falls back to the native engine
+otherwise — so a config opt-in on a machine without `nmo` is harmless.
+
 ### Resolver order
 
 When delegation is enabled, the binary is resolved in the following

src/pyirk/nemobridge/delegation.py

@@ -41,6 +41,60 @@
 # avoid a hard import-time dependency between the two modules.
 _LITERAL_PREFIX = "LIT:"
 
+
+_TRUTHY_TOKENS = ("1", "true", "yes", "on")
+_FALSY_TOKENS = ("0", "false", "no", "off", "")
+
+
+def _coerce_flag(value) -> "bool | None":
+    """Interpret a config/env value as an on/off flag.
+
+    Returns ``True``/``False`` for a recognised token, or ``None`` if the
+    value is absent (``None``) or unrecognised (caller decides the default).
+    A genuine ``bool`` (e.g. from a TOML ``delegation = true``) passes through.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    token = str(value).strip().lower()
+    if token in _TRUTHY_TOKENS:
+        return True
+    if token in _FALSY_TOKENS:
+        return False
+    return None
+
+
+def delegation_enabled() -> bool:
+    """Whether the Nemo-delegation path should be used.
+
+    Resolution order (first decisive wins):
+      1. ``PYIRK_NEMO_DELEGATION`` env var — an explicit truthy/falsy token
+         decides in BOTH directions (so ``=0`` disables even if the config
+         enables it). An unrecognised value is ignored, not treated as on.
+      2. pyirk config ``[nemo] delegation`` (``p.CONF``) — lets a user opt in
+         persistently without setting the env var on every invocation.
+      3. Default: ``False`` (delegation stays opt-in; the native Python engine
+         is the shipped default).
+
+    Note: this only expresses *intent*. The hook still verifies that an
+    ``nmo`` binary is available and version-compatible before delegating,
+    and falls back silently otherwise.
+    """
+    env_flag = _coerce_flag(os.environ.get("PYIRK_NEMO_DELEGATION"))
+    if env_flag is not None:
+        return env_flag
+
+    try:
+        import pyirk as p
+        cfg_flag = _coerce_flag(p.CONF.get("nemo", {}).get("delegation"))
+        if cfg_flag is not None:
+            return cfg_flag
+    except Exception:
+        pass
+
+    return False
+
 # ── Deployment-Robustheit (H5 Deployment) ────────────────────────────────────
 # Modul-State für idempotente Logs/Warnings — pro Prozess genau einmal.
 # Tests setzen diese Flags via monkeypatch zurück.

src/pyirk/ruleengine.py

@@ -70,7 +70,9 @@ def apply_semantic_rules(*rules: List, mod_context_uri: str = None, exhaust=Fals
 
     :param exhaust:     boolean flag; if True: repeat rule application until no new statements are created
 
-    Bei aktivem PYIRK_NEMO_DELEGATION, verfügbarem Nemo-Binary und nicht-leerer
+    Bei aktivierter Delegation (siehe ``delegation_enabled()``: Env-Variable
+    ``PYIRK_NEMO_DELEGATION`` ODER pyirk-Config ``[nemo] delegation``),
+    verfügbarem Nemo-Binary und nicht-leerer
     delegable-Teilmenge wird der V4-Pfad gewählt: ein beschränkter Fixpunkt-Loop
     nemo↔python, der pro Iteration zuerst die delegierbaren Regeln via Nemo bis
     zu deren Fixpunkt materialisiert und danach die remaining-Regeln genau
@@ -88,7 +90,8 @@ def apply_semantic_rules(*rules: List, mod_context_uri: str = None, exhaust=Fals
     delegated: list = []
     remaining: list = list(rules)
 
-    if os.environ.get("PYIRK_NEMO_DELEGATION"):
+    from pyirk.nemobridge.delegation import delegation_enabled
+    if delegation_enabled():
         from pyirk.nemobridge.delegation import (
             _nemo_available,
             _resolve_nmo_bin,

tests/test_nemobridge_resolver.py

@@ -353,3 +353,47 @@ def test_fires_only_once_across_many_calls(self, caplog):
             delegation.mark_nmo_failed_warned(RuntimeError(f"call {i}"))
         warns = _records_for(caplog, logging.WARNING, "Nemo delegation failed")
         assert len(warns) == 1
+
+
+class TestDelegationEnabled:
+    """``delegation_enabled()`` — env-var (both directions) over pyirk config
+    over a shipped default of off."""
+
+    def test_env_truthy_tokens_enable(self, monkeypatch):
+        for tok in ("1", "true", "TRUE", "yes", "on"):
+            monkeypatch.setenv("PYIRK_NEMO_DELEGATION", tok)
+            assert delegation.delegation_enabled() is True
+
+    def test_env_falsy_tokens_disable(self, monkeypatch):
+        # Regression: the old ``if os.environ.get(...)`` treated "0"/"false"
+        # as truthy and wrongly ENABLED delegation.
+        for tok in ("0", "false", "no", "off", ""):
+            monkeypatch.setenv("PYIRK_NEMO_DELEGATION", tok)
+            assert delegation.delegation_enabled() is False
+
+    def test_env_disable_overrides_config_enable(self, monkeypatch):
+        monkeypatch.setenv("PYIRK_NEMO_DELEGATION", "0")
+        monkeypatch.setattr(p, "CONF", {"nemo": {"delegation": True}}, raising=False)
+        assert delegation.delegation_enabled() is False
+
+    def test_config_enables_when_env_unset(self, monkeypatch):
+        monkeypatch.delenv("PYIRK_NEMO_DELEGATION", raising=False)
+        monkeypatch.setattr(p, "CONF", {"nemo": {"delegation": True}}, raising=False)
+        assert delegation.delegation_enabled() is True
+
+    def test_config_falsy_keeps_disabled(self, monkeypatch):
+        monkeypatch.delenv("PYIRK_NEMO_DELEGATION", raising=False)
+        monkeypatch.setattr(p, "CONF", {"nemo": {"delegation": False}}, raising=False)
+        assert delegation.delegation_enabled() is False
+
+    def test_default_off_when_nothing_set(self, monkeypatch):
+        monkeypatch.delenv("PYIRK_NEMO_DELEGATION", raising=False)
+        monkeypatch.setattr(p, "CONF", {}, raising=False)
+        assert delegation.delegation_enabled() is False
+
+    def test_unrecognised_env_falls_through_to_config(self, monkeypatch):
+        # An unrecognised env token is ignored, not treated as on; the config
+        # then decides.
+        monkeypatch.setenv("PYIRK_NEMO_DELEGATION", "maybe")
+        monkeypatch.setattr(p, "CONF", {"nemo": {"delegation": True}}, raising=False)
+        assert delegation.delegation_enabled() is True