godcode-engine 4.0.0__py3-none-any.whl

godcode/spirit.py

@@ -0,0 +1,180 @@
+"""SpiritEngine -- discerns the spiritual intent behind words. 🕊
+
+Loads the God Code training dataset, builds a keyword index over each row's
+primary_action + spiritual_intent + logic_flows, and classifies new text by
+keyword overlap. When nothing resonates, it falls back to silent contemplation.
+"""
+
+from __future__ import annotations
+
+import csv
+import re
+from collections import Counter
+from pathlib import Path
+
+_WORD_RE = re.compile(r"[a-z0-9]+")
+
+STOPWORDS = frozenset(
+    """
+    a an the of and to in for on with by or is are was were be been being
+    this that these those it its as at from into over under between through
+    during before after above below up down out off again further then once
+    here there when where why how all any both each few more most other some
+    such no nor not only own same so than too very can will just don should
+    now your you we they them their our us my me him her his she he i
+    do does did have has had shall may might must would could ought
+    """.split()
+)
+
+SILENT_CONTEMPLATION = {
+    "intent": "Silent contemplation",
+    "confidence": 0.0,
+    "spiritual_intent": "The Spirit is quiet on this matter.",
+    "suggestion": "BREATHE and try again.",
+    "keywords": [],
+}
+
+
+def _keywords(text: str) -> set[str]:
+    """Lowercase word tokens with stopwords removed."""
+    return {w for w in _WORD_RE.findall((text or "").lower()) if w not in STOPWORDS}
+
+
+class SpiritEngine:
+    """Keyword-overlap classifier over the God Code training dataset."""
+
+    def __init__(self, dataset_path: str | Path | None = None) -> None:
+        if dataset_path is None:
+            # Default: god_code_training_dataset.csv at the repo root.
+            dataset_path = Path(__file__).resolve().parent.parent / "god_code_training_dataset.csv"
+        self.dataset_path = Path(dataset_path)
+        self.rows: list[dict] = self._load()
+        # v4.0 -- declared intents: rite name -> natural-language intent text,
+        # registered by DECLARE INTENT and consulted by resolve_intent().
+        self.declared_intents: dict[str, str] = {}
+
+    def _load(self) -> list[dict]:
+        try:
+            with open(self.dataset_path, newline="", encoding="utf-8") as f:
+                records = list(csv.reader(f))
+        except OSError:
+            # No dataset beside the engine (e.g. an installed copy):
+            # the Spirit is quiet, and classify() falls back gracefully.
+            return []
+        if not records:
+            return []
+        header, records = records[0], records[1:]
+        rows: list[dict] = []
+        buf: list[str] = []
+        for rec in records:
+            if len(rec) == len(header):
+                # A row ends here: the code field may have spanned earlier
+                # physical lines (unquoted), accumulated in buf.
+                code = "\n".join(buf + [rec[0]])
+                row = dict(zip(header, [code] + rec[1:]))
+                row["keywords"] = _keywords(
+                    " ".join(row[c] for c in ("primary_action", "spiritual_intent", "logic_flows"))
+                )
+                rows.append(row)
+                buf = []
+            else:
+                # Continuation line of the multi-line code field.
+                buf.extend(rec)
+        return rows
+
+    def classify(self, text: str) -> dict:
+        """Classify text -> {intent, confidence, spiritual_intent, suggestion, keywords}."""
+        words = _keywords(text)
+        best: dict | None = None
+        best_overlap = 0
+        best_confidence = 0.0
+        for row in self.rows:
+            overlap = len(words & row["keywords"])
+            if overlap == 0:
+                continue
+            confidence = overlap / max(1, len(row["keywords"]))
+            # Most shared keywords wins; ties go to the row whose
+            # vocabulary best explains the input (highest confidence),
+            # so an incidental word cannot outshout the true theme.
+            if overlap > best_overlap or (
+                overlap == best_overlap and confidence > best_confidence
+            ):
+                best, best_overlap, best_confidence = row, overlap, confidence
+        if best is None:
+            return dict(SILENT_CONTEMPLATION)
+        confidence = min(1.0, best_overlap / max(1, len(best["keywords"])))
+        return {
+            "intent": best["primary_action"],
+            "confidence": round(confidence, 4),
+            "spiritual_intent": best["spiritual_intent"],
+            "suggestion": best["next_suggestions"],
+            "keywords": sorted(words & best["keywords"]),
+        }
+
+    def prophesy(self, program_text: str) -> str:
+        """Compose a 2-3 sentence divine forecast over a program's lines."""
+        lines = [ln.strip() for ln in (program_text or "").splitlines() if ln.strip()]
+        results = [self.classify(ln) for ln in lines] or [dict(SILENT_CONTEMPLATION)]
+        counts = Counter(r["intent"] for r in results)
+        top = max(counts.values())
+        # Dominant intent = mode; ties resolve to the earliest line's intent.
+        dominant = next(r for r in results if counts[r["intent"]] == top)
+        avg_conf = sum(r["confidence"] for r in results) / len(results)
+        pct = round(avg_conf * 100)
+        return (
+            f"Thus the Spirit speaks over this creation: the prevailing wind is "
+            f"'{dominant['intent']}', discerned with {pct}% certainty. "
+            f"{dominant['spiritual_intent']} "
+            f"Therefore the counsel of heaven is this: {dominant['suggestion']}"
+        )
+
+    # ------------------------------------------------- v4.0: intent layer
+
+    def declare_intent(self, rite_name: str, text: str) -> None:
+        """Register a natural-language intent on a named rite."""
+        self.declared_intents[str(rite_name)] = str(text)
+
+    def intents_aligned(self, declared: str, discerned: dict) -> bool:
+        """True when the declared intent shares a keyword with the discerned one.
+
+        *declared* is the natural-language text from DECLARE INTENT;
+        *discerned* is a classify() result for the rite's actual words.
+        The Spirit counsels on divergence; it never condemns.
+        """
+        declared_words = _keywords(declared)
+        discerned_words = (
+            _keywords(discerned.get("intent") or "")
+            | _keywords(discerned.get("spiritual_intent") or "")
+            | {str(k).lower() for k in (discerned.get("keywords") or [])}
+        )
+        return bool(declared_words & discerned_words)
+
+    def resolve_intent(self, text: str) -> dict:
+        """Classify *text* and report which declared intents it aligns with.
+
+        Returns the classify() payload plus ``aligned_with``: a list of
+        ``{rite, declared, shared_keywords}`` for every declared intent
+        sharing at least one keyword with the text.
+        """
+        result = self.classify(text)
+        words = _keywords(text)
+        aligned_with = []
+        for rite, declared in self.declared_intents.items():
+            shared = sorted(words & _keywords(declared))
+            if shared:
+                aligned_with.append(
+                    {"rite": rite, "declared": declared,
+                     "shared_keywords": shared}
+                )
+        result["aligned_with"] = aligned_with
+        return result
+
+    def counsel(self, question: str) -> str:
+        """Speak 2-3 sentences of counsel over a question, in prophesy's voice."""
+        r = self.classify(question)
+        pct = round(r["confidence"] * 100)
+        return (
+            f"Concerning '{question}', the Spirit discerns '{r['intent']}' "
+            f"with {pct}% certainty. {r['spiritual_intent']} "
+            f"Therefore the counsel of heaven is this: {r['suggestion']}"
+        )

