eq-layer 0.2.1__tar.gz → 0.2.3__tar.gz

{eq_layer-0.2.1 → eq_layer-0.2.3}/.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 .venv/
 venv/
 .env
+.npmrc
 .DS_Store
 .idea/
 .vscode/

{eq_layer-0.2.1 → eq_layer-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: eq-layer
-Version: 0.2.1
+Version: 0.2.3
 Summary: Inspectable intent, affect, repair, uncertainty, and factored-action control for LLM responses
 Project-URL: Homepage, https://github.com/Furox-Art/eq-layer
 Project-URL: Repository, https://github.com/Furox-Art/eq-layer
@@ -554,6 +554,25 @@ detection — were tested and retained as no-go results instead of being wired
 into policy routing. The tracker exposes where labels are direct, derived,
 structural, fallback, or externally verified.
 
+## Publishing
+
+Two artifacts, one semantic version: PyPI `eq-layer` (the Python runtime and
+control layer) and npm `eq-layer` (the portable Agent Skill installer and CLI
+bridge). Each side keeps its version in exactly one canonical location, and the
+release workflows verify the GitHub release tag against those fields before
+uploading.
+
+npm publishing picks its credential mode at run time, based on repository
+settings only:
+
+- `NPM_TOKEN` configured: token mode, `npm publish --access public
+  --no-provenance`;
+- no `NPM_TOKEN`: trusted publishing over GitHub OIDC, `npm publish
+  --access public --provenance`.
+
+Provenance is an OIDC-only attestation, so it is only requested when no token is
+configured. See `docs/PUBLISHING.md` for the full flow.
+
 ## Contributing
 
 Cases are the main entry point. Open one for a failure mode you can describe concretely — especially the ones where two policies seem equally right.

{eq_layer-0.2.1 → eq_layer-0.2.3}/README.md

@@ -519,6 +519,25 @@ detection — were tested and retained as no-go results instead of being wired
 into policy routing. The tracker exposes where labels are direct, derived,
 structural, fallback, or externally verified.
 
+## Publishing
+
+Two artifacts, one semantic version: PyPI `eq-layer` (the Python runtime and
+control layer) and npm `eq-layer` (the portable Agent Skill installer and CLI
+bridge). Each side keeps its version in exactly one canonical location, and the
+release workflows verify the GitHub release tag against those fields before
+uploading.
+
+npm publishing picks its credential mode at run time, based on repository
+settings only:
+
+- `NPM_TOKEN` configured: token mode, `npm publish --access public
+  --no-provenance`;
+- no `NPM_TOKEN`: trusted publishing over GitHub OIDC, `npm publish
+  --access public --provenance`.
+
+Provenance is an OIDC-only attestation, so it is only requested when no token is
+configured. See `docs/PUBLISHING.md` for the full flow.
+
 ## Contributing
 
 Cases are the main entry point. Open one for a failure mode you can describe concretely — especially the ones where two policies seem equally right.

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/__init__.py

@@ -1,14 +1,21 @@
-__version__ = "0.2.1"
-
+from ._deps import OptionalDependencyError
+from ._version import __version__
 from .affect import AffectAdapter, HeuristicAffect, load_cases
 from .auditor import AuditContext, AuditIssue, ResponseAudit, ResponseAuditor, audit_from_generation_metadata
 from .actions import FactoredAction, RealizationControls, compose_action
 from .intent import HeuristicIntent, IntentAdapter, IntentState
 from .intent_belief import IntentBelief, IntentRiskDecision, decide_intent_action, expected_loss
 from .interaction import InteractionQualityState, RepairState, infer_interaction_quality, infer_repair_state
+from .model_state import ModelStateError
 from .policies import POLICIES, REGISTRY, SUBTEXTS, AffectState, Policy, Register, Selector
 from .preferences import SessionPreferences, infer_session_preferences
-from .response_experiment import CommandModel, FullEQPipeline, generate_pairs, validate_experiment_cases
+from .response_experiment import (
+    CommandModel,
+    FullEQPipeline,
+    ModelCommandTimeout,
+    generate_pairs,
+    validate_experiment_cases,
+)
 from .steer import Steer, aggregate, score_case
 from .trained_affect import DimensionalAffect, TrainedAffect
 from .trained_intent import TrainedIntent
@@ -17,6 +24,8 @@ from .tracker import AnnotationStanceResolver, ConversationTracker, StanceDecisi
 
 __all__ = [
     "__version__",
+    "OptionalDependencyError",
+    "ModelStateError",
     "AffectAdapter",
     "AffectState",
     "audit_from_generation_metadata",
@@ -62,6 +71,7 @@ __all__ = [
     "AnnotationStanceResolver",
     "CommandModel",
     "FullEQPipeline",
+    "ModelCommandTimeout",
     "generate_pairs",
     "validate_experiment_cases",
     "score_case",

eq_layer-0.2.3/eq_layer/_deps.py

@@ -0,0 +1,62 @@
+"""Typed boundary for the optional ``ml`` extra.
+
+The trained adapters import scikit-learn and their artifact loaders import
+joblib; both ship in ``eq-layer[ml]``. Every optional import in the package
+goes through this module so a missing or unusable extra surfaces as one typed,
+actionable error that names the package and the install command, instead of a
+bare ``ImportError`` traceback at request time (audit M-2/M-7).
+"""
+
+from __future__ import annotations
+
+ML_EXTRA = "ml"
+ML_PACKAGE = "scikit-learn"
+JOBLIB_PACKAGE = "joblib"
+ML_INSTALL_COMMAND = 'pip install "eq-layer[ml]"'
+
+
+class OptionalDependencyError(ImportError):
+    """An optional dependency of the ``ml`` extra is missing or unusable.
+
+    Subclasses ``ImportError`` so existing ``except ImportError`` fallbacks
+    (the CLI's heuristic intent fallback under ``--intent-mode auto``) keep
+    working, while callers that want to map the failure to their own exit code
+    or message can catch the typed error instead of matching on message text.
+    """
+
+    def __init__(
+        self,
+        purpose: str,
+        *,
+        package: str = ML_PACKAGE,
+        cause: BaseException | None = None,
+        install_command: str = ML_INSTALL_COMMAND,
+    ) -> None:
+        detail = f" ({cause})" if cause is not None else ""
+        super().__init__(
+            f"{purpose} requires the optional ML dependencies: "
+            f"{package} is unavailable{detail}. "
+            f"Install with: {install_command}"
+        )
+        self.purpose = purpose
+        self.package = package
+        self.install_command = install_command
+
+
+def missing_ml_dependency(purpose: str, cause: BaseException) -> OptionalDependencyError:
+    """Build the typed error for a failed scikit-learn import."""
+    return OptionalDependencyError(purpose, package=ML_PACKAGE, cause=cause)
+
+
+def missing_joblib(purpose: str, cause: BaseException) -> OptionalDependencyError:
+    """Build the typed error for a failed joblib import."""
+    return OptionalDependencyError(purpose, package=JOBLIB_PACKAGE, cause=cause)
+
+
+def ml_extra_available() -> bool:
+    """Report whether the optional ML extra can be imported at all."""
+    try:
+        import sklearn  # noqa: F401
+    except ImportError:
+        return False
+    return True

eq_layer-0.2.3/eq_layer/_version.py

@@ -0,0 +1,57 @@
+"""Single source of truth for the EQ-Layer Python package version.
+
+The editable location is the ``version`` field of the ``[project]`` table in
+``pyproject.toml``. When the distribution is installed, ``importlib.metadata``
+is authoritative; from a source checkout the same field is read from the
+nearest ``pyproject.toml`` so both paths report the identical string instead
+of a hardcoded copy that drifts (audit M4).
+"""
+
+from __future__ import annotations
+
+import re
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+DISTRIBUTION = "eq-layer"
+
+_PROJECT_HEADER = re.compile(r"(?m)^\[project\]\s*$")
+_NEXT_TABLE = re.compile(r"(?m)^\[")
+_VERSION_KEY = re.compile(r'(?m)^version\s*=\s*"([^"]+)"')
+
+
+def _project_table(pyproject_text: str) -> str:
+    """Return the ``[project]`` table body, or "" when absent.
+
+    Scoping the search matters: an unrelated ``version =`` key under another
+    table must not win over the package version.
+    """
+    header = _PROJECT_HEADER.search(pyproject_text)
+    if header is None:
+        return ""
+    rest = pyproject_text[header.end() :]
+    next_table = _NEXT_TABLE.search(rest)
+    return rest[: next_table.start()] if next_table else rest
+
+
+def _source_checkout_version() -> str | None:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        match = _VERSION_KEY.search(_project_table(pyproject.read_text(encoding="utf-8")))
+        if match:
+            return match.group(1)
+    return None
+
+
+def detect_version() -> str:
+    try:
+        return version(DISTRIBUTION)
+    except PackageNotFoundError:
+        # Source checkout without an installed distribution.
+        return _source_checkout_version() or "0.0.0+unknown"
+
+
+__version__ = detect_version()

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/auditor.py

@@ -4,6 +4,8 @@ import re
 from dataclasses import asdict, dataclass
 from difflib import SequenceMatcher
 
+from .textnorm import normalise_light as _normalise
+
 
 ABSOLUTE_PRIVACY_PROMISES = (
     "kimseye söylemem",
@@ -77,10 +79,6 @@ class ResponseAudit:
         }
 
 
-def _normalise(text: str) -> str:
-    return " ".join(text.lower().split())
-
-
 def _sentence_starts(text: str) -> tuple[str, ...]:
     parts = re.split(r"(?<=[.!?])\s+|\n+", _normalise(text))
     return tuple(part.strip(" -—:;,.!?") for part in parts if part.strip())

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/cli.py

@@ -7,6 +7,8 @@ import json
 import sys
 from dataclasses import asdict
 
+from ._deps import ML_INSTALL_COMMAND, OptionalDependencyError, ml_extra_available
+
 
 def _load_messages(raw: str) -> list[dict]:
     payload = json.loads(raw)
@@ -38,9 +40,11 @@ def _intent_adapter(mode: str):
         return HeuristicIntent(), "heuristic"
     try:
         return TrainedIntent.from_bundled(), "trained-tfidf-logreg"
-    except ImportError:
+    except OptionalDependencyError:
         if mode == "learned":
             raise
+        # A missing optional extra is not a routing failure: degrade to the
+        # zero-dependency heuristic path and say which backend answered.
         return HeuristicIntent(), "heuristic-fallback-no-ml-extra"
 
 
@@ -125,16 +129,19 @@ def _route(args: argparse.Namespace) -> int:
 
 
 def _doctor() -> int:
+    from . import __version__
+
+    ml_available = ml_extra_available()
     payload = {
         "package": "eq-layer",
-        "version": "0.2.1",
+        "version": __version__,
         "python": sys.version.split()[0],
-        "ml_extra_available": True,
+        "ml_extra_available": ml_available,
     }
-    try:
-        import sklearn  # noqa: F401
-    except ImportError:
-        payload["ml_extra_available"] = False
+    if not ml_available:
+        payload["ml_extra_hint"] = (
+            f"Optional ML dependencies are unavailable. Install with: {ML_INSTALL_COMMAND}"
+        )
     print(json.dumps(payload, indent=2))
     return 0
 
@@ -165,6 +172,12 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     try:
         return int(args.handler(args))
+    except OptionalDependencyError as exc:
+        # A missing optional extra is a configuration problem, not a usage
+        # error: report it on stderr with the install command and exit 2
+        # without dumping the usage block on top of the actionable message.
+        print(f"{parser.prog}: error: {exc}", file=sys.stderr)
+        return 2
     except (ValueError, json.JSONDecodeError, ImportError) as exc:
         parser.error(str(exc))
     return 2

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/dialogue_reference.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
+from .textnorm import normalise_plain
+
 
 @dataclass(frozen=True)
 class GoalCandidate:
@@ -106,8 +108,9 @@ _USER_GOAL_MARKERS = (
 
 
 def _normalise(text: str) -> str:
-    lowered = text.lower().replace("\u0307", "")
-    return " ".join(re.sub(r"[^\w\s]", " ", lowered).split())
+    # Drop the Turkish combining dot above so dotted and dotless spellings of
+    # the same word compare equal before the shared punctuation pass.
+    return normalise_plain(text, drop_combining_dot_above=True)
 
 
 def _excerpt(text: str) -> str:

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/intent.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from typing import Protocol
 
 from .intent_belief import IntentBelief, IntentRiskDecision
+from .textnorm import normalise_light
 
 
 @dataclass(frozen=True)
@@ -179,7 +180,7 @@ class HeuristicIntent:
         return f'{prefix}: "{request}".{suffix}'
 
     def _normalise(self, text: str) -> str:
-        return " ".join(text.lower().split())
+        return normalise_light(text)
 
     def _first_marker(self, text: str, markers: tuple[str, ...]) -> str | None:
         for marker in markers:

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/interaction.py

@@ -4,6 +4,7 @@ import re
 from dataclasses import dataclass
 
 from .affect import CORRECTION_MARKERS
+from .textnorm import normalise_plain as _normalise
 
 
 @dataclass(frozen=True)
@@ -42,10 +43,6 @@ class InteractionQualityState:
     evidence: tuple[str, ...] = ()
 
 
-def _normalise(text: str) -> str:
-    return " ".join(re.sub(r"[^\w\s]", " ", text.lower()).split())
-
-
 def _has_correction(text: str) -> bool:
     low = text.lower()
     return any(marker in low for marker in CORRECTION_MARKERS)

eq_layer-0.2.3/eq_layer/model_state.py

@@ -0,0 +1,99 @@
+"""Schema validation for persisted trained-model state (audit H-2).
+
+A trained adapter is restored from a joblib artifact. Before this validation
+the loaders indexed the payload directly, so a malformed artifact surfaced as a
+raw ``KeyError`` for a missing key, or a ``TypeError``/``ValueError`` raised
+from inside the dataclass constructor for the wrong field type. Either way the
+caller got an unhandled path with no hint about which field was at fault.
+
+Every loader in ``eq_layer/trained_*.py`` now validates the payload schema
+before constructing the adapter, and raises one typed error naming the offending
+field.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+# A field that must be present and non-None but whose value is an opaque fitted
+# estimator, so its concrete type is deliberately not pinned here.
+FITTED = object()
+
+_FLOAT_TYPES = (int, float)
+
+
+class ModelStateError(ValueError):
+    """A persisted model artifact failed schema validation at load time."""
+
+    def __init__(
+        self,
+        model: str,
+        field: str,
+        problem: str,
+        path: str | Path | None = None,
+    ) -> None:
+        location = f" in {path}" if path is not None else ""
+        super().__init__(
+            f"{model} artifact{location} has an invalid {field!r} field: {problem}"
+        )
+        self.model = model
+        self.field = field
+        self.problem = problem
+
+
+def _type_names(types: tuple[type, ...]) -> str:
+    return " or ".join(entry.__name__ for entry in types)
+
+
+def _check(
+    model: str,
+    field: str,
+    value: Any,
+    accepted: Any,
+    path: str | Path | None,
+) -> None:
+    if accepted is FITTED:
+        if value is None:
+            raise ModelStateError(model, field, "must not be None", path)
+        return
+    if not isinstance(value, accepted):
+        raise ModelStateError(
+            model,
+            field,
+            f"expected {_type_names(accepted)}, got {type(value).__name__}",
+            path,
+        )
+
+
+def validate_state(
+    payload: Any,
+    *,
+    model: str,
+    path: str | Path | None = None,
+    required: Mapping[str, Any] | None = None,
+    optional: Mapping[str, Any] | None = None,
+) -> None:
+    """Validate a persisted model artifact before it is used.
+
+    ``required``/``optional`` map a field name to an accepted type tuple, or to
+    ``FITTED`` for an opaque fitted estimator. A missing required key, an empty
+    payload and a wrongly typed field each raise ``ModelStateError`` naming the
+    offending field.
+    """
+    if not isinstance(payload, Mapping):
+        raise ModelStateError(
+            model,
+            "payload",
+            f"expected a mapping of fields, got {type(payload).__name__}",
+            path,
+        )
+
+    for spec, must_exist in ((required or {}, True), (optional or {}, False)):
+        for field, accepted in spec.items():
+            if field not in payload:
+                if must_exist:
+                    raise ModelStateError(model, field, "missing required key", path)
+                continue
+            _check(model, field, payload[field], accepted, path)

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/preferences.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 from dataclasses import asdict, dataclass, replace
 
+from .textnorm import normalise_light as _normalise
+
 
 SESSION_SCOPE_PATTERNS = (
     r"\bbundan sonra\b",
@@ -44,10 +46,6 @@ class SessionPreferences:
         return asdict(self)
 
 
-def _normalise(text: str) -> str:
-    return " ".join(text.lower().split())
-
-
 def _session_scoped(text: str) -> bool:
     low = _normalise(text)
     if any(re.search(pattern, low) for pattern in SESSION_SCOPE_PATTERNS):

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/response_experiment.py

@@ -6,6 +6,7 @@ import random
 import re
 import shlex
 import subprocess
+import threading
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Iterable
@@ -28,6 +29,42 @@ LEAKAGE_FIELDS = {
 }
 
 
+class ModelCommandTimeout(RuntimeError):
+    """A model command failed to answer within its configured timeout.
+
+    Raised for both the one-shot and the persistent command modes so callers
+    (including the A/B generation CLI) can catch one typed error instead of
+    pattern-matching messages. Subclasses ``RuntimeError`` like the other
+    model-command failures.
+    """
+
+
+def _force_kill(process: subprocess.Popen) -> None:
+    """Best-effort hard kill of a wedged child so its pipes close.
+
+    Used by the persistent-command timeout path and as the escalation step of
+    ``CommandModel.close``. Terminate first, then kill if the child ignores
+    it; both are no-ops when the process has already been reaped.
+    """
+    try:
+        process.terminate()
+    except OSError:
+        pass
+    try:
+        process.wait(timeout=5)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    try:
+        process.kill()
+    except OSError:
+        pass
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        pass
+
+
 def validate_experiment_cases(cases: list[dict], *, final: bool = False) -> dict:
     errors: list[str] = []
     seen: set[str] = set()
@@ -222,14 +259,20 @@ class CommandModel:
         if self.persistent:
             raw = self._persistent_generate(payload)
         else:
-            completed = subprocess.run(
-                list(self.command),
-                input=json.dumps(payload, ensure_ascii=False),
-                text=True,
-                capture_output=True,
-                timeout=self.timeout_seconds,
-                check=False,
-            )
+            try:
+                completed = subprocess.run(
+                    list(self.command),
+                    input=json.dumps(payload, ensure_ascii=False),
+                    text=True,
+                    capture_output=True,
+                    timeout=self.timeout_seconds,
+                    check=False,
+                )
+            except subprocess.TimeoutExpired as exc:
+                raise ModelCommandTimeout(
+                    f"Model command did not respond within "
+                    f"{self.timeout_seconds} seconds: {' '.join(self.command)}"
+                ) from exc
             if completed.returncode != 0:
                 raise RuntimeError(
                     f"Model command failed ({completed.returncode}): "
@@ -261,7 +304,7 @@ class CommandModel:
 
         process.stdin.write(json.dumps(payload, ensure_ascii=False) + "\n")
         process.stdin.flush()
-        raw = process.stdout.readline().strip()
+        raw = self._read_line(process, self.timeout_seconds)
         if not raw:
             stderr = process.stderr.read().strip() if process.stderr else ""
             raise RuntimeError(
@@ -270,6 +313,40 @@ class CommandModel:
             )
         return raw
 
+    def _read_line(self, process: subprocess.Popen, timeout_seconds: float) -> str:
+        """Read one stdout line from the child under a wall-clock deadline.
+
+        A blocking ``readline()`` on a pipe waits until the child writes a
+        newline, and on Windows a blocked pipe read cannot be interrupted, so
+        the read runs on a daemon reader thread that is joined with the
+        configured timeout. On expiry the child is force-killed: its stdout
+        closes, the blocked read unwinds with EOF, and a wedged model command
+        can never stall the experiment synchronously.
+        """
+        stdout = process.stdout
+        if stdout is None:
+            raise RuntimeError("Persistent model command pipes are unavailable.")
+
+        lines: list[str] = []
+
+        def _read() -> None:
+            lines.append(stdout.readline())
+
+        reader = threading.Thread(
+            target=_read,
+            name="eq-layer-model-reader",
+            daemon=True,
+        )
+        reader.start()
+        reader.join(timeout_seconds)
+        if reader.is_alive():
+            _force_kill(process)
+            raise ModelCommandTimeout(
+                f"Persistent model command produced no response within "
+                f"{timeout_seconds} seconds: {' '.join(self.command)}"
+            )
+        return lines[0].strip() if lines else ""
+
     @staticmethod
     def _decode_response(raw: str) -> str:
         if not raw:
@@ -300,12 +377,7 @@ class CommandModel:
         try:
             process.wait(timeout=10)
         except subprocess.TimeoutExpired:
-            process.terminate()
-            try:
-                process.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                process.kill()
-                process.wait(timeout=5)
+            _force_kill(process)
 
 
 @dataclass

eq_layer-0.2.3/eq_layer/textnorm.py

@@ -0,0 +1,42 @@
+"""Shared text-normalisation helpers.
+
+Five modules used to carry copy-pasted ``_normalise`` helpers, and the copies
+had already drifted into two behaviours:
+
+* a light form — lowercase and collapse whitespace, punctuation preserved
+  (``auditor``, ``preferences``, ``intent``);
+* a plain form — also replace punctuation runs with spaces (``interaction``),
+  with ``dialogue_reference`` additionally dropping the Turkish combining dot
+  above (U+0307) so dotted and dotless spellings compare equal.
+
+Both behaviours live here, in one place. Callers must keep using the variant
+their matching logic was written against: this consolidation removes the
+duplicated code without silently changing any matcher's semantics.
+"""
+
+from __future__ import annotations
+
+import re
+
+_PUNCTUATION = re.compile(r"[^\w\s]")
+_COMBINING_DOT_ABOVE = "\u0307"
+
+
+def normalise_light(text: str) -> str:
+    """Lowercase and collapse whitespace. Punctuation is preserved."""
+    return " ".join(text.lower().split())
+
+
+def normalise_plain(text: str, *, drop_combining_dot_above: bool = False) -> str:
+    """Lowercase, replace punctuation with spaces, and collapse whitespace.
+
+    ``drop_combining_dot_above`` removes U+0307 before the punctuation pass so
+    that ``i`` + combining dot above normalises like a bare ``i``. This is
+    needed by Turkish dotted/dotless matching in the dialogue-reference
+    matcher; it is off by default so the default behaviour stays identical to
+    the historical copies.
+    """
+    lowered = text.lower()
+    if drop_combining_dot_above:
+        lowered = lowered.replace(_COMBINING_DOT_ABOVE, "")
+    return " ".join(_PUNCTUATION.sub(" ", lowered).split())

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/trained_affect.py

@@ -5,7 +5,9 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Iterable
 
+from ._deps import missing_joblib, missing_ml_dependency
 from .affect import HeuristicAffect
+from .model_state import FITTED, validate_state
 from .policies import AffectState
 
 EMOBANK_COMMIT = "248ce2a43e165a66d31aeaed83cff9641d6654e0"
@@ -23,10 +25,7 @@ def build_affect_pipeline():
         from sklearn.linear_model import Ridge
         from sklearn.pipeline import FeatureUnion, Pipeline
     except ImportError as exc:
-        raise ImportError(
-            "TrainedAffect requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedAffect", exc) from exc
 
     features = FeatureUnion(
         [
@@ -205,7 +204,7 @@ class TrainedAffect:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Saving a trained affect model requires joblib.") from exc
+            raise missing_joblib("Saving a trained affect model", exc) from exc
 
         joblib.dump(
             {
@@ -222,8 +221,25 @@ class TrainedAffect:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Loading a trained affect model requires joblib.") from exc
-        payload = joblib.load(path)
+            raise missing_joblib("Loading a trained affect model", exc) from exc
+        try:
+            payload = joblib.load(path)
+        except ImportError as exc:
+            # Unpickling an artifact fitted on another machine needs the same
+            # optional extra, so a missing module must surface as a typed error
+            # rather than a raw traceback at request time.
+            raise missing_ml_dependency("Loading a trained affect model", exc) from exc
+        validate_state(
+            payload,
+            model="TrainedAffect",
+            path=path,
+            required={"model": FITTED},
+            optional={
+                "training_examples": (int,),
+                "training_source": (str,),
+                "training_license": (str,),
+            },
+        )
         return cls(
             model=payload["model"],
             training_examples=int(payload.get("training_examples", 0)),

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/trained_breakdown.py

@@ -4,6 +4,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
 
+from ._deps import missing_joblib, missing_ml_dependency
+from .model_state import FITTED, validate_state
+
 
 def build_breakdown_pipeline():
     try:
@@ -11,10 +14,7 @@ def build_breakdown_pipeline():
         from sklearn.linear_model import SGDClassifier
         from sklearn.pipeline import FeatureUnion, Pipeline
     except ImportError as exc:
-        raise ImportError(
-            "TrainedBreakdown requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedBreakdown", exc) from exc
 
     features = FeatureUnion(
         [
@@ -115,7 +115,7 @@ class TrainedBreakdown:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Saving breakdown model requires joblib.") from exc
+            raise missing_joblib("Saving breakdown model", exc) from exc
 
         joblib.dump(
             {
@@ -132,9 +132,23 @@ class TrainedBreakdown:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Loading breakdown model requires joblib.") from exc
+            raise missing_joblib("Loading breakdown model", exc) from exc
 
-        payload = joblib.load(path)
+        try:
+            payload = joblib.load(path)
+        except ImportError as exc:
+            raise missing_ml_dependency("Loading breakdown model", exc) from exc
+        validate_state(
+            payload,
+            model="TrainedBreakdown",
+            path=path,
+            required={"model": FITTED},
+            optional={
+                "training_examples": (int,),
+                "positive_examples": (int,),
+                "threshold": (int, float),
+            },
+        )
         return cls(
             model=payload["model"],
             training_examples=int(payload.get("training_examples", 0)),

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/trained_disagreement.py

@@ -4,6 +4,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
 
+from ._deps import missing_joblib, missing_ml_dependency
+from .model_state import FITTED, validate_state
+
 COARSE_DISCOURSE_ARCHIVE_SHA256 = (
     "33cc25e906e677881c0031c1e134460b1e389fac707f2e52fe59b484dc6d0b61"
 )
@@ -15,10 +18,7 @@ def build_disagreement_pipeline():
         from sklearn.linear_model import SGDClassifier
         from sklearn.pipeline import FeatureUnion, Pipeline
     except ImportError as exc:
-        raise ImportError(
-            "TrainedDisagreement requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedDisagreement", exc) from exc
 
     features = FeatureUnion(
         [
@@ -120,7 +120,7 @@ class TrainedDisagreement:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Saving disagreement model requires joblib.") from exc
+            raise missing_joblib("Saving disagreement model", exc) from exc
 
         joblib.dump(
             {
@@ -137,9 +137,23 @@ class TrainedDisagreement:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Loading disagreement model requires joblib.") from exc
+            raise missing_joblib("Loading disagreement model", exc) from exc
 
-        payload = joblib.load(path)
+        try:
+            payload = joblib.load(path)
+        except ImportError as exc:
+            raise missing_ml_dependency("Loading disagreement model", exc) from exc
+        validate_state(
+            payload,
+            model="TrainedDisagreement",
+            path=path,
+            required={"model": FITTED},
+            optional={
+                "training_examples": (int,),
+                "positive_examples": (int,),
+                "threshold": (int, float),
+            },
+        )
         return cls(
             model=payload["model"],
             training_examples=int(payload.get("training_examples", 0)),

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/trained_intent.py

@@ -2,12 +2,15 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field, replace
+from functools import lru_cache
 from importlib import resources
 from pathlib import Path
 from typing import Iterable
 
+from ._deps import missing_joblib, missing_ml_dependency
 from .intent import HeuristicIntent, IntentState
 from .intent_belief import IntentBelief, decide_intent_action, fuse_dialogue_evidence
+from .model_state import FITTED, validate_state
 
 
 def build_pipeline():
@@ -17,10 +20,7 @@ def build_pipeline():
         from sklearn.linear_model import LogisticRegression
         from sklearn.pipeline import FeatureUnion, Pipeline
     except ImportError as exc:
-        raise ImportError(
-            "TrainedIntent requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedIntent", exc) from exc
 
     features = FeatureUnion(
         [
@@ -64,6 +64,62 @@ def bundled_training_records() -> list[dict]:
         return [json.loads(line) for line in fh if line.strip()]
 
 
+def bundled_records_path() -> Path:
+    """Locate the bundled corpus on the filesystem, when it has a path.
+
+    The cache key needs path+mtime so an edited corpus invalidates the memo.
+    Zipped/egg distributions expose no real path, in which case this raises and
+    the cache falls back to a stable key (a zipped corpus cannot change under
+    the running process anyway).
+    """
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        for candidate in (parent / "eq_layer" / "data", parent / "data"):
+            artifact = candidate / "intent_train.jsonl"
+            if artifact.is_file():
+                return artifact
+    raise FileNotFoundError("Bundled intent training corpus has no filesystem path.")
+
+
+def _bundled_cache_key(
+    confidence_threshold: float,
+    margin_threshold: float,
+) -> tuple[str, int, float, float]:
+    """Cache key for the bundled fit: artifact path + mtime + thresholds."""
+    try:
+        artifact = bundled_records_path()
+    except FileNotFoundError:
+        return (":resources:", 0, float(confidence_threshold), float(margin_threshold))
+    return (
+        str(artifact),
+        artifact.stat().st_mtime_ns,
+        float(confidence_threshold),
+        float(margin_threshold),
+    )
+
+
+@lru_cache(maxsize=8)
+def _fit_bundled(
+    cls: type["TrainedIntent"],
+    artifact: str,
+    mtime_ns: int,
+    confidence_threshold: float,
+    margin_threshold: float,
+) -> "TrainedIntent":
+    """Fit once per (artifact, mtime, thresholds); cached for the process."""
+    adapter = cls(
+        confidence_threshold=confidence_threshold,
+        margin_threshold=margin_threshold,
+    )
+    adapter.fit(bundled_training_records())
+    return adapter
+
+
+def clear_bundled_cache() -> None:
+    """Drop the memoised bundled fits (used by tests and long-lived processes)."""
+    _fit_bundled.cache_clear()
+
+
 @dataclass
 class TrainedIntent:
     """Trainable intent adapter.
@@ -86,12 +142,18 @@ class TrainedIntent:
         confidence_threshold: float = 0.40,
         margin_threshold: float = 0.08,
     ) -> "TrainedIntent":
-        adapter = cls(
-            confidence_threshold=confidence_threshold,
-            margin_threshold=margin_threshold,
+        """Return the bundled intent adapter, fitting it at most once.
+
+        The fit is deterministic but expensive (~seconds), so it is memoised
+        per process on (artifact path, artifact mtime, both thresholds). A
+        repeated call is O(1) and returns the *same* adapter instance, which
+        therefore has to be treated as read-only: callers must not call
+        ``fit`` on it or they would mutate every other user of the cache.
+        """
+        return _fit_bundled(
+            cls,
+            *_bundled_cache_key(confidence_threshold, margin_threshold),
         )
-        adapter.fit(bundled_training_records())
-        return adapter
 
     @classmethod
     def from_jsonl(
@@ -265,7 +327,7 @@ class TrainedIntent:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Saving a trained model requires joblib.") from exc
+            raise missing_joblib("Saving a trained intent model", exc) from exc
         joblib.dump(
             {
                 "model": self.model,
@@ -281,8 +343,21 @@ class TrainedIntent:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Loading a trained model requires joblib.") from exc
-        payload = joblib.load(path)
+            raise missing_joblib("Loading a trained intent model", exc) from exc
+        try:
+            payload = joblib.load(path)
+        except ImportError as exc:
+            raise missing_ml_dependency("Loading a trained intent model", exc) from exc
+        validate_state(
+            payload,
+            model="TrainedIntent",
+            path=path,
+            required={"model": FITTED, "confidence_threshold": (int, float)},
+            optional={
+                "margin_threshold": (int, float),
+                "training_examples": (int,),
+            },
+        )
         return cls(
             confidence_threshold=float(payload["confidence_threshold"]),
             margin_threshold=float(payload.get("margin_threshold", 0.08)),

{eq_layer-0.2.1 → eq_layer-0.2.3}/eq_layer/trained_subtext.py

@@ -4,7 +4,9 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Iterable
 
+from ._deps import missing_joblib, missing_ml_dependency
 from .affect import CORRECTION_MARKERS, DISCLOSURE_MARKERS, HeuristicAffect
+from .model_state import FITTED, validate_state
 from .policies import AffectState
 
 XDAILYDIALOG_COMMIT = "6e7ecf54c9f169215b4b8c18995c7aac74117127"
@@ -104,10 +106,7 @@ def build_feature_extractor():
         from sklearn.feature_extraction.text import TfidfVectorizer
         from sklearn.pipeline import FeatureUnion
     except ImportError as exc:
-        raise ImportError(
-            "TrainedSubtext requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedSubtext", exc) from exc
 
     return FeatureUnion(
         [
@@ -141,10 +140,7 @@ def build_classifier():
     try:
         from sklearn.linear_model import SGDClassifier
     except ImportError as exc:
-        raise ImportError(
-            "TrainedSubtext requires the optional ML dependencies. "
-            'Install with: pip install "eq-layer[ml]"'
-        ) from exc
+        raise missing_ml_dependency("TrainedSubtext", exc) from exc
 
     return SGDClassifier(
         loss="log_loss",
@@ -375,7 +371,7 @@ class TrainedSubtext:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Saving a trained subtext model requires joblib.") from exc
+            raise missing_joblib("Saving a trained subtext model", exc) from exc
 
         joblib.dump(
             {
@@ -394,9 +390,27 @@ class TrainedSubtext:
         try:
             import joblib
         except ImportError as exc:
-            raise ImportError("Loading a trained subtext model requires joblib.") from exc
+            raise missing_joblib("Loading a trained subtext model", exc) from exc
 
-        payload = joblib.load(path)
+        try:
+            payload = joblib.load(path)
+        except ImportError as exc:
+            raise missing_ml_dependency("Loading a trained subtext model", exc) from exc
+        validate_state(
+            payload,
+            model="TrainedSubtext",
+            path=path,
+            required={
+                "features": FITTED,
+                "act_model": FITTED,
+                "emotion_model": FITTED,
+            },
+            optional={
+                "training_examples": (int,),
+                "act_confidence_threshold": (int, float),
+                "emotion_confidence_threshold": (int, float),
+            },
+        )
         return cls(
             features=payload["features"],
             act_model=payload["act_model"],

{eq_layer-0.2.1 → eq_layer-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eq-layer"
-version = "0.2.1"
+version = "0.2.3"
 description = "Inspectable intent, affect, repair, uncertainty, and factored-action control for LLM responses"
 readme = "README.md"
 license = { text = "MIT" }
@@ -69,6 +69,9 @@ include = [
   "/THIRD_PARTY_DATA.md",
 ]
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [tool.ruff]
 line-length = 100