se-interpretive-kernel 0.1.0__tar.gz

se_interpretive_kernel-0.1.0/.gitignore

@@ -0,0 +1,369 @@
+# ============================================================
+# .gitignore (ALL-REPOS)
+# ============================================================
+# Updated: 2026-10-11
+#
+# WHAT: A Git configuration file that identifies files and directories
+#       that should not be included in the repository's version history.
+#       Git uses this file to determine which untracked files to ignore.
+#
+# WHEN: Use in professional repositories managed with Git.
+#       Git automatically applies these rules when working with files.
+#
+# WHY: Version the files we create and maintain for this project.
+#      Avoid tracking downloaded dependencies, generated output,
+#      temporary files, local settings, and sensitive information.
+#      Other projects maintain the source code and version history
+#      of their own dependencies.
+#
+# HOW: List file and directory patterns below.
+#      Patterns work across different languages, tools, and project types.
+#      Sections are organized by purpose for easier maintenance.
+#
+#      In VS Code, open the 'Outline view' in the Explorer sidebar to
+#      see and navigate the different sections of this file.
+#      Requires the recommended 'Comment Section Outline' extension
+#      (see .vscode/extensions.json).
+#
+# TOOLS: Git tracks changes to project files and maintains version history.
+#        .gitignore controls which untracked files Git ignores.
+#
+# SKILLS: Git, version control, repository management,
+#         file patterns, dependency management, and project maintenance.
+#
+# REQ: All professional GitHub project repositories MUST include .gitignore.
+# REQ: Never commit secrets or private credentials.
+#
+# OBS: .gitignore does not remove files already tracked by Git.
+# OBS: Dependency manifests and lockfiles should generally be committed
+#      even when downloaded dependencies are ignored.
+# OBS: Patterns for unused tools or languages are generally harmless.
+#
+# ALT: Repositories may customize ignores while preserving safety rules.
+# CUSTOM: Delete sections that are not needed for the project.
+# CUSTOM: Add project-specific patterns when necessary.
+#
+# ============================================================
+# === INTRO: How .gitignore patterns work ===
+# ============================================================
+# NOTE: .gitignore uses glob-style patterns, not regular expressions.
+#
+# /name
+# WHY: A leading slash anchors the pattern to the directory containing this
+# .gitignore file. In a repository-root .gitignore, /name matches only name
+# at the repository root.
+# EXAMPLE: /pyproject.toml.ruff ignores only the root-level temporary fragment.
+#
+# name/
+# WHY: A trailing slash means the pattern matches directories, not files.
+# EXAMPLE: bin/ ignores directories named bin and their contents.
+#
+# *.ext
+# WHY: An asterisk (*) matches any number of characters within one path component.
+# EXAMPLE: *.log ignores files ending in .log.
+#
+# **
+# WHY: A double asterisk (**) can match across directory levels.
+# EXAMPLE: **/src/**/_version.py matches generated _version.py files inside
+# src trees regardless of repository depth or package name.
+#
+# ?
+# WHY: A question mark (?) matches exactly one character within a path component.
+# EXAMPLE: temp?.txt matches temp1.txt and tempa.txt, but not temp10.txt.
+#
+# [abc]
+# WHY: Square brackets match one character from the listed set or range.
+# EXAMPLE: file[0-9].txt matches file0.txt through file9.txt.
+#
+# !pattern
+# WHY: An exclamation point (!) negates an earlier ignore rule and re-includes
+# a matching file when its parent directory has not itself been excluded.
+# EXAMPLE: !.env.example keeps the safe example file even though .env.* is ignored.
+#
+# # text
+# WHY: A leading # makes the line a comment unless the # is escaped.
+#
+# NOTE: Prefer the narrowest pattern that expresses the intent.
+# Anchored patterns such as /name are safer when
+# only a repository-root file should be ignored.
+# ============================================================
+
+# ============================================================
+# === SECTION: UNIVERSAL ===
+# ============================================================
+
+# === Environment variables and secrets ===
+
+# WHY: Never commit credentials or environment-specific configuration.
+*.env
+.env
+.env.*
+
+# WHY: Commit .env.example as a safe template showing which variables to set.
+# NOTE: Copy .env.example to .env locally and customize the local copy.
+!.env.example
+
+
+# === Private notes and local-only files ===
+
+# WHY: Private working notes should remain local unless intentionally published.
+PRIVATE-NOTES.md
+PRIVATE_NOTES.md
+
+# WHY: The root-level refs directory holds local reference papers and source
+# materials that should be cited or linked to rather than committed.
+# NOTE: The leading slash limits this rule to the repository-root refs directory.
+# ALT: Commit only reference material that is intentionally redistributable and
+# appropriate to include in the repository.
+/refs/
+
+
+# === Operating-system files ===
+
+# WHY: OS-generated metadata files are machine-specific and should not be tracked.
+.AppleDouble
+.DS_Store
+.LSOverride
+.Spotlight-V100/
+.Trashes
+._*
+Icon\r
+Thumbs.db
+desktop.ini
+ehthumbs.db
+
+
+# === Editors and IDEs ===
+
+# WHY: IDE metadata is generally machine-local and should not be tracked.
+*.code-workspace
+.idea/
+
+
+# === VS Code ===
+
+# WHY: Ignore editor state by default while allowing shared project configuration.
+# NOTE: Use .vscode/* (contents), not .vscode/ (directory). Git will not
+# re-include a file whose parent directory is excluded.
+.vscode/*
+!.vscode/ABOUT_THIS_FOLDER.md
+!.vscode/extensions.json
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/*.code-snippets
+
+
+# === Temporary, lock, and swap files ===
+
+# WHY: Temporary and swap files are machine-local noise and create meaningless diffs.
+*.swo
+*.swp
+*.tmp
+*~
+
+# WHY: Microsoft Office creates temporary owner/lock files beside open documents.
+# NOTE: These patterns cover Word, Excel, and PowerPoint temporary files without
+# ignoring the actual Office documents.
+~$*.doc*
+~$*.xls*
+~$*.ppt*
+
+# WHY: LibreOffice and OpenOffice create temporary lock files beside open documents.
+.~lock.*#
+
+
+# === Logs and generated runtime output ===
+
+# WHY: Ignore logs and runtime output by default.
+# ALT: Explicitly re-include a specific log only when it is intentionally used
+# as project evidence.
+*.log
+logs/
+# !/project.log
+
+
+# === Generic caches ===
+
+# WHY: Generic caches are machine-local and should not be tracked.
+.cache/
+
+
+# === Generic bin (binary) folder ===
+
+# WHY: The root-level bin directory contains generated executable or build output.
+# NOTE: The leading slash limits this rule to the repository-root bin directory
+# and avoids ignoring a nested source directory that happens to be named bin.
+/bin/
+
+
+# ============================================================
+# === SECTION: PROJECT DOCS ===
+# ============================================================
+
+# WHY: Static site build output is generated from the documentation source.
+# NOTE: Zensical uses site/ as the generated site output directory.
+site/
+
+# ============================================================
+# === SECTION: PYTHON ===
+# ============================================================
+
+# === Python environments ===
+
+# WHY: Virtual environments are machine-local and reproducible from project files.
+.venv/
+venv/
+
+
+# === Python project state ===
+
+# REQ: Do NOT git ignore .python-version.
+# WHY: Commit .python-version to declare the Python version used by the project.
+
+# REQ: Do NOT git ignore uv.lock.
+# WHY: Commit uv.lock to preserve the resolved dependency environment and use it
+# in CI/CD pipelines.
+
+# WHY: Generated SCM version modules should not be tracked.
+# NOTE: This recursive pattern works regardless of repository depth or package name.
+**/src/**/_version.py
+
+
+# === Python bytecode ===
+
+# WHY: Python bytecode is generated automatically and is machine-specific.
+*.pyc
+*.pyd
+*.pyo
+__pycache__/
+
+
+# === Python build and packaging artifacts ===
+
+# WHY: Build and packaging artifacts are generated from project source.
+*.egg
+*.egg-info/
+*.whl
+.eggs/
+build/
+dist/
+
+
+# === Python testing and coverage output ===
+
+# WHY: Test and coverage reports are generated and can be reproduced.
+.coverage
+.coverage.*
+.pytest_cache/
+htmlcov/
+coverage.xml
+coverage.json
+coverage.lcov
+
+
+# === Python tooling caches ===
+
+# WHY: Tooling caches improve local performance but should not be tracked.
+.mypy_cache/
+.pytype/
+.ruff_cache/
+.tox/
+
+
+# === Python notebooks and marimo ===
+
+# WHY: Jupyter notebook checkpoint state is generated.
+.ipynb_checkpoints/
+
+# REQ: Do NOT git ignore layouts/ when using marimo custom layouts.
+# WHY: Marimo layout files are project source and should be version controlled.
+
+# REQ: Do NOT git ignore public/ when it contains source assets or data
+# used by marimo or WASM applications.
+# WHY: These files may be required to reproduce or publish the application.
+
+
+# ============================================================
+# === SECTION: NODE ===
+# ============================================================
+# Some tooling and projects require Node.js and its dependencies.
+
+# WHY: Node dependencies are restored from package-lock.json with npm ci.
+node_modules/
+
+# REQ: Do NOT git ignore package-lock.json.
+# WHY: Commit package-lock.json to preserve reproducible Node dependency
+# resolution and use it in CI/CD pipelines.
+
+
+# === Node package-manager caches ===
+
+# WHY: Package-manager caches are machine-local and should not be tracked.
+.npm/
+.pnpm-store/
+.yarn/cache/
+.yarn/unplugged/
+.yarn/build-state.yml
+.yarn/install-state.gz
+
+# ============================================================
+# === SECTION: TYPESCRIPT AND JAVASCRIPT ===
+# ============================================================
+
+# === TypeScript and JavaScript build output ===
+
+# WHY: Compiled JavaScript output is generated from TypeScript source.
+out/
+
+# WHY: TypeScript incremental build metadata is generated.
+*.tsbuildinfo
+
+
+# === TypeScript and JavaScript tooling caches ===
+
+# WHY: Tooling caches and generated coverage output should not be tracked.
+.eslintcache
+.nyc_output/
+coverage/
+
+
+# === VS Code extension test and package output ===
+
+# WHY: VS Code extension test-host files are generated by @vscode/test-electron.
+.vscode-test/
+
+# WHY: VSIX packages are generated release artifacts.
+*.vsix
+
+# ============================================================
+# === SECTION: COMPUTER-CHECKED MATHEMATICAL PROOFS (LEAN) ===
+# ============================================================
+
+# === Lean ===
+
+# WHAT: Lean is a programming language and proof assistant used to
+#       express mathematical definitions, theorems, and proofs.
+#       It can also verify properties of software and logical systems.
+#       Lean checks whether formal proofs satisfy their stated rules.
+#
+# WHY: Lake, Lean's project and build tool, generates build files
+#      and downloads dependencies that do not need to be committed.
+.lake/
+lake-packages/
+/docbuild/
+
+
+# ============================================================
+# === SECTION: CUSTOM GENERATED ARTIFACTS ===
+# ============================================================
+
+# === Generated files for supported repositories ===
+
+# WHY: Generated analytics and guide-context artifacts should be rebuilt rather
+# than committed.
+# NOTE: These entries are harmless in repositories that do not generate them.
+docs/assets/data/view-analytics.json
+docs/assets/data/guide-context.json
+# marimo WASM export; built at deploy time, not committed
+docs/app/

