gdk9-cli 0.3.0__py3-none-any.whl

examples/01_analyze.py

@@ -0,0 +1,28 @@
+"""Example 01 — analyze: break text into energy units.
+
+gdk9 analyze decomposes text from document → paragraph → sentence → word,
+reporting the A1Z26 digital-root energy at each level.
+"""
+import subprocess, sys, os
+
+_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+        cwd=_ROOT,
+    )
+    print(result.stdout or result.stderr)
+
+# Basic analysis
+print("=== analyze a phrase ===")
+run("--color", "analyze", "Signal 123 ehdxkcit 3245768")
+
+# Table format
+print("=== analyze — table format ===")
+run("--color", "analyze", "FWEM dark swan protocol", "--format", "table")
+
+# Compare two phrases
+print("=== compare two strings ===")
+run("--color", "compare", "dark swan", "dark swan protocol")

examples/02_profile.py

@@ -0,0 +1,24 @@
+"""Example 02 — profile: energy histogram and DR distribution.
+
+profile shows how energy is distributed across digital roots 1-9,
+rendered as a coloured block-bar chart.
+"""
+import subprocess, sys
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+    )
+    print(result.stdout or result.stderr)
+
+texts = [
+    "The quick brown fox jumps over the lazy dog",
+    "FWEM",
+    "dark swan protocol identity",
+]
+
+for text in texts:
+    print(f'=== profile: {text!r} ===')
+    run("--color", "profile", text)
+    print()

examples/03_assign.py

@@ -0,0 +1,19 @@
+"""Example 03 — assign: per-character energy breakdown.
+
+assign lists every character with its individual energy value and DR,
+useful for auditing which letters drive the total energy of a word.
+"""
+import subprocess, sys
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+    )
+    print(result.stdout or result.stderr)
+
+print("=== assign: FWEM ===")
+run("--color", "assign", "FWEM")
+
+print("=== assign: dark swan ===")
+run("--color", "assign", "dark swan")

examples/04_dcg.py

@@ -0,0 +1,41 @@
+"""Example 04 — DCG: Directed Cognition Graph.
+
+The DCG models letters as nodes in a directed graph with three edge types:
+  DC↔AC   uppercase ↔ lowercase (cost 0.5 / 2.0)
+  within  all-pairs within symmetry class (cost 1.0)
+  cross   energy cycle asym → biph → idemp → invol → asym (cost 2.0)
+
+Demonstrates: classify, path, homotopy, shortest, vector, info.
+"""
+import subprocess, sys
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+    )
+    print(result.stdout or result.stderr)
+
+# Symmetry class of individual letters
+print("=== dcg classify ===")
+run("--color", "dcg", "classify", "FWEM")
+
+# Full word path — symmetry class + energy per letter
+print("=== dcg path: FWEM ===")
+run("--color", "dcg", "path", "FWEM")
+
+# Shortest path between two nodes
+print("=== dcg shortest: F → M ===")
+run("--color", "dcg", "shortest", "F", "M")
+
+# Homotopy equivalence: same letters reordered
+print("=== dcg homotopy: FWEM vs MWEF ===")
+run("--color", "dcg", "homotopy", "FWEM", "MWEF")
+
+# 4D vector encoding
+print("=== dcg vector: FWEM ===")
+run("--color", "dcg", "vector", "FWEM")
+
+# Graph info
+print("=== dcg info ===")
+run("--color", "dcg", "info")

examples/05_tokenize.py

@@ -0,0 +1,22 @@
+"""Example 05 — tokenize: split text by symbolic energy delimiters.
+
+Delimiters are characters whose symbol-energy equals the requested level.
+With -F table the output includes per-token DR, energy totals, and a
+metrics footer (DR histogram, top tokens, class breakdown).
+"""
+import subprocess, sys
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+    )
+    print(result.stdout or result.stderr)
+
+text = "alpha|beta:gamma/delta=epsilon"
+
+print("=== tokenize at energy-1 delimiters (table) ===")
+run("--color", "tokenize", text, "--energy", "1", "-F", "table")
+
+print("=== tokenize JSON payload ===")
+run("tokenize", "FWEM dark-swan protocol", "-F", "json")

examples/06_synthesize.py

