gdk9-cli 0.3.0__py3-none-any.whl

gdk9/kernel/errors.py

@@ -0,0 +1,17 @@
+"""Kernel-specific exceptions."""
+
+
+class KernelError(Exception):
+  """Base exception for symbolic implication kernel failures."""
+
+
+class ConservationError(KernelError):
+  """Raised when a transformation violates an invariant."""
+
+
+class ImplicationError(KernelError):
+  """Raised when a rule cannot be applied to an expression."""
+
+
+class UnknownSymbolError(KernelError):
+  """Raised when an expression references a symbol absent from a principle."""

gdk9/kernel/expression.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Sequence
+
+from .principle import KernelPrinciple
+from .symbol import Symbol
+
+
+@dataclass(frozen=True)
+class Expression:
+  """An ordered symbolic expression."""
+
+  symbols: tuple[Symbol, ...]
+
+  @classmethod
+  def from_names(cls, names: Iterable[str], principle: KernelPrinciple) -> "Expression":
+    return cls(tuple(Symbol(name, principle.energy_of(name)) for name in names))
+
+  @classmethod
+  def from_text(cls, text: str, principle: KernelPrinciple) -> "Expression":
+    return cls.from_names(text, principle)
+
+  def __iter__(self) -> Iterator[Symbol]:
+    return iter(self.symbols)
+
+  def __len__(self) -> int:
+    return len(self.symbols)
+
+  def names(self) -> tuple[str, ...]:
+    return tuple(symbol.name for symbol in self.symbols)
+
+  def total_energy(self) -> float:
+    return sum(symbol.energy for symbol in self.symbols)
+
+  def digital_root(self, principle: KernelPrinciple) -> int:
+    return principle.total_root(self.total_energy())
+
+  def text(self) -> str:
+    return "".join(self.names())
+
+  def replace(self, symbols: Sequence[Symbol]) -> "Expression":
+    return Expression(tuple(symbols))

gdk9/kernel/principle.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+from gdk9.energy import char_energy, digital_root
+from gdk9.principles import Principle
+
+
+@dataclass(frozen=True)
+class KernelPrinciple:
+  """Immutable valuation context for kernel expressions."""
+
+  name: str
+  symbol_energy: Mapping[str, float] = field(default_factory=dict)
+  source: Principle | None = None
+  normalize_zero_to_nine: bool = True
+
+  @classmethod
+  def default(cls) -> "KernelPrinciple":
+    principle = Principle.default()
+    return cls(
+      name=principle.name,
+      symbol_energy=dict(principle.symbol_energy),
+      source=principle,
+      normalize_zero_to_nine=principle.normalize_zero_to_nine,
+    )
+
+  def energy_of(self, name: str) -> float:
+    if len(name) == 1:
+      if self.source is not None:
+        return float(char_energy(name, self.source))
+      explicit = self.symbol_energy.get(name)
+      if explicit is not None:
+        return float(explicit)
+      return float(digital_root(ord(name), self.normalize_zero_to_nine))
+    explicit = self.symbol_energy.get(name)
+    if explicit is not None:
+      return float(explicit)
+    return sum(self.energy_of(ch) for ch in name)
+
+  def total_root(self, total: float) -> int:
+    return digital_root(int(round(total)), self.normalize_zero_to_nine)

gdk9/kernel/proof.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .expression import Expression
+
+
+@dataclass(frozen=True)
+class Judgment:
+  """The result of applying one implication rule."""
+
+  rule: str
+  before: Expression
+  after: Expression
+  conserved: bool
+  delta: float
+
+
+@dataclass(frozen=True)
+class ProofStep:
+  """A traceable implication step suitable for proof paths."""
+
+  judgment: Judgment
+  index: int

