entropy-table 1.0.1__py3-none-any.whl

entropy_table/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.1'
+__version_tuple__ = version_tuple = (1, 0, 1)
+
+__commit_id__ = commit_id = None

entropy_table/cli.py

@@ -0,0 +1,147 @@
+"""entropy-table – Contract-first scientific entropy atlas CLI."""
+from __future__ import annotations
+
+import sys
+
+import typer
+
+app = typer.Typer(
+    name="entropy-table",
+    help="Contract-first scientific entropy atlas CLI",
+    rich_markup_mode="markdown",
+    no_args_is_help=True,
+)
+
+
+# ── Validation ────────────────────────────────────────────────────────────────
+
+@app.command()
+def validate(
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable JSON output"),
+) -> None:
+    """Validate domain/relation schemas and cross-references."""
+    from entropy_table.commands.validate import main
+    argv = ["--json"] if json_out else []
+    raise SystemExit(main(argv))
+
+
+@app.command("validate-all")
+def validate_all() -> None:
+    """Run ALL validation checks (schema + claims + composition + bibliography + math)."""
+    from entropy_table.commands.validate import main as validate_main
+    from entropy_table.commands.validate_claims import main as claims_main
+    from entropy_table.commands.validate_composition import main as comp_main
+    from entropy_table.commands.validate_bibliography import main as bib_main
+    from entropy_table.commands.manage_cases import main as cases_main
+    from entropy_table.commands.validate_math import main as math_main
+
+    rc = 0
+    rc |= validate_main([]) or 0
+    rc |= claims_main([]) or 0
+    rc |= comp_main([]) or 0
+    rc |= bib_main([]) or 0
+    rc |= cases_main(["validate"]) or 0
+    rc |= math_main([]) or 0
+    raise SystemExit(rc)
+
+
+@app.command("validate-math")
+def validate_math() -> None:
+    """Validate mathematical expressions in atlas domains (SymPy-assisted)."""
+    from entropy_table.commands.validate_math import main
+    raise SystemExit(main([]))
+
+
+@app.command("validate-cases")
+def validate_cases() -> None:
+    """Validate claim↔case cross-references (dangling + orphaned)."""
+    from entropy_table.commands.manage_cases import main
+    raise SystemExit(main(["validate"]))
+
+
+# ── Visualisation ─────────────────────────────────────────────────────────────
+
+@app.command()
+def visualize(
+    format: str = typer.Option("mermaid", "--format", help="mermaid | dot"),
+    output: str = typer.Option("docs/atlas_graph.mmd", "--output", help="Output file path"),
+    filter_status: list[str] = typer.Option([], "--filter-status", help="Filter by status"),
+    exclude_group: list[str] = typer.Option([], "--exclude-group", help="Exclude group"),
+) -> None:
+    """Generate Mermaid or Graphviz DOT graph."""
+    from entropy_table.commands.visualize import main
+    argv = ["--format", format, "--output", output]
+    for s in filter_status:
+        argv += ["--filter-status", s]
+    for g in exclude_group:
+        argv += ["--exclude-group", g]
+    raise SystemExit(main(argv))
+
+
+# ── Rendering ─────────────────────────────────────────────────────────────────
+
+@app.command()
+def render() -> None:
+    """Render atlas to atlas.md + atlas.tex."""
+    from entropy_table.commands.render import main
+    raise SystemExit(main())
+
+
+# ── Scaffolding ───────────────────────────────────────────────────────────────
+
+@app.command()
+def scaffold(
+    kind: str = typer.Argument(..., help="domain | case"),
+    id: str = typer.Argument(..., help="kebab-case ID"),
+    category: str = typer.Option("01_physics", "--category", help="Target category"),
+) -> None:
+    """Scaffold a new domain or case."""
+    from entropy_table.commands.scaffold import main
+    argv = [kind, id, "--category", category]
+    raise SystemExit(main(argv))
+
+
+# ── Analysis & Metrics ────────────────────────────────────────────────────────
+
+@app.command()
+def health(
+    ci_check: bool = typer.Option(False, "--ci-check", help="Exit 1 on integrity issues"),
+    out: str = typer.Option("outputs/atlas_health.md", "--out"),
+) -> None:
+    """Atlas health analysis (orphaned domains, unfalsifiable claims, …)."""
+    from entropy_table.commands.analyze_health import main
+    argv = ["--out", out]
+    if ci_check:
+        argv.append("--ci-check")
+    raise SystemExit(main(argv))
+
+
+@app.command()
+def metrics(
+    format: str = typer.Option("markdown", "--format", help="markdown | json"),
+) -> None:
+    """Compute operational atlas metrics."""
+    from entropy_table.commands.metrics import main
+    raise SystemExit(main(["--format", format]))
+
+
+# ── Index & Release ───────────────────────────────────────────────────────────
+
+@app.command("build-index")
+def build_index() -> None:
+    """Build the domain/relation search index."""
+    from entropy_table.commands.build_index import main
+    raise SystemExit(main([]))
+
+
+@app.command()
+def release(
+    version: str = typer.Option("dev", "--version", help="Release version, e.g. v1.2.3"),
+) -> None:
+    """Build a release pack."""
+    from entropy_table.commands.release import main
+    raise SystemExit(main(["--version", version]))
+
+
+if __name__ == "__main__":
+    app()