@@ -0,0 +1,20 @@
+"""Example 06 — synthesize: build a sigil from an energy profile.
+
+synthesize takes a word and renders a bordered sigil with per-letter
+DR coloring, the total SymPhi energy, and the digital root.
+"""
+import subprocess, sys
+
+def run(*args):
+    result = subprocess.run(
+        [sys.executable, "-m", "gdk9.cli", *args],
+        capture_output=True, text=True,
+    )
+    print(result.stdout or result.stderr)
+
+words = ["FWEM", "dark", "swan", "protocol"]
+
+for word in words:
+    print(f"=== synthesize: {word} ===")
+    run("--color", "synthesize", word)
+    print()

examples/07_api.py

@@ -0,0 +1,57 @@
+"""Example 07 — Python API: use gdk9 modules directly.
+
+All CLI commands are thin wrappers around importable Python functions.
+This example exercises the core API without subprocess.
+"""
+import sys, os
+# Allow running from the examples/ directory
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from gdk9.energy import string_energy, char_energy
+from gdk9.dcg import (
+    get_dcg, symmetry_class, sym_energy,
+    word_sym_energy, homotopy_equivalent,
+)
+from gdk9.fmt import fmt_class, fmt_dr, fmt_float_e, Box, section, kv
+from gdk9.principles import Principle
+
+principle = Principle.default()
+
+# ── Energy model ──────────────────────────────────────────────────────────────
+print(section("energy model", enabled=False))
+
+for word in ["FWEM", "dark", "swan"]:
+    total, dr = string_energy(word, principle)
+    print(f'  {word:<10}  total={total:>6}  dr={dr}')
+
+# ── DCG ───────────────────────────────────────────────────────────────────────
+print()
+print(section("dcg", enabled=False))
+
+g = get_dcg()
+print(f'  nodes={g.node_count()}  edges={g.edge_count()}')
+
+for ch in "FWEM":
+    cls = symmetry_class(ch)
+    e   = sym_energy(ch)
+    print(f'  {ch}  {cls:<12}  e={e:.4f}')
+
+print()
+path = g.shortest_path("F", "M")
+print(f'  shortest F→M:  {" → ".join(path)}')
+
+equiv, detail = homotopy_equivalent("FWEM", "MWEF", tol=1.0)
+print(f'  homotopy FWEM≅MWEF:  {equiv}  '
+      f'(Δe={detail["energy_diff"]:.4f}  dist={detail["vector_distance"]:.4f})')
+
+# ── fmt helpers ───────────────────────────────────────────────────────────────
+print()
+print(section("fmt — Box table", enabled=False))
+
+box = Box(["char", "class", "energy", "dr"], col_align=["c", "l", "r", "c"], enabled=False)
+for ch in "FWEM":
+    e   = sym_energy(ch)
+    cls = symmetry_class(ch)
+    _, dr = string_energy(ch, principle)
+    box.row([ch, cls, f"{e:.4f}", str(dr)])
+print(box.render())

examples/08_kernel.py