se_interpretive_kernel-0.1.0/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+All notable changes to this project will be documented in this file.
+
+The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**
+and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.1.0] - 2026-10-31
+
+### Added
+
+- Added the initial Python package, the executable companion to the Lean
+  library `se-theory-interpretive-kernel`.
+- Added the finite partition algebra and the comparison lifting protocol with
+  the three cost laws and their validators.
+- Added the finite artifact: frames, outputs, probes, and a total
+  interpretation table.
+- Added the interpretation-induced kernel, coherence, the generated occurrence
+  regime, and the interpretive threshold.
+- Added finite incompatibility witnesses and pairwise interpretive demand with
+  the generalized ultrametric laws.
+- Added an independent pair-set oracle for the partition-based
+  implementation.
+- Added finite cases mirroring the Lean examples.
+- Added exhaustive law checks over every probe family and every pair of
+  regimes, and seeded random artifacts, run by the command-line interface.
+- Added documentation, CI, release automation, and the repository manifest.
+- Added probe sensitivity: separating probes, load-bearing probes, minimal
+  probe sets, and the threshold each probe forces alone.
+- Added derivations for forced identifications: the chain of probes and frame
+  pairs that connects two outputs in the threshold.
+- Added a loader that builds an artifact and a frame regime from tabular data,
+  with declared handling of empty cells.
+- Added a report of the differences between two frame regimes.
+
+---
+
+## Notes on Versioning and Releases
+
+- We use **SemVer**:
+  - **MAJOR** - breaking changes
+  - **MINOR** - backward-compatible features
+  - **PATCH** - fixes, documentation, tests, tooling
+- Versions are driven by git tags. Tag `vX.Y.Z` to release.
+- Docs are deployed per version tag and aliased to **latest**.
+
+## Release Procedure (Required)
+
+Follow these steps exactly when creating a new release.
+
+### Task 1. Update release metadata (manual edits)
+
+1.1. `CITATION.cff` - update `version` and `date-released`
+1.2. `CHANGELOG.md` - add section, move unreleased entries, update links
+1.3. `pyproject.toml` - update build system `fallback-version`
+1.4. `codemeta.json` - update `version` and `datePublished`
+
+### Task 2. Validate
+
+```pwsh
+.\sit.ps1
+
+uv lock
+foreach ($v in '3.12','3.13','3.14','3.15') {
+  Write-Host "=== Python $v"
+  uv run --isolated --frozen --python $v --no-default-groups --group dev python -m pytest -q
+}
+
+uvx gha-tools autoupdate --pin=all --write .github/workflows
+
+uvx zizmor@latest .github/
+# suppressed and informational are okay
+
+uvx cffconvert --validate
+uvx se-manifest-schema validate-manifest --strict
+
+# This may take a little time
+uv run se-interpretive-kernel --random 2000 --seed 0
+
+uv run python -c "import shutil; from pathlib import Path; shutil.rmtree(Path('dist'), ignore_errors=True)"
+
+uv build
+uvx twine check --strict dist/*
+
+uv run python -c "import pathlib, zipfile; wheels=list(pathlib.Path('dist').glob('*.whl')); assert wheels, 'No wheel found'; wheel=wheels[-1]; names=zipfile.ZipFile(wheel).namelist(); packaged=[n for n in names if n.startswith('se_interpretive_kernel/')]; print(packaged); assert packaged, 'Package files missing from wheel'"
+```
+
+### Task 3. Commit, push, tag
+
+```shell
+git add -A
+git commit -m "Prepare X.Y.Z"
+git push -u origin main
+```
+
+Verify actions run on GitHub. After success:
+
+```shell
+git tag vX.Y.Z -m "X.Y.Z"
+git push origin vX.Y.Z
+```
+
+### Task 4. Verify the Release and Zenodo archive
+
+The release workflow creates a GitHub Release automatically.
+To verify:
+
+```shell
+gh release view vX.Y.Z                    # confirm Release exists with notes + artifacts
+gh run list --workflow=release-pypi.yml   # confirm the workflow succeeded
+```
+
+Confirm Zenodo shows a new version-specific DOI for this release
+and that it remains linked under the
+repository's concept DOI recorded in `CITATION.cff`.
+
+## Only As Needed (delete a tag)
+
+```shell
+git tag -d vX.Y.Z
+git push origin :refs/tags/vX.Y.Z
+```
+
+## Links
+
+[Unreleased]: https://github.com/structural-explainability/se-interpretive-kernel/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/structural-explainability/se-interpretive-kernel/releases/tag/v0.1.0
+
+<!-- markdownlint-enable MD024 -->

