semantic-trust 0.1.0__py3-none-any.whl

semantic_trust-0.1.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: semantic-trust
+Version: 0.1.0
+Summary: Score and certify dbt Semantic Layer models — trust bands, gates, and dbt-parse certification.
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Provides-Extra: ci
+Requires-Dist: pytest>=8.0; extra == "ci"
+Requires-Dist: hypothesis>=6.0; extra == "ci"
+Requires-Dist: pyyaml>=6.0; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: dbt-metricflow<0.14,>=0.13; extra == "dev"
+Dynamic: license-file

semantic_trust-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+semantic_trust-0.1.0.dist-info/licenses/LICENSE,sha256=1r0o_UhrOmuTUzlbt5iEVop1Fv5ZO8RjvYGMNjX4oWo,1068
+trust/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trust/cli.py,sha256=-4aJu9cjC6OJVB4K2iX6drH_UpdG5lh9Azu3gW-WtL0,4953
+trust/compile.py,sha256=XbwwQI2OHyY46yybq9ZIXvDDh6_2H5Q4Yv4TNf7Kb7I,1060
+trust/config.py,sha256=O2dIO9FdRy05Zv6jhxRoKZLumpaBDmdrz1R7zw5yVT4,1186
+trust/joinability.py,sha256=HAW5eKfiC5tQKMBI4Zelh8hC_yaGdwyctNqJtKfuvgM,8471
+trust/judgment.py,sha256=dIzYuuR54YCSgsH_1XjgQvpr1e7MSm8xo-eSHGZrD6Q,3899
+trust/manifest_loader.py,sha256=gVu2X5iEAkgC8WCznhpSovFg4eA43aNqAS04cbRF6wg,6474
+trust/manifest_scaffold.py,sha256=JTdCIDvkrb2QF5E29hKpIfrdmRollheeET7bOqoB404,3783
+trust/mcp_server.py,sha256=rtopQD_TWnD-SjiXbBKFsDWC5BZvnAAHOx5EQSdPnik,9177
+trust/normalized.py,sha256=OFNGR39W5yQtETFvjahahK8Gj-j2k8s8Q3W_yT8S5kU,869
+trust/ownership.py,sha256=4SLmFQUAtJF9A-YhY7ZMJ6lewXOL_DuMwogMCMApAIE,3423
+trust/report.py,sha256=hii2CQbNOPmhJcxF1LWaQF5pVzxonYy40KOwMnlMt6A,4329
+trust/scorer.py,sha256=71cJFX0O7eC-LdsEesDDWEP1BZBTuMNVtDrCG_StwIU,11521
+trust/spec_detect.py,sha256=lm2eRLsJZ3PkK8DcTqALUbEKpXvf3ewPCjOgVcohcbc,1375
+trust/uniqueness.py,sha256=PZGyuvCj0iWlilz6Xit2MOmD3gQAXsvsfHDxmD6xHCU,2732
+semantic_trust-0.1.0.dist-info/METADATA,sha256=DUxkvQVRmb-b42lwB1o387PTy9Ssyafs5ilSMbjEBLs,616
+semantic_trust-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+semantic_trust-0.1.0.dist-info/entry_points.txt,sha256=_26KQWYsv1EnYiK0aBpCZIAL4Md13_dwmzDW8HWm-88,97
+semantic_trust-0.1.0.dist-info/top_level.txt,sha256=NzvF6jjub_MhDLfrB0muRk25AxCu4iFX0dzIHx9d1uU,6
+semantic_trust-0.1.0.dist-info/RECORD,,

semantic_trust-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semantic_trust-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+semantic-trust = trust.cli:main_cli
+semantic-trust-mcp = trust.mcp_server:main

semantic_trust-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravish Jain
+
+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.

semantic_trust-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trust

trust/cli.py

