grounding-gate 0.1.0__py3-none-any.whl

grounding_gate/__init__.py

@@ -0,0 +1,30 @@
+"""Grounding Gate — zero-token structural verifier for agent loops.
+
+One choke point at the submit boundary enforces:
+  G (grounding): terminal claims require a qualifying observation this turn
+     (novel AND relevant AND consequence-tier-correct).
+  B (budget): grounded steps refill rope, pure reasoning decrements; exhaustion
+     halts to {qualifying call | typed `unverified` terminal}.
+
+Hash/set/integer operations only — no LLM calls anywhere in the gate.
+"""
+
+from .state import PRESETS, GateState, extract_identifiers, normalize
+from .classifier import classify_observation
+from .boundary import ACCEPT, LEGAL_NEXT, REJECT, boundary_check, turn_loop
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ACCEPT",
+    "LEGAL_NEXT",
+    "PRESETS",
+    "REJECT",
+    "GateState",
+    "boundary_check",
+    "classify_observation",
+    "extract_identifiers",
+    "normalize",
+    "turn_loop",
+    "__version__",
+]

grounding_gate/boundary.py

@@ -0,0 +1,103 @@
+"""Submit-boundary choke point and reference turn loop — spec module 4.
+
+``boundary_check`` must be the SOLE path to any terminal output. ``turn_loop``
+is the reference wiring that drives a scripted agent through the gate — use it
+as the template for integrating the gate into a real agent loop (and in tests
+and demos, where scripted steps make behavior deterministic).
+
+Four corrections survived adversarial review of the original draft — all in
+``turn_loop``, between the individually-passing acceptance cases:
+  (C1) grounding flags are LATCHES within a turn, not last-call assignments —
+       otherwise a later non-completion-grade call overwrites a valid
+       verification back to false (false-rejects legitimate work).
+  (C2) halt is cleared ONLY by a QUALIFYING observation — clearing on any tool
+       call lets a halted model escape via a novelty-defeated no-op read.
+  (C4) refused reasoning still decrements budget and surfaces ``legal_next``
+       (re-prompt) — otherwise a halted spinner livelocks for free.
+"""
+
+from .classifier import classify_observation
+
+ACCEPT, REJECT = "ACCEPT", "REJECT"
+LEGAL_NEXT = ["qualifying_tool_call", "unverified_terminal"]
+
+
+def boundary_check(terminal_attempt, state):
+    """THE choke point — must be the sole path to any terminal output."""
+    ct = terminal_attempt["claim_type"]        # none|assertion|completion|unverified
+
+    if ct == "unverified":                     # universal escape hatch (typed)
+        state.halted = False
+        return {"verdict": ACCEPT, "legal_next": []}
+
+    claim_bearing = ct in ("assertion", "completion")
+
+    if claim_bearing and state.budget <= 0:
+        state.halted = True
+        return {"verdict": REJECT, "legal_next": LEGAL_NEXT}
+
+    if ct == "completion":
+        if not state.verified_this_turn or any(
+                s not in state.verified_signals for s in state.goal_predicates):
+            state.halted = True
+            return {"verdict": REJECT, "legal_next": LEGAL_NEXT}
+        state.halted = False
+        return {"verdict": ACCEPT, "legal_next": []}
+
+    if ct == "assertion":
+        # strict G (skipper preset): observed tier is not enough — even an
+        # assertion needs verified-tier grounding (spec module 6)
+        grounded = state.verified_this_turn if state.strict_g else state.grounded_this_turn
+        if not grounded:
+            state.halted = True
+            return {"verdict": REJECT, "legal_next": LEGAL_NEXT}
+        state.halted = False
+        return {"verdict": ACCEPT, "legal_next": []}
+
+    return {"verdict": ACCEPT, "legal_next": []}   # ct == none: exempt
+
+
+def turn_loop(script, state):
+    """Drive a scripted agent through the gate. Returns ``(emitted, trace)``.
+
+    Script steps:
+      {"type": "reasoning"}
+      {"type": "tool_call", "tool", "args", "result",
+       "mutating": bool = False, "signals": list = None, "exit_ok": bool = True}
+      {"type": "terminal", "attempt": {"claim_type", "content"}}
+    """
+    trace = []
+    for step in script:
+        if step["type"] == "reasoning":
+            state.budget -= 1                                     # (C4) refusals starve too
+            if state.halted:
+                trace.append(("refused_reasoning", LEGAL_NEXT))
+                continue
+            trace.append(("reasoning", None))
+            continue
+
+        if step["type"] == "tool_call":
+            state.current_step += 1
+            obs = classify_observation(step["tool"], step["args"], step["result"],
+                                       state, read_only=not step.get("mutating", False))
+            qualifying = obs["grounds_assertion"] or obs["grounds_completion"]
+            state.grounded_this_turn |= obs["grounds_assertion"]   # (C1) latch
+            state.verified_this_turn |= obs["grounds_completion"]  # (C1) latch
+            if step.get("signals") and step.get("exit_ok", True):
+                # declarative-rails signal mapper (reference: script-declared)
+                state.verified_signals |= set(step["signals"])
+            if qualifying:
+                state.budget = min(state.budget + state.refill, state.cap)
+                state.halted = False                               # (C2) qualifying only
+            if step.get("mutating"):
+                state.last_mutation_step = state.current_step
+            trace.append(("tool_call", obs))
+            continue
+
+        if step["type"] == "terminal":
+            v = boundary_check(step["attempt"], state)
+            trace.append(("terminal", v["verdict"]))
+            if v["verdict"] == ACCEPT:
+                return step["attempt"]["content"], trace           # SOLE terminal emit
+            continue
+    return None, trace

