verdict4 0.2.0__tar.gz

verdict4-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the released tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distributions
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/verdict4
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

verdict4-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/
+.venv/

verdict4-0.2.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to verdict4 are documented here.
+
+## 0.2.0 — 2026-09-04
+
+- Add the substrate-free `QICTController` with finite-rank termination.
+- Add typed `EvidenceNeed` and `ComputeNeed` payloads for `MAYBE`.
+- Add one-use failure, evidence, computation, and dependency alphabets.
+- Add logical lease expiry as a controller event.
+- Add receipt replay auditing without candidate activations.
+- Preserve the v0.1.0 runner API and legacy string `MAYBE` behavior.
+
+## 0.1.0 — 2026-07-17
+
+- Initial four-verdict protocol and agent-loop runner.

verdict4-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaCortex Dynamics
+
+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.

verdict4-0.2.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: verdict4
+Version: 0.2.0
+Summary: Four-value evaluation for agentic AI loops. Replace pass/fail with NO/YES/MAYBE/IFF.
+Project-URL: Homepage, https://github.com/MetaCortex-Dynamics/verdict4
+Project-URL: Documentation, https://metacortexdynamics.substack.com/p/your-loop-has-two-states-it-needs
+Project-URL: Repository, https://github.com/MetaCortex-Dynamics/verdict4
+Project-URL: Issues, https://github.com/MetaCortex-Dynamics/verdict4/issues
+Project-URL: Paper, https://doi.org/10.5281/zenodo.22309225
+Author-email: MetaCortex Dynamics <Contact@metacortexdynamics.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic,ai,evaluation,loop,quaternary,verdict
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# verdict4
+
+Four-value evaluation for agentic AI loops.
+
+**Replace pass/fail with NO / YES / MAYBE / IFF.**
+
+Most agentic loops evaluate with a boolean. Pass or fail. That works when every non-pass condition is actually failure. But it is not. Some outputs cannot be evaluated yet because evidence is missing. Some outputs are correct only if another result holds. A boolean check compresses both into failure and destroys correct work.
+
+This package provides a four-value `Verdict` enum, a structured `CheckResult`, and a loop runner that handles all four branches.
+
+Read the full explanation: [Your Loop Has Two States. It Needs Four.](https://metacortexdynamics.substack.com/p/your-loop-has-two-states-it-needs)
+
+The finite-rank controller is specified in [Quaternary Iteration Control for Looped Transformers](https://doi.org/10.5281/zenodo.22309225). The controller is included in this release; looped-transformer substrate integration is in preparation.
+
+## Install
+
+Install directly from GitHub:
+
+```bash
+pip install git+https://github.com/MetaCortex-Dynamics/verdict4.git@v0.2.0
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/MetaCortex-Dynamics/verdict4.git
+cd verdict4
+pip install -e .
+```
+
+After the GitHub release has published the package to PyPI, install the pinned release with:
+
+```bash
+pip install verdict4==0.2.0
+```
+
+Until that release workflow completes, use the GitHub install above.
+
+## Quick start
+
+```python
+from quaternary import Verdict, CheckResult, no, yes, maybe, iff, run
+
+# Define your check function — return a CheckResult, not a bool
+def check(output):
+    if not output.get("valid"):
+        return no("validation failed: missing required field")
+    if not output.get("schema_available"):
+        return maybe("schema file not found")
+    if output.get("depends_on_auth"):
+        return iff("auth module deployed")
+    return yes()
+
+# Define your generator
+def generate(task, *, exclusions):
+    # Your agent generates output here
+    # `exclusions` carries named reasons from prior NO results
+    return {"valid": True, "schema_available": True}
+
+# Run the loop
+outcome = run(
+    task="build parser",
+    generate=generate,
+    check=check,
+)
+
+print(outcome.status)       # "accepted" | "held" | "blocked" | "exhausted"
+print(outcome.exclusions)   # accumulated NO reasons
+print(outcome.rounds)       # how many iterations
+```
+
+## The four verdicts
+
+| Verdict | Meaning | Loop action |
+|---------|---------|-------------|
+| `NO`    | Fails a named condition | Add reason to exclusions, retry |
+| `YES`   | Satisfies conditions | Accept |
+| `MAYBE` | Cannot evaluate — evidence missing | Hold, gather evidence, recheck |
+| `IFF`   | Correct if dependency holds | Bind to dependency, resolve, recheck |
+
+## API
+
+### Core types
+
+```python
+from quaternary import Verdict, CheckResult, no, yes, maybe, iff
+```
+
+**`Verdict`** — `IntEnum` with values `NO=0`, `YES=1`, `MAYBE=2`, `IFF=3`
+
+**`CheckResult`** — frozen dataclass:
+- `verdict: Verdict`
+- `reason: str | None` — required for `NO`
+- `needed: str | EvidenceNeed | ComputeNeed | None` — required for `MAYBE`
+- `dependency: str | None` — required for `IFF`
+- `meta: dict[str, Any]` — optional domain metadata
+
+**Constructors**: `no(reason)`, `yes()`, `maybe(needed)`, `iff(dependency)` — all accept `**meta` kwargs.
+
+### Runner
+
+```python
+from quaternary import run, LoopOutcome
+```
+
+**`run(task, *, generate, check, ...)`** — runs the quaternary loop.
+
+Required:
+- `generate(task, *, exclusions) -> output`
+- `check(output) -> CheckResult`
+
+Optional:
+- `gather(needed) -> evidence` — called on MAYBE
+- `recheck(output, evidence?) -> CheckResult` — called after gather or dependency resolution
+- `is_resolved(dep) -> bool` — called on IFF
+- `is_failed(dep) -> bool` — called on IFF
+- `max_rounds: int` — default 10
+- `on_hold(output, reason)` — callback when holding
+- `on_blocked(output, dep)` — callback when blocked
+
+**`LoopOutcome`**:
+- `status`: `"accepted"` | `"held"` | `"blocked"` | `"exhausted"`
+- `output`: the final output (or None if exhausted)
+- `exclusions`: accumulated NO reasons
+- `rounds`: iterations used
+- `held_reason` / `blocked_by`: why the loop stopped
+- `contradiction`: flagged contradictory exclusion pairs (if any)
+
+### Finite-rank controller
+
+Version 0.2.0 adds a substrate-free controller for repeated computation. It
+preserves the v0.1.0 runner API while adding typed `MAYBE` needs, finite
+one-use alphabets, dependency bindings, logical leases, and replayable
+accounting receipts.
+
+```python
+from quaternary import (
+    ComputeNeed,
+    QICTConfig,
+    QICTController,
+    maybe,
+    rank,
+    yes,
+)
+
+config = QICTConfig(compute_alphabet={"next_1", "next_2"})
+controller = QICTController(config)
+initial_rank = rank(config, controller.state)
+
+controller.process(maybe(ComputeNeed("next_1")))
+controller.process(maybe(ComputeNeed("next_2")))
+controller.process(yes())
+
+assert controller.state.evaluation_count <= initial_rank + 1
+assert controller.audit().valid
+```
+
+Every evaluation that continues consumes exactly one finite opportunity: a
+new exclusion, an evidence request, another computation, or a dependency.
+Therefore the controller terminates in at most `initial_rank + 1`
+evaluations, without assuming that the evaluator is sound.
+
+Receipts contain controller accounting state and transition data. Candidate
+activations are excluded from the receipt state by type.
+
+## Examples
+
+```bash
+python examples/json_parser.py
+python examples/multi_file_refactor.py
+```
+
+## Design constraints
+
+- **Zero domain logic.** The runner is a protocol over user-supplied callables.
+- **No framework.** The fix is local — an enum and a branch.
+- **Bounded MAYBE.** A second MAYBE after evidence gathering → hold and report. No infinite gather loops.
+- **Exclusion memory.** NO reasons accumulate across rounds. Contradictions are flagged, not resolved.
+- **No dependencies.** Standard library only.
+
+## License
+
+MIT — [MetaCortex Dynamics](https://github.com/MetaCortex-Dynamics)

verdict4-0.2.0/README.md

@@ -0,0 +1,183 @@
+# verdict4
+
+Four-value evaluation for agentic AI loops.
+
+**Replace pass/fail with NO / YES / MAYBE / IFF.**
+
+Most agentic loops evaluate with a boolean. Pass or fail. That works when every non-pass condition is actually failure. But it is not. Some outputs cannot be evaluated yet because evidence is missing. Some outputs are correct only if another result holds. A boolean check compresses both into failure and destroys correct work.
+
+This package provides a four-value `Verdict` enum, a structured `CheckResult`, and a loop runner that handles all four branches.
+
+Read the full explanation: [Your Loop Has Two States. It Needs Four.](https://metacortexdynamics.substack.com/p/your-loop-has-two-states-it-needs)
+
+The finite-rank controller is specified in [Quaternary Iteration Control for Looped Transformers](https://doi.org/10.5281/zenodo.22309225). The controller is included in this release; looped-transformer substrate integration is in preparation.
+
+## Install
+
+Install directly from GitHub:
+
+```bash
+pip install git+https://github.com/MetaCortex-Dynamics/verdict4.git@v0.2.0
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/MetaCortex-Dynamics/verdict4.git
+cd verdict4
+pip install -e .
+```
+
+After the GitHub release has published the package to PyPI, install the pinned release with:
+
+```bash
+pip install verdict4==0.2.0
+```
+
+Until that release workflow completes, use the GitHub install above.
+
+## Quick start
+
+```python
+from quaternary import Verdict, CheckResult, no, yes, maybe, iff, run
+
+# Define your check function — return a CheckResult, not a bool
+def check(output):
+    if not output.get("valid"):
+        return no("validation failed: missing required field")
+    if not output.get("schema_available"):
+        return maybe("schema file not found")
+    if output.get("depends_on_auth"):
+        return iff("auth module deployed")
+    return yes()
+
+# Define your generator
+def generate(task, *, exclusions):
+    # Your agent generates output here
+    # `exclusions` carries named reasons from prior NO results
+    return {"valid": True, "schema_available": True}
+
+# Run the loop
+outcome = run(
+    task="build parser",
+    generate=generate,
+    check=check,
+)
+
+print(outcome.status)       # "accepted" | "held" | "blocked" | "exhausted"
+print(outcome.exclusions)   # accumulated NO reasons
+print(outcome.rounds)       # how many iterations
+```
+
+## The four verdicts
+
+| Verdict | Meaning | Loop action |
+|---------|---------|-------------|
+| `NO`    | Fails a named condition | Add reason to exclusions, retry |
+| `YES`   | Satisfies conditions | Accept |
+| `MAYBE` | Cannot evaluate — evidence missing | Hold, gather evidence, recheck |
+| `IFF`   | Correct if dependency holds | Bind to dependency, resolve, recheck |
+
+## API
+
+### Core types
+
+```python
+from quaternary import Verdict, CheckResult, no, yes, maybe, iff
+```
+
+**`Verdict`** — `IntEnum` with values `NO=0`, `YES=1`, `MAYBE=2`, `IFF=3`
+
+**`CheckResult`** — frozen dataclass:
+- `verdict: Verdict`
+- `reason: str | None` — required for `NO`
+- `needed: str | EvidenceNeed | ComputeNeed | None` — required for `MAYBE`
+- `dependency: str | None` — required for `IFF`
+- `meta: dict[str, Any]` — optional domain metadata
+
+**Constructors**: `no(reason)`, `yes()`, `maybe(needed)`, `iff(dependency)` — all accept `**meta` kwargs.
+
+### Runner
+
+```python
+from quaternary import run, LoopOutcome
+```
+
+**`run(task, *, generate, check, ...)`** — runs the quaternary loop.
+
+Required:
+- `generate(task, *, exclusions) -> output`
+- `check(output) -> CheckResult`
+
+Optional:
+- `gather(needed) -> evidence` — called on MAYBE
+- `recheck(output, evidence?) -> CheckResult` — called after gather or dependency resolution
+- `is_resolved(dep) -> bool` — called on IFF
+- `is_failed(dep) -> bool` — called on IFF
+- `max_rounds: int` — default 10
+- `on_hold(output, reason)` — callback when holding
+- `on_blocked(output, dep)` — callback when blocked
+
+**`LoopOutcome`**:
+- `status`: `"accepted"` | `"held"` | `"blocked"` | `"exhausted"`
+- `output`: the final output (or None if exhausted)
+- `exclusions`: accumulated NO reasons
+- `rounds`: iterations used
+- `held_reason` / `blocked_by`: why the loop stopped
+- `contradiction`: flagged contradictory exclusion pairs (if any)
+
+### Finite-rank controller
+
+Version 0.2.0 adds a substrate-free controller for repeated computation. It
+preserves the v0.1.0 runner API while adding typed `MAYBE` needs, finite
+one-use alphabets, dependency bindings, logical leases, and replayable
+accounting receipts.
+
+```python
+from quaternary import (
+    ComputeNeed,
+    QICTConfig,
+    QICTController,
+    maybe,
+    rank,
+    yes,
+)
+
+config = QICTConfig(compute_alphabet={"next_1", "next_2"})
+controller = QICTController(config)
+initial_rank = rank(config, controller.state)
+
+controller.process(maybe(ComputeNeed("next_1")))
+controller.process(maybe(ComputeNeed("next_2")))
+controller.process(yes())
+
+assert controller.state.evaluation_count <= initial_rank + 1
+assert controller.audit().valid
+```
+
+Every evaluation that continues consumes exactly one finite opportunity: a
+new exclusion, an evidence request, another computation, or a dependency.
+Therefore the controller terminates in at most `initial_rank + 1`
+evaluations, without assuming that the evaluator is sound.
+
+Receipts contain controller accounting state and transition data. Candidate
+activations are excluded from the receipt state by type.
+
+## Examples
+
+```bash
+python examples/json_parser.py
+python examples/multi_file_refactor.py
+```
+
+## Design constraints
+
+- **Zero domain logic.** The runner is a protocol over user-supplied callables.
+- **No framework.** The fix is local — an enum and a branch.
+- **Bounded MAYBE.** A second MAYBE after evidence gathering → hold and report. No infinite gather loops.
+- **Exclusion memory.** NO reasons accumulate across rounds. Contradictions are flagged, not resolved.
+- **No dependencies.** Standard library only.
+
+## License
+
+MIT — [MetaCortex Dynamics](https://github.com/MetaCortex-Dynamics)

verdict4-0.2.0/examples/json_parser.py

@@ -0,0 +1,123 @@
+"""
+Worked example: JSON parser — binary vs quaternary convergence.
+
+From: "Your Loop Has Two States. It Needs Four."
+https://metacortexdynamics.substack.com/p/your-loop-has-two-states-it-needs
+
+Simulates the JSON parser scenario from the post.
+Binary loop: 3 full generations, oscillation.
+Quaternary loop: 1 generation, 1 targeted repair, convergence.
+"""
+
+from __future__ import annotations
+
+from quaternary import CheckResult, LoopOutcome, Verdict, iff, maybe, no, run, yes
+
+
+# --- Simulated component state ---
+
+class SimulatedParser:
+    """Simulates a parser that initially fails on nested arrays
+    and has a missing schema import."""
+
+    def __init__(self) -> None:
+        self.handles_nested_arrays = False
+        self.schema_imported = False
+        self.generation_count = 0
+
+    def generate(self, task: str, *, exclusions: list[str]) -> dict[str, str]:
+        self.generation_count += 1
+
+        # After being told about the nested array issue, fix it
+        if "nested array not handled" in exclusions:
+            self.handles_nested_arrays = True
+
+        return {
+            "parser": "json_parser_v" + str(self.generation_count),
+            "handles_nested": str(self.handles_nested_arrays),
+            "schema_imported": str(self.schema_imported),
+        }
+
+    def check(self, output: dict[str, str]) -> CheckResult:
+        """Evaluate each component."""
+        # Test 1: basic parsing — always passes
+        # Test 2: nested arrays
+        if output["handles_nested"] == "False":
+            return no("nested array not handled")
+
+        # Validator: depends on schema import
+        if output["schema_imported"] == "False":
+            return iff("schema library imported")
+
+        return yes()
+
+    def is_resolved(self, dep: str) -> bool:
+        if dep == "schema library imported":
+            # Simulate: resolve by importing
+            self.schema_imported = True
+            return True
+        return False
+
+    def is_failed(self, dep: str) -> bool:
+        return False
+
+    def recheck(self, output: dict[str, str], evidence: object = None) -> CheckResult:
+        # After dependency resolved, recheck
+        if self.schema_imported and self.handles_nested_arrays:
+            return yes()
+        return no("still failing after dependency resolution")
+
+
+def run_binary_simulation() -> None:
+    """Simulate binary loop behavior from the post."""
+    print("=" * 60)
+    print("BINARY LOOP (simulated)")
+    print("=" * 60)
+
+    generations = 0
+    for attempt in range(1, 4):
+        generations += 1
+        print(f"\nRound {attempt}: generate everything from scratch")
+        if attempt == 1:
+            print("  test 2 fails: nested arrays not handled")
+            print("  -> regenerate everything")
+        elif attempt == 2:
+            print("  test 1 now fails (regression)")
+            print("  -> regenerate everything")
+        elif attempt == 3:
+            print("  schema validator fails: missing import")
+            print("  -> regenerate everything")
+
+    print(f"\nResult: {generations} full generations, oscillation, no convergence")
+
+
+def run_quaternary() -> None:
+    """Run actual quaternary loop."""
+    print("\n" + "=" * 60)
+    print("QUATERNARY LOOP")
+    print("=" * 60)
+
+    sim = SimulatedParser()
+
+    outcome: LoopOutcome = run(
+        task="write json parser with schema validation",
+        generate=sim.generate,
+        check=sim.check,
+        recheck=sim.recheck,
+        is_resolved=sim.is_resolved,
+        is_failed=sim.is_failed,
+        max_rounds=5,
+    )
+
+    print(f"\nStatus: {outcome.status}")
+    print(f"Rounds: {outcome.rounds}")
+    print(f"Generations: {sim.generation_count}")
+    print(f"Exclusions accumulated: {outcome.exclusions}")
+    if outcome.contradiction:
+        print(f"Contradictions flagged: {outcome.contradiction}")
+    print(f"Output: {outcome.output}")
+
+
+if __name__ == "__main__":
+    run_binary_simulation()
+    run_quaternary()