feat(core): add PartialValidationResult with tri-state semantics (#924)

* feat(core): add PartialValidationResult with tri-state semantics

Adds PartialValidationResult to mellea/core/requirement.py — a tri-state
result type for per-chunk streaming validation. Follows the same
private-fields-with-property-accessors pattern as ValidationResult.

success: Literal["pass", "fail", "unknown"]. __bool__ returns True for
"pass", False for "fail" and "unknown". "pass" is informational only in
Phase 1; orchestrators call validate() at stream end for all non-"fail"
results.

Closes #898
Part of #891

Assisted-by: Claude Code
Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>

* fix(core): add explicit Literal type annotation to PartialValidationResult._success

Pyright infers self._success as str without the annotation because it doesn't
narrow Literal types through bare instance attribute assignment. The explicit
annotation makes the property return type verifiable.

Assisted-by: Claude Code
Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>

* fix(core): address PR #924 review feedback on PartialValidationResult

- Update mellea/core/__init__.py module docstring to mention PartialValidationResult
- Update mellea/core/requirement.py module docstring to mention PartialValidationResult
- Document ValidationResult/PartialValidationResult API asymmetry in class docstring
- Add runtime validation of success parameter (fail fast on invalid values)
- Expand as_bool() docstring with streaming-context warning for "unknown" → False
- Add __repr__ for opaque debug output in streaming pipelines
- Replace test_as_bool_matches_bool loop with parametrised test_as_bool_correctness
- Add test_invalid_success_raises and test_repr_shows_state

Assisted-by: Claude Code
Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>

* fix(core): add ValidationResult.__repr__ and thunk/context tests

- Add __repr__ to ValidationResult for parity with PartialValidationResult
- Add test_thunk_field and test_context_field to close the test coverage gap
  for keyword-only constructor arguments (previously only default-None was
  verified)

Assisted-by: Claude Code
Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>

---------

Signed-off-by: Nigel Jones <jonesn@uk.ibm.com>

Author: planetf1

mellea/core/__init__.py

@@ -4,7 +4,7 @@
 other layer of mellea is built: the ``Backend``, ``Formatter``, and
 ``SamplingStrategy`` protocols; the ``Component``, ``CBlock``, ``Context``, and
 ``ModelOutputThunk`` data types that flow through the inference pipeline; and
-``Requirement`` / ``ValidationResult`` for constrained generation. Start here when
+``Requirement`` / ``ValidationResult`` / ``PartialValidationResult`` for constrained generation. Start here when
 building a new backend, formatter, or sampling strategy, or when you need the type
 definitions shared across the library.
 """
@@ -29,7 +29,12 @@
     blockify,
 )
 from .formatter import Formatter
-from .requirement import Requirement, ValidationResult, default_output_to_bool
+from .requirement import (
+    PartialValidationResult,
+    Requirement,
+    ValidationResult,
+    default_output_to_bool,
+)
 from .sampling import SamplingResult, SamplingStrategy
 from .utils import MelleaLogger, clear_log_context, log_context, set_log_context
 
@@ -66,6 +71,7 @@ def __getattr__(name: str) -> object:
     "MelleaLogger",
     "ModelOutputThunk",
     "ModelToolCall",
+    "PartialValidationResult",
     "Requirement",
     "S",
     "SamplingResult",

mellea/core/requirement.py

@@ -4,13 +4,16 @@
 inspects a ``Context`` (and optionally a backend) to determine whether a model output
 meets a constraint. ``ValidationResult`` carries the pass/fail verdict along with an
 optional reason, score, and the ``ModelOutputThunk`` produced during validation.
+``PartialValidationResult`` provides a tri-state variant (``"pass"``, ``"fail"``,
+``"unknown"``) for per-chunk streaming validation.
 Helper factories such as ``default_output_to_bool`` make it easy to build requirements
 without boilerplate.
 """
 
 import re
 from collections.abc import Callable
 from copy import copy
+from typing import Literal
 
 from .backend import Backend, BaseModelSubclass
 from .base import CBlock, Component, Context, ModelOutputThunk, TemplateRepresentation
@@ -76,6 +79,97 @@ def __bool__(self) -> bool:
         """Return a boolean value based on the result."""
         return self.as_bool()
 
+    def __repr__(self) -> str:
+        """Return a developer-readable representation of the validation result."""
+        return f"ValidationResult({self._result!r}, reason={self._reason!r}, score={self._score!r})"
+
+
+class PartialValidationResult:
+    """Tri-state result from per-chunk streaming validation.
+
+    Unlike :class:`ValidationResult`, which stores its verdict as a private
+    ``_result: bool``, this class exposes ``success`` as a public property.
+    The asymmetry is intentional: the tri-state value cannot be recovered from
+    a ``bool``, so a public property is the only way to distinguish ``"fail"``
+    from ``"unknown"`` after construction.
+
+    Args:
+        success: Validation state — ``"pass"`` (constraint satisfied so far),
+            ``"fail"`` (constraint violated, stop streaming), or
+            ``"unknown"`` (insufficient data yet, continue streaming).
+        reason: Optional human-readable explanation.
+        score: Optional numeric confidence score.
+        thunk: Optional ModelOutputThunk from the validation call.
+        context: Optional context associated with the validation call.
+
+    """
+
+    def __init__(
+        self,
+        success: Literal["pass", "fail", "unknown"],
+        *,
+        reason: str | None = None,
+        score: float | None = None,
+        thunk: ModelOutputThunk | None = None,
+        context: Context | None = None,
+    ):
+        """Initialize PartialValidationResult with a tri-state success value."""
+        if success not in ("pass", "fail", "unknown"):
+            raise ValueError(
+                f"success must be 'pass', 'fail', or 'unknown', got {success!r}"
+            )
+        self._success: Literal["pass", "fail", "unknown"] = success
+        self._reason = reason
+        self._score = score
+        self._thunk = thunk
+        self._context = context
+
+    @property
+    def success(self) -> Literal["pass", "fail", "unknown"]:
+        """The tri-state validation result."""
+        return self._success
+
+    @property
+    def reason(self) -> str | None:
+        """Reason for the validation result."""
+        return self._reason
+
+    @property
+    def score(self) -> float | None:
+        """An optional score for the validation result."""
+        return self._score
+
+    @property
+    def thunk(self) -> ModelOutputThunk | None:
+        """The ModelOutputThunk associated with the validation call, if any."""
+        return self._thunk
+
+    @property
+    def context(self) -> Context | None:
+        """The context associated with the validation call, if any."""
+        return self._context
+
+    def as_bool(self) -> bool:
+        """Return True for ``"pass"``, False for ``"fail"`` or ``"unknown"``.
+
+        ``"unknown"`` maps to ``False`` intentionally. In streaming contexts,
+        check ``pvr.success == "unknown"`` before treating ``False`` as a definitive
+        failure — ``"unknown"`` means insufficient data so far, not a constraint
+        violation.
+
+        Returns:
+            bool: ``True`` if the partial result is ``"pass"``, ``False`` otherwise.
+        """
+        return self._success == "pass"
+
+    def __bool__(self) -> bool:
+        """Return a boolean value based on the success state."""
+        return self.as_bool()
+
+    def __repr__(self) -> str:
+        """Return a developer-readable representation showing the tri-state value."""
+        return f"PartialValidationResult({self._success!r}, reason={self._reason!r}, score={self._score!r})"
+
 
 def default_output_to_bool(x: CBlock | str) -> bool:
     """Convert a model output string to a boolean by checking for a "yes" answer.

test/core/test_partial_validation_result.py

@@ -0,0 +1,78 @@
+"""Unit tests for PartialValidationResult tri-state semantics."""
+
+import pytest
+
+from mellea.core import PartialValidationResult
+
+
+def test_pass_state():
+    pvr = PartialValidationResult("pass")
+    assert pvr.success == "pass"
+    assert pvr.as_bool() is True
+    assert bool(pvr) is True
+
+
+def test_fail_state():
+    pvr = PartialValidationResult("fail")
+    assert pvr.success == "fail"
+    assert pvr.as_bool() is False
+    assert bool(pvr) is False
+
+
+def test_unknown_state():
+    pvr = PartialValidationResult("unknown")
+    assert pvr.success == "unknown"
+    assert pvr.as_bool() is False
+    assert bool(pvr) is False
+
+
+def test_default_optional_fields_are_none():
+    pvr = PartialValidationResult("unknown")
+    assert pvr.reason is None
+    assert pvr.score is None
+    assert pvr.thunk is None
+    assert pvr.context is None
+
+
+def test_reason_field():
+    pvr = PartialValidationResult("fail", reason="Too short")
+    assert pvr.reason == "Too short"
+
+
+def test_score_field():
+    pvr = PartialValidationResult("pass", score=0.95)
+    assert pvr.score == 0.95
+
+
+@pytest.mark.parametrize(
+    ("state", "expected"), [("pass", True), ("fail", False), ("unknown", False)]
+)
+def test_as_bool_correctness(state: str, expected: bool) -> None:
+    pvr = PartialValidationResult(state)  # type: ignore[arg-type]
+    assert pvr.as_bool() is expected
+    assert bool(pvr) is expected
+
+
+def test_invalid_success_raises() -> None:
+    with pytest.raises(ValueError, match="success must be"):
+        PartialValidationResult("maybe")  # type: ignore[arg-type]
+
+
+def test_repr_shows_state() -> None:
+    pvr = PartialValidationResult("fail", reason="too short", score=0.1)
+    r = repr(pvr)
+    assert "'fail'" in r
+    assert "too short" in r
+    assert "0.1" in r
+
+
+def test_thunk_field() -> None:
+    sentinel = object()
+    pvr = PartialValidationResult("pass", thunk=sentinel)  # type: ignore[arg-type]
+    assert pvr.thunk is sentinel
+
+
+def test_context_field() -> None:
+    sentinel = object()
+    pvr = PartialValidationResult("pass", context=sentinel)  # type: ignore[arg-type]
+    assert pvr.context is sentinel