@@ -0,0 +1,35 @@
+"""Example 08 — Pure kernel smoke: evaluate, fuse, and bounded search.
+
+The kernel package has no CLI/state/plugin I/O. This script uses the library
+surface (and optionally the thin ``gdk9 kernel`` CLI adapter) for research.
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from gdk9.kernel import Expression, ImplicationEngine, KernelPrinciple
+from gdk9.kernel.engine import fusion_rule
+from gdk9.kernel.symbol import Symbol
+from gdk9.kernel_cli import expression_payload, judgment_payload, proof_steps_payload, principle_to_kernel
+from gdk9.principles import Principle
+
+principle = Principle.default()
+kp = principle_to_kernel(principle)
+engine = ImplicationEngine(kp, (fusion_rule(),))
+
+# Evaluate
+expr = Expression.from_text("ABC", kp)
+total, root = engine.evaluate(expr)
+print(json.dumps({"eval": {"expression": expression_payload(expr), "total": total, "digital_root": root}}, indent=2))
+
+# Apply fuse
+source = Expression.from_names(["A", "B"], kp)
+judgment = engine.apply("fuse", source)
+print(json.dumps({"apply": judgment_payload(judgment)}, indent=2))
+
+# Bounded search A,B -> AB
+target = Expression((Symbol("AB", source.total_energy()),))
+path = engine.infer(source, target, max_depth=2)
+print(json.dumps({"search": {"found": path is not None, "steps": proof_steps_payload(path or ())}}, indent=2))

examples/09_kernel_search_walkthrough.py

@@ -0,0 +1,102 @@
+"""Example 09 — Kernel search walkthrough (handbook voice).
+
+Three short scenes. Each conserves energy. Each can fail if the depth bound
+is too tight or the target energy does not match — that failure is the point.
+
+Run::
+
+    python examples/09_kernel_search_walkthrough.py
+
+Or mirror with the CLI::
+
+    gdk9 kernel eval A B C
+    gdk9 kernel apply fuse A B
+    gdk9 kernel search A B --target AB --max-depth 2 --rules fuse
+    gdk9 kernel apply split AB --parts A,B --energies 1,2
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from gdk9.kernel import Expression, ImplicationEngine
+from gdk9.kernel.engine import fusion_rule, split_rule
+from gdk9.kernel.symbol import Symbol
+from gdk9.kernel_cli import (
+  judgment_payload,
+  principle_to_kernel,
+  proof_steps_payload,
+)
+from gdk9.principles import Principle
+
+
+def scene(title: str, payload: dict) -> None:
+  print(f"\n## {title}")
+  print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def main() -> int:
+  kp = principle_to_kernel(Principle.default())
+  fuse = fusion_rule()
+  a_e = Expression.from_names(["A"], kp).total_energy()
+  b_e = Expression.from_names(["B"], kp).total_energy()
+  split = split_rule(("A", "B"), (a_e, b_e))
+
+  # Scene 1 — weigh the letters (eval)
+  eng = ImplicationEngine(kp, (fuse,))
+  abc = Expression.from_names(["A", "B", "C"], kp)
+  total, root = eng.evaluate(abc)
+  scene(
+    "1. Weigh — eval ABC",
+    {
+      "names": list(abc.names()),
+      "total_energy": total,
+      "digital_root": root,
+      "note": "A=1, B=2, C=3 under the default principle; sum=6, DR=6.",
+    },
+  )
+
+  # Scene 2 — one conserved fuse, then find it by bounded search
+  src = Expression.from_names(["A", "B"], kp)
+  judgment = eng.apply("fuse", src)
+  target = Expression((Symbol("AB", src.total_energy()),))
+  path = eng.infer(src, target, max_depth=2)
+  scene(
+    "2. Fuse — then search A,B → AB (max_depth=2)",
+    {
+      "apply": judgment_payload(judgment),
+      "search_found": path is not None,
+      "steps": proof_steps_payload(path or ()),
+      "note": "Search is not magic: it is bounded BFS over conserving rules.",
+    },
+  )
+
+  # Scene 3 — reverse the arrow (split) with matching energies
+  eng2 = ImplicationEngine(kp, (fuse, split))
+  ab = judgment.after
+  back = eng2.apply("split", ab)
+  scene(
+    "3. Split — AB → A,B with matching energies (conserved)",
+    {
+      "judgment": judgment_payload(back),
+      "note": "Split needs explicit part energies that sum to the whole.",
+    },
+  )
+
+  # Scene 4 — deliberate miss (prove it can fail)
+  miss = eng.infer(src, Expression((Symbol("ZZ", 99.0),)), max_depth=2)
+  scene(
+    "4. Miss — impossible target (energy 99) within depth 2",
+    {
+      "found": miss is not None,
+      "note": "A honest research tool must be able to say no.",
+    },
+  )
+  return 0
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())

examples/10_conserve_vs_naive.py

