moral-spectrum-analyzer 0.1.0__tar.gz

moral_spectrum_analyzer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew H. Bond (San José State University)
+
+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.

moral_spectrum_analyzer-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: moral-spectrum-analyzer
+Version: 0.1.0
+Summary: The Moral Spectrum Analyzer — Geometric Ethics for Trustworthy AI: validation-gated, auditable multilingual content moderation.
+Author-email: "Andrew H. Bond" <andrew.bond@sjsu.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/ahb-sjsu/moral-spectrum-analyzer
+Project-URL: Repository, https://github.com/ahb-sjsu/moral-spectrum-analyzer
+Project-URL: Issues, https://github.com/ahb-sjsu/moral-spectrum-analyzer/issues
+Keywords: ai-ethics,trust,content-moderation,geometric-ethics,deme,invariance,moral-spectrum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: erisml-compiler>=0.9.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: click>=8.1
+Provides-Extra: perception
+Requires-Dist: xbse; extra == "perception"
+Requires-Dist: torch>=2.2; extra == "perception"
+Requires-Dist: sentence-transformers>=2.7; extra == "perception"
+Provides-Extra: baselines
+Requires-Dist: detoxify>=0.5; extra == "baselines"
+Provides-Extra: remote
+Requires-Dist: openai>=1.0; extra == "remote"
+Requires-Dist: paramiko>=3.0; extra == "remote"
+Provides-Extra: spectrum
+Requires-Dist: scikit-learn>=1.3; extra == "spectrum"
+Requires-Dist: matplotlib>=3.7; extra == "spectrum"
+Requires-Dist: numpy>=1.24; extra == "spectrum"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: black>=24.8; extra == "dev"
+Requires-Dist: ty>=0.0.1a1; extra == "dev"
+Dynamic: license-file
+
+# Moral Spectrum Analyzer
+
+[![CI](https://github.com/ahb-sjsu/moral-spectrum-analyzer/actions/workflows/ci.yaml/badge.svg)](https://github.com/ahb-sjsu/moral-spectrum-analyzer/actions/workflows/ci.yaml)
+[![PyPI](https://img.shields.io/pypi/v/moral-spectrum-analyzer.svg)](https://pypi.org/project/moral-spectrum-analyzer/)
+[![Python](https://img.shields.io/pypi/pyversions/moral-spectrum-analyzer.svg)](https://pypi.org/project/moral-spectrum-analyzer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+**Geometric Ethics for Trustworthy AI** — an instrument that reads a moderation decision not as one
+scalar, but as a **spectrum** across nine (+1 discovered) moral axes, grounds every number in a
+**cross-dataset-validated encoder**, holds the verdict **invariant** under re-description, and emits a
+**re-verifiable audit proof** behind every decision. *A worked instance of **Philosophy Engineering**.*
+
+Built for the **Global Trust Challenge (2026)**. Domain: **multilingual content moderation**.
+
+> Current AI systems collapse a morally significant decision into a single number. That scalar can't
+> say *which* value it acted on, drifts when you reword the same sentence, and — worst — can't tell you
+> what it fails to see. The Moral Spectrum Analyzer decomposes the signal per moral axis, moderates
+> where it is validated, **escalates and discloses where it is not**, and **discovers the moral
+> dimensions a fixed taxonomy is missing**.
+
+See **[CHARTER.md](CHARTER.md)** for the evaluated claims (each marked `[demonstrated]` / `[committed]`)
+and **[PLAN.md](PLAN.md)** for the build plan and milestones.
+
+## What this is
+
+A thin orchestration layer that **composes two existing libraries** — it does not fork them:
+
+- **[`xbse`](https://github.com/ahb-sjsu/xbse)** — the perception layer: small per-dimension moral
+  encoders, each cross-dataset **validated** by a shared, pre-registered gate.
+- **[`erisml-compiler`](https://github.com/ahb-sjsu/erisml-compiler)** — the DEME reasoning engine:
+  natural language → 9-dimension moral **tensor** → contraction to a verdict + moral residue, with
+  canonicalization and a hash-chained **audit bundle**.
+
+## The three trust beats
+
+1. **Grounded** — every dimension score traces to a validated encoder, or is flagged unvalidated.
+2. **Invariant** — reframing / translation does not move the verdict; a scalar-toxicity baseline drifts.
+3. **Contained** — you cannot game the verdict by relabeling or euphemism.
+
+## Install
+
+```bash
+pip install moral-spectrum-analyzer
+```
+
+Optional extras: `perception` (the `xbse` GPU encoders), `baselines`, `remote`, `spectrum`, `dev`.
+
+## Quickstart
+
+```bash
+msa perceive "They will attack and beat people with a weapon." --backend stub
+msa moderate "Doctors are hiding the cure — drink bleach to flush the virus."
+msa version
+```
+
+> The `stub` backend is a deterministic, **unvalidated** keyword heuristic for offline/CI use only.
+> Real, validated perception runs the `xbse` feeders on a GPU host; the demo replays those cached
+> real outputs (`--backend cached`). A stub number is never presented as a real one.
+
+## Develop
+
+```bash
+git clone https://github.com/ahb-sjsu/moral-spectrum-analyzer
+cd moral-spectrum-analyzer
+pip install -e ".[dev]"
+
+ruff check src tests      # lint
+black --check src tests   # format
+ty check src              # type-check
+pytest                    # 48 tests
+```
+
+## Release
+
+Tag-driven PyPI publish via GitHub Actions **Trusted Publishing** (OIDC, no stored token):
+
+```bash
+git tag v0.1.0 && git push --tags   # → builds sdist+wheel → publishes to PyPI
+```
+
+## Status
+
+Prototyping phase — the pipeline (content → moral spectrum → decision + residue → re-verifiable audit
+proof) runs end-to-end. See the milestone checklist in [PLAN.md](PLAN.md).
+
+## License
+
+MIT © Andrew H. Bond (SJSU).

moral_spectrum_analyzer-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Moral Spectrum Analyzer
+
+[![CI](https://github.com/ahb-sjsu/moral-spectrum-analyzer/actions/workflows/ci.yaml/badge.svg)](https://github.com/ahb-sjsu/moral-spectrum-analyzer/actions/workflows/ci.yaml)
+[![PyPI](https://img.shields.io/pypi/v/moral-spectrum-analyzer.svg)](https://pypi.org/project/moral-spectrum-analyzer/)
+[![Python](https://img.shields.io/pypi/pyversions/moral-spectrum-analyzer.svg)](https://pypi.org/project/moral-spectrum-analyzer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+**Geometric Ethics for Trustworthy AI** — an instrument that reads a moderation decision not as one
+scalar, but as a **spectrum** across nine (+1 discovered) moral axes, grounds every number in a
+**cross-dataset-validated encoder**, holds the verdict **invariant** under re-description, and emits a
+**re-verifiable audit proof** behind every decision. *A worked instance of **Philosophy Engineering**.*
+
+Built for the **Global Trust Challenge (2026)**. Domain: **multilingual content moderation**.
+
+> Current AI systems collapse a morally significant decision into a single number. That scalar can't
+> say *which* value it acted on, drifts when you reword the same sentence, and — worst — can't tell you
+> what it fails to see. The Moral Spectrum Analyzer decomposes the signal per moral axis, moderates
+> where it is validated, **escalates and discloses where it is not**, and **discovers the moral
+> dimensions a fixed taxonomy is missing**.
+
+See **[CHARTER.md](CHARTER.md)** for the evaluated claims (each marked `[demonstrated]` / `[committed]`)
+and **[PLAN.md](PLAN.md)** for the build plan and milestones.
+
+## What this is
+
+A thin orchestration layer that **composes two existing libraries** — it does not fork them:
+
+- **[`xbse`](https://github.com/ahb-sjsu/xbse)** — the perception layer: small per-dimension moral
+  encoders, each cross-dataset **validated** by a shared, pre-registered gate.
+- **[`erisml-compiler`](https://github.com/ahb-sjsu/erisml-compiler)** — the DEME reasoning engine:
+  natural language → 9-dimension moral **tensor** → contraction to a verdict + moral residue, with
+  canonicalization and a hash-chained **audit bundle**.
+
+## The three trust beats
+
+1. **Grounded** — every dimension score traces to a validated encoder, or is flagged unvalidated.
+2. **Invariant** — reframing / translation does not move the verdict; a scalar-toxicity baseline drifts.
+3. **Contained** — you cannot game the verdict by relabeling or euphemism.
+
+## Install
+
+```bash
+pip install moral-spectrum-analyzer
+```
+
+Optional extras: `perception` (the `xbse` GPU encoders), `baselines`, `remote`, `spectrum`, `dev`.
+
+## Quickstart
+
+```bash
+msa perceive "They will attack and beat people with a weapon." --backend stub
+msa moderate "Doctors are hiding the cure — drink bleach to flush the virus."
+msa version
+```
+
+> The `stub` backend is a deterministic, **unvalidated** keyword heuristic for offline/CI use only.
+> Real, validated perception runs the `xbse` feeders on a GPU host; the demo replays those cached
+> real outputs (`--backend cached`). A stub number is never presented as a real one.
+
+## Develop
+
+```bash
+git clone https://github.com/ahb-sjsu/moral-spectrum-analyzer
+cd moral-spectrum-analyzer
+pip install -e ".[dev]"
+
+ruff check src tests      # lint
+black --check src tests   # format
+ty check src              # type-check
+pytest                    # 48 tests
+```
+
+## Release
+
+Tag-driven PyPI publish via GitHub Actions **Trusted Publishing** (OIDC, no stored token):
+
+```bash
+git tag v0.1.0 && git push --tags   # → builds sdist+wheel → publishes to PyPI
+```
+
+## Status
+
+Prototyping phase — the pipeline (content → moral spectrum → decision + residue → re-verifiable audit
+proof) runs end-to-end. See the milestone checklist in [PLAN.md](PLAN.md).
+
+## License
+
+MIT © Andrew H. Bond (SJSU).

moral_spectrum_analyzer-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moral-spectrum-analyzer"
+version = "0.1.0"
+description = "The Moral Spectrum Analyzer — Geometric Ethics for Trustworthy AI: validation-gated, auditable multilingual content moderation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Andrew H. Bond", email = "andrew.bond@sjsu.edu" }]
+keywords = ["ai-ethics", "trust", "content-moderation", "geometric-ethics", "deme", "invariance", "moral-spectrum"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "erisml-compiler>=0.9.0",
+  "numpy>=1.24",
+  "click>=8.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ahb-sjsu/moral-spectrum-analyzer"
+Repository = "https://github.com/ahb-sjsu/moral-spectrum-analyzer"
+Issues = "https://github.com/ahb-sjsu/moral-spectrum-analyzer/issues"
+
+[project.optional-dependencies]
+# Real perception + GPU work (heavy; runs on a GPU host). `xbse` is the validated
+# per-dimension encoder layer.
+perception = ["xbse", "torch>=2.2", "sentence-transformers>=2.7"]
+# Scalar toxicity baseline (Phase 2/3).
+baselines = ["detoxify>=0.5"]
+# Black-box target-AI clients + remote driver.
+remote = ["openai>=1.0", "paramiko>=3.0"]
+# Moral-spectrum band (local analysis + viz).
+spectrum = ["scikit-learn>=1.3", "matplotlib>=3.7", "numpy>=1.24"]
+# Dev toolchain: test, lint, format, type-check.
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "black>=24.8", "ty>=0.0.1a1"]
+
+[project.scripts]
+msa = "moral_spectrum.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]  # line length is handled by black
+
+[tool.ty.environment]
+python-version = "3.10"
+root = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+source = ["moral_spectrum"]
+branch = true

moral_spectrum_analyzer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moral_spectrum_analyzer-0.1.0/src/moral_spectrum/__init__.py

@@ -0,0 +1,29 @@
+"""moral_spectrum — the Moral Spectrum Analyzer (Geometric Ethics for Trustworthy AI).
+
+Composes two existing libraries into one multilingual content-moderation prototype:
+
+  - xbse            : the perception layer (validated per-dimension moral encoders)
+  - erisml-compiler : the DEME reasoning engine (tensor, contraction, audit)
+
+This package orchestrates them; it does not fork either. See PLAN.md.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# DEME-9 moral dimensions, canonical k-axis order (re-exported from the compiler so
+# the whole prototype speaks one dimension vocabulary).
+from erisml_compiler.ir.v3.dimensions import MORAL_DIMENSIONS_V3 as DEME9  # noqa: E402
+
+# The Moral Spectrum Analyzer discovered — and then *validated* through the same pre-registered gate
+# as the compiler's own feeders — a 10th moral axis that the fixed DEME-9 taxonomy was missing:
+# `identity_attack` (docs/IDENTITY_ATTACK.md — cross-dataset held-out AUROC 0.80, +0.25 over its null,
+# fuzz 14.3, on two independent corpora). The prototype therefore EXTENDS ITSELF to a 10-axis working
+# vocabulary while leaving the compiler's canonical DEME-9 untouched. `DEME10` is what the live
+# pipeline speaks; `DEME9` remains the compiler's frozen taxonomy. This is the entry's
+# falsifiability-and-extensibility thesis made concrete: a discovered blind spot, repaired.
+IDENTITY_ATTACK = "identity_attack"
+DEME10 = (*DEME9, IDENTITY_ATTACK)
+
+__all__ = ["__version__", "DEME9", "DEME10", "IDENTITY_ATTACK"]

moral_spectrum_analyzer-0.1.0/src/moral_spectrum/audit.py

@@ -0,0 +1,104 @@
+"""Hash-chained DecisionProof — the audit artifact carrying validation provenance.
+
+Every moderation decision emits a `DecisionProof`: a SHA-256 over the exact inputs that produced
+it (source text, the DEME-9 moral vector, the per-dimension feeder validation records, the decision,
+and the tensor hash), chained to the previous proof. This is what makes a decision *auditable* —
+anyone can re-verify the chain and see which validated (or unvalidated) encoder produced each
+number. It is the self-contained seed of the Phase-4.5 audit-verification UI.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+
+GENESIS = "0" * 64
+
+
+def _sha256_json(obj) -> str:
+    return hashlib.sha256(
+        json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class DecisionProof:
+    """A tamper-evident record binding a decision to the exact inputs that produced it."""
+
+    source_text_sha256: str
+    perception_backend: str
+    all_validated: bool
+    moral_vector: list[float]  # DEME-9 signed values, canonical k-axis order
+    validation: list[dict]  # per-dimension feeder validation records
+    decision: dict  # ModerationDecision.as_dict()
+    tensor_sha256: str
+    prev_hash: str = GENESIS
+    proof_hash: str = ""
+    # Present only for decisions made under the invariance mechanism: the generated equivalence class
+    # (hashes + size + refused flag) that the perception was averaged over. Records the
+    # canonicalisation step so it is not a silent, unauditable transform (docs/INVARIANCE_FINDINGS.md).
+    equivalence_class: dict | None = None
+
+    # Fields that are part of the signed payload (everything except proof_hash itself).
+    _PAYLOAD = (
+        "source_text_sha256",
+        "perception_backend",
+        "all_validated",
+        "moral_vector",
+        "validation",
+        "decision",
+        "tensor_sha256",
+        "prev_hash",
+    )
+
+    def _payload(self) -> dict:
+        payload = {k: getattr(self, k) for k in self._PAYLOAD}
+        # Included only when set, so non-invariance proofs keep their exact prior hash.
+        if self.equivalence_class is not None:
+            payload["equivalence_class"] = self.equivalence_class
+        return payload
+
+    def compute_hash(self) -> str:
+        return _sha256_json(self._payload())
+
+    def finalize(self) -> DecisionProof:
+        self.proof_hash = self.compute_hash()
+        return self
+
+    def verify(self) -> bool:
+        """True iff the recomputed hash matches — i.e. nothing in the payload was tampered with."""
+        return bool(self.proof_hash) and self.proof_hash == self.compute_hash()
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ProofChain:
+    """An append-only chain of DecisionProofs. Each proof's prev_hash = the prior proof_hash."""
+
+    proofs: list[DecisionProof] = field(default_factory=list)
+
+    @property
+    def head(self) -> str:
+        return self.proofs[-1].proof_hash if self.proofs else GENESIS
+
+    def append(self, proof: DecisionProof) -> DecisionProof:
+        proof.prev_hash = self.head
+        proof.finalize()
+        self.proofs.append(proof)
+        return proof
+
+    def verify_chain(self) -> bool:
+        """True iff every proof verifies AND the prev_hash links are intact and ordered."""
+        prev = GENESIS
+        for p in self.proofs:
+            if p.prev_hash != prev or not p.verify():
+                return False
+            prev = p.proof_hash
+        return True

moral_spectrum_analyzer-0.1.0/src/moral_spectrum/classgen.py

@@ -0,0 +1,122 @@
+"""Inference-time equivalence-class generation — the deployable form of the BIP mechanism.
+
+The decision-layer invariance mechanism (`moral_spectrum.invariance_mechanism.average_perceptions`) averages a
+perception over the input's paraphrase **equivalence class**, then decides — so two surface forms of
+the same meaning yield ~the same verdict (θ_d 0.42, `docs/INVARIANCE_FINDINGS.md`). At deployment the
+class is not hand-authored; it must be **generated** at inference. That generation is a real part of
+the trust boundary (spec in `docs/INVARIANCE_FINDINGS.md`), so this module makes its failure mode
+explicit rather than silent:
+
+  - **Refuse-to-paraphrase → singleton class.** An adversary can *starve* the generator: overtly
+    harmful content the LLM refuses to rewrite yields no class members, i.e. no averaging, i.e. the
+    weakly-invariant raw score on exactly the content invariance matters most for. A singleton class
+    is flagged (`refused=True`, `singleton=True`) so the decision layer can default to **escalate**
+    instead of trusting the raw score.
+  - **Auditability.** The class carries per-member SHA-256 hashes so the averaging step — an input to
+    a system whose whole pitch is that nothing is unauditable — is itself recorded in the proof.
+
+A deterministic ``StubClassGenerator`` lets the whole path run and be tested offline (no network); the
+``LLMClassGenerator`` is the real one (NRP managed LLM).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+
+def _sha(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class EquivalenceClass:
+    """The input plus its generated meaning-preserving paraphrases (members[0] is the original)."""
+
+    original: str
+    members: tuple[str, ...]  # members[0] == original; the rest are paraphrases
+    generator: str  # provenance, e.g. "nrp:gpt-oss:reframe:k=5" or "stub"
+    refused: bool = False  # the generator produced nothing (refusal / empty / error)
+
+    @property
+    def size(self) -> int:
+        return len(self.members)
+
+    @property
+    def singleton(self) -> bool:
+        """True when there is nothing to average over (only the original) — no invariance applied."""
+        return len(self.members) <= 1
+
+    def member_hashes(self) -> list[str]:
+        return [_sha(m) for m in self.members]
+
+    def audit_record(self) -> dict:
+        """The class as it should appear in the DecisionProof — hashes, not raw text."""
+        return {
+            "class_size": self.size,
+            "singleton": self.singleton,
+            "refused": self.refused,
+            "generator": self.generator,
+            "member_sha256": self.member_hashes(),
+        }
+
+
+class ClassGenerator:
+    """Interface: turn one input into its equivalence class."""
+
+    def generate(self, text: str) -> EquivalenceClass:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class LLMClassGenerator(ClassGenerator):
+    """Generate the class with the NRP managed LLM. Refusal/empty ⇒ a flagged singleton class."""
+
+    def __init__(self, client=None, k: int = 5, style: str = "reframe"):
+        self.client = client
+        self.k = k
+        self.style = style
+
+    def _client(self):
+        if self.client is None:
+            from moral_spectrum.llm import NRPClient
+
+            self.client = NRPClient()
+        return self.client
+
+    def generate(self, text: str) -> EquivalenceClass:
+        try:
+            paras = self._client().paraphrase(text, k=self.k, style=self.style)
+        except Exception:
+            paras = []
+        model = getattr(self.client, "model", "llm")
+        gen = f"nrp:{model}:{self.style}:k={self.k}"
+        if not paras:
+            return EquivalenceClass(original=text, members=(text,), generator=gen, refused=True)
+        return EquivalenceClass(original=text, members=(text, *paras), generator=gen, refused=False)
+
+
+class StubClassGenerator(ClassGenerator):
+    """Deterministic offline class: light surface edits that preserve meaning. For tests + offline
+    runs — NOT a substitute for real paraphrases (it cannot exercise the refusal path)."""
+
+    def __init__(self, k: int = 3):
+        self.k = k
+
+    def generate(self, text: str) -> EquivalenceClass:
+        t = text.strip()
+        variants = [
+            t,
+            (t[0].lower() + t[1:]) if t else t,  # decapitalise
+            t.rstrip(".!"),  # drop terminal punctuation
+            f"Honestly, {t[0].lower() + t[1:]}" if t else t,  # benign prefix (meaning-preserving)
+        ]
+        seen, members = set(), []
+        for v in variants:
+            if v and v not in seen:
+                seen.add(v)
+                members.append(v)
+            if len(members) >= self.k + 1:
+                break
+        return EquivalenceClass(
+            original=text, members=tuple(members), generator="stub", refused=False
+        )

moral_spectrum_analyzer-0.1.0/src/moral_spectrum/cli.py

@@ -0,0 +1,84 @@
+"""msa command-line interface. Grows one subcommand per phase; today: perceive (stub-backed)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from moral_spectrum import DEME10, __version__
+from moral_spectrum.perception import get_backend
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__)
+def cli() -> None:
+    """Geometric Ethics for Trustworthy AI — GTC prototype."""
+
+
+@cli.command("perceive")
+@click.argument("text", type=str)
+@click.option("--backend", type=click.Choice(["stub", "cached", "atlas"]), default="stub")
+def cmd_perceive(text: str, backend: str) -> None:
+    """Score TEXT across the DEME-10 moral dimensions with the chosen perception backend."""
+    result = get_backend(backend).perceive(text)
+    click.echo(f"[backend] {result.backend}  validated={result.all_validated()}")
+    for dim in DEME10:
+        if dim not in result.scores:
+            continue
+        s = result.scores[dim]
+        click.echo(f"  {dim:24s} {s.value:+.3f}  conf={s.confidence:.2f}  {s.direction}")
+    if result.meta.get("warning"):
+        click.echo(f"[!] {result.meta['warning']}")
+
+
+@cli.command("moderate")
+@click.argument("text", type=str)
+@click.option("--backend", type=click.Choice(["stub", "cached", "atlas"]), default="stub")
+@click.option(
+    "--hard-flag",
+    "hard_flags",
+    multiple=True,
+    help="Hand-specified categorical hard-constraint veto(s), e.g. 'dosage_cap_exceeded'. Repeatable.",
+)
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Write report.html + result.json here. Default: out/",
+)
+def cmd_moderate(
+    text: str, backend: str, hard_flags: tuple[str, ...], out_dir: Path | None
+) -> None:
+    """Run TEXT through the end-to-end moderation spine."""
+    from moral_spectrum.pipeline import moderate
+    from moral_spectrum.report import render_html, result_to_json
+
+    result = moderate(text, backend=backend, hard_flags=list(hard_flags))
+    s = result.summary()
+    click.echo(
+        f"[decision] {s['action'].upper()}  S={s['satisfaction']:+.3f}  "
+        f"review={s['requires_human_review']}  validated={s['all_validated']}"
+    )
+    click.echo(f"[tensor]   principal={s['principal_dimension']}")
+    if result.decision.moral_residue:
+        click.echo(f"[residue]  {', '.join(r['dimension'] for r in result.decision.moral_residue)}")
+    click.echo(f"[audit]    proof={s['proof_hash'][:16]}…  verify={result.proof.verify()}")
+
+    out = out_dir or (Path("out"))
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "report.html").write_text(render_html(result), encoding="utf-8")
+    (out / "result.json").write_text(result_to_json(result), encoding="utf-8")
+    click.echo(f"[wrote]    {out / 'report.html'}  {out / 'result.json'}")
+
+
+@cli.command("version")
+def cmd_version() -> None:
+    """Print the prototype version."""
+    click.echo(json.dumps({"moral-spectrum-analyzer": __version__}))
+
+
+if __name__ == "__main__":
+    cli()