entropy_table/commands/analyze_health.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from entropy_table.core.common import ROOT, load_yaml
+
+DEFAULT_REPORT_PATH = Path("outputs/atlas_health.md")
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Analyze atlas graph health and coverage gaps")
+    parser.add_argument("--atlas-root", default="atlas", help="Atlas root directory")
+    parser.add_argument("--out", default=str(DEFAULT_REPORT_PATH), help="Markdown report output path")
+    parser.add_argument(
+        "--ci-check",
+        action="store_true",
+        help="Exit with code 1 when stable claims are unfalsifiable or uncited",
+    )
+    return parser.parse_args(argv)
+
+
+def _resolve_path(path_arg: str, *, base: Path) -> Path:
+    path = Path(path_arg)
+    if path.is_absolute():
+        return path
+    return base / path
+
+
+def _yaml_files(root: Path) -> list[Path]:
+    if not root.exists():
+        return []
+    return sorted(root.glob("**/*.yaml"))
+
+
+def _load_items(paths: list[Path]) -> list[dict]:
+    return [load_yaml(path) for path in paths]
+
+
+def analyze_health(atlas_root: Path) -> dict:
+    domain_paths = _yaml_files(atlas_root / "domains")
+    relation_paths = _yaml_files(atlas_root / "relations")
+    claim_paths = _yaml_files(atlas_root / "claims")
+
+    domains = _load_items(domain_paths)
+    relations = _load_items(relation_paths)
+    claims = _load_items(claim_paths)
+
+    domain_ids_to_paths: dict[str, Path] = {}
+    for path, domain in zip(domain_paths, domains):
+        domain_id = domain.get("id")
+        if isinstance(domain_id, str) and domain_id:
+            domain_ids_to_paths[domain_id] = path
+
+    connected_domain_ids: set[str] = set()
+    regime_shift_connected_ids: set[str] = set()
+    for relation in relations:
+        src = relation.get("source_domain_id")
+        tgt = relation.get("target_domain_id")
+        if isinstance(src, str) and src:
+            connected_domain_ids.add(src)
+        if isinstance(tgt, str) and tgt:
+            connected_domain_ids.add(tgt)
+
+        if relation.get("relation_type") == "regime_shift":
+            if isinstance(src, str) and src:
+                regime_shift_connected_ids.add(src)
+            if isinstance(tgt, str) and tgt:
+                regime_shift_connected_ids.add(tgt)
+
+    orphaned_domains: list[dict] = []
+    missing_regime_shifts: list[dict] = []
+
+    for domain in domains:
+        domain_id = domain.get("id")
+        if not isinstance(domain_id, str) or not domain_id:
+            continue
+
+        domain_path = domain_ids_to_paths.get(domain_id)
+        limitations = domain.get("limitations")
+        assumptions = domain.get("assumptions")
+        has_limits_or_assumptions = (
+            isinstance(limitations, list)
+            and len([item for item in limitations if isinstance(item, str) and item.strip()]) > 0
+        ) or (
+            isinstance(assumptions, list)
+            and len([item for item in assumptions if isinstance(item, str) and item.strip()]) > 0
+        )
+
+        if domain_id not in connected_domain_ids:
+            orphaned_domains.append({"id": domain_id, "path": domain_path})
+
+        if has_limits_or_assumptions and domain_id not in regime_shift_connected_ids:
+            missing_regime_shifts.append({"id": domain_id, "path": domain_path})
+
+    unfalsifiable_stable_claims: list[dict] = []
+    uncited_stable_claims: list[dict] = []
+
+    for path, claim in zip(claim_paths, claims):
+        if claim.get("status") != "stable":
+            continue
+
+        evidence = claim.get("evidence")
+        cases: list[str] = []
+        citations: list[str] = []
+        if isinstance(evidence, dict):
+            raw_cases = evidence.get("cases")
+            if isinstance(raw_cases, list):
+                cases = [case for case in raw_cases if isinstance(case, str) and case.strip()]
+
+            raw_citations = evidence.get("citations")
+            if isinstance(raw_citations, list):
+                citations = [citation for citation in raw_citations if isinstance(citation, str) and citation.strip()]
+
+        row = {"id": claim.get("id", "<missing-id>"), "path": path}
+
+        if len(cases) == 0:
+            unfalsifiable_stable_claims.append(row)
+        if len(citations) == 0:
+            uncited_stable_claims.append(row)
+
+    return {
+        "total_domains": len(domain_ids_to_paths),
+        "total_relations": len(relations),
+        "total_claims": len(claims),
+        "orphaned_domains": sorted(orphaned_domains, key=lambda item: item["id"]),
+        "missing_regime_shifts": sorted(missing_regime_shifts, key=lambda item: item["id"]),
+        "unfalsifiable_stable_claims": sorted(unfalsifiable_stable_claims, key=lambda item: str(item["id"])),
+        "uncited_stable_claims": sorted(uncited_stable_claims, key=lambda item: str(item["id"])),
+    }
+
+
+def _render_table(rows: list[dict]) -> list[str]:
+    if not rows:
+        return ["_None._", ""]
+    lines = ["| ID | File |", "| --- | --- |"]
+    for row in rows:
+        path = row.get("path")
+        lines.append(f"| `{row.get('id', '<missing-id>')}` | `{path}` |")
+    lines.append("")
+    return lines
+
+
+def render_markdown(report: dict) -> str:
+    lines = [
+        "# Atlas Graph Health & Coverage Report",
+        "",
+        "## Summary",
+        "",
+        f"- Total Domains: {report['total_domains']}",
+        f"- Total Relations: {report['total_relations']}",
+        f"- Total Claims: {report['total_claims']}",
+        f"- Orphaned Domains: {len(report['orphaned_domains'])}",
+        f"- Missing Regime Shifts: {len(report['missing_regime_shifts'])}",
+        f"- Unfalsifiable Stable Claims: {len(report['unfalsifiable_stable_claims'])}",
+        f"- Uncited Stable Claims: {len(report['uncited_stable_claims'])}",
+        "",
+        "## Orphaned Domains",
+        "",
+        "Domains not referenced as `source_domain_id` or `target_domain_id` in any relation.",
+        "",
+    ]
+    lines.extend(_render_table(report["orphaned_domains"]))
+    lines.extend(
+        [
+            "## Missing Regime Shifts",
+            "",
+            "Domains with listed `limitations` or `assumptions` but no connected `regime_shift` relation.",
+            "",
+        ]
+    )
+    lines.extend(_render_table(report["missing_regime_shifts"]))
+    lines.extend(
+        [
+            "## Unfalsifiable Stable Claims",
+            "",
+            "Stable claims with no linked `evidence.cases` entries.",
+            "",
+        ]
+    )
+    lines.extend(_render_table(report["unfalsifiable_stable_claims"]))
+    lines.extend(
+        [
+            "## Uncited Stable Claims",
+            "",
+            "Stable claims with missing or empty `evidence.citations`.",
+            "",
+        ]
+    )
+    lines.extend(_render_table(report["uncited_stable_claims"]))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    atlas_root = _resolve_path(args.atlas_root, base=ROOT)
+    output_path = _resolve_path(args.out, base=ROOT)
+
+    report = analyze_health(atlas_root)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(render_markdown(report), encoding="utf-8")
+    print(f"Wrote atlas health report: {output_path}")
+
+    ci_failures = len(report["unfalsifiable_stable_claims"]) + len(report["uncited_stable_claims"])
+    if args.ci_check and ci_failures > 0:
+        print("CI check failed: stable claim integrity issues detected.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

entropy_table/commands/build_index.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build deterministic atlas metadata index")
+    parser.add_argument("--out", default="cache/index.json")
+    parser.add_argument("--domains-root", default="atlas/domains")
+    parser.add_argument("--relations-root", default="atlas/relations")
+    return parser.parse_args(argv)
+
+
+def load_yaml(path: Path) -> dict:
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a YAML object")
+    return data
+
+
+def iter_yaml_files(root: Path) -> list[Path]:
+    return sorted(root.glob("**/*.yaml"))
+
+
+def build_index(domains_root: Path, relations_root: Path) -> dict:
+    domains: dict[str, dict] = {}
+    relations: dict[str, dict] = {}
+    citation_to_domains: dict[str, set[str]] = defaultdict(set)
+    citation_to_relations: dict[str, set[str]] = defaultdict(set)
+    outgoing: dict[str, list[str]] = defaultdict(list)
+    incoming: dict[str, list[str]] = defaultdict(list)
+
+    for path in iter_yaml_files(domains_root):
+        data = load_yaml(path)
+        domain_id = data.get("id")
+        if not isinstance(domain_id, str) or not domain_id:
+            raise ValueError(f"{path} missing required 'id'")
+
+        boundary = data.get("boundary") or {}
+        system_type = data.get("system_type") or {}
+        context = data.get("context") or {}
+        domain_tags = sorted(set((system_type.get("tags") or []) + (context.get("tags") or [])))
+        citation_ids = sorted(c.get("id") for c in (data.get("citations") or []) if isinstance(c, dict) and c.get("id"))
+
+        must_fail_rows = []
+        for test in data.get("must_fail_tests") or []:
+            if not isinstance(test, dict):
+                continue
+            test_id = test.get("id", "<missing-test-id>")
+            severity = test.get("severity", "unknown")
+            for citation_id in test.get("citations") or []:
+                citation_to_domains[citation_id].add(domain_id)
+                must_fail_rows.append(
+                    {
+                        "citation_id": citation_id,
+                        "test_id": test_id,
+                        "severity": severity,
+                    }
+                )
+
+        domains[domain_id] = {
+            "path": str(path.as_posix()),
+            "title": data.get("title", ""),
+            "system_primary": system_type.get("primary", ""),
+            "tags": domain_tags,
+            "closure_type": boundary.get("closure_type", "unknown"),
+            "exchange_channels": sorted(boundary.get("exchange_channels") or []),
+            "citation_ids": citation_ids,
+            "must_fail_rows": sorted(
+                must_fail_rows,
+                key=lambda row: (row["citation_id"], row["test_id"], row["severity"]),
+            ),
+        }
+
+    for path in iter_yaml_files(relations_root):
+        data = load_yaml(path)
+        relation_id = data.get("id")
+        if not isinstance(relation_id, str) or not relation_id:
+            raise ValueError(f"{path} missing required 'id'")
+
+        source = data.get("source_domain_id", "")
+        target = data.get("target_domain_id", "")
+        citation_ids = sorted(c.get("id") for c in (data.get("citations") or []) if isinstance(c, dict) and c.get("id"))
+
+        must_fail_rows = []
+        for test in data.get("must_fail_tests") or []:
+            if not isinstance(test, dict):
+                continue
+            test_id = test.get("id", "<missing-test-id>")
+            severity = test.get("severity", "unknown")
+            for citation_id in test.get("citations") or []:
+                citation_to_relations[citation_id].add(relation_id)
+                must_fail_rows.append(
+                    {
+                        "citation_id": citation_id,
+                        "test_id": test_id,
+                        "severity": severity,
+                    }
+                )
+
+        relations[relation_id] = {
+            "path": str(path.as_posix()),
+            "relation_type": data.get("relation_type", "unknown"),
+            "source": source,
+            "target": target,
+            "citation_ids": citation_ids,
+            "must_fail_rows": sorted(
+                must_fail_rows,
+                key=lambda row: (row["citation_id"], row["test_id"], row["severity"]),
+            ),
+        }
+        outgoing[source].append(relation_id)
+        incoming[target].append(relation_id)
+
+    return {
+        "domains": {key: domains[key] for key in sorted(domains)},
+        "relations": {key: relations[key] for key in sorted(relations)},
+        "reverse": {
+            "citation_to_domains": {
+                citation_id: sorted(domain_ids)
+                for citation_id, domain_ids in sorted(citation_to_domains.items())
+            },
+            "citation_to_relations": {
+                citation_id: sorted(relation_ids)
+                for citation_id, relation_ids in sorted(citation_to_relations.items())
+            },
+        },
+        "graph": {
+            "outgoing": {
+                domain_id: sorted(relation_ids)
+                for domain_id, relation_ids in sorted(outgoing.items())
+            },
+            "incoming": {
+                domain_id: sorted(relation_ids)
+                for domain_id, relation_ids in sorted(incoming.items())
+            },
+        },
+        "meta": {
+            "generated_utc": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+            "domain_count": len(domains),
+            "relation_count": len(relations),
+        },
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        index = build_index(Path(args.domains_root), Path(args.relations_root))
+    except (yaml.YAMLError, OSError, ValueError) as exc:
+        print(f"Error building index: {exc}", file=sys.stderr)
+        return 1
+
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(index, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(f"Wrote index: {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

entropy_table/commands/extract_domain_from_template.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import yaml
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Extract a domain YAML draft from a template")
+    parser.add_argument("--template", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--set", dest="sets", action="append", default=[])
+    parser.add_argument("--force", action="store_true")
+    return parser.parse_args(argv)
+
+
+def parse_set(value: str) -> tuple[list[str], str]:
+    if "=" not in value:
+        raise ValueError(f"Invalid --set value '{value}', expected path=value")
+    dotted, raw = value.split("=", 1)
+    path_parts = [part for part in dotted.split(".") if part]
+    if not path_parts:
+        raise ValueError(f"Invalid --set path in '{value}'")
+    return path_parts, raw
+
+
+def coerce_value(raw: str):
+    lowered = raw.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered == "null":
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    return raw
+
+
+def apply_path(target, path_parts: list[str], value) -> None:
+    cursor = target
+    for index, part in enumerate(path_parts[:-1]):
+        next_part = path_parts[index + 1]
+        is_next_index = next_part.isdigit()
+
+        if isinstance(cursor, list):
+            if not part.isdigit():
+                raise ValueError(f"Expected list index at '{part}' in path {'.'.join(path_parts)}")
+            item_index = int(part)
+            if item_index < 0:
+                raise ValueError("List index cannot be negative")
+            while len(cursor) <= item_index:
+                cursor.append({} if not is_next_index else [])
+            if not isinstance(cursor[item_index], (dict, list)):
+                cursor[item_index] = {} if not is_next_index else []
+            cursor = cursor[item_index]
+            continue
+
+        if not isinstance(cursor, dict):
+            raise ValueError(f"Cannot descend into non-container for path {'.'.join(path_parts)}")
+
+        if part not in cursor or cursor[part] is None:
+            cursor[part] = [] if is_next_index else {}
+        elif not isinstance(cursor[part], (dict, list)):
+            cursor[part] = [] if is_next_index else {}
+
+        cursor = cursor[part]
+
+    final = path_parts[-1]
+    if isinstance(cursor, list):
+        if not final.isdigit():
+            raise ValueError(f"Expected list index at final segment '{final}'")
+        final_index = int(final)
+        if final_index < 0:
+            raise ValueError("List index cannot be negative")
+        while len(cursor) <= final_index:
+            cursor.append(None)
+        cursor[final_index] = value
+        return
+
+    if not isinstance(cursor, dict):
+        raise ValueError(f"Cannot assign into non-dict at path {'.'.join(path_parts)}")
+    cursor[final] = value
+
+
+def load_template(path: Path):
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Template must be a YAML object")
+    return data
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    template_path = Path(args.template)
+    out_path = Path(args.out)
+
+    if out_path.exists() and not args.force:
+        print(f"Refusing to overwrite existing file: {out_path}")
+        return 1
+
+    try:
+        payload = load_template(template_path)
+        for assignment in args.sets:
+            path_parts, raw_value = parse_set(assignment)
+            apply_path(payload, path_parts, coerce_value(raw_value))
+    except (OSError, yaml.YAMLError, ValueError) as exc:
+        print(f"Error: {exc}")
+        return 1
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8")
+    print(f"Wrote draft: {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())