@@ -0,0 +1,100 @@
+"""Example 10 — Conserved search vs naive name-join/split (research move 4).
+
+Prints a short JSON summary. Full fail bar lives in pytest::
+
+    python -m pytest -q tests/experiment/test_conserve_vs_naive.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from gdk9.kernel import Expression, ImplicationEngine, KernelPrinciple
+from gdk9.kernel.engine import fusion_rule, split_rule
+from gdk9.kernel.symbol import Symbol
+from tests.experiment.test_conserve_vs_naive import (
+  MISMATCHED_AB_ENERGY,
+  MISMATCHED_A_ENERGY,
+  MISMATCHED_B_ENERGY,
+  conserved_kernel_proof,
+  naive_join_search,
+  naive_split_search,
+)
+
+
+def main() -> int:
+  principle = KernelPrinciple.default()
+  ea = principle.energy_of("A")
+  eb = principle.energy_of("B")
+  source = Expression.from_names(["A", "B"], principle)
+  conserved_target = Expression((Symbol("AB", source.total_energy()),))
+  mismatched = Expression((Symbol("AB", MISMATCHED_AB_ENERGY),))
+  fuse_engine = ImplicationEngine(principle, (fusion_rule(),))
+
+  ab_source = Expression((Symbol("AB", ea + eb),))
+  split_target = Expression.from_names(["A", "B"], principle)
+  split_mismatched = Expression(
+    (Symbol("A", MISMATCHED_A_ENERGY), Symbol("B", MISMATCHED_B_ENERGY))
+  )
+  split_engine = ImplicationEngine(principle, (split_rule(("A", "B"), (ea, eb)),))
+
+  conserved_path = conserved_kernel_proof(fuse_engine, source, conserved_target, max_depth=2)
+  mismatch_kernel = conserved_kernel_proof(fuse_engine, source, mismatched, max_depth=2)
+  naive_ok = naive_join_search(source.names(), ("AB",), max_depth=2)
+
+  split_path = conserved_kernel_proof(split_engine, ab_source, split_target, max_depth=2)
+  split_mismatch_kernel = conserved_kernel_proof(
+    split_engine, ab_source, split_mismatched, max_depth=2
+  )
+  naive_split_ok = naive_split_search(ab_source.names(), ("A", "B"), max_depth=2)
+
+  summary = {
+    "experiment": "conserve_vs_naive",
+    "approach": "A",
+    "move": 4,
+    "claim": "beats naive join/split on proof validity under conservation",
+    "source_names": list(source.names()),
+    "source_energy": source.total_energy(),
+    "conserved_ab": {
+      "kernel_found": conserved_path is not None,
+      "steps": len(conserved_path or ()),
+      "all_conserved": bool(
+        conserved_path
+        and all(s.judgment.conserved for s in conserved_path)
+      ),
+    },
+    "mismatched_ab_energy": MISMATCHED_AB_ENERGY,
+    "mismatched_ab": {
+      "naive_found": naive_ok is not None,
+      "kernel_found": mismatch_kernel is not None,
+    },
+    "conserved_split": {
+      "kernel_found": split_path is not None,
+      "steps": len(split_path or ()),
+      "all_conserved": bool(
+        split_path and all(s.judgment.conserved for s in split_path)
+      ),
+    },
+    "mismatched_split": {
+      "naive_found": naive_split_ok is not None,
+      "kernel_found": split_mismatch_kernel is not None,
+      "part_energies": [MISMATCHED_A_ENERGY, MISMATCHED_B_ENERGY],
+    },
+    "validity_beat_fuse": naive_ok is not None and mismatch_kernel is None,
+    "validity_beat_split": naive_split_ok is not None and split_mismatch_kernel is None,
+  }
+  print(json.dumps(summary, indent=2))
+  ok = (
+    summary["validity_beat_fuse"]
+    and summary["validity_beat_split"]
+    and summary["conserved_ab"]["kernel_found"]
+    and summary["conserved_split"]["kernel_found"]
+  )
+  return 0 if ok else 1
+
+
+if __name__ == "__main__":
+  raise SystemExit(main())

gdk9/__init__.py

@@ -0,0 +1,5 @@
+__all__ = [
+  "__version__",
+]
+
+__version__ = "0.3.0"

gdk9/ansi.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+_CODES: dict[str, str] = {
+  # styles
+  "bold":           "\033[1m",
+  "dim":            "\033[2m",
+  "italic":         "\033[3m",
+  "underline":      "\033[4m",
+  "reverse":        "\033[7m",
+  # standard colours
+  "red":            "\033[31m",
+  "green":          "\033[32m",
+  "yellow":         "\033[33m",
+  "blue":           "\033[34m",
+  "magenta":        "\033[35m",
+  "cyan":           "\033[36m",
+  "white":          "\033[37m",
+  # bright variants
+  "bright_black":   "\033[90m",
+  "bright_red":     "\033[91m",
+  "bright_green":   "\033[92m",
+  "bright_yellow":  "\033[93m",
+  "bright_blue":    "\033[94m",
+  "bright_magenta": "\033[95m",
+  "bright_cyan":    "\033[96m",
+  "bright_white":   "\033[97m",
+}
+
+_RESET = "\033[0m"
+
+
+def supports_color() -> bool:
+  if os.getenv("NO_COLOR") == "1":
+    return False
+  term = os.getenv("TERM", "")
+  if term in ("dumb", ""):
+    return False
+  return sys.stdout.isatty()
+
+
+def colorize(text: str, color: str | None, enabled: bool) -> str:
+  if not enabled or not color:
+    return text
+  code = _CODES.get(color, "")
+  return f"{code}{text}{_RESET}" if code else text
+
+
+def strip_ansi(s: str) -> str:
+  """Remove all ANSI escape codes from *s*."""
+  return _ANSI_RE.sub("", s)
+