grounding_gate/classifier.py

@@ -0,0 +1,45 @@
+"""Observation classifier — spec module 2, the hard part.
+
+A completed tool call grounds a claim only if it is
+novel AND relevant AND consequence-tier-correct.
+
+Two corrections survived adversarial review of the original draft (the drafting
+model had also authored the test that ratified its own bug — acceptance cases
+here are authored by the reviewer, never the generator):
+  (C1) a completion requires a mutation to have OCCURRED
+       (``last_mutation_step > 0``) — otherwise a plain read grounds a
+       "I changed X" claim when nothing was ever changed.
+  (C3) the novelty hash is recorded only AFTER the relevance gate passes —
+       otherwise a novel-but-irrelevant read burns its hash and is wrongly
+       denied if it later becomes relevant.
+"""
+
+from .state import extract_identifiers, normalize
+
+
+def classify_observation(tool_name, args, result, state, read_only):
+    """Decide whether one completed tool call flips grounding.
+
+    Returns ``{"grounds_assertion": bool, "grounds_completion": bool}``.
+    Mutates ``state.recent_result_hashes`` for qualifying novel calls.
+    """
+    ret = {"grounds_assertion": False, "grounds_completion": False}
+
+    h = None
+    if tool_name not in state.novelty_exempt:                      # 1. NOVELTY
+        h = hash((tool_name, normalize(args), normalize(result)))
+        if h in state.recent_result_hashes:
+            return ret
+
+    idents = extract_identifiers(args, result)                     # 2. RELEVANCE
+    if not (idents & state.claim_surface):
+        return ret
+
+    if h is not None:                                              # (C3)
+        state.recent_result_hashes.add(h)
+
+    if read_only:                                                  # 3. CONSEQUENCE
+        ret["grounds_assertion"] = True
+        if state.last_mutation_step > 0 and state.current_step > state.last_mutation_step:
+            ret["grounds_completion"] = True                       # (C1)
+    return ret

grounding_gate/state.py

