confgate 0.1.0__tar.gz

confgate-0.1.0/LICENSE

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

confgate-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: confgate
+Version: 0.1.0
+Summary: Confidence-gated decisions for LLM agent outputs
+Author:  Sri Harsha
+License: MIT
+Keywords: agents,llm,confidence,ai,agentic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# confgate
+
+Confidence-gated decisions for LLM agent outputs.
+
+> Prevent false-positive fatigue by abstaining from low-confidence findings.
+
+## Installation
+
+```bash
+pip install confgate
+```
+
+## Quick start
+
+```python
+from confgate import Decision, gate
+
+@gate(threshold=0.75)
+def security_agent(diff: str) -> Decision:
+    # your LLM call here
+    return Decision(
+        category="security",
+        confidence=0.9,
+        reasoning="Potential SQL injection in query builder.",
+        severity="high",
+        line_ref="src/db.py:42",
+    )
+
+result = security_agent(diff)
+if not result.abstained:
+    print(result)
+```
+
+## License
+
+MIT

confgate-0.1.0/README.md

@@ -0,0 +1,36 @@
+# confgate
+
+Confidence-gated decisions for LLM agent outputs.
+
+> Prevent false-positive fatigue by abstaining from low-confidence findings.
+
+## Installation
+
+```bash
+pip install confgate
+```
+
+## Quick start
+
+```python
+from confgate import Decision, gate
+
+@gate(threshold=0.75)
+def security_agent(diff: str) -> Decision:
+    # your LLM call here
+    return Decision(
+        category="security",
+        confidence=0.9,
+        reasoning="Potential SQL injection in query builder.",
+        severity="high",
+        line_ref="src/db.py:42",
+    )
+
+result = security_agent(diff)
+if not result.abstained:
+    print(result)
+```
+
+## License
+
+MIT