@@ -0,0 +1,119 @@
+"""
+Local dev CLI for the trust scorer. NOT the skill-facing interface in production —
+skills consume the MCP server (trust/mcp_server.py, AD-1).
+
+Retained for: manual spot-checks during development, smoke tests, Task 3 wiring smoke.
+"""
+import json, sys
+from trust.manifest_loader import load_models, load_metrics
+from trust.uniqueness import find_collisions
+from trust.joinability import check_joinability
+from trust.scorer import score_model
+
+
+def _metrics_for_model(sm, all_metrics):
+    """
+    Return metrics owned by this semantic model.
+
+    Attribution is exact via each metric's owner_model field, stamped at load time:
+    - Latest spec: STRUCTURAL — a simple metric is owned by the model it is nested
+      under (semantic_model.metrics). No column/substring matching.
+    - Legacy spec: the semantic_model that DEFINES the measure the metric references
+      (type_params.measure → SM).
+    Cross-model metrics (latest derived/ratio) have owner_model=None and match no model.
+    """
+    return [m for m in all_metrics if m.owner_model == sm.name]
+
+
+def _orphan_collision_warnings(all_metrics: list, collisions: list) -> list[str]:
+    """
+    Build warning strings for collisions that involve at least one unattributed
+    (owner_model=None) metric.
+
+    Orphan metrics are excluded from any single model's gate, so a collision among
+    them would otherwise pass clean-and-silent. This helper surfaces BOTH formula and
+    name collisions that involve an orphan so they are visible in the report.
+
+    Note: a name collision between two orphan metrics is unreachable via real dbt —
+    dbt enforces unique metric names at parse time. This path is retained as
+    defense-in-depth and is unit-tested directly in tests/test_cli.py.
+
+    Args:
+        all_metrics: full list of NormalizedMetric for the project.
+        collisions:  output of find_collisions(all_metrics), each a dict with keys
+                     {kind, a, b, files}.
+
+    Returns:
+        List of human-readable warning strings (may be empty).
+    """
+    unattributed_names = {m.name for m in all_metrics if m.owner_model is None}
+    warnings: list[str] = []
+    for c in collisions:
+        kind = c.get("kind")
+        if kind not in ("formula", "name"):
+            continue
+        label = "formula collision" if kind == "formula" else "name collision"
+        if c.get("a") in unattributed_names:
+            warnings.append(
+                f"unattributed metric '{c['a']}' has {label} with '{c['b']}'"
+            )
+        elif c.get("b") in unattributed_names:
+            warnings.append(
+                f"unattributed metric '{c['b']}' has {label} with '{c['a']}'"
+            )
+    return warnings
+
+
+def build_report_object(project_dir: str, model_name: str):
+    """
+    Build the fully-populated ModelReport object for *model_name*.
+
+    Returns a ModelReport on success, or a dict {"model": ..., "error": ...} if the
+    semantic model is not found. Callers that need the object for apply_judgment must
+    check for the error dict first (isinstance check on dict).
+
+    This is the shared implementation beneath build_report (dict) and the MCP
+    validate_semantic_model handler (object).  Back-compat: build_report's dict
+    contract is preserved by calling .to_dict() on the result.
+    """
+    from trust.report import ModelReport  # avoid circular at module level
+    models = load_models(project_dir)
+    sm = next((m for m in models if m.name == model_name), None)
+    if sm is None:
+        return {"model": model_name, "error": "semantic model not found in project"}
+    all_metrics = load_metrics(project_dir)
+    collisions = find_collisions(all_metrics)
+    model_metrics = _metrics_for_model(sm, all_metrics)
+    # Joinability needs ALL models — compute cross-model issues then filter to this model.
+    all_j_issues = check_joinability(models)
+    model_j_issues = [i for i in all_j_issues if i.location == sm.source_file]
+    rep = score_model(
+        sm, model_metrics, collisions,
+        joinability_issues=model_j_issues,
+        project_dir=project_dir,
+    )
+    unattributed = [m for m in all_metrics if m.owner_model is None]
+    rep.warnings = _orphan_collision_warnings(all_metrics, collisions)
+    rep.unattributed_metrics = len(unattributed)
+    return rep
+
+
+def build_report(project_dir: str, model_name: str) -> dict:
+    """Return the deterministic trust report as a plain dict (back-compat public API)."""
+    result = build_report_object(project_dir, model_name)
+    if isinstance(result, dict):
+        # error path — already a dict
+        return result
+    return result.to_dict()
+
+
+def main_cli():
+    if len(sys.argv) < 3:
+        print("usage: python -m trust.cli <project_dir> <model_name>", file=sys.stderr)
+        sys.exit(1)
+    project_dir, model_name = sys.argv[1], sys.argv[2]
+    print(json.dumps(build_report(project_dir, model_name), indent=2))
+
+
+if __name__ == "__main__":
+    main_cli()

trust/compile.py

