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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: eq-layer
-Version: 0.2.2
+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.2 → 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.2 → eq_layer-0.2.3}/eq_layer/__init__.py

@@ -1,3 +1,4 @@
+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
@@ -5,6 +6,7 @@ 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 (
@@ -22,6 +24,8 @@ from .tracker import AnnotationStanceResolver, ConversationTracker, StanceDecisi
 
 __all__ = [
     "__version__",
+    "OptionalDependencyError",
+    "ModelStateError",
     "AffectAdapter",
     "AffectState",
     "audit_from_generation_metadata",

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.2 → 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"
 
 
@@ -127,16 +131,17 @@ def _route(args: argparse.Namespace) -> int:
 def _doctor() -> int:
     from . import __version__
 
+    ml_available = ml_extra_available()
     payload = {
         "package": "eq-layer",
         "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
 
@@ -167,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.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.2 → 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.2 → 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.2 → 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.2 → 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.2 → 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.2 → eq_layer-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eq-layer"
-version = "0.2.2"
+version = "0.2.3"
 description = "Inspectable intent, affect, repair, uncertainty, and factored-action control for LLM responses"
 readme = "README.md"
 license = { text = "MIT" }