se-interpretive-kernel 0.1.0__py3-none-any.whl

se_interpretive_kernel-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: se-interpretive-kernel
+Version: 0.1.0
+Summary: Executable contract for the Structural Explainability interpretive kernel: finite kernel, generated occurrence regime, thresholds, witnesses, and comparison-lifting laws
+Project-URL: Changelog, https://github.com/structural-explainability/se-interpretive-kernel/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://structural-explainability.github.io/se-interpretive-kernel/
+Project-URL: Homepage, https://github.com/structural-explainability/se-interpretive-kernel
+Project-URL: Issues, https://github.com/structural-explainability/se-interpretive-kernel/issues
+Project-URL: Repository, https://github.com/structural-explainability/se-interpretive-kernel
+Author: Denise M. Case
+Maintainer: Denise M. Case
+License-Expression: MIT
+License-File: LICENSE
+Keywords: equivalence-relations,galois-connection,identity,interpretive-kernel,partitions,refinement,research-software,structural-explainability,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# se-interpretive-kernel
+
+[![PyPI](https://img.shields.io/pypi/v/se-interpretive-kernel?logo=pypi&label=pypi)](https://pypi.org/project/se-interpretive-kernel/)
+[![Docs Site](https://img.shields.io/badge/docs-site-blue?logo=github)](https://structural-explainability.github.io/se-interpretive-kernel/)
+[![Repo](https://img.shields.io/badge/repo-GitHub-black?logo=github)](https://github.com/structural-explainability/se-interpretive-kernel)
+[![Python](https://img.shields.io/pypi/pyversions/se-interpretive-kernel?logo=python)](https://pypi.org/project/se-interpretive-kernel/)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/structural-explainability/se-interpretive-kernel/blob/main/LICENSE)
+
+[![CI](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/ci-python-zensical.yml)
+[![Docs-Deploy](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/deploy-zensical.yml)
+[![Pre-Release](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/pre-release.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/pre-release.yml)
+[![Release](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/release-pypi.yml/badge.svg)](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/release-pypi.yml)
+[![Links](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-interpretive-kernel/actions/workflows/links.yml)
+[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/structural-explainability/se-interpretive-kernel/security)
+
+> An executable contract for the Structural Explainability (SE) **interpretive kernel**:
+> when a declared identity regime over frames induces well-defined judgments about the
+> objects an interpretation produces, and what it costs when it does not.
+
+## Install
+
+```bash
+pip install se-interpretive-kernel
+```
+
+Python 3.12 or newer. No runtime dependencies. The package is typed.
+
+## Quick start
+
+Two probes read two frames. The declared regime says frames `a` and `b` are the
+same, and outputs are compared by equality.
+
+```python
+from se_interpretive_kernel.artifact import Artifact
+from se_interpretive_kernel.explain import explain, format_steps
+from se_interpretive_kernel.generated import generated
+from se_interpretive_kernel.kernel import coherent
+from se_interpretive_kernel.partition import Partition
+from se_interpretive_kernel.witness import find_witness
+
+artifact = Artifact(
+    frames=("a", "b"),
+    outputs=("x", "y", "z"),
+    probes=("p", "q"),
+    table={("p", "a"): "x", ("p", "b"): "y", ("q", "a"): "y", ("q", "b"): "z"},
+)
+same = Partition.from_blocks(artifact.frames, [("a", "b")])
+equal = Partition.discrete(artifact.outputs)
+
+print(coherent(artifact, artifact.probes, same, equal))
+# False
+
+print(find_witness(artifact, artifact.probes, same, equal))
+# Witness(frame_1='a', frame_2='b', probe='p', output_1='x', output_2='y')
+
+print(generated(artifact, artifact.probes, same).blocks())
+# (('x', 'y', 'z'),)
+
+print(format_steps(explain(artifact, artifact.probes, same, "x", "z")))
+# 1. probe 'p' reads frame 'a' as 'x' and frame 'b' as 'y'; the frame regime relates those two frames
+# 2. probe 'q' reads frame 'a' as 'y' and frame 'b' as 'z'; the frame regime relates those two frames
+```
+
+The regime is coherent only if `x`, `y`, and `z` are called the same, and the
+derivation shows why.
+
+## Purpose
+
+An interpretation `I` maps a probe and a frame to structured output.
+Fix a finite probe domain `P` and an equivalence `rho` on outputs.
+The **interpretive kernel** relates two frames when no probe can tell
+them apart:
+
+```text
+F ~ker F'   iff   for every p in P, I(p, F) is rho-indistinguishable from I(p, F')
+```
+
+A declared identity regime over frames induces well-defined
+object-level judgments exactly when it refines the kernel, and every failure
+comes with a finite witness: the probe and the pair of frames on which
+the regime identifies what interpretation separates.
+
+The stronger result is the **threshold**.
+For a declared regime `phi`, the least output equivalence under which `phi` is
+coherent is generated directly by the pairs `phi` forces together:
+
+```text
+L(phi) = equivalence closure of { (I(p, F), I(p, F')) : p in P, F phi F' }
+```
+
+`L` is left adjoint to the kernel, so no search over the lattice is required.
+The result is a computed commitment rather than a pass or fail verdict:
+not
+"this regime is inadmissible" but
+"this regime is coherent only if you are willing to call these outputs the same".
+
+The construction is domain-agnostic.
+Interpretation is supplied by the consuming domain and not imported.
+
+The package reports commitments and differences.
+It reports whether a declared identity regime is consistent
+with a declared interpretation,
+what the regime obliges the outputs to be, and
+where two regimes disagree.
+It does not certify ground truth:
+when two regimes disagree,
+it shows where and why, and does not say which is correct.
+
+## Comparison Liftings Have Laws
+
+Comparing structured outputs requires carrying an output equivalence up to
+the structures:
+
+```text
+C : Eq(O) -> Eq(X)
+```
+
+The kernel construction needs `C` to preserve arbitrary meets.
+Complete meet homomorphisms of this shape are exactly the `Eq(O)`-valued
+generalized ultrametrics on `X`, so every one of them is given by a cost
+`delta(x, y)`: the least output identification that would make two objects
+the same.
+The cost must satisfy three laws, and `check_lifting_laws` is the finite test
+that decides whether a supplied comparison has them.
+
+Two comparisons in this package are present because they fail, and both
+failures are regressions that must keep failing.
+
+- **Indexed pointwise**: monotone, meet-preserving, and a lifting.
+- **Quotient-image equality**: monotone, but not meet-preserving, so not a
+  lifting.
+- **Optimal matching over bijections**: not a lifting, because the triangle
+  law fails.
+
+Quotient-image equality on unordered outputs is the natural way to compare
+occurrence sets and does not preserve meets, so no cost represents it.
+Optimal matching is the natural repair and violates the triangle law, because
+moving the meet over alternative bijections through the join needs a
+distributivity the partition lattice does not have.
+
+The surviving repair is a declared canonicalization, which fixes the index
+before the output regime is known.
+It restores every law, and it costs something: the identification it demands
+is no finer than the best matching would have required.
+That price is measured in the test suite rather than asserted.
+
+A canonicalization is therefore a declared artifact, not an implementation
+detail.
+One that is not injective identifies distinct objects at zero cost, which
+declares an identity without ever appearing as a declared identity regime.
+
+## Run
+
+```bash
+uv sync
+
+uv run pytest
+```
+
+## Developer
+
+### Clone and copy
+
+Open a machine terminal where you want the project:
+
+```shell
+git clone https://github.com/structural-explainability/se-interpretive-kernel
+
+cd se-interpretive-kernel
+code .
+```
+
+### Open in VS Code and Run
+
+In a VS Code terminal
+
+```pwsh
+.\sit
+
+uv run se-interpretive-kernel --random 2000 --seed 0
+```
+
+```shell
+# save progress
+git add -A
+git commit -m "update"
+git push -u origin main
+```
+
+## Planned
+
+The boundary of the current slice is explicit.
+
+- `outcome.py`: the tagged output domain carrying end, undefined, and error,
+  which makes length mismatch a declared comparison result rather than an
+  exception.
+- `signature.py`: declared roles for each variable. A variable in the probe
+  domain is a test condition, in the frame domain it is a thing whose
+  sameness is at issue, and in the output domain it is observable. The same
+  variable in three positions asks three different questions, so position is
+  a declaration and must be validated.
+
+## Related Repositories
+
+- [se-theory-interpretive-kernel](https://github.com/structural-explainability/se-theory-interpretive-kernel):
+  the Lean formalization of the same results. The two are independent
+  realizations of one contract, and disagreement between them means one of
+  the definitions is wrong.
+- [se-verification-operational-identity](https://github.com/structural-explainability/se-verification-operational-identity):
+  SE-210, whose refinement and four-way sibling positioning this construction
+  builds on.
+
+## Citation
+
+[CITATION.cff](https://github.com/structural-explainability/se-interpretive-kernel/blob/main/CITATION.cff)
+
+## Software Metadata
+
+[CodeMeta (`codemeta.json`)](https://github.com/structural-explainability/se-interpretive-kernel/blob/main/codemeta.json)
+
+## License
+
+[MIT](https://github.com/structural-explainability/se-interpretive-kernel/blob/main/LICENSE)
+
+## Repository Manifest
+
+[SE_MANIFEST.toml](https://github.com/structural-explainability/se-interpretive-kernel/blob/main/SE_MANIFEST.toml)

se_interpretive_kernel-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+se_interpretive_kernel/__init__.py,sha256=HJftBV3Hwbd-fnUUJc18kmjefqwPvJ8GjraD04RwH8Y,283
+se_interpretive_kernel/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+se_interpretive_kernel/artifact.py,sha256=o3FVtewRSE-BtiZIT6m3tyxbPJgkOvUYlYD9EE-f3kw,2941
+se_interpretive_kernel/cases.py,sha256=BhB87lmRZN8Kuy8GjdyCR5UHP4CWLfl6bBhkH7DnA0I,3686
+se_interpretive_kernel/check.py,sha256=XkUdUniZ0seybEkAs_-i9639CDkzUrA5soo0xQGJRoA,12296
+se_interpretive_kernel/cli.py,sha256=1omCSSiRkqyGTOWkOSf9jpKnW3pLI-T8Fz2eh-34jaU,97
+se_interpretive_kernel/demand.py,sha256=E-PCts6n35XmPhxG-eFpKoDG-jHmrQHa-UU55Lu0X3Q,2701
+se_interpretive_kernel/differences.py,sha256=AC_GgVZmERUwy_OiRaZWyPeMQbKslosWxyRmRrf23AE,2469
+se_interpretive_kernel/explain.py,sha256=WkqIy4MZ1n6PAKdERNT5ukTa20Tm_YJ-kXryoV7n5mg,7476
+se_interpretive_kernel/generated.py,sha256=0HJadzqqVK4TT1XOJIBLOxcMusFsC2ZR9NzcHZ-2OGI,3536
+se_interpretive_kernel/kernel.py,sha256=2zPqVFuSt6hHGbiKD8SWDIvEOx9AwSUK-Tahc8takzg,1982
+se_interpretive_kernel/lifting.py,sha256=cQ3n7KLkdyBSr01CJ0ICWo3qNTPPLRWK-kwbbefF8zY,13868
+se_interpretive_kernel/literal.py,sha256=ypIrQRnvcK16RtFO-4M9A7P9UgDIv5mjLGXTQWBaKrc,2732
+se_interpretive_kernel/loader.py,sha256=I4xhMl-gN9CPrC1AATt-NfWMiTetvMZ4JvUtvLPWtUE,8227
+se_interpretive_kernel/partition.py,sha256=bCkTALEAnUG-I7Z29cO5zktZ_nXToM7GjZ5v91rxgK8,13224
+se_interpretive_kernel/probes.py,sha256=D3JQDbbwk-Mss0mmtc9pVO4GLzHbybQdWjM5M1Pp8fE,4459
+se_interpretive_kernel/sampling.py,sha256=menI3G9GBzv6C36G_57QHJjMZSfJUE0ANXteA0h_j1c,1194
+se_interpretive_kernel/witness.py,sha256=dulJ3bDFbDMgS2Gg5ahPpoG-9CdBHRU6uxGNE3KiJIM,2292
+se_interpretive_kernel-0.1.0.dist-info/METADATA,sha256=jblefopF2clR0i0opVsPkY-6hmfM_e54tDJrYrYuJxc,11299
+se_interpretive_kernel-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+se_interpretive_kernel-0.1.0.dist-info/entry_points.txt,sha256=ELjA9hgrT2Oau--Jf4vZc47DyGIAYww9EyZV0YA0ohE,75
+se_interpretive_kernel-0.1.0.dist-info/licenses/LICENSE,sha256=Xs6IcjtQ_6V_-e6sSH0xOsGwgZ1zwlqOz12Tx4VMXvU,1068
+se_interpretive_kernel-0.1.0.dist-info/RECORD,,

se_interpretive_kernel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

se_interpretive_kernel-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+se-interpretive-kernel = se_interpretive_kernel.cli:main

se_interpretive_kernel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denise Case
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.