@@ -0,0 +1,28 @@
+"""Production-path helper: run the user's own `dbt parse` to (re)generate
+target/semantic_manifest.json, then the engine reads it. Version-agnostic:
+`dbt parse` works for both legacy (1.6-1.11) and latest (1.12+) specs.
+(mf validate-configs is legacy-only — dbt-metricflow pins dbt-core <1.12 — so
+dbt parse, not mf, is the universal compile gate.)"""
+import os
+import subprocess
+
+
+def compile_manifest(project_dir: str, profiles_dir: str | None = None) -> dict:
+    env = dict(os.environ)
+    env["DBT_PROJECT_DIR"] = project_dir
+    if profiles_dir:
+        env["DBT_PROFILES_DIR"] = profiles_dir
+    proc = subprocess.run(
+        ["dbt", "parse"],
+        cwd=project_dir, env=env,
+        capture_output=True, text=True,
+    )
+    manifest_path = os.path.join(project_dir, "target", "semantic_manifest.json")
+    ok = proc.returncode == 0 and os.path.exists(manifest_path)
+    return {
+        "ok": ok,
+        "returncode": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+        "manifest_path": manifest_path,
+    }

trust/config.py

@@ -0,0 +1,37 @@
+"""
+trust/config.py — load optional project-level config from .semantic-trust.json.
+
+Safe default: if file is missing or key is absent → empty list.
+An empty approved_email_domains list means NO domain check is applied (not a failure).
+
+Config file format (.semantic-trust.json):
+    {"approved_email_domains": ["example.com", "corp.io"]}
+"""
+import json
+import os
+
+
+def load_config(project_dir: str) -> dict:
+    """
+    Read .semantic-trust.json from project_dir (if it exists).
+
+    Returns a dict with at minimum:
+        {"approved_email_domains": [...]}
+
+    SAFE DEFAULT: missing file, empty file, or absent key → empty list.
+    Never hardcodes any domain — the allowlist comes exclusively from the file.
+    """
+    config_path = os.path.join(project_dir, ".semantic-trust.json")
+    raw: dict = {}
+    if os.path.isfile(config_path):
+        with open(config_path, "r") as fh:
+            try:
+                loaded = json.load(fh)
+                if isinstance(loaded, dict):
+                    raw = loaded
+            except json.JSONDecodeError:
+                pass
+
+    return {
+        "approved_email_domains": raw.get("approved_email_domains") or [],
+    }

trust/joinability.py