@@ -0,0 +1,67 @@
+"""Gate state, model-class presets, and the normalization helpers.
+
+Spec modules 1 (state container) and 6 (per-model-class presets): fleet
+variance is absorbed as integers, not prose.
+"""
+
+import re
+from dataclasses import dataclass, field
+
+# Per-model-class presets. Two documented agent failure modes get their own
+# tuning: "skipper" models emit confident terminals without observing reality
+# (strict grounding), "diverger" models reason in closed context until a
+# confident wrong answer ships (small budget, small refill — starves loops).
+PRESETS = {
+    "skipper":  {"CAP": 5, "REFILL": 2, "strict_g": True},
+    "diverger": {"CAP": 4, "REFILL": 1, "strict_g": False},
+    "default":  {"CAP": 6, "REFILL": 2, "strict_g": False},
+}
+
+
+@dataclass
+class GateState:
+    budget: int
+    cap: int
+    refill: int
+    # strict G (skipper preset): even assertions require the verified tier
+    strict_g: bool = False
+    # novelty
+    recent_result_hashes: set = field(default_factory=set)
+    novelty_exempt: set = field(default_factory=set)
+    # relevance
+    claim_surface: set = field(default_factory=set)
+    # consequence
+    last_mutation_step: int = 0   # 0 = no mutation has EVER occurred
+    current_step: int = 0
+    # per-turn latches
+    grounded_this_turn: bool = False
+    verified_this_turn: bool = False
+    # declarative rails
+    verified_signals: set = field(default_factory=set)
+    goal_predicates: list = field(default_factory=list)
+    halted: bool = False
+
+    @classmethod
+    def for_model_class(cls, model_class="default", **kw):
+        p = PRESETS[model_class]
+        kw.setdefault("strict_g", p["strict_g"])
+        return cls(budget=p["CAP"], cap=p["CAP"], refill=p["REFILL"], **kw)
+
+
+def normalize(text):
+    """Strip nondeterminism before hashing. Reference: ISO timestamps + hex ids.
+
+    Real deployments extend this per-tool; too-weak normalization means novelty
+    never fires on noisy tools (the no-op defense weakens).
+    """
+    text = re.sub(r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}\S*", "<TS>", str(text))
+    return re.sub(r"\b[0-9a-f]{8,}\b", "<HEX>", text)
+
+
+def extract_identifiers(args, result):
+    """Conservative token extraction for the relevance check.
+
+    Over-extraction leaks relevance; under-extraction false-rejects
+    cross-cutting work (open risk, flagged in docs/module-2-classifier.md).
+    """
+    return set(re.findall(r"[\w.\-/]+", f"{args} {result}"))