confgate-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "confgate"
+version = "0.1.0"
+description = "Confidence-gated decisions for LLM agent outputs"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = " Sri Harsha" }]
+keywords = ["agents", "llm", "confidence", "ai", "agentic"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

confgate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

confgate-0.1.0/src/confgate/__init__.py

@@ -0,0 +1,8 @@
+"""confgate — confidence-gated decisions for LLM agent outputs."""
+
+from confgate._core import Decision
+from confgate._exceptions import GateError, InvalidDecisionError
+from confgate._gate import gate
+
+__version__ = "0.1.0"
+__all__ = ["Decision", "gate", "GateError", "InvalidDecisionError"]

confgate-0.1.0/src/confgate/_core.py

@@ -0,0 +1,55 @@
+"""Decision dataclass — the core data structure for confgate."""
+
+from dataclasses import dataclass, field
+
+_VALID_SEVERITIES = {"low", "medium", "high", "critical"}
+
+
+@dataclass
+class Decision:
+    """A structured finding produced by an LLM agent.
+
+    Attributes:
+        category:   Type of finding, e.g. 'security' or 'style'.
+        confidence: Agent's self-reported confidence, 0.0–1.0.
+        reasoning:  One-sentence explanation shown to end users.
+        severity:   Impact level — 'low', 'medium', 'high', or 'critical'.
+        line_ref:   Optional code location, e.g. 'src/auth.py:42'.
+        abstained:  Set True by @gate when confidence < threshold.
+    """
+
+    category: str
+    confidence: float
+    reasoning: str
+    severity: str = "medium"
+    line_ref: str | None = None
+    abstained: bool = False
+
+    def __post_init__(self) -> None:
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(
+                f"confidence must be between 0.0 and 1.0, got {self.confidence}"
+            )
+        if self.severity not in _VALID_SEVERITIES:
+            raise ValueError(
+                f"severity must be one of {sorted(_VALID_SEVERITIES)}, got {self.severity!r}"
+            )
+
+    def to_dict(self) -> dict:
+        """Return a plain dict suitable for JSON serialisation."""
+        return {
+            "category": self.category,
+            "confidence": self.confidence,
+            "reasoning": self.reasoning,
+            "severity": self.severity,
+            "line_ref": self.line_ref,
+            "abstained": self.abstained,
+        }
+
+    def __str__(self) -> str:
+        abstained_tag = " [ABSTAINED]" if self.abstained else ""
+        loc = f" @ {self.line_ref}" if self.line_ref else ""
+        return (
+            f"[{self.severity.upper()}]{abstained_tag} {self.category}{loc}"
+            f" (confidence={self.confidence:.2f}): {self.reasoning}"
+        )

confgate-0.1.0/src/confgate/_exceptions.py

@@ -0,0 +1,9 @@
+"""Exceptions raised by confgate."""
+
+
+class GateError(Exception):
+    """Base exception for all confgate errors."""
+
+
+class InvalidDecisionError(GateError):
+    """Raised when a @gate-decorated function returns a non-Decision value."""

confgate-0.1.0/src/confgate/_gate.py

@@ -0,0 +1,46 @@
+"""@gate decorator — confidence-gates a function that returns a Decision."""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import TypeVar
+
+from confgate._core import Decision
+from confgate._exceptions import InvalidDecisionError
+
+F = TypeVar("F", bound=Callable[..., Decision])
+
+
+def gate(threshold: float = 0.8) -> Callable[[F], F]:
+    """Decorator factory that abstains low-confidence decisions.
+
+    Args:
+        threshold: Minimum confidence required to pass. Decisions with
+                   confidence strictly below this value have abstained=True.
+                   Must be between 0.0 and 1.0 inclusive.
+
+    Raises:
+        ValueError: At decoration time if threshold is outside [0.0, 1.0].
+        InvalidDecisionError: At call time if the wrapped function does not
+                              return a Decision instance.
+    """
+    if not (0.0 <= threshold <= 1.0):
+        raise ValueError(
+            f"gate threshold must be between 0.0 and 1.0, got {threshold}"
+        )
+
+    def decorator(fn: F) -> F:
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            result = fn(*args, **kwargs)
+            if not isinstance(result, Decision):
+                raise InvalidDecisionError(
+                    f"{fn.__name__} must return a Decision instance, "
+                    f"got {type(result).__name__}"
+                )
+            if result.confidence < threshold:
+                result.abstained = True
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

confgate-0.1.0/src/confgate.egg-info/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: confgate
+Version: 0.1.0
+Summary: Confidence-gated decisions for LLM agent outputs
+Author:  Sri Harsha
+License: MIT
+Keywords: agents,llm,confidence,ai,agentic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# confgate
+
+Confidence-gated decisions for LLM agent outputs.
+
+> Prevent false-positive fatigue by abstaining from low-confidence findings.
+
+## Installation
+
+```bash
+pip install confgate
+```
+
+## Quick start
+
+```python
+from confgate import Decision, gate
+
+@gate(threshold=0.75)
+def security_agent(diff: str) -> Decision:
+    # your LLM call here
+    return Decision(
+        category="security",
+        confidence=0.9,
+        reasoning="Potential SQL injection in query builder.",
+        severity="high",
+        line_ref="src/db.py:42",
+    )
+
+result = security_agent(diff)
+if not result.abstained:
+    print(result)
+```
+
+## License
+
+MIT

confgate-0.1.0/src/confgate.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/confgate/__init__.py
+src/confgate/_core.py
+src/confgate/_exceptions.py
+src/confgate/_gate.py
+src/confgate.egg-info/PKG-INFO
+src/confgate.egg-info/SOURCES.txt
+src/confgate.egg-info/dependency_links.txt
+src/confgate.egg-info/requires.txt
+src/confgate.egg-info/top_level.txt
+tests/test_decision.py
+tests/test_gate.py

confgate-0.1.0/src/confgate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

confgate-0.1.0/src/confgate.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest
+pytest-cov

confgate-0.1.0/src/confgate.egg-info/top_level.txt

@@ -0,0 +1 @@
+confgate

confgate-0.1.0/tests/test_decision.py

@@ -0,0 +1,122 @@
+"""Tests for the Decision dataclass."""
+
+import pytest
+
+from confgate import Decision
+
+
+def make_decision(**overrides) -> Decision:
+    defaults = dict(
+        category="security",
+        confidence=0.9,
+        reasoning="SQL injection risk in query builder.",
+    )
+    return Decision(**{**defaults, **overrides})
+
+
+class TestDecisionDefaults:
+    def test_valid_creation_with_defaults(self):
+        d = make_decision()
+        assert d.category == "security"
+        assert d.confidence == 0.9
+        assert d.reasoning == "SQL injection risk in query builder."
+        assert d.severity == "medium"
+        assert d.line_ref is None
+        assert d.abstained is False
+
+    def test_all_fields_set_explicitly(self):
+        d = Decision(
+            category="style",
+            confidence=0.6,
+            reasoning="Missing type hint.",
+            severity="low",
+            line_ref="src/auth.py:42",
+            abstained=False,
+        )
+        assert d.line_ref == "src/auth.py:42"
+        assert d.severity == "low"
+
+
+class TestDecisionValidation:
+    def test_confidence_above_one_raises(self):
+        with pytest.raises(ValueError, match="confidence"):
+            make_decision(confidence=1.1)
+
+    def test_confidence_below_zero_raises(self):
+        with pytest.raises(ValueError, match="confidence"):
+            make_decision(confidence=-0.01)
+
+    def test_confidence_exactly_zero_is_valid(self):
+        d = make_decision(confidence=0.0)
+        assert d.confidence == 0.0
+
+    def test_confidence_exactly_one_is_valid(self):
+        d = make_decision(confidence=1.0)
+        assert d.confidence == 1.0
+
+    def test_invalid_severity_raises(self):
+        with pytest.raises(ValueError, match="severity"):
+            make_decision(severity="fatal")
+
+    @pytest.mark.parametrize("sev", ["low", "medium", "high", "critical"])
+    def test_all_valid_severities(self, sev):
+        d = make_decision(severity=sev)
+        assert d.severity == sev
+
+
+class TestDecisionToDict:
+    def test_to_dict_keys(self):
+        d = make_decision()
+        result = d.to_dict()
+        assert set(result.keys()) == {
+            "category", "confidence", "reasoning", "severity", "line_ref", "abstained"
+        }
+
+    def test_to_dict_values(self):
+        d = Decision(
+            category="security",
+            confidence=0.85,
+            reasoning="Hardcoded secret.",
+            severity="high",
+            line_ref="config.py:10",
+            abstained=False,
+        )
+        assert d.to_dict() == {
+            "category": "security",
+            "confidence": 0.85,
+            "reasoning": "Hardcoded secret.",
+            "severity": "high",
+            "line_ref": "config.py:10",
+            "abstained": False,
+        }
+
+    def test_to_dict_line_ref_none(self):
+        d = make_decision()
+        assert d.to_dict()["line_ref"] is None
+
+    def test_to_dict_reflects_abstained_state(self):
+        d = make_decision()
+        d.abstained = True
+        assert d.to_dict()["abstained"] is True
+
+
+class TestDecisionStr:
+    def test_str_not_abstained(self):
+        d = make_decision(severity="high", confidence=0.9)
+        s = str(d)
+        assert "[HIGH]" in s
+        assert "0.90" in s
+        assert "ABSTAINED" not in s
+
+    def test_str_abstained(self):
+        d = make_decision()
+        d.abstained = True
+        assert "ABSTAINED" in str(d)
+
+    def test_str_includes_line_ref(self):
+        d = make_decision(line_ref="src/auth.py:42")
+        assert "src/auth.py:42" in str(d)
+
+    def test_str_no_line_ref_omits_at(self):
+        d = make_decision(line_ref=None)
+        assert " @ " not in str(d)

confgate-0.1.0/tests/test_gate.py

@@ -0,0 +1,160 @@
+"""Tests for the @gate decorator."""
+
+import pytest
+
+from confgate import Decision, InvalidDecisionError, gate
+
+
+def _decision(confidence: float, **kwargs) -> Decision:
+    return Decision(
+        category="security",
+        confidence=confidence,
+        reasoning="Test finding.",
+        **kwargs,
+    )
+
+
+class TestGateThreshold:
+    def test_above_threshold_not_abstained(self):
+        @gate(threshold=0.75)
+        def agent() -> Decision:
+            return _decision(0.9)
+
+        result = agent()
+        assert result.abstained is False
+
+    def test_below_threshold_abstained(self):
+        @gate(threshold=0.75)
+        def agent() -> Decision:
+            return _decision(0.5)
+
+        result = agent()
+        assert result.abstained is True
+
+    def test_exactly_at_threshold_not_abstained(self):
+        """Equal to threshold must pass — strictly less-than triggers abstain."""
+        @gate(threshold=0.75)
+        def agent() -> Decision:
+            return _decision(0.75)
+
+        result = agent()
+        assert result.abstained is False
+
+    def test_just_below_threshold_abstained(self):
+        @gate(threshold=0.75)
+        def agent() -> Decision:
+            return _decision(0.7499)
+
+        result = agent()
+        assert result.abstained is True
+
+    def test_default_threshold_is_0_8(self):
+        @gate()
+        def agent() -> Decision:
+            return _decision(0.79)
+
+        result = agent()
+        assert result.abstained is True
+
+    def test_default_threshold_passes_0_8(self):
+        @gate()
+        def agent() -> Decision:
+            return _decision(0.8)
+
+        result = agent()
+        assert result.abstained is False
+
+
+class TestGateMetadataPreservation:
+    def test_preserves_name(self):
+        @gate(threshold=0.5)
+        def my_agent() -> Decision:
+            """Agent docstring."""
+            return _decision(0.9)
+
+        assert my_agent.__name__ == "my_agent"
+
+    def test_preserves_doc(self):
+        @gate(threshold=0.5)
+        def my_agent() -> Decision:
+            """Agent docstring."""
+            return _decision(0.9)
+
+        assert my_agent.__doc__ == "Agent docstring."
+
+    def test_preserves_annotations(self):
+        @gate(threshold=0.5)
+        def my_agent(diff: str) -> Decision:
+            return _decision(0.9)
+
+        assert my_agent.__annotations__["diff"] is str
+
+
+class TestGateReturnTypeEnforcement:
+    def test_non_decision_return_raises(self):
+        @gate(threshold=0.5)
+        def bad_agent():
+            return {"confidence": 0.9}
+
+        with pytest.raises(InvalidDecisionError):
+            bad_agent()
+
+    def test_none_return_raises(self):
+        @gate(threshold=0.5)
+        def bad_agent():
+            return None
+
+        with pytest.raises(InvalidDecisionError):
+            bad_agent()
+
+    def test_string_return_raises(self):
+        @gate(threshold=0.5)
+        def bad_agent():
+            return "finding"
+
+        with pytest.raises(InvalidDecisionError):
+            bad_agent()
+
+
+class TestGateThresholdValidation:
+    def test_threshold_above_one_raises_at_decoration(self):
+        with pytest.raises(ValueError, match="threshold"):
+            @gate(threshold=1.1)
+            def agent():
+                pass
+
+    def test_threshold_below_zero_raises_at_decoration(self):
+        with pytest.raises(ValueError, match="threshold"):
+            @gate(threshold=-0.1)
+            def agent():
+                pass
+
+    def test_threshold_exactly_zero_is_valid(self):
+        @gate(threshold=0.0)
+        def agent() -> Decision:
+            return _decision(0.0)
+
+        result = agent()
+        assert result.abstained is False
+
+    def test_threshold_exactly_one_is_valid(self):
+        @gate(threshold=1.0)
+        def agent() -> Decision:
+            return _decision(0.99)
+
+        result = agent()
+        assert result.abstained is True
+
+
+class TestGatePassesArguments:
+    def test_wrapped_function_receives_args(self):
+        received = {}
+
+        @gate(threshold=0.5)
+        def agent(diff: str, extra: int = 0) -> Decision:
+            received["diff"] = diff
+            received["extra"] = extra
+            return _decision(0.9)
+
+        agent("some diff", extra=7)
+        assert received == {"diff": "some diff", "extra": 7}