godcode/tokens.py

@@ -0,0 +1,91 @@
+"""Token types and the Token dataclass for God Code v2.0.
+
+Keyword tokens carry their canonical UPPER name as ``value``;
+identifiers preserve the author's casing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class TokenType(Enum):
+    # --- keywords -----------------------------------------------------------
+    BEGIN = auto()
+    CREATION = auto()
+    END = auto()
+    DECLARE = auto()
+    AS = auto()
+    BREATHE = auto()
+    LIFE = auto()
+    INTO = auto()
+    REVEAL = auto()
+    PROPHESY = auto()
+    ASCEND = auto()
+    IF = auto()
+    THEN = auto()
+    ELSE = auto()
+    ENDIF = auto()
+    FOR = auto()
+    IN = auto()
+    ENDFOR = auto()
+    WHILE = auto()
+    DO = auto()
+    ENDWHILE = auto()
+    DEFINE = auto()
+    RITE = auto()
+    INVOKE = auto()
+    RETURN = auto()
+    IMPORT = auto()
+    IS = auto()
+    NOT = auto()
+    AND = auto()
+    OR = auto()
+    # §4 additions (missed in §1's list)
+    REFLECT = auto()
+    BLESS = auto()
+    ANOINT = auto()
+    SEAL = auto()
+    TESTIFY = auto()
+    # boolean / void literals (added for fmt <-> parse round-trip fidelity)
+    TRUE = auto()
+    FALSE = auto()
+    VOID = auto()
+    # --- literals -----------------------------------------------------------
+    NUMBER = auto()
+    STRING = auto()
+    IDENT = auto()
+    # --- operators ----------------------------------------------------------
+    PLUS = auto()      # +
+    MINUS = auto()     # -
+    STAR = auto()      # *
+    SLASH = auto()     # /
+    PERCENT = auto()   # %
+    EQ = auto()        # = or ==
+    NEQ = auto()       # !=
+    LT = auto()        # <
+    GT = auto()        # >
+    LTE = auto()       # <=
+    GTE = auto()       # >=
+    # --- punctuation --------------------------------------------------------
+    LPAREN = auto()
+    RPAREN = auto()
+    LBRACKET = auto()
+    RBRACKET = auto()
+    COMMA = auto()
+    # --- structural ---------------------------------------------------------
+    NEWLINE = auto()
+    EOF = auto()
+
+
+@dataclass
+class Token:
+    type: TokenType
+    value: object  # NUMBER -> int|float, STRING -> str (unescaped),
+                   # IDENT/keywords -> str, operators/punct -> the lexeme
+    line: int      # 1-based
+    col: int       # 1-based
+
+    def __repr__(self) -> str:  # compact, readable in test failures
+        return f"Token({self.type.name}, {self.value!r}, {self.line}:{self.col})"

godcode/tools.py

@@ -0,0 +1,378 @@
+"""Agent tool bridge for God Code v4.0 -- "Intent & Chain".
+
+MCP-compatible tool schemas plus a stdio JSON-RPC 2.0 bridge, with no
+third-party dependencies. ``godcode tools`` prints the schemas;
+``godcode bridge`` speaks the protocol so any MCP-compatible agent host
+can check, run, consult, resolve intent, and verify chains.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+TOOL_SCHEMAS: list[dict] = [
+    {
+        "name": "check",
+        "description": (
+            "Lex and parse a God Code scroll without running it. "
+            "Returns ok plus diagnostics with line, column, error code, "
+            "and a fix hint."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file": {"type": "string",
+                         "description": "Path to the .god scroll"},
+            },
+            "required": ["file"],
+        },
+    },
+    {
+        "name": "run",
+        "description": (
+            "Run a God Code scroll and capture its output. "
+            "Runs inside the deny-by-default sandbox unless sandbox is false."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file": {"type": "string",
+                         "description": "Path to the .god scroll"},
+                "sandbox": {"type": "boolean",
+                            "description": "Use the sandbox (default true)"},
+            },
+            "required": ["file"],
+        },
+    },
+    {
+        "name": "consult",
+        "description": (
+            "Ask the Spirit Engine -- the local oracle -- a question. "
+            "Returns two to three sentences of counsel. No external calls."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "question": {"type": "string",
+                             "description": "The question to lay before the Spirit"},
+            },
+            "required": ["question"],
+        },
+    },
+    {
+        "name": "intent",
+        "description": (
+            "Resolve the spiritual intent behind words with the Spirit "
+            "Engine: intent, confidence, spiritual intent, suggestion, "
+            "keywords, and declared intents the words align with."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "text": {"type": "string",
+                         "description": "Words to resolve the intent of"},
+            },
+            "required": ["text"],
+        },
+    },
+    {
+        "name": "anchor_verify",
+        "description": (
+            "Verify a blockchain anchor receipt (as returned by ANCHOR) "
+            "against its anchor chain."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "receipt": {"type": "object",
+                            "description": "The anchor receipt map"},
+            },
+            "required": ["receipt"],
+        },
+    },
+    {
+        "name": "ledger_verify",
+        "description": (
+            "Verify the covenant chain and the anchor chain for tampering."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file": {"type": "string",
+                         "description": "Covenant chain file (default covenant.chain)"},
+                "anchor_file": {"type": "string",
+                                "description": "Anchor chain file (default anchors.chain)"},
+            },
+            "required": [],
+        },
+    },
+]
+
+_TOOLS_BY_NAME = {t["name"]: t for t in TOOL_SCHEMAS}
+
+
+# ---------------------------------------------------------------------------
+# tool implementations (each returns a plain-JSON result dict)
+# ---------------------------------------------------------------------------
+def tool_check(arguments: dict) -> dict:
+    from godcode import agentics
+    from godcode.errors import GodCodeError
+    from godcode.lexer import Lexer
+    from godcode.parser import Parser
+
+    file = arguments.get("file")
+    if not isinstance(file, str):
+        return {"ok": False, "error": "check needs 'file' as a string path"}
+    try:
+        source = Path(file).read_text(encoding="utf-8")
+    except OSError as exc:
+        return {"ok": False, "error": f"cannot read '{file}': {exc.strerror or exc}"}
+    try:
+        Parser(Lexer(source).lex()).parse()
+    except GodCodeError as err:
+        return {"ok": False, "diagnostics": [agentics.diagnostic(err)]}
+    return {"ok": True, "diagnostics": []}
+
+
+def tool_run(arguments: dict) -> dict:
+    from godcode.errors import GodCodeError
+
+    file = arguments.get("file")
+    if not isinstance(file, str):
+        return {"ok": False, "error": "run needs 'file' as a string path"}
+    sandbox = arguments.get("sandbox", True)
+    try:
+        source = Path(file).read_text(encoding="utf-8")
+    except OSError as exc:
+        return {"ok": False, "error": f"cannot read '{file}': {exc.strerror or exc}"}
+    if sandbox:
+        from godcode.sandbox import run_sandboxed
+
+        try:
+            output = run_sandboxed(source, source_name=file)
+        except GodCodeError as err:
+            return {"ok": False, "output": [], "error": str(err)}
+        return {"ok": True, "output": output, "error": None}
+    from godcode.cli import _make_interpreter
+    import contextlib
+    import io
+
+    interp = _make_interpreter(None)
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf):
+            interp.run_source(source, source_name=file)
+    except GodCodeError as err:
+        return {"ok": False,
+                "output": buf.getvalue().splitlines(),
+                "error": str(err)}
+    return {"ok": True, "output": buf.getvalue().splitlines(), "error": None}
+
+
+def tool_consult(arguments: dict) -> dict:
+    from godcode.spirit import SpiritEngine
+
+    question = arguments.get("question")
+    if not isinstance(question, str):
+        return {"ok": False, "error": "consult needs 'question' as a string"}
+    try:
+        counsel = SpiritEngine().counsel(question)
+    except Exception as exc:  # pragma: no cover - defensive
+        return {"ok": False, "error": f"the oracle faltered: {exc}"}
+    return {"ok": True, "counsel": counsel}
+
+
+def tool_intent(arguments: dict) -> dict:
+    from godcode.spirit import SpiritEngine
+
+    text = arguments.get("text")
+    if not isinstance(text, str):
+        return {"ok": False, "error": "intent needs 'text' as a string"}
+    try:
+        result = SpiritEngine().resolve_intent(text)
+    except Exception as exc:  # pragma: no cover - defensive
+        return {"ok": False, "error": f"the Spirit faltered: {exc}"}
+    return {"ok": True, "result": result}
+
+
+def tool_anchor_verify(arguments: dict) -> dict:
+    from godcode.chain import default_adapters
+
+    receipt = arguments.get("receipt")
+    if not isinstance(receipt, dict):
+        return {"ok": False, "error": "anchor_verify needs 'receipt' as an object"}
+    chain_name = receipt.get("chain", "simulated")
+    adapter = default_adapters().get(chain_name)
+    if adapter is None:
+        return {"ok": False,
+                "error": f"unknown chain '{chain_name}'"}
+    valid = adapter.verify(receipt)
+    return {
+        "ok": True,
+        "valid": valid,
+        "message": ("the anchor stands" if valid
+                    else "the anchor does not verify"),
+    }
+
+
+def tool_ledger_verify(arguments: dict) -> dict:
+    from godcode.chain import SimulatedChainAdapter
+    from godcode.ledger import CovenantLedger
+
+    file = arguments.get("file", "covenant.chain")
+    anchor_file = arguments.get("anchor_file", "anchors.chain")
+    cov_ok, cov_msg = CovenantLedger(file).verify()
+    anc_ok, anc_msg = SimulatedChainAdapter(anchor_file).verify_chain()
+    return {
+        "ok": True,
+        "covenants": {"ok": cov_ok, "message": cov_msg},
+        "anchors": {"ok": anc_ok, "message": anc_msg},
+    }
+
+
+_TOOL_FUNCS = {
+    "check": tool_check,
+    "run": tool_run,
+    "consult": tool_consult,
+    "intent": tool_intent,
+    "anchor_verify": tool_anchor_verify,
+    "ledger_verify": tool_ledger_verify,
+}
+
+
+def call_tool(name: str, arguments: dict) -> dict:
+    """Run one tool by name; always returns a JSON-safe result dict."""
+    func = _TOOL_FUNCS.get(name)
+    if func is None:
+        return {"ok": False,
+                "error": f"unknown tool '{name}'",
+                "known_tools": sorted(_TOOL_FUNCS)}
+    if not isinstance(arguments, dict):
+        return {"ok": False, "error": "arguments must be an object"}
+    try:
+        return func(arguments)
+    except Exception as exc:  # pragma: no cover - defensive
+        return {"ok": False, "error": f"the tool faltered: {exc!r}"}
+
+
+# ---------------------------------------------------------------------------
+# `godcode tools`
+# ---------------------------------------------------------------------------
+def cmd_tools(args) -> int:
+    """Print the MCP-compatible tool schemas (--json for machines)."""
+    if getattr(args, "json", False):
+        print(json.dumps({"tools": TOOL_SCHEMAS}, ensure_ascii=False, indent=2))
+        return 0
+    print("God Code tools (MCP-compatible):")
+    for tool in TOOL_SCHEMAS:
+        required = ", ".join(tool["inputSchema"].get("required", [])) or "none"
+        print(f"  {tool['name']}({required}): {tool['description']}")
+    print("Speak them through `godcode bridge`, the stdio JSON-RPC loop.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# `godcode bridge` -- stdio JSON-RPC 2.0
+# ---------------------------------------------------------------------------
+_PARSE_ERROR = -32700
+_INVALID_REQUEST = -32600
+_METHOD_NOT_FOUND = -32601
+_INVALID_PARAMS = -32602
+_INTERNAL_ERROR = -32603
+
+
+def _response_ok(req_id, result: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+
+def _response_err(req_id, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": req_id,
+            "error": {"code": code, "message": message}}
+
+
+def _handle_initialize(params: dict) -> dict:
+    from godcode import __version__
+
+    return {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {"tools": {}},
+        "serverInfo": {"name": "godcode-bridge", "version": __version__},
+    }
+
+
+def _handle_tools_call(params: dict) -> dict:
+    name = params.get("name")
+    arguments = params.get("arguments", {})
+    if not isinstance(name, str):
+        raise _BridgeError(_INVALID_PARAMS, "tools/call needs 'name' as a string")
+    result = call_tool(name, arguments if isinstance(arguments, dict) else {})
+    content = [{"type": "text",
+                "text": json.dumps(result, ensure_ascii=False)}]
+    payload = {"content": content}
+    if not result.get("ok", True):
+        payload["isError"] = True
+    return payload
+
+
+class _BridgeError(Exception):
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def _dispatch(method: str, params: dict):
+    if method == "initialize":
+        return _handle_initialize(params)
+    if method == "ping":
+        return {}
+    if method == "tools/list":
+        return {"tools": TOOL_SCHEMAS}
+    if method == "tools/call":
+        return _handle_tools_call(params)
+    raise _BridgeError(_METHOD_NOT_FOUND, f"no such method '{method}'")
+
+
+def cmd_bridge(args) -> int:  # noqa: ARG001
+    """Serve the tool bridge: JSON-RPC 2.0 over stdio, one request per line."""
+    import sys
+
+    stdin, stdout = sys.stdin, sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            stdout.write(json.dumps(_response_err(None, _PARSE_ERROR,
+                                                 "the request was not JSON"))
+                         + "\n")
+            stdout.flush()
+            continue
+        req_id = request.get("id") if isinstance(request, dict) else None
+        # Notifications carry no id and get no answer.
+        is_notification = isinstance(request, dict) and "id" not in request
+        try:
+            if not isinstance(request, dict) or "method" not in request:
+                raise _BridgeError(_INVALID_REQUEST,
+                                   "a request needs a 'method'")
+            params = request.get("params", {})
+            if not isinstance(params, dict):
+                raise _BridgeError(_INVALID_PARAMS,
+                                   "'params' must be an object")
+            result = _dispatch(request["method"], params)
+        except _BridgeError as err:
+            response = _response_err(req_id, err.code, err.message)
+        except Exception as exc:  # pragma: no cover - defensive
+            response = _response_err(req_id, _INTERNAL_ERROR,
+                                     f"the bridge faltered: {exc!r}")
+        else:
+            if is_notification:
+                continue
+            response = _response_ok(req_id, result)
+        if is_notification:
+            continue
+        stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+        stdout.flush()
+    return 0