se_interpretive_kernel-0.1.0/CITATION.cff

@@ -0,0 +1,51 @@
+# ============================================================
+# CITATION.cff (How to cite this project)
+# ============================================================
+# REQ.UNIVERSAL: Professional open projects SHOULD include this file.
+# May reference upstream dependencies, but must not refer to downstream.
+# USAGE: See https://citation-file-format.github.io/ for details.
+# check with:
+# uvx cffconvert --validate
+
+cff-version: "1.2.0"
+type: software
+message: "If you use this work, please cite it using the metadata in this file."
+
+title: "Structural Explainability Verification: Interpretive Kernel"
+version: "0.1.0"
+date-released: "2026-10-31"
+
+authors:
+  - family-names: Case
+    given-names: Denise M.
+    orcid: "https://orcid.org/0000-0001-6165-7389"
+    affiliation: "Northwest Missouri State University, School of Computer Science and Information Systems, Maryville, MO, USA"
+
+repository-code: "https://github.com/structural-explainability/se-interpretive-kernel"
+url: "https://github.com/structural-explainability/se-interpretive-kernel"
+
+license: MIT
+
+abstract: >
+  A Python implementation and verification harness for the finite
+  interpretive kernel of Structural Explainability.
+  Given finite frames, outputs, and probes with a total interpretation,
+  the software computes the interpretation-induced kernel of an output
+  regime, the generated occurrence regime and interpretive threshold of a
+  frame regime, finite incompatibility witnesses, and pairwise interpretive
+  demand.
+  It checks the adjunction between kernel and generated regime, their
+  preservation properties, and the laws a comparison lifting must satisfy,
+  exhaustively on small cases and on seeded random artifacts, against an
+  independent pair-set oracle.
+
+keywords:
+  - structural-explainability
+  - interpretive-kernel
+  - interpretation
+  - equivalence-relations
+  - partitions
+  - refinement
+  - galois-connection
+  - verification
+  - differential-testing

se_interpretive_kernel-0.1.0/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.