gdk9/kernel/rule.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable
+
+from .expression import Expression
+
+Transform = Callable[[Expression], Expression]
+
+
+class RuleKind(str, Enum):
+  FUSION = "fusion"
+  SPLIT = "split"
+  REWRITE = "rewrite"
+
+
+@dataclass(frozen=True)
+class ImplicationRule:
+  """A pure implication transform with invariant metadata."""
+
+  name: str
+  kind: RuleKind
+  transform: Transform
+  reversible: bool = False
+  preserves_energy: bool = True
+  tolerance: float = 1e-9
+
+  def apply(self, expression: Expression) -> Expression:
+    return self.transform(expression)

gdk9/kernel/symbol.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+
+@dataclass(frozen=True)
+class Symbol:
+  """A named symbolic unit with an evaluated energy."""
+
+  name: str
+  energy: float
+  traits: Mapping[str, str] = field(default_factory=dict)
+
+  def __post_init__(self) -> None:
+    if not self.name:
+      raise ValueError("Symbol name must be non-empty")
+    if not isinstance(self.energy, (int, float)):
+      raise TypeError("Symbol energy must be numeric")

gdk9/kernel_cli.py

@@ -0,0 +1,195 @@
+"""Thin CLI/API adapter for the pure implication kernel.
+
+Lives outside ``gdk9.kernel`` so the kernel package stays free of CLI, state,
+plugin, crypto, TUI, and terminal-formatting imports.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Sequence
+
+from gdk9.errors import InputError
+from gdk9.kernel import Expression, ImplicationEngine, KernelPrinciple
+from gdk9.kernel.engine import fusion_rule, split_rule
+from gdk9.kernel.errors import ConservationError, ImplicationError, KernelError
+from gdk9.kernel.proof import Judgment, ProofStep
+from gdk9.kernel.rule import ImplicationRule
+from gdk9.principles import Principle
+
+
+def principle_to_kernel(principle: Principle) -> KernelPrinciple:
+  """Adapt a GDk9 ``Principle`` into an immutable ``KernelPrinciple``."""
+  return KernelPrinciple(
+    name=principle.name,
+    symbol_energy=dict(principle.symbol_energy),
+    source=principle,
+    normalize_zero_to_nine=principle.normalize_zero_to_nine,
+  )
+
+
+def expression_payload(expression: Expression) -> dict[str, Any]:
+  return {
+    "names": list(expression.names()),
+    "text": expression.text(),
+    "total_energy": expression.total_energy(),
+    "symbols": [
+      {"name": symbol.name, "energy": symbol.energy} for symbol in expression.symbols
+    ],
+  }
+
+
+def judgment_payload(judgment: Judgment) -> dict[str, Any]:
+  return {
+    "rule": judgment.rule,
+    "before": expression_payload(judgment.before),
+    "after": expression_payload(judgment.after),
+    "conserved": judgment.conserved,
+    "delta": judgment.delta,
+  }
+
+
+def proof_steps_payload(steps: Sequence[ProofStep]) -> list[dict[str, Any]]:
+  return [
+    {"index": step.index, "judgment": judgment_payload(step.judgment)} for step in steps
+  ]
+
+
+def _parse_float_list(raw: str, label: str) -> tuple[float, ...]:
+  parts = [p.strip() for p in raw.split(",") if p.strip()]
+  if not parts:
+    raise InputError(f"{label} must list at least one value")
+  try:
+    return tuple(float(p) for p in parts)
+  except ValueError as exc:
+    raise InputError(f"Invalid {label}: {raw}") from exc
+
+
+def _parse_name_list(raw: str, label: str) -> tuple[str, ...]:
+  parts = [p.strip() for p in raw.split(",") if p.strip()]
+  if not parts:
+    raise InputError(f"{label} must list at least one symbol name")
+  return tuple(parts)
+
+
+def builtin_rules(
+  names: Sequence[str],
+  *,
+  split_parts: tuple[str, ...] | None = None,
+  split_energies: tuple[float, ...] | None = None,
+) -> tuple[ImplicationRule, ...]:
+  """Build the small set of demo rules used by the kernel smoke path."""
+  rules: list[ImplicationRule] = []
+  for name in names:
+    key = name.strip().lower()
+    if key in {"fuse", "fusion"}:
+      rules.append(fusion_rule(name="fuse"))
+    elif key == "split":
+      if not split_parts or not split_energies:
+        raise InputError("split requires --parts and --energies")
+      rules.append(split_rule(split_parts, split_energies, name="split"))
+    else:
+      raise InputError(f"Unknown builtin kernel rule: {name}")
+  return tuple(rules)
+
+
+def _print_json(payload: dict[str, Any]) -> int:
+  print(json.dumps(payload, indent=2, ensure_ascii=False))
+  return 0
+
+
+def cmd_kernel_eval(args: Any, principle: Principle) -> int:
+  kp = principle_to_kernel(principle)
+  expr = Expression.from_text(args.text, kp)
+  total, root = ImplicationEngine(kp).evaluate(expr)
+  return _print_json(
+    {
+      "ok": True,
+      "cmd": "eval",
+      "expression": expression_payload(expr),
+      "total": total,
+      "digital_root": root,
+      "principle": kp.name,
+    }
+  )
+
+
+def cmd_kernel_apply(args: Any, principle: Principle) -> int:
+  kp = principle_to_kernel(principle)
+  names = tuple(args.symbols)
+  if not names:
+    raise InputError("apply requires at least one symbol name")
+  expr = Expression.from_names(names, kp)
+  split_parts = _parse_name_list(args.parts, "parts") if getattr(args, "parts", None) else None
+  split_energies = (
+    _parse_float_list(args.energies, "energies") if getattr(args, "energies", None) else None
+  )
+  rules = builtin_rules(
+    [args.rule],
+    split_parts=split_parts,
+    split_energies=split_energies,
+  )
+  engine = ImplicationEngine(kp, rules)
+  try:
+    judgment = engine.apply(rules[0].name, expr)
+  except KernelError as exc:
+    return _print_json({"ok": False, "cmd": "apply", "error": str(exc)})
+  return _print_json(
+    {
+      "ok": True,
+      "cmd": "apply",
+      "judgment": judgment_payload(judgment),
+      "principle": kp.name,
+    }
+  )
+
+
+def cmd_kernel_search(args: Any, principle: Principle) -> int:
+  kp = principle_to_kernel(principle)
+  source_names = tuple(args.source)
+  target_names = tuple(args.target)
+  if not source_names or not target_names:
+    raise InputError("search requires --source and --target symbol names")
+  source = Expression.from_names(source_names, kp)
+  target = Expression.from_names(target_names, kp)
+  rule_names = list(args.rules) if getattr(args, "rules", None) else ["fuse"]
+  split_parts = _parse_name_list(args.parts, "parts") if getattr(args, "parts", None) else None
+  split_energies = (
+    _parse_float_list(args.energies, "energies") if getattr(args, "energies", None) else None
+  )
+  rules = builtin_rules(
+    rule_names,
+    split_parts=split_parts,
+    split_energies=split_energies,
+  )
+  engine = ImplicationEngine(kp, rules)
+  max_depth = int(getattr(args, "max_depth", 4))
+  path = engine.infer(source, target, max_depth=max_depth)
+  return _print_json(
+    {
+      "ok": path is not None,
+      "cmd": "search",
+      "found": path is not None,
+      "max_depth": max_depth,
+      "source": expression_payload(source),
+      "target": expression_payload(target),
+      "rules": [rule.name for rule in rules],
+      "steps": proof_steps_payload(path or ()),
+      "principle": kp.name,
+    }
+  )
+
+
+def run_kernel(args: Any, principle: Principle) -> int:
+  """Dispatch ``gdk9 kernel …`` subcommands."""
+  cmd = getattr(args, "kernel_cmd", None)
+  try:
+    if cmd == "eval":
+      return cmd_kernel_eval(args, principle)
+    if cmd == "apply":
+      return cmd_kernel_apply(args, principle)
+    if cmd == "search":
+      return cmd_kernel_search(args, principle)
+  except (ConservationError, ImplicationError) as exc:
+    return _print_json({"ok": False, "cmd": cmd, "error": str(exc)})
+  raise InputError(f"Unknown kernel subcommand: {cmd}")

gdk9/log.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+
+class Logger:
+  def __init__(self, enabled: bool = False) -> None:
+    self.enabled = enabled or (os.getenv("GDK9_DEBUG") == "1")
+
+  def set_enabled(self, enabled: bool) -> None:
+    self.enabled = bool(enabled)
+
+  def debug(self, *args: Any) -> None:
+    if self.enabled:
+      msg = " ".join(str(a) for a in args)
+      print(f"[gdk9:debug] {msg}", file=sys.stderr)
+
+  def info(self, *args: Any) -> None:
+    msg = " ".join(str(a) for a in args)
+    print(msg)
+
+  def error(self, *args: Any) -> None:
+    msg = " ".join(str(a) for a in args)
+    print(msg, file=sys.stderr)
+
+
+logger = Logger()
+

gdk9/optimize.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+from .energy import digital_root, string_energy, char_energy
+from .principles import Principle
+
+
+@dataclass
+class Plan:
+  method: str
+  target: int
+  steps: List[Tuple[str, int]]  # (symbol, count)
+  total_before: int
+  dr_before: int
+  total_after: int
+  dr_after: int
+
+
+def _residue(n: int) -> int:
+  return n % 9
+
+
+def _target_residue(total: int, target: int) -> int:
+  cur_r = _residue(total)
+  tgt_r = target % 9  # 9 -> 0
+  return (tgt_r - cur_r) % 9
+
+
+def _allowed_residues(allowed: List[Tuple[str, int]]) -> Dict[int, List[str]]:
+  by_res: Dict[int, List[str]] = {i: [] for i in range(9)}
+  for s, e in allowed:
+    r = e % 9
+    by_res[r].append(s)
+  return by_res
+
+
+def minimal_residue_combo(delta_res: int, allowed: List[Tuple[str, int]], max_steps: int = 64) -> Optional[List[int]]:
+  # BFS on residues 0..8; each step adds one symbol residue
+  residues = [e % 9 for _, e in allowed]
+  if delta_res == 0:
+    return []
+  # If all residues are 0 we cannot change the residue
+  if all(r == 0 for r in residues):
+    return None
+  parent = {0: (-1, -1)}  # residue -> (prev_residue, symbol_index)
+  q = deque([0])
+  depth = {0: 0}
+  while q:
+    cur = q.popleft()
+    d = depth[cur]
+    if d >= max_steps:
+      continue
+    for idx, r in enumerate(residues):
+      nxt = (cur + r) % 9
+      if nxt not in parent:
+        parent[nxt] = (cur, idx)
+        depth[nxt] = d + 1
+        if nxt == delta_res:
+          # reconstruct path of indices
+          seq: List[int] = []
+          at = nxt
+          while at != 0:
+            prev, i = parent[at]
+            seq.append(i)
+            at = prev
+          seq.reverse()
+          return seq
+        q.append(nxt)
+  return None
+
+
+def build_steps_from_seq(seq: List[int], allowed: List[Tuple[str, int]]) -> List[Tuple[str, int]]:
+  counts: Dict[int, int] = {}
+  for i in seq:
+    counts[i] = counts.get(i, 0) + 1
+  steps: List[Tuple[str, int]] = []
+  for i, (sym, _e) in enumerate(allowed):
+    if i in counts:
+      steps.append((sym, counts[i]))
+  return steps
+
+
+def optimize_attunement(
+  text: str,
+  target: int,
+  principle: Principle,
+  allowed_symbols: Optional[str] = None,
+  method: str = "append",
+  max_steps: int = 64,
+) -> Plan:
+  total, dr = string_energy(text, principle)
+  if not (1 <= target <= 9):
+    raise ValueError("Target energy must be 1..9")
+  if dr == target:
+    return Plan(method, target, [], total, dr, total, dr)
+  # Determine allowed symbol energies
+  if not allowed_symbols:
+    allowed_symbols = ".!?,*+"  # sensible defaults with varied residues
+  allowed: List[Tuple[str, int]] = []
+  for s in allowed_symbols:
+    e = char_energy(s, principle)
+    if e == 0:
+      continue
+    allowed.append((s, e))
+  if not allowed:
+    raise ValueError("No valid allowed symbols; provide a non-empty set.")
+  delta_res = _target_residue(total, target)
+  seq = minimal_residue_combo(delta_res, allowed, max_steps=max_steps)
+  if seq is None:
+    raise ValueError("No feasible combination to reach target with given symbols.")
+  steps = build_steps_from_seq(seq, allowed)
+  added = sum(count * char_energy(sym, principle) for sym, count in steps)
+  new_total = total + added
+  new_dr = digital_root(new_total, principle.normalize_zero_to_nine)
+  return Plan(method, target, steps, total, dr, new_total, new_dr)
+
+
+def apply_plan(text: str, plan: Plan, spread: Optional[int] = None) -> str:
+  if not plan.steps:
+    return text
+  if plan.method == "append":
+    suffix = "".join(sym * count for sym, count in plan.steps)
+    return text + suffix
+  if plan.method == "prepend":
+    prefix = "".join(sym * count for sym, count in plan.steps)
+    return prefix + text
+  if plan.method == "intersperse":
+    # Spread symbols approximately evenly through text
+    chars = list(text)
+    inserts: List[str] = []
+    for sym, count in plan.steps:
+      inserts.extend([sym] * count)
+    if not chars:
+      return "".join(inserts)
+    n = len(inserts)
+    if n == 0:
+      return text
+    interval = spread or max(1, len(chars) // (n + 1))
+    out: List[str] = []
+    i_ins = 0
+    for i, ch in enumerate(chars):
+      out.append(ch)
+      if (i + 1) % interval == 0 and i_ins < n:
+        out.append(inserts[i_ins])
+        i_ins += 1
+    while i_ins < n:
+      out.append(inserts[i_ins])
+      i_ins += 1
+    return "".join(out)
+  raise ValueError(f"Unsupported method: {plan.method}")
+
+
+@dataclass
+class EditOp:
+  kind: str  # 'sub', 'del', 'ins'
+  pos: int
+  ch: Optional[str] = None
+  count: int = 1
+
+
+@dataclass
+class EditPlan:
+  method: str  # 'substitute' or 'edit'
+  target: int
+  ops: List[EditOp]
+  total_before: int
+  dr_before: int
+  total_after: int
+  dr_after: int
+
+
+def apply_edit_plan(text: str, plan: EditPlan) -> str:
+  if not plan.ops:
+    return text
+  chars = list(text)
+  # Apply deletions first from highest pos to lowest
+  dels = [op for op in plan.ops if op.kind == 'del']
+  for op in sorted(dels, key=lambda o: o.pos, reverse=True):
+    if 0 <= op.pos < len(chars):
+      del chars[op.pos]
+  # Apply substitutions
+  subs = [op for op in plan.ops if op.kind == 'sub']
+  for op in subs:
+    if 0 <= op.pos < len(chars) and op.ch is not None:
+      chars[op.pos] = op.ch
+  # Apply insertions from lowest pos to highest
+  ins = [op for op in plan.ops if op.kind == 'ins']
+  for op in sorted(ins, key=lambda o: o.pos):
+    insert_str = (op.ch or '') * max(1, op.count)
+    if 0 <= op.pos <= len(chars):
+      left = ''.join(chars[:op.pos])
+      right = ''.join(chars[op.pos:])
+      chars = list(left + insert_str + right)
+  return ''.join(chars)
+
+
+def optimize_substitution(
+  text: str,
+  target: int,
+  principle: Principle,
+  subs: Optional[Dict[str, List[str]]] = None,
+  allow_delete: bool = False,
+  allowed_inserts: Optional[str] = None,
+  max_edits: int = 8,
+) -> EditPlan:
+  total, dr = string_energy(text, principle)
+  if not (1 <= target <= 9):
+    raise ValueError("Target energy must be 1..9")
+  if dr == target:
+    return EditPlan('substitute', target, [], total, dr, total, dr)
+
+  # Build per-position residue deltas for substitutions (and deletions)
+  n = len(text)
+  pos_deltas: List[List[Tuple[int, Optional[str]]]] = [[] for _ in range(n)]
+  for i, ch in enumerate(text):
+    cur_e = char_energy(ch, principle)
+    seen: Dict[int, str] = {}
+    # substitution options
+    if subs and ch in subs:
+      for repl in subs[ch]:
+        new_e = char_energy(repl, principle)
+        r = (new_e - cur_e) % 9
+        if r not in seen:
+          seen[r] = repl
+    # trivial case-change option for letters
+    if ch.isalpha():
+      alt = ch.swapcase()
+      if alt != ch:
+        new_e = char_energy(alt, principle)
+        r = (new_e - cur_e) % 9
+        if r not in seen:
+          seen[r] = alt
+    for r, repl in seen.items():
+      if r != 0:  # ignore no-ops
+        pos_deltas[i].append((r, repl))
+    # deletion option
+    if allow_delete:
+      rdel = (-cur_e) % 9
+      if rdel != 0:
+        pos_deltas[i].append((rdel, None))
+
+  delta_res = _target_residue(total, target)
+  # DP over residues with minimal edits, tracking choices
+  # state: residue -> (count, prev_residue, (pos, r, repl))
+  best: Dict[int, Tuple[int, int, Tuple[int, int, Optional[str]]]] = {0: (0, -1, (-1, 0, None))}
+  frontier = [0]
+  for i in range(n):
+    new_best = best.copy()
+    for res, (cnt, prev, info) in best.items():
+      for r, repl in pos_deltas[i]:
+        nr = (res + r) % 9
+        nc = cnt + 1
+        if nc > max_edits:
+          continue
+        if nr not in new_best or nc < new_best[nr][0]:
+          new_best[nr] = (nc, res, (i, r, repl))
+    best = new_best
+
+  if delta_res not in best:
+    # Try insertion-only fallback using symbol residues
+    if allowed_inserts:
+      append_plan = optimize_attunement(text, target, principle, allowed_symbols=allowed_inserts, method='append')
+      ops: List[EditOp] = []
+      for sym, cnt in append_plan.steps:
+        ops.append(EditOp('ins', len(text), sym, cnt))
+      out = apply_edit_plan(text, EditPlan('edit', target, ops, total, dr, total, dr))
+      new_total, new_dr = string_energy(out, principle)
+      return EditPlan('edit', target, ops, total, dr, new_total, new_dr)
+    raise ValueError("No feasible substitution/deletion plan to reach target.")
+
+  # Reconstruct
+  ops: List[EditOp] = []
+  cur = delta_res
+  while cur != 0:
+    cnt, prev, (pos, r, repl) = best[cur]
+    if pos >= 0:
+      if repl is None:
+        ops.append(EditOp('del', pos))
+      else:
+        ops.append(EditOp('sub', pos, repl))
+    cur = prev
+  # Apply and compute totals
+  out = apply_edit_plan(text, EditPlan('edit', target, list(reversed(ops)), total, dr, total, dr))
+  new_total, new_dr = string_energy(out, principle)
+  return EditPlan('edit', target, list(reversed(ops)), total, dr, new_total, new_dr)