beyondnn 0.1.0__py3-none-any.whl

beyondnn/__init__.py

@@ -0,0 +1,82 @@
+"""BeyondNN: an interpretability evidence framework for PyTorch.
+
+Implemented: the trace schema (:mod:`beyondnn.schema`), provenance
+(:mod:`beyondnn.provenance`), trace recording (:func:`trace`,
+:func:`recording`, :class:`TraceResult`), persistence (``TraceResult.save``,
+:func:`load_trace`), and :func:`instrument` (``handle.explain`` returns
+INPUT -> WHY -> OUTPUT, where Phase-1 WHY is measured internal evidence, not a
+causal or attributed explanation).
+
+``import beyondnn`` does not import torch; the tracing names are loaded lazily on
+first use, so :mod:`beyondnn.schema` stays usable without torch.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from . import schema
+from .schema import EstimandScope, EvidenceStatus, Outcome, Relation, Verdict
+
+if TYPE_CHECKING:
+    from .attribution import attribute
+    from .audits import audit
+    from .core.persistence import load_trace
+    from .core.trace import TraceResult, recording, trace
+    from .explain import compose, instrument
+    from .interventions import intervene
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EstimandScope",
+    "EvidenceStatus",
+    "Outcome",
+    "Relation",
+    "TraceResult",
+    "Verdict",
+    "__version__",
+    "attribute",
+    "attribution",
+    "audit",
+    "audits",
+    "compose",
+    "concepts",
+    "faithfulness",
+    "instrument",
+    "intervene",
+    "interventions",
+    "load_trace",
+    "recording",
+    "schema",
+    "trace",
+]
+
+_LAZY = {
+    "trace": "beyondnn.core.trace",
+    "recording": "beyondnn.core.trace",
+    "TraceResult": "beyondnn.core.trace",
+    "load_trace": "beyondnn.core.persistence",
+    "instrument": "beyondnn.explain",
+    "compose": "beyondnn.explain",
+    "intervene": "beyondnn.interventions",
+    "attribute": "beyondnn.attribution",
+    "audit": "beyondnn.audits",
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("interventions", "attribution", "faithfulness", "concepts", "audits"):
+        import importlib
+
+        module = importlib.import_module(f"beyondnn.{name}")
+        globals()[name] = module
+        return module
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module 'beyondnn' has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module_name), name)
+    globals()[name] = value
+    return value

beyondnn/_testing/__init__.py

@@ -0,0 +1,7 @@
+"""Internal, unstable testing utilities. NOT public BeyondNN API.
+
+Contents may change or disappear without notice. Nothing here is exported from
+``beyondnn``. The reference models in :mod:`beyondnn._testing.models` are
+deliberately ordinary networks for testing BeyondNN's evidence machinery; they
+are not BeyondNN model architectures.
+"""

beyondnn/_testing/attribution_models.py

@@ -0,0 +1,84 @@
+"""Fixed-weight ground-truth models for Phase-3 attribution tests (internal, unstable).
+
+Input ``x = (x0, x1)`` of shape (1, 2); target ``y[0, 0]``. Expected attributions are
+derived analytically in docs/PHASE_3_PLAN.md (before any experiment ran).
+
+==========  ===================  ==============  ==============  =====================
+Model       F                    gradient        input x grad    IG, zero baseline
+==========  ===================  ==============  ==============  =====================
+Linear      2 x0 + 3 x1          [2, 3]          [2 x0, 3 x1]    [2 x0, 3 x1]
+Irrelevant  4 x0                 [4, 0]          [4 x0, 0]       [4 x0, 0]
+Product     x0 x1                [x1, x0]        [x0 x1, x0 x1]  [x0 x1 / 2, x0 x1 / 2]
+Saturating  tanh(x0) + x1        [sech^2 x0, 1]  [x0 sech^2 x0,  [tanh x0, x1]
+                                                  x1]
+==========  ===================  ==============  ==============  =====================
+
+``Twice`` applies one scalar linear map (weight 2) twice: ``y = lin(lin(x))``; the
+gradient at call 0's output is 2 and at call 1's output is 1. ``Aliased`` registers
+one module under two paths.
+"""
+
+from __future__ import annotations
+
+import torch
+from torch import nn
+
+__all__ = ["Aliased", "Irrelevant", "Linear", "Product", "Saturating", "Twice"]
+
+
+def _linear(weights: list[float]) -> nn.Linear:
+    layer = nn.Linear(len(weights), 1, bias=False)
+    with torch.no_grad():
+        layer.weight.copy_(torch.tensor([weights]))
+    return layer
+
+
+class Linear(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.lin = _linear([2.0, 3.0])
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        out: torch.Tensor = self.lin(x)
+        return out
+
+
+class Irrelevant(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.lin = _linear([4.0, 0.0])
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        out: torch.Tensor = self.lin(x)
+        return out
+
+
+class Product(nn.Module):
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return (x[:, 0] * x[:, 1]).unsqueeze(1)
+
+
+class Saturating(nn.Module):
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return (torch.tanh(x[:, 0]) + x[:, 1]).unsqueeze(1)
+
+
+class Twice(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.lin = _linear([2.0])
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        out: torch.Tensor = self.lin(self.lin(x))
+        return out
+
+
+class Aliased(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.first = _linear([1.0, 1.0])
+        self.alias = self.first
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        out: torch.Tensor = self.first(x)
+        return out