gdk9-cli 0.3.0__py3-none-any.whl

gdk9/energy.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Tuple
+
+from .principles import Principle
+
+
+def digital_root(n: int, zero_to_nine: bool = True) -> int:
+  n = abs(int(n))
+  if n == 0:
+    return 9 if zero_to_nine else 0
+  return 9 if (n % 9 == 0) else (n % 9)
+
+
+def letter_value(ch: str) -> int:
+  c = ch.upper()
+  if "A" <= c <= "Z":
+    return ord(c) - ord("A") + 1
+  return ord(c)
+
+
+def char_energy(ch: str, principle: Principle) -> int:
+  if ch.isspace():
+    return 0
+  if ch.isalpha():
+    base = letter_value(ch) if principle.letter_mode == "a1z26" else ord(ch)
+    e = digital_root(base, principle.normalize_zero_to_nine)
+    return digital_root(e * principle.weights.get("letter", 1), principle.normalize_zero_to_nine)
+  if ch.isdigit():
+    base = int(ch)
+    e = digital_root(base, principle.normalize_zero_to_nine)
+    return digital_root(e * principle.weights.get("digit", 1), principle.normalize_zero_to_nine)
+  if ch in principle.symbol_energy:
+    e = digital_root(principle.symbol_energy[ch], principle.normalize_zero_to_nine)
+    return digital_root(e * principle.weights.get("symbol", 1), principle.normalize_zero_to_nine)
+  # Fallback for other unicode symbols
+  e = digital_root(ord(ch), principle.normalize_zero_to_nine)
+  return digital_root(e * principle.weights.get("symbol", 1), principle.normalize_zero_to_nine)
+
+
+def string_energy(text: str, principle: Principle) -> Tuple[int, int]:
+  total = sum(char_energy(ch, principle) for ch in text)
+  return total, digital_root(total, principle.normalize_zero_to_nine)
+
+
+def tokenize_sentences(text: str) -> List[str]:
+  # Simple sentence split on .!? while retaining textual coherence
+  parts = re.split(r"(?<=[.!?])\s+", text.strip())
+  return [p for p in parts if p]
+
+
+def tokenize_words(text: str) -> List[str]:
+  return re.findall(r"\b\w+\b", text, flags=re.UNICODE)
+
+
+@dataclass
+class UnitEnergy:
+  unit: str
+  value: str
+  energy: int
+  total: int
+
+
+def analyze_text(text: str, principle: Principle) -> Dict[str, Iterable[UnitEnergy]]:
+  chars: List[UnitEnergy] = []
+  for ch in text:
+    e = char_energy(ch, principle)
+    total = e
+    chars.append(UnitEnergy("char", ch, e, total))
+
+  words: List[UnitEnergy] = []
+  for w in tokenize_words(text):
+    total, dr = string_energy(w, principle)
+    words.append(UnitEnergy("word", w, dr, total))
+
+  sentences: List[UnitEnergy] = []
+  for s in tokenize_sentences(text):
+    total, dr = string_energy(s, principle)
+    sentences.append(UnitEnergy("sentence", s, dr, total))
+
+  paragraphs: List[UnitEnergy] = []
+  for p in [pp for pp in text.splitlines() if pp.strip()]:
+    total, dr = string_energy(p, principle)
+    paragraphs.append(UnitEnergy("paragraph", p, dr, total))
+
+  doc_total, doc_dr = string_energy(text, principle)
+  doc = [UnitEnergy("document", text, doc_dr, doc_total)]
+
+  return {
+    "chars": chars,
+    "words": words,
+    "sentences": sentences,
+    "paragraphs": paragraphs,
+    "document": doc,
+  }
+
+
+def vector_energy(text: str, principle: Principle) -> Dict[str, Dict[str, int]]:
+  letters = 0
+  digits = 0
+  symbols = 0
+  for ch in text:
+    if ch.isspace():
+      continue
+    if ch.isalpha():
+      letters += char_energy(ch, principle)
+    elif ch.isdigit():
+      digits += char_energy(ch, principle)
+    else:
+      symbols += char_energy(ch, principle)
+  return {
+    "sum": {"letters": letters, "digits": digits, "symbols": symbols},
+    "dr": {
+      "letters": digital_root(letters, principle.normalize_zero_to_nine),
+      "digits": digital_root(digits, principle.normalize_zero_to_nine),
+      "symbols": digital_root(symbols, principle.normalize_zero_to_nine),
+    },
+  }
+
+
+def harmonic_triads(text: str, principle: Principle) -> Dict[str, int]:
+  # Group by residue classes: 1/4/7=root, 2/5/8=wave, 3/6/9=peak
+  triads = {"root": 0, "wave": 0, "peak": 0}
+  for ch in text:
+    e = char_energy(ch, principle)
+    if e == 0:
+      continue
+    r = e % 9
+    if r in (1, 4, 7):
+      triads["root"] += 1
+    elif r in (2, 5, 8):
+      triads["wave"] += 1
+    else:
+      triads["peak"] += 1
+  return triads
+
+
+def energy_profile(text: str, principle: Principle) -> Dict[str, int]:
+  profile: Dict[str, int] = {str(i): 0 for i in range(1, 10)}
+  for ch in text:
+    e = char_energy(ch, principle)
+    key = str(9 if e == 0 else e)
+    profile[key] += 1
+  return profile
+
+
+def required_delta(current: int, target: int, zero_to_nine: bool = True) -> int:
+  if current == target:
+    return 0
+  # Determine minimal addition to move digital root to target
+  # Try deltas 1..100 and pick the first that matches
+  for d in range(1, 101):
+    if digital_root(current + d, zero_to_nine) == target:
+      return d
+  return 0
+
+
+def attune_text(
+  text: str,
+  target: int,
+  principle: Principle,
+  method: str = "append",
+  symbol: str = ".",
+) -> Tuple[str, int, int, int]:
+  total, dr = string_energy(text, principle)
+  if not (1 <= target <= 9):
+    raise ValueError("Target energy must be 1..9")
+  if dr == target:
+    return text, total, dr, 0
+  if method != "append":
+    raise ValueError("Only 'append' method supported in default build")
+  sym_e = char_energy(symbol, principle)
+  delta = required_delta(total, target, principle.normalize_zero_to_nine)
+  if sym_e == 0:
+    raise ValueError("Chosen symbol has zero energy; pick another.")
+  count = max(1, (delta + sym_e - 1) // sym_e)
+  new_text = text + (symbol * count)
+  new_total, new_dr = string_energy(new_text, principle)
+  # Adjust if overshoot; ensure we hit target
+  if new_dr != target:
+    # Try up to 20 adjustments by adding one symbol until matched
+    tries = 0
+    while new_dr != target and tries < 20:
+      new_text += symbol
+      new_total, new_dr = string_energy(new_text, principle)
+      tries += 1
+  return new_text, new_total, new_dr, count
+
+
+def synthesize_sigil(text: str, principle: Principle, style: str = "grid") -> str:
+  total, dr = string_energy(text, principle)
+  prof = energy_profile(text, principle)
+  if style == "grid":
+    # Build a 3x3 grid where each cell repeats count of that energy
+    order = ["1", "2", "3", "4", "5", "6", "7", "8", "9"]
+    cells = ["" for _ in range(9)]
+    for i, k in enumerate(order):
+      cells[i] = str(prof[k])
+    rows = [" ".join(cells[i:i+3]) for i in range(0, 9, 3)]
+    title = f"DR={dr} TOTAL={total}"
+    return title + "\n" + "\n".join(rows)
+  if style == "bar":
+    bars = []
+    for i in range(1, 10):
+      k = str(i)
+      count = prof[k]
+      bars.append(f"{i}: " + ("#" * min(count, 40)))
+    return "\n".join(bars)
+  return f"DR={dr} TOTAL={total}"

gdk9/errors.py

@@ -0,0 +1,15 @@
+class Gdk9Error(Exception):
+  """Base exception for Gdk9 CLI."""
+
+
+class ConfigError(Gdk9Error):
+  """Configuration file or principle load error."""
+
+
+class InputError(Gdk9Error):
+  """Invalid input provided by user."""
+
+
+class OptimizationError(Gdk9Error):
+  """Unable to find or apply an attunement/optimization plan."""
+

gdk9/fmt.py

@@ -0,0 +1,212 @@
+"""gdk9/fmt.py — Pretty terminal output helpers.
+
+Box          Bordered Unicode table with ANSI-aware column widths.
+energy_bar   Coloured block-bar for profile histograms.
+fmt_class    Symmetry class with colour coding.
+fmt_dr       Digital-root integer 1–9 with colour.
+fmt_float_e  Float energy value with colour.
+fmt_valid    ✓ / ✗ validity mark.
+fmt_form     DC / AC form label.
+kv           dim-key=bright-value inline pair.
+section      Dim rule + bold title header line.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+from .ansi import colorize, strip_ansi
+
+
+# ── ANSI-aware string helpers ─────────────────────────────────────────────────
+
+def vlen(s: str) -> int:
+    """Visible length of *s* (ANSI codes have zero width)."""
+    return len(strip_ansi(s))
+
+
+def vpad(s: str, width: int, align: str = 'l') -> str:
+    """Pad *s* to *width* visible characters, preserving embedded ANSI codes."""
+    diff = max(0, width - vlen(s))
+    if align == 'r':
+        return ' ' * diff + s
+    if align == 'c':
+        lp = diff // 2
+        return ' ' * lp + s + ' ' * (diff - lp)
+    return s + ' ' * diff
+
+
+# ── Domain formatters ─────────────────────────────────────────────────────────
+
+_CLASS_COLOR = {
+    'idempotent': 'cyan',
+    'biphasic':   'yellow',
+    'involutive': 'magenta',
+    'asymmetric': 'red',
+}
+
+_DR_COLOR = {
+    1: 'blue',       2: 'blue',
+    3: 'cyan',       4: 'green',
+    5: 'yellow',     6: 'magenta',
+    7: 'red',        8: 'bright_red',
+    9: 'bright_white',
+}
+
+# Maps DR 1–9 to coloured block chars
+_BAR_CHAR = '█'
+
+
+def fmt_class(cls: str, enabled: bool, *, full: bool = True) -> str:
+    """Return symmetry *cls* with class-specific colour."""
+    return colorize(cls, _CLASS_COLOR.get(cls), enabled)
+
+
+def fmt_dr(dr: int, enabled: bool) -> str:
+    """Return the digit *dr* (1–9) in its energy colour."""
+    return colorize(str(dr), _DR_COLOR.get(dr), enabled)
+
+
+def fmt_float_e(e: float, enabled: bool) -> str:
+    """Format a float SymPhi energy with colour cues."""
+    s = f'{e:>9.4f}'
+    if not enabled:
+        return s
+    if e < 0:
+        return colorize(s, 'bright_magenta', True)
+    if e >= 10:
+        return colorize(s, 'bright_white', True)
+    return colorize(s, 'cyan', True)
+
+
+def fmt_valid(v: bool, enabled: bool) -> str:
+    if v:
+        return colorize('✓', 'bright_green', enabled)
+    return colorize('✗', 'bright_red', enabled)
+
+
+def fmt_form(form: str, enabled: bool) -> str:
+    if form == 'upper':
+        return colorize('DC', 'bold', enabled)
+    return colorize('ac', 'dim', enabled)
+
+
+def energy_bar(dr: int, count: int, max_count: int,
+               bar_width: int = 20, enabled: bool = True) -> str:
+    """Return a coloured block-bar proportional to *count* / *max_count*."""
+    filled = round(count / max_count * bar_width) if max_count else 0
+    bar = _BAR_CHAR * filled
+    return colorize(bar, _DR_COLOR.get(dr), enabled)
+
+
+def kv(key: str, value: str, enabled: bool = True, sep: str = '=') -> str:
+    """Return a dim *key* + *value* inline pair.
+
+    If *value* already contains ANSI codes it is passed through unchanged;
+    otherwise it is wrapped in bright_white.
+    """
+    from .ansi import strip_ansi
+    v = value if (enabled and strip_ansi(value) != value) else colorize(value, 'bright_white', enabled)
+    return colorize(key, 'dim', enabled) + sep + v
+
+
+def section(title: str, width: int = 44, enabled: bool = True) -> str:
+    """A light horizontal rule with a bold centred label.
+
+    Example: ``── classify ─────────────────────``
+    """
+    label = f' {title} '
+    prefix = '── '
+    fill = max(0, width - len(prefix) - len(label))
+    return (
+        colorize(prefix, 'dim', enabled)
+        + colorize(title, 'bold', enabled)
+        + colorize(' ' + '─' * fill, 'dim', enabled)
+    )
+
+
+# ── Box table ─────────────────────────────────────────────────────────────────
+
+class Box:
+    """Unicode-bordered table with ANSI-aware column widths.
+
+    Build the table, then call ``render()`` or ``print()``::
+
+        t = Box(['char', 'class', 'energy'], col_align=['c', 'l', 'r'])
+        t.row(['F', fmt_class('asymmetric', True), fmt_float_e(7.0, True)])
+        print(t.render())
+    """
+
+    _TL = '┌'; _TR = '┐'; _BL = '└'; _BR = '┘'
+    _TJ = '┬'; _BJ = '┴'; _LJ = '├'; _RJ = '┤'; _X  = '┼'
+    _H  = '─'; _V  = '│'
+
+    def __init__(
+        self,
+        headers: Sequence[str],
+        *,
+        col_align: Optional[Sequence[str]] = None,
+        enabled: bool = True,
+    ) -> None:
+        self._h      = list(headers)
+        self._rows:  List[List[str]] = []
+        self._aligns = list(col_align or ['l'] * len(headers))
+        self._divs:  set = set()          # row indices after which to draw ├─┤
+        self.enabled = enabled
+
+    # ── Builder API ───────────────────────────────────────────────────────────
+
+    def row(self, cells: Sequence[str]) -> 'Box':
+        self._rows.append(list(cells))
+        return self
+
+    def divider(self) -> 'Box':
+        """Insert a ├───┤ rule after the most recently added row."""
+        if self._rows:
+            self._divs.add(len(self._rows) - 1)
+        return self
+
+    # ── Rendering ─────────────────────────────────────────────────────────────
+
+    def render(self) -> str:
+        en  = self.enabled
+        nc  = len(self._h)
+
+        # Compute per-column widths from visible content
+        widths = [vlen(h) for h in self._h]
+        for row in self._rows:
+            for i in range(min(nc, len(row))):
+                widths[i] = max(widths[i], vlen(row[i]))
+
+        def bd(s: str) -> str:
+            return colorize(s, 'dim', en) if en else s
+
+        def hsep(left: str, mid: str, right: str) -> str:
+            segs = (bd(self._H * (w + 2)) for w in widths)
+            return bd(left) + bd(mid).join(segs) + bd(right)
+
+        def render_row(cells: List[str]) -> str:
+            parts: List[str] = []
+            for i in range(nc):
+                content = cells[i] if i < len(cells) else ''
+                a = self._aligns[i] if i < len(self._aligns) else 'l'
+                parts.append(' ' + vpad(content, widths[i], a) + ' ')
+            return bd(self._V) + bd(self._V).join(parts) + bd(self._V)
+
+        lines: List[str] = []
+        lines.append(hsep(self._TL, self._TJ, self._TR))
+        lines.append(render_row([colorize(h, 'bold', en) for h in self._h]))
+        lines.append(hsep(self._LJ, self._X, self._RJ))
+
+        for i, row in enumerate(self._rows):
+            lines.append(render_row(row))
+            if i in self._divs and i < len(self._rows) - 1:
+                lines.append(hsep(self._LJ, self._X, self._RJ))
+
+        lines.append(hsep(self._BL, self._BJ, self._BR))
+        return '\n'.join(lines)
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def print(self) -> None:
+        print(self.render())

gdk9/imply.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, asdict
+from typing import Any, Dict, List, Tuple
+
+from .errors import InputError
+
+
+NAME_RE = re.compile(r"^[A-Z][A-Za-z0-9_]*$")
+
+
+@dataclass
+class Rule:
+  name: str
+  type: str  # 'fusion' or 'split'
+  arity: int
+  params: Dict[str, Any]
+
+  def to_json(self) -> Dict[str, Any]:
+    return asdict(self)
+
+
+def validate_symbol_name(name: str) -> None:
+  if not NAME_RE.match(name):
+    raise InputError(f"Invalid symbol name: {name}")
+
+
+def make_fusion(rule_name: str, out_name: str, arity: int) -> Rule:
+  if arity < 2:
+    raise InputError("Fusion arity must be >= 2")
+  return Rule(name=rule_name, type="fusion", arity=arity, params={"out": out_name})
+
+
+def make_split(rule_name: str, out_a: str, out_b: str, ratio: float) -> Rule:
+  if not (0.0 <= ratio <= 1.0):
+    raise InputError("Split ratio must be between 0 and 1")
+  return Rule(name=rule_name, type="split", arity=1, params={"out_a": out_a, "out_b": out_b, "ratio": float(ratio)})
+
+
+def apply_rule(rule: Rule, symbols: Dict[str, float], inputs: List[str], tol: float = 1e-9) -> Dict[str, Any]:
+  if rule.type == "fusion":
+    if len(inputs) < rule.arity:
+      raise InputError(f"Rule '{rule.name}' requires at least {rule.arity} inputs")
+    energies = []
+    for name in inputs:
+      if name not in symbols:
+        raise InputError(f"Unknown symbol: {name}")
+      energies.append(float(symbols[name]))
+    total = sum(energies)
+    out_name = rule.params.get("out", "AUTO")
+    if out_name.upper() == "AUTO":
+      out_name = "".join(inputs)
+    validate_symbol_name(out_name)
+    outputs = [{"name": out_name, "energy": total}]
+    if abs(sum(energies) - sum(o["energy"] for o in outputs)) > tol:
+      raise InputError("Conservation failed in fusion")
+    return {"inputs": list(zip(inputs, energies)), "outputs": outputs}
+
+  if rule.type == "split":
+    if len(inputs) != 1:
+      raise InputError(f"Rule '{rule.name}' requires exactly 1 input")
+    name = inputs[0]
+    if name not in symbols:
+      raise InputError(f"Unknown symbol: {name}")
+    ein = float(symbols[name])
+    ratio = float(rule.params.get("ratio", 0.5))
+    out_a = str(rule.params.get("out_a", "OUT_A"))
+    out_b = str(rule.params.get("out_b", "OUT_B"))
+    validate_symbol_name(out_a)
+    validate_symbol_name(out_b)
+    ea = ein * ratio
+    eb = ein * (1.0 - ratio)
+    if not math.isfinite(ea) or not math.isfinite(eb):
+      raise InputError("Non-finite energies in split")
+    if abs(ein - (ea + eb)) > tol:
+      raise InputError("Conservation failed in split")
+    outputs = [{"name": out_a, "energy": ea}, {"name": out_b, "energy": eb}]
+    return {"inputs": [(name, ein)], "outputs": outputs}
+
+  raise InputError(f"Unsupported rule type: {rule.type}")
+

gdk9/io_utils.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .errors import InputError
+
+
+def read_input(text: Optional[str], file: Optional[str]) -> str:
+  if file and text:
+    raise InputError("Provide either text or --file, not both.")
+  if file:
+    p = Path(file)
+    if not p.exists() or not p.is_file():
+      raise InputError(f"File not found: {file}")
+    return p.read_text(encoding="utf-8", errors="replace")
+  if text:
+    return text
+  data = sys.stdin.read()
+  if not data:
+    raise InputError("No input provided. Pass text, --file, or pipe stdin.")
+  return data
+

gdk9/kernel/__init__.py

@@ -0,0 +1,24 @@
+"""Minimal symbolic implication kernel.
+
+The kernel package is intentionally independent from the CLI and plugin
+surfaces. It exposes small, typed primitives that can be composed and tested
+without file-system state, terminal output, or user configuration side effects.
+"""
+
+from .engine import ImplicationEngine
+from .expression import Expression
+from .principle import KernelPrinciple
+from .proof import Judgment, ProofStep
+from .rule import ImplicationRule, RuleKind
+from .symbol import Symbol
+
+__all__ = [
+  "Expression",
+  "ImplicationEngine",
+  "ImplicationRule",
+  "Judgment",
+  "KernelPrinciple",
+  "ProofStep",
+  "RuleKind",
+  "Symbol",
+]

gdk9/kernel/engine.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+from .errors import ConservationError, ImplicationError
+from .expression import Expression
+from .principle import KernelPrinciple
+from .proof import Judgment, ProofStep
+from .rule import ImplicationRule, RuleKind
+from .symbol import Symbol
+
+
+@dataclass
+class ImplicationEngine:
+  """Pure symbolic implication engine."""
+
+  principle: KernelPrinciple = field(default_factory=KernelPrinciple.default)
+  rules: tuple[ImplicationRule, ...] = ()
+
+  def evaluate(self, expression: Expression) -> tuple[float, int]:
+    total = expression.total_energy()
+    return total, expression.digital_root(self.principle)
+
+  def judge(self, rule: ImplicationRule, expression: Expression) -> Judgment:
+    before_total = expression.total_energy()
+    after = rule.apply(expression)
+    after_total = after.total_energy()
+    delta = after_total - before_total
+    conserved = abs(delta) <= rule.tolerance
+    if rule.preserves_energy and not conserved:
+      raise ConservationError(
+        f"Rule '{rule.name}' changed energy by {delta:.12g}"
+      )
+    return Judgment(rule.name, expression, after, conserved, delta)
+
+  def apply(self, rule_name: str, expression: Expression) -> Judgment:
+    for rule in self.rules:
+      if rule.name == rule_name:
+        return self.judge(rule, expression)
+    raise ImplicationError(f"Unknown rule: {rule_name}")
+
+  def normalize(self, expression: Expression, max_steps: int = 64) -> list[ProofStep]:
+    """Apply the first valid rule repeatedly until no rule changes the expression."""
+    steps: list[ProofStep] = []
+    current = expression
+    seen = {current.names()}
+    for index in range(max_steps):
+      for rule in self.rules:
+        try:
+          judgment = self.judge(rule, current)
+        except ImplicationError:
+          continue
+        if judgment.after.names() == current.names():
+          continue
+        if judgment.after.names() in seen:
+          return steps
+        step = ProofStep(judgment, index)
+        steps.append(step)
+        current = judgment.after
+        seen.add(current.names())
+        break
+      else:
+        return steps
+    return steps
+
+  def infer(
+    self,
+    source: Expression,
+    target: Expression,
+    max_depth: int = 4,
+  ) -> list[ProofStep] | None:
+    """Find a bounded implication path from source to target."""
+    if source.names() == target.names():
+      return []
+    queue: deque[tuple[Expression, list[ProofStep]]] = deque([(source, [])])
+    seen = {source.names()}
+    while queue:
+      current, path = queue.popleft()
+      if len(path) >= max_depth:
+        continue
+      for rule in self.rules:
+        try:
+          judgment = self.judge(rule, current)
+        except (ConservationError, ImplicationError):
+          continue
+        names = judgment.after.names()
+        if names in seen:
+          continue
+        next_path = [*path, ProofStep(judgment, len(path))]
+        if names == target.names():
+          return next_path
+        seen.add(names)
+        queue.append((judgment.after, next_path))
+    return None
+
+
+def fusion_rule(name: str = "fuse") -> ImplicationRule:
+  def transform(expression: Expression) -> Expression:
+    if len(expression) < 2:
+      raise ImplicationError("Fusion requires at least two symbols")
+    fused_name = "".join(expression.names())
+    return Expression((Symbol(fused_name, expression.total_energy()),))
+
+  return ImplicationRule(name, RuleKind.FUSION, transform, reversible=True)
+
+
+def split_rule(
+  parts: tuple[str, ...],
+  energies: tuple[float, ...],
+  name: str = "split",
+) -> ImplicationRule:
+  if len(parts) != len(energies):
+    raise ValueError("Split parts and energies must have the same length")
+  if not parts:
+    raise ValueError("Split requires at least one output part")
+
+  def transform(expression: Expression) -> Expression:
+    if len(expression) != 1:
+      raise ImplicationError("Split requires exactly one input symbol")
+    return Expression(tuple(Symbol(part, energy) for part, energy in zip(parts, energies)))
+
+  return ImplicationRule(name, RuleKind.SPLIT, transform, reversible=True)