@@ -0,0 +1,216 @@
+"""
+Cross-model joinability gate [J] (Task 3.1b).
+
+Produces Issue(severity="warning", provenance="deterministic") for:
+  - joinability_orphan : an entity name appears on exactly one model
+                         (cannot participate in a join).
+  - joinability_parity : the same *conceptual* join partner resolves to
+                         different entity names across models — detected
+                         when entity names share a common stem but differ
+                         in suffix (e.g. "customer" vs "customer_id") while
+                         being used as join-compatible types (primary/foreign).
+
+Orphan detection strategy
+--------------------------
+MetricFlow ships `CommonEntitysRule` in
+  metricflow_semantic_interfaces.validations.common_entities
+This rule does the same orphan check but requires constructing MetricFlow's
+internal SemanticManifest/SemanticModel objects.  We confirm the import
+succeeds (proving the rule exists and the dependency is present) and then
+implement the equivalent logic over NormalizedModel directly — avoiding the
+overhead of building MetricFlow's internal object graph just to call one rule.
+`CommonEntitysRule` is a NON-DEFAULT MetricFlow rule: it is NOT included in
+the validator's DEFAULT_RULES set; callers must add it explicitly.
+
+Parity detection strategy
+--------------------------
+MetricFlow has no built-in cross-model name-parity check.  We implement it:
+  1. Normalise each entity name to a *stem* (strip trailing `_id`, `_key`).
+  2. Group entity names by stem across all models.
+  3. When a stem maps to more than one distinct entity name, the names
+     are mismatched join-partner candidates — flag joinability_parity.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from trust.report import Issue
+
+if TYPE_CHECKING:
+    from trust.normalized import NormalizedModel
+
+# --- MetricFlow import probe (non-default rule; light dependency) ---
+# CommonEntitysRule is a non-default MetricFlow validation rule.  We confirm
+# the import works so users know the dependency is present, then fall back to
+# our own equivalent scan over NormalizedModel.entities.
+try:
+    from metricflow_semantic_interfaces.validations.common_entities import (  # noqa: F401
+        CommonEntitysRule,
+    )
+    _MF_COMMON_ENTITIES_AVAILABLE = True
+except ImportError:
+    _MF_COMMON_ENTITIES_AVAILABLE = False
+
+# Types that represent "one end" of a join (primary key side).
+_PRIMARY_TYPES = {"primary", "natural"}
+# Types that reference the primary side (foreign key side).
+_FOREIGN_TYPES = {"foreign"}
+# Both sides together — entities of other types (e.g. "unique") are skipped.
+_JOIN_TYPES = _PRIMARY_TYPES | _FOREIGN_TYPES
+
+
+def _stem(name: str) -> str:
+    """Normalise an entity name to a stem by stripping common id-suffix patterns."""
+    for suffix in ("_id", "_key", "_ref"):
+        if name.endswith(suffix) and len(name) > len(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def _orphan_issues(models: list) -> list[Issue]:
+    """
+    Flag entity names that appear on exactly one model.
+
+    Logic mirrors CommonEntitysRule._map_semantic_model_entities but operates
+    on NormalizedModel.entities dicts ({name, type}) instead of MetricFlow's
+    internal Entity/SemanticModel objects.
+
+    Source recorded as "own_scan" when MF rule is unavailable,
+    "mf_equivalent" when the import confirmed availability.
+    """
+    # Map entity_name -> set of model names that declare it.
+    entity_to_models: dict[str, set[str]] = defaultdict(set)
+
+    for model in models:
+        for e in (model.entities or []):
+            name = e.get("name", "")
+            if not name:
+                continue
+            entity_to_models[name].add(model.name)
+
+    # With only one model in the project there can be no join partners at all —
+    # every entity is "orphaned" by definition.  Skip the check; it is
+    # vacuously true and produces false positives on single-model projects.
+    if len(models) < 2:
+        return []
+
+    issues: list[Issue] = []
+    source_note = (
+        "mf_equivalent" if _MF_COMMON_ENTITIES_AVAILABLE else "own_scan"
+    )
+
+    # Second pass — emit one Issue per (entity_name, model) pair that is orphaned.
+    for model in models:
+        for e in (model.entities or []):
+            name = e.get("name", "")
+            if not name:
+                continue
+            if len(entity_to_models[name]) == 1:
+                issues.append(
+                    Issue(
+                        severity="warning",
+                        dimension="joinability",
+                        rule="joinability_orphan",
+                        message=(
+                            f"Entity '{name}' on model '{model.name}' "
+                            f"appears on no other model — it cannot "
+                            f"participate in a join. "
+                            f"(source: {source_note})"
+                        ),
+                        location=model.source_file,
+                        provenance="deterministic",
+                    )
+                )
+
+    return issues
+
+
+def _parity_issues(models: list) -> list[Issue]:
+    """
+    Flag entity name/stem mismatches that indicate broken join partners.
+
+    Groups entity names by their normalised stem across all models.  When a
+    stem maps to multiple distinct names, those names are mismatched join
+    candidates — e.g. "customer" (primary) and "customer_id" (foreign)
+    both stem to "customer" but differ in name, breaking MetricFlow joins.
+
+    MetricFlow has no built-in rule for this — entirely our check.
+    """
+    # stem -> set of (entity_name, model_name, source_file, entity_type)
+    stem_map: dict[str, list[dict]] = defaultdict(list)
+
+    for model in models:
+        for e in (model.entities or []):
+            name = e.get("name", "")
+            etype = e.get("type", "")
+            if not name or etype not in _JOIN_TYPES:
+                continue
+            s = _stem(name)
+            stem_map[s].append(
+                {
+                    "name": name,
+                    "type": etype,
+                    "model": model.name,
+                    "source_file": model.source_file,
+                }
+            )
+
+    issues: list[Issue] = []
+
+    for stem, entries in stem_map.items():
+        distinct_names = {e["name"] for e in entries}
+        if len(distinct_names) <= 1:
+            continue  # all consistent — no mismatch
+
+        # Multiple distinct names for the same stem across models: parity mismatch.
+        names_str = ", ".join(sorted(distinct_names))
+        models_str = ", ".join(sorted({e["model"] for e in entries}))
+
+        # Emit one Issue per model that contributes a mismatched name.
+        seen_model_name = set()
+        for entry in entries:
+            if entry["model"] in seen_model_name:
+                continue
+            seen_model_name.add(entry["model"])
+            issues.append(
+                Issue(
+                    severity="warning",
+                    dimension="joinability",
+                    rule="joinability_parity",
+                    message=(
+                        f"Entity stem '{stem}' has mismatched names "
+                        f"across models [{models_str}]: [{names_str}]. "
+                        f"MetricFlow joins require exact name match — "
+                        f"these will not join correctly."
+                    ),
+                    location=entry["source_file"],
+                    provenance="deterministic",
+                )
+            )
+
+    return issues
+
+
+def check_joinability(models: list) -> list[Issue]:
+    """
+    Cross-model joinability check.  Consumes all NormalizedModels for the project.
+
+    Returns:
+      list[Issue] — empty means fully joinable.
+
+    Checks performed:
+      1. Orphan entities (joinability_orphan) — entity on only one model.
+         Leverages MetricFlow's CommonEntitysRule algorithm when the import
+         is available; falls back to own scan if not.
+      2. Name/type parity mismatches (joinability_parity) — same conceptual
+         join partner has different entity names across models.
+         MetricFlow has no built-in rule for this; we build it ourselves.
+    """
+    if not models:
+        return []
+
+    issues: list[Issue] = []
+    issues.extend(_orphan_issues(models))
+    issues.extend(_parity_issues(models))
+    return issues

trust/judgment.py

@@ -0,0 +1,102 @@
+"""
+Judgment combination + guardrail (Task 3.1d).
+
+apply_judgment(report: ModelReport, judgment: dict) -> ModelReport
+
+Takes the deterministic ModelReport (read-only) produced by scorer.py and an LLM
+judgment payload (per eval/judge.md Step 6) and returns a NEW ModelReport that:
+  - adds document_quality per DocumentReport for each key in judgment["documents"]
+  - appends provenance="llm_judge" advisory issues to the matching DocumentReport
+
+GUARDRAIL — the function enforces a strict read-only contract on the deterministic
+output.  Any key in the payload that would touch trust_score, band, gates, context,
+quality, or any provenance="deterministic" issue is silently ignored.  Only
+"documents" is read; everything else (e.g. "override_gates") is ignored.
+
+Two distinct scores stay distinct:
+  - trust_score / band  : deterministic (unchanged)
+  - document_quality    : advisory, per DocumentReport (from judgment)
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from trust.report import DocumentReport, Issue, ModelReport
+
+
+def apply_judgment(report: ModelReport, judgment: dict[str, Any]) -> ModelReport:
+    """
+    Combine a deterministic ModelReport with an LLM judgment payload.
+
+    Parameters
+    ----------
+    report:
+        The deterministic ModelReport from score_model().  Treated as read-only;
+        the caller's object is never mutated.
+    judgment:
+        Dict produced by the LLM following eval/judge.md Step 6.  Only the
+        "documents" key is consumed; all other keys are ignored (guardrail).
+
+        Expected shape::
+
+            {
+              "documents": {
+                "<doc_type>": {
+                  "quality": <int 0-100>,
+                  "issues": [
+                    {
+                      "severity": "warning"|"info"|"critical",
+                      "dimension": "<string>",
+                      "rule":      "<string>",
+                      "message":   "<string>",
+                      "location":  "<string>"
+                    },
+                    ...
+                  ]
+                },
+                ...
+              }
+            }
+
+    Returns
+    -------
+    ModelReport
+        A deep copy of the input report with document_quality and llm_judge issues
+        attached to the relevant DocumentReports.  trust_score, band, gates, context,
+        quality, and all deterministic issues are identical to the input.
+    """
+    # Deep-copy so the caller's report is never mutated (guardrail: immutability)
+    new_report: ModelReport = copy.deepcopy(report)
+
+    # GUARDRAIL: only read "documents"; ignore everything else in judgment
+    doc_judgments: dict[str, Any] = judgment.get("documents", {})
+
+    for doc_type, payload in doc_judgments.items():
+        if doc_type not in new_report.documents:
+            # Unknown doc_type from LLM — silently ignore
+            continue
+
+        doc: DocumentReport = new_report.documents[doc_type]
+
+        # Attach advisory document_quality score (separate from deterministic score)
+        # Clamp to [0, 100]; skip gracefully if quality is absent or not convertible.
+        quality_score = payload.get("quality")
+        if quality_score is not None:
+            try:
+                doc.document_quality = max(0, min(100, int(quality_score)))
+            except (ValueError, TypeError):
+                pass  # non-int/None — leave document_quality unset
+
+        # Append llm_judge advisory issues (tagged provenance="llm_judge")
+        for raw in payload.get("issues", []):
+            doc.issues.append(Issue(
+                severity=raw.get("severity", "info"),
+                dimension=raw.get("dimension", ""),
+                rule=raw.get("rule", ""),
+                message=raw.get("message", ""),
+                location=raw.get("location", ""),
+                provenance="llm_judge",
+            ))
+
+    return new_report