confgate 0.1.0__py3-none-any.whl

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/_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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+confgate/__init__.py,sha256=kXiJVx_TQz26BsZg7ITBYiCI4hQs18-nKF4cWRBuN2w,294
+confgate/_core.py,sha256=AOyCQE1s0p2WOgIb8hd89lQGgA9U5CReIx4XDly86wY,1929
+confgate/_exceptions.py,sha256=Cs723XMHa5Q2I0zG604PRZlfyZRbnTYAiYooIAQksas,237
+confgate/_gate.py,sha256=NNiD0flQ345jjVWMbIk35RPvm-h0YUPnPmANxTabFWs,1580
+confgate-0.1.0.dist-info/licenses/LICENSE,sha256=iDLjLh3XbHcjbWPHeOPPmaLOoR9cYTKzAvba2mMm3xg,1068
+confgate-0.1.0.dist-info/METADATA,sha256=hREsMW2_PLzxSmWE4e3aD5IkW25qSutrIEqytZdv-7M,1244
+confgate-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+confgate-0.1.0.dist-info/top_level.txt,sha256=NAVONwK2CvnM_UmVPKQlT3BPuKBBhzy11vNMtoiVpRM,9
+confgate-0.1.0.dist-info/RECORD,,

confgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

confgate-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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