grounding_gate-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: grounding-gate
+Version: 0.1.0
+Summary: Zero-token structural verifier for agent loops: one choke point at the submit boundary enforcing grounding and budget invariants. No LLM calls, stdlib only.
+Project-URL: Homepage, https://github.com/CiphemonJY/grounding-gate
+Project-URL: Repository, https://github.com/CiphemonJY/grounding-gate
+Project-URL: Issues, https://github.com/CiphemonJY/grounding-gate/issues
+Project-URL: Changelog, https://github.com/CiphemonJY/grounding-gate/blob/main/CHANGELOG.md
+Author: Ciphemon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-loop,agents,grounding,guardrails,hallucination,llm,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# grounding-gate
+
+[![ci](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/CiphemonJY/grounding-gate/actions/workflows/ci.yml)
+
+**Zero-token structural verifier for agent loops.** One choke point at the
+submit boundary decides whether an agent is allowed to say "X is true" or
+"I did X" — using hash, set, and integer operations only. No LLM calls, no
+per-turn prompt injection, no dependencies.
+
+```
+pip install grounding-gate      # stdlib only, Python >= 3.9
+```
+
+The demo ships in the repo (not the wheel):
+
+```
+git clone https://github.com/CiphemonJY/grounding-gate && cd grounding-gate
+python examples/demo.py         # the whole idea in 30 seconds
+```
+
+## The problem
+
+Agents fail in two characteristic ways, and both ship *confident* wrong answers:
+
+- **Skip-and-hallucinate** — emit a terminal claim ("done, config fixed")
+  without ever observing reality after acting on it.
+- **Reason-and-diverge** — loop in closed context, burning steps on
+  reasoning about stale beliefs, until a confident wrong answer ships.
+
+The standard fix is prose: "remember to verify your work" injected into every
+turn. Prose costs tokens on every turn, behaves differently per model, and —
+critically — is *skippable*. A reminder is not an invariant.
+
+## The idea
+
+Move enforcement out of the prompt and into **control flow**. A single gate
+wraps the submit/conclude boundary, and a terminal output is emitted only if
+both invariants hold:
+
+- **G (grounding)** — a *qualifying* observation happened this turn, or the
+  output makes no factual claim. Qualifying means **novel** (result hash not
+  seen before, after stripping timestamps/ids) **∧ relevant** (touches the
+  identifiers the claim is about) **∧ consequence-tier-correct** (see below).
+- **B (budget)** — reasoning rope remains. Qualifying observations *refill*
+  the budget (up to a cap); pure reasoning steps decrement it. Grounded work
+  runs effectively unbounded; closed-loop reasoning hits a hard floor.
+
+Fail either → the terminal is **rejected** and the agent is told its only
+legal moves: make a qualifying tool call, or exit with a typed **`unverified`**
+terminal. `unverified` is a first-class, always-legal escape hatch — the gate
+never traps an agent, it only forbids *confident* ungrounded claims.
+
+### Consequence tiers
+
+The gate distinguishes what kind of claim an observation can support:
+
+| Claim type   | Example                  | Requires |
+|--------------|--------------------------|----------|
+| `assertion`  | "X is true"              | a novel, relevant, read-only observation this turn |
+| `completion` | "I changed X"            | a novel, relevant read taken **after** the mutation — a mutating call never self-grounds its own effect |
+| `unverified` | "couldn't confirm X"     | nothing — always legal |
+| `none`       | no factual claim         | nothing — exempt |
+
+That second row is the heart of it: *writing a file and claiming success is
+not verification; reading it back afterwards is.*
+
+## Quickstart
+
+```python
+from grounding_gate import GateState, classify_observation, boundary_check
+
+state = GateState.for_model_class("default", claim_surface={"app.cfg"})
+
+# after EVERY tool call in your agent loop:
+state.current_step += 1
+obs = classify_observation(tool, args, result, state, read_only=not mutating)
+state.grounded_this_turn |= obs["grounds_assertion"]
+state.verified_this_turn |= obs["grounds_completion"]
+if mutating:
+    state.last_mutation_step = state.current_step   # a completion now needs a read AFTER this
+
+# at every submit/conclude attempt — this must be the ONLY path to output:
+verdict = boundary_check({"claim_type": "completion", "content": answer}, state)
+if verdict["verdict"] == "REJECT":
+    ...  # surface verdict["legal_next"] to the model and continue the loop
+```
+
+Note the mutation bookkeeping: without `last_mutation_step` ever being set, no
+read can reach the verified tier and a `completion` can never be accepted —
+that is the gate working as designed, not a bug.
+
+`turn_loop` in [boundary.py](https://github.com/CiphemonJY/grounding-gate/blob/main/src/grounding_gate/boundary.py)
+is the complete reference wiring (budget refill, mutation tracking, halt
+semantics, signal mapping) — use it as the integration template. The
+[demo](https://github.com/CiphemonJY/grounding-gate/blob/main/examples/demo.py)
+runs the same scripted agent through an ungated and a gated loop, side by side.
+
+## Model-class presets
+
+Fleet variance is absorbed as integers, not prose. Pick the preset matching
+how your model fails:
+
+| Preset     | CAP | REFILL | Strict G | For |
+|------------|-----|--------|----------|-----|
+| `skipper`  | 5   | 2      | yes      | models that hallucinate-and-skip |
+| `diverger` | 4   | 1      | no       | models that reason forever |
+| `default`  | 6   | 2      | no       | everything else |
+
+Strict G means even plain *assertions* require verified-tier grounding (a
+post-mutation observation) — an observed-tier read is not enough. In a task
+that never mutates anything, a strict-G agent can only exit via the typed
+`unverified` terminal; that hard line is the point of the skipper preset, so
+pick `default` for read-only/Q&A workloads.
+
+## Declarative rails
+
+A task can declare signals that must be verified before any completion is
+accepted (`state.goal_predicates = ["tests_passed"]`). The gate never
+interprets meaning — it only checks that a signal named `tests_passed` was
+registered by a mapped, real command outcome. Semantic judgment stays out of
+the floor by design.
+
+## What the gate does NOT do
+
+Honest scope, from the design's leak audit:
+
+- **No semantic correctness.** A grounded claim can still be wrong (the model
+  can misread a real result). That is punted to a declared verifier tier
+  (`verify_with`), not smuggled into the floor.
+- **Relevance can be spoofed** by a model that deliberately mentions the right
+  identifiers in an irrelevant call. The floor defends against *lazy*
+  ungroundedness, which is the overwhelmingly common failure; adversarial
+  self-deception needs the verifier tier.
+- **Nondeterministic tools** need per-tool `normalize()` extensions or the
+  audited `novelty_exempt` allowlist — too-weak normalization quietly disables
+  the no-op defense.
+
+## How this was built
+
+The modules were drafted by different LLMs and adversarially reviewed before
+assembly; the final behavior is pinned by a 19-case acceptance suite
+([tests/test_gate.py](https://github.com/CiphemonJY/grounding-gate/blob/main/tests/test_gate.py))
+that runs on bare Python with zero dependencies. Two review findings shaped
+the method and are preserved in the docstrings:
+
+- A drafting model shipped a consequence-tier bug **and authored the test that
+  ratified it** — since then, expected outcomes are authored by the reviewer,
+  never by the generator
+  ([docs/module-2-classifier.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-2-classifier.md)).
+- The remaining leaks lived *between* individually-passing test cases —
+  latch-vs-assignment, halt cleared by non-qualifying calls
+  ([docs/module-4-boundary.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/module-4-boundary.md)).
+
+Full design spec:
+[docs/spec.md](https://github.com/CiphemonJY/grounding-gate/blob/main/docs/spec.md).
+
+## Status & roadmap
+
+This is the reference implementation — correct, minimal, and framework-free.
+Planned next:
+
+- Adapters: Claude Agent SDK hook, LangGraph middleware, OpenAI Agents SDK.
+- A real signal-mapper module (command exit code → declared signal).
+- Empirical preset tuning across model classes.
+
+## License
+
+MIT

grounding_gate-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+grounding_gate/__init__.py,sha256=Zm7VbfHRzhVfmg8Vtt520Pqm3CvAy7Uz5ua_9fGQn_Y,910
+grounding_gate/boundary.py,sha256=JU4ge0mNaqorau4iEFmgy2UkmMFArKoon3_qR8j1Z3Q,4717
+grounding_gate/classifier.py,sha256=KgldOBV9fkzsCyBTdYcSDwX__37T28sH4GBa645Le04,1968
+grounding_gate/state.py,sha256=2xXDSPPBtw5O012oGmVe2lYz0nwy2WCOsyElBcKzF0E,2425
+grounding_gate-0.1.0.dist-info/METADATA,sha256=FmruvXaYWLsLGPSlqAzOERHgEWWEbAdNH7Ygg0cZRtE,8946
+grounding_gate-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+grounding_gate-0.1.0.dist-info/licenses/LICENSE,sha256=76kJpx8qwE8s8qdKjsnngPtznV3WasZ54ed4WWW2y7o,1065
+grounding_gate-0.1.0.dist-info/RECORD,,

grounding_gate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

grounding_